diff --git a/.github/scripts/vsixPolicy.mjs b/.github/scripts/vsixPolicy.mjs
index bfe9b1ff..5564194e 100644
--- a/.github/scripts/vsixPolicy.mjs
+++ b/.github/scripts/vsixPolicy.mjs
@@ -18,6 +18,10 @@ const FORBIDDEN_ENTRY_PATTERNS = [
   /^extension\/node_modules(?:\/|$)/i,
   /^extension\/issue87-.*\.cjs$/i,
   /^extension\/out\/claudeIncrementalPrototype\.js$/i,
+  /^extension\/out\/adviceEffectiveness\/(?:evidencePreparation|feedback|legacyBridge|legacyPersonalization|modelExperiment)\.js$/i,
+  /^extension\/out\/(?:adviceDemoSample|adviceSummary)\.js$/i,
+  /^extension\/(?:AI-ADVICE-.*V2\.3\.1|V2\.3\.1-CANDIDATE-CONTRACT(?:\.zh-CN)?)\.md$/i,
+  /^extension\/CLAUDE-COLD-AB-V2\.3\.1(?:\.zh-CN)?\.md$/i,
   /(?:^|\/)\.env(?:\.|$)/i,
   /\.(?:pem|key|p12|pfx)$/i,
 ];
diff --git a/.github/scripts/vsixPolicy.test.mjs b/.github/scripts/vsixPolicy.test.mjs
index 8b95bf91..0fbc97b9 100644
--- a/.github/scripts/vsixPolicy.test.mjs
+++ b/.github/scripts/vsixPolicy.test.mjs
@@ -73,6 +73,26 @@ test('VSIX policy rejects internal Superpowers review material', () => {
   );
 });
 
+test('VSIX policy rejects dormant v2.3.1 preparation seams and review documents', () => {
+  for (const entry of [
+    'extension/out/adviceEffectiveness/evidencePreparation.js',
+    'extension/out/adviceEffectiveness/feedback.js',
+    'extension/out/adviceEffectiveness/legacyBridge.js',
+    'extension/out/adviceEffectiveness/legacyPersonalization.js',
+    'extension/out/adviceEffectiveness/modelExperiment.js',
+    'extension/out/adviceDemoSample.js',
+    'extension/out/adviceSummary.js',
+    'extension/AI-ADVICE-INTEGRATION-V2.3.1.md',
+    'extension/V2.3.1-CANDIDATE-CONTRACT.zh-CN.md',
+  ]) {
+    assert.throws(
+      () => assertSafeVsixEntries([...minimalEntries, entry]),
+      /forbidden VSIX entry/,
+      entry,
+    );
+  }
+});
+
 test('VSIX policy rejects unsafe or non-canonical archive paths', () => {
   for (const entry of [
     '/extension/out/extra.js',
diff --git a/.vscodeignore b/.vscodeignore
index ec2a3674..ce7fa89c 100644
--- a/.vscodeignore
+++ b/.vscodeignore
@@ -20,6 +20,16 @@ CONTRIBUTING.md
 probe-*.mjs
 issue87-*.cjs
 out/claudeIncrementalPrototype.js
+out/adviceEffectiveness/evidencePreparation.js
+out/adviceEffectiveness/feedback.js
+out/adviceEffectiveness/legacyBridge.js
+out/adviceEffectiveness/legacyPersonalization.js
+out/adviceEffectiveness/modelExperiment.js
+out/adviceDemoSample.js
+out/adviceSummary.js
+AI-ADVICE-*V2.3.1*.md
+CLAUDE-COLD-AB-V2.3.1*.md
+V2.3.1-CANDIDATE-CONTRACT*.md
 docs/**
 
 .gitignore
diff --git a/AGENTS.md b/AGENTS.md
index eab08c5f..3ed71d86 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -213,3 +213,6 @@ Co-authored-by: OpenAI Codex <215057067+openai-codex[bot]@users.noreply.github.c
 ```
 - Keep controlled comment-only first-pass automation separate from the
   privileged maintainer-only mention workflow.
+
+## Codex 工具適配
+瀏覽器操作使用當前 Codex browser／computer-use 工具；原文的 Claude MCP 工具名稱只描述操作意圖，不能直接呼叫。提問依目前模式使用可用工具；Git 操作仍需當次明確授權。
diff --git a/AGENTS.zh-CN.md b/AGENTS.zh-CN.md
index 524e0cab..86e2e667 100644
--- a/AGENTS.zh-CN.md
+++ b/AGENTS.zh-CN.md
@@ -177,3 +177,9 @@ Co-authored-by: OpenAI Codex <215057067+openai-codex[bot]@users.noreply.github.c
 ```
 - comment-only 的受控 first-pass automation 与 maintainer-only 的高权限 mention
   workflow 必须保持分离。
+
+## Codex 工具适配
+
+浏览器操作使用当前可用的 Codex browser／computer-use 工具；原文中的 Claude MCP
+工具名称只描述操作意图，不能直接调用。提问按当前模式使用可用工具；Git 操作仍须
+获得当次明确授权。
diff --git a/ARCHITECTURE-zh-CN.md b/ARCHITECTURE-zh-CN.md
index d293b4e6..cca2e1c4 100644
--- a/ARCHITECTURE-zh-CN.md
+++ b/ARCHITECTURE-zh-CN.md
@@ -3,11 +3,16 @@
 > 本文简要说明扩展的 provider 边界、数据流与用量语义。模块职责或
 > provider 行为变化时必须同步更新。英文版见
 > [`ARCHITECTURE.md`](ARCHITECTURE.md)。
+> 持久数据清单、保留、迁移、清除和网络边界的规范来源是双语
+> [`v2.3.1 本地数据契约`](docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md)。
 
 ## 产品边界
 
 **Claude Code Usage** 继续保持 local-first、无 runtime dependency 和 read-mostly。
 v2.3.0 保留完整 Claude 体验，并增加 provider-specific 的 Codex Beta 用量与优化视图。
+v2.3.1 候选在不改变 provider 计量口径的前提下，增加一套默认关闭、
+local-first 的建议有效性闭环、唯一的显式 BYOK 请求边界、可持久的历史任务状态、
+Codex 有界的本地每周重置观测历史，以及滚动 30 天的日期→小时投影。
 
 - Claude：精确的本地 token bucket、模型成本估算和 Anthropic OAuth 5 小时/每周配额。
 - Codex Beta：本地 processed/fresh/cache/output/reasoning 指标、模型与 effort 拆分、
@@ -25,19 +30,25 @@ Opt-in GitHub 认证和跨设备聚合同步延后到 v2.4.x，届时单独做
 | `extension.ts` | 激活、命令、设置、provider 生命周期、刷新编排、watcher、状态栏/webview 接线和匿名诊断。 |
 | `dataLoader.ts` | 为精确兼容保留的 Claude 解析、校验、归因和内容分析 primitive。 |
 | `claudeIncrementalIndex.ts` | 生产环境 Claude 内存 per-file 索引：append-tail 解析、精确跨文件 response 去重、受影响 group 聚合、内容分析 contribution 和已物化 dashboard row。 |
+| `adviceEffectiveness/contract.ts`、`adapters.ts`、`payload.ts` | 严格的观察/证据/建议/行动/结果契约，隐私重建型 provider adapter，以及 canonical 聚合/个性化 payload。 |
+| `adviceEffectiveness/preparedRequest.ts` / `remoteAdvice.ts` | host 持有的唯一完整 HTTP Prepared 对象、精确 preview/send bytes、BYOK-only 授权、取消与严格结构化解析。 |
+| `adviceEffectiveness/comparisonPairing.ts`、`comparisonResult.ts`、`versionedPersistence.ts` | 净化的可比任务配对、冻结的 measurement-version envelope 与有界的本地反馈/比较存储。 |
+| `optimizerRequest.ts` | 仅用户粘贴草稿通过同一 Prepared 与严格发送边界；不回退到 advice 证据 parser。 |
+| `backgroundWorkState.ts` / `resourceOwnership.ts` | 可持久的 progress/backoff/pause 状态，以及供测试核对 timer、watcher、worker、network 和 backfill 创建者/停止/真实销毁的 registry。 |
 | `providers/providerTypes.ts` | Provider-neutral token、event、confidence、outcome、coverage 和 limit contract。 |
 | `providers/claudeProvider.ts` | 薄兼容 adapter，不改变既有 Claude 聚合结果。 |
 | `providers/codex/codexSchema.ts` | 最小安全 JSON guard，不展开或返回 message/command/tool body。 |
 | `providers/codex/codexParser.ts` | Codex 精确单次请求解析及 cumulative high-water 回退、伪名 lineage metadata、结构计数、quality flag 和 last-observed limit。 |
 | `providers/codex/codexManifest.ts` | Codex 允许目录发现、HMAC file key、fingerprint 和 manifest diff。 |
-| `providers/codex/codexIndex.ts` | schema-3 的 per-file 数字聚合与重放证据持久化、有界 cold/tail parse、独立 aggregate/period/current-day coverage 和原子存取。 |
+| `providers/codex/codexIndex.ts` | schema-3 的 per-file 数字聚合与重放证据持久化、有界 cold/tail parse、独立 aggregate/period/滚动 30 天小时 coverage 和原子存取。 |
+| `providers/codex/codexQuotaHistory.ts` | 小型、账户中性的每周重置观测缓存；压缩重复本地样本，不保留凭据、账户名或原始标签。 |
 | `providers/codex/codexIndexWorker.ts` / `codexIndexClient.ts` | 后台协调器、recent-first progress、cancel、resume、checkpoint 持久化和 single-flight client。 |
 | `providers/codex/codexFilePassPool.ts` / `codexFilePassWorker.ts` | 未完成回填期间，用于独立 main、lineage、period、current-day 和 identity per-file pass 的自适应受限本地 pool。 |
 | `providers/codex/codexProvider.ts` | 面向 extension 的 Codex snapshot facade 与 partial/unavailable/error outcome。 |
 | `providers/codex/codexUsage.ts` | Codex 自然日 Today/小时、7 天、30 天、月度、task 与项目 view model 聚合，以及精确模型 API 等效成本。 |
 | `providers/codex/codexInsights.ts` | 确定性的结构用量建议，不读 prompt/body。 |
 | `codexView.ts` / `codexViewComponents.ts` | Codex 本地化文案与默认 provider contract；不负责 HTML renderer、client script 或 CSS。 |
-| `settings.ts` | 权威 `SETTINGS` catalog 和 `SettingsStore`；不得散落直接读取。 |
+| `settings.ts` | 权威 `SETTINGS` catalog 和 `SettingsStore`；普通值进入 configuration/globalState，BYOK 凭证只进入 SecretStorage，且绝不进入 Webview snapshot。不得散落直接读取。 |
 | `statusBar.ts` / `codexStatus.ts` | Provider-specific 状态展示和通用 Claude 配额格式化。 |
 | `webview.ts` | Claude/Codex 唯一一套 provider-aware dashboard shell、共享 render function、共享 client 行为、provider tab 与 Compare 展示。 |
 | `i18n.ts` | 八个 UI locale 的全部用户可见文案。 |
@@ -60,13 +71,20 @@ Claude JSONL
   ──> manifest metadata
   ──> background worker
   ──> schema guard + 精确单次请求 parser（lineage high-water 回退）
-  ──> per-file 数字聚合索引 + 定向的当日小时 sidecar
+  ──> per-file 数字聚合索引 + 有界账户中性的每周重置历史
+  ──> 滚动稀疏 30 天小时 sidecar
   ──> CodexProviderSnapshot
   ──> Codex scope + insight
   ──> Codex 状态栏 + provider-aware dashboard render input
 
 Claude aggregate + Codex scope ──> 同一套 `webview.ts` dashboard render stack
 Claude aggregate + Codex scope ──> 并列 Compare（不跨 provider 求和）
+
+已物化 provider snapshot
+  ──> 隐私重建型 advice adapter
+  ──> 本地证据 + 确定性建议
+  ──> 可选 host-owned Prepared 请求 ──> 预览 ──> 显式 BYOK 发送
+  ──> 本地反馈 ──> 净化可比 pair ──> 冻结 comparison envelope
 ```
 
 任一 provider unavailable 或 partial 时，不清空另一 provider 最近验证的 snapshot。
@@ -79,7 +97,8 @@ provider 都已有真实数据时才显示「对比」。worker 启动前先装
 选中 Codex 时才重绘 Webview；refresh 返回后仍会用已验证 snapshot 做最后一次渲染。
 
 Codex 的「今天」指配置时区中的当前自然日，而不是最近任务。汇总来自该日已验证的 period slice；
-精确小时行来自下文所述的独立当日 sidecar。小时、每日与每月主图默认使用 API 等效成本，Token 构成图
+精确小时行与 30 天日期下钻来自下文的独立滚动 sidecar。点击已渲染日期只展开这份投影，
+不要求 host 读取 JSONL。小时、每日与每月主图默认使用 API 等效成本，Token 构成图
 仍独立展示。未知模型计入 Token 分母但保持未定价，因此定价 coverage 始终可见。Claude 与 Codex 的
 时间序列布局使用对齐的响应式宽度，较密集的图表和表格在各自可键盘聚焦的区域内滚动。
 
@@ -106,7 +125,10 @@ output 与 reasoning component 是精确的单次请求归因。`last_token_usag
 parent baseline，因此该路径按 component 与 lineage 维护 high-water。Unknown parent、counter
 regression 和 schema drift 产生 quality flag，不生成负用量或伪造精度。
 
-本地日志中的 Codex `rate_limits.primary` 只是 last-observed snapshot，到 reset 时间后隐藏。
+本地日志中的 Codex `rate_limits` 只是 last-observed snapshot，到 reset 时间后隐藏。
+v2.3.1 候选还会保留一份有界、账户中性的 account-wide 每周观测历史：同一重置边界的
+重复样本只保留一个代表，真正不同的重置时刻则分别保留。这份历史用于对齐和复核每周
+估算，不是账户注册表；如果某次重置从未出现在本地日志行里，插件也无法凭空发现它。
 v2.3.0 不读 Codex credential，也不发网络请求刷新它。
 
 ## 隐私与持久化
@@ -118,9 +140,19 @@ Codex 发现仅限：
 - 默认 `$CODEX_HOME`：`~/.codex`
 
 绝不读取 `auth.json`、SQLite、config secret、keychain、浏览器状态或未知文件。
-Raw path/session/parent ID 只留在本地 worker 的短期内存。磁盘只持久化 machine-salted 伪名 key
-和按 day/model/effort/session 聚合的数字，绝不存 prompt、response、command、tool arguments、
-raw line 或 raw path。
+Raw path/session/parent ID 只留在本地 worker 的短期内存。磁盘只持久化 machine-salted 伪名 key、
+按 day/model/effort/session 聚合的数字，以及上面所述的有界账户中性额度历史；绝不存 prompt、
+response、command、tool arguments、raw line、raw path、账户名、凭据或原始 provider label。
+
+Advice 只消费已物化聚合，不重读 JSONL，也不重遍历保留的 records。远程默认为
+aggregate-only；prompt sample 与可选 user context 需单独明确同意，并必须原样出现在精确请求预览中。
+host 保管 Prepared 对象和 API key；webview 只拿到预览与不透明 handle。第二次点击才把同一 bytes 对象
+发给用户配置的 BYOK endpoint。Feedback、comparable pair 与 comparison envelope 全部保持本地，
+不接受 prompt、response、path、session、title、endpoint 或 credential 字段。
+
+Advice 同意变更会立即作废 Prepared handle。host 的 pending-write 计数器在全部排队同意
+写入结束前阻止新预览与发送；持久化失败保持关闭。聚合或提示授权撤回还会通过既有 network
+owner 取消在途建议请求，与仅含用户草稿的 Optimizer 请求隔离。取消不能追回已传出的字节。
 
 Machine salt 存在 VS Code `globalState`，不写入索引。Worker progress/result/error 与 diagnostics
 只含匿名计数与时间，不含 path 或 ID。
@@ -150,10 +182,10 @@ aggregate；按日的期间切片则独立晋升，因此 partial migration 不
 all-time 的状态。7 天与 30 天只累加自然日内发生的 event；不会因为 Session 的最后活动落在范围内，
 就把该 Session 的整段较早历史吸收进来。
 
-当日小时索引是 schema 3 的增量 sidecar，不是第三份 all-time 事实来源。只有经重复分类选为 canonical，
-且已验证 period slice 已包含 `asOfDay` 的文件才会进入候选集。每个文件的小时晋升状态与处理中 cursor
-都会写入 checkpoint，因此取消后可从已验证 offset 续传。日期或时区变化时会丢弃过期 sidecar，改为
-目标新自然日；该路径既不使主 aggregate 失效，也不会触发全历史重建。
+滚动 30 天小时索引是 schema 3 的增量 sidecar，不是第三份 all-time 事实来源。只有经重复分类选为
+canonical，且已验证 period slice 与配置自然日窗口相交的文件才会进入候选集。每个文件的小时晋升状态与
+处理中 cursor 都会写入 checkpoint，因此取消后可从已验证 offset 续传。窗口前移时淘汰第 31 天；
+时区改变只请求一次定向迁移。该路径既不使主 aggregate 失效，也不会触发无关的全历史重建。
 
 Identity 同样是一份 coverage 契约。Git 的 SCP 形式 SSH URL 与 HTTPS URL 在 host/path 一致时
 会规范化为同一个 repository identity。Root title 采用可信的最新 `updated_at` title；subagent
@@ -192,17 +224,31 @@ Codex 按多 GiB 本地历史设计：
   数十 MB snapshot 主导高速回填耗时；
 - 只有可能改变 lineage 的阶段才重新 reconcile；period 和稳定阶段复用已验证关系，
   不再反复扫描完整索引；
-- 当日小时任务仅处理 period slice 已证明包含 `asOfDay` 的 canonical 文件；它独立 checkpoint/续传，
-  不会重置主索引；
+- 滚动 30 天小时任务仅处理 period slice 已证明与配置自然日窗口相交的 canonical 文件；
+  它独立 checkpoint/续传，滚动淘汰第 31 天，不会重置主索引；
 - append refresh 只读新 tail；未完成行只留在 scanner 的短期内存，从 safe cursor 重试，绝不写入 v3；
 - truncate/replacement 只重解析受影响文件；
 - cancel checkpoint 会原子保存 per-file contribution 与 migration progress，下一轮从已验证 cursor resume；
 - 并发 refresh 共享同一 worker run。
 
-每周 API 等效价值历史只从已经聚合的 Token 用量生成。有真实每周重置观测时，七天窗口按该重置
-对齐；没有时，仅已用历史按 UTC 周一至周一的自然周分组。Token 日志能够证明已用价值，但不能证明
-历史订阅总额度，因此总额度与未用额度仅在存在真实额度用量比例观测时生成。Codex 的仅已用历史可能
-合并同一 home 中的多个登录，而额度推算行仍绑定其实际观测的重置序列。
+额度历史由同一批 JSONL 解析流程顺便填充。旧的完整索引最多接受一次基于已保存
+last-observed limit 的 metadata-only 播种；不会增加第二套额度扫描器、timer、网络轮询或凭据读取。
+播种完成后，未变化的 warm refresh 仍然读取 0 字节用量正文。
+
+历史任务还使用一份精简的可持久控制状态：measurement version、reason、progress、
+failure streak、next eligible time 和 pause reason。成功后立即继续，不人为等待；失败或无进展后
+进入 backoff，普通 refresh/watch/focus 事件不能重启同一停滞迁移。Resource registry 记录每个 timer、
+watcher、worker、network request 与 backfill 的创建者，只在真实 stop callback 完成后释放 lease。
+为降低首次可用延迟，有界的首次索引可在失焦后继续；但 extension dispose、provider 关闭或显式取消
+仍对其终止负责。
+
+每周 API 等效价值历史只从已经聚合的 Token 用量生成。最新有效的重置观测用于锚定互不重叠的七天
+展示窗口；没有观测时，仅已用历史按 UTC 周一至周一的自然周分组。真实的额度用量比例观测可以支持
+历史窗口的总额度近似，而不只支持当前窗口。Codex 的 account-wide `codex` series 会纳入同一 home
+中所有符合条件的本地文件，因为文件键不是账号身份。重置时间如果偏离七天网格，则按观测时间映射到
+对应展示窗口；来源不确定、重置漂移或日切片跨边界时降低可信度并标注为近似。真正不同的 quota
+series 仍仅显示已用值；当前周期不显示未用值，历史周期只有在同时存在总额度近似时才显示未用值。
+每条用量仍只进入一个窗口。
 
 v2.3.0 不推断 20、100 或 200 美元的订阅档位。本地 Codex 日志没有可靠的账号与套餐身份，
 后续比较必须采用用户明确选择的 opt-in 账号映射，不能猜测后绑定价格。
@@ -213,6 +259,7 @@ v2.3.0 不推断 20、100 或 200 美元的订阅档位。本地 Codex 日志没
   和安装 VSIX smoke test。
 - 用户可见字符串覆盖 `en`、`de-DE`、`zh-TW`、`zh-CN`、`ja`、`ko`、`pt-BR`、`id`；
   七份 README 同步。
+- dormant 的 preparation/experiment 模块与仅供评审的 v2.3.1 文档必须保持不可从生产 command graph 到达，并排除出 VSIX。
 - 不手工修改 `package.json` 版本。发布已审阅的 Release Drafter draft 后才创建 tag，
   publish workflow 再从 tag 写入包版本。
 - 通过合并贡献者原 PR，或经授权先修改该 PR 分支再合并，保留贡献归属。
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index baf4852b..164abf04 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -4,12 +4,19 @@
 > semantics. Update it whenever module ownership or provider behavior changes.
 > A faithful Simplified-Chinese companion lives in
 > [`ARCHITECTURE-zh-CN.md`](ARCHITECTURE-zh-CN.md).
+> The normative persistent-data inventory, retention, migration, clearing, and
+> network boundaries live in the bilingual
+> [`v2.3.1 local data contract`](docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md).
 
 ## Product boundary
 
 **Claude Code Usage** remains local-first, dependency-free, and read-mostly.
 v2.3.0 preserves the complete Claude experience and adds Codex Beta as a
 provider-specific usage and optimization view.
+The v2.3.1 candidate adds a default-off, local-first advice-effectiveness loop,
+a single explicit BYOK request boundary, durable historical-work state, a
+bounded local history of Codex weekly reset observations, and a rolling 30-day
+Codex date/hour projection without changing provider accounting.
 
 - Claude: exact local token buckets, model pricing estimates, and Anthropic
   OAuth 5-hour/weekly quota.
@@ -32,19 +39,25 @@ aggregate sync are deferred to v2.4.x after a separate privacy review.
 | `extension.ts` | Activation, commands, settings, provider lifecycle, refresh orchestration, watchers, status/webview wiring, and anonymous diagnostics. |
 | `dataLoader.ts` | Claude parsing, validation, attribution, and content-analysis primitives retained for exact compatibility. |
 | `claudeIncrementalIndex.ts` | Production in-memory per-file Claude index: append-tail parsing, exact cross-file response deduplication, affected-group aggregation, content-analysis contributions, and materialized dashboard rows. |
+| `adviceEffectiveness/contract.ts`, `adapters.ts`, and `payload.ts` | Strict observation/evidence/recommendation/action/result contracts, privacy-rebuilding provider adapters, and canonical aggregate/personalization payloads. |
+| `adviceEffectiveness/preparedRequest.ts` and `remoteAdvice.ts` | One host-owned full HTTP request object, exact preview/send bytes, BYOK-only authorization, cancellation, and strict structured-advice parsing. |
+| `adviceEffectiveness/comparisonPairing.ts`, `comparisonResult.ts`, and `versionedPersistence.ts` | Sanitized comparable-task pairing, frozen measurement-version envelopes, and bounded local feedback/comparison storage. |
+| `optimizerRequest.ts` | User-draft-only projection through the same prepared-request and strict-send boundary; no advice-evidence parser fallback. |
+| `backgroundWorkState.ts` / `resourceOwnership.ts` | Durable progress/backoff/pause state and the testable creator/stop/disposal registry for timers, watchers, workers, network calls, and backfills. |
 | `providers/providerTypes.ts` | Provider-neutral token, event, confidence, outcome, coverage, and limit contracts. |
 | `providers/claudeProvider.ts` | Thin compatibility adapter that exposes existing Claude aggregates without changing their results. |
 | `providers/codex/codexSchema.ts` | Minimal safe JSON guards; never flattens or returns message/command/tool bodies. |
 | `providers/codex/codexParser.ts` | Codex exact-request parsing with cumulative high-water fallback, pseudonymous lineage metadata, structural counters, quality flags, and last-observed limits. |
 | `providers/codex/codexManifest.ts` | Allowlisted Codex directory discovery, HMAC file keys, fingerprints, and manifest diffing. |
-| `providers/codex/codexIndex.ts` | Schema-3 persistent per-file numeric aggregates and replay evidence, bounded cold/tail parsing, independent aggregate/period/current-day coverage, and atomic save/load. |
+| `providers/codex/codexIndex.ts` | Schema-3 persistent per-file numeric aggregates and replay evidence, bounded cold/tail parsing, independent aggregate/period/rolling-30-day-hour coverage, and atomic save/load. |
+| `providers/codex/codexQuotaHistory.ts` | Small account-neutral weekly reset-observation cache; compacts repeated local samples without retaining credentials, account names, or raw labels. |
 | `providers/codex/codexIndexWorker.ts` / `codexIndexClient.ts` | Background coordinator, recent-first progress, cancellation, resume, checkpoint persistence, and single-flight client. |
 | `providers/codex/codexFilePassPool.ts` / `codexFilePassWorker.ts` | Adaptive bounded local pool for independent per-file main, lineage, period, current-day, and identity passes during incomplete backfills. |
 | `providers/codex/codexProvider.ts` | Extension-facing Codex snapshot facade and partial/unavailable/error outcomes. |
 | `providers/codex/codexUsage.ts` | Codex calendar-Today/hourly, 7-day, 30-day, monthly, task, and project view-model aggregation with exact-model API-equivalent cost. |
 | `providers/codex/codexInsights.ts` | Deterministic structural usage guidance; no prompt/body inspection. |
 | `codexView.ts` / `codexViewComponents.ts` | Codex localized-copy and default-provider contracts; no HTML renderer, client script, or CSS ownership. |
-| `settings.ts` | Canonical `SETTINGS` catalog and `SettingsStore`; do not scatter direct reads. |
+| `settings.ts` | Canonical `SETTINGS` catalog and `SettingsStore`; ordinary values use configuration/globalState, while BYOK credentials use SecretStorage and never enter Webview snapshots. Do not scatter direct reads. |
 | `statusBar.ts` / `codexStatus.ts` | Provider-specific status presentation and generic Claude quota formatting. |
 | `webview.ts` | Single provider-aware Claude/Codex dashboard shell, shared render functions, shared client behavior, provider tabs, and Compare presentation. |
 | `i18n.ts` | All user-facing copy for all eight UI locales. |
@@ -68,13 +81,20 @@ allowlisted Codex JSONL
   ──> manifest metadata
   ──> background worker
   ──> schema guard + exact-request parser with lineage high-water fallback
-  ──> per-file numeric aggregate index + targeted current-day hourly sidecar
+  ──> per-file numeric aggregate index + bounded neutral weekly-reset history
+  ──> rolling sparse 30-day hourly sidecar
   ──> CodexProviderSnapshot
   ──> Codex scopes + insights
   ──> Codex status + provider-aware dashboard render inputs
 
 Claude aggregates + Codex scopes ──> one `webview.ts` dashboard render stack
 Claude aggregates + Codex scopes ──> side-by-side Compare (no cross-provider totals)
+
+materialized provider snapshots
+  ──> privacy-rebuilding advice adapters
+  ──> local evidence + deterministic recommendations
+  ──> optional host-owned Prepared request ──> preview ──> explicit BYOK send
+  ──> local feedback ──> sanitized comparable pairs ──> frozen comparison envelope
 ```
 
 One provider may be unavailable or partial without clearing the other
@@ -93,7 +113,9 @@ still gets a final render when the refresh returns.
 
 Codex Today is the current civil day in the configured timezone, not the most
 recent task. Its summary uses that day's verified period slice; exact hourly
-rows come from the independent current-day sidecar described below. Hourly,
+rows and 30-day drill-downs come from the independent rolling sidecar described
+below. Clicking an already-rendered date only reveals that projection and does
+not ask the host to read JSONL. Hourly,
 daily, and monthly primary charts use API-equivalent cost by default, while the
 token-composition chart remains a separate view. Unknown models contribute to
 the token denominator but remain unpriced, so pricing coverage stays visible.
@@ -127,9 +149,14 @@ fallback and may include an inherited parent baseline. That path uses
 per-component, per-lineage high-water marks. Unknown parents, regressions, and
 schema drift produce quality flags rather than negative or fabricated usage.
 
-Codex `rate_limits.primary` found in local logs is a last-observed snapshot only.
-It is hidden once its reset time passes. v2.3.0 does not read Codex credentials
-or make a network call to refresh it.
+Codex `rate_limits` found in local logs is a last-observed snapshot only. It is
+hidden once its reset time passes. The v2.3.1 candidate also keeps a bounded,
+account-neutral history of account-wide weekly observations: repeated samples
+for one reset boundary collapse to one representative, while genuinely
+different reset times remain separate. This history is evidence for aligning
+and auditing weekly estimates; it is not an account registry and cannot reveal
+a reset that never appears in a local log line. v2.3.0 does not read Codex
+credentials or make a network call to refresh it.
 
 ## Privacy and persistence
 
@@ -141,9 +168,25 @@ Codex discovery is restricted to:
 
 It never reads `auth.json`, SQLite databases, config secrets, keychains, browser
 state, or unknown files. Raw paths/session/parent IDs stay in short-lived local
-worker memory. Disk persistence contains machine-salted pseudonymous keys and
-numeric per-day/model/effort/session aggregates only—never prompt, response,
-command, tool-argument, raw-line, or raw-path content.
+worker memory. Disk persistence contains machine-salted pseudonymous keys,
+numeric per-day/model/effort/session aggregates, and the bounded neutral quota
+history described above—never prompt, response, command, tool-argument,
+raw-line, raw-path, account name, credential, or raw provider-label content.
+
+Advice starts from materialized aggregates rather than rereading JSONL or
+walking retained records. Aggregate-only is the remote default. Prompt samples
+and optional user context have a separate explicit consent and must appear in
+the exact request preview. The host keeps the prepared object and API key; the
+webview receives only the preview and an opaque handle. A second click sends the
+same byte object to the configured BYOK endpoint. Feedback, comparable pairs,
+and comparison envelopes remain local and accept no prompt, response, path,
+session, title, endpoint, or credential field.
+
+Advice consent changes invalidate prepared handles immediately. A host-side
+pending-write counter blocks new previews and sends until every queued consent
+write settles; failed persistence stays closed. Aggregate/prompt revocation also
+cancels active advice transports through the existing network owner, separately
+from user-draft Optimizer calls. Cancellation cannot recall transmitted bytes.
 
 The machine salt lives in VS Code `globalState`, not in the index file. Worker
 progress/results/errors and diagnostics contain anonymous counts and timings,
@@ -187,13 +230,14 @@ states. The 7/30-day views sum events in their natural calendar days; they do
 not pull an entire older session into a range merely because the session's last
 activity falls inside it.
 
-The current-day hourly index is an additive schema-3 sidecar, not a third source
-of all-time truth. A file becomes eligible only after duplicate classification
-selects it as canonical and its verified period slice already contains
-`asOfDay`. Per-file hourly promotion and in-progress cursors are checkpointed,
-so cancellation resumes from the verified offset. A day or timezone change
-discards the stale sidecar and targets the new civil day. This path neither
-invalidates the primary aggregate nor triggers a full-history reindex.
+The rolling 30-day hourly index is an additive schema-3 sidecar, not a third
+source of all-time truth. A file becomes eligible only after duplicate
+classification selects it as canonical and its verified period slice intersects
+the configured civil-day window. Per-file hourly promotion and in-progress
+cursors are checkpointed, so cancellation resumes from the verified offset.
+Day 31 is evicted as the window advances. A timezone change requests one
+targeted migration. This path neither invalidates the primary aggregate nor
+triggers an unrelated full-history reindex.
 
 Identity is also a coverage contract. Git SCP-style SSH and HTTPS repository
 URLs are canonicalized to the same repository identity where their host/path
@@ -247,9 +291,10 @@ Codex history is designed for multi-gigabyte local corpora:
 - derived lineage is reconciled only in stages that can change it; period and
   stable stages reuse the verified relationship instead of repeatedly scanning
   the complete index;
-- current-day hourly work is limited to canonical files already known from
-  period slices to contain `asOfDay`; its own checkpoints resume independently
-  and do not reset the primary index;
+- rolling 30-day hourly work is limited to canonical files already known from
+  period slices to intersect the configured civil-day window; its own
+  checkpoints resume independently, evicts day 31, and does not reset the
+  primary index;
 - append refresh reads only the new tail; an incomplete line stays only in the
   scanner's short-lived memory and is retried from the safe cursor, never in v3;
 - truncation/replacement reparses only the affected file;
@@ -257,13 +302,34 @@ Codex history is designed for multi-gigabyte local corpora:
   progress, so the next run resumes from the verified cursor;
 - concurrent refresh requests share one worker run.
 
+Quota history is populated opportunistically by those same JSONL passes. An
+older complete index may receive one metadata-only seed from its already saved
+last-observed limit, but there is no second quota scanner, timer, network poll,
+or credential lookup. Once that seed is present, an unchanged warm refresh
+continues to read zero usage-record bodies.
+
+Historical work also has a small durable control state: measurement version,
+reason, progress, failure streak, next eligible time, and pause reason. Progress
+continues immediately after success. Failure or no progress applies backoff, so
+ordinary refresh/watch/focus events cannot restart the same stalled migration.
+The resource registry records who created every timer, watcher, worker, network
+request, and backfill, and releases a lease only after its real stop callback
+finishes. A bounded first-index backfill may continue after focus loss for
+first-use latency, but extension disposal, provider disable, or explicit
+cancellation still owns its termination.
+
 Weekly API-equivalent history is derived from already-aggregated token usage.
-Observed weekly resets align seven-day buckets; otherwise usage-only history
-uses Monday-to-Monday UTC calendar weeks. A token log can prove used value, but
-not an historical subscription capacity: full and unused estimates are emitted
-only where a real quota-utilization sample exists. Codex usage-only history may
-combine multiple sign-ins in one home, while quota-derived rows remain bound to
-their observed reset series.
+The newest valid reset observation anchors non-overlapping seven-day display
+buckets; without one, usage-only history uses Monday-to-Monday UTC calendar
+weeks. A real utilization sample can support a full-window estimate, including
+for historical buckets. For Codex, the account-wide `codex` series is allowed to
+use all eligible local files in the same home because file keys are not account
+identities. A reset that drifts from the seven-day grid is mapped by observation
+time to the corresponding display bucket; source uncertainty, reset drift, and
+daily slices crossing a boundary lower confidence and are rendered as an
+approximation. A genuinely different quota series remains usage-only. Current
+unused value is withheld, while historical unused value is shown only alongside
+a full estimate. Each usage row still contributes to exactly one bucket.
 
 v2.3.0 does not infer a $20, $100, or $200 subscription tier. Local Codex logs
 do not expose a reliable account-and-plan identity, so a future comparison must
@@ -275,6 +341,8 @@ use an explicit opt-in account mapping rather than attaching prices by guess.
   VSIX smoke test are required in proportion to the change.
 - User-visible strings cover `en`, `de-DE`, `zh-TW`, `zh-CN`, `ja`, `ko`,
   `pt-BR`, and `id`; all seven README editions move together.
+- Dormant preparation/experiment modules and review-only v2.3.1 documents stay
+  unreachable from the production command graph and are excluded from VSIX.
 - `package.json` is not manually version-bumped. Publishing the reviewed Release
   Drafter draft creates the tag; the publish workflow stamps that tag version.
 - Contributor PR attribution is preserved by merging the contributor's original
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dce931ae..075e06ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,223 @@ All notable changes to this fork compared to upstream
 [`ClaudeCodeUsage/ClaudeCodeUsage`](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage) (last
 upstream release: 1.0.8). Format follows [Keep a Changelog](https://keepachangelog.com).
 
+## [2.3.1] — Unreleased
+
+### Added
+- **GPT-6 Astra and Claude Fable 5.1 pricing** — exact model IDs now use their
+  current official Standard API rates and context windows: `gpt-6-astra`
+  (1.05M context) and `claude-fable-5-1` / `claude-mythos-5-1` (1M context).
+  Fable 5.1's model-specific cache-read rate is `$0.25 / MTok`; historical
+  Fable 5 pricing remains unchanged. GPT-6 requests above 272K input receive a
+  request-wide surcharge from OpenAI, but local aggregate logs cannot prove
+  that per-request boundary, so the API-equivalent estimate deliberately uses
+  the standard short-context rate and keeps the existing request-level-pricing
+  disclaimer.
+- **AWS Bedrock in-region Claude pricing (#95)** — an opt-in Claude pricing
+  backend covers Opus 4.5–5, Sonnet 4.5–5, and Haiku 4.5 with separate
+  5-minute/1-hour cache-write and cache-read rates. Switching backends
+  invalidates cached Claude cost aggregates so unchanged local logs are
+  repriced immediately. Sonnet 5 uses the standard in-region rate that applies
+  after its launch promotion ended on 2026-08-31. Thanks to
+  [@akapti](https://github.com/akapti) for the contribution.
+- **Combined activity heatmap and private sharing** — Compare now leads with a
+  Claude + Codex calendar heatmap built from the existing provider daily
+  aggregates. Its preview-first share studio exports deterministic local SVG, a
+  privacy-safe card, and a copyable Markdown snippet with configurable title,
+  30/90-day or yearly range, and an explicit privacy preview. The default
+  Academic Violet ramp follows the project-profile visual reference, quantile
+  bands keep isolated peaks from flattening ordinary days, and the mapping can
+  be switched locally between quantile, logarithmic, and linear modes. Four
+  curated or one custom accent palette can be selected. Claude-only and
+  Codex-only histories remain useful; no second log scan or statistics cache is
+  introduced.
+- **Durable quota observation history** — versioned, atomically written,
+  bounded observations keep provider, machine-local anonymous account epoch,
+  observation/reset time, used/remaining fraction, window identity, source,
+  confidence, and quality flags. Window-ID changes, reset-time changes, and
+  significant usage rollbacks preserve irregular and same-day reset events.
+- **Observed weekly allowance estimates** — every valid observation in a
+  coherent window contributes `priced used equivalent / used fraction`; robust
+  aggregation weights price/log coverage, boundary quality, attribution, and
+  recency. Total estimates never fall below confirmed usage, unused estimates
+  never go negative, and a coherent current or completed window exposes both as
+  a subscription-durability estimate. If later logs overrun a stale observation,
+  the full value remains a low-confidence lower bound while unused is withheld
+  instead of showing a false zero. Unattributed or approximate windows are
+  labelled low confidence. Even when local Codex quota series overlap, the
+  current period uses the latest real observation for a clearly labelled
+  low-confidence blended total/unused estimate; ambiguous completed periods
+  stay used-only.
+- **Evidence-backed advice loop** — the default-off feature keeps local
+  observations, evidence, recommendations, actions, local helpful/not-helpful/
+  applied feedback, and guarded comparable-task results in one surface. When
+  reliable comparable work is unavailable, it says that the evidence is
+  insufficient instead of manufacturing an improvement claim.
+- **Exact BYOK preview and explicit send** — aggregate-only is the default.
+  Prompt personalization has separate consent. The complete Anthropic or
+  OpenAI-compatible request body is prepared once, previewed with its byte count
+  and SHA-256, and only the same canonical bytes can be sent after a second user
+  click. Claude Code OAuth credentials are never used for generative requests.
+- **Versioned local comparison evidence** — sanitized task pairs and frozen
+  comparison-result envelopes retain only coarse provider, cohort, metric,
+  quality, coverage, and version fields. Prompt text, response text, paths,
+  session identifiers, and task bodies have no persistence field.
+- **Bounded local advice snooze** — each recommendation can be paused for seven
+  days (up to thirty days), moved out of the default summary, and shown again
+  on demand or after expiry; ratings and applied feedback remain independent.
+- **Thirty-day Codex hourly drill-down** — every populated date in the rolling
+  30-day view can expand from the already-indexed sparse date/hour sidecar.
+  Clicking a date reads zero JSONL bodies; the 31st day is evicted, and Claude
+  and Codex use the configured timezone and shared `HH:00` labels.
+
+### Changed
+- **Refreshed release documentation** — all seven README editions now show the
+  current Claude Today, Codex overview, collapsed weekly details, and vertical
+  sharing studio. Captures use the production renderer with disclosed synthetic
+  fixtures; a repeatable capture script keeps screenshot provenance explicit.
+- **Shared dashboard system** — Claude and Codex now reuse the same density,
+  headings, disclosure controls, chart/table framing, empty states, focus
+  treatment, responsive navigation, and light/dark design tokens while keeping
+  provider-specific metric labels and meanings. Dashboard figures use the VS
+  Code UI font again; monospace remains limited to code and copyable snippets.
+- **Preview-first sharing layout** — the combined heatmap now occupies the full
+  reading width and Card settings sit directly below it. Weekly period tables
+  are collapsed by default so the trend chart remains primary. The sharing
+  workspace is enabled by default and one Settings toggle hides all sharing UI.
+- **Concise plugin settings** — the verbose local-data inventory and destructive
+  privacy-control panel no longer renders inside the dashboard. The authoritative
+  inventory, retention boundaries, and clear paths remain in the repository's
+  `LOCAL-DATA.md` files.
+- **Aligned Codex status bar** — the main Codex item now uses configured-zone
+  Today instead of Recent task. Its compact quota percentage means remaining
+  allowance; the tooltip and warning colour continue to use observed utilisation
+  with Claude's progress bars, thresholds, reset columns, and line wrapping.
+- **Chronological month views** — Codex monthly charts and tables render
+  oldest-first in every range.
+- **Explicit Codex uncached composition** — the Token composition summary now
+  surfaces uncached usage (uncached input + output) while retaining the
+  non-overlapping uncached-input / cached-input / output stack; reasoning stays
+  a disclosed subset of output.
+- **System-reminder prompt filtering remains intentional** — framework reminder
+  messages are excluded from user-input counts; token and cost totals are unchanged.
+- **One AI request boundary** — the former Get AI Advice command and Usage
+  Optimizer now enter the same preview, explicit-send, cancellation, strict
+  response parsing, and local-state boundary. The optimizer still sends only
+  the draft pasted by the user and keeps its copyable result format.
+- **Resumable Codex historical work** — first-use and migration work records its
+  progress, failure streak, next eligible time, and pause reason. Successful
+  work continues without an artificial delay; failure or no progress cannot be
+  hot-looped by ordinary refreshes, and restart resumes from a safe checkpoint.
+- **Unified resource ownership** — timers, watchers, workers, network requests,
+  and backfills expose their creator, stop conditions, and actual disposal to
+  lifecycle tests. A bounded first-index exception may finish after focus loss,
+  but disable, explicit cancellation, and extension disposal still stop it.
+- **Safer Codex rolling totals and reset history** — recent 7/30-day views no
+  longer trust an inflated or still-rebuilding period sidecar; they use the
+  verified daily aggregate until the configured-zone projection catches up.
+  The existing index pass also captures compact quota observations without
+  polling, credentials, or a second scanner.
+
+### Fixed
+- **One-time v2.3.0 Codex token-semantics migration** — the per-file parser
+  state now carries a new semantics version. Existing schema-3 indexes request
+  one bounded, resumable rebuild instead of retaining pre-fix request
+  attribution indefinitely; completed files survive partial checkpoints.
+- **Account-aware quota confidence** — a reset boundary may remain useful for
+  deterministic weekly alignment across anonymous Codex epochs, but crossing
+  an account/profile fingerprint can no longer erase `account-ambiguous`.
+  Current-window total and unused estimates remain available at low confidence.
+- **Deterministic scroll debounce test** — continuous-scroll coverage now emits
+  one synchronous gesture and advances only the fake clock, removing a race
+  between animation frames and the 180 ms persistence timer.
+- **Immediate advice-consent revocation** — withdrawing aggregate or prompt
+  consent immediately invalidates prepared previews and cancels active advice
+  requests, without waiting for local storage. New previews/sends stay blocked
+  until all consent writes settle; persistence failures stay closed. Unrelated
+  user-draft Optimizer requests are not cancelled. Already transmitted bytes
+  cannot be recalled.
+- **Claude watcher failures fall back safely** — asynchronous `fs.watch`
+  errors (for example, an exhausted watch-handle limit) are now handled after
+  registration, close the owned watcher cleanly, and leave normal polling
+  active instead of escaping through the Extension Host.
+- **Timezone-stable chart date labels** — daily and monthly usage keys no
+  longer roll back a day or month when a chart metric changes or a drill-down
+  renders in a Webview host/configured timezone west of UTC. Bare monthly keys
+  also render as the intended month instead of `Invalid Date`.
+- **Configured-zone advice snooze dates** — Advice and Optimizer now format a
+  snooze expiry with the selected UI locale and configured timezone instead of
+  whichever timezone happens to host the Extension process.
+- **Configured-zone rolling ranges** — the Claude provider heatmap now ends on
+  today in the configured timezone. Share Card 7-day, 30-day, and yearly scopes,
+  plus Usage tracking and AI-advice 7-day/30-day attribution, use exact
+  civil-date windows instead of fixed millisecond cutoffs. Claude and Codex
+  session range filters now follow those same Today/7-day/30-day date keys.
+  Claude session, project, branch, and workflow timestamps also use the
+  configured timezone for their clock and Today/Yesterday/year labels.
+  Activity near UTC boundaries is no longer omitted or pulled from an adjacent
+  local day.
+- **Complete Share studio localization** — the active Compare sharing workspace
+  now carries complete German, Japanese, Korean, Brazilian Portuguese, and
+  Indonesian copy instead of silently falling back to English. A repository
+  coverage guard keeps all eight supported locales aligned when copy fields
+  change.
+- **Hardened Codex thread-title path redaction** — runtime titles now mask POSIX
+  absolute paths even when a path is attached directly to a colon or other
+  punctuation (for example, `3:/Users/name`), preventing local usernames and
+  filesystem locations from reaching dashboard text or screenshots.
+- **Claude chart drill-down reload parity** — expanded day-to-hour and
+  month-to-day rows now survive a Webview reload, re-request their lazy detail
+  data, and retain selected/ARIA state. Chart controls derive their drill-down
+  kind from their own tab instead of whichever tab happened to be active while
+  the page initialized; an intentional tab switch still clears expansions.
+- **Claude rolling-range regression** — Claude's middle dashboard tab now uses
+  Today plus the preceding 29 configured-zone calendar dates instead of the
+  current calendar month. The Workflows summary now uses the same rolling range,
+  classifies runs by their configured-zone start date, and compares against the
+  matching 30-day total. The monthly-cost status-bar option remains a calendar
+  month, and an empty Today view identifies the latest recent activity date.
+- **Reconciled 30-day Codex statistics** — “Last 30 days” is the configured
+  timezone's current calendar date plus the preceding 29 dates. The view is
+  projected from verified daily aggregates, so Today ≤ Last 30 days ≤ All time,
+  daily/monthly/model/effort totals reconcile, and repeated refresh/reindex does
+  not accumulate duplicate thread or historical-file usage.
+- **Reasoning-effort normalization** — current, legacy, nested, missing, and
+  invalid structured variants are normalized without guessing from a model
+  name. Non-zero unknown usage is visible with an explanation; zero-value
+  unknown rows are omitted.
+- **Duplicate share rows fail safely** — identical provider/date rows are
+  idempotent, conflicting duplicates block export, and absent dates render as
+  zero in the selected range.
+- **Smooth Codex dashboard scrolling** — scroll position is persisted once
+  after a gesture instead of serializing Webview state on every animation
+  frame. Live first-index progress now patches its status text in place rather
+  than rebuilding the complete dashboard DOM every 250 ms, so active indexing
+  no longer interrupts scrolling or disclosure state.
+- **Per-model API-equivalent headlines** — Codex model disclosures now follow
+  Claude's visual meaning: the green value is an exact-model API-equivalent
+  price with pricing-coverage help. Unknown models remain visibly unpriced, and
+  effort disclosures keep their uncached-token value in neutral text.
+- **OpenAI reasoning-effort requests** — OpenAI-compatible request bodies now
+  send `reasoning_effort` without the unsupported top-level `thinking`
+  parameter, fixing [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94).
+  Thanks to [@aaroncvan](https://github.com/aaroncvan) for the report and
+  [@Alex668866](https://github.com/Alex668866) for the precise diagnosis.
+
+### Privacy and packaging
+- Disabled or unconsented advice adds no timer, watcher, worker, network request,
+  log scan, or hidden Webview render relative to v2.3.0. There are no default or
+  background AI requests.
+- Combined exports contain only title, date range, daily aggregate totals,
+  provider labels, and caveats—never accounts, fingerprints, projects, threads,
+  paths, prompts, or log content. Local SVG/Markdown needs no account permission.
+- Direct GitHub publication remains an explicit, exact-destination action. It
+  requests only `public_repo`, verifies a public repository and default branch,
+  previews create/overwrite, and stores owner/repository/path only after success.
+  Release validation uses mocks and performs no real repository write.
+- Dormant migration/experiment modules and internal v2.3.1 review documents are
+  explicitly excluded from the VSIX. The human-controlled publish workflow
+  stamps package metadata from the reviewed `v2.3.1` release tag.
+
 ## [2.3.0] — Unreleased
 
 ### Fixed
@@ -19,16 +236,19 @@ upstream release: 1.0.8). Format follows [Keep a Changelog](https://keepachangel
 - **Weekly API-equivalent periods no longer overlap or double-count usage** —
   the newest valid official reset observation anchors one sequence of unique
   `[start, reset)` weekly buckets, so each local usage event contributes to
-  exactly one period. Any overlapping, non-aligned future reset is treated as a
-  conflict even when its series name differs; it cannot create an additional
+  exactly one period. A genuinely different quota series with an overlapping,
+  non-aligned future reset is treated as a conflict; same-series observations
+  remain one low-confidence series rather than creating an additional
   "current" row. Codex usage is persisted in daily slices, so a slice that
   crosses an official intraday reset remains counted once but marks the affected
-  period as a boundary approximation and suppresses total / unused allowance
-  inference. This display-only correction does not change the index schema or
-  trigger a rebuild. Historical Codex periods are always used-value-only; only
-  the newest current period may infer a total when its reset is unambiguous and
-  its indexed usage can be attributed to one observation source. Current unused
-  value remains withheld, and ambiguous multi-sign-in usage stays used-only.
+  period as a boundary approximation and lowers confidence on any full
+  allowance estimate. Drifted reset observations are mapped by observation time
+  to the corresponding display bucket. This display-only correction does not
+  change the index schema or trigger a rebuild. Same-series Codex observations
+  can estimate historical as well as current full values from all eligible local
+  files; current unused value remains withheld, historical unused value requires
+  a full estimate, and genuinely different quota series or missing evidence stays
+  used-only.
 - **Claude changed-file refreshes no longer reread the full corpus (#87)** —
   the production refresh path now keeps an exact in-memory per-file index,
   reads only a verified append tail, and rebuilds only affected files for
@@ -91,10 +311,12 @@ upstream release: 1.0.8). Format follows [Keep a Changelog](https://keepachangel
   views now calculate historical used API-equivalent value directly from local
   token logs. One valid observed reset anchors unique, non-overlapping weekly
   buckets; without one, usage-only rows use Monday-to-Monday UTC calendar weeks.
-  Codex historical periods, boundary-approximate daily slices, conflicting reset
-  sequences, and usage that cannot be assigned to one observed sign-in remain
-  used-value-only. Only an unambiguous newest current period with single-source
-  attribution may infer a total allowance; its unused value is still withheld.
+  Codex account-wide observations can decorate historical and current buckets;
+  reset drift is mapped by observation time, while source ambiguity and boundary
+  slices lower confidence. Genuinely conflicting quota series and periods with
+  no usable observation remain used-value-only. Current unused value is still
+  withheld, while historical unused value is shown only when a full estimate is
+  available.
   Current official API prices are applied consistently and each period includes
   model-price coverage. This remains an estimate, not a bill or an official
   subscription price. The panel is enabled by default and can be hidden with
diff --git a/LOCAL-DATA.md b/LOCAL-DATA.md
new file mode 100644
index 00000000..c8a50812
--- /dev/null
+++ b/LOCAL-DATA.md
@@ -0,0 +1,116 @@
+# Local data and privacy
+
+Claude Code Usage is local-first. It reads provider-owned usage logs, stores
+only bounded derived state needed for fast refresh and reset-aware estimates,
+and never treats API-equivalent cost as a bill.
+
+This page is the user-facing inventory for v2.3.1. The normative field-level
+contract is in
+[`docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md`](docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md).
+
+## What the extension reads and retains
+
+| Data class | Source | What is retained by the extension | Retention and clearing | Remote interaction |
+|---|---|---|---|---|
+| Claude usage records | Claude Code's local `projects/**/*.jsonl` | Runtime usage records and an in-memory per-file index; bounded prompt samples only when content analysis is enabled | Released on window reload/exit. Data controls never touch source logs; the separately opt-in Session Actions feature may move one exactly confirmed log to the OS trash (recoverable) | None unless the user separately previews and sends an advice request |
+| Codex usage records | `$CODEX_HOME/sessions/**/*.jsonl` and `archived_sessions/**/*.jsonl` | A versioned incremental index of pseudonymous file keys, offsets, numeric usage, dates, model/effort, and sanitized structural aggregates | Until rebuild, explicit clear, schema replacement, or host removal | None |
+| Codex titles | Exactly `$CODEX_HOME/session_index.jsonl` | `id → thread_name` is streamed for runtime display; titles are not written to the index | Runtime only | None |
+| Quota observations | Claude's official quota response or structured Codex rate-limit events | Provider, machine-local anonymous account epoch, observed/reset time, period, used/remaining fraction, anonymous window identity, source, confidence, and quality flags | At most 180 days and 512 observations per provider/account/period after boundary-preserving compaction; clear separately or with all derived data | Claude quota lookup contacts Anthropic when enabled; Codex quota evidence is local |
+| Settings and UI preferences | User choices | Typed extension settings, selected tab/filters, bounded background-work state, heatmap title/range/privacy preview | Until reset, clear, or uninstall; ordinary VS Code settings may participate in Settings Sync | No extension-initiated transfer |
+| Share destination | User-entered GitHub target | Optional `owner/repository/path`; no GitHub credential | Until sharing preferences are reset | Only after an explicit publish action and exact destination confirmation |
+| Advice evidence | Derived local aggregates and explicit feedback | Coarse observations, recommendations, ratings, snoozes, comparable-task metrics, coverage, and versions | Bounded local ledger; clear independently | Nothing by default; only the exact previewed request is sent after a separate action |
+| Advice API key | User-provided secret | Secret value in VS Code SecretStorage only | Until the key or all derived data is cleared | Used only as the authorization credential for the explicitly configured endpoint |
+
+## What is never cached
+
+- OAuth access or refresh tokens, cookies, authorization headers, or GitHub
+  credentials.
+- API keys outside VS Code SecretStorage.
+- Full account identifiers, email addresses, display names, or subscription
+  names. Account continuity uses a machine-local HMAC fingerprint or an
+  isolated unattributed epoch.
+- Raw prompt/response bodies, tool arguments, commands, complete CLI output,
+  absolute source-log paths, repository remotes, or persistent thread titles.
+
+Different anonymous account fingerprints are not merged. If local Codex logs
+cannot establish one coherent account/window, the dashboard shows only used
+API-equivalent value and explains why it cannot claim an account-level unused
+allowance.
+
+## Combined heatmap and exports
+
+The Compare heatmap reuses daily provider aggregates; it does not scan logs
+again or create another statistics cache.
+
+```text
+Claude processed = input + cache creation + cache read + output
+Codex processed  = input total + output total
+Combined activity = Claude processed + Codex processed
+```
+
+Codex cached input is already part of input total, and reasoning is already
+part of output total, so neither is added again. Combined activity is local
+token volume—not productivity, billing, model capability, or provider
+equivalence.
+
+Local SVG and Markdown exports contain only a bounded title, selected date
+range, daily Claude/Codex/combined aggregates, labels, and caveats. They do not
+contain accounts, projects, thread titles, paths, prompts, or log content.
+
+Direct GitHub publication is optional and never runs in the background. v2.3.1
+requests `public_repo`, verifies the repository is public and resolves its
+default branch, then asks the user to confirm the exact
+`owner/repository/branch/path` and whether the file will be created or replaced.
+Private repositories use local SVG plus Markdown instead of silently requesting
+broader access.
+
+## Clear and migration behavior
+
+Separate Command Palette actions rebuild the Codex derived index, clear quota
+history, clear advice data, reset UI or sharing preferences, and remove the BYOK
+secret. “Clear all extension-derived data” first lists its targets. These
+maintenance actions stay out of the dashboard Settings tab so it remains
+concise. None of them deletes Claude or Codex source logs or provider-owned
+credentials.
+
+Clearing all quota history atomically replaces the quota store with one valid
+empty schema-2 document and removes only its exact quarantine/interrupted-write
+siblings under the same cross-process lease. A provider/account-only clear
+fails closed when quarantined data or an unresolved legacy migration cannot be
+assigned safely; the user may then explicitly choose the all-history clear.
+
+Clear All deletes an exact catalog of released setting/state names, not every
+key beginning with `ccu.setting.`. Unknown or future keys are preserved. Before
+any mutation it checks all currently visible configuration scopes; an
+unregistered legacy setting that VS Code cannot safely update blocks the whole
+operation, leaves existing data intact, and is reported for manual removal.
+Queued activation writes are drained before deletion and exact postconditions
+are verified afterward. If the Webview cannot acknowledge its allowlisted
+browser-state reset, a value-free pending action marker is retried on the next
+panel open instead of reporting a false success.
+
+This clearing boundary is separate from the opt-in Session Actions feature.
+That feature can move one user-selected Claude session log to the OS trash only
+after its own modal confirmation; it never participates in Clear All.
+
+v2.3.1 validates and atomically migrates known legacy quota/config state before
+removing the legacy copy. Corrupt or future-schema files fail closed; an old
+valid file is not overwritten until the replacement validates. Uninstall may
+leave host-managed extension storage behind, so the explicit clear command is
+the reliable deletion route.
+
+VS Code only lets the running extension inspect Global, the current Workspace,
+and currently open Workspace Folder configuration scopes. A legacy value that
+exists only in a closed workspace remains there until that workspace is opened
+and the clear control is run again (or the setting is removed manually).
+
+## Known limits
+
+- A reset that never appears in an official response or local structured event
+  cannot be reconstructed. Day-only Codex evidence lowers boundary confidence.
+- Local Codex histories may include several sign-ins. Ambiguous overlap remains
+  used-only; the extension never invents an account split.
+- API-equivalent values use currently known public API prices and pricing
+  coverage. They are estimates, not provider bills or subscription prices.
+- Retention of source logs is controlled by Claude Code and Codex, not this
+  extension.
diff --git a/LOCAL-DATA.zh-CN.md b/LOCAL-DATA.zh-CN.md
new file mode 100644
index 00000000..6fb06ea5
--- /dev/null
+++ b/LOCAL-DATA.zh-CN.md
@@ -0,0 +1,93 @@
+# 本地数据与隐私
+
+Claude Code Usage 采用本地优先设计。插件只读取供应商拥有的本地用量日志，
+并保留快速刷新、重置识别和额度估算所必需的有界派生状态；API 等效成本始终
+只是估算，不是账单。
+
+本文是 v2.3.1 面向用户的数据清单。字段级规范见
+[`docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md`](docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md)。
+
+## 插件读取和保留什么
+
+| 数据类别 | 来源 | 插件保留的内容 | 保留与清除 | 远程交互 |
+|---|---|---|---|---|
+| Claude 用量记录 | Claude Code 本地 `projects/**/*.jsonl` | 运行时用量记录和内存中的逐文件索引；仅在启用内容分析时保留有界提示样本 | 窗口重载/退出即释放。本地数据控制绝不触碰源日志；另行启用的“会话操作”可把一个精确确认的日志移入系统回收站（可恢复） | 默认无；只有用户另行预览并发送建议请求时才可能包含获准内容 |
+| Codex 用量记录 | `$CODEX_HOME/sessions/**/*.jsonl` 与 `archived_sessions/**/*.jsonl` | 版本化增量索引：匿名文件键、偏移量、数值用量、日期、模型/effort 和已净化结构聚合 | 保留到重建、明确清除、schema 替换或宿主移除 | 无 |
+| Codex 标题 | 仅 `$CODEX_HOME/session_index.jsonl` | 流式读取 `id → thread_name` 供运行时显示；标题不写入索引 | 仅运行时 | 无 |
+| 额度观测 | Claude 官方额度响应或 Codex 结构化 rate-limit 事件 | 供应商、本机匿名账号 epoch、观测/重置时间、周期、已用/剩余比例、匿名窗口标识、来源、可信度和质量标志 | 保留不超过 180 天；边界保护压缩后每个供应商/账号/周期最多 512 条；可单独或随全部派生数据清除 | 启用时 Claude 额度查询会访问 Anthropic；Codex 额度证据只来自本地 |
+| 设置与 UI 偏好 | 用户选择 | 类型化设置、标签页/筛选、有限后台任务状态、热力图标题/范围/隐私预览 | 保留到重置、清除或卸载；普通 VS Code 设置可能参与 Settings Sync | 插件不主动传输 |
+| 分享目标 | 用户输入的 GitHub 目标 | 可选 `owner/repository/path`；不保存 GitHub 凭据 | 保留到重置分享偏好 | 仅在用户明确发布并确认精确目标后发生 |
+| 建议证据 | 本地派生聚合与明确反馈 | 粗粒度观察、建议、评分、暂停、可比任务指标、覆盖率和版本 | 有界本地台账；可独立清除 | 默认不发送；只有单独确认后才发送精确预览过的请求 |
+| 建议 API Key | 用户自备密钥 | 仅存于 VS Code SecretStorage | 保留到清除密钥或全部派生数据 | 只作为用户明确配置端点的授权凭据 |
+
+## 绝不缓存什么
+
+- OAuth access/refresh token、cookie、authorization header 或 GitHub 凭据。
+- VS Code SecretStorage 之外的 API key。
+- 完整账号标识、邮箱、显示名或订阅名称。账号连续性只用本机 HMAC
+  fingerprint 或隔离的未归属 epoch。
+- 原始提示/响应正文、工具参数、命令、完整 CLI 输出、源日志绝对路径、
+  仓库 remote 或持久化线程标题。
+
+不同匿名账号 fingerprint 不会合并。如果本地 Codex 日志无法证明属于同一账号
+和同一窗口，仪表盘只显示已用 API 等效价值，并说明为何不能声称账号级未用额度。
+
+## 综合热力图与导出
+
+“对比”热力图直接复用供应商日聚合，不会再次扫描日志，也不会新增第二套统计缓存。
+
+```text
+Claude processed = input + cache creation + cache read + output
+Codex processed  = input total + output total
+综合活动量 = Claude processed + Codex processed
+```
+
+Codex 的 cached input 已包含在 input total 中，reasoning 已包含在 output total 中，
+因此均不得重复相加。综合活动量只代表本地 Token 活动，不代表生产率、账单、模型能力
+或两个供应商的能力等价。
+
+本地 SVG 与 Markdown 导出只含有界标题、所选日期范围、每日 Claude/Codex/综合聚合、
+标签和免责声明；不含账号、项目、线程标题、路径、提示或日志内容。
+
+直接发布到 GitHub 是可选动作，且绝不在后台运行。v2.3.1 仅请求 `public_repo`，
+先验证仓库公开性和默认分支，再要求用户确认精确的
+`owner/repository/branch/path` 以及创建或覆盖动作。私有仓库应改用本地 SVG +
+Markdown，不会静默索取更宽权限。
+
+## 清除与迁移
+
+命令面板提供独立维护动作：重建 Codex 派生索引、清除额度历史、清除建议数据、重置
+UI 或分享偏好、移除 BYOK 密钥。“清除全部扩展派生数据”会先列出精确目标。这些动作
+不进入仪表盘设置页，以保持插件设置简洁；同时均不删除 Claude/Codex 源日志或供应商
+拥有的凭据。
+
+清除全部额度历史时，插件会在同一个跨进程 lease 内把额度存储原子替换为一个合法的
+空 schema-2 文档，并只删除该文件族中精确匹配的隔离/中断写入文件。若隔离数据或尚未
+完成的旧版迁移无法安全归属到 provider/账号，范围清除会安全拒绝；用户可再明确选择
+清除全部额度历史。
+
+“清除全部”按已发布的精确 setting/state 名称清单删除，不会泛删所有
+`ccu.setting.*`；未知或未来键会保留。任何修改之前，插件先检查当前可见配置作用域；
+若发现 VS Code 已无法安全更新的未注册旧设置，整个操作会在零删除状态下停止，并提示
+手动移除。激活期排队写入会先排空，删除后再验证精确后置条件。若 Webview 未能确认其
+白名单浏览器状态已清除，插件会保存一个不含数据值的待重试动作，在下次打开面板时重放，
+而不会误报成功。
+
+这个清除边界与另行选择启用的“会话操作”相互独立。后者只有在用户针对单个 Claude
+会话日志完成模态确认后，才会把它移入系统回收站（可恢复）；它不会参与“清除全部”。
+
+v2.3.1 会先验证并原子迁移已知旧版额度/配置状态，成功后才移除旧副本。损坏或未来
+schema 会安全失败；替代文件通过验证前不会覆盖旧的有效文件。卸载后宿主可能保留
+扩展存储，因此明确的清除命令才是可靠删除路径。
+
+VS Code 只允许当前运行的插件检查 Global、当前 Workspace 及当前已打开的 Workspace
+Folder 配置作用域。只存在于关闭工作区中的旧值会继续保留，直到打开该工作区后再次
+运行清除控制（或手动删除该设置）。
+
+## 已知限制
+
+- 从未出现在官方响应或本地结构化事件中的重置无法重建；只有日粒度的 Codex 证据
+  会降低边界可信度。
+- 同一 Codex home 可能包含多个登录。归属重叠不清时只显示已用值，绝不虚构账号拆分。
+- API 等效价值按当前已知公开 API 单价和定价覆盖率估算，不是供应商账单或订阅价格。
+- 源日志保留期由 Claude Code 和 Codex 控制，不由本插件控制。
diff --git a/README-en.md b/README-en.md
index 043b98d1..ab665cea 100644
--- a/README-en.md
+++ b/README-en.md
@@ -10,7 +10,7 @@
 >
 > **What it is _not_:** a billing tool. All amounts are estimates based on public per-million-token rates. Refer to your Anthropic account for actual charges.
 
-> Screenshots are from the English UI. See the [main README](README.md) for the full feature reference.
+> Screenshots include English and Simplified Chinese. See the [main README](README.md) for the full feature reference.
 
 ## Screenshots
 
@@ -26,24 +26,67 @@ Hover the quota indicator for a breakdown:
 
 ![Dashboard](images/v2-dashboard-en.png)
 
+### v2.3.1 Codex and Compare
+
+![Claude Today, Simplified Chinese, dark theme](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+![Codex overview, Simplified Chinese, dark theme](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+![Codex weekly allowance estimate, English, dark theme](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+![Combined Claude and Codex heatmap, English, light theme](images/v2.3.1/compare-heatmap-en-light.png)
+
+These four v2.3.1 captures use the production renderer, synthetic fixtures, and VS Code Light+/Dark+ theme variables—not personal usage or billing evidence. Native VSIX installation is checked separately.
+
+- Codex shows **Today token usage** and separate **remaining quota**: 36% used means `wk 64%`. Hover shows utilisation bars, resets, and wrapped notes. Quota is last-observed local evidence, not a live balance.
+- Period details start collapsed; sharing settings sit below the preview. Sharing is on by default with an off switch and quantile, logarithmic, or linear intensity.
+- CLI calls count only when persistent sessions leave usage-bearing logs. Non-persisted calls cannot be backfilled; Today and Last 30 days use the configured timezone.
+
 ## Features
 
 - **Status bar** — today's cost, current-session cost, and real 5-hour / weekly quota (`5h:N% wk:N%`) read from Claude Code's own OAuth session. Zero configuration.
-- **Dashboard tabs** — Today / This Month / All Time, plus **Sessions / Projects / Content / Branches**, all sortable.
+- **Dashboard tabs** — Today / Last 30 Days / All Time, plus **Sessions / Projects / Content / Branches**, all sortable.
 - **Stacked cost-composition charts** with a Y-axis and reference lines — see at a glance how much of each day / month went to input, output, cache-write and cache-read.
 - **Content tab** — estimates which content consumes your tokens (your prompts vs. tool results vs. assistant output / thinking).
-- **AI advice** (opt-in) — sends a usage summary plus a sample of your prompts to an OpenAI-compatible API (DeepSeek V4 Pro by default) and suggests concrete rewrites. Bring your own key, or preview a static demo first.
+- **AI advice** (opt-in) — starts with local evidence and explainable actions. Optional BYOK personalisation defaults to aggregates only; prompt samples require separate consent. The exact full request is previewed before a separate Send action, and helpful / not-helpful / applied feedback stays local. Recommendations can be snoozed for a bounded period and return after expiry or on demand.
+  Withdrawing advice consent immediately invalidates previews and cancels active advice requests; already transmitted bytes cannot be recalled.
 - **Multi-vendor pricing** — Opus 4.x / Sonnet 4.x / Haiku 4.5 verified against Anthropic's public pricing; reference rates for OpenAI / Gemini / DeepSeek / Kimi / GLM / Qwen with family-aware fallback. `Refresh Token Pricing` pulls live LiteLLM data.
 - **Personalisation** — language, timezone, decimal places, compact numbers, project grouping, dashboard auto-refresh toggle.
 
+## What's new in v2.3.1
+
+- Exact pricing and context metadata now cover **GPT-6 Astra**
+  (`gpt-6-astra`, 1.05M context) and **Claude Fable 5.1 / Mythos 5.1**
+  (`claude-fable-5-1` / `claude-mythos-5-1`, 1M context). Fable 5.1 uses its
+  model-specific `$0.25 / MTok` cache-read rate without changing historical
+  Fable 5 data. GPT-6 API-equivalent values use the official Standard
+  short-context rates; the request-wide surcharge above 272K input is excluded
+  because aggregate local logs cannot establish that per-request threshold.
+- Claude estimates can optionally use direct Anthropic or AWS Bedrock in-region
+  on-demand rates for current Opus, Sonnet, and Haiku families. Switching the
+  backend reprices unchanged logs immediately; Sonnet 5 uses the standard rate
+  after its launch promotion ended on 31 August 2026.
+- Last 30 days is the configured-timezone current date plus the preceding 29 dates. Today ≤ Last 30 days ≤ All time, repeated refresh/reindex is stable, all breakdowns reconcile, and months run oldest-first. Claude's Workflows summary uses the same rolling range and assigns each run by its configured-zone start date. Chart metric switches and drill-down labels render daily/monthly usage keys without host-timezone rollback; Advice and Optimizer snooze dates also use the configured timezone and UI locale.
+- Structured reasoning-effort variants normalize without model-name guessing. Non-zero unknown is explained; zero unknown is hidden.
+- Bounded anonymous quota observations preserve irregular and same-day resets. Every valid same-window used fraction contributes to labelled total and unused subscription-durability estimates, including the current window. Approximate or unattributed evidence is low confidence. If local Codex quota series overlap, the current window uses the latest real observation for a low-confidence blended estimate; ambiguous completed windows remain used-only. Unused value never becomes negative.
+- Compare now leads with a combined Claude + Codex activity heatmap that reuses daily aggregates, works with either provider alone, and keeps both components in every tooltip.
+- The preview-first share studio supports deterministic local SVG, a combined card, copyable Markdown, title/range controls, a privacy preview, and curated/custom colors. It is on by default and can be hidden with one Settings switch. Academic Violet is the default; intensity can use quantile (default), logarithmic, or linear mapping. Optional public-GitHub publication is separately confirmed at the exact destination.
+- Codex Token composition now shows **uncached usage** (uncached input + output) above the non-overlapping uncached-input / cached-input / output stack; reasoning remains a subset of output.
+- Codex scrolling stays smooth while indexing: scroll state is saved once after a gesture and live index progress patches text without rebuilding the page. Per-model green headlines now show exact-model API-equivalent price with coverage help; unknown models show `—`, while effort headlines retain neutral uncached-token values.
+- OpenAI-compatible optimizer requests now send `reasoning_effort` without the unsupported top-level `thinking` parameter, resolving [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94).
+- Claude and Codex now share dashboard density, hierarchy, disclosure, focus, ARIA, narrow-width, and light/dark design tokens while retaining provider-specific metric meanings.
+- Get AI Advice and Usage Optimizer share one exact-preview and explicit-send boundary. There is no default or background AI request, and local evidence/feedback remains bounded.
+
+The reviewed draft is `v2.3.1`; the human-controlled publish workflow stamps package metadata from that release tag.
+
 ## Codex Beta in v2.3
 
 - Codex usage records are discovered only from `sessions/**/*.jsonl` and `archived_sessions/**/*.jsonl`; credential, database, and unknown files remain excluded. Separately, the extension streams exactly `$CODEX_HOME/session_index.jsonl` to map `id` to `thread_name` for truthful thread titles. Absolute paths are redacted and titles remain memory-only. Usage-record JSONL lines are streamed and temporarily parsed only to extract allowlisted usage and structural metadata; prompt, response, command, and tool-argument fields are not inspected or used for analysis, and are never retained or persisted.
 - **Processed** means input + output, **uncached usage** means uncached input + output, **cached input** remains a subset of input, and reasoning remains a subset of output. The overview also shows input cache hit rate as cached input / input. Codex billing cost is not shown. Its first summary card is a clearly labelled API-equivalent cost estimate for the selected scope, and the All-time view shows the weekly trend on the same pricing basis; Claude / Codex / Compare keep each provider's accounting separate.
-- Codex **Today** means the current calendar day in the configured timezone. It adds exact hourly API-equivalent cost beside a separate token-composition view; daily and monthly primary charts also default to API-equivalent cost while token composition stays separately visible. Only exact known-model prices contribute, so unknown models remain unpriced and pricing coverage stays visible. The additive, schema-3-compatible hourly sidecar processes only canonical files already known to contain today, is checkpointed and resumable, and does not force a full-history reindex.
+- Codex **Today** means the current calendar day in the configured timezone. It adds exact hourly API-equivalent cost beside a separate token-composition view; daily and monthly primary charts also default to API-equivalent cost while token composition stays separately visible. Only exact known-model prices contribute, so unknown models remain unpriced and pricing coverage stays visible. The additive, schema-3-compatible hourly sidecar keeps sparse buckets for the rolling last 30 days, is checkpointed and resumable, evicts day 31, and serves date expansion without reading JSONL on click. Codex monthly charts and tables list months oldest-first.
 - Request-level attribution prefers valid `last_token_usage` components; its `total_tokens` is active-context size, not request usage. A full numeric total-plus-last signature suppresses only proven replay from the same pseudonymous rate-limit source or an immediately adjacent duplicate. Missing last snapshots fall back to cumulative lineage high-water. Upgrading triggers one automatic reindex, while the indexed subtotal remains visible throughout the pass.
-- Claude and Codex All-time / Compare views calculate historical used equivalents directly from local token logs. The newest valid official reset observation anchors one sequence of unique, non-overlapping weekly periods, so each usage event is counted once; without a usable observation, usage-only rows fall back to Monday-to-Monday UTC calendar weeks. Any overlapping, non-aligned future reset is a conflict even when its series name differs; it cannot create another current period, and period ranges are shown separately from reset times. Codex usage is stored in daily slices: when one crosses an official intraday reset, its tokens are still counted once, the affected period is labelled a boundary approximation, and only used equivalent is shown. This display rule does not change the index schema or trigger a rebuild. Codex historical periods are always used-value-only. Only the newest current period may infer a total when the reset is unambiguous and indexed usage can be attributed to one observation source; current unused value remains withheld. Multi-sign-in usage that cannot be attributed reliably also stays used-only, without inventing an account split. Current official API rates are applied consistently across history. This is a proxy, not a bill or an official subscription price. The panel is enabled by default and can be hidden in Settings with `showWeeklyEquivalentValue`. Claude records profile-scoped quota observations from this release onward.
-- Switching to Codex keeps the established Today / Month / All time / Sessions / Projects / Content / Settings structure, relabelled where Codex semantics differ. Both providers use the same render functions, HTML classes, charts, tables, spacing, and responsive rules; their time-series charts stay width-aligned while dense content scrolls inside its own region. Codex recommendations use indexed 30-day structural evidence.
+- Claude and Codex All-time / Compare views calculate historical used equivalents directly from local token logs. The newest valid official reset observation anchors one sequence of unique, non-overlapping weekly periods, so each usage event is counted once; without a usable observation, usage-only rows fall back to Monday-to-Monday UTC calendar weeks. A genuinely different quota series with an overlapping, non-aligned future reset is a conflict; same-series observations remain one series and may be shown as a low-confidence approximation. It cannot create another current period, and period ranges are shown separately from reset times. Codex usage is stored in daily slices, and an account-wide `codex` observation may decorate both historical and current buckets. If an observed reset drifts from the seven-day grid, the sample is mapped to the display period containing its observation time; file-source uncertainty, reset drift, and daily boundary crossings lower confidence and are labelled approximate. File keys are not account identities, so eligible local files in one home are included together. If local quota series overlap, the current period uses the latest real observation for a low-confidence blended estimate; ambiguous completed periods, or periods without a usable observation, stay used-only rather than inventing an account split. Any coherent observed window—including the current one—can show total and unused durability estimates; attribution or boundary uncertainty lowers confidence instead of silently replacing the values with dashes. This display rule does not change the index schema or trigger a rebuild. Current official API rates are applied consistently across history. This is a proxy, not a bill, official balance, or official subscription price. The panel is enabled by default and can be hidden in Settings with `showWeeklyEquivalentValue`. Claude records profile-scoped quota observations from this release onward.
+- Switching to Codex keeps the established Today / Last 30 days / All time / Sessions / Projects / Content / Settings structure, relabelled where Codex semantics differ. Both providers use the same render functions, HTML classes, charts, tables, spacing, and responsive rules; their time-series charts stay width-aligned while dense content scrolls inside its own region. Codex recommendations use indexed 30-day structural evidence.
 - Root tasks use the latest real thread title after path redaction. Child rows prefer their own real thread title; when it is missing, they use the reported nickname and display the parent/root title; if those are also missing, they receive a localized neutral fallback. Project names use the Git repository name, or the directory basename outside Git. The extension does not invent Branches or Workflows that cannot be measured reliably.
 - Rolling 7-day and 30-day values use exact event-day slices in the configured timezone. During an incomplete migration or rebuild, every Codex card, table, project, session, recommendation, and status value is visibly an **indexed subtotal**; unverified legacy totals are excluded. Once a Codex home is detected, its provider tab appears immediately; the page shows exact indexed-file, percentage, and byte progress during the first build, while Compare waits until both providers have real data. After the first atomic checkpoint, the complete subtotal dashboard stays usable while indexing continues; progress never replaces its cards or tables. A selected Codex home is account-agnostic, so logs left by multiple sign-ins in that same home are combined. Local logs expose no reliable account identity, so limit cards remain **last-observed** and are never summed.
 - Each recommendation presents an observation, readable evidence, and a conditional action only when the indexed 30-day structural aggregates support it; no evidence means no generic advice.
@@ -69,15 +112,41 @@ Open Settings (`Ctrl+,`) and search for **`Claude Code Usage`**. All settings ar
 - `usageLimitTracking` — show the real 5h / weekly quota indicator.
 - `showCost` / `showContext` — toggle the cost item and the context-window fill indicator (like `/context`) in the status bar.
 - Each of these status-bar items is opt-out — set `usageLimitTracking`, `showCost`, or `showContext` to `false` to hide just that one.
-- `advice.apiKey` — API key for the AI advice feature (OpenAI-compatible).
+- `advice.apiKey` — bring-your-own key shared by AI Advice and the Usage Optimizer (Anthropic or OpenAI-compatible endpoint).
 - `pauseDashboardRefresh` — pause dashboard auto-refresh (also toggleable in the dashboard header).
 
 See the [full settings table in the main README](README.md#configuration).
 
+## Local data, privacy, and known limits
+
+See [Local data and privacy](LOCAL-DATA.md) for the complete inventory,
+retention, migration, clearing, and remote-interaction contract.
+
+| Data | Local retention | Remote behavior |
+|---|---|---|
+| Source logs | Provider-owned, read-only; never copied wholesale | None by default |
+| Codex index | Bounded pseudonymous numeric/structural aggregates | None |
+| Quota history | Bounded anonymous window observations; no raw account ID | Claude quota lookup only when enabled; Codex evidence stays local |
+| UI/share state | Filters plus optional title/range and GitHub destination strings | Publish only after exact explicit confirmation |
+| Advice state/key | Bounded aggregate evidence; key only in SecretStorage | Exact previewed request only after a separate Send action |
+
+A reset absent from official/local structured evidence cannot be reconstructed.
+Ambiguous multi-login Codex history uses the latest real observation for a
+low-confidence current-period blend; ambiguous completed periods remain used-only. API-equivalent values
+depend on visible pricing coverage and are not bills. Source-log retention is
+controlled by Claude Code and Codex; explicit clear controls are the reliable
+way to remove extension-derived state.
+
 ## Troubleshooting
 
 **"No Claude Code Data"** — make sure Claude Code is installed and used at least once; check the `dataDirectory` setting (auto-detection looks at `~/.claude/projects`).
 
+**One-shot Claude CLI activity is missing** — calls made with
+`--no-session-persistence` can leave prompt history but no project transcript or
+token `usage` fields. The extension does not invent token/cost totals from that
+history. Run future audited calls without the flag if they should appear; past
+unpersisted token usage cannot be reconstructed locally.
+
 **Quota shows `5h:--% wk:--%`** — log in to the active Claude profile once.
 Credentials follow explicit `dataDirectory`, then the first valid
 `CLAUDE_CONFIG_DIR`, then `~/.claude`; the global macOS Keychain item is used
diff --git a/README-id.md b/README-id.md
index 942600be..603ef099 100644
--- a/README-id.md
+++ b/README-id.md
@@ -10,7 +10,7 @@
 
 > **ini _Bukanlah_:** alat billing. Semua angka adalah estimasi berdasarkan tarif publik per-juta-token. Rujuk ke akun Anthropic Anda untuk biaya yang sebenarnya.
 
-> Screenshot berasal dari UI berbahasa Inggris. Lihat [README utama](README.md) untuk referensi fitur lengkap.
+> Screenshot mencakup UI bahasa Inggris dan Tionghoa Sederhana. Lihat [README utama](README.md) untuk referensi lengkap.
 
 ## Screenshot
 
@@ -26,24 +26,67 @@ Arahkan kursor ke indikator kuota untuk melihat rinciannya:
 
 ![Dashboard](images/v2-dashboard-en.png)
 
+### Codex dan Perbandingan v2.3.1
+
+![Claude hari ini, Tionghoa Sederhana, tema gelap](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+![Ringkasan Codex, Tionghoa Sederhana, tema gelap](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+![Estimasi batas mingguan Codex, Inggris, tema gelap](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+![Heatmap gabungan Claude dan Codex, Inggris, tema terang](images/v2.3.1/compare-heatmap-en-light.png)
+
+Empat gambar v2.3.1 ini menggunakan renderer produksi, data sintetis, dan variabel tema VS Code Light+/Dark+, bukan bukti penggunaan pribadi atau tagihan. Instalasi VSIX native diverifikasi secara terpisah.
+
+- Codex menampilkan **token terpakai hari ini** dan **sisa kuota** secara terpisah: penggunaan mingguan 36% berarti `wk 64%`. Tooltip tetap menampilkan bilah penggunaan, waktu reset, dan catatan berbaris. Kuota berasal dari pengamatan lokal terakhir, bukan saldo langsung.
+- Detail periode tertutup secara default; pengaturan berbagi berada di bawah pratinjau. Berbagi aktif secara default dan dapat dimatikan, dengan intensitas kuantil, logaritmik, atau linear.
+- Panggilan CLI dihitung hanya jika sesi persisten menyimpan log dengan usage. Panggilan tanpa log tidak dapat dipulihkan; Hari ini dan 30 hari terakhir memakai zona waktu yang dikonfigurasi.
+
 ## Fitur
 
 - **Status bar** — biaya hari ini, biaya sesi saat ini, dan kuota 5-jam / mingguan yang sebenarnya (`5h:N% wk:N%`) dibaca dari sesi OAuth Claude Code sendiri. Tanpa konfigurasi.
-- **Tab dashboard** — Hari Ini / Bulan Ini / Sepanjang Waktu, plus **Sesi / Proyek / Konten / Branch**, semuanya bisa diurutkan.
+- **Tab dashboard** — Hari Ini / 30 Hari Terakhir / Sepanjang Waktu, plus **Sesi / Proyek / Konten / Branch**, semuanya bisa diurutkan.
 - **Grafik komposisi biaya bertumpuk** dengan sumbu Y dan garis referensi — lihat sekilas berapa banyak dari tiap hari / bulan yang terpakai untuk masukan, keluaran, cache-write, dan cache-read.
 - **Tab Konten** — memperkirakan konten mana yang menghabiskan token Anda (prompt Anda vs. hasil tool vs. output / pemikiran asisten).
-- **Saran AI** (opsional) — mengirim ringkasan penggunaan plus sampel prompt Anda ke API yang kompatibel dengan OpenAI (DeepSeek V4 Pro secara default) dan menyarankan penulisan ulang yang konkret. Gunakan API key Anda sendiri, atau pratinjau demo statis terlebih dahulu.
+- **Saran AI** (opsional) — dimulai dari bukti lokal dan tindakan yang dapat dijelaskan. Personalisasi BYOK opsional hanya memakai agregat secara default; sampel prompt memerlukan persetujuan terpisah. Permintaan lengkap dipratinjau secara persis sebelum tindakan Kirim yang terpisah, dan umpan balik berguna / tidak berguna / diterapkan tetap lokal. Saran dapat ditunda untuk waktu terbatas dan muncul kembali setelah kedaluwarsa atau secara manual.
+  Pencabutan persetujuan langsung membatalkan pratinjau dan permintaan saran yang sedang berjalan; data yang sudah terkirim tidak dapat ditarik kembali.
 - **Harga multi-vendor** — Opus 4.x / Sonnet 4.x / Haiku 4.5 diverifikasi terhadap harga publik Anthropic; tarif referensi untuk OpenAI / Gemini / DeepSeek / Kimi / GLM / Qwen dengan fallback berbasis family model. `Refresh Token Pricing` menarik data LiteLLM langsung.
 - **Personalisasi** — bahasa, zona waktu, angka desimal, angka ringkas, pengelompokan proyek, toggle penyegaran otomatis dashboard.
 
+## Yang baru di v2.3.1
+
+- Metadata harga dan konteks yang tepat kini mencakup **GPT-6 Astra**
+  (`gpt-6-astra`, konteks 1,05 juta token) serta **Claude Fable 5.1 / Mythos
+  5.1** (`claude-fable-5-1` / `claude-mythos-5-1`, konteks 1 juta token).
+  Fable 5.1 memakai tarif baca cache khusus `$0.25 / juta token` tanpa mengubah
+  riwayat Fable 5. Nilai ekuivalen API GPT-6 memakai tarif Standard resmi untuk
+  konteks pendek. Biaya tambahan untuk seluruh permintaan di atas 272K input
+  tidak disertakan karena log agregat lokal tidak dapat memastikan ambang per
+  permintaan tersebut.
+- Estimasi Claude dapat memakai tarif langsung Anthropic atau tarif on-demand
+  AWS Bedrock in-region untuk keluarga Opus, Sonnet, dan Haiku saat ini.
+  Mengganti backend langsung menghitung ulang log yang tidak berubah; Sonnet 5
+  memakai tarif standar setelah promosi peluncurannya berakhir 31 Agustus 2026.
+- 30 hari terakhir berarti hari ini dan 29 tanggal sebelumnya dalam zona waktu konfigurasi. Total dapat direkonsiliasi, refresh berulang stabil, dan bulan tampil dari lama ke baru. Ringkasan Workflows Claude memakai rentang bergulir yang sama dan memasukkan setiap eksekusi berdasarkan tanggal mulai di zona waktu konfigurasi. Saat metrik grafik diganti atau label drill-down dirender, kunci penggunaan harian/bulanan tidak lagi mundur sehari atau sebulan akibat zona waktu host. Tanggal berakhirnya penundaan Saran AI dan Usage Optimizer juga memakai zona waktu konfigurasi dan bahasa UI.
+- Reasoning effort terstruktur tidak ditebak dari nama model. `unknown` bukan nol dijelaskan; nilai nol disembunyikan.
+- Pengamatan kuota anonim yang terbatas mempertahankan reset tidak teratur dan pada hari yang sama. Fraksi valid dalam satu jendela menghasilkan estimasi total dan sisa daya tahan langganan, termasuk periode berjalan. Bukti perkiraan atau tanpa atribusi diberi keyakinan rendah. Jika series kuota Codex lokal tumpang tindih, periode berjalan memakai pengamatan nyata terbaru untuk estimasi gabungan berkeyakinan rendah; periode selesai yang atribusinya ambigu tetap hanya menampilkan nilai terpakai.
+- Perbandingan menampilkan heatmap aktivitas gabungan Claude + Codex dari agregat harian yang sudah ada dan tetap berfungsi dengan satu penyedia.
+- Studio berbagi yang mengutamakan pratinjau mencakup SVG lokal deterministik, kartu, Markdown, judul/rentang, pratinjau privasi, dan warna yang dapat disesuaikan. Academic Violet menjadi default; pemetaan intensitas dapat memakai kuantil (default), logaritmik, atau linear. Publikasi GitHub publik mengonfirmasi tujuan tepat secara terpisah.
+- Komposisi Token Codex sekarang menampilkan **penggunaan tanpa cache** (input tanpa cache + output) di atas stack input tanpa cache / input cache / output yang tidak tumpang tindih; reasoning tetap merupakan bagian dari output.
+- Codex tetap dapat digulir dengan mulus saat pengindeksan: status gulir disimpan sekali setelah gerakan selesai dan progres indeks langsung hanya memperbarui teks tanpa membangun ulang halaman. Ringkasan hijau per model kini mengikuti makna Claude, yaitu harga ekuivalen API untuk model yang cocok tepat beserta cakupan harga. Model tak dikenal menampilkan `—`, sedangkan effort tetap memakai nilai Token tanpa cache berwarna netral.
+- Permintaan Optimizer yang kompatibel dengan OpenAI kini hanya mengirim `reasoning_effort` tanpa parameter tingkat atas `thinking` yang tidak didukung, menyelesaikan [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94).
+- Claude/Codex berbagi token desain untuk kepadatan, hierarki, fokus, ARIA, lebar sempit, serta tema terang/gelap tanpa menyamakan arti metrik.
+
+Draft Release yang ditinjau adalah `v2.3.1`; alur publikasi manual menetapkan versi paket dari tag tersebut.
+
 ## Codex Beta di v2.3
 
 - Catatan penggunaan Codex hanya ditemukan dari `sessions/**/*.jsonl` dan `archived_sessions/**/*.jsonl`; file kredensial, database, dan file tak dikenal tetap dikecualikan. Secara terpisah, ekstensi hanya melakukan streaming terhadap `$CODEX_HOME/session_index.jsonl` untuk memetakan `id` ke `thread_name` bagi judul thread yang sebenarnya. Jalur absolut dalam judul disamarkan dan judul hanya disimpan di memori. Setiap baris JSONL penggunaan di-stream dan diparse sementara hanya untuk mengambil metadata penggunaan dan struktur dalam daftar izin; field prompt, respons, perintah, dan argumen alat tidak diperiksa atau dipakai untuk analisis, serta tidak pernah disimpan atau dipersistenkan.
 - **Diproses** = input + output, **Penggunaan tanpa cache** = Input tanpa cache + output, **cached input** tetap bagian dari input, dan reasoning bagian dari output. Ringkasan juga menampilkan tingkat hit cache input sebagai cached input / input. Biaya tagihan Codex tidak ditampilkan. Kartu ringkasan pertama menampilkan estimasi biaya ekuivalen API untuk cakupan terpilih dengan label yang jelas, sedangkan tampilan Sepanjang Waktu menunjukkan tren mingguan dengan dasar harga yang sama. Claude / Codex / Compare tetap memisahkan makna tiap penyedia.
-- **Hari Ini** pada Codex berarti hari kalender saat ini dalam zona waktu yang dikonfigurasi. Tampilan ini menambahkan biaya ekuivalen API per jam yang tepat di samping tampilan komposisi Token yang terpisah. Grafik utama harian dan bulanan juga memakai biaya ekuivalen API sebagai default, sementara komposisi Token tetap tersedia secara terpisah. Hanya harga model yang dikenal dan cocok tepat yang dihitung; model tak dikenal tetap tanpa harga dan cakupan harga selalu terlihat. Sidecar per jam yang bersifat tambahan dan kompatibel dengan schema 3 hanya memproses file canonical yang sudah diketahui memuat penggunaan hari ini, dapat dilanjutkan dari checkpoint, dan tidak memicu pengindeksan ulang seluruh riwayat.
+- **Hari Ini** pada Codex berarti hari kalender saat ini dalam zona waktu yang dikonfigurasi. Tampilan ini menambahkan biaya ekuivalen API per jam yang tepat di samping tampilan komposisi Token yang terpisah. Grafik utama harian dan bulanan juga memakai biaya ekuivalen API sebagai default, sementara komposisi Token tetap tersedia secara terpisah. Hanya harga model yang dikenal dan cocok tepat yang dihitung; model tak dikenal tetap tanpa harga dan cakupan harga selalu terlihat. Sidecar per jam yang bersifat tambahan dan kompatibel dengan schema 3 menyimpan bucket tanggal / jam yang jarang untuk 30 hari bergulir, mendukung checkpoint dan resume, membuang hari ke-31, dan membuka tanggal tanpa membaca JSONL. Grafik dan tabel bulanan Codex menampilkan bulan dari yang paling lama ke yang terbaru.
 - Atribusi Token per permintaan memprioritaskan component `last_token_usage` yang valid; `total_tokens` di dalamnya adalah ukuran konteks aktif, bukan penggunaan permintaan. Signature numerik lengkap total-plus-last hanya menghapus replay yang terbukti berasal dari sumber rate-limit pseudonim yang sama atau record yang tepat bersebelahan. Jika last snapshot tidak ada, parser kembali ke cumulative lineage high-water. Setelah upgrade, indeks dibangun ulang otomatis satu kali dan subtotal terindeks tetap terlihat selama prosesnya.
-- Tampilan Sepanjang Waktu / Perbandingan Claude dan Codex menghitung ekuivalen terpakai historis langsung dari log Token lokal. Pengamatan reset resmi terbaru yang valid menjadi satu jangkar bagi rangkaian periode mingguan yang unik dan tidak tumpang tindih, sehingga setiap peristiwa penggunaan hanya dihitung dalam satu periode. Jika tidak ada pengamatan yang dapat dipakai, riwayat khusus pemakaian kembali ke minggu kalender UTC Senin-ke-Senin. Reset masa depan yang tumpang tindih tetapi tidak selaras dianggap konflik meskipun nama series berbeda; reset itu tidak dapat membuat periode berjalan kedua. Rentang periode dan waktu reset ditampilkan terpisah. Penggunaan Codex disimpan sebagai irisan harian. Bila suatu irisan melewati reset resmi di tengah hari, Token tetap dihitung satu kali, periode terdampak diberi label 「perkiraan batas」, dan hanya ekuivalen terpakai yang ditampilkan tanpa menyimpulkan total batas atau sisa. Aturan tampilan ini tidak mengubah schema indeks dan tidak memicu pembangunan ulang. Periode historis Codex selalu hanya menampilkan nilai terpakai. Hanya periode berjalan terbaru yang boleh memperkirakan total batas bila reset tidak berkonflik dan penggunaan terindeks dapat diatribusikan dengan andal ke satu sumber pengamatan; nilai sisa periode berjalan tetap tidak ditampilkan sebagai kesimpulan. Penggunaan dari beberapa login yang tidak dapat diatribusikan juga tetap hanya menampilkan nilai terpakai tanpa mengarang pemisahan akun. Harga API resmi saat ini diterapkan konsisten pada riwayat. Ini proksi, bukan tagihan atau harga langganan resmi. Panel ini aktif secara default dan dapat disembunyikan di Settings dengan `showWeeklyEquivalentValue`. Claude mulai merekam pengamatan batas per profil sejak rilis ini.
-- Beralih ke Codex tetap memakai struktur Hari Ini / Bulan Ini / Sepanjang Waktu / Sesi / Proyek / Konten / Settings yang sudah ada, dengan label yang disesuaikan pada makna Codex. Kedua penyedia memakai render function, HTML class, grafik, tabel, jarak, dan aturan responsif yang sama; grafik deret waktunya tetap sejajar lebarnya, sedangkan konten padat hanya bergulir di areanya sendiri. Rekomendasi Codex memakai bukti struktural 30 hari yang telah diindeks.
+- Tampilan Sepanjang Waktu / Perbandingan Claude dan Codex menghitung ekuivalen terpakai historis langsung dari log Token lokal. Pengamatan reset resmi terbaru yang valid menjadi jangkar bagi rangkaian periode mingguan yang unik dan tidak tumpang tindih, sehingga setiap peristiwa penggunaan hanya dihitung dalam satu periode. Jika tidak ada pengamatan yang dapat dipakai, riwayat khusus pemakaian kembali ke minggu kalender UTC Senin-ke-Senin. Pengamatan dari series yang sama tetap menjadi satu series dan dapat ditampilkan sebagai perkiraan berkeyakinan rendah tanpa membuat periode berjalan kedua. Pengamatan account-wide `codex` dapat menghias periode historis dan berjalan; pergeseran reset, ketidakpastian sumber file, atau batas irisan harian menurunkan keyakinan. Kunci file bukan identitas akun, sehingga file lokal yang memenuhi syarat dalam satu home dipakai bersama. Jika series kuota lokal tumpang tindih, periode berjalan memakai pengamatan nyata terbaru untuk estimasi gabungan berkeyakinan rendah. Periode selesai yang atribusinya ambigu atau periode tanpa pengamatan tetap hanya menampilkan ekuivalen terpakai tanpa mengarang pemisahan akun. Setiap periode teramati yang konsisten, termasuk periode berjalan, dapat menampilkan estimasi total dan sisa daya tahan; ketidakpastian atribusi atau batas menurunkan keyakinan alih-alih menyembunyikan nilainya. Aturan tampilan ini tidak mengubah schema indeks dan tidak memicu pembangunan ulang. Harga API resmi saat ini diterapkan konsisten pada riwayat. Ini proksi, bukan tagihan, saldo resmi, atau harga langganan resmi. Panel ini aktif secara default dan dapat disembunyikan di Settings dengan `showWeeklyEquivalentValue`. Claude mulai merekam pengamatan batas per profil sejak rilis ini.
+- Beralih ke Codex tetap memakai struktur Hari Ini / 30 Hari Terakhir / Sepanjang Waktu / Sesi / Proyek / Konten / Settings yang sudah ada, dengan label yang disesuaikan pada makna Codex. Kedua penyedia memakai render function, HTML class, grafik, tabel, jarak, dan aturan responsif yang sama; grafik deret waktunya tetap sejajar lebarnya, sedangkan konten padat hanya bergulir di areanya sendiri. Rekomendasi Codex memakai bukti struktural 30 hari yang telah diindeks.
 - Tugas utama memakai judul thread nyata terbaru setelah jalur disamarkan. Baris tugas anak memprioritaskan judul thread nyatanya sendiri; jika tidak ada, baris memakai nama panggilan yang dilaporkan sambil menampilkan judul induk / tugas utama. Jika informasi itu juga tidak ada, baris memakai nama pengganti netral yang dilokalkan. Nama proyek memakai nama repositori Git, atau nama folder di luar Git. Ekstensi tidak mengarang Branches atau Workflows yang tidak dapat dihitung secara andal.
 - Nilai 7 dan 30 hari memakai irisan tepat berdasarkan hari peristiwa di zona waktu yang dikonfigurasi. Saat migrasi atau pembangunan ulang belum selesai, setiap kartu, tabel, proyek, sesi, rekomendasi, dan nilai status Codex ditandai sebagai **subtotal terindeks**, sementara total lama yang belum diverifikasi dikecualikan. Setelah Codex home terdeteksi, tab penyedianya langsung ditampilkan; selama indeks pertama dibuat, jumlah file terindeks yang tepat, persentase, dan progres kapasitas tampil langsung di halaman, sedangkan Perbandingan menunggu hingga kedua penyedia memiliki data nyata. Setelah checkpoint atomik pertama dibuat, seluruh dasbor subtotal tetap dapat digunakan saat pengindeksan berlanjut; indikator progres tidak menggantikan kartu atau tabel. Codex home yang dipilih tidak membedakan akun, jadi log dari beberapa login di home yang sama digabung. Log lokal tidak memiliki identitas akun yang andal; kartu batas tetap **terakhir diamati** dan tidak dijumlahkan.
 - Setiap rekomendasi hanya menampilkan pengamatan, bukti yang mudah dibaca, dan tindakan bersyarat bila agregat struktural 30 hari yang telah diindeks mendukungnya. Tanpa bukti, tidak ada saran umum.
@@ -68,11 +111,30 @@ Buka Settings (`Ctrl+,`) dan cari **`Claude Code Usage`**. Semua pengaturan bers
 - `usageLimitTracking` — tampilkan indikator kuota 5 jam / mingguan yang sebenarnya.
 - `showCost` / `showContext` — nyalakan/matikan item biaya dan indikator pengisian jendela konteks (seperti `/context`) di status bar.
 - Setiap item status bar ini bisa dimatikan sendiri — atur `usageLimitTracking`, `showCost`, atau `showContext` ke `false` untuk menyembunyikan salah satunya saja.
-- `advice.apiKey` — API key untuk fitur saran AI (kompatibel dengan OpenAI).
+- `advice.apiKey` — API key milik pengguna yang dipakai bersama oleh Saran AI dan Usage Optimizer (endpoint Anthropic atau kompatibel OpenAI).
 - `dashboardAutoRefresh` — nyalakan/matikan penyegaran otomatis dashboard (bisa juga di-toggle di header dashboard).
 
 Lihat [tabel pengaturan lengkap di README utama](README.md#configuration).
 
+## Data lokal, privasi, dan batasan
+
+Lihat [Local data and privacy](LOCAL-DATA.md) untuk inventaris lengkap,
+retensi, migrasi, penghapusan, dan batas interaksi jarak jauh.
+
+| Data | Retensi lokal | Perilaku jarak jauh |
+|---|---|---|
+| Log sumber | Milik penyedia, hanya-baca, tidak disalin utuh | Tidak ada secara default |
+| Indeks Codex | Agregat numerik/struktur pseudonim yang terbatas | Tidak ada |
+| Riwayat kuota | Pengamatan jendela anonim terbatas, tanpa ID akun mentah | Hanya kuota Claude saat aktif; Codex tetap lokal |
+| UI/berbagi | Filter serta judul/rentang/tujuan GitHub opsional | Publikasi hanya setelah konfirmasi tepat |
+| Saran/kunci | Bukti agregat terbatas; kunci hanya di SecretStorage | Hanya permintaan yang dipratinjau persis setelah tindakan Kirim terpisah |
+
+Reset tanpa bukti terstruktur tidak dapat direkonstruksi. Riwayat beberapa login
+yang ambigu memakai pengamatan nyata terbaru untuk estimasi gabungan periode berjalan
+berkeyakinan rendah; periode selesai tetap hanya menampilkan nilai terpakai. Nilai ekuivalen API bukan
+tagihan. Retensi log sumber dikelola Claude Code/Codex; kontrol hapus eksplisit
+adalah cara andal menghapus state turunan ekstensi.
+
 ## Pemecahan masalah
 
 **"No Claude Code Data"** — pastikan Claude Code sudah terpasang dan pernah dipakai minimal sekali; periksa pengaturan `dataDirectory` (deteksi otomatis mencari di `~/.claude/projects`).
diff --git a/README-ja.md b/README-ja.md
index ede16bdd..5ec8ebd9 100644
--- a/README-ja.md
+++ b/README-ja.md
@@ -10,7 +10,7 @@
 >
 > **これは何ではないか**：請求ツールではありません。表示される金額はすべて公開のトークン単価に基づく見積もりです。実際の請求は Anthropic アカウントをご確認ください。
 
-> スクリーンショットは英語 UI のものです。全機能の詳細は[メイン README](README.md) を参照してください。
+> スクリーンショットには英語と簡体字中国語を使用しています。詳細は[メイン README](README.md) を参照してください。
 
 ## スクリーンショット
 
@@ -26,24 +26,67 @@
 
 ![ダッシュボード](images/v2-dashboard-en.png)
 
+### v2.3.1 Codex と比較
+
+![Claude 本日、簡体字中国語、ダークテーマ](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+![Codex 概要、簡体字中国語、ダークテーマ](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+![Codex 週間枠推定、英語、ダークテーマ](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+![Claude と Codex の統合ヒートマップ、英語、ライトテーマ](images/v2.3.1/compare-heatmap-en-light.png)
+
+上の4枚は本番ダッシュボードのレンダラー、合成データ、VS Code Light+/Dark+ のテーマ変数から生成しています。個人の使用量や請求の証拠ではありません。ネイティブ VSIX のインストールは別途検証します。
+
+- Codex は**本日の使用済みトークン**と**残りクォータ**を別表示します。週の使用率が36%なら `wk 64%`。ツールチップには使用率バー、リセット時刻、折り返した説明を表示します。クォータは最後のローカル観測であり、リアルタイム残高ではありません。
+- 期間詳細は初期状態で折りたたみ、共有設定はプレビューの下に配置。共有は既定で有効、無効化も可能です。色の強度は分位数・対数・線形から選択できます。
+- CLI の計上には usage を含む永続セッションログが必要です。未保存の呼び出しは復元できません。本日と過去30日は設定タイムゾーンを使用します。
+
 ## 主な機能
 
 - **ステータスバー** — 本日のコスト、現在のセッションのコスト、そして Claude Code 自身の OAuth セッションから読み取る実際の 5 時間 / 週間クォータ（`5h:N% wk:N%`）。設定不要。
-- **ダッシュボードタブ** — 今日 / 今月 / 全期間 に加え、**Sessions / Projects / Content / Branches**。すべて並べ替え可能。
+- **ダッシュボードタブ** — 今日 / 直近 30 日 / 全期間 に加え、**Sessions / Projects / Content / Branches**。すべて並べ替え可能。
 - **積み上げコスト構成チャート**（Y 軸と参照線付き）— 各日 / 各月のコストが入力・出力・キャッシュ書き込み・キャッシュ読み取りにどれだけ使われたか一目で分かります。
 - **Content タブ** — どの内容がトークンを消費しているか（あなたのプロンプト vs ツール結果 vs アシスタント出力 / 思考）を推定。
-- **AI アドバイス**（任意）— 使用量サマリーと最近のプロンプトのサンプルを OpenAI 互換 API（デフォルト DeepSeek V4 Pro）に送り、具体的な書き換えを提案。キーは自分で用意、または静的デモを先にプレビュー可能。
+- **AI アドバイス**（任意）— まずローカルの根拠と説明可能な行動を示します。BYOK による任意のパーソナライズは集計値のみが既定で、プロンプト例には別の同意が必要です。完全なリクエストを正確にプレビューしてから、別の送信操作を行います。有用 / 不要 / 適用済みのフィードバックはローカルだけに残り、提案は期間限定で保留して期限後または手動で再表示できます。
+  同意を撤回するとプレビューは直ちに無効となり、実行中のアドバイス要求をキャンセルします。送信済みのデータは取り戻せません。
 - **マルチベンダー価格** — Opus 4.x / Sonnet 4.x / Haiku 4.5 は Anthropic 公式価格で検証済み。OpenAI / Gemini / DeepSeek / Kimi / GLM / Qwen の参考価格（ファミリー認識フォールバック付き）。`Refresh Token Pricing` で LiteLLM の最新価格を取得。
 - **パーソナライズ** — 言語、タイムゾーン、小数点桁数、コンパクト数値、プロジェクトのグループ化、ダッシュボード自動更新の切り替え。
 
+## v2.3.1 の新機能
+
+- 正確な料金とコンテキスト情報が **GPT-6 Astra**（`gpt-6-astra`、
+  105 万トークン）および **Claude Fable 5.1 / Mythos 5.1**
+  （`claude-fable-5-1` / `claude-mythos-5-1`、100 万トークン）に対応しました。
+  Fable 5.1 は専用のキャッシュ読み取り料金 `$0.25 / 100 万トークン` を使い、
+  従来の Fable 5 履歴は変更しません。GPT-6 の API 相当額には公式 Standard
+  の短コンテキスト料金を使用します。ローカル集計ログでは各リクエストが
+  272K 入力を超えたか判定できないため、その場合のリクエスト全体への追加料金は
+  含めません。
+- Claude の見積もりでは、Anthropic 直接料金または AWS Bedrock の in-region
+  オンデマンド料金を選択でき、現行の Opus・Sonnet・Haiku 系列を対象にします。
+  切り替えると未変更のログも直ちに再計算され、Sonnet 5 には 2026 年 8 月 31 日の
+  開始記念価格終了後の標準料金を使用します。
+- 直近 30 日は設定タイムゾーンの今日と過去 29 日です。合計は照合可能で、再更新は安定し、月は古い順に表示します。Claude の Workflows サマリーも同じローリング範囲を使い、設定タイムゾーンでの開始日に基づいて各実行を集計します。チャート指標の切り替えやドリルダウンラベルの表示でも、日／月の使用量キーがホストのタイムゾーンによって前日・前月へずれることはありません。AI アドバイスと Usage Optimizer の保留期限も、設定タイムゾーンと UI 言語で表示します。
+- 構造化 reasoning effort をモデル名から推測しません。非ゼロの `unknown` は理由を示し、ゼロは表示しません。
+- 上限付き匿名クォータ観測が不規則・同日リセットを保持します。有効な同一ウィンドウの割合から、現在期間を含む総枠と未使用分の耐久性推定を表示します。近似・未帰属は低信頼度です。ローカルの Codex クォータ系列が重複していても、現在期間は最新の実測値による低信頼度の混合推定を表示し、帰属が曖昧な完了期間だけを使用済み表示に留めます。
+- 比較タブは既存の日次集計から Claude + Codex 統合活動ヒートマップを表示し、単一プロバイダーでも機能します。
+- プレビュー優先の共有スタジオは、決定的ローカル SVG、共有カード、Markdown、タイトル/範囲、プライバシープレビュー、調整可能な色に対応します。Academic Violet が既定で、強度マッピングは分位数（既定）、対数、線形から選べます。公開 GitHub 送信は正確な宛先を別途確認します。
+- Codex の Token 構成は、重複しない「非キャッシュ入力 / キャッシュ入力 / 出力」スタックの上に **非キャッシュ使用量**（非キャッシュ入力 + 出力）を明示します。推論は引き続き出力の部分集合です。
+- Codex はインデックス作成中も滑らかにスクロールします。スクロール状態は操作後に一度だけ保存され、ライブ進捗はページ全体を再構築せずテキストだけを更新します。モデル別の緑色サマリーは Claude と同じ意味になり、完全一致モデルの API 等価コストと価格カバレッジを表示します。未知モデルは `—`、effort は中立色の非キャッシュ Token 表示です。
+- OpenAI 互換の Optimizer リクエストは `reasoning_effort` のみを送り、未対応のトップレベル `thinking` を送信しないため、[#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94) を解決します。
+- Claude/Codex は密度、階層、フォーカス、ARIA、狭幅、明暗テーマの token を共有しつつ、指標の意味は分離します。
+
+レビュー済み Release ドラフトは `v2.3.1` です。手動公開ワークフローが、その tag からパッケージ版を設定します。
+
 ## v2.3 Codex Beta
 
 - Codex の使用量レコードは `sessions/**/*.jsonl` と `archived_sessions/**/*.jsonl` からだけ検出し、認証情報、DB、未知のファイルは対象外です。これとは別に、`$CODEX_HOME/session_index.jsonl` だけをストリームで読み込み、実際のスレッド名に使う `id` → `thread_name` の対応を取得します。名前に含まれる絶対パスは伏せ、名前はメモリ内だけに保持します。使用量 JSONL の各行は、許可リスト内の使用量・構造メタデータを抽出するためだけにストリーム処理で一時解析します。プロンプト、応答、コマンド、ツール引数の各フィールドは参照も分析利用もせず、保持・永続化もしません。
 - **処理済み** = 入力 + 出力、**非キャッシュ使用量** = 非キャッシュ入力 + 出力、**キャッシュ入力**は入力の部分集合、reasoning は出力の部分集合です。概要には「キャッシュ入力 / 入力」による入力キャッシュヒット率も表示します。Codex の請求コストは表示しません。先頭のサマリーカードには選択範囲の API 等価コスト推定を明示し、全期間ビューには同じ単価基準の週間推移を表示します。Claude / Codex / Compare は各プロバイダーの集計方法を分けて扱います。
-- Codex の**今日**は、設定したタイムゾーンの現在の暦日です。正確な時間別 API 等価コストを表示し、Token 構成は独立したビューとして残します。日別・月別のメインチャートも API 等価コストを既定表示にし、Token 構成は別に確認できます。正確に一致する既知モデルだけを価格計算に含めるため、未知モデルは価格未設定のままで、価格カバレッジは常に表示されます。schema 3 と互換性のある追加型の時間別 sidecar は、今日の使用を含むことが既に分かっている canonical ファイルだけを対象とし、checkpoint 保存と再開に対応します。全履歴の再インデックスは発生させません。
+- Codex の**今日**は、設定したタイムゾーンの現在の暦日です。正確な時間別 API 等価コストを表示し、Token 構成は独立したビューとして残します。日別・月別のメインチャートも API 等価コストを既定表示にし、Token 構成は別に確認できます。正確に一致する既知モデルだけを価格計算に含めるため、未知モデルは価格未設定のままで、価格カバレッジは常に表示されます。schema 3 と互換性のある追加型の時間別 sidecar は、直近 30 日の疎な日付 / 時間バケットを保持し、checkpoint 保存と再開、31 日目の削除に対応します。日付を展開しても JSONL は読みません。Codex の月別チャートと表は古い月から順に表示します。
 - リクエスト単位の Token 帰属では、有効な `last_token_usage` の各 component を優先します。その `total_tokens` はアクティブなコンテキスト量であり、リクエスト使用量ではありません。total と last の完全な数値署名により、同じ仮名化 rate-limit ソースまたは直前の隣接レコードの再生を証明できる場合だけ除外します。last snapshot がない場合は cumulative lineage high-water にフォールバックします。アップグレード後はインデックスを一度自動再構築し、その間もインデックス済み小計を表示します。
-- Claude と Codex の全期間 / 比較ビューは、ローカル Token ログから過去の使用済み等価値を直接計算します。最新の有効な公式リセット観測を基準に、一意で重複しない週間期間の列を作り、各使用イベントは一つの期間にだけ数えます。利用できる観測がなければ、使用分のみの履歴を UTC の月曜から月曜の暦週にフォールバックします。系列名が異なっていても、重複して整合しない将来リセットは競合として扱い、二つ目の「現在の期間」を作りません。期間範囲とリセット時刻は分けて表示します。Codex の使用量は日単位のスライスで保存されます。スライスが公式の日中リセットをまたぐ場合も Token は一度だけ数え、影響する期間を「境界近似」と表示し、使用済み等価値だけを示して総上限や未使用分を逆算しません。この表示規則はインデックス schema を変更せず、再構築も発生させません。Codex の過去期間は常に使用済み値だけを表示します。最新の現在期間に限り、リセット競合がなく、インデックス済み使用量を単一の観測元へ確実に帰属できる場合だけ総上限を推定でき、現在の未使用値は結論として示しません。帰属できない複数ログインの使用量も使用済み値だけとし、架空のアカウント分割は行いません。履歴には現在の公式 API 単価を一貫して適用します。これは請求額や公式のサブスクリプション価格ではなく代理推定です。このパネルは既定で有効で、設定の `showWeeklyEquivalentValue` から非表示にできます。Claude はこのリリースからプロファイル別に上限観測を記録します。
-- Codex に切り替えても、既存の今日 / 今月 / 全期間 / セッション / プロジェクト / コンテンツ / 設定の構成を維持し、Codex の意味に合わせてラベルだけを調整します。両プロバイダーは同じ render function、HTML class、チャート、表、余白、レスポンシブルールを使います。時系列チャートの幅は揃い、密な内容だけが各領域内でスクロールします。Codex の提案はインデックス済み 30 日間の構造的根拠を使います。
+- Claude と Codex の全期間 / 比較ビューは、ローカル Token ログから過去の使用済み等価値を直接計算します。最新の有効な公式リセット観測を基準に、一意で重複しない週間期間の列を作り、各使用イベントは一つの期間にだけ数えます。利用できる観測がなければ、使用分のみの履歴を UTC の月曜から月曜の暦週にフォールバックします。同じ quota series の観測は一つの series のまま、低信頼度の近似として表示でき、二つ目の「現在の期間」は作りません。Codex の account-wide `codex` 観測は過去と現在の期間の両方を装飾でき、リセット時刻のずれ、ファイルソース、日次境界越えは信頼度を下げます。ファイルキーはアカウント ID ではないため、同じ home の対象ファイルをまとめて扱います。ローカルの quota series が重複していても、現在期間は最新の実測値による低信頼度の混合推定を表示します。帰属が曖昧な完了期間、または観測のない期間は使用済み等価値だけを表示し、アカウント分割を作りません。一貫した観測期間は現在期間を含めて総枠と未使用分の耐久性推定を表示でき、帰属や境界が不確かな場合は値を隠さず信頼度を下げます。この表示規則はインデックス schema を変更せず、再構築も発生させません。履歴には現在の公式 API 単価を一貫して適用します。これは請求額、公式残高、公式のサブスクリプション価格ではなく代理推定です。このパネルは既定で有効で、設定の `showWeeklyEquivalentValue` から非表示にできます。Claude はこのリリースからプロファイル別に上限観測を記録します。
+- Codex に切り替えても、既存の今日 / 直近 30 日 / 全期間 / セッション / プロジェクト / コンテンツ / 設定の構成を維持し、Codex の意味に合わせてラベルだけを調整します。両プロバイダーは同じ render function、HTML class、チャート、表、余白、レスポンシブルールを使います。時系列チャートの幅は揃い、密な内容だけが各領域内でスクロールします。Codex の提案はインデックス済み 30 日間の構造的根拠を使います。
 - ルートタスクには、絶対パスを伏せた最新の実際のスレッド名を使います。子タスクは自身の実際のスレッド名を優先し、ない場合は報告されたニックネームを使って親 / ルートタスク名も表示します。それらもない場合はローカライズ済みの中立的な代替名を表示します。プロジェクト名は Git リポジトリ名、Git 外ではフォルダー名です。信頼できる集計ができない Branches や Workflows は作り上げません。
 - 過去 7 日 / 30 日は、設定したタイムゾーンでイベント発生日を正確に区切ります。移行または再構築中は、Codex のカード、表、プロジェクト、セッション、提案、ステータス値を**インデックス済み小計**として明示し、未検証の旧集計値を除外します。Codex home を検出するとプロバイダータブを直ちに表示し、初回インデックス中はページ内に正確なインデックス済みファイル数、割合、容量の進捗をリアルタイム表示します。「比較」は両プロバイダーに実データが揃ってから表示します。最初のアトミックチェックポイント生成後は、インデックス処理が続いていても小計ダッシュボード全体を利用でき、進捗表示がカードや表に置き換わることはありません。選択した Codex home はアカウントを区別しないため、同じ home に複数のログインが残したログは合算されます。ローカルログには信頼できるアカウント識別子がないため、上限カードは**最終観測**のままで合算しません。
 - 各提案は、インデックス済み 30 日間の構造集計に根拠がある場合だけ、観測、読みやすい根拠、条件付きアクションを示します。根拠がなければ一般論を生成しません。
@@ -69,11 +112,27 @@ Cursor / Windsurf 向けに [Open VSX Registry](https://open-vsx.org/extension/G
 - `usageLimitTracking` — 実際の 5 時間 / 週間クォータ表示。
 - `showCost` / `showContext` — ステータスバーのコスト表示と、コンテキストウィンドウ使用率（`/context` 風）の切り替え。
 - これらのステータスバー項目は個別に非表示にできます。`usageLimitTracking` / `showCost` / `showContext` を `false` にすると、その項目だけ消えます。
-- `advice.apiKey` — AI アドバイス機能の API キー（OpenAI 互換）。
+- `advice.apiKey` — AI アドバイスと Usage Optimizer で共有する持ち込み API キー（Anthropic または OpenAI 互換エンドポイント）。
 - `pauseDashboardRefresh` — ダッシュボードの自動更新を一時停止（ダッシュボードのヘッダーでも切り替え可能）。
 
 設定の全一覧は[メイン README](README.md#configuration) を参照。
 
+## ローカルデータ、プライバシー、制限
+
+完全な一覧、保持、移行、消去、通信境界は
+[Local data and privacy](LOCAL-DATA.md)（[中文](LOCAL-DATA.zh-CN.md)）を参照してください。
+
+| データ | ローカル保持 | リモート動作 |
+|---|---|---|
+| ソースログ | プロバイダー所有・読み取り専用、丸ごと複製しない | 既定なし |
+| Codex インデックス | 上限付き仮名化数値/構造集計 | なし |
+| クォータ履歴 | 上限付き匿名ウィンドウ観測、元アカウント ID なし | 有効時の Claude クォータ取得のみ。Codex はローカル |
+| UI/共有 | フィルター、任意のタイトル/範囲/GitHub 宛先文字列 | 正確な確認後だけ公開 |
+| アドバイス/鍵 | 上限付き集計証拠。鍵は SecretStorage のみ | 別の送信操作後だけ正確にプレビューした要求 |
+
+構造化証拠にないリセットは復元できません。複数ログインの帰属が曖昧な場合、現在期間は最新の実測値による低信頼度の混合推定を表示し、完了期間は使用済みのみです。
+API 等価値は請求額ではありません。ソースログの保持は Claude Code/Codex が管理し、派生状態は明示消去が確実です。
+
 ## トラブルシューティング
 
 **「No Claude Code Data」** — Claude Code がインストールされ、少なくとも一度使用されていることを確認。`dataDirectory` 設定を確認（自動検出は `~/.claude/projects` を参照）。
diff --git a/README-ko.md b/README-ko.md
index 0520408a..3e452860 100644
--- a/README-ko.md
+++ b/README-ko.md
@@ -10,7 +10,7 @@
 >
 > **무엇이 아닌가**: 청구 도구가 아닙니다. 표시되는 모든 금액은 공개된 100만 토큰당 단가 기준 추정치입니다. 실제 청구는 Anthropic 계정을 확인하세요.
 
-> 스크린샷은 영어 UI 기준입니다. 전체 기능 설명은 [메인 README](README.md)를 참고하세요.
+> 스크린샷에는 영어와 중국어 간체 UI가 포함됩니다. 전체 기능 설명은 [메인 README](README.md)를 참고하세요.
 
 ## 스크린샷
 
@@ -26,24 +26,67 @@
 
 ![대시보드](images/v2-dashboard-en.png)
 
+### v2.3.1 Codex 및 비교
+
+![Claude 오늘, 중국어 간체, 어두운 테마](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+![Codex 개요, 중국어 간체, 어두운 테마](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+![Codex 주간 한도 추정, 영어, 어두운 테마](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+![Claude와 Codex 통합 히트맵, 영어, 밝은 테마](images/v2.3.1/compare-heatmap-en-light.png)
+
+위 4장은 실제 대시보드 렌더러, 합성 데이터, VS Code Light+/Dark+ 테마 변수로 생성했습니다. 개인 사용량이나 청구 증거가 아니며, 네이티브 VSIX 설치는 별도로 검증합니다.
+
+- Codex는 **오늘 사용한 토큰**과 **남은 쿼터**를 따로 표시합니다. 주간 사용률 36%이면 `wk 64%`입니다. 툴팁에는 사용률 막대, 초기화 시각, 줄바꿈 설명이 유지됩니다. 쿼터는 마지막 로컬 관측이며 실시간 잔액이 아닙니다.
+- 기간 상세는 기본으로 접고 공유 설정은 미리보기 아래에 둡니다. 공유는 기본 활성화이며 끌 수 있고, 색 강도는 분위수·로그·선형 중 선택합니다.
+- CLI 호출은 usage가 있는 영구 세션 로그를 남겨야 집계됩니다. 저장하지 않은 호출은 복원할 수 없습니다. 오늘과 최근 30일은 설정된 시간대를 사용합니다.
+
 ## 기능
 
 - **상태 표시줄** — 오늘 비용, 현재 세션 비용, 그리고 Claude Code 자체 OAuth 세션에서 읽는 실제 5시간 / 주간 쿼터(`5h:N% wk:N%`). 설정 불필요.
-- **대시보드 탭** — 오늘 / 이번 달 / 전체 기간, 그리고 **Sessions / Projects / Content / Branches**. 모두 정렬 가능.
+- **대시보드 탭** — 오늘 / 최근 30일 / 전체 기간, 그리고 **Sessions / Projects / Content / Branches**. 모두 정렬 가능.
 - **누적 비용 구성 차트**(Y축과 기준선 포함) — 각 일 / 월의 비용 중 입력·출력·캐시 쓰기·캐시 읽기가 차지하는 비율을 한눈에.
 - **Content 탭** — 어떤 콘텐츠가 토큰을 소비하는지 추정(내 프롬프트 vs 도구 결과 vs 어시스턴트 출력 / 사고).
-- **AI 조언**(선택) — 사용량 요약과 최근 프롬프트 샘플을 OpenAI 호환 API(기본 DeepSeek V4 Pro)로 보내 구체적인 재작성을 제안. 키는 직접 준비하거나, 정적 데모를 먼저 미리보기.
+- **AI 조언**(선택) — 먼저 로컬 근거와 설명 가능한 행동을 보여 줍니다. 선택형 BYOK 개인화는 기본적으로 집계만 포함하고 프롬프트 샘플에는 별도 동의가 필요합니다. 전체 요청을 정확히 미리 본 뒤 별도의 보내기 동작을 수행하며, 유용함 / 유용하지 않음 / 적용됨 피드백은 로컬에만 남습니다. 조언은 제한된 기간 동안 일시 중지할 수 있으며 만료되거나 수동으로 다시 표시됩니다.
+  동의를 철회하면 미리보기가 즉시 무효화되고 진행 중인 조언 요청이 취소됩니다. 이미 전송된 데이터는 회수할 수 없습니다.
 - **멀티 벤더 가격** — Opus 4.x / Sonnet 4.x / Haiku 4.5는 Anthropic 공식 가격으로 검증. OpenAI / Gemini / DeepSeek / Kimi / GLM / Qwen 참고 가격(패밀리 인식 폴백 포함). `Refresh Token Pricing`으로 LiteLLM 최신 가격 가져오기.
 - **개인화** — 언어, 시간대, 소수 자릿수, 간략 숫자, 프로젝트 그룹화, 대시보드 자동 새로고침 토글.
 
+## v2.3.1 새로운 기능
+
+- 정확한 가격 및 컨텍스트 메타데이터가 **GPT-6 Astra**(`gpt-6-astra`,
+  105만 토큰)와 **Claude Fable 5.1 / Mythos 5.1**
+  (`claude-fable-5-1` / `claude-mythos-5-1`, 100만 토큰)을 지원합니다.
+  Fable 5.1은 전용 캐시 읽기 요금인 `$0.25 / 백만 토큰`을 사용하며 기존
+  Fable 5 기록은 바꾸지 않습니다. GPT-6 API 등가액은 공식 Standard 단기
+  컨텍스트 요금을 사용합니다. 로컬 집계 로그로는 개별 요청이 272K 입력을
+  넘었는지 확인할 수 없으므로 해당 요청 전체에 적용되는 추가 요금은 포함하지
+  않습니다.
+- Claude 추정치는 Anthropic 직접 요금 또는 AWS Bedrock in-region 온디맨드 요금을
+  선택해 현재 Opus·Sonnet·Haiku 계열에 적용할 수 있습니다. 백엔드를 바꾸면 변경되지
+  않은 로그도 즉시 다시 계산하며, Sonnet 5에는 2026년 8월 31일 출시 프로모션 종료
+  이후의 표준 요금을 사용합니다.
+- 최근 30일은 설정 시간대의 오늘과 이전 29일입니다. 합계가 대조되고 반복 새로고침이 안정적이며 월은 오래된 순서로 표시됩니다. Claude Workflows 요약도 같은 롤링 범위를 사용하고 설정 시간대의 시작일에 따라 각 실행을 집계합니다. 차트 지표를 전환하거나 드릴다운 레이블을 표시할 때도 일/월 사용량 키가 호스트 시간대 때문에 전날이나 전월로 밀리지 않습니다. AI 조언과 Usage Optimizer의 일시 중지 만료일도 설정 시간대와 UI 언어로 표시합니다.
+- 구조화 reasoning effort를 모델 이름에서 추측하지 않습니다. 0이 아닌 `unknown`은 이유를 설명하고 0은 숨깁니다.
+- 제한된 익명 쿼터 관측이 불규칙·당일 재설정을 보존합니다. 같은 창의 유효 비율로 현재 기간을 포함한 총한도와 미사용 내구성 추정치를 표시합니다. 근사·미귀속 증거는 낮은 신뢰도로 표시합니다. 로컬 Codex 쿼터 계열이 겹쳐도 현재 기간은 마지막 실제 관측으로 신뢰도 낮은 혼합 추정을 표시하고, 귀속이 모호한 완료 기간만 사용분 전용으로 유지합니다.
+- 비교 탭은 기존 일별 집계로 Claude + Codex 통합 활동 히트맵을 표시하며 단일 공급자에서도 작동합니다.
+- 미리보기 중심 공유 스튜디오는 결정적 로컬 SVG, 공유 카드, Markdown, 제목/기간, 개인정보 미리보기와 조절 가능한 색상을 지원합니다. Academic Violet이 기본이며 강도 매핑은 분위수(기본), 로그, 선형 중에서 선택할 수 있습니다. 공개 GitHub 전송은 정확한 대상을 별도로 확인합니다.
+- Codex Token 구성은 겹치지 않는 「캐시되지 않은 입력 / 캐시 입력 / 출력」스택 위에 **캐시되지 않은 사용량**(캐시되지 않은 입력 + 출력)을 명확히 표시합니다. 추론은 계속 출력의 부분집합입니다.
+- Codex는 인덱싱 중에도 부드럽게 스크롤됩니다. 스크롤 상태는 동작이 끝난 뒤 한 번만 저장되고 실시간 인덱스 진행률은 페이지 전체를 다시 만들지 않고 텍스트만 갱신합니다. 모델별 녹색 요약은 Claude와 같은 의미로 정확히 일치하는 모델의 API 등가 비용과 가격 적용 범위를 표시합니다. 알 수 없는 모델은 `—`, effort는 중립색의 캐시되지 않은 Token 값으로 유지합니다.
+- OpenAI 호환 Optimizer 요청은 `reasoning_effort`만 보내고 지원되지 않는 최상위 `thinking`을 보내지 않아 [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94)를 해결합니다.
+- Claude/Codex는 밀도, 계층, 포커스, ARIA, 좁은 폭, 밝고 어두운 테마 token을 공유하되 지표 의미는 분리합니다.
+
+검토된 Release 초안은 `v2.3.1`이며, 수동 게시 워크플로가 해당 tag에서 패키지 버전을 설정합니다.
+
 ## v2.3 Codex Beta
 
 - Codex 사용량 레코드는 `sessions/**/*.jsonl`과 `archived_sessions/**/*.jsonl`에서만 찾으며 자격 증명, DB, 알 수 없는 파일은 제외합니다. 별도로 `$CODEX_HOME/session_index.jsonl` 하나만 정확히 스트리밍해 실제 스레드 제목에 사용할 `id` → `thread_name` 매핑을 가져옵니다. 제목 속 절대 경로는 가리고 제목은 메모리에만 유지합니다. 사용량 JSONL 각 줄은 허용 목록의 사용량·구조 메타데이터를 추출하기 위해서만 스트리밍 방식으로 일시 파싱합니다. 프롬프트, 응답, 명령, 도구 인수 필드는 검사하거나 분석에 사용하지 않으며 보관·영구 저장하지 않습니다.
 - **처리된** 값 = 입력 + 출력, **캐시되지 않은 사용량** = 캐시되지 않은 입력 + 출력, **캐시 입력**은 입력의 부분집합, reasoning은 출력의 부분집합입니다. 개요에는 캐시 입력 / 입력으로 계산한 입력 캐시 적중률도 표시합니다. Codex 청구 비용은 표시하지 않습니다. 첫 요약 카드에는 선택 범위의 API 등가 비용 추정치를 명확히 표시하고, 전체 기간 보기에는 같은 가격 기준의 주간 추이를 표시합니다. Claude / Codex / Compare는 공급자별 집계 의미를 분리합니다.
-- Codex의 **오늘**은 설정한 시간대의 현재 달력 날짜를 뜻합니다. 정확한 시간별 API 등가 비용을 표시하고 Token 구성은 별도 보기로 유지합니다. 일별·월별 기본 차트도 API 등가 비용을 기본값으로 사용하며 Token 구성은 따로 볼 수 있습니다. 정확히 일치하는 알려진 모델만 가격 계산에 포함하므로 알 수 없는 모델은 가격을 매기지 않고 가격 적용 범위는 계속 표시합니다. schema 3과 호환되는 추가형 시간별 sidecar는 오늘 사용량이 있다고 이미 확인된 canonical 파일만 처리하고 checkpoint 저장과 재개를 지원하며, 전체 기록 재인덱싱을 유발하지 않습니다.
+- Codex의 **오늘**은 설정한 시간대의 현재 달력 날짜를 뜻합니다. 정확한 시간별 API 등가 비용을 표시하고 Token 구성은 별도 보기로 유지합니다. 일별·월별 기본 차트도 API 등가 비용을 기본값으로 사용하며 Token 구성은 따로 볼 수 있습니다. 정확히 일치하는 알려진 모델만 가격 계산에 포함하므로 알 수 없는 모델은 가격을 매기지 않고 가격 적용 범위는 계속 표시합니다. schema 3과 호환되는 추가형 시간별 sidecar는 최근 30일의 희소한 날짜 / 시간 버킷을 보관하고 checkpoint 저장과 재개, 31일째 제거를 지원하며 날짜를 펼칠 때 JSONL을 읽지 않습니다. Codex 월별 차트와 표는 오래된 달부터 표시합니다.
 - 요청 단위 Token 귀속은 유효한 `last_token_usage` component를 우선 사용합니다. 그 안의 `total_tokens`는 활성 컨텍스트 크기이며 요청 사용량이 아닙니다. total과 last의 전체 숫자 서명이 동일한 가명 rate-limit 소스 또는 바로 인접한 레코드의 재생을 증명할 때만 중복을 제거합니다. last snapshot이 없으면 cumulative lineage high-water로 되돌아갑니다. 업그레이드 후 인덱스를 한 번 자동 재구축하며 그동안에도 인덱싱된 소계를 계속 표시합니다.
-- Claude와 Codex의 전체 기간 / 비교 보기는 로컬 Token 로그에서 과거 사용 등가치를 직접 계산합니다. 가장 최근의 유효한 공식 재설정 관측 하나만 고유하고 겹치지 않는 주간 기간열의 기준이 되므로 각 사용 이벤트는 한 기간에만 집계됩니다. 사용할 수 있는 관측이 없으면 사용분 전용 기록만 UTC 월요일부터 월요일까지의 달력 주로 되돌아갑니다. series 이름이 달라도 겹치면서 정렬되지 않은 미래 재설정은 충돌로 처리하며 두 번째 「현재 기간」을 만들 수 없습니다. 기간 범위와 재설정 시각은 따로 표시합니다. Codex 사용량은 일별 슬라이스로 저장됩니다. 슬라이스가 공식 일중 재설정을 가로지르더라도 Token은 한 번만 집계하고, 영향을 받은 기간을 「경계 근사치」로 표시하며 사용된 등가치만 보여 주고 총한도나 미사용분을 역산하지 않습니다. 이 표시 규칙은 인덱스 schema를 변경하거나 재구축을 유발하지 않습니다. Codex 과거 기간은 항상 사용된 값만 표시합니다. 최신 현재 기간에 한해 재설정 충돌이 없고 인덱싱된 사용량을 단일 관측 출처에 안정적으로 귀속할 수 있을 때만 총한도를 추정할 수 있으며, 현재 미사용 값은 결론으로 제시하지 않습니다. 귀속할 수 없는 여러 로그인 사용량도 사용된 값만 표시하며 계정 분리를 만들어 내지 않습니다. 현재 공식 API 단가를 전체 기록에 일관되게 적용합니다. 이는 청구액이나 공식 구독 가격이 아닌 대리 추정치입니다. 이 패널은 기본으로 켜지며 설정의 `showWeeklyEquivalentValue`에서 끌 수 있습니다. Claude는 이 릴리스부터 프로필별 한도 관측을 기록합니다.
-- Codex로 전환해도 기존 오늘 / 이번 달 / 전체 기간 / 세션 / 프로젝트 / 콘텐츠 / 설정 구조를 유지하고 Codex 의미에 맞게 레이블만 조정합니다. 두 공급자는 같은 render function, HTML class, 차트, 표, 간격 및 반응형 규칙을 사용합니다. 시계열 차트는 너비가 정렬되고 밀집된 콘텐츠만 각 영역 안에서 스크롤됩니다. Codex 제안은 인덱싱된 30일 구조 근거를 사용합니다.
+- Claude와 Codex의 전체 기간 / 비교 보기는 로컬 Token 로그에서 과거 사용 등가치를 직접 계산합니다. 가장 최근의 유효한 공식 재설정 관측을 기준으로 고유하고 겹치지 않는 주간 기간열을 만들며 각 사용 이벤트는 한 기간에만 집계됩니다. 사용할 수 있는 관측이 없으면 사용분 전용 기록만 UTC 월요일부터 월요일까지의 달력 주로 되돌아갑니다. 같은 quota series의 관측은 하나의 series로 유지하고 낮은 신뢰도의 근사치로 표시할 수 있으며 두 번째 「현재 기간」을 만들지 않습니다. Codex의 account-wide `codex` 관측은 과거와 현재 기간 모두를 장식할 수 있고 재설정 이동, 파일 출처 또는 일별 경계 통과는 신뢰도를 낮춥니다. 파일 키는 계정 ID가 아니므로 같은 home의 대상 파일을 함께 사용합니다. 로컬 quota series가 겹쳐도 현재 기간은 마지막 실제 관측으로 신뢰도 낮은 혼합 추정을 표시합니다. 귀속이 모호한 완료 기간이나 관측이 없는 기간은 사용된 등가치만 표시하고 계정 분리를 만들어 내지 않습니다. 내부적으로 일관된 관측 기간은 현재 기간을 포함해 총한도와 미사용 내구성 추정치를 표시할 수 있으며, 귀속이나 경계가 불확실하면 값을 숨기지 않고 신뢰도를 낮춥니다. 이 표시 규칙은 인덱스 schema를 변경하거나 재구축을 유발하지 않습니다. 현재 공식 API 단가를 전체 기록에 일관되게 적용합니다. 이는 청구액, 공식 잔액 또는 공식 구독 가격이 아닌 대리 추정치입니다. 이 패널은 기본으로 켜지며 설정의 `showWeeklyEquivalentValue`에서 끌 수 있습니다. Claude는 이 릴리스부터 프로필별 한도 관측을 기록합니다.
+- Codex로 전환해도 기존 오늘 / 최근 30일 / 전체 기간 / 세션 / 프로젝트 / 콘텐츠 / 설정 구조를 유지하고 Codex 의미에 맞게 레이블만 조정합니다. 두 공급자는 같은 render function, HTML class, 차트, 표, 간격 및 반응형 규칙을 사용합니다. 시계열 차트는 너비가 정렬되고 밀집된 콘텐츠만 각 영역 안에서 스크롤됩니다. Codex 제안은 인덱싱된 30일 구조 근거를 사용합니다.
 - 루트 작업은 절대 경로를 가린 최신 실제 스레드 제목을 사용합니다. 자식 작업은 자신의 실제 스레드 제목을 우선 사용하고, 제목이 없으면 보고된 닉네임을 사용하면서 부모 / 루트 작업 제목도 표시합니다. 이 정보도 없으면 현지화된 중립 대체 이름을 표시합니다. 프로젝트 이름은 Git 저장소 이름을, Git 외부에서는 폴더 이름을 사용합니다. 안정적으로 집계할 수 없는 Branches나 Workflows를 만들어 내지 않습니다.
 - 최근 7일 / 30일 값은 설정한 시간대에서 이벤트 발생일을 정확히 나눠 계산합니다. 마이그레이션이나 재구축이 진행 중이면 Codex 카드, 표, 프로젝트, 세션, 권장 사항 및 상태 값을 **인덱싱된 소계**로 명시하고 검증되지 않은 이전 합계를 제외합니다. Codex home이 감지되면 공급자 탭을 즉시 표시하고, 최초 인덱싱 중에는 페이지 안에 정확한 인덱싱 파일 수, 백분율, 용량 진행 상황을 실시간으로 표시합니다. 비교 탭은 두 공급자 모두 실제 데이터가 생긴 뒤에만 표시됩니다. 첫 원자적 체크포인트가 생성되면 인덱싱이 계속되는 동안에도 전체 소계 대시보드를 사용할 수 있으며 진행 표시가 카드나 표를 대체하지 않습니다. 선택한 Codex home은 계정을 구분하지 않으므로 같은 home에 여러 로그인이 남긴 로그는 합산됩니다. 로컬 로그에는 신뢰할 수 있는 계정 식별자가 없으므로 한도 카드는 **마지막 관측**만 유지하며 합산하지 않습니다.
 - 각 제안은 인덱싱된 30일 구조 집계에 근거가 있을 때만 관측, 읽기 쉬운 근거, 조건부 행동을 보여 줍니다. 근거가 없으면 일반적인 조언을 생성하지 않습니다.
@@ -69,11 +112,27 @@ Cursor / Windsurf용으로 [Open VSX Registry](https://open-vsx.org/extension/Gr
 - `usageLimitTracking` — 실제 5시간 / 주간 쿼터 표시.
 - `showCost` / `showContext` — 상태 표시줄의 비용 항목과 컨텍스트 윈도우 사용률(`/context` 유사) 표시 전환.
 - 위 상태 표시줄 항목들은 개별적으로 끌 수 있습니다. `usageLimitTracking` / `showCost` / `showContext` 를 `false`로 설정하면 해당 항목만 숨겨집니다.
-- `advice.apiKey` — AI 조언 기능용 API 키(OpenAI 호환).
+- `advice.apiKey` — AI 조언과 Usage Optimizer가 함께 쓰는 사용자 제공 API 키(Anthropic 또는 OpenAI 호환 엔드포인트).
 - `pauseDashboardRefresh` — 대시보드 자동 새로고침 일시정지(대시보드 헤더에서도 토글 가능).
 
 전체 설정 표는 [메인 README](README.md#configuration)를 참고하세요.
 
+## 로컬 데이터, 개인정보 및 제한
+
+전체 목록, 보존, 마이그레이션, 삭제 및 원격 경계는
+[Local data and privacy](LOCAL-DATA.md)([中文](LOCAL-DATA.zh-CN.md))를 참고하세요.
+
+| 데이터 | 로컬 보존 | 원격 동작 |
+|---|---|---|
+| 원본 로그 | 공급자 소유·읽기 전용, 전체 복사 안 함 | 기본 없음 |
+| Codex 인덱스 | 제한된 가명 수치/구조 집계 | 없음 |
+| 쿼터 기록 | 제한된 익명 창 관측, 원시 계정 ID 없음 | 활성화된 Claude 쿼터 조회만. Codex는 로컬 |
+| UI/공유 | 필터와 선택형 제목/범위/GitHub 대상 문자열 | 정확한 확인 후에만 게시 |
+| 조언/키 | 제한된 집계 근거, 키는 SecretStorage만 | 별도 보내기 후 정확히 미리 본 요청만 전송 |
+
+구조화 근거에 없는 재설정은 복원할 수 없습니다. 여러 로그인 귀속이 모호하면 현재 기간은 마지막 실제 관측으로 신뢰도 낮은 혼합 추정을 표시하고, 완료 기간은 사용분만 표시합니다.
+API 등가 값은 청구액이 아닙니다. 원본 로그 보존은 Claude Code/Codex가 관리하며 파생 상태는 명시적 삭제가 가장 확실합니다.
+
 ## 문제 해결
 
 **"No Claude Code Data"** — Claude Code가 설치되어 최소 한 번 사용되었는지 확인하고, `dataDirectory` 설정을 확인하세요(자동 감지는 `~/.claude/projects`를 봅니다).
diff --git a/README-zh-CN.md b/README-zh-CN.md
index 04a341a4..c2884019 100644
--- a/README-zh-CN.md
+++ b/README-zh-CN.md
@@ -10,7 +10,7 @@
 >
 > **它不是什么**：账单工具。所有金额均为估算值（基于公开的每百万 token 单价），实际费用请以 Anthropic 官方账单为准。
 
-> 截图取自英文界面。
+> 截图包含中英文界面；各图标明主题与范围。
 
 ---
 
@@ -35,40 +35,77 @@
 
 *点击状态栏打开完整仪表板：堆叠 token 构成图、小时分布、缓存命中率、按 token 类型的成本构成，以及下方的按模型 / 按日表格。*
 
+### v2.3.1 Codex 与对比
+
+![Claude 今日，简体中文深色主题](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+![Codex 概览，简体中文深色主题](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+![Codex 每周额度估算，英文深色主题](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+![Claude 与 Codex 综合热力图，英文浅色主题](images/v2.3.1/compare-heatmap-en-light.png)
+
+以上四张 v2.3.1 截图使用生产仪表板渲染器、合成夹具及 VS Code Light+/Dark+ 主题变量生成，不是个人用量或账单证据；原生 VSIX 安装单独验收。
+
+- Codex 主状态项显示**今日已用 token**，周额度项显示**余量**：已用 36% 时为 `wk 64%`；悬浮卡保留已用进度条、重置时间和分行说明。额度来自本地最后观测，不是实时余额。
+- 周期详情默认折叠；分享设置位于图下方。分享工作台默认开启、可关闭；色阶可选分位数、对数或线性。
+- CLI 调用只有留下带 usage 的持久会话日志才能计入。未保存会话的历史调用不能回填；今日和最近 30 天都采用配置时区。
+
 ### Content 标签页：看清 token 究竟花在了哪里
 
 ![Content 标签页](images/v2-content-en.png)
 
 *估算各类内容的 token 占比：你的提示词 vs 工具结果（按工具）vs 助手输出 / 思考。这是优化使用的切入点，范围为最近 30 天（`advice.promptWindowDays`）。*
 
-### AI 建议：基于你真实用量的一份教练报告
+### AI 建议：先看本地证据，再决定是否发送
 
-AI 建议生成的是一份 **Markdown 文档**，用文字展示比截图更直观。配好 key（`advice.apiKey`），点击 **Get AI advice**（✨ 按钮，或 Content 标签页那张卡），选一个范围（全部项目，或某个项目），它会把你的用量汇总加上一份**你自己的**提示词样本发给你的模型，打开一份按优先级排好的报告。自备 key，默认使用 Anthropic（`/v1/messages`），也支持任意 OpenAI 兼容端点。
+**Get AI advice** 现在打开统一的建议有效性界面：先用已物化的本地聚合解释观察、证据和条件式行动；用户可记录「有用 / 无用 / 已应用」，并在存在可靠同类任务时查看版本化的前后比较。比较账本只保存粗粒度指标、质量、覆盖率和版本，不保存提示词、正文、路径或 session ID；没有可靠配对时会明确显示证据不足。单条建议可暂停有限时间，期间移出默认摘要，到期或手动恢复后重新出现。
 
-返回内容大致是这样（示意）：
+AI 个性化仍为可选项。自备 `advice.apiKey` 后，默认请求只含聚合数据；提示样本需要单独同意。界面会先展示将要发送的**完整请求及其规范字节**，随后必须另外点击「发送」才会调用配置的 Anthropic 或 OpenAI 兼容端点。密钥只进入请求头，不出现在预览中；没有默认、后台或订阅凭据请求。
 
-> **把指令写得更完整**
-> - 有几条提示词只写了「修一下这个 bug」，没说是哪个文件、什么现象，于是第一轮要先去找。开头先点明文件 + 期望行为 vs 实际行为。
->
-> **在不牺牲清晰度的地方省 token**
-> - 约 38% 的 token 花在 150k 上下文以上。不相关的任务之间用 `/clear`，每次请求都更省。
+撤回建议的数据授权会立即作废预览并取消在途建议请求，不等待本地存储写入；已经传出的字节无法追回。
 
 ### 用量优化器
 
 ![用量优化器卡片](images/v2-optimizer-en.png)
 
-粘贴进一条粗略、没成形的需求，获得一条干净、**可直接粘贴**的提示词（纯文本、无 Markdown），并附上推荐的 effort / thinking / 模型（以小标签显示）。三个可选开关进一步微调（标出含糊指代 · 压缩长粘贴内容 · 建议风格方向）。实验性，默认关闭；**只发送你粘贴的文字**，不碰你的文件、不进终端，且首次有一次性同意确认。
+粘贴进一条粗略、没成形的需求，获得一条干净、**可直接粘贴**的提示词（纯文本、无 Markdown），并附上推荐的 effort / thinking / 模型（以小标签显示）。三个可选开关进一步微调（标出含糊指代 · 压缩长粘贴内容 · 建议风格方向）。实验性，默认关闭；**只发送你粘贴的文字**，不碰你的文件、不进终端。它与 AI 建议共用完整请求预览、单独发送、取消和严格响应解析边界。
 
 ---
 
+## v2.3.1 新功能
+
+- 精确定价与上下文元数据现已覆盖 **GPT-6 Astra**（`gpt-6-astra`，105 万
+  token 上下文）以及 **Claude Fable 5.1 / Mythos 5.1**
+  （`claude-fable-5-1` / `claude-mythos-5-1`，100 万 token 上下文）。
+  Fable 5.1 使用其专属的 `$0.25 / 百万 token` 缓存读取价，既有 Fable 5
+  历史数据不变。GPT-6 的 API 等效值采用官方 Standard 短上下文费率；由于
+  本地聚合日志无法判定单次请求是否超过 272K 输入，因此不计入该阈值以上的
+  整个请求附加价。
+- Claude 估算可选用 Anthropic 直连或 AWS Bedrock in-region 按需费率，覆盖当前
+  Opus、Sonnet 与 Haiku 系列；切换后端会立即按新费率重算未变化的本地日志。
+  Sonnet 5 使用 2026 年 8 月 31 日上线促销结束后的标准费率。
+- 最近 30 天严格定义为配置时区中的今天及此前 29 个自然日；满足「今天 ≤ 最近 30 天 ≤ 全部时间」，重复刷新/重建不累加，所有分组可核对，月份从旧到新显示。Claude 的工作流摘要使用同一滚动范围，并按配置时区中的开始日期归入周期。切换图表指标或渲染下钻标签时，日/月用量键不会再受宿主时区影响而回退一天或一个月；AI 建议和用量优化器的暂停截止日期也统一使用配置时区与界面语言。
+- 兼容当前和旧版结构化 reasoning effort，不根据模型名猜测；非零 `unknown` 会解释原因，零值不会渲染。
+- 有界匿名额度观测可保留不规则、连续乃至同日重置。每个同窗有效已用比例都参与总额度和未用耐用度估算（包括当前周期）；近似或未归属证据标为低可信度。即使本地 Codex 额度系列重叠，当前周期仍采用最后一次真实观测给出低可信度混合估算；归属不清的已结束周期保持仅已用值。未用估算不会为负。
+- 「对比」默认展示 Claude + Codex 综合活动热力图，直接复用日聚合、支持任一单供应商，并在 tooltip 中分别显示两侧数据。
+- 预览优先的分享工作台包含确定性本地 SVG、综合分享卡、可复制 Markdown、自定义标题/范围、隐私预览和可调配色。工作台默认开启，可在设置中用一个开关整体隐藏。默认采用 Academic Violet；色阶映射可选分位数（默认）、对数或线性；可选的公开 GitHub 发布需要另行确认精确目标。
+- Codex Token 构成现在会在互不重叠的「未缓存输入 / 缓存输入 / 输出」堆叠上方明确显示 **未缓存用量**（未缓存输入 + 输出）；推理仍是输出的子集。
+- Codex 在索引期间也能顺畅滚动：滚动状态改为操作结束后只保存一次，实时索引进度只更新文字，不再重建整页。分模型折叠项的绿色摘要现在与 Claude 一致，显示精确模型的 API 等效价格并附定价覆盖说明；未知模型显示 `—`，推理强度仍以中性色显示未缓存 Token。
+- OpenAI 兼容的优化器请求现在只发送 `reasoning_effort`，不再附带不受支持的顶层 `thinking` 参数，解决 [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94)。
+- Claude/Codex 共用卡片密度、层级、折叠、焦点、ARIA、窄宽度和深浅主题 token，同时保持各供应商指标含义独立。
+- AI 建议与用量优化器共用精确预览和明确发送边界；没有默认/后台 AI 请求，本地证据与反馈保持有界。
+
+已审阅的 Release 草稿为 `v2.3.1`；人工发布工作流会从该 tag 写入包版本。
+
 ## 2.3 Codex Beta
 
 - Codex 用量记录只会从 `sessions/**/*.jsonl` 与 `archived_sessions/**/*.jsonl` 中发现；凭据、数据库和未知文件仍明确排除。此外，插件会精确流式读取 `$CODEX_HOME/session_index.jsonl`，仅将 `id` 映射为 `thread_name`，用于真实线程标题。标题中的绝对路径会先脱敏，标题只保留在内存。用量 JSONL 会逐行流式、临时解析，以提取白名单内的用量与结构元数据；提示词、回复、命令和工具参数字段不会被检查或用于分析，也不会被保留或持久化。
 - **已处理** = 输入 + 输出；**未缓存用量** = 未缓存输入 + 输出；**缓存输入**仍是输入的子集，reasoning 仍是输出的子集。概览还会按「缓存输入 / 输入」显示输入缓存命中率。Codex 不显示账单成本；首张汇总卡会针对当前范围显示明确标注的 API 等效成本估算，「全部时间」则按同一定价口径展示每周趋势。Claude / Codex / Compare 仍保持各供应商口径独立。
-- Codex 的**今天**指配置时区中的当前自然日。页面会显示精确的小时 API 等效成本，并把 Token 构成作为独立视图；每日与每月主图也默认显示 API 等效成本，Token 构成仍单独保留。只有精确匹配的已知模型才参与计价，未知模型保持未定价，定价覆盖率始终可见。这个兼容 schema 3 的增量小时 sidecar 仅处理已知包含今天用量的 canonical 文件，支持检查点与续传，且不会触发全历史重建。
+- Codex 的**今天**指配置时区中的当前自然日。页面会显示精确的小时 API 等效成本，并把 Token 构成作为独立视图；每日与每月主图也默认显示 API 等效成本，Token 构成仍单独保留。只有精确匹配的已知模型才参与计价，未知模型保持未定价，定价覆盖率始终可见。这个兼容 schema 3 的增量小时 sidecar 保存滚动最近 30 天的稀疏日期 / 小时桶，支持检查点与续传、淘汰第 31 天，并在展开日期时不读取 JSONL。Codex 按月图表和表格按月份从旧到新显示。
 - 单次请求 Token 归因优先采用有效的 `last_token_usage` component；其中 `total_tokens` 表示活跃上下文大小，不是该请求的用量。只有完整的 total-plus-last 数字签名能证明同一伪名 rate-limit 来源或紧邻记录发生重放时才去重；缺少 last snapshot 时回退为 cumulative lineage high-water。升级后会自动重建一次索引，期间持续显示已索引小计。
-- Claude 与 Codex 的「全部时间」/「对比」会直接根据本地 Token 日志计算历史已用等价值。最新且有效的官方重置观测只会锚定一组唯一、互不重叠的每周周期，每条用量只计入一个周期；没有可用观测时，仅已用历史才回退到 UTC 周一至周一的自然周。任何重叠但未对齐的未来重置都会视为冲突，即使 series 名称不同，也不能再生成第二个「当前周期」；周期范围与重置时刻会分开表达。Codex 用量按日切片保存：若某个切片跨过官方日内重置，其 Token 仍只计一次，受影响周期会标为「边界近似」，并且只显示已用等价值，不反推总额度或未用额度。该显示规则不改变索引 schema，也不会触发重建。Codex 历史周期一律仅显示已用值；只有最新当前周期在重置无冲突、且已索引用量可可靠归属到单一观测来源时，才允许反推总额度，当前未用值仍不会作为结论。无法归属的多登录用量同样只显示已用值，不会虚构账号拆分。历史统一套用当前官方 API 单价；这是代理估算，不是账单或官方订阅价格。该面板默认开启，可在设置中通过 `showWeeklyEquivalentValue` 关闭。Claude 从此版本开始按本地 profile 记录额度观测。
-- 切换到 Codex 后仍沿用既有的今天 / 本月 / 全部时间 / 会话 / 项目 / 内容 / 设置结构，并按 Codex 语义调整标签。两个供应商复用同一组渲染函数、HTML class、图表、表格、间距和响应式规则；时间序列图保持宽度对齐，密集内容只在各自区域内滚动。Codex 建议使用已索引的 30 天结构化证据。
+- Claude 与 Codex 的「全部时间」/「对比」会直接根据本地 Token 日志计算历史已用等价值。最新且有效的官方重置观测会锚定一组唯一、互不重叠的每周周期，每条用量只计入一个周期；没有可用观测时，仅已用历史才回退到 UTC 周一至周一的自然周。只有真正不同 quota series 且其未来重置重叠、未对齐时才视为冲突；同一 series 的观测仍保持为一个 series，并可按低可信度近似显示，不会再生成第二个「当前周期」。周期范围与重置时刻会分开表达。Codex 的 account-wide `codex` 观测可以同时装饰历史和当前周期；如果重置时间偏离七天网格，就按观测时间映射到对应展示周期。文件来源、重置漂移或日切片跨边界时仍可给出总额度近似，但会降低可信度并标注为近似。文件键不是账号身份，因此同一 home 中符合条件的本地文件会一起参与；即使本地 quota series 重叠，当前周期仍采用最后一次真实观测给出低可信度混合估算；归属不清的已结束周期或没有可用观测的周期保持仅已用值，不会虚构账号拆分。任何内部一致且有观测的周期（包括当前周期）都可以显示总额度和未用耐用度估算；归属或边界不确定时降低可信度，而不是静默显示破折号。Codex 用量按日切片保存，Token 仍只计入一个周期；该显示规则不改变索引 schema，也不会触发重建。历史统一套用当前官方 API 单价；这是代理估算，不是账单、官方余额或官方订阅价格。该面板默认开启，可在设置中通过 `showWeeklyEquivalentValue` 关闭。Claude 从此版本开始按本地 profile 记录额度观测。
+- 切换到 Codex 后仍沿用既有的今天 / 最近 30 天 / 全部时间 / 会话 / 项目 / 内容 / 设置结构，并按 Codex 语义调整标签。两个供应商复用同一组渲染函数、HTML class、图表、表格、间距和响应式规则；时间序列图保持宽度对齐，密集内容只在各自区域内滚动。Codex 建议使用已索引的 30 天结构化证据。
 - 根任务使用经过路径脱敏的最新真实线程标题；子任务优先使用自己的真实线程标题，缺失时使用其上报的昵称并显示父级 / 根任务标题；这些信息仍缺失时采用本地化的中性回退名称。项目名称使用 Git 仓库名，非 Git 目录则使用文件夹的末级名称。插件不会虚构无法可靠统计的 Branches 或 Workflows。
 - 最近 7 天与 30 天按配置时区中的事件发生日精确切片。迁移或重建未完成时，Codex 的卡片、表格、项目、会话、建议与状态栏都会明确标为**已索引小计**，并排除未经验证的旧版总量。检测到 Codex home 后会立即显示供应商标签；首次建立索引期间在页面内实时显示精确的已索引文件数、百分比与容量进度，「对比」则等到两个供应商都有真实数据后才出现。生成首个原子检查点后，完整的小计仪表盘会在索引继续期间保持可用；进度提示不会替代卡片和表格。所选 Codex home 不区分账号，因此同一目录中多个登录账号留下的日志会合并统计；本地日志没有可靠的账号身份字段，额度卡只能保留**最后观测**，不会相加。
 - 每条建议仅在已索引的 30 天结构聚合有证据时展示观测、易读证据和条件式行动；没有证据就不会生成泛化建议。
@@ -104,8 +141,8 @@ AI 建议生成的是一份 **Markdown 文档**，用文字展示比截图更直
   实际返回的受限模型名称，例如 `fable 17%`；由 PR #38
   （[@wheelbarrel00](https://github.com/wheelbarrel00)）最初的
   模型专属额度功能演进而来。
-- **AI 建议 2.0**：自备 key：默认 **Anthropic**（`/v1/messages`），也支持任意 OpenAI 兼容端点（`advice.apiFormat`）。引入新信号（运行、缓存命中率、归因、思考占比）；可选 `advice.userContext` 会附上"针对本项目的个性化"一节；`advice.promptWindowDays`（默认 30）设定采样窗口。传输层加强了：超时、重试、curl 兜底。*（一个免 key 的"订阅"后端做过原型，但本版未上线 —— Anthropic 封禁用 Claude Code 的 OAuth token 直连 API；若日后放开会再启用。）*
-- **用量优化器**（实验性，`advice.optimizer.enabled`，默认关闭）：Content 标签页的一张卡，粘贴进粗略需求，返回一条精炼提示词，以**纯文本**形式（可直接粘贴、无 Markdown），并附推荐的 effort / thinking / 模型。三个可选微调项（标出含糊指代 · 压缩长粘贴内容 · 建议风格方向）。**只发送你粘贴的文字**，且首次有一次性同意确认。
+- **AI 建议 2.0 的兼容基础**：继续支持自备 key 的 Anthropic（`/v1/messages`）与 OpenAI 兼容端点（`advice.apiFormat`）、超时、重试和 curl 兜底；v2.3.1 将旧入口收敛到统一的本地证据、完整请求预览、明确发送和反馈边界。订阅凭据从不用于模型请求。
+- **用量优化器**（实验性，`advice.optimizer.enabled`，默认关闭）：Content 标签页的一张卡，粘贴进粗略需求，返回一条精炼提示词，以**纯文本**形式（可直接粘贴、无 Markdown），并附推荐的 effort / thinking / 模型。三个可选微调项（标出含糊指代 · 压缩长粘贴内容 · 建议风格方向）。先生成包含所粘贴文字的精确请求预览；只有随后明确点击发送才会访问配置的 BYOK endpoint。
 - **上下文窗口指示器**（实验性，默认关闭）：在设置里开启后，状态栏显示当前 session 的上下文占用。`~` 表示窗口大小是猜测；代理 / 自定义模型可用 `contextWindowOverride` 手填真实窗口。
 
 ## 2.0 新功能
@@ -113,7 +150,7 @@ AI 建议生成的是一份 **Markdown 文档**，用文字展示比截图更直
 - **真实的 5 小时和每周配额** 显示在状态栏：OAuth 会话跟随当前窗口所选的 Claude profile，优先级为显式 `dataDirectory`、首个有效 `CLAUDE_CONFIG_DIR`、最后 `~/.claude`；macOS 钥匙串仅用于默认 profile。借鉴上游 [PR #9](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/pull/9)（[@Dobidop](https://github.com/Dobidop)）。
 - **四个新标签页**：Sessions、Projects、Content、Branches，均可排序。
 - **堆叠 token 构成图**，含 Y 轴和参考线。
-- **AI 建议命令**（默认 DeepSeek V4 Pro，`reasoning_effort=max`），未配置 key 时提供 demo 演示。
+- **AI 建议命令**现在转到统一的本地证据界面；没有自备 key 时请求保持未发送，不再打开另一套 demo 路径。
 - **多厂商定价**：Opus 4.x、Sonnet 4.x、Haiku 4.5 对照 Anthropic 官方定价；OpenAI、Gemini、DeepSeek、Kimi、GLM、Qwen 等代理场景的参考价，含家族感知回退。`Refresh Token Pricing` 可拉取 LiteLLM 即时价格。
 - **自定义时区** 用于日期显示（`claudeCodeUsage.timezone`）。
 - **浅色主题标签可读性** 修复。
@@ -154,7 +191,7 @@ ext install GrowthJack.claude-code-usage
 |---|---|---|
 | `language` | `"auto"` | 界面语言：`auto` / `en` / `de-DE` / `zh-TW` / `zh-CN` / `ja` / `ko` / `pt-BR` / `id`。 |
 | `dataDirectory` | `""` | 自定义 Claude 数据目录；留空 = 自动检测。 |
-| `advice.apiKey` | `""` | AI 建议 + 用量优化器的 API key（留空则 AI 建议会打开 demo）。 |
+| `advice.apiKey` | `""` | AI 建议 + 用量优化器的自备 API key；留空时不能发送请求。 |
 
 其余全部 —— 刷新间隔、状态栏各项、数字 / 日期格式、项目分组、内容分析，以及所有 AI 建议 / 优化器选项 —— 都在仪表板的 ⚙ 设置标签页里。升级不丢配置：首次启动会做一次性迁移，把你 `settings.json` 里已有的值搬过来。
 
@@ -180,9 +217,27 @@ ext install GrowthJack.claude-code-usage
 
 ## 隐私
 
+完整数据清单、保留期、迁移、清除和远程边界见
+[本地数据与隐私](LOCAL-DATA.zh-CN.md)（[English](LOCAL-DATA.md)）。
+
+| 数据 | 本地保留 | 远程行为 |
+|---|---|---|
+| 源日志 | 供应商拥有、只读；不整份复制 | 默认无 |
+| Codex 索引 | 有界匿名数值/结构聚合 | 无 |
+| 额度历史 | 有界匿名窗口观测，不含原始账号 ID | 启用时仅 Claude 查询额度；Codex 证据留在本地 |
+| UI/分享状态 | 筛选及可选标题/范围/GitHub 目标字符串 | 仅精确确认后发布 |
+| 建议状态/密钥 | 有界聚合证据；密钥仅在 SecretStorage | 另行点击发送后才传输精确预览过的请求 |
+
 - 所有 token / 成本 / session 分析都在**本地**进行，只读取你的 `~/.claude/projects/**/*.jsonl` 文件。
 - 配额指示器用 Claude Code 现有的 OAuth token 调用 **`api.anthropic.com/api/oauth/usage`**，不发送任何额外凭证。
-- **AI 建议**和**用量优化器**是仅有的会调用模型的功能 —— 且只在**你**主动触发时。AI 建议发送的是你的用量汇总加上一份近期提示词样本；优化器**只发送你粘贴进去的文字**（不碰你的文件、不进终端），且首次有一次性同意确认。两者都发往 `advice.apiUrl` 指定的端点，用你自己的 `advice.apiKey`（默认 Anthropic `/v1/messages`，也支持任意 OpenAI 兼容端点）。**自备 key**；插件本身不附带任何密钥。
+- **AI 建议**和**用量优化器**是仅有的会调用模型的功能，而且只在你查看完整请求后再次主动点击「发送」时调用。AI 建议默认只发送聚合证据；提示样本与用户上下文需要独立同意，并完整出现在预览中。优化器只包含你粘贴的文字。两者仅使用 `advice.apiUrl` 与自备 `advice.apiKey`；密钥只进入请求头，插件不使用订阅凭据，也没有后台请求。
+
+### 已知限制
+
+- 从未出现在官方或本地结构化证据中的重置无法重建；只有日粒度时可信度会下降。
+- 一个 Codex home 可能包含多个登录；当前周期会用最后一次真实观测给出低可信度混合估算，归属不清的已结束周期保持仅已用值，不虚构账号拆分。
+- API 等效价值受当前公开单价与可见定价覆盖率影响，不是账单或订阅价格。
+- 源日志保留期由 Claude Code/Codex 控制；明确的清除控制才是移除插件派生状态的可靠方式。
 
 ---
 
@@ -192,6 +247,11 @@ ext install GrowthJack.claude-code-usage
 - 确认 Claude Code 已安装并至少使用过一次。
 - 检查 `dataDirectory` 设置；自动检测会查 `~/.claude/projects` 和 `~/.config/claude/projects`。
 
+**一次性 Claude CLI 调用没有计入**
+- 使用 `--no-session-persistence` 的调用可能只留下提示历史，不会写入项目转录，
+  也没有 token `usage` 字段。插件不会根据提示历史虚构 token 或成本。希望后续
+  审计调用计入时，请不要使用该参数；过去未持久化的 token 用量无法在本地重建。
+
 **配额行显示 `5h:--% wk:--%`**
 - Claude Code 的 OAuth token 缺失或过期。请登录一次当前 Claude profile。凭证按显式 `dataDirectory`、首个有效 `CLAUDE_CONFIG_DIR`、最后 `~/.claude` 的顺序选择；全局 macOS 钥匙串条目不会替代已选中的自定义 profile。
 
@@ -201,8 +261,8 @@ ext install GrowthJack.claude-code-usage
 **`Get AI Usage Advice` 返回 404**
 - DeepSeek 当前端点**不**使用 `/v1` 前缀。请用 `https://api.deepseek.com/chat/completions`。扩展会自动剥除多余的 `/v1`。
 
-**`Get AI Usage Advice` 显示 demo 而非真实建议**
-- AI 建议需要 key。若 `claudeCodeUsage.advice.apiKey` 为空，命令会打开一份手写 demo（文件名带 `…-DEMO-…`，顶部有醒目横幅）而不调用任何 API。在设置中填入 key 即可获得真实建议。
+**`Get AI Usage Advice` 无法发送**
+- AI 个性化需要自备 key。若 `claudeCodeUsage.advice.apiKey` 为空，仍可查看本地证据，但发送按钮不可用且不会调用 API；在设置中填入 key 后，先核对完整请求预览，再单独点击发送。
 
 **大历史下 CPU 占用高或刷新缓慢（包括 Linux）**
 - V2.2.1 移除了 active 状态下隐藏的 8 秒轮询覆盖，并限制首时间戳扫描。
diff --git a/README-zh-TW.md b/README-zh-TW.md
index 222d1979..733caff0 100644
--- a/README-zh-TW.md
+++ b/README-zh-TW.md
@@ -10,7 +10,7 @@
 >
 > **它不是什麼**：帳單工具。顯示金額均為估算值，實際費用請以官方帳單為準。
 
-> 截圖取自英文介面。完整功能說明請見[主 README](README.md)。
+> 截圖包含英文與簡體中文介面。完整功能說明請見[主 README](README.md)。
 
 ## 截圖
 
@@ -26,24 +26,65 @@
 
 ![儀表板](images/v2-dashboard-en.png)
 
+### v2.3.1 Codex 與比較
+
+![Claude 今日，簡體中文深色主題](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+![Codex 概覽，簡體中文深色主題](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+![Codex 每週額度估算，英文深色主題](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+![Claude 與 Codex 綜合熱力圖，英文淺色主題](images/v2.3.1/compare-heatmap-en-light.png)
+
+以上四張 v2.3.1 影像使用正式儀表板渲染器、合成資料與 VS Code Light+/Dark+ 主題變數產生，不是個人用量或帳單證據；原生 VSIX 安裝另行驗證。
+
+- Codex 狀態列分別顯示**今日已用 token**和**剩餘額度**：已用 36% 時顯示 `wk 64%`。提示卡保留使用進度條、重置時間與換行說明；額度是本地最後觀測，不是即時餘額。
+- 週期明細預設收合，分享設定位於預覽下方。分享工作台預設開啟、可關閉；色階可選分位數、對數或線性。
+- CLI 呼叫須留下帶 usage 的持久工作階段日誌才能計入。未保存的呼叫無法回填；今日與最近 30 天使用設定時區。
+
 ## 功能特色
 
 - **狀態列** — 今日成本、當前 session 成本，以及真實的 5 小時 / 每週配額（`5h:N% wk:N%`），透過 Claude Code 自身的 OAuth 工作階段讀取，無需設定。
-- **儀表板分頁** — 今日 / 本月 / 全部時間，外加 **Sessions / Projects / Content / Branches**，皆可排序。
+- **儀表板分頁** — 今日 / 最近 30 天 / 全部時間，外加 **Sessions / Projects / Content / Branches**，皆可排序。
 - **堆疊式成本構成圖**，含 Y 軸與參考線 —— 一眼看出每日 / 每月的成本中，輸入、輸出、快取寫入、快取讀取各佔多少。
 - **Content 分頁** — 估算哪些內容消耗你的 token（你的提示 vs 工具結果 vs 助理輸出 / 思考）。
-- **AI 建議**（選用）— 將用量摘要加上你近期提示的樣本送往 OpenAI 相容 API（預設 DeepSeek V4 Pro），給出具體改寫建議。需自備 key，或先預覽靜態示範。
+- **AI 建議**（選用）— 先呈現本機證據與可解釋行動。可選的自備金鑰個人化預設只含聚合資料；提示樣本需要另行同意。完整請求會先精確預覽，再由你另外按下「傳送」；有用 / 無用 / 已套用回饋只留在本機。單一建議可暫停有限期間，期間會從摘要移除，期滿或手動恢復後再顯示。
+  撤回建議的資料授權會立即使預覽失效並取消進行中的建議請求；已傳出的位元組無法收回。
 - **多廠商定價** — Opus 4.x / Sonnet 4.x / Haiku 4.5 對照 Anthropic 官方定價；OpenAI / Gemini / DeepSeek / Kimi / GLM / Qwen 參考價，含家族感知回退。`Refresh Token Pricing` 可拉取 LiteLLM 即時價格。
 - **個人化** — 語言、時區、小數位數、精簡數字、專案分組、儀表板自動刷新開關。
 
+## v2.3.1 新功能
+
+- 精確定價與上下文中繼資料現已涵蓋 **GPT-6 Astra**（`gpt-6-astra`，105 萬
+  token 上下文）以及 **Claude Fable 5.1 / Mythos 5.1**
+  （`claude-fable-5-1` / `claude-mythos-5-1`，100 萬 token 上下文）。
+  Fable 5.1 採用專屬的 `$0.25 / 百萬 token` 快取讀取價，既有 Fable 5
+  歷史資料不變。GPT-6 的 API 等效值採用官方 Standard 短上下文費率；由於
+  本機彙總日誌無法判定單次請求是否超過 272K 輸入，因此不計入該門檻以上的
+  整個請求附加價。
+- Claude 估算可選用 Anthropic 直連或 AWS Bedrock in-region 隨選費率，涵蓋目前
+  Opus、Sonnet 與 Haiku 系列；切換後端會立即按新費率重算未變更的本機日誌。
+  Sonnet 5 使用 2026 年 8 月 31 日上市優惠結束後的標準費率。
+- 最近 30 天是設定時區中的今天與前 29 個日期；總計可核對、重複重新整理穩定，月份由舊到新。Claude 的工作流程摘要使用同一滾動範圍，並依設定時區中的開始日期歸入週期。切換圖表指標或呈現下鑽標籤時，日／月用量鍵不會再受宿主時區影響而倒退一天或一個月；AI 建議與用量最佳化器的暫停截止日期也統一使用設定時區與介面語言。
+- 結構化 reasoning effort 不依模型名稱猜測；非零 `unknown` 會解釋，零值不顯示。
+- 有界匿名額度觀測保留不規則及同日重設；有效同窗比例可估算總額度與未用耐用度（包括目前週期）。近似或未歸屬證據標為低可信度。即使本機 Codex 額度系列重疊，目前週期仍採用最後一次真實觀測提供低可信度混合估算；歸屬不清的已結束週期維持僅已用值。
+- 「比較」預設顯示 Claude + Codex 綜合活動熱力圖，沿用日聚合，也支援單一供應商。
+- 預覽優先的分享工作台可匯出確定性本機 SVG、分享卡與 Markdown，並自訂標題/範圍、預覽隱私及調整配色。工作台預設開啟，可在設定用一個開關整體隱藏。預設 Academic Violet；色階映射可選分位數（預設）、對數或線性；GitHub 公開發佈另行確認精確目標。
+- Codex Token 構成現在會在互不重疊的「未快取輸入 / 快取輸入 / 輸出」堆疊上方明確顯示 **未快取用量**（未快取輸入 + 輸出）；推理仍是輸出的子集。
+- Codex 在索引期間也能順暢捲動：捲動狀態改為操作結束後只儲存一次，即時索引進度只更新文字，不再重建整頁。各模型折疊項的綠色摘要現在與 Claude 一致，顯示精確模型的 API 等效價格並附定價涵蓋說明；未知模型顯示 `—`，推理強度仍以中性色顯示未快取 Token。
+- OpenAI 相容的最佳化器請求現在只傳送 `reasoning_effort`，不再附帶不受支援的頂層 `thinking` 參數，解決 [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94)。
+- Claude/Codex 共用密度、層級、焦點、ARIA、窄幅與深淺色設計 token，但不混淆指標語義。
+
+已審閱的 Release 草稿為 `v2.3.1`；人工發佈工作流程會從該 tag 寫入套件版本。
+
 ## v2.3 Codex Beta
 
 - Codex 用量記錄只會從 `sessions/**/*.jsonl` 與 `archived_sessions/**/*.jsonl` 中發現；憑證、資料庫與未知檔案仍明確排除。此外，擴充功能會精確串流讀取 `$CODEX_HOME/session_index.jsonl`，僅將 `id` 對應到 `thread_name`，用於真實執行緒標題。標題中的絕對路徑會先去識別化，標題只保留在記憶體。用量 JSONL 會逐行串流並暫時解析，以擷取白名單內的用量與結構中繼資料；提示、回覆、命令和工具參數欄位不會被檢查或用於分析，也不會被保留或持久化。
 - **已處理** = 輸入 + 輸出；**未快取用量** = 未快取輸入 + 輸出；**快取輸入**仍是輸入的子集，reasoning 仍是輸出的子集。概覽也會依「快取輸入 / 輸入」顯示輸入快取命中率。Codex 不顯示帳單成本；首張摘要卡會針對目前範圍顯示明確標示的 API 等效成本估算，「全部時間」則依同一定價口徑顯示每週趨勢。Claude / Codex / Compare 仍維持各供應商口徑獨立。
-- Codex 的**今天**指設定時區中的目前自然日。頁面會顯示精確的每小時 API 等效成本，並將 Token 構成保留為獨立檢視；每日與每月主圖也預設顯示 API 等效成本，Token 構成仍分開呈現。只有精確符合的已知模型才參與計價，未知模型維持未定價，定價涵蓋率始終可見。這個相容 schema 3 的增量小時 sidecar 只處理已知包含今天用量的 canonical 檔案，支援檢查點與續傳，且不會觸發完整歷史重建。
+- Codex 的**今天**指設定時區中的目前自然日。頁面會顯示精確的每小時 API 等效成本，並將 Token 構成保留為獨立檢視；每日與每月主圖也預設顯示 API 等效成本，Token 構成仍分開呈現。只有精確符合的已知模型才參與計價，未知模型維持未定價，定價涵蓋率始終可見。這個相容 schema 3 的增量小時 sidecar 會保留最近 30 天的稀疏日期 / 小時分桶，支援檢查點與續傳、淘汰第 31 天，並在展開日期時不讀取 JSONL。Codex 按月圖表與表格會按月份由舊到新顯示。
 - 單次請求 Token 歸因優先採用有效的 `last_token_usage` component；其中 `total_tokens` 表示目前上下文大小，不是該次請求的用量。只有完整的 total-plus-last 數字簽名能證明同一假名化 rate-limit 來源或相鄰記錄發生重播時才去重；缺少 last snapshot 時回退為 cumulative lineage high-water。升級後會自動重建一次索引，期間持續顯示已索引小計。
-- Claude 與 Codex 的「全部時間」/「比較」會直接依本機 Token 日誌計算歷史已用等價值。最新且有效的官方重設觀測只會錨定一組唯一、互不重疊的每週週期，每筆用量只計入一個週期；沒有可用觀測時，僅已用歷史才回退到 UTC 週一至週一的自然週。任何重疊但未對齊的未來重設都會視為衝突，即使 series 名稱不同，也不能再建立第二個「目前週期」；週期範圍與重設時刻會分開呈現。Codex 用量按日切片保存：若某個切片跨過官方日內重設，其 Token 仍只計一次，受影響週期會標為「邊界近似」，並且只顯示已用等價值，不反推總額度或未用額度。此顯示規則不改變索引 schema，也不會觸發重建。Codex 歷史週期一律只顯示已用值；只有最新目前週期在重設無衝突，且已索引用量可可靠歸屬到單一觀測來源時，才允許反推總額度，目前未用值仍不作為結論。無法歸屬的多登入用量同樣只顯示已用值，不會虛構帳號拆分。歷史統一套用目前官方 API 單價；這是代理估算，不是帳單或官方訂閱價格。此面板預設開啟，可在設定中透過 `showWeeklyEquivalentValue` 關閉。Claude 從此版本開始依本機 profile 記錄額度觀測。
-- 切換到 Codex 後仍沿用既有的今天 / 本月 / 全部時間 / 工作階段 / 專案 / 內容 / 設定結構，並依 Codex 語義調整標籤。兩個供應商共用同一組 render function、HTML class、圖表、表格、間距與響應式規則；時間序列圖維持寬度對齊，密集內容只在各自區域內捲動。Codex 建議使用已索引的 30 天結構化證據。
+- Claude 與 Codex 的「全部時間」/「比較」會直接依本機 Token 日誌計算歷史已用等價值。最新且有效的官方重設觀測會錨定一組唯一、互不重疊的每週週期，每筆用量只計入一個週期；沒有可用觀測時，僅已用歷史才回退到 UTC 週一至週一的自然週。只有真正不同的 quota series 且其未來重設重疊、未對齊時才視為衝突；同一 series 的觀測仍維持為一個 series，並可按低可信度近似顯示，不會再建立第二個「目前週期」。週期範圍與重設時刻會分開呈現。Codex 的 account-wide `codex` 觀測可同時裝飾歷史與目前週期；若重設時間偏離七天網格，就依觀測時間映射到對應展示週期。檔案來源、重設漂移或日切片跨邊界時仍可給出總額度近似，但會降低可信度並標示為近似。檔案鍵不是帳號身分，因此同一個 home 中符合條件的本機檔案會一起參與；即使本機 quota series 重疊，目前週期仍採用最後一次真實觀測提供低可信度混合估算；歸屬不清的已結束週期或沒有可用觀測的週期維持僅已用值，不會虛構帳號拆分。任何內部一致且有觀測的週期（包括目前週期）都可顯示總額度與未用耐用度估算；歸屬或邊界不確定時降低可信度，而不是靜默顯示破折號。Codex 用量按日切片保存，Token 仍只計入一個週期；此顯示規則不改變索引 schema，也不會觸發重建。歷史統一套用目前官方 API 單價；這是代理估算，不是帳單、官方餘額或官方訂閱價格。此面板預設開啟，可在設定中透過 `showWeeklyEquivalentValue` 關閉。Claude 從此版本開始依本機 profile 記錄額度觀測。
+- 切換到 Codex 後仍沿用既有的今天 / 最近 30 天 / 全部時間 / 工作階段 / 專案 / 內容 / 設定結構，並依 Codex 語義調整標籤。兩個供應商共用同一組 render function、HTML class、圖表、表格、間距與響應式規則；時間序列圖維持寬度對齊，密集內容只在各自區域內捲動。Codex 建議使用已索引的 30 天結構化證據。
 - 根任務使用經過路徑去識別化的最新真實執行緒標題；子任務優先使用自己的真實執行緒標題，缺少時使用其回報的暱稱並顯示父級 / 根任務標題；這些資訊仍缺少時採用本地化的中性回退名稱。專案名稱使用 Git 儲存庫名稱，非 Git 目錄則使用資料夾的末級名稱。擴充功能不會虛構無法可靠統計的 Branches 或 Workflows。
 - 最近 7 天與 30 天依設定時區中的事件發生日精確切片。遷移或重建未完成時，Codex 的卡片、表格、專案、工作階段、建議與狀態列都會明確標為**已索引小計**，並排除未驗證的舊版總量。偵測到 Codex home 後會立即顯示供應商分頁；首次建立索引期間會在頁面內即時顯示精確的已索引檔案數、百分比與容量進度，「比較」則等到兩個供應商都有真實資料後才出現。產生第一個原子檢查點後，完整的小計儀表盤會在索引繼續期間保持可用；進度提示不會取代卡片和表格。所選 Codex home 不區分帳戶，因此同一目錄中多個登入帳戶留下的記錄會合併統計；本機記錄沒有可靠的帳戶身分欄位，額度卡只能保留**最後觀測**，不會相加。
 - 每則建議只在已索引的 30 天結構聚合有證據時顯示觀測、易讀證據和條件式行動；沒有證據就不會產生泛化建議。
@@ -69,15 +110,36 @@ ext install GrowthJack.claude-code-usage
 - `usageLimitTracking` — 顯示真實的 5 小時 / 每週配額指示器。
 - `showCost` / `showContext` — 切換狀態列的成本項目與上下文視窗佔用指示器（類似 `/context`）。
 - 上述狀態列項目皆可個別隱藏：將 `usageLimitTracking` / `showCost` / `showContext` 設為 `false` 即可只隱藏該項。
-- `advice.apiKey` — AI 建議功能的 API key（OpenAI 相容）。
+- `advice.apiKey` — AI 建議與 Usage Optimizer 共用的自備 API key（Anthropic 或 OpenAI 相容 endpoint）。
 - `pauseDashboardRefresh` — 暫停儀表板自動刷新（也可在儀表板標題列切換）。
 
 完整設定表請見[主 README](README.md#configuration)。
 
+## 本機資料、隱私與限制
+
+完整清單、保留期、遷移、清除及遠端邊界見
+[本機資料與隱私](LOCAL-DATA.zh-CN.md)（[English](LOCAL-DATA.md)）。
+
+| 資料 | 本機保留 | 遠端行為 |
+|---|---|---|
+| 來源日誌 | 供應商擁有、唯讀，不整份複製 | 預設無 |
+| Codex 索引 | 有界假名化數值/結構聚合 | 無 |
+| 額度歷史 | 有界匿名窗口觀測，不含原始帳號 ID | 啟用時僅 Claude 查詢額度；Codex 證據留在本機 |
+| UI/分享 | 篩選與可選標題/範圍/GitHub 目的字串 | 僅在精確確認後發佈 |
+| 建議/金鑰 | 有界聚合證據；金鑰僅在 SecretStorage | 另行傳送精確預覽的請求 |
+
+未出現在結構化證據中的重設無法重建；多登入歸屬不清時，目前週期會用最後一次真實觀測提供低可信度混合估算，已結束週期維持僅已用值。
+API 等效價值不是帳單。來源日誌保留由 Claude Code/Codex 控制，明確清除才是移除擴充功能派生狀態的可靠方式。
+
 ## 疑難排解
 
 **「無 Claude Code 資料」** — 確認 Claude Code 已安裝並至少使用過一次；檢查 `dataDirectory` 設定（自動偵測會查 `~/.claude/projects`）。
 
+**一次性 Claude CLI 呼叫沒有計入** — 使用 `--no-session-persistence` 的呼叫
+可能只留下提示歷史，不會寫入專案轉錄，也沒有 token `usage` 欄位。本擴充功能
+不會根據提示歷史虛構 token 或成本。希望之後的審計呼叫計入時，請不要使用該參數；
+過去未持久化的 token 用量無法在本機重建。
+
 **配額顯示 `5h:--% wk:--%`** — 請登入目前的 Claude profile。憑證依序跟隨
 明確設定的 `dataDirectory`、第一個有效的 `CLAUDE_CONFIG_DIR`、最後
 `~/.claude`；全域 macOS 鑰匙圈項目只用於預設 profile。
diff --git a/README.md b/README.md
index b8c0594c..5a888726 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,45 @@ the same data.
 
 ## Screenshots
 
-### Status bar
+### v2.3.1 Claude, Codex and Compare
+
+The four v2.3.1 images below are reproducible captures of the production dashboard
+renderer with synthetic fixtures and VS Code Light+/Dark+ theme variables, not
+personal usage or billing evidence. Native VSIX installation is verified separately.
+
+![Claude Today in Simplified Chinese, dark theme](images/v2.3.1/claude-today-zh-CN-dark.png)
+
+*Today and Last 30 days share the configured calendar timezone. CLI usage is
+counted only when normal persistent sessions leave usage-bearing local logs;
+calls made without session persistence cannot be reconstructed.*
+
+![Codex overview in Simplified Chinese, dark theme](images/v2.3.1/codex-overview-zh-CN-dark.png)
+
+*The corrected Codex overview uses one configured-timezone calendar model for
+Today, Last 30 days, months, models, effort, and all-time totals.*
+
+![Codex weekly allowance estimate in English, dark theme](images/v2.3.1/codex-weekly-estimate-en-dark.png)
+
+*Observed quota windows retain reset evidence locally. A valid used fraction can
+produce labelled total and unused subscription-durability estimates, including
+for the current window. Approximate evidence remains visible with low confidence.
+Period details start collapsed; expand them to inspect the numeric evidence.*
+
+![Combined Claude and Codex heatmap in English, light theme](images/v2.3.1/compare-heatmap-en-light.png)
+
+*Compare combines provider daily activity without double-counting Codex cached
+input or reasoning. Its preview-first share studio offers an Academic Violet
+default, curated/custom colors, deterministic local SVG, and privacy-safe
+Markdown. It is enabled by default and can be hidden with the single sharing
+workspace setting. Card settings sit below the preview; intensity can use quantile,
+logarithmic, or linear scaling. The metric is activity volume, not productivity or billing.*
+
+### Claude status bar
+
+Codex uses a compact **Today token usage** item and a separate **remaining quota**
+item: observed 36% weekly utilisation displays `wk 64%`. The hover card retains
+utilisation progress bars, reset times, and wrapped explanations. Local Codex
+quota is last-observed evidence, not a live account balance.
 
 ![Status bar](images/v2-status-bar-en.png)
 
@@ -73,14 +111,24 @@ tool results (by tool) vs. assistant output / thinking. This is the lever
 for optimising your usage. Scoped to the last 30 days
 (`advice.promptWindowDays`).*
 
-### AI advice — a coaching report from your real usage
+### AI advice — evidence first, sending optional
+
+v2.3.1 keeps one readable path from a local observation to its
+evidence, recommendation, action, feedback, and guarded result. It is off by
+default. Local evidence appears before any model is involved; **Helpful**, **Not
+helpful**, and **Applied** stay on this device. Once enough reliable, similar
+before/after tasks exist, the card reports the frozen comparison result;
+otherwise it says that the evidence is insufficient.
+
+Each recommendation can be snoozed for a bounded period; it leaves the default
+summary and returns after expiry or when you choose to show it again.
 
-AI advice writes you a **Markdown document**, so it reads better as text than as
-a screenshot. Set a key (`advice.apiKey`), click **Get AI advice** (the ✨ button
-or the card on the Content tab), pick a scope (all projects, or one), and it sends
-your usage aggregates + a sample of *your own* prompts to your model and opens a
-prioritised report. Bring your own key — Anthropic (`/v1/messages`) by default, or
-any OpenAI-compatible endpoint.
+AI personalisation is a separate choice. Aggregate-only is the default and
+prompt samples remain off until separately allowed. The extension prepares the
+complete request once and shows its exact JSON, byte count, and SHA-256. Preview
+sends nothing; **Send this exact request** is a second explicit action, using the
+same canonical bytes and your own configured key/endpoint. Claude Code OAuth
+credentials are never used as a generative backend.
 
 A flavour of what it returns (illustrative):
 
@@ -101,11 +149,94 @@ Paste a rough, half-formed request; get back one clean, **paste-ready** prompt
 (plain text, no Markdown) plus a recommended reasoning effort / thinking / model
 shown as chips. Three optional toggles refine it (flag vague references · condense
 long pastes · suggest a style direction). Experimental, off by default; **only the
-text you paste is sent** — never your files or the terminal — behind a one-time
-consent prompt.
+text you paste is included** — never your files or the terminal. It now uses the
+same full-request preview and separate explicit Send action as AI advice.
 
 ---
 
+## What's new in v2.3.1
+
+- **GPT-6 Astra and Fable 5.1 support** — exact pricing and context metadata now
+  cover `gpt-6-astra` (1.05M context) and `claude-fable-5-1` /
+  `claude-mythos-5-1` (1M context). Fable 5.1 uses its model-specific
+  `$0.25 / MTok` cache-read rate without changing historical Fable 5 data.
+  GPT-6 API-equivalent values use official Standard short-context rates; the
+  request-wide surcharge above 272K input is excluded because aggregate local
+  logs cannot establish that per-request threshold.
+- **Optional AWS Bedrock pricing** — Claude estimates can use direct Anthropic
+  or AWS Bedrock in-region on-demand rates for current Opus, Sonnet, and Haiku
+  families. Switching the backend reprices unchanged logs immediately; Sonnet
+  5 uses the standard rate after its launch promotion ended on 31 August 2026.
+- **Correct, stable date ranges** — Last 30 days means today plus the preceding
+  29 calendar dates in the configured timezone. Today ≤ Last 30 days ≤ All time,
+  provider totals reconcile, repeated refresh/reindex is idempotent, and Codex
+  monthly charts/tables run oldest-first. Claude's Workflows summary uses that
+  same rolling range and assigns each run by its configured-zone start date.
+  Chart metric switches and drill-down labels render daily/monthly usage keys
+  without host-timezone rollback; Advice and Optimizer snooze dates also use
+  the configured timezone and UI locale.
+- **Truthful effort attribution** — legacy and current structured effort fields
+  normalize without guessing from model names. A non-zero `unknown` bucket is
+  explained; a zero bucket is not rendered.
+- **Reset-aware weekly estimates** — bounded, atomically written quota
+  observations preserve reset-time/window changes and significant usage drops,
+  including consecutive and same-day resets. Every valid same-window used
+  fraction contributes an observed full-allowance estimate. Coherent current and
+  completed windows show total and unused durability estimates; approximate or
+  unattributed evidence is labelled low confidence. If local Codex series
+  overlap, the current window uses the latest real observation for a labelled
+  low-confidence blended estimate; ambiguous completed windows remain
+  usage-only. Unused value never goes negative.
+- **Combined heatmap in Compare** — Claude and Codex daily processed volume is
+  merged with provider components visible in every tooltip. It works with both
+  providers or either provider alone and reuses existing aggregates instead of
+  scanning logs again.
+- **Private share loop** — use the preview-first studio to customize title,
+  30/90-day or yearly range, and heatmap colors. Academic Violet is the default;
+  choose quantile (default), logarithmic, or linear intensity mapping to suit
+  the activity distribution. Inspect the privacy preview, export deterministic
+  SVG, and copy a Markdown snippet. Optional public-GitHub publication is a
+  separate exact-destination confirmation; local export needs no account
+  permission.
+- **Explicit Codex uncached composition** — Token composition shows uncached
+  usage (uncached input + output) above the non-overlapping uncached-input /
+  cached-input / output stack; reasoning remains a subset of output.
+- **Smooth live Codex dashboard** — scroll state is saved once after a gesture,
+  and active index progress updates its text in place instead of rebuilding the
+  page. Per-model disclosure headlines now use Claude's green-money convention:
+  exact-model API-equivalent price with coverage help; unknown models show `—`,
+  while effort headlines keep neutral uncached-token values.
+- **OpenAI reasoning compatibility** — OpenAI-compatible optimizer requests
+  send `reasoning_effort` without the unsupported top-level `thinking`
+  parameter, resolving [#94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94).
+- **Aligned dashboard interaction** — shared density, headings, disclosures,
+  charts, empty states, keyboard focus, ARIA behavior, narrow layout, and
+  light/dark design tokens keep Claude and Codex consistent without claiming
+  their metrics are semantically equivalent.
+- **One advice loop** — local evidence, explainable recommendations, optional
+  exact BYOK preview/send, device-local feedback, and versioned comparable-task
+  results share one boundary. Get AI Advice opens this surface; the Optimizer
+  reuses its preview/send/cancel/strict-parse behavior instead of forming a
+  third network path.
+- **No automatic AI traffic** — the feature is off by default, aggregate consent
+  and prompt-personalisation consent are separate, and a request crosses the
+  network only after the user previews it and clicks Send.
+  Withdrawing advice consent immediately invalidates previews and cancels active
+  advice requests; it cannot recall bytes already transmitted.
+- **Resumable first-use work** — Codex history and the rolling 30-day hour
+  migration show why they are running, persist progress/failure/backoff state,
+  and do not restart equivalent work after completion or on every refresh.
+- **Thirty-day hour drill-down** — any populated Codex day in the last 30 days
+  expands from the existing index with zero JSONL reads on click. Claude and
+  Codex use the configured timezone and the same `HH:00` labels.
+- **Safe rolling totals and resumable indexing** — recent 7/30-day views reject
+  stale/inflated period projections and use verified daily aggregates until the
+  zone projection catches up. First-use work persists bounded progress and does
+  not hot-loop or repeat after completion.
+
+The reviewed draft is `v2.3.1`; the human-controlled publish workflow stamps
+package metadata from that release tag.
+
 ## What's new in 2.3
 
 - **Codex Beta, enabled by default** — usage records are discovered only from
@@ -130,8 +261,9 @@ consent prompt.
   API-equivalent cost while token composition stays separately visible. Only
   exact known-model prices contribute; unknown models remain unpriced and every
   row keeps pricing coverage visible. The schema-3-compatible hourly sidecar
-  processes only canonical files already known to contain today, is checkpointed
-  and resumable, and does not force a full-history reindex.
+  keeps sparse buckets for the rolling last 30 days, is checkpointed and
+  resumable, evicts day 31, and serves date expansion with zero JSONL reads on
+  click. Codex monthly charts and tables list months oldest-first.
 - **Request-level token attribution** — valid `last_token_usage` components are
   preferred, while its `total_tokens` remains an active-context measurement,
   not request usage. A full numeric total-plus-last signature suppresses only
@@ -143,22 +275,31 @@ consent prompt.
   newest valid official reset observation anchors one sequence of unique,
   non-overlapping weekly periods, and each usage event belongs to exactly one
   period; without a usable observation, usage-only rows fall back to
-  Monday-to-Monday UTC calendar weeks. Any overlapping, non-aligned future reset
-  is a conflict even if its series name differs; it cannot create a second current
-  period, and period ranges are shown separately from reset times. Codex usage is
+  Monday-to-Monday UTC calendar weeks. A genuinely different quota series with
+  an overlapping, non-aligned future reset is a conflict; same-series observations
+  remain one series and may be shown as a low-confidence approximation. It cannot
+  create a second current period, and period ranges are shown separately from reset times. Codex usage is
   stored in daily slices: when one crosses an official intraday reset, its tokens
   are still counted once, the affected period is labelled a boundary
-  approximation, and only used equivalent is shown. This display rule neither
-  changes the index schema nor triggers a rebuild. Codex historical periods are
-  always used-value-only. Only the newest current period may infer a total when
-  the reset is unambiguous and indexed usage can be attributed to one observation
-  source; current unused value is still withheld. Multi-sign-in usage that cannot
-  be attributed reliably also remains used-only, without inventing an account
-  split. Current official API rates are applied consistently across history. This
-  is a proxy, not a bill or an official subscription price. The panel is enabled
-  by default and can be hidden in Settings with `showWeeklyEquivalentValue`.
+  approximation. Codex's account-wide `codex` observations can decorate both
+  historical and current buckets. If an observed reset drifts from the seven-day
+  grid, the sample is mapped to the display period containing its observation
+  time; file-source uncertainty, reset drift, and daily boundary crossings lower
+  confidence and are labelled as approximate. File keys are not account
+  identities, so eligible local files in one home are included together. A
+  current period still uses the latest real observation for a low-confidence
+  blended estimate when local quota series overlap. Ambiguous completed periods,
+  or periods without a usable observation, remain usage-only rather than
+  inventing an account split. Any coherent
+  observed window—including the current one—can show total and unused durability
+  estimates; attribution or boundary uncertainty lowers confidence instead of
+  silently replacing the values with dashes.
+  This display rule neither changes the index schema nor triggers a rebuild.
+  Current official API rates are applied consistently across history. This is a
+  proxy, not a bill or an official subscription price. The panel is enabled by
+  default and can be hidden in Settings with `showWeeklyEquivalentValue`.
 - **One dashboard render stack** — switching to Codex keeps the established
-  Today / Month / All time / Sessions / Projects / Content / Settings structure,
+  Today / Last 30 days / All time / Sessions / Projects / Content / Settings structure,
   relabelled where Codex semantics differ. The same render functions, HTML
   classes, charts, tables, spacing, and responsive rules are used for both
   providers. Claude and Codex time-series charts stay width-aligned while dense
@@ -284,20 +425,19 @@ consent prompt.
   cap actually named by Anthropic, such as `fable 17%`; migrated from the
   original model-specific contribution in PR #38 by
   [@wheelbarrel00](https://github.com/wheelbarrel00).
-- **AI advice 2.0** — bring your own key: **Anthropic** (`/v1/messages`) by
-  default, or any OpenAI-compatible endpoint (`advice.apiFormat`). Fed with the
-  new signals (runs, cache hit rates, attribution, thinking share); optional
-  `advice.userContext` adds a "Personalised for this project" section;
-  `advice.promptWindowDays` (default 30) sets the sampling window. Transport
-  hardened: timeout, retry, curl fallback. *(A keyless "subscription" backend
-  was prototyped but isn't shipped — Anthropic blocks calling the API with the
-  Claude Code OAuth token; it may return if that changes.)*
+- **AI advice 2.0** — bring your own key for Anthropic or an OpenAI-compatible
+  endpoint (`advice.apiFormat`). v2.3.1 places local evidence and an exact full-
+  request preview before the separate Send action. Aggregate-only is the
+  default; prompt samples and `advice.userContext` require independent prompt-
+  personalisation consent and appear verbatim in the preview. The keyless
+  Claude Code subscription backend is not shipped and is unreachable.
 - **Usage Optimizer** (experimental, `advice.optimizer.enabled`, default off) —
   a Content-tab card where you paste a rough request and get back one tightened
   prompt as **plain text** (paste-ready, no Markdown) plus a recommended effort
   / thinking / model. Three optional lenses (flag ambiguous references ·
   condense long pastes · suggest a style direction). **Only the text you paste
-  is sent**, behind a one-time consent prompt.
+  is included**, and the full provider request must be previewed and explicitly
+  sent.
 - **Context-window indicator** (experimental, off by default) — opt in via
   Settings to show the current session's context fill in the status bar. A "~"
   marks a guessed window; set `contextWindowOverride` for proxied/custom models.
@@ -312,8 +452,9 @@ consent prompt.
   by [@Dobidop](https://github.com/Dobidop).
 - **Four new tabs**: Sessions, Projects, Content, Branches — all sortable.
 - **Token-composition stacked chart** with Y-axis and reference lines.
-- **AI advice command** (DeepSeek V4 Pro default, `reasoning_effort=max`)
-  with a demo-mode fallback when no API key is configured.
+- **AI advice command** — now routes to the unified local-evidence surface; a
+  missing API key leaves the request unsent instead of opening a separate demo
+  or transport path.
 - **Multi-vendor pricing**: Opus 4.x, Sonnet 4.x, Haiku 4.5 (verified
   against Anthropic's public pricing); reference rates for proxied setups
   (OpenAI, Gemini, DeepSeek, Kimi, GLM, Qwen) with family-aware fallback.
@@ -372,7 +513,7 @@ for **`Claude Code Usage`**:
 | `language` | `"auto"` | UI language: `auto` / `en` / `de-DE` / `zh-TW` / `zh-CN` / `ja` / `ko` / `pt-BR` / `id`. |
 | `dataDirectory` | `""` | Custom Claude data dir; empty = auto-detect. |
 | `codex.dataDirectory` | `""` | Custom Codex home; empty = `CODEX_HOME` or `~/.codex`. |
-| `advice.apiKey` | `""` | API key for AI advice + the Usage Optimizer (empty = advice opens a demo instead). |
+| `advice.apiKey` | `""` | Bring-your-own key for AI advice + the Usage Optimizer; empty means no request can be sent. |
 
 Everything else — refresh interval, status-bar items, number/date formatting,
 project grouping, content analysis, and all the AI advice / Optimizer options —
@@ -417,6 +558,17 @@ authoritative.
 
 ## Privacy
 
+The complete user-facing inventory, retention rules, clearing behavior, and
+remote boundaries are in [Local data and privacy](LOCAL-DATA.md) ([简体中文](LOCAL-DATA.zh-CN.md)).
+
+| Data | Stored locally | Remote behavior | Clear path |
+|---|---|---|---|
+| Claude/Codex source logs | Provider-owned and read-only; never copied wholesale | None by default | Managed by the provider tools, not deleted by this extension |
+| Codex derived index | Bounded pseudonymous numeric/structural aggregates | None | Rebuild or clear derived index |
+| Quota observations | Bounded anonymous window facts; no raw account ID | Claude quota fetch only when enabled; Codex evidence stays local | Clear by provider/account epoch or all |
+| UI/share preferences | Tab/filter state plus optional title/range and GitHub destination strings | Publish only after exact explicit confirmation | Reset UI or sharing preferences independently |
+| Advice data/key | Bounded aggregate evidence; key only in SecretStorage | Exact previewed request only after separate Send | Clear advice data and key independently |
+
 - All **Claude** token / cost / session analysis runs locally by reading your
   `~/.claude/projects/**/*.jsonl` files.
 - Codex usage records are discovered only from `sessions/**/*.jsonl` and
@@ -435,13 +587,25 @@ authoritative.
 - The quota indicator calls **`api.anthropic.com/api/oauth/usage`** using
   Claude Code's existing OAuth token. No additional credentials are sent.
 - **AI advice** and the **Usage Optimizer** are the only features that call a
-  model — and only when *you* trigger them. AI advice sends an aggregate
-  summary of your usage plus a sample of your recent prompts; the Optimizer
-  sends **only the text you paste into it** (never your files or the terminal),
-  behind a one-time consent prompt. Both send to the endpoint in `advice.apiUrl`
-  with your own `advice.apiKey` (Anthropic `/v1/messages` by default, or any
-  OpenAI-compatible endpoint). **Bring your own key**; nothing is shipped with
-  the extension.
+  model — and only after *you* preview and explicitly send a prepared request.
+  Advice defaults to allowlisted aggregates; prompt samples and optional user
+  context require separate consent. The Optimizer includes **only the text you
+  paste into it** (never your files or terminal). Both use the exact previewed
+  bytes, the endpoint in `advice.apiUrl`, and your own `advice.apiKey`.
+  **Bring your own key**; no key or generative OAuth credential is shipped.
+
+### Known limits
+
+- A reset absent from an official response or local structured event cannot be
+  reconstructed; day-only evidence lowers confidence.
+- One Codex home may contain several sign-ins. The current period may therefore
+  show a low-confidence blended estimate from the latest real observation;
+  ambiguous completed periods remain used-only rather than inventing an account split.
+- API-equivalent values depend on current known API prices and visible pricing
+  coverage. They are not bills or subscription prices.
+- Source-log retention belongs to Claude Code and Codex. Uninstall may leave
+  host-managed extension storage behind, so the explicit clear controls are the
+  reliable deletion route.
 
 ---
 
@@ -452,6 +616,13 @@ authoritative.
 - Check the `dataDirectory` setting; auto-detection looks at
   `~/.claude/projects` and `~/.config/claude/projects`.
 
+**One-shot Claude CLI activity is missing**
+- Calls made with `--no-session-persistence` can leave a prompt-history entry
+  but no project transcript and no token `usage` fields. The extension does not
+  invent token or cost totals from prompt history. Run future audited calls
+  without that flag if they should appear; past unpersisted token usage cannot
+  be reconstructed locally.
+
 **Quota row shows `5h:--% wk:--%`**
 - Claude Code's OAuth token is missing or expired. Log in to the active Claude
   profile once. Credentials follow explicit `dataDirectory`, then the first
@@ -463,10 +634,10 @@ authoritative.
   `https://api.deepseek.com/chat/completions`. The extension auto-strips
   `/v1` if present.
 
-**`Get AI Usage Advice` shows demo instead of real advice**
-- AI advice needs a key. With no key under `claudeCodeUsage.advice.apiKey`, the
-  command opens a hand-written demo (filename-marked `…-DEMO-…`, with a prominent
-  banner) instead of calling any API. Add a key in Settings to get real advice.
+**`Send this exact request` is unavailable**
+- Enable the default-off advice-effectiveness setting, allow aggregate data,
+  and configure your own `claudeCodeUsage.advice.apiKey`. Previewing is always
+  local; without a key the request remains unsent.
 
 **High CPU or sluggish refresh on a large history (Linux included)**
 - V2.2.1 removes the hidden 8-second active polling override and bounds the
diff --git a/docs/releases/2026-09-01-v2.3.1-goal-ledger.en.md b/docs/releases/2026-09-01-v2.3.1-goal-ledger.en.md
new file mode 100644
index 00000000..678e2a08
--- /dev/null
+++ b/docs/releases/2026-09-01-v2.3.1-goal-ledger.en.md
@@ -0,0 +1,341 @@
+# Claude Code Usage v2.3.1 Goal Ledger
+
+This tracked ledger records G0–G6 stage status, reproducible acceptance evidence, read-only Claude CLI reviews, and residual risk. It never stores accounts, credentials, real logs, prompts, thread titles, or local paths.
+
+## Execution boundary
+
+- Branch: `codex/v2.3.1-goal-g0-g6`
+- Baseline: `7fd03f3183240940d0a2d1cfe76f60cb80f0a6ae`
+- Workspace: isolated worktree; the user's primary checkout and pre-existing edits remain read-only.
+- Allowed: local code/document changes, tests, builds, VSIX packaging, stage commits, and the specified read-only Claude CLI checkpoints.
+- Forbidden: push, Marketplace publication, remote releases, real GitHub writes, or uploading user logs and identity data.
+
+## Stage status
+
+| Stage | Status | Local commit | Verification | Claude review | Residual risk |
+|---|---|---|---|---|---|
+| G0 baseline and fixtures | Complete | `f0af506` | Node 795 passed / 1 skipped; UI 90 passed; targeted 29 passed | N/A | No blocking risk |
+| G1 data contract | Complete | `86d95df` | Focused 17 passed; Node 806 passed / 1 skipped; compile passed | Conditional GO, then revision GO | Blocked legacy workspace plaintext remains until explicit recovery; host SecretStorage backing varies; unified quota store is a G3 deliverable |
+| G2 statistics/order/effort | Complete | `49f2041` | Node 815 passed / 1 skipped; UI 90 passed; all focused regressions passed | N/A | Unified observation/account attribution remains a G3 concern |
+| G3 quota observations/estimates | Complete | `a04ab04`, `4672079` | Node 841 passed / 1 skipped at exit; installed-candidate regression: quota/weekly 49 passed | GO, then revision GO | Quarantined corrupt/future files remain on disk until the data-clear path or a future cleanup policy removes them |
+| G4A visual/interaction/accessibility | Complete | `fca21da` | Node 841 passed / 1 skipped; UI 107 passed; focused G4A 68 passed | N/A | Provider-native metric semantics and card counts intentionally remain different |
+| G4B combined heatmap/share | Complete | `1e6bbab`, `5e5bf9f` | Node 861 passed / 1 skipped; UI 112 passed; focused 69 + 5 passed | GO, then revision GO | GitHub `public_repo` remains account-wide for public repositories; local SVG/Markdown requires no scope and is the default safe path |
+| G5 README/screenshots | Complete | `e9a149a` | Node 865 passed / 1 skipped; UI 112 passed; three installed-candidate screenshots inspected | GO TO G6 | Final packaging evidence belongs to G6 |
+| G6 release candidate | Complete | `b435e06`, `5e6e5cc`, `5af60b4`, `666f04c` | Latest regression candidate: Node 902 passed / 1 skipped; UI 117 passed; VSIX policy, visual QA, and isolated stock-host install passed | Regression first review NO-GO; revision review: **GO** | Hands-on empty-data Settings, legacy plaintext-key upgrade, and Clear All checks remain; broader interaction parity is assigned to the v2.4 roadmap |
+
+## G0 baseline evidence
+
+### Environment and tests
+
+- Node: `v24.19.0`
+- npm: `11.17.0`
+- `npm ci`: successful.
+- `npm run test:node`: 796 tests, 795 passed, 0 failed, 1 skipped. Two loopback `EPERM` failures in the first restricted run were test-sandbox artifacts; both passed when the local test servers were allowed to bind.
+- `npm run test:ui`: 90/90 passed.
+- Baseline worktree: clean.
+
+### v2.3.1 minimum regression fixture registry
+
+| Risk | Fixed input/test | Acceptance fact |
+|---|---|---|
+| Last 30 days exceeds all time | `codexUsage.test.ts`: `an inflated period sidecar falls back to the verified daily aggregate`; `v2.3.1 acceptance fixture keeps non-negative ranges monotonic and reconciled` | `today ≤ last30Days ≤ allTime`; daily/monthly totals reconcile |
+| Reindex double counting | `codexIndex.test.ts`: `fully indexed unchanged corpus returns a warm no-op without body reads`; `cold scan, appended tail, and persisted reload agree` | Repeated refresh is a stable no-op and reload preserves totals |
+| Active/archive duplication | `codexIndex.test.ts`: `exact active and archive copies contribute usage only once` | Identical content contributes once and dedup coverage is reported |
+| Month ordering | `codexUsage.test.ts`: `all-time, monthly, and behavior views stay provider-native` | Chart/table source rows are chronological |
+| Consecutive/irregular quota resets | `codexQuotaHistory.test.ts`: `irregular reset boundaries survive polling compaction`; fresh/irregular reset fixtures in `weeklyValue.test.ts` | Distinct resets remain distinct and windows are not double-counted |
+| Unknown reasoning effort | Current, legacy, missing, and unsafe context fixtures in `codexParser.test.ts`; `missing model and effort values are grouped as unknown` in `codexUsage.test.ts` | Parseable values survive; only missing or safely rejected values become unknown |
+
+### G0 exit gate
+
+- [x] Isolate the candidate and leave the user checkout untouched.
+- [x] Record branch, HEAD, status, and baseline tests.
+- [x] Register automated fixtures for every known regression family.
+- [x] Add a cross-view non-negative, monotonic, daily/monthly reconciliation assertion.
+- [x] Commit the G0 ledger and acceptance assertion (`f0af506`).
+
+## G1 local-data and privacy evidence
+
+### Contract and implementation
+
+- Added the bilingual normative local-data contract covering raw sources, indexes, derived statistics, quota observations, reset events, UI/share preferences, schema migration, retention, clearing, and every remote boundary.
+- Defined anonymous account fingerprints, atomic/deduplicated observation writes, per-account isolation, and the prohibition on credentials, complete identifiers, raw CLI output, and private source content.
+- Moved the advice BYOK key from contributed configuration/globalState into VS Code SecretStorage. Webview snapshots expose only `configured`, and the password field never rehydrates a stored secret.
+- Migration inspects Global, current Workspace, and every open Workspace Folder. It automatically migrates only one unambiguous machine-wide value, writes secure storage first, clears plaintext second, and fails closed with localized recovery copy on workspace-only, conflicting, or provider-failure cases.
+
+### Verification and review
+
+- Focused privacy/contract suite: 17 passed.
+- Full Node suite on an isolated loopback port: 807 tests, 806 passed, 0 failed, 1 filesystem-capability skip.
+- Claude CLI first review: conditional GO, requesting complete scope enumeration, concurrency/idempotency protection, fixed failure UX, and explicit Settings Sync evidence.
+- Revision review: GO to G2 with no blocker. Non-blocking caveats about blocked workspace plaintext and host-dependent SecretStorage backing are now explicit in the contract.
+
+### G1 exit gate
+
+- [x] Track a bilingual normative data contract in the repository.
+- [x] Make every persisted data class, retention rule, clear path, and remote interaction auditable.
+- [x] Migrate the only credential to SecretStorage without exposing it to Webview state.
+- [x] Fail closed and preserve recoverability for ambiguous or failed legacy migration.
+- [x] Pass the G1 test gate and Claude revision review.
+
+## G2 entry audit
+
+The following implementation risks are test hypotheses, not accepted behavior. Each must first be reproduced by a minimal fixture before its implementation changes:
+
+1. Weekly pricing coverage appears to use the whole window rather than the observation-time prefix.
+2. Exact-content deduplication does not include day/period distribution and can collapse records with equal totals but different dates.
+3. A `codex-spark` limit may be classified account-wide when its scope is model-specific.
+4. A delayed post-reset current observation may mask a valid cached pre-reset observation.
+5. Cumulative-delta repair may permit `reasoning > output` or `cached input > input`.
+6. Residual usage in a partial effort map may disappear instead of being attributed to `unknown`.
+
+Additional guards cover the complete 30-day definition in the configured timezone, cross-year chronological month order, alias/invalid reasoning-effort variants, and conservation across daily, monthly, model, effort, and total views.
+
+## G2 correctness evidence
+
+### Root-cause fixes
+
+- Exact active/archive deduplication now includes the authoritative all-time `byDay` distribution, so equal totals on different dates cannot silently collapse. Rebuilding `period`/`today` projections intentionally remain outside identity, preserving refresh idempotence while their independent readability checks run.
+- Weekly allowance inference gates on priced-token coverage up to the observation timestamp, not later rows in the same week. A later priced row can no longer make a weak prefix look sufficiently priced.
+- An explicit model-specific Codex `limitId` takes precedence over a generic `limitName`, preventing Spark and similar allowances from entering the account-wide series.
+- A delayed poll written at or after reset no longer shadows a useful cached pre-reset observation.
+- Cumulative token deltas clamp cached input to input and reasoning to output, mark the repaired event partial, and continue to count processed tokens exactly once.
+- Partial model/effort maps send positive residual components to `unknown`; zero-value buckets are removed from aggregate and thread projections.
+
+### Actual-schema effort audit
+
+- A local field-path-only audit emitted counts, never filenames, values, timestamps, or log text. It observed 51,912 `turn_context.payload.effort` fields, 33,403 `thread_settings_applied` variants, and 33 explicit completed-item variants during the bounded scan.
+- Every string encountered by the allowlisted paths normalized to `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `ultra`; one explicit null remained unattributed. The parser now accepts these explicit current/legacy paths and never infers effort from model names.
+
+### Verification
+
+- Focused red/green fixtures cover authoritative day distribution, sidecar migration stability, observation-prefix pricing coverage, explicit limit-ID precedence, delayed rollover polls, cumulative component repair, real effort schema variants, partial/zero unknown buckets, 30-day conservation, and cross-year month order.
+- Final full Node suite: 816 tests, 815 passed, 0 failed, 1 filesystem-capability skip.
+- Final Playwright suite: 90/90 passed, including accessibility, keyboard, light/dark, 360 px, chronology, and Compare regressions.
+
+### G2 exit gate
+
+- [x] “Last 30 days” remains today plus the previous 29 configured-zone civil dates and reconciles with its daily/model/effort rows.
+- [x] `today ≤ last 30 days ≤ all time`; daily/monthly totals reconcile with all time.
+- [x] Exact duplicates are stable across refresh while differing day distributions are retained as ambiguous.
+- [x] Monthly chart and table data are chronological, including a year boundary.
+- [x] Explicit reasoning-effort variants normalize; missing/invalid evidence becomes `unknown`; zero unknown is hidden.
+- [x] Full Node and browser gates pass.
+
+## G3 quota-observation and weekly-estimate evidence
+
+### Persisted observation boundary
+
+- Added a schema-versioned, provider/account/window-partitioned observation store with machine-local HMAC fingerprints. Raw credentials and identity signals are discarded after fingerprinting; Webview projections receive only per-run ephemeral aliases.
+- Observation writes use a same-directory `0600` temporary file, `fsync`, and atomic rename. A cross-process lease, locked re-read, canonical deduplication, 180-day retention, and bounded compaction make repeated refreshes stable without merging account epochs.
+- Strict validation quarantines corrupt or future-schema files instead of trusting or deleting them. Legacy P3/P4 global-state observations and P5 Codex index history migrate P2-first; source keys and migration markers advance only after the destination append succeeds, so an interrupted migration retries safely.
+- Claude account continuity is derived only after a successful quota response from a one-way refresh-token HMAC. The token itself is never returned, persisted, logged, or exposed to the Webview. Codex observations use the same store and privacy projection.
+
+### Reset detection and allowance inference
+
+- Reset events are derived at runtime from provider window identity, changed `resetAt`, or a significant used-percentage rollback. Account changes alone do not invent an official reset; same-day and consecutive-day resets remain distinct.
+- Every valid observation with `0 < usedFraction ≤ 1` contributes `priced usage through observedAt ÷ usedFraction` as a candidate total. A weighted robust median combines candidates while pricing coverage, log coverage, boundary precision, and attribution determine confidence.
+- Estimated total is never lower than confirmed used value, and unused value is clamped non-negative. A current window with a valid real observation may expose explicitly low-confidence total and unused durability estimates when account or boundary evidence is approximate; completed windows with genuinely competing overlap remain used-only.
+- Unused stays hidden when there is no valid observation, competing series cannot be reconciled, or post-observation usage has overrun the candidate total. The last case retains only a low-confidence total lower bound instead of presenting unknown as `$0`.
+
+### Verification and read-only review
+
+- Focused fixtures cover current/legacy adapters, atomic/deduplicated persistence, concurrent append, deterministic out-of-order identities, corrupt/future quarantine, retention, interrupted migration, token rotation, stale in-flight responses, same-day and consecutive resets, rollback noise, reset changes, duplicate observations, multi-account ambiguity, low pricing coverage, current windows, and non-negative floors.
+- Final full Node suite: 842 tests, 841 passed, 0 failed, 1 filesystem-capability skip. Final Playwright suite: 90/90 passed. TypeScript compilation passed.
+- Claude CLI checkpoint review: GO with no blocker. It requested legacy-trend hardening, a real migration-write-failure fixture, and explicit account-transition semantics; all were added. The single permitted revision review returned GO for G4A with no blocker, followed by a tighter exact-error assertion.
+
+### G3 exit gate
+
+- [x] Persist immutable, anonymous, per-account quota observations without credentials or stable identifiers in UI state.
+- [x] Preserve irregular, consecutive, and same-day reset evidence without treating noise or account switches as official resets.
+- [x] Produce a total allowance estimate whenever a valid same-window utilization observation exists, with robust aggregation and explicit confidence.
+- [x] Suppress unsafe unused estimates and prevent negative or below-used values.
+- [x] Make migration, repeated refresh, and concurrent append idempotent and recoverable.
+- [x] Pass full Node/browser/compile gates and both allowed Claude review passes.
+
+### Installed-candidate regression addendum
+
+- The G5 installed-VSIX capture exposed a false `account-ambiguous` flag on a new anonymous Codex epoch even though a changed `resetAt` supplied deterministic reset evidence. The epochs were already isolated by fingerprint and window, but the stale flag suppressed the mathematically valid low-confidence total estimate.
+- Commit `4672079` now removes only this synthetic ambiguity across a coherent reset boundary, including stores written by the earlier schema-2 behavior. A fingerprint change without reset evidence remains ambiguous, and overlapping anonymous epochs still fail closed.
+- The focused quota/weekly suite passed 49/49. After the later preview-regression revision, the synthetic installed candidate's current 74% observation reports `$397.50` used, `$537.16` full allowance estimate, and `$139.66` unused estimate, explicitly at low confidence. No real account, path, project, thread, or log content entered the evidence.
+
+## G4A visual, interaction, and accessibility evidence
+
+### One shared visual contract
+
+- Added shared spacing, radius, surface, border, data-font, and focus tokens to the single production stylesheet used byte-for-byte by Claude and Codex. Summary cards, model disclosures, chart controls, empty states, and compact navigation now use that contract without copying provider branding or asserting that unlike metrics are equivalent.
+- Kept provider-native labels, card counts, and accounting definitions. Tests compare component geometry and interaction treatment, not provider values or semantic parity.
+- At 360 px, provider and dashboard navigation remain one-line horizontal strips. Every Claude/Codex destination plus Compare is checked in all eight UI locales against absolute page overflow, while tables and dense charts retain their own explicit scrollers.
+
+### Keyboard and assistive-technology contract
+
+- Dashboard destinations now implement `tablist` / `tab` / `tabpanel`, roving tabindex, automatic activation, Arrow/Home/End navigation, `aria-selected`, `aria-controls`, and synchronized hidden panels.
+- Sortable headers expose keyboard sorting and `aria-sort`. Chart metric controls expose `aria-pressed`; drill-down bars have accessible names, Enter/Space activation, `aria-controls`, and synchronized `aria-expanded`. Claude and Codex model disclosures retain native keyboard behavior.
+- Shared `:focus-visible` treatment and reduced-motion handling cover buttons, summaries, inputs, scrollers, sorting controls, and chart drill-downs. Dark-theme Axe coverage found low-contrast description text on the new raised surface; the final design uses the editor canvas plus a border, restoring readable contrast in both Light+ and Dark+.
+
+### Verification
+
+- Focused G4A browser gate: 68/68 passed (24 accessibility/keyboard, 15 responsive, 29 visual/component-contract checks).
+- Full Node gate: 842 tests, 841 passed, 0 failed, 1 filesystem-capability skip. Full browser gate: 107/107 passed.
+- Privacy-safe fixture renders were inspected for Claude light, Codex light, and Codex dark at 360 px. They confirmed aligned density, chronological reading flow, intact provider semantics, readable dark contrast, and one-line narrow navigation. These inspection images are temporary evidence, not release screenshots; G5 will capture the installed VSIX.
+
+### G4A exit gate
+
+- [x] Reuse one tokenized stylesheet and shared component treatment without creating a second provider design system.
+- [x] Preserve honest provider-specific metrics and destinations.
+- [x] Pass keyboard, ARIA, focus, reduced-motion, light/dark, eight-locale, and 360 px gates.
+- [x] Pass full Node and browser regression suites and visually inspect representative fixture states.
+
+## G4B combined heatmap and sharing evidence
+
+### One aggregate pipeline and deterministic artifact
+
+- Added a pure, configured-timezone daily merge over the existing Claude `DayUsage` map and Codex daily view. Claude processed activity is input + cache creation + cache read + output; Codex processed activity is input total + output total, with cached input already inside input and reasoning already inside output.
+- Identical duplicate provider/day rows are idempotent; conflicting duplicates fail closed. Missing dates and single-provider days remain valid, and the Codex daily projection now retains 370 rows so a complete leap-year share window plus boundary margin never triggers a second log scan or cache.
+- The combined share card is deterministic for an explicit end date, uses a neutral non-provider palette, exposes Claude/Codex/combined values in every daily tooltip, and accepts only aggregate date/value DTOs. Privacy-canary tests prove that account, project, thread, path, prompt, and log fields cannot enter the SVG.
+
+### Compare workflow and publication boundary
+
+- Compare now leads with the combined heatmap whenever provider activity is available. The user can select 30 days, 90 days, or one year, set an 80-character title, inspect the explicit inclusion/exclusion preview, export SVG, copy a relative Markdown snippet, or reset only the sharing preferences.
+- Local export and Markdown copy never request network access. The existing GitHub publisher now requests `public_repo` instead of broad private-repository access, probes repository visibility/default branch and create/update state, fails closed for private or unverifiable targets, and requires a second exact owner/repo/branch/path/action/byte confirmation before the write.
+- Destination strings persist only after a successful confirmed write; credentials remain in VS Code authentication. Goal verification uses a mock transport only and performs no real GitHub write.
+
+### Verification and read-only review
+
+- Focused pure/host suites: 69/69 passed, including formulas, duplicate and fully missing dates, symmetric Claude-only/Codex-only input, non-Sunday 30/90-day grid starts, deterministic SVG, privacy canaries, public-only GitHub permission and exact confirmation, sharing reset, and the 370-day source cap.
+- Focused browser suite: 5/5 passed for default Compare placement, both-provider tooltips, explicit actions, preference reset, Light+/Dark+ Axe, and 360 px containment.
+- Final full Node gate: 862 tests, 861 passed, 0 failed, 1 filesystem-capability skip. Full Playwright gate: 112/112 passed.
+- Claude CLI checkpoint returned GO to G5 with no blocker. It identified three low-risk test gaps: symmetric Codex-only input, a date missing from both providers, and 30/90-day SVG starts that are not Sunday-aligned. Commit `5e5bf9f` added direct assertions for all three; the single permitted revision review confirmed each gap closed and returned final GO to G5.
+
+### G4B exit gate
+
+- [x] Reuse existing provider daily aggregates without another source scan or statistics cache.
+- [x] Define and test non-duplicating provider formulas, configured-zone ranges, duplicate semantics, and a complete annual source window.
+- [x] Deliver deterministic SVG, combined share card, relative Markdown, custom title/range, and a privacy preview in Compare.
+- [x] Keep local export offline and harden optional direct GitHub publication with public-only permission, exact confirmation, and mock-only tests.
+- [x] Pass focused and complete Node/browser gates.
+- [x] Receive the required Claude CLI checkpoint verdict and close every review finding selected for revision.
+
+## G5 README, local-data inventory, and installed-VSIX screenshot evidence
+
+### Release documentation
+
+- Updated all seven README editions for v2.3.1: Claude/Codex/Compare coverage, corrected time ranges and chronological months, quota observation and reset-aware estimation, combined heatmap sharing, local-only data boundaries, and known uncertainty limits.
+- Added concise bilingual user inventories in `LOCAL-DATA.md` and `LOCAL-DATA.zh-CN.md`, backed by the normative contract, covering sources, derived caches, anonymous quota history, preferences, retention, clear controls, remote interactions, and data that is never stored.
+- Updated the v2.3.1 changelog, package/lock version, exact-version release announcement, and all eight announcement locales. The release remains explicitly unreleased; no Marketplace, remote release, or repository publication occurred.
+
+### Real host evidence
+
+- Built and installed the v2.3.1 candidate VSIX in a separate ad-hoc-signed VS Code copy with isolated extension/user-data directories and synthetic Claude/Codex JSONL only.
+- Captured and visually inspected `images/v2.3.1/codex-overview-zh-CN-dark.png`, `images/v2.3.1/codex-weekly-estimate-en-dark.png`, and `images/v2.3.1/compare-heatmap-en-light.png` from that installed candidate.
+- The images cover the Codex overview, a reset-aware full allowance estimate, and Compare's combined heatmap/share controls in Chinese/English and dark/light themes. They contain no account identifier, local path, real project/thread title, prompt, credential, or user log content.
+- The captured JPEG frames were transcoded to real PNG bytes before commit and stripped of EXIF and textual PNG chunks. Repository-policy tests require every README to reference all three images, every referenced file to exist, the PNG signature/IEND structure to be valid, and `eXIf`/`iTXt`/`tEXt`/`zTXt` chunks to be absent.
+
+### Verification and read-only review
+
+- Focused release/document/quota suite: 77/77 passed.
+- Full Node gate: 866 tests, 865 passed, 0 failed, 1 filesystem-capability skip. Full Playwright gate: 112/112 passed.
+- The G4B host tests explicitly confirm that GitHub destination preferences persist only after a successful exact-target write and that reset clears only the remembered destination. The G5 repository-policy gate separately protects the shipped evidence files.
+- Claude CLI returned **GO TO G6** with no blocker or semantic/privacy error. It noted non-native data-inventory language coverage and requested explicit mention of the GitHub test and stronger screenshot scrubbing; the former is now recorded above, while the latter is enforced for file format and metadata plus visual inspection for rendered pixels. Final VSIX packaging, clean fresh-install/migration/clear-path smoke tests, acceptance matrix, and candidate hash belong to G6.
+
+### G5 exit gate
+
+- [x] Update all README editions, changelog, version metadata, and migration/uncertainty notes.
+- [x] Track concise bilingual local-data inventories consistent with the normative contract.
+- [x] Capture three privacy-safe screenshots from an actually installed v2.3.1 candidate.
+- [x] Pass focused and complete Node/browser gates.
+- [x] Receive the required Claude CLI checkpoint and close the selected evidence-hardening notes.
+- [x] Commit the completed G5 implementation and evidence (`e9a149a`).
+
+## G6 release-candidate evidence
+
+### Local-data controls and audit hardening
+
+- Added the Settings/Data inventory and seven separately confirmed controls: rebuild Codex index, clear quota history, clear advice data, reset UI state, reset sharing preferences, clear the BYOK secret, and clear all extension-derived data.
+- An independent read-only code audit found five blockers and two high risks around partial configuration deletion, false Webview acknowledgements, quota clear races/quarantine, activation-write resurrection, and overly broad setting/migration deletion. Every finding was closed before the release gate.
+- Clear All now preflights every currently visible configuration scope before mutation, drains activation-owned writes, uses exact key/file families, preserves unknown future `ccu.setting.*` keys, verifies postconditions, and fails closed on unregistered legacy configuration.
+- Quota all-clear holds one cross-process lease, atomically installs a valid empty P2 document, and purges only exact auxiliary files. Scoped clear refuses quarantined or unresolved migration evidence instead of stranding it. Webview resets use a truthful acknowledgement plus a value-free pending-action tombstone for idempotent retry.
+- The bilingual normative contract and user inventory now describe these exact storage, migration, clearing, retention, retry, and host-limit semantics.
+
+### Final automated and package gates
+
+- `npm run test:release`: 897 Node tests, 896 passed, 0 failed, 1 filesystem-capability skip; Playwright 116/116 passed.
+- `git diff --check` and TypeScript compile passed.
+- Pinned `@vscode/vsce@3.9.1` produced the superseding `claude-code-usage-2.3.1-5af60b4.vsix`. The repository verifier accepted version `2.3.1`, runtime main `extension/out/extension.js`, 107 entries, and 1,903,765 bytes.
+- Candidate SHA-256: `074d0b774b983cebd654eda59c2f6c22168607768aa99a52fb50c98ec199d7a0`.
+
+### Stock VS Code isolated smoke
+
+- Stock VS Code `1.135.0` installed the final VSIX into a new isolated user-data/extensions pair. A second isolated profile installed the earlier screenshot candidate and then force-installed the final candidate over it.
+- Both extracted manifests reported `growthjack.claude-code-usage@2.3.1`, `./out/extension.js`, and the new Clear All command. Extracted runtime SHA-256 matched the compiled runtime exactly: `0e86438a32225caffe130ba8326979234b7398e7a07b91cd161d2c0c9e6a2036`.
+- With only synthetic Claude/Codex sources, the stock Extension Host activated `GrowthJack.claude-code-usage` without an extension error. The exact isolated process was normally terminated and restarted; the new Extension Host activated the extension again without an extension error.
+- Both isolated profiles uninstalled successfully and then listed no installed extension. VS Code retained extension globalStorage after uninstall, confirming the documented need for an explicit clear action. Source fixtures were never rewritten; the before/after Codex index-source hash remained identical.
+- The G5 ad-hoc screenshot wrapper was not used in G6. Its macOS crash alert is isolated from the final VSIX and was not reproduced in stock VS Code.
+
+### Final pre-install Claude CLI review (2026-09-02)
+
+- Claude Code CLI `2.1.228`, Opus, and `max` effort reviewed the actual 3,488-addition/88-deletion G6 patch from the G5 checkpoint `8eac9a0` through implementation commit `b435e06`, plus final test, package, and stock-host evidence. It ran in safe/print/no-tools/no-session-persistence mode. The complete input-stream SHA-256 was `350582b6b76e58167f1864787c4192f07b6babf7c15911001beca3b56488fb1e`; it contained no real logs, accounts, credentials, project content, or user paths.
+- Claude reported **Release blockers: None** and returned **GO FOR USER INSTALL**. This authorizes the maintainer's local install test only, not a push, Marketplace publication, remote release, or real GitHub write.
+- The hands-on install pass should prioritize three cases: opening Manage Local Data and Privacy with no Claude/Codex logs; activating an upgrade profile that contains a legacy plaintext `claudeCodeUsage.advice.apiKey`; and testing both blocked-legacy and successful Clear All paths in a scratch workspace. Clear All removes explicitly owned `claudeCodeUsage.*` entries from that scratch workspace's `.vscode/settings.json`, so it must not be tried first in an important workspace.
+- Nonblocking follow-ups include a real-temp-globalStorage Clear All postcondition E2E test, an advice-clear versus in-flight-migration race, the Webview two-second ACK timeout, sharing-preference reset scope, and exact blocked-key copy. Any hands-on unhandled activation failure or out-of-scope deletion reopens the candidate before publication.
+- A later maintainer preview-feedback revision changed the share studio, heatmap renderer, weekly estimates, localized copy, tests, and release documentation. It therefore supersedes the earlier `b435e06` package; the final review and candidate evidence are recorded below.
+
+### Post-preview feedback revision and superseding candidate (2026-09-02)
+
+- The data font was returned to the VS Code UI font while the Markdown field retains the editor monospace font. Compare now uses a preview-first share studio with a privacy badge, grouped card settings, explicit actions, a collapsible Markdown result, desktop-fit preview geometry, and preserved narrow-screen horizontal scrolling.
+- Heatmap color is locally selectable. The default Academic Violet ramp is exactly `#ebedf0`, `#eee8f8`, `#d8c9f1`, `#bca5e6`, `#8668c7`, `#4f2f87`; three other curated palettes and one validated custom accent are available. Quantile ties, sparse maxima, near-white custom colors, short-range legend bounds, SVG injection, contrast, deterministic output, and the full desktop `More` legend all have direct tests.
+- A coherent Claude or Codex observation now exposes both full and unused API-equivalent subscription-durability estimates for current and completed windows, including unattributed or approximate evidence at low confidence. Dashes remain only when there is no valid observation, genuinely overlapping quota series compete, or later usage has overrun a stale observation-derived candidate; in the latter case the total is a low-confidence lower bound and unused is withheld instead of showing a false zero.
+- Claude CLI reviewed the sanitized feedback revision in print/no-tools/no-session-persistence mode and returned **GO FOR USER INSTALL** with no blocker or network, permission, or privacy concern. Its nonblocking findings on sparse/tied quantiles, custom-color contrast, provider-symmetric confidence, stale-observation overrun, surcharge wording, short-range legend bounds, exact palette/source-overlap fixtures, preview semantics, Axe completeness, and UI-font assertions were all closed before the final gate.
+- The superseding release gate passed 896/897 Node tests (the one skip is the documented filesystem-capability fixture), 116/116 Playwright tests, TypeScript compile, `git diff --check`, bilingual visual QA, and the repository VSIX policy verifier. Synthetic English-light and Chinese-dark final renders were visually inspected; they contain no real account, project, thread, path, or log data.
+- Stock VS Code `1.135.0` force-installed the superseding package over the prior candidate in the same isolated temporary profile and listed `growthjack.claude-code-usage@2.3.1`. Installed `webview.js`, `weeklyValue.js`, and `combinedHeatmapSvg.js` hashes exactly matched the compiled files. No push, Marketplace publication, remote release, or real GitHub write occurred.
+- Runtime candidate commit: `5af60b4` (including the main feedback implementation in `5e6e5cc`). Package: `claude-code-usage-2.3.1-5af60b4.vsix`, 1,903,765 bytes, SHA-256 `074d0b774b983cebd654eda59c2f6c22168607768aa99a52fb50c98ec199d7a0`. The following local documentation commit records this evidence and is excluded from the VSIX.
+
+### Post-install regression correction and final local candidate (2026-09-02)
+
+- Local implementation commit `666f04c` fixes the maintainer-observed regression: Claude's middle scope is now Today plus the previous 29 civil dates in the configured timezone, and Today / rolling-30 / month daily rows all read `byLocalDay`. An inactive Today renders an explicit zero state rather than looking like a missing page.
+- A current Codex period may use the latest real observation for explicitly low-confidence total and unused durability estimates; weekly period tables are collapsed by default. Compare is vertically preview-first, with card settings directly below the share graphic instead of leaving a large empty right column.
+- The Codex primary status item now reports configured-timezone Today. Quota compact text uses Claude-compatible used-percent semantics; the tooltip reuses progress bars, thresholds, and reset columns. The item background follows the highest usage among live windows rendered by the active preference, so compact `wk 40%` alongside tooltip `5h 96%` correctly produces an error background.
+- A Los Angeles DST/local-boundary fixture directly asserts the Today row equals the Today aggregate, `Today ≤ 30 days ≤ all time`, and snapshot materialization adds no JSONL body read. Additional fixtures cover two-window quota severity, expired windows, provider-label escaping, and the real `renderCodex` wiring.
+- Final gates: TypeScript compile; 903 Node tests with 902 passed, 0 failed, and 1 existing filesystem-capability skip; Playwright 117/117; `git diff --check`. Pinned `@vscode/vsce@3.9.1` produced `claude-code-usage-2.3.1-regression-fix-final-20260902.vsix`; the repository verifier accepted 107 files, 1,905,981 bytes, version `2.3.1`, runtime main `extension/out/extension.js`, and SHA-256 `869149b3e6034da4341ba55fa50c2d365accb5280e9ffd16520dfc845340f5b8`.
+- The package force-installed into an isolated VS Code/profile using synthetic data only. Installed `extension.js`, `webview.js`, `weeklyValue.js`, and `statusBar.js` hashes exactly match the compiled outputs. The stock-host accessibility tree confirms settings below the preview, both weekly disclosures closed, a current Codex 74% total/unused low-confidence estimate, and compact `CX 5M` / `wk 74%` status items.
+- Claude Code CLI `2.1.228`, Opus, and `max` effort ran in safe/print/no-tools/no-session-persistence mode. Its first regression review identified two blockers (Claude day-map consistency and Codex quota severity colour); after revision it marked B1/B2 **CLOSED**, the roadmap **ADEQUATE**, and the local candidate **GO**. The revision-review input SHA-256 was `437fd7a5a593d4b272877f5641e6a8d3545243c9cd575e3684ed50cd29602e1a`; it contained relative-path patches, synthetic evidence, and the roadmap only.
+- Broader parity work is deliberately outside v2.3.1 and is tracked in the [v2.4 Claude / Codex interaction-parity roadmap](../roadmap/provider-parity-v2.4.md): month-to-day and day-to-hour drill-down, zero JSONL reads on click, refresh/reload state preservation, non-UTC/DST conservation, sparse-range zero fill, unique accessible names, and top-level chart/status/quota contracts. Maintenance follow-ups include documenting the `byDay`/`byLocalDay` invariant, removing `month` naming drift, structuring tooltip copy, and adding a manager-level five-hour-only fixture.
+- No push, Marketplace publication, remote release, real GitHub write, or real user-data scan occurred. This package supersedes every earlier VSIX candidate.
+
+### Concise-settings and remaining-quota follow-up candidate (2026-09-02)
+
+- Follow-up implementation commit `ddfe99d` removes the local-data/privacy inventory from the plugin Settings surface while retaining the normative repository documents, exact host-side clear contracts, and their safety tests. Settings now exposes one shared **Enable sharing workspace** switch: it defaults on, controls both Compare and provider share surfaces, and hides them completely when off; every export remains an explicit action.
+- Compare remains vertically preview-first, and the SVG now expands to the available desktop width before the card settings below it. Weekly period details remain collapsed by default. Synthetic Chinese-dark visual QA confirmed that enabling the workspace no longer leaves the former right-side void, while disabling it leaves Compare summaries and both weekly charts intact.
+- The compact Codex quota item now reports **remaining** capacity (`wk 64%` for 36% used), as requested. Tooltip progress bars, severity colours, and warning thresholds continue to use observed utilisation, and the separate `CX` token item continues to report the configured-timezone Today scope rather than a recent-task subtotal.
+- A user-authorized, read-only diagnostic of the selected default Claude profile inspected only file/timestamp metadata and allowlisted numeric usage fields. The production loader found 682 project JSONL files and correctly reconstructed the rolling 30-day scope as 104 messages and 2,487,790 output tokens, but found zero persisted usage for 2026-09-02. Four 2026-09-02 history entries had neither usage fields nor a corresponding project transcript, and there was no measurable 2026-09-01 entry. The existing audit ledger records that those Claude CLI reviews used `--no-session-persistence`; that mode writes no measurable transcript/token record, so the extension cannot truthfully backfill the missing Today/Yesterday values. No prompt, response, command, credential, path, or raw log content was reported or changed.
+- Final gates after the desktop-width refinement: TypeScript compile; Node 903 total with 902 passed, 0 failed, and 1 existing filesystem-capability skip; Playwright 118/118; targeted combined-share tests 6/6; `git diff --check`; ZIP integrity; and repository VSIX policy verification. Pinned `@vscode/vsce@3.9.1` produced `claude-code-usage-2.3.1-followup-final-20260902.vsix`, 107 files, 1,906,703 bytes, SHA-256 `33bc404ce0dc693f7d97d40dd485c8d6ea96c8727ea9b178fe978cbb101daa0f`.
+- The package installed successfully into a new isolated stock-VS-Code user-data/extensions pair and listed `growthjack.claude-code-usage@2.3.1`. The primary checkout was not modified. No push, Marketplace publication, remote release, or real GitHub write occurred; the read-only Claude diagnostic above is the only real-data access added after the earlier candidate evidence.
+
+### Acceptance matrix
+
+| Requirement | Implementation | Automated verification | Screenshot / host evidence |
+|---|---|---|---|
+| Last-30-day conservation, deduplication, chronological month order | `src/dateKeys.ts`, `src/providers/codex/codexDedup.ts`, `codexIndex.ts`, `codexUsage.ts`, `codexView.ts` | `dateKeys`, `codexDedup`, `codexIndex`, `codexUsage`, Webview visual/interaction suites | Codex overview and weekly screenshots; stock activation/restart |
+| Reasoning-effort normalization and meaningful `unknown` | `src/providers/codex/codexSchema.ts`, `codexParser.ts`, `codexUsage.ts`, `src/webview.ts` | current/legacy/missing/invalid/zero/non-zero effort fixtures plus total conservation | Codex overview screenshot |
+| Anonymous quota history, multiple resets, robust full/unused estimates | `src/quotaObservationStore.ts`, `codexQuotaHistory.ts`, `src/weeklyValue.ts` | quota-store, quota-history, weekly-value, race, quarantine, migration and ambiguity fixtures | Weekly-estimate screenshot; stock-generated P2 store |
+| Claude/Codex visual, keyboard, theme and narrow-width alignment | shared `src/webview.ts` and `src/codexViewComponents.ts` tokens/components | accessibility, responsive, visual and interaction suites | G5 English/Chinese, dark/light screenshots |
+| Compare combined heatmap and privacy-bounded sharing | `src/combinedHeatmap.ts`, `combinedHeatmapSvg.ts`, `githubHeatmapPublish.ts`, `webview.ts` | deterministic SVG, duplicate/conflict, timezone, privacy canary, mock GitHub, accessibility tests | Compare heatmap/share screenshot |
+| Auditable local inventory, exact clear/migration boundaries | `src/localDataControls.ts`, `extension.ts`, `settings.ts`, `quotaObservationStore.ts` | `localDataControls`, `localDataExtension`, `settingsPrivacy`, quota clear-race/quarantine and UI ACK suites | Stock install/activation/restart/uninstall; host-retained storage observed |
+| README, contract, screenshots and migration disclosure | all README editions, CHANGELOG, `LOCAL-DATA*`, normative contract, release ledger | repository/release policy and screenshot metadata/privacy gates | Three installed-candidate screenshots |
+| Installable release candidate without remote side effects | package manifest, compiled `out`, `.github/scripts/verify-vsix.mjs` | full release gate and VSIX policy verifier | Two isolated stock profiles; no push, release, Marketplace, or real GitHub write |
+
+### G6 exit gate
+
+- [x] Close all read-only audit blockers and high-risk findings.
+- [x] Pass final compile, diff, complete Node and complete browser suites.
+- [x] Build and policy-verify the v2.3.1 VSIX with a recorded SHA-256.
+- [x] Verify isolated fresh install, candidate-over-candidate update, real activation, full process reload, uninstall, migration fixtures, repeated-refresh fixtures, and exact clear paths.
+- [x] Record the requirement-to-code-to-test-to-evidence acceptance matrix.
+- [x] Receive the final pre-install Claude CLI **GO FOR USER INSTALL** verdict and record the hands-on checkpoints.
+- [x] Stop before push, Marketplace publication, remote release, or real GitHub write.
+- [x] Commit the G6 implementation and feedback revision (`b435e06`, `5e6e5cc`, `5af60b4`); the following local documentation commit records the superseding package evidence in both ledgers.
+
+## Update rule
+
+Each stage must finish its automated verification before this ledger records its commit, evidence, Claude decision, and risk. The G6 acceptance matrix must be derived from these records; screenshots or copy cannot substitute for a failed gate.
+
+The future ability to select one project, invoke AI on demand to review its inputs/outputs, and return evidence-bound usage-behavior advice now lives in the [v2.5.3 project-scoped AI usage review plan](../superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.md). It does not reopen v2.3.1 and requires a new Goal that explicitly ends at R0–R4 or also authorizes the R5 local Claude CLI safety gate.
diff --git a/docs/releases/2026-09-01-v2.3.1-goal-ledger.zh-CN.md b/docs/releases/2026-09-01-v2.3.1-goal-ledger.zh-CN.md
new file mode 100644
index 00000000..3a4e88b1
--- /dev/null
+++ b/docs/releases/2026-09-01-v2.3.1-goal-ledger.zh-CN.md
@@ -0,0 +1,341 @@
+# Claude Code Usage v2.3.1 Goal 执行台账
+
+本台账记录本地候选从 G0 到 G6 的阶段状态、可复现验收证据、Claude CLI 只读审阅和剩余风险。它不记录账号、凭证、真实日志、提示词、线程标题或本地路径。
+
+## 执行边界
+
+- 分支：`codex/v2.3.1-goal-g0-g6`
+- 基线：`7fd03f3183240940d0a2d1cfe76f60cb80f0a6ae`
+- 工作方式：隔离 worktree；用户主 checkout 及其中已有修改保持只读。
+- 允许：本地代码/文档修改、测试、构建、VSIX、阶段性本地 commit、指定检查点的 Claude CLI 只读审阅。
+- 禁止：push、Marketplace 发布、远程 release、真实 GitHub 写入、上传用户日志或身份数据。
+
+## 阶段状态
+
+| 阶段 | 状态 | 本地 commit | 验证摘要 | Claude 审阅 | 剩余风险 |
+|---|---|---|---|---|---|
+| G0 基线与夹具 | 已完成 | `f0af506` | Node 795 passed / 1 skipped；UI 90 passed；定向 29 passed | 不适用 | 无阻塞风险 |
+| G1 数据契约 | 已完成 | `86d95df` | 定向 17 passed；Node 806 passed / 1 skipped；compile passed | 首轮有条件 GO，修订复核 GO | 受阻 workspace 明文需用户显式恢复；SecretStorage 底层保护依赖宿主；统一额度存储属于 G3 |
+| G2 统计/排序/effort | 已完成 | `49f2041` | Node 815 passed / 1 skipped；UI 90 passed；全部定向回归通过 | 不适用 | 统一观测与账号归属仍由 G3 处理 |
+| G3 额度观测与估算 | 已完成 | `a04ab04`、`4672079` | 阶段出口 Node 841 passed / 1 skipped；安装候选回归：quota/weekly 49 passed | 首轮 GO，修订复核 GO | 损坏/未来 schema 的隔离文件会保留至“清除数据”或未来清理策略处理 |
+| G4A 视觉/交互/可访问性 | 已完成 | `fca21da` | Node 841 passed / 1 skipped；UI 107 passed；G4A 定向 68 passed | 不适用 | 刻意保留 provider 原生指标语义与卡片数量差异 |
+| G4B 综合热力图与分享 | 已完成 | `1e6bbab`、`5e5bf9f` | Node 861 passed / 1 skipped；UI 112 passed；定向 69 + 5 passed | 首轮 GO，修订复核 GO | GitHub `public_repo` 对公开仓库仍是账号级权限；本地 SVG/Markdown 无需权限，是默认安全路径 |
+| G5 README/截图 | 已完成 | `e9a149a` | Node 865 passed / 1 skipped；UI 112 passed；已目检 3 张安装候选截图 | GO TO G6 | 最终打包证据属于 G6 |
+| G6 发布候选 | 已完成 | `b435e06`、`5e6e5cc`、`5af60b4`、`666f04c` | 最新回归候选 Node 902 passed / 1 skipped；UI 117 passed；VSIX policy、视觉 QA 与隔离原生宿主安装通过 | 回归首审 NO-GO；修订复核：**GO** | 需在隔离 profile/临时 workspace 手测空数据设置页、旧明文 key 升级和 Clear All；其余交互一致性进入 v2.4 路线图 |
+
+## G0 基线证据
+
+### 环境与测试
+
+- Node：`v24.19.0`
+- npm：`11.17.0`
+- `npm ci`：成功。
+- `npm run test:node`：796 项，795 通过，0 失败，1 跳过。首次受限运行中的两个 loopback `EPERM` 由测试沙箱引起；允许本地测试服务器绑定后均通过。
+- `npm run test:ui`：90/90 通过。
+- 基线工作树：干净。
+
+### v2.3.1 最小回归夹具登记
+
+| 风险 | 固定输入/测试 | 验收事实 |
+|---|---|---|
+| 最近 30 天大于全部时间 | `codexUsage.test.ts`：`an inflated period sidecar falls back to the verified daily aggregate`；`v2.3.1 acceptance fixture keeps non-negative ranges monotonic and reconciled` | `today ≤ last30Days ≤ allTime`，日/月汇总与总计可核对 |
+| 重复索引/重复累计 | `codexIndex.test.ts`：`fully indexed unchanged corpus returns a warm no-op without body reads`；`cold scan, appended tail, and persisted reload agree` | 连续刷新为稳定 no-op，重载后总计不变 |
+| 活跃/归档重复文件 | `codexIndex.test.ts`：`exact active and archive copies contribute usage only once` | 同一内容只计一次并报告去重覆盖 |
+| 月度顺序 | `codexUsage.test.ts`：`all-time, monthly, and behavior views stay provider-native` | 图表/表格源数据按月份正序 |
+| 连续/不规则额度重置 | `codexQuotaHistory.test.ts`：`irregular reset boundaries survive polling compaction`；`weeklyValue.test.ts` 的 fresh reset/irregular reset fixtures | 独立 reset 被保留，窗口不重复计量 |
+| unknown 推理强度 | `codexParser.test.ts` 的 current/legacy/missing/unsafe context fixtures；`codexUsage.test.ts`：`missing model and effort values are grouped as unknown` | 可解析值保留；确实缺失或被安全拒绝时进入 unknown |
+
+### G0 通过条件
+
+- [x] 隔离候选，不触碰用户 checkout。
+- [x] 记录 branch、HEAD、状态和基线测试。
+- [x] 为五类已知回归建立可重复的自动化夹具索引。
+- [x] 加入跨视图非负、单调、日/月核对断言。
+- [x] 提交 G0 台账与新增验收断言（`f0af506`）。
+
+## G1 本地数据与隐私证据
+
+### 契约与实现
+
+- 新增中英文规范性本地数据契约，覆盖原始来源、索引、派生统计、额度观测、重置事件、UI/分享偏好、schema 迁移、保留期、清除方式和所有远程边界。
+- 定义匿名账号 fingerprint、原子且去重的观测写入、账号隔离，并禁止保存凭证、完整账号标识、原始 CLI 输出及私密源内容。
+- 将 AI 建议 BYOK key 从 contributed configuration/globalState 迁入 VS Code SecretStorage；Webview snapshot 只暴露 `configured`，密码框绝不回填 secret。
+- 迁移检查 Global、当前 Workspace 和所有已打开 Workspace Folder；仅自动迁移唯一且无歧义的机器级值，先写安全存储、后清明文；workspace-only、冲突值或 provider 失败均以本地化固定提示 fail closed，并保留可恢复数据。
+
+### 验证与审阅
+
+- 隐私/契约定向测试：17 passed。
+- 独立 loopback 端口完整 Node 测试：807 项，806 passed，0 failed，1 项因文件系统能力 skipped。
+- Claude CLI 首轮审阅：有条件 GO，要求补齐 scope 枚举、并发/幂等保护、固定失败 UX 及 Settings Sync 证据。
+- 修订复核：无阻塞，可进入 G2；关于受阻 workspace 明文和 SecretStorage 宿主差异的非阻塞提示已写入契约。
+
+### G1 通过条件
+
+- [x] 在 repo 内跟踪中英文规范性数据契约。
+- [x] 使所有持久化数据类别、保留期、清除路径和远程交互可审计。
+- [x] 唯一凭证迁入 SecretStorage，且不暴露到 Webview 状态。
+- [x] 对歧义或失败的旧数据迁移 fail closed 并保留可恢复性。
+- [x] 通过 G1 测试门和 Claude 修订复核。
+
+## G2 入口审计
+
+以下是必须先用最小 fixture 复现、再修改实现的风险假设，不代表已接受的现有行为：
+
+1. 每周定价覆盖率疑似使用完整窗口，而不是截至观测时刻的前缀。
+2. 精确内容去重签名未纳入日/周期分布，可能把总量相同但日期不同的记录折叠掉。
+3. `codex-spark` 限额可能被误判成账号级，而实际作用域是特定模型。
+4. 重置后延迟到达的当前观测可能掩盖有效的重置前缓存观测。
+5. 累计 delta 修复可能产生 `reasoning > output` 或 `cached input > input`。
+6. 部分 effort map 的剩余用量可能消失，而不是归入 `unknown`。
+
+额外 guard 覆盖配置时区下完整的 30 天定义、跨年月份正序、reasoning-effort 别名/非法变体，以及日、月、模型、effort 和总计之间的守恒关系。
+
+## G2 正确性证据
+
+### 根因修复
+
+- active/archive 精确去重签名现包含权威 all-time `byDay` 分布，因此“总量相同、日期不同”不会被静默折叠。可重建的 `period`/`today` 投影不进入身份签名，避免 sidecar 迁移时破坏刷新幂等；它们继续由独立可读性检查保护。
+- 周额度推断改用截至观测时刻的已定价 Token 覆盖率，而不是同周后续记录；后到的已定价行不能再把证据不足的前缀变成可推断样本。
+- 显式模型级 Codex `limitId` 优先于通用 `limitName`，防止 Spark 等独立额度混入账号级序列。
+- reset 时刻或之后才写入的延迟 poll 不再遮蔽有效的重置前缓存观测。
+- 累计 Token delta 强制 cached input ≤ input、reasoning ≤ output；修复事件标为 partial，并保持 processed 只计一次。
+- 部分 model/effort map 的正残差进入 `unknown`；aggregate 与线程投影均删除零值 bucket。
+
+### 真实 schema 的 effort 审计
+
+- 本地只做字段路径计数，不输出文件名、字段值、时间或日志正文。有限扫描中观察到 51,912 个 `turn_context.payload.effort`、33,403 个 `thread_settings_applied` 变体和 33 个显式 completed-item 变体。
+- 白名单路径中的字符串都可规范为 `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max` 或 `ultra`；另有 1 个显式 null 保持未归属。解析器现支持这些显式新旧路径，绝不按模型名称推断 effort。
+
+### 验证
+
+- 定向 red/green fixture 覆盖权威日期分布、sidecar 迁移稳定性、观测前缀定价覆盖、显式 limit ID 优先、延迟 rollover poll、累计分量修复、真实 effort schema、部分/零值 unknown、30 天守恒和跨年月份正序。
+- 最终完整 Node：816 项，815 passed，0 failed，1 项因文件系统能力 skipped。
+- 最终 Playwright：90/90 passed，覆盖可访问性、键盘、深浅主题、360 px、时间正序和 Compare 回归。
+
+### G2 通过条件
+
+- [x] “最近 30 天”保持为配置时区下今天及此前 29 个自然日，并与日/model/effort 行守恒。
+- [x] `今日 ≤ 最近 30 天 ≤ 全部时间`；日/月总计与 all-time 核对一致。
+- [x] 精确副本在刷新间稳定；日期分布不同的记录保留为 ambiguous。
+- [x] 月度图表与表格数据按时间正序，包含跨年边界。
+- [x] 显式 reasoning-effort 新旧变体可规范化；缺失/非法证据进入 `unknown`；零 unknown 隐藏。
+- [x] 完整 Node 与浏览器门均通过。
+
+## G3 额度观测与周额度估算证据
+
+### 持久化观测边界
+
+- 新增带 schema 版本、按 provider/账号/窗口分区的观测存储，账号与窗口仅使用机器本地 HMAC fingerprint。原始凭证和身份信号完成摘要后立即丢弃；Webview 只能收到本次运行内的临时别名。
+- 写入采用同目录 `0600` 临时文件、`fsync` 和原子 rename；跨进程 lease、锁内重读、规范化去重、180 天保留期及有界压缩保证重复刷新稳定且不合并账号 epoch。
+- 严格校验会隔离损坏或未来 schema 文件，而不是信任或删除它们。P3/P4 globalState 旧观测及 P5 Codex index history 均先写入 P2，只有目标 append 成功后才清理源键或推进迁移 marker，因此中断后可安全重试。
+- Claude 的账号连续性只在额度请求成功后由 refresh token 的单向 HMAC 得到；token 本身不返回、不持久化、不记录日志、也不进入 Webview。Codex 观测使用同一存储及隐私投影。
+
+### 重置检测与额度推断
+
+- reset 事件在运行时依据 provider window identity、`resetAt` 变化或 used 百分比显著回落推导。单纯账号切换不会伪造官方重置；同日多次及连续两日重置均保留为独立事件。
+- 每个满足 `0 < usedFraction ≤ 1` 的有效观测都会形成“截至 observedAt 的已定价用量 ÷ usedFraction”候选总额度；多个候选用加权稳健中位数合并，并由定价覆盖、日志覆盖、边界精度和账号归属共同决定可信度。
+- 总额度估算绝不低于窗口已确认使用值；未用值强制非负。当前窗口存在有效真实观测但账号/边界近似时，可以显示明确标为低可信度的总额与未用耐用度估算；已结束窗口若存在竞争性重叠系列则仍只显示已用值。
+- 不存在有效观测、竞争性系列无法归一，或观测后新增用量已超过候选总额时，不显示未用值；最后一种情况只保留低可信度总额下界，不把未知伪装成 `$0`。
+
+### 验证与只读审阅
+
+- 定向 fixture 覆盖新旧 adapter、原子/去重持久化、并发 append、乱序窗口身份、损坏/未来 schema 隔离、保留期、中断迁移、token 轮换、过期 in-flight 响应、同日/连续 reset、回落噪声、reset 变化、重复观测、多账号歧义、低定价覆盖、当前窗口及非负下限。
+- 最终完整 Node：842 项，841 passed，0 failed，1 项因文件系统能力 skipped；最终 Playwright：90/90 passed；TypeScript compile passed。
+- Claude CLI 检查点首轮无阻塞 GO，并要求加固旧 trend、加入真实迁移写失败 fixture、明确账号切换语义；均已完成。允许的一次修订复核返回“可进入 G4A、无阻塞”，随后又收紧了精确错误断言。
+
+### G3 通过条件
+
+- [x] 以不可变、匿名、按账号隔离的形式保存额度观测，不保存凭证，不向 UI 暴露稳定标识。
+- [x] 保留不规则、连续及同日多次 reset 证据，且不把噪声或账号切换误判为官方重置。
+- [x] 只要同窗存在有效利用率观测即给出总额度估算，并采用稳健聚合及显式可信度。
+- [x] 抑制不安全的未用额度，且任何估算不得为负或低于已确认使用值。
+- [x] 迁移、重复刷新和并发 append 均幂等且可恢复。
+- [x] 通过完整 Node、浏览器、compile 门及两次允许的 Claude 审阅。
+
+### 安装候选回归补记
+
+- G5 的已安装 VSIX 截图暴露了一个误判：新的匿名 Codex epoch 明明有 `resetAt` 变化这一确定性重置证据，却仍被自动标成 `account-ambiguous`。不同 epoch 本已由 fingerprint 和窗口隔离，但这枚旧标记会压掉数学上有效的低可信总额度估算。
+- `4672079` 只解除“跨越连贯重置边界”的这类合成歧义，并兼容由早期 schema-2 行为写出的存储；没有 reset 证据的 fingerprint 变化仍是歧义，重叠匿名 epoch 仍然 fail closed。
+- quota/weekly 定向测试 49/49 通过。后续预览回归修订后，合成安装候选中的当前 74% 观测显示已用 `$397.50`、总额度估算 `$537.16`、未用估算 `$139.66`，并明确标为低可信度；证据未使用真实账号、路径、项目、线程或日志内容。
+
+## G4A 视觉、交互与可访问性证据
+
+### 单一共享视觉契约
+
+- 在 Claude 与 Codex 逐字节共用的生产样式表中加入统一的间距、圆角、表面、边框、数据字体和焦点 token；摘要卡、模型折叠、图表控件、空状态及紧凑导航均使用该契约，不复制 provider 品牌色，也不把不同指标宣称为语义等价。
+- 保留 provider 原生标签、卡片数量和核算定义。自动化只比较组件几何及交互处理，不比较 provider 数值或强制语义一致。
+- 360 px 下 provider 与主导航保持单行横向滚动；8 种 UI 语言中 Claude/Codex 的全部目的页和 Compare 均检查绝对页面宽度，表格与密集图表只允许在自身明确的 scroller 内横向滚动。
+
+### 键盘与辅助技术契约
+
+- 主导航现实现 `tablist` / `tab` / `tabpanel`、roving tabindex、自动激活、方向键/Home/End、`aria-selected`、`aria-controls` 及同步隐藏 panel。
+- 可排序表头支持键盘并公开 `aria-sort`；图表指标公开 `aria-pressed`；可钻取柱具有可访问名称、Enter/Space、`aria-controls` 与同步 `aria-expanded`。Claude/Codex 的模型折叠保留原生键盘行为。
+- 共用 `:focus-visible` 与 reduced-motion 处理覆盖按钮、summary、输入、scroller、排序与图表钻取。新增深色 Axe 门发现抬升表面的辅助文字对比度不足；最终以编辑器底色加边框表达层级，使 Light+ 与 Dark+ 均恢复可读对比度。
+
+### 验证
+
+- G4A 定向浏览器门：68/68 passed（24 项可访问性/键盘、15 项响应式、29 项视觉/组件契约）。
+- 完整 Node：842 项，841 passed，0 failed，1 项因文件系统能力 skipped；完整浏览器：107/107 passed。
+- 已目检不含敏感信息的 Claude 浅色、Codex 浅色及 360 px Codex 深色 fixture，确认密度对齐、阅读顺序清楚、provider 语义完整、深色对比度可读、窄屏导航保持单行。这些仅为临时检查证据；G5 将从已安装 VSIX 生成正式截图。
+
+### G4A 通过条件
+
+- [x] 复用一份 token 化样式表与共享组件处理，不建立第二套 provider 设计系统。
+- [x] 保留真实的 provider 专属指标与目的页。
+- [x] 通过键盘、ARIA、焦点、reduced-motion、深浅主题、8 种语言和 360 px 验收。
+- [x] 通过完整 Node/浏览器回归，并目检代表性 fixture。
+
+## G4B 综合热力图与分享证据
+
+### 单一聚合链与确定性产物
+
+- 在既有 Claude `DayUsage` 和 Codex daily view 上新增配置时区下的纯函数按日合并层。Claude processed = input + cache creation + cache read + output；Codex processed = input total + output total，其中 cached input 已包含在 input，reasoning 已包含在 output。
+- 同 provider/日期且数值相同的重复行保持幂等，冲突重复则 fail closed；缺失日期及单 provider 日期仍可用。Codex 日投影保留 370 行，覆盖完整闰年分享窗口及边界余量，不触发第二次日志扫描或第二套缓存。
+- 综合分享卡以显式结束日期确定性生成，使用中性非 provider 配色；每日 tooltip 同时给出 Claude、Codex 和综合值；输入 DTO 只含日期及聚合数值。隐私 canary 测试证明账号、项目、线程、路径、prompt 和日志字段无法进入 SVG。
+
+### Compare 工作流与发布边界
+
+- Compare 现以综合热力图作为首要内容（存在任一 provider 活动时可用）。用户可选 30 天、90 天或一年，设置 80 字符以内标题，查看明确的包含/排除预览，导出 SVG、复制相对 Markdown，或仅重置分享偏好。
+- 本地导出和 Markdown 复制不请求网络。既有 GitHub 发布器由广泛私有仓库权限改为 `public_repo`，先探测仓库公开性、默认分支及创建/更新状态；私有或无法验证目标均 fail closed；写入前必须二次确认精确 owner/repo/branch/path/action/字节数。
+- 目标字符串只在已确认写入成功后保存，凭证继续由 VS Code authentication 管理。Goal 验证只使用 mock transport，没有向真实 GitHub 写入。
+
+### 验证与只读审阅
+
+- 定向纯函数/host 测试：69/69 passed，覆盖公式、重复及双方均缺失日期、对称 Claude-only/Codex-only 输入、非周日起始的 30/90 天网格、确定性 SVG、隐私 canary、公开仓库权限与精确确认、分享偏好重置及 370 天源数据上限。
+- 定向浏览器：5/5 passed，覆盖 Compare 默认位置、双 provider tooltip、显式动作、偏好重置、Light+/Dark+ Axe 和 360 px 约束。
+- 最终完整 Node：862 项，861 passed，0 failed，1 项因文件系统能力 skipped；完整 Playwright：112/112 passed。
+- Claude CLI 首轮检查无阻塞并返回 GO to G5，同时指出三个低风险测试空白：Codex-only 对称输入、双方都缺失的日期、以及非周日起始的 30/90 天 SVG。`5e5bf9f` 为三项加入直接断言；允许的一次修订复核确认全部关闭，并给出最终 GO to G5。
+
+### G4B 通过条件
+
+- [x] 复用既有 provider 日聚合，不新增源扫描或统计缓存。
+- [x] 定义并测试无重复计量的 provider 公式、配置时区范围、重复语义和完整年度源窗口。
+- [x] 在 Compare 交付确定性 SVG、综合分享卡、相对 Markdown、自定义标题/范围和隐私预览。
+- [x] 本地导出保持离线；可选 GitHub 直发采用公开仓库权限、精确确认及纯 mock 测试。
+- [x] 通过定向及完整 Node/浏览器门。
+- [x] 获得规定的 Claude CLI 检查点结论，并关闭本轮选择修订的全部意见。
+
+## G5 README、本地数据清单与已安装 VSIX 截图证据
+
+### 发版文档
+
+- 更新 7 个 README 版本中的 v2.3.1 说明：Claude/Codex/对比覆盖、修正后的时间范围与月份正序、额度观测和重置感知估算、综合热力图分享、本地数据边界及已知不确定性。
+- 新增面向用户的双语简表 `LOCAL-DATA.md`、`LOCAL-DATA.zh-CN.md`，并与规范性数据契约对齐，覆盖来源、派生缓存、匿名额度历史、偏好、保留期、清除入口、远程交互以及绝不保存的数据。
+- 更新 v2.3.1 CHANGELOG、package/lock 版本、精确版本公告及 8 种公告语言。版本仍明确标为未发布；没有执行 Marketplace、远程 release 或仓库发布。
+
+### 真实宿主证据
+
+- 在独立的临时签名 VS Code 副本中构建并安装 v2.3.1 候选 VSIX，扩展目录与 user-data 均隔离，数据源只有合成 Claude/Codex JSONL。
+- 从该安装候选截图并目检 `images/v2.3.1/codex-overview-zh-CN-dark.png`、`images/v2.3.1/codex-weekly-estimate-en-dark.png`、`images/v2.3.1/compare-heatmap-en-light.png`。
+- 三张图覆盖 Codex 概览、重置感知总额度估算以及 Compare 综合热力图/分享控件，并覆盖中英文、深浅主题；不含账号标识、本地路径、真实项目/线程标题、prompt、凭证或用户日志内容。
+- 提交前已将捕获的 JPEG 帧转码为真实 PNG 字节，并移除 EXIF 与 PNG 文本块。repository-policy 测试要求每个 README 引用三张图、每个引用文件实际存在、PNG signature/IEND 结构有效，并禁止 `eXIf`/`iTXt`/`tEXt`/`zTXt` 块。
+
+### 验证与只读审阅
+
+- release/document/quota 定向测试：77/77 passed。
+- 完整 Node：866 项，865 passed，0 failed，1 项因文件系统能力 skipped；完整 Playwright：112/112 passed。
+- G4B host 测试明确确认：只有精确目标写入成功后才保存 GitHub 目标偏好；重置只清理已记住的目标。G5 repository-policy 门另行保护交付截图。
+- Claude CLI 返回 **GO TO G6**，未发现阻塞项、语义错误或隐私错误。其非阻塞意见包括非英语数据清单覆盖，以及更强的截图清理证据；前者记录为未来本地化改进，后者已落实为格式/元数据自动门，并继续以目检覆盖实际渲染像素。最终 VSIX 打包、全新安装/迁移/清除路径 smoke、验收矩阵和候选 hash 属于 G6。
+
+### G5 通过条件
+
+- [x] 更新全部 README、CHANGELOG、版本元数据和迁移/不确定性说明。
+- [x] 跟踪与规范契约一致的双语本地数据清单。
+- [x] 从实际安装的 v2.3.1 候选生成三张隐私安全截图。
+- [x] 通过定向及完整 Node/浏览器门。
+- [x] 获得规定的 Claude CLI 检查点结论，并关闭所选证据加固项。
+- [x] 提交 G5 实现与证据（`e9a149a`）。
+
+## G6 发布候选证据
+
+### 本地数据控制与审计加固
+
+- 在 Settings/Data 中新增本地数据清单和 7 条独立确认路径：重建 Codex 索引、清除额度历史、清除建议数据、重置 UI、重置分享偏好、清除 BYOK secret、清除全部插件派生数据。
+- 独立只读代码审计发现 5 个 blocker 和 2 个高风险点，涉及配置部分删除、Webview 假确认、额度清除竞争/隔离数据、激活写入复活及过宽 setting/迁移删除；全部在 release gate 前关闭。
+- “清除全部”现在会在任何修改前预检所有当前可见配置作用域，排空激活期自有写入，只处理精确 key/文件族，保留未知未来 `ccu.setting.*`，并验证后置条件；遇到 VS Code 无法安全更新的未注册旧配置时零删除失败关闭。
+- 额度全部清除在同一个跨进程 lease 内原子安装合法空 P2 文档，只清理精确辅助文件；范围清除面对隔离或未完成迁移证据时拒绝执行。Webview 重置采用真实 ACK，并以不含数据值的 pending-action tombstone 做幂等重试。
+- 双语规范契约和用户清单已同步上述精确存储、迁移、清除、保留、重试和宿主限制语义。
+
+### 最终自动化与打包门
+
+- `npm run test:release`：Node 共 897 项，896 passed、0 failed、1 项文件系统能力 skip；Playwright 116/116 passed。
+- `git diff --check` 与 TypeScript compile 通过。
+- 固定版本 `@vscode/vsce@3.9.1` 生成最终替代候选 `claude-code-usage-2.3.1-5af60b4.vsix`；仓库 verifier 确认版本 `2.3.1`、入口 `extension/out/extension.js`、107 个 entry、1,903,765 bytes。
+- 候选 SHA-256：`074d0b774b983cebd654eda59c2f6c22168607768aa99a52fb50c98ec199d7a0`。
+
+### 原生 VS Code 隔离 smoke
+
+- 原生 VS Code `1.135.0` 把最终 VSIX 安装到全新隔离 user-data/extensions；第二个隔离配置先装截图阶段候选，再以 `--force` 覆盖安装最终候选。
+- 两个已解包 manifest 均显示 `growthjack.claude-code-usage@2.3.1`、`./out/extension.js` 和新的 Clear All 命令。已解包 runtime 与编译产物 SHA-256 完全一致：`0e86438a32225caffe130ba8326979234b7398e7a07b91cd161d2c0c9e6a2036`。
+- 仅使用合成 Claude/Codex 源数据时，原生 Extension Host 成功激活 `GrowthJack.claude-code-usage`，无插件异常。随后正常终止并重启精确隔离进程，新 Extension Host 再次无异常激活插件。
+- 两个隔离配置均成功卸载，随后扩展列表为空。VS Code 卸载后仍保留 extension globalStorage，印证“可靠删除需先显式清除”的文档说明。源 fixture 未被改写；Codex index 源文件的前后 hash 一致。
+- G5 临时截图壳未参与 G6；其 macOS crash alert 与最终 VSIX 隔离，原生 VS Code 中未复现。
+
+### 安装前 Claude CLI 终审（2026-09-02）
+
+- 使用 Claude Code CLI `2.1.228`、Opus、`max` effort，以 safe/print/no-tools/no-session-persistence 模式只读审阅 G5 检查点 `8eac9a0` 到 G6 实现 `b435e06` 的实际 3,488 行新增、88 行删除补丁以及最终测试、包和原生宿主证据；输入流 SHA-256 为 `350582b6b76e58167f1864787c4192f07b6babf7c15911001beca3b56488fb1e`。输入不含真实日志、账号、凭证、项目内容或用户路径。
+- Claude 判定 **Release blockers: None**，最终结论为 **GO FOR USER INSTALL**。这只授权维护者进行本地安装测试，不授权 push、Marketplace、远程 release 或真实 GitHub 写入。
+- 安装验收优先覆盖三项：无 Claude/Codex 日志时直接打开“管理本地数据与隐私”；带旧明文 `claudeCodeUsage.advice.apiKey` 的升级激活；在临时 workspace 中分别验证受阻旧配置和成功 Clear All。Clear All 会删除该临时 workspace `.vscode/settings.json` 中明确拥有的 `claudeCodeUsage.*` 设置，不能在重要工作区试验。
+- 非阻塞跟进包括：补齐真实临时 globalStorage 的 Clear All 后置条件端到端测试、建议数据清除与并发迁移的竞争测试、Webview 2 秒 ACK 超时、分享偏好重置范围、以及把受阻 legacy key 精确传达给用户。任一手测若出现未处理激活失败或范围外删除，应在发布前重新开候选修复。
+- 随后的维护者预览反馈修订修改了分享工作台、热力图渲染、周额度估算、本地化文案、测试和发布文档，因此取代此前对应 `b435e06` 的包；最终复核与候选证据记录如下。
+
+### 预览反馈修订与最终替代候选（2026-09-02）
+
+- 数据字体已恢复为 VS Code UI 字体，只有 Markdown 字段继续使用编辑器等宽字体。“对比”页改为预览优先的分享工作台，包含隐私徽标、成组卡片设置、显式操作、可折叠 Markdown 结果、桌面自适应预览，同时保留窄屏横向滚动。
+- 热力图配色可在本地选择。默认“学术紫”严格使用 `#ebedf0`、`#eee8f8`、`#d8c9f1`、`#bca5e6`、`#8668c7`、`#4f2f87`；另有三套预设和一个经校验的自定义主色。分位数并列、稀疏最大值、近白自定义色、短区间图例边界、SVG 注入、对比度、确定性输出，以及桌面完整显示 `More` 图例均有直接测试。
+- 对于内部一致的 Claude/Codex 额度观测，进行中和已结束窗口现在都会展示总额度与未用 API 等效订阅耐用度估算；未归属或边界近似证据仍可低可信度展示。只有无有效观测、确有竞争性重叠额度系列，或最后观测过旧且后续日志已超过其推导候选值时才保留破折号；最后一种情况保留低可信度总额下界，但不伪造 `$0` 未用值。
+- Claude CLI 以 print、禁用工具、禁用会话持久化的只读模式审阅了经清理的反馈修订，并给出 **GO FOR USER INSTALL**，未发现 blocker、网络/权限或隐私风险。其关于稀疏/并列分位数、自定义色对比度、provider 对称可信度、过时观测超额、附加价格文案、短区间图例边界、精确配色/source-overlap 夹具、预览语义、Axe 完整性及 UI 字体断言的非阻塞意见，均在最终门前关闭。
+- 最终替代候选通过 896/897 项 Node 测试（唯一 skip 为已记录的文件系统能力夹具）、116/116 项 Playwright、TypeScript compile、`git diff --check`、双语视觉 QA 和仓库 VSIX policy verifier。最终英文浅色与中文深色渲染使用合成数据并已目检，不含真实账号、项目、线程、路径或日志。
+- 原生 VS Code `1.135.0` 在同一隔离临时 profile 中把最终包强制覆盖安装到上一候选之上，并列出 `growthjack.claude-code-usage@2.3.1`。已安装的 `webview.js`、`weeklyValue.js` 和 `combinedHeatmapSvg.js` 与编译文件哈希完全一致。未发生 push、Marketplace 发布、远程 release 或真实 GitHub 写入。
+- 运行时候选 commit：`5af60b4`（包含 `5e6e5cc` 的主要反馈实现）。包：`claude-code-usage-2.3.1-5af60b4.vsix`，1,903,765 bytes，SHA-256 `074d0b774b983cebd654eda59c2f6c22168607768aa99a52fb50c98ec199d7a0`。其后的本地文档 commit 仅记录本证据，不进入 VSIX。
+
+### 安装后回归修正与最终本地候选（2026-09-02）
+
+- 本地实现 commit `666f04c` 修复维护者安装后发现的回归：Claude 的中间范围改为配置时区下“今天 + 前 29 个自然日”，Today/30 天/月内日表统一读取 `byLocalDay`；Today 无活动时不再把空卡片误当成缺页。
+- Codex 当前周期可由最后一次真实观测给出明确标为低可信度的总额与未用耐用度估算；周额度表默认折叠。Compare 改为纵向预览优先，卡片设置紧接在分享图下方，不再保留右侧大块空白。
+- Codex 状态栏主项改为配置时区下的今日用量，额度短文本使用与 Claude 一致的“已用百分比”。tooltip 复用进度条、阈值和重置列；状态背景由当前偏好实际渲染的有效窗口中最高用量驱动，因此 `wk 40%` 与同表 `5h 96%` 并存时会正确显示红色警告。
+- 新增洛杉矶 DST/本地日边界夹具，直接断言 Today 日行等于 Today 汇总、`Today ≤ 30 天 ≤ 全部` 且物化不增加 JSONL body read；另有双额度窗口、过期窗口、provider 标签转义和真实 `renderCodex` wiring 测试。
+- 最终门：TypeScript compile；Node 903 项中 902 passed、0 failed、1 项既有文件系统能力 skip；Playwright 117/117；`git diff --check` 通过。固定 `@vscode/vsce@3.9.1` 生成 `claude-code-usage-2.3.1-regression-fix-final-20260902.vsix`，仓库 verifier 确认 107 files、1,905,981 bytes、版本 `2.3.1`、入口 `extension/out/extension.js`，SHA-256 `869149b3e6034da4341ba55fa50c2d365accb5280e9ffd16520dfc845340f5b8`。
+- 该包强制覆盖安装至隔离 VS Code/profile，仅使用合成数据。安装后的 `extension.js`、`webview.js`、`weeklyValue.js`、`statusBar.js` 与编译产物哈希完全一致；真实可访问树确认分享设置位于预览下方、两组“周期详情”默认关闭、Codex 当前 74% 可见总额/未用低可信度估算，状态栏为紧凑的 `CX 5M` / `wk 74%`。
+- Claude Code CLI `2.1.228`、Opus、`max` effort 以 safe/print/no-tools/no-session-persistence 模式先指出两个 blocker（Claude 日表口径和 Codex 状态色），修订后复核将 B1/B2 均判定 **CLOSED**、路线图判定 **ADEQUATE**，最终结论为本地候选 **GO**。复核输入流 SHA-256 为 `437fd7a5a593d4b272877f5641e6a8d3545243c9cd575e3684ed50cd29602e1a`，仅含相对路径补丁、合成证据和路线图。
+- 非阻塞一致性工作不再扩入 v2.3.1，已登记到 [`v2.4 Claude / Codex 交互一致性路线图`](../roadmap/provider-parity-v2.4.zh-CN.md)：月→日、日→小时、零 JSONL 点击、刷新/重载状态保留、非 UTC/DST 守恒、稀疏范围补零、唯一可访问名称、顶层图表与状态/额度细节契约。维护清理还包括明确 `byDay`/`byLocalDay` 不变量、清除 `month` 命名漂移、结构化 tooltip 文案及 five-hour-only manager 夹具。
+- 未发生 push、Marketplace 发布、远程 release、真实 GitHub 写入或真实用户数据扫描；此前所有 VSIX 均由该包取代。
+
+### 简洁设置与额度余量跟进候选（2026-09-02）
+
+- 跟进实现 commit `ddfe99d` 从插件 Settings 界面移除“本地数据与隐私控制”清单，同时保留仓库中的规范文档、宿主侧精确清除契约及其安全测试。设置页现在只保留一个共享的“启用分享工作台”开关：默认开启，同时控制 Compare 与供应商分享卡；关闭后完整隐藏分享界面，所有导出仍必须显式触发。
+- Compare 继续采用纵向“预览优先”，SVG 现会先铺满桌面可用宽度，再显示其下方的卡片设置；周周期详情仍默认折叠。使用合成数据完成的中文深色目检确认：开启时不再留下原右侧空洞，关闭时 Compare 汇总和两组周额度图仍完整保留。
+- Codex 额度状态栏短文本现按要求显示**剩余**比例（已用 36% 时显示 `wk 64%`）。tooltip 进度条、严重度颜色和警告阈值仍由真实已用比例驱动；独立的 `CX` token 状态项继续显示配置时区下的今日范围，而非最近任务小计。
+- 经用户授权，对当前默认 Claude profile 做了只读排查，仅检查文件/时间戳元数据和允许列出的数值用量字段。生产 loader 找到 682 个项目 JSONL，并正确重建最近 30 天为 104 条消息、2,487,790 个输出 token，但 2026-09-02 的持久化用量为 0。`history.jsonl` 中 2026-09-02 的 4 条记录都没有 usage 字段，也找不到对应项目 transcript；2026-09-01 同样没有可计量记录。既有审计台账明确记录这些 Claude CLI 审阅使用了 `--no-session-persistence`；该模式不会留下可计量 transcript/token，因此插件不能诚实回填缺失的今日/昨日数据。本次未报告或改写 prompt、response、command、凭证、路径或原始日志内容。
+- 桌面宽度修订后的最终门：TypeScript compile；Node 共 903 项，902 passed、0 failed、1 项既有文件系统能力 skip；Playwright 118/118；综合分享定向测试 6/6；`git diff --check`；ZIP 完整性；仓库 VSIX policy verifier。固定 `@vscode/vsce@3.9.1` 生成 `claude-code-usage-2.3.1-followup-final-20260902.vsix`，107 files、1,906,703 bytes，SHA-256 `33bc404ce0dc693f7d97d40dd485c8d6ea96c8727ea9b178fe978cbb101daa0f`。
+- 该包成功安装到全新的原生 VS Code 隔离 user-data/extensions，并列出 `growthjack.claude-code-usage@2.3.1`。主 checkout 未被修改。未发生 push、Marketplace 发布、远程 release 或真实 GitHub 写入；上面的只读 Claude 排查是早期候选证据之后唯一新增的真实数据访问。
+
+### 验收矩阵
+
+| 需求 | 实现 | 自动验证 | 截图/宿主证据 |
+|---|---|---|---|
+| 最近 30 天守恒、去重、月份正序 | `src/dateKeys.ts`、`src/providers/codex/codexDedup.ts`、`codexIndex.ts`、`codexUsage.ts`、`codexView.ts` | `dateKeys`、`codexDedup`、`codexIndex`、`codexUsage` 与 Webview visual/interaction suites | Codex 概览/周额度截图；原生激活与重启 |
+| reasoning effort 规范化及有意义的 `unknown` | `src/providers/codex/codexSchema.ts`、`codexParser.ts`、`codexUsage.ts`、`src/webview.ts` | 当前/旧版/缺失/非法/零值/非零 effort fixture 与总量守恒 | Codex 概览截图 |
+| 匿名额度历史、多次重置、稳健总额/未用估算 | `src/quotaObservationStore.ts`、`codexQuotaHistory.ts`、`src/weeklyValue.ts` | quota store/history、weekly value、竞争、隔离、迁移、歧义 fixture | 周额度截图；原生宿主生成 P2 store |
+| Claude/Codex 视觉、键盘、主题和窄屏对齐 | 共享 `src/webview.ts`、`src/codexViewComponents.ts` token/组件 | accessibility、responsive、visual、interaction suites | G5 中英文、深浅主题截图 |
+| Compare 综合热力图与隐私有界分享 | `src/combinedHeatmap.ts`、`combinedHeatmapSvg.ts`、`githubHeatmapPublish.ts`、`webview.ts` | 确定性 SVG、重复/冲突、时区、隐私 canary、mock GitHub、可访问性测试 | Compare 热力图/分享截图 |
+| 可审计本地清单与精确清除/迁移边界 | `src/localDataControls.ts`、`extension.ts`、`settings.ts`、`quotaObservationStore.ts` | `localDataControls`、`localDataExtension`、`settingsPrivacy`、额度竞争/隔离、UI ACK suites | 原生安装/激活/重启/卸载；观察到宿主保留存储 |
+| README、契约、截图和迁移披露 | 全部 README、CHANGELOG、`LOCAL-DATA*`、规范契约、release ledger | repository/release policy 与截图 metadata/privacy gates | 3 张安装候选截图 |
+| 无远程副作用的可安装候选 | package manifest、编译 `out`、`.github/scripts/verify-vsix.mjs` | 完整 release gate 与 VSIX policy verifier | 2 个隔离原生配置；无 push/release/Marketplace/真实 GitHub 写入 |
+
+### G6 通过条件
+
+- [x] 关闭只读审计全部 blocker 和高风险意见。
+- [x] 通过最终 compile、diff、完整 Node 与完整浏览器测试。
+- [x] 构建并按 policy 校验 v2.3.1 VSIX，记录 SHA-256。
+- [x] 验证隔离全新安装、候选覆盖更新、真实激活、完整进程 reload、卸载、迁移 fixture、重复刷新 fixture 和精确清除路径。
+- [x] 记录“需求 → 代码 → 测试 → 证据”验收矩阵。
+- [x] 获得安装前 Claude CLI 终审 **GO FOR USER INSTALL**，并登记人工安装检查点。
+- [x] 在 push、Marketplace 发布、远程 release 或真实 GitHub 写入之前停止。
+- [x] 提交 G6 实现与反馈修订（`b435e06`、`5e6e5cc`、`5af60b4`）；其后的本地文档 commit 只负责把最终替代包证据回填到双语台账。
+
+## 后续更新规则
+
+每阶段必须先完成对应自动化验证，再更新本表中的 commit、测试证据、Claude 结论和风险。G6 的最终验收矩阵应由本台账中的证据生成；任何未通过项不得用截图或文案替代。
+
+后续“选择单一项目、按需调用 AI 审阅输入/输出并从用量行为给出证据化建议”的能力已放入 [`v2.5.3 项目级 AI 用量审阅计划`](../superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.zh-CN.md)。它不回填 v2.3.1，需另建 Goal 并明确授权到 R0–R4 或包含本机 Claude CLI 安全门的 R5。
diff --git a/docs/releases/v2.3.1/AI-ADVICE-EFFECTIVENESS-V2.3.1.md b/docs/releases/v2.3.1/AI-ADVICE-EFFECTIVENESS-V2.3.1.md
new file mode 100644
index 00000000..0f8d8ee0
--- /dev/null
+++ b/docs/releases/v2.3.1/AI-ADVICE-EFFECTIVENESS-V2.3.1.md
@@ -0,0 +1,132 @@
+# v2.3.1 AI 建议有效性：候选实现说明
+
+## 状态与边界
+
+当前 worktree 是从正式 `v2.3.0` 基线选择性移植并继续收敛的 v2.3.1 本地候选；版本号、
+release workflow 与发布入口保持不变，尚未发布。
+
+候选代码已经进入 `extension.ts`、`webview.ts` 与生产 VSIX 路径，但相关功能默认关闭。
+关闭、隐藏或未授权时不创建 AI timer、watcher、worker、network 或额外日志扫描。启用后，
+只有用户先检查完整请求预览、再另行点击“发送”，才会调用现有用户配置的 BYOK endpoint。
+旧 `Get AI Advice` 命令仅打开这一统一界面；Prompt Optimizer 也使用同一 prepare → preview →
+explicit Send → strict parse → local feedback 边界，不再保留一次性持久授权或宽松 parser fallback。
+
+## 新增核心
+
+### `src/adviceEffectiveness/contract.ts`
+
+`AdviceContract` 是 provider-neutral 的 v1 契约，统一保存：
+
+- host 生成的本地 observation 与 evidence；
+- direct / correlational / proxy 证据强度；
+- AI 只能引用已有证据的 explanation；
+- 带 `when` 与 stop condition 的 conditional action；
+- 带最小可比任务数与质量 guardrail 的 success criterion；
+- host 盖章的 privacy、source、confidence、quality flags 与 provenance。
+
+模型不能提供 observation、evidence、privacy 或 provenance。`createAdviceContract()`
+只在整个引用图和隐私声明一致时返回 `{ ok: true }`。空 recommendations 是合法的
+“没有足够证据下结论”，不会自动补通用建议。
+
+### `src/adviceEffectiveness/payload.ts`
+
+`buildAdviceAggregateSnapshot()` 只消费现有 `UsageData` aggregate，并通过 allow-list
+重建 DTO。完整/自定义 model ID 被压成 `opus / sonnet / haiku / fable / other`；raw
+record、project label/path、cwd、session、prompt、response、credential 没有目标字段。
+可远程发送的 metric 还有单独 allow-list；新增 metric 必须经过显式隐私评审。low/unknown
+confidence 或仍带 quality flag 的 source 会在 payload 生成前失败，不会要求模型填补缺口。
+
+`prepareAdvicePayload()` 默认生成 `aggregates-only` 的内层 evidence body，且序列化结果中完全没有
+`promptSamples` key。只有调用者额外提供：
+
+```ts
+{ consent: 'explicit', samples: [{ text: '...' }] }
+```
+
+才会加入受数量、单条长度和总长度限制的 prompt 文本；sample 上的 `cwd` 等多余字段仍会被
+丢弃。`advice.userContext` 与 prompt sample 共用独立于 aggregate 的 personalization consent；
+未授权时两者都不进入 body，授权后必须逐字出现在完整预览中。
+
+生产路径再由 `preparedRequest.ts` 把内层 evidence body 封装为完整 Anthropic / OpenAI-compatible
+provider HTTP JSON body。该 body 只序列化一次，生成 host-retained `PreparedAiInvocation`、
+`canonicalBytes` 与 SHA-256；预览从同一 bytes 解码，实际发送和同一次发送内的 retry / curl
+fallback 继续复用该 Prepared bytes。API key 只在发送边界加入 header，不进入预览 body。
+
+### `src/adviceEffectiveness/versionedPersistence.ts`
+
+生产反馈统一写入 `ccu.adviceEffectiveness.localState` v2 envelope，只接受
+`helpful / not-helpful / applied`、格式验证后的 advice/recommendation ID 与本地 epoch 时间。
+它不接受自由文本、prompt、payload、解释、endpoint、path 或 session ID。helpful 与
+not-helpful 互斥，applied 独立；再次点击已选状态会撤回并在全部状态清空时删除该条记录。
+Advice 的每条 recommendation 与 Prompt Optimizer 的每次结果都走同一个写入函数。
+损坏、未知版本或带额外字段的数据 fail closed，写失败后不会用旧快照覆盖新决定。
+
+### `src/adviceEffectiveness/comparison.ts`
+
+`compareAdviceEffectiveness()` 是无时间/IO 依赖的 paired comparison。只有以下条件全部
+满足，才可能返回 `improved`：
+
+- task kind、complexity、provider、model family、effort、metric definition、单位、方向、
+  quality rubric 在 pair 内和 cohort 间一致；
+- coverage complete，confidence 不是 low/unknown，无未允许的 quality flag；
+- 达到预先声明的最小 pair 数，数值均为有限值且 baseline 非零；
+- before/after 质量证据已知，after 全部通过 rubric；
+- 主指标达到阈值，同时 minimum quality 与最大允许退化两个 guardrail 都守住。
+
+任何可比性、覆盖、置信度、数值或质量证据问题都返回 `insufficient-evidence`。主指标
+改善但质量退化返回 `quality-guardrail-failed`；没有达到预设幅度只返回
+`no-demonstrated-improvement`，不声称建议造成伤害或收益。
+
+`comparisonPairing.ts`、`comparisonProduction.ts` 与 `comparisonResult.ts` 把这条纯比较边界接入
+真实、已净化的 provider/task-level 物化 aggregate。只有 scope、task kind、complexity、provider、
+model、effort、metric definition 与 quality rubric 全部相同，且 applied 时间能可靠划分前后时，
+才形成 comparable pair。版本化 result envelope 只保存 schema、provider、measurement / recommendation
+version、guardrail、replay eligibility、sample 与 result；prompt、response、session、path、正文和未知字段
+没有目标字段。无可靠 pair 时 UI 明确显示“证据不足”。
+
+### `src/adviceEffectiveness/structuredOutput.ts`
+
+`parseStructuredAdviceOutput()` 只接受一个严格 JSON 值，并逐层拒绝未知/缺失字段、错误
+schema version、非法枚举、超长/超量内容、重复 ID、空 action/criterion 和未知证据引用。
+任一 recommendation 非法会拒绝整批。它不会剥 Markdown fence、修 JSON、接受尾随 prose、
+返回 partial batch，或把 raw 输出 fallback 成看似有效的建议；错误结果也不回显 raw 模型
+正文。`recommendations: []` 是明确的 no-conclusion 成功结果。
+
+## 当前生产闭环
+
+1. **本地证据**：Claude 只消费 `claudeIncrementalIndex` 已物化的同窗口 aggregate / session
+   summary；Codex 只消费现有结构化数值 insight 与任务级物化 aggregate，不新增日志扫描器。
+2. **独立 consent**：Advice 的 aggregate consent 与 prompt-personalization consent 分开持久化；
+   默认是 aggregates-only。Optimizer 只包含用户主动粘贴的 draft，不使用持久网络授权。
+3. **exact preview / explicit Send**：host 保留完整 Prepared provider body；Webview 只持有 opaque
+   snapshot ID、精确 body、byte count、content type、data mode 与 SHA-256。只有另行 Send 点击会联网。
+4. **唯一生产 sender**：Advice 与 Optimizer 都进入 `sendPreparedModelRequest()` →
+   `sendPreparedAiInvocation()`，且只能使用配置的 BYOK key / endpoint。
+5. **strict response**：Advice 只接受 exact-shape JSON 与已知 evidence references；Optimizer 只接受
+   完整 marker / 三行 settings contract。任一失败都不显示 raw 或自由文本 fallback。
+6. **可撤销本地 feedback**：每条 Advice recommendation 和 Optimizer result 共用 v2 bounded ledger；
+   不接 analytics、telemetry、contribution endpoint 或 advice payload。
+7. **有效性评估**：只有 applied 后出现严格可比的前后任务时才写 pair / result envelope；否则显示
+   `insufficient-evidence`。结果是受控描述性证据，不是因果证明。
+
+## 排除项与剩余边界
+
+- `claudeCodeUsage.getAdvice` 只打开统一 Content 界面，不再构建旧 summary 或直接调用模型。
+- `legacyBridge.ts`、`adviceSummary.ts`、旧 demo / personalization / experiment 准备模块被排除出 VSIX，
+  且 `extension.ts` / `webview.ts` 没有生产调用点；它们不能成为默认或第三条 sender。
+- 生产 backend 固定为 BYOK `api`。Claude Code OAuth/subscription 凭据仅服务既有 quota/usage，
+  不用于 Advice 或 Optimizer，也不存在后台模型请求。
+- Codex remote advice 仍保持关闭；Codex recommendation 与 comparison 使用本地结构数据。
+- comparison 不做显著性或因果识别；缺少可靠 cohort、质量证据或最小样本时保持证据不足。
+- feedback 不存自由文本、不同步、不发 telemetry；Optimizer feedback 当前不触发 comparable-task comparison。
+
+## 验证
+
+测试平铺在 `src/test/` 与 `tests/ui/`，覆盖契约引用、完整 Prepared preview/send object identity、
+默认 aggregates-only、prompt 独立 opt-in、Optimizer 关闭态与严格 parser、敌意隐私字段注入、
+可撤销本地 feedback、真实 pairing / 版本化 result envelope、可比性 / quality guardrail 以及
+未知字段 fail-closed。候选验证仍按仓库流程运行：
+
+```bash
+npm test
+```
diff --git a/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md
new file mode 100644
index 00000000..53fb5e0b
--- /dev/null
+++ b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md
@@ -0,0 +1,120 @@
+# v2.3.1 AI Advice Effectiveness: Experimental UI Design Plan
+
+> Status: v2.3.1 integration candidate only. The feature flag is off by default;
+> this document is not a current-release commitment.
+
+## Goal and boundaries
+
+The UI answers one question: can a user see which local evidence supports an
+advice candidate, exactly what would leave the device, and how effectiveness
+would be judged before opting in? It extends the existing AI Advice and Prompt
+Optimizer cards on the Content tab instead of adding a third top-level entry.
+
+Both features are off by default and create no AI network work while disabled.
+When enabled, AI Advice and Prompt Optimizer use the same interaction grammar:
+prepare a complete provider HTTP JSON body, preview its exact UTF-8 bytes, require
+a separate explicit Send click, strictly parse the response, and offer reversible
+local helpful / not-helpful / applied feedback. There is no automatic or default
+model request.
+
+## Visual system
+
+- **Color:** use existing VS Code theme tokens only. Background and copy use
+  `--vscode-editor-background` / `--vscode-foreground`; borders and secondary
+  copy use `--vscode-panel-border` / `--vscode-descriptionForeground`; actions
+  and focus use `--vscode-button-background` / `--vscode-focusBorder`; the
+  snapshot uses `--vscode-editorWidget-background`. Light+ and Dark+ remain
+  host-owned, with no new gradient or hard-coded brand accent.
+- **Type:** explanatory copy uses `--vscode-font-family` at the existing 13px
+  density. Metrics, byte counts, and JSON use `--vscode-editor-font-family`.
+  Small 10–11px status stamps never carry meaning by color alone.
+- **Spacing:** reuse `.action-card`, `.model-details-stacked`, and the existing
+  button/input rhythm. Avoid a new oversized KPI-card language.
+- **Signature:** one continuous evidence spine joins five ordered stages. The
+  sealed snapshot header reads `SEALED · N BYTES · SHA-256`, and its body is
+  decoded verbatim from the same canonical UTF-8 bytes.
+
+## Information architecture and wireframe
+
+Wide layout:
+
+```text
+┌ AI advice effectiveness (experimental) ──────────────────────────┐
+│ [Observed] ─── [Evidence] ─── [Advice] ─── [Action] ─── [Result] │
+│   values          strength       conditional   local feedback     │
+│                                                   sample/guardrail│
+│                                                                  │
+│ □ Allow aggregates only   □ Allow prompt samples (separate, off) │
+│ [Create sealed snapshot]                                         │
+│ ▾ SEALED · 1248 BYTES · SHA-256 · AGGREGATES ONLY                │
+│   {"schemaVersion":1,...}                                        │
+│ [Send prepared request]  (disabled until a valid preview exists) │
+│ Helpful ○  Not helpful ○  Applied ○                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+At narrow widths the five stages stack vertically and the spine becomes a left
+rail. Consent controls and actions wrap naturally. JSON scrolls horizontally;
+actual transmitted bytes are never compressed or elided.
+
+## Interaction and accessibility
+
+- Aggregate consent and prompt-personalization consent are separate values in
+  version-migrated VS Code `globalState`. Both start off; prompt consent is
+  disabled until aggregate consent is selected. Every included prompt is
+  visible in the sealed snapshot.
+- “Create sealed snapshot” asks the extension host to prepare the object. The
+  host rechecks the flag and consent, serializes the complete provider body once,
+  and retains its canonical UTF-8 bytes. Preview text, byte count, and SHA-256 all
+  come from that object. The separately clicked Send action resolves the opaque
+  snapshot ID and passes the same Prepared object to the sole production BYOK
+  transport; it cannot rebuild a request from webview text.
+- Prompt Optimizer has the same preview and Send stages. Its body contains only
+  the pasted draft plus the fixed optimizer system instruction and configured
+  model fields; it has no persistent “first-run authorization.”
+- Advice output uses the strict evidence-referencing JSON parser. Optimizer output
+  uses its strict marker/settings parser. Neither repairs malformed output or
+  falls back to free-form prose.
+- Helpful / not helpful / applied are native buttons with `aria-pressed` for
+  every advice recommendation and for an Optimizer result. Selecting an active
+  button again withdraws that value. Helpful and not helpful are mutually
+  exclusive; applied is independent. All mutations use the same bounded local
+  `globalState` envelope and never enter a remote payload.
+- Every action is keyboard reachable. Headings, lists, `fieldset` / `legend`,
+  `aria-live`, and VS Code focus tokens give screen-reader and focus semantics.
+  Consent, disclosure, and provider UI state survive a webview reload.
+- The result stage says “insufficient evidence” until comparable sample and
+  quality guardrails are met; a one-off movement is never called effective.
+
+## Content and privacy rules
+
+- The default route carries same-window aggregate numbers, coarse model families,
+  allow-listed metrics, confidence, and evidence references only. It never accepts
+  or serializes raw sessions, per-record data, prompts, responses, project paths,
+  cwd values, or stable session IDs.
+- Long sessions use elapsed-duration as a proxy; large context uses numeric token
+  thresholds. A conditional “start a new session / `/clear` at a stable task
+  boundary” action appears only when deterministic thresholds and sample rules pass.
+- Topic drift is semantic. It may enter the AI Advice model request only after
+  separate prompt-personalization consent, with every included prompt visible in
+  the exact preview. The host never infers drift from body-free signals.
+- Strict parse failure, unknown persistence versions, damaged state, or incomplete
+  evidence closes the result and never produces a permissive fallback suggestion.
+- `claudeCodeUsage.getAdvice` only reveals the unified Content surface. It does
+  not call a model, build a legacy summary, or open a separate Markdown result.
+- `legacyBridge.ts`, `adviceSummary.ts`, and the demo/preparation modules have no
+  production import and are excluded from the VSIX. They are neither a default
+  transport nor a third sender.
+- Only the configured Anthropic/OpenAI-compatible BYOK endpoint may receive these
+  requests. Claude Code OAuth/subscription credentials are not an AI backend, and
+  no preview, refresh, timer, or background task sends a model request.
+
+## Design critique and revision
+
+An early direction risked becoming another generic dashboard and a third isolated
+experience. The revision embeds the evidence chain in the existing Advice card and
+applies the same preview, Send, strict-result, and feedback grammar to Prompt
+Optimizer. The only new visual signature is the sealed byte snapshot because it
+directly supports privacy review. Narrow layouts, keyboard use, screen readers, and
+theme changes remain candidate checks; with either feature disabled, its host
+message seam fails closed and creates no AI network resource.
diff --git a/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md
new file mode 100644
index 00000000..2d1ab032
--- /dev/null
+++ b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md
@@ -0,0 +1,92 @@
+# v2.3.1 AI 建议有效性：实验界面设计计划
+
+> 状态：仅用于 v2.3.1 候选集成。功能开关默认关闭；本文不代表当前发布承诺。
+
+## 设计目标与边界
+
+界面服务于一个明确问题：用户能否先看清“哪些本地证据支持哪条建议、若继续会发送什么、
+应用后怎样判断是否有效”，再决定是否参与实验。它扩展 Content 页已有的 AI Advice 与 Prompt
+Optimizer 卡片，不增加第三个顶层入口。
+
+两项功能都默认关闭，关闭时不创建任何 AI 网络工作。启用后，AI Advice 与 Prompt Optimizer
+使用同一种交互语法：准备完整 provider HTTP JSON body、精确预览其 UTF-8 bytes、要求用户另行
+明确点击“发送”、严格解析响应，并提供可撤销的本地“有用 / 无用 / 已应用”反馈。不存在自动或
+默认模型请求。
+
+## 视觉系统
+
+- **颜色**：只使用现有 VS Code 主题令牌。背景与正文使用
+  `--vscode-editor-background` / `--vscode-foreground`；边界和次级文本使用
+  `--vscode-panel-border` / `--vscode-descriptionForeground`；交互和焦点使用
+  `--vscode-button-background` / `--vscode-focusBorder`；快照使用
+  `--vscode-editorWidget-background` 与编辑器等宽字体。Light+ 与 Dark+ 均由宿主主题决定，
+  不引入品牌外的渐变或硬编码强调色。
+- **字体**：说明文字沿用 `--vscode-font-family` 与现有 13px 密度；指标、字节数和 JSON
+  使用 `--vscode-editor-font-family`。小型状态章保持 10–11px，但不承载唯一语义。
+- **空间**：沿用 `.action-card`、`.model-details-stacked`、现有按钮与输入组件的间距，
+  保持 Content 页的信息密度，不新增“大号 KPI 卡片”风格。
+- **标志性元素**：一条连续的“证据脊柱”连接五个有序阶段；密封快照标题显示
+  `SEALED · N BYTES · SHA-256`，正文逐字呈现同一组 canonical UTF-8 bytes。
+
+## 信息架构与草图
+
+宽屏：
+
+```text
+┌ AI 建议有效性（实验）──────────────────────────────────────────────┐
+│ [观察] ─── [证据] ─── [建议] ─── [行动] ─── [结果]               │
+│  数值        强度        有条件      本地反馈      样本/质量护栏       │
+│                                                                  │
+│ □ 仅允许聚合数据     □ 允许附加用户 prompt（默认关，独立同意）        │
+│ [生成密封快照]                                                    │
+│ ▾ SEALED · 1248 BYTES · SHA-256 · AGGREGATES ONLY                │
+│   {"schemaVersion":1,...}                                        │
+│ [发送已准备请求]（只有有效预览后才启用）                              │
+│ 有用 ○  无用 ○  已应用 ○                                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+窄屏时五个阶段改为纵向排列，脊柱成为左侧竖线；同意项和按钮自然换行，JSON 区域横向滚动，
+不压缩或省略发送字节。
+
+## 交互与可访问性
+
+- 两项同意分开保存于带版本迁移的 VS Code `globalState`：聚合数据默认未同意；prompt 个性化默认关闭，
+  且只有聚合同意后才可选择。prompt 的正文必然出现在密封快照中。
+- “生成密封快照”只向 extension host 请求准备对象。host 再次验证实验开关与同意状态，只序列化
+  一次完整 provider body，并保留 canonical UTF-8 bytes；预览正文、byte count 与 SHA-256 都由
+  该对象派生。用户另行点击“发送”后，host 才通过 opaque snapshot ID 取回同一个 Prepared 对象，
+  交给唯一生产 BYOK transport；不能从 webview 文本重建请求。
+- Prompt Optimizer 使用相同的预览与发送阶段。其 body 只包含用户粘贴的 draft、固定 optimizer
+  system instruction 与已配置模型字段；不存在持久的“首次运行授权”。
+- Advice 输出只进入严格的 evidence-reference JSON parser；Optimizer 输出只进入严格的 marker / settings
+  parser。两者都不修复畸形输出，也不 fallback 到自由文本。
+- 每条 Advice recommendation 和每次 Optimizer 结果都使用原生 `<button>` 提供有用 / 无用 / 已应用，
+  并通过 `aria-pressed` 表达状态。再次点击已选按钮会撤回该值；有用与无用互斥，已应用独立。
+  所有修改共用同一个有界 `globalState` envelope，绝不进入远程 payload。
+- 所有交互可用键盘完成；结构使用标题、列表、`fieldset` / `legend`、`aria-live`，焦点使用
+  VS Code 焦点令牌。刷新后同意、展开状态和选中的 provider UI 状态保持。
+- 结果阶段在最小可比样本或质量护栏不足时只显示“证据不足”，不把单次波动表述为有效。
+
+## 内容与隐私规则
+
+- 默认路径仅包含同一窗口的聚合数值、粗粒度模型家族、allow-list 指标、置信度与证据引用；
+  不接收或序列化 raw session、逐条记录、prompt、response、工程路径、cwd 或稳定会话 ID。
+- 长 Session 只使用 elapsed-duration 代理；大上下文只使用数值 token 阈值。只有确定性阈值
+  达到且样本充分时，才呈现“在稳定任务边界新建 Session / `/clear`”的条件动作。
+- 主题漂移属于语义判断；只有用户单独允许 prompt 个性化时才可能进入 AI Advice 模型请求，且相关
+  prompt 必须完整出现在精确预览中。host 不从无正文信号推断主题漂移。
+- 严格解析失败、版本未知、持久化损坏或证据不完整时关闭结果，不生成宽松 fallback 建议。
+- `claudeCodeUsage.getAdvice` 只负责显示统一 Content 界面；它不调用模型、不构建旧 summary，
+  也不打开独立 Markdown 结果。
+- `legacyBridge.ts`、`adviceSummary.ts` 与 demo／准备模块没有生产 import，并被排除出 VSIX；
+  它们既不是默认 transport，也不是第三条 sender。
+- 只有配置的 Anthropic / OpenAI-compatible BYOK endpoint 可以接收这些请求。Claude Code OAuth / subscription
+  凭据不是 AI backend；预览、刷新、timer 或后台任务都不会发送模型请求。
+
+## 设计自检与修订
+
+初稿容易演变为另一组通用指标卡，造成第三套孤立体验。修订后，证据链嵌入现有 Advice 卡，
+Prompt Optimizer 也采用同一 preview、Send、strict result 与 feedback 语法。唯一新增的视觉签名是
+“密封字节快照”，它直接服务于隐私核对，不是装饰。窄屏、键盘、屏幕阅读器和主题切换仍是候选
+验收项；任一功能关闭时，其 host message seam 都会失败关闭，并且不创建 AI 网络资源。
diff --git a/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-V2.3.1.md b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-V2.3.1.md
new file mode 100644
index 00000000..5ff000ea
--- /dev/null
+++ b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-V2.3.1.md
@@ -0,0 +1,284 @@
+# v2.3.1 AI Advice Effectiveness: Integration Handoff
+
+Companion documents: [中文交接说明](AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md) · [English handoff](AI-ADVICE-INTEGRATION-V2.3.1.md)
+
+Related design: [中文设计说明](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md) · [English design](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md)
+
+## 1. Status and safety conclusion
+
+This branch provides a **default-off v2.3.1 local candidate**, not a published feature. It implements an “Observation → Evidence → Advice → Action → Result” chain inside the existing shared Claude/Codex dashboard and connects the optional remote step to the existing user-configured BYOK endpoint. It makes no automatic model call and sends no telemetry.
+
+The current safety boundary is:
+
+- `advice.effectiveness.enabled` and `advice.optimizer.enabled` default to `false`. Their host message seams also recheck the setting, so disabled or hidden UI cannot create an AI network resource.
+- Remote AI is production-reachable in this candidate only after a complete request preview and a separate explicit Send click. Previewing never sends.
+- Claude can create a remote preview only after separate explicit aggregate consent; its default mode is `aggregates-only`.
+- “Attach user prompt samples” is a second, independent, default-off consent. It cannot be granted unless aggregate consent is also granted.
+- Codex advice remains `local-only` and cannot create a remote snapshot.
+- The default aggregate path does not accept, transmit, or persist raw conversation records, raw session IDs, absolute or project paths, prompt/response bodies, tool arguments, credentials, or local usernames. Only the second explicit consent can place origin-filtered, bounded prompt samples into one in-memory snapshot; prompt text is never written to `globalState`.
+- Prompt Optimizer sends only the draft the user pasted, through the same complete-request preview and explicit-Send transport boundary.
+- Failure does not produce plausible-looking advice: invalid evidence, invalid local state, transport failure, or strict-output failure all fail closed.
+
+The legacy `claudeCodeUsage.getAdvice` command now only opens the unified Content surface. It does not build a legacy summary, call a model, or open a separate Markdown result. Prompt Optimizer shares the Prepared preview/send boundary, strict parsing policy, and reversible local feedback boundary; it is not a third sender.
+
+### Baseline and selective portability
+
+The candidate is designed for selective replay on the formal `v2.3.0` baseline. It
+reuses the released Claude incremental index, Codex provider index, refresh
+coordinator, and versioned migration state. It does not introduce a second log
+scanner, scheduler, authorization store, or comparison ledger. The candidate may be
+packaged locally for verification, but it does not change the package version,
+release workflow, tag, or publication state.
+
+## 2. Implementation map and ownership
+
+| Responsibility | Current integration point | Constraint |
+| --- | --- | --- |
+| Unified advice contract | `src/adviceEffectiveness/contract.ts` | The host owns observations, evidence, privacy, and provenance; advice must reference known evidence |
+| Claude / Codex adaptation | `src/adviceEffectiveness/adapters.ts` | Accepts narrow DTOs only; Codex never enters a remote payload |
+| Canonical payload | `src/adviceEffectiveness/payload.ts` | Serializes allowlisted fields only; omits `promptSamples` by default |
+| Evidence snapshot | `src/adviceEffectiveness/integration.ts` | Builds the consent-scoped inner evidence body; no transport |
+| Complete Prepared request | `src/adviceEffectiveness/preparedRequest.ts` | Serializes the full provider HTTP JSON body once; preview and send consume the same object and canonical bytes |
+| Production BYOK request | `src/adviceEffectiveness/remoteAdvice.ts`, `src/optimizerRequest.ts`, `src/advisor.ts` | Explicit Send only; configured API key/endpoint; one shared sender and retry policy |
+| Local state and migration | `src/adviceEffectiveness/versionedPersistence.ts` | VS Code `globalState`, exact schema, fail closed |
+| Before/after comparison | `src/adviceEffectiveness/comparison.ts` | Pure function, paired comparable tasks, quality guardrail, no causal claim |
+| Pair/result production | `src/adviceEffectiveness/comparisonPairing.ts`, `comparisonProduction.ts`, `comparisonResult.ts` | Sanitized materialized task aggregates, strict cohort identity, versioned bounded envelope |
+| Strict model output | `src/adviceEffectiveness/structuredOutput.ts` | JSON-only, exact shape, known references, no repair/fallback |
+| Framework-origin classification | `src/promptOrigin.ts`, `src/dataLoader.ts` | Structural markers are aggregated immediately; no semantic or writing-quality judgment |
+| Host / UI wiring | `src/extension.ts`, `src/webview.ts` | Feature gates, host-only prompts, opaque snapshots, explicit Send, strict result handling, reversible local feedback |
+| Excluded preparation seams | `legacyBridge.ts`, `evidencePreparation.ts`, `legacyPersonalization.ts`, `modelExperiment.ts`, `adviceSummary.ts`, demo modules | No production import and explicitly excluded from VSIX; never a default sender |
+
+## 3. Unified advice contract
+
+`AdviceContract` separates an advice artifact into six auditable parts:
+
+1. `observations`: finite numeric or boolean observations with a stable metric, unit, method, and source ID.
+2. `evidence`: references observations, declares direct/correlational/proxy strength, and states limitations for proxies.
+3. `recommendations`: references evidence and includes an explanation, conditional actions, stop conditions, and success criteria.
+4. `privacy`: records local-only / aggregates-only / aggregates-with-prompt-samples mode, prompt consent, and the local-feedback boundary.
+5. `provenance`: generation method, time, locale, sources, scope/window, confidence, and machine-readable quality flags.
+6. `schemaVersion` and stable opaque IDs: support strict parsing, migration, and comparison without carrying free-text identity data.
+
+The host always owns observations, evidence, privacy, and provenance. The production remote model may return only `recommendations`, and every observation/evidence reference must already exist; the model cannot manufacture measurements, rewrite provenance, or claim higher confidence. An empty recommendation array is valid and preferred to guessing.
+
+## 4. Adapters and provider boundaries
+
+### Claude
+
+`adaptClaudeAdvice` accepts two narrow data sets for exactly the same scope and rolling window:
+
+- a coarse usage aggregate containing token, message, estimated-cost, and coarse model-family totals;
+- a numeric session summary containing total, long, and large-context session counts.
+
+The adapter type does not accept raw records, paths, session IDs, titles, or prompts. `extension.ts` consumes the already materialized Claude dashboard snapshot and maps its same-window advice aggregate/session summary into the DTO. A scope/window mismatch, out-of-range count, or non-finite value rejects the entire result.
+
+Claude's structural evidence is eligible for a sealed remote preview, but only after separate explicit aggregate consent.
+
+### Incremental-index dependency
+
+Claude advice consumes the stable `claudeIncrementalIndex` materialized dashboard
+snapshot. It does not filter `cache.records`, call full-corpus reducers, or trigger a
+JSONL scan. Prompt samples and framework-overhead contributions come from the same
+existing indexed analysis state; missing or stale optional personalization evidence
+fails closed instead of starting automatic work.
+
+### Codex
+
+`adaptCodexLocalAdvice` maps only existing R8 structural numeric signals such as fresh shares, cache share, processed/fresh multiples, and post-patch tool intensity. It uses only an insight's allowlisted `kind`, `scope`, and `proxy` fields plus a separate numeric behavior DTO; open-ended evidence objects and strings such as `observedEffort` do not enter the unified contract.
+
+If index, identity, or period coverage is incomplete, or unresolved quality flags exist, source confidence becomes `unknown` and the adapter returns observations/evidence but no recommendations. `remoteEvidenceEligible` is always `false` and must stay that way until a provider-discriminated Codex aggregate contract receives a separate privacy review.
+
+## 5. Sealed canonical payload
+
+`prepareAdvicePayload` first builds the allowlisted inner evidence body. `prepareAiInvocation` then embeds that body in the complete configured Anthropic/OpenAI-compatible provider HTTP JSON body and serializes that provider body exactly once. It rejects non-finite numbers and unsupported values, then derives:
+
+- `serializedBody`: the exact canonical UTF-8 JSON string;
+- `canonicalBytes`: the bytes encoded once from that string;
+- `sha256`: the lowercase hexadecimal SHA-256 of those bytes;
+- `utf8Bytes`: `canonicalBytes.byteLength`, shown in preview;
+- `contentType`, `dataMode`, and prompt sample count.
+
+SHA-256 is a snapshot identity/integrity digest, not a signature and not proof that a server is trustworthy. Its purpose is to let people and tests verify that the reviewed preview and the transmitted bytes are the same sealed object.
+
+Required invariants are:
+
+- `preview.body === UTF8.decode(prepared.canonicalBytes) === prepared.serializedBody`;
+- `preview.utf8Bytes === prepared.canonicalBytes.byteLength`; JavaScript character count is not a substitute;
+- `preview.sha256 === SHA256(prepared.canonicalBytes) === prepared.sha256`;
+- preview and the sender both recompute and check body/bytes/digest before use; mutation of any field rejects the complete object;
+- the production sender receives the same host-retained `PreparedAiInvocation` / `canonicalBytes`; it never reserializes webview text or an ordinary object;
+- the host exposes only the body, byte count, digest, and non-sensitive metadata to the webview, while retaining the Prepared object in memory behind an opaque snapshot ID;
+- provider refresh, consent changes, panel close, or explicit discard invalidate old snapshots.
+
+The default advice snapshot is `aggregates-only`, and its inner evidence JSON omits the `promptSamples` key entirely. Only a second explicit prompt-personalization consent adds bounded samples/context; runtime cwd, session IDs, paths, or extra fields are discarded. Previewing performs no network call. A request crosses the network only when the user separately clicks Send, using the configured BYOK endpoint and key.
+
+## 6. Local feedback and versioned persistence
+
+The experimental UI's only write target is `ccu.adviceEffectiveness.localState` in VS Code `globalState`, currently schema version 3. The v3 envelope permits only:
+
+- feature mode and two consent enums;
+- opaque validated advice / recommendation / pair / rubric / metric IDs;
+- `helpful` / `not-helpful` / `unrated` and `applied` / `not-applied` enums;
+- bounded finite numbers, epoch timestamps, provider/context/quality enums, and allowlisted quality flags.
+
+It accepts no prompt, payload, explanation, endpoint, path, raw session ID, or arbitrary free text. Feedback is capped at 500 entries and comparable pairs at 200.
+
+`helpful` and `not-helpful` are mutually exclusive for one recommendation; `applied` is independent and may coexist with either rating. Clicking a selected value again withdraws it. Every Advice recommendation and each Prompt Optimizer result uses this same mutation boundary. All feedback stays local, never enters a payload, and emits no telemetry.
+
+Migration and degradation policy:
+
+- Missing state yields an all-closed v3 default.
+- Current v3 state loads unchanged. Supported legacy v2/v3 shapes migrate in place to the current bounded feedback, suppression, comparable-pair, and comparison-result shape.
+- A valid v1 envelope migrates only validated feedback; feature mode, aggregate consent, and prompt consent all close, and comparable pairs start empty.
+- An unknown future version, extra field, duplicate ID, invalid enum, non-finite number, or storage error returns the all-closed state and does not overwrite the unknown/corrupt source.
+- After a write failure, the host enters degraded mode and rejects further consent or feedback mutations.
+- A state with explicit prompt consent but no aggregate consent is treated as corrupt, fails closed as a whole, and is never overwritten.
+
+The foundation's separate `feedback.ts` / `claudeCodeUsage.adviceEffectiveness.feedback.v1` event ledger remains for compatibility tests, but it is not the integrated UI's write target and is not silently merged into the v2 envelope. Any future migration needs a separately reviewed one-time import; code must not dual-write in the meantime.
+
+## 7. Before/after comparison and “no conclusion without enough evidence”
+
+`compareAdviceEffectiveness` is a pure function with no I/O. Every before/after pair must match on task kind, complexity band, provider, model family, effort, metric definition, quality rubric, and primary metric name/unit/direction; the whole cohort must match as well. One bad pair makes the complete comparison `insufficient-evidence` instead of being silently dropped.
+
+The comparison entry point first selects a stable recommendation lineage by `provider + recommendationId`; it does not truncate history on the date-varying `adviceId`. Each pair still retains `adviceId` as an audit field for the individual advice instance. The same recommendation can therefore span observation days, while the downstream pure comparator still rejects a mixed task kind, complexity, model, effort, metric-definition, quality-rubric, or primary-metric cohort. It never drops incompatible pairs merely to reach the sample threshold.
+
+The default policy requires:
+
+- at least 5 comparable pairs;
+- complete before/after coverage;
+- confidence above low/unknown;
+- no unresolved, non-allowlisted quality flag;
+- a finite non-negative primary metric and a non-zero baseline;
+- a 0..1 quality score, explicit pass/fail, and at least one quality evidence item on both sides; the baseline must pass its rubric;
+- at least 10% mean relative primary-metric improvement;
+- every after task passing, a mean after quality of at least 0.8, and no more than 0.02 mean quality regression.
+
+The only results are `insufficient-evidence`, `quality-guardrail-failed`, `improved`, and `no-demonstrated-improvement`. Even `improved` is a controlled paired observation, not proof of causation. Production pairing consumes only sanitized, already materialized task-level structural observations and requires an applied timestamp plus an exact cohort match. It writes a bounded, versioned comparison-result envelope and never records prompt, response, path, raw session ID, or task body. Without a reliable before/after pair and quality evidence, the UI remains explicitly `insufficient-evidence`.
+
+## 8. Evidence interpretation boundaries
+
+### Long sessions, large context, and `/clear`
+
+- A “long session” is locally classified as active for at least 8 hours; “large context” means peak context of at least 150k.
+- Both shares use session counts from the same rolling window.
+- A conditional `/clear` recommendation appears only when both “at least 2 affected sessions” and “at least 25% share” hold.
+- Its condition is that the next task is genuinely unrelated; its stop condition preserves the current context if prior material is still needed.
+- These are structural proxies. They prove neither waste nor that `/clear` caused an improvement.
+
+### Topic drift
+
+There is no topic-drift observer, and the code does not infer semantic drift from session duration, context size, or body-free aggregates. Even after separate prompt-sample consent, current code only places visible samples in the sealed snapshot. Until the host adds a separately privacy-reviewed topic-drift observation/evidence ID, a remote model must not present topic drift as established evidence or generate a deterministic recommendation from it.
+
+### Framework origin and overhead proxy
+
+The loader uses structural fields and allowlisted wrapper/command/system markers to distinguish user-authored from framework-origin content, retaining only token/count aggregates after classification. A tool-result body enters the `observedInputEstimatedTokens` denominator once and does not ordinarily enter the numerator; a fixed tool-result envelope may enter the framework numerator. A Skill body used as a skill-preamble proxy is not counted again in the denominator.
+
+The adapter accepts only `frameworkEstimatedTokens`, `observedInputEstimatedTokens`, and `classifiedEvents`. All must be finite and non-negative, event count must be an integer, and framework tokens cannot exceed observed tokens. `framework-overhead-share = frameworkEstimatedTokens / observedInputEstimatedTokens`, its method is always `structural-proxy`, and it carries an overlay limitation.
+
+This share cannot assess the quality of the user's writing, identify topics, automatically generate rewrite advice, or be treated as removable cost. It may enter the Claude aggregates-only payload through the metric allowlist, but component text and hostile extra fields do not.
+
+### Model rightsizing
+
+Model rightsizing is only a typed, reversible experiment seam. It permits `opus → sonnet` or `sonnet → haiku`, and rejects two-tier changes, upgrades, and undeclared families. It does not claim that a smaller model is necessarily cheaper or better, and does not turn a short-output proxy into a model-switch directive.
+
+Comparison requires a local `applied` mark and a helpful/not-helpful rating, followed by at least 5 comparable pairs. Its target is 10% primary-metric improvement while retaining the 0.8 minimum quality and 0.02 maximum-regression guardrails. If quality regresses, the stop condition is to restore the baseline model.
+
+## 9. Unified AI compatibility matrix
+
+| Existing capability | Current production-candidate behavior | Boundary |
+| --- | --- | --- | --- |
+| `claudeCodeUsage.getAdvice` | Opens/reveals the unified Content surface; when disabled it offers the Settings entry | No model call, legacy summary, scope dialog, or Markdown output |
+| AI Advice remote personalization | Prepare full provider body → exact preview → explicit Send → strict JSON/reference parser → Advice contract | Aggregates-only by default; prompt/context requires separate consent; configured BYOK only |
+| Prompt Optimizer | Prepare user-draft-only provider body → exact preview → explicit Send → strict marker/settings parser → local result | Same sender/cancellation/feedback boundary; no persistent first-run authorization and no parser fallback |
+| Former `advisor.ts#callModel` / `getUsageAdvice` shortcuts | Removed from the candidate | The packaged module exports only the already-prepared sender; there is no prepare-and-send preview bypass |
+| `legacyBridge.ts`, `adviceSummary.ts`, demo/preparation modules | No production import; compiled artifacts explicitly forbidden from the VSIX | Readiness/reference code only, never a default or third sender |
+
+Aggregate and prompt-personalization consent remain separate. Prompt Optimizer does
+not borrow either consent: its authorization is the user's visible draft preview plus
+the separate Send click for that opaque Prepared snapshot. None of these local choices
+authorizes a later background request.
+
+## 10. Strict parsing and the production BYOK boundary
+
+`parseStructuredAdviceOutput` accepts exactly one bounded, exact-shape JSON object. It rejects Markdown fences, surrounding prose, unknown fields, unknown observation/evidence references, duplicate IDs, oversized arrays/text, missing conditional actions, missing success criteria or quality guardrails, and unsupported versions. It does not strip fences, repair JSON, return a partial batch, or call legacy Markdown/Optimizer fallbacks. An empty `recommendations` array is a valid fail-closed result.
+
+`parseStrictOptimizerOutput` independently requires the exact `===PROMPT===` and
+`===SETTINGS===` sections plus three bounded settings lines. It does not accept a
+marker-free response as a prompt. The two feature-specific parsers converge after
+the shared Prepared transport and both fail closed without displaying raw fallback
+text.
+
+The production request chain is:
+
+1. The host creates and retains one `PreparedAiInvocation` containing the complete provider HTTP JSON body.
+2. The user reviews the exact decoded body, UTF-8 byte count, content type/data mode, and SHA-256.
+3. A separate Send click passes the same object, source revision, and consent generation to `sendPreparedAiInvocation`.
+4. That boundary accepts only `backend: api` plus a non-empty user-configured key and sends to the endpoint frozen into the Prepared object.
+5. Fetch retry and curl fallback reuse the same canonical body bytes; no caller rebuilds the request from webview text.
+6. The shape-specific strict parser runs before any result or recommendation is rendered.
+
+Claude Code OAuth credentials remain scoped to the existing usage/quota API. OAuth
+and subscription credentials are not approved AI backends; production configuration
+and the Prepared sender both require BYOK `api`. Advice/Optimizer never expand OAuth
+scope, read another credential source, or repurpose a quota token as a model token.
+
+## 11. Release acceptance gates
+
+Before anyone changes a default or publishes the candidate, all of the following must hold.
+
+### Safety and privacy
+
+- Fresh-install, upgrade, and corrupt-state tests prove that the feature flag and both consents default closed.
+- Aggregates-only shape snapshots and hostile-sentinel tests prove there is no prompt/response/path/session/raw-record/tool-argument/credential leakage.
+- Prompt samples appear only after the second explicit consent, with tests for limits, extra-field removal, and invalidation of old snapshots after consent withdrawal.
+- Preview body, canonical bytes, UTF-8 count, SHA-256, and production-sender object-identity tests pass; the send path cannot reserialize.
+- Both AI surfaces retain the explicit Send action, BYOK-only configuration, redacted errors, feature-off host gate, cancellation, and no-telemetry guarantees.
+- Codex remote eligibility remains false under test.
+
+### Effectiveness and failure policy
+
+- Focused and affected-repository tests pass for the contract, adapters, pairing/result envelopes, migration, Prepared transport, both strict parsers, and reversible feedback.
+- A rotating cross-day `adviceId` does not reset one `provider + recommendationId` lineage; mixed task/model/effort/metric-version/rubric cohorts still fail closed as a whole.
+- Fewer than 5 pairs, incomparable context, insufficient coverage/confidence/quality, zero baseline, and unresolved flags all return `insufficient-evidence`.
+- Quality regression takes precedence over token/cost improvement, and UI copy never turns correlation into causation.
+- Malformed, fenced, oversized, or unknown-reference model output displays neither a partial recommendation nor a free-text fallback.
+- Topic drift remains unsupported without separate host evidence; framework overhead never triggers writing-quality advice.
+
+### UI, i18n, and release verification
+
+- All user-visible copy and placeholders exist in all eight locales with matching privacy meaning.
+- Keyboard reachability, visible focus, labels/roles/live status for consent, feedback, and preview, and screen-reader reading order are verified.
+- Visual snapshots count as evidence only after the webview harness provides real built-in-theme values for every production `--vscode-*` CSS variable.
+- Every consent, disclosure, feedback, and snapshot state has an operation → reload → persists/invalidates test.
+- Complete an F5 Extension Development Host smoke test, feasible Playwright/screenshot review, `npm run compile`, the full `npm test`, VSIX packaging, and the macOS/Linux installed-VSIX smoke required for a release candidate.
+- Verify the current CHANGELOG/README candidate wording against the packaged behavior, without changing the version or release workflow.
+
+The operation → full reload → persistence/invalidation tests must continue to cover
+consent, per-recommendation and Optimizer feedback, source/config changes, feature
+disablement, surface close, and local-data clear. A stale opaque snapshot must never
+be retrievable after any invalidating event.
+
+## 12. Current limitations and next step
+
+- A sealed preview is still local; only the separate Send click creates the production BYOK network request.
+- Real comparison production currently depends on sanitized materialized task-level structural and quality evidence. Missing or incomparable observations remain `insufficient-evidence`.
+- The remote advice parser accepts model-authored recommendation IDs after strict shape/reference validation; host policy must continue preventing unsupported evidence from being presented as `/clear` or another deterministic action.
+- Advice renders and closes feedback/comparison state for every recommendation, not only the first. Optimizer shares feedback but does not currently enter comparable-task comparison.
+- Topic drift and writing quality have no local semantic evidence.
+- Codex has no remote payload schema and remains local-only.
+- Framework origin is a structural proxy; log schema drift may reduce coverage and must not be filled with guesses.
+- `advice.userContext` and prompt samples enter a request only under separate prompt-personalization consent and exact preview; aggregates-only payloads contain neither.
+- The separate feedback v1 ledger is not automatically imported into the v2 envelope.
+
+The production rule is stable: resolve only a host-retained Prepared object from its
+opaque snapshot ID, send only through `sendPreparedAiInvocation`, and render only a
+strictly parsed result. Never wire through webview body text, `getAdvice`,
+`buildAdviceSummary`, the removed `getUsageAdvice` / `callModel` shortcuts, or
+`legacyBridge`.
+
+## 13. Release-line statement
+
+This candidate remains isolated from release actions. It has not pushed, merged, tagged, or published anything and changes no version number, release workflow, or release entry point. Candidate code may enter a local VSIX for verification; default enablement, publishing, or any version action still requires separate maintainer approval.
+
+---
+🤖 Generated with [OpenAI Codex](https://developers.openai.com/codex/)
diff --git a/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md
new file mode 100644
index 00000000..40e316fb
--- /dev/null
+++ b/docs/releases/v2.3.1/AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md
@@ -0,0 +1,263 @@
+# v2.3.1 AI 建议有效性：集成交接说明
+
+配套文档：[中文交接说明](AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md) · [English handoff](AI-ADVICE-INTEGRATION-V2.3.1.md)
+
+相关设计：[中文设计说明](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md) · [English design](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md)
+
+## 1. 状态与安全结论
+
+本分支提供的是 **默认关闭的 v2.3.1 本地候选**，不是已发布功能。它在现有 Claude / Codex 共用 dashboard 中实现“观察 → 证据 → 建议 → 行动 → 结果”证据链，并把可选远程步骤接入现有用户配置的 BYOK endpoint。它不会自动调用模型，也不发送遥测。
+
+当前安全边界如下：
+
+- `advice.effectiveness.enabled` 与 `advice.optimizer.enabled` 都默认 `false`。host message seam 还会再次检查设置，因此关闭或隐藏的 UI 不能创建 AI network resource。
+- 远程 AI 在本候选中已生产可达，但只有用户先检查完整请求预览、再另行明确点击“发送”后才会调用；预览绝不发送。
+- Claude 只有经过独立明确同意后才能生成远程预览；默认是 `aggregates-only`。
+- “附加用户 prompt 样本”是第二个、独立且默认关闭的同意项；它不能在聚合同意未开启时单独开启。
+- Codex 建议保持 `local-only`，不能生成远程快照。
+- 默认聚合路径不读取、传递或持久化原始会话记录、原始 session ID、绝对路径、项目路径、prompt/response 正文、tool argument、凭据或本地用户名。只有第二项明确同意可把经过来源过滤和长度限制的 prompt 样本加入一次内存快照；它不写入 `globalState`。
+- Prompt Optimizer 只发送用户粘贴的 draft，并使用相同的完整请求预览与显式发送边界。
+- 失败时不生成“看起来合理”的建议：无效证据、无效本地状态、传输失败或严格输出失败均保守关闭。
+
+旧 `claudeCodeUsage.getAdvice` 命令现在只打开统一 Content 界面，不再构建旧 summary、调用模型或打开独立 Markdown 结果。Prompt Optimizer 共用 Prepared 预览/发送边界、严格解析策略和可撤销本地反馈边界，不是第三条 sender。
+
+### 基线与选择性移植
+
+本候选面向正式 `v2.3.0` 基线选择性重放，复用已发布的 Claude incremental index、Codex
+provider index、刷新协调器与版本化迁移状态。它不建立第二套日志扫描器、scheduler、授权存储或
+comparison ledger。候选可以打包本地 VSIX 供验证，但不改变 package version、release workflow、
+tag 或发布状态。
+
+## 2. 实现地图与所有权
+
+| 责任 | 当前接入点 | 约束 |
+| --- | --- | --- |
+| 统一建议契约 | `src/adviceEffectiveness/contract.ts` | host 拥有观察、证据、隐私和来源；建议必须引用已知证据 |
+| Claude / Codex 适配 | `src/adviceEffectiveness/adapters.ts` | 只接受窄化 DTO；Codex 永不进入远程 payload |
+| canonical payload | `src/adviceEffectiveness/payload.ts` | 只序列化 allowlist 字段；默认不含 `promptSamples` |
+| evidence 快照 | `src/adviceEffectiveness/integration.ts` | 构建 consent-scoped 内层 evidence body；无 transport |
+| 完整 Prepared 请求 | `src/adviceEffectiveness/preparedRequest.ts` | 完整 provider HTTP JSON body 只序列化一次；预览与发送消费同一对象和 canonical bytes |
+| 生产 BYOK 请求 | `src/adviceEffectiveness/remoteAdvice.ts`、`src/optimizerRequest.ts`、`src/advisor.ts` | 只有显式 Send；配置的 API key/endpoint；一个共用 sender 与 retry policy |
+| 本地状态与迁移 | `src/adviceEffectiveness/versionedPersistence.ts` | VS Code `globalState`、严格 schema、失败关闭 |
+| 前后比较 | `src/adviceEffectiveness/comparison.ts` | 纯函数、成对同类任务、质量护栏、无因果声称 |
+| pair/result 生产 | `src/adviceEffectiveness/comparisonPairing.ts`、`comparisonProduction.ts`、`comparisonResult.ts` | 已净化的物化任务 aggregate、严格 cohort identity、版本化有界 envelope |
+| 严格模型输出 | `src/adviceEffectiveness/structuredOutput.ts` | JSON-only、exact shape、已知引用、无修复/fallback |
+| framework 来源分类 | `src/promptOrigin.ts`、`src/dataLoader.ts` | 只看结构标记并立即聚合，不做语义/写作质量判断 |
+| host / UI 接线 | `src/extension.ts`、`src/webview.ts` | feature gate、host-only prompt、opaque snapshot、显式 Send、严格结果处理、可撤销本地反馈 |
+| 已排除准备 seam | `legacyBridge.ts`、`evidencePreparation.ts`、`legacyPersonalization.ts`、`modelExperiment.ts`、`adviceSummary.ts`、demo 模块 | 无生产 import 且明确排除出 VSIX；绝不是默认 sender |
+
+## 3. 统一建议契约
+
+`AdviceContract` 把建议拆成六类可审计数据：
+
+1. `observations`：有限数值或布尔观察，带稳定 metric、单位、方法和 source ID。
+2. `evidence`：引用观察，明确是 direct、correlational 或 proxy，并为 proxy 声明限制。
+3. `recommendations`：引用证据，包含解释、条件动作、停止条件和成功判据。
+4. `privacy`：记录 local-only / aggregates-only / aggregates-with-prompt-samples、prompt 同意和本地反馈边界。
+5. `provenance`：生成方式、时间、locale、来源、scope/window、confidence 和机器化 quality flags。
+6. `schemaVersion` 与稳定 opaque IDs：便于严格解析、迁移和比较，不承载自由文本身份信息。
+
+host 始终拥有观察、证据、隐私和来源。生产远程模型最多只能返回 `recommendations`，且所有 observation/evidence 引用必须已存在；模型不能制造测量结果、改写来源或自称有更高置信度。空建议数组是合法且优先于推测的结果。
+
+## 4. 适配器及 provider 边界
+
+### Claude
+
+`adaptClaudeAdvice` 接收同一 scope、同一 rolling window 的两类窄化数据：
+
+- coarse usage aggregate：token、message、估算成本与粗粒度 model family；
+- 数值 session summary：总 session 数、长 session 数、大 context session 数。
+
+适配器类型不接受 raw record、路径、session ID、标题或 prompt。`extension.ts` 消费已物化的 Claude dashboard snapshot，并把同窗口 advice aggregate / session summary 映射为 DTO。scope/window 不一致、计数越界或非有限数会整批拒绝。
+
+Claude 的结构化证据可用于密封远程预览，但仍需聚合数据的独立明确同意。
+
+### 增量索引依赖
+
+Claude advice 消费稳定 `claudeIncrementalIndex` 已物化的 dashboard snapshot；不会过滤
+`cache.records`、调用 full-corpus reducer 或触发 JSONL 扫描。prompt sample 与 framework-overhead
+contribution 来自同一现有 indexed analysis state；可选个性化证据缺失或过期时失败关闭，不启动自动工作。
+
+### Codex
+
+`adaptCodexLocalAdvice` 只映射 R8 已有的结构数值信号，例如 fresh share、cache share、processed/fresh multiple 与 post-patch tool intensity。它只使用 insight 的 allowlisted `kind`、`scope`、`proxy` 和单独的数值 behavior DTO；开放式 evidence 对象以及 `observedEffort` 等字符串不会进入统一契约。
+
+当 index、identity 或 period coverage 不完整，或存在未解决 quality flag 时，来源 confidence 降为 `unknown`，并返回观察/证据但不返回建议。`remoteEvidenceEligible` 固定为 `false`；在出现经过单独隐私评审的 provider-discriminated Codex aggregate 契约前，不得改变。
+
+## 5. 密封 canonical payload
+
+`prepareAdvicePayload` 先构建 allowlisted 内层 evidence body；`prepareAiInvocation` 再把它嵌入完整配置的 Anthropic / OpenAI-compatible provider HTTP JSON body，并且只序列化该 provider body 一次。它拒绝非有限数和不支持的值，随后产生：
+
+- `serializedBody`：canonical UTF-8 JSON 的精确字符串；
+- `canonicalBytes`：由该字符串一次性编码得到的字节；
+- `sha256`：这些字节的 lowercase hexadecimal SHA-256；
+- `utf8Bytes`：预览中展示的 `canonicalBytes.byteLength`；
+- `contentType`、`dataMode` 和 prompt sample count。
+
+SHA-256 是快照身份/一致性摘要，不是签名，也不代表服务端可信。它的作用是让人和测试确认“预览的内容”与“实际发送的字节”是同一个密封对象。
+
+关键不变量：
+
+- `preview.body === UTF8.decode(prepared.canonicalBytes) === prepared.serializedBody`；
+- `preview.utf8Bytes === prepared.canonicalBytes.byteLength`，不能用 JavaScript 字符数代替；
+- `preview.sha256 === SHA256(prepared.canonicalBytes) === prepared.sha256`；
+- preview 与 sender 在使用前都会重算并核对 body/bytes/digest；任一字段被修改都会整份拒绝；
+- 生产 sender 必须接收同一个 host-retained `PreparedAiInvocation` / `canonicalBytes`，不能从 webview 文本或普通对象重新序列化；
+- host 只把 body、byte count、digest 和非敏感元数据交给 webview，Prepared 对象保留在内存中并由 opaque snapshot ID 引用；
+- provider 数据刷新、同意变更、面板关闭或显式丢弃会清除旧快照。
+
+默认 Advice 快照是 `aggregates-only`，其内层 evidence JSON 连 `promptSamples` key 都不存在。只有第二项 prompt-personalization consent 明确为 `explicit` 时才加入有界 sample/context；runtime 附带的 cwd、session ID、path 或额外字段会被丢弃。预览不联网；只有用户另行点击“发送”后，才使用配置的 BYOK endpoint 与 key 发出请求。
+
+## 6. 本地反馈与版本化持久化
+
+实验 UI 的唯一写入目标是 VS Code `globalState` 中的 `ccu.adviceEffectiveness.localState`，当前 schema version 为 3。v3 envelope 只允许：
+
+- feature mode 与两个 consent enum；
+- opaque、格式已验证的 advice / recommendation / pair / rubric / metric IDs；
+- `helpful` / `not-helpful` / `unrated` 与 `applied` / `not-applied` 枚举；
+- 有界、有限的数值、epoch 时间、provider/context/quality 枚举与 allowlisted quality flags。
+
+它不接受 prompt、payload、解释、endpoint、path、raw session ID 或任意自由文本。反馈最多 500 项，可比任务对最多 200 项。
+
+`helpful` 与 `not-helpful` 对同一建议互斥；`applied` 与评分独立，可同时存在。再次点击已选值会撤回。每条 Advice recommendation 与每次 Prompt Optimizer 结果都使用这一写入边界。所有反馈只写本地，不联网、不进入 payload、不记遥测。
+
+迁移/降级策略：
+
+- 缺少状态时返回全关闭的 v3 默认值。
+- 当前 v3 原样读取；受支持的旧 v2/v3 形状原地迁移到包含有界反馈、暂停、可比任务对与比较结果的当前形状。
+- 合法 v1 envelope 只迁移已验证反馈；feature、aggregate consent、prompt consent 全部重置为关闭，可比任务对从空数组开始。
+- 未知未来版本、额外字段、重复 ID、非法 enum、非有限数或存储错误都返回全关闭状态，并且不覆盖原始未知/损坏数据。
+- 写入失败后 host 进入 degraded 状态，拒绝继续修改 consent 或反馈。
+- 状态若出现 `promptSampleConsent=explicit` 但 aggregate consent 未授予，会作为损坏状态整体失败关闭，且不会覆盖原值。
+
+基础提交中的独立 `feedback.ts` / `claudeCodeUsage.adviceEffectiveness.feedback.v1` event ledger 仍保留供兼容测试，但不是集成 UI 的写入点，也不会被静默合并进 v2 envelope。未来若决定迁移，必须单独设计可审计的一次性导入；在此之前不得双写。
+
+## 7. 前后比较与“不足证据时不下结论”
+
+`compareAdviceEffectiveness` 是无 I/O 的纯函数。每个 before/after pair 必须在 task kind、complexity band、provider、model family、effort、metric definition、quality rubric、metric name/unit/direction 上一致；整个 cohort 也必须一致。任何坏 pair 都会使整次比较返回 `insufficient-evidence`，而不是悄悄丢弃。
+
+比较入口先按稳定的 recommendation lineage（`provider + recommendationId`）选取 pair，而不按会随观察日期变化的 `adviceId` 截断。`adviceId` 仍保留在每个 pair 中，作为一次建议实例的审计字段。因此不同日期的同一建议可以形成闭环，但后续纯比较器仍会严格拒绝 task kind、complexity、model、effort、metric definition、quality rubric 或 primary metric 不一致的混合 cohort；它不会为了凑样本而静默过滤。
+
+默认门槛为：
+
+- 至少 5 个可比 pair；
+- before/after coverage 完整；
+- confidence 不得为 low/unknown；
+- 不得有未 allowlist 的 quality flag；
+- primary metric 必须有限、非负，baseline 不能为 0；
+- 两侧都要有 0..1 quality score、明确 pass/fail 和至少一条质量证据；baseline 必须通过 rubric；
+- 平均 primary metric 相对改善至少 10%；
+- 每个 after task 必须通过，after 平均质量至少 0.8，平均质量下降不得超过 0.02。
+
+结果只可能是 `insufficient-evidence`、`quality-guardrail-failed`、`improved` 或 `no-demonstrated-improvement`。即使结果为 `improved`，它也只是受控的配对观察，不是因果证明。生产配对只消费已经净化、已物化的任务级结构 observation，并要求本地 `applied` 时间点以及完全一致的 scope、task kind、complexity、provider、model、effort、metric 与 rubric cohort。只有可靠的 before/after pair 才会写入有界、版本化的 comparison result envelope；它不记录 prompt、response、路径、原始 session ID 或任务正文。缺少可靠 pair 或质量证据时，界面明确显示“证据不足”。
+
+## 8. 证据解释边界
+
+### 长 session、大 context 与 `/clear`
+
+- “长 session”是本地已分类的活动跨度至少 8 小时；“大 context”是 peak context 至少 150k。
+- 两者都按同一 rolling window 的 session 数计算 share。
+- 只有“受影响 session 至少 2 个”且“share 至少 25%”同时满足时，才生成条件 `/clear` 建议。
+- 条件是下一项任务确实无关；如果仍需前文，停止条件要求保留当前 context。
+- 这些指标是 structural proxy，不证明浪费，也不证明 `/clear` 导致改善。
+
+### Topic drift
+
+当前没有 topic-drift 观察器，也不从 session 时长、context 大小或 body-free aggregates 推断语义漂移。即使用户单独同意附加 prompt 样本，当前代码也只是把可见样本放入密封快照；在 host 没有新增、经过隐私评审的 topic-drift observation/evidence ID 前，远程模型不得把“topic drift”作为已证实证据或生成相应确定性建议。
+
+### Framework origin 与 overhead proxy
+
+loader 使用结构字段和 allowlisted wrapper/command/system marker 区分 user-authored 与 framework-origin 内容；分类后只保留 token/count aggregates。tool result 正文只进入 `observedInputEstimatedTokens` denominator 一次，普通正文不进入 numerator；固定 tool-result envelope 可计入 framework numerator。Skill body 作为 skill-preamble proxy 时不在 denominator 中重复计算。
+
+适配器只接收 `frameworkEstimatedTokens`、`observedInputEstimatedTokens`、`classifiedEvents`，要求全部为非负有限数、event count 为整数且 framework 不超过 observed。`framework-overhead-share = frameworkEstimatedTokens / observedInputEstimatedTokens`，method 固定为 `structural-proxy`，并声明 overlay limitation。
+
+该 share 不能评价用户写作质量、不能识别话题、不能自动生成改写建议，也不能等同于可消除成本。它可以进入 Claude aggregate-only payload 的 metric allowlist，但不携带 component text 或 hostile extra fields。
+
+### Model rightsizing
+
+model rightsizing 只是一条 typed、可逆实验 seam：允许 `opus → sonnet` 或 `sonnet → haiku`，拒绝跨两档、向上切换和未声明 family。它不声称“较小模型一定更便宜/更好”，也不根据短 output 直接要求换模型。
+
+比较前必须本地标记 `applied` 并给出 helpful/not-helpful 评分；随后至少收集 5 对同类任务，目标 primary metric 改善 10%，同时保留 0.8 最低质量和 0.02 最大回退护栏。一旦质量回退，停止条件是恢复 baseline model。
+
+## 9. 统一 AI 兼容矩阵
+
+| 现有能力 | 当前生产候选行为 | 边界 |
+| --- | --- | --- |
+| `claudeCodeUsage.getAdvice` | 打开或显示统一的 Content 界面；功能关闭时提供 Settings 入口 | 不调用模型，不生成旧 summary，不弹 scope 对话框，也不输出 Markdown |
+| AI Advice 远程个性化 | 准备完整 provider body → 逐字节预览 → 显式点击 Send → 严格 JSON／引用解析 → Advice contract | 默认仅 aggregate；prompt/context 需要独立同意；只使用用户配置的 BYOK |
+| Prompt Optimizer | 准备只含用户 draft 的完整 provider body → 逐字节预览 → 显式点击 Send → 严格 marker/settings 解析 → 本地结果 | 共用 sender、取消和反馈边界；没有持久化的首次运行授权，也没有 parser fallback |
+| 原 `advisor.ts#callModel` / `getUsageAdvice` 快捷路径 | 已从候选中删除 | 打包模块只导出接收既有 Prepared 对象的 sender，不再存在 prepare-and-send 的预览绕过路径 |
+| `legacyBridge.ts`、`adviceSummary.ts`、demo／准备模块 | 没有生产 import，其编译产物被明确禁止进入 VSIX | 仅供准备或参考，绝不是默认 sender 或第三条 sender |
+
+aggregate consent 与 prompt-personalization consent 始终独立。Prompt Optimizer 不借用其中任何一种 consent：它的授权来自用户可见的 draft 精确预览，以及针对该 opaque Prepared snapshot 的另一次 Send 点击。这些本地选择都不授权未来的后台请求。
+
+## 10. 严格解析与生产 BYOK 边界
+
+`parseStructuredAdviceOutput` 只接受一个 bounded、exact-shape JSON object。它拒绝 Markdown fence、前后 prose、未知字段、未知 observation/evidence reference、重复 ID、过大数组/字符串、无条件动作、无成功判据、无 quality guardrail 以及不合版本的输出。它不剥 fence、不修 JSON、不返回部分 batch，也不调用旧 Markdown/Optimizer fallback；空 `recommendations` 是合法的 fail-closed 结果。
+
+`parseStrictOptimizerOutput` 独立要求精确的 `===PROMPT===` 与 `===SETTINGS===` 段，以及三行有界 settings。缺少 marker 的回复不能被当作 prompt。两种特性各自使用严格 parser，但在共用的 Prepared transport 之后收敛；两者失败时都关闭，不显示原始 fallback 文本。
+
+生产请求链为：
+
+1. host 创建并保留一个 `PreparedAiInvocation`，其中包含完整的 provider HTTP JSON body；
+2. 用户审查该 body 的精确解码内容、UTF-8 byte count、content type／data mode 与 SHA-256；
+3. 用户另行点击 Send，把同一个对象、source revision 与 consent generation 交给 `sendPreparedAiInvocation`；
+4. 该边界只接受 `backend: api` 和非空的用户配置 key，并发送到冻结在 Prepared 对象中的 endpoint；
+5. fetch retry 与 curl fallback 复用同一份 canonical body bytes；任何 caller 都不能从 webview 文本重建请求；
+6. 在呈现任何结果或建议之前，必须先运行对应输出形状的严格 parser。
+
+Claude Code OAuth 凭据仍只用于既有 usage/quota API。OAuth 与 subscription 凭据都不是获准的 AI backend；生产配置与 Prepared sender 都要求 BYOK `api`。Advice／Optimizer 不扩大 OAuth scope、不读取其他凭据来源，也不把 quota token 转作模型 token。
+
+## 11. 上线验收门槛
+
+在任何人改变默认值或发布候选前，至少必须同时满足：
+
+### 安全与隐私
+
+- feature flag 和两个 consent 的 fresh-install、upgrade、corrupt-state 测试均证明默认关闭。
+- aggregates-only payload 的结构快照和敌意 sentinel 测试证明没有 prompt/response/path/session/raw record/tool argument/credential 泄漏。
+- prompt 样本只在第二项显式同意后出现，并证明长度上限、字段丢弃和 consent 撤回后旧 snapshot 失效。
+- preview body、canonical bytes、UTF-8 count、SHA-256 与生产 sender 的对象身份测试全部通过；发送路径不能重新序列化。
+- 两个 AI 界面都保留显式 Send、BYOK-only 配置、错误脱敏、feature-off host gate、取消能力与“无遥测”保证。
+- Codex 的远程资格测试持续为 false。
+
+### 有效性与失败策略
+
+- contract、Claude/Codex adapters、pairing/result envelope、migration、Prepared transport、两种 strict parser 与可撤销反馈的聚焦及受影响全仓测试通过。
+- 跨日变化的 `adviceId` 不会重置同一 `provider + recommendationId` lineage；不同任务/模型/effort/指标版本/rubric 的混合 cohort 仍会整体失败关闭。
+- 不足 5 对、context 不可比、coverage/confidence/quality 不足、零 baseline、未解决 flags 均返回 `insufficient-evidence`。
+- quality regression 优先于 token/cost 改善，且 UI 不把相关性写成因果。
+- malformed/fenced/oversized/unknown-reference model output 不显示部分建议或自由文本 fallback。
+- topic drift 在没有独立 host evidence 前保持不支持；framework overhead 不触发写作质量建议。
+
+### UI、i18n 与发布验证
+
+- 八个 locale 的全部用户可见文案、placeholder 和隐私语义一致。
+- 键盘可达、focus 可见、checkbox/feedback/preview 有正确 label、role、live status 和屏幕阅读器顺序。
+- webview 测试环境为所有 production `--vscode-*` CSS variables 提供真实主题值后，才接受视觉 snapshot。
+- 每个 consent、展开/收起、feedback 与 snapshot 状态都有“操作 → reload → 应保留/应失效”的测试。
+- 完成 F5 Extension Development Host smoke、可行的 Playwright/截图检查、`npm run compile`、全量 `npm test`、VSIX 打包，以及发布候选所需的 macOS/Linux installed-VSIX smoke。
+- 核对当前 CHANGELOG／README 候选文案与打包行为一致，但不修改版本或 release workflow。
+
+“操作 → full reload → 状态保留／失效”测试必须持续覆盖 consent、逐条 recommendation 与 Optimizer 反馈、source/config 变化、功能关闭、界面关闭和本地数据清除。任何失效事件发生后，过期的 opaque snapshot 都不得再被取回。
+
+## 12. 当前已知限制与下一步
+
+- 密封预览仍是本地状态；只有另行点击 Send 才会创建生产 BYOK 网络请求。
+- 真实 comparison production 依赖已净化、已物化的任务级结构与质量证据；观察缺失或不可比时保持 `insufficient-evidence`。
+- 远程 Advice parser 在严格校验形状与引用后接受模型生成的 recommendation ID；host policy 必须继续防止把不支持的 evidence 呈现为 `/clear` 或其他确定性动作。
+- Advice 会渲染每条 recommendation，并分别闭环其反馈与比较状态，而不是只处理第一条。Optimizer 共用反馈，但当前不进入可比任务 comparison。
+- topic drift 和写作质量没有本地语义证据。
+- Codex 没有远程 payload schema，保持 local-only。
+- framework origin 是结构 proxy，日志 schema 漂移可能降低覆盖；不得用猜测补齐。
+- `advice.userContext` 与 prompt 样本只有在独立 prompt-personalization consent 和精确预览下才会进入请求；aggregates-only payload 两者都不包含。
+- 独立 feedback v1 ledger 没有自动导入 v2 envelope。
+
+生产规则已经稳定：只通过 opaque snapshot ID 取回 host 保留的 Prepared 对象，只通过 `sendPreparedAiInvocation` 发送，并且只呈现严格解析后的结果。绝不能从 webview body 文本、`getAdvice`、`buildAdviceSummary`、已删除的 `getUsageAdvice` / `callModel` 快捷路径或 `legacyBridge` 绕接。
+
+## 13. 发布线声明
+
+本候选与发布动作保持隔离。它没有推送、合并、打 tag 或发布，也没有修改任何版本号、release workflow 或发布入口。候选代码可以进入本地 VSIX 供验证；默认启用、发布或任何版本动作仍需要维护者另行批准。
+
+---
+🤖 Generated with [OpenAI Codex](https://developers.openai.com/codex/)
diff --git a/docs/releases/v2.3.1/CLAUDE-COLD-AB-V2.3.1.md b/docs/releases/v2.3.1/CLAUDE-COLD-AB-V2.3.1.md
new file mode 100644
index 00000000..c37ecc31
--- /dev/null
+++ b/docs/releases/v2.3.1/CLAUDE-COLD-AB-V2.3.1.md
@@ -0,0 +1,15 @@
+# Claude cold-build A/B — v2.3.1 candidate
+
+This is a fixed-corpus measurement, not a release benchmark. Both runs used the same deterministic one-file Claude JSONL fixture (50,000 assistant records spanning 365 calendar days) and `America/New_York`.
+
+| run | body reads | bytes | parsed lines | elapsed | hourly buckets |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| baseline, per-record zone/hour helpers | 1 | 17,227,780 | 50,000 | 15,885.58 ms | 8,759 |
+| candidate, one formatter + recent-hour window | 1 | 17,227,780 | 50,000 | 6,791.68 ms | 764 |
+| candidate warm unchanged | 0 | 0 | 0 | 13.47 ms | unchanged |
+
+The comparison supports the narrow optimization: formatter construction and unbounded hour materialization were a material part of cold-build time. Day, month, all-time and record semantics remain unchanged; only the transient hourly sidecar is limited to the configured recent 30 civil days. Historical date expansion still uses the in-memory visible records and never reopens JSONL.
+
+Resource ownership remains single-producer: the existing Claude incremental index owns parsing and aggregates; the existing refresh coordinator owns its watcher/timer lifecycle. Codex migration keeps its existing worker/index producer, with a 10-second blur deadline for the one bounded first-history exception. The deadline cancels cooperatively, checkpoints the safe cursor, and leaves the persisted background state eligible for resume. Warm unchanged refreshes read zero JSONL bodies, and disabling or disposing the extension releases timers, watchers, workers, network leases, and backfill leases with no long-lived resource left behind.
+
+This fixture does not claim a 2.4-GB wall-clock or energy benchmark; that remains a release-candidate dependency.
diff --git a/docs/releases/v2.3.1/CLAUDE-COLD-AB-V2.3.1.zh-CN.md b/docs/releases/v2.3.1/CLAUDE-COLD-AB-V2.3.1.zh-CN.md
new file mode 100644
index 00000000..6957e67c
--- /dev/null
+++ b/docs/releases/v2.3.1/CLAUDE-COLD-AB-V2.3.1.zh-CN.md
@@ -0,0 +1,15 @@
+# Claude 冷启动 A/B 对照——v2.3.1 候选
+
+这是固定语料测量，不是发布基准。两次运行使用同一份确定性单文件 Claude JSONL fixture（50,000 条 assistant 记录，覆盖 365 个日历日）和 `America/New_York`。
+
+| 运行 | body reads | 字节数 | 解析行数 | 耗时 | 小时桶 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 基线：逐记录时区/小时 helper | 1 | 17,227,780 | 50,000 | 15,885.58 ms | 8,759 |
+| 候选：单 formatter + 近期小时窗口 | 1 | 17,227,780 | 50,000 | 6,791.68 ms | 764 |
+| 候选 warm unchanged | 0 | 0 | 0 | 13.47 ms | 不变 |
+
+对照支持这一项窄优化：formatter 创建和无界小时物化确实占用了冷启动时间。日、月、全历史和记录语义保持不变；只把临时小时 sidecar 限制为配置时区最近 30 个民用日。历史日期展开仍从内存中的可见记录得到，绝不重新打开 JSONL。
+
+资源所有权仍是单一生产者：现有 Claude 增量索引拥有解析和聚合，现有刷新协调器拥有 watcher/timer 生命周期。Codex 迁移继续使用现有 worker/index 生产者，并为唯一有界的首次历史整理例外增加 10 秒失焦截止。截止到达后协作式取消、保存安全游标，持久 background state 保持 eligible 以便续跑。warm unchanged 刷新读取零 JSONL；关闭或停用功能时释放 timer、watcher、worker、network lease 和 backfill lease，不留下长期资源。
+
+该 fixture 不代表 2.4-GB 墙钟时间或能耗基准；这仍是发布候选的依赖项。
diff --git a/docs/releases/v2.3.1/README.md b/docs/releases/v2.3.1/README.md
new file mode 100644
index 00000000..03a491e9
--- /dev/null
+++ b/docs/releases/v2.3.1/README.md
@@ -0,0 +1,20 @@
+# v2.3.1 release-cycle archive
+
+[中文索引](README.zh-CN.md) · [English index](README.md)
+
+This directory preserves design, audit, benchmark, and release-candidate material created while v2.3.1 was being prepared. It is historical evidence, not current product documentation or a statement of the release's present status.
+
+For current information, use the repository [README](../../../README.md), [changelog](../../../CHANGELOG.md), [local-data policy](../../../LOCAL-DATA.md), and the published GitHub release notes.
+
+## Archived material
+
+- AI Advice effectiveness implementation note: [candidate note](AI-ADVICE-EFFECTIVENESS-V2.3.1.md)
+- AI Advice integration handoff: [中文](AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md) · [English](AI-ADVICE-INTEGRATION-V2.3.1.md)
+- AI Advice UI design: [中文](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md) · [English](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md)
+- Claude cold-build A/B note: [中文](CLAUDE-COLD-AB-V2.3.1.zh-CN.md) · [English](CLAUDE-COLD-AB-V2.3.1.md)
+- Local candidate contract: [中文](V2.3.1-CANDIDATE-CONTRACT.zh-CN.md) · [English](V2.3.1-CANDIDATE-CONTRACT.md)
+
+Some files intentionally retain candidate SHAs, test counts, package hashes, and pre-release wording from the point when they were written. Do not treat those snapshots as the current release source of truth.
+
+---
+🤖 Generated with [OpenAI Codex](https://developers.openai.com/codex/)
diff --git a/docs/releases/v2.3.1/README.zh-CN.md b/docs/releases/v2.3.1/README.zh-CN.md
new file mode 100644
index 00000000..f09c24db
--- /dev/null
+++ b/docs/releases/v2.3.1/README.zh-CN.md
@@ -0,0 +1,20 @@
+# v2.3.1 发布周期档案
+
+[中文索引](README.zh-CN.md) · [English index](README.md)
+
+本目录保存 v2.3.1 准备期间形成的设计、审计、基准和候选发布材料。它们属于历史证据，不是当前产品文档，也不代表该版本现在的发布状态。
+
+如需了解当前信息，请以仓库[简体中文 README](../../../README-zh-CN.md)、[更新日志](../../../CHANGELOG.md)、[本地数据与隐私说明](../../../LOCAL-DATA.zh-CN.md)及 GitHub 正式 Release 说明为准。
+
+## 归档材料
+
+- AI Advice 有效性实现说明：[候选说明](AI-ADVICE-EFFECTIVENESS-V2.3.1.md)
+- AI Advice 集成交接：[中文](AI-ADVICE-INTEGRATION-V2.3.1.zh-CN.md) · [English](AI-ADVICE-INTEGRATION-V2.3.1.md)
+- AI Advice 界面设计：[中文](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.zh-CN.md) · [English](AI-ADVICE-INTEGRATION-DESIGN-V2.3.1.md)
+- Claude 冷启动 A/B 记录：[中文](CLAUDE-COLD-AB-V2.3.1.zh-CN.md) · [English](CLAUDE-COLD-AB-V2.3.1.md)
+- 本地候选契约：[中文](V2.3.1-CANDIDATE-CONTRACT.zh-CN.md) · [English](V2.3.1-CANDIDATE-CONTRACT.md)
+
+部分文件会原样保留当时的候选 SHA、测试数量、安装包哈希和发布前措辞。这些快照不应被视为当前版本事实的权威来源。
+
+---
+🤖 Generated with [OpenAI Codex](https://developers.openai.com/codex/)
diff --git a/docs/releases/v2.3.1/V2.3.1-CANDIDATE-CONTRACT.md b/docs/releases/v2.3.1/V2.3.1-CANDIDATE-CONTRACT.md
new file mode 100644
index 00000000..a6cc8b8c
--- /dev/null
+++ b/docs/releases/v2.3.1/V2.3.1-CANDIDATE-CONTRACT.md
@@ -0,0 +1,60 @@
+# v2.3.1 Local Candidate: Feature and Resource Contract
+
+Companion documents: [中文契约](V2.3.1-CANDIDATE-CONTRACT.zh-CN.md) · [English contract](V2.3.1-CANDIDATE-CONTRACT.md)
+
+## 2026-09-04 release preflight
+
+- This candidate adds only the consent-revocation fix above `5f3db3a`: immediately invalidate old previews, block new previews/sends while consent persistence is pending, and cancel active advice requests without cancelling independent Optimizer calls. Claude performed the read-only audit; Codex implemented and tested the fix.
+- Full Node: 931 passed, 0 failed, 1 existing filesystem-capability skip; full Playwright: 124/124 passed. Six new behavioral regressions plus the host-callback wiring check failed before the fix and passed afterward.
+- Local package: `claude-code-usage-2.3.1-release-ready-20260904.vsix`, version 2.3.1, 107 files, 1,917,142 bytes; SHA-256: `0d1beaedb3bcf28467f776462e6028f4319a6c36944518e25194755067df8b8e`. This supersedes the overnight candidate and does not add future-version preparation features.
+- Native VS Code 1.135.0 isolated installation succeeded. Installed entry/Webview hashes match the tested build, and extension activation was observed without an extension error. The locked Mac prevented final native UI interaction checks; browser regressions do not substitute for them. No real BYOK request was made.
+- Read-only upstream check: main `eca4e43`, latest published release v2.3.0, open issues #94 / #91, no open PRs. Candidate publish/test workflows match upstream; the #94 compatibility-parameter fix is included, while #91 multi-currency remains deferred. No push, PR, merge, tag, or publication was performed.
+- Before release, the maintainer must unlock and spot-check Claude Today/30 days and Codex allowance in the original profile. Its intermittent zero-value symptom is not reliably reproduced; early non-persistent CLI sessions cannot be backfilled, while new normal persistent sessions retain logs. Windows/Linux installed-host smoke remains outstanding.
+- The maintainer reported Claude quota exhaustion; this turn made no further Claude calls. The overnight task remains scheduled until 08:00, with local verification and follow-up organization during the quota wait.
+
+## User benefit
+
+v2.3.1 converges existing advice into one verifiable loop. A user first sees the local aggregate evidence and success measure behind a recommendation, then chooses whether to use optional AI personalization. Afterwards they can record helpful, not helpful, and applied feedback, and compare tasks only when provider, task kind, complexity, measurement semantics, and quality guardrails match. When reliable pairs do not exist, the product says that evidence is insufficient instead of turning a fluctuation into a causal claim.
+
+The same release adds Codex hour detail for the last 30 days. Every populated date reads the sparse hourly aggregate already maintained by the provider index, with zero raw JSONL reads on click. Claude and Codex share the configured timezone and `HH:00` label format.
+
+## Furthest boundary for this candidate
+
+- AI sending reuses only the existing legal BYOK or user-configured endpoint and occurs only after an explicit click. Refreshes, background work, and hidden pages never generate AI requests.
+- The host prepares one `PreparedAdvicePayload`. Preview, byte count, SHA-256, retries, and the actual request body consume the same canonical UTF-8 bytes from that object. Reconstruction or disagreement fails closed.
+- The default payload contains allow-listed aggregates only. Prompt personalization is a separate, default-off, revocable consent; only text supplied or explicitly selected by the user can appear verbatim in preview and send.
+- Feedback, comparable pairs, and the versioned comparison-result envelope remain in bounded local state. They never store prompts, responses, sessions, paths, project names, raw records, or free-text feedback.
+- Legacy Get AI Advice and Prompt Optimizer share the preparation, preview, send, parse, and feedback boundary. Optimizer still processes only the user's pasted draft and never treats a permissive text fallback as structured advice.
+- Account center, authentication, multi-account switching, achievements, GitHub, default/background AI, version changes, default-setting changes, release-workflow changes, and publishing remain out of scope.
+
+## Single data producer
+
+- `ClaudeUsageIndex` remains the sole reader of Claude logs. The existing persistent provider index and its worker remain the sole readers of Codex logs.
+- Advice, feedback comparison, hourly expansion, and the Webview consume only main-index aggregates or bounded projections carrying `provider + measurementProfileVersion + revision + coverage`. They do not create a second scanner, scheduler, or competing cache of truth.
+- The Codex index maintains the sparse last-30-day `date -> hour` buckets during its normal incremental pass and evicts day 31 in the configured timezone. Its one-time fill migration runs in the existing Codex worker and shares the same durable progress state.
+
+## Resource ownership and stop conditions
+
+| Resource | Creator | Creation condition | Stop condition and disposer |
+| --- | --- | --- | --- |
+| Claude / Codex recurring timers and watchers | Existing window lifecycle coordinator in `extension.ts` | Provider enabled and window lifecycle permits work | Window loses focus, provider is disabled, or extension disposes; lifecycle coordinator disposes them |
+| Codex index / backfill worker | Existing `CodexIndexClient` | Main index needs a cold build, compatible migration, or incremental work and E-03 allows execution | Completion, checkpoint at budget exhaustion, user pause, provider disable, or extension dispose; client terminates the worker. A bounded first-availability backfill may continue after focus loss but never after explicit pause, disable, or dispose |
+| AI network request | Single host sender | User clicks Send after preview, the Prepared object is valid, and BYOK configuration is legal | Response, error, user cancellation, consent withdrawal, feature disable, or extension dispose; the sender cancellation owner aborts it. No retry timer or background poll exists |
+| Advice projections and comparison | No long-lived resource | Pure projection on a changed main-index revision, local feedback, or on-demand visible render | Released synchronously; no recomputation or render while hidden or disabled |
+| E-03 progress record | Main-index durable state | First migration or backfill need | Not a runtime resource; completion retains only version, verified position, `failStreak`, `nextEligibleAt`, `pausedReason`, and required counters |
+
+The E-03 success path continues immediately without an artificial delay. Only failure, lack of progress, or explicit pause creates a durable cooldown. Ordinary refresh, watch, focus, reset, menu open, or extension upgrade cannot bypass `nextEligibleAt`. Restart resumes from the verified checkpoint.
+
+## Zero additional long-lived resources when off
+
+Relative to v2.3.0, a disabled, unconsented, unsent, or hidden advice loop owns zero new timers, watchers, workers, network requests, log enumeration/body reads, and hidden Webview renders. After the Codex base-index migration finishes or stops, the resource inventory returns to baseline; no empty loop remains for hypothetical future work.
+
+## Acceptance boundary
+
+- Red-green focused tests first cover canonical bytes, explicit sending, strict parsing, real pair ingestion, the versioned comparison envelope, resource registration/disposal, durable backoff/resume, and 30-day hourly expansion.
+- Warm unchanged work produces zero JSONL body reads, derived mutations, and durable writes. Date expansion performs zero JSONL reads, and the hourly sum matches the daily total.
+- All user-facing copy covers eight locales. UI state has operation -> full reload -> state remains or snapshot invalidates coverage.
+- The candidate runs compile, focused and full Node/UI tests, disabled/unconsented zero-resource checks, warm-unchanged checks, VSIX inventory, and version/settings/workflow boundary checks, plus F5 and installed-VSIX smoke where feasible.
+
+---
+🤖 Generated with [OpenAI Codex](https://developers.openai.com/codex/)
diff --git a/docs/releases/v2.3.1/V2.3.1-CANDIDATE-CONTRACT.zh-CN.md b/docs/releases/v2.3.1/V2.3.1-CANDIDATE-CONTRACT.zh-CN.md
new file mode 100644
index 00000000..4376fd7c
--- /dev/null
+++ b/docs/releases/v2.3.1/V2.3.1-CANDIDATE-CONTRACT.zh-CN.md
@@ -0,0 +1,60 @@
+# v2.3.1 本地候选：功能与资源契约
+
+配套文档：[中文契约](V2.3.1-CANDIDATE-CONTRACT.zh-CN.md) · [English contract](V2.3.1-CANDIDATE-CONTRACT.md)
+
+## 2026-09-04 发版前核对
+
+- 当前候选在 `5f3db3a` 之上只补齐 Claude 独立审计指出的授权撤回问题：立即作废旧预览、阻止等待持久化期间的新预览/发送，并中止在途建议请求；独立 Optimizer 请求不受影响。Claude 只读审计，修复与回归由 Codex 实施。
+- 完整 Node：931 通过、0 失败、1 项既有文件系统能力跳过；完整 Playwright：124/124 通过。新增 6 个行为回归及宿主回调接线检查先失败、修复后通过。
+- 本地包：`claude-code-usage-2.3.1-release-ready-20260904.vsix`，版本 2.3.1，107 文件，1,917,142 bytes；SHA-256：`0d1beaedb3bcf28467f776462e6028f4319a6c36944518e25194755067df8b8e`。此包取代此前 overnight 候选，不混入后续版本预备功能。
+- 原生 VS Code 1.135.0 隔离安装成功，入口与 Webview 的安装文件哈希均与测试构建一致，观察到扩展激活且无本扩展异常。Mac 锁屏使最后的原生界面点验受阻；浏览器回归不替代这一步，也未做真实 BYOK 网络调用。
+- 上游只读核对：main 为 `eca4e43`，最新已发布版本为 v2.3.0，open issue 为 #94 / #91，open PR 为 0。候选的发布/测试 workflow 与当前上游一致；#94 的兼容参数修复已包含，#91 多币种延期。没有推送、PR、合并、tag 或发布操作。
+- 发版前仍需维护者解锁后点验原 profile 的 Claude 今日/30 天及 Codex 额度。原环境偶发零值尚未稳定复现；早期无持久会话的 CLI 调用不能回填，新的标准持久会话保留正常日志。Windows/Linux 安装态烟测仍未完成。
+- Claude 额度已由维护者报告耗尽，本轮没有再次调用；保留夜间任务到 08:00，额度等待期间只继续本地验证与后续整理。
+
+## 用户增益
+
+v2.3.1 把现有建议收敛成一条可验证的闭环：用户先看到建议所依据的本地聚合证据和成功标准，再决定是否使用可选的 AI 个性化；之后可以记录“有用 / 无用 / 已应用”，并用满足相同 provider、任务类型、复杂度、测量口径和质量护栏的任务对判断是否观察到改善。证据不足时只显示“证据不足”，不把波动写成因果结论。
+
+同版补齐 Codex 最近 30 天的日期到小时展开。任一有数据日期都从主索引已经保存的稀疏小时聚合读取，点击时不读原始 JSONL；Claude 与 Codex 使用同一配置时区和 `HH:00` 标签。
+
+## 本轮最远边界
+
+- AI 发送只复用现有合法 BYOK / 用户配置 endpoint，并且只由用户点击触发；没有默认、后台、刷新触发或隐藏页面触发的 AI 请求。
+- host 只准备一次 `PreparedAdvicePayload`。预览、字节数、SHA-256、重试与实际请求体都消费同一对象的同一组 canonical UTF-8 bytes，任何重建或不一致都失败关闭。
+- 默认只包含 allowlist 聚合。prompt 个性化是独立、默认关闭、可撤回的同意；只有用户提供或明确选择的文本才能逐字进入预览和发送。
+- 反馈、可比任务对和版本化 comparison result envelope 只保存在本地有界状态中；不保存 prompt、response、session、路径、项目名、原始记录或自由文本反馈。
+- 旧 Get AI Advice 与 Prompt Optimizer 复用同一准备、预览、发送、解析和反馈边界；Optimizer 仍只处理用户粘贴的草稿，不把宽松文本 fallback 当作结构化建议。
+- 不做账户中心、认证、多账户切换、成就页、GitHub、默认或后台 AI 请求；不改版本号、默认设置或 release workflow，也不发布。
+
+## 唯一数据生产者
+
+- Claude 原始日志的唯一读取者是 `ClaudeUsageIndex`；Codex 原始日志的唯一读取者是现有 persistent provider index 与其 worker。
+- advice、feedback comparison、小时展开和 Webview 只消费带 `provider + measurementProfileVersion + revision + coverage` 的主索引聚合或其有界投影；它们不建立第二套 scanner、缓存真相或 scheduler。
+- Codex 最近 30 天稀疏 `date -> hour` 桶由同一次主索引增量处理维护，并在配置时区下淘汰第 31 天。一次补齐迁移由现有 Codex worker 执行并复用同一持久进度状态。
+
+## 资源所有权与停止条件
+
+| 资源 | 创建者 | 创建条件 | 停止条件与实际销毁者 |
+| --- | --- | --- | --- |
+| Claude / Codex 周期 timer 与 watcher | `extension.ts` 的既有窗口生命周期协调器 | provider 启用且窗口处于允许状态 | 失焦、provider 关闭或 extension dispose；由生命周期协调器清理 |
+| Codex index / backfill worker | 现有 `CodexIndexClient` | 主索引需要 cold build、兼容迁移或增量工作，且 E-03 允许执行 | 完成、预算耗尽并 checkpoint、用户暂停、provider 关闭或 extension dispose；由 client 终止 worker。首次可用性 backfill 可在失焦后有界继续，但不能越过明确暂停、关闭或 dispose |
+| AI 网络请求 | 唯一 host sender | 用户预览后主动点击发送，Prepared 对象仍有效，且 BYOK 配置合法 | 响应、错误、用户取消、同意撤回、功能关闭或 extension dispose；由 sender 的 cancellation owner 中止。不存在 retry timer 或后台轮询 |
+| 建议投影与 comparison | 不创建长期资源 | 仅在主索引 revision 变化、用户反馈或相关页面按需展示时执行纯投影 | 同步完成即释放；页面隐藏或功能关闭后不重算、不重绘 |
+| E-03 进度记录 | 主索引 durable state | migration / backfill 第一次需要时 | 不是运行资源；完成后只保留版本、完成位置、`failStreak`、`nextEligibleAt`、`pausedReason` 与必要统计 |
+
+E-03 的成功路径立即继续，不人为等待。只有失败、无进展或明确暂停才设置持久 cooldown；普通 refresh、watch、focus、reset、菜单打开或插件升级不能绕过 `nextEligibleAt`。重启从已验证 checkpoint 继续。
+
+## 关闭后的零新增长期资源
+
+相对 v2.3.0：建议闭环关闭、未同意、未发送或页面隐藏时，新增资源必须为 0 timer、0 watcher、0 worker、0 network、0 额外日志枚举 / 正文读取、0 隐藏 Webview 重绘。Codex 基础索引迁移结束或停止后资源清单必须回到基线；不存在为“以后可能有用”保留的空循环。
+
+## 验收边界
+
+- red-green 聚焦测试先覆盖 canonical bytes、显式发送、严格解析、真实 pair ingestion、版本化 comparison envelope、资源登记 / 销毁、持久 backoff / resume 和 30 天小时展开。
+- warm unchanged 为 0 JSONL body read、0 派生 mutation、0 durable write；展开日期为 0 JSONL read，小时合计与当日汇总一致。
+- 所有用户文案覆盖八个 locale；UI 状态具备“操作 -> full reload -> 状态保留 / 快照失效”测试。
+- 最终运行 compile、聚焦与全量 Node/UI 测试、关闭 / 未授权零资源、warm unchanged、VSIX 清单及版本 / 设置 / workflow 边界检查；可行时完成 F5 与 installed-VSIX smoke。
+
+---
+🤖 Generated with [OpenAI Codex](https://developers.openai.com/codex/)
diff --git a/docs/roadmap/provider-parity-v2.4.md b/docs/roadmap/provider-parity-v2.4.md
new file mode 100644
index 00000000..602de5c5
--- /dev/null
+++ b/docs/roadmap/provider-parity-v2.4.md
@@ -0,0 +1,69 @@
+# v2.4 Claude / Codex interaction-parity roadmap
+
+This roadmap follows the v2.3.1 regression fixes. Its goal is to give equivalent information the same interaction, visual hierarchy, keyboard behavior, and feedback without pretending that Claude and Codex expose equivalent metrics. It is outside the v2.3.1 release scope; every item starts with a minimal failing fixture.
+
+## P0: inventory and independent audit
+
+- Build a component-by-component Claude/Codex matrix covering status items, quota tooltips, summary cards, charts, tables, disclosures, empty/loading/error states, filters, sorting, drill-down, return paths, narrow layouts, and light/dark themes.
+- Before adding a drill-down affordance, prove the required aggregate exists for each provider and source. Codex's materialized hourly sidecar is the first feasibility gate. If a source cannot support the same level truthfully, record an intentional semantic difference and offer a provider-appropriate detail (or no affordance) instead of a dead or invented chart.
+- Run one read-only Claude CLI audit over production HTML/CSS/TypeScript and installed-build screenshots, classifying findings as missing, behavior mismatch, visual mismatch, or intentional semantic difference.
+- The audit may use only source, synthetic fixtures, and privacy-safe screenshots; no account data, paths, thread titles, prompts, log bodies, or credentials.
+
+## P0.5: accepted post-v2.3.1 audit follow-ups
+
+- Rearm failed Claude/Codex file watchers with bounded exponential backoff while
+  polling remains the safe fallback; test repeated failure, recovery, and
+  disposal without a hot loop.
+- Cache `session_index.jsonl` by verified size/mtime and keep title recovery
+  streaming and memory-bounded. Preserve the rule that titles stay memory-only
+  and every non-title field remains ignored.
+- Rename rolling-30-day variables that still say `month`, remove dead hourly
+  caches/branches, and escape every dynamic error-page slot before insertion.
+- Localize the non-zero `component-delta-clamped` quality explanation and add a
+  migration fixture proving quota compaction retains the oldest/newest boundary
+  evidence needed for later confidence calculations.
+- Add explicit browser contracts for Advice snooze persistence and for Compare
+  never summing cross-provider cost or quota. Decide whether the legacy Claude
+  Share Card is retired into the Compare studio or receives full timezone and
+  eight-locale parity before adding more sharing surfaces.
+- Implement [#91](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/91)
+  as a local display preference only: user-entered rate, currency code/symbol,
+  deterministic formatting, no exchange-rate network dependency, and USD kept
+  as the auditable base value.
+- Keep the detailed local-data inventory and destructive clear-path reference in
+  `LOCAL-DATA.md` / `LOCAL-DATA.zh-CN.md`; do not reintroduce the verbose panel
+  into the normal plugin Settings surface.
+
+## P1: time-hierarchy chart drill-down
+
+- All-time month bar: click or Enter/Space opens that month's daily data.
+- Last-30-days day bar: click or Enter/Space opens that day's hourly data.
+- Today hour bar: use the same selected/highlight/detail feedback without inventing unsupported granularity.
+- Claude and Codex share selection, `aria-expanded`, `aria-controls`, focus, empty-state, back/collapse, and responsive-layout behavior.
+- Drill-down must use materialized month/day/hour aggregates and perform zero JSONL reads on click. An incomplete hourly migration shows explicit subtotal/coverage state rather than unverified legacy totals.
+- Preserve the expanded chain, selected period, keyboard focus, and scroll anchor through live refresh. Define which of those states survives a webview reload and test that contract explicitly.
+- Zero-fill missing calendar dates/hours inside a selected range so sparse activity does not distort axes or make the hierarchy appear shorter than the requested range.
+
+## P2: status bar and quota detail
+
+- Both providers use configured-timezone Today for the main item and a structured tooltip table.
+- Five-hour/weekly quotas share used-percent semantics, green/amber/red thresholds, progress bars, reset columns, and keyboard-reachable entry points.
+- The status-item background follows the worst live window that the current preference renders; expired and no-observation states never leave a stale warning colour or an empty tooltip table.
+- Evidence remains honest: Claude is official `/usage`; Codex is a last local observation. Visual parity must not imply equal authority.
+
+## P3: component and state parity
+
+- Align summary-card density, numeric typography, units, help copy, zero values, unpriced values, and indexed-subtotal treatment.
+- Align table sorting, numeric alignment, row expansion, scrollers, empty rows, and narrow layouts.
+- Align disclosure defaults, hit areas, focus treatment, and persistence rules.
+- Align loading, no-data, partial-index, stale-observation, and error hierarchy while retaining provider-specific causes.
+- Give every chart a provider-qualified accessible text alternative. In Compare, controls and regions must have unique accessible names even when the visible label is shared.
+- Compare continues to combine only comparable activity; it never adds bills, allowances, or capability.
+
+## P4: exit gate
+
+- A tracked parity matrix marks every difference aligned or intentionally different with a semantic rationale.
+- Node fixtures cover non-UTC and DST conservation (`sum(hours) = day`, `sum(days) = month`, and Today uses the same day map), zero JSONL reads on click, quota thresholds, and Today status scope.
+- Playwright covers mouse, Enter/Space, ARIA, focus, Light+/Dark+, 360 px, the longest locale, and drill-down/collapse flows.
+- An isolated VS Code profile installs the VSIX and captures privacy-safe Claude/Codex Today status, quota tooltip, month-to-day, and day-to-hour evidence.
+- After one read-only Claude CLI audit, allow one revision review for selected findings; all blockers close before candidate packaging.
diff --git a/docs/roadmap/provider-parity-v2.4.zh-CN.md b/docs/roadmap/provider-parity-v2.4.zh-CN.md
new file mode 100644
index 00000000..d88fae16
--- /dev/null
+++ b/docs/roadmap/provider-parity-v2.4.zh-CN.md
@@ -0,0 +1,63 @@
+# v2.4 Claude / Codex 交互一致性路线图
+
+本路线图承接 v2.3.1 的回归修复，目标是在不混淆两家 provider 指标语义的前提下，让相同类型的信息采用相同的交互、视觉层级、键盘行为和反馈方式。它不是 v2.3.1 发布范围；每项进入实现前都要先补最小失败夹具。
+
+## P0：交互清单与独立审计
+
+- 建立 Claude / Codex 逐组件对照表：状态栏、额度 tooltip、摘要卡、图表、表格、折叠项、空状态、加载/失败状态、筛选、排序、下钻、返回路径、窄屏和深浅主题。
+- 增加任何下钻入口前，先证明各 provider、各数据源确实具备所需聚合；Codex 已物化小时侧车是首个可行性门。若某个来源无法如实支持同一层级，应记录为“刻意保留的语义差异”，改用 provider 合适的详情或不提供入口，不能做无响应或虚构的图表。
+- 用 Claude CLI 对生产 HTML/CSS/TypeScript 和真实安装截图做一次只读审计，输出“缺失、行为不同、视觉不同、刻意保留语义差异”四类问题。
+- 审计不得读取或输出账号、路径、线程标题、prompt、日志正文或凭证；只允许代码、合成 fixture 和隐私安全截图。
+
+## P0.5：v2.3.1 独立审阅后采纳的后续项
+
+- Claude/Codex 文件 watcher 失败后采用有界指数退避重建，轮询继续作为安全兜底；
+  测试连续失败、恢复与 dispose，确保不会热循环。
+- 按校验后的 size/mtime 缓存 `session_index.jsonl`，线程标题恢复继续保持流式与
+  内存有界；标题仍只驻留内存，其他字段继续全部忽略。
+- 清理仍以 `month` 命名的滚动 30 天变量、无效小时缓存与死分支，并在插入动态
+  错误页内容前统一转义。
+- 为非零 `component-delta-clamped` 质量标记补齐本地化解释，并增加迁移夹具，证明
+  quota 压缩会保留后续置信度计算所需的最早/最新边界证据。
+- 增加 Advice 暂停状态跨重载持久化，以及 Compare 永不跨 provider 相加成本或额度
+  的浏览器契约。继续扩展分享功能前，先决定旧 Claude Share Card 是收敛到 Compare
+  工作台，还是补齐时区与八语言一致性。
+- 将 [#91](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/91) 实现为纯本地
+  显示偏好：用户填写汇率、币种代码/符号，格式确定可复现，不增加联网汇率源，并
+  保留 USD 作为可审计基准值。
+- 详细本地数据清单与破坏性清理路径只保留在 `LOCAL-DATA.md` /
+  `LOCAL-DATA.zh-CN.md`；不把冗长面板重新放回插件的常规设置界面。
+
+## P1：图表按时间层级下钻
+
+- 全部时间的月柱：点击或按 Enter/Space 后展开该月的每日数据。
+- 最近 30 天的日柱：点击或按 Enter/Space 后展开该日的小时数据。
+- 今日的小时柱：保持同一选中/高亮/详情反馈，不制造无法从本地索引支持的更细粒度。
+- Claude 与 Codex 共用同一套选中态、`aria-expanded`、`aria-controls`、焦点、空数据提示、返回/收起入口和响应式布局。
+- 下钻只能使用已物化的日/月/小时聚合；点击时不得重新扫描 JSONL。若小时侧车仍在迁移，显示明确的小计/覆盖率，不回退到未经验证的旧总量。
+- 实时刷新后保留展开链、所选周期、键盘焦点和滚动锚点；同时明确哪些状态应跨 webview 重载保存，并对该契约单独测试。
+- 在选定范围内补齐无活动的日期/小时为零，避免稀疏记录扭曲坐标轴或让层级看起来短于请求范围。
+
+## P2：状态栏与额度详情
+
+- 两个 provider 的主状态项都以配置时区下的“今日”作为范围，并在 tooltip 中使用结构化表格。
+- 5 小时/每周额度统一使用“已用百分比”、同一绿色/黄色/红色阈值、同一进度条、重置时间列和键盘可达入口。
+- 状态项背景色由当前偏好实际显示的所有有效窗口中最危险者决定；已过期或无观测状态不得遗留警告色，也不得显示只有表头的空 tooltip。
+- provider 特有的证据边界保留原意：Claude 为官方 `/usage`，Codex 为本地最后观测；不得用视觉一致性暗示数据权威性等价。
+
+## P3：组件和状态一致性
+
+- 摘要卡：密度、数字字体、单位、帮助文本、零值、未定价和索引小计样式一致。
+- 表格：排序、数值对齐、行展开、滚动容器、空行和窄屏行为一致。
+- 折叠项：默认开合状态、summary 命中区、焦点样式和状态持久化规则一致。
+- 加载、空数据、部分索引、过期观测和错误状态使用同一信息层级，但保留 provider 专属原因。
+- 每张图都提供带 provider 名称的可访问文本替代；Compare 中即使可见标签相同，控件与区域也必须具有唯一的可访问名称。
+- Compare 只比较可比较的活动量，不相加账单、额度或能力。
+
+## P4：验收门
+
+- 一份可追踪的 provider parity matrix，每个差异标记为“已对齐”或“刻意不同”，后者必须写明语义理由。
+- Node 夹具覆盖非 UTC 与 DST 守恒（`小时之和 = 日`、`日之和 = 月`，且 Today 使用同一日表）、点击零额外 JSONL 读取、额度阈值和状态栏范围。
+- Playwright 覆盖鼠标、Enter/Space、ARIA、焦点、Light+/Dark+、360 px、最长语言和逐级下钻/收起。
+- 在隔离 VS Code profile 安装 VSIX，至少截取 Claude/Codex 今日状态栏、额度 tooltip、月→日和日→小时四组隐私安全实图。
+- Claude CLI 首轮只读审计后只允许一次针对已选问题的修订复核；阻塞问题关闭后才进入候选打包。
diff --git a/docs/superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.md b/docs/superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.md
new file mode 100644
index 00000000..4a9f08e9
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.md
@@ -0,0 +1,156 @@
+# v2.5.3 Project-scoped AI usage review plan
+
+Status: planning frozen; implementation is not authorized.
+Target train: internal `v2.5.3` slot within `v2.5.x`; it need not ship as a standalone Marketplace release.
+Product host: the existing `Explore → Projects` surface; no new top-level tab.
+Prerequisites: the v2.3.1 safe AI request boundary and local-data controls, the X-06 project-usage matrix, and the v2.4.x recommendation-experiment/comparable-task envelope.
+
+## 1. Placement decision
+
+This feature does not reopen v2.3.1 and does not block its install verification or release decision. It is more sensitive than ordinary project aggregation: it may read selected project input/output text, invoke a user-selected remote AI or local Claude CLI, and retain a structured recommendation result. It therefore belongs to the `v2.5.x` “local efficiency lab”, with `v2.5.3` as its candidate internal slot.
+
+It does not depend on GitHub Connect. It may share a package with other v2.5.x capabilities, but its consent, clearing, network, and rollback boundaries remain independent.
+
+## 2. User outcome
+
+After selecting one project, provider, and date range, the user first receives a deterministic, fully local usage-behavior summary and then decides whether to invoke AI for deeper review. The report answers:
+
+- how tokens, caching, context, model/effort, sessions, and iteration behavior changed in this project;
+- which input/output patterns may indicate repeated work, context growth, or redundant review;
+- one small experiment to try on the next comparable task; and
+- which observable metric should be used to evaluate that experiment.
+
+The report must not infer productivity, code quality, research quality, individual performance, or model capability from token volume alone.
+
+## 3. Three review modes
+
+1. **Local usage review (default):** numeric and structural aggregates from existing indexes only; no network and no content reads.
+2. **AI aggregate review:** sends a user-previewed and confirmed project aggregate snapshot; no prompt, response, path, project name, thread title, or account identifier.
+3. **AI content-assisted review (separate consent):** reads only the conversations/date range selected for this run and produces bounded, sanitized input/output samples. Before sending, the UI shows the exact items, roles, byte count, and final request body; the user can remove any item. Aggregate-review consent never implies content consent.
+
+No mode may automatically scan the workspace, source code, dotfiles, secrets, git remotes, terminal history, or unselected conversations.
+
+## 4. Analysis semantics
+
+### 4.1 Deterministic local evidence
+
+- provider-native processed, fresh-input, cached-input, output, and reasoning semantics;
+- cache reuse/warm-up, context churn/compaction, and long-context growth;
+- model and reasoning-effort changes across task phases;
+- structural counts for session splits, resumes, subagents, and tool steps;
+- observable proxies for retries, repeated review, unchanged long chains, and output rewrites;
+- input/output length, turn count, and ratios; and
+- separate columns for official quota observations, API-equivalent value, and local tokens—never substitutes for one another.
+
+### 4.2 AI interpretation layer
+
+Every finding uses a fixed structure:
+
+`observation → local evidence reference → why it may matter → one next experiment → measurement → confidence/limits`
+
+AI may only interpret the frozen snapshot. It cannot rewrite source metrics, change model/effort, edit project files, run commands, or perform external writes. Content-assisted mode may discuss prompt structure, output verbosity, or repeated instructions, but must not equate writing style with task quality.
+
+## 5. Local and outbound data-contract delta
+
+| Data class | Content | Persistence | Outbound rule |
+|---|---|---|---|
+| Project review snapshot | Anonymous `projectRef`, provider, date/timezone, coverage, model/effort, token and structural aggregates, evidence IDs | Generated on demand by default; no second log index or permanent per-project cache | Sent only in AI aggregate/content modes after exact preview |
+| Optional content samples | Inputs/outputs selected for this run, roles, local order, sanitation flags | Memory only until completion/cancellation; never globalState, logs, or reports | Separate consent and itemized preview; stop at item/byte limits without silent truncation |
+| Request preview | Backend, model, mode, exact body, byte count, snapshot hash | Not persisted by default; only value-free audit metadata may be retained | Preview and actual body must be byte-identical |
+| Structured review result | Finding IDs, evidence IDs, confidence, limitations, experiment, measurement | Optional local save; schemaVersion, bounded count/retention, per-item/all clear; no raw quotes or raw CLI output | Not sent again by default |
+| Consent/preferences | Default mode, retention choice, last backend | Bounded local settings; content consent is per request and cannot be “always allow” | Never outbound |
+| AI credential | Existing SecretStorage key or a future separately reviewed secret key | SecretStorage only | Used only for the confirmed backend; never body, preview, or Webview state |
+| CLI audit metadata | Sanitized executable identity, version, model, input hash, time, exit status | Optional bounded record; no raw stdout/stderr | Never sent to a second service |
+
+`projectRef` is a one-way derivation from machine salt and the provider-native project key. The runtime UI may show the local project name, but persisted results and outbound payloads must not contain that name or an absolute path.
+
+## 6. AI backend boundaries
+
+### 6.1 Existing BYOK/API mode
+
+- Reuse the v2.3.1 preview → separate Send → result flow, timeouts, cancellation, and SecretStorage.
+- Endpoint/model/key failures exit safely; disabled mode has zero requests and zero timers.
+- Send only the exact previewed payload, with no diagnostics, paths, or ambient context.
+
+### 6.2 Optional local Claude CLI mode
+
+This adapter is an independent v2.5.3 safety gate. Finding `claude` on the machine never enables it automatically:
+
+- show the exact executable, version, model, mode, payload bytes, and network disclosure for every run;
+- spawn an argument array directly and stream stdin—never concatenate a shell command; use print mode, no tools, no session persistence, safe mode, an isolated empty cwd, a minimal environment, timeout, and cancellation;
+- grant no repository tools, project cwd access, MCP, plugins, or hooks; treat all project input/output as untrusted data;
+- cap captured output, validate it against the schema before display, and never persist raw stdout/stderr; and
+- on expired login, quota exhaustion, timeout, or non-zero exit, offer at most one explicit retry and never loop in the background.
+
+The local CLI may still send the confirmed payload to its AI service, so the UI must not call it “fully offline”.
+
+## 7. Prompt injection and output validation
+
+- Project input/output, tool results, code fragments, and earlier model replies are **untrusted data**; embedded instructions cannot alter the reviewer system contract.
+- The reviewer has no tools, network tools, or write access and returns versioned JSON only.
+- The output schema includes at least `schemaVersion`, `snapshotHash`, `scope`, `findings[]`, and `limitations[]`; every finding references evidence IDs present in the request.
+- Unknown evidence, cross-project claims, unsupported quality claims, invented causality, and auto-execution advice invalidate the finding. Parse failure is shown as failure and never falls back to unvalidated free text.
+- The renderer uses `textContent` or an equivalent safe renderer; model HTML/Markdown never becomes executable DOM.
+
+## 8. UI and interaction placement
+
+Add a “Generate AI usage review” action to the selected project detail within `Explore → Projects`:
+
+1. choose provider, project, and a 7/30/90-day or custom range;
+2. inspect the local deterministic summary and coverage;
+3. select one of the three modes;
+4. inspect and edit the exact payload preview;
+5. explicitly Send/Run, with cancellation; and
+6. read results as observation–evidence–experiment–measurement, then optionally save the sanitized result, mark the experiment tried, or clear it.
+
+Single-provider, no-content, insufficient-sample, rebuilding-data, and AI-unavailable states all need explicit empty states. Reload restores only nonsensitive choices and never restores an unsent body or automatically resends it.
+
+## 9. Goal stages and checkpoints
+
+| Stage | Deliverable | Exit condition | Read-only Claude calibration |
+|---|---|---|---|
+| R0 scope/threat model | Spec, contract delta, golden fixtures, non-goals | Project isolation, three modes, and outbound fields frozen | Review privacy, injection, and release placement |
+| R1 project snapshot | Pure snapshot/coverage/evidence functions over existing indexes | Cold/warm agree; no rescan and no second cache | Not required |
+| R2 preview/consent | Payload builder, exact preview, size caps, revoke/clear | Aggregate-only default; content consent cannot inherit; preview=body | Review minimization and permission semantics |
+| R3 AI result contract | Backend-neutral adapter, JSON schema, evidence validator | Malformed, injected, and cross-project output fail closed | Not required |
+| R4 UI/local report | Project entry, progress/cancel, structured report, experiment record | Eight locales, keyboard, ARIA, themes, and 360 px pass | Review advice against evidence boundaries |
+| R5 optional Claude CLI adapter | No-shell spawn, isolated cwd, no tools/persistence, timeout | Synthetic end-to-end passes; failure/unauthorized mode leaves no process | Security review before production wiring |
+| R6 docs/candidate | README/LOCAL-DATA/CHANGELOG, installed screenshot, VSIX | Release tests, fresh/upgrade/clear, matrix, hands-on test | Pre-install final review; GO authorizes local install only |
+
+Every Goal states `authorized_through: R<n>`. Without explicit R5 authorization, the CLI adapter remains fake/fixture-only. Without explicit external-AI authorization, R2–R4 use mock transport only.
+
+## 10. Acceptance matrix
+
+- [ ] The selected project never mixes a same-named project, another provider/profile, or another date range.
+- [ ] Local mode has zero network and zero content reads; closing the page leaves no timer/watcher/worker.
+- [ ] Warm unchanged reuses the existing snapshot and does not rescan JSONL.
+- [ ] Aggregate-only payload has no project name, path, account, thread/session ID, prompt/response, or unknown field.
+- [ ] Content mode requires per-run consent; exact preview equals the body; cancellation sends nothing.
+- [ ] Secret/path/project/privacy canaries cannot leak through API, CLI, result persistence, or export.
+- [ ] Malicious input/output cannot obtain tools, alter the system contract, execute HTML, or fabricate evidence.
+- [ ] Findings with missing evidence are rejected; insufficient samples yield “insufficient evidence” rather than generic advice.
+- [ ] Tokens, cost, quota, forecast, and quality proxies are separate and carry coverage/confidence.
+- [ ] Timeout, cancellation, expired CLI login, exhausted quota, non-zero exit, oversized output, and malformed JSON fail closed.
+- [ ] Raw content, full requests, and raw CLI output are not persisted; structured reports obey bounded retention and exact clearing.
+- [ ] Migration, window reload, repeat clicks, and stale ACKs do not duplicate calls or revive cleared data.
+- [ ] All copy covers eight locales; keyboard/focus/ARIA, light/dark themes, and approximately 360 px pass.
+- [ ] Docs state that local CLI is not necessarily offline, AI advice is not a productivity/quality judgment, and the extension never auto-executes advice.
+- [ ] Before a real release, Codex runs the complete gate and Claude performs bounded read-only reviews of the spec, payload/security diff, advice semantics, and final candidate.
+
+## 11. Explicit non-goals
+
+- No project/person productivity score, leaderboard, cross-user benchmark, or “which model is strongest” claim.
+- No automatic edits to model, effort, prompts, code, CLAUDE.md, settings, issues, or pull requests.
+- No background AI calls, quota-triggered sending, or permanent consent inherited from one run.
+- No retained full-project conversation corpus and no second raw prompt/response index.
+- No GitHub connection, sync, public sharing, or community data prerequisite.
+
+## 12. Conditions to start the next Goal
+
+Create an implementation Goal only after all of the following are true:
+
+1. v2.3.1 has completed the maintainer's install test and has a release-or-revise decision;
+2. the X-06 project-usage matrix is on a stable line or its snapshot contract is frozen;
+3. the v2.4.x comparison envelope and local feedback/clear semantics are reusable;
+4. the user decides whether this run ends at R4 or also authorizes the R5 local Claude CLI safety gate; and
+5. the data contract, README/LOCAL-DATA, and clear inventory are planned to ship with the code change.
diff --git a/docs/superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.zh-CN.md b/docs/superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.zh-CN.md
new file mode 100644
index 00000000..44db6fa3
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-02-v2.5.3-project-ai-usage-review.zh-CN.md
@@ -0,0 +1,156 @@
+# v2.5.3 项目级 AI 用量审阅计划
+
+状态：规划冻结，尚未授权实现。
+目标列车：`v2.5.x` 内部槽位 `v2.5.3`；不承诺单独发布 Marketplace 包。
+产品宿主：现有 `Explore → Projects`，不新增顶层 Tab。
+前置能力：v2.3.1 安全 AI 请求边界和本地数据控制、X-06 项目用量矩阵、v2.4.x 建议实验/同类任务比较 envelope。
+
+## 1. 版本归属决定
+
+本功能不回填 v2.3.1，也不阻塞 v2.3.1 的安装验证或发布决策。它比普通的项目聚合更敏感：可能读取选定项目的输入/输出正文、调用用户选择的远程 AI 或本机 Claude CLI，并保存结构化建议结果。因此归入 `v2.5.x` 的“本地效率实验室”，候选内部槽位为 `v2.5.3`。
+
+它不依赖 GitHub Connect。若发版列车需要合并，可与其他 v2.5.x 能力同包发布，但必须保留独立的同意、数据清除、网络和回滚边界。
+
+## 2. 用户结果
+
+用户选择一个项目、provider 和时间范围后，可以先获得完全本地、确定性的用量行为摘要，再决定是否调用 AI 深度审阅。报告回答：
+
+- 这个项目的 Token、缓存、上下文、模型/effort、Session 和迭代行为如何变化；
+- 哪些输入/输出形态可能造成重复劳动、上下文膨胀或无效复审；
+- 下一次相似任务可以尝试哪一个小实验；
+- 用什么可观测指标判断实验是否有效。
+
+报告不得仅凭 Token 消耗评价生产率、代码质量、研究质量、人员表现或模型能力。
+
+## 3. 三档审阅模式
+
+1. **仅本地用量审阅（默认）**：只使用现有索引中的数值和结构聚合，不联网，不读取正文。
+2. **AI 聚合审阅**：发送用户预览并确认的项目聚合快照；不包含 prompt、response、路径、项目名、线程标题或账号标识。
+3. **AI 内容辅助审阅（单独同意）**：只读取用户本次明确选择的会话/日期范围，净化并有界抽取输入/输出。发送前显示精确条目、角色、字节数和最终请求正文；用户可以移除任何条目。该同意不能由“AI 聚合审阅”继承。
+
+任何模式都不得自动扫描整个 workspace、读取源码、dotfile、secret、git remote、终端历史或未经选择的会话。
+
+## 4. 分析口径
+
+### 4.1 本地确定性证据
+
+- processed、fresh input、cached input、output 和 reasoning 的 provider 原生口径；
+- cache reuse/warm-up、context churn/compaction、长上下文增长；
+- 模型与 reasoning effort 的切换及其任务阶段；
+- Session 拆分、恢复、subagent 和工具步骤的结构计数；
+- 重试、反复复审、无变化长链路和输出重写的可观测 proxy；
+- 输入/输出长度、轮次和比例；
+- 官方额度观测、API 等效价值和本地 Token 必须分栏，不能互相替代。
+
+### 4.2 AI 可解释层
+
+每条发现必须使用固定结构：
+
+`看到了什么 → 本地证据引用 → 为什么值得注意 → 下次只试一个什么动作 → 用什么指标复核 → 置信度/限制`
+
+AI 只能解释冻结的项目快照，不能改写源指标、自动更换模型/effort、编辑项目文件、运行命令或发起外部写入。内容模式可以评论提示结构、输出冗余和重复说明，但不得把文字风格直接推断为任务质量。
+
+## 5. 本地与外发数据契约增量
+
+| 数据类 | 内容 | 持久化 | 外发规则 |
+|---|---|---|---|
+| 项目审阅快照 | 匿名 `projectRef`、provider、日期/时区、coverage、模型/effort、Token 与结构聚合、证据 ID | 默认按需生成；不得建立第二套日志索引或按项目常驻缓存 | 仅 AI 聚合/内容模式在精确预览后发送 |
+| 可选内容样本 | 用户本次选择的输入/输出、角色、局部时间顺序及净化标记 | 只在内存保留到请求完成/取消；不得写入 globalState、日志或报告 | 必须单独同意并逐项预览；达到字节/条目上限后停止，不静默截断 |
+| 请求预览 | backend、model、模式、精确正文、字节数、snapshot hash | 默认不持久化；只可记录无内容的审计元数据 | 预览与实际 body 必须字节一致 |
+| 结构化审阅结果 | finding ID、evidence IDs、置信度、限制、建议实验和衡量方式 | 可选本地保存；有 schemaVersion、有界条数/保留期、可单项及全部清除；不得含原文引语或原始 CLI 输出 | 默认不再次外发 |
+| 用户同意/偏好 | 默认模式、是否允许内容、保留策略、上次选定 backend | 本地有界设置；内容同意按每次请求，不允许永久“总是允许” | 不外发 |
+| AI 凭证 | 沿用现有 SecretStorage key 或未来独立、审阅后的 secret key | 仅 SecretStorage | 只用于用户本次确认的 backend；绝不进入 body/预览/Webview state |
+| CLI 审计元数据 | CLI 路径的净化标识、版本、model、输入 hash、时间、退出状态 | 可选有界记录；不保存 stdout/stderr 原文 | 不外发给第二服务 |
+
+`projectRef` 必须由机器盐和 provider 原生项目键单向派生；报告 UI 可在运行期显示本地项目名，但持久化结果和外发 payload 不得包含项目名或绝对路径。
+
+## 6. AI backend 边界
+
+### 6.1 现有 BYOK/API 模式
+
+- 复用 v2.3.1 的 preview → 单独 Send → result 流程、超时、取消和 SecretStorage。
+- endpoint/model/key 失败必须安全退出；不开启时零请求、零 timer。
+- 请求只发送精确预览中的 payload，不附加诊断、路径或后台上下文。
+
+### 6.2 可选本机 Claude CLI 模式
+
+该 adapter 属于 v2.5.3 的独立安全门，不能因为机器上存在 `claude` 就默认启用：
+
+- 每次显示将执行的精确二进制、版本、model、模式、payload 字节数和联网说明；
+- 直接 spawn 参数数组并通过 stdin 传输，禁止 shell 拼接；使用 print、禁用工具、禁用会话持久化、安全模式、隔离空目录、最小环境、超时和取消；
+- CLI 无仓库工具、无 cwd 项目访问权、无 MCP/plugin/hook；项目输入/输出始终按不可信数据处理；
+- 捕获输出有严格字节上限，先按 schema 校验再显示；原始 stdout/stderr 不持久化；
+- 登录失效、额度不足、超时或非零退出最多给出一次显式重试，不后台循环。
+
+本机 CLI 仍可能把确认后的 payload 发送给对应 AI 服务，因此 UI 不能把它称为“完全离线”。
+
+## 7. Prompt injection 与输出校验
+
+- 项目输入/输出、工具结果、代码片段和模型旧回答全部是**不可信数据**，其中的指令不得改变 reviewer system contract。
+- reviewer 无工具、无网络工具、无写权限，只返回版本化 JSON。
+- 输出 schema 至少包含 `schemaVersion`、`snapshotHash`、`scope`、`findings[]`、`limitations[]`；每个 finding 必须引用输入中存在的 evidence ID。
+- 未知 evidence、跨项目主张、未提供的质量结论、凭空的因果关系和自动执行建议使该 finding 失效；解析失败时展示失败，不回退到未经校验的自由文本。
+- 展示层以 `textContent`/安全 renderer 输出，任何模型 HTML/Markdown 均不得成为可执行 DOM。
+
+## 8. UI 与交互位置
+
+在 `Explore → Projects` 的选定项目详情中增加“生成 AI 用量审阅”动作：
+
+1. 选择 provider、项目和 7/30/90 天或自定义范围；
+2. 查看本地确定性摘要和 coverage；
+3. 选择三档模式；
+4. 查看并编辑精确 payload 预览；
+5. 明确 Send/Run，支持取消；
+6. 结果按“观察—证据—实验—复核”展示，并允许保存净化结果、标记已尝试或清除。
+
+单一 provider、无内容、样本不足、数据重建中和 AI 不可用都必须有可解释空状态。刷新/重载后只恢复非敏感选择，不恢复未发送正文或自动重发。
+
+## 9. Goal 阶段与检查点
+
+| 阶段 | 产物 | 退出条件 | Claude 只读校准 |
+|---|---|---|---|
+| R0 范围与威胁模型 | spec、数据契约增量、golden fixtures、非目标 | 项目隔离、三档模式和外发字段冻结 | 审阅隐私、注入和版本归属 |
+| R1 项目快照 | 复用现有索引的纯函数 snapshot/coverage/evidence | 冷/热结果一致，不重扫日志，无第二缓存 | 不需要 |
+| R2 预览与同意 | payload builder、精确 preview、大小上限、撤回/清除 | aggregate-only 默认；内容同意不能继承；preview=body | 审阅数据最小化和权限语义 |
+| R3 AI 结果契约 | backend-neutral adapter、JSON schema、evidence validator | malformed/injected/跨项目输出全部 fail closed | 不需要 |
+| R4 UI 与本地报告 | Explore 项目入口、进度/取消、结构化报告和实验记录 | 8 locale、键盘、ARIA、深浅主题、360 px 通过 | 审阅建议是否越过证据边界 |
+| R5 可选 Claude CLI adapter | 无 shell spawn、隔离 cwd、no-tools/no-persistence、超时 | 合成端到端通过，未授权/失败时零残留进程 | 安全复核后才允许接生产 |
+| R6 文档与候选 | README/LOCAL-DATA/CHANGELOG、安装截图、VSIX | release tests、fresh/upgrade/clear、验收矩阵、人工试用 | 发布前终审；GO 只授权本地安装 |
+
+每个 Goal 必须写明 `authorized_through: R<n>`。未明确授权 R5 时，CLI adapter 只能保留 fake/fixture 实现；未明确授权外部 AI 时，R2–R4 只用 mock transport。
+
+## 10. 验收矩阵
+
+- [ ] 选定项目的数据不会混入同名项目、另一个 provider、另一个 profile 或另一个日期范围。
+- [ ] 本地模式零网络、零正文读取；页面关闭后零新增 timer/watcher/worker。
+- [ ] warm unchanged 复用现有快照，不重新扫描 JSONL。
+- [ ] aggregate-only payload 不含项目名、路径、账号、thread/session ID、prompt/response 或未知字段。
+- [ ] 内容模式逐次同意，精确预览与实际 body 字节一致，取消后不发送。
+- [ ] secret/path/project/privacy canary 在 API、CLI、结果保存和导出四条路径都不能泄漏。
+- [ ] malicious prompt/output 不能获得工具、改变 system contract、执行 HTML 或伪造 evidence。
+- [ ] AI 结果引用不存在 evidence 时被拒绝；不足样本返回“证据不足”，不生成泛化建议。
+- [ ] Token、成本、额度、预测和质量 proxy 在报告中分栏并带 coverage/置信度。
+- [ ] timeout、取消、CLI 登录失效、额度不足、非零退出、超长输出和 malformed JSON fail closed。
+- [ ] 原始内容、完整请求和原始 CLI 输出不持久化；结构化报告遵守有界保留和精确清除。
+- [ ] 旧缓存迁移、窗口 reload、重复点击和 stale ACK 不重复调用或复活已清数据。
+- [ ] 所有用户文案覆盖 8 locale，键盘/焦点/ARIA、深浅主题和约 360 px 通过。
+- [ ] 文档准确说明：本机 CLI 不等于离线、AI 建议不是生产率/质量结论、插件不会自动执行建议。
+- [ ] 真实发布前由 Codex 运行完整门禁，并让 Claude 对 spec、payload/security diff、建议语义和最终候选各做一次有界只读审阅。
+
+## 11. 明确不做
+
+- 不做项目/人员生产力评分、排行榜、跨用户 benchmark 或“哪个模型更强”结论。
+- 不自动修改模型、effort、prompt、代码、CLAUDE.md、设置、issue 或 PR。
+- 不后台调用 AI，不根据额度充足自动发送，不把一次同意扩展为永久授权。
+- 不保存完整项目对话语料，不把 raw prompt/response 变成第二套索引。
+- 不把 GitHub 连接、同步、公开分享或社区数据作为本功能前置。
+
+## 12. 下一次启动条件
+
+只有以下前置全部满足时才建议创建实现 Goal：
+
+1. v2.3.1 已完成用户安装验证并确定发布/修订结论；
+2. X-06 项目用量矩阵已接入稳定线或其 snapshot contract 已冻结；
+3. v2.4.x comparison envelope 和本地反馈/清除语义可复用；
+4. 用户明确本轮只做到 `R0–R4`，还是同时授权 `R5` 的本机 Claude CLI 安全门；
+5. 数据契约、README/LOCAL-DATA 和清除清单计划与代码同版更新。
diff --git a/docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md b/docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md
new file mode 100644
index 00000000..684f0e98
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md
@@ -0,0 +1,178 @@
+# Claude Code Usage v2.3.1 Local Data Contract
+
+Status: normative v2.3.1 specification. Items marked **migration input** describe legacy storage that v2.3.1 must import or clear; they are not the desired final shape.
+
+This document is the source of truth for data read, retained, derived, displayed, exported, or sent by the extension. Any new persistent field must update this contract, its Chinese counterpart, migration and clearing logic, privacy tests, and the README privacy table in the same change.
+
+## 1. Non-negotiable rules
+
+1. All Section 6 local-data controls treat Claude and Codex logs as read-only source data and never delete or rewrite them. The separately opt-in Session Actions feature may move one user-selected Claude log to the OS trash only after its own exact modal confirmation; that recoverable source action is outside this clearing contract. Codex source logs are always read-only.
+2. Persistent caches contain bounded aggregates, cursors, pseudonymous relationships, and minimum quota observations—not copied conversations.
+3. Account identity is represented only by a stable, machine-local HMAC fingerprint. Email, display name, subscription name, raw account ID, credentials path, and reversible identifiers are forbidden.
+4. Different account fingerprints are never merged into an account-level fact. If account continuity cannot be established, observations stay in an isolated unattributed epoch. A coherent epoch may still support a clearly low-confidence local-history durability estimate, but never an official account balance or invented account split.
+5. Observations are facts; cost, full-quota, unused-quota, confidence, and heatmap intensity are recomputable derivatives.
+6. API keys use VS Code SecretStorage. OAuth tokens, cookies, API keys, authorization headers, and unfiltered CLI output never enter configuration, globalState, Webview state, logs, exports, or indexes.
+7. Network writes require an explicit user action and an exact preview of the destination and payload class. No background GitHub publication is permitted.
+8. Every persisted object has a schema version, bounded retention, an idempotent migration, corruption handling, and a user-visible clearing route.
+9. API-equivalent cost is an estimate at the current known API price, never a bill or a promise about subscription allowance.
+
+## 2. Data inventory
+
+| ID | Class and source | Persistent location | Allowed persisted fields | Retention / clearing | Remote interaction |
+|---|---|---|---|---|---|
+| R1 | Claude local JSONL | Source owned by Claude Code; extension cache is memory-only | Runtime token, model, date, project/session derivations; bounded prompt text only when content analysis is enabled | Source retention is controlled by Claude Code. Section 6 controls never touch R1. Separately opt-in Session Actions may move exactly one confirmed log to the OS trash (recoverable) | None by default. A separately consented advice request may include the exact previewed bounded sample |
+| R2 | Codex `sessions/**/*.jsonl` and `archived_sessions/**/*.jsonl` | Source owned by Codex; read-only | Runtime token, model, effort, timestamps, structural and lineage evidence | Source retention is controlled by Codex. Never delete R2 | None |
+| P1 | Codex incremental index derived from R2 | `globalStorageUri/codex-index-v1.json`, internal schema 3 at the v2.3.1 baseline | HMAC file keys, source area, size/mtime/inode, offsets, parser state, scan coverage, bounded numeric aggregates, sanitized relationship keys, normalized limits | Retained until rebuild, clear, uninstall, or schema replacement. `Clear local derived data` removes only this file and permits rebuild | None |
+| P2 | Unified quota observations derived from official provider observations | `globalStorageUri/quota-observations-v2.json`, schema 2; atomically replaced | Only fields in section 3 | Maximum 180 days and 512 retained observations per provider/account/period type after boundary-preserving compaction. Clear by provider/account epoch or all; an all-clear retains one valid empty canonical document and removes exact auxiliary recovery files | Claude observations originate from the Anthropic quota request; Codex observations originate from local structured log events |
+| P3 | Latest Claude quota response **migration input** | `ccu.usageLimits.<legacyProfileHash>` in globalState | Legacy response plus timestamp | v2.3.1 reads once, normalizes into P2, then removes it. No raw response is a long-term source of truth | No additional request |
+| P4 | Legacy Claude weekly history **migration input** | `ccu.weeklyQuotaHistory.v1.<legacyProfileHash>` in globalState | Legacy normalized observations | v2.3.1 imports, deduplicates into P2, then removes it | None |
+| P5 | Legacy Codex quota history **migration input** | `quotaHistory` inside P1 | provider, observed/reset time, used percent | v2.3.1 normalizes into schema 2 without inventing an account. Rebuilding P1 must not erase already migrated P2 history | None |
+| P6 | Extension preferences and migration flags | Exact catalogued `ccu.setting.<key>` names, `ccu.lastSeenVersion`, `ccu.codex.backgroundWork.v1`, migration flags, and `ccu.localData.pendingClientReset.v1` in globalState; language and data directories in VS Code configuration | Typed preferences, bounded worker status, schema/migration flags, or one value-free pending client action enum | Preferences remain until reset/clear/uninstall; the pending action remains only until a verified Webview acknowledgement or Clear All | Settings Sync may sync VS Code configuration according to the user's VS Code account; extension globalState is not intentionally uploaded by this extension |
+| P7 | Machine-local pseudonymization material | `ccu.codex.machineSalt` plus versioned local fingerprint salt | Random secret salt and algorithm version only | Until all derived data is cleared. Clearing it invalidates old fingerprints rather than relinking them | Never |
+| P8 | BYOK advice credential | `claudeCodeUsage.secret.advice.apiKey` in VS Code SecretStorage | Secret value only | Until the user clears the key or extension data. VS Code documents SecretStorage as encrypted and not synchronized across machines; the concrete protection mechanism remains host-dependent | Sent only as an authorization credential to the user-configured endpoint after a separate Send action; never included in request body or preview |
+| P9 | Advice-effectiveness ledger | `ccu.adviceEffectiveness.localState`, schema 3; legacy feedback key may exist | Consent mode, feedback, suppression records, comparable-pair metrics and results; no prompt body/path/account | Bounded by implementation (feedback/suppression 500, pairs/results 200). Clear Advice Data removes current and known legacy keys | Advice payload is sent only after preview and explicit Send |
+| P10 | Webview preferences | Webview state and localStorage keys `ccu.activeTab`, `ccu.sessionFilter`, `ccu.sessionRange`, `ccu.sessionModel` | Tab, sort/filter/range, expanded state, scroll and chart selection | Until Reset UI State, Webview storage clear, or uninstall | Never |
+| P11 | Heatmap/share preferences | `showHeatmap`, share-card settings, Webview localStorage `ccu.combinedHeatmap.title`, `ccu.combinedHeatmap.range`, `ccu.combinedHeatmap.intensityMode`, `ccu.combinedHeatmap.privacyPreview`, `ccu.combinedHeatmap.palette`, `ccu.combinedHeatmap.customAccent`, plus globalState `ccu.heatmapRepo` and `ccu.heatmapPath` | Bounded title (80 characters), range/intensity/palette enums, privacy-preview boolean, validated six-digit hex accent, and optional GitHub `owner/repo/path` destination strings | Until Reset Sharing Preferences, Webview storage clear, or all derived data clear | Local SVG/Markdown export has none. Direct publication is public-repository-only in v2.3.1, requires an exact destination confirmation every time, and never caches GitHub credentials |
+| M1 | Runtime-only Claude/Codex views | Extension-host memory | Records, prepared aggregates, charts, current session mappings, bounded content sample | Released on reload/exit | None unless included in a separately previewed request/export |
+| M2 | Runtime credentials and network responses | Extension-host memory or provider-owned credential store | OAuth access/refresh token, transient headers, response/error object | Never retained by this extension. Provider refresh may update the provider-owned credential store | Anthropic OAuth/quota endpoint or user-configured advice endpoint only |
+
+The extension must never persist raw prompt/response text, tool arguments, command text, thread titles, project names, repository remotes, absolute source-log paths, full account identifiers, OAuth tokens, cookies, API keys outside SecretStorage, or unfiltered Claude CLI output.
+
+Codex thread titles read from the exact `session_index.jsonl` mapping remain
+runtime-only. Before a title reaches dashboard text, tooltips, diagnostics, or
+an export boundary, absolute paths must be masked even when they are attached
+directly to punctuation such as `3:/Users/name` or `:/etc/file`; surrounding
+non-path text may remain visible.
+
+## 3. Quota observation schema
+
+P2 is an atomically written document:
+
+```ts
+interface QuotaObservationStoreV2 {
+  schemaVersion: 2;
+  fingerprintAlgorithm: 'hmac-sha256-v1';
+  observations: QuotaObservationV2[];
+}
+
+interface QuotaObservationV2 {
+  schemaVersion: 2;
+  provider: 'claude' | 'codex';
+  accountFingerprint: string; // machine-local HMAC or isolated unattributed epoch
+  accountAttribution: 'verified-local-signal' | 'profile-continuity' | 'unattributed';
+  observedAt: number;         // Unix milliseconds when the observation was received
+  periodType: 'five-hour' | 'seven-day' | 'provider-scoped-seven-day';
+  usedFraction: number;       // finite 0..1
+  remainingFraction: number;  // finite 0..1, normalized with usedFraction
+  resetAt: number | null;     // Unix milliseconds from structured evidence when available
+  source: 'claude-official-api' | 'codex-local-structured-event';
+  windowId: string;           // HMAC(provider, fingerprint, period, reset identity/epoch)
+  providerWindowFingerprint: string | null; // HMAC of a known provider window ID; never the raw ID
+  confidence: 'high' | 'medium' | 'low';
+  captureReason: 'refresh' | 'reset-at-change' | 'window-id-change' | 'usage-drop' | 'profile-change' | 'migration';
+  flags: Array<'approximate-boundary' | 'low-log-coverage' | 'low-price-coverage' | 'account-ambiguous' | 'clock-anomaly'>;
+}
+```
+
+### 3.1 Fingerprints and account isolation
+
+- A fingerprint is `HMAC(machineSalt, provider + stableLocalIdentitySignal + algorithmVersion)`. The raw identity signal is discarded immediately.
+- A filesystem path alone identifies a local profile, not a verified account. Such observations use `profile-continuity` and cannot be merged after a detected profile/login change.
+- If Codex exposes no safe stable identity signal, generate a random unattributed epoch. Never label a Codex home hash as an account. Window changes, `resetAt` changes, implausible percentage rollback, or explicit profile changes close the epoch.
+- Only identical fingerprints and compatible attribution may be robustly aggregated. `unattributed` epochs never merge with one another, even when reset times coincide.
+- Persistent account, provider-window, and window HMACs never enter Webview state or exports. Host projections replace them with invocation-local aliases before rendering.
+
+### 3.2 Validation, deduplication, and atomicity
+
+- Reject non-finite times/fractions, impossible period types, observations from the far future, and unknown free-form fields.
+- Normalize fractions to 0..1 only when the source semantics are known; do not silently reinterpret arbitrary values.
+- Deduplication key: `provider + accountFingerprint + periodType + windowId + observedAt + usedFraction + resetAt + source` after timestamp normalization. Exact duplicates are removed.
+- Semantically unchanged polls within a short interval may compact, but each window retains first, last, pre-reset, post-reset, and anomaly observations.
+- Write a sanitized temporary file in the same directory, flush and close it, then atomically rename it over the canonical file. A failed write leaves the prior valid file intact.
+- Corrupt or future-schema files are quarantined with a bounded diagnostic name; no raw contents enter logs. Rebuild or migration never overwrites the only recoverable source before validation succeeds.
+- A scoped provider/account clear refuses to mutate P2 when quarantined, interrupted-write, or unresolved legacy evidence cannot be attributed safely. An explicitly confirmed all-clear holds one cross-process lease, installs one valid empty canonical P2 document, and removes only exact P2 auxiliary filenames before releasing the lease; this prevents a later appender from being erased by a second delete phase.
+
+### 3.3 Reset events and derived estimates
+
+A reset/window boundary is detected from, in priority order: a stable provider window identifier change, `resetAt` identity change, or a significant used-fraction rollback that exceeds the configured noise tolerance. Multiple boundaries on the same day are retained as separate events. Reset events are deterministic runtime projections of boundary observations, not a second persisted fact table. Event timestamps split usage when available; day-only aggregates are explicitly approximate.
+
+For each valid observation in one stable fingerprint/window:
+
+```text
+candidateFullEquivalent = pricedUsedEquivalentThroughObservedAt / usedFraction
+```
+
+Candidates require `0 < usedFraction <= 1`. They are robustly aggregated with weights for price coverage, log/index coverage, time-boundary quality, account attribution, and observation recency. The displayed total is never below final confirmed used equivalent. Whenever one coherent window produces a valid total, the dashboard also shows `max(full - confirmedUsed, 0)` for completed and in-progress windows, except when usage recorded after the latest observation has already overrun that observation-derived candidate; in that stale-observation case the total remains a low-confidence lower bound and unused value is withheld rather than presenting a false `$0`. Unattributed, boundary-approximate, partially priced, or locally multi-sign-in evidence remains visible but is forced to low confidence and described as a local-history durability estimate—not an official account balance. Actually overlapping quota series or competing mapped epochs still fall back to used equivalent only; no account split is invented.
+
+Full/unused estimates are not persisted facts. They are recomputed when pricing, coverage, logs, or observation evidence changes.
+
+## 4. Aggregation and combined heatmap semantics
+
+All date keys use the configured data timezone. “Last 30 days” means today plus the previous 29 calendar dates in that timezone. Daily, monthly, weekly, model, effort, and grand totals must reconcile; repeated refresh/reindex must be idempotent.
+
+The v2.3.1 combined heatmap reuses provider daily aggregates and must not rescan source logs or create a second statistics cache.
+
+The share renderer defaults to the curated `academicViolet` palette and quantile intensity bands so isolated peaks do not flatten ordinary active days. Users may retain one of the curated palette IDs or a validated custom hex accent in P11; colors are rendering preferences, not usage facts.
+
+```text
+Claude processed = input + cache_creation + cache_read + output
+Codex processed  = input_total + output_total
+Combined activity volume = Claude processed + Codex processed
+```
+
+Codex cached input is already included in `input_total`; reasoning is already included in `output_total`. Neither is added twice. The combined number is a local activity volume only—not productivity, billable usage, model capability, or provider equivalence. The tooltip always exposes both provider components. Cost may be an optional view only with price-coverage disclosure.
+
+Provider daily inputs are already deduplicated aggregates. If an identical provider/date row is nevertheless repeated at the share boundary, it is treated idempotently; conflicting values for the same provider/date fail closed and block export rather than being added together. Missing calendar dates render as zero without creating persisted facts. The activity series is bounded to 370 Codex day rows—one complete share-card year plus a boundary margin—and is reused directly from the existing provider view.
+
+## 5. Exports, sharing, and network boundaries
+
+- Deterministic local SVG and Markdown snippets may contain only selected date range, title, normalized daily aggregates, provider labels, totals, and explicit caveats.
+- Export/share payloads must pass privacy-canary tests proving absence of account IDs, fingerprints, project/thread names, repository names, local paths, prompt/log text, and credentials.
+- Optional GitHub owner/repo/path preferences are destinations, not credentials. GitHub authentication remains transient in the VS Code authentication provider. v2.3.1 requests only `public_repo`, verifies public visibility and the default branch, previews the exact owner/repo/branch/path and create-or-overwrite action, and persists destination strings only after a successful confirmed write. Private repositories use local SVG + Markdown instead of silently escalating to broad `repo` access.
+- v2.3.1 release validation uses mocked GitHub publication only. No Goal step may write to a real repository.
+- AI advice requires exact request preview and a separate Send action. Quota tracking sends no local logs. Pricing refresh sends no user usage.
+
+## 6. User controls
+
+By G6, the Settings/Data surface and command palette must expose:
+
+1. View local data inventory: category, location class (not a sensitive absolute path), schema, approximate size/count, oldest/newest timestamp, and possible network interaction.
+2. Clear Codex derived index and rebuild it without touching source logs.
+3. Clear quota observation history by provider/account epoch or all; this is irreversible but does not alter provider quotas.
+4. Clear advice ledger/current and known legacy keys without clearing external accounts.
+5. Reset UI state and sharing preferences independently.
+6. Clear the BYOK secret from SecretStorage.
+7. Clear all extension-derived data only after listing exact targets; source Claude/Codex logs and provider-owned credentials are always excluded.
+
+Uninstall behavior is disclosed rather than assumed: VS Code may retain extension global storage until it is removed by the host/user, so the explicit clear command is the reliable deletion route.
+
+Configuration clearing covers Global, the current Workspace, and every
+currently open Workspace Folder scope. VS Code does not expose configuration
+belonging only to a closed workspace; such a legacy value remains in that
+workspace's settings file until the workspace is opened and the control is run
+there (or the user removes it directly). The inventory and confirmation state
+this host limitation instead of claiming that an unseen workspace was cleared.
+
+Clear All is an exact-catalog operation: it removes only currently owned and
+known retired names plus the two versioned legacy quota prefixes. It never
+deletes an unknown/future `ccu.setting.*` key. Before any mutation, all visible
+configuration scopes are preflighted. If a legacy key is present but is no
+longer registered with VS Code and therefore cannot be safely updated, the
+whole operation stops without deleting host state or secrets and reports the
+exact key for manual removal. Activation-time owned writes are drained before
+deletion, and exact global-state/file/P2 postconditions are checked afterward.
+
+Webview-owned state is cleared only after an exact allowlist operation returns
+a truthful acknowledgement. The host stores only a value-free pending client
+action before requesting the reset; failure, timeout, or panel disposal leaves
+that marker for idempotent replay on the next panel open. A verified
+acknowledgement removes it.
+
+## 7. Migration and release gates
+
+- Migration order: load and validate current schema; migrate legacy quota/config values into a new temporary document; validate invariants; atomically install it; only then delete legacy plaintext/duplicate state. The P1 migration-complete marker is written only after P1 was read successfully and every resulting P2 observation was durably appended; a read/write failure remains retryable on the next activation.
+- Secret migration writes SecretStorage first, then removes all explicit Global, current Workspace, every open Workspace Folder, and old globalState value. Every closed workspace is inspected when it is next opened. A workspace-only or conflicting key is never silently promoted into the one global secret slot: activation stops with fixed, localized recovery instructions and leaves plaintext recoverable. Until the user removes or reconciles that blocked legacy workspace value, it remains ordinary configuration and may remain eligible for Settings Sync. Repeat/concurrent machine-wide migration is idempotent because only identical global candidates are automatic. Other failures likewise preserve the legacy value and stop activation rather than pretending migration succeeded.
+- [VS Code's extension storage documentation](https://code.visualstudio.com/api/extension-capabilities/common-capabilities#data-storage) states that SecretStorage is encrypted and is not synchronized across machines. The extension relies on the active VS Code-compatible host's SecretStorage implementation, whose concrete backing protection can vary by host. Ordinary VS Code configuration can still participate in Settings Sync according to the user's VS Code settings.
+- Unknown reasoning effort is retained only when the field is missing or unrecognized. Non-zero unknown is visible and explained; zero unknown is omitted. Effort components reconcile with provider totals.
+- Tests must cover old/current/future schema, duplicate observations, corruption, consecutive and same-day resets, rollback noise, account/profile changes, low price/log coverage, timezone boundaries, deterministic/private exports, and clear-data exclusion of source logs.
+- G1, G3, G4B, and G5 require the specified read-only Claude CLI checkpoint. A passing review does not replace local tests or the main agent's acceptance decision.
diff --git a/docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md b/docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md
new file mode 100644
index 00000000..88330826
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md
@@ -0,0 +1,167 @@
+# Claude Code Usage v2.3.1 本地数据契约
+
+状态：v2.3.1 规范性说明。标记为 **迁移输入** 的项目描述旧版存储，只能用于迁移或清除，不是最终目标结构。
+
+本文件是插件读取、保留、派生、展示、导出或发送数据的事实来源。任何新增持久字段，都必须在同一变更中更新本文件、英文版、迁移与清除逻辑、隐私测试和 README 隐私表。
+
+## 1. 不可放宽的原则
+
+1. 本文件第 6 节的所有本地数据控制都把 Claude/Codex 日志视为只读源，绝不删除或改写。另行选择启用的“会话操作”可在用户针对单个 Claude 日志完成精确模态确认后，将它移入系统回收站（可恢复）；该源文件动作不属于本清除契约。Codex 源日志始终只读。
+2. 持久缓存只保存有界聚合、游标、匿名关系和最小额度观测，不复制完整会话。
+3. 账号只能表示为本机稳定的 HMAC 匿名 fingerprint。禁止保存邮箱、显示名、订阅名、原始账号 ID、凭证路径或可逆身份标识。
+4. 不同 fingerprint 的观测绝不合并为账号级事实。无法证明账号连续性时，观测进入隔离的未归属 epoch；内部一致的 epoch 仍可支持明确标为低可信度的“本地历史耐用度估算”，但绝不能冒充官方账号余额或虚构账号拆分。
+5. 官方百分比和重置时间是观测事实；成本、总周额度、未用额度、可信度和热力图强度均为可重算派生值。
+6. API key 只能进入 VS Code SecretStorage。OAuth token、cookie、API key、Authorization header 和未经筛选的 CLI 输出不得进入 configuration、globalState、Webview 状态、日志、导出或索引。
+7. 远程写入必须由用户明确触发，并预览精确目标和载荷类别；禁止后台发布 GitHub 内容。
+8. 每个持久对象都要有 schema 版本、有界保留期、幂等迁移、损坏处理和用户可见的清除入口。
+9. API 等效成本只是按当前已知单价计算的估算，不是账单，也不是官方订阅额度承诺。
+
+## 2. 本地数据清单
+
+| ID | 数据类别与来源 | 持久位置 | 允许持久化的字段 | 保留与清除 | 远程交互 |
+|---|---|---|---|---|---|
+| R1 | Claude 本机 JSONL | Claude Code 自有源文件；插件聚合主要在内存 | 运行期 token、模型、日期、项目/会话派生信息；仅内容分析开启时使用有界 prompt 文本 | 源文件保留由 Claude Code 控制；第 6 节控制绝不触碰 R1。另行启用的“会话操作”可把一个已精确确认的日志移入系统回收站（可恢复） | 默认无。只有用户单独同意并确认 AI 建议请求时，才可能发送精确预览中的有界样本 |
+| R2 | Codex `sessions/**/*.jsonl` 与 `archived_sessions/**/*.jsonl` | Codex 自有源文件，只读 | 运行期 token、模型、effort、时间、结构和 lineage 证据 | 源文件保留由 Codex 控制；插件绝不删除 R2 | 无 |
+| P1 | R2 派生的 Codex 增量索引 | `globalStorageUri/codex-index-v1.json`；v2.3.1 基线内部 schema 3 | HMAC fileKey、来源区、size/mtime/inode、offset、解析器状态、扫描覆盖、有界数值聚合、清洗后的关系键和规范化 limit | 保留到重建、显式清除、卸载或 schema 替换；“清除本地派生数据”只删除此文件并允许重建 | 无 |
+| P2 | 官方观测派生的统一额度历史 | `globalStorageUri/quota-observations-v2.json`，schema 2，原子替换 | 仅第 3 节定义字段 | 每个 provider/account/周期类型最多保留 180 天、512 条；压缩时保留窗口边界。可按 provider/account epoch 或全部清除；全部清除后保留一个合法空 canonical 文档，并移除精确匹配的辅助恢复文件 | Claude 来源为 Anthropic 额度请求；Codex 来源为本机结构化日志事件 |
+| P3 | 最新 Claude 额度 response **迁移输入** | globalState `ccu.usageLimits.<legacyProfileHash>` | 旧版 response 与时间戳 | v2.3.1 读取一次并规范化到 P2，成功后删除；完整 response 不再作为长期事实 | 不新增请求 |
+| P4 | Claude 周额度历史 **迁移输入** | globalState `ccu.weeklyQuotaHistory.v1.<legacyProfileHash>` | 旧版规范化观测 | 导入 P2、去重后删除 | 无 |
+| P5 | Codex 旧额度历史 **迁移输入** | P1 内 `quotaHistory` | provider、观测/重置时间、已用百分比 | 迁移为 schema 2，不虚构账号；重建 P1 不得抹掉已迁移 P2 历史 | 无 |
+| P6 | 插件设置与迁移标记 | globalState 中精确列入清单的 `ccu.setting.<key>`、`ccu.lastSeenVersion`、`ccu.codex.backgroundWork.v1`、迁移 flag 与 `ccu.localData.pendingClientReset.v1`；语言和数据目录在 VS Code configuration | 类型化偏好、有界后台任务状态、schema/迁移标记，或一个不含数据值的待执行客户端动作枚举 | 偏好保留到重置/清除/卸载；待执行动作只保留到 Webview 验证确认或清除全部 | VS Code configuration 可能按用户的 VS Code 账号设置参与 Settings Sync；插件自身不主动上传 globalState |
+| P7 | 本机匿名化材料 | `ccu.codex.machineSalt` 与带版本的 fingerprint salt | 随机盐和算法版本 | 保留到清除全部派生数据；清除后旧 fingerprint 失效，不跨盐重连 | 永不外发 |
+| P8 | AI 建议 BYOK 凭证 | VS Code SecretStorage 的 `claudeCodeUsage.secret.advice.apiKey` | secret 值本身 | 用户清除 key 或清除插件数据前保留；VS Code 官方说明 SecretStorage 会加密且不跨设备同步，具体保护机制仍取决于宿主实现 | 只有用户预览后再次点击 Send，才作为授权凭证发送给用户配置的 endpoint；不进入请求正文或预览 |
+| P9 | 建议效果账本 | `ccu.adviceEffectiveness.localState` schema 3；可能仍有旧 feedback key | consent 模式、反馈、抑制记录、可比较任务指标和结果；无 prompt/path/account | 实现上限：反馈/抑制约 500，对与结果约 200；“清除建议数据”同时删除当前键和已知旧键 | 请求只有在预览后显式 Send 才外发 |
+| P10 | Webview 偏好 | Webview state 与 localStorage：`ccu.activeTab`、`ccu.sessionFilter`、`ccu.sessionRange`、`ccu.sessionModel` | tab、排序/筛选/范围、展开状态、滚动和图表选择 | 直到重置 UI、清除 Webview 存储或卸载 | 无 |
+| P11 | 热力图/分享偏好 | `showHeatmap`、share-card 设置、Webview localStorage `ccu.combinedHeatmap.title`、`ccu.combinedHeatmap.range`、`ccu.combinedHeatmap.intensityMode`、`ccu.combinedHeatmap.privacyPreview`、`ccu.combinedHeatmap.palette`、`ccu.combinedHeatmap.customAccent`，以及 globalState `ccu.heatmapRepo`、`ccu.heatmapPath` | 有界标题（80 字符）、范围/色阶/配色枚举、隐私预览布尔值、经校验的六位十六进制主色，以及可选 GitHub `owner/repo/path` 目的地字符串 | 直到重置分享偏好、清除 Webview 存储或清除全部派生数据 | 本地 SVG/Markdown 导出不联网。v2.3.1 直发只支持公开仓库，每次均须精确确认目标，且绝不缓存 GitHub 凭证 |
+| M1 | Claude/Codex 运行期视图 | Extension Host 内存 | records、prepared aggregate、图表、当前会话映射和有界内容样本 | reload/退出即释放 | 除非进入单独预览并确认的请求/导出，否则无 |
+| M2 | 运行期凭证和网络 response | Extension Host 内存或 provider 自有凭证存储 | OAuth access/refresh token、临时 header、response/error object | 插件绝不长期保留；provider 刷新流程可能更新其自有凭证存储 | 仅 Anthropic OAuth/额度端点或用户配置的建议端点 |
+
+插件绝不能持久化原始 prompt/response、tool arguments、命令文本、线程标题、项目名、repo remote、源日志绝对路径、完整账号标识、OAuth token、cookie、SecretStorage 之外的 API key，或未过滤的 Claude CLI 输出。
+
+从精确 `session_index.jsonl` 映射读取的 Codex 线程标题只能留在运行期内存。在线程标题进入仪表盘文本、tooltip、诊断或导出边界前，必须脱敏其中的绝对路径；即使路径紧贴冒号或其他标点（例如 `3:/Users/name`、`:/etc/file`），也不能漏出本机用户名或文件位置，路径之外的普通文本可以保留。
+
+## 3. 额度观测 schema
+
+P2 是原子写入的文档：
+
+```ts
+interface QuotaObservationStoreV2 {
+  schemaVersion: 2;
+  fingerprintAlgorithm: 'hmac-sha256-v1';
+  observations: QuotaObservationV2[];
+}
+
+interface QuotaObservationV2 {
+  schemaVersion: 2;
+  provider: 'claude' | 'codex';
+  accountFingerprint: string; // 本机 HMAC 或隔离的未归属 epoch
+  accountAttribution: 'verified-local-signal' | 'profile-continuity' | 'unattributed';
+  observedAt: number;         // Unix 毫秒
+  periodType: 'five-hour' | 'seven-day' | 'provider-scoped-seven-day';
+  usedFraction: number;       // 有限数，0..1
+  remainingFraction: number;  // 有限数，0..1，与 usedFraction 规范化一致
+  resetAt: number | null;
+  source: 'claude-official-api' | 'codex-local-structured-event';
+  windowId: string;           // HMAC(provider, fingerprint, period, reset identity/epoch)
+  providerWindowFingerprint: string | null; // 已知 provider window ID 的 HMAC，绝不保存原值
+  confidence: 'high' | 'medium' | 'low';
+  captureReason: 'refresh' | 'reset-at-change' | 'window-id-change' | 'usage-drop' | 'profile-change' | 'migration';
+  flags: Array<'approximate-boundary' | 'low-log-coverage' | 'low-price-coverage' | 'account-ambiguous' | 'clock-anomaly'>;
+}
+```
+
+### 3.1 Fingerprint 与账号隔离
+
+- fingerprint 采用 `HMAC(machineSalt, provider + stableLocalIdentitySignal + algorithmVersion)`；原始 identity signal 立即丢弃。
+- 文件路径只能说明本机 profile，不能证明真实账号。此类观测标为 `profile-continuity`，检测到登录/profile 改变后不得继续合并。
+- Codex 若没有安全稳定的账号信号，就生成随机 `unattributed` epoch，绝不能把 Codex home hash 冒充账号。窗口变化、`resetAt` 变化、明显百分比回落或显式 profile 变化都会关闭 epoch。
+- 只有 fingerprint 相同且 attribution 兼容的观测才能稳健聚合。不同 `unattributed` epoch 即使 reset 时间相同也绝不合并。
+- 持久化的账号、provider window 与 window HMAC 不得进入 Webview 状态或导出；宿主在渲染前必须替换为仅对本次投影有效的临时别名。
+
+### 3.2 校验、去重和原子写入
+
+- 拒绝非有限时间/比例、非法周期、明显未来时间和未知自由字段。
+- 只有确认来源语义时才把比例规范化为 0..1，不能静默猜测任意数值。
+- 去重键：规范化后的 `provider + accountFingerprint + periodType + windowId + observedAt + usedFraction + resetAt + source`。
+- 短时间内语义不变的轮询可以压缩，但每个窗口必须保留首条、末条、reset 前后及异常观测。
+- 在同一目录写入清洗后的临时文件，flush/close 后原子 rename 覆盖 canonical 文件；失败时旧文件保持有效。
+- 损坏或未来 schema 文件使用有界诊断名隔离，原文不得进入日志；迁移验证成功前不得覆盖唯一可恢复版本。
+- 当隔离文件、中断写入文件或未完成旧迁移无法安全归属时，按 provider/账号的范围清除必须拒绝修改 P2。明确确认的全部清除在同一个跨进程 lease 内安装一个合法空 canonical P2 文档，并只移除精确匹配的 P2 辅助文件后才释放 lease，避免后续 appender 被第二阶段删除误伤。
+
+### 3.3 重置事件与派生估算
+
+重置/窗口边界按以下优先级判断：稳定 window ID 改变、`resetAt` identity 改变、超过噪声阈值的 used fraction 回落。同一天多次重置必须分别保留。重置事件由边界观测在运行期确定性派生，不另建第二张持久事实表。有事件时间戳时按事件切分；只有日汇总时明确标记近似。
+
+同一稳定 fingerprint/window 内，每个有效观测产生候选：
+
+```text
+candidateFullEquivalent = pricedUsedEquivalentThroughObservedAt / usedFraction
+```
+
+只接受 `0 < usedFraction <= 1`。多个候选按定价覆盖、日志/索引覆盖、边界质量、账号归属和时效做稳健聚合。展示的总额度不得低于最终确认的已用等价值。只要一个内部一致的窗口能产生有效总额，已结束和进行中的窗口都显示 `max(full - confirmedUsed, 0)`；但如果最后一次观测之后新增的日志已超过该观测推导出的候选总额，则把总额保留为低可信度下界，并暂不显示未用值，避免伪造 `$0`。未归属、边界近似、低定价覆盖或本地多登录证据仍可展示，但必须强制为低可信度，并明确称为“本地历史耐用度估算”，而非官方账号余额。真正重叠的额度系列或竞争性的映射 epoch 仍只显示已用等价值，不虚构账号拆分。
+
+总额/未用估算不作为永久事实落盘；单价、覆盖、日志或观测变化后重新计算。
+
+## 4. 聚合与综合热力图语义
+
+所有日期键都使用用户配置的数据时区。“最近 30 天”定义为该时区下今天及此前 29 个自然日期。日/月/周/模型/effort/总计必须守恒；重复刷新或重建索引必须幂等。
+
+v2.3.1 综合热力图复用 provider 日汇总，不重复扫描源日志，也不新增第二套统计缓存。
+
+分享渲染默认使用精选 `academicViolet` 配色和分位数强度分档，避免极少数峰值把普通活跃日压成同一浅色。用户可以在 P11 中保留精选配色 ID 或经校验的自定义十六进制主色；颜色只是渲染偏好，不是用量事实。
+
+```text
+Claude processed = input + cache_creation + cache_read + output
+Codex processed  = input_total + output_total
+综合活动量 = Claude processed + Codex processed
+```
+
+Codex cached input 已包含在 `input_total`，reasoning 已包含在 `output_total`，都不得重复相加。综合值只表示本机活动量，不代表生产率、账单、模型能力或 provider 等价。tooltip 必须分别展示两端构成。成本只能是可选视图，并披露定价覆盖率。
+
+Provider 日输入本身已经去重。如果分享边界仍收到同一 provider/date 的完全相同记录，则按幂等重复处理；同一 provider/date 数值冲突时必须失败关闭并阻止导出，不能求和放大。缺失自然日仅在渲染时补零，不生成持久事实。Codex 活动序列最多保留 370 个日行——完整一年加少量边界余量——并直接复用既有 provider view。
+
+## 5. 导出、分享和网络边界
+
+- 确定性本地 SVG 与 Markdown 片段只能包含所选日期范围、标题、规范化日聚合、provider 标签、总计和明确限制说明。
+- 导出/分享必须通过隐私 canary 测试，确保不存在账号 ID/fingerprint、项目/线程名、repo 名、本地路径、prompt/log 文本或凭证。
+- GitHub owner/repo/path 是目的地偏好，不是凭证；GitHub 登录只临时使用 VS Code authentication provider。v2.3.1 只请求 `public_repo`，验证仓库为公开、核实默认分支，写入前预览精确 owner/repo/branch/path 以及创建或覆盖动作，并仅在确认写入成功后保存目的地字符串。私有仓库使用本地 SVG + Markdown，不静默升级到宽泛 `repo` 权限。
+- v2.3.1 的发布验证只允许 mock GitHub publish；Goal 全程不得写入真实仓库。
+- AI 建议必须先给出精确请求预览，再单独点击 Send；额度跟踪不发送本地日志；价格刷新不发送用户用量。
+
+## 6. 用户数据控制
+
+G6 前，设置/Data 页面和命令面板应提供：
+
+1. 查看本地数据清单：类别、非敏感位置类别、schema、近似大小/条数、最早/最新时间和可能的网络交互。
+2. 清除 Codex 派生索引并重建，不触碰源日志。
+3. 按 provider/account epoch 或全部清除额度历史；该操作不可恢复，但不会改变官方额度。
+4. 清除当前及已知旧版建议账本，不影响外部账号。
+5. 分别重置 UI 状态和分享偏好。
+6. 从 SecretStorage 清除 BYOK key。
+7. “清除全部插件派生数据”执行前列出精确目标；Claude/Codex 源日志和 provider 自有凭证永远排除。
+
+不能假定卸载一定删除 VS Code global storage；README 应披露这一点，显式清除命令才是可靠删除路径。
+
+配置清除覆盖 Global、当前 Workspace 和所有当前已打开的 Workspace Folder 作用域。
+VS Code 不会暴露只属于关闭工作区的配置；这类旧值会继续留在该工作区的 settings
+文件中，直到打开该工作区后再次运行清除控制（或由用户直接删除）。清单和确认界面
+必须披露这一宿主限制，不能声称已清除不可见工作区。
+
+“清除全部”只处理当前拥有的精确名称、已知退役名称和两类带版本的旧额度前缀，绝不
+泛删未知/未来 `ccu.setting.*`。任何修改前先预检所有可见配置作用域；若某旧 key 已不
+再向 VS Code 注册、因而不能安全更新，整个操作必须在删除 host state/secret 之前停止，
+并给出精确 key 供用户手动清理。插件激活期的自有排队写入必须在删除前排空，删除后再
+验证 globalState、文件族及 P2 的精确后置条件。
+
+Webview 自有状态只有在精确白名单清除返回真实确认后才算完成。Host 会先保存一个不含
+数据值的待执行客户端动作；失败、超时或面板关闭时保留该 marker，并在下次打开面板时
+幂等重放；验证确认后才删除 marker。
+
+## 7. 迁移与发版门槛
+
+- 迁移顺序：加载并校验当前 schema；将旧额度/config 写入新临时文档；验证不变量；原子安装；最后删除旧明文或重复状态。只有成功读取 P1 且由此得到的 P2 观测均已持久追加后，才写入 P1 迁移完成标记；读取或写入失败时保留为下次激活可重试状态。
+- Secret 迁移先写 SecretStorage，再清除 Global、当前 Workspace、所有已打开 Workspace Folder 和旧 globalState 中的明文值；关闭的 workspace 会在下次打开时检查。workspace-only 或相互冲突的 key 不会静默提升为一个全局 secret：插件用固定、已本地化的恢复提示停止激活，并保留可恢复明文。在用户删除或协调该受阻的旧 workspace 值之前，它仍属于普通 configuration，因而仍可能参与 Settings Sync。机器级自动迁移只接受相同候选，因此重复/并发激活保持幂等。其他失败同样保留旧值并停止，不得假装迁移成功。
+- [VS Code 扩展存储官方说明](https://code.visualstudio.com/api/extension-capabilities/common-capabilities#data-storage)指出 SecretStorage 会加密且不跨设备同步；插件依赖当前 VS Code 兼容宿主的 SecretStorage 实现，而其具体底层保护方式可能因宿主而异。普通 VS Code configuration 仍可能按用户的 Settings Sync 设置同步。
+- `unknown` effort 只在字段缺失或无法识别时保留；非零时展示并解释，零时隐藏；各 effort 分量必须与 provider 总计守恒。
+- 测试覆盖旧/当前/未来 schema、重复观测、损坏、连续及同日重置、回落噪声、账号/profile 改变、低定价/日志覆盖、时区边界、确定性/隐私导出及清除数据不触碰源日志。
+- G1、G3、G4B、G5 执行指定的只读 Claude CLI 检查点。Claude 通过不替代本地测试和主代理的验收判断。
diff --git a/docs/superpowers/specs/2026-09-03-v2.3.2-overnight-review.md b/docs/superpowers/specs/2026-09-03-v2.3.2-overnight-review.md
new file mode 100644
index 00000000..f8760cd6
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-03-v2.3.2-overnight-review.md
@@ -0,0 +1,335 @@
+# Claude Code Usage v2.3.2 夜间审阅记录
+
+日期：2026-09-03（Asia/Shanghai）
+
+范围：仅在隔离 worktree `codex/v2.3.1-goal-g0-g6` 内审阅、修复与验证；不推送、不合并、不发布，也不操作远程 issue/PR。
+
+## 本轮结论
+
+### 中午审阅摘要（2026-09-03 11:40 CST 封板）
+
+**已完成。** 维护者点名的发布候选行为已经逐项落到实现或回归证据：Claude / Codex 柱状图可按日、小时下钻并在 Webview 重载后恢复；Codex 周额度状态栏显示余量、tooltip 以 Claude 同款进度条显示已用量；有可归属真实观测时展示 Codex 总额度与未用估算，无证据时不伪造；周额度周期详情默认折叠；Compare 分享工作台默认开启且可关闭，设置位于预览下方，支持分位数、对数、线性色阶；Codex Token 构成明确显示未缓存用量；插件设置页不再渲染“本地数据与隐私控制”。夜间另修复了路径脱敏、五语言分享文案、多个配置时区边界和 watcher 异步错误降级。
+
+**建议本次采纳。** 建议保留 `95b67f3` 至 `c120cad` 的全部源码/测试提交，并以当前候选包做维护者最终 spot check。它们都有先失败后通过的定向回归，且没有新增运行时依赖。Issue #94 的代码修复位于既有基线 `0614442`；发布 2.3.1 后用实际 OpenAI-compatible 请求核验一次，再附版本号关闭。当前上游仍是 2 个 open issue、0 个 open PR。
+
+**建议延期或保留边界。** 不把原 profile 中偶发的 Claude Today / 最近 30 天零值写成“已彻底修复”：隔离安装态的真实 watcher→增量索引→Webview 合成链已通过，但原环境根因仍未复现，中午只需核对 data root 选择、自动刷新/窗口活动状态和匿名 `refresh:` 诊断。旧 Claude Share Card 的整段八语言本地化、宿主时区月份选择器，以及两个分享入口是否收敛，放到 2.3.2 决策；Windows / Linux 安装态 VSIX 烟测也仍待补。Issue #91 多币种继续保持后续版本范围。
+
+**最终验证。** 11:10 CST 的完整 Node 套件为 925 通过、0 失败、1 跳过；完整 Playwright 为 124/124 通过。11:40 CST 再次完成 TypeScript 编译、`git diff --check`、文件模式/重命名检查、运行时依赖检查和 VSIX 清单校验；当前 `out/extension.js` 与候选 VSIX 内入口的 SHA-256 均为 `b36296acfe614395fb822773d8ad69dcbc4e30684645a1f5eceb0e6070976b61`。候选包仍为 107 文件、1,915,921 bytes，SHA-256 `238408bbe64f55992323a2371e986c374a997d0f21acb57655c081de17484818`。
+
+**Claude CLI。** 标准持久会话的可核对下限为 2,357 条 usage 事件（input 4,612、cache creation 8,222,142、cache read 136,893,633、output 1,572,231），另有一次已完成但 summary 丢失的续跑未计入；所有成功调用都保留会话并进入本地日志，未触发 Claude rate limit。随后三次请求均在进程创建前被权限审阅器拒绝，包括一次不附源码的脱敏 QA 请求；它们没有产生 usage。遵守明确限制后没有重试、变形或绕过，因此本夜没有人为“刷满”额度。
+
+**本地提交。** 相对 `0614442` 封板后共 19 个提交；最后一条就是承载本摘要的文档提交，全部使用规定的 OpenAI Codex trailer：
+
+1. `95b67f3 fix: harden Codex title path redaction`
+2. `c405fef fix: persist Claude chart drilldowns`
+3. `c0102ea fix: localize Share studio across supported locales`
+4. `1d4ba4e fix: align share ranges with configured timezone`
+5. `6c0641b fix: align attribution ranges with configured timezone`
+6. `3a03349 fix: align session ranges with configured timezone`
+7. `8efe716 fix: honor configured timezone in Claude date labels`
+8. `1491f10 fix: align workflow summary with rolling range`
+9. `99946f6 fix: stabilize chart date labels across timezones`
+10. `88d2dc3 fix: honor configured timezone in advice snooze dates`
+11. `75669df test: cover nested Claude usage refresh paths`
+12. `c120cad fix: fail soft on Claude watcher errors`
+13. `8c973a7 docs: record release package verification`
+14. `ec39741 docs: record installed VSIX smoke`
+15. `155fd52 docs: record focused UI release gates`
+16. `abd1a02 docs: record overnight release hygiene`
+17. `7bcc1cf docs: map maintainer release requirements`
+18. `fca1d16 docs: refresh release review snapshot`
+19. `docs: finalize noon release review`（本摘要提交）
+
+### 维护者本轮要求覆盖矩阵
+
+| 要求 | 当前候选状态 | 可核验证据 | 中午动作 |
+|:--|:--|:--|:--|
+| Claude 今日 / 近 30 天不能为零 | **安装态合成链通过，原环境偶发零值未复现** | 隔离 VSIX 中追加 1 条当日记录后，watcher 只尾读 418 bytes / 1 line；Today 与近 30 天立即出现精确同值 | 在原 profile 只核对 data root 选择与匿名 `refresh:` 诊断，不猜测性再改统计主链 |
+| Codex 显示未用额度估算 | **已实现，并保留真实性边界** | `weeklyValue.test.ts` 覆盖当前、已结束、重置和重叠窗口；有真实观测的当前窗口可显示低可信度总额/未用值，无法归属的已结束重叠窗口仍保持仅已用值 | 安装包中用维护者真实观测再看一次数值；不要把无证据的历史窗口填成假余额 |
+| 每周订阅额度周期详情默认折叠 | **已完成** | 生产 HTML 使用无 `open` 的 `<details class="weekly-value-details">`；隔离安装态辅助功能树确认默认只见“周期详情”摘要 | 无 |
+| 分享图下方放卡片设置，减少横向留白 | **已完成** | `combined-heatmap.spec.mjs` 实测 `settingsTop >= previewBottom`，并约束设置卡不宽于面板 | 无 |
+| 分享工作台默认开启、可关闭 | **已完成** | `enableShareCard` 默认 `true`；UI 测试确认关闭后只隐藏分享工作台，不移除 Compare 数据或周额度面板 | 无 |
+| “本地数据与隐私控制”不进入插件设置 | **已完成** | `local-data-controls.spec.mjs` 锁定设置页不渲染该面板，命令动作和 repo 文档仍保留 | 无 |
+| 热力图色阶可选分位数 / 对数 / 线性 | **已完成** | `combined-heatmap.spec.mjs` 覆盖默认 quantile、切换 logarithmic、重载持久化和导出消息；纯函数另覆盖 linear | 无 |
+| Codex Token 构成显示未缓存用量 | **已完成** | 汇总标题显示 `uncached input + output`，下方堆叠仍只含互斥的未缓存输入 / 缓存输入 / 输出，reasoning 继续标为输出子集 | 无 |
+| Codex 状态栏与 Claude 画风对齐 | **已完成** | `codexStatus.test.ts` 与 `statusBarThresholds.test.ts` 锁定短文本为今日用量、周文本为剩余百分比、tooltip 为已用百分比进度条；安装态显示 `CX 0` 与 `wk 26%` | 无 |
+| 点击柱状图按日 / 小时展开并在刷新后保留 | **已完成** | `codex-interactions.spec.mjs` 覆盖 Codex 日→小时、Claude 日→小时和月→日，均验证点击、ARIA、完整 reload 与恢复 | 无 |
+| 旧 Claude Share Card 与新分享工作台一致 | **建议延期到 2.3.2** | 安装态简中界面确认旧卡片整段仍为英语，月份选择器还依赖宿主时区；它与本轮已修好的 Compare 分享工作台是两个入口 | 先决定收敛为一个入口还是完整八语言修补，避免今天临时扩大 2.3.1 |
+
+### 已复现并修复：Codex 线程标题的路径脱敏边界
+
+Claude CLI 对 `src/providers/codex/codexIdentity.ts` 的标题清洗链路做了定向隐私审计，确认 POSIX 绝对路径在紧贴 ASCII 冒号或部分标点时可能绕过原有正则。例如：
+
+- `3:/Users/carl`
+- `3:/etc/passwd`
+- `:/etc/passwd`
+
+这些标题只在内存中使用，不会持久化或联网，但可能进入仪表盘和截图，因而仍违反“绝对路径不得展示”的隐私边界。
+
+处理方式：先加入上述三类回归样例，编译后的定向测试按预期失败；随后仅放宽路径前缀识别，不改变标题的其他清洗规则。修复后定向测试 15/15 通过。英文与中文本地数据契约同步补充了“路径紧贴标点也必须脱敏”的要求。
+
+### 已审计、无需修改：Codex 周额度状态栏语义
+
+Claude CLI 复核了状态栏、tooltip 和告警阈值的数据流：
+
+- 紧凑状态栏 `wk 64%` 表示“剩余 64%”，符合本轮产品要求。
+- tooltip 的进度条和标签显示“已用百分比”，与 Claude 的明细画风一致。
+- 告警颜色按已用百分比判断，避免把“剩余越多”错误视为风险。
+
+这是有测试和变更记录覆盖的刻意语义分工，不是本轮缺陷，因此没有为了表面一致而反转数据。
+
+### 已复现并修复：Claude 图表下钻在 Webview 重载后丢失
+
+Claude CLI 对 Claude/Codex 共用图表交互做定向审计，确认 Claude 的两条既有下钻路径没有进入 Webview 状态：
+
+- “最近 30 天”日柱展开到小时后，刷新/重载会收起。
+- “全部时间”月柱展开到每日后，刷新/重载会收起。
+- 相同场景下，Codex 的已物化日→小时路径已经能够恢复，形成 provider 间的不一致。
+
+先加入两个真实 Playwright 操作测试，均在完整 `page.reload()` 后检查行可见性、选中态、`aria-expanded` 和延迟详情数据请求。修复前两个测试按预期失败；修复后：
+
+- Claude 日→小时、月→日展开状态写入统一 Webview state，并在重载时恢复。
+- 恢复过程会重新请求 Claude 的延迟详情数据，但不自动滚动，之后仍由既有滚动恢复逻辑定位。
+- 用户主动切换 tab 时仍按既有规则清空展开状态。
+- 控件类型改由控件自身所在 tab 判定，不再依赖初始化瞬间的全局活动 tab；这同时修正了“全部时间”非活动 tab 柱状图初次初始化缺少 ARIA 绑定的边界。
+
+第二次 Claude CLI 只读复核认为当前 diff 没有受支持的阻塞缺陷，并确认 Codex 路径未被改变。它指出的非阻塞测试缺口——恢复后是否重新请求 Claude 的 `getHourlyData` / `getDailyData`——也已加入断言。
+
+### 已复现并修复：分享工作台在五种语言中静默回落英语
+
+三次 Claude CLI 定向审阅先后检查了设置简洁性、本地数据契约和分享工作台的语言覆盖，并通过第二次挑战审阅纠正了首轮的两个误判：
+
+- `CHANGELOG.md` 中“Usage Share Card 默认关闭”的文字位于已发布的 2.2.0 历史区段，记录的是当时行为，不应改写；当前 2.3.1 Unreleased 区段已经正确记录分享工作台默认开启。
+- `LocalDataUiCopy` / `renderLocalDataControls()` 虽仍保留为命令动作白名单的源码交叉检查，但已经不接入 `renderSettingsPanel()`；既有 Node 与 Playwright 测试明确锁定“插件设置页不渲染本地数据与隐私控制”。因此它的非英语副本缺口不是活动 UI 缺陷。
+- 真正活动的 `CombinedHeatmapUiCopy` 会进入 Compare 分享工作台、客户端预览状态和 SVG 文案；此前只有简体中文、繁体中文和英文完整，德语、日语、韩语、巴西葡萄牙语、印尼语除四个色阶标签外全部回落为英语。
+
+处理方式：先加入从 `CombinedHeatmapUiCopy` 接口推导字段清单的仓库覆盖测试，修复前稳定报告五个缺失 locale；随后补齐五种语言的 34 个活动字段，并在真实 Playwright 渲染中逐一验证八种语言的色阶标签和面板标题。配色名称沿用简繁中文已经采用的规则：保留 Claude、Codex、GitHub 品牌名，翻译颜色形容词。
+
+同时把 `LOCAL-DATA.md` 与 `LOCAL-DATA.zh-CN.md` 中容易让人误以为存在设置面板的“Data 设置提供控制”改为“命令面板提供维护动作”，明确这些动作不进入仪表盘设置页。`enableShareCard = true` 保持不变：这是维护者明确要求的默认行为；现有用户仍可用同一个设置开关隐藏全部分享 UI，导出始终需要显式操作。
+
+### 已审计、暂未复现：Claude 今日 / 最近 30 天数据显示为零
+
+Claude CLI 沿真实生产链路复核了 Claude 的文件发现、增量读取、去重、时区归档、文件监听和 Webview 刷新：
+
+- 顶层会话与嵌套 `subagents/**/*.jsonl` 都由递归发现覆盖；路径键与稳定文件身份共同防止重复计数。
+- 新增 CLI 记录可由增量游标读取，`Today` 与最近 30 天汇总最终都使用同一配置时区的自然日键。
+- 文件监听事件能够触发重新加载并把新 HTML 发送给现有 Webview。
+
+在当前代码和现有夹具中没有找到能把“昨日、今日均有真实 Claude CLI 使用”稳定变成两个零卡片的生产缺陷，因此本轮没有猜测性修改统计主链。后续已补入两项更接近生产路径的回归：第一项在真实临时目录创建顶层 transcript 与嵌套 `session/subagents/agent-*.jsonl`，证明冷索引会把两者分别计入 Today、最近 30 天、全部时间和 Sessions，未变化刷新零 body read，subagent 追加只读该文件尾部且不会重复累计；第二项直接驱动生产 `startFileWatching()` 注册的递归 watcher callback，证明嵌套 subagent `.jsonl` 会触发一次 `watch` refresh，而相邻 `.meta.json` 不会误触发。
+
+这两项测试均在旧代码上通过，因此进一步缩小了嫌疑范围，但仍没有复现维护者截图中的零值。第二项使用受控 watcher callback，不把它夸大为真实操作系统 `fs.watch` 一路到 Webview HTML 的端到端测试；该完整链路以及多候选 Claude data root 的自动选择仍是最有价值的后续诊断。
+
+后续独立深审仍未推翻这个结论，并按可能性整理了现有机制：历史记录证明 `--no-session-persistence` / `--bare` 会直接造成“CLI 有执行感但无本地 transcript”；`dashboardAutoRefresh=false` 会让非手动触发不推送 Webview，而状态栏仍可更新；窗口失焦会暂停轮询；符号链接项目目录会被安全遍历规则跳过。后三项都是代码中真实存在的机制，但没有证据证明命中维护者当时的环境。本夜所有 Claude CLI 调用都使用标准持久会话，因此新用量已进入本地日志。
+
+### 已复现并修复：Claude 文件监听的异步错误没有安全降级
+
+为补齐上一节留下的真实 `fs.watch` 缺口，本轮加入了从临时 Claude transcript、操作系统文件事件、manifest diff、增量索引到 Webview `updateData()` 的整链测试。受限测试宿主在注册递归 watcher 后异步返回 `EMFILE`；这暴露出一个独立的生产缺陷：原实现的 `try/catch` 只能捕获 `fs.watch()` 同步抛错，没有监听 `FSWatcher` 后续发出的 `error` 事件，因而资源耗尽或文件系统 watcher 故障可能逃逸到 Extension Host。
+
+处理方式先以独立红灯锁定：watcher 注册后必须存在异步错误处理，错误发生后要关闭真实 watcher、释放 ownership lease、清空当前监听目录，并保留轮询作为降级路径。修复只记录安全的错误码，不记录本地路径或文件名。随后保留整链测试：支持递归 watcher 的宿主会验证新增嵌套 subagent 文件把 Today 从 10 更新到 30，同时 manifest 与记录数都变为 2；无法分配 watcher 的受限宿主会明确跳过该能力测试，而专门的错误路径测试仍必须通过。
+
+该修复提高了实时刷新失败时的稳定性，但轮询本来就是后备路径，因此不能据此断言维护者截图中的 Claude Today / 最近 30 天零值已经被复现或完全解决。当前机器只检测到一个有效默认 Claude data root，且其最新 `.jsonl` 修改时间为 2026-09-03 06:16 CST；没有发现 `CLAUDE_CONFIG_DIR` 覆盖或第二个候选根目录，因此“误选旧 profile”在本机没有证据支持。
+
+### 已复现并修复：配置时区边界下热力图与分享范围偏移
+
+上述审计同时发现两个独立、可确定复现的日期边界问题，第二个 Claude 持久会话继续做了挑战审阅并确认均为活动生产路径：
+
+- Claude provider 自身的 Token 热力图调用 `renderHeatmapSvg(daily)` 时没有传配置时区中的“今天”，会回落到 UTC 日期；在 UTC 前后跨日时可能少一天或多一天。
+- Share Card 的 7 天、30 天和一年范围以固定毫秒数过滤，和产品其余部分的“配置时区自然日”口径不一致；UTC 边界附近会把相邻本地日错误纳入或排除。
+
+处理方式：先固定 `Pacific/Honolulu` 与 UTC 跨日样例，证明三个滚动范围都错误纳入相邻旧日，同时用源码契约锁定 provider 热力图缺少配置时区锚点；修复前定向套件 27 通过、2 失败。随后：
+
+- provider 热力图显式以配置时区的当前日作为结束日期；
+- 分享范围从固定毫秒阈值改为 7 / 30 / 365 个精确自然日键的集合，并注入可测试的 `now`；
+- `today` 与默认当前月也复用同一个 `now`，避免单次计算跨越时钟边界。
+
+修复后定向套件 29/29 通过。挑战审阅还指出 `getUsageAttribution` 的 week/month 仍使用固定毫秒窗口；后续一次独立审计确认了它的活动调用面，并作为下一项边界明确的修复单独落地。
+
+### 已复现并修复：Usage tracking 与 AI advice 的 7 / 30 日归因边界
+
+Claude CLI 对 `ClaudeDataLoader.getUsageAttribution()` 的全部调用点做了独立审计，确认 week/month 仍以 `now - N × 24h` 过滤，而同一函数的 day 分支和刚修正的 Share Card 已使用配置时区自然日。实际受影响的活动界面只有：
+
+- Content 页“Usage tracking”面板的默认 Week 视图及 Week / Month 切换；
+- `adviceSummary.ts` 生成 AI advice 输入时的 week 范围。
+
+Claude Today、仪表盘“最近 30 天”、Share Card 和 Codex 聚合均不调用这条函数，因此没有把影响面夸大。`types.ts` 已明确 week = 最近 7 天、month = 最近 30 天；正确口径是“今天 + 前 6 / 29 个配置时区自然日”。
+
+处理方式仍采用红绿测试：分别在 `Asia/Tokyo` 和 `Pacific/Honolulu` 构造 UTC 边界样例，旧逻辑会把第 8 / 31 个本地日纳入，两个测试均稳定失败；随后仅在 `getUsageAttribution()` 内复用 `rollingDayKeysFromDayKey()`，让 day/week/month 共用精确日期键集合，session/project 路径保持原样。
+
+第三次 Claude CLI diff 复核没有发现阻塞问题，但指出 `ContentAnalysis.skillUses[].day` 是解析时缓存值：用户改时区而文件未变化时，增量索引不会重新解析，旧 day 可能滞留。为避免只修 record 而遗漏 skill/plugin 归因，又增加一个先红后绿样例，并在过滤时优先由绝对时间 `ts` 按当前配置时区重新归档；只有不可解析的旧记录才回退缓存 day。最终定向 `dataLoader` 套件 16/16 通过。
+
+同一复核还确认浏览器侧 `applySessionFilters()` 仍用宿主系统午夜和固定毫秒窗口筛 Sessions 列表；这是不同代码层的独立缺陷，随后作为下一项边界明确的修复单独落地。
+
+### 已复现并修复：Claude / Codex Sessions 使用宿主时区过滤
+
+Claude CLI 对浏览器侧 `applySessionFilters()` 做了独立调用面审计，确认旧实现以 Webview 所在机器的本地午夜处理 `today`，并以 `Date.now() - N × 24h` 处理 7 / 30 天。实际影响面是 Claude Sessions 的 Today / 7 / 30 天，以及 Codex Sessions 的 7 / 30 天；Workflows 和 Compare 不经过这条路径。
+
+UTC 边界反例可以稳定复现错误：当 Webview 运行在香港时区、插件配置为 `Pacific/Honolulu`，Honolulu 当日凌晨的 session 会被 Today 隐藏；7 / 30 天还会错误纳入边界外的相邻本地日。相反方向在 `Asia/Tokyo` 也可能把配置时区的昨日保留在 Today。
+
+处理方式仍采用红绿测试：先在 Playwright 中固定浏览器时钟和 Honolulu 配置时区，旧实现稳定把 `Honolulu today` 隐藏；随后由服务端为 Claude 与 Codex session 主行写入配置时区的 `data-day-key`，客户端以插件宿主解析后的配置时区构造“今天 + 前 6 / 29 日”的精确自然日集合。这样也覆盖空值表示“系统时区”以及远程插件宿主和本地 Webview 时区不同的情况。过滤状态在完整 Webview 重载后继续保留，明细行仍跟随主行显隐。
+
+修复后定向 Playwright 1/1 通过，完整 UI 回归 122/122 通过。第三个 Claude CLI diff 复核在达到回合上限前完成了源码编译、生成脚本正则、服务端日期键和定向绿灯检查，未报告已证实缺陷；由于没有生成最终结论，本记录不把它表述为完整验收。它另行指出 Claude `formatDateTime()` 仍使用宿主时区 getter，这是显示层的独立后续项，不与本次范围过滤修复混在一起。
+
+### 已复现并修复：Claude 列表时间标签忽略配置时区
+
+新一轮 Claude CLI 只读审计确认 `UsageWebviewProvider.formatDateTime()` 完全依赖 Extension Host 的 `Date#getHours/getDate/getMonth/getFullYear`，未读取 `I18n.getTimezone()`。它只影响 Claude 分支，但调用面横跨 Sessions、Projects、Branches 和 Workflows 的七处时间列；Codex 同类标签已经通过 `createCodexLocalizedFormatters()` 使用配置时区。
+
+最直接的矛盾位于同一个 Claude Session 行：过滤用的 `data-day-key` 已按配置时区生成，紧邻的可见日期文本却按宿主时区显示。在宿主为 UTC、配置为 `Asia/Tokyo`、当前时刻为 `2026-09-03T15:00:00Z` 时，`2026-09-03T14:00:00Z` 的 session 旧逻辑显示为 `Today 14:00`，而配置时区中的正确含义是 `Yesterday 23:00`。
+
+处理方式：先加入 Today/Yesterday、DST 切换和跨年分支三个定向测试，旧实现实际结果为 1 通过、2 失败；随后把方法改为使用解析后的配置时区、`dayKeyInZone()` 和自然日键计算 Today/Yesterday，并用明确的 `h23` 时钟格式保持原有 `HH:MM` 外观。DST 的“昨日”由日期键运算得到，不以 24 小时毫秒相减。挑战复核后又补上同年紧凑格式、无效/epoch sentinel，以及八种 UI locale 的 Today/Yesterday 文案覆盖，最终定向测试 5/5 通过。
+
+同一持久 Claude 会话对 diff 给出 `ACCEPT`，确认配置时区、DST、24 小时制、八语言文案和 Extension Host / Webview 边界均未发现阻塞缺陷。需要披露的是：Claude 在明确的只读要求下误执行了一次 `git stash`，随即 `pop` 恢复；本地随后逐文件核对 diff、未跟踪测试、stash 列表和完整回归，确认没有丢失或混入变更。审阅还确认三个相邻但独立的既有问题仍待后续处理：Workflow“本月”聚合、图表 tooltip 日期和 Advice snooze 日期仍有宿主时区路径。
+
+第三次 Claude CLI 独立复核被限制为只读搜索工具，没有再获得 Git 或写入能力。它未发现正确性阻塞项，但指出初版修复在每个表格行会重复构造 6 个 `Intl.DateTimeFormat`，与 Codex 一次创建、整表复用的既有模式不一致。新增构造次数回归后，旧修复对两个标签实际构造 12 次（预期 2 次），稳定红灯；随后在 Webview provider 内按配置时区缓存一个同时产出日期键和 `HH:MM` 的 formatter，并让 Session 的过滤日期键复用它。最终两个标签合计只构造 2 次，后续行不再新增 formatter，同时保持全部语义测试不变。
+
+### 已复现并修复：Workflows 摘要混用自然月与滚动 30 天
+
+Claude CLI 对 Workflows 页摘要及其数据入口做了只读审计，确认旧实现把分子按 Extension Host 的自然月和 `endTime` 筛选，而分母 `this.monthData` 实际来自 `materialized.last30Days`。因此它不仅会在 UTC 边界错分，还会在每次渲染中把“自然月工作流成本”除以“滚动 30 天总成本”，页面上的“本月”文字也与中间仪表板标签的真实口径冲突。
+
+同一持久 Claude 会话继续查阅 CHANGELOG、既有滚动范围测试和调用点后给出高置信度结论：Workflows 摘要应与中间页保持一致，范围是配置时区中的“今天 + 前 29 个自然日”；工作流按列表展示和排序所采用的 `startTime` 归属，而不是可能跨日或跨月的 `endTime`。不应为此新增自然月数据管线，也不应改动状态栏中确实仍采用自然月的月成本选项。
+
+处理方式仍采用红绿测试：在 `Asia/Tokyo` 下固定当前时刻，把两个工作流开始时间放在 30 日边界的前后一分钟，并故意让结束时间跨入范围。旧实现实际显示 `Workflows this month: 2 · $30.00 · 75%`，稳定证明了错误；修复后只纳入边界内开始的一个工作流，显示 `1 · $10.00 · 25%`，与同一滚动 30 天分母核对。摘要使用既有自然日键工具并复用缓存的配置时区 formatter；八种 UI locale 的“最近 30 天工作流 / 成本占比”文案也由独立断言覆盖。
+
+定向测试 2/2、完整 Node 回归 920 通过（另 1 项按平台能力跳过）、完整 Playwright UI 回归 122/122 通过。README 七种版本和 CHANGELOG 已同步真实语义。F5 Extension Development Host 与安装 VSIX 的人工烟测仍保留给白天发版检查，不把浏览器夹具回归夸大为真实宿主验收。
+
+### 已复现并修复：图表日期标签受宿主时区影响
+
+Claude CLI 对 `src/webview.ts` 的浏览器侧日期格式化调用做了只读审计，确认已经按配置时区归档的 `YYYY-MM-DD` / `YYYY-MM` 用量键，在若干活动路径中又被 `new Date(key)` 解析成 UTC 午夜，再按 Webview 宿主或配置时区显示。受影响的活动路径包括主图切换指标后的 tooltip / ARIA 标签、日→小时标题、月→日标题、每日 Token 构成标签和每日明细表日期。宿主位于 UTC 以西时，日键会退回前一天；月键会退回前一个月。该问题与数据归档无关，属于显示层二次解析错误。
+
+处理方式仍采用红绿测试：先让 Playwright 在 `America/Los_Angeles` 宿主时区切换日/月主图指标，并在插件配置为 `Pacific/Honolulu` 时直接渲染日、月下钻。旧实现稳定把 `2026-07-20` 显示为 `7/19/2026`，把 `2026-07` 显示为 `June 2026`，每日构成与表格中的 `7/1` 也都退成 `6/30`。随后在 Webview 客户端加入一个只处理规范用量键的 formatter：按组件解析，使用 UTC 正午 sentinel，并固定以 UTC 输出既有 locale 格式，从而不再让宿主或配置时区对已经归档的键做第二次位移。
+
+绿灯过程中又捕获到服务端共享 helper 的相邻缺陷：`formatUsageDate('2026-07', ..., true)` 会把缺失的日组件传入 `Date.UTC()`，得到 `Invalid Date`。增加独立红灯后，月键明确以每月 1 日的 UTC 正午 sentinel 格式化。最终定向 Node 3/3、Playwright 2/2、完整 Node 920 通过（另 1 项跳过）、完整 Playwright 124/124 通过。
+
+本轮还尝试在同一持久 Claude 会话中做挑战复核，但调用在 CLI 进程启动前被权限审阅器拦截，原因是请求会传输仓库源码 / 测试内容；没有绕过限制，也没有产生该次 Claude 用量。改由本地 diff 检查、定向红绿测试和两套完整回归完成验收。
+
+### 已复现并修复：Advice / Optimizer 暂停日期使用宿主时区
+
+上一轮审计留下的五个活动显示调用都直接执行 `new Date(snoozedUntil).toLocaleDateString()`，没有传入 UI locale 或插件配置时区。暂停是否到期本身按 epoch 毫秒比较，是刻意的七天持续时间语义，不受时区影响；错误只发生在用户看到的截止日期。Extension Host 与配置时区分居日期边界两侧时，页面会把同一个截止时刻显示成不同自然日。
+
+处理方式：在 Node 测试中把宿主固定为 UTC、插件配置为 `Pacific/Honolulu`，并把截止时刻固定为 `2099-01-01T00:30:00Z`。旧实现显示 `Snoozed until 1/1/2099`，而配置时区中的正确日期是 `12/31/2098`。随后增加一个仅负责 Advice 暂停日期的 formatter，复用 `I18n.getLocale()` 与 `I18n.dateFormatOptions()`，并让 Advice 活动卡、折叠摘要和 Optimizer 两种暂停状态共用它；到期判定与七天时长完全不变。
+
+修复后定向测试 9/9、完整 Node 921 通过（另 1 项跳过）、完整 Playwright 124/124 通过。本轮原计划再次调用 Claude CLI 审计这两条剩余路径，但权限审阅器在 CLI 启动前拒绝了仓库源码传输；遵守限制后只使用本地搜索、测试和实现，没有尝试绕过，也没有新增 Claude usage。
+
+## Claude CLI 用量与会话
+
+所有调用均使用标准持久会话，未使用 `--no-session-persistence` 或 `--bare`，因此会进入 Claude Code 本地用量日志。
+
+- 基线扫描：114 条 usage 事件；input 228、cache creation 345,157、cache read 11,162,603、output 88,236。
+- 路径脱敏审计：47 条 usage 事件；input 94、cache creation 146,606、cache read 2,247,048、output 72,535。
+- 周额度语义审计：53 条 usage 事件；input 106、cache creation 271,767、cache read 3,145,242、output 53,757。
+- 图表下钻审计（同一持久会话续跑完成）：57 条 usage 事件；input 112、cache creation 144,163、cache read 3,498,499、output 34,409。
+- 下钻修复独立复核：67 条 usage 事件；input 134、cache creation 176,071、cache read 5,169,897、output 47,671。
+- 设置 / 隐私 / 分享默认值审计：259 条 usage 事件；input 518、cache creation 805,819、cache read 13,505,410、output 93,643。
+- 设置页显隐与迁移语义挑战审阅：196 条 usage 事件；input 392、cache creation 632,326、cache read 8,509,434、output 102,804。
+- 分享工作台八语言覆盖审计：172 条 usage 事件；input 344、cache creation 522,114、cache read 7,735,749、output 146,744。
+- Claude 今日 / 最近 30 天数据链路审计：286 条 usage 事件；input 572、cache creation 1,045,567、cache read 19,000,503、output 129,784。
+- 热力图与分享范围时区挑战审阅（同一持久会话续跑完成）：170 条 usage 事件；input 338、cache creation 606,321、cache read 8,696,000、output 100,697。
+- Claude 零值生产链路二次深审：205 条 usage 事件；input 410、cache creation 1,059,844、cache read 14,316,982、output 141,673。
+- Usage attribution 固定毫秒窗口审计：151 条 usage 事件；input 302、cache creation 452,274、cache read 6,667,494、output 91,859。
+- Attribution 修复独立 diff 复核：52 条 usage 事件；input 104、cache creation 236,000、cache read 3,445,457、output 88,058。
+- Session 范围时区审计及同一持久会话续跑：260 条 usage 事件；input 518、cache creation 983,150、cache read 13,683,393、output 124,781。
+- Session 范围修复 diff 复核（达到回合上限，未生成最终结论）：85 条 usage 事件；input 170、cache creation 260,322、cache read 7,062,336、output 110,602。
+- Claude 列表时间标签审计：37 条 usage 事件；input 44、cache creation 76,163、cache read 1,488,896、output 27,701。
+- 时间标签修复 diff 复核（同一持久会话续跑）：21 条 usage 事件；input 36、cache creation 104,185、cache read 2,014,177、output 20,653。
+- 时间标签性能与测试独立复核（仅允许读/搜索工具）：27 条 usage 事件；input 46、cache creation 69,721、cache read 1,031,324、output 25,520。
+- Workflows 范围与数据链路审计（仅允许读/搜索工具）：50 条 usage 事件；input 74、cache creation 73,249、cache read 1,506,564、output 36,377。
+- Workflows 产品语义续跑（同一持久会话）：执行完成，但调用器结果在进程关闭后被截断，未获得可核对的单次 CLI summary；本记录不读取 conversation 正文反推，也不把它并入下方可核对下限。
+- Workflows 最终结论提取（同一持久会话，仅允许读/搜索工具）：1 条 usage 事件；input 2、cache creation 116,336、cache read 26,128、output 1,149。
+- 图表日期标签宿主时区审计（标准持久会话）：47 条 usage 事件；input 68、cache creation 94,987、cache read 2,980,497、output 33,578。
+- 图表日期标签挑战复核在 CLI 进程启动前被权限审阅器拒绝，没有产生 Claude usage，也未重试或绕过。
+- Advice / Optimizer 暂停日期与旧 Share Card 月份选择器的只读审计，同样在 CLI 进程启动前被权限审阅器拒绝；没有产生 Claude usage，也未重试或绕过。
+- 不带仓库文件工具、只含脱敏产品摘要的发布 QA 矩阵请求也在 CLI 进程启动前被权限审阅器拒绝；没有产生 Claude usage。此后不再尝试外部 Claude 调用，避免绕过权限边界。
+- 截至本轮**可核对下限**：2,357 条 usage 事件；input 4,612、cache creation 8,222,142、cache read 136,893,633、output 1,572,231（均为 Claude Code CLI summary 口径；另有一次已完成但 summary 丢失的续跑未计入）。一次受限 sandbox 调用因 `FailedToOpenSocket` 退出且 usage 全为 0；授权正常网络后，同一标准持久会话调用成功。未触发 rate limit。
+
+## 上游 issue / PR 发版前快照
+
+读取时间：2026-09-03 07:51 CST；09:12 与 10:40 CST 再次只读复核，队列均无变化。这里只做只读盘点和本地核对；依照夜间任务边界，没有评论、关闭、合并、推送或发布任何远程对象。
+
+- 上游当前有 2 个 open issue、0 个 open PR。
+- [Issue #94](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/94)（OpenAI `thinking` 参数导致 400）已经由本分支 `0614442` 修复：OpenAI-compatible body 只发送 `reasoning_effort`，并有 GPT-5.6 Sol `max` 与 DeepSeek 路径回归。维护者已在 issue 中说明“发布后关闭”；明天应在已发布构建核验一次，再以版本号关闭。
+- [Issue #91](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/issues/91)（多币种显示）已经接受为后续版本，约定范围是用户自填汇率与币种/符号、无联网汇率源。它不属于本次稳定性发版，不应临时塞入 2.3.1。
+- 最近的上游 PR 均已关闭或合并，最新为 [PR #93](https://github.com/ClaudeCodeUsage/ClaudeCodeUsage/pull/93)；当前没有需要审阅、rebase 或合并的 PR 队列。
+
+明天的远程动作建议保持最小：发布候选通过安装态烟测后，发布 2.3.1；随后在 #94 留下发布版本与最小验证结果并关闭。#91 保持 open，不承诺具体版本；没有新 PR 时无需创建占位 PR。
+
+## 验证记录
+
+- 红灯：`node --test out/test/codexIdentity.test.js` 在 `3:/Users/carl` 样例上失败，证明测试能捕获问题。
+- 绿灯：修复后同一套定向测试 15/15 通过。
+- 完整 Node 测试：在允许测试进程监听本机 loopback 后，906 通过、0 失败、1 跳过。受限 sandbox 内的首次运行仅有两个 `listen EPERM`，均由测试夹具无法绑定 `127.0.0.1` 引起；解除该限制后相同测试通过。
+- `git diff --check` 通过；TypeScript 编译通过。
+- 路径脱敏本地提交标题：`fix: harden Codex title path redaction`。
+- Claude 下钻红灯：新增两个 Playwright 测试后，日→小时未写入状态，月→日缺少初始化 ARIA，两个测试均失败。
+- Claude 下钻绿灯：定向测试 2/2 通过；完整交互文件 16/16 通过；既有 Codex 键盘下钻可访问性测试 1/1 通过。
+- Claude 下钻修复后的完整 Node 回归：906 通过、0 失败、1 跳过。
+- Claude 下钻修复后的完整 Playwright UI 回归：121/121 通过。
+- 隔离的 `CCU Release VSCode` 合成数据宿主烟测：Claude“所有”页点击 2026 年 8 月柱后出现每日明细；点击页头刷新后，辅助功能树保留展开明细、选中 provider/tab 与焦点语义，和自动化重载验证一致。
+- `git diff --check` 在本轮最终 diff 上再次通过。
+- 图表下钻本地提交标题：`fix: persist Claude chart drilldowns`。
+- 分享工作台本地化红灯：新增覆盖测试报告 `de-DE`、`ja`、`ko`、`pt-BR`、`id` 五个活动分支缺失，0/1 通过。
+- 分享工作台本地化绿灯：补齐文案后定向 Node 测试 1/1 通过；真实 Share studio Playwright 文件 7/7 通过，并逐一渲染八个 locale。
+- 本地化修复后的完整 Node 回归：907 通过、0 失败、1 跳过。
+- 本地化修复后的完整 Playwright UI 回归：121/121 通过；其后增加的八语言面板标题断言已由定向 Playwright 7/7 再验证。
+- 分享工作台本地化提交标题：`fix: localize Share studio across supported locales`。
+- 配置时区红灯：新增两个回归入口后，定向 Node 套件 27 通过、2 失败；失败分别锁定 provider 热力图的 UTC 默认结束日，以及 Share Card 三个滚动范围的固定毫秒边界。
+- 配置时区绿灯：修复后同一定向套件 29/29 通过。
+- 配置时区修复后的完整 Node 回归：909 通过、0 失败、1 跳过（共 910）；受限 sandbox 首次运行的两个失败均为测试夹具无法监听 loopback 的 `EPERM`，授权后完全通过。
+- 配置时区修复后的完整 Playwright UI 回归：121/121 通过。
+- 配置时区本地提交标题：`fix: align share ranges with configured timezone`。
+- Usage attribution 红灯：week 与 month 两个 UTC 边界测试均失败（定向套件 13 通过、2 失败）；修复日期集合后 15/15 通过。
+- Skill-use 重归档红灯：构造“缓存 day 属于旧时区、ts 属于当前范围”的样例后，当前实现错误保留 outside skill；改为按 `ts` 重归档后定向套件 16/16 通过。
+- Attribution 修复后的完整 Node 回归：912 通过、0 失败、1 跳过（共 913）。
+- Attribution 修复后的完整 Playwright UI 回归：121/121 通过。
+- Attribution 修复本地提交标题：`fix: align attribution ranges with configured timezone`。
+- Session 范围红灯：固定香港浏览器时区、Honolulu 配置时区和 `2026-07-20T20:00:00Z` 时钟后，旧实现把 Honolulu 当日 session 隐藏，定向 Playwright 0/1 通过。
+- Session 范围绿灯：Today / 7 / 30 天六个边界行均按配置时区显隐，完整重载后 30 天筛选与结果保持，定向 Playwright 1/1 通过。
+- Session 范围修复后的完整 Node 回归：912 通过、0 失败、1 跳过（共 913）。
+- Session 范围修复后的完整 Playwright UI 回归：122/122 通过。
+- Session 范围修复本地提交标题：`fix: align session ranges with configured timezone`。
+- Claude 时间标签红灯：初始三个定向样例 1 通过、2 失败；错误输出分别为 `Today 22:00`（预期 `Yesterday 23:00`）和 `03-08 14:30`（预期 DST 边界下的 `Yesterday 01:30`）。
+- Claude 时间标签绿灯：修复后初始 3/3 通过；补齐同年、sentinel 与八 locale 后 5/5 通过。
+- Formatter 复用红灯 / 绿灯：两个标签从实际构造 12 个 `Intl.DateTimeFormat` 降为固定 2 个；加入该契约后定向套件最终 6/6 通过。
+- Claude 时间标签修复后的完整 Node 回归：918 通过、0 失败、1 跳过（共 919）。受限 sandbox 中的两个 loopback `EPERM` 不属于产品失败；授权后同一套件全绿。
+- Claude 时间标签修复后的完整 Playwright UI 回归：122/122 通过。
+- Claude 时间标签修复本地提交标题：`fix: honor configured timezone in Claude date labels`。
+- Workflows 摘要红灯：东京时区的 30 日边界前后一分钟样例中，旧实现错误显示 2 个自然月工作流、`$30.00` 和 75%，而正确滚动范围应为 1 个、`$10.00` 和 25%。
+- Workflows 摘要绿灯：配置时区边界、`startTime` 归属、匹配分母和八 locale 文案的定向套件 2/2 通过。
+- Workflows 修复后的完整 Node 回归：920 通过、0 失败、1 跳过（共 921）。受限 sandbox 中的两个 loopback `EPERM` 不属于产品失败；授权后同一套件全绿。
+- Workflows 修复后的完整 Playwright UI 回归：122/122 通过。
+- Workflows 摘要修复本地提交标题：`fix: align workflow summary with rolling range`。
+- 图表日期标签红灯：Playwright 两个测试 0/2 通过；主图指标切换把 `7/20/2026` 变成 `7/19/2026`，下钻标题把 `July 2026` 变成 `June 2026`，每日构成与表格把 `7/1` 变成 `6/30`。
+- 服务端月键红灯：加入裸 `YYYY-MM` 样例后，`usageDateLabels` 定向套件 2/3 通过，失败值为 `Invalid Date`。
+- 图表日期标签绿灯：`usageDateLabels` 定向 Node 3/3、图表标签定向 Playwright 2/2 通过。
+- 图表日期标签修复后的完整 Node 回归：920 通过、0 失败、1 跳过（共 921）。
+- 图表日期标签修复后的完整 Playwright UI 回归：124/124 通过。
+- 图表日期标签修复本地提交标题：`fix: stabilize chart date labels across timezones`。
+- 暂停日期红灯：宿主 UTC、配置 `Pacific/Honolulu`、截止时刻 `2099-01-01T00:30:00Z` 时，Optimizer 实际显示 `1/1/2099`，而正确配置时区日期为 `12/31/2098`；定向套件 8/9 通过。
+- 暂停日期绿灯：Advice 与 Optimizer 共用配置时区 formatter 后，定向套件 9/9 通过。
+- 暂停日期修复后的完整 Node 回归：921 通过、0 失败、1 跳过（共 922）。
+- 暂停日期修复后的完整 Playwright UI 回归：124/124 通过。
+- 暂停日期修复本地提交标题：`fix: honor configured timezone in advice snooze dates`。
+- Claude 零值链路加固：真实嵌套 subagent 目录覆盖冷索引、无变化刷新与尾部追加，定向 `claudeIncrementalIndex` 17/17 通过；生产递归 watcher callback 覆盖嵌套 `.jsonl` 与非用量 metadata，合并定向套件 55/55 通过。
+- 上述测试加固后的完整 Node 回归：923 通过、0 失败、1 跳过（共 924）。没有产品代码改动，因此未重复运行 UI 套件。
+- Claude 零值链路测试提交标题：`test: cover nested Claude usage refresh paths`。
+- 文件监听错误红灯：mock watcher 没有注册 `error` listener，定向测试 0/1 通过。
+- 文件监听错误绿灯：异步 `EMFILE` 会关闭 watcher、释放 ownership，并保留 polling；定向错误路径 1/1、完整 `extensionWindowActivity` 39 通过、1 项按宿主能力跳过。
+- 新增真实文件事件整链测试；当前受限测试宿主无法分配递归 watcher，按明确能力条件跳过，不把它记作产品绿灯。
+- 文件监听修复后的完整 Node 回归：925 通过、0 失败、1 跳过（共 926）。受限 sandbox 首次运行另有两个 loopback `EPERM`；允许测试夹具绑定本机 `127.0.0.1` 后同一套件全绿。
+- 文件监听修复及最终源码状态的完整 Playwright UI 回归：124/124 通过。该结果覆盖浏览器夹具，不替代 Extension Development Host 或安装态 VSIX 的人工烟测。
+- 发版相关 UI 闸门复跑：`codex-responsive`、`codex-visual`、`codex-accessibility`、`combined-heatmap` 与 `codex-interactions` 合计 93/93 通过。覆盖八种 locale 的 360px Codex shell、Claude/Codex 共用窄屏几何、明暗主题变量与不透明色块、严重/致命可访问性问题、Codex 日柱→小时展开及重载恢复、分享工作台默认开启/可隐藏，以及分位数、对数、线性色阶偏好与导出消息的一致性。首次受限运行只因 Playwright 无权绑定 `127.0.0.1:4173` 失败；授权本机测试服务器后相同套件全绿。
+- 夜间增量的 Git / 包卫生复核：`0614442..HEAD` 共涉及 36 个文件，`git diff --check` 通过，`git diff --summary` 没有权限位变化或意外重命名；全部新增/修改文件仍为 `100644`。`npm ls --omit=dev --depth=0` 为空，未增加运行时依赖；截至 10:40 CST，该范围内 17 个本地提交均包含仓库规定的 OpenAI Codex trailer。
+- 发版候选封装验证：使用仓库锁定版本 `@vscode/vsce@3.9.1` 在仓库外生成 `/private/tmp/claude-code-usage-2.3.1-overnight.vsix`，共 107 个文件、1,915,921 bytes；`.github/scripts/verify-vsix.mjs` 校验版本 `2.3.1`、入口 `extension/out/extension.js` 与打包清单通过，SHA-256 为 `238408bbe64f55992323a2371e986c374a997d0f21acb57655c081de17484818`。这是封装与静态清单验证，不把它表述为安装态宿主验收。
+- 安装态 VSIX 烟测：把上述同一个候选包安装进隔离的 `CCU Release VSCode` 临时 profile，重启 Extension Host 后核对已安装 `out/extension.js` 与 VSIX 内入口 SHA-256 均为 `b36296acfe614395fb822773d8ad69dcbc4e30684645a1f5eceb0e6070976b61`。Codex 每周额度的周期详情默认折叠；状态栏显示简短的 `CX 0`、以“今日”为 hover 口径，并以 `wk 26%` 显示周余量，同时 hover 进度条显示 74% 已用，语义和 Claude 样式约定一致。
+- Claude 安装态增量链烟测：只向隔离 profile 的合成 transcript 追加一条 2026-09-03 记录；生产 watcher 日志显示一次 418-byte / 1-line 尾读和一次 aggregate mutation，未见错误或重复读取。Webview 的“今日”随即精确显示 input 2,300,000、output 170,000、cache miss 300,000、cache hit 1,800,000 及 `08:00` 小时桶；“近 30 天”显示 input 76,100,000，并在日图和表格中出现 2026/9/3 的同一组数值。该烟测没有读取真实用户 transcript、账号或凭据，证明当前安装包在 macOS 合成环境中的 `fs.watch` → 增量索引 → Webview 路径成立；它仍不能复现或解释维护者原环境中的偶发零值。
+
+## 后续版本建议（尚未实施）
+
+- 用英文界面和浅色主题再走一遍 Today / Last 30 days / All time、柱状图展开和空状态，重点检查中英文文本长度造成的布局差异。
+- 在 Windows 环境补充盘符、UNC 与混合分隔符的可视化端到端验证；现有单元测试只证明清洗函数本身的预期行为。
+- 继续逐项对照 Claude 与 Codex 的交互细节，但每项先确认 provider 语义，再决定是视觉统一还是保留差异。
+- 后续可把仍由源码交叉测试使用、但不会渲染的本地数据面板模板改成更窄的动作清单契约；当前删除它会同时削弱七个命令动作的白名单一致性测试，故本轮不做无收益清理。
+- 继续追查偶发 Claude Today / 最近 30 天零值：现已覆盖真实嵌套目录的发现、单次计数、增量尾读、生产 watcher callback 调度、异步 watcher 失败降级，并在隔离安装态 VSIX 中完成一次真实 macOS 文件事件到 Webview 的合成烟测。原截图中的零值仍未稳定复现；白天优先核对原机器当时选中的 Claude data root、多个候选 profile、dashboard auto-refresh / 窗口活动状态及标准持久 CLI 是否实际写入 transcript。只收集匿名 `refresh:` 诊断和根目录选择结果，不读取 transcript 正文。
+- 单独审计旧 Claude Share Card：它不是 Compare 的综合分享工作台，但仍是活动 UI。安装态简体中文烟测确认该整段标题、说明、控件及月份仍回落英语；特定月份选择器还以 Extension Host 的 `new Date(year, month, 1)` 生成过去 12 个月，并硬编码英文月份与 `last month`。应先明确旧卡片在 2.3.2 的保留范围，再决定是按配置时区和八语言完整修正，还是在后续版本收敛两个分享入口，避免只修月份形成半本地化界面。
+
+## 边界说明
+
+本记录中的“已修复”仅指已由回归测试复现并在本地代码中修正的路径脱敏、Claude 图表下钻持久化、活动分享工作台本地化、配置时区日期边界、Usage attribution、Claude / Codex Sessions 范围、Claude 列表时间标签、Workflows 滚动 30 天摘要、图表日/月用量键标签、Advice / Optimizer 暂停日期与文件监听异步错误降级问题；“无需修改”仅指本轮追踪到的周额度状态栏链路与设置页显隐链路。Claude Today / 最近 30 天零值目前属于“已审计、未稳定复现”，不能把未证实原因写成发布结论。旧 Claude Share Card 的月份选择器和其他初步审阅意见在独立复现前同样不作为发布结论。
diff --git a/images/v2.3.1/claude-today-zh-CN-dark.png b/images/v2.3.1/claude-today-zh-CN-dark.png
new file mode 100644
index 00000000..22442d88
Binary files /dev/null and b/images/v2.3.1/claude-today-zh-CN-dark.png differ
diff --git a/images/v2.3.1/codex-overview-zh-CN-dark.png b/images/v2.3.1/codex-overview-zh-CN-dark.png
new file mode 100644
index 00000000..93e83fc6
Binary files /dev/null and b/images/v2.3.1/codex-overview-zh-CN-dark.png differ
diff --git a/images/v2.3.1/codex-weekly-estimate-en-dark.png b/images/v2.3.1/codex-weekly-estimate-en-dark.png
new file mode 100644
index 00000000..d7990932
Binary files /dev/null and b/images/v2.3.1/codex-weekly-estimate-en-dark.png differ
diff --git a/images/v2.3.1/compare-heatmap-en-light.png b/images/v2.3.1/compare-heatmap-en-light.png
new file mode 100644
index 00000000..ca71849b
Binary files /dev/null and b/images/v2.3.1/compare-heatmap-en-light.png differ
diff --git a/package.json b/package.json
index 642769d1..64cbcca6 100644
--- a/package.json
+++ b/package.json
@@ -69,11 +69,6 @@
           ],
           "default": "auto",
           "description": "Display language (auto-detection or manual selection). All other settings now live in the dashboard's ⚙ Settings tab (Show Usage Details)."
-        },
-        "claudeCodeUsage.advice.apiKey": {
-          "type": "string",
-          "default": "",
-          "description": "API key for the 'Get AI Advice' feature (used when advice.backend = api). Leave empty to use the subscription backend. Other advice options live in the dashboard's ⚙ Settings tab."
         }
       }
     },
@@ -127,6 +122,46 @@
         "command": "claudeCodeUsage.previewWhatsNew",
         "title": "Preview What's New",
         "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.manageLocalData",
+        "title": "Manage Local Data and Privacy",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.rebuildCodexIndex",
+        "title": "Rebuild Codex Derived Index",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.clearQuotaHistory",
+        "title": "Clear Quota Observation History…",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.clearAdviceData",
+        "title": "Clear Local Advice Data…",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.resetUiState",
+        "title": "Reset Dashboard UI State…",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.resetSharingPreferences",
+        "title": "Reset Sharing Preferences…",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.clearByokSecret",
+        "title": "Clear BYOK Advice Secret…",
+        "category": "Claude Code Usage"
+      },
+      {
+        "command": "claudeCodeUsage.clearAllDerivedData",
+        "title": "Clear All Extension-Derived Data…",
+        "category": "Claude Code Usage"
       }
     ]
   },
diff --git a/src/adviceEffectiveness/adapters.ts b/src/adviceEffectiveness/adapters.ts
new file mode 100644
index 00000000..453fdac0
--- /dev/null
+++ b/src/adviceEffectiveness/adapters.ts
@@ -0,0 +1,597 @@
+import type {
+  CodexInsight,
+  CodexInsightKind,
+} from '../providers/codex/codexInsights';
+import type { CodexScope } from '../types';
+import {
+  AdviceContract,
+  AdviceEvidence,
+  AdviceObservation,
+  AdviceRecommendation,
+  AdviceScope,
+  AdviceSourceInfo,
+  AdviceWindow,
+  createAdviceContract,
+  isAdviceIdentifier,
+} from './contract';
+import {
+  AdviceAggregateSnapshot,
+  validateAdviceAggregateSnapshot,
+} from './payload';
+
+/** Pre-declared local-rule threshold; both the count and share must hold. */
+export const CLAUDE_CLEAR_MIN_AFFECTED_SESSIONS = 2;
+export const CLAUDE_CLEAR_MIN_AFFECTED_SHARE = 0.25;
+
+const MIN_COMPARABLE_TASKS = 5;
+const DEFAULT_RELATIVE_TARGET = 0.1;
+const QUALITY_GUARDRAIL = {
+  rubricId: 'task-quality-rubric-v1',
+  minimumScore: 0.8,
+  maximumRegression: 0.02,
+} as const;
+
+export interface AdviceAdapterMetadata {
+  adviceId: string;
+  generatedAt: string;
+  locale: string;
+}
+
+export interface ClaudeAdviceSessionSummary {
+  scope: AdviceAggregateSnapshot['scope'];
+  windowDays: number;
+  /** Numeric aggregate only; no session IDs, titles, paths, or records. */
+  totalSessions: number;
+  /** Sessions already classified locally as active for at least eight hours. */
+  longSessionCount: number;
+  /** Sessions already classified locally as observing context above 150k. */
+  largeContextSessionCount: number;
+}
+
+export interface ClaudeAdviceAdapterInput extends AdviceAdapterMetadata {
+  /** Must already represent exactly the same scope/window as sessionSummary. */
+  aggregate: AdviceAggregateSnapshot;
+  sessionSummary: ClaudeAdviceSessionSummary;
+  frameworkOverhead?: {
+    frameworkEstimatedTokens: number;
+    /** Upstream-owned denominator; the adapter never re-sums content buckets. */
+    observedInputEstimatedTokens: number;
+    classifiedEvents: number;
+  };
+}
+
+export interface ClaudeAdviceAdapterOutput {
+  aggregate: AdviceAggregateSnapshot;
+  contract: AdviceContract;
+  remoteEvidenceEligible: true;
+}
+
+export interface CodexAdviceBehaviorSummary {
+  childFreshShare: number;
+  approvalReviewerFreshShare: number;
+  highEffortFreshShare: number;
+  processedToFreshRatio: number;
+  cacheShare: number;
+  postPatchToolCallsPerPatchCall: number;
+}
+
+export interface CodexAdviceQualitySummary {
+  indexComplete: boolean;
+  identityComplete: boolean;
+  periodComplete: boolean;
+  /** Machine-readable provider flags only. */
+  qualityFlags: readonly string[];
+}
+
+export interface CodexAdviceAdapterInput extends AdviceAdapterMetadata {
+  scope: CodexScope;
+  insights: readonly CodexInsight[];
+  /** Narrow structural aggregate; deliberately excludes task/session/project data. */
+  behavior: CodexAdviceBehaviorSummary;
+  quality: CodexAdviceQualitySummary;
+}
+
+export interface CodexAdviceAdapterOutput {
+  contract: AdviceContract;
+  /** Codex aggregate payload semantics require a separate future review. */
+  remoteEvidenceEligible: false;
+}
+
+export type AdviceAdapterBuildResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; issues: string[] };
+
+function cloneAggregate(input: AdviceAggregateSnapshot): AdviceAggregateSnapshot | undefined {
+  try {
+    const value: AdviceAggregateSnapshot = {
+      scope: input.scope,
+      windowDays: input.windowDays,
+      totals: {
+        inputTokens: input.totals.inputTokens,
+        outputTokens: input.totals.outputTokens,
+        cacheCreationTokens: input.totals.cacheCreationTokens,
+        cacheReadTokens: input.totals.cacheReadTokens,
+        messageCount: input.totals.messageCount,
+        estimatedCostUsd: input.totals.estimatedCostUsd,
+      },
+      modelFamilies: input.modelFamilies.map((row) => ({
+        family: row.family,
+        inputTokens: row.inputTokens,
+        outputTokens: row.outputTokens,
+        cacheCreationTokens: row.cacheCreationTokens,
+        cacheReadTokens: row.cacheReadTokens,
+        count: row.count,
+      })),
+    };
+    validateAdviceAggregateSnapshot(value);
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function validCount(value: number): boolean {
+  return Number.isInteger(value) && value >= 0;
+}
+
+function validFiniteNonNegative(value: number): boolean {
+  return Number.isFinite(value) && value >= 0;
+}
+
+function validShare(value: number): boolean {
+  return validFiniteNonNegative(value) && value <= 1;
+}
+
+function localPrivacy() {
+  return {
+    dataMode: 'local-only' as const,
+    promptSampleConsent: 'not-applicable' as const,
+    promptSampleCount: 0,
+    feedbackStorage: 'local-only' as const,
+  };
+}
+
+function successCriterion(
+  metricObservationId: string,
+  direction: 'increase' | 'decrease' | 'maintain' = 'decrease',
+) {
+  return {
+    metricObservationId,
+    direction,
+    target: { kind: 'relative-change' as const, value: DEFAULT_RELATIVE_TARGET },
+    minimumComparableTasks: MIN_COMPARABLE_TASKS,
+    qualityGuardrail: { ...QUALITY_GUARDRAIL },
+  };
+}
+
+function adapterFailure(...issues: string[]): AdviceAdapterBuildResult<never> {
+  return { ok: false, issues };
+}
+
+/**
+ * Map one already-windowed Claude aggregate into a complete local advice
+ * contract. No raw-record type is accepted at this boundary.
+ */
+export function adaptClaudeAdvice(
+  input: ClaudeAdviceAdapterInput,
+): AdviceAdapterBuildResult<ClaudeAdviceAdapterOutput> {
+  const aggregate = cloneAggregate(input.aggregate);
+  if (!aggregate) return adapterFailure('claude-aggregate-invalid');
+  const summary = input.sessionSummary;
+  if (summary.scope !== aggregate.scope || summary.windowDays !== aggregate.windowDays) {
+    return adapterFailure('claude-session-summary-scope-window-mismatch');
+  }
+  if (
+    !validCount(summary.totalSessions) ||
+    !validCount(summary.longSessionCount) ||
+    !validCount(summary.largeContextSessionCount) ||
+    summary.longSessionCount > summary.totalSessions ||
+    summary.largeContextSessionCount > summary.totalSessions
+  ) {
+    return adapterFailure('claude-session-summary-invalid');
+  }
+  const framework = input.frameworkOverhead;
+  if (
+    framework !== undefined &&
+    (!validFiniteNonNegative(framework.frameworkEstimatedTokens) ||
+      !validFiniteNonNegative(framework.observedInputEstimatedTokens) ||
+      !validCount(framework.classifiedEvents) ||
+      framework.frameworkEstimatedTokens > framework.observedInputEstimatedTokens)
+  ) {
+    return adapterFailure('claude-framework-overhead-invalid');
+  }
+
+  const aggregateSource: AdviceSourceInfo = {
+    id: 'source-claude-usage-aggregate',
+    kind: 'claude-usage-aggregate',
+    scope: aggregate.scope,
+    window: { kind: 'rolling-days', days: aggregate.windowDays },
+    confidence: 'high',
+    qualityFlags: [],
+  };
+  const sessionSource: AdviceSourceInfo = {
+    id: 'source-claude-session-summary',
+    kind: 'claude-local-insight',
+    scope: aggregate.scope,
+    window: { kind: 'rolling-days', days: aggregate.windowDays },
+    confidence: 'high',
+    qualityFlags: [],
+  };
+  const frameworkSource: AdviceSourceInfo | undefined =
+    framework === undefined || framework.observedInputEstimatedTokens === 0
+    ? undefined
+    : {
+        id: 'source-claude-framework-summary',
+        kind: 'claude-local-insight',
+        scope: aggregate.scope,
+        window: { kind: 'rolling-days', days: aggregate.windowDays },
+        confidence: 'high',
+        qualityFlags: [],
+      };
+
+  const observations: AdviceObservation[] = [
+    {
+      id: 'observation-claude-input-tokens',
+      metric: 'input-tokens',
+      value: aggregate.totals.inputTokens,
+      unit: 'tokens',
+      method: 'measured',
+      sourceId: aggregateSource.id,
+      summary: 'advice.observation.claude.input-tokens',
+    },
+    {
+      id: 'observation-claude-output-tokens',
+      metric: 'output-tokens',
+      value: aggregate.totals.outputTokens,
+      unit: 'tokens',
+      method: 'measured',
+      sourceId: aggregateSource.id,
+      summary: 'advice.observation.claude.output-tokens',
+    },
+    {
+      id: 'observation-claude-cache-creation-tokens',
+      metric: 'cache-creation-tokens',
+      value: aggregate.totals.cacheCreationTokens,
+      unit: 'tokens',
+      method: 'measured',
+      sourceId: aggregateSource.id,
+      summary: 'advice.observation.claude.cache-creation-tokens',
+    },
+    {
+      id: 'observation-claude-cache-read-tokens',
+      metric: 'cache-read-tokens',
+      value: aggregate.totals.cacheReadTokens,
+      unit: 'tokens',
+      method: 'measured',
+      sourceId: aggregateSource.id,
+      summary: 'advice.observation.claude.cache-read-tokens',
+    },
+    {
+      id: 'observation-claude-message-count',
+      metric: 'message-count',
+      value: aggregate.totals.messageCount,
+      unit: 'count',
+      method: 'measured',
+      sourceId: aggregateSource.id,
+      summary: 'advice.observation.claude.message-count',
+    },
+    {
+      id: 'observation-claude-estimated-cost',
+      metric: 'estimated-cost-usd',
+      value: aggregate.totals.estimatedCostUsd,
+      unit: 'usd-estimate',
+      method: 'estimated',
+      sourceId: aggregateSource.id,
+      summary: 'advice.observation.claude.estimated-cost-usd',
+    },
+  ];
+  const longShare = summary.totalSessions > 0
+    ? summary.longSessionCount / summary.totalSessions
+    : 0;
+  const contextShare = summary.totalSessions > 0
+    ? summary.largeContextSessionCount / summary.totalSessions
+    : 0;
+  const longObservation: AdviceObservation = {
+    id: 'observation-claude-long-session-share',
+    metric: 'long-session-share',
+    value: longShare,
+    unit: 'ratio',
+    method: 'structural-proxy',
+    sourceId: sessionSource.id,
+    summary: 'advice.observation.claude.long-session-share',
+  };
+  const contextObservation: AdviceObservation = {
+    id: 'observation-claude-large-context-share',
+    metric: 'large-context-share',
+    value: contextShare,
+    unit: 'ratio',
+    method: 'structural-proxy',
+    sourceId: sessionSource.id,
+    summary: 'advice.observation.claude.large-context-share',
+  };
+  observations.push(longObservation, contextObservation);
+
+  const aggregateEvidence: AdviceEvidence = {
+    id: 'evidence-claude-usage-aggregate',
+    observationIds: observations.slice(0, 6).map((item) => item.id),
+    strength: 'direct',
+    summary: 'advice.evidence.claude.usage-aggregate',
+    limitations: [],
+  };
+  const longEvidence: AdviceEvidence = {
+    id: 'evidence-claude-long-session-share',
+    observationIds: [longObservation.id],
+    strength: 'proxy',
+    summary: 'advice.evidence.claude.long-session-share',
+    limitations: ['advice.limitation.claude.session-duration-proxy'],
+  };
+  const contextEvidence: AdviceEvidence = {
+    id: 'evidence-claude-large-context-share',
+    observationIds: [contextObservation.id],
+    strength: 'proxy',
+    summary: 'advice.evidence.claude.large-context-share',
+    limitations: ['advice.limitation.claude.context-size-proxy'],
+  };
+  const evidence = [aggregateEvidence, longEvidence, contextEvidence];
+  if (framework && frameworkSource) {
+    const denominator = framework.observedInputEstimatedTokens;
+    const frameworkObservation: AdviceObservation = {
+      id: 'observation-claude-framework-overhead-share',
+      metric: 'framework-overhead-share',
+      value: framework.frameworkEstimatedTokens / denominator,
+      unit: 'ratio',
+      method: 'structural-proxy',
+      sourceId: frameworkSource.id,
+      summary: 'advice.observation.claude.framework-overhead-share',
+    };
+    observations.push(frameworkObservation);
+    evidence.push({
+      id: 'evidence-claude-framework-overhead-share',
+      observationIds: [frameworkObservation.id],
+      strength: 'proxy',
+      summary: 'advice.evidence.claude.framework-overhead-share',
+      limitations: ['advice.limitation.claude.framework-overlay-proxy'],
+    });
+  }
+
+  const longTriggered =
+    summary.longSessionCount >= CLAUDE_CLEAR_MIN_AFFECTED_SESSIONS &&
+    longShare >= CLAUDE_CLEAR_MIN_AFFECTED_SHARE;
+  const contextTriggered =
+    summary.largeContextSessionCount >= CLAUDE_CLEAR_MIN_AFFECTED_SESSIONS &&
+    contextShare >= CLAUDE_CLEAR_MIN_AFFECTED_SHARE;
+  const triggered = [
+    ...(longTriggered ? [{ evidence: longEvidence, observation: longObservation }] : []),
+    ...(contextTriggered ? [{ evidence: contextEvidence, observation: contextObservation }] : []),
+  ];
+  const recommendations: AdviceRecommendation[] = triggered.length === 0
+    ? []
+    : [
+        {
+          id: 'recommendation-claude-clear-between-tasks',
+          title: 'advice.recommendation.claude.clear-between-unrelated-tasks',
+          evidenceIds: triggered.map((item) => item.evidence.id),
+          explanation: {
+            summary: 'advice.explanation.claude.clear-is-conditional',
+            proxyMetricObservationIds: triggered.map((item) => item.observation.id),
+            limitations: ['advice.limitation.claude.clear-not-causal'],
+          },
+          conditionalActions: [
+            {
+              when: 'advice.condition.claude.next-task-is-unrelated',
+              action: '/clear',
+              evidenceIds: triggered.map((item) => item.evidence.id),
+              stopCondition: 'advice.stop.claude.prior-context-still-required',
+            },
+          ],
+          successCriteria: triggered.map((item) => successCriterion(item.observation.id)),
+        },
+      ];
+
+  const built = createAdviceContract({
+    adviceId: input.adviceId,
+    observations,
+    evidence,
+    recommendations,
+    privacy: localPrivacy(),
+    provenance: {
+      generatedBy: { kind: 'local-rules' },
+      generatedAt: input.generatedAt,
+      locale: input.locale,
+      sources: [
+        aggregateSource,
+        sessionSource,
+        ...(frameworkSource ? [frameworkSource] : []),
+      ],
+    },
+  });
+  if (!built.ok) return { ok: false, issues: built.issues };
+  return {
+    ok: true,
+    value: { aggregate, contract: built.value, remoteEvidenceEligible: true },
+  };
+}
+
+const CODEX_KINDS = new Set<CodexInsightKind>([
+  'multi-agent-share',
+  'effort-comparison',
+  'post-patch-tool-intensity',
+  'cache-context',
+  'approval-reviewer-share',
+]);
+
+function codexScope(scope: CodexScope): { scope: AdviceScope; window: AdviceWindow } {
+  if (scope === 'recent') return { scope: 'task-cohort', window: { kind: 'task-cohort' } };
+  if (scope === '7d') return { scope: 'overall', window: { kind: 'rolling-days', days: 7 } };
+  if (scope === '30d') return { scope: 'overall', window: { kind: 'rolling-days', days: 30 } };
+  return { scope: 'overall', window: { kind: 'all-time' } };
+}
+
+function codexSignal(
+  kind: CodexInsightKind,
+  behavior: CodexAdviceBehaviorSummary,
+  sourceId: string,
+): {
+  observations: AdviceObservation[];
+  evidence: AdviceEvidence;
+  recommendation: AdviceRecommendation;
+} {
+  const observation = (
+    suffix: string,
+    metric: string,
+    value: number,
+    unit: 'ratio' | 'multiple',
+  ): AdviceObservation => ({
+    id: `observation-codex-${suffix}`,
+    metric,
+    value,
+    unit,
+    method: 'structural-proxy',
+    sourceId,
+    summary: `advice.observation.codex.${suffix}`,
+  });
+  let observations: AdviceObservation[];
+  if (kind === 'multi-agent-share') {
+    observations = [observation('subagent-share', 'subagent-share', behavior.childFreshShare, 'ratio')];
+  } else if (kind === 'effort-comparison') {
+    observations = [observation('high-effort-share', 'high-effort-share', behavior.highEffortFreshShare, 'ratio')];
+  } else if (kind === 'post-patch-tool-intensity') {
+    observations = [
+      observation(
+        'post-patch-tool-intensity',
+        'post-patch-tool-intensity',
+        behavior.postPatchToolCallsPerPatchCall,
+        'multiple',
+      ),
+    ];
+  } else if (kind === 'cache-context') {
+    observations = [
+      observation(
+        'processed-to-fresh-ratio',
+        'processed-to-fresh-ratio',
+        behavior.processedToFreshRatio,
+        'multiple',
+      ),
+      observation('cache-read-share', 'cache-read-share', behavior.cacheShare, 'ratio'),
+    ];
+  } else {
+    observations = [
+      observation(
+        'approval-reviewer-share',
+        'approval-reviewer-share',
+        behavior.approvalReviewerFreshShare,
+        'ratio',
+      ),
+    ];
+  }
+  const evidence: AdviceEvidence = {
+    id: `evidence-codex-${kind}`,
+    observationIds: observations.map((item) => item.id),
+    strength: 'proxy',
+    summary: `advice.evidence.codex.${kind}`,
+    limitations: ['advice.limitation.codex.structural-proxy'],
+  };
+  const recommendation: AdviceRecommendation = {
+    id: `recommendation-codex-${kind}`,
+    title: `advice.recommendation.codex.${kind}`,
+    evidenceIds: [evidence.id],
+    explanation: {
+      summary: `advice.explanation.codex.${kind}`,
+      proxyMetricObservationIds: observations.map((item) => item.id),
+      limitations: ['advice.limitation.codex.no-causal-claim'],
+    },
+    conditionalActions: [
+      {
+        when: 'advice.condition.codex.next-comparable-task',
+        action: `advice.action.codex.${kind}`,
+        evidenceIds: [evidence.id],
+        stopCondition: 'advice.stop.codex.quality-guardrail-fails',
+      },
+    ],
+    successCriteria: [successCriterion(observations[0].id)],
+  };
+  return { observations, evidence, recommendation };
+}
+
+/** Map R8 structural insights without copying their open evidence object. */
+export function adaptCodexLocalAdvice(
+  input: CodexAdviceAdapterInput,
+): AdviceAdapterBuildResult<CodexAdviceAdapterOutput> {
+  const b = input.behavior;
+  if (
+    !validShare(b.childFreshShare) ||
+    !validShare(b.approvalReviewerFreshShare) ||
+    !validShare(b.highEffortFreshShare) ||
+    !validFiniteNonNegative(b.processedToFreshRatio) ||
+    !validShare(b.cacheShare) ||
+    !validFiniteNonNegative(b.postPatchToolCallsPerPatchCall)
+  ) {
+    return adapterFailure('codex-behavior-summary-invalid');
+  }
+  if (
+    typeof input.quality.indexComplete !== 'boolean' ||
+    typeof input.quality.identityComplete !== 'boolean' ||
+    typeof input.quality.periodComplete !== 'boolean' ||
+    !Array.isArray(input.quality.qualityFlags)
+  ) {
+    return adapterFailure('codex-quality-summary-invalid');
+  }
+  for (const flag of input.quality.qualityFlags) {
+    if (typeof flag !== 'string' || !isAdviceIdentifier(flag)) {
+      return adapterFailure('codex-quality-flag-invalid');
+    }
+  }
+
+  const seen = new Set<CodexInsightKind>();
+  for (const insight of input.insights) {
+    if (
+      !CODEX_KINDS.has(insight.kind) ||
+      insight.scope !== input.scope ||
+      insight.proxy !== true ||
+      seen.has(insight.kind)
+    ) {
+      return adapterFailure('codex-insight-invalid');
+    }
+    seen.add(insight.kind);
+  }
+
+  const qualityFlags = [
+    ...(!input.quality.indexComplete ? ['incomplete-index'] : []),
+    ...(!input.quality.identityComplete ? ['incomplete-identity'] : []),
+    ...(!input.quality.periodComplete ? ['incomplete-period'] : []),
+    ...input.quality.qualityFlags,
+  ].filter((flag, index, all) => all.indexOf(flag) === index);
+  const mappedScope = codexScope(input.scope);
+  const source: AdviceSourceInfo = {
+    id: `source-codex-local-insight-${input.scope}`,
+    kind: 'codex-local-insight',
+    scope: mappedScope.scope,
+    window: mappedScope.window,
+    confidence: qualityFlags.length === 0 ? 'high' : 'unknown',
+    qualityFlags,
+  };
+  const signals = input.insights.map((insight) => codexSignal(insight.kind, b, source.id));
+  const observations = signals.flatMap((signal) => signal.observations);
+  const evidence = signals.map((signal) => signal.evidence);
+  const recommendations = source.confidence === 'high'
+    ? signals.map((signal) => signal.recommendation)
+    : [];
+  const built = createAdviceContract({
+    adviceId: input.adviceId,
+    observations,
+    evidence,
+    recommendations,
+    privacy: localPrivacy(),
+    provenance: {
+      generatedBy: { kind: 'local-rules' },
+      generatedAt: input.generatedAt,
+      locale: input.locale,
+      sources: [source],
+    },
+  });
+  if (!built.ok) return { ok: false, issues: built.issues };
+  return {
+    ok: true,
+    value: { contract: built.value, remoteEvidenceEligible: false },
+  };
+}
diff --git a/src/adviceEffectiveness/comparison.ts b/src/adviceEffectiveness/comparison.ts
new file mode 100644
index 00000000..027a1235
--- /dev/null
+++ b/src/adviceEffectiveness/comparison.ts
@@ -0,0 +1,239 @@
+/** Pure, paired before/after comparison for genuinely comparable tasks. */
+
+export interface ComparableTaskContext {
+  taskKind: string;
+  complexityBand: 'low' | 'medium' | 'high';
+  provider: string;
+  modelFamily: string;
+  effort: string;
+  metricDefinitionVersion: string;
+  qualityRubricId: string;
+}
+
+export interface ComparableTaskOutcome {
+  context: ComparableTaskContext;
+  primaryMetric: {
+    name: string;
+    unit: string;
+    direction: 'lower-is-better' | 'higher-is-better';
+    value: number;
+  };
+  quality: {
+    score: number | null;
+    passed: boolean | null;
+    evidenceCount: number;
+  };
+  evidence: {
+    coverage: 'complete' | 'partial' | 'unknown';
+    confidence: 'high' | 'medium' | 'low' | 'unknown';
+    qualityFlags: string[];
+  };
+}
+
+export interface ComparableTaskPair {
+  pairId: string;
+  before: ComparableTaskOutcome;
+  after: ComparableTaskOutcome;
+}
+
+export interface AdviceComparisonPolicy {
+  minComparablePairs: number;
+  minRelativeImprovement: number;
+  minAfterQualityScore: number;
+  maxMeanQualityRegression: number;
+  allowedQualityFlags: string[];
+}
+
+export const DEFAULT_ADVICE_COMPARISON_POLICY: AdviceComparisonPolicy = {
+  minComparablePairs: 5,
+  minRelativeImprovement: 0.1,
+  minAfterQualityScore: 0.8,
+  maxMeanQualityRegression: 0.02,
+  allowedQualityFlags: [],
+};
+
+export interface AdviceComparisonStats {
+  comparablePairs: number;
+  meanBeforeValue: number;
+  meanAfterValue: number;
+  meanRelativeImprovement: number;
+  meanBeforeQuality: number;
+  meanAfterQuality: number;
+  meanQualityChange: number;
+}
+
+export type AdviceComparisonResult =
+  | {
+      status: 'insufficient-evidence';
+      reasons: string[];
+      comparablePairs: number;
+    }
+  | {
+      status: 'quality-guardrail-failed';
+      reasons: string[];
+      stats: AdviceComparisonStats;
+    }
+  | {
+      status: 'improved' | 'no-demonstrated-improvement';
+      reasons: string[];
+      stats: AdviceComparisonStats;
+    };
+
+function mean(values: readonly number[]): number {
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function sameContext(a: ComparableTaskOutcome, b: ComparableTaskOutcome): boolean {
+  return (
+    a.context.taskKind === b.context.taskKind &&
+    a.context.complexityBand === b.context.complexityBand &&
+    a.context.provider === b.context.provider &&
+    a.context.modelFamily === b.context.modelFamily &&
+    a.context.effort === b.context.effort &&
+    a.context.metricDefinitionVersion === b.context.metricDefinitionVersion &&
+    a.context.qualityRubricId === b.context.qualityRubricId &&
+    a.primaryMetric.name === b.primaryMetric.name &&
+    a.primaryMetric.unit === b.primaryMetric.unit &&
+    a.primaryMetric.direction === b.primaryMetric.direction
+  );
+}
+
+function validScore(value: number | null): value is number {
+  return value !== null && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function policyIssues(policy: AdviceComparisonPolicy): string[] {
+  const issues: string[] = [];
+  if (!Number.isInteger(policy.minComparablePairs) || policy.minComparablePairs < 2) {
+    issues.push('comparison policy requires at least two pairs');
+  }
+  if (!Number.isFinite(policy.minRelativeImprovement) || policy.minRelativeImprovement < 0) {
+    issues.push('comparison policy has an invalid improvement threshold');
+  }
+  if (
+    !Number.isFinite(policy.minAfterQualityScore) ||
+    policy.minAfterQualityScore < 0 ||
+    policy.minAfterQualityScore > 1 ||
+    !Number.isFinite(policy.maxMeanQualityRegression) ||
+    policy.maxMeanQualityRegression < 0 ||
+    policy.maxMeanQualityRegression > 1
+  ) {
+    issues.push('comparison policy has an invalid quality guardrail');
+  }
+  return issues;
+}
+
+/**
+ * Compare paired tasks without inferring causation. Any ambiguity in task
+ * comparability, coverage, confidence, metric values, or quality evidence
+ * returns insufficient-evidence rather than silently dropping the bad pair.
+ */
+export function compareAdviceEffectiveness(
+  pairs: readonly ComparableTaskPair[],
+  policy: AdviceComparisonPolicy = DEFAULT_ADVICE_COMPARISON_POLICY
+): AdviceComparisonResult {
+  const reasons = policyIssues(policy);
+  const pairIds = new Set<string>();
+  const allowedFlags = new Set(policy.allowedQualityFlags);
+  const cohort = pairs.length > 0 ? pairs[0].before : undefined;
+
+  for (const pair of pairs) {
+    if (pairIds.has(pair.pairId)) reasons.push(`duplicate pair id: ${pair.pairId}`);
+    pairIds.add(pair.pairId);
+    if (!sameContext(pair.before, pair.after)) {
+      reasons.push(`pair ${pair.pairId} is not comparable`);
+      continue;
+    }
+    if (cohort && !sameContext(cohort, pair.before)) {
+      reasons.push(`pair ${pair.pairId} is outside the comparison cohort`);
+      continue;
+    }
+    for (const [period, outcome] of [
+      ['before', pair.before],
+      ['after', pair.after],
+    ] as const) {
+      if (outcome.evidence.coverage !== 'complete') {
+        reasons.push(`pair ${pair.pairId} ${period} coverage is incomplete`);
+      }
+      if (outcome.evidence.confidence === 'unknown' || outcome.evidence.confidence === 'low') {
+        reasons.push(`pair ${pair.pairId} ${period} confidence is insufficient`);
+      }
+      const disallowedFlags = outcome.evidence.qualityFlags.filter((flag) => !allowedFlags.has(flag));
+      if (disallowedFlags.length > 0) {
+        reasons.push(`pair ${pair.pairId} ${period} has unresolved quality flags`);
+      }
+      if (!Number.isFinite(outcome.primaryMetric.value) || outcome.primaryMetric.value < 0) {
+        reasons.push(`pair ${pair.pairId} ${period} metric is invalid`);
+      }
+      if (period === 'before' && outcome.primaryMetric.value === 0) {
+        reasons.push(`pair ${pair.pairId} has a zero baseline`);
+      }
+      if (!validScore(outcome.quality.score) || outcome.quality.passed === null) {
+        reasons.push(`pair ${pair.pairId} ${period} quality evidence is unknown`);
+      }
+      if (!Number.isInteger(outcome.quality.evidenceCount) || outcome.quality.evidenceCount < 1) {
+        reasons.push(`pair ${pair.pairId} ${period} has no quality evidence`);
+      }
+      if (period === 'before' && outcome.quality.passed === false) {
+        reasons.push(`pair ${pair.pairId} baseline did not pass its quality rubric`);
+      }
+    }
+  }
+
+  if (pairs.length < policy.minComparablePairs) {
+    reasons.push(`need at least ${policy.minComparablePairs} comparable pairs`);
+  }
+  if (reasons.length > 0) {
+    return { status: 'insufficient-evidence', reasons, comparablePairs: pairs.length };
+  }
+
+  const beforeValues = pairs.map((pair) => pair.before.primaryMetric.value);
+  const afterValues = pairs.map((pair) => pair.after.primaryMetric.value);
+  const beforeQuality = pairs.map((pair) => pair.before.quality.score as number);
+  const afterQuality = pairs.map((pair) => pair.after.quality.score as number);
+  const relativeImprovements = pairs.map((pair) => {
+    const before = pair.before.primaryMetric.value;
+    const after = pair.after.primaryMetric.value;
+    return pair.before.primaryMetric.direction === 'lower-is-better'
+      ? (before - after) / before
+      : (after - before) / before;
+  });
+  const meanBeforeQuality = mean(beforeQuality);
+  const meanAfterQuality = mean(afterQuality);
+  const stats: AdviceComparisonStats = {
+    comparablePairs: pairs.length,
+    meanBeforeValue: mean(beforeValues),
+    meanAfterValue: mean(afterValues),
+    meanRelativeImprovement: mean(relativeImprovements),
+    meanBeforeQuality,
+    meanAfterQuality,
+    meanQualityChange: meanAfterQuality - meanBeforeQuality,
+  };
+
+  const guardrailReasons: string[] = [];
+  if (pairs.some((pair) => pair.after.quality.passed !== true)) {
+    guardrailReasons.push('at least one after task failed its quality rubric');
+  }
+  if (meanAfterQuality < policy.minAfterQualityScore) {
+    guardrailReasons.push('mean after quality is below the required score');
+  }
+  if (stats.meanQualityChange < -policy.maxMeanQualityRegression) {
+    guardrailReasons.push('mean quality regressed beyond the allowed guardrail');
+  }
+  if (guardrailReasons.length > 0) {
+    return { status: 'quality-guardrail-failed', reasons: guardrailReasons, stats };
+  }
+
+  if (stats.meanRelativeImprovement >= policy.minRelativeImprovement) {
+    return {
+      status: 'improved',
+      reasons: ['primary metric met the threshold while the quality guardrail held'],
+      stats,
+    };
+  }
+  return {
+    status: 'no-demonstrated-improvement',
+    reasons: ['primary metric did not meet the pre-declared improvement threshold'],
+    stats,
+  };
+}
diff --git a/src/adviceEffectiveness/comparisonPairing.ts b/src/adviceEffectiveness/comparisonPairing.ts
new file mode 100644
index 00000000..7ed7d46b
--- /dev/null
+++ b/src/adviceEffectiveness/comparisonPairing.ts
@@ -0,0 +1,562 @@
+import { createHash } from 'node:crypto';
+
+import type { ComparableTaskPair } from './comparison';
+import { isAdviceIdentifier } from './contract';
+
+export type StoredAdviceScope = 'overall' | 'project' | 'task-cohort';
+export type StoredProvider = 'claude' | 'codex';
+export type StoredTaskKind = 'small-change' | 'feature' | 'bug-fix' | 'review' | 'other';
+export type StoredComplexityBand = 'low' | 'medium' | 'high';
+export type StoredModelFamily = 'opus' | 'sonnet' | 'haiku' | 'fable' | 'other';
+export type StoredEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'unknown';
+export type StoredMetricUnit = 'count' | 'tokens' | 'ratio' | 'multiple' | 'milliseconds';
+export type StoredMetricDirection = 'lower-is-better' | 'higher-is-better';
+export type StoredQualityPass = 'passed' | 'failed' | 'unknown';
+export type StoredCoverage = 'complete' | 'partial' | 'unknown';
+export type StoredConfidence = 'high' | 'medium' | 'low' | 'unknown';
+
+export interface StoredComparableContext {
+  scope: StoredAdviceScope;
+  taskKind: StoredTaskKind;
+  complexityBand: StoredComplexityBand;
+  provider: StoredProvider;
+  modelFamily: StoredModelFamily;
+  effort: StoredEffort;
+  measurementProfileVersion: string;
+  metricDefinitionVersion: string;
+  qualityRubricId: string;
+}
+
+export interface ComparableObservation {
+  context: StoredComparableContext;
+  metric: {
+    name: string;
+    unit: StoredMetricUnit;
+    direction: StoredMetricDirection;
+    value: number;
+  };
+  quality: {
+    score: number;
+    passed: StoredQualityPass;
+    evidenceCount: number;
+  };
+  evidence: {
+    coverage: StoredCoverage;
+    confidence: StoredConfidence;
+    qualityFlags: string[];
+  };
+  observedAtEpochMs: number;
+}
+
+export interface ComparablePairBuildInput {
+  adviceId: string;
+  recommendationId: string;
+  recommendationVersion: string;
+  before: ComparableObservation;
+  after: ComparableObservation;
+  recordedAtEpochMs: number;
+}
+
+export interface StoredComparablePair {
+  pairId: string;
+  adviceId: string;
+  recommendationId: string;
+  recommendationVersion: string;
+  context: StoredComparableContext;
+  metric: {
+    name: string;
+    unit: StoredMetricUnit;
+    direction: StoredMetricDirection;
+    beforeValue: number;
+    afterValue: number;
+  };
+  quality: {
+    beforeScore: number;
+    afterScore: number;
+    beforePassed: StoredQualityPass;
+    afterPassed: StoredQualityPass;
+    beforeEvidenceCount: number;
+    afterEvidenceCount: number;
+  };
+  evidence: {
+    beforeCoverage: StoredCoverage;
+    afterCoverage: StoredCoverage;
+    beforeConfidence: StoredConfidence;
+    afterConfidence: StoredConfidence;
+    beforeQualityFlags: string[];
+    afterQualityFlags: string[];
+  };
+  recordedAtEpochMs: number;
+}
+
+export type ComparablePairEvidenceIssue =
+  | 'scope-mismatch'
+  | 'task-kind-mismatch'
+  | 'complexity-mismatch'
+  | 'provider-mismatch'
+  | 'model-mismatch'
+  | 'effort-mismatch'
+  | 'measurement-profile-mismatch'
+  | 'metric-definition-mismatch'
+  | 'quality-rubric-mismatch'
+  | 'metric-name-mismatch'
+  | 'metric-unit-mismatch'
+  | 'metric-direction-mismatch'
+  | 'incomplete-coverage'
+  | 'insufficient-confidence'
+  | 'unresolved-quality-flags'
+  | 'unknown-quality-result'
+  | 'missing-quality-evidence'
+  | 'failed-quality-baseline'
+  | 'unknown-effort'
+  | 'zero-metric-baseline'
+  | 'invalid-observation-order';
+
+export type ComparablePairBuildResult =
+  | { ok: true; value: StoredComparablePair }
+  | {
+      ok: false;
+      reason: 'invalid-input';
+      issues: ['invalid-sanitized-observation'];
+    }
+  | {
+      ok: false;
+      reason: 'evidence-insufficient';
+      issues: ComparablePairEvidenceIssue[];
+    };
+
+const BUILD_INPUT_KEYS = [
+  'adviceId',
+  'after',
+  'before',
+  'recommendationId',
+  'recommendationVersion',
+  'recordedAtEpochMs',
+] as const;
+const OBSERVATION_KEYS = ['context', 'evidence', 'metric', 'observedAtEpochMs', 'quality'] as const;
+const CONTEXT_KEYS = [
+  'complexityBand',
+  'effort',
+  'measurementProfileVersion',
+  'metricDefinitionVersion',
+  'modelFamily',
+  'provider',
+  'qualityRubricId',
+  'scope',
+  'taskKind',
+] as const;
+const OBSERVATION_METRIC_KEYS = ['direction', 'name', 'unit', 'value'] as const;
+const OBSERVATION_QUALITY_KEYS = ['evidenceCount', 'passed', 'score'] as const;
+const OBSERVATION_EVIDENCE_KEYS = ['confidence', 'coverage', 'qualityFlags'] as const;
+const PAIR_KEYS = [
+  'adviceId',
+  'context',
+  'evidence',
+  'metric',
+  'pairId',
+  'quality',
+  'recommendationId',
+  'recommendationVersion',
+  'recordedAtEpochMs',
+] as const;
+const PAIR_METRIC_KEYS = ['afterValue', 'beforeValue', 'direction', 'name', 'unit'] as const;
+const PAIR_QUALITY_KEYS = [
+  'afterEvidenceCount',
+  'afterPassed',
+  'afterScore',
+  'beforeEvidenceCount',
+  'beforePassed',
+  'beforeScore',
+] as const;
+const PAIR_EVIDENCE_KEYS = [
+  'afterConfidence',
+  'afterCoverage',
+  'afterQualityFlags',
+  'beforeConfidence',
+  'beforeCoverage',
+  'beforeQualityFlags',
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const keys = [...expected].sort();
+  return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+
+function oneOf<T extends string>(value: unknown, values: readonly T[]): value is T {
+  return typeof value === 'string' && (values as readonly string[]).includes(value);
+}
+
+function isEpochMs(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+function isFiniteNonNegative(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function isScore(value: unknown): value is number {
+  return isFiniteNonNegative(value) && value <= 1;
+}
+
+function parseQualityFlags(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length > 32) return undefined;
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const flag of value) {
+    if (typeof flag !== 'string' || !isAdviceIdentifier(flag) || seen.has(flag)) return undefined;
+    seen.add(flag);
+    result.push(flag);
+  }
+  return result;
+}
+
+function parseContext(value: unknown): StoredComparableContext | undefined {
+  if (!isObject(value) || !hasExactKeys(value, CONTEXT_KEYS)) return undefined;
+  if (
+    !oneOf(value.scope, ['overall', 'project', 'task-cohort'] as const) ||
+    !oneOf(value.taskKind, ['small-change', 'feature', 'bug-fix', 'review', 'other'] as const) ||
+    !oneOf(value.complexityBand, ['low', 'medium', 'high'] as const) ||
+    !oneOf(value.provider, ['claude', 'codex'] as const) ||
+    !oneOf(value.modelFamily, ['opus', 'sonnet', 'haiku', 'fable', 'other'] as const) ||
+    !oneOf(value.effort, ['low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'unknown'] as const) ||
+    typeof value.measurementProfileVersion !== 'string' ||
+    typeof value.metricDefinitionVersion !== 'string' ||
+    typeof value.qualityRubricId !== 'string' ||
+    !isAdviceIdentifier(value.measurementProfileVersion) ||
+    !isAdviceIdentifier(value.metricDefinitionVersion) ||
+    !isAdviceIdentifier(value.qualityRubricId)
+  ) {
+    return undefined;
+  }
+  return {
+    scope: value.scope,
+    taskKind: value.taskKind,
+    complexityBand: value.complexityBand,
+    provider: value.provider,
+    modelFamily: value.modelFamily,
+    effort: value.effort,
+    measurementProfileVersion: value.measurementProfileVersion,
+    metricDefinitionVersion: value.metricDefinitionVersion,
+    qualityRubricId: value.qualityRubricId,
+  };
+}
+
+function parseObservation(value: unknown): ComparableObservation | undefined {
+  if (!isObject(value) || !hasExactKeys(value, OBSERVATION_KEYS)) return undefined;
+  const context = parseContext(value.context);
+  if (
+    !context ||
+    !isObject(value.metric) ||
+    !hasExactKeys(value.metric, OBSERVATION_METRIC_KEYS) ||
+    !isObject(value.quality) ||
+    !hasExactKeys(value.quality, OBSERVATION_QUALITY_KEYS) ||
+    !isObject(value.evidence) ||
+    !hasExactKeys(value.evidence, OBSERVATION_EVIDENCE_KEYS) ||
+    !isEpochMs(value.observedAtEpochMs)
+  ) {
+    return undefined;
+  }
+  const metric = value.metric;
+  const quality = value.quality;
+  const evidence = value.evidence;
+  if (
+    typeof metric.name !== 'string' ||
+    !isAdviceIdentifier(metric.name) ||
+    !oneOf(metric.unit, ['count', 'tokens', 'ratio', 'multiple', 'milliseconds'] as const) ||
+    !oneOf(metric.direction, ['lower-is-better', 'higher-is-better'] as const) ||
+    !isFiniteNonNegative(metric.value) ||
+    !isScore(quality.score) ||
+    !oneOf(quality.passed, ['passed', 'failed', 'unknown'] as const) ||
+    !isEpochMs(quality.evidenceCount) ||
+    !oneOf(evidence.coverage, ['complete', 'partial', 'unknown'] as const) ||
+    !oneOf(evidence.confidence, ['high', 'medium', 'low', 'unknown'] as const)
+  ) {
+    return undefined;
+  }
+  const qualityFlags = parseQualityFlags(evidence.qualityFlags);
+  if (!qualityFlags) return undefined;
+  return {
+    context,
+    metric: {
+      name: metric.name,
+      unit: metric.unit,
+      direction: metric.direction,
+      value: metric.value,
+    },
+    quality: {
+      score: quality.score,
+      passed: quality.passed,
+      evidenceCount: quality.evidenceCount,
+    },
+    evidence: {
+      coverage: evidence.coverage,
+      confidence: evidence.confidence,
+      qualityFlags,
+    },
+    observedAtEpochMs: value.observedAtEpochMs,
+  };
+}
+
+/** Strictly parse the content-free persisted representation and clone its arrays. */
+export function parseStoredComparablePair(value: unknown): StoredComparablePair | undefined {
+  if (!isObject(value) || !hasExactKeys(value, PAIR_KEYS)) return undefined;
+  if (
+    typeof value.pairId !== 'string' ||
+    typeof value.adviceId !== 'string' ||
+    typeof value.recommendationId !== 'string' ||
+    typeof value.recommendationVersion !== 'string' ||
+    !isAdviceIdentifier(value.pairId) ||
+    !isAdviceIdentifier(value.adviceId) ||
+    !isAdviceIdentifier(value.recommendationId) ||
+    !isAdviceIdentifier(value.recommendationVersion) ||
+    !isEpochMs(value.recordedAtEpochMs)
+  ) {
+    return undefined;
+  }
+  const context = parseContext(value.context);
+  if (
+    !context ||
+    !isObject(value.metric) ||
+    !hasExactKeys(value.metric, PAIR_METRIC_KEYS) ||
+    !isObject(value.quality) ||
+    !hasExactKeys(value.quality, PAIR_QUALITY_KEYS) ||
+    !isObject(value.evidence) ||
+    !hasExactKeys(value.evidence, PAIR_EVIDENCE_KEYS)
+  ) {
+    return undefined;
+  }
+  const metric = value.metric;
+  const quality = value.quality;
+  const evidence = value.evidence;
+  if (
+    typeof metric.name !== 'string' ||
+    !isAdviceIdentifier(metric.name) ||
+    !oneOf(metric.unit, ['count', 'tokens', 'ratio', 'multiple', 'milliseconds'] as const) ||
+    !oneOf(metric.direction, ['lower-is-better', 'higher-is-better'] as const) ||
+    !isFiniteNonNegative(metric.beforeValue) ||
+    !isFiniteNonNegative(metric.afterValue) ||
+    !isScore(quality.beforeScore) ||
+    !isScore(quality.afterScore) ||
+    !oneOf(quality.beforePassed, ['passed', 'failed', 'unknown'] as const) ||
+    !oneOf(quality.afterPassed, ['passed', 'failed', 'unknown'] as const) ||
+    !isEpochMs(quality.beforeEvidenceCount) ||
+    !isEpochMs(quality.afterEvidenceCount) ||
+    !oneOf(evidence.beforeCoverage, ['complete', 'partial', 'unknown'] as const) ||
+    !oneOf(evidence.afterCoverage, ['complete', 'partial', 'unknown'] as const) ||
+    !oneOf(evidence.beforeConfidence, ['high', 'medium', 'low', 'unknown'] as const) ||
+    !oneOf(evidence.afterConfidence, ['high', 'medium', 'low', 'unknown'] as const)
+  ) {
+    return undefined;
+  }
+  const beforeQualityFlags = parseQualityFlags(evidence.beforeQualityFlags);
+  const afterQualityFlags = parseQualityFlags(evidence.afterQualityFlags);
+  if (!beforeQualityFlags || !afterQualityFlags) return undefined;
+  return {
+    pairId: value.pairId,
+    adviceId: value.adviceId,
+    recommendationId: value.recommendationId,
+    recommendationVersion: value.recommendationVersion,
+    context,
+    metric: {
+      name: metric.name,
+      unit: metric.unit,
+      direction: metric.direction,
+      beforeValue: metric.beforeValue,
+      afterValue: metric.afterValue,
+    },
+    quality: {
+      beforeScore: quality.beforeScore,
+      afterScore: quality.afterScore,
+      beforePassed: quality.beforePassed,
+      afterPassed: quality.afterPassed,
+      beforeEvidenceCount: quality.beforeEvidenceCount,
+      afterEvidenceCount: quality.afterEvidenceCount,
+    },
+    evidence: {
+      beforeCoverage: evidence.beforeCoverage,
+      afterCoverage: evidence.afterCoverage,
+      beforeConfidence: evidence.beforeConfidence,
+      afterConfidence: evidence.afterConfidence,
+      beforeQualityFlags,
+      afterQualityFlags,
+    },
+    recordedAtEpochMs: value.recordedAtEpochMs,
+  };
+}
+
+function mismatchIssues(before: ComparableObservation, after: ComparableObservation): ComparablePairEvidenceIssue[] {
+  const issues: ComparablePairEvidenceIssue[] = [];
+  const compare = <T>(left: T, right: T, issue: ComparablePairEvidenceIssue): void => {
+    if (left !== right) issues.push(issue);
+  };
+  compare(before.context.scope, after.context.scope, 'scope-mismatch');
+  compare(before.context.taskKind, after.context.taskKind, 'task-kind-mismatch');
+  compare(before.context.complexityBand, after.context.complexityBand, 'complexity-mismatch');
+  compare(before.context.provider, after.context.provider, 'provider-mismatch');
+  compare(before.context.modelFamily, after.context.modelFamily, 'model-mismatch');
+  compare(before.context.effort, after.context.effort, 'effort-mismatch');
+  compare(
+    before.context.measurementProfileVersion,
+    after.context.measurementProfileVersion,
+    'measurement-profile-mismatch',
+  );
+  compare(
+    before.context.metricDefinitionVersion,
+    after.context.metricDefinitionVersion,
+    'metric-definition-mismatch',
+  );
+  compare(before.context.qualityRubricId, after.context.qualityRubricId, 'quality-rubric-mismatch');
+  compare(before.metric.name, after.metric.name, 'metric-name-mismatch');
+  compare(before.metric.unit, after.metric.unit, 'metric-unit-mismatch');
+  compare(before.metric.direction, after.metric.direction, 'metric-direction-mismatch');
+  return issues;
+}
+
+function reliabilityIssues(
+  before: ComparableObservation,
+  after: ComparableObservation,
+  recordedAtEpochMs: number,
+): ComparablePairEvidenceIssue[] {
+  const issues: ComparablePairEvidenceIssue[] = [];
+  const add = (issue: ComparablePairEvidenceIssue): void => {
+    if (!issues.includes(issue)) issues.push(issue);
+  };
+  for (const observation of [before, after]) {
+    if (observation.evidence.coverage !== 'complete') add('incomplete-coverage');
+    if (observation.evidence.confidence === 'low' || observation.evidence.confidence === 'unknown') {
+      add('insufficient-confidence');
+    }
+    if (observation.evidence.qualityFlags.length > 0) add('unresolved-quality-flags');
+    if (observation.quality.passed === 'unknown') add('unknown-quality-result');
+    if (observation.quality.evidenceCount < 1) add('missing-quality-evidence');
+  }
+  if (before.quality.passed === 'failed') add('failed-quality-baseline');
+  if (before.context.effort === 'unknown') add('unknown-effort');
+  if (before.metric.value === 0) add('zero-metric-baseline');
+  if (
+    before.observedAtEpochMs >= after.observedAtEpochMs ||
+    recordedAtEpochMs < after.observedAtEpochMs
+  ) {
+    add('invalid-observation-order');
+  }
+  return issues;
+}
+
+function pairDigest(value: Omit<StoredComparablePair, 'pairId'>): string {
+  return createHash('sha256').update(JSON.stringify(value), 'utf8').digest('hex').slice(0, 32);
+}
+
+/**
+ * Pair two already-sanitized observations. Comparability and reliability are
+ * proven from coarse machine fields; free text, paths, and session identifiers
+ * are not part of this boundary and make the exact parser fail.
+ */
+export function buildComparableTaskPair(input: unknown): ComparablePairBuildResult {
+  if (!isObject(input) || !hasExactKeys(input, BUILD_INPUT_KEYS)) {
+    return { ok: false, reason: 'invalid-input', issues: ['invalid-sanitized-observation'] };
+  }
+  const before = parseObservation(input.before);
+  const after = parseObservation(input.after);
+  if (
+    typeof input.adviceId !== 'string' ||
+    typeof input.recommendationId !== 'string' ||
+    typeof input.recommendationVersion !== 'string' ||
+    !isAdviceIdentifier(input.adviceId) ||
+    !isAdviceIdentifier(input.recommendationId) ||
+    !isAdviceIdentifier(input.recommendationVersion) ||
+    !isEpochMs(input.recordedAtEpochMs) ||
+    !before ||
+    !after
+  ) {
+    return { ok: false, reason: 'invalid-input', issues: ['invalid-sanitized-observation'] };
+  }
+  const issues = [
+    ...mismatchIssues(before, after),
+    ...reliabilityIssues(before, after, input.recordedAtEpochMs),
+  ];
+  if (issues.length > 0) return { ok: false, reason: 'evidence-insufficient', issues };
+
+  const pairWithoutId: Omit<StoredComparablePair, 'pairId'> = {
+    adviceId: input.adviceId,
+    recommendationId: input.recommendationId,
+    recommendationVersion: input.recommendationVersion,
+    context: { ...before.context },
+    metric: {
+      name: before.metric.name,
+      unit: before.metric.unit,
+      direction: before.metric.direction,
+      beforeValue: before.metric.value,
+      afterValue: after.metric.value,
+    },
+    quality: {
+      beforeScore: before.quality.score,
+      afterScore: after.quality.score,
+      beforePassed: before.quality.passed,
+      afterPassed: after.quality.passed,
+      beforeEvidenceCount: before.quality.evidenceCount,
+      afterEvidenceCount: after.quality.evidenceCount,
+    },
+    evidence: {
+      beforeCoverage: before.evidence.coverage,
+      afterCoverage: after.evidence.coverage,
+      beforeConfidence: before.evidence.confidence,
+      afterConfidence: after.evidence.confidence,
+      beforeQualityFlags: [...before.evidence.qualityFlags],
+      afterQualityFlags: [...after.evidence.qualityFlags],
+    },
+    recordedAtEpochMs: input.recordedAtEpochMs,
+  };
+  return {
+    ok: true,
+    value: { pairId: `pair-${pairDigest(pairWithoutId)}`, ...pairWithoutId },
+  };
+}
+
+/** Convert only state that has already passed the exact persistence parser. */
+export function toComparableTaskPairs(pairs: readonly StoredComparablePair[]): ComparableTaskPair[] {
+  return pairs.map((pair) => {
+    const context = {
+      taskKind: pair.context.taskKind,
+      complexityBand: pair.context.complexityBand,
+      provider: pair.context.provider,
+      modelFamily: pair.context.modelFamily,
+      effort: pair.context.effort,
+      metricDefinitionVersion: pair.context.metricDefinitionVersion,
+      qualityRubricId: pair.context.qualityRubricId,
+    };
+    const outcome = (period: 'before' | 'after'): ComparableTaskPair['before'] => ({
+      context: { ...context },
+      primaryMetric: {
+        name: pair.metric.name,
+        unit: pair.metric.unit,
+        direction: pair.metric.direction,
+        value: period === 'before' ? pair.metric.beforeValue : pair.metric.afterValue,
+      },
+      quality: {
+        score: period === 'before' ? pair.quality.beforeScore : pair.quality.afterScore,
+        passed: (() => {
+          const value = period === 'before' ? pair.quality.beforePassed : pair.quality.afterPassed;
+          return value === 'unknown' ? null : value === 'passed';
+        })(),
+        evidenceCount:
+          period === 'before' ? pair.quality.beforeEvidenceCount : pair.quality.afterEvidenceCount,
+      },
+      evidence: {
+        coverage: period === 'before' ? pair.evidence.beforeCoverage : pair.evidence.afterCoverage,
+        confidence:
+          period === 'before' ? pair.evidence.beforeConfidence : pair.evidence.afterConfidence,
+        qualityFlags: [
+          ...(period === 'before'
+            ? pair.evidence.beforeQualityFlags
+            : pair.evidence.afterQualityFlags),
+        ],
+      },
+    });
+    return { pairId: pair.pairId, before: outcome('before'), after: outcome('after') };
+  });
+}
diff --git a/src/adviceEffectiveness/comparisonProduction.ts b/src/adviceEffectiveness/comparisonProduction.ts
new file mode 100644
index 00000000..56e7dc5c
--- /dev/null
+++ b/src/adviceEffectiveness/comparisonProduction.ts
@@ -0,0 +1,413 @@
+import { isAdviceIdentifier } from './contract';
+import {
+  ComparableObservation,
+  StoredComparablePair,
+  StoredEffort,
+  StoredModelFamily,
+  buildComparableTaskPair,
+} from './comparisonPairing';
+
+export const CODEX_COMPARISON_MEASUREMENT_PROFILE_VERSION = 'codex-task-structural-v1';
+export const CODEX_LOCAL_RECOMMENDATION_VERSION = 'codex-local-rule-v1';
+
+export type ComparableCodexRecommendationId =
+  | 'recommendation-codex-multi-agent-share'
+  | 'recommendation-codex-effort-comparison'
+  | 'recommendation-codex-post-patch-tool-intensity'
+  | 'recommendation-codex-cache-context'
+  | 'recommendation-codex-approval-reviewer-share';
+
+export interface CodexComparableTaskProjection {
+  observedAtEpochMs: number;
+  total: {
+    processed: number;
+    fresh: number;
+  };
+  structural: {
+    patchCalls: number;
+    toolCalls: number;
+    postPatchToolCalls: number;
+    taskCompleteCount: number;
+  };
+  childFreshShare: number;
+  approvalReviewerFreshShare: number;
+  modelFamilies: StoredModelFamily[];
+  efforts: StoredEffort[];
+  coverage: {
+    complete: boolean;
+    identityComplete: boolean;
+    qualityFlags: string[];
+  };
+}
+
+export interface AppliedComparablePairsInput {
+  adviceId: string;
+  recommendationId: string;
+  recommendationVersion: string;
+  appliedAtEpochMs: number;
+  tasks: readonly CodexComparableTaskProjection[];
+}
+
+export type AppliedComparablePairsResult =
+  | {
+      ok: true;
+      status: 'comparable' | 'evidence-insufficient';
+      pairs: StoredComparablePair[];
+    }
+  | { ok: false; reason: 'invalid-input' };
+
+const INPUT_KEYS = [
+  'adviceId',
+  'appliedAtEpochMs',
+  'recommendationId',
+  'recommendationVersion',
+  'tasks',
+] as const;
+const TASK_KEYS = [
+  'approvalReviewerFreshShare',
+  'childFreshShare',
+  'coverage',
+  'efforts',
+  'modelFamilies',
+  'observedAtEpochMs',
+  'structural',
+  'total',
+] as const;
+const TOTAL_KEYS = ['fresh', 'processed'] as const;
+const STRUCTURAL_KEYS = [
+  'patchCalls',
+  'postPatchToolCalls',
+  'taskCompleteCount',
+  'toolCalls',
+] as const;
+const COVERAGE_KEYS = ['complete', 'identityComplete', 'qualityFlags'] as const;
+const RECOMMENDATION_IDS = new Set<ComparableCodexRecommendationId>([
+  'recommendation-codex-multi-agent-share',
+  'recommendation-codex-effort-comparison',
+  'recommendation-codex-post-patch-tool-intensity',
+  'recommendation-codex-cache-context',
+  'recommendation-codex-approval-reviewer-share',
+]);
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const keys = [...expected].sort();
+  return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+
+function isEpochMs(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+function isFiniteNonNegative(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function isCount(value: unknown): value is number {
+  return isFiniteNonNegative(value) && Number.isInteger(value);
+}
+
+function isShare(value: unknown): value is number {
+  return isFiniteNonNegative(value) && value <= 1;
+}
+
+function parseIdentifierList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length > 32) return undefined;
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== 'string' || !isAdviceIdentifier(item) || seen.has(item)) return undefined;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+
+function parseEnumList<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  maximum: number,
+): T[] | undefined {
+  if (!Array.isArray(value) || value.length > maximum) return undefined;
+  const result: T[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (
+      typeof item !== 'string' ||
+      !(allowed as readonly string[]).includes(item) ||
+      seen.has(item)
+    ) {
+      return undefined;
+    }
+    seen.add(item);
+    result.push(item as T);
+  }
+  return result;
+}
+
+function parseTask(value: unknown): CodexComparableTaskProjection | undefined {
+  if (!isObject(value) || !hasExactKeys(value, TASK_KEYS)) return undefined;
+  if (
+    !isEpochMs(value.observedAtEpochMs) ||
+    !isObject(value.total) ||
+    !hasExactKeys(value.total, TOTAL_KEYS) ||
+    !isObject(value.structural) ||
+    !hasExactKeys(value.structural, STRUCTURAL_KEYS) ||
+    !isObject(value.coverage) ||
+    !hasExactKeys(value.coverage, COVERAGE_KEYS) ||
+    !isFiniteNonNegative(value.total.processed) ||
+    !isFiniteNonNegative(value.total.fresh) ||
+    !isCount(value.structural.patchCalls) ||
+    !isCount(value.structural.toolCalls) ||
+    !isCount(value.structural.postPatchToolCalls) ||
+    !isCount(value.structural.taskCompleteCount) ||
+    !isShare(value.childFreshShare) ||
+    !isShare(value.approvalReviewerFreshShare) ||
+    typeof value.coverage.complete !== 'boolean' ||
+    typeof value.coverage.identityComplete !== 'boolean'
+  ) {
+    return undefined;
+  }
+  const modelFamilies = parseEnumList(
+    value.modelFamilies,
+    ['opus', 'sonnet', 'haiku', 'fable', 'other'] as const,
+    5,
+  );
+  const efforts = parseEnumList(
+    value.efforts,
+    ['low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'unknown'] as const,
+    7,
+  );
+  const qualityFlags = parseIdentifierList(value.coverage.qualityFlags);
+  if (!modelFamilies || !efforts || !qualityFlags) return undefined;
+  return {
+    observedAtEpochMs: value.observedAtEpochMs,
+    total: { processed: value.total.processed, fresh: value.total.fresh },
+    structural: {
+      patchCalls: value.structural.patchCalls,
+      toolCalls: value.structural.toolCalls,
+      postPatchToolCalls: value.structural.postPatchToolCalls,
+      taskCompleteCount: value.structural.taskCompleteCount,
+    },
+    childFreshShare: value.childFreshShare,
+    approvalReviewerFreshShare: value.approvalReviewerFreshShare,
+    modelFamilies,
+    efforts,
+    coverage: {
+      complete: value.coverage.complete,
+      identityComplete: value.coverage.identityComplete,
+      qualityFlags,
+    },
+  };
+}
+
+export function isComparableCodexRecommendationId(
+  value: string,
+): value is ComparableCodexRecommendationId {
+  return RECOMMENDATION_IDS.has(value as ComparableCodexRecommendationId);
+}
+
+function complexityBand(task: CodexComparableTaskProjection): 'low' | 'medium' | 'high' {
+  if (
+    task.structural.patchCalls === 1 &&
+    task.structural.toolCalls <= 8 &&
+    task.total.fresh <= 50_000
+  ) {
+    return 'low';
+  }
+  if (
+    task.structural.patchCalls <= 2 &&
+    task.structural.toolCalls <= 24 &&
+    task.total.fresh <= 200_000
+  ) {
+    return 'medium';
+  }
+  return 'high';
+}
+
+function metric(
+  recommendationId: ComparableCodexRecommendationId,
+  task: CodexComparableTaskProjection,
+): ComparableObservation['metric'] | undefined {
+  if (recommendationId === 'recommendation-codex-effort-comparison') {
+    return {
+      name: 'fresh-tokens',
+      unit: 'tokens',
+      direction: 'lower-is-better',
+      value: task.total.fresh,
+    };
+  }
+  if (recommendationId === 'recommendation-codex-post-patch-tool-intensity') {
+    return {
+      name: 'post-patch-tool-intensity',
+      unit: 'multiple',
+      direction: 'lower-is-better',
+      value: task.structural.postPatchToolCalls / task.structural.patchCalls,
+    };
+  }
+  if (recommendationId === 'recommendation-codex-multi-agent-share') {
+    return {
+      name: 'subagent-fresh-share',
+      unit: 'ratio',
+      direction: 'lower-is-better',
+      value: task.childFreshShare,
+    };
+  }
+  if (recommendationId === 'recommendation-codex-approval-reviewer-share') {
+    return {
+      name: 'approval-reviewer-fresh-share',
+      unit: 'ratio',
+      direction: 'lower-is-better',
+      value: task.approvalReviewerFreshShare,
+    };
+  }
+  if (task.total.fresh === 0) return undefined;
+  return {
+    name: 'processed-to-fresh-ratio',
+    unit: 'multiple',
+    direction: 'lower-is-better',
+    value: task.total.processed / task.total.fresh,
+  };
+}
+
+function observation(
+  recommendationId: ComparableCodexRecommendationId,
+  task: CodexComparableTaskProjection,
+): ComparableObservation | undefined {
+  if (
+    !task.coverage.complete ||
+    !task.coverage.identityComplete ||
+    task.coverage.qualityFlags.length > 0 ||
+    task.structural.taskCompleteCount < 1 ||
+    task.structural.patchCalls < 1 ||
+    task.structural.patchCalls > 2 ||
+    task.modelFamilies.length !== 1 ||
+    task.efforts.length !== 1 ||
+    task.efforts[0] === 'unknown'
+  ) {
+    return undefined;
+  }
+  const primaryMetric = metric(recommendationId, task);
+  if (!primaryMetric || !Number.isFinite(primaryMetric.value) || primaryMetric.value < 0) {
+    return undefined;
+  }
+  return {
+    context: {
+      scope: 'task-cohort',
+      taskKind: 'small-change',
+      complexityBand: complexityBand(task),
+      provider: 'codex',
+      modelFamily: task.modelFamilies[0],
+      effort: task.efforts[0],
+      measurementProfileVersion: CODEX_COMPARISON_MEASUREMENT_PROFILE_VERSION,
+      metricDefinitionVersion: `${primaryMetric.name}-v1`,
+      qualityRubricId: 'task-quality-rubric-v1',
+    },
+    metric: primaryMetric,
+    quality: {
+      score: 1,
+      passed: 'passed',
+      evidenceCount: task.structural.taskCompleteCount,
+    },
+    evidence: { coverage: 'complete', confidence: 'high', qualityFlags: [] },
+    observedAtEpochMs: task.observedAtEpochMs,
+  };
+}
+
+function cohortKey(value: ComparableObservation): string {
+  return JSON.stringify({
+    context: value.context,
+    metric: {
+      name: value.metric.name,
+      unit: value.metric.unit,
+      direction: value.metric.direction,
+    },
+  });
+}
+
+/**
+ * Match already materialized, completed Codex task projections around one
+ * explicit applied event. No task key survives this boundary: observations are
+ * distinguished only by coarse context, numeric measurements, and timestamp.
+ */
+export function buildAppliedComparablePairs(input: unknown): AppliedComparablePairsResult {
+  if (!isObject(input) || !hasExactKeys(input, INPUT_KEYS)) {
+    return { ok: false, reason: 'invalid-input' };
+  }
+  if (
+    typeof input.adviceId !== 'string' ||
+    typeof input.recommendationId !== 'string' ||
+    typeof input.recommendationVersion !== 'string' ||
+    !isAdviceIdentifier(input.adviceId) ||
+    !isAdviceIdentifier(input.recommendationId) ||
+    !isAdviceIdentifier(input.recommendationVersion) ||
+    !isEpochMs(input.appliedAtEpochMs) ||
+    !Array.isArray(input.tasks) ||
+    input.tasks.length > 1_000
+  ) {
+    return { ok: false, reason: 'invalid-input' };
+  }
+  const tasks: CodexComparableTaskProjection[] = [];
+  for (const raw of input.tasks) {
+    const parsed = parseTask(raw);
+    if (!parsed) return { ok: false, reason: 'invalid-input' };
+    tasks.push(parsed);
+  }
+  if (!isComparableCodexRecommendationId(input.recommendationId)) {
+    return { ok: true, status: 'evidence-insufficient', pairs: [] };
+  }
+
+  const seen = new Set<string>();
+  const observations = tasks
+    .map((task) => observation(input.recommendationId as ComparableCodexRecommendationId, task))
+    .filter((item): item is ComparableObservation => item !== undefined)
+    .filter((item) => {
+      const key = JSON.stringify(item);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  const beforeByCohort = new Map<string, ComparableObservation[]>();
+  const afterByCohort = new Map<string, ComparableObservation[]>();
+  for (const item of observations) {
+    const target = item.observedAtEpochMs < input.appliedAtEpochMs
+      ? beforeByCohort
+      : item.observedAtEpochMs > input.appliedAtEpochMs
+        ? afterByCohort
+        : undefined;
+    if (!target) continue;
+    const key = cohortKey(item);
+    const cohort = target.get(key) ?? [];
+    cohort.push(item);
+    target.set(key, cohort);
+  }
+
+  const pairs: StoredComparablePair[] = [];
+  for (const [key, after] of [...afterByCohort.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    const before = beforeByCohort.get(key) ?? [];
+    before.sort((left, right) => right.observedAtEpochMs - left.observedAtEpochMs);
+    after.sort((left, right) => left.observedAtEpochMs - right.observedAtEpochMs);
+    const count = Math.min(before.length, after.length);
+    for (let index = 0; index < count; index += 1) {
+      const paired = buildComparableTaskPair({
+        adviceId: input.adviceId,
+        recommendationId: input.recommendationId,
+        recommendationVersion: input.recommendationVersion,
+        before: before[index],
+        after: after[index],
+        recordedAtEpochMs: after[index].observedAtEpochMs,
+      });
+      if (paired.ok) pairs.push(paired.value);
+    }
+  }
+  pairs.sort((left, right) => left.pairId.localeCompare(right.pairId));
+  return {
+    ok: true,
+    status: pairs.length > 0 ? 'comparable' : 'evidence-insufficient',
+    pairs,
+  };
+}
diff --git a/src/adviceEffectiveness/comparisonResult.ts b/src/adviceEffectiveness/comparisonResult.ts
new file mode 100644
index 00000000..09cd15cd
--- /dev/null
+++ b/src/adviceEffectiveness/comparisonResult.ts
@@ -0,0 +1,615 @@
+import { createHash } from 'node:crypto';
+
+import {
+  AdviceComparisonStats,
+  compareAdviceEffectiveness,
+} from './comparison';
+import { isAdviceIdentifier } from './contract';
+import {
+  StoredAdviceScope,
+  StoredComparablePair,
+  StoredComplexityBand,
+  StoredEffort,
+  StoredMetricDirection,
+  StoredMetricUnit,
+  StoredModelFamily,
+  StoredProvider,
+  StoredTaskKind,
+  parseStoredComparablePair,
+  toComparableTaskPairs,
+} from './comparisonPairing';
+
+export const ADVICE_COMPARISON_RESULT_VERSION = 1 as const;
+export const MAX_COMPARISON_RESULT_SAMPLE_PAIRS = 200;
+
+export interface AdviceComparisonGuardrail {
+  minComparablePairs: number;
+  minRelativeImprovement: number;
+  minAfterQualityScore: number;
+  maxMeanQualityRegression: number;
+  allowedQualityFlags: string[];
+  qualityRubricId: string;
+}
+
+export interface AdviceComparisonCohort {
+  scope: StoredAdviceScope;
+  taskKind: StoredTaskKind;
+  complexityBand: StoredComplexityBand;
+  modelFamily: StoredModelFamily;
+  effort: StoredEffort;
+  metricDefinitionVersion: string;
+  qualityRubricId: string;
+  metric: {
+    name: string;
+    unit: StoredMetricUnit;
+    direction: StoredMetricDirection;
+  };
+}
+
+export interface AdviceComparisonSample extends AdviceComparisonCohort {
+  pairIds: string[];
+  pairCount: number;
+}
+
+export type AdviceComparisonEvidenceReason =
+  | 'minimum-sample-not-met'
+  | 'incomparable-sample'
+  | 'unreliable-sample'
+  | 'comparison-inconclusive';
+
+export type FrozenAdviceComparisonResult =
+  | {
+      status: 'evidence-insufficient';
+      reasonCode: AdviceComparisonEvidenceReason;
+      comparablePairs: number;
+    }
+  | {
+      status: 'quality-guardrail-failed' | 'improved' | 'no-demonstrated-improvement';
+      stats: AdviceComparisonStats;
+    };
+
+export type AdviceComparisonReplayEligibility =
+  | { status: 'eligible'; reason: 'conclusive-result' }
+  | { status: 'ineligible'; reason: 'evidence-insufficient' };
+
+export interface AdviceComparisonResultEnvelope {
+  schemaVersion: typeof ADVICE_COMPARISON_RESULT_VERSION;
+  comparisonId: string;
+  provider: StoredProvider;
+  recommendationId: string;
+  recommendationVersion: string;
+  measurementProfileVersion: string;
+  guardrail: AdviceComparisonGuardrail;
+  replayEligibility: AdviceComparisonReplayEligibility;
+  sample: AdviceComparisonSample;
+  result: FrozenAdviceComparisonResult;
+  recordedAtEpochMs: number;
+}
+
+export interface AdviceComparisonResultBuildInput {
+  provider: StoredProvider;
+  recommendationId: string;
+  recommendationVersion: string;
+  measurementProfileVersion: string;
+  cohort: AdviceComparisonCohort;
+  guardrail: AdviceComparisonGuardrail;
+  pairs: readonly StoredComparablePair[];
+  recordedAtEpochMs: number;
+}
+
+export type AdviceComparisonResultBuildIssue =
+  | 'invalid-envelope-input'
+  | 'invalid-comparable-pair'
+  | 'duplicate-comparable-pair'
+  | 'comparison-precedes-sample';
+
+export type AdviceComparisonResultBuildResult =
+  | { ok: true; value: AdviceComparisonResultEnvelope }
+  | { ok: false; reason: 'invalid-input'; issues: AdviceComparisonResultBuildIssue[] };
+
+const BUILD_KEYS = [
+  'cohort',
+  'guardrail',
+  'measurementProfileVersion',
+  'pairs',
+  'provider',
+  'recommendationId',
+  'recommendationVersion',
+  'recordedAtEpochMs',
+] as const;
+const ENVELOPE_KEYS = [
+  'comparisonId',
+  'guardrail',
+  'measurementProfileVersion',
+  'provider',
+  'recommendationId',
+  'recommendationVersion',
+  'recordedAtEpochMs',
+  'replayEligibility',
+  'result',
+  'sample',
+  'schemaVersion',
+] as const;
+const GUARDRAIL_KEYS = [
+  'allowedQualityFlags',
+  'maxMeanQualityRegression',
+  'minAfterQualityScore',
+  'minComparablePairs',
+  'minRelativeImprovement',
+  'qualityRubricId',
+] as const;
+const COHORT_KEYS = [
+  'complexityBand',
+  'effort',
+  'metric',
+  'metricDefinitionVersion',
+  'modelFamily',
+  'qualityRubricId',
+  'scope',
+  'taskKind',
+] as const;
+const SAMPLE_KEYS = [...COHORT_KEYS, 'pairCount', 'pairIds'] as const;
+const METRIC_KEYS = ['direction', 'name', 'unit'] as const;
+const REPLAY_KEYS = ['reason', 'status'] as const;
+const INSUFFICIENT_RESULT_KEYS = ['comparablePairs', 'reasonCode', 'status'] as const;
+const CONCLUSIVE_RESULT_KEYS = ['stats', 'status'] as const;
+const STATS_KEYS = [
+  'comparablePairs',
+  'meanAfterQuality',
+  'meanAfterValue',
+  'meanBeforeQuality',
+  'meanBeforeValue',
+  'meanQualityChange',
+  'meanRelativeImprovement',
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const keys = [...expected].sort();
+  return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+
+function oneOf<T extends string>(value: unknown, values: readonly T[]): value is T {
+  return typeof value === 'string' && (values as readonly string[]).includes(value);
+}
+
+function isEpochMs(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isFiniteNonNegative(value: unknown): value is number {
+  return isFiniteNumber(value) && value >= 0;
+}
+
+function isScore(value: unknown): value is number {
+  return isFiniteNonNegative(value) && value <= 1;
+}
+
+function parseIdentifierList(value: unknown, maximum: number): string[] | undefined {
+  if (!Array.isArray(value) || value.length > maximum) return undefined;
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== 'string' || !isAdviceIdentifier(item) || seen.has(item)) return undefined;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+
+function parseGuardrail(value: unknown): AdviceComparisonGuardrail | undefined {
+  if (!isObject(value) || !hasExactKeys(value, GUARDRAIL_KEYS)) return undefined;
+  if (
+    !Number.isInteger(value.minComparablePairs) ||
+    (value.minComparablePairs as number) < 2 ||
+    !isFiniteNonNegative(value.minRelativeImprovement) ||
+    !isScore(value.minAfterQualityScore) ||
+    !isScore(value.maxMeanQualityRegression) ||
+    typeof value.qualityRubricId !== 'string' ||
+    !isAdviceIdentifier(value.qualityRubricId)
+  ) {
+    return undefined;
+  }
+  const allowedQualityFlags = parseIdentifierList(value.allowedQualityFlags, 32);
+  if (!allowedQualityFlags) return undefined;
+  return {
+    minComparablePairs: value.minComparablePairs as number,
+    minRelativeImprovement: value.minRelativeImprovement,
+    minAfterQualityScore: value.minAfterQualityScore,
+    maxMeanQualityRegression: value.maxMeanQualityRegression,
+    allowedQualityFlags,
+    qualityRubricId: value.qualityRubricId,
+  };
+}
+
+function parseMetric(value: unknown): AdviceComparisonCohort['metric'] | undefined {
+  if (!isObject(value) || !hasExactKeys(value, METRIC_KEYS)) return undefined;
+  if (
+    typeof value.name !== 'string' ||
+    !isAdviceIdentifier(value.name) ||
+    !oneOf(value.unit, ['count', 'tokens', 'ratio', 'multiple', 'milliseconds'] as const) ||
+    !oneOf(value.direction, ['lower-is-better', 'higher-is-better'] as const)
+  ) {
+    return undefined;
+  }
+  return { name: value.name, unit: value.unit, direction: value.direction };
+}
+
+function parseCohort(value: unknown): AdviceComparisonCohort | undefined {
+  if (!isObject(value) || !hasExactKeys(value, COHORT_KEYS)) return undefined;
+  const metric = parseMetric(value.metric);
+  if (
+    !metric ||
+    !oneOf(value.scope, ['overall', 'project', 'task-cohort'] as const) ||
+    !oneOf(value.taskKind, ['small-change', 'feature', 'bug-fix', 'review', 'other'] as const) ||
+    !oneOf(value.complexityBand, ['low', 'medium', 'high'] as const) ||
+    !oneOf(value.modelFamily, ['opus', 'sonnet', 'haiku', 'fable', 'other'] as const) ||
+    !oneOf(value.effort, ['low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'unknown'] as const) ||
+    typeof value.metricDefinitionVersion !== 'string' ||
+    typeof value.qualityRubricId !== 'string' ||
+    !isAdviceIdentifier(value.metricDefinitionVersion) ||
+    !isAdviceIdentifier(value.qualityRubricId)
+  ) {
+    return undefined;
+  }
+  return {
+    scope: value.scope,
+    taskKind: value.taskKind,
+    complexityBand: value.complexityBand,
+    modelFamily: value.modelFamily,
+    effort: value.effort,
+    metricDefinitionVersion: value.metricDefinitionVersion,
+    qualityRubricId: value.qualityRubricId,
+    metric,
+  };
+}
+
+function parseSample(value: unknown): AdviceComparisonSample | undefined {
+  if (!isObject(value) || !hasExactKeys(value, SAMPLE_KEYS)) return undefined;
+  const cohortCandidate: Record<string, unknown> = {};
+  for (const key of COHORT_KEYS) cohortCandidate[key] = value[key];
+  const cohort = parseCohort(cohortCandidate);
+  const pairIds = parseIdentifierList(value.pairIds, MAX_COMPARISON_RESULT_SAMPLE_PAIRS);
+  if (
+    !cohort ||
+    !pairIds ||
+    !Number.isInteger(value.pairCount) ||
+    (value.pairCount as number) < 0 ||
+    value.pairCount !== pairIds.length
+  ) {
+    return undefined;
+  }
+  return { ...cohort, pairIds, pairCount: value.pairCount as number };
+}
+
+function parseStats(value: unknown): AdviceComparisonStats | undefined {
+  if (!isObject(value) || !hasExactKeys(value, STATS_KEYS)) return undefined;
+  if (
+    !Number.isInteger(value.comparablePairs) ||
+    (value.comparablePairs as number) < 0 ||
+    !isFiniteNonNegative(value.meanBeforeValue) ||
+    !isFiniteNonNegative(value.meanAfterValue) ||
+    !isFiniteNumber(value.meanRelativeImprovement) ||
+    !isScore(value.meanBeforeQuality) ||
+    !isScore(value.meanAfterQuality) ||
+    !isFiniteNumber(value.meanQualityChange) ||
+    value.meanQualityChange < -1 ||
+    value.meanQualityChange > 1
+  ) {
+    return undefined;
+  }
+  return {
+    comparablePairs: value.comparablePairs as number,
+    meanBeforeValue: value.meanBeforeValue,
+    meanAfterValue: value.meanAfterValue,
+    meanRelativeImprovement: value.meanRelativeImprovement,
+    meanBeforeQuality: value.meanBeforeQuality,
+    meanAfterQuality: value.meanAfterQuality,
+    meanQualityChange: value.meanQualityChange,
+  };
+}
+
+function parseResult(value: unknown): FrozenAdviceComparisonResult | undefined {
+  if (!isObject(value) || typeof value.status !== 'string') return undefined;
+  if (value.status === 'evidence-insufficient') {
+    if (
+      !hasExactKeys(value, INSUFFICIENT_RESULT_KEYS) ||
+      !oneOf(value.reasonCode, [
+        'minimum-sample-not-met',
+        'incomparable-sample',
+        'unreliable-sample',
+        'comparison-inconclusive',
+      ] as const) ||
+      !Number.isInteger(value.comparablePairs) ||
+      (value.comparablePairs as number) < 0
+    ) {
+      return undefined;
+    }
+    return {
+      status: value.status,
+      reasonCode: value.reasonCode,
+      comparablePairs: value.comparablePairs as number,
+    };
+  }
+  if (
+    !oneOf(value.status, [
+      'quality-guardrail-failed',
+      'improved',
+      'no-demonstrated-improvement',
+    ] as const) ||
+    !hasExactKeys(value, CONCLUSIVE_RESULT_KEYS)
+  ) {
+    return undefined;
+  }
+  const stats = parseStats(value.stats);
+  if (!stats) return undefined;
+  return { status: value.status, stats };
+}
+
+function parseReplayEligibility(value: unknown): AdviceComparisonReplayEligibility | undefined {
+  if (!isObject(value) || !hasExactKeys(value, REPLAY_KEYS)) return undefined;
+  if (value.status === 'eligible' && value.reason === 'conclusive-result') {
+    return { status: value.status, reason: value.reason };
+  }
+  if (value.status === 'ineligible' && value.reason === 'evidence-insufficient') {
+    return { status: value.status, reason: value.reason };
+  }
+  return undefined;
+}
+
+function canonicalJson(value: unknown): string {
+  const canonicalize = (current: unknown): unknown => {
+    if (Array.isArray(current)) return current.map(canonicalize);
+    if (isObject(current)) {
+      const result: Record<string, unknown> = {};
+      for (const key of Object.keys(current).sort()) result[key] = canonicalize(current[key]);
+      return result;
+    }
+    return current;
+  };
+  return JSON.stringify(canonicalize(value));
+}
+
+function comparisonId(value: Omit<AdviceComparisonResultEnvelope, 'comparisonId'>): string {
+  const digest = createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex').slice(0, 32);
+  return `comparison-${digest}`;
+}
+
+/** Parse, clone, and verify the entire frozen envelope, including its digest. */
+export function parseAdviceComparisonResultEnvelope(
+  value: unknown,
+): AdviceComparisonResultEnvelope | undefined {
+  if (!isObject(value) || !hasExactKeys(value, ENVELOPE_KEYS)) return undefined;
+  if (
+    value.schemaVersion !== ADVICE_COMPARISON_RESULT_VERSION ||
+    typeof value.comparisonId !== 'string' ||
+    typeof value.recommendationId !== 'string' ||
+    typeof value.recommendationVersion !== 'string' ||
+    typeof value.measurementProfileVersion !== 'string' ||
+    !isAdviceIdentifier(value.comparisonId) ||
+    !oneOf(value.provider, ['claude', 'codex'] as const) ||
+    !isAdviceIdentifier(value.recommendationId) ||
+    !isAdviceIdentifier(value.recommendationVersion) ||
+    !isAdviceIdentifier(value.measurementProfileVersion) ||
+    !isEpochMs(value.recordedAtEpochMs)
+  ) {
+    return undefined;
+  }
+  const guardrail = parseGuardrail(value.guardrail);
+  const sample = parseSample(value.sample);
+  const result = parseResult(value.result);
+  const replayEligibility = parseReplayEligibility(value.replayEligibility);
+  if (
+    !guardrail ||
+    !sample ||
+    !result ||
+    !replayEligibility ||
+    guardrail.qualityRubricId !== sample.qualityRubricId ||
+    (result.status === 'evidence-insufficient'
+      ? replayEligibility.status !== 'ineligible' || result.comparablePairs !== sample.pairCount
+      : replayEligibility.status !== 'eligible' || result.stats.comparablePairs !== sample.pairCount)
+  ) {
+    return undefined;
+  }
+  const withoutId: Omit<AdviceComparisonResultEnvelope, 'comparisonId'> = {
+    schemaVersion: ADVICE_COMPARISON_RESULT_VERSION,
+    provider: value.provider,
+    recommendationId: value.recommendationId,
+    recommendationVersion: value.recommendationVersion,
+    measurementProfileVersion: value.measurementProfileVersion,
+    guardrail,
+    replayEligibility,
+    sample,
+    result,
+    recordedAtEpochMs: value.recordedAtEpochMs,
+  };
+  if (value.comparisonId !== comparisonId(withoutId)) return undefined;
+  return { comparisonId: value.comparisonId, ...withoutId };
+}
+
+function pairMatchesCohort(
+  pair: StoredComparablePair,
+  input: {
+    provider: StoredProvider;
+    recommendationId: string;
+    recommendationVersion: string;
+    measurementProfileVersion: string;
+    cohort: AdviceComparisonCohort;
+  },
+): boolean {
+  return (
+    pair.context.provider === input.provider &&
+    pair.recommendationId === input.recommendationId &&
+    pair.recommendationVersion === input.recommendationVersion &&
+    pair.context.measurementProfileVersion === input.measurementProfileVersion &&
+    pair.context.scope === input.cohort.scope &&
+    pair.context.taskKind === input.cohort.taskKind &&
+    pair.context.complexityBand === input.cohort.complexityBand &&
+    pair.context.modelFamily === input.cohort.modelFamily &&
+    pair.context.effort === input.cohort.effort &&
+    pair.context.metricDefinitionVersion === input.cohort.metricDefinitionVersion &&
+    pair.context.qualityRubricId === input.cohort.qualityRubricId &&
+    pair.metric.name === input.cohort.metric.name &&
+    pair.metric.unit === input.cohort.metric.unit &&
+    pair.metric.direction === input.cohort.metric.direction
+  );
+}
+
+function pairIsReliable(pair: StoredComparablePair, allowedFlags: ReadonlySet<string>): boolean {
+  return (
+    pair.evidence.beforeCoverage === 'complete' &&
+    pair.evidence.afterCoverage === 'complete' &&
+    pair.evidence.beforeConfidence !== 'low' &&
+    pair.evidence.beforeConfidence !== 'unknown' &&
+    pair.evidence.afterConfidence !== 'low' &&
+    pair.evidence.afterConfidence !== 'unknown' &&
+    pair.evidence.beforeQualityFlags.every((flag) => allowedFlags.has(flag)) &&
+    pair.evidence.afterQualityFlags.every((flag) => allowedFlags.has(flag)) &&
+    pair.quality.beforePassed === 'passed' &&
+    pair.quality.afterPassed !== 'unknown' &&
+    pair.quality.beforeEvidenceCount > 0 &&
+    pair.quality.afterEvidenceCount > 0 &&
+    pair.context.effort !== 'unknown' &&
+    pair.metric.beforeValue > 0
+  );
+}
+
+/**
+ * Freeze a comparison result from one strict recommendation/cohort lineage.
+ * The envelope stores only coarse cohort fields, aggregate statistics, and
+ * opaque pair IDs; comparator prose is deliberately not persisted.
+ */
+export function buildAdviceComparisonResultEnvelope(
+  input: unknown,
+): AdviceComparisonResultBuildResult {
+  if (!isObject(input) || !hasExactKeys(input, BUILD_KEYS)) {
+    return { ok: false, reason: 'invalid-input', issues: ['invalid-envelope-input'] };
+  }
+  const cohort = parseCohort(input.cohort);
+  const guardrail = parseGuardrail(input.guardrail);
+  if (
+    !oneOf(input.provider, ['claude', 'codex'] as const) ||
+    typeof input.recommendationId !== 'string' ||
+    typeof input.recommendationVersion !== 'string' ||
+    typeof input.measurementProfileVersion !== 'string' ||
+    !isAdviceIdentifier(input.recommendationId) ||
+    !isAdviceIdentifier(input.recommendationVersion) ||
+    !isAdviceIdentifier(input.measurementProfileVersion) ||
+    !cohort ||
+    !guardrail ||
+    cohort.qualityRubricId !== guardrail.qualityRubricId ||
+    !Array.isArray(input.pairs) ||
+    input.pairs.length > MAX_COMPARISON_RESULT_SAMPLE_PAIRS ||
+    !isEpochMs(input.recordedAtEpochMs)
+  ) {
+    return { ok: false, reason: 'invalid-input', issues: ['invalid-envelope-input'] };
+  }
+  const provider = input.provider;
+  const recommendationId = input.recommendationId;
+  const recommendationVersion = input.recommendationVersion;
+  const measurementProfileVersion = input.measurementProfileVersion;
+  const recordedAtEpochMs = input.recordedAtEpochMs;
+
+  const pairs: StoredComparablePair[] = [];
+  const pairIds = new Set<string>();
+  for (const raw of input.pairs) {
+    const parsed = parseStoredComparablePair(raw);
+    if (!parsed) {
+      return { ok: false, reason: 'invalid-input', issues: ['invalid-comparable-pair'] };
+    }
+    if (pairIds.has(parsed.pairId)) {
+      return { ok: false, reason: 'invalid-input', issues: ['duplicate-comparable-pair'] };
+    }
+    if (parsed.recordedAtEpochMs > recordedAtEpochMs) {
+      return { ok: false, reason: 'invalid-input', issues: ['comparison-precedes-sample'] };
+    }
+    pairIds.add(parsed.pairId);
+    pairs.push(parsed);
+  }
+  pairs.sort((left, right) => left.pairId.localeCompare(right.pairId));
+
+  const sample: AdviceComparisonSample = {
+    ...cohort,
+    pairIds: pairs.map((pair) => pair.pairId),
+    pairCount: pairs.length,
+  };
+  let result: FrozenAdviceComparisonResult;
+  if (pairs.length < guardrail.minComparablePairs) {
+    result = {
+      status: 'evidence-insufficient',
+      reasonCode: 'minimum-sample-not-met',
+      comparablePairs: pairs.length,
+    };
+  } else if (
+    pairs.some((pair) =>
+      !pairMatchesCohort(pair, {
+        provider,
+        recommendationId,
+        recommendationVersion,
+        measurementProfileVersion,
+        cohort,
+      }),
+    )
+  ) {
+    result = {
+      status: 'evidence-insufficient',
+      reasonCode: 'incomparable-sample',
+      comparablePairs: pairs.length,
+    };
+  } else if (
+    pairs.some((pair) => !pairIsReliable(pair, new Set(guardrail.allowedQualityFlags)))
+  ) {
+    result = {
+      status: 'evidence-insufficient',
+      reasonCode: 'unreliable-sample',
+      comparablePairs: pairs.length,
+    };
+  } else {
+    const compared = compareAdviceEffectiveness(toComparableTaskPairs(pairs), {
+      minComparablePairs: guardrail.minComparablePairs,
+      minRelativeImprovement: guardrail.minRelativeImprovement,
+      minAfterQualityScore: guardrail.minAfterQualityScore,
+      maxMeanQualityRegression: guardrail.maxMeanQualityRegression,
+      allowedQualityFlags: [...guardrail.allowedQualityFlags],
+    });
+    result = compared.status === 'insufficient-evidence'
+      ? {
+          status: 'evidence-insufficient',
+          reasonCode: 'comparison-inconclusive',
+          comparablePairs: pairs.length,
+        }
+      : { status: compared.status, stats: { ...compared.stats } };
+  }
+  const replayEligibility: AdviceComparisonReplayEligibility =
+    result.status === 'evidence-insufficient'
+      ? { status: 'ineligible', reason: 'evidence-insufficient' }
+      : { status: 'eligible', reason: 'conclusive-result' };
+  const withoutId: Omit<AdviceComparisonResultEnvelope, 'comparisonId'> = {
+    schemaVersion: ADVICE_COMPARISON_RESULT_VERSION,
+    provider,
+    recommendationId,
+    recommendationVersion,
+    measurementProfileVersion,
+    guardrail,
+    replayEligibility,
+    sample,
+    result,
+    recordedAtEpochMs,
+  };
+  const envelope: AdviceComparisonResultEnvelope = {
+    comparisonId: comparisonId(withoutId),
+    ...withoutId,
+  };
+  const parsed = parseAdviceComparisonResultEnvelope(envelope);
+  return parsed
+    ? { ok: true, value: parsed }
+    : { ok: false, reason: 'invalid-input', issues: ['invalid-envelope-input'] };
+}
diff --git a/src/adviceEffectiveness/contract.ts b/src/adviceEffectiveness/contract.ts
new file mode 100644
index 00000000..58b78620
--- /dev/null
+++ b/src/adviceEffectiveness/contract.ts
@@ -0,0 +1,374 @@
+/**
+ * Versioned, provider-neutral contract for evidence-backed advice.
+ *
+ * The host owns observations, evidence, provenance, and privacy metadata. A
+ * remote model may only propose recommendations that reference those host-owned
+ * IDs; it never gets to manufacture measurements or claim its own provenance.
+ */
+
+export const ADVICE_CONTRACT_VERSION = 1 as const;
+
+export type AdviceScope = 'overall' | 'project' | 'task-cohort';
+
+export type AdviceWindow =
+  | { kind: 'rolling-days'; days: number }
+  | { kind: 'all-time' }
+  | { kind: 'task-cohort' };
+
+export type AdviceSourceKind =
+  | 'claude-usage-aggregate'
+  | 'claude-local-insight'
+  | 'codex-local-insight'
+  | 'task-comparison';
+
+export interface AdviceSourceInfo {
+  id: string;
+  kind: AdviceSourceKind;
+  scope: AdviceScope;
+  window: AdviceWindow;
+  confidence: 'high' | 'medium' | 'low' | 'unknown';
+  /** Machine-readable quality flags only; never raw paths, IDs, or content. */
+  qualityFlags: string[];
+}
+
+export type AdviceMetricUnit =
+  | 'count'
+  | 'tokens'
+  | 'ratio'
+  | 'multiple'
+  | 'percent'
+  | 'milliseconds'
+  | 'usd-estimate'
+  | 'boolean';
+
+export interface AdviceObservation {
+  id: string;
+  /** Stable machine-readable metric name, e.g. cache-read-share. */
+  metric: string;
+  value: number | boolean;
+  unit: AdviceMetricUnit;
+  method: 'measured' | 'estimated' | 'structural-proxy';
+  sourceId: string;
+  /** Host-authored readable observation. It is not included in remote payloads. */
+  summary: string;
+}
+
+export interface AdviceEvidence {
+  id: string;
+  observationIds: string[];
+  strength: 'direct' | 'correlational' | 'proxy';
+  /** Host-authored readable evidence. It is not included in remote payloads. */
+  summary: string;
+  limitations: string[];
+}
+
+export interface AdviceExplanation {
+  summary: string;
+  /** Observation IDs used only as proxies, never as proof of causation. */
+  proxyMetricObservationIds: string[];
+  limitations: string[];
+}
+
+export interface AdviceConditionalAction {
+  when: string;
+  action: string;
+  evidenceIds: string[];
+  stopCondition?: string;
+}
+
+export interface AdviceQualityGuardrail {
+  /** Stable rubric ID shared by every task in the comparison cohort. */
+  rubricId: string;
+  /** Normalized 0..1 quality score required after applying the advice. */
+  minimumScore: number;
+  /** Maximum allowed mean quality-score drop, normalized to 0..1. */
+  maximumRegression: number;
+}
+
+export interface AdviceSuccessCriterion {
+  metricObservationId: string;
+  direction: 'increase' | 'decrease' | 'maintain';
+  target: {
+    kind: 'relative-change' | 'absolute';
+    value: number;
+  };
+  minimumComparableTasks: number;
+  qualityGuardrail: AdviceQualityGuardrail;
+}
+
+export interface AdviceRecommendation {
+  id: string;
+  title: string;
+  evidenceIds: string[];
+  explanation: AdviceExplanation;
+  conditionalActions: AdviceConditionalAction[];
+  successCriteria: AdviceSuccessCriterion[];
+}
+
+export interface AdvicePrivacyInfo {
+  dataMode:
+    | 'local-only'
+    | 'aggregates-only'
+    | 'aggregates-with-personalization'
+    | 'aggregates-with-prompt-samples';
+  promptSampleConsent: 'not-applicable' | 'not-granted' | 'explicit';
+  promptSampleCount: number;
+  feedbackStorage: 'local-only';
+}
+
+export interface AdviceProvenance {
+  generatedBy: {
+    kind: 'local-rules' | 'remote-model';
+    /** Coarse family only; never a full custom model or endpoint identifier. */
+    modelFamily?: string;
+  };
+  generatedAt: string;
+  locale: string;
+  sources: AdviceSourceInfo[];
+}
+
+export interface AdviceContract {
+  schemaVersion: typeof ADVICE_CONTRACT_VERSION;
+  adviceId: string;
+  observations: AdviceObservation[];
+  evidence: AdviceEvidence[];
+  recommendations: AdviceRecommendation[];
+  privacy: AdvicePrivacyInfo;
+  provenance: AdviceProvenance;
+}
+
+export type AdviceContractBuildResult =
+  | { ok: true; value: AdviceContract }
+  | { ok: false; issues: string[] };
+
+export interface AdviceContractInput {
+  adviceId: string;
+  observations: AdviceObservation[];
+  evidence: AdviceEvidence[];
+  recommendations: AdviceRecommendation[];
+  privacy: AdvicePrivacyInfo;
+  provenance: AdviceProvenance;
+}
+
+const ID_PATTERN = /^[a-z][a-z0-9._-]{0,95}$/;
+
+export function isAdviceIdentifier(value: string): boolean {
+  return ID_PATTERN.test(value);
+}
+
+function uniqueIds<T extends { id: string }>(items: T[], label: string, issues: string[]): Set<string> {
+  const ids = new Set<string>();
+  for (const item of items) {
+    if (!isAdviceIdentifier(item.id)) {
+      issues.push(`${label} has invalid id: ${item.id}`);
+    } else if (ids.has(item.id)) {
+      issues.push(`${label} has duplicate id: ${item.id}`);
+    }
+    ids.add(item.id);
+  }
+  return ids;
+}
+
+function nonEmpty(value: string): boolean {
+  return value.trim().length > 0;
+}
+
+function validFiniteNumber(value: number): boolean {
+  return Number.isFinite(value);
+}
+
+/** Validate the complete host-owned advice artifact. No partial artifact is returned. */
+export function validateAdviceContract(contract: AdviceContract): string[] {
+  const issues: string[] = [];
+  if (contract.schemaVersion !== ADVICE_CONTRACT_VERSION) {
+    issues.push(`unsupported schemaVersion: ${String(contract.schemaVersion)}`);
+  }
+  if (!isAdviceIdentifier(contract.adviceId)) {
+    issues.push('adviceId must be a stable machine-readable identifier');
+  }
+  if (contract.recommendations.length > 0 && contract.observations.length === 0) {
+    issues.push('recommendations require at least one observation');
+  }
+  if (contract.recommendations.length > 0 && contract.evidence.length === 0) {
+    issues.push('recommendations require at least one evidence item');
+  }
+
+  const sourceIds = uniqueIds(contract.provenance.sources, 'source', issues);
+  const observationIds = uniqueIds(contract.observations, 'observation', issues);
+  const evidenceIds = uniqueIds(contract.evidence, 'evidence', issues);
+  uniqueIds(contract.recommendations, 'recommendation', issues);
+
+  for (const source of contract.provenance.sources) {
+    if (source.window.kind === 'rolling-days') {
+      if (!Number.isInteger(source.window.days) || source.window.days < 1) {
+        issues.push(`source ${source.id} has an invalid rolling window`);
+      }
+    }
+    for (const flag of source.qualityFlags) {
+      if (!isAdviceIdentifier(flag)) {
+        issues.push(`source ${source.id} has an invalid quality flag`);
+      }
+    }
+  }
+
+  for (const observation of contract.observations) {
+    if (!isAdviceIdentifier(observation.metric)) {
+      issues.push(`observation ${observation.id} has an invalid metric`);
+    }
+    if (typeof observation.value === 'number' && !validFiniteNumber(observation.value)) {
+      issues.push(`observation ${observation.id} has a non-finite value`);
+    }
+    if (!sourceIds.has(observation.sourceId)) {
+      issues.push(`observation ${observation.id} references unknown source ${observation.sourceId}`);
+    }
+    if (!nonEmpty(observation.summary)) {
+      issues.push(`observation ${observation.id} has an empty summary`);
+    }
+  }
+
+  for (const item of contract.evidence) {
+    if (item.observationIds.length === 0) {
+      issues.push(`evidence ${item.id} must reference an observation`);
+    }
+    for (const observationId of item.observationIds) {
+      if (!observationIds.has(observationId)) {
+        issues.push(`evidence ${item.id} references unknown observation ${observationId}`);
+      }
+    }
+    if (!nonEmpty(item.summary)) issues.push(`evidence ${item.id} has an empty summary`);
+    if (item.strength === 'proxy' && item.limitations.length === 0) {
+      issues.push(`proxy evidence ${item.id} must state a limitation`);
+    }
+  }
+
+  for (const recommendation of contract.recommendations) {
+    if (!nonEmpty(recommendation.title)) {
+      issues.push(`recommendation ${recommendation.id} has an empty title`);
+    }
+    if (recommendation.evidenceIds.length === 0) {
+      issues.push(`recommendation ${recommendation.id} must reference evidence`);
+    }
+    for (const evidenceId of recommendation.evidenceIds) {
+      if (!evidenceIds.has(evidenceId)) {
+        issues.push(`recommendation ${recommendation.id} references unknown evidence ${evidenceId}`);
+      }
+    }
+    if (!nonEmpty(recommendation.explanation.summary)) {
+      issues.push(`recommendation ${recommendation.id} has an empty explanation`);
+    }
+    for (const observationId of recommendation.explanation.proxyMetricObservationIds) {
+      if (!observationIds.has(observationId)) {
+        issues.push(`recommendation ${recommendation.id} references unknown proxy ${observationId}`);
+      }
+    }
+    if (
+      recommendation.explanation.proxyMetricObservationIds.length > 0 &&
+      recommendation.explanation.limitations.length === 0
+    ) {
+      issues.push(`recommendation ${recommendation.id} must limit its proxy interpretation`);
+    }
+    if (recommendation.conditionalActions.length === 0) {
+      issues.push(`recommendation ${recommendation.id} must include a conditional action`);
+    }
+    for (const action of recommendation.conditionalActions) {
+      if (!nonEmpty(action.when) || !nonEmpty(action.action)) {
+        issues.push(`recommendation ${recommendation.id} has an empty condition or action`);
+      }
+      if (action.evidenceIds.length === 0) {
+        issues.push(`recommendation ${recommendation.id} action must reference evidence`);
+      }
+      for (const evidenceId of action.evidenceIds) {
+        if (!evidenceIds.has(evidenceId)) {
+          issues.push(`recommendation ${recommendation.id} action references unknown evidence ${evidenceId}`);
+        }
+      }
+    }
+    if (recommendation.successCriteria.length === 0) {
+      issues.push(`recommendation ${recommendation.id} must include a success criterion`);
+    }
+    for (const criterion of recommendation.successCriteria) {
+      if (!observationIds.has(criterion.metricObservationId)) {
+        issues.push(
+          `recommendation ${recommendation.id} criterion references unknown observation ${criterion.metricObservationId}`
+        );
+      }
+      if (!validFiniteNumber(criterion.target.value) || criterion.target.value < 0) {
+        issues.push(`recommendation ${recommendation.id} has an invalid success target`);
+      }
+      if (!Number.isInteger(criterion.minimumComparableTasks) || criterion.minimumComparableTasks < 2) {
+        issues.push(`recommendation ${recommendation.id} needs at least two comparable tasks`);
+      }
+      const guardrail = criterion.qualityGuardrail;
+      if (!isAdviceIdentifier(guardrail.rubricId)) {
+        issues.push(`recommendation ${recommendation.id} has an invalid quality rubric`);
+      }
+      if (
+        !validFiniteNumber(guardrail.minimumScore) ||
+        guardrail.minimumScore < 0 ||
+        guardrail.minimumScore > 1 ||
+        !validFiniteNumber(guardrail.maximumRegression) ||
+        guardrail.maximumRegression < 0 ||
+        guardrail.maximumRegression > 1
+      ) {
+        issues.push(`recommendation ${recommendation.id} has an invalid quality guardrail`);
+      }
+    }
+  }
+
+  const privacy = contract.privacy;
+  if (!Number.isInteger(privacy.promptSampleCount) || privacy.promptSampleCount < 0) {
+    issues.push('promptSampleCount must be a non-negative integer');
+  }
+  if (
+    privacy.dataMode === 'local-only' &&
+    (privacy.promptSampleConsent !== 'not-applicable' || privacy.promptSampleCount !== 0)
+  ) {
+    issues.push('local-only advice cannot carry prompt-sample consent or samples');
+  }
+  if (
+    privacy.dataMode === 'aggregates-only' &&
+    (privacy.promptSampleConsent !== 'not-granted' || privacy.promptSampleCount !== 0)
+  ) {
+    issues.push('aggregates-only advice must contain zero prompt samples');
+  }
+  if (
+    privacy.dataMode === 'aggregates-with-prompt-samples' &&
+    (privacy.promptSampleConsent !== 'explicit' || privacy.promptSampleCount < 1)
+  ) {
+    issues.push('prompt samples require explicit consent and a non-zero sample count');
+  }
+  if (
+    privacy.dataMode === 'aggregates-with-personalization' &&
+    (privacy.promptSampleConsent !== 'explicit' || privacy.promptSampleCount !== 0)
+  ) {
+    issues.push('personal context requires explicit consent and zero prompt samples');
+  }
+
+  if (!nonEmpty(contract.provenance.locale)) issues.push('provenance locale is required');
+  if (!Number.isFinite(Date.parse(contract.provenance.generatedAt))) {
+    issues.push('provenance generatedAt must be an ISO-compatible timestamp');
+  }
+  if (
+    contract.provenance.generatedBy.modelFamily !== undefined &&
+    !isAdviceIdentifier(contract.provenance.generatedBy.modelFamily)
+  ) {
+    issues.push('provenance modelFamily must be coarse and machine-readable');
+  }
+
+  return issues;
+}
+
+/** Assemble host metadata with recommendations only after the whole contract validates. */
+export function createAdviceContract(input: AdviceContractInput): AdviceContractBuildResult {
+  const value: AdviceContract = {
+    schemaVersion: ADVICE_CONTRACT_VERSION,
+    adviceId: input.adviceId,
+    observations: input.observations,
+    evidence: input.evidence,
+    recommendations: input.recommendations,
+    privacy: input.privacy,
+    provenance: input.provenance,
+  };
+  const issues = validateAdviceContract(value);
+  return issues.length === 0 ? { ok: true, value } : { ok: false, issues };
+}
diff --git a/src/adviceEffectiveness/evidencePreparation.ts b/src/adviceEffectiveness/evidencePreparation.ts
new file mode 100644
index 00000000..a615a4fc
--- /dev/null
+++ b/src/adviceEffectiveness/evidencePreparation.ts
@@ -0,0 +1,166 @@
+/**
+ * Pure planning contract between v2.3.1 advice and the future stable #87
+ * materialized Claude index. It deliberately performs no I/O and never starts
+ * a content scan. The host may interpret `refresh-content-analysis` only after
+ * the user explicitly requests prompt personalization.
+ */
+
+export const ADVICE_EVIDENCE_PREPARATION_PLAN_VERSION = 1 as const;
+
+export type AdviceEvidencePreparationOperation = 'local-render' | 'preview' | 'send';
+export type AdviceEvidencePreparationDataMode =
+  | 'local-only'
+  | 'aggregates-only'
+  | 'aggregates-with-prompt-samples';
+
+export interface AdviceContentSnapshotDescriptor {
+  status: 'ready' | 'stale';
+  windowDays: number;
+  promptSampleCount: number;
+}
+
+export interface AdviceEvidencePreparationRequest {
+  featureMode: 'disabled' | 'enabled';
+  operation: AdviceEvidencePreparationOperation;
+  dataMode: AdviceEvidencePreparationDataMode;
+  aggregateAvailable: boolean;
+  aggregateConsent: 'not-granted' | 'explicit';
+  promptPersonalizationConsent: 'not-granted' | 'explicit';
+  requestedWindowDays: number;
+  contentSnapshot?: AdviceContentSnapshotDescriptor;
+}
+
+export type AdviceEvidencePreparationReason =
+  | 'feature-disabled'
+  | 'invalid-request'
+  | 'local-evidence-ready'
+  | 'aggregate-consent-required'
+  | 'aggregate-unavailable'
+  | 'aggregate-evidence-ready'
+  | 'prompt-personalization-consent-required'
+  | 'content-snapshot-missing'
+  | 'content-snapshot-stale'
+  | 'content-window-mismatch'
+  | 'prompt-samples-unavailable'
+  | 'personalized-evidence-ready';
+
+export interface AdviceEvidencePreparationPlan {
+  schemaVersion: typeof ADVICE_EVIDENCE_PREPARATION_PLAN_VERSION;
+  status: 'disabled' | 'ready' | 'blocked' | 'explicit-refresh-required';
+  dataMode: AdviceEvidencePreparationDataMode;
+  reason: AdviceEvidencePreparationReason;
+  requiredHostAction: 'none' | 'refresh-content-analysis';
+  /** This pure seam never authorizes a background or implicit JSONL scan. */
+  allowAutomaticScan: false;
+}
+
+function plan(
+  status: AdviceEvidencePreparationPlan['status'],
+  dataMode: AdviceEvidencePreparationDataMode,
+  reason: AdviceEvidencePreparationReason,
+  requiredHostAction: AdviceEvidencePreparationPlan['requiredHostAction'] = 'none',
+): AdviceEvidencePreparationPlan {
+  return {
+    schemaVersion: ADVICE_EVIDENCE_PREPARATION_PLAN_VERSION,
+    status,
+    dataMode,
+    reason,
+    requiredHostAction,
+    allowAutomaticScan: false,
+  };
+}
+
+function validSnapshot(value: unknown): value is AdviceContentSnapshotDescriptor {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const snapshot = value as Record<string, unknown>;
+  const keys = Object.keys(snapshot).sort();
+  if (keys.join('\0') !== ['promptSampleCount', 'status', 'windowDays'].join('\0')) return false;
+  return (
+    (snapshot.status === 'ready' || snapshot.status === 'stale') &&
+    typeof snapshot.windowDays === 'number' &&
+    Number.isInteger(snapshot.windowDays) &&
+    snapshot.windowDays >= 1 &&
+    snapshot.windowDays <= 365 &&
+    typeof snapshot.promptSampleCount === 'number' &&
+    Number.isInteger(snapshot.promptSampleCount) &&
+    snapshot.promptSampleCount >= 0
+  );
+}
+
+function validRequest(value: AdviceEvidencePreparationRequest): boolean {
+  return (
+    (value.operation === 'local-render' || value.operation === 'preview' || value.operation === 'send') &&
+    (value.dataMode === 'local-only' ||
+      value.dataMode === 'aggregates-only' ||
+      value.dataMode === 'aggregates-with-prompt-samples') &&
+    typeof value.aggregateAvailable === 'boolean' &&
+    (value.aggregateConsent === 'not-granted' || value.aggregateConsent === 'explicit') &&
+    (value.promptPersonalizationConsent === 'not-granted' ||
+      value.promptPersonalizationConsent === 'explicit') &&
+    Number.isInteger(value.requestedWindowDays) &&
+    value.requestedWindowDays >= 1 &&
+    value.requestedWindowDays <= 365 &&
+    (value.contentSnapshot === undefined || validSnapshot(value.contentSnapshot))
+  );
+}
+
+export function planAdviceEvidencePreparation(
+  request: AdviceEvidencePreparationRequest,
+): AdviceEvidencePreparationPlan {
+  if (request?.featureMode === 'disabled') {
+    return plan('disabled', 'local-only', 'feature-disabled');
+  }
+  if (request?.featureMode !== 'enabled' || !validRequest(request)) {
+    return plan('blocked', 'local-only', 'invalid-request');
+  }
+  if (request.operation === 'local-render') {
+    return request.dataMode === 'local-only'
+      ? plan('ready', 'local-only', 'local-evidence-ready')
+      : plan('blocked', 'local-only', 'invalid-request');
+  }
+  if (request.dataMode === 'local-only') {
+    return plan('blocked', 'local-only', 'invalid-request');
+  }
+  if (request.aggregateConsent !== 'explicit') {
+    return plan('blocked', request.dataMode, 'aggregate-consent-required');
+  }
+  if (!request.aggregateAvailable) {
+    return plan('blocked', request.dataMode, 'aggregate-unavailable');
+  }
+  if (request.dataMode === 'aggregates-only') {
+    return plan('ready', request.dataMode, 'aggregate-evidence-ready');
+  }
+  if (request.promptPersonalizationConsent !== 'explicit') {
+    return plan('blocked', request.dataMode, 'prompt-personalization-consent-required');
+  }
+
+  const snapshot = request.contentSnapshot;
+  if (!snapshot) {
+    return plan(
+      'explicit-refresh-required',
+      request.dataMode,
+      'content-snapshot-missing',
+      'refresh-content-analysis',
+    );
+  }
+  if (snapshot.status === 'stale') {
+    return plan(
+      'explicit-refresh-required',
+      request.dataMode,
+      'content-snapshot-stale',
+      'refresh-content-analysis',
+    );
+  }
+  if (snapshot.windowDays !== request.requestedWindowDays) {
+    return plan(
+      'explicit-refresh-required',
+      request.dataMode,
+      'content-window-mismatch',
+      'refresh-content-analysis',
+    );
+  }
+  if (snapshot.promptSampleCount === 0) {
+    return plan('blocked', request.dataMode, 'prompt-samples-unavailable');
+  }
+  return plan('ready', request.dataMode, 'personalized-evidence-ready');
+}
diff --git a/src/adviceEffectiveness/feedback.ts b/src/adviceEffectiveness/feedback.ts
new file mode 100644
index 00000000..143b15b1
--- /dev/null
+++ b/src/adviceEffectiveness/feedback.ts
@@ -0,0 +1,166 @@
+import { isAdviceIdentifier } from './contract';
+
+export const ADVICE_FEEDBACK_STORAGE_KEY = 'claudeCodeUsage.adviceEffectiveness.feedback.v1';
+export const ADVICE_FEEDBACK_VERSION = 1 as const;
+export const MAX_ADVICE_FEEDBACK_EVENTS = 500;
+
+export type AdviceFeedbackKind = 'helpful' | 'not-helpful' | 'applied';
+
+export interface AdviceFeedbackEvent {
+  schemaVersion: typeof ADVICE_FEEDBACK_VERSION;
+  eventId: string;
+  adviceId: string;
+  recommendationId: string;
+  kind: AdviceFeedbackKind;
+  recordedAt: string;
+  localOnly: true;
+}
+
+export interface AdviceFeedbackStorage {
+  get<T>(key: string): T | undefined;
+  update(key: string, value: unknown): PromiseLike<void>;
+}
+
+interface StoredAdviceFeedback {
+  schemaVersion: typeof ADVICE_FEEDBACK_VERSION;
+  events: AdviceFeedbackEvent[];
+}
+
+export type AdviceFeedbackLoadResult =
+  | { ok: true; events: AdviceFeedbackEvent[] }
+  | { ok: false; reason: 'invalid-local-data' };
+
+export type AdviceFeedbackWriteResult =
+  | { ok: true; events: AdviceFeedbackEvent[] }
+  | { ok: false; reason: 'invalid-event' | 'invalid-local-data' };
+
+const EVENT_KEYS = [
+  'adviceId',
+  'eventId',
+  'kind',
+  'localOnly',
+  'recordedAt',
+  'recommendationId',
+  'schemaVersion',
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const sortedExpected = [...expected].sort();
+  return actual.length === sortedExpected.length && actual.every((key, index) => key === sortedExpected[index]);
+}
+
+function isFeedbackKind(value: unknown): value is AdviceFeedbackKind {
+  return value === 'helpful' || value === 'not-helpful' || value === 'applied';
+}
+
+function parseEvent(value: unknown): AdviceFeedbackEvent | undefined {
+  if (!isObject(value) || !hasExactKeys(value, EVENT_KEYS)) return undefined;
+  if (
+    value.schemaVersion !== ADVICE_FEEDBACK_VERSION ||
+    value.localOnly !== true ||
+    typeof value.eventId !== 'string' ||
+    typeof value.adviceId !== 'string' ||
+    typeof value.recommendationId !== 'string' ||
+    typeof value.recordedAt !== 'string' ||
+    !isFeedbackKind(value.kind) ||
+    !isAdviceIdentifier(value.eventId) ||
+    !isAdviceIdentifier(value.adviceId) ||
+    !isAdviceIdentifier(value.recommendationId) ||
+    !Number.isFinite(Date.parse(value.recordedAt))
+  ) {
+    return undefined;
+  }
+  return {
+    schemaVersion: ADVICE_FEEDBACK_VERSION,
+    eventId: value.eventId,
+    adviceId: value.adviceId,
+    recommendationId: value.recommendationId,
+    kind: value.kind,
+    recordedAt: value.recordedAt,
+    localOnly: true,
+  };
+}
+
+/** Read only the versioned local ledger; corrupt or unknown shapes fail closed. */
+export function loadAdviceFeedback(storage: AdviceFeedbackStorage): AdviceFeedbackLoadResult {
+  const raw = storage.get<unknown>(ADVICE_FEEDBACK_STORAGE_KEY);
+  if (raw === undefined) return { ok: true, events: [] };
+  if (!isObject(raw) || !hasExactKeys(raw, ['events', 'schemaVersion'])) {
+    return { ok: false, reason: 'invalid-local-data' };
+  }
+  if (raw.schemaVersion !== ADVICE_FEEDBACK_VERSION || !Array.isArray(raw.events)) {
+    return { ok: false, reason: 'invalid-local-data' };
+  }
+  const events: AdviceFeedbackEvent[] = [];
+  const eventIds = new Set<string>();
+  for (const rawEvent of raw.events) {
+    const event = parseEvent(rawEvent);
+    if (!event || eventIds.has(event.eventId)) return { ok: false, reason: 'invalid-local-data' };
+    eventIds.add(event.eventId);
+    events.push(event);
+  }
+  return { ok: true, events };
+}
+
+/**
+ * Store a local feedback state transition. Helpful/not-helpful are mutually
+ * exclusive for one recommendation; applied is independent and may coexist.
+ * No prompt, payload, explanation, endpoint, or free-text field is accepted.
+ */
+export async function recordAdviceFeedback(
+  storage: AdviceFeedbackStorage,
+  eventInput: Omit<AdviceFeedbackEvent, 'schemaVersion' | 'localOnly'>
+): Promise<AdviceFeedbackWriteResult> {
+  const event = parseEvent({
+    schemaVersion: ADVICE_FEEDBACK_VERSION,
+    eventId: eventInput.eventId,
+    adviceId: eventInput.adviceId,
+    recommendationId: eventInput.recommendationId,
+    kind: eventInput.kind,
+    recordedAt: eventInput.recordedAt,
+    localOnly: true,
+  });
+  if (!event) return { ok: false, reason: 'invalid-event' };
+
+  const loaded = loadAdviceFeedback(storage);
+  if (!loaded.ok) return loaded;
+
+  const sameTarget = (candidate: AdviceFeedbackEvent): boolean =>
+    candidate.adviceId === event.adviceId && candidate.recommendationId === event.recommendationId;
+  const next = loaded.events.filter((candidate) => {
+    if (candidate.eventId === event.eventId) return false;
+    if (!sameTarget(candidate)) return true;
+    if (event.kind === 'applied') return candidate.kind !== 'applied';
+    return candidate.kind === 'applied';
+  });
+  next.push(event);
+  const bounded = next.slice(-MAX_ADVICE_FEEDBACK_EVENTS);
+  const stored: StoredAdviceFeedback = { schemaVersion: ADVICE_FEEDBACK_VERSION, events: bounded };
+  await storage.update(ADVICE_FEEDBACK_STORAGE_KEY, stored);
+  return { ok: true, events: bounded };
+}
+
+export interface AdviceFeedbackSummary {
+  rating: 'helpful' | 'not-helpful' | 'unrated';
+  applied: boolean;
+}
+
+export function summarizeAdviceFeedback(
+  events: readonly AdviceFeedbackEvent[],
+  adviceId: string,
+  recommendationId: string
+): AdviceFeedbackSummary {
+  let rating: AdviceFeedbackSummary['rating'] = 'unrated';
+  let applied = false;
+  for (const event of events) {
+    if (event.adviceId !== adviceId || event.recommendationId !== recommendationId) continue;
+    if (event.kind === 'applied') applied = true;
+    else rating = event.kind;
+  }
+  return { rating, applied };
+}
diff --git a/src/adviceEffectiveness/integration.ts b/src/adviceEffectiveness/integration.ts
new file mode 100644
index 00000000..5ae0a6af
--- /dev/null
+++ b/src/adviceEffectiveness/integration.ts
@@ -0,0 +1,140 @@
+import { AdviceContract } from './contract';
+import {
+  AdviceAggregateSnapshot,
+  PreparedAdvicePayload,
+  prepareAdvicePayload,
+  previewAdvicePayload,
+} from './payload';
+
+export type AdviceEffectivenessProvider = 'claude' | 'codex';
+
+/**
+ * Extension-host state for the experimental panel. Prompt text stays in this
+ * host-only object and is not rendered or serialized until the separate
+ * prompt-sample capability is explicitly granted for one sealed snapshot.
+ */
+export interface AdviceEffectivenessProviderState {
+  provider: AdviceEffectivenessProvider;
+  contract: AdviceContract;
+  remotePreviewEligible: boolean;
+  aggregate?: AdviceAggregateSnapshot;
+  /** Included only when the separate prompt-personalisation consent is explicit. */
+  userContext?: string;
+  promptSamples: readonly { text: string }[];
+}
+
+export type AdviceEffectivenessProviderStates = Partial<
+  Record<AdviceEffectivenessProvider, AdviceEffectivenessProviderState>
+>;
+
+export type AdviceSnapshotConsent = {
+  aggregate: 'explicit' | 'not-granted';
+  promptSamples: 'explicit' | 'not-granted';
+};
+
+/** Select only timestamped samples inside the current consent window. */
+export function selectAdvicePromptSamples(
+  samples: readonly { text: string; observedAtEpochMs: number }[],
+  nowEpochMs: number,
+  windowDays: number,
+): { text: string }[] {
+  if (
+    !Number.isFinite(nowEpochMs) ||
+    !Number.isInteger(windowDays) ||
+    windowDays < 1 ||
+    windowDays > 365
+  ) {
+    return [];
+  }
+  const cutoff = nowEpochMs - windowDays * 86_400_000;
+  return samples
+    .filter(
+      (sample) =>
+        typeof sample.text === 'string' &&
+        Number.isFinite(sample.observedAtEpochMs) &&
+        sample.observedAtEpochMs >= cutoff &&
+        sample.observedAtEpochMs <= nowEpochMs,
+    )
+    .map((sample) => ({ text: sample.text }));
+}
+
+export interface PreparedAdviceSnapshot {
+  provider: 'claude';
+  prepared: PreparedAdvicePayload;
+  preview: {
+    contentType: PreparedAdvicePayload['contentType'];
+    dataMode: PreparedAdvicePayload['dataMode'];
+    promptSampleCount: number;
+    body: string;
+    utf8Bytes: number;
+    sha256: string;
+  };
+}
+
+export type PrepareAdviceSnapshotResult =
+  | { ok: true; value: PreparedAdviceSnapshot }
+  | {
+      ok: false;
+      reason:
+        | 'aggregate-consent-required'
+        | 'provider-not-eligible'
+        | 'aggregate-unavailable'
+        | 'invalid-evidence';
+    };
+
+/**
+ * Seal one canonical remote object. This function has no transport and cannot
+ * send; callers retain `prepared` under an opaque snapshot ID for the single
+ * future wiring point. Preview text is read from that same prepared value.
+ */
+export function prepareAdviceSnapshot(
+  state: AdviceEffectivenessProviderState,
+  consent: AdviceSnapshotConsent,
+): PrepareAdviceSnapshotResult {
+  if (consent.aggregate !== 'explicit') {
+    return { ok: false, reason: 'aggregate-consent-required' };
+  }
+  if (state.provider !== 'claude' || !state.remotePreviewEligible) {
+    return { ok: false, reason: 'provider-not-eligible' };
+  }
+  if (!state.aggregate) {
+    return { ok: false, reason: 'aggregate-unavailable' };
+  }
+
+  try {
+    const prepared = prepareAdvicePayload({
+      locale: state.contract.provenance.locale,
+      aggregate: state.aggregate,
+      sources: state.contract.provenance.sources,
+      observations: state.contract.observations,
+      evidence: state.contract.evidence,
+      ...(consent.promptSamples === 'explicit'
+        ? {
+            promptSamples: {
+              consent: 'explicit' as const,
+              ...(state.userContext === undefined ? {} : { userContext: state.userContext }),
+              samples: state.promptSamples.map((sample) => ({ text: sample.text })),
+            },
+          }
+        : {}),
+    });
+    const preview = previewAdvicePayload(prepared);
+    return {
+      ok: true,
+      value: {
+        provider: 'claude',
+        prepared,
+        preview: {
+          contentType: preview.contentType,
+          dataMode: preview.dataMode,
+          promptSampleCount: preview.promptSampleCount,
+          body: preview.body,
+          utf8Bytes: preview.utf8Bytes,
+          sha256: preview.sha256,
+        },
+      },
+    };
+  } catch {
+    return { ok: false, reason: 'invalid-evidence' };
+  }
+}
diff --git a/src/adviceEffectiveness/legacyBridge.ts b/src/adviceEffectiveness/legacyBridge.ts
new file mode 100644
index 00000000..259ae886
--- /dev/null
+++ b/src/adviceEffectiveness/legacyBridge.ts
@@ -0,0 +1,131 @@
+import {
+  PreparedAdvicePayload,
+  sendPreparedAdvicePayload,
+} from './payload';
+import {
+  StructuredAdviceOutput,
+  StructuredAdviceParseErrorCode,
+  StructuredAdviceReferences,
+  parseStructuredAdviceOutput,
+} from './structuredOutput';
+
+/**
+ * The only approved future seam from the evidence contract into the existing
+ * user-key transport. This module is intentionally not wired by production.
+ */
+export const LEGACY_BYOK_STRUCTURED_ADVICE_SYSTEM_PROMPT =
+  'Return exactly one strict JSON object matching the requested response contract. ' +
+  'Do not use Markdown fences, prose outside JSON, unknown fields, or evidence IDs ' +
+  'that are absent from the sealed user payload. An empty recommendations array is ' +
+  'required when the evidence does not support a recommendation.';
+
+export interface LegacyByokAdviceOptions {
+  backend?: 'api';
+  apiFormat: 'anthropic' | 'openai';
+  apiKey: string;
+  apiUrl: string;
+  model: string;
+  reasoningEffort?: '' | 'high' | 'max';
+  timeoutMs?: number;
+}
+
+export interface LegacyByokCallOptions extends LegacyByokAdviceOptions {
+  backend: 'api';
+  summary: '';
+  language: '';
+}
+
+export type LegacyByokModelCall = (
+  systemPrompt: string,
+  userContent: string,
+  options: LegacyByokCallOptions,
+) => Promise<string>;
+
+export type LegacyByokAdviceResult =
+  | { ok: true; value: StructuredAdviceOutput }
+  | {
+      ok: false;
+      code: StructuredAdviceParseErrorCode | 'invalid-config' | 'transport-error';
+      issues: string[];
+    };
+
+/**
+ * Passes the already-sealed body as the exact model user turn and applies the
+ * strict parser. It never calls the legacy Markdown advice builder or fallback.
+ */
+export async function requestStructuredAdviceViaLegacyByok(
+  prepared: PreparedAdvicePayload,
+  references: StructuredAdviceReferences,
+  options: LegacyByokAdviceOptions,
+  invoke: LegacyByokModelCall,
+): Promise<LegacyByokAdviceResult> {
+  if (!validLegacyByokOptions(options)) {
+    return {
+      ok: false,
+      code: 'invalid-config',
+      issues: ['legacy BYOK configuration was rejected'],
+    };
+  }
+  let raw: string;
+  try {
+    raw = await sendPreparedAdvicePayload(
+      prepared,
+      async (canonicalBytes) => invoke(
+        LEGACY_BYOK_STRUCTURED_ADVICE_SYSTEM_PROMPT,
+        Buffer.from(canonicalBytes).toString('utf8'),
+        {
+          backend: 'api',
+          apiFormat: options.apiFormat,
+          apiKey: options.apiKey,
+          apiUrl: options.apiUrl,
+          model: options.model,
+          summary: '',
+          language: '',
+          ...(options.reasoningEffort === undefined
+            ? {}
+            : { reasoningEffort: options.reasoningEffort }),
+          ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        },
+      ),
+    );
+  } catch {
+    return {
+      ok: false,
+      code: 'transport-error',
+      issues: ['legacy BYOK transport failed'],
+    };
+  }
+  return parseStructuredAdviceOutput(raw, references);
+}
+
+function validLegacyByokOptions(value: unknown): value is LegacyByokAdviceOptions {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const input = value as Record<string, unknown>;
+  const required = ['apiFormat', 'apiKey', 'apiUrl', 'model'];
+  const allowed = new Set([...required, 'backend', 'reasoningEffort', 'timeoutMs']);
+  const keys = Object.keys(input);
+  if (!required.every((key) => keys.includes(key)) || keys.some((key) => !allowed.has(key))) {
+    return false;
+  }
+  if (
+    (input.backend !== undefined && input.backend !== 'api') ||
+    (input.apiFormat !== 'anthropic' && input.apiFormat !== 'openai') ||
+    typeof input.apiKey !== 'string' ||
+    input.apiKey.trim().length === 0 ||
+    typeof input.apiUrl !== 'string' ||
+    input.apiUrl.trim().length === 0 ||
+    typeof input.model !== 'string' ||
+    input.model.trim().length === 0 ||
+    (input.reasoningEffort !== undefined &&
+      input.reasoningEffort !== '' &&
+      input.reasoningEffort !== 'high' &&
+      input.reasoningEffort !== 'max') ||
+    (input.timeoutMs !== undefined &&
+      (typeof input.timeoutMs !== 'number' ||
+        !Number.isFinite(input.timeoutMs) ||
+        input.timeoutMs <= 0))
+  ) {
+    return false;
+  }
+  return true;
+}
diff --git a/src/adviceEffectiveness/legacyPersonalization.ts b/src/adviceEffectiveness/legacyPersonalization.ts
new file mode 100644
index 00000000..7a81fddc
--- /dev/null
+++ b/src/adviceEffectiveness/legacyPersonalization.ts
@@ -0,0 +1,276 @@
+import {
+  MAX_PROMPT_SAMPLES,
+  MAX_PROMPT_SAMPLE_CHARS,
+  MAX_PROMPT_SAMPLE_TOTAL_CHARS,
+} from './payload';
+
+export const LEGACY_PERSONALIZATION_MIGRATION_VERSION = 1 as const;
+export const MAX_LEGACY_USER_CONTEXT_CHARS = 1_000;
+
+export type LegacyPromptSampleAge = 'within-window' | 'older-than-window' | 'unknown';
+
+export interface LegacyPersonalizationMigrationSummary {
+  requiresExplicitPromptPersonalizationConsent: boolean;
+  userContextChars: number;
+  userContextTruncated: boolean;
+  promptSampleCount: number;
+  promptSamplesTruncated: boolean;
+  sampleAge: {
+    withinWindow: number;
+    olderThanWindow: number;
+    unknown: number;
+  };
+}
+
+export interface LegacyPersonalizationDraft {
+  schemaVersion: typeof LEGACY_PERSONALIZATION_MIGRATION_VERSION;
+  windowDays: number;
+  userContext?: string;
+  promptSamples: { text: string; age: LegacyPromptSampleAge }[];
+  /** Content-free metadata safe for migration/status UI. */
+  migration: LegacyPersonalizationMigrationSummary;
+}
+
+export interface LegacyPersonalizationProjection {
+  schemaVersion: typeof LEGACY_PERSONALIZATION_MIGRATION_VERSION;
+  consent: 'explicit';
+  windowDays: number;
+  userContext?: string;
+  promptSamples: { text: string; age: LegacyPromptSampleAge }[];
+}
+
+export type BuildLegacyPersonalizationDraftResult =
+  | { ok: true; value: LegacyPersonalizationDraft }
+  | { ok: false; reason: 'invalid-legacy-personalization' };
+
+interface LegacyPromptSampleInput {
+  text?: unknown;
+  observedAtEpochMs?: unknown;
+  [key: string]: unknown;
+}
+
+export interface LegacyPersonalizationInput {
+  promptWindowDays: unknown;
+  userContext: unknown;
+  promptSamples: unknown;
+  nowEpochMs: unknown;
+}
+
+function invalid(): BuildLegacyPersonalizationDraftResult {
+  return { ok: false, reason: 'invalid-legacy-personalization' };
+}
+
+function sampleAge(
+  observedAtEpochMs: number | undefined,
+  cutoffEpochMs: number,
+): LegacyPromptSampleAge {
+  if (observedAtEpochMs === undefined) return 'unknown';
+  return observedAtEpochMs >= cutoffEpochMs ? 'within-window' : 'older-than-window';
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: string[]): boolean {
+  return Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+
+function validDraft(value: unknown): value is LegacyPersonalizationDraft {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const draft = value as Record<string, unknown>;
+  const rootKeys = ['migration', 'promptSamples', 'schemaVersion', 'windowDays'];
+  if (draft.userContext !== undefined) rootKeys.push('userContext');
+  if (!hasExactKeys(draft, rootKeys)) return false;
+  if (
+    draft.schemaVersion !== LEGACY_PERSONALIZATION_MIGRATION_VERSION ||
+    typeof draft.windowDays !== 'number' ||
+    !Number.isInteger(draft.windowDays) ||
+    draft.windowDays < 1 ||
+    draft.windowDays > 365 ||
+    (draft.userContext !== undefined &&
+      (typeof draft.userContext !== 'string' ||
+        draft.userContext.length < 1 ||
+        draft.userContext.length > MAX_LEGACY_USER_CONTEXT_CHARS ||
+        draft.userContext.trim() !== draft.userContext)) ||
+    !Array.isArray(draft.promptSamples) ||
+    draft.promptSamples.length > MAX_PROMPT_SAMPLES
+  ) {
+    return false;
+  }
+
+  const sampleAgeCounts = { withinWindow: 0, olderThanWindow: 0, unknown: 0 };
+  let totalChars = 0;
+  for (const candidate of draft.promptSamples) {
+    if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) return false;
+    const sample = candidate as Record<string, unknown>;
+    if (
+      !hasExactKeys(sample, ['age', 'text']) ||
+      typeof sample.text !== 'string' ||
+      sample.text.length < 1 ||
+      sample.text.length > MAX_PROMPT_SAMPLE_CHARS ||
+      sample.text.trim() !== sample.text ||
+      (sample.age !== 'within-window' && sample.age !== 'older-than-window' && sample.age !== 'unknown')
+    ) {
+      return false;
+    }
+    totalChars += sample.text.length;
+    if (totalChars > MAX_PROMPT_SAMPLE_TOTAL_CHARS) return false;
+    sampleAgeCounts[
+      sample.age === 'within-window'
+        ? 'withinWindow'
+        : sample.age === 'older-than-window'
+          ? 'olderThanWindow'
+          : 'unknown'
+    ] += 1;
+  }
+
+  if (typeof draft.migration !== 'object' || draft.migration === null || Array.isArray(draft.migration)) {
+    return false;
+  }
+  const migration = draft.migration as Record<string, unknown>;
+  if (!hasExactKeys(migration, [
+    'promptSampleCount',
+    'promptSamplesTruncated',
+    'requiresExplicitPromptPersonalizationConsent',
+    'sampleAge',
+    'userContextChars',
+    'userContextTruncated',
+  ])) {
+    return false;
+  }
+  if (
+    migration.requiresExplicitPromptPersonalizationConsent !==
+      (draft.userContext !== undefined || draft.promptSamples.length > 0) ||
+    migration.userContextChars !== (draft.userContext?.length ?? 0) ||
+    typeof migration.userContextTruncated !== 'boolean' ||
+    migration.promptSampleCount !== draft.promptSamples.length ||
+    typeof migration.promptSamplesTruncated !== 'boolean' ||
+    typeof migration.sampleAge !== 'object' ||
+    migration.sampleAge === null ||
+    Array.isArray(migration.sampleAge)
+  ) {
+    return false;
+  }
+  const ages = migration.sampleAge as Record<string, unknown>;
+  return (
+    hasExactKeys(ages, ['olderThanWindow', 'unknown', 'withinWindow']) &&
+    ages.withinWindow === sampleAgeCounts.withinWindow &&
+    ages.olderThanWindow === sampleAgeCounts.olderThanWindow &&
+    ages.unknown === sampleAgeCounts.unknown
+  );
+}
+
+/**
+ * Rebuild the old settings/content into a host-only, bounded draft. Extra
+ * runtime fields (cwd, session IDs, paths) have no destination. No projection
+ * is returned until the new prompt-personalization consent is explicit.
+ */
+export function buildLegacyPersonalizationDraft(
+  input: LegacyPersonalizationInput,
+): BuildLegacyPersonalizationDraftResult {
+  if (
+    typeof input !== 'object' ||
+    input === null ||
+    typeof input.promptWindowDays !== 'number' ||
+    !Number.isInteger(input.promptWindowDays) ||
+    input.promptWindowDays < 1 ||
+    input.promptWindowDays > 365 ||
+    typeof input.nowEpochMs !== 'number' ||
+    !Number.isFinite(input.nowEpochMs) ||
+    input.nowEpochMs < 0 ||
+    typeof input.userContext !== 'string' ||
+    !Array.isArray(input.promptSamples)
+  ) {
+    return invalid();
+  }
+
+  const nowEpochMs = input.nowEpochMs;
+  const cutoffEpochMs = nowEpochMs - input.promptWindowDays * 86_400_000;
+  const rawContext = input.userContext.trim();
+  const userContext = rawContext.slice(0, MAX_LEGACY_USER_CONTEXT_CHARS);
+  const promptSamples: LegacyPersonalizationDraft['promptSamples'] = [];
+  let totalChars = 0;
+  let promptSamplesTruncated = input.promptSamples.length > MAX_PROMPT_SAMPLES;
+  const ages = { withinWindow: 0, olderThanWindow: 0, unknown: 0 };
+
+  const candidates = input.promptSamples.slice(0, MAX_PROMPT_SAMPLES) as LegacyPromptSampleInput[];
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'object' || candidate === null || typeof candidate.text !== 'string') {
+      return invalid();
+    }
+    let observedAtEpochMs: number | undefined;
+    if (candidate.observedAtEpochMs !== undefined) {
+      if (
+        typeof candidate.observedAtEpochMs !== 'number' ||
+        !Number.isFinite(candidate.observedAtEpochMs) ||
+        candidate.observedAtEpochMs < 0 ||
+        candidate.observedAtEpochMs > nowEpochMs
+      ) {
+        return invalid();
+      }
+      observedAtEpochMs = candidate.observedAtEpochMs;
+    }
+
+    const trimmed = candidate.text.trim();
+    if (trimmed.length === 0) {
+      promptSamplesTruncated = true;
+      continue;
+    }
+    const individuallyBounded = trimmed.slice(0, MAX_PROMPT_SAMPLE_CHARS);
+    const remaining = MAX_PROMPT_SAMPLE_TOTAL_CHARS - totalChars;
+    if (remaining <= 0) {
+      promptSamplesTruncated = true;
+      break;
+    }
+    const text = individuallyBounded.slice(0, remaining);
+    if (text.length !== candidate.text.length || text.length !== trimmed.length) {
+      promptSamplesTruncated = true;
+    }
+    const age = sampleAge(observedAtEpochMs, cutoffEpochMs);
+    ages[age === 'within-window' ? 'withinWindow' : age === 'older-than-window' ? 'olderThanWindow' : 'unknown'] += 1;
+    promptSamples.push({ text, age });
+    totalChars += text.length;
+    if (text.length < individuallyBounded.length) {
+      promptSamplesTruncated = true;
+      break;
+    }
+  }
+  if (promptSamples.length < input.promptSamples.length) promptSamplesTruncated = true;
+
+  const effectiveContext = userContext.length > 0 ? userContext : undefined;
+  return {
+    ok: true,
+    value: {
+      schemaVersion: LEGACY_PERSONALIZATION_MIGRATION_VERSION,
+      windowDays: input.promptWindowDays,
+      ...(effectiveContext === undefined ? {} : { userContext: effectiveContext }),
+      promptSamples,
+      migration: {
+        requiresExplicitPromptPersonalizationConsent:
+          effectiveContext !== undefined || promptSamples.length > 0,
+        userContextChars: effectiveContext?.length ?? 0,
+        userContextTruncated: rawContext.length > MAX_LEGACY_USER_CONTEXT_CHARS,
+        promptSampleCount: promptSamples.length,
+        promptSamplesTruncated,
+        sampleAge: ages,
+      },
+    },
+  };
+}
+
+/**
+ * Create the exact future payload addendum only after separate consent. The
+ * current v2.3.1 prototype deliberately has no production caller.
+ */
+export function projectLegacyPersonalization(
+  draft: unknown,
+  consent: unknown,
+): LegacyPersonalizationProjection | undefined {
+  if (consent !== 'explicit' || !validDraft(draft)) {
+    return undefined;
+  }
+  return {
+    schemaVersion: LEGACY_PERSONALIZATION_MIGRATION_VERSION,
+    consent: 'explicit',
+    windowDays: draft.windowDays,
+    ...(draft.userContext === undefined ? {} : { userContext: draft.userContext }),
+    promptSamples: draft.promptSamples.map((sample) => ({ ...sample })),
+  };
+}
diff --git a/src/adviceEffectiveness/modelExperiment.ts b/src/adviceEffectiveness/modelExperiment.ts
new file mode 100644
index 00000000..61616f8a
--- /dev/null
+++ b/src/adviceEffectiveness/modelExperiment.ts
@@ -0,0 +1,125 @@
+import { AdviceRecommendation } from './contract';
+import {
+  AdviceComparisonPolicy,
+  AdviceComparisonResult,
+  ComparableTaskPair,
+  DEFAULT_ADVICE_COMPARISON_POLICY,
+  compareAdviceEffectiveness,
+} from './comparison';
+
+export type ExperimentModelFamily = 'opus' | 'sonnet' | 'haiku';
+
+export interface ModelRightsizingExperimentInput {
+  recommendationId: string;
+  baselineModelFamily: ExperimentModelFamily;
+  candidateModelFamily: ExperimentModelFamily;
+  evidenceId: string;
+  metricObservationId: string;
+}
+
+const ONE_TIER_LOWER: Partial<Record<ExperimentModelFamily, ExperimentModelFamily>> = {
+  opus: 'sonnet',
+  sonnet: 'haiku',
+};
+
+/**
+ * Typed seam for the dormant model-rightsizing signal. It never turns the
+ * weak “small output” proxy into a directive or savings claim. A candidate is
+ * valid only as a reversible, one-tier experiment on comparable tasks, using
+ * the same local feedback and quality guardrails as every other recommendation.
+ */
+export function buildReversibleModelExperiment(
+  input: ModelRightsizingExperimentInput,
+): AdviceRecommendation | undefined {
+  if (ONE_TIER_LOWER[input.baselineModelFamily] !== input.candidateModelFamily) {
+    return undefined;
+  }
+  return {
+    id: input.recommendationId,
+    title: 'advice.recommendation.model-one-tier-experiment',
+    evidenceIds: [input.evidenceId],
+    explanation: {
+      summary: 'advice.explanation.model-output-size-is-weak-proxy',
+      proxyMetricObservationIds: [input.metricObservationId],
+      limitations: [
+        'advice.limitation.model-experiment-not-causal',
+        'advice.limitation.model-experiment-no-savings-claim',
+      ],
+    },
+    conditionalActions: [
+      {
+        when: 'advice.when.same-task-cohort-and-quality-rubric',
+        action: 'advice.action.compare-one-tier-lower-model',
+        evidenceIds: [input.evidenceId],
+        stopCondition: 'advice.stop.restore-baseline-on-quality-regression',
+      },
+    ],
+    successCriteria: [
+      {
+        metricObservationId: input.metricObservationId,
+        direction: 'decrease',
+        target: { kind: 'relative-change', value: 0.1 },
+        minimumComparableTasks: 5,
+        qualityGuardrail: {
+          rubricId: 'task-quality-rubric-v1',
+          minimumScore: 0.8,
+          maximumRegression: 0.02,
+        },
+      },
+    ],
+  };
+}
+
+export interface ReversibleModelExperimentComparisonInput {
+  baselineModelFamily: ExperimentModelFamily;
+  candidateModelFamily: ExperimentModelFamily;
+  applied: boolean;
+  localRating: 'unrated' | 'helpful' | 'not-helpful';
+  pairs: readonly ComparableTaskPair[];
+  policy?: AdviceComparisonPolicy;
+}
+
+/**
+ * Compare a one-tier intervention while keeping every other comparability
+ * dimension strict. Model family is normalized only after each pair proves it
+ * represents the declared baseline→candidate transition.
+ */
+export function compareReversibleModelExperiment(
+  input: ReversibleModelExperimentComparisonInput,
+): AdviceComparisonResult {
+  const insufficient = (reason: string): AdviceComparisonResult => ({
+    status: 'insufficient-evidence',
+    reasons: [reason],
+    comparablePairs: input.pairs.length,
+  });
+  if (ONE_TIER_LOWER[input.baselineModelFamily] !== input.candidateModelFamily) {
+    return insufficient('model experiment is not an adjacent lower-tier transition');
+  }
+  if (!input.applied || input.localRating === 'unrated') {
+    return insufficient('model experiment requires local applied and rating feedback');
+  }
+  for (const pair of input.pairs) {
+    if (
+      pair.before.context.modelFamily !== input.baselineModelFamily ||
+      pair.after.context.modelFamily !== input.candidateModelFamily
+    ) {
+      return insufficient(`pair ${pair.pairId} does not match the declared model transition`);
+    }
+  }
+  const interventionKey = `experiment-${input.baselineModelFamily}-to-${input.candidateModelFamily}`;
+  const normalized = input.pairs.map((pair) => ({
+    ...pair,
+    before: {
+      ...pair.before,
+      context: { ...pair.before.context, modelFamily: interventionKey },
+    },
+    after: {
+      ...pair.after,
+      context: { ...pair.after.context, modelFamily: interventionKey },
+    },
+  }));
+  return compareAdviceEffectiveness(
+    normalized,
+    input.policy ?? DEFAULT_ADVICE_COMPARISON_POLICY,
+  );
+}
diff --git a/src/adviceEffectiveness/payload.ts b/src/adviceEffectiveness/payload.ts
new file mode 100644
index 00000000..eebafcb5
--- /dev/null
+++ b/src/adviceEffectiveness/payload.ts
@@ -0,0 +1,499 @@
+import { createHash } from 'node:crypto';
+import { UsageData } from '../types';
+import {
+  ADVICE_CONTRACT_VERSION,
+  AdviceEvidence,
+  AdviceObservation,
+  AdviceSourceInfo,
+  isAdviceIdentifier,
+} from './contract';
+
+export const ADVICE_REMOTE_PAYLOAD_VERSION = 1 as const;
+export const MAX_PROMPT_SAMPLES = 20;
+export const MAX_PROMPT_SAMPLE_CHARS = 1_000;
+export const MAX_PROMPT_SAMPLE_TOTAL_CHARS = 12_000;
+export const MAX_USER_CONTEXT_CHARS = 1_000;
+
+/** Adding a metric here is an explicit remote-data/privacy review point. */
+export const REMOTE_ADVICE_METRIC_ALLOWLIST = [
+  'approval-reviewer-share',
+  'cache-creation-tokens',
+  'cache-hit-rate',
+  'cache-read-share',
+  'cache-read-tokens',
+  'estimated-cost-usd',
+  'framework-overhead-share',
+  'high-effort-share',
+  'input-tokens',
+  'large-context-share',
+  'long-session-share',
+  'message-count',
+  'multi-agent-share',
+  'output-tokens',
+  'post-patch-tool-intensity',
+  'processed-to-fresh-ratio',
+  'quality-score',
+  'subagent-share',
+  'task-primary-metric',
+  'thinking-share',
+  'workflow-share',
+] as const;
+
+export type AdviceModelFamily = 'opus' | 'sonnet' | 'haiku' | 'fable' | 'other';
+
+export interface AdviceAggregateSnapshot {
+  scope: 'overall' | 'project';
+  windowDays: number;
+  totals: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    messageCount: number;
+    estimatedCostUsd: number;
+  };
+  modelFamilies: {
+    family: AdviceModelFamily;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    count: number;
+  }[];
+}
+
+export interface PromptSampleOptIn {
+  consent: 'explicit';
+  /** Configured context shares the same separate prompt-personalisation consent. */
+  userContext?: string;
+  /** Only text is accepted. Extra runtime fields such as cwd are discarded. */
+  samples: readonly { text: string }[];
+}
+
+export interface PrepareAdvicePayloadInput {
+  locale: string;
+  aggregate: AdviceAggregateSnapshot;
+  sources: readonly AdviceSourceInfo[];
+  observations: readonly AdviceObservation[];
+  evidence: readonly AdviceEvidence[];
+  promptSamples?: PromptSampleOptIn;
+}
+
+export interface PreparedAdvicePayload {
+  contentType: 'application/json';
+  dataMode:
+    | 'aggregates-only'
+    | 'aggregates-with-personalization'
+    | 'aggregates-with-prompt-samples';
+  promptSampleCount: number;
+  /** The one canonical serialization used by both preview and transport. */
+  serializedBody: string;
+  /** Exact UTF-8 bytes derived once from serializedBody. The sender uses these bytes directly. */
+  canonicalBytes: Uint8Array;
+  /** SHA-256 of canonicalBytes, lowercase hexadecimal. */
+  sha256: string;
+}
+
+export interface AdvicePayloadPreview {
+  contentType: 'application/json';
+  dataMode: PreparedAdvicePayload['dataMode'];
+  promptSampleCount: number;
+  body: string;
+  utf8Bytes: number;
+  sha256: string;
+}
+
+interface RemoteAdviceRequest {
+  schemaVersion: typeof ADVICE_REMOTE_PAYLOAD_VERSION;
+  responseContractVersion: typeof ADVICE_CONTRACT_VERSION;
+  locale: string;
+  aggregate: AdviceAggregateSnapshot;
+  signals: {
+    sources: {
+      id: string;
+      kind: AdviceSourceInfo['kind'];
+      scope: AdviceSourceInfo['scope'];
+      window: AdviceSourceInfo['window'];
+      confidence: 'high' | 'medium';
+    }[];
+    observations: {
+      id: string;
+      metric: string;
+      value: number | boolean;
+      unit: AdviceObservation['unit'];
+      method: AdviceObservation['method'];
+      sourceId: string;
+    }[];
+    evidence: {
+      id: string;
+      observationIds: string[];
+      strength: AdviceEvidence['strength'];
+    }[];
+  };
+  responseRules: {
+    format: 'strict-json';
+    unknownFields: 'reject';
+    evidenceReferences: 'required';
+    qualityGuardrail: 'required';
+    hostOwnedFields: ['observations', 'evidence', 'privacy', 'provenance'];
+  };
+  privacy: {
+    dataMode: PreparedAdvicePayload['dataMode'];
+    promptSampleConsent: 'not-granted' | 'explicit';
+    promptSampleCount: number;
+    userContextIncluded: boolean;
+  };
+  userContext?: string;
+  promptSamples?: { id: string; text: string }[];
+}
+
+function requireFiniteNonNegative(value: number, label: string): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be a finite non-negative number`);
+  }
+  return value;
+}
+
+function requireCount(value: number, label: string): number {
+  requireFiniteNonNegative(value, label);
+  if (!Number.isInteger(value)) throw new Error(`${label} must be an integer`);
+  return value;
+}
+
+function modelFamily(model: string): AdviceModelFamily {
+  const normalized = model.toLowerCase();
+  if (normalized.includes('opus')) return 'opus';
+  if (normalized.includes('sonnet')) return 'sonnet';
+  if (normalized.includes('haiku')) return 'haiku';
+  if (normalized.includes('fable')) return 'fable';
+  return 'other';
+}
+
+/**
+ * Convert the existing UsageData aggregate through an explicit allow-list.
+ * Full/custom model IDs, project labels, paths, sessions, and prompt content
+ * have no destination field and therefore cannot leak through object spreads.
+ */
+export function buildAdviceAggregateSnapshot(
+  usage: UsageData,
+  scope: AdviceAggregateSnapshot['scope'],
+  windowDays: number
+): AdviceAggregateSnapshot {
+  if (!Number.isInteger(windowDays) || windowDays < 1 || windowDays > 3_650) {
+    throw new Error('windowDays must be an integer from 1 to 3650');
+  }
+  const families = new Map<AdviceModelFamily, AdviceAggregateSnapshot['modelFamilies'][number]>();
+  for (const model of Object.keys(usage.modelBreakdown)) {
+    const row = usage.modelBreakdown[model];
+    const family = modelFamily(model);
+    const current = families.get(family) || {
+      family,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheCreationTokens: 0,
+      cacheReadTokens: 0,
+      count: 0,
+    };
+    current.inputTokens += requireFiniteNonNegative(row.inputTokens, `${family}.inputTokens`);
+    current.outputTokens += requireFiniteNonNegative(row.outputTokens, `${family}.outputTokens`);
+    current.cacheCreationTokens += requireFiniteNonNegative(
+      row.cacheCreationTokens,
+      `${family}.cacheCreationTokens`
+    );
+    current.cacheReadTokens += requireFiniteNonNegative(row.cacheReadTokens, `${family}.cacheReadTokens`);
+    current.count += requireCount(row.count, `${family}.count`);
+    families.set(family, current);
+  }
+
+  return {
+    scope,
+    windowDays,
+    totals: {
+      inputTokens: requireFiniteNonNegative(usage.totalInputTokens, 'totalInputTokens'),
+      outputTokens: requireFiniteNonNegative(usage.totalOutputTokens, 'totalOutputTokens'),
+      cacheCreationTokens: requireFiniteNonNegative(
+        usage.totalCacheCreationTokens,
+        'totalCacheCreationTokens'
+      ),
+      cacheReadTokens: requireFiniteNonNegative(usage.totalCacheReadTokens, 'totalCacheReadTokens'),
+      messageCount: requireCount(usage.messageCount, 'messageCount'),
+      estimatedCostUsd: requireFiniteNonNegative(usage.totalCost, 'totalCost'),
+    },
+    modelFamilies: Array.from(families.values()).sort((a, b) => a.family.localeCompare(b.family)),
+  };
+}
+
+export function validateAdviceAggregateSnapshot(aggregate: AdviceAggregateSnapshot): void {
+  if (aggregate.scope !== 'overall' && aggregate.scope !== 'project') {
+    throw new Error('aggregate scope is invalid');
+  }
+  if (!Number.isInteger(aggregate.windowDays) || aggregate.windowDays < 1 || aggregate.windowDays > 3_650) {
+    throw new Error('aggregate windowDays is invalid');
+  }
+  requireFiniteNonNegative(aggregate.totals.inputTokens, 'aggregate.inputTokens');
+  requireFiniteNonNegative(aggregate.totals.outputTokens, 'aggregate.outputTokens');
+  requireFiniteNonNegative(aggregate.totals.cacheCreationTokens, 'aggregate.cacheCreationTokens');
+  requireFiniteNonNegative(aggregate.totals.cacheReadTokens, 'aggregate.cacheReadTokens');
+  requireCount(aggregate.totals.messageCount, 'aggregate.messageCount');
+  requireFiniteNonNegative(aggregate.totals.estimatedCostUsd, 'aggregate.estimatedCostUsd');
+  const allowedFamilies = new Set<AdviceModelFamily>(['opus', 'sonnet', 'haiku', 'fable', 'other']);
+  const seen = new Set<AdviceModelFamily>();
+  for (const row of aggregate.modelFamilies) {
+    if (!allowedFamilies.has(row.family) || seen.has(row.family)) {
+      throw new Error('aggregate model family is invalid or duplicated');
+    }
+    seen.add(row.family);
+    requireFiniteNonNegative(row.inputTokens, `${row.family}.inputTokens`);
+    requireFiniteNonNegative(row.outputTokens, `${row.family}.outputTokens`);
+    requireFiniteNonNegative(row.cacheCreationTokens, `${row.family}.cacheCreationTokens`);
+    requireFiniteNonNegative(row.cacheReadTokens, `${row.family}.cacheReadTokens`);
+    requireCount(row.count, `${row.family}.count`);
+  }
+}
+
+function validateSignalGraph(input: PrepareAdvicePayloadInput): void {
+  if (!/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(input.locale)) {
+    throw new Error('locale must be a BCP-47-style locale code');
+  }
+  if (input.sources.length === 0 || input.observations.length === 0 || input.evidence.length === 0) {
+    throw new Error('evidence-backed advice requires sources, observations, and evidence');
+  }
+  const sourceIds = new Set<string>();
+  for (const source of input.sources) {
+    if (!isAdviceIdentifier(source.id) || sourceIds.has(source.id)) throw new Error('invalid source id');
+    sourceIds.add(source.id);
+    if (source.confidence !== 'high' && source.confidence !== 'medium') {
+      throw new Error('remote advice requires high or medium source confidence');
+    }
+    if (source.qualityFlags.length > 0) {
+      throw new Error('remote advice does not accept unresolved source quality flags');
+    }
+    if (source.window.kind === 'rolling-days') {
+      if (!Number.isInteger(source.window.days) || source.window.days < 1) {
+        throw new Error('invalid source window');
+      }
+    }
+    for (const flag of source.qualityFlags) {
+      if (!isAdviceIdentifier(flag)) throw new Error('invalid source quality flag');
+    }
+  }
+  const observationIds = new Set<string>();
+  const allowedMetrics = new Set<string>(REMOTE_ADVICE_METRIC_ALLOWLIST);
+  for (const observation of input.observations) {
+    if (!isAdviceIdentifier(observation.id) || observationIds.has(observation.id)) {
+      throw new Error('invalid observation id');
+    }
+    observationIds.add(observation.id);
+    if (!allowedMetrics.has(observation.metric) || !sourceIds.has(observation.sourceId)) {
+      throw new Error('invalid observation metric or source reference');
+    }
+    if (typeof observation.value === 'number') {
+      requireFiniteNonNegative(observation.value, observation.metric);
+    }
+    if (observation.unit === 'ratio' && typeof observation.value === 'number' && observation.value > 1) {
+      throw new Error('ratio observations must be between 0 and 1');
+    }
+    if (observation.unit === 'percent' && typeof observation.value === 'number' && observation.value > 100) {
+      throw new Error('percent observations must be between 0 and 100');
+    }
+    if (observation.unit === 'boolean' && typeof observation.value !== 'boolean') {
+      throw new Error('boolean observations require a boolean value');
+    }
+  }
+  const evidenceIds = new Set<string>();
+  for (const item of input.evidence) {
+    if (!isAdviceIdentifier(item.id) || evidenceIds.has(item.id) || item.observationIds.length === 0) {
+      throw new Error('invalid evidence id or empty evidence references');
+    }
+    evidenceIds.add(item.id);
+    for (const observationId of item.observationIds) {
+      if (!observationIds.has(observationId)) throw new Error('evidence references an unknown observation');
+    }
+  }
+}
+
+function promptSamples(optIn: PromptSampleOptIn | undefined): { id: string; text: string }[] {
+  if (optIn === undefined) return [];
+  if (optIn.consent !== 'explicit' || !Array.isArray(optIn.samples)) {
+    throw new Error('prompt samples require a separate explicit opt-in');
+  }
+  const out: { id: string; text: string }[] = [];
+  let totalChars = 0;
+  for (const sample of optIn.samples.slice(0, MAX_PROMPT_SAMPLES)) {
+    if (!sample || typeof sample.text !== 'string') throw new Error('prompt sample text must be a string');
+    const text = sample.text.trim().slice(0, MAX_PROMPT_SAMPLE_CHARS);
+    if (text.length === 0) continue;
+    const remaining = MAX_PROMPT_SAMPLE_TOTAL_CHARS - totalChars;
+    if (remaining <= 0) break;
+    const bounded = text.slice(0, remaining);
+    out.push({ id: `prompt-${out.length + 1}`, text: bounded });
+    totalChars += bounded.length;
+  }
+  return out;
+}
+
+function userContext(optIn: PromptSampleOptIn | undefined): string | undefined {
+  if (optIn === undefined || optIn.userContext === undefined) return undefined;
+  if (optIn.consent !== 'explicit' || typeof optIn.userContext !== 'string') {
+    throw new Error('user context requires the separate prompt-personalisation opt-in');
+  }
+  const text = optIn.userContext.trim().slice(0, MAX_USER_CONTEXT_CHARS);
+  return text.length > 0 ? text : undefined;
+}
+
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('payload contains a non-finite number');
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item));
+  if (typeof value === 'object') {
+    const source = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(source).sort()) {
+      const item = source[key];
+      if (item !== undefined) out[key] = canonicalize(item);
+    }
+    return out;
+  }
+  throw new Error(`payload contains unsupported ${typeof value} value`);
+}
+
+export function stableAdvicePayloadStringify(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+/** Build and serialize once. Aggregates-only is the default and has no promptSamples key. */
+export function prepareAdvicePayload(input: PrepareAdvicePayloadInput): PreparedAdvicePayload {
+  validateAdviceAggregateSnapshot(input.aggregate);
+  validateSignalGraph(input);
+  const samples = promptSamples(input.promptSamples);
+  const context = userContext(input.promptSamples);
+  if (input.promptSamples !== undefined && samples.length === 0 && context === undefined) {
+    throw new Error('explicit prompt opt-in must contain a sample or user context');
+  }
+  const dataMode: PreparedAdvicePayload['dataMode'] =
+    samples.length > 0
+      ? 'aggregates-with-prompt-samples'
+      : context !== undefined
+        ? 'aggregates-with-personalization'
+        : 'aggregates-only';
+
+  const request: RemoteAdviceRequest = {
+    schemaVersion: ADVICE_REMOTE_PAYLOAD_VERSION,
+    responseContractVersion: ADVICE_CONTRACT_VERSION,
+    locale: input.locale,
+    aggregate: {
+      scope: input.aggregate.scope,
+      windowDays: input.aggregate.windowDays,
+      totals: {
+        inputTokens: input.aggregate.totals.inputTokens,
+        outputTokens: input.aggregate.totals.outputTokens,
+        cacheCreationTokens: input.aggregate.totals.cacheCreationTokens,
+        cacheReadTokens: input.aggregate.totals.cacheReadTokens,
+        messageCount: input.aggregate.totals.messageCount,
+        estimatedCostUsd: input.aggregate.totals.estimatedCostUsd,
+      },
+      modelFamilies: input.aggregate.modelFamilies.map((row) => ({
+        family: row.family,
+        inputTokens: row.inputTokens,
+        outputTokens: row.outputTokens,
+        cacheCreationTokens: row.cacheCreationTokens,
+        cacheReadTokens: row.cacheReadTokens,
+        count: row.count,
+      })),
+    },
+    signals: {
+      sources: input.sources.map((source) => ({
+        id: source.id,
+        kind: source.kind,
+        scope: source.scope,
+        window:
+          source.window.kind === 'rolling-days'
+            ? { kind: 'rolling-days', days: source.window.days }
+            : { kind: source.window.kind },
+        confidence: source.confidence as 'high' | 'medium',
+      })),
+      observations: input.observations.map((observation) => ({
+        id: observation.id,
+        metric: observation.metric,
+        value: observation.value,
+        unit: observation.unit,
+        method: observation.method,
+        sourceId: observation.sourceId,
+      })),
+      evidence: input.evidence.map((item) => ({
+        id: item.id,
+        observationIds: [...item.observationIds],
+        strength: item.strength,
+      })),
+    },
+    responseRules: {
+      format: 'strict-json',
+      unknownFields: 'reject',
+      evidenceReferences: 'required',
+      qualityGuardrail: 'required',
+      hostOwnedFields: ['observations', 'evidence', 'privacy', 'provenance'],
+    },
+    privacy: {
+      dataMode,
+      promptSampleConsent: input.promptSamples !== undefined ? 'explicit' : 'not-granted',
+      promptSampleCount: samples.length,
+      userContextIncluded: context !== undefined,
+    },
+  };
+  if (context !== undefined) request.userContext = context;
+  if (samples.length > 0) request.promptSamples = samples;
+
+  const serializedBody = stableAdvicePayloadStringify(request);
+  const canonicalBytes = Buffer.from(serializedBody, 'utf8');
+  const sha256 = createHash('sha256').update(canonicalBytes).digest('hex');
+  return {
+    contentType: 'application/json',
+    dataMode,
+    promptSampleCount: samples.length,
+    serializedBody,
+    canonicalBytes,
+    sha256,
+  };
+}
+
+function assertPreparedAdvicePayloadIntegrity(prepared: PreparedAdvicePayload): void {
+  if (!(prepared.canonicalBytes instanceof Uint8Array)) {
+    throw new Error('prepared advice payload bytes are invalid');
+  }
+  const decoded = Buffer.from(prepared.canonicalBytes).toString('utf8');
+  const digest = createHash('sha256').update(prepared.canonicalBytes).digest('hex');
+  if (decoded !== prepared.serializedBody || digest !== prepared.sha256) {
+    throw new Error('prepared advice payload integrity check failed');
+  }
+}
+
+/** Preview decodes the same canonical bytes that the explicit sender receives. */
+export function previewAdvicePayload(prepared: PreparedAdvicePayload): AdvicePayloadPreview {
+  assertPreparedAdvicePayloadIntegrity(prepared);
+  return {
+    contentType: prepared.contentType,
+    dataMode: prepared.dataMode,
+    promptSampleCount: prepared.promptSampleCount,
+    body: Buffer.from(prepared.canonicalBytes).toString('utf8'),
+    utf8Bytes: prepared.canonicalBytes.byteLength,
+    sha256: prepared.sha256,
+  };
+}
+
+export type AdvicePayloadSender<T> = (
+  canonicalBytes: Uint8Array,
+  contentType: PreparedAdvicePayload['contentType'],
+  sha256: string,
+) => Promise<T>;
+
+/** This boundary deliberately cannot reserialize: it only receives the prepared bytes. */
+export async function sendPreparedAdvicePayload<T>(
+  prepared: PreparedAdvicePayload,
+  sender: AdvicePayloadSender<T>
+): Promise<T> {
+  assertPreparedAdvicePayloadIntegrity(prepared);
+  return sender(prepared.canonicalBytes, prepared.contentType, prepared.sha256);
+}
diff --git a/src/adviceEffectiveness/preparedRequest.ts b/src/adviceEffectiveness/preparedRequest.ts
new file mode 100644
index 00000000..1954fce1
--- /dev/null
+++ b/src/adviceEffectiveness/preparedRequest.ts
@@ -0,0 +1,254 @@
+import { createHash } from 'node:crypto';
+
+import type { AdviceFormat } from '../advisor';
+import { stableAdvicePayloadStringify } from './payload';
+
+const AI_INVOCATION_SCHEMA_VERSION = 1 as const;
+const AI_MAX_TOKENS = 16_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export type AiInvocationKind = 'advice' | 'optimizer';
+export type AiInvocationDataMode =
+  | 'aggregates-only'
+  | 'aggregates-with-personalization'
+  | 'aggregates-with-prompt-samples'
+  | 'user-draft-only';
+
+export interface PrepareAiInvocationInput {
+  kind: AiInvocationKind;
+  apiFormat: AdviceFormat;
+  apiUrl: string;
+  model: string;
+  reasoningEffort?: string;
+  systemPrompt: string;
+  userContent: string;
+  dataMode: AiInvocationDataMode;
+  /** Opaque provider-index or draft revision; never a path/session/title. */
+  sourceRevision: string;
+  consentGeneration: number;
+  createdAtEpochMs: number;
+  timeoutMs?: number;
+}
+
+export interface PreparedAiInvocation {
+  readonly schemaVersion: typeof AI_INVOCATION_SCHEMA_VERSION;
+  readonly kind: AiInvocationKind;
+  readonly apiFormat: AdviceFormat;
+  readonly endpoint: string;
+  readonly model: string;
+  readonly dataMode: AiInvocationDataMode;
+  readonly sourceRevision: string;
+  readonly consentGeneration: number;
+  readonly createdAtEpochMs: number;
+  readonly timeoutMs: number;
+  readonly contentType: 'application/json';
+  /** Canonical full provider HTTP body. It is never rebuilt after preparation. */
+  readonly serializedBody: string;
+  readonly canonicalBytes: Uint8Array;
+  readonly sha256: string;
+}
+
+export interface AiInvocationPreview {
+  kind: AiInvocationKind;
+  dataMode: AiInvocationDataMode;
+  contentType: 'application/json';
+  body: string;
+  utf8Bytes: number;
+  sha256: string;
+}
+
+export interface PreparedAiSendAuthorization {
+  backend: 'api';
+  apiKey: string;
+  expectedSourceRevision?: string;
+  expectedConsentGeneration?: number;
+  signal?: AbortSignal;
+}
+
+export interface PreparedAiTransportRequest {
+  endpoint: string;
+  apiFormat: AdviceFormat;
+  contentType: 'application/json';
+  headers: Record<string, string>;
+  /** Same object identity as PreparedAiInvocation.canonicalBytes. */
+  canonicalBytes: Uint8Array;
+  timeoutMs: number;
+  signal?: AbortSignal;
+}
+
+export type PreparedAiTransport<T> = (request: PreparedAiTransportRequest) => Promise<T>;
+
+function normalizeOpenAiUrl(value: string): string {
+  let url = value.trim().replace(/\/+$/, '');
+  if (url === '') return 'https://api.deepseek.com/chat/completions';
+  if (/api\.deepseek\.com\/v1(?:\/chat\/completions)?$/.test(url)) {
+    url = url.replace('/v1', '');
+  }
+  return url.endsWith('/chat/completions') ? url : `${url}/chat/completions`;
+}
+
+function normalizeAnthropicUrl(value: string): string {
+  const url = value.trim().replace(/\/+$/, '');
+  if (url === '' || /api\.anthropic\.com$/.test(url) || /chat\/completions$/.test(url)) {
+    return 'https://api.anthropic.com/v1/messages';
+  }
+  return url.endsWith('/v1/messages') ? url : `${url}/v1/messages`;
+}
+
+function requireBoundedText(value: string, label: string, maxChars: number): string {
+  if (typeof value !== 'string') throw new Error(`${label} must be a string`);
+  const text = value.trim();
+  if (text.length === 0 || text.length > maxChars) {
+    throw new Error(`${label} must contain 1-${maxChars} characters`);
+  }
+  return value;
+}
+
+function requireOpaqueRevision(value: string): string {
+  if (!/^[A-Za-z0-9._:-]{1,128}$/.test(value)) {
+    throw new Error('sourceRevision must be an opaque revision');
+  }
+  return value;
+}
+
+function requestBody(input: PrepareAiInvocationInput): Record<string, unknown> {
+  if (input.apiFormat === 'anthropic') {
+    return {
+      model: requireBoundedText(input.model, 'model', 256),
+      max_tokens: AI_MAX_TOKENS,
+      system: requireBoundedText(input.systemPrompt, 'systemPrompt', 40_000),
+      messages: [{ role: 'user', content: requireBoundedText(input.userContent, 'userContent', 200_000) }],
+    };
+  }
+  const body: Record<string, unknown> = {
+    model: requireBoundedText(input.model, 'model', 256),
+    stream: false,
+    messages: [
+      { role: 'system', content: requireBoundedText(input.systemPrompt, 'systemPrompt', 40_000) },
+      { role: 'user', content: requireBoundedText(input.userContent, 'userContent', 200_000) },
+    ],
+  };
+  const reasoningEffort = input.reasoningEffort?.trim();
+  if (reasoningEffort) {
+    if (!/^[A-Za-z0-9_-]{1,32}$/.test(reasoningEffort)) {
+      throw new Error('reasoningEffort is invalid');
+    }
+    body.reasoning_effort = reasoningEffort;
+  }
+  return body;
+}
+
+/** Prepare the complete provider wire body exactly once. No credential enters it. */
+export function prepareAiInvocation(input: PrepareAiInvocationInput): PreparedAiInvocation {
+  if (input.kind !== 'advice' && input.kind !== 'optimizer') {
+    throw new Error('AI invocation kind is invalid');
+  }
+  if (input.apiFormat !== 'anthropic' && input.apiFormat !== 'openai') {
+    throw new Error('AI invocation format is invalid');
+  }
+  if (!Number.isInteger(input.consentGeneration) || input.consentGeneration < 0) {
+    throw new Error('consentGeneration must be a non-negative integer');
+  }
+  if (!Number.isFinite(input.createdAtEpochMs) || input.createdAtEpochMs < 0) {
+    throw new Error('createdAtEpochMs must be finite and non-negative');
+  }
+  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 10 * 60_000) {
+    throw new Error('timeoutMs is outside the supported range');
+  }
+  const serializedBody = stableAdvicePayloadStringify(requestBody(input));
+  const canonicalBytes = Buffer.from(serializedBody, 'utf8');
+  const sha256 = createHash('sha256').update(canonicalBytes).digest('hex');
+  return {
+    schemaVersion: AI_INVOCATION_SCHEMA_VERSION,
+    kind: input.kind,
+    apiFormat: input.apiFormat,
+    endpoint: input.apiFormat === 'anthropic'
+      ? normalizeAnthropicUrl(input.apiUrl)
+      : normalizeOpenAiUrl(input.apiUrl),
+    model: input.model.trim(),
+    dataMode: input.dataMode,
+    sourceRevision: requireOpaqueRevision(input.sourceRevision),
+    consentGeneration: input.consentGeneration,
+    createdAtEpochMs: input.createdAtEpochMs,
+    timeoutMs,
+    contentType: 'application/json',
+    serializedBody,
+    canonicalBytes,
+    sha256,
+  };
+}
+
+export function assertPreparedAiInvocationIntegrity(prepared: PreparedAiInvocation): void {
+  if (
+    prepared.schemaVersion !== AI_INVOCATION_SCHEMA_VERSION ||
+    !(prepared.canonicalBytes instanceof Uint8Array) ||
+    prepared.contentType !== 'application/json'
+  ) {
+    throw new Error('prepared AI invocation integrity check failed');
+  }
+  const decoded = Buffer.from(prepared.canonicalBytes).toString('utf8');
+  const digest = createHash('sha256').update(prepared.canonicalBytes).digest('hex');
+  if (decoded !== prepared.serializedBody || digest !== prepared.sha256) {
+    throw new Error('prepared AI invocation integrity check failed');
+  }
+}
+
+export function previewAiInvocation(prepared: PreparedAiInvocation): AiInvocationPreview {
+  assertPreparedAiInvocationIntegrity(prepared);
+  return {
+    kind: prepared.kind,
+    dataMode: prepared.dataMode,
+    contentType: prepared.contentType,
+    body: Buffer.from(prepared.canonicalBytes).toString('utf8'),
+    utf8Bytes: prepared.canonicalBytes.byteLength,
+    sha256: prepared.sha256,
+  };
+}
+
+/**
+ * The only send boundary. It validates current consent/source generation and
+ * gives transport the original canonical byte object; it cannot reserialize.
+ */
+export async function sendPreparedAiInvocation<T>(
+  prepared: PreparedAiInvocation,
+  authorization: PreparedAiSendAuthorization,
+  transport: PreparedAiTransport<T>,
+): Promise<T> {
+  assertPreparedAiInvocationIntegrity(prepared);
+  if (!authorization || authorization.backend !== 'api') {
+    throw new Error('Only the configured BYOK API backend may send AI requests');
+  }
+  const apiKey = authorization.apiKey?.trim();
+  if (!apiKey) throw new Error('A user-configured API key is required');
+  if (
+    (authorization.expectedSourceRevision !== undefined &&
+      authorization.expectedSourceRevision !== prepared.sourceRevision) ||
+    (authorization.expectedConsentGeneration !== undefined &&
+      authorization.expectedConsentGeneration !== prepared.consentGeneration)
+  ) {
+    throw new Error('The prepared AI invocation is stale');
+  }
+  if (authorization.signal?.aborted) {
+    throw new Error('The prepared AI invocation was cancelled');
+  }
+  const headers: Record<string, string> = prepared.apiFormat === 'anthropic'
+    ? {
+        'Content-Type': prepared.contentType,
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      }
+    : {
+        'Content-Type': prepared.contentType,
+        Authorization: `Bearer ${apiKey}`,
+      };
+  return transport({
+    endpoint: prepared.endpoint,
+    apiFormat: prepared.apiFormat,
+    contentType: prepared.contentType,
+    headers,
+    canonicalBytes: prepared.canonicalBytes,
+    timeoutMs: prepared.timeoutMs,
+    ...(authorization.signal ? { signal: authorization.signal } : {}),
+  });
+}
diff --git a/src/adviceEffectiveness/remoteAdvice.ts b/src/adviceEffectiveness/remoteAdvice.ts
new file mode 100644
index 00000000..9271fbd4
--- /dev/null
+++ b/src/adviceEffectiveness/remoteAdvice.ts
@@ -0,0 +1,113 @@
+import type {
+  PreparedAiTransportRequest,
+  PreparedAiInvocation,
+} from './preparedRequest';
+import { prepareAiInvocation } from './preparedRequest';
+import type { PreparedAdvicePayload } from './payload';
+import { previewAdvicePayload } from './payload';
+import { parseStructuredAdviceOutput } from './structuredOutput';
+import type {
+  StructuredAdviceOutput,
+  StructuredAdviceParseErrorCode,
+  StructuredAdviceReferences,
+} from './structuredOutput';
+import type { HttpResponse } from '../httpClient';
+import { sendPreparedModelRequest } from '../advisor';
+
+export const STRUCTURED_ADVICE_SYSTEM_PROMPT =
+  'Return exactly one strict JSON object matching the response contract in the user payload. ' +
+  'Do not use Markdown fences, prose outside JSON, unknown fields, or evidence IDs absent ' +
+  'from that payload. Return an empty recommendations array when the evidence is insufficient.';
+
+export interface StructuredAdviceInvocationConfig {
+  apiFormat: 'anthropic' | 'openai';
+  apiUrl: string;
+  model: string;
+  reasoningEffort?: string;
+  sourceRevision: string;
+  consentGeneration: number;
+  createdAtEpochMs: number;
+  timeoutMs?: number;
+}
+
+export interface StructuredAdviceSendOptions {
+  apiKey: string;
+  expectedSourceRevision?: string;
+  expectedConsentGeneration?: number;
+  signal?: AbortSignal;
+  transport?: (request: PreparedAiTransportRequest) => Promise<HttpResponse>;
+}
+
+export type StructuredAdviceRequestResult =
+  | { ok: true; value: StructuredAdviceOutput }
+  | {
+      ok: false;
+      code: StructuredAdviceParseErrorCode | 'transport-error' | 'invalid-prepared-request';
+      issues: string[];
+    };
+
+/**
+ * Wrap the sealed evidence body in the provider's complete HTTP body exactly
+ * once. The returned object, not the evidence-only inner payload, is what both
+ * preview and transport consume.
+ */
+export function prepareStructuredAdviceInvocation(
+  evidence: PreparedAdvicePayload,
+  config: StructuredAdviceInvocationConfig,
+): PreparedAiInvocation {
+  // This assertion catches any mismatch between the inner evidence preview and
+  // its bytes before those exact bytes are embedded in the provider body.
+  previewAdvicePayload(evidence);
+  return prepareAiInvocation({
+    kind: 'advice',
+    apiFormat: config.apiFormat,
+    apiUrl: config.apiUrl,
+    model: config.model,
+    ...(config.reasoningEffort ? { reasoningEffort: config.reasoningEffort } : {}),
+    systemPrompt: STRUCTURED_ADVICE_SYSTEM_PROMPT,
+    userContent: evidence.serializedBody,
+    dataMode: evidence.dataMode,
+    sourceRevision: config.sourceRevision,
+    consentGeneration: config.consentGeneration,
+    createdAtEpochMs: config.createdAtEpochMs,
+    ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
+  });
+}
+
+/**
+ * Strict advice send boundary. Only an already-prepared advice invocation may
+ * cross it; malformed output is rejected without prose repair or fallback.
+ */
+export async function requestStructuredAdvice(
+  prepared: PreparedAiInvocation,
+  references: StructuredAdviceReferences,
+  options: StructuredAdviceSendOptions,
+): Promise<StructuredAdviceRequestResult> {
+  if (prepared.kind !== 'advice' || prepared.dataMode === 'user-draft-only') {
+    return {
+      ok: false,
+      code: 'invalid-prepared-request',
+      issues: ['prepared request is not structured advice'],
+    };
+  }
+  let raw: string;
+  try {
+    raw = await sendPreparedModelRequest(prepared, options.apiKey, {
+      ...(options.expectedSourceRevision === undefined
+        ? {}
+        : { expectedSourceRevision: options.expectedSourceRevision }),
+      ...(options.expectedConsentGeneration === undefined
+        ? {}
+        : { expectedConsentGeneration: options.expectedConsentGeneration }),
+      ...(options.signal ? { signal: options.signal } : {}),
+      ...(options.transport ? { transport: options.transport } : {}),
+    });
+  } catch {
+    return {
+      ok: false,
+      code: 'transport-error',
+      issues: ['configured BYOK transport failed'],
+    };
+  }
+  return parseStructuredAdviceOutput(raw, references);
+}
diff --git a/src/adviceEffectiveness/structuredOutput.ts b/src/adviceEffectiveness/structuredOutput.ts
new file mode 100644
index 00000000..017e7b76
--- /dev/null
+++ b/src/adviceEffectiveness/structuredOutput.ts
@@ -0,0 +1,346 @@
+import {
+  ADVICE_CONTRACT_VERSION,
+  AdviceConditionalAction,
+  AdviceExplanation,
+  AdviceQualityGuardrail,
+  AdviceRecommendation,
+  AdviceSuccessCriterion,
+  isAdviceIdentifier,
+} from './contract';
+
+export interface StructuredAdviceOutput {
+  schemaVersion: typeof ADVICE_CONTRACT_VERSION;
+  /** Empty is a valid "no supported recommendation" result. */
+  recommendations: AdviceRecommendation[];
+}
+
+export interface StructuredAdviceReferences {
+  observationIds: readonly string[];
+  evidenceIds: readonly string[];
+}
+
+export type StructuredAdviceParseErrorCode =
+  | 'empty-output'
+  | 'output-too-large'
+  | 'invalid-json'
+  | 'invalid-schema'
+  | 'unknown-reference';
+
+export type StructuredAdviceParseResult =
+  | { ok: true; value: StructuredAdviceOutput }
+  | { ok: false; code: StructuredAdviceParseErrorCode; issues: string[] };
+
+const MAX_RAW_CHARS = 100_000;
+const MAX_RECOMMENDATIONS = 8;
+const MAX_ACTIONS = 4;
+const MAX_CRITERIA = 4;
+const MAX_REFERENCES = 12;
+const MAX_LIMITATIONS = 8;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function exactKeys(value: Record<string, unknown>, required: string[], optional: string[] = []): boolean {
+  const actual = Object.keys(value);
+  const allowed = new Set([...required, ...optional]);
+  return required.every((key) => actual.includes(key)) && actual.every((key) => allowed.has(key));
+}
+
+function boundedText(value: unknown, max: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const text = value.trim();
+  return text.length > 0 && text.length <= max ? text : undefined;
+}
+
+function idArray(
+  value: unknown,
+  max: number,
+  known: Set<string>,
+  path: string,
+  issues: string[],
+  allowEmpty: boolean = false
+): string[] | undefined {
+  if (!Array.isArray(value) || value.length > max || (!allowEmpty && value.length === 0)) {
+    issues.push(`${path} must be a bounded reference array`);
+    return undefined;
+  }
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== 'string' || !isAdviceIdentifier(item) || seen.has(item)) {
+      issues.push(`${path} contains an invalid or duplicate id`);
+      return undefined;
+    }
+    if (!known.has(item)) {
+      issues.push(`${path} contains an unknown reference`);
+      return undefined;
+    }
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+}
+
+function textArray(value: unknown, path: string, issues: string[]): string[] | undefined {
+  if (!Array.isArray(value) || value.length > MAX_LIMITATIONS) {
+    issues.push(`${path} must be a bounded string array`);
+    return undefined;
+  }
+  const out: string[] = [];
+  for (const item of value) {
+    const text = boundedText(item, 400);
+    if (!text) {
+      issues.push(`${path} contains invalid text`);
+      return undefined;
+    }
+    out.push(text);
+  }
+  return out;
+}
+
+function parseExplanation(
+  value: unknown,
+  observationIds: Set<string>,
+  path: string,
+  issues: string[]
+): AdviceExplanation | undefined {
+  if (!isObject(value) || !exactKeys(value, ['limitations', 'proxyMetricObservationIds', 'summary'])) {
+    issues.push(`${path} has an invalid shape`);
+    return undefined;
+  }
+  const summary = boundedText(value.summary, 1_500);
+  const proxyMetricObservationIds = idArray(
+    value.proxyMetricObservationIds,
+    MAX_REFERENCES,
+    observationIds,
+    `${path}.proxyMetricObservationIds`,
+    issues,
+    true
+  );
+  const limitations = textArray(value.limitations, `${path}.limitations`, issues);
+  if (!summary || !proxyMetricObservationIds || !limitations) {
+    if (!summary) issues.push(`${path}.summary is empty or too long`);
+    return undefined;
+  }
+  if (proxyMetricObservationIds.length > 0 && limitations.length === 0) {
+    issues.push(`${path} must state limitations for proxy metrics`);
+    return undefined;
+  }
+  return { summary, proxyMetricObservationIds, limitations };
+}
+
+function parseAction(
+  value: unknown,
+  evidenceIds: Set<string>,
+  path: string,
+  issues: string[]
+): AdviceConditionalAction | undefined {
+  if (!isObject(value) || !exactKeys(value, ['action', 'evidenceIds', 'when'], ['stopCondition'])) {
+    issues.push(`${path} has an invalid shape`);
+    return undefined;
+  }
+  const when = boundedText(value.when, 600);
+  const action = boundedText(value.action, 800);
+  const references = idArray(value.evidenceIds, MAX_REFERENCES, evidenceIds, `${path}.evidenceIds`, issues);
+  const stopCondition = value.stopCondition === undefined ? undefined : boundedText(value.stopCondition, 600);
+  if (!when || !action || !references || (value.stopCondition !== undefined && !stopCondition)) {
+    issues.push(`${path} has empty or oversized text`);
+    return undefined;
+  }
+  return stopCondition ? { when, action, evidenceIds: references, stopCondition } : { when, action, evidenceIds: references };
+}
+
+function finiteRange(value: unknown, min: number, max: number): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max;
+}
+
+function parseGuardrail(value: unknown, path: string, issues: string[]): AdviceQualityGuardrail | undefined {
+  if (!isObject(value) || !exactKeys(value, ['maximumRegression', 'minimumScore', 'rubricId'])) {
+    issues.push(`${path} has an invalid shape`);
+    return undefined;
+  }
+  if (
+    typeof value.rubricId !== 'string' ||
+    !isAdviceIdentifier(value.rubricId) ||
+    !finiteRange(value.minimumScore, 0, 1) ||
+    !finiteRange(value.maximumRegression, 0, 1)
+  ) {
+    issues.push(`${path} has invalid bounds or rubric id`);
+    return undefined;
+  }
+  return {
+    rubricId: value.rubricId,
+    minimumScore: value.minimumScore,
+    maximumRegression: value.maximumRegression,
+  };
+}
+
+function parseCriterion(
+  value: unknown,
+  observationIds: Set<string>,
+  path: string,
+  issues: string[]
+): AdviceSuccessCriterion | undefined {
+  if (
+    !isObject(value) ||
+    !exactKeys(value, [
+      'direction',
+      'metricObservationId',
+      'minimumComparableTasks',
+      'qualityGuardrail',
+      'target',
+    ])
+  ) {
+    issues.push(`${path} has an invalid shape`);
+    return undefined;
+  }
+  if (
+    typeof value.metricObservationId !== 'string' ||
+    !observationIds.has(value.metricObservationId) ||
+    (value.direction !== 'increase' && value.direction !== 'decrease' && value.direction !== 'maintain') ||
+    !Number.isInteger(value.minimumComparableTasks) ||
+    (value.minimumComparableTasks as number) < 2 ||
+    (value.minimumComparableTasks as number) > 10_000
+  ) {
+    issues.push(`${path} has an invalid metric reference, direction, or sample size`);
+    return undefined;
+  }
+  if (!isObject(value.target) || !exactKeys(value.target, ['kind', 'value'])) {
+    issues.push(`${path}.target has an invalid shape`);
+    return undefined;
+  }
+  if (
+    (value.target.kind !== 'relative-change' && value.target.kind !== 'absolute') ||
+    !finiteRange(value.target.value, 0, Number.MAX_SAFE_INTEGER)
+  ) {
+    issues.push(`${path}.target has an invalid kind or value`);
+    return undefined;
+  }
+  const guardrail = parseGuardrail(value.qualityGuardrail, `${path}.qualityGuardrail`, issues);
+  if (!guardrail) return undefined;
+  return {
+    metricObservationId: value.metricObservationId,
+    direction: value.direction,
+    target: { kind: value.target.kind, value: value.target.value },
+    minimumComparableTasks: value.minimumComparableTasks as number,
+    qualityGuardrail: guardrail,
+  };
+}
+
+function parseRecommendation(
+  value: unknown,
+  references: { observationIds: Set<string>; evidenceIds: Set<string> },
+  path: string,
+  issues: string[]
+): AdviceRecommendation | undefined {
+  if (
+    !isObject(value) ||
+    !exactKeys(value, [
+      'conditionalActions',
+      'evidenceIds',
+      'explanation',
+      'id',
+      'successCriteria',
+      'title',
+    ])
+  ) {
+    issues.push(`${path} has an invalid shape`);
+    return undefined;
+  }
+  if (typeof value.id !== 'string' || !isAdviceIdentifier(value.id)) {
+    issues.push(`${path}.id is invalid`);
+    return undefined;
+  }
+  const title = boundedText(value.title, 160);
+  const evidenceIds = idArray(
+    value.evidenceIds,
+    MAX_REFERENCES,
+    references.evidenceIds,
+    `${path}.evidenceIds`,
+    issues
+  );
+  const explanation = parseExplanation(value.explanation, references.observationIds, `${path}.explanation`, issues);
+  if (!Array.isArray(value.conditionalActions) || value.conditionalActions.length < 1 || value.conditionalActions.length > MAX_ACTIONS) {
+    issues.push(`${path}.conditionalActions must be a bounded non-empty array`);
+    return undefined;
+  }
+  if (!Array.isArray(value.successCriteria) || value.successCriteria.length < 1 || value.successCriteria.length > MAX_CRITERIA) {
+    issues.push(`${path}.successCriteria must be a bounded non-empty array`);
+    return undefined;
+  }
+  const conditionalActions = value.conditionalActions.map((item, index) =>
+    parseAction(item, references.evidenceIds, `${path}.conditionalActions[${index}]`, issues)
+  );
+  const successCriteria = value.successCriteria.map((item, index) =>
+    parseCriterion(item, references.observationIds, `${path}.successCriteria[${index}]`, issues)
+  );
+  if (!title || !evidenceIds || !explanation || conditionalActions.some((item) => !item) || successCriteria.some((item) => !item)) {
+    if (!title) issues.push(`${path}.title is empty or too long`);
+    return undefined;
+  }
+  return {
+    id: value.id,
+    title,
+    evidenceIds,
+    explanation,
+    conditionalActions: conditionalActions as AdviceConditionalAction[],
+    successCriteria: successCriteria as AdviceSuccessCriterion[],
+  };
+}
+
+/**
+ * Strict JSON-only parser. It never strips fences, repairs output, returns a
+ * partial batch, or turns malformed prose into a plausible recommendation.
+ */
+export function parseStructuredAdviceOutput(
+  raw: string,
+  knownReferences: StructuredAdviceReferences
+): StructuredAdviceParseResult {
+  const text = raw.trim();
+  if (text.length === 0) return { ok: false, code: 'empty-output', issues: ['model output was empty'] };
+  if (text.length > MAX_RAW_CHARS) {
+    return { ok: false, code: 'output-too-large', issues: ['model output exceeded the size limit'] };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    return { ok: false, code: 'invalid-json', issues: ['model output was not one strict JSON value'] };
+  }
+  if (!isObject(parsed) || !exactKeys(parsed, ['recommendations', 'schemaVersion'])) {
+    return { ok: false, code: 'invalid-schema', issues: ['top-level response shape is invalid'] };
+  }
+  if (parsed.schemaVersion !== ADVICE_CONTRACT_VERSION || !Array.isArray(parsed.recommendations)) {
+    return { ok: false, code: 'invalid-schema', issues: ['response schema version or recommendations is invalid'] };
+  }
+  if (parsed.recommendations.length > MAX_RECOMMENDATIONS) {
+    return { ok: false, code: 'invalid-schema', issues: ['too many recommendations'] };
+  }
+
+  const observationIds = new Set(knownReferences.observationIds);
+  const evidenceIds = new Set(knownReferences.evidenceIds);
+  const issues: string[] = [];
+  const recommendations = parsed.recommendations.map((item, index) =>
+    parseRecommendation(item, { observationIds, evidenceIds }, `recommendations[${index}]`, issues)
+  );
+  const recommendationIds = new Set<string>();
+  for (const recommendation of recommendations) {
+    if (!recommendation) continue;
+    if (recommendationIds.has(recommendation.id)) issues.push('recommendation ids must be unique');
+    recommendationIds.add(recommendation.id);
+  }
+  if (issues.length > 0 || recommendations.some((item) => !item)) {
+    const code: StructuredAdviceParseErrorCode = issues.some((issue) => issue.includes('unknown reference'))
+      ? 'unknown-reference'
+      : 'invalid-schema';
+    return { ok: false, code, issues };
+  }
+  return {
+    ok: true,
+    value: {
+      schemaVersion: ADVICE_CONTRACT_VERSION,
+      recommendations: recommendations as AdviceRecommendation[],
+    },
+  };
+}
diff --git a/src/adviceEffectiveness/versionedPersistence.ts b/src/adviceEffectiveness/versionedPersistence.ts
new file mode 100644
index 00000000..ac627b96
--- /dev/null
+++ b/src/adviceEffectiveness/versionedPersistence.ts
@@ -0,0 +1,723 @@
+import { isAdviceIdentifier } from './contract';
+import {
+  StoredComparablePair,
+  parseStoredComparablePair,
+  toComparableTaskPairs,
+} from './comparisonPairing';
+import {
+  AdviceComparisonResultEnvelope,
+  parseAdviceComparisonResultEnvelope,
+} from './comparisonResult';
+
+export type {
+  StoredAdviceScope,
+  StoredComparableContext,
+  StoredComparablePair,
+  StoredComplexityBand,
+  StoredConfidence,
+  StoredCoverage,
+  StoredEffort,
+  StoredMetricDirection,
+  StoredMetricUnit,
+  StoredModelFamily,
+  StoredProvider,
+  StoredQualityPass,
+  StoredTaskKind,
+} from './comparisonPairing';
+export { toComparableTaskPairs } from './comparisonPairing';
+
+/** Stable key: schema versions migrate in-place instead of changing the key. */
+export const ADVICE_LOCAL_STATE_KEY = 'ccu.adviceEffectiveness.localState';
+export const ADVICE_LOCAL_STATE_VERSION = 3 as const;
+export const MAX_PERSISTED_ADVICE_FEEDBACK = 500;
+export const MAX_PERSISTED_COMPARABLE_PAIRS = 200;
+export const MAX_PERSISTED_ADVICE_COMPARISON_RESULTS = 200;
+export const ADVICE_SNOOZE_DURATION_MS = 7 * 24 * 60 * 60 * 1_000;
+export const MAX_ADVICE_SNOOZE_DURATION_MS = 30 * 24 * 60 * 60 * 1_000;
+
+export type AdviceFeatureMode = 'disabled' | 'enabled';
+export type AdviceConsentState = 'not-granted' | 'explicit';
+export type PersistedAdviceRating = 'unrated' | 'helpful' | 'not-helpful';
+export type PersistedAdviceApplied = 'not-applied' | 'applied';
+export type AdviceFeedbackMutationKind = 'helpful' | 'not-helpful' | 'applied';
+
+/** A separate, bounded suppression record; it never changes the feedback rating. */
+export interface PersistedAdviceSuppression {
+  provider: 'claude' | 'codex' | 'optimizer';
+  surface: 'advice' | 'optimizer';
+  recommendationId: string;
+  snoozedUntilEpochMs: number;
+  updatedAtEpochMs: number;
+}
+
+export interface PersistedAdviceFeedback {
+  adviceId: string;
+  recommendationId: string;
+  rating: PersistedAdviceRating;
+  applied: PersistedAdviceApplied;
+  /** Stable intervention boundary; later rating changes never move it. */
+  appliedAtEpochMs: number | null;
+  updatedAtEpochMs: number;
+}
+
+export interface AdviceLocalState {
+  schemaVersion: typeof ADVICE_LOCAL_STATE_VERSION;
+  featureMode: AdviceFeatureMode;
+  aggregateConsent: AdviceConsentState;
+  promptSampleConsent: AdviceConsentState;
+  feedback: PersistedAdviceFeedback[];
+  suppression: PersistedAdviceSuppression[];
+  comparablePairs: StoredComparablePair[];
+  comparisonResults: AdviceComparisonResultEnvelope[];
+}
+
+export interface AdviceLocalStateStorage {
+  get<T>(key: string): T | undefined;
+  update(key: string, value: unknown): PromiseLike<void>;
+}
+
+export type AdviceLocalStateLoadResult =
+  | { ok: true; migrated: boolean; value: AdviceLocalState }
+  | { ok: false; reason: 'invalid-local-data' | 'storage-error'; value: AdviceLocalState };
+
+export type AdviceLocalStateWriteResult =
+  | { ok: true; value: AdviceLocalState }
+  | { ok: false; reason: 'invalid-local-data' | 'storage-error' };
+
+export type AdviceLocalStateMutationResult =
+  | { ok: true; value: AdviceLocalState }
+  | { ok: false; reason: 'invalid-local-data' | 'invalid-input' };
+
+const STATE_KEYS = [
+  'aggregateConsent',
+  'comparablePairs',
+  'comparisonResults',
+  'featureMode',
+  'feedback',
+  'promptSampleConsent',
+  'suppression',
+  'schemaVersion',
+] as const;
+const LEGACY_V2_STATE_KEYS = [
+  'aggregateConsent',
+  'comparablePairs',
+  'featureMode',
+  'feedback',
+  'promptSampleConsent',
+  'schemaVersion',
+] as const;
+const LEGACY_V2_COMPLETE_STATE_KEYS = [
+  'aggregateConsent',
+  'comparablePairs',
+  'comparisonResults',
+  'featureMode',
+  'feedback',
+  'promptSampleConsent',
+  'schemaVersion',
+] as const;
+const FEEDBACK_KEYS = [
+  'adviceId',
+  'applied',
+  'appliedAtEpochMs',
+  'rating',
+  'recommendationId',
+  'updatedAtEpochMs',
+] as const;
+const LEGACY_FEEDBACK_KEYS = [
+  'adviceId',
+  'applied',
+  'rating',
+  'recommendationId',
+  'updatedAtEpochMs',
+] as const;
+const SUPPRESSION_KEYS = [
+  'provider',
+  'recommendationId',
+  'surface',
+  'snoozedUntilEpochMs',
+  'updatedAtEpochMs',
+] as const;
+const LEGACY_SUPPRESSION_KEYS = [
+  'adviceId',
+  'recommendationId',
+  'snoozedUntilEpochMs',
+  'updatedAtEpochMs',
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const keys = [...expected].sort();
+  return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+
+function isEpochMs(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+function oneOf<T extends string>(value: unknown, values: readonly T[]): value is T {
+  return typeof value === 'string' && (values as readonly string[]).includes(value);
+}
+
+function parseFeedback(value: unknown): PersistedAdviceFeedback | undefined {
+  if (!isObject(value) || !hasExactKeys(value, FEEDBACK_KEYS)) return undefined;
+  if (
+    typeof value.adviceId !== 'string' ||
+    !isAdviceIdentifier(value.adviceId) ||
+    typeof value.recommendationId !== 'string' ||
+    !isAdviceIdentifier(value.recommendationId) ||
+    !oneOf(value.rating, ['unrated', 'helpful', 'not-helpful'] as const) ||
+    !oneOf(value.applied, ['not-applied', 'applied'] as const) ||
+    !(value.appliedAtEpochMs === null || isEpochMs(value.appliedAtEpochMs)) ||
+    (value.applied === 'applied' && value.appliedAtEpochMs === null) ||
+    (value.applied === 'not-applied' && value.appliedAtEpochMs !== null) ||
+    !isEpochMs(value.updatedAtEpochMs)
+  ) {
+    return undefined;
+  }
+  return {
+    adviceId: value.adviceId,
+    recommendationId: value.recommendationId,
+    rating: value.rating,
+    applied: value.applied,
+    appliedAtEpochMs: value.appliedAtEpochMs,
+    updatedAtEpochMs: value.updatedAtEpochMs,
+  };
+}
+
+function parseSuppression(value: unknown): PersistedAdviceSuppression | undefined {
+  if (!isObject(value) || !hasExactKeys(value, SUPPRESSION_KEYS)) return undefined;
+  if (
+    !oneOf(value.provider, ['claude', 'codex', 'optimizer'] as const) ||
+    !oneOf(value.surface, ['advice', 'optimizer'] as const) ||
+    (value.provider === 'optimizer' && value.surface !== 'optimizer') ||
+    (value.provider !== 'optimizer' && value.surface !== 'advice') ||
+    typeof value.recommendationId !== 'string' ||
+    !isAdviceIdentifier(value.recommendationId) ||
+    !isEpochMs(value.snoozedUntilEpochMs) ||
+    !isEpochMs(value.updatedAtEpochMs) ||
+    value.snoozedUntilEpochMs <= value.updatedAtEpochMs
+  ) return undefined;
+  return {
+    provider: value.provider,
+    surface: value.surface,
+    recommendationId: value.recommendationId,
+    snoozedUntilEpochMs: value.snoozedUntilEpochMs,
+    updatedAtEpochMs: value.updatedAtEpochMs,
+  };
+}
+
+function migrateLegacySuppression(value: unknown): PersistedAdviceSuppression | undefined {
+  if (!isObject(value) || !hasExactKeys(value, LEGACY_SUPPRESSION_KEYS)) return undefined;
+  if (
+    typeof value.adviceId !== 'string' ||
+    !isAdviceIdentifier(value.adviceId) ||
+    typeof value.recommendationId !== 'string' ||
+    !isAdviceIdentifier(value.recommendationId) ||
+    !isEpochMs(value.snoozedUntilEpochMs) ||
+    !isEpochMs(value.updatedAtEpochMs) ||
+    value.snoozedUntilEpochMs <= value.updatedAtEpochMs
+  ) return undefined;
+  const match = /^advice-(claude|codex|optimizer)(?:-|$)/.exec(value.adviceId);
+  if (!match) return undefined;
+  const provider = match[1] as 'claude' | 'codex' | 'optimizer';
+  return {
+    provider,
+    surface: provider === 'optimizer' ? 'optimizer' : 'advice',
+    recommendationId: value.recommendationId,
+    snoozedUntilEpochMs: value.snoozedUntilEpochMs,
+    updatedAtEpochMs: value.updatedAtEpochMs,
+  };
+}
+
+function parseCurrentState(value: unknown): AdviceLocalState | undefined {
+  if (!isObject(value) || !hasExactKeys(value, STATE_KEYS)) return undefined;
+  if (
+    value.schemaVersion !== ADVICE_LOCAL_STATE_VERSION ||
+    !oneOf(value.featureMode, ['disabled', 'enabled'] as const) ||
+    !oneOf(value.aggregateConsent, ['not-granted', 'explicit'] as const) ||
+    !oneOf(value.promptSampleConsent, ['not-granted', 'explicit'] as const) ||
+    (value.promptSampleConsent === 'explicit' && value.aggregateConsent !== 'explicit') ||
+    !Array.isArray(value.feedback) ||
+    value.feedback.length > MAX_PERSISTED_ADVICE_FEEDBACK ||
+    !Array.isArray(value.suppression) ||
+    value.suppression.length > MAX_PERSISTED_ADVICE_FEEDBACK ||
+    !Array.isArray(value.comparablePairs) ||
+    value.comparablePairs.length > MAX_PERSISTED_COMPARABLE_PAIRS ||
+    !Array.isArray(value.comparisonResults) ||
+    value.comparisonResults.length > MAX_PERSISTED_ADVICE_COMPARISON_RESULTS
+  ) {
+    return undefined;
+  }
+  const suppression: PersistedAdviceSuppression[] = [];
+  const suppressionTargets = new Set<string>();
+  for (const raw of value.suppression) {
+    const item = parseSuppression(raw);
+    if (!item) return undefined;
+    const target = `${item.provider}\0${item.surface}\0${item.recommendationId}`;
+    if (suppressionTargets.has(target)) return undefined;
+    suppressionTargets.add(target);
+    suppression.push(item);
+  }
+  const feedback: PersistedAdviceFeedback[] = [];
+  const feedbackTargets = new Set<string>();
+  for (const raw of value.feedback) {
+    const item = parseFeedback(raw);
+    if (!item) return undefined;
+    const target = `${item.adviceId}\0${item.recommendationId}`;
+    if (feedbackTargets.has(target)) return undefined;
+    feedbackTargets.add(target);
+    feedback.push(item);
+  }
+  const comparablePairs: StoredComparablePair[] = [];
+  const pairIds = new Set<string>();
+  for (const raw of value.comparablePairs) {
+    const item = parseStoredComparablePair(raw);
+    if (!item || pairIds.has(item.pairId)) return undefined;
+    pairIds.add(item.pairId);
+    comparablePairs.push(item);
+  }
+  const comparisonResults: AdviceComparisonResultEnvelope[] = [];
+  const comparisonIds = new Set<string>();
+  for (const raw of value.comparisonResults) {
+    const item = parseAdviceComparisonResultEnvelope(raw);
+    if (!item || comparisonIds.has(item.comparisonId)) return undefined;
+    comparisonIds.add(item.comparisonId);
+    comparisonResults.push(item);
+  }
+  return {
+    schemaVersion: ADVICE_LOCAL_STATE_VERSION,
+    featureMode: value.featureMode,
+    aggregateConsent: value.aggregateConsent,
+    promptSampleConsent: value.promptSampleConsent,
+    feedback,
+    suppression,
+    comparablePairs,
+    comparisonResults,
+  };
+}
+
+function migrateLegacyV2(value: Record<string, unknown>): AdviceLocalState | undefined {
+  const oldRoot = hasExactKeys(value, LEGACY_V2_STATE_KEYS);
+  const completeRoot = hasExactKeys(value, LEGACY_V2_COMPLETE_STATE_KEYS);
+  if (
+    (!oldRoot && !completeRoot) ||
+    value.schemaVersion !== 2 ||
+    !Array.isArray(value.feedback) ||
+    (oldRoot && (!Array.isArray(value.comparablePairs) || value.comparablePairs.length !== 0))
+  ) {
+    return undefined;
+  }
+  const feedback: PersistedAdviceFeedback[] = [];
+  for (const raw of value.feedback) {
+    if (!isObject(raw) || !hasExactKeys(raw, LEGACY_FEEDBACK_KEYS)) return undefined;
+    const parsed = parseFeedback({
+      ...raw,
+      appliedAtEpochMs: raw.applied === 'applied' ? raw.updatedAtEpochMs : null,
+    });
+    if (!parsed) return undefined;
+    feedback.push(parsed);
+  }
+  return parseCurrentState({
+    ...value,
+    schemaVersion: ADVICE_LOCAL_STATE_VERSION,
+    feedback,
+    suppression: [],
+    comparisonResults: completeRoot ? value.comparisonResults : [],
+  });
+}
+
+function migrateLegacyV3(value: Record<string, unknown>): AdviceLocalState | undefined {
+  if (!hasExactKeys(value, STATE_KEYS) || value.schemaVersion !== ADVICE_LOCAL_STATE_VERSION) {
+    return undefined;
+  }
+  if (!Array.isArray(value.suppression) || value.suppression.length > MAX_PERSISTED_ADVICE_FEEDBACK) {
+    return undefined;
+  }
+  const suppression: PersistedAdviceSuppression[] = [];
+  const targets = new Set<string>();
+  for (const raw of value.suppression) {
+    // Mixed v3 writes can contain both the new stable shape and an older
+    // adviceId record; preserve only records whose provider scope is explicit.
+    const migrated = parseSuppression(raw) ?? migrateLegacySuppression(raw);
+    if (!migrated) continue;
+    const target = `${migrated.provider}\0${migrated.surface}\0${migrated.recommendationId}`;
+    if (targets.has(target)) continue;
+    targets.add(target);
+    suppression.push(migrated);
+  }
+  return parseCurrentState({ ...value, suppression });
+}
+
+interface LegacyFeedbackV1 {
+  adviceId: string;
+  recommendationId: string;
+  rating: PersistedAdviceRating;
+  applied: boolean;
+  updatedAtEpochMs: number;
+}
+
+function migrateV1(value: Record<string, unknown>): AdviceLocalState | undefined {
+  if (!hasExactKeys(value, ['enabled', 'feedback', 'includePromptSamples', 'schemaVersion'])) {
+    return undefined;
+  }
+  if (
+    value.schemaVersion !== 1 ||
+    typeof value.enabled !== 'boolean' ||
+    typeof value.includePromptSamples !== 'boolean' ||
+    !Array.isArray(value.feedback) ||
+    value.feedback.length > MAX_PERSISTED_ADVICE_FEEDBACK
+  ) {
+    return undefined;
+  }
+  const feedback: PersistedAdviceFeedback[] = [];
+  const targets = new Set<string>();
+  for (const raw of value.feedback) {
+    if (
+      !isObject(raw) ||
+      !hasExactKeys(raw, ['adviceId', 'applied', 'rating', 'recommendationId', 'updatedAtEpochMs']) ||
+      typeof raw.adviceId !== 'string' ||
+      typeof raw.recommendationId !== 'string' ||
+      !isAdviceIdentifier(raw.adviceId) ||
+      !isAdviceIdentifier(raw.recommendationId) ||
+      !oneOf(raw.rating, ['unrated', 'helpful', 'not-helpful'] as const) ||
+      typeof raw.applied !== 'boolean' ||
+      !isEpochMs(raw.updatedAtEpochMs)
+    ) {
+      return undefined;
+    }
+    const legacy: LegacyFeedbackV1 = {
+      adviceId: raw.adviceId,
+      recommendationId: raw.recommendationId,
+      rating: raw.rating,
+      applied: raw.applied,
+      updatedAtEpochMs: raw.updatedAtEpochMs,
+    };
+    const target = `${legacy.adviceId}\0${legacy.recommendationId}`;
+    if (targets.has(target)) return undefined;
+    targets.add(target);
+    feedback.push({
+      adviceId: legacy.adviceId,
+      recommendationId: legacy.recommendationId,
+      rating: legacy.rating,
+      applied: legacy.applied ? 'applied' : 'not-applied',
+      appliedAtEpochMs: legacy.applied ? legacy.updatedAtEpochMs : null,
+      updatedAtEpochMs: legacy.updatedAtEpochMs,
+    });
+  }
+  // Old booleans did not encode the new separate consent, so both close.
+  return {
+    schemaVersion: ADVICE_LOCAL_STATE_VERSION,
+    featureMode: 'disabled',
+    aggregateConsent: 'not-granted',
+    promptSampleConsent: 'not-granted',
+    feedback,
+    suppression: [],
+    comparablePairs: [],
+    comparisonResults: [],
+  };
+}
+
+export function createClosedAdviceLocalState(): AdviceLocalState {
+  return {
+    schemaVersion: ADVICE_LOCAL_STATE_VERSION,
+    featureMode: 'disabled',
+    aggregateConsent: 'not-granted',
+    promptSampleConsent: 'not-granted',
+    feedback: [],
+    suppression: [],
+    comparablePairs: [],
+    comparisonResults: [],
+  };
+}
+
+/** User-visible privacy reset: keep the enabled surface, close consent, and erase its local ledger. */
+export function createClearedAdviceLocalState(): AdviceLocalState {
+  return {
+    ...createClosedAdviceLocalState(),
+    featureMode: 'enabled',
+  };
+}
+
+/** Load/migrate without ever overwriting unknown or corrupt future data. */
+export async function loadAndMigrateAdviceLocalState(
+  storage: AdviceLocalStateStorage,
+): Promise<AdviceLocalStateLoadResult> {
+  const closed = createClosedAdviceLocalState();
+  let raw: unknown;
+  try {
+    raw = storage.get<unknown>(ADVICE_LOCAL_STATE_KEY);
+  } catch {
+    return { ok: false, reason: 'storage-error', value: closed };
+  }
+  if (raw === undefined) return { ok: true, migrated: false, value: closed };
+  const current = parseCurrentState(raw);
+  if (current) return { ok: true, migrated: false, value: current };
+  if (!isObject(raw)) {
+    return { ok: false, reason: 'invalid-local-data', value: closed };
+  }
+  const migrated = raw.schemaVersion === ADVICE_LOCAL_STATE_VERSION
+    ? migrateLegacyV3(raw)
+    : raw.schemaVersion === 2
+    ? migrateLegacyV2(raw)
+    : raw.schemaVersion === 1
+      ? migrateV1(raw)
+      : undefined;
+  if (!migrated) return { ok: false, reason: 'invalid-local-data', value: closed };
+  try {
+    await storage.update(ADVICE_LOCAL_STATE_KEY, migrated);
+  } catch {
+    return { ok: false, reason: 'storage-error', value: closed };
+  }
+  return { ok: true, migrated: true, value: migrated };
+}
+
+export async function saveAdviceLocalState(
+  storage: AdviceLocalStateStorage,
+  value: unknown,
+): Promise<AdviceLocalStateWriteResult> {
+  const parsed = parseCurrentState(value);
+  if (!parsed) return { ok: false, reason: 'invalid-local-data' };
+  try {
+    await storage.update(ADVICE_LOCAL_STATE_KEY, parsed);
+  } catch {
+    return { ok: false, reason: 'storage-error' };
+  }
+  return { ok: true, value: parsed };
+}
+
+export function upsertAdviceLocalFeedback(
+  state: AdviceLocalState,
+  input: {
+    adviceId: string;
+    recommendationId: string;
+    kind: AdviceFeedbackMutationKind;
+    updatedAtEpochMs: number;
+  },
+): AdviceLocalStateMutationResult {
+  const current = parseCurrentState(state);
+  if (!current) return { ok: false, reason: 'invalid-local-data' };
+  if (
+    !isObject(input) ||
+    !hasExactKeys(input, ['adviceId', 'kind', 'recommendationId', 'updatedAtEpochMs']) ||
+    !isAdviceIdentifier(input.adviceId) ||
+    !isAdviceIdentifier(input.recommendationId) ||
+    !oneOf(input.kind, ['helpful', 'not-helpful', 'applied'] as const) ||
+    !isEpochMs(input.updatedAtEpochMs)
+  ) {
+    return { ok: false, reason: 'invalid-input' };
+  }
+  const existing = current.feedback.find(
+    (item) => item.adviceId === input.adviceId && item.recommendationId === input.recommendationId,
+  );
+  let rating = existing?.rating ?? 'unrated';
+  let applied = existing?.applied ?? 'not-applied';
+  let appliedAtEpochMs = existing?.appliedAtEpochMs ?? null;
+  if (input.kind === 'helpful') {
+    rating = rating === 'helpful' ? 'unrated' : 'helpful';
+  } else if (input.kind === 'not-helpful') {
+    rating = rating === 'not-helpful' ? 'unrated' : 'not-helpful';
+  } else if (applied === 'applied') {
+    applied = 'not-applied';
+    appliedAtEpochMs = null;
+  } else {
+    applied = 'applied';
+    appliedAtEpochMs = input.updatedAtEpochMs;
+  }
+  const next: PersistedAdviceFeedback = {
+    adviceId: input.adviceId,
+    recommendationId: input.recommendationId,
+    rating,
+    applied,
+    appliedAtEpochMs,
+    updatedAtEpochMs: input.updatedAtEpochMs,
+  };
+  const withoutTarget = current.feedback.filter(
+    (item) => item.adviceId !== input.adviceId || item.recommendationId !== input.recommendationId,
+  );
+  const feedback = (rating === 'unrated' && applied === 'not-applied'
+    ? withoutTarget
+    : withoutTarget.concat(next))
+    .slice(-MAX_PERSISTED_ADVICE_FEEDBACK);
+  return { ok: true, value: { ...current, feedback } };
+}
+
+export function snoozeAdviceRecommendation(
+  state: AdviceLocalState,
+  input: {
+    provider: 'claude' | 'codex' | 'optimizer';
+    surface: 'advice' | 'optimizer';
+    recommendationId: string;
+    snoozedUntilEpochMs: number;
+    updatedAtEpochMs: number;
+  },
+): AdviceLocalStateMutationResult {
+  const current = parseCurrentState(state);
+  if (!current) return { ok: false, reason: 'invalid-local-data' };
+  if (
+    !isObject(input) ||
+    !hasExactKeys(input, [
+      'provider',
+      'recommendationId',
+      'surface',
+      'snoozedUntilEpochMs',
+      'updatedAtEpochMs',
+    ]) ||
+    !oneOf(input.provider, ['claude', 'codex', 'optimizer'] as const) ||
+    !oneOf(input.surface, ['advice', 'optimizer'] as const) ||
+    (input.provider === 'optimizer' && input.surface !== 'optimizer') ||
+    (input.provider !== 'optimizer' && input.surface !== 'advice') ||
+    !isAdviceIdentifier(input.recommendationId) ||
+    !isEpochMs(input.snoozedUntilEpochMs) ||
+    !isEpochMs(input.updatedAtEpochMs) ||
+    input.snoozedUntilEpochMs <= input.updatedAtEpochMs ||
+    input.snoozedUntilEpochMs - input.updatedAtEpochMs > MAX_ADVICE_SNOOZE_DURATION_MS
+  ) return { ok: false, reason: 'invalid-input' };
+  const suppression = current.suppression
+    .filter(
+      (item) =>
+        item.snoozedUntilEpochMs > input.updatedAtEpochMs &&
+        (item.provider !== input.provider ||
+          item.surface !== input.surface ||
+          item.recommendationId !== input.recommendationId),
+    )
+    .concat({
+      provider: input.provider,
+      surface: input.surface,
+      recommendationId: input.recommendationId,
+      snoozedUntilEpochMs: input.snoozedUntilEpochMs,
+      updatedAtEpochMs: input.updatedAtEpochMs,
+    })
+    .slice(-MAX_PERSISTED_ADVICE_FEEDBACK);
+  return { ok: true, value: { ...current, suppression } };
+}
+
+export function resumeAdviceRecommendation(
+  state: AdviceLocalState,
+  input: {
+    provider: 'claude' | 'codex' | 'optimizer';
+    surface: 'advice' | 'optimizer';
+    recommendationId: string;
+  },
+): AdviceLocalStateMutationResult {
+  const current = parseCurrentState(state);
+  if (!current) return { ok: false, reason: 'invalid-local-data' };
+  if (
+    !isObject(input) ||
+    !hasExactKeys(input, ['provider', 'recommendationId', 'surface']) ||
+    !oneOf(input.provider, ['claude', 'codex', 'optimizer'] as const) ||
+    !oneOf(input.surface, ['advice', 'optimizer'] as const) ||
+    (input.provider === 'optimizer' && input.surface !== 'optimizer') ||
+    (input.provider !== 'optimizer' && input.surface !== 'advice') ||
+    !isAdviceIdentifier(input.recommendationId)
+  ) return { ok: false, reason: 'invalid-input' };
+  return {
+    ok: true,
+    value: {
+      ...current,
+      suppression: current.suppression.filter(
+        (item) =>
+        item.provider !== input.provider ||
+        item.surface !== input.surface ||
+        item.recommendationId !== input.recommendationId,
+      ),
+    },
+  };
+}
+
+export function adviceRecommendationSnoozedUntil(
+  state: AdviceLocalState,
+  input: {
+    provider: 'claude' | 'codex' | 'optimizer';
+    surface: 'advice' | 'optimizer';
+    recommendationId: string;
+    nowEpochMs: number;
+  },
+): number | null {
+  if (!parseCurrentState(state) || !isEpochMs(input.nowEpochMs)) return null;
+  const record = state.suppression.find(
+    (item) =>
+      item.provider === input.provider &&
+      item.surface === input.surface &&
+      item.recommendationId === input.recommendationId &&
+      item.snoozedUntilEpochMs > input.nowEpochMs,
+  );
+  return record?.snoozedUntilEpochMs ?? null;
+}
+
+export function appendStoredComparablePair(
+  state: AdviceLocalState,
+  input: unknown,
+): AdviceLocalStateMutationResult {
+  const current = parseCurrentState(state);
+  if (!current) return { ok: false, reason: 'invalid-local-data' };
+  const pair = parseStoredComparablePair(input);
+  if (!pair || current.comparablePairs.some((item) => item.pairId === pair.pairId)) {
+    return { ok: false, reason: 'invalid-input' };
+  }
+  return {
+    ok: true,
+    value: {
+      ...current,
+      comparablePairs: current.comparablePairs
+        .concat(pair)
+        .slice(-MAX_PERSISTED_COMPARABLE_PAIRS),
+    },
+  };
+}
+
+export function appendAdviceComparisonResult(
+  state: AdviceLocalState,
+  input: unknown,
+): AdviceLocalStateMutationResult {
+  const current = parseCurrentState(state);
+  if (!current) return { ok: false, reason: 'invalid-local-data' };
+  const result = parseAdviceComparisonResultEnvelope(input);
+  if (
+    !result ||
+    current.comparisonResults.some((item) => item.comparisonId === result.comparisonId)
+  ) {
+    return { ok: false, reason: 'invalid-input' };
+  }
+  return {
+    ok: true,
+    value: {
+      ...current,
+      comparisonResults: current.comparisonResults
+        .concat(result)
+        .slice(-MAX_PERSISTED_ADVICE_COMPARISON_RESULTS),
+    },
+  };
+}
+
+export interface AdviceRecommendationLineage {
+  provider: 'claude' | 'codex';
+  recommendationId: string;
+}
+
+/**
+ * Select a stable recommendation lineage across advice instances. adviceId is
+ * deliberately retained on every pair as an audit field, but is not part of
+ * lineage identity because advice instances rotate with their observation day.
+ * The downstream comparator remains responsible for rejecting mixed task,
+ * model, effort, metric-version, rubric, or primary-metric cohorts.
+ */
+export function selectStoredComparablePairLineage(
+  pairs: readonly StoredComparablePair[],
+  lineage: AdviceRecommendationLineage,
+): StoredComparablePair[] {
+  if (
+    (lineage.provider !== 'claude' && lineage.provider !== 'codex') ||
+    !isAdviceIdentifier(lineage.recommendationId)
+  ) {
+    return [];
+  }
+  return pairs.filter(
+    (pair) =>
+      pair.context.provider === lineage.provider &&
+      pair.recommendationId === lineage.recommendationId,
+  );
+}
diff --git a/src/advisor.ts b/src/advisor.ts
index 4a6aab0e..6868c4d1 100644
--- a/src/advisor.ts
+++ b/src/advisor.ts
@@ -1,76 +1,17 @@
-// Optional "usage advice" feature: sends a usage summary (and, optionally, a
-// sample of the developer's own prompts) to a model and returns advice on how
-// to use Claude Code more effectively.
-//
-// Transport (v2.1 Phase 9): three backends behind one entry point —
-//   1. 'subscription' — reuse Claude Code's own OAuth session (the same token
-//      the quota indicator reads) to call Anthropic's Messages API with a cheap
-//      model (haiku) — zero API key, works out of the box. Verified 2026-06-13:
-//      Bearer <oauth> + `anthropic-beta: oauth-2025-04-20` → 200.
-//   2. 'api' + apiFormat 'anthropic' (the default for a configured key) —
-//      x-api-key against /v1/messages.
-//   3. 'api' + apiFormat 'openai' — the OpenAI chat-completions shape
-//      (DeepSeek etc.), kept for compatibility.
-// Anthropic is the default shape across the extension; OpenAI is opt-in.
+// Shared AI helpers for the two explicit user-triggered workflows. Production
+// can send only an already-previewed PreparedAiInvocation through the user's
+// configured BYOK endpoint. Anthropic Messages and OpenAI-compatible chat are
+// wire formats; neither implies subscription/OAuth credential reuse.
 
 import { HttpResponse, requestViaCurl, requestViaFetch } from './httpClient';
+import {
+  PreparedAiInvocation,
+  PreparedAiTransportRequest,
+  sendPreparedAiInvocation,
+} from './adviceEffectiveness/preparedRequest';
 
-export type AdviceBackend = 'subscription' | 'api';
 export type AdviceFormat = 'anthropic' | 'openai';
 
-export interface AdviceOptions {
-  // Transport selection. Defaults (when omitted) keep the pre-2.1 behaviour:
-  // backend 'api' + format 'openai'.
-  backend?: AdviceBackend;
-  apiFormat?: AdviceFormat;
-  // backend 'api':
-  apiKey: string;
-  apiUrl: string;
-  model: string;
-  // backend 'subscription': the cheap model to spend a little quota on, plus a
-  // provider for a valid OAuth access token (ClaudeApiClient.getAccessToken).
-  subscriptionModel?: string;
-  getSubscriptionToken?: () => Promise<string | null>;
-  // The usage digest sent as the user turn (built by adviceSummary.ts).
-  summary: string;
-  // Localised name of the user's UI language, e.g. "简体中文 (Simplified Chinese)".
-  language: string;
-  // '', 'high' or 'max' — passed as reasoning_effort for OpenAI-format models.
-  reasoningEffort?: string;
-  // Free-text background about the user/project; when set, the reply ends with
-  // a "Personalised for this project" section calibrated against it.
-  userContext?: string;
-  // Abort the request after this long (reasoning models can take minutes).
-  timeoutMs?: number;
-}
-
-const DEFAULT_TIMEOUT_MS = 120_000;
-const ADVICE_MAX_TOKENS = 16_000;
-
-function buildSystemPrompt(language: string, userContext?: string): string {
-  let prompt =
-    'You are a coaching advisor that helps a developer use the Claude Code AI ' +
-    'coding agent more effectively. You are given a breakdown of their usage and ' +
-    'a sample of their actual prompts. Your PRIMARY goal: advise how to write ' +
-    'clearer, more complete and more precise instructions so tasks are completed ' +
-    'correctly and efficiently — point at concrete weaknesses in the sample ' +
-    'prompts and show better rewrites. SECONDARY goal: where it does not hurt ' +
-    'clarity, suggest ways to reduce token consumption. Be concrete and ' +
-    'actionable, use short sections and bullet points. ';
-  const ctx = (userContext || '').trim();
-  if (ctx !== '') {
-    prompt +=
-      'The user provided this background about themself and the project: ' +
-      `"${ctx.slice(0, 1000)}". End your reply with a final section titled ` +
-      '"Personalised for this project" that calibrates the advice against this ' +
-      'background instead of generic best practice. ';
-  }
-  prompt +=
-    `IMPORTANT: write your entire reply in ${language}, regardless of the ` +
-    'language(s) used in the sample prompts.';
-  return prompt;
-}
-
 /** Normalise an OpenAI-compatible chat endpoint URL. */
 function normalizeOpenAiUrl(url: string): string {
   let u = (url || '').trim().replace(/\/+$/, '');
@@ -99,10 +40,11 @@ function normalizeAnthropicUrl(url: string): string {
 async function send(
   url: string,
   headers: Record<string, string>,
-  body: string,
-  timeoutMs: number
+  body: string | Uint8Array,
+  timeoutMs: number,
+  signal?: AbortSignal,
 ): Promise<HttpResponse> {
-  const reqOpts = { method: 'POST', headers, body };
+  const reqOpts = { method: 'POST', headers, body, ...(signal ? { signal } : {}) };
   const curl = (): Promise<HttpResponse> =>
     requestViaCurl(url, { ...reqOpts, timeoutSec: Math.ceil(timeoutMs / 1000) });
   try {
@@ -114,133 +56,92 @@ async function send(
     }
     return r;
   } catch {
+    if (signal?.aborted) throw new Error('Request cancelled');
     try {
       return await requestViaFetch(url, { ...reqOpts, timeoutMs });
     } catch {
+      if (signal?.aborted) throw new Error('Request cancelled');
       return curl();
     }
   }
 }
 
-/**
- * Send one system+user turn to whichever backend is configured and return the
- * assistant text. Shared by the advice feature and the Usage Optimizer.
- */
-export async function callModel(
-  systemPrompt: string,
-  userContent: string,
-  options: AdviceOptions
-): Promise<string> {
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const backend: AdviceBackend = options.backend ?? 'api';
-  const format: AdviceFormat = options.apiFormat ?? 'openai';
-
-  // --- Anthropic Messages shape (subscription, or api+anthropic) ---
-  if (backend === 'subscription' || format === 'anthropic') {
-    let headers: Record<string, string>;
-    let model: string;
-    let url = normalizeAnthropicUrl(options.apiUrl);
-    if (backend === 'subscription') {
-      const token = options.getSubscriptionToken ? await options.getSubscriptionToken() : null;
-      if (!token) {
-        throw new Error(
-          'No Claude subscription session found — sign in to Claude Code, or configure an API key.'
-        );
-      }
-      url = 'https://api.anthropic.com/v1/messages';
-      model = options.subscriptionModel || 'claude-haiku-4-5';
-      headers = {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-        'anthropic-version': '2023-06-01',
-        'anthropic-beta': 'oauth-2025-04-20',
-      };
-    } else {
-      model = options.model;
-      headers = {
-        'Content-Type': 'application/json',
-        'x-api-key': options.apiKey,
-        'anthropic-version': '2023-06-01',
-      };
-    }
-    const body = JSON.stringify({
-      model,
-      max_tokens: ADVICE_MAX_TOKENS,
-      system: systemPrompt,
-      messages: [{ role: 'user', content: userContent }],
-    });
-    const response = await send(url, headers, body, timeoutMs);
-    if (response.status < 200 || response.status >= 300) {
-      throw new Error(`API ${response.status}: ${response.body.slice(0, 300)}`);
-    }
-    let data: { content?: { type?: string; text?: string }[] };
-    try {
-      data = JSON.parse(response.body);
-    } catch {
-      throw new Error(`The API returned a non-JSON response: ${response.body.slice(0, 200)}`);
-    }
-    const text = (data.content || [])
-      .filter((b) => b.type === 'text' && typeof b.text === 'string')
-      .map((b) => b.text as string)
-      .join('');
-    if (!text.trim()) {
-      throw new Error('The model returned an empty response.');
-    }
-    return text;
-  }
-
-  // --- OpenAI chat-completions shape (api + openai) ---
-  const body: Record<string, unknown> = {
-    model: options.model,
-    stream: false,
-    messages: [
-      { role: 'system', content: systemPrompt },
-      { role: 'user', content: userContent },
-    ],
-  };
-  if (options.reasoningEffort && options.reasoningEffort.trim() !== '') {
-    body.reasoning_effort = options.reasoningEffort.trim();
-    body.thinking = { type: 'enabled' };
-  }
-  const url = normalizeOpenAiUrl(options.apiUrl);
-  const headers = {
-    'Content-Type': 'application/json',
-    Authorization: `Bearer ${options.apiKey}`,
-  };
-  const response = await send(url, headers, JSON.stringify(body), timeoutMs);
+function parsePreparedModelResponse(
+  prepared: PreparedAiInvocation,
+  response: HttpResponse,
+): string {
   if (response.status < 200 || response.status >= 300) {
-    const hint =
-      response.status === 404
-        ? ' (check advice.apiUrl — for DeepSeek it is https://api.deepseek.com/chat/completions)'
-        : '';
+    const hint = prepared.apiFormat === 'openai' && response.status === 404
+      ? ' (check advice.apiUrl — for DeepSeek it is https://api.deepseek.com/chat/completions)'
+      : '';
     throw new Error(`API ${response.status}${hint}: ${response.body.slice(0, 300)}`);
   }
-  let data: { choices?: { message?: { content?: string } }[] };
+  let data: unknown;
   try {
     data = JSON.parse(response.body);
   } catch {
     throw new Error(`The API returned a non-JSON response: ${response.body.slice(0, 200)}`);
   }
-  const content = data.choices?.[0]?.message?.content;
-  if (!content || content.trim() === '') {
-    throw new Error('The model returned an empty response.');
+  let text = '';
+  if (prepared.apiFormat === 'anthropic') {
+    const blocks = (data as { content?: { type?: string; text?: string }[] }).content;
+    text = (blocks ?? [])
+      .filter((block) => block.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text as string)
+      .join('');
+  } else {
+    text = (data as { choices?: { message?: { content?: string } }[] })
+      .choices?.[0]?.message?.content ?? '';
   }
-  return content;
+  if (!text.trim()) throw new Error('The model returned an empty response.');
+  return text;
 }
 
 /**
- * Request usage advice. Returns the advice text (markdown).
+ * Production transport for an already-previewed invocation. The full wire
+ * body is the original canonical byte object on every fetch retry/curl
+ * fallback; this function never calls JSON.stringify.
  */
-export async function getUsageAdvice(options: AdviceOptions): Promise<string> {
-  const systemPrompt = buildSystemPrompt(options.language || 'English', options.userContext);
-  return callModel(systemPrompt, options.summary, options);
+export async function sendPreparedModelRequest(
+  prepared: PreparedAiInvocation,
+  apiKey: string,
+  options: {
+    expectedSourceRevision?: string;
+    expectedConsentGeneration?: number;
+    signal?: AbortSignal;
+    transport?: (request: PreparedAiTransportRequest) => Promise<HttpResponse>;
+  } = {},
+): Promise<string> {
+  const response = await sendPreparedAiInvocation(
+    prepared,
+    {
+      backend: 'api',
+      apiKey,
+      ...(options.expectedSourceRevision !== undefined
+        ? { expectedSourceRevision: options.expectedSourceRevision }
+        : {}),
+      ...(options.expectedConsentGeneration !== undefined
+        ? { expectedConsentGeneration: options.expectedConsentGeneration }
+        : {}),
+      ...(options.signal ? { signal: options.signal } : {}),
+    },
+    options.transport ?? ((request) => send(
+      request.endpoint,
+      request.headers,
+      request.canonicalBytes,
+      request.timeoutMs,
+      request.signal,
+    )),
+  );
+  return parsePreparedModelResponse(prepared, response);
 }
 
 // === Usage Optimizer (Phase 9c) ===
 // The optimizer turns a rough pasted request into one tight, paste-ready prompt
 // plus a settings recommendation. The system prompt and the reply parser are
 // pure functions here (no VS Code dependency) so they can be unit-tested; the
-// VS Code glue (consent modal, config, webview round-trip) lives in extension.ts.
+// VS Code glue (exact preview, explicit send, config, webview round-trip) lives
+// in extension.ts and webview.ts.
 
 export interface OptimizerLenses {
   resolve: boolean; // flag ambiguous references
diff --git a/src/backgroundWorkState.ts b/src/backgroundWorkState.ts
new file mode 100644
index 00000000..f0923173
--- /dev/null
+++ b/src/backgroundWorkState.ts
@@ -0,0 +1,466 @@
+export const BACKGROUND_WORK_STATE_SCHEMA_VERSION = 1 as const;
+
+export const BACKGROUND_WORK_STATUSES = [
+  'eligible',
+  'running',
+  'cooldown',
+  'paused',
+  'complete',
+] as const;
+
+export const BACKGROUND_WORK_REASONS = [
+  'first-index',
+  'parser-migration',
+  'period-migration',
+  'hourly-history',
+  'history-backfill',
+  'rule-migration',
+  'resume',
+] as const;
+
+export const BACKGROUND_WORK_PAUSED_REASONS = [
+  'failure-backoff',
+  'no-progress',
+  'user',
+  'corrupt-state',
+] as const;
+
+export const BACKGROUND_WORK_TRIGGERS = ['automatic', 'manual'] as const;
+
+export type BackgroundWorkStatus = typeof BACKGROUND_WORK_STATUSES[number];
+export type BackgroundWorkReason = typeof BACKGROUND_WORK_REASONS[number];
+export type BackgroundWorkPausedReason = typeof BACKGROUND_WORK_PAUSED_REASONS[number];
+export type BackgroundWorkTrigger = typeof BACKGROUND_WORK_TRIGGERS[number];
+
+/** A monotonic, aggregate-only watermark. It is not a scanner cursor: the
+ * provider index remains responsible for exact resume positions. */
+export interface BackgroundWorkProgress {
+  completedUnits: number;
+  totalUnits: number;
+  completedBytes: number;
+  totalBytes: number;
+}
+
+export interface BackgroundWorkState {
+  schemaVersion: typeof BACKGROUND_WORK_STATE_SCHEMA_VERSION;
+  measurementVersion: number;
+  /** Persisted producer generation; prevents reusing completion from an old index. */
+  indexGeneration: number | null;
+  status: BackgroundWorkStatus;
+  reason: BackgroundWorkReason;
+  progress: BackgroundWorkProgress;
+  failStreak: number;
+  nextEligibleAt: number | null;
+  pausedReason: BackgroundWorkPausedReason | null;
+  updatedAt: number;
+}
+
+export interface BackgroundWorkBackoffPolicy {
+  failureBaseMs: number;
+  failureMaxMs: number;
+  noProgressCooldownMs: number;
+}
+
+export const DEFAULT_BACKGROUND_WORK_BACKOFF_POLICY: Readonly<BackgroundWorkBackoffPolicy> =
+  Object.freeze({
+    failureBaseMs: 60_000,
+    failureMaxMs: 3_600_000,
+    noProgressCooldownMs: 300_000,
+  });
+
+export interface CreateBackgroundWorkStateOptions {
+  measurementVersion: number;
+  reason: BackgroundWorkReason;
+  now: number;
+  progress?: BackgroundWorkProgress;
+  indexGeneration?: number | null;
+}
+
+export type BackgroundWorkRestoreDisposition =
+  | 'new'
+  | 'valid'
+  | 'measurement-changed'
+  | 'generation-changed'
+  | 'corrupt';
+
+export interface BackgroundWorkRestoreResult {
+  disposition: BackgroundWorkRestoreDisposition;
+  state: BackgroundWorkState;
+}
+
+export interface BackgroundWorkStartOptions {
+  trigger: BackgroundWorkTrigger;
+  now: number;
+  reason?: BackgroundWorkReason;
+}
+
+export interface BackgroundWorkStartResult {
+  started: boolean;
+  state: BackgroundWorkState;
+}
+
+const STATE_FIELDS = [
+  'schemaVersion',
+  'measurementVersion',
+  'indexGeneration',
+  'status',
+  'reason',
+  'progress',
+  'failStreak',
+  'nextEligibleAt',
+  'pausedReason',
+  'updatedAt',
+] as const;
+
+const PROGRESS_FIELDS = [
+  'completedUnits',
+  'totalUnits',
+  'completedBytes',
+  'totalBytes',
+] as const;
+
+const statusSet = new Set<unknown>(BACKGROUND_WORK_STATUSES);
+const reasonSet = new Set<unknown>(BACKGROUND_WORK_REASONS);
+const pausedReasonSet = new Set<unknown>(BACKGROUND_WORK_PAUSED_REASONS);
+const triggerSet = new Set<unknown>(BACKGROUND_WORK_TRIGGERS);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactFields(value: Record<string, unknown>, fields: readonly string[]): boolean {
+  const keys = Object.keys(value);
+  return keys.length === fields.length && fields.every((field) =>
+    Object.prototype.hasOwnProperty.call(value, field));
+}
+
+function isSafeNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isIndexGeneration(value: unknown): value is number | null {
+  return value === null || (isSafeNonNegativeInteger(value) && value > 0);
+}
+
+function assertSafeNonNegativeInteger(value: number, field: string): void {
+  if (!isSafeNonNegativeInteger(value)) {
+    throw new RangeError(`${field} must be a non-negative safe integer`);
+  }
+}
+
+function assertReason(reason: BackgroundWorkReason): void {
+  if (!reasonSet.has(reason)) throw new TypeError('reason must be a fixed BackgroundWorkReason');
+}
+
+function assertTrigger(trigger: BackgroundWorkTrigger): void {
+  if (!triggerSet.has(trigger)) throw new TypeError('trigger must be automatic or manual');
+}
+
+function isProgress(value: unknown): value is BackgroundWorkProgress {
+  if (!isRecord(value) || !hasExactFields(value, PROGRESS_FIELDS)) return false;
+  if (!isSafeNonNegativeInteger(value.completedUnits) ||
+      !isSafeNonNegativeInteger(value.totalUnits) ||
+      !isSafeNonNegativeInteger(value.completedBytes) ||
+      !isSafeNonNegativeInteger(value.totalBytes)) {
+    return false;
+  }
+  return value.completedUnits <= value.totalUnits && value.completedBytes <= value.totalBytes;
+}
+
+function cloneProgress(progress: BackgroundWorkProgress): BackgroundWorkProgress {
+  if (!isProgress(progress)) throw new TypeError('progress must contain fixed non-negative numeric fields');
+  return {
+    completedUnits: progress.completedUnits,
+    totalUnits: progress.totalUnits,
+    completedBytes: progress.completedBytes,
+    totalBytes: progress.totalBytes,
+  };
+}
+
+function emptyProgress(): BackgroundWorkProgress {
+  return {
+    completedUnits: 0,
+    totalUnits: 0,
+    completedBytes: 0,
+    totalBytes: 0,
+  };
+}
+
+function validStatusFields(value: Record<string, unknown>): boolean {
+  switch (value.status) {
+    case 'eligible':
+      return isSafeNonNegativeInteger(value.nextEligibleAt) && value.pausedReason === null;
+    case 'running':
+    case 'complete':
+      return value.nextEligibleAt === null && value.pausedReason === null;
+    case 'cooldown':
+      return isSafeNonNegativeInteger(value.nextEligibleAt) &&
+        (value.pausedReason === 'failure-backoff' || value.pausedReason === 'no-progress');
+    case 'paused':
+      return value.nextEligibleAt === null &&
+        (value.pausedReason === 'user' || value.pausedReason === 'corrupt-state');
+    default:
+      return false;
+  }
+}
+
+export function isBackgroundWorkState(value: unknown): value is BackgroundWorkState {
+  if (!isRecord(value) || !hasExactFields(value, STATE_FIELDS)) return false;
+  return value.schemaVersion === BACKGROUND_WORK_STATE_SCHEMA_VERSION &&
+    isSafeNonNegativeInteger(value.measurementVersion) && value.measurementVersion > 0 &&
+    isIndexGeneration(value.indexGeneration) &&
+    statusSet.has(value.status) &&
+    reasonSet.has(value.reason) &&
+    isProgress(value.progress) &&
+    isSafeNonNegativeInteger(value.failStreak) &&
+    (value.nextEligibleAt === null || isSafeNonNegativeInteger(value.nextEligibleAt)) &&
+    (value.pausedReason === null || pausedReasonSet.has(value.pausedReason)) &&
+    isSafeNonNegativeInteger(value.updatedAt) &&
+    validStatusFields(value);
+}
+
+function cloneState(value: BackgroundWorkState): BackgroundWorkState {
+  return {
+    schemaVersion: BACKGROUND_WORK_STATE_SCHEMA_VERSION,
+    measurementVersion: value.measurementVersion,
+    indexGeneration: value.indexGeneration,
+    status: value.status,
+    reason: value.reason,
+    progress: cloneProgress(value.progress),
+    failStreak: value.failStreak,
+    nextEligibleAt: value.nextEligibleAt,
+    pausedReason: value.pausedReason,
+    updatedAt: value.updatedAt,
+  };
+}
+
+export function createBackgroundWorkState(
+  options: CreateBackgroundWorkStateOptions,
+): BackgroundWorkState {
+  assertSafeNonNegativeInteger(options.measurementVersion, 'measurementVersion');
+  if (options.measurementVersion === 0) throw new RangeError('measurementVersion must be positive');
+  assertSafeNonNegativeInteger(options.now, 'now');
+  assertReason(options.reason);
+  return {
+    schemaVersion: BACKGROUND_WORK_STATE_SCHEMA_VERSION,
+    measurementVersion: options.measurementVersion,
+    indexGeneration: options.indexGeneration ?? null,
+    status: 'eligible',
+    reason: options.reason,
+    progress: options.progress === undefined ? emptyProgress() : cloneProgress(options.progress),
+    failStreak: 0,
+    nextEligibleAt: options.now,
+    pausedReason: null,
+    updatedAt: options.now,
+  };
+}
+
+export function restoreBackgroundWorkState(
+  value: unknown,
+  options: CreateBackgroundWorkStateOptions,
+): BackgroundWorkRestoreResult {
+  const fresh = (): BackgroundWorkState => createBackgroundWorkState(options);
+  if (value === undefined || value === null) return { disposition: 'new', state: fresh() };
+  if (!isBackgroundWorkState(value)) {
+    const state = fresh();
+    return {
+      disposition: 'corrupt',
+      state: {
+        ...state,
+        status: 'paused',
+        nextEligibleAt: null,
+        pausedReason: 'corrupt-state',
+      },
+    };
+  }
+  if (value.measurementVersion !== options.measurementVersion) {
+    return { disposition: 'measurement-changed', state: fresh() };
+  }
+  if (options.indexGeneration !== undefined && value.indexGeneration !== options.indexGeneration) {
+    return { disposition: 'generation-changed', state: fresh() };
+  }
+  return { disposition: 'valid', state: cloneState(value) };
+}
+
+export function canStartBackgroundWork(
+  state: BackgroundWorkState,
+  options: Pick<BackgroundWorkStartOptions, 'trigger' | 'now'>,
+): boolean {
+  assertTrigger(options.trigger);
+  assertSafeNonNegativeInteger(options.now, 'now');
+  if (!isBackgroundWorkState(state)) return false;
+  if (state.status === 'complete' || state.status === 'running') return false;
+  if (state.status === 'paused') {
+    return state.pausedReason === 'user' && options.trigger === 'manual';
+  }
+  if (options.trigger === 'manual') return true;
+  return state.nextEligibleAt !== null && options.now >= state.nextEligibleAt;
+}
+
+export function beginBackgroundWork(
+  state: BackgroundWorkState,
+  options: BackgroundWorkStartOptions,
+): BackgroundWorkStartResult {
+  if (options.reason !== undefined) assertReason(options.reason);
+  if (!canStartBackgroundWork(state, options)) return { started: false, state };
+  return {
+    started: true,
+    state: {
+      ...cloneState(state),
+      status: 'running',
+      reason: options.reason ?? state.reason,
+      nextEligibleAt: null,
+      pausedReason: null,
+      updatedAt: options.now,
+    },
+  };
+}
+
+function assertRunningState(state: BackgroundWorkState): void {
+  if (!isBackgroundWorkState(state) || state.status !== 'running') {
+    throw new Error('background work attempt must be running');
+  }
+}
+
+function assertBackoffPolicy(policy: BackgroundWorkBackoffPolicy): void {
+  assertSafeNonNegativeInteger(policy.failureBaseMs, 'failureBaseMs');
+  assertSafeNonNegativeInteger(policy.failureMaxMs, 'failureMaxMs');
+  assertSafeNonNegativeInteger(policy.noProgressCooldownMs, 'noProgressCooldownMs');
+  if (policy.failureBaseMs === 0 || policy.failureMaxMs < policy.failureBaseMs ||
+      policy.noProgressCooldownMs === 0) {
+    throw new RangeError('background work backoff durations must be positive and ordered');
+  }
+}
+
+export function backgroundWorkFailureBackoffMs(
+  failStreak: number,
+  policy: BackgroundWorkBackoffPolicy = DEFAULT_BACKGROUND_WORK_BACKOFF_POLICY,
+): number {
+  assertSafeNonNegativeInteger(failStreak, 'failStreak');
+  assertBackoffPolicy(policy);
+  if (failStreak === 0) return 0;
+  const exponent = Math.min(52, failStreak - 1);
+  return Math.min(policy.failureMaxMs, policy.failureBaseMs * Math.pow(2, exponent));
+}
+
+function safeTimestampAfter(now: number, delay: number): number {
+  return Math.min(Number.MAX_SAFE_INTEGER, now + delay);
+}
+
+export function recordBackgroundWorkFailure(
+  state: BackgroundWorkState,
+  options: { now: number },
+  policy: BackgroundWorkBackoffPolicy = DEFAULT_BACKGROUND_WORK_BACKOFF_POLICY,
+): BackgroundWorkState {
+  assertRunningState(state);
+  assertSafeNonNegativeInteger(options.now, 'now');
+  assertBackoffPolicy(policy);
+  const failStreak = Math.min(Number.MAX_SAFE_INTEGER, state.failStreak + 1);
+  return {
+    ...cloneState(state),
+    status: 'cooldown',
+    failStreak,
+    nextEligibleAt: safeTimestampAfter(
+      options.now,
+      backgroundWorkFailureBackoffMs(failStreak, policy),
+    ),
+    pausedReason: 'failure-backoff',
+    updatedAt: options.now,
+  };
+}
+
+/** Return an interrupted in-flight attempt to the immediately eligible state.
+ * Cancellation is neither a failure nor proof of no progress: the provider
+ * index owns the exact durable cursor and the next permitted coordinator pass
+ * may resume it from there. */
+export function interruptBackgroundWork(
+  state: BackgroundWorkState,
+  options: { now: number },
+): BackgroundWorkState {
+  assertRunningState(state);
+  assertSafeNonNegativeInteger(options.now, 'now');
+  return {
+    ...cloneState(state),
+    status: 'eligible',
+    reason: 'resume',
+    nextEligibleAt: options.now,
+    pausedReason: null,
+    updatedAt: options.now,
+  };
+}
+
+function mergedProgress(
+  current: BackgroundWorkProgress,
+  incoming: BackgroundWorkProgress,
+): BackgroundWorkProgress {
+  const checked = cloneProgress(incoming);
+  const completedUnits = Math.max(current.completedUnits, checked.completedUnits);
+  const completedBytes = Math.max(current.completedBytes, checked.completedBytes);
+  return {
+    completedUnits,
+    totalUnits: Math.max(current.totalUnits, checked.totalUnits, completedUnits),
+    completedBytes,
+    totalBytes: Math.max(current.totalBytes, checked.totalBytes, completedBytes),
+  };
+}
+
+export function recordBackgroundWorkProgress(
+  state: BackgroundWorkState,
+  options: { now: number; complete: boolean; progress: BackgroundWorkProgress },
+  policy: BackgroundWorkBackoffPolicy = DEFAULT_BACKGROUND_WORK_BACKOFF_POLICY,
+): BackgroundWorkState {
+  assertRunningState(state);
+  assertSafeNonNegativeInteger(options.now, 'now');
+  assertBackoffPolicy(policy);
+  const progress = mergedProgress(state.progress, options.progress);
+  const advanced = progress.completedUnits > state.progress.completedUnits ||
+    progress.completedBytes > state.progress.completedBytes;
+
+  if (options.complete) {
+    return {
+      ...cloneState(state),
+      status: 'complete',
+      progress,
+      failStreak: 0,
+      nextEligibleAt: null,
+      pausedReason: null,
+      updatedAt: options.now,
+    };
+  }
+  if (advanced) {
+    return {
+      ...cloneState(state),
+      status: 'eligible',
+      progress,
+      failStreak: 0,
+      nextEligibleAt: options.now,
+      pausedReason: null,
+      updatedAt: options.now,
+    };
+  }
+  return {
+    ...cloneState(state),
+    status: 'cooldown',
+    progress,
+    nextEligibleAt: safeTimestampAfter(options.now, policy.noProgressCooldownMs),
+    pausedReason: 'no-progress',
+    updatedAt: options.now,
+  };
+}
+
+export function pauseBackgroundWork(
+  state: BackgroundWorkState,
+  options: { now: number },
+): BackgroundWorkState {
+  assertSafeNonNegativeInteger(options.now, 'now');
+  if (!isBackgroundWorkState(state)) throw new TypeError('background work state is invalid');
+  if (state.status === 'complete' || state.pausedReason === 'corrupt-state') return state;
+  if (state.status === 'paused' && state.pausedReason === 'user') return state;
+  return {
+    ...cloneState(state),
+    status: 'paused',
+    nextEligibleAt: null,
+    pausedReason: 'user',
+    updatedAt: options.now,
+  };
+}
diff --git a/src/claudeApiClient.ts b/src/claudeApiClient.ts
index 7b8156cb..dd4c4bb5 100644
--- a/src/claudeApiClient.ts
+++ b/src/claudeApiClient.ts
@@ -1,4 +1,5 @@
 import { execFileSync } from 'child_process';
+import { createHmac } from 'node:crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -13,6 +14,15 @@ export interface ResolvedClaudeProfile {
   allowKeychainFallback: boolean;
 }
 
+export function claudeQuotaIdentitySignal(
+  machineSalt: string,
+  refreshToken: string,
+): string {
+  return createHmac('sha256', machineSalt)
+    .update(`claude-quota-account-v1|${refreshToken}`)
+    .digest('hex');
+}
+
 function isDirectory(candidate: string): boolean {
   try {
     return fs.existsSync(candidate) && fs.statSync(candidate).isDirectory();
@@ -85,10 +95,12 @@ export class ClaudeApiClient {
   // Once curl has succeeded after fetch failed, remember so we don't keep
   // paying the cost of a doomed fetch attempt on every refresh.
   private preferCurl: boolean = false;
+  private lastQuotaIdentitySignal: string | null = null;
 
   constructor(
     out: vscode.OutputChannel | null = null,
     dataDirectory?: string | null,
+    private readonly quotaIdentitySalt?: string,
   ) {
     const profile = resolveClaudeProfile(dataDirectory);
     this.credentialsPath = profile.credentialsPath;
@@ -134,6 +146,13 @@ export class ClaudeApiClient {
     return this.credentialsPath;
   }
 
+  /** Machine-local one-way continuity signal for the exact credentials used
+   * by the last successful quota request. No token or account identifier is
+   * returned to the extension host. */
+  getLastQuotaIdentitySignal(): string | null {
+    return this.lastQuotaIdentitySignal;
+  }
+
   private loadCredentialsFromKeychain(): ClaudeCredentials | null {
     if (process.platform !== 'darwin') {
       return null;
@@ -189,15 +208,21 @@ export class ClaudeApiClient {
     return Date.now() >= credentials.claudeAiOauth.expiresAt - 60 * 1000;
   }
 
-  private async refreshAccessToken(credentials: ClaudeCredentials): Promise<ClaudeCredentials> {
+  private async refreshAccessToken(
+    credentials: ClaudeCredentials,
+    signal?: AbortSignal,
+  ): Promise<ClaudeCredentials> {
+    if (signal?.aborted) throw new Error('Request cancelled');
     const r = await this.request('https://console.anthropic.com/v1/oauth/token', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         refresh_token: credentials.claudeAiOauth.refreshToken,
         grant_type: 'refresh_token'
-      })
+      }),
+      signal,
     });
+    if (signal?.aborted) throw new Error('Request cancelled');
     if (r.status !== 200) {
       throw new Error(`Token refresh failed: ${r.status}`);
     }
@@ -214,7 +239,8 @@ export class ClaudeApiClient {
     return updated;
   }
 
-  private async getValidCredentials(): Promise<ClaudeCredentials | null> {
+  private async getValidCredentials(signal?: AbortSignal): Promise<ClaudeCredentials | null> {
+    if (signal?.aborted) throw new Error('Request cancelled');
     // Re-read from disk/keychain on every call so switching Claude accounts is
     // honoured without a window reload. #45: a switched-in account has a *valid*
     // (non-expired) token, so the expiry-only re-read below never noticed it and
@@ -222,6 +248,7 @@ export class ClaudeApiClient {
     // loadCredentials refreshes this.credentials; fall back to the cached copy
     // only if the fresh read transiently fails.
     let credentials = (await this.loadCredentials()) || this.credentials;
+    if (signal?.aborted) throw new Error('Request cancelled');
     if (!credentials) {
       return null;
     }
@@ -238,7 +265,7 @@ export class ClaudeApiClient {
       }
       this.log('token: expired, refreshing');
       try {
-        credentials = await this.refreshAccessToken(fresh || credentials);
+        credentials = await this.refreshAccessToken(fresh || credentials, signal);
       } catch (e) {
         this.log(`token: refresh failed: ${(e as Error).message}`);
         return null;
@@ -249,9 +276,9 @@ export class ClaudeApiClient {
 
   /**
    * A valid OAuth access token (refreshed if needed), or null when not signed
-   * in. Lets the advice/optimizer features reuse the user's Claude subscription
-   * — `Authorization: Bearer <token>` + `anthropic-beta: oauth-2025-04-20` —
-   * to call the Messages API with no separate API key (verified 2026-06-13).
+   * in. This credential is used for Claude Code account/quota APIs. It is not a
+   * default AI-advice backend; the old keyless Messages prototype is dormant
+   * after 403 responses and production advice remains user-configured BYOK.
    */
   async getAccessToken(): Promise<string | null> {
     const credentials = await this.getValidCredentials();
@@ -262,8 +289,14 @@ export class ClaudeApiClient {
    * rejection ("403 Request not allowed"). */
   private async request(
     url: string,
-    opts: { method?: string; headers?: Record<string, string>; body?: string }
+    opts: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: string;
+      signal?: AbortSignal;
+    }
   ): Promise<HttpResponse> {
+    if (opts.signal?.aborted) throw new Error('Request cancelled');
     if (!this.preferCurl) {
       try {
         const r = await requestViaFetch(url, opts);
@@ -275,22 +308,25 @@ export class ClaudeApiClient {
           return r;
         }
       } catch (e) {
+        if (opts.signal?.aborted) throw new Error('Request cancelled');
         this.log(`fetch: error ${(e as Error).message} → trying curl`);
       }
     }
+    if (opts.signal?.aborted) throw new Error('Request cancelled');
     const r = await requestViaCurl(url, opts, (line) => this.log(line));
     this.log(`curl:  ${r.status} ${url}`);
     return r;
   }
 
-  private callUsageApi(accessToken: string): Promise<HttpResponse> {
+  private callUsageApi(accessToken: string, signal?: AbortSignal): Promise<HttpResponse> {
     return this.request('https://api.anthropic.com/api/oauth/usage', {
       method: 'GET',
       headers: {
         Authorization: `Bearer ${accessToken}`,
         'anthropic-beta': 'oauth-2025-04-20',
         'Content-Type': 'application/json'
-      }
+      },
+      signal,
     });
   }
 
@@ -300,19 +336,24 @@ export class ClaudeApiClient {
    * or when anything else goes wrong. All decisions are logged to the
    * "Claude Code Usage" output channel for diagnosis.
    */
-  async fetchUsageLimits(): Promise<ClaudeApiUsageResponse | null> {
+  async fetchUsageLimits(signal?: AbortSignal): Promise<ClaudeApiUsageResponse | null> {
+    if (signal?.aborted) return null;
     if (Date.now() < this.rateLimitedUntil) {
       this.log(`skip: cooling down for ${Math.round((this.rateLimitedUntil - Date.now()) / 1000)}s after 429`);
       return null;
     }
 
     try {
-      const credentials = await this.getValidCredentials();
+      let credentials = await this.getValidCredentials(signal);
       if (!credentials) {
         return null;
       }
 
-      let response = await this.callUsageApi(credentials.claudeAiOauth.accessToken);
+      if (signal?.aborted) return null;
+      let response = await this.callUsageApi(
+        credentials.claudeAiOauth.accessToken,
+        signal,
+      );
 
       if (response.status === 429) {
         // 60 s cool-down. The old flat 5-minute cool-down made a single 429
@@ -328,8 +369,12 @@ export class ClaudeApiClient {
       if (response.status === 401) {
         this.log('401: forcing token refresh and retrying once');
         try {
-          const refreshed = await this.refreshAccessToken(credentials);
-          response = await this.callUsageApi(refreshed.claudeAiOauth.accessToken);
+          const refreshed = await this.refreshAccessToken(credentials, signal);
+          credentials = refreshed;
+          response = await this.callUsageApi(
+            refreshed.claudeAiOauth.accessToken,
+            signal,
+          );
         } catch (e) {
           this.log(`401 retry: refresh failed: ${(e as Error).message}`);
           return null;
@@ -341,6 +386,12 @@ export class ClaudeApiClient {
         return null;
       }
       const data = JSON.parse(response.body) as ClaudeApiUsageResponse;
+      this.lastQuotaIdentitySignal = this.quotaIdentitySalt
+        ? claudeQuotaIdentitySignal(
+            this.quotaIdentitySalt,
+            credentials.claudeAiOauth.refreshToken,
+          )
+        : null;
       this.log(`usage: ok — 5h=${data.five_hour?.utilization ?? 'n/a'}%, wk=${data.seven_day?.utilization ?? 'n/a'}%`);
       return data;
     } catch (e) {
diff --git a/src/claudeIncrementalIndex.ts b/src/claudeIncrementalIndex.ts
index 2ad6dd8e..1e2baf70 100644
--- a/src/claudeIncrementalIndex.ts
+++ b/src/claudeIncrementalIndex.ts
@@ -16,7 +16,13 @@ import {
   newAnalysisAcc,
   validateUsageRecord,
 } from './dataLoader';
-import { dayKeyInZone, monthKeyInZone } from './dateKeys';
+import {
+  dayKeyInZone,
+  formatHourLabel,
+  monthKeyInZone,
+  resolveTimeZone,
+  rollingDayKeys,
+} from './dateKeys';
 import { I18n } from './i18n';
 import { isRetryDuplicatePrompt } from './promptDedup';
 import {
@@ -101,7 +107,14 @@ interface CopyOnWriteKeys {
   visibleLocalDays: Set<string>;
 }
 
+interface ConfiguredTimeKeyers {
+  formatter: Intl.DateTimeFormat;
+  hourWindowStartDay: string;
+}
+
 export interface ClaudeUsageIndex {
+  /** Canonical configured zone used by every materialized calendar bucket. */
+  timeZone: string;
   files: Map<string, ClaudeUsageFileContribution>;
   manifest: UsageManifest | null;
   candidatesByMessage: Map<string, Map<string, IndexedRecord>>;
@@ -129,6 +142,8 @@ export interface ClaudeUsageIndex {
   analyzeContent: boolean;
   windowDays: number;
   analysisCutoffMs: number;
+  /** Transient formatter/cache state; never persisted with the index. */
+  timeKeyers: ConfiguredTimeKeyers;
 }
 
 export interface ClaudeUsageIndexDiagnostics extends LoadUsageDiagnostics {
@@ -159,8 +174,13 @@ export interface ClaudeUsageIndexUpdateResult {
 
 export interface ClaudeUsageAggregateSnapshot {
   today: UsageData;
+  /** Rolling 30 local calendar days, including the snapshot day. This is kept
+   * separate from `month` because the status bar's monthly-cost metric is a
+   * true calendar-month total while the dashboard range is rolling. */
+  last30Days: UsageData;
   month: UsageData;
   allTime: UsageData;
+  dailyForLast30Days: { date: string; data: UsageData }[];
   dailyForMonth: { date: string; data: UsageData }[];
   monthlyForAllTime: { date: string; data: UsageData }[];
   hourlyForToday: { hour: string; data: UsageData }[];
@@ -175,6 +195,14 @@ export interface ClaudeUsageDashboardSnapshot extends ClaudeUsageAggregateSnapsh
   workflows: WorkflowUsage[];
   costliestMessages: CostlyMessage[];
   context: ContextWindowInfo | null;
+  /** Present only for the default-off advice capability; built from materialized aggregates. */
+  adviceWindow?: {
+    windowDays: number;
+    aggregate: UsageData;
+    totalSessions: number;
+    longSessionCount: number;
+    largeContextSessionCount: number;
+  };
 }
 
 interface FilePlan {
@@ -239,8 +267,25 @@ function emptyCopyOnWriteKeys(): CopyOnWriteKeys {
   };
 }
 
+function createConfiguredTimeKeyers(timeZone: string, now = Date.now()): ConfiguredTimeKeyers {
+  const resolved = resolveTimeZone(timeZone);
+  return {
+    formatter: new Intl.DateTimeFormat('en-CA', {
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      hourCycle: 'h23',
+      timeZone: resolved,
+    }),
+    hourWindowStartDay: rollingDayKeys(now, resolved, 30)[0] ?? '',
+  };
+}
+
 export function createClaudeUsageIndex(): ClaudeUsageIndex {
+  const timeZone = resolveTimeZone(I18n.getTimezone());
   return {
+    timeZone,
     files: new Map(),
     manifest: null,
     candidatesByMessage: new Map(),
@@ -268,6 +313,7 @@ export function createClaudeUsageIndex(): ClaudeUsageIndex {
     analyzeContent: false,
     windowDays: 30,
     analysisCutoffMs: 0,
+    timeKeyers: createConfiguredTimeKeyers(timeZone),
   };
 }
 
@@ -381,6 +427,12 @@ function cloneAnalysisAcc(value: AnalysisAcc): AnalysisAcc {
     ),
     skillUses: value.skillUses.map((use) => ({ ...use })),
     skillByToolId: { ...value.skillByToolId },
+    frameworkOverhead: Object.fromEntries(
+      Object.entries(value.frameworkOverhead).map(([key, bucket]) => [key, { ...bucket }]),
+    ),
+    observedInputEstimatedTokens: value.observedInputEstimatedTokens,
+    userAuthoredEstimatedTokens: value.userAuthoredEstimatedTokens,
+    toolResultEstimatedTokens: value.toolResultEstimatedTokens,
   };
 }
 
@@ -604,9 +656,17 @@ function cloneUsageData(value: UsageData): UsageData {
   };
 }
 
-function localDayKey(date: Date): string {
-  if (Number.isNaN(date.getTime())) return '';
-  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+function configuredTimeKeys(
+  index: ClaudeUsageIndex,
+  date: Date,
+): { day: string; month: string; hour: string } {
+  if (isNaN(date.getTime())) return { day: '', month: '', hour: '' };
+  const parts = index.timeKeyers.formatter.formatToParts(date);
+  const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? '';
+  const day = `${get('year')}-${get('month')}-${get('day')}`;
+  const month = day.slice(0, 7);
+  const hour = formatHourLabel(get('hour'));
+  return { day, month, hour };
 }
 
 function addUsageData(target: UsageData, source: UsageData, sign: 1 | -1): void {
@@ -663,29 +723,38 @@ function applyBucket(
   else buckets.set(key, value);
 }
 
+function applyConfiguredTimeAggregate(
+  index: ClaudeUsageIndex,
+  record: ClaudeUsageRecord,
+  contribution: UsageData,
+  sign: 1 | -1,
+): void {
+  const date = new Date(record.timestamp);
+  const { day, month, hour } = configuredTimeKeys(index, date);
+  const dayHour = day && hour
+    ? `${day}\0${hour}`
+    : '';
+  applyBucket(index.aggregates.byDay, day, contribution, sign);
+  applyBucket(index.aggregates.byMonth, month, contribution, sign);
+  applyBucket(index.aggregates.byLocalDay, day, contribution, sign);
+  if (day >= index.timeKeyers.hourWindowStartDay) {
+    applyBucket(index.aggregates.byLocalHour, dayHour, contribution, sign);
+  }
+}
+
 function applyAggregate(index: ClaudeUsageIndex, record: ClaudeUsageRecord, sign: 1 | -1): void {
   const contribution = ClaudeDataLoader.calculateUsageData([record]);
   addUsageData(index.aggregates.allTime, contribution, sign);
-  const date = new Date(record.timestamp);
-  const day = dayKeyInZone(date, I18n.getTimezone());
-  const month = monthKeyInZone(date, I18n.getTimezone());
-  const localDay = localDayKey(date);
-  const localHour = localDay
-    ? `${localDay}\0${String(date.getHours()).padStart(2, '0')}:00`
-    : '';
+  applyConfiguredTimeAggregate(index, record, contribution, sign);
   const project = record._projectPath || record._projectName || 'unknown';
   const branch = record._gitBranch && record._gitBranch.trim() ? record._gitBranch : '-';
-  applyBucket(index.aggregates.byDay, day, contribution, sign);
-  applyBucket(index.aggregates.byMonth, month, contribution, sign);
-  applyBucket(index.aggregates.byLocalDay, localDay, contribution, sign);
-  applyBucket(index.aggregates.byLocalHour, localHour, contribution, sign);
   applyBucket(index.aggregates.bySession, record._sessionId || 'unknown', contribution, sign);
   applyBucket(index.aggregates.byProject, project.toLowerCase(), contribution, sign);
   applyBucket(index.aggregates.byBranch, `${record._projectName || 'unknown'}\0${branch}`, contribution, sign);
   applyBucket(index.aggregates.byWorkflow, record._workflowId, contribution, sign);
 }
 
-function membershipKeys(record: ClaudeUsageRecord): {
+function membershipKeys(index: ClaudeUsageIndex, record: ClaudeUsageRecord): {
   session: string;
   project: string;
   branch: string;
@@ -698,7 +767,13 @@ function membershipKeys(record: ClaudeUsageRecord): {
   const branchName = record._gitBranch && record._gitBranch.trim() ? record._gitBranch : '-';
   const branch = `${record._projectName || 'unknown'}\0${branchName}`;
   const workflow = record._workflowId || (record._agentId ? `adhoc:${session}` : undefined);
-  return { session, project, branch, workflow, localDay: localDayKey(new Date(record.timestamp)) };
+  return {
+    session,
+    project,
+    branch,
+    workflow,
+    localDay: dayKeyInZone(new Date(record.timestamp), index.timeZone),
+  };
 }
 
 function writableSet(
@@ -743,7 +818,7 @@ function removeMembership(
 }
 
 function markDirty(index: ClaudeUsageIndex, record: ClaudeUsageRecord): void {
-  const keys = membershipKeys(record);
+  const keys = membershipKeys(index, record);
   index.dirtyGroups.sessions.add(keys.session);
   index.dirtyGroups.projects.add(keys.project);
   index.dirtyGroups.branches.add(keys.branch);
@@ -751,7 +826,7 @@ function markDirty(index: ClaudeUsageIndex, record: ClaudeUsageRecord): void {
 }
 
 function addVisibleMembership(index: ClaudeUsageIndex, visibleKey: string, record: ClaudeUsageRecord): void {
-  const keys = membershipKeys(record);
+  const keys = membershipKeys(index, record);
   addMembership(index.visibleKeysBySession, keys.session, visibleKey, index.copyOnWrite.visibleSessions);
   addMembership(index.visibleKeysByProject, keys.project, visibleKey, index.copyOnWrite.visibleProjects);
   addMembership(index.visibleKeysByBranch, keys.branch, visibleKey, index.copyOnWrite.visibleBranches);
@@ -761,7 +836,7 @@ function addVisibleMembership(index: ClaudeUsageIndex, visibleKey: string, recor
 }
 
 function removeVisibleMembership(index: ClaudeUsageIndex, visibleKey: string, record: ClaudeUsageRecord): void {
-  const keys = membershipKeys(record);
+  const keys = membershipKeys(index, record);
   removeMembership(index.visibleKeysBySession, keys.session, visibleKey, index.copyOnWrite.visibleSessions);
   removeMembership(index.visibleKeysByProject, keys.project, visibleKey, index.copyOnWrite.visibleProjects);
   removeMembership(index.visibleKeysByBranch, keys.branch, visibleKey, index.copyOnWrite.visibleBranches);
@@ -791,6 +866,26 @@ function setVisible(
   return 1;
 }
 
+/** Rebucket already-materialized records after an explicit timezone change. */
+function rebuildConfiguredTimeAggregates(index: ClaudeUsageIndex): void {
+  index.aggregates.byDay = new Map();
+  index.aggregates.byMonth = new Map();
+  index.aggregates.byLocalDay = new Map();
+  index.aggregates.byLocalHour = new Map();
+  index.visibleKeysByLocalDay = new Map();
+  index.copyOnWrite.visibleLocalDays = new Set();
+  for (const [visibleKey, record] of index.visibleRecords) {
+    const contribution = ClaudeDataLoader.calculateUsageData([record]);
+    applyConfiguredTimeAggregate(index, record, contribution, 1);
+    addMembership(
+      index.visibleKeysByLocalDay,
+      dayKeyInZone(new Date(record.timestamp), index.timeZone),
+      visibleKey,
+      index.copyOnWrite.visibleLocalDays,
+    );
+  }
+}
+
 function candidateMessageId(value: IndexedRecord): string | null {
   const messageId = value.record.message.id;
   return messageId ? String(messageId) : null;
@@ -990,6 +1085,14 @@ function cloneIndexForCommit(previous: ClaudeUsageIndex): ClaudeUsageIndex {
   };
 }
 
+function pruneHourlyBuckets(index: ClaudeUsageIndex): void {
+  const cutoff = index.timeKeyers.hourWindowStartDay;
+  if (!cutoff) return;
+  for (const key of index.aggregates.byLocalHour.keys()) {
+    if (key.slice(0, 10) < cutoff) index.aggregates.byLocalHour.delete(key);
+  }
+}
+
 function recordsOf(index: ClaudeUsageIndex): ClaudeUsageRecord[] {
   return [...index.visibleRecords.values()];
 }
@@ -1183,23 +1286,48 @@ export function claudeUsageAggregateSnapshot(
   index: ClaudeUsageIndex,
   now: Date = new Date(),
 ): ClaudeUsageAggregateSnapshot {
-  const localToday = localDayKey(now);
-  const configuredMonth = monthKeyInZone(now, I18n.getTimezone());
-  const dailyForMonth = [...index.aggregates.byDay.entries()]
+  const localToday = dayKeyInZone(now, index.timeZone);
+  const configuredMonth = monthKeyInZone(now, index.timeZone);
+  const last30DayKeys = rollingDayKeys(now.getTime(), index.timeZone, 30);
+  const last30Days = emptyUsageData();
+  const dailyForLast30Days = last30DayKeys.flatMap((date) => {
+    const data = index.aggregates.byLocalDay.get(date);
+    if (!data) return [];
+    addUsageData(last30Days, data, 1);
+    return [{ date, data: cloneUsageData(data) }];
+  }).sort((left, right) => right.date.localeCompare(left.date));
+  const dailyForMonth = [...index.aggregates.byLocalDay.entries()]
     .filter(([day]) => day.startsWith(configuredMonth))
     .map(([date, data]) => ({ date, data: cloneUsageData(data) }))
     .sort((left, right) => right.date.localeCompare(left.date));
   const monthlyForAllTime = [...index.aggregates.byMonth.entries()]
     .map(([month, data]) => ({ date: `${month}-01`, data: cloneUsageData(data) }))
     .sort((left, right) => right.date.localeCompare(left.date));
-  const hourlyForToday = [...index.aggregates.byLocalHour.entries()]
+  let hourlyForToday = [...index.aggregates.byLocalHour.entries()]
     .filter(([key]) => key.startsWith(`${localToday}\0`))
     .map(([key, data]) => ({ hour: key.slice(localToday.length + 1), data: cloneUsageData(data) }))
     .sort((left, right) => left.hour.localeCompare(right.hour));
+  // Historical callers may ask for a deterministic snapshot date (tests,
+  // replay, or an already-rendered day). If that day is outside the rolling
+  // materialized hour window, derive its hours from the in-memory visible
+  // records only; never reopen JSONL.
+  if (hourlyForToday.length === 0 && index.aggregates.byLocalDay.has(localToday)) {
+    const fallback = new Map<string, UsageData>();
+    for (const record of index.visibleRecords.values()) {
+      const keys = configuredTimeKeys(index, new Date(record.timestamp));
+      if (keys.day !== localToday || !keys.hour) continue;
+      applyBucket(fallback, keys.hour, ClaudeDataLoader.calculateUsageData([record]), 1);
+    }
+    hourlyForToday = [...fallback.entries()]
+      .map(([hour, data]) => ({ hour, data }))
+      .sort((left, right) => left.hour.localeCompare(right.hour));
+  }
   return {
     today: cloneUsageData(index.aggregates.byLocalDay.get(localToday) ?? emptyUsageData()),
+    last30Days,
     month: cloneUsageData(index.aggregates.byMonth.get(configuredMonth) ?? emptyUsageData()),
     allTime: cloneUsageData(index.aggregates.allTime),
+    dailyForLast30Days,
     dailyForMonth,
     monthlyForAllTime,
     hourlyForToday,
@@ -1212,6 +1340,7 @@ export function claudeUsageDashboardSnapshot(
     workspacePath?: string;
     projectGroupingMode?: 'git' | 'folder' | 'flat';
     contextWindowOverride?: number;
+    adviceWindowDays?: number;
     now?: Date;
   } = {},
 ): ClaudeUsageDashboardSnapshot {
@@ -1236,7 +1365,7 @@ export function claudeUsageDashboardSnapshot(
   if (options.workspacePath) {
     const todayRecords = recordsForKeys(
       index,
-      index.visibleKeysByLocalDay.get(localDayKey(now)),
+      index.visibleKeysByLocalDay.get(dayKeyInZone(now, index.timeZone)),
     ).filter((record) => recordMatchesWorkspace(record, options.workspacePath!));
     workspaceToday = ClaudeDataLoader.calculateUsageData(todayRecords);
   }
@@ -1265,6 +1394,30 @@ export function claudeUsageDashboardSnapshot(
     .flat()
     .sort((left, right) => right.cost - left.cost)
     .slice(0, 10);
+  let adviceWindow: ClaudeUsageDashboardSnapshot['adviceWindow'];
+  if (options.adviceWindowDays !== undefined) {
+    const windowDays = Math.min(365, Math.max(1, Math.round(options.adviceWindowDays)));
+    const dayKeys = new Set(rollingDayKeys(now.getTime(), index.timeZone, windowDays));
+    const aggregate = emptyUsageData();
+    for (const day of dayKeys) {
+      const value = index.aggregates.byLocalDay.get(day);
+      if (value) addUsageData(aggregate, value, 1);
+    }
+    const windowSessions = [...index.sessionRows.values()].filter((row) =>
+      dayKeys.has(dayKeyInZone(row.endTime, index.timeZone)),
+    );
+    adviceWindow = {
+      windowDays,
+      aggregate,
+      totalSessions: windowSessions.length,
+      longSessionCount: windowSessions.filter(
+        (row) => row.endTime.getTime() - row.startTime.getTime() >= 8 * 60 * 60 * 1000,
+      ).length,
+      largeContextSessionCount: windowSessions.filter(
+        (row) => row.peakContextTokens >= 150_000,
+      ).length,
+    };
+  }
   return {
     ...aggregates,
     session,
@@ -1279,6 +1432,7 @@ export function claudeUsageDashboardSnapshot(
       .slice(0, 50),
     costliestMessages,
     context,
+    ...(adviceWindow ? { adviceWindow } : {}),
   };
 }
 
@@ -1288,6 +1442,9 @@ export async function updateClaudeUsageIndex(
   options: ClaudeUsageIndexUpdateOptions = {},
 ): Promise<ClaudeUsageIndexUpdateResult> {
   const started = performance.now();
+  const configuredTimeZone = resolveTimeZone(I18n.getTimezone());
+  const timeKeyers = createConfiguredTimeKeyers(configuredTimeZone);
+  const timeZoneChanged = previous.timeZone !== configuredTimeZone;
   const analyzeContent = options.analyzeContent !== false;
   const windowDays = Math.min(365, Math.max(1, Math.round(options.windowDays ?? 30)));
   const analysisCutoffMs = analyzeContent && previous.analyzeContent &&
@@ -1425,6 +1582,12 @@ export async function updateClaudeUsageIndex(
   }
 
   const next = cloneIndexForCommit(previous);
+  next.timeZone = configuredTimeZone;
+  next.timeKeyers = timeKeyers;
+  pruneHourlyBuckets(next);
+  if (timeZoneChanged) {
+    rebuildConfiguredTimeAggregates(next);
+  }
   next.manifest = manifest;
   next.analyzeContent = analyzeContent;
   next.windowDays = windowDays;
@@ -1432,7 +1595,7 @@ export async function updateClaudeUsageIndex(
   const affectedMessages = new Set<string>();
   const affectedDirect = new Set<string>();
   const affectedSessions = new Set<string>();
-  let aggregateMutations = 0;
+  let aggregateMutations = timeZoneChanged ? next.visibleRecords.size : 0;
   const removeFile = (file: ClaudeUsageFileContribution): void => {
     next.files.delete(file.fileId);
     affectedSessions.add(ClaudeDataLoader.parseSessionInfo(file.path).sessionId);
diff --git a/src/codexStatus.ts b/src/codexStatus.ts
index dd5cc1c9..cb60a04b 100644
--- a/src/codexStatus.ts
+++ b/src/codexStatus.ts
@@ -3,12 +3,30 @@ import { ProviderLimitSnapshot } from './providers/providerTypes';
 
 export type CodexStatusMetric = 'fresh' | 'processed' | 'output';
 
+export interface CodexStatusOptions {
+  /** Keep the existing opt-in preference meaningful for the Codex bar. */
+  quotaFiveHourOnly?: boolean;
+}
+
+export interface CodexStatusLimit {
+  label: string;
+  windowMinutes?: number;
+  usedPercent: number;
+  remainingPercent: number;
+  observedAt?: number;
+  resetsAt?: number;
+}
+
 export interface CodexStatusText {
   text: string;
   limitText?: string;
+  limit?: CodexStatusLimit;
   stale: boolean;
 }
 
+const FIVE_HOUR_MINUTES = 5 * 60;
+const WEEK_MINUTES = 7 * 24 * 60;
+
 function compact(value: number): string {
   const safe = Math.max(0, value);
   if (safe >= 1_000_000_000) {
@@ -23,7 +41,16 @@ function compact(value: number): string {
   return String(Math.round(safe));
 }
 
-function windowLabel(minutes: number | undefined, fallback: string | undefined): string {
+export function codexQuotaWindowLabel(
+  minutes: number | undefined,
+  fallback: string | undefined,
+): string {
+  if (minutes === FIVE_HOUR_MINUTES) {
+    return '5h';
+  }
+  if (minutes === WEEK_MINUTES) {
+    return 'wk';
+  }
   if (minutes !== undefined && minutes > 0) {
     if (minutes % (24 * 60) === 0) {
       return `${minutes / (24 * 60)}d`;
@@ -36,11 +63,56 @@ function windowLabel(minutes: number | undefined, fallback: string | undefined):
   return fallback && fallback !== 'primary' ? fallback : 'limit';
 }
 
+function clampPercent(value: number): number {
+  return Math.max(0, Math.min(100, Number.isFinite(value) ? value : 0));
+}
+
+function selectQuotaWindow(
+  windows: ProviderLimitSnapshot['windows'],
+  options: CodexStatusOptions,
+): ProviderLimitSnapshot['windows'][number] | undefined {
+  if (options.quotaFiveHourOnly) {
+    return windows.find((window) => window.windowMinutes === FIVE_HOUR_MINUTES);
+  }
+  // The weekly allowance is the useful default after a reset: it answers how
+  // much room remains for the week, rather than how much has already gone.
+  return windows.find((window) => window.windowMinutes === WEEK_MINUTES)
+    ?? windows.find((window) => window.windowMinutes === FIVE_HOUR_MINUTES)
+    ?? windows[0];
+}
+
+/** Live windows that the Codex status item and its tooltip actually expose.
+ * The five-hour-only preference must affect the compact text, tooltip, and
+ * warning colour together; otherwise a red item can have no visible red row. */
+export function visibleCodexQuotaWindows(
+  limit: ProviderLimitSnapshot | null,
+  now: number = Date.now(),
+  options: CodexStatusOptions = {},
+): ProviderLimitSnapshot['windows'] {
+  return (limit?.windows ?? []).filter((window) =>
+    (window.resetsAt === undefined || window.resetsAt > now) &&
+    (!options.quotaFiveHourOnly || window.windowMinutes === FIVE_HOUR_MINUTES),
+  );
+}
+
+/** Highest utilisation among the live rows rendered for Codex. */
+export function codexQuotaWarningPercent(
+  limit: ProviderLimitSnapshot | null,
+  now: number = Date.now(),
+  options: CodexStatusOptions = {},
+): number {
+  return visibleCodexQuotaWindows(limit, now, options).reduce(
+    (worst, window) => Math.max(worst, clampPercent(window.usedPercent)),
+    0,
+  );
+}
+
 export function formatCodexStatus(
   scope: CodexUsageScopeView,
   metric: CodexStatusMetric,
   limit: ProviderLimitSnapshot | null,
   now: number = Date.now(),
+  options: CodexStatusOptions = {},
 ): CodexStatusText {
   const value =
     metric === 'processed'
@@ -48,17 +120,31 @@ export function formatCodexStatus(
       : metric === 'output'
         ? scope.total.output
         : scope.total.fresh;
-  const liveWindow = limit?.windows.find(
-    (window) => window.resetsAt === undefined || window.resetsAt > now,
-  );
-  const limitText = liveWindow
-    ? `${windowLabel(liveWindow.windowMinutes, liveWindow.label)} ${Math.round(
-        Math.max(0, Math.min(100, liveWindow.usedPercent)),
-      )}%`
+  const liveWindows = visibleCodexQuotaWindows(limit, now, options);
+  const liveWindow = selectQuotaWindow(liveWindows, options);
+  const selectedLimit = liveWindow
+    ? {
+        label: codexQuotaWindowLabel(liveWindow.windowMinutes, liveWindow.label),
+        ...(liveWindow.windowMinutes !== undefined
+          ? { windowMinutes: liveWindow.windowMinutes }
+          : {}),
+        usedPercent: clampPercent(liveWindow.usedPercent),
+        remainingPercent: 100 - clampPercent(liveWindow.usedPercent),
+        ...(limit?.observedAt !== undefined ? { observedAt: limit.observedAt } : {}),
+        ...(liveWindow.resetsAt !== undefined ? { resetsAt: liveWindow.resetsAt } : {}),
+      }
+    : undefined;
+  // The compact Codex allowance item answers the immediate planning question:
+  // how much room is left. The tooltip and warning colour still use the
+  // provider's observed utilisation, so progress semantics and thresholds stay
+  // aligned with Claude without making the short label ambiguous.
+  const limitText = selectedLimit
+    ? `${selectedLimit.label} ${Math.round(selectedLimit.remainingPercent)}%`
     : undefined;
   return {
     text: `CX ${compact(value)}${scope.indexedSubtotal ? '*' : ''}`,
     limitText,
-    stale: Boolean(limit && !liveWindow),
+    ...(selectedLimit ? { limit: selectedLimit } : {}),
+    stale: Boolean(limit && liveWindows.length === 0),
   };
 }
diff --git a/src/codexViewComponents.ts b/src/codexViewComponents.ts
index 3e340574..7703b2c1 100644
--- a/src/codexViewComponents.ts
+++ b/src/codexViewComponents.ts
@@ -2,6 +2,7 @@ import {
   CodexInsightEvidenceKey,
   CodexInsightKind,
 } from './providers/codex/codexInsights';
+import type { BackgroundWorkReason } from './backgroundWorkState';
 
 /** Copy contract retained for provider-aware renderers in webview.ts. */
 export const CODEX_QUALITY_FLAGS = [
@@ -149,6 +150,7 @@ export interface CodexViewCopy {
   indexedAllTime: string;
   indexedSubtotal: string;
   indexingInProgress: string;
+  indexingReasons: Record<BackgroundWorkReason, string>;
   updatedAt: string;
   claudeTokenAccounting: string;
   codexTokenAccounting: string;
@@ -289,6 +291,15 @@ export const CODEX_COPY_EN: CodexViewCopy = {
   observedSessionDuration: 'Elapsed span between the first and last observed events; a proxy, not actual active time.',
   indexedSubtotal: 'Indexed subtotal',
   indexingInProgress: 'Indexing is still in progress; unverified legacy totals are excluded.',
+  indexingReasons: {
+    'first-index': 'First local history setup',
+    'parser-migration': 'Updating the local parser index',
+    'period-migration': 'Updating date history',
+    'hourly-history': 'Building recent hourly history',
+    'history-backfill': 'Completing local history',
+    'rule-migration': 'Updating measurement rules',
+    resume: 'Resuming local history',
+  },
   indexedLogEntries: 'Indexed log entries',
   indexedStorage: 'Indexed storage',
   indexedAllTime: 'Indexed all time',
diff --git a/src/combinedHeatmap.ts b/src/combinedHeatmap.ts
new file mode 100644
index 00000000..a7435952
--- /dev/null
+++ b/src/combinedHeatmap.ts
@@ -0,0 +1,242 @@
+import { DayUsage } from './heatmap';
+
+export type CombinedHeatmapRange = '30d' | '90d' | 'year';
+
+export interface ProviderDailyPoint {
+  dateISO: string;
+  processed: number;
+}
+
+export interface CodexDailyProcessedLike {
+  day: string;
+  total: {
+    input: number;
+    output: number;
+    cachedInput?: number;
+    reasoning?: number;
+    processed?: number;
+  };
+}
+
+export interface CombinedDayUsage {
+  dateISO: string;
+  claudeProcessed: number;
+  codexProcessed: number;
+  combinedProcessed: number;
+}
+
+export interface CombinedHeatmapTotals {
+  claudeProcessed: number;
+  codexProcessed: number;
+  combinedProcessed: number;
+  activeDays: number;
+}
+
+export interface CombinedHeatmapWindow {
+  range: CombinedHeatmapRange;
+  startDateISO: string;
+  endDateISO: string;
+  daily: Record<string, CombinedDayUsage>;
+  totals: CombinedHeatmapTotals;
+}
+
+const DATE_KEY = /^\d{4}-\d{2}-\d{2}$/;
+
+function finiteNonNegative(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, value)
+    : 0;
+}
+
+function isCalendarDateKey(value: string): boolean {
+  if (!DATE_KEY.test(value)) {
+    return false;
+  }
+  const parsed = new Date(`${value}T00:00:00Z`);
+  return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+
+/** UTC date-key arithmetic keeps an already timezone-bucketed day stable. */
+export function addCalendarDays(dateISO: string, days: number): string {
+  if (!isCalendarDateKey(dateISO)) {
+    throw new Error(`Invalid calendar date: ${dateISO}`);
+  }
+  const date = new Date(`${dateISO}T00:00:00Z`);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}
+
+export function normalizeCombinedHeatmapRange(value: unknown): CombinedHeatmapRange {
+  return value === '30d' || value === '90d' || value === 'year' ? value : 'year';
+}
+
+export function combinedHeatmapRangeDays(range: CombinedHeatmapRange): number {
+  return range === '30d' ? 30 : range === '90d' ? 90 : 366;
+}
+
+/** Claude daily aggregates already implement the four-bucket processed formula. */
+export function claudeDailyPointsFromUsage(
+  daily: Readonly<Record<string, DayUsage>>,
+): ProviderDailyPoint[] {
+  return Object.entries(daily)
+    .filter(([dateISO]) => isCalendarDateKey(dateISO))
+    .map(([dateISO, usage]) => ({
+      dateISO,
+      processed: finiteNonNegative(usage.tokens),
+    }));
+}
+
+/**
+ * Codex processed activity is input total + output total. Cached input is
+ * already included in input and reasoning is already included in output, so
+ * neither field is added again. Deliberately recomputing this from the two
+ * source totals protects the combined view from a malformed `processed` field.
+ */
+export function codexDailyPointsFromUsage(
+  rows: readonly CodexDailyProcessedLike[],
+): ProviderDailyPoint[] {
+  return rows
+    .filter((row) => isCalendarDateKey(row.day))
+    .map((row) => ({
+      dateISO: row.day,
+      processed:
+        finiteNonNegative(row.total.input) +
+        finiteNonNegative(row.total.output),
+    }));
+}
+
+function deduplicatePoints(points: readonly ProviderDailyPoint[]): Map<string, number> {
+  const deduplicated = new Map<string, number>();
+  for (const point of points) {
+    if (!isCalendarDateKey(point.dateISO)) {
+      continue;
+    }
+    const processed = finiteNonNegative(point.processed);
+    const previous = deduplicated.get(point.dateISO);
+    if (previous === undefined) {
+      deduplicated.set(point.dateISO, processed);
+      continue;
+    }
+    if (previous !== processed) {
+      throw new Error(`Conflicting duplicate daily aggregate: ${point.dateISO}`);
+    }
+  }
+  return deduplicated;
+}
+
+/**
+ * Merge by configured-timezone date key. Byte-equivalent duplicate provider
+ * rows are idempotent; conflicting duplicates fail closed instead of silently
+ * inflating the share artifact.
+ */
+export function mergeCombinedDailyUsage(
+  claude: readonly ProviderDailyPoint[],
+  codex: readonly ProviderDailyPoint[],
+): Record<string, CombinedDayUsage> {
+  const claudeByDay = deduplicatePoints(claude);
+  const codexByDay = deduplicatePoints(codex);
+  const days = new Set([...claudeByDay.keys(), ...codexByDay.keys()]);
+  return Object.fromEntries(
+    [...days]
+      .sort((left, right) => left.localeCompare(right))
+      .map((dateISO) => {
+        const claudeProcessed = claudeByDay.get(dateISO) ?? 0;
+        const codexProcessed = codexByDay.get(dateISO) ?? 0;
+        return [dateISO, {
+          dateISO,
+          claudeProcessed,
+          codexProcessed,
+          combinedProcessed: claudeProcessed + codexProcessed,
+        } satisfies CombinedDayUsage];
+      }),
+  );
+}
+
+export function selectCombinedHeatmapWindow(
+  daily: Readonly<Record<string, CombinedDayUsage>>,
+  rangeInput: unknown,
+  endDateISO: string,
+): CombinedHeatmapWindow {
+  if (!isCalendarDateKey(endDateISO)) {
+    throw new Error(`Invalid heatmap end date: ${endDateISO}`);
+  }
+  const range = normalizeCombinedHeatmapRange(rangeInput);
+  const startDateISO = addCalendarDays(
+    endDateISO,
+    -(combinedHeatmapRangeDays(range) - 1),
+  );
+  const selected: Record<string, CombinedDayUsage> = {};
+  let claudeProcessed = 0;
+  let codexProcessed = 0;
+  let activeDays = 0;
+  for (const dateISO of Object.keys(daily).sort((left, right) => left.localeCompare(right))) {
+    if (dateISO < startDateISO || dateISO > endDateISO) {
+      continue;
+    }
+    const source = daily[dateISO];
+    const claudeValue = finiteNonNegative(source.claudeProcessed);
+    const codexValue = finiteNonNegative(source.codexProcessed);
+    const combinedProcessed = claudeValue + codexValue;
+    selected[dateISO] = {
+      dateISO,
+      claudeProcessed: claudeValue,
+      codexProcessed: codexValue,
+      combinedProcessed,
+    };
+    claudeProcessed += claudeValue;
+    codexProcessed += codexValue;
+    if (combinedProcessed > 0) {
+      activeDays += 1;
+    }
+  }
+  return {
+    range,
+    startDateISO,
+    endDateISO,
+    daily: selected,
+    totals: {
+      claudeProcessed,
+      codexProcessed,
+      combinedProcessed: claudeProcessed + codexProcessed,
+      activeDays,
+    },
+  };
+}
+
+export function combinedDailyAsHeatmapUsage(
+  daily: Readonly<Record<string, CombinedDayUsage>>,
+): Record<string, DayUsage> {
+  return Object.fromEntries(
+    Object.entries(daily).map(([dateISO, usage]) => [dateISO, {
+      tokens: finiteNonNegative(usage.combinedProcessed),
+      cost: 0,
+      sessions: 0,
+    }]),
+  );
+}
+
+export function sanitizeCombinedHeatmapTitle(value: unknown, fallback: string): string {
+  const cleaned = typeof value === 'string'
+    ? value.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80)
+    : '';
+  return cleaned || fallback;
+}
+
+export function combinedHeatmapFilename(
+  range: CombinedHeatmapRange,
+  endDateISO: string,
+): string {
+  if (!isCalendarDateKey(endDateISO)) {
+    throw new Error(`Invalid heatmap end date: ${endDateISO}`);
+  }
+  return `claude-codex-activity-${range}-${endDateISO}.svg`;
+}
+
+export function combinedHeatmapMarkdown(filename: string, title: string): string {
+  const safeFilename = filename
+    .replace(/[\r\n<>]/g, '')
+    .replace(/\\/g, '/')
+    .replace(/\s/g, '%20');
+  const safeTitle = title.replace(/[\r\n\[\]]/g, ' ').replace(/\s+/g, ' ').trim();
+  return `![${safeTitle || 'Claude and Codex activity'}](${safeFilename})`;
+}
diff --git a/src/combinedHeatmapSvg.ts b/src/combinedHeatmapSvg.ts
new file mode 100644
index 00000000..6ccaf4f2
--- /dev/null
+++ b/src/combinedHeatmapSvg.ts
@@ -0,0 +1,188 @@
+import {
+  CombinedDayUsage,
+  CombinedHeatmapRange,
+  combinedDailyAsHeatmapUsage,
+  selectCombinedHeatmapWindow,
+} from './combinedHeatmap';
+import { renderHeatmapSvg } from './heatmapSvg';
+
+export type CombinedHeatmapPalette =
+  | 'academicViolet'
+  | 'claudeOrange'
+  | 'codexBlue'
+  | 'githubGreen'
+  | 'custom';
+
+export type CombinedHeatmapIntensityMode = 'quantile' | 'logarithmic' | 'linear';
+
+/** The default mirrors Carl's public combined-activity card: a neutral empty
+ * cell plus five active violet bands. */
+export const ACADEMIC_VIOLET_SCALE = [
+  '#ebedf0', '#eee8f8', '#d8c9f1', '#bca5e6', '#8668c7', '#4f2f87',
+];
+
+const EMPTY_CELL_COLOR = '#ebedf0';
+const MIN_ACCENT_CONTRAST = 1.5;
+
+export const COMBINED_ACTIVITY_PALETTES: Record<Exclude<CombinedHeatmapPalette, 'custom'>, string[]> = {
+  academicViolet: ACADEMIC_VIOLET_SCALE,
+  claudeOrange: ['#ebedf0', '#fff1e8', '#fadcc9', '#f0aa82', '#e07d4f', '#c85a2b'],
+  codexBlue: ['#ebedf0', '#eff6ff', '#dbeafe', '#93c5fd', '#3b82f6', '#1d4ed8'],
+  githubGreen: ['#ebedf0', '#dafbe1', '#aceebb', '#6fdd8b', '#2da44e', '#116329'],
+};
+
+/** Compatibility alias for callers that imported the original scale. */
+export const COMBINED_ACTIVITY_SCALE = ACADEMIC_VIOLET_SCALE;
+
+export function normalizeCombinedHeatmapPalette(value: unknown): CombinedHeatmapPalette {
+  return value === 'claudeOrange' || value === 'codexBlue' ||
+    value === 'githubGreen' || value === 'custom'
+    ? value
+    : 'academicViolet';
+}
+
+export function normalizeCombinedHeatmapIntensityMode(value: unknown): CombinedHeatmapIntensityMode {
+  return value === 'logarithmic' || value === 'linear' ? value : 'quantile';
+}
+
+export function normalizeCombinedHeatmapAccent(value: unknown): string {
+  const normalized = typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value.trim())
+    ? value.trim().toLowerCase()
+    : '#4f2f87';
+  const emptyLuminance = relativeLuminance(EMPTY_CELL_COLOR);
+  let channels = hexChannels(normalized);
+  // A near-white custom colour can otherwise make active cells lighter than
+  // the neutral empty cell. Preserve hue while darkening only as much as is
+  // needed to keep the exported intensity direction visually honest.
+  for (let attempt = 0; attempt < 24; attempt++) {
+    const candidate = channelsToHex(channels);
+    const contrast = (emptyLuminance + 0.05) / (relativeLuminance(candidate) + 0.05);
+    if (contrast >= MIN_ACCENT_CONTRAST) {
+      return candidate;
+    }
+    channels = channels.map((channel) => Math.round(channel * 0.88));
+  }
+  return channelsToHex(channels);
+}
+
+function hexChannels(hex: string): number[] {
+  return [1, 3, 5].map((start) => Number.parseInt(hex.slice(start, start + 2), 16));
+}
+
+function channelsToHex(channels: number[]): string {
+  return '#' + channels.map((channel) =>
+    Math.max(0, Math.min(255, Math.round(channel))).toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+function relativeLuminance(hex: string): number {
+  const linear = hexChannels(hex).map((channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+}
+
+function mixFromEmpty(hex: string, accentShare: number): string {
+  const accent = normalizeCombinedHeatmapAccent(hex);
+  const baseChannels = hexChannels(EMPTY_CELL_COLOR);
+  const accentChannels = hexChannels(accent);
+  return channelsToHex(accentChannels.map((channel, index) =>
+    baseChannels[index] * (1 - accentShare) + channel * accentShare,
+  ));
+}
+
+export function customCombinedHeatmapScale(value: unknown): string[] {
+  const accent = normalizeCombinedHeatmapAccent(value);
+  return [
+    EMPTY_CELL_COLOR,
+    mixFromEmpty(accent, 0.12),
+    mixFromEmpty(accent, 0.28),
+    mixFromEmpty(accent, 0.48),
+    mixFromEmpty(accent, 0.72),
+    accent,
+  ];
+}
+
+export interface CombinedHeatmapSvgOptions {
+  range?: CombinedHeatmapRange;
+  endDateISO: string;
+  title?: string;
+  watermark?: string;
+  palette?: CombinedHeatmapPalette | string;
+  customAccent?: string;
+  intensityMode?: CombinedHeatmapIntensityMode | string;
+  labels?: {
+    combined: string;
+    processedTokens: string;
+    footerNote: string;
+  };
+}
+
+function compactNumber(value: number): string {
+  const absolute = Math.abs(value);
+  const format = (scaled: number): string => scaled.toFixed(1).replace(/\.0$/, '');
+  if (absolute >= 1_000_000_000) return `${format(value / 1_000_000_000)}B`;
+  if (absolute >= 1_000_000) return `${format(value / 1_000_000)}M`;
+  if (absolute >= 1_000) return `${format(value / 1_000)}K`;
+  return String(Math.round(value));
+}
+
+/**
+ * Deterministic, privacy-bounded share card. Its input carries date keys and
+ * aggregate provider totals only; it has no account, project, thread, path, or
+ * log-content fields that could accidentally be serialized.
+ */
+export function renderCombinedHeatmapSvg(
+  daily: Readonly<Record<string, CombinedDayUsage>>,
+  options: CombinedHeatmapSvgOptions,
+): string {
+  const window = selectCombinedHeatmapWindow(
+    daily,
+    options.range ?? 'year',
+    options.endDateISO,
+  );
+  const title = options.title ?? 'Claude + Codex local activity';
+  const labels = options.labels ?? {
+    combined: 'Combined',
+    processedTokens: 'processed tokens',
+    footerNote: 'Local activity volume · not productivity, billing, or provider equivalence',
+  };
+  const subtitle = [
+    `Claude ${compactNumber(window.totals.claudeProcessed)}`,
+    `Codex ${compactNumber(window.totals.codexProcessed)}`,
+    `${labels.combined} ${compactNumber(window.totals.combinedProcessed)} ${labels.processedTokens}`,
+  ].join(' · ');
+  const palette = normalizeCombinedHeatmapPalette(options.palette);
+  const scale = palette === 'custom'
+    ? customCombinedHeatmapScale(options.customAccent)
+    : COMBINED_ACTIVITY_PALETTES[palette];
+  return renderHeatmapSvg(combinedDailyAsHeatmapUsage(window.daily), {
+    metric: 'tokens',
+    startDateISO: window.startDateISO,
+    endDateISO: window.endDateISO,
+    title,
+    subtitle,
+    footerNote: labels.footerNote,
+    watermark: options.watermark ?? 'Made with Claude Code Usage',
+    scale,
+    intensityMode: normalizeCombinedHeatmapIntensityMode(options.intensityMode),
+    background: '#fcfaff',
+    primaryText: '#2f2142',
+    secondaryText: '#685a77',
+    borderColor: '#e5dded',
+    accentColor: scale[scale.length - 1],
+    minWidth: 720,
+    ariaLabel: `${title}. ${subtitle}`,
+    tooltip: (dateISO) => {
+      const usage = window.daily[dateISO] ?? {
+        claudeProcessed: 0,
+        codexProcessed: 0,
+        combinedProcessed: 0,
+      };
+      return `${dateISO} · Claude: ${compactNumber(usage.claudeProcessed)} · ` +
+        `Codex: ${compactNumber(usage.codexProcessed)} · ` +
+        `${labels.combined}: ${compactNumber(usage.combinedProcessed)} ${labels.processedTokens}`;
+    },
+  });
+}
diff --git a/src/dataLoader.ts b/src/dataLoader.ts
index 1b82dae0..44f909f8 100644
--- a/src/dataLoader.ts
+++ b/src/dataLoader.ts
@@ -6,7 +6,13 @@ import * as path from 'path';
 // Removed zod dependency - using native validation instead
 import { calculateCostBreakdown, getModelRatesPerMillion } from './pricing';
 import { isRetryDuplicatePrompt } from './promptDedup';
-import { dayKeyInZone, monthKeyInZone } from './dateKeys';
+import {
+  dayKeyInZone,
+  formatHourLabel,
+  hourKeyInZone,
+  monthKeyInZone,
+  rollingDayKeysFromDayKey,
+} from './dateKeys';
 import { I18n } from './i18n';
 import { DayUsage } from './heatmap';
 import { ShareInput, ShareRange, rangeLabel as shareRangeLabel } from './shareCard';
@@ -16,6 +22,7 @@ import {
   UsageManifest,
 } from './claudeUsageFiles';
 import { LoadUsageDiagnostics } from './refreshDiagnostics';
+import { classifyPromptTextOrigin } from './promptOrigin';
 import {
   AttributionEntry,
   AttributionScope,
@@ -24,6 +31,7 @@ import {
   CostlyMessage,
   ContentAnalysis,
   ContextWindowInfo,
+  FrameworkOverheadKind,
   ContentSlice,
   ProjectGroup,
   ProjectUsage,
@@ -101,7 +109,7 @@ export interface AnalysisAcc {
   toolIdToName: Record<string, string>;
   seenUuids: Set<string>;
   cutoffMs: number;
-  prompts: { cwd: string; text: string }[];
+  prompts: { cwd: string; text: string; observedAtEpochMs: number }[];
   // Estimated thinking vs. total assistant-output tokens, per session and per
   // local day ("YYYY-MM-DD") — feeds the thinking-share column / Today line.
   thinkingBySession: Record<string, ThinkingShare>;
@@ -110,6 +118,10 @@ export interface AnalysisAcc {
   // so the matching tool result's size can be attributed to the skill.
   skillUses: SkillUse[];
   skillByToolId: Record<string, number>;
+  frameworkOverhead: Partial<Record<FrameworkOverheadKind, { tokens: number; count: number }>>;
+  observedInputEstimatedTokens: number;
+  userAuthoredEstimatedTokens: number;
+  toolResultEstimatedTokens: number;
 }
 
 // cutoffMs: ignore log lines older than this (0 = no cutoff).
@@ -125,6 +137,10 @@ export function newAnalysisAcc(cutoffMs: number): AnalysisAcc {
     thinkingByDay: {},
     skillUses: [],
     skillByToolId: {},
+    frameworkOverhead: {},
+    observedInputEstimatedTokens: 0,
+    userAuthoredEstimatedTokens: 0,
+    toolResultEstimatedTokens: 0,
   };
 }
 
@@ -153,18 +169,24 @@ function localDayKey(timestamp: unknown): string {
 }
 
 // Collect an actual user prompt (capped + truncated) for the AI-advice feature.
-function collectPrompt(acc: AnalysisAcc, cwd: string, text: string): void {
+function collectPrompt(
+  acc: AnalysisAcc,
+  cwd: string,
+  text: string,
+  observedAtEpochMs: number,
+): void {
   const trimmed = text.trim();
   if (trimmed.length < 4) {
     return;
   }
-  // Agent-framework scaffolding is not something the user typed: interrupt
-  // notices and kebab-case XML-ish wrappers (<command-name>, <system-reminder>,
-  // <local-command-stdout>, …). Plain HTML a user pastes (<div>, <p>) survives.
-  if (/^\[Request interrupted/i.test(trimmed) || /^<[a-z][a-z0-9]*(-[a-z0-9]+)+[\s>/]/i.test(trimmed)) {
-    return;
-  }
-  acc.prompts.push({ cwd, text: trimmed.slice(0, 2500) });
+  // The caller has already applied classifyPromptTextOrigin. Do not repeat a
+  // looser tag heuristic here: unknown custom elements may be user-authored
+  // Web Component examples and must remain eligible for explicit opt-in.
+  acc.prompts.push({
+    cwd,
+    text: trimmed.slice(0, 2500),
+    observedAtEpochMs: Number.isFinite(observedAtEpochMs) ? observedAtEpochMs : 0,
+  });
   if (acc.prompts.length > 600) {
     acc.prompts.shift();
   }
@@ -244,6 +266,42 @@ function addToBucket(map: Record<string, AnalysisBucket>, key: string, text: str
   map[key].count += 1;
 }
 
+function addFrameworkOverhead(
+  acc: AnalysisAcc,
+  kind: FrameworkOverheadKind,
+  tokens: number,
+): void {
+  if (!Number.isFinite(tokens) || tokens < 0) {
+    return;
+  }
+  const current = acc.frameworkOverhead[kind] || { tokens: 0, count: 0 };
+  current.tokens += tokens;
+  current.count += 1;
+  acc.frameworkOverhead[kind] = current;
+}
+
+function trackPromptTextOrigin(
+  parsed: any,
+  acc: AnalysisAcc,
+  text: string,
+  isSubagentFile: boolean,
+): 'user-authored' | FrameworkOverheadKind {
+  const origin = classifyPromptTextOrigin({
+    text,
+    isMeta: parsed.isMeta === true,
+    isSidechain: parsed.isSidechain === true,
+    isSubagentFile,
+  });
+  const tokens = estimateTokens(text);
+  acc.observedInputEstimatedTokens += tokens;
+  if (origin === 'user-authored') {
+    acc.userAuthoredEstimatedTokens += tokens;
+  } else {
+    addFrameworkOverhead(acc, origin, tokens);
+  }
+  return origin;
+}
+
 // Accumulate one raw log line into the content analysis.
 // isSubagentFile: lines from sub-agent / workflow logs still count toward the
 // token-consumption buckets, but their "user" lines are agent-framework task
@@ -354,10 +412,14 @@ export function analyzeLine(parsed: any, acc: AnalysisAcc, isSubagentFile = fals
     // sub-agent logs, meta lines (command echoes) or sidechain dispatches.
     const allowPromptSample = !isSubagentFile && !parsed.isMeta && !parsed.isSidechain;
     if (typeof content === 'string') {
+      const origin = trackPromptTextOrigin(parsed, acc, content, isSubagentFile);
+      // Keep the legacy content-category shape stable for the current UI and
+      // calibration path. The separate numeric overlay above is the only
+      // source for framework-vs-user advice evidence.
       addToBucket(acc.cat, 'userPrompts', content);
       collectCommandUse(acc, content, sessionId, parsed.timestamp);
-      if (allowPromptSample) {
-        collectPrompt(acc, cwd, content);
+      if (allowPromptSample && origin === 'user-authored') {
+        collectPrompt(acc, cwd, content, Date.parse(parsed.timestamp));
       }
     } else if (Array.isArray(content)) {
       for (const block of content) {
@@ -366,19 +428,29 @@ export function analyzeLine(parsed: any, acc: AnalysisAcc, isSubagentFile = fals
         }
         if (block.type === 'tool_result') {
           const text = blockText(block.content);
+          const toolResultTokens = estimateTokens(text);
+          acc.toolResultEstimatedTokens += toolResultTokens;
+          acc.observedInputEstimatedTokens += toolResultTokens + 8;
           addToBucket(acc.cat, 'toolResults', text);
           addToBucket(acc.tools, acc.toolIdToName[block.tool_use_id] || 'unknown', text);
+          // Count only a fixed structural envelope proxy here; the tool-result
+          // body remains in its ordinary consumption bucket and is never
+          // mistaken for user-authored prose.
+          addFrameworkOverhead(acc, 'tool-result-envelope', 8);
           // The injected skill prompt comes back as the Skill tool's result —
           // its size is the best available estimate of the skill's footprint.
           const skillIdx = acc.skillByToolId[block.tool_use_id];
           if (skillIdx !== undefined && acc.skillUses[skillIdx]) {
-            acc.skillUses[skillIdx].estTokens += estimateTokens(text);
+            const skillTokens = estimateTokens(text);
+            acc.skillUses[skillIdx].estTokens += skillTokens;
+            addFrameworkOverhead(acc, 'skill-preamble', skillTokens);
           }
         } else if (block.type === 'text' && typeof block.text === 'string') {
+          const origin = trackPromptTextOrigin(parsed, acc, block.text, isSubagentFile);
           addToBucket(acc.cat, 'userPrompts', block.text);
           collectCommandUse(acc, block.text, sessionId, parsed.timestamp);
-          if (allowPromptSample) {
-            collectPrompt(acc, cwd, block.text);
+          if (allowPromptSample && origin === 'user-authored') {
+            collectPrompt(acc, cwd, block.text, Date.parse(parsed.timestamp));
           }
         }
       }
@@ -393,11 +465,27 @@ export function finalizeAnalysis(acc: AnalysisAcc): ContentAnalysis {
       .sort((a, b) => b.estimatedTokens - a.estimatedTokens);
 
   const categories = toSlices(acc.cat);
+  const frameworkComponents = (Object.entries(acc.frameworkOverhead) as Array<
+    [FrameworkOverheadKind, { tokens: number; count: number }]
+  >)
+    .map(([kind, value]) => ({ kind, estimatedTokens: value.tokens, count: value.count }))
+    .sort((a, b) => a.kind.localeCompare(b.kind));
   return {
     categories,
     toolResultBreakdown: toSlices(acc.tools),
     totalEstimatedTokens: categories.reduce((sum, c) => sum + c.estimatedTokens, 0),
     recentPrompts: acc.prompts.slice(-300),
+    frameworkOverhead: {
+      frameworkEstimatedTokens: frameworkComponents.reduce(
+        (sum, component) => sum + component.estimatedTokens,
+        0,
+      ),
+      observedInputEstimatedTokens: acc.observedInputEstimatedTokens,
+      userAuthoredEstimatedTokens: acc.userAuthoredEstimatedTokens,
+      toolResultEstimatedTokens: acc.toolResultEstimatedTokens,
+      classifiedEvents: frameworkComponents.reduce((sum, component) => sum + component.count, 0),
+      components: frameworkComponents,
+    },
     thinkingBySession: acc.thinkingBySession,
     thinkingByDay: acc.thinkingByDay,
     skillUses: acc.skillUses,
@@ -446,6 +534,17 @@ export function mergeAnalysisAcc(target: AnalysisAcc, source: AnalysisAcc): void
     if (target.skillUses.length >= MAX_SKILL_USES) break;
     target.skillUses.push({ ...use });
   }
+  for (const [kind, value] of Object.entries(source.frameworkOverhead) as Array<
+    [FrameworkOverheadKind, { tokens: number; count: number }]
+  >) {
+    const current = target.frameworkOverhead[kind] ?? { tokens: 0, count: 0 };
+    current.tokens += value.tokens;
+    current.count += value.count;
+    target.frameworkOverhead[kind] = current;
+  }
+  target.observedInputEstimatedTokens += source.observedInputEstimatedTokens;
+  target.userAuthoredEstimatedTokens += source.userAuthoredEstimatedTokens;
+  target.toolResultEstimatedTokens += source.toolResultEstimatedTokens;
 }
 
 export function finalizeAnalysisWithCalibration(
@@ -1033,32 +1132,13 @@ export class ClaudeDataLoader {
     return { sessionId, projectName, projectPath };
   }
 
-  /** True if a `user` line's text is a Claude Code system marker rather than
-   * something the user actually typed: an interruption notice, or the echo of
-   * a slash command (`/model`, `/clear`, …) and its output. These otherwise
-   * inflate the "Messages" count (one session showed 106 vs ~80 real prompts:
-   * `[Request interrupted by user]` ×3, `<command-name>/model…` ×8, etc.). */
+  /** True if a `user` line's text carries one of the reviewed Claude Code
+   * framework markers. Unknown XML/custom elements remain user-authored.
+   *
+   * Keep this public for the existing compatibility tests and callers; the
+   * classifier itself remains the single source of marker semantics. */
   static isSyntheticUserText(text: string): boolean {
-    const t = text.trim();
-    if (/^\[Request interrupted/i.test(t)) {
-      return true;
-    }
-    // Compaction continuation: when a session is auto-compacted, Claude Code
-    // injects the summary as a *user* message — the user never typed it, so it
-    // must not count towards "Messages".
-    if (/^This session is being continued from a previous conversation/i.test(t)) {
-      return true;
-    }
-    // Slash-command echo blocks wrap the invocation/output in these tags.
-    if (
-      t.startsWith('<command-name>') ||
-      t.startsWith('<command-message>') ||
-      t.includes('<local-command-stdout>') ||
-      t.includes('<local-command-caveat>')
-    ) {
-      return true;
-    }
-    return false;
+    return classifyPromptTextOrigin({ text }) !== 'user-authored';
   }
 
   /** Last segment of a path, handling both '/' and '\\' separators. */
@@ -1302,9 +1382,10 @@ export class ClaudeDataLoader {
 
   /** Model context-window size in tokens, plus whether it's a guess. Current
    * Claude (Opus 4.6+, Opus 5+, Sonnet 4.6+, Sonnet 5+, Fable/Mythos 5) is 1M;
-   * Haiku and older Claude are 200K; a "[1m]" suffix forces 1M (the marker
-   * pricing.ts strips). A user override (>0) wins outright and is treated as
-   * exact. Unrecognised / proxied models fall back to 200K and are flagged
+   * GPT-6 Astra is 1.05M; Haiku and older Claude are 200K; a "[1m]" suffix
+   * forces 1M (the marker pricing.ts strips). A user override (>0) wins
+   * outright and is treated as exact. Unrecognised / proxied models fall back
+   * to 200K and are flagged
    * `estimated` so the UI can mark the percentage as approximate.
    * Sonnet 5 (`claude-sonnet-5`) verified 2026-07-01 —
    * https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5
@@ -1337,6 +1418,9 @@ export class ClaudeDataLoader {
     if (/haiku/.test(m) || /opus|sonnet/.test(m)) {
       return { tokens: 200_000, estimated: false };
     }
+    if (/gpt-6-astra/.test(m)) {
+      return { tokens: 1_050_000, estimated: false };
+    }
     if (/deepseek/.test(m)) {
       return { tokens: 128_000, estimated: false };
     }
@@ -1345,13 +1429,11 @@ export class ClaudeDataLoader {
   }
 
   static getTodayData(records: ClaudeUsageRecord[]): UsageData {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-
-    const todayRecords = records.filter((record) => {
-      const recordDate = new Date(record.timestamp);
-      return recordDate >= today;
-    });
+    const tz = I18n.getTimezone();
+    const today = dayKeyInZone(new Date(), tz);
+    const todayRecords = records.filter((record) =>
+      dayKeyInZone(new Date(record.timestamp), tz) === today
+    );
 
     return this.calculateUsageData(todayRecords);
   }
@@ -2072,7 +2154,8 @@ export class ClaudeDataLoader {
   static buildShareInput(
     records: ClaudeUsageRecord[],
     range: ShareRange,
-    scope: string = 'all'
+    scope: string = 'all',
+    now: Date = new Date(),
   ): ShareInput {
     const tz = I18n.getTimezone();
 
@@ -2091,22 +2174,17 @@ export class ClaudeDataLoader {
     // Range filter.
     let inRange: ClaudeUsageRecord[];
     if (range === 'today') {
-      const todayKey = dayKeyInZone(new Date(), tz);
+      const todayKey = dayKeyInZone(now, tz);
       inRange = scoped.filter((r) => dayKeyInZone(new Date(r.timestamp), tz) === todayKey);
-    } else if (range === 'week') {
-      const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
-      inRange = scoped.filter((r) => new Date(r.timestamp).getTime() >= cutoff);
-    } else if (range === 'last30') {
-      const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
-      inRange = scoped.filter((r) => new Date(r.timestamp).getTime() >= cutoff);
-    } else if (range === 'year') {
-      const cutoff = Date.now() - 365 * 24 * 60 * 60 * 1000;
-      inRange = scoped.filter((r) => new Date(r.timestamp).getTime() >= cutoff);
+    } else if (range === 'week' || range === 'last30' || range === 'year') {
+      const dayCount = range === 'week' ? 7 : range === 'last30' ? 30 : 365;
+      const dayKeys = new Set(rollingDayKeysFromDayKey(dayKeyInZone(now, tz), dayCount));
+      inRange = scoped.filter((r) => dayKeys.has(dayKeyInZone(new Date(r.timestamp), tz)));
     } else if (range.startsWith('month:')) {
       const monthKey = range.slice('month:'.length); // 'YYYY-MM'
       inRange = scoped.filter((r) => monthKeyInZone(new Date(r.timestamp), tz) === monthKey);
     } else {
-      const monthKey = monthKeyInZone(new Date(), tz);
+      const monthKey = monthKeyInZone(now, tz);
       inRange = scoped.filter((r) => monthKeyInZone(new Date(r.timestamp), tz) === monthKey);
     }
 
@@ -2458,15 +2536,16 @@ export class ClaudeDataLoader {
   static getUsageAttribution(
     records: ClaudeUsageRecord[],
     analysis: ContentAnalysis | null,
-    scope: AttributionScope
+    scope: AttributionScope,
+    now: Date = new Date(),
   ): UsageAttribution {
-    const now = new Date();
-    const startOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
-    const minTs =
-      scope.kind === 'day' ? startOfDay
-      : scope.kind === 'week' ? now.getTime() - 7 * 24 * 60 * 60 * 1000
-      : scope.kind === 'month' ? now.getTime() - 30 * 24 * 60 * 60 * 1000
-      : 0;
+    const timeZone = I18n.getTimezone();
+    const configuredToday = dayKeyInZone(now, timeZone);
+    const scopeDayKeys =
+      scope.kind === 'day' ? new Set([configuredToday])
+      : scope.kind === 'week' ? new Set(rollingDayKeysFromDayKey(configuredToday, 7))
+      : scope.kind === 'month' ? new Set(rollingDayKeysFromDayKey(configuredToday, 30))
+      : undefined;
     const normScope = scope.projectPath ? this.normalizePath(scope.projectPath) : '';
 
     const scoped = records.filter((r) => {
@@ -2480,7 +2559,10 @@ export class ClaudeDataLoader {
         return this.normalizePath(r._projectPath || '').startsWith(normScope);
       }
       const t = Date.parse(r.timestamp);
-      return !isNaN(t) && t >= minTs;
+      if (isNaN(t)) {
+        return false;
+      }
+      return scopeDayKeys?.has(dayKeyInZone(new Date(t), timeZone)) ?? true;
     });
 
     // Skill / plugin activation points. A skill's usage share is the weight
@@ -2502,9 +2584,12 @@ export class ClaudeDataLoader {
         const sessionIds = new Set(scoped.map((r) => r._sessionId));
         uses = uses.filter((u) => sessionIds.has(u.sessionId));
       } else {
-        // "YYYY-MM-DD" compares correctly as a string.
-        const minDay = localDayKey(new Date(minTs).toISOString());
-        uses = uses.filter((u) => u.day >= minDay);
+        uses = uses.filter((u) => {
+          const currentZoneDay = u.ts > 0 && Number.isFinite(u.ts)
+            ? dayKeyInZone(new Date(u.ts), timeZone)
+            : u.day;
+          return scopeDayKeys?.has(currentZoneDay) === true;
+        });
       }
       // key → session → earliest invocation ts (skills and plugins separately)
       const skillEarliest: Record<string, Record<string, number>> = {};
@@ -2982,20 +3067,21 @@ export class ClaudeDataLoader {
   }
 
   static getHourlyDataForToday(records: ClaudeUsageRecord[]): { hour: string; data: UsageData }[] {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-
-    const todayRecords = records.filter((record) => {
-      const recordDate = new Date(record.timestamp);
-      return recordDate >= today;
-    });
+    const tz = I18n.getTimezone();
+    const today = dayKeyInZone(new Date(), tz);
+    const todayRecords = records.filter((record) =>
+      dayKeyInZone(new Date(record.timestamp), tz) === today
+    );
 
     // Group records by hour
     const recordsByHour: Record<string, ClaudeUsageRecord[]> = {};
 
     todayRecords.forEach((record) => {
       const recordDate = new Date(record.timestamp);
-      const hourKey = `${recordDate.getHours().toString().padStart(2, '0')}:00`; // HH:00 format
+      const hourKey = formatHourLabel(hourKeyInZone(recordDate, tz));
+      if (!hourKey) {
+        return;
+      }
 
       if (!recordsByHour[hourKey]) {
         recordsByHour[hourKey] = [];
@@ -3015,23 +3101,20 @@ export class ClaudeDataLoader {
   }
 
   static getHourlyDataForDate(records: ClaudeUsageRecord[], dateString: string): { hour: string; data: UsageData }[] {
-    const targetDate = new Date(dateString);
-    targetDate.setHours(0, 0, 0, 0);
-
-    const nextDate = new Date(targetDate);
-    nextDate.setDate(nextDate.getDate() + 1);
-
-    const dateRecords = records.filter((record) => {
-      const recordDate = new Date(record.timestamp);
-      return recordDate >= targetDate && recordDate < nextDate;
-    });
+    const tz = I18n.getTimezone();
+    const dateRecords = records.filter((record) =>
+      dayKeyInZone(new Date(record.timestamp), tz) === dateString
+    );
 
     // Group records by hour
     const recordsByHour: Record<string, ClaudeUsageRecord[]> = {};
 
     dateRecords.forEach((record) => {
       const recordDate = new Date(record.timestamp);
-      const hourKey = `${recordDate.getHours().toString().padStart(2, '0')}:00`; // HH:00 format
+      const hourKey = formatHourLabel(hourKeyInZone(recordDate, tz));
+      if (!hourKey) {
+        return;
+      }
 
       if (!recordsByHour[hourKey]) {
         recordsByHour[hourKey] = [];
diff --git a/src/dateKeys.ts b/src/dateKeys.ts
index 8b3ac0f5..f4d01a0f 100644
--- a/src/dateKeys.ts
+++ b/src/dateKeys.ts
@@ -55,6 +55,11 @@ export function hourKeyInZone(date: Date, timeZone: string): string {
     ?.value ?? '';
 }
 
+/** Provider-neutral display label for a validated "00" through "23" hour key. */
+export function formatHourLabel(hour: string): string {
+  return /^(?:[01]\d|2[0-3])$/.test(hour) ? `${hour}:00` : '';
+}
+
 /**
  * Calendar-day keys ending on `now` in `timeZone`, ordered from oldest to newest.
  * The range walks civil dates rather than subtracting fixed-duration milliseconds.
diff --git a/src/extension.ts b/src/extension.ts
index d878cbb8..103043dc 100644
--- a/src/extension.ts
+++ b/src/extension.ts
@@ -17,25 +17,46 @@ import {
 import { StatusBarManager } from './statusBar';
 import { UsageWebviewProvider } from './webview';
 import { I18n } from './i18n';
-import { resolveTimeZone } from './dateKeys';
-import { fetchLatestPricing } from './pricing';
+import { dayKeyInZone, resolveTimeZone } from './dateKeys';
+import {
+  GITHUB_PUBLIC_REPO_SCOPE,
+  createGitHubPublishPlan,
+  githubPublishConfirmationDetail,
+  probePublicGitHubPublishTarget,
+  publishPublicGitHubFile,
+} from './githubHeatmapPublish';
+import { fetchLatestPricing, setPricingBackend } from './pricing';
 import { ClaudeApiClient } from './claudeApiClient';
 import {
   buildOptimizerSystemPrompt,
-  callModel,
-  getUsageAdvice,
-  parseOptimizerOutput
 } from './advisor';
-import { buildAdviceSummary } from './adviceSummary';
-import { getDemoBody } from './adviceDemoSample';
 import { ClaudeApiUsageResponse, ContentAnalysis, ExtensionConfig } from './types';
-import { SettingsStore } from './settings';
+import {
+  KNOWN_CONFIGURATION_SETTING_KEYS,
+  OWNED_SETTING_GLOBAL_STATE_KEYS,
+  REGISTERED_CONFIGURATION_SETTING_KEYS,
+  SettingsLocalDataClearError,
+  SettingsSecretMigrationError,
+  SettingsStore,
+} from './settings';
 import { normalizeQuotaWindows } from './quotaWindows';
 import {
-  appendWeeklyQuotaObservations,
-  claudeWeeklyQuotaObservations,
   WeeklyQuotaObservation,
 } from './weeklyValue';
+import {
+  claudeQuotaCapturesFromUsage,
+  codexQuotaCapturesFromWeeklyObservations,
+  createEmptyQuotaObservationStore,
+  fingerprintForStableIdentity,
+  loadQuotaObservationStore,
+  mergeQuotaCaptures,
+  QUOTA_OBSERVATION_FILE,
+  QuotaCapture,
+  QuotaObservationRepository,
+  QuotaObservationScopedClearBlockedError,
+  QuotaObservationStoreV2,
+  quotaStoreWeeklyObservations,
+} from './quotaObservationStore';
 import {
   diffUsageManifests,
   scanUsageManifest,
@@ -63,7 +84,12 @@ import {
   CodexProvider,
   CodexProviderSnapshot,
 } from './providers/codex/codexProvider';
-import { CodexIndexProgress } from './providers/codex/codexIndex';
+import {
+  CodexIndexProgress,
+  loadCodexIndex,
+} from './providers/codex/codexIndex';
+import { acquireCodexIndexLease } from './providers/codex/codexIndexLease';
+import { weeklyQuotaObservationsFromCodexHistory } from './providers/codex/codexQuotaHistory';
 import { resolveCodexHome } from './providers/codex/codexManifest';
 import { buildCodexUsageView, CodexUsageView } from './providers/codex/codexUsage';
 import {
@@ -76,12 +102,249 @@ import {
   latestAnnouncementVersion,
   ReleaseAnnouncementCatalog,
 } from './releaseAnnouncements';
+import {
+  adaptClaudeAdvice,
+  adaptCodexLocalAdvice,
+} from './adviceEffectiveness/adapters';
+import {
+  AdviceEffectivenessProviderStates,
+  selectAdvicePromptSamples,
+} from './adviceEffectiveness/integration';
+import { buildAdviceAggregateSnapshot } from './adviceEffectiveness/payload';
+import {
+  prepareStructuredAdviceInvocation,
+  requestStructuredAdvice,
+} from './adviceEffectiveness/remoteAdvice';
+import {
+  prepareOptimizerInvocation,
+  requestPreparedOptimizer,
+} from './optimizerRequest';
+import {
+  BackgroundWorkReason,
+  BackgroundWorkState,
+  beginBackgroundWork,
+  createBackgroundWorkState,
+  interruptBackgroundWork,
+  recordBackgroundWorkFailure,
+  recordBackgroundWorkProgress,
+  restoreBackgroundWorkState,
+} from './backgroundWorkState';
+import {
+  ResourceLease,
+  ResourceOwnershipRegistry,
+  ResourceStopCondition,
+} from './resourceOwnership';
+import {
+  LOCAL_DATA_ACTION_TARGETS,
+  LOCAL_DATA_GLOBAL_STATE_KEYS,
+  LOCAL_DATA_GLOBAL_STATE_PREFIXES,
+  LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+  LOCAL_DATA_SOURCE_EXCLUSIONS,
+  LEGACY_ADVICE_LOCAL_STATE_KEYS,
+  LocalDataAction,
+  LocalDataActionResult,
+  LocalDataClientAction,
+  LocalDataClientSummary,
+  LocalDataInventory,
+  LocalDataInventoryRow,
+  LocalDataQuotaScopeOption,
+  ResolvedQuotaScope,
+  approximateJsonBytes,
+  finiteTimestampRange,
+  groupQuotaAccountEpochs,
+  localDataActionTitle,
+} from './localDataControls';
 
 interface LocalizedReleaseAnnouncement {
   version: string;
   body: () => string;
 }
 
+interface ActiveNetworkOperation {
+  readonly lease: ResourceLease;
+  /** Resolves only after the request promise has reached its own terminal path. */
+  readonly settled: Promise<void>;
+}
+
+interface QuotaObservationRuntime {
+  repository: QuotaObservationRepository;
+  store: QuotaObservationStoreV2;
+  salt: string;
+}
+
+const QUOTA_FINGERPRINT_SALT_KEY = 'ccu.quota.fingerprintSalt.v1';
+const QUOTA_P5_MIGRATION_KEY = 'ccu.quota.migratedCodexIndex.v2';
+const LEGACY_QUOTA_PREFIX = 'ccu.usageLimits.';
+const LEGACY_WEEKLY_PREFIX = 'ccu.weeklyQuotaHistory.v1.';
+const LOCAL_DATA_QUOTA_SCOPE_TTL_MS = 5 * 60_000;
+const LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS = [
+  ...new Set([
+    ...LOCAL_DATA_GLOBAL_STATE_KEYS,
+    ...OWNED_SETTING_GLOBAL_STATE_KEYS,
+  ]),
+] as const;
+
+class QuotaObservationScopedMigrationBlockedError extends Error {
+  constructor() {
+    super('quota-observation-clear:scoped-clear-blocked-by-unresolved-migration');
+    this.name = 'QuotaObservationScopedMigrationBlockedError';
+  }
+}
+
+function legacyProfileSuffix(credentialsPath: string): string {
+  return createHash('sha256').update(credentialsPath).digest('hex').slice(0, 16);
+}
+
+function objectRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function legacyWeeklyCaptures(
+  value: unknown,
+  identitySignal: string,
+): QuotaCapture[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const item = objectRecord(entry);
+    if (
+      !item ||
+      item.provider !== 'claude' ||
+      typeof item.observedAt !== 'number' ||
+      !Number.isFinite(item.observedAt) ||
+      typeof item.resetAt !== 'number' ||
+      !Number.isFinite(item.resetAt) ||
+      typeof item.usedPercent !== 'number' ||
+      !Number.isFinite(item.usedPercent)
+    ) return [];
+    return [{
+      provider: 'claude' as const,
+      stableIdentitySignal: identitySignal,
+      accountAttribution: 'profile-continuity' as const,
+      observedAt: item.observedAt,
+      periodType: 'seven-day' as const,
+      usedFraction: Math.max(0, Math.min(1, item.usedPercent / 100)),
+      resetAt: item.resetAt,
+      source: 'claude-official-api' as const,
+      confidence: 'low' as const,
+      captureReason: 'migration' as const,
+      flags: ['account-ambiguous' as const],
+    }];
+  });
+}
+
+/** Load and transactionally migrate quota facts before any provider refresh
+ * starts. Legacy values are removed only after the schema-2 file is durable. */
+export async function initializeQuotaObservationRuntime(
+  context: vscode.ExtensionContext,
+  settings: SettingsStore,
+): Promise<QuotaObservationRuntime> {
+  let salt = context.globalState.get<string>(QUOTA_FINGERPRINT_SALT_KEY);
+  if (!salt) {
+    salt = randomBytes(32).toString('hex');
+    await context.globalState.update(QUOTA_FINGERPRINT_SALT_KEY, salt);
+  }
+  const repository = new QuotaObservationRepository(
+    path.join(context.globalStorageUri.fsPath, QUOTA_OBSERVATION_FILE),
+    salt,
+  );
+  let store = await repository.load();
+  const migrationCaptures: QuotaCapture[] = [];
+  const removableLegacyKeys: string[] = [];
+  let codexLegacyMigrationReady = context.globalState.get<boolean>(
+    QUOTA_P5_MIGRATION_KEY,
+  ) === true;
+  const profileClient = new ClaudeApiClient(
+    null,
+    settings.get<string>('dataDirectory'),
+    salt,
+  );
+  const currentCredentialsPath = profileClient.getCredentialsPath();
+  const currentSuffix = legacyProfileSuffix(currentCredentialsPath);
+  const keys = typeof context.globalState.keys === 'function'
+    ? context.globalState.keys()
+    : [];
+  for (const key of keys) {
+    if (key.startsWith(LEGACY_QUOTA_PREFIX)) {
+      const suffix = key.slice(LEGACY_QUOTA_PREFIX.length);
+      const saved = objectRecord(context.globalState.get<unknown>(key));
+      const data = saved ? saved.data as ClaudeApiUsageResponse | undefined : undefined;
+      const ts = saved?.ts;
+      if (data && typeof ts === 'number' && Number.isFinite(ts) && ts > 0) {
+        const identitySignal = suffix === currentSuffix
+          ? `profile-path-v1|${currentCredentialsPath}`
+          : `legacy-profile-v1|${suffix}`;
+        const additions = claudeQuotaCapturesFromUsage(
+          data,
+          identitySignal,
+          'profile-continuity',
+          ts,
+          'migration',
+        );
+        if (additions.length > 0) {
+          migrationCaptures.push(...additions.map((item) => ({
+            ...item,
+            confidence: 'low' as const,
+            flags: [...(item.flags ?? []), 'account-ambiguous' as const],
+          })));
+          removableLegacyKeys.push(key);
+        }
+      }
+      continue;
+    }
+    if (key.startsWith(LEGACY_WEEKLY_PREFIX)) {
+      const suffix = key.slice(LEGACY_WEEKLY_PREFIX.length);
+      const identitySignal = suffix === currentSuffix
+        ? `profile-path-v1|${currentCredentialsPath}`
+        : `legacy-profile-v1|${suffix}`;
+      const additions = legacyWeeklyCaptures(
+        context.globalState.get<unknown>(key),
+        identitySignal,
+      );
+      if (additions.length > 0) {
+        migrationCaptures.push(...additions);
+        removableLegacyKeys.push(key);
+      }
+    }
+  }
+
+  if (!codexLegacyMigrationReady) {
+    try {
+      const index = await loadCodexIndex(
+        path.join(context.globalStorageUri.fsPath, 'codex-index-v1.json'),
+        resolveTimeZone(settings.get<string>('timezone')),
+      );
+      const legacyHistory = [
+        ...(index.quotaHistory ?? []),
+        ...Object.values(index.files).flatMap((file) => file.quotaHistory ?? []),
+      ];
+      migrationCaptures.push(...codexQuotaCapturesFromWeeklyObservations(
+        weeklyQuotaObservationsFromCodexHistory(legacyHistory),
+        'migration',
+      ));
+      codexLegacyMigrationReady = true;
+      // Set only after the P2 append below succeeds.
+    } catch {
+      // A corrupt/absent P1 cannot block activation or destroy its only copy.
+    }
+  }
+
+  if (migrationCaptures.length > 0) {
+    store = await repository.append(migrationCaptures);
+  }
+  for (const key of removableLegacyKeys) {
+    await context.globalState.update(key, undefined);
+  }
+  if (
+    codexLegacyMigrationReady &&
+    !context.globalState.get<boolean>(QUOTA_P5_MIGRATION_KEY)
+  ) {
+    await context.globalState.update(QUOTA_P5_MIGRATION_KEY, true);
+  }
+  return { repository, store, salt };
+}
+
 // Full-version entries only: an installed patch must never inherit stale notes
 // from an older major/minor release.
 const WHATS_NEW: ReleaseAnnouncementCatalog<LocalizedReleaseAnnouncement> = {
@@ -89,19 +352,31 @@ const WHATS_NEW: ReleaseAnnouncementCatalog<LocalizedReleaseAnnouncement> = {
     version: '2.3.0',
     body: () => I18n.t.releaseAnnouncement.v230,
   },
+  '2.3.1': {
+    version: '2.3.1',
+    body: () => I18n.t.releaseAnnouncement.v231,
+  },
 };
 
 export class ClaudeCodeUsageExtension {
+  private static readonly CODEX_BACKGROUND_WORK_STATE_KEY =
+    'ccu.codex.backgroundWork.v1';
+  private static readonly CODEX_BACKGROUND_MEASUREMENT_VERSION = 1;
+  private static readonly CODEX_FIRST_BACKFILL_BLUR_DEADLINE_MS = 10_000;
   private statusBar: StatusBarManager;
   private webviewProvider: UsageWebviewProvider;
   private apiClient: ClaudeApiClient;
   private settings: SettingsStore;
   private refreshTimer: NodeJS.Timeout | undefined;
+  private refreshTimerLease: ResourceLease | undefined;
   private fileWatcher: fs.FSWatcher | undefined;
+  private fileWatcherLease: ResourceLease | undefined;
   private codexWatchers: fs.FSWatcher[] = [];
-  private readonly codexWatchDebounce = new QuietDebounce();
+  private readonly codexWatcherLeases = new Map<fs.FSWatcher, ResourceLease>();
+  private readonly debounceTimerLeases = new Map<NodeJS.Timeout, ResourceLease>();
+  private readonly codexWatchDebounce = this.createOwnedRefreshDebounce('codex');
   private codexWatchedHome: string | null = null;
-  private readonly watchDebounce = new QuietDebounce();
+  private readonly watchDebounce = this.createOwnedRefreshDebounce('claude');
   private readonly refreshGate = new RefreshSingleFlight();
   private readonly windowActivity =
     new WindowActivityGate(vscode.window.state.focused);
@@ -111,7 +386,9 @@ export class ClaudeCodeUsageExtension {
   // Watches ~/.claude/.credentials.json so an account switch is reflected
   // promptly instead of after a full quota TTL (#45).
   private credsWatcher: fs.FSWatcher | undefined;
+  private credsWatcherLease: ResourceLease | undefined;
   private credsDebounceTimer: NodeJS.Timeout | undefined;
+  private credsDebounceTimerLease: ResourceLease | undefined;
   private cache: {
     records: any[];
     contentAnalysis: ContentAnalysis | null;
@@ -148,8 +425,15 @@ export class ClaudeCodeUsageExtension {
   // flaky network and the very first /usage fetch fails, try once more shortly
   // after so the indicator appears without waiting for the next regular tick.
   private quotaColdRetryDone: boolean = false;
+  private quotaColdRetryTimer: NodeJS.Timeout | undefined;
+  private quotaColdRetryTimerLease: ResourceLease | undefined;
   private claudeProfileGeneration: number = 0;
   private claudeWeeklyQuotaHistory: WeeklyQuotaObservation[] = [];
+  private readonly quotaObservationRepository: QuotaObservationRepository;
+  private quotaObservationStore: QuotaObservationStoreV2;
+  private readonly quotaFingerprintSalt: string;
+  private activeClaudeQuotaFingerprint: string | undefined;
+  private activePricingBackend: ExtensionConfig['pricingBackend'] = 'anthropic';
   private codexProvider: CodexProvider;
   private readonly codexSalt: string;
   private codexView: CodexUsageView | null = null;
@@ -161,49 +445,224 @@ export class ClaudeCodeUsageExtension {
   private codexProgressLastRenderedAt = 0;
   private codexCheckpointHydration: Promise<void> | null = null;
   private codexCheckpointHydrationLastAttemptAt = 0;
+  private codexBackgroundState: BackgroundWorkState;
+  private readonly resourceOwnership = new ResourceOwnershipRegistry();
+  private codexBackfillLease: ResourceLease | undefined;
+  private codexWorkerLease: ResourceLease | undefined;
+  private codexFirstBackfillActive = false;
+  private codexFirstBackfillBlurTimer: NodeJS.Timeout | undefined;
+  private codexFirstBackfillBlurTimerLease: ResourceLease | undefined;
+  private codexWorkerCancellationRequested = false;
+  private readonly activeAdviceNetworks = new Map<
+    AbortController,
+    ActiveNetworkOperation & { surface: 'advice' | 'optimizer' }
+  >();
+  private readonly activeQuotaNetworks = new Map<AbortController, ActiveNetworkOperation>();
+  private readonly codexProviderRetirements = new Set<Promise<void>>();
+  private codexProviderRetirementFailure: unknown = null;
+  private readonly activeCodexRefreshes = new Set<Promise<void>>();
+  private readonly pendingResourceStops = new Set<Promise<void>>();
+  private resourceStopFailure: unknown = null;
+  private codexBackgroundStateWrite: Promise<void> = Promise.resolve();
+  private initializationWrites: Promise<void> = Promise.resolve();
+  private initializationWriteFailure: unknown = null;
+  private localDataActionWrite: Promise<void> = Promise.resolve();
+  private pendingClientResetReplay: Promise<void> = Promise.resolve();
+  private clearingAllLocalData = false;
+  private localDataClearedRequiresReload = false;
+  private readonly localDataQuotaScopes = new Map<
+    string,
+    {
+      scope: ResolvedQuotaScope;
+      label: string;
+      createdAt: number;
+      revision: string;
+    }
+  >();
+  private configurationGeneration = 0;
+  private fileWatcherGeneration = 0;
+  private codexWatcherGeneration = 0;
+  private credentialsWatcherGeneration = 0;
+  private disposed = false;
+  private disposal: Promise<void> | null = null;
 
-  constructor(private context: vscode.ExtensionContext) {
+  constructor(
+    private context: vscode.ExtensionContext,
+    settings?: SettingsStore,
+    quotaRuntime?: QuotaObservationRuntime,
+  ) {
     console.log('Claude Code Usage Extension: Constructor called');
     this.outputChannel = vscode.window.createOutputChannel('Claude Code Usage');
     context.subscriptions.push(this.outputChannel);
     this.statusBar = new StatusBarManager();
-    this.settings = new SettingsStore(context);
+    this.settings = settings ?? new SettingsStore(context);
+    const backgroundRestore = restoreBackgroundWorkState(
+      context.globalState.get<unknown>(
+        ClaudeCodeUsageExtension.CODEX_BACKGROUND_WORK_STATE_KEY,
+      ),
+      {
+        measurementVersion:
+          ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+        reason: 'history-backfill',
+        now: Date.now(),
+      },
+    );
+    this.codexBackgroundState = backgroundRestore.state;
+    if (this.codexBackgroundState.status === 'running') {
+      this.codexBackgroundState = interruptBackgroundWork(
+        this.codexBackgroundState,
+        { now: Date.now() },
+      );
+    }
+    if (
+      backgroundRestore.disposition !== 'valid' ||
+      backgroundRestore.state.status === 'running'
+    ) {
+      this.queueInitializationWrite(() => this.saveCodexBackgroundState());
+    }
     this.webviewProvider = new UsageWebviewProvider(context);
+    const existingQuotaSalt = context.globalState.get<string>(
+      'ccu.quota.fingerprintSalt.v1',
+    );
+    this.quotaFingerprintSalt = quotaRuntime?.salt ??
+      existingQuotaSalt ?? randomBytes(32).toString('hex');
+    if (!existingQuotaSalt && !quotaRuntime) {
+      this.queueInitializationWrite(() => context.globalState.update(
+        'ccu.quota.fingerprintSalt.v1',
+        this.quotaFingerprintSalt,
+      ));
+    }
+    this.quotaObservationRepository = quotaRuntime?.repository ??
+      new QuotaObservationRepository(
+        path.join(context.globalStorageUri.fsPath, QUOTA_OBSERVATION_FILE),
+        this.quotaFingerprintSalt,
+      );
+    this.quotaObservationStore = quotaRuntime?.store ??
+      createEmptyQuotaObservationStore();
     this.apiClient = new ClaudeApiClient(
       this.outputChannel,
       this.settings.get<string>('dataDirectory'),
+      this.quotaFingerprintSalt,
+    );
+    this.activeClaudeQuotaFingerprint = fingerprintForStableIdentity(
+      this.quotaFingerprintSalt,
+      'claude',
+      this.claudeProfileContinuitySignal(),
     );
     const existingCodexSalt = context.globalState.get<string>('ccu.codex.machineSalt');
     this.codexSalt = existingCodexSalt ?? randomBytes(32).toString('hex');
     if (!existingCodexSalt) {
-      void context.globalState.update('ccu.codex.machineSalt', this.codexSalt);
+      this.queueInitializationWrite(() =>
+        context.globalState.update('ccu.codex.machineSalt', this.codexSalt),
+      );
     }
     this.codexProvider = this.createCodexProvider(this.getConfiguration());
     // Migrate any pre-2.1 settings.json values for the keys that have moved out
     // of the VS Code Settings UI into the dashboard-managed store. Runs once.
-    void this.settings.migrateOnce();
+    this.queueInitializationWrite(() => this.settings.migrateOnce());
     // V2.2: convert the old pauseDashboardRefresh to the positive
     // dashboardAutoRefresh (inverted). Runs once.
-    void this.settings.migrateDashboardAutoRefresh();
+    this.queueInitializationWrite(() => this.settings.migrateDashboardAutoRefresh());
     // Rename showOpusWeekly -> showScopedWeekly (the API stopped naming Opus).
     // Runs once.
-    void this.settings.migrateScopedWeekly();
+    this.queueInitializationWrite(() => this.settings.migrateScopedWeekly());
     // Usage Optimizer (Phase 9c): the webview posts a draft prompt; we run it
     // through the same model backend as the advice feature and post back a
     // tightened prompt + a settings recommendation. Consent gate lives here.
-    this.webviewProvider.onOptimize = (draft, options) => this.runOptimizer(draft, options);
+    this.webviewProvider.onPrepareOptimizerInvocation = (
+      draft,
+      options,
+      sourceRevision,
+      consentGeneration,
+    ) => this.prepareOptimizerRequest(
+      draft,
+      options,
+      sourceRevision,
+      consentGeneration,
+    );
+    this.webviewProvider.onSendOptimizerInvocation = (
+      prepared,
+      expectedSourceRevision,
+      expectedConsentGeneration,
+    ) => {
+      const config = this.getConfiguration();
+      return this.runAdviceNetwork((signal) =>
+        requestPreparedOptimizer(prepared, {
+          apiKey: config.adviceApiKey,
+          expectedSourceRevision,
+          expectedConsentGeneration,
+          signal,
+        }),
+        'optimizer',
+      );
+    };
+    this.webviewProvider.onAiSurfaceClosed = () => {
+      void this.cancelAdviceNetworks('cancelled');
+    };
+    this.webviewProvider.onAdviceDataCleared = () =>
+      this.cancelAdviceNetworks('cancelled');
+    this.webviewProvider.onAdviceConsentWithdrawn = () =>
+      this.cancelAdviceNetworks('cancelled', 'advice');
+    this.webviewProvider.onPrepareAdviceInvocation = (
+      snapshot,
+      sourceRevision,
+      consentGeneration,
+    ) => {
+      const config = this.getConfiguration();
+      return prepareStructuredAdviceInvocation(snapshot.prepared, {
+        apiFormat: config.adviceApiFormat,
+        apiUrl: config.adviceApiUrl,
+        model: config.adviceModel,
+        reasoningEffort: config.adviceReasoningEffort,
+        sourceRevision,
+        consentGeneration,
+        createdAtEpochMs: Date.now(),
+      });
+    };
+    this.webviewProvider.onSendAdviceInvocation = (
+      prepared,
+      references,
+      expectedSourceRevision,
+      expectedConsentGeneration,
+    ) => {
+      const config = this.getConfiguration();
+      return this.runAdviceNetwork((signal) =>
+        requestStructuredAdvice(prepared, references, {
+          apiKey: config.adviceApiKey,
+          expectedSourceRevision,
+          expectedConsentGeneration,
+          signal,
+        }),
+      );
+    };
     // Share the settings store with the dashboard's ⚙ Settings panel, and have
     // it tell us when the user changes a setting there so we re-apply config
     // (globalState changes don't fire onDidChangeConfiguration).
     this.webviewProvider.settings = this.settings;
     this.webviewProvider.onSettingsChanged = (key) => this.onSettingsChangedFromPanel(key);
+    this.webviewProvider.onRequestLocalDataInventory = (client) =>
+      this.buildLocalDataInventory(client);
+    this.webviewProvider.onRunLocalDataAction = (action, quotaScopeToken) =>
+      this.runLocalDataActionInteractive(action, quotaScopeToken);
+    this.webviewProvider.onResetSharingPreferences = () =>
+      this.resetSharingPreferencesHost();
+    this.webviewProvider.onLocalDataClientReady = () => {
+      void this.replayPendingClientReset();
+    };
 
     this.setupCommands();
     this.loadConfiguration();
-    this.loadPersistedQuota();
+    this.refreshQuotaObservationViews();
     if (this.windowActivity.focused) {
       this.startAutoRefresh();
+      const startupGeneration = this.configurationGeneration;
       void this.refreshData(false, 'startup').then(() => {
+        if (
+          this.disposed ||
+          startupGeneration !== this.configurationGeneration
+        ) {
+          return;
+        }
         void this.startFileWatching();
         this.startCodexWatching();
       });
@@ -214,6 +673,30 @@ export class ClaudeCodeUsageExtension {
     console.log('Claude Code Usage Extension: Initialization complete');
   }
 
+  private queueInitializationWrite(
+    operation: () => PromiseLike<void>,
+  ): void {
+    const run = this.initializationWrites
+      .catch(() => undefined)
+      .then(async () => {
+        if (this.disposed || this.localDataClearedRequiresReload) return;
+        await operation();
+      });
+    this.initializationWrites = run.catch((error) => {
+      this.initializationWriteFailure ??= error;
+    });
+  }
+
+  private async drainInitializationWritesForClear(): Promise<void> {
+    await this.initializationWrites;
+    // An initialization failure is non-fatal for normal activation, but a
+    // destructive clear cannot claim a verified postcondition while an owned
+    // initialization write failed or remains unknown.
+    if (this.initializationWriteFailure !== null) {
+      throw new Error('initialization-write-barrier-failed');
+    }
+  }
+
   /** After an upgrade, show a single "what's new" notification pointing at the
    * dashboard — so users discover new features (including opt-in, default-off
    * ones they'd never find otherwise). Shown once per version; skipped on a
@@ -230,7 +713,9 @@ export class ClaudeCodeUsageExtension {
       this.getConfiguration().releaseAnnouncements,
       WHATS_NEW,
     );
-    void this.context.globalState.update('ccu.lastSeenVersion', current);
+    this.queueInitializationWrite(() =>
+      this.context.globalState.update('ccu.lastSeenVersion', current),
+    );
     if (announcement) {
       this.showWhatsNew(announcement.version);
     }
@@ -295,15 +780,890 @@ export class ClaudeCodeUsageExtension {
       }),
       vscode.commands.registerCommand('claudeCodeUsage.previewWhatsNew', () => {
         this.previewWhatsNew();
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.manageLocalData', () => {
+        this.webviewProvider.show('settings');
+        queueMicrotask(() => this.webviewProvider.requestLocalDataInventoryRefresh());
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.rebuildCodexIndex', () => {
+        void this.runLocalDataActionInteractive('rebuild-codex-index');
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.clearQuotaHistory', () => {
+        void this.clearQuotaHistoryFromCommandPalette();
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.clearAdviceData', () => {
+        void this.runLocalDataActionInteractive('clear-advice-data');
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.resetUiState', () => {
+        this.webviewProvider.show('settings');
+        void this.runLocalDataActionInteractive('reset-ui-state');
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.resetSharingPreferences', () => {
+        this.webviewProvider.show('settings');
+        void this.runLocalDataActionInteractive('reset-sharing-preferences');
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.clearByokSecret', () => {
+        void this.runLocalDataActionInteractive('clear-byok-secret');
+      }),
+      vscode.commands.registerCommand('claudeCodeUsage.clearAllDerivedData', () => {
+        this.webviewProvider.show('settings');
+        void this.runLocalDataActionInteractive('clear-all-derived-data');
       })
     ];
 
     commands.forEach(command => this.context.subscriptions.push(command));
   }
 
+  private async derivedFileFamilyNames(
+    filePath: string,
+    family: 'codex-index' | 'quota-observations',
+  ): Promise<string[]> {
+    const directory = path.dirname(filePath);
+    const canonical = path.basename(filePath);
+    let names: string[];
+    try {
+      names = await fs.promises.readdir(directory);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+    return names.filter((name) => {
+      if (name === canonical) return true;
+      if (family === 'codex-index') {
+        return /^codex-index-v1\.corrupt-\d+-\d+\.json$/.test(name) ||
+          /^codex-index-v1\.json\.tmp-\d+-[a-f0-9-]{36}$/.test(name);
+      }
+      return /^quota-observations-v2\.json\.quarantine-\d+-[a-f0-9]{8}$/.test(name) ||
+        /^\.quota-observations-v2\.json\.\d+\.[a-f0-9]{12}\.tmp$/.test(name);
+    });
+  }
+
+  private async localFileFamilyInventory(
+    filePath: string,
+    family: 'codex-index' | 'quota-observations',
+  ): Promise<{
+    approximateBytes: number | null;
+    itemCount: number;
+    oldestAt: number | null;
+    newestAt: number | null;
+  }> {
+    try {
+      const names = await this.derivedFileFamilyNames(filePath, family);
+      const stats = await Promise.all(names.map((name) =>
+        fs.promises.lstat(path.join(path.dirname(filePath), name)),
+      ));
+      const files = stats.filter((stat) => stat.isFile() || stat.isSymbolicLink());
+      if (files.length === 0) {
+        return { approximateBytes: 0, itemCount: 0, oldestAt: null, newestAt: null };
+      }
+      const range = finiteTimestampRange(files.flatMap((stat) => [
+        stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.ctimeMs,
+        stat.mtimeMs,
+      ]));
+      return {
+        approximateBytes: files.reduce((sum, stat) => sum + stat.size, 0),
+        itemCount: files.length,
+        ...range,
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        this.outputChannel.appendLine('local-data inventory: one derived file is unreadable');
+      }
+      return { approximateBytes: null, itemCount: 0, oldestAt: null, newestAt: null };
+    }
+  }
+
+  private async removeDerivedFileFamily(
+    filePath: string,
+    family: 'codex-index' | 'quota-observations',
+  ): Promise<void> {
+    const directory = path.dirname(filePath);
+    const names = await this.derivedFileFamilyNames(filePath, family);
+    for (const name of names) {
+      // `name` came from an exact allowlisted family matcher in this one
+      // directory. unlink never follows a symlink target.
+      await fs.promises.unlink(path.join(directory, name)).catch((error) => {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      });
+    }
+  }
+
+  private async removeDerivedFileFamilyWithLease(
+    filePath: string,
+    family: 'codex-index' | 'quota-observations',
+  ): Promise<void> {
+    const lease = await acquireCodexIndexLease(filePath);
+    try {
+      await this.removeDerivedFileFamily(filePath, family);
+    } finally {
+      await lease.release();
+    }
+  }
+
+  private extensionGlobalStateKeys(): readonly string[] {
+    const keys = this.context.globalState.keys;
+    return typeof keys === 'function' ? keys.call(this.context.globalState) : [];
+  }
+
+  private globalStateAggregate(keys: readonly string[]): {
+    approximateBytes: number | null;
+    itemCount: number;
+  } {
+    let bytes = 0;
+    let knownBytes = true;
+    for (const key of keys) {
+      const valueBytes = approximateJsonBytes(this.context.globalState.get<unknown>(key));
+      if (valueBytes === null) knownBytes = false;
+      else bytes += valueBytes;
+    }
+    return {
+      approximateBytes: knownBytes ? bytes : null,
+      itemCount: keys.length,
+    };
+  }
+
+  private buildQuotaScopeOptions(): LocalDataQuotaScopeOption[] {
+    this.localDataQuotaScopes.clear();
+    const locale = I18n.getLocale();
+    const zh = locale === 'zh-CN';
+    const observations = this.quotaObservationStore.observations;
+    const revision = this.quotaObservationRevision();
+    const createdAt = Date.now();
+    const result: LocalDataQuotaScopeOption[] = [];
+    const add = (
+      label: string,
+      scope: ResolvedQuotaScope,
+      itemCount: number,
+      oldestAt: number | null,
+      newestAt: number | null,
+      provider: 'claude' | 'codex' | 'all',
+    ): void => {
+      const token = randomBytes(18).toString('hex');
+      this.localDataQuotaScopes.set(token, {
+        scope,
+        label,
+        createdAt,
+        revision,
+      });
+      result.push({ token, label, provider, itemCount, oldestAt, newestAt });
+    };
+    const allRange = finiteTimestampRange(observations.map((item) => item.observedAt));
+    add(
+      zh ? `全部额度观测（${observations.length} 项）` : `All quota observations (${observations.length})`,
+      {},
+      observations.length,
+      allRange.oldestAt,
+      allRange.newestAt,
+      'all',
+    );
+    for (const provider of ['claude', 'codex'] as const) {
+      const selected = observations.filter((item) => item.provider === provider);
+      if (selected.length === 0) continue;
+      const range = finiteTimestampRange(selected.map((item) => item.observedAt));
+      add(
+        zh
+          ? `${provider === 'claude' ? 'Claude' : 'Codex'} 全部观测（${selected.length} 项）`
+          : `${provider === 'claude' ? 'Claude' : 'Codex'} observations (${selected.length})`,
+        { provider },
+        selected.length,
+        range.oldestAt,
+        range.newestAt,
+        provider,
+      );
+    }
+    const epochNumber = new Map<'claude' | 'codex', number>([['claude', 0], ['codex', 0]]);
+    for (const epoch of groupQuotaAccountEpochs(this.quotaObservationStore)) {
+      const index = (epochNumber.get(epoch.provider) ?? 0) + 1;
+      epochNumber.set(epoch.provider, index);
+      const providerLabel = epoch.provider === 'claude' ? 'Claude' : 'Codex';
+      add(
+        zh
+          ? `${providerLabel} 本地匿名账号周期 ${index}（${epoch.itemCount} 项）`
+          : `${providerLabel} local anonymous account epoch ${index} (${epoch.itemCount})`,
+        {
+          provider: epoch.provider,
+          accountFingerprint: epoch.accountFingerprint,
+        },
+        epoch.itemCount,
+        epoch.oldestAt,
+        epoch.newestAt,
+        epoch.provider,
+      );
+    }
+    return result;
+  }
+
+  private quotaObservationRevision(): string {
+    return createHash('sha256')
+      .update(JSON.stringify(this.quotaObservationStore.observations))
+      .digest('hex');
+  }
+
+  private async buildLocalDataInventory(
+    client: LocalDataClientSummary,
+  ): Promise<LocalDataInventory> {
+    const zh = I18n.getLocale() === 'zh-CN';
+    const local = (english: string, chinese: string): string =>
+      zh ? chinese : english;
+    const indexPath = path.join(this.context.globalStorageUri.fsPath, 'codex-index-v1.json');
+    const quotaPath = path.join(this.context.globalStorageUri.fsPath, QUOTA_OBSERVATION_FILE);
+    const [indexFile, quotaFile] = await Promise.all([
+      this.localFileFamilyInventory(indexPath, 'codex-index'),
+      this.localFileFamilyInventory(quotaPath, 'quota-observations'),
+    ]);
+    const stateKeys = this.extensionGlobalStateKeys();
+    const legacyQuotaKeys = stateKeys.filter((key) =>
+      key.startsWith(LEGACY_QUOTA_PREFIX) || key.startsWith(LEGACY_WEEKLY_PREFIX),
+    );
+    const sharingSettingKeys = new Set([
+      'ccu.setting.showHeatmap',
+      'ccu.setting.enableShareCard',
+    ]);
+    const ownedSettingKeys = new Set(OWNED_SETTING_GLOBAL_STATE_KEYS);
+    const preferenceKeys = stateKeys.filter((key) =>
+      (ownedSettingKeys.has(key) &&
+        !sharingSettingKeys.has(key) &&
+        key !== 'ccu.setting.advice.apiKey') ||
+      [
+        'ccu.lastSeenVersion',
+        'ccu.codex.backgroundWork.v1',
+        'ccu.migrated.dashboardAutoRefresh',
+        'ccu.migrated.showScopedWeekly',
+        LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+        'ccu.quota.migratedCodexIndex.v2',
+        'ccu.settingsMigrated.v1',
+      ].includes(key),
+    );
+    const saltKeys = stateKeys.filter((key) =>
+      key === QUOTA_FINGERPRINT_SALT_KEY || key === 'ccu.codex.machineSalt',
+    );
+    const sharingKeys = stateKeys.filter((key) =>
+      key === 'ccu.heatmapRepo' ||
+      key === 'ccu.heatmapPath' ||
+      sharingSettingKeys.has(key),
+    );
+    const adviceSummary = this.webviewProvider.adviceLocalDataInventorySummary();
+    const quotaRange = finiteTimestampRange(
+      this.quotaObservationStore.observations.map((item) => item.observedAt),
+    );
+    const byokConfigured = this.settings.snapshot().some((item) =>
+      item.key === 'advice.apiKey' && item.configured === true,
+    );
+    const rows: LocalDataInventoryRow[] = [
+      {
+        id: 'R1',
+        category: local('R1 · Claude provider-owned source logs', 'R1 · Claude 自有源日志'),
+        locationClass: local('Claude Code data directory (read-only source)', 'Claude Code 数据目录（只读源）'),
+        schema: 'provider-owned JSONL',
+        approximateBytes: null,
+        itemCount: null,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('None by default; exact preview only for separately consented advice', '默认无；仅另行同意的建议会发送精确预览内容'),
+        clearability: local('Never touched by these controls; opt-in Session Actions is separate', '这些控制绝不触碰；另行启用的会话操作相互独立'),
+      },
+      {
+        id: 'R2',
+        category: local('R2 · Codex provider-owned source logs', 'R2 · Codex 自有源日志'),
+        locationClass: local('Codex home sessions/archives (read-only source)', 'Codex home 会话/归档（只读源）'),
+        schema: 'provider-owned JSONL',
+        approximateBytes: null,
+        itemCount: null,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('None', '无'),
+        clearability: local('Never cleared by this extension', '插件绝不清除'),
+      },
+      {
+        id: 'P1',
+        category: local('P1 · Codex incremental index', 'P1 · Codex 增量索引'),
+        locationClass: local('Extension global storage / codex index', '插件全局存储 / Codex 索引'),
+        schema: 'internal schema 3',
+        ...indexFile,
+        networkInteraction: local('None', '无'),
+        clearability: local('Clear and rebuild from R2', '清除后从 R2 重建'),
+      },
+      {
+        id: 'P2',
+        category: local('P2 · Quota observation history', 'P2 · 额度观测历史'),
+        locationClass: local('Extension global storage / quota observations', '插件全局存储 / 额度观测'),
+        schema: 'schema 2',
+        approximateBytes: quotaFile.approximateBytes,
+        itemCount: this.quotaObservationStore.observations.length,
+        ...quotaRange,
+        networkInteraction: local('Claude official quota request; Codex local structured events', 'Claude 官方额度请求；Codex 本地结构化事件'),
+        clearability: local('Clear by provider, anonymous account epoch, or all', '按供应商、匿名账号 epoch 或全部清除'),
+      },
+      {
+        id: 'P3-P4',
+        category: local('P3/P4 · Legacy quota migration inputs', 'P3/P4 · 旧版额度迁移输入'),
+        locationClass: local('Extension globalState (legacy, migration-only)', '插件 globalState（旧版，仅迁移）'),
+        schema: 'legacy',
+        ...this.globalStateAggregate(legacyQuotaKeys),
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('None', '无'),
+        clearability: local('Imported transactionally, then removed; included in clear-all', '事务导入后删除；纳入清除全部'),
+      },
+      {
+        id: 'P5',
+        category: local('P5 · Codex legacy quota migration input', 'P5 · Codex 旧额度迁移输入'),
+        locationClass: local('Embedded in the P1 Codex index (migration-only)', '嵌入 P1 Codex 索引（仅迁移）'),
+        schema: 'legacy quotaHistory + exact migration marker',
+        approximateBytes: null,
+        itemCount: this.context.globalState.get<boolean>(QUOTA_P5_MIGRATION_KEY) === true
+          ? 0
+          : null,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('None', '无'),
+        clearability: local('Migrated once into P2; P1 rebuild never deletes migrated P2 history', '一次性迁入 P2；重建 P1 不删除已迁移的 P2 历史'),
+      },
+      {
+        id: 'P6',
+        category: local('P6 · Extension preferences and migration state', 'P6 · 插件偏好与迁移状态'),
+        locationClass: local('VS Code configuration + extension globalState', 'VS Code 配置 + 插件 globalState'),
+        schema: 'typed settings + versioned flags',
+        ...this.globalStateAggregate(preferenceKeys),
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('VS Code Settings Sync may apply to configuration', '配置可能参与 VS Code Settings Sync'),
+        clearability: local('Reset settings or clear all extension-derived data', '重置设置或清除全部插件派生数据'),
+      },
+      {
+        id: 'P7',
+        category: local('P7 · Machine-local pseudonymization material', 'P7 · 本机匿名化材料'),
+        locationClass: local('Extension globalState', '插件 globalState'),
+        schema: 'random salts / HMAC v1',
+        approximateBytes: null,
+        itemCount: saltKeys.length,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('Never', '永不'),
+        clearability: local('Included in clear-all; invalidates prior local fingerprints', '纳入清除全部；旧本机 fingerprint 随即失效'),
+      },
+      {
+        id: 'P8',
+        category: local('P8 · BYOK advice credential', 'P8 · BYOK 建议凭证'),
+        locationClass: 'VS Code SecretStorage',
+        schema: 'host SecretStorage',
+        approximateBytes: null,
+        itemCount: byokConfigured ? 1 : 0,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('Only to the configured endpoint after explicit Send', '仅在明确点击发送后用于所配置端点'),
+        clearability: local('Clear BYOK secret or clear all; value is never inventoried', '清除 BYOK 密钥或清除全部；清单绝不读取值'),
+      },
+      {
+        id: 'P9',
+        category: local('P9 · Advice-effectiveness ledger', 'P9 · 建议效果台账'),
+        locationClass: local('Extension globalState', '插件 globalState'),
+        schema: 'schema 3',
+        ...adviceSummary,
+        networkInteraction: local('Only exact previewed payload after explicit Send', '仅在明确点击发送后发送精确预览载荷'),
+        clearability: local('Clear Advice Data', '清除建议数据'),
+      },
+      {
+        id: 'P10',
+        category: local('P10 · Dashboard UI preferences', 'P10 · 仪表板界面偏好'),
+        locationClass: local('Webview state + allowlisted localStorage keys', 'Webview 状态 + 白名单 localStorage 键'),
+        schema: 'ephemeral UI state',
+        approximateBytes: null,
+        itemCount: client.uiPreferenceKeys + client.webviewStateFields,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('Never', '永不'),
+        clearability: local('Reset UI State', '重置界面状态'),
+      },
+      {
+        id: 'P11',
+        category: local('P11 · Heatmap/share preferences', 'P11 · 热力图/分享偏好'),
+        locationClass: local('Webview localStorage + extension globalState', 'Webview localStorage + 插件 globalState'),
+        schema: 'bounded title/range/privacy + destination strings',
+        approximateBytes: this.globalStateAggregate(sharingKeys).approximateBytes,
+        itemCount: sharingKeys.length + client.sharingPreferenceKeys,
+        oldestAt: null,
+        newestAt: null,
+        networkInteraction: local('Local export: none; GitHub publish: explicit confirmed action only', '本地导出：无；GitHub 发布：仅明确确认的动作'),
+        clearability: local('Reset Sharing Preferences', '重置分享偏好'),
+      },
+    ];
+    return {
+      schemaVersion: 1,
+      generatedAt: Date.now(),
+      rows,
+      quotaScopes: this.buildQuotaScopeOptions(),
+      exclusions: zh
+        ? [
+            'Claude 自有源日志',
+            'Codex 自有源日志',
+            '供应商自有 OAuth 凭证与 cookie',
+            '外部账号额度与订阅状态',
+          ]
+        : [...LOCAL_DATA_SOURCE_EXCLUSIONS],
+    };
+  }
+
+  private async clearQuotaHistoryFromCommandPalette(): Promise<void> {
+    const inventory = await this.buildLocalDataInventory({
+      uiPreferenceKeys: 0,
+      webviewStateFields: 0,
+      sharingPreferenceKeys: 0,
+    });
+    const picked = await vscode.window.showQuickPick(
+      inventory.quotaScopes.map((scope) => ({
+        label: scope.label,
+        description: `${scope.itemCount} observations`,
+        token: scope.token,
+      })),
+      { placeHolder: 'Select the exact quota-history scope to clear' },
+    );
+    if (!picked) return;
+    await this.runLocalDataActionInteractive('clear-quota-history', picked.token);
+  }
+
+  private serializeLocalDataAction<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.localDataActionWrite.then(operation, operation);
+    this.localDataActionWrite = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  /**
+   * Prevent a deliberate P2 clear from being undone by one-shot legacy
+   * migration on the next activation. Account-specific Claude legacy inputs
+   * cannot be mapped safely from their old path suffix, so they are only
+   * removed for a provider-wide/all clear; such inputs normally disappeared
+   * immediately after their original durable migration.
+   */
+  private async clearLegacyQuotaMigrationInputs(
+    scope: ResolvedQuotaScope,
+  ): Promise<void> {
+    const broadScope = scope.accountFingerprint === undefined;
+    const clearsClaude = scope.provider === undefined || scope.provider === 'claude';
+    const clearsCodex = scope.provider === undefined || scope.provider === 'codex';
+    if (broadScope && clearsClaude) {
+      const legacyKeys = this.extensionGlobalStateKeys().filter((key) =>
+        key.startsWith(LEGACY_QUOTA_PREFIX) ||
+        key.startsWith(LEGACY_WEEKLY_PREFIX),
+      );
+      for (const key of legacyKeys) {
+        await this.context.globalState.update(key, undefined);
+      }
+    }
+    if (broadScope && clearsCodex) {
+      // A clear is the user's decision to discard legacy P5 quota history too.
+      // Keep the marker so a surviving P1 cannot repopulate P2 later.
+      await this.context.globalState.update(QUOTA_P5_MIGRATION_KEY, true);
+    }
+  }
+
+  private assertScopedQuotaMigrationIsResolved(scope: ResolvedQuotaScope): void {
+    if (scope.accountFingerprint === undefined) return;
+    if (scope.provider === 'claude') {
+      const unresolved = this.extensionGlobalStateKeys().some((key) =>
+        key.startsWith(LEGACY_QUOTA_PREFIX) ||
+        key.startsWith(LEGACY_WEEKLY_PREFIX),
+      );
+      if (unresolved) throw new QuotaObservationScopedMigrationBlockedError();
+    }
+    if (
+      scope.provider === 'codex' &&
+      this.context.globalState.get<boolean>(QUOTA_P5_MIGRATION_KEY) !== true
+    ) {
+      throw new QuotaObservationScopedMigrationBlockedError();
+    }
+  }
+
+  private async resetSharingPreferencesHost(): Promise<void> {
+    await this.settings.resetSharingOwnedData();
+    await this.context.globalState.update('ccu.heatmapRepo', undefined);
+    await this.context.globalState.update('ccu.heatmapPath', undefined);
+    this.webviewProvider.clearSharingRuntimeState();
+  }
+
+  private pendingClientReset(): LocalDataClientAction | undefined {
+    const value = this.context.globalState.get<unknown>(
+      LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+    );
+    return value === 'reset-ui-state' ||
+      value === 'reset-sharing-preferences' ||
+      value === 'clear-all-client-state'
+      ? value
+      : undefined;
+  }
+
+  private replayPendingClientReset(): Promise<void> {
+    const run = this.pendingClientResetReplay
+      .catch(() => undefined)
+      .then(async () => {
+        const pending = this.pendingClientReset();
+        if (!pending) return;
+        if (await this.webviewProvider.requestClientLocalDataAction(pending)) {
+          await this.context.globalState.update(
+            LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+            undefined,
+          );
+        }
+      });
+    this.pendingClientResetReplay = run;
+    return run;
+  }
+
+  private async runLocalDataActionInteractive(
+    action: LocalDataAction,
+    quotaScopeToken?: string,
+  ): Promise<LocalDataActionResult> {
+    return this.serializeLocalDataAction(async () => {
+      const locale = I18n.getLocale();
+      const zh = locale === 'zh-CN';
+      let quotaSelection: {
+        scope: ResolvedQuotaScope;
+        label: string;
+        createdAt: number;
+        revision: string;
+        token: string;
+      } | undefined;
+      if (action === 'clear-quota-history') {
+        const selected = quotaScopeToken
+          ? this.localDataQuotaScopes.get(quotaScopeToken)
+          : undefined;
+        if (
+          !selected ||
+          Date.now() - selected.createdAt > LOCAL_DATA_QUOTA_SCOPE_TTL_MS ||
+          selected.revision !== this.quotaObservationRevision()
+        ) {
+          return {
+            ok: false,
+            message: zh ? '额度历史范围已过期，请刷新清单后重试。' : 'The quota-history scope expired. Refresh the inventory and try again.',
+          };
+        }
+        quotaSelection = { ...selected, token: quotaScopeToken as string };
+      }
+      const title = localDataActionTitle(action, locale);
+      const targets = LOCAL_DATA_ACTION_TARGETS[action].map((target) => `• ${target}`);
+      if (quotaSelection) targets.unshift(`• ${quotaSelection.label}`);
+      const preflightNotes: string[] = [];
+      if (action === 'clear-all-derived-data') {
+        targets.push(...LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS.map((key) =>
+          `• globalState/${key}`,
+        ));
+        targets.push(...REGISTERED_CONFIGURATION_SETTING_KEYS.map((key) =>
+          `• configuration/claudeCodeUsage.${key}`,
+        ));
+        const discoveredMigrationKeys = this.extensionGlobalStateKeys().filter((key) =>
+          LOCAL_DATA_GLOBAL_STATE_PREFIXES.some((prefix) => key.startsWith(prefix)),
+        );
+        targets.push(...discoveredMigrationKeys.map((key) => `• globalState/${key}`));
+        const registered = new Set(REGISTERED_CONFIGURATION_SETTING_KEYS);
+        const inspectedOnly = KNOWN_CONFIGURATION_SETTING_KEYS.filter((key) =>
+          !registered.has(key),
+        );
+        preflightNotes.push(
+          zh
+            ? `仅预检（若存在则在任何删除前停止）：${inspectedOnly.map((key) => `claudeCodeUsage.${key}`).join(', ')}`
+            : `Preflight only (if present, stop before any deletion): ${inspectedOnly.map((key) => `claudeCodeUsage.${key}`).join(', ')}`,
+        );
+      }
+      const exclusions = LOCAL_DATA_SOURCE_EXCLUSIONS.map((target) => `• ${target}`);
+      const proceed = zh ? '继续' : 'Continue';
+      const detail = [
+        zh ? '精确目标：' : 'Exact targets:',
+        ...targets,
+        ...(preflightNotes.length > 0 ? ['', ...preflightNotes] : []),
+        '',
+        zh ? '始终排除：' : 'Always excluded:',
+        ...exclusions,
+      ].join('\n');
+      const picked = await vscode.window.showWarningMessage(
+        title,
+        { modal: true, detail },
+        proceed,
+      );
+      if (picked !== proceed) {
+        return {
+          ok: false,
+          cancelled: true,
+          message: zh ? '已取消；未更改任何本地数据。' : 'Cancelled; no local data was changed.',
+        };
+      }
+      if (quotaSelection) {
+        const current = this.localDataQuotaScopes.get(quotaSelection.token);
+        this.localDataQuotaScopes.delete(quotaSelection.token);
+        if (
+          current !== undefined &&
+          (
+            current.createdAt !== quotaSelection.createdAt ||
+            current.revision !== quotaSelection.revision ||
+            Date.now() - current.createdAt > LOCAL_DATA_QUOTA_SCOPE_TTL_MS ||
+            current.revision !== this.quotaObservationRevision()
+          )
+        ) {
+          return {
+            ok: false,
+            message: zh ? '额度历史在确认期间发生变化，请刷新清单后重试。' : 'Quota history changed while confirming. Refresh the inventory and try again.',
+          };
+        }
+        if (!current) {
+          return {
+            ok: false,
+            message: zh ? '额度历史范围已使用或过期，请刷新后重试。' : 'The quota-history scope was already used or expired. Refresh and try again.',
+          };
+        }
+      }
+      let result: LocalDataActionResult;
+      try {
+        result = await this.executeLocalDataAction(action, quotaSelection?.scope);
+      } catch (error) {
+        if (error instanceof SettingsLocalDataClearError) {
+          result = {
+            ok: false,
+            message: zh
+              ? '检测到当前清单无法通过 VS Code API 安全删除的旧版 settings.json 项；尚未删除任何设置或密钥，请先手动移除这些旧项后重试。'
+              : 'Legacy settings.json entries cannot be removed safely through the current VS Code API. No setting or secret was deleted; remove those legacy entries manually, then retry.',
+          };
+        } else if (
+          error instanceof QuotaObservationScopedClearBlockedError ||
+          error instanceof QuotaObservationScopedMigrationBlockedError
+        ) {
+          result = {
+            ok: false,
+            message: zh
+              ? '所选按账号/供应商范围无法与隔离或待迁移的额度数据安全对应；尚未做范围删除。请选择“全部额度观测”并再次明确确认。'
+              : 'The selected account/provider scope cannot be mapped safely while quarantined or pending-migration quota data exists. Nothing was scope-cleared; choose All quota observations and confirm again.',
+          };
+        } else {
+          result = {
+            ok: false,
+            message: zh ? '操作未完成；源日志和账号数据均未更改。' : 'The action did not complete; source logs and account data were not changed.',
+          };
+        }
+      }
+      if (result.clientAction) {
+        let tombstoneStored = false;
+        try {
+          await this.context.globalState.update(
+            LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+            result.clientAction,
+          );
+          tombstoneStored = true;
+        } catch {
+          // Still attempt the live client clear. A successful verified ACK is
+          // sufficient even when the recovery tombstone could not be written.
+        }
+        const clientResetOk = await this.webviewProvider.requestClientLocalDataAction(
+          result.clientAction,
+        );
+        if (clientResetOk && tombstoneStored) {
+          try {
+            await this.context.globalState.update(
+              LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+              undefined,
+            );
+          } catch {
+            // A stale tombstone only replays the same exact idempotent reset.
+          }
+        }
+        result = clientResetOk
+          ? { ...result, clientAction: undefined }
+          : {
+              ok: false,
+              message: zh
+                ? tombstoneStored
+                  ? '宿主数据已处理，但 Webview 未确认本地状态重置；已记录待处理重置，下次打开面板会自动重试。'
+                  : '宿主数据已处理，但 Webview 未确认本地状态重置，且无法写入重试标记；请保持面板打开后重试。'
+                : tombstoneStored
+                  ? 'Host data was handled, but the Webview did not confirm its local reset. A pending reset was recorded and will retry when the panel next opens.'
+                  : 'Host data was handled, but the Webview did not confirm its local reset and a retry marker could not be stored. Keep the panel open and retry.',
+            };
+      }
+      if (result.ok) {
+        this.webviewProvider.requestLocalDataInventoryRefresh();
+      }
+      if (!this.webviewProvider) return result;
+      void vscode.window.showInformationMessage(result.message);
+      return result;
+    });
+  }
+
+  private async executeLocalDataAction(
+    action: LocalDataAction,
+    quotaScope: ResolvedQuotaScope | undefined,
+  ): Promise<LocalDataActionResult> {
+    const zh = I18n.getLocale() === 'zh-CN';
+    switch (action) {
+      case 'rebuild-codex-index':
+        await this.clearCodexDerivedIndex(true);
+        return { ok: true, message: zh ? 'Codex 派生索引已安全重建。' : 'The Codex derived index was safely rebuilt.' };
+      case 'clear-quota-history':
+        this.stopQuotaColdRetry('settings-change');
+        await this.cancelQuotaNetworks('cancelled');
+        this.assertScopedQuotaMigrationIsResolved(quotaScope ?? {});
+        this.quotaObservationStore = await this.quotaObservationRepository.clear(quotaScope ?? {});
+        await this.clearLegacyQuotaMigrationInputs(quotaScope ?? {});
+        this.refreshQuotaObservationViews();
+        return { ok: true, message: zh ? '所选额度观测历史已清除；官方额度未受影响。' : 'The selected quota observations were cleared; provider quotas were not changed.' };
+      case 'clear-advice-data': {
+        const cleared = await this.webviewProvider.clearAdviceLocalData();
+        if (!cleared) throw new Error('advice-clear-failed');
+        for (const key of LEGACY_ADVICE_LOCAL_STATE_KEYS) {
+          await this.context.globalState.update(key, undefined);
+        }
+        return { ok: true, message: zh ? '本地建议台账已清除。' : 'The local advice ledger was cleared.' };
+      }
+      case 'reset-ui-state':
+        return {
+          ok: true,
+          message: zh ? '仪表板界面状态已重置。' : 'Dashboard UI state was reset.',
+          clientAction: 'reset-ui-state',
+        };
+      case 'reset-sharing-preferences':
+        await this.resetSharingPreferencesHost();
+        return {
+          ok: true,
+          message: zh ? '分享偏好和目标字符串已重置。' : 'Sharing preferences and destination strings were reset.',
+          clientAction: 'reset-sharing-preferences',
+        };
+      case 'clear-byok-secret':
+        this.webviewProvider.invalidatePreparedAiRequests();
+        await this.cancelAdviceNetworks('cancelled');
+        await this.settings.clearByokOwnedData();
+        return { ok: true, message: zh ? 'BYOK 建议密钥已从 SecretStorage 清除。' : 'The BYOK advice secret was cleared from SecretStorage.' };
+      case 'clear-all-derived-data':
+        return this.clearAllExtensionDerivedData();
+    }
+  }
+
+  private async clearCodexDerivedIndex(rebuild: boolean): Promise<void> {
+    const generation = ++this.configurationGeneration;
+    this.stopCodexWatching('settings-change');
+    this.codexWorkerCancellationRequested = true;
+    await this.waitForCodexProviderRetirements();
+    const retiring = this.codexProvider;
+    await this.cancelCodexProviderAndWait(retiring);
+    while (this.activeCodexRefreshes.size > 0) {
+      await Promise.allSettled([...this.activeCodexRefreshes]);
+    }
+    await retiring.dispose();
+    await this.releaseCodexOwnership('settings-change');
+    const indexPath = path.join(this.context.globalStorageUri.fsPath, 'codex-index-v1.json');
+    await this.removeDerivedFileFamilyWithLease(indexPath, 'codex-index');
+    this.codexView = null;
+    this.codexInsights = emptyCodexScopedInsights();
+    this.codexHasData = false;
+    this.codexRefreshing = false;
+    this.codexProgress = null;
+    this.codexBackgroundState = createBackgroundWorkState({
+      measurementVersion: ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+      reason: 'first-index',
+      now: Date.now(),
+    });
+    await this.saveCodexBackgroundState();
+    this.codexProvider = this.createCodexProvider(this.getConfiguration());
+    this.syncProviderUi();
+    if (
+      rebuild &&
+      !this.disposed &&
+      generation === this.configurationGeneration &&
+      this.windowActivity.focused &&
+      this.getConfiguration().codexEnabled
+    ) {
+      await this.refreshCodexData('manual');
+      if (!this.disposed && generation === this.configurationGeneration) {
+        this.startCodexWatching();
+      }
+    }
+  }
+
+  private async clearAllExtensionDerivedData(): Promise<LocalDataActionResult> {
+    const zh = I18n.getLocale() === 'zh-CN';
+    this.settings.preflightResetAllOwnedData();
+    this.clearingAllLocalData = true;
+    // The in-memory fingerprint salt and repositories deliberately stay
+    // immutable. Fail closed after any clear-all attempt until a reload creates
+    // fresh runtime objects from the now-empty stores.
+    this.localDataClearedRequiresReload = true;
+    try {
+      await this.drainInitializationWritesForClear();
+      this.stopQuotaColdRetry('settings-change');
+      this.stopAutoRefresh('settings-change');
+      this.stopFileWatching('settings-change');
+      this.stopCredentialsWatching('settings-change');
+      await Promise.all([
+        this.cancelAdviceNetworks('cancelled'),
+        this.cancelQuotaNetworks('cancelled'),
+      ]);
+      await this.settings.resetAllOwnedData();
+      await this.clearCodexDerivedIndex(false);
+      this.quotaObservationStore = await this.quotaObservationRepository.clear({});
+      await this.webviewProvider.clearAdviceLocalData();
+      this.webviewProvider.clearSharingRuntimeState();
+      const keys = this.extensionGlobalStateKeys().filter((key) =>
+        LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS.includes(key as typeof LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS[number]) ||
+        LOCAL_DATA_GLOBAL_STATE_PREFIXES.some((prefix) => key.startsWith(prefix)) ||
+        LEGACY_ADVICE_LOCAL_STATE_KEYS.includes(key),
+      );
+      for (const key of keys) {
+        await this.context.globalState.update(key, undefined);
+      }
+      await this.verifyClearAllPostcondition();
+      this.quotaObservationStore = createEmptyQuotaObservationStore();
+      this.claudeWeeklyQuotaHistory = [];
+      this.cache.usageLimits = null;
+      this.cache.usageLimitsLastUpdate = new Date(0);
+      this.cache.records = [];
+      this.cache.contentAnalysis = null;
+      this.cache.claudeIndex = createClaudeUsageIndex();
+      this.codexView = null;
+      this.codexInsights = emptyCodexScopedInsights();
+      this.codexHasData = false;
+      this.refreshQuotaObservationViews();
+      this.syncProviderUi();
+      return {
+        ok: true,
+        message: zh
+          ? '插件派生数据已按清单清除；Claude/Codex 源日志和账号凭证未更改。请重载窗口以重新初始化。'
+          : 'Extension-derived data was cleared as listed; Claude/Codex source logs and provider credentials were unchanged. Reload the window to reinitialize.',
+        clientAction: 'clear-all-client-state',
+      };
+    } finally {
+      this.clearingAllLocalData = false;
+    }
+  }
+
+  private async verifyClearAllPostcondition(): Promise<void> {
+    const residualState = this.extensionGlobalStateKeys().filter((key) =>
+      LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS.includes(key as typeof LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS[number]) ||
+      LOCAL_DATA_GLOBAL_STATE_PREFIXES.some((prefix) => key.startsWith(prefix)) ||
+      LEGACY_ADVICE_LOCAL_STATE_KEYS.includes(key),
+    );
+    if (residualState.length > 0) {
+      throw new Error('local-data-clear:global-state-postcondition-failed');
+    }
+    const indexPath = path.join(this.context.globalStorageUri.fsPath, 'codex-index-v1.json');
+    if ((await this.derivedFileFamilyNames(indexPath, 'codex-index')).length > 0) {
+      throw new Error('local-data-clear:codex-index-postcondition-failed');
+    }
+    const quotaPath = path.join(
+      this.context.globalStorageUri.fsPath,
+      QUOTA_OBSERVATION_FILE,
+    );
+    const quotaNames = await this.derivedFileFamilyNames(
+      quotaPath,
+      'quota-observations',
+    );
+    if (quotaNames.some((name) => name !== QUOTA_OBSERVATION_FILE)) {
+      throw new Error('local-data-clear:quota-auxiliary-postcondition-failed');
+    }
+    const quota = await loadQuotaObservationStore(quotaPath);
+    if (quota.disposition !== 'valid' || quota.store.observations.length > 0) {
+      throw new Error('local-data-clear:quota-postcondition-failed');
+    }
+  }
+
   private async refreshPricing(): Promise<void> {
     try {
       const result = await fetchLatestPricing();
+      this.invalidateClaudeUsagePricingCache();
       vscode.window.showInformationMessage(`${I18n.t.popup.pricingUpdated} (${result.updated})`);
       // Force a full recompute so the new prices take effect.
       void this.refreshData(true, 'pricing');
@@ -322,8 +1682,11 @@ export class ClaudeCodeUsageExtension {
       vscode.window.showWarningMessage(I18n.t.popup.noDataMessage);
       return;
     }
-    const daily = ClaudeDataLoader.getDailyUsageMap(records, I18n.getTimezone());
-    const svg = renderHeatmapSvg(daily);
+    const timeZone = I18n.getTimezone();
+    const daily = ClaudeDataLoader.getDailyUsageMap(records, timeZone);
+    const svg = renderHeatmapSvg(daily, {
+      endDateISO: dayKeyInZone(new Date(), timeZone),
+    });
     const uri = await vscode.window.showSaveDialog({
       defaultUri: vscode.Uri.file(path.join(os.homedir(), 'claude-code-heatmap.svg')),
       filters: { 'SVG image': ['svg'] },
@@ -384,9 +1747,12 @@ export class ClaudeCodeUsageExtension {
     });
   }
 
-  /** Publish the token heatmap SVG to a GitHub repo (e.g. the user's profile
-   * repo, so it shows on their GitHub home) using VS Code's built-in GitHub
-   * auth — no PAT handling. Creates or updates the file via the Contents API. */
+  /**
+   * Publish one aggregate SVG to a verified public repository. v2.3.1 no
+   * longer requests the broad `repo` scope: private targets fail closed and
+   * retain the local SVG + Markdown path. A second modal names the exact
+   * owner/repo/branch/path and create-vs-overwrite action before any PUT.
+   */
   private async publishHeatmapToGitHub(): Promise<void> {
     const records = this.cache.records;
     if (!records || records.length === 0) {
@@ -394,15 +1760,13 @@ export class ClaudeCodeUsageExtension {
       return;
     }
 
-    // This is an authorization + write action, not a local export — make that
-    // explicit and get consent before touching GitHub.
-    const proceed = 'Sign in & publish';
+    const proceed = 'Continue with public-only access';
     const ok = await vscode.window.showWarningMessage(
-      'Publish the token heatmap to GitHub?',
+      'Publish the token heatmap to a public GitHub repository?',
       {
         modal: true,
         detail:
-          'This signs you in to GitHub (VS Code asks once) and commits a single SVG image to a repo you choose (default: your profile repo, so it shows on your GitHub home). Only the aggregate heatmap is uploaded — never prompts, file paths, or session ids. You can delete it from the repo anytime.',
+          'VS Code will request the narrower public_repo permission. Private repositories are intentionally unsupported; use local SVG export there. The plugin will read repository metadata and then show the exact public repository, branch, path, create/overwrite action, and payload size before writing.',
       },
       proceed
     );
@@ -412,8 +1776,11 @@ export class ClaudeCodeUsageExtension {
 
     let session: vscode.AuthenticationSession | undefined;
     try {
-      // 'repo' so private profile repos work too; VS Code shows its own consent.
-      session = await vscode.authentication.getSession('github', ['repo'], { createIfNone: true });
+      session = await vscode.authentication.getSession(
+        'github',
+        [GITHUB_PUBLIC_REPO_SCOPE],
+        { createIfNone: true },
+      );
     } catch {
       vscode.window.showErrorMessage('GitHub sign-in was cancelled.');
       return;
@@ -425,9 +1792,16 @@ export class ClaudeCodeUsageExtension {
     const login = session.account.label.split(/\s/)[0];
 
     const repo = await vscode.window.showInputBox({
-      prompt: 'Target repo (owner/name). Your profile repo (name = username) shows the heatmap on your GitHub home page.',
+      prompt: 'Public target repository (owner/name). Private repositories use local SVG export.',
       value: this.context.globalState.get<string>('ccu.heatmapRepo') || `${login}/${login}`,
-      validateInput: (v) => (/^[^/\s]+\/[^/\s]+$/.test(v.trim()) ? undefined : 'Use the form owner/name'),
+      validateInput: (value) => {
+        try {
+          createGitHubPublishPlan(value, 'heatmap.svg');
+          return undefined;
+        } catch (error) {
+          return error instanceof Error ? error.message : 'Use the form owner/name';
+        }
+      },
     });
     if (!repo) {
       return;
@@ -440,58 +1814,70 @@ export class ClaudeCodeUsageExtension {
     if (!filePath) {
       return;
     }
-    await this.context.globalState.update('ccu.heatmapRepo', repo.trim());
-    await this.context.globalState.update('ccu.heatmapPath', filePath.trim());
-
-    const [owner, name] = repo.trim().split('/');
-    const svg = renderHeatmapSvg(ClaudeDataLoader.getDailyUsageMap(records, I18n.getTimezone()));
+    let plan;
+    try {
+      plan = createGitHubPublishPlan(repo, filePath);
+    } catch (error) {
+      vscode.window.showErrorMessage(error instanceof Error ? error.message : String(error));
+      return;
+    }
+    const timeZone = I18n.getTimezone();
+    const svg = renderHeatmapSvg(
+      ClaudeDataLoader.getDailyUsageMap(records, timeZone),
+      { endDateISO: dayKeyInZone(new Date(), timeZone) },
+    );
     const contentB64 = Buffer.from(svg, 'utf8').toString('base64');
-    const apiPath = `/repos/${owner}/${name}/contents/${filePath.trim().split('/').map(encodeURIComponent).join('/')}`;
+    const request = (
+      method: 'GET' | 'PUT',
+      apiPath: string,
+      body?: unknown,
+    ) => this.githubApi(method, apiPath, token, body);
+
+    let preview;
+    try {
+      preview = await probePublicGitHubPublishTarget(plan, request);
+    } catch (error) {
+      vscode.window.showErrorMessage(`Heatmap publish unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+
+    const exactProceed = preview.action === 'update'
+      ? 'Overwrite exactly this file'
+      : 'Create exactly this file';
+    const exact = await vscode.window.showWarningMessage(
+      'Confirm the exact GitHub write',
+      {
+        modal: true,
+        detail: githubPublishConfirmationDetail(preview, Buffer.byteLength(svg, 'utf8')),
+      },
+      exactProceed,
+    );
+    if (exact !== exactProceed) {
+      return;
+    }
 
     try {
       await vscode.window.withProgress(
         { location: vscode.ProgressLocation.Notification, title: 'Publishing heatmap to GitHub…' },
-        async () => {
-          // Look up the current sha (needed to update an existing file).
-          let sha: string | undefined;
-          const getRes = await this.githubApi('GET', apiPath, token);
-          if (getRes.status === 200) {
-            sha = JSON.parse(getRes.body).sha as string;
-          } else if (getRes.status !== 404) {
-            throw new Error(this.githubError(getRes));
-          }
-          const putRes = await this.githubApi('PUT', apiPath, token, {
-            message: 'Update Claude Code usage heatmap',
-            content: contentB64,
-            sha,
-          });
-          if (putRes.status !== 200 && putRes.status !== 201) {
-            throw new Error(this.githubError(putRes));
-          }
-        }
+        () => publishPublicGitHubFile(preview, contentB64, request),
       );
     } catch (e) {
       vscode.window.showErrorMessage(`Heatmap publish failed: ${(e as Error).message}`);
       return;
     }
 
+    // Destination strings are convenience preferences, not credentials. Save
+    // them only after the exact, confirmed write succeeds.
+    await this.context.globalState.update('ccu.heatmapRepo', `${preview.owner}/${preview.repository}`);
+    await this.context.globalState.update('ccu.heatmapPath', preview.filePath);
+
     const view = 'View on GitHub';
     const pick = await vscode.window.showInformationMessage(
-      `Heatmap published to ${repo.trim()}.`,
+      `Heatmap published to ${preview.owner}/${preview.repository}.`,
       view
     );
     if (pick === view) {
-      void vscode.env.openExternal(vscode.Uri.parse(`https://github.com/${owner}/${name}/blob/HEAD/${filePath.trim()}`));
-    }
-  }
-
-  /** Pull a human message out of a GitHub error response. */
-  private githubError(res: { status: number; body: string }): string {
-    try {
-      const msg = JSON.parse(res.body).message;
-      return `GitHub ${res.status}: ${msg || res.body.slice(0, 120)}`;
-    } catch {
-      return `GitHub ${res.status}`;
+      void vscode.env.openExternal(vscode.Uri.parse(preview.browserUrl));
     }
   }
 
@@ -543,125 +1929,27 @@ export class ClaudeCodeUsageExtension {
   }
 
   private async getAdvice(): Promise<void> {
-    const config = this.getConfiguration();
-    // The subscription backend needs no API key (it reuses the Claude Code
-    // OAuth session); only the 'api' backend requires a configured key.
-    const needsKey =
-      config.adviceBackend === 'api' && (!config.adviceApiKey || config.adviceApiKey.trim() === '');
-    if (needsKey) {
-      const picked = await vscode.window.showWarningMessage(
-        I18n.t.popup.adviceNeedsKey,
+    // The legacy command now enters the one evidence/preview/send surface. It
+    // never constructs or sends an alternate free-form summary.
+    this.webviewProvider.show('content');
+    if (!this.settings.get<boolean>('advice.effectiveness.enabled')) {
+      const picked = await vscode.window.showInformationMessage(
+        I18n.t.popup.adviceEffectiveness.description,
         I18n.t.popup.settings,
-        I18n.t.popup.adviceDemoButton
       );
       if (picked === I18n.t.popup.settings) {
         vscode.commands.executeCommand('claudeCodeUsage.openSettings');
-      } else if (picked === I18n.t.popup.adviceDemoButton) {
-        await this.openAdviceDemo();
       }
-      return;
     }
-
-    const records = this.cache.records;
-    const analysis = this.cache.contentAnalysis;
-    if (!records || records.length === 0 || !analysis) {
-      vscode.window.showWarningMessage(I18n.t.popup.noDataMessage);
-      return;
-    }
-
-    // Let the user scope the advice to everything, or to one project.
-    const projects = ClaudeDataLoader.getProjectBreakdown(records);
-    const items: (vscode.QuickPickItem & { scope: string })[] = [
-      { label: I18n.t.popup.adviceScopeOverall, scope: 'overall' },
-      ...projects.map((p) => ({ label: p.groupName, description: p.groupPath, scope: p.groupPath }))
-    ];
-    const picked = await vscode.window.showQuickPick(items, { placeHolder: I18n.t.popup.adviceScopePrompt });
-    if (!picked) {
-      return;
-    }
-
-    const summary = buildAdviceSummary(
-      records,
-      analysis,
-      picked.scope,
-      picked.label,
-      config.advicePromptWindowDays
-    );
-
-    await this.runAdviceRequest(config, picked.scope, picked.label, summary);
-  }
-
-  private async openAdviceDemo(): Promise<void> {
-    const now = new Date();
-    const pad = (n: number): string => String(n).padStart(2, '0');
-    const stamp =
-      `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
-      `_${pad(now.getHours())}${pad(now.getMinutes())}`;
-    const uri = vscode.Uri.parse(`untitled:claude-advice-DEMO-${stamp}.md`);
-    const doc = await vscode.workspace.openTextDocument(uri);
-    const editor = await vscode.window.showTextDocument(doc);
-    const lang = I18n.getCurrentLanguage();
-    const banner = I18n.t.popup.adviceDemoNotice;
-    const body = getDemoBody(lang);
-    const content = `${banner}\n\n---\n\n${body}`;
-    await editor.edit((eb) => eb.insert(new vscode.Position(0, 0), content));
-  }
-
-  private async runAdviceRequest(
-    config: ExtensionConfig,
-    scope: string,
-    label: string,
-    summary: string
-  ): Promise<void> {
-    await vscode.window.withProgress(
-      { location: vscode.ProgressLocation.Notification, title: I18n.t.popup.adviceGenerating },
-      async () => {
-        try {
-          const advice = await getUsageAdvice({
-            backend: config.adviceBackend,
-            apiFormat: config.adviceApiFormat,
-            subscriptionModel: config.adviceSubscriptionModel,
-            getSubscriptionToken: () => this.apiClient.getAccessToken(),
-            apiKey: config.adviceApiKey,
-            apiUrl: config.adviceApiUrl,
-            model: config.adviceModel,
-            reasoningEffort: config.adviceReasoningEffort,
-            userContext: config.adviceUserContext,
-            language: I18n.getLanguageName(),
-            summary
-          });
-
-          // Give the document a distinguishable name like
-          // claude-advice-<scope>-YYYY-MM-DD_HHmm.md so different runs are easy
-          // to tell apart in the tab strip.
-          const now = new Date();
-          const pad = (n: number): string => String(n).padStart(2, '0');
-          const stamp =
-            `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
-            `_${pad(now.getHours())}${pad(now.getMinutes())}`;
-          const safeScope =
-            scope === 'overall'
-              ? 'overall'
-              : (label || 'project').replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 30) || 'project';
-          const uri = vscode.Uri.parse(`untitled:claude-advice-${safeScope}-${stamp}.md`);
-          const doc = await vscode.workspace.openTextDocument(uri);
-          const editor = await vscode.window.showTextDocument(doc);
-          await editor.edit((eb) => eb.insert(new vscode.Position(0, 0), advice));
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          vscode.window.showErrorMessage(`${I18n.t.popup.adviceFailed}: ${message}`);
-        }
-      }
-    );
   }
 
   /**
    * Usage Optimizer round-trip (Phase 9c). Takes the user's rough draft and the
    * three optional lenses, asks the configured model to return a tightened
    * paste-ready prompt plus a settings recommendation, and parses the two
-   * sections out. ONLY the pasted draft is sent — no filesystem access. First
-   * use shows a one-time consent modal (the text is going to a model, not to
-   * Claude Code's terminal).
+   * sections out. ONLY the pasted draft enters the sealed preview — no
+   * filesystem access. A separate Send click is the sole authorization for the
+   * prepared bytes to leave the machine.
    */
   /** Distinct models the user actually uses — Claude reduced to family names
    * (haiku/sonnet/opus/fable), third-party models kept as-is — so the optimizer
@@ -699,30 +1987,17 @@ export class ClaudeCodeUsageExtension {
     return out.slice(0, 8);
   }
 
-  private async runOptimizer(
+  private async prepareOptimizerRequest(
     draft: string,
-    options: { resolve: boolean; distil: boolean; aesthetic: boolean }
-  ): Promise<{ prompt?: string; settings?: string; error?: string }> {
+    options: { resolve: boolean; distil: boolean; aesthetic: boolean },
+    sourceRevision: string,
+    consentGeneration: number,
+  ): Promise<{ prepared?: ReturnType<typeof prepareOptimizerInvocation>; error?: string }> {
     const text = (draft || '').trim();
     if (text === '') {
       return { error: I18n.t.popup.noDataMessage };
     }
 
-    // One-time consent: the draft leaves the machine for whichever model the
-    // advice backend points at. Remember the choice in globalState.
-    const consentKey = 'claudeCodeUsage.optimizerConsented';
-    if (!this.context.globalState.get<boolean>(consentKey, false)) {
-      const proceed = await vscode.window.showWarningMessage(
-        I18n.t.popup.optimizerConsent,
-        { modal: true },
-        I18n.t.popup.optimizerRun
-      );
-      if (proceed !== I18n.t.popup.optimizerRun) {
-        return { error: '' };
-      }
-      await this.context.globalState.update(consentKey, true);
-    }
-
     const config = this.getConfiguration();
     const needsKey =
       config.adviceBackend === 'api' && (!config.adviceApiKey || config.adviceApiKey.trim() === '');
@@ -734,20 +2009,18 @@ export class ClaudeCodeUsageExtension {
     const systemPrompt = buildOptimizerSystemPrompt(language, options, this.usedModelNames());
 
     try {
-      const raw = await callModel(systemPrompt, text, {
-        backend: config.adviceBackend,
+      return { prepared: prepareOptimizerInvocation({
         apiFormat: config.adviceApiFormat,
-        subscriptionModel: config.adviceSubscriptionModel,
-        getSubscriptionToken: () => this.apiClient.getAccessToken(),
-        apiKey: config.adviceApiKey,
         apiUrl: config.adviceApiUrl,
         model: config.adviceModel,
         reasoningEffort: config.adviceReasoningEffort,
-        language,
-        summary: '',
-        timeoutMs: 90_000
-      });
-      return parseOptimizerOutput(raw);
+        systemPrompt,
+        draft: text,
+        sourceRevision,
+        consentGeneration,
+        createdAtEpochMs: Date.now(),
+        timeoutMs: 90_000,
+      }) };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       return { error: `${I18n.t.popup.adviceFailed}: ${message}` };
@@ -756,6 +2029,8 @@ export class ClaudeCodeUsageExtension {
 
   private loadConfiguration(): void {
     const config = this.getConfiguration();
+    this.activePricingBackend = config.pricingBackend;
+    setPricingBackend(config.pricingBackend);
     I18n.setLanguage(config.language as any);
     I18n.setDecimalPlaces(config.decimalPlaces);
     I18n.setTokenDecimalPlaces(config.tokenDecimalPlaces);
@@ -784,13 +2059,14 @@ export class ClaudeCodeUsageExtension {
   }
 
   private getConfiguration(): ExtensionConfig {
-    // All settings now flow through SettingsStore: the core trio (language,
-    // dataDirectory, advice.apiKey) still lives in VS Code config; the rest in
+    // All settings flow through SettingsStore: language and dataDirectory live
+    // in VS Code config, BYOK secrets live in SecretStorage, and the rest use
     // the dashboard-managed store. Defaults come from the settings catalog.
     const s = this.settings;
     return {
       refreshInterval: s.get<number>('refreshInterval'),
       dataDirectory: s.get<string>('dataDirectory'),
+      pricingBackend: s.get<'anthropic' | 'aws-bedrock-in-region'>('pricingBackend'),
       codexEnabled: s.get<boolean>('codex.enabled'),
       codexDataDirectory: s.get<string>('codex.dataDirectory'),
       codexFileWatchSeconds:
@@ -825,7 +2101,6 @@ export class ClaudeCodeUsageExtension {
       // subscription transport remains in advisor.ts.
       adviceBackend: 'api',
       adviceApiFormat: s.get<'anthropic' | 'openai'>('advice.apiFormat'),
-      adviceSubscriptionModel: 'claude-haiku-4-5',
       advicePromptWindowDays: s.get<number>('advice.promptWindowDays'),
       enableContentAnalysis: s.get<boolean>('enableContentAnalysis'),
       projectGroupingMode: s.get<'git' | 'folder' | 'flat'>('projectGroupingMode'),
@@ -842,66 +2117,473 @@ export class ClaudeCodeUsageExtension {
     );
   }
 
-  private createCodexProvider(config: ExtensionConfig): CodexProvider {
-    return new CodexProvider({
-      enabled: config.codexEnabled,
-      codexHome: this.codexHome(config),
-      indexPath: path.join(
-        this.context.globalStorageUri.fsPath,
-        'codex-index-v1.json',
-      ),
-      salt: this.codexSalt,
-      timeZone: resolveTimeZone(config.timezone),
+  private createCodexProvider(config: ExtensionConfig): CodexProvider {
+    return new CodexProvider({
+      enabled: config.codexEnabled,
+      codexHome: this.codexHome(config),
+      indexPath: path.join(
+        this.context.globalStorageUri.fsPath,
+        'codex-index-v1.json',
+      ),
+      salt: this.codexSalt,
+      timeZone: resolveTimeZone(config.timezone),
+    });
+  }
+
+  private syncProviderUi(): void {
+    const config = this.getConfiguration();
+    const claudeHasData = this.cache.records.length > 0;
+    this.webviewProvider.updateAdviceEffectivenessData(
+      this.buildAdviceEffectivenessProviderStates(config),
+    );
+    this.webviewProvider.updateProviderData(
+      this.codexView,
+      this.codexInsights,
+      {
+        claude: claudeHasData,
+        codex: this.codexAvailable,
+        codexData: this.codexHasData,
+        codexLoading: this.codexRefreshing,
+        codexProgress: this.codexProgress
+          ? {
+              scannedFiles: this.codexProgress.scannedFiles,
+              totalFiles: this.codexProgress.totalFiles,
+              indexedBytes: this.codexProgress.indexedBytes,
+              totalBytes: this.codexProgress.totalBytes,
+              reason: this.codexBackgroundState.reason,
+            }
+          : this.codexRefreshing
+            ? {
+                scannedFiles: this.codexView?.coverage.indexedFiles ?? 0,
+                totalFiles: this.codexView?.coverage.totalFiles ?? 0,
+                indexedBytes: this.codexView?.coverage.indexedBytes ?? 0,
+                totalBytes: this.codexView?.coverage.totalBytes ?? 0,
+                reason: this.codexBackgroundState.reason,
+              }
+            : null,
+      },
+    );
+
+    const selected =
+      config.statusBarProvider === 'auto'
+        ? claudeHasData
+          ? 'claude'
+          : this.codexHasData
+            ? 'codex'
+            : 'claude'
+        : config.statusBarProvider;
+    if (selected === 'codex') {
+      if (this.codexView) {
+        this.statusBar.updateCodex(
+          this.codexView.today,
+          config.codexStatusMetric,
+          this.codexView.limit,
+        );
+      }
+      this.statusBar.setProvider('codex');
+    } else {
+      this.statusBar.setProvider('claude');
+    }
+  }
+
+  /**
+   * Build the default-off experimental evidence view from narrow, numeric
+   * inputs already materialized by each provider index. Neither provider
+   * adapter accepts records, paths, session IDs, or prompt bodies.
+   */
+  private buildAdviceEffectivenessProviderStates(
+    config: ExtensionConfig,
+  ): AdviceEffectivenessProviderStates {
+    if (!this.settings.get<boolean>('advice.effectiveness.enabled')) {
+      return {};
+    }
+    const states: AdviceEffectivenessProviderStates = {};
+    const now = Date.now();
+    const generatedAt = new Date(now).toISOString();
+    const epochDay = Math.floor(now / 86_400_000);
+    const windowDays = Math.max(1, Math.round(config.advicePromptWindowDays));
+
+    try {
+      const materialized = claudeUsageDashboardSnapshot(this.cache.claudeIndex, {
+        now: new Date(now),
+        adviceWindowDays: windowDays,
+      });
+      const adviceWindow = materialized.adviceWindow;
+      if (adviceWindow && adviceWindow.aggregate.messageCount > 0) {
+        const aggregate = buildAdviceAggregateSnapshot(
+          adviceWindow.aggregate,
+          'overall',
+          windowDays,
+        );
+        const framework = this.cache.contentAnalysis?.frameworkOverhead;
+        const adapted = adaptClaudeAdvice({
+          adviceId: `advice-claude-${windowDays}d-${epochDay}`,
+          generatedAt,
+          locale: I18n.getLocale(),
+          aggregate,
+          sessionSummary: {
+            scope: 'overall',
+            windowDays,
+            totalSessions: adviceWindow.totalSessions,
+            longSessionCount: adviceWindow.longSessionCount,
+            largeContextSessionCount: adviceWindow.largeContextSessionCount,
+          },
+          ...(framework
+            ? {
+                frameworkOverhead: {
+                  frameworkEstimatedTokens: framework.frameworkEstimatedTokens,
+                  observedInputEstimatedTokens: framework.observedInputEstimatedTokens,
+                  classifiedEvents: framework.classifiedEvents,
+                },
+              }
+            : {}),
+        });
+        if (adapted.ok) {
+          states.claude = {
+            provider: 'claude',
+            contract: adapted.value.contract,
+            remotePreviewEligible: adapted.value.remoteEvidenceEligible,
+            aggregate: adapted.value.aggregate,
+            userContext: config.adviceUserContext,
+            promptSamples: selectAdvicePromptSamples(
+              this.cache.contentAnalysis?.recentPrompts ?? [],
+              now,
+              windowDays,
+            ),
+          };
+        }
+      }
+    } catch {
+      // Conservative degradation: omit the experimental Claude state.
+    }
+
+    try {
+      const view = this.codexView;
+      if (view) {
+        const behavior = view.behaviorScopes.last30Days;
+        const adapted = adaptCodexLocalAdvice({
+          adviceId: `advice-codex-30d-${epochDay}`,
+          generatedAt,
+          locale: I18n.getLocale(),
+          scope: '30d',
+          insights: this.codexInsights.last30Days,
+          behavior: {
+            childFreshShare: behavior.childFreshShare,
+            approvalReviewerFreshShare: behavior.approvalReviewerFreshShare,
+            highEffortFreshShare: behavior.highEffortFreshShare,
+            processedToFreshRatio: behavior.processedToFreshRatio,
+            cacheShare: behavior.cacheShare,
+            postPatchToolCallsPerPatchCall: behavior.postPatchToolCallsPerPatchCall,
+          },
+          quality: {
+            indexComplete: view.coverage.complete,
+            identityComplete: view.coverage.identity.complete,
+            periodComplete: view.periodCoverage.last30Days.complete,
+            qualityFlags: view.qualityFlags.map((flag) => flag.flag),
+          },
+        });
+        if (adapted.ok) {
+          states.codex = {
+            provider: 'codex',
+            contract: adapted.value.contract,
+            remotePreviewEligible: adapted.value.remoteEvidenceEligible,
+            promptSamples: [],
+          };
+        }
+      }
+    } catch {
+      // Existing Codex local recommendations remain authoritative on failure.
+    }
+    return states;
+  }
+
+  private codexHistoricalWorkPending(snapshot: CodexProviderSnapshot | null): boolean {
+    if (!snapshot) return true;
+    const coverage = snapshot.coverage;
+    return !coverage.complete ||
+      !coverage.identity.complete ||
+      !coverage.period.allTime.complete ||
+      !snapshot.hourlyCoverage?.complete;
+  }
+
+  private codexIndexGeneration(snapshot: CodexProviderSnapshot | null): number | null {
+    return snapshot?.indexGeneration ?? null;
+  }
+
+  private codexBackgroundReason(snapshot: CodexProviderSnapshot | null): BackgroundWorkReason {
+    if (!snapshot || snapshot.coverage.totalFiles === 0) return 'first-index';
+    if (!snapshot.coverage.period.allTime.complete) return 'period-migration';
+    if (!snapshot.hourlyCoverage?.complete) return 'hourly-history';
+    return 'history-backfill';
+  }
+
+  private codexBackgroundProgress(snapshot: CodexProviderSnapshot): BackgroundWorkState['progress'] {
+    const main = snapshot.coverage;
+    const period = main.period.allTime;
+    const hourly = snapshot.hourlyCoverage;
+    return {
+      completedUnits: main.indexedFiles + period.migratedFiles + (hourly?.indexedFiles ?? 0),
+      totalUnits: main.totalFiles + period.totalFiles + (hourly?.totalFiles ?? 0),
+      completedBytes: main.indexedBytes + period.migratedBytes + (hourly?.indexedBytes ?? 0),
+      totalBytes: main.totalBytes + period.totalBytes + (hourly?.totalBytes ?? 0),
+    };
+  }
+
+  private async saveCodexBackgroundState(): Promise<void> {
+    const snapshot: BackgroundWorkState = {
+      ...this.codexBackgroundState,
+      progress: { ...this.codexBackgroundState.progress },
+    };
+    const previous = this.codexBackgroundStateWrite;
+    const write = previous
+      .catch(() => undefined)
+      .then(() => this.context.globalState.update(
+        ClaudeCodeUsageExtension.CODEX_BACKGROUND_WORK_STATE_KEY,
+        snapshot,
+      ));
+    this.codexBackgroundStateWrite = write;
+    await write;
+  }
+
+  private trackResourceStop(stop: Promise<unknown>): void {
+    let tracked!: Promise<void>;
+    tracked = stop
+      .then(() => undefined)
+      .catch((error: unknown) => {
+        this.resourceStopFailure ??= error;
+        throw error;
+      })
+      .finally(() => this.pendingResourceStops.delete(tracked));
+    this.pendingResourceStops.add(tracked);
+    // The owning lifecycle later drains and reports the failure. Attaching a
+    // handler here prevents a fire-and-forget watcher close from becoming an
+    // unhandled rejection before disposal reaches that drain point.
+    void tracked.catch(() => undefined);
+  }
+
+  private async drainResourceStops(): Promise<void> {
+    while (this.pendingResourceStops.size > 0) {
+      await Promise.allSettled([...this.pendingResourceStops]);
+    }
+    if (this.resourceStopFailure) {
+      const failure = this.resourceStopFailure;
+      this.resourceStopFailure = null;
+      throw failure;
+    }
+  }
+
+  private async runAdviceNetwork<T>(
+    request: (signal: AbortSignal) => Promise<T>,
+    surface: 'advice' | 'optimizer' = 'advice',
+  ): Promise<T> {
+    if (this.disposed) {
+      throw new Error('Extension is disposed');
+    }
+    const controller = new AbortController();
+    const lease = this.resourceOwnership.register({
+      kind: 'network',
+      capability: 'advice-personalization',
+      scope: 'advice',
+      creator: 'advice-runtime',
+      stopConditions: [
+        'settled',
+        'cancelled',
+        'feature-disabled',
+        'extension-dispose',
+        'settings-change',
+      ],
+      boundedException: 'none',
+    });
+    let markSettled!: () => void;
+    const settled = new Promise<void>((resolve) => {
+      markSettled = resolve;
+    });
+    this.activeAdviceNetworks.set(controller, { lease, settled, surface });
+    try {
+      return await request(controller.signal);
+    } finally {
+      this.activeAdviceNetworks.delete(controller);
+      markSettled();
+      if (lease.active) {
+        await lease.stop(controller.signal.aborted ? 'cancelled' : 'settled', () => undefined);
+      }
+    }
+  }
+
+  private async cancelAdviceNetworks(
+    condition: Extract<
+      ResourceStopCondition,
+      'cancelled' | 'feature-disabled' | 'extension-dispose' | 'settings-change'
+    >,
+    surface?: 'advice' | 'optimizer',
+  ): Promise<void> {
+    const active = [...this.activeAdviceNetworks.entries()]
+      .filter(([, operation]) => surface === undefined || operation.surface === surface);
+    await Promise.all(active.map(async ([controller, operation]) => {
+      const { lease, settled } = operation;
+      if (lease.active) {
+        await lease.stop(condition, async () => {
+          controller.abort();
+          await settled;
+        });
+      }
+      this.activeAdviceNetworks.delete(controller);
+    }));
+  }
+
+  private async cancelQuotaNetworks(
+    condition: Extract<
+      ResourceStopCondition,
+      | 'cancelled'
+      | 'window-blur'
+      | 'feature-disabled'
+      | 'extension-dispose'
+      | 'settings-change'
+      | 'profile-change'
+    >,
+  ): Promise<void> {
+    const active = [...this.activeQuotaNetworks.entries()];
+    await Promise.all(active.map(async ([controller, operation]) => {
+      const { lease, settled } = operation;
+      if (lease.active) {
+        await lease.stop(condition, async () => {
+          controller.abort();
+          await settled;
+        });
+      }
+      this.activeQuotaNetworks.delete(controller);
+    }));
+  }
+
+  private createOwnedRefreshDebounce(
+    scope: 'claude' | 'codex',
+  ): QuietDebounce {
+    return new QuietDebounce(
+      (callback, ms) => {
+        if (this.disposed) {
+          return undefined as unknown as NodeJS.Timeout;
+        }
+        let timer!: NodeJS.Timeout;
+        timer = setTimeout(() => {
+          const lease = this.debounceTimerLeases.get(timer);
+          this.debounceTimerLeases.delete(timer);
+          if (lease?.active) {
+            this.trackResourceStop(lease.stop('settled', () => undefined));
+          }
+          if (!this.disposed) callback();
+        }, ms);
+        const lease = this.resourceOwnership.register({
+          kind: 'timer',
+          capability: 'refresh',
+          scope,
+          creator: 'refresh-coordinator',
+          stopConditions: [
+            'settled',
+            'cancelled',
+            'window-blur',
+            'feature-disabled',
+            'extension-dispose',
+            'settings-change',
+          ],
+          boundedException: 'none',
+        });
+        this.debounceTimerLeases.set(timer, lease);
+        return timer;
+      },
+      (timer) => {
+        if (!timer) return;
+        const lease = this.debounceTimerLeases.get(timer);
+        this.debounceTimerLeases.delete(timer);
+        if (lease?.active) {
+          this.trackResourceStop(lease.stop('cancelled', () => clearTimeout(timer)));
+        }
+        else clearTimeout(timer);
+      },
+    );
+  }
+
+  private scheduleQuotaColdRetry(): void {
+    if (
+      this.disposed ||
+      this.quotaColdRetryTimer ||
+      !this.windowActivity.focused ||
+      !this.getConfiguration().usageLimitTracking
+    ) {
+      return;
+    }
+    this.quotaColdRetryTimer = setTimeout(() => {
+      const lease = this.quotaColdRetryTimerLease;
+      this.quotaColdRetryTimer = undefined;
+      this.quotaColdRetryTimerLease = undefined;
+      if (lease?.active) {
+        this.trackResourceStop(lease.stop('settled', () => undefined));
+      }
+      if (
+        this.disposed ||
+        !this.windowActivity.focused ||
+        !this.getConfiguration().usageLimitTracking
+      ) {
+        return;
+      }
+      void this.maybeFetchUsageLimits(this.getConfiguration()).then((retry) => {
+        if (retry) {
+          this.statusBar.updateQuota(retry);
+          this.webviewProvider.updateQuota(retry);
+        }
+      });
+    }, 8_000);
+    this.quotaColdRetryTimerLease = this.resourceOwnership.register({
+      kind: 'timer',
+      capability: 'quota',
+      scope: 'claude',
+      creator: 'refresh-coordinator',
+      stopConditions: [
+        'settled',
+        'window-blur',
+        'feature-disabled',
+        'extension-dispose',
+        'settings-change',
+        'profile-change',
+      ],
+      boundedException: 'none',
     });
   }
 
-  private syncProviderUi(): void {
-    const config = this.getConfiguration();
-    const claudeHasData = this.cache.records.length > 0;
-    this.webviewProvider.updateProviderData(
-      this.codexView,
-      this.codexInsights,
-      {
-        claude: claudeHasData,
-        codex: this.codexAvailable,
-        codexData: this.codexHasData,
-        codexLoading: this.codexRefreshing,
-        codexProgress: this.codexProgress
-          ? {
-              scannedFiles: this.codexProgress.scannedFiles,
-              totalFiles: this.codexProgress.totalFiles,
-              indexedBytes: this.codexProgress.indexedBytes,
-              totalBytes: this.codexProgress.totalBytes,
-            }
-          : null,
-      },
-    );
-
-    const selected =
-      config.statusBarProvider === 'auto'
-        ? claudeHasData
-          ? 'claude'
-          : this.codexHasData
-            ? 'codex'
-            : 'claude'
-        : config.statusBarProvider;
-    if (selected === 'codex') {
-      if (this.codexView?.lastTask) {
-        this.statusBar.updateCodex(
-          this.codexView.lastTask,
-          config.codexStatusMetric,
-          this.codexView.limit,
-        );
+  private stopQuotaColdRetry(
+    condition: Extract<
+      ResourceStopCondition,
+      | 'window-blur'
+      | 'feature-disabled'
+      | 'extension-dispose'
+      | 'settings-change'
+      | 'profile-change'
+    >,
+  ): void {
+    const timer = this.quotaColdRetryTimer;
+    const lease = this.quotaColdRetryTimerLease;
+    this.quotaColdRetryTimer = undefined;
+    this.quotaColdRetryTimerLease = undefined;
+    if (timer) {
+      if (lease?.active) {
+        this.trackResourceStop(lease.stop(condition, () => clearTimeout(timer)));
       }
-      this.statusBar.setProvider('codex');
-    } else {
-      this.statusBar.setProvider('claude');
+      else clearTimeout(timer);
     }
   }
 
   private async refreshCodexData(trigger: RefreshTrigger): Promise<void> {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
+    const generation = this.configurationGeneration;
+    try {
+      await this.waitForCodexProviderRetirements();
+    } catch {
+      return;
+    }
+    if (this.disposed || generation !== this.configurationGeneration) return;
+    const operation = this.runCodexRefresh(trigger);
+    this.activeCodexRefreshes.add(operation);
     try {
-      await this.runCodexRefresh(trigger);
+      await operation;
     } catch {
       this.codexView = null;
       this.codexInsights = emptyCodexScopedInsights();
@@ -909,6 +2591,7 @@ export class ClaudeCodeUsageExtension {
       this.codexRefreshing = false;
       this.codexProgress = null;
       this.codexProgressLastRenderedAt = 0;
+      if (this.disposed) return;
       this.outputChannel.appendLine(
         formatCodexIndexDiagnostic({
           outcome: 'error',
@@ -927,12 +2610,41 @@ export class ClaudeCodeUsageExtension {
         }),
       );
       this.syncProviderUi();
+    } finally {
+      this.activeCodexRefreshes.delete(operation);
+    }
+  }
+
+  private async cancelCodexProviderAndWait(provider = this.codexProvider): Promise<void> {
+    const lifecycleProvider = provider as CodexProvider & {
+      cancelAndWait?: () => Promise<void>;
+    };
+    if (typeof lifecycleProvider.cancelAndWait === 'function') {
+      await lifecycleProvider.cancelAndWait();
+      return;
     }
+    // Retains compatibility with narrow provider doubles while production
+    // always uses the awaitable Codex provider lifecycle.
+    provider.cancel();
   }
 
   private async runCodexRefresh(trigger: RefreshTrigger): Promise<void> {
+    if (this.disposed) return;
+    let ownedBackfillLease: ResourceLease | undefined;
+    let ownedWorkerLease: ResourceLease | undefined;
+    let workerStoppedSafely = false;
+    let continueHistoricalWork = false;
     const config = this.getConfiguration();
     if (!config.codexEnabled) {
+      await this.cancelCodexProviderAndWait();
+      if (this.codexBackfillLease?.active) {
+        await this.codexBackfillLease.stop('feature-disabled', () => undefined);
+      }
+      this.codexBackfillLease = undefined;
+      if (this.codexWorkerLease?.active) {
+        await this.codexWorkerLease.stop('feature-disabled', () => undefined);
+      }
+      this.codexWorkerLease = undefined;
       this.codexView = null;
       this.codexInsights = emptyCodexScopedInsights();
       this.codexAvailable = false;
@@ -944,6 +2656,7 @@ export class ClaudeCodeUsageExtension {
       return;
     }
     this.codexAvailable = await this.codexProvider.isAvailable();
+    if (this.disposed) return;
     if (!this.codexAvailable) {
       this.codexView = null;
       this.codexInsights = emptyCodexScopedInsights();
@@ -961,18 +2674,133 @@ export class ClaudeCodeUsageExtension {
     const provider = this.codexProvider;
     this.codexCheckpointHydrationLastAttemptAt = Date.now();
     const persisted = await provider.loadPersistedSnapshot();
-    if (provider !== this.codexProvider) {
+    if (this.disposed || provider !== this.codexProvider) {
       return;
     }
     if (persisted) {
       this.applyCodexSnapshot(persisted);
+      if (this.codexBackgroundState.indexGeneration !== this.codexIndexGeneration(persisted)) {
+        this.codexBackgroundState = createBackgroundWorkState({
+          measurementVersion:
+            ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+          reason: this.codexBackgroundReason(persisted),
+          now: Date.now(),
+          progress: this.codexBackgroundProgress(persisted),
+          indexGeneration: this.codexIndexGeneration(persisted),
+        });
+        await this.saveCodexBackgroundState();
+      }
       this.syncProviderUi();
     }
+    if (!persisted && this.codexBackgroundState.status === 'complete') {
+      this.codexBackgroundState = createBackgroundWorkState({
+        measurementVersion:
+          ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+        reason: 'first-index',
+        now: Date.now(),
+        indexGeneration: null,
+      });
+      await this.saveCodexBackgroundState();
+    }
+    const historicalPending = this.codexHistoricalWorkPending(persisted);
+    let historicalAttempt = false;
+    if (historicalPending) {
+      const started = beginBackgroundWork(this.codexBackgroundState, {
+        trigger: trigger === 'manual' ? 'manual' : 'automatic',
+        now: Date.now(),
+        reason: this.codexBackgroundReason(persisted),
+      });
+      this.codexBackgroundState = started.state;
+      historicalAttempt = started.started;
+      try {
+        await this.saveCodexBackgroundState();
+      } catch (error) {
+        if (historicalAttempt && this.codexBackgroundState.status === 'running') {
+          this.codexBackgroundState = interruptBackgroundWork(
+            this.codexBackgroundState,
+            { now: Date.now() },
+          );
+          await this.saveCodexBackgroundState().catch(() => undefined);
+        }
+        throw error;
+      }
+      if (historicalAttempt) {
+        ownedBackfillLease = this.resourceOwnership.register({
+          kind: 'backfill',
+          capability: 'codex-history',
+          scope: 'codex',
+          creator: 'refresh-coordinator',
+          stopConditions: [
+            'settled',
+            'completed',
+            'cancelled',
+            'feature-disabled',
+            'extension-dispose',
+            'user-pause',
+            'settings-change',
+          ],
+          boundedException: persisted ? 'none' : 'first-codex-history',
+        });
+        this.codexBackfillLease = ownedBackfillLease;
+        this.codexFirstBackfillActive = !persisted;
+      }
+    } else if (
+      this.codexBackgroundState.status !== 'complete' &&
+      this.codexBackgroundState.pausedReason !== 'corrupt-state' &&
+      persisted
+    ) {
+      const fresh = createBackgroundWorkState({
+        measurementVersion:
+          ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+        reason: this.codexBackgroundReason(persisted),
+        now: Date.now(),
+        progress: this.codexBackgroundProgress(persisted),
+        indexGeneration: this.codexIndexGeneration(persisted),
+      });
+      const running = beginBackgroundWork(fresh, {
+        trigger: 'automatic',
+        now: Date.now(),
+      });
+      if (running.started) {
+        this.codexBackgroundState = recordBackgroundWorkProgress(running.state, {
+          now: Date.now(),
+          complete: true,
+          progress: this.codexBackgroundProgress(persisted),
+        });
+        await this.saveCodexBackgroundState();
+      }
+    }
+    // The trigger reason is visible while metadata discovery and the first
+    // worker progress event are still pending.
+    this.syncProviderUi();
     try {
+      if (!this.codexWorkerLease?.active) {
+        ownedWorkerLease = this.resourceOwnership.register({
+          kind: 'worker',
+          capability: 'codex-index',
+          scope: 'codex',
+          creator: 'codex-index-client',
+          stopConditions: [
+            'settled',
+            'cancelled',
+            'feature-disabled',
+            'extension-dispose',
+            'settings-change',
+          ],
+          boundedException: 'none',
+        });
+        this.codexWorkerLease = ownedWorkerLease;
+        this.codexWorkerCancellationRequested = false;
+      }
       const result = await provider.refresh(
         codexRefreshProfileForTrigger(trigger),
         (progress) => this.onCodexIndexProgress(progress),
+        historicalAttempt,
       );
+      workerStoppedSafely = true;
+      if (this.disposed || provider !== this.codexProvider) {
+        return;
+      }
       if (result.outcome === 'unavailable') {
         this.codexView = null;
         this.codexInsights = emptyCodexScopedInsights();
@@ -982,7 +2810,60 @@ export class ClaudeCodeUsageExtension {
       }
 
       this.applyCodexSnapshot(result.snapshot);
+      if (this.codexBackgroundState.indexGeneration !== this.codexIndexGeneration(result.snapshot)) {
+        this.codexBackgroundState = createBackgroundWorkState({
+          measurementVersion:
+            ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+          reason: this.codexBackgroundReason(result.snapshot),
+          now: Date.now(),
+          progress: this.codexBackgroundProgress(result.snapshot),
+          indexGeneration: this.codexIndexGeneration(result.snapshot),
+        });
+        await this.saveCodexBackgroundState();
+      }
+      if (historicalAttempt && this.codexBackgroundState.status === 'running') {
+        const complete = !this.codexHistoricalWorkPending(result.snapshot);
+        if (this.codexWorkerCancellationRequested || provider !== this.codexProvider) {
+          this.codexBackgroundState = interruptBackgroundWork(
+            this.codexBackgroundState,
+            { now: Date.now() },
+          );
+        } else if (result.outcome === 'error' || (result.diagnostic?.failedFiles ?? 0) > 0) {
+          this.codexBackgroundState = recordBackgroundWorkFailure(
+            this.codexBackgroundState,
+            { now: Date.now() },
+          );
+        } else {
+          this.codexBackgroundState = recordBackgroundWorkProgress(
+            this.codexBackgroundState,
+            {
+              now: Date.now(),
+              complete,
+              progress: this.codexBackgroundProgress(result.snapshot),
+            },
+          );
+          continueHistoricalWork = this.codexBackgroundState.status === 'eligible';
+        }
+        await this.saveCodexBackgroundState();
+      }
       const diagnostic = result.diagnostic;
+      if (
+        !historicalAttempt &&
+        diagnostic?.indexRecovery &&
+        this.codexBackgroundState.status === 'complete' &&
+        this.codexHistoricalWorkPending(result.snapshot)
+      ) {
+        this.codexBackgroundState = createBackgroundWorkState({
+          measurementVersion:
+            ClaudeCodeUsageExtension.CODEX_BACKGROUND_MEASUREMENT_VERSION,
+          reason: this.codexBackgroundReason(result.snapshot),
+          now: Date.now(),
+          progress: this.codexBackgroundProgress(result.snapshot),
+          indexGeneration: this.codexIndexGeneration(result.snapshot),
+        });
+        await this.saveCodexBackgroundState();
+        continueHistoricalWork = true;
+      }
       this.outputChannel.appendLine(
         formatCodexIndexDiagnostic({
           outcome: result.outcome,
@@ -1003,10 +2884,56 @@ export class ClaudeCodeUsageExtension {
         }),
       );
     } finally {
+      this.stopFirstBackfillBlurDeadline('cancelled');
+      if (historicalAttempt && this.codexBackgroundState.status === 'running') {
+        this.codexBackgroundState =
+          this.codexWorkerCancellationRequested || provider !== this.codexProvider
+          ? interruptBackgroundWork(this.codexBackgroundState, { now: Date.now() })
+          : recordBackgroundWorkFailure(
+              this.codexBackgroundState,
+              { now: Date.now() },
+            );
+        await this.saveCodexBackgroundState();
+      }
+      if (workerStoppedSafely && ownedBackfillLease?.active) {
+        const condition = this.codexBackgroundState.status === 'complete'
+          ? 'completed'
+          : 'settled';
+        await ownedBackfillLease.stop(condition, () => undefined);
+      }
+      if (
+        workerStoppedSafely &&
+        this.codexBackfillLease === ownedBackfillLease
+      ) {
+        this.codexBackfillLease = undefined;
+      }
+      if (workerStoppedSafely && ownedWorkerLease?.active) {
+        await ownedWorkerLease.stop(
+          this.codexWorkerCancellationRequested || provider !== this.codexProvider
+            ? 'cancelled'
+            : 'settled',
+          () => undefined,
+        );
+      }
+      if (workerStoppedSafely && this.codexWorkerLease === ownedWorkerLease) {
+        this.codexWorkerLease = undefined;
+      }
+      if (workerStoppedSafely && ownedBackfillLease) {
+        this.codexFirstBackfillActive = false;
+      }
       this.codexRefreshing = false;
       this.codexProgress = null;
       this.codexProgressLastRenderedAt = 0;
-      this.syncProviderUi();
+      if (!this.disposed) this.syncProviderUi();
+      if (
+        !this.disposed &&
+        continueHistoricalWork &&
+        provider === this.codexProvider &&
+        this.getConfiguration().codexEnabled &&
+        this.windowActivity.focused
+      ) {
+        queueMicrotask(() => void this.refreshCodexData(trigger));
+      }
     }
   }
 
@@ -1024,15 +2951,43 @@ export class ClaudeCodeUsageExtension {
         totalFiles: progress.totalFiles,
         indexedBytes: progress.indexedBytes,
         totalBytes: progress.totalBytes,
+        reason: this.codexBackgroundState.reason,
       });
     }
   }
 
   private applyCodexSnapshot(snapshot: CodexProviderSnapshot): void {
     this.codexView = buildCodexUsageView(snapshot);
+    const capturedObservations = snapshot.weeklyValueInputs?.observations ?? [];
+    const capturedQuotaFacts = codexQuotaCapturesFromWeeklyObservations(
+      capturedObservations,
+    );
+    const previewStore = capturedQuotaFacts.length > 0
+      ? mergeQuotaCaptures(this.quotaObservationStore, capturedQuotaFacts, {
+          salt: this.quotaFingerprintSalt,
+          now: capturedQuotaFacts.reduce(
+            (latest, item) => Math.max(latest, item.observedAt),
+            Date.now(),
+          ),
+        })
+      : this.quotaObservationStore;
+    const storedCodexObservations = quotaStoreWeeklyObservations(
+      previewStore,
+      'codex',
+    );
+    if (storedCodexObservations.length > 0 && this.codexView.weeklyValueInputs) {
+      this.codexView.weeklyValueInputs = {
+        ...this.codexView.weeklyValueInputs,
+        observations: storedCodexObservations,
+      };
+    }
     this.codexInsights = buildScopedCodexInsights(this.codexView);
     this.codexAvailable = true;
     this.codexHasData = snapshot.coverage.totalFiles > 0;
+    void this.recordCodexQuotaObservations(capturedObservations).catch(() => {
+      // P1 remains readable when P2 is temporarily unavailable. The next
+      // refresh retries the exact idempotent observation set.
+    });
   }
 
   /** Adopt the first atomic checkpoint during a brand-new cold index. */
@@ -1093,6 +3048,7 @@ export class ClaudeCodeUsageExtension {
 
   /** Dashboard Settings change — status-bar-only toggles apply in place, others reload. */
   private onSettingsChangedFromPanel(key?: string): void {
+    if (this.disposed) return;
     if (key && ClaudeCodeUsageExtension.DASHBOARD_ONLY_SETTINGS.has(key)) {
       this.syncProviderUi();
       return;
@@ -1107,8 +3063,65 @@ export class ClaudeCodeUsageExtension {
     this.onConfigurationChanged();
   }
 
+  private trackCodexProviderRetirement(provider: CodexProvider): Promise<void> {
+    let tracked!: Promise<void>;
+    tracked = Promise.resolve()
+      .then(() => provider.dispose())
+      .catch((error: unknown) => {
+        this.codexProviderRetirementFailure ??= error;
+        throw error;
+      })
+      .finally(() => this.codexProviderRetirements.delete(tracked));
+    this.codexProviderRetirements.add(tracked);
+    void tracked.catch(() => undefined);
+    return tracked;
+  }
+
+  private async waitForCodexProviderRetirements(): Promise<void> {
+    while (this.codexProviderRetirements.size > 0) {
+      await Promise.all([...this.codexProviderRetirements]);
+    }
+    if (this.codexProviderRetirementFailure) {
+      throw this.codexProviderRetirementFailure;
+    }
+  }
+
+  private async releaseCodexOwnership(
+    condition: Extract<
+      ResourceStopCondition,
+      'cancelled' | 'feature-disabled' | 'extension-dispose' | 'settings-change'
+    >,
+  ): Promise<void> {
+    if (this.codexWorkerLease?.active) {
+      await this.codexWorkerLease.stop(condition, () => undefined);
+    }
+    if (this.codexBackfillLease?.active) {
+      await this.codexBackfillLease.stop(condition, () => undefined);
+    }
+    this.codexWorkerLease = undefined;
+    this.codexBackfillLease = undefined;
+  }
+
   private onConfigurationChanged(): void {
+    if (
+      this.disposed ||
+      this.clearingAllLocalData ||
+      this.localDataClearedRequiresReload
+    ) return;
+    const generation = ++this.configurationGeneration;
+    // Any endpoint/model/key/consent-affecting configuration change invalidates
+    // a visible preview before a later click could send it.
+    this.webviewProvider.invalidatePreparedAiRequests();
+    void this.cancelAdviceNetworks('settings-change');
+    this.stopQuotaColdRetry('settings-change');
+    void this.cancelQuotaNetworks('settings-change');
     const config = this.getConfiguration();
+    const pricingBackendChanged = this.activePricingBackend !== config.pricingBackend;
+    this.activePricingBackend = config.pricingBackend;
+    setPricingBackend(config.pricingBackend);
+    if (pricingBackendChanged) {
+      this.invalidateClaudeUsagePricingCache();
+    }
     I18n.setLanguage(config.language as any);
     I18n.setDecimalPlaces(config.decimalPlaces);
     I18n.setTokenDecimalPlaces(config.tokenDecimalPlaces);
@@ -1124,26 +3137,61 @@ export class ClaudeCodeUsageExtension {
     this.stopCodexWatching();
     this.stopCredentialsWatching();
     this.selectClaudeProfile(config.dataDirectory);
-    this.codexProvider.dispose();
+    const retiringCodexProvider = this.codexProvider;
+    this.codexWorkerCancellationRequested = true;
+    retiringCodexProvider.cancel();
+    this.trackCodexProviderRetirement(retiringCodexProvider);
     this.codexProvider = this.createCodexProvider(config);
     if (!this.windowActivity.focused) {
       return;
     }
-    void this.refreshData(true, 'settings').then(() => {
-      void this.startFileWatching();
-      this.startCodexWatching();
-      this.startCredentialsWatching();
-    });
+    void (async () => {
+      try {
+        await this.waitForCodexProviderRetirements();
+        if (this.disposed || generation !== this.configurationGeneration) return;
+        await this.releaseCodexOwnership('settings-change');
+        await this.refreshData(true, 'settings');
+        if (this.disposed || generation !== this.configurationGeneration) return;
+        await this.startFileWatching();
+        if (this.disposed || generation !== this.configurationGeneration) return;
+        this.startCodexWatching();
+        this.startCredentialsWatching();
+      } catch {
+        // A provider that cannot be terminated stays fail-closed. Disposal will
+        // surface the retained failure instead of starting an unowned replacement.
+      }
+    })();
+  }
+
+  /**
+   * Pricing is part of every cached UsageData aggregate. The incremental
+   * loader normally skips unchanged JSONL files, so changing the pricing
+   * backend would otherwise update only the displayed rate labels while
+   * leaving totalCost/modelBreakdown.cost at the old rates.
+   */
+  private invalidateClaudeUsagePricingCache(): void {
+    this.cache.claudeIndex = createClaudeUsageIndex();
+    this.cache.records = [];
+    this.cache.contentAnalysis = null;
+    this.cache.manifest = null;
+    this.cache.dataDirectory = null;
+    this.cache.lastUpdate = new Date(0);
   }
 
   /** Keep quota credentials on the same Claude profile as this window's logs.
    * A profile switch invalidates every in-memory quota/backoff value because it
    * belongs to a different account. */
   private selectClaudeProfile(dataDirectory?: string | null): void {
-    const nextClient = new ClaudeApiClient(this.outputChannel, dataDirectory);
+    const nextClient = new ClaudeApiClient(
+      this.outputChannel,
+      dataDirectory,
+      this.quotaFingerprintSalt,
+    );
     if (nextClient.getCredentialsPath() === this.apiClient.getCredentialsPath()) {
       return;
     }
+    this.stopQuotaColdRetry('profile-change');
+    void this.cancelQuotaNetworks('profile-change');
     this.apiClient = nextClient;
     this.claudeProfileGeneration += 1;
     this.cache.usageLimits = null;
@@ -1154,8 +3202,13 @@ export class ClaudeCodeUsageExtension {
     this.statusBar.updateQuota(null);
     this.webviewProvider.updateQuota(null);
     this.claudeWeeklyQuotaHistory = [];
+    this.activeClaudeQuotaFingerprint = fingerprintForStableIdentity(
+      this.quotaFingerprintSalt,
+      'claude',
+      this.claudeProfileContinuitySignal(),
+    );
     this.webviewProvider.updateWeeklyQuotaHistory([]);
-    this.loadPersistedQuota();
+    this.refreshQuotaObservationViews();
   }
 
   /**
@@ -1165,18 +3218,33 @@ export class ClaudeCodeUsageExtension {
    * filesystems do not support recursive watching).
    */
   private async startFileWatching(): Promise<void> {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
+    const requestGeneration = ++this.fileWatcherGeneration;
     if (!this.windowActivity.focused) {
-      this.stopFileWatching();
+      this.stopFileWatching('window-blur');
       return;
     }
     const config = this.getConfiguration();
     if (!(config.fileWatchSeconds > 0)) {
-      this.stopFileWatching(); // "Off"
+      this.stopFileWatching('feature-disabled'); // "Off"
       return;
     }
     const dataDirectory = await ClaudeDataLoader.findClaudeDataDirectory(config.dataDirectory || undefined);
+    if (
+      this.disposed ||
+      requestGeneration !== this.fileWatcherGeneration
+    ) {
+      return;
+    }
     if (!this.windowActivity.focused) {
-      this.stopFileWatching();
+      this.stopFileWatching('window-blur');
+      return;
+    }
+    const currentConfig = this.getConfiguration();
+    if (
+      !(currentConfig.fileWatchSeconds > 0) ||
+      currentConfig.dataDirectory !== config.dataDirectory
+    ) {
       return;
     }
     if (!dataDirectory) {
@@ -1187,8 +3255,10 @@ export class ClaudeCodeUsageExtension {
       return;
     }
     this.stopFileWatching();
+    const activeGeneration = this.fileWatcherGeneration;
     try {
-      this.fileWatcher = fs.watch(projectsDir, { recursive: true }, (_event, filename) => {
+      const watcher = fs.watch(projectsDir, { recursive: true }, (_event, filename) => {
+        if (this.disposed || activeGeneration !== this.fileWatcherGeneration) return;
         if (!filename || !String(filename).endsWith('.jsonl')) {
           return;
         }
@@ -1198,40 +3268,78 @@ export class ClaudeCodeUsageExtension {
         this.watcherEventsSinceRefresh += 1;
         const delaySeconds = this.getConfiguration().fileWatchSeconds;
         if (!(delaySeconds > 0)) {
-          this.stopFileWatching();
+          this.stopFileWatching('feature-disabled');
           return;
         }
         this.watchDebounce.push(delaySeconds * 1000, () => {
           void this.refreshData(false, 'watch');
         });
       });
+      this.fileWatcher = watcher;
       this.watchedDir = projectsDir;
+      this.fileWatcherLease = this.resourceOwnership.register({
+        kind: 'watcher',
+        capability: 'refresh',
+        scope: 'claude',
+        creator: 'extension',
+        stopConditions: [
+          'window-blur',
+          'feature-disabled',
+          'extension-dispose',
+          'settings-change',
+          'profile-change',
+          'cancelled',
+        ],
+        boundedException: 'none',
+      });
+      watcher.on('error', (error) => {
+        if (this.fileWatcher !== watcher || activeGeneration !== this.fileWatcherGeneration) return;
+        const code = (error as NodeJS.ErrnoException).code || 'watch-error';
+        this.outputChannel.appendLine(
+          `Claude file watcher stopped (${code}); polling remains active.`,
+        );
+        this.stopFileWatching('cancelled');
+      });
     } catch {
       // Recursive watching unsupported — the polling timer is enough.
     }
   }
 
-  private stopFileWatching(): void {
+  private stopFileWatching(
+    condition: Extract<
+      ResourceStopCondition,
+      'cancelled' | 'window-blur' | 'feature-disabled' | 'extension-dispose' | 'settings-change' | 'profile-change'
+    > = 'settings-change',
+  ): void {
+    this.fileWatcherGeneration += 1;
     this.watchDebounce.clear();
-    if (this.fileWatcher) {
-      try {
-        this.fileWatcher.close();
-      } catch {
-        // Already closed.
-      }
-      this.fileWatcher = undefined;
+    const watcher = this.fileWatcher;
+    const lease = this.fileWatcherLease;
+    this.fileWatcher = undefined;
+    this.fileWatcherLease = undefined;
+    if (watcher) {
+      const close = (): void => {
+        try {
+          watcher.close();
+        } catch {
+          // Already closed.
+        }
+      };
+      if (lease?.active) this.trackResourceStop(lease.stop(condition, close));
+      else close();
     }
     this.watchedDir = null;
   }
 
   private startCodexWatching(): void {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
     if (!this.windowActivity.focused) {
-      this.stopCodexWatching();
+      this.stopCodexWatching('window-blur');
       return;
     }
     const config = this.getConfiguration();
     if (!config.codexEnabled || !(config.codexFileWatchSeconds > 0)) {
-      this.stopCodexWatching();
+      this.stopCodexWatching('feature-disabled');
       return;
     }
     const codexHome = this.codexHome(config);
@@ -1239,6 +3347,7 @@ export class ClaudeCodeUsageExtension {
       return;
     }
     this.stopCodexWatching();
+    const activeGeneration = this.codexWatcherGeneration;
     for (const child of ['sessions', 'archived_sessions']) {
       const directory = path.join(codexHome, child);
       if (!fs.existsSync(directory)) {
@@ -1249,12 +3358,13 @@ export class ClaudeCodeUsageExtension {
           directory,
           { recursive: true },
           (_event, filename) => {
+            if (this.disposed || activeGeneration !== this.codexWatcherGeneration) return;
             if (!filename || !String(filename).endsWith('.jsonl')) {
               return;
             }
             const delaySeconds = this.getConfiguration().codexFileWatchSeconds;
             if (!(delaySeconds > 0)) {
-              this.stopCodexWatching();
+              this.stopCodexWatching('feature-disabled');
               return;
             }
             this.codexWatchDebounce.push(delaySeconds * 1000, () => {
@@ -1263,6 +3373,19 @@ export class ClaudeCodeUsageExtension {
           },
         );
         this.codexWatchers.push(watcher);
+        this.codexWatcherLeases.set(watcher, this.resourceOwnership.register({
+          kind: 'watcher',
+          capability: 'codex-index',
+          scope: 'codex',
+          creator: 'extension',
+          stopConditions: [
+            'window-blur',
+            'feature-disabled',
+            'extension-dispose',
+            'settings-change',
+          ],
+          boundedException: 'none',
+        }));
       } catch {
         // Polling remains available when recursive watches are unsupported.
       }
@@ -1271,16 +3394,28 @@ export class ClaudeCodeUsageExtension {
       this.codexWatchers.length > 0 ? codexHome : null;
   }
 
-  private stopCodexWatching(): void {
+  private stopCodexWatching(
+    condition: Extract<
+      ResourceStopCondition,
+      'window-blur' | 'feature-disabled' | 'extension-dispose' | 'settings-change'
+    > = 'settings-change',
+  ): void {
+    this.codexWatcherGeneration += 1;
     this.codexWatchDebounce.clear();
     for (const watcher of this.codexWatchers) {
-      try {
-        watcher.close();
-      } catch {
-        // Already closed.
-      }
+      const close = (): void => {
+        try {
+          watcher.close();
+        } catch {
+          // Already closed.
+        }
+      };
+      const lease = this.codexWatcherLeases.get(watcher);
+      if (lease?.active) this.trackResourceStop(lease.stop(condition, close));
+      else close();
     }
     this.codexWatchers = [];
+    this.codexWatcherLeases.clear();
     this.codexWatchedHome = null;
   }
 
@@ -1295,8 +3430,9 @@ export class ClaudeCodeUsageExtension {
    * watch — those still self-correct on the next refresh tick.
    */
   private startCredentialsWatching(): void {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
     if (!this.windowActivity.focused) {
-      this.stopCredentialsWatching();
+      this.stopCredentialsWatching('window-blur');
       return;
     }
     this.stopCredentialsWatching();
@@ -1307,16 +3443,64 @@ export class ClaudeCodeUsageExtension {
       return;
     }
     try {
+      const activeGeneration = this.credentialsWatcherGeneration;
       this.credsWatcher = fs.watch(dir, (_event, filename) => {
+        if (this.disposed || activeGeneration !== this.credentialsWatcherGeneration) return;
         if (filename && String(filename) !== name) {
           return;
         }
         if (this.credsDebounceTimer) {
-          clearTimeout(this.credsDebounceTimer);
+          const timer = this.credsDebounceTimer;
+          const timerLease = this.credsDebounceTimerLease;
+          this.credsDebounceTimer = undefined;
+          this.credsDebounceTimerLease = undefined;
+          if (timerLease?.active) {
+            this.trackResourceStop(
+              timerLease.stop('cancelled', () => clearTimeout(timer)),
+            );
+          } else {
+            clearTimeout(timer);
+          }
         }
         this.credsDebounceTimer = setTimeout(() => {
-          this.handleCredentialsChange();
+          const timerLease = this.credsDebounceTimerLease;
+          this.credsDebounceTimer = undefined;
+          this.credsDebounceTimerLease = undefined;
+          if (timerLease?.active) {
+            this.trackResourceStop(timerLease.stop('settled', () => undefined));
+          }
+          if (!this.disposed && activeGeneration === this.credentialsWatcherGeneration) {
+            this.handleCredentialsChange();
+          }
         }, 800);
+        this.credsDebounceTimerLease = this.resourceOwnership.register({
+          kind: 'timer',
+          capability: 'quota',
+          scope: 'claude',
+          creator: 'extension',
+          stopConditions: [
+            'settled',
+            'cancelled',
+            'window-blur',
+            'extension-dispose',
+            'settings-change',
+            'profile-change',
+          ],
+          boundedException: 'none',
+        });
+      });
+      this.credsWatcherLease = this.resourceOwnership.register({
+        kind: 'watcher',
+        capability: 'quota',
+        scope: 'claude',
+        creator: 'extension',
+        stopConditions: [
+          'window-blur',
+          'extension-dispose',
+          'settings-change',
+          'profile-change',
+        ],
+        boundedException: 'none',
       });
     } catch {
       // Watching unsupported on this platform/filesystem — the refresh tick
@@ -1330,21 +3514,44 @@ export class ClaudeCodeUsageExtension {
     this.cache.usageLimitsLastUpdate = new Date(0);
     this.cache.usageLimitsFailStreak = 0;
     this.cache.usageLimitsBackoffUntil = new Date(0);
+    this.claudeProfileGeneration += 1;
+    this.activeClaudeQuotaFingerprint = undefined;
+    this.claudeWeeklyQuotaHistory = [];
+    this.webviewProvider.updateWeeklyQuotaHistory([]);
     void this.refreshData(false, 'credentials');
   }
 
-  private stopCredentialsWatching(): void {
+  private stopCredentialsWatching(
+    condition: Extract<
+      ResourceStopCondition,
+      'window-blur' | 'extension-dispose' | 'settings-change' | 'profile-change'
+    > = 'settings-change',
+  ): void {
+    this.credentialsWatcherGeneration += 1;
     if (this.credsDebounceTimer) {
-      clearTimeout(this.credsDebounceTimer);
+      const timer = this.credsDebounceTimer;
+      const lease = this.credsDebounceTimerLease;
       this.credsDebounceTimer = undefined;
-    }
-    if (this.credsWatcher) {
-      try {
-        this.credsWatcher.close();
-      } catch {
-        // Already closed.
+      this.credsDebounceTimerLease = undefined;
+      if (lease?.active) {
+        this.trackResourceStop(lease.stop(condition, () => clearTimeout(timer)));
       }
-      this.credsWatcher = undefined;
+      else clearTimeout(timer);
+    }
+    const watcher = this.credsWatcher;
+    const lease = this.credsWatcherLease;
+    this.credsWatcher = undefined;
+    this.credsWatcherLease = undefined;
+    if (watcher) {
+      const close = (): void => {
+        try {
+          watcher.close();
+        } catch {
+          // Already closed.
+        }
+      };
+      if (lease?.active) this.trackResourceStop(lease.stop(condition, close));
+      else close();
     }
   }
 
@@ -1354,13 +3561,23 @@ export class ClaudeCodeUsageExtension {
   }
 
   private suspendRecurringWork(): void {
-    this.stopAutoRefresh();
-    this.stopFileWatching();
-    this.stopCodexWatching();
-    this.stopCredentialsWatching();
+    this.stopAutoRefresh('window-blur');
+    this.stopQuotaColdRetry('window-blur');
+    void this.cancelQuotaNetworks('window-blur');
+    this.stopFileWatching('window-blur');
+    this.stopCodexWatching('window-blur');
+    this.stopCredentialsWatching('window-blur');
+    if (this.codexRefreshing && this.codexFirstBackfillActive) {
+      this.scheduleFirstBackfillBlurDeadline();
+    } else if (this.codexRefreshing) {
+      this.codexWorkerCancellationRequested = true;
+      void this.cancelCodexProviderAndWait();
+    }
   }
 
   private resumeRecurringWork(): void {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
+    this.stopFirstBackfillBlurDeadline('cancelled');
     this.startAutoRefresh();
     void this.startFileWatching();
     this.startCodexWatching();
@@ -1369,6 +3586,7 @@ export class ClaudeCodeUsageExtension {
   }
 
   private handleWindowFocusChange(focused: boolean): void {
+    if (this.disposed) return;
     const transition = this.windowActivity.update(focused);
     if (transition === 'suspend') {
       this.suspendRecurringWork();
@@ -1377,6 +3595,50 @@ export class ClaudeCodeUsageExtension {
     }
   }
 
+  private stopFirstBackfillBlurDeadline(
+    condition: Extract<ResourceStopCondition, 'window-blur' | 'cancelled' | 'extension-dispose'> = 'cancelled',
+  ): void {
+    const timer = this.codexFirstBackfillBlurTimer;
+    const lease = this.codexFirstBackfillBlurTimerLease;
+    this.codexFirstBackfillBlurTimer = undefined;
+    this.codexFirstBackfillBlurTimerLease = undefined;
+    if (!timer) return;
+    if (lease?.active) {
+      this.trackResourceStop(lease.stop(condition, () => clearTimeout(timer)));
+    } else {
+      clearTimeout(timer);
+    }
+  }
+
+  private scheduleFirstBackfillBlurDeadline(): void {
+    if (
+      this.disposed ||
+      !this.codexRefreshing ||
+      !this.codexFirstBackfillActive ||
+      this.codexFirstBackfillBlurTimer
+    ) return;
+    const lease = this.resourceOwnership.register({
+      kind: 'timer',
+      capability: 'codex-history',
+      scope: 'codex',
+      creator: 'refresh-coordinator',
+      stopConditions: ['window-blur', 'cancelled', 'extension-dispose'],
+      boundedException: 'none',
+    });
+    const timer = setTimeout(() => {
+      this.codexFirstBackfillBlurTimer = undefined;
+      this.codexFirstBackfillBlurTimerLease = undefined;
+      if (lease.active) {
+        this.trackResourceStop(lease.stop('cancelled', () => undefined));
+      }
+      if (this.disposed || !this.codexRefreshing || !this.codexFirstBackfillActive) return;
+      this.codexWorkerCancellationRequested = true;
+      void this.cancelCodexProviderAndWait();
+    }, ClaudeCodeUsageExtension.CODEX_FIRST_BACKFILL_BLUR_DEADLINE_MS);
+    this.codexFirstBackfillBlurTimer = timer;
+    this.codexFirstBackfillBlurTimerLease = lease;
+  }
+
   /** Keep recurring work only in the active VS Code window. Each window owns a
    * separate Extension Host, so leaving timers and both provider watchers active
    * in every background window multiplies the same local scans. A focused window
@@ -1384,120 +3646,149 @@ export class ClaudeCodeUsageExtension {
   private startWindowFocusRefresh(): void {
     this.context.subscriptions.push(
       vscode.window.onDidChangeWindowState((state) => {
+        if (this.disposed) return;
         this.handleWindowFocusChange(state.focused);
       })
     );
   }
 
-  private stopAutoRefresh(): void {
+  private stopAutoRefresh(
+    condition: Extract<
+      ResourceStopCondition,
+      'window-blur' | 'extension-dispose' | 'settings-change'
+    > = 'settings-change',
+  ): void {
     this.refreshGen += 1;
-    if (this.refreshTimer) {
-      clearTimeout(this.refreshTimer);
-      this.refreshTimer = undefined;
+    const timer = this.refreshTimer;
+    const lease = this.refreshTimerLease;
+    this.refreshTimer = undefined;
+    this.refreshTimerLease = undefined;
+    if (timer) {
+      if (lease?.active) {
+        this.trackResourceStop(lease.stop(condition, () => clearTimeout(timer)));
+      }
+      else clearTimeout(timer);
     }
   }
 
   private startAutoRefresh(): void {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
     this.stopAutoRefresh();
     if (!this.windowActivity.focused) {
       return;
     }
     const gen = this.refreshGen;
     const tick = (): void => {
-      if (gen !== this.refreshGen) {
+      if (this.disposed || gen !== this.refreshGen) {
         return; // superseded by a newer startAutoRefresh — stop this chain
       }
       const intervalMs = pollIntervalMs(this.getConfiguration().refreshInterval);
       this.refreshTimer = setTimeout(() => {
+        const timerLease = this.refreshTimerLease;
+        this.refreshTimer = undefined;
+        this.refreshTimerLease = undefined;
+        if (timerLease?.active) {
+          this.trackResourceStop(timerLease.stop('settled', () => undefined));
+        }
+        if (this.disposed || gen !== this.refreshGen) return;
         this.refreshData(false, 'poll').finally(() => {
-          if (gen === this.refreshGen) {
+          if (!this.disposed && gen === this.refreshGen) {
             tick();
           }
         });
       }, intervalMs);
+      this.refreshTimerLease = this.resourceOwnership.register({
+        kind: 'timer',
+        capability: 'refresh',
+        scope: 'extension',
+        creator: 'refresh-coordinator',
+        stopConditions: [
+          'settled',
+          'window-blur',
+          'extension-dispose',
+          'settings-change',
+        ],
+        boundedException: 'none',
+      });
     };
     tick();
   }
 
-  /** Fetch real usage limits via OAuth, cached for 2 minutes. */
-  // Persist the last-known quota across reloads/restarts.
-  private static readonly QUOTA_STATE_KEY = 'ccu.usageLimits';
-  private static readonly WEEKLY_QUOTA_STATE_KEY = 'ccu.weeklyQuotaHistory.v1';
-
-  private quotaProfileHash(): string {
-    return createHash('sha256')
-      .update(this.apiClient.getCredentialsPath())
-      .digest('hex')
-      .slice(0, 16);
-  }
-
-  private quotaStateKey(): string {
-    return `${ClaudeCodeUsageExtension.QUOTA_STATE_KEY}.${this.quotaProfileHash()}`;
-  }
-
-  private weeklyQuotaStateKey(): string {
-    return `${ClaudeCodeUsageExtension.WEEKLY_QUOTA_STATE_KEY}.${this.quotaProfileHash()}`;
+  /** Fetch real usage limits via OAuth, cached in memory for at most two
+   * minutes. Durable history contains only schema-2 normalized observations;
+   * the raw OAuth response is never retained by the extension. */
+  private claudeProfileContinuitySignal(): string {
+    return `profile-path-v1|${this.apiClient.getCredentialsPath()}`;
   }
 
-  private loadPersistedQuota(): void {
-    if (!this.getConfiguration().usageLimitTracking) {
-      return;
-    }
-    try {
-      const storedHistory = this.context.globalState.get<WeeklyQuotaObservation[]>(
-        this.weeklyQuotaStateKey(),
-      ) ?? [];
-      const saved = this.context.globalState.get<{ data: ClaudeApiUsageResponse; ts: number }>(
-        this.quotaStateKey()
-      );
-      const savedObservation = saved?.data
-        ? claudeWeeklyQuotaObservations(
-            saved.data,
-            this.quotaProfileHash(),
-            saved.ts || 0,
-          )
-        : [];
-      this.claudeWeeklyQuotaHistory = appendWeeklyQuotaObservations(
-        [],
-        [...storedHistory, ...savedObservation],
-      );
-      this.webviewProvider.updateWeeklyQuotaHistory(this.claudeWeeklyQuotaHistory);
-      if (saved && saved.data) {
-        this.cache.usageLimits = saved.data;
-        this.cache.usageLimitsLastUpdate = new Date(saved.ts || 0);
-        this.statusBar.updateQuota(saved.data);
-        this.webviewProvider.updateQuota(saved.data);
-      }
-    } catch {
-      /* ignore corrupt persisted state */
+  private refreshQuotaObservationViews(): void {
+    this.claudeWeeklyQuotaHistory = this.activeClaudeQuotaFingerprint
+      ? quotaStoreWeeklyObservations(
+          this.quotaObservationStore,
+          'claude',
+          this.activeClaudeQuotaFingerprint,
+        )
+      : [];
+    this.webviewProvider.updateWeeklyQuotaHistory(this.claudeWeeklyQuotaHistory);
+    if (this.codexView?.weeklyValueInputs) {
+      this.codexView.weeklyValueInputs = {
+        ...this.codexView.weeklyValueInputs,
+        observations: quotaStoreWeeklyObservations(
+          this.quotaObservationStore,
+          'codex',
+        ),
+      };
     }
   }
 
-  private recordClaudeWeeklyQuota(
+  private async recordClaudeQuotaObservation(
     usage: ClaudeApiUsageResponse,
     observedAt: number,
-  ): void {
-    const additions = claudeWeeklyQuotaObservations(
+  ): Promise<void> {
+    const verifiedSignal = this.apiClient.getLastQuotaIdentitySignal();
+    const identitySignal = verifiedSignal ?? this.claudeProfileContinuitySignal();
+    const accountAttribution = verifiedSignal
+      ? 'verified-local-signal' as const
+      : 'profile-continuity' as const;
+    const additions = claudeQuotaCapturesFromUsage(
       usage,
-      this.quotaProfileHash(),
+      identitySignal,
+      accountAttribution,
       observedAt,
     );
+    if (additions.length === 0) return;
+    this.quotaObservationStore = await this.quotaObservationRepository.append(
+      additions,
+    );
+    this.activeClaudeQuotaFingerprint = fingerprintForStableIdentity(
+      this.quotaFingerprintSalt,
+      'claude',
+      identitySignal,
+    );
+    this.refreshQuotaObservationViews();
+  }
+
+  private async recordCodexQuotaObservations(
+    observations: readonly WeeklyQuotaObservation[],
+  ): Promise<void> {
+    const additions = codexQuotaCapturesFromWeeklyObservations(observations);
     if (additions.length === 0) {
+      this.refreshQuotaObservationViews();
       return;
     }
-    this.claudeWeeklyQuotaHistory = appendWeeklyQuotaObservations(
-      this.claudeWeeklyQuotaHistory,
+    this.quotaObservationStore = await this.quotaObservationRepository.append(
       additions,
     );
-    this.webviewProvider.updateWeeklyQuotaHistory(this.claudeWeeklyQuotaHistory);
-    void this.context.globalState.update(
-      this.weeklyQuotaStateKey(),
-      this.claudeWeeklyQuotaHistory,
-    );
+    this.refreshQuotaObservationViews();
+    if (!this.disposed) this.syncProviderUi();
   }
 
   private async maybeFetchUsageLimits(config: ExtensionConfig): Promise<ClaudeApiUsageResponse | null> {
-    if (!config.usageLimitTracking) {
+    if (
+      this.disposed ||
+      this.localDataClearedRequiresReload ||
+      !config.usageLimitTracking
+    ) {
       return null;
     }
     const now = Date.now();
@@ -1523,7 +3814,47 @@ export class ClaudeCodeUsageExtension {
     }
     const profileGeneration = this.claudeProfileGeneration;
     const apiClient = this.apiClient;
-    const fetched = await apiClient.fetchUsageLimits();
+    const controller = new AbortController();
+    const quotaNetworkLease = this.resourceOwnership.register({
+      kind: 'network',
+      capability: 'quota',
+      scope: 'claude',
+      creator: 'claude-api-client',
+      stopConditions: [
+        'settled',
+        'cancelled',
+        'window-blur',
+        'feature-disabled',
+        'extension-dispose',
+        'settings-change',
+        'profile-change',
+      ],
+      boundedException: 'none',
+    });
+    let markSettled!: () => void;
+    const settled = new Promise<void>((resolve) => {
+      markSettled = resolve;
+    });
+    this.activeQuotaNetworks.set(controller, {
+      lease: quotaNetworkLease,
+      settled,
+    });
+    let fetched: ClaudeApiUsageResponse | null;
+    try {
+      fetched = await apiClient.fetchUsageLimits(controller.signal);
+    } finally {
+      this.activeQuotaNetworks.delete(controller);
+      markSettled();
+      if (quotaNetworkLease.active) {
+        await quotaNetworkLease.stop(
+          controller.signal.aborted ? 'cancelled' : 'settled',
+          () => undefined,
+        );
+      }
+    }
+    if (controller.signal.aborted) {
+      return this.cache.usageLimits;
+    }
     if (
       profileGeneration !== this.claudeProfileGeneration ||
       apiClient !== this.apiClient
@@ -1541,12 +3872,7 @@ export class ClaudeCodeUsageExtension {
       // expired-window bypass so a just-rolled window can't trigger an immediate
       // refetch.
       this.cache.usageLimitsBackoffUntil = new Date(Date.now() + 30000);
-      // Write through to disk so the next startup/reload has it instantly.
-      void this.context.globalState.update(
-        this.quotaStateKey(),
-        { data: fetched, ts: observedAt }
-      );
-      this.recordClaudeWeeklyQuota(fetched, observedAt);
+      await this.recordClaudeQuotaObservation(fetched, observedAt);
       return fetched;
     }
     // Failed (usually a 429 or invalid/expired credentials). Exponentially back
@@ -1573,6 +3899,7 @@ export class ClaudeCodeUsageExtension {
     forceReload: boolean = false,
     trigger: RefreshTrigger = 'poll'
   ): Promise<void> {
+    if (this.disposed || this.localDataClearedRequiresReload) return;
     // `watch` reaches this shared path only from the Claude projects watcher.
     // Codex has its own watcher and quiet-delay setting, so refreshing it here
     // would bypass codex.fileWatchSeconds whenever Claude writes a JSONL line.
@@ -1610,30 +3937,26 @@ export class ClaudeCodeUsageExtension {
     this.coalescedTriggersSinceRefresh = 0;
     let updateWebview = request.trigger === 'manual';
     try {
+      if (this.disposed) return;
       const config = this.getConfiguration();
       updateWebview = updateWebview || config.dashboardAutoRefresh;
 
       // Account quota is independent from local JSONL. Do not let a slow OAuth
       // request delay the local usage refresh.
-      this.maybeFetchUsageLimits(config).then((limits) => {
+      void this.maybeFetchUsageLimits(config).then((limits) => {
+        if (this.disposed) return;
         this.statusBar.updateQuota(limits);
         this.webviewProvider.updateQuota(limits);
         if (!limits && !this.cache.usageLimits && !this.quotaColdRetryDone) {
           this.quotaColdRetryDone = true;
-          setTimeout(() => {
-            this.maybeFetchUsageLimits(this.getConfiguration()).then((retry) => {
-              if (retry) {
-                this.statusBar.updateQuota(retry);
-                this.webviewProvider.updateQuota(retry);
-              }
-            });
-          }, 8000);
+          this.scheduleQuotaColdRetry();
         }
-      });
+      }).catch(() => undefined);
 
       const dataDirectory = await ClaudeDataLoader.findClaudeDataDirectory(
         config.dataDirectory || undefined
       );
+      if (this.disposed) return;
       if (!dataDirectory) {
         const error = 'Claude data directory not found. Please check your configuration.';
         this.statusBar.updateUsageData(null, null, error);
@@ -1764,9 +4087,10 @@ export class ClaudeCodeUsageExtension {
         const sessionData = materialized.session;
         const todayData = materialized.today;
         const workspaceTodayData = materialized.workspaceToday;
-        const monthData = materialized.month;
+        const calendarMonthData = materialized.month;
+        const rolling30Data = materialized.last30Days;
         const allTimeData = materialized.allTime;
-        const dailyDataForMonth = materialized.dailyForMonth;
+        const dailyDataForRolling30 = materialized.dailyForLast30Days;
         const dailyDataForAllTime = materialized.monthlyForAllTime;
         const hourlyDataForToday = materialized.hourlyForToday;
         const sessionBreakdown = materialized.sessions;
@@ -1775,10 +4099,13 @@ export class ClaudeCodeUsageExtension {
         const workflowBreakdown = materialized.workflows;
         const costliestMessages = materialized.costliestMessages;
 
-        this.statusBar.updateUsageData(todayData, workspaceTodayData, undefined, undefined, monthData);
+        // The status bar setting is explicitly "monthly cost" and therefore
+        // keeps calendar-month semantics. The dashboard's middle range is the
+        // more useful rolling 30-day view and receives a separate aggregate.
+        this.statusBar.updateUsageData(todayData, workspaceTodayData, undefined, undefined, calendarMonthData);
         this.statusBar.updateContext(materialized.context);
         if (updateWebview) {
-          this.webviewProvider.updateData(sessionData, todayData, monthData, allTimeData, dailyDataForMonth, dailyDataForAllTime, hourlyDataForToday, undefined, dataDirectory, records, sessionBreakdown, projectBreakdown, contentAnalysis, branchBreakdown, workflowBreakdown, costliestMessages);
+          this.webviewProvider.updateData(sessionData, todayData, rolling30Data, allTimeData, dailyDataForRolling30, dailyDataForAllTime, hourlyDataForToday, undefined, dataDirectory, records, sessionBreakdown, projectBreakdown, contentAnalysis, branchBreakdown, workflowBreakdown, costliestMessages);
         }
       }
 
@@ -1835,34 +4162,104 @@ export class ClaudeCodeUsageExtension {
         totalMs: performance.now() - totalStarted,
       }));
     } finally {
-      this.syncProviderUi();
+      if (!this.disposed) this.syncProviderUi();
       const next = this.refreshGate.complete();
-      if (next !== null) {
-        setTimeout(() => void this.runRefresh(next), 0);
+      if (!this.disposed && next !== null) {
+        queueMicrotask(() => void this.runRefresh(next));
       }
     }
   }
 
-  dispose(): void {
-    this.stopAutoRefresh();
-    this.stopFileWatching();
-    this.stopCodexWatching();
-    this.stopCredentialsWatching();
-    this.codexProvider.dispose();
-    this.statusBar.dispose();
-    this.webviewProvider.dispose();
+  dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
+    this.disposed = true;
+    this.configurationGeneration += 1;
+    this.disposal = (async () => {
+      const failures: unknown[] = [];
+      const capture = async (operation: Promise<unknown>): Promise<boolean> => {
+        try {
+          await operation;
+          return true;
+        } catch (error) {
+          failures.push(error);
+          return false;
+        }
+      };
+      this.stopQuotaColdRetry('extension-dispose');
+      this.stopAutoRefresh('extension-dispose');
+      this.stopFirstBackfillBlurDeadline('extension-dispose');
+      this.stopFileWatching('extension-dispose');
+      this.stopCodexWatching('extension-dispose');
+      this.stopCredentialsWatching('extension-dispose');
+      await capture(Promise.all([
+        this.cancelAdviceNetworks('extension-dispose'),
+        this.cancelQuotaNetworks('extension-dispose'),
+      ]));
+      this.codexWorkerCancellationRequested = true;
+      this.codexProvider.cancel();
+      const providerStopped = await capture(Promise.all([
+        this.waitForCodexProviderRetirements(),
+        this.codexProvider.dispose(),
+      ]));
+      while (this.activeCodexRefreshes.size > 0) {
+        await Promise.allSettled([...this.activeCodexRefreshes]);
+      }
+      if (providerStopped) {
+        await capture(this.releaseCodexOwnership('extension-dispose'));
+      }
+      await capture(this.codexBackgroundStateWrite.catch((error) => {
+        throw error;
+      }));
+      await capture(this.drainResourceStops());
+      this.statusBar.dispose();
+      this.webviewProvider.dispose();
+      if (failures.length > 0) {
+        const first = failures[0];
+        throw first instanceof Error
+          ? first
+          : new Error('Extension resources could not be stopped safely');
+      }
+    })();
+    return this.disposal;
   }
 }
 
-export function activate(context: vscode.ExtensionContext) {
+let activeExtension: ClaudeCodeUsageExtension | null = null;
+
+export async function activate(context: vscode.ExtensionContext): Promise<void> {
   console.log('Claude Code Usage extension is now active');
 
-  const extension = new ClaudeCodeUsageExtension(context);
+  const settings = new SettingsStore(context);
+  I18n.setLanguage(settings.get<string>('language') as any);
+  try {
+    await settings.initializeSecrets();
+  } catch (error) {
+    const needsManualWorkspaceMigration =
+      error instanceof SettingsSecretMigrationError &&
+      (error.code === 'legacy-secret-conflict' ||
+        error.code === 'workspace-secret-requires-manual-migration');
+    await vscode.window.showErrorMessage(
+      needsManualWorkspaceMigration
+        ? I18n.t.popup.secretMigrationWorkspace
+        : I18n.t.popup.secretMigrationFailed,
+    );
+    throw error;
+  }
+  const quotaRuntime = await initializeQuotaObservationRuntime(context, settings);
+  const extension = new ClaudeCodeUsageExtension(
+    context,
+    settings,
+    quotaRuntime,
+  );
+  activeExtension = extension;
   context.subscriptions.push({
-    dispose: () => extension.dispose()
+    dispose: () => { void extension.dispose(); }
   });
 }
 
-export function deactivate() {
+export async function deactivate(): Promise<void> {
   console.log('Claude Code Usage extension is now deactivated');
+  const extension = activeExtension;
+  activeExtension = null;
+  await extension?.dispose();
 }
diff --git a/src/githubHeatmapPublish.ts b/src/githubHeatmapPublish.ts
new file mode 100644
index 00000000..5de322fb
--- /dev/null
+++ b/src/githubHeatmapPublish.ts
@@ -0,0 +1,178 @@
+export const GITHUB_PUBLIC_REPO_SCOPE = 'public_repo';
+
+export interface GitHubApiResponse {
+  status: number;
+  body: string;
+}
+
+export type GitHubApiRequest = (
+  method: 'GET' | 'PUT',
+  apiPath: string,
+  body?: unknown,
+) => Promise<GitHubApiResponse>;
+
+export interface GitHubPublishPlan {
+  owner: string;
+  repository: string;
+  filePath: string;
+  repoApiPath: string;
+  contentsApiPath: string;
+}
+
+export interface GitHubPublishPreview extends GitHubPublishPlan {
+  visibility: 'public';
+  branch: string;
+  action: 'create' | 'update';
+  existingSha?: string;
+  browserUrl: string;
+}
+
+export class GitHubPublishHttpError extends Error {
+  constructor(
+    public readonly operation: 'repository-probe' | 'file-probe' | 'file-write',
+    public readonly status: number,
+  ) {
+    super(`GitHub ${operation} failed (status ${status}).`);
+    this.name = 'GitHubPublishHttpError';
+  }
+}
+
+function encodedSegments(value: string): string {
+  return value.split('/').map(encodeURIComponent).join('/');
+}
+
+export function createGitHubPublishPlan(
+  repositoryInput: string,
+  pathInput: string,
+): GitHubPublishPlan {
+  const repository = repositoryInput.trim();
+  const parts = repository.split('/');
+  if (parts.length !== 2) {
+    throw new Error('Repository must use the exact owner/name form.');
+  }
+  const [owner, name] = parts;
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(owner)) {
+    throw new Error('Repository owner contains unsupported characters.');
+  }
+  if (!/^[A-Za-z0-9._-]{1,100}$/.test(name) || name === '.' || name === '..') {
+    throw new Error('Repository name contains unsupported characters.');
+  }
+
+  const filePath = pathInput.trim();
+  if (
+    !filePath ||
+    filePath.length > 512 ||
+    filePath.startsWith('/') ||
+    filePath.endsWith('/') ||
+    /[\\?#\u0000-\u001f\u007f]/.test(filePath)
+  ) {
+    throw new Error('Repository path must be a relative path without query, fragment, or control characters.');
+  }
+  const pathSegments = filePath.split('/');
+  if (pathSegments.some((segment) => !segment || segment === '.' || segment === '..')) {
+    throw new Error('Repository path contains an unsafe segment.');
+  }
+
+  const encodedOwner = encodeURIComponent(owner);
+  const encodedRepository = encodeURIComponent(name);
+  return {
+    owner,
+    repository: name,
+    filePath,
+    repoApiPath: `/repos/${encodedOwner}/${encodedRepository}`,
+    contentsApiPath: `/repos/${encodedOwner}/${encodedRepository}/contents/${encodedSegments(filePath)}`,
+  };
+}
+
+function parseObject(body: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error('GitHub returned an unreadable response.');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('GitHub returned an unexpected response.');
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export async function probePublicGitHubPublishTarget(
+  plan: GitHubPublishPlan,
+  request: GitHubApiRequest,
+): Promise<GitHubPublishPreview> {
+  const repository = await request('GET', plan.repoApiPath);
+  if (repository.status !== 200) {
+    throw new GitHubPublishHttpError('repository-probe', repository.status);
+  }
+  const repositoryBody = parseObject(repository.body);
+  if (repositoryBody.private === true) {
+    throw new Error('Private repositories are not supported by the public-only publisher. Export the SVG and add it manually instead.');
+  }
+  if (repositoryBody.private !== false) {
+    throw new Error('GitHub repository visibility could not be verified.');
+  }
+  const branch = typeof repositoryBody.default_branch === 'string'
+    ? repositoryBody.default_branch.trim()
+    : '';
+  if (!branch || /[\u0000-\u001f\u007f]/.test(branch)) {
+    throw new Error('GitHub default branch could not be verified.');
+  }
+
+  const fileProbePath = `${plan.contentsApiPath}?ref=${encodeURIComponent(branch)}`;
+  const file = await request('GET', fileProbePath);
+  let action: 'create' | 'update';
+  let existingSha: string | undefined;
+  if (file.status === 404) {
+    action = 'create';
+  } else if (file.status === 200) {
+    const fileBody = parseObject(file.body);
+    if (typeof fileBody.sha !== 'string' || !/^[0-9a-f]{40,64}$/i.test(fileBody.sha)) {
+      throw new Error('GitHub existing-file identity could not be verified.');
+    }
+    action = 'update';
+    existingSha = fileBody.sha;
+  } else {
+    throw new GitHubPublishHttpError('file-probe', file.status);
+  }
+
+  return {
+    ...plan,
+    visibility: 'public',
+    branch,
+    action,
+    existingSha,
+    browserUrl: `https://github.com/${encodeURIComponent(plan.owner)}/${encodeURIComponent(plan.repository)}/blob/${encodedSegments(branch)}/${encodedSegments(plan.filePath)}`,
+  };
+}
+
+export function githubPublishConfirmationDetail(
+  preview: GitHubPublishPreview,
+  payloadBytes: number,
+): string {
+  const action = preview.action === 'update' ? 'OVERWRITE the existing file' : 'CREATE a new file';
+  return [
+    `Repository: ${preview.owner}/${preview.repository} (public)`,
+    `Branch: ${preview.branch}`,
+    `Path: ${preview.filePath}`,
+    `Action: ${action}`,
+    `Payload: one aggregate SVG (${Math.max(0, Math.trunc(payloadBytes))} bytes)`,
+    'Excluded: accounts, projects, thread titles, local paths, prompts, and log content.',
+  ].join('\n');
+}
+
+export async function publishPublicGitHubFile(
+  preview: GitHubPublishPreview,
+  contentBase64: string,
+  request: GitHubApiRequest,
+): Promise<void> {
+  const response = await request('PUT', preview.contentsApiPath, {
+    message: 'Update Claude Code usage heatmap',
+    content: contentBase64,
+    branch: preview.branch,
+    ...(preview.existingSha ? { sha: preview.existingSha } : {}),
+  });
+  if (response.status !== 200 && response.status !== 201) {
+    throw new GitHubPublishHttpError('file-write', response.status);
+  }
+}
diff --git a/src/heatmapSvg.ts b/src/heatmapSvg.ts
index be8aec97..6f9d1ed7 100644
--- a/src/heatmapSvg.ts
+++ b/src/heatmapSvg.ts
@@ -15,10 +15,83 @@ export const CLAUDE_ORANGE_SCALE = ['#ebedf0', '#fadcc9', '#f0aa82', '#e07d4f',
 export interface HeatmapSvgOptions {
   metric?: HeatMetric; // default 'tokens'
   weeks?: number; // trailing weeks to show (default 53, GitHub-like)
+  startDateISO?: string; // explicit inclusive start for deterministic custom ranges
   endDateISO?: string; // last day to show (default today)
   title?: string; // override the auto summary heading
+  subtitle?: string; // optional aggregate breakdown below the heading
+  footerNote?: string; // optional semantic disclaimer above the watermark row
   watermark?: string; // bottom-left source note (default "Made with Claude Code Usage")
-  scale?: string[]; // 5 colours, empty→max (default CLAUDE_ORANGE_SCALE)
+  scale?: string[]; // 2..8 colours, empty→max (default CLAUDE_ORANGE_SCALE)
+  intensityMode?: 'linear' | 'quantile' | 'logarithmic'; // default linear; alternatives keep outliers from flattening the history
+  background?: string;
+  primaryText?: string;
+  secondaryText?: string;
+  borderColor?: string;
+  accentColor?: string;
+  minWidth?: number; // optional card width floor for short date ranges
+  ariaLabel?: string;
+  tooltip?: (dateISO: string, usage: DayUsage, value: number, metric: HeatMetric) => string;
+}
+
+function lowerBound(sorted: readonly number[], value: number): number {
+  let low = 0;
+  let high = sorted.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (sorted[middle] < value) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+
+function assignRenderBuckets(
+  cells: HeatGridCell[],
+  activeBands: number,
+  max: number,
+  mode: 'linear' | 'quantile' | 'logarithmic',
+): void {
+  // buildContributionGrid already applies the original four-band linear rule.
+  // Preserve that exact output for the long-standing Claude ramp.
+  if (mode === 'linear' && activeBands === 4) {
+    return;
+  }
+  const bands = Math.max(1, activeBands);
+  const positive = mode === 'quantile'
+    ? cells.map((cell) => cell.value).filter((value) => value > 0).sort((a, b) => a - b)
+    : [];
+  for (const cell of cells) {
+    if (cell.value <= 0 || max <= 0) {
+      cell.bucket = 0;
+      continue;
+    }
+    // Rank by the first occurrence, so a large tie of ordinary days stays in
+    // the lightest active band. The observed maximum is always the top band;
+    // otherwise sparse inputs and a tie at the maximum make the legend's
+    // darkest swatch unreachable.
+    if (mode === 'quantile' && positive.length > 0) {
+      cell.bucket = cell.value >= max
+        ? bands
+        : Math.min(bands, Math.max(1, Math.floor((lowerBound(positive, cell.value) / positive.length) * bands) + 1));
+      continue;
+    }
+    const normalized = mode === 'logarithmic'
+      ? Math.log1p(cell.value) / Math.log1p(max)
+      : cell.value / max;
+    cell.bucket = Math.min(bands, Math.max(1, Math.ceil(normalized * bands)));
+  }
+}
+
+function safeSvgColor(value: unknown, fallback: string): string {
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === 'transparent' || /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(normalized)
+    ? normalized
+    : fallback;
 }
 
 function valueOf(u: DayUsage, metric: HeatMetric): number {
@@ -128,14 +201,26 @@ export function renderHeatmapSvg(daily: Record<string, DayUsage>, opts: HeatmapS
   const metric = opts.metric ?? 'tokens';
   const weeks = Math.max(1, Math.min(53, opts.weeks ?? 53));
   const today = opts.endDateISO ?? new Date().toISOString().slice(0, 10);
-  const scale = opts.scale && opts.scale.length === 5 ? opts.scale : CLAUDE_ORANGE_SCALE;
+  const requestedScale = opts.scale && opts.scale.length >= 2 && opts.scale.length <= 8
+    ? opts.scale
+    : CLAUDE_ORANGE_SCALE;
+  const scale = requestedScale.map((color, index) => safeSvgColor(
+    color,
+    CLAUDE_ORANGE_SCALE[Math.min(index, CLAUDE_ORANGE_SCALE.length - 1)],
+  ));
   const watermark = opts.watermark ?? 'Made with Claude Code Usage';
 
   // Trailing window: full weeks ending on the Saturday of today's week, cells
   // only up to today (no future) — GitHub's default contribution view.
   const gridEndSat = addDays(today, 6 - weekdayOf(today));
-  const startISO = addDays(gridEndSat, -(weeks * 7 - 1)); // a Sunday, `weeks` back
+  const startISO = opts.startDateISO ?? addDays(gridEndSat, -(weeks * 7 - 1)); // a Sunday, `weeks` back
   const grid = buildContributionGrid(daily, startISO, today, metric);
+  assignRenderBuckets(
+    grid.cells,
+    scale.length - 1,
+    grid.max,
+    opts.intensityMode ?? 'linear',
+  );
 
   // Auto summary heading, e.g. "5.3B tokens in Claude Code · 2026".
   const year = Number(today.slice(0, 4));
@@ -152,29 +237,44 @@ export function renderHeatmapSvg(daily: Record<string, DayUsage>, opts: HeatmapS
   const gap = 3;
   const step = cell + gap;
   const padL = 38; // weekday labels
-  const titleH = 24;
+  const titleH = opts.subtitle ? 43 : 24;
   const monthH = 18;
   const padT = titleH + monthH;
   const gridW = grid.columns * step;
   const gridH = 7 * step;
-  const footerH = 30;
-  const width = padL + gridW + 10;
+  const footerH = opts.footerNote ? 48 : 30;
+  const width = Math.max(padL + gridW + 10, Math.max(0, opts.minWidth ?? 0));
   const height = padT + gridH + footerH;
 
   const parts: string[] = [];
+  const background = safeSvgColor(opts.background, '#ffffff');
+  const primaryText = safeSvgColor(opts.primaryText, '#24292f');
+  const secondaryText = safeSvgColor(opts.secondaryText, '#57606a');
+  const borderColor = safeSvgColor(opts.borderColor, 'transparent');
+  const accentColor = opts.accentColor
+    ? safeSvgColor(opts.accentColor, '')
+    : undefined;
   parts.push(
-    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="-apple-system,Segoe UI,Helvetica,Arial,sans-serif">`
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="-apple-system,Segoe UI,Helvetica,Arial,sans-serif" role="img" aria-label="${esc(opts.ariaLabel ?? summary)}">`
   );
-  parts.push(`<rect width="${width}" height="${height}" fill="#ffffff"/>`);
-  parts.push(`<text x="${padL}" y="16" font-size="15" font-weight="600" fill="#24292f">${esc(summary)}</text>`);
+  parts.push(`<rect x="0.5" y="0.5" width="${width - 1}" height="${height - 1}" rx="12" fill="${background}" stroke="${borderColor}"/>`);
+  if (accentColor) {
+    parts.push(`<rect x="0" y="0" width="${width}" height="4" rx="2" fill="${accentColor}"/>`);
+  }
+  parts.push(`<text x="${padL}" y="16" font-size="15" font-weight="600" fill="${primaryText}">${esc(summary)}</text>`);
+  if (opts.subtitle) {
+    parts.push(`<text x="${padL}" y="34" font-size="11" fill="${secondaryText}">${esc(opts.subtitle)}</text>`);
+  }
 
   // Cells with GitHub-style tooltips: "1.2M tokens on June 18th".
   for (const c of grid.cells) {
     const x = padL + c.col * step;
     const y = padT + c.row * step;
     const when = longDate(c.dateISO);
-    const tip =
-      c.value <= 0
+    const usage = daily[c.dateISO] ?? { tokens: 0, cost: 0, sessions: 0 };
+    const tip = opts.tooltip
+      ? opts.tooltip(c.dateISO, usage, c.value, metric)
+      : c.value <= 0
         ? `No ${noun || 'usage'} on ${when}`
         : metric === 'cost'
           ? `$${compactNum(c.value)} on ${when}`
@@ -194,29 +294,37 @@ export function renderHeatmapSvg(daily: Record<string, DayUsage>, opts: HeatmapS
     const m = Number(first.dateISO.slice(5, 7)) - 1;
     if (m !== lastMonth) {
       lastMonth = m;
-      parts.push(`<text x="${padL + col * step}" y="${titleH + 13}" font-size="12" fill="#57606a">${MONTHS[m]}</text>`);
+      parts.push(`<text x="${padL + col * step}" y="${titleH + 13}" font-size="12" fill="${secondaryText}">${MONTHS[m]}</text>`);
     }
   }
 
   // Weekday labels (Mon / Wed / Fri).
   for (const [row, label] of [[1, 'Mon'], [3, 'Wed'], [5, 'Fri']] as [number, string][]) {
-    parts.push(`<text x="0" y="${padT + row * step + cell - 1}" font-size="11" fill="#57606a">${label}</text>`);
+    parts.push(`<text x="0" y="${padT + row * step + cell - 1}" font-size="11" fill="${secondaryText}">${label}</text>`);
   }
 
-  const footY = padT + gridH + 18;
+  const footY = padT + gridH + (opts.footerNote ? 36 : 18);
+
+  if (opts.footerNote) {
+    parts.push(`<text x="${padL}" y="${padT + gridH + 15}" font-size="10" fill="${secondaryText}">${esc(opts.footerNote)}</text>`);
+  }
 
   // Watermark, bottom-left (an orange dot + source, to point back at the tool).
-  parts.push(`<rect x="${padL}" y="${footY - 8}" width="9" height="9" rx="2" ry="2" fill="${scale[3]}"/>`);
-  parts.push(`<text x="${padL + 13}" y="${footY}" font-size="11" fill="#57606a">${esc(watermark)}</text>`);
+  const watermarkColor = scale[Math.min(3, scale.length - 1)];
+  parts.push(`<rect x="${padL}" y="${footY - 8}" width="9" height="9" rx="2" ry="2" fill="${watermarkColor}"/>`);
+  parts.push(`<text x="${padL + 13}" y="${footY}" font-size="11" fill="${secondaryText}">${esc(watermark)}</text>`);
 
   // Legend, bottom-right: Less [][][][][] More.
-  let lx = padL + gridW - (5 * step + 56);
-  parts.push(`<text x="${lx}" y="${footY}" font-size="11" fill="#57606a">Less</text>`);
+  // Anchor to the rendered card rather than the raw grid. Short 30/90-day
+  // ranges use minWidth, so a grid-relative position can fall outside the
+  // viewBox as the legend gains additional bands.
+  let lx = Math.max(padL, width - (scale.length * step + 66));
+  parts.push(`<text x="${lx}" y="${footY}" font-size="11" fill="${secondaryText}">Less</text>`);
   lx += 26;
-  for (let b = 0; b < 5; b++) {
+  for (let b = 0; b < scale.length; b++) {
     parts.push(`<rect x="${lx + b * step}" y="${footY - 9}" width="${cell}" height="${cell}" rx="2" ry="2" fill="${scale[b]}"/>`);
   }
-  parts.push(`<text x="${lx + 5 * step + 4}" y="${footY}" font-size="11" fill="#57606a">More</text>`);
+  parts.push(`<text x="${lx + scale.length * step + 4}" y="${footY}" font-size="11" fill="${secondaryText}">More</text>`);
 
   parts.push('</svg>');
   return parts.join('\n');
diff --git a/src/httpClient.ts b/src/httpClient.ts
index 8d7d4168..051a4588 100644
--- a/src/httpClient.ts
+++ b/src/httpClient.ts
@@ -17,7 +17,8 @@ export interface HttpResponse {
 export interface HttpRequestOptions {
   method?: string;
   headers?: Record<string, string>;
-  body?: string;
+  body?: string | Uint8Array;
+  signal?: AbortSignal;
 }
 
 /** Run an HTTP request via Node fetch. Optional timeoutMs aborts the request
@@ -30,22 +31,31 @@ export async function requestViaFetch(
     throw new Error('fetch unavailable in this VS Code version');
   }
   let signal: AbortSignal | undefined;
+  let controller: AbortController | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
-  if (opts.timeoutMs && opts.timeoutMs > 0) {
-    const controller = new AbortController();
+  const abortFromCaller = (): void => controller?.abort();
+  if ((opts.timeoutMs && opts.timeoutMs > 0) || opts.signal) {
+    controller = new AbortController();
+    if (opts.signal?.aborted) controller.abort();
+    else opts.signal?.addEventListener('abort', abortFromCaller, { once: true });
+  }
+  if (opts.timeoutMs && opts.timeoutMs > 0 && controller) {
     timer = setTimeout(() => controller.abort(), opts.timeoutMs);
-    signal = controller.signal;
   }
+  signal = controller?.signal ?? opts.signal;
   try {
     const res = await fetch(url, {
       method: opts.method || 'GET',
       headers: opts.headers,
-      body: opts.body,
+      body: typeof opts.body === 'string' || opts.body === undefined
+        ? opts.body
+        : Buffer.from(opts.body),
       signal
     });
     return { status: res.status, body: await res.text() };
   } catch (e) {
     if ((e as Error).name === 'AbortError') {
+      if (opts.signal?.aborted) throw new Error('Request cancelled');
       throw new Error(`Request timed out after ${Math.round((opts.timeoutMs || 0) / 1000)}s`);
     }
     throw e;
@@ -53,6 +63,7 @@ export async function requestViaFetch(
     if (timer !== undefined) {
       clearTimeout(timer);
     }
+    opts.signal?.removeEventListener('abort', abortFromCaller);
   }
 }
 
@@ -63,6 +74,10 @@ export function requestViaCurl(
   log?: (line: string) => void
 ): Promise<HttpResponse> {
   return new Promise((resolve, reject) => {
+    if (opts.signal?.aborted) {
+      reject(new Error('Request cancelled'));
+      return;
+    }
     const args: string[] = ['-sS', '-w', '\n__CCU_STATUS__%{http_code}', '--max-time', String(opts.timeoutSec ?? 15)];
     if (opts.method && opts.method !== 'GET') {
       args.push('-X', opts.method);
@@ -84,6 +99,23 @@ export function requestViaCurl(
     // quota silently stops loading (while a fresh window, with a valid cwd, works
     // fine). curl needs no particular cwd, so anchor it somewhere always valid.
     const child = spawn(cmd, args, { shell: false, windowsHide: true, cwd: os.homedir() });
+    let settled = false;
+    let aborted = false;
+    const finishReject = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+    const finishResolve = (response: HttpResponse): void => {
+      if (settled) return;
+      settled = true;
+      resolve(response);
+    };
+    const abort = (): void => {
+      aborted = true;
+      child.kill();
+    };
+    opts.signal?.addEventListener('abort', abort, { once: true });
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', (c: Buffer) => (stdout += c.toString('utf-8')));
@@ -92,17 +124,22 @@ export function requestViaCurl(
       if (log) {
         log(`curl: spawn error ${(e as Error).message} (is curl on PATH?)`);
       }
-      reject(e);
+      finishReject(e);
     });
     child.on('close', (code) => {
+      opts.signal?.removeEventListener('abort', abort);
+      if (aborted) {
+        return finishReject(new Error('Request cancelled'));
+      }
+      if (settled) return;
       if (code !== 0) {
-        return reject(new Error(`curl exit ${code}: ${stderr.trim().slice(0, 200)}`));
+        return finishReject(new Error(`curl exit ${code}: ${stderr.trim().slice(0, 200)}`));
       }
       const m = stdout.match(/^([\s\S]*)\n__CCU_STATUS__(\d{3})$/);
       if (!m) {
-        return reject(new Error(`Could not parse curl output: ${stdout.slice(0, 200)}`));
+        return finishReject(new Error(`Could not parse curl output: ${stdout.slice(0, 200)}`));
       }
-      resolve({ status: parseInt(m[2], 10), body: m[1] });
+      finishResolve({ status: parseInt(m[2], 10), body: m[1] });
     });
     if (opts.body !== undefined) {
       child.stdin.end(opts.body);
diff --git a/src/i18n.ts b/src/i18n.ts
index 483775c5..4c9d4e00 100644
--- a/src/i18n.ts
+++ b/src/i18n.ts
@@ -12,6 +12,7 @@ export interface WeeklyValueCopy {
   title: string;
   description: string;
   period: string;
+  periodDetails: string;
   currentPeriod: string;
   currentPeriodShort: string;
   resetsAt: string;
@@ -36,6 +37,67 @@ export interface WeeklyValueCopy {
   indexedSubtotal: string;
 }
 
+export interface AdviceEffectivenessTranslations {
+  title: string;
+  description: string;
+  candidateNotice: string;
+  spineLabel: string;
+  observation: string;
+  evidence: string;
+  recommendation: string;
+  action: string;
+  result: string;
+  source: string;
+  limitations: string;
+  proxyMetric: string;
+  longSessionSignal: string;
+  largeContextSignal: string;
+  frameworkOverheadSignal: string;
+  clearBoundaryRecommendation: string;
+  clearBoundaryAction: string;
+  codexLocalRecommendation: string;
+  noEvidenceAdvice: string;
+  codexPreviewUnavailable: string;
+  elapsedTimeProxy: string;
+  qualityGuardrailPending: string;
+  payloadTitle: string;
+  payloadDescription: string;
+  aggregatesOnly: string;
+  aggregatesWithPersonalization: string;
+  aggregatesWithPromptSamples: string;
+  payloadBytes: string;
+  promptSamplesIncluded: string;
+  previewPayload: string;
+  noNetworkTransport: string;
+  sendPreparedRequest: string;
+  sendingPreparedRequest: string;
+  sentPreparedRequest: string;
+  aggregateConsentLabel: string;
+  aggregateConsentHelp: string;
+  promptConsentLabel: string;
+  promptConsentHelp: string;
+  promptWindowHelp: string;
+  feedbackTitle: string;
+  helpful: string;
+  notHelpful: string;
+  applied: string;
+  snooze: string;
+  resume: string;
+  snoozedUntil: string;
+  feedbackLocalOnly: string;
+  feedbackSaveFailed: string;
+  comparisonTitle: string;
+  comparablePairs: string;
+  minimumComparablePairs: string;
+  insufficientEvidence: string;
+  qualityGuardrailFailed: string;
+  improved: string;
+  noDemonstratedImprovement: string;
+  clearLocalData: string;
+  clearLocalDataConfirm: string;
+  strictOutputRejected: string;
+}
+
 export interface Translations {
   statusBar: {
     loading: string;
@@ -47,6 +109,7 @@ export interface Translations {
   };
   releaseAnnouncement: {
     v230: string;
+    v231: string;
   };
   providers: ProviderTranslations;
   weeklyValue: WeeklyValueCopy;
@@ -62,6 +125,8 @@ export interface Translations {
     settings: string;
     settingsTab: string;
     settingsIntro: string;
+    secretMigrationFailed: string;
+    secretMigrationWorkspace: string;
     settingsResetAll: string;
     settingsGroupGeneral: string;
     settingsGroupProviders: string;
@@ -69,6 +134,7 @@ export interface Translations {
     settingsGroupStatusBar: string;
     settingsGroupData: string;
     settingsGroupAdvice: string;
+    adviceEffectiveness: AdviceEffectivenessTranslations;
     totalTokens: string;
     inputTokens: string;
     outputTokens: string;
@@ -137,8 +203,8 @@ export interface Translations {
     model: string;
     agents: string;
     agent: string;
-    workflowsThisMonth: string;
-    workflowCostShare: string;
+    workflowsLast30Days: string;
+    workflowLast30DaysCostShare: string;
     workflowCacheHint: string;
     adhocBadge: string;
     workflowModeBadge: string;
@@ -249,13 +315,15 @@ type CodexCopyMapKey =
   | 'insightTitles'
   | 'insightObservations'
   | 'insightTips'
-  | 'insightEvidenceLabels';
+  | 'insightEvidenceLabels'
+  | 'indexingReasons';
 
 type CodexCopyOverrides = Partial<Omit<CodexViewCopy, CodexCopyMapKey>> & {
   insightTitles?: Partial<CodexViewCopy['insightTitles']>;
   insightObservations?: Partial<CodexViewCopy['insightObservations']>;
   insightTips?: Partial<CodexViewCopy['insightTips']>;
   insightEvidenceLabels?: Partial<CodexViewCopy['insightEvidenceLabels']>;
+  indexingReasons?: Partial<CodexViewCopy['indexingReasons']>;
 };
 
 const TASK5_CODEX_COPY: Record<Exclude<SupportedLanguage, 'en'>, CodexCopyOverrides> = {
@@ -494,6 +562,7 @@ type CodexTask8CopyKey =
   | 'indexedAllTime'
   | 'indexedSubtotal'
   | 'indexingInProgress'
+  | 'indexingReasons'
   | 'updatedAt'
   | 'claudeTokenAccounting'
   | 'codexTokenAccounting'
@@ -513,6 +582,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: 'Indexierter Gesamtzeitraum',
     indexedSubtotal: 'Indizierte Zwischensumme',
     indexingInProgress: 'Die Indexierung läuft noch; nicht verifizierte Altsummen werden ausgeschlossen.',
+    indexingReasons: {
+      'first-index': 'Erste lokale Verlaufseinrichtung',
+      'parser-migration': 'Lokalen Parser-Index aktualisieren',
+      'period-migration': 'Datumsverlauf aktualisieren',
+      'hourly-history': 'Stündlichen Verlauf der letzten Zeit erstellen',
+      'history-backfill': 'Lokalen Verlauf vervollständigen',
+      'rule-migration': 'Messregeln aktualisieren',
+      resume: 'Lokalen Verlauf fortsetzen',
+    },
     updatedAt: 'Aktualisiert um',
     claudeTokenAccounting: 'Claude-Token-Zählung',
     codexTokenAccounting: 'Codex-Token-Zählung',
@@ -547,6 +625,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: '已索引的全部時間',
     indexedSubtotal: '已索引小計',
     indexingInProgress: '索引仍在進行；未驗證的舊版總量不會計入。',
+    indexingReasons: {
+      'first-index': '首次設定本機歷史',
+      'parser-migration': '更新本機解析器索引',
+      'period-migration': '更新日期歷史',
+      'hourly-history': '建立近期每小時歷史',
+      'history-backfill': '補齊本機歷史',
+      'rule-migration': '更新量測規則',
+      resume: '繼續整理本機歷史',
+    },
     updatedAt: '更新於',
     claudeTokenAccounting: 'Claude Token 口徑',
     codexTokenAccounting: 'Codex Token 口徑',
@@ -581,6 +668,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: '已索引的全部时间',
     indexedSubtotal: '已索引小计',
     indexingInProgress: '索引仍在进行；未验证的旧版总量不会计入。',
+    indexingReasons: {
+      'first-index': '首次整理本地历史',
+      'parser-migration': '更新本地解析器索引',
+      'period-migration': '更新日期历史',
+      'hourly-history': '整理近期小时历史',
+      'history-backfill': '补齐本地历史',
+      'rule-migration': '更新测量规则',
+      resume: '继续整理本地历史',
+    },
     updatedAt: '更新时间',
     claudeTokenAccounting: 'Claude Token 口径',
     codexTokenAccounting: 'Codex Token 口径',
@@ -615,6 +711,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: '索引済みの全期間',
     indexedSubtotal: 'インデックス済み小計',
     indexingInProgress: 'インデックス作成中です。未検証の旧集計値は除外されています。',
+    indexingReasons: {
+      'first-index': '初回のローカル履歴設定',
+      'parser-migration': 'ローカル解析インデックスを更新中',
+      'period-migration': '日付履歴を更新中',
+      'hourly-history': '最近の時間別履歴を作成中',
+      'history-backfill': 'ローカル履歴を補完中',
+      'rule-migration': '測定ルールを更新中',
+      resume: 'ローカル履歴を再開中',
+    },
     updatedAt: '更新日時',
     claudeTokenAccounting: 'Claude トークン集計',
     codexTokenAccounting: 'Codex トークン集計',
@@ -649,6 +754,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: '인덱싱된 전체 기간',
     indexedSubtotal: '인덱싱된 소계',
     indexingInProgress: '인덱싱이 진행 중이며 검증되지 않은 이전 합계는 제외됩니다.',
+    indexingReasons: {
+      'first-index': '첫 로컬 기록 설정',
+      'parser-migration': '로컬 파서 인덱스 업데이트',
+      'period-migration': '날짜 기록 업데이트',
+      'hourly-history': '최근 시간별 기록 생성',
+      'history-backfill': '로컬 기록 완성',
+      'rule-migration': '측정 규칙 업데이트',
+      resume: '로컬 기록 재개',
+    },
     updatedAt: '업데이트 시각',
     claudeTokenAccounting: 'Claude 토큰 집계',
     codexTokenAccounting: 'Codex 토큰 집계',
@@ -683,6 +797,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: 'Todo o período indexado',
     indexedSubtotal: 'Subtotal indexado',
     indexingInProgress: 'A indexação ainda está em andamento; totais legados não verificados são excluídos.',
+    indexingReasons: {
+      'first-index': 'Primeira configuração do histórico local',
+      'parser-migration': 'Atualizando o índice do analisador local',
+      'period-migration': 'Atualizando o histórico por data',
+      'hourly-history': 'Criando o histórico horário recente',
+      'history-backfill': 'Concluindo o histórico local',
+      'rule-migration': 'Atualizando as regras de medição',
+      resume: 'Retomando o histórico local',
+    },
     updatedAt: 'Atualizado em',
     claudeTokenAccounting: 'Contagem de tokens do Claude',
     codexTokenAccounting: 'Contagem de tokens do Codex',
@@ -717,6 +840,15 @@ const TASK8_CODEX_COPY: Record<
     indexedAllTime: 'Seluruh waktu terindeks',
     indexedSubtotal: 'Subtotal terindeks',
     indexingInProgress: 'Pengindeksan masih berlangsung; total lama yang belum diverifikasi tidak disertakan.',
+    indexingReasons: {
+      'first-index': 'Penyiapan awal riwayat lokal',
+      'parser-migration': 'Memperbarui indeks parser lokal',
+      'period-migration': 'Memperbarui riwayat tanggal',
+      'hourly-history': 'Membuat riwayat per jam terbaru',
+      'history-backfill': 'Melengkapi riwayat lokal',
+      'rule-migration': 'Memperbarui aturan pengukuran',
+      resume: 'Melanjutkan riwayat lokal',
+    },
     updatedAt: 'Diperbarui pada',
     claudeTokenAccounting: 'Penghitungan token Claude',
     codexTokenAccounting: 'Penghitungan token Codex',
@@ -780,6 +912,11 @@ function providerTranslations(
         ...overrides.insightEvidenceLabels,
         ...task5Overrides.insightEvidenceLabels,
       },
+      indexingReasons: {
+        ...CODEX_COPY_EN.indexingReasons,
+        ...overrides.indexingReasons,
+        ...task5Overrides.indexingReasons,
+      },
     },
   };
 }
@@ -905,122 +1042,122 @@ const PROVIDERS: Record<SupportedLanguage, ProviderTranslations> = {
 
 const WEEKLY_VALUE_COPY: Record<SupportedLanguage, WeeklyValueCopy> = {
   en: {
-    title: 'Weekly allowance value',
-    description: 'Current official API prices applied to local tokens; full allowance is inferred from the last observed utilization in each reset window. Request-level surcharges absent from aggregate logs are excluded. Estimate, not a bill.',
-    period: 'Period', currentPeriod: 'Current period', currentPeriodShort: 'Current', resetsAt: 'resets',
+    title: 'Weekly subscription allowance · API-equivalent estimate',
+    description: 'A durability estimate for the subscription: current official API prices applied to local tokens, with total and unused value inferred from observed quota utilization. Request-level surcharges absent from aggregate logs are excluded. It is not an official balance, bill, or cash value.',
+    period: 'Period', periodDetails: 'Period details', currentPeriod: 'Current period', currentPeriodShort: 'Current', resetsAt: 'resets',
     usedValue: 'Used equivalent', fullValue: 'Full allowance est.', unusedValue: 'Unused est.',
     reset: 'Week / reset', utilization: 'End observed', confidence: 'Confidence', pricingCoverage: 'Priced coverage',
     current: 'In progress', high: 'High', medium: 'Medium', low: 'Low', usageOnly: 'Usage only',
     noData: 'No locally recorded weekly usage is available yet.',
     historyFromLogs: 'Historical used equivalents come directly from local token logs. Full and unused estimates appear only for windows with a real quota-utilization observation.',
     calendarFallback: 'No historical weekly reset was observed; usage-only history is grouped into Monday-to-Monday UTC calendar weeks.',
-    multiAccount: 'Codex usage-only history combines all sign-ins in this Codex home. When usage cannot be reliably attributed to a single quota observation, only the used equivalent is shown; no account split or allowance estimate is invented.',
-    boundaryApproximation: 'Codex usage is aggregated by day. If an official reset falls within a recorded day, the affected period keeps only its used equivalent; full and unused values are not inferred.',
+    multiAccount: 'Codex local history may span multiple sign-ins. The current window uses the latest real quota observation for a low-confidence blended durability estimate even when local series overlap; ambiguous completed windows remain usage-only. No account split or official balance is invented.',
+    boundaryApproximation: 'Codex usage is aggregated by day. A reset inside a recorded day lowers confidence, but current and completed windows may still show total and unused approximations.',
     boundaryApproximate: 'Boundary approx.',
     indexedSubtotal: 'Indexing is incomplete; weekly values are conservative subtotals.',
   },
   'zh-CN': {
-    title: '每周等效额度价值',
-    description: '按当前官方 API 单价折算本地 Token；每个重置窗口的总额度由最后观测用量比例反推。聚合日志无法确认的请求级附加价格不计入。属于估算，并非账单。',
-    period: '周期', currentPeriod: '当前周期', currentPeriodShort: '当前', resetsAt: '重置于',
+    title: '每周订阅额度 · API 等效估算',
+    description: '用于粗略理解订阅套餐耐用度：按当前官方 API 单价折算本地 Token，并由真实额度观测反推总额和未用值。聚合日志无法确认的请求级附加价格不计入。它不是官方余额、账单或现金价值。',
+    period: '周期', periodDetails: '周期详情', currentPeriod: '当前周期', currentPeriodShort: '当前', resetsAt: '重置于',
     usedValue: '已用等价值', fullValue: '总额度估算', unusedValue: '未用估算',
     reset: '周期 / 重置', utilization: '末次观测', confidence: '可信度', pricingCoverage: '已定价覆盖',
     current: '进行中', high: '高', medium: '中', low: '低', usageOnly: '仅已用值',
     noData: '尚无可用于按周计算的本地用量记录。',
     historyFromLogs: '历史“已用等价值”直接由本地 Token 日志计算；只有某个窗口存在真实额度用量观测时，才显示总额度和未用额度估算。',
     calendarFallback: '未观测到可用于对齐历史的每周重置时间；仅已用历史按 UTC 周一至周一的自然周分组。',
-    multiAccount: 'Codex 的仅已用历史会合并此 Codex home 中的全部登录。用量无法可靠归属到单一额度观测时，只显示已用等价值；不会虚构账号拆分或额度估算。',
-    boundaryApproximation: 'Codex 用量按日汇总。如果官方重置发生在某个已记录日期内，受影响周期只保留已用等价值，不反推总额度或未用额度。',
+    multiAccount: 'Codex 本地历史可能跨多个登录。即使本地额度系列重叠，当前周期仍会采用最后一次真实额度观测给出低可信度的混合耐用度估算；归属不清的已结束周期仍只显示已用值。不虚构账号拆分或官方余额。',
+    boundaryApproximation: 'Codex 用量按日汇总。若官方重置发生在某个记录日内，可信度会降低，但当前和已结束周期仍可显示总额与未用近似值。',
     boundaryApproximate: '边界近似',
     indexedSubtotal: '索引尚未完成；每周价值目前是保守小计。',
   },
   'zh-TW': {
-    title: '每週等效額度價值',
-    description: '依目前官方 API 單價折算本機 Token；每個重設視窗的總額度由最後觀測用量比例反推。彙總日誌無法確認的請求級附加價格不計入。屬於估算，並非帳單。',
-    period: '週期', currentPeriod: '目前週期', currentPeriodShort: '目前', resetsAt: '重設於',
+    title: '每週訂閱額度 · API 等效估算',
+    description: '用於粗略理解訂閱方案耐用度：依目前官方 API 單價折算本機 Token，並由真實額度觀測反推總額與未用值。彙總日誌無法確認的請求級附加價格不計入。它不是官方餘額、帳單或現金價值。',
+    period: '週期', periodDetails: '週期詳情', currentPeriod: '目前週期', currentPeriodShort: '目前', resetsAt: '重設於',
     usedValue: '已用等價值', fullValue: '總額度估算', unusedValue: '未用估算',
     reset: '週期 / 重設', utilization: '末次觀測', confidence: '可信度', pricingCoverage: '已定價涵蓋',
     current: '進行中', high: '高', medium: '中', low: '低', usageOnly: '僅已用值',
     noData: '尚無可用於每週計算的本機用量記錄。',
     historyFromLogs: '歷史「已用等價值」直接由本機 Token 日誌計算；只有視窗存在真實額度用量觀測時，才顯示總額度與未用額度估算。',
     calendarFallback: '未觀測到可用於對齊歷史的每週重設時間；僅已用歷史依 UTC 週一至週一的自然週分組。',
-    multiAccount: 'Codex 的僅已用歷史會合併此 Codex home 中的所有登入。用量無法可靠歸屬到單一額度觀測時，只顯示已用等價值；不會虛構帳號拆分或額度估算。',
-    boundaryApproximation: 'Codex 用量按日彙總。如果官方重設發生在某個已記錄日期內，受影響週期只保留已用等價值，不反推總額度或未用額度。',
+    multiAccount: 'Codex 本機歷史可能跨多個登入。即使本機額度系列重疊，目前週期仍會採用最後一次真實額度觀測提供低可信度的混合耐用度估算；歸屬不清的已結束週期仍只顯示已用值。不虛構帳號拆分或官方餘額。',
+    boundaryApproximation: 'Codex 用量按日彙總。若官方重設發生於某個記錄日內，可信度會降低，但目前與已結束週期仍可顯示總額與未用近似值。',
     boundaryApproximate: '邊界近似',
     indexedSubtotal: '索引尚未完成；每週價值目前是保守小計。',
   },
   ja: {
-    title: '週間上限の等価価値',
-    description: '現在の公式 API 単価をローカルトークンに適用し、各リセット枠の総上限を最終観測利用率から推定します。集計ログで確認できないリクエスト単位の追加料金は含みません。請求額ではありません。',
-    period: '期間', currentPeriod: '現在の期間', currentPeriodShort: '現在', resetsAt: 'リセット',
+    title: '週間サブスクリプション枠 · API 等価推定',
+    description: 'サブスクリプションの耐用度を把握するため、現在の公式 API 単価をローカル Token に適用し、観測された枠の利用率から総量と未使用量を推定します。集計ログで確認できないリクエスト単位の追加料金は含みません。公式残高、請求額、現金価値ではありません。',
+    period: '期間', periodDetails: '期間の詳細', currentPeriod: '現在の期間', currentPeriodShort: '現在', resetsAt: 'リセット',
     usedValue: '使用済み等価値', fullValue: '総上限の推定', unusedValue: '未使用の推定',
     reset: '期間 / リセット', utilization: '最終観測', confidence: '信頼度', pricingCoverage: '価格適用率',
     current: '進行中', high: '高', medium: '中', low: '低', usageOnly: '使用分のみ',
     noData: '週単位で計算できるローカル使用記録がまだありません。',
     historyFromLogs: '過去の使用済み等価値はローカルの Token ログから直接計算します。総上限と未使用分は、実際の上限利用率が観測された枠だけで推定します。',
     calendarFallback: '履歴を揃える週間リセットが観測されていないため、使用分のみの履歴は UTC の月曜から月曜の暦週で集計します。',
-    multiAccount: 'Codex の使用分のみの履歴は、この Codex home の全ログインを合算します。使用量を単一の上限観測に確実に帰属できない場合は使用済み等価値だけを表示し、アカウント分割や上限推定を作りません。',
-    boundaryApproximation: 'Codex の使用量は日単位で集計されます。公式リセットが記録日の途中にある場合、影響する期間は使用済み等価値だけを保持し、総上限や未使用分を推定しません。',
+    multiAccount: 'Codex のローカル履歴には複数のログインが含まれる場合があります。ローカルの系列が重複していても、現在の期間は最新の実測クォータを使った低信頼度の混合耐久性推定を表示します。帰属が曖昧な完了期間は使用分のみです。アカウント分割や公式残高は推測しません。',
+    boundaryApproximation: 'Codex の使用量は日単位で集計されます。記録日の途中にリセットがあると信頼度は下がりますが、現在と完了済みの枠に総量と未使用量の近似を表示できます。',
     boundaryApproximate: '境界近似',
     indexedSubtotal: '索引作成中のため、週間価値は保守的な小計です。',
   },
   ko: {
-    title: '주간 한도 등가 가치',
-    description: '현재 공식 API 단가를 로컬 토큰에 적용하고 각 재설정 창의 총한도를 마지막 관측 사용률로 추정합니다. 집계 로그에서 확인할 수 없는 요청 단위 추가 요금은 제외합니다. 청구 금액이 아닙니다.',
-    period: '기간', currentPeriod: '현재 기간', currentPeriodShort: '현재', resetsAt: '재설정',
+    title: '주간 구독 한도 · API 등가 추정',
+    description: '구독이 얼마나 오래 지속되는지 가늠하기 위해 현재 공식 API 단가를 로컬 Token에 적용하고, 관측된 한도 사용률에서 총량과 미사용량을 추정합니다. 집계 로그에서 확인할 수 없는 요청 단위 추가 요금은 제외합니다. 공식 잔액, 청구액 또는 현금 가치가 아닙니다.',
+    period: '기간', periodDetails: '기간 세부 정보', currentPeriod: '현재 기간', currentPeriodShort: '현재', resetsAt: '재설정',
     usedValue: '사용 등가치', fullValue: '총한도 추정', unusedValue: '미사용 추정',
     reset: '주 / 재설정', utilization: '마지막 관측', confidence: '신뢰도', pricingCoverage: '가격 적용률',
     current: '진행 중', high: '높음', medium: '보통', low: '낮음', usageOnly: '사용분만',
     noData: '주간 계산에 사용할 로컬 사용 기록이 아직 없습니다.',
     historyFromLogs: '과거 사용 등가치는 로컬 Token 로그에서 직접 계산합니다. 실제 한도 사용률 관측이 있는 창에서만 총한도와 미사용분을 추정합니다.',
     calendarFallback: '과거를 정렬할 주간 재설정이 관측되지 않아 사용분 전용 기록은 UTC 월요일부터 월요일까지의 달력 주로 묶습니다.',
-    multiAccount: 'Codex 사용분 전용 기록은 이 Codex home의 모든 로그인을 합산합니다. 사용량을 단일 할당량 관측에 안정적으로 귀속할 수 없으면 사용 등가치만 표시하며 계정 분리나 한도 추정을 만들어 내지 않습니다.',
-    boundaryApproximation: 'Codex 사용량은 일별로 집계됩니다. 공식 재설정이 기록된 하루 중간에 발생하면 영향을 받는 기간에는 사용 등가치만 유지하고 총한도나 미사용분을 추정하지 않습니다.',
+    multiAccount: 'Codex 로컬 기록에는 여러 로그인이 포함될 수 있습니다. 로컬 할당량 계열이 겹쳐도 현재 기간은 마지막 실제 할당량 관측으로 신뢰도 낮은 혼합 내구성 추정을 표시합니다. 귀속이 불명확한 완료 기간은 사용분만 표시합니다. 계정 분리나 공식 잔액은 추정하지 않습니다.',
+    boundaryApproximation: 'Codex 사용량은 일별로 집계됩니다. 기록일 중간에 재설정이 있으면 신뢰도가 낮아지지만 현재 및 완료 창에도 총량과 미사용 근사를 표시할 수 있습니다.',
     boundaryApproximate: '경계 근사',
     indexedSubtotal: '인덱싱이 끝나지 않아 주간 가치는 보수적인 소계입니다.',
   },
   'pt-BR': {
-    title: 'Valor equivalente semanal',
-    description: 'Aplica os preços oficiais atuais da API aos tokens locais e infere o limite total pela última utilização observada em cada janela. Sobretaxas por solicitação ausentes dos logs agregados não são incluídas. É uma estimativa, não uma fatura.',
-    period: 'Período', currentPeriod: 'Período atual', currentPeriodShort: 'Atual', resetsAt: 'reinicia em',
+    title: 'Cota semanal da assinatura · estimativa equivalente à API',
+    description: 'Estima a durabilidade da assinatura aplicando os preços oficiais atuais da API aos Tokens locais e inferindo o total e o saldo não usado a partir da utilização de cota observada. Sobretaxas por solicitação ausentes dos logs agregados são excluídas. Não é saldo oficial, fatura nem valor em dinheiro.',
+    period: 'Período', periodDetails: 'Detalhes do período', currentPeriod: 'Período atual', currentPeriodShort: 'Atual', resetsAt: 'reinicia em',
     usedValue: 'Equivalente usado', fullValue: 'Limite total est.', unusedValue: 'Não usado est.',
     reset: 'Semana / reset', utilization: 'Última observação', confidence: 'Confiança', pricingCoverage: 'Cobertura de preços',
     current: 'Em andamento', high: 'Alta', medium: 'Média', low: 'Baixa', usageOnly: 'Somente uso',
     noData: 'Ainda não há uso local registrado para o cálculo semanal.',
     historyFromLogs: 'Os equivalentes usados no histórico vêm diretamente dos logs locais de Token. O limite total e o não usado só são estimados quando há uma observação real da utilização da cota.',
     calendarFallback: 'Nenhuma redefinição semanal histórica foi observada; o histórico somente de uso é agrupado em semanas UTC de segunda a segunda.',
-    multiAccount: 'O histórico somente de uso do Codex combina todos os logins deste Codex home. Quando o uso não pode ser atribuído com segurança a uma única observação de cota, só o equivalente usado é mostrado; nenhuma divisão por conta ou estimativa de limite é inventada.',
-    boundaryApproximation: 'O uso do Codex é agregado por dia. Se uma redefinição oficial ocorrer dentro de um dia registrado, o período afetado mantém apenas o equivalente usado; o limite total e o não usado não são inferidos.',
+    multiAccount: 'O histórico local do Codex pode abranger vários logins. Mesmo com séries locais sobrepostas, o período atual usa a observação real mais recente para uma estimativa combinada de baixa confiança; períodos concluídos com atribuição ambígua mostram apenas o uso. Nenhuma divisão de conta ou saldo oficial é inventado.',
+    boundaryApproximation: 'O uso do Codex é agregado por dia. Uma redefinição dentro de um dia registrado reduz a confiança, mas janelas atuais e concluídas ainda podem mostrar aproximações do total e do restante.',
     boundaryApproximate: 'Fronteira aprox.',
     indexedSubtotal: 'A indexação está incompleta; os valores semanais são subtotais conservadores.',
   },
   'de-DE': {
-    title: 'Wöchentlicher Gegenwert',
-    description: 'Aktuelle offizielle API-Preise werden auf lokale Token angewandt; das Gesamtlimit wird aus der letzten beobachteten Auslastung je Reset-Fenster geschätzt. Anfragebezogene Aufpreise, die in aggregierten Logs fehlen, sind ausgeschlossen. Keine Rechnung.',
-    period: 'Zeitraum', currentPeriod: 'Aktueller Zeitraum', currentPeriodShort: 'Aktuell', resetsAt: 'Reset',
+    title: 'Wöchentliches Abo-Kontingent · API-Äquivalenzschätzung',
+    description: 'Schätzt die Reichweite des Abonnements, indem aktuelle offizielle API-Preise auf lokale Token angewandt und Gesamt- sowie Restwert aus beobachteter Kontingentnutzung abgeleitet werden. Anfragebezogene Aufpreise, die in aggregierten Logs fehlen, sind ausgeschlossen. Dies ist weder offizielles Guthaben noch Rechnung oder Barwert.',
+    period: 'Zeitraum', periodDetails: 'Zeitraumdetails', currentPeriod: 'Aktueller Zeitraum', currentPeriodShort: 'Aktuell', resetsAt: 'Reset',
     usedValue: 'Genutzter Gegenwert', fullValue: 'Gesamtlimit geschätzt', unusedValue: 'Ungenutzt geschätzt',
     reset: 'Woche / Reset', utilization: 'Letzte Beobachtung', confidence: 'Vertrauen', pricingCoverage: 'Preisabdeckung',
     current: 'Laufend', high: 'Hoch', medium: 'Mittel', low: 'Niedrig', usageOnly: 'Nur Nutzung',
     noData: 'Noch keine lokal erfasste Nutzung für die Wochenberechnung verfügbar.',
     historyFromLogs: 'Historische genutzte Gegenwerte stammen direkt aus lokalen Token-Logs. Gesamtlimit und ungenutzter Anteil werden nur bei real beobachteter Quotenauslastung geschätzt.',
     calendarFallback: 'Kein historischer Wochen-Reset wurde beobachtet; reine Nutzungsverläufe werden in UTC-Kalenderwochen von Montag bis Montag gruppiert.',
-    multiAccount: 'Der reine Codex-Nutzungsverlauf kombiniert alle Anmeldungen in diesem Codex home. Lässt sich die Nutzung nicht zuverlässig einer einzelnen Kontingentbeobachtung zuordnen, wird nur der genutzte Gegenwert angezeigt; weder Kontotrennung noch Limitschätzung werden erfunden.',
-    boundaryApproximation: 'Die Codex-Nutzung wird tageweise aggregiert. Fällt ein offizieller Reset in einen erfassten Tag, behält der betroffene Zeitraum nur den genutzten Gegenwert; Gesamtlimit und ungenutzter Anteil werden nicht geschätzt.',
+    multiAccount: 'Der lokale Codex-Verlauf kann mehrere Anmeldungen umfassen. Auch bei überlappenden lokalen Serien nutzt der aktuelle Zeitraum die jüngste reale Kontingentbeobachtung für eine zusammengeführte Schätzung mit niedriger Zuverlässigkeit; mehrdeutige abgeschlossene Zeiträume zeigen nur die Nutzung. Weder Kontotrennung noch offizielles Guthaben werden erfunden.',
+    boundaryApproximation: 'Die Codex-Nutzung wird tageweise aggregiert. Ein Reset innerhalb eines erfassten Tages senkt die Zuverlässigkeit, dennoch können aktuelle und abgeschlossene Fenster Näherungen für Gesamt- und Restwert zeigen.',
     boundaryApproximate: 'Grenznäherung',
     indexedSubtotal: 'Die Indizierung ist unvollständig; Wochenwerte sind konservative Zwischensummen.',
   },
   id: {
-    title: 'Nilai ekuivalen mingguan',
-    description: 'Harga API resmi saat ini diterapkan pada token lokal; total batas disimpulkan dari pemakaian terakhir yang diamati pada tiap jendela reset. Biaya tambahan per permintaan yang tidak ada dalam log agregat tidak dihitung. Ini perkiraan, bukan tagihan.',
-    period: 'Periode', currentPeriod: 'Periode saat ini', currentPeriodShort: 'Saat ini', resetsAt: 'reset',
+    title: 'Batas langganan mingguan · estimasi ekuivalen API',
+    description: 'Memperkirakan daya tahan langganan dengan menerapkan harga API resmi terkini pada Token lokal, lalu menyimpulkan total dan sisa dari pemakaian kuota yang teramati. Biaya tambahan per permintaan yang tidak ada dalam log agregat dikecualikan. Ini bukan saldo resmi, tagihan, atau nilai tunai.',
+    period: 'Periode', periodDetails: 'Detail periode', currentPeriod: 'Periode saat ini', currentPeriodShort: 'Saat ini', resetsAt: 'reset',
     usedValue: 'Ekuivalen terpakai', fullValue: 'Total batas estimasi', unusedValue: 'Tak terpakai estimasi',
     reset: 'Minggu / reset', utilization: 'Pengamatan akhir', confidence: 'Keyakinan', pricingCoverage: 'Cakupan harga',
     current: 'Berjalan', high: 'Tinggi', medium: 'Sedang', low: 'Rendah', usageOnly: 'Hanya pemakaian',
     noData: 'Belum ada penggunaan lokal yang tercatat untuk perhitungan mingguan.',
     historyFromLogs: 'Ekuivalen terpakai historis dihitung langsung dari log Token lokal. Total batas dan sisa hanya diestimasi jika ada pengamatan nyata atas persentase kuota.',
     calendarFallback: 'Tidak ada reset mingguan historis yang teramati; riwayat khusus pemakaian dikelompokkan dalam minggu UTC Senin-ke-Senin.',
-    multiAccount: 'Riwayat khusus pemakaian Codex menggabungkan semua login di Codex home ini. Jika penggunaan tidak dapat dikaitkan secara andal ke satu pengamatan kuota, hanya ekuivalen terpakai yang ditampilkan; pemisahan akun atau perkiraan batas tidak direka.',
-    boundaryApproximation: 'Penggunaan Codex diagregasi per hari. Jika reset resmi terjadi di tengah hari yang tercatat, periode yang terdampak hanya mempertahankan ekuivalen terpakai; total batas dan sisa tidak diperkirakan.',
+    multiAccount: 'Riwayat lokal Codex dapat mencakup beberapa login. Meski seri lokal tumpang tindih, periode saat ini memakai pengamatan kuota nyata terbaru untuk perkiraan daya tahan gabungan berkeyakinan rendah; periode selesai yang ambigu tetap hanya menampilkan pemakaian. Pemisahan akun atau saldo resmi tidak direka.',
+    boundaryApproximation: 'Penggunaan Codex diagregasi per hari. Reset di tengah hari tercatat menurunkan keyakinan, tetapi jendela saat ini dan selesai tetap dapat menampilkan perkiraan total dan sisa.',
     boundaryApproximate: 'Perkiraan batas',
     indexedSubtotal: 'Pengindeksan belum selesai; nilai mingguan masih berupa subtotal konservatif.',
   },
@@ -1038,6 +1175,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: "What's new — Codex Beta usage and local optimization guidance, exact-version release notes, and removal of the obsolete model-specific weekly Opus option.",
+      v231: 'Accurate 30-day Codex totals, reset-aware weekly allowance estimates, and a private combined activity heatmap with local SVG and Markdown sharing.',
     },
     providers: PROVIDERS.en,
     weeklyValue: WEEKLY_VALUE_COPY.en,
@@ -1053,7 +1191,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: 'Settings',
       settingsTab: 'Settings',
       settingsIntro:
-        'Settings live here now. Only language, data directory and API key remain in VS Code Settings (so they sync). Changes apply immediately.',
+        'Settings live here now. Language and data directories remain in VS Code Settings; API keys use VS Code SecretStorage and never sync. Changes apply immediately.',
+      secretMigrationFailed:
+        'Claude Code Usage could not move the saved advice API key into encrypted SecretStorage. The extension stopped before deleting the old value. Fix the legacy setting and reload the window.',
+      secretMigrationWorkspace:
+        'A workspace-specific advice API key cannot be migrated safely into one global SecretStorage entry. Copy it, remove it from workspace settings, reload, then enter it under Dashboard Settings → Advice.',
       settingsResetAll: 'Reset all to defaults',
       settingsGroupGeneral: 'General',
       settingsGroupProviders: 'Providers',
@@ -1061,6 +1203,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: 'Status bar',
       settingsGroupData: 'Data & refresh',
       settingsGroupAdvice: 'AI advice & Optimizer',
+      adviceEffectiveness: {
+        title: 'AI advice effectiveness',
+        description: 'Review how each suggestion moves from a local observation to evidence, an action, and a guarded result.',
+        candidateNotice: 'v2.3.1 candidate · off by default · no default or background AI requests.',
+        spineLabel: 'Advice evidence path',
+        observation: 'Observation',
+        evidence: 'Evidence',
+        recommendation: 'Advice',
+        action: 'Action',
+        result: 'Result',
+        source: 'Source',
+        limitations: 'Limitations',
+        proxyMetric: 'Proxy metric',
+        longSessionSignal: '{share} of observed usage came from long sessions.',
+        largeContextSignal: '{share} of observed usage occurred at large context sizes.',
+        frameworkOverheadSignal: '{share} of observed usage is separately estimated framework injection; it does not evaluate the quality of the user\'s writing.',
+        clearBoundaryRecommendation: 'Use clearer task boundaries for long or large-context work.',
+        clearBoundaryAction: 'Start a fresh session when the task changes; compact only when continuing the same task.',
+        codexLocalRecommendation: 'Review the local Codex structural signal before the next comparable task.',
+        noEvidenceAdvice: 'No evidence-backed advice is available for this scope.',
+        codexPreviewUnavailable: 'A privacy-safe Codex aggregate payload preview is not available yet.',
+        elapsedTimeProxy: 'Elapsed session span is a proxy, not measured active work time.',
+        qualityGuardrailPending: 'Quality evidence is pending, so no effectiveness conclusion is available.',
+        payloadTitle: 'Sealed payload snapshot',
+        payloadDescription: 'This sealed snapshot is the exact UTF-8 JSON body the configured BYOK endpoint receives only after the separate Send click.',
+        aggregatesOnly: 'Aggregates only',
+        aggregatesWithPersonalization: 'Aggregates + explicitly allowed personal context',
+        aggregatesWithPromptSamples: 'Aggregates + explicitly allowed prompt samples',
+        payloadBytes: '{bytes} UTF-8 bytes',
+        promptSamplesIncluded: '{count} prompt samples included',
+        previewPayload: 'Preview sealed snapshot',
+        noNetworkTransport: 'Previewing sends nothing. Sending requires a separate click.',
+        sendPreparedRequest: 'Send this exact request',
+        sendingPreparedRequest: 'Sending…',
+        sentPreparedRequest: 'Structured advice received.',
+        aggregateConsentLabel: 'Allow aggregate usage data',
+        aggregateConsentHelp: 'Includes only allowlisted numeric aggregates and structural signals — no prompts, paths, session IDs, or individual records.',
+        promptConsentLabel: 'Also include prompt samples and configured personal context',
+        promptConsentHelp: 'Optional and off by default. Bounded prompt text and configured personal context are added only after this separate explicit consent.',
+        promptWindowHelp: 'Prompt samples older than the configured {days}-day evidence window are excluded.',
+        feedbackTitle: 'Local feedback',
+        helpful: 'Helpful',
+        notHelpful: 'Not helpful',
+        applied: 'Applied',
+        snooze: 'Snooze 7 days',
+        resume: 'Show again',
+        snoozedUntil: 'Snoozed until {date}',
+        feedbackLocalOnly: 'Stored only on this device and never added to a remote payload.',
+        feedbackSaveFailed: 'Feedback could not be saved locally. Nothing was sent.',
+        comparisonTitle: 'Comparable task results',
+        comparablePairs: '{count} comparable task pairs',
+        minimumComparablePairs: 'At least {minimum} comparable task pairs are required before drawing a conclusion.',
+        insufficientEvidence: 'Not enough evidence to draw a conclusion.',
+        qualityGuardrailFailed: 'The quality guardrail did not hold, so no effectiveness claim is made.',
+        improved: 'Improvement met the pre-declared threshold while the quality guardrail held.',
+        noDemonstratedImprovement: 'No improvement was demonstrated; this does not establish harm or causation.',
+        clearLocalData: 'Clear local advice data',
+        clearLocalDataConfirm: 'Clear advice consent, feedback, comparable pairs, and comparison results stored on this device?',
+        strictOutputRejected: 'The structured model output was rejected. No advice was created.',
+      },
       totalTokens: 'Total Tokens',
       inputTokens: 'Input Tokens',
       outputTokens: 'Output Tokens',
@@ -1129,8 +1331,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: 'Model',
       agents: 'Agents',
       agent: 'Agent',
-      workflowsThisMonth: 'Workflows this month',
-      workflowCostShare: "share of this month's cost",
+      workflowsLast30Days: 'Workflows in the last 30 days',
+      workflowLast30DaysCostShare: "share of the last 30 days' cost",
       workflowCacheHint:
         'Cache hit rate = cache reads ÷ all input-side tokens. Native Claude workflows reuse the prompt cache across agents (high rate); a provider without cross-agent caching shows ~0% — the same workflow costs disproportionately more there.',
       adhocBadge: 'subagents (ad-hoc)',
@@ -1203,14 +1405,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: 'Get AI Advice',
       adviceCardTitle: 'AI advice',
       adviceCardDesc:
-        'Send your usage digest + a sample of your own prompts to your model and get concrete tips on writing clearer instructions and cutting waste.',
+        'Review local evidence first. The exact request defaults to aggregates only; prompt samples and personal context require separate consent, and nothing is sent until you click Send.',
       optimizerTitle: 'Usage optimizer',
       optimizerDesc:
         'Turn a rough, half-formed request into a clean prompt you can paste straight into Claude Code — plus a suggested effort / thinking / model for the task.',
       optimizerHowto:
-        'Type or paste your draft below, tick any of the optional tweaks, then click Optimise. Only the text you paste is sent to your model — never to Claude Code or your terminal.',
+        'Type or paste your draft below, choose any optional tweaks, then build the exact request preview. Nothing is sent until you click Send; only the text you pasted can be included.',
       optimizerConsent:
-        'The Usage Optimizer sends the text you paste to your configured API model. Nothing is sent to Claude Code and nothing is typed into a terminal. Continue?',
+        'Build the exact request preview? This does not send anything; sending to your configured API model requires a separate click.',
       optimizerEnableBtn: 'Enable in settings',
       optimizerPlaceholder: 'Paste a rough prompt to optimise…',
       optimizerRun: 'Optimise',
@@ -1242,10 +1444,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> feature produces. It is **not** based on your actual Claude Code\n' +
         '> usage data — nothing was sent to any API to generate this.\n\n' +
         '### To get real, personalised advice based on YOUR usage:\n\n' +
-        '1. Open Settings (`Ctrl+,` / `Cmd+,`)\n' +
-        '2. Search for **`claudeCodeUsage.advice.apiKey`**\n' +
-        '3. Paste an OpenAI-compatible API key — DeepSeek works out of the box\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. Run **`Claude Code Usage: Show Usage Details`**\n' +
+        '2. Open the dashboard **Settings → Advice** section\n' +
+        '3. Paste an OpenAI-compatible API key — it is kept in VS Code SecretStorage\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. Re-run **`Claude Code Usage: Get AI Usage Advice`**',
       costComposition: 'Cost Composition',
       date: 'Date',
@@ -1273,6 +1475,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: 'Neu: Codex-Beta-Nutzung und lokale Optimierungshinweise, versionsgenaue Release-Hinweise und Entfernung der veralteten modellspezifischen wöchentlichen Opus-Option.',
+      v231: 'Neu: korrekte 30-Tage-Codex-Werte, reset-bewusste Wochenschätzungen und eine private kombinierte Aktivitäts-Heatmap mit lokalem SVG- und Markdown-Export.',
     },
     providers: PROVIDERS['de-DE'],
     weeklyValue: WEEKLY_VALUE_COPY['de-DE'],
@@ -1288,7 +1491,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: "Einstellungen",
       settingsTab: "Einstellungen",
       settingsIntro:
-        "Die Einstellungen sind jetzt hier. Nur Sprache, Datenverzeichnis und API-Schlüssel bleiben in den VS-Code-Einstellungen (damit sie synchronisiert werden). Änderungen wirken sofort.",
+        "Die Einstellungen sind jetzt hier. Sprache und Datenverzeichnisse bleiben in den VS-Code-Einstellungen; API-Schlüssel liegen in VS Code SecretStorage und werden nie synchronisiert. Änderungen wirken sofort.",
+      secretMigrationFailed:
+        'Der gespeicherte API-Schlüssel konnte nicht in den verschlüsselten SecretStorage verschoben werden. Die Erweiterung wurde beendet, bevor der alte Wert gelöscht wurde. Korrigieren Sie die alte Einstellung und laden Sie das Fenster neu.',
+      secretMigrationWorkspace:
+        'Ein arbeitsbereichsspezifischer API-Schlüssel kann nicht sicher in einen globalen SecretStorage-Eintrag migriert werden. Kopieren und entfernen Sie ihn aus den Arbeitsbereichseinstellungen, laden Sie neu und geben Sie ihn unter Dashboard-Einstellungen → Beratung ein.',
       settingsResetAll: "Alle zurücksetzen",
       settingsGroupGeneral: "Allgemein",
       settingsGroupProviders: "Anbieter",
@@ -1296,6 +1503,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: "Statusleiste",
       settingsGroupData: "Daten & Aktualisierung",
       settingsGroupAdvice: "KI-Beratung & Optimizer",
+      adviceEffectiveness: {
+        title: 'Wirksamkeit von KI-Empfehlungen',
+        description: 'Prüfe, wie jede Empfehlung von einer lokalen Beobachtung über Evidenz und eine Maßnahme zu einem abgesicherten Ergebnis gelangt.',
+        candidateNotice: 'v2.3.1-Kandidat · standardmäßig deaktiviert · keine standardmäßigen oder Hintergrund-KI-Anfragen.',
+        spineLabel: 'Evidenzpfad der Empfehlung',
+        observation: 'Beobachtung',
+        evidence: 'Evidenz',
+        recommendation: 'Empfehlung',
+        action: 'Maßnahme',
+        result: 'Ergebnis',
+        source: 'Quelle',
+        limitations: 'Einschränkungen',
+        proxyMetric: 'Proxy-Metrik',
+        longSessionSignal: '{share} der beobachteten Nutzung stammten aus langen Sitzungen.',
+        largeContextSignal: '{share} der beobachteten Nutzung traten bei großen Kontextgrößen auf.',
+        frameworkOverheadSignal: '{share} der beobachteten Nutzung entfallen auf separat geschätzte Framework-Injektionen; dies bewertet nicht die Qualität der Texte des Nutzers.',
+        clearBoundaryRecommendation: 'Nutze klarere Aufgabengrenzen für lange Arbeiten oder Arbeiten mit großem Kontext.',
+        clearBoundaryAction: 'Beginne bei einem Aufgabenwechsel eine neue Sitzung; kompaktiere nur beim Fortsetzen derselben Aufgabe.',
+        codexLocalRecommendation: 'Prüfe vor der nächsten vergleichbaren Aufgabe das lokale strukturelle Codex-Signal.',
+        noEvidenceAdvice: 'Für diesen Bereich ist keine evidenzbasierte Empfehlung verfügbar.',
+        codexPreviewUnavailable: 'Eine datenschutzfreundliche Vorschau der aggregierten Codex-Payload ist noch nicht verfügbar.',
+        elapsedTimeProxy: 'Die verstrichene Sitzungsspanne ist ein Proxy und keine gemessene aktive Arbeitszeit.',
+        qualityGuardrailPending: 'Qualitätsevidenz steht noch aus; daher ist keine Aussage zur Wirksamkeit möglich.',
+        payloadTitle: 'Versiegelte Payload-Momentaufnahme',
+        payloadDescription: 'Diese versiegelte Momentaufnahme ist exakt der UTF-8-JSON-Body, den der konfigurierte BYOK-Endpunkt erst nach einem separaten Klick auf Senden erhält.',
+        aggregatesOnly: 'Nur Aggregate',
+        aggregatesWithPersonalization: 'Aggregate + ausdrücklich erlaubter persönlicher Kontext',
+        aggregatesWithPromptSamples: 'Aggregate + ausdrücklich erlaubte Prompt-Beispiele',
+        payloadBytes: '{bytes} UTF-8-Bytes',
+        promptSamplesIncluded: '{count} Prompt-Beispiele enthalten',
+        previewPayload: 'Versiegelte Momentaufnahme anzeigen',
+        noNetworkTransport: 'Die Vorschau sendet nichts. Das Senden erfordert einen separaten Klick.',
+        sendPreparedRequest: 'Genau diese Anfrage senden',
+        sendingPreparedRequest: 'Wird gesendet…',
+        sentPreparedRequest: 'Strukturierter Rat empfangen.',
+        aggregateConsentLabel: 'Aggregierte Nutzungsdaten erlauben',
+        aggregateConsentHelp: 'Enthält nur freigegebene numerische Aggregate und strukturelle Signale — keine Prompts, Pfade, Sitzungs-IDs oder Einzelaufzeichnungen.',
+        promptConsentLabel: 'Auch Prompt-Beispiele und konfigurierten persönlichen Kontext einschließen',
+        promptConsentHelp: 'Optional und standardmäßig deaktiviert. Begrenzter Prompt-Text und der konfigurierte persönliche Kontext werden nur nach dieser separaten ausdrücklichen Einwilligung hinzugefügt.',
+        promptWindowHelp: 'Prompt-Beispiele außerhalb des konfigurierten Evidenzfensters von {days} Tagen werden ausgeschlossen.',
+        feedbackTitle: 'Lokales Feedback',
+        helpful: 'Hilfreich',
+        notHelpful: 'Nicht hilfreich',
+        applied: 'Angewendet',
+        snooze: '7 Tage zurückstellen',
+        resume: 'Wieder anzeigen',
+        snoozedUntil: 'Zurückgestellt bis {date}',
+        feedbackLocalOnly: 'Wird nur auf diesem Gerät gespeichert und nie einer Remote-Payload hinzugefügt.',
+        feedbackSaveFailed: 'Das Feedback konnte lokal nicht gespeichert werden. Es wurde nichts gesendet.',
+        comparisonTitle: 'Ergebnisse vergleichbarer Aufgaben',
+        comparablePairs: '{count} vergleichbare Aufgabenpaare',
+        minimumComparablePairs: 'Mindestens {minimum} vergleichbare Aufgabenpaare sind nötig, bevor eine Schlussfolgerung gezogen wird.',
+        insufficientEvidence: 'Nicht genügend Evidenz für eine Schlussfolgerung.',
+        qualityGuardrailFailed: 'Die Qualitätsleitplanke hielt nicht; deshalb wird keine Wirksamkeit behauptet.',
+        improved: 'Die Verbesserung erreichte den vorab festgelegten Schwellenwert, während die Qualitätsleitplanke hielt.',
+        noDemonstratedImprovement: 'Es wurde keine Verbesserung nachgewiesen; daraus folgen weder Schaden noch Kausalität.',
+        clearLocalData: 'Lokale Empfehlungsdaten löschen',
+        clearLocalDataConfirm: 'Einwilligungen, Feedback, vergleichbare Paare und Vergleichsergebnisse auf diesem Gerät löschen?',
+        strictOutputRejected: 'Die strukturierte Modellausgabe wurde abgelehnt. Es wurde keine Empfehlung erstellt.',
+      },
       totalTokens: "Gesamte Token",
       inputTokens: "Eingabe Token",
       outputTokens: "Ausgabe Token",
@@ -1364,8 +1631,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: "Modell",
       agents: "Agenten",
       agent: "Agent",
-      workflowsThisMonth: "Workflows diesen Monat",
-      workflowCostShare: "Anteil an den Monatskosten",
+      workflowsLast30Days: 'Workflows in den letzten 30 Tagen',
+      workflowLast30DaysCostShare: 'Anteil an den Kosten der letzten 30 Tage',
       workflowCacheHint:
         "Cache-Trefferrate = Cache-Lesevorgänge ÷ alle eingabeseitigen Tokens. Native Claude-Workflows nutzen den Prompt-Cache agentenübergreifend (hohe Rate); ein Anbieter ohne agentenübergreifenden Cache zeigt ~0 % — derselbe Workflow kostet dort unverhältnismäßig mehr.",
       adhocBadge: "Subagenten (ad-hoc)",
@@ -1438,14 +1705,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: "KI-Rat holen",
       adviceCardTitle: "KI-Rat",
       adviceCardDesc:
-        "Sende deine Nutzungsübersicht + eine Auswahl deiner eigenen Prompts an dein Modell und erhalte konkrete Tipps für klarere Anweisungen und weniger Verschwendung.",
+        "Prüfe zuerst die lokalen Belege. Die exakte Anfrage enthält standardmäßig nur Aggregate; Prompt-Beispiele und persönlicher Kontext brauchen eine separate Einwilligung, und erst ein Klick auf Senden überträgt etwas.",
       optimizerTitle: "Nutzungs-Optimierer",
       optimizerDesc:
         "Mach aus einer groben, halbfertigen Anfrage einen sauberen Prompt, den du direkt in Claude Code einfügen kannst — plus empfohlenes Effort / Thinking / Modell für die Aufgabe.",
       optimizerHowto:
-        "Tippe oder füge deinen Entwurf unten ein, aktiviere optionale Feineinstellungen und klicke Optimieren. Nur der eingefügte Text wird an dein Modell gesendet — nie an Claude Code oder dein Terminal.",
+        "Tippe oder füge deinen Entwurf unten ein, wähle optionale Anpassungen und erstelle dann die exakte Anfragevorschau. Erst ein separater Klick auf Senden überträgt etwas; enthalten sein kann nur dein eingefügter Text.",
       optimizerConsent:
-        "Der Nutzungs-Optimierer sendet den eingefügten Text an dein konfiguriertes API-Modell. Nichts geht an Claude Code, nichts wird ins Terminal getippt. Fortfahren?",
+        "Exakte Anfragevorschau erstellen? Dabei wird nichts gesendet; die Übertragung an dein konfiguriertes API-Modell erfordert einen separaten Klick.",
       optimizerEnableBtn: "In Einstellungen aktivieren",
       optimizerPlaceholder: "Groben Prompt zum Optimieren einfügen…",
       optimizerRun: "Optimieren",
@@ -1478,10 +1745,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> Ihren tatsächlichen Nutzungsdaten — es wurde nichts an eine API\n' +
         '> gesendet, um diesen Text zu generieren.\n\n' +
         '### Für echten, personalisierten Rat basierend auf IHRER Nutzung:\n\n' +
-        '1. Einstellungen öffnen (`Ctrl+,` / `Cmd+,`)\n' +
-        '2. Nach **`claudeCodeUsage.advice.apiKey`** suchen\n' +
-        '3. Einen OpenAI-kompatiblen API-Key einfügen — DeepSeek funktioniert\n' +
-        '   sofort ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. **`Claude Code Usage: Show Usage Details`** ausführen\n' +
+        '2. Im Dashboard **Einstellungen → Beratung** öffnen\n' +
+        '3. Einen OpenAI-kompatiblen API-Key einfügen — er bleibt in VS Code SecretStorage\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. **`Claude Code Usage: Get AI Usage Advice`** erneut ausführen',
       costComposition: "Kostenzusammensetzung",
       date: "Datum",
@@ -1511,6 +1778,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: '新功能：Codex Beta 用量與本機優化建議、與安裝版本精確對應的更新說明，並移除已過時的特定模型每週 Opus 選項。',
+      v231: '新功能：正確的 Codex 最近 30 天統計、可識別重置的每週額度估算，以及可匯出本機 SVG／Markdown 的隱私安全綜合活動熱力圖。',
     },
     providers: PROVIDERS['zh-TW'],
     weeklyValue: WEEKLY_VALUE_COPY['zh-TW'],
@@ -1526,7 +1794,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: '設定',
       settingsTab: '設定',
       settingsIntro:
-        '設定現在都在這裡。只有語言、資料目錄與 API 金鑰仍留在 VS Code 設定中(以便同步)。變更會立即生效。',
+        '設定現在都在這裡。語言與資料目錄仍使用 VS Code 設定；API 金鑰存於 VS Code SecretStorage，絕不同步。變更會立即生效。',
+      secretMigrationFailed:
+        '無法將已儲存的建議 API 金鑰移入加密 SecretStorage。擴充套件已在刪除舊值前停止。請修正舊設定並重新載入視窗。',
+      secretMigrationWorkspace:
+        '工作區專用 API 金鑰無法安全遷移至單一全域 SecretStorage。請先複製並從工作區設定移除，重新載入後在「儀表板設定 → 建議」輸入。',
       settingsResetAll: '全部還原為預設',
       settingsGroupGeneral: '一般',
       settingsGroupProviders: '供應商',
@@ -1534,6 +1806,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: '狀態列',
       settingsGroupData: '資料與重新整理',
       settingsGroupAdvice: 'AI 建議與最佳化工具',
+      adviceEffectiveness: {
+        title: 'AI 建議有效性',
+        description: '檢視每項建議如何從本機觀察，經由證據與行動，走到有品質護欄的結果。',
+        candidateNotice: 'v2.3.1 候選功能 · 預設關閉 · 沒有預設或背景 AI 請求。',
+        spineLabel: '建議證據路徑',
+        observation: '觀察',
+        evidence: '證據',
+        recommendation: '建議',
+        action: '行動',
+        result: '結果',
+        source: '來源',
+        limitations: '限制',
+        proxyMetric: '代理指標',
+        longSessionSignal: '觀察到的用量中，有 {share} 來自長工作階段。',
+        largeContextSignal: '觀察到的用量中，有 {share} 發生於大型上下文。',
+        frameworkOverheadSignal: '觀察到的用量中，{share} 是另行估算的框架注入占比；這不評價使用者的寫作品質。',
+        clearBoundaryRecommendation: '對長時間或大型上下文工作採用更清楚的任務邊界。',
+        clearBoundaryAction: '任務改變時開始新的工作階段；只有繼續同一任務時才壓縮上下文。',
+        codexLocalRecommendation: '在下一個可比任務前，先檢視本機 Codex 結構訊號。',
+        noEvidenceAdvice: '此範圍目前沒有以證據為基礎的建議。',
+        codexPreviewUnavailable: '隱私安全的 Codex 彙總 payload 預覽尚未可用。',
+        elapsedTimeProxy: '工作階段首尾跨度是代理指標，不是實測的活躍工作時間。',
+        qualityGuardrailPending: '品質證據仍待補充，因此目前無法判定建議有效性。',
+        payloadTitle: '密封 payload 快照',
+        payloadDescription: '此密封快照就是設定的 BYOK 端點在另行點擊「傳送」後才會收到的確切 UTF-8 JSON body。',
+        aggregatesOnly: '僅彙總資料',
+        aggregatesWithPersonalization: '彙總資料 + 明確允許的個人上下文',
+        aggregatesWithPromptSamples: '彙總資料 + 明確允許的 prompt 樣本',
+        payloadBytes: '{bytes} 個 UTF-8 位元組',
+        promptSamplesIncluded: '包含 {count} 個 prompt 樣本',
+        previewPayload: '預覽密封快照',
+        noNetworkTransport: '預覽不會傳送任何內容；傳送需要另行點擊。',
+        sendPreparedRequest: '傳送這個完全相同的請求',
+        sendingPreparedRequest: '正在傳送…',
+        sentPreparedRequest: '已收到結構化建議。',
+        aggregateConsentLabel: '允許使用彙總用量資料',
+        aggregateConsentHelp: '只包含允許清單內的數值彙總與結構訊號——不含 prompt、路徑、工作階段 ID 或逐筆記錄。',
+        promptConsentLabel: '同時包含 prompt 樣本與設定的個人上下文',
+        promptConsentHelp: '選用且預設關閉。只有在另行明確同意後，才會加入有數量與長度限制的 prompt 文字及設定的個人上下文。',
+        promptWindowHelp: '早於設定之 {days} 天證據視窗的 prompt 樣本不會包含。',
+        feedbackTitle: '本機意見回饋',
+        helpful: '有用',
+        notHelpful: '無用',
+        applied: '已套用',
+        snooze: '暫停 7 天',
+        resume: '再次顯示',
+        snoozedUntil: '暫停至 {date}',
+        feedbackLocalOnly: '只儲存在此裝置，絕不加入遠端 payload。',
+        feedbackSaveFailed: '無法在本機儲存回饋。未傳送任何內容。',
+        comparisonTitle: '可比任務結果',
+        comparablePairs: '{count} 組可比任務',
+        minimumComparablePairs: '至少需要 {minimum} 組可比任務，才能下結論。',
+        insufficientEvidence: '證據不足，無法下結論。',
+        qualityGuardrailFailed: '品質護欄未通過，因此不聲稱建議有效。',
+        improved: '改善達到預先聲明的門檻，且品質護欄維持通過。',
+        noDemonstratedImprovement: '尚未證明有改善；這不代表造成傷害，也不建立因果關係。',
+        clearLocalData: '清除本機建議資料',
+        clearLocalDataConfirm: '要清除此裝置上的建議同意、回饋、可比配對與比較結果嗎？',
+        strictOutputRejected: '結構化模型輸出遭拒絕，因此未建立任何建議。',
+      },
       totalTokens: '總 Token 數',
       inputTokens: '輸入 Token',
       outputTokens: '輸出 Token',
@@ -1602,8 +1934,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: '模型',
       agents: '代理數',
       agent: '代理',
-      workflowsThisMonth: '本月工作流',
-      workflowCostShare: '佔本月成本',
+      workflowsLast30Days: '最近 30 天工作流',
+      workflowLast30DaysCostShare: '佔最近 30 天成本',
       workflowCacheHint:
         '快取命中率 = 快取讀取 ÷ 全部輸入側 token。原生 Claude 工作流可在代理間重用提示快取（命中率高）；不支援跨代理快取的供應商約為 0%——同樣的工作流在那裡的成本會高出許多。',
       adhocBadge: '子代理（臨時）',
@@ -1672,14 +2004,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: '取得 AI 建議',
       adviceCardTitle: 'AI 建議',
       adviceCardDesc:
-        '將你的用量摘要 + 你自己的 prompt 樣本送給模型，取得寫出更清楚指令、減少浪費的具體建議。',
+        '先查看本機證據。精確請求預設只含彙總資料；prompt 樣本與個人上下文需另行同意，而且只有按下「傳送」才會送出。',
       optimizerTitle: '用量優化器',
       optimizerDesc:
         '把粗略、半成形的需求，變成可直接貼進 Claude Code 的乾淨 prompt，並附上這個任務建議的 effort / thinking / 模型。',
       optimizerHowto:
-        '在下方輸入或貼上你的草稿，按需勾選可選的微調項，再按「優化」。只有你貼上的文字會送給模型——不會送給 Claude Code 或終端。',
+        '在下方輸入或貼上草稿，選取需要的調整，再建立精確請求預覽。此步驟不會傳送；只有另按「傳送」才會送出，且只會包含你貼上的文字。',
       optimizerConsent:
-        '用量優化器會把你貼上的文字送給你配置的 API 模型。不會送給 Claude Code，也不會注入終端。要繼續嗎？',
+        '要建立精確請求預覽嗎？此步驟不會傳送；送往你配置的 API 模型仍需另按一次「傳送」。',
       optimizerEnableBtn: '在設定中啟用',
       optimizerPlaceholder: '貼上要優化的粗略 prompt…',
       optimizerRun: '優化',
@@ -1711,10 +2043,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> 它**不是**基於你實際的 Claude Code 用量資料 ——\n' +
         '> 沒有任何資料被送往 API 來產生本內容。\n\n' +
         '### 要取得基於你實際用量的個人化建議:\n\n' +
-        '1. 開啟設定(`Ctrl+,` / `Cmd+,`)\n' +
-        '2. 搜尋 **`claudeCodeUsage.advice.apiKey`**\n' +
-        '3. 貼入 OpenAI-相容 API key —— DeepSeek 開箱即用\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. 執行 **`Claude Code Usage: Show Usage Details`**\n' +
+        '2. 開啟儀表板的 **設定 → 建議** 區段\n' +
+        '3. 貼入 OpenAI 相容 API key —— 金鑰只會存於 VS Code SecretStorage\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. 重新執行 **`Claude Code Usage: Get AI Usage Advice`**',
       costComposition: '成本構成',
       date: '日期',
@@ -1742,6 +2074,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: '新功能：Codex Beta 用量与本地优化建议、与安装版本精确对应的更新说明，并移除已过时的特定模型每周 Opus 选项。',
+      v231: '新功能：准确的 Codex 最近 30 天统计、可识别重置的每周额度估算，以及可导出本地 SVG／Markdown 的隐私安全综合活动热力图。',
     },
     providers: PROVIDERS['zh-CN'],
     weeklyValue: WEEKLY_VALUE_COPY['zh-CN'],
@@ -1757,7 +2090,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: '设置',
       settingsTab: '设置',
       settingsIntro:
-        '设置现在都在这里。只有语言、数据目录和 API key 仍留在 VS Code 设置中(便于同步)。更改即时生效。',
+        '设置现在都在这里。语言和数据目录仍使用 VS Code 设置；API 密钥存入 VS Code SecretStorage，绝不同步。更改即时生效。',
+      secretMigrationFailed:
+        '无法把已保存的建议 API 密钥迁入加密 SecretStorage。插件已在删除旧值前停止。请修正旧设置并重新加载窗口。',
+      secretMigrationWorkspace:
+        '工作区专用 API 密钥无法安全迁移到单一全局 SecretStorage。请先复制并从工作区设置中移除，重新加载后在“仪表板设置 → 建议”中输入。',
       settingsResetAll: '全部恢复默认',
       settingsGroupGeneral: '常规',
       settingsGroupProviders: '供应商',
@@ -1765,6 +2102,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: '状态栏',
       settingsGroupData: '数据与刷新',
       settingsGroupAdvice: 'AI 建议与优化器',
+      adviceEffectiveness: {
+        title: 'AI 建议有效性',
+        description: '查看每条建议如何从本地观察，经由证据与行动，走到有质量护栏的结果。',
+        candidateNotice: 'v2.3.1 候选功能 · 默认关闭 · 不存在默认或后台 AI 请求。',
+        spineLabel: '建议证据路径',
+        observation: '观察',
+        evidence: '证据',
+        recommendation: '建议',
+        action: '行动',
+        result: '结果',
+        source: '来源',
+        limitations: '限制',
+        proxyMetric: '代理指标',
+        longSessionSignal: '观察到的用量中，有 {share} 来自长会话。',
+        largeContextSignal: '观察到的用量中，有 {share} 发生在大型上下文。',
+        frameworkOverheadSignal: '观察到的用量中，{share} 是单独估算的框架注入占比；这不评价用户的写作质量。',
+        clearBoundaryRecommendation: '对长时间或大型上下文工作采用更清晰的任务边界。',
+        clearBoundaryAction: '任务改变时开始新会话；只有继续同一任务时才压缩上下文。',
+        codexLocalRecommendation: '在下一个可比任务前，先查看本地 Codex 结构信号。',
+        noEvidenceAdvice: '此范围目前没有基于证据的建议。',
+        codexPreviewUnavailable: '隐私安全的 Codex 汇总 payload 预览尚不可用。',
+        elapsedTimeProxy: '会话首尾跨度是代理指标，不是实测的活跃工作时间。',
+        qualityGuardrailPending: '质量证据仍待补充，因此目前无法判断建议有效性。',
+        payloadTitle: '密封 payload 快照',
+        payloadDescription: '此密封快照就是配置的 BYOK 端点仅在另行点击“发送”后才会收到的确切 UTF-8 JSON body。',
+        aggregatesOnly: '仅汇总数据',
+        aggregatesWithPersonalization: '汇总数据 + 明确允许的个人上下文',
+        aggregatesWithPromptSamples: '汇总数据 + 明确允许的 prompt 样本',
+        payloadBytes: '{bytes} 个 UTF-8 字节',
+        promptSamplesIncluded: '包含 {count} 个 prompt 样本',
+        previewPayload: '预览密封快照',
+        noNetworkTransport: '预览不会发送任何内容；发送需要另行点击。',
+        sendPreparedRequest: '发送这份完全相同的请求',
+        sendingPreparedRequest: '正在发送…',
+        sentPreparedRequest: '已收到结构化建议。',
+        aggregateConsentLabel: '允许使用汇总用量数据',
+        aggregateConsentHelp: '只包含允许列表内的数值汇总与结构信号——不含 prompt、路径、会话 ID 或逐条记录。',
+        promptConsentLabel: '同时包含 prompt 样本与配置的个人上下文',
+        promptConsentHelp: '可选且默认关闭。只有另行明确同意后，才会加入有数量和长度限制的 prompt 文本及配置的个人上下文。',
+        promptWindowHelp: '早于所配置 {days} 天证据窗口的 prompt 样本不会包含。',
+        feedbackTitle: '本地反馈',
+        helpful: '有用',
+        notHelpful: '无用',
+        applied: '已应用',
+        snooze: '暂停 7 天',
+        resume: '再次显示',
+        snoozedUntil: '暂停至 {date}',
+        feedbackLocalOnly: '只存储在此设备上，绝不加入远程 payload。',
+        feedbackSaveFailed: '无法在本地保存反馈。未发送任何内容。',
+        comparisonTitle: '可比任务结果',
+        comparablePairs: '{count} 组可比任务',
+        minimumComparablePairs: '至少需要 {minimum} 组可比任务，才能下结论。',
+        insufficientEvidence: '证据不足，无法下结论。',
+        qualityGuardrailFailed: '质量护栏未通过，因此不声称建议有效。',
+        improved: '改善达到预先声明的门槛，且质量护栏保持通过。',
+        noDemonstratedImprovement: '尚未证明有改善；这不代表造成伤害，也不建立因果关系。',
+        clearLocalData: '清除本地建议数据',
+        clearLocalDataConfirm: '要清除此设备上保存的建议同意、反馈、可比配对和比较结果吗？',
+        strictOutputRejected: '结构化模型输出被拒绝，因此未创建任何建议。',
+      },
       totalTokens: '总 Token 数',
       inputTokens: '输入 Token',
       outputTokens: '输出 Token',
@@ -1833,8 +2230,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: '模型',
       agents: '代理数',
       agent: '代理',
-      workflowsThisMonth: '本月工作流',
-      workflowCostShare: '占本月成本',
+      workflowsLast30Days: '最近 30 天工作流',
+      workflowLast30DaysCostShare: '占最近 30 天成本',
       workflowCacheHint:
         '缓存命中率 = 缓存读取 ÷ 全部输入侧 token。原生 Claude 工作流可在代理间复用提示缓存（命中率高）；不支持跨代理缓存的供应商约为 0%——同样的工作流在那里的成本会高出许多。',
       adhocBadge: '子代理（临时）',
@@ -1903,14 +2300,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: '获取 AI 建议',
       adviceCardTitle: 'AI 建议',
       adviceCardDesc:
-        '将你的用量摘要 + 你自己的 prompt 样本送给模型，获得写出更清晰指令、减少浪费的具体建议。',
+        '先查看本地证据。精确请求默认只含汇总数据；prompt 样本与个人上下文需另行同意，而且只有点击“发送”才会发出。',
       optimizerTitle: '用量优化器',
       optimizerDesc:
         '把粗略、没成形的需求，变成可以直接粘进 Claude Code 的干净 prompt，并附上这个任务建议的 effort / thinking / 模型。',
       optimizerHowto:
-        '在下方输入或粘贴你的草稿，按需勾选下面的可选微调项，再点「优化」。只有你粘贴的文字会发给模型——不会发给 Claude Code，也不会注入终端。',
+        '在下方输入或粘贴草稿，选择需要的调整，再生成精确请求预览。此步骤不会发送；只有另点“发送”才会发出，且只会包含你粘贴的文字。',
       optimizerConsent:
-        '用量优化器会把你粘贴的文字发送给你配置的 API 模型。不会发送给 Claude Code，也不会注入终端。要继续吗？',
+        '要生成精确请求预览吗？此步骤不会发送；发送到你配置的 API 模型仍需另点一次“发送”。',
       optimizerEnableBtn: '在设置中启用',
       optimizerPlaceholder: '粘贴要优化的粗略 prompt…',
       optimizerRun: '优化',
@@ -1942,10 +2339,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> 它**不是**基于你实际的 Claude Code 用量数据 ——\n' +
         '> 没有任何数据被发往 API 来生成本内容。\n\n' +
         '### 要获得基于你实际用量的个性化建议:\n\n' +
-        '1. 打开设置(`Ctrl+,` / `Cmd+,`)\n' +
-        '2. 搜索 **`claudeCodeUsage.advice.apiKey`**\n' +
-        '3. 填入 OpenAI-兼容 API key —— DeepSeek 开箱即用\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. 运行 **`Claude Code Usage: Show Usage Details`**\n' +
+        '2. 打开仪表板的 **设置 → 建议** 区域\n' +
+        '3. 填入 OpenAI 兼容 API key —— 密钥只存入 VS Code SecretStorage\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. 重新运行 **`Claude Code Usage: Get AI Usage Advice`**',
       costComposition: '成本构成',
       date: '日期',
@@ -1973,6 +2370,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: '新機能：Codex Beta の使用量とローカル最適化ガイド、完全なバージョンに対応するリリース通知、および古いモデル別の週間 Opus オプションの削除。',
+      v231: '新機能：正確な Codex の直近 30 日集計、リセットを考慮した週間枠の推定、ローカル SVG／Markdown 共有に対応したプライバシー保護の統合アクティビティヒートマップ。',
     },
     providers: PROVIDERS.ja,
     weeklyValue: WEEKLY_VALUE_COPY.ja,
@@ -1988,7 +2386,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: '設定',
       settingsTab: '設定',
       settingsIntro:
-        '設定はここにまとまりました。言語・データディレクトリ・API キーのみ VS Code 設定に残ります(同期のため)。変更は即時反映されます。',
+        '設定はここにまとまりました。言語とデータディレクトリは VS Code 設定を使い、API キーは同期されない VS Code SecretStorage に保存されます。変更は即時反映されます。',
+      secretMigrationFailed:
+        '保存済みのアドバイス API キーを暗号化された SecretStorage に移動できませんでした。旧値を削除する前に拡張機能を停止しました。旧設定を修正してウィンドウを再読み込みしてください。',
+      secretMigrationWorkspace:
+        'ワークスペース固有の API キーを単一のグローバル SecretStorage に安全に移行できません。キーをコピーしてワークスペース設定から削除し、再読み込み後に「ダッシュボード設定 → アドバイス」で入力してください。',
       settingsResetAll: 'すべて既定値に戻す',
       settingsGroupGeneral: '一般',
       settingsGroupProviders: 'プロバイダー',
@@ -1996,6 +2398,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: 'ステータスバー',
       settingsGroupData: 'データと更新',
       settingsGroupAdvice: 'AI アドバイス & オプティマイザー',
+      adviceEffectiveness: {
+        title: 'AI アドバイスの有効性',
+        description: '各提案がローカルの観察から根拠と行動を経て、品質ガードレール付きの結果に至る流れを確認します。',
+        candidateNotice: 'v2.3.1 候補機能 · デフォルトは無効 · 既定またはバックグラウンドの AI リクエストはありません。',
+        spineLabel: 'アドバイスの根拠経路',
+        observation: '観察',
+        evidence: '根拠',
+        recommendation: 'アドバイス',
+        action: '行動',
+        result: '結果',
+        source: '情報源',
+        limitations: '制約',
+        proxyMetric: '代理指標',
+        longSessionSignal: '観測された使用量のうち {share} は長時間セッションから生じました。',
+        largeContextSignal: '観測された使用量のうち {share} は大きなコンテキストで生じました。',
+        frameworkOverheadSignal: '観測された使用量のうち {share} は、別途推定したフレームワーク注入の割合です。ユーザーの文章品質を評価するものではありません。',
+        clearBoundaryRecommendation: '長時間または大きなコンテキストの作業では、タスク境界をより明確にします。',
+        clearBoundaryAction: 'タスクが変わったら新しいセッションを開始し、同じタスクを続ける場合にだけコンテキストを圧縮します。',
+        codexLocalRecommendation: '次の比較可能なタスクの前に、ローカルの Codex 構造シグナルを確認します。',
+        noEvidenceAdvice: 'この範囲には、根拠に基づくアドバイスがありません。',
+        codexPreviewUnavailable: 'プライバシーを保護した Codex 集計 payload のプレビューは、まだ利用できません。',
+        elapsedTimeProxy: 'セッションの経過範囲は代理指標であり、実測した作業時間ではありません。',
+        qualityGuardrailPending: '品質の根拠が未確定のため、有効性について結論を出せません。',
+        payloadTitle: '封印済み payload スナップショット',
+        payloadDescription: 'この封印済みスナップショットは、別の送信クリック後にだけ設定済み BYOK エンドポイントが受け取る UTF-8 JSON body と完全に同一です。',
+        aggregatesOnly: '集計データのみ',
+        aggregatesWithPersonalization: '集計データ + 明示的に許可した個人コンテキスト',
+        aggregatesWithPromptSamples: '集計データ + 明示的に許可したプロンプト例',
+        payloadBytes: '{bytes} UTF-8 バイト',
+        promptSamplesIncluded: '{count} 件のプロンプト例を含む',
+        previewPayload: '封印済みスナップショットをプレビュー',
+        noNetworkTransport: 'プレビューでは何も送信されません。送信には別のクリックが必要です。',
+        sendPreparedRequest: 'この同一リクエストを送信',
+        sendingPreparedRequest: '送信中…',
+        sentPreparedRequest: '構造化された助言を受信しました。',
+        aggregateConsentLabel: '集計使用データを許可する',
+        aggregateConsentHelp: '許可リスト内の数値集計と構造シグナルだけを含み、プロンプト、パス、セッション ID、個別レコードは含みません。',
+        promptConsentLabel: 'プロンプト例と設定済み個人コンテキストも含める',
+        promptConsentHelp: '任意で、デフォルトは無効です。この独立した明示的同意の後にだけ、件数と長さを制限したプロンプト本文と設定済み個人コンテキストを追加します。',
+        promptWindowHelp: '設定した {days} 日間の根拠期間より古いプロンプト例は除外します。',
+        feedbackTitle: 'ローカルフィードバック',
+        helpful: '役に立った',
+        notHelpful: '役に立たなかった',
+        applied: '適用済み',
+        snooze: '7日間保留',
+        resume: '再表示',
+        snoozedUntil: '{date} まで保留',
+        feedbackLocalOnly: 'この端末だけに保存され、リモート payload には追加されません。',
+        feedbackSaveFailed: 'フィードバックをローカルに保存できませんでした。何も送信されていません。',
+        comparisonTitle: '比較可能なタスクの結果',
+        comparablePairs: '{count} 組の比較可能なタスク',
+        minimumComparablePairs: '結論を出す前に、少なくとも {minimum} 組の比較可能なタスクが必要です。',
+        insufficientEvidence: '結論を出すには根拠が不足しています。',
+        qualityGuardrailFailed: '品質ガードレールを満たさなかったため、有効性を主張しません。',
+        improved: '品質ガードレールを保ったまま、事前に定めた改善基準に達しました。',
+        noDemonstratedImprovement: '改善は実証されていません。これは害や因果関係を示すものではありません。',
+        clearLocalData: 'ローカルのアドバイスデータを消去',
+        clearLocalDataConfirm: 'この端末に保存された同意、フィードバック、比較可能ペア、比較結果を消去しますか？',
+        strictOutputRejected: '構造化されたモデル出力を拒否しました。アドバイスは作成されていません。',
+      },
       totalTokens: '総トークン数',
       inputTokens: '入力トークン',
       outputTokens: '出力トークン',
@@ -2064,8 +2526,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: 'モデル',
       agents: 'エージェント数',
       agent: 'エージェント',
-      workflowsThisMonth: '今月のワークフロー',
-      workflowCostShare: '今月のコストに占める割合',
+      workflowsLast30Days: '過去30日間のワークフロー',
+      workflowLast30DaysCostShare: '過去30日間のコストに占める割合',
       workflowCacheHint:
         'キャッシュヒット率 = キャッシュ読取 ÷ 入力側トークン全体。ネイティブ Claude のワークフローはエージェント間でプロンプトキャッシュを再利用します（高い率）。エージェント間キャッシュのないプロバイダーでは約 0% となり、同じワークフローのコストが大幅に高くなります。',
       adhocBadge: 'サブエージェント（アドホック）',
@@ -2138,14 +2600,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: 'AI アドバイスを取得',
       adviceCardTitle: 'AI アドバイス',
       adviceCardDesc:
-        '使用量サマリー + あなた自身のプロンプトのサンプルをモデルに送り、より明確な指示と無駄削減の具体的なヒントを得ます。',
+        'まずローカルの根拠を確認します。正確なリクエストは既定で集計のみです。プロンプト例と個人コンテキストには別の同意が必要で、「送信」を押すまで何も送られません。',
       optimizerTitle: '使用量オプティマイザー',
       optimizerDesc:
         '雑で半端な依頼を、Claude Code にそのまま貼り付けられる整ったプロンプトに変換し、そのタスクに推奨の effort / thinking / モデルも返します。',
       optimizerHowto:
-        '下に下書きを入力または貼り付け、必要に応じて任意の調整オプションを選び「最適化」を押します。送信されるのは貼り付けたテキストのみ——Claude Code やターミナルには送られません。',
+        '下に下書きを入力または貼り付け、必要な調整を選んで正確なリクエストをプレビューします。この段階では送信されません。別途「送信」を押した場合のみ、貼り付けたテキストが含まれます。',
       optimizerConsent:
-        '使用量オプティマイザーは貼り付けたテキストを設定した API モデルに送信します。Claude Code には送られず、ターミナルにも入力されません。続行しますか？',
+        '正確なリクエストをプレビューしますか？この操作では送信されません。設定した API モデルへの送信には別のクリックが必要です。',
       optimizerEnableBtn: '設定で有効化',
       optimizerPlaceholder: '最適化する雑なプロンプトを貼り付け…',
       optimizerRun: '最適化',
@@ -2178,10 +2640,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> に基づくものでは**ありません** —— この内容を生成するために\n' +
         '> API にデータは送信されていません。\n\n' +
         '### あなたの実際の使用量に基づくパーソナライズされたアドバイスを取得するには:\n\n' +
-        '1. 設定を開く(`Ctrl+,` / `Cmd+,`)\n' +
-        '2. **`claudeCodeUsage.advice.apiKey`** を検索\n' +
-        '3. OpenAI 互換 API キーを貼り付け —— DeepSeek はすぐに使えます\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. **`Claude Code Usage: Show Usage Details`** を実行\n' +
+        '2. ダッシュボードの **設定 → アドバイス** を開く\n' +
+        '3. OpenAI 互換 API キーを貼り付け —— VS Code SecretStorage のみに保存されます\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. **`Claude Code Usage: Get AI Usage Advice`** を再実行',
       costComposition: 'コスト構成',
       date: '日付',
@@ -2209,6 +2671,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: '새 기능: Codex Beta 사용량과 로컬 최적화 안내, 설치된 전체 버전에 맞는 릴리스 알림, 그리고 오래된 모델별 주간 Opus 옵션 제거.',
+      v231: '새 기능: 정확한 Codex 최근 30일 통계, 재설정을 인식하는 주간 한도 추정, 로컬 SVG/Markdown 공유를 지원하는 개인정보 보호 통합 활동 히트맵.',
     },
     providers: PROVIDERS.ko,
     weeklyValue: WEEKLY_VALUE_COPY.ko,
@@ -2224,7 +2687,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: '설정',
       settingsTab: '설정',
       settingsIntro:
-        '설정이 이제 여기로 모였습니다. 언어, 데이터 디렉터리, API 키만 VS Code 설정에 남습니다(동기화를 위해). 변경은 즉시 적용됩니다.',
+        '설정이 이제 여기로 모였습니다. 언어와 데이터 디렉터리는 VS Code 설정을 사용하고, API 키는 동기화되지 않는 VS Code SecretStorage에 저장됩니다. 변경은 즉시 적용됩니다.',
+      secretMigrationFailed:
+        '저장된 조언 API 키를 암호화된 SecretStorage로 옮기지 못했습니다. 이전 값을 삭제하기 전에 확장이 중지되었습니다. 기존 설정을 수정하고 창을 다시 로드하세요.',
+      secretMigrationWorkspace:
+        '작업 영역별 API 키는 하나의 전역 SecretStorage 항목으로 안전하게 이전할 수 없습니다. 키를 복사한 뒤 작업 영역 설정에서 제거하고, 다시 로드한 후 대시보드 설정 → 조언에 입력하세요.',
       settingsResetAll: '모두 기본값으로',
       settingsGroupGeneral: '일반',
       settingsGroupProviders: '공급자',
@@ -2232,6 +2699,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: '상태 표시줄',
       settingsGroupData: '데이터 및 새로고침',
       settingsGroupAdvice: 'AI 조언 & 옵티마이저',
+      adviceEffectiveness: {
+        title: 'AI 조언 효과성',
+        description: '각 제안이 로컬 관찰에서 근거와 행동을 거쳐 품질 가드레일이 있는 결과로 이어지는 과정을 확인합니다.',
+        candidateNotice: 'v2.3.1 후보 기능 · 기본적으로 꺼짐 · 기본 또는 백그라운드 AI 요청 없음.',
+        spineLabel: '조언 근거 경로',
+        observation: '관찰',
+        evidence: '근거',
+        recommendation: '조언',
+        action: '행동',
+        result: '결과',
+        source: '출처',
+        limitations: '제한 사항',
+        proxyMetric: '프록시 지표',
+        longSessionSignal: '관찰된 사용량 중 {share}가 긴 세션에서 발생했습니다.',
+        largeContextSignal: '관찰된 사용량 중 {share}가 큰 컨텍스트에서 발생했습니다.',
+        frameworkOverheadSignal: '관찰된 사용량 중 {share}는 별도로 추정한 프레임워크 주입 비중이며, 사용자의 글쓰기 품질을 평가하지 않습니다.',
+        clearBoundaryRecommendation: '오래 걸리거나 컨텍스트가 큰 작업에는 더 명확한 작업 경계를 사용하세요.',
+        clearBoundaryAction: '작업이 바뀌면 새 세션을 시작하고, 같은 작업을 계속할 때만 컨텍스트를 압축하세요.',
+        codexLocalRecommendation: '다음 비교 가능한 작업 전에 로컬 Codex 구조 신호를 검토하세요.',
+        noEvidenceAdvice: '이 범위에는 근거 기반 조언이 없습니다.',
+        codexPreviewUnavailable: '개인정보를 보호하는 Codex 집계 payload 미리보기는 아직 사용할 수 없습니다.',
+        elapsedTimeProxy: '세션의 시작과 끝 사이 시간은 프록시이며, 실제로 측정한 활성 작업 시간이 아닙니다.',
+        qualityGuardrailPending: '품질 근거가 아직 준비되지 않아 효과성 결론을 내릴 수 없습니다.',
+        payloadTitle: '봉인된 payload 스냅샷',
+        payloadDescription: '이 봉인된 스냅샷은 별도의 보내기 클릭 후에만 설정된 BYOK 엔드포인트가 받는 UTF-8 JSON body와 정확히 같습니다.',
+        aggregatesOnly: '집계 데이터만',
+        aggregatesWithPersonalization: '집계 데이터 + 명시적으로 허용한 개인 컨텍스트',
+        aggregatesWithPromptSamples: '집계 데이터 + 명시적으로 허용한 프롬프트 샘플',
+        payloadBytes: '{bytes} UTF-8바이트',
+        promptSamplesIncluded: '프롬프트 샘플 {count}개 포함',
+        previewPayload: '봉인된 스냅샷 미리보기',
+        noNetworkTransport: '미리보기는 아무것도 보내지 않습니다. 전송하려면 별도로 클릭해야 합니다.',
+        sendPreparedRequest: '이 동일한 요청 보내기',
+        sendingPreparedRequest: '전송 중…',
+        sentPreparedRequest: '구조화된 조언을 받았습니다.',
+        aggregateConsentLabel: '집계 사용량 데이터 허용',
+        aggregateConsentHelp: '허용 목록의 수치 집계와 구조 신호만 포함하며 프롬프트, 경로, 세션 ID, 개별 레코드는 포함하지 않습니다.',
+        promptConsentLabel: '프롬프트 샘플과 설정된 개인 컨텍스트도 포함',
+        promptConsentHelp: '선택 사항이며 기본적으로 꺼져 있습니다. 이 별도의 명시적 동의 후에만 제한된 프롬프트 텍스트와 설정된 개인 컨텍스트를 추가합니다.',
+        promptWindowHelp: '설정한 {days}일 근거 기간보다 오래된 프롬프트 샘플은 제외합니다.',
+        feedbackTitle: '로컬 피드백',
+        helpful: '유용함',
+        notHelpful: '유용하지 않음',
+        applied: '적용함',
+        snooze: '7일간 숨기기',
+        resume: '다시 표시',
+        snoozedUntil: '{date}까지 숨김',
+        feedbackLocalOnly: '이 기기에만 저장되며 원격 payload에는 절대 추가되지 않습니다.',
+        feedbackSaveFailed: '피드백을 로컬에 저장하지 못했습니다. 아무것도 전송되지 않았습니다.',
+        comparisonTitle: '비교 가능한 작업 결과',
+        comparablePairs: '비교 가능한 작업 쌍 {count}개',
+        minimumComparablePairs: '결론을 내리기 전에 비교 가능한 작업 쌍이 최소 {minimum}개 필요합니다.',
+        insufficientEvidence: '결론을 내리기에 근거가 부족합니다.',
+        qualityGuardrailFailed: '품질 가드레일을 충족하지 못했으므로 효과성을 주장하지 않습니다.',
+        improved: '품질 가드레일을 유지하면서 사전에 정한 개선 기준을 충족했습니다.',
+        noDemonstratedImprovement: '개선이 입증되지 않았습니다. 이는 피해나 인과관계를 뜻하지 않습니다.',
+        clearLocalData: '로컬 조언 데이터 지우기',
+        clearLocalDataConfirm: '이 기기에 저장된 조언 동의, 피드백, 비교 쌍 및 비교 결과를 지우시겠습니까?',
+        strictOutputRejected: '구조화된 모델 출력을 거부했습니다. 조언이 생성되지 않았습니다.',
+      },
       totalTokens: '총 토큰 수',
       inputTokens: '입력 토큰',
       outputTokens: '출력 토큰',
@@ -2300,8 +2827,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: '모델',
       agents: '에이전트 수',
       agent: '에이전트',
-      workflowsThisMonth: '이번 달 워크플로',
-      workflowCostShare: '이번 달 비용 중 비율',
+      workflowsLast30Days: '최근 30일 워크플로',
+      workflowLast30DaysCostShare: '최근 30일 비용 중 비율',
       workflowCacheHint:
         '캐시 적중률 = 캐시 읽기 ÷ 전체 입력측 토큰. 네이티브 Claude 워크플로는 에이전트 간 프롬프트 캐시를 재사용합니다(높은 적중률). 에이전트 간 캐시가 없는 공급자는 약 0%로, 같은 워크플로 비용이 훨씬 더 많이 듭니다.',
       adhocBadge: '서브에이전트(애드혹)',
@@ -2374,14 +2901,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: 'AI 조언 받기',
       adviceCardTitle: 'AI 조언',
       adviceCardDesc:
-        '사용량 요약 + 본인 프롬프트 샘플을 모델에 보내 더 명확한 지시와 낭비 줄이기에 대한 구체적 팁을 받습니다.',
+        '먼저 로컬 근거를 확인합니다. 정확한 요청은 기본적으로 집계만 포함하며, 프롬프트 샘플과 개인 컨텍스트는 별도 동의가 필요하고 「전송」을 누르기 전에는 아무것도 보내지 않습니다.',
       optimizerTitle: '사용량 옵티마이저',
       optimizerDesc:
         '대략적이고 정리되지 않은 요청을 Claude Code에 바로 붙여넣을 수 있는 깔끔한 프롬프트로 바꾸고, 그 작업에 추천하는 effort / thinking / 모델도 함께 제공합니다.',
       optimizerHowto:
-        '아래에 초안을 입력하거나 붙여넣고, 필요하면 선택 옵션을 고른 뒤 「최적화」를 누르세요. 붙여넣은 텍스트만 모델로 전송됩니다 — Claude Code나 터미널로는 가지 않습니다.',
+        '아래에 초안을 입력하거나 붙여넣고 필요한 옵션을 고른 뒤 정확한 요청을 미리 봅니다. 이 단계에서는 전송되지 않으며, 별도로 「전송」을 눌렀을 때만 붙여넣은 텍스트가 포함됩니다.',
       optimizerConsent:
-        '사용량 옵티마이저는 붙여넣은 텍스트를 설정한 API 모델로 보냅니다. Claude Code로는 전송되지 않고 터미널에도 입력되지 않습니다. 계속할까요?',
+        '정확한 요청을 미리 볼까요? 이 단계에서는 아무것도 보내지 않으며, 설정한 API 모델로 보내려면 별도의 클릭이 필요합니다.',
       optimizerEnableBtn: '설정에서 사용',
       optimizerPlaceholder: '최적화할 대략적인 프롬프트 붙여넣기…',
       optimizerRun: '최적화',
@@ -2414,10 +2941,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> 기반하지 **않으며**, 이 내용을 생성하기 위해 API에 데이터가\n' +
         '> 전송된 적이 없습니다.\n\n' +
         '### 실제 사용량 기반의 맞춤형 조언을 받으려면:\n\n' +
-        '1. 설정 열기 (`Ctrl+,` / `Cmd+,`)\n' +
-        '2. **`claudeCodeUsage.advice.apiKey`** 검색\n' +
-        '3. OpenAI 호환 API 키 붙여넣기 — DeepSeek 즉시 사용 가능\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. **`Claude Code Usage: Show Usage Details`** 실행\n' +
+        '2. 대시보드의 **설정 → 조언** 섹션 열기\n' +
+        '3. OpenAI 호환 API 키 붙여넣기 — VS Code SecretStorage에만 저장됩니다\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. **`Claude Code Usage: Get AI Usage Advice`** 다시 실행',
       costComposition: '비용 구성',
       date: '날짜',
@@ -2445,6 +2972,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: 'Novidades: uso do Codex Beta e orientações locais de otimização, avisos da versão exata instalada e remoção da opção semanal obsoleta do Opus por modelo.',
+      v231: 'Novidades: totais corretos dos últimos 30 dias do Codex, estimativas semanais cientes de redefinições e um mapa de calor combinado e privado com exportação local em SVG e Markdown.',
     },
     providers: PROVIDERS['pt-BR'],
     weeklyValue: WEEKLY_VALUE_COPY['pt-BR'],
@@ -2460,7 +2988,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: 'Configurações',
       settingsTab: 'Configurações',
       settingsIntro:
-        'As configurações agora ficam aqui. Apenas idioma, diretório de dados e chave de API permanecem nas Configurações do VS Code (para sincronizar). As alterações são aplicadas imediatamente.',
+        'As configurações agora ficam aqui. Idioma e diretórios de dados continuam nas Configurações do VS Code; chaves de API ficam no VS Code SecretStorage e nunca são sincronizadas. As alterações são aplicadas imediatamente.',
+      secretMigrationFailed:
+        'Não foi possível mover a chave de API de conselho salva para o SecretStorage criptografado. A extensão parou antes de excluir o valor antigo. Corrija a configuração legada e recarregue a janela.',
+      secretMigrationWorkspace:
+        'Uma chave de API específica do espaço de trabalho não pode ser migrada com segurança para uma única entrada global do SecretStorage. Copie-a, remova-a das configurações do espaço de trabalho, recarregue e informe-a em Configurações do painel → Conselho.',
       settingsResetAll: 'Restaurar tudo para os padrões',
       settingsGroupGeneral: 'Geral',
       settingsGroupProviders: 'Provedores',
@@ -2468,6 +3000,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: 'Barra de status',
       settingsGroupData: 'Dados e atualização',
       settingsGroupAdvice: 'Conselho de IA e Optimizer',
+      adviceEffectiveness: {
+        title: 'Eficácia dos conselhos de IA',
+        description: 'Revise como cada sugestão passa de uma observação local para evidências, uma ação e um resultado com proteção de qualidade.',
+        candidateNotice: 'Candidato v2.3.1 · desativado por padrão · sem solicitações de IA padrão ou em segundo plano.',
+        spineLabel: 'Trilha de evidências do conselho',
+        observation: 'Observação',
+        evidence: 'Evidência',
+        recommendation: 'Conselho',
+        action: 'Ação',
+        result: 'Resultado',
+        source: 'Fonte',
+        limitations: 'Limitações',
+        proxyMetric: 'Métrica proxy',
+        longSessionSignal: '{share} do uso observado veio de sessões longas.',
+        largeContextSignal: '{share} do uso observado ocorreu com contextos grandes.',
+        frameworkOverheadSignal: '{share} do uso observado corresponde à parcela estimada separadamente de injeção do framework; isso não avalia a qualidade da escrita do usuário.',
+        clearBoundaryRecommendation: 'Use limites de tarefa mais claros em trabalhos longos ou com contexto grande.',
+        clearBoundaryAction: 'Inicie uma nova sessão quando a tarefa mudar; compacte apenas ao continuar a mesma tarefa.',
+        codexLocalRecommendation: 'Revise o sinal estrutural local do Codex antes da próxima tarefa comparável.',
+        noEvidenceAdvice: 'Não há conselho baseado em evidências disponível para este escopo.',
+        codexPreviewUnavailable: 'Uma prévia de payload agregado do Codex que preserve a privacidade ainda não está disponível.',
+        elapsedTimeProxy: 'O intervalo decorrido da sessão é um proxy, não tempo de trabalho ativo medido.',
+        qualityGuardrailPending: 'As evidências de qualidade estão pendentes; portanto, ainda não há conclusão sobre eficácia.',
+        payloadTitle: 'Snapshot de payload selado',
+        payloadDescription: 'Este snapshot selado é exatamente o body JSON em UTF-8 que o endpoint BYOK configurado recebe somente após um clique separado em Enviar.',
+        aggregatesOnly: 'Somente agregados',
+        aggregatesWithPersonalization: 'Agregados + contexto pessoal permitido explicitamente',
+        aggregatesWithPromptSamples: 'Agregados + amostras de prompt permitidas explicitamente',
+        payloadBytes: '{bytes} bytes UTF-8',
+        promptSamplesIncluded: '{count} amostras de prompt incluídas',
+        previewPayload: 'Visualizar snapshot selado',
+        noNetworkTransport: 'A prévia não envia nada. O envio exige um clique separado.',
+        sendPreparedRequest: 'Enviar esta solicitação exata',
+        sendingPreparedRequest: 'Enviando…',
+        sentPreparedRequest: 'Conselho estruturado recebido.',
+        aggregateConsentLabel: 'Permitir dados agregados de uso',
+        aggregateConsentHelp: 'Inclui somente agregados numéricos e sinais estruturais da lista permitida — sem prompts, caminhos, IDs de sessão ou registros individuais.',
+        promptConsentLabel: 'Incluir amostras de prompt e contexto pessoal configurado',
+        promptConsentHelp: 'Opcional e desativado por padrão. Texto de prompt limitado e contexto pessoal configurado só são adicionados após este consentimento explícito separado.',
+        promptWindowHelp: 'Amostras de prompt anteriores à janela de evidências configurada de {days} dias são excluídas.',
+        feedbackTitle: 'Feedback local',
+        helpful: 'Útil',
+        notHelpful: 'Não útil',
+        applied: 'Aplicado',
+        snooze: 'Adiar por 7 dias',
+        resume: 'Mostrar novamente',
+        snoozedUntil: 'Adiado até {date}',
+        feedbackLocalOnly: 'Armazenado somente neste dispositivo e nunca adicionado a um payload remoto.',
+        feedbackSaveFailed: 'Não foi possível salvar o feedback localmente. Nada foi enviado.',
+        comparisonTitle: 'Resultados de tarefas comparáveis',
+        comparablePairs: '{count} pares de tarefas comparáveis',
+        minimumComparablePairs: 'São necessários pelo menos {minimum} pares de tarefas comparáveis antes de chegar a uma conclusão.',
+        insufficientEvidence: 'Não há evidências suficientes para chegar a uma conclusão.',
+        qualityGuardrailFailed: 'A proteção de qualidade não foi mantida, portanto nenhuma eficácia é afirmada.',
+        improved: 'A melhoria atingiu o limite pré-declarado enquanto a proteção de qualidade foi mantida.',
+        noDemonstratedImprovement: 'Nenhuma melhoria foi demonstrada; isso não estabelece dano nem causalidade.',
+        clearLocalData: 'Limpar dados locais de conselho',
+        clearLocalDataConfirm: 'Limpar consentimentos, feedback, pares comparáveis e resultados de comparação armazenados neste dispositivo?',
+        strictOutputRejected: 'A saída estruturada do modelo foi rejeitada. Nenhum conselho foi criado.',
+      },
       totalTokens: 'Total de tokens',
       inputTokens: 'Tokens de entrada',
       outputTokens: 'Tokens de saída',
@@ -2536,8 +3128,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: 'Modelo',
       agents: 'Agentes',
       agent: 'Agente',
-      workflowsThisMonth: 'Workflows neste mês',
-      workflowCostShare: 'do custo deste mês',
+      workflowsLast30Days: 'Workflows nos últimos 30 dias',
+      workflowLast30DaysCostShare: 'dos custos dos últimos 30 dias',
       workflowCacheHint:
         'Taxa de acerto do cache = leituras de cache ÷ todos os tokens do lado da entrada. Workflows nativos do Claude reaproveitam o cache de prompt entre agentes (taxa alta); um provedor sem cache entre agentes mostra ~0% — o mesmo workflow custa desproporcionalmente mais nele.',
       adhocBadge: 'subagentes (ad-hoc)',
@@ -2610,14 +3202,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: 'Obter conselho de IA',
       adviceCardTitle: 'Conselho de IA',
       adviceCardDesc:
-        'Envie o resumo do seu uso + uma amostra dos seus próprios prompts ao seu modelo e receba dicas concretas para escrever instruções mais claras e reduzir desperdício.',
+        'Revise primeiro as evidências locais. A solicitação exata usa apenas agregados por padrão; amostras de prompts e contexto pessoal exigem consentimento separado, e nada é enviado até você clicar em Enviar.',
       optimizerTitle: 'Otimizador de uso',
       optimizerDesc:
         'Transforme um pedido rascunhado e malformado em um prompt limpo para colar direto no Claude Code — além de um esforço / raciocínio / modelo sugeridos para a tarefa.',
       optimizerHowto:
-        'Digite ou cole seu rascunho abaixo, marque quaisquer ajustes opcionais e clique em Otimizar. Apenas o texto que você cola é enviado ao seu modelo — nunca ao Claude Code nem ao seu terminal.',
+        'Digite ou cole seu rascunho abaixo, escolha os ajustes opcionais e gere a visualização da solicitação exata. Nada é enviado até um clique separado em Enviar; somente o texto colado pode ser incluído.',
       optimizerConsent:
-        'O Otimizador de Uso envia o texto que você cola ao modelo de API configurado. Nada é enviado ao Claude Code e nada é digitado em um terminal. Continuar?',
+        'Gerar a visualização da solicitação exata? Isso não envia nada; o envio ao modelo de API configurado exige outro clique.',
       optimizerEnableBtn: 'Ativar nas configurações',
       optimizerPlaceholder: 'Cole um prompt rascunhado para otimizar…',
       optimizerRun: 'Otimizar',
@@ -2649,10 +3241,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> que o recurso produz. Ele **não** é baseado nos seus dados reais de uso\n' +
         '> do Claude Code — nada foi enviado a nenhuma API para gerar isso.\n\n' +
         '### Para obter um conselho real e personalizado com base no SEU uso:\n\n' +
-        '1. Abra as Configurações (`Ctrl+,` / `Cmd+,`)\n' +
-        '2. Pesquise por **`claudeCodeUsage.advice.apiKey`**\n' +
-        '3. Cole uma chave de API compatível com OpenAI — DeepSeek funciona direto\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. Execute **`Claude Code Usage: Show Usage Details`**\n' +
+        '2. Abra **Configurações → Conselho** no painel\n' +
+        '3. Cole uma chave compatível com OpenAI — ela fica apenas no VS Code SecretStorage\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. Execute novamente **`Claude Code Usage: Get AI Usage Advice`**',
       costComposition: 'Composição de custos',
       date: 'Data',
@@ -2680,6 +3272,7 @@ const translations: Record<SupportedLanguage, Translations> = {
     },
     releaseAnnouncement: {
       v230: 'Yang baru: penggunaan Codex Beta dan panduan optimasi lokal, catatan rilis yang sesuai dengan versi lengkap terpasang, serta penghapusan opsi Opus mingguan khusus model yang sudah usang.',
+      v231: 'Yang baru: statistik 30 hari Codex yang akurat, estimasi batas mingguan yang mengenali reset, dan heatmap aktivitas gabungan privat dengan ekspor SVG serta Markdown lokal.',
     },
     providers: PROVIDERS.id,
     weeklyValue: WEEKLY_VALUE_COPY.id,
@@ -2695,7 +3288,11 @@ const translations: Record<SupportedLanguage, Translations> = {
       settings: 'Pengaturan',
       settingsTab: 'Pengaturan',
       settingsIntro:
-        'Pengaturan sekarang ada di sini. Hanya bahasa, direktori data, dan API key yang tetap berada di Pengaturan VS Code (agar dapat disinkronkan). Perubahan langsung diterapkan.',
+        'Pengaturan sekarang ada di sini. Bahasa dan direktori data tetap memakai Pengaturan VS Code; API key disimpan di VS Code SecretStorage dan tidak pernah disinkronkan. Perubahan langsung diterapkan.',
+      secretMigrationFailed:
+        'API key saran yang tersimpan tidak dapat dipindahkan ke SecretStorage terenkripsi. Ekstensi dihentikan sebelum nilai lama dihapus. Perbaiki pengaturan lama lalu muat ulang jendela.',
+      secretMigrationWorkspace:
+        'API key khusus workspace tidak dapat dimigrasikan dengan aman ke satu entri SecretStorage global. Salin lalu hapus dari pengaturan workspace, muat ulang, kemudian masukkan di Pengaturan Dashboard → Saran.',
       settingsResetAll: 'Kembalikan semua ke default',
       settingsGroupGeneral: 'Umum',
       settingsGroupProviders: 'Penyedia',
@@ -2703,6 +3300,66 @@ const translations: Record<SupportedLanguage, Translations> = {
       settingsGroupStatusBar: 'Status bar',
       settingsGroupData: 'Data & penyegaran',
       settingsGroupAdvice: 'Saran AI & Optimizer',
+      adviceEffectiveness: {
+        title: 'Efektivitas saran AI',
+        description: 'Tinjau bagaimana setiap saran bergerak dari pengamatan lokal menuju bukti, tindakan, dan hasil dengan pagar pengaman kualitas.',
+        candidateNotice: 'Kandidat v2.3.1 · nonaktif secara default · tanpa permintaan AI default atau latar belakang.',
+        spineLabel: 'Alur bukti saran',
+        observation: 'Pengamatan',
+        evidence: 'Bukti',
+        recommendation: 'Saran',
+        action: 'Tindakan',
+        result: 'Hasil',
+        source: 'Sumber',
+        limitations: 'Keterbatasan',
+        proxyMetric: 'Metrik proksi',
+        longSessionSignal: '{share} penggunaan yang diamati berasal dari sesi panjang.',
+        largeContextSignal: '{share} penggunaan yang diamati terjadi pada konteks besar.',
+        frameworkOverheadSignal: '{share} dari penggunaan yang diamati adalah porsi injeksi framework yang diperkirakan secara terpisah; ini tidak menilai kualitas tulisan pengguna.',
+        clearBoundaryRecommendation: 'Gunakan batas tugas yang lebih jelas untuk pekerjaan panjang atau berkonteks besar.',
+        clearBoundaryAction: 'Mulai sesi baru saat tugas berubah; ringkas konteks hanya saat melanjutkan tugas yang sama.',
+        codexLocalRecommendation: 'Tinjau sinyal struktural Codex lokal sebelum tugas berikutnya yang sebanding.',
+        noEvidenceAdvice: 'Tidak ada saran berbasis bukti untuk cakupan ini.',
+        codexPreviewUnavailable: 'Pratinjau payload agregat Codex yang aman bagi privasi belum tersedia.',
+        elapsedTimeProxy: 'Rentang waktu sesi adalah proksi, bukan waktu kerja aktif yang diukur.',
+        qualityGuardrailPending: 'Bukti kualitas masih tertunda, sehingga belum ada kesimpulan efektivitas.',
+        payloadTitle: 'Snapshot payload tersegel',
+        payloadDescription: 'Snapshot tersegel ini persis sama dengan body JSON UTF-8 yang diterima endpoint BYOK terkonfigurasi hanya setelah klik Kirim yang terpisah.',
+        aggregatesOnly: 'Hanya agregat',
+        aggregatesWithPersonalization: 'Agregat + konteks pribadi yang diizinkan secara eksplisit',
+        aggregatesWithPromptSamples: 'Agregat + sampel prompt yang diizinkan secara eksplisit',
+        payloadBytes: '{bytes} byte UTF-8',
+        promptSamplesIncluded: '{count} sampel prompt disertakan',
+        previewPayload: 'Pratinjau snapshot tersegel',
+        noNetworkTransport: 'Pratinjau tidak mengirim apa pun. Pengiriman memerlukan klik terpisah.',
+        sendPreparedRequest: 'Kirim permintaan persis ini',
+        sendingPreparedRequest: 'Mengirim…',
+        sentPreparedRequest: 'Saran terstruktur diterima.',
+        aggregateConsentLabel: 'Izinkan data penggunaan agregat',
+        aggregateConsentHelp: 'Hanya mencakup agregat numerik dan sinyal struktural dalam daftar izin — tanpa prompt, path, ID sesi, atau catatan individual.',
+        promptConsentLabel: 'Sertakan sampel prompt dan konteks pribadi terkonfigurasi',
+        promptConsentHelp: 'Opsional dan nonaktif secara default. Teks prompt terbatas dan konteks pribadi terkonfigurasi hanya ditambahkan setelah persetujuan eksplisit terpisah ini.',
+        promptWindowHelp: 'Sampel prompt yang lebih lama dari jendela bukti {days} hari yang dikonfigurasi akan dikecualikan.',
+        feedbackTitle: 'Umpan balik lokal',
+        helpful: 'Bermanfaat',
+        notHelpful: 'Tidak bermanfaat',
+        applied: 'Diterapkan',
+        snooze: 'Tunda 7 hari',
+        resume: 'Tampilkan lagi',
+        snoozedUntil: 'Ditunda hingga {date}',
+        feedbackLocalOnly: 'Disimpan hanya di perangkat ini dan tidak pernah ditambahkan ke payload jarak jauh.',
+        feedbackSaveFailed: 'Umpan balik tidak dapat disimpan secara lokal. Tidak ada yang dikirim.',
+        comparisonTitle: 'Hasil tugas yang sebanding',
+        comparablePairs: '{count} pasangan tugas yang sebanding',
+        minimumComparablePairs: 'Setidaknya {minimum} pasangan tugas yang sebanding diperlukan sebelum menarik kesimpulan.',
+        insufficientEvidence: 'Bukti belum cukup untuk menarik kesimpulan.',
+        qualityGuardrailFailed: 'Pagar pengaman kualitas tidak terpenuhi, sehingga tidak ada klaim efektivitas.',
+        improved: 'Peningkatan mencapai ambang yang ditetapkan sebelumnya sambil mempertahankan pagar pengaman kualitas.',
+        noDemonstratedImprovement: 'Belum ada peningkatan yang terbukti; ini tidak membuktikan kerugian atau hubungan sebab-akibat.',
+        clearLocalData: 'Hapus data saran lokal',
+        clearLocalDataConfirm: 'Hapus persetujuan saran, umpan balik, pasangan sebanding, dan hasil perbandingan yang tersimpan di perangkat ini?',
+        strictOutputRejected: 'Output model terstruktur ditolak. Tidak ada saran yang dibuat.',
+      },
       totalTokens: 'Total Token',
       inputTokens: 'Token Masukan',
       outputTokens: 'Token Keluaran',
@@ -2772,8 +3429,8 @@ const translations: Record<SupportedLanguage, Translations> = {
       model: 'Model',
       agents: 'Agen',
       agent: 'Agen',
-      workflowsThisMonth: 'Workflow bulan ini',
-      workflowCostShare: 'proporsi dari biaya bulan ini',
+      workflowsLast30Days: 'Workflow 30 hari terakhir',
+      workflowLast30DaysCostShare: 'proporsi biaya 30 hari terakhir',
       workflowCacheHint:
         'Tingkat cache hit = cache read ÷ semua token sisi masukan. Workflow native Claude memakai ulang prompt cache lintas agen (tingkat tinggi); provider tanpa cache lintas-agen menunjukkan ~0% — workflow yang sama jadi jauh lebih mahal di sana.',
       adhocBadge: 'subagent (ad-hoc)',
@@ -2846,14 +3503,14 @@ const translations: Record<SupportedLanguage, Translations> = {
       getAdvice: 'Dapatkan Saran AI',
       adviceCardTitle: 'Saran AI',
       adviceCardDesc:
-        'Kirim ringkasan penggunaan Anda + sampel prompt Anda sendiri ke model Anda dan dapatkan tips konkret untuk menulis instruksi yang lebih jelas dan mengurangi pemborosan.',
+        'Tinjau bukti lokal terlebih dahulu. Permintaan persis hanya berisi agregat secara default; sampel prompt dan konteks pribadi memerlukan persetujuan terpisah, dan tidak ada yang dikirim sampai Anda mengeklik Kirim.',
       optimizerTitle: 'Pengoptimal Penggunaan',
       optimizerDesc:
         'Ubah permintaan yang masih kasar dan belum rapi menjadi prompt bersih yang bisa langsung ditempel ke Claude Code — plus saran effort / thinking / model untuk tugas tersebut.',
       optimizerHowto:
-        'Ketik atau tempel draf Anda di bawah, centang penyesuaian opsional yang diinginkan, lalu klik Optimalkan. Hanya teks yang Anda tempel yang dikirim ke model Anda — tidak pernah ke Claude Code atau terminal Anda.',
+        'Ketik atau tempel draf Anda di bawah, pilih penyesuaian opsional, lalu buat pratinjau permintaan persis. Tidak ada yang dikirim sampai Anda mengeklik Kirim secara terpisah; hanya teks yang ditempel yang dapat disertakan.',
       optimizerConsent:
-        'Usage Optimizer mengirim teks yang Anda tempel ke model API yang telah dikonfigurasi. Tidak ada yang dikirim ke Claude Code dan tidak ada yang diketik ke terminal. Lanjutkan?',
+        'Buat pratinjau permintaan persis? Ini tidak mengirim apa pun; pengiriman ke model API yang dikonfigurasi memerlukan klik terpisah.',
       optimizerEnableBtn: 'Aktifkan di pengaturan',
       optimizerPlaceholder: 'Tempel draf prompt untuk dioptimalkan…',
       optimizerRun: 'Optimalkan',
@@ -2885,10 +3542,10 @@ const translations: Record<SupportedLanguage, Translations> = {
         '> yang dihasilkan fitur ini. Ini **bukan** berdasarkan data penggunaan\n' +
         '> Claude Code Anda yang sebenarnya — tidak ada yang dikirim ke API mana pun untuk menghasilkan ini.\n\n' +
         '### Untuk mendapatkan saran nyata dan personal berdasarkan penggunaan ANDA:\n\n' +
-        '1. Buka Pengaturan (`Ctrl+,` / `Cmd+,`)\n' +
-        '2. Cari **`claudeCodeUsage.advice.apiKey`**\n' +
-        '3. Tempel API key yang kompatibel dengan OpenAI — DeepSeek langsung berfungsi\n' +
-        '   ([deepseek.com](https://platform.deepseek.com))\n' +
+        '1. Jalankan **`Claude Code Usage: Show Usage Details`**\n' +
+        '2. Buka bagian **Pengaturan → Saran** di dashboard\n' +
+        '3. Tempel API key yang kompatibel dengan OpenAI — hanya disimpan di VS Code SecretStorage\n' +
+        '   DeepSeek: [deepseek.com](https://platform.deepseek.com)\n' +
         '4. Jalankan ulang **`Claude Code Usage: Get AI Usage Advice`**',
       costComposition: 'Komposisi Biaya',
       date: 'Tanggal',
@@ -2919,18 +3576,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: 'Token-Dezimalstellen', help: 'Dezimalstellen für kompakte Token-Anzeige (1.2M / 345.6K). Volle Ganzzahlen bleiben unberührt.' },
     'compactNumbers': { label: 'Kompakte Token-Zahlen', help: 'Zeige 1.2M / 345K statt voller Zahlen.' },
     'releaseAnnouncements': { label: 'Release-Hinweise', help: 'Nach einem Erweiterungs-Upgrade einmal die Neuerungen anzeigen.' },
+    'pricingBackend': { label: 'Claude-Preisquelle', help: 'Wähle AWS-Bedrock-In-Region-Preise, wenn Claude Code über Bedrock geroutet wird.' },
     'codex.enabled': { label: 'Codex Beta aktivieren', help: 'Datenschutzfreundliche Nutzungsaggregate aus lokalen Codex-Sitzungslogs lesen.' },
     'codex.dataDirectory': { label: 'Benutzerdefiniertes Codex-Datenverzeichnis', help: 'Leer = CODEX_HOME, dann ~/.codex. Authentifizierungsdateien werden nie gelesen.' },
     'codex.fileWatchSeconds': { label: 'Codex-Live-Aktualisierungsverzögerung', help: 'Ruhe-Debounce nach lokalen Codex-JSONL-Änderungen. Aus deaktiviert die Überwachung.' },
     'codex.optimization.enabled': { label: 'Codex-Verhaltensoptimierung anzeigen', help: 'Lokale, deterministische Codex-Verhaltensmetriken und Empfehlungen anzeigen.' },
     'statusBarProvider': { label: 'Statusleisten-Anbieter', help: 'Auto bevorzugt Claude, wenn beide Anbieter Daten haben.' },
-    'codex.statusMetric': { label: 'Codex-Statusmetrik', help: 'Nutzung ohne Cache, verarbeitete Token oder Ausgabe-Token.' },
+    'codex.statusMetric': { label: 'Codex-Statusmetrik', help: 'Heutige Nutzung ohne Cache, verarbeitete Token oder Ausgabe-Token.' },
     'timezone': { label: 'Zeitzone für Daten', help: 'Gängige Zone oder UTC-Offset (jeder Offset abgedeckt) oder Systemstandard. Labels zeigen den aktuellen UTC-Offset.' },
     'showWeeklyEquivalentValue': { label: 'Wöchentlichen API-Gegenwert anzeigen', help: 'Standardmäßig an. Zeigt den historischen wöchentlichen API-Gegenwert in „Seit Aufzeichnungsbeginn“ und „Vergleich“. Dies ist eine Schätzung, keine Rechnung und kein Abonnementkontingent.' },
     'showHeatmap': { label: 'Token-Heatmap zeigen (Tab „Seit Aufzeichnungsbeginn“)', help: 'Standardmäßig aus. GitHub-artige Jahres-Heatmap; als SVG exportieren oder auf dein GitHub-Profil veröffentlichen.' },
     'showEfficiency': { label: 'Effizienz-Einblicke zeigen', help: 'Standardmäßig aus. Kosten/Nachricht, Token/Nachricht, Cache-Ersparnis und die Cache-Warmzeit-Schätzung.' },
     'showCostliestMessages': { label: '„Top 10 teuerste Nachrichten“ zeigen', help: 'Standardmäßig aus. Reiht deine teuersten Einzel-Turns; das Aufklappen zeigt den Prompt (dein eigener Text).' },
-    'enableShareCard': { label: 'Nutzungs-Sharecard aktivieren', help: 'Standardmäßig aus. Eine konfigurierbare einseitige SVG-Zusammenfassung zum Erzeugen und Teilen.' },
+    'enableShareCard': { label: 'Freigabe-Arbeitsbereich aktivieren', help: 'Standardmäßig an. Zeigt den Freigabe-Arbeitsbereich im Vergleich und die Anbieter-Sharecard. Ausschalten blendet die Freigabeoberfläche aus; Export bleibt eine ausdrückliche Aktion.' },
     'enableSessionActions': { label: 'Sitzungsaktionen (Fortsetzen & Löschen)', help: 'Standardmäßig aus. Zeigt auf dem Sitzungen-Tab die Schaltflächen „Fortsetzen“ und „Löschen“. Beide WIRKEN auf dein Claude Code (Gespräch erneut öffnen / Log in den Papierkorb), anders als diese schreibgeschützte Erweiterung — daher zusammen optional.' },
     'projectGroupingMode': { label: 'Projektgruppierung', help: 'git = nach Repo · folder = oberste Ebene · flat = jedes cwd.' },
     'showCost': { label: 'Heutige Kosten / Token anzeigen', help: '' },
@@ -2951,13 +3609,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'dashboardAutoRefresh': { label: 'Dashboard-Auto-Aktualisierung', help: 'Aktualisiert das Dashboard automatisch bei neuer Nutzung. Aus = nur manuelle Aktualisierung (die Statusleiste aktualisiert weiter).' },
     'enableContentAnalysis': { label: 'Inhaltsanalyse (Content-Registerkarte)', help: 'Deaktivieren, um die CPU-intensive Textprüfung zu überspringen.' },
     'analysis.calibrate': { label: 'Inhaltszahlen kalibrieren', help: 'Skalieren Sie Schätzungen auf die exakten abgerechneten Token-Gesamtzahlen.' },
-    'advice.apiKey': { label: 'API-Schlüssel', help: 'Für das api-Backend. Bleibt in den VS Code-Einstellungen.' },
+    'advice.effectiveness.enabled': { label: 'Vorschau zur Wirksamkeit von KI-Empfehlungen aktivieren', help: 'Standardmäßig aus. Zeigt lokale Evidenz, exakte BYOK-Anfragevorschau, Feedback und Vergleiche; gesendet wird nur nach einem separaten Klick.' },
+    'advice.apiKey': { label: 'API-Schlüssel', help: 'Für das api-Backend. Liegt in VS Code SecretStorage, wird nie synchronisiert und nie an das Dashboard gesendet.' },
     'advice.apiFormat': { label: 'API-Format', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'API-URL', help: 'Endpunkt für das api-Backend.' },
     'advice.model': { label: 'API-Modell', help: '' },
     'advice.reasoningEffort': { label: 'Reasoning-Aufwand (openai)', help: '' },
-    'advice.promptWindowDays': { label: 'Prompt-Beispielfenster (Tage)', help: '' },
-    'advice.userContext': { label: 'Persönlicher/Projektkontext', help: 'Optionale Hintergrundinfo; fügt einen Abschnitt "Personalisiert" hinzu.' },
+    'advice.promptWindowDays': { label: 'Evidenz- und Prompt-Fenster (Tage)', help: '' },
+    'advice.userContext': { label: 'Persönlicher/Projektkontext', help: 'Optional; wird nur mit separater Prompt-Personalisierungs-Einwilligung und sichtbar in der exakten Vorschau gesendet.' },
     'advice.optimizer.enabled': { label: 'Usage Optimizer aktivieren', help: 'Zeigt die Opt-in-Optimizer-Karte auf der Registerkarte "Content" an.' },
   },
   'zh-TW': {
@@ -2966,18 +3625,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: 'Token 小數位數', help: '緊湊 token 顯示（1.2M / 345.6K）的小數位數。完整整數值不受影響。' },
     'compactNumbers': { label: '簡潔的 Token 計數', help: '顯示 1.2M / 345K 而非完整數字。' },
     'releaseAnnouncements': { label: '版本更新通知', help: '擴充套件升級後顯示一次「新功能」通知。' },
+    'pricingBackend': { label: 'Claude 價格來源', help: '若 Claude Code 透過 Bedrock 路由，請選擇 AWS Bedrock 區域內價格。' },
     'codex.enabled': { label: '啟用 Codex Beta', help: '從本機 Codex 工作階段日誌讀取隱私安全的用量彙總。' },
     'codex.dataDirectory': { label: '自訂 Codex 資料目錄', help: '留空時使用 CODEX_HOME，再使用 ~/.codex；不會讀取認證檔案。' },
     'codex.fileWatchSeconds': { label: 'Codex 即時重新整理延遲', help: '本機 Codex JSONL 變更後的靜默防抖；關閉即停用監看。' },
     'codex.optimization.enabled': { label: '顯示 Codex 行為最佳化', help: '顯示本機、確定性的 Codex 行為指標與建議。' },
     'statusBarProvider': { label: '狀態列供應商', help: '兩個供應商都有資料時，自動模式優先顯示 Claude。' },
-    'codex.statusMetric': { label: 'Codex 狀態列指標', help: '未快取用量、已處理 Token 或輸出 Token。' },
+    'codex.statusMetric': { label: 'Codex 狀態列指標', help: '今日未快取用量、已處理 Token 或輸出 Token。' },
     'timezone': { label: '日期時區', help: '常用時區或 UTC 偏移（涵蓋所有偏移），或系統預設。標籤顯示目前的 UTC 偏移。' },
     'showWeeklyEquivalentValue': { label: '顯示每週 API 等效價值', help: '預設開啟。在「所有」與「比較」中顯示歷史每週 API 等效價值；屬於估算，不是帳單或訂閱額度。' },
     'showHeatmap': { label: '顯示 Token 熱力圖（「所有」分頁）', help: '預設關閉。全部分頁上的 GitHub 風格年度熱力圖；可匯出 SVG 或發佈到你的 GitHub 首頁。' },
     'showEfficiency': { label: '顯示效率洞察', help: '預設關閉。加入每則成本、每則 token、快取節省與快取保溫估計。' },
     'showCostliestMessages': { label: '顯示「最貴 10 則訊息」', help: '預設關閉。列出最貴的單則對話；展開會顯示 prompt（隱私：你自己的文字）。' },
-    'enableShareCard': { label: '啟用用量分享卡', help: '預設關閉。可設定的一頁式 SVG 摘要，可產生並匯出分享。' },
+    'enableShareCard': { label: '啟用分享工作台', help: '預設開啟。顯示「比較」分享工作台與供應商分享卡；關閉後隱藏分享介面，匯出仍需明確操作。' },
     'enableSessionActions': { label: '會話操作（恢復與刪除）', help: '預設關閉。在「會話」分頁顯示「恢復」和「刪除」按鈕。兩者都會「操作」你的 Claude Code（重開對話／把紀錄檔丟進垃圾桶），與這個唯讀擴充功能的定位相反，所以一起維持選用。' },
     'projectGroupingMode': { label: '專案分組', help: 'git = 依儲存庫 · folder = 最上層 · flat = 每個目前工作目錄。' },
     'showCost': { label: '顯示今日費用 / Token 用量', help: '' },
@@ -2998,13 +3658,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'dashboardAutoRefresh': { label: '儀表板自動重新整理', help: '有新用量時自動重新整理儀表板。關閉 = 僅手動重新整理（狀態列仍會更新）。' },
     'enableContentAnalysis': { label: '內容分析 (Content 分頁)', help: '停用以跳過 CPU 密集的文字掃描。' },
     'analysis.calibrate': { label: '校準內容數據', help: '將估計值縮放至確切的計費 Token 總數。' },
-    'advice.apiKey': { label: 'API 金鑰', help: '用於 api 後端。保留在 VS Code 設定中。' },
+    'advice.effectiveness.enabled': { label: '啟用 AI 建議有效性預覽', help: '預設關閉。顯示本機證據、精確 BYOK 請求預覽、回饋與比較；只有另行點擊後才會傳送。' },
+    'advice.apiKey': { label: 'API 金鑰', help: '用於 api 後端。只存於 VS Code SecretStorage，不同步，也不傳送至儀表板。' },
     'advice.apiFormat': { label: 'API 格式', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'API URL', help: 'api 後端的端點。' },
     'advice.model': { label: 'API 模型', help: '' },
     'advice.reasoningEffort': { label: '推論努力度 (openai)', help: '' },
-    'advice.promptWindowDays': { label: '提示取樣視窗 (天數)', help: '' },
-    'advice.userContext': { label: '個人/專案上下文', help: '可選的背景資訊；新增「Personalised」區段。' },
+    'advice.promptWindowDays': { label: '證據與提示視窗 (天數)', help: '' },
+    'advice.userContext': { label: '個人/專案上下文', help: '選用；僅在另行同意提示個人化後傳送，並完整顯示在精確預覽中。' },
     'advice.optimizer.enabled': { label: '啟用使用情況優化器', help: '在 Content 分頁上顯示自願加入的 Optimizer 卡片。' },
   },
   'zh-CN': {
@@ -3013,18 +3674,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: 'Token 小数位数', help: '紧凑 token 显示（1.2M / 345.6K）的小数位数。完整整数值不受影响。' },
     'compactNumbers': { label: '简洁的 token 计数', help: '显示 1.2M / 345K 而非完整数字。' },
     'releaseAnnouncements': { label: '版本更新通知', help: '扩展升级后显示一次“新功能”通知。' },
+    'pricingBackend': { label: 'Claude 价格来源', help: '如果 Claude Code 通过 Bedrock 路由，请选择 AWS Bedrock 区域内价格。' },
     'codex.enabled': { label: '启用 Codex Beta', help: '从本地 Codex 会话日志读取隐私安全的用量汇总。' },
     'codex.dataDirectory': { label: '自定义 Codex 数据目录', help: '留空时使用 CODEX_HOME，再使用 ~/.codex；不会读取认证文件。' },
     'codex.fileWatchSeconds': { label: 'Codex 实时刷新延迟', help: '本地 Codex JSONL 变更后的静默防抖；关闭即停用监视。' },
     'codex.optimization.enabled': { label: '显示 Codex 行为优化', help: '显示本地、确定性的 Codex 行为指标与建议。' },
     'statusBarProvider': { label: '状态栏供应商', help: '两个供应商都有数据时，自动模式优先显示 Claude。' },
-    'codex.statusMetric': { label: 'Codex 状态栏指标', help: '未缓存用量、已处理 Token 或输出 Token。' },
+    'codex.statusMetric': { label: 'Codex 状态栏指标', help: '今日未缓存用量、已处理 Token 或输出 Token。' },
     'timezone': { label: '日期时区', help: '常用时区或 UTC 偏移（涵盖所有偏移），或系统默认。标签显示当前的 UTC 偏移。' },
     'showWeeklyEquivalentValue': { label: '显示每周 API 等效价值', help: '默认开启。在“全部时间”和“对比”中显示历史每周 API 等效价值；属于估算，不是账单或订阅额度。' },
     'showHeatmap': { label: '显示 Token 热力图（“所有”选项卡）', help: '默认关闭。全部标签上的 GitHub 风格年度热力图；可导出 SVG 或发布到你的 GitHub 主页。' },
     'showEfficiency': { label: '显示效率洞察', help: '默认关闭。加入每条成本、每条 token、缓存节省与缓存保温估计。' },
     'showCostliestMessages': { label: '显示“最贵 10 条消息”', help: '默认关闭。列出最贵的单条对话；展开会显示 prompt（隐私：你自己的文字）。' },
-    'enableShareCard': { label: '启用用量分享卡', help: '默认关闭。可配置的一页式 SVG 摘要，可生成并导出分享。' },
+    'enableShareCard': { label: '启用分享工作台', help: '默认开启。显示“对比”分享工作台与供应商分享卡；关闭后隐藏分享界面，导出仍需明确操作。' },
     'enableSessionActions': { label: '会话操作（恢复与删除）', help: '默认关闭。在「会话」标签页显示「恢复」和「删除」按钮。两者都会「操作」你的 Claude Code（重开对话／把日志丢进回收站），与这个只读扩展的定位相反，所以一起保持可选。' },
     'projectGroupingMode': { label: '项目分组', help: 'git = 按仓库 · folder = 顶层 · flat = 每个当前工作目录。' },
     'showCost': { label: '显示今日费用 / token 用量', help: '' },
@@ -3045,13 +3707,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'dashboardAutoRefresh': { label: '仪表板自动刷新', help: '有新用量时自动刷新仪表板。关闭 = 仅手动刷新（状态栏仍会更新）。' },
     'enableContentAnalysis': { label: '内容分析 (Content 选项卡)', help: '禁用以跳过 CPU 密集型文本扫描。' },
     'analysis.calibrate': { label: '校准内容数据', help: '将估计值缩放至确切的计费 token 总数。' },
-    'advice.apiKey': { label: 'API 密钥', help: '用于 api 后端。保留在 VS Code 设置中。' },
+    'advice.effectiveness.enabled': { label: '启用 AI 建议有效性预览', help: '默认关闭。显示本地证据、精确 BYOK 请求预览、反馈与比较；只有另行点击后才会发送。' },
+    'advice.apiKey': { label: 'API 密钥', help: '用于 api 后端。只存入 VS Code SecretStorage，不同步，也不发送到仪表板。' },
     'advice.apiFormat': { label: 'API 格式', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'API URL', help: 'api 后端的端点。' },
     'advice.model': { label: 'API 模型', help: '' },
     'advice.reasoningEffort': { label: '推理努力度 (openai)', help: '' },
-    'advice.promptWindowDays': { label: '提示采样窗口 (天数)', help: '' },
-    'advice.userContext': { label: '个人/项目上下文', help: '可选的背景信息；添加「Personalised」部分。' },
+    'advice.promptWindowDays': { label: '证据与提示窗口 (天数)', help: '' },
+    'advice.userContext': { label: '个人/项目上下文', help: '可选；仅在另行同意提示个性化后发送，并完整显示在精确预览中。' },
     'advice.optimizer.enabled': { label: '启用使用优化器', help: '在「Content」选项卡上显示自愿加入的 Optimizer 卡片。' },
   },
   'ja': {
@@ -3060,18 +3723,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: 'トークンの小数点以下桁数', help: 'トークンの短縮表示（1.2M / 345.6K）の小数桁数。完全な整数値には影響しません。' },
     'compactNumbers': { label: 'トークン数を短縮表記', help: '完全な数値の代わりに 1.2M / 345K と表示します。' },
     'releaseAnnouncements': { label: 'リリース通知', help: '拡張機能のアップグレード後に新機能を一度通知します。' },
+    'pricingBackend': { label: 'Claude の価格ソース', help: 'Claude Code を Bedrock 経由でルーティングする場合は AWS Bedrock のリージョン内価格を選択します。' },
     'codex.enabled': { label: 'Codex Beta を有効化', help: 'ローカルの Codex セッションログからプライバシー安全な使用量集計を読み取ります。' },
     'codex.dataDirectory': { label: 'カスタム Codex データディレクトリ', help: '空欄の場合は CODEX_HOME、次に ~/.codex。認証ファイルは読みません。' },
     'codex.fileWatchSeconds': { label: 'Codex ライブ更新遅延', help: 'ローカル Codex JSONL 変更後の静かなデバウンス。オフで監視を無効化します。' },
     'codex.optimization.enabled': { label: 'Codex の行動最適化を表示', help: 'ローカルで決定論的な Codex の行動指標と提案を表示します。' },
     'statusBarProvider': { label: 'ステータスバーのプロバイダー', help: '両方にデータがある場合、自動は Claude を優先します。' },
-    'codex.statusMetric': { label: 'Codex ステータスメトリック', help: '非キャッシュ使用量、処理済みトークン、または出力トークン。' },
+    'codex.statusMetric': { label: 'Codex ステータスメトリック', help: '今日の非キャッシュ使用量、処理済みトークン、または出力トークン。' },
     'timezone': { label: '日付のタイムゾーン', help: '一般的なゾーンまたは UTC オフセット（全オフセット対応）、あるいはシステム既定。ラベルは現在の UTC オフセットを表示。' },
     'showWeeklyEquivalentValue': { label: '週間 API 等価価値を表示', help: '既定でオン。「すべて」と「比較」に過去の週間 API 等価価値を表示します。これは推定値であり、請求額やサブスクリプション利用枠ではありません。' },
     'showHeatmap': { label: 'トークンヒートマップを表示（「すべて」タブ）', help: '既定でオフ。GitHub 風の年間ヒートマップ。SVG 書き出しや GitHub プロフィールへの公開が可能。' },
     'showEfficiency': { label: '効率インサイトを表示', help: '既定でオフ。メッセージ単価、メッセージ当たりトークン、キャッシュ節約、キャッシュ保温推定を追加。' },
     'showCostliestMessages': { label: '「最も高価なメッセージ Top 10」を表示', help: '既定でオフ。最も高価な単一ターンを順位付け。展開でプロンプト表示（自分の文章）。' },
-    'enableShareCard': { label: '使用状況シェアカードを有効化', help: '既定でオフ。生成して共有できる、設定可能な 1 ページの SVG サマリー。' },
+    'enableShareCard': { label: '共有ワークスペースを有効化', help: '既定でオン。「比較」の共有ワークスペースとプロバイダーの共有カードを表示します。オフにすると共有 UI を隠し、書き出しは引き続き明示操作です。' },
     'enableSessionActions': { label: 'セッション操作（再開と削除）', help: '既定はオフ。セッションタブに「再開」と「削除」ボタンを表示します。どちらもあなたの Claude Code を操作します（会話を再度開く／ログをゴミ箱へ）。読み取り専用のこの拡張とは相容れないため、まとめてオプトインです。' },
     'projectGroupingMode': { label: 'プロジェクトのグループ化', help: 'git = リポジトリごと · folder = トップレベル · flat = 各 cwd。' },
     'showCost': { label: '今日のコスト / トークンを表示', help: '' },
@@ -3092,13 +3756,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'dashboardAutoRefresh': { label: 'ダッシュボードの自動更新', help: '新しい使用があるとダッシュボードを自動更新します。オフ = 手動更新のみ（ステータスバーは更新を続行）。' },
     'enableContentAnalysis': { label: 'コンテンツ分析 (Content タブ)', help: 'CPU負荷の高いテキストスキャンをスキップするには無効にします。' },
     'analysis.calibrate': { label: 'コンテンツ数値を調整', help: '推定値を正確な課金トークン総数に合わせて拡大縮小します。' },
-    'advice.apiKey': { label: 'API キー', help: 'api バックエンド用。VS Code 設定に保存されます。' },
+    'advice.effectiveness.enabled': { label: 'AI アドバイス有効性プレビューを有効化', help: 'デフォルトは無効です。ローカル根拠、正確な BYOK リクエストプレビュー、フィードバック、比較を表示し、別のクリック後にだけ送信します。' },
+    'advice.apiKey': { label: 'API キー', help: 'api バックエンド用。VS Code SecretStorage のみに保存され、同期もダッシュボードへの送信も行いません。' },
     'advice.apiFormat': { label: 'API 形式', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'API URL', help: 'api バックエンドのエンドポイント。' },
     'advice.model': { label: 'API モデル', help: '' },
     'advice.reasoningEffort': { label: '推論努力 (openai)', help: '' },
-    'advice.promptWindowDays': { label: 'プロンプトサンプルウィンドウ (日数)', help: '' },
-    'advice.userContext': { label: '個人/プロジェクトのコンテキスト', help: 'オプションの背景情報。「Personalised」セクションが追加されます。' },
+    'advice.promptWindowDays': { label: '根拠とプロンプトの期間 (日数)', help: '' },
+    'advice.userContext': { label: '個人/プロジェクトのコンテキスト', help: '任意です。別のプロンプト個人化同意後だけ送信し、正確なプレビューに全文を表示します。' },
     'advice.optimizer.enabled': { label: 'Usage Optimizer を有効にする', help: '「Content」タブにオプトインの Optimizer カードを表示します。' },
   },
   'ko': {
@@ -3107,18 +3772,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: '토큰 소수점 자리수', help: '간략한 토큰 표시(1.2M / 345.6K)의 소수 자리수. 전체 정수 값에는 영향을 주지 않습니다.' },
     'compactNumbers': { label: '간략한 토큰 수 표시', help: '전체 숫자 대신 1.2M / 345K로 표시합니다.' },
     'releaseAnnouncements': { label: '릴리스 알림', help: '확장 업그레이드 후 새 기능 알림을 한 번 표시합니다.' },
+    'pricingBackend': { label: 'Claude 가격 출처', help: 'Claude Code가 Bedrock을 통해 라우팅될 때 AWS Bedrock 리전 내 가격을 선택합니다.' },
     'codex.enabled': { label: 'Codex Beta 사용', help: '로컬 Codex 세션 로그에서 개인정보 보호형 사용량 집계를 읽습니다.' },
     'codex.dataDirectory': { label: '사용자 지정 Codex 데이터 디렉터리', help: '비우면 CODEX_HOME, 그다음 ~/.codex를 사용하며 인증 파일은 읽지 않습니다.' },
     'codex.fileWatchSeconds': { label: 'Codex 실시간 새로고침 지연', help: '로컬 Codex JSONL 변경 후 조용한 디바운스입니다. 끄면 감시를 중지합니다.' },
     'codex.optimization.enabled': { label: 'Codex 행동 최적화 표시', help: '로컬의 결정론적 Codex 행동 지표와 권장 사항을 표시합니다.' },
     'statusBarProvider': { label: '상태 표시줄 공급자', help: '두 공급자 모두 데이터가 있으면 자동은 Claude를 우선합니다.' },
-    'codex.statusMetric': { label: 'Codex 상태 지표', help: '캐시되지 않은 사용량, 처리된 토큰 또는 출력 토큰.' },
+    'codex.statusMetric': { label: 'Codex 상태 지표', help: '오늘의 캐시되지 않은 사용량, 처리된 토큰 또는 출력 토큰.' },
     'timezone': { label: '날짜 시간대', help: '일반 지역 또는 UTC 오프셋(모든 오프셋 지원), 또는 시스템 기본값. 라벨에 현재 UTC 오프셋 표시.' },
     'showWeeklyEquivalentValue': { label: '주간 API 등가 가치 표시', help: '기본값 켜짐. 전체 및 비교 화면에 과거 주간 API 등가 가치를 표시합니다. 이는 추정치이며 청구서나 구독 할당량이 아닙니다.' },
     'showHeatmap': { label: '토큰 히트맵 표시(전체 탭)', help: '기본 꺼짐. GitHub 스타일 연간 히트맵. SVG 내보내기 또는 GitHub 프로필에 게시 가능.' },
     'showEfficiency': { label: '효율 인사이트 표시', help: '기본 꺼짐. 메시지당 비용/토큰, 캐시 절감, 캐시 보온 추정치를 추가.' },
     'showCostliestMessages': { label: '“가장 비싼 메시지 Top 10” 표시', help: '기본 꺼짐. 가장 비싼 단일 턴을 순위화. 펼치면 프롬프트 표시(본인 텍스트).' },
-    'enableShareCard': { label: '사용량 공유 카드 사용', help: '기본 꺼짐. 생성·내보내 공유할 수 있는 구성 가능한 1페이지 SVG 요약.' },
+    'enableShareCard': { label: '공유 작업 공간 사용', help: '기본 켜짐. 비교 공유 작업 공간과 공급자 공유 카드를 표시합니다. 끄면 공유 UI가 숨겨지며 내보내기는 계속 명시적 작업입니다.' },
     'enableSessionActions': { label: '세션 작업(재개 및 삭제)', help: '기본값 꺼짐. 세션 탭에 재개·삭제 버튼을 표시합니다. 둘 다 사용자의 Claude Code를 조작하므로(대화 다시 열기/로그를 휴지통으로) 읽기 전용인 이 확장과 맞지 않아 함께 옵트인으로 둡니다.' },
     'projectGroupingMode': { label: '프로젝트 그룹화', help: 'git = 저장소별 · folder = 최상위 · flat = 각 cwd.' },
     'showCost': { label: '오늘의 비용 / 토큰 표시', help: '' },
@@ -3139,13 +3805,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'dashboardAutoRefresh': { label: '대시보드 자동 새로 고침', help: '새 사용량이 들어오면 대시보드를 자동 새로 고침. 끄면 수동 새로 고침만(상태 표시줄은 계속 업데이트).' },
     'enableContentAnalysis': { label: '콘텐츠 분석 (Content 탭)', help: 'CPU 사용이 많은 텍스트 검사를 건너뛰려면 비활성화하세요.' },
     'analysis.calibrate': { label: '콘텐츠 수치 보정', help: '예상치를 정확한 청구 토큰 총합에 맞게 조정합니다.' },
-    'advice.apiKey': { label: 'API 키', help: 'api 백엔드용. VS Code 설정에 보관됩니다.' },
+    'advice.effectiveness.enabled': { label: 'AI 조언 효과성 미리보기 활성화', help: '기본적으로 꺼져 있습니다. 로컬 근거, 정확한 BYOK 요청 미리보기, 피드백, 비교를 표시하며 별도 클릭 후에만 전송합니다.' },
+    'advice.apiKey': { label: 'API 키', help: 'api 백엔드용. VS Code SecretStorage에만 저장되며 동기화되거나 대시보드로 전송되지 않습니다.' },
     'advice.apiFormat': { label: 'API 형식', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'API URL', help: 'api 백엔드의 엔드포인트.' },
     'advice.model': { label: 'API 모델', help: '' },
     'advice.reasoningEffort': { label: '추론 노력 (openai)', help: '' },
-    'advice.promptWindowDays': { label: '프롬프트 샘플 창 (일)', help: '' },
-    'advice.userContext': { label: '개인/프로젝트 컨텍스트', help: '선택적 배경 정보; "Personalised" 섹션을 추가합니다.' },
+    'advice.promptWindowDays': { label: '근거 및 프롬프트 기간 (일)', help: '' },
+    'advice.userContext': { label: '개인/프로젝트 컨텍스트', help: '선택 사항이며 별도의 프롬프트 개인화 동의 후에만 전송되고 정확한 미리보기에 모두 표시됩니다.' },
     'advice.optimizer.enabled': { label: '사용량 최적화 도구 활성화', help: 'Content 탭에 옵트인 Optimizer 카드를 표시합니다.' },
   },
   'pt-BR': {
@@ -3154,18 +3821,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: 'Casas decimais de tokens', help: 'Casas decimais para a exibição compacta de tokens (1.2M / 345.6K). As contagens inteiras completas não são afetadas.' },
     'compactNumbers': { label: 'Contagem de tokens compacta', help: 'Mostra 1.2M / 345K em vez dos números completos.' },
     'releaseAnnouncements': { label: 'Avisos de versão', help: 'Mostra uma vez as novidades após atualizar a extensão.' },
+    'pricingBackend': { label: 'Fonte de preços do Claude', help: 'Selecione os preços regionais da AWS Bedrock quando o Claude Code for roteado pela Bedrock.' },
     'codex.enabled': { label: 'Ativar Codex Beta', help: 'Lê agregados de uso com privacidade a partir dos logs locais de sessão do Codex.' },
     'codex.dataDirectory': { label: 'Diretório de dados Codex personalizado', help: 'Vazio = CODEX_HOME, depois ~/.codex. Arquivos de autenticação nunca são lidos.' },
     'codex.fileWatchSeconds': { label: 'Atraso da atualização ao vivo do Codex', help: 'Debounce silencioso após mudanças locais em JSONL do Codex. Desligado desativa a observação.' },
     'codex.optimization.enabled': { label: 'Mostrar otimização de comportamento do Codex', help: 'Mostra métricas e recomendações locais e determinísticas de comportamento do Codex.' },
     'statusBarProvider': { label: 'Provedor da barra de status', help: 'Auto prioriza Claude quando ambos têm dados.' },
-    'codex.statusMetric': { label: 'Métrica de status do Codex', help: 'Uso sem cache, tokens processados ou tokens de saída.' },
+    'codex.statusMetric': { label: 'Métrica de status do Codex', help: 'Uso de hoje sem cache, tokens processados ou tokens de saída.' },
     'timezone': { label: 'Fuso horário das datas', help: 'Zona comum ou deslocamento UTC (todos cobertos), ou padrão do sistema. Os rótulos mostram o deslocamento UTC atual.' },
     'showWeeklyEquivalentValue': { label: 'Mostrar valor equivalente semanal da API', help: 'Ligado por padrão. Mostra o valor equivalente semanal histórico da API em Todo o período e Comparar. É uma estimativa, não uma fatura nem uma franquia de assinatura.' },
     'showHeatmap': { label: 'Mostrar heatmap de tokens (aba Todo o período)', help: 'Desligado por padrão. Heatmap anual estilo GitHub; exporte SVG ou publique no seu perfil do GitHub.' },
     'showEfficiency': { label: 'Mostrar insights de eficiência', help: 'Desligado por padrão. Custo/mensagem, tokens/mensagem, economia de cache e a estimativa de aquecimento do cache.' },
     'showCostliestMessages': { label: 'Mostrar "10 mensagens mais caras"', help: 'Desligado por padrão. Ranqueia seus turnos mais caros; ao expandir mostra o prompt (seu próprio texto).' },
-    'enableShareCard': { label: 'Ativar cartão de compartilhamento de uso', help: 'Desligado por padrão. Um resumo SVG de uma página, configurável, para gerar e compartilhar.' },
+    'enableShareCard': { label: 'Ativar espaço de compartilhamento', help: 'Ligado por padrão. Mostra o espaço de compartilhamento em Comparar e o cartão do provedor. Desligar oculta a interface; exportar continua exigindo uma ação explícita.' },
     'enableSessionActions': { label: 'Ações de sessão (retomar e excluir)', help: 'Desligado por padrão. Mostra os botões Retomar e Excluir na aba Sessões. Ambos AGEM sobre o seu Claude Code (reabrir uma conversa / mover o log para a lixeira), ao contrário desta extensão somente leitura, então ficam opcionais juntos.' },
     'projectGroupingMode': { label: 'Agrupamento de projetos', help: 'git = por repositório · folder = nível superior · flat = cada cwd.' },
     'showCost': { label: 'Mostrar custo / tokens de hoje', help: '' },
@@ -3187,13 +3855,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'pauseDashboardRefresh': { label: 'Pausar atualização do dashboard', help: 'A barra de status continua atualizando; o dashboard só atualiza manualmente.' },
     'enableContentAnalysis': { label: 'Análise de conteúdo (aba Content)', help: 'Desative para pular a varredura de texto, que usa muita CPU.' },
     'analysis.calibrate': { label: 'Calibrar números de conteúdo', help: 'Ajusta as estimativas aos totais exatos de tokens cobrados.' },
-    'advice.apiKey': { label: 'Chave de API', help: 'Para o backend api. Permanece nas Configurações do VS Code.' },
+    'advice.effectiveness.enabled': { label: 'Ativar prévia de eficácia dos conselhos de IA', help: 'Desativado por padrão. Mostra evidências locais, prévia exata da solicitação BYOK, feedback e comparação; só envia após um clique separado.' },
+    'advice.apiKey': { label: 'Chave de API', help: 'Para o backend api. Fica apenas no VS Code SecretStorage, sem sincronização nem envio ao painel.' },
     'advice.apiFormat': { label: 'Formato da API', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'URL da API', help: 'Endpoint do backend api.' },
     'advice.model': { label: 'Modelo da API', help: '' },
     'advice.reasoningEffort': { label: 'Esforço de raciocínio (openai)', help: '' },
-    'advice.promptWindowDays': { label: 'Janela de amostragem de prompts (dias)', help: '' },
-    'advice.userContext': { label: 'Contexto pessoal/do projeto', help: 'Informação de fundo opcional; adiciona uma seção "Personalizado".' },
+    'advice.promptWindowDays': { label: 'Janela de evidências e prompts (dias)', help: '' },
+    'advice.userContext': { label: 'Contexto pessoal/do projeto', help: 'Opcional; só é enviado após consentimento separado de personalização e aparece por inteiro na prévia exata.' },
     'advice.optimizer.enabled': { label: 'Ativar o Otimizador de uso', help: 'Mostra o cartão opt-in do Optimizer na aba Content.' },
   },
   'id': {
@@ -3202,18 +3871,19 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'tokenDecimalPlaces': { label: 'Angka desimal token', help: 'Angka desimal untuk tampilan token ringkas (1.2M / 345.6K). Jumlah bilangan bulat penuh tidak terpengaruh.' },
     'compactNumbers': { label: 'Jumlah token ringkas', help: 'Tampilkan 1.2M / 345K, bukan angka penuh.' },
     'releaseAnnouncements': { label: 'Pengumuman rilis', help: 'Tampilkan sekali hal baru setelah ekstensi ditingkatkan.' },
+    'pricingBackend': { label: 'Sumber harga Claude', help: 'Pilih harga AWS Bedrock dalam-region saat Claude Code dirutekan melalui Bedrock.' },
     'codex.enabled': { label: 'Aktifkan Codex Beta', help: 'Baca agregat penggunaan yang aman untuk privasi dari log sesi Codex lokal.' },
     'codex.dataDirectory': { label: 'Direktori data Codex kustom', help: 'Kosong = CODEX_HOME, lalu ~/.codex. Berkas autentikasi tidak pernah dibaca.' },
     'codex.fileWatchSeconds': { label: 'Jeda penyegaran langsung Codex', help: 'Debounce tenang setelah perubahan JSONL Codex lokal. Mati menonaktifkan pemantauan.' },
     'codex.optimization.enabled': { label: 'Tampilkan optimasi perilaku Codex', help: 'Tampilkan metrik dan rekomendasi perilaku Codex yang lokal dan deterministik.' },
     'statusBarProvider': { label: 'Penyedia status bar', help: 'Otomatis memprioritaskan Claude saat keduanya memiliki data.' },
-    'codex.statusMetric': { label: 'Metrik status Codex', help: 'Penggunaan tanpa cache, token diproses, atau token output.' },
+    'codex.statusMetric': { label: 'Metrik status Codex', help: 'Penggunaan hari ini tanpa cache, token diproses, atau token output.' },
     'timezone': { label: 'Zona waktu untuk tanggal', help: 'Pilih zona umum atau offset UTC (semua offset tersedia), atau default sistem. Label menampilkan offset UTC saat ini.' },
     'showWeeklyEquivalentValue': { label: 'Tampilkan nilai ekuivalen API mingguan', help: 'Aktif secara default. Tampilkan riwayat nilai ekuivalen API mingguan di Sepanjang Waktu dan Perbandingan. Ini perkiraan, bukan tagihan atau jatah langganan.' },
     'showHeatmap': { label: 'Tampilkan heatmap token (tab Sepanjang Waktu)', help: 'Nonaktif secara default. Heatmap token tahunan bergaya GitHub di tab All; ekspor sebagai SVG atau publikasikan ke profil GitHub Anda.' },
     'showEfficiency': { label: 'Tampilkan wawasan efisiensi', help: 'Nonaktif secara default. Menambahkan biaya/pesan, token/pesan, penghematan cache, dan perkiraan cache warmth.' },
     'showCostliestMessages': { label: 'Tampilkan "10 pesan termahal"', help: 'Nonaktif secara default. Menampilkan giliran termahal; membuka detail menampilkan prompt-nya (teks Anda sendiri).' },
-    'enableShareCard': { label: 'Aktifkan share card penggunaan', help: 'Nonaktif secara default. Ringkasan SVG satu halaman yang dapat dikonfigurasi untuk dibuat dan dibagikan.' },
+    'enableShareCard': { label: 'Aktifkan ruang kerja berbagi', help: 'Aktif secara default. Menampilkan ruang kerja berbagi Perbandingan dan kartu penyedia. Menonaktifkannya menyembunyikan UI; ekspor tetap memerlukan tindakan eksplisit.' },
     'enableSessionActions': { label: 'Aksi sesi (Lanjutkan & Hapus)', help: 'Nonaktif secara default. Menampilkan tombol Lanjutkan dan Hapus di tab Sesi. Keduanya BERTINDAK pada Claude Code Anda (membuka ulang percakapan / memindahkan log ke sampah) — bertentangan dengan sifat baca-saja extension ini, jadi tetap opsional bersama.' },
     'projectGroupingMode': { label: 'Pengelompokan proyek', help: 'git = per repo · folder = level teratas · flat = setiap cwd.' },
     'showCost': { label: 'Tampilkan biaya / token hari ini', help: '' },
@@ -3234,13 +3904,14 @@ const SETTINGS_I18N: Partial<Record<SupportedLanguage, Record<string, { label: s
     'dashboardAutoRefresh': { label: 'Penyegaran otomatis dashboard', help: 'Segarkan dashboard secara otomatis saat ada penggunaan baru. Nonaktif = hanya penyegaran manual (status bar tetap diperbarui).' },
     'enableContentAnalysis': { label: 'Analisis konten (tab Konten)', help: 'Nonaktifkan untuk melewati pemindaian teks yang berat bagi CPU.' },
     'analysis.calibrate': { label: 'Kalibrasi angka konten', help: 'Skalakan perkiraan ke total token yang benar-benar ditagih.' },
-    'advice.apiKey': { label: 'API key', help: 'Untuk backend api. Tetap berada di Pengaturan VS Code.' },
+    'advice.effectiveness.enabled': { label: 'Aktifkan pratinjau efektivitas saran AI', help: 'Nonaktif secara default. Menampilkan bukti lokal, pratinjau permintaan BYOK yang persis, umpan balik, dan perbandingan; hanya mengirim setelah klik terpisah.' },
+    'advice.apiKey': { label: 'API key', help: 'Untuk backend api. Hanya disimpan di VS Code SecretStorage, tidak disinkronkan atau dikirim ke dashboard.' },
     'advice.apiFormat': { label: 'Format API', help: 'anthropic = /v1/messages · openai = chat-completions.' },
     'advice.apiUrl': { label: 'URL API', help: 'Endpoint untuk backend api.' },
     'advice.model': { label: 'Model API', help: '' },
     'advice.reasoningEffort': { label: 'Effort reasoning (openai)', help: '' },
-    'advice.promptWindowDays': { label: 'Jendela sampel prompt (hari)', help: '' },
-    'advice.userContext': { label: 'Konteks pribadi/proyek', help: 'Latar belakang opsional; menambahkan bagian "Personalisasi".' },
+    'advice.promptWindowDays': { label: 'Jendela bukti dan prompt (hari)', help: '' },
+    'advice.userContext': { label: 'Konteks pribadi/proyek', help: 'Opsional; hanya dikirim setelah persetujuan personalisasi prompt terpisah dan ditampilkan penuh dalam pratinjau persis.' },
     'advice.optimizer.enabled': { label: 'Aktifkan Usage Optimizer', help: 'Tampilkan kartu Optimizer opsional di tab Konten.' },
   },
 };
diff --git a/src/localDataControls.ts b/src/localDataControls.ts
new file mode 100644
index 00000000..f619eb4b
--- /dev/null
+++ b/src/localDataControls.ts
@@ -0,0 +1,245 @@
+import type { QuotaObservationStoreV2 } from './quotaObservationStore';
+import type { UsageProvider } from './providers/providerTypes';
+
+/**
+ * Public, value-free description of one class of local data. Inventory rows
+ * deliberately contain no path, account fingerprint, setting value, or raw
+ * provider payload.
+ */
+export interface LocalDataInventoryRow {
+  id: string;
+  category: string;
+  locationClass: string;
+  schema: string;
+  approximateBytes: number | null;
+  itemCount: number | null;
+  oldestAt: number | null;
+  newestAt: number | null;
+  networkInteraction: string;
+  clearability: string;
+}
+
+export interface LocalDataClientSummary {
+  uiPreferenceKeys: number;
+  webviewStateFields: number;
+  sharingPreferenceKeys: number;
+}
+
+export interface LocalDataQuotaScopeOption {
+  token: string;
+  label: string;
+  provider: UsageProvider | 'all';
+  itemCount: number;
+  oldestAt: number | null;
+  newestAt: number | null;
+}
+
+export interface LocalDataInventory {
+  schemaVersion: 1;
+  generatedAt: number;
+  rows: LocalDataInventoryRow[];
+  quotaScopes: LocalDataQuotaScopeOption[];
+  exclusions: string[];
+}
+
+export type LocalDataAction =
+  | 'rebuild-codex-index'
+  | 'clear-quota-history'
+  | 'clear-advice-data'
+  | 'reset-ui-state'
+  | 'reset-sharing-preferences'
+  | 'clear-byok-secret'
+  | 'clear-all-derived-data';
+
+const LOCAL_DATA_ACTIONS: readonly LocalDataAction[] = [
+  'rebuild-codex-index',
+  'clear-quota-history',
+  'clear-advice-data',
+  'reset-ui-state',
+  'reset-sharing-preferences',
+  'clear-byok-secret',
+  'clear-all-derived-data',
+];
+
+export function isLocalDataAction(value: unknown): value is LocalDataAction {
+  return typeof value === 'string' &&
+    (LOCAL_DATA_ACTIONS as readonly string[]).includes(value);
+}
+
+export type LocalDataClientAction =
+  | 'reset-ui-state'
+  | 'reset-sharing-preferences'
+  | 'clear-all-client-state';
+
+export interface LocalDataActionResult {
+  ok: boolean;
+  cancelled?: boolean;
+  message: string;
+  clientAction?: LocalDataClientAction;
+}
+
+export interface ResolvedQuotaScope {
+  provider?: UsageProvider;
+  accountFingerprint?: string;
+}
+
+export const LOCAL_DATA_SOURCE_EXCLUSIONS = [
+  'Claude provider-owned source logs',
+  'Codex provider-owned source logs',
+  'provider-owned OAuth credentials and cookies',
+  'external account quotas and subscription state',
+] as const;
+
+/** Exact globalState prefixes owned by this extension and eligible for clear-all. */
+export const LOCAL_DATA_GLOBAL_STATE_PREFIXES = [
+  'ccu.usageLimits.',
+  'ccu.weeklyQuotaHistory.v1.',
+] as const;
+
+export const LOCAL_DATA_PENDING_CLIENT_RESET_KEY =
+  'ccu.localData.pendingClientReset.v1' as const;
+
+/** Exact non-setting globalState keys eligible for clear-all. */
+export const LOCAL_DATA_GLOBAL_STATE_KEYS = [
+  'ccu.adviceEffectiveness.localState',
+  'ccu.codex.backgroundWork.v1',
+  'ccu.codex.machineSalt',
+  'ccu.heatmapPath',
+  'ccu.heatmapRepo',
+  'ccu.lastSeenVersion',
+  LOCAL_DATA_PENDING_CLIENT_RESET_KEY,
+  'ccu.migrated.dashboardAutoRefresh',
+  'ccu.migrated.showScopedWeekly',
+  'ccu.quota.fingerprintSalt.v1',
+  'ccu.quota.migratedCodexIndex.v2',
+  'ccu.settingsMigrated.v1',
+] as const;
+
+/** Known, released advice-ledger keys retired by the versioned v3 ledger. */
+export const LEGACY_ADVICE_LOCAL_STATE_KEYS: readonly string[] = [
+  'claudeCodeUsage.adviceEffectiveness.feedback.v1',
+];
+
+export const LOCAL_DATA_ACTION_TARGETS: Record<LocalDataAction, readonly string[]> = {
+  'rebuild-codex-index': [
+    'globalStorageUri/codex-index-v1.json',
+    'exact codex-index-v1.corrupt-<timestamp>-<pid>.json recovery files',
+    'exact codex-index-v1.json.tmp-<pid>-<uuid> interrupted-write files',
+    'runtime Codex derived views (then rebuilt from read-only source logs)',
+  ],
+  'clear-quota-history': [
+    'selected rows in globalStorageUri/quota-observations-v2.json; an all-clear retains one valid empty canonical document',
+    'exact quota-observations-v2.json quarantine/interrupted-write recovery files on an all-clear',
+    'matching legacy ccu.usageLimits.* and ccu.weeklyQuotaHistory.v1.* migration inputs when clearing all Claude history',
+    'ccu.quota.migratedCodexIndex.v2 marker when clearing Codex history',
+  ],
+  'clear-advice-data': [
+    'ccu.adviceEffectiveness.localState',
+    'claudeCodeUsage.adviceEffectiveness.feedback.v1',
+  ],
+  'reset-ui-state': [
+    'P10 Webview state and allowlisted UI localStorage keys',
+  ],
+  'reset-sharing-preferences': [
+    'ccu.setting.showHeatmap and ccu.setting.enableShareCard',
+    'ccu.combinedHeatmap.title, .range, and .privacyPreview Webview keys',
+    'ccu.heatmapRepo and ccu.heatmapPath destination strings',
+    'in-memory share-card SVG/configuration preview',
+  ],
+  'clear-byok-secret': [
+    'SecretStorage claudeCodeUsage.secret.advice.apiKey',
+    'legacy ccu.setting.advice.apiKey and currently inspectable configuration scopes',
+  ],
+  'clear-all-derived-data': [
+    'P1 exact Codex index/recovery/interrupted-write file family',
+    'P2 exact quota-observation/quarantine/interrupted-write file family, replaced by one valid empty canonical document',
+    'P3/P4 ccu.usageLimits.* and ccu.weeklyQuotaHistory.v1.* migration inputs',
+    'P6 exact catalogued ccu.setting.<key> names, worker/release/migration keys, pending client-reset marker, and currently inspectable configuration scopes',
+    'P7 ccu.codex.machineSalt and ccu.quota.fingerprintSalt.v1',
+    'P8 SecretStorage claudeCodeUsage.secret.advice.apiKey and exact plaintext migration locations',
+    'P9 ccu.adviceEffectiveness.localState and claudeCodeUsage.adviceEffectiveness.feedback.v1',
+    'P10 four allowlisted UI localStorage keys plus Webview state',
+    'P11 two sharing settings, three sharing localStorage keys, two destination keys, and in-memory preview',
+  ],
+};
+
+export function finiteTimestampRange(
+  values: readonly (number | null | undefined)[],
+): { oldestAt: number | null; newestAt: number | null } {
+  const timestamps = values.filter(
+    (value): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0,
+  );
+  return {
+    oldestAt: timestamps.length > 0 ? Math.min(...timestamps) : null,
+    newestAt: timestamps.length > 0 ? Math.max(...timestamps) : null,
+  };
+}
+
+export function approximateJsonBytes(value: unknown): number | null {
+  try {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? null : Buffer.byteLength(serialized, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export interface QuotaEpochGroup {
+  provider: UsageProvider;
+  accountFingerprint: string;
+  itemCount: number;
+  oldestAt: number | null;
+  newestAt: number | null;
+}
+
+/** Internal-only grouping. Callers must replace fingerprints with random tokens. */
+export function groupQuotaAccountEpochs(
+  store: QuotaObservationStoreV2,
+): QuotaEpochGroup[] {
+  const groups = new Map<string, QuotaEpochGroup>();
+  for (const observation of store.observations) {
+    const key = `${observation.provider}\0${observation.accountFingerprint}`;
+    const current = groups.get(key) ?? {
+      provider: observation.provider,
+      accountFingerprint: observation.accountFingerprint,
+      itemCount: 0,
+      oldestAt: null,
+      newestAt: null,
+    };
+    current.itemCount += 1;
+    current.oldestAt = current.oldestAt === null
+      ? observation.observedAt
+      : Math.min(current.oldestAt, observation.observedAt);
+    current.newestAt = current.newestAt === null
+      ? observation.observedAt
+      : Math.max(current.newestAt, observation.observedAt);
+    groups.set(key, current);
+  }
+  return [...groups.values()].sort((left, right) =>
+    left.provider.localeCompare(right.provider) ||
+    left.accountFingerprint.localeCompare(right.accountFingerprint),
+  );
+}
+
+export function shouldClearQuotaObservation(
+  observation: QuotaObservationStoreV2['observations'][number],
+  scope: ResolvedQuotaScope,
+): boolean {
+  return (scope.provider === undefined || observation.provider === scope.provider) &&
+    (scope.accountFingerprint === undefined ||
+      observation.accountFingerprint === scope.accountFingerprint);
+}
+
+export function localDataActionTitle(action: LocalDataAction, locale: string): string {
+  const zh = locale === 'zh-CN';
+  const labels: Record<LocalDataAction, [string, string]> = {
+    'rebuild-codex-index': ['Rebuild Codex derived index', '重建 Codex 派生索引'],
+    'clear-quota-history': ['Clear quota observation history', '清除额度观测历史'],
+    'clear-advice-data': ['Clear advice data', '清除建议数据'],
+    'reset-ui-state': ['Reset dashboard UI state', '重置仪表板界面状态'],
+    'reset-sharing-preferences': ['Reset sharing preferences', '重置分享偏好'],
+    'clear-byok-secret': ['Clear BYOK advice secret', '清除 BYOK 建议密钥'],
+    'clear-all-derived-data': ['Clear all extension-derived data', '清除全部插件派生数据'],
+  };
+  return labels[action][zh ? 1 : 0];
+}
diff --git a/src/optimizerRequest.ts b/src/optimizerRequest.ts
new file mode 100644
index 00000000..94f5d3d7
--- /dev/null
+++ b/src/optimizerRequest.ts
@@ -0,0 +1,133 @@
+import type {
+  PreparedAiInvocation,
+  PreparedAiTransportRequest,
+} from './adviceEffectiveness/preparedRequest';
+import { prepareAiInvocation } from './adviceEffectiveness/preparedRequest';
+import type { HttpResponse } from './httpClient';
+import { sendPreparedModelRequest } from './advisor';
+
+export interface PrepareOptimizerInvocationInput {
+  apiFormat: 'anthropic' | 'openai';
+  apiUrl: string;
+  model: string;
+  reasoningEffort?: string;
+  systemPrompt: string;
+  draft: string;
+  sourceRevision: string;
+  consentGeneration: number;
+  createdAtEpochMs: number;
+  timeoutMs?: number;
+}
+
+export interface PreparedOptimizerSendOptions {
+  apiKey: string;
+  expectedSourceRevision?: string;
+  expectedConsentGeneration?: number;
+  signal?: AbortSignal;
+  transport?: (request: PreparedAiTransportRequest) => Promise<HttpResponse>;
+}
+
+export type PreparedOptimizerResult =
+  | { ok: true; value: { prompt: string; settings: string } }
+  | {
+      ok: false;
+      code: 'invalid-prepared-request' | 'invalid-output' | 'transport-error';
+      issues: string[];
+    };
+
+export function prepareOptimizerInvocation(
+  input: PrepareOptimizerInvocationInput,
+): PreparedAiInvocation {
+  return prepareAiInvocation({
+    kind: 'optimizer',
+    apiFormat: input.apiFormat,
+    apiUrl: input.apiUrl,
+    model: input.model,
+    ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
+    systemPrompt: input.systemPrompt,
+    userContent: input.draft,
+    dataMode: 'user-draft-only',
+    sourceRevision: input.sourceRevision,
+    consentGeneration: input.consentGeneration,
+    createdAtEpochMs: input.createdAtEpochMs,
+    ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+  });
+}
+
+/** Strict marker and three-line settings parser; never surfaces malformed text. */
+export function parseStrictOptimizerOutput(
+  raw: string,
+): { prompt: string; settings: string } | undefined {
+  const text = raw.trim();
+  const promptMarker = '===PROMPT===';
+  const settingsMarker = '===SETTINGS===';
+  if (!text.startsWith(`${promptMarker}\n`)) return undefined;
+  const settingsIndex = text.indexOf(`\n${settingsMarker}\n`);
+  if (settingsIndex <= promptMarker.length) return undefined;
+  if (
+    text.indexOf(promptMarker, promptMarker.length) !== -1 ||
+    text.indexOf(settingsMarker, settingsIndex + settingsMarker.length + 2) !== -1
+  ) {
+    return undefined;
+  }
+  const prompt = text.slice(promptMarker.length, settingsIndex).trim();
+  const settings = text
+    .slice(settingsIndex + settingsMarker.length + 2)
+    .trim();
+  if (!prompt || prompt.length > 100_000 || !settings || settings.length > 10_000) {
+    return undefined;
+  }
+  const lines = settings.split(/\r?\n/);
+  if (lines.length !== 3) return undefined;
+  const reason = String.raw`\s+—\s+\S.{0,1000}`;
+  if (!new RegExp(`^Effort: (low|medium|high|max|ultracode)${reason}$`).test(lines[0])) {
+    return undefined;
+  }
+  if (!new RegExp(`^Thinking: (on|off)${reason}$`).test(lines[1])) {
+    return undefined;
+  }
+  if (!new RegExp(`^Model: [A-Za-z0-9._/-]{1,128}${reason}$`).test(lines[2])) {
+    return undefined;
+  }
+  return { prompt, settings };
+}
+
+export async function requestPreparedOptimizer(
+  prepared: PreparedAiInvocation,
+  options: PreparedOptimizerSendOptions,
+): Promise<PreparedOptimizerResult> {
+  if (prepared.kind !== 'optimizer' || prepared.dataMode !== 'user-draft-only') {
+    return {
+      ok: false,
+      code: 'invalid-prepared-request',
+      issues: ['prepared request is not an optimizer request'],
+    };
+  }
+  let raw: string;
+  try {
+    raw = await sendPreparedModelRequest(prepared, options.apiKey, {
+      ...(options.expectedSourceRevision === undefined
+        ? {}
+        : { expectedSourceRevision: options.expectedSourceRevision }),
+      ...(options.expectedConsentGeneration === undefined
+        ? {}
+        : { expectedConsentGeneration: options.expectedConsentGeneration }),
+      ...(options.signal ? { signal: options.signal } : {}),
+      ...(options.transport ? { transport: options.transport } : {}),
+    });
+  } catch {
+    return {
+      ok: false,
+      code: 'transport-error',
+      issues: ['configured BYOK transport failed'],
+    };
+  }
+  const parsed = parseStrictOptimizerOutput(raw);
+  return parsed
+    ? { ok: true, value: parsed }
+    : {
+        ok: false,
+        code: 'invalid-output',
+        issues: ['optimizer output did not match the strict response contract'],
+      };
+}
diff --git a/src/pricing.ts b/src/pricing.ts
index 191cd0d4..74919fe0 100644
--- a/src/pricing.ts
+++ b/src/pricing.ts
@@ -8,6 +8,20 @@ import * as https from 'https';
 
 import { ModelPricing } from './types';
 
+export type PricingBackend = 'anthropic' | 'aws-bedrock-in-region';
+
+let pricingBackend: PricingBackend = 'anthropic';
+
+/** Select the price table used for Claude model cost calculations. */
+export function setPricingBackend(backend: PricingBackend): void {
+  pricingBackend = backend === 'aws-bedrock-in-region' ? backend : 'anthropic';
+}
+
+/** Return the currently selected Claude pricing backend. */
+export function getPricingBackend(): PricingBackend {
+  return pricingBackend;
+}
+
 export interface TokenUsage {
   input_tokens: number;
   output_tokens: number;
@@ -60,7 +74,8 @@ const MILL = 1_000_000;
 // Anthropic / Claude pricing
 // Verified 2026-05-21 — https://platform.claude.com/docs/en/about-claude/pricing
 //
-// Cache pricing follows Anthropic's standard multipliers vs base input price:
+// Cache pricing follows Anthropic's standard multipliers vs base input price,
+// except where a model-specific rate below says otherwise:
 //   - 5-minute cache write : 1.25x base input  (what Claude Code writes by default)
 //   - 1-hour cache write   : 2.00x base input  (used when a 1h TTL is requested)
 //   - cache read (hit)     : 0.10x base input
@@ -71,6 +86,17 @@ const MILL = 1_000_000;
 // falls back to the 5-minute rate (what Claude Code writes by default).
 // =====================================================================
 
+// Fable 5.1 / Mythos 5.1 — frontier tier ($10 / $50), verified 2026-09-06.
+// Cache reads are the model-specific exception: 0.025x input ($0.25/MTok).
+// https://platform.claude.com/docs/en/models/fable-5-1/overview
+const FABLE_5_1: ModelPricing = {
+  input_cost_per_token: 10 / MILL,
+  output_cost_per_token: 50 / MILL,
+  cache_creation_input_token_cost: 12.5 / MILL,
+  cache_creation_1h_input_token_cost: 20 / MILL,
+  cache_read_input_token_cost: 0.25 / MILL,
+};
+
 // Fable 5 / Mythos 5 — frontier tier ($10 / $50), verified 2026-06-09
 // https://platform.claude.com/docs/en/about-claude/pricing
 const FABLE_5: ModelPricing = {
@@ -126,6 +152,93 @@ const HAIKU_35: ModelPricing = {
   cache_read_input_token_cost: 0.08 / MILL,
 };
 
+// AWS Bedrock in-region, on-demand pricing (USD per 1M tokens).
+//
+// The Bedrock table also publishes batch prices. Claude Code's normal
+// pay-as-you-go inference is not batch inference, so only the standard input /
+// output rates and the cache rates are used here.
+const BEDROCK_OPUS_5: ModelPricing = {
+  input_cost_per_token: 5.5 / MILL,
+  output_cost_per_token: 27.5 / MILL,
+  cache_creation_input_token_cost: 6.875 / MILL,
+  cache_creation_1h_input_token_cost: 11 / MILL,
+  cache_read_input_token_cost: 0.55 / MILL,
+};
+
+// AWS Bedrock Claude Sonnet 4.5 / 4.6 in-region, on-demand pricing.
+const BEDROCK_SONNET_45_PLUS: ModelPricing = {
+  input_cost_per_token: 3.3 / MILL,
+  output_cost_per_token: 16.5 / MILL,
+  cache_creation_input_token_cost: 4.125 / MILL,
+  cache_creation_1h_input_token_cost: 6.6 / MILL,
+  cache_read_input_token_cost: 0.33 / MILL,
+};
+
+// Sonnet 5's $2/$10 launch promotion ended on 2026-08-31. The standard
+// in-region rates now match the Sonnet 4.5/4.6 tier.
+const BEDROCK_SONNET_5: ModelPricing = {
+  input_cost_per_token: 3.3 / MILL,
+  output_cost_per_token: 16.5 / MILL,
+  cache_creation_input_token_cost: 4.125 / MILL,
+  cache_creation_1h_input_token_cost: 6.6 / MILL,
+  cache_read_input_token_cost: 0.33 / MILL,
+};
+
+const BEDROCK_HAIKU_45: ModelPricing = {
+  input_cost_per_token: 1.1 / MILL,
+  output_cost_per_token: 5.5 / MILL,
+  cache_creation_input_token_cost: 1.375 / MILL,
+  cache_creation_1h_input_token_cost: 2.2 / MILL,
+  cache_read_input_token_cost: 0.11 / MILL,
+};
+
+/**
+ * Resolve the user-supplied Claude model label to an AWS Bedrock model family.
+ *
+ * Claude Code may log a short model name (`claude-sonnet-5`) even when the
+ * request was routed through Bedrock. Bedrock itself may expose a regional
+ * inference-profile prefix such as `us.anthropic.`. In the explicit Bedrock
+ * mode both forms must use the same in-region table.
+ */
+function getBedrockPricing(modelName: string): ModelPricing | null {
+  const name = modelName
+    .toLowerCase()
+    .replace(/\[[^\]]*\]\s*$/, '')
+    .replace(/^(?:(?:global|us|eu|apac|in)\.)?anthropic[./]/, '')
+    // Some integrations display the version separator as "." or "_", while
+    // Claude Code's native IDs use "-". Treat those labels as the same
+    // Bedrock model family so pricing is not silently reduced to Anthropic's
+    // generic Sonnet fallback.
+    .replace(/[._]/g, '-')
+    .replace(/\s+/g, '-');
+
+  if (name.includes('claude-opus-5') || name.includes('opus-5')) {
+    return BEDROCK_OPUS_5;
+  }
+  if (
+    name.includes('claude-opus-4-8') ||
+    name.includes('claude-opus-4-7') ||
+    name.includes('claude-opus-4-6') ||
+    name.includes('claude-opus-4-5') ||
+    name.includes('opus-4-8') ||
+    name.includes('opus-4-7') ||
+    name.includes('opus-4-6') ||
+    name.includes('opus-4-5')
+  ) {
+    return BEDROCK_OPUS_5;
+  }
+  if (name.includes('claude-sonnet-5') || name.includes('sonnet-5')) {
+    return BEDROCK_SONNET_5;
+  }
+  if (name.includes('claude-sonnet-4-6') || name.includes('claude-sonnet-4-5')) {
+    return BEDROCK_SONNET_45_PLUS;
+  }
+  if (name.includes('claude-haiku-4-5') || name.includes('haiku-4-5') || name.includes('haiku-4.5')) {
+    return BEDROCK_HAIKU_45;
+  }
+  return null;
+}
+
 /**
  * Build pricing for non-Anthropic providers, which usually only publish an
  * input price, an output price, and an optional discounted "cached input" price.
@@ -133,18 +246,32 @@ const HAIKU_35: ModelPricing = {
  * @param outputPerM      Output price per 1M tokens (USD)
  * @param cachedInputPerM Cached/'cache hit' input price per 1M tokens (USD).
  *                        Defaults to 10% of the input price when omitted.
+ * @param cacheWritePerM  Cache-write price per 1M tokens (USD). Most providers
+ *                        do not expose a separate write rate, so it defaults to
+ *                        the ordinary input price.
  */
-function priced(inputPerM: number, outputPerM: number, cachedInputPerM?: number): ModelPricing {
+function priced(
+  inputPerM: number,
+  outputPerM: number,
+  cachedInputPerM?: number,
+  cacheWritePerM?: number,
+): ModelPricing {
   return {
     input_cost_per_token: inputPerM / MILL,
     output_cost_per_token: outputPerM / MILL,
-    // These providers do not charge extra to *write* a cache entry — a cache-write
-    // token is billed like a normal input token.
-    cache_creation_input_token_cost: inputPerM / MILL,
+    cache_creation_input_token_cost:
+      (cacheWritePerM != null ? cacheWritePerM : inputPerM) / MILL,
     cache_read_input_token_cost: (cachedInputPerM != null ? cachedInputPerM : inputPerM * 0.1) / MILL,
   };
 }
 
+// GPT-6 Astra Standard, short-context rates. Inputs above 272K receive a
+// request-wide long-context uplift, but the Codex aggregate index cannot prove
+// that per-request threshold, so the existing API-equivalent view deliberately
+// excludes it as an unavailable request-level surcharge.
+// https://developers.openai.com/api/docs/models/gpt-6-astra
+const GPT_6_ASTRA = priced(10, 50, 1, 12.5);
+
 // =====================================================================
 // Non-Claude reference pricing (USD per 1M tokens)
 // Last checked 2026-05. OpenAI / Gemini / DeepSeek from vendor docs; Chinese
@@ -152,7 +279,11 @@ function priced(inputPerM: number, outputPerM: number, cachedInputPerM?: number)
 // — treat these as estimates and re-verify before relying on them.
 // =====================================================================
 const NON_CLAUDE_PRICING: Record<string, ModelPricing> = {
-  // --- OpenAI --- https://openai.com/api/pricing/
+  // --- OpenAI --- https://developers.openai.com/api/docs/pricing
+  'gpt-6-astra': GPT_6_ASTRA,
+  // Common proxy-qualified spelling; the official API model id remains the
+  // unprefixed `gpt-6-astra` above.
+  'openai/gpt-6-astra': GPT_6_ASTRA,
   // GPT-5.6 Codex tiers — verified 2026-08-22 against the official model
   // catalog. These exact entries are also used by the weekly API-equivalent
   // value audit; unknown Codex model labels are intentionally not inferred.
@@ -233,6 +364,10 @@ const NON_CLAUDE_PRICING: Record<string, ModelPricing> = {
 // so direct lookups stay fast; anything not listed is resolved by getModelPricing()'s
 // family-aware fallback below.
 const MODEL_PRICING: Record<string, ModelPricing> = {
+  // Claude Fable 5.1 / Mythos 5.1 (2026-09) — reduced cache-read rate.
+  'claude-fable-5-1': FABLE_5_1,
+  'claude-mythos-5-1': FABLE_5_1,
+
   // Claude Fable 5 / Mythos 5 (2026-06) — frontier tier
   'claude-fable-5': FABLE_5,
   'claude-mythos-5': FABLE_5,
@@ -305,6 +440,9 @@ function inferPricingByFamily(modelName: string): { pricing: ModelPricing; famil
 
   // --- Anthropic / Claude ---
   if (name.includes('fable') || name.includes('mythos')) {
+    if (/\b(?:fable|mythos)[._ -]+5[._ -]+1(?:\b|[._ -])/.test(name)) {
+      return { pricing: FABLE_5_1, family: 'Fable 5.1 (frontier tier)' };
+    }
     return { pricing: FABLE_5, family: 'Fable 5 (frontier tier)' };
   }
   if (name.includes('haiku')) {
@@ -323,6 +461,9 @@ function inferPricingByFamily(modelName: string): { pricing: ModelPricing; famil
   }
 
   // --- Other providers ---
+  if (name.includes('gpt-6-astra')) {
+    return { pricing: GPT_6_ASTRA, family: 'OpenAI GPT-6 Astra' };
+  }
   if (name.includes('gpt') || /(^|[^a-z])o[1-9]([^a-z]|$)/.test(name)) {
     return { pricing: NON_CLAUDE_PRICING['gpt-5'], family: 'OpenAI GPT' };
   }
@@ -373,6 +514,17 @@ export function getModelPricing(modelName: string | undefined): ModelPricing | n
   // pricing applies.
   modelName = modelName.replace(/\[[^\]]*\]\s*$/, '');
 
+  // A Bedrock route cannot be inferred reliably from the model label alone:
+  // Claude Code commonly records just "claude-sonnet-5". When the user
+  // explicitly selects Bedrock, its known Claude rates must therefore take
+  // precedence over both the generic Anthropic table and LiteLLM overrides.
+  if (pricingBackend === 'aws-bedrock-in-region') {
+    const bedrockPricing = getBedrockPricing(modelName);
+    if (bedrockPricing) {
+      return bedrockPricing;
+    }
+  }
+
   // Try different variation matches (similar to ccusage logic)
   const variations = [modelName, `anthropic/${modelName}`, `claude-3-5-${modelName}`, `claude-3-${modelName}`, `claude-${modelName}`];
 
@@ -416,6 +568,12 @@ export function getExactModelPricing(modelName: string | undefined): ModelPricin
     return null;
   }
   const base = modelName.replace(/\[[^\]]*\]\s*$/, '');
+  if (pricingBackend === 'aws-bedrock-in-region') {
+    const bedrockPricing = getBedrockPricing(base);
+    if (bedrockPricing) {
+      return bedrockPricing;
+    }
+  }
   const variations = [
     base,
     `anthropic/${base}`,
diff --git a/src/promptOrigin.ts b/src/promptOrigin.ts
new file mode 100644
index 00000000..253e4e3f
--- /dev/null
+++ b/src/promptOrigin.ts
@@ -0,0 +1,40 @@
+import { FrameworkOverheadKind } from './types';
+
+export type PromptTextOrigin = 'user-authored' | FrameworkOverheadKind;
+
+export interface PromptOriginInput {
+  text: string;
+  isMeta?: boolean;
+  isSidechain?: boolean;
+  isSubagentFile?: boolean;
+}
+
+/**
+ * Classify a user-role text block without retaining it. This deliberately uses
+ * structural markers only; it does not attempt semantic topic or writing-
+ * quality analysis.
+ */
+export function classifyPromptTextOrigin(input: PromptOriginInput): PromptTextOrigin {
+  if (input.isSubagentFile) return 'subagent-dispatch';
+  if (input.isMeta) return 'meta';
+  if (input.isSidechain) return 'sidechain';
+
+  const text = input.text.trim();
+  if (
+    /^\[Request interrupted/i.test(text) ||
+    /^This session is being continued from a previous conversation/i.test(text) ||
+    /<system-reminder(?:\s|>)/i.test(text)
+  ) {
+    return 'system-reminder';
+  }
+  if (
+    /<command-(?:name|message)>/i.test(text) ||
+    /<local-command-(?:stdout|caveat)>/i.test(text)
+  ) {
+    return 'command-echo';
+  }
+  // Do not classify arbitrary kebab-case custom elements as framework text.
+  // Only the reviewed Claude Code markers above are accepted; unknown markup
+  // such as <my-component> may be content the user intentionally pasted.
+  return 'user-authored';
+}
diff --git a/src/providers/codex/codexDedup.ts b/src/providers/codex/codexDedup.ts
index 228ecec4..0fa60b0b 100644
--- a/src/providers/codex/codexDedup.ts
+++ b/src/providers/codex/codexDedup.ts
@@ -37,11 +37,28 @@ function bucketSignature(
     .map(([key, tokens]) => [key, tokenSignature(tokens)]);
 }
 
+function structuralSignature(structural: {
+  patchCalls: number;
+  toolCalls: number;
+  postPatchToolCalls: number;
+  compactCount: number;
+  taskCompleteCount: number;
+}): StableNumber[] {
+  return [
+    stableNumber(structural.patchCalls),
+    stableNumber(structural.toolCalls),
+    stableNumber(structural.postPatchToolCalls),
+    stableNumber(structural.compactCount),
+    stableNumber(structural.taskCompleteCount),
+  ];
+}
+
 function contributionSignature(contribution: CodexFileContribution): string {
   const { aggregate } = contribution;
   const { session, structural } = aggregate;
   return JSON.stringify([
     tokenSignature(aggregate.total),
+    bucketSignature(aggregate.byDay),
     bucketSignature(aggregate.byModel),
     bucketSignature(aggregate.byEffort),
     session.parentSessionKey ?? null,
@@ -49,11 +66,7 @@ function contributionSignature(contribution: CodexFileContribution): string {
     session.role,
     stableNumber(session.startedAt),
     stableNumber(session.endedAt),
-    stableNumber(structural.patchCalls),
-    stableNumber(structural.toolCalls),
-    stableNumber(structural.postPatchToolCalls),
-    stableNumber(structural.compactCount),
-    stableNumber(structural.taskCompleteCount),
+    structuralSignature(structural),
   ]);
 }
 
diff --git a/src/providers/codex/codexFilePassPool.ts b/src/providers/codex/codexFilePassPool.ts
index f5d7a62a..5560a7fa 100644
--- a/src/providers/codex/codexFilePassPool.ts
+++ b/src/providers/codex/codexFilePassPool.ts
@@ -67,6 +67,9 @@ export class CodexFilePassPool {
   private workers: WorkerSlot[] = [];
   private active: ActiveBatch | null = null;
   private disposed = false;
+  private readonly pendingTerminations = new Set<Promise<void>>();
+  private terminationFailure: unknown = null;
+  private disposal: Promise<void> | null = null;
 
   readonly run: CodexFilePassBatchRunner = async (
     tasks,
@@ -121,19 +124,19 @@ export class CodexFilePassPool {
     this.workerFactory = workerFactory;
   }
 
-  async dispose(): Promise<void> {
+  dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
     this.disposed = true;
-    if (this.active) {
-      this.failActive(new CodexIndexCancelledError());
-    }
-    const workers = this.workers.splice(0);
-    await Promise.all(workers.map(async ({ worker }) => {
-      try {
-        await worker.terminate();
-      } catch {
-        // Best-effort local worker cleanup.
+    this.disposal = (async () => {
+      if (this.active) {
+        this.failActive(new CodexIndexCancelledError());
       }
-    }));
+      const workers = this.workers.splice(0);
+      for (const { worker } of workers) this.trackTermination(worker);
+      await Promise.all([...this.pendingTerminations]);
+      if (this.terminationFailure) throw this.terminationFailure;
+    })();
+    return this.disposal;
   }
 
   private ensureWorkers(count: number): void {
@@ -249,8 +252,25 @@ export class CodexFilePassPool {
     this.active = null;
     const workers = this.workers.splice(0);
     for (const { worker } of workers) {
-      void worker.terminate();
+      this.trackTermination(worker);
     }
     active.reject(error);
   }
+
+  private trackTermination(worker: CodexFilePassWorkerLike): void {
+    let pending!: Promise<void>;
+    pending = Promise.resolve()
+      .then(() => worker.terminate())
+      .then(() => undefined)
+      .catch((error: unknown) => {
+        this.terminationFailure ??= error;
+        throw error;
+      })
+      .finally(() => this.pendingTerminations.delete(pending));
+    this.pendingTerminations.add(pending);
+    // Disposal consumes and propagates this failure. Attach a side handler now
+    // so a fast rejection cannot become unhandled before the pool reaches its
+    // finally/dispose path.
+    void pending.catch(() => undefined);
+  }
 }
diff --git a/src/providers/codex/codexIdentity.ts b/src/providers/codex/codexIdentity.ts
index e3359279..3013bd55 100644
--- a/src/providers/codex/codexIdentity.ts
+++ b/src/providers/codex/codexIdentity.ts
@@ -78,10 +78,10 @@ function redactAbsolutePaths(value: string): string {
     .replace(/file:\/\/\/[^\s"'`<>]+/gi, '[path]')
     .replace(/[a-z]:[\\/][^\s"'`<>]+/gi, '[path]')
     .replace(
-      /(^|[^:/])\/(?:[^\s/"'`<>]+\/)+[^\s"'`<>]+/g,
+      /(^|[^/])\/(?:[^\s/"'`<>]+\/)+[^\s"'`<>]+/g,
       '$1[path]',
     )
-    .replace(/(^|[\s("'`])\/[^\s"'`<>]+/g, '$1[path]')
+    .replace(/(^|[\s("'`:])\/[^\s"'`<>]+/g, '$1[path]')
     .replace(/(^|[\s("'`])\\\\[^\s"'`<>]+/g, '$1[path]');
 }
 
diff --git a/src/providers/codex/codexIndex.ts b/src/providers/codex/codexIndex.ts
index 93cfc4dd..d1386685 100644
--- a/src/providers/codex/codexIndex.ts
+++ b/src/providers/codex/codexIndex.ts
@@ -26,14 +26,20 @@ import {
   parseCodexLine,
 } from './codexParser';
 import {
+  CODEX_PERIOD_LINEAGE_VERSION,
+  CODEX_ROLLING_HOURLY_DAYS,
   CodexFilePeriodIndex,
   CodexFileTodayIndex,
+  CodexHourlyDays,
   CodexPeriodMigrationState,
   CodexStructuralSummary,
   CodexTodayMigrationState,
-  reduceCodexHourlySlice,
+  isCompatibleCodexPeriodLineage,
+  pruneCodexHourlyDays,
+  reduceCodexRollingHourlySlice,
   reduceCodexStructuralSlice,
   reduceCodexUsageSlice,
+  codexPeriodFitsAggregate,
 } from './codexPeriodIndex';
 import { parseJsonObject, stringField } from './codexSchema';
 import {
@@ -65,11 +71,20 @@ import {
   CODEX_LINEAGE_FINGERPRINTS_PER_BLOCK,
   CodexLineageTrace,
 } from './codexLineage';
+import {
+  appendCodexQuotaHistory,
+  CODEX_FILE_QUOTA_HISTORY_LIMIT,
+  CODEX_QUOTA_HISTORY_LIMIT,
+  codexQuotaObservationsFromLimit,
+  CodexQuotaObservation,
+  sanitizeCodexQuotaHistory,
+} from './codexQuotaHistory';
 
 export {
   CodexPeriodMigrationState,
   CodexStructuralSummary,
 } from './codexPeriodIndex';
+export type { CodexQuotaObservation } from './codexQuotaHistory';
 
 export interface CodexFileAggregate {
   total: ProviderTokenCounts;
@@ -108,6 +123,8 @@ export interface CodexFileContribution {
   aggregate: CodexFileAggregate;
   limit?: ProviderLimitSnapshot;
   limits?: Record<string, ProviderLimitSnapshot>;
+  /** Small neutral history of weekly reset observations found in this file. */
+  quotaHistory?: CodexQuotaObservation[];
   qualityFlags: string[];
   identityChecked?: boolean;
   periodMigration?: CodexPeriodMigrationState;
@@ -177,6 +194,28 @@ export interface CodexTodayCoverage {
   complete: boolean;
 }
 
+export interface CodexHourlyDayCoverage {
+  day: string;
+  indexedFiles: number;
+  totalFiles: number;
+  indexedBytes: number;
+  totalBytes: number;
+  complete: boolean;
+}
+
+export interface CodexHourlyCoverage {
+  timeZone: string;
+  asOfDay: string;
+  windowDays: number;
+  indexedFiles: number;
+  totalFiles: number;
+  indexedBytes: number;
+  totalBytes: number;
+  complete: boolean;
+  /** Coverage for each civil day that has a verified period contribution. */
+  days: Record<string, CodexHourlyDayCoverage>;
+}
+
 export interface CodexIndexCoverage {
   indexedFiles: number;
   totalFiles: number;
@@ -185,6 +224,9 @@ export interface CodexIndexCoverage {
   complete: boolean;
   identity: CodexIdentityCoverage;
   period: CodexPeriodCoverage;
+  /** Missing only on pre-v2.3.1 schema-3 snapshots. */
+  hourly?: CodexHourlyCoverage;
+  /** Current-day compatibility projection of `hourly`. */
   today: CodexTodayCoverage;
 }
 
@@ -203,9 +245,13 @@ export interface CodexProviderAggregate {
 
 export interface CodexIndexV3 {
   schemaVersion: 3;
+  /** Independent persisted generation for migration completion isolation. */
+  indexGeneration?: number;
   files: Record<string, CodexFileContribution>;
   aggregate: CodexProviderAggregate;
   coverage: CodexIndexCoverage;
+  /** Bounded neutral history retained across file replacement/removal. */
+  quotaHistory?: CodexQuotaObservation[];
 }
 
 /** @deprecated Compatibility name until the remaining v2 consumers are rewired. */
@@ -219,6 +265,8 @@ export interface CodexIndexProgress {
   indexedBytes: number;
   totalBytes: number;
   period: CodexPeriodCoverage;
+  /** Present once rolling-hour coverage has been normalized or recomputed. */
+  hourly?: CodexHourlyCoverage;
 }
 
 export interface CodexIndexSchedulingPolicy {
@@ -292,6 +340,9 @@ export interface CodexIndexUpdateOptions {
   scheduling?: Partial<CodexIndexSchedulingPolicy>;
   /** Present only for accelerated cold/incomplete backfills. */
   filePassBatch?: CodexFilePassBatchRunner;
+  /** False skips unchanged historical lineage/period/hour/identity passes while
+   * still allowing the main changed-file and append-tail stage to run. */
+  allowHistoricalBackfill?: boolean;
   /** Internal resolved civil day shared with local file-pass workers. */
   asOfDay?: string;
 }
@@ -327,6 +378,14 @@ export class CodexIndexBudgetError extends Error {
 }
 
 const MAX_IDENTITY_BYTES = 256 * 1024;
+let lastRecoveryGeneration = 1;
+
+function recoveredIndex(timeZone: string): CodexIndexV3 {
+  const index = createEmptyCodexIndex(timeZone);
+  lastRecoveryGeneration = Math.max(lastRecoveryGeneration + 1, Date.now());
+  index.indexGeneration = lastRecoveryGeneration;
+  return index;
+}
 
 function zeroTokens(): ProviderTokenCounts {
   return {
@@ -442,6 +501,7 @@ export function createEmptyCodexIndex(timeZone = 'UTC'): CodexIndexV3 {
   });
   return {
     schemaVersion: 3,
+    indexGeneration: 1,
     files: {},
     aggregate: emptyAggregate(),
     coverage: {
@@ -462,6 +522,17 @@ export function createEmptyCodexIndex(timeZone = 'UTC'): CodexIndexV3 {
         last30Days: emptyRange(),
         allTime: emptyRange(),
       },
+      hourly: {
+        timeZone: resolvedTimeZone,
+        asOfDay,
+        windowDays: CODEX_ROLLING_HOURLY_DAYS,
+        indexedFiles: 0,
+        totalFiles: 0,
+        indexedBytes: 0,
+        totalBytes: 0,
+        complete: true,
+        days: {},
+      },
       today: {
         timeZone: resolvedTimeZone,
         day: asOfDay,
@@ -588,8 +659,12 @@ function promoteCaughtUpPeriod(
   timeZone: string,
 ): void {
   const migration = contribution.periodMigration;
+  const prefixEvents = contribution.lineage?.desiredPrefixEvents ?? 0;
   if (
     migration?.timeZone !== timeZone ||
+    migration.prefixEvents !== prefixEvents ||
+    !Number.isFinite(migration.tokenEventsSeen) ||
+    (migration.tokenEventsSeen ?? 0) < prefixEvents ||
     migration.offset < contribution.offset ||
     migration.discardingOversizedLine
   ) {
@@ -599,6 +674,8 @@ function promoteCaughtUpPeriod(
     timeZone,
     indexedThrough: contribution.offset,
     days: migration.days,
+    lineageVersion: CODEX_PERIOD_LINEAGE_VERSION,
+    lineagePrefixEvents: prefixEvents,
   };
   contribution.qualityFlags = uniqueFlags(
     contribution.qualityFlags,
@@ -612,7 +689,58 @@ function emptyTodayIndex(
   timeZone: string,
   indexedThrough = 0,
 ): CodexFileTodayIndex {
-  return { day, timeZone, indexedThrough, hours: {} };
+  return {
+    day,
+    timeZone,
+    indexedThrough,
+    hours: {},
+    windowDays: CODEX_ROLLING_HOURLY_DAYS,
+    days: {},
+  };
+}
+
+function rollingHourlyDaySet(day: string): Set<string> {
+  return new Set(
+    rollingDayKeysFromDayKey(day, CODEX_ROLLING_HOURLY_DAYS),
+  );
+}
+
+function isRollingTodayIndex(
+  value: CodexFileTodayIndex | undefined,
+  timeZone: string,
+): value is CodexFileTodayIndex & { days: CodexHourlyDays } {
+  return Boolean(
+    value &&
+    value.timeZone === timeZone &&
+    value.windowDays === CODEX_ROLLING_HOURLY_DAYS &&
+    value.days,
+  );
+}
+
+function syncTodayProjection(
+  value: CodexFileTodayIndex & { days: CodexHourlyDays },
+): void {
+  pruneCodexHourlyDays(value.days, rollingHourlyDaySet(value.day));
+  value.hours = value.days[value.day] ?? {};
+}
+
+/**
+ * A forward civil-day rollover needs only pruning: unchanged files cannot have
+ * events in the newly entered days. Moving the clock backwards can require
+ * days that were previously evicted, so it deliberately falls back to the
+ * resumable migration pass.
+ */
+function reanchorRollingToday(
+  value: CodexFileTodayIndex | undefined,
+  day: string,
+  timeZone: string,
+): boolean {
+  if (!isRollingTodayIndex(value, timeZone) || day < value.day) {
+    return false;
+  }
+  value.day = day;
+  syncTodayProjection(value);
+  return true;
 }
 
 function promoteCaughtUpToday(
@@ -625,6 +753,8 @@ function promoteCaughtUpToday(
   if (
     migration?.day !== day ||
     migration.timeZone !== timeZone ||
+    migration.windowDays !== CODEX_ROLLING_HOURLY_DAYS ||
+    !migration.days ||
     migration.prefixEvents !== prefixEvents ||
     migration.offset < contribution.offset ||
     migration.discardingOversizedLine
@@ -635,8 +765,15 @@ function promoteCaughtUpToday(
     day,
     timeZone,
     indexedThrough: contribution.offset,
-    hours: migration.hours,
+    hours: migration.days[day] ?? {},
+    windowDays: CODEX_ROLLING_HOURLY_DAYS,
+    days: migration.days,
   };
+  syncTodayProjection(
+    contribution.aggregate.today as CodexFileTodayIndex & {
+      days: CodexHourlyDays;
+    },
+  );
   contribution.qualityFlags = uniqueFlags(
     contribution.qualityFlags,
     migration.qualityFlags,
@@ -721,33 +858,43 @@ async function updateContribution(
   const pseudonymize = pseudonymizer(options.salt);
   let limit = contribution.limit;
   const limits = { ...(contribution.limits ?? {}) };
+  let quotaHistory = appendCodexQuotaHistory(
+    contribution.quotaHistory ?? [],
+    [],
+    CODEX_FILE_QUOTA_HISTORY_LIMIT,
+  );
   const timeZone = resolveTimeZone(options.timeZone);
   const asOfDay = options.asOfDay ?? dayKeyInZone(
     new Date((options.now ?? Date.now)()),
     timeZone,
   );
+  const rollingDays = rollingHourlyDaySet(asOfDay);
+  const desiredPrefixEvents = lineage.desiredPrefixEvents ?? 0;
   const advancePeriod =
     aggregate.period?.timeZone === timeZone &&
-    aggregate.period.indexedThrough === contribution.offset;
-  if (
-    aggregate.today &&
-    (aggregate.today.day !== asOfDay || aggregate.today.timeZone !== timeZone)
-  ) {
+    aggregate.period.indexedThrough === contribution.offset &&
+    lineage.appliedPrefixEvents === desiredPrefixEvents &&
+    isCompatibleCodexPeriodLineage(aggregate.period, desiredPrefixEvents) &&
+    codexPeriodFitsAggregate(aggregate.period, aggregate.total);
+  if (aggregate.today && !reanchorRollingToday(aggregate.today, asOfDay, timeZone)) {
     delete aggregate.today;
   }
   if (!aggregate.today && contribution.offset === 0) {
     aggregate.today = emptyTodayIndex(asOfDay, timeZone);
   }
-  const advanceToday =
-    aggregate.today?.day === asOfDay &&
-    aggregate.today.timeZone === timeZone &&
-    aggregate.today.indexedThrough === contribution.offset;
+  const activeToday =
+    isRollingTodayIndex(aggregate.today, timeZone) &&
+      aggregate.today.day === asOfDay &&
+      aggregate.today.indexedThrough === contribution.offset
+      ? aggregate.today
+      : undefined;
   let invalidEventTimestamp = false;
 
   const snapshot = (cursor: CodexJsonlCursor): CodexFileContribution => {
     syncSession(aggregate, parserState);
-    if (advanceToday && aggregate.today) {
-      aggregate.today.indexedThrough = cursor.offset;
+    if (activeToday) {
+      activeToday.indexedThrough = cursor.offset;
+      syncTodayProjection(activeToday);
     }
     return {
       ...contribution,
@@ -764,6 +911,7 @@ async function updateContribution(
       aggregate,
       limit,
       limits,
+      ...(quotaHistory.length > 0 ? { quotaHistory } : {}),
       qualityFlags: uniqueFlags(
         contribution.qualityFlags,
         parserState.qualityFlags,
@@ -795,11 +943,11 @@ async function updateContribution(
           } else if (advancePeriod && aggregate.period) {
             reduceCodexUsageSlice(aggregate.period.days, event, timeZone);
           }
-          if (advanceToday && aggregate.today) {
-            reduceCodexHourlySlice(
-              aggregate.today.hours,
+          if (activeToday) {
+            reduceCodexRollingHourlySlice(
+              activeToday.days,
               event,
-              asOfDay,
+              rollingDays,
               timeZone,
             );
           }
@@ -823,6 +971,11 @@ async function updateContribution(
           limit = parsed.limit ?? limit;
         }
         if (parsed.limit) {
+          quotaHistory = appendCodexQuotaHistory(
+            quotaHistory,
+            codexQuotaObservationsFromLimit(parsed.limit),
+            CODEX_FILE_QUOTA_HISTORY_LIMIT,
+          );
           const limitKey =
             parsed.limit.limitId ?? parsed.limit.limitName ?? 'default';
           const previousLimit = limits[limitKey];
@@ -847,8 +1000,9 @@ async function updateContribution(
   if (advancePeriod && aggregate.period) {
     aggregate.period.indexedThrough = scan.cursor.offset;
   }
-  if (advanceToday && aggregate.today) {
-    aggregate.today.indexedThrough = scan.cursor.offset;
+  if (activeToday) {
+    activeToday.indexedThrough = scan.cursor.offset;
+    syncTodayProjection(activeToday);
   }
   if (
     scan.cursor.offset >= entry.size &&
@@ -880,6 +1034,10 @@ function promoteCaughtUpLineage(
   }
   contribution.aggregate = reconciliation.aggregate;
   lineage.appliedPrefixEvents = reconciliation.prefixEvents;
+  if (contribution.aggregate.period) {
+    contribution.aggregate.period.lineageVersion = CODEX_PERIOD_LINEAGE_VERSION;
+    contribution.aggregate.period.lineagePrefixEvents = reconciliation.prefixEvents;
+  }
   contribution.qualityFlags = uniqueFlags(
     contribution.qualityFlags,
     reconciliation.qualityFlags,
@@ -901,10 +1059,14 @@ async function reconcileContributionLineage(
     new Date((options.now ?? Date.now)()),
     timeZone,
   );
+  const rollingDays = rollingHourlyDaySet(asOfDay);
   const initial = contribution.lineageReconciliation?.prefixEvents ===
       prefixEvents &&
-      contribution.lineageReconciliation.aggregate.today?.day === asOfDay &&
-      contribution.lineageReconciliation.aggregate.today.timeZone === timeZone
+      isRollingTodayIndex(
+        contribution.lineageReconciliation.aggregate.today,
+        timeZone,
+      ) &&
+      contribution.lineageReconciliation.aggregate.today.day === asOfDay
     ? contribution.lineageReconciliation
     : {
         prefixEvents,
@@ -924,6 +1086,11 @@ async function reconcileContributionLineage(
   const aggregate = initial.aggregate;
   let invalidEventTimestamp = false;
   const pseudonymize = pseudonymizer(options.salt);
+  let quotaHistory = appendCodexQuotaHistory(
+    contribution.quotaHistory ?? [],
+    [],
+    CODEX_FILE_QUOTA_HISTORY_LIMIT,
+  );
 
   const snapshot = (cursor: CodexJsonlCursor): CodexFileContribution => {
     syncSession(aggregate, parserState);
@@ -932,9 +1099,13 @@ async function reconcileContributionLineage(
     }
     if (aggregate.today) {
       aggregate.today.indexedThrough = cursor.offset;
+      if (isRollingTodayIndex(aggregate.today, timeZone)) {
+        syncTodayProjection(aggregate.today);
+      }
     }
     return {
       ...contribution,
+      ...(quotaHistory.length > 0 ? { quotaHistory } : {}),
       lineageReconciliation: {
         prefixEvents,
         tokenEventsSeen,
@@ -965,6 +1136,13 @@ async function reconcileContributionLineage(
       }
       const parsed = parseCodexLine(line, parserState, pseudonymize);
       parserState = parsed.state;
+      if (parsed.limit) {
+        quotaHistory = appendCodexQuotaHistory(
+          quotaHistory,
+          codexQuotaObservationsFromLimit(parsed.limit),
+          CODEX_FILE_QUOTA_HISTORY_LIMIT,
+        );
+      }
       if (parsed.lineageTokenKey) {
         tokenEventsSeen += 1;
       }
@@ -977,11 +1155,11 @@ async function reconcileContributionLineage(
           } else if (aggregate.period) {
             reduceCodexUsageSlice(aggregate.period.days, event, timeZone);
           }
-          if (aggregate.today) {
-            reduceCodexHourlySlice(
-              aggregate.today.hours,
+          if (isRollingTodayIndex(aggregate.today, timeZone)) {
+            reduceCodexRollingHourlySlice(
+              aggregate.today.days,
               event,
-              asOfDay,
+              rollingDays,
               timeZone,
             );
           }
@@ -1030,10 +1208,18 @@ async function migrateContributionPeriod(
   onChunk: ContributionChunkHandler,
 ): Promise<CodexFilePassResult> {
   const timeZone = resolveTimeZone(options.timeZone);
-  const initial = contribution.periodMigration?.timeZone === timeZone
-    ? contribution.periodMigration
+  const prefixEvents = contribution.lineage?.desiredPrefixEvents ?? 0;
+  const savedMigration = contribution.periodMigration;
+  const canResume = savedMigration?.timeZone === timeZone &&
+    savedMigration.prefixEvents === prefixEvents &&
+    Number.isFinite(savedMigration.tokenEventsSeen) &&
+    (savedMigration.tokenEventsSeen ?? 0) >= prefixEvents;
+  const initial: CodexPeriodMigrationState = canResume
+    ? savedMigration
     : {
         timeZone,
+        prefixEvents,
+        tokenEventsSeen: 0,
         offset: 0,
         discardingOversizedLine: false,
         parserState: createCodexParserState(entry.fileKey),
@@ -1042,17 +1228,26 @@ async function migrateContributionPeriod(
       };
   let parserState = initial.parserState;
   const days = initial.days;
+  let tokenEventsSeen = initial.tokenEventsSeen ?? 0;
   let invalidEventTimestamp = false;
   const pseudonymize = pseudonymizer(options.salt);
+  let quotaHistory = appendCodexQuotaHistory(
+    contribution.quotaHistory ?? [],
+    [],
+    CODEX_FILE_QUOTA_HISTORY_LIMIT,
+  );
 
   const snapshot = (cursor: CodexJsonlCursor): CodexFileContribution => ({
     ...contribution,
+    ...(quotaHistory.length > 0 ? { quotaHistory } : {}),
     aggregate: {
       ...contribution.aggregate,
       period: undefined,
     },
     periodMigration: {
       timeZone,
+      prefixEvents,
+      tokenEventsSeen,
       offset: cursor.offset,
       discardingOversizedLine: cursor.discardingOversizedLine,
       parserState,
@@ -1079,14 +1274,26 @@ async function migrateContributionPeriod(
       }
       const parsed = parseCodexLine(line, parserState, pseudonymize);
       parserState = parsed.state;
-      for (const event of parsed.events) {
-        if (!Number.isFinite(event.timestamp) || event.timestamp <= 0) {
-          invalidEventTimestamp = true;
-        } else {
-          reduceCodexUsageSlice(days, event, timeZone);
+      if (parsed.limit) {
+        quotaHistory = appendCodexQuotaHistory(
+          quotaHistory,
+          codexQuotaObservationsFromLimit(parsed.limit),
+          CODEX_FILE_QUOTA_HISTORY_LIMIT,
+        );
+      }
+      if (parsed.lineageTokenKey) {
+        tokenEventsSeen += 1;
+      }
+      if (tokenEventsSeen > prefixEvents) {
+        for (const event of parsed.events) {
+          if (!Number.isFinite(event.timestamp) || event.timestamp <= 0) {
+            invalidEventTimestamp = true;
+          } else {
+            reduceCodexUsageSlice(days, event, timeZone);
+          }
         }
       }
-      if (parsed.structural) {
+      if (parsed.structural && tokenEventsSeen >= prefixEvents) {
         if (
           !Number.isFinite(parsed.structural.timestamp) ||
           parsed.structural.timestamp <= 0
@@ -1120,6 +1327,8 @@ async function migrateContributionPeriod(
       timeZone,
       indexedThrough: contribution.offset,
       days: updated.periodMigration.days,
+      lineageVersion: CODEX_PERIOD_LINEAGE_VERSION,
+      lineagePrefixEvents: prefixEvents,
     };
     updated.qualityFlags = uniqueFlags(
       updated.qualityFlags,
@@ -1143,10 +1352,14 @@ async function migrateContributionToday(
     new Date((options.now ?? Date.now)()),
     timeZone,
   );
+  const rollingDays = rollingHourlyDaySet(day);
   const prefixEvents = contribution.lineage?.desiredPrefixEvents ?? 0;
   const initial =
     contribution.todayMigration?.day === day &&
       contribution.todayMigration.timeZone === timeZone &&
+      contribution.todayMigration.windowDays ===
+        CODEX_ROLLING_HOURLY_DAYS &&
+      contribution.todayMigration.days &&
       contribution.todayMigration.prefixEvents === prefixEvents
       ? contribution.todayMigration
       : {
@@ -1158,16 +1371,25 @@ async function migrateContributionToday(
           discardingOversizedLine: false,
           parserState: createCodexParserState(entry.fileKey),
           hours: {},
+          windowDays: CODEX_ROLLING_HOURLY_DAYS,
+          days: {},
           qualityFlags: [],
         };
   let parserState = initial.parserState;
   let tokenEventsSeen = initial.tokenEventsSeen;
-  const hours = initial.hours;
+  const days = initial.days as CodexHourlyDays;
+  pruneCodexHourlyDays(days, rollingDays);
   let invalidEventTimestamp = false;
   const pseudonymize = pseudonymizer(options.salt);
+  let quotaHistory = appendCodexQuotaHistory(
+    contribution.quotaHistory ?? [],
+    [],
+    CODEX_FILE_QUOTA_HISTORY_LIMIT,
+  );
 
   const snapshot = (cursor: CodexJsonlCursor): CodexFileContribution => ({
     ...contribution,
+    ...(quotaHistory.length > 0 ? { quotaHistory } : {}),
     aggregate: {
       ...contribution.aggregate,
       today: undefined,
@@ -1180,7 +1402,9 @@ async function migrateContributionToday(
       offset: cursor.offset,
       discardingOversizedLine: cursor.discardingOversizedLine,
       parserState,
-      hours,
+      hours: days[day] ?? {},
+      windowDays: CODEX_ROLLING_HOURLY_DAYS,
+      days,
       qualityFlags: uniqueFlags(
         initial.qualityFlags,
         parserState.qualityFlags,
@@ -1203,6 +1427,13 @@ async function migrateContributionToday(
       }
       const parsed = parseCodexLine(line, parserState, pseudonymize);
       parserState = parsed.state;
+      if (parsed.limit) {
+        quotaHistory = appendCodexQuotaHistory(
+          quotaHistory,
+          codexQuotaObservationsFromLimit(parsed.limit),
+          CODEX_FILE_QUOTA_HISTORY_LIMIT,
+        );
+      }
       if (parsed.lineageTokenKey) {
         tokenEventsSeen += 1;
       }
@@ -1214,7 +1445,7 @@ async function migrateContributionToday(
           invalidEventTimestamp = true;
           continue;
         }
-        reduceCodexHourlySlice(hours, event, day, timeZone);
+        reduceCodexRollingHourlySlice(days, event, rollingDays, timeZone);
       }
     },
     async (progress) => {
@@ -1222,7 +1453,7 @@ async function migrateContributionToday(
     },
   );
   if (!scan.reachedEnd) {
-    throw new Error('Codex log changed during current-day migration');
+    throw new Error('Codex log changed during rolling-hour migration');
   }
   const updated = snapshot(scan.cursor);
   if (updated.todayMigration && scan.oversizedLines > 0) {
@@ -1629,6 +1860,54 @@ function recomputeAggregate(
   return aggregate;
 }
 
+/**
+ * Merge the small per-file observations into the index-level history before
+ * any manifest removals can discard their last copy. The history is neutral by
+ * construction, so it can preserve reset boundaries without pretending to
+ * identify which account produced them.
+ */
+function mergeCodexQuotaHistory(index: CodexIndexV3): void {
+  const additions: CodexQuotaObservation[] = [];
+  for (const contribution of Object.values(index.files)) {
+    additions.push(...(contribution.quotaHistory ?? []));
+    for (const snapshot of [
+      ...Object.values(contribution.limits ?? {}),
+      ...(contribution.limit ? [contribution.limit] : []),
+    ]) {
+      additions.push(...codexQuotaObservationsFromLimit(snapshot));
+    }
+  }
+  const history = appendCodexQuotaHistory(
+    sanitizeCodexQuotaHistory(index.quotaHistory, CODEX_QUOTA_HISTORY_LIMIT),
+    additions,
+    CODEX_QUOTA_HISTORY_LIMIT,
+  );
+  index.quotaHistory = history.length > 0 ? history : undefined;
+}
+
+function hasCodexQuotaEvidence(index: CodexIndexV3): boolean {
+  return Object.values(index.files).some((contribution) =>
+    (contribution.quotaHistory?.length ?? 0) > 0 || [
+      ...Object.values(contribution.limits ?? {}),
+      ...(contribution.limit ? [contribution.limit] : []),
+    ].some((snapshot) => codexQuotaObservationsFromLimit(snapshot).length > 0),
+  );
+}
+
+export function isReadableCodexPeriod(
+  contribution: CodexFileContribution | undefined,
+  timeZone: string,
+): boolean {
+  if (!contribution || !isCodexUsageContributionCurrent(contribution)) {
+    return false;
+  }
+  const period = contribution.aggregate.period;
+  const prefixEvents = contribution.lineage?.desiredPrefixEvents ?? 0;
+  return period?.timeZone === timeZone &&
+    isCompatibleCodexPeriodLineage(period, prefixEvents) &&
+    codexPeriodFitsAggregate(period, contribution.aggregate.total);
+}
+
 function coverageFor(
   files: Record<string, CodexFileContribution>,
   manifest: CodexManifest,
@@ -1698,8 +1977,18 @@ function coverageFor(
       }
       rangeTotalFiles += 1;
       rangeTotalBytes += entry.size;
-      const periodIsCurrent = Boolean(
-        contribution && isCodexUsageContributionCurrent(contribution),
+      const periodIsCurrent = isReadableCodexPeriod(contribution, timeZone);
+      const periodMigration = contribution?.periodMigration;
+      // A migration draft is intentionally not a readable period yet, but
+      // its cursor still represents verified work for the progress display.
+      // Keep this separate from periodIsCurrent so a rejected legacy sidecar
+      // cannot be rendered as data while an active rebuild remains visible.
+      const periodMigrationIsCurrent = Boolean(
+        contribution &&
+        isCodexUsageContributionCurrent(contribution) &&
+        periodMigration?.timeZone === timeZone &&
+        periodMigration.prefixEvents ===
+          (contribution.lineage?.desiredPrefixEvents ?? 0),
       );
       const promoted = periodIsCurrent &&
         contribution?.aggregate.period?.timeZone === timeZone
@@ -1709,9 +1998,8 @@ function coverageFor(
             entry.size,
           )
         : 0;
-      const draft = periodIsCurrent &&
-        contribution?.periodMigration?.timeZone === timeZone
-        ? Math.min(contribution.periodMigration.offset, contribution.offset, entry.size)
+      const draft = periodMigrationIsCurrent && periodMigration
+        ? Math.min(periodMigration.offset, contribution.offset, entry.size)
         : 0;
       const migrated = Math.max(0, Math.max(promoted, draft));
       migratedBytes += migrated;
@@ -1735,14 +2023,20 @@ function coverageFor(
     };
   };
   const last7Start = rollingDayKeysFromDayKey(asOfDay, 7)[0];
-  const last30Start = rollingDayKeysFromDayKey(asOfDay, 30)[0];
+  const last30DayKeys = rollingDayKeysFromDayKey(
+    asOfDay,
+    CODEX_ROLLING_HOURLY_DAYS,
+  );
+  const last30Start = last30DayKeys[0];
   const last7Days = rangeCoverage(last7Start);
   const last30Days = rangeCoverage(last30Start);
   const allTime = rangeCoverage();
-  let todayIndexedFiles = 0;
-  let todayTotalFiles = 0;
-  let todayIndexedBytes = 0;
-  let todayTotalBytes = 0;
+  const rollingDays = new Set(last30DayKeys);
+  const hourlyDays: Record<string, CodexHourlyDayCoverage> = {};
+  let hourlyIndexedFiles = 0;
+  let hourlyTotalFiles = 0;
+  let hourlyIndexedBytes = 0;
+  let hourlyTotalBytes = 0;
   for (const entry of manifest.files) {
     if (!deduplication.canonicalFileKeys.has(entry.fileKey)) {
       continue;
@@ -1754,15 +2048,20 @@ function coverageFor(
       contribution.lineageReconciliation ||
       contribution.lineage?.appliedPrefixEvents !==
         contribution.lineage?.desiredPrefixEvents ||
-      !contribution.aggregate.period?.days[asOfDay]
+      !isReadableCodexPeriod(contribution, timeZone)
     ) {
       continue;
     }
-    todayTotalFiles += 1;
-    todayTotalBytes += entry.size;
+    const eligibleDays = Object.keys(contribution.aggregate.period!.days)
+      .filter((day) => rollingDays.has(day));
+    if (eligibleDays.length === 0) {
+      continue;
+    }
+    hourlyTotalFiles += 1;
+    hourlyTotalBytes += entry.size;
     const promoted =
-      contribution.aggregate.today?.day === asOfDay &&
-      contribution.aggregate.today.timeZone === timeZone
+      isRollingTodayIndex(contribution.aggregate.today, timeZone) &&
+      contribution.aggregate.today.day === asOfDay
         ? Math.min(
             contribution.aggregate.today.indexedThrough,
             contribution.offset,
@@ -1772,6 +2071,9 @@ function coverageFor(
     const draft =
       contribution.todayMigration?.day === asOfDay &&
       contribution.todayMigration.timeZone === timeZone &&
+      contribution.todayMigration.windowDays ===
+        CODEX_ROLLING_HOURLY_DAYS &&
+      contribution.todayMigration.days &&
       contribution.todayMigration.prefixEvents ===
         (contribution.lineage?.desiredPrefixEvents ?? 0)
         ? Math.min(
@@ -1780,15 +2082,47 @@ function coverageFor(
             entry.size,
           )
         : 0;
-    todayIndexedBytes += Math.max(0, Math.max(promoted, draft));
-    if (
-      contribution.aggregate.today?.day === asOfDay &&
-      contribution.aggregate.today.timeZone === timeZone &&
-      contribution.aggregate.today.indexedThrough >= contribution.offset
-    ) {
-      todayIndexedFiles += 1;
+    const migratedBytes = Math.max(0, Math.max(promoted, draft));
+    hourlyIndexedBytes += migratedBytes;
+    const completeFile = Boolean(
+      isRollingTodayIndex(contribution.aggregate.today, timeZone) &&
+      contribution.aggregate.today.day === asOfDay &&
+      contribution.aggregate.today.indexedThrough >= contribution.offset,
+    );
+    if (completeFile) {
+      hourlyIndexedFiles += 1;
     }
+    for (const day of eligibleDays) {
+      const current = (hourlyDays[day] ??= {
+        day,
+        indexedFiles: 0,
+        totalFiles: 0,
+        indexedBytes: 0,
+        totalBytes: 0,
+        complete: false,
+      });
+      current.totalFiles += 1;
+      current.totalBytes += entry.size;
+      current.indexedBytes += migratedBytes;
+      if (completeFile) {
+        current.indexedFiles += 1;
+      }
+    }
+  }
+  const hourlyComplete =
+    last30Days.complete && hourlyIndexedFiles === hourlyTotalFiles;
+  for (const coverage of Object.values(hourlyDays)) {
+    coverage.complete =
+      last30Days.complete && coverage.indexedFiles === coverage.totalFiles;
   }
+  const todayDayCoverage = hourlyDays[asOfDay] ?? {
+    day: asOfDay,
+    indexedFiles: 0,
+    totalFiles: 0,
+    indexedBytes: 0,
+    totalBytes: 0,
+    complete: last30Days.complete,
+  };
   return {
     indexedFiles,
     totalFiles,
@@ -1807,14 +2141,25 @@ function coverageFor(
       last30Days,
       allTime,
     },
+    hourly: {
+      timeZone,
+      asOfDay,
+      windowDays: CODEX_ROLLING_HOURLY_DAYS,
+      indexedFiles: hourlyIndexedFiles,
+      totalFiles: hourlyTotalFiles,
+      indexedBytes: hourlyIndexedBytes,
+      totalBytes: hourlyTotalBytes,
+      complete: hourlyComplete,
+      days: hourlyDays,
+    },
     today: {
       timeZone,
       day: asOfDay,
-      indexedFiles: todayIndexedFiles,
-      totalFiles: todayTotalFiles,
-      indexedBytes: todayIndexedBytes,
-      totalBytes: todayTotalBytes,
-      complete: last7Days.complete && todayIndexedFiles === todayTotalFiles,
+      indexedFiles: todayDayCoverage.indexedFiles,
+      totalFiles: todayDayCoverage.totalFiles,
+      indexedBytes: todayDayCoverage.indexedBytes,
+      totalBytes: todayDayCoverage.totalBytes,
+      complete: todayDayCoverage.complete,
     },
   };
 }
@@ -1833,6 +2178,7 @@ function recomputeDerivedIndex(
       initialDeduplication.canonicalFileKeys,
     );
   }
+  mergeCodexQuotaHistory(index);
   const deduplication = classifyCodexSessionDuplicates(index.files);
   index.aggregate = recomputeAggregate(index.files, deduplication);
   index.coverage = coverageFor(
@@ -1851,6 +2197,7 @@ function progressFor(index: CodexIndexV3, scannedFiles: number): CodexIndexProgr
     indexedBytes: index.coverage.indexedBytes,
     totalBytes: index.coverage.totalBytes,
     period: index.coverage.period,
+    hourly: index.coverage.hourly,
   };
 }
 
@@ -1861,7 +2208,14 @@ function isWarmNoOp(
   timeZone: string,
   asOfDay: string,
 ): boolean {
+  // Older schema-3 indexes have a current `limit` projection but no neutral
+  // reset history. Give the next refresh one chance to seed the bounded cache
+  // even when the JSONL manifest itself has not changed.
+  if (hasCodexQuotaEvidence(previous) && !previous.quotaHistory?.length) {
+    return false;
+  }
   const totalBytes = manifest.files.reduce((sum, entry) => sum + entry.size, 0);
+  const hourlyCoverage = previous.coverage.hourly;
   if (
     diff.appended.length > 0 ||
     diff.truncated.length > 0 ||
@@ -1877,6 +2231,10 @@ function isWarmNoOp(
     !previous.coverage.period.allTime.complete ||
     previous.coverage.period.timeZone !== timeZone ||
     previous.coverage.period.asOfDay !== asOfDay ||
+    !hourlyCoverage?.complete ||
+    hourlyCoverage.timeZone !== timeZone ||
+    hourlyCoverage.asOfDay !== asOfDay ||
+    hourlyCoverage.windowDays !== CODEX_ROLLING_HOURLY_DAYS ||
     !previous.coverage.today?.complete ||
     previous.coverage.today.timeZone !== timeZone ||
     previous.coverage.today.day !== asOfDay
@@ -1885,6 +2243,7 @@ function isWarmNoOp(
   }
   const canonical = classifyCodexSessionDuplicates(previous.files)
     .canonicalFileKeys;
+  const rollingDays = rollingHourlyDaySet(asOfDay);
   return manifest.files.every((entry) => {
     const contribution = previous.files[entry.fileKey];
     const baseIsCurrent = Boolean(
@@ -1897,21 +2256,22 @@ function isWarmNoOp(
       !contribution.lineageReconciliation &&
       contribution.aggregate.period?.timeZone === timeZone &&
       contribution.aggregate.period.indexedThrough >= contribution.offset &&
+      isReadableCodexPeriod(contribution, timeZone) &&
       !contribution.qualityFlags.includes('stale-file') &&
       !contribution.qualityFlags.includes('stale-reset-required'),
     );
     if (!baseIsCurrent || !contribution) {
       return false;
     }
-    if (
-      !canonical.has(entry.fileKey) ||
-      !contribution.aggregate.period?.days[asOfDay]
-    ) {
+    const hasRollingDay = Object.keys(
+      contribution.aggregate.period?.days ?? {},
+    ).some((day) => rollingDays.has(day));
+    if (!canonical.has(entry.fileKey) || !hasRollingDay) {
       return true;
     }
     return Boolean(
-      contribution.aggregate.today?.day === asOfDay &&
-      contribution.aggregate.today.timeZone === timeZone &&
+      isRollingTodayIndex(contribution.aggregate.today, timeZone) &&
+      contribution.aggregate.today.day === asOfDay &&
       contribution.aggregate.today.indexedThrough >= contribution.offset &&
       !contribution.todayMigration
     );
@@ -1980,6 +2340,12 @@ export async function updateCodexIndex(
     };
   }
   const index = cloneIndex(previous);
+  // Seed the durable neutral history before moved/removed files disappear.
+  // This also upgrades an older index without rereading unchanged JSONL.
+  mergeCodexQuotaHistory(index);
+  if (previous.coverage.period.timeZone !== timeZone) {
+    index.indexGeneration = Math.max(1, Math.floor(previous.indexGeneration ?? 0) + 1);
+  }
   const entries = new Map(manifest.files.map((entry) => [entry.fileKey, entry]));
   let bodyReads = 0;
   let failedFiles = 0;
@@ -2027,27 +2393,60 @@ export async function updateCodexIndex(
   }
   for (const contribution of Object.values(index.files)) {
     promoteCaughtUpLineage(contribution);
-    if (contribution.aggregate.period?.timeZone !== timeZone) {
+    const desiredPrefixEvents = contribution.lineage?.desiredPrefixEvents ?? 0;
+    if (contribution.aggregate.period && (
+      !isCompatibleCodexPeriodLineage(
+        contribution.aggregate.period,
+        desiredPrefixEvents,
+      ) ||
+      !codexPeriodFitsAggregate(
+        contribution.aggregate.period,
+        contribution.aggregate.total,
+      ) ||
+      contribution.aggregate.period.timeZone !== timeZone
+    )) {
       delete contribution.aggregate.period;
     }
-    if (contribution.periodMigration?.timeZone !== timeZone) {
-      delete contribution.periodMigration;
-    }
-    promoteCaughtUpPeriod(contribution, timeZone);
     if (
-      contribution.aggregate.today &&
+      contribution.periodMigration &&
       (
-        contribution.aggregate.today.day !== asOfDay ||
-        contribution.aggregate.today.timeZone !== timeZone
+        contribution.periodMigration.timeZone !== timeZone ||
+        contribution.periodMigration.prefixEvents !== desiredPrefixEvents ||
+        !Number.isFinite(contribution.periodMigration.tokenEventsSeen) ||
+        (contribution.periodMigration.tokenEventsSeen ?? 0) < desiredPrefixEvents
       )
     ) {
-      delete contribution.aggregate.today;
+      delete contribution.periodMigration;
+    }
+    promoteCaughtUpPeriod(contribution, timeZone);
+    const today = contribution.aggregate.today;
+    if (today) {
+      if (isRollingTodayIndex(today, timeZone)) {
+        const previousDay = today.day;
+        const nextWindow = rollingHourlyDaySet(asOfDay);
+        const hasPreviouslyFutureUsage =
+          asOfDay > previousDay &&
+          Object.keys(contribution.aggregate.period?.days ?? {}).some(
+            (day) => day > previousDay && nextWindow.has(day),
+          );
+        if (
+          hasPreviouslyFutureUsage ||
+          !reanchorRollingToday(today, asOfDay, timeZone)
+        ) {
+          delete contribution.aggregate.today;
+        }
+      } else if (today.day !== asOfDay || today.timeZone !== timeZone) {
+        delete contribution.aggregate.today;
+      }
     }
     if (
       contribution.todayMigration &&
       (
         contribution.todayMigration.day !== asOfDay ||
         contribution.todayMigration.timeZone !== timeZone ||
+        contribution.todayMigration.windowDays !==
+          CODEX_ROLLING_HOURLY_DAYS ||
+        !contribution.todayMigration.days ||
         contribution.todayMigration.prefixEvents !==
           (contribution.lineage?.desiredPrefixEvents ?? 0)
       )
@@ -2388,7 +2787,8 @@ export async function updateCodexIndex(
   }
 
   await finishStage(filePasses > mainPassStart, true);
-  const lineageWork = manifest.files
+  const allowHistoricalBackfill = options.allowHistoricalBackfill !== false;
+  const lineageWork = (allowHistoricalBackfill ? manifest.files : [])
     .filter((entry) => {
       const contribution = index.files[entry.fileKey];
       return Boolean(
@@ -2510,7 +2910,7 @@ export async function updateCodexIndex(
 
   await finishStage(filePasses > lineagePassStart);
   const canonical = classifyCodexSessionDuplicates(index.files).canonicalFileKeys;
-  const periodWork = manifest.files
+  const periodWork = (allowHistoricalBackfill ? manifest.files : [])
     .filter((entry) => {
       if (!canonical.has(entry.fileKey)) {
         return false;
@@ -2525,6 +2925,14 @@ export async function updateCodexIndex(
         contribution.offset >= entry.size &&
         !contribution.discardingOversizedLine &&
         (
+          !isCompatibleCodexPeriodLineage(
+            contribution.aggregate.period,
+            contribution.lineage?.desiredPrefixEvents ?? 0,
+          ) ||
+          !codexPeriodFitsAggregate(
+            contribution.aggregate.period,
+            contribution.aggregate.total,
+          ) ||
           contribution.aggregate.period?.timeZone !== timeZone ||
           contribution.aggregate.period.indexedThrough !== contribution.offset
         ),
@@ -2550,7 +2958,12 @@ export async function updateCodexIndex(
         continue;
       }
       const base = cloneContribution(prior);
-      const start = base.periodMigration?.timeZone === timeZone
+      const start = base.periodMigration?.timeZone === timeZone &&
+          base.periodMigration.prefixEvents ===
+            (base.lineage?.desiredPrefixEvents ?? 0) &&
+          Number.isFinite(base.periodMigration.tokenEventsSeen) &&
+          (base.periodMigration.tokenEventsSeen ?? 0) >=
+            (base.lineage?.desiredPrefixEvents ?? 0)
         ? base.periodMigration.offset
         : 0;
       const endExclusive = Math.min(
@@ -2590,7 +3003,12 @@ export async function updateCodexIndex(
       continue;
     }
     const base = cloneContribution(prior);
-    const start = base.periodMigration?.timeZone === timeZone
+    const start = base.periodMigration?.timeZone === timeZone &&
+        base.periodMigration.prefixEvents ===
+          (base.lineage?.desiredPrefixEvents ?? 0) &&
+        Number.isFinite(base.periodMigration.tokenEventsSeen) &&
+        (base.periodMigration.tokenEventsSeen ?? 0) >=
+          (base.lineage?.desiredPrefixEvents ?? 0)
       ? base.periodMigration.offset
       : 0;
     const endExclusive = Math.min(
@@ -2633,7 +3051,8 @@ export async function updateCodexIndex(
 
   const todayCanonical = classifyCodexSessionDuplicates(index.files)
     .canonicalFileKeys;
-  const todayWork = manifest.files
+  const hourlyWindowDays = rollingHourlyDaySet(asOfDay);
+  const todayWork = (allowHistoricalBackfill ? manifest.files : [])
     .filter((entry) => {
       if (!todayCanonical.has(entry.fileKey)) {
         return false;
@@ -2648,10 +3067,11 @@ export async function updateCodexIndex(
         contribution.offset > 0 &&
         contribution.offset >= entry.size &&
         !contribution.discardingOversizedLine &&
-        contribution.aggregate.period?.days[asOfDay] &&
+        Object.keys(contribution.aggregate.period?.days ?? {})
+          .some((day) => hourlyWindowDays.has(day)) &&
         (
-          contribution.aggregate.today?.day !== asOfDay ||
-          contribution.aggregate.today.timeZone !== timeZone ||
+          !isRollingTodayIndex(contribution.aggregate.today, timeZone) ||
+          contribution.aggregate.today.day !== asOfDay ||
           contribution.aggregate.today.indexedThrough !== contribution.offset
         )
       );
@@ -2680,6 +3100,8 @@ export async function updateCodexIndex(
       const start =
         migration?.day === asOfDay &&
           migration.timeZone === timeZone &&
+          migration.windowDays === CODEX_ROLLING_HOURLY_DAYS &&
+          migration.days &&
           migration.prefixEvents ===
             (base.lineage?.desiredPrefixEvents ?? 0)
           ? migration.offset
@@ -2727,6 +3149,8 @@ export async function updateCodexIndex(
     const start =
       migration?.day === asOfDay &&
         migration.timeZone === timeZone &&
+        migration.windowDays === CODEX_ROLLING_HOURLY_DAYS &&
+        migration.days &&
         migration.prefixEvents ===
           (base.lineage?.desiredPrefixEvents ?? 0)
         ? migration.offset
@@ -2773,7 +3197,9 @@ export async function updateCodexIndex(
 
   reconcileLineageForCheckpoint = true;
   const identityPassStart = filePasses;
-  const identityWork = manifest.files.sort(recentFirst);
+  const identityWork = allowHistoricalBackfill
+    ? manifest.files.sort(recentFirst)
+    : [];
   const pendingIdentity = identityWork.filter(
     (entry) => index.files[entry.fileKey]?.identityChecked !== true,
   );
@@ -2869,7 +3295,7 @@ export async function updateCodexIndex(
       pending:
         !index.coverage.complete ||
         !index.coverage.period.allTime.complete ||
-        !index.coverage.today.complete,
+        !index.coverage.hourly?.complete,
     },
   };
 }
@@ -2879,6 +3305,7 @@ interface LegacyCodexIndexV1 {
   readonly files: Readonly<Record<string, LegacyCodexFileContribution>>;
   readonly aggregate?: unknown;
   readonly coverage?: unknown;
+  readonly quotaHistory?: unknown;
 }
 
 interface LegacyCodexFileContribution {
@@ -2895,6 +3322,7 @@ interface LegacyCodexFileContribution {
   readonly aggregate?: unknown;
   readonly limit?: unknown;
   readonly limits?: unknown;
+  readonly quotaHistory?: unknown;
   readonly qualityFlags?: unknown;
   readonly identityChecked?: unknown;
 }
@@ -2916,6 +3344,7 @@ interface LegacyCodexIndexV2 {
   readonly files: Readonly<Record<string, unknown>>;
   readonly aggregate?: unknown;
   readonly coverage?: unknown;
+  readonly quotaHistory?: unknown;
 }
 
 function isLegacyIndexV2(value: unknown): value is LegacyCodexIndexV2 {
@@ -3110,7 +3539,7 @@ function sanitizeParserState(value: unknown, fileKey: string): CodexParserState
     record.previousSnapshotSignature,
   );
   return {
-    schemaVersion: 3,
+    schemaVersion: 4,
     fileKey,
     sessionKey,
     ...(treeKey ? { treeKey } : {}),
@@ -3195,6 +3624,12 @@ function sanitizePeriod(value: unknown): CodexFilePeriodIndex | undefined {
     timeZone: resolveTimeZone(value.timeZone),
     indexedThrough: Math.max(0, finiteNumber(value.indexedThrough)),
     days,
+    ...(optionalNumber(value.lineageVersion) !== undefined
+      ? { lineageVersion: optionalNumber(value.lineageVersion) }
+      : {}),
+    ...(optionalNumber(value.lineagePrefixEvents) !== undefined
+      ? { lineagePrefixEvents: Math.max(0, Math.floor(optionalNumber(value.lineagePrefixEvents)!)) }
+      : {}),
   };
 }
 
@@ -3217,6 +3652,21 @@ function sanitizeHourlySlices(
   );
 }
 
+function sanitizeHourlyDays(value: unknown): CodexHourlyDays {
+  if (!isRecord(value)) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([day, rawHours]) => {
+      if (rollingDayKeysFromDayKey(day, 1)[0] !== day) {
+        return [];
+      }
+      const hours = sanitizeHourlySlices(rawHours);
+      return Object.keys(hours).length > 0 ? [[day, hours]] : [];
+    }),
+  );
+}
+
 function sanitizeToday(value: unknown): CodexFileTodayIndex | undefined {
   if (
     !isRecord(value) ||
@@ -3226,11 +3676,24 @@ function sanitizeToday(value: unknown): CodexFileTodayIndex | undefined {
   ) {
     return undefined;
   }
+  const timeZone = resolveTimeZone(value.timeZone);
+  const modern = value.windowDays === CODEX_ROLLING_HOURLY_DAYS &&
+    isRecord(value.days);
+  const days = modern ? sanitizeHourlyDays(value.days) : undefined;
+  if (days) {
+    pruneCodexHourlyDays(days, rollingHourlyDaySet(value.day));
+  }
   return {
     day: value.day,
-    timeZone: resolveTimeZone(value.timeZone),
+    timeZone,
     indexedThrough: Math.max(0, finiteNumber(value.indexedThrough)),
-    hours: sanitizeHourlySlices(value.hours),
+    hours: days ? days[value.day] ?? {} : sanitizeHourlySlices(value.hours),
+    ...(days
+      ? {
+          windowDays: CODEX_ROLLING_HOURLY_DAYS,
+          days,
+        }
+      : {}),
   };
 }
 
@@ -3308,6 +3771,12 @@ function sanitizePeriodMigration(
   }
   return {
     timeZone: period.timeZone,
+    ...(optionalNumber(value.prefixEvents) !== undefined
+      ? { prefixEvents: Math.max(0, Math.floor(optionalNumber(value.prefixEvents)!)) }
+      : {}),
+    ...(optionalNumber(value.tokenEventsSeen) !== undefined
+      ? { tokenEventsSeen: Math.max(0, Math.floor(optionalNumber(value.tokenEventsSeen)!)) }
+      : {}),
     offset: Math.max(0, finiteNumber(value.offset)),
     discardingOversizedLine: value.discardingOversizedLine === true,
     parserState: sanitizeParserState(value.parserState, fileKey),
@@ -3328,6 +3797,8 @@ function sanitizeTodayMigration(
     timeZone: value.timeZone,
     indexedThrough: value.offset,
     hours: value.hours,
+    windowDays: value.windowDays,
+    days: value.days,
   });
   if (!today) {
     return undefined;
@@ -3344,6 +3815,12 @@ function sanitizeTodayMigration(
     discardingOversizedLine: value.discardingOversizedLine === true,
     parserState: sanitizeParserState(value.parserState, fileKey),
     hours: today.hours,
+    ...(today.windowDays === CODEX_ROLLING_HOURLY_DAYS && today.days
+      ? {
+          windowDays: CODEX_ROLLING_HOURLY_DAYS,
+          days: today.days,
+        }
+      : {}),
     qualityFlags: sanitizeQualityFlags(value.qualityFlags),
   };
 }
@@ -3518,6 +3995,39 @@ function sanitizeCoverage(value: unknown): CodexIndexCoverage {
     : dayKeyInZone(new Date(Date.now()), timeZone);
   const last7Days = sanitizeRange(period.last7Days);
   const last30Days = sanitizeRange(period.last30Days);
+  const rawHourly = isRecord(coverage.hourly) ? coverage.hourly : {};
+  const hourlyTimeZone = resolveTimeZone(
+    typeof rawHourly.timeZone === 'string' ? rawHourly.timeZone : timeZone,
+  );
+  const candidateHourlyDay = typeof rawHourly.asOfDay === 'string'
+    ? rawHourly.asOfDay
+    : '';
+  const hasValidHourly =
+    typeof rawHourly.timeZone === 'string' &&
+    rawHourly.windowDays === CODEX_ROLLING_HOURLY_DAYS &&
+    rollingDayKeysFromDayKey(candidateHourlyDay, 1)[0] === candidateHourlyDay;
+  const hourlyAsOfDay = hasValidHourly ? candidateHourlyDay : asOfDay;
+  const allowedHourlyDays = rollingHourlyDaySet(hourlyAsOfDay);
+  const rawHourlyDays = isRecord(rawHourly.days) ? rawHourly.days : {};
+  const hourlyDays = Object.fromEntries(
+    Object.entries(rawHourlyDays).flatMap(([day, raw]) => {
+      if (!allowedHourlyDays.has(day) || !isRecord(raw)) {
+        return [];
+      }
+      const indexedFiles = Math.max(0, finiteNumber(raw.indexedFiles));
+      const totalFiles = Math.max(0, finiteNumber(raw.totalFiles));
+      return [[day, {
+        day,
+        indexedFiles,
+        totalFiles,
+        indexedBytes: Math.max(0, finiteNumber(raw.indexedBytes)),
+        totalBytes: Math.max(0, finiteNumber(raw.totalBytes)),
+        complete: hasValidHourly && raw.complete === true,
+      }]];
+    }),
+  );
+  const hourlyIndexedFiles = Math.max(0, finiteNumber(rawHourly.indexedFiles));
+  const hourlyTotalFiles = Math.max(0, finiteNumber(rawHourly.totalFiles));
   const rawToday = isRecord(coverage.today) ? coverage.today : {};
   const todayTimeZone = resolveTimeZone(
     typeof rawToday.timeZone === 'string' ? rawToday.timeZone : timeZone,
@@ -3562,6 +4072,17 @@ function sanitizeCoverage(value: unknown): CodexIndexCoverage {
       last30Days,
       allTime: sanitizeRange(period.allTime),
     },
+    hourly: {
+      timeZone: hourlyTimeZone,
+      asOfDay: hourlyAsOfDay,
+      windowDays: CODEX_ROLLING_HOURLY_DAYS,
+      indexedFiles: hourlyIndexedFiles,
+      totalFiles: hourlyTotalFiles,
+      indexedBytes: Math.max(0, finiteNumber(rawHourly.indexedBytes)),
+      totalBytes: Math.max(0, finiteNumber(rawHourly.totalBytes)),
+      complete: hasValidHourly && rawHourly.complete === true,
+      days: hourlyDays,
+    },
     today: {
       timeZone: todayTimeZone,
       day: todayDay,
@@ -3575,6 +4096,7 @@ function sanitizeCoverage(value: unknown): CodexIndexCoverage {
 }
 
 function markLineageRescanRequired(index: CodexIndexV3): CodexIndexV3 {
+  index.indexGeneration = Math.max(1, Math.floor(index.indexGeneration ?? 0) + 1);
   for (const contribution of Object.values(index.files)) {
     delete contribution.lineage;
     delete contribution.lineageReconciliation;
@@ -3605,6 +4127,12 @@ function markLineageRescanRequired(index: CodexIndexV3): CodexIndexV3 {
   index.coverage.today.indexedFiles = 0;
   index.coverage.today.indexedBytes = 0;
   index.coverage.today.complete = false;
+  if (index.coverage.hourly) {
+    index.coverage.hourly.indexedFiles = 0;
+    index.coverage.hourly.indexedBytes = 0;
+    index.coverage.hourly.complete = false;
+    index.coverage.hourly.days = {};
+  }
   return index;
 }
 
@@ -3622,11 +4150,15 @@ function migrateIndexV1(index: LegacyCodexIndexV1): CodexIndexV3 {
       false,
     );
   }
+  const quotaHistory = sanitizeCodexQuotaHistory(index.quotaHistory);
   return {
     schemaVersion: 3,
     files,
     aggregate: sanitizeProviderAggregate(index.aggregate),
     coverage: sanitizeCoverage(index.coverage),
+    ...(quotaHistory.length > 0
+      ? { quotaHistory }
+      : {}),
   };
 }
 
@@ -3649,6 +4181,10 @@ function sanitizeFileContribution(
   const safeOffset = offsetOverride ?? Math.max(0, finiteNumber(contribution.offset));
   const limit = sanitizeLimit(contribution.limit);
   const limits = sanitizeLimits(contribution.limits);
+  const quotaHistory = sanitizeCodexQuotaHistory(
+    contribution.quotaHistory,
+    CODEX_FILE_QUOTA_HISTORY_LIMIT,
+  );
   const lineage = sanitizeLineage(contribution.lineage);
   const lineageReconciliation = sanitizeLineageReconciliation(
     contribution.lineageReconciliation,
@@ -3674,6 +4210,20 @@ function sanitizeFileContribution(
   );
   if (periodMigration) {
     periodMigration.offset = Math.min(periodMigration.offset, safeOffset);
+    if (lineage) {
+      if (periodMigration.prefixEvents !== undefined) {
+        periodMigration.prefixEvents = Math.min(
+          periodMigration.prefixEvents,
+          lineage.tokenEvents,
+        );
+      }
+      if (periodMigration.tokenEventsSeen !== undefined) {
+        periodMigration.tokenEventsSeen = Math.min(
+          periodMigration.tokenEventsSeen,
+          lineage.tokenEvents,
+        );
+      }
+    }
   }
   const todayMigration = sanitizeTodayMigration(
     contribution.todayMigration,
@@ -3719,6 +4269,7 @@ function sanitizeFileContribution(
     aggregate,
     ...(limit ? { limit } : {}),
     ...(limits ? { limits } : {}),
+    ...(quotaHistory.length > 0 ? { quotaHistory } : {}),
     qualityFlags: sanitizeQualityFlags(contribution.qualityFlags),
     ...(typeof contribution.identityChecked === 'boolean'
       ? { identityChecked: contribution.identityChecked }
@@ -3758,11 +4309,19 @@ function sanitizeIndexV2(value: unknown): CodexIndexV3 {
       delete contribution.todayMigration;
     }
   }
+  const quotaHistory = sanitizeCodexQuotaHistory(index.quotaHistory);
   return {
     schemaVersion: 3,
+    ...(typeof index.indexGeneration === 'number' &&
+      Number.isSafeInteger(index.indexGeneration) && index.indexGeneration > 0
+      ? { indexGeneration: index.indexGeneration }
+      : {}),
     files,
     aggregate: sanitizeProviderAggregate(index.aggregate),
     coverage,
+    ...(quotaHistory.length > 0
+      ? { quotaHistory }
+      : {}),
   };
 }
 
@@ -3770,7 +4329,7 @@ function requiresTokenSemanticsRescan(index: CodexIndexV3): boolean {
   return Object.values(index.files).some((contribution) =>
     !isRecord(contribution) ||
     !isRecord(contribution.parserState) ||
-    contribution.parserState.schemaVersion !== 3
+    contribution.parserState.schemaVersion !== 4
   );
 }
 
@@ -3811,7 +4370,7 @@ export async function loadCodexIndex(
     if (error instanceof SyntaxError) {
       await quarantineCorruptCodexIndex(indexPath);
       onRecovery?.({ reason: 'invalid-json' });
-      return createEmptyCodexIndex(timeZone);
+      return recoveredIndex(timeZone);
     }
     throw error;
   }
@@ -3830,7 +4389,7 @@ export async function loadCodexIndex(
   }
   await quarantineCorruptCodexIndex(indexPath);
   onRecovery?.({ reason: 'unsupported-schema' });
-  return createEmptyCodexIndex(timeZone);
+  return recoveredIndex(timeZone);
 }
 
 export async function saveCodexIndexAtomic(
diff --git a/src/providers/codex/codexIndexClient.ts b/src/providers/codex/codexIndexClient.ts
index 96ceeb0b..bded606b 100644
--- a/src/providers/codex/codexIndexClient.ts
+++ b/src/providers/codex/codexIndexClient.ts
@@ -33,6 +33,7 @@ interface ActiveRefresh {
   reject: (error: CodexWorkerError) => void;
   progressListeners: Array<(progress: CodexIndexProgress) => void>;
   cancelSent: boolean;
+  finishing: boolean;
   profile: 'background' | 'foreground';
 }
 
@@ -48,6 +49,9 @@ export class CodexIndexClient {
   private worker: CodexWorkerLike | null = null;
   private active: ActiveRefresh | null = null;
   private disposed = false;
+  private termination: Promise<void> | null = null;
+  private terminationFailure: unknown = null;
+  private disposal: Promise<void> | null = null;
 
   constructor(private readonly workerFactory: CodexWorkerFactory = defaultWorkerFactory) {}
 
@@ -91,6 +95,7 @@ export class CodexIndexClient {
       reject,
       progressListeners: onProgress ? [onProgress] : [],
       cancelSent: false,
+      finishing: false,
       profile: input.profile ?? 'background',
     };
     worker.postMessage({ type: 'refresh', requestId, ...input });
@@ -108,19 +113,51 @@ export class CodexIndexClient {
     });
   }
 
-  dispose(): void {
-    if (this.disposed) {
-      return;
+  async whenIdle(): Promise<void> {
+    const active = this.active;
+    if (active) {
+      try {
+        await active.promise;
+      } catch {
+        // Idle is a lifecycle condition, independent of the refresh outcome.
+      }
+    }
+    if (this.termination) {
+      try {
+        await this.termination;
+      } catch {
+        // A terminal refresh already surfaces termination failure to callers.
+      }
     }
+  }
+
+  dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
     this.disposed = true;
-    if (this.active) {
-      this.active.reject(
+    const active = this.active;
+    if (active) {
+      active.reject(
         new CodexWorkerError('disposed', 'Codex index client is disposed'),
       );
       this.active = null;
     }
-    void this.worker?.terminate();
+    const worker = this.worker;
     this.worker = null;
+    const terminating = worker
+      ? Promise.resolve(worker.terminate())
+          .then(() => undefined)
+          .catch((error: unknown) => {
+            this.terminationFailure ??= error;
+            throw error;
+          })
+      : Promise.resolve();
+    this.disposal = Promise.all([
+      terminating,
+      this.termination ?? Promise.resolve(),
+    ]).then(() => {
+      if (this.terminationFailure) throw this.terminationFailure;
+    });
+    return this.disposal;
   }
 
   private ensureWorker(): CodexWorkerLike {
@@ -145,24 +182,58 @@ export class CodexIndexClient {
       }
       return;
     }
-    this.active = null;
-    if (message.type === 'result') {
-      active.resolve(message.result);
-    } else {
-      active.reject(new CodexWorkerError(message.error.code, message.error.message));
+    if (active.finishing) return;
+    active.finishing = true;
+    const terminal = message;
+    void this.terminateSettledWorker()
+      .then(() => {
+        if (this.active === active) this.active = null;
+        if (terminal.type === 'result') {
+          active.resolve(terminal.result);
+        } else {
+          active.reject(new CodexWorkerError(terminal.error.code, terminal.error.message));
+        }
+      })
+      .catch(() => {
+        if (this.active === active) this.active = null;
+        active.reject(new CodexWorkerError(
+          'worker-failed',
+          'Codex index worker could not be stopped safely',
+        ));
+      });
+  }
+
+  /** A worker owns no steady-state responsibility after one terminal reply. */
+  private async terminateSettledWorker(): Promise<void> {
+    const worker = this.worker;
+    this.worker = null;
+    const termination = worker
+      ? Promise.resolve(worker.terminate()).then(() => undefined)
+      : Promise.resolve();
+    this.termination = termination;
+    try {
+      await termination;
+    } catch (error) {
+      this.terminationFailure ??= error;
+      throw error;
+    } finally {
+      if (this.termination === termination) this.termination = null;
     }
   }
 
   private handleWorkerFailure(): void {
-    if (this.active) {
-      this.active.reject(
+    const active = this.active;
+    if (!active || active.finishing) return;
+    active.finishing = true;
+    const settle = (): void => {
+      if (this.active === active) this.active = null;
+      active.reject(
         new CodexWorkerError(
           'worker-failed',
           'Codex index worker stopped unexpectedly',
         ),
       );
-      this.active = null;
-    }
-    this.worker = null;
+    };
+    void this.terminateSettledWorker().then(settle, settle);
   }
 }
diff --git a/src/providers/codex/codexIndexWorker.ts b/src/providers/codex/codexIndexWorker.ts
index 8d10bb9f..b125c217 100644
--- a/src/providers/codex/codexIndexWorker.ts
+++ b/src/providers/codex/codexIndexWorker.ts
@@ -112,7 +112,8 @@ export async function runCodexWorkerRefresh(
       const metadataMs = now() - metadataStarted;
       const parseStarted = now();
       const foreground = request.profile === 'foreground';
-      const expeditedBackfill = needsExpeditedBackfill(
+      const allowHistoricalBackfill = request.allowHistoricalBackfill !== false;
+      const expeditedBackfill = allowHistoricalBackfill && needsExpeditedBackfill(
         previous,
         manifest.files.length,
       );
@@ -149,6 +150,7 @@ export async function runCodexWorkerRefresh(
               requestId: request.requestId,
               progress,
             }),
+          allowHistoricalBackfill,
           ...(filePassPool ? { filePassBatch: filePassPool.run } : {}),
         });
       } finally {
diff --git a/src/providers/codex/codexParser.ts b/src/providers/codex/codexParser.ts
index e67adb98..32c9e261 100644
--- a/src/providers/codex/codexParser.ts
+++ b/src/providers/codex/codexParser.ts
@@ -23,7 +23,7 @@ export interface CodexRawTokenCounts {
 }
 
 export interface CodexParserState {
-  schemaVersion: 1 | 2 | 3;
+  schemaVersion: 1 | 2 | 3 | 4;
   fileKey: string;
   sessionKey: string;
   treeKey?: string;
@@ -63,7 +63,10 @@ export function createCodexParserState(
   fileKey: string,
 ): CodexParserState {
   return {
-    schemaVersion: 3,
+    // Version 4 invalidates v2.3.0's schema-3 parser snapshots after the
+    // request-level token attribution rules changed. The outer persisted
+    // index remains schema 3; only each file's parser semantics are rebuilt.
+    schemaVersion: 4,
     fileKey,
     sessionKey: fileKey,
     identityLocked: false,
@@ -161,16 +164,43 @@ function componentDelta(
   current: CodexRawTokenCounts,
   previous: CodexRawTokenCounts,
 ): ProviderTokenCounts {
+  const inputTotal = Math.max(0, current.inputTokens - previous.inputTokens);
+  const outputTotal = Math.max(0, current.outputTokens - previous.outputTokens);
   return {
-    inputTotal: current.inputTokens - previous.inputTokens,
-    cachedInput: current.cachedInputTokens - previous.cachedInputTokens,
-    outputTotal: current.outputTokens - previous.outputTokens,
-    reasoningOutput:
-      current.reasoningOutputTokens - previous.reasoningOutputTokens,
-    sourceTotal: current.totalTokens - previous.totalTokens,
+    inputTotal,
+    cachedInput: Math.min(
+      inputTotal,
+      Math.max(0, current.cachedInputTokens - previous.cachedInputTokens),
+    ),
+    outputTotal,
+    reasoningOutput: Math.min(
+      outputTotal,
+      Math.max(
+        0,
+        current.reasoningOutputTokens - previous.reasoningOutputTokens,
+      ),
+    ),
+    sourceTotal: inputTotal + outputTotal,
   };
 }
 
+function componentDeltaNeedsClamp(
+  current: CodexRawTokenCounts,
+  previous: CodexRawTokenCounts,
+): boolean {
+  const inputTotal = Math.max(0, current.inputTokens - previous.inputTokens);
+  const cachedInput = Math.max(
+    0,
+    current.cachedInputTokens - previous.cachedInputTokens,
+  );
+  const outputTotal = Math.max(0, current.outputTokens - previous.outputTokens);
+  const reasoningOutput = Math.max(
+    0,
+    current.reasoningOutputTokens - previous.reasoningOutputTokens,
+  );
+  return cachedInput > inputTotal || reasoningOutput > outputTotal;
+}
+
 function containedHighWater(
   current: CodexRawTokenCounts,
   previous: CodexRawTokenCounts,
@@ -315,9 +345,8 @@ function parseTurnContext(
   const model = Object.prototype.hasOwnProperty.call(entry.payload, 'model')
     ? sanitizeCodexMetadataLabel(entry.payload.model)
     : state.model;
-  const effort = Object.prototype.hasOwnProperty.call(entry.payload, 'effort')
-    ? sanitizeCodexMetadataLabel(entry.payload.effort)
-    : state.effort;
+  const effortEvidence = explicitReasoningEffort(entry.payload);
+  const effort = effortEvidence.present ? effortEvidence.value : state.effort;
   return {
     state: {
       ...state,
@@ -328,6 +357,68 @@ function parseTurnContext(
   };
 }
 
+const CODEX_REASONING_EFFORTS = new Set([
+  'none',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+  'ultra',
+]);
+
+function normalizedReasoningEffort(value: unknown): string | undefined {
+  const label = sanitizeCodexMetadataLabel(value)?.toLowerCase();
+  return label && CODEX_REASONING_EFFORTS.has(label) ? label : undefined;
+}
+
+function explicitReasoningEffort(payload: JsonObject): {
+  present: boolean;
+  value?: string;
+} {
+  const raw: unknown[] = [];
+  const collect = (object: JsonObject | undefined, key: string): void => {
+    if (object && Object.prototype.hasOwnProperty.call(object, key)) {
+      raw.push(object[key]);
+    }
+  };
+  collect(payload, 'effort');
+  const collaborationMode = isObject(payload.collaboration_mode)
+    ? payload.collaboration_mode
+    : undefined;
+  const collaborationSettings = collaborationMode &&
+    isObject(collaborationMode.settings)
+    ? collaborationMode.settings
+    : undefined;
+  collect(collaborationSettings, 'reasoning_effort');
+  const threadSettings = isObject(payload.thread_settings)
+    ? payload.thread_settings
+    : undefined;
+  collect(threadSettings, 'reasoning_effort');
+  const threadCollaboration = threadSettings &&
+    isObject(threadSettings.collaboration_mode)
+    ? threadSettings.collaboration_mode
+    : undefined;
+  const threadCollaborationSettings = threadCollaboration &&
+    isObject(threadCollaboration.settings)
+    ? threadCollaboration.settings
+    : undefined;
+  collect(threadCollaborationSettings, 'reasoning_effort');
+  const item = isObject(payload.item) ? payload.item : undefined;
+  collect(item, 'reasoning_effort');
+  if (raw.length === 0) {
+    return { present: false };
+  }
+  const normalized = raw.map(normalizedReasoningEffort);
+  const values = new Set(
+    normalized.filter((value): value is string => value !== undefined),
+  );
+  return normalized.some((value) => value === undefined) || values.size !== 1
+    ? { present: true }
+    : { present: true, value: [...values][0] };
+}
+
 function nestedObject(
   object: JsonObject,
   ...keys: string[]
@@ -524,8 +615,20 @@ function parseTokenCount(
     : last
       ? exactTokenCounts(last)
       : componentDelta(nextHighWater!, previous);
+  const componentClamped = Boolean(
+    !duplicate && !last && nextHighWater &&
+    componentDeltaNeedsClamp(nextHighWater, previous),
+  );
+  const flaggedState = componentClamped
+    ? withFlag(
+        regressed ? withFlag(state, 'counter-regression') : state,
+        'component-delta-clamped',
+      )
+    : regressed
+      ? withFlag(state, 'counter-regression')
+      : state;
   let nextState: CodexParserState = {
-    ...(regressed ? withFlag(state, 'counter-regression') : state),
+    ...flaggedState,
     ...(nextHighWater ? { highWater: nextHighWater } : {}),
     previousSnapshotSignature: signature,
   };
@@ -582,14 +685,18 @@ export function parseCodexLine(
     if (!isObject(entry.payload)) {
       return { state: withFlag(state, 'invalid-event-payload'), events: [] };
     }
+    const effortEvidence = explicitReasoningEffort(entry.payload);
+    const eventState = effortEvidence.present
+      ? { ...state, effort: effortEvidence.value }
+      : state;
     if (stringField(entry.payload, 'type') === 'token_count') {
-      return parseTokenCount(entry, entry.payload, state, pseudonymize);
+      return parseTokenCount(entry, entry.payload, eventState, pseudonymize);
     }
     if (stringField(entry.payload, 'type') === 'task_started') {
-      return { state, events: [], lineageBoundary: true };
+      return { state: eventState, events: [], lineageBoundary: true };
     }
     return {
-      state,
+      state: eventState,
       events: [],
       structural: structuralFromEventMessage(entry, entry.payload),
     };
diff --git a/src/providers/codex/codexPeriodIndex.ts b/src/providers/codex/codexPeriodIndex.ts
index 0fce1bdd..5f0bf1c9 100644
--- a/src/providers/codex/codexPeriodIndex.ts
+++ b/src/providers/codex/codexPeriodIndex.ts
@@ -27,6 +27,10 @@ export interface CodexFilePeriodIndex {
   timeZone: string;
   indexedThrough: number;
   days: Record<string, CodexDailySlice>;
+  /** Semantic marker for period data produced after lineage filtering. */
+  lineageVersion?: number;
+  /** The lineage prefix excluded while this period was built. */
+  lineagePrefixEvents?: number;
 }
 
 export interface CodexHourlySlice {
@@ -34,15 +38,28 @@ export interface CodexHourlySlice {
   byModel: Record<string, ProviderTokenCounts>;
 }
 
+export const CODEX_ROLLING_HOURLY_DAYS = 30;
+
+/** Sparse local civil-day -> hour buckets. Empty dates and hours are omitted. */
+export type CodexHourlyDays = Record<
+  string,
+  Record<string, CodexHourlySlice>
+>;
+
 /**
- * Deliberately ephemeral across civil days: only one target day is persisted,
- * and empty hours do not consume index space.
+ * The historic `day` / `hours` fields remain as the current-day compatibility
+ * projection. New indexes also persist `days`, a sparse rolling window whose
+ * semantic width is identified by `windowDays`.
  */
 export interface CodexFileTodayIndex {
   day: string;
   timeZone: string;
   indexedThrough: number;
   hours: Record<string, CodexHourlySlice>;
+  /** Missing on v2.3.0 one-day sidecars and therefore migration-required. */
+  windowDays?: number;
+  /** Missing on v2.3.0 one-day sidecars and therefore migration-required. */
+  days?: CodexHourlyDays;
 }
 
 export interface CodexTodayMigrationState extends CodexJsonlCursor {
@@ -52,16 +69,151 @@ export interface CodexTodayMigrationState extends CodexJsonlCursor {
   tokenEventsSeen: number;
   parserState: CodexParserState;
   hours: Record<string, CodexHourlySlice>;
+  /** Missing on v2.3.0 drafts; a missing value restarts the bounded pass. */
+  windowDays?: number;
+  /** Sparse rolling buckets checkpointed with the existing file cursor. */
+  days?: CodexHourlyDays;
   qualityFlags: string[];
 }
 
 export interface CodexPeriodMigrationState extends CodexJsonlCursor {
   timeZone: string;
+  /** Missing on pre-fix drafts; those drafts must restart from byte zero. */
+  prefixEvents?: number;
+  /** Number of lineage token events consumed by the resumable cursor. */
+  tokenEventsSeen?: number;
   parserState: CodexParserState;
   days: Record<string, CodexDailySlice>;
   qualityFlags: string[];
 }
 
+/** Increment when the period lineage filtering algorithm changes. */
+export const CODEX_PERIOD_LINEAGE_VERSION = 1;
+
+export function isCurrentCodexPeriodLineage(
+  period: CodexFilePeriodIndex | undefined,
+  prefixEvents: number,
+): boolean {
+  return Boolean(
+    period &&
+    period.lineageVersion === CODEX_PERIOD_LINEAGE_VERSION &&
+    period.lineagePrefixEvents === Math.max(0, Math.floor(prefixEvents)),
+  );
+}
+
+/**
+ * Pre-fix schema-3 indexes did not carry a lineage marker. A bounded
+ * aggregate-size check can still safely read those legacy slices; once a
+ * marker exists, it must match the current filtering algorithm exactly.
+ */
+export function isCompatibleCodexPeriodLineage(
+  period: CodexFilePeriodIndex | undefined,
+  prefixEvents: number,
+): boolean {
+  if (!period) {
+    return false;
+  }
+  const hasMarker =
+    period.lineageVersion !== undefined ||
+    period.lineagePrefixEvents !== undefined;
+  return !hasMarker || isCurrentCodexPeriodLineage(period, prefixEvents);
+}
+
+const TOKEN_FIELDS = [
+  'inputTotal',
+  'cachedInput',
+  'cacheWriteInput',
+  'outputTotal',
+  'reasoningOutput',
+  'sourceTotal',
+] as const;
+
+type TokenField = (typeof TOKEN_FIELDS)[number];
+
+function tokenValue(tokens: ProviderTokenCounts, field: TokenField): number {
+  const value = tokens[field];
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, value)
+    : 0;
+}
+
+function tokenShapeIsValid(tokens: ProviderTokenCounts): boolean {
+  return TOKEN_FIELDS.every((field) => {
+    const value = tokens[field];
+    return value === undefined ||
+      (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+  });
+}
+
+function sumTokenBuckets(
+  buckets: readonly ProviderTokenCounts[],
+): ProviderTokenCounts {
+  const total: ProviderTokenCounts = {
+    inputTotal: 0,
+    cachedInput: 0,
+    cacheWriteInput: 0,
+    outputTotal: 0,
+    reasoningOutput: 0,
+    sourceTotal: 0,
+  };
+  for (const bucket of buckets) {
+    for (const field of TOKEN_FIELDS) {
+      total[field] = tokenValue(total, field) + tokenValue(bucket, field);
+    }
+  }
+  return total;
+}
+
+function tokensFitWithin(
+  actual: ProviderTokenCounts,
+  allowed: ProviderTokenCounts,
+): boolean {
+  if (!tokenShapeIsValid(actual) || !tokenShapeIsValid(allowed)) {
+    return false;
+  }
+  // Older persisted DTOs legitimately omit optional buckets such as
+  // reasoningOutput, sourceTotal, or cacheWriteInput. An omitted allowance is
+  // unknown, not zero; constraining it to zero would reject otherwise valid
+  // legacy period projections and make the reader fall back unnecessarily.
+  return TOKEN_FIELDS.every((field) => {
+    if (allowed[field] === undefined) {
+      return true;
+    }
+    return tokenValue(actual, field) <= tokenValue(allowed, field);
+  });
+}
+
+/**
+ * A period is a subset of a file's all-time aggregate. This inexpensive
+ * invariant lets readers reject old/replayed sidecars immediately, before a
+ * background rebuild has finished.
+ */
+export function codexPeriodFitsAggregate(
+  period: CodexFilePeriodIndex | undefined,
+  aggregateTotal: ProviderTokenCounts,
+): boolean {
+  if (!period || !tokenShapeIsValid(aggregateTotal)) {
+    return false;
+  }
+  const periodTotal = sumTokenBuckets(
+    Object.values(period.days).map((slice) => slice.total),
+  );
+  if (!tokensFitWithin(periodTotal, aggregateTotal)) {
+    return false;
+  }
+  return Object.values(period.days).every((slice) =>
+    tokenShapeIsValid(slice.total) &&
+    tokensFitWithin(
+      sumTokenBuckets(Object.values(slice.byModel)),
+      slice.total,
+    ) &&
+    tokensFitWithin(
+      sumTokenBuckets(Object.values(slice.byEffort)),
+      slice.total,
+    ),
+  );
+}
+
 function zeroTokens(): ProviderTokenCounts {
   return {
     inputTotal: 0,
@@ -173,6 +325,43 @@ export function reduceCodexHourlySlice(
   addTokens(tokenBucket(slice.byModel, event.model ?? 'unknown'), event.tokens);
 }
 
+/**
+ * Add an event to a precomputed rolling civil-day window. Callers construct
+ * `allowedDays` once per file pass so multi-gigabyte backfills do not rebuild a
+ * 30-day set for every JSONL event.
+ */
+export function reduceCodexRollingHourlySlice(
+  days: CodexHourlyDays,
+  event: NormalizedUsageEvent,
+  allowedDays: ReadonlySet<string>,
+  timeZone: string,
+): void {
+  if (!Number.isFinite(event.timestamp) || event.timestamp <= 0) {
+    return;
+  }
+  const day = dayKeyInZone(new Date(event.timestamp), timeZone);
+  if (!allowedDays.has(day)) {
+    return;
+  }
+  const hours = (days[day] ??= {});
+  reduceCodexHourlySlice(hours, event, day, timeZone);
+  if (Object.keys(hours).length === 0) {
+    delete days[day];
+  }
+}
+
+/** Mutate a sparse rolling map in place, discarding every out-of-window day. */
+export function pruneCodexHourlyDays(
+  days: CodexHourlyDays,
+  allowedDays: ReadonlySet<string>,
+): void {
+  for (const day of Object.keys(days)) {
+    if (!allowedDays.has(day)) {
+      delete days[day];
+    }
+  }
+}
+
 export function reduceCodexStructuralSlice(
   days: Record<string, CodexDailySlice>,
   event: CodexStructuralEvent,
diff --git a/src/providers/codex/codexProvider.ts b/src/providers/codex/codexProvider.ts
index b75ee92f..32dcbb90 100644
--- a/src/providers/codex/codexProvider.ts
+++ b/src/providers/codex/codexProvider.ts
@@ -12,12 +12,27 @@ import {
   CodexIndexCoverage,
   CodexIndexProgress,
   CodexIndexRecovery,
+  CodexHourlyCoverage,
   CodexTodayCoverage,
   CodexIndexV1,
   createEmptyCodexIndex,
+  isReadableCodexPeriod,
   isCodexUsageContributionCurrent,
   loadCodexIndex,
 } from './codexIndex';
+import {
+  CODEX_ROLLING_HOURLY_DAYS,
+  codexPeriodFitsAggregate,
+  isCompatibleCodexPeriodLineage,
+} from './codexPeriodIndex';
+import {
+  appendCodexQuotaHistory,
+  CODEX_QUOTA_HISTORY_LIMIT,
+  CODEX_QUOTA_RESET_CLUSTER_MS,
+  CodexQuotaObservation,
+  weeklyQuotaObservationsFromCodexHistory,
+  weeklyQuotaObservationsFromCodexLimit,
+} from './codexQuotaHistory';
 import { CodexIndexClient } from './codexIndexClient';
 import {
   CodexWorkerRefreshInput,
@@ -40,11 +55,15 @@ export interface CodexIndexClientLike {
     input: CodexWorkerRefreshInput,
     onProgress?: (progress: CodexIndexProgress) => void,
   ): Promise<CodexWorkerResult>;
-  dispose(): void;
+  cancel?(): void;
+  whenIdle?(): Promise<void>;
+  dispose(): void | Promise<void>;
 }
 
 export interface CodexProviderSnapshot {
   provider: 'codex';
+  /** Persisted index generation used to isolate migration completion state. */
+  indexGeneration?: number;
   total: ProviderTokenCounts;
   files: CodexFileAggregate[];
   coverage: CodexIndexCoverage;
@@ -53,6 +72,8 @@ export interface CodexProviderSnapshot {
   limit: ProviderLimitSnapshot | null;
   /** Aggregate-only inputs for reset-aligned API-equivalent value estimates. */
   weeklyValueInputs?: WeeklyValueInputs;
+  /** Exact sparse configured-zone hour coverage for the rolling 30-day view. */
+  hourlyCoverage?: CodexHourlyCoverage;
   /** Independent exact-hour backfill state for the current civil day. */
   todayCoverage: CodexTodayCoverage;
   todayPartial: boolean;
@@ -142,57 +163,81 @@ function aggregateTotal(
   return total;
 }
 
-function isAccountWideCodexLimit(snapshot: ProviderLimitSnapshot): boolean {
-  const id = (snapshot.limitId ?? '').trim().toLowerCase();
-  const name = (snapshot.limitName ?? '').trim().toLowerCase();
-  return id === 'codex' || name === 'codex' || (!name && id === '');
-}
-
 function codexWeeklyValueInputs(
   files: CodexFileContribution[],
+  persistedHistory: readonly CodexQuotaObservation[] = [],
+  timeZone = 'UTC',
 ): WeeklyValueInputs {
-  const observations: WeeklyQuotaObservation[] = [];
+  const currentObservations: WeeklyQuotaObservation[] = [];
   const usage: WeeklyValueInputs['usage'] = [];
+  const seenObservations = new Set<string>();
+  const fileHistory: CodexQuotaObservation[] = [];
   for (const file of files) {
     const sourceKey = file.fileKey;
-    const seenSnapshots = new Set<string>();
+    fileHistory.push(...(file.quotaHistory ?? []));
     for (const snapshot of [
       ...Object.values(file.limits ?? {}),
       ...(file.limit ? [file.limit] : []),
     ]) {
-      if (!isAccountWideCodexLimit(snapshot)) {
-        continue;
-      }
-      const seriesKey = snapshot.limitId ?? snapshot.limitName ?? 'codex';
-      for (const window of snapshot.windows) {
-        if (
-          window.windowMinutes !== 7 * 24 * 60 ||
-          window.resetsAt === undefined
-        ) {
-          continue;
-        }
+      for (const observation of weeklyQuotaObservationsFromCodexLimit(
+        snapshot,
+        sourceKey,
+      )) {
         const identity = [
-          seriesKey,
-          snapshot.observedAt,
-          window.resetsAt,
-          window.usedPercent,
+          observation.observedAt,
+          observation.resetAt,
+          observation.usedPercent,
+          observation.sourceKey ?? '',
         ].join('|');
-        if (seenSnapshots.has(identity)) {
-          continue;
+        if (!seenObservations.has(identity)) {
+          seenObservations.add(identity);
+          currentObservations.push(observation);
         }
-        seenSnapshots.add(identity);
-        observations.push({
-          provider: 'codex',
-          seriesKey,
-          ...(snapshot.limitName ? { seriesLabel: snapshot.limitName } : {}),
-          observedAt: snapshot.observedAt,
-          resetAt: window.resetsAt,
-          usedPercent: window.usedPercent,
-          sourceKey,
-        });
       }
     }
-    for (const slice of Object.values(file.aggregate.period?.days ?? {})) {
+  }
+
+  const cachedHistory = appendCodexQuotaHistory(
+    persistedHistory,
+    fileHistory,
+    CODEX_QUOTA_HISTORY_LIMIT,
+  );
+  const cachedObservations = weeklyQuotaObservationsFromCodexHistory(
+    cachedHistory,
+  ).filter((cached) => !currentObservations.some((current) =>
+    Math.abs(current.resetAt - cached.resetAt) <= CODEX_QUOTA_RESET_CLUSTER_MS &&
+    // A delayed line written at/after reset is ineligible for the closed
+    // window. It cannot shadow a useful pre-reset observation retained by the
+    // durable history.
+    current.observedAt < current.resetAt,
+  ));
+  const observations = [...currentObservations, ...cachedObservations];
+
+  for (const file of files) {
+    const sourceKey = file.fileKey;
+    const usageReady = isCodexUsageContributionCurrent(file) &&
+      !file.lineageReconciliation &&
+      (
+        !file.lineage ||
+        file.lineage.appliedPrefixEvents === file.lineage.desiredPrefixEvents
+      );
+    if (!usageReady) {
+      continue;
+    }
+    const period = file.aggregate.period;
+    const prefixEvents = file.lineage?.desiredPrefixEvents ?? 0;
+    if (
+      !period ||
+      period.timeZone !== timeZone ||
+      !isCompatibleCodexPeriodLineage(period, prefixEvents) ||
+      !codexPeriodFitsAggregate(period, file.aggregate.total)
+    ) {
+      // A pre-fix or still-rebuilding period projection may contain copied
+      // lineage records. Do not turn the reliable all-time total into a false
+      // model-priced weekly estimate; the next bounded refresh will rebuild it.
+      continue;
+    }
+    for (const slice of Object.values(period.days)) {
       const timestamp = slice.lastObservedAt ?? slice.firstObservedAt;
       if (timestamp === undefined) {
         continue;
@@ -234,27 +279,53 @@ function snapshotFromIndex(
     ),
   );
   const files = usageContributions
-    .map((file) => ({
-      ...file.aggregate,
-      session: {
-        ...file.aggregate.session,
-        sessionTitle: sessionTitles.get(file.aggregate.session.sessionKey),
-      },
-    }))
+    .map((file) => {
+      const periodReadable = isReadableCodexPeriod(
+        file,
+        index.coverage.period.timeZone,
+      );
+      return {
+        ...file.aggregate,
+        // Keep the trusted all-time aggregate visible, but do not let a
+        // rejected or rebuilding period projection reach any period consumer.
+        ...(periodReadable ? {} : { period: undefined }),
+        session: {
+          ...file.aggregate.session,
+          sessionTitle: sessionTitles.get(file.aggregate.session.sessionKey),
+        },
+      };
+    })
     .sort(
       (left, right) =>
         (right.session.startedAt ?? 0) - (left.session.startedAt ?? 0),
     );
   const limits = latestLimits(contributions);
+  const hourlyCoverage = index.coverage.hourly ?? {
+    timeZone: index.coverage.period.timeZone,
+    asOfDay: index.coverage.period.asOfDay,
+    windowDays: CODEX_ROLLING_HOURLY_DAYS,
+    indexedFiles: 0,
+    totalFiles: 0,
+    indexedBytes: 0,
+    totalBytes: 0,
+    complete: false,
+    days: {},
+  };
   return {
     provider: 'codex',
+    indexGeneration: index.indexGeneration,
     total: aggregateTotal(usageContributions),
     files,
     coverage: index.coverage,
     qualityFlags: qualityCounts(contributions),
     limits,
     limit: limits[0] ?? null,
-    weeklyValueInputs: codexWeeklyValueInputs(usageContributions),
+    weeklyValueInputs: codexWeeklyValueInputs(
+      usageContributions,
+      index.quotaHistory ?? [],
+      index.coverage.period.timeZone,
+    ),
+    hourlyCoverage,
     todayCoverage: index.coverage.today,
     todayPartial: !index.coverage.today.complete,
   };
@@ -275,6 +346,8 @@ export class CodexProvider {
   private lastProgress: CodexIndexProgress | undefined;
   private snapshotGeneration = 0;
   private persistedSnapshotLoad: Promise<CodexProviderSnapshot | null> | null = null;
+  private disposed = false;
+  private disposal: Promise<void> | null = null;
 
   constructor(
     private readonly options: CodexProviderOptions,
@@ -283,7 +356,7 @@ export class CodexProvider {
   ) {}
 
   async isAvailable(): Promise<boolean> {
-    if (!this.options.enabled) {
+    if (this.disposed || !this.options.enabled) {
       return false;
     }
     const [sessions, archive] = await Promise.all([
@@ -301,6 +374,7 @@ export class CodexProvider {
    * lineage reconciliation continues in the background.
    */
   async loadPersistedSnapshot(): Promise<CodexProviderSnapshot | null> {
+    if (this.disposed) return null;
     if (this.currentSnapshot) {
       return this.currentSnapshot;
     }
@@ -346,7 +420,14 @@ export class CodexProvider {
   async refresh(
     profile: 'background' | 'foreground' = 'background',
     onProgress?: (progress: CodexIndexProgress) => void,
+    allowHistoricalBackfill: boolean = true,
   ): Promise<CodexProviderResult> {
+    if (this.disposed) {
+      return {
+        outcome: 'unavailable',
+        snapshot: this.currentSnapshot ?? emptySnapshot(this.options.timeZone),
+      };
+    }
     if (!(await this.isAvailable())) {
       return {
         outcome: 'unavailable',
@@ -354,15 +435,17 @@ export class CodexProvider {
       };
     }
     this.client ??= this.clientFactory();
+    const client = this.client;
     this.lastProgress = undefined;
     try {
-      const result = await this.client.refresh(
+      const result = await client.refresh(
         {
           codexHome: this.options.codexHome,
           indexPath: this.options.indexPath,
           salt: this.options.salt,
           timeZone: this.options.timeZone,
           profile,
+          allowHistoricalBackfill,
         },
         (progress) => {
           this.lastProgress = progress;
@@ -381,7 +464,9 @@ export class CodexProvider {
           !result.index.coverage.identity.complete ||
           !result.index.coverage.period.last7Days.complete ||
           !result.index.coverage.period.last30Days.complete ||
-          !result.index.coverage.period.allTime.complete
+          !result.index.coverage.period.allTime.complete ||
+          (result.index.coverage.hourly !== undefined &&
+            !result.index.coverage.hourly.complete)
           ? 'partial'
           : 'success';
       return {
@@ -400,6 +485,11 @@ export class CodexProvider {
         },
       };
     } catch {
+      try {
+        await client.dispose();
+      } finally {
+        if (this.client === client) this.client = null;
+      }
       return {
         outcome: 'error',
         snapshot: this.currentSnapshot ?? emptySnapshot(this.options.timeZone),
@@ -412,9 +502,25 @@ export class CodexProvider {
     return this.currentSnapshot;
   }
 
-  dispose(): void {
+  cancel(): void {
+    this.client?.cancel?.();
+  }
+
+  async cancelAndWait(): Promise<void> {
+    const client = this.client;
+    client?.cancel?.();
+    await client?.whenIdle?.();
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
+    this.disposed = true;
     this.snapshotGeneration += 1;
-    this.client?.dispose();
+    const client = this.client;
     this.client = null;
+    this.disposal = Promise.resolve()
+      .then(() => client?.dispose())
+      .then(() => undefined);
+    await this.disposal;
   }
 }
diff --git a/src/providers/codex/codexQuotaHistory.ts b/src/providers/codex/codexQuotaHistory.ts
new file mode 100644
index 00000000..7568c7da
--- /dev/null
+++ b/src/providers/codex/codexQuotaHistory.ts
@@ -0,0 +1,195 @@
+import type {
+  ProviderLimitSnapshot,
+} from '../providerTypes';
+import type {
+  WeeklyQuotaObservation,
+} from '../../weeklyValue';
+
+/** The Codex secondary window is the only window used for weekly estimates. */
+export const CODEX_WEEKLY_WINDOW_MINUTES = 7 * 24 * 60;
+
+/** Reset timestamps from the same provider window may differ by a few minutes. */
+export const CODEX_QUOTA_RESET_CLUSTER_MS = 5 * 60 * 1000;
+
+/**
+ * Keep the per-file copy small. The index-level history below is the durable
+ * cross-file record; the per-file copy lets a changed or newly discovered file
+ * contribute its observations again without retaining every quota poll.
+ */
+export const CODEX_FILE_QUOTA_HISTORY_LIMIT = 16;
+
+/** A few hundred reset events are only a few kilobytes, but remain bounded. */
+export const CODEX_QUOTA_HISTORY_LIMIT = 256;
+
+/**
+ * Deliberately neutral persisted quota evidence. There is no account name,
+ * source key, token, credential, or raw provider label in this shape.
+ */
+export interface CodexQuotaObservation {
+  provider: 'codex';
+  seriesKey: 'codex';
+  observedAt: number;
+  resetAt: number;
+  usedPercent: number;
+}
+
+function finite(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function isAccountWideCodexLimit(snapshot: ProviderLimitSnapshot): boolean {
+  const id = (snapshot.limitId ?? '').trim().toLowerCase();
+  const name = (snapshot.limitName ?? '').trim().toLowerCase();
+  // Spark has its own rolling allowance and must never be folded into the
+  // account-wide Codex estimate. An explicit ID is authoritative: a generic
+  // display name must not broaden a model-specific allowance.
+  if (id) {
+    return id === 'codex';
+  }
+  return name === 'codex' || !name;
+}
+
+function normalizeObservation(value: unknown): CodexQuotaObservation | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  const observedAt = finite(record.observedAt);
+  const resetAt = finite(record.resetAt);
+  const usedPercent = finite(record.usedPercent);
+  if (
+    observedAt === undefined ||
+    resetAt === undefined ||
+    usedPercent === undefined ||
+    observedAt <= 0 ||
+    resetAt <= 0
+  ) {
+    return undefined;
+  }
+  return {
+    provider: 'codex',
+    seriesKey: 'codex',
+    observedAt,
+    resetAt,
+    usedPercent: Math.min(100, Math.max(0, usedPercent)),
+  };
+}
+
+/** Extract only account-wide weekly windows from a parsed local snapshot. */
+export function codexQuotaObservationsFromLimit(
+  snapshot: ProviderLimitSnapshot,
+): CodexQuotaObservation[] {
+  if (snapshot.provider !== 'codex' || !isAccountWideCodexLimit(snapshot)) {
+    return [];
+  }
+  return snapshot.windows.flatMap((window) => {
+    if (window.windowMinutes !== CODEX_WEEKLY_WINDOW_MINUTES) {
+      return [];
+    }
+    const observation = normalizeObservation({
+      observedAt: snapshot.observedAt,
+      resetAt: window.resetsAt,
+      usedPercent: window.usedPercent,
+    });
+    return observation ? [observation] : [];
+  });
+}
+
+function representative(
+  items: CodexQuotaObservation[],
+): CodexQuotaObservation {
+  // Prefer the latest sample that was actually observed before the reset. A
+  // delayed log line carrying an old reset must not replace a useful boundary
+  // sample with an observation that the weekly timeline will reject.
+  const beforeReset = items
+    .filter((item) => item.observedAt < item.resetAt)
+    .sort((left, right) =>
+      left.observedAt - right.observedAt || left.resetAt - right.resetAt,
+    );
+  if (beforeReset.length > 0) {
+    return beforeReset[beforeReset.length - 1];
+  }
+  return [...items].sort((left, right) =>
+    left.observedAt - right.observedAt || left.resetAt - right.resetAt,
+  )[items.length - 1];
+}
+
+/**
+ * Compact quota polls to one useful observation per reset boundary. This is
+ * intentionally different from retaining every percentage step: the product
+ * needs to know that an irregular reset happened, not to build a second poll
+ * database. The result is sorted oldest-first and capped by reset count.
+ */
+export function appendCodexQuotaHistory(
+  history: readonly CodexQuotaObservation[] = [],
+  additions: readonly CodexQuotaObservation[] = [],
+  limit = CODEX_QUOTA_HISTORY_LIMIT,
+): CodexQuotaObservation[] {
+  const all = [...history, ...additions]
+    .map(normalizeObservation)
+    .filter((item): item is CodexQuotaObservation => item !== undefined)
+    .sort((left, right) =>
+      left.resetAt - right.resetAt || left.observedAt - right.observedAt,
+    );
+  const groups: CodexQuotaObservation[][] = [];
+  for (const item of all) {
+    const current = groups[groups.length - 1];
+    // Compare with the beginning of the group. Comparing with the previous
+    // item would let a chain of small skews merge two genuinely different
+    // reset boundaries that are more than the allowed cluster width apart.
+    const currentResetAt = current?.[0]?.resetAt;
+    if (
+      current &&
+      currentResetAt !== undefined &&
+      item.resetAt - currentResetAt <= CODEX_QUOTA_RESET_CLUSTER_MS
+    ) {
+      current.push(item);
+    } else {
+      groups.push([item]);
+    }
+  }
+  const compacted = groups.map(representative).sort((left, right) =>
+    left.resetAt - right.resetAt || left.observedAt - right.observedAt,
+  );
+  return compacted.slice(-Math.max(1, Math.floor(limit)));
+}
+
+/** Sanitize untrusted persisted data without carrying through raw fields. */
+export function sanitizeCodexQuotaHistory(
+  value: unknown,
+  limit = CODEX_QUOTA_HISTORY_LIMIT,
+): CodexQuotaObservation[] {
+  const raw = Array.isArray(value) ? value : [];
+  const normalized = raw
+    .map(normalizeObservation)
+    .filter((item): item is CodexQuotaObservation => item !== undefined);
+  return appendCodexQuotaHistory([], normalized, limit);
+}
+
+export function weeklyQuotaObservationsFromCodexHistory(
+  history: readonly CodexQuotaObservation[],
+): WeeklyQuotaObservation[] {
+  return history.map((item) => ({
+    provider: 'codex' as const,
+    seriesKey: 'codex',
+    observedAt: item.observedAt,
+    resetAt: item.resetAt,
+    usedPercent: item.usedPercent,
+  }));
+}
+
+export function weeklyQuotaObservationsFromCodexLimit(
+  snapshot: ProviderLimitSnapshot,
+  sourceKey?: string,
+): WeeklyQuotaObservation[] {
+  return codexQuotaObservationsFromLimit(snapshot).map((item) => ({
+    provider: 'codex' as const,
+    seriesKey: 'codex',
+    observedAt: item.observedAt,
+    resetAt: item.resetAt,
+    usedPercent: item.usedPercent,
+    ...(sourceKey ? { sourceKey } : {}),
+  }));
+}
diff --git a/src/providers/codex/codexUsage.ts b/src/providers/codex/codexUsage.ts
index b2b6e26d..42fb64a3 100644
--- a/src/providers/codex/codexUsage.ts
+++ b/src/providers/codex/codexUsage.ts
@@ -1,13 +1,20 @@
 import { CodexProviderSnapshot } from './codexProvider';
 import {
   CodexFileAggregate,
+  CodexHourlyCoverage,
   CodexIndexCoverage,
   CodexPeriodCoverage,
   CodexRangeCoverage,
   CodexStructuralSummary,
   CodexTodayCoverage,
 } from './codexIndex';
-import { rollingDayKeysFromDayKey } from '../../dateKeys';
+import { formatHourLabel, rollingDayKeysFromDayKey } from '../../dateKeys';
+import {
+  CODEX_ROLLING_HOURLY_DAYS,
+  CodexDailySlice,
+  CODEX_PERIOD_LINEAGE_VERSION,
+  codexPeriodFitsAggregate,
+} from './codexPeriodIndex';
 import {
   freshInputPlusOutput,
   processedTokens,
@@ -132,12 +139,15 @@ export interface CodexPeriodUsageView {
 
 export interface CodexHourlyUsageView {
   hour: string;
+  label: string;
   total: CodexMetricTotals;
   apiEquivalent: EquivalentCostBreakdown;
   threads: number;
 }
 
 export interface CodexTokenComposition {
+  /** Uncached input plus output. Kept outside the stack because output is already a segment. */
+  uncachedUsage: number;
   freshInput: number;
   cachedInput: number;
   output: number;
@@ -170,6 +180,9 @@ export interface CodexUsageView {
   /** Exact, sparse current-day hours from the independently resumable sidecar. */
   todayHourly: CodexHourlyUsageView[];
   todayCoverage: CodexTodayCoverage;
+  /** Sparse data-day -> exact hour rows for the configured rolling window. */
+  last30DaysHourlyByDay: Record<string, CodexHourlyUsageView[]>;
+  hourlyCoverage: CodexHourlyCoverage;
   lastTask: CodexUsageScopeView | null;
   lastTaskIdentity: CodexTaskIdentityView | null;
   last7Days: CodexUsageScopeView;
@@ -196,7 +209,10 @@ export interface CodexUsageView {
   weeklyValueInputs?: WeeklyValueInputs;
 }
 
-const MAX_DAILY_ROWS = 90;
+// Keep one complete GitHub-style share-card year plus a small boundary margin.
+// The existing table can scroll this bounded view, while Compare reuses it
+// directly instead of rescanning source logs or creating a second cache.
+const MAX_DAILY_ROWS = 370;
 const MAX_RECENT_THREAD_ROWS = 1_000;
 const HIGH_EFFORTS = new Set(['high', 'xhigh', 'max', 'ultra']);
 
@@ -235,8 +251,10 @@ export function tokenComposition(
   const input = Math.max(0, total.input);
   const cachedInput = Math.min(input, Math.max(0, total.cachedInput));
   const output = Math.max(0, total.output);
+  const freshInput = Math.max(0, input - cachedInput);
   return {
-    freshInput: Math.max(0, input - cachedInput),
+    uncachedUsage: freshInput + output,
+    freshInput,
     cachedInput,
     output,
     reasoningWithinOutput: Math.min(output, Math.max(0, total.reasoning)),
@@ -282,6 +300,37 @@ function addBuckets(
     addTokens(current, tokens);
     target.set(key, current);
   }
+  const attributed = zeroTokens();
+  for (const [, tokens] of entries) {
+    addTokens(attributed, tokens);
+  }
+  const inputTotal = Math.max(0, fallback.inputTotal - attributed.inputTotal);
+  const outputTotal = Math.max(0, fallback.outputTotal - attributed.outputTotal);
+  const residual: ProviderTokenCounts = {
+    inputTotal,
+    cachedInput: Math.min(
+      inputTotal,
+      Math.max(0, (fallback.cachedInput ?? 0) - (attributed.cachedInput ?? 0)),
+    ),
+    outputTotal,
+    reasoningOutput: Math.min(
+      outputTotal,
+      Math.max(
+        0,
+        (fallback.reasoningOutput ?? 0) - (attributed.reasoningOutput ?? 0),
+      ),
+    ),
+  };
+  if (
+    residual.inputTotal > 0 ||
+    (residual.cachedInput ?? 0) > 0 ||
+    residual.outputTotal > 0 ||
+    (residual.reasoningOutput ?? 0) > 0
+  ) {
+    const unknown = target.get('unknown') ?? zeroTokens();
+    addTokens(unknown, residual);
+    target.set('unknown', unknown);
+  }
 }
 
 function bucketRows(
@@ -289,6 +338,14 @@ function bucketRows(
 ): Array<{ key: string; totals: CodexMetricTotals }> {
   return [...buckets.entries()]
     .map(([key, tokens]) => ({ key, totals: metrics(tokens) }))
+    .filter(({ totals }) =>
+      totals.processed > 0 ||
+      totals.fresh > 0 ||
+      totals.input > 0 ||
+      totals.cachedInput > 0 ||
+      totals.output > 0 ||
+      totals.reasoning > 0,
+    )
     .sort(
       (left, right) =>
         right.totals.processed - left.totals.processed ||
@@ -308,6 +365,39 @@ function apiEquivalentForBuckets(
   );
 }
 
+function fallbackPeriodSlice(total: ProviderTokenCounts): CodexDailySlice {
+  return {
+    total,
+    byModel: {},
+    byEffort: {},
+    structural: zeroStructural(),
+  };
+}
+
+/**
+ * Period sidecars are a configured-zone, model-aware projection. A legacy or
+ * currently rebuilding sidecar must not be allowed to inflate a range beyond
+ * the verified per-file all-time aggregate. The UTC-keyed all-time day map is
+ * a conservative temporary fallback until the zone-aware sidecar is rebuilt;
+ * it preserves totals without pretending to know model/day attribution.
+ */
+function periodSlicesForFile(
+  file: CodexFileAggregate,
+  timeZone: string,
+): Array<[string, CodexDailySlice]> {
+  if (
+    file.period?.timeZone === timeZone &&
+    (file.period.lineageVersion === undefined ||
+      file.period.lineageVersion === CODEX_PERIOD_LINEAGE_VERSION) &&
+    codexPeriodFitsAggregate(file.period, file.total)
+  ) {
+    return Object.entries(file.period.days);
+  }
+  return Object.entries(file.byDay)
+    .filter(([day]) => /^\d{4}-\d{2}-\d{2}$/.test(day))
+    .map(([day, total]) => [day, fallbackPeriodSlice(total)]);
+}
+
 function ratio(numerator: number, denominator: number): number {
   return denominator > 0 ? numerator / denominator : 0;
 }
@@ -394,10 +484,7 @@ function scopeFromPeriodDays(
   let approvalReviewerThreads = 0;
 
   for (const file of files) {
-    if (file.period?.timeZone !== timeZone) {
-      continue;
-    }
-    const slices = Object.entries(file.period.days)
+    const slices = periodSlicesForFile(file, timeZone)
       .filter(([day]) => selectedKeys.has(day))
       .map(([, slice]) => slice);
     if (slices.length === 0) {
@@ -474,10 +561,15 @@ function observedAt(file: CodexFileAggregate): number {
 function sortedBucketKeys(
   buckets: Record<string, ProviderTokenCounts>,
 ): string[] {
-  const rows = Object.entries(buckets);
-  if (rows.length === 0) {
+  const entries = Object.entries(buckets);
+  if (entries.length === 0) {
     return ['unknown'];
   }
+  const rows = entries.filter(([, tokens]) =>
+    processedTokens(tokens) > 0 ||
+    (tokens.cachedInput ?? 0) > 0 ||
+    (tokens.reasoningOutput ?? 0) > 0,
+  );
   return rows
     .sort(
       ([leftKey, left], [rightKey, right]) =>
@@ -502,10 +594,7 @@ function dailyRows(
     }
   >();
   for (const file of files) {
-    if (file.period?.timeZone !== timeZone) {
-      continue;
-    }
-    for (const [day, slice] of Object.entries(file.period.days)) {
+    for (const [day, slice] of periodSlicesForFile(file, timeZone)) {
       const row = days.get(day) ?? {
         tokens: zeroTokens(),
         models: new Map<string, ProviderTokenCounts>(),
@@ -556,10 +645,7 @@ function monthlyRows(
     }
   >();
   for (const file of files) {
-    if (file.period?.timeZone !== timeZone) {
-      continue;
-    }
-    for (const [day, slice] of Object.entries(file.period.days)) {
+    for (const [day, slice] of periodSlicesForFile(file, timeZone)) {
       const period = day.slice(0, 7);
       if (!/^\d{4}-\d{2}$/.test(period)) {
         continue;
@@ -576,7 +662,9 @@ function monthlyRows(
     }
   }
   return [...months.entries()]
-    .sort(([left], [right]) => right.localeCompare(left))
+    // Monthly history is a time series: keep the oldest month first so the
+    // chart, table, and screen-reader order all read chronologically.
+    .sort(([left], [right]) => left.localeCompare(right))
     .map(([period, row]) => {
       const total = metrics(row.tokens);
       return {
@@ -591,7 +679,7 @@ function monthlyRows(
     });
 }
 
-function todayHourlyRows(
+function hourlyRows(
   files: CodexFileAggregate[],
   day: string,
   timeZone: string,
@@ -605,10 +693,16 @@ function todayHourlyRows(
     }
   >();
   for (const file of files) {
-    if (file.today?.day !== day || file.today.timeZone !== timeZone) {
+    if (!file.today || file.today.timeZone !== timeZone) {
       continue;
     }
-    for (const [hour, slice] of Object.entries(file.today.hours)) {
+    const slices =
+      file.today.windowDays === CODEX_ROLLING_HOURLY_DAYS && file.today.days
+        ? file.today.days[day] ?? {}
+        : file.today.day === day
+          ? file.today.hours
+          : {};
+    for (const [hour, slice] of Object.entries(slices)) {
       if (!/^(?:[01]\d|2[0-3])$/.test(hour)) {
         continue;
       }
@@ -629,6 +723,7 @@ function todayHourlyRows(
       const total = metrics(row.tokens);
       return {
         hour,
+        label: formatHourLabel(hour),
         total,
         apiEquivalent: apiEquivalentForBuckets(row.models, total.processed),
         threads: row.threads.size,
@@ -706,10 +801,7 @@ function periodMembership(
   if (context.recentSessionKeys.has(sessionIdentityKey(file))) {
     result.push('recent');
   }
-  if (file.period?.timeZone !== context.timeZone) {
-    return result;
-  }
-  const days = Object.keys(file.period.days);
+  const days = periodSlicesForFile(file, context.timeZone).map(([day]) => day);
   if (days.some((day) => context.last7DayKeys.has(day))) {
     result.push('7d');
   }
@@ -726,9 +818,9 @@ function dayMembership(
   file: CodexFileAggregate,
   context: CodexThreadPeriodContext,
 ): string[] {
-  return file.period?.timeZone === context.timeZone
-    ? Object.keys(file.period.days).sort()
-    : [];
+  return periodSlicesForFile(file, context.timeZone)
+    .map(([day]) => day)
+    .sort();
 }
 
 function recentThreadRows(
@@ -933,6 +1025,18 @@ export function buildCodexUsageView(
   const periodCoverage = snapshot.coverage.period;
   const last7DayKeys = rollingDayKeysFromDayKey(periodCoverage.asOfDay, 7);
   const last30DayKeys = rollingDayKeysFromDayKey(periodCoverage.asOfDay, 30);
+  const hourlyCoverage = snapshot.hourlyCoverage ??
+    snapshot.coverage.hourly ?? {
+      timeZone: periodCoverage.timeZone,
+      asOfDay: periodCoverage.asOfDay,
+      windowDays: CODEX_ROLLING_HOURLY_DAYS,
+      indexedFiles: 0,
+      totalFiles: 0,
+      indexedBytes: 0,
+      totalBytes: 0,
+      complete: false,
+      days: {},
+    };
   const periodContext: CodexThreadPeriodContext = {
     recentSessionKeys: new Set(recent.map(sessionIdentityKey)),
     last7DayKeys: new Set(last7DayKeys),
@@ -982,6 +1086,14 @@ export function buildCodexUsageView(
   );
   const allTime = scope(snapshot.files, aggregateIndexIncomplete);
   const daily = dailyRows(snapshot.files, periodCoverage.timeZone);
+  const last30DaysHourlyByDay = Object.fromEntries(
+    last30DayKeys.flatMap((day) => {
+      const rows = hourlyRows(snapshot.files, day, periodCoverage.timeZone);
+      return rows.length > 0 || (hourlyCoverage.days[day]?.totalFiles ?? 0) > 0
+        ? [[day, rows]]
+        : [];
+    }),
+  );
   const taskRoot = taskRootFile(recent);
   const taskIdentityFile = taskRoot ?? fallbackTaskIdentityFile(recent);
   const sourceLimits = snapshot.limits.length > 0
@@ -1020,12 +1132,14 @@ export function buildCodexUsageView(
 
   return {
     today: todayScope,
-    todayHourly: todayHourlyRows(
+    todayHourly: hourlyRows(
       snapshot.files,
       periodCoverage.asOfDay,
       periodCoverage.timeZone,
     ),
     todayCoverage: snapshot.coverage.today,
+    last30DaysHourlyByDay,
+    hourlyCoverage,
     lastTask: recentScope,
     lastTaskIdentity: recent.length > 0
       ? {
diff --git a/src/providers/codex/codexWorkerProtocol.ts b/src/providers/codex/codexWorkerProtocol.ts
index 0a74aae4..b24a4233 100644
--- a/src/providers/codex/codexWorkerProtocol.ts
+++ b/src/providers/codex/codexWorkerProtocol.ts
@@ -12,6 +12,9 @@ export interface CodexWorkerRefreshInput {
   timeZone: string;
   /** Controls the steady-state budget after any first-time/migration backfill. */
   profile?: 'background' | 'foreground';
+  /** False keeps changed-file/tail maintenance active but suppresses unchanged
+   * historical reconciliation until the persisted eligibility time. */
+  allowHistoricalBackfill?: boolean;
 }
 
 export type CodexWorkerRequest =
diff --git a/src/quotaObservationStore.ts b/src/quotaObservationStore.ts
new file mode 100644
index 00000000..2dd758db
--- /dev/null
+++ b/src/quotaObservationStore.ts
@@ -0,0 +1,1103 @@
+import { createHmac, randomBytes } from 'node:crypto';
+import {
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  unlink,
+} from 'node:fs/promises';
+import * as path from 'node:path';
+
+import type { UsageProvider } from './providers/providerTypes';
+import { acquireCodexIndexLease } from './providers/codex/codexIndexLease';
+import type { ClaudeApiUsageResponse } from './types';
+import { normalizeQuotaWindows } from './quotaWindows';
+import type { WeeklyQuotaObservation } from './weeklyValue';
+
+export const QUOTA_OBSERVATION_SCHEMA_VERSION = 2 as const;
+export const QUOTA_OBSERVATION_FILE = 'quota-observations-v2.json';
+export const QUOTA_OBSERVATION_RETENTION_DAYS = 180;
+export const QUOTA_OBSERVATION_LIMIT_PER_SERIES = 512;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const FUTURE_SKEW_MS = DAY_MS;
+const RESET_CLUSTER_MS = 5 * 60 * 1000;
+const USAGE_DROP_THRESHOLD = 0.15;
+
+export type QuotaPeriodType =
+  | 'five-hour'
+  | 'seven-day'
+  | 'provider-scoped-seven-day';
+export type QuotaAccountAttribution =
+  | 'verified-local-signal'
+  | 'profile-continuity'
+  | 'unattributed';
+export type QuotaObservationSource =
+  | 'claude-official-api'
+  | 'codex-local-structured-event';
+export type QuotaEvidenceConfidence = 'high' | 'medium' | 'low';
+export type QuotaCaptureReason =
+  | 'refresh'
+  | 'reset-at-change'
+  | 'window-id-change'
+  | 'usage-drop'
+  | 'profile-change'
+  | 'migration';
+export type QuotaObservationFlag =
+  | 'approximate-boundary'
+  | 'low-log-coverage'
+  | 'low-price-coverage'
+  | 'account-ambiguous'
+  | 'clock-anomaly';
+export type QuotaResetEvidence =
+  | 'reset-at-change'
+  | 'window-id-change'
+  | 'usage-drop';
+
+/** Runtime-only input. Raw identity/window signals are HMACed and discarded. */
+export interface QuotaCapture {
+  provider: UsageProvider;
+  stableIdentitySignal?: string;
+  /** Caller-owned random epoch nonce for evidence without a safe account
+   * identity. It is HMACed immediately and never persisted verbatim. */
+  unattributedEpochSignal?: string;
+  accountAttribution: QuotaAccountAttribution;
+  observedAt: number;
+  periodType: QuotaPeriodType;
+  usedFraction: number;
+  resetAt: number | null;
+  source: QuotaObservationSource;
+  /** A provider-supplied window identity only when its semantics are known.
+   * It is HMACed before persistence. */
+  sourceWindowId?: string;
+  confidence: QuotaEvidenceConfidence;
+  captureReason: QuotaCaptureReason;
+  flags?: QuotaObservationFlag[];
+}
+
+export interface QuotaObservationV2 {
+  schemaVersion: 2;
+  provider: UsageProvider;
+  accountFingerprint: string;
+  accountAttribution: QuotaAccountAttribution;
+  observedAt: number;
+  periodType: QuotaPeriodType;
+  usedFraction: number;
+  remainingFraction: number;
+  resetAt: number | null;
+  source: QuotaObservationSource;
+  windowId: string;
+  providerWindowFingerprint: string | null;
+  confidence: QuotaEvidenceConfidence;
+  captureReason: QuotaCaptureReason;
+  flags: QuotaObservationFlag[];
+}
+
+export interface QuotaObservationClearScope {
+  provider?: UsageProvider;
+  /** Internal machine-local HMAC. It must never cross into a Webview/export. */
+  accountFingerprint?: string;
+}
+
+export interface QuotaResetEventV2 {
+  schemaVersion: 2;
+  provider: UsageProvider;
+  periodType: QuotaPeriodType;
+  detectedAt: number;
+  boundaryAt: number;
+  previousAccountFingerprint: string;
+  nextAccountFingerprint: string;
+  previousWindowId: string;
+  nextWindowId: string;
+  evidence: QuotaResetEvidence;
+  confidence: QuotaEvidenceConfidence;
+  flags: QuotaObservationFlag[];
+}
+
+export interface QuotaObservationStoreV2 {
+  schemaVersion: 2;
+  fingerprintAlgorithm: 'hmac-sha256-v1';
+  observations: QuotaObservationV2[];
+}
+
+export interface MergeQuotaCaptureOptions {
+  salt: string;
+  now?: number;
+  retentionDays?: number;
+  limitPerSeries?: number;
+  usageDropThreshold?: number;
+}
+
+export interface QuotaObservationLoadResult {
+  store: QuotaObservationStoreV2;
+  disposition: 'missing' | 'valid' | 'quarantined';
+  quarantinePath?: string;
+}
+
+export class QuotaObservationScopedClearBlockedError extends Error {
+  readonly code = 'quota-scoped-clear-blocked-by-quarantine' as const;
+
+  constructor() {
+    super('quota-observation-clear:scoped-clear-blocked-by-quarantine');
+    this.name = 'QuotaObservationScopedClearBlockedError';
+  }
+}
+
+const PERIOD_TYPES = new Set<QuotaPeriodType>([
+  'five-hour',
+  'seven-day',
+  'provider-scoped-seven-day',
+]);
+const ATTRIBUTIONS = new Set<QuotaAccountAttribution>([
+  'verified-local-signal',
+  'profile-continuity',
+  'unattributed',
+]);
+const SOURCES = new Set<QuotaObservationSource>([
+  'claude-official-api',
+  'codex-local-structured-event',
+]);
+const CONFIDENCES = new Set<QuotaEvidenceConfidence>(['high', 'medium', 'low']);
+const CAPTURE_REASONS = new Set<QuotaCaptureReason>([
+  'refresh',
+  'reset-at-change',
+  'window-id-change',
+  'usage-drop',
+  'profile-change',
+  'migration',
+]);
+const FLAGS = new Set<QuotaObservationFlag>([
+  'approximate-boundary',
+  'low-log-coverage',
+  'low-price-coverage',
+  'account-ambiguous',
+  'clock-anomaly',
+]);
+const RESET_EVIDENCE = new Set<QuotaResetEvidence>([
+  'reset-at-change',
+  'window-id-change',
+  'usage-drop',
+]);
+
+function hmac(salt: string, value: string, prefix: string): string {
+  return `${prefix}_${createHmac('sha256', salt).update(value).digest('hex').slice(0, 32)}`;
+}
+
+export function fingerprintForStableIdentity(
+  salt: string,
+  provider: UsageProvider,
+  stableIdentitySignal: string,
+): string {
+  return hmac(
+    salt,
+    `account|v1|${provider}|${stableIdentitySignal}`,
+    'acct',
+  );
+}
+
+function providerWindowFingerprint(
+  salt: string,
+  capture: QuotaCapture,
+): string | null {
+  const raw = capture.sourceWindowId?.trim();
+  return raw
+    ? hmac(salt, `provider-window|${capture.provider}|${capture.periodType}|${raw}`, 'pwin')
+    : null;
+}
+
+function observationIdentity(item: QuotaObservationV2): string {
+  return [
+    item.provider,
+    item.accountFingerprint,
+    item.periodType,
+    item.windowId,
+    item.observedAt,
+    item.usedFraction,
+    item.resetAt ?? '',
+    item.source,
+  ].join('|');
+}
+
+function orderedUniqueFlags(flags: readonly QuotaObservationFlag[] = []): QuotaObservationFlag[] {
+  return [...new Set(flags.filter((flag) => FLAGS.has(flag)))].sort();
+}
+
+export function createEmptyQuotaObservationStore(): QuotaObservationStoreV2 {
+  return {
+    schemaVersion: QUOTA_OBSERVATION_SCHEMA_VERSION,
+    fingerprintAlgorithm: 'hmac-sha256-v1',
+    observations: [],
+  };
+}
+
+function validCapture(capture: QuotaCapture, now: number): boolean {
+  return (
+    (capture.provider === 'claude' || capture.provider === 'codex') &&
+    ATTRIBUTIONS.has(capture.accountAttribution) &&
+    PERIOD_TYPES.has(capture.periodType) &&
+    SOURCES.has(capture.source) &&
+    CONFIDENCES.has(capture.confidence) &&
+    CAPTURE_REASONS.has(capture.captureReason) &&
+    Number.isFinite(capture.observedAt) &&
+    capture.observedAt > 0 &&
+    capture.observedAt <= now + FUTURE_SKEW_MS &&
+    Number.isFinite(capture.usedFraction) &&
+    capture.usedFraction >= 0 &&
+    capture.usedFraction <= 1 &&
+    (
+      capture.resetAt === null ||
+      (Number.isFinite(capture.resetAt) && capture.resetAt > 0)
+    ) &&
+    (
+      capture.accountAttribution === 'unattributed'
+        ? typeof capture.unattributedEpochSignal === 'string' &&
+          capture.unattributedEpochSignal.length > 0
+        :
+      typeof capture.stableIdentitySignal === 'string' &&
+        capture.stableIdentitySignal.length > 0
+    )
+  );
+}
+
+function latestBefore(
+  observations: readonly QuotaObservationV2[],
+  capture: QuotaCapture,
+  stableFingerprint: string,
+): QuotaObservationV2 | undefined {
+  const eligible = observations
+    .filter((item) =>
+      item.provider === capture.provider &&
+      item.periodType === capture.periodType &&
+      item.observedAt <= capture.observedAt &&
+      item.accountFingerprint === stableFingerprint,
+    )
+    .sort((left, right) =>
+      left.observedAt - right.observedAt ||
+      left.windowId.localeCompare(right.windowId),
+    );
+  return eligible[eligible.length - 1];
+}
+
+function latestProviderPeriodBefore(
+  observations: readonly QuotaObservationV2[],
+  capture: QuotaCapture,
+): QuotaObservationV2 | undefined {
+  const eligible = observations
+    .filter((item) =>
+      item.provider === capture.provider &&
+      item.periodType === capture.periodType &&
+      item.observedAt <= capture.observedAt,
+    )
+    .sort((left, right) =>
+      left.observedAt - right.observedAt ||
+      left.windowId.localeCompare(right.windowId),
+    );
+  return eligible[eligible.length - 1];
+}
+
+function boundaryEvidence(
+  previous: QuotaObservationV2 | undefined,
+  capture: QuotaCapture,
+  currentProviderWindowFingerprint: string | null,
+  usageDropThreshold: number,
+): QuotaResetEvidence | null {
+  if (!previous) return null;
+  if (
+    previous.providerWindowFingerprint !== null &&
+    currentProviderWindowFingerprint !== null &&
+    previous.providerWindowFingerprint !== currentProviderWindowFingerprint
+  ) {
+    return 'window-id-change';
+  }
+  if (
+    previous.resetAt !== null &&
+    capture.resetAt !== null &&
+    Math.abs(previous.resetAt - capture.resetAt) > RESET_CLUSTER_MS
+  ) {
+    return 'reset-at-change';
+  }
+  if (
+    previous.usedFraction - capture.usedFraction >= usageDropThreshold
+  ) {
+    return 'usage-drop';
+  }
+  return null;
+}
+
+function confidenceRank(value: QuotaEvidenceConfidence): number {
+  return value === 'high' ? 3 : value === 'medium' ? 2 : 1;
+}
+
+function lowerConfidence(
+  left: QuotaEvidenceConfidence,
+  right: QuotaEvidenceConfidence,
+): QuotaEvidenceConfidence {
+  return confidenceRank(left) <= confidenceRank(right) ? left : right;
+}
+
+function normalizedObservation(
+  capture: QuotaCapture,
+  salt: string,
+  previous: QuotaObservationV2 | undefined,
+  boundary: QuotaResetEvidence | null,
+  currentProviderWindowFingerprint: string | null,
+): QuotaObservationV2 {
+  const stableFingerprint = capture.accountAttribution === 'unattributed'
+    ? hmac(
+        salt,
+        `unattributed-account-epoch|${capture.provider}|${capture.unattributedEpochSignal}`,
+        'anon',
+      )
+    : fingerprintForStableIdentity(
+        salt,
+        capture.provider,
+        capture.stableIdentitySignal as string,
+      );
+  const keepPreviousWindow = previous !== undefined && boundary === null;
+  const hasStructuredWindowIdentity =
+    currentProviderWindowFingerprint !== null || capture.resetAt !== null;
+  const epochSeed = boundary === 'usage-drop' || !hasStructuredWindowIdentity
+    ? [
+        capture.provider,
+        capture.periodType,
+        currentProviderWindowFingerprint ?? '',
+        capture.resetAt ?? '',
+        capture.observedAt,
+        boundary ?? 'initial',
+      ].join('|')
+    : [
+        capture.provider,
+        capture.periodType,
+        currentProviderWindowFingerprint ?? '',
+        capture.resetAt ?? '',
+      ].join('|');
+  const accountFingerprint = stableFingerprint;
+  const windowId = keepPreviousWindow
+    ? previous.windowId
+    : hmac(
+        salt,
+        `window|${accountFingerprint}|${epochSeed}`,
+        'win',
+      );
+  return {
+    schemaVersion: QUOTA_OBSERVATION_SCHEMA_VERSION,
+    provider: capture.provider,
+    accountFingerprint,
+    accountAttribution: capture.accountAttribution,
+    observedAt: capture.observedAt,
+    periodType: capture.periodType,
+    usedFraction: capture.usedFraction,
+    remainingFraction: Math.max(0, Math.min(1, 1 - capture.usedFraction)),
+    resetAt: capture.resetAt,
+    source: capture.source,
+    windowId,
+    providerWindowFingerprint: currentProviderWindowFingerprint,
+    confidence: capture.confidence,
+    captureReason: boundary ?? capture.captureReason,
+    flags: orderedUniqueFlags(capture.flags),
+  };
+}
+
+function compactBySeries(
+  observations: QuotaObservationV2[],
+  limit: number,
+): QuotaObservationV2[] {
+  const groups = new Map<string, QuotaObservationV2[]>();
+  for (const item of observations) {
+    const key = [item.provider, item.accountFingerprint, item.periodType].join('|');
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+  const retained: QuotaObservationV2[] = [];
+  for (const group of groups.values()) {
+    const ordered = group.sort((left, right) =>
+      left.observedAt - right.observedAt ||
+      left.usedFraction - right.usedFraction,
+    );
+    if (ordered.length <= limit) {
+      retained.push(...ordered);
+      continue;
+    }
+    const mandatory = new Map<string, QuotaObservationV2>();
+    const windows = new Map<string, QuotaObservationV2[]>();
+    for (const item of ordered) {
+      const window = windows.get(item.windowId) ?? [];
+      window.push(item);
+      windows.set(item.windowId, window);
+      if (item.captureReason !== 'refresh' || item.flags.length > 0) {
+        mandatory.set(observationIdentity(item), item);
+      }
+    }
+    for (const window of windows.values()) {
+      mandatory.set(observationIdentity(window[0]), window[0]);
+      mandatory.set(observationIdentity(window[window.length - 1]), window[window.length - 1]);
+    }
+    const selected = [...mandatory.values()]
+      .sort((left, right) => right.observedAt - left.observedAt)
+      .slice(0, limit);
+    const selectedIds = new Set(selected.map(observationIdentity));
+    for (const item of [...ordered].reverse()) {
+      if (selected.length >= limit) break;
+      const identity = observationIdentity(item);
+      if (!selectedIds.has(identity)) {
+        selected.push(item);
+        selectedIds.add(identity);
+      }
+    }
+    retained.push(...selected);
+  }
+  return retained.sort((left, right) =>
+    left.observedAt - right.observedAt ||
+    left.provider.localeCompare(right.provider) ||
+    left.periodType.localeCompare(right.periodType) ||
+    left.windowId.localeCompare(right.windowId),
+  );
+}
+
+function persistedBoundaryEvidence(
+  previous: QuotaObservationV2,
+  current: QuotaObservationV2,
+  usageDropThreshold: number,
+): QuotaResetEvidence | null {
+  if (previous.windowId === current.windowId) return null;
+  if (
+    previous.providerWindowFingerprint !== null &&
+    current.providerWindowFingerprint !== null &&
+    previous.providerWindowFingerprint !== current.providerWindowFingerprint
+  ) return 'window-id-change';
+  if (
+    previous.resetAt !== null &&
+    current.resetAt !== null &&
+    Math.abs(previous.resetAt - current.resetAt) > RESET_CLUSTER_MS
+  ) return 'reset-at-change';
+  if (previous.usedFraction - current.usedFraction >= usageDropThreshold) {
+    return 'usage-drop';
+  }
+  return null;
+}
+
+function annotateBoundaries(
+  observations: readonly QuotaObservationV2[],
+  usageDropThreshold: number,
+): QuotaObservationV2[] {
+  const ordered = [...observations].sort((left, right) =>
+    left.observedAt - right.observedAt ||
+    left.provider.localeCompare(right.provider) ||
+    left.periodType.localeCompare(right.periodType) ||
+    left.windowId.localeCompare(right.windowId),
+  );
+  const previousByProviderPeriod = new Map<string, QuotaObservationV2>();
+  return ordered.map((item) => {
+    const providerPeriodKey = `${item.provider}|${item.periodType}`;
+    const previousForProvider = previousByProviderPeriod.get(providerPeriodKey);
+    // A reset can be observed across anonymous Codex epochs, so retain its
+    // boundary evidence for deterministic replay. Account changes are handled
+    // independently below and always remain explicitly ambiguous.
+    const inferred = previousForProvider
+      ? persistedBoundaryEvidence(previousForProvider, item, usageDropThreshold)
+      : null;
+    const crossesAccountEpoch = Boolean(
+      previousForProvider &&
+      previousForProvider.accountFingerprint !== item.accountFingerprint,
+    );
+    const normalized = {
+      ...item,
+      captureReason: inferred ?? item.captureReason,
+      flags: orderedUniqueFlags([
+        ...item.flags,
+        ...(crossesAccountEpoch ? ['account-ambiguous' as const] : []),
+      ]),
+    };
+    previousByProviderPeriod.set(providerPeriodKey, normalized);
+    return normalized;
+  });
+}
+
+export function mergeQuotaCaptures(
+  store: QuotaObservationStoreV2,
+  captures: readonly QuotaCapture[],
+  options: MergeQuotaCaptureOptions,
+): QuotaObservationStoreV2 {
+  const now = options.now ?? Date.now();
+  const retentionDays = Math.max(
+    1,
+    Math.floor(options.retentionDays ?? QUOTA_OBSERVATION_RETENTION_DAYS),
+  );
+  const limitPerSeries = Math.max(
+    1,
+    Math.floor(options.limitPerSeries ?? QUOTA_OBSERVATION_LIMIT_PER_SERIES),
+  );
+  const usageDropThreshold = Math.max(
+    0,
+    Math.min(1, options.usageDropThreshold ?? USAGE_DROP_THRESHOLD),
+  );
+  const cutoff = now - retentionDays * DAY_MS;
+  const observations = store.observations
+    .filter((item) => item.observedAt >= cutoff && item.observedAt <= now + FUTURE_SKEW_MS)
+    .map((item) => ({ ...item, flags: [...item.flags] }));
+  const observationIds = new Set(observations.map(observationIdentity));
+  const orderedCaptures = [...captures]
+    .filter((item) => validCapture(item, now))
+    .sort((left, right) =>
+      left.observedAt - right.observedAt ||
+      left.provider.localeCompare(right.provider) ||
+      left.periodType.localeCompare(right.periodType),
+    );
+  for (const capture of orderedCaptures) {
+    const stableFingerprint = capture.accountAttribution === 'unattributed'
+      ? hmac(
+          options.salt,
+          `unattributed-account-epoch|${capture.provider}|${capture.unattributedEpochSignal}`,
+          'anon',
+        )
+      : fingerprintForStableIdentity(
+          options.salt,
+          capture.provider,
+          capture.stableIdentitySignal as string,
+        );
+    const previous = latestBefore(observations, capture, stableFingerprint);
+    // Codex does not expose a safe stable account identity. Its reset windows
+    // intentionally use separate unattributed epochs, but a resetAt/window
+    // transition still remains useful low-confidence reset evidence. Consult
+    // the preceding provider-period observation only for boundary detection;
+    // never reuse its fingerprint or combine account-level estimates.
+    const boundaryPrevious = previous ?? (
+      capture.accountAttribution === 'unattributed'
+        ? latestProviderPeriodBefore(observations, capture)
+        : undefined
+    );
+    const currentProviderWindowFingerprint = providerWindowFingerprint(
+      options.salt,
+      capture,
+    );
+    const boundary = boundaryEvidence(
+      boundaryPrevious,
+      capture,
+      currentProviderWindowFingerprint,
+      usageDropThreshold,
+    );
+    const captureWithBoundaryFlags = boundaryPrevious &&
+      boundaryPrevious.accountFingerprint !== stableFingerprint
+      ? {
+          ...capture,
+          flags: orderedUniqueFlags([
+            ...(capture.flags ?? []),
+            'account-ambiguous',
+          ]),
+        }
+      : capture;
+    const observation = normalizedObservation(
+      captureWithBoundaryFlags,
+      options.salt,
+      previous,
+      boundary,
+      currentProviderWindowFingerprint,
+    );
+    const identity = observationIdentity(observation);
+    if (!observationIds.has(identity)) {
+      observations.push(observation);
+      observationIds.add(identity);
+    }
+  }
+  return {
+    schemaVersion: QUOTA_OBSERVATION_SCHEMA_VERSION,
+    fingerprintAlgorithm: 'hmac-sha256-v1',
+    observations: compactBySeries(
+      annotateBoundaries(observations, usageDropThreshold),
+      limitPerSeries,
+    ),
+  };
+}
+
+/** Reset events are a deterministic runtime projection, not a second persisted
+ * fact table. Boundary observations carry the evidence needed to reconstruct
+ * consecutive and same-day resets without duplicating sensitive identifiers. */
+export function deriveQuotaResetEvents(
+  store: QuotaObservationStoreV2,
+): QuotaResetEventV2[] {
+  const events: QuotaResetEventV2[] = [];
+  const ordered = [...store.observations].sort((left, right) =>
+    left.observedAt - right.observedAt || left.windowId.localeCompare(right.windowId),
+  );
+  const previousBySeries = new Map<string, QuotaObservationV2>();
+  for (let index = 0; index < ordered.length; index += 1) {
+    const current = ordered[index];
+    const seriesKey = `${current.provider}|${current.periodType}`;
+    const previous = previousBySeries.get(seriesKey);
+    previousBySeries.set(seriesKey, current);
+    if (!previous || previous.windowId === current.windowId) continue;
+    const inferred = persistedBoundaryEvidence(
+      previous,
+      current,
+      USAGE_DROP_THRESHOLD,
+    );
+    const evidence = inferred ?? (
+      RESET_EVIDENCE.has(current.captureReason as QuotaResetEvidence)
+        ? current.captureReason as QuotaResetEvidence
+        : null
+    );
+    if (!evidence) continue;
+    const crossesAccountEpoch =
+      previous.accountFingerprint !== current.accountFingerprint;
+    events.push({
+      schemaVersion: 2,
+      provider: current.provider,
+      periodType: current.periodType,
+      detectedAt: current.observedAt,
+      boundaryAt: evidence === 'usage-drop'
+        ? current.observedAt
+        : previous.resetAt ?? current.observedAt,
+      previousAccountFingerprint: previous.accountFingerprint,
+      nextAccountFingerprint: current.accountFingerprint,
+      previousWindowId: previous.windowId,
+      nextWindowId: current.windowId,
+      evidence,
+      confidence: crossesAccountEpoch
+        ? 'low'
+        : evidence === 'usage-drop'
+          ? lowerConfidence(current.confidence, 'medium')
+          : current.confidence,
+      flags: orderedUniqueFlags([
+        ...current.flags,
+        ...(crossesAccountEpoch ? ['account-ambiguous' as const] : []),
+      ]),
+    });
+  }
+  return events;
+}
+
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  const allowedSet = new Set(allowed);
+  return Object.keys(value).every((key) => allowedSet.has(key));
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function finiteFraction(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function finitePositive(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function validFingerprint(value: unknown): value is string {
+  return typeof value === 'string' && /^(?:acct|anon)_[a-f0-9]{32}$/.test(value);
+}
+
+function validWindowId(value: unknown): value is string {
+  return typeof value === 'string' && /^win_[a-f0-9]{32}$/.test(value);
+}
+
+function parseFlags(value: unknown): QuotaObservationFlag[] | null {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && FLAGS.has(item as QuotaObservationFlag))) {
+    return null;
+  }
+  return orderedUniqueFlags(value as QuotaObservationFlag[]);
+}
+
+function parseObservation(value: unknown, now: number): QuotaObservationV2 | null {
+  const item = record(value);
+  if (!item || !exactKeys(item, [
+    'schemaVersion', 'provider', 'accountFingerprint', 'accountAttribution',
+    'observedAt', 'periodType', 'usedFraction', 'remainingFraction', 'resetAt',
+    'source', 'windowId', 'providerWindowFingerprint', 'confidence',
+    'captureReason', 'flags',
+  ])) return null;
+  const flags = parseFlags(item.flags);
+  if (
+    item.schemaVersion !== 2 ||
+    (item.provider !== 'claude' && item.provider !== 'codex') ||
+    !validFingerprint(item.accountFingerprint) ||
+    typeof item.accountAttribution !== 'string' ||
+    !ATTRIBUTIONS.has(item.accountAttribution as QuotaAccountAttribution) ||
+    !finitePositive(item.observedAt) ||
+    item.observedAt > now + FUTURE_SKEW_MS ||
+    typeof item.periodType !== 'string' ||
+    !PERIOD_TYPES.has(item.periodType as QuotaPeriodType) ||
+    !finiteFraction(item.usedFraction) ||
+    !finiteFraction(item.remainingFraction) ||
+    Math.abs(item.usedFraction + item.remainingFraction - 1) > 1e-9 ||
+    !(item.resetAt === null || finitePositive(item.resetAt)) ||
+    typeof item.source !== 'string' ||
+    !SOURCES.has(item.source as QuotaObservationSource) ||
+    !validWindowId(item.windowId) ||
+    !(item.providerWindowFingerprint === null ||
+      typeof item.providerWindowFingerprint === 'string' &&
+      /^pwin_[a-f0-9]{32}$/.test(item.providerWindowFingerprint)) ||
+    typeof item.confidence !== 'string' ||
+    !CONFIDENCES.has(item.confidence as QuotaEvidenceConfidence) ||
+    typeof item.captureReason !== 'string' ||
+    !CAPTURE_REASONS.has(item.captureReason as QuotaCaptureReason) ||
+    flags === null
+  ) return null;
+  return {
+    schemaVersion: 2,
+    provider: item.provider,
+    accountFingerprint: item.accountFingerprint,
+    accountAttribution: item.accountAttribution as QuotaAccountAttribution,
+    observedAt: item.observedAt,
+    periodType: item.periodType as QuotaPeriodType,
+    usedFraction: item.usedFraction,
+    remainingFraction: item.remainingFraction,
+    resetAt: item.resetAt as number | null,
+    source: item.source as QuotaObservationSource,
+    windowId: item.windowId,
+    providerWindowFingerprint: item.providerWindowFingerprint as string | null,
+    confidence: item.confidence as QuotaEvidenceConfidence,
+    captureReason: item.captureReason as QuotaCaptureReason,
+    flags,
+  };
+}
+
+function parseStore(value: unknown, now: number): QuotaObservationStoreV2 | null {
+  const item = record(value);
+  if (!item || !exactKeys(item, [
+    'schemaVersion', 'fingerprintAlgorithm', 'observations',
+  ])) return null;
+  if (
+    item.schemaVersion !== 2 ||
+    item.fingerprintAlgorithm !== 'hmac-sha256-v1' ||
+    !Array.isArray(item.observations)
+  ) return null;
+  const observations = item.observations.map((entry) => parseObservation(entry, now));
+  if (observations.some((entry) => entry === null)) {
+    return null;
+  }
+  const observationMap = new Map(
+    (observations as QuotaObservationV2[]).map((entry) => [observationIdentity(entry), entry]),
+  );
+  return {
+    schemaVersion: 2,
+    fingerprintAlgorithm: 'hmac-sha256-v1',
+    observations: [...observationMap.values()].sort((left, right) =>
+      left.observedAt - right.observedAt || left.windowId.localeCompare(right.windowId),
+    ),
+  };
+}
+
+async function quarantine(filePath: string, now: number): Promise<string | undefined> {
+  const quarantinePath = `${filePath}.quarantine-${Math.floor(now)}-${randomBytes(4).toString('hex')}`;
+  try {
+    await rename(filePath, quarantinePath);
+    return quarantinePath;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function loadQuotaObservationStore(
+  filePath: string,
+  options: { now?: number } = {},
+): Promise<QuotaObservationLoadResult> {
+  const now = options.now ?? Date.now();
+  let body: string;
+  try {
+    body = await readFile(filePath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { store: createEmptyQuotaObservationStore(), disposition: 'missing' };
+    }
+    return { store: createEmptyQuotaObservationStore(), disposition: 'quarantined' };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body) as unknown;
+  } catch {
+    const quarantinePath = await quarantine(filePath, now);
+    return {
+      store: createEmptyQuotaObservationStore(),
+      disposition: 'quarantined',
+      ...(quarantinePath ? { quarantinePath } : {}),
+    };
+  }
+  const store = parseStore(parsed, now);
+  if (!store) {
+    const quarantinePath = await quarantine(filePath, now);
+    return {
+      store: createEmptyQuotaObservationStore(),
+      disposition: 'quarantined',
+      ...(quarantinePath ? { quarantinePath } : {}),
+    };
+  }
+  return { store, disposition: 'valid' };
+}
+
+export async function saveQuotaObservationStoreAtomic(
+  filePath: string,
+  store: QuotaObservationStoreV2,
+): Promise<void> {
+  const sanitized = parseStore(store, Date.now());
+  if (!sanitized) {
+    throw new Error('invalid quota observation store');
+  }
+  const directory = path.dirname(filePath);
+  await mkdir(directory, { recursive: true });
+  const temporaryPath = path.join(
+    directory,
+    `.${path.basename(filePath)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`,
+  );
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(temporaryPath, 'wx', 0o600);
+    await handle.writeFile(JSON.stringify(sanitized), 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporaryPath, filePath);
+    try {
+      const directoryHandle = await open(directory, 'r');
+      await directoryHandle.sync();
+      await directoryHandle.close();
+    } catch {
+      // Some VS Code hosts/filesystems do not permit directory fsync. The file
+      // itself was still flushed and installed by same-directory rename.
+    }
+  } finally {
+    await handle?.close().catch(() => undefined);
+    await unlink(temporaryPath).catch((error) => {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    });
+  }
+}
+
+function cloneStore(store: QuotaObservationStoreV2): QuotaObservationStoreV2 {
+  return {
+    schemaVersion: 2,
+    fingerprintAlgorithm: 'hmac-sha256-v1',
+    observations: store.observations.map((item) => ({
+      ...item,
+      flags: [...item.flags],
+    })),
+  };
+}
+
+async function quotaObservationAuxiliaryNames(filePath: string): Promise<string[]> {
+  const directory = path.dirname(filePath);
+  const canonical = path.basename(filePath);
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const quarantinePattern = new RegExp(
+    `^${canonical.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.quarantine-\\d+-[a-f0-9]{8}$`,
+  );
+  const temporaryPattern = new RegExp(
+    `^\\.${canonical.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.\\d+\\.[a-f0-9]{12}\\.tmp$`,
+  );
+  return names.filter((name) => quarantinePattern.test(name) || temporaryPattern.test(name));
+}
+
+async function purgeQuotaObservationAuxiliaries(filePath: string): Promise<void> {
+  const directory = path.dirname(filePath);
+  for (const name of await quotaObservationAuxiliaryNames(filePath)) {
+    await unlink(path.join(directory, name)).catch((error) => {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    });
+  }
+}
+
+export class QuotaObservationRepository {
+  private state: QuotaObservationStoreV2 | undefined;
+  private pending: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly filePath: string,
+    private readonly salt: string,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private serialized<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.pending.then(operation, operation);
+    this.pending = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  load(): Promise<QuotaObservationStoreV2> {
+    return this.serialized(async () => {
+      this.state = (await loadQuotaObservationStore(this.filePath, {
+        now: this.now(),
+      })).store;
+      return cloneStore(this.state);
+    });
+  }
+
+  append(captures: readonly QuotaCapture[]): Promise<QuotaObservationStoreV2> {
+    return this.serialized(async () => {
+      const lease = await acquireCodexIndexLease(this.filePath);
+      try {
+        // Always re-read under the process-shared lease. A second VS Code
+        // Extension Host may have committed observations since our last call.
+        const current = (await loadQuotaObservationStore(this.filePath, {
+          now: this.now(),
+        })).store;
+        const next = mergeQuotaCaptures(current, captures, {
+          salt: this.salt,
+          now: this.now(),
+        });
+        if (JSON.stringify(next) !== JSON.stringify(current)) {
+          await saveQuotaObservationStoreAtomic(this.filePath, next);
+        }
+        this.state = next;
+        return cloneStore(next);
+      } finally {
+        await lease.release();
+      }
+    });
+  }
+
+  /**
+   * Remove only observations selected by an exact provider/fingerprint scope.
+   * The same process-shared lease and atomic writer as append() prevent a
+   * clear from racing another Extension Host into resurrecting an older file.
+   */
+  clear(scope: QuotaObservationClearScope = {}): Promise<QuotaObservationStoreV2> {
+    return this.serialized(async () => {
+      const lease = await acquireCodexIndexLease(this.filePath);
+      try {
+        const loaded = await loadQuotaObservationStore(this.filePath, {
+          now: this.now(),
+        });
+        const clearAll = scope.provider === undefined &&
+          scope.accountFingerprint === undefined;
+        const auxiliaries = await quotaObservationAuxiliaryNames(this.filePath);
+        if (!clearAll && (loaded.disposition === 'quarantined' || auxiliaries.length > 0)) {
+          throw new QuotaObservationScopedClearBlockedError();
+        }
+        const current = loaded.store;
+        const observations = current.observations.filter((item) => {
+          const providerMatches = scope.provider === undefined ||
+            item.provider === scope.provider;
+          const accountMatches = scope.accountFingerprint === undefined ||
+            item.accountFingerprint === scope.accountFingerprint;
+          return !(providerMatches && accountMatches);
+        });
+        const next: QuotaObservationStoreV2 = {
+          schemaVersion: 2,
+          fingerprintAlgorithm: 'hmac-sha256-v1',
+          observations,
+        };
+        if (clearAll || observations.length !== current.observations.length) {
+          await saveQuotaObservationStoreAtomic(this.filePath, next);
+        }
+        if (clearAll) {
+          // Keep the canonical empty file. Another Extension Host that appends
+          // after this lease is released must extend that empty store instead
+          // of having its new write deleted by a second lease acquisition.
+          await purgeQuotaObservationAuxiliaries(this.filePath);
+        }
+        this.state = next;
+        return cloneStore(next);
+      } finally {
+        await lease.release();
+      }
+    });
+  }
+}
+
+export function quotaStoreWeeklyObservations(
+  store: QuotaObservationStoreV2,
+  provider: UsageProvider,
+  accountFingerprint?: string,
+): WeeklyQuotaObservation[] {
+  const selected = store.observations
+    .filter((item) =>
+      item.provider === provider &&
+      item.periodType === 'seven-day' &&
+      item.resetAt !== null &&
+      (accountFingerprint === undefined || item.accountFingerprint === accountFingerprint),
+    );
+  const fingerprints = [...new Set(selected.map((item) => item.accountFingerprint))]
+    .sort();
+  const aliases = new Map(fingerprints.map((fingerprint, index) => [
+    fingerprint,
+    accountFingerprint === undefined
+      ? `${provider}-epoch-${index + 1}`
+      : `active-${provider}`,
+  ]));
+  const windows = [...new Set(selected.map((item) => item.windowId))].sort();
+  const windowAliases = new Map(windows.map((windowId, index) => [
+    windowId,
+    `${provider}-window-${index + 1}`,
+  ]));
+  return selected.map((item) => ({
+      provider: item.provider,
+      seriesKey: aliases.get(item.accountFingerprint) as string,
+      observedAt: item.observedAt,
+      resetAt: item.resetAt as number,
+      usedPercent: item.usedFraction * 100,
+      accountAttribution: item.accountAttribution,
+      windowId: windowAliases.get(item.windowId) as string,
+      observationConfidence: item.confidence,
+      flags: [...item.flags],
+    }));
+}
+
+export function claudeQuotaCapturesFromUsage(
+  usage: ClaudeApiUsageResponse | null,
+  identitySignal: string,
+  accountAttribution: Extract<
+    QuotaAccountAttribution,
+    'verified-local-signal' | 'profile-continuity'
+  >,
+  observedAt: number,
+  captureReason: QuotaCaptureReason = 'refresh',
+): QuotaCapture[] {
+  return normalizeQuotaWindows(usage).map((window): QuotaCapture => {
+    const resetAt = Date.parse(window.resetsAt);
+    return {
+      provider: 'claude',
+      stableIdentitySignal: identitySignal,
+      accountAttribution,
+      observedAt,
+      periodType: window.kind === 'session'
+        ? 'five-hour'
+        : window.kind === 'weekly_all'
+          ? 'seven-day'
+          : 'provider-scoped-seven-day',
+      usedFraction: Math.max(0, Math.min(1, window.utilization / 100)),
+      resetAt: Number.isFinite(resetAt) && resetAt > 0 ? resetAt : null,
+      source: 'claude-official-api',
+      // Scope labels never persist: this runtime string is HMACed into the
+      // provider-window fingerprint by mergeQuotaCaptures.
+      sourceWindowId: `${window.kind}|${window.scopeLabel ?? 'all'}`,
+      confidence: Number.isFinite(resetAt) && resetAt > 0 ? 'high' : 'medium',
+      captureReason,
+      flags: Number.isFinite(resetAt) && resetAt > 0 ? [] : ['approximate-boundary'],
+    };
+  });
+}
+
+export function codexQuotaCapturesFromWeeklyObservations(
+  observations: readonly WeeklyQuotaObservation[],
+  captureReason: QuotaCaptureReason = 'refresh',
+): QuotaCapture[] {
+  return observations.map((item): QuotaCapture => {
+    // A Codex file key identifies one local log, not an account. The reset
+    // window is the narrowest safe epoch we can infer without inventing an
+    // account split; attribution therefore remains explicitly unattributed.
+    const sourceEpoch = `codex-window|${item.windowId ?? item.resetAt}`;
+    return {
+      provider: 'codex',
+      unattributedEpochSignal: sourceEpoch,
+      accountAttribution: 'unattributed',
+      observedAt: item.observedAt,
+      periodType: 'seven-day',
+      usedFraction: Math.max(0, Math.min(1, item.usedPercent / 100)),
+      resetAt: item.resetAt,
+      source: 'codex-local-structured-event',
+      confidence: item.observationConfidence ?? 'medium',
+      captureReason,
+      flags: orderedUniqueFlags(item.flags),
+    };
+  });
+}
diff --git a/src/resourceOwnership.ts b/src/resourceOwnership.ts
new file mode 100644
index 00000000..6a07755d
--- /dev/null
+++ b/src/resourceOwnership.ts
@@ -0,0 +1,204 @@
+export const RESOURCE_KINDS = ['timer', 'watcher', 'worker', 'network', 'backfill'] as const;
+
+export const RESOURCE_CAPABILITIES = [
+  'refresh',
+  'quota',
+  'codex-index',
+  'codex-history',
+  'hourly-history',
+  'advice-personalization',
+] as const;
+
+export const RESOURCE_SCOPES = ['extension', 'claude', 'codex', 'advice'] as const;
+
+export const RESOURCE_CREATORS = [
+  'extension',
+  'refresh-coordinator',
+  'claude-api-client',
+  'codex-index-client',
+  'codex-index-worker',
+  'codex-file-pass-pool',
+  'advice-runtime',
+] as const;
+
+export const RESOURCE_STOP_CONDITIONS = [
+  'settled',
+  'completed',
+  'cancelled',
+  'window-blur',
+  'feature-disabled',
+  'extension-dispose',
+  'user-pause',
+  'settings-change',
+  'profile-change',
+] as const;
+
+export const RESOURCE_BOUNDED_EXCEPTIONS = ['none', 'first-codex-history'] as const;
+
+export type ResourceKind = typeof RESOURCE_KINDS[number];
+export type ResourceCapability = typeof RESOURCE_CAPABILITIES[number];
+export type ResourceScope = typeof RESOURCE_SCOPES[number];
+export type ResourceCreator = typeof RESOURCE_CREATORS[number];
+export type ResourceStopCondition = typeof RESOURCE_STOP_CONDITIONS[number];
+export type ResourceBoundedException = typeof RESOURCE_BOUNDED_EXCEPTIONS[number];
+
+export interface ResourceDescriptor {
+  readonly kind: ResourceKind;
+  readonly capability: ResourceCapability;
+  readonly scope: ResourceScope;
+  readonly creator: ResourceCreator;
+  readonly stopConditions: readonly ResourceStopCondition[];
+  readonly boundedException: ResourceBoundedException;
+}
+
+export interface ResourceLease {
+  readonly descriptor: ResourceDescriptor;
+  readonly active: boolean;
+
+  /** Runs the real close/abort/terminate/settle action. Ownership is released
+   * only after that action resolves; a rejected action leaves the lease active. */
+  stop(
+    condition: ResourceStopCondition,
+    actualStopOrSettle: () => void | Promise<void>,
+  ): Promise<boolean>;
+}
+
+export interface ResourceOwnershipSnapshot {
+  readonly activeCount: number;
+  readonly byKind: Readonly<Record<ResourceKind, number>>;
+  readonly active: readonly ResourceDescriptor[];
+}
+
+const DESCRIPTOR_FIELDS = [
+  'kind',
+  'capability',
+  'scope',
+  'creator',
+  'stopConditions',
+  'boundedException',
+] as const;
+
+const kindSet = new Set<unknown>(RESOURCE_KINDS);
+const capabilitySet = new Set<unknown>(RESOURCE_CAPABILITIES);
+const scopeSet = new Set<unknown>(RESOURCE_SCOPES);
+const creatorSet = new Set<unknown>(RESOURCE_CREATORS);
+const stopConditionSet = new Set<unknown>(RESOURCE_STOP_CONDITIONS);
+const boundedExceptionSet = new Set<unknown>(RESOURCE_BOUNDED_EXCEPTIONS);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function assertExactDescriptorFields(value: Record<string, unknown>): void {
+  const keys = Object.keys(value);
+  if (keys.length !== DESCRIPTOR_FIELDS.length ||
+      !DESCRIPTOR_FIELDS.every((field) => Object.prototype.hasOwnProperty.call(value, field))) {
+    throw new TypeError('resource ownership metadata contains an unknown or missing field');
+  }
+}
+
+function checkedDescriptor(value: ResourceDescriptor): ResourceDescriptor {
+  if (!isRecord(value)) throw new TypeError('resource descriptor must be an object');
+  assertExactDescriptorFields(value);
+  if (!kindSet.has(value.kind)) throw new TypeError('resource kind must be fixed');
+  if (!capabilitySet.has(value.capability)) throw new TypeError('resource capability must be fixed');
+  if (!scopeSet.has(value.scope)) throw new TypeError('resource scope must be fixed');
+  if (!creatorSet.has(value.creator)) throw new TypeError('resource creator must be fixed');
+  if (!boundedExceptionSet.has(value.boundedException)) {
+    throw new TypeError('resource bounded exception must be fixed');
+  }
+  if (!Array.isArray(value.stopConditions) || value.stopConditions.length === 0) {
+    throw new TypeError('resource stop conditions must be a non-empty fixed list');
+  }
+  const seen = new Set<ResourceStopCondition>();
+  for (const condition of value.stopConditions) {
+    if (!stopConditionSet.has(condition)) throw new TypeError('resource stop condition must be fixed');
+    if (seen.has(condition)) throw new TypeError('resource stop conditions contain a duplicate');
+    seen.add(condition);
+  }
+  if (value.boundedException === 'first-codex-history' &&
+      (value.kind !== 'backfill' || value.capability !== 'codex-history' || value.scope !== 'codex')) {
+    throw new TypeError('first Codex history bounded exception is only valid for a Codex history backfill');
+  }
+
+  return Object.freeze({
+    kind: value.kind,
+    capability: value.capability,
+    scope: value.scope,
+    creator: value.creator,
+    stopConditions: Object.freeze([...value.stopConditions]),
+    boundedException: value.boundedException,
+  });
+}
+
+function emptyKindCounts(): Record<ResourceKind, number> {
+  return {
+    timer: 0,
+    watcher: 0,
+    worker: 0,
+    network: 0,
+    backfill: 0,
+  };
+}
+
+/** Test-observable ownership bookkeeping only. It neither schedules resources
+ * nor retains callbacks, paths, request bodies, or other user content. */
+export class ResourceOwnershipRegistry {
+  private nextLeaseId = 1;
+  private readonly activeDescriptors = new Map<number, ResourceDescriptor>();
+
+  register(input: ResourceDescriptor): ResourceLease {
+    const descriptor = checkedDescriptor(input);
+    const leaseId = this.nextLeaseId;
+    this.nextLeaseId += 1;
+    this.activeDescriptors.set(leaseId, descriptor);
+
+    let active = true;
+    let stopping: Promise<boolean> | undefined;
+    const registry = this;
+    return {
+      descriptor,
+      get active(): boolean {
+        return active;
+      },
+      stop(
+        condition: ResourceStopCondition,
+        actualStopOrSettle: () => void | Promise<void>,
+      ): Promise<boolean> {
+        if (!stopConditionSet.has(condition) || !descriptor.stopConditions.includes(condition)) {
+          return Promise.reject(new TypeError('stop condition is not declared by this resource'));
+        }
+        if (typeof actualStopOrSettle !== 'function') {
+          return Promise.reject(new TypeError('actual stop or settle action must be a function'));
+        }
+        if (!active) return Promise.resolve(false);
+        if (stopping !== undefined) return stopping;
+
+        stopping = Promise.resolve()
+          .then(actualStopOrSettle)
+          .then(() => {
+            if (!active) return false;
+            active = false;
+            registry.activeDescriptors.delete(leaseId);
+            return true;
+          })
+          .catch((error: unknown) => {
+            stopping = undefined;
+            throw error;
+          });
+        return stopping;
+      },
+    };
+  }
+
+  snapshotForTests(): ResourceOwnershipSnapshot {
+    const byKind = emptyKindCounts();
+    const active = [...this.activeDescriptors.values()];
+    for (const descriptor of active) byKind[descriptor.kind] += 1;
+    return Object.freeze({
+      activeCount: active.length,
+      byKind: Object.freeze(byKind),
+      active: Object.freeze(active),
+    });
+  }
+}
diff --git a/src/settings.ts b/src/settings.ts
index 67ea4063..27a0b05b 100644
--- a/src/settings.ts
+++ b/src/settings.ts
@@ -13,7 +13,9 @@ import {
 //   - language        (UI language; people sync this)
 //   - dataDirectory   (machine-specific path a power user may script)
 //   - codex.dataDirectory (optional machine-specific Codex home)
-//   - advice.apiKey   (a secret some keep in their synced settings)
+// API keys are deliberately absent from settings.json/globalState. The
+// dashboard writes them to VS Code SecretStorage and never receives a stored
+// value back from the extension host.
 //
 // The catalog below drives BOTH the read/write plumbing and the dashboard
 // panel rendering, so adding a setting is a one-line change here.
@@ -22,7 +24,7 @@ import {
 // panel chrome — group headers, buttons, notes — is localised via i18n.
 
 export type SettingType = 'boolean' | 'number' | 'enum' | 'string';
-export type SettingStorage = 'config' | 'state';
+export type SettingStorage = 'config' | 'state' | 'secret';
 export type SettingGroup = 'general' | 'providers' | 'features' | 'statusBar' | 'data' | 'advice';
 export type SettingProvider = 'claude' | 'codex';
 
@@ -58,6 +60,7 @@ export function settingAppliesToProvider(
 // globalState key prefix for moved settings — namespaced to avoid colliding
 // with other globalState entries (consent flags, dismissals, …).
 const STATE_PREFIX = 'ccu.setting.';
+const SECRET_PREFIX = 'claudeCodeUsage.secret.';
 const MIGRATION_FLAG = 'ccu.settingsMigrated.v1';
 // V2.2: one-shot conversion of the old double-negative pauseDashboardRefresh to
 // the positive dashboardAutoRefresh. Its own flag so it runs even for users who
@@ -69,6 +72,40 @@ const AUTOREFRESH_MIGRATION_FLAG = 'ccu.migrated.dashboardAutoRefresh';
 // it controls. Own flag so it runs regardless of the earlier migrations.
 const SCOPED_WEEKLY_MIGRATION_FLAG = 'ccu.migrated.showScopedWeekly';
 
+// Exact configuration/globalState names used by released predecessors but no
+// longer present in SETTINGS. They are migration inputs, never a prefix-based
+// deletion rule.
+const RETIRED_SETTING_KEYS = [
+  'fileWatching',
+  'pauseDashboardRefresh',
+  'showOpusWeekly',
+  'advice.backend',
+  'advice.subscriptionModel',
+] as const;
+
+export type SettingsSecretMigrationErrorCode =
+  | 'legacy-secret-conflict'
+  | 'workspace-secret-requires-manual-migration'
+  | 'secret-storage-unavailable'
+  | 'secret-storage-failed';
+
+/** A fixed-code error that can never carry the secret or provider error text. */
+export class SettingsSecretMigrationError extends Error {
+  constructor(readonly code: SettingsSecretMigrationErrorCode) {
+    super(`settings-secret-migration:${code}`);
+    this.name = 'SettingsSecretMigrationError';
+  }
+}
+
+export class SettingsLocalDataClearError extends Error {
+  readonly code = 'legacy-configuration-requires-manual-removal' as const;
+
+  constructor(readonly keys: readonly string[]) {
+    super('settings-local-data-clear:legacy-configuration-requires-manual-removal');
+    this.name = 'SettingsLocalDataClearError';
+  }
+}
+
 // Timezone dropdown ('' = system default). A dropdown (not free text) means an
 // invalid value can never be entered (#51). Rather than dump all ~400 IANA
 // zones, we curate the common ones — like a typical app's timezone picker — and
@@ -226,6 +263,18 @@ export const SETTINGS: SettingDef[] = [
   },
 
   // --- Providers ---
+  {
+    key: 'pricingBackend',
+    type: 'enum',
+    default: 'anthropic',
+    storage: 'state',
+    group: 'providers',
+    label: 'Claude pricing backend',
+    help: 'Select AWS Bedrock in-region rates when Claude Code usage is routed through Bedrock.',
+    enumValues: ['anthropic', 'aws-bedrock-in-region'],
+    enumLabels: ['Anthropic direct API', 'AWS Bedrock (in-region)'],
+    providers: ['claude'],
+  },
   {
     key: 'codex.enabled',
     type: 'boolean',
@@ -299,11 +348,12 @@ export const SETTINGS: SettingDef[] = [
   {
     key: 'enableShareCard',
     type: 'boolean',
-    default: false,
+    default: true,
     storage: 'state',
     group: 'features',
-    label: 'Enable usage share card',
-    help: 'Off by default. When on, the All tab gets a configurable "Share card" — pick a range (week / month / year / a specific month), a scope (overall / a project / a session) and which metrics to show, then generate a one-page SVG to share. Only aggregate numbers leave your machine, and only when you export.',
+    label: 'Enable sharing workspace',
+    help: 'On by default. Show the Compare sharing workspace and provider share card. Turn it off to hide sharing UI; exporting still requires an explicit action.',
+    providers: ['claude', 'codex'],
   },
   {
     key: 'showCostliestMessages',
@@ -385,7 +435,7 @@ export const SETTINGS: SettingDef[] = [
     storage: 'state',
     group: 'statusBar',
     label: 'Codex status metric',
-    help: 'Uncached usage, processed tokens, or output tokens.',
+    help: "Today's uncached usage, processed tokens, or output tokens.",
     enumValues: ['fresh', 'processed', 'output'],
     enumLabels: ['Uncached', 'Processed', 'Output'],
     providers: ['codex'],
@@ -556,20 +606,27 @@ export const SETTINGS: SettingDef[] = [
   },
 
   // --- AI advice & Optimizer ---
-  // NOTE: the 'subscription' backend (call Anthropic with the Claude Code OAuth
-  // session, no API key) is intentionally NOT shipped in this version. Anthropic
-  // returns 403 "Request not allowed" for that gray-area use of the OAuth token
-  // (it only succeeds by routing around the TLS-fingerprint gate via curl), so
-  // it is too fragile/inappropriate for a public extension. The transport code
-  // stays in advisor.ts, dormant, to re-enable if direct calls become allowed.
+  {
+    key: 'advice.effectiveness.enabled',
+    type: 'boolean',
+    default: false,
+    storage: 'state',
+    group: 'advice',
+    label: 'Enable AI advice effectiveness preview',
+    help: 'Off by default. Shows local evidence, an optional exact BYOK request preview/send flow, local feedback, and comparable-task results. Previewing never sends; sending requires a separate click.',
+    providers: ['claude', 'codex'],
+  },
+  // Claude Code OAuth/subscription credentials remain quota-only. AI requests
+  // have no dormant subscription transport: both surfaces require an exact
+  // Prepared preview plus a separate Send click through configured BYOK.
   {
     key: 'advice.apiKey',
     type: 'string',
     default: '',
-    storage: 'config',
+    storage: 'secret',
     group: 'advice',
     label: 'API key',
-    help: 'For the api backend. Stays in VS Code settings.',
+    help: 'Bring-your-own key for the configured endpoint. It is stored in VS Code SecretStorage and is never sent to the dashboard or placed in a preview body.',
     secret: true,
   },
   {
@@ -615,7 +672,7 @@ export const SETTINGS: SettingDef[] = [
     default: 30,
     storage: 'state',
     group: 'advice',
-    label: 'Prompt sample window (days)',
+    label: 'Evidence and prompt window (days)',
     min: 1,
     max: 365,
   },
@@ -626,7 +683,7 @@ export const SETTINGS: SettingDef[] = [
     storage: 'state',
     group: 'advice',
     label: 'Personal/project context',
-    help: 'Optional background; adds a "Personalised" section.',
+    help: 'Optional free text. It may leave the machine only with separate prompt-personalization consent and appears verbatim in the exact request preview.',
     multiline: true,
   },
   {
@@ -636,24 +693,170 @@ export const SETTINGS: SettingDef[] = [
     storage: 'state',
     group: 'advice',
     label: 'Enable Usage Optimizer',
-    help: 'Show the opt-in Optimizer card on the Content tab.',
+    help: 'Show the opt-in Optimizer card on the Content tab. Its user-draft-only request is previewed before a separate Send action.',
   },
 ];
 
+/** Exact globalState entries owned by the current catalog or known releases. */
+export const OWNED_SETTING_GLOBAL_STATE_KEYS: readonly string[] = [
+  ...SETTINGS
+    .filter((definition) => definition.storage === 'state' || definition.storage === 'secret')
+    .map((definition) => STATE_PREFIX + definition.key),
+  ...RETIRED_SETTING_KEYS.map((key) => STATE_PREFIX + key),
+];
+
+/** Only these still-registered configuration keys may be updated through VS Code. */
+export const REGISTERED_CONFIGURATION_SETTING_KEYS: readonly string[] = SETTINGS
+  .filter((definition) => definition.storage === 'config')
+  .map((definition) => definition.key);
+
+/** Current and released keys inspected before a local-data clear. */
+export const KNOWN_CONFIGURATION_SETTING_KEYS: readonly string[] = [
+  ...new Set([
+    ...SETTINGS.map((definition) => definition.key),
+    ...RETIRED_SETTING_KEYS,
+  ]),
+];
+
 const BY_KEY: Map<string, SettingDef> = new Map(SETTINGS.map((d) => [d.key, d]));
 
 /** A snapshot of one setting for the webview panel: definition + current value. */
 export interface SettingView extends SettingDef {
   value: boolean | number | string;
+  /** Secret values never cross into the webview; it receives only this bit. */
+  configured?: boolean;
 }
 
 /**
- * Read/write layer over the two stores. Core settings live in VS Code config;
- * the rest live in globalState. Both are addressed by the same dotted key.
+ * Read/write layer over VS Code configuration, globalState, and SecretStorage.
+ * All entries are addressed by the same dotted catalog key.
  */
 export class SettingsStore {
+  private readonly secretValues = new Map<string, string>();
+
   constructor(private context: vscode.ExtensionContext) {}
 
+  private secretKey(key: string): string {
+    return SECRET_PREFIX + key;
+  }
+
+  /**
+   * Load secrets before the extension starts. Legacy plaintext values migrate
+   * only after SecretStorage succeeds, then are removed from globalState and
+   * the old global configuration entry. This method is idempotent.
+   */
+  async initializeSecrets(): Promise<void> {
+    const secrets = this.context.secrets;
+    if (!secrets) {
+      throw new SettingsSecretMigrationError('secret-storage-unavailable');
+    }
+    try {
+      const rootConfiguration = this.cfg();
+      for (const def of SETTINGS) {
+        if (def.storage !== 'secret') {
+          continue;
+        }
+        const storageKey = this.secretKey(def.key);
+        let value = await secrets.get(storageKey);
+        const legacyStateKey = STATE_PREFIX + def.key;
+        const legacyState = this.context.globalState.get<unknown>(legacyStateKey);
+        const inspected = rootConfiguration.inspect<unknown>(def.key);
+        const folderScopes = (vscode.workspace.workspaceFolders ?? []).map((folder) => {
+          const configuration = vscode.workspace.getConfiguration('claudeCodeUsage', folder.uri);
+          return {
+            configuration,
+            value: configuration.inspect<unknown>(def.key)?.workspaceFolderValue,
+          };
+        });
+        const legacyScopes = [
+          legacyState,
+          inspected?.globalValue,
+          inspected?.workspaceValue,
+          ...folderScopes.map((scope) => scope.value),
+        ];
+        const strings = legacyScopes
+          .filter((candidate): candidate is string => typeof candidate === 'string')
+          .map((candidate) => candidate.trim())
+          .filter((candidate) => candidate !== '');
+
+        const configurationPlaintext = [
+          inspected?.globalValue,
+          inspected?.workspaceValue,
+          ...folderScopes.map((scope) => scope.value),
+        ].some((candidate) =>
+          typeof candidate === 'string' && candidate.trim() !== '',
+        );
+        if (configurationPlaintext) {
+          // `advice.apiKey` is intentionally no longer registered. VS Code
+          // refuses programmatic updates to unregistered settings, so an
+          // automatic migration could copy the secret yet leave plaintext in
+          // settings.json. Require explicit manual removal instead.
+          throw new SettingsSecretMigrationError(
+            'workspace-secret-requires-manual-migration',
+          );
+        }
+
+        if (!value) {
+          const machineCandidates = [legacyState, inspected?.globalValue]
+            .filter((candidate): candidate is string => typeof candidate === 'string')
+            .map((candidate) => candidate.trim())
+            .filter((candidate) => candidate !== '');
+          const distinctMachineCandidates = [...new Set(machineCandidates)];
+          if (distinctMachineCandidates.length > 1) {
+            throw new SettingsSecretMigrationError('legacy-secret-conflict');
+          }
+          const machineCandidate = distinctMachineCandidates[0];
+          const workspaceCandidates = [
+            inspected?.workspaceValue,
+            ...folderScopes.map((scope) => scope.value),
+          ].filter((candidate): candidate is string => typeof candidate === 'string');
+
+          if (!machineCandidate && workspaceCandidates.some((candidate) => candidate.trim() !== '')) {
+            // A global SecretStorage slot cannot safely preserve a workspace-
+            // specific key. Leave the plaintext untouched and ask the user to
+            // migrate it explicitly instead of selecting one folder silently.
+            throw new SettingsSecretMigrationError('workspace-secret-requires-manual-migration');
+          }
+          if (
+            machineCandidate &&
+            workspaceCandidates.some((candidate) => candidate.trim() !== machineCandidate)
+          ) {
+            throw new SettingsSecretMigrationError('legacy-secret-conflict');
+          }
+          if (machineCandidate) {
+            // A second Extension Host may have completed the same machine-wide
+            // migration after our first read. Re-read before writing; all safe
+            // automatic candidates are already required to be identical.
+            const concurrentValue = await secrets.get(storageKey);
+            if (concurrentValue) {
+              value = concurrentValue;
+            } else {
+              await secrets.store(storageKey, machineCandidate);
+              value = machineCandidate;
+            }
+          }
+        }
+
+        // Delete legacy entries only when a secure value is present, or when
+        // every explicit legacy entry is empty. This prevents a partial
+        // migration from destroying the only recoverable credential.
+        if (value || strings.length === 0) {
+          if (legacyState !== undefined) {
+            await this.context.globalState.update(legacyStateKey, undefined);
+          }
+        }
+        if (value) {
+          this.secretValues.set(def.key, value);
+        }
+      }
+    } catch (error) {
+      if (error instanceof SettingsSecretMigrationError) {
+        throw error;
+      }
+      throw new SettingsSecretMigrationError('secret-storage-failed');
+    }
+  }
+
   private cfg(): vscode.WorkspaceConfiguration {
     return vscode.workspace.getConfiguration('claudeCodeUsage');
   }
@@ -667,6 +870,9 @@ export class SettingsStore {
     if (def.storage === 'config') {
       return this.cfg().get<T>(def.key, def.default as unknown as T);
     }
+    if (def.storage === 'secret') {
+      return (this.secretValues.get(def.key) ?? def.default) as unknown as T;
+    }
     return this.context.globalState.get<T>(STATE_PREFIX + def.key, def.default as unknown as T);
   }
 
@@ -679,6 +885,15 @@ export class SettingsStore {
     const coerced = this.coerce(def, value);
     if (def.storage === 'config') {
       await this.cfg().update(def.key, coerced, vscode.ConfigurationTarget.Global);
+    } else if (def.storage === 'secret') {
+      const secret = String(coerced).trim();
+      if (secret === '') {
+        await this.context.secrets.delete(this.secretKey(def.key));
+        this.secretValues.delete(def.key);
+      } else {
+        await this.context.secrets.store(this.secretKey(def.key), secret);
+        this.secretValues.set(def.key, secret);
+      }
     } else {
       await this.context.globalState.update(STATE_PREFIX + def.key, coerced);
     }
@@ -692,11 +907,152 @@ export class SettingsStore {
     }
     if (def.storage === 'config') {
       await this.cfg().update(def.key, undefined, vscode.ConfigurationTarget.Global);
+    } else if (def.storage === 'secret') {
+      await this.context.secrets.delete(this.secretKey(def.key));
+      this.secretValues.delete(def.key);
     } else {
       await this.context.globalState.update(STATE_PREFIX + def.key, undefined);
     }
   }
 
+  private explicitConfigurationScopes(key: string): Array<{
+    configuration: vscode.WorkspaceConfiguration;
+    target: vscode.ConfigurationTarget;
+  }> {
+    const scopes: Array<{
+      configuration: vscode.WorkspaceConfiguration;
+      target: vscode.ConfigurationTarget;
+    }> = [];
+    const root = this.cfg();
+    const rootValues = root.inspect<unknown>(key);
+    if (rootValues?.globalValue !== undefined) {
+      scopes.push({ configuration: root, target: vscode.ConfigurationTarget.Global });
+    }
+    const workspaceOpen = vscode.workspace.workspaceFile !== undefined ||
+      (vscode.workspace.workspaceFolders?.length ?? 0) > 0;
+    if (workspaceOpen && rootValues?.workspaceValue !== undefined) {
+      scopes.push({ configuration: root, target: vscode.ConfigurationTarget.Workspace });
+    }
+    for (const folder of vscode.workspace.workspaceFolders ?? []) {
+      const configuration = vscode.workspace.getConfiguration('claudeCodeUsage', folder.uri);
+      if (configuration.inspect<unknown>(key)?.workspaceFolderValue !== undefined) {
+        scopes.push({
+          configuration,
+          target: vscode.ConfigurationTarget.WorkspaceFolder,
+        });
+      }
+    }
+    return scopes;
+  }
+
+  private preflightConfigurationClear(keys: readonly string[]): void {
+    const registered = new Set(REGISTERED_CONFIGURATION_SETTING_KEYS);
+    const blocked = keys.filter((key) =>
+      !registered.has(key) && this.explicitConfigurationScopes(key).length > 0,
+    );
+    if (blocked.length > 0) {
+      // VS Code rejects updates to keys no longer registered by the current
+      // manifest. Stop before deleting SecretStorage/globalState so the user
+      // never receives a misleading partial-clear success.
+      throw new SettingsLocalDataClearError([...new Set(blocked)].sort());
+    }
+  }
+
+  private async clearRegisteredConfigurationScopes(key: string): Promise<void> {
+    for (const scope of this.explicitConfigurationScopes(key)) {
+      await scope.configuration.update(key, undefined, scope.target);
+    }
+  }
+
+  private async clearOwnedSetting(def: SettingDef): Promise<void> {
+    if (def.storage === 'state') {
+      await this.context.globalState.update(STATE_PREFIX + def.key, undefined);
+    } else if (def.storage === 'secret') {
+      await this.context.secrets.delete(this.secretKey(def.key));
+      this.secretValues.delete(def.key);
+      // Released development builds briefly used the state slot as a
+      // plaintext migration source. Remove only this exact key.
+      await this.context.globalState.update(STATE_PREFIX + def.key, undefined);
+    }
+    if (def.storage === 'config') {
+      await this.clearRegisteredConfigurationScopes(def.key);
+    }
+  }
+
+  private async verifyOwnedSettingsCleared(definitions: readonly SettingDef[]): Promise<void> {
+    for (const definition of definitions) {
+      if (
+        (definition.storage === 'state' || definition.storage === 'secret') &&
+        this.context.globalState.get(STATE_PREFIX + definition.key) !== undefined
+      ) {
+        throw new Error('settings-local-data-clear:state-postcondition-failed');
+      }
+      if (
+        definition.storage === 'secret' &&
+        await this.context.secrets.get(this.secretKey(definition.key)) !== undefined
+      ) {
+        throw new Error('settings-local-data-clear:secret-postcondition-failed');
+      }
+      if (
+        definition.storage === 'config' &&
+        this.explicitConfigurationScopes(definition.key).length > 0
+      ) {
+        throw new Error('settings-local-data-clear:configuration-postcondition-failed');
+      }
+    }
+  }
+
+  /** Clear a bounded subset of catalogued settings from every visible scope. */
+  async resetOwnedSettings(keys: readonly string[]): Promise<void> {
+    const definitions = keys.map((key) => {
+      const definition = BY_KEY.get(key);
+      if (!definition) throw new Error(`Unknown setting: ${key}`);
+      return definition;
+    });
+    this.preflightConfigurationClear(definitions.map((definition) => definition.key));
+    for (const def of definitions) {
+      await this.clearOwnedSetting(def);
+    }
+    await this.verifyOwnedSettingsCleared(definitions);
+  }
+
+  /** Clear the secret and every exact plaintext migration location we can inspect. */
+  async clearByokOwnedData(): Promise<void> {
+    await this.resetOwnedSettings(['advice.apiKey']);
+  }
+
+  /** Reset both host-side feature toggles owned by sharing/heatmap UI. */
+  async resetSharingOwnedData(): Promise<void> {
+    await this.resetOwnedSettings(['showHeatmap', 'enableShareCard']);
+  }
+
+  preflightResetAllOwnedData(): void {
+    this.preflightConfigurationClear(KNOWN_CONFIGURATION_SETTING_KEYS);
+  }
+
+  /**
+   * Clear the exact settings catalog from globalState, SecretStorage, and all
+   * currently inspectable configuration scopes. This is intentionally an
+   * allowlist; it never deletes arbitrary `claudeCodeUsage` configuration.
+   */
+  async resetAllOwnedData(): Promise<void> {
+    this.preflightResetAllOwnedData();
+    for (const def of SETTINGS) {
+      await this.clearOwnedSetting(def);
+    }
+    // Retired names are migration inputs, not an invitation to prefix-delete
+    // unknown future settings.
+    for (const key of RETIRED_SETTING_KEYS) {
+      await this.context.globalState.update(STATE_PREFIX + key, undefined);
+    }
+    await this.verifyOwnedSettingsCleared(SETTINGS);
+    for (const key of RETIRED_SETTING_KEYS) {
+      if (this.context.globalState.get(STATE_PREFIX + key) !== undefined) {
+        throw new Error('settings-local-data-clear:retired-state-postcondition-failed');
+      }
+    }
+  }
+
   /** Clamp/validate a value against the def so the panel can't store garbage. */
   private coerce(def: SettingDef, value: boolean | number | string): boolean | number | string {
     if (def.type === 'boolean') {
@@ -724,7 +1080,13 @@ export class SettingsStore {
 
   /** Catalog + current values, for rendering the dashboard settings panel. */
   snapshot(): SettingView[] {
-    return SETTINGS.map((def) => ({ ...def, value: this.get(def.key) }));
+    return SETTINGS.map((def) => def.storage === 'secret'
+      ? {
+          ...def,
+          value: '',
+          configured: this.secretValues.has(def.key),
+        }
+      : { ...def, value: this.get(def.key) });
   }
 
   /**
diff --git a/src/statusBar.ts b/src/statusBar.ts
index bb99fa0a..adb51429 100644
--- a/src/statusBar.ts
+++ b/src/statusBar.ts
@@ -23,7 +23,13 @@ import {
   normalizeQuotaWindows,
   visibleQuotaWindows
 } from './quotaWindows';
-import { CodexStatusMetric, formatCodexStatus } from './codexStatus';
+import {
+  CodexStatusMetric,
+  codexQuotaWarningPercent,
+  codexQuotaWindowLabel,
+  formatCodexStatus,
+  visibleCodexQuotaWindows,
+} from './codexStatus';
 import { CodexUsageScopeView } from './providers/codex/codexUsage';
 import { ProviderLimitSnapshot } from './providers/providerTypes';
 
@@ -102,7 +108,7 @@ export class StatusBarManager {
         );
       } else {
         this.statusBarItem.text = 'CX —';
-        this.statusBarItem.tooltip = I18n.t.providers.codex.noRecentTask;
+        this.statusBarItem.tooltip = I18n.t.providers.codex.noDailyData;
         this.statusBarItem.backgroundColor = undefined;
         this.quotaItem.hide();
         this.applyCostVisibility();
@@ -369,13 +375,21 @@ export class StatusBarManager {
     metric: CodexStatusMetric,
     limit: ProviderLimitSnapshot | null,
   ): void {
-    const formatted = formatCodexStatus(scope, metric, limit);
+    const now = Date.now();
+    const quotaOptions = { quotaFiveHourOnly: this.quotaFiveHourOnly };
+    const formatted = formatCodexStatus(
+      scope,
+      metric,
+      limit,
+      now,
+      quotaOptions,
+    );
     const copy = I18n.t.providers.codex;
     this.isLoading = false;
     this.statusBarItem.text = formatted.text;
     this.statusBarItem.backgroundColor = undefined;
     const md = new vscode.MarkdownString();
-    md.appendMarkdown(`**${copy.title} — ${copy.lastTask}**\n\n`);
+    md.appendMarkdown(`**${copy.title} — ${I18n.t.popup.today}**\n\n`);
     if (scope.indexedSubtotal) {
       md.appendMarkdown(`_${copy.indexedSubtotal} — ${copy.indexingInProgress}_\n\n`);
     }
@@ -388,10 +402,12 @@ export class StatusBarManager {
     this.statusBarItem.tooltip = md;
     this.applyCostVisibility();
 
-    if (formatted.limitText) {
+    if (formatted.limitText && formatted.limit && limit) {
       this.quotaItem.text = `$(dashboard) ${formatted.limitText}`;
-      this.quotaItem.tooltip = `${copy.accountSnapshotLastObserved} — ${formatted.limitText}`;
-      this.quotaItem.backgroundColor = undefined;
+      this.quotaItem.tooltip = this.createCodexQuotaTooltip(limit, now);
+      this.quotaItem.backgroundColor = this.fillBackground(
+        fillLevel(codexQuotaWarningPercent(limit, now, quotaOptions), QUOTA_FILL_THRESHOLDS),
+      );
       this.quotaItem.show();
     } else {
       this.quotaItem.hide();
@@ -527,6 +543,65 @@ export class StatusBarManager {
     return md;
   }
 
+  /** Codex exposes the same window facts through its local provider adapter.
+   * Render them with the exact table, progress bar, reset-cell, and threshold
+   * vocabulary used by Claude so switching providers does not change the
+   * interaction model. */
+  private createCodexQuotaTooltip(limit: ProviderLimitSnapshot, now: number): vscode.MarkdownString {
+    const t = I18n.t.popup;
+    const copy = I18n.t.providers.codex;
+    const live = visibleCodexQuotaWindows(limit, now, {
+      quotaFiveHourOnly: this.quotaFiveHourOnly,
+    });
+    const md = new vscode.MarkdownString();
+    md.supportThemeIcons = true;
+    md.supportHtml = true;
+    md.appendMarkdown(`**${copy.usageLimits}**\n\n`);
+    md.appendMarkdown(`<table>\n`);
+    md.appendMarkdown(
+      `<tr><th align="left">${t.quotaWindow}</th>` +
+      `<th></th><th align="right">${t.share}</th>` +
+      `<th align="right">${t.resets}</th></tr>\n`,
+    );
+    for (const window of live) {
+      const pct = Math.max(0, Math.min(100, window.usedPercent));
+      const label = window.windowMinutes === 5 * 60
+        ? t.quota5h
+        : window.windowMinutes === 7 * 24 * 60
+          ? t.quotaWeekly
+          : codexQuotaWindowLabel(window.windowMinutes, window.label);
+      const reset = window.resetsAt === undefined
+        ? '—'
+        : formatResetCell(new Date(window.resetsAt).toISOString(), {
+            format: this.resetCountdownFormat,
+            now,
+          });
+      md.appendMarkdown(this.quotaRowHtml(
+        this.escapeTooltipHtml(label),
+        `${Math.round(pct)}%`,
+        pct,
+        reset,
+      ));
+    }
+    md.appendMarkdown(`</table>\n\n`);
+    md.appendMarkdown(`*${copy.localLogNotLive}*`);
+    for (const note of copy.accountSnapshotLastObserved.split(' · ')) {
+      md.appendMarkdown(`  \n*${note}*`);
+    }
+    return md;
+  }
+
+  /** Provider labels can originate in local structured observations. Escape
+   * them before inserting them into the HTML-enabled Markdown tooltip. */
+  private escapeTooltipHtml(value: string): string {
+    return value
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
   /** Credit amounts always carry two decimals (they are real money, unlike the
    * estimated token costs elsewhere, which follow the user's decimalPlaces).
    * I18n.formatCurrency is USD-only, so any other currency prints its code
diff --git a/src/test/adviceAdapters.test.ts b/src/test/adviceAdapters.test.ts
new file mode 100644
index 00000000..c17491ac
--- /dev/null
+++ b/src/test/adviceAdapters.test.ts
@@ -0,0 +1,312 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  CLAUDE_CLEAR_MIN_AFFECTED_SESSIONS,
+  CLAUDE_CLEAR_MIN_AFFECTED_SHARE,
+  adaptClaudeAdvice,
+  adaptCodexLocalAdvice,
+} from '../adviceEffectiveness/adapters';
+import { prepareAdvicePayload } from '../adviceEffectiveness/payload';
+import { payloadInputFixture } from './adviceTestFixtures';
+
+function claudeInput() {
+  const payload = payloadInputFixture();
+  return {
+    adviceId: 'advice-claude-window-1',
+    generatedAt: '2026-08-24T08:00:00.000Z',
+    locale: 'en',
+    aggregate: payload.aggregate,
+    sessionSummary: {
+      scope: payload.aggregate.scope,
+      windowDays: payload.aggregate.windowDays,
+      totalSessions: 8,
+      longSessionCount: 0,
+      largeContextSessionCount: 0,
+    },
+  } as const;
+}
+
+test('Claude adapter creates guarded /clear advice only after the declared session threshold', () => {
+  const input = claudeInput();
+  const affected = Math.max(
+    CLAUDE_CLEAR_MIN_AFFECTED_SESSIONS,
+    Math.ceil(input.sessionSummary.totalSessions * CLAUDE_CLEAR_MIN_AFFECTED_SHARE),
+  );
+  const result = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: { ...input.sessionSummary, longSessionCount: affected },
+  });
+
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.remoteEvidenceEligible, true);
+  assert.equal(result.value.contract.privacy.dataMode, 'local-only');
+  assert.equal(result.value.contract.recommendations.length, 1);
+  const recommendation = result.value.contract.recommendations[0];
+  assert.deepEqual(recommendation.conditionalActions.map((action) => action.action), ['/clear']);
+  assert.equal(recommendation.successCriteria.length, 1);
+  assert.equal(recommendation.successCriteria[0].qualityGuardrail.rubricId, 'task-quality-rubric-v1');
+  const prepared = prepareAdvicePayload({
+    locale: result.value.contract.provenance.locale,
+    aggregate: result.value.aggregate,
+    sources: result.value.contract.provenance.sources,
+    observations: result.value.contract.observations,
+    evidence: result.value.contract.evidence,
+  });
+  assert.equal(prepared.dataMode, 'aggregates-only');
+
+  const below = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: {
+      ...input.sessionSummary,
+      longSessionCount: Math.max(0, affected - 1),
+      largeContextSessionCount: Math.max(0, affected - 1),
+    },
+  });
+  assert.equal(below.ok, true);
+  if (below.ok) assert.deepEqual(below.value.contract.recommendations, []);
+
+  const countOnly = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: {
+      ...input.sessionSummary,
+      totalSessions: 20,
+      longSessionCount: CLAUDE_CLEAR_MIN_AFFECTED_SESSIONS,
+    },
+  });
+  assert.equal(countOnly.ok, true);
+  if (countOnly.ok) assert.deepEqual(countOnly.value.contract.recommendations, []);
+
+  const shareOnly = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: {
+      ...input.sessionSummary,
+      totalSessions: 1,
+      largeContextSessionCount: 1,
+    },
+  });
+  assert.equal(shareOnly.ok, true);
+  if (shareOnly.ok) assert.deepEqual(shareOnly.value.contract.recommendations, []);
+
+  const contextTriggered = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: { ...input.sessionSummary, largeContextSessionCount: affected },
+  });
+  assert.equal(contextTriggered.ok, true);
+  if (contextTriggered.ok) {
+    assert.equal(
+      contextTriggered.value.contract.recommendations[0].successCriteria[0].metricObservationId,
+      'observation-claude-large-context-share',
+    );
+  }
+});
+
+test('Claude adapter rejects a session summary from a different window or scope', () => {
+  const input = claudeInput();
+  const wrongWindow = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: { ...input.sessionSummary, windowDays: input.aggregate.windowDays - 1 },
+  });
+  assert.equal(wrongWindow.ok, false);
+  if (!wrongWindow.ok) {
+    assert.deepEqual(wrongWindow.issues, ['claude-session-summary-scope-window-mismatch']);
+  }
+
+  const wrongScope = adaptClaudeAdvice({
+    ...input,
+    sessionSummary: { ...input.sessionSummary, scope: 'project' },
+  });
+  assert.equal(wrongScope.ok, false);
+});
+
+test('Claude adapter rebuilds its DTO and cannot retain injected paths, sessions, prompts, or raw model fields', () => {
+  const privateSentinel = '/Users/private/project/PRIVATE_SESSION prompt';
+  const input = claudeInput() as ReturnType<typeof claudeInput> & Record<string, unknown>;
+  input.sessionId = privateSentinel;
+  (input.aggregate as unknown as Record<string, unknown>).projectPath = privateSentinel;
+  (input.aggregate.modelFamilies[0] as unknown as Record<string, unknown>).rawModel = privateSentinel;
+  (input.sessionSummary as unknown as Record<string, unknown>).prompt = privateSentinel;
+
+  const result = adaptClaudeAdvice(input);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(JSON.stringify(result.value).includes(privateSentinel), false);
+});
+
+test('Claude framework-overhead seam emits only a numeric proxy and never creates writing advice', () => {
+  const input = claudeInput();
+  const result = adaptClaudeAdvice({
+    ...input,
+    frameworkOverhead: {
+      frameworkEstimatedTokens: 300,
+      observedInputEstimatedTokens: 2_000,
+      classifiedEvents: 5,
+      prompt: 'PRIVATE_FRAMEWORK_PROMPT',
+      toolResultText: 'PRIVATE_TOOL_RESULT_BODY',
+    } as {
+      frameworkEstimatedTokens: number;
+      observedInputEstimatedTokens: number;
+      classifiedEvents: number;
+    },
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  const observation = result.value.contract.observations.find(
+    (item) => item.metric === 'framework-overhead-share',
+  );
+  assert.deepEqual(
+    observation && { value: observation.value, unit: observation.unit, method: observation.method },
+    { value: 0.15, unit: 'ratio', method: 'structural-proxy' },
+  );
+  assert.deepEqual(result.value.contract.recommendations, []);
+  assert.equal(JSON.stringify(result.value).includes('PRIVATE_FRAMEWORK_PROMPT'), false);
+  assert.equal(JSON.stringify(result.value).includes('PRIVATE_TOOL_RESULT_BODY'), false);
+  const prepared = prepareAdvicePayload({
+    locale: result.value.contract.provenance.locale,
+    aggregate: result.value.aggregate,
+    sources: result.value.contract.provenance.sources,
+    observations: result.value.contract.observations,
+    evidence: result.value.contract.evidence,
+  });
+  assert.match(prepared.serializedBody, /framework-overhead-share/);
+  assert.doesNotMatch(prepared.serializedBody, /PRIVATE_FRAMEWORK_PROMPT|PRIVATE_TOOL_RESULT_BODY/);
+
+  const invalid = adaptClaudeAdvice({
+    ...input,
+    frameworkOverhead: {
+      frameworkEstimatedTokens: -1,
+      observedInputEstimatedTokens: 1,
+      classifiedEvents: 1,
+    },
+  });
+  assert.equal(invalid.ok, false);
+
+  const fractionalEvents = adaptClaudeAdvice({
+    ...input,
+    frameworkOverhead: {
+      frameworkEstimatedTokens: 1,
+      observedInputEstimatedTokens: 2,
+      classifiedEvents: 1.5,
+    },
+  });
+  assert.equal(fractionalEvents.ok, false);
+
+  const impossibleShare = adaptClaudeAdvice({
+    ...input,
+    frameworkOverhead: {
+      frameworkEstimatedTokens: 2,
+      observedInputEstimatedTokens: 1,
+      classifiedEvents: 1,
+    },
+  });
+  assert.equal(impossibleShare.ok, false);
+});
+
+function codexInput() {
+  return {
+    adviceId: 'advice-codex-window-1',
+    generatedAt: '2026-08-24T08:00:00.000Z',
+    locale: 'en',
+    scope: '30d' as const,
+    insights: [
+      {
+        kind: 'effort-comparison' as const,
+        severity: 'normal' as const,
+        scope: '30d' as const,
+        evidence: {
+          observedEffort: 'PRIVATE_EFFORT_SENTINEL',
+          highEffortFresh: 700,
+          lowMediumEffortFresh: 300,
+        },
+        proxy: true as const,
+      },
+      {
+        kind: 'cache-context' as const,
+        severity: 'info' as const,
+        scope: '30d' as const,
+        evidence: { processedToFreshRatio: 3, cachedInputShare: 0.7 },
+        proxy: true as const,
+      },
+    ],
+    behavior: {
+      childFreshShare: 0.2,
+      approvalReviewerFreshShare: 0.1,
+      highEffortFreshShare: 0.7,
+      processedToFreshRatio: 3,
+      cacheShare: 0.7,
+      postPatchToolCallsPerPatchCall: 4,
+    },
+    quality: {
+      indexComplete: true,
+      identityComplete: true,
+      periodComplete: true,
+      qualityFlags: [] as string[],
+    },
+  };
+}
+
+test('Codex adapter is local-only, maps reviewed behavior numbers, and drops observedEffort text', () => {
+  const result = adaptCodexLocalAdvice(codexInput());
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.remoteEvidenceEligible, false);
+  assert.equal(result.value.contract.privacy.dataMode, 'local-only');
+  const serialized = JSON.stringify(result.value);
+  assert.equal(serialized.includes('PRIVATE_EFFORT_SENTINEL'), false);
+  assert.deepEqual(
+    result.value.contract.observations.map((item) => [item.metric, item.unit, item.value]),
+    [
+      ['high-effort-share', 'ratio', 0.7],
+      ['processed-to-fresh-ratio', 'multiple', 3],
+      ['cache-read-share', 'ratio', 0.7],
+    ],
+  );
+  assert.equal(result.value.contract.recommendations.length, 2);
+});
+
+test('Codex adapter preserves incomplete evidence locally but blocks scope mismatches and unsafe quality flags', () => {
+  const partial = codexInput();
+  partial.quality.indexComplete = false;
+  const partialResult = adaptCodexLocalAdvice(partial);
+  assert.equal(partialResult.ok, true);
+  if (partialResult.ok) {
+    assert.equal(partialResult.value.contract.provenance.sources[0].confidence, 'unknown');
+    assert.deepEqual(partialResult.value.contract.provenance.sources[0].qualityFlags, ['incomplete-index']);
+  }
+
+  const mismatched = codexInput();
+  (mismatched.insights[0] as { scope: string }).scope = '7d';
+  const mismatchResult = adaptCodexLocalAdvice(mismatched);
+  assert.equal(mismatchResult.ok, false);
+
+  const unsafe = codexInput();
+  unsafe.quality.qualityFlags = ['/Users/private/project'];
+  const unsafeResult = adaptCodexLocalAdvice(unsafe);
+  assert.equal(unsafeResult.ok, false);
+});
+
+test('prepared payload accepts a reviewed ratio expressed as an unbounded multiple', () => {
+  const input = payloadInputFixture();
+  input.observations = [
+    {
+      ...input.observations[0],
+      id: 'observation-processed-fresh',
+      metric: 'processed-to-fresh-ratio',
+      value: 3,
+      unit: 'multiple',
+      method: 'structural-proxy',
+    },
+  ];
+  input.evidence = [
+    {
+      ...input.evidence[0],
+      observationIds: ['observation-processed-fresh'],
+      strength: 'proxy',
+      limitations: ['advice.limitation.codex.structural-proxy'],
+    },
+  ];
+  const prepared = prepareAdvicePayload(input);
+  assert.match(prepared.serializedBody, /"unit":"multiple"/);
+  assert.match(prepared.serializedBody, /"value":3/);
+});
diff --git a/src/test/adviceComparison.test.ts b/src/test/adviceComparison.test.ts
new file mode 100644
index 00000000..6b7f0b3b
--- /dev/null
+++ b/src/test/adviceComparison.test.ts
@@ -0,0 +1,106 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  AdviceComparisonPolicy,
+  ComparableTaskPair,
+  compareAdviceEffectiveness,
+} from '../adviceEffectiveness/comparison';
+
+const policy: AdviceComparisonPolicy = {
+  minComparablePairs: 5,
+  minRelativeImprovement: 0.1,
+  minAfterQualityScore: 0.8,
+  maxMeanQualityRegression: 0.02,
+  allowedQualityFlags: [],
+};
+
+function pairs(afterValue: number = 80, afterQuality: number = 0.9): ComparableTaskPair[] {
+  return Array.from({ length: 5 }, (_, index) => ({
+    pairId: `pair-${index + 1}`,
+    before: {
+      context: {
+        taskKind: 'focused-code-change',
+        complexityBand: 'medium' as const,
+        provider: 'claude',
+        modelFamily: 'sonnet',
+        effort: 'high',
+        metricDefinitionVersion: 'tokens-v1',
+        qualityRubricId: 'acceptance-v1',
+      },
+      primaryMetric: {
+        name: 'total-tokens',
+        unit: 'tokens',
+        direction: 'lower-is-better' as const,
+        value: 100,
+      },
+      quality: { score: 0.9, passed: true, evidenceCount: 2 },
+      evidence: { coverage: 'complete' as const, confidence: 'high' as const, qualityFlags: [] },
+    },
+    after: {
+      context: {
+        taskKind: 'focused-code-change',
+        complexityBand: 'medium' as const,
+        provider: 'claude',
+        modelFamily: 'sonnet',
+        effort: 'high',
+        metricDefinitionVersion: 'tokens-v1',
+        qualityRubricId: 'acceptance-v1',
+      },
+      primaryMetric: {
+        name: 'total-tokens',
+        unit: 'tokens',
+        direction: 'lower-is-better' as const,
+        value: afterValue,
+      },
+      quality: { score: afterQuality, passed: true, evidenceCount: 2 },
+      evidence: { coverage: 'complete' as const, confidence: 'high' as const, qualityFlags: [] },
+    },
+  }));
+}
+
+test('concludes improved only after the metric threshold and quality guardrail both hold', () => {
+  const input = pairs();
+  const before = JSON.stringify(input);
+  const result = compareAdviceEffectiveness(input, policy);
+  assert.equal(result.status, 'improved');
+  if (result.status === 'improved') assert.equal(result.stats.meanRelativeImprovement, 0.2);
+  assert.equal(JSON.stringify(input), before, 'comparison must not mutate measurements');
+});
+
+test('returns insufficient evidence for small, incomparable, partial, or unknown-quality cohorts', () => {
+  assert.equal(compareAdviceEffectiveness(pairs().slice(0, 4), policy).status, 'insufficient-evidence');
+
+  const incomparable = pairs();
+  incomparable[1].after.context.modelFamily = 'opus';
+  assert.equal(compareAdviceEffectiveness(incomparable, policy).status, 'insufficient-evidence');
+
+  const partial = pairs();
+  partial[2].before.evidence.coverage = 'partial';
+  assert.equal(compareAdviceEffectiveness(partial, policy).status, 'insufficient-evidence');
+
+  const unknownQuality = pairs();
+  unknownQuality[3].after.quality.score = null;
+  assert.equal(compareAdviceEffectiveness(unknownQuality, policy).status, 'insufficient-evidence');
+});
+
+test('does not claim effectiveness when the primary metric improves but quality regresses', () => {
+  const result = compareAdviceEffectiveness(pairs(70, 0.75), policy);
+  assert.equal(result.status, 'quality-guardrail-failed');
+});
+
+test('reports no demonstrated improvement without turning it into a causal harm claim', () => {
+  const result = compareAdviceEffectiveness(pairs(95, 0.9), policy);
+  assert.equal(result.status, 'no-demonstrated-improvement');
+  assert.ok(result.reasons[0].includes('pre-declared'));
+});
+
+test('zero baselines and non-finite measurements are inconclusive', () => {
+  const zero = pairs();
+  zero[0].before.primaryMetric.value = 0;
+  assert.equal(compareAdviceEffectiveness(zero, policy).status, 'insufficient-evidence');
+
+  const invalid = pairs();
+  invalid[0].after.primaryMetric.value = Number.NaN;
+  assert.equal(compareAdviceEffectiveness(invalid, policy).status, 'insufficient-evidence');
+});
diff --git a/src/test/adviceComparisonPairing.test.ts b/src/test/adviceComparisonPairing.test.ts
new file mode 100644
index 00000000..8bfc74b4
--- /dev/null
+++ b/src/test/adviceComparisonPairing.test.ts
@@ -0,0 +1,148 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  ComparableObservation,
+  ComparablePairBuildInput,
+  buildComparableTaskPair,
+} from '../adviceEffectiveness/comparisonPairing';
+
+function observation(value: number, observedAtEpochMs: number): ComparableObservation {
+  return {
+    context: {
+      scope: 'task-cohort',
+      taskKind: 'small-change',
+      complexityBand: 'medium',
+      provider: 'codex',
+      modelFamily: 'other',
+      effort: 'high',
+      measurementProfileVersion: 'codex-aggregate-v1',
+      metricDefinitionVersion: 'fresh-tokens-v1',
+      qualityRubricId: 'task-quality-v1',
+    },
+    metric: {
+      name: 'fresh-tokens',
+      unit: 'tokens',
+      direction: 'lower-is-better',
+      value,
+    },
+    quality: { score: 0.9, passed: 'passed', evidenceCount: 2 },
+    evidence: { coverage: 'complete', confidence: 'high', qualityFlags: [] },
+    observedAtEpochMs,
+  };
+}
+
+function input(): ComparablePairBuildInput {
+  return {
+    adviceId: 'advice-day-2',
+    recommendationId: 'reduce-fresh-tokens',
+    recommendationVersion: 'recommendation-v1',
+    before: observation(1_000, 1_777_000_000_000),
+    after: observation(800, 1_777_086_400_000),
+    recordedAtEpochMs: 1_777_086_400_001,
+  };
+}
+
+test('builds a deterministic comparable pair from matching sanitized observations only', () => {
+  const candidate = input();
+  const before = JSON.stringify(candidate);
+  const first = buildComparableTaskPair(candidate);
+  const second = buildComparableTaskPair(candidate);
+  assert.equal(first.ok, true);
+  assert.deepEqual(second, first);
+  assert.equal(JSON.stringify(candidate), before, 'pairing must not mutate observations');
+  if (!first.ok) return;
+  assert.match(first.value.pairId, /^pair-[a-f0-9]{32}$/);
+  assert.equal(first.value.context.scope, 'task-cohort');
+  assert.equal(first.value.context.measurementProfileVersion, 'codex-aggregate-v1');
+  assert.equal(first.value.recommendationVersion, 'recommendation-v1');
+  assert.equal(first.value.metric.beforeValue, 1_000);
+  assert.equal(first.value.metric.afterValue, 800);
+  assert.doesNotMatch(
+    JSON.stringify(first.value),
+    /prompt|session|path|body/i,
+    'the persisted pair is aggregate-only and content-free',
+  );
+});
+
+test('returns evidence-insufficient for every mismatched comparison dimension', () => {
+  const mismatches: Array<(candidate: ComparablePairBuildInput) => void> = [
+    (candidate) => { candidate.after.context.scope = 'project'; },
+    (candidate) => { candidate.after.context.taskKind = 'feature'; },
+    (candidate) => { candidate.after.context.complexityBand = 'high'; },
+    (candidate) => { candidate.after.context.provider = 'claude'; },
+    (candidate) => { candidate.after.context.modelFamily = 'sonnet'; },
+    (candidate) => { candidate.after.context.effort = 'medium'; },
+    (candidate) => { candidate.after.context.measurementProfileVersion = 'codex-aggregate-v2'; },
+    (candidate) => { candidate.after.context.metricDefinitionVersion = 'fresh-tokens-v2'; },
+    (candidate) => { candidate.after.context.qualityRubricId = 'task-quality-v2'; },
+    (candidate) => { candidate.after.metric.name = 'processed-tokens'; },
+    (candidate) => { candidate.after.metric.unit = 'count'; },
+    (candidate) => { candidate.after.metric.direction = 'higher-is-better'; },
+  ];
+
+  for (const change of mismatches) {
+    const candidate = input();
+    change(candidate);
+    const result = buildComparableTaskPair(candidate);
+    assert.equal(result.ok, false);
+    if (!result.ok) assert.equal(result.reason, 'evidence-insufficient');
+  }
+});
+
+test('returns explicit evidence-insufficient issues for unreliable observations', () => {
+  const cases: Array<{
+    issue: string;
+    change: (candidate: ComparablePairBuildInput) => void;
+  }> = [
+    { issue: 'incomplete-coverage', change: (candidate) => { candidate.before.evidence.coverage = 'partial'; } },
+    { issue: 'insufficient-confidence', change: (candidate) => { candidate.after.evidence.confidence = 'low'; } },
+    { issue: 'unresolved-quality-flags', change: (candidate) => { candidate.after.evidence.qualityFlags = ['schema-drift']; } },
+    { issue: 'unknown-quality-result', change: (candidate) => { candidate.after.quality.passed = 'unknown'; } },
+    { issue: 'missing-quality-evidence', change: (candidate) => { candidate.before.quality.evidenceCount = 0; } },
+    { issue: 'failed-quality-baseline', change: (candidate) => { candidate.before.quality.passed = 'failed'; } },
+    { issue: 'unknown-effort', change: (candidate) => {
+      candidate.before.context.effort = 'unknown';
+      candidate.after.context.effort = 'unknown';
+    } },
+    { issue: 'zero-metric-baseline', change: (candidate) => { candidate.before.metric.value = 0; } },
+    { issue: 'invalid-observation-order', change: (candidate) => { candidate.after.observedAtEpochMs = candidate.before.observedAtEpochMs; } },
+  ];
+
+  for (const { issue, change } of cases) {
+    const candidate = input();
+    change(candidate);
+    const result = buildComparableTaskPair(candidate);
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.equal(result.reason, 'evidence-insufficient');
+      assert.ok(result.issues.includes(issue as never), `${issue} should be explicit`);
+    }
+  }
+});
+
+test('rejects prompt, session, path, body, and any other unknown field at every boundary', () => {
+  const hostileValues: unknown[] = [
+    { ...input(), prompt: 'PRIVATE_PROMPT' },
+    { ...input(), sessionId: 'PRIVATE_SESSION' },
+    { ...input(), body: 'PRIVATE_BODY' },
+    (() => {
+      const candidate = input() as ComparablePairBuildInput & { before: ComparableObservation & { projectPath: string } };
+      candidate.before.projectPath = '/Users/private/project';
+      return candidate;
+    })(),
+    (() => {
+      const candidate = input() as ComparablePairBuildInput & {
+        after: ComparableObservation & { context: ComparableObservation['context'] & { unknown: string } };
+      };
+      candidate.after.context.unknown = 'not-allowed';
+      return candidate;
+    })(),
+  ];
+
+  for (const hostile of hostileValues) {
+    const result = buildComparableTaskPair(hostile);
+    assert.equal(result.ok, false);
+    if (!result.ok) assert.equal(result.reason, 'invalid-input');
+  }
+});
diff --git a/src/test/adviceComparisonProduction.test.ts b/src/test/adviceComparisonProduction.test.ts
new file mode 100644
index 00000000..1d36a59c
--- /dev/null
+++ b/src/test/adviceComparisonProduction.test.ts
@@ -0,0 +1,239 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import Module = require('node:module');
+
+import {
+  CodexComparableTaskProjection,
+  buildAppliedComparablePairs,
+} from '../adviceEffectiveness/comparisonProduction';
+import { adaptCodexLocalAdvice } from '../adviceEffectiveness/adapters';
+import { createClosedAdviceLocalState } from '../adviceEffectiveness/versionedPersistence';
+
+function projection(observedAtEpochMs: number, fresh: number): CodexComparableTaskProjection {
+  return {
+    observedAtEpochMs,
+    total: { processed: fresh * 2, fresh },
+    structural: {
+      patchCalls: 1,
+      toolCalls: 4,
+      postPatchToolCalls: 2,
+      taskCompleteCount: 1,
+    },
+    childFreshShare: 0,
+    approvalReviewerFreshShare: 0,
+    modelFamilies: ['other'],
+    efforts: ['high'],
+    coverage: { complete: true, identityComplete: true, qualityFlags: [] },
+  };
+}
+
+test('pairs five real completed Codex task projections around the applied timestamp', () => {
+  const input = {
+    adviceId: 'advice-codex-30d-1',
+    recommendationId: 'recommendation-codex-effort-comparison',
+    recommendationVersion: 'codex-local-rule-v1',
+    appliedAtEpochMs: 1_000,
+    tasks: [
+      ...Array.from({ length: 5 }, (_, index) => projection(100 + index, 100)),
+      ...Array.from({ length: 5 }, (_, index) => projection(1_100 + index, 80)),
+    ],
+  };
+  const before = JSON.stringify(input);
+  const result = buildAppliedComparablePairs(input);
+  assert.equal(result.ok, true);
+  assert.equal(JSON.stringify(input), before, 'production must not mutate materialized projections');
+  if (!result.ok) return;
+  assert.equal(result.status, 'comparable');
+  assert.equal(result.pairs.length, 5);
+  assert.equal(result.pairs[0].context.scope, 'task-cohort');
+  assert.equal(result.pairs[0].context.taskKind, 'small-change');
+  assert.equal(result.pairs[0].context.measurementProfileVersion, 'codex-task-structural-v1');
+  assert.equal(result.pairs[0].quality.beforePassed, 'passed');
+  assert.equal(result.pairs[0].quality.afterPassed, 'passed');
+  assert.doesNotMatch(JSON.stringify(result), /prompt|session|path|body/i);
+});
+
+test('fails closed to evidence-insufficient when tasks are incomplete, mixed, or unreliable', () => {
+  const base = {
+    adviceId: 'advice-codex-30d-1',
+    recommendationId: 'recommendation-codex-effort-comparison',
+    recommendationVersion: 'codex-local-rule-v1',
+    appliedAtEpochMs: 1_000,
+  };
+  const unreliable = projection(1_100, 80);
+  unreliable.coverage.qualityFlags = ['schema-drift'];
+  const unknownEffort = projection(1_101, 80);
+  unknownEffort.efforts = ['unknown'];
+  const incomplete = projection(1_102, 80);
+  incomplete.structural.taskCompleteCount = 0;
+  const differentComplexity = projection(1_103, 500_000);
+
+  const result = buildAppliedComparablePairs({
+    ...base,
+    tasks: [projection(100, 100), unreliable, unknownEffort, incomplete, differentComplexity],
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.status, 'evidence-insufficient');
+  assert.equal(result.pairs.length, 0);
+});
+
+test('rejects sensitive or unknown fields before creating observations', () => {
+  const base = {
+    adviceId: 'advice-codex-30d-1',
+    recommendationId: 'recommendation-codex-effort-comparison',
+    recommendationVersion: 'codex-local-rule-v1',
+    appliedAtEpochMs: 1_000,
+    tasks: [projection(100, 100), projection(1_100, 80)],
+  };
+  const hostile: unknown[] = [
+    { ...base, prompt: 'PRIVATE_PROMPT' },
+    { ...base, sessionId: 'PRIVATE_SESSION' },
+    { ...base, projectPath: '/Users/private/project' },
+    { ...base, body: 'PRIVATE_BODY' },
+    (() => {
+      const value = JSON.parse(JSON.stringify(base));
+      value.tasks[0].title = 'PRIVATE_TITLE';
+      return value;
+    })(),
+  ];
+  for (const value of hostile) {
+    const result = buildAppliedComparablePairs(value);
+    assert.equal(result.ok, false);
+    if (!result.ok) assert.equal(result.reason, 'invalid-input');
+  }
+});
+
+function codexAdvice(insightKinds: Array<'effort-comparison' | 'post-patch-tool-intensity'>) {
+  const result = adaptCodexLocalAdvice({
+    adviceId: 'advice-codex-30d-1',
+    generatedAt: '2026-08-30T00:00:00.000Z',
+    locale: 'en',
+    scope: '30d',
+    insights: insightKinds.map((kind) => ({
+      kind,
+      severity: 'normal' as const,
+      scope: '30d' as const,
+      evidence: {},
+      proxy: true as const,
+    })),
+    behavior: {
+      childFreshShare: 0,
+      approvalReviewerFreshShare: 0,
+      highEffortFreshShare: 1,
+      processedToFreshRatio: 2,
+      cacheShare: 0.5,
+      postPatchToolCallsPerPatchCall: 2,
+    },
+    quality: {
+      indexComplete: true,
+      identityComplete: true,
+      periodComplete: true,
+      qualityFlags: [],
+    },
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) throw new Error('advice fixture failed');
+  return result.value.contract;
+}
+
+function withWebview<T>(run: (provider: any) => T): T {
+  const originalLoad = (Module as any)._load;
+  (Module as any)._load = function(request: string, parent: unknown, isMain: boolean) {
+    if (request === 'vscode') {
+      return { workspace: { workspaceFolders: [] } };
+    }
+    return originalLoad.call(this, request, parent, isMain);
+  };
+  try {
+    const { UsageWebviewProvider } = require('../webview') as typeof import('../webview');
+    const provider = new UsageWebviewProvider({} as any) as any;
+    provider.settings = { get: (key: string) => key === 'advice.effectiveness.enabled' };
+    provider.adviceLocalStateStatus = 'ready';
+    return run(provider);
+  } finally {
+    (Module as any)._load = originalLoad;
+  }
+}
+
+test('webview materializes bounded pairs and a frozen result from the existing Codex view only', () => {
+  withWebview((provider) => {
+    const contract = codexAdvice(['effort-comparison']);
+    provider.adviceEffectivenessStates = {
+      codex: {
+        provider: 'codex',
+        contract,
+        remotePreviewEligible: false,
+        promptSamples: [],
+      },
+    };
+    const local = createClosedAdviceLocalState();
+    local.featureMode = 'enabled';
+    local.feedback.push({
+      adviceId: contract.adviceId,
+      recommendationId: contract.recommendations[0].id,
+      rating: 'helpful',
+      applied: 'applied',
+      appliedAtEpochMs: 1_000,
+      updatedAtEpochMs: 1_000,
+    });
+    provider.adviceLocalState = local;
+    provider.codexView = {
+      recentThreads: [
+        ...Array.from({ length: 5 }, (_, index) => ({
+          rootTaskViewKey: `before-${index}`,
+          role: 'root',
+          observedAt: 100 + index,
+          total: { processed: 200, fresh: 100, input: 100, cachedInput: 0, output: 0, reasoning: 0 },
+          structural: { patchCalls: 1, toolCalls: 4, postPatchToolCalls: 2, compactCount: 0, taskCompleteCount: 1 },
+          models: ['gpt-5'],
+          efforts: ['high'],
+        })),
+        ...Array.from({ length: 5 }, (_, index) => ({
+          rootTaskViewKey: `after-${index}`,
+          role: 'root',
+          observedAt: 1_100 + index,
+          total: { processed: 160, fresh: 80, input: 80, cachedInput: 0, output: 0, reasoning: 0 },
+          structural: { patchCalls: 1, toolCalls: 4, postPatchToolCalls: 2, compactCount: 0, taskCompleteCount: 1 },
+          models: ['gpt-5'],
+          efforts: ['high'],
+        })),
+      ],
+      coverage: { complete: true, identity: { complete: true } },
+      qualityFlags: [],
+    };
+
+    const next = provider.materializeAdviceComparisonState(2_000);
+    assert.equal(next.comparablePairs.length, 5);
+    assert.equal(next.comparisonResults.length, 1);
+    assert.equal(next.comparisonResults[0].result.status, 'improved');
+    assert.doesNotMatch(JSON.stringify(next.comparablePairs), /before-|after-|gpt-5|prompt|session|path|body/i);
+  });
+});
+
+test('advice rendering gives every recommendation its own feedback and comparison boundary', () => {
+  withWebview((provider) => {
+    const contract = codexAdvice(['effort-comparison', 'post-patch-tool-intensity']);
+    provider.adviceEffectivenessStates = {
+      codex: {
+        provider: 'codex',
+        contract,
+        remotePreviewEligible: false,
+        promptSamples: [],
+      },
+    };
+    provider.adviceLocalState = createClosedAdviceLocalState();
+    const html = provider.renderAdviceEffectivenessBody('codex');
+    for (const recommendation of contract.recommendations) {
+      const matches = html.match(
+        new RegExp(`<button[^>]+data-recommendation-id="${recommendation.id}"`, 'g'),
+      ) ?? [];
+      assert.equal(matches.length, 4, `${recommendation.id} needs three feedback buttons plus snooze`);
+    }
+    assert.doesNotMatch(
+      provider.renderAdviceEffectivenessBody.toString(),
+      /recommendations\[0\]/,
+      'the rendering boundary must not collapse the contract to its first recommendation',
+    );
+  });
+});
diff --git a/src/test/adviceComparisonResult.test.ts b/src/test/adviceComparisonResult.test.ts
new file mode 100644
index 00000000..2031cf90
--- /dev/null
+++ b/src/test/adviceComparisonResult.test.ts
@@ -0,0 +1,189 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  AdviceComparisonResultBuildInput,
+  AdviceComparisonResultEnvelope,
+  buildAdviceComparisonResultEnvelope,
+  parseAdviceComparisonResultEnvelope,
+} from '../adviceEffectiveness/comparisonResult';
+import {
+  ComparablePairBuildInput,
+  StoredComparablePair,
+  buildComparableTaskPair,
+} from '../adviceEffectiveness/comparisonPairing';
+
+function pair(index: number, afterValue = 80, afterScore = 0.9, afterPassed: 'passed' | 'failed' = 'passed'): StoredComparablePair {
+  const base = 1_777_000_000_000 + index * 10_000;
+  const input: ComparablePairBuildInput = {
+    adviceId: `advice-${index}`,
+    recommendationId: 'reduce-token-use',
+    recommendationVersion: 'recommendation-v1',
+    before: {
+      context: {
+        scope: 'task-cohort',
+        taskKind: 'small-change',
+        complexityBand: 'medium',
+        provider: 'claude',
+        modelFamily: 'sonnet',
+        effort: 'high',
+        measurementProfileVersion: 'claude-aggregate-v1',
+        metricDefinitionVersion: 'processed-tokens-v1',
+        qualityRubricId: 'acceptance-v1',
+      },
+      metric: { name: 'processed-tokens', unit: 'tokens', direction: 'lower-is-better', value: 100 },
+      quality: { score: 0.9, passed: 'passed', evidenceCount: 2 },
+      evidence: { coverage: 'complete', confidence: 'high', qualityFlags: [] },
+      observedAtEpochMs: base,
+    },
+    after: {
+      context: {
+        scope: 'task-cohort',
+        taskKind: 'small-change',
+        complexityBand: 'medium',
+        provider: 'claude',
+        modelFamily: 'sonnet',
+        effort: 'high',
+        measurementProfileVersion: 'claude-aggregate-v1',
+        metricDefinitionVersion: 'processed-tokens-v1',
+        qualityRubricId: 'acceptance-v1',
+      },
+      metric: { name: 'processed-tokens', unit: 'tokens', direction: 'lower-is-better', value: afterValue },
+      quality: { score: afterScore, passed: afterPassed, evidenceCount: 2 },
+      evidence: { coverage: 'complete', confidence: 'high', qualityFlags: [] },
+      observedAtEpochMs: base + 1,
+    },
+    recordedAtEpochMs: base + 2,
+  };
+  const result = buildComparableTaskPair(input);
+  assert.equal(result.ok, true);
+  if (!result.ok) throw new Error('fixture pair failed validation');
+  return result.value;
+}
+
+function buildInput(pairs: StoredComparablePair[]): AdviceComparisonResultBuildInput {
+  return {
+    provider: 'claude',
+    recommendationId: 'reduce-token-use',
+    recommendationVersion: 'recommendation-v1',
+    measurementProfileVersion: 'claude-aggregate-v1',
+    cohort: {
+      scope: 'task-cohort',
+      taskKind: 'small-change',
+      complexityBand: 'medium',
+      modelFamily: 'sonnet',
+      effort: 'high',
+      metricDefinitionVersion: 'processed-tokens-v1',
+      qualityRubricId: 'acceptance-v1',
+      metric: { name: 'processed-tokens', unit: 'tokens', direction: 'lower-is-better' },
+    },
+    guardrail: {
+      minComparablePairs: 5,
+      minRelativeImprovement: 0.1,
+      minAfterQualityScore: 0.8,
+      maxMeanQualityRegression: 0.02,
+      allowedQualityFlags: [],
+      qualityRubricId: 'acceptance-v1',
+    },
+    pairs,
+    recordedAtEpochMs: 1_778_000_000_000,
+  };
+}
+
+test('freezes an improved comparison in a strict versioned, replayable envelope', () => {
+  const input = buildInput(Array.from({ length: 5 }, (_, index) => pair(index + 1)));
+  const before = JSON.stringify(input);
+  const built = buildAdviceComparisonResultEnvelope(input);
+  assert.equal(built.ok, true);
+  assert.equal(JSON.stringify(input), before, 'comparison result creation must be pure');
+  if (!built.ok) return;
+  assert.equal(built.value.schemaVersion, 1);
+  assert.equal(built.value.provider, 'claude');
+  assert.equal(built.value.measurementProfileVersion, 'claude-aggregate-v1');
+  assert.equal(built.value.recommendationVersion, 'recommendation-v1');
+  assert.equal(built.value.sample.pairIds.length, 5);
+  assert.equal(built.value.result.status, 'improved');
+  assert.deepEqual(built.value.replayEligibility, {
+    status: 'eligible',
+    reason: 'conclusive-result',
+  });
+  assert.match(built.value.comparisonId, /^comparison-[a-f0-9]{32}$/);
+  assert.deepEqual(parseAdviceComparisonResultEnvelope(built.value), built.value);
+  assert.doesNotMatch(JSON.stringify(built.value), /prompt|session|path|body/i);
+});
+
+test('freezes too-small and incomparable samples as explicit evidence-insufficient results', () => {
+  const tooSmall = buildAdviceComparisonResultEnvelope(
+    buildInput(Array.from({ length: 4 }, (_, index) => pair(index + 1))),
+  );
+  assert.equal(tooSmall.ok, true);
+  if (tooSmall.ok) {
+    assert.deepEqual(tooSmall.value.replayEligibility, {
+      status: 'ineligible',
+      reason: 'evidence-insufficient',
+    });
+    assert.deepEqual(tooSmall.value.result, {
+      status: 'evidence-insufficient',
+      reasonCode: 'minimum-sample-not-met',
+      comparablePairs: 4,
+    });
+  }
+
+  const mixed = Array.from({ length: 5 }, (_, index) => pair(index + 1));
+  mixed[4].context.scope = 'project';
+  const incomparable = buildAdviceComparisonResultEnvelope(buildInput(mixed));
+  assert.equal(incomparable.ok, true);
+  if (incomparable.ok) {
+    assert.equal(incomparable.value.result.status, 'evidence-insufficient');
+    if (incomparable.value.result.status === 'evidence-insufficient') {
+      assert.equal(incomparable.value.result.reasonCode, 'incomparable-sample');
+    }
+  }
+});
+
+test('records a measured quality guardrail failure without claiming improvement', () => {
+  const pairs = Array.from({ length: 5 }, (_, index) => pair(index + 1, 70, 0.75, 'failed'));
+  const result = buildAdviceComparisonResultEnvelope(buildInput(pairs));
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.result.status, 'quality-guardrail-failed');
+  assert.equal(result.value.replayEligibility.status, 'eligible');
+});
+
+test('strict envelope parsing rejects sensitive, nested, unknown, and inconsistent fields', () => {
+  const built = buildAdviceComparisonResultEnvelope(
+    buildInput(Array.from({ length: 5 }, (_, index) => pair(index + 1))),
+  );
+  assert.equal(built.ok, true);
+  if (!built.ok) return;
+  const value = built.value;
+  const hostileValues: unknown[] = [
+    { ...value, prompt: 'PRIVATE_PROMPT' },
+    { ...value, sessionId: 'PRIVATE_SESSION' },
+    { ...value, body: 'PRIVATE_BODY' },
+    { ...value, projectPath: '/Users/private/project' },
+    {
+      ...value,
+      guardrail: { ...value.guardrail, unknown: true },
+    },
+    {
+      ...value,
+      sample: { ...value.sample, qualityRubricId: 'different-rubric' },
+    },
+    {
+      ...value,
+      replayEligibility: { status: 'ineligible', reason: 'evidence-insufficient' },
+    },
+  ];
+  for (const hostile of hostileValues) {
+    assert.equal(parseAdviceComparisonResultEnvelope(hostile), undefined);
+  }
+
+  const cloned: AdviceComparisonResultEnvelope = JSON.parse(JSON.stringify(value));
+  cloned.sample.pairIds.reverse();
+  assert.equal(
+    parseAdviceComparisonResultEnvelope(cloned),
+    undefined,
+    'comparisonId protects the frozen envelope from silent mutation',
+  );
+});
diff --git a/src/test/adviceContract.test.ts b/src/test/adviceContract.test.ts
new file mode 100644
index 00000000..aea79447
--- /dev/null
+++ b/src/test/adviceContract.test.ts
@@ -0,0 +1,96 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import { AdviceContractInput, createAdviceContract } from '../adviceEffectiveness/contract';
+import {
+  evidenceFixture,
+  observationFixture,
+  recommendationFixture,
+  sourceFixture,
+} from './adviceTestFixtures';
+
+function validInput(): AdviceContractInput {
+  return {
+    adviceId: 'advice-run-1',
+    observations: [observationFixture],
+    evidence: [evidenceFixture],
+    recommendations: [recommendationFixture],
+    privacy: {
+      dataMode: 'aggregates-only',
+      promptSampleConsent: 'not-granted',
+      promptSampleCount: 0,
+      feedbackStorage: 'local-only',
+    },
+    provenance: {
+      generatedBy: { kind: 'remote-model', modelFamily: 'sonnet' },
+      generatedAt: '2026-08-24T00:00:00.000Z',
+      locale: 'en',
+      sources: [sourceFixture],
+    },
+  };
+}
+
+test('creates one versioned contract with observation, evidence, action, criterion, source, and privacy', () => {
+  const result = createAdviceContract(validInput());
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.schemaVersion, 1);
+  assert.equal(result.value.recommendations[0].conditionalActions.length, 1);
+  assert.equal(result.value.recommendations[0].successCriteria[0].qualityGuardrail.minimumScore, 0.8);
+  assert.equal(result.value.privacy.dataMode, 'aggregates-only');
+  assert.equal(result.value.provenance.sources[0].kind, 'claude-usage-aggregate');
+});
+
+test('rejects invented evidence references and proxy explanations without limitations', () => {
+  const input = validInput();
+  input.recommendations = [
+    {
+      ...recommendationFixture,
+      evidenceIds: ['evidence-invented'],
+      explanation: {
+        summary: 'Looks causal.',
+        proxyMetricObservationIds: [observationFixture.id],
+        limitations: [],
+      },
+    },
+  ];
+  const result = createAdviceContract(input);
+  assert.equal(result.ok, false);
+  if (result.ok) return;
+  assert.ok(result.issues.some((issue) => issue.includes('unknown evidence')));
+  assert.ok(result.issues.some((issue) => issue.includes('proxy interpretation')));
+});
+
+test('rejects privacy metadata that claims aggregates-only while carrying prompt samples', () => {
+  const input = validInput();
+  input.privacy = {
+    dataMode: 'aggregates-only',
+    promptSampleConsent: 'explicit',
+    promptSampleCount: 1,
+    feedbackStorage: 'local-only',
+  };
+  const result = createAdviceContract(input);
+  assert.equal(result.ok, false);
+  if (result.ok) return;
+  assert.ok(result.issues.some((issue) => issue.includes('zero prompt samples')));
+});
+
+test('accepts explicit personal context without pretending that prompt samples were included', () => {
+  const input = validInput();
+  input.privacy = {
+    dataMode: 'aggregates-with-personalization',
+    promptSampleConsent: 'explicit',
+    promptSampleCount: 0,
+    feedbackStorage: 'local-only',
+  };
+  const result = createAdviceContract(input);
+  assert.equal(result.ok, true);
+});
+
+test('allows an empty recommendation list to represent no supported conclusion', () => {
+  const input = validInput();
+  input.recommendations = [];
+  const result = createAdviceContract(input);
+  assert.equal(result.ok, true);
+  if (result.ok) assert.deepEqual(result.value.recommendations, []);
+});
diff --git a/src/test/adviceEffectivenessI18n.test.ts b/src/test/adviceEffectivenessI18n.test.ts
new file mode 100644
index 00000000..e38a164d
--- /dev/null
+++ b/src/test/adviceEffectivenessI18n.test.ts
@@ -0,0 +1,106 @@
+import * as assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { test } from 'node:test';
+
+import { I18n } from '../i18n';
+import { SupportedLanguage } from '../types';
+
+const LOCALES: SupportedLanguage[] = [
+  'en',
+  'de-DE',
+  'zh-TW',
+  'zh-CN',
+  'ja',
+  'ko',
+  'pt-BR',
+  'id',
+];
+
+function withLanguage<T>(language: SupportedLanguage, run: () => T): T {
+  const previous = I18n.getCurrentLanguage();
+  I18n.setLanguage(language);
+  try {
+    return run();
+  } finally {
+    I18n.setLanguage(previous);
+  }
+}
+
+function placeholders(value: string): string[] {
+  return [...value.matchAll(/\{[a-z][a-zA-Z0-9]*\}/g)].map((match) => match[0]).sort();
+}
+
+test('AI advice effectiveness copy is complete and preserves placeholders in all eight locales', () => {
+  const english = withLanguage('en', () => I18n.t.popup.adviceEffectiveness);
+  const expectedKeys = Object.keys(english).sort();
+  assert.ok(expectedKeys.length >= 40, 'expected the complete advice-effectiveness copy contract');
+
+  for (const language of LOCALES) {
+    withLanguage(language, () => {
+      const copy = I18n.t.popup.adviceEffectiveness;
+      assert.deepEqual(Object.keys(copy).sort(), expectedKeys, `${language}: copy keys differ from English`);
+      for (const key of expectedKeys as (keyof typeof copy)[]) {
+        assert.equal(typeof copy[key], 'string', `${language}: ${key} must be a string`);
+        assert.ok(copy[key].trim().length > 0, `${language}: ${key} must not be empty`);
+        assert.deepEqual(
+          placeholders(copy[key]),
+          placeholders(english[key]),
+          `${language}: ${key} placeholders differ from English`,
+        );
+      }
+    });
+  }
+});
+
+test('privacy, separate consent, local feedback, and inconclusive states have dedicated localized copy', () => {
+  const english = withLanguage('en', () => I18n.t.popup.adviceEffectiveness);
+  assert.match(english.aggregateConsentHelp, /no prompts, paths, session IDs, or individual records/i);
+  assert.match(english.promptConsentHelp, /off by default[\s\S]*separate explicit consent/i);
+  assert.match(english.feedbackLocalOnly, /only on this device[\s\S]*never[\s\S]*remote payload/i);
+  assert.match(english.insufficientEvidence, /not enough evidence[\s\S]*conclusion/i);
+  assert.match(english.noEvidenceAdvice, /no evidence-backed advice/i);
+  assert.match(english.qualityGuardrailPending, /pending[\s\S]*no effectiveness conclusion/i);
+  assert.match(
+    english.frameworkOverheadSignal,
+    /separately estimated framework injection[\s\S]*does not evaluate[\s\S]*quality[\s\S]*user's writing/i,
+  );
+  assert.notEqual(english.aggregateConsentLabel, english.promptConsentLabel);
+
+  const criticalKeys: (keyof typeof english)[] = [
+    'title',
+    'aggregateConsentLabel',
+    'aggregateConsentHelp',
+    'promptConsentLabel',
+    'promptConsentHelp',
+    'feedbackLocalOnly',
+    'insufficientEvidence',
+    'noEvidenceAdvice',
+    'qualityGuardrailPending',
+    'frameworkOverheadSignal',
+    'strictOutputRejected',
+  ];
+  for (const language of LOCALES.filter((locale) => locale !== 'en')) {
+    withLanguage(language, () => {
+      const copy = I18n.t.popup.adviceEffectiveness;
+      for (const key of criticalKeys) {
+        assert.notEqual(copy[key], english[key], `${language}: ${key} still uses English copy`);
+      }
+      const setting = I18n.settingText('advice.effectiveness.enabled');
+      assert.ok(setting.label?.trim(), `${language}: experiment setting needs a label`);
+      assert.ok(setting.help?.trim(), `${language}: experiment setting needs privacy-safe help`);
+    });
+  }
+});
+
+test('the experiment setting is local-state, provider-shared, and off by default', () => {
+  const source = readFileSync(path.resolve(process.cwd(), 'src', 'settings.ts'), 'utf8');
+  const start = source.indexOf("key: 'advice.effectiveness.enabled'");
+  assert.ok(start >= 0, 'missing advice.effectiveness.enabled setting');
+  const block = source.slice(start, source.indexOf('\n  },', start));
+  assert.match(block, /type:\s*'boolean'/);
+  assert.match(block, /default:\s*false/);
+  assert.match(block, /storage:\s*'state'/);
+  assert.match(block, /group:\s*'advice'/);
+  assert.match(block, /providers:\s*\['claude', 'codex'\]/);
+});
diff --git a/src/test/adviceEvidencePreparation.test.ts b/src/test/adviceEvidencePreparation.test.ts
new file mode 100644
index 00000000..e2cd5190
--- /dev/null
+++ b/src/test/adviceEvidencePreparation.test.ts
@@ -0,0 +1,144 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  AdviceEvidencePreparationRequest,
+  planAdviceEvidencePreparation,
+} from '../adviceEffectiveness/evidencePreparation';
+
+function request(
+  overrides: Partial<AdviceEvidencePreparationRequest> = {},
+): AdviceEvidencePreparationRequest {
+  return {
+    featureMode: 'enabled',
+    operation: 'preview',
+    dataMode: 'aggregates-only',
+    aggregateAvailable: true,
+    aggregateConsent: 'explicit',
+    promptPersonalizationConsent: 'not-granted',
+    requestedWindowDays: 30,
+    ...overrides,
+  };
+}
+
+test('disabled advice preparation requests no aggregate or content work', () => {
+  const plan = planAdviceEvidencePreparation(request({
+    featureMode: 'disabled',
+    dataMode: 'aggregates-with-prompt-samples',
+    aggregateAvailable: false,
+    aggregateConsent: 'not-granted',
+    promptPersonalizationConsent: 'not-granted',
+  }));
+
+  assert.deepEqual(plan, {
+    schemaVersion: 1,
+    status: 'disabled',
+    dataMode: 'local-only',
+    reason: 'feature-disabled',
+    requiredHostAction: 'none',
+    allowAutomaticScan: false,
+  });
+});
+
+test('local render and aggregates-only preview never require content analysis', () => {
+  const local = planAdviceEvidencePreparation(request({
+    operation: 'local-render',
+    dataMode: 'local-only',
+    aggregateConsent: 'not-granted',
+  }));
+  assert.equal(local.status, 'ready');
+  assert.equal(local.reason, 'local-evidence-ready');
+  assert.equal(local.requiredHostAction, 'none');
+  assert.equal(local.allowAutomaticScan, false);
+
+  const aggregate = planAdviceEvidencePreparation(request({
+    contentSnapshot: {
+      status: 'stale',
+      windowDays: 7,
+      promptSampleCount: 0,
+    },
+  }));
+  assert.equal(aggregate.status, 'ready');
+  assert.equal(aggregate.reason, 'aggregate-evidence-ready');
+  assert.equal(aggregate.requiredHostAction, 'none');
+  assert.equal(aggregate.allowAutomaticScan, false);
+});
+
+test('personalized preparation cannot request work before both consents', () => {
+  const noAggregateConsent = planAdviceEvidencePreparation(request({
+    dataMode: 'aggregates-with-prompt-samples',
+    aggregateConsent: 'not-granted',
+    promptPersonalizationConsent: 'explicit',
+  }));
+  assert.equal(noAggregateConsent.status, 'blocked');
+  assert.equal(noAggregateConsent.reason, 'aggregate-consent-required');
+  assert.equal(noAggregateConsent.requiredHostAction, 'none');
+
+  const noPromptConsent = planAdviceEvidencePreparation(request({
+    dataMode: 'aggregates-with-prompt-samples',
+    promptPersonalizationConsent: 'not-granted',
+  }));
+  assert.equal(noPromptConsent.status, 'blocked');
+  assert.equal(noPromptConsent.reason, 'prompt-personalization-consent-required');
+  assert.equal(noPromptConsent.requiredHostAction, 'none');
+  assert.equal(noPromptConsent.allowAutomaticScan, false);
+});
+
+test('personalized preparation asks the host for one explicit refresh only when needed', () => {
+  const base = {
+    dataMode: 'aggregates-with-prompt-samples' as const,
+    promptPersonalizationConsent: 'explicit' as const,
+  };
+  for (const [contentSnapshot, reason] of [
+    [undefined, 'content-snapshot-missing'],
+    [{ status: 'stale', windowDays: 30, promptSampleCount: 3 }, 'content-snapshot-stale'],
+    [{ status: 'ready', windowDays: 7, promptSampleCount: 3 }, 'content-window-mismatch'],
+  ] as const) {
+    const plan = planAdviceEvidencePreparation(request({ ...base, contentSnapshot }));
+    assert.equal(plan.status, 'explicit-refresh-required');
+    assert.equal(plan.reason, reason);
+    assert.equal(plan.requiredHostAction, 'refresh-content-analysis');
+    assert.equal(plan.allowAutomaticScan, false);
+  }
+});
+
+test('personalized preparation is ready only for a matching materialized snapshot', () => {
+  const ready = planAdviceEvidencePreparation(request({
+    operation: 'send',
+    dataMode: 'aggregates-with-prompt-samples',
+    promptPersonalizationConsent: 'explicit',
+    contentSnapshot: {
+      status: 'ready',
+      windowDays: 30,
+      promptSampleCount: 4,
+    },
+  }));
+  assert.equal(ready.status, 'ready');
+  assert.equal(ready.reason, 'personalized-evidence-ready');
+  assert.equal(ready.requiredHostAction, 'none');
+  assert.equal(ready.allowAutomaticScan, false);
+
+  const empty = planAdviceEvidencePreparation(request({
+    dataMode: 'aggregates-with-prompt-samples',
+    promptPersonalizationConsent: 'explicit',
+    contentSnapshot: {
+      status: 'ready',
+      windowDays: 30,
+      promptSampleCount: 0,
+    },
+  }));
+  assert.equal(empty.status, 'blocked');
+  assert.equal(empty.reason, 'prompt-samples-unavailable');
+  assert.equal(empty.requiredHostAction, 'none');
+});
+
+test('invalid preparation combinations fail closed without work', () => {
+  const invalid = planAdviceEvidencePreparation(request({
+    operation: 'local-render',
+    dataMode: 'aggregates-only',
+  }));
+  assert.equal(invalid.status, 'blocked');
+  assert.equal(invalid.reason, 'invalid-request');
+  assert.equal(invalid.requiredHostAction, 'none');
+  assert.equal(invalid.allowAutomaticScan, false);
+});
diff --git a/src/test/adviceFeedback.test.ts b/src/test/adviceFeedback.test.ts
new file mode 100644
index 00000000..910b49f1
--- /dev/null
+++ b/src/test/adviceFeedback.test.ts
@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  ADVICE_FEEDBACK_STORAGE_KEY,
+  AdviceFeedbackStorage,
+  loadAdviceFeedback,
+  recordAdviceFeedback,
+  summarizeAdviceFeedback,
+} from '../adviceEffectiveness/feedback';
+
+class MemoryStorage implements AdviceFeedbackStorage {
+  value: unknown;
+  updates = 0;
+
+  get<T>(_key: string): T | undefined {
+    return this.value as T | undefined;
+  }
+
+  async update(key: string, value: unknown): Promise<void> {
+    assert.equal(key, ADVICE_FEEDBACK_STORAGE_KEY);
+    this.value = value;
+    this.updates += 1;
+  }
+}
+
+function event(eventId: string, kind: 'helpful' | 'not-helpful' | 'applied') {
+  return {
+    eventId,
+    adviceId: 'advice-run-1',
+    recommendationId: 'recommendation-1',
+    kind,
+    recordedAt: `2026-08-24T00:00:0${eventId.slice(-1)}.000Z`,
+  };
+}
+
+test('records rating and applied state locally while keeping them semantically independent', async () => {
+  const storage = new MemoryStorage();
+  await recordAdviceFeedback(storage, event('event-1', 'helpful'));
+  await recordAdviceFeedback(storage, event('event-2', 'applied'));
+  const result = await recordAdviceFeedback(storage, event('event-3', 'not-helpful'));
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(storage.updates, 3);
+  assert.equal(result.events.length, 2, 'the new rating replaces the previous rating, not applied');
+  assert.deepEqual(
+    summarizeAdviceFeedback(result.events, 'advice-run-1', 'recommendation-1'),
+    { rating: 'not-helpful', applied: true }
+  );
+  const stored = JSON.stringify(storage.value);
+  assert.doesNotMatch(stored, /prompt|payload|explanation|endpoint|PRIVATE/);
+  assert.match(stored, /"localOnly":true/);
+});
+
+test('invalid events are rejected without writing', async () => {
+  const storage = new MemoryStorage();
+  const result = await recordAdviceFeedback(storage, {
+    ...event('event-1', 'helpful'),
+    recordedAt: 'not-a-date',
+  });
+  assert.deepEqual(result, { ok: false, reason: 'invalid-event' });
+  assert.equal(storage.updates, 0);
+});
+
+test('corrupt or unknown-version local data fails closed and is not overwritten', async () => {
+  const storage = new MemoryStorage();
+  storage.value = { schemaVersion: 99, events: [{ prompt: 'private' }] };
+  assert.deepEqual(loadAdviceFeedback(storage), { ok: false, reason: 'invalid-local-data' });
+  const result = await recordAdviceFeedback(storage, event('event-1', 'helpful'));
+  assert.deepEqual(result, { ok: false, reason: 'invalid-local-data' });
+  assert.equal(storage.updates, 0);
+});
diff --git a/src/test/adviceIntegration.test.ts b/src/test/adviceIntegration.test.ts
new file mode 100644
index 00000000..e1e48758
--- /dev/null
+++ b/src/test/adviceIntegration.test.ts
@@ -0,0 +1,152 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+
+import { createAdviceContract } from '../adviceEffectiveness/contract';
+import {
+  AdviceEffectivenessProviderState,
+  prepareAdviceSnapshot,
+  selectAdvicePromptSamples,
+} from '../adviceEffectiveness/integration';
+import {
+  buildAdviceAggregateSnapshot,
+  sendPreparedAdvicePayload,
+} from '../adviceEffectiveness/payload';
+import {
+  evidenceFixture,
+  observationFixture,
+  sourceFixture,
+  usageFixture,
+} from './adviceTestFixtures';
+
+function state(provider: 'claude' | 'codex' = 'claude'): AdviceEffectivenessProviderState {
+  const built = createAdviceContract({
+    adviceId: `advice-${provider}-integration`,
+    observations: [observationFixture],
+    evidence: [evidenceFixture],
+    recommendations: [],
+    privacy: {
+      dataMode: 'local-only',
+      promptSampleConsent: 'not-applicable',
+      promptSampleCount: 0,
+      feedbackStorage: 'local-only',
+    },
+    provenance: {
+      generatedBy: { kind: 'local-rules' },
+      generatedAt: '2026-08-24T08:00:00.000Z',
+      locale: 'zh-CN',
+      sources: [sourceFixture],
+    },
+  });
+  if (!built.ok) throw new Error(built.issues.join(', '));
+  assert.equal(built.ok, true);
+  return {
+    provider,
+    contract: built.value,
+    remotePreviewEligible: provider === 'claude',
+    aggregate:
+      provider === 'claude' ? buildAdviceAggregateSnapshot(usageFixture, 'overall', 30) : undefined,
+    userContext: '私有项目约束',
+    promptSamples: [{ text: '请核对这个非 ASCII 样本' }],
+  };
+}
+
+test('sealed snapshot requires separate aggregate consent and defaults to no prompts', () => {
+  const denied = prepareAdviceSnapshot(state(), {
+    aggregate: 'not-granted',
+    promptSamples: 'explicit',
+  });
+  assert.deepEqual(denied, { ok: false, reason: 'aggregate-consent-required' });
+
+  const result = prepareAdviceSnapshot(state(), {
+    aggregate: 'explicit',
+    promptSamples: 'not-granted',
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.preview.body, result.value.prepared.serializedBody);
+  assert.equal(result.value.preview.dataMode, 'aggregates-only');
+  assert.equal(result.value.preview.body.includes('promptSamples'), false);
+  assert.equal(result.value.preview.body.includes('私有项目约束'), false);
+});
+
+test('prompt text enters only the explicitly opted-in sealed body and UTF-8 bytes are exact', () => {
+  const result = prepareAdviceSnapshot(state(), {
+    aggregate: 'explicit',
+    promptSamples: 'explicit',
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.preview.body, result.value.prepared.serializedBody);
+  assert.equal(result.value.preview.dataMode, 'aggregates-with-prompt-samples');
+  assert.equal(result.value.preview.promptSampleCount, 1);
+  assert.equal(result.value.preview.body.includes('私有项目约束'), true);
+  assert.equal(
+    result.value.preview.utf8Bytes,
+    Buffer.byteLength(result.value.prepared.serializedBody, 'utf8'),
+  );
+  assert.ok(result.value.preview.utf8Bytes > result.value.preview.body.length);
+});
+
+test('configured context remains usable when no prompt sample is inside the window', () => {
+  const contextOnly = state();
+  contextOnly.promptSamples = [];
+  const result = prepareAdviceSnapshot(contextOnly, {
+    aggregate: 'explicit',
+    promptSamples: 'explicit',
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.preview.dataMode, 'aggregates-with-personalization');
+  assert.equal(result.value.preview.promptSampleCount, 0);
+  assert.equal(result.value.preview.body.includes('私有项目约束'), true);
+});
+
+test('sealed snapshot preview, digest, and future sender share one canonical UTF-8 byte sequence', async () => {
+  const result = prepareAdviceSnapshot(state(), {
+    aggregate: 'explicit',
+    promptSamples: 'explicit',
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+
+  const { prepared, preview } = result.value;
+  const expectedDigest = createHash('sha256')
+    .update(prepared.canonicalBytes)
+    .digest('hex');
+  assert.equal(preview.body, Buffer.from(prepared.canonicalBytes).toString('utf8'));
+  assert.equal(preview.utf8Bytes, prepared.canonicalBytes.byteLength);
+  assert.equal(preview.sha256, expectedDigest);
+  assert.equal(prepared.sha256, expectedDigest);
+
+  let sentBytes: Uint8Array | undefined;
+  const response = await sendPreparedAdvicePayload(
+    prepared,
+    async (canonicalBytes, contentType, sha256) => {
+      sentBytes = canonicalBytes;
+      assert.equal(contentType, 'application/json');
+      assert.equal(sha256, expectedDigest);
+      return 'ok';
+    },
+  );
+  assert.equal(response, 'ok');
+  assert.strictEqual(sentBytes, prepared.canonicalBytes);
+});
+
+test('Codex evidence stays local until a provider-discriminated remote aggregate exists', () => {
+  const result = prepareAdviceSnapshot(state('codex'), {
+    aggregate: 'explicit',
+    promptSamples: 'not-granted',
+  });
+  assert.deepEqual(result, { ok: false, reason: 'provider-not-eligible' });
+});
+
+test('prompt personalisation excludes old, future, and untrusted-age samples', () => {
+  const now = 1_778_000_000_000;
+  assert.deepEqual(selectAdvicePromptSamples([
+    { text: 'inside', observedAtEpochMs: now - 29 * 86_400_000 },
+    { text: 'too old', observedAtEpochMs: now - 31 * 86_400_000 },
+    { text: 'future', observedAtEpochMs: now + 1 },
+    { text: 'missing age', observedAtEpochMs: 0 },
+  ], now, 30), [{ text: 'inside' }]);
+});
diff --git a/src/test/adviceLegacyBridge.test.ts b/src/test/adviceLegacyBridge.test.ts
new file mode 100644
index 00000000..097a0383
--- /dev/null
+++ b/src/test/adviceLegacyBridge.test.ts
@@ -0,0 +1,133 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  LegacyByokCallOptions,
+  LegacyByokModelCall,
+  requestStructuredAdviceViaLegacyByok,
+} from '../adviceEffectiveness/legacyBridge';
+import { prepareAdvicePayload } from '../adviceEffectiveness/payload';
+import { payloadInputFixture, structuredOutputFixture } from './adviceTestFixtures';
+
+const byok = {
+  apiFormat: 'openai' as const,
+  apiKey: 'PRIVATE_API_KEY',
+  apiUrl: 'https://example.invalid/chat/completions',
+  model: 'private-model',
+};
+
+test('legacy BYOK bridge uses the sealed serialization as the exact user turn and strict-parses the result', async () => {
+  const prepared = prepareAdvicePayload(payloadInputFixture());
+  let capturedUser = '';
+  let capturedOptions: LegacyByokCallOptions | undefined;
+  const invoke: LegacyByokModelCall = async (_system, userContent, options) => {
+    capturedUser = userContent;
+    capturedOptions = options;
+    return JSON.stringify(structuredOutputFixture());
+  };
+
+  const result = await requestStructuredAdviceViaLegacyByok(
+    prepared,
+    {
+      observationIds: ['observation-cache-share'],
+      evidenceIds: ['evidence-cache-share'],
+    },
+    byok,
+    invoke,
+  );
+
+  assert.equal(result.ok, true);
+  assert.equal(capturedUser, prepared.serializedBody);
+  assert.equal(capturedOptions?.summary, '');
+  assert.equal(
+    capturedOptions === undefined
+      ? false
+      : Object.prototype.hasOwnProperty.call(capturedOptions, 'userContext'),
+    false,
+  );
+  assert.equal(capturedOptions?.backend, 'api');
+});
+
+test('legacy BYOK bridge rejects a Prepared object whose preview text no longer matches its bytes', async () => {
+  const prepared = prepareAdvicePayload(payloadInputFixture());
+  prepared.serializedBody = '{"tamperedPreview":true}';
+  let invocations = 0;
+  const result = await requestStructuredAdviceViaLegacyByok(
+    prepared,
+    { observationIds: ['observation-cache-share'], evidenceIds: ['evidence-cache-share'] },
+    byok,
+    async () => {
+      invocations += 1;
+      return JSON.stringify(structuredOutputFixture());
+    },
+  );
+  assert.deepEqual(result, {
+    ok: false,
+    code: 'transport-error',
+    issues: ['legacy BYOK transport failed'],
+  });
+  assert.equal(invocations, 0);
+});
+
+test('legacy BYOK bridge rejects fenced or malformed model output without a prose fallback', async () => {
+  const prepared = prepareAdvicePayload(payloadInputFixture());
+  const invoke: LegacyByokModelCall = async () =>
+    `\`\`\`json\n${JSON.stringify(structuredOutputFixture())}\n\`\`\``;
+  const result = await requestStructuredAdviceViaLegacyByok(
+    prepared,
+    { observationIds: ['observation-cache-share'], evidenceIds: ['evidence-cache-share'] },
+    byok,
+    invoke,
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) assert.equal(result.code, 'invalid-json');
+});
+
+test('legacy BYOK bridge fails closed on transport errors and does not echo secrets', async () => {
+  const prepared = prepareAdvicePayload(payloadInputFixture());
+  const invoke: LegacyByokModelCall = async () => {
+    throw new Error('PRIVATE_API_KEY endpoint failure');
+  };
+  const result = await requestStructuredAdviceViaLegacyByok(
+    prepared,
+    { observationIds: ['observation-cache-share'], evidenceIds: ['evidence-cache-share'] },
+    byok,
+    invoke,
+  );
+  assert.deepEqual(result, {
+    ok: false,
+    code: 'transport-error',
+    issues: ['legacy BYOK transport failed'],
+  });
+  assert.doesNotMatch(JSON.stringify(result), /PRIVATE_API_KEY/);
+});
+
+test('legacy BYOK bridge rejects subscription or hostile transport fields before invocation', async () => {
+  const prepared = prepareAdvicePayload(payloadInputFixture());
+  let invocations = 0;
+  const invoke: LegacyByokModelCall = async () => {
+    invocations += 1;
+    return JSON.stringify(structuredOutputFixture());
+  };
+  for (const hostile of [
+    { ...byok, backend: 'subscription' },
+    { ...byok, getSubscriptionToken: async () => 'PRIVATE_TOKEN' },
+    { ...byok, subscriptionModel: 'private-subscription-model' },
+    { ...byok, apiKey: '' },
+    { ...byok, apiUrl: '' },
+    { ...byok, model: '' },
+  ]) {
+    const result = await requestStructuredAdviceViaLegacyByok(
+      prepared,
+      { observationIds: ['observation-cache-share'], evidenceIds: ['evidence-cache-share'] },
+      hostile as typeof byok,
+      invoke,
+    );
+    assert.deepEqual(result, {
+      ok: false,
+      code: 'invalid-config',
+      issues: ['legacy BYOK configuration was rejected'],
+    });
+  }
+  assert.equal(invocations, 0);
+});
diff --git a/src/test/adviceLegacyPersonalization.test.ts b/src/test/adviceLegacyPersonalization.test.ts
new file mode 100644
index 00000000..016c042f
--- /dev/null
+++ b/src/test/adviceLegacyPersonalization.test.ts
@@ -0,0 +1,134 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  buildLegacyPersonalizationDraft,
+  LegacyPersonalizationDraft,
+  projectLegacyPersonalization,
+} from '../adviceEffectiveness/legacyPersonalization';
+
+const NOW = Date.parse('2026-08-27T12:00:00.000Z');
+
+test('legacy user context and prompt samples remain host-only without separate consent', () => {
+  const draft = buildLegacyPersonalizationDraft({
+    promptWindowDays: 30,
+    userContext: '  PRIVATE_CONTEXT  ',
+    promptSamples: [{
+      text: 'PRIVATE_PROMPT',
+      observedAtEpochMs: NOW - 2 * 86_400_000,
+      cwd: '/private/workspace',
+      sessionId: 'private-session',
+    }],
+    nowEpochMs: NOW,
+  });
+  assert.equal(draft.ok, true);
+  if (!draft.ok) return;
+
+  assert.equal(projectLegacyPersonalization(draft.value, 'not-granted'), undefined);
+  assert.equal(draft.value.migration.requiresExplicitPromptPersonalizationConsent, true);
+  assert.equal(draft.value.migration.userContextChars, 'PRIVATE_CONTEXT'.length);
+  assert.equal(draft.value.migration.promptSampleCount, 1);
+  assert.deepEqual(draft.value.migration.sampleAge, {
+    withinWindow: 1,
+    olderThanWindow: 0,
+    unknown: 0,
+  });
+  assert.doesNotMatch(JSON.stringify(draft.value.migration), /PRIVATE_|workspace|session/);
+});
+
+test('explicit projection rebuilds an exact allowlisted personalization object', () => {
+  const draft = buildLegacyPersonalizationDraft({
+    promptWindowDays: 30,
+    userContext: '  Project uses a strict review rubric.  ',
+    promptSamples: [
+      { text: '  Please review this change.  ', observedAtEpochMs: NOW - 5 * 86_400_000 },
+      { text: 'Older sample', observedAtEpochMs: NOW - 40 * 86_400_000 },
+      { text: 'Unknown age' },
+    ],
+    nowEpochMs: NOW,
+  });
+  assert.equal(draft.ok, true);
+  if (!draft.ok) return;
+
+  const projected = projectLegacyPersonalization(draft.value, 'explicit');
+  assert.deepEqual(projected, {
+    schemaVersion: 1,
+    consent: 'explicit',
+    windowDays: 30,
+    userContext: 'Project uses a strict review rubric.',
+    promptSamples: [
+      { text: 'Please review this change.', age: 'within-window' },
+      { text: 'Older sample', age: 'older-than-window' },
+      { text: 'Unknown age', age: 'unknown' },
+    ],
+  });
+});
+
+test('legacy personalization uses payload bounds and exposes truncation in migration metadata', () => {
+  const draft = buildLegacyPersonalizationDraft({
+    promptWindowDays: 30,
+    userContext: `context-${'x'.repeat(2_000)}`,
+    promptSamples: Array.from({ length: 25 }, (_value, index) => ({
+      text: `sample-${index}-${'y'.repeat(2_000)}`,
+      observedAtEpochMs: NOW,
+    })),
+    nowEpochMs: NOW,
+  });
+  assert.equal(draft.ok, true);
+  if (!draft.ok) return;
+
+  const projected = projectLegacyPersonalization(draft.value, 'explicit');
+  assert.ok(projected);
+  assert.equal(projected.userContext?.length, 1_000);
+  assert.equal(projected.promptSamples.length, 12);
+  assert.equal(
+    projected.promptSamples.reduce((sum, sample) => sum + sample.text.length, 0),
+    12_000,
+  );
+  assert.equal(draft.value.migration.userContextTruncated, true);
+  assert.equal(draft.value.migration.promptSamplesTruncated, true);
+});
+
+test('legacy personalization rejects invalid windows and timestamps without retaining content', () => {
+  for (const input of [
+    {
+      promptWindowDays: 0,
+      userContext: 'PRIVATE_CONTEXT',
+      promptSamples: [],
+      nowEpochMs: NOW,
+    },
+    {
+      promptWindowDays: 30,
+      userContext: '',
+      promptSamples: [{ text: 'PRIVATE_PROMPT', observedAtEpochMs: Number.NaN }],
+      nowEpochMs: NOW,
+    },
+  ]) {
+    const result = buildLegacyPersonalizationDraft(input);
+    assert.deepEqual(result, { ok: false, reason: 'invalid-legacy-personalization' });
+    assert.doesNotMatch(JSON.stringify(result), /PRIVATE_/);
+  }
+});
+
+test('legacy personalization projection revalidates a hostile in-memory draft', () => {
+  const hostile = {
+    schemaVersion: 1,
+    windowDays: 30,
+    userContext: 'PRIVATE_CONTEXT',
+    promptSamples: [{
+      text: 'PRIVATE_PROMPT',
+      age: 'within-window',
+      cwd: '/private/workspace',
+    }],
+    migration: {
+      requiresExplicitPromptPersonalizationConsent: true,
+      userContextChars: 15,
+      userContextTruncated: false,
+      promptSampleCount: 1,
+      promptSamplesTruncated: false,
+      sampleAge: { withinWindow: 1, olderThanWindow: 0, unknown: 0 },
+    },
+  } as unknown as LegacyPersonalizationDraft;
+
+  assert.equal(projectLegacyPersonalization(hostile, 'explicit'), undefined);
+});
diff --git a/src/test/adviceModelExperiment.test.ts b/src/test/adviceModelExperiment.test.ts
new file mode 100644
index 00000000..4459b2fc
--- /dev/null
+++ b/src/test/adviceModelExperiment.test.ts
@@ -0,0 +1,117 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import { ComparableTaskPair } from '../adviceEffectiveness/comparison';
+import {
+  buildReversibleModelExperiment,
+  compareReversibleModelExperiment,
+} from '../adviceEffectiveness/modelExperiment';
+
+const input = {
+  recommendationId: 'recommendation-model-experiment',
+  baselineModelFamily: 'opus' as const,
+  candidateModelFamily: 'sonnet' as const,
+  evidenceId: 'evidence-model-proxy',
+  metricObservationId: 'observation-task-primary-metric',
+};
+
+test('model rightsizing seam allows only a reversible adjacent-tier experiment with guardrails', () => {
+  const recommendation = buildReversibleModelExperiment(input);
+  assert.ok(recommendation);
+  assert.equal(recommendation!.conditionalActions.length, 1);
+  assert.equal(recommendation!.successCriteria[0].minimumComparableTasks, 5);
+  assert.deepEqual(recommendation!.successCriteria[0].qualityGuardrail, {
+    rubricId: 'task-quality-rubric-v1',
+    minimumScore: 0.8,
+    maximumRegression: 0.02,
+  });
+  const serialized = JSON.stringify(recommendation);
+  assert.doesNotMatch(serialized, /should switch|cheaper model|smaller model|guaranteed savings/i);
+});
+
+test('model rightsizing seam rejects multi-tier and upward switches', () => {
+  assert.equal(
+    buildReversibleModelExperiment({ ...input, candidateModelFamily: 'haiku' }),
+    undefined,
+  );
+  assert.equal(
+    buildReversibleModelExperiment({
+      ...input,
+      baselineModelFamily: 'sonnet',
+      candidateModelFamily: 'opus',
+    }),
+    undefined,
+  );
+});
+
+function pair(index: number, afterQuality = 0.91): ComparableTaskPair {
+  const context = {
+    taskKind: 'small-change',
+    complexityBand: 'low' as const,
+    provider: 'claude',
+    effort: 'high',
+    metricDefinitionVersion: 'task-tokens-v1',
+    qualityRubricId: 'task-quality-rubric-v1',
+  };
+  const outcome = (
+    modelFamily: 'opus' | 'sonnet',
+    value: number,
+    quality: number,
+  ) => ({
+    context: { ...context, modelFamily },
+    primaryMetric: {
+      name: 'task-primary-metric',
+      unit: 'tokens',
+      direction: 'lower-is-better' as const,
+      value,
+    },
+    quality: { score: quality, passed: quality >= 0.8, evidenceCount: 2 },
+    evidence: { coverage: 'complete' as const, confidence: 'high' as const, qualityFlags: [] },
+  });
+  return {
+    pairId: `pair-model-${index}`,
+    before: outcome('opus', 100, 0.9),
+    after: outcome('sonnet', 80, afterQuality),
+  };
+}
+
+test('adjacent model experiment compares five matched pairs only after local feedback', () => {
+  const pairs = Array.from({ length: 5 }, (_, index) => pair(index));
+  const missingFeedback = compareReversibleModelExperiment({
+    baselineModelFamily: 'opus',
+    candidateModelFamily: 'sonnet',
+    applied: true,
+    localRating: 'unrated',
+    pairs,
+  });
+  assert.equal(missingFeedback.status, 'insufficient-evidence');
+
+  const result = compareReversibleModelExperiment({
+    baselineModelFamily: 'opus',
+    candidateModelFamily: 'sonnet',
+    applied: true,
+    localRating: 'helpful',
+    pairs,
+  });
+  assert.equal(result.status, 'improved');
+});
+
+test('adjacent model experiment preserves the quality guardrail and minimum sample', () => {
+  const tooFew = compareReversibleModelExperiment({
+    baselineModelFamily: 'opus',
+    candidateModelFamily: 'sonnet',
+    applied: true,
+    localRating: 'not-helpful',
+    pairs: Array.from({ length: 4 }, (_, index) => pair(index)),
+  });
+  assert.equal(tooFew.status, 'insufficient-evidence');
+
+  const qualityFailure = compareReversibleModelExperiment({
+    baselineModelFamily: 'opus',
+    candidateModelFamily: 'sonnet',
+    applied: true,
+    localRating: 'helpful',
+    pairs: Array.from({ length: 5 }, (_, index) => pair(index, 0.7)),
+  });
+  assert.equal(qualityFailure.status, 'quality-guardrail-failed');
+});
diff --git a/src/test/adviceOutput.test.ts b/src/test/adviceOutput.test.ts
new file mode 100644
index 00000000..5492fac5
--- /dev/null
+++ b/src/test/adviceOutput.test.ts
@@ -0,0 +1,74 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import { parseStructuredAdviceOutput } from '../adviceEffectiveness/structuredOutput';
+import {
+  evidenceFixture,
+  observationFixture,
+  recommendationFixture,
+  structuredOutputFixture,
+} from './adviceTestFixtures';
+
+const references = {
+  observationIds: [observationFixture.id],
+  evidenceIds: [evidenceFixture.id],
+};
+
+test('parses one exact JSON response whose recommendations reference host evidence', () => {
+  const result = parseStructuredAdviceOutput(JSON.stringify(structuredOutputFixture()), references);
+  assert.equal(result.ok, true);
+  if (result.ok) assert.deepEqual(result.value.recommendations, [recommendationFixture]);
+});
+
+test('accepts an empty recommendation list as an explicit no-conclusion result', () => {
+  const result = parseStructuredAdviceOutput(JSON.stringify({ schemaVersion: 1, recommendations: [] }), references);
+  assert.deepEqual(result, { ok: true, value: { schemaVersion: 1, recommendations: [] } });
+});
+
+test('fails closed for prose, markdown fences, trailing text, and extra host-owned fields', () => {
+  const valid = JSON.stringify(structuredOutputFixture());
+  for (const raw of [
+    'This looks useful.',
+    `\`\`\`json\n${valid}\n\`\`\``,
+    `${valid}\nextra prose`,
+    JSON.stringify({ ...structuredOutputFixture() as object, privacy: { dataMode: 'local-only' } }),
+  ]) {
+    const result = parseStructuredAdviceOutput(raw, references);
+    assert.equal(result.ok, false);
+  }
+});
+
+test('rejects unknown evidence references and never echoes raw model output in the error', () => {
+  const secret = 'PRIVATE_MODEL_OUTPUT_SENTINEL';
+  const output = structuredOutputFixture() as { schemaVersion: number; recommendations: typeof recommendationFixture[] };
+  output.recommendations = [
+    {
+      ...recommendationFixture,
+      evidenceIds: ['evidence-invented'],
+      title: secret,
+    },
+  ];
+  const result = parseStructuredAdviceOutput(JSON.stringify(output), references);
+  assert.equal(result.ok, false);
+  if (result.ok) return;
+  assert.equal(result.code, 'unknown-reference');
+  assert.equal(JSON.stringify(result).includes(secret), false);
+});
+
+test('rejects the entire batch when one recommendation is malformed or duplicated', () => {
+  const malformed = {
+    ...recommendationFixture,
+    successCriteria: [{ ...recommendationFixture.successCriteria[0], qualityGuardrail: undefined }],
+  };
+  const result = parseStructuredAdviceOutput(
+    JSON.stringify({ schemaVersion: 1, recommendations: [recommendationFixture, malformed] }),
+    references
+  );
+  assert.equal(result.ok, false);
+
+  const duplicate = parseStructuredAdviceOutput(
+    JSON.stringify({ schemaVersion: 1, recommendations: [recommendationFixture, recommendationFixture] }),
+    references
+  );
+  assert.equal(duplicate.ok, false);
+});
diff --git a/src/test/advicePayload.test.ts b/src/test/advicePayload.test.ts
new file mode 100644
index 00000000..5ecc816c
--- /dev/null
+++ b/src/test/advicePayload.test.ts
@@ -0,0 +1,143 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  buildAdviceAggregateSnapshot,
+  prepareAdvicePayload,
+  previewAdvicePayload,
+  sendPreparedAdvicePayload,
+} from '../adviceEffectiveness/payload';
+import { payloadInputFixture, usageFixture } from './adviceTestFixtures';
+
+test('builds a coarse aggregate without retaining full or custom model names', () => {
+  const aggregate = buildAdviceAggregateSnapshot(usageFixture, 'overall', 30);
+  assert.deepEqual(aggregate.modelFamilies.map((row) => row.family), ['other', 'sonnet']);
+  assert.doesNotMatch(JSON.stringify(aggregate), /private-router|20250514/);
+});
+
+test('defaults to aggregates-only and omits the promptSamples field entirely', () => {
+  const prepared = prepareAdvicePayload(payloadInputFixture());
+  const parsed = JSON.parse(prepared.serializedBody) as Record<string, unknown>;
+  assert.equal(prepared.dataMode, 'aggregates-only');
+  assert.equal(prepared.promptSampleCount, 0);
+  assert.equal(Object.prototype.hasOwnProperty.call(parsed, 'promptSamples'), false);
+});
+
+test('preview and sender consume the exact same canonical serialization', async () => {
+  const input = payloadInputFixture();
+  const before = JSON.stringify(input);
+  const first = prepareAdvicePayload(input);
+  const second = prepareAdvicePayload(input);
+  const preview = previewAdvicePayload(first);
+  let captured: Uint8Array | undefined;
+  const result = await sendPreparedAdvicePayload(first, async (canonicalBytes, contentType, sha256) => {
+    captured = canonicalBytes;
+    assert.equal(contentType, 'application/json');
+    assert.equal(sha256, first.sha256);
+    return 'sent';
+  });
+  assert.equal(result, 'sent');
+  assert.equal(preview.body, first.serializedBody);
+  assert.strictEqual(captured, first.canonicalBytes);
+  assert.equal(Buffer.from(first.canonicalBytes).toString('utf8'), preview.body);
+  assert.equal(preview.sha256, first.sha256);
+  assert.equal(first.serializedBody, second.serializedBody);
+  assert.deepEqual(first.canonicalBytes, second.canonicalBytes);
+  assert.equal(first.sha256, second.sha256);
+  assert.equal(JSON.stringify(input), before, 'payload preparation must not mutate input');
+});
+
+test('preview and sender reject any mutation of the sealed body, bytes, or digest', async () => {
+  const bodyMutation = prepareAdvicePayload(payloadInputFixture());
+  bodyMutation.serializedBody = '{"mutated":true}';
+  assert.throws(() => previewAdvicePayload(bodyMutation), /integrity check failed/);
+  await assert.rejects(
+    () => sendPreparedAdvicePayload(bodyMutation, async () => 'sent'),
+    /integrity check failed/,
+  );
+
+  const byteMutation = prepareAdvicePayload(payloadInputFixture());
+  byteMutation.canonicalBytes[0] ^= 1;
+  assert.throws(() => previewAdvicePayload(byteMutation), /integrity check failed/);
+
+  const digestMutation = prepareAdvicePayload(payloadInputFixture());
+  digestMutation.sha256 = '0'.repeat(64);
+  assert.throws(() => previewAdvicePayload(digestMutation), /integrity check failed/);
+});
+
+test('prompt text appears only behind the separate explicit opt-in and is bounded', () => {
+  const input = payloadInputFixture();
+  input.promptSamples = {
+    consent: 'explicit',
+    userContext: `  private project context ${'y'.repeat(2_000)}  `,
+    samples: [{ text: `private prompt ${'x'.repeat(2_000)}` }],
+  };
+  const prepared = prepareAdvicePayload(input);
+  const parsed = JSON.parse(prepared.serializedBody) as {
+    promptSamples: { text: string }[];
+    privacy: { promptSampleConsent: string; userContextIncluded: boolean };
+    userContext: string;
+  };
+  assert.equal(prepared.dataMode, 'aggregates-with-prompt-samples');
+  assert.equal(parsed.privacy.promptSampleConsent, 'explicit');
+  assert.equal(parsed.privacy.userContextIncluded, true);
+  assert.equal(parsed.userContext.length, 1_000);
+  assert.equal(parsed.userContext.startsWith('private project context'), true);
+  assert.equal(parsed.promptSamples.length, 1);
+  assert.equal(parsed.promptSamples[0].text.length, 1_000);
+});
+
+test('configured user context is absent without the separate prompt-personalisation consent', () => {
+  const input = payloadInputFixture();
+  (input as typeof input & { userContext?: string }).userContext = 'must not be accepted here';
+  const prepared = prepareAdvicePayload(input);
+  const parsed = JSON.parse(prepared.serializedBody) as Record<string, unknown>;
+  assert.equal(Object.prototype.hasOwnProperty.call(parsed, 'userContext'), false);
+  assert.equal(
+    (parsed.privacy as { userContextIncluded: boolean }).userContextIncluded,
+    false,
+  );
+});
+
+test('configured context can be the only explicitly consented personalisation field', () => {
+  const input = payloadInputFixture();
+  input.promptSamples = {
+    consent: 'explicit',
+    userContext: 'private project constraint',
+    samples: [],
+  };
+  const prepared = prepareAdvicePayload(input);
+  const parsed = JSON.parse(prepared.serializedBody) as {
+    userContext: string;
+    privacy: { promptSampleConsent: string; promptSampleCount: number };
+  };
+  assert.equal(prepared.dataMode, 'aggregates-with-personalization');
+  assert.equal(prepared.promptSampleCount, 0);
+  assert.equal(parsed.userContext, 'private project constraint');
+  assert.equal(parsed.privacy.promptSampleConsent, 'explicit');
+  assert.equal(parsed.privacy.promptSampleCount, 0);
+});
+
+test('invalid aggregates and empty explicit prompt consent fail before a payload exists', () => {
+  const invalid = payloadInputFixture();
+  invalid.aggregate.totals.inputTokens = Number.NaN;
+  assert.throws(() => prepareAdvicePayload(invalid), /finite non-negative/);
+
+  const empty = payloadInputFixture();
+  empty.promptSamples = { consent: 'explicit', samples: [{ text: '   ' }] };
+  assert.throws(() => prepareAdvicePayload(empty), /sample or user context/);
+});
+
+test('remote observations require reviewed metrics and sufficiently clean source evidence', () => {
+  const unknownMetric = payloadInputFixture();
+  unknownMetric.observations = [{ ...unknownMetric.observations[0], metric: 'private-user-name' }];
+  assert.throws(() => prepareAdvicePayload(unknownMetric), /invalid observation metric/);
+
+  const degraded = payloadInputFixture();
+  degraded.sources = [{ ...degraded.sources[0], qualityFlags: ['partial-coverage'] }];
+  assert.throws(() => prepareAdvicePayload(degraded), /unresolved source quality flags/);
+
+  const unknownConfidence = payloadInputFixture();
+  unknownConfidence.sources = [{ ...unknownConfidence.sources[0], confidence: 'unknown' }];
+  assert.throws(() => prepareAdvicePayload(unknownConfidence), /source confidence/);
+});
diff --git a/src/test/advicePersistence.test.ts b/src/test/advicePersistence.test.ts
new file mode 100644
index 00000000..67e0acea
--- /dev/null
+++ b/src/test/advicePersistence.test.ts
@@ -0,0 +1,625 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import { compareAdviceEffectiveness } from '../adviceEffectiveness/comparison';
+
+import {
+  ADVICE_LOCAL_STATE_KEY,
+  ADVICE_LOCAL_STATE_VERSION,
+  ADVICE_SNOOZE_DURATION_MS,
+  MAX_PERSISTED_ADVICE_COMPARISON_RESULTS,
+  AdviceLocalStateStorage,
+  StoredComparablePair,
+  appendAdviceComparisonResult,
+  appendStoredComparablePair,
+  adviceRecommendationSnoozedUntil,
+  createClearedAdviceLocalState,
+  createClosedAdviceLocalState,
+  loadAndMigrateAdviceLocalState,
+  saveAdviceLocalState,
+  snoozeAdviceRecommendation,
+  resumeAdviceRecommendation,
+  selectStoredComparablePairLineage,
+  toComparableTaskPairs,
+  upsertAdviceLocalFeedback,
+} from '../adviceEffectiveness/versionedPersistence';
+import {
+  AdviceComparisonResultEnvelope,
+  buildAdviceComparisonResultEnvelope,
+} from '../adviceEffectiveness/comparisonResult';
+
+class MemoryStorage implements AdviceLocalStateStorage {
+  value: unknown;
+  updates: unknown[] = [];
+  failUpdate = false;
+
+  get<T>(key: string): T | undefined {
+    assert.equal(key, ADVICE_LOCAL_STATE_KEY);
+    return this.value as T | undefined;
+  }
+
+  async update(key: string, value: unknown): Promise<void> {
+    assert.equal(key, ADVICE_LOCAL_STATE_KEY);
+    if (this.failUpdate) throw new Error('PRIVATE_STORAGE_FAILURE');
+    this.value = value;
+    this.updates.push(value);
+  }
+}
+
+test('missing local state defaults to a closed, non-consenting state without writing', async () => {
+  const storage = new MemoryStorage();
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.deepEqual(result, {
+    ok: true,
+    migrated: false,
+    value: createClosedAdviceLocalState(),
+  });
+  assert.equal(storage.updates.length, 0);
+});
+
+test('user privacy reset keeps the surface enabled while erasing consent and every local result', () => {
+  assert.deepEqual(createClearedAdviceLocalState(), {
+    ...createClosedAdviceLocalState(),
+    featureMode: 'enabled',
+  });
+});
+
+test('v1 migration preserves validated local feedback but conservatively closes feature and consent', async () => {
+  const storage = new MemoryStorage();
+  storage.value = {
+    schemaVersion: 1,
+    enabled: true,
+    includePromptSamples: true,
+    feedback: [
+      {
+        adviceId: 'advice-1',
+        recommendationId: 'recommendation-1',
+        rating: 'helpful',
+        applied: true,
+        updatedAtEpochMs: 1_777_000_000_000,
+      },
+    ],
+  };
+
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.migrated, true);
+  assert.equal(result.value.schemaVersion, ADVICE_LOCAL_STATE_VERSION);
+  assert.equal(result.value.featureMode, 'disabled');
+  assert.equal(result.value.aggregateConsent, 'not-granted');
+  assert.equal(result.value.promptSampleConsent, 'not-granted');
+  assert.deepEqual(result.value.comparisonResults, []);
+  assert.deepEqual(result.value.suppression, []);
+  assert.deepEqual(result.value.feedback, [
+    {
+      adviceId: 'advice-1',
+      recommendationId: 'recommendation-1',
+      rating: 'helpful',
+      applied: 'applied',
+      appliedAtEpochMs: 1_777_000_000_000,
+      updatedAtEpochMs: 1_777_000_000_000,
+    },
+  ]);
+  assert.deepEqual(storage.updates, [result.value]);
+});
+
+test('v2 migration preserves feedback, application time, pairs, and results while adding empty suppression', async () => {
+  const storage = new MemoryStorage();
+  const legacy = {
+    schemaVersion: 2,
+    featureMode: 'disabled',
+    aggregateConsent: 'not-granted',
+    promptSampleConsent: 'not-granted',
+    feedback: [{
+      adviceId: 'advice-1',
+      recommendationId: 'recommendation-1',
+      rating: 'not-helpful',
+      applied: 'applied',
+      updatedAtEpochMs: 1_777_000_000_001,
+    }],
+    comparablePairs: [],
+    comparisonResults: [],
+  } as Record<string, unknown>;
+  storage.value = legacy;
+
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.migrated, true);
+  assert.equal(result.value.schemaVersion, ADVICE_LOCAL_STATE_VERSION);
+  assert.deepEqual(result.value.feedback, [{
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    rating: 'not-helpful',
+    applied: 'applied',
+    appliedAtEpochMs: 1_777_000_000_001,
+    updatedAtEpochMs: 1_777_000_000_001,
+  }]);
+  assert.deepEqual(result.value.suppression, []);
+});
+
+test('v3 suppression migration maps only explicit provider prefixes and drops ambiguous identities', async () => {
+  const storage = new MemoryStorage();
+  storage.value = {
+    ...createClosedAdviceLocalState(),
+    suppression: [
+      {
+        adviceId: 'advice-claude-20260830',
+        recommendationId: 'recommendation-1',
+        snoozedUntilEpochMs: 1_777_000_100_000,
+        updatedAtEpochMs: 1_777_000_000_000,
+      },
+      {
+        adviceId: 'advice-unknown-dynamic',
+        recommendationId: 'recommendation-2',
+        snoozedUntilEpochMs: 1_777_000_100_100,
+        updatedAtEpochMs: 1_777_000_000_000,
+      },
+    ],
+  };
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.migrated, true);
+  assert.deepEqual(result.value.suppression, [{
+    provider: 'claude',
+    surface: 'advice',
+    recommendationId: 'recommendation-1',
+    snoozedUntilEpochMs: 1_777_000_100_000,
+    updatedAtEpochMs: 1_777_000_000_000,
+  }]);
+});
+
+test('v3 migration preserves stable suppression records in a mixed-generation write', async () => {
+  const storage = new MemoryStorage();
+  storage.value = {
+    ...createClosedAdviceLocalState(),
+    suppression: [
+      {
+        provider: 'optimizer',
+        surface: 'optimizer',
+        recommendationId: 'recommendation-optimizer-result-v1',
+        snoozedUntilEpochMs: 1_777_000_100_000,
+        updatedAtEpochMs: 1_777_000_000_000,
+      },
+      {
+        adviceId: 'advice-claude-20260830',
+        recommendationId: 'recommendation-2',
+        snoozedUntilEpochMs: 1_777_000_100_100,
+        updatedAtEpochMs: 1_777_000_000_000,
+      },
+    ],
+  };
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.value.suppression.length, 2);
+  assert.equal(result.value.suppression[0]?.provider, 'optimizer');
+  assert.equal(result.value.suppression[1]?.provider, 'claude');
+});
+
+test('unknown, corrupt, or identifying local data fails closed and is never overwritten', async () => {
+  for (const value of [
+    { schemaVersion: 99, prompt: 'PRIVATE_PROMPT' },
+    {
+      schemaVersion: ADVICE_LOCAL_STATE_VERSION,
+      featureMode: 'enabled',
+      aggregateConsent: 'explicit',
+      promptSampleConsent: 'explicit',
+      feedback: [],
+      comparablePairs: [],
+      projectPath: '/Users/private/project',
+    },
+  ]) {
+    const storage = new MemoryStorage();
+    storage.value = value;
+    const result = await loadAndMigrateAdviceLocalState(storage);
+    assert.equal(result.ok, false);
+    assert.deepEqual(result.value, createClosedAdviceLocalState());
+    assert.equal(storage.updates.length, 0);
+  }
+});
+
+test('current local state rejects prompt consent without aggregate consent', async () => {
+  const inconsistent = {
+    ...createClosedAdviceLocalState(),
+    featureMode: 'enabled' as const,
+    aggregateConsent: 'not-granted' as const,
+    promptSampleConsent: 'explicit' as const,
+  };
+  const storage = new MemoryStorage();
+  storage.value = inconsistent;
+
+  const loaded = await loadAndMigrateAdviceLocalState(storage);
+  assert.deepEqual(loaded, {
+    ok: false,
+    reason: 'invalid-local-data',
+    value: createClosedAdviceLocalState(),
+  });
+  assert.equal(storage.updates.length, 0);
+
+  const saved = await saveAdviceLocalState(storage, inconsistent);
+  assert.deepEqual(saved, { ok: false, reason: 'invalid-local-data' });
+  assert.equal(storage.updates.length, 0);
+});
+
+test('migration write failure returns a closed state without exposing the storage error', async () => {
+  const storage = new MemoryStorage();
+  storage.value = {
+    schemaVersion: 1,
+    enabled: false,
+    includePromptSamples: false,
+    feedback: [],
+  };
+  storage.failUpdate = true;
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.deepEqual(result, {
+    ok: false,
+    reason: 'storage-error',
+    value: createClosedAdviceLocalState(),
+  });
+  assert.doesNotMatch(JSON.stringify(result), /PRIVATE_STORAGE_FAILURE/);
+});
+
+test('save accepts only the exact enum, numeric, and opaque-id state shape', async () => {
+  const storage = new MemoryStorage();
+  const state = createClosedAdviceLocalState();
+  state.featureMode = 'enabled';
+  state.aggregateConsent = 'explicit';
+  state.feedback.push({
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    rating: 'not-helpful',
+    applied: 'not-applied',
+    appliedAtEpochMs: null,
+    updatedAtEpochMs: 1_777_000_000_000,
+  });
+  const saved = await saveAdviceLocalState(storage, state);
+  assert.deepEqual(saved, { ok: true, value: state });
+
+  const hostile = { ...state, sessionId: 'PRIVATE_SESSION' };
+  const rejected = await saveAdviceLocalState(storage, hostile);
+  assert.equal(rejected.ok, false);
+  assert.equal(storage.updates.length, 1);
+});
+
+test('feedback upsert keeps rating mutually exclusive while applied remains independent', () => {
+  const initial = createClosedAdviceLocalState();
+  const helpful = upsertAdviceLocalFeedback(initial, {
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    kind: 'helpful',
+    updatedAtEpochMs: 1_777_000_000_001,
+  });
+  assert.equal(helpful.ok, true);
+  if (!helpful.ok) return;
+  const applied = upsertAdviceLocalFeedback(helpful.value, {
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    kind: 'applied',
+    updatedAtEpochMs: 1_777_000_000_002,
+  });
+  assert.equal(applied.ok, true);
+  if (!applied.ok) return;
+  const notHelpful = upsertAdviceLocalFeedback(applied.value, {
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    kind: 'not-helpful',
+    updatedAtEpochMs: 1_777_000_000_003,
+  });
+  assert.equal(notHelpful.ok, true);
+  if (!notHelpful.ok) return;
+  assert.deepEqual(notHelpful.value.feedback, [
+    {
+      adviceId: 'advice-1',
+      recommendationId: 'recommendation-1',
+      rating: 'not-helpful',
+      applied: 'applied',
+      appliedAtEpochMs: 1_777_000_000_002,
+      updatedAtEpochMs: 1_777_000_000_003,
+    },
+  ]);
+
+  const ratingRetracted = upsertAdviceLocalFeedback(notHelpful.value, {
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    kind: 'not-helpful',
+    updatedAtEpochMs: 1_777_000_000_004,
+  });
+  assert.equal(ratingRetracted.ok, true);
+  if (!ratingRetracted.ok) return;
+  assert.equal(ratingRetracted.value.feedback[0].rating, 'unrated');
+  assert.equal(ratingRetracted.value.feedback[0].applied, 'applied');
+
+  const applicationRetracted = upsertAdviceLocalFeedback(ratingRetracted.value, {
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    kind: 'applied',
+    updatedAtEpochMs: 1_777_000_000_005,
+  });
+  assert.equal(applicationRetracted.ok, true);
+  if (!applicationRetracted.ok) return;
+  assert.deepEqual(applicationRetracted.value.feedback, []);
+});
+
+test('explicit snooze is bounded, expires, resumes, and never overwrites feedback', () => {
+  const now = 1_777_000_000_000;
+  const rated = upsertAdviceLocalFeedback(createClosedAdviceLocalState(), {
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    kind: 'helpful',
+    updatedAtEpochMs: now,
+  });
+  assert.equal(rated.ok, true);
+  if (!rated.ok) return;
+  const snoozed = snoozeAdviceRecommendation(rated.value, {
+    provider: 'claude',
+    surface: 'advice',
+    recommendationId: 'recommendation-1',
+    updatedAtEpochMs: now + 1,
+    snoozedUntilEpochMs: now + 1 + ADVICE_SNOOZE_DURATION_MS,
+  });
+  assert.equal(snoozed.ok, true);
+  if (!snoozed.ok) return;
+  assert.equal(snoozed.value.feedback[0].rating, 'helpful');
+  assert.equal(
+    adviceRecommendationSnoozedUntil(snoozed.value, {
+      provider: 'claude',
+      surface: 'advice',
+      recommendationId: 'recommendation-1',
+      nowEpochMs: now + 2,
+    }),
+    now + 1 + ADVICE_SNOOZE_DURATION_MS,
+  );
+  assert.equal(
+    adviceRecommendationSnoozedUntil(snoozed.value, {
+      provider: 'claude',
+      surface: 'advice',
+      recommendationId: 'recommendation-1',
+      nowEpochMs: now + 1 + ADVICE_SNOOZE_DURATION_MS,
+    }),
+    null,
+  );
+  assert.equal(
+    adviceRecommendationSnoozedUntil(snoozed.value, {
+      provider: 'claude',
+      surface: 'advice',
+      recommendationId: 'recommendation-new',
+      nowEpochMs: now + 2,
+    }),
+    null,
+    'a new evidence/advice revision must reappear immediately',
+  );
+  const resumed = resumeAdviceRecommendation(snoozed.value, {
+    provider: 'claude',
+    surface: 'advice',
+    recommendationId: 'recommendation-1',
+  });
+  assert.equal(resumed.ok, true);
+  if (!resumed.ok) return;
+  assert.deepEqual(resumed.value.suppression, []);
+  assert.equal(resumed.value.feedback[0].rating, 'helpful');
+});
+
+test('suppression rejects unbounded duration and identifying payload fields', () => {
+  const now = 1_777_000_000_000;
+  const state = createClosedAdviceLocalState();
+  const tooLong = snoozeAdviceRecommendation(state, {
+    provider: 'claude',
+    surface: 'advice',
+    recommendationId: 'recommendation-1',
+    updatedAtEpochMs: now,
+    snoozedUntilEpochMs: now + 31 * 24 * 60 * 60 * 1_000,
+  });
+  assert.deepEqual(tooLong, { ok: false, reason: 'invalid-input' });
+  const rawPayload = snoozeAdviceRecommendation(state, {
+    provider: 'claude',
+    surface: 'advice',
+    recommendationId: 'recommendation-1',
+    updatedAtEpochMs: now,
+    snoozedUntilEpochMs: now + ADVICE_SNOOZE_DURATION_MS,
+    prompt: 'PRIVATE_PROMPT',
+  } as never);
+  assert.deepEqual(rawPayload, { ok: false, reason: 'invalid-input' });
+  const crossProvider = snoozeAdviceRecommendation(state, {
+    provider: 'optimizer',
+    surface: 'advice',
+    recommendationId: 'recommendation-1',
+    updatedAtEpochMs: now,
+    snoozedUntilEpochMs: now + ADVICE_SNOOZE_DURATION_MS,
+  });
+  assert.deepEqual(crossProvider, { ok: false, reason: 'invalid-input' });
+});
+
+function comparablePair(): StoredComparablePair {
+  return {
+    pairId: 'pair-1',
+    adviceId: 'advice-1',
+    recommendationId: 'recommendation-1',
+    recommendationVersion: 'recommendation-v1',
+    context: {
+      scope: 'task-cohort',
+      taskKind: 'small-change',
+      complexityBand: 'low',
+      provider: 'codex',
+      modelFamily: 'other',
+      effort: 'high',
+      measurementProfileVersion: 'codex-aggregate-v1',
+      metricDefinitionVersion: 'fresh-tokens-v1',
+      qualityRubricId: 'task-quality-rubric-v1',
+    },
+    metric: {
+      name: 'fresh-tokens',
+      unit: 'tokens',
+      direction: 'lower-is-better',
+      beforeValue: 1_000,
+      afterValue: 800,
+    },
+    quality: {
+      beforeScore: 0.9,
+      afterScore: 0.91,
+      beforePassed: 'passed',
+      afterPassed: 'passed',
+      beforeEvidenceCount: 2,
+      afterEvidenceCount: 2,
+    },
+    evidence: {
+      beforeCoverage: 'complete',
+      afterCoverage: 'complete',
+      beforeConfidence: 'high',
+      afterConfidence: 'high',
+      beforeQualityFlags: [],
+      afterQualityFlags: [],
+    },
+    recordedAtEpochMs: 1_777_000_000_000,
+  };
+}
+
+function comparisonResult(recordedAtEpochMs: number): AdviceComparisonResultEnvelope {
+  const pairs = Array.from({ length: 5 }, (_, index) => {
+    const value = comparablePair();
+    value.pairId = `pair-${recordedAtEpochMs}-${index}`;
+    return value;
+  });
+  const result = buildAdviceComparisonResultEnvelope({
+    provider: 'codex',
+    recommendationId: 'recommendation-1',
+    recommendationVersion: 'recommendation-v1',
+    measurementProfileVersion: 'codex-aggregate-v1',
+    cohort: {
+      scope: 'task-cohort',
+      taskKind: 'small-change',
+      complexityBand: 'low',
+      modelFamily: 'other',
+      effort: 'high',
+      metricDefinitionVersion: 'fresh-tokens-v1',
+      qualityRubricId: 'task-quality-rubric-v1',
+      metric: { name: 'fresh-tokens', unit: 'tokens', direction: 'lower-is-better' },
+    },
+    guardrail: {
+      minComparablePairs: 5,
+      minRelativeImprovement: 0.1,
+      minAfterQualityScore: 0.8,
+      maxMeanQualityRegression: 0.02,
+      allowedQualityFlags: [],
+      qualityRubricId: 'task-quality-rubric-v1',
+    },
+    pairs,
+    recordedAtEpochMs,
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) throw new Error('comparison result fixture failed validation');
+  return result.value;
+}
+
+test('comparable-pair persistence accepts only coarse enums, finite numbers, and opaque IDs', async () => {
+  const state = createClosedAdviceLocalState();
+  const appended = appendStoredComparablePair(state, comparablePair());
+  assert.equal(appended.ok, true);
+  if (!appended.ok) return;
+  assert.equal(appended.value.comparablePairs.length, 1);
+  const converted = toComparableTaskPairs(appended.value.comparablePairs);
+  assert.equal(converted.length, 1);
+  assert.equal(converted[0].before.primaryMetric.value, 1_000);
+  assert.equal(converted[0].after.primaryMetric.value, 800);
+  const storage = new MemoryStorage();
+  storage.value = appended.value;
+  const loaded = await loadAndMigrateAdviceLocalState(storage);
+  assert.equal(loaded.ok, true);
+  if (loaded.ok) assert.deepEqual(loaded.value.comparablePairs, [comparablePair()]);
+
+  const hostile = {
+    ...comparablePair(),
+    sessionId: 'PRIVATE_SESSION',
+  };
+  const rejected = appendStoredComparablePair(state, hostile);
+  assert.equal(rejected.ok, false);
+
+  const nestedHostile = comparablePair() as StoredComparablePair & {
+    context: StoredComparablePair['context'] & { projectPath: string };
+  };
+  nestedHostile.context.projectPath = '/Users/private/project';
+  assert.equal(appendStoredComparablePair(state, nestedHostile).ok, false);
+
+  const invalidNumber = comparablePair();
+  invalidNumber.metric.afterValue = Number.NaN;
+  assert.equal(appendStoredComparablePair(state, invalidNumber).ok, false);
+});
+
+test('comparison lineage spans rotating advice instances while preserving strict cohort checks', () => {
+  const acrossDays = Array.from({ length: 5 }, (_, index) => {
+    const pair = comparablePair();
+    pair.pairId = `pair-day-${index + 1}`;
+    pair.adviceId = `advice-codex-30d-day-${index + 1}`;
+    return pair;
+  });
+  const otherRecommendation = comparablePair();
+  otherRecommendation.pairId = 'pair-other-recommendation';
+  otherRecommendation.recommendationId = 'recommendation-other';
+  const otherProvider = comparablePair();
+  otherProvider.pairId = 'pair-other-provider';
+  otherProvider.context.provider = 'claude';
+
+  const selected = selectStoredComparablePairLineage(
+    [...acrossDays, otherRecommendation, otherProvider],
+    { provider: 'codex', recommendationId: 'recommendation-1' },
+  );
+  assert.deepEqual(selected.map((pair) => pair.adviceId), acrossDays.map((pair) => pair.adviceId));
+  assert.equal(compareAdviceEffectiveness(toComparableTaskPairs(selected)).status, 'improved');
+
+  const mixedTask = comparablePair();
+  mixedTask.pairId = 'pair-mixed-task';
+  mixedTask.adviceId = 'advice-codex-30d-later-day';
+  mixedTask.context.taskKind = 'feature';
+  const withMixedCohort = selectStoredComparablePairLineage(
+    [...acrossDays, mixedTask],
+    { provider: 'codex', recommendationId: 'recommendation-1' },
+  );
+  assert.equal(
+    compareAdviceEffectiveness(toComparableTaskPairs(withMixedCohort)).status,
+    'insufficient-evidence',
+    'lineage selection must not silently drop an incomparable task cohort',
+  );
+});
+
+test('legacy exact v2 state migrates in-place to the same ledger with empty comparison results', async () => {
+  const storage = new MemoryStorage();
+  storage.value = {
+    schemaVersion: 2,
+    featureMode: 'disabled',
+    aggregateConsent: 'not-granted',
+    promptSampleConsent: 'not-granted',
+    feedback: [],
+    comparablePairs: [],
+  };
+  const result = await loadAndMigrateAdviceLocalState(storage);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(result.migrated, true);
+  assert.deepEqual(result.value.comparisonResults, []);
+  assert.deepEqual(storage.updates, [result.value]);
+});
+
+test('comparison results share v2 state, remain bounded, and reject duplicate or hostile envelopes', () => {
+  let state = createClosedAdviceLocalState();
+  const first = comparisonResult(1_778_000_000_000);
+  const appended = appendAdviceComparisonResult(state, first);
+  assert.equal(appended.ok, true);
+  if (!appended.ok) return;
+  state = appended.value;
+  assert.deepEqual(state.comparisonResults, [first]);
+  assert.equal(appendAdviceComparisonResult(state, first).ok, false, 'duplicate IDs fail closed');
+
+  const hostile = { ...comparisonResult(1_778_000_000_001), prompt: 'PRIVATE_PROMPT' };
+  assert.equal(appendAdviceComparisonResult(state, hostile).ok, false);
+
+  for (let index = 1; index <= MAX_PERSISTED_ADVICE_COMPARISON_RESULTS; index += 1) {
+    const result = appendAdviceComparisonResult(state, comparisonResult(1_778_000_000_001 + index));
+    assert.equal(result.ok, true);
+    if (!result.ok) return;
+    state = result.value;
+  }
+  assert.equal(state.comparisonResults.length, MAX_PERSISTED_ADVICE_COMPARISON_RESULTS);
+  assert.notEqual(state.comparisonResults[0].comparisonId, first.comparisonId);
+});
diff --git a/src/test/advicePreparedRequest.test.ts b/src/test/advicePreparedRequest.test.ts
new file mode 100644
index 00000000..93488fbf
--- /dev/null
+++ b/src/test/advicePreparedRequest.test.ts
@@ -0,0 +1,150 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  prepareAiInvocation,
+  previewAiInvocation,
+  sendPreparedAiInvocation,
+} from '../adviceEffectiveness/preparedRequest';
+
+test('Anthropic preview and sender consume the exact same canonical HTTP bytes', async () => {
+  const prepared = prepareAiInvocation({
+    kind: 'advice',
+    apiFormat: 'anthropic',
+    apiUrl: 'https://api.anthropic.com',
+    model: 'claude-sonnet-4-5',
+    systemPrompt: 'Return strict JSON only.',
+    userContent: '{"evidence":"aggregate-only"}',
+    dataMode: 'aggregates-only',
+    sourceRevision: 'rev-42',
+    consentGeneration: 3,
+    createdAtEpochMs: 1_000,
+  });
+  const preview = previewAiInvocation(prepared);
+  let networkCalls = 0;
+  let sentBytes: Uint8Array | undefined;
+
+  assert.equal(networkCalls, 0, 'preparing and previewing must not send');
+  const result = await sendPreparedAiInvocation(
+    prepared,
+    { backend: 'api', apiKey: 'byok-secret' },
+    async (request) => {
+      networkCalls += 1;
+      sentBytes = request.canonicalBytes;
+      assert.equal(request.headers['x-api-key'], 'byok-secret');
+      assert.equal(Object.values(request.headers).some((value) => preview.body.includes(value)), false);
+      return 'ok';
+    },
+  );
+
+  assert.equal(result, 'ok');
+  assert.equal(networkCalls, 1);
+  assert.strictEqual(sentBytes, prepared.canonicalBytes);
+  assert.equal(Buffer.from(sentBytes!).toString('utf8'), preview.body);
+  assert.equal(preview.utf8Bytes, prepared.canonicalBytes.byteLength);
+  assert.match(preview.sha256, /^[a-f0-9]{64}$/);
+  assert.deepEqual(JSON.parse(preview.body), {
+    max_tokens: 16_000,
+    messages: [{ content: '{"evidence":"aggregate-only"}', role: 'user' }],
+    model: 'claude-sonnet-4-5',
+    system: 'Return strict JSON only.',
+  });
+});
+
+test('OpenAI-compatible optimizer uses the same boundary without advice parser fallback', async () => {
+  const prepared = prepareAiInvocation({
+    kind: 'optimizer',
+    apiFormat: 'openai',
+    apiUrl: 'https://api.deepseek.com/v1',
+    model: 'deepseek-chat',
+    reasoningEffort: 'high',
+    systemPrompt: 'Use the optimizer markers exactly.',
+    userContent: 'User pasted draft only',
+    dataMode: 'user-draft-only',
+    sourceRevision: 'optimizer-draft-1',
+    consentGeneration: 1,
+    createdAtEpochMs: 2_000,
+  });
+  const preview = previewAiInvocation(prepared);
+  const body = JSON.parse(preview.body);
+
+  assert.equal(prepared.endpoint, 'https://api.deepseek.com/chat/completions');
+  assert.equal(body.messages[1].content, 'User pasted draft only');
+  assert.equal(body.reasoning_effort, 'high');
+  assert.equal(body.thinking, undefined);
+  assert.equal(JSON.stringify(body).includes('byok-secret'), false);
+});
+
+test('OpenAI reasoning effort never emits the unsupported top-level thinking parameter', () => {
+  const prepared = prepareAiInvocation({
+    kind: 'optimizer',
+    apiFormat: 'openai',
+    apiUrl: 'https://api.openai.com/v1',
+    model: 'gpt-5.6-sol',
+    reasoningEffort: 'max',
+    systemPrompt: 'Return the requested optimizer payload.',
+    userContent: 'Draft request',
+    dataMode: 'user-draft-only',
+    sourceRevision: 'issue-94',
+    consentGeneration: 1,
+    createdAtEpochMs: 2_500,
+  });
+  const body = JSON.parse(previewAiInvocation(prepared).body);
+
+  assert.equal(prepared.endpoint, 'https://api.openai.com/v1/chat/completions');
+  assert.equal(body.reasoning_effort, 'max');
+  assert.equal(body.thinking, undefined);
+});
+
+test('prepared request fails closed for subscription OAuth, missing BYOK, stale state, or tampering', async () => {
+  const prepared = prepareAiInvocation({
+    kind: 'advice',
+    apiFormat: 'openai',
+    apiUrl: 'https://example.invalid/v1',
+    model: 'safe-model',
+    systemPrompt: 'strict',
+    userContent: '{}',
+    dataMode: 'aggregates-only',
+    sourceRevision: 'rev-safe',
+    consentGeneration: 7,
+    createdAtEpochMs: 10_000,
+  });
+  let calls = 0;
+  const sender = async (): Promise<string> => {
+    calls += 1;
+    return 'unexpected';
+  };
+
+  await assert.rejects(
+    sendPreparedAiInvocation(prepared, { backend: 'subscription', apiKey: 'x' } as never, sender),
+    /BYOK API/,
+  );
+  await assert.rejects(
+    sendPreparedAiInvocation(prepared, { backend: 'api', apiKey: '  ' }, sender),
+    /API key/,
+  );
+  await assert.rejects(
+    sendPreparedAiInvocation(
+      prepared,
+      { backend: 'api', apiKey: 'x', expectedSourceRevision: 'different' },
+      sender,
+    ),
+    /stale/,
+  );
+  await assert.rejects(
+    sendPreparedAiInvocation(
+      prepared,
+      { backend: 'api', apiKey: 'x', expectedConsentGeneration: 8 },
+      sender,
+    ),
+    /stale/,
+  );
+
+  const mutated = prepared as unknown as { serializedBody: string };
+  mutated.serializedBody = '{"changed":true}';
+  await assert.rejects(
+    sendPreparedAiInvocation(prepared, { backend: 'api', apiKey: 'x' }, sender),
+    /integrity/,
+  );
+  assert.equal(calls, 0);
+});
diff --git a/src/test/advicePrivacy.test.ts b/src/test/advicePrivacy.test.ts
new file mode 100644
index 00000000..425a5994
--- /dev/null
+++ b/src/test/advicePrivacy.test.ts
@@ -0,0 +1,64 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import { prepareAdvicePayload, previewAdvicePayload } from '../adviceEffectiveness/payload';
+import { payloadInputFixture } from './adviceTestFixtures';
+
+const SENTINELS = {
+  prompt: 'PRIVATE_PROMPT_SENTINEL',
+  response: 'PRIVATE_RESPONSE_SENTINEL',
+  path: '/Users/private/repository',
+  session: 'PRIVATE_SESSION_ID',
+  credential: 'sk-ant-private-credential',
+  username: 'private-user-name',
+};
+
+function hostileInput(includePrompt: boolean) {
+  const input = payloadInputFixture() as ReturnType<typeof payloadInputFixture> & Record<string, unknown>;
+  input.cwd = SENTINELS.path;
+  input.sessionId = SENTINELS.session;
+  input.apiKey = SENTINELS.credential;
+  (input.aggregate as unknown as Record<string, unknown>).response = SENTINELS.response;
+  (input.aggregate.totals as unknown as Record<string, unknown>).username = SENTINELS.username;
+  (input.aggregate.modelFamilies[0] as unknown as Record<string, unknown>).model = 'private-custom-model';
+  (input.sources[0] as unknown as Record<string, unknown>).repoPath = SENTINELS.path;
+  (input.sources[0].window as unknown as Record<string, unknown>).rawSessionId = SENTINELS.session;
+  (input.observations[0] as unknown as Record<string, unknown>).prompt = SENTINELS.prompt;
+  (input.evidence[0] as unknown as Record<string, unknown>).response = SENTINELS.response;
+  if (includePrompt) {
+    input.promptSamples = {
+      consent: 'explicit',
+      samples: [
+        {
+          text: SENTINELS.prompt,
+          cwd: SENTINELS.path,
+          response: SENTINELS.response,
+          apiKey: SENTINELS.credential,
+        } as { text: string },
+      ],
+    };
+  }
+  return input;
+}
+
+test('aggregates-only serialization strips hostile raw content and identifying fields at every depth', () => {
+  const prepared = prepareAdvicePayload(hostileInput(false));
+  const preview = previewAdvicePayload(prepared);
+  assert.equal(preview.body, prepared.serializedBody);
+  for (const sentinel of Object.values(SENTINELS)) {
+    assert.equal(prepared.serializedBody.includes(sentinel), false, `leaked sentinel: ${sentinel}`);
+  }
+  assert.doesNotMatch(
+    prepared.serializedBody,
+    /"(?:cwd|path|repoPath|sessionId|rawSessionId|username|apiKey|response|prompt)"/
+  );
+});
+
+test('prompt opt-in permits only bounded prompt text and still strips cwd, response, and credentials', () => {
+  const prepared = prepareAdvicePayload(hostileInput(true));
+  assert.equal(prepared.serializedBody.includes(SENTINELS.prompt), true);
+  for (const sentinel of [SENTINELS.path, SENTINELS.response, SENTINELS.credential, SENTINELS.session]) {
+    assert.equal(prepared.serializedBody.includes(sentinel), false, `leaked non-consented sentinel: ${sentinel}`);
+  }
+  assert.doesNotMatch(prepared.serializedBody, /"(?:cwd|repoPath|sessionId|apiKey|response)"/);
+});
diff --git a/src/test/adviceRemoteInvocation.test.ts b/src/test/adviceRemoteInvocation.test.ts
new file mode 100644
index 00000000..d69f3d73
--- /dev/null
+++ b/src/test/adviceRemoteInvocation.test.ts
@@ -0,0 +1,106 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  prepareStructuredAdviceInvocation,
+  requestStructuredAdvice,
+} from '../adviceEffectiveness/remoteAdvice';
+import { prepareAdvicePayload } from '../adviceEffectiveness/payload';
+import { previewAiInvocation } from '../adviceEffectiveness/preparedRequest';
+import { payloadInputFixture, structuredOutputFixture } from './adviceTestFixtures';
+
+const config = {
+  apiFormat: 'openai' as const,
+  apiUrl: 'https://example.invalid/v1',
+  model: 'private-model',
+};
+
+test('structured advice preview is the complete provider body later sent byte-for-byte', async () => {
+  const evidence = prepareAdvicePayload(payloadInputFixture());
+  const prepared = prepareStructuredAdviceInvocation(evidence, {
+    ...config,
+    sourceRevision: 'claude-index-42',
+    consentGeneration: 3,
+    createdAtEpochMs: 1_000,
+  });
+  const preview = previewAiInvocation(prepared);
+  const parsedBody = JSON.parse(preview.body);
+  let sentBytes: Uint8Array | undefined;
+
+  assert.equal(parsedBody.messages[1].content, evidence.serializedBody);
+  assert.equal(parsedBody.messages[0].role, 'system');
+  assert.equal(prepared.dataMode, 'aggregates-only');
+
+  const result = await requestStructuredAdvice(
+    prepared,
+    {
+      observationIds: ['observation-cache-share'],
+      evidenceIds: ['evidence-cache-share'],
+    },
+    {
+      apiKey: 'PRIVATE_API_KEY',
+      expectedSourceRevision: 'claude-index-42',
+      expectedConsentGeneration: 3,
+      transport: async (request) => {
+        sentBytes = request.canonicalBytes;
+        return {
+          status: 200,
+          body: JSON.stringify({
+            choices: [{ message: { content: JSON.stringify(structuredOutputFixture()) } }],
+          }),
+        };
+      },
+    },
+  );
+
+  assert.equal(result.ok, true);
+  assert.strictEqual(sentBytes, prepared.canonicalBytes);
+  assert.equal(Buffer.from(sentBytes!).toString('utf8'), preview.body);
+  assert.doesNotMatch(preview.body, /PRIVATE_API_KEY/);
+});
+
+test('structured advice fails closed on stale consent or malformed strict output', async () => {
+  const prepared = prepareStructuredAdviceInvocation(
+    prepareAdvicePayload(payloadInputFixture()),
+    {
+      ...config,
+      sourceRevision: 'claude-index-42',
+      consentGeneration: 3,
+      createdAtEpochMs: 1_000,
+    },
+  );
+  let calls = 0;
+  const stale = await requestStructuredAdvice(
+    prepared,
+    { observationIds: ['observation-cache-share'], evidenceIds: ['evidence-cache-share'] },
+    {
+      apiKey: 'PRIVATE_API_KEY',
+      expectedConsentGeneration: 4,
+      transport: async () => {
+        calls += 1;
+        return { status: 200, body: '{}' };
+      },
+    },
+  );
+  assert.deepEqual(stale, {
+    ok: false,
+    code: 'transport-error',
+    issues: ['configured BYOK transport failed'],
+  });
+  assert.equal(calls, 0);
+
+  const malformed = await requestStructuredAdvice(
+    prepared,
+    { observationIds: ['observation-cache-share'], evidenceIds: ['evidence-cache-share'] },
+    {
+      apiKey: 'PRIVATE_API_KEY',
+      expectedConsentGeneration: 3,
+      transport: async () => ({
+        status: 200,
+        body: JSON.stringify({ choices: [{ message: { content: '```json\n{}\n```' } }] }),
+      }),
+    },
+  );
+  assert.equal(malformed.ok, false);
+  if (!malformed.ok) assert.equal(malformed.code, 'invalid-json');
+});
diff --git a/src/test/adviceRuntimePolicy.test.ts b/src/test/adviceRuntimePolicy.test.ts
new file mode 100644
index 00000000..30d08a00
--- /dev/null
+++ b/src/test/adviceRuntimePolicy.test.ts
@@ -0,0 +1,88 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+
+const root = path.resolve(__dirname, '..', '..');
+
+test('extension advice and optimizer runtime stay API/BYOK-only', () => {
+  const source = readFileSync(path.join(root, 'src', 'extension.ts'), 'utf8');
+  const types = readFileSync(path.join(root, 'src', 'types.ts'), 'utf8');
+  assert.match(source, /adviceBackend:\s*'api'/);
+  assert.doesNotMatch(source, /getSubscriptionToken\s*:/);
+  assert.doesNotMatch(source, /subscriptionModel\s*:/);
+  assert.match(types, /adviceBackend:\s*'api'/);
+  assert.doesNotMatch(types, /adviceSubscriptionModel/);
+
+  // Advice and optimizer now share the prepared-request hooks installed during
+  // activation. Keep the production credential/endpoint assertions attached to
+  // those hooks instead of the legacy command-method boundaries.
+  const hooksStart = source.indexOf('this.webviewProvider.onSendOptimizerInvocation');
+  const hooksEnd = source.indexOf('this.webviewProvider.settings = this.settings', hooksStart);
+  assert.ok(hooksStart >= 0 && hooksEnd > hooksStart);
+  const runtimeHooks = source.slice(hooksStart, hooksEnd);
+  assert.match(runtimeHooks, /apiKey:\s*config\.adviceApiKey/);
+  assert.match(runtimeHooks, /apiUrl:\s*config\.adviceApiUrl/);
+  assert.match(runtimeHooks, /requestPreparedOptimizer\s*\(/);
+  assert.match(runtimeHooks, /requestStructuredAdvice\s*\(/);
+  assert.doesNotMatch(runtimeHooks, /getAccessToken\s*\(/);
+});
+
+test('optimizer preview does not create a second persisted authorization path', () => {
+  const source = readFileSync(path.join(root, 'src', 'extension.ts'), 'utf8');
+  const start = source.indexOf('private async prepareOptimizerRequest');
+  const end = source.indexOf('private loadConfiguration', start);
+  assert.ok(start >= 0 && end > start);
+  const preparation = source.slice(start, end);
+  assert.doesNotMatch(preparation, /optimizerConsented/);
+  assert.doesNotMatch(preparation, /showWarningMessage/);
+  assert.doesNotMatch(preparation, /globalState\.update/);
+});
+
+test('packaged advisor exposes no prepare-and-send shortcut around exact preview', () => {
+  const source = readFileSync(path.join(root, 'src', 'advisor.ts'), 'utf8');
+  assert.doesNotMatch(source, /export\s+async\s+function\s+callModel\b/);
+  assert.doesNotMatch(source, /export\s+async\s+function\s+getUsageAdvice\b/);
+  assert.doesNotMatch(source, /getSubscriptionToken|subscriptionModel/);
+  assert.match(source, /export\s+async\s+function\s+sendPreparedModelRequest\b/);
+});
+
+test('only the reviewed comparison writer reaches the bounded local ledger', () => {
+  const extension = readFileSync(path.join(root, 'src', 'extension.ts'), 'utf8');
+  const webview = readFileSync(path.join(root, 'src', 'webview.ts'), 'utf8');
+  const production = [extension, webview].join('\n');
+
+  for (const seam of [
+    'planAdviceEvidencePreparation',
+    'buildLegacyPersonalizationDraft',
+    'projectLegacyPersonalization',
+    'requestStructuredAdviceViaLegacyByok',
+  ]) {
+    assert.doesNotMatch(production, new RegExp(`\\b${seam}\\b`));
+  }
+
+  assert.doesNotMatch(extension, /\bappendStoredComparablePair\b/);
+  const materializerStart = webview.indexOf('private materializeAdviceComparisonState');
+  const materializerEnd = webview.indexOf(
+    'private currentAdviceComparisonProductionRevision',
+    materializerStart,
+  );
+  assert.ok(materializerStart >= 0 && materializerEnd > materializerStart);
+  const materializer = webview.slice(materializerStart, materializerEnd);
+  assert.match(materializer, /\bbuildAppliedComparablePairs\b/);
+  assert.match(materializer, /\bappendStoredComparablePair\b/);
+  assert.match(materializer, /\bbuildAdviceComparisonResultEnvelope\b/);
+  assert.match(materializer, /\bappendAdviceComparisonResult\b/);
+});
+
+test('Claude advice consumes the materialized index snapshot instead of rebuilding from records', () => {
+  const source = readFileSync(path.join(root, 'src', 'extension.ts'), 'utf8');
+  const start = source.indexOf('private buildAdviceEffectivenessProviderStates');
+  const end = source.indexOf('private codexHistoricalWorkPending', start);
+  assert.ok(start >= 0 && end > start);
+  const builder = source.slice(start, end);
+  assert.match(builder, /claudeUsageDashboardSnapshot\s*\(/);
+  assert.match(builder, /adviceWindowDays:\s*windowDays/);
+  assert.doesNotMatch(builder, /this\.cache\.records/);
+  assert.doesNotMatch(builder, /ClaudeDataLoader\.(?:getAllTimeData|getSessionBreakdown)/);
+});
diff --git a/src/test/adviceStateSerialization.test.ts b/src/test/adviceStateSerialization.test.ts
new file mode 100644
index 00000000..27bedf97
--- /dev/null
+++ b/src/test/adviceStateSerialization.test.ts
@@ -0,0 +1,616 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import Module = require('node:module');
+
+import {
+  ADVICE_LOCAL_STATE_KEY,
+  AdviceLocalState,
+  AdviceLocalStateStorage,
+  createClosedAdviceLocalState,
+  snoozeAdviceRecommendation,
+} from '../adviceEffectiveness/versionedPersistence';
+import { I18n } from '../i18n';
+import { prepareStructuredAdviceInvocation } from '../adviceEffectiveness/remoteAdvice';
+import { payloadInputFixture } from './adviceTestFixtures';
+
+class ControlledStorage implements AdviceLocalStateStorage {
+  public value: AdviceLocalState | undefined;
+  public readonly pending: Array<{
+    value: AdviceLocalState | undefined;
+    resolve: () => void;
+  }> = [];
+
+  constructor(value: AdviceLocalState) {
+    this.value = value;
+  }
+
+  get<T>(key: string): T | undefined {
+    return key === ADVICE_LOCAL_STATE_KEY ? this.value as T : undefined;
+  }
+
+  update(key: string, value: unknown): Promise<void> {
+    assert.equal(key, ADVICE_LOCAL_STATE_KEY);
+    return new Promise((resolve) => {
+      this.pending.push({
+        value: value as AdviceLocalState | undefined,
+        resolve: () => {
+          this.value = value as AdviceLocalState | undefined;
+          resolve();
+        },
+      });
+    });
+  }
+
+  releaseNext(): void {
+    const next = this.pending.shift();
+    assert.ok(next, 'expected a pending state write');
+    next.resolve();
+  }
+}
+
+async function nextTurn(): Promise<void> {
+  await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+async function createProvider(storage: AdviceLocalStateStorage): Promise<any> {
+  const originalLoad = (Module as any)._load;
+  (Module as any)._load = function(request: string, parent: unknown, isMain: boolean) {
+    if (request === 'vscode') {
+      return { workspace: { workspaceFolders: [] } };
+    }
+    return originalLoad.call(this, request, parent, isMain);
+  };
+  let UsageWebviewProvider: typeof import('../webview').UsageWebviewProvider;
+  try {
+    ({ UsageWebviewProvider } = require('../webview') as typeof import('../webview'));
+  } finally {
+    (Module as any)._load = originalLoad;
+  }
+  const provider = new UsageWebviewProvider({ globalState: storage } as any) as any;
+  await nextTurn();
+  provider.settings = { get: (key: string) => key === 'advice.effectiveness.enabled' };
+  provider.adviceLocalStateStatus = 'ready';
+  provider.postAdviceMessage = () => undefined;
+  return provider;
+}
+
+function grantedState(promptSamples = false): AdviceLocalState {
+  const state = createClosedAdviceLocalState();
+  state.featureMode = 'enabled';
+  state.aggregateConsent = 'explicit';
+  state.promptSampleConsent = promptSamples ? 'explicit' : 'not-granted';
+  return state;
+}
+
+async function preparedProvider(storage: AdviceLocalStateStorage, initial: AdviceLocalState) {
+  const provider = await createProvider(storage);
+  const input = payloadInputFixture();
+  const messages: Array<Record<string, unknown>> = [];
+  provider.adviceLocalState = initial;
+  provider.postAdviceMessage = (message: Record<string, unknown>) => messages.push(message);
+  provider.adviceEffectivenessStates = {
+    claude: {
+      provider: 'claude', remotePreviewEligible: true, aggregate: input.aggregate,
+      promptSamples: [{ text: 'synthetic consent fixture' }],
+      contract: {
+        adviceId: 'advice-consent-test', recommendations: [],
+        observations: input.observations, evidence: input.evidence,
+        provenance: { locale: input.locale, sources: input.sources },
+      },
+    },
+  };
+  provider.onPrepareAdviceInvocation = (snapshot: any, sourceRevision: string, consentGeneration: number) =>
+    prepareStructuredAdviceInvocation(snapshot.prepared, {
+      apiFormat: 'openai', apiUrl: 'https://example.invalid/v1', model: 'fixture',
+      sourceRevision, consentGeneration, createdAtEpochMs: 1_000,
+    });
+  provider.handlePrepareAdviceSnapshotMessage({
+    provider: 'claude', aggregateConsent: 'explicit',
+    promptSampleConsent: initial.promptSampleConsent,
+  });
+  assert.equal(provider.preparedAdviceSnapshots.size, 1);
+  const snapshotId = [...provider.preparedAdviceSnapshots.keys()][0];
+  return { provider, snapshotId, messages };
+}
+
+test('withdrawal rejects an old preview before its durable consent write completes', async () => {
+  const initial = grantedState();
+  const storage = new ControlledStorage(initial);
+  const { provider, snapshotId } = await preparedProvider(storage, initial);
+  let sends = 0;
+  provider.onSendAdviceInvocation = async () => {
+    sends += 1;
+    return { ok: false, code: 'transport-error' };
+  };
+  const withdrawal = provider.handleAdviceConsentMessage({
+    provider: 'claude', aggregateConsent: 'not-granted', promptSampleConsent: 'not-granted',
+  });
+  await nextTurn();
+  assert.equal(storage.pending.length, 1);
+  await provider.handleSendAdviceSnapshotMessage({ provider: 'claude', snapshotId });
+  assert.equal(sends, 0, 'a pending disk write must not extend revoked permission');
+  storage.releaseNext();
+  await withdrawal;
+});
+
+test('prompt withdrawal blocks fresh previews until all queued consent writes settle', async () => {
+  const initial = grantedState(true);
+  const storage = new ControlledStorage(initial);
+  const { provider, messages } = await preparedProvider(storage, initial);
+  const change = { provider: 'claude', aggregateConsent: 'explicit', promptSampleConsent: 'not-granted' };
+  const first = provider.handleAdviceConsentMessage(change);
+  const second = provider.handleAdviceConsentMessage(change);
+  await nextTurn();
+  messages.length = 0;
+  provider.handlePrepareAdviceSnapshotMessage({ ...change, promptSampleConsent: 'explicit' });
+  assert.equal(messages[messages.length - 1]?.ok, false, 'cannot recreate the old personalized request');
+  assert.equal(provider.preparedAdviceSnapshots.size, 0);
+  storage.releaseNext();
+  await nextTurn();
+  assert.equal(storage.pending.length, 1);
+  provider.handlePrepareAdviceSnapshotMessage(change);
+  assert.equal(messages[messages.length - 1]?.ok, false, 'one settled write does not unlock another pending write');
+  storage.releaseNext();
+  await Promise.all([first, second]);
+  provider.handlePrepareAdviceSnapshotMessage(change);
+  assert.equal(messages[messages.length - 1]?.ok, true, 'fresh aggregate-only preview works after withdrawal settles');
+});
+
+for (const kind of ['aggregate', 'prompt'] as const) {
+  test(`${kind} withdrawal cancels an active send before storage settles`, async () => {
+    const initial = grantedState(true);
+    const storage = new ControlledStorage(initial);
+    const { provider, snapshotId, messages } = await preparedProvider(storage, initial);
+    let finish!: (value: unknown) => void;
+    let cancelled = false;
+    provider.onSendAdviceInvocation = () => new Promise((resolve) => { finish = resolve; });
+    provider.onAdviceConsentWithdrawn = async () => {
+      cancelled = true;
+      finish({ ok: false, code: 'transport-error' });
+    };
+    const send = provider.handleSendAdviceSnapshotMessage({ provider: 'claude', snapshotId });
+    await nextTurn();
+    const withdrawal = provider.handleAdviceConsentMessage({
+      provider: 'claude', aggregateConsent: kind === 'aggregate' ? 'not-granted' : 'explicit',
+      promptSampleConsent: 'not-granted',
+    });
+    await nextTurn();
+    assert.equal(storage.pending.length, 1);
+    assert.equal(cancelled, true, 'host cancellation cannot wait for disk persistence');
+    await send;
+    assert.equal(messages.some((m) => m.command === 'adviceSendResult' && m.ok === true), false);
+    storage.releaseNext();
+    await withdrawal;
+  });
+}
+
+test('failed consent persistence cannot revive an old preview or create a new one', async () => {
+  const initial = grantedState();
+  const { provider, snapshotId, messages } = await preparedProvider({
+    get: <T>() => initial as T,
+    update: async () => { throw new Error('synthetic storage failure'); },
+  }, initial);
+  let sends = 0;
+  provider.onSendAdviceInvocation = async () => {
+    sends += 1;
+    return { ok: false, code: 'transport-error' };
+  };
+  await provider.handleAdviceConsentMessage({
+    provider: 'claude', aggregateConsent: 'not-granted', promptSampleConsent: 'not-granted',
+  });
+  await provider.handleSendAdviceSnapshotMessage({ provider: 'claude', snapshotId });
+  provider.handlePrepareAdviceSnapshotMessage({
+    provider: 'claude', aggregateConsent: 'explicit', promptSampleConsent: 'not-granted',
+  });
+  assert.equal(sends, 0);
+  assert.equal(provider.preparedAdviceSnapshots.size, 0);
+  assert.equal(messages[messages.length - 1]?.ok, false);
+});
+
+test('clear is serialized after an older consent write and remains the final durable state', async () => {
+  const initial = createClosedAdviceLocalState();
+  initial.featureMode = 'enabled';
+  const storage = new ControlledStorage(initial);
+  const provider = await createProvider(storage);
+  provider.adviceLocalState = initial;
+  provider.adviceEffectivenessStates = {
+    claude: {
+      provider: 'claude',
+      remotePreviewEligible: true,
+      aggregate: { windowDays: 30 },
+      promptSamples: [],
+      contract: { adviceId: 'advice-claude-test', recommendations: [] },
+    },
+  };
+  provider.onAdviceDataCleared = async () => undefined;
+
+  const consent = provider.handleAdviceConsentMessage({
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'not-granted',
+  });
+  await nextTurn();
+  assert.equal(storage.pending.length, 1);
+
+  const clear = provider.handleClearAdviceLocalDataMessage();
+  await nextTurn();
+  assert.equal(
+    storage.pending.length,
+    1,
+    'clear must share the one state-writer queue instead of racing the consent write',
+  );
+
+  storage.releaseNext();
+  await nextTurn();
+  assert.equal(storage.pending.length, 1, 'clear should begin after consent settles');
+  storage.releaseNext();
+  await Promise.all([consent, clear]);
+
+  assert.equal(storage.value, undefined, 'the current ledger key is removed');
+  assert.equal(provider.adviceLocalState.featureMode, 'enabled');
+  assert.equal(provider.adviceLocalState.aggregateConsent, 'not-granted');
+  assert.equal(provider.adviceLocalState.promptSampleConsent, 'not-granted');
+  assert.deepEqual(provider.adviceLocalState.feedback, []);
+  assert.deepEqual(provider.adviceLocalState.suppression, []);
+  assert.deepEqual(provider.adviceLocalState.comparablePairs, []);
+  assert.deepEqual(provider.adviceLocalState.comparisonResults, []);
+});
+
+test('discarded optimizer request cannot install a stale result after await', async () => {
+  const provider = await createProvider({
+    get: () => undefined,
+    update: async () => undefined,
+  });
+  provider.settings = {
+    get: (key: string) => key === 'advice.optimizer.enabled',
+  };
+  const snapshotId = 'optimizer-stale-test';
+  provider.optimizerConsentGeneration = 7;
+  provider.optimizerState = {
+    draft: 'old draft',
+    resolve: true,
+    distil: false,
+    aesthetic: false,
+  };
+  const stored = {
+    prepared: {},
+    draft: 'old draft',
+    sourceRevision: 'optimizer-source',
+    consentGeneration: 7,
+  };
+  provider.preparedOptimizerRequests.set(snapshotId, stored);
+  const messages: Array<Record<string, unknown>> = [];
+  provider.postAdviceMessage = (message: Record<string, unknown>) => messages.push(message);
+  let finish!: (value: unknown) => void;
+  provider.onSendOptimizerInvocation = () => new Promise((resolve) => {
+    finish = resolve;
+  });
+
+  const send = provider.handleSendOptimizerMessage({ snapshotId, draft: 'old draft' });
+  await nextTurn();
+  provider.discardPreparedOptimizer();
+  finish({ ok: true, value: { prompt: 'STALE RESULT', settings: 'stale' } });
+  await send;
+
+  assert.equal(provider.optimizerState.prompt, undefined);
+  assert.equal(messages.some((message) => message.prompt === 'STALE RESULT'), false);
+  const lastMessage = messages[messages.length - 1];
+  assert.equal(lastMessage?.command, 'optimizeResult');
+  assert.equal(typeof lastMessage?.error, 'string');
+});
+
+test('optimizer feedback uses the same retractable local ledger and rendered controls', async () => {
+  let durable = createClosedAdviceLocalState();
+  const provider = await createProvider({
+    get: <T>() => durable as T,
+    update: async (_key: string, value: unknown) => {
+      durable = value as AdviceLocalState;
+    },
+  });
+  provider.settings = {
+    get: (key: string) =>
+      key === 'advice.effectiveness.enabled' || key === 'advice.optimizer.enabled',
+  };
+  provider.adviceLocalState = durable;
+  provider.optimizerState = {
+    draft: 'host-only draft',
+    resolve: false,
+    distil: false,
+    aesthetic: false,
+    prompt: 'Paste-ready result',
+    settings: 'Effort: high',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+  };
+
+  await provider.handleAdviceFeedbackMessage({
+    provider: 'optimizer',
+    adviceId: provider.optimizerState.adviceId,
+    recommendationId: 'recommendation-optimizer-result-v1',
+    kind: 'helpful',
+  });
+
+  assert.equal(durable.feedback.length, 1);
+  assert.equal(durable.feedback[0].rating, 'helpful');
+  assert.equal(durable.feedback[0].applied, 'not-applied');
+  assert.doesNotMatch(JSON.stringify(durable), /host-only draft|Paste-ready result|Effort: high/);
+  const html = provider.renderOptimizerCard();
+  assert.equal((html.match(/data-advice-action="feedback"/g) ?? []).length, 3);
+  assert.match(html, /data-provider="optimizer"/);
+  assert.match(html, /recommendation-optimizer-result-v1/);
+  await provider.handleAdviceSnoozeMessage({
+    provider: 'optimizer',
+    adviceId: provider.optimizerState.adviceId,
+    recommendationId: 'recommendation-optimizer-result-v1',
+    mode: 'snooze',
+  });
+  assert.equal(durable.suppression.length, 1);
+  const snoozedHtml = provider.renderOptimizerCard();
+  assert.match(snoozedHtml, /id="optDraft"/);
+  assert.match(snoozedHtml, /id="optRunBtn"/);
+  assert.doesNotMatch(snoozedHtml, /id="optResult"|id="optSendBtn"|id="optFeedback"/);
+  assert.match(snoozedHtml, /data-snooze-mode="resume"/);
+  provider.optimizerState.adviceId = 'advice-optimizer-reloaded-dynamic';
+  provider.adviceLocalState = durable;
+  const reloadedHtml = provider.renderOptimizerCard();
+  assert.match(reloadedHtml, /data-snooze-mode="resume"/);
+});
+
+test('optimizer snooze date uses the configured timezone instead of the host timezone', async () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  const previousHostTimezone = process.env.TZ;
+  try {
+    process.env.TZ = 'UTC';
+    I18n.setLanguage('en');
+    I18n.setTimezone('Pacific/Honolulu');
+    const snoozedUntilEpochMs = Date.parse('2099-01-01T00:30:00.000Z');
+    const durable = createClosedAdviceLocalState();
+    durable.suppression = [{
+      provider: 'optimizer',
+      surface: 'optimizer',
+      recommendationId: 'recommendation-optimizer-result-v1',
+      updatedAtEpochMs: snoozedUntilEpochMs - 60_000,
+      snoozedUntilEpochMs,
+    }];
+    const provider = await createProvider({
+      get: <T>() => durable as T,
+      update: async () => undefined,
+    });
+    provider.settings = { get: (key: string) => key === 'advice.optimizer.enabled' };
+    provider.adviceLocalState = durable;
+    provider.optimizerState = {
+      draft: 'host-only draft',
+      resolve: false,
+      distil: false,
+      aesthetic: false,
+      prompt: 'Paste-ready result',
+      settings: 'Effort: high',
+      adviceId: 'advice-optimizer-timezone-test',
+    };
+
+    const html = provider.renderOptimizerCard();
+    assert.match(html, /Snoozed until 12\/31\/2098/);
+    assert.doesNotMatch(html, /Snoozed until 1\/1\/2099/);
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+    if (previousHostTimezone === undefined) {
+      delete process.env.TZ;
+    } else {
+      process.env.TZ = previousHostTimezone;
+    }
+  }
+});
+
+test('snoozed advice leaves a closed, on-demand resume control instead of the default recommendation summary', async () => {
+  let durable = createClosedAdviceLocalState();
+  const provider = await createProvider({
+    get: <T>() => durable as T,
+    update: async (_key: string, value: unknown) => {
+      durable = value as AdviceLocalState;
+    },
+  });
+  provider.settings = { get: (key: string) => key === 'advice.effectiveness.enabled' };
+  provider.adviceLocalState = durable;
+  provider.adviceEffectivenessStates = {
+    claude: {
+      provider: 'claude',
+      remotePreviewEligible: false,
+      aggregate: { windowDays: 30 },
+      promptSamples: [],
+      contract: {
+        schemaVersion: 1,
+        adviceId: 'advice-claude-snooze-test',
+        observations: [{
+          id: 'observation-1',
+          metric: 'long-session-share',
+          value: 0.5,
+          unit: 'ratio',
+          method: 'measured',
+          sourceId: 'source-1',
+          summary: 'local',
+        }],
+        evidence: [{
+          id: 'evidence-1',
+          observationIds: ['observation-1'],
+          strength: 'direct',
+          summary: 'local',
+          limitations: [],
+        }],
+        recommendations: [{
+          id: 'recommendation-claude-snooze',
+          title: 'Boundary',
+          evidenceIds: ['evidence-1'],
+          explanation: { summary: 'local', proxyMetricObservationIds: [], limitations: [] },
+          conditionalActions: [{ when: 'next task', action: 'try', evidenceIds: ['evidence-1'] }],
+          successCriteria: [],
+        }],
+        privacy: {
+          dataMode: 'local-only',
+          promptSampleConsent: 'not-applicable',
+          promptSampleCount: 0,
+          feedbackStorage: 'local-only',
+        },
+        provenance: {
+          generatedBy: { kind: 'local-rules' },
+          generatedAt: new Date(1_777_000_000_000).toISOString(),
+          locale: 'en',
+          sources: [{
+            id: 'source-1',
+            kind: 'claude-local-insight',
+            scope: 'overall',
+            window: { kind: 'rolling-days', days: 30 },
+            confidence: 'high',
+            qualityFlags: [],
+          }],
+        },
+      },
+    },
+  };
+  const snoozeNow = Date.now();
+  const result = snoozeAdviceRecommendation(durable, {
+    provider: 'claude',
+    surface: 'advice',
+    recommendationId: 'recommendation-claude-snooze',
+    updatedAtEpochMs: snoozeNow,
+    snoozedUntilEpochMs: snoozeNow + 86_400_000,
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  provider.adviceLocalState = result.value;
+  const html = provider.renderAdviceEffectivenessBody('claude');
+  assert.doesNotMatch(html, /advice-recommendation-boundary/);
+  assert.match(html, /advice-recommendation-snoozed/);
+  assert.match(html, /data-snooze-mode="resume"/);
+});
+
+test('a failed feedback save returns the validated target identity so only its controls unlock', async () => {
+  const durable = createClosedAdviceLocalState();
+  const provider = await createProvider({
+    get: <T>() => durable as T,
+    update: async () => {
+      throw new Error('simulated storage failure');
+    },
+  });
+  provider.settings = {
+    get: (key: string) => key === 'advice.optimizer.enabled',
+  };
+  provider.adviceLocalState = durable;
+  provider.optimizerState = {
+    draft: 'host-only draft',
+    resolve: false,
+    distil: false,
+    aesthetic: false,
+    prompt: 'Paste-ready result',
+    settings: 'Effort: high',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+  };
+  const messages: Array<Record<string, unknown>> = [];
+  provider.postAdviceMessage = (message: Record<string, unknown>) => messages.push(message);
+
+  await provider.handleAdviceFeedbackMessage({
+    provider: 'optimizer',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+    recommendationId: 'recommendation-optimizer-result-v1',
+    kind: 'helpful',
+  });
+
+  assert.deepEqual(messages[messages.length - 1], {
+    command: 'adviceFeedbackResult',
+    ok: false,
+    provider: 'optimizer',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+    recommendationId: 'recommendation-optimizer-result-v1',
+  });
+});
+
+test('optimizer host seam fails closed while its feature is disabled', async () => {
+  const provider = await createProvider({
+    get: () => undefined,
+    update: async () => undefined,
+  });
+  provider.settings = { get: () => false };
+  let prepares = 0;
+  let sends = 0;
+  provider.onPrepareOptimizerInvocation = async () => {
+    prepares += 1;
+    return { error: 'must not run' };
+  };
+  provider.onSendOptimizerInvocation = async () => {
+    sends += 1;
+    return { ok: false, code: 'transport-error', issues: [] };
+  };
+
+  await provider.handlePrepareOptimizerMessage({ draft: 'private draft' });
+  provider.preparedOptimizerRequests.set('optimizer-disabled', {
+    prepared: {},
+    draft: 'private draft',
+    sourceRevision: 'disabled',
+    consentGeneration: provider.optimizerConsentGeneration,
+  });
+  await provider.handleSendOptimizerMessage({
+    snapshotId: 'optimizer-disabled',
+    draft: 'private draft',
+  });
+
+  assert.equal(prepares, 0);
+  assert.equal(sends, 0);
+});
+
+test('explicit optimizer rerun resumes the stable recommendation scope without touching feedback', async () => {
+  let durable = createClosedAdviceLocalState();
+  durable.suppression = [{
+    provider: 'optimizer',
+    surface: 'optimizer',
+    recommendationId: 'recommendation-optimizer-result-v1',
+    snoozedUntilEpochMs: Date.now() + 60_000,
+    updatedAtEpochMs: Date.now(),
+  }];
+  const provider = await createProvider({
+    get: <T>() => durable as T,
+    update: async (_key: string, value: unknown) => { durable = value as AdviceLocalState; },
+  });
+  provider.settings = { get: (key: string) => key === 'advice.optimizer.enabled' };
+  provider.adviceLocalState = durable;
+  provider.onPrepareOptimizerInvocation = async () => ({ error: 'no prepared result' });
+
+  await provider.handlePrepareOptimizerMessage({ draft: 'explicit rerun' });
+
+  assert.deepEqual(durable.suppression, []);
+});
+
+test('successful optimizer send creates an opaque feedback target without deriving it from content', async () => {
+  const provider = await createProvider({
+    get: () => undefined,
+    update: async () => undefined,
+  });
+  provider.settings = { get: (key: string) => key === 'advice.optimizer.enabled' };
+  provider.optimizerConsentGeneration = 3;
+  provider.optimizerState = {
+    draft: 'SENSITIVE_DRAFT',
+    resolve: false,
+    distil: false,
+    aesthetic: false,
+  };
+  const snapshotId = 'optimizer-success';
+  provider.preparedOptimizerRequests.set(snapshotId, {
+    prepared: {},
+    draft: 'SENSITIVE_DRAFT',
+    sourceRevision: 'optimizer-source',
+    consentGeneration: 3,
+  });
+  provider.onSendOptimizerInvocation = async () => ({
+    ok: true,
+    value: { prompt: 'SENSITIVE_RESULT', settings: 'SENSITIVE_SETTINGS' },
+  });
+  const messages: Array<Record<string, unknown>> = [];
+  provider.postAdviceMessage = (message: Record<string, unknown>) => messages.push(message);
+
+  await provider.handleSendOptimizerMessage({ snapshotId, draft: 'SENSITIVE_DRAFT' });
+
+  assert.match(provider.optimizerState.adviceId, /^advice-optimizer-[a-f0-9]{24}$/);
+  assert.doesNotMatch(provider.optimizerState.adviceId, /SENSITIVE/i);
+  const lastMessage = messages[messages.length - 1];
+  assert.equal(lastMessage.recommendationId, 'recommendation-optimizer-result-v1');
+  assert.equal(lastMessage.adviceId, provider.optimizerState.adviceId);
+});
diff --git a/src/test/adviceTestFixtures.ts b/src/test/adviceTestFixtures.ts
new file mode 100644
index 00000000..888641c6
--- /dev/null
+++ b/src/test/adviceTestFixtures.ts
@@ -0,0 +1,130 @@
+import {
+  AdviceEvidence,
+  AdviceObservation,
+  AdviceRecommendation,
+  AdviceSourceInfo,
+} from '../adviceEffectiveness/contract';
+import { PrepareAdvicePayloadInput, buildAdviceAggregateSnapshot } from '../adviceEffectiveness/payload';
+import { UsageData } from '../types';
+
+export const usageFixture: UsageData = {
+  totalInputTokens: 1_000,
+  totalOutputTokens: 400,
+  totalCacheCreationTokens: 200,
+  totalCacheReadTokens: 2_000,
+  totalCost: 1.25,
+  costBreakdown: { input: 0.1, output: 0.4, cacheWrite: 0.25, cacheRead: 0.5 },
+  messageCount: 10,
+  modelBreakdown: {
+    'claude-sonnet-4-20250514': {
+      inputTokens: 700,
+      outputTokens: 300,
+      cacheCreationTokens: 100,
+      cacheReadTokens: 1_500,
+      cost: 1,
+      count: 7,
+    },
+    'private-router-model-name': {
+      inputTokens: 300,
+      outputTokens: 100,
+      cacheCreationTokens: 100,
+      cacheReadTokens: 500,
+      cost: 0.25,
+      count: 3,
+    },
+  },
+};
+
+export const sourceFixture: AdviceSourceInfo = {
+  id: 'source-usage-30d',
+  kind: 'claude-usage-aggregate',
+  scope: 'overall',
+  window: { kind: 'rolling-days', days: 30 },
+  confidence: 'high',
+  qualityFlags: [],
+};
+
+export const observationFixture: AdviceObservation = {
+  id: 'observation-cache-share',
+  metric: 'cache-read-share',
+  value: 0.625,
+  unit: 'ratio',
+  method: 'measured',
+  sourceId: sourceFixture.id,
+  summary: 'Cache reads are 62.5% of observed input-side tokens.',
+};
+
+export const proxyObservationFixture: AdviceObservation = {
+  id: 'observation-tool-intensity',
+  metric: 'post-patch-tool-intensity',
+  value: 5,
+  unit: 'count',
+  method: 'structural-proxy',
+  sourceId: sourceFixture.id,
+  summary: 'Five tool calls were observed after a patch.',
+};
+
+export const evidenceFixture: AdviceEvidence = {
+  id: 'evidence-cache-share',
+  observationIds: [observationFixture.id],
+  strength: 'correlational',
+  summary: 'The aggregate has substantial cache-read reuse.',
+  limitations: ['Cache share does not measure task quality.'],
+};
+
+export const proxyEvidenceFixture: AdviceEvidence = {
+  id: 'evidence-tool-intensity',
+  observationIds: [proxyObservationFixture.id],
+  strength: 'proxy',
+  summary: 'Post-patch tool-call count is elevated.',
+  limitations: ['Tool names and command bodies are not inspected.'],
+};
+
+export const recommendationFixture: AdviceRecommendation = {
+  id: 'recommendation-compare-boundaries',
+  title: 'Compare task boundaries on representative work',
+  evidenceIds: [evidenceFixture.id],
+  explanation: {
+    summary: 'A controlled comparison can test whether a smaller task boundary helps.',
+    proxyMetricObservationIds: [],
+    limitations: ['This aggregate alone does not establish causation.'],
+  },
+  conditionalActions: [
+    {
+      when: 'When the next task matches the same complexity and rubric',
+      action: 'Compare the current boundary with one smaller boundary.',
+      evidenceIds: [evidenceFixture.id],
+      stopCondition: 'Stop if the quality rubric fails.',
+    },
+  ],
+  successCriteria: [
+    {
+      metricObservationId: observationFixture.id,
+      direction: 'increase',
+      target: { kind: 'relative-change', value: 0.1 },
+      minimumComparableTasks: 5,
+      qualityGuardrail: {
+        rubricId: 'acceptance-rubric-v1',
+        minimumScore: 0.8,
+        maximumRegression: 0.02,
+      },
+    },
+  ],
+};
+
+export function payloadInputFixture(): PrepareAdvicePayloadInput {
+  return {
+    locale: 'en',
+    aggregate: buildAdviceAggregateSnapshot(usageFixture, 'overall', 30),
+    sources: [sourceFixture],
+    observations: [observationFixture],
+    evidence: [evidenceFixture],
+  };
+}
+
+export function structuredOutputFixture(): unknown {
+  return {
+    schemaVersion: 1,
+    recommendations: [recommendationFixture],
+  };
+}
diff --git a/src/test/backgroundWorkState.test.ts b/src/test/backgroundWorkState.test.ts
new file mode 100644
index 00000000..41a08cd2
--- /dev/null
+++ b/src/test/backgroundWorkState.test.ts
@@ -0,0 +1,299 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import {
+  BACKGROUND_WORK_STATE_SCHEMA_VERSION,
+  beginBackgroundWork,
+  canStartBackgroundWork,
+  createBackgroundWorkState,
+  interruptBackgroundWork,
+  pauseBackgroundWork,
+  recordBackgroundWorkFailure,
+  recordBackgroundWorkProgress,
+  restoreBackgroundWorkState,
+  type BackgroundWorkBackoffPolicy,
+  type BackgroundWorkProgress,
+} from '../backgroundWorkState';
+
+const policy: BackgroundWorkBackoffPolicy = {
+  failureBaseMs: 100,
+  failureMaxMs: 400,
+  noProgressCooldownMs: 250,
+};
+
+const emptyProgress: BackgroundWorkProgress = {
+  completedUnits: 0,
+  totalUnits: 5,
+  completedBytes: 0,
+  totalBytes: 50,
+};
+
+test('successful progress resets failures and is immediately eligible', () => {
+  const initial = createBackgroundWorkState({
+    measurementVersion: 7,
+    reason: 'first-index',
+    now: 1_000,
+    progress: emptyProgress,
+  });
+  const firstStart = beginBackgroundWork(initial, { trigger: 'automatic', now: 1_000 });
+  assert.equal(firstStart.started, true);
+
+  const failed = recordBackgroundWorkFailure(firstStart.state, { now: 1_010 }, policy);
+  assert.equal(failed.failStreak, 1);
+  const retry = beginBackgroundWork(failed, { trigger: 'manual', now: 1_011, reason: 'resume' });
+  assert.equal(retry.started, true);
+
+  const progressed = recordBackgroundWorkProgress(retry.state, {
+    now: 1_020,
+    complete: false,
+    progress: {
+      completedUnits: 1,
+      totalUnits: 5,
+      completedBytes: 10,
+      totalBytes: 50,
+    },
+  }, policy);
+
+  assert.equal(progressed.status, 'eligible');
+  assert.equal(progressed.failStreak, 0);
+  assert.equal(progressed.nextEligibleAt, 1_020);
+  assert.equal(progressed.pausedReason, null);
+  assert.equal(progressed.reason, 'resume');
+  assert.equal(canStartBackgroundWork(progressed, { trigger: 'automatic', now: 1_020 }), true);
+});
+
+test('failures persist an exponential backoff and manual work may bypass it', () => {
+  let state = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'first-index',
+    now: 1_000,
+    progress: emptyProgress,
+  });
+
+  state = beginBackgroundWork(state, { trigger: 'automatic', now: 1_000 }).state;
+  state = recordBackgroundWorkFailure(state, { now: 1_000 }, policy);
+  assert.equal(state.failStreak, 1);
+  assert.equal(state.nextEligibleAt, 1_100);
+  assert.equal(state.pausedReason, 'failure-backoff');
+  assert.equal(canStartBackgroundWork(state, { trigger: 'automatic', now: 1_099 }), false);
+  assert.equal(canStartBackgroundWork(state, { trigger: 'automatic', now: 1_100 }), true);
+  assert.equal(canStartBackgroundWork(state, { trigger: 'manual', now: 1_001 }), true);
+
+  state = beginBackgroundWork(state, { trigger: 'automatic', now: 1_100 }).state;
+  state = recordBackgroundWorkFailure(state, { now: 1_100 }, policy);
+  assert.equal(state.failStreak, 2);
+  assert.equal(state.nextEligibleAt, 1_300);
+
+  state = beginBackgroundWork(state, { trigger: 'automatic', now: 1_300 }).state;
+  state = recordBackgroundWorkFailure(state, { now: 1_300 }, policy);
+  state = beginBackgroundWork(state, { trigger: 'automatic', now: 1_700 }).state;
+  state = recordBackgroundWorkFailure(state, { now: 1_700 }, policy);
+  assert.equal(state.failStreak, 4);
+  assert.equal(state.nextEligibleAt, 2_100, 'backoff is capped by failureMaxMs');
+});
+
+test('an attempt with no progress cools down instead of hot-looping', () => {
+  const initial = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'hourly-history',
+    now: 10,
+    progress: emptyProgress,
+  });
+  const running = beginBackgroundWork(initial, { trigger: 'automatic', now: 10 }).state;
+  const noProgress = recordBackgroundWorkProgress(running, {
+    now: 20,
+    complete: false,
+    progress: emptyProgress,
+  }, policy);
+
+  assert.equal(noProgress.status, 'cooldown');
+  assert.equal(noProgress.pausedReason, 'no-progress');
+  assert.equal(noProgress.nextEligibleAt, 270);
+  assert.equal(noProgress.failStreak, 0, 'no-progress is distinct from an execution failure');
+  assert.equal(canStartBackgroundWork(noProgress, { trigger: 'automatic', now: 269 }), false);
+  assert.equal(canStartBackgroundWork(noProgress, { trigger: 'manual', now: 21 }), true);
+});
+
+test('a user pause can only be resumed by a manual trigger', () => {
+  const initial = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'period-migration',
+    now: 1,
+  });
+  const paused = pauseBackgroundWork(initial, { now: 2 });
+
+  assert.equal(paused.status, 'paused');
+  assert.equal(paused.pausedReason, 'user');
+  assert.equal(canStartBackgroundWork(paused, { trigger: 'automatic', now: 10_000 }), false);
+
+  const automatic = beginBackgroundWork(paused, { trigger: 'automatic', now: 10_000 });
+  assert.equal(automatic.started, false);
+  assert.equal(automatic.state, paused);
+
+  const manual = beginBackgroundWork(paused, { trigger: 'manual', now: 3, reason: 'resume' });
+  assert.equal(manual.started, true);
+  assert.equal(manual.state.status, 'running');
+  assert.equal(manual.state.pausedReason, null);
+  assert.equal(manual.state.reason, 'resume');
+});
+
+test('an interrupted running attempt resumes without counting as a failure', () => {
+  const initial = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'first-index',
+    now: 10,
+    progress: emptyProgress,
+  });
+  const running = beginBackgroundWork(initial, {
+    trigger: 'automatic',
+    now: 10,
+  }).state;
+  const interrupted = interruptBackgroundWork(running, { now: 20 });
+
+  assert.equal(interrupted.status, 'eligible');
+  assert.equal(interrupted.reason, 'resume');
+  assert.equal(interrupted.failStreak, 0);
+  assert.equal(interrupted.nextEligibleAt, 20);
+  assert.equal(interrupted.pausedReason, null);
+  assert.equal(canStartBackgroundWork(interrupted, {
+    trigger: 'automatic',
+    now: 20,
+  }), true);
+});
+
+test('complete work stays complete for the same measurement version', () => {
+  const initial = createBackgroundWorkState({
+    measurementVersion: 4,
+    reason: 'first-index',
+    now: 100,
+    progress: emptyProgress,
+  });
+  const running = beginBackgroundWork(initial, { trigger: 'automatic', now: 100 }).state;
+  const complete = recordBackgroundWorkProgress(running, {
+    now: 110,
+    complete: true,
+    progress: {
+      completedUnits: 5,
+      totalUnits: 5,
+      completedBytes: 50,
+      totalBytes: 50,
+    },
+  }, policy);
+
+  assert.equal(complete.status, 'complete');
+  assert.equal(complete.nextEligibleAt, null);
+  assert.equal(canStartBackgroundWork(complete, { trigger: 'manual', now: 1_000 }), false);
+
+  const sameVersion = restoreBackgroundWorkState(JSON.parse(JSON.stringify(complete)), {
+    measurementVersion: 4,
+    reason: 'first-index',
+    now: 1_000,
+  });
+  assert.equal(sameVersion.disposition, 'valid');
+  assert.equal(sameVersion.state.status, 'complete');
+  assert.equal(canStartBackgroundWork(sameVersion.state, { trigger: 'automatic', now: 1_000 }), false);
+
+  const changedVersion = restoreBackgroundWorkState(complete, {
+    measurementVersion: 5,
+    reason: 'parser-migration',
+    now: 1_000,
+  });
+  assert.equal(changedVersion.disposition, 'measurement-changed');
+  assert.equal(changedVersion.state.status, 'eligible');
+  assert.equal(changedVersion.state.measurementVersion, 5);
+  assert.deepEqual(changedVersion.state.progress, {
+    completedUnits: 0,
+    totalUnits: 0,
+    completedBytes: 0,
+    totalBytes: 0,
+  });
+});
+
+test('completion cannot cross an independent index generation', () => {
+  const initial = createBackgroundWorkState({
+    measurementVersion: 4,
+    reason: 'history-backfill',
+    now: 100,
+    indexGeneration: 7,
+    progress: emptyProgress,
+  });
+  const running = beginBackgroundWork(initial, { trigger: 'automatic', now: 100 }).state;
+  const complete = recordBackgroundWorkProgress(running, {
+    now: 110,
+    complete: true,
+    progress: { completedUnits: 5, totalUnits: 5, completedBytes: 50, totalBytes: 50 },
+  }, policy);
+  assert.equal(complete.indexGeneration, 7);
+
+  const sameGeneration = restoreBackgroundWorkState(JSON.parse(JSON.stringify(complete)), {
+    measurementVersion: 4,
+    reason: 'history-backfill',
+    now: 200,
+    indexGeneration: 7,
+  });
+  assert.equal(sameGeneration.disposition, 'valid');
+  assert.equal(sameGeneration.state.status, 'complete');
+
+  const changedGeneration = restoreBackgroundWorkState(JSON.parse(JSON.stringify(complete)), {
+    measurementVersion: 4,
+    reason: 'history-backfill',
+    now: 200,
+    indexGeneration: 8,
+  });
+  assert.equal(changedGeneration.disposition, 'generation-changed');
+  assert.equal(changedGeneration.state.status, 'eligible');
+  assert.equal(changedGeneration.state.indexGeneration, 8);
+
+  const missingGeneration = restoreBackgroundWorkState(JSON.parse(JSON.stringify(complete)), {
+    measurementVersion: 4,
+    reason: 'history-backfill',
+    now: 200,
+  });
+  assert.equal(missingGeneration.disposition, 'valid', 'legacy callers may restore before snapshot hydration');
+  assert.equal(missingGeneration.state.indexGeneration, 7);
+});
+
+test('missing state starts safely while corrupt or content-bearing state fails closed', () => {
+  const missing = restoreBackgroundWorkState(undefined, {
+    measurementVersion: 3,
+    reason: 'hourly-history',
+    now: 50,
+  });
+  assert.equal(missing.disposition, 'new');
+  assert.equal(missing.state.status, 'eligible');
+
+  const unsafe = {
+    schemaVersion: BACKGROUND_WORK_STATE_SCHEMA_VERSION,
+    measurementVersion: 3,
+    status: 'eligible',
+    reason: 'hourly-history',
+    progress: {
+      completedUnits: 0,
+      totalUnits: 0,
+      completedBytes: 0,
+      totalBytes: 0,
+    },
+    failStreak: 0,
+    nextEligibleAt: 50,
+    pausedReason: null,
+    updatedAt: 50,
+    path: '/Users/alice/.codex/sessions/private.jsonl',
+  };
+  const corrupt = restoreBackgroundWorkState(unsafe, {
+    measurementVersion: 3,
+    reason: 'hourly-history',
+    now: 60,
+  });
+
+  assert.equal(corrupt.disposition, 'corrupt');
+  assert.equal(corrupt.state.status, 'paused');
+  assert.equal(corrupt.state.pausedReason, 'corrupt-state');
+  assert.equal(canStartBackgroundWork(corrupt.state, { trigger: 'manual', now: 61 }), false);
+  assert.doesNotMatch(JSON.stringify(corrupt.state), /alice|private|path|session/i);
+
+  const invalidNumber = restoreBackgroundWorkState({ ...unsafe, path: undefined, failStreak: -1 }, {
+    measurementVersion: 3,
+    reason: 'hourly-history',
+    now: 60,
+  });
+  assert.equal(invalidNumber.disposition, 'corrupt');
+});
diff --git a/src/test/claudeApiClient.test.ts b/src/test/claudeApiClient.test.ts
index 139d342d..de226e2d 100644
--- a/src/test/claudeApiClient.test.ts
+++ b/src/test/claudeApiClient.test.ts
@@ -27,7 +27,11 @@ function loadApiModule(): ApiModule {
   }
 }
 
-const { ClaudeApiClient, resolveClaudeProfile } = loadApiModule();
+const {
+  ClaudeApiClient,
+  claudeQuotaIdentitySignal,
+  resolveClaudeProfile,
+} = loadApiModule();
 const tempRoots: string[] = [];
 
 after(() => {
@@ -68,6 +72,43 @@ test('the default profile retains the macOS Keychain fallback', () => {
   assert.equal(resolved.allowKeychainFallback, true);
 });
 
+test('quota identity follows refresh-token continuity without exposing the token', () => {
+  const first = claudeQuotaIdentitySignal('machine-salt', 'refresh-token-a');
+  const repeated = claudeQuotaIdentitySignal('machine-salt', 'refresh-token-a');
+  const rotated = claudeQuotaIdentitySignal('machine-salt', 'refresh-token-b');
+
+  assert.equal(first, repeated);
+  assert.notEqual(first, rotated);
+  assert.equal(first.includes('refresh-token-a'), false);
+});
+
+test('successful quota fetch records only the safe account continuity signal', async () => {
+  const client = new ClaudeApiClient(null, undefined, 'machine-salt') as any;
+  client.getValidCredentials = async () => ({
+    claudeAiOauth: {
+      accessToken: 'access-token',
+      refreshToken: 'refresh-token',
+      expiresAt: Date.now() + 60_000,
+    },
+  });
+  client.callUsageApi = async () => ({
+    status: 200,
+    body: JSON.stringify({
+      seven_day: {
+        utilization: 25,
+        resets_at: '2026-09-07T03:24:00.000Z',
+      },
+    }),
+  });
+
+  assert.ok(await client.fetchUsageLimits());
+  assert.equal(
+    client.getLastQuotaIdentitySignal(),
+    claudeQuotaIdentitySignal('machine-salt', 'refresh-token'),
+  );
+  assert.equal(client.getLastQuotaIdentitySignal().includes('refresh-token'), false);
+});
+
 test('a custom profile without a credentials file never falls back to Keychain', async () => {
   const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'ccu-claude-profile-'));
   tempRoots.push(profile);
@@ -101,3 +142,33 @@ test('refreshed credentials are written back to the selected profile', async ()
   const stored = JSON.parse(fs.readFileSync(path.join(profile, '.credentials.json'), 'utf8'));
   assert.deepEqual(stored, credentials);
 });
+
+test('quota fetch forwards caller cancellation through the active request', async () => {
+  const client = new ClaudeApiClient(null) as any;
+  const controller = new AbortController();
+  let observedSignal: AbortSignal | undefined;
+  client.getValidCredentials = async () => ({
+    claudeAiOauth: {
+      accessToken: 'test-access',
+      refreshToken: 'test-refresh',
+      expiresAt: Date.now() + 60_000,
+    },
+  });
+  client.callUsageApi = (_token: string, signal?: AbortSignal) =>
+    new Promise((_resolve, reject) => {
+      observedSignal = signal;
+      signal?.addEventListener(
+        'abort',
+        () => reject(new Error('Request cancelled')),
+        { once: true },
+      );
+    });
+
+  const pending = client.fetchUsageLimits(controller.signal);
+  await Promise.resolve();
+  controller.abort();
+
+  assert.equal(await pending, null);
+  assert.strictEqual(observedSignal, controller.signal);
+  assert.equal(observedSignal?.aborted, true);
+});
diff --git a/src/test/claudeIncrementalIndex.test.ts b/src/test/claudeIncrementalIndex.test.ts
index 63e4e573..98f0f270 100644
--- a/src/test/claudeIncrementalIndex.test.ts
+++ b/src/test/claudeIncrementalIndex.test.ts
@@ -18,6 +18,7 @@ import {
   updateClaudeUsageIndex,
 } from '../claudeIncrementalIndex';
 import { ClaudeDataLoader } from '../dataLoader';
+import { I18n } from '../i18n';
 import { ClaudeUsageRecord } from '../types';
 
 const roots: string[] = [];
@@ -250,6 +251,252 @@ test('materialized dashboard rows match every legacy full-record aggregation', a
   );
 });
 
+test('the dashboard middle scope is a rolling 30-day window across month boundaries', async () => {
+  const previousTimeZone = I18n.getTimezone();
+  I18n.setTimezone('UTC');
+  try {
+    const { root, first } = await fixture();
+    await appendFile(first, [
+      usageLine('rolling-boundary', 30, 12, {
+        timestamp: '2026-08-04T09:00:00.000Z',
+      }),
+      usageLine('rolling-outside', 40, 16, {
+        timestamp: '2026-08-03T09:00:00.000Z',
+      }),
+      '',
+    ].join('\n'), 'utf8');
+    const loaded = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
+      analyzeContent: false,
+    });
+    const snapshot = claudeUsageDashboardSnapshot(loaded.index, {
+      now: new Date('2026-09-02T12:00:00.000Z'),
+    });
+
+    assert.equal(snapshot.month.messageCount, 0);
+    assert.equal(snapshot.last30Days.messageCount, 1);
+    assert.equal(snapshot.last30Days.totalInputTokens, 60);
+    assert.equal(snapshot.last30Days.totalOutputTokens, 24);
+    assert.deepEqual(
+      snapshot.dailyForLast30Days.map((row) => row.date),
+      ['2026-08-21', '2026-08-04'],
+    );
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
+test('Today and rolling 30 days share the configured local-day map across DST', async () => {
+  const previousTimeZone = I18n.getTimezone();
+  I18n.setTimezone('America/Los_Angeles');
+  try {
+    const { root, first, second } = await fixture();
+    await writeFile(first, [
+      usageLine('dst-today', 10, 1, { timestamp: '2026-11-02T08:30:00.000Z' }),
+      usageLine('dst-transition-day', 20, 2, { timestamp: '2026-11-01T07:30:00.000Z' }),
+      usageLine('rolling-first-day', 30, 3, { timestamp: '2026-10-04T07:30:00.000Z' }),
+      usageLine('rolling-outside', 40, 4, { timestamp: '2026-10-04T06:30:00.000Z' }),
+      '',
+    ].join('\n'), 'utf8');
+    await unlink(second);
+
+    const loaded = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
+      analyzeContent: false,
+    });
+    const bodyReads = loaded.diagnostics.bodyReads;
+    const snapshot = claudeUsageDashboardSnapshot(loaded.index, {
+      now: new Date('2026-11-02T12:00:00.000Z'),
+    });
+
+    assert.deepEqual(
+      snapshot.dailyForLast30Days.map((row) => row.date),
+      ['2026-11-02', '2026-11-01', '2026-10-04'],
+    );
+    assert.equal(snapshot.today.totalInputTokens, 10);
+    assert.equal(snapshot.last30Days.totalInputTokens, 60);
+    assert.equal(snapshot.allTime.totalInputTokens, 100);
+    assert.deepEqual(
+      stableValue(snapshot.dailyForLast30Days.find((row) => row.date === '2026-11-02')?.data),
+      stableValue(snapshot.today),
+    );
+    for (const field of [
+      'messageCount',
+      'totalInputTokens',
+      'totalOutputTokens',
+      'totalCacheCreationTokens',
+      'totalCacheReadTokens',
+      'totalCost',
+    ] as const) {
+      assert.ok(snapshot.today[field] <= snapshot.last30Days[field], `${field}: Today <= 30 days`);
+      assert.ok(snapshot.last30Days[field] <= snapshot.allTime[field], `${field}: 30 days <= all time`);
+    }
+    assert.equal(loaded.diagnostics.bodyReads, bodyReads, 'snapshot materialization performs no extra reads');
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
+test('advice window is opt-in and comes only from materialized day and session aggregates', async () => {
+  const { root, first } = await fixture();
+  await writeFile(
+    path.join(path.dirname(first), 'session-old.jsonl'),
+    `${usageLine('old-advice', 999, 99, { timestamp: '2026-06-01T08:00:00.000Z' })}\n`,
+    'utf8',
+  );
+  const loaded = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
+    analyzeContent: false,
+  });
+  const ordinary = claudeUsageDashboardSnapshot(loaded.index, {
+    now: new Date('2026-08-22T12:00:00.000Z'),
+  });
+  assert.equal(ordinary.adviceWindow, undefined);
+
+  const candidate = claudeUsageDashboardSnapshot(loaded.index, {
+    now: new Date('2026-08-22T12:00:00.000Z'),
+    adviceWindowDays: 30,
+  });
+  assert.equal(candidate.adviceWindow?.aggregate.messageCount, 1);
+  assert.equal(candidate.adviceWindow?.aggregate.totalInputTokens, 30);
+  assert.equal(candidate.adviceWindow?.totalSessions, 2);
+  assert.equal(candidate.adviceWindow?.longSessionCount, 0);
+  assert.equal(candidate.adviceWindow?.largeContextSessionCount, 0);
+  assert.equal(loaded.diagnostics.bodyReads, 3, 'snapshot materialization performs no extra reads');
+});
+
+test('configured timezone rebuckets Claude Today and hours from the in-memory index without body reads', async () => {
+  const previousTimeZone = I18n.getTimezone();
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-claude-timezone-index-'));
+  roots.push(root);
+  const project = path.join(root, 'projects', '-fixture-timezone');
+  await mkdir(project, { recursive: true });
+  const file = path.join(project, 'timezone.jsonl');
+  await writeFile(file, `${usageLine('timezone', 10, 2, {
+    timestamp: '2026-07-20T23:30:00.000Z',
+  })}\n`, 'utf8');
+
+  try {
+    I18n.setTimezone('UTC');
+    const cold = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
+      analyzeContent: false,
+    });
+    const utc = claudeUsageDashboardSnapshot(cold.index, {
+      now: new Date('2026-07-21T00:15:00.000Z'),
+    });
+    assert.equal(utc.today.totalInputTokens, 0);
+    assert.deepEqual(utc.hourlyForToday, []);
+
+    I18n.setTimezone('Asia/Hong_Kong');
+    const shifted = await updateClaudeUsageIndex(cold.index, root, {
+      analyzeContent: false,
+    });
+    const hongKong = claudeUsageDashboardSnapshot(shifted.index, {
+      now: new Date('2026-07-21T00:15:00.000Z'),
+    });
+
+    assert.equal(shifted.diagnostics.bodyReads, 0);
+    assert.equal(hongKong.today.totalInputTokens, 10);
+    assert.deepEqual(hongKong.hourlyForToday.map(({ hour }) => hour), ['07:00']);
+    assert.deepEqual(
+      ClaudeDataLoader.getHourlyDataForDate(shifted.records, '2026-07-21')
+        .map(({ hour }) => hour),
+      ['07:00'],
+    );
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
+test('nested Claude subagent logs feed Today and rolling 30 days exactly once', async () => {
+  const previousTimeZone = I18n.getTimezone();
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-claude-subagent-index-'));
+  roots.push(root);
+  const project = path.join(root, 'projects', '-fixture-subagent');
+  const subagents = path.join(project, 'session-root', 'subagents');
+  await mkdir(subagents, { recursive: true });
+  await writeFile(
+    path.join(project, 'session-root.jsonl'),
+    `${usageLine('root', 10, 2, { timestamp: '2026-08-21T08:00:00.000Z' })}\n`,
+    'utf8',
+  );
+  const subagentFile = path.join(subagents, 'agent-review.jsonl');
+  await writeFile(
+    subagentFile,
+    `${usageLine('subagent', 20, 4, { timestamp: '2026-08-21T09:00:00.000Z' })}\n`,
+    'utf8',
+  );
+
+  try {
+    I18n.setTimezone('UTC');
+    const cold = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
+      analyzeContent: false,
+    });
+    const first = claudeUsageDashboardSnapshot(cold.index, {
+      now: new Date('2026-08-21T12:00:00.000Z'),
+    });
+
+    assert.equal(cold.diagnostics.bodyReads, 2);
+    assert.equal(cold.records.filter((record) => record._agentId === 'agent-review').length, 1);
+    assert.equal(first.today.totalInputTokens, 30);
+    assert.equal(first.last30Days.totalInputTokens, 30);
+    assert.equal(first.allTime.totalInputTokens, 30);
+    assert.equal(first.sessions.reduce((sum, session) => sum + session.data.totalInputTokens, 0), 30);
+
+    const unchanged = await updateClaudeUsageIndex(cold.index, root, {
+      analyzeContent: false,
+    });
+    const unchangedSnapshot = claudeUsageDashboardSnapshot(unchanged.index, {
+      now: new Date('2026-08-21T12:00:00.000Z'),
+    });
+    assert.equal(unchanged.diagnostics.bodyReads, 0);
+    assert.equal(unchangedSnapshot.today.totalInputTokens, 30);
+
+    await appendFile(
+      subagentFile,
+      `${usageLine('subagent-tail', 7, 1, { timestamp: '2026-08-21T10:00:00.000Z' })}\n`,
+      'utf8',
+    );
+    const appended = await updateClaudeUsageIndex(unchanged.index, root, {
+      analyzeContent: false,
+    });
+    const appendedSnapshot = claudeUsageDashboardSnapshot(appended.index, {
+      now: new Date('2026-08-21T12:00:00.000Z'),
+    });
+    assert.equal(appended.diagnostics.bodyReads, 1);
+    assert.equal(appendedSnapshot.today.totalInputTokens, 37);
+    assert.equal(appendedSnapshot.last30Days.totalInputTokens, 37);
+    assert.equal(appendedSnapshot.allTime.totalInputTokens, 37);
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
+test('hourly materialization is limited to the recent 30-day window while day and month stay all-time', async () => {
+  const previousTimeZone = I18n.getTimezone();
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-claude-hour-window-'));
+  roots.push(root);
+  const project = path.join(root, 'projects', '-fixture-hour-window');
+  await mkdir(project, { recursive: true });
+  const now = Date.now();
+  const oldTimestamp = new Date(now - 45 * 24 * 60 * 60 * 1000).toISOString();
+  const recentTimestamp = new Date(now - 5 * 24 * 60 * 60 * 1000).toISOString();
+  await writeFile(path.join(project, 'window.jsonl'), [
+    usageLine('old', 10, 1, { timestamp: oldTimestamp }),
+    usageLine('recent', 20, 2, { timestamp: recentTimestamp }),
+    '',
+  ].join('\n'), 'utf8');
+  try {
+    I18n.setTimezone('UTC');
+    const loaded = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
+      analyzeContent: false,
+    });
+    assert.equal(loaded.index.aggregates.byDay.size, 2);
+    assert.equal(loaded.index.aggregates.byMonth.size >= 1, true);
+    assert.equal([...loaded.index.aggregates.byLocalHour.keys()].some((key) => key.startsWith(oldTimestamp.slice(0, 10))), false);
+    assert.equal([...loaded.index.aggregates.byLocalHour.keys()].some((key) => key.startsWith(recentTimestamp.slice(0, 10))), true);
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
 test('append reads only the verified tail and preserves exact totals', async () => {
   const { root, first } = await fixture();
   const cold = await updateClaudeUsageIndex(createClaudeUsageIndex(), root, {
diff --git a/src/test/codexDedup.test.ts b/src/test/codexDedup.test.ts
index 90100e3e..6444d531 100644
--- a/src/test/codexDedup.test.ts
+++ b/src/test/codexDedup.test.ts
@@ -102,6 +102,39 @@ test('a token-total mismatch retains both copies as one ambiguous group', () =>
   assert.equal(ambiguous.exactDuplicateFileKeys.size, 0);
 });
 
+test('equal totals with different authoritative day distributions are not exact duplicates', () => {
+  const active = contribution('active-key', 'sessions');
+  const archive = contribution('archive-key', 'archive');
+  active.aggregate.byDay = {
+    '2026-08-30': { ...active.aggregate.total },
+  };
+  archive.aggregate.byDay = {
+    '2026-08-31': { ...archive.aggregate.total },
+  };
+
+  const result = classify(active, archive);
+
+  assert.equal(result.ambiguousSessionGroups, 1);
+  assert.deepEqual([...result.canonicalFileKeys], ['active-key', 'archive-key']);
+  assert.equal(result.exactDuplicateFileKeys.size, 0);
+});
+
+test('a one-sided rebuilding period projection does not destabilize exact dedup', () => {
+  const active = contribution('active-key', 'sessions');
+  const archive = contribution('archive-key', 'archive');
+  active.aggregate.period = {
+    timeZone: 'Asia/Shanghai',
+    indexedThrough: 50,
+    days: {},
+  };
+
+  const result = classify(active, archive);
+
+  assert.deepEqual([...result.canonicalFileKeys], ['active-key']);
+  assert.deepEqual([...result.exactDuplicateFileKeys], ['archive-key']);
+  assert.equal(result.ambiguousSessionGroups, 0);
+});
+
 test('a missing optional token field does not equal an explicit zero', () => {
   const active = contribution('active-key', 'sessions');
   const archive = contribution('archive-key', 'archive');
diff --git a/src/test/codexIdentity.test.ts b/src/test/codexIdentity.test.ts
index 1b260412..7ac106a0 100644
--- a/src/test/codexIdentity.test.ts
+++ b/src/test/codexIdentity.test.ts
@@ -107,6 +107,31 @@ test('session index keeps the latest clean title behind an anonymous key', async
   }
 });
 
+test('thread titles mask absolute paths glued to a bare colon or punctuation', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-title-colon-'));
+  try {
+    await writeFile(
+      path.join(root, 'session_index.jsonl'),
+      [
+        JSON.stringify({ id: 'raw-session-g', thread_name: '3:/Users/carl' }),
+        JSON.stringify({ id: 'raw-session-h', thread_name: '3:/etc/passwd' }),
+        JSON.stringify({ id: 'raw-session-i', thread_name: ':/etc/passwd' }),
+      ].join('\n'),
+      'utf8',
+    );
+
+    const titles = await loadCodexSessionTitles(root, SALT);
+
+    for (const id of ['raw-session-g', 'raw-session-h', 'raw-session-i']) {
+      const title = titles.get(pseudonymousIdentityKey(SALT, id)) ?? '';
+      assert.match(title, /\[path\]/);
+      assert.doesNotMatch(title, /\/Users\/carl|\/etc\/passwd/);
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('session title loading rejects a symlinked metadata file', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-title-link-'));
   const outside = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-title-out-'));
diff --git a/src/test/codexIndex.test.ts b/src/test/codexIndex.test.ts
index e6596180..71cb1536 100644
--- a/src/test/codexIndex.test.ts
+++ b/src/test/codexIndex.test.ts
@@ -31,7 +31,10 @@ import {
   CodexRuntimeManifestEntry,
   scanCodexManifest,
 } from '../providers/codex/codexManifest';
-import { CodexFilePassPool } from '../providers/codex/codexFilePassPool';
+import {
+  CodexFilePassPool,
+  CodexFilePassWorkerLike,
+} from '../providers/codex/codexFilePassPool';
 import { pseudonymousIdentityKey } from '../providers/codex/codexIdentity';
 import { parseCodexLine } from '../providers/codex/codexParser';
 
@@ -47,7 +50,8 @@ test('corrupt index trailing data is preserved and rebuilt from an empty index',
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-corrupt-'));
   try {
     const indexPath = path.join(root, 'codex-index.json');
-    const original = `${JSON.stringify(createEmptyCodexIndex('UTC'))},"cachedInput":1}`;
+    const originalIndex = createEmptyCodexIndex('UTC');
+    const original = `${JSON.stringify(originalIndex)},"cachedInput":1}`;
     const recoveries: Array<{ reason: string }> = [];
     await writeFile(indexPath, original, 'utf8');
 
@@ -58,6 +62,7 @@ test('corrupt index trailing data is preserved and rebuilt from an empty index',
     );
 
     assert.equal(loaded.schemaVersion, 3);
+    assert.notEqual(loaded.indexGeneration, originalIndex.indexGeneration);
     assert.equal(loaded.coverage.period.timeZone, 'Asia/Hong_Kong');
     assert.deepEqual(recoveries, [{ reason: 'invalid-json' }]);
     await assert.rejects(readFile(indexPath, 'utf8'), { code: 'ENOENT' });
@@ -84,6 +89,7 @@ test('unsupported index schema is quarantined with its distinct recovery reason'
     );
 
     assert.equal(loaded.schemaVersion, 3);
+    assert.ok((loaded.indexGeneration ?? 0) > 1);
     assert.deepEqual(recoveries, [{ reason: 'unsupported-schema' }]);
     const backups = await corruptIndexBackups(root);
     assert.equal(backups.length, 1);
@@ -116,6 +122,23 @@ test('valid and missing indexes do not report recovery while I/O errors still fa
   }
 });
 
+test('timezone migration advances the independent index generation', async () => {
+  const initial = createEmptyCodexIndex('UTC');
+  assert.equal(initial.indexGeneration, 1);
+  const updated = await updateCodexIndexRaw(initial, persistableManifest([]), {
+    salt: SALT,
+    timeZone: 'Asia/Hong_Kong',
+    now: () => Date.parse('2026-08-30T00:00:00.000Z'),
+  });
+  assert.equal(updated.index.indexGeneration, 2);
+  const warm = await updateCodexIndexRaw(updated.index, persistableManifest([]), {
+    salt: SALT,
+    timeZone: 'Asia/Hong_Kong',
+    now: () => Date.parse('2026-08-30T00:00:00.000Z'),
+  });
+  assert.equal(warm.index.indexGeneration, 2);
+});
+
 test('concurrent atomic saves use independent temporary files', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-concurrent-save-'));
   try {
@@ -159,7 +182,7 @@ test('schema-3 reload preserves only bounded pseudonymous replay evidence', asyn
     const index = createEmptyCodexIndex('UTC');
     const contribution = dedupContribution(fileKey, 'sessions');
     contribution.parserState = {
-      schemaVersion: 3,
+      schemaVersion: 4,
       fileKey,
       sessionKey: fileKey,
       role: 'root',
@@ -192,7 +215,7 @@ test('schema-3 reload preserves only bounded pseudonymous replay evidence', asyn
     const replayState = loaded.files[fileKey].parserState;
     const savedSources = Object.keys(replayState.snapshotSignaturesBySource ?? {});
 
-    assert.equal(replayState.schemaVersion, 3);
+    assert.equal(replayState.schemaVersion, 4);
     assert.equal(savedSources.length, 32);
     assert.ok(savedSources.includes(sourceKey));
     assert.equal(savedSources.includes('raw-account@example.invalid'), false);
@@ -238,7 +261,7 @@ test('schema-3 reload preserves only bounded pseudonymous replay evidence', asyn
   }
 });
 
-test('schema-3 index with pre-last-usage parser state requests one rescan', async () => {
+test('schema-3 index with v2.3.0 parser semantics requests one rescan', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-token-migration-'));
   try {
     const indexPath = path.join(root, 'codex-index.json');
@@ -247,7 +270,7 @@ test('schema-3 index with pre-last-usage parser state requests one rescan', asyn
     const contribution = dedupContribution(fileKey, 'sessions');
     contribution.parserState = {
       ...contribution.parserState,
-      schemaVersion: 2,
+      schemaVersion: 3,
       fileKey,
       sessionKey: fileKey,
     };
@@ -311,7 +334,7 @@ test('token semantics rescan preserves completed files across a partial checkpoi
     for (const contribution of Object.values(legacy.files)) {
       contribution.parserState = {
         ...contribution.parserState,
-        schemaVersion: 2,
+        schemaVersion: 3,
       };
     }
     await writeFile(indexPath, JSON.stringify(legacy), 'utf8');
@@ -454,7 +477,7 @@ test('index load and save fail closed for unsafe metadata labels and bucket keys
       offset: 100,
       discardingOversizedLine: false,
       parserState: {
-        schemaVersion: 3,
+        schemaVersion: 4,
         fileKey,
         sessionKey,
         agentNickname: unsafe.posix,
@@ -723,6 +746,39 @@ function tokenLine(input: number, output: number, timestamp: string): string {
   });
 }
 
+function tokenLineWithWeeklyLimit(
+  input: number,
+  output: number,
+  timestamp: string,
+  resetAt: string,
+  usedPercent: number,
+): string {
+  return JSON.stringify({
+    timestamp,
+    type: 'event_msg',
+    payload: {
+      type: 'token_count',
+      info: {
+        total_token_usage: {
+          input_tokens: input,
+          cached_input_tokens: Math.floor(input / 2),
+          output_tokens: output,
+          reasoning_output_tokens: Math.floor(output / 2),
+          total_tokens: input + output,
+        },
+      },
+      rate_limits: {
+        limit_id: 'codex',
+        secondary: {
+          used_percent: usedPercent,
+          window_minutes: 7 * 24 * 60,
+          resets_at: resetAt,
+        },
+      },
+    },
+  });
+}
+
 function structuralLine(
   timestamp: string,
   type: 'event_msg' | 'response_item',
@@ -775,6 +831,153 @@ function chunkingIo(chunkBytes: number): CodexIndexIo {
   };
 }
 
+test('weekly quota history retains separate resets after the source file is removed', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-quota-history-'));
+  try {
+    const indexPath = path.join(root, 'codex-index.json');
+    const sessions = path.join(root, 'sessions');
+    await mkdir(sessions, { recursive: true });
+    await writeFile(
+      path.join(sessions, 'quota-history.jsonl'),
+      [
+        sessionLine('quota-history'),
+        contextLine(),
+        tokenLineWithWeeklyLimit(
+          100,
+          20,
+          '2026-08-28T08:00:00.000Z',
+          '2026-08-28T11:00:00.000Z',
+          18,
+        ),
+        tokenLineWithWeeklyLimit(
+          200,
+          40,
+          '2026-08-30T04:00:00.000Z',
+          '2026-08-30T07:00:00.000Z',
+          42,
+        ),
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+    const manifest = await scanCodexManifest(root, SALT);
+    const now = Date.parse('2026-08-31T12:00:00.000Z');
+    const cold = await updateCodexIndex(createEmptyCodexIndex('UTC'), manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => now,
+    });
+
+    assert.deepEqual(
+      cold.index.quotaHistory?.map(({ resetAt, usedPercent }) => ({ resetAt, usedPercent })),
+      [
+        { resetAt: Date.parse('2026-08-28T11:00:00.000Z'), usedPercent: 18 },
+        { resetAt: Date.parse('2026-08-30T07:00:00.000Z'), usedPercent: 42 },
+      ],
+    );
+
+    await saveCodexIndexAtomic(indexPath, {
+      ...cold.index,
+      quotaHistory: cold.index.quotaHistory?.map((observation) => ({
+        ...observation,
+        account: 'must-not-persist',
+      })) as any,
+    });
+    const reloaded = await loadCodexIndex(indexPath, 'UTC');
+    assert.deepEqual(
+      reloaded.quotaHistory?.map(({ resetAt, usedPercent }) => ({ resetAt, usedPercent })),
+      [
+        { resetAt: Date.parse('2026-08-28T11:00:00.000Z'), usedPercent: 18 },
+        { resetAt: Date.parse('2026-08-30T07:00:00.000Z'), usedPercent: 42 },
+      ],
+    );
+    assert.doesNotMatch(await readFile(indexPath, 'utf8'), /must-not-persist/);
+
+    const removed = await updateCodexIndex(
+      reloaded,
+      persistableManifest([]),
+      { salt: SALT, timeZone: 'UTC', now: () => now },
+    );
+    assert.equal(removed.bodyReads, 0);
+    assert.deepEqual(
+      removed.index.quotaHistory?.map(({ resetAt, usedPercent }) => ({ resetAt, usedPercent })),
+      [
+        { resetAt: Date.parse('2026-08-28T11:00:00.000Z'), usedPercent: 18 },
+        { resetAt: Date.parse('2026-08-30T07:00:00.000Z'), usedPercent: 42 },
+      ],
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('legacy indexed quota projections seed reset history once without rereading bodies', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-quota-seed-'));
+  try {
+    const sessions = path.join(root, 'sessions');
+    await mkdir(sessions, { recursive: true });
+    await writeFile(
+      path.join(sessions, 'quota-seed.jsonl'),
+      [
+        sessionLine('quota-seed'),
+        contextLine(),
+        tokenLineWithWeeklyLimit(
+          100,
+          20,
+          '2026-08-30T04:00:00.000Z',
+          '2026-08-30T07:00:00.000Z',
+          42,
+        ),
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+    const manifest = await scanCodexManifest(root, SALT);
+    const now = Date.parse('2026-08-31T12:00:00.000Z');
+    const cold = await updateCodexIndex(createEmptyCodexIndex('UTC'), manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => now,
+    });
+    const legacy = structuredClone(cold.index);
+    delete legacy.quotaHistory;
+    for (const contribution of Object.values(legacy.files)) {
+      // Model an older complete schema-3 index: it has the last observed
+      // limit projection, but predates the neutral reset-history cache.
+      delete contribution.quotaHistory;
+    }
+
+    const io = trackingIo();
+    const seeded = await updateCodexIndex(legacy, manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => now,
+      io,
+    });
+
+    assert.equal(seeded.bodyReads, 0);
+    assert.equal(io.bodyReads.size, 0);
+    assert.deepEqual(
+      seeded.index.quotaHistory?.map(({ resetAt, usedPercent }) => ({ resetAt, usedPercent })),
+      [{ resetAt: Date.parse('2026-08-30T07:00:00.000Z'), usedPercent: 42 }],
+    );
+    assert.equal(seeded.indexChanged, true);
+
+    const warmIo = trackingIo();
+    const warm = await updateCodexIndex(seeded.index, manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => now,
+      io: warmIo,
+    });
+    assert.equal(warm.indexChanged, false);
+    assert.equal(warm.bodyReads, 0);
+    assert.equal(warmIo.bodyReads.size, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('fully indexed unchanged corpus returns a warm no-op without body reads', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-noop-'));
   try {
@@ -877,20 +1080,154 @@ test('cold and append scans maintain a sparse exact current-day hourly sidecar',
       total: { inputTotal: 999, rawResponse: 'today-secret-hour' },
       byModel: {},
     };
+    caller.files[key].aggregate.today.days['2026-07-21']['02'].total.promptBody =
+      'rolling-secret-total';
+    caller.files[key].aggregate.today.days.notADay = {
+      '02': {
+        total: { inputTotal: 999, rawResponse: 'rolling-secret-day' },
+        byModel: {},
+      },
+    };
     await saveCodexIndexAtomic(indexPath, caller);
     const persisted = await readFile(indexPath, 'utf8');
-    assert.doesNotMatch(persisted, /today-secret/);
+    assert.doesNotMatch(persisted, /today-secret|rolling-secret/);
     const reloaded = await loadCodexIndex(indexPath, 'Asia/Hong_Kong');
     assert.equal(reloaded.files[key].aggregate.today?.day, '2026-07-21');
+    assert.equal(reloaded.files[key].aggregate.today?.windowDays, 30);
     assert.deepEqual(Object.keys(reloaded.files[key].aggregate.today!.hours), ['00', '02']);
+    assert.deepEqual(
+      Object.keys(reloaded.files[key].aggregate.today?.days ?? {}),
+      ['2026-07-21'],
+    );
     assert.equal(reloaded.files[key].aggregate.today?.hours['02'].total.inputTotal, 50);
     assert.equal((reloaded.files[key].aggregate.today?.hours['02'] as any).byEffort, undefined);
+    const reloadIo = trackingIo();
+    const warmReload = await updateCodexIndex(reloaded, await scanCodexManifest(root, SALT), {
+      salt: SALT,
+      timeZone: 'Asia/Hong_Kong',
+      now: () => now,
+      io: reloadIo,
+    });
+    assert.equal(warmReload.bodyReads, 0);
+    assert.equal(reloadIo.bodyReads.size, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('rolling hourly sidecar keeps 30 configured-zone days and evicts day 31 without rereading JSONL', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-rolling-hours-'));
+  try {
+    const sessions = path.join(root, 'sessions');
+    await mkdir(sessions, { recursive: true });
+    await writeFile(
+      path.join(sessions, 'rolling-hours.jsonl'),
+      [
+        tokenLine(100, 20, '2026-06-30T08:05:00.000Z'),
+        tokenLine(200, 40, '2026-07-01T09:05:00.000Z'),
+        tokenLine(300, 60, '2026-07-15T10:05:00.000Z'),
+        tokenLine(400, 80, '2026-07-30T11:05:00.000Z'),
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+    const manifest = await scanCodexManifest(root, SALT);
+    const first = await updateCodexIndex(createEmptyCodexIndex('UTC'), manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => Date.parse('2026-07-30T12:00:00.000Z'),
+    });
+    const key = manifest.files[0].fileKey;
+    const sidecar = first.index.files[key].aggregate.today!;
+
+    assert.equal(sidecar.windowDays, 30);
+    assert.deepEqual(Object.keys(sidecar.days ?? {}).sort(), [
+      '2026-07-01',
+      '2026-07-15',
+      '2026-07-30',
+    ]);
+    assert.equal(sidecar.days?.['2026-07-01']['09'].total.inputTotal, 100);
+    assert.equal(sidecar.days?.['2026-07-30']['11'].total.outputTotal, 20);
+    assert.equal(sidecar.days?.['2026-06-30'], undefined);
+    assert.equal(first.index.coverage.hourly?.complete, true);
+
+    const io = trackingIo();
+    const rolled = await updateCodexIndex(first.index, manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => Date.parse('2026-07-31T12:00:00.000Z'),
+      io,
+    });
+    const rolledSidecar = rolled.index.files[key].aggregate.today!;
+
+    assert.equal(rolled.bodyReads, 0);
+    assert.equal(io.bodyReads.size, 0);
+    assert.equal(rolledSidecar.day, '2026-07-31');
+    assert.deepEqual(Object.keys(rolledSidecar.days ?? {}).sort(), [
+      '2026-07-15',
+      '2026-07-30',
+    ]);
+    assert.deepEqual(rolledSidecar.hours, {});
+    assert.equal(rolled.index.coverage.hourly?.asOfDay, '2026-07-31');
+    assert.equal(rolled.index.coverage.hourly?.complete, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('legacy one-day schema-3 sidecars receive one targeted rolling migration', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-rolling-legacy-'));
+  try {
+    const now = Date.parse('2026-07-20T12:00:00.000Z');
+    const sessions = path.join(root, 'sessions');
+    await mkdir(sessions, { recursive: true });
+    await writeFile(
+      path.join(sessions, 'legacy-hours.jsonl'),
+      [
+        tokenLine(100, 20, '2026-07-05T08:00:00.000Z'),
+        tokenLine(200, 40, '2026-07-20T09:00:00.000Z'),
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+    const manifest = await scanCodexManifest(root, SALT);
+    const current = await updateCodexIndex(createEmptyCodexIndex('UTC'), manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => now,
+    });
+    const key = manifest.files[0].fileKey;
+    const legacy = structuredClone(current.index) as any;
+    const modern = legacy.files[key].aggregate.today;
+    legacy.files[key].aggregate.today = {
+      day: modern.day,
+      timeZone: modern.timeZone,
+      indexedThrough: modern.indexedThrough,
+      hours: modern.hours,
+    };
+    delete legacy.coverage.hourly;
+    const io = trackingIo();
+
+    const migrated = await updateCodexIndex(legacy, manifest, {
+      salt: SALT,
+      timeZone: 'UTC',
+      now: () => now,
+      io,
+    });
+
+    assert.deepEqual(io.fileKeysRead, [key]);
+    assert.equal(migrated.index.files[key].aggregate.today?.windowDays, 30);
+    assert.deepEqual(
+      Object.keys(migrated.index.files[key].aggregate.today?.days ?? {}).sort(),
+      ['2026-07-05', '2026-07-20'],
+    );
+    assert.equal(migrated.index.coverage.hourly?.complete, true);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
 });
 
-test('an old schema-3 index backfills today only from canonical files known to contain that day', async () => {
+test('an old schema-3 index targets canonical files that intersect the rolling hour window', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-today-targeted-'));
   try {
     const today = Date.parse('2026-07-21T04:00:00.000Z');
@@ -910,6 +1247,11 @@ test('an old schema-3 index backfills today only from canonical files known to c
       `${tokenLine(300, 60, '2026-07-19T18:05:00.000Z')}\n`,
       'utf8',
     );
+    await writeFile(
+      path.join(sessions, 'outside-window.jsonl'),
+      `${tokenLine(400, 80, '2026-06-01T18:05:00.000Z')}\n`,
+      'utf8',
+    );
     const manifest = await scanCodexManifest(root, SALT);
     const cold = await updateCodexIndex(createEmptyCodexIndex('Asia/Hong_Kong'), manifest, {
       salt: SALT,
@@ -932,17 +1274,29 @@ test('an old schema-3 index backfills today only from canonical files known to c
     const todayKeys = manifest.files.filter((entry) =>
       cold.index.files[entry.fileKey].aggregate.period?.days['2026-07-21']
     ).map((entry) => entry.fileKey);
-    const todayKey = io.fileKeysRead[0];
-    const oldKey = manifest.files.find((entry) =>
-      !cold.index.files[entry.fileKey].aggregate.period?.days['2026-07-21']
+    const todayKey = todayKeys.find((key) => io.bodyReads.has(key))!;
+    const recentKey = manifest.files.find((entry) =>
+      cold.index.files[entry.fileKey].aggregate.period?.days['2026-07-20']
+    )!.fileKey;
+    const outsideKey = manifest.files.find((entry) =>
+      cold.index.files[entry.fileKey].aggregate.period?.days['2026-06-02']
     )!.fileKey;
 
     assert.equal(rebuilt.index.schemaVersion, 3);
-    assert.deepEqual(io.fileKeysRead, [todayKey]);
+    assert.deepEqual(new Set(io.fileKeysRead), new Set([todayKey, recentKey]));
     assert.equal(todayKeys.length, 2);
     assert.equal(todayKeys.filter((key) => io.bodyReads.has(key)).length, 1);
-    assert.equal(io.bodyReads.has(oldKey), false);
+    assert.equal(io.bodyReads.has(recentKey), true);
+    assert.equal(io.bodyReads.has(outsideKey), false);
     assert.equal(rebuilt.index.files[todayKey].aggregate.today?.hours['02'].total.inputTotal, 100);
+    assert.equal(
+      rebuilt.index.files[recentKey].aggregate.today?.days?.['2026-07-20']['02']
+        .total.inputTotal,
+      300,
+    );
+    assert.equal(rebuilt.index.coverage.hourly?.indexedFiles, 2);
+    assert.equal(rebuilt.index.coverage.hourly?.totalFiles, 2);
+    assert.equal(rebuilt.index.coverage.hourly?.complete, true);
     assert.deepEqual(rebuilt.index.coverage.today, {
       timeZone: 'Asia/Hong_Kong',
       day: '2026-07-21',
@@ -1184,6 +1538,16 @@ test('timezone changes rebuild the current civil day and then stay warm without
     assert.equal(hongKong.index.files[key].aggregate.today?.timeZone, 'Asia/Hong_Kong');
     assert.equal(hongKong.index.files[key].aggregate.today?.hours['00'].total.inputTotal, 50);
     assert.equal(hongKong.index.files[key].aggregate.today?.hours['15'], undefined);
+    assert.equal(
+      hongKong.index.files[key].aggregate.today?.days?.['2026-07-20']['23']
+        .total.inputTotal,
+      100,
+    );
+    assert.equal(
+      hongKong.index.files[key].aggregate.today?.days?.['2026-07-21']['00']
+        .total.inputTotal,
+      50,
+    );
     assert.equal(hongKong.index.coverage.today.complete, true);
 
     const warmIo = trackingIo();
@@ -1363,6 +1727,57 @@ test('parallel file passes preserve the exact sequential index across every back
   }
 });
 
+test('file-pass pool disposal waits for workers removed by a failed batch to terminate', async () => {
+  let finishTerminate!: (code: number) => void;
+  const termination = new Promise<number>((resolve) => {
+    finishTerminate = resolve;
+  });
+  let terminateCalls = 0;
+  const worker = {
+    postMessage: () => undefined,
+    on: () => worker,
+    terminate: () => {
+      terminateCalls += 1;
+      return termination;
+    },
+  } as CodexFilePassWorkerLike;
+  const pool = new CodexFilePassPool(1, () => worker);
+  const running = pool.run(
+    [{ taskId: 'aggregate-only-test' } as any],
+    async () => undefined,
+  );
+  (pool as any).failActive(new Error('synthetic batch failure'));
+  await assert.rejects(running, /synthetic batch failure/);
+
+  let disposalSettled = false;
+  const disposal = pool.dispose().then(() => {
+    disposalSettled = true;
+  });
+  await Promise.resolve();
+  assert.equal(terminateCalls, 1);
+  assert.equal(disposalSettled, false);
+
+  finishTerminate(0);
+  await disposal;
+  assert.equal(disposalSettled, true);
+});
+
+test('file-pass pool disposal rejects when a worker cannot be terminated', async () => {
+  const worker = {
+    postMessage: () => undefined,
+    on: () => worker,
+    terminate: () => Promise.reject(new Error('file-pass terminate failed')),
+  } as CodexFilePassWorkerLike;
+  const pool = new CodexFilePassPool(1, () => worker);
+  const running = pool.run(
+    [{ taskId: 'aggregate-only-termination-failure' } as any],
+    async () => undefined,
+  );
+  (pool as any).failActive(new Error('synthetic batch failure'));
+  await assert.rejects(running, /synthetic batch failure/);
+  await assert.rejects(pool.dispose(), /file-pass terminate failed/);
+});
+
 test('day or timezone changes invalidate the warm no-op metadata shortcut', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-index-noop-boundary-'));
   try {
@@ -1709,15 +2124,18 @@ test('cancellation checkpoints a resumable period cursor without clearing all-ti
     );
 
     assert.equal(checkpoints.length, 1);
+    assert.equal(checkpoints[0].indexGeneration, legacy.indexGeneration);
     assert.ok(checkpoints[0].files[key].periodMigration!.offset > 0);
     assert.equal(checkpoints[0].aggregate.total.inputTotal, cold.index.aggregate.total.inputTotal);
     const saved = await loadCodexIndex(checkpointPath, 'UTC');
+    assert.equal(saved.indexGeneration, legacy.indexGeneration);
     assert.equal(saved.files[key].periodMigration?.offset, checkpoints[0].files[key].periodMigration?.offset);
     assert.equal('carry' in (saved.files[key].periodMigration ?? {}), false);
     const resumed = await updateCodexIndex(saved, manifest, {
       salt: SALT,
       timeZone: 'UTC',
     });
+    assert.equal(resumed.index.indexGeneration, saved.indexGeneration);
     assert.equal(resumed.index.files[key].aggregate.period?.indexedThrough, legacy.files[key].offset);
   } finally {
     await rm(root, { recursive: true, force: true });
@@ -1803,7 +2221,7 @@ function dedupContribution(
     offset: 100,
     discardingOversizedLine: false,
     parserState: {
-      schemaVersion: 3,
+      schemaVersion: 4,
       fileKey,
       sessionKey: 'shared-anonymous-session',
       role: 'root',
diff --git a/src/test/codexIndexClient.test.ts b/src/test/codexIndexClient.test.ts
index ba8ad91e..b69f1401 100644
--- a/src/test/codexIndexClient.test.ts
+++ b/src/test/codexIndexClient.test.ts
@@ -59,6 +59,22 @@ class FakeWorker extends EventEmitter implements CodexWorkerLike {
   }
 }
 
+class DelayedTerminateWorker extends FakeWorker {
+  private finishTerminate!: (value: number) => void;
+  readonly terminateSettled = new Promise<number>((resolve) => {
+    this.finishTerminate = resolve;
+  });
+
+  override terminate(): Promise<number> {
+    this.terminated += 1;
+    return this.terminateSettled;
+  }
+
+  finish(): void {
+    this.finishTerminate(0);
+  }
+}
+
 const request = {
   codexHome: '/private/runtime-only-codex-home',
   indexPath: '/private/global-storage/codex-index-v1.json',
@@ -201,6 +217,7 @@ test('a worker error rejects all shared callers with a typed safe error', async
       );
     });
   }
+  assert.equal(worker.terminated, 1);
 });
 
 test('dispose terminates the worker and rejects later refreshes', async () => {
@@ -208,13 +225,76 @@ test('dispose terminates the worker and rejects later refreshes', async () => {
   const client = new CodexIndexClient(() => worker);
   const pending = client.refresh(request);
 
-  client.dispose();
+  await client.dispose();
 
   assert.equal(worker.terminated, 1);
   await assert.rejects(pending, { code: 'disposed' });
   await assert.rejects(client.refresh(request), { code: 'disposed' });
 });
 
+test('terminal refresh remains owned until the worker has actually terminated', async () => {
+  const firstWorker = new DelayedTerminateWorker();
+  const secondWorker = new FakeWorker();
+  const workers = [firstWorker, secondWorker];
+  const client = new CodexIndexClient(() => {
+    const worker = workers.shift();
+    if (!worker) throw new Error('unexpected worker allocation');
+    return worker;
+  });
+  let firstSettled = false;
+  const first = client.refresh(request).finally(() => {
+    firstSettled = true;
+  });
+  const firstRequest = firstWorker.requests[0];
+  if (firstRequest.type !== 'refresh') throw new Error('expected refresh');
+
+  firstWorker.emitMessage({
+    type: 'result',
+    requestId: firstRequest.requestId,
+    result: result(),
+  });
+  const sharedWhileStopping = client.refresh(request);
+  await Promise.resolve();
+  assert.equal(firstSettled, false);
+  assert.equal(secondWorker.requests.length, 0);
+
+  firstWorker.finish();
+  await first;
+  await sharedWhileStopping;
+  assert.equal(firstWorker.terminated, 1);
+  assert.equal(secondWorker.requests.length, 0);
+  await client.dispose();
+});
+
+test('dispose resolves only after actual worker termination settles', async () => {
+  const worker = new DelayedTerminateWorker();
+  const client = new CodexIndexClient(() => worker);
+  const pending = client.refresh(request);
+  let disposed = false;
+  const disposal = client.dispose().then(() => {
+    disposed = true;
+  });
+
+  await Promise.resolve();
+  assert.equal(worker.terminated, 1);
+  assert.equal(disposed, false);
+  await assert.rejects(pending, { code: 'disposed' });
+  worker.finish();
+  await disposal;
+  assert.equal(disposed, true);
+});
+
+test('dispose rejects when worker termination cannot be confirmed', async () => {
+  const worker = new FakeWorker();
+  worker.terminate = () => Promise.reject(new Error('terminate failed'));
+  const client = new CodexIndexClient(() => worker);
+  const pending = client.refresh(request);
+  const pendingRejection = assert.rejects(pending, { code: 'disposed' });
+
+  await assert.rejects(client.dispose(), /terminate failed/);
+  await pendingRejection;
+});
+
 test('the compiled worker keeps a safe project basename without raw identifiers or paths', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-worker-'));
   const client = new CodexIndexClient();
@@ -395,6 +475,46 @@ test('unchanged worker refresh skips the final atomic index write', async () =>
   assert.equal((resultMessage.result as any).indexChanged, false);
 });
 
+test('an ineligible background state disables historical passes without disabling the main refresh', async () => {
+  const previous = createEmptyCodexIndex(request.timeZone);
+  let historicalAllowed: boolean | undefined;
+  let pools = 0;
+  const messages: CodexWorkerMessage[] = [];
+  await runCodexWorkerRefresh(
+    {
+      type: 'refresh',
+      requestId: 'historical-cooldown',
+      ...request,
+      allowHistoricalBackfill: false,
+    },
+    {
+      isCancelled: () => false,
+      post: (message) => messages.push(message),
+      acquireCodexIndexLease: async () => ({ release: async () => undefined }),
+      loadCodexIndex: async () => previous,
+      scanCodexManifest: async () => ({ files: [], persistable: {} }),
+      updateCodexIndex: async (_index, _manifest, options) => {
+        historicalAllowed = options.allowHistoricalBackfill;
+        return {
+          index: previous,
+          indexChanged: false,
+          bodyReads: 0,
+          failedFiles: 0,
+          migration: { filePasses: 0, bytesRead: 0, pending: true },
+        };
+      },
+      saveCodexIndexAtomic: async () => undefined,
+      createCodexFilePassPool: () => {
+        pools += 1;
+        return { run: async () => undefined, dispose: async () => undefined };
+      },
+    },
+  );
+  assert.equal(historicalAllowed, false);
+  assert.equal(pools, 0);
+  assert.equal(messages.some((message) => message.type === 'result'), true);
+});
+
 test('a refresh already saved by its final checkpoint skips the duplicate final write', async () => {
   const savedIndex = createEmptyCodexIndex(request.timeZone);
   let saves = 0;
diff --git a/src/test/codexParser.test.ts b/src/test/codexParser.test.ts
index 4ae6d9bb..df7dde35 100644
--- a/src/test/codexParser.test.ts
+++ b/src/test/codexParser.test.ts
@@ -685,6 +685,86 @@ test('counter regression keeps exact last usage and marks it partial', () => {
   assert.equal(result.events[0].confidence, 'partial');
 });
 
+test('cumulative deltas preserve cached-input and reasoning subset invariants', () => {
+  let state = createCodexParserState('root-file');
+  state = parseCodexLine(
+    tokenSnapshot({
+      second: 1,
+      total: { input: 100, cached: 0, output: 100, reasoning: 0 },
+    }),
+    state,
+  ).state;
+  const result = parseCodexLine(
+    tokenSnapshot({
+      second: 2,
+      total: { input: 101, cached: 100, output: 101, reasoning: 100 },
+    }),
+    state,
+  );
+
+  assert.equal(result.events.length, 1);
+  assert.deepEqual(result.events[0].tokens, {
+    inputTotal: 1,
+    cachedInput: 1,
+    outputTotal: 1,
+    reasoningOutput: 1,
+    sourceTotal: 2,
+  });
+  assert.ok(result.events[0].qualityFlags.includes('component-delta-clamped'));
+  assert.equal(result.events[0].confidence, 'partial');
+});
+
+test('actual reasoning-effort schema variants normalize without model inference', () => {
+  let state = createCodexParserState('root-file');
+  state = parseCodexLine(
+    JSON.stringify({
+      timestamp: '2026-07-20T00:00:00.000Z',
+      type: 'turn_context',
+      payload: {
+        model: 'gpt-5.6-sol',
+        collaboration_mode: { settings: { reasoning_effort: 'ULTRA' } },
+      },
+    }),
+    state,
+  ).state;
+  assert.equal(state.effort, 'ultra');
+
+  state = parseCodexLine(
+    JSON.stringify({
+      timestamp: '2026-07-20T00:00:01.000Z',
+      type: 'event_msg',
+      payload: {
+        type: 'thread_settings_applied',
+        thread_settings: {
+          reasoning_effort: 'low',
+          collaboration_mode: { settings: { reasoning_effort: 'low' } },
+        },
+      },
+    }),
+    state,
+  ).state;
+  assert.equal(state.effort, 'low');
+
+  state = parseCodexLine(
+    JSON.stringify({
+      timestamp: '2026-07-20T00:00:02.000Z',
+      type: 'event_msg',
+      payload: {
+        type: 'thread_settings_applied',
+        thread_settings: { reasoning_effort: 'turbo' },
+      },
+    }),
+    state,
+  ).state;
+  assert.equal(state.effort, undefined);
+
+  const usage = parseCodexLine(
+    tokenLine({ inputTotal: 10, inputLast: 10 }),
+    state,
+  );
+  assert.equal(usage.events[0].effort, undefined);
+});
+
 test('session metadata is pseudonymized and auto-review stays distinct', () => {
   const pseudonyms: Record<string, string> = {
     'raw-session': 'session:001',
diff --git a/src/test/codexPeriodIndex.test.ts b/src/test/codexPeriodIndex.test.ts
index c60a4a1a..6e1ed55a 100644
--- a/src/test/codexPeriodIndex.test.ts
+++ b/src/test/codexPeriodIndex.test.ts
@@ -2,8 +2,12 @@ import { test } from 'node:test';
 import * as assert from 'node:assert/strict';
 
 import {
+  CODEX_ROLLING_HOURLY_DAYS,
   CodexDailySlice,
+  CodexHourlyDays,
   CodexHourlySlice,
+  pruneCodexHourlyDays,
+  reduceCodexRollingHourlySlice,
   reduceCodexHourlySlice,
   reduceCodexStructuralSlice,
   reduceCodexUsageSlice,
@@ -158,3 +162,39 @@ test('hourly reducer retains only the requested local day as sparse hour buckets
   assert.equal(hours['02'].total.outputTotal, 5);
   assert.equal('byEffort' in hours['00'], false);
 });
+
+test('rolling hourly reducer keeps sparse configured-zone days and prunes day 31', () => {
+  const days: CodexHourlyDays = {};
+  const allowedDays = new Set([
+    '2026-06-22',
+    '2026-07-20',
+    '2026-07-21',
+  ]);
+
+  reduceCodexRollingHourlySlice(
+    days,
+    usage('2026-06-21T15:55:00.000Z', 25, 5, 3),
+    allowedDays,
+    'Asia/Hong_Kong',
+  );
+  reduceCodexRollingHourlySlice(
+    days,
+    usage('2026-06-21T16:05:00.000Z', 50, 10, 6),
+    allowedDays,
+    'Asia/Hong_Kong',
+  );
+  reduceCodexRollingHourlySlice(
+    days,
+    usage('2026-07-20T16:05:00.000Z', 75, 15, 9),
+    allowedDays,
+    'Asia/Hong_Kong',
+  );
+
+  assert.equal(CODEX_ROLLING_HOURLY_DAYS, 30);
+  assert.deepEqual(Object.keys(days).sort(), ['2026-06-22', '2026-07-21']);
+  assert.equal(days['2026-06-22']['00'].total.inputTotal, 50);
+  assert.equal(days['2026-07-21']['00'].total.outputTotal, 15);
+
+  pruneCodexHourlyDays(days, new Set(['2026-07-21']));
+  assert.deepEqual(Object.keys(days), ['2026-07-21']);
+});
diff --git a/src/test/codexProvider.test.ts b/src/test/codexProvider.test.ts
index 71006515..975d202f 100644
--- a/src/test/codexProvider.test.ts
+++ b/src/test/codexProvider.test.ts
@@ -29,7 +29,7 @@ function contribution(
     offset: 100,
     discardingOversizedLine: false,
     parserState: {
-      schemaVersion: 3,
+      schemaVersion: 4,
       fileKey,
       sessionKey: 'anonymous-session-key',
       role: 'root',
@@ -520,6 +520,153 @@ test('provider snapshots promote exact period slices for scoped consumers', asyn
   }
 });
 
+test('a delayed post-reset current poll does not hide cached pre-reset evidence', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-provider-quota-rollover-'));
+  try {
+    await mkdir(path.join(root, 'sessions'), { recursive: true });
+    const index = duplicateIndex(false);
+    const file = index.files['active-key'];
+    const resetAt = Date.parse('2026-08-31T03:00:00.000Z');
+    file.limits = {
+      codex: {
+        provider: 'codex',
+        limitId: 'codex',
+        observedAt: resetAt + 30 * 60 * 1000,
+        source: 'local-log',
+        confidence: 'last-observed',
+        windows: [{
+          label: 'secondary',
+          usedPercent: 1,
+          windowMinutes: 7 * 24 * 60,
+          resetsAt: resetAt,
+        }],
+      },
+    };
+    index.quotaHistory = [{
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt: resetAt - 30 * 60 * 1000,
+      resetAt,
+      usedPercent: 96,
+    }];
+    const provider = new CodexProvider(
+      {
+        enabled: true,
+        codexHome: root,
+        indexPath: 'index',
+        salt: 'salt',
+        timeZone: 'UTC',
+      },
+      () => new FakeClient([{ ...workerResult(index), failedFiles: 0 }]),
+    );
+
+    const refreshed = await provider.refresh();
+    const observations = refreshed.snapshot.weeklyValueInputs?.observations ?? [];
+
+    assert.deepEqual(
+      observations.map((item) => [item.observedAt, item.usedPercent]),
+      [
+        [resetAt + 30 * 60 * 1000, 1],
+        [resetAt - 30 * 60 * 1000, 96],
+      ],
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an invalid period sidecar cannot create a false weekly priced estimate', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-provider-period-guard-'));
+  try {
+    await mkdir(path.join(root, 'sessions'), { recursive: true });
+    const index = duplicateIndex(false);
+    const file = index.files['active-key'];
+    file.aggregate.period = {
+      timeZone: 'UTC',
+      indexedThrough: file.offset,
+      days: {
+        '2026-07-20': {
+          total: { inputTotal: 10_000_000_000, outputTotal: 5_000_000_000 },
+          byModel: {
+            'gpt-5.6-sol': {
+              inputTotal: 10_000_000_000,
+              outputTotal: 5_000_000_000,
+            },
+          },
+          byEffort: {},
+          structural: file.aggregate.structural,
+        },
+      },
+    };
+
+    const provider = new CodexProvider(
+      {
+        enabled: true,
+        codexHome: root,
+        indexPath: 'index',
+        salt: 'salt',
+        timeZone: 'UTC',
+      },
+      () => new FakeClient([{ ...workerResult(index), failedFiles: 0 }]),
+    );
+
+    const refreshed = await provider.refresh();
+
+    assert.equal(refreshed.snapshot.total.inputTotal, 80);
+    assert.deepEqual(refreshed.snapshot.weeklyValueInputs?.usage, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a period with a mismatched lineage marker stays hidden during rebuild', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-provider-period-marker-'));
+  try {
+    await mkdir(path.join(root, 'sessions'), { recursive: true });
+    const index = duplicateIndex(false);
+    const file = index.files['active-key'];
+    file.lineage = {
+      fingerprintBlocks: [],
+      pendingFingerprints: [],
+      tokenEvents: 0,
+      desiredPrefixEvents: 0,
+      appliedPrefixEvents: 0,
+    };
+    file.aggregate.period = {
+      timeZone: 'UTC',
+      indexedThrough: file.offset,
+      lineageVersion: 1,
+      lineagePrefixEvents: 1,
+      days: {
+        '2026-07-20': {
+          total: { ...file.aggregate.total },
+          byModel: { ...file.aggregate.byModel },
+          byEffort: { ...file.aggregate.byEffort },
+          structural: file.aggregate.structural,
+        },
+      },
+    };
+
+    const provider = new CodexProvider(
+      {
+        enabled: true,
+        codexHome: root,
+        indexPath: 'index',
+        salt: 'salt',
+        timeZone: 'UTC',
+      },
+      () => new FakeClient([{ ...workerResult(index), failedFiles: 0 }]),
+    );
+
+    const refreshed = await provider.refresh();
+
+    assert.equal(refreshed.snapshot.files[0].period, undefined);
+    assert.deepEqual(refreshed.snapshot.weeklyValueInputs?.usage, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('a worker failure retains the last verified provider snapshot', async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-codex-provider-stale-'));
   try {
diff --git a/src/test/codexQuotaHistory.test.ts b/src/test/codexQuotaHistory.test.ts
new file mode 100644
index 00000000..a8290f31
--- /dev/null
+++ b/src/test/codexQuotaHistory.test.ts
@@ -0,0 +1,138 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  appendCodexQuotaHistory,
+  CODEX_QUOTA_HISTORY_LIMIT,
+  codexQuotaObservationsFromLimit,
+  weeklyQuotaObservationsFromCodexHistory,
+} from '../providers/codex/codexQuotaHistory';
+import { ProviderLimitSnapshot } from '../providers/providerTypes';
+
+function limit(
+  observedAt: number,
+  resetAt: number,
+  usedPercent: number,
+  options: {
+    limitId?: string;
+    limitName?: string;
+    windowMinutes?: number;
+  } = {},
+): ProviderLimitSnapshot {
+  return {
+    provider: 'codex',
+    ...(options.limitId ? { limitId: options.limitId } : {}),
+    ...(options.limitName ? { limitName: options.limitName } : {}),
+    observedAt,
+    source: 'local-log',
+    confidence: 'last-observed',
+    windows: [{
+      label: 'secondary',
+      usedPercent,
+      windowMinutes: options.windowMinutes ?? 7 * 24 * 60,
+      resetsAt: resetAt,
+    }],
+  };
+}
+
+test('only account-wide weekly Codex windows become neutral reset evidence', () => {
+  const resetAt = Date.parse('2026-08-30T00:00:00.000Z');
+  const observedAt = resetAt - 60 * 60 * 1000;
+
+  assert.deepEqual(
+    codexQuotaObservationsFromLimit(limit(observedAt, resetAt, 42)),
+    [{
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt,
+      resetAt,
+      usedPercent: 42,
+    }],
+  );
+  assert.deepEqual(
+    codexQuotaObservationsFromLimit(
+      limit(observedAt, resetAt, 42, { windowMinutes: 300 }),
+    ),
+    [],
+  );
+  assert.deepEqual(
+    codexQuotaObservationsFromLimit(
+      limit(observedAt, resetAt, 42, { limitId: 'codex-spark' }),
+    ),
+    [],
+  );
+  assert.deepEqual(
+    codexQuotaObservationsFromLimit(
+      limit(observedAt, resetAt, 42, {
+        limitId: 'codex-spark',
+        limitName: 'Codex',
+      }),
+    ),
+    [],
+  );
+});
+
+test('irregular reset boundaries survive polling compaction', () => {
+  const firstReset = Date.parse('2026-08-28T11:00:00.000Z');
+  const secondReset = Date.parse('2026-08-30T07:00:00.000Z');
+  const history = appendCodexQuotaHistory([], [
+    {
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt: firstReset - 3 * 60 * 60 * 1000,
+      resetAt: firstReset,
+      usedPercent: 12,
+    },
+    {
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt: firstReset - 30 * 60 * 1000,
+      resetAt: firstReset,
+      usedPercent: 38,
+    },
+    {
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt: secondReset - 2 * 60 * 60 * 1000,
+      resetAt: secondReset,
+      usedPercent: 7,
+    },
+  ]);
+
+  assert.deepEqual(history, [
+    {
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt: firstReset - 30 * 60 * 1000,
+      resetAt: firstReset,
+      usedPercent: 38,
+    },
+    {
+      provider: 'codex',
+      seriesKey: 'codex',
+      observedAt: secondReset - 2 * 60 * 60 * 1000,
+      resetAt: secondReset,
+      usedPercent: 7,
+    },
+  ]);
+
+  const weekly = weeklyQuotaObservationsFromCodexHistory(history);
+  assert.equal(weekly.length, 2);
+  assert.equal(weekly.every((item) => item.sourceKey === undefined), true);
+  assert.equal(Object.prototype.hasOwnProperty.call(weekly[0], 'account'), false);
+  assert.equal(Object.prototype.hasOwnProperty.call(weekly[0], 'sourceKey'), false);
+});
+
+test('quota history remains bounded even when resets are numerous', () => {
+  const additions = Array.from({ length: CODEX_QUOTA_HISTORY_LIMIT + 17 }, (_, index) => ({
+    provider: 'codex' as const,
+    seriesKey: 'codex' as const,
+    observedAt: 1_700_000_000_000 + index * 7 * 24 * 60 * 60 * 1000,
+    resetAt: 1_700_000_100_000 + index * 7 * 24 * 60 * 60 * 1000,
+    usedPercent: index % 101,
+  }));
+
+  const history = appendCodexQuotaHistory([], additions);
+  assert.equal(history.length, CODEX_QUOTA_HISTORY_LIMIT);
+  assert.equal(history[0].resetAt < history[history.length - 1].resetAt, true);
+});
diff --git a/src/test/codexStatus.test.ts b/src/test/codexStatus.test.ts
index da3c9470..ecf63d06 100644
--- a/src/test/codexStatus.test.ts
+++ b/src/test/codexStatus.test.ts
@@ -1,7 +1,11 @@
 import { test } from 'node:test';
 import * as assert from 'node:assert/strict';
 
-import { formatCodexStatus } from '../codexStatus';
+import {
+  codexQuotaWarningPercent,
+  formatCodexStatus,
+  visibleCodexQuotaWindows,
+} from '../codexStatus';
 import { ProviderLimitSnapshot } from '../providers/providerTypes';
 import { CodexUsageScopeView } from '../providers/codex/codexUsage';
 
@@ -35,31 +39,90 @@ const scope: CodexUsageScopeView = {
   efforts: [],
 };
 
-function limit(resetsAt: number): ProviderLimitSnapshot {
+function limit(
+  resetsAt: number,
+  windows: ProviderLimitSnapshot['windows'] = [
+    {
+      label: 'primary',
+      usedPercent: 42,
+      windowMinutes: 300,
+      resetsAt,
+    },
+  ],
+): ProviderLimitSnapshot {
   return {
     provider: 'codex',
     observedAt: NOW - 60_000,
     source: 'local-log',
     confidence: 'last-observed',
-    windows: [
-      {
-        label: 'primary',
-        usedPercent: 42,
-        windowMinutes: 300,
-        resetsAt,
-      },
-    ],
+    windows,
   };
 }
 
-test('Codex status defaults to fresh and labels last-observed limits', () => {
-  assert.deepEqual(formatCodexStatus(scope, 'fresh', limit(NOW + 60_000), NOW), {
+test('Codex status defaults to fresh and shows remaining weekly quota', () => {
+  const formatted = formatCodexStatus(scope, 'fresh', limit(NOW + 60_000, [
+    {
+      label: 'primary',
+      usedPercent: 42,
+      windowMinutes: 300,
+      resetsAt: NOW + 60_000,
+    },
+    {
+      label: 'secondary',
+      usedPercent: 67,
+      windowMinutes: 10_080,
+      resetsAt: NOW + 86_400_000,
+    },
+  ]), NOW);
+
+  assert.deepEqual(formatted, {
     text: 'CX 400',
-    limitText: '5h 42%',
+    limitText: 'wk 33%',
+    limit: {
+      label: 'wk',
+      windowMinutes: 10_080,
+      usedPercent: 67,
+      remainingPercent: 33,
+      observedAt: NOW - 60_000,
+      resetsAt: NOW + 86_400_000,
+    },
     stale: false,
   });
 });
 
+test('the existing five-hour-only preference selects the five-hour remaining quota', () => {
+  const formatted = formatCodexStatus(scope, 'fresh', limit(NOW + 60_000, [
+    { label: 'primary', usedPercent: 42, windowMinutes: 300, resetsAt: NOW + 60_000 },
+    { label: 'secondary', usedPercent: 67, windowMinutes: 10_080, resetsAt: NOW + 86_400_000 },
+  ]), NOW, { quotaFiveHourOnly: true });
+
+  assert.equal(formatted.limitText, '5h 58%');
+  assert.equal(formatted.limit?.windowMinutes, 300);
+  assert.equal(formatted.limit?.remainingPercent, 58);
+});
+
+test('the default falls back to a live five-hour window when weekly data is absent', () => {
+  const formatted = formatCodexStatus(scope, 'fresh', limit(NOW + 60_000), NOW);
+  assert.equal(formatted.limitText, '5h 58%');
+  assert.equal(formatted.limit?.remainingPercent, 58);
+});
+
+test('quota warning follows the worst live visible window, not the compact weekly choice', () => {
+  const snapshot = limit(NOW + 60_000, [
+    { label: 'primary', usedPercent: 96, windowMinutes: 300, resetsAt: NOW + 60_000 },
+    { label: 'secondary', usedPercent: 40, windowMinutes: 10_080, resetsAt: NOW + 86_400_000 },
+    { label: 'expired', usedPercent: 100, windowMinutes: 60, resetsAt: NOW - 1 },
+  ]);
+
+  assert.equal(formatCodexStatus(scope, 'fresh', snapshot, NOW).limitText, 'wk 60%');
+  assert.equal(codexQuotaWarningPercent(snapshot, NOW), 96);
+  assert.equal(codexQuotaWarningPercent(snapshot, NOW, { quotaFiveHourOnly: true }), 96);
+  assert.deepEqual(
+    visibleCodexQuotaWindows(snapshot, NOW).map((window) => window.usedPercent),
+    [96, 40],
+  );
+});
+
 test('processed and output metrics stay distinct', () => {
   assert.equal(formatCodexStatus(scope, 'processed', null, NOW).text, 'CX 1.2k');
   assert.equal(formatCodexStatus(scope, 'output', null, NOW).text, 'CX 200');
diff --git a/src/test/codexUsage.test.ts b/src/test/codexUsage.test.ts
index 390745f4..f57859f0 100644
--- a/src/test/codexUsage.test.ts
+++ b/src/test/codexUsage.test.ts
@@ -84,6 +84,49 @@ test('partial period coverage disables unreliable session membership ranges', ()
   });
 });
 
+test('an inflated period sidecar falls back to the verified daily aggregate', () => {
+  const snapshot = snapshotFixture();
+  const file = snapshot.files[0];
+  const safeDay = Object.keys(file.byDay)[0];
+  const safeDailyTotal = file.byDay[safeDay];
+  file.period = {
+    ...file.period!,
+    days: {
+      [safeDay]: {
+        ...file.period!.days[safeDay],
+        total: {
+          inputTotal: 10_000_000_000,
+          outputTotal: 5_000_000_000,
+        },
+      },
+    },
+  };
+  snapshot.files = [file];
+  snapshot.total = { ...file.total };
+
+  const view = buildCodexUsageView(snapshot, NOW);
+  const daily = view.daily.find((row) => row.day === safeDay);
+
+  assert.equal(
+    daily?.total.processed,
+    safeDailyTotal.inputTotal + safeDailyTotal.outputTotal,
+  );
+  assert.equal(
+    view.allTime.total.processed,
+    file.total.inputTotal + file.total.outputTotal,
+  );
+  assert.equal(view.last30Days.total.processed <= view.allTime.total.processed, true);
+  assert.deepEqual(daily?.apiEquivalent, {
+    equivalentUsd: 0,
+    freshInputUsd: 0,
+    cachedInputUsd: 0,
+    outputUsd: 0,
+    pricedTokens: 0,
+    totalTokens: safeDailyTotal.inputTotal + safeDailyTotal.outputTotal,
+    pricingCoverage: 0,
+  });
+});
+
 test('index backfill quality warning follows index convergence', () => {
   const snapshot = snapshotFixture();
   const incomplete = buildCodexUsageView(snapshot, NOW);
@@ -415,6 +458,18 @@ test('daily and monthly Codex rows retain exact-model API-equivalent cost and co
       },
     },
   };
+  // The period projection is now required to be a subset of the verified
+  // file aggregate. Keep this synthetic cost fixture internally consistent so
+  // it exercises pricing rather than the corrupted-period fallback.
+  file.total = {
+    inputTotal: 5_000_000,
+    // Both period days are part of this file's verified aggregate. Keep the
+    // cache bucket consistent as well so the test exercises pricing rather
+    // than the corrupted-period fallback.
+    cachedInput: 2_000_000,
+    outputTotal: 2_500_000,
+    reasoningOutput: 1_750_000,
+  };
   snapshot.files = [file];
 
   const view = buildCodexUsageView(snapshot, NOW);
@@ -436,24 +491,66 @@ test('daily and monthly Codex rows retain exact-model API-equivalent cost and co
 
 test('Today is a calendar-day scope with exact sparse hourly cost and token composition', () => {
   const snapshot = snapshotFixture();
-  for (const [index, file] of snapshot.files.slice(0, 2).entries()) {
-    const slice = file.period!.days['2026-07-20'];
-    const hour = index === 0 ? '10' : '11';
+  for (const [index, file] of snapshot.files.slice(0, 3).entries()) {
+    const day = index < 2 ? '2026-07-20' : '2026-07-10';
+    const slice = file.period!.days[day];
+    const hours = index === 0
+      ? {
+          '10': {
+            total: {
+              inputTotal: 250,
+              cachedInput: 200,
+              outputTotal: 50,
+              reasoningOutput: 30,
+              sourceTotal: 300,
+            },
+            byModel: {
+              'gpt-5.6-sol': {
+                inputTotal: 250,
+                cachedInput: 200,
+                outputTotal: 50,
+                reasoningOutput: 30,
+                sourceTotal: 300,
+              },
+            },
+          },
+          '11': {
+            total: {
+              inputTotal: 250,
+              cachedInput: 200,
+              outputTotal: 50,
+              reasoningOutput: 30,
+              sourceTotal: 300,
+            },
+            byModel: {
+              'gpt-5.6-sol': {
+                inputTotal: 250,
+                cachedInput: 200,
+                outputTotal: 50,
+                reasoningOutput: 30,
+                sourceTotal: 300,
+              },
+            },
+          },
+        }
+      : {
+          [index === 1 ? '11' : '09']: {
+            total: { ...slice.total },
+            byModel: Object.fromEntries(
+              Object.entries(slice.byModel).map(([model, tokens]) => [
+                model,
+                { ...tokens },
+              ]),
+            ),
+          },
+        };
     file.today = {
       day: '2026-07-20',
       timeZone: 'UTC',
       indexedThrough: file.period!.indexedThrough,
-      hours: {
-        [hour]: {
-          total: { ...slice.total },
-          byModel: Object.fromEntries(
-            Object.entries(slice.byModel).map(([model, tokens]) => [
-              model,
-              { ...tokens },
-            ]),
-          ),
-        },
-      },
+      windowDays: 30,
+      days: { [day]: hours },
+      hours: day === '2026-07-20' ? hours : {},
     };
   }
   snapshot.coverage.today = {
@@ -465,17 +562,64 @@ test('Today is a calendar-day scope with exact sparse hourly cost and token comp
     totalBytes: 2,
     complete: true,
   };
+  const hourlyCoverage = {
+    timeZone: 'UTC',
+    asOfDay: '2026-07-20',
+    windowDays: 30,
+    indexedFiles: 3,
+    totalFiles: 3,
+    indexedBytes: 3,
+    totalBytes: 3,
+    complete: true,
+    days: {
+      '2026-07-10': {
+        day: '2026-07-10',
+        indexedFiles: 1,
+        totalFiles: 1,
+        indexedBytes: 1,
+        totalBytes: 1,
+        complete: true,
+      },
+      '2026-07-20': {
+        day: '2026-07-20',
+        indexedFiles: 2,
+        totalFiles: 2,
+        indexedBytes: 2,
+        totalBytes: 2,
+        complete: true,
+      },
+    },
+  };
+  snapshot.coverage.hourly = hourlyCoverage;
+  snapshot.hourlyCoverage = hourlyCoverage;
 
   const view = buildCodexUsageView(snapshot, NOW);
 
   assert.equal(view.today.total.processed, 1_200);
   assert.equal(view.today.threads, 2);
   assert.deepEqual(view.todayHourly.map((row) => row.hour), ['10', '11']);
-  assert.equal(view.todayHourly[0].total.processed, 600);
-  assert.equal(view.todayHourly[0].apiEquivalent.equivalentUsd, 0.0037);
+  assert.deepEqual(view.todayHourly.map((row) => row.label), ['10:00', '11:00']);
+  assert.equal(view.todayHourly[0].total.processed, 300);
+  assert.equal(view.todayHourly[0].apiEquivalent.equivalentUsd, 0.00185);
   assert.equal(view.todayHourly[0].apiEquivalent.pricingCoverage, 1);
   assert.equal(view.todayHourly[0].threads, 1);
   assert.equal(view.todayCoverage.complete, true);
+  assert.equal(view.last30DaysHourlyByDay['2026-07-10'][0].hour, '09');
+  assert.equal(view.last30DaysHourlyByDay['2026-07-10'][0].label, '09:00');
+  assert.equal(view.last30DaysHourlyByDay['2026-07-10'][0].threads, 1);
+  assert.equal(view.hourlyCoverage.days['2026-07-10'].complete, true);
+
+  const hourlyProcessed = view.todayHourly.reduce(
+    (sum, row) => sum + row.total.processed,
+    0,
+  );
+  const hourlyThreads = view.todayHourly.reduce(
+    (sum, row) => sum + row.threads,
+    0,
+  );
+  assert.equal(hourlyProcessed, view.today.total.processed);
+  assert.equal(hourlyThreads, 3);
+  assert.equal(view.today.threads, 2);
 });
 
 test('rolling scopes stay anchored to snapshot coverage across Hong Kong midnight', () => {
@@ -659,9 +803,12 @@ test('all-time, monthly, and behavior views stay provider-native', () => {
 
   assert.equal(view.allTime.total.processed, 1_560);
   assert.equal(view.allTime.total.fresh, 640);
-  assert.equal(view.monthly[0].period, '2026-07');
-  assert.equal(view.monthly[0].total.processed, 1_440);
-  assert.equal(view.monthly[0].threads, 3);
+  assert.deepEqual(
+    view.monthly.map((row) => row.period),
+    ['2026-06', '2026-07'],
+  );
+  assert.equal(view.monthly[1].total.processed, 1_440);
+  assert.equal(view.monthly[1].threads, 3);
   assert.equal(view.last7DaysDaily.length, 7);
   assert.equal(view.last7DaysDaily[0].day, '2026-07-14');
   assert.equal(view.last7DaysDaily[6].day, '2026-07-20');
@@ -684,6 +831,108 @@ test('all-time, monthly, and behavior views stay provider-native', () => {
   assert.equal(view.behaviorScopes.allTime.childFreshShare, view.behavior.childFreshShare);
 });
 
+test('v2.3.1 acceptance fixture keeps non-negative ranges monotonic and reconciled', () => {
+  const view = buildCodexUsageView(snapshotFixture(), NOW);
+  const monthProcessed = view.monthly.reduce(
+    (sum, row) => sum + row.total.processed,
+    0,
+  );
+  const allDailyProcessed = view.daily.reduce(
+    (sum, row) => sum + row.total.processed,
+    0,
+  );
+  const last30DailyProcessed = view.last30DaysDaily.reduce(
+    (sum, row) => sum + row.total.processed,
+    0,
+  );
+  const last30ModelProcessed = view.last30Days.models.reduce(
+    (sum, row) => sum + row.totals.processed,
+    0,
+  );
+  const last30EffortProcessed = view.last30Days.efforts.reduce(
+    (sum, row) => sum + row.totals.processed,
+    0,
+  );
+
+  assert.equal(view.today.total.processed >= 0, true);
+  assert.equal(view.today.total.processed <= view.last30Days.total.processed, true);
+  assert.equal(view.last30Days.total.processed <= view.allTime.total.processed, true);
+  assert.equal(monthProcessed, view.allTime.total.processed);
+  assert.equal(allDailyProcessed, view.allTime.total.processed);
+  assert.equal(last30DailyProcessed, view.last30Days.total.processed);
+  assert.equal(last30ModelProcessed, view.last30Days.total.processed);
+  assert.equal(last30EffortProcessed, view.last30Days.total.processed);
+  assert.deepEqual(
+    view.monthly.map((row) => row.period),
+    [...view.monthly.map((row) => row.period)].sort(),
+  );
+});
+
+test('monthly rows remain chronological across a year boundary', () => {
+  const snapshot = snapshotFixture();
+  snapshot.files = snapshot.files.slice(0, 2);
+  const days = ['2026-01-01', '2025-12-31'];
+  snapshot.files.forEach((file, index) => {
+    const day = days[index];
+    file.byDay = { [day]: { ...file.total } };
+    file.period = {
+      ...file.period!,
+      days: {
+        [day]: {
+          ...Object.values(file.period!.days)[0],
+          total: { ...file.total },
+        },
+      },
+    };
+  });
+
+  const view = buildCodexUsageView(snapshot, NOW);
+
+  assert.deepEqual(view.monthly.map((row) => row.period), [
+    '2025-12',
+    '2026-01',
+  ]);
+});
+
+test('daily activity view retains a complete leap-year share window plus boundary margin', () => {
+  const snapshot = snapshotFixture();
+  const file = structuredClone(snapshot.files[0]);
+  const byDay = Object.fromEntries(
+    Array.from({ length: 371 }, (_, offset) => {
+      const day = new Date(NOW);
+      day.setUTCHours(0, 0, 0, 0);
+      day.setUTCDate(day.getUTCDate() - offset);
+      return [day.toISOString().slice(0, 10), {
+        inputTotal: 1,
+        cachedInput: 0,
+        outputTotal: 0,
+        reasoningOutput: 0,
+        sourceTotal: 1,
+      }];
+    }),
+  );
+  file.total = {
+    inputTotal: 371,
+    cachedInput: 0,
+    outputTotal: 0,
+    reasoningOutput: 0,
+    sourceTotal: 371,
+  };
+  file.byDay = byDay;
+  file.byModel = { 'gpt-5.6-sol': { ...file.total } };
+  file.byEffort = { high: { ...file.total } };
+  file.period = undefined;
+  snapshot.files = [file];
+  snapshot.total = { ...file.total };
+
+  const view = buildCodexUsageView(snapshot, NOW);
+
+  assert.equal(view.daily.length, 370);
+  assert.equal(view.daily[0].day, '2026-07-20');
+  assert.equal(view.daily[view.daily.length - 1]?.day, '2025-07-16');
+  assert.equal(view.daily.some((row) => row.day === '2025-07-15'), false);
+});
+
 test('behavior exposes patch and tool call proxies without file or command claims', () => {
   const snapshot = snapshotFixture();
   snapshot.files[0].structural = {
@@ -711,6 +960,7 @@ test('token composition partitions processed tokens without counting reasoning t
       reasoning: 60,
     }),
     {
+      uncachedUsage: 200,
       freshInput: 100,
       cachedInput: 400,
       output: 100,
@@ -817,6 +1067,52 @@ test('missing model and effort values are grouped as unknown', () => {
   assert.equal(view.last7Days.efforts.find((row) => row.key === 'unknown')?.totals.processed, 600);
 });
 
+test('partial effort buckets attribute every residual component to unknown', () => {
+  const snapshot = snapshotFixture();
+  const file = snapshot.files[0];
+  const partial = {
+    inputTotal: 100,
+    cachedInput: 60,
+    outputTotal: 20,
+    reasoningOutput: 10,
+  };
+  file.byEffort = { high: partial };
+  const periodDay = file.period?.days['2026-07-20'];
+  assert.ok(periodDay);
+  periodDay.byEffort = { high: partial };
+
+  const view = buildCodexUsageView(snapshot, NOW);
+  const unknown = view.last7Days.efforts.find((row) => row.key === 'unknown');
+  const effortProcessed = view.last7Days.efforts.reduce(
+    (sum, row) => sum + row.totals.processed,
+    0,
+  );
+
+  assert.equal(unknown?.totals.processed, 480);
+  assert.equal(unknown?.totals.cachedInput, 340);
+  assert.equal(unknown?.totals.reasoning, 50);
+  assert.equal(effortProcessed, view.last7Days.total.processed);
+});
+
+test('zero-value unknown effort buckets stay out of every rendered scope', () => {
+  const snapshot = snapshotFixture();
+  for (const file of snapshot.files) {
+    file.byEffort.unknown = { inputTotal: 0, outputTotal: 0 };
+    for (const day of Object.values(file.period?.days ?? {})) {
+      day.byEffort.unknown = { inputTotal: 0, outputTotal: 0 };
+    }
+  }
+
+  const view = buildCodexUsageView(snapshot, NOW);
+
+  assert.equal(view.allTime.efforts.some((row) => row.key === 'unknown'), false);
+  assert.equal(view.last30Days.efforts.some((row) => row.key === 'unknown'), false);
+  assert.equal(
+    view.recentThreads.some((row) => row.efforts.includes('unknown')),
+    false,
+  );
+});
+
 test('incomplete session timestamps never invent a multi-year duration', () => {
   const snapshot = snapshotFixture();
   snapshot.files[0].session.startedAt = undefined;
diff --git a/src/test/codexWebviewFixtures.ts b/src/test/codexWebviewFixtures.ts
index 35f96f21..f717ea96 100644
--- a/src/test/codexWebviewFixtures.ts
+++ b/src/test/codexWebviewFixtures.ts
@@ -1,6 +1,8 @@
 import { CodexProviderSnapshot } from '../providers/codex/codexProvider';
 import { CodexFileAggregate } from '../providers/codex/codexIndex';
 import { ProviderTokenCounts } from '../providers/providerTypes';
+import { hourKeyInZone } from '../dateKeys';
+import { CODEX_ROLLING_HOURLY_DAYS } from '../providers/codex/codexPeriodIndex';
 import { codexFixtureIdentityKey, snapshotFixture } from './codexFixtures';
 
 export const CODEX_WEBVIEW_NOW = Date.parse('2026-07-20T12:00:00.000Z');
@@ -52,6 +54,11 @@ function generatedFile(index: number, template: CodexFileAggregate): CodexFileAg
     compactCount: index % 7 === 0 ? 1 : 0,
     taskCompleteCount: role === 'root' ? 1 : 0,
   };
+  const hour = hourKeyInZone(new Date(endedAt), 'Asia/Hong_Kong');
+  const hourlySlice = {
+    total: { ...total },
+    byModel: { [model]: { ...total } },
+  };
 
   return {
     ...structuredClone(template),
@@ -86,19 +93,14 @@ function generatedFile(index: number, template: CodexFileAggregate): CodexFileAg
         },
       },
     },
-    today: dayKey === '2026-07-20'
-      ? {
-          day: dayKey,
-          timeZone: 'Asia/Hong_Kong',
-          indexedThrough: 1,
-          hours: {
-            [String(8 + (index % 4)).padStart(2, '0')]: {
-              total: { ...total },
-              byModel: { [model]: { ...total } },
-            },
-          },
-        }
-      : undefined,
+    today: {
+      day: '2026-07-20',
+      timeZone: 'Asia/Hong_Kong',
+      indexedThrough: 1,
+      windowDays: CODEX_ROLLING_HOURLY_DAYS,
+      days: { [dayKey]: { [hour]: hourlySlice } },
+      hours: dayKey === '2026-07-20' ? { [hour]: hourlySlice } : {},
+    },
   };
 }
 
@@ -113,10 +115,36 @@ export function codexWebviewFixture(): CodexProviderSnapshot {
     totalBytes: 3_000_000,
     complete: false,
   };
+  const hourlyDays = Object.fromEntries(
+    [...new Set(files.flatMap((file) => Object.keys(file.today?.days ?? {})))]
+      .map((day) => {
+        const totalFiles = files.filter((file) => file.today?.days?.[day]).length;
+        return [day, {
+          day,
+          indexedFiles: totalFiles,
+          totalFiles,
+          indexedBytes: totalFiles,
+          totalBytes: totalFiles,
+          complete: true,
+        }];
+      }),
+  );
+  const hourlyCoverage = {
+    timeZone: 'Asia/Hong_Kong',
+    asOfDay: '2026-07-20',
+    windowDays: CODEX_ROLLING_HOURLY_DAYS,
+    indexedFiles: files.length,
+    totalFiles: files.length,
+    indexedBytes: files.length,
+    totalBytes: files.length,
+    complete: false,
+    days: hourlyDays,
+  };
   return {
     ...base,
     files,
     total: sumTotals(files),
+    hourlyCoverage,
     weeklyValueInputs: {
       observations: [
         {
@@ -171,6 +199,7 @@ export function codexWebviewFixture(): CodexProviderSnapshot {
         last30Days: { ...periodCoverage },
         allTime: { ...periodCoverage },
       },
+      hourly: hourlyCoverage,
       today: {
         timeZone: 'Asia/Hong_Kong',
         day: '2026-07-20',
@@ -232,6 +261,20 @@ export function unknownModelCodexWebviewFixture(): CodexProviderSnapshot {
                 },
               ]),
             ),
+            days: Object.fromEntries(
+              Object.entries(file.today.days ?? {}).map(([day, hours]) => [
+                day,
+                Object.fromEntries(
+                  Object.entries(hours).map(([hour, slice]) => [
+                    hour,
+                    {
+                      ...slice,
+                      byModel: { 'unknown-model-fixture': { ...slice.total } },
+                    },
+                  ]),
+                ),
+              ]),
+            ),
           }
         : undefined,
     })),
diff --git a/src/test/combinedHeatmap.test.ts b/src/test/combinedHeatmap.test.ts
new file mode 100644
index 00000000..66f74303
--- /dev/null
+++ b/src/test/combinedHeatmap.test.ts
@@ -0,0 +1,274 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import {
+  claudeDailyPointsFromUsage,
+  codexDailyPointsFromUsage,
+  combinedHeatmapFilename,
+  combinedHeatmapMarkdown,
+  mergeCombinedDailyUsage,
+  sanitizeCombinedHeatmapTitle,
+  selectCombinedHeatmapWindow,
+} from '../combinedHeatmap';
+import {
+  ACADEMIC_VIOLET_SCALE,
+  customCombinedHeatmapScale,
+  normalizeCombinedHeatmapAccent,
+  normalizeCombinedHeatmapIntensityMode,
+  normalizeCombinedHeatmapPalette,
+  renderCombinedHeatmapSvg,
+} from '../combinedHeatmapSvg';
+
+function relativeLuminance(hex: string): number {
+  const channels = [1, 3, 5].map((start) => {
+    const value = Number.parseInt(hex.slice(start, start + 2), 16) / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2];
+}
+
+function contrastRatio(foreground: string, background: string): number {
+  const foregroundLuminance = relativeLuminance(foreground);
+  const backgroundLuminance = relativeLuminance(background);
+  return (Math.max(foregroundLuminance, backgroundLuminance) + 0.05) /
+    (Math.min(foregroundLuminance, backgroundLuminance) + 0.05);
+}
+
+test('provider mappings preserve the processed-token formulas without double counting', () => {
+  const claude = claudeDailyPointsFromUsage({
+    '2026-07-20': { tokens: 100, cost: 2, sessions: 1 },
+  });
+  const codex = codexDailyPointsFromUsage([{
+    day: '2026-07-20',
+    total: {
+      input: 200,
+      output: 50,
+      cachedInput: 190,
+      reasoning: 40,
+      processed: 99_999,
+    },
+  }]);
+  assert.deepEqual(claude, [{ dateISO: '2026-07-20', processed: 100 }]);
+  assert.deepEqual(codex, [{ dateISO: '2026-07-20', processed: 250 }]);
+});
+
+test('merge de-duplicates identical provider days and zero-fills the missing provider', () => {
+  const daily = mergeCombinedDailyUsage(
+    [
+      { dateISO: '2026-07-19', processed: 30 },
+      { dateISO: '2026-07-19', processed: 30 },
+    ],
+    [
+      { dateISO: '2026-07-19', processed: 5 },
+      { dateISO: '2026-07-20', processed: 7 },
+    ],
+  );
+  assert.deepEqual(daily, {
+    '2026-07-19': {
+      dateISO: '2026-07-19',
+      claudeProcessed: 30,
+      codexProcessed: 5,
+      combinedProcessed: 35,
+    },
+    '2026-07-20': {
+      dateISO: '2026-07-20',
+      claudeProcessed: 0,
+      codexProcessed: 7,
+      combinedProcessed: 7,
+    },
+  });
+});
+
+test('conflicting duplicate provider days fail closed instead of inflating output', () => {
+  assert.throws(
+    () => mergeCombinedDailyUsage([
+      { dateISO: '2026-07-19', processed: 10 },
+      { dateISO: '2026-07-19', processed: 20 },
+    ], []),
+    /Conflicting duplicate daily aggregate/,
+  );
+});
+
+test('single-provider and empty inputs remain valid instead of producing a blank compare contract', () => {
+  assert.deepEqual(
+    mergeCombinedDailyUsage([{ dateISO: '2026-07-20', processed: 9 }], []),
+    {
+      '2026-07-20': {
+        dateISO: '2026-07-20',
+        claudeProcessed: 9,
+        codexProcessed: 0,
+        combinedProcessed: 9,
+      },
+    },
+  );
+  assert.deepEqual(
+    mergeCombinedDailyUsage([], [{ dateISO: '2026-07-20', processed: 11 }]),
+    {
+      '2026-07-20': {
+        dateISO: '2026-07-20',
+        claudeProcessed: 0,
+        codexProcessed: 11,
+        combinedProcessed: 11,
+      },
+    },
+  );
+  assert.deepEqual(mergeCombinedDailyUsage([], []), {});
+});
+
+test('range boundaries use inclusive configured-timezone date keys', () => {
+  const daily = mergeCombinedDailyUsage([
+    { dateISO: '2026-06-20', processed: 1 },
+    { dateISO: '2026-06-21', processed: 2 },
+    { dateISO: '2026-07-20', processed: 3 },
+    { dateISO: '2026-07-21', processed: 4 },
+  ], []);
+  const window = selectCombinedHeatmapWindow(daily, '30d', '2026-07-20');
+  assert.equal(window.startDateISO, '2026-06-21');
+  assert.deepEqual(Object.keys(window.daily), ['2026-06-21', '2026-07-20']);
+  assert.equal(window.totals.combinedProcessed, 5);
+});
+
+test('SVG is deterministic and tooltips disclose both provider totals and the combined total', () => {
+  assert.deepEqual(ACADEMIC_VIOLET_SCALE, [
+    '#ebedf0', '#eee8f8', '#d8c9f1', '#bca5e6', '#8668c7', '#4f2f87',
+  ]);
+  const daily = mergeCombinedDailyUsage(
+    [{ dateISO: '2026-07-20', processed: 1_200_000 }],
+    [{ dateISO: '2026-07-20', processed: 300_000 }],
+  );
+  const options = { range: '30d' as const, endDateISO: '2026-07-20', title: 'Local AI activity' };
+  const first = renderCombinedHeatmapSvg(daily, options);
+  const second = renderCombinedHeatmapSvg(daily, options);
+  assert.equal(first, second);
+  assert.match(first, /2026-07-20 · Claude: 1\.2M · Codex: 300K · Combined: 1\.5M processed tokens/);
+  assert.match(first, /not productivity, billing, or provider equivalence/);
+  assert.match(first, /role="img"/);
+  assert.ok(contrastRatio('#2f2142', '#fcfaff') >= 4.5);
+  assert.ok(contrastRatio('#685a77', '#fcfaff') >= 4.5);
+  assert.match(first, new RegExp(ACADEMIC_VIOLET_SCALE[ACADEMIC_VIOLET_SCALE.length - 1], 'i'));
+  assert.doesNotMatch(first, /#1d4ed8/i);
+  const orderedRamp = ACADEMIC_VIOLET_SCALE
+    .map((color) => `fill="${color}"`)
+    .join('[\\s\\S]*');
+  assert.match(first, new RegExp(orderedRamp, 'i'));
+});
+
+test('combined heatmap supports curated and sanitized custom colour ramps', () => {
+  const daily = mergeCombinedDailyUsage(
+    [{ dateISO: '2026-07-20', processed: 100 }],
+    [{ dateISO: '2026-07-20', processed: 50 }],
+  );
+  const custom = customCombinedHeatmapScale('#0f766e');
+  assert.equal(custom.length, 6);
+  assert.equal(custom[custom.length - 1], '#0f766e');
+
+  const svg = renderCombinedHeatmapSvg(daily, {
+    range: '30d',
+    endDateISO: '2026-07-20',
+    palette: 'custom',
+    customAccent: '#0F766E',
+  });
+  assert.match(svg, /#0f766e/i);
+
+  const invalid = renderCombinedHeatmapSvg(daily, {
+    range: '30d',
+    endDateISO: '2026-07-20',
+    palette: 'custom',
+    customAccent: 'url(javascript:alert(1))',
+  });
+  assert.doesNotMatch(invalid, /javascript|url\(/i);
+  assert.match(invalid, new RegExp(ACADEMIC_VIOLET_SCALE[ACADEMIC_VIOLET_SCALE.length - 1], 'i'));
+
+  assert.equal(normalizeCombinedHeatmapPalette('unexpected'), 'academicViolet');
+  assert.equal(normalizeCombinedHeatmapAccent('#fff'), '#4f2f87');
+  assert.equal(normalizeCombinedHeatmapAccent(' #0F766E '), '#0f766e');
+  const nearWhite = customCombinedHeatmapScale('#ffffff');
+  assert.notEqual(nearWhite[nearWhite.length - 1], '#ffffff');
+  for (let index = 1; index < nearWhite.length; index++) {
+    assert.ok(
+      relativeLuminance(nearWhite[index]) < relativeLuminance(nearWhite[index - 1]),
+      `${nearWhite[index]} should be darker than ${nearWhite[index - 1]}`,
+    );
+  }
+});
+
+test('combined heatmap exposes deterministic quantile, logarithmic, and linear intensity modes', () => {
+  assert.equal(normalizeCombinedHeatmapIntensityMode('quantile'), 'quantile');
+  assert.equal(normalizeCombinedHeatmapIntensityMode('logarithmic'), 'logarithmic');
+  assert.equal(normalizeCombinedHeatmapIntensityMode('linear'), 'linear');
+  assert.equal(normalizeCombinedHeatmapIntensityMode('unexpected'), 'quantile');
+
+  const daily = mergeCombinedDailyUsage([
+    { dateISO: '2026-07-17', processed: 1 },
+    { dateISO: '2026-07-18', processed: 9 },
+    { dateISO: '2026-07-19', processed: 99 },
+    { dateISO: '2026-07-20', processed: 999 },
+  ], []);
+  const base = { range: '30d' as const, endDateISO: '2026-07-20' };
+  const logarithmic = renderCombinedHeatmapSvg(daily, { ...base, intensityMode: 'logarithmic' });
+  const linear = renderCombinedHeatmapSvg(daily, { ...base, intensityMode: 'linear' });
+  const quantile = renderCombinedHeatmapSvg(daily, { ...base, intensityMode: 'quantile' });
+
+  assert.notEqual(logarithmic, linear);
+  assert.notEqual(quantile, linear);
+  assert.equal(
+    logarithmic,
+    renderCombinedHeatmapSvg(daily, { ...base, intensityMode: 'logarithmic' }),
+  );
+});
+
+test('30d and 90d SVG windows render every date from non-Sunday starts in the correct weekday row', () => {
+  const endDateISO = '2026-07-22'; // Wednesday; 30d starts Tuesday, 90d starts Friday.
+  const thirty = renderCombinedHeatmapSvg({}, { range: '30d', endDateISO });
+  const ninety = renderCombinedHeatmapSvg({}, { range: '90d', endDateISO });
+
+  assert.equal((thirty.match(/processed tokens<\/title>/g) ?? []).length, 30);
+  assert.match(thirty, /<rect x="38" y="91"[^>]*><title>2026-06-23 · Claude: 0 · Codex: 0 · Combined: 0 processed tokens<\/title>/);
+  assert.equal((ninety.match(/processed tokens<\/title>/g) ?? []).length, 90);
+  assert.match(ninety, /<rect x="38" y="136"[^>]*><title>2026-04-24 · Claude: 0 · Codex: 0 · Combined: 0 processed tokens<\/title>/);
+});
+
+test('combined rendering zero-fills a date absent from both providers', () => {
+  const daily = mergeCombinedDailyUsage([], [
+    { dateISO: '2026-06-24', processed: 5 },
+  ]);
+  const svg = renderCombinedHeatmapSvg(daily, {
+    range: '30d',
+    endDateISO: '2026-07-22',
+  });
+
+  assert.match(svg, /2026-06-23 · Claude: 0 · Codex: 0 · Combined: 0 processed tokens/);
+  assert.match(svg, /2026-06-24 · Claude: 0 · Codex: 5 · Combined: 5 processed tokens/);
+});
+
+test('share artifact cannot serialize privacy canaries from extra source fields', () => {
+  const source = {
+    '2026-07-20': {
+      dateISO: '2026-07-20',
+      claudeProcessed: 10,
+      codexProcessed: 20,
+      combinedProcessed: 30,
+      accountFingerprint: 'PRIVACY_CANARY_ACCOUNT',
+      projectName: 'PRIVACY_CANARY_PROJECT',
+      threadTitle: 'PRIVACY_CANARY_THREAD',
+      localPath: '/PRIVACY_CANARY_PATH',
+      logContent: 'PRIVACY_CANARY_LOG',
+    },
+  } as unknown as Record<string, import('../combinedHeatmap').CombinedDayUsage>;
+  const svg = renderCombinedHeatmapSvg(source, {
+    range: '30d',
+    endDateISO: '2026-07-20',
+    title: 'Safe aggregate',
+  });
+  assert.doesNotMatch(svg, /PRIVACY_CANARY/);
+});
+
+test('title, filename, and Markdown are bounded and deterministic', () => {
+  assert.equal(sanitizeCombinedHeatmapTitle('  Team\nactivity  ', 'Fallback'), 'Team activity');
+  assert.equal(sanitizeCombinedHeatmapTitle('', 'Fallback'), 'Fallback');
+  const filename = combinedHeatmapFilename('90d', '2026-07-20');
+  assert.equal(filename, 'claude-codex-activity-90d-2026-07-20.svg');
+  assert.equal(
+    combinedHeatmapMarkdown(filename, 'Claude + Codex [activity]'),
+    '![Claude + Codex activity](claude-codex-activity-90d-2026-07-20.svg)',
+  );
+});
diff --git a/src/test/combinedHeatmapI18n.test.ts b/src/test/combinedHeatmapI18n.test.ts
new file mode 100644
index 00000000..0fe3b757
--- /dev/null
+++ b/src/test/combinedHeatmapI18n.test.ts
@@ -0,0 +1,60 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { SupportedLanguage } from '../types';
+
+// webview.ts imports vscode, so this repository-policy test inspects the source
+// instead of loading the module under plain node:test. This mirrors the settings
+// catalogue coverage guard in quotaI18n.test.ts.
+const SOURCE = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'webview.ts'), 'utf8');
+const LOCALES: SupportedLanguage[] = ['en', 'de-DE', 'zh-TW', 'zh-CN', 'ja', 'ko', 'pt-BR', 'id'];
+const NON_ENGLISH = LOCALES.filter((locale) => locale !== 'en');
+
+function copyFields(): string[] {
+  const start = SOURCE.indexOf('interface CombinedHeatmapUiCopy {');
+  const end = SOURCE.indexOf('\n}', start);
+  assert.ok(start >= 0 && end > start, 'CombinedHeatmapUiCopy interface must exist');
+  const fields = [...SOURCE.slice(start, end).matchAll(/^\s+(\w+): string;$/gm)]
+    .map((match) => match[1]);
+  assert.equal(fields.length, 38, 'the Share studio copy contract changed; update its locale coverage');
+  return fields;
+}
+
+function copyFunction(): string {
+  const start = SOURCE.indexOf('function combinedHeatmapUiCopy(');
+  const end = SOURCE.indexOf('\nexport class UsageWebviewProvider', start);
+  assert.ok(start >= 0 && end > start, 'combinedHeatmapUiCopy must exist');
+  return SOURCE.slice(start, end);
+}
+
+function localeBranch(locale: SupportedLanguage): string | undefined {
+  const source = copyFunction();
+  const marker = `if (locale === '${locale}')`;
+  const markerStart = source.indexOf(marker);
+  if (markerStart < 0) {
+    return undefined;
+  }
+  const objectStart = source.indexOf('return {', markerStart);
+  const objectEnd = source.indexOf('\n    };', objectStart);
+  assert.ok(objectStart >= 0 && objectEnd > objectStart, `${locale}: locale object must be parseable`);
+  return source.slice(objectStart, objectEnd);
+}
+
+test('every non-English locale owns complete active Share studio copy', () => {
+  const translatedFields = copyFields().filter((field) => !field.startsWith('intensity'));
+  const missing: string[] = [];
+  for (const locale of NON_ENGLISH) {
+    const branch = localeBranch(locale);
+    if (!branch) {
+      missing.push(`${locale}:branch`);
+      continue;
+    }
+    for (const field of translatedFields) {
+      if (!new RegExp(`\\b${field}:`).test(branch)) {
+        missing.push(`${locale}:${field}`);
+      }
+    }
+  }
+  assert.deepEqual(missing, [], `missing Share studio translations: ${missing.join(', ')}`);
+});
diff --git a/src/test/dataLoader.test.ts b/src/test/dataLoader.test.ts
index 1cbc65d0..2f420127 100644
--- a/src/test/dataLoader.test.ts
+++ b/src/test/dataLoader.test.ts
@@ -6,7 +6,8 @@ import * as path from 'node:path';
 
 import { scanUsageManifest } from '../claudeUsageFiles';
 import { ClaudeDataLoader } from '../dataLoader';
-import { ClaudeUsageRecord } from '../types';
+import { I18n } from '../i18n';
+import { ClaudeUsageRecord, ContentAnalysis } from '../types';
 
 const tempRoots: string[] = [];
 
@@ -40,6 +41,18 @@ test('getCurrentContextInfo reports a 1M window for Opus 5, with or without the
   }
 });
 
+test('getCurrentContextInfo recognizes Fable 5.1 and GPT-6 Astra context windows', () => {
+  const fable = ClaudeDataLoader.getCurrentContextInfo([record('claude-fable-5-1')]);
+  assert.ok(fable, 'expected Fable 5.1 context info, got null');
+  assert.equal(fable!.windowTokens, 1_000_000);
+  assert.equal(fable!.estimated, false);
+
+  const astra = ClaudeDataLoader.getCurrentContextInfo([record('gpt-6-astra')]);
+  assert.ok(astra, 'expected GPT-6 Astra context info, got null');
+  assert.equal(astra!.windowTokens, 1_050_000);
+  assert.equal(astra!.estimated, false);
+});
+
 test('getCurrentContextInfo keeps the 200K window for pre-4.6 Opus and Sonnet', () => {
   for (const model of ['claude-opus-4-20250514', 'claude-sonnet-4-5-20250929', 'claude-3-5-sonnet-20241022']) {
     const info = ClaudeDataLoader.getCurrentContextInfo([record(model)]);
@@ -48,6 +61,259 @@ test('getCurrentContextInfo keeps the 200K window for pre-4.6 Opus and Sonnet',
   }
 });
 
+test('day attribution uses the configured timezone instead of the host timezone', () => {
+  const previousTimeZone = I18n.getTimezone();
+  const fixedNow = new Date('2026-07-21T02:00:00.000Z');
+  const attributionRecord = (
+    timestamp: string,
+    inputTokens: number,
+    sessionId: string,
+  ): ClaudeUsageRecord => ({
+    timestamp,
+    _sessionId: sessionId,
+    message: {
+      model: 'claude-sonnet-4-5',
+      usage: { input_tokens: inputTokens, output_tokens: 10 },
+    },
+  });
+
+  try {
+    I18n.setTimezone('America/New_York');
+    const attribution = ClaudeDataLoader.getUsageAttribution(
+      [
+        attributionRecord('2026-07-20T03:30:00.000Z', 200, 'previous-day'),
+        attributionRecord('2026-07-21T01:00:00.000Z', 100, 'configured-today'),
+      ],
+      null,
+      { kind: 'day' },
+      fixedNow,
+    );
+
+    assert.equal(attribution.totalTokens, 110);
+    assert.deepEqual(attribution.models.map(({ key, count }) => ({ key, count })), [
+      { key: 'claude-sonnet-4-5', count: 1 },
+    ]);
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
+function assertRollingAttributionUsesCivilDays(
+  kind: 'week' | 'month',
+  cases: ReadonlyArray<{
+    timeZone: string;
+    now: string;
+    outside: string;
+    outsideDay: string;
+    inside: string;
+    insideDay: string;
+  }>,
+): void {
+  const previousTimeZone = I18n.getTimezone();
+  const attributionRecord = (
+    timestamp: string,
+    inputTokens: number,
+    sessionId: string,
+  ): ClaudeUsageRecord => ({
+    timestamp,
+    _sessionId: sessionId,
+    message: {
+      model: 'claude-sonnet-4-5',
+      usage: { input_tokens: inputTokens, output_tokens: 10 },
+    },
+  });
+
+  try {
+    for (const sample of cases) {
+      I18n.setTimezone(sample.timeZone);
+      const analysis: ContentAnalysis = {
+        categories: [],
+        toolResultBreakdown: [],
+        totalEstimatedTokens: 0,
+        recentPrompts: [],
+        thinkingBySession: {},
+        thinkingByDay: {},
+        skillUses: [
+          {
+            name: 'outside-skill',
+            sessionId: 'outside',
+            day: sample.outsideDay,
+            ts: Date.parse(sample.outside),
+            estTokens: 50,
+          },
+          {
+            name: 'inside-skill',
+            sessionId: 'inside',
+            day: sample.insideDay,
+            ts: Date.parse(sample.inside),
+            estTokens: 100,
+          },
+        ],
+      };
+      const attribution = ClaudeDataLoader.getUsageAttribution(
+        [
+          attributionRecord(sample.outside, 500, 'outside'),
+          attributionRecord(sample.inside, 1_000, 'inside'),
+        ],
+        analysis,
+        { kind },
+        new Date(sample.now),
+      );
+
+      assert.equal(attribution.totalTokens, 1_010, sample.timeZone);
+      assert.deepEqual(attribution.skills.map(({ key }) => key), ['inside-skill'], sample.timeZone);
+    }
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+}
+
+test('week attribution uses seven configured-zone civil days', () => {
+  assertRollingAttributionUsesCivilDays('week', [
+    {
+      timeZone: 'Asia/Tokyo',
+      now: '2026-07-21T23:30:00.000Z',
+      outside: '2026-07-15T05:00:00.000Z',
+      outsideDay: '2026-07-15',
+      inside: '2026-07-15T15:30:00.000Z',
+      insideDay: '2026-07-16',
+    },
+    {
+      timeZone: 'Pacific/Honolulu',
+      now: '2026-07-21T05:00:00.000Z',
+      outside: '2026-07-14T07:00:00.000Z',
+      outsideDay: '2026-07-13',
+      inside: '2026-07-14T12:00:00.000Z',
+      insideDay: '2026-07-14',
+    },
+  ]);
+});
+
+test('month attribution uses thirty configured-zone civil days', () => {
+  assertRollingAttributionUsesCivilDays('month', [
+    {
+      timeZone: 'Asia/Tokyo',
+      now: '2026-07-21T23:30:00.000Z',
+      outside: '2026-06-22T05:00:00.000Z',
+      outsideDay: '2026-06-22',
+      inside: '2026-06-22T15:30:00.000Z',
+      insideDay: '2026-06-23',
+    },
+    {
+      timeZone: 'Pacific/Honolulu',
+      now: '2026-07-21T05:00:00.000Z',
+      outside: '2026-06-21T07:00:00.000Z',
+      outsideDay: '2026-06-20',
+      inside: '2026-06-21T12:00:00.000Z',
+      insideDay: '2026-06-21',
+    },
+  ]);
+});
+
+test('rolling attribution rebuckets cached skill-use timestamps after a timezone change', () => {
+  const previousTimeZone = I18n.getTimezone();
+  const outside = '2026-07-15T05:00:00.000Z';
+  const inside = '2026-07-15T15:30:00.000Z';
+  const analysis: ContentAnalysis = {
+    categories: [],
+    toolResultBreakdown: [],
+    totalEstimatedTokens: 0,
+    recentPrompts: [],
+    thinkingBySession: {},
+    thinkingByDay: {},
+    skillUses: [
+      {
+        name: 'outside-skill',
+        sessionId: 'outside',
+        day: '2026-07-16',
+        ts: Date.parse(outside),
+        estTokens: 50,
+      },
+      {
+        name: 'inside-skill',
+        sessionId: 'inside',
+        day: '2026-07-15',
+        ts: Date.parse(inside),
+        estTokens: 100,
+      },
+    ],
+  };
+
+  try {
+    I18n.setTimezone('Asia/Tokyo');
+    const attribution = ClaudeDataLoader.getUsageAttribution(
+      [
+        {
+          timestamp: outside,
+          _sessionId: 'outside',
+          message: {
+            model: 'claude-sonnet-4-5',
+            usage: { input_tokens: 500, output_tokens: 10 },
+          },
+        },
+        {
+          timestamp: inside,
+          _sessionId: 'inside',
+          message: {
+            model: 'claude-sonnet-4-5',
+            usage: { input_tokens: 1_000, output_tokens: 10 },
+          },
+        },
+      ],
+      analysis,
+      { kind: 'week' },
+      new Date('2026-07-21T23:30:00.000Z'),
+    );
+
+    assert.equal(attribution.totalTokens, 1_010);
+    assert.deepEqual(attribution.skills.map(({ key }) => key), ['inside-skill']);
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
+test('share-card rolling ranges use configured-zone civil days', () => {
+  const previousTimeZone = I18n.getTimezone();
+  const fixedNow = new Date('2026-07-08T04:00:00.000Z');
+  const shareRecord = (
+    timestamp: string,
+    inputTokens: number,
+    id: string,
+  ): ClaudeUsageRecord => ({
+    timestamp,
+    requestId: `request-${id}`,
+    message: {
+      id: `message-${id}`,
+      model: 'claude-sonnet-4-5',
+      usage: { input_tokens: inputTokens, output_tokens: 0 },
+    },
+  });
+  const cases = [
+    { range: 'week', outside: '2026-07-01T06:00:00.000Z', inside: '2026-07-01T12:00:00.000Z' },
+    { range: 'last30', outside: '2026-06-08T06:00:00.000Z', inside: '2026-06-08T12:00:00.000Z' },
+    { range: 'year', outside: '2025-07-08T06:00:00.000Z', inside: '2025-07-08T12:00:00.000Z' },
+  ] as const;
+
+  try {
+    I18n.setTimezone('Pacific/Honolulu');
+    for (const { range, outside, inside } of cases) {
+      const input = ClaudeDataLoader.buildShareInput(
+        [
+          shareRecord(outside, 500, `${range}-outside`),
+          shareRecord(inside, 1_000, `${range}-inside`),
+        ],
+        range,
+        'all',
+        fixedNow,
+      );
+      assert.equal(input.rangeData.totalInputTokens, 1_000, range);
+      assert.deepEqual(input.dailyDates, [inside.slice(0, 10)], range);
+    }
+  } finally {
+    I18n.setTimezone(previousTimeZone);
+  }
+});
+
 test('an injected manifest is authoritative and returns anonymous load counters', async () => {
   const manifestRoot = await mkdtemp(path.join(os.tmpdir(), 'ccu-loader-manifest-'));
   const emptyArgumentRoot = await mkdtemp(path.join(os.tmpdir(), 'ccu-loader-empty-'));
@@ -218,3 +484,121 @@ test('request ID presence may degrade within one message without double-counting
     assert.equal(records.length, 1, name);
   }
 });
+
+test('content analysis keeps framework injection out of user prompt samples and emits numeric-only overhead', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ccu-loader-framework-'));
+  tempRoots.push(root);
+  const project = path.join(root, 'projects', '-tmp-project');
+  await mkdir(project, { recursive: true });
+  const timestamp = new Date().toISOString();
+  const lines = [
+    {
+      type: 'user',
+      uuid: 'user-1',
+      timestamp,
+      cwd: '/private/project-sentinel',
+      message: { role: 'user', content: 'Please fix the login bug carefully.' },
+    },
+    {
+      type: 'user',
+      uuid: 'user-web-component',
+      timestamp,
+      cwd: '/private/project-sentinel',
+      message: {
+        role: 'user',
+        content: '<my-component data-mode="safe">Please review this component.</my-component>',
+      },
+    },
+    {
+      type: 'user',
+      uuid: 'meta-1',
+      timestamp,
+      isMeta: true,
+      message: { role: 'user', content: 'PRIVATE_META_FRAMEWORK_TEXT' },
+    },
+    {
+      type: 'user',
+      uuid: 'command-1',
+      timestamp,
+      message: { role: 'user', content: '<command-name>/review</command-name>' },
+    },
+    {
+      type: 'user',
+      uuid: 'reminder-1',
+      timestamp,
+      message: {
+        role: 'user',
+        content: [{
+          type: 'text',
+          text: 'User-looking prefix <system-reminder>PRIVATE_REMINDER</system-reminder>',
+        }],
+      },
+    },
+    {
+      type: 'user',
+      uuid: 'compaction-1',
+      timestamp,
+      message: {
+        role: 'user',
+        content: 'This session is being continued from a previous conversation PRIVATE_COMPACTION_SENTINEL',
+      },
+    },
+    {
+      type: 'assistant',
+      uuid: 'assistant-1',
+      timestamp,
+      message: {
+        role: 'assistant',
+        model: 'claude-sonnet-4-5',
+        usage: { input_tokens: 10, output_tokens: 2 },
+        content: [{ type: 'tool_use', id: 'tool-private-id', name: 'Skill', input: { skill: 'review' } }],
+      },
+    },
+    {
+      type: 'user',
+      uuid: 'tool-result-1',
+      timestamp,
+      message: {
+        role: 'user',
+        content: [{ type: 'tool_result', tool_use_id: 'tool-private-id', content: 'PRIVATE_SKILL_PREAMBLE' }],
+      },
+    },
+  ];
+  const body = lines.map((line) => JSON.stringify(line)).join('\n') + '\n';
+  await writeFile(path.join(project, 'session.jsonl'), body);
+  const manifest = await scanUsageManifest([root]);
+
+  const loaded = await ClaudeDataLoader.loadUsageRecords(root, {
+    analyzeContent: true,
+    windowDays: 30,
+    manifest,
+  });
+  const analysis = loaded.contentAnalysis;
+  assert.ok(analysis);
+  assert.deepEqual(analysis!.recentPrompts.map((prompt) => prompt.text), [
+    'Please fix the login bug carefully.',
+    '<my-component data-mode="safe">Please review this component.</my-component>',
+  ]);
+  assert.ok((analysis!.frameworkOverhead?.frameworkEstimatedTokens ?? 0) > 0);
+  assert.ok(
+    (analysis!.frameworkOverhead?.observedInputEstimatedTokens ?? 0) >=
+      (analysis!.frameworkOverhead?.frameworkEstimatedTokens ?? 0),
+  );
+  assert.ok((analysis!.frameworkOverhead?.userAuthoredEstimatedTokens ?? 0) > 0);
+  assert.ok((analysis!.frameworkOverhead?.toolResultEstimatedTokens ?? 0) > 0);
+  assert.deepEqual(
+    analysis!.frameworkOverhead?.components.map((component) => component.kind),
+    ['command-echo', 'meta', 'skill-preamble', 'system-reminder', 'tool-result-envelope'],
+  );
+  const serialized = JSON.stringify(analysis!.frameworkOverhead);
+  for (const privateText of [
+    'PRIVATE_META_FRAMEWORK_TEXT',
+    'PRIVATE_REMINDER',
+    'PRIVATE_SKILL_PREAMBLE',
+    'PRIVATE_COMPACTION_SENTINEL',
+    '/private/project-sentinel',
+    'tool-private-id',
+  ]) {
+    assert.equal(serialized.includes(privateText), false);
+  }
+});
diff --git a/src/test/dateKeys.test.ts b/src/test/dateKeys.test.ts
index 390c819a..ee9372fa 100644
--- a/src/test/dateKeys.test.ts
+++ b/src/test/dateKeys.test.ts
@@ -2,6 +2,7 @@ import { test } from 'node:test';
 import * as assert from 'node:assert/strict';
 import {
   dayKeyInZone,
+  formatHourLabel,
   hourKeyInZone,
   monthKeyInZone,
   resolveTimeZone,
@@ -93,6 +94,15 @@ test('hour keys use the same target zone and a stable 00-23 clock', () => {
   assert.equal(hourKeyInZone(new Date('nonsense'), 'UTC'), '');
 });
 
+test('hour labels use one strict HH:00 formatter for every provider', () => {
+  assert.equal(formatHourLabel('00'), '00:00');
+  assert.equal(formatHourLabel('09'), '09:00');
+  assert.equal(formatHourLabel('23'), '23:00');
+  assert.equal(formatHourLabel('24'), '');
+  assert.equal(formatHourLabel('9'), '');
+  assert.equal(formatHourLabel('09:00'), '');
+});
+
 test('timezone resolution returns a usable canonical zone', () => {
   assert.equal(resolveTimeZone('Asia/Hong_Kong'), 'Asia/Hong_Kong');
   assert.notEqual(resolveTimeZone(''), '');
diff --git a/src/test/extensionRefreshRouting.test.ts b/src/test/extensionRefreshRouting.test.ts
index 9b662b2f..d7299725 100644
--- a/src/test/extensionRefreshRouting.test.ts
+++ b/src/test/extensionRefreshRouting.test.ts
@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { WindowActivityGate } from '../refreshPolicy';
+import { ResourceOwnershipRegistry } from '../resourceOwnership';
 
 type ExtensionModule = typeof import('../extension');
 
@@ -33,7 +34,14 @@ function loadExtensionModule(): ExtensionModule {
 const { ClaudeCodeUsageExtension } = loadExtensionModule();
 
 function bareExtension(): any {
-  return Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  extension.resourceOwnership = new ResourceOwnershipRegistry();
+  extension.codexWatcherLeases = new Map();
+  extension.pendingResourceStops = new Set();
+  extension.resourceStopFailure = null;
+  extension.codexWatcherGeneration = 0;
+  extension.disposed = false;
+  return extension;
 }
 
 test('Claude watcher refresh stays Claude-only while manual refresh updates both providers', async () => {
diff --git a/src/test/extensionWindowActivity.test.ts b/src/test/extensionWindowActivity.test.ts
index 727f8e53..de3d9f0a 100644
--- a/src/test/extensionWindowActivity.test.ts
+++ b/src/test/extensionWindowActivity.test.ts
@@ -5,8 +5,24 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 
 import { ClaudeDataLoader } from '../dataLoader';
-import { WindowActivityGate } from '../refreshPolicy';
+import {
+  RefreshSingleFlight,
+  WindowActivityGate,
+} from '../refreshPolicy';
+import { createClaudeUsageIndex } from '../claudeIncrementalIndex';
+import {
+  beginBackgroundWork,
+  createBackgroundWorkState,
+  pauseBackgroundWork,
+  recordBackgroundWorkFailure,
+  recordBackgroundWorkProgress,
+} from '../backgroundWorkState';
+import { ResourceOwnershipRegistry } from '../resourceOwnership';
 import { snapshotFixture } from './codexFixtures';
+import {
+  createEmptyQuotaObservationStore,
+  mergeQuotaCaptures,
+} from '../quotaObservationStore';
 
 type ExtensionModule = typeof import('../extension');
 
@@ -16,7 +32,10 @@ function loadExtensionModule(): ExtensionModule {
   };
   const originalLoad = moduleLoader._load;
   const vscodeStub: any = new Proxy(function () {}, {
-    get: (_target, property) => property === 'then' ? undefined : vscodeStub,
+    get: (_target, property) => {
+      if (property === 'then' || property === 'workspaceFolders') return undefined;
+      return vscodeStub;
+    },
     apply: () => vscodeStub,
     construct: () => vscodeStub,
   });
@@ -33,10 +52,60 @@ function loadExtensionModule(): ExtensionModule {
   }
 }
 
-const { ClaudeCodeUsageExtension } = loadExtensionModule();
+const {
+  ClaudeCodeUsageExtension,
+  initializeQuotaObservationRuntime,
+} = loadExtensionModule();
 
 function bareExtension(): any {
-  return Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  const quotaSalt = 'extension-window-activity-test-salt';
+  extension.resourceOwnership = new ResourceOwnershipRegistry();
+  extension.codexWatcherLeases = new Map();
+  extension.debounceTimerLeases = new Map();
+  extension.activeAdviceNetworks = new Map();
+  extension.activeQuotaNetworks = new Map();
+  extension.codexProviderRetirements = new Set();
+  extension.activeCodexRefreshes = new Set();
+  extension.pendingResourceStops = new Set();
+  extension.resourceStopFailure = null;
+  extension.codexProviderRetirementFailure = null;
+  extension.codexBackgroundStateWrite = Promise.resolve();
+  extension.configurationGeneration = 0;
+  extension.fileWatcherGeneration = 0;
+  extension.codexWatcherGeneration = 0;
+  extension.credentialsWatcherGeneration = 0;
+  extension.disposed = false;
+  extension.codexBackgroundState = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'first-index',
+    now: 0,
+  });
+  extension.codexFirstBackfillActive = false;
+  extension.codexWorkerCancellationRequested = false;
+  extension.context = {
+    globalState: {
+      update: async () => undefined,
+    },
+  };
+  extension.outputChannel = { appendLine: () => undefined };
+  extension.quotaFingerprintSalt = quotaSalt;
+  extension.quotaObservationStore = createEmptyQuotaObservationStore();
+  extension.quotaObservationRepository = {
+    append: async (captures: any[]) => {
+      extension.quotaObservationStore = mergeQuotaCaptures(
+        extension.quotaObservationStore,
+        captures,
+        { salt: quotaSalt, now: Date.now() },
+      );
+      return extension.quotaObservationStore;
+    },
+  };
+  extension.webviewProvider = {
+    updateQuota: () => undefined,
+    updateWeeklyQuotaHistory: () => undefined,
+  };
+  return extension;
 }
 
 test('background transition stops every Claude and Codex recurring resource once', () => {
@@ -87,6 +156,34 @@ test('foreground transition resumes both providers and catches up once', () => {
   ]);
 });
 
+test('blur deadline cooperatively cancels the bounded first Codex backfill', async () => {
+  const extension = bareExtension();
+  extension.codexRefreshing = true;
+  extension.codexFirstBackfillActive = true;
+  let cancelCalls = 0;
+  extension.codexProvider = { cancelAndWait: async () => { cancelCalls += 1; } };
+  const originalSetTimeout = globalThis.setTimeout;
+  const originalClearTimeout = globalThis.clearTimeout;
+  let callback: (() => void) | undefined;
+  globalThis.setTimeout = ((fn: () => void) => {
+    callback = fn;
+    return 123 as any;
+  }) as typeof setTimeout;
+  globalThis.clearTimeout = (() => undefined) as typeof clearTimeout;
+  try {
+    extension.scheduleFirstBackfillBlurDeadline();
+    assert.equal(extension.resourceOwnership.snapshotForTests().byKind.timer, 1);
+    callback?.();
+    await Promise.resolve();
+    assert.equal(cancelCalls, 1);
+    await extension.drainResourceStops();
+    assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+    globalThis.clearTimeout = originalClearTimeout;
+  }
+});
+
 test('background window cannot arm a new polling timer', () => {
   const extension = bareExtension();
   extension.windowActivity = new WindowActivityGate(false);
@@ -196,15 +293,15 @@ test('Codex becomes available in the dashboard before a slow cold index finishes
   });
 
   const pending = extension.runCodexRefresh('startup');
-  await Promise.resolve();
-  await Promise.resolve();
+  await new Promise((resolve) => setImmediate(resolve));
 
-  assert.deepEqual(states, [{
+  assert.deepEqual(states[0], {
     available: true,
     hasData: false,
     refreshing: true,
     scannedFiles: null,
-  }]);
+  });
+  assert.ok(states.every((state) => state.available && state.refreshing));
   assert.deepEqual(liveProgress, [12]);
 
   releaseRefresh?.({ outcome: 'unavailable' });
@@ -245,8 +342,7 @@ test('a verified Codex checkpoint stays visible while its index refresh continue
   });
 
   const pending = extension.runCodexRefresh('startup');
-  await Promise.resolve();
-  await Promise.resolve();
+  await new Promise((resolve) => setImmediate(resolve));
 
   assert.ok(releaseRefresh, 'the background worker refresh should still be running');
   assert.ok(
@@ -299,11 +395,17 @@ test('Codex live index progress coalesces dashboard renders', () => {
   const originalNow = Date.now;
   let now = 1_000;
   let renders = 0;
+  const reasons: unknown[] = [];
   extension.codexProgress = null;
   extension.codexProgressLastRenderedAt = 0;
+  extension.codexBackgroundState = beginBackgroundWork(
+    extension.codexBackgroundState,
+    { trigger: 'automatic', now, reason: 'first-index' },
+  ).state;
   extension.webviewProvider = {
-    updateCodexProgress: () => {
+    updateCodexProgress: (rendered: { reason?: unknown }) => {
       renders += 1;
+      reasons.push(rendered.reason);
     },
   };
   const progress = (scannedFiles: number) => ({
@@ -330,9 +432,681 @@ test('Codex live index progress coalesces dashboard renders', () => {
     extension.onCodexIndexProgress(progress(40));
     assert.equal(renders, 2);
     assert.equal(extension.codexProgress.scannedFiles, 40);
+    assert.deepEqual(reasons, ['first-index', 'first-index']);
+  } finally {
+    Date.now = originalNow;
+  }
+});
+
+test('cooldown, user pause, and completed measurement suppress historical backfill', async () => {
+  const originalNow = Date.now;
+  Date.now = () => 1_001;
+  const snapshot = snapshotFixture();
+  snapshot.coverage.complete = false;
+  snapshot.coverage.indexedFiles = Math.max(0, snapshot.coverage.totalFiles - 1);
+  const progress = {
+    completedUnits: 1,
+    totalUnits: 2,
+    completedBytes: 10,
+    totalBytes: 20,
+  };
+  const seed = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'history-backfill',
+    now: 1_000,
+    progress,
+  });
+  const running = beginBackgroundWork(seed, {
+    trigger: 'automatic',
+    now: 1_000,
+  }).state;
+  const states = [
+    recordBackgroundWorkFailure(running, { now: 1_000 }),
+    pauseBackgroundWork(seed, { now: 1_000 }),
+    recordBackgroundWorkProgress(running, {
+      now: 1_000,
+      complete: true,
+      progress,
+    }),
+  ];
+  const allowed: boolean[] = [];
+
+  try {
+    for (const state of states) {
+      const extension = bareExtension();
+      extension.codexBackgroundState = state;
+      extension.getConfiguration = () => ({ codexEnabled: true });
+      extension.webviewProvider = { updateCodexProgress: () => undefined };
+      extension.syncProviderUi = () => undefined;
+      extension.codexProvider = {
+        isAvailable: async () => true,
+        loadPersistedSnapshot: async () => snapshot,
+        refresh: async (
+          _profile: string,
+          _onProgress: unknown,
+          allowHistoricalBackfill: boolean,
+        ) => {
+          allowed.push(allowHistoricalBackfill);
+          return {
+            outcome: 'partial',
+            snapshot,
+            diagnostic: {
+              bodyReads: 0,
+              failedFiles: 0,
+              metadataMs: 0,
+              parseMs: 0,
+              migrationPending: true,
+            },
+          };
+        },
+      };
+
+      await extension.runCodexRefresh('poll');
+      assert.equal(extension.codexBackgroundState.status, state.status);
+    }
   } finally {
     Date.now = originalNow;
   }
+
+  assert.deepEqual(allowed, [false, false, false]);
+});
+
+test('a missing persisted index invalidates same-version complete background work', async () => {
+  const extension = bareExtension();
+  const completeSnapshot = snapshotFixture();
+  const seed = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'history-backfill',
+    now: 1,
+    progress: {
+      completedUnits: 1,
+      totalUnits: 1,
+      completedBytes: 1,
+      totalBytes: 1,
+    },
+  });
+  extension.codexBackgroundState = recordBackgroundWorkProgress(
+    beginBackgroundWork(seed, { trigger: 'automatic', now: 1 }).state,
+    {
+      now: 2,
+      complete: true,
+      progress: seed.progress,
+    },
+  );
+  extension.getConfiguration = () => ({ codexEnabled: true });
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.webviewProvider = { updateCodexProgress: () => undefined };
+  extension.syncProviderUi = () => undefined;
+  let historicalAllowed: boolean | undefined;
+  extension.codexProvider = {
+    isAvailable: async () => true,
+    loadPersistedSnapshot: async () => null,
+    refresh: async (
+      _profile: string,
+      _onProgress: unknown,
+      allowHistoricalBackfill: boolean,
+    ) => {
+      historicalAllowed = allowHistoricalBackfill;
+      return {
+        outcome: 'success',
+        snapshot: completeSnapshot,
+        diagnostic: {
+          bodyReads: 1,
+          failedFiles: 0,
+          metadataMs: 1,
+          parseMs: 1,
+          migrationPending: false,
+        },
+      };
+    },
+  };
+
+  await extension.runCodexRefresh('startup');
+
+  assert.equal(historicalAllowed, true);
+  assert.equal(extension.codexBackgroundState.status, 'eligible');
+});
+
+test('a failed preflight state write never strands in-memory background work as running', async () => {
+  const extension = bareExtension();
+  const snapshot = snapshotFixture();
+  snapshot.coverage.complete = false;
+  snapshot.coverage.indexedFiles = Math.max(0, snapshot.coverage.totalFiles - 1);
+  let writes = 0;
+  extension.context.globalState.update = async () => {
+    writes += 1;
+    if (writes === 1) throw new Error('persistence unavailable');
+  };
+  extension.getConfiguration = () => ({ codexEnabled: true });
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.webviewProvider = { updateCodexProgress: () => undefined };
+  extension.syncProviderUi = () => undefined;
+  extension.codexProvider = {
+    isAvailable: async () => true,
+    loadPersistedSnapshot: async () => snapshot,
+    refresh: async () => assert.fail('worker must not start before state is durable'),
+  };
+
+  await assert.rejects(extension.runCodexRefresh('poll'), /persistence unavailable/);
+
+  assert.equal(extension.codexBackgroundState.status, 'eligible');
+  assert.equal(extension.codexBackgroundState.reason, 'resume');
+  assert.ok(writes >= 1);
+});
+
+test('background state writes are serialized and preserve their captured order', async () => {
+  const extension = bareExtension();
+  let finishFirst!: () => void;
+  const firstGate = new Promise<void>((resolve) => { finishFirst = resolve; });
+  const writes: Array<{ status: string; reason: string }> = [];
+  extension.context.globalState.update = async (_key: string, value: any) => {
+    writes.push({ status: value.status, reason: value.reason });
+    if (writes.length === 1) await firstGate;
+  };
+
+  const first = extension.saveCodexBackgroundState();
+  extension.codexBackgroundState = beginBackgroundWork(
+    extension.codexBackgroundState,
+    { trigger: 'automatic', now: 1, reason: 'first-index' },
+  ).state;
+  const second = extension.saveCodexBackgroundState();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(writes, [{ status: 'eligible', reason: 'first-index' }]);
+
+  finishFirst();
+  await Promise.all([first, second]);
+  assert.deepEqual(writes, [
+    { status: 'eligible', reason: 'first-index' },
+    { status: 'running', reason: 'first-index' },
+  ]);
+});
+
+test('a recovered index invalidates complete state and queues historical reconciliation', async () => {
+  const extension = bareExtension();
+  const pending = snapshotFixture();
+  pending.coverage.complete = false;
+  pending.coverage.indexedFiles = Math.max(0, pending.coverage.totalFiles - 1);
+  const seed = createBackgroundWorkState({
+    measurementVersion: 1,
+    reason: 'history-backfill',
+    now: 1,
+    progress: {
+      completedUnits: 1,
+      totalUnits: 1,
+      completedBytes: 1,
+      totalBytes: 1,
+    },
+  });
+  extension.codexBackgroundState = recordBackgroundWorkProgress(
+    beginBackgroundWork(seed, { trigger: 'automatic', now: 1 }).state,
+    { now: 2, complete: true, progress: seed.progress },
+  );
+  extension.getConfiguration = () => ({ codexEnabled: true });
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.webviewProvider = { updateCodexProgress: () => undefined };
+  extension.syncProviderUi = () => undefined;
+  const continuations: string[] = [];
+  extension.refreshCodexData = async (trigger: string) => {
+    continuations.push(trigger);
+  };
+  extension.codexProvider = {
+    isAvailable: async () => true,
+    loadPersistedSnapshot: async () => pending,
+    refresh: async () => ({
+      outcome: 'partial',
+      snapshot: pending,
+      diagnostic: {
+        bodyReads: 0,
+        failedFiles: 0,
+        metadataMs: 1,
+        parseMs: 1,
+        migrationPending: true,
+        indexRecovery: { reason: 'invalid-json' },
+      },
+    }),
+  };
+
+  await extension.runCodexRefresh('poll');
+  await Promise.resolve();
+  await Promise.resolve();
+
+  assert.equal(extension.codexBackgroundState.status, 'eligible');
+  assert.deepEqual(continuations, ['poll']);
+});
+
+test('successful historical progress queues one immediate continuation without a timer', async () => {
+  const extension = bareExtension();
+  const before = snapshotFixture();
+  const after = structuredClone(before);
+  before.coverage.complete = false;
+  after.coverage.complete = false;
+  before.coverage.indexedFiles = Math.max(0, before.coverage.totalFiles - 2);
+  after.coverage.indexedFiles = Math.max(0, after.coverage.totalFiles - 1);
+  before.coverage.indexedBytes = Math.max(0, before.coverage.totalBytes - 200);
+  after.coverage.indexedBytes = Math.max(0, after.coverage.totalBytes - 100);
+  const continuations: string[] = [];
+  extension.getConfiguration = () => ({ codexEnabled: true });
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.webviewProvider = { updateCodexProgress: () => undefined };
+  extension.syncProviderUi = () => undefined;
+  extension.refreshCodexData = async (trigger: string) => {
+    continuations.push(trigger);
+  };
+  extension.codexProvider = {
+    isAvailable: async () => true,
+    loadPersistedSnapshot: async () => before,
+    refresh: async () => ({
+      outcome: 'partial',
+      snapshot: after,
+      diagnostic: {
+        bodyReads: 1,
+        failedFiles: 0,
+        metadataMs: 1,
+        parseMs: 1,
+        migrationPending: true,
+      },
+    }),
+  };
+
+  await extension.runCodexRefresh('startup');
+  await Promise.resolve();
+  await Promise.resolve();
+
+  assert.equal(extension.codexBackgroundState.status, 'eligible');
+  assert.deepEqual(continuations, ['startup']);
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
+});
+
+test('timer and watcher ownership clear only after their real handles stop', async () => {
+  const extension = bareExtension();
+  extension.refreshGen = 0;
+  extension.watchDebounce = { clear: () => undefined };
+  let fired = false;
+  let watcherClosed = 0;
+  const timer = setTimeout(() => { fired = true; }, 20);
+  extension.refreshTimer = timer;
+  extension.refreshTimerLease = extension.resourceOwnership.register({
+    kind: 'timer',
+    capability: 'refresh',
+    scope: 'extension',
+    creator: 'refresh-coordinator',
+    stopConditions: ['window-blur'],
+    boundedException: 'none',
+  });
+  extension.fileWatcher = {
+    close: () => { watcherClosed += 1; },
+  };
+  extension.fileWatcherLease = extension.resourceOwnership.register({
+    kind: 'watcher',
+    capability: 'refresh',
+    scope: 'claude',
+    creator: 'extension',
+    stopConditions: ['window-blur'],
+    boundedException: 'none',
+  });
+
+  extension.stopAutoRefresh('window-blur');
+  extension.stopFileWatching('window-blur');
+  await Promise.resolve();
+  await Promise.resolve();
+
+  assert.equal(watcherClosed, 1);
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  assert.equal(fired, false);
+});
+
+test('watch quiet-delay timers are owned and actually cancelled', async () => {
+  const extension = bareExtension();
+  extension.debounceTimerLeases = new Map();
+  const debounce = extension.createOwnedRefreshDebounce('codex');
+  let fired = false;
+
+  debounce.push(20, () => { fired = true; });
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.timer, 1);
+  debounce.clear();
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.timer, 0);
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  assert.equal(fired, false);
+});
+
+test('backgrounding aborts an active quota network before releasing ownership', async () => {
+  const extension = bareExtension();
+  let observedSignal: AbortSignal | undefined;
+  extension.cache = {
+    usageLimits: null,
+    usageLimitsLastUpdate: new Date(0),
+    usageLimitsBackoffUntil: new Date(0),
+    usageLimitsFailStreak: 0,
+  };
+  extension.isActive = () => false;
+  extension.apiClient = {
+    fetchUsageLimits: (signal?: AbortSignal) => new Promise<null>((resolve) => {
+      observedSignal = signal;
+      assert.ok(signal);
+      signal.addEventListener('abort', () => resolve(null), { once: true });
+    }),
+  };
+
+  const pending = extension.maybeFetchUsageLimits({ usageLimitTracking: true });
+  await Promise.resolve();
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 1);
+
+  await extension.cancelQuotaNetworks('window-blur');
+  assert.equal(observedSignal?.aborted, true);
+  await pending;
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 0);
+  assert.equal(extension.cache.usageLimitsFailStreak, 0);
+});
+
+test('network ownership remains active until an aborted request actually settles', async () => {
+  const extension = bareExtension();
+  let releaseRequest!: () => void;
+  let aborted = false;
+  const pending = extension.runAdviceNetwork((signal: AbortSignal) =>
+    new Promise<void>((_resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        aborted = true;
+        releaseRequest = () => reject(new Error('request finally settled'));
+      }, { once: true });
+    }),
+  );
+  await Promise.resolve();
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 1);
+
+  let cancellationSettled = false;
+  const cancellation = extension.cancelAdviceNetworks('cancelled').then(() => {
+    cancellationSettled = true;
+  });
+  await Promise.resolve();
+  await Promise.resolve();
+
+  assert.equal(aborted, true);
+  assert.equal(cancellationSettled, false);
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 1);
+
+  releaseRequest();
+  await assert.rejects(pending, /finally settled/);
+  await cancellation;
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 0);
+});
+
+test('advice consent cancellation aborts advice without cancelling a separate optimizer request', async () => {
+  const extension = bareExtension();
+  let adviceSignal!: AbortSignal;
+  let optimizerSignal!: AbortSignal;
+  const advice = extension.runAdviceNetwork((signal: AbortSignal) => {
+    adviceSignal = signal;
+    return new Promise<void>((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }));
+  }, 'advice');
+  const optimizer = extension.runAdviceNetwork((signal: AbortSignal) => {
+    optimizerSignal = signal;
+    return new Promise<void>((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }));
+  }, 'optimizer');
+  await extension.cancelAdviceNetworks('cancelled', 'advice');
+  await advice;
+  assert.equal(adviceSignal.aborted, true);
+  assert.equal(optimizerSignal.aborted, false);
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 1);
+  await extension.cancelAdviceNetworks('cancelled');
+  await optimizer;
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 0);
+});
+
+test('quota cold retry timer is owned and cleared on blur', async () => {
+  const extension = bareExtension();
+  const originalSetTimeout = global.setTimeout;
+  const originalClearTimeout = global.clearTimeout;
+  let cleared = 0;
+  const fakeTimer = { fake: true } as unknown as NodeJS.Timeout;
+  global.setTimeout = ((_callback: () => void, _ms: number) =>
+    fakeTimer) as typeof setTimeout;
+  global.clearTimeout = ((handle: NodeJS.Timeout) => {
+    assert.equal(handle, fakeTimer);
+    cleared += 1;
+  }) as typeof clearTimeout;
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.getConfiguration = () => ({ usageLimitTracking: true });
+  extension.maybeFetchUsageLimits = async () => null;
+
+  try {
+    extension.scheduleQuotaColdRetry();
+    assert.equal(extension.resourceOwnership.snapshotForTests().byKind.timer, 1);
+    extension.stopQuotaColdRetry('window-blur');
+    await Promise.resolve();
+    await Promise.resolve();
+    assert.equal(cleared, 1);
+    assert.equal(extension.resourceOwnership.snapshotForTests().byKind.timer, 0);
+  } finally {
+    global.setTimeout = originalSetTimeout;
+    global.clearTimeout = originalClearTimeout;
+  }
+});
+
+test('extension disposal releases worker and backfill only after provider termination', async () => {
+  const extension = bareExtension();
+  let finishProviderDispose!: () => void;
+  const providerDisposed = new Promise<void>((resolve) => {
+    finishProviderDispose = resolve;
+  });
+  let providerCancelCalls = 0;
+  let hostDisposals = 0;
+  extension.stopAutoRefresh = () => undefined;
+  extension.stopFileWatching = () => undefined;
+  extension.stopCodexWatching = () => undefined;
+  extension.stopCredentialsWatching = () => undefined;
+  extension.codexProviderRetirements = new Set();
+  extension.codexProvider = {
+    cancel: () => { providerCancelCalls += 1; },
+    dispose: () => providerDisposed,
+  };
+  extension.statusBar = { dispose: () => { hostDisposals += 1; } };
+  extension.webviewProvider = { dispose: () => { hostDisposals += 1; } };
+  extension.codexWorkerLease = extension.resourceOwnership.register({
+    kind: 'worker',
+    capability: 'codex-index',
+    scope: 'codex',
+    creator: 'codex-index-client',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'none',
+  });
+  extension.codexBackfillLease = extension.resourceOwnership.register({
+    kind: 'backfill',
+    capability: 'codex-history',
+    scope: 'codex',
+    creator: 'refresh-coordinator',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'first-codex-history',
+  });
+
+  let disposalSettled = false;
+  const disposal = extension.dispose().then(() => {
+    disposalSettled = true;
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.equal(providerCancelCalls, 1);
+  assert.equal(disposalSettled, false);
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 2);
+  assert.equal(hostDisposals, 0);
+
+  finishProviderDispose();
+  await disposal;
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
+  assert.equal(hostDisposals, 2);
+});
+
+test('extension disposal keeps worker ownership active when termination fails', async () => {
+  const extension = bareExtension();
+  let hostDisposals = 0;
+  extension.stopAutoRefresh = () => undefined;
+  extension.stopFileWatching = () => undefined;
+  extension.stopCodexWatching = () => undefined;
+  extension.stopCredentialsWatching = () => undefined;
+  extension.codexProvider = {
+    cancel: () => undefined,
+    dispose: async () => { throw new Error('provider terminate failed'); },
+  };
+  extension.statusBar = { dispose: () => { hostDisposals += 1; } };
+  extension.webviewProvider = { dispose: () => { hostDisposals += 1; } };
+  extension.codexWorkerLease = extension.resourceOwnership.register({
+    kind: 'worker',
+    capability: 'codex-index',
+    scope: 'codex',
+    creator: 'codex-index-client',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'none',
+  });
+  extension.codexBackfillLease = extension.resourceOwnership.register({
+    kind: 'backfill',
+    capability: 'codex-history',
+    scope: 'codex',
+    creator: 'refresh-coordinator',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'first-codex-history',
+  });
+
+  await assert.rejects(extension.dispose(), /provider terminate failed/);
+
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 2);
+  assert.equal(hostDisposals, 2);
+});
+
+test('a refresh termination failure retains its worker and backfill leases for disposal', async () => {
+  const extension = bareExtension();
+  const snapshot = snapshotFixture();
+  snapshot.coverage.complete = false;
+  snapshot.coverage.indexedFiles = Math.max(0, snapshot.coverage.totalFiles - 1);
+  extension.getConfiguration = () => ({ codexEnabled: true });
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.webviewProvider = { updateCodexProgress: () => undefined };
+  extension.syncProviderUi = () => undefined;
+  extension.codexProvider = {
+    isAvailable: async () => true,
+    loadPersistedSnapshot: async () => snapshot,
+    refresh: async () => { throw new Error('worker could not terminate'); },
+  };
+
+  await assert.rejects(extension.runCodexRefresh('poll'), /could not terminate/);
+
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.worker, 1);
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.backfill, 1);
+  assert.equal(extension.codexWorkerLease?.active, true);
+  assert.equal(extension.codexBackfillLease?.active, true);
+});
+
+test('disposal drains every resource kind and stale callbacks cannot recreate work', async () => {
+  const extension = bareExtension();
+  let releaseNetwork!: () => void;
+  let releaseProvider!: () => void;
+  let releaseStaleCallbacks!: () => void;
+  let watcherClosed = 0;
+  let providerCancelled = 0;
+  let hostDisposals = 0;
+  const providerDisposal = new Promise<void>((resolve) => {
+    releaseProvider = resolve;
+  });
+  const staleCallbacks = new Promise<void>((resolve) => {
+    releaseStaleCallbacks = resolve;
+  });
+
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.refreshGen = 0;
+  extension.refreshTimer = setTimeout(() => assert.fail('disposed timer fired'), 60_000);
+  extension.refreshTimerLease = extension.resourceOwnership.register({
+    kind: 'timer',
+    capability: 'refresh',
+    scope: 'extension',
+    creator: 'refresh-coordinator',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'none',
+  });
+  extension.watchDebounce = { clear: () => undefined };
+  extension.codexWatchDebounce = { clear: () => undefined };
+  extension.fileWatcher = { close: () => { watcherClosed += 1; } };
+  extension.fileWatcherLease = extension.resourceOwnership.register({
+    kind: 'watcher',
+    capability: 'refresh',
+    scope: 'claude',
+    creator: 'extension',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'none',
+  });
+  extension.codexWatchers = [];
+  extension.codexWorkerLease = extension.resourceOwnership.register({
+    kind: 'worker',
+    capability: 'codex-index',
+    scope: 'codex',
+    creator: 'codex-index-client',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'none',
+  });
+  extension.codexBackfillLease = extension.resourceOwnership.register({
+    kind: 'backfill',
+    capability: 'codex-history',
+    scope: 'codex',
+    creator: 'refresh-coordinator',
+    stopConditions: ['extension-dispose'],
+    boundedException: 'first-codex-history',
+  });
+  extension.codexProvider = {
+    cancel: () => { providerCancelled += 1; },
+    dispose: () => providerDisposal,
+  };
+  extension.statusBar = { dispose: () => { hostDisposals += 1; } };
+  extension.webviewProvider = { dispose: () => { hostDisposals += 1; } };
+  extension.stopQuotaColdRetry = ClaudeCodeUsageExtension.prototype['stopQuotaColdRetry'];
+  extension.stopAutoRefresh = ClaudeCodeUsageExtension.prototype['stopAutoRefresh'];
+  extension.stopFileWatching = ClaudeCodeUsageExtension.prototype['stopFileWatching'];
+  extension.stopCodexWatching = ClaudeCodeUsageExtension.prototype['stopCodexWatching'];
+  extension.stopCredentialsWatching = () => undefined;
+
+  const network = extension.runAdviceNetwork((signal: AbortSignal) =>
+    new Promise<void>((_resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        releaseNetwork = () => reject(new Error('network closed'));
+      }, { once: true });
+    }),
+  ).catch(() => undefined);
+  await Promise.resolve();
+  assert.deepEqual(extension.resourceOwnership.snapshotForTests().byKind, {
+    timer: 1,
+    watcher: 1,
+    worker: 1,
+    network: 1,
+    backfill: 1,
+  });
+
+  const stale = staleCallbacks.then(async () => {
+    extension.startAutoRefresh();
+    await extension.startFileWatching();
+    extension.startCodexWatching();
+    extension.scheduleQuotaColdRetry();
+    await extension.refreshData(false, 'poll');
+  });
+  const disposal = extension.dispose();
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.equal(extension.resourceOwnership.snapshotForTests().byKind.network, 1);
+
+  releaseStaleCallbacks();
+  releaseNetwork();
+  releaseProvider();
+  await Promise.all([network, stale, disposal]);
+  await Promise.resolve();
+  await Promise.resolve();
+
+  assert.equal(watcherClosed, 1);
+  assert.equal(providerCancelled, 1);
+  assert.equal(hostDisposals, 2);
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
+  await assert.rejects(
+    extension.runAdviceNetwork(async () => undefined),
+    /disposed/i,
+  );
+  assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
 });
 
 test('Claude watcher is not created when the window loses focus during directory lookup', async () => {
@@ -373,6 +1147,367 @@ test('Claude watcher is not created when the window loses focus during directory
   }
 });
 
+test('Claude watcher is not created after disposal or a stale settings generation', async () => {
+  const extension = bareExtension();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ccu-claude-watch-dispose-'));
+  fs.mkdirSync(path.join(root, 'projects'));
+  const originalFind = ClaudeDataLoader.findClaudeDataDirectory;
+  const originalWatch = fs.watch;
+  let resolveDirectory!: (value: string) => void;
+  let watchCalls = 0;
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.watchDebounce = { clear: () => undefined };
+  extension.fileWatcher = undefined;
+  extension.watchedDir = null;
+  extension.getConfiguration = () => ({
+    fileWatchSeconds: 30,
+    dataDirectory: '',
+  });
+  (ClaudeDataLoader as any).findClaudeDataDirectory = () => new Promise<string>((resolve) => {
+    resolveDirectory = resolve;
+  });
+  (fs as any).watch = () => {
+    watchCalls += 1;
+    return { close: () => undefined };
+  };
+
+  try {
+    const pending = extension.startFileWatching();
+    extension.disposed = true;
+    extension.fileWatcherGeneration += 1;
+    resolveDirectory(root);
+    await pending;
+    assert.equal(watchCalls, 0);
+    assert.equal(extension.fileWatcher, undefined);
+  } finally {
+    (ClaudeDataLoader as any).findClaudeDataDirectory = originalFind;
+    (fs as any).watch = originalWatch;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('Claude recursive watcher forwards nested subagent JSONL writes to a watch refresh', async () => {
+  const extension = bareExtension();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ccu-claude-watch-subagent-'));
+  fs.mkdirSync(path.join(root, 'projects'));
+  const originalFind = ClaudeDataLoader.findClaudeDataDirectory;
+  const originalWatch = fs.watch;
+  let listener: ((eventType: string, filename: string | Buffer | null) => void) | undefined;
+  let watcherClosed = 0;
+  const refreshes: Array<{ forceReload: boolean; trigger: string }> = [];
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.watchDebounce = {
+    clear: () => undefined,
+    push: (_delay: number, callback: () => void) => callback(),
+  };
+  extension.fileWatcher = undefined;
+  extension.fileWatcherLease = undefined;
+  extension.watchedDir = null;
+  extension.getConfiguration = () => ({
+    fileWatchSeconds: 1,
+    dataDirectory: '',
+  });
+  extension.refreshData = async (forceReload: boolean, trigger: string) => {
+    refreshes.push({ forceReload, trigger });
+  };
+  (ClaudeDataLoader as any).findClaudeDataDirectory = async () => root;
+  (fs as any).watch = (
+    directory: string,
+    options: { recursive?: boolean },
+    callback: (eventType: string, filename: string | Buffer | null) => void,
+  ) => {
+    assert.equal(directory, path.join(root, 'projects'));
+    assert.equal(options.recursive, true);
+    listener = callback;
+    return { close: () => { watcherClosed += 1; } };
+  };
+
+  try {
+    await extension.startFileWatching();
+    assert.ok(listener);
+    listener('change', path.join('-fixture', 'session-root', 'subagents', 'agent-review.jsonl'));
+    await Promise.resolve();
+    assert.deepEqual(refreshes, [{ forceReload: false, trigger: 'watch' }]);
+
+    listener('change', path.join('-fixture', 'session-root', 'subagents', 'agent-review.meta.json'));
+    await Promise.resolve();
+    assert.equal(refreshes.length, 1, 'non-JSONL metadata must not schedule a usage refresh');
+  } finally {
+    extension.stopFileWatching();
+    (ClaudeDataLoader as any).findClaudeDataDirectory = originalFind;
+    (fs as any).watch = originalWatch;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.equal(watcherClosed, 1);
+});
+
+test('Claude watcher errors close the watcher and fall back to polling', async () => {
+  const extension = bareExtension();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ccu-claude-watch-error-'));
+  fs.mkdirSync(path.join(root, 'projects'));
+  const originalFind = ClaudeDataLoader.findClaudeDataDirectory;
+  const originalWatch = fs.watch;
+  let errorListener: ((error: Error) => void) | undefined;
+  let watcherClosed = 0;
+  const diagnostics: string[] = [];
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.watchDebounce = { clear: () => undefined };
+  extension.fileWatcher = undefined;
+  extension.fileWatcherLease = undefined;
+  extension.watchedDir = null;
+  extension.outputChannel = { appendLine: (line: string) => diagnostics.push(line) };
+  extension.getConfiguration = () => ({
+    fileWatchSeconds: 1,
+    dataDirectory: '',
+  });
+  (ClaudeDataLoader as any).findClaudeDataDirectory = async () => root;
+  const watcher = {
+    close: () => { watcherClosed += 1; },
+    on: (event: string, listener: (error: Error) => void) => {
+      if (event === 'error') errorListener = listener;
+      return watcher;
+    },
+  };
+  (fs as any).watch = () => watcher;
+
+  try {
+    await extension.startFileWatching();
+    assert.ok(errorListener, 'the watcher must handle asynchronous fs.watch errors');
+    const error = Object.assign(new Error('watch resources exhausted'), { code: 'EMFILE' });
+    errorListener(error);
+    await extension.drainResourceStops();
+
+    assert.equal(extension.fileWatcher, undefined);
+    assert.equal(extension.watchedDir, null);
+    assert.equal(watcherClosed, 1);
+    assert.equal(extension.resourceOwnership.snapshotForTests().activeCount, 0);
+    assert.match(diagnostics.join('\n'), /EMFILE/);
+    assert.match(diagnostics.join('\n'), /poll/i);
+  } finally {
+    extension.stopFileWatching();
+    (ClaudeDataLoader as any).findClaudeDataDirectory = originalFind;
+    (fs as any).watch = originalWatch;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('real Claude filesystem events flow through manifest, index, and dashboard refresh', {
+  timeout: 10_000,
+}, async (t) => {
+  const extension = bareExtension();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ccu-claude-watch-e2e-'));
+  const project = path.join(root, 'projects', '-fixture');
+  const subagents = path.join(project, 'session-root', 'subagents');
+  fs.mkdirSync(subagents, { recursive: true });
+  const timestamp = new Date().toISOString();
+  const usageLine = (id: string, input: number): string => JSON.stringify({
+    type: 'assistant',
+    timestamp,
+    cwd: '/fixture/project',
+    gitBranch: 'main',
+    requestId: `request-${id}`,
+    message: {
+      id: `message-${id}`,
+      model: 'claude-sonnet-4-5',
+      content: [{ type: 'text', text: `answer-${id}` }],
+      usage: {
+        input_tokens: input,
+        output_tokens: 1,
+        cache_creation_input_tokens: 2,
+        cache_read_input_tokens: 3,
+      },
+    },
+  });
+  const initialFile = path.join(project, 'session-root.jsonl');
+  const nestedFile = path.join(subagents, 'agent-review.jsonl');
+  fs.writeFileSync(initialFile, `${usageLine('root', 10)}\n`, 'utf8');
+
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.localDataClearedRequiresReload = false;
+  extension.refreshGate = new RefreshSingleFlight();
+  extension.watchDebounce = {
+    clear: () => undefined,
+    push: (_delay: number, callback: () => void) => callback(),
+  };
+  extension.fileWatcher = undefined;
+  extension.fileWatcherLease = undefined;
+  extension.watchedDir = null;
+  extension.quotaColdRetryDone = true;
+  extension.cache = {
+    records: [],
+    contentAnalysis: null,
+    claudeIndex: createClaudeUsageIndex(),
+    manifest: null,
+    lastUpdate: new Date(0),
+    dataDirectory: null,
+    usageLimits: null,
+    usageLimitsLastUpdate: new Date(0),
+    usageLimitsBackoffUntil: new Date(0),
+    usageLimitsFailStreak: 0,
+  };
+  extension.getConfiguration = () => ({
+    dataDirectory: root,
+    fileWatchSeconds: 1,
+    dashboardAutoRefresh: true,
+    enableContentAnalysis: false,
+    advicePromptWindowDays: 30,
+    projectGroupingMode: 'git',
+    contextWindowOverride: 0,
+  });
+  extension.refreshCodexData = () => undefined;
+  extension.maybeFetchUsageLimits = async () => null;
+  extension.syncProviderUi = () => undefined;
+  const diagnostics: string[] = [];
+  extension.outputChannel = { appendLine: (line: string) => diagnostics.push(line) };
+  extension.statusBar = {
+    setLoading: () => undefined,
+    updateQuota: () => undefined,
+    updateUsageData: () => undefined,
+    updateContext: () => undefined,
+  };
+
+  let resolveNestedRefresh!: () => void;
+  const nestedRefresh = new Promise<void>((resolve) => {
+    resolveNestedRefresh = resolve;
+  });
+  const todayInputs: number[] = [];
+  const allTimeInputs: number[] = [];
+  extension.webviewProvider = {
+    setLoading: () => undefined,
+    updateQuota: () => undefined,
+    updateData: (
+      _session: unknown,
+      today: { totalInputTokens?: number } | null,
+      _last30Days: unknown,
+      allTime: { totalInputTokens?: number } | null,
+      _dailyForLast30Days: unknown,
+      _monthlyForAllTime: unknown,
+      _hourlyForToday: unknown,
+      error?: string,
+    ) => {
+      const input = today?.totalInputTokens ?? 0;
+      todayInputs.push(input);
+      allTimeInputs.push(allTime?.totalInputTokens ?? 0);
+      if (error) diagnostics.push(error);
+      if (input === 30) resolveNestedRefresh();
+    },
+  };
+
+  try {
+    await extension.refreshData(true, 'manual');
+    assert.equal(
+      todayInputs[todayInputs.length - 1],
+      10,
+      `allTime=${allTimeInputs[allTimeInputs.length - 1]} records=${extension.cache.records.length} diagnostics=${diagnostics.join(' | ')}`,
+    );
+
+    await extension.startFileWatching();
+    if (!extension.fileWatcher) {
+      t.skip('recursive fs.watch is not supported on this platform');
+      return;
+    }
+    const activeWatcher = extension.fileWatcher as fs.FSWatcher;
+
+    const outcomePromise = new Promise<'refreshed' | 'watch-error'>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('timed out waiting for nested Claude refresh'));
+      }, 5_000);
+      nestedRefresh.then(() => {
+        clearTimeout(timeout);
+        resolve('refreshed');
+      });
+      activeWatcher.once('error', () => {
+        clearTimeout(timeout);
+        resolve('watch-error');
+      });
+    });
+    fs.writeFileSync(nestedFile, `${usageLine('subagent', 20)}\n`, 'utf8');
+    const outcome = await outcomePromise;
+    if (outcome === 'watch-error') {
+      t.skip('the test host cannot allocate a recursive fs.watch handle');
+      return;
+    }
+
+    assert.equal(todayInputs[todayInputs.length - 1], 30);
+    assert.equal(extension.cache.records.length, 2);
+    assert.equal(extension.cache.manifest?.entries.size, 2);
+  } finally {
+    extension.stopFileWatching();
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('rapid settings changes wait for every provider retirement and only latest generation restarts', async () => {
+  const extension = bareExtension();
+  let finishFirst!: () => void;
+  let finishSecond!: () => void;
+  const firstDisposal = new Promise<void>((resolve) => { finishFirst = resolve; });
+  const secondDisposal = new Promise<void>((resolve) => { finishSecond = resolve; });
+  const calls: string[] = [];
+  const provider = (name: string, disposal: Promise<void>) => ({
+    cancel: () => calls.push(`${name}:cancel`),
+    dispose: () => disposal,
+  });
+  const first = provider('first', firstDisposal);
+  const second = provider('second', secondDisposal);
+  const third = provider('third', Promise.resolve());
+  const replacements = [second, third];
+  extension.codexProvider = first;
+  extension.windowActivity = new WindowActivityGate(true);
+  extension.webviewProvider = {
+    invalidatePreparedAiRequests: () => undefined,
+  };
+  extension.statusBar = {
+    setVisibility: () => undefined,
+  };
+  extension.getConfiguration = () => ({
+    language: 'en',
+    decimalPlaces: 2,
+    tokenDecimalPlaces: 0,
+    compactNumbers: true,
+    timezone: 'UTC',
+    showCost: true,
+    showContext: true,
+    usageLimitTracking: false,
+    statusBarMetric: 'tokens',
+    showScopedWeekly: false,
+    quotaFiveHourOnly: false,
+    showResetInStatusBar: false,
+    resetCountdownFormat: 'short',
+    dataDirectory: '',
+  });
+  extension.cancelAdviceNetworks = async () => undefined;
+  extension.cancelQuotaNetworks = async () => undefined;
+  extension.stopQuotaColdRetry = () => undefined;
+  extension.startAutoRefresh = () => undefined;
+  extension.stopFileWatching = () => undefined;
+  extension.stopCodexWatching = () => undefined;
+  extension.stopCredentialsWatching = () => undefined;
+  extension.selectClaudeProfile = () => undefined;
+  extension.createCodexProvider = () => replacements.shift();
+  extension.refreshData = async () => { calls.push('refresh'); };
+  extension.startFileWatching = async () => { calls.push('claude:start'); };
+  extension.startCodexWatching = () => { calls.push('codex:start'); };
+  extension.startCredentialsWatching = () => { calls.push('credentials:start'); };
+
+  extension.onConfigurationChanged();
+  extension.onConfigurationChanged();
+  finishSecond();
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.deepEqual(calls.filter((call) => call === 'refresh'), []);
+
+  finishFirst();
+  await new Promise((resolve) => setImmediate(resolve));
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(calls.filter((call) => call === 'refresh'), ['refresh']);
+  assert.equal(calls.filter((call) => call === 'claude:start').length, 1);
+  assert.equal(calls.filter((call) => call === 'codex:start').length, 1);
+  assert.equal(calls.filter((call) => call === 'credentials:start').length, 1);
+});
+
 test('credentials change clears quota failure backoff before refreshing', async () => {
   const extension = bareExtension();
   const calls: string[] = [];
@@ -385,6 +1520,9 @@ test('credentials change clears quota failure backoff before refreshing', async
     calls.push(`refresh:${trigger}`);
     return Promise.resolve();
   };
+  extension.webviewProvider = {
+    updateWeeklyQuotaHistory: () => undefined,
+  };
 
   extension.handleCredentialsChange();
   await Promise.resolve();
@@ -468,6 +1606,63 @@ test('a quota response from the previous profile is discarded after a switch', a
   assert.equal(extension.cache.usageLimitsLastUpdate.getTime(), 0);
 });
 
+test('a same-path credential rotation cannot persist the stale in-flight quota response', async () => {
+  const extension = bareExtension();
+  let releaseRequest: ((value: unknown) => void) | undefined;
+  const client = {
+    getCredentialsPath: () => '/private/profile/.credentials.json',
+    getLastQuotaIdentitySignal: () => 'stale-continuity-signal',
+    fetchUsageLimits: () => new Promise((resolve) => {
+      releaseRequest = resolve;
+    }),
+  };
+  extension.apiClient = client;
+  extension.claudeProfileGeneration = 0;
+  extension.cache = {
+    usageLimits: null,
+    usageLimitsLastUpdate: new Date(0),
+    usageLimitsBackoffUntil: new Date(0),
+    usageLimitsFailStreak: 0,
+  };
+  extension.isActive = () => false;
+  extension.refreshData = async () => undefined;
+
+  const pending = extension.maybeFetchUsageLimits({ usageLimitTracking: true });
+  extension.handleCredentialsChange();
+  releaseRequest?.({
+    limits: [{
+      kind: 'weekly_all',
+      group: 'weekly',
+      percent: 75,
+      resets_at: '2026-09-07T03:24:00.000Z',
+      scope: null,
+      is_active: true,
+    }],
+  });
+
+  assert.equal(await pending, null);
+  assert.equal(extension.quotaObservationStore.observations.length, 0);
+  assert.equal(extension.cache.usageLimits, null);
+});
+
+test('disabled quota tracking neither calls the provider nor records an observation', async () => {
+  const extension = bareExtension();
+  let fetches = 0;
+  extension.apiClient = {
+    fetchUsageLimits: async () => {
+      fetches += 1;
+      return null;
+    },
+  };
+
+  assert.equal(
+    await extension.maybeFetchUsageLimits({ usageLimitTracking: false }),
+    null,
+  );
+  assert.equal(fetches, 0);
+  assert.equal(extension.quotaObservationStore.observations.length, 0);
+});
+
 test('repeated quota failures use the one-hour backoff cap', async () => {
   const extension = bareExtension();
   const originalNow = Date.now;
@@ -504,6 +1699,7 @@ test('a successful Claude quota fetch persists sanitized weekly observations per
   const historyUpdates: unknown[] = [];
   extension.apiClient = {
     getCredentialsPath: () => '/private/profile-a/.credentials.json',
+    getLastQuotaIdentitySignal: () => 'safe-local-continuity-signal',
     fetchUsageLimits: async () => ({
       limits: [{
         kind: 'weekly_all',
@@ -539,16 +1735,140 @@ test('a successful Claude quota fetch persists sanitized weekly observations per
   try {
     const result = await extension.maybeFetchUsageLimits({ usageLimitTracking: true });
     assert.ok(result);
-    const historyWrite = writes.find((write) => write.key.startsWith('ccu.weeklyQuotaHistory.v1.'));
-    assert.ok(historyWrite);
-    const history = historyWrite.value as Array<Record<string, unknown>>;
-    assert.equal(history.length, 1);
-    assert.deepEqual(Object.keys(history[0]).sort(), [
-      'observedAt', 'provider', 'resetAt', 'seriesKey', 'usedPercent',
-    ]);
-    assert.equal(history[0].usedPercent, 40);
+    assert.equal(
+      writes.some((write) => write.key.startsWith('ccu.weeklyQuotaHistory.v1.')),
+      false,
+    );
+    const observations = extension.quotaObservationStore.observations;
+    assert.equal(observations.length, 1);
+    assert.equal(observations[0].provider, 'claude');
+    assert.equal(observations[0].usedFraction, 0.4);
+    assert.equal(observations[0].accountAttribution, 'verified-local-signal');
+    assert.match(observations[0].accountFingerprint, /^acct_[a-f0-9]{32}$/);
+    assert.equal(
+      JSON.stringify(extension.quotaObservationStore).includes('/private/profile-a'),
+      false,
+    );
+    assert.equal(
+      JSON.stringify(extension.quotaObservationStore).includes('safe-local-continuity-signal'),
+      false,
+    );
     assert.equal(historyUpdates.length, 1);
   } finally {
     Date.now = originalNow;
   }
 });
+
+test('legacy quota migration is atomic, private, idempotent, and independent of tracking state', async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'ccu-quota-migration-'));
+  const observedAt = Date.now() - 60_000;
+  const resetAt = Date.now() + 7 * 24 * 60 * 60 * 1000;
+  const state = new Map<string, unknown>([
+    ['ccu.usageLimits.legacy-profile', {
+      ts: observedAt,
+      data: {
+        limits: [{
+          kind: 'weekly_all',
+          group: 'weekly',
+          percent: 40,
+          resets_at: new Date(resetAt).toISOString(),
+          scope: null,
+          is_active: true,
+        }],
+        unsafeCredentialCanary: 'oauth-token-canary',
+      },
+    }],
+    ['ccu.weeklyQuotaHistory.v1.legacy-profile', [{
+      provider: 'claude',
+      seriesKey: '/private/legacy-profile',
+      observedAt,
+      resetAt,
+      usedPercent: 40,
+    }]],
+  ]);
+  const globalState = {
+    keys: () => [...state.keys()],
+    get: <T>(key: string): T | undefined => state.get(key) as T | undefined,
+    update: async (key: string, value: unknown) => {
+      if (value === undefined) state.delete(key);
+      else state.set(key, value);
+    },
+  };
+  const context = {
+    globalState,
+    globalStorageUri: { fsPath: root },
+  } as any;
+  const settings = {
+    get: (key: string) => key === 'dataDirectory'
+      ? path.join(root, 'profile-without-credentials')
+      : key === 'timezone'
+        ? 'UTC'
+        : key === 'usageLimitTracking'
+          ? false
+          : undefined,
+  } as any;
+
+  const first = await initializeQuotaObservationRuntime(context, settings);
+  assert.equal(first.store.observations.length, 1);
+  assert.equal(first.store.observations[0].usedFraction, 0.4);
+  assert.equal(first.store.observations[0].captureReason, 'migration');
+  assert.ok(first.store.observations[0].flags.includes('account-ambiguous'));
+  assert.equal(state.has('ccu.usageLimits.legacy-profile'), false);
+  assert.equal(state.has('ccu.weeklyQuotaHistory.v1.legacy-profile'), false);
+  assert.equal(state.get('ccu.quota.migratedCodexIndex.v2'), true);
+
+  const file = path.join(root, 'quota-observations-v2.json');
+  const persisted = await fs.promises.readFile(file, 'utf8');
+  assert.doesNotMatch(persisted, /oauth-token-canary|private\/legacy-profile/);
+  const second = await initializeQuotaObservationRuntime(context, settings);
+  assert.deepEqual(second.store, first.store);
+});
+
+test('a failed P2 migration write preserves every legacy quota source and retry marker', async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'ccu-quota-migration-failure-'));
+  const blockedStorage = path.join(root, 'not-a-directory');
+  await fs.promises.writeFile(blockedStorage, 'fixture', 'utf8');
+  const observedAt = Date.now() - 60_000;
+  const state = new Map<string, unknown>([[
+    'ccu.usageLimits.retryable-profile',
+    {
+      ts: observedAt,
+      data: {
+        limits: [{
+          kind: 'weekly_all',
+          group: 'weekly',
+          percent: 25,
+          resets_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+          scope: null,
+          is_active: true,
+        }],
+      },
+    },
+  ]]);
+  const context = {
+    globalState: {
+      keys: () => [...state.keys()],
+      get: <T>(key: string): T | undefined => state.get(key) as T | undefined,
+      update: async (key: string, value: unknown) => {
+        if (value === undefined) state.delete(key);
+        else state.set(key, value);
+      },
+    },
+    globalStorageUri: { fsPath: blockedStorage },
+  } as any;
+  const settings = {
+    get: (key: string) => key === 'timezone' ? 'UTC' : '',
+  } as any;
+
+  await assert.rejects(
+    initializeQuotaObservationRuntime(context, settings),
+    (error: unknown) =>
+      typeof error === 'object' &&
+      error !== null &&
+      'code' in error &&
+      (error as NodeJS.ErrnoException).code === 'EEXIST' &&
+      String((error as NodeJS.ErrnoException).path).endsWith('not-a-directory'),
+  );
+  assert.equal(state.has('ccu.usageLimits.retryable-profile'), true);
+  assert.equal(state.has('ccu.quota.migratedCodexIndex.v2'), false);
+});
diff --git a/src/test/githubHeatmapPublish.test.ts b/src/test/githubHeatmapPublish.test.ts
new file mode 100644
index 00000000..dc50b2d5
--- /dev/null
+++ b/src/test/githubHeatmapPublish.test.ts
@@ -0,0 +1,113 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import {
+  GITHUB_PUBLIC_REPO_SCOPE,
+  GitHubApiRequest,
+  createGitHubPublishPlan,
+  githubPublishConfirmationDetail,
+  probePublicGitHubPublishTarget,
+  publishPublicGitHubFile,
+} from '../githubHeatmapPublish';
+
+test('GitHub publisher uses the public-only scope and rejects ambiguous destinations', () => {
+  assert.equal(GITHUB_PUBLIC_REPO_SCOPE, 'public_repo');
+  for (const [repo, path] of [
+    ['owner/repo/extra', 'heatmap.svg'],
+    ['owner?x/repo', 'heatmap.svg'],
+    ['owner/repo', '../heatmap.svg'],
+    ['owner/repo', '/heatmap.svg'],
+    ['owner/repo', 'folder//heatmap.svg'],
+    ['owner/repo', 'heatmap.svg?raw=1'],
+    ['owner/repo', 'folder\\heatmap.svg'],
+  ]) {
+    assert.throws(() => createGitHubPublishPlan(repo, path));
+  }
+});
+
+test('destination paths are encoded segment by segment without introducing query or fragment data', () => {
+  const plan = createGitHubPublishPlan('owner/repo.name', 'docs/AI activity.svg');
+  assert.equal(plan.repoApiPath, '/repos/owner/repo.name');
+  assert.equal(plan.contentsApiPath, '/repos/owner/repo.name/contents/docs/AI%20activity.svg');
+});
+
+test('mocked public create probe and write use the verified branch and no sha', async () => {
+  const calls: Array<{ method: string; path: string; body?: any }> = [];
+  const request: GitHubApiRequest = async (method, path, body) => {
+    calls.push({ method, path, body });
+    if (calls.length === 1) return { status: 200, body: JSON.stringify({ private: false, default_branch: 'main' }) };
+    if (calls.length === 2) return { status: 404, body: '{}' };
+    return { status: 201, body: '{}' };
+  };
+  const preview = await probePublicGitHubPublishTarget(
+    createGitHubPublishPlan('owner/repo', 'assets/activity.svg'),
+    request,
+  );
+  assert.equal(preview.action, 'create');
+  await publishPublicGitHubFile(preview, 'U0ZH', request);
+  assert.deepEqual(calls[2], {
+    method: 'PUT',
+    path: '/repos/owner/repo/contents/assets/activity.svg',
+    body: {
+      message: 'Update Claude Code usage heatmap',
+      content: 'U0ZH',
+      branch: 'main',
+    },
+  });
+});
+
+test('mocked update carries only the exact probed sha', async () => {
+  const sha = 'a'.repeat(40);
+  const calls: Array<{ method: string; body?: any }> = [];
+  const request: GitHubApiRequest = async (method, _path, body) => {
+    calls.push({ method, body });
+    if (calls.length === 1) return { status: 200, body: JSON.stringify({ private: false, default_branch: 'release/v2' }) };
+    if (calls.length === 2) return { status: 200, body: JSON.stringify({ sha }) };
+    return { status: 200, body: '{}' };
+  };
+  const preview = await probePublicGitHubPublishTarget(
+    createGitHubPublishPlan('owner/repo', 'activity.svg'),
+    request,
+  );
+  assert.equal(preview.action, 'update');
+  await publishPublicGitHubFile(preview, 'U0ZH', request);
+  assert.equal(calls[2].body.sha, sha);
+  assert.equal(calls[2].body.branch, 'release/v2');
+});
+
+test('private or unverifiable targets fail closed before any mock write', async () => {
+  let calls = 0;
+  const request: GitHubApiRequest = async () => {
+    calls += 1;
+    return { status: 200, body: JSON.stringify({ private: true, default_branch: 'main' }) };
+  };
+  await assert.rejects(
+    probePublicGitHubPublishTarget(createGitHubPublishPlan('owner/repo', 'activity.svg'), request),
+    /Private repositories are not supported/,
+  );
+  assert.equal(calls, 1);
+});
+
+test('exact confirmation names repository, branch, path, action, visibility, and payload class', () => {
+  const detail = githubPublishConfirmationDetail({
+    ...createGitHubPublishPlan('owner/repo', 'docs/activity.svg'),
+    visibility: 'public',
+    branch: 'main',
+    action: 'update',
+    existingSha: 'b'.repeat(40),
+    browserUrl: 'https://github.com/owner/repo/blob/main/docs/activity.svg',
+  }, 1234);
+  assert.match(detail, /owner\/repo \(public\)/);
+  assert.match(detail, /Branch: main/);
+  assert.match(detail, /Path: docs\/activity\.svg/);
+  assert.match(detail, /OVERWRITE/);
+  assert.match(detail, /aggregate SVG \(1234 bytes\)/);
+  assert.match(detail, /Excluded: accounts, projects, thread titles, local paths, prompts, and log content/);
+});
+
+test('mocked request failures expose status only, never response-body canaries', async () => {
+  const request: GitHubApiRequest = async () => ({ status: 503, body: 'TOKEN_COOKIE_PRIVACY_CANARY' });
+  await assert.rejects(
+    probePublicGitHubPublishTarget(createGitHubPublishPlan('owner/repo', 'activity.svg'), request),
+    (error: Error) => /status 503/.test(error.message) && !/PRIVACY_CANARY/.test(error.message),
+  );
+});
diff --git a/src/test/heatmapSvg.test.ts b/src/test/heatmapSvg.test.ts
index 1f3f3449..504f7ed6 100644
--- a/src/test/heatmapSvg.test.ts
+++ b/src/test/heatmapSvg.test.ts
@@ -1,10 +1,34 @@
 import { test } from 'node:test';
 import * as assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { buildContributionGrid, renderHeatmapSvg, CLAUDE_ORANGE_SCALE } from '../heatmapSvg';
 import { DayUsage } from '../heatmap';
 
 const day = (tokens: number): DayUsage => ({ tokens, cost: tokens / 1000, sessions: 1 });
 
+function fillForDate(svg: string, dateISO: string): string | undefined {
+  const match = svg.match(new RegExp(
+    `<rect[^>]*fill="([^"]+)"[^>]*><title>${dateISO}</title></rect>`,
+  ));
+  return match?.[1];
+}
+
+test('the in-dashboard heatmap anchors its end date in the configured timezone', () => {
+  const webviewSource = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'src', 'webview.ts'),
+    'utf8',
+  );
+  const start = webviewSource.indexOf("if (this.setting<boolean>('showHeatmap', false)");
+  const end = webviewSource.indexOf('const dailyBreakdown =', start);
+  assert.ok(start >= 0 && end > start, 'the live provider heatmap panel must remain discoverable');
+  const panel = webviewSource.slice(start, end);
+  assert.match(
+    panel,
+    /renderHeatmapSvg\(daily,\s*\{\s*endDateISO:\s*dayKeyInZone\(new Date\(\),\s*I18n\.getTimezone\(\)\),?\s*\}\)/,
+  );
+});
+
 test('grid holds only days in [start, end], and totals them', () => {
   const daily: Record<string, DayUsage> = { '2026-01-05': day(10), '2026-01-10': day(20) };
   const g = buildContributionGrid(daily, '2026-01-01', '2026-01-20', 'tokens');
@@ -65,3 +89,125 @@ test('has legend, watermark and the orange ramp; no crash on empty data', () =>
   assert.ok(svg.includes('Made with Claude Code Usage'));
   assert.ok(svg.includes(CLAUDE_ORANGE_SCALE[0]));
 });
+
+test('short custom ramps keep a valid watermark and matching legend', () => {
+  const svg = renderHeatmapSvg(
+    { '2026-06-20': day(10) },
+    { endDateISO: '2026-07-01', scale: ['#f5f3ff', '#4f2f87'] },
+  );
+
+  assert.ok(svg.includes('fill="#4f2f87"'));
+  assert.equal((svg.match(/fill="#f5f3ff"/g) ?? []).length > 0, true);
+  assert.equal(svg.includes('fill="undefined"'), false);
+});
+
+test('quantile mode keeps a large ordinary-day tie light and an isolated peak dark', () => {
+  const daily: Record<string, DayUsage> = {};
+  const start = new Date('2026-01-01T00:00:00Z');
+  for (let index = 0; index < 100; index++) {
+    const date = new Date(start);
+    date.setUTCDate(date.getUTCDate() + index);
+    daily[date.toISOString().slice(0, 10)] = day(index === 99 ? 10 : 1);
+  }
+  const scale = ['#eeeeee', '#dddddd', '#bbbbbb', '#999999', '#777777', '#333333'];
+  const svg = renderHeatmapSvg(daily, {
+    startDateISO: '2026-01-01',
+    endDateISO: '2026-04-10',
+    scale,
+    intensityMode: 'quantile',
+    tooltip: (dateISO) => dateISO,
+  });
+
+  assert.equal(fillForDate(svg, '2026-01-01'), scale[1]);
+  assert.equal(fillForDate(svg, '2026-04-09'), scale[1]);
+  assert.equal(fillForDate(svg, '2026-04-10'), scale[5]);
+});
+
+test('quantile mode always reaches the top band for sparse and maximum-tied data', () => {
+  const scale = ['#eeeeee', '#dddddd', '#bbbbbb', '#999999', '#777777', '#333333'];
+  const svg = renderHeatmapSvg({
+    '2026-06-01': day(1),
+    '2026-06-02': day(2),
+    '2026-06-03': day(4),
+    '2026-06-04': day(4),
+  }, {
+    startDateISO: '2026-06-01',
+    endDateISO: '2026-06-04',
+    scale,
+    intensityMode: 'quantile',
+    tooltip: (dateISO) => dateISO,
+  });
+
+  assert.equal(fillForDate(svg, '2026-06-01'), scale[1]);
+  assert.equal(fillForDate(svg, '2026-06-03'), scale[5]);
+  assert.equal(fillForDate(svg, '2026-06-04'), scale[5]);
+});
+
+test('logarithmic mode compresses a long tail while preserving value order', () => {
+  const scale = ['#eeeeee', '#dddddd', '#bbbbbb', '#999999', '#777777', '#333333'];
+  const svg = renderHeatmapSvg({
+    '2026-06-01': day(1),
+    '2026-06-02': day(9),
+    '2026-06-03': day(99),
+    '2026-06-04': day(999),
+  }, {
+    startDateISO: '2026-06-01',
+    endDateISO: '2026-06-04',
+    scale,
+    intensityMode: 'logarithmic',
+    tooltip: (dateISO) => dateISO,
+  });
+
+  assert.equal(fillForDate(svg, '2026-06-01'), scale[1]);
+  assert.equal(fillForDate(svg, '2026-06-02'), scale[2]);
+  assert.equal(fillForDate(svg, '2026-06-03'), scale[4]);
+  assert.equal(fillForDate(svg, '2026-06-04'), scale[5]);
+});
+
+test('short-range legends stay inside a min-width share card', () => {
+  const svg = renderHeatmapSvg({}, {
+    startDateISO: '2026-06-23',
+    endDateISO: '2026-07-22',
+    scale: ['#ebedf0', '#eee8f8', '#d8c9f1', '#bca5e6', '#8668c7', '#4f2f87'],
+    minWidth: 720,
+  });
+
+  assert.doesNotMatch(svg, /<(?:text|rect) x="-/);
+  assert.match(svg, /<text x="\d+"[^>]*>Less<\/text>/);
+  assert.match(svg, /<text x="\d+"[^>]*>More<\/text>/);
+});
+
+test('the default linear renderer preserves the original four active buckets', () => {
+  const daily: Record<string, DayUsage> = {
+    '2026-06-01': day(1),
+    '2026-06-02': day(25),
+    '2026-06-03': day(50),
+    '2026-06-04': day(75),
+    '2026-06-05': day(100),
+  };
+  const svg = renderHeatmapSvg(daily, {
+    startDateISO: '2026-06-01',
+    endDateISO: '2026-06-05',
+    tooltip: (dateISO) => dateISO,
+  });
+
+  assert.equal(fillForDate(svg, '2026-06-01'), CLAUDE_ORANGE_SCALE[1]);
+  assert.equal(fillForDate(svg, '2026-06-02'), CLAUDE_ORANGE_SCALE[1]);
+  assert.equal(fillForDate(svg, '2026-06-03'), CLAUDE_ORANGE_SCALE[2]);
+  assert.equal(fillForDate(svg, '2026-06-04'), CLAUDE_ORANGE_SCALE[3]);
+  assert.equal(fillForDate(svg, '2026-06-05'), CLAUDE_ORANGE_SCALE[4]);
+});
+
+test('renderer sanitizes caller-supplied SVG colors at the shared boundary', () => {
+  const svg = renderHeatmapSvg(
+    { '2026-06-20': day(10) },
+    {
+      endDateISO: '2026-07-01',
+      scale: ['#eeeeee', 'url(javascript:alert(1))'],
+      background: 'url(javascript:alert(2))',
+      accentColor: '" onload="alert(3)',
+    },
+  );
+
+  assert.doesNotMatch(svg, /javascript|onload|url\(/i);
+});
diff --git a/src/test/i18nTimezone.test.ts b/src/test/i18nTimezone.test.ts
index e9fc4872..689b654c 100644
--- a/src/test/i18nTimezone.test.ts
+++ b/src/test/i18nTimezone.test.ts
@@ -40,10 +40,22 @@ test('every locale implements complete non-English Codex product copy', () => {
       I18n.setLanguage(language);
       const copy = I18n.t.providers.codex;
       assert.deepEqual(Object.keys(copy).sort(), Object.keys(CODEX_COPY_EN).sort(), language);
+      assert.deepEqual(
+        Object.keys(copy.indexingReasons).sort(),
+        Object.keys(CODEX_COPY_EN.indexingReasons).sort(),
+        `${language}.indexingReasons`,
+      );
       if (language !== 'en') {
         for (const key of userFacingKeys) {
           assert.notEqual(copy[key], CODEX_COPY_EN[key], `${language}.${key} fell back to English`);
         }
+        for (const reason of Object.keys(CODEX_COPY_EN.indexingReasons) as Array<keyof typeof CODEX_COPY_EN.indexingReasons>) {
+          assert.notEqual(
+            copy.indexingReasons[reason],
+            CODEX_COPY_EN.indexingReasons[reason],
+            `${language}.indexingReasons.${reason} fell back to English`,
+          );
+        }
       }
     }
   } finally {
diff --git a/src/test/localDataControls.test.ts b/src/test/localDataControls.test.ts
new file mode 100644
index 00000000..3a751a82
--- /dev/null
+++ b/src/test/localDataControls.test.ts
@@ -0,0 +1,410 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+
+import {
+  LOCAL_DATA_ACTION_TARGETS,
+  LOCAL_DATA_GLOBAL_STATE_KEYS,
+  LOCAL_DATA_GLOBAL_STATE_PREFIXES,
+  LOCAL_DATA_SOURCE_EXCLUSIONS,
+  approximateJsonBytes,
+  finiteTimestampRange,
+  groupQuotaAccountEpochs,
+  isLocalDataAction,
+  shouldClearQuotaObservation,
+} from '../localDataControls';
+import type {
+  LocalDataAction,
+  LocalDataInventoryRow,
+  LocalDataQuotaScopeOption,
+} from '../localDataControls';
+import type {
+  QuotaObservationStoreV2,
+  QuotaObservationV2,
+} from '../quotaObservationStore';
+
+const DATA_ACTION_COMMANDS = [
+  { action: 'rebuild-codex-index', command: 'claudeCodeUsage.rebuildCodexIndex' },
+  { action: 'clear-quota-history', command: 'claudeCodeUsage.clearQuotaHistory' },
+  { action: 'clear-advice-data', command: 'claudeCodeUsage.clearAdviceData' },
+  { action: 'reset-ui-state', command: 'claudeCodeUsage.resetUiState' },
+  { action: 'reset-sharing-preferences', command: 'claudeCodeUsage.resetSharingPreferences' },
+  { action: 'clear-byok-secret', command: 'claudeCodeUsage.clearByokSecret' },
+  { action: 'clear-all-derived-data', command: 'claudeCodeUsage.clearAllDerivedData' },
+] as const satisfies readonly { action: LocalDataAction; command: string }[];
+
+const REPOSITORY_ROOT = path.resolve(__dirname, '..', '..');
+
+function observation(overrides: Partial<QuotaObservationV2> = {}): QuotaObservationV2 {
+  const provider = overrides.provider ?? 'codex';
+  return {
+    schemaVersion: 2,
+    provider,
+    accountFingerprint: 'acct-default-private',
+    accountAttribution: 'profile-continuity',
+    observedAt: 100,
+    periodType: 'seven-day',
+    usedFraction: 0.25,
+    remainingFraction: 0.75,
+    resetAt: null,
+    source: provider === 'claude'
+      ? 'claude-official-api'
+      : 'codex-local-structured-event',
+    windowId: 'window-fixture',
+    providerWindowFingerprint: null,
+    confidence: 'medium',
+    captureReason: 'refresh',
+    flags: [],
+    ...overrides,
+  };
+}
+
+function store(observations: QuotaObservationV2[]): QuotaObservationStoreV2 {
+  return {
+    schemaVersion: 2,
+    fingerprintAlgorithm: 'hmac-sha256-v1',
+    observations,
+  };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function sourceSlice(source: string, startMarker: string, endMarker: string): string {
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker, start + startMarker.length);
+  assert.notEqual(start, -1, `missing source marker: ${startMarker}`);
+  assert.notEqual(end, -1, `missing source marker: ${endMarker}`);
+  return source.slice(start, end);
+}
+
+function sourceStringArray(source: string, variableName: string): string[] {
+  const match = source.match(new RegExp(
+    `var\\s+${escapeRegExp(variableName)}\\s*=\\s*\\[([\\s\\S]*?)\\];`,
+  ));
+  assert.ok(match, `missing client allowlist: ${variableName}`);
+  return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map((item) => item[1]);
+}
+
+test('local-data action validation accepts exactly the seven declared actions', () => {
+  const accepted = DATA_ACTION_COMMANDS.map(({ action }) => action);
+  assert.deepEqual(
+    Object.keys(LOCAL_DATA_ACTION_TARGETS).sort(),
+    [...accepted].sort(),
+  );
+  for (const action of accepted) {
+    assert.equal(isLocalDataAction(action), true, action);
+  }
+
+  const rejected: unknown[] = [
+    undefined,
+    null,
+    '',
+    ' rebuild-codex-index',
+    'rebuild-codex-index ',
+    'REBUILD-CODEX-INDEX',
+    'clear-provider-logs',
+    'clear-all',
+    {},
+    [],
+    new String('reset-ui-state'),
+  ];
+  for (const candidate of rejected) {
+    assert.equal(isLocalDataAction(candidate), false, String(candidate));
+  }
+});
+
+test('source exclusions and clear-all allowlists cannot target provider logs or credentials', () => {
+  const exclusions = LOCAL_DATA_SOURCE_EXCLUSIONS.join('\n');
+  assert.match(exclusions, /Claude provider-owned source logs/);
+  assert.match(exclusions, /Codex provider-owned source logs/);
+  assert.match(exclusions, /provider-owned OAuth credentials and cookies/);
+
+  const clearAllTargets = LOCAL_DATA_ACTION_TARGETS['clear-all-derived-data'].join('\n');
+  assert.doesNotMatch(
+    clearAllTargets,
+    /provider-owned source logs|provider-owned OAuth credentials|provider-owned cookies/i,
+  );
+
+  const allowlistedState = new Set<string>([
+    ...LOCAL_DATA_GLOBAL_STATE_KEYS,
+    ...LOCAL_DATA_GLOBAL_STATE_PREFIXES,
+  ]);
+  assert.ok(allowlistedState.size > 0);
+  for (const key of allowlistedState) {
+    assert.match(key, /^ccu\./);
+    assert.doesNotMatch(key, /oauth|cookie|provider.?credential|provider.?log/i);
+    assert.notEqual(key, 'ccu.', 'a blanket ccu.* prefix is forbidden');
+    assert.equal(key.includes('*'), false, 'wildcard deletion is forbidden');
+  }
+  assert.equal(allowlistedState.has('claudeCodeUsage.dataDirectory'), false);
+  assert.equal(allowlistedState.has('claudeCodeUsage.codex.dataDirectory'), false);
+});
+
+test('approximateJsonBytes reports UTF-8 JSON bytes and fails closed', () => {
+  const value = { label: '额度', count: 3, enabled: true };
+  const serialized = JSON.stringify(value);
+  assert.equal(
+    approximateJsonBytes(value),
+    Buffer.byteLength(serialized, 'utf8'),
+  );
+  assert.equal(approximateJsonBytes(undefined), null);
+
+  const circular: { self?: unknown } = {};
+  circular.self = circular;
+  assert.equal(approximateJsonBytes(circular), null);
+  assert.equal(approximateJsonBytes(1n), null);
+});
+
+test('finiteTimestampRange filters invalid and negative timestamps', () => {
+  assert.deepEqual(
+    finiteTimestampRange([
+      undefined,
+      null,
+      Number.NaN,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      -1,
+      42,
+      0,
+      7,
+    ]),
+    { oldestAt: 0, newestAt: 42 },
+  );
+  assert.deepEqual(
+    finiteTimestampRange([undefined, null, Number.NaN, -1]),
+    { oldestAt: null, newestAt: null },
+  );
+});
+
+test('quota account epochs group deterministically while public scope fixtures hide fingerprints', () => {
+  const observations = [
+    observation({
+      provider: 'codex',
+      accountFingerprint: 'acct-codex-private-canary',
+      observedAt: 200,
+    }),
+    observation({
+      provider: 'claude',
+      accountFingerprint: 'acct-claude-z-private-canary',
+      observedAt: 300,
+    }),
+    observation({
+      provider: 'claude',
+      accountFingerprint: 'acct-claude-a-private-canary',
+      observedAt: 250,
+    }),
+    observation({
+      provider: 'claude',
+      accountFingerprint: 'acct-claude-z-private-canary',
+      observedAt: 100,
+    }),
+  ];
+
+  const grouped = groupQuotaAccountEpochs(store(observations));
+  const groupedFromReverseInput = groupQuotaAccountEpochs(store([...observations].reverse()));
+  assert.deepEqual(groupedFromReverseInput, grouped);
+  assert.deepEqual(grouped, [
+    {
+      provider: 'claude',
+      accountFingerprint: 'acct-claude-a-private-canary',
+      itemCount: 1,
+      oldestAt: 250,
+      newestAt: 250,
+    },
+    {
+      provider: 'claude',
+      accountFingerprint: 'acct-claude-z-private-canary',
+      itemCount: 2,
+      oldestAt: 100,
+      newestAt: 300,
+    },
+    {
+      provider: 'codex',
+      accountFingerprint: 'acct-codex-private-canary',
+      itemCount: 1,
+      oldestAt: 200,
+      newestAt: 200,
+    },
+  ]);
+
+  const epochNumber = new Map<'claude' | 'codex', number>();
+  const publicOptions: LocalDataQuotaScopeOption[] = grouped.map((epoch) => {
+    const number = (epochNumber.get(epoch.provider) ?? 0) + 1;
+    epochNumber.set(epoch.provider, number);
+    return {
+      token: `scope-${epoch.provider}-${number}`,
+      label: `${epoch.provider} local anonymous account epoch ${number}`,
+      provider: epoch.provider,
+      itemCount: epoch.itemCount,
+      oldestAt: epoch.oldestAt,
+      newestAt: epoch.newestAt,
+    };
+  });
+  for (const option of publicOptions) {
+    assert.deepEqual(Object.keys(option).sort(), [
+      'itemCount',
+      'label',
+      'newestAt',
+      'oldestAt',
+      'provider',
+      'token',
+    ]);
+  }
+  const serializedPublicOptions = JSON.stringify(publicOptions);
+  assert.doesNotMatch(serializedPublicOptions, /accountFingerprint/);
+  assert.doesNotMatch(serializedPublicOptions, /acct-(?:claude|codex)-.*private-canary/);
+});
+
+test('shouldClearQuotaObservation applies all, provider, account, and exact scopes', () => {
+  const claudeA = observation({
+    provider: 'claude',
+    accountFingerprint: 'acct-a',
+  });
+  const claudeB = observation({
+    provider: 'claude',
+    accountFingerprint: 'acct-b',
+  });
+  const codexA = observation({
+    provider: 'codex',
+    accountFingerprint: 'acct-a',
+  });
+
+  assert.equal(shouldClearQuotaObservation(claudeA, {}), true);
+  assert.equal(shouldClearQuotaObservation(codexA, {}), true);
+
+  assert.equal(shouldClearQuotaObservation(claudeA, { provider: 'claude' }), true);
+  assert.equal(shouldClearQuotaObservation(claudeB, { provider: 'claude' }), true);
+  assert.equal(shouldClearQuotaObservation(codexA, { provider: 'claude' }), false);
+
+  assert.equal(shouldClearQuotaObservation(claudeA, { accountFingerprint: 'acct-a' }), true);
+  assert.equal(shouldClearQuotaObservation(codexA, { accountFingerprint: 'acct-a' }), true);
+  assert.equal(shouldClearQuotaObservation(claudeB, { accountFingerprint: 'acct-a' }), false);
+
+  assert.equal(shouldClearQuotaObservation(claudeA, {
+    provider: 'claude',
+    accountFingerprint: 'acct-a',
+  }), true);
+  assert.equal(shouldClearQuotaObservation(claudeB, {
+    provider: 'claude',
+    accountFingerprint: 'acct-a',
+  }), false);
+  assert.equal(shouldClearQuotaObservation(codexA, {
+    provider: 'claude',
+    accountFingerprint: 'acct-a',
+  }), false);
+});
+
+test('source policy keeps controls out of Settings while preserving safe command allowlists', () => {
+  const extensionSource = readFileSync(path.join(REPOSITORY_ROOT, 'src', 'extension.ts'), 'utf8');
+  const webviewSource = readFileSync(path.join(REPOSITORY_ROOT, 'src', 'webview.ts'), 'utf8');
+  const controlsSource = readFileSync(
+    path.join(REPOSITORY_ROOT, 'src', 'localDataControls.ts'),
+    'utf8',
+  );
+  const packageJson = JSON.parse(
+    readFileSync(path.join(REPOSITORY_ROOT, 'package.json'), 'utf8'),
+  ) as { contributes?: { commands?: Array<{ command?: string }> } };
+  const contributedCommands = packageJson.contributes?.commands ?? [];
+  const setupCommands = sourceSlice(
+    extensionSource,
+    'private setupCommands',
+    'private async derivedFileFamilyNames',
+  );
+  const settingsDataSurface = sourceSlice(
+    webviewSource,
+    'private renderLocalDataControls',
+    '/** One row in the settings panel',
+  );
+
+  assert.doesNotMatch(webviewSource, /html \+= this\.renderLocalDataControls\(\);/);
+  for (const { action, command } of DATA_ACTION_COMMANDS) {
+    assert.equal(
+      contributedCommands.filter((entry) => entry.command === command).length,
+      1,
+      `${command} must be contributed exactly once`,
+    );
+    assert.equal(
+      setupCommands.split(`registerCommand('${command}'`).length - 1,
+      1,
+      `${command} must be registered exactly once`,
+    );
+    const commandHandler = action === 'clear-quota-history'
+      ? new RegExp(
+        `registerCommand\\('${escapeRegExp(command)}'[\\s\\S]{0,300}?clearQuotaHistoryFromCommandPalette\\(\\)`,
+      )
+      : new RegExp(
+        `registerCommand\\('${escapeRegExp(command)}'[\\s\\S]{0,300}?runLocalDataActionInteractive\\('${escapeRegExp(action)}'\\)`,
+      );
+    assert.match(setupCommands, commandHandler, `${command} must dispatch ${action}`);
+    assert.equal(
+      settingsDataSurface.split(`runLocalDataAction(\\'${action}\\')`).length - 1,
+      1,
+      `${action} must appear exactly once in Settings/Data`,
+    );
+  }
+
+  const publicRowInterface = controlsSource.match(
+    /export interface LocalDataInventoryRow \{([\s\S]*?)\n\}/,
+  );
+  assert.ok(publicRowInterface);
+  assert.doesNotMatch(
+    publicRowInterface[1],
+    /\b(?:path|fsPath|absolutePath|accountFingerprint)\??\s*:/,
+  );
+
+  const inventoryBuilder = sourceSlice(
+    extensionSource,
+    'private async buildLocalDataInventory',
+    'private async clearQuotaHistoryFromCommandPalette',
+  );
+  assert.doesNotMatch(
+    inventoryBuilder,
+    /(?:^|[,{]\s*)(?:path|fsPath|absolutePath|accountFingerprint)\s*:/m,
+  );
+  assert.doesNotMatch(webviewSource, /row\.(?:path|fsPath|absolutePath|accountFingerprint)\b/);
+
+  const publicRow: LocalDataInventoryRow = {
+    id: 'P2',
+    category: 'Quota observation history',
+    locationClass: 'Extension global storage / quota observations',
+    schema: 'schema 2',
+    approximateBytes: 256,
+    itemCount: 2,
+    oldestAt: 100,
+    newestAt: 200,
+    networkInteraction: 'None for this fixture',
+    clearability: 'Scoped clear',
+  };
+  assert.doesNotMatch(JSON.stringify(publicRow), /accountFingerprint|"(?:path|fsPath|absolutePath)"/);
+  for (const value of Object.values(publicRow)) {
+    if (typeof value === 'string') {
+      assert.doesNotMatch(value, /^(?:\/|[A-Za-z]:[\\/])/);
+    }
+  }
+
+  const uiKeys = sourceStringArray(webviewSource, '__ccuUiPreferenceKeys');
+  const sharingKeys = sourceStringArray(webviewSource, '__ccuSharingPreferenceKeys');
+  assert.ok(uiKeys.length > 0);
+  assert.ok(sharingKeys.length > 0);
+  assert.deepEqual(
+    uiKeys.filter((key) => sharingKeys.includes(key)),
+    [],
+    'UI and sharing client allowlists must remain disjoint',
+  );
+
+  const clearAll = sourceSlice(
+    extensionSource,
+    'private async clearAllExtensionDerivedData',
+    'private async refreshPricing',
+  );
+  assert.match(clearAll, /resetAllOwnedData\(\)/);
+  assert.match(clearAll, /quotaObservationRepository\.clear\(\{\}\)/);
+  assert.match(clearAll, /verifyClearAllPostcondition\(\)/);
+  assert.match(clearAll, /LOCAL_DATA_EXACT_GLOBAL_STATE_KEYS\.includes/);
+  assert.match(clearAll, /LOCAL_DATA_GLOBAL_STATE_PREFIXES\.some/);
+  assert.doesNotMatch(clearAll, /key\.startsWith\(\s*['"]ccu\.['"]\s*\)/);
+  assert.doesNotMatch(clearAll, /['"]ccu\.\*['"]/);
+});
diff --git a/src/test/localDataExtension.test.ts b/src/test/localDataExtension.test.ts
new file mode 100644
index 00000000..0fc6164e
--- /dev/null
+++ b/src/test/localDataExtension.test.ts
@@ -0,0 +1,330 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { mkdir, writeFile } from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import Module = require('node:module');
+
+import { createEmptyQuotaObservationStore } from '../quotaObservationStore';
+
+type ExtensionModule = typeof import('../extension');
+
+function loadExtensionModule(): ExtensionModule {
+  const originalLoad = (Module as any)._load;
+  const vscodeStub: any = new Proxy(function () {}, {
+    get: (_target, property) => property === 'then' ? undefined : vscodeStub,
+    apply: () => vscodeStub,
+    construct: () => vscodeStub,
+  });
+  (Module as any)._load = function(request: string, parent: unknown, isMain: boolean) {
+    if (request === 'vscode') return vscodeStub;
+    return originalLoad.call(this, request, parent, isMain);
+  };
+  try {
+    return require('../extension') as ExtensionModule;
+  } finally {
+    (Module as any)._load = originalLoad;
+  }
+}
+
+const { ClaudeCodeUsageExtension } = loadExtensionModule();
+
+function memoryGlobalState(initial: Record<string, unknown>) {
+  const state = new Map(Object.entries(initial));
+  return {
+    get<T>(key: string, fallback?: T): T | undefined {
+      return (state.has(key) ? state.get(key) : fallback) as T | undefined;
+    },
+    async update(key: string, value: unknown): Promise<void> {
+      if (value === undefined) state.delete(key);
+      else state.set(key, value);
+    },
+    keys(): readonly string[] {
+      return [...state.keys()];
+    },
+    state,
+  };
+}
+
+test('host inventory exposes only value-free location classes and random quota scope tokens', async () => {
+  const root = path.join(os.tmpdir(), `ccu-local-inventory-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  await writeFile(path.join(root, 'codex-index-v1.json'), '{"schemaVersion":3}', 'utf8');
+  await writeFile(path.join(root, 'quota-observations-v2.json'), '{"schemaVersion":2}', 'utf8');
+  const globalState = memoryGlobalState({
+    'ccu.setting.privateCanary': '/Users/private/account/path',
+    'ccu.heatmapRepo': 'private-owner/private-repo',
+    'ccu.codex.machineSalt': 'machine-salt-canary',
+  });
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  extension.context = {
+    globalStorageUri: { fsPath: root },
+    globalState,
+  };
+  extension.outputChannel = { appendLine: () => undefined };
+  extension.localDataQuotaScopes = new Map();
+  extension.quotaObservationStore = {
+    schemaVersion: 2,
+    fingerprintAlgorithm: 'hmac-sha256-v1',
+    observations: [{
+      schemaVersion: 2,
+      provider: 'codex',
+      accountFingerprint: 'fingerprint-private-canary',
+      accountAttribution: 'unattributed',
+      observedAt: Date.parse('2026-09-02T00:00:00Z'),
+      periodType: 'seven-day',
+      usedFraction: 0.25,
+      remainingFraction: 0.75,
+      resetAt: Date.parse('2026-09-07T00:00:00Z'),
+      source: 'codex-local-structured-event',
+      windowId: 'window-private-canary',
+      providerWindowFingerprint: null,
+      confidence: 'low',
+      captureReason: 'refresh',
+      flags: [],
+    }],
+  };
+  extension.settings = {
+    snapshot: () => [{ key: 'advice.apiKey', configured: true, value: '' }],
+  };
+  extension.webviewProvider = {
+    adviceLocalDataInventorySummary: () => ({
+      approximateBytes: 80,
+      itemCount: 2,
+      oldestAt: 1,
+      newestAt: 2,
+    }),
+  };
+
+  const inventory = await extension.buildLocalDataInventory({
+    uiPreferenceKeys: 2,
+    webviewStateFields: 3,
+    sharingPreferenceKeys: 1,
+  });
+  const serialized = JSON.stringify(inventory);
+  assert.equal(inventory.schemaVersion, 1);
+  assert.deepEqual(inventory.rows.map((row: any) => row.id), [
+    'R1', 'R2', 'P1', 'P2', 'P3-P4', 'P5', 'P6', 'P7', 'P8', 'P9', 'P10', 'P11',
+  ]);
+  assert.doesNotMatch(serialized, /Users\/private|private-owner|private-repo/);
+  assert.doesNotMatch(serialized, /fingerprint-private-canary|window-private-canary|machine-salt-canary/);
+  assert.doesNotMatch(serialized, new RegExp(root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  assert.ok(inventory.quotaScopes.length >= 2);
+  assert.ok(inventory.quotaScopes.every((scope: any) => /^[a-f0-9]{36}$/.test(scope.token)));
+  assert.ok(inventory.quotaScopes.every((scope: any) => !('accountFingerprint' in scope)));
+  assert.equal(extension.localDataQuotaScopes.size, inventory.quotaScopes.length);
+  assert.equal(inventory.rows.find((row: any) => row.id === 'P10')?.itemCount, 5);
+  assert.equal(inventory.rows.find((row: any) => row.id === 'P11')?.itemCount, 2);
+  assert.equal(inventory.rows.find((row: any) => row.id === 'P7')?.approximateBytes, null);
+});
+
+test('derived-file family matching accepts only exact canonical, recovery, and interrupted-write names', async () => {
+  const root = path.join(os.tmpdir(), `ccu-local-family-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const names = [
+    'codex-index-v1.json',
+    'codex-index-v1.corrupt-100-200.json',
+    'codex-index-v1.json.tmp-200-123e4567-e89b-12d3-a456-426614174000',
+    'codex-index-v1.corrupt-100-200.json.bak',
+    'codex-index-v1.json.lock',
+    'codex-index-v1.json.lock.pending-123e4567-e89b-12d3-a456-426614174000',
+    'quota-observations-v2.json',
+    'quota-observations-v2.json.quarantine-100-deadbeef',
+    '.quota-observations-v2.json.200.abcdef123456.tmp',
+    'quota-observations-v2.json.quarantine-100-deadbeef.bak',
+    'quota-observations-v2.json.lock',
+    'unrelated.json',
+  ];
+  await Promise.all(names.map((name) => writeFile(path.join(root, name), 'fixture', 'utf8')));
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+
+  assert.deepEqual(
+    (await extension.derivedFileFamilyNames(
+      path.join(root, 'codex-index-v1.json'),
+      'codex-index',
+    )).sort(),
+    [
+      'codex-index-v1.corrupt-100-200.json',
+      'codex-index-v1.json',
+      'codex-index-v1.json.tmp-200-123e4567-e89b-12d3-a456-426614174000',
+    ].sort(),
+  );
+  assert.deepEqual(
+    (await extension.derivedFileFamilyNames(
+      path.join(root, 'quota-observations-v2.json'),
+      'quota-observations',
+    )).sort(),
+    [
+      '.quota-observations-v2.json.200.abcdef123456.tmp',
+      'quota-observations-v2.json',
+      'quota-observations-v2.json.quarantine-100-deadbeef',
+    ].sort(),
+  );
+});
+
+test('provider-wide quota clear removes only matching migration inputs and seals P5 against resurrection', async () => {
+  const globalState = memoryGlobalState({
+    'ccu.usageLimits.profile-a': { legacy: true },
+    'ccu.weeklyQuotaHistory.v1.profile-a': [{ legacy: true }],
+    'ccu.unrelated.canary': 'preserve',
+  });
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  extension.context = { globalState };
+
+  await extension.clearLegacyQuotaMigrationInputs({ provider: 'claude' });
+  assert.equal(globalState.state.has('ccu.usageLimits.profile-a'), false);
+  assert.equal(globalState.state.has('ccu.weeklyQuotaHistory.v1.profile-a'), false);
+  assert.equal(globalState.state.has('ccu.quota.migratedCodexIndex.v2'), false);
+  assert.equal(globalState.state.get('ccu.unrelated.canary'), 'preserve');
+
+  await extension.clearLegacyQuotaMigrationInputs({
+    provider: 'codex',
+    accountFingerprint: 'opaque-local-fingerprint',
+  });
+  assert.equal(globalState.state.get('ccu.quota.migratedCodexIndex.v2'), undefined);
+  await extension.clearLegacyQuotaMigrationInputs({ provider: 'codex' });
+  assert.equal(globalState.state.get('ccu.quota.migratedCodexIndex.v2'), true);
+  assert.equal(globalState.state.get('ccu.unrelated.canary'), 'preserve');
+});
+
+test('account-scoped quota clear refuses unresolved Claude and Codex migration inputs', () => {
+  const globalState = memoryGlobalState({
+    'ccu.usageLimits.profile-a': { legacy: true },
+  });
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  extension.context = { globalState };
+
+  assert.throws(
+    () => extension.assertScopedQuotaMigrationIsResolved({
+      provider: 'claude',
+      accountFingerprint: 'opaque-claude-epoch',
+    }),
+    /scoped-clear-blocked-by-unresolved-migration/,
+  );
+  assert.throws(
+    () => extension.assertScopedQuotaMigrationIsResolved({
+      provider: 'codex',
+      accountFingerprint: 'opaque-codex-epoch',
+    }),
+    /scoped-clear-blocked-by-unresolved-migration/,
+  );
+
+  globalState.state.delete('ccu.usageLimits.profile-a');
+  globalState.state.set('ccu.quota.migratedCodexIndex.v2', true);
+  assert.doesNotThrow(() => extension.assertScopedQuotaMigrationIsResolved({
+    provider: 'claude',
+    accountFingerprint: 'opaque-claude-epoch',
+  }));
+  assert.doesNotThrow(() => extension.assertScopedQuotaMigrationIsResolved({
+    provider: 'codex',
+    accountFingerprint: 'opaque-codex-epoch',
+  }));
+});
+
+test('pending Webview reset tombstone survives failure and clears only after verified ACK', async () => {
+  const globalState = memoryGlobalState({
+    'ccu.localData.pendingClientReset.v1': 'clear-all-client-state',
+  });
+  const acknowledgements = [false, true];
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  extension.context = { globalState };
+  extension.pendingClientResetReplay = Promise.resolve();
+  extension.webviewProvider = {
+    requestClientLocalDataAction: async (action: string) => {
+      assert.equal(action, 'clear-all-client-state');
+      return acknowledgements.shift() ?? false;
+    },
+  };
+
+  await extension.replayPendingClientReset();
+  assert.equal(
+    globalState.state.get('ccu.localData.pendingClientReset.v1'),
+    'clear-all-client-state',
+  );
+  await extension.replayPendingClientReset();
+  assert.equal(globalState.state.has('ccu.localData.pendingClientReset.v1'), false);
+});
+
+test('clear-all uses the exact allowlist and preserves unrelated state', async () => {
+  const globalState = memoryGlobalState({
+    'ccu.setting.showCost': true,
+    'ccu.setting.unknown-canary': 'must-survive',
+    'ccu.lastSeenVersion': '2.3.0',
+    'ccu.heatmapRepo': 'owner/repo',
+    'ccu.adviceEffectiveness.localState': { schemaVersion: 3 },
+    'claudeCodeUsage.adviceEffectiveness.feedback.v1': { schemaVersion: 1 },
+    'ccu.unrelated.canary': 'must-survive',
+    'provider.credentials.canary': 'must-survive',
+  });
+  const resetSettings: string[] = [];
+  const extension = Object.create(ClaudeCodeUsageExtension.prototype) as any;
+  extension.context = { globalState, globalStorageUri: { fsPath: '/synthetic/global-storage' } };
+  extension.settings = {
+    preflightResetAllOwnedData: () => undefined,
+    resetAllOwnedData: async () => { resetSettings.push('advice.apiKey'); },
+  };
+  let releaseInitialization!: () => void;
+  extension.initializationWrites = new Promise<void>((resolve) => {
+    releaseInitialization = () => {
+      globalState.state.set('ccu.codex.machineSalt', 'late-initialization-write');
+      resolve();
+    };
+  });
+  extension.initializationWriteFailure = null;
+  extension.stopQuotaColdRetry = () => undefined;
+  extension.stopAutoRefresh = () => undefined;
+  extension.stopFileWatching = () => undefined;
+  extension.stopCredentialsWatching = () => undefined;
+  extension.cancelAdviceNetworks = async () => undefined;
+  extension.cancelQuotaNetworks = async () => undefined;
+  let codexClearCalls = 0;
+  extension.clearCodexDerivedIndex = async (rebuild: boolean) => {
+    assert.equal(rebuild, false);
+    codexClearCalls += 1;
+  };
+  extension.quotaObservationRepository = {
+    clear: async () => createEmptyQuotaObservationStore(),
+  };
+  extension.removeDerivedFileFamilyWithLease = async () => undefined;
+  extension.quotaObservationStore = createEmptyQuotaObservationStore();
+  let adviceClearCalls = 0;
+  extension.webviewProvider = {
+    clearAdviceLocalData: async () => { adviceClearCalls += 1; return true; },
+    clearSharingRuntimeState: () => undefined,
+  };
+  extension.claudeWeeklyQuotaHistory = [];
+  extension.cache = {
+    usageLimits: null,
+    usageLimitsLastUpdate: new Date(0),
+    records: [{ synthetic: true }],
+    contentAnalysis: null,
+    claudeIndex: {},
+  };
+  extension.codexView = null;
+  extension.codexInsights = {};
+  extension.codexHasData = false;
+  extension.refreshQuotaObservationViews = () => undefined;
+  extension.syncProviderUi = () => undefined;
+  extension.verifyClearAllPostcondition = async () => undefined;
+
+  const pendingResult = extension.clearAllExtensionDerivedData();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(resetSettings.length, 0, 'clear waits for the initialization write barrier');
+  releaseInitialization();
+  const result = await pendingResult;
+
+  assert.equal(result.ok, true);
+  assert.equal(result.clientAction, 'clear-all-client-state');
+  assert.equal(codexClearCalls, 1);
+  assert.equal(adviceClearCalls, 1);
+  assert.ok(resetSettings.includes('advice.apiKey'));
+  assert.equal(globalState.state.has('ccu.setting.showCost'), false);
+  assert.equal(globalState.state.get('ccu.setting.unknown-canary'), 'must-survive');
+  assert.equal(globalState.state.has('ccu.lastSeenVersion'), false);
+  assert.equal(globalState.state.has('ccu.heatmapRepo'), false);
+  assert.equal(globalState.state.has('ccu.adviceEffectiveness.localState'), false);
+  assert.equal(globalState.state.has('ccu.codex.machineSalt'), false);
+  assert.equal(globalState.state.has('claudeCodeUsage.adviceEffectiveness.feedback.v1'), false);
+  assert.equal(globalState.state.get('ccu.unrelated.canary'), 'must-survive');
+  assert.equal(globalState.state.get('provider.credentials.canary'), 'must-survive');
+});
diff --git a/src/test/optimizerPreparedFlow.test.ts b/src/test/optimizerPreparedFlow.test.ts
new file mode 100644
index 00000000..931e874c
--- /dev/null
+++ b/src/test/optimizerPreparedFlow.test.ts
@@ -0,0 +1,84 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import {
+  prepareOptimizerInvocation,
+  requestPreparedOptimizer,
+} from '../optimizerRequest';
+import { previewAiInvocation } from '../adviceEffectiveness/preparedRequest';
+
+const base = {
+  apiFormat: 'openai' as const,
+  apiUrl: 'https://example.invalid/v1',
+  model: 'private-model',
+  reasoningEffort: 'high',
+  systemPrompt: 'Return the exact optimizer markers.',
+  draft: 'Fix the cache bug without changing public APIs.',
+  sourceRevision: 'optimizer-draft-42',
+  consentGeneration: 2,
+  createdAtEpochMs: 1_000,
+};
+
+test('optimizer preview and explicit sender share the complete provider bytes', async () => {
+  const prepared = prepareOptimizerInvocation(base);
+  const preview = previewAiInvocation(prepared);
+  let calls = 0;
+  let sent: Uint8Array | undefined;
+  const result = await requestPreparedOptimizer(prepared, {
+    apiKey: 'PRIVATE_API_KEY',
+    expectedSourceRevision: base.sourceRevision,
+    expectedConsentGeneration: base.consentGeneration,
+    transport: async (request) => {
+      calls += 1;
+      sent = request.canonicalBytes;
+      return {
+        status: 200,
+        body: JSON.stringify({
+          choices: [{ message: { content:
+            '===PROMPT===\nFix the cache bug. Keep public APIs unchanged.\n' +
+            '===SETTINGS===\n' +
+            'Effort: high — Requires tracing state.\n' +
+            'Thinking: on — Verify the invariant.\n' +
+            'Model: opus — Ambiguous debugging task.' } }],
+        }),
+      };
+    },
+  });
+  assert.equal(result.ok, true);
+  assert.equal(calls, 1);
+  assert.strictEqual(sent, prepared.canonicalBytes);
+  assert.equal(Buffer.from(sent!).toString('utf8'), preview.body);
+  assert.doesNotMatch(preview.body, /PRIVATE_API_KEY/);
+});
+
+test('optimizer rejects malformed model output without a marker-free fallback', async () => {
+  const prepared = prepareOptimizerInvocation(base);
+  const result = await requestPreparedOptimizer(prepared, {
+    apiKey: 'PRIVATE_API_KEY',
+    transport: async () => ({
+      status: 200,
+      body: JSON.stringify({ choices: [{ message: { content: 'Just use a clearer prompt.' } }] }),
+    }),
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    code: 'invalid-output',
+    issues: ['optimizer output did not match the strict response contract'],
+  });
+});
+
+test('optimizer stale consent fails before transport', async () => {
+  const prepared = prepareOptimizerInvocation(base);
+  let calls = 0;
+  const result = await requestPreparedOptimizer(prepared, {
+    apiKey: 'PRIVATE_API_KEY',
+    expectedConsentGeneration: 3,
+    transport: async () => {
+      calls += 1;
+      return { status: 200, body: '{}' };
+    },
+  });
+  assert.equal(result.ok, false);
+  if (!result.ok) assert.equal(result.code, 'transport-error');
+  assert.equal(calls, 0);
+});
diff --git a/src/test/pricing.test.ts b/src/test/pricing.test.ts
index f92e6b52..6d0e1b48 100644
--- a/src/test/pricing.test.ts
+++ b/src/test/pricing.test.ts
@@ -14,7 +14,12 @@
 import { test } from 'node:test';
 import * as assert from 'node:assert/strict';
 
-import { calculateCostFromTokens, calculateCostBreakdown, getModelPricing } from '../pricing';
+import {
+  calculateCostFromTokens,
+  calculateCostBreakdown,
+  getModelPricing,
+  setPricingBackend,
+} from '../pricing';
 
 test('calculateCostFromTokens prices a known model from its per-token rates', () => {
   // Opus current tier: $5 / $25 / $6.25 / $0.50 per million in/out/write/read.
@@ -83,3 +88,143 @@ test('getModelPricing falls back to the right family for an unknown snapshot', (
   assert.ok(pricing, 'expected a fallback pricing object, got null');
   assert.equal(pricing!.input_cost_per_token, 5 / 1_000_000);
 });
+
+test('Fable 5.1 uses its reduced cache-read rate without changing Fable 5 history', () => {
+  for (const model of ['claude-fable-5-1', 'claude-mythos-5-1', 'claude-fable-5-1[1m]']) {
+    const pricing = getModelPricing(model);
+    assert.ok(pricing, `expected pricing for ${model}, got null`);
+    assert.equal(pricing!.input_cost_per_token, 10 / 1_000_000, model);
+    assert.equal(pricing!.output_cost_per_token, 50 / 1_000_000, model);
+    assert.equal(pricing!.cache_creation_input_token_cost, 12.5 / 1_000_000, model);
+    assert.equal(pricing!.cache_creation_1h_input_token_cost, 20 / 1_000_000, model);
+    assert.equal(pricing!.cache_read_input_token_cost, 0.25 / 1_000_000, model);
+  }
+
+  assert.equal(
+    getModelPricing('claude-fable-5')!.cache_read_input_token_cost,
+    1 / 1_000_000,
+    'historical Fable 5 cache reads keep their original price',
+  );
+});
+
+test('GPT-6 Astra uses official Standard short-context rates', () => {
+  for (const model of ['gpt-6-astra', 'openai/gpt-6-astra']) {
+    const pricing = getModelPricing(model);
+    assert.ok(pricing, `expected pricing for ${model}, got null`);
+    assert.equal(pricing!.input_cost_per_token, 10 / 1_000_000, model);
+    assert.equal(pricing!.output_cost_per_token, 50 / 1_000_000, model);
+    assert.equal(pricing!.cache_creation_input_token_cost, 12.5 / 1_000_000, model);
+    assert.equal(pricing!.cache_read_input_token_cost, 1 / 1_000_000, model);
+  }
+});
+
+test('AWS Bedrock mode prices Claude 5 models with in-region rates', () => {
+  setPricingBackend('aws-bedrock-in-region');
+  try {
+    for (const model of [
+      'claude-sonnet-5',
+      'us.anthropic.claude-sonnet-5-v1:0',
+      'claude-sonnet-5[1m]',
+    ]) {
+      const pricing = getModelPricing(model);
+      assert.ok(pricing, `expected Bedrock pricing for ${model}, got null`);
+      assert.equal(pricing!.input_cost_per_token, 3.3 / 1_000_000, model);
+      assert.equal(pricing!.output_cost_per_token, 16.5 / 1_000_000, model);
+      assert.equal(pricing!.cache_creation_input_token_cost, 4.125 / 1_000_000, model);
+      assert.equal(pricing!.cache_creation_1h_input_token_cost, 6.6 / 1_000_000, model);
+      assert.equal(pricing!.cache_read_input_token_cost, 0.33 / 1_000_000, model);
+    }
+
+    const cost = calculateCostFromTokens(
+      {
+        input_tokens: 1_000_000,
+        output_tokens: 1_000_000,
+        cache_creation_input_tokens: 1_000_000,
+        cache_read_input_tokens: 1_000_000,
+      },
+      'claude-sonnet-5',
+    );
+    assert.ok(Math.abs(cost - 24.255) < 1e-9, `expected ~24.255, got ${cost}`);
+  } finally {
+    setPricingBackend('anthropic');
+  }
+});
+
+test('AWS Bedrock mode prices Claude Opus 4.5-4.8 with in-region rates', () => {
+  setPricingBackend('aws-bedrock-in-region');
+  try {
+    for (const model of [
+      'claude-opus-4-8',
+      'claude-opus-4-7',
+      'claude-opus-4-6',
+      'claude-opus-4-5-20251101',
+      'us.anthropic.claude-opus-4-8-v1:0',
+    ]) {
+      const pricing = getModelPricing(model);
+      assert.ok(pricing, `expected Bedrock pricing for ${model}, got null`);
+      assert.equal(pricing!.input_cost_per_token, 5.5 / 1_000_000, model);
+      assert.equal(pricing!.output_cost_per_token, 27.5 / 1_000_000, model);
+      assert.equal(pricing!.cache_creation_input_token_cost, 6.875 / 1_000_000, model);
+      assert.equal(pricing!.cache_creation_1h_input_token_cost, 11 / 1_000_000, model);
+      assert.equal(pricing!.cache_read_input_token_cost, 0.55 / 1_000_000, model);
+    }
+  } finally {
+    setPricingBackend('anthropic');
+  }
+});
+
+test('AWS Bedrock mode prices Claude Sonnet 4.5 and 4.6 with in-region rates', () => {
+  setPricingBackend('aws-bedrock-in-region');
+  try {
+    for (const model of [
+      'claude-sonnet-4-6',
+      'claude-sonnet-4-5-20250929',
+      'claude-sonnet-4-5',
+      'us.anthropic.claude-sonnet-4-6-v1:0',
+      'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+      'claude-sonnet-4.5',
+      'claude_sonnet_4_5',
+    ]) {
+      const pricing = getModelPricing(model);
+      assert.ok(pricing, `expected Bedrock pricing for ${model}, got null`);
+      assert.equal(pricing!.input_cost_per_token, 3.3 / 1_000_000, model);
+      assert.equal(pricing!.output_cost_per_token, 16.5 / 1_000_000, model);
+      assert.equal(pricing!.cache_creation_input_token_cost, 4.125 / 1_000_000, model);
+      assert.equal(pricing!.cache_creation_1h_input_token_cost, 6.6 / 1_000_000, model);
+      assert.equal(pricing!.cache_read_input_token_cost, 0.33 / 1_000_000, model);
+    }
+
+    const cost = calculateCostFromTokens(
+      {
+        input_tokens: 1_000_000,
+        output_tokens: 1_000_000,
+        cache_creation_input_tokens: 1_000_000,
+        cache_read_input_tokens: 1_000_000,
+      },
+      'claude-sonnet-4-5-20250929',
+    );
+    assert.ok(Math.abs(cost - 24.255) < 1e-9, `expected ~24.255, got ${cost}`);
+  } finally {
+    setPricingBackend('anthropic');
+  }
+});
+
+test('Claude Sonnet 4.5 switches between direct and Bedrock rates for the same model id', () => {
+  const model = 'claude-sonnet-4-5-20250929';
+
+  setPricingBackend('anthropic');
+  const direct = getModelPricing(model);
+  assert.ok(direct);
+  assert.equal(direct.input_cost_per_token, 3 / 1_000_000);
+  assert.equal(direct.output_cost_per_token, 15 / 1_000_000);
+
+  setPricingBackend('aws-bedrock-in-region');
+  try {
+    const bedrock = getModelPricing(model);
+    assert.ok(bedrock);
+    assert.equal(bedrock.input_cost_per_token, 3.3 / 1_000_000);
+    assert.equal(bedrock.output_cost_per_token, 16.5 / 1_000_000);
+  } finally {
+    setPricingBackend('anthropic');
+  }
+});
diff --git a/src/test/promptOrigin.test.ts b/src/test/promptOrigin.test.ts
new file mode 100644
index 00000000..a062918e
--- /dev/null
+++ b/src/test/promptOrigin.test.ts
@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+import { classifyPromptTextOrigin } from '../promptOrigin';
+
+test('prompt origin classifier separates framework structures without semantic guessing', () => {
+  assert.equal(classifyPromptTextOrigin({ text: 'Fix the login bug' }), 'user-authored');
+  assert.equal(classifyPromptTextOrigin({ text: '<div>user pasted HTML</div>' }), 'user-authored');
+  assert.equal(classifyPromptTextOrigin({ text: 'anything', isMeta: true }), 'meta');
+  assert.equal(classifyPromptTextOrigin({ text: 'anything', isSidechain: true }), 'sidechain');
+  assert.equal(classifyPromptTextOrigin({ text: 'dispatch', isSubagentFile: true }), 'subagent-dispatch');
+  assert.equal(
+    classifyPromptTextOrigin({ text: '<command-name>/review</command-name>' }),
+    'command-echo',
+  );
+  assert.equal(
+    classifyPromptTextOrigin({ text: '<system-reminder>private framework text</system-reminder>' }),
+    'system-reminder',
+  );
+  assert.equal(
+    classifyPromptTextOrigin({ text: 'User-looking prefix <system-reminder>PRIVATE</system-reminder>' }),
+    'system-reminder',
+  );
+  assert.equal(
+    classifyPromptTextOrigin({ text: '<local-command-stdout>output</local-command-stdout>' }),
+    'command-echo',
+  );
+  assert.equal(
+    classifyPromptTextOrigin({ text: '<agent-context>injected</agent-context>' }),
+    'user-authored',
+  );
+  assert.equal(
+    classifyPromptTextOrigin({ text: '<my-component>user-authored markup</my-component>' }),
+    'user-authored',
+  );
+});
diff --git a/src/test/providerSelection.test.ts b/src/test/providerSelection.test.ts
index 104d5c86..d15b4fff 100644
--- a/src/test/providerSelection.test.ts
+++ b/src/test/providerSelection.test.ts
@@ -122,7 +122,14 @@ test('Codex dashboard HTML uses only classes already rendered by the Claude dash
     provider.currentProvider = 'codex';
     const codexHtml = provider.getMainContent();
     const codexClasses = renderedClasses(codexHtml);
-    const codexOnly = [...codexClasses].filter((className) => !claudeClasses.has(className)).sort();
+    // The weekly allowance disclosure is shared by both providers, but this
+    // compact Claude fixture has no quota observations and therefore does not
+    // render that optional surface. Keep the parity gate strict for every
+    // unconditional class while acknowledging this data-dependent shared one.
+    const conditionalShared = new Set(['weekly-value-details']);
+    const codexOnly = [...codexClasses]
+      .filter((className) => !claudeClasses.has(className) && !conditionalShared.has(className))
+      .sort();
 
     assert.deepEqual(codexOnly, []);
     const equivalentCostIndex = codexHtml.indexOf('API-equivalent cost');
@@ -208,6 +215,7 @@ test('Codex tab stays visible while its first index is still running', () => {
           totalFiles: 1_827,
           indexedBytes: 1_024,
           totalBytes: 4_096,
+          reason: 'first-index',
         },
       },
     );
@@ -217,6 +225,7 @@ test('Codex tab stays visible while its first index is still running', () => {
     assert.match(html, /id="provider-tab-codex"/);
     assert.doesNotMatch(html, /id="provider-tab-compare"/);
     assert.match(html, /Indexing is still in progress/);
+    assert.match(html, /First local history setup/);
     assert.match(html, /Indexed log entries[^<]*1,566\/1,827 \(86%\)/);
     assert.doesNotMatch(html, /1\.6K\/1\.8K/);
     assert.match(html, /Indexed storage[^<]*1kB\/4kB/i);
@@ -226,6 +235,51 @@ test('Codex tab stays visible while its first index is still running', () => {
   }
 });
 
+test('Codex index progress patches live text without rebuilding the webview', () => {
+  const originalLoad = (Module as any)._load;
+  const originalLanguage = I18n.getCurrentLanguage();
+  I18n.setLanguage('en');
+  (Module as any)._load = function(request: string, parent: unknown, isMain: boolean) {
+    if (request === 'vscode') {
+      return { workspace: { workspaceFolders: [] } };
+    }
+    return originalLoad.call(this, request, parent, isMain);
+  };
+  try {
+    const { UsageWebviewProvider } = require('../webview') as typeof import('../webview');
+    const provider = new UsageWebviewProvider({} as any) as any;
+    const messages: Array<Record<string, unknown>> = [];
+    let rebuilds = 0;
+    provider.panel = {
+      webview: {
+        postMessage: (message: Record<string, unknown>) => {
+          messages.push(message);
+          return Promise.resolve(true);
+        },
+      },
+    };
+    provider.currentProvider = 'codex';
+    provider.updateWebview = () => { rebuilds += 1; };
+
+    provider.updateCodexProgress({
+      scannedFiles: 1_566,
+      totalFiles: 1_827,
+      indexedBytes: 1_024,
+      totalBytes: 4_096,
+      reason: 'first-index',
+    });
+
+    assert.equal(rebuilds, 0);
+    assert.equal(messages.length, 1);
+    assert.equal(messages[0].command, 'codexIndexProgress');
+    assert.match(String(messages[0].text), /Indexed log entries: 1,566\/1,827 \(86%\)/);
+    assert.match(String(messages[0].text), /Indexed storage: 1kB\/4kB/i);
+  } finally {
+    I18n.setLanguage(originalLanguage);
+    (Module as any)._load = originalLoad;
+  }
+});
+
 test('webview provider changes are allowlisted and kept outside time tabs', () => {
   const source = readFileSync(
     path.resolve(__dirname, '..', '..', 'src', 'webview.ts'),
@@ -353,7 +407,7 @@ test('provider and Codex view copy is complete in every UI locale', () => {
         if (typeof value === 'string') {
           assert.notEqual(value.trim(), '', `${language} has empty Codex copy`);
         } else {
-          assert.ok([5, 15, 16, 17, 18].includes(Object.keys(value).length));
+          assert.ok([5, 7, 15, 16, 17, 18].includes(Object.keys(value).length));
         }
       }
       assert.deepEqual(
@@ -424,7 +478,13 @@ test('provider and Codex view copy is complete in every UI locale', () => {
     assert.doesNotMatch(englishVisibleCopy, /\b(?:fresh|new)\b/i);
     const settingsSource = readFileSync(path.resolve(__dirname, '..', '..', 'src', 'settings.ts'), 'utf8');
     assert.match(settingsSource, /key: 'codex\.statusMetric'[\s\S]*?enumValues: \['fresh', 'processed', 'output'\][\s\S]*?enumLabels: \['Uncached', 'Processed', 'Output'\]/);
-    assert.match(settingsSource, /help: 'Uncached usage, processed tokens, or output tokens\.'/);
+    assert.match(settingsSource, /help: "Today's uncached usage, processed tokens, or output tokens\."/);
+    const extensionSource = readFileSync(path.resolve(__dirname, '..', '..', 'src', 'extension.ts'), 'utf8');
+    assert.match(
+      extensionSource,
+      /statusBar\.updateCodex\(\s*this\.codexView\.today,\s*config\.codexStatusMetric,/,
+      'Codex status must use the configured-zone Today scope, not the recent task scope',
+    );
   } finally {
     I18n.setLanguage(previous);
   }
diff --git a/src/test/quotaI18n.test.ts b/src/test/quotaI18n.test.ts
index 01d74828..61fb56ea 100644
--- a/src/test/quotaI18n.test.ts
+++ b/src/test/quotaI18n.test.ts
@@ -126,3 +126,30 @@ test('every settings-catalog key has a label in every non-English locale', () =>
   }
   assert.deepEqual(missing, [], `untranslated setting labels: ${missing.join(', ')}`);
 });
+
+test('BYOK privacy copy points every locale to SecretStorage, not plaintext settings', () => {
+  for (const lang of LOCALES) {
+    withLanguage(lang, () => {
+      const text = lang === 'en'
+        ? (() => {
+            const src = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'settings.ts'), 'utf8');
+            const match = src.match(/key: 'advice\.apiKey',[\s\S]*?help: '([^']+)'/);
+            return { help: match?.[1] ?? '' };
+          })()
+        : I18n.settingText('advice.apiKey');
+      assert.match(text.help ?? '', /SecretStorage/, `${lang}: BYOK help must name SecretStorage`);
+      assert.doesNotMatch(
+        I18n.t.popup.adviceDemoNotice,
+        /claudeCodeUsage\.advice\.apiKey/,
+        `${lang}: demo must not direct users to the retired plaintext setting`,
+      );
+      assert.ok(I18n.t.popup.secretMigrationFailed.length > 20, `${lang}: needs migration failure copy`);
+      assert.ok(I18n.t.popup.secretMigrationWorkspace.length > 20, `${lang}: needs workspace migration copy`);
+      assert.doesNotMatch(
+        I18n.t.popup.secretMigrationFailed + I18n.t.popup.secretMigrationWorkspace,
+        /\$\{|apiKey\}|\.message/,
+        `${lang}: failure copy must be fixed and never interpolate a provider error`,
+      );
+    });
+  }
+});
diff --git a/src/test/quotaObservationStore.test.ts b/src/test/quotaObservationStore.test.ts
new file mode 100644
index 00000000..694a9083
--- /dev/null
+++ b/src/test/quotaObservationStore.test.ts
@@ -0,0 +1,526 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import {
+  createEmptyQuotaObservationStore,
+  deriveQuotaResetEvents,
+  fingerprintForStableIdentity,
+  loadQuotaObservationStore,
+  mergeQuotaCaptures,
+  QuotaCapture,
+  QuotaObservationRepository,
+  QuotaObservationScopedClearBlockedError,
+  quotaStoreWeeklyObservations,
+  saveQuotaObservationStoreAtomic,
+} from '../quotaObservationStore';
+
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+const NOW = Date.parse('2026-09-02T12:00:00.000Z');
+const RESET = Date.parse('2026-09-07T03:24:00.000Z');
+const SALT = '00112233445566778899aabbccddeeff';
+
+function capture(overrides: Partial<QuotaCapture> = {}): QuotaCapture {
+  return {
+    provider: 'codex',
+    unattributedEpochSignal: 'fixture-codex-epoch',
+    accountAttribution: 'unattributed',
+    observedAt: NOW,
+    periodType: 'seven-day',
+    usedFraction: 0.3,
+    resetAt: RESET,
+    source: 'codex-local-structured-event',
+    confidence: 'medium',
+    captureReason: 'refresh',
+    ...overrides,
+  };
+}
+
+test('stable fingerprints are machine-local and never retain the raw identity signal', () => {
+  const first = fingerprintForStableIdentity(SALT, 'claude', '/private/profile-a');
+  const repeated = fingerprintForStableIdentity(SALT, 'claude', '/private/profile-a');
+  const other = fingerprintForStableIdentity(SALT, 'claude', '/private/profile-b');
+
+  assert.equal(first, repeated);
+  assert.notEqual(first, other);
+  assert.equal(first.includes('/private/profile-a'), false);
+
+  const merged = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [capture({
+    provider: 'claude',
+    stableIdentitySignal: '/private/profile-a',
+    accountAttribution: 'profile-continuity',
+    source: 'claude-official-api',
+    sourceWindowId: 'private-provider-window-canary',
+  })], { salt: SALT, now: NOW });
+  const serialized = JSON.stringify(merged);
+  assert.equal(serialized.includes('/private/profile-a'), false);
+  assert.equal(serialized.includes('private-provider-window-canary'), false);
+  assert.equal(merged.observations[0].accountFingerprint, first);
+  assert.match(
+    merged.observations[0].providerWindowFingerprint ?? '',
+    /^pwin_[a-f0-9]{32}$/,
+  );
+});
+
+test('exact duplicate polls are idempotent while changed utilization is retained', () => {
+  const first = capture({ observedAt: NOW - HOUR, usedFraction: 0.2 });
+  let store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [first, first], {
+    salt: SALT,
+    now: NOW,
+  });
+  store = mergeQuotaCaptures(store, [
+    first,
+    capture({ observedAt: NOW, usedFraction: 0.3 }),
+  ], { salt: SALT, now: NOW });
+
+  assert.equal(store.observations.length, 2);
+  assert.deepEqual(store.observations.map((item) => item.usedFraction), [0.2, 0.3]);
+  assert.equal(new Set(store.observations.map((item) => item.windowId)).size, 1);
+});
+
+test('structured windows remain deterministic when observations arrive out of order', () => {
+  const early = capture({ observedAt: NOW - HOUR, usedFraction: 0.2 });
+  const late = capture({ observedAt: NOW, usedFraction: 0.3 });
+  const ordered = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [early, late], {
+    salt: SALT,
+    now: NOW,
+  });
+  let reversed = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [late], {
+    salt: SALT,
+    now: NOW,
+  });
+  reversed = mergeQuotaCaptures(reversed, [early], { salt: SALT, now: NOW });
+
+  assert.deepEqual(reversed, ordered);
+  assert.equal(new Set(ordered.observations.map((item) => item.windowId)).size, 1);
+});
+
+test('reset projections remain deterministic when the post-reset fact arrives first', () => {
+  const before = capture({
+    observedAt: NOW - HOUR,
+    resetAt: NOW + HOUR,
+    usedFraction: 0.9,
+    unattributedEpochSignal: 'before-reset-epoch',
+  });
+  const after = capture({
+    observedAt: NOW,
+    resetAt: NOW + 8 * HOUR,
+    usedFraction: 0.05,
+    unattributedEpochSignal: 'after-reset-epoch',
+  });
+  const ordered = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [before, after], {
+    salt: SALT,
+    now: NOW,
+  });
+  let reversed = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [after], {
+    salt: SALT,
+    now: NOW,
+  });
+  reversed = mergeQuotaCaptures(reversed, [before], { salt: SALT, now: NOW });
+
+  assert.deepEqual(reversed, ordered);
+  assert.deepEqual(deriveQuotaResetEvents(reversed), deriveQuotaResetEvents(ordered));
+  assert.equal(deriveQuotaResetEvents(reversed)[0].evidence, 'reset-at-change');
+});
+
+test('resetAt changes retain consecutive and same-day reset events', () => {
+  const firstReset = NOW + 2 * HOUR;
+  const secondReset = NOW + 8 * HOUR;
+  const thirdReset = NOW + 14 * HOUR;
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({ observedAt: NOW - HOUR, resetAt: firstReset, usedFraction: 0.92 }),
+    capture({ observedAt: NOW, resetAt: secondReset, usedFraction: 0.03 }),
+    capture({ observedAt: NOW + HOUR, resetAt: thirdReset, usedFraction: 0.02 }),
+  ], { salt: SALT, now: NOW + 2 * HOUR });
+
+  const resetEvents = deriveQuotaResetEvents(store);
+  assert.equal(resetEvents.length, 2);
+  assert.deepEqual(resetEvents.map((event) => event.evidence), [
+    'reset-at-change',
+    'reset-at-change',
+  ]);
+  assert.equal(new Set(store.observations.map((item) => item.windowId)).size, 3);
+  assert.equal(new Set(store.observations.map((item) => item.accountFingerprint)).size, 1);
+});
+
+test('unattributed reset epochs retain low-confidence account ambiguity at a reset boundary', () => {
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({
+      observedAt: NOW - HOUR,
+      resetAt: NOW + HOUR,
+      usedFraction: 0.91,
+      unattributedEpochSignal: 'first-unattributed-window',
+    }),
+    capture({
+      observedAt: NOW,
+      resetAt: NOW + 8 * HOUR,
+      usedFraction: 0.04,
+      unattributedEpochSignal: 'second-unattributed-window',
+    }),
+  ], { salt: SALT, now: NOW });
+
+  assert.equal(new Set(store.observations.map((item) => item.accountFingerprint)).size, 2);
+  assert.equal(new Set(store.observations.map((item) => item.windowId)).size, 2);
+  assert.equal(store.observations[1].flags.includes('account-ambiguous'), true);
+  const events = deriveQuotaResetEvents(store);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].evidence, 'reset-at-change');
+  assert.notEqual(events[0].previousAccountFingerprint, events[0].nextAccountFingerprint);
+});
+
+test('a legacy account-ambiguous flag survives a coherent reset boundary', () => {
+  const first = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [capture({
+    observedAt: NOW - HOUR,
+    resetAt: NOW + HOUR,
+    usedFraction: 0.91,
+    unattributedEpochSignal: 'legacy-first-window',
+  })], { salt: SALT, now: NOW });
+  const legacy = mergeQuotaCaptures(first, [capture({
+    observedAt: NOW,
+    resetAt: NOW + 8 * HOUR,
+    usedFraction: 0.04,
+    unattributedEpochSignal: 'legacy-second-window',
+    flags: ['account-ambiguous'],
+  })], { salt: SALT, now: NOW });
+
+  assert.equal(legacy.observations[1].captureReason, 'reset-at-change');
+  assert.equal(legacy.observations[1].flags.includes('account-ambiguous'), true);
+});
+
+test('an unattributed epoch change without reset evidence remains account ambiguous', () => {
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({
+      observedAt: NOW - HOUR,
+      usedFraction: 0.2,
+      unattributedEpochSignal: 'first-unattributed-epoch',
+    }),
+    capture({
+      observedAt: NOW,
+      usedFraction: 0.3,
+      unattributedEpochSignal: 'second-unattributed-epoch',
+    }),
+  ], { salt: SALT, now: NOW });
+
+  assert.equal(store.observations[1].captureReason, 'refresh');
+  assert.ok(store.observations[1].flags.includes('account-ambiguous'));
+});
+
+test('small percentage rollback is noise but a significant rollback creates a new window', () => {
+  const noisy = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({ observedAt: NOW - 2 * HOUR, usedFraction: 0.5 }),
+    capture({ observedAt: NOW - HOUR, usedFraction: 0.48 }),
+  ], { salt: SALT, now: NOW });
+  assert.equal(deriveQuotaResetEvents(noisy).length, 0);
+  assert.equal(new Set(noisy.observations.map((item) => item.windowId)).size, 1);
+
+  const reset = mergeQuotaCaptures(noisy, [
+    capture({ observedAt: NOW, usedFraction: 0.08 }),
+  ], { salt: SALT, now: NOW });
+  const resetEvents = deriveQuotaResetEvents(reset);
+  assert.equal(resetEvents.length, 1);
+  assert.equal(resetEvents[0].evidence, 'usage-drop');
+  assert.notEqual(reset.observations[1].windowId, reset.observations[2].windowId);
+});
+
+test('different stable account signals never share a fingerprint or window', () => {
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({
+      provider: 'claude',
+      stableIdentitySignal: '/profile/a',
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+    }),
+    capture({
+      provider: 'claude',
+      stableIdentitySignal: '/profile/b',
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+    }),
+  ], { salt: SALT, now: NOW });
+
+  assert.equal(new Set(store.observations.map((item) => item.accountFingerprint)).size, 2);
+  assert.equal(new Set(store.observations.map((item) => item.windowId)).size, 2);
+});
+
+test('an account epoch change alone does not invent an official reset event', () => {
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({
+      provider: 'claude',
+      stableIdentitySignal: '/profile/a',
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+      observedAt: NOW - HOUR,
+      usedFraction: 0.2,
+    }),
+    capture({
+      provider: 'claude',
+      stableIdentitySignal: '/profile/b',
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+      observedAt: NOW,
+      usedFraction: 0.3,
+    }),
+  ], { salt: SALT, now: NOW });
+
+  assert.equal(new Set(store.observations.map((item) => item.accountFingerprint)).size, 2);
+  assert.equal(new Set(store.observations.map((item) => item.windowId)).size, 2);
+  assert.ok(store.observations[1].flags.includes('account-ambiguous'));
+  assert.deepEqual(deriveQuotaResetEvents(store), []);
+});
+
+test('invalid and far-future captures are rejected without manufacturing values', () => {
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({ usedFraction: Number.NaN }),
+    capture({ usedFraction: 1.01 }),
+    capture({ observedAt: NOW + 2 * DAY }),
+    capture({ resetAt: null, usedFraction: 0 }),
+  ], { salt: SALT, now: NOW });
+
+  assert.equal(store.observations.length, 1);
+  assert.equal(store.observations[0].usedFraction, 0);
+  assert.equal(store.observations[0].remainingFraction, 1);
+  assert.equal(store.observations[0].resetAt, null);
+});
+
+test('weekly projection exposes only seven-day facts and retains attribution metadata', () => {
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [
+    capture({ periodType: 'five-hour', usedFraction: 0.4 }),
+    capture({ periodType: 'seven-day', usedFraction: 0.3 }),
+  ], { salt: SALT, now: NOW });
+  const rows = quotaStoreWeeklyObservations(store, 'codex');
+
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].usedPercent, 30);
+  assert.equal(rows[0].accountAttribution, 'unattributed');
+  assert.equal(rows[0].seriesKey, 'codex-epoch-1');
+  assert.notEqual(rows[0].seriesKey, store.observations[1].accountFingerprint);
+  assert.equal(rows[0].windowId, 'codex-window-1');
+  assert.doesNotMatch(JSON.stringify(rows), /(?:acct|anon|win|pwin)_[a-f0-9]{32}/);
+});
+
+test('retention and compaction preserve a live window first and last observation', () => {
+  const additions = Array.from({ length: 10 }, (_unused, index) => capture({
+    observedAt: NOW - (9 - index) * HOUR,
+    usedFraction: 0.1 + index * 0.01,
+  }));
+  const compacted = mergeQuotaCaptures(createEmptyQuotaObservationStore(), additions, {
+    salt: SALT,
+    now: NOW,
+    limitPerSeries: 4,
+  });
+  assert.equal(compacted.observations.length, 4);
+  assert.ok(compacted.observations.some((item) => item.observedAt === NOW - 9 * HOUR));
+  assert.ok(compacted.observations.some((item) => item.observedAt === NOW));
+
+  const oldNow = NOW - 190 * DAY;
+  const old = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [capture({
+    observedAt: oldNow,
+    resetAt: oldNow + DAY,
+  })], { salt: SALT, now: oldNow });
+  const retained = mergeQuotaCaptures(old, [], { salt: SALT, now: NOW });
+  assert.equal(retained.observations.length, 0);
+});
+
+test('quota store writes atomically and reloads a strict schema-2 document', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-store-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const file = path.join(root, 'quota-observations-v2.json');
+  const store = mergeQuotaCaptures(createEmptyQuotaObservationStore(), [capture()], {
+    salt: SALT,
+    now: NOW,
+  });
+  await saveQuotaObservationStoreAtomic(file, store);
+  const loaded = await loadQuotaObservationStore(file, { now: NOW });
+
+  assert.equal(loaded.disposition, 'valid');
+  assert.deepEqual(loaded.store, store);
+  const persisted = JSON.parse(await readFile(file, 'utf8')) as Record<string, unknown>;
+  assert.equal(persisted.schemaVersion, 2);
+  assert.deepEqual(Object.keys(persisted).sort(), [
+    'fingerprintAlgorithm',
+    'observations',
+    'schemaVersion',
+  ]);
+  assert.deepEqual(Object.keys((persisted.observations as Record<string, unknown>[])[0]).sort(), [
+    'accountAttribution',
+    'accountFingerprint',
+    'captureReason',
+    'confidence',
+    'flags',
+    'observedAt',
+    'periodType',
+    'provider',
+    'providerWindowFingerprint',
+    'remainingFraction',
+    'resetAt',
+    'schemaVersion',
+    'source',
+    'usedFraction',
+    'windowId',
+  ]);
+  assert.equal(root.startsWith(os.tmpdir()), true);
+});
+
+test('corrupt and future-schema files are quarantined without exposing their contents', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-quarantine-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  for (const [name, body] of [
+    ['corrupt', '{secret-cookie'],
+    ['future', JSON.stringify({ schemaVersion: 99, secret: 'token-canary' })],
+  ] as const) {
+    const file = path.join(root, `${name}.json`);
+    await writeFile(file, body, 'utf8');
+    const loaded = await loadQuotaObservationStore(file, { now: NOW });
+    assert.equal(loaded.disposition, 'quarantined');
+    assert.equal(loaded.store.observations.length, 0);
+    assert.ok(loaded.quarantinePath);
+    assert.equal(path.basename(loaded.quarantinePath ?? '').includes('secret'), false);
+    await access(loaded.quarantinePath as string);
+  }
+});
+
+test('repository serializes cross-instance concurrent appends without losing either observation', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-repository-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const file = path.join(root, 'quota-observations-v2.json');
+  const repository = new QuotaObservationRepository(
+    file,
+    SALT,
+    () => NOW,
+  );
+  const secondRepository = new QuotaObservationRepository(
+    file,
+    SALT,
+    () => NOW,
+  );
+  await Promise.all([
+    repository.append([capture({ observedAt: NOW - HOUR, usedFraction: 0.2 })]),
+    secondRepository.append([capture({ observedAt: NOW, usedFraction: 0.3 })]),
+  ]);
+  const loaded = await repository.load();
+
+  assert.equal(loaded.observations.length, 2);
+  assert.deepEqual(loaded.observations.map((item) => item.usedFraction), [0.2, 0.3]);
+});
+
+test('repository clears exact provider and account scopes without rewriting unrelated epochs', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-clear-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const file = path.join(root, 'quota-observations-v2.json');
+  const repository = new QuotaObservationRepository(file, SALT, () => NOW);
+  await repository.append([
+    capture({
+      provider: 'claude',
+      stableIdentitySignal: 'claude-profile-one',
+      unattributedEpochSignal: undefined,
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+      sourceWindowId: 'weekly',
+      observedAt: NOW - 2 * HOUR,
+    }),
+    capture({
+      provider: 'claude',
+      stableIdentitySignal: 'claude-profile-two',
+      unattributedEpochSignal: undefined,
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+      sourceWindowId: 'weekly',
+      observedAt: NOW - HOUR,
+    }),
+    capture({ observedAt: NOW }),
+  ]);
+  const seeded = await repository.load();
+  const firstClaude = seeded.observations.find((item) =>
+    item.provider === 'claude' && item.observedAt === NOW - 2 * HOUR,
+  );
+  assert.ok(firstClaude);
+
+  const afterEpochClear = await repository.clear({
+    provider: 'claude',
+    accountFingerprint: firstClaude.accountFingerprint,
+  });
+  assert.equal(afterEpochClear.observations.length, 2);
+  assert.equal(afterEpochClear.observations.some((item) =>
+    item.accountFingerprint === firstClaude.accountFingerprint,
+  ), false);
+  assert.equal(afterEpochClear.observations.some((item) => item.provider === 'codex'), true);
+
+  const afterProviderClear = await repository.clear({ provider: 'claude' });
+  assert.deepEqual(afterProviderClear.observations.map((item) => item.provider), ['codex']);
+
+  const afterAllClear = await repository.clear();
+  assert.deepEqual(afterAllClear.observations, []);
+  assert.deepEqual((await repository.load()).observations, []);
+});
+
+test('provider clear and a concurrent append preserve the new unrelated observation', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-clear-race-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const file = path.join(root, 'quota-observations-v2.json');
+  const first = new QuotaObservationRepository(file, SALT, () => NOW);
+  const second = new QuotaObservationRepository(file, SALT, () => NOW);
+  await first.append([capture({ observedAt: NOW - HOUR })]);
+
+  await Promise.all([
+    first.clear({ provider: 'codex' }),
+    second.append([capture({
+      provider: 'claude',
+      stableIdentitySignal: 'concurrent-profile',
+      unattributedEpochSignal: undefined,
+      accountAttribution: 'profile-continuity',
+      source: 'claude-official-api',
+      sourceWindowId: 'weekly',
+      observedAt: NOW,
+    })]),
+  ]);
+  const loaded = await first.load();
+  assert.equal(loaded.observations.some((item) => item.provider === 'codex'), false);
+  assert.equal(loaded.observations.some((item) => item.provider === 'claude'), true);
+});
+
+test('all-history clear purges exact auxiliaries under one lease and preserves later appends', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-clear-all-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const file = path.join(root, 'quota-observations-v2.json');
+  const first = new QuotaObservationRepository(file, SALT, () => NOW);
+  const second = new QuotaObservationRepository(file, SALT, () => NOW);
+  await first.append([capture({ observedAt: NOW - HOUR })]);
+  await writeFile(`${file}.quarantine-100-deadbeef`, 'quarantined-canary', 'utf8');
+  await writeFile(path.join(root, '.quota-observations-v2.json.200.abcdef123456.tmp'), 'temp-canary', 'utf8');
+
+  const cleared = await first.clear({});
+  assert.deepEqual(cleared.observations, []);
+  assert.deepEqual((await readdir(root)).sort(), ['quota-observations-v2.json']);
+
+  await second.append([capture({
+    provider: 'claude',
+    stableIdentitySignal: 'post-clear-profile',
+    unattributedEpochSignal: undefined,
+    accountAttribution: 'profile-continuity',
+    source: 'claude-official-api',
+    sourceWindowId: 'weekly',
+    observedAt: NOW,
+  })]);
+  const loaded = await first.load();
+  assert.deepEqual(loaded.observations.map((item) => item.provider), ['claude']);
+});
+
+test('scoped clear refuses to strand quarantined quota data', async () => {
+  const root = path.join(os.tmpdir(), `ccu-quota-scoped-quarantine-${process.pid}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(root, { recursive: true });
+  const file = path.join(root, 'quota-observations-v2.json');
+  const repository = new QuotaObservationRepository(file, SALT, () => NOW);
+  await repository.append([capture()]);
+  const quarantine = `${file}.quarantine-100-deadbeef`;
+  await writeFile(quarantine, 'quarantined-canary', 'utf8');
+
+  await assert.rejects(
+    () => repository.clear({ provider: 'codex' }),
+    QuotaObservationScopedClearBlockedError,
+  );
+  assert.equal((await repository.load()).observations.length, 1);
+  await access(quarantine);
+});
diff --git a/src/test/releaseAnnouncements.test.ts b/src/test/releaseAnnouncements.test.ts
index 0e8f13cd..a910a84c 100644
--- a/src/test/releaseAnnouncements.test.ts
+++ b/src/test/releaseAnnouncements.test.ts
@@ -6,14 +6,20 @@ import {
   latestAnnouncementVersion,
 } from '../releaseAnnouncements';
 
-const catalog = { '2.3.0': { version: '2.3.0' } };
+const catalog = {
+  '2.3.0': { version: '2.3.0' },
+  '2.3.1': { version: '2.3.1' },
+};
 
 test('upgrade resolves only the exact current version', () => {
   assert.deepEqual(
     announcementForUpgrade('2.3.0', '2.2.1', true, catalog),
     catalog['2.3.0'],
   );
-  assert.equal(announcementForUpgrade('2.3.1', '2.3.0', true, catalog), null);
+  assert.deepEqual(
+    announcementForUpgrade('2.3.1', '2.3.0', true, catalog),
+    catalog['2.3.1'],
+  );
   assert.equal(announcementForUpgrade('2.2.9', '2.1.0', true, catalog), null);
 });
 
@@ -25,7 +31,7 @@ test('fresh install, already-seen, and disabled announcements do not show', () =
 
 test('preview selects the greatest full semantic version', () => {
   assert.equal(
-    latestAnnouncementVersion({ '2.3.0': {}, '2.10.0': {}, '2.9.5': {} }),
+    latestAnnouncementVersion({ '2.3.0': {}, '2.3.1': {}, '2.10.0': {}, '2.9.5': {} }),
     '2.10.0',
   );
 });
diff --git a/src/test/repositoryPolicy.test.ts b/src/test/repositoryPolicy.test.ts
index 382e04a3..f0aa7f5c 100644
--- a/src/test/repositoryPolicy.test.ts
+++ b/src/test/repositoryPolicy.test.ts
@@ -11,6 +11,30 @@ function repoFile(relativePath: string): string {
   return readFileSync(resolve(REPO_ROOT, relativePath), 'utf8');
 }
 
+function privacySafePngChunkTypes(relativePath: string): string[] {
+  const bytes = readFileSync(resolve(REPO_ROOT, relativePath));
+  assert.deepEqual(
+    [...bytes.subarray(0, 8)],
+    [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+    `${relativePath} must contain PNG bytes, not only use a .png suffix`,
+  );
+  const types: string[] = [];
+  let offset = 8;
+  while (offset + 12 <= bytes.length) {
+    const payloadLength = bytes.readUInt32BE(offset);
+    const type = bytes.toString('ascii', offset + 4, offset + 8);
+    const nextOffset = offset + 12 + payloadLength;
+    assert.ok(nextOffset <= bytes.length, `${relativePath} has a truncated ${type} chunk`);
+    types.push(type);
+    offset = nextOffset;
+    if (type === 'IEND') {
+      break;
+    }
+  }
+  assert.equal(types[types.length - 1], 'IEND', `${relativePath} must end with IEND`);
+  return types;
+}
+
 type WorkflowStepValue = {
   readonly value: string;
   readonly line: number;
@@ -202,12 +226,14 @@ function functionDeclarations(file: ts.SourceFile): ReadonlyMap<string, ts.Funct
 
 function sanitizedDtoViolations(file: ts.SourceFile): string[] {
   const declarations = functionDeclarations(file);
-  const trustedLabelSanitizerBindings = new Set<string>();
+  const trustedSanitizerBindings = new Set<string>();
   for (const statement of file.statements) {
     if (
       !ts.isImportDeclaration(statement) ||
       !ts.isStringLiteral(statement.moduleSpecifier) ||
-      statement.moduleSpecifier.text !== './codexMetadataLabel' ||
+      !['./codexMetadataLabel', './codexQuotaHistory'].includes(
+        statement.moduleSpecifier.text,
+      ) ||
       !statement.importClause ||
       statement.importClause.isTypeOnly ||
       !statement.importClause.namedBindings ||
@@ -217,8 +243,14 @@ function sanitizedDtoViolations(file: ts.SourceFile): string[] {
     }
     for (const specifier of statement.importClause.namedBindings.elements) {
       const exportedName = specifier.propertyName?.text ?? specifier.name.text;
-      if (!specifier.isTypeOnly && exportedName === 'sanitizeCodexMetadataLabel') {
-        trustedLabelSanitizerBindings.add(specifier.name.text);
+      if (
+        !specifier.isTypeOnly &&
+        (
+          exportedName === 'sanitizeCodexMetadataLabel' ||
+          exportedName === 'sanitizeCodexQuotaHistory'
+        )
+      ) {
+        trustedSanitizerBindings.add(specifier.name.text);
       }
     }
   }
@@ -250,7 +282,7 @@ function sanitizedDtoViolations(file: ts.SourceFile): string[] {
     if (ts.isIdentifier(call.expression)) {
       return call.expression.text === 'resolveTimeZone' ||
         call.expression.text === 'dayKeyInZone' ||
-        (trustedLabelSanitizerBindings.has(call.expression.text) &&
+        (trustedSanitizerBindings.has(call.expression.text) &&
           !shadowedBindings.has(call.expression.text));
     }
     if (!ts.isPropertyAccessExpression(call.expression)) {
@@ -1415,6 +1447,67 @@ test('all seven README editions explain Codex Beta in their own language', () =>
   }
 });
 
+test('v2.3.1 README editions share release evidence and local-data boundaries', () => {
+  const readmes = [
+    'README.md',
+    'README-en.md',
+    'README-zh-CN.md',
+    'README-zh-TW.md',
+    'README-ja.md',
+    'README-ko.md',
+    'README-id.md',
+  ];
+  const releaseImages = [
+    'images/v2.3.1/claude-today-zh-CN-dark.png',
+    'images/v2.3.1/codex-overview-zh-CN-dark.png',
+    'images/v2.3.1/codex-weekly-estimate-en-dark.png',
+    'images/v2.3.1/compare-heatmap-en-light.png',
+  ];
+  for (const image of releaseImages) {
+    assert.ok(
+      existsSync(resolve(REPO_ROOT, image)),
+      `release evidence is missing ${image}`,
+    );
+    const chunkTypes = privacySafePngChunkTypes(image);
+    for (const metadataChunk of ['eXIf', 'iTXt', 'tEXt', 'zTXt']) {
+      assert.equal(
+        chunkTypes.includes(metadataChunk),
+        false,
+        `${image} retains unnecessary ${metadataChunk} metadata`,
+      );
+    }
+  }
+  for (const readme of readmes) {
+    const body = repoFile(readme);
+    assert.match(body, /2\.3\.1/, `${readme} is missing the release section`);
+    assert.match(body, /LOCAL-DATA(?:\.zh-CN)?\.md/, `${readme} is missing the local-data inventory`);
+    for (const image of releaseImages) {
+      assert.ok(body.includes(image), `${readme} is missing ${image}`);
+    }
+    assert.doesNotMatch(
+      body,
+      /local candidate|本地候选|本機候選|ローカル候補|로컬 후보|Kandidat lokal/i,
+      `${readme} still labels v2.3.1 as a local candidate`,
+    );
+  }
+
+  const packageJson = JSON.parse(repoFile('package.json')) as { version: string };
+  const packageLock = JSON.parse(repoFile('package-lock.json')) as {
+    version: string;
+    packages: Record<string, { version?: string }>;
+  };
+  assert.equal(
+    packageJson.version,
+    '2.1.1',
+    'source metadata stays unstamped until the release-tag publish workflow',
+  );
+  assert.equal(packageLock.version, packageJson.version);
+  assert.equal(packageLock.packages['']?.version, packageJson.version);
+  assert.match(repoFile('.github/workflows/publish.yml'), /npm version "\$VER"/);
+  assert.match(repoFile('LOCAL-DATA.md'), /OAuth access or refresh tokens/);
+  assert.match(repoFile('LOCAL-DATA.zh-CN.md'), /OAuth access\/refresh token/);
+});
+
 test('Marketplace metadata presents Claude and Codex local usage support', () => {
   const packageJson = JSON.parse(repoFile('package.json')) as {
     description: string;
@@ -1450,8 +1543,9 @@ test('changelog records the V2.2.2 energy patch after the released V2.2.1 baseli
   assert.doesNotMatch(changelog, /^## \[2\.2\.[01]\] — Unreleased$/m);
 });
 
-test('changelog records the v2.3.0 candidate', () => {
+test('changelog records the v2.3.0 and v2.3.1 candidates', () => {
   const changelog = repoFile('CHANGELOG.md');
+  assert.match(changelog, /^## \[2\.3\.1\] — Unreleased$/m);
   assert.match(changelog, /^## \[2\.3\.0\] — Unreleased$/m);
 });
 
@@ -1460,6 +1554,7 @@ test('release announcements are exact-version and user-disableable', () => {
   const settings = repoFile('src/settings.ts');
 
   assert.match(extension, /'2\.3\.0'/);
+  assert.match(extension, /'2\.3\.1'/);
   assert.doesNotMatch(extension, /'2\.2'\s*:/);
   assert.match(settings, /key:\s*'releaseAnnouncements'/);
   assert.match(settings, /default:\s*true/);
diff --git a/src/test/resourceOwnership.test.ts b/src/test/resourceOwnership.test.ts
new file mode 100644
index 00000000..acd2a376
--- /dev/null
+++ b/src/test/resourceOwnership.test.ts
@@ -0,0 +1,160 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import {
+  ResourceOwnershipRegistry,
+  type ResourceDescriptor,
+} from '../resourceOwnership';
+
+const descriptors: ResourceDescriptor[] = [
+  {
+    kind: 'timer',
+    capability: 'refresh',
+    scope: 'extension',
+    creator: 'extension',
+    stopConditions: ['window-blur', 'feature-disabled', 'extension-dispose'],
+    boundedException: 'none',
+  },
+  {
+    kind: 'watcher',
+    capability: 'codex-index',
+    scope: 'codex',
+    creator: 'extension',
+    stopConditions: ['window-blur', 'feature-disabled', 'settings-change', 'extension-dispose'],
+    boundedException: 'none',
+  },
+  {
+    kind: 'worker',
+    capability: 'codex-index',
+    scope: 'codex',
+    creator: 'codex-index-client',
+    stopConditions: ['completed', 'cancelled', 'feature-disabled', 'extension-dispose', 'user-pause'],
+    boundedException: 'none',
+  },
+  {
+    kind: 'network',
+    capability: 'advice-personalization',
+    scope: 'advice',
+    creator: 'advice-runtime',
+    stopConditions: ['settled', 'cancelled', 'feature-disabled', 'extension-dispose'],
+    boundedException: 'none',
+  },
+  {
+    kind: 'backfill',
+    capability: 'codex-history',
+    scope: 'codex',
+    creator: 'refresh-coordinator',
+    stopConditions: ['completed', 'cancelled', 'feature-disabled', 'extension-dispose', 'user-pause'],
+    boundedException: 'first-codex-history',
+  },
+];
+
+test('registry exposes fixed ownership metadata for every active resource kind', async () => {
+  const registry = new ResourceOwnershipRegistry();
+  const leases = descriptors.map((descriptor) => registry.register(descriptor));
+  const snapshot = registry.snapshotForTests();
+
+  assert.equal(snapshot.activeCount, 5);
+  assert.deepEqual(snapshot.byKind, {
+    timer: 1,
+    watcher: 1,
+    worker: 1,
+    network: 1,
+    backfill: 1,
+  });
+  assert.deepEqual(snapshot.active, descriptors);
+  assert.equal(Object.isFrozen(snapshot), true);
+  assert.equal(Object.isFrozen(snapshot.byKind), true);
+  assert.equal(Object.isFrozen(snapshot.active), true);
+  assert.equal(Object.isFrozen(snapshot.active[0]), true);
+  assert.equal(Object.isFrozen(snapshot.active[0].stopConditions), true);
+
+  let finishWorker!: () => void;
+  const workerStopped = leases[2].stop('completed', () => new Promise<void>((resolve) => {
+    finishWorker = resolve;
+  }));
+  await Promise.resolve();
+  assert.equal(registry.snapshotForTests().activeCount, 5, 'ownership remains active until terminate settles');
+  finishWorker();
+  assert.equal(await workerStopped, true);
+  assert.equal(registry.snapshotForTests().activeCount, 4);
+
+  await Promise.all([
+    leases[0].stop('extension-dispose', () => undefined),
+    leases[1].stop('extension-dispose', () => undefined),
+    leases[3].stop('settled', () => undefined),
+    leases[4].stop('completed', () => undefined),
+  ]);
+  assert.equal(registry.snapshotForTests().activeCount, 0);
+});
+
+test('a lease is idempotent and invokes the actual stopper once', async () => {
+  const registry = new ResourceOwnershipRegistry();
+  const lease = registry.register(descriptors[2]);
+  let stopCalls = 0;
+  let finish!: () => void;
+  const stopper = (): Promise<void> => {
+    stopCalls += 1;
+    return new Promise<void>((resolve) => { finish = resolve; });
+  };
+
+  const first = lease.stop('completed', stopper);
+  const concurrent = lease.stop('completed', stopper);
+  await Promise.resolve();
+  assert.equal(stopCalls, 1);
+  assert.equal(lease.active, true);
+  finish();
+  assert.equal(await first, true);
+  assert.equal(await concurrent, true);
+  assert.equal(lease.active, false);
+  assert.equal(await lease.stop('completed', stopper), false);
+  assert.equal(stopCalls, 1);
+});
+
+test('failed destruction keeps ownership active and permits an explicit retry', async () => {
+  const registry = new ResourceOwnershipRegistry();
+  const lease = registry.register(descriptors[3]);
+
+  await assert.rejects(
+    lease.stop('settled', async () => { throw new Error('abort failed'); }),
+    /abort failed/,
+  );
+  assert.equal(lease.active, true);
+  assert.equal(registry.snapshotForTests().byKind.network, 1);
+
+  assert.equal(await lease.stop('settled', () => undefined), true);
+  assert.equal(lease.active, false);
+  assert.equal(registry.snapshotForTests().byKind.network, 0);
+});
+
+test('registry rejects free-form, extra, duplicate, and invalid exception metadata', async () => {
+  const registry = new ResourceOwnershipRegistry();
+  const base = descriptors[0];
+
+  assert.throws(
+    () => registry.register({ ...base, capability: 'read-private-log' } as unknown as ResourceDescriptor),
+    /capability/,
+  );
+  assert.throws(
+    () => registry.register({ ...base, path: '/Users/alice/private.jsonl' } as ResourceDescriptor),
+    /field|metadata/i,
+  );
+  assert.throws(
+    () => registry.register({ ...base, stopConditions: ['window-blur', 'window-blur'] }),
+    /duplicate/i,
+  );
+  assert.throws(
+    () => registry.register({ ...base, boundedException: 'first-codex-history' }),
+    /bounded exception/i,
+  );
+
+  const lease = registry.register(base);
+  let stopCalls = 0;
+  await assert.rejects(
+    lease.stop('completed', () => { stopCalls += 1; }),
+    /stop condition/i,
+  );
+  assert.equal(stopCalls, 0);
+  assert.equal(lease.active, true);
+  await lease.stop('extension-dispose', () => { stopCalls += 1; });
+  assert.equal(stopCalls, 1);
+});
diff --git a/src/test/resourceOwnershipIntegration.test.ts b/src/test/resourceOwnershipIntegration.test.ts
new file mode 100644
index 00000000..efa5ab11
--- /dev/null
+++ b/src/test/resourceOwnershipIntegration.test.ts
@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+
+const root = path.resolve(__dirname, '..', '..');
+
+test('production host registers timer, watcher, worker, network, and backfill ownership', () => {
+  const source = readFileSync(path.join(root, 'src', 'extension.ts'), 'utf8');
+  for (const kind of ['timer', 'watcher', 'worker', 'network', 'backfill']) {
+    assert.match(source, new RegExp(`kind:\\s*'${kind}'`));
+  }
+  for (const actualStop of [
+    'clearTimeout(timer)',
+    'watcher.close()',
+    'controller.abort()',
+    'this.codexProvider.cancel()',
+    'this.codexProvider.dispose()',
+  ]) {
+    assert.ok(source.includes(actualStop), `missing actual stop: ${actualStop}`);
+  }
+  assert.match(source, /onAiSurfaceClosed\s*=.*cancelAdviceNetworks/s);
+  assert.match(source, /onAdviceConsentWithdrawn\s*=\s*\(\)\s*=>\s*this\.cancelAdviceNetworks\('cancelled', 'advice'\)/);
+  assert.match(source, /scheduleFirstBackfillBlurDeadline/);
+  assert.match(source, /CODEX_FIRST_BACKFILL_BLUR_DEADLINE_MS/);
+  assert.match(source, /stopFirstBackfillBlurDeadline\('extension-dispose'\)/);
+});
+
+test('background eligibility is persisted and controls historical work only', () => {
+  const extension = readFileSync(path.join(root, 'src', 'extension.ts'), 'utf8');
+  const protocol = readFileSync(
+    path.join(root, 'src', 'providers', 'codex', 'codexWorkerProtocol.ts'),
+    'utf8',
+  );
+  const index = readFileSync(
+    path.join(root, 'src', 'providers', 'codex', 'codexIndex.ts'),
+    'utf8',
+  );
+  assert.match(extension, /ccu\.codex\.backgroundWork\.v1/);
+  assert.match(extension, /beginBackgroundWork/);
+  assert.match(extension, /recordBackgroundWorkProgress/);
+  assert.match(extension, /recordBackgroundWorkFailure/);
+  assert.match(extension, /historicalAttempt/);
+  assert.match(protocol, /allowHistoricalBackfill\?: boolean/);
+  assert.match(index, /allowHistoricalBackfill \? manifest\.files : \[\]/);
+  assert.match(index, /indexGeneration/);
+  assert.match(extension, /codexIndexGeneration/);
+});
+
+test('Codex worker is terminal after every result instead of remaining idle', () => {
+  const source = readFileSync(
+    path.join(root, 'src', 'providers', 'codex', 'codexIndexClient.ts'),
+    'utf8',
+  );
+  assert.match(source, /terminateSettledWorker/);
+  assert.match(source, /Promise\.resolve\(worker\.terminate\(\)\)/);
+  assert.match(source, /await termination/);
+  assert.match(source, /terminateSettledWorker\(\)[\s\S]*active\.resolve/);
+});
diff --git a/src/test/settingsPrivacy.test.ts b/src/test/settingsPrivacy.test.ts
new file mode 100644
index 00000000..f3285b7c
--- /dev/null
+++ b/src/test/settingsPrivacy.test.ts
@@ -0,0 +1,445 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+type SettingsModule = typeof import('../settings');
+
+interface FakeConfiguration {
+  values: {
+    global?: unknown;
+    workspace?: unknown;
+    folder?: unknown;
+  };
+  updates: Array<{ key: string; value: unknown; target: number }>;
+  get<T>(key: string, fallback: T): T;
+  inspect<T>(key: string): {
+    globalValue?: T;
+    workspaceValue?: T;
+    workspaceFolderValue?: T;
+  };
+  update(key: string, value: unknown, target: number): Promise<void>;
+}
+
+function fakeConfiguration(initial: FakeConfiguration['values'] = {}): FakeConfiguration {
+  const config: FakeConfiguration = {
+    values: { ...initial },
+    updates: [],
+    get<T>(_key: string, fallback: T): T {
+      return (config.values.folder ?? config.values.workspace ?? config.values.global ?? fallback) as T;
+    },
+    inspect<T>(_key: string) {
+      return {
+        globalValue: config.values.global as T | undefined,
+        workspaceValue: config.values.workspace as T | undefined,
+        workspaceFolderValue: config.values.folder as T | undefined,
+      };
+    },
+    async update(key: string, value: unknown, target: number): Promise<void> {
+      config.updates.push({ key, value, target });
+      const slot = target === 3 ? 'folder' : target === 2 ? 'workspace' : 'global';
+      config.values[slot] = value;
+    },
+  };
+  return config;
+}
+
+let activeConfiguration = fakeConfiguration();
+let activeWorkspaceFolders: Array<{ uri: string }> = [];
+let activeFolderConfigurations = new Map<string, FakeConfiguration>();
+
+function loadSettingsModule(): SettingsModule {
+  const moduleLoader = require('node:module') as {
+    _load: (request: string, parent: unknown, isMain: boolean) => unknown;
+  };
+  const originalLoad = moduleLoader._load;
+  moduleLoader._load = function (request, parent, isMain): unknown {
+    if (request === 'vscode') {
+      return {
+        ConfigurationTarget: { Global: 1, Workspace: 2, WorkspaceFolder: 3 },
+        workspace: {
+          get workspaceFolders() { return activeWorkspaceFolders; },
+          getConfiguration: (_section: string, resource?: string) =>
+            resource ? activeFolderConfigurations.get(resource) ?? activeConfiguration : activeConfiguration,
+        },
+      };
+    }
+    return Reflect.apply(originalLoad, this, [request, parent, isMain]);
+  };
+  try {
+    return require('../settings') as SettingsModule;
+  } finally {
+    moduleLoader._load = originalLoad;
+  }
+}
+
+const { SettingsStore } = loadSettingsModule();
+
+function fakeContext(options: {
+  state?: Map<string, unknown>;
+  secrets?: Map<string, string>;
+  failSecretStore?: boolean;
+} = {}): any {
+  const state = options.state ?? new Map<string, unknown>();
+  const secrets = options.secrets ?? new Map<string, string>();
+  const secretStores: Array<{ key: string; value: string }> = [];
+  const secretDeletes: string[] = [];
+  return {
+    globalState: {
+      get: <T>(key: string, fallback?: T): T | undefined =>
+        (state.has(key) ? state.get(key) : fallback) as T | undefined,
+      update: async (key: string, value: unknown): Promise<void> => {
+        if (value === undefined) state.delete(key);
+        else state.set(key, value);
+      },
+    },
+    secrets: {
+      get: async (key: string): Promise<string | undefined> => secrets.get(key),
+      store: async (key: string, value: string): Promise<void> => {
+        if (options.failSecretStore) throw new Error('synthetic secret-store failure');
+        secretStores.push({ key, value });
+        secrets.set(key, value);
+      },
+      delete: async (key: string): Promise<void> => {
+        secretDeletes.push(key);
+        secrets.delete(key);
+      },
+    },
+    _state: state,
+    _secrets: secrets,
+    _secretStores: secretStores,
+    _secretDeletes: secretDeletes,
+  };
+}
+
+test('legacy plaintext BYOK migrates to SecretStorage and never enters a settings snapshot', async () => {
+  const canary = 'sk-v2.3.1-privacy-canary';
+  activeConfiguration = fakeConfiguration();
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext({
+    state: new Map([['ccu.setting.advice.apiKey', canary]]),
+  });
+  const store = new SettingsStore(context);
+
+  await store.initializeSecrets();
+
+  assert.equal(context._secrets.get('claudeCodeUsage.secret.advice.apiKey'), canary);
+  assert.equal(context._state.has('ccu.setting.advice.apiKey'), false);
+  assert.equal(activeConfiguration.updates.length, 0);
+  assert.equal(store.get('advice.apiKey'), canary, 'the extension host can still use the key');
+  const apiKeyView = store.snapshot().find((entry) => entry.key === 'advice.apiKey');
+  assert.equal(apiKeyView?.configured, true);
+  assert.equal(apiKeyView?.value, '');
+  assert.doesNotMatch(JSON.stringify(store.snapshot()), /v2\.3\.1-privacy-canary/);
+});
+
+test('legacy settings.json secrets fail closed because the key is no longer registered', async () => {
+  activeConfiguration = fakeConfiguration({
+    global: 'sk-global-canary',
+    workspace: 'sk-workspace-canary',
+  });
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext();
+  const store = new SettingsStore(context);
+
+  await assert.rejects(
+    () => store.initializeSecrets(),
+    /settings-secret-migration:workspace-secret-requires-manual-migration/,
+  );
+
+  assert.equal(context._secrets.size, 0);
+  assert.equal(activeConfiguration.values.global, 'sk-global-canary');
+  assert.equal(activeConfiguration.values.workspace, 'sk-workspace-canary');
+  assert.equal(activeConfiguration.updates.length, 0);
+});
+
+test('workspace-only secrets require explicit migration and every open folder is inspected', async () => {
+  activeConfiguration = fakeConfiguration();
+  const first = fakeConfiguration({ folder: 'sk-folder-one' });
+  const second = fakeConfiguration({ folder: 'sk-folder-two' });
+  activeWorkspaceFolders = [{ uri: 'folder-a' }, { uri: 'folder-b' }];
+  activeFolderConfigurations = new Map([
+    ['folder-a', first],
+    ['folder-b', second],
+  ]);
+  const context = fakeContext();
+  const store = new SettingsStore(context);
+
+  await assert.rejects(
+    () => store.initializeSecrets(),
+    /settings-secret-migration:workspace-secret-requires-manual-migration/,
+  );
+  assert.equal(first.values.folder, 'sk-folder-one');
+  assert.equal(second.values.folder, 'sk-folder-two');
+  assert.equal(context._secrets.size, 0);
+});
+
+test('failed SecretStorage migration leaves legacy plaintext in place for recovery', async () => {
+  const canary = 'sk-recovery-canary';
+  activeConfiguration = fakeConfiguration();
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext({
+    state: new Map([['ccu.setting.advice.apiKey', canary]]),
+    failSecretStore: true,
+  });
+  const store = new SettingsStore(context);
+
+  await assert.rejects(
+    () => store.initializeSecrets(),
+    (error: unknown) => {
+      assert.match(String(error), /settings-secret-migration:secret-storage-failed/);
+      assert.doesNotMatch(String(error), /recovery-canary|synthetic secret-store failure/);
+      return true;
+    },
+  );
+  assert.equal(context._state.get('ccu.setting.advice.apiKey'), canary);
+  assert.equal(activeConfiguration.values.global, undefined);
+});
+
+test('BYOK set and reset use only SecretStorage', async () => {
+  activeConfiguration = fakeConfiguration();
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext();
+  const store = new SettingsStore(context);
+
+  await store.set('advice.apiKey', '  sk-runtime-canary  ');
+  assert.equal(store.get('advice.apiKey'), 'sk-runtime-canary');
+  assert.equal(context._secrets.get('claudeCodeUsage.secret.advice.apiKey'), 'sk-runtime-canary');
+  assert.equal(context._state.size, 0);
+  assert.equal(activeConfiguration.updates.length, 0);
+
+  await store.reset('advice.apiKey');
+  assert.equal(store.get('advice.apiKey'), '');
+  assert.equal(context._secrets.size, 0);
+});
+
+test('clear-all settings uses the exact catalog across current scopes and preserves unrelated state', async () => {
+  activeConfiguration = fakeConfiguration();
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext({
+    state: new Map<string, unknown>([
+      ['ccu.setting.showCost', true],
+      ['ccu.setting.pauseDashboardRefresh', true],
+      ['ccu.setting.fileWatching', true],
+      ['ccu.setting.advice.backend', 'subscription'],
+      ['ccu.setting.advice.subscriptionModel', 'legacy-model'],
+      ['ccu.unrelated.canary', 'preserve'],
+    ]),
+    secrets: new Map([['claudeCodeUsage.secret.advice.apiKey', 'secret-canary']]),
+  });
+  const store = new SettingsStore(context);
+
+  await store.resetAllOwnedData();
+
+  assert.equal(context._state.has('ccu.setting.showCost'), false);
+  assert.equal(context._state.has('ccu.setting.pauseDashboardRefresh'), false);
+  assert.equal(context._state.has('ccu.setting.fileWatching'), false);
+  assert.equal(context._state.has('ccu.setting.advice.backend'), false);
+  assert.equal(context._state.has('ccu.setting.advice.subscriptionModel'), false);
+  assert.equal(context._state.get('ccu.unrelated.canary'), 'preserve');
+  assert.equal(context._secrets.size, 0);
+  assert.ok(context._secretDeletes.includes('claudeCodeUsage.secret.advice.apiKey'));
+  assert.equal(activeConfiguration.updates.length, 0);
+});
+
+test('BYOK and sharing resets clear only their exact owned stores and visible scopes', async () => {
+  activeConfiguration = fakeConfiguration();
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext({
+    state: new Map<string, unknown>([
+      ['ccu.setting.advice.apiKey', 'legacy-state-canary'],
+      ['ccu.setting.showHeatmap', true],
+      ['ccu.setting.enableShareCard', true],
+      ['ccu.setting.showCost', true],
+    ]),
+    secrets: new Map([['claudeCodeUsage.secret.advice.apiKey', 'secret-canary']]),
+  });
+  const store = new SettingsStore(context);
+
+  await store.clearByokOwnedData();
+  assert.equal(context._secrets.has('claudeCodeUsage.secret.advice.apiKey'), false);
+  assert.equal(context._state.has('ccu.setting.advice.apiKey'), false);
+  assert.equal(context._state.get('ccu.setting.showHeatmap'), true);
+
+  await store.resetSharingOwnedData();
+  assert.equal(context._state.has('ccu.setting.showHeatmap'), false);
+  assert.equal(context._state.has('ccu.setting.enableShareCard'), false);
+  assert.equal(context._state.get('ccu.setting.showCost'), true);
+  assert.equal(activeConfiguration.updates.length, 0);
+});
+
+test('unregistered legacy configuration blocks a clear before state or SecretStorage changes', async () => {
+  activeConfiguration = fakeConfiguration({ global: 'legacy-plaintext-canary' });
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext({
+    state: new Map([['ccu.setting.advice.apiKey', 'legacy-state-canary']]),
+    secrets: new Map([['claudeCodeUsage.secret.advice.apiKey', 'secret-canary']]),
+  });
+  const store = new SettingsStore(context);
+
+  await assert.rejects(
+    () => store.clearByokOwnedData(),
+    /settings-local-data-clear:legacy-configuration-requires-manual-removal/,
+  );
+  assert.equal(context._state.get('ccu.setting.advice.apiKey'), 'legacy-state-canary');
+  assert.equal(context._secrets.get('claudeCodeUsage.secret.advice.apiKey'), 'secret-canary');
+  assert.equal(activeConfiguration.updates.length, 0);
+});
+
+test('registered configuration clear updates only explicit valid scopes', async () => {
+  activeConfiguration = fakeConfiguration({
+    global: '/global/claude',
+    workspace: '/workspace/claude',
+  });
+  const first = fakeConfiguration({ folder: '/folder/claude' });
+  activeWorkspaceFolders = [{ uri: 'folder-a' }];
+  activeFolderConfigurations = new Map([['folder-a', first]]);
+  const store = new SettingsStore(fakeContext());
+
+  await store.resetOwnedSettings(['dataDirectory']);
+
+  assert.deepEqual(activeConfiguration.updates.map((entry) => entry.target).sort(), [1, 2]);
+  assert.deepEqual(first.updates.map((entry) => entry.target), [3]);
+  assert.ok([...activeConfiguration.updates, ...first.updates].every((entry) =>
+    entry.key === 'dataDirectory' && entry.value === undefined,
+  ));
+});
+
+test('registered global configuration clear does not write a workspace target in an empty window', async () => {
+  activeConfiguration = fakeConfiguration({ global: '/global/claude' });
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const store = new SettingsStore(fakeContext());
+
+  await store.resetOwnedSettings(['dataDirectory']);
+
+  assert.deepEqual(activeConfiguration.updates, [{
+    key: 'dataDirectory',
+    value: undefined,
+    target: 1,
+  }]);
+});
+
+test('repeat activation is idempotent and secret metadata is independent of key length', async () => {
+  activeConfiguration = fakeConfiguration();
+  activeWorkspaceFolders = [];
+  activeFolderConfigurations = new Map();
+  const context = fakeContext({
+    secrets: new Map([['claudeCodeUsage.secret.advice.apiKey', 'sk-short']]),
+  });
+  const store = new SettingsStore(context);
+
+  await store.initializeSecrets();
+  const shortView = store.snapshot().find((entry) => entry.key === 'advice.apiKey');
+  await store.initializeSecrets();
+  await store.set('advice.apiKey', 'sk-a-much-longer-secret-value');
+  const longView = store.snapshot().find((entry) => entry.key === 'advice.apiKey');
+
+  assert.deepEqual(shortView, longView);
+  assert.deepEqual(shortView && { value: shortView.value, configured: shortView.configured }, {
+    value: '',
+    configured: true,
+  });
+  assert.equal(context._secretStores.length, 1, 'only the explicit user edit writes SecretStorage');
+  assert.equal(activeConfiguration.updates.length, 0);
+});
+
+test('the extension manifest no longer contributes a plaintext API-key setting', () => {
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8'),
+  ) as any;
+  assert.equal(
+    Object.prototype.hasOwnProperty.call(
+      manifest.contributes.configuration.properties,
+      'claudeCodeUsage.advice.apiKey',
+    ),
+    false,
+  );
+});
+
+test('activation reports a fixed localized migration failure without echoing provider errors', () => {
+  const source = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'extension.ts'), 'utf8');
+  assert.match(source, /showErrorMessage\([\s\S]*secretMigrationWorkspace[\s\S]*secretMigrationFailed/);
+  assert.doesNotMatch(source, /secretMigrationFailed[^;]*\.message/);
+});
+
+test('the tracked bilingual data contract covers quota, retention, clearing, and remote boundaries', () => {
+  const root = path.join(__dirname, '..', '..');
+  const documents = [
+    'docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.md',
+    'docs/superpowers/specs/2026-09-02-v2.3.1-local-data-contract.zh-CN.md',
+  ].map((relative) => fs.readFileSync(path.join(root, relative), 'utf8'));
+
+  for (const document of documents) {
+    for (const required of [
+      'schemaVersion',
+      'provider',
+      'accountFingerprint',
+      'observedAt',
+      'periodType',
+      'usedFraction',
+      'remainingFraction',
+      'resetAt',
+      'source',
+      'windowId',
+      'confidence',
+      'SecretStorage',
+      '180',
+      '512',
+      'ccu.heatmapRepo',
+      'ccu.heatmapPath',
+      'ccu.combinedHeatmap.title',
+      'ccu.combinedHeatmap.range',
+      'ccu.combinedHeatmap.privacyPreview',
+      'ccu.combinedHeatmap.intensityMode',
+      'ccu.combinedHeatmap.palette',
+      'ccu.combinedHeatmap.customAccent',
+      'Codex processed',
+      'public_repo',
+    ]) {
+      assert.match(document, new RegExp(required.replace('.', '\\.')));
+    }
+    assert.match(document, /OAuth token/i);
+    assert.match(document, /cookie/i);
+    assert.match(document, /API key/i);
+    assert.match(document, /clear|清除/i);
+    assert.match(document, /remote|network|远程|网络/i);
+  }
+});
+
+test('GitHub heatmap publication is public-only, exact-target confirmed, and persists destinations after success', () => {
+  const source = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'extension.ts'), 'utf8');
+  const start = source.indexOf('private async publishHeatmapToGitHub');
+  const end = source.indexOf('/** Export a one-page usage share card', start);
+  const publish = source.slice(start, end);
+
+  assert.ok(start >= 0 && end > start);
+  assert.match(publish, /GITHUB_PUBLIC_REPO_SCOPE/);
+  assert.doesNotMatch(publish, /\['repo'\]/);
+  assert.match(publish, /probePublicGitHubPublishTarget/);
+  assert.match(publish, /githubPublishConfirmationDetail/);
+  assert.match(publish, /Confirm the exact GitHub write/);
+  const write = publish.indexOf('publishPublicGitHubFile');
+  const persistRepo = publish.indexOf("globalState.update('ccu.heatmapRepo'");
+  const persistPath = publish.indexOf("globalState.update('ccu.heatmapPath'");
+  assert.ok(write >= 0 && persistRepo > write && persistPath > write);
+});
+
+test('reset sharing preferences clears only the remembered GitHub destination', () => {
+  const source = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'webview.ts'), 'utf8');
+  const start = source.indexOf("case 'resetCombinedHeatmapPreferences'");
+  const end = source.indexOf("case 'buildShareCard'", start);
+  const reset = source.slice(start, end);
+
+  assert.ok(start >= 0 && end > start);
+  assert.match(reset, /globalState\.update\('ccu\.heatmapRepo', undefined\)/);
+  assert.match(reset, /globalState\.update\('ccu\.heatmapPath', undefined\)/);
+  assert.doesNotMatch(reset, /quota|index|secret|token|cookie|log/i);
+});
diff --git a/src/test/statusBarThresholds.test.ts b/src/test/statusBarThresholds.test.ts
index a4d1aec1..2c2c2cfe 100644
--- a/src/test/statusBarThresholds.test.ts
+++ b/src/test/statusBarThresholds.test.ts
@@ -20,6 +20,17 @@ class RecordingThemeColor {
   constructor(public readonly id: string) {}
 }
 
+class RecordingMarkdownString {
+  value = '';
+  supportThemeIcons = false;
+  supportHtml = false;
+
+  appendMarkdown(value: string): this {
+    this.value += value;
+    return this;
+  }
+}
+
 function loadStatusBarModule(): StatusBarModule {
   const moduleLoader = require('node:module') as {
     _load: (request: string, parent: unknown, isMain: boolean) => unknown;
@@ -33,6 +44,9 @@ function loadStatusBarModule(): StatusBarModule {
       if (property === 'ThemeColor') {
         return RecordingThemeColor;
       }
+      if (property === 'MarkdownString') {
+        return RecordingMarkdownString;
+      }
       return vscodeStub;
     },
     apply: () => vscodeStub,
@@ -110,3 +124,111 @@ test('item background follows the same level as the bar', () => {
   assert.equal(bg(80, CONTEXT_FILL_THRESHOLDS), 'statusBarItem.warningBackground');
   assert.equal(bg(95, CONTEXT_FILL_THRESHOLDS), 'statusBarItem.errorBackground');
 });
+
+test('Codex quota tooltip reuses the Claude table, progress bar, and line-broken notes', () => {
+  const now = Date.parse('2026-09-02T12:00:00.000Z');
+  const tooltip = bareStatusBar().createCodexQuotaTooltip({
+    provider: 'codex',
+    observedAt: now - 60_000,
+    source: 'local-log',
+    confidence: 'last-observed',
+    windows: [{
+      label: 'primary',
+      usedPercent: 36,
+      windowMinutes: 7 * 24 * 60,
+      resetsAt: now + 5 * 24 * 60 * 60 * 1000,
+    }],
+  }, now) as RecordingMarkdownString;
+
+  assert.match(tooltip.value, /<table>/);
+  assert.match(tooltip.value, /Weekly/);
+  assert.match(tooltip.value, /36%/);
+  assert.match(tooltip.value, /#4caf50/);
+  assert.doesNotMatch(tooltip.value, /Codex home · limits/);
+  assert.equal(tooltip.supportHtml, true);
+});
+
+test('Codex item warns for the worst rendered window while keeping weekly compact text', () => {
+  const item = (): any => ({
+    text: '',
+    tooltip: undefined,
+    backgroundColor: undefined,
+    visible: false,
+    show(): void { this.visible = true; },
+    hide(): void { this.visible = false; },
+  });
+  const manager = bareStatusBar();
+  manager.statusBarItem = item();
+  manager.quotaItem = item();
+  manager.contextItem = item();
+  manager.showCost = true;
+  manager.showContext = true;
+  manager.usageLimitTracking = true;
+  manager.quotaFiveHourOnly = false;
+  manager.resetCountdownFormat = 'decimal';
+
+  const resetsAt = Date.now() + 24 * 60 * 60 * 1000;
+  manager.renderCodex({
+    total: {
+      processed: 5_000_000,
+      fresh: 1_000_000,
+      input: 4_500_000,
+      cachedInput: 3_500_000,
+      output: 500_000,
+      reasoning: 100_000,
+    },
+    rootTasks: 1,
+    threads: 1,
+    childThreads: 0,
+    childProcessedShare: 0,
+    childFreshShare: 0,
+    approvalReviewerThreads: 0,
+    approvalReviewerFreshShare: 0,
+    cacheShare: 0.7,
+    durationMs: 1_000,
+    structural: {
+      patchCalls: 0,
+      toolCalls: 0,
+      postPatchToolCalls: 0,
+      compactCount: 0,
+      taskCompleteCount: 0,
+    },
+    models: [],
+    efforts: [],
+  }, 'fresh', {
+    provider: 'codex',
+    observedAt: Date.now() - 60_000,
+    source: 'local-log',
+    confidence: 'last-observed',
+    windows: [
+      { label: 'primary', usedPercent: 96, windowMinutes: 300, resetsAt },
+      { label: 'secondary', usedPercent: 40, windowMinutes: 10_080, resetsAt },
+    ],
+  });
+
+  assert.equal(manager.quotaItem.text, '$(dashboard) wk 60%');
+  assert.equal(manager.quotaItem.backgroundColor?.id, 'statusBarItem.errorBackground');
+  assert.match(manager.quotaItem.tooltip.value, /96%/);
+  assert.match(manager.quotaItem.tooltip.value, /#f44336/);
+});
+
+test('Codex quota tooltip escapes provider labels', () => {
+  const now = Date.parse('2026-09-02T12:00:00.000Z');
+  const manager = bareStatusBar();
+  manager.quotaFiveHourOnly = false;
+  manager.resetCountdownFormat = 'decimal';
+  const tooltip = manager.createCodexQuotaTooltip({
+    provider: 'codex',
+    observedAt: now,
+    source: 'local-log',
+    confidence: 'last-observed',
+    windows: [{
+      label: '<unsafe & label>',
+      usedPercent: 12,
+      resetsAt: now + 60_000,
+    }],
+  }, now) as RecordingMarkdownString;
+
+  assert.match(tooltip.value, /&lt;unsafe &amp; label&gt;/);
+  assert.doesNotMatch(tooltip.value, /<unsafe/);
+});
diff --git a/src/test/usageDateLabels.test.ts b/src/test/usageDateLabels.test.ts
index c790edd5..36f9b213 100644
--- a/src/test/usageDateLabels.test.ts
+++ b/src/test/usageDateLabels.test.ts
@@ -14,6 +14,7 @@ test('the first day of a month remains a daily label outside monthly views', ()
 test('monthly views explicitly render month labels', () => {
   assert.equal(shortUsageDate('2026-07-01', true), '2026/07');
   assert.equal(formatUsageDate('2026-07-01', 'en-US', {}, true), 'July 2026');
+  assert.equal(formatUsageDate('2026-07', 'en-US', {}, true), 'July 2026');
 });
 
 test('date keys are rendered verbatim instead of shifting in behind-UTC zones', () => {
diff --git a/src/test/webviewDateTime.test.ts b/src/test/webviewDateTime.test.ts
new file mode 100644
index 00000000..1e2a5bac
--- /dev/null
+++ b/src/test/webviewDateTime.test.ts
@@ -0,0 +1,169 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import Module = require('node:module');
+
+import { I18n } from '../i18n';
+
+function withWebviewProvider(run: (provider: any) => void): void {
+  const originalLoad = (Module as any)._load;
+  (Module as any)._load = function(request: string, parent: unknown, isMain: boolean) {
+    if (request === 'vscode') {
+      return { workspace: { workspaceFolders: [] } };
+    }
+    return originalLoad.call(this, request, parent, isMain);
+  };
+  try {
+    const { UsageWebviewProvider } = require('../webview') as typeof import('../webview');
+    run(new UsageWebviewProvider({} as any) as any);
+  } finally {
+    (Module as any)._load = originalLoad;
+  }
+}
+
+test('Claude date labels use the configured timezone for Today and Yesterday', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setLanguage('en');
+    I18n.setTimezone('Asia/Tokyo');
+    withWebviewProvider((provider) => {
+      assert.equal(
+        provider.formatDateTime(
+          new Date('2026-09-03T14:00:00.000Z'),
+          new Date('2026-09-03T15:00:00.000Z'),
+        ),
+        'Yesterday 23:00',
+      );
+      I18n.setTimezone('Pacific/Honolulu');
+      assert.equal(
+        provider.formatDateTime(
+          new Date('2026-09-03T14:00:00.000Z'),
+          new Date('2026-09-03T15:00:00.000Z'),
+        ),
+        'Today 04:00',
+      );
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
+
+test('Claude date labels walk configured civil days across a DST transition', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setLanguage('en');
+    I18n.setTimezone('America/New_York');
+    withWebviewProvider((provider) => {
+      assert.equal(
+        provider.formatDateTime(
+          new Date('2026-03-08T06:30:00.000Z'),
+          new Date('2026-03-09T04:30:00.000Z'),
+        ),
+        'Yesterday 01:30',
+      );
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
+
+test('Claude date labels choose the year branch in the configured timezone', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setLanguage('en');
+    I18n.setTimezone('Asia/Tokyo');
+    withWebviewProvider((provider) => {
+      assert.equal(
+        provider.formatDateTime(
+          new Date('2025-06-15T12:00:00.000Z'),
+          new Date('2026-01-01T04:00:00.000Z'),
+        ),
+        '2025-06-15',
+      );
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
+
+test('Claude date labels preserve compact same-year and invalid-date output', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setLanguage('en');
+    I18n.setTimezone('Asia/Tokyo');
+    withWebviewProvider((provider) => {
+      assert.equal(
+        provider.formatDateTime(
+          new Date('2026-06-01T10:00:00.000Z'),
+          new Date('2026-09-03T15:00:00.000Z'),
+        ),
+        '06-01 19:00',
+      );
+      assert.equal(provider.formatDateTime(new Date(Number.NaN)), '-');
+      assert.equal(provider.formatDateTime(new Date(0)), '-');
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
+
+test('Claude date labels reuse localized Today and Yesterday copy in every UI locale', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setTimezone('Asia/Tokyo');
+    withWebviewProvider((provider) => {
+      for (const language of ['en', 'de-DE', 'zh-TW', 'zh-CN', 'ja', 'ko', 'pt-BR', 'id'] as const) {
+        I18n.setLanguage(language);
+        assert.equal(
+          provider.formatDateTime(
+            new Date('2026-09-03T14:00:00.000Z'),
+            new Date('2026-09-03T15:00:00.000Z'),
+          ),
+          I18n.t.popup.yesterday + ' 23:00',
+          language,
+        );
+      }
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
+
+test('Claude date labels reuse configured-zone Intl formatters across rows', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setLanguage('en');
+    I18n.setTimezone('Asia/Tokyo');
+    withWebviewProvider((provider) => {
+      const OriginalDateTimeFormat = Intl.DateTimeFormat;
+      let constructions = 0;
+      const CountingDateTimeFormat = function(...args: ConstructorParameters<typeof Intl.DateTimeFormat>) {
+        constructions++;
+        return Reflect.construct(OriginalDateTimeFormat, args);
+      } as unknown as typeof Intl.DateTimeFormat;
+      CountingDateTimeFormat.supportedLocalesOf = OriginalDateTimeFormat.supportedLocalesOf.bind(OriginalDateTimeFormat);
+      (Intl as any).DateTimeFormat = CountingDateTimeFormat;
+      try {
+        const now = new Date('2026-09-03T15:00:00.000Z');
+        provider.formatDateTime(new Date('2026-09-03T14:00:00.000Z'), now);
+        provider.formatDateTime(new Date('2026-09-03T13:00:00.000Z'), now);
+        assert.ok(constructions <= 2, `expected at most two formatter constructions, got ${constructions}`);
+      } finally {
+        (Intl as any).DateTimeFormat = OriginalDateTimeFormat;
+      }
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
diff --git a/src/test/webviewWorkflowSummary.test.ts b/src/test/webviewWorkflowSummary.test.ts
new file mode 100644
index 00000000..7b201300
--- /dev/null
+++ b/src/test/webviewWorkflowSummary.test.ts
@@ -0,0 +1,116 @@
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import Module = require('node:module');
+
+import { I18n } from '../i18n';
+import { UsageData, WorkflowUsage } from '../types';
+
+function usage(totalCost: number): UsageData {
+  return {
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheCreationTokens: 0,
+    totalCacheReadTokens: 0,
+    totalCost,
+    costBreakdown: { input: totalCost, output: 0, cacheWrite: 0, cacheRead: 0 },
+    messageCount: 0,
+    modelBreakdown: {},
+  };
+}
+
+function workflow(
+  workflowId: string,
+  startTime: string,
+  endTime: string,
+  totalCost: number,
+): WorkflowUsage {
+  return {
+    workflowId,
+    name: workflowId,
+    sessionId: 'session',
+    projectPath: '/fixture/project',
+    projectName: 'fixture',
+    startTime: new Date(startTime),
+    endTime: new Date(endTime),
+    agentCount: 0,
+    data: usage(totalCost),
+    agents: [],
+  };
+}
+
+function withWebviewProvider(run: (provider: any) => void): void {
+  const originalLoad = (Module as any)._load;
+  (Module as any)._load = function(request: string, parent: unknown, isMain: boolean) {
+    if (request === 'vscode') {
+      return { workspace: { workspaceFolders: [] } };
+    }
+    return originalLoad.call(this, request, parent, isMain);
+  };
+  try {
+    const { UsageWebviewProvider } = require('../webview') as typeof import('../webview');
+    run(new UsageWebviewProvider({} as any) as any);
+  } finally {
+    (Module as any)._load = originalLoad;
+  }
+}
+
+test('Workflows summary matches the configured-zone rolling 30-day dashboard scope', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  try {
+    I18n.setLanguage('en');
+    I18n.setTimezone('Asia/Tokyo');
+    withWebviewProvider((provider) => {
+      provider.monthData = usage(40);
+      provider.workflowBreakdown = [
+        // The first included civil date is 2026-08-06 in Tokyo.
+        workflow('included-by-start', '2026-08-05T15:00:00.000Z', '2026-09-05T00:00:00.000Z', 10),
+        // One minute earlier is outside, even though this workflow ends inside the range.
+        workflow('excluded-by-start', '2026-08-05T14:59:00.000Z', '2026-09-03T00:00:00.000Z', 20),
+      ];
+
+      const html = provider.renderWorkflowData(new Date('2026-09-03T15:00:00.000Z'));
+
+      assert.match(
+        html,
+        /Workflows in the last 30 days: 1 · \$10\.00 · 25% share of the last 30 days' cost/,
+      );
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
+
+test('Workflows rolling-range summary is localized in every UI language', () => {
+  const previousLanguage = I18n.getCurrentLanguage();
+  const previousTimezone = I18n.getTimezone();
+  const expected = {
+    en: ['Workflows in the last 30 days', "share of the last 30 days' cost"],
+    'de-DE': ['Workflows in den letzten 30 Tagen', 'Anteil an den Kosten der letzten 30 Tage'],
+    'zh-TW': ['最近 30 天工作流', '佔最近 30 天成本'],
+    'zh-CN': ['最近 30 天工作流', '占最近 30 天成本'],
+    ja: ['過去30日間のワークフロー', '過去30日間のコストに占める割合'],
+    ko: ['최근 30일 워크플로', '최근 30일 비용 중 비율'],
+    'pt-BR': ['Workflows nos últimos 30 dias', 'dos custos dos últimos 30 dias'],
+    id: ['Workflow 30 hari terakhir', 'proporsi biaya 30 hari terakhir'],
+  } as const;
+  try {
+    I18n.setTimezone('UTC');
+    withWebviewProvider((provider) => {
+      provider.monthData = usage(10);
+      provider.workflowBreakdown = [
+        workflow('recent', '2026-09-01T00:00:00.000Z', '2026-09-01T01:00:00.000Z', 10),
+      ];
+      for (const [language, phrases] of Object.entries(expected)) {
+        I18n.setLanguage(language as keyof typeof expected);
+        const html = provider.renderWorkflowData(new Date('2026-09-03T12:00:00.000Z'));
+        assert.ok(html.includes(phrases[0]), language);
+        assert.ok(html.includes(phrases[1]), language);
+      }
+    });
+  } finally {
+    I18n.setLanguage(previousLanguage);
+    I18n.setTimezone(previousTimezone);
+  }
+});
diff --git a/src/test/weeklyValue.test.ts b/src/test/weeklyValue.test.ts
index b7692239..e95f9d94 100644
--- a/src/test/weeklyValue.test.ts
+++ b/src/test/weeklyValue.test.ts
@@ -63,7 +63,7 @@ test('completed reset window reports used, inferred full, and unused API-equival
   assert.equal(points[0].confidence, 'high');
 });
 
-test('current window is provisional and never presents unused allowance as final', () => {
+test('current window presents a provisional unused API-equivalent estimate', () => {
   const points = buildWeeklyValueTrend({
     observations: [observation({ resetAt: RESET + DAY, observedAt: RESET, usedPercent: 50 })],
     usage: [usage(20, RESET - HOUR)],
@@ -71,7 +71,24 @@ test('current window is provisional and never presents unused allowance as final
 
   assert.equal(points[0].current, true);
   assert.equal(points[0].fullEquivalentUsd, 40);
-  assert.equal(points[0].unusedEquivalentUsd, null);
+  assert.equal(points[0].unusedEquivalentUsd, 20);
+  assert.equal(points[0].confidence, 'medium');
+});
+
+test('legacy trend keeps an unattributed or approximate unused value visibly low-confidence', () => {
+  for (const overrides of [
+    { accountAttribution: 'unattributed' as const },
+    { flags: ['account-ambiguous' as const] },
+    { flags: ['approximate-boundary' as const] },
+  ]) {
+    const points = buildWeeklyValueTrend({
+      observations: [observation(overrides)],
+      usage: [usage(45, RESET - 2 * HOUR)],
+    }, RESET + HOUR);
+    assert.equal(points[0].fullEquivalentUsd, 60);
+    assert.equal(points[0].unusedEquivalentUsd, 15);
+    assert.equal(points[0].confidence, 'low');
+  }
 });
 
 test('usage observed after a stale quota sample cannot exceed the displayed full allowance', () => {
@@ -85,17 +102,17 @@ test('usage observed after a stale quota sample cannot exceed the displayed full
 
   assert.equal(points[0].usedEquivalentUsd, 45);
   assert.equal(points[0].fullEquivalentUsd, 45);
-  assert.equal(points[0].unusedEquivalentUsd, 0);
+  assert.equal(points[0].unusedEquivalentUsd, null);
   assert.equal(points[0].confidence, 'low');
 });
 
-test('tiny utilization and poor price coverage do not manufacture a full allowance value', () => {
+test('valid tiny utilization and partial pricing still produce a low-confidence total estimate', () => {
   const lowUtilization = buildWeeklyValueTrend({
     observations: [observation({ usedPercent: 2 })],
     usage: [usage(20, RESET - 2 * HOUR)],
   }, RESET + HOUR);
-  assert.equal(lowUtilization[0].fullEquivalentUsd, null);
-  assert.equal(lowUtilization[0].confidence, 'usage-only');
+  assert.equal(lowUtilization[0].fullEquivalentUsd, 1_000);
+  assert.equal(lowUtilization[0].confidence, 'low');
 
   const partialPricing = buildWeeklyValueTrend({
     observations: [observation()],
@@ -106,7 +123,35 @@ test('tiny utilization and poor price coverage do not manufacture a full allowan
       totalTokens: 1_000,
     }],
   }, RESET + HOUR);
-  assert.equal(partialPricing[0].fullEquivalentUsd, null);
+  assert.equal(partialPricing[0].fullEquivalentUsd, 20 / 0.75);
+  assert.equal(partialPricing[0].unusedEquivalentUsd, (20 / 0.75) - 20);
+  assert.equal(partialPricing[0].confidence, 'low');
+});
+
+test('pricing coverage after the observation cannot inflate confidence for an underpriced prefix', () => {
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [observation({ usedPercent: 50 })],
+    usage: [
+      {
+        timestamp: RESET - 2 * HOUR,
+        equivalentUsd: 1,
+        pricedTokens: 1,
+        totalTokens: 1_000,
+      },
+      {
+        timestamp: RESET - 30 * 60 * 1000,
+        equivalentUsd: 99,
+        pricedTokens: 9_000,
+        totalTokens: 9_000,
+      },
+    ],
+  }, { now: RESET + HOUR });
+
+  assert.ok(points[0].pricingCoverage > 0.8);
+  assert.equal(points[0].utilizationPercent, 50);
+  assert.equal(points[0].fullEquivalentUsd, 100);
+  assert.equal(points[0].unusedEquivalentUsd, null);
+  assert.equal(points[0].confidence, 'low');
 });
 
 test('source keys keep overlapping Codex account windows from sharing usage', () => {
@@ -125,6 +170,12 @@ test('source keys keep overlapping Codex account windows from sharing usage', ()
   const accountB = points.find((point) => point.resetAt === RESET + DAY);
   assert.equal(accountA?.usedEquivalentUsd, 40);
   assert.equal(accountB?.usedEquivalentUsd, 10);
+  assert.equal(accountA?.fullEquivalentUsd, null);
+  assert.equal(accountA?.unusedEquivalentUsd, null);
+  assert.equal(accountB?.fullEquivalentUsd, null);
+  assert.equal(accountB?.unusedEquivalentUsd, null);
+  assert.equal(accountA?.confidence, 'usage-only');
+  assert.equal(accountB?.confidence, 'usage-only');
 });
 
 test('quota history keeps the latest observation for each percentage step', () => {
@@ -167,6 +218,19 @@ test('known Codex models use exact current API prices and unknown models stay un
   assert.equal(unattributedRemainder.pricingCoverage, 0.5);
 });
 
+test('GPT-6 Astra contributes exact Standard short-context API-equivalent value', () => {
+  const astra = equivalentUsageFromProviderTokens(RESET, 'gpt-6-astra', {
+    inputTotal: 2_000_000,
+    cachedInput: 1_000_000,
+    outputTotal: 1_000_000,
+  });
+
+  // 1M uncached * $10 + 1M cached * $1 + 1M output * $50.
+  assert.equal(astra.equivalentUsd, 61);
+  assert.equal(astra.pricedTokens, 3_000_000);
+  assert.equal(astra.totalTokens, 3_000_000);
+});
+
 test('Codex API-equivalent cost breakdown prices fresh cache-read and output buckets without charging reasoning twice', () => {
   const tokens = {
     inputTotal: 2_000_000,
@@ -274,7 +338,90 @@ test('weekly timeline keeps only the latest current reset for one anonymous Code
   assert.equal(points.reduce((sum, point) => sum + point.usedEquivalentUsd, 0), 65);
 });
 
-test('ambiguous overlapping Codex reset observations do not invent a combined allowance', () => {
+test('Codex keeps post-reset usage in a new reset-aligned period when the quota sample is stale', () => {
+  const now = RESET + HOUR;
+  const points = buildWeeklyValueTimeline('codex', {
+    // Older than the sample window, but still a trustworthy reset timestamp.
+    observations: [observation({
+      observedAt: RESET - 8 * DAY,
+      resetAt: RESET,
+      sourceKey: 'one-file',
+    })],
+    usage: [
+      usage(40, RESET - HOUR, 'one-file'),
+      usage(7, RESET + 30 * 60 * 1000, 'one-file'),
+    ],
+  }, { now });
+
+  const previous = points.find((point) => point.resetAt === RESET);
+  const current = points.find((point) => point.resetAt === RESET + 7 * DAY);
+  assert.equal(previous?.usedEquivalentUsd, 40);
+  assert.equal(current?.usedEquivalentUsd, 7);
+  assert.equal(previous?.basis, 'reset-aligned-usage');
+  assert.equal(current?.basis, 'reset-aligned-usage');
+  assert.equal(current?.utilizationPercent, null);
+  assert.equal(current?.fullEquivalentUsd, null);
+  assert.equal(points.reduce((sum, point) => sum + point.usedEquivalentUsd, 0), 47);
+});
+
+test('conflicting stale Codex reset schedules do not choose an arbitrary alignment', () => {
+  const now = RESET + HOUR;
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [
+      observation({
+        observedAt: RESET - 8 * DAY,
+        resetAt: RESET,
+        sourceKey: 'older-login',
+      }),
+      observation({
+        observedAt: RESET - 8 * DAY + 1,
+        resetAt: RESET + DAY,
+        sourceKey: 'other-login',
+      }),
+    ],
+    usage: [usage(7, RESET + 30 * 60 * 1000, 'older-login')],
+  }, { now });
+
+  assert.equal(points.some((point) => point.resetAt === RESET + 7 * DAY), false);
+  assert.equal(points[0]?.basis, 'calendar-usage');
+  assert.equal(points[0]?.fullEquivalentUsd, null);
+});
+
+test('a fresh Codex reset starts a new current period and estimates both observed windows', () => {
+  const now = RESET + HOUR;
+  const nextReset = RESET + 7 * DAY;
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [
+      observation({
+        observedAt: RESET - HOUR,
+        resetAt: RESET,
+        usedPercent: 80,
+        sourceKey: 'one-file',
+      }),
+      observation({
+        observedAt: RESET + 30 * 60 * 1000,
+        resetAt: nextReset,
+        usedPercent: 10,
+        sourceKey: 'one-file',
+      }),
+    ],
+    usage: [
+      usage(40, RESET - 2 * HOUR, 'one-file'),
+      usage(7, RESET + 15 * 60 * 1000, 'one-file'),
+    ],
+  }, { now });
+
+  assert.equal(points.find((point) => point.resetAt === RESET)?.usedEquivalentUsd, 40);
+  const current = points.find((point) => point.current);
+  assert.equal(current?.resetAt, nextReset);
+  assert.equal(current?.usedEquivalentUsd, 7);
+  assert.equal(current?.utilizationPercent, 10);
+  assert.equal(points.find((point) => point.resetAt === RESET)?.fullEquivalentUsd, 50);
+  assert.equal(points.find((point) => point.resetAt === RESET)?.unusedEquivalentUsd, 10);
+  assert.equal(current?.fullEquivalentUsd, 70);
+});
+
+test('same account-wide Codex series uses the newest coherent observation across stale reset forecasts', () => {
   const now = Date.parse('2026-08-27T04:00:00.000Z');
   const points = buildWeeklyValueTimeline('codex', {
     observations: [
@@ -296,12 +443,12 @@ test('ambiguous overlapping Codex reset observations do not invent a combined al
 
   const current = points.find((point) => point.current);
   assert.equal(current?.utilizationPercent, 43);
-  assert.equal(current?.fullEquivalentUsd, null);
-  assert.equal(current?.unusedEquivalentUsd, null);
-  assert.equal(current?.confidence, 'usage-only');
+  assert.equal(current?.fullEquivalentUsd, 40 / 0.43);
+  assert.equal(current?.unusedEquivalentUsd, (40 / 0.43) - 40);
+  assert.equal(current?.confidence, 'medium');
 });
 
-test('different anonymous Codex series with overlapping current resets are still ambiguous', () => {
+test('overlapping current Codex resets use the latest observation as a low-confidence blended estimate', () => {
   const now = Date.parse('2026-08-27T04:00:00.000Z');
   const points = buildWeeklyValueTimeline('codex', {
     observations: [
@@ -323,11 +470,12 @@ test('different anonymous Codex series with overlapping current resets are still
 
   const current = points.find((point) => point.current);
   assert.equal(current?.utilizationPercent, 43);
-  assert.equal(current?.fullEquivalentUsd, null);
-  assert.equal(current?.confidence, 'usage-only');
+  assert.equal(current?.fullEquivalentUsd, 40 / 0.43);
+  assert.equal(current?.unusedEquivalentUsd, (40 / 0.43) - 40);
+  assert.equal(current?.confidence, 'low');
 });
 
-test('Codex allowance inference is withheld when combined usage has multiple log sources', () => {
+test('Codex allowance inference includes multiple local log sources but lowers confidence', () => {
   const now = RESET - HOUR;
   const points = buildWeeklyValueTimeline('codex', {
     observations: [observation({
@@ -343,11 +491,12 @@ test('Codex allowance inference is withheld when combined usage has multiple log
 
   assert.equal(points[0].usedEquivalentUsd, 50);
   assert.equal(points[0].utilizationPercent, 50);
-  assert.equal(points[0].fullEquivalentUsd, null);
-  assert.equal(points[0].confidence, 'usage-only');
+  assert.equal(points[0].fullEquivalentUsd, 100);
+  assert.equal(points[0].unusedEquivalentUsd, 50);
+  assert.equal(points[0].confidence, 'low');
 });
 
-test('completed Codex periods remain usage-only because account attribution is unavailable', () => {
+test('completed Codex periods estimate total and unused value from an observed window', () => {
   const points = buildWeeklyValueTimeline('codex', {
     observations: [observation({ sourceKey: 'one-file' })],
     usage: [usage(40, RESET - 2 * HOUR, 'one-file')],
@@ -356,12 +505,12 @@ test('completed Codex periods remain usage-only because account attribution is u
   assert.equal(points[0].current, false);
   assert.equal(points[0].usedEquivalentUsd, 40);
   assert.equal(points[0].utilizationPercent, 75);
-  assert.equal(points[0].fullEquivalentUsd, null);
-  assert.equal(points[0].unusedEquivalentUsd, null);
-  assert.equal(points[0].confidence, 'usage-only');
+  assert.equal(points[0].fullEquivalentUsd, 40 / 0.75);
+  assert.ok(Math.abs((points[0].unusedEquivalentUsd ?? 0) - 40 / 3) < 1e-9);
+  assert.equal(points[0].confidence, 'high');
 });
 
-test('a daily Codex aggregate crossing a reset is marked approximate and cannot infer allowance', () => {
+test('a daily Codex aggregate crossing a reset keeps a low-confidence allowance estimate', () => {
   const now = RESET + HOUR;
   const points = buildWeeklyValueTimeline('codex', {
     observations: [observation({
@@ -378,8 +527,47 @@ test('a daily Codex aggregate crossing a reset is marked approximate and cannot
 
   const affected = points.find((point) => point.resetAt === RESET + 7 * DAY);
   assert.equal(affected?.boundaryUncertain, true);
-  assert.equal(affected?.fullEquivalentUsd, null);
-  assert.equal(affected?.confidence, 'usage-only');
+  assert.equal(affected?.fullEquivalentUsd, 80);
+  assert.equal(affected?.unusedEquivalentUsd, 40);
+  assert.equal(affected?.confidence, 'low');
+});
+
+test('an irregular Codex reset is mapped to the fixed period containing its observation', () => {
+  const now = Date.parse('2026-08-31T12:00:00.000Z');
+  const currentReset = Date.parse('2026-09-07T00:00:00.000Z');
+  const driftingReset = Date.parse('2026-08-31T02:00:00.000Z');
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [
+      observation({
+        observedAt: Date.parse('2026-08-25T12:00:00.000Z'),
+        resetAt: driftingReset,
+        usedPercent: 40,
+        sourceKey: 'older-file',
+      }),
+      observation({
+        observedAt: Date.parse('2026-08-31T11:00:00.000Z'),
+        resetAt: currentReset,
+        usedPercent: 20,
+        sourceKey: 'current-file',
+      }),
+    ],
+    usage: [
+      usage(30, Date.parse('2026-08-25T10:00:00.000Z'), 'older-file'),
+      usage(40, Date.parse('2026-08-31T10:00:00.000Z'), 'current-file'),
+    ],
+  }, { now });
+
+  const previous = points.find((point) => point.resetAt === driftingReset - 2 * HOUR);
+  const current = points.find((point) => point.resetAt === currentReset);
+  assert.equal(previous?.usedEquivalentUsd, 30);
+  assert.equal(previous?.utilizationPercent, 40);
+  assert.equal(previous?.fullEquivalentUsd, 75);
+  assert.equal(previous?.unusedEquivalentUsd, 45);
+  assert.equal(previous?.confidence, 'low');
+  assert.equal(current?.usedEquivalentUsd, 40);
+  assert.equal(current?.utilizationPercent, 20);
+  assert.equal(current?.fullEquivalentUsd, 200);
+  assert.equal(current?.unusedEquivalentUsd, 160);
 });
 
 test('quota observations at the reset boundary do not decorate the closed period', () => {
@@ -476,3 +664,180 @@ test('future-dated quota observations cannot anchor weekly history', () => {
   assert.equal(points[0].utilizationPercent, null);
   assert.equal(points[0].fullEquivalentUsd, null);
 });
+
+test('multiple same-window observations use a robust candidate aggregate instead of the latest outlier', () => {
+  const points = buildWeeklyValueTimeline('claude', {
+    observations: [
+      observation({
+        provider: 'claude',
+        seriesKey: 'active-claude',
+        windowId: 'window-one',
+        accountAttribution: 'profile-continuity',
+        observedAt: RESET - 4 * HOUR,
+        usedPercent: 20,
+      }),
+      observation({
+        provider: 'claude',
+        seriesKey: 'active-claude',
+        windowId: 'window-one',
+        accountAttribution: 'profile-continuity',
+        observedAt: RESET - 3 * HOUR,
+        usedPercent: 40,
+      }),
+      observation({
+        provider: 'claude',
+        seriesKey: 'active-claude',
+        windowId: 'window-one',
+        accountAttribution: 'profile-continuity',
+        observedAt: RESET - 2 * HOUR,
+        usedPercent: 10,
+      }),
+    ],
+    usage: [
+      usage(20, RESET - 5 * HOUR),
+      usage(20, RESET - 3.5 * HOUR),
+      usage(20, RESET - 2.5 * HOUR),
+    ],
+  }, { now: RESET + HOUR });
+
+  assert.equal(points[0].fullEquivalentUsd, 100);
+  assert.equal(points[0].usedEquivalentUsd, 60);
+  assert.equal(points[0].unusedEquivalentUsd, 40);
+});
+
+test('low priced coverage lowers confidence but does not hide a mathematically valid total', () => {
+  const points = buildWeeklyValueTimeline('claude', {
+    observations: [observation({
+      provider: 'claude',
+      seriesKey: 'active-claude',
+      accountAttribution: 'profile-continuity',
+      observationConfidence: 'medium',
+      usedPercent: 50,
+    })],
+    usage: [{
+      timestamp: RESET - 2 * HOUR,
+      equivalentUsd: 20,
+      pricedTokens: 100,
+      totalTokens: 1_000,
+    }],
+  }, { now: RESET + HOUR });
+
+  assert.equal(points[0].fullEquivalentUsd, 40);
+  assert.equal(points[0].unusedEquivalentUsd, 20);
+  assert.equal(points[0].confidence, 'low');
+});
+
+test('one unattributed Codex window shows low-confidence total and unused estimates', () => {
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [observation({
+      seriesKey: 'codex-epoch-1',
+      windowId: 'window-one',
+      accountAttribution: 'unattributed',
+      usedPercent: 50,
+    })],
+    usage: [usage(40, RESET - 2 * HOUR)],
+  }, { now: RESET + HOUR });
+
+  assert.equal(points[0].fullEquivalentUsd, 80);
+  assert.equal(points[0].unusedEquivalentUsd, 40);
+  assert.equal(points[0].confidence, 'low');
+});
+
+test('one unattributed Claude window also forces a low-confidence estimate', () => {
+  const points = buildWeeklyValueTimeline('claude', {
+    observations: [observation({
+      provider: 'claude',
+      seriesKey: 'claude-profile',
+      accountAttribution: 'unattributed',
+      usedPercent: 50,
+    })],
+    usage: [usage(40, RESET - 2 * HOUR)],
+  }, { now: RESET + HOUR });
+
+  assert.equal(points[0].fullEquivalentUsd, 80);
+  assert.equal(points[0].unusedEquivalentUsd, 40);
+  assert.equal(points[0].confidence, 'low');
+});
+
+test('a current unattributed Codex window after a completed reset still estimates its total', () => {
+  const currentReset = RESET + 7 * DAY;
+  const now = currentReset - HOUR;
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [
+      observation({
+        seriesKey: 'codex-epoch-1',
+        windowId: 'completed-window',
+        accountAttribution: 'unattributed',
+        observedAt: RESET - HOUR,
+        resetAt: RESET,
+        usedPercent: 84,
+      }),
+      observation({
+        seriesKey: 'codex-epoch-2',
+        windowId: 'current-window',
+        accountAttribution: 'unattributed',
+        observedAt: now - HOUR,
+        resetAt: currentReset,
+        usedPercent: 74,
+      }),
+    ],
+    usage: [
+      usage(40, RESET - 2 * HOUR),
+      usage(74, now - 2 * HOUR),
+    ],
+  }, { now });
+
+  const current = points.find((point) => point.current);
+  assert.equal(current?.usedEquivalentUsd, 74);
+  assert.equal(current?.utilizationPercent, 74);
+  assert.equal(current?.fullEquivalentUsd, 100);
+  assert.equal(current?.unusedEquivalentUsd, 26);
+  assert.equal(current?.confidence, 'low');
+});
+
+test('a single Codex window flagged account-ambiguous still exposes a durability estimate', () => {
+  const currentReset = RESET + 7 * DAY;
+  const now = currentReset - HOUR;
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [observation({
+      seriesKey: 'codex-local-home',
+      windowId: 'current-window',
+      accountAttribution: 'unattributed',
+      flags: ['account-ambiguous'],
+      observedAt: now - HOUR,
+      resetAt: currentReset,
+      usedPercent: 25,
+    })],
+    usage: [usage(50, now - 2 * HOUR)],
+  }, { now });
+
+  assert.equal(points[0].fullEquivalentUsd, 200);
+  assert.equal(points[0].unusedEquivalentUsd, 150);
+  assert.equal(points[0].confidence, 'low');
+});
+
+test('overlapping unattributed Codex epochs never share usage for an allowance estimate', () => {
+  const points = buildWeeklyValueTimeline('codex', {
+    observations: [
+      observation({
+        seriesKey: 'codex-epoch-1',
+        windowId: 'window-one',
+        accountAttribution: 'unattributed',
+        observedAt: RESET - 2 * HOUR,
+        usedPercent: 50,
+      }),
+      observation({
+        seriesKey: 'codex-epoch-2',
+        windowId: 'window-two',
+        accountAttribution: 'unattributed',
+        observedAt: RESET - HOUR,
+        usedPercent: 25,
+      }),
+    ],
+    usage: [usage(40, RESET - 3 * HOUR)],
+  }, { now: RESET + HOUR });
+
+  assert.equal(points[0].fullEquivalentUsd, null);
+  assert.equal(points[0].unusedEquivalentUsd, null);
+  assert.equal(points[0].confidence, 'usage-only');
+});
diff --git a/src/types.ts b/src/types.ts
index d3cc91d5..defac15d 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -194,7 +194,7 @@ export interface ThinkingShare {
 export interface SkillUse {
   name: string;
   sessionId: string;
-  day: string; // local "YYYY-MM-DD"
+  day: string; // configured-zone "YYYY-MM-DD" captured when parsed; rebucket ts after zone changes
   ts: number; // epoch ms of the invocation (0 when unparsable)
   estTokens: number;
 }
@@ -208,7 +208,15 @@ export interface ContentAnalysis {
   totalEstimatedTokens: number;
   // Recent user prompts (last 30 days), for the AI-advice feature. Each carries
   // its working directory so advice can be scoped to a project.
-  recentPrompts: { cwd: string; text: string }[];
+  recentPrompts: { cwd: string; text: string; observedAtEpochMs: number }[];
+  /**
+   * Numeric-only proxy separating Claude Code framework injection from text
+   * attributed to the user. No source text, path, session ID, or tool ID is
+   * retained. Components may overlap ordinary content buckets (for example a
+   * Skill tool result is both consumed tool output and a framework preamble),
+   * so this is a labelled proxy rather than a billing decomposition.
+   */
+  frameworkOverhead?: FrameworkOverheadAnalysis;
   // Thinking-token share per session id and per local day ("YYYY-MM-DD"),
   // last 30 days (analysis window).
   thinkingBySession: Record<string, ThinkingShare>;
@@ -228,6 +236,30 @@ export interface ContentAnalysis {
   };
 }
 
+export type FrameworkOverheadKind =
+  | 'meta'
+  | 'sidechain'
+  | 'subagent-dispatch'
+  | 'command-echo'
+  | 'system-reminder'
+  | 'framework-wrapper'
+  | 'tool-result-envelope'
+  | 'skill-preamble';
+
+export interface FrameworkOverheadAnalysis {
+  frameworkEstimatedTokens: number;
+  /** Unique estimated input-side total used as the ratio denominator. */
+  observedInputEstimatedTokens: number;
+  userAuthoredEstimatedTokens: number;
+  toolResultEstimatedTokens: number;
+  classifiedEvents: number;
+  components: Array<{
+    kind: FrameworkOverheadKind;
+    estimatedTokens: number;
+    count: number;
+  }>;
+}
+
 // Scope of the usage-attribution panel. day = today, week = last 7 days,
 // month = last 30 days; session/project narrow to one session / one project.
 export interface AttributionScope {
@@ -268,6 +300,7 @@ export interface UsageAttribution {
 export interface ExtensionConfig {
   refreshInterval: number;
   dataDirectory: string;
+  pricingBackend: 'anthropic' | 'aws-bedrock-in-region';
   codexEnabled: boolean;
   codexDataDirectory: string;
   codexFileWatchSeconds: number;
@@ -313,12 +346,11 @@ export interface ExtensionConfig {
   // Free-text background about the user/project; when set, the advice ends
   // with a "Personalised for this project" section calibrated against it.
   adviceUserContext: string;
-  // Advice/optimizer transport (v2.1 Phase 9). backend: 'subscription' reuses
-  // the Claude Code OAuth session (no key, prefers haiku); 'api' uses a key.
-  // apiFormat: 'anthropic' (default) or 'openai'-compatible.
-  adviceBackend: 'subscription' | 'api';
+  // Production advice/optimizer transport is user-configured API/BYOK only.
+  // The old subscription transport remains isolated inside advisor.ts and has
+  // no ExtensionConfig/runtime call point after its Messages requests returned 403.
+  adviceBackend: 'api';
   adviceApiFormat: 'anthropic' | 'openai';
-  adviceSubscriptionModel: string;
   // How many days of prompts/content the advice analysis samples (default 30).
   advicePromptWindowDays: number;
   // Run the (CPU-heavy) content/prompt-token analysis. When false the Content
diff --git a/src/usageDateLabels.ts b/src/usageDateLabels.ts
index 17ea4024..611f54ea 100644
--- a/src/usageDateLabels.ts
+++ b/src/usageDateLabels.ts
@@ -16,7 +16,7 @@ export function formatUsageDate(
   // itself in UTC so negative offsets cannot roll it into the previous day or
   // month (#54), and use an explicit monthly flag so July 1 remains a day.
   const [year, month, day] = dateString.split('-').map(Number);
-  const date = new Date(Date.UTC(year, month - 1, day, 12));
+  const date = new Date(Date.UTC(year, month - 1, monthly ? 1 : day, 12));
   const options: Intl.DateTimeFormatOptions = monthly
     ? { year: 'numeric', month: 'long' }
     : dailyOptions;
diff --git a/src/webview.ts b/src/webview.ts
index 436375cd..4f4f39ce 100644
--- a/src/webview.ts
+++ b/src/webview.ts
@@ -11,6 +11,23 @@ import {
 } from './settings';
 import { buildResumeCommand, isUsableCwd, isValidSessionId, isUnderDir } from './sessionResume';
 import { renderHeatmapSvg } from './heatmapSvg';
+import {
+  CombinedHeatmapRange,
+  claudeDailyPointsFromUsage,
+  codexDailyPointsFromUsage,
+  combinedHeatmapFilename,
+  combinedHeatmapMarkdown,
+  mergeCombinedDailyUsage,
+  normalizeCombinedHeatmapRange,
+  sanitizeCombinedHeatmapTitle,
+  selectCombinedHeatmapWindow,
+} from './combinedHeatmap';
+import {
+  normalizeCombinedHeatmapAccent,
+  normalizeCombinedHeatmapIntensityMode,
+  normalizeCombinedHeatmapPalette,
+  renderCombinedHeatmapSvg,
+} from './combinedHeatmapSvg';
 import { DEFAULT_SECTIONS, ShareSections, buildShareCardData, shareCardFilename } from './shareCard';
 import { renderShareCardSvg, ShareCardTheme } from './shareCardSvg';
 import { parseConversation } from './conversationLog';
@@ -47,6 +64,48 @@ import { getProviderNavClientScript } from './providerNavClient';
 import * as os from 'os';
 import * as path from 'path';
 import * as https from 'https';
+import { createHash, randomBytes } from 'crypto';
+import {
+  AdviceEffectivenessProvider,
+  AdviceEffectivenessProviderState,
+  AdviceEffectivenessProviderStates,
+  PreparedAdviceSnapshot,
+  prepareAdviceSnapshot,
+} from './adviceEffectiveness/integration';
+import type { PreparedAiInvocation } from './adviceEffectiveness/preparedRequest';
+import { previewAiInvocation } from './adviceEffectiveness/preparedRequest';
+import type {
+  StructuredAdviceRequestResult,
+} from './adviceEffectiveness/remoteAdvice';
+import type { StructuredAdviceReferences } from './adviceEffectiveness/structuredOutput';
+import { AdviceRecommendation, createAdviceContract } from './adviceEffectiveness/contract';
+import type { PreparedOptimizerResult } from './optimizerRequest';
+import type { BackgroundWorkReason } from './backgroundWorkState';
+import {
+  AdviceLocalState,
+  AdviceLocalStateStorage,
+  StoredComparablePair,
+  appendAdviceComparisonResult,
+  appendStoredComparablePair,
+  createClearedAdviceLocalState,
+  createClosedAdviceLocalState,
+  loadAndMigrateAdviceLocalState,
+  adviceRecommendationSnoozedUntil,
+  ADVICE_SNOOZE_DURATION_MS,
+  ADVICE_LOCAL_STATE_KEY,
+  resumeAdviceRecommendation,
+  saveAdviceLocalState,
+  snoozeAdviceRecommendation,
+  upsertAdviceLocalFeedback,
+} from './adviceEffectiveness/versionedPersistence';
+import {
+  CODEX_COMPARISON_MEASUREMENT_PROFILE_VERSION,
+  CODEX_LOCAL_RECOMMENDATION_VERSION,
+  CodexComparableTaskProjection,
+  buildAppliedComparablePairs,
+  isComparableCodexRecommendationId,
+} from './adviceEffectiveness/comparisonProduction';
+import { buildAdviceComparisonResultEnvelope } from './adviceEffectiveness/comparisonResult';
 import {
   AttributionScope,
   BranchUsage,
@@ -61,12 +120,486 @@ import {
   UsageData,
   WorkflowUsage,
 } from './types';
+import { dayKeyInZone, resolveTimeZone, rollingDayKeys, rollingDayKeysFromDayKey } from './dateKeys';
+import {
+  LocalDataAction,
+  LocalDataActionResult,
+  LocalDataClientAction,
+  LocalDataClientSummary,
+  LocalDataInventory,
+  approximateJsonBytes,
+  finiteTimestampRange,
+  isLocalDataAction,
+} from './localDataControls';
 
 interface CodexRenderProgress {
   scannedFiles: number;
   totalFiles: number;
   indexedBytes: number;
   totalBytes: number;
+  reason?: BackgroundWorkReason;
+}
+
+const OPTIMIZER_FEEDBACK_RECOMMENDATION_ID = 'recommendation-optimizer-result-v1';
+
+interface LocalDataUiCopy {
+  title: string;
+  intro: string;
+  inventory: string;
+  refresh: string;
+  category: string;
+  location: string;
+  schema: string;
+  sizeCount: string;
+  dateRange: string;
+  network: string;
+  clearability: string;
+  actions: string;
+  rebuildIndex: string;
+  quotaScope: string;
+  clearQuota: string;
+  clearAdvice: string;
+  resetUi: string;
+  resetSharing: string;
+  clearByok: string;
+  clearAll: string;
+  loading: string;
+  unavailable: string;
+  bytes: string;
+  items: string;
+  sourceExclusions: string;
+}
+
+function localDataUiCopy(locale: string): LocalDataUiCopy {
+  if (locale === 'zh-CN') {
+    return {
+      title: '本地数据与隐私控制',
+      intro: '清单只显示类别、非敏感位置类型和汇总元数据；不会显示路径、账号指纹、设置值或日志内容。',
+      inventory: '本地数据清单',
+      refresh: '刷新清单',
+      category: '类别',
+      location: '位置类型',
+      schema: 'Schema',
+      sizeCount: '约占用 / 数量',
+      dateRange: '最早 / 最新',
+      network: '可能的网络交互',
+      clearability: '清除方式',
+      actions: '安全清除与重建',
+      rebuildIndex: '重建 Codex 索引…',
+      quotaScope: '额度历史范围',
+      clearQuota: '清除所选额度历史…',
+      clearAdvice: '清除建议数据…',
+      resetUi: '重置界面状态…',
+      resetSharing: '重置分享偏好…',
+      clearByok: '清除 BYOK 密钥…',
+      clearAll: '清除全部插件派生数据…',
+      loading: '正在读取不含敏感值的本地清单…',
+      unavailable: '暂时无法读取本地数据清单。',
+      bytes: '字节',
+      items: '项',
+      sourceExclusions: '始终排除：',
+    };
+  }
+  return {
+    title: 'Local data and privacy controls',
+    intro: 'The inventory exposes categories, non-sensitive location classes, and aggregate metadata only—never paths, account fingerprints, setting values, or log content.',
+    inventory: 'Local data inventory',
+    refresh: 'Refresh inventory',
+    category: 'Category',
+    location: 'Location class',
+    schema: 'Schema',
+    sizeCount: 'Approx. size / count',
+    dateRange: 'Oldest / newest',
+    network: 'Possible network interaction',
+    clearability: 'Clearing route',
+    actions: 'Safe clearing and rebuild',
+    rebuildIndex: 'Rebuild Codex index…',
+    quotaScope: 'Quota-history scope',
+    clearQuota: 'Clear selected quota history…',
+    clearAdvice: 'Clear advice data…',
+    resetUi: 'Reset UI state…',
+    resetSharing: 'Reset sharing preferences…',
+    clearByok: 'Clear BYOK secret…',
+    clearAll: 'Clear all extension-derived data…',
+    loading: 'Reading a value-free local inventory…',
+    unavailable: 'The local data inventory is temporarily unavailable.',
+    bytes: 'bytes',
+    items: 'items',
+    sourceExclusions: 'Always excluded:',
+  };
+}
+
+interface CombinedHeatmapUiCopy {
+  eyebrow: string;
+  panelTitle: string;
+  description: string;
+  previewLabel: string;
+  privateBadge: string;
+  settingsLabel: string;
+  defaultTitle: string;
+  titleLabel: string;
+  rangeLabel: string;
+  last30: string;
+  last90: string;
+  year: string;
+  intensityLabel: string;
+  intensityQuantile: string;
+  intensityLogarithmic: string;
+  intensityLinear: string;
+  paletteLabel: string;
+  academicViolet: string;
+  claudeOrange: string;
+  codexBlue: string;
+  githubGreen: string;
+  customPalette: string;
+  customAccent: string;
+  privacyToggle: string;
+  privacyIncludes: string;
+  privacyExcludes: string;
+  updatePreview: string;
+  exportSvg: string;
+  copyMarkdown: string;
+  resetSharing: string;
+  resetComplete: string;
+  resetFailed: string;
+  markdownLabel: string;
+  noData: string;
+  activityDisclaimer: string;
+  combinedLabel: string;
+  processedTokensLabel: string;
+  svgFooterNote: string;
+}
+
+function combinedHeatmapIntensityUiCopy(locale: string): Pick<
+  CombinedHeatmapUiCopy,
+  'intensityLabel' | 'intensityQuantile' | 'intensityLogarithmic' | 'intensityLinear'
+> {
+  const copy: Record<string, [string, string, string, string]> = {
+    en: ['Intensity scale', 'Quantile', 'Logarithmic', 'Linear'],
+    'de-DE': ['Intensitätsskala', 'Quantil', 'Logarithmisch', 'Linear'],
+    'zh-TW': ['色階映射', '分位數', '對數', '線性'],
+    'zh-CN': ['色阶映射', '分位数', '对数', '线性'],
+    ja: ['強度スケール', '分位数', '対数', '線形'],
+    ko: ['강도 스케일', '분위수', '로그', '선형'],
+    'pt-BR': ['Escala de intensidade', 'Quantil', 'Logarítmica', 'Linear'],
+    id: ['Skala intensitas', 'Kuantil', 'Logaritmik', 'Linear'],
+  };
+  const [intensityLabel, intensityQuantile, intensityLogarithmic, intensityLinear] = copy[locale] ?? copy.en;
+  return { intensityLabel, intensityQuantile, intensityLogarithmic, intensityLinear };
+}
+
+function combinedHeatmapUiCopy(locale: string): CombinedHeatmapUiCopy {
+  const intensity = combinedHeatmapIntensityUiCopy(locale);
+  if (locale === 'zh-CN') {
+    return {
+      ...intensity,
+      eyebrow: '分享工作台',
+      panelTitle: '综合活动热力图与分享卡',
+      description: '按本地自然日合并 Claude 与 Codex 的已处理 Token 活动量；默认强度不是成本。',
+      previewLabel: '实时预览',
+      privateBadge: '仅含隐私安全的日汇总',
+      settingsLabel: '卡片设置',
+      defaultTitle: 'Claude + Codex 本地活动',
+      titleLabel: '分享标题',
+      rangeLabel: '时间范围',
+      last30: '最近 30 天',
+      last90: '最近 90 天',
+      year: '最近一年',
+      paletteLabel: '热力图配色',
+      academicViolet: '学术紫',
+      claudeOrange: 'Claude 橙',
+      codexBlue: 'Codex 蓝',
+      githubGreen: 'GitHub 绿',
+      customPalette: '自定义',
+      customAccent: '自定义主色',
+      privacyToggle: '显示隐私预览',
+      privacyIncludes: '导出包含：自定义标题、日期范围，以及 Claude、Codex 和综合的每日已处理 Token 汇总。',
+      privacyExcludes: '明确排除：账号、项目、线程标题、本地路径和日志内容。',
+      updatePreview: '更新预览',
+      exportSvg: '导出 SVG…',
+      copyMarkdown: '复制 Markdown',
+      resetSharing: '重置分享偏好',
+      resetComplete: '分享偏好已重置。',
+      resetFailed: '无法完全重置分享偏好。',
+      markdownLabel: 'README / Markdown 引用片段',
+      noData: '所选时间范围内尚无本地活动。',
+      activityDisclaimer: '综合 Token 仅表示本地活动量，不代表生产率、订阅账单或两个 provider 的能力等价。',
+      combinedLabel: '综合',
+      processedTokensLabel: '已处理 Token',
+      svgFooterNote: '本地活动量 · 不代表生产率、账单或 provider 能力等价',
+    };
+  }
+  if (locale === 'zh-TW') {
+    return {
+      ...intensity,
+      eyebrow: '分享工作台',
+      panelTitle: '綜合活動熱力圖與分享卡',
+      description: '依本機自然日合併 Claude 與 Codex 的已處理 Token 活動量；預設強度不是成本。',
+      previewLabel: '即時預覽',
+      privateBadge: '僅含隱私安全的每日彙總',
+      settingsLabel: '卡片設定',
+      defaultTitle: 'Claude + Codex 本機活動',
+      titleLabel: '分享標題',
+      rangeLabel: '時間範圍',
+      last30: '最近 30 天',
+      last90: '最近 90 天',
+      year: '最近一年',
+      paletteLabel: '熱力圖配色',
+      academicViolet: '學術紫',
+      claudeOrange: 'Claude 橙',
+      codexBlue: 'Codex 藍',
+      githubGreen: 'GitHub 綠',
+      customPalette: '自訂',
+      customAccent: '自訂主色',
+      privacyToggle: '顯示隱私預覽',
+      privacyIncludes: '匯出包含：自訂標題、日期範圍，以及 Claude、Codex 和綜合的每日已處理 Token 彙總。',
+      privacyExcludes: '明確排除：帳號、專案、執行緒標題、本機路徑和記錄內容。',
+      updatePreview: '更新預覽',
+      exportSvg: '匯出 SVG…',
+      copyMarkdown: '複製 Markdown',
+      resetSharing: '重設分享偏好',
+      resetComplete: '分享偏好已重設。',
+      resetFailed: '無法完全重設分享偏好。',
+      markdownLabel: 'README / Markdown 引用片段',
+      noData: '所選時間範圍內尚無本機活動。',
+      activityDisclaimer: '綜合 Token 僅表示本機活動量，不代表生產力、訂閱帳單或兩個 provider 的能力等價。',
+      combinedLabel: '綜合',
+      processedTokensLabel: '已處理 Token',
+      svgFooterNote: '本機活動量 · 不代表生產力、帳單或 provider 能力等價',
+    };
+  }
+  if (locale === 'de-DE') {
+    return {
+      ...intensity,
+      eyebrow: 'Freigabe-Arbeitsbereich',
+      panelTitle: 'Kombinierte Aktivitäts-Heatmap und Freigabekarte',
+      description: 'Fasst die verarbeitete Token-Aktivität von Claude und Codex nach lokalem Kalendertag zusammen. Die Kosten sind nicht die Standardintensität.',
+      previewLabel: 'Live-Vorschau',
+      privateBadge: 'Nur datenschutzsichere Tagesaggregate',
+      settingsLabel: 'Karteneinstellungen',
+      defaultTitle: 'Claude + Codex lokale Aktivität',
+      titleLabel: 'Freigabetitel',
+      rangeLabel: 'Zeitraum',
+      last30: 'Letzte 30 Tage',
+      last90: 'Letzte 90 Tage',
+      year: 'Letztes Jahr',
+      paletteLabel: 'Heatmap-Farben',
+      academicViolet: 'Akademisches Violett',
+      claudeOrange: 'Claude Orange',
+      codexBlue: 'Codex Blau',
+      githubGreen: 'GitHub Grün',
+      customPalette: 'Benutzerdefiniert',
+      customAccent: 'Benutzerdefinierter Akzent',
+      privacyToggle: 'Datenschutzvorschau anzeigen',
+      privacyIncludes: 'Export enthält: den benutzerdefinierten Titel, den Zeitraum sowie die täglichen Claude-, Codex- und kombinierten Gesamtsummen der verarbeiteten Token.',
+      privacyExcludes: 'Ausdrücklich ausgeschlossen: Konten, Projekte, Thread-Titel, lokale Pfade und Protokollinhalte.',
+      updatePreview: 'Vorschau aktualisieren',
+      exportSvg: 'SVG exportieren…',
+      copyMarkdown: 'Markdown kopieren',
+      resetSharing: 'Freigabeeinstellungen zurücksetzen',
+      resetComplete: 'Freigabeeinstellungen wurden zurückgesetzt.',
+      resetFailed: 'Die Freigabeeinstellungen konnten nicht vollständig zurückgesetzt werden.',
+      markdownLabel: 'README-/Markdown-Ausschnitt',
+      noData: 'Im ausgewählten Zeitraum sind noch keine lokalen Aktivitätsdaten verfügbar.',
+      activityDisclaimer: 'Kombinierte Token beschreiben das lokale Aktivitätsvolumen, nicht Produktivität, Abonnementkosten oder die Gleichwertigkeit der Anbieterfähigkeiten.',
+      combinedLabel: 'Kombiniert',
+      processedTokensLabel: 'verarbeitete Token',
+      svgFooterNote: 'Lokales Aktivitätsvolumen · nicht Produktivität, Abrechnung oder Anbieter-Gleichwertigkeit',
+    };
+  }
+  if (locale === 'ja') {
+    return {
+      ...intensity,
+      eyebrow: '共有ワークスペース',
+      panelTitle: '統合アクティビティヒートマップと共有カード',
+      description: 'Claude と Codex の処理済みトークン活動をローカルの暦日単位で統合します。既定の強度はコストではありません。',
+      previewLabel: 'ライブプレビュー',
+      privateBadge: 'プライバシーに配慮した日次集計のみ',
+      settingsLabel: 'カード設定',
+      defaultTitle: 'Claude + Codex のローカルアクティビティ',
+      titleLabel: '共有タイトル',
+      rangeLabel: '期間',
+      last30: '過去30日間',
+      last90: '過去90日間',
+      year: '過去1年間',
+      paletteLabel: 'ヒートマップの配色',
+      academicViolet: 'アカデミックバイオレット',
+      claudeOrange: 'Claude オレンジ',
+      codexBlue: 'Codex ブルー',
+      githubGreen: 'GitHub グリーン',
+      customPalette: 'カスタム',
+      customAccent: 'カスタムアクセントカラー',
+      privacyToggle: 'プライバシープレビューを表示',
+      privacyIncludes: 'エクスポートに含まれるもの: カスタムタイトル、期間、Claude・Codex・統合の日次処理済みトークン合計。',
+      privacyExcludes: '明示的に除外されるもの: アカウント、プロジェクト、スレッドタイトル、ローカルパス、ログ内容。',
+      updatePreview: 'プレビューを更新',
+      exportSvg: 'SVG をエクスポート…',
+      copyMarkdown: 'Markdown をコピー',
+      resetSharing: '共有設定をリセット',
+      resetComplete: '共有設定をリセットしました。',
+      resetFailed: '共有設定を完全にリセットできませんでした。',
+      markdownLabel: 'README / Markdown スニペット',
+      noData: '選択した期間にはまだローカルアクティビティがありません。',
+      activityDisclaimer: '統合トークンはローカルの活動量を示すものであり、生産性、サブスクリプション料金、プロバイダー間の能力の等価性を表すものではありません。',
+      combinedLabel: '統合',
+      processedTokensLabel: '処理済みトークン',
+      svgFooterNote: 'ローカルの活動量 · 生産性、請求額、プロバイダー間の等価性を表すものではありません',
+    };
+  }
+  if (locale === 'ko') {
+    return {
+      ...intensity,
+      eyebrow: '공유 작업 공간',
+      panelTitle: '통합 활동 히트맵과 공유 카드',
+      description: 'Claude와 Codex의 처리된 토큰 활동을 로컬 달력 날짜 기준으로 통합합니다. 기본 강도는 비용이 아닙니다.',
+      previewLabel: '실시간 미리보기',
+      privateBadge: '개인정보를 보호하는 일별 집계만',
+      settingsLabel: '카드 설정',
+      defaultTitle: 'Claude + Codex 로컬 활동',
+      titleLabel: '공유 제목',
+      rangeLabel: '기간',
+      last30: '최근 30일',
+      last90: '최근 90일',
+      year: '최근 1년',
+      paletteLabel: '히트맵 색상',
+      academicViolet: '아카데믹 바이올렛',
+      claudeOrange: 'Claude 오렌지',
+      codexBlue: 'Codex 블루',
+      githubGreen: 'GitHub 그린',
+      customPalette: '사용자 지정',
+      customAccent: '사용자 지정 강조색',
+      privacyToggle: '개인정보 미리보기 표시',
+      privacyIncludes: '내보내기에 포함되는 항목: 사용자 지정 제목, 기간, Claude·Codex·통합 일별 처리된 토큰 합계.',
+      privacyExcludes: '명시적으로 제외되는 항목: 계정, 프로젝트, 스레드 제목, 로컬 경로, 로그 내용.',
+      updatePreview: '미리보기 업데이트',
+      exportSvg: 'SVG 내보내기…',
+      copyMarkdown: 'Markdown 복사',
+      resetSharing: '공유 환경설정 재설정',
+      resetComplete: '공유 환경설정이 재설정되었습니다.',
+      resetFailed: '공유 환경설정을 완전히 재설정하지 못했습니다.',
+      markdownLabel: 'README / Markdown 스니펫',
+      noData: '선택한 기간에는 아직 로컬 활동 데이터가 없습니다.',
+      activityDisclaimer: '통합 토큰은 로컬 활동량을 나타낼 뿐, 생산성이나 구독 결제액, 공급자 간 성능 등가성을 의미하지 않습니다.',
+      combinedLabel: '통합',
+      processedTokensLabel: '처리된 토큰',
+      svgFooterNote: '로컬 활동량 · 생산성, 청구액, 공급자 등가성을 의미하지 않음',
+    };
+  }
+  if (locale === 'pt-BR') {
+    return {
+      ...intensity,
+      eyebrow: 'Espaço de compartilhamento',
+      panelTitle: 'Mapa de calor de atividade combinado e cartão de compartilhamento',
+      description: 'Combina a atividade de tokens processados do Claude e do Codex por dia do calendário local. O custo não é a intensidade padrão.',
+      previewLabel: 'Prévia em tempo real',
+      privateBadge: 'Somente agregados diários que preservam a privacidade',
+      settingsLabel: 'Configurações do cartão',
+      defaultTitle: 'Atividade local do Claude + Codex',
+      titleLabel: 'Título do compartilhamento',
+      rangeLabel: 'Intervalo de datas',
+      last30: 'Últimos 30 dias',
+      last90: 'Últimos 90 dias',
+      year: 'Último ano',
+      paletteLabel: 'Cores do mapa de calor',
+      academicViolet: 'Violeta Acadêmico',
+      claudeOrange: 'Claude Laranja',
+      codexBlue: 'Codex Azul',
+      githubGreen: 'GitHub Verde',
+      customPalette: 'Personalizado',
+      customAccent: 'Cor de destaque personalizada',
+      privacyToggle: 'Mostrar prévia de privacidade',
+      privacyIncludes: 'A exportação inclui: o título personalizado, o intervalo de datas e os totais diários agregados de tokens processados do Claude, do Codex e combinados.',
+      privacyExcludes: 'Explicitamente excluído: contas, projetos, títulos de threads, caminhos locais e conteúdo de logs.',
+      updatePreview: 'Atualizar prévia',
+      exportSvg: 'Exportar SVG…',
+      copyMarkdown: 'Copiar Markdown',
+      resetSharing: 'Redefinir preferências de compartilhamento',
+      resetComplete: 'Preferências de compartilhamento redefinidas.',
+      resetFailed: 'Não foi possível redefinir totalmente as preferências de compartilhamento.',
+      markdownLabel: 'Trecho de README / Markdown',
+      noData: 'Ainda não há atividade local disponível no intervalo selecionado.',
+      activityDisclaimer: 'Os tokens combinados descrevem o volume de atividade local, não produtividade, cobrança da assinatura ou equivalência de capacidade entre provedores.',
+      combinedLabel: 'Combinado',
+      processedTokensLabel: 'tokens processados',
+      svgFooterNote: 'Volume de atividade local · não produtividade, cobrança ou equivalência entre provedores',
+    };
+  }
+  if (locale === 'id') {
+    return {
+      ...intensity,
+      eyebrow: 'Ruang kerja berbagi',
+      panelTitle: 'Heatmap aktivitas gabungan dan kartu berbagi',
+      description: 'Menggabungkan aktivitas token yang diproses oleh Claude dan Codex berdasarkan hari kalender lokal. Biaya bukan intensitas default.',
+      previewLabel: 'Pratinjau langsung',
+      privateBadge: 'Hanya agregat harian yang aman bagi privasi',
+      settingsLabel: 'Pengaturan kartu',
+      defaultTitle: 'Aktivitas lokal Claude + Codex',
+      titleLabel: 'Judul berbagi',
+      rangeLabel: 'Rentang tanggal',
+      last30: '30 hari terakhir',
+      last90: '90 hari terakhir',
+      year: '1 tahun terakhir',
+      paletteLabel: 'Warna heatmap',
+      academicViolet: 'Violet Akademik',
+      claudeOrange: 'Claude Oranye',
+      codexBlue: 'Codex Biru',
+      githubGreen: 'GitHub Hijau',
+      customPalette: 'Kustom',
+      customAccent: 'Aksen kustom',
+      privacyToggle: 'Tampilkan pratinjau privasi',
+      privacyIncludes: 'Ekspor mencakup: judul kustom, rentang tanggal, dan total harian token yang diproses (Claude, Codex, dan gabungan).',
+      privacyExcludes: 'Secara eksplisit dikecualikan: akun, proyek, judul thread, jalur lokal, dan konten log.',
+      updatePreview: 'Perbarui pratinjau',
+      exportSvg: 'Ekspor SVG…',
+      copyMarkdown: 'Salin Markdown',
+      resetSharing: 'Atur ulang preferensi berbagi',
+      resetComplete: 'Preferensi berbagi telah diatur ulang.',
+      resetFailed: 'Preferensi berbagi tidak dapat diatur ulang sepenuhnya.',
+      markdownLabel: 'Cuplikan README / Markdown',
+      noData: 'Belum ada aktivitas lokal yang tersedia dalam rentang yang dipilih.',
+      activityDisclaimer: 'Token gabungan menggambarkan volume aktivitas lokal, bukan produktivitas, tagihan langganan, atau kesetaraan kemampuan antar-provider.',
+      combinedLabel: 'Gabungan',
+      processedTokensLabel: 'token yang diproses',
+      svgFooterNote: 'Volume aktivitas lokal · bukan produktivitas, tagihan, atau kesetaraan provider',
+    };
+  }
+  return {
+    ...intensity,
+    eyebrow: 'Share studio',
+    panelTitle: 'Combined activity heatmap and share card',
+    description: 'Combines Claude and Codex processed-token activity by local calendar day. Cost is not the default intensity.',
+    previewLabel: 'Live preview',
+    privateBadge: 'Privacy-safe daily aggregates only',
+    settingsLabel: 'Card settings',
+    defaultTitle: 'Claude + Codex local activity',
+    titleLabel: 'Share title',
+    rangeLabel: 'Date range',
+    last30: 'Last 30 days',
+    last90: 'Last 90 days',
+    year: 'Last year',
+    paletteLabel: 'Heatmap colors',
+    academicViolet: 'Academic Violet',
+    claudeOrange: 'Claude Orange',
+    codexBlue: 'Codex Blue',
+    githubGreen: 'GitHub Green',
+    customPalette: 'Custom',
+    customAccent: 'Custom accent',
+    privacyToggle: 'Show privacy preview',
+    privacyIncludes: 'Export includes: the custom title, date range, and daily aggregate Claude, Codex, and combined processed-token totals.',
+    privacyExcludes: 'Explicitly excluded: accounts, projects, thread titles, local paths, and log content.',
+    updatePreview: 'Update preview',
+    exportSvg: 'Export SVG…',
+    copyMarkdown: 'Copy Markdown',
+    resetSharing: 'Reset sharing preferences',
+    resetComplete: 'Sharing preferences reset.',
+    resetFailed: 'Could not fully reset sharing preferences.',
+    markdownLabel: 'README / Markdown snippet',
+    noData: 'No local activity is available in the selected range yet.',
+    activityDisclaimer: 'Combined tokens describe local activity volume, not productivity, subscription billing, or provider capability equivalence.',
+    combinedLabel: 'Combined',
+    processedTokensLabel: 'processed tokens',
+    svgFooterNote: 'Local activity volume · not productivity, billing, or provider equivalence',
+  };
 }
 
 export class UsageWebviewProvider {
@@ -90,6 +623,10 @@ export class UsageWebviewProvider {
   private codexProgress: CodexRenderProgress | null = null;
   private providerSelectionInitialized = false;
   private hourlyDataCache: Map<string, { hour: string; data: UsageData }[]> = new Map();
+  private configuredDateTimeFormatter?: {
+    configuredTimeZone: string;
+    formatter: Intl.DateTimeFormat;
+  };
   private allRecords: any[] = [];
   private sessionBreakdown: SessionUsage[] = [];
   private projectBreakdown: ProjectGroup[] = [];
@@ -126,18 +663,52 @@ export class UsageWebviewProvider {
     fullNumbers: boolean;
     theme: string;
   };
+  private readonly localDataClientActionRequests = new Map<
+    string,
+    { resolve: (ok: boolean) => void; timeout: NodeJS.Timeout }
+  >();
   // Real quota utilisation (pushed asynchronously) for the workflow quota
   // guard banner; dismissal lasts for the lifetime of this window.
   private usageLimits: ClaudeApiUsageResponse | null = null;
   private claudeWeeklyQuotaHistory: WeeklyQuotaObservation[] = [];
   private quotaWarnDismissed: boolean = false;
-  // Set by extension.ts: runs the Usage Optimizer round-trip (model lives there
-  // with the config + OAuth client). Returns the optimised prompt + settings
-  // recommendation, or an error string.
-  public onOptimize?: (
+  // Extension-host hooks make the optimizer use the same prepare -> preview ->
+  // explicit send boundary as advice, without exposing keys to the webview.
+  public onPrepareOptimizerInvocation?: (
     draft: string,
-    options: { resolve: boolean; distil: boolean; aesthetic: boolean }
-  ) => Promise<{ prompt?: string; settings?: string; error?: string }>;
+    options: { resolve: boolean; distil: boolean; aesthetic: boolean },
+    sourceRevision: string,
+    consentGeneration: number,
+  ) => Promise<{ prepared?: PreparedAiInvocation; error?: string }>;
+  public onSendOptimizerInvocation?: (
+    prepared: PreparedAiInvocation,
+    expectedSourceRevision: string,
+    expectedConsentGeneration: number,
+  ) => Promise<PreparedOptimizerResult>;
+  /** Extension-host hooks keep API configuration and keys out of the webview. */
+  public onPrepareAdviceInvocation?: (
+    snapshot: PreparedAdviceSnapshot,
+    sourceRevision: string,
+    consentGeneration: number,
+  ) => PreparedAiInvocation;
+  public onSendAdviceInvocation?: (
+    prepared: PreparedAiInvocation,
+    references: StructuredAdviceReferences,
+    expectedSourceRevision: string,
+    expectedConsentGeneration: number,
+  ) => Promise<StructuredAdviceRequestResult>;
+  public onAiSurfaceClosed?: () => void;
+  public onAdviceDataCleared?: () => Promise<void>;
+  public onAdviceConsentWithdrawn?: () => Promise<void>;
+  public onRequestLocalDataInventory?: (
+    client: LocalDataClientSummary,
+  ) => Promise<LocalDataInventory>;
+  public onRunLocalDataAction?: (
+    action: LocalDataAction,
+    quotaScopeToken?: string,
+  ) => Promise<LocalDataActionResult>;
+  public onResetSharingPreferences?: () => Promise<void>;
+  public onLocalDataClientReady?: () => void;
   // Shared settings store + a callback to let extension.ts re-apply config when
   // the user edits a setting in the dashboard's ⚙ Settings tab. Both are set by
   // extension.ts right after construction.
@@ -154,9 +725,68 @@ export class UsageWebviewProvider {
     prompt?: string;
     settings?: string;
     error?: string;
+    snapshotId?: string;
+    previewBody?: string;
+    previewSha256?: string;
+    previewBytes?: number;
+    /** Random opaque run ID; never derived from the draft or model output. */
+    adviceId?: string;
   } | null = null;
-
-  constructor(private context: vscode.ExtensionContext) {}
+  private preparedOptimizerRequests = new Map<
+    string,
+    {
+      prepared: PreparedAiInvocation;
+      draft: string;
+      sourceRevision: string;
+      consentGeneration: number;
+    }
+  >();
+  private optimizerConsentGeneration = 0;
+  /**
+   * Experimental v2.3.1 state. Raw prompt samples never enter rendered HTML:
+   * they stay in the provider state until one explicit sealed-snapshot request.
+   */
+  private adviceEffectivenessStates: AdviceEffectivenessProviderStates = {};
+  private preparedAdviceSnapshots = new Map<
+    string,
+    {
+      provider: AdviceEffectivenessProvider;
+      snapshot: PreparedAdviceSnapshot;
+      invocation: PreparedAiInvocation;
+      sourceRevision: string;
+      consentGeneration: number;
+      references: StructuredAdviceReferences;
+    }
+  >();
+  private adviceConsentGeneration = 0;
+  private adviceConsentWritesPending = 0;
+  private adviceLocalState: AdviceLocalState = createClosedAdviceLocalState();
+  private adviceLocalStateStatus: 'loading' | 'ready' | 'degraded' = 'loading';
+  private adviceLocalStateGeneration = 0;
+  private adviceLocalStateWrite: Promise<void> = Promise.resolve();
+  private adviceComparisonProductionRevision = '';
+
+  constructor(private context: vscode.ExtensionContext) {
+    const storage = this.adviceStateStorage();
+    if (!storage) {
+      this.adviceLocalStateStatus = 'degraded';
+      return;
+    }
+    void loadAndMigrateAdviceLocalState(storage).then((loaded) => {
+      this.adviceLocalState = loaded.value;
+      this.adviceLocalStateStatus = loaded.ok ? 'ready' : 'degraded';
+      this.scheduleAdviceComparisonProduction();
+      if (this.panel) {
+        this.updateWebview();
+      }
+    }).catch(() => {
+      this.adviceLocalState = createClosedAdviceLocalState();
+      this.adviceLocalStateStatus = 'degraded';
+      if (this.panel) {
+        this.updateWebview();
+      }
+    });
+  }
 
   /** Read a moved/core setting through the shared store, with a fallback. */
   private setting<T>(key: string, fallback: T): T {
@@ -167,9 +797,796 @@ export class UsageWebviewProvider {
     return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
   }
 
-  show(): void {
+  private adviceStateStorage(): AdviceLocalStateStorage | undefined {
+    const state = (this.context as Partial<vscode.ExtensionContext>).globalState;
+    if (!state || typeof state.get !== 'function' || typeof state.update !== 'function') {
+      return undefined;
+    }
+    return state;
+  }
+
+  private adviceExperimentEnabled(): boolean {
+    return this.setting<boolean>('advice.effectiveness.enabled', false);
+  }
+
+  /**
+   * Serialize every persisted advice mutation through one writer. The mutation
+   * is derived from the latest committed state only when its turn starts, so a
+   * delayed consent, feedback, comparison, or clear write cannot resurrect an
+   * older snapshot over a newer user decision.
+   */
+  private enqueueAdviceLocalStateWrite(
+    mutate: (current: AdviceLocalState) => AdviceLocalState | undefined,
+  ): Promise<
+    | { ok: true; changed: boolean; value: AdviceLocalState }
+    | { ok: false }
+  > {
+    const operation = this.adviceLocalStateWrite.then(async () => {
+      const storage = this.adviceStateStorage();
+      if (!storage || this.adviceLocalStateStatus !== 'ready') {
+        return { ok: false as const };
+      }
+      let next: AdviceLocalState | undefined;
+      try {
+        next = mutate(this.adviceLocalState);
+      } catch {
+        return { ok: false as const };
+      }
+      if (!next) {
+        return { ok: true as const, changed: false, value: this.adviceLocalState };
+      }
+      const saved = await saveAdviceLocalState(storage, next);
+      if (!saved.ok) {
+        this.adviceLocalStateStatus = 'degraded';
+        return { ok: false as const };
+      }
+      this.adviceLocalState = saved.value;
+      return { ok: true as const, changed: true, value: saved.value };
+    });
+    this.adviceLocalStateWrite = operation.then(
+      () => undefined,
+      () => undefined,
+    );
+    return operation;
+  }
+
+  private adviceProviderState(value: unknown): AdviceEffectivenessProviderState | undefined {
+    if (!this.adviceExperimentEnabled() || (value !== 'claude' && value !== 'codex')) {
+      return undefined;
+    }
+    return this.adviceEffectivenessStates[value];
+  }
+
+  private postAdviceMessage(message: Record<string, unknown>): void {
+    void this.panel?.webview.postMessage(message);
+  }
+
+  private clearPreparedAdviceSnapshots(provider?: AdviceEffectivenessProvider): void {
+    if (!provider) {
+      this.preparedAdviceSnapshots.clear();
+      return;
+    }
+    for (const [snapshotId, value] of this.preparedAdviceSnapshots) {
+      if (value.provider === provider) {
+        this.preparedAdviceSnapshots.delete(snapshotId);
+      }
+    }
+  }
+
+  /** Opaque content revision; no path/session/title is retained or exposed. */
+  private adviceSourceRevision(state: AdviceEffectivenessProviderState): string {
+    const safeShape = {
+      provider: state.provider,
+      aggregate: state.aggregate,
+      observations: state.contract.observations.map((item) => ({
+        id: item.id,
+        metric: item.metric,
+        value: item.value,
+        unit: item.unit,
+        method: item.method,
+        sourceId: item.sourceId,
+      })),
+      evidence: state.contract.evidence.map((item) => ({
+        id: item.id,
+        observationIds: item.observationIds,
+        strength: item.strength,
+      })),
+      sourceQuality: state.contract.provenance.sources.map((source) => ({
+        id: source.id,
+        confidence: source.confidence,
+        qualityFlags: source.qualityFlags,
+        window: source.window,
+      })),
+      // Prompt text remains host-only. Its digest merely invalidates a preview
+      // if the separately consented sample set changes before send.
+      promptSampleDigest: createHash('sha256')
+        .update(state.promptSamples.map((sample) => sample.text).join('\u0000'), 'utf8')
+        .digest('hex'),
+      userContextDigest: createHash('sha256')
+        .update(state.userContext ?? '', 'utf8')
+        .digest('hex'),
+    };
+    return `advice-${createHash('sha256')
+      .update(JSON.stringify(safeShape), 'utf8')
+      .digest('hex')}`;
+  }
+
+  private async handleAdviceConsentMessage(message: Record<string, unknown>): Promise<void> {
+    const providerState = this.adviceProviderState(message.provider);
+    const aggregateConsent = message.aggregateConsent;
+    const promptSampleConsent = message.promptSampleConsent;
+    const stateGeneration = this.adviceLocalStateGeneration;
+    if (
+      !providerState ||
+      providerState.provider !== 'claude' ||
+      !providerState.remotePreviewEligible ||
+      !providerState.aggregate ||
+      (aggregateConsent !== 'explicit' && aggregateConsent !== 'not-granted') ||
+      (promptSampleConsent !== 'explicit' && promptSampleConsent !== 'not-granted') ||
+      (promptSampleConsent === 'explicit' && aggregateConsent !== 'explicit') ||
+      (promptSampleConsent === 'explicit' &&
+        providerState.promptSamples.length === 0 &&
+        !providerState.userContext?.trim()) ||
+      this.adviceLocalStateStatus !== 'ready' ||
+      !this.adviceStateStorage()
+    ) {
+      this.postAdviceMessage({ command: 'adviceConsentResult', ok: false, provider: message.provider });
+      return;
+    }
+    const withdrawn =
+      (this.adviceLocalState.aggregateConsent === 'explicit' && aggregateConsent === 'not-granted') ||
+      (this.adviceLocalState.promptSampleConsent === 'explicit' && promptSampleConsent === 'not-granted');
+    // Revocation takes effect on receipt, not after a potentially slow disk write.
+    // A counter also covers overlapping consent changes in the shared writer queue.
+    this.adviceConsentWritesPending += 1;
+    this.adviceConsentGeneration += 1;
+    this.clearPreparedAdviceSnapshots(providerState.provider);
+    const cancellation = withdrawn
+      ? Promise.resolve().then(() => this.onAdviceConsentWithdrawn?.()).then(() => true, () => false)
+      : Promise.resolve(true);
+    try {
+      const saved = await this.enqueueAdviceLocalStateWrite((current) => {
+        if (stateGeneration !== this.adviceLocalStateGeneration) return undefined;
+        return {
+          ...current,
+          featureMode: 'enabled',
+          aggregateConsent,
+          promptSampleConsent,
+        };
+      });
+      const cancelled = await cancellation;
+      if (!cancelled) this.adviceLocalStateStatus = 'degraded';
+      if (!saved.ok || !saved.changed || !cancelled) {
+        this.postAdviceMessage({ command: 'adviceConsentResult', ok: false, provider: message.provider });
+        return;
+      }
+      this.postAdviceMessage({
+        command: 'adviceConsentResult',
+        ok: true,
+        provider: providerState.provider,
+        aggregateConsent: saved.value.aggregateConsent,
+        promptSampleConsent: saved.value.promptSampleConsent,
+      });
+    } finally {
+      this.adviceConsentWritesPending -= 1;
+    }
+  }
+
+  private handlePrepareAdviceSnapshotMessage(message: Record<string, unknown>): void {
+    const providerState = this.adviceProviderState(message.provider);
+    if (!providerState) {
+      this.postAdviceMessage({ command: 'adviceSnapshotResult', ok: false, provider: message.provider });
+      return;
+    }
+    const aggregate = message.aggregateConsent;
+    const promptSamples = message.promptSampleConsent;
+    if (
+      (aggregate !== 'explicit' && aggregate !== 'not-granted') ||
+      (promptSamples !== 'explicit' && promptSamples !== 'not-granted') ||
+      this.adviceLocalStateStatus !== 'ready' ||
+      this.adviceConsentWritesPending > 0 ||
+      aggregate !== this.adviceLocalState.aggregateConsent ||
+      (promptSamples === 'explicit' && this.adviceLocalState.promptSampleConsent !== 'explicit')
+    ) {
+      this.postAdviceMessage({ command: 'adviceSnapshotResult', ok: false, provider: providerState.provider });
+      return;
+    }
+    const result = prepareAdviceSnapshot(providerState, {
+      aggregate,
+      promptSamples,
+    });
+    if (!result.ok) {
+      this.postAdviceMessage({
+        command: 'adviceSnapshotResult',
+        ok: false,
+        provider: providerState.provider,
+        reason: result.reason,
+      });
+      return;
+    }
+    let invocation: PreparedAiInvocation;
+    const sourceRevision = this.adviceSourceRevision(providerState);
+    try {
+      if (!this.onPrepareAdviceInvocation) {
+        throw new Error('AI preparation is unavailable');
+      }
+      invocation = this.onPrepareAdviceInvocation(
+        result.value,
+        sourceRevision,
+        this.adviceConsentGeneration,
+      );
+    } catch {
+      this.postAdviceMessage({
+        command: 'adviceSnapshotResult',
+        ok: false,
+        provider: providerState.provider,
+        reason: 'invalid-evidence',
+      });
+      return;
+    }
+    const preview = previewAiInvocation(invocation);
+    this.clearPreparedAdviceSnapshots(providerState.provider);
+    const snapshotId = `snapshot-${randomBytes(12).toString('hex')}`;
+    this.preparedAdviceSnapshots.set(snapshotId, {
+      provider: providerState.provider,
+      snapshot: result.value,
+      invocation,
+      sourceRevision,
+      consentGeneration: this.adviceConsentGeneration,
+      references: {
+        observationIds: providerState.contract.observations.map((item) => item.id),
+        evidenceIds: providerState.contract.evidence.map((item) => item.id),
+      },
+    });
+    this.postAdviceMessage({
+      command: 'adviceSnapshotResult',
+      ok: true,
+      snapshotId,
+      provider: providerState.provider,
+      contentType: preview.contentType,
+      dataMode: preview.dataMode,
+      promptSampleCount: result.value.preview.promptSampleCount,
+      utf8Bytes: preview.utf8Bytes,
+      sha256: preview.sha256,
+      body: preview.body,
+    });
+  }
+
+  private async handleSendAdviceSnapshotMessage(message: Record<string, unknown>): Promise<void> {
+    const snapshotId = message.snapshotId;
+    const providerState = this.adviceProviderState(message.provider);
+    const stored = typeof snapshotId === 'string'
+      ? this.preparedAdviceSnapshots.get(snapshotId)
+      : undefined;
+    if (
+      !providerState ||
+      !stored ||
+      this.adviceLocalStateStatus !== 'ready' ||
+      this.adviceConsentWritesPending > 0 ||
+      this.adviceLocalState.aggregateConsent !== 'explicit' ||
+      stored.provider !== providerState.provider ||
+      stored.sourceRevision !== this.adviceSourceRevision(providerState) ||
+      stored.consentGeneration !== this.adviceConsentGeneration ||
+      !this.onSendAdviceInvocation
+    ) {
+      this.postAdviceMessage({
+        command: 'adviceSendResult',
+        ok: false,
+        provider: message.provider,
+        reason: 'stale-preview',
+      });
+      return;
+    }
+    const result = await this.onSendAdviceInvocation(
+      stored.invocation,
+      stored.references,
+      stored.sourceRevision,
+      stored.consentGeneration,
+    );
+    if (
+      this.preparedAdviceSnapshots.get(snapshotId as string) !== stored ||
+      stored.sourceRevision !== this.adviceSourceRevision(providerState) ||
+      stored.consentGeneration !== this.adviceConsentGeneration
+    ) {
+      this.postAdviceMessage({
+        command: 'adviceSendResult',
+        ok: false,
+        provider: providerState.provider,
+        reason: 'stale-preview',
+      });
+      return;
+    }
+    if (!result.ok) {
+      this.postAdviceMessage({
+        command: 'adviceSendResult',
+        ok: false,
+        provider: providerState.provider,
+        reason: result.code,
+      });
+      return;
+    }
+    const next = createAdviceContract({
+      adviceId: providerState.contract.adviceId,
+      observations: providerState.contract.observations,
+      evidence: providerState.contract.evidence,
+      recommendations: result.value.recommendations,
+      privacy: {
+        dataMode: stored.invocation.dataMode === 'aggregates-with-prompt-samples'
+          ? 'aggregates-with-prompt-samples'
+          : stored.invocation.dataMode === 'aggregates-with-personalization'
+            ? 'aggregates-with-personalization'
+            : 'aggregates-only',
+        promptSampleConsent: stored.invocation.dataMode === 'aggregates-only'
+          ? 'not-granted'
+          : 'explicit',
+        promptSampleCount: stored.snapshot.prepared.promptSampleCount,
+        feedbackStorage: 'local-only',
+      },
+      provenance: {
+        ...providerState.contract.provenance,
+        generatedBy: { kind: 'remote-model' },
+        generatedAt: new Date().toISOString(),
+      },
+    });
+    if (!next.ok) {
+      this.postAdviceMessage({
+        command: 'adviceSendResult',
+        ok: false,
+        provider: providerState.provider,
+        reason: 'invalid-schema',
+      });
+      return;
+    }
+    providerState.contract = next.value;
+    this.preparedAdviceSnapshots.delete(snapshotId as string);
+    this.postAdviceMessage({
+      command: 'adviceSendResult',
+      ok: true,
+      provider: providerState.provider,
+      recommendationCount: next.value.recommendations.length,
+    });
+    this.updateWebview();
+  }
+
+  public async clearAdviceLocalData(): Promise<boolean> {
+    const storage = this.adviceStateStorage();
+    if (!storage) {
+      return false;
+    }
+    this.adviceLocalStateGeneration += 1;
+    this.adviceConsentGeneration += 1;
+    this.clearPreparedAdviceSnapshots();
+    this.adviceComparisonProductionRevision = '';
+    const write = this.adviceLocalStateWrite.then(async () => {
+      const cleared = createClearedAdviceLocalState();
+      try {
+        // Removing the current key is the user-visible privacy guarantee. The
+        // in-memory enabled/closed surface remains usable until reload, while a
+        // later mutation must queue after this removal before recreating state.
+        await storage.update(ADVICE_LOCAL_STATE_KEY, undefined);
+        this.adviceLocalState = cleared;
+        this.adviceLocalStateStatus = 'ready';
+        return { ok: true };
+      } catch {
+        return { ok: false };
+      }
+    });
+    this.adviceLocalStateWrite = write.then(() => undefined, () => undefined);
+    const cancelled = Promise.resolve(this.onAdviceDataCleared?.()).catch(() => undefined);
+    const saved = await write;
+    await cancelled;
+    if (!saved.ok) {
+      return false;
+    }
+    this.updateWebview();
+    return true;
+  }
+
+  public adviceLocalDataInventorySummary(): {
+    approximateBytes: number | null;
+    itemCount: number;
+    oldestAt: number | null;
+    newestAt: number | null;
+  } {
+    const state = this.adviceLocalState;
+    const timestamps = [
+      ...state.feedback.flatMap((item) => [item.updatedAtEpochMs, item.appliedAtEpochMs]),
+      ...state.suppression.flatMap((item) => [item.updatedAtEpochMs, item.snoozedUntilEpochMs]),
+      ...state.comparablePairs.map((item) => item.recordedAtEpochMs),
+      ...state.comparisonResults.map((item) => item.recordedAtEpochMs),
+    ];
+    const range = finiteTimestampRange(timestamps);
+    return {
+      approximateBytes: approximateJsonBytes(state),
+      itemCount:
+        state.feedback.length +
+        state.suppression.length +
+        state.comparablePairs.length +
+        state.comparisonResults.length,
+      ...range,
+    };
+  }
+
+  public requestLocalDataInventoryRefresh(): void {
+    this.panel?.webview.postMessage({ command: 'requestLocalDataInventoryClient' });
+  }
+
+  private settleLocalDataClientAction(requestId: string, ok: boolean): void {
+    const pending = this.localDataClientActionRequests.get(requestId);
+    if (!pending) return;
+    clearTimeout(pending.timeout);
+    this.localDataClientActionRequests.delete(requestId);
+    pending.resolve(ok);
+  }
+
+  /**
+   * Apply Webview-owned deletion with an acknowledgement. Host-side success is
+   * not reported until the live panel confirms its exact allowlists ran.
+   */
+  public requestClientLocalDataAction(action: LocalDataClientAction): Promise<boolean> {
+    const panel = this.panel;
+    if (!panel) return Promise.resolve(false);
+    const requestId = randomBytes(12).toString('hex');
+    return new Promise<boolean>((resolve) => {
+      const timeout = setTimeout(
+        () => this.settleLocalDataClientAction(requestId, false),
+        2_000,
+      );
+      this.localDataClientActionRequests.set(requestId, { resolve, timeout });
+      void Promise.resolve(panel.webview.postMessage({
+        command: 'localDataClientAction',
+        action,
+        requestId,
+      })).then((delivered) => {
+        if (!delivered) this.settleLocalDataClientAction(requestId, false);
+      }).catch(() => this.settleLocalDataClientAction(requestId, false));
+    });
+  }
+
+  public clearSharingRuntimeState(): void {
+    this.lastShareCardSvg = undefined;
+    this.lastShareCardConfig = undefined;
+  }
+
+  private async handleClearAdviceLocalDataMessage(): Promise<void> {
+    const ok = await this.clearAdviceLocalData();
+    this.postAdviceMessage({ command: 'adviceClearResult', ok });
+  }
+
+  private async handleAdviceFeedbackMessage(message: Record<string, unknown>): Promise<void> {
+    const optimizerTarget =
+      message.provider === 'optimizer' &&
+      this.setting<boolean>('advice.optimizer.enabled', false) &&
+      typeof this.optimizerState?.adviceId === 'string' &&
+      this.optimizerState.adviceId === message.adviceId &&
+      message.recommendationId === OPTIMIZER_FEEDBACK_RECOMMENDATION_ID &&
+      typeof this.optimizerState.prompt === 'string' &&
+      this.optimizerState.prompt.length > 0;
+    const providerState = optimizerTarget
+      ? undefined
+      : this.adviceProviderState(message.provider);
+    const stateGeneration = this.adviceLocalStateGeneration;
+    const adviceId = message.adviceId;
+    const recommendationId = message.recommendationId;
+    const kind = message.kind;
+    const recommendation = providerState?.contract.recommendations.find(
+      (candidate) => candidate.id === recommendationId,
+    );
+    const targetAdviceId = optimizerTarget
+      ? this.optimizerState!.adviceId as string
+      : providerState?.contract.adviceId;
+    const targetRecommendationId = optimizerTarget
+      ? OPTIMIZER_FEEDBACK_RECOMMENDATION_ID
+      : recommendation?.id;
+    const responseIdentity =
+      typeof targetAdviceId === 'string' &&
+      typeof targetRecommendationId === 'string' &&
+      targetAdviceId === adviceId &&
+      targetRecommendationId === recommendationId
+        ? { adviceId: targetAdviceId, recommendationId: targetRecommendationId }
+        : {};
+    if (
+      (!optimizerTarget && !providerState) ||
+      targetAdviceId !== adviceId ||
+      targetRecommendationId !== recommendationId ||
+      (kind !== 'helpful' && kind !== 'not-helpful' && kind !== 'applied') ||
+      this.adviceLocalStateStatus !== 'ready' ||
+      !this.adviceStateStorage()
+    ) {
+      this.postAdviceMessage({
+        command: 'adviceFeedbackResult',
+        ok: false,
+        provider: message.provider,
+        ...responseIdentity,
+      });
+      return;
+    }
+    const updatedAtEpochMs = Date.now();
+    let mutationAccepted = true;
+    const saved = await this.enqueueAdviceLocalStateWrite((current) => {
+      if (stateGeneration !== this.adviceLocalStateGeneration) return undefined;
+      const changed = upsertAdviceLocalFeedback(current, {
+        adviceId: targetAdviceId as string,
+        recommendationId: targetRecommendationId as string,
+        kind,
+        updatedAtEpochMs,
+      });
+      if (!changed.ok) {
+        mutationAccepted = false;
+        return undefined;
+      }
+      const changedFeedback = changed.value.feedback.find(
+        (item) => item.adviceId === adviceId && item.recommendationId === recommendationId,
+      );
+      return kind === 'applied' && changedFeedback?.applied !== 'applied'
+        ? {
+            ...changed.value,
+            featureMode: 'enabled' as const,
+            comparablePairs: changed.value.comparablePairs.filter(
+              (pair) => pair.adviceId !== adviceId || pair.recommendationId !== recommendationId,
+            ),
+            comparisonResults: changed.value.comparisonResults.filter(
+              (result) => result.recommendationId !== recommendationId,
+            ),
+          }
+        : { ...changed.value, featureMode: 'enabled' as const };
+    });
+    if (!saved.ok) {
+      this.postAdviceMessage({
+        command: 'adviceFeedbackResult',
+        ok: false,
+        provider: message.provider,
+        ...responseIdentity,
+      });
+      return;
+    }
+    if (!saved.changed || !mutationAccepted) {
+      this.postAdviceMessage({
+        command: 'adviceFeedbackResult',
+        ok: false,
+        provider: message.provider,
+        ...responseIdentity,
+      });
+      return;
+    }
+    if (kind === 'applied' && !optimizerTarget) {
+      this.adviceComparisonProductionRevision = '';
+      this.scheduleAdviceComparisonProduction();
+    }
+    const feedback = saved.value.feedback.find(
+      (item) => item.adviceId === adviceId && item.recommendationId === recommendationId,
+    );
+    this.postAdviceMessage({
+      command: 'adviceFeedbackResult',
+      ok: true,
+      provider: message.provider,
+      adviceId,
+      recommendationId,
+      rating: feedback?.rating ?? 'unrated',
+      applied: feedback?.applied ?? 'not-applied',
+    });
+  }
+
+  private async handleAdviceSnoozeMessage(message: Record<string, unknown>): Promise<void> {
+    const optimizerTarget =
+      message.provider === 'optimizer' &&
+      this.setting<boolean>('advice.optimizer.enabled', false) &&
+      typeof this.optimizerState?.adviceId === 'string' &&
+      this.optimizerState.adviceId === message.adviceId &&
+      message.recommendationId === OPTIMIZER_FEEDBACK_RECOMMENDATION_ID;
+    const providerState = optimizerTarget ? undefined : this.adviceProviderState(message.provider);
+    const adviceId = message.adviceId;
+    const recommendationId = message.recommendationId;
+    const targetAdviceId = optimizerTarget ? this.optimizerState!.adviceId : providerState?.contract.adviceId;
+    const targetRecommendationId = optimizerTarget
+      ? OPTIMIZER_FEEDBACK_RECOMMENDATION_ID
+      : providerState?.contract.recommendations.find((item) => item.id === recommendationId)?.id;
+    const valid =
+      (optimizerTarget || Boolean(providerState)) &&
+      typeof adviceId === 'string' &&
+      typeof recommendationId === 'string' &&
+      targetAdviceId === adviceId &&
+      targetRecommendationId === recommendationId &&
+      this.adviceLocalStateStatus === 'ready' &&
+      Boolean(this.adviceStateStorage());
+    const response = { command: 'adviceSnoozeResult', provider: message.provider, adviceId, recommendationId };
+    if (!valid) {
+      this.postAdviceMessage({ ...response, ok: false });
+      return;
+    }
+    const stateGeneration = this.adviceLocalStateGeneration;
+    const now = Date.now();
+    const resume = message.mode === 'resume';
+    let mutationAccepted = true;
+    const saved = await this.enqueueAdviceLocalStateWrite((current) => {
+      if (stateGeneration !== this.adviceLocalStateGeneration) return undefined;
+      const changed = resume
+        ? resumeAdviceRecommendation(current, {
+            provider: optimizerTarget ? 'optimizer' : message.provider as 'claude' | 'codex',
+            surface: optimizerTarget ? 'optimizer' : 'advice',
+            recommendationId: targetRecommendationId as string,
+          })
+        : snoozeAdviceRecommendation(current, {
+            provider: optimizerTarget ? 'optimizer' : message.provider as 'claude' | 'codex',
+            surface: optimizerTarget ? 'optimizer' : 'advice',
+            recommendationId: targetRecommendationId as string,
+            updatedAtEpochMs: now,
+            snoozedUntilEpochMs: now + ADVICE_SNOOZE_DURATION_MS,
+          });
+      if (!changed.ok) {
+        mutationAccepted = false;
+        return undefined;
+      }
+      return { ...changed.value, featureMode: 'enabled' as const };
+    });
+    if (!saved.ok || !saved.changed || !mutationAccepted) {
+      this.postAdviceMessage({ ...response, ok: false });
+      return;
+    }
+    const until = adviceRecommendationSnoozedUntil(saved.value, {
+      provider: optimizerTarget ? 'optimizer' : message.provider as 'claude' | 'codex',
+      surface: optimizerTarget ? 'optimizer' : 'advice',
+      recommendationId: targetRecommendationId as string,
+      nowEpochMs: now,
+    });
+    this.postAdviceMessage({ ...response, ok: true, snoozedUntilEpochMs: until });
+    this.updateWebview();
+  }
+
+  private async handlePrepareOptimizerMessage(message: Record<string, unknown>): Promise<void> {
+    if (!this.setting<boolean>('advice.optimizer.enabled', false)) {
+      this.discardPreparedOptimizer();
+      this.postAdviceMessage({ command: 'optimizePreviewResult', ok: false, error: I18n.t.popup.adviceEffectiveness.strictOutputRejected });
+      return;
+    }
+    const draft = typeof message.draft === 'string' ? message.draft : '';
+    const options = {
+      resolve: message.resolve === true,
+      distil: message.distil === true,
+      aesthetic: message.aesthetic === true,
+    };
+    // An explicit rerun is an active user decision: it re-opens the stable
+    // optimizer recommendation scope without changing its independent feedback.
+    if (this.adviceLocalStateStatus === 'ready' && this.adviceStateStorage()) {
+      await this.enqueueAdviceLocalStateWrite((current) => {
+        const resumed = resumeAdviceRecommendation(current, {
+          provider: 'optimizer',
+          surface: 'optimizer',
+          recommendationId: OPTIMIZER_FEEDBACK_RECOMMENDATION_ID,
+        });
+        return resumed.ok ? resumed.value : undefined;
+      });
+    }
+    this.optimizerConsentGeneration += 1;
+    this.preparedOptimizerRequests.clear();
+    const sourceRevision = `optimizer-${createHash('sha256')
+      .update(JSON.stringify({ draft, options }), 'utf8')
+      .digest('hex')}`;
+    const consentGeneration = this.optimizerConsentGeneration;
+    const baseState = { draft, ...options };
+    if (!this.onPrepareOptimizerInvocation) {
+      this.optimizerState = { ...baseState, error: 'Optimizer is not available.' };
+      this.postAdviceMessage({ command: 'optimizePreviewResult', ok: false, error: 'Optimizer is not available.' });
+      return;
+    }
+    const result = await this.onPrepareOptimizerInvocation(
+      draft,
+      options,
+      sourceRevision,
+      consentGeneration,
+    );
+    if (consentGeneration !== this.optimizerConsentGeneration) {
+      this.postAdviceMessage({ command: 'optimizePreviewResult', ok: false, error: I18n.t.popup.adviceEffectiveness.strictOutputRejected });
+      return;
+    }
+    if (!result.prepared) {
+      this.optimizerState = { ...baseState, error: result.error ?? '' };
+      this.postAdviceMessage({ command: 'optimizePreviewResult', ok: false, error: result.error ?? '' });
+      return;
+    }
+    const preview = previewAiInvocation(result.prepared);
+    const snapshotId = `optimizer-${randomBytes(12).toString('hex')}`;
+    this.preparedOptimizerRequests.set(snapshotId, {
+      prepared: result.prepared,
+      draft,
+      sourceRevision,
+      consentGeneration,
+    });
+    this.optimizerState = {
+      ...baseState,
+      snapshotId,
+      previewBody: preview.body,
+      previewSha256: preview.sha256,
+      previewBytes: preview.utf8Bytes,
+    };
+    this.postAdviceMessage({
+      command: 'optimizePreviewResult',
+      ok: true,
+      snapshotId,
+      contentType: preview.contentType,
+      dataMode: preview.dataMode,
+      body: preview.body,
+      sha256: preview.sha256,
+      utf8Bytes: preview.utf8Bytes,
+    });
+  }
+
+  private async handleSendOptimizerMessage(message: Record<string, unknown>): Promise<void> {
+    if (!this.setting<boolean>('advice.optimizer.enabled', false)) {
+      this.discardPreparedOptimizer();
+      this.postAdviceMessage({ command: 'optimizeResult', error: I18n.t.popup.adviceEffectiveness.strictOutputRejected });
+      return;
+    }
+    const snapshotId = typeof message.snapshotId === 'string' ? message.snapshotId : '';
+    const stored = this.preparedOptimizerRequests.get(snapshotId);
+    if (
+      !stored ||
+      !this.onSendOptimizerInvocation ||
+      stored.consentGeneration !== this.optimizerConsentGeneration ||
+      message.draft !== stored.draft
+    ) {
+      this.postAdviceMessage({ command: 'optimizeResult', error: I18n.t.popup.adviceEffectiveness.strictOutputRejected });
+      return;
+    }
+    const result = await this.onSendOptimizerInvocation(
+      stored.prepared,
+      stored.sourceRevision,
+      stored.consentGeneration,
+    );
+    if (
+      this.preparedOptimizerRequests.get(snapshotId) !== stored ||
+      stored.consentGeneration !== this.optimizerConsentGeneration
+    ) {
+      this.postAdviceMessage({ command: 'optimizeResult', error: I18n.t.popup.adviceEffectiveness.strictOutputRejected });
+      return;
+    }
+    this.preparedOptimizerRequests.delete(snapshotId);
+    if (!result.ok) {
+      const error = I18n.t.popup.adviceEffectiveness.strictOutputRejected;
+      this.optimizerState = this.optimizerState
+        ? { ...this.optimizerState, error }
+        : null;
+      this.postAdviceMessage({ command: 'optimizeResult', error });
+      return;
+    }
+    this.optimizerState = this.optimizerState
+      ? {
+          draft: this.optimizerState.draft,
+          resolve: this.optimizerState.resolve,
+          distil: this.optimizerState.distil,
+          aesthetic: this.optimizerState.aesthetic,
+          prompt: result.value.prompt,
+          settings: result.value.settings,
+          adviceId: `advice-optimizer-${randomBytes(12).toString('hex')}`,
+        }
+      : null;
+    this.postAdviceMessage({
+      command: 'optimizeResult',
+      ...result.value,
+      adviceId: this.optimizerState?.adviceId,
+      recommendationId: OPTIMIZER_FEEDBACK_RECOMMENDATION_ID,
+    });
+  }
+
+  private discardPreparedOptimizer(): void {
+    this.optimizerConsentGeneration += 1;
+    this.preparedOptimizerRequests.clear();
+    if (this.optimizerState) {
+      const { draft, resolve, distil, aesthetic } = this.optimizerState;
+      this.optimizerState = { draft, resolve, distil, aesthetic };
+    }
+  }
+
+  show(tab?: string): void {
+    if (tab) {
+      this.currentTab = tab;
+      if (tab === 'settings' && this.currentProvider === 'compare') {
+        this.currentProvider = this.providerAvailability.claude ? 'claude' : 'codex';
+      }
+    }
     if (this.panel) {
       this.panel.reveal();
+      this.updateWebview();
       return;
     }
 
@@ -180,6 +1597,12 @@ export class UsageWebviewProvider {
 
     this.panel.onDidDispose(() => {
       this.panel = undefined;
+      for (const requestId of [...this.localDataClientActionRequests.keys()]) {
+        this.settleLocalDataClientAction(requestId, false);
+      }
+      this.clearPreparedAdviceSnapshots();
+      this.discardPreparedOptimizer();
+      this.onAiSurfaceClosed?.();
       // Force a fresh render into the next panel (the lastHtml guard must not
       // suppress the first paint after the panel was closed and reopened).
       this.lastHtml = '';
@@ -199,12 +1622,208 @@ export class UsageWebviewProvider {
         case 'getAdvice':
           vscode.commands.executeCommand('claudeCodeUsage.getAdvice');
           break;
+        case 'updateAdviceConsent':
+          await this.handleAdviceConsentMessage(message as Record<string, unknown>);
+          break;
+        case 'prepareAdviceSnapshot':
+          this.handlePrepareAdviceSnapshotMessage(message as Record<string, unknown>);
+          break;
+        case 'sendAdviceSnapshot':
+          await this.handleSendAdviceSnapshotMessage(message as Record<string, unknown>);
+          break;
+        case 'discardAdviceSnapshot': {
+          const provider = message.provider;
+          if (provider === 'claude' || provider === 'codex') {
+            this.clearPreparedAdviceSnapshots(provider);
+          }
+          break;
+        }
+        case 'recordAdviceFeedback':
+          await this.handleAdviceFeedbackMessage(message as Record<string, unknown>);
+          break;
+        case 'snoozeAdvice':
+          await this.handleAdviceSnoozeMessage(message as Record<string, unknown>);
+          break;
+        case 'clearAdviceLocalData':
+          await this.handleClearAdviceLocalDataMessage();
+          break;
+        case 'localDataClientReady':
+          this.onLocalDataClientReady?.();
+          break;
+        case 'requestLocalDataInventory': {
+          const summary = message.clientSummary as Partial<LocalDataClientSummary> | undefined;
+          const clientSummary: LocalDataClientSummary = {
+            uiPreferenceKeys: Number.isInteger(summary?.uiPreferenceKeys) &&
+              Number(summary?.uiPreferenceKeys) >= 0
+              ? Number(summary?.uiPreferenceKeys)
+              : 0,
+            webviewStateFields: Number.isInteger(summary?.webviewStateFields) &&
+              Number(summary?.webviewStateFields) >= 0
+              ? Number(summary?.webviewStateFields)
+              : 0,
+            sharingPreferenceKeys: Number.isInteger(summary?.sharingPreferenceKeys) &&
+              Number(summary?.sharingPreferenceKeys) >= 0
+              ? Number(summary?.sharingPreferenceKeys)
+              : 0,
+          };
+          try {
+            const inventory = await this.onRequestLocalDataInventory?.(clientSummary);
+            this.panel?.webview.postMessage({
+              command: 'localDataInventoryResult',
+              ok: inventory !== undefined,
+              inventory,
+            });
+          } catch {
+            this.panel?.webview.postMessage({
+              command: 'localDataInventoryResult',
+              ok: false,
+            });
+          }
+          break;
+        }
+        case 'runLocalDataAction': {
+          if (!isLocalDataAction(message.action) || !this.onRunLocalDataAction) {
+            this.panel?.webview.postMessage({
+              command: 'localDataActionResult',
+              result: { ok: false, message: 'Unsupported local-data action.' },
+            });
+            break;
+          }
+          const token = typeof message.quotaScopeToken === 'string'
+            ? message.quotaScopeToken
+            : undefined;
+          try {
+            const result = await this.onRunLocalDataAction(message.action, token);
+            this.panel?.webview.postMessage({
+              command: 'localDataActionResult',
+              result,
+            });
+          } catch {
+            this.panel?.webview.postMessage({
+              command: 'localDataActionResult',
+              result: { ok: false, message: 'The local-data action could not be completed.' },
+            });
+          }
+          break;
+        }
+        case 'localDataClientActionAck': {
+          if (typeof message.requestId === 'string') {
+            this.settleLocalDataClientAction(
+              message.requestId,
+              message.ok === true,
+            );
+          }
+          break;
+        }
         case 'exportHeatmap':
           vscode.commands.executeCommand('claudeCodeUsage.exportHeatmap');
           break;
         case 'publishHeatmap':
           vscode.commands.executeCommand('claudeCodeUsage.publishHeatmapToGitHub');
           break;
+        case 'previewCombinedHeatmap': {
+          if (!this.panel) {
+            break;
+          }
+          try {
+            const artifact = this.buildCombinedHeatmapArtifact(
+              message.range,
+              message.title,
+              message.palette,
+              message.customAccent,
+              message.intensityMode,
+            );
+            this.panel.webview.postMessage({
+              command: 'combinedHeatmapResult',
+              svg: artifact.svg,
+              markdown: artifact.markdown,
+              filename: artifact.filename,
+              hasData: artifact.hasData,
+            });
+          } catch (error) {
+            this.panel.webview.postMessage({
+              command: 'combinedHeatmapResult',
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+          break;
+        }
+        case 'exportCombinedHeatmap': {
+          const copy = combinedHeatmapUiCopy(I18n.getLocale());
+          let artifact: ReturnType<UsageWebviewProvider['buildCombinedHeatmapArtifact']>;
+          try {
+            artifact = this.buildCombinedHeatmapArtifact(
+              message.range,
+              message.title,
+              message.palette,
+              message.customAccent,
+              message.intensityMode,
+            );
+          } catch (error) {
+            vscode.window.showErrorMessage(`Combined heatmap export failed: ${error instanceof Error ? error.message : String(error)}`);
+            break;
+          }
+          if (!artifact.hasData) {
+            vscode.window.showWarningMessage(copy.noData);
+            break;
+          }
+          const uri = await vscode.window.showSaveDialog({
+            defaultUri: vscode.Uri.file(path.join(os.homedir(), artifact.filename)),
+            filters: { 'SVG image': ['svg'] },
+            saveLabel: copy.exportSvg.replace('…', ''),
+          });
+          if (!uri) {
+            break;
+          }
+          try {
+            await vscode.workspace.fs.writeFile(uri, Buffer.from(artifact.svg, 'utf8'));
+            vscode.window.showInformationMessage(`Combined activity SVG exported: ${path.basename(uri.fsPath)}`);
+          } catch (error) {
+            vscode.window.showErrorMessage(`Combined heatmap export failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+          break;
+        }
+        case 'copyCombinedHeatmapMarkdown': {
+          try {
+            const artifact = this.buildCombinedHeatmapArtifact(
+              message.range,
+              message.title,
+              message.palette,
+              message.customAccent,
+              message.intensityMode,
+            );
+            await vscode.env.clipboard.writeText(artifact.markdown);
+            this.panel?.webview.postMessage({ command: 'combinedHeatmapMarkdownCopied', ok: true });
+          } catch (error) {
+            this.panel?.webview.postMessage({
+              command: 'combinedHeatmapMarkdownCopied',
+              ok: false,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+          break;
+        }
+        case 'resetCombinedHeatmapPreferences': {
+          try {
+            if (this.onResetSharingPreferences) {
+              await this.onResetSharingPreferences();
+            } else {
+              await this.context.globalState.update('ccu.heatmapRepo', undefined);
+              await this.context.globalState.update('ccu.heatmapPath', undefined);
+              this.clearSharingRuntimeState();
+            }
+            this.panel?.webview.postMessage({
+              command: 'combinedHeatmapPreferencesReset',
+              ok: true,
+            });
+          } catch {
+            this.panel?.webview.postMessage({
+              command: 'combinedHeatmapPreferencesReset',
+              ok: false,
+            });
+          }
+          break;
+        }
         case 'buildShareCard': {
           // On-demand preview: build the SVG from the panel's config and send
           // it back for injection (no full re-render).
@@ -419,26 +2038,15 @@ export class UsageWebviewProvider {
           if (!this.panel) {
             break;
           }
-          const draft = String(message.draft || '');
-          const opts = {
-            resolve: !!message.resolve,
-            distil: !!message.distil,
-            aesthetic: !!message.aesthetic,
-          };
-          // Persist the inputs immediately so a refresh mid-request keeps them.
-          this.optimizerState = { draft, ...opts };
-          let result: { prompt?: string; settings?: string; error?: string };
-          if (this.onOptimize) {
-            result = await this.onOptimize(draft, opts);
-          } else {
-            result = { error: 'Optimizer is not available.' };
-          }
-          // Persist the result too, so re-rendering the webview (auto-refresh)
-          // restores it instead of wiping a prompt the user is still reading.
-          this.optimizerState = { draft, ...opts, ...result };
-          if (this.panel) {
-            this.panel.webview.postMessage({ command: 'optimizeResult', ...result });
-          }
+          await this.handlePrepareOptimizerMessage(message as Record<string, unknown>);
+          break;
+        }
+        case 'sendOptimizerRequest': {
+          await this.handleSendOptimizerMessage(message as Record<string, unknown>);
+          break;
+        }
+        case 'discardOptimizerRequest': {
+          this.discardPreparedOptimizer();
           break;
         }
         case 'getAttribution': {
@@ -559,6 +2167,7 @@ export class UsageWebviewProvider {
       codex: providerAvailability.codex,
       codexData: providerAvailability.codexData ?? providerAvailability.codex,
     };
+    this.scheduleAdviceComparisonProduction();
     if (!this.providerSelectionInitialized) {
       this.currentProvider = defaultDashboardProvider(
         providerAvailability.claude,
@@ -584,8 +2193,45 @@ export class UsageWebviewProvider {
   updateCodexProgress(progress: CodexRenderProgress): void {
     this.codexProgress = progress;
     if (this.panel && this.currentProvider === 'codex') {
-      this.updateWebview();
+      void this.panel.webview.postMessage({
+        command: 'codexIndexProgress',
+        text: this.codexProgressText(progress),
+      });
+    }
+  }
+
+  /**
+   * Receive privacy-reviewed provider contracts from the extension host. This
+   * deliberately does not trigger a render: syncProviderUi immediately follows
+   * it with updateProviderData, so one data refresh still produces one paint.
+   */
+  updateAdviceEffectivenessData(states: AdviceEffectivenessProviderStates): void {
+    for (const provider of ['claude', 'codex'] as const) {
+      const previous = this.adviceEffectivenessStates[provider];
+      const next = states[provider];
+      if (!previous || !next) {
+        this.clearPreparedAdviceSnapshots(provider);
+        continue;
+      }
+      const unchanged =
+        this.adviceSourceRevision(previous) === this.adviceSourceRevision(next);
+      if (!unchanged) {
+        this.clearPreparedAdviceSnapshots(provider);
+        continue;
+      }
+      // Keep a strictly parsed remote recommendation across ordinary refreshes
+      // of the same materialized source revision. Evidence remains host-owned.
+      if (previous.contract.provenance.generatedBy.kind === 'remote-model') {
+        next.contract = previous.contract;
+      }
     }
+    this.adviceEffectivenessStates = states;
+  }
+
+  invalidatePreparedAiRequests(): void {
+    this.adviceConsentGeneration += 1;
+    this.clearPreparedAdviceSnapshots();
+    this.discardPreparedOptimizer();
   }
 
   setLoading(loading: boolean): void {
@@ -671,6 +2317,11 @@ export class UsageWebviewProvider {
   }
 
   private getWebviewContent(): string {
+    // Data/privacy controls must remain reachable even when neither provider
+    // has logs yet or a refresh is in progress.
+    if (this.currentTab === 'settings' && this.currentProvider !== 'compare') {
+      return this.getMainContent();
+    }
     if (this.isLoading) {
       return this.getLoadingContent();
     }
@@ -703,7 +2354,7 @@ export class UsageWebviewProvider {
       </head>
       <body>
         <div class="container">
-          <div class="loading">
+          <div class="loading" role="status" aria-live="polite">
             <div class="spinner"></div>
             <p>${I18n.t.statusBar.loading}</p>
           </div>
@@ -725,7 +2376,7 @@ export class UsageWebviewProvider {
       </head>
       <body>
         <div class="container">
-          <div class="error">
+          <div class="error" role="alert">
             <h2>${I18n.t.statusBar.error}</h2>
             <p>${this.error}</p>
             <button onclick="refresh()">${I18n.t.popup.refresh}</button>
@@ -749,7 +2400,7 @@ export class UsageWebviewProvider {
       </head>
       <body>
         <div class="container">
-          <div class="no-data">
+          <div class="no-data" role="status" aria-live="polite">
             <h2>${I18n.t.statusBar.noData}</h2>
             <p>${I18n.t.popup.noDataMessage}</p>
             <div class="actions">
@@ -786,6 +2437,135 @@ export class UsageWebviewProvider {
     return html + '</nav>';
   }
 
+  private buildCombinedHeatmapArtifact(
+    rangeInput: unknown,
+    titleInput: unknown,
+    paletteInput: unknown = 'academicViolet',
+    customAccentInput: unknown = '#4f2f87',
+    intensityModeInput: unknown = 'quantile',
+  ): {
+    range: CombinedHeatmapRange;
+    title: string;
+    endDateISO: string;
+    filename: string;
+    markdown: string;
+    svg: string;
+    hasData: boolean;
+  } {
+    const copy = combinedHeatmapUiCopy(I18n.getLocale());
+    const range = normalizeCombinedHeatmapRange(rangeInput);
+    const title = sanitizeCombinedHeatmapTitle(titleInput, copy.defaultTitle);
+    const palette = normalizeCombinedHeatmapPalette(paletteInput);
+    const customAccent = normalizeCombinedHeatmapAccent(customAccentInput);
+    const intensityMode = normalizeCombinedHeatmapIntensityMode(intensityModeInput);
+    const timeZone = I18n.getTimezone();
+    const endDateISO = dayKeyInZone(new Date(), timeZone);
+    if (!endDateISO) {
+      throw new Error('Could not resolve the configured timezone date.');
+    }
+    const claudeDaily = ClaudeDataLoader.getDailyUsageMap(this.allRecords ?? [], timeZone);
+    const daily = mergeCombinedDailyUsage(
+      claudeDailyPointsFromUsage(claudeDaily),
+      codexDailyPointsFromUsage(this.codexView?.daily ?? []),
+    );
+    const selected = selectCombinedHeatmapWindow(daily, range, endDateISO);
+    const filename = combinedHeatmapFilename(range, endDateISO);
+    return {
+      range,
+      title,
+      endDateISO,
+      filename,
+      markdown: combinedHeatmapMarkdown(filename, title),
+      svg: renderCombinedHeatmapSvg(daily, {
+        range,
+        endDateISO,
+        title,
+        palette,
+        customAccent,
+        intensityMode,
+        labels: {
+          combined: copy.combinedLabel,
+          processedTokens: copy.processedTokensLabel,
+          footerNote: copy.svgFooterNote,
+        },
+      }),
+      hasData: selected.totals.combinedProcessed > 0,
+    };
+  }
+
+  private renderCombinedHeatmapPanel(): string {
+    const copy = combinedHeatmapUiCopy(I18n.getLocale());
+    const artifact = this.buildCombinedHeatmapArtifact('year', copy.defaultTitle);
+    const preview = artifact.hasData
+      ? artifact.svg
+      : '<p class="table-hint">' + this.escapeHtml(copy.noData) + '</p>';
+    const paletteChoice = (
+      value: string,
+      label: string,
+      colors: string[],
+      checked = false,
+    ): string => '<label class="combined-palette-choice">' +
+      '<input type="radio" name="combinedHeatmapPalette" value="' + value + '"' + (checked ? ' checked' : '') +
+      ' onchange="toggleCombinedCustomAccent()">' +
+      '<span class="combined-palette-swatch" aria-hidden="true">' +
+      colors.map((color) => '<i style="background:' + color + '"></i>').join('') + '</span>' +
+      '<span>' + this.escapeHtml(label) + '</span></label>';
+    const palettes =
+      paletteChoice('academicViolet', copy.academicViolet, ['#eee8f8', '#bca5e6', '#8668c7', '#4f2f87'], true) +
+      paletteChoice('claudeOrange', copy.claudeOrange, ['#fff1e8', '#fadcc9', '#e07d4f', '#c85a2b']) +
+      paletteChoice('codexBlue', copy.codexBlue, ['#eff6ff', '#93c5fd', '#3b82f6', '#1d4ed8']) +
+      paletteChoice('githubGreen', copy.githubGreen, ['#dafbe1', '#6fdd8b', '#2da44e', '#116329']) +
+      paletteChoice('custom', copy.customPalette, ['#eee8f8', '#bca5e6', '#8668c7', '#4f2f87']);
+    return '<section class="heatmap-panel combined-heatmap-panel" aria-labelledby="combinedHeatmapHeading">' +
+      '<header class="combined-share-header"><div>' +
+      '<span class="combined-share-eyebrow">' + this.escapeHtml(copy.eyebrow) + '</span>' +
+      '<h2 id="combinedHeatmapHeading">' + this.escapeHtml(copy.panelTitle) + '</h2>' +
+      '<p>' + this.escapeHtml(copy.description) + '</p></div>' +
+      '<span class="combined-private-badge">◆ ' + this.escapeHtml(copy.privateBadge) + '</span></header>' +
+      '<div class="combined-share-layout">' +
+      '<div class="combined-preview-column">' +
+      '<div class="combined-preview-toolbar"><strong>' + this.escapeHtml(copy.previewLabel) + '</strong>' +
+      '<span id="combinedHeatmapStatus" role="status" aria-live="polite"></span></div>' +
+      '<div id="combinedHeatmapPreview" class="heatmap-svg combined-heatmap-preview" role="region" tabindex="0" aria-label="' + this.escapeHtml(copy.previewLabel) + '">' + preview + '</div>' +
+      '<p class="combined-activity-disclaimer">' + this.escapeHtml(copy.activityDisclaimer) + '</p>' +
+      '</div>' +
+      '<aside class="combined-config-card" aria-label="' + this.escapeHtml(copy.settingsLabel) + '">' +
+      '<h3>' + this.escapeHtml(copy.settingsLabel) + '</h3>' +
+      '<div class="combined-heatmap-controls">' +
+      '<label class="sc-field" for="combinedHeatmapTitle"><span>' + this.escapeHtml(copy.titleLabel) + '</span>' +
+      '<input type="text" id="combinedHeatmapTitle" maxlength="80" value="' + this.escapeHtml(artifact.title) + '" data-default-value="' + this.escapeHtml(artifact.title) + '"></label>' +
+      '<label class="sc-field" for="combinedHeatmapRange"><span>' + this.escapeHtml(copy.rangeLabel) + '</span>' +
+      '<select id="combinedHeatmapRange" data-default-value="year">' +
+      '<option value="30d">' + this.escapeHtml(copy.last30) + '</option>' +
+      '<option value="90d">' + this.escapeHtml(copy.last90) + '</option>' +
+      '<option value="year" selected>' + this.escapeHtml(copy.year) + '</option>' +
+      '</select></label>' +
+      '<label class="sc-field" for="combinedHeatmapIntensityMode"><span>' + this.escapeHtml(copy.intensityLabel) + '</span>' +
+      '<select id="combinedHeatmapIntensityMode" data-default-value="quantile">' +
+      '<option value="quantile" selected>' + this.escapeHtml(copy.intensityQuantile) + '</option>' +
+      '<option value="logarithmic">' + this.escapeHtml(copy.intensityLogarithmic) + '</option>' +
+      '<option value="linear">' + this.escapeHtml(copy.intensityLinear) + '</option>' +
+      '</select></label></div>' +
+      '<fieldset class="combined-palette-fieldset"><legend>' + this.escapeHtml(copy.paletteLabel) + '</legend>' +
+      '<div class="combined-palette-options">' + palettes + '</div>' +
+      '<label class="combined-custom-accent" for="combinedHeatmapCustomAccent"><span>' + this.escapeHtml(copy.customAccent) + '</span>' +
+      '<input type="color" id="combinedHeatmapCustomAccent" value="#4f2f87" disabled></label></fieldset>' +
+      '<label class="sc-check combined-privacy-toggle"><input type="checkbox" id="combinedHeatmapPrivacy" checked onchange="toggleCombinedHeatmapPrivacy(true)"> ' +
+      this.escapeHtml(copy.privacyToggle) + '</label>' +
+      '<div id="combinedHeatmapPrivacyPreview" class="combined-privacy-preview" role="note">' +
+      '<p>✓ ' + this.escapeHtml(copy.privacyIncludes) + '</p>' +
+      '<p>✓ ' + this.escapeHtml(copy.privacyExcludes) + '</p></div>' +
+      '<div class="share-actions combined-share-actions">' +
+      '<button class="btn-primary btn-small" onclick="generateCombinedHeatmapPreview()">' + this.escapeHtml(copy.updatePreview) + '</button>' +
+      '<button class="btn-secondary btn-small" onclick="exportCombinedHeatmap()">' + this.escapeHtml(copy.exportSvg) + '</button>' +
+      '<button class="btn-secondary btn-small" onclick="copyCombinedHeatmapMarkdown()">' + this.escapeHtml(copy.copyMarkdown) + '</button>' +
+      '<button class="btn-secondary btn-small" onclick="resetCombinedHeatmapPreferences()">' + this.escapeHtml(copy.resetSharing) + '</button></div>' +
+      '</aside></div>' +
+      '<details class="combined-output-panel"><summary>' + this.escapeHtml(copy.markdownLabel) + '</summary>' +
+      '<textarea id="combinedHeatmapMarkdown" class="combined-markdown" rows="2" readonly aria-label="' + this.escapeHtml(copy.markdownLabel) + '">' + this.escapeHtml(artifact.markdown) + '</textarea>' +
+      '</details></section>';
+  }
+
   private renderCodexCompare(): string {
     const claude = this.allTimeData;
     const updatedAt = Date.now();
@@ -793,14 +2573,12 @@ export class UsageWebviewProvider {
       I18n.getLocale(),
       I18n.getTimezone(),
     );
-    const codexTotals = (this.codexView?.projects ?? []).reduce(
-      (total, project) => ({
-        input: total.input + project.scope.total.input,
-        output: total.output + project.scope.total.output,
-        cache: total.cache + project.scope.total.cachedInput,
-      }),
-      { input: 0, output: 0, cache: 0 },
-    );
+    const codexAllTime = this.codexView?.allTime.total;
+    const codexTotals = {
+      input: codexAllTime?.input ?? 0,
+      output: codexAllTime?.output ?? 0,
+      cache: codexAllTime?.cachedInput ?? 0,
+    };
     const copy = I18n.t.providers.codex;
     const card = (
       label: string,
@@ -816,7 +2594,11 @@ export class UsageWebviewProvider {
       '<span><span class="model-stat-label">' + this.escapeHtml(copy.cachedInput) + '</span><strong>' + I18n.formatNumber(cache) + '</strong></span>' +
       '<span><span class="model-stat-label">' + this.escapeHtml(copy.output) + '</span><strong>' + I18n.formatNumber(output) + '</strong></span>' +
       '</div></article>';
-    return '<section class="usage-summary">' +
+    const sharingWorkspace = this.setting<boolean>('enableShareCard', true)
+      ? this.renderCombinedHeatmapPanel()
+      : '';
+    return sharingWorkspace +
+      '<section class="usage-summary">' +
       '<p class="model-details"><strong>' + this.escapeHtml(copy.indexedAllTime) + '</strong> · ' +
       this.escapeHtml(copy.updatedAt) + ': ' + this.escapeHtml(formatters.formatDateTime(updatedAt)) + '</p>' +
       '<div class="summary-grid">' +
@@ -876,7 +2658,7 @@ export class UsageWebviewProvider {
     // Keep the navigation familiar across providers. Codex still renders the
     // provider-native "Recent task" heading and aggregation inside this tab.
     const today = I18n.t.popup.today;
-    const thisMonth = provider === 'codex' ? codexCopy.last30Days : I18n.t.popup.thisMonth;
+    const thisMonth = provider === 'codex' ? codexCopy.last30Days : I18n.t.popup.last30days;
     const allTime = provider === 'codex' ? codexCopy.allTime : I18n.t.popup.allTime;
     const sessions = provider === 'codex' ? codexCopy.sessions : I18n.t.popup.sessions;
     const projects = provider === 'codex' ? codexCopy.projects : I18n.t.popup.projects;
@@ -895,18 +2677,35 @@ export class UsageWebviewProvider {
     const workflowsActive = this.currentTab === 'workflows' ? 'active' : '';
     const settingsActive = this.currentTab === 'settings' ? 'active' : '';
 
+    const dashboardTab = (name: string, label: string, active: string): string => {
+      const selected = active === 'active';
+      return '<button id="tab-' + name + '" class="tab ' + active +
+        '" role="tab" data-dashboard-tab="' + name + '" aria-controls="' + name +
+        '" aria-selected="' + selected + '" tabindex="' + (selected ? '0' : '-1') +
+        '" onclick="showTab(\'' + name + '\')">' + this.escapeHtml(label) + '</button>';
+    };
+    const dashboardPanel = (name: string, active: string, content: string): string =>
+      '<div id="' + name + '" class="tab-content ' + active + '" role="tabpanel" ' +
+      'aria-labelledby="tab-' + name + '"' + (active === 'active' ? '' : ' hidden') + '>' +
+      content + '</div>';
+
     // The Content tab is hidden when content analysis is disabled via
     // claudeCodeUsage.enableContentAnalysis (the analyser returned null).
     const contentEnabled = provider === 'codex'
       ? Boolean(this.codexView && this.setting<boolean>('codex.optimization.enabled', true))
       : this.contentAnalysis !== null;
     const contentTabButton = contentEnabled
-      ? '<button id="tab-content" class="tab ' + contentActive +
-        '" onclick="showTab(\'content\')">' + contentTab + '</button>'
+      ? dashboardTab('content', contentTab, contentActive)
       : '';
     const contentTabContent = contentEnabled
-      ? '<div id="content" class="tab-content ' + contentActive + '">' + this.renderContentData(provider) +
-        (provider === 'claude' ? this.renderCacheWarmth() + this.renderInsights() + this.renderCostliestMessages() : '') + '</div>'
+      ? dashboardPanel(
+          'content',
+          contentActive,
+          this.renderContentData(provider) +
+            (provider === 'claude'
+              ? this.renderCacheWarmth() + this.renderInsights() + this.renderCostliestMessages()
+              : ''),
+        )
       : '';
 
     return (
@@ -949,123 +2748,31 @@ export class UsageWebviewProvider {
       `<div id="provider-panel" role="tabpanel" aria-labelledby="provider-tab-${this.currentProvider}">` +
       this.renderQuotaBanner(provider) +
       `
-          <div class="tabs">
-            <button id="tab-today" class="tab ` +
-      todayActive +
-      `" onclick="showTab('today')">` +
-      today +
-      `</button>
-            <button id="tab-month" class="tab ` +
-      monthActive +
-      `" onclick="showTab('month')">` +
-      thisMonth +
-      `</button>
-            <button id="tab-all" class="tab ` +
-      allActive +
-      `" onclick="showTab('all')">` +
-      allTime +
-      `</button>
-            <button id="tab-sessions" class="tab ` +
-      sessionsActive +
-      `" onclick="showTab('sessions')">` +
-      sessions +
-      `</button>
-            <button id="tab-projects" class="tab ` +
-      projectsActive +
-      `" onclick="showTab('projects')">` +
-      projects +
-      `</button>
-            ` +
+          <div class="tabs" role="tablist" aria-label="${this.escapeHtml(title)}">
+            ` + dashboardTab('today', today, todayActive) +
+      dashboardTab('month', thisMonth, monthActive) +
+      dashboardTab('all', allTime, allActive) +
+      dashboardTab('sessions', sessions, sessionsActive) +
+      dashboardTab('projects', projects, projectsActive) +
       contentTabButton +
-      `
-            ` +
-      (provider === 'claude' ? `<button id="tab-branches" class="tab ` +
-      branchesActive +
-      `" onclick="showTab('branches')">` +
-      branchesTab +
-      `</button>
-            <button id="tab-workflows" class="tab ` +
-      workflowsActive +
-      `" onclick="showTab('workflows')">` +
-      workflowsTab +
-      `</button>` : '') +
-      `
-            <button id="tab-settings" class="tab ` +
-      settingsActive +
-      `" onclick="showTab('settings')">` +
-      settingsTab +
-      `</button>
-          </div>
-
-          <div id="today" class="tab-content ` +
-      todayActive +
-      `">
-            ` +
-      this.renderTodayData(provider) +
-      `
-          </div>
-
-          <div id="month" class="tab-content ` +
-      monthActive +
-      `">
-            ` +
-      this.renderMonthData(provider) +
-      `
-          </div>
-
-          <div id="all" class="tab-content ` +
-      allActive +
-      `">
-            ` +
-      this.renderAllTimeData(provider) +
-      `
-          </div>
-
-          <div id="sessions" class="tab-content ` +
-      sessionsActive +
-      `">
-            ` +
-      this.renderSessionData(provider) +
-      `
-          </div>
-
-          <div id="projects" class="tab-content ` +
-      projectsActive +
-      `">
-            ` +
-      this.renderProjectData(provider) +
-      `
+      (provider === 'claude'
+        ? dashboardTab('branches', branchesTab, branchesActive) +
+          dashboardTab('workflows', workflowsTab, workflowsActive)
+        : '') +
+      dashboardTab('settings', settingsTab, settingsActive) + `
           </div>
 
-          ` +
+          ` + dashboardPanel('today', todayActive, this.renderTodayData(provider)) +
+      dashboardPanel('month', monthActive, this.renderMonthData(provider)) +
+      dashboardPanel('all', allActive, this.renderAllTimeData(provider)) +
+      dashboardPanel('sessions', sessionsActive, this.renderSessionData(provider)) +
+      dashboardPanel('projects', projectsActive, this.renderProjectData(provider)) +
       contentTabContent +
-      `
-
-          ` +
-      (provider === 'claude' ? `<div id="branches" class="tab-content ` +
-      branchesActive +
-      `">
-            ` +
-      this.renderBranchData() +
-      `
-          </div>
-
-          <div id="workflows" class="tab-content ` +
-      workflowsActive +
-      `">
-            ` +
-      this.renderWorkflowData() +
-      `
-          </div>` : '') +
-      `
-
-          <div id="settings" class="tab-content ` +
-      settingsActive +
-      `">
-            ` +
-      this.renderSettingsPanel(provider) +
-      `
-          </div>
+      (provider === 'claude'
+        ? dashboardPanel('branches', branchesActive, this.renderBranchData()) +
+          dashboardPanel('workflows', workflowsActive, this.renderWorkflowData())
+        : '') +
+      dashboardPanel('settings', settingsActive, this.renderSettingsPanel(provider)) + `
         </div>
         </div>
         <script>` +
@@ -1079,9 +2786,9 @@ export class UsageWebviewProvider {
 
   /**
    * The ⚙ Settings tab: every setting, grouped, editable in place. Core
-   * settings (language / dataDirectory / advice.apiKey) still write to VS Code
-   * config; the rest write to the dashboard-managed store. Setting labels/help
-   * are English (technical); group headers + chrome are localised.
+   * settings (language / dataDirectory) still write to VS Code config; secrets
+   * go to SecretStorage and the rest use the dashboard-managed store. Setting
+   * labels/help are English (technical); group headers + chrome are localised.
    */
   private renderSettingsPanel(provider: SettingProvider): string {
     const t = I18n.t.popup;
@@ -1119,6 +2826,41 @@ export class UsageWebviewProvider {
     return html;
   }
 
+  private renderLocalDataControls(): string {
+    const copy = localDataUiCopy(I18n.getLocale());
+    const esc = (value: string): string => this.escapeHtml(value);
+    return (
+      '<section class="settings-group local-data-controls" aria-labelledby="localDataTitle">' +
+      '<h3 id="localDataTitle">' + esc(copy.title) + '</h3>' +
+      '<p class="table-hint">' + esc(copy.intro) + '</p>' +
+      '<div class="local-data-heading"><h4>' + esc(copy.inventory) + '</h4>' +
+      '<button class="btn-secondary btn-small" type="button" onclick="requestLocalDataInventory()">' +
+      esc(copy.refresh) + '</button></div>' +
+      '<div class="table-wrap local-data-table-wrap" role="region" tabindex="0" aria-label="' +
+      esc(copy.inventory) + '"><table class="data-table local-data-table">' +
+      '<thead><tr><th>' + esc(copy.category) + '</th><th>' + esc(copy.location) + '</th>' +
+      '<th>' + esc(copy.schema) + '</th><th>' + esc(copy.sizeCount) + '</th>' +
+      '<th>' + esc(copy.dateRange) + '</th><th>' + esc(copy.network) + '</th>' +
+      '<th>' + esc(copy.clearability) + '</th></tr></thead>' +
+      '<tbody id="localDataInventoryBody"><tr><td colspan="7" class="table-hint">' +
+      esc(copy.loading) + '</td></tr></tbody></table></div>' +
+      '<p id="localDataExclusions" class="table-hint"></p>' +
+      '<div class="local-data-heading"><h4>' + esc(copy.actions) + '</h4></div>' +
+      '<div class="local-data-actions" role="group" aria-label="' + esc(copy.actions) + '">' +
+      '<button class="btn-secondary btn-small" type="button" onclick="runLocalDataAction(\'rebuild-codex-index\')">' + esc(copy.rebuildIndex) + '</button>' +
+      '<label class="local-data-scope-label" for="localDataQuotaScope">' + esc(copy.quotaScope) + '</label>' +
+      '<select id="localDataQuotaScope" aria-label="' + esc(copy.quotaScope) + '"></select>' +
+      '<button class="btn-secondary btn-small" type="button" onclick="runLocalDataAction(\'clear-quota-history\')">' + esc(copy.clearQuota) + '</button>' +
+      '<button class="btn-secondary btn-small" type="button" onclick="runLocalDataAction(\'clear-advice-data\')">' + esc(copy.clearAdvice) + '</button>' +
+      '<button class="btn-secondary btn-small" type="button" onclick="runLocalDataAction(\'reset-ui-state\')">' + esc(copy.resetUi) + '</button>' +
+      '<button class="btn-secondary btn-small" type="button" onclick="runLocalDataAction(\'reset-sharing-preferences\')">' + esc(copy.resetSharing) + '</button>' +
+      '<button class="btn-secondary btn-small" type="button" onclick="runLocalDataAction(\'clear-byok-secret\')">' + esc(copy.clearByok) + '</button>' +
+      '<button class="btn-secondary btn-small local-data-danger" type="button" onclick="runLocalDataAction(\'clear-all-derived-data\')">' + esc(copy.clearAll) + '</button>' +
+      '</div><p id="localDataActionStatus" class="table-hint" role="status" aria-live="polite"></p>' +
+      '</section>'
+    );
+  }
+
   /** One row in the settings panel: label + help + the right input control. The
    * label / help follow the plugin language (I18n.settingText), falling back to
    * the catalog English for the English UI. */
@@ -1190,6 +2932,9 @@ export class UsageWebviewProvider {
         '" value="' +
         esc(String(it.value)) +
         '"' +
+        (it.secret
+          ? ' autocomplete="new-password" placeholder="' + (it.configured ? '••••••••' : '') + '"'
+          : '') +
         onCh('string') +
         '>';
     }
@@ -1244,13 +2989,20 @@ export class UsageWebviewProvider {
               ? copy.unlimited
               : limit.state === 'missing'
                 ? copy.limitMissing
-                : `${I18n.formatNumber(limit.usedPercent ?? 0)}% ${copy.used}`;
+                : `${I18n.formatNumber(limit.usedPercent ?? 0)}% ${copy.used} · ` +
+                  `${I18n.formatNumber(limit.remainingPercent ?? Math.max(0, 100 - (limit.usedPercent ?? 0)))}% ${copy.remaining}`;
             const reset = limit.resetsAt && limit.state === 'current'
               ? '<div class="model-details">' + this.escapeHtml(copy.resets) + ': ' +
-                this.escapeHtml(formatters.formatDateTime(limit.resetsAt)) + '</div>'
+                this.escapeHtml(formatters.formatDateTime(limit.resetsAt)) + ' · ' +
+                this.escapeHtml(formatters.formatRelativeTime(limit.resetsAt, Date.now())) + '</div>'
+              : '';
+            const observed = limit.observedAt
+              ? '<div class="model-details">' + this.escapeHtml(copy.lastObserved) + ': ' +
+                this.escapeHtml(formatters.formatDateTime(limit.observedAt)) + ' · ' +
+                this.escapeHtml(copy.localLogNotLive) + '</div>'
               : '';
             return '<div class="summary-item"><div class="label">' + this.escapeHtml(label) +
-              '</div><div class="value">' + this.escapeHtml(value) + '</div>' + reset + '</div>';
+              '</div><div class="value">' + this.escapeHtml(value) + '</div>' + reset + observed + '</div>';
           }).join('') + '</div></div>'
         : '';
       const qualityFlags = view.qualityFlags.length > 0
@@ -1279,7 +3031,25 @@ export class UsageWebviewProvider {
       return '<div class="no-data"><p>' + I18n.t.popup.noDataMessage + '</p></div>';
     }
 
-    const todaySummary = this.renderUsageData(this.todayData, provider) + this.renderTodayInsights(provider);
+    const todayHasActivity = this.todayData.messageCount > 0 ||
+      this.todayData.totalInputTokens > 0 ||
+      this.todayData.totalOutputTokens > 0 ||
+      this.todayData.totalCacheCreationTokens > 0 ||
+      this.todayData.totalCacheReadTokens > 0;
+    const latestActivityDate = this.dailyDataForMonth.reduce<string | undefined>(
+      (latest, row) => latest === undefined || row.date > latest ? row.date : latest,
+      undefined,
+    );
+    const emptyRangeHint = todayHasActivity
+      ? ''
+      : '<p class="table-hint range-empty-hint"><strong>' +
+        this.escapeHtml(I18n.t.popup.today) + ':</strong> 0' +
+        (latestActivityDate
+          ? ' · ' + this.escapeHtml(I18n.t.popup.lastActive) + ': ' +
+            this.escapeHtml(this.formatDate(latestActivityDate))
+          : '') + '</p>';
+    const todaySummary = emptyRangeHint + this.renderUsageData(this.todayData, provider) +
+      this.renderTodayInsights(provider);
 
     let hourlyBreakdown = '';
     if (this.hourlyDataForToday.length > 0) {
@@ -1389,9 +3159,22 @@ export class UsageWebviewProvider {
   }
 
   private renderCodexTodayHourly(view: CodexUsageView): string {
-    const rows = view.todayHourly;
-    const coverage = view.todayCoverage;
-    if (rows.length === 0 && coverage.complete) {
+    return this.renderCodexHourlyBreakdown(
+      view.todayHourly,
+      view.todayCoverage,
+    );
+  }
+
+  private renderCodexHourlyBreakdown(
+    rows: CodexHourlyUsageView[],
+    coverage: {
+      indexedFiles: number;
+      totalFiles: number;
+      complete: boolean;
+    },
+    day?: string,
+  ): string {
+    if (rows.length === 0 && coverage.complete && !day) {
       return '';
     }
     const copy = I18n.t.providers.codex;
@@ -1409,10 +3192,10 @@ export class UsageWebviewProvider {
       '<button class="chart-tab" data-metric="messages">' + this.escapeHtml(copy.threads) + '</button>' +
       '</div>';
     const chart = rows.length > 0
-      ? '<div class="chart-content" id="codexTodayHourlyChart">' +
+      ? '<div class="chart-content"' + (day ? '' : ' id="codexTodayHourlyChart"') + '>' +
         this.renderCodexHourlyChart(rows) + '</div>' +
         this.renderCompositionChart(
-          rows.map((row) => ({ label: row.hour, data: row.total })),
+          rows.map((row) => ({ label: row.label, data: row.total })),
           'codex',
         )
       : '<div class="no-chart-data">' + this.escapeHtml(copy.noDailyData) + '</div>';
@@ -1425,7 +3208,7 @@ export class UsageWebviewProvider {
         '<th>' + this.escapeHtml(copy.output) + '</th><th>' + this.escapeHtml(copy.reasoning) + '</th>' +
         '<th>' + this.escapeHtml(copy.threads) + '</th></tr></thead><tbody>' +
         rows.map((row) =>
-          '<tr><td class="date-cell">' + this.escapeHtml(row.hour) + '</td>' +
+          '<tr><td class="date-cell">' + this.escapeHtml(row.label) + '</td>' +
           '<td class="cost-cell" title="' + this.escapeHtml(this.codexCostHelp(row.apiEquivalent)) + '">' +
           (row.apiEquivalent.pricedTokens > 0 ? I18n.formatCurrency(row.apiEquivalent.equivalentUsd) : '—') + '</td>' +
           '<td class="number-cell">' + I18n.formatNumber(row.total.processed) + '</td>' +
@@ -1437,8 +3220,15 @@ export class UsageWebviewProvider {
           '<td class="number-cell">' + I18n.formatNumber(row.threads) + '</td></tr>',
         ).join('') + '</tbody></table></div>'
       : '';
-    return '<div class="daily-breakdown" data-codex-time-series data-codex-today-hourly>' +
-      '<h3>' + this.escapeHtml(I18n.t.popup.hourlyBreakdown) + '</h3>' + partial + tabs + chart + table + '</div>';
+    const heading = day
+      ? '<h4>' + this.escapeHtml(this.formatDate(day)) + ' · ' +
+        this.escapeHtml(I18n.t.popup.hourlyBreakdown) + '</h4>'
+      : '<h3>' + this.escapeHtml(I18n.t.popup.hourlyBreakdown) + '</h3>';
+    return '<div class="' + (day ? 'hourly-breakdown' : 'daily-breakdown') +
+      '" data-codex-time-series' + (day
+        ? ' data-codex-materialized-hours="true" data-date="' + this.escapeHtml(day) + '"'
+        : ' data-codex-today-hourly') + '>' +
+      heading + partial + tabs + chart + table + '</div>';
   }
 
   /** Opt-in (showEfficiency) efficiency chips appended to a usage summary:
@@ -1490,7 +3280,10 @@ export class UsageWebviewProvider {
               totalBytes: coverage.totalBytes,
             }
           : null;
-    const details = progress ? ' · ' + this.renderCodexProgressText(progress) : '';
+    const details = progress
+      ? ' · <span data-codex-index-progress-text>' +
+        this.renderCodexProgressText(progress) + '</span>'
+      : '';
     const subtotal = indexedSubtotal
       ? '<strong>' + this.escapeHtml(copy.indexedSubtotal) + '</strong> · '
       : '';
@@ -1504,14 +3297,18 @@ export class UsageWebviewProvider {
       ? copy.indexingInProgress
       : copy.noRecentTask;
     const progress = this.codexLoading && this.codexProgress
-      ? '<p class="model-details">' +
-        this.renderCodexProgressText(this.codexProgress) + '</p>'
+      ? '<p class="model-details"><span data-codex-index-progress-text>' +
+        this.renderCodexProgressText(this.codexProgress) + '</span></p>'
       : '';
     return '<div class="no-data"><p>' + this.escapeHtml(message) + '</p>' +
       progress + '</div>';
   }
 
   private renderCodexProgressText(progress: CodexRenderProgress): string {
+    return this.escapeHtml(this.codexProgressText(progress));
+  }
+
+  private codexProgressText(progress: CodexRenderProgress): string {
     const copy = I18n.t.providers.codex;
     const exactCount = new Intl.NumberFormat(I18n.getLocale(), {
       maximumFractionDigits: 0,
@@ -1528,13 +3325,16 @@ export class UsageWebviewProvider {
       I18n.getLocale(),
       I18n.getTimezone(),
     );
-    return this.escapeHtml(copy.indexedLogEntries) + ': ' +
+    const reason = progress.reason
+      ? copy.indexingReasons[progress.reason] + ' · '
+      : '';
+    return reason + copy.indexedLogEntries + ': ' +
       exactCount.format(progress.scannedFiles) + '/' +
       exactCount.format(progress.totalFiles) +
       (progress.totalFiles > 0 ? ' (' + completedPercent + '%)' : '') + ' · ' +
-      this.escapeHtml(copy.indexedStorage) + ': ' +
-      this.escapeHtml(formatters.formatBytes(progress.indexedBytes)) + '/' +
-      this.escapeHtml(formatters.formatBytes(progress.totalBytes));
+      copy.indexedStorage + ': ' +
+      formatters.formatBytes(progress.indexedBytes) + '/' +
+      formatters.formatBytes(progress.totalBytes);
   }
 
   private renderUsageData(
@@ -1565,10 +3365,11 @@ export class UsageWebviewProvider {
         equivalentRows,
         scope.total.processed,
       );
-      const pricingCoverage = new Intl.NumberFormat(I18n.getLocale(), {
+      const pricingCoverageFormatter = new Intl.NumberFormat(I18n.getLocale(), {
         style: 'percent',
         maximumFractionDigits: 0,
-      }).format(equivalent.pricingCoverage);
+      });
+      const pricingCoverage = pricingCoverageFormatter.format(equivalent.pricingCoverage);
       const equivalentHelp = copy.apiEquivalentCostHelp.replace(
         '{coverage}',
         pricingCoverage,
@@ -1588,7 +3389,9 @@ export class UsageWebviewProvider {
         '<span class="legend-item"><span class="legend-dot ' + className + '"></span>' +
         this.escapeHtml(label) + ' ' + I18n.formatNumber(value) + '</span>';
       const compositionHtml = '<div class="cost-composition"><div class="cost-comp-head">' +
-        this.escapeHtml(copy.tokenComposition) + '</div><div class="cost-comp-bar">' +
+        '<span>' + this.escapeHtml(copy.tokenComposition) + '</span>' +
+        '<strong>' + this.escapeHtml(copy.fresh) + ' ' +
+        I18n.formatNumber(composition.uncachedUsage) + '</strong></div><div class="cost-comp-bar">' +
         '<div class="cost-comp-seg seg-input" style="width:' + width(composition.freshInput) + '"></div>' +
         '<div class="cost-comp-seg seg-cache-read" style="width:' + width(composition.cachedInput) + '"></div>' +
         '<div class="cost-comp-seg seg-output" style="width:' + width(composition.output) + '"></div>' +
@@ -1602,15 +3405,36 @@ export class UsageWebviewProvider {
       const dimension = (
         title: string,
         rows: Array<{ key: string; totals: CodexMetricTotals }>,
+        showEquivalentPrice: boolean,
       ): string => {
         if (rows.length === 0) {
           return '';
         }
         return '<div class="model-breakdown"><div class="section-header"><h3>' +
-          this.escapeHtml(title) + '</h3></div><div class="model-list">' + rows.map((row, index) =>
-            '<details class="model-item"' + (index === 0 ? ' open' : '') + '><summary class="model-header">' +
-            '<span class="model-name">' + this.escapeHtml(row.key) + '</span><span class="model-cost">' +
-            I18n.formatNumber(row.totals.fresh) + ' ' + this.escapeHtml(copy.fresh) + '</span></summary>' +
+          this.escapeHtml(title) + '</h3></div><div class="model-list">' + rows.map((row, index) => {
+          let headline: string;
+          if (showEquivalentPrice) {
+            const rowEquivalent = summarizeEquivalentUsage([
+              equivalentUsageFromProviderTokens(0, row.key, {
+                inputTotal: row.totals.input,
+                cachedInput: row.totals.cachedInput,
+                outputTotal: row.totals.output,
+                reasoningOutput: row.totals.reasoning,
+              }),
+            ], row.totals.processed);
+            const rowCoverage = pricingCoverageFormatter.format(rowEquivalent.pricingCoverage);
+            const rowHelp = copy.apiEquivalentCostHelp.replace('{coverage}', rowCoverage);
+            headline = '<span class="model-metric model-cost" title="' +
+              this.escapeHtml(rowHelp) + '">' +
+              this.escapeHtml(rowEquivalent.pricedTokens > 0
+                ? I18n.formatCurrency(rowEquivalent.equivalentUsd)
+                : '—') + '</span>';
+          } else {
+            headline = '<span class="model-metric">' + I18n.formatNumber(row.totals.fresh) + ' ' +
+              this.escapeHtml(copy.fresh) + '</span>';
+          }
+          return '<details class="model-item"' + (index === 0 ? ' open' : '') + '><summary class="model-header">' +
+            '<span class="model-name">' + this.escapeHtml(row.key) + '</span>' + headline + '</summary>' +
             '<div class="model-details model-details-stacked">' +
             '<span><span class="model-stat-label">' + this.escapeHtml(copy.processed) + '</span><strong>' +
             I18n.formatNumber(row.totals.processed) + '</strong></span>' +
@@ -1619,8 +3443,8 @@ export class UsageWebviewProvider {
             '<span><span class="model-stat-label">' + this.escapeHtml(copy.output) + '</span><strong>' +
             I18n.formatNumber(row.totals.output) + '</strong></span>' +
             '<span><span class="model-stat-label">' + this.escapeHtml(copy.reasoning) + '</span><strong>' +
-            I18n.formatNumber(row.totals.reasoning) + '</strong></span></div></details>',
-          ).join('') + '</div></div>';
+            I18n.formatNumber(row.totals.reasoning) + '</strong></span></div></details>';
+        }).join('') + '</div></div>';
       };
       return '<div class="usage-summary">' +
         this.renderCodexIndexedSubtotal(scope.indexedSubtotal) +
@@ -1637,7 +3461,7 @@ export class UsageWebviewProvider {
         metric(copy.output, scope.total.output) +
         metric(copy.reasoning, scope.total.reasoning) +
         '</div>' + compositionHtml + '</div>' +
-        dimension(copy.models, scope.models) + dimension(copy.efforts, scope.efforts);
+        dimension(copy.models, scope.models, true) + dimension(copy.efforts, scope.efforts, false);
     }
     if (!data) {
       return '<div class="no-data"><p>' + I18n.t.popup.noDataMessage + '</p></div>';
@@ -1811,7 +3635,7 @@ export class UsageWebviewProvider {
           '<span class="model-name">' +
           this.escapeHtml(model) +
           '</span>' +
-          '<span class="model-cost">' +
+          '<span class="model-metric model-cost">' +
           I18n.formatCurrency(modelData.cost) +
           '</span>' +
           '</summary>' +
@@ -1866,8 +3690,28 @@ export class UsageWebviewProvider {
           '<th>' + this.escapeHtml(copy.fresh) + '</th><th>' + this.escapeHtml(copy.input) + '</th>' +
           '<th>' + this.escapeHtml(copy.cachedInput) + '</th><th>' + this.escapeHtml(copy.output) + '</th>' +
           '<th>' + this.escapeHtml(copy.reasoning) + '</th><th>' + this.escapeHtml(copy.threads) + '</th>' +
-          '</tr></thead><tbody>' + rows.map((row) =>
-            '<tr><td class="date-cell">' + this.escapeHtml(row.day) + '</td>' +
+          '<th></th></tr></thead><tbody>' + rows.map((row) => {
+            const hourly = view.last30DaysHourlyByDay[row.day];
+            const canExpand = hourly !== undefined;
+            const dayCoverage = view.hourlyCoverage.days[row.day] ?? view.hourlyCoverage;
+            const day = this.escapeHtml(row.day);
+            const detailButton = canExpand
+              ? '<button class="detail-button" data-codex-hourly-toggle data-date="' + day + '" ' +
+                'onclick="toggleCodexHourlyDetail(\'' + day + '\')" aria-expanded="false" ' +
+                'aria-controls="codex-hourly-detail-' + day + '" title="' +
+                this.escapeHtml(I18n.t.popup.hourlyBreakdown) + '">' +
+                '<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true" focusable="false">' +
+                '<path class="expand-icon" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/>' +
+                '</svg></button>'
+              : '';
+            const detailRow = canExpand
+              ? '<tr class="hourly-detail-row" data-codex-hourly-detail-row data-date="' + day +
+                '" style="display: none;"><td colspan="10"><div class="hourly-detail-container" ' +
+                'id="codex-hourly-detail-' + day + '" data-loaded="true">' +
+                this.renderCodexHourlyBreakdown(hourly, dayCoverage, row.day) +
+                '</div></td></tr>'
+              : '';
+            return '<tr class="daily-row" data-date="' + day + '"><td class="date-cell">' + day + '</td>' +
             '<td class="cost-cell" title="' + this.escapeHtml(this.codexCostHelp(row.apiEquivalent)) + '">' +
             (row.apiEquivalent.pricedTokens > 0 ? I18n.formatCurrency(row.apiEquivalent.equivalentUsd) : '—') + '</td>' +
             '<td class="number-cell">' + I18n.formatNumber(row.total.processed) + '</td>' +
@@ -1876,8 +3720,9 @@ export class UsageWebviewProvider {
             '<td class="number-cell">' + I18n.formatNumber(row.total.cachedInput) + '</td>' +
             '<td class="number-cell">' + I18n.formatNumber(row.total.output) + '</td>' +
             '<td class="number-cell">' + I18n.formatNumber(row.total.reasoning) + '</td>' +
-            '<td class="number-cell">' + I18n.formatNumber(row.threads) + '</td></tr>',
-          ).join('') + '</tbody></table></div></div>';
+            '<td class="number-cell">' + I18n.formatNumber(row.threads) + '</td>' +
+            '<td class="detail-cell">' + detailButton + '</td></tr>' + detailRow;
+          }).join('') + '</tbody></table></div></div>';
       return this.renderUsageData(null, provider, view.last30Days) + breakdown;
     }
     if (!this.monthData) {
@@ -1943,8 +3788,10 @@ export class UsageWebviewProvider {
                   <td class="number-cell">${this.formatPercent(this.cacheHitRate(data))}</td>
                   <td class="number-cell">${I18n.formatNumber(data.messageCount)}</td>
                   <td class="detail-cell">
-                    <button class="detail-button" onclick="toggleHourlyDetail('${date}')" title="${I18n.t.popup.hourlyBreakdown}">
-                      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+                    <button class="detail-button" onclick="toggleHourlyDetail('${date}')"
+                      aria-expanded="false" aria-controls="hourly-detail-${date}"
+                      title="${this.escapeHtml(I18n.t.popup.hourlyBreakdown)}">
+                      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true" focusable="false">
                         <path class="expand-icon" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/>
                       </svg>
                     </button>
@@ -1953,7 +3800,7 @@ export class UsageWebviewProvider {
                 <tr class="hourly-detail-row" data-date="${date}" style="display: none;">
                   <td colspan="9">
                     <div class="hourly-detail-container" id="hourly-detail-${date}">
-                      <div class="loading-indicator">載入中...</div>
+                      <div class="loading-indicator">${this.escapeHtml(I18n.t.statusBar.loading)}</div>
                     </div>
                   </td>
                 </tr>
@@ -2024,7 +3871,9 @@ export class UsageWebviewProvider {
       const daily = ClaudeDataLoader.getDailyUsageMap(this.allRecords, I18n.getTimezone());
       heatmapPanel =
         '<div class="heatmap-panel"><h3>Token heatmap</h3>' +
-        '<div class="heatmap-svg">' + renderHeatmapSvg(daily) + '</div>' +
+        '<div class="heatmap-svg">' + renderHeatmapSvg(daily, {
+          endDateISO: dayKeyInZone(new Date(), I18n.getTimezone()),
+        }) + '</div>' +
         '<div class="share-actions">' +
         '<button class="btn-secondary btn-small" onclick="exportHeatmap()">Export as SVG…</button>' +
         '<button class="btn-secondary btn-small" onclick="publishHeatmap()">Publish to GitHub…</button>' +
@@ -2088,8 +3937,10 @@ export class UsageWebviewProvider {
                   <td class="number-cell">${this.formatPercent(this.cacheHitRate(data))}</td>
                   <td class="number-cell">${I18n.formatNumber(data.messageCount)}</td>
                   <td class="detail-cell">
-                    <button class="detail-button" onclick="toggleMonthlyDetail('${date}')" title="顯示每日詳細資料">
-                      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+                    <button class="detail-button" onclick="toggleMonthlyDetail('${date}')"
+                      aria-expanded="false" aria-controls="monthly-detail-${date}"
+                      title="${this.escapeHtml(I18n.t.popup.dailyBreakdown)}">
+                      <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true" focusable="false">
                         <path class="expand-icon" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/>
                       </svg>
                     </button>
@@ -2098,7 +3949,7 @@ export class UsageWebviewProvider {
                 <tr class="monthly-detail-row" data-date="${date}" style="display: none;">
                   <td colspan="9">
                     <div class="monthly-detail-container" id="monthly-detail-${date}">
-                      <div class="loading-indicator">載入中...</div>
+                      <div class="loading-indicator">${this.escapeHtml(I18n.t.statusBar.loading)}</div>
                     </div>
                   </td>
                 </tr>
@@ -2204,7 +4055,9 @@ export class UsageWebviewProvider {
     };
     const confidenceLabel = (point: WeeklyValuePoint): string => {
       if (point.boundaryUncertain) {
-        return `${copy.usageOnly} · ${copy.boundaryApproximate}`;
+        return point.fullEquivalentUsd === null
+          ? `${copy.usageOnly} · ${copy.boundaryApproximate}`
+          : `${copy.low} · ${copy.boundaryApproximate}`;
       }
       switch (point.confidence) {
         case 'high': return copy.high;
@@ -2278,27 +4131,23 @@ export class UsageWebviewProvider {
     ).join('');
     return '<div class="daily-breakdown"><div class="section-header"><h3>' + heading +
       '</h3></div><p class="table-hint">' + notes + '</p>' + chart +
-      '<div class="daily-table-container" tabindex="0"><table class="daily-table"><thead><tr>' +
+      '<details class="weekly-value-details"><summary>' + this.escapeHtml(copy.periodDetails) +
+      '</summary><div class="daily-table-container" tabindex="0"><table class="daily-table"><thead><tr>' +
       '<th>' + this.escapeHtml(copy.period) + '</th><th>' + this.escapeHtml(copy.usedValue) + '</th>' +
       '<th>' + this.escapeHtml(copy.utilization) + '</th><th>' + this.escapeHtml(copy.fullValue) + '</th>' +
       '<th>' + this.escapeHtml(copy.unusedValue) + '</th><th>' + this.escapeHtml(copy.confidence) + '</th>' +
       '<th>' + this.escapeHtml(copy.pricingCoverage) + '</th></tr></thead><tbody>' +
-      tableRows + '</tbody></table></div></div>';
+      tableRows + '</tbody></table></div></details></div>';
   }
 
-  /** The "Share card" panel (All tab). Off by default (`enableShareCard`); when
-   * on, a config form — range / scope / which metrics — with a Generate button.
+  /** The "Share card" panel (All tab). On by default (`enableShareCard`); when
+   * enabled, a config form — range / scope / which metrics — with a Generate button.
    * The preview is built on demand (no per-keystroke re-render), and export uses
    * the same config. Privacy-safe: built from buildShareCardData, aggregate only. */
   private renderShareCardPanel(): string {
     const esc = (s: string): string => this.escapeHtml(s);
-    if (!this.setting<boolean>('enableShareCard', false)) {
-      // Off by default, but leave a discoverable pointer.
-      return (
-        '<div class="share-panel"><h3>Share card</h3>' +
-        '<p class="table-hint">Turn on <b>Enable usage share card</b> in <a href="#" onclick="openSettings();return false;">⚙ Settings</a> to build a one-page, shareable summary of your usage.</p>' +
-        '</div>'
-      );
+    if (!this.setting<boolean>('enableShareCard', true)) {
+      return '';
     }
     if (!this.allRecords || this.allRecords.length === 0) {
       return '';
@@ -2533,6 +4382,7 @@ export class UsageWebviewProvider {
           '<span data-session-detail-item><span class="model-stat-label">' + this.escapeHtml(label) +
           '</span><strong title="' + this.escapeHtml(value) + '">' + this.escapeHtml(value) + '</strong></span>';
         const mainRow = '<tr class="sort-row" data-session-row data-sort-time="' + session.observedAt + '" ' +
+          'data-day-key="' + this.escapeHtml(this.configuredDateTimeParts(new Date(session.observedAt)).dayKey) + '" ' +
           'data-sort-session="' + this.escapeHtml(title.toLowerCase()) + '" ' +
           'data-sort-project="' + this.escapeHtml(project.toLowerCase()) + '" ' +
           'data-sort-role="' + this.escapeHtml(session.role) + '" ' +
@@ -2648,6 +4498,7 @@ export class UsageWebviewProvider {
       rows +=
         '<tr class="sort-row' + (foreign ? ' session-foreign' : '') + '"' +
         ' data-sort-time="' + s.startTime.getTime() + '"' +
+        ' data-day-key="' + this.escapeHtml(this.configuredDateTimeParts(s.startTime).dayKey) + '"' +
         ' data-models="' + this.escapeHtml(rowModels.join('|').toLowerCase()) + '"' +
         ' data-sort-session="' + this.escapeHtml(fullName.toLowerCase()) + '"' +
         ' data-sort-project="' + this.escapeHtml((s.projectName || '').toLowerCase()) + '"' +
@@ -2768,29 +4619,66 @@ export class UsageWebviewProvider {
     );
   }
 
+  private formatAdviceSnoozeDate(value: number): string {
+    const date = new Date(value);
+    if (isNaN(date.getTime())) {
+      return '';
+    }
+    return date.toLocaleDateString(I18n.getLocale(), I18n.dateFormatOptions());
+  }
+
   /** Reading-friendly date/time: "Today HH:MM", "Yesterday HH:MM", "MM-DD HH:MM" or "YYYY-MM-DD". */
-  private formatDateTime(date: Date): string {
+  private formatDateTime(date: Date, now: Date = new Date()): string {
     if (!date || isNaN(date.getTime()) || date.getTime() === 0) {
       return '-';
     }
-    const now = new Date();
-    const pad = (n: number): string => String(n).padStart(2, '0');
-    const hm = pad(date.getHours()) + ':' + pad(date.getMinutes());
-    const sameDay = (a: Date, b: Date): boolean =>
-      a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
-    const yesterday = new Date(now);
-    yesterday.setDate(yesterday.getDate() - 1);
-
-    if (sameDay(date, now)) {
+    const { dayKey, hm } = this.configuredDateTimeParts(date);
+    const todayKey = this.configuredDateTimeParts(now).dayKey;
+    const [yesterdayKey] = rollingDayKeysFromDayKey(todayKey, 2);
+
+    if (dayKey === todayKey) {
       return I18n.t.popup.today + ' ' + hm;
     }
-    if (sameDay(date, yesterday)) {
+    if (dayKey === yesterdayKey) {
       return I18n.t.popup.yesterday + ' ' + hm;
     }
-    if (date.getFullYear() === now.getFullYear()) {
-      return pad(date.getMonth() + 1) + '-' + pad(date.getDate()) + ' ' + hm;
+    if (dayKey.slice(0, 4) === todayKey.slice(0, 4)) {
+      return dayKey.slice(5) + ' ' + hm;
+    }
+    return dayKey;
+  }
+
+  private configuredDateTimeParts(date: Date): { dayKey: string; hm: string } {
+    if (!date || isNaN(date.getTime())) {
+      return { dayKey: '', hm: '' };
+    }
+    const configuredTimeZone = I18n.getTimezone();
+    if (!this.configuredDateTimeFormatter ||
+        this.configuredDateTimeFormatter.configuredTimeZone !== configuredTimeZone) {
+      this.configuredDateTimeFormatter = {
+        configuredTimeZone,
+        formatter: new Intl.DateTimeFormat('en-CA', {
+          year: 'numeric',
+          month: '2-digit',
+          day: '2-digit',
+          hour: '2-digit',
+          minute: '2-digit',
+          hourCycle: 'h23',
+          timeZone: resolveTimeZone(configuredTimeZone),
+        }),
+      };
     }
-    return date.getFullYear() + '-' + pad(date.getMonth() + 1) + '-' + pad(date.getDate());
+    const parts = this.configuredDateTimeFormatter.formatter.formatToParts(date);
+    const value = (type: string): string => parts.find((part) => part.type === type)?.value ?? '';
+    const year = value('year');
+    const month = value('month');
+    const day = value('day');
+    const hour = value('hour');
+    const minute = value('minute');
+    return {
+      dayKey: year && month && day ? `${year}-${month}-${day}` : '',
+      hm: hour && minute ? `${hour}:${minute}` : '',
+    };
   }
 
   /** USD per-1M-token rate, trimmed of trailing zeros for compact display. */
@@ -3200,30 +5088,32 @@ export class UsageWebviewProvider {
    * diagnostic — it tells whether the provider reuses the prompt cache across
    * a workflow's agents (see the hint line / V2.1-WORKFLOW-SPEC §Phase 2).
    */
-  private renderWorkflowData(): string {
+  private renderWorkflowData(now: Date = new Date()): string {
     if (!this.workflowBreakdown || this.workflowBreakdown.length === 0) {
       return '<div class="no-data"><p>' + I18n.t.popup.noDataMessage + '</p></div>';
     }
 
     const t = I18n.t.popup;
 
-    // Summary strip: workflow count + cost this calendar month, and that
-    // cost's share of the month's total spend.
-    const now = new Date();
-    const thisMonth = this.workflowBreakdown.filter(
-      (w) => w.endTime.getFullYear() === now.getFullYear() && w.endTime.getMonth() === now.getMonth()
+    // The middle dashboard scope is Today plus the preceding 29 configured-zone
+    // civil dates. Match that exact range and classify runs by their displayed
+    // start time so the numerator and rolling-30-day denominator reconcile.
+    const timeZone = I18n.getTimezone();
+    const rollingDays = new Set(rollingDayKeys(now.getTime(), timeZone, 30));
+    const recentWorkflows = this.workflowBreakdown.filter(
+      (w) => rollingDays.has(this.configuredDateTimeParts(w.startTime).dayKey)
     );
-    const monthWorkflowCost = thisMonth.reduce(
+    const rollingWorkflowCost = recentWorkflows.reduce(
       (sum, w) => sum + w.data.totalCost + (w.orchestration ? w.orchestration.totalCost : 0),
       0
     );
-    const monthTotalCost = this.monthData ? this.monthData.totalCost : 0;
-    const monthShare = monthTotalCost > 0 ? monthWorkflowCost / monthTotalCost : null;
+    const rollingTotalCost = this.monthData ? this.monthData.totalCost : 0;
+    const rollingShare = rollingTotalCost > 0 ? rollingWorkflowCost / rollingTotalCost : null;
     const summaryStrip =
       '<p class="table-hint">' +
-      t.workflowsThisMonth + ': ' + thisMonth.length +
-      ' · ' + I18n.formatCurrency(monthWorkflowCost) +
-      (monthShare !== null ? ' · ' + this.formatPercent(monthShare) + ' ' + t.workflowCostShare : '') +
+      t.workflowsLast30Days + ': ' + recentWorkflows.length +
+      ' · ' + I18n.formatCurrency(rollingWorkflowCost) +
+      (rollingShare !== null ? ' · ' + this.formatPercent(rollingShare) + ' ' + t.workflowLast30DaysCostShare : '') +
       '</p>';
 
     let rows = '';
@@ -3534,19 +5424,651 @@ export class UsageWebviewProvider {
       '" onclick="attrSetScope(\'' + kind + '\')">' + label + '</button>';
 
     return (
-      '<div class="daily-breakdown">' +
-      '<div class="section-header"><h3>' + t.attribution + '</h3>' +
-      '<span class="section-header-right attr-controls">' +
-      '<select id="attrTargetSession" onchange="requestAttribution()" style="display:none">' + sessionOptions + '</select>' +
-      '<select id="attrTargetProject" onchange="requestAttribution()" style="display:none">' + projectOptions + '</select>' +
-      tab('day', t.scopeDay, false) +
-      tab('week', t.scopeWeek, true) +
-      tab('month', t.scopeMonth, false) +
-      tab('session', t.sessionTitle, false) +
-      tab('project', t.project, false) +
-      '</span></div>' +
-      '<div id="attrPanel">' + this.renderAttributionPanel(weekAttr) + '</div>' +
-      '</div>'
+      '<div class="daily-breakdown">' +
+      '<div class="section-header"><h3>' + t.attribution + '</h3>' +
+      '<span class="section-header-right attr-controls">' +
+      '<select id="attrTargetSession" onchange="requestAttribution()" style="display:none">' + sessionOptions + '</select>' +
+      '<select id="attrTargetProject" onchange="requestAttribution()" style="display:none">' + projectOptions + '</select>' +
+      tab('day', t.scopeDay, false) +
+      tab('week', t.scopeWeek, true) +
+      tab('month', t.scopeMonth, false) +
+      tab('session', t.sessionTitle, false) +
+      tab('project', t.project, false) +
+      '</span></div>' +
+      '<div id="attrPanel">' + this.renderAttributionPanel(weekAttr) + '</div>' +
+      '</div>'
+    );
+  }
+
+  private codexComparisonModelFamily(model: string): 'opus' | 'sonnet' | 'haiku' | 'fable' | 'other' {
+    const value = model.toLowerCase();
+    if (value.includes('opus')) return 'opus';
+    if (value.includes('sonnet')) return 'sonnet';
+    if (value.includes('haiku')) return 'haiku';
+    if (value.includes('fable')) return 'fable';
+    return 'other';
+  }
+
+  private codexComparisonEffort(
+    effort: string,
+  ): 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'unknown' {
+    const value = effort.toLowerCase();
+    return value === 'low' || value === 'medium' || value === 'high' || value === 'xhigh' ||
+      value === 'max' || value === 'ultra'
+      ? value
+      : 'unknown';
+  }
+
+  /**
+   * Project the existing bounded Codex view into numeric task aggregates. The
+   * rootTaskViewKey is used transiently only to join already-materialized child
+   * rows; it has no destination in the returned or persisted representation.
+   */
+  private codexComparableTaskProjections(): CodexComparableTaskProjection[] {
+    const view = this.codexView;
+    if (!view) return [];
+    interface Group {
+      hasRoot: boolean;
+      observedAtEpochMs: number;
+      processed: number;
+      fresh: number;
+      childFresh: number;
+      approvalReviewerFresh: number;
+      patchCalls: number;
+      toolCalls: number;
+      postPatchToolCalls: number;
+      taskCompleteCount: number;
+      modelFamilies: Set<'opus' | 'sonnet' | 'haiku' | 'fable' | 'other'>;
+      efforts: Set<'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'unknown'>;
+    }
+    const groups = new Map<string, Group>();
+    for (const thread of view.recentThreads.slice(0, 1_000)) {
+      const current = groups.get(thread.rootTaskViewKey) ?? {
+        hasRoot: false,
+        observedAtEpochMs: 0,
+        processed: 0,
+        fresh: 0,
+        childFresh: 0,
+        approvalReviewerFresh: 0,
+        patchCalls: 0,
+        toolCalls: 0,
+        postPatchToolCalls: 0,
+        taskCompleteCount: 0,
+        modelFamilies: new Set<'opus' | 'sonnet' | 'haiku' | 'fable' | 'other'>(),
+        efforts: new Set<'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'unknown'>(),
+      };
+      current.hasRoot ||= thread.role === 'root';
+      current.observedAtEpochMs = Math.max(current.observedAtEpochMs, thread.observedAt);
+      current.processed += Math.max(0, thread.total.processed);
+      current.fresh += Math.max(0, thread.total.fresh);
+      if (thread.role === 'subagent') current.childFresh += Math.max(0, thread.total.fresh);
+      if (thread.role === 'approval-reviewer') {
+        current.approvalReviewerFresh += Math.max(0, thread.total.fresh);
+      }
+      current.patchCalls += Math.max(0, thread.structural.patchCalls);
+      current.toolCalls += Math.max(0, thread.structural.toolCalls);
+      current.postPatchToolCalls += Math.max(0, thread.structural.postPatchToolCalls);
+      current.taskCompleteCount += Math.max(0, thread.structural.taskCompleteCount);
+      for (const model of thread.models) {
+        current.modelFamilies.add(this.codexComparisonModelFamily(model));
+      }
+      for (const effort of thread.efforts) {
+        current.efforts.add(this.codexComparisonEffort(effort));
+      }
+      groups.set(thread.rootTaskViewKey, current);
+    }
+    const qualityFlags = view.qualityFlags.map((item) => item.flag);
+    return [...groups.values()]
+      .filter((group) => group.hasRoot)
+      .map((group) => ({
+        observedAtEpochMs: group.observedAtEpochMs,
+        total: { processed: group.processed, fresh: group.fresh },
+        structural: {
+          patchCalls: group.patchCalls,
+          toolCalls: group.toolCalls,
+          postPatchToolCalls: group.postPatchToolCalls,
+          taskCompleteCount: group.taskCompleteCount,
+        },
+        childFreshShare: group.fresh > 0 ? group.childFresh / group.fresh : 0,
+        approvalReviewerFreshShare:
+          group.fresh > 0 ? group.approvalReviewerFresh / group.fresh : 0,
+        modelFamilies: [...group.modelFamilies].sort(),
+        efforts: [...group.efforts].sort(),
+        coverage: {
+          complete: view.coverage.complete,
+          identityComplete: view.coverage.identity.complete,
+          qualityFlags: [...qualityFlags],
+        },
+      }))
+      .sort((left, right) => left.observedAtEpochMs - right.observedAtEpochMs);
+  }
+
+  private adviceComparablePairSampleKey(pair: StoredComparablePair): string {
+    return JSON.stringify({
+      recommendationId: pair.recommendationId,
+      recommendationVersion: pair.recommendationVersion,
+      context: pair.context,
+      metric: pair.metric,
+      quality: pair.quality,
+      evidence: pair.evidence,
+      recordedAtEpochMs: pair.recordedAtEpochMs,
+    });
+  }
+
+  private adviceComparablePairCohortKey(pair: StoredComparablePair): string {
+    return JSON.stringify({
+      context: pair.context,
+      metric: {
+        name: pair.metric.name,
+        unit: pair.metric.unit,
+        direction: pair.metric.direction,
+      },
+    });
+  }
+
+  /** Pure state projection used by the production writer and focused tests. */
+  private materializeAdviceComparisonState(
+    _now: number = Date.now(),
+    baseState: AdviceLocalState = this.adviceLocalState,
+  ): AdviceLocalState {
+    const providerState = this.adviceEffectivenessStates.codex;
+    if (
+      !this.adviceExperimentEnabled() ||
+      !providerState ||
+      !this.codexView ||
+      this.adviceLocalStateStatus !== 'ready'
+    ) {
+      return baseState;
+    }
+    const tasks = this.codexComparableTaskProjections();
+    let next = baseState;
+    for (const recommendation of providerState.contract.recommendations) {
+      if (!isComparableCodexRecommendationId(recommendation.id)) continue;
+      const applied = [...next.feedback]
+        .filter(
+          (item) =>
+            item.applied === 'applied' &&
+            item.recommendationId === recommendation.id &&
+            item.adviceId.startsWith('advice-codex-'),
+        )
+        .sort(
+          (left, right) =>
+            (right.appliedAtEpochMs ?? right.updatedAtEpochMs) -
+              (left.appliedAtEpochMs ?? left.updatedAtEpochMs) ||
+            right.adviceId.localeCompare(left.adviceId),
+        )[0];
+      if (!applied) continue;
+      const built = buildAppliedComparablePairs({
+        adviceId: applied.adviceId,
+        recommendationId: recommendation.id,
+        recommendationVersion: CODEX_LOCAL_RECOMMENDATION_VERSION,
+        appliedAtEpochMs: applied.appliedAtEpochMs ?? applied.updatedAtEpochMs,
+        tasks,
+      });
+      if (!built.ok) continue;
+      const existingSamples = new Set(
+        next.comparablePairs.map((pair) => this.adviceComparablePairSampleKey(pair)),
+      );
+      for (const pair of built.pairs) {
+        const sampleKey = this.adviceComparablePairSampleKey(pair);
+        if (existingSamples.has(sampleKey)) continue;
+        const appended = appendStoredComparablePair(next, pair);
+        if (!appended.ok) continue;
+        next = appended.value;
+        existingSamples.add(sampleKey);
+      }
+
+      const criterion = recommendation.successCriteria.find(
+        (item) =>
+          item.target.kind === 'relative-change' &&
+          item.direction === 'decrease' &&
+          item.qualityGuardrail.rubricId === 'task-quality-rubric-v1',
+      );
+      if (!criterion) continue;
+      const lineage = next.comparablePairs.filter(
+        (pair) =>
+          pair.context.provider === 'codex' &&
+          pair.recommendationId === recommendation.id &&
+          pair.recommendationVersion === CODEX_LOCAL_RECOMMENDATION_VERSION &&
+          pair.context.measurementProfileVersion === CODEX_COMPARISON_MEASUREMENT_PROFILE_VERSION,
+      );
+      const cohorts = new Map<string, StoredComparablePair[]>();
+      for (const pair of lineage) {
+        const key = this.adviceComparablePairCohortKey(pair);
+        const cohort = cohorts.get(key) ?? [];
+        cohort.push(pair);
+        cohorts.set(key, cohort);
+      }
+      for (const pairs of cohorts.values()) {
+        const first = pairs[0];
+        const frozen = buildAdviceComparisonResultEnvelope({
+          provider: 'codex',
+          recommendationId: recommendation.id,
+          recommendationVersion: CODEX_LOCAL_RECOMMENDATION_VERSION,
+          measurementProfileVersion: CODEX_COMPARISON_MEASUREMENT_PROFILE_VERSION,
+          cohort: {
+            scope: first.context.scope,
+            taskKind: first.context.taskKind,
+            complexityBand: first.context.complexityBand,
+            modelFamily: first.context.modelFamily,
+            effort: first.context.effort,
+            metricDefinitionVersion: first.context.metricDefinitionVersion,
+            qualityRubricId: first.context.qualityRubricId,
+            metric: {
+              name: first.metric.name,
+              unit: first.metric.unit,
+              direction: first.metric.direction,
+            },
+          },
+          guardrail: {
+            minComparablePairs: criterion.minimumComparableTasks,
+            minRelativeImprovement: criterion.target.value,
+            minAfterQualityScore: criterion.qualityGuardrail.minimumScore,
+            maxMeanQualityRegression: criterion.qualityGuardrail.maximumRegression,
+            allowedQualityFlags: [],
+            qualityRubricId: criterion.qualityGuardrail.rubricId,
+          },
+          pairs,
+          recordedAtEpochMs: Math.max(...pairs.map((pair) => pair.recordedAtEpochMs)),
+        });
+        if (
+          !frozen.ok ||
+          next.comparisonResults.some(
+            (result) => result.comparisonId === frozen.value.comparisonId,
+          )
+        ) {
+          continue;
+        }
+        const appended = appendAdviceComparisonResult(next, frozen.value);
+        if (appended.ok) next = appended.value;
+      }
+    }
+    return next;
+  }
+
+  private currentAdviceComparisonProductionRevision(): string {
+    const view = this.codexView;
+    const safe = {
+      enabled: this.adviceExperimentEnabled(),
+      stateStatus: this.adviceLocalStateStatus,
+      applied: this.adviceLocalState.feedback
+        .filter((item) => item.applied === 'applied')
+        .map((item) => ({
+          adviceId: item.adviceId,
+          recommendationId: item.recommendationId,
+          appliedAtEpochMs: item.appliedAtEpochMs ?? item.updatedAtEpochMs,
+        })),
+      comparablePairCount: this.adviceLocalState.comparablePairs.length,
+      comparisonResultCount: this.adviceLocalState.comparisonResults.length,
+      codex: view
+        ? {
+            indexedFiles: view.coverage.indexedFiles,
+            indexedBytes: view.coverage.indexedBytes,
+            complete: view.coverage.complete,
+            identityComplete: view.coverage.identity.complete,
+            totalThreadCount: view.totalThreadCount,
+            lastActiveAt: view.lastTaskIdentity?.lastActiveAt ?? 0,
+            lastTaskTotal: view.lastTask?.total,
+            lastTaskStructural: view.lastTask?.structural,
+            qualityFlags: view.qualityFlags,
+          }
+        : null,
+    };
+    return createHash('sha256').update(JSON.stringify(safe), 'utf8').digest('hex');
+  }
+
+  private scheduleAdviceComparisonProduction(): void {
+    if (
+      !this.adviceExperimentEnabled() ||
+      this.adviceLocalStateStatus !== 'ready' ||
+      !this.codexView ||
+      !this.adviceStateStorage()
+    ) {
+      return;
+    }
+    const revision = this.currentAdviceComparisonProductionRevision();
+    if (revision === this.adviceComparisonProductionRevision) return;
+    this.adviceComparisonProductionRevision = revision;
+    void this.enqueueAdviceLocalStateWrite((current) => {
+      const next = this.materializeAdviceComparisonState(Date.now(), current);
+      if (
+        next.comparablePairs.length === current.comparablePairs.length &&
+        next.comparisonResults.length === current.comparisonResults.length
+      ) {
+        return undefined;
+      }
+      return next;
+    })
+      .then((saved) => {
+        if (!saved.ok) {
+          if (this.adviceComparisonProductionRevision === revision) {
+            this.adviceComparisonProductionRevision = '';
+          }
+          return;
+        }
+        this.adviceComparisonProductionRevision =
+          this.currentAdviceComparisonProductionRevision();
+        if (saved.changed && this.panel) this.updateWebview();
+      })
+      .catch(() => {
+        if (this.adviceComparisonProductionRevision === revision) {
+          this.adviceComparisonProductionRevision = '';
+        }
+      });
+  }
+
+  private adviceComparison(
+    state: AdviceEffectivenessProviderState,
+    recommendationId: string | undefined,
+  ): {
+    status:
+      | 'evidence-insufficient'
+      | 'quality-guardrail-failed'
+      | 'improved'
+      | 'no-demonstrated-improvement';
+    comparablePairs: number;
+    minimumComparablePairs: number;
+  } {
+    const minimumComparablePairs = state.contract.recommendations
+      .find((item) => item.id === recommendationId)
+      ?.successCriteria[0]?.minimumComparableTasks ?? 5;
+    if (!recommendationId) {
+      return { status: 'evidence-insufficient', comparablePairs: 0, minimumComparablePairs };
+    }
+    const recommendationVersion = state.provider === 'codex' &&
+      isComparableCodexRecommendationId(recommendationId)
+      ? CODEX_LOCAL_RECOMMENDATION_VERSION
+      : undefined;
+    const frozen = this.adviceLocalState.comparisonResults
+      .filter(
+        (item) =>
+          item.provider === state.provider &&
+          item.recommendationId === recommendationId &&
+          (!recommendationVersion || item.recommendationVersion === recommendationVersion),
+      )
+      .sort(
+        (left, right) =>
+          right.sample.pairCount - left.sample.pairCount ||
+          right.recordedAtEpochMs - left.recordedAtEpochMs ||
+          right.comparisonId.localeCompare(left.comparisonId),
+      )[0];
+    if (frozen) {
+      return {
+        status: frozen.result.status,
+        comparablePairs: frozen.sample.pairCount,
+        minimumComparablePairs: frozen.guardrail.minComparablePairs,
+      };
+    }
+    const comparablePairs = this.adviceLocalState.comparablePairs.filter(
+      (pair) =>
+        pair.context.provider === state.provider &&
+        pair.recommendationId === recommendationId &&
+        (!recommendationVersion || pair.recommendationVersion === recommendationVersion),
+    ).length;
+    return { status: 'evidence-insufficient', comparablePairs, minimumComparablePairs };
+  }
+
+  /**
+   * Hidden v2.3.1 candidate surface. It extends the existing Advice /
+   * Recommendations cards instead of creating a third experience. Machine
+   * summaries and prompt samples are intentionally never rendered here.
+   */
+  private renderAdviceEffectivenessBody(provider: AdviceEffectivenessProvider): string {
+    if (!this.adviceExperimentEnabled()) {
+      return '';
+    }
+    const t = I18n.t.popup.adviceEffectiveness;
+    const state = this.adviceEffectivenessStates[provider];
+    const html = (value: string): string => this.escapeHtml(value);
+    const replace = (template: string, key: string, value: string): string =>
+      template.replace(`{${key}}`, value);
+    const percent = (value: number): string =>
+      `${Math.round(Math.max(0, Math.min(1, value)) * 100)}%`;
+    const contract = state?.contract;
+    const recommendations = contract?.recommendations ?? [];
+    const observations: string[] = [];
+    let limitationText = t.qualityGuardrailPending;
+
+    if (state && provider === 'claude') {
+      const byMetric = new Map(state.contract.observations.map((item) => [item.metric, item]));
+      const longSession = byMetric.get('long-session-share');
+      const largeContext = byMetric.get('large-context-share');
+      const framework = byMetric.get('framework-overhead-share');
+      if (longSession && typeof longSession.value === 'number') {
+        observations.push(replace(t.longSessionSignal, 'share', percent(longSession.value)));
+      }
+      if (largeContext && typeof largeContext.value === 'number') {
+        observations.push(replace(t.largeContextSignal, 'share', percent(largeContext.value)));
+      }
+      if (framework && typeof framework.value === 'number') {
+        observations.push(replace(t.frameworkOverheadSignal, 'share', percent(framework.value)));
+      }
+      limitationText = `${t.elapsedTimeProxy} ${t.qualityGuardrailPending}`;
+    } else if (state && provider === 'codex') {
+      const copy = I18n.t.providers.codex;
+      for (const recommendation of recommendations) {
+        const kind = recommendation.id.replace('recommendation-codex-', '') as
+          keyof typeof copy.insightObservations;
+        if (Object.prototype.hasOwnProperty.call(copy.insightObservations, kind)) {
+          const observation = copy.insightObservations[kind];
+          if (!observations.includes(observation)) observations.push(observation);
+        }
+      }
+      limitationText = `${copy.structuralProxy} ${t.qualityGuardrailPending}`;
+    }
+    if (observations.length === 0) {
+      observations.push(t.noEvidenceAdvice);
+    }
+
+    const evidenceText = state
+      ? `${t.source}: ${provider === 'claude' ? 'Claude' : 'Codex'} · ${t.evidence}: ${state.contract.evidence.length}`
+      : t.noEvidenceAdvice;
+    const bodyId = `advice-effectiveness-${provider}`;
+    const step = (index: number, label: string, content: string): string =>
+      '<li><span class="advice-step-marker" aria-hidden="true">' + index + '</span>' +
+      '<div><strong>' + html(label) + '</strong><p>' + content + '</p></div></li>';
+    const feedbackFor = (recommendation: AdviceRecommendation, suppressed = false): string => {
+      if (!state) return '';
+      const feedback = this.adviceLocalState.feedback.find(
+        (item) =>
+          item.adviceId === state.contract.adviceId &&
+          item.recommendationId === recommendation.id,
+      );
+      const snoozedUntil = adviceRecommendationSnoozedUntil(this.adviceLocalState, {
+        provider,
+        surface: 'advice',
+        recommendationId: recommendation.id,
+        nowEpochMs: Date.now(),
+      });
+      const disabled = this.adviceLocalStateStatus !== 'ready' ? ' disabled' : '';
+      const button = (
+        kind: 'helpful' | 'not-helpful' | 'applied',
+        label: string,
+        selected: boolean,
+      ): string =>
+        '<button type="button" class="advice-feedback-button' + (selected ? ' is-selected' : '') + '"' +
+        ' data-advice-action="feedback" data-provider="' + provider + '"' +
+        ' data-advice-id="' + html(state.contract.adviceId) + '"' +
+        ' data-recommendation-id="' + html(recommendation.id) + '"' +
+        ' data-feedback-kind="' + kind + '" aria-pressed="' + String(selected) + '"' + disabled + '>' +
+        '<span aria-hidden="true">' + (selected ? '✓' : '○') + '</span> ' + html(label) + '</button>';
+      return (
+        '<div class="advice-feedback-section">' +
+        '<h5>' + html(t.feedbackTitle) + '</h5>' +
+        '<div class="advice-feedback-group" role="group" aria-label="' + html(t.feedbackTitle) + '">' +
+        (suppressed ? '' :
+          button('helpful', t.helpful, feedback?.rating === 'helpful') +
+          button('not-helpful', t.notHelpful, feedback?.rating === 'not-helpful') +
+          button('applied', t.applied, feedback?.applied === 'applied')) +
+        '<button type="button" class="advice-feedback-button" data-advice-action="snooze"' +
+        ' data-provider="' + provider + '" data-advice-id="' + html(state.contract.adviceId) +
+        '" data-recommendation-id="' + html(recommendation.id) + '" data-snooze-mode="' +
+        (snoozedUntil ? 'resume' : 'snooze') + '"' + disabled + '>' +
+        html(snoozedUntil ? t.resume : t.snooze) + '</button>' +
+        '</div>' +
+        '<p class="advice-local-note">' + html(t.feedbackLocalOnly) + '</p>' +
+        (snoozedUntil
+          ? '<p class="advice-local-note">' + html(t.snoozedUntil.replace('{date}', this.formatAdviceSnoozeDate(snoozedUntil))) + '</p>'
+          : '') +
+        '<p class="advice-inline-status" data-advice-feedback-status="' + provider + '"' +
+        ' data-advice-id="' + html(state.contract.adviceId) + '"' +
+        ' data-recommendation-id="' + html(recommendation.id) + '" aria-live="polite"></p>' +
+        '</div>'
+      );
+    };
+    const recommendationCopy = (
+      recommendation: AdviceRecommendation,
+    ): { recommendation: string; action: string } => {
+      if (provider === 'claude') {
+        return { recommendation: t.clearBoundaryRecommendation, action: t.clearBoundaryAction };
+      }
+      const copy = I18n.t.providers.codex;
+      const kind = recommendation.id.replace('recommendation-codex-', '') as keyof typeof copy.insightTips;
+      return {
+        recommendation: t.codexLocalRecommendation,
+        action: Object.prototype.hasOwnProperty.call(copy.insightTips, kind)
+          ? copy.insightTips[kind]
+          : t.noEvidenceAdvice,
+      };
+    };
+    const activeRecommendations = state
+      ? recommendations.filter((recommendation) => !adviceRecommendationSnoozedUntil(this.adviceLocalState, {
+          provider,
+          surface: 'advice',
+          recommendationId: recommendation.id,
+          nowEpochMs: Date.now(),
+        }))
+      : [];
+    const suppressedRecommendations = state
+      ? recommendations.filter((recommendation) => !activeRecommendations.includes(recommendation))
+      : [];
+    const recommendationHtml = state && activeRecommendations.length > 0
+      ? activeRecommendations.map((recommendation) => {
+          const copy = recommendationCopy(recommendation);
+          const comparison = this.adviceComparison(state, recommendation.id);
+          const resultText = comparison.status === 'quality-guardrail-failed'
+            ? t.qualityGuardrailFailed
+            : comparison.status === 'improved'
+              ? t.improved
+              : comparison.status === 'no-demonstrated-improvement'
+                ? t.noDemonstratedImprovement
+                : t.insufficientEvidence;
+          const pairText = replace(
+            t.comparablePairs,
+            'count',
+            String(comparison.comparablePairs),
+          );
+          const minimumText = replace(
+            t.minimumComparablePairs,
+            'minimum',
+            String(comparison.minimumComparablePairs),
+          );
+          return (
+            '<div class="advice-recommendation-boundary" data-advice-recommendation="' +
+            html(recommendation.id) + '">' +
+            '<ol class="advice-spine" aria-label="' + html(t.spineLabel) + '">' +
+            step(3, t.recommendation, html(copy.recommendation)) +
+            step(4, t.action, html(copy.action)) +
+            step(
+              5,
+              t.result,
+              html(resultText) + '<br><span class="advice-step-caveat">' +
+                html(pairText + ' · ' + minimumText) + '</span>',
+            ) +
+            '</ol>' + feedbackFor(recommendation) + '</div>'
+          );
+        }).join('') + suppressedRecommendations.map((recommendation) => {
+          const until = adviceRecommendationSnoozedUntil(this.adviceLocalState, {
+            provider,
+            surface: 'advice',
+            recommendationId: recommendation.id,
+            nowEpochMs: Date.now(),
+          });
+          return '<details class="advice-recommendation-snoozed" data-advice-recommendation="' +
+            html(recommendation.id) + '"><summary>' + html(t.snoozedUntil.replace(
+              '{date}',
+              until ? this.formatAdviceSnoozeDate(until) : '',
+            )) + '</summary>' + feedbackFor(recommendation, true) + '</details>';
+        }).join('')
+      : state && suppressedRecommendations.length > 0
+        ? suppressedRecommendations.map((recommendation) => {
+            const until = adviceRecommendationSnoozedUntil(this.adviceLocalState, {
+              provider,
+              surface: 'advice',
+              recommendationId: recommendation.id,
+              nowEpochMs: Date.now(),
+            });
+            return '<details class="advice-recommendation-snoozed" data-advice-recommendation="' +
+              html(recommendation.id) + '"><summary>' + html(t.snoozedUntil.replace(
+                '{date}',
+                until ? this.formatAdviceSnoozeDate(until) : '',
+              )) + '</summary>' + feedbackFor(recommendation, true) + '</details>';
+          }).join('')
+      : '<ol class="advice-spine" aria-label="' + html(t.spineLabel) + '">' +
+        step(3, t.recommendation, html(t.noEvidenceAdvice)) +
+        step(4, t.action, html(t.noEvidenceAdvice)) +
+        step(5, t.result, html(t.insufficientEvidence)) +
+        '</ol>';
+
+    let payloadHtml = '<p class="advice-local-note">' + html(t.codexPreviewUnavailable) + '</p>';
+    if (state?.provider === 'claude' && state.remotePreviewEligible && state.aggregate) {
+      const ready = this.adviceLocalStateStatus === 'ready';
+      const aggregateChecked = ready && this.adviceLocalState.aggregateConsent === 'explicit';
+      const promptAvailable = state.promptSamples.length > 0 || Boolean(state.userContext?.trim());
+      const promptChecked =
+        aggregateChecked && promptAvailable && this.adviceLocalState.promptSampleConsent === 'explicit';
+      const aggregateDisabled = ready ? '' : ' disabled';
+      const promptDisabled = ready && aggregateChecked && promptAvailable ? '' : ' disabled';
+      const previewDisabled = ready && aggregateChecked ? '' : ' disabled';
+      payloadHtml =
+        '<div class="advice-payload-section">' +
+        '<h5>' + html(t.payloadTitle) + '</h5>' +
+        '<p class="advice-local-note">' + html(t.payloadDescription) + '</p>' +
+        '<fieldset class="advice-consent" data-advice-consent="' + provider + '">' +
+        '<legend>' + html(t.payloadTitle) + '</legend>' +
+        '<label><input type="checkbox" data-advice-consent-kind="aggregate" data-provider="' + provider + '"' +
+        (aggregateChecked ? ' checked' : '') + aggregateDisabled + '> <span><strong>' +
+        html(t.aggregateConsentLabel) + '</strong><small>' + html(t.aggregateConsentHelp) + '</small></span></label>' +
+        '<label><input type="checkbox" data-advice-consent-kind="prompt" data-provider="' + provider + '"' +
+        ' data-prompt-available="' + String(promptAvailable) + '"' +
+        (promptChecked ? ' checked' : '') + promptDisabled + '> <span><strong>' +
+        html(t.promptConsentLabel) + '</strong><small>' +
+        html(t.promptConsentHelp + ' ' + replace(
+          t.promptWindowHelp,
+          'days',
+          String(state.aggregate.windowDays),
+        )) + '</small></span></label>' +
+        '</fieldset>' +
+        '<div class="advice-payload-actions"><button type="button" class="btn-secondary btn-small"' +
+        ' data-advice-action="preview" data-provider="' + provider + '"' + previewDisabled + '>' +
+        html(t.previewPayload) + '</button><span>' + html(t.noNetworkTransport) + '</span></div>' +
+        '<p class="advice-inline-status" data-advice-consent-status="' + provider + '" aria-live="polite"></p>' +
+        '<details class="advice-payload-preview" data-advice-preview="' + provider + '" hidden>' +
+        '<summary><span>' + html(t.payloadTitle) + '</span><span class="advice-seal-stamp">SHA-256</span></summary>' +
+        '<div class="advice-payload-meta" aria-live="polite">' +
+        '<span data-advice-preview-content-type></span><span data-advice-preview-mode></span><span data-advice-preview-bytes></span>' +
+        '<span data-advice-preview-count></span><code data-advice-preview-digest></code></div>' +
+        '<pre tabindex="0" data-advice-preview-body aria-label="' + html(t.payloadTitle) + '"></pre>' +
+        '<div class="advice-payload-actions"><button type="button" class="btn-primary btn-small"' +
+        ' data-advice-action="send" data-provider="' + provider + '" disabled>' +
+        html(t.sendPreparedRequest) + '</button></div>' +
+        '</details></div>';
+    }
+
+    return (
+      '<section class="advice-effectiveness-body" data-advice-provider="' + provider + '" aria-labelledby="' + bodyId + '">' +
+      '<div class="advice-effectiveness-heading"><h4 id="' + bodyId + '">' + html(t.title) +
+      ' <span class="exp-pill">v2.3.1</span></h4><p>' + html(t.description) + '</p></div>' +
+      '<p class="advice-candidate-note">' + html(t.candidateNotice) + '</p>' +
+      '<ol class="advice-spine" aria-label="' + html(t.spineLabel) + '">' +
+      step(1, t.observation, observations.map((item) => html(item)).join('<br>')) +
+      step(2, t.evidence, html(evidenceText) + '<br><span class="advice-step-caveat">' + html(limitationText) + '</span>') +
+      '</ol>' +
+      recommendationHtml + payloadHtml +
+      '<div class="advice-local-data-actions"><button type="button" class="btn-secondary btn-small"' +
+      ' data-advice-action="clear" data-provider="' + provider + '">' +
+      html(t.clearLocalData) + '</button></div>' +
+      '</section>'
     );
   }
 
@@ -3567,6 +6089,7 @@ export class UsageWebviewProvider {
       '</div>' +
       '<button class="btn-primary" onclick="getAdvice()">' + t.getAdvice + '</button>' +
       '</div>' +
+      this.renderAdviceEffectivenessBody('claude') +
       '</div>'
     );
   }
@@ -3574,12 +6097,13 @@ export class UsageWebviewProvider {
   /**
    * Usage Optimizer card (Phase 9c). Default OFF — until the user opts in via
    * settings it shows only a description + an "enable" button. When enabled it
-   * exposes a textarea + toggles; the round-trip runs in extension.ts via the
-   * onOptimize hook (consent modal lives there). The result skeleton is baked
+   * exposes a textarea + toggles; preparation and explicit sending run through
+   * the same sealed-request hooks as advice. The result skeleton is baked
    * in (hidden) so the webview JS only fills text — no labels passed to JS.
    */
   private renderOptimizerCard(): string {
     const t = I18n.t.popup;
+    const ai = t.adviceEffectiveness;
     const enabled = this.setting<boolean>('advice.optimizer.enabled', false);
     // Shared header: icon badge + title (with an "experimental" pill) + purpose.
     const head = (action: string): string =>
@@ -3595,7 +6119,7 @@ export class UsageWebviewProvider {
 
     if (!enabled) {
       return (
-        '<div class="action-card">' +
+        '<div class="action-card" data-advice-provider="optimizer">' +
         head(
           '<button class="btn-secondary btn-small" onclick="showTab(\'settings\')">' +
             t.optimizerEnableBtn +
@@ -3610,12 +6134,112 @@ export class UsageWebviewProvider {
     const draftVal = st ? this.escapeHtml(st.draft) : '';
     const hasResult = !!(st && (st.prompt || st.settings));
     const hasErr = !!(st && st.error);
+    const hasPreview = !!(
+      st && st.snapshotId && st.previewBody && st.previewSha256 && st.previewBytes !== undefined
+    );
+    const optimizerAdviceId = st?.adviceId ?? '';
+    const optimizerFeedback = optimizerAdviceId
+      ? this.adviceLocalState.feedback.find(
+          (item) =>
+            item.adviceId === optimizerAdviceId &&
+            item.recommendationId === OPTIMIZER_FEEDBACK_RECOMMENDATION_ID,
+        )
+      : undefined;
+    const optimizerSnoozedUntil = optimizerAdviceId
+      ? adviceRecommendationSnoozedUntil(this.adviceLocalState, {
+          provider: 'optimizer',
+          surface: 'optimizer',
+          recommendationId: OPTIMIZER_FEEDBACK_RECOMMENDATION_ID,
+          nowEpochMs: Date.now(),
+        })
+      : null;
+    const feedbackDisabled =
+      !optimizerAdviceId || this.adviceLocalStateStatus !== 'ready' ? ' disabled' : '';
+    const feedbackButton = (
+      kind: 'helpful' | 'not-helpful' | 'applied',
+      label: string,
+      selected: boolean,
+    ): string =>
+      '<button type="button" class="advice-feedback-button' + (selected ? ' is-selected' : '') + '"' +
+      ' data-advice-action="feedback" data-provider="optimizer"' +
+      ' data-advice-id="' + this.escapeHtml(optimizerAdviceId) + '"' +
+      ' data-recommendation-id="' + OPTIMIZER_FEEDBACK_RECOMMENDATION_ID + '"' +
+      ' data-feedback-kind="' + kind + '" aria-pressed="' + String(selected) + '"' +
+      feedbackDisabled + '><span aria-hidden="true">' + (selected ? '✓' : '○') +
+      '</span> ' + this.escapeHtml(label) + '</button>';
+    const optimizerFeedbackHtml =
+      '<div id="optFeedback" class="advice-feedback-section" style="display:' +
+      (hasResult && optimizerAdviceId ? '' : 'none') + '">' +
+      '<h5>' + this.escapeHtml(ai.feedbackTitle) + '</h5>' +
+      '<div class="advice-feedback-group" role="group" aria-label="' +
+      this.escapeHtml(ai.feedbackTitle) + '">' +
+      feedbackButton('helpful', ai.helpful, optimizerFeedback?.rating === 'helpful') +
+      feedbackButton('not-helpful', ai.notHelpful, optimizerFeedback?.rating === 'not-helpful') +
+      feedbackButton('applied', ai.applied, optimizerFeedback?.applied === 'applied') +
+      '<button type="button" class="advice-feedback-button" data-advice-action="snooze" data-provider="optimizer"' +
+      ' data-advice-id="' + this.escapeHtml(optimizerAdviceId) + '" data-recommendation-id="' +
+      OPTIMIZER_FEEDBACK_RECOMMENDATION_ID + '" data-snooze-mode="' +
+      (optimizerSnoozedUntil ? 'resume' : 'snooze') + '"' + feedbackDisabled + '>' +
+      this.escapeHtml(optimizerSnoozedUntil ? ai.resume : ai.snooze) + '</button>' +
+      '</div><p class="advice-local-note">' + this.escapeHtml(ai.feedbackLocalOnly) + '</p>' +
+      (optimizerSnoozedUntil
+        ? '<p class="advice-local-note">' + this.escapeHtml(ai.snoozedUntil.replace('{date}', this.formatAdviceSnoozeDate(optimizerSnoozedUntil))) + '</p>'
+        : '') +
+      '<p class="advice-inline-status" data-advice-feedback-status="optimizer"' +
+      ' data-advice-id="' + this.escapeHtml(optimizerAdviceId) + '"' +
+      ' data-recommendation-id="' + OPTIMIZER_FEEDBACK_RECOMMENDATION_ID +
+      '" aria-live="polite"></p></div>';
+    const optimizerSnoozedHtml = optimizerSnoozedUntil && optimizerAdviceId
+      ? '<div class="advice-recommendation-snoozed" role="status">' +
+        '<p class="advice-local-note">' + this.escapeHtml(ai.snoozedUntil.replace(
+          '{date}',
+          this.formatAdviceSnoozeDate(optimizerSnoozedUntil),
+        )) + '</p>' +
+        '<button type="button" class="advice-feedback-button" data-advice-action="snooze" data-provider="optimizer"' +
+        ' data-advice-id="' + this.escapeHtml(optimizerAdviceId) + '" data-recommendation-id="' +
+        OPTIMIZER_FEEDBACK_RECOMMENDATION_ID + '" data-snooze-mode="resume"' + feedbackDisabled + '>' +
+        this.escapeHtml(ai.resume) + '</button></div>'
+      : '';
+    const optimizerResultHtml = optimizerSnoozedUntil
+      ? ''
+      : '<div id="optResult" class="opt-result" style="display:' + (hasResult ? '' : 'none') + '">' +
+        '<h4 class="opt-subhead">' + t.optimizerPromptHeading + '</h4>' +
+        '<div class="opt-output"><pre id="optPrompt">' +
+        (st && st.prompt ? this.escapeHtml(st.prompt) : '') + '</pre>' +
+        '<button class="opt-copy" data-copy="' + this.escapeHtml(t.optimizerCopy) +
+        '" data-copied="' + this.escapeHtml(t.optimizerCopied) +
+        '" title="' + this.escapeHtml(t.optimizerCopy) + '" onclick="copyOptPrompt(this)">' +
+        '<span class="opt-copy-ico">⧉</span><span class="opt-copy-lbl">' +
+        this.escapeHtml(t.optimizerCopy) + '</span></button></div>' +
+        '<h4 class="opt-subhead">' + t.optimizerSettingsHeading + '</h4>' +
+        '<div id="optSettings" class="opt-settings" data-raw="' +
+        (st && st.settings ? this.escapeHtml(st.settings) : '') + '">' +
+        (st && st.settings ? this.escapeHtml(st.settings) : '') + '</div>' +
+        optimizerFeedbackHtml + '</div>';
+    const optimizerPreviewHtml = optimizerSnoozedUntil
+      ? ''
+      : '<details id="optPreview" class="advice-payload-preview"' + (hasPreview ? ' open' : '') +
+        ' style="display:' + (hasPreview ? '' : 'none') + '" data-snapshot-id="' +
+        (hasPreview ? this.escapeHtml(st!.snapshotId as string) : '') + '">' +
+        '<summary><span>' + this.escapeHtml(ai.payloadTitle) +
+        '</span><span class="advice-seal-stamp">SHA-256</span></summary>' +
+        '<div class="advice-payload-meta"><span id="optPreviewBytes">' +
+        (hasPreview ? this.escapeHtml(ai.payloadBytes.replace('{bytes}', String(st!.previewBytes))) : '') +
+        '</span><code id="optPreviewDigest">' +
+        (hasPreview ? this.escapeHtml(`SHA-256 ${st!.previewSha256}`) : '') +
+        '</code></div><pre id="optPreviewBody" tabindex="0">' +
+        (hasPreview ? this.escapeHtml(st!.previewBody as string) : '') +
+        '</pre><div class="advice-payload-actions"><button type="button" class="btn-primary btn-small"' +
+        ' id="optSendBtn" onclick="sendOptimizer()"' + (hasPreview ? '' : ' disabled') + '>' +
+        this.escapeHtml(ai.sendPreparedRequest) +
+        '</button><span>' + this.escapeHtml(ai.noNetworkTransport) + '</span></div></details>';
     const lens = (id: string, label: string, hint: string, on?: boolean): string =>
       '<label title="' + this.escapeHtml(hint) + '"><input type="checkbox" id="' + id + '"' +
       ck(on) + '> ' + this.escapeHtml(label) + '</label>';
     return (
-      '<div class="action-card">' +
+      '<div class="action-card" data-advice-provider="optimizer">' +
       head('') +
+      optimizerSnoozedHtml +
       '<p class="action-card-howto">' + t.optimizerHowto + '</p>' +
       '<textarea id="optDraft" class="opt-input" rows="4" placeholder="' +
       this.escapeHtml(t.optimizerPlaceholder) + '">' + draftVal + '</textarea>' +
@@ -3624,26 +6248,14 @@ export class UsageWebviewProvider {
       lens('optDistil', t.optimizerDistil, t.optimizerDistilHint, st?.distil) +
       lens('optAesthetic', t.optimizerAesthetic, t.optimizerAestheticHint, st?.aesthetic) +
       '<button class="btn-primary" id="optRunBtn" data-run="' +
-      this.escapeHtml(t.optimizerRun) + '" data-running="' +
+      this.escapeHtml(ai.previewPayload) + '" data-running="' +
       this.escapeHtml(t.optimizerRunning) + '" onclick="runOptimizer()">' +
-      t.optimizerRun + '</button>' +
+      ai.previewPayload + '</button>' +
       '</div>' +
       '<div id="optError" class="opt-error" style="display:' + (hasErr ? '' : 'none') + '">' +
       (hasErr ? this.escapeHtml(st!.error as string) : '') + '</div>' +
-      '<div id="optResult" class="opt-result" style="display:' + (hasResult ? '' : 'none') + '">' +
-      '<h4 class="opt-subhead">' + t.optimizerPromptHeading + '</h4>' +
-      '<div class="opt-output"><pre id="optPrompt">' +
-      (st && st.prompt ? this.escapeHtml(st.prompt) : '') + '</pre>' +
-      '<button class="opt-copy" data-copy="' + this.escapeHtml(t.optimizerCopy) +
-      '" data-copied="' + this.escapeHtml(t.optimizerCopied) +
-      '" title="' + this.escapeHtml(t.optimizerCopy) + '" onclick="copyOptPrompt(this)">' +
-      '<span class="opt-copy-ico">⧉</span><span class="opt-copy-lbl">' +
-      this.escapeHtml(t.optimizerCopy) + '</span></button></div>' +
-      '<h4 class="opt-subhead">' + t.optimizerSettingsHeading + '</h4>' +
-      '<div id="optSettings" class="opt-settings" data-raw="' +
-      (st && st.settings ? this.escapeHtml(st.settings) : '') + '">' +
-      (st && st.settings ? this.escapeHtml(st.settings) : '') + '</div>' +
-      '</div>' +
+      optimizerPreviewHtml +
+      optimizerResultHtml +
       '</div>'
     );
   }
@@ -4010,7 +6622,8 @@ export class UsageWebviewProvider {
         : '<p class="table-hint">' + this.escapeHtml(copy.recommendationPartial) + '</p>';
       return '<div class="action-card"><div class="action-card-head"><span class="action-icon">✨</span>' +
         '<div class="action-card-titles"><h3>' + this.escapeHtml(copy.optimization) + '</h3>' +
-        '<p class="action-card-desc">' + this.escapeHtml(copy.structuralProxy) + '</p></div></div></div>' +
+        '<p class="action-card-desc">' + this.escapeHtml(copy.structuralProxy) + '</p></div></div>' +
+        this.renderAdviceEffectivenessBody('codex') + '</div>' +
         '<div class="daily-breakdown"><div class="section-header"><h3>' +
         this.escapeHtml(copy.behavior + ' · ' + copy.last30Days) + '</h3></div>' +
         partial + behaviorSummary + insightHtml + '</div>';
@@ -4193,7 +6806,9 @@ export class UsageWebviewProvider {
       // click-to-expand that month's per-day composition (reuses the table's
       // month-detail round-trip).
       const colOpen = provider === 'claude' && it.key
-        ? '<div class="hc-col hc-col-clickable" onclick="toggleMonthlyDetail(\'' + it.key + '\')" title="' +
+        ? '<div class="hc-col hc-col-clickable" data-date="' + this.escapeHtml(it.key) +
+          '" role="button" tabindex="0" aria-expanded="false" aria-controls="monthly-detail-' +
+          this.escapeHtml(it.key) + '" onclick="toggleMonthlyDetail(\'' + it.key + '\')" title="' +
           this.escapeHtml(it.label) + ' — ' + I18n.formatNumber(total) + '">'
         : '<div class="hc-col">';
       bars +=
@@ -4351,7 +6966,10 @@ export class UsageWebviewProvider {
     provider: SettingProvider = 'claude',
   ): string {
     if (sortedData.length === 0) {
-      return '<div class="no-chart-data">No data available</div>';
+      const message = provider === 'codex'
+        ? I18n.t.providers.codex.noDailyData
+        : I18n.t.statusBar.noData;
+      return '<div class="no-chart-data" role="status">' + this.escapeHtml(message) + '</div>';
     }
     if (provider === 'codex') {
       const rows = sortedData as Array<{
@@ -4371,9 +6989,14 @@ export class UsageWebviewProvider {
         const cost = data.apiEquivalent;
         const height = maxCost > 0 ? (cost.equivalentUsd / maxCost) * maxHeight : 2;
         const costLabel = cost.pricedTokens > 0 ? I18n.formatCurrency(cost.equivalentUsd) : '—';
+        const hasHourlyDetail = !monthly && Object.prototype.hasOwnProperty.call(
+          this.codexView?.last30DaysHourlyByDay ?? {},
+          date,
+        );
         return '<div class="hc-col" data-date="' + this.escapeHtml(date) + '">' +
           '<div class="hc-barval">' + costLabel + '</div>' +
-          '<div class="chart-bar cost-bar cost-stacked" style="height:' + height + 'px" ' +
+          '<div class="chart-bar cost-bar cost-stacked' + (hasHourlyDetail ? ' clickable' : '') +
+          '" style="height:' + height + 'px" ' +
           'data-cost="' + cost.equivalentUsd + '" data-priced-tokens="' + cost.pricedTokens + '" ' +
           'data-input="' + data.total.processed + '" data-output="' + data.total.fresh + '" ' +
           'data-cache-creation="' + data.total.output + '" data-cache-read="' + data.total.reasoning + '" ' +
@@ -4457,7 +7080,8 @@ export class UsageWebviewProvider {
    */
   private renderCodexHourlyChart(rows: CodexHourlyUsageView[]): string {
     if (rows.length === 0) {
-      return '<div class="no-chart-data">No data available</div>';
+      return '<div class="no-chart-data" role="status">' +
+        this.escapeHtml(I18n.t.providers.codex.noDailyData) + '</div>';
     }
     const maxCost = Math.max(...rows.map((row) => row.apiEquivalent.equivalentUsd), 0);
     const hasPricedCost = rows.some((row) => row.apiEquivalent.pricedTokens > 0);
@@ -4482,7 +7106,7 @@ export class UsageWebviewProvider {
         this.codexCostStackHtml(cost, height) + '</div></div>';
     }).join('');
     const labels = rows.map((row) =>
-      '<div class="hc-xlabel">' + this.escapeHtml(row.hour) + '</div>'
+      '<div class="hc-xlabel">' + this.escapeHtml(row.label) + '</div>'
     ).join('');
     return '<div class="hc-wrap"><div class="hc-yaxis">' +
       '<span class="hc-yval">' + costAxisLabel(maxCost) + '</span>' +
@@ -4496,7 +7120,8 @@ export class UsageWebviewProvider {
 
   private renderHourlyChart(): string {
     if (this.hourlyDataForToday.length === 0) {
-      return '<div class="no-chart-data">No data available</div>';
+      return '<div class="no-chart-data" role="status">' +
+        this.escapeHtml(I18n.t.statusBar.noData) + '</div>';
     }
 
     const sortedData = [...this.hourlyDataForToday].sort((a, b) => a.hour.localeCompare(b.hour));
@@ -4562,13 +7187,39 @@ export class UsageWebviewProvider {
 
   private getStyles(): string {
     return `
+      :root {
+        color-scheme: light dark;
+        --ccu-space-1: 4px;
+        --ccu-space-2: 8px;
+        --ccu-space-3: 12px;
+        --ccu-space-4: 16px;
+        --ccu-space-5: 20px;
+        --ccu-space-6: 24px;
+        --ccu-radius-control: 4px;
+        --ccu-radius-panel: 8px;
+        --ccu-radius-lg: 12px;
+        --ccu-border: var(--vscode-panel-border, rgba(127, 127, 127, 0.35));
+        /* Description text must retain 4.5:1 in both Light+ and Dark+. Some
+           input/editor-widget surfaces are deliberately more contrasted than
+           ordinary text, so use the editor canvas and let the shared border
+           carry the raised-card hierarchy. */
+        --ccu-surface-raised: var(--vscode-editor-background);
+        --ccu-surface-subtle: var(--vscode-editorWidget-background, var(--vscode-input-background));
+        --ccu-surface-muted: var(--vscode-editorWidget-background, var(--vscode-input-background));
+        /* Dashboard figures follow VS Code's UI typography. The prior editor
+           monospace override made dense cards and tables feel visually foreign;
+           true code/Markdown fields opt into the editor font directly. */
+        --ccu-data-font: var(--vscode-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif);
+        --ccu-focus: var(--vscode-focusBorder, #007fd4);
+      }
+
       body {
         font-family: var(--vscode-font-family);
         font-size: var(--vscode-font-size);
         color: var(--vscode-foreground);
         background-color: var(--vscode-editor-background);
         margin: 0;
-        padding: 16px;
+        padding: var(--ccu-space-4);
       }
 
       .container {
@@ -4581,9 +7232,10 @@ export class UsageWebviewProvider {
         display: flex;
         justify-content: space-between;
         align-items: center;
-        margin-bottom: 16px;
-        border-bottom: 1px solid var(--vscode-panel-border);
-        padding-bottom: 16px;
+        gap: var(--ccu-space-4);
+        margin-bottom: var(--ccu-space-4);
+        border-bottom: 1px solid var(--ccu-border);
+        padding-bottom: var(--ccu-space-4);
       }
 
 
@@ -4594,19 +7246,31 @@ export class UsageWebviewProvider {
 
       .actions {
         display: flex;
-        gap: 8px;
+        justify-content: flex-end;
+        flex-wrap: wrap;
+        gap: var(--ccu-space-2);
       }
 
       button {
         background: var(--vscode-button-background);
         color: var(--vscode-button-foreground);
         border: none;
-        border-radius: 4px;
-        padding: 8px 12px;
+        border-radius: var(--ccu-radius-control);
+        padding: var(--ccu-space-2) var(--ccu-space-3);
         cursor: pointer;
         font-size: 12px;
       }
 
+      button:focus-visible,
+      summary:focus-visible,
+      input:focus-visible,
+      select:focus-visible,
+      textarea:focus-visible,
+      [tabindex="0"]:focus-visible {
+        outline: 2px solid var(--ccu-focus);
+        outline-offset: 2px;
+      }
+
       button:hover {
         background: var(--vscode-button-hoverBackground);
       }
@@ -4908,6 +7572,44 @@ export class UsageWebviewProvider {
         transform: translateX(18px);
         background: #fff;
       }
+      .local-data-controls { margin-top: 26px; }
+      .local-data-heading {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 12px;
+        margin: 12px 0 8px;
+      }
+      .local-data-heading h4 { margin: 0; font-size: 12px; }
+      .local-data-table-wrap { max-width: 100%; overflow-x: auto; }
+      .local-data-table { min-width: 920px; }
+      .local-data-table td { vertical-align: top; font-size: 11px; }
+      .local-data-actions {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 8px;
+      }
+      .local-data-actions select {
+        max-width: 260px;
+        min-width: 180px;
+        color: var(--vscode-dropdown-foreground);
+        background: var(--vscode-dropdown-background);
+        border: 1px solid var(--vscode-dropdown-border, var(--ccu-border));
+        border-radius: 4px;
+        padding: 4px 6px;
+      }
+      .local-data-scope-label { font-size: 11px; color: var(--vscode-descriptionForeground); }
+      .local-data-danger {
+        color: var(--vscode-errorForeground);
+        border-color: var(--vscode-errorForeground);
+      }
+      @media (max-width: 520px) {
+        .set-row { flex-direction: column; gap: 6px; }
+        .set-control, .set-control input, .set-control select, .set-control textarea { width: 100%; }
+        .local-data-actions { align-items: stretch; flex-direction: column; }
+        .local-data-actions > * { width: 100%; max-width: none; }
+      }
 
       /* Manual refresh is also the explicit accelerated Codex catch-up path. */
       .btn-refresh-now {
@@ -5038,16 +7740,24 @@ export class UsageWebviewProvider {
 
       .tabs {
         display: flex;
-        margin-bottom: 20px;
-        border-bottom: 1px solid var(--vscode-panel-border);
+        gap: var(--ccu-space-1);
+        max-width: 100%;
+        margin-bottom: var(--ccu-space-5);
+        border-bottom: 1px solid var(--ccu-border);
+        overflow-x: auto;
+        overflow-y: hidden;
+        overscroll-behavior-inline: contain;
+        scrollbar-width: thin;
       }
 
       .tab {
+        flex: 0 0 auto;
         background: transparent;
         border: none;
-        padding: 8px 16px;
+        padding: var(--ccu-space-2) var(--ccu-space-4);
         cursor: pointer;
         border-bottom: 2px solid transparent;
+        white-space: nowrap;
         /* Explicit foreground colour — otherwise the inherited button
            foreground (white) becomes invisible on light themes. (Fixes
            upstream issue #11.) */
@@ -5070,21 +7780,25 @@ export class UsageWebviewProvider {
       }
 
       .usage-summary {
-        margin-bottom: 24px;
+        margin-bottom: var(--ccu-space-6);
       }
 
       .summary-grid {
         display: grid;
         grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
-        gap: 12px;
+        gap: var(--ccu-space-3);
       }
 
       .summary-item {
-        text-align: center;
-        padding: 16px;
-        background: var(--vscode-input-background);
-        border-radius: 8px;
-        border: 1px solid var(--vscode-input-border);
+        display: flex;
+        min-height: 68px;
+        flex-direction: column;
+        justify-content: center;
+        text-align: left;
+        padding: var(--ccu-space-3) 14px;
+        background: var(--ccu-surface-raised);
+        border-radius: var(--ccu-radius-panel);
+        border: 1px solid var(--ccu-border);
       }
 
       .summary-item .label {
@@ -5096,6 +7810,8 @@ export class UsageWebviewProvider {
       .summary-item .value {
         font-size: 18px;
         font-weight: bold;
+        font-family: var(--ccu-data-font);
+        font-variant-numeric: tabular-nums;
       }
 
       .summary-item .value.cost {
@@ -5114,14 +7830,14 @@ export class UsageWebviewProvider {
       .model-list {
         display: flex;
         flex-direction: column;
-        gap: 12px;
+        gap: var(--ccu-space-3);
       }
 
       .model-item {
-        padding: 12px;
-        background: var(--vscode-input-background);
+        padding: var(--ccu-space-3);
+        background: var(--ccu-surface-raised);
         border-radius: 6px;
-        border: 1px solid var(--vscode-input-border);
+        border: 1px solid var(--ccu-border);
       }
 
       /* <details>/<summary> reset: remove the default triangle, position our own */
@@ -5145,7 +7861,10 @@ export class UsageWebviewProvider {
         display: flex;
         align-items: center;
         gap: 8px;
-        margin-bottom: 8px;
+        margin-bottom: 0;
+      }
+      details.model-item[open] > .model-header {
+        margin-bottom: var(--ccu-space-2);
       }
       /* Model name sits flush against the disclosure triangle on the left;
          the cost is pushed to the far right by margin-left:auto. Avoids the
@@ -5161,10 +7880,16 @@ export class UsageWebviewProvider {
         color: var(--vscode-symbolIcon-functionForeground);
       }
 
-      .model-cost {
+      .model-metric {
         font-weight: bold;
-        color: var(--vscode-charts-green);
+        color: var(--vscode-foreground);
         margin-left: auto;
+        font-family: var(--ccu-data-font);
+        font-variant-numeric: tabular-nums;
+      }
+
+      .model-cost {
+        color: var(--vscode-charts-green);
       }
 
       .model-details {
@@ -5198,16 +7923,16 @@ export class UsageWebviewProvider {
 
       .chart-tabs {
         display: flex;
-        gap: 4px;
-        margin-bottom: 16px;
+        gap: var(--ccu-space-1);
+        margin-bottom: var(--ccu-space-4);
         flex-wrap: wrap;
       }
 
       .chart-tab {
         background: var(--vscode-button-secondaryBackground);
         color: var(--vscode-button-secondaryForeground);
-        border: 1px solid var(--vscode-input-border);
-        border-radius: 4px;
+        border: 1px solid var(--ccu-border);
+        border-radius: var(--ccu-radius-control);
         padding: 6px 12px;
         font-size: 11px;
         cursor: pointer;
@@ -5225,10 +7950,10 @@ export class UsageWebviewProvider {
       }
 
       .chart-container {
-        background: var(--vscode-input-background);
-        border: 1px solid var(--vscode-input-border);
-        border-radius: 8px;
-        padding: 16px;
+        background: var(--ccu-surface-subtle);
+        border: 1px solid var(--ccu-border);
+        border-radius: var(--ccu-radius-panel);
+        padding: var(--ccu-space-4);
         margin-bottom: 20px;
         height: 180px;
         overflow-x: auto;
@@ -5343,6 +8068,28 @@ export class UsageWebviewProvider {
         margin-top: 12px;
       }
 
+      .weekly-value-details {
+        margin-top: var(--ccu-space-3);
+        border-top: 1px solid var(--ccu-border);
+      }
+
+      .weekly-value-details > summary {
+        width: fit-content;
+        padding-top: var(--ccu-space-3);
+        color: var(--vscode-textLink-foreground);
+        cursor: pointer;
+        font-weight: 600;
+      }
+
+      .weekly-value-details > summary:focus-visible {
+        outline: 1px solid var(--ccu-focus);
+        outline-offset: 3px;
+      }
+
+      .range-empty-hint {
+        margin-bottom: var(--ccu-space-3);
+      }
+
       .daily-table {
         width: 100%;
         border-collapse: collapse;
@@ -5382,7 +8129,8 @@ export class UsageWebviewProvider {
 
       .number-cell {
         text-align: right;
-        font-family: var(--vscode-editor-font-family);
+        font-family: var(--ccu-data-font);
+        font-variant-numeric: tabular-nums;
         /* Keep figures on one line: compact (k/M) numbers fit the panel with no
          * horizontal scroll; full integer numbers overflow so the table (only)
          * scrolls, while the chart above keeps its own independent scroll. */
@@ -5445,6 +8193,9 @@ export class UsageWebviewProvider {
       .loading, .error, .no-data {
         text-align: center;
         padding: 40px 20px;
+        border: 1px dashed var(--ccu-border);
+        border-radius: var(--ccu-radius-panel);
+        background: var(--ccu-surface-raised);
       }
 
       .spinner {
@@ -5804,58 +8555,294 @@ export class UsageWebviewProvider {
         border: 1px solid var(--vscode-panel-border);
         border-radius: 999px;
         color: var(--vscode-foreground);
-        cursor: pointer;
-        user-select: none;
+        cursor: pointer;
+        user-select: none;
+      }
+      .sc-check:hover {
+        border-color: var(--vscode-focusBorder);
+      }
+      .share-preview {
+        margin: 12px 0 0;
+        padding: 10px;
+        border: 1px solid var(--vscode-panel-border);
+        border-radius: 10px;
+        overflow: auto;
+        max-height: 640px;
+        background:
+          linear-gradient(45deg, #f3f3f3 25%, transparent 25%, transparent 75%, #f3f3f3 75%),
+          linear-gradient(45deg, #f3f3f3 25%, #fff 25%, #fff 75%, #f3f3f3 75%);
+        background-size: 20px 20px;
+        background-position: 0 0, 10px 10px;
+      }
+      .share-preview svg {
+        display: block;
+        width: 100%;
+        height: auto;
+        max-width: 560px;
+        margin: 0 auto;
+        box-shadow: 0 2px 12px rgba(0,0,0,0.18);
+        border-radius: 8px;
+      }
+      .share-preview p {
+        text-align: center;
+      }
+      .share-actions {
+        display: flex;
+        gap: 8px;
+        flex-wrap: wrap;
+        margin-top: 4px;
+      }
+
+      /* Optional token heatmap panel (All tab). The SVG has a fixed size; let it
+       * scroll horizontally on narrow panels rather than squash. */
+      .heatmap-panel {
+        margin: 4px 0 22px;
+      }
+      .heatmap-svg {
+        overflow-x: auto;
+        border: 1px solid var(--vscode-panel-border);
+        border-radius: 6px;
+        padding: 6px;
+        background: #ffffff;
+      }
+      .heatmap-svg svg {
+        display: block;
+      }
+      .combined-heatmap-panel {
+        position: relative;
+        overflow: hidden;
+        padding: var(--ccu-space-5);
+        border: 1px solid var(--ccu-border);
+        border-left: 4px solid var(--vscode-charts-purple, #4f2f87);
+        border-radius: var(--ccu-radius-lg);
+        background: var(--ccu-surface-raised);
+      }
+      .combined-share-header {
+        display: flex;
+        align-items: flex-start;
+        justify-content: space-between;
+        gap: var(--ccu-space-4);
+        margin-bottom: var(--ccu-space-5);
+      }
+      .combined-share-header h2 {
+        margin: 3px 0 5px;
+      }
+      .combined-share-header p {
+        max-width: 760px;
+        margin: 0;
+        color: var(--vscode-descriptionForeground);
+        line-height: 1.5;
+      }
+      .combined-share-eyebrow {
+        color: var(--vscode-charts-purple, #8668c7);
+        font-size: 10px;
+        font-weight: 700;
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+      }
+      .combined-private-badge {
+        flex: 0 0 auto;
+        padding: 5px 9px;
+        border: 1px solid var(--ccu-border);
+        border-radius: 999px;
+        background: var(--ccu-surface-subtle);
+        color: var(--vscode-foreground);
+        font-size: 10px;
+        white-space: nowrap;
+      }
+      .combined-share-layout {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr);
+        gap: var(--ccu-space-4);
+        align-items: start;
+      }
+      .combined-preview-column,
+      .combined-config-card {
+        min-width: 0;
+      }
+      .combined-preview-toolbar {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        min-height: 24px;
+        margin-bottom: var(--ccu-space-2);
+        color: var(--vscode-descriptionForeground);
+        font-size: 11px;
+      }
+      .combined-preview-toolbar strong {
+        color: var(--vscode-foreground);
+        font-size: 12px;
+      }
+      .combined-config-card {
+        padding: var(--ccu-space-4);
+        border: 1px solid var(--ccu-border);
+        border-radius: var(--ccu-radius-panel);
+        background: var(--ccu-surface-subtle);
+      }
+      .combined-config-card h3 {
+        margin: 0 0 var(--ccu-space-3);
+        font-size: 13px;
+      }
+      .combined-config-card .sc-field > span {
+        color: var(--vscode-foreground);
+      }
+      .combined-heatmap-controls {
+        display: grid;
+        grid-template-columns: minmax(0, 2fr) repeat(2, minmax(160px, 0.8fr));
+        gap: var(--ccu-space-3);
+        margin-bottom: var(--ccu-space-4);
+      }
+      .combined-heatmap-controls .sc-field input,
+      .combined-heatmap-controls .sc-field select {
+        box-sizing: border-box;
+        width: 100%;
+        min-height: 30px;
+        padding: 5px 8px;
+        border: 1px solid var(--vscode-input-border, var(--ccu-border));
+        border-radius: var(--ccu-radius-control);
+        background: var(--vscode-input-background);
+        color: var(--vscode-input-foreground, var(--vscode-foreground));
+        font-family: var(--vscode-font-family);
+      }
+      .combined-palette-fieldset {
+        min-width: 0;
+        margin: 0 0 var(--ccu-space-4);
+        padding: var(--ccu-space-3) 0 0;
+        border: 0;
+        border-top: 1px solid var(--ccu-border);
+      }
+      .combined-palette-fieldset legend {
+        padding: 0 6px 0 0;
+        color: var(--vscode-foreground);
+        font-size: 10px;
+        font-weight: 700;
+        letter-spacing: 0.06em;
+        text-transform: uppercase;
+      }
+      .combined-palette-options {
+        display: grid;
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        gap: 6px;
+      }
+      .combined-palette-choice {
+        display: grid;
+        grid-template-columns: 14px minmax(42px, 1fr);
+        gap: 4px 6px;
+        align-items: center;
+        padding: 7px;
+        border: 1px solid var(--ccu-border);
+        border-radius: 6px;
+        background: var(--ccu-surface-raised);
+        cursor: pointer;
+        font-size: 10px;
+      }
+      .combined-palette-choice:has(input:checked) {
+        border-color: var(--vscode-focusBorder);
+        box-shadow: inset 0 0 0 1px var(--vscode-focusBorder);
+      }
+      .combined-palette-choice input {
+        grid-column: 1;
+        grid-row: 1;
+        margin: 0;
+      }
+      .combined-palette-swatch {
+        grid-column: 2;
+        grid-row: 2;
+        display: flex;
+        height: 7px;
+        overflow: hidden;
+        border-radius: 999px;
+      }
+      .combined-palette-choice > span:last-child {
+        grid-column: 2;
+        grid-row: 1;
+        min-width: 0;
+        line-height: 1.25;
+      }
+      .combined-palette-swatch i {
+        flex: 1 1 0;
+      }
+      .combined-custom-accent {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--ccu-space-2);
+        margin-top: var(--ccu-space-2);
+        color: var(--vscode-foreground);
+        font-size: 11px;
+      }
+      .combined-custom-accent input {
+        width: 42px;
+        height: 26px;
+        padding: 2px;
+        border: 1px solid var(--ccu-border);
+        border-radius: 5px;
+        background: var(--vscode-input-background);
+      }
+      .combined-privacy-toggle {
+        width: fit-content;
+        margin-bottom: var(--ccu-space-2);
+      }
+      .combined-privacy-preview {
+        padding: var(--ccu-space-2) var(--ccu-space-3);
+        border-left: 3px solid var(--vscode-testing-iconPassed, #2ea043);
+        border-radius: var(--ccu-radius-control);
+        background: var(--ccu-surface-muted);
+        color: var(--vscode-foreground);
+        font-size: 10px;
+        line-height: 1.4;
       }
-      .sc-check:hover {
-        border-color: var(--vscode-focusBorder);
+      .combined-privacy-preview p {
+        margin: 3px 0;
       }
-      .share-preview {
-        margin: 12px 0 0;
-        padding: 10px;
-        border: 1px solid var(--vscode-panel-border);
-        border-radius: 10px;
-        overflow: auto;
-        max-height: 640px;
-        background:
-          linear-gradient(45deg, #f3f3f3 25%, transparent 25%, transparent 75%, #f3f3f3 75%),
-          linear-gradient(45deg, #f3f3f3 25%, #fff 25%, #fff 75%, #f3f3f3 75%);
-        background-size: 20px 20px;
-        background-position: 0 0, 10px 10px;
+      .combined-activity-disclaimer {
+        margin: var(--ccu-space-2) var(--ccu-space-1) 0;
+        color: var(--vscode-descriptionForeground);
+        font-size: 11px;
+        line-height: 1.45;
       }
-      .share-preview svg {
-        display: block;
-        width: 100%;
-        height: auto;
-        max-width: 560px;
-        margin: 0 auto;
-        box-shadow: 0 2px 12px rgba(0,0,0,0.18);
-        border-radius: 8px;
+      .combined-share-actions {
+        margin-top: var(--ccu-space-3);
+        padding-top: var(--ccu-space-3);
+        border-top: 1px solid var(--ccu-border);
       }
-      .share-preview p {
-        text-align: center;
+      .combined-output-panel {
+        margin-top: var(--ccu-space-4);
+        border-top: 1px solid var(--ccu-border);
+        padding-top: var(--ccu-space-3);
       }
-      .share-actions {
-        display: flex;
-        gap: 8px;
-        flex-wrap: wrap;
-        margin-top: 4px;
+      .combined-output-panel summary {
+        width: fit-content;
+        cursor: pointer;
+        color: var(--vscode-descriptionForeground);
+        font-size: 11px;
+        font-weight: 600;
       }
-
-      /* Optional token heatmap panel (All tab). The SVG has a fixed size; let it
-       * scroll horizontally on narrow panels rather than squash. */
-      .heatmap-panel {
-        margin: 4px 0 22px;
+      .combined-markdown {
+        width: 100%;
+        min-height: 46px;
+        margin-top: var(--ccu-space-2);
+        resize: vertical;
+        box-sizing: border-box;
+        border: 1px solid var(--vscode-input-border, var(--ccu-border));
+        border-radius: var(--ccu-radius-control);
+        padding: var(--ccu-space-2);
+        background: var(--vscode-input-background);
+        color: var(--vscode-input-foreground, var(--vscode-foreground));
+        font-family: var(--vscode-editor-font-family, ui-monospace, monospace);
       }
-      .heatmap-svg {
-        overflow-x: auto;
-        border: 1px solid var(--vscode-panel-border);
-        border-radius: 6px;
-        padding: 6px;
-        background: #ffffff;
+      .combined-heatmap-preview {
+        margin: 0;
+        padding: var(--ccu-space-3);
+        border-radius: var(--ccu-radius-panel);
+        background: var(--vscode-editor-background);
       }
-      .heatmap-svg svg {
-        display: block;
+      .combined-heatmap-preview svg {
+        width: 100%;
+        max-width: none;
+        height: auto;
+        border-radius: 12px;
+        box-shadow: 0 8px 26px rgba(24, 16, 36, 0.18);
       }
 
       /* Clickable month bars in the all-time composition chart (drill to daily). */
@@ -5874,11 +8861,21 @@ export class UsageWebviewProvider {
       }
 
       .cost-comp-head {
+        display: flex;
+        align-items: baseline;
+        justify-content: space-between;
+        flex-wrap: wrap;
+        gap: 4px 12px;
         font-size: 12px;
         color: var(--vscode-descriptionForeground);
         margin-bottom: 6px;
       }
 
+      .cost-comp-head strong {
+        color: var(--vscode-foreground);
+        font-weight: 600;
+      }
+
       .cost-comp-bar {
         display: flex;
         height: 14px;
@@ -6304,120 +9301,453 @@ export class UsageWebviewProvider {
       [data-codex-last30-daily] .daily-table th {
         white-space: nowrap;
       }
-
-      .git-badge {
-        display: inline-block;
-        font-size: 9px;
-        text-transform: uppercase;
-        letter-spacing: 0.5px;
-        padding: 1px 5px;
-        border-radius: 3px;
-        background: var(--vscode-badge-background);
-        color: var(--vscode-badge-foreground);
-        vertical-align: middle;
+
+      .git-badge {
+        display: inline-block;
+        font-size: 9px;
+        text-transform: uppercase;
+        letter-spacing: 0.5px;
+        padding: 1px 5px;
+        border-radius: 3px;
+        background: var(--vscode-badge-background);
+        color: var(--vscode-badge-foreground);
+        vertical-align: middle;
+      }
+
+      .cbar-total {
+        font-size: 12px;
+        color: var(--vscode-descriptionForeground);
+      }
+
+      .cbar-list {
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+        margin: 8px 0 16px;
+      }
+
+      .cbar-subhead {
+        margin: 16px 0 4px;
+        font-size: 14px;
+      }
+
+      .cbar-row {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        font-size: 12px;
+      }
+
+      .cbar-label {
+        width: 160px;
+        flex-shrink: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .cbar-track {
+        flex: 1;
+        height: 16px;
+        min-width: 40px;
+        background: var(--vscode-input-background);
+        border: 1px solid var(--vscode-input-border);
+        border-radius: 3px;
+        overflow: hidden;
+      }
+
+      .cbar-fill {
+        height: 100%;
+        border-radius: 2px;
+        min-width: 1px;
+      }
+
+      .cbar-val {
+        width: 96px;
+        flex-shrink: 0;
+        text-align: right;
+        font-family: var(--vscode-editor-font-family);
+      }
+
+      .cbar-pct {
+        width: 52px;
+        flex-shrink: 0;
+        text-align: right;
+        color: var(--vscode-descriptionForeground);
+      }
+
+      .cf-1 {
+        background: var(--vscode-charts-blue);
+      }
+
+      .cf-2 {
+        background: var(--vscode-charts-yellow);
+      }
+
+      .cf-3 {
+        background: var(--vscode-charts-purple);
+      }
+
+      .cf-4 {
+        background: var(--vscode-charts-green);
+      }
+
+      .cf-5 {
+        background: var(--vscode-charts-red);
+      }
+
+      .provider-tabs {
+        display: flex;
+        gap: 6px;
+        margin: 4px 0 18px;
+        padding-bottom: 10px;
+        max-width: 100%;
+        border-bottom: 1px solid var(--ccu-border);
+        overflow-x: auto;
+        overflow-y: hidden;
+        overscroll-behavior-inline: contain;
+        scrollbar-width: thin;
+      }
+      .provider-tab {
+        flex: 0 0 auto;
+        white-space: nowrap;
+        border: 1px solid var(--ccu-border);
+        border-radius: 999px;
+        padding: 5px 13px;
+        background: transparent;
+        color: var(--vscode-foreground);
+        cursor: pointer;
+      }
+      .provider-tab.active {
+        background: var(--vscode-button-background);
+        color: var(--vscode-button-foreground);
+        border-color: var(--vscode-button-background);
+      }
+
+      .advice-effectiveness-body {
+        margin-top: 13px;
+        padding-top: 14px;
+        border-top: 1px solid var(--vscode-panel-border);
+        background: var(--vscode-editor-background);
+        min-width: 0;
+      }
+      .advice-effectiveness-heading h4,
+      .advice-feedback-section h5,
+      .advice-payload-section h5 {
+        margin: 0;
+        font-size: 12px;
+        font-weight: 600;
+      }
+      .advice-effectiveness-heading h4 {
+        display: flex;
+        align-items: center;
+        gap: 7px;
+      }
+      .advice-effectiveness-heading p,
+      .advice-candidate-note,
+      .advice-local-note,
+      .advice-inline-status {
+        margin: 4px 0 0;
+        color: var(--vscode-descriptionForeground);
+        font-size: 11px;
+        line-height: 1.45;
+      }
+      .advice-candidate-note {
+        margin-top: 7px;
+      }
+      .advice-spine {
+        position: relative;
+        display: grid;
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        gap: 10px;
+        list-style: none;
+        margin: 14px 0 12px;
+        padding: 0;
+      }
+      .advice-spine::before {
+        content: "";
+        position: absolute;
+        z-index: 0;
+        left: 10%;
+        right: 10%;
+        top: 13px;
+        height: 1px;
+        background: var(--vscode-textLink-foreground);
+      }
+      .advice-spine li {
+        position: relative;
+        z-index: 1;
+        min-width: 0;
+      }
+      .advice-step-marker {
+        display: flex;
+        width: 26px;
+        height: 26px;
+        margin: 0 auto 7px;
+        align-items: center;
+        justify-content: center;
+        border: 1px solid var(--vscode-textLink-foreground);
+        border-radius: 999px;
+        background: var(--vscode-editor-background);
+        color: var(--vscode-textLink-foreground);
+        font-size: 10px;
+        font-weight: 700;
+      }
+      .advice-spine li > div {
+        text-align: center;
+      }
+      .advice-spine strong {
+        font-size: 11px;
+      }
+      .advice-spine p {
+        margin: 3px 0 0;
+        color: var(--vscode-descriptionForeground);
+        font-size: 10.5px;
+        line-height: 1.4;
+        overflow-wrap: anywhere;
+      }
+      .advice-step-caveat {
+        font-size: 10px;
+      }
+      .advice-feedback-section,
+      .advice-payload-section {
+        margin-top: 12px;
+        padding-top: 11px;
+        border-top: 1px solid var(--vscode-panel-border);
+      }
+      .advice-feedback-group {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 7px;
+        margin-top: 7px;
+      }
+      .advice-feedback-button {
+        padding: 4px 9px;
+        border: 1px solid var(--vscode-button-secondaryBackground, var(--vscode-panel-border));
+        border-radius: 999px;
+        background: transparent;
+        color: var(--vscode-foreground);
+        cursor: pointer;
+        font-size: 11px;
+      }
+      .advice-feedback-button.is-selected {
+        border-width: 2px;
+        border-color: var(--vscode-focusBorder);
+        font-weight: 600;
+      }
+      .advice-feedback-button:disabled,
+      .advice-consent input:disabled {
+        opacity: 0.55;
+        cursor: default;
+      }
+      .advice-feedback-button:focus-visible,
+      .advice-consent input:focus-visible,
+      .advice-payload-actions button:focus-visible,
+      .advice-payload-preview summary:focus-visible,
+      .advice-payload-preview pre:focus-visible {
+        outline: 2px solid var(--vscode-focusBorder);
+        outline-offset: 2px;
       }
-
-      .cbar-total {
-        font-size: 12px;
+      .advice-consent {
+        display: grid;
+        gap: 8px;
+        margin: 9px 0 0;
+        padding: 10px;
+        border: 1px solid var(--vscode-panel-border);
+        border-radius: 6px;
+      }
+      .advice-consent legend {
+        padding: 0 5px;
         color: var(--vscode-descriptionForeground);
+        font-size: 10px;
       }
-
-      .cbar-list {
+      .advice-consent label {
         display: flex;
-        flex-direction: column;
+        align-items: flex-start;
         gap: 8px;
-        margin: 8px 0 16px;
+        cursor: pointer;
       }
-
-      .cbar-subhead {
-        margin: 16px 0 4px;
-        font-size: 14px;
+      .advice-consent input {
+        flex: 0 0 auto;
+        margin-top: 2px;
       }
-
-      .cbar-row {
+      .advice-consent label span {
+        display: grid;
+        gap: 2px;
+        min-width: 0;
+      }
+      .advice-consent label strong,
+      .advice-consent label small {
+        font-size: 11px;
+        line-height: 1.4;
+      }
+      .advice-consent label small {
+        color: var(--vscode-descriptionForeground);
+      }
+      .advice-payload-actions {
         display: flex;
+        flex-wrap: wrap;
         align-items: center;
-        gap: 10px;
-        font-size: 12px;
+        gap: 8px;
+        margin-top: 9px;
       }
-
-      .cbar-label {
-        width: 160px;
-        flex-shrink: 0;
-        overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
+      .advice-payload-actions span {
+        color: var(--vscode-descriptionForeground);
+        font-size: 10.5px;
       }
-
-      .cbar-track {
-        flex: 1;
-        height: 16px;
-        min-width: 40px;
-        background: var(--vscode-input-background);
-        border: 1px solid var(--vscode-input-border);
-        border-radius: 3px;
+      .advice-payload-preview {
+        margin-top: 9px;
+        border: 1px solid var(--vscode-panel-border);
+        border-radius: 6px;
         overflow: hidden;
       }
-
-      .cbar-fill {
-        height: 100%;
-        border-radius: 2px;
-        min-width: 1px;
+      .advice-payload-preview summary {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 8px;
+        padding: 7px 9px;
+        cursor: pointer;
+        background: var(--vscode-sideBar-background, var(--vscode-editor-background));
+        font-size: 11px;
+        font-weight: 600;
       }
-
-      .cbar-val {
-        width: 96px;
-        flex-shrink: 0;
-        text-align: right;
-        font-family: var(--vscode-editor-font-family);
+      .advice-seal-stamp {
+        flex: 0 0 auto;
+        padding: 1px 5px;
+        border: 1px solid var(--vscode-textLink-foreground);
+        border-radius: 3px;
+        color: var(--vscode-textLink-foreground);
+        font-family: var(--vscode-editor-font-family, monospace);
+        font-size: 9px;
+        letter-spacing: 0.4px;
       }
-
-      .cbar-pct {
-        width: 52px;
-        flex-shrink: 0;
-        text-align: right;
+      .advice-payload-meta {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 5px 10px;
+        padding: 8px 9px 0;
         color: var(--vscode-descriptionForeground);
+        font-size: 10px;
       }
-
-      .cf-1 {
-        background: var(--vscode-charts-blue);
-      }
-
-      .cf-2 {
-        background: var(--vscode-charts-yellow);
-      }
-
-      .cf-3 {
-        background: var(--vscode-charts-purple);
-      }
-
-      .cf-4 {
-        background: var(--vscode-charts-green);
+      .advice-payload-meta code {
+        flex-basis: 100%;
+        color: var(--vscode-foreground);
+        overflow-wrap: anywhere;
       }
-
-      .cf-5 {
-        background: var(--vscode-charts-red);
+      .advice-payload-preview pre {
+        max-height: 280px;
+        margin: 8px 9px 9px;
+        padding: 9px;
+        overflow: auto;
+        border: 1px solid var(--vscode-panel-border);
+        border-radius: 4px;
+        background: var(--vscode-textCodeBlock-background, var(--vscode-editor-background));
+        color: var(--vscode-editor-foreground, var(--vscode-foreground));
+        font-family: var(--vscode-editor-font-family, monospace);
+        font-size: 10px;
+        line-height: 1.45;
+        white-space: pre;
       }
-
-      .provider-tabs {
-        display: flex;
-        gap: 6px;
-        margin: 4px 0 18px;
-        padding-bottom: 10px;
-        border-bottom: 1px solid var(--vscode-panel-border);
+      @media (max-width: 800px) {
+        .combined-share-layout {
+          grid-template-columns: minmax(0, 1fr);
+        }
+        .combined-heatmap-controls {
+          grid-template-columns: minmax(0, 1fr);
+        }
+        .combined-palette-options {
+          grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+        .combined-heatmap-preview svg {
+          width: auto;
+          max-width: none;
+        }
+        .action-card-head {
+          align-items: flex-start;
+          flex-wrap: wrap;
+        }
+        .advice-spine {
+          grid-template-columns: minmax(0, 1fr);
+          gap: 9px;
+          padding-left: 0;
+        }
+        .advice-spine::before {
+          left: 13px;
+          right: auto;
+          top: 13px;
+          bottom: 13px;
+          width: 1px;
+          height: auto;
+        }
+        .advice-spine li {
+          display: grid;
+          grid-template-columns: 26px minmax(0, 1fr);
+          gap: 9px;
+        }
+        .advice-step-marker {
+          margin: 0;
+        }
+        .advice-spine li > div {
+          text-align: left;
+        }
       }
-      .provider-tab {
-        border: 1px solid var(--vscode-panel-border);
-        border-radius: 999px;
-        padding: 5px 13px;
-        background: transparent;
-        color: var(--vscode-foreground);
-        cursor: pointer;
+      @media (max-width: 480px) {
+        body {
+          padding: var(--ccu-space-3);
+        }
+        header {
+          align-items: flex-start;
+          gap: var(--ccu-space-3);
+        }
+        h1 {
+          padding-top: 3px;
+          font-size: 18px;
+        }
+        .actions {
+          gap: var(--ccu-space-1);
+        }
+        .actions button {
+          padding: 7px 9px;
+        }
+        .summary-grid {
+          grid-template-columns: repeat(2, minmax(0, 1fr));
+          gap: var(--ccu-space-2);
+        }
+        .summary-item {
+          min-height: 58px;
+          padding: 10px var(--ccu-space-3);
+        }
+        .summary-item .value {
+          font-size: 17px;
+        }
+        .tabs {
+          margin-bottom: var(--ccu-space-4);
+        }
+        .combined-heatmap-panel {
+          padding: var(--ccu-space-3);
+        }
+        .combined-share-header {
+          flex-direction: column;
+          gap: var(--ccu-space-2);
+        }
+        .combined-private-badge {
+          white-space: normal;
+        }
+        .combined-heatmap-controls {
+          grid-template-columns: minmax(0, 1fr);
+        }
+        .combined-palette-options {
+          grid-template-columns: minmax(0, 1fr);
+        }
       }
-      .provider-tab.active {
-        background: var(--vscode-button-background);
-        color: var(--vscode-button-foreground);
-        border-color: var(--vscode-button-background);
+      @media (prefers-reduced-motion: reduce) {
+        *, *::before, *::after {
+          scroll-behavior: auto !important;
+          animation-duration: 0.01ms !important;
+          animation-iteration-count: 1 !important;
+          transition-duration: 0.01ms !important;
+        }
       }
       .sr-only {
         position: absolute;
@@ -6437,6 +9767,7 @@ export class UsageWebviewProvider {
     return `
 // Get VSCode API
 const vscode = acquireVsCodeApi();
+const __adviceCopy = ${JSON.stringify(I18n.t.popup.adviceEffectiveness)};
 
 function ccuReadUiState() {
   try { return vscode.getState() || {}; } catch (e) { return {}; }
@@ -6448,6 +9779,30 @@ function ccuWriteUiState(key, value) {
     vscode.setState(st);
   } catch (e) {}
 }
+async function ccuVerifyCanonicalPreview(body, sha256, utf8Bytes) {
+  if (
+    typeof body !== 'string' ||
+    typeof sha256 !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(sha256) ||
+    !Number.isInteger(utf8Bytes) ||
+    utf8Bytes < 0
+  ) { return false; }
+  try {
+    var encoded = new TextEncoder().encode(body);
+    if (encoded.byteLength !== utf8Bytes || !globalThis.crypto || !globalThis.crypto.subtle) {
+      return false;
+    }
+    var digest = await globalThis.crypto.subtle.digest('SHA-256', encoded);
+    var hex = Array.prototype.map.call(new Uint8Array(digest), function(byte) {
+      return byte.toString(16).padStart(2, '0');
+    }).join('');
+    return hex === sha256;
+  } catch (e) {
+    return false;
+  }
+}
+var advicePreviewValidationGeneration = {};
+var optimizerPreviewValidationGeneration = 0;
 function ccuProviderName() {
   var selected = document.querySelector('.provider-tab[aria-selected="true"]');
   return selected ? (selected.getAttribute('data-provider') || selected.id.replace('provider-tab-', '')) : 'claude';
@@ -6459,6 +9814,71 @@ function ccuElementStateKey(element, kind) {
   return ccuProviderName() + ':' + (tab ? tab.id : 'page') + ':' + kind + ':' + Math.max(0, elements.indexOf(element));
 }
 
+function adviceRoot(provider) {
+  if (provider === 'optimizer') {
+    return document.querySelector('.action-card[data-advice-provider="optimizer"]');
+  }
+  return document.querySelector('.advice-effectiveness-body[data-advice-provider="' + provider + '"]');
+}
+function adviceConsentElements(provider) {
+  var root = adviceRoot(provider);
+  return {
+    root: root,
+    aggregate: root ? root.querySelector('[data-advice-consent-kind="aggregate"]') : null,
+    prompt: root ? root.querySelector('[data-advice-consent-kind="prompt"]') : null,
+    previewButton: root ? root.querySelector('[data-advice-action="preview"]') : null,
+    sendButton: root ? root.querySelector('[data-advice-action="send"]') : null,
+    preview: root ? root.querySelector('[data-advice-preview]') : null,
+    consentStatus: root ? root.querySelector('[data-advice-consent-status]') : null,
+  };
+}
+function adviceSyncConsentControls(provider) {
+  var elements = adviceConsentElements(provider);
+  if (!elements.root || !elements.aggregate || !elements.prompt) { return; }
+  var promptAvailable = elements.prompt.getAttribute('data-prompt-available') === 'true';
+  elements.prompt.disabled = elements.aggregate.disabled || !elements.aggregate.checked || !promptAvailable;
+  if (elements.prompt.disabled) { elements.prompt.checked = false; }
+  if (elements.previewButton) {
+    elements.previewButton.disabled = elements.aggregate.disabled || !elements.aggregate.checked;
+  }
+}
+function adviceClearPreview(provider) {
+  var elements = adviceConsentElements(provider);
+  if (!elements.preview) { return; }
+  elements.preview.hidden = true;
+  elements.preview.open = false;
+  elements.preview.removeAttribute('data-snapshot-id');
+  if (elements.sendButton) {
+    elements.sendButton.disabled = true;
+    elements.sendButton.textContent = __adviceCopy.sendPreparedRequest;
+  }
+  var body = elements.preview.querySelector('[data-advice-preview-body]');
+  var digest = elements.preview.querySelector('[data-advice-preview-digest]');
+  var mode = elements.preview.querySelector('[data-advice-preview-mode]');
+  var contentType = elements.preview.querySelector('[data-advice-preview-content-type]');
+  var bytes = elements.preview.querySelector('[data-advice-preview-bytes]');
+  var count = elements.preview.querySelector('[data-advice-preview-count]');
+  if (body) { body.textContent = ''; }
+  if (digest) { digest.textContent = ''; }
+  if (mode) { mode.textContent = ''; }
+  if (contentType) { contentType.textContent = ''; }
+  if (bytes) { bytes.textContent = ''; }
+  if (count) { count.textContent = ''; }
+}
+function adviceSetConsentPending(provider, pending) {
+  var elements = adviceConsentElements(provider);
+  if (elements.aggregate) { elements.aggregate.disabled = !!pending; }
+  if (elements.prompt) { elements.prompt.disabled = !!pending; }
+  if (elements.previewButton) { elements.previewButton.disabled = true; }
+  if (!pending) { adviceSyncConsentControls(provider); }
+}
+function restoreAdviceEffectivenessState() {
+  document.querySelectorAll('.advice-effectiveness-body[data-advice-provider]').forEach(function(root) {
+    var provider = root.getAttribute('data-advice-provider');
+    if (provider) { adviceSyncConsentControls(provider); }
+  });
+}
+
 // Keep expanded <details data-persist> open across auto-refresh re-renders — a
 // data refresh shouldn't collapse something you're reading. Only a tab switch
 // resets to the default (see clearPersistedDetails in showTab).
@@ -6484,7 +9904,13 @@ function restorePersistedDetails() {
   } catch (e) {}
 }
 function clearPersistedDetails() {
-  try { var st = ccuReadUiState(); st.openDetails = []; vscode.setState(st); } catch (e) {}
+  try {
+    var st = ccuReadUiState();
+    st.openDetails = [];
+    st.claudeDrilldownDetails = {};
+    st.codexHourlyDetails = {};
+    vscode.setState(st);
+  } catch (e) {}
 }
 // 'toggle' doesn't bubble — listen in the capture phase.
 document.addEventListener('toggle', function(e){
@@ -6505,10 +9931,18 @@ function restoreUi() {
   restoreActiveTab();
   restoreSessionFilter();
   restorePersistedDetails();
+  restoreClaudeDrilldownDetails();
+  restoreCodexHourlyDetails();
+  restoreAdviceEffectivenessState();
   restoreSessionDetails();
   restoreTableSorts();
   restoreChartMetrics();
+  initializeChartDrilldowns();
+  initializeStatusRegions();
+  restoreCombinedHeatmapConfig();
+  requestLocalDataInventoryForVisibleSettings();
   restoreScrollPosition();
+  vscode.postMessage({ command: 'localDataClientReady' });
 }
 function ccuScrollStateKey() {
   var active = document.querySelector('.tab.active');
@@ -6531,14 +9965,28 @@ function restoreScrollPosition() {
     });
   });
 }
-var __ccuScrollFrame = 0;
-window.addEventListener('scroll', function() {
-  if (!__ccuUiReady || __ccuScrollFrame) { return; }
-  __ccuScrollFrame = requestAnimationFrame(function() {
-    __ccuScrollFrame = 0;
-    saveScrollPosition();
-  });
-}, { passive: true });
+var __ccuScrollSaveTimer = 0;
+var __ccuScrollDirty = false;
+function flushScrollPosition() {
+  if (__ccuScrollSaveTimer) {
+    clearTimeout(__ccuScrollSaveTimer);
+    __ccuScrollSaveTimer = 0;
+  }
+  if (!__ccuUiReady || !__ccuScrollDirty) { return; }
+  __ccuScrollDirty = false;
+  saveScrollPosition();
+}
+function scheduleScrollPositionSave() {
+  if (!__ccuUiReady) { return; }
+  __ccuScrollDirty = true;
+  if (__ccuScrollSaveTimer) { clearTimeout(__ccuScrollSaveTimer); }
+  __ccuScrollSaveTimer = setTimeout(flushScrollPosition, 180);
+}
+window.addEventListener('scroll', scheduleScrollPositionSave, { passive: true });
+window.addEventListener('pagehide', flushScrollPosition);
+document.addEventListener('visibilitychange', function() {
+  if (document.visibilityState === 'hidden') { flushScrollPosition(); }
+});
 if (document.readyState === 'loading') {
   document.addEventListener('DOMContentLoaded', restoreUi);
 } else {
@@ -6549,12 +9997,67 @@ if (document.readyState === 'loading') {
 // user's UI language and configured timezone (instead of the hardcoded zh-TW
 // that the original used in this script body).
 const __locale = ${JSON.stringify(I18n.getLocale())};
-const __tz = ${JSON.stringify(I18n.getTimezone())};
+const __tz = ${JSON.stringify(resolveTimeZone(I18n.getTimezone()))};
+const __combinedHeatmapCopy = ${JSON.stringify(combinedHeatmapUiCopy(I18n.getLocale()))};
+const __localDataCopy = ${JSON.stringify(localDataUiCopy(I18n.getLocale()))};
 const __dateOpts = (extra) => {
   const opts = Object.assign({}, extra || {});
   if (__tz) opts.timeZone = __tz;
   return opts;
 };
+// Usage date keys have already been bucketed in the configured timezone. Parse
+// their components and format a UTC-noon sentinel so neither the configured
+// zone nor the Webview host zone can roll a day/month label backwards.
+function ccuFormatUsageDateKey(value, extra, monthly) {
+  var raw = String(value || '');
+  var match = /^(\\d{4})-(\\d{2})(?:-(\\d{2}))?$/.exec(raw);
+  if (!match) { return raw; }
+  var year = Number(match[1]);
+  var month = Number(match[2]);
+  var day = Number(match[3] || 1);
+  var date = new Date(Date.UTC(year, month - 1, day, 12));
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    return raw;
+  }
+  var isMonthly = monthly === true || !match[3];
+  var options = isMonthly
+    ? { year: 'numeric', month: 'long' }
+    : Object.assign({}, extra || {});
+  options.timeZone = 'UTC';
+  return date.toLocaleDateString(__locale, options);
+}
+const __dayKeyFormatter = new Intl.DateTimeFormat('en-CA', __dateOpts({
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit'
+}));
+function ccuDayKey(value) {
+  var date = new Date(value);
+  if (isNaN(date.getTime())) { return ''; }
+  var parts = __dayKeyFormatter.formatToParts(date);
+  var year = '';
+  var month = '';
+  var day = '';
+  parts.forEach(function(part) {
+    if (part.type === 'year') { year = part.value; }
+    if (part.type === 'month') { month = part.value; }
+    if (part.type === 'day') { day = part.value; }
+  });
+  return year && month && day ? year + '-' + month + '-' + day : '';
+}
+function ccuRollingDaySet(count) {
+  var endKey = ccuDayKey(Date.now());
+  var match = /^(\\d{4})-(\\d{2})-(\\d{2})$/.exec(endKey);
+  var days = new Set();
+  if (!match || count <= 0) { return days; }
+  var end = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  for (var offset = 0; offset < count; offset++) {
+    var cursor = new Date(end.getTime());
+    cursor.setUTCDate(cursor.getUTCDate() - offset);
+    days.add(cursor.toISOString().slice(0, 10));
+  }
+  return days;
+}
 
 // Define basic functions
 function showProvider(provider, tab) {
@@ -6601,33 +10104,311 @@ function exportHeatmap() {
 function publishHeatmap() {
   vscode.postMessage({ command: 'publishHeatmap' });
 }
-function refresh() {
-  vscode.postMessage({ command: 'refresh' });
+function combinedHeatmapReadConfig() {
+  var title = document.getElementById('combinedHeatmapTitle');
+  var range = document.getElementById('combinedHeatmapRange');
+  var intensityMode = document.getElementById('combinedHeatmapIntensityMode');
+  var privacy = document.getElementById('combinedHeatmapPrivacy');
+  var palette = document.querySelector('input[name="combinedHeatmapPalette"]:checked');
+  var customAccent = document.getElementById('combinedHeatmapCustomAccent');
+  return {
+    title: title ? title.value : __combinedHeatmapCopy.defaultTitle,
+    range: range ? range.value : 'year',
+    intensityMode: intensityMode ? intensityMode.value : 'quantile',
+    privacyPreview: privacy ? privacy.checked : true,
+    palette: palette ? palette.value : 'academicViolet',
+    customAccent: customAccent ? customAccent.value : '#4f2f87'
+  };
+}
+function combinedHeatmapSaveConfig(config) {
+  try {
+    localStorage.setItem('ccu.combinedHeatmap.title', config.title);
+    localStorage.setItem('ccu.combinedHeatmap.range', config.range);
+    localStorage.setItem('ccu.combinedHeatmap.intensityMode', config.intensityMode);
+    localStorage.setItem('ccu.combinedHeatmap.privacyPreview', config.privacyPreview ? 'true' : 'false');
+    localStorage.setItem('ccu.combinedHeatmap.palette', config.palette);
+    localStorage.setItem('ccu.combinedHeatmap.customAccent', config.customAccent);
+  } catch (e) {}
+}
+function toggleCombinedCustomAccent() {
+  var config = combinedHeatmapReadConfig();
+  var customAccent = document.getElementById('combinedHeatmapCustomAccent');
+  if (customAccent) { customAccent.disabled = config.palette !== 'custom'; }
+}
+function toggleCombinedHeatmapPrivacy(save) {
+  var config = combinedHeatmapReadConfig();
+  var preview = document.getElementById('combinedHeatmapPrivacyPreview');
+  if (preview) { preview.hidden = !config.privacyPreview; }
+  if (save) { combinedHeatmapSaveConfig(config); }
+}
+function restoreCombinedHeatmapConfig() {
+  var title = document.getElementById('combinedHeatmapTitle');
+  var range = document.getElementById('combinedHeatmapRange');
+  var intensityMode = document.getElementById('combinedHeatmapIntensityMode');
+  var privacy = document.getElementById('combinedHeatmapPrivacy');
+  var customAccent = document.getElementById('combinedHeatmapCustomAccent');
+  if (!title || !range || !intensityMode || !privacy || !customAccent) { return; }
+  var changed = false;
+  try {
+    var storedTitle = localStorage.getItem('ccu.combinedHeatmap.title');
+    var storedRange = localStorage.getItem('ccu.combinedHeatmap.range');
+    var storedIntensityMode = localStorage.getItem('ccu.combinedHeatmap.intensityMode');
+    var storedPrivacy = localStorage.getItem('ccu.combinedHeatmap.privacyPreview');
+    var storedPalette = localStorage.getItem('ccu.combinedHeatmap.palette');
+    var storedAccent = localStorage.getItem('ccu.combinedHeatmap.customAccent');
+    if (storedTitle) { title.value = storedTitle; changed = storedTitle !== title.getAttribute('data-default-value'); }
+    if (storedRange === '30d' || storedRange === '90d' || storedRange === 'year') {
+      range.value = storedRange;
+      changed = changed || storedRange !== range.getAttribute('data-default-value');
+    }
+    if (storedIntensityMode === 'quantile' || storedIntensityMode === 'logarithmic' || storedIntensityMode === 'linear') {
+      intensityMode.value = storedIntensityMode;
+      changed = changed || storedIntensityMode !== intensityMode.getAttribute('data-default-value');
+    }
+    if (storedPrivacy === 'false') { privacy.checked = false; }
+    if (['academicViolet', 'claudeOrange', 'codexBlue', 'githubGreen', 'custom'].indexOf(storedPalette) >= 0) {
+      var paletteInput = document.querySelector('input[name="combinedHeatmapPalette"][value="' + storedPalette + '"]');
+      if (paletteInput) { paletteInput.checked = true; }
+      changed = changed || storedPalette !== 'academicViolet';
+    }
+    if (storedAccent && /^#[0-9a-fA-F]{6}$/.test(storedAccent)) {
+      customAccent.value = storedAccent;
+      changed = changed || storedAccent.toLowerCase() !== '#4f2f87';
+    }
+  } catch (e) {}
+  toggleCombinedCustomAccent();
+  toggleCombinedHeatmapPrivacy(false);
+  if (changed) { generateCombinedHeatmapPreview(); }
+}
+function generateCombinedHeatmapPreview() {
+  var config = combinedHeatmapReadConfig();
+  combinedHeatmapSaveConfig(config);
+  var status = document.getElementById('combinedHeatmapStatus');
+  if (status) { status.textContent = __combinedHeatmapCopy.updatePreview + '…'; }
+  vscode.postMessage({ command: 'previewCombinedHeatmap', title: config.title, range: config.range, intensityMode: config.intensityMode, palette: config.palette, customAccent: config.customAccent });
+}
+function exportCombinedHeatmap() {
+  var config = combinedHeatmapReadConfig();
+  combinedHeatmapSaveConfig(config);
+  vscode.postMessage({ command: 'exportCombinedHeatmap', title: config.title, range: config.range, intensityMode: config.intensityMode, palette: config.palette, customAccent: config.customAccent });
+}
+function copyCombinedHeatmapMarkdown() {
+  var config = combinedHeatmapReadConfig();
+  combinedHeatmapSaveConfig(config);
+  vscode.postMessage({ command: 'copyCombinedHeatmapMarkdown', title: config.title, range: config.range, intensityMode: config.intensityMode, palette: config.palette, customAccent: config.customAccent });
+}
+function resetCombinedHeatmapPreferences() {
+  var title = document.getElementById('combinedHeatmapTitle');
+  var range = document.getElementById('combinedHeatmapRange');
+  var intensityMode = document.getElementById('combinedHeatmapIntensityMode');
+  var privacy = document.getElementById('combinedHeatmapPrivacy');
+  var customAccent = document.getElementById('combinedHeatmapCustomAccent');
+  try {
+    localStorage.removeItem('ccu.combinedHeatmap.title');
+    localStorage.removeItem('ccu.combinedHeatmap.range');
+    localStorage.removeItem('ccu.combinedHeatmap.intensityMode');
+    localStorage.removeItem('ccu.combinedHeatmap.privacyPreview');
+    localStorage.removeItem('ccu.combinedHeatmap.palette');
+    localStorage.removeItem('ccu.combinedHeatmap.customAccent');
+  } catch (e) {}
+  if (title) { title.value = __combinedHeatmapCopy.defaultTitle; }
+  if (range) { range.value = 'year'; }
+  if (intensityMode) { intensityMode.value = 'quantile'; }
+  if (privacy) { privacy.checked = true; }
+  var defaultPalette = document.querySelector('input[name="combinedHeatmapPalette"][value="academicViolet"]');
+  if (defaultPalette) { defaultPalette.checked = true; }
+  if (customAccent) { customAccent.value = '#4f2f87'; }
+  toggleCombinedCustomAccent();
+  toggleCombinedHeatmapPrivacy(false);
+  var status = document.getElementById('combinedHeatmapStatus');
+  if (status) { status.textContent = __combinedHeatmapCopy.resetSharing + '…'; }
+  vscode.postMessage({
+    command: 'previewCombinedHeatmap',
+    title: __combinedHeatmapCopy.defaultTitle,
+    range: 'year',
+    intensityMode: 'quantile',
+    palette: 'academicViolet',
+    customAccent: '#4f2f87'
+  });
+  vscode.postMessage({ command: 'resetCombinedHeatmapPreferences' });
+}
+function refresh() {
+  vscode.postMessage({ command: 'refresh' });
+}
+
+function openSettings() {
+  vscode.postMessage({ command: 'openSettings' });
+}
+
+function refreshPricing() {
+  vscode.postMessage({ command: 'refreshPricing' });
+}
+
+function getAdvice() {
+  vscode.postMessage({ command: 'getAdvice' });
+}
+
+function setSetting(key, value, type) {
+  if (type === 'number') {
+    var n = Number(value);
+    if (!isFinite(n)) { return; }
+    value = n;
+  }
+  vscode.postMessage({ command: 'updateSetting', key: key, value: value });
+}
+
+function resetAllSettings(keys) {
+  vscode.postMessage({ command: 'resetAllSettings', keys: Array.isArray(keys) ? keys : undefined });
+}
+
+var __ccuUiPreferenceKeys = [
+  'ccu.activeTab',
+  'ccu.sessionFilter',
+  'ccu.sessionRange',
+  'ccu.sessionModel'
+];
+var __ccuSharingPreferenceKeys = [
+  'ccu.combinedHeatmap.title',
+  'ccu.combinedHeatmap.range',
+  'ccu.combinedHeatmap.intensityMode',
+  'ccu.combinedHeatmap.privacyPreview',
+  'ccu.combinedHeatmap.palette',
+  'ccu.combinedHeatmap.customAccent'
+];
+
+function ccuCountPresentLocalStorageKeys(keys) {
+  var count = 0;
+  try {
+    keys.forEach(function(key) {
+      if (localStorage.getItem(key) !== null) { count += 1; }
+    });
+  } catch (e) {}
+  return count;
+}
+
+function ccuLocalDataClientSummary() {
+  var state = ccuReadUiState();
+  return {
+    uiPreferenceKeys: ccuCountPresentLocalStorageKeys(__ccuUiPreferenceKeys),
+    webviewStateFields: state && typeof state === 'object' ? Object.keys(state).length : 0,
+    sharingPreferenceKeys: ccuCountPresentLocalStorageKeys(__ccuSharingPreferenceKeys)
+  };
+}
+
+function requestLocalDataInventory() {
+  if (!document.getElementById('localDataInventoryBody')) { return; }
+  vscode.postMessage({
+    command: 'requestLocalDataInventory',
+    clientSummary: ccuLocalDataClientSummary()
+  });
+}
+
+function requestLocalDataInventoryForVisibleSettings() {
+  var settings = document.getElementById('settings');
+  if (settings && !settings.hidden && settings.classList.contains('active')) {
+    requestLocalDataInventory();
+  }
 }
 
-function openSettings() {
-  vscode.postMessage({ command: 'openSettings' });
+function runLocalDataAction(action) {
+  var status = document.getElementById('localDataActionStatus');
+  if (status) { status.textContent = '…'; }
+  var scope = document.getElementById('localDataQuotaScope');
+  vscode.postMessage({
+    command: 'runLocalDataAction',
+    action: action,
+    quotaScopeToken: action === 'clear-quota-history' && scope ? scope.value : undefined
+  });
 }
 
-function refreshPricing() {
-  vscode.postMessage({ command: 'refreshPricing' });
+function ccuResetLocalStorageKeys(keys) {
+  try {
+    keys.forEach(function(key) { localStorage.removeItem(key); });
+    return keys.every(function(key) { return localStorage.getItem(key) === null; });
+  } catch (e) {
+    return false;
+  }
 }
 
-function getAdvice() {
-  vscode.postMessage({ command: 'getAdvice' });
+function ccuApplyLocalDataClientAction(action) {
+  var ok = true;
+  if (action === 'reset-ui-state' || action === 'clear-all-client-state') {
+    ok = ccuResetLocalStorageKeys(__ccuUiPreferenceKeys) && ok;
+    try {
+      vscode.setState({});
+      var state = vscode.getState();
+      ok = (state === undefined || state === null || Object.keys(state).length === 0) && ok;
+    } catch (e) {
+      ok = false;
+    }
+  }
+  if (action === 'reset-sharing-preferences' || action === 'clear-all-client-state') {
+    ok = ccuResetLocalStorageKeys(__ccuSharingPreferenceKeys) && ok;
+    restoreCombinedHeatmapConfig();
+  }
+  return ok;
 }
 
-function setSetting(key, value, type) {
-  if (type === 'number') {
-    var n = Number(value);
-    if (!isFinite(n)) { return; }
-    value = n;
+function ccuLocalDataFormatSizeCount(row) {
+  var parts = [];
+  if (typeof row.approximateBytes === 'number' && isFinite(row.approximateBytes)) {
+    parts.push(new Intl.NumberFormat(__locale).format(row.approximateBytes) + ' ' + __localDataCopy.bytes);
   }
-  vscode.postMessage({ command: 'updateSetting', key: key, value: value });
+  if (typeof row.itemCount === 'number' && isFinite(row.itemCount)) {
+    parts.push(new Intl.NumberFormat(__locale).format(row.itemCount) + ' ' + __localDataCopy.items);
+  }
+  return parts.length ? parts.join(' · ') : '—';
 }
 
-function resetAllSettings(keys) {
-  vscode.postMessage({ command: 'resetAllSettings', keys: Array.isArray(keys) ? keys : undefined });
+function ccuLocalDataFormatDate(value) {
+  if (typeof value !== 'number' || !isFinite(value) || value < 0) { return '—'; }
+  try {
+    return new Intl.DateTimeFormat(__locale, __dateOpts({
+      year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit'
+    })).format(new Date(value));
+  } catch (e) { return '—'; }
+}
+
+function ccuRenderLocalDataInventory(inventory) {
+  var body = document.getElementById('localDataInventoryBody');
+  var exclusions = document.getElementById('localDataExclusions');
+  var select = document.getElementById('localDataQuotaScope');
+  if (!body || !inventory || inventory.schemaVersion !== 1 || !Array.isArray(inventory.rows)) { return false; }
+  while (body.firstChild) { body.removeChild(body.firstChild); }
+  inventory.rows.forEach(function(row) {
+    var tr = document.createElement('tr');
+    var values = [
+      row.category,
+      row.locationClass,
+      row.schema,
+      ccuLocalDataFormatSizeCount(row),
+      ccuLocalDataFormatDate(row.oldestAt) + ' / ' + ccuLocalDataFormatDate(row.newestAt),
+      row.networkInteraction,
+      row.clearability
+    ];
+    values.forEach(function(value) {
+      var td = document.createElement('td');
+      td.textContent = typeof value === 'string' ? value : '—';
+      tr.appendChild(td);
+    });
+    body.appendChild(tr);
+  });
+  if (exclusions) {
+    exclusions.textContent = __localDataCopy.sourceExclusions + ' ' +
+      (Array.isArray(inventory.exclusions) ? inventory.exclusions.join(' · ') : '');
+  }
+  if (select) {
+    while (select.firstChild) { select.removeChild(select.firstChild); }
+    (Array.isArray(inventory.quotaScopes) ? inventory.quotaScopes : []).forEach(function(scope) {
+      if (!scope || typeof scope.token !== 'string' || typeof scope.label !== 'string') { return; }
+      var option = document.createElement('option');
+      option.value = scope.token;
+      option.textContent = scope.label;
+      select.appendChild(option);
+    });
+  }
+  return true;
 }
 
 function runOptimizer() {
@@ -6636,8 +10417,10 @@ function runOptimizer() {
   if (!ta || !ta.value.trim()) { return; }
   var err = document.getElementById('optError');
   var res = document.getElementById('optResult');
+  var preview = document.getElementById('optPreview');
   if (err) { err.style.display = 'none'; }
   if (res) { res.style.display = 'none'; }
+  if (preview) { preview.style.display = 'none'; preview.removeAttribute('data-snapshot-id'); }
   if (btn) {
     btn.disabled = true;
     btn.textContent = btn.getAttribute('data-running') || '…';
@@ -6651,6 +10434,70 @@ function runOptimizer() {
   });
 }
 
+async function showOptimizerPreview(msg) {
+  var validationGeneration = ++optimizerPreviewValidationGeneration;
+  var btn = document.getElementById('optRunBtn');
+  if (btn) {
+    btn.disabled = false;
+    btn.textContent = btn.getAttribute('data-run') || __adviceCopy.previewPayload;
+  }
+  var err = document.getElementById('optError');
+  var preview = document.getElementById('optPreview');
+  var body = document.getElementById('optPreviewBody');
+  var digest = document.getElementById('optPreviewDigest');
+  var bytes = document.getElementById('optPreviewBytes');
+  var send = document.getElementById('optSendBtn');
+  if (preview) { preview.style.display = 'none'; preview.removeAttribute('data-snapshot-id'); }
+  if (send) { send.disabled = true; send.textContent = __adviceCopy.sendPreparedRequest; }
+  if (!msg.ok) {
+    if (err && msg.error) { err.textContent = msg.error; err.style.display = ''; }
+    return;
+  }
+  var valid =
+    msg.ok === true &&
+    /^optimizer-[a-f0-9]{24}$/.test(msg.snapshotId || '') &&
+    typeof msg.body === 'string' &&
+    typeof msg.sha256 === 'string' && /^[a-f0-9]{64}$/.test(msg.sha256) &&
+    Number.isInteger(msg.utf8Bytes) && msg.utf8Bytes >= 0 &&
+    msg.contentType === 'application/json' &&
+    msg.dataMode === 'user-draft-only';
+  if (valid) {
+    valid = await ccuVerifyCanonicalPreview(msg.body, msg.sha256, msg.utf8Bytes);
+  }
+  if (validationGeneration !== optimizerPreviewValidationGeneration) { return; }
+  if (!preview || !valid) {
+    if (preview) { preview.style.display = 'none'; preview.removeAttribute('data-snapshot-id'); }
+    if (send) { send.disabled = true; send.textContent = __adviceCopy.sendPreparedRequest; }
+    if (err) {
+      err.textContent = __adviceCopy.strictOutputRejected;
+      err.style.display = '';
+    }
+    return;
+  }
+  if (err) { err.style.display = 'none'; }
+  preview.setAttribute('data-snapshot-id', msg.snapshotId);
+  preview.style.display = '';
+  preview.open = true;
+  if (body) { body.textContent = msg.body; }
+  if (digest) { digest.textContent = 'SHA-256 ' + msg.sha256; }
+  if (bytes) { bytes.textContent = __adviceCopy.payloadBytes.replace('{bytes}', String(msg.utf8Bytes)); }
+  if (send) { send.disabled = false; send.textContent = __adviceCopy.sendPreparedRequest; }
+}
+
+function sendOptimizer() {
+  var preview = document.getElementById('optPreview');
+  var send = document.getElementById('optSendBtn');
+  var draft = document.getElementById('optDraft');
+  var snapshotId = preview ? preview.getAttribute('data-snapshot-id') : '';
+  if (!draft || !/^optimizer-[a-f0-9]{24}$/.test(snapshotId || '')) { return; }
+  if (send) { send.disabled = true; send.textContent = __adviceCopy.sendingPreparedRequest; }
+  vscode.postMessage({
+    command: 'sendOptimizerRequest',
+    snapshotId: snapshotId,
+    draft: draft.value,
+  });
+}
+
 function showOptimizeResult(msg) {
   var btn = document.getElementById('optRunBtn');
   if (btn) {
@@ -6659,10 +10506,22 @@ function showOptimizeResult(msg) {
   }
   var err = document.getElementById('optError');
   var res = document.getElementById('optResult');
+  var preview = document.getElementById('optPreview');
+  if (preview) { preview.style.display = 'none'; preview.removeAttribute('data-snapshot-id'); }
   if (msg.error) {
     if (err) { err.textContent = msg.error; err.style.display = ''; }
     return;
   }
+  var validFeedbackTarget =
+    typeof msg.adviceId === 'string' && /^advice-optimizer-[a-f0-9]{24}$/.test(msg.adviceId) &&
+    msg.recommendationId === 'recommendation-optimizer-result-v1';
+  if (!validFeedbackTarget) {
+    if (err) {
+      err.textContent = __adviceCopy.strictOutputRejected;
+      err.style.display = '';
+    }
+    return;
+  }
   var promptEl = document.getElementById('optPrompt');
   var settingsEl = document.getElementById('optSettings');
   if (promptEl) { promptEl.textContent = msg.prompt || ''; }
@@ -6671,6 +10530,20 @@ function showOptimizeResult(msg) {
     formatOptSettings();
   }
   if (res) { res.style.display = ''; }
+  var feedback = document.getElementById('optFeedback');
+  if (feedback) {
+    feedback.querySelectorAll('[data-advice-action="feedback"]').forEach(function(button) {
+      button.setAttribute('data-advice-id', msg.adviceId);
+      button.disabled = false;
+      button.setAttribute('aria-pressed', 'false');
+      button.classList.remove('is-selected');
+      var marker = button.querySelector('[aria-hidden="true"]');
+      if (marker) { marker.textContent = '○'; }
+    });
+    var feedbackStatus = feedback.querySelector('[data-advice-feedback-status]');
+    if (feedbackStatus) { feedbackStatus.textContent = ''; }
+    feedback.style.display = '';
+  }
 }
 
 function copyOptPrompt(btn) {
@@ -6823,14 +10696,12 @@ function applySessionFilters() {
   var list = document.getElementById('sessionList');
   if (!list) { return; }
   var st = ccuSessState();
-  var now = Date.now();
-  var threshold = st.range === 'today' ? new Date().setHours(0, 0, 0, 0)
-    : st.range === '7' ? now - 7 * 86400000
-    : st.range === '30' ? now - 30 * 86400000
-    : 0;
+  var dayCount = st.range === 'today' ? 1 : st.range === '7' ? 7 : st.range === '30' ? 30 : 0;
+  var allowedDays = dayCount > 0 ? ccuRollingDaySet(dayCount) : null;
   list.querySelectorAll('tr.sort-row').forEach(function(tr) {
     var okProject = st.project === 'all' || !tr.classList.contains('session-foreign');
-    var okTime = st.range === 'all' || Number(tr.getAttribute('data-sort-time')) >= threshold;
+    var rowDay = tr.getAttribute('data-day-key') || ccuDayKey(Number(tr.getAttribute('data-sort-time')));
+    var okTime = !allowedDays || allowedDays.has(rowDay);
     var okModel = st.model === 'all' || (tr.getAttribute('data-models') || '').split('|').indexOf(st.model) !== -1;
     var visible = okProject && okTime && okModel;
     tr.style.display = visible ? '' : 'none';
@@ -6973,9 +10844,11 @@ function sortTable(table, key, th, restoring) {
   table.querySelectorAll('th.sortable').forEach(function(h) {
     h.removeAttribute('data-sortdir');
     h.classList.remove('sorted-asc', 'sorted-desc');
+    h.setAttribute('aria-sort', 'none');
   });
   th.setAttribute('data-sortdir', ascending ? 'asc' : 'desc');
   th.classList.add(ascending ? 'sorted-asc' : 'sorted-desc');
+  th.setAttribute('aria-sort', ascending ? 'ascending' : 'descending');
 
   units.sort(function(a, b) {
     var va = a.lead.getAttribute('data-sort-' + key);
@@ -7003,8 +10876,16 @@ function sortTable(table, key, th, restoring) {
     ccuWriteUiState('tableSorts', sorts);
   }
 }
+function initializeSortableHeaders(root) {
+  var scope = root || document;
+  scope.querySelectorAll('th.sortable').forEach(function(header) {
+    header.setAttribute('tabindex', '0');
+    if (!header.hasAttribute('aria-sort')) { header.setAttribute('aria-sort', 'none'); }
+  });
+}
 function restoreTableSorts(root) {
   var scope = root || document;
+  initializeSortableHeaders(scope);
   var sorts = ccuReadUiState().tableSorts || {};
   scope.querySelectorAll('table').forEach(function(table) {
     var saved = sorts[ccuElementStateKey(table, 'table')];
@@ -7018,9 +10899,16 @@ function restoreTableSorts(root) {
 
 function showTab(tabName, restoring) {
   try {
-    // Remove active from all tabs and contents
-    document.querySelectorAll('.tab').forEach(tab => tab.classList.remove('active'));
-    document.querySelectorAll('.tab-content').forEach(content => content.classList.remove('active'));
+    // Keep the visual state and the WAI-ARIA tab contract in lockstep.
+    document.querySelectorAll('.tabs [role="tab"]').forEach(function(tab) {
+      tab.classList.remove('active');
+      tab.setAttribute('aria-selected', 'false');
+      tab.setAttribute('tabindex', '-1');
+    });
+    document.querySelectorAll('.tab-content[role="tabpanel"]').forEach(function(content) {
+      content.classList.remove('active');
+      content.hidden = true;
+    });
 
     // Add active to selected tab and content
     const selectedTab = document.getElementById('tab-' + tabName);
@@ -7028,7 +10916,10 @@ function showTab(tabName, restoring) {
 
     if (selectedTab && selectedContent) {
       selectedTab.classList.add('active');
+      selectedTab.setAttribute('aria-selected', 'true');
+      selectedTab.setAttribute('tabindex', '0');
       selectedContent.classList.add('active');
+      selectedContent.hidden = false;
 
       if (!restoring) {
         vscode.postMessage({ command: 'tabChanged', tab: tabName });
@@ -7036,6 +10927,7 @@ function showTab(tabName, restoring) {
         clearPersistedDetails();
         // Persist in localStorage too — survives the reload, restored before paint.
         try { localStorage.setItem('ccu.activeTab', tabName); } catch (e) {}
+        if (tabName === 'settings') { requestLocalDataInventory(); }
       }
     } else {
       console.error("Tab or content not found:", tabName);
@@ -7045,12 +10937,71 @@ function showTab(tabName, restoring) {
   }
 }
 
-function toggleHourlyDetail(date) {
+// The dashboard views use the same roving-tabindex keyboard contract as the
+// provider selector. A single-line scroll strip keeps the focused destination
+// visible at narrow widths without turning translated labels vertical.
+document.addEventListener('keydown', function(event) {
+  var tab = event.target && event.target.closest
+    ? event.target.closest('.tabs [role="tab"][data-dashboard-tab]')
+    : null;
+  if (!tab || ['ArrowLeft', 'ArrowRight', 'Home', 'End'].indexOf(event.key) === -1) { return; }
+  var tablist = tab.closest('.tabs[role="tablist"]');
+  if (!tablist) { return; }
+  var items = Array.prototype.slice.call(
+    tablist.querySelectorAll('[role="tab"][data-dashboard-tab]'),
+  );
+  var index = items.indexOf(tab);
+  if (index === -1 || items.length === 0) { return; }
+  if (event.key === 'Home') { index = 0; }
+  else if (event.key === 'End') { index = items.length - 1; }
+  else { index = (index + (event.key === 'ArrowRight' ? 1 : -1) + items.length) % items.length; }
+  event.preventDefault();
+  var next = items[index];
+  next.focus();
+  if (next.scrollIntoView) { next.scrollIntoView({ block: 'nearest', inline: 'nearest' }); }
+  showTab(next.getAttribute('data-dashboard-tab'));
+});
+
+function claudeDrilldownStateKey(detailRow, kind) {
+  const tab = detailRow && detailRow.closest ? detailRow.closest('.tab-content') : null;
+  return 'claude:' + (tab ? tab.id : kind) + ':' + kind;
+}
+
+function persistClaudeDrilldown(detailRow, kind, date) {
+  if (!detailRow) { return; }
+  const details = ccuReadUiState().claudeDrilldownDetails || {};
+  const key = claudeDrilldownStateKey(detailRow, kind);
+  if (date) { details[key] = date; } else { delete details[key]; }
+  ccuWriteUiState('claudeDrilldownDetails', details);
+}
+
+function restoreClaudeDrilldownDetails() {
+  try {
+    const saved = ccuReadUiState().claudeDrilldownDetails || {};
+    document.querySelectorAll('.hourly-detail-row:not([data-codex-hourly-detail-row])').forEach(function(row) {
+      const date = row.getAttribute('data-date');
+      if (date && saved[claudeDrilldownStateKey(row, 'hourly')] === date) {
+        toggleHourlyDetail(date, true);
+      }
+    });
+    document.querySelectorAll('.monthly-detail-row').forEach(function(row) {
+      const date = row.getAttribute('data-date');
+      if (date && saved[claudeDrilldownStateKey(row, 'monthly')] === date) {
+        toggleMonthlyDetail(date, true);
+      }
+    });
+  } catch (e) {}
+}
+
+function toggleHourlyDetail(date, restoring) {
   try {
     const detailRow = document.querySelector('.hourly-detail-row[data-date="' + date + '"]');
     const button = document.querySelector('.daily-row[data-date="' + date + '"] .detail-button');
     const container = document.getElementById('hourly-detail-' + date);
-    const chartBar = document.querySelector('.chart-bar-container[data-date="' + date + '"] .chart-bar');
+    const chartBar = document.querySelector(
+      '.tab-content.active .hc-col[data-date="' + date + '"] .chart-bar.clickable, ' +
+      '.tab-content.active .chart-bar-container[data-date="' + date + '"] .chart-bar.clickable',
+    );
 
     if (detailRow && button && container) {
       const isExpanded = detailRow.style.display !== 'none' && detailRow.style.display !== '';
@@ -7062,11 +11013,13 @@ function toggleHourlyDetail(date) {
         // Show detail for this date
         detailRow.style.display = 'table-row';
         button.classList.add('expanded');
+        setChartDrilldownExpanded('hourly-detail-' + date, true);
 
         // Update chart bar selection state
         if (chartBar) {
           chartBar.classList.add('selected');
         }
+        persistClaudeDrilldown(detailRow, 'hourly', date);
 
         // Request hourly data if not loaded
         if (!container.dataset.loaded) {
@@ -7077,16 +11030,20 @@ function toggleHourlyDetail(date) {
         // Scroll the newly-revealed detail into view — clicking a bar at the
         // top of the tab otherwise expands a detail far down the table that
         // the user never notices.
-        try { detailRow.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (e) {}
+        if (!restoring) {
+          try { detailRow.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (e) {}
+        }
       } else {
         // Hide detail
         detailRow.style.display = 'none';
         button.classList.remove('expanded');
+        setChartDrilldownExpanded('hourly-detail-' + date, false);
 
         // Update chart bar selection state
         if (chartBar) {
           chartBar.classList.remove('selected');
         }
+        persistClaudeDrilldown(detailRow, 'hourly', '');
       }
 
     } else {
@@ -7097,6 +11054,98 @@ function toggleHourlyDetail(date) {
   }
 }
 
+function codexHourlyDetailElements(date) {
+  const detailRow = document.querySelector('[data-codex-hourly-detail-row][data-date="' + date + '"]');
+  const scope = detailRow && detailRow.closest ? detailRow.closest('.tab-content') : document;
+  return {
+    detailRow: detailRow,
+    button: scope ? scope.querySelector('[data-codex-hourly-toggle][data-date="' + date + '"]') : null,
+    chartBar: scope ? scope.querySelector('.hc-col[data-date="' + date + '"] .chart-bar') : null,
+    scope: scope,
+  };
+}
+
+function codexHourlyDetailStateKey(detailRow) {
+  const tab = detailRow && detailRow.closest ? detailRow.closest('.tab-content') : null;
+  return 'codex:' + (tab ? tab.id : 'month');
+}
+
+function persistCodexHourlyDetail(detailRow, date) {
+  if (!detailRow) { return; }
+  const details = ccuReadUiState().codexHourlyDetails || {};
+  const key = codexHourlyDetailStateKey(detailRow);
+  if (date) { details[key] = date; } else { delete details[key]; }
+  ccuWriteUiState('codexHourlyDetails', details);
+}
+
+function closeAllCodexHourlyDetails(scope) {
+  const root = scope || document;
+  root.querySelectorAll('[data-codex-hourly-detail-row]').forEach(function(row) {
+    row.style.display = 'none';
+  });
+  root.querySelectorAll('[data-codex-hourly-toggle]').forEach(function(button) {
+    button.classList.remove('expanded');
+    button.setAttribute('aria-expanded', 'false');
+  });
+  root.querySelectorAll('[data-codex-last30-daily] .chart-bar.selected').forEach(function(bar) {
+    bar.classList.remove('selected');
+  });
+  root.querySelectorAll('[aria-controls^="codex-hourly-detail-"]').forEach(function(control) {
+    control.setAttribute('aria-expanded', 'false');
+  });
+}
+
+function setCodexHourlyDetail(date, expanded, restoring) {
+  const elements = codexHourlyDetailElements(date);
+  if (!elements.detailRow || !elements.button) { return false; }
+  if (expanded) {
+    closeAllCodexHourlyDetails(elements.scope);
+    elements.detailRow.style.display = 'table-row';
+    elements.button.classList.add('expanded');
+    elements.button.setAttribute('aria-expanded', 'true');
+    setChartDrilldownExpanded('codex-hourly-detail-' + date, true);
+    if (elements.chartBar) { elements.chartBar.classList.add('selected'); }
+    persistCodexHourlyDetail(elements.detailRow, date);
+    if (!restoring) {
+      try { elements.detailRow.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (e) {}
+    }
+  } else {
+    elements.detailRow.style.display = 'none';
+    elements.button.classList.remove('expanded');
+    elements.button.setAttribute('aria-expanded', 'false');
+    setChartDrilldownExpanded('codex-hourly-detail-' + date, false);
+    if (elements.chartBar) { elements.chartBar.classList.remove('selected'); }
+    persistCodexHourlyDetail(elements.detailRow, '');
+  }
+  return true;
+}
+
+function toggleCodexHourlyDetail(date) {
+  try {
+    const elements = codexHourlyDetailElements(date);
+    if (!elements.detailRow || !elements.button) { return; }
+    setCodexHourlyDetail(
+      date,
+      elements.button.getAttribute('aria-expanded') !== 'true',
+      false,
+    );
+  } catch (error) {
+    console.error('Error in toggleCodexHourlyDetail:', error);
+  }
+}
+
+function restoreCodexHourlyDetails() {
+  try {
+    const saved = ccuReadUiState().codexHourlyDetails || {};
+    document.querySelectorAll('[data-codex-hourly-detail-row]').forEach(function(row) {
+      const date = row.getAttribute('data-date');
+      if (date && saved[codexHourlyDetailStateKey(row)] === date) {
+        setCodexHourlyDetail(date, true, true);
+      }
+    });
+  } catch (e) {}
+}
+
 function closeAllHourlyDetails() {
   // Close all expanded detail rows
   const allDetailRows = document.querySelectorAll('.hourly-detail-row');
@@ -7109,20 +11158,27 @@ function closeAllHourlyDetails() {
 
   allButtons.forEach(function(btn) {
     btn.classList.remove('expanded');
+    btn.setAttribute('aria-expanded', 'false');
   });
 
   allChartBars.forEach(function(bar) {
     bar.classList.remove('selected');
   });
+  document.querySelectorAll('[aria-controls^="hourly-detail-"]').forEach(function(control) {
+    control.setAttribute('aria-expanded', 'false');
+  });
 
 }
 
-function toggleMonthlyDetail(monthDate) {
+function toggleMonthlyDetail(monthDate, restoring) {
   try {
     const detailRow = document.querySelector('.monthly-detail-row[data-date="' + monthDate + '"]');
     const button = document.querySelector('.daily-row[data-date="' + monthDate + '"] .detail-button');
     const container = document.getElementById('monthly-detail-' + monthDate);
-    const chartBar = document.querySelector('.chart-bar-container[data-date="' + monthDate + '"] .chart-bar');
+    const chartBar = document.querySelector(
+      '.tab-content.active .hc-col[data-date="' + monthDate + '"] .chart-bar.clickable, ' +
+      '.tab-content.active .chart-bar-container[data-date="' + monthDate + '"] .chart-bar.clickable',
+    );
 
     if (detailRow && button && container) {
       const isExpanded = detailRow.style.display !== 'none' && detailRow.style.display !== '';
@@ -7134,11 +11190,13 @@ function toggleMonthlyDetail(monthDate) {
         // Show detail for this month
         detailRow.style.display = 'table-row';
         button.classList.add('expanded');
+        setChartDrilldownExpanded('monthly-detail-' + monthDate, true);
 
         // Update chart bar selection state
         if (chartBar) {
           chartBar.classList.add('selected');
         }
+        persistClaudeDrilldown(detailRow, 'monthly', monthDate);
 
         // Request monthly data if not loaded
         if (!container.dataset.loaded) {
@@ -7147,16 +11205,20 @@ function toggleMonthlyDetail(monthDate) {
         }
 
         // Scroll the newly-revealed detail into view (see toggleHourlyDetail).
-        try { detailRow.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (e) {}
+        if (!restoring) {
+          try { detailRow.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (e) {}
+        }
       } else {
         // Hide detail
         detailRow.style.display = 'none';
         button.classList.remove('expanded');
+        setChartDrilldownExpanded('monthly-detail-' + monthDate, false);
 
         // Update chart bar selection state
         if (chartBar) {
           chartBar.classList.remove('selected');
         }
+        persistClaudeDrilldown(detailRow, 'monthly', '');
       }
 
     } else {
@@ -7179,11 +11241,15 @@ function closeAllMonthlyDetails() {
 
   allButtons.forEach(function(btn) {
     btn.classList.remove('expanded');
+    btn.setAttribute('aria-expanded', 'false');
   });
 
   allChartBars.forEach(function(bar) {
     bar.classList.remove('selected');
   });
+  document.querySelectorAll('[aria-controls^="monthly-detail-"]').forEach(function(control) {
+    control.setAttribute('aria-expanded', 'false');
+  });
 
 }
 
@@ -7226,6 +11292,7 @@ window.refresh = refresh;
 window.openSettings = openSettings;
 window.refreshPricing = refreshPricing;
 window.getAdvice = getAdvice;
+window.sendOptimizer = sendOptimizer;
 window.toggleProjectGroup = toggleProjectGroup;
 window.sortTable = sortTable;
 window.dismissQuotaWarn = dismissQuotaWarn;
@@ -7240,10 +11307,366 @@ window.syncChartBarSelection = syncChartBarSelection;
 window.closeAllHourlyDetails = closeAllHourlyDetails;
 window.closeAllMonthlyDetails = closeAllMonthlyDetails;
 
+document.addEventListener('change', function(event) {
+  var input = event.target && event.target.closest
+    ? event.target.closest('[data-advice-consent-kind][data-provider]')
+    : null;
+  if (!input) { return; }
+  var provider = input.getAttribute('data-provider');
+  if (provider !== 'claude' && provider !== 'codex' && provider !== 'optimizer') { return; }
+  var elements = adviceConsentElements(provider);
+  if (!elements.aggregate || !elements.prompt) { return; }
+  if (!elements.aggregate.checked) { elements.prompt.checked = false; }
+  adviceSyncConsentControls(provider);
+  adviceClearPreview(provider);
+  vscode.postMessage({ command: 'discardAdviceSnapshot', provider: provider });
+  adviceSetConsentPending(provider, true);
+  vscode.postMessage({
+    command: 'updateAdviceConsent',
+    provider: provider,
+    aggregateConsent: elements.aggregate.checked ? 'explicit' : 'not-granted',
+    promptSampleConsent: elements.prompt.checked ? 'explicit' : 'not-granted',
+  });
+});
+
+document.addEventListener('input', function(event) {
+  var target = event.target;
+  if (!target || target.id !== 'optDraft') { return; }
+  var preview = document.getElementById('optPreview');
+  if (preview && preview.getAttribute('data-snapshot-id')) {
+    preview.style.display = 'none';
+    preview.removeAttribute('data-snapshot-id');
+    vscode.postMessage({ command: 'discardOptimizerRequest' });
+  }
+});
+
+document.addEventListener('click', function(event) {
+  var action = event.target && event.target.closest
+    ? event.target.closest('[data-advice-action][data-provider]')
+    : null;
+  if (!action) { return; }
+  var provider = action.getAttribute('data-provider');
+  if (provider !== 'claude' && provider !== 'codex' && provider !== 'optimizer') { return; }
+  if (action.getAttribute('data-advice-action') === 'preview') {
+    event.preventDefault();
+    var elements = adviceConsentElements(provider);
+    if (!elements.aggregate || !elements.prompt || !elements.aggregate.checked) { return; }
+    action.disabled = true;
+    if (elements.consentStatus) { elements.consentStatus.textContent = ''; }
+    vscode.postMessage({
+      command: 'prepareAdviceSnapshot',
+      provider: provider,
+      aggregateConsent: 'explicit',
+      promptSampleConsent: elements.prompt.checked ? 'explicit' : 'not-granted',
+    });
+    return;
+  }
+  if (action.getAttribute('data-advice-action') === 'send') {
+    event.preventDefault();
+    var sendElements = adviceConsentElements(provider);
+    var snapshotId = sendElements.preview
+      ? sendElements.preview.getAttribute('data-snapshot-id')
+      : null;
+    if (!snapshotId || !/^snapshot-[a-f0-9]{24}$/.test(snapshotId)) { return; }
+    action.disabled = true;
+    action.textContent = __adviceCopy.sendingPreparedRequest;
+    if (sendElements.consentStatus) {
+      sendElements.consentStatus.textContent = __adviceCopy.sendingPreparedRequest;
+    }
+    vscode.postMessage({
+      command: 'sendAdviceSnapshot',
+      provider: provider,
+      snapshotId: snapshotId,
+    });
+    return;
+  }
+  if (action.getAttribute('data-advice-action') === 'feedback') {
+    event.preventDefault();
+    var root = adviceRoot(provider);
+    if (!root) { return; }
+    var recommendationId = action.getAttribute('data-recommendation-id');
+    root.querySelectorAll('[data-advice-action="feedback"]').forEach(function(button) {
+      if (button.getAttribute('data-recommendation-id') !== recommendationId) { return; }
+      button.disabled = true;
+    });
+    root.querySelectorAll('[data-advice-feedback-status]').forEach(function(status) {
+      if (
+        status.getAttribute('data-advice-id') === action.getAttribute('data-advice-id') &&
+        status.getAttribute('data-recommendation-id') === recommendationId
+      ) {
+        status.textContent = '';
+      }
+    });
+    vscode.postMessage({
+      command: 'recordAdviceFeedback',
+      provider: provider,
+      adviceId: action.getAttribute('data-advice-id'),
+      recommendationId: recommendationId,
+      kind: action.getAttribute('data-feedback-kind'),
+    });
+    return;
+  }
+  if (action.getAttribute('data-advice-action') === 'snooze') {
+    event.preventDefault();
+    action.disabled = true;
+    vscode.postMessage({
+      command: 'snoozeAdvice',
+      provider: provider,
+      adviceId: action.getAttribute('data-advice-id'),
+      recommendationId: action.getAttribute('data-recommendation-id'),
+      mode: action.getAttribute('data-snooze-mode') === 'resume' ? 'resume' : 'snooze',
+    });
+    return;
+  }
+  if (action.getAttribute('data-advice-action') === 'clear') {
+    event.preventDefault();
+    if (!window.confirm(__adviceCopy.clearLocalDataConfirm)) { return; }
+    action.disabled = true;
+    vscode.postMessage({ command: 'clearAdviceLocalData' });
+  }
+});
+
 // Handle messages from extension
-window.addEventListener('message', function(event) {
+window.addEventListener('message', async function(event) {
   const message = event.data;
 
+  if (
+    message.command === 'codexIndexProgress' &&
+    typeof message.text === 'string' &&
+    message.text.length <= 1024
+  ) {
+    document.querySelectorAll('[data-codex-index-progress-text]').forEach(function(element) {
+      element.textContent = message.text;
+    });
+  }
+
+  if (message.command === 'requestLocalDataInventoryClient') {
+    requestLocalDataInventory();
+  }
+
+  if (message.command === 'localDataClientAction') {
+    var localDataClientActionOk = false;
+    try {
+      localDataClientActionOk = ccuApplyLocalDataClientAction(message.action) === true;
+    } catch (e) {}
+    if (typeof message.requestId === 'string' && message.requestId.length > 0) {
+      vscode.postMessage({
+        command: 'localDataClientActionAck',
+        requestId: message.requestId,
+        ok: localDataClientActionOk
+      });
+    }
+    requestLocalDataInventory();
+  }
+
+  if (message.command === 'localDataInventoryResult') {
+    var inventoryBody = document.getElementById('localDataInventoryBody');
+    if (message.ok !== true || !ccuRenderLocalDataInventory(message.inventory)) {
+      if (inventoryBody) {
+        while (inventoryBody.firstChild) { inventoryBody.removeChild(inventoryBody.firstChild); }
+        var unavailableRow = document.createElement('tr');
+        var unavailableCell = document.createElement('td');
+        unavailableCell.colSpan = 7;
+        unavailableCell.className = 'table-hint';
+        unavailableCell.textContent = __localDataCopy.unavailable;
+        unavailableRow.appendChild(unavailableCell);
+        inventoryBody.appendChild(unavailableRow);
+      }
+    }
+  }
+
+  if (message.command === 'localDataActionResult') {
+    var localDataResult = message.result || {};
+    var localDataStatus = document.getElementById('localDataActionStatus');
+    if (localDataResult.clientAction) {
+      ccuApplyLocalDataClientAction(localDataResult.clientAction);
+    }
+    if (localDataStatus) {
+      localDataStatus.textContent = typeof localDataResult.message === 'string'
+        ? localDataResult.message
+        : __localDataCopy.unavailable;
+    }
+    requestLocalDataInventory();
+  }
+
+  if (message.command === 'adviceConsentResult') {
+    var consentProvider = message.provider;
+    var consentElements = adviceConsentElements(consentProvider);
+    if (consentElements.aggregate && consentElements.prompt) {
+      if (message.ok === true) {
+        consentElements.aggregate.checked = message.aggregateConsent === 'explicit';
+        consentElements.prompt.checked =
+          consentElements.aggregate.checked && message.promptSampleConsent === 'explicit';
+        adviceSetConsentPending(consentProvider, false);
+        if (consentElements.consentStatus) { consentElements.consentStatus.textContent = ''; }
+      } else {
+        consentElements.aggregate.checked = false;
+        consentElements.prompt.checked = false;
+        consentElements.aggregate.disabled = true;
+        consentElements.prompt.disabled = true;
+        if (consentElements.previewButton) { consentElements.previewButton.disabled = true; }
+        if (consentElements.consentStatus) {
+          consentElements.consentStatus.textContent = __adviceCopy.feedbackSaveFailed;
+        }
+      }
+    }
+  }
+
+  if (message.command === 'adviceSnapshotResult') {
+    var snapshotProvider = message.provider;
+    var snapshotValidationGeneration =
+      (advicePreviewValidationGeneration[snapshotProvider] || 0) + 1;
+    advicePreviewValidationGeneration[snapshotProvider] = snapshotValidationGeneration;
+    var snapshotElements = adviceConsentElements(snapshotProvider);
+    if (snapshotElements.previewButton) { snapshotElements.previewButton.disabled = false; }
+    adviceClearPreview(snapshotProvider);
+    var validSnapshot =
+      message.ok === true &&
+      typeof message.snapshotId === 'string' && /^snapshot-[a-f0-9]{24}$/.test(message.snapshotId) &&
+      typeof message.body === 'string' &&
+      typeof message.sha256 === 'string' && /^[a-f0-9]{64}$/.test(message.sha256) &&
+      Number.isInteger(message.utf8Bytes) && message.utf8Bytes >= 0 &&
+      Number.isInteger(message.promptSampleCount) && message.promptSampleCount >= 0 &&
+      message.contentType === 'application/json' &&
+      (message.dataMode === 'aggregates-only' ||
+        message.dataMode === 'aggregates-with-personalization' ||
+        message.dataMode === 'aggregates-with-prompt-samples');
+    if (validSnapshot) {
+      validSnapshot = await ccuVerifyCanonicalPreview(
+        message.body,
+        message.sha256,
+        message.utf8Bytes,
+      );
+    }
+    if (advicePreviewValidationGeneration[snapshotProvider] !== snapshotValidationGeneration) {
+      return;
+    }
+    if (!validSnapshot || !snapshotElements.preview) {
+      if (snapshotElements.consentStatus) {
+        snapshotElements.consentStatus.textContent = __adviceCopy.strictOutputRejected;
+      }
+    } else {
+      var preview = snapshotElements.preview;
+      var previewBody = preview.querySelector('[data-advice-preview-body]');
+      var previewDigest = preview.querySelector('[data-advice-preview-digest]');
+      var previewMode = preview.querySelector('[data-advice-preview-mode]');
+      var previewContentType = preview.querySelector('[data-advice-preview-content-type]');
+      var previewBytes = preview.querySelector('[data-advice-preview-bytes]');
+      var previewCount = preview.querySelector('[data-advice-preview-count]');
+      if (previewBody) { previewBody.textContent = message.body; }
+      if (previewDigest) { previewDigest.textContent = 'SHA-256 ' + message.sha256; }
+      if (previewContentType) { previewContentType.textContent = message.contentType; }
+      if (previewMode) {
+        previewMode.textContent = message.dataMode === 'aggregates-only'
+          ? __adviceCopy.aggregatesOnly
+          : message.dataMode === 'aggregates-with-personalization'
+            ? __adviceCopy.aggregatesWithPersonalization
+            : __adviceCopy.aggregatesWithPromptSamples;
+      }
+      if (previewBytes) {
+        previewBytes.textContent = __adviceCopy.payloadBytes.replace('{bytes}', String(message.utf8Bytes));
+      }
+      if (previewCount) {
+        previewCount.textContent = __adviceCopy.promptSamplesIncluded.replace(
+          '{count}',
+          String(message.promptSampleCount),
+        );
+      }
+      preview.setAttribute('data-snapshot-id', message.snapshotId);
+      preview.hidden = false;
+      preview.open = true;
+      if (snapshotElements.sendButton) {
+        snapshotElements.sendButton.disabled = false;
+        snapshotElements.sendButton.textContent = __adviceCopy.sendPreparedRequest;
+      }
+      if (snapshotElements.consentStatus) {
+        snapshotElements.consentStatus.textContent = __adviceCopy.noNetworkTransport;
+      }
+    }
+    adviceSyncConsentControls(snapshotProvider);
+  }
+
+  if (message.command === 'adviceSendResult') {
+    var sendProvider = message.provider;
+    var sendElements = adviceConsentElements(sendProvider);
+    if (message.ok === true) {
+      if (sendElements.consentStatus) {
+        sendElements.consentStatus.textContent = __adviceCopy.sentPreparedRequest;
+      }
+      adviceClearPreview(sendProvider);
+    } else {
+      if (sendElements.sendButton) {
+        sendElements.sendButton.disabled = false;
+        sendElements.sendButton.textContent = __adviceCopy.sendPreparedRequest;
+      }
+      if (sendElements.consentStatus) {
+        sendElements.consentStatus.textContent = __adviceCopy.strictOutputRejected;
+      }
+    }
+  }
+
+  if (message.command === 'adviceFeedbackResult') {
+    var feedbackProvider = message.provider;
+    var feedbackRoot = adviceRoot(feedbackProvider);
+    if (feedbackRoot) {
+      var feedbackStatus = null;
+      feedbackRoot.querySelectorAll('[data-advice-feedback-status]').forEach(function(status) {
+        if (
+          status.getAttribute('data-advice-id') === message.adviceId &&
+          status.getAttribute('data-recommendation-id') === message.recommendationId
+        ) {
+          feedbackStatus = status;
+        }
+      });
+      if (message.ok === true) {
+        feedbackRoot.querySelectorAll('[data-advice-action="feedback"]').forEach(function(button) {
+          if (
+            button.getAttribute('data-advice-id') !== message.adviceId ||
+            button.getAttribute('data-recommendation-id') !== message.recommendationId
+          ) { return; }
+          var kind = button.getAttribute('data-feedback-kind');
+          var selected =
+            (kind === 'helpful' && message.rating === 'helpful') ||
+            (kind === 'not-helpful' && message.rating === 'not-helpful') ||
+            (kind === 'applied' && message.applied === 'applied');
+          button.disabled = false;
+          button.setAttribute('aria-pressed', selected ? 'true' : 'false');
+          button.classList.toggle('is-selected', selected);
+          var marker = button.querySelector('[aria-hidden="true"]');
+          if (marker) { marker.textContent = selected ? '✓' : '○'; }
+        });
+        if (feedbackStatus) { feedbackStatus.textContent = __adviceCopy.feedbackLocalOnly; }
+      } else {
+        feedbackRoot.querySelectorAll('[data-advice-action="feedback"]').forEach(function(button) {
+          if (
+            button.getAttribute('data-advice-id') === message.adviceId &&
+            button.getAttribute('data-recommendation-id') === message.recommendationId
+          ) {
+            button.disabled = false;
+          }
+        });
+        if (feedbackStatus) { feedbackStatus.textContent = __adviceCopy.feedbackSaveFailed; }
+      }
+    }
+  }
+
+  if (message.command === 'adviceSnoozeResult' && message.ok !== true) {
+    document.querySelectorAll('[data-advice-action="snooze"]').forEach(function(button) {
+      if (
+        button.getAttribute('data-advice-id') === message.adviceId &&
+        button.getAttribute('data-recommendation-id') === message.recommendationId
+      ) {
+        button.disabled = false;
+      }
+    });
+  }
+
+  if (message.command === 'adviceClearResult' && message.ok !== true) {
+    document.querySelectorAll('[data-advice-action="clear"]').forEach(function(button) {
+      button.disabled = false;
+    });
+  }
+
   if (message.command === 'shareCardResult') {
     const prev = document.getElementById('scPreview');
     if (prev) {
@@ -7253,6 +11676,43 @@ window.addEventListener('message', function(event) {
     }
   }
 
+  if (message.command === 'combinedHeatmapResult') {
+    var combinedPreview = document.getElementById('combinedHeatmapPreview');
+    var combinedMarkdown = document.getElementById('combinedHeatmapMarkdown');
+    var combinedStatus = document.getElementById('combinedHeatmapStatus');
+    if (message.error) {
+      if (combinedStatus) { combinedStatus.textContent = String(message.error); }
+    } else {
+      if (combinedPreview) {
+        if (message.hasData) {
+          combinedPreview.innerHTML = message.svg || '';
+        } else {
+          combinedPreview.textContent = __combinedHeatmapCopy.noData;
+        }
+      }
+      if (combinedMarkdown) { combinedMarkdown.value = message.markdown || ''; }
+      if (combinedStatus) { combinedStatus.textContent = ''; }
+    }
+  }
+
+  if (message.command === 'combinedHeatmapMarkdownCopied') {
+    var copyStatus = document.getElementById('combinedHeatmapStatus');
+    if (copyStatus) {
+      copyStatus.textContent = message.ok
+        ? __combinedHeatmapCopy.copyMarkdown + ' ✓'
+        : String(message.error || 'Could not copy Markdown.');
+    }
+  }
+
+  if (message.command === 'combinedHeatmapPreferencesReset') {
+    var resetStatus = document.getElementById('combinedHeatmapStatus');
+    if (resetStatus) {
+      resetStatus.textContent = message.ok
+        ? __combinedHeatmapCopy.resetComplete
+        : __combinedHeatmapCopy.resetFailed;
+    }
+  }
+
   if (message.command === 'hourlyDataResponse') {
     const container = document.getElementById('hourly-detail-' + message.date);
     if (container && message.data) {
@@ -7261,6 +11721,8 @@ window.addEventListener('message', function(event) {
       // Re-bind chart tab events after rendering
       bindChartTabEvents(container);
       restoreChartMetrics(container);
+      initializeChartDrilldowns(container);
+      initializeStatusRegions(container);
     }
   }
 
@@ -7272,6 +11734,8 @@ window.addEventListener('message', function(event) {
       // Re-bind chart tab events after rendering
       bindChartTabEvents(container);
       restoreChartMetrics(container);
+      initializeChartDrilldowns(container);
+      initializeStatusRegions(container);
     }
   }
 
@@ -7285,6 +11749,9 @@ window.addEventListener('message', function(event) {
   if (message.command === 'optimizeResult') {
     showOptimizeResult(message);
   }
+  if (message.command === 'optimizePreviewResult') {
+    showOptimizerPreview(message);
+  }
 });
 
 // Format any optimiser settings restored into the DOM by a re-render.
@@ -7299,11 +11766,25 @@ function saveChartMetric(container, metric) {
   metrics[ccuChartStateKey(container)] = metric;
   ccuWriteUiState('chartMetrics', metrics);
 }
+function syncChartMetricState(container) {
+  var heading = container.querySelector(':scope > h3, :scope > h4, :scope > .section-header h3');
+  container.querySelectorAll(':scope > .chart-tabs').forEach(function(group) {
+    group.setAttribute('role', 'group');
+    if (heading && heading.textContent) { group.setAttribute('aria-label', heading.textContent.trim()); }
+  });
+  container.querySelectorAll('.chart-tab[data-metric]').forEach(function(item) {
+    item.setAttribute('aria-pressed', item.classList.contains('active') ? 'true' : 'false');
+  });
+}
 function applyChartMetric(container, metric, persist) {
   var tab = container.querySelector('.chart-tab[data-metric="' + metric + '"]');
   if (!tab) { return; }
-  container.querySelectorAll('.chart-tab').forEach(function(item) { item.classList.remove('active'); });
+  container.querySelectorAll('.chart-tab').forEach(function(item) {
+    item.classList.remove('active');
+    item.setAttribute('aria-pressed', 'false');
+  });
   tab.classList.add('active');
+  tab.setAttribute('aria-pressed', 'true');
   if (container.classList.contains('hourly-breakdown')) {
     var chartContent = container.querySelector('[id^="hourly-chart-"]');
     if (chartContent) { updateHourlyChart(chartContent.id.replace('hourly-chart-', ''), metric); }
@@ -7321,6 +11802,66 @@ function restoreChartMetrics(root) {
   containers.forEach(function(container) {
     var metric = metrics[ccuChartStateKey(container)];
     if (metric) { applyChartMetric(container, metric, false); }
+    else { syncChartMetricState(container); }
+  });
+}
+
+function chartDrilldownInfo(element) {
+  var holder = element && element.closest
+    ? element.closest('[data-date]')
+    : null;
+  var date = holder ? holder.getAttribute('data-date') : '';
+  if (!date) { return null; }
+  var containingTab = element && element.closest ? element.closest('.tab-content') : null;
+  var kind = containingTab && containingTab.id === 'all'
+    ? 'monthly'
+    : element.closest('[data-codex-last30-daily]')
+      ? 'codex-hourly'
+      : 'hourly';
+  var prefix = kind === 'monthly'
+    ? 'monthly-detail-'
+    : kind === 'codex-hourly'
+      ? 'codex-hourly-detail-'
+      : 'hourly-detail-';
+  return { date: date, kind: kind, controls: prefix + date };
+}
+function setChartDrilldownExpanded(controls, expanded) {
+  document.querySelectorAll('[aria-controls="' + controls + '"]').forEach(function(control) {
+    control.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+  });
+}
+function activateChartDrilldown(element) {
+  var info = chartDrilldownInfo(element);
+  if (!info) { return; }
+  if (info.kind === 'monthly') { toggleMonthlyDetail(info.date); }
+  else if (info.kind === 'codex-hourly') { toggleCodexHourlyDetail(info.date); }
+  else { toggleHourlyDetail(info.date); }
+}
+function initializeChartDrilldowns(root) {
+  var scope = root || document;
+  scope.querySelectorAll('.chart-bar.clickable, .hc-col-clickable[data-date]').forEach(function(control) {
+    var info = chartDrilldownInfo(control);
+    if (!info || !document.getElementById(info.controls)) { return; }
+    control.setAttribute('role', 'button');
+    control.setAttribute('tabindex', '0');
+    control.setAttribute('aria-controls', info.controls);
+    var label = control.getAttribute('title') || info.date;
+    control.setAttribute('aria-label', label);
+    var detail = document.getElementById(info.controls);
+    var expanded = detail && detail.closest('tr')
+      ? getComputedStyle(detail.closest('tr')).display !== 'none'
+      : false;
+    control.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+  });
+}
+function initializeStatusRegions(root) {
+  var scope = root || document;
+  scope.querySelectorAll('.loading, .no-data, .no-chart-data').forEach(function(region) {
+    region.setAttribute('role', 'status');
+    region.setAttribute('aria-live', 'polite');
+  });
+  scope.querySelectorAll('.error').forEach(function(region) {
+    region.setAttribute('role', 'alert');
   });
 }
 
@@ -7344,7 +11885,7 @@ document.addEventListener('click', function(event) {
     const metric = chartTab.dataset.metric;
 
     // Find the container and determine the context
-    const container = chartTab.closest('.daily-breakdown') || chartTab.closest('.hourly-breakdown');
+    const container = chartTab.closest('.daily-breakdown, .hourly-breakdown');
 
     if (container) {
       applyChartMetric(container, metric, true);
@@ -7354,26 +11895,31 @@ document.addEventListener('click', function(event) {
   // Handle chart bar clicks - only for clickable charts
   if (event.target.classList.contains('chart-bar') && event.target.classList.contains('clickable')) {
     event.preventDefault();
-    // Daily/monthly charts now use .hc-col; the JS-rendered drill-downs still
-    // use .chart-bar-container — support both.
-    const container = event.target.closest('.hc-col') || event.target.closest('.chart-bar-container');
-    if (container) {
-      const date = container.dataset.date;
-      if (date) {
-        // Determine if this is a monthly chart or daily chart based on current tab
-        const activeTab = document.querySelector('.tab.active');
-        if (activeTab && activeTab.id === 'tab-all') {
-          // This is in the "all time" tab, so it's a monthly chart
-          toggleMonthlyDetail(date);
-        } else {
-          // This is in the "month" tab, so it's a daily chart
-          toggleHourlyDetail(date);
-        }
-      }
-    }
+    activateChartDrilldown(event.target);
   }
 });
 
+document.addEventListener('keydown', function(event) {
+  var sortableTh = event.target && event.target.closest
+    ? event.target.closest('th.sortable')
+    : null;
+  if (!sortableTh || (event.key !== 'Enter' && event.key !== ' ')) { return; }
+  var table = sortableTh.closest('table');
+  var key = sortableTh.getAttribute('data-sortkey');
+  if (!table || !key) { return; }
+  event.preventDefault();
+  sortTable(table, key, sortableTh);
+});
+
+document.addEventListener('keydown', function(event) {
+  var control = event.target && event.target.closest
+    ? event.target.closest('.chart-bar.clickable[role="button"], .hc-col-clickable[role="button"]')
+    : null;
+  if (!control || (event.key !== 'Enter' && event.key !== ' ')) { return; }
+  event.preventDefault();
+  activateChartDrilldown(control);
+});
+
 function bindChartTabEvents(container) {
   const chartTabs = container.querySelectorAll('.chart-tab[data-metric]');
 
@@ -7391,7 +11937,7 @@ function handleChartTabClick(event) {
 
   const metric = this.dataset.metric;
   if (!metric) { return; }
-  const container = this.closest('.daily-breakdown') || this.closest('.hourly-breakdown');
+  const container = this.closest('.daily-breakdown, .hourly-breakdown');
 
   if (container) {
     applyChartMetric(container, metric, true);
@@ -7470,8 +12016,13 @@ function updateMainChart(metric, container) {
       // Hourly chart: tooltip shows the value only (the hour is on the x-axis).
       bar.title = valueWithHelp;
     } else if (date) {
-      const dateObj = new Date(date);
-      bar.title = dateObj.toLocaleDateString() + ': ' + valueWithHelp;
+      bar.title = ccuFormatUsageDateKey(date) + ': ' + valueWithHelp;
+    }
+    // Drill-down bars keep their accessible name synchronized with the
+    // currently selected metric; otherwise a keyboard user would continue to
+    // hear the initial cost value after switching to tokens or messages.
+    if (bar.getAttribute('role') === 'button' && bar.title) {
+      bar.setAttribute('aria-label', bar.title);
     }
 
     const barVal = container.querySelector('.hc-barval');
@@ -7598,7 +12149,7 @@ function renderHourlyData(hourlyData, date) {
   }
 
   let html = '<div class="hourly-breakdown">';
-  html += '<h4>' + new Date(date).toLocaleDateString(__locale, __dateOpts()) + ' ${I18n.t.popup.hourlyBreakdown}</h4>';
+  html += '<h4>' + ccuFormatUsageDateKey(date) + ' ${I18n.t.popup.hourlyBreakdown}</h4>';
 
   html += '<div class="chart-tabs">';
   html += '<button class="chart-tab active" data-metric="cost">${I18n.t.popup.cost}</button>';
@@ -7651,7 +12202,7 @@ function renderDailyData(dailyData, monthDate) {
   }
 
   let html = '<div class="daily-breakdown">';
-  html += '<h4>' + new Date(monthDate).toLocaleDateString(__locale, __dateOpts({ year: 'numeric', month: 'long' })) + ' ${I18n.t.popup.dailyBreakdown}</h4>';
+  html += '<h4>' + ccuFormatUsageDateKey(monthDate, null, true) + ' ${I18n.t.popup.dailyBreakdown}</h4>';
 
   html += '<div class="chart-tabs">';
   html += '<button class="chart-tab active" data-metric="cost">${I18n.t.popup.cost}</button>';
@@ -7671,7 +12222,7 @@ function renderDailyData(dailyData, monthDate) {
   // monthly composition the user clicked).
   html += compositionHtml(dailyData.map(function(item) {
     return {
-      label: new Date(item.date).toLocaleDateString(__locale, __dateOpts({ month: 'numeric', day: 'numeric' })),
+      label: ccuFormatUsageDateKey(item.date, { month: 'numeric', day: 'numeric' }),
       data: item.data
     };
   }));
@@ -7688,8 +12239,7 @@ function renderDailyData(dailyData, monthDate) {
   html += '</tr></thead><tbody>';
 
   dailyData.forEach(function(item) {
-    const dateObj = new Date(item.date);
-    const formattedDate = dateObj.toLocaleDateString(__locale, __dateOpts({ month: 'numeric', day: 'numeric' }));
+    const formattedDate = ccuFormatUsageDateKey(item.date, { month: 'numeric', day: 'numeric' });
 
     html += '<tr>';
     html += '<td class="date-cell">' + formattedDate + '</td>';
@@ -7717,7 +12267,7 @@ function renderDailyData(dailyData, monthDate) {
 // attributes so the in-place metric switcher (updateMainChart) can rebuild.
 function griddedChart(items, metric, opts) {
   if (!items || items.length === 0) {
-    return '<div class="no-chart-data">No data available</div>';
+    return '<div class="no-chart-data" role="status">${this.escapeHtml(I18n.t.statusBar.noData)}</div>';
   }
   const maxHeight = 120;
   function metricValue(d) {
diff --git a/src/weeklyValue.ts b/src/weeklyValue.ts
index bfd82c28..a4c3cb09 100644
--- a/src/weeklyValue.ts
+++ b/src/weeklyValue.ts
@@ -5,7 +5,6 @@ import { ProviderTokenCounts, UsageProvider } from './providers/providerTypes';
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 const RESET_CLUSTER_MS = 5 * 60 * 1000;
-const MIN_EXTRAPOLATION_PERCENT = 5;
 const MIN_PRICED_SHARE = 0.8;
 
 export type WeeklyValueConfidence = 'high' | 'medium' | 'low' | 'usage-only';
@@ -22,6 +21,19 @@ export interface WeeklyQuotaObservation {
   resetAt: number;
   usedPercent: number;
   sourceKey?: string;
+  /** Account continuity carried by the schema-2 local observation store. Old
+   * fixtures and migration rows may omit these fields and are treated as
+   * low-information legacy evidence. */
+  accountAttribution?: 'verified-local-signal' | 'profile-continuity' | 'unattributed';
+  windowId?: string;
+  observationConfidence?: 'high' | 'medium' | 'low';
+  flags?: Array<
+    | 'approximate-boundary'
+    | 'low-log-coverage'
+    | 'low-price-coverage'
+    | 'account-ambiguous'
+    | 'clock-anomaly'
+  >;
 }
 
 export interface WeeklyEquivalentUsage {
@@ -279,10 +291,15 @@ function clusterObservations(observations: WeeklyQuotaObservation[]): Observatio
     );
   for (const observation of ordered) {
     const previous = clusters[clusters.length - 1];
+    const previousWindowId = previous?.observations[0]?.windowId;
+    const sameExplicitWindow = previousWindowId !== undefined || observation.windowId !== undefined
+      ? previousWindowId !== undefined && previousWindowId === observation.windowId
+      : true;
     if (
       previous &&
       previous.provider === observation.provider &&
       previous.seriesKey === observation.seriesKey &&
+      sameExplicitWindow &&
       Math.abs(previous.resetAt - observation.resetAt) <= RESET_CLUSTER_MS
     ) {
       previous.observations.push(observation);
@@ -511,16 +528,166 @@ function alignedResetAt(resetAt: number, anchorResetAt: number): number | null {
   return Math.abs(aligned - resetAt) <= RESET_CLUSTER_MS ? aligned : null;
 }
 
+interface AllowanceCandidateSummary {
+  value: number;
+  pricingCoverage: number;
+  count: number;
+  dispersed: boolean;
+}
+
+function evidenceWeight(
+  observation: WeeklyQuotaObservation,
+  pricingCoverage: number,
+  boundaryApproximate: boolean,
+  windowStart: number,
+  periodEnd: number,
+): number {
+  const confidenceWeight = observation.observationConfidence === 'high'
+    ? 1
+    : observation.observationConfidence === 'medium'
+      ? 0.8
+      : observation.observationConfidence === 'low'
+        ? 0.55
+        : 0.7;
+  const attributionWeight = observation.accountAttribution === 'verified-local-signal'
+    ? 1
+    : observation.accountAttribution === 'profile-continuity'
+      ? 0.9
+      : observation.accountAttribution === 'unattributed'
+        ? 0.55
+        : 0.7;
+  const flags = new Set(observation.flags ?? []);
+  const flagWeight =
+    (flags.has('low-log-coverage') ? 0.6 : 1) *
+    (flags.has('low-price-coverage') ? 0.7 : 1) *
+    (flags.has('account-ambiguous') ? 0.4 : 1) *
+    (flags.has('clock-anomaly') ? 0.5 : 1);
+  const boundaryWeight = boundaryApproximate || flags.has('approximate-boundary')
+    ? 0.55
+    : 1;
+  const span = Math.max(1, periodEnd - windowStart);
+  const progress = Math.max(
+    0,
+    Math.min(1, (observation.observedAt - windowStart) / span),
+  );
+  const recencyWeight = 0.65 + 0.35 * progress;
+  // Low coverage must lower confidence, not erase a mathematically valid
+  // observation. Keep a small non-zero floor for partially priced prefixes.
+  const coverageWeight = Math.max(0.05, Math.min(1, pricingCoverage));
+  return confidenceWeight * attributionWeight * flagWeight *
+    boundaryWeight * recencyWeight * coverageWeight;
+}
+
+function robustAllowanceCandidate(
+  observations: WeeklyQuotaObservation[],
+  rows: WeeklyEquivalentUsage[],
+  windowStart: number,
+  periodEnd: number,
+  boundaryApproximate: boolean,
+): AllowanceCandidateSummary | null {
+  const candidates = observations.flatMap((observation) => {
+    if (
+      observation.observedAt < windowStart ||
+      observation.observedAt > periodEnd ||
+      observation.usedPercent <= 0 ||
+      observation.usedPercent > 100
+    ) {
+      return [];
+    }
+    const observed = totals(rows.filter((row) => row.timestamp <= observation.observedAt));
+    if (observed.equivalentUsd <= 0) {
+      return [];
+    }
+    const pricingCoverage = observed.totalTokens > 0
+      ? Math.min(1, observed.pricedTokens / observed.totalTokens)
+      : 0;
+    const value = observed.equivalentUsd / (observation.usedPercent / 100);
+    if (!Number.isFinite(value) || value <= 0) {
+      return [];
+    }
+    return [{
+      value,
+      pricingCoverage,
+      weight: evidenceWeight(
+        observation,
+        pricingCoverage,
+        boundaryApproximate,
+        windowStart,
+        periodEnd,
+      ),
+    }];
+  }).sort((left, right) => left.value - right.value);
+  if (candidates.length === 0) return null;
+  const totalWeight = candidates.reduce((sum, item) => sum + item.weight, 0);
+  let accumulated = 0;
+  let median = candidates[candidates.length - 1].value;
+  for (const candidate of candidates) {
+    accumulated += candidate.weight;
+    if (accumulated >= totalWeight / 2) {
+      median = candidate.value;
+      break;
+    }
+  }
+  const weightedCoverage = candidates.reduce(
+    (sum, item) => sum + item.pricingCoverage * item.weight,
+    0,
+  ) / Math.max(Number.EPSILON, totalWeight);
+  const minimum = candidates[0].value;
+  const maximum = candidates[candidates.length - 1].value;
+  return {
+    value: median,
+    pricingCoverage: weightedCoverage,
+    count: candidates.length,
+    dispersed: minimum > 0 && maximum / minimum > 2,
+  };
+}
+
+/**
+ * A quota sample can outlive the seven-day interval it describes. When that
+ * is the only evidence left after a reset, falling back to Monday buckets would
+ * put the new usage in a different period from the provider's actual window.
+ * Recover the reset as an alignment hint only when every observed Codex reset
+ * sits on the same seven-day sequence. This helper never supplies a quota
+ * observation, so it cannot enable an allowance estimate on its own.
+ */
+function latestKnownCodexResetAnchor(
+  observations: WeeklyQuotaObservation[],
+  now: number,
+): number | undefined {
+  const candidates = observations
+    .filter((item) =>
+      item.provider === 'codex' &&
+      Number.isFinite(item.observedAt) &&
+      item.observedAt <= now &&
+      Number.isFinite(item.resetAt) &&
+      item.resetAt > 0,
+    )
+    .sort((left, right) =>
+      right.observedAt - left.observedAt || right.resetAt - left.resetAt,
+    );
+  const latest = candidates[0];
+  if (!latest) {
+    return undefined;
+  }
+  return candidates.every((item) =>
+    alignedResetAt(item.resetAt, latest.resetAt) !== null,
+  )
+    ? latest.resetAt
+    : undefined;
+}
+
 /**
  * Builds the dashboard's one authoritative weekly timeline. Token-log usage is
  * first assigned to non-overlapping [start, reset) buckets exactly once. Quota
  * observations may then decorate their matching bucket with utilization and a
  * conservative allowance estimate; they never add a second usage row.
  *
- * Codex logs do not expose a reliable account identity. Any overlapping,
- * non-aligned future reset makes the current allowance ambiguous regardless of
- * its label. Historical Codex periods and source-mixed current periods remain
- * usage-only rather than manufacturing an account split.
+ * Codex logs do not expose a reliable account identity, but a file source key
+ * is not an account key either: one Codex home commonly contributes many
+ * files to the same account-wide quota series. Those rows may therefore be
+ * aggregated for an allowance estimate, with low confidence when the source
+ * or reset boundary is approximate. A genuinely different quota series still
+ * blocks the estimate rather than manufacturing an account split.
  */
 export function buildWeeklyValueTimeline(
   provider: UsageProvider,
@@ -557,7 +724,16 @@ export function buildWeeklyValueTimeline(
       right.latest.observedAt - left.latest.observedAt ||
       right.cluster.resetAt - left.cluster.resetAt,
     )[0];
-  const anchorResetAt = anchorEntry?.cluster.resetAt ?? options.anchorResetAt;
+  // If the newest reset sample is older than its own seven-day window, it is
+  // still useful for grouping usage after a rollover. It remains alignment-only
+  // until a valid in-window sample exists, so no allowance is inferred here.
+  const staleResetAnchor = !anchorEntry &&
+    options.anchorResetAt === undefined &&
+    provider === 'codex'
+    ? latestKnownCodexResetAnchor(normalizedObservations, now)
+    : undefined;
+  const anchorResetAt = anchorEntry?.cluster.resetAt ??
+    options.anchorResetAt ?? staleResetAnchor;
   const limit = Math.max(1, Math.floor(options.limit ?? 12));
   let history = buildWeeklyUsageHistory(provider, inputs.usage, {
     now,
@@ -596,23 +772,35 @@ export function buildWeeklyValueTimeline(
       .sort((left, right) => right.resetAt - left.resetAt);
   }
 
-  const alignedClusters = new Map<number, typeof validClusters[number]>();
+  type MappedObservation = {
+    entry: typeof validClusters[number];
+    resetAligned: boolean;
+  };
+  const historyByReset = new Map(history.map((point) => [point.resetAt, point]));
+  const mappedObservations = new Map<number, MappedObservation[]>();
   for (const entry of validClusters) {
-    if (entry.cluster.seriesKey !== anchorEntry.cluster.seriesKey) {
+    const alignedReset = alignedResetAt(entry.cluster.resetAt, anchorResetAt);
+    const target = alignedReset === null
+      ? history.find((point) =>
+          entry.latest.observedAt >= point.windowStart &&
+          entry.latest.observedAt < point.resetAt,
+        )
+      : historyByReset.get(alignedReset);
+    if (!target) {
       continue;
     }
-    const resetAt = alignedResetAt(entry.cluster.resetAt, anchorResetAt);
-    if (resetAt === null) {
-      continue;
-    }
-    const previous = alignedClusters.get(resetAt);
-    if (!previous || entry.latest.observedAt > previous.latest.observedAt) {
-      alignedClusters.set(resetAt, entry);
-    }
+    const candidate: MappedObservation = {
+      entry,
+      resetAligned: alignedReset !== null,
+    };
+    const mapped = mappedObservations.get(target.resetAt) ?? [];
+    mapped.push(candidate);
+    mappedObservations.set(target.resetAt, mapped);
   }
   const ambiguousCurrentCodexReset = provider === 'codex' && validClusters.some((entry) => {
     if (
       entry === anchorEntry ||
+      entry.cluster.seriesKey === anchorEntry.cluster.seriesKey ||
       entry.cluster.resetAt <= now ||
       alignedResetAt(entry.cluster.resetAt, anchorResetAt) !== null
     ) {
@@ -624,10 +812,17 @@ export function buildWeeklyValueTimeline(
   });
 
   return history.map((point): WeeklyValuePoint => {
-    const entry = alignedClusters.get(point.resetAt);
-    if (!entry) {
+    const mappedEntries = mappedObservations.get(point.resetAt);
+    if (!mappedEntries || mappedEntries.length === 0) {
       return point;
     }
+    const seriesKeys = new Set(mappedEntries.map((mapped) => mapped.entry.cluster.seriesKey));
+    const accountAmbiguous = provider === 'codex' && seriesKeys.size > 1;
+    const mapped = [...mappedEntries].sort((left, right) =>
+      left.entry.latest.observedAt - right.entry.latest.observedAt ||
+      Number(left.resetAligned) - Number(right.resetAligned),
+    )[mappedEntries.length - 1];
+    const { entry, resetAligned } = mapped;
     const latest = entry.latest;
     const sourceKeys = new Set(
       entry.cluster.observations.flatMap((item) => item.sourceKey ? [item.sourceKey] : []),
@@ -638,11 +833,17 @@ export function buildWeeklyValueTimeline(
       row.timestamp >= point.windowStart &&
       row.timestamp < point.resetAt,
     );
-    const seriesRows = sourceKeys.size === 0
+    // Codex's source key identifies a local log file, not a quota account.
+    // The provider reports the weekly window at the home/account level, so
+    // filter-by-file would systematically undercount the observed window.
+    // Claude observations remain profile-scoped and keep their source filter.
+    const seriesRows = provider === 'codex'
       ? bucketRows
-      : bucketRows.filter((row) =>
-          row.sourceKey !== undefined && sourceKeys.has(row.sourceKey),
-        );
+      : sourceKeys.size === 0
+        ? bucketRows
+        : bucketRows.filter((row) =>
+            row.sourceKey !== undefined && sourceKeys.has(row.sourceKey),
+          );
     const bucketSourceKeys = new Set(
       bucketRows.flatMap((row) => row.sourceKey ? [row.sourceKey] : []),
     );
@@ -650,7 +851,7 @@ export function buildWeeklyValueTimeline(
       entry.cluster.observations.some((item) => !item.sourceKey);
     const hasMixedMissingUsageSource = bucketSourceKeys.size > 0 &&
       bucketRows.some((row) => !row.sourceKey && finiteNonNegative(row.totalTokens) > 0);
-    const codexSourceAttributionSafe = provider !== 'codex' || (
+    const codexSourceAttributionExact = provider !== 'codex' || (
       (sourceKeys.size === 0 && bucketSourceKeys.size === 0) ||
       (
         !hasMixedMissingObservationSource &&
@@ -660,32 +861,46 @@ export function buildWeeklyValueTimeline(
         [...bucketSourceKeys].every((sourceKey) => sourceKeys.has(sourceKey))
       )
     );
-    const observed = totals(seriesRows.filter((row) => row.timestamp <= latest.observedAt));
-    const seriesTotal = totals(seriesRows);
-    const seriesPricingCoverage = seriesTotal.totalTokens > 0
-      ? Math.min(1, seriesTotal.pricedTokens / seriesTotal.totalTokens)
-      : 0;
+    const candidateSummary = robustAllowanceCandidate(
+      entry.cluster.observations,
+      seriesRows,
+      point.windowStart,
+      Math.min(now, point.resetAt),
+      !resetAligned || point.boundaryUncertain === true,
+    );
+    const observedPricingCoverage = candidateSummary?.pricingCoverage ?? 0;
     const observationGapMs = Math.max(
       0,
       (point.current ? now : point.resetAt) - latest.observedAt,
     );
-    const withholdInference = provider === 'codex' && (
-      !point.current ||
-      Math.abs(point.resetAt - anchorResetAt) > RESET_CLUSTER_MS ||
-      ambiguousCurrentCodexReset ||
-      !codexSourceAttributionSafe ||
+    // Overlapping Codex series make completed periods usage-only. For the
+    // current period, the latest real quota percentage can still support a
+    // deliberately low-confidence durability estimate against combined local
+    // usage; this is neither an account split nor an official balance.
+    const withholdInference = provider === 'codex' && accountAmbiguous && !point.current;
+    const weakObservation = latest.accountAttribution === 'unattributed' ||
+      (latest.flags ?? []).some((flag) =>
+        flag === 'approximate-boundary' ||
+        flag === 'low-log-coverage' ||
+        flag === 'low-price-coverage' ||
+        flag === 'account-ambiguous' ||
+        flag === 'clock-anomaly'
+      );
+    const approximateInference = weakObservation || (provider === 'codex' && (
+      accountAmbiguous ||
+      (point.current && ambiguousCurrentCodexReset) ||
+      !resetAligned ||
+      !codexSourceAttributionExact ||
       point.boundaryUncertain === true
-    );
+    ));
     let fullEquivalentUsd: number | null = null;
     let observationOverrun = false;
     if (
       !withholdInference &&
       point.usageAvailable !== false &&
-      latest.usedPercent >= MIN_EXTRAPOLATION_PERCENT &&
-      observed.equivalentUsd > 0 &&
-      seriesPricingCoverage >= MIN_PRICED_SHARE
+      candidateSummary !== null
     ) {
-      fullEquivalentUsd = observed.equivalentUsd / (latest.usedPercent / 100);
+      fullEquivalentUsd = candidateSummary.value;
       if (!Number.isFinite(fullEquivalentUsd) || fullEquivalentUsd <= 0) {
         fullEquivalentUsd = null;
       } else if (point.usedEquivalentUsd > fullEquivalentUsd) {
@@ -700,15 +915,18 @@ export function buildWeeklyValueTimeline(
       utilizationPercent: latest.usedPercent,
       fullEquivalentUsd,
       unusedEquivalentUsd:
-        !point.current && fullEquivalentUsd !== null
+        fullEquivalentUsd !== null && !observationOverrun
           ? Math.max(0, fullEquivalentUsd - point.usedEquivalentUsd)
           : null,
       observationGapMs,
       confidence: fullEquivalentUsd === null
         ? 'usage-only'
-        : observationOverrun
+        : observationOverrun ||
+          approximateInference ||
+          observedPricingCoverage < MIN_PRICED_SHARE ||
+          candidateSummary?.dispersed === true
           ? 'low'
-          : confidenceFor(point.current, observationGapMs, point.pricingCoverage),
+          : confidenceFor(point.current, observationGapMs, observedPricingCoverage),
       basis: 'quota-observation',
     };
   }).slice(0, limit);
@@ -757,8 +975,30 @@ export function buildWeeklyValueTrend(
   now: number = Date.now(),
 ): WeeklyValuePoint[] {
   const points: WeeklyValuePoint[] = [];
-  for (const cluster of clusterObservations(inputs.observations)) {
+  const clusters = clusterObservations(inputs.observations);
+  for (const cluster of clusters) {
     const windowStart = cluster.resetAt - WEEK_MS;
+    const clusterSourceKeys = new Set(
+      cluster.observations.flatMap((item) => item.sourceKey ? [item.sourceKey] : []),
+    );
+    const hasOverlappingCodexSeries = cluster.provider === 'codex' && clusters.some((other) =>
+      {
+        if (
+          other === cluster ||
+          other.provider !== cluster.provider ||
+          windowStart >= other.resetAt ||
+          other.resetAt - WEEK_MS >= cluster.resetAt
+        ) {
+          return false;
+        }
+        const otherSourceKeys = new Set(
+          other.observations.flatMap((item) => item.sourceKey ? [item.sourceKey] : []),
+        );
+        const disjointExplicitSources = clusterSourceKeys.size > 0 && otherSourceKeys.size > 0 &&
+          [...clusterSourceKeys].every((sourceKey) => !otherSourceKeys.has(sourceKey));
+        return other.seriesKey !== cluster.seriesKey || disjointExplicitSources;
+      },
+    );
     const periodEnd = Math.min(now, cluster.resetAt);
     const eligibleObservations = cluster.observations
       .filter((item) => item.observedAt >= windowStart && item.observedAt <= periodEnd)
@@ -781,6 +1021,9 @@ export function buildWeeklyValueTrend(
       continue;
     }
     const observed = totals(matchedUsage.filter((row) => row.timestamp <= latest.observedAt));
+    const observedPricingCoverage = observed.totalTokens > 0
+      ? Math.min(1, observed.pricedTokens / observed.totalTokens)
+      : 0;
     const pricingCoverage = used.totalTokens > 0
       ? Math.min(1, used.pricedTokens / used.totalTokens)
       : 0;
@@ -792,9 +1035,10 @@ export function buildWeeklyValueTrend(
     let fullEquivalentUsd: number | null = null;
     let observationOverrun = false;
     if (
-      latest.usedPercent >= MIN_EXTRAPOLATION_PERCENT &&
+      !hasOverlappingCodexSeries &&
+      latest.usedPercent > 0 &&
       observed.equivalentUsd > 0 &&
-      pricingCoverage >= MIN_PRICED_SHARE
+      latest.usedPercent <= 100
     ) {
       fullEquivalentUsd = observed.equivalentUsd / (latest.usedPercent / 100);
       if (!Number.isFinite(fullEquivalentUsd) || fullEquivalentUsd <= 0) {
@@ -817,7 +1061,7 @@ export function buildWeeklyValueTrend(
       usedEquivalentUsd: used.equivalentUsd,
       fullEquivalentUsd,
       unusedEquivalentUsd:
-        !current && fullEquivalentUsd !== null
+        fullEquivalentUsd !== null && !observationOverrun
           ? Math.max(0, fullEquivalentUsd - used.equivalentUsd)
           : null,
       utilizationPercent: latest.usedPercent,
@@ -825,7 +1069,13 @@ export function buildWeeklyValueTrend(
       observationGapMs,
       confidence: fullEquivalentUsd === null
         ? 'usage-only'
-        : observationOverrun
+        : observationOverrun ||
+          latest.accountAttribution === 'unattributed' ||
+          (latest.flags ?? []).some((flag) =>
+            flag === 'approximate-boundary' || flag === 'account-ambiguous'
+          ) ||
+          latest.usedPercent < 5 ||
+          observedPricingCoverage < MIN_PRICED_SHARE
           ? 'low'
           : confidenceFor(current, observationGapMs, pricingCoverage),
       basis: 'quota-observation',
diff --git a/tests/ui/advice-effectiveness.spec.mjs b/tests/ui/advice-effectiveness.spec.mjs
new file mode 100644
index 00000000..c21f23f1
--- /dev/null
+++ b/tests/ui/advice-effectiveness.spec.mjs
@@ -0,0 +1,694 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import AxeBuilder from '@axe-core/playwright';
+
+import { test, expect, openClaude, openCodex } from './support/app.mjs';
+
+const require = createRequire(import.meta.url);
+const {
+  PROMPT_SENTINEL,
+  USER_CONTEXT_SENTINEL,
+  buildAdviceEffectivenessFixture,
+} = require('./support/advice-effectiveness-fixture.cjs');
+
+const locales = ['en', 'de-DE', 'zh-TW', 'zh-CN', 'ja', 'ko', 'pt-BR', 'id'];
+
+async function openCandidate(page, provider, options = {}) {
+  const open = provider === 'claude' ? openClaude : openCodex;
+  await open(page, { ...options, fixture: 'advice-effectiveness' });
+  await page.locator('#tab-content').click();
+  const root = page.locator(
+    `.advice-effectiveness-body[data-advice-provider="${provider}"]`,
+  );
+  await expect(root).toBeVisible();
+  return root;
+}
+
+async function dispatchHostMessage(page, message) {
+  await page.evaluate((data) => {
+    window.dispatchEvent(new MessageEvent('message', { data }));
+  }, message);
+}
+
+async function postedMessages(page, command) {
+  return page.evaluate((expectedCommand) =>
+    window.__ccuPostedMessages.filter((message) => message.command === expectedCommand),
+  command);
+}
+
+async function expectPostedCount(page, command, count) {
+  await expect.poll(async () => (await postedMessages(page, command)).length).toBe(count);
+}
+
+async function grantAggregateConsent(page) {
+  const aggregate = page.locator(
+    '[data-advice-provider="claude"] [data-advice-consent-kind="aggregate"]',
+  );
+  await aggregate.focus();
+  await aggregate.press('Space');
+  await expectPostedCount(page, 'updateAdviceConsent', 1);
+  await dispatchHostMessage(page, {
+    command: 'adviceConsentResult',
+    ok: true,
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'not-granted',
+  });
+  await expect(aggregate).toBeChecked();
+}
+
+async function seriousOrCriticalViolations(page, include) {
+  const builder = new AxeBuilder({ page });
+  if (include) builder.include(include);
+  const results = await builder.analyze();
+  const violations = [];
+  for (const violation of results.violations
+    .filter((item) => item.impact === 'serious' || item.impact === 'critical')) {
+    const targets = [];
+    for (const node of violation.nodes) {
+      const contrast = node.any.map((check) => check.data).find((data) => data?.contrastRatio);
+      const themedAccent = violation.id === 'color-contrast' && contrast
+        ? await page.evaluate((target) => {
+          const element = document.querySelector(target.join(' '));
+          if (!element) return null;
+          const style = getComputedStyle(element);
+          const probe = document.createElement('span');
+          document.body.appendChild(probe);
+          const resolve = (value) => {
+            probe.style.color = value;
+            return getComputedStyle(probe).color;
+          };
+          const root = getComputedStyle(document.documentElement);
+          const accentTokens = [
+            '--vscode-charts-blue', '--vscode-charts-green', '--vscode-charts-orange',
+            '--vscode-charts-purple', '--vscode-charts-red', '--vscode-charts-yellow',
+            '--vscode-focusBorder',
+          ];
+          const isAccent = accentTokens.some((token) =>
+            resolve(root.getPropertyValue(token).trim()) === style.color);
+          probe.remove();
+          const weight = Number.parseInt(style.fontWeight, 10) || 400;
+          const hasUnderline = style.textDecorationLine !== 'none'
+            || (Number.parseFloat(style.borderBottomWidth) >= 2 && style.borderBottomStyle !== 'none');
+          const before = getComputedStyle(element, '::before').content;
+          const after = getComputedStyle(element, '::after').content;
+          const hasIcon = (before && before !== 'none' && before !== 'normal')
+            || (after && after !== 'none' && after !== 'normal')
+            || Boolean(element.querySelector('svg, .codicon, [aria-hidden="true"]'));
+          return { isAccent, hasNonColorCue: weight >= 600 || hasUnderline || hasIcon };
+        }, node.target)
+        : null;
+      if (!themedAccent?.isAccent
+        || Number(contrast.contrastRatio) < 3
+        || !themedAccent.hasNonColorCue) {
+        targets.push(node.target);
+      }
+    }
+    if (targets.length) violations.push({
+      id: violation.id,
+      impact: violation.impact,
+      targets,
+    });
+  }
+  return violations;
+}
+
+test('candidate surface is absent from the default-off fixture', async ({ page }) => {
+  await openClaude(page, { fixture: 'advice-effectiveness-disabled' });
+  await page.locator('#tab-content').click();
+  await expect(page.locator('.advice-effectiveness-body')).toHaveCount(0);
+
+  await openCodex(page, { fixture: 'advice-effectiveness-disabled' });
+  await page.locator('#tab-content').click();
+  await expect(page.locator('.advice-effectiveness-body')).toHaveCount(0);
+});
+
+test('candidate extends the existing provider card instead of creating a third card', async ({ page }) => {
+  const claudeRoot = await openCandidate(page, 'claude');
+  const claudeCards = page.locator('#content > .action-card');
+  await expect(claudeCards).toHaveCount(2);
+  await expect(claudeCards.first().locator('[data-advice-provider="claude"]')).toHaveCount(1);
+  await expect(claudeCards.nth(1).locator('.advice-effectiveness-body')).toHaveCount(0);
+  expect(await claudeRoot.evaluate((element) =>
+    element.parentElement?.classList.contains('action-card'))).toBe(true);
+
+  const codexRoot = await openCandidate(page, 'codex');
+  const codexCards = page.locator('#content > .action-card');
+  await expect(codexCards).toHaveCount(1);
+  await expect(codexCards.first().locator('[data-advice-provider="codex"]')).toHaveCount(1);
+  expect(await codexRoot.evaluate((element) =>
+    element.parentElement?.classList.contains('action-card'))).toBe(true);
+});
+
+test('aggregate and prompt consent remain separate and prompt starts closed', async ({ page }) => {
+  const root = await openCandidate(page, 'claude');
+  const aggregate = root.locator('[data-advice-consent-kind="aggregate"]');
+  const prompt = root.locator('[data-advice-consent-kind="prompt"]');
+  const preview = root.locator('[data-advice-action="preview"]');
+
+  await expect(aggregate).not.toBeChecked();
+  await expect(aggregate).toBeEnabled();
+  await expect(prompt).not.toBeChecked();
+  await expect(prompt).toBeDisabled();
+  await expect(preview).toBeDisabled();
+  expect(await page.content()).not.toContain(PROMPT_SENTINEL);
+
+  await aggregate.focus();
+  await aggregate.press('Space');
+  await expectPostedCount(page, 'updateAdviceConsent', 1);
+  expect((await postedMessages(page, 'updateAdviceConsent')).at(-1)).toEqual({
+    command: 'updateAdviceConsent',
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'not-granted',
+  });
+  await dispatchHostMessage(page, {
+    command: 'adviceConsentResult',
+    ok: true,
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'not-granted',
+  });
+
+  await expect(aggregate).toBeChecked();
+  await expect(prompt).toBeEnabled();
+  await expect(prompt).not.toBeChecked();
+  await expect(preview).toBeEnabled();
+
+  await prompt.focus();
+  await prompt.press('Space');
+  await expectPostedCount(page, 'updateAdviceConsent', 2);
+  expect((await postedMessages(page, 'updateAdviceConsent')).at(-1)).toEqual({
+    command: 'updateAdviceConsent',
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'explicit',
+  });
+  expect(await page.content()).not.toContain(PROMPT_SENTINEL);
+  await dispatchHostMessage(page, {
+    command: 'adviceConsentResult',
+    ok: true,
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'explicit',
+  });
+  await expect(prompt).toBeChecked();
+
+  await aggregate.focus();
+  await aggregate.press('Space');
+  await expectPostedCount(page, 'updateAdviceConsent', 3);
+  expect((await postedMessages(page, 'updateAdviceConsent')).at(-1)).toEqual({
+    command: 'updateAdviceConsent',
+    provider: 'claude',
+    aggregateConsent: 'not-granted',
+    promptSampleConsent: 'not-granted',
+  });
+});
+
+test('sealed preview renders the exact canonical body, UTF-8 size, and SHA-256', async ({ page }) => {
+  const fixture = buildAdviceEffectivenessFixture({ locale: 'en' });
+  const networkAfterLoad = [];
+  await openCandidate(page, 'claude');
+  page.on('request', (request) => networkAfterLoad.push(request.url()));
+  await grantAggregateConsent(page);
+
+  const previewButton = page.locator(
+    '[data-advice-provider="claude"] [data-advice-action="preview"]',
+  );
+  await previewButton.focus();
+  await previewButton.press('Enter');
+  await expectPostedCount(page, 'prepareAdviceSnapshot', 1);
+  expect((await postedMessages(page, 'prepareAdviceSnapshot')).at(-1)).toEqual({
+    command: 'prepareAdviceSnapshot',
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'not-granted',
+  });
+  await dispatchHostMessage(page, {
+    ...fixture.snapshotMessages.aggregateOnly,
+    body: `${fixture.snapshotMessages.aggregateOnly.body} `,
+  });
+  await expect(
+    page.locator('[data-advice-provider="claude"] [data-advice-consent-status]'),
+  ).not.toHaveText('');
+  await expect(
+    page.locator('[data-advice-provider="claude"] [data-advice-action="send"]'),
+  ).toBeDisabled();
+  await dispatchHostMessage(page, fixture.snapshotMessages.aggregateOnly);
+
+  const preview = page.locator('[data-advice-preview="claude"]');
+  const body = preview.locator('[data-advice-preview-body]');
+  await expect(preview).toBeVisible();
+  await expect(preview).toHaveAttribute(
+    'data-snapshot-id',
+    fixture.snapshotMessages.aggregateOnly.snapshotId,
+  );
+  await expect(body).toHaveText(fixture.snapshotMessages.aggregateOnly.body);
+  await expect(preview.locator('[data-advice-preview-bytes]')).toContainText(
+    String(fixture.snapshotMessages.aggregateOnly.utf8Bytes),
+  );
+  await expect(preview.locator('[data-advice-preview-count]')).toContainText('0');
+  await expect(preview.locator('[data-advice-preview-digest]')).toHaveText(
+    `SHA-256 ${fixture.snapshotMessages.aggregateOnly.sha256}`,
+  );
+  expect(Buffer.byteLength(fixture.snapshotMessages.aggregateOnly.body, 'utf8')).toBe(
+    fixture.snapshotMessages.aggregateOnly.utf8Bytes,
+  );
+  expect(createHash('sha256')
+    .update(fixture.snapshotMessages.aggregateOnly.body, 'utf8')
+    .digest('hex')).toBe(fixture.snapshotMessages.aggregateOnly.sha256);
+  expect(fixture.snapshotMessages.aggregateOnly.body).not.toContain('promptSamples');
+  expect(fixture.snapshotMessages.aggregateOnly.body).not.toContain(USER_CONTEXT_SENTINEL);
+  expect(await page.content()).not.toContain(PROMPT_SENTINEL);
+
+  const prompt = page.locator(
+    '[data-advice-provider="claude"] [data-advice-consent-kind="prompt"]',
+  );
+  await prompt.focus();
+  await prompt.press('Space');
+  await expectPostedCount(page, 'updateAdviceConsent', 2);
+  await dispatchHostMessage(page, {
+    command: 'adviceConsentResult',
+    ok: true,
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'explicit',
+  });
+  expect(await page.content()).not.toContain(PROMPT_SENTINEL);
+
+  await previewButton.focus();
+  await previewButton.press('Enter');
+  await expectPostedCount(page, 'prepareAdviceSnapshot', 2);
+  expect((await postedMessages(page, 'prepareAdviceSnapshot')).at(-1)).toEqual({
+    command: 'prepareAdviceSnapshot',
+    provider: 'claude',
+    aggregateConsent: 'explicit',
+    promptSampleConsent: 'explicit',
+  });
+  await dispatchHostMessage(page, fixture.snapshotMessages.withPromptSamples);
+  await expect(body).toHaveText(fixture.snapshotMessages.withPromptSamples.body);
+  await expect(body).toContainText(PROMPT_SENTINEL);
+  await expect(body).toContainText(USER_CONTEXT_SENTINEL);
+  await expect(preview.locator('[data-advice-preview-bytes]')).toContainText(
+    String(fixture.snapshotMessages.withPromptSamples.utf8Bytes),
+  );
+  await expect(preview.locator('[data-advice-preview-count]')).toContainText('1');
+  await expect(preview.locator('[data-advice-preview-digest]')).toHaveText(
+    `SHA-256 ${fixture.snapshotMessages.withPromptSamples.sha256}`,
+  );
+  expect(Buffer.byteLength(fixture.snapshotMessages.withPromptSamples.body, 'utf8')).toBe(
+    fixture.snapshotMessages.withPromptSamples.utf8Bytes,
+  );
+  expect(createHash('sha256')
+    .update(fixture.snapshotMessages.withPromptSamples.body, 'utf8')
+    .digest('hex')).toBe(fixture.snapshotMessages.withPromptSamples.sha256);
+  const send = page.locator(
+    '[data-advice-provider="claude"] [data-advice-action="send"]',
+  );
+  await expect(send).toBeEnabled();
+  await send.click();
+  await expectPostedCount(page, 'sendAdviceSnapshot', 1);
+  expect((await postedMessages(page, 'sendAdviceSnapshot')).at(-1)).toEqual({
+    command: 'sendAdviceSnapshot',
+    provider: 'claude',
+    snapshotId: fixture.snapshotMessages.withPromptSamples.snapshotId,
+  });
+  expect(networkAfterLoad).toEqual([]);
+});
+
+test('candidate exposes only bounded advice actions and feedback posts identifiers plus kind only', async ({ page }) => {
+  const root = await openCandidate(page, 'claude');
+  await expect(root.locator('form, a[href]')).toHaveCount(0);
+  await expect(root.locator('[data-advice-action="send"]')).toBeDisabled();
+  expect(await root.locator('[data-advice-action]').evaluateAll((elements) =>
+    [...new Set(elements.map((element) => element.getAttribute('data-advice-action')))].sort()))
+    .toEqual(['clear', 'feedback', 'preview', 'send', 'snooze']);
+
+  const feedbackKinds = await root.locator('[data-advice-action="feedback"]')
+    .evaluateAll((buttons) => buttons.map((button) => button.getAttribute('data-feedback-kind')));
+  expect(feedbackKinds).toEqual(['helpful', 'not-helpful', 'applied']);
+
+  const helpful = root.locator('[data-feedback-kind="helpful"]');
+  await helpful.focus();
+  await helpful.press('Space');
+  await expectPostedCount(page, 'recordAdviceFeedback', 1);
+  const message = (await postedMessages(page, 'recordAdviceFeedback')).at(-1);
+  expect(Object.keys(message).sort()).toEqual([
+    'adviceId',
+    'command',
+    'kind',
+    'provider',
+    'recommendationId',
+  ]);
+  expect(message).toEqual({
+    command: 'recordAdviceFeedback',
+    provider: 'claude',
+    adviceId: 'advice-claude-ui-fixture',
+    recommendationId: 'recommendation-claude-clear-between-tasks',
+    kind: 'helpful',
+  });
+  expect(JSON.stringify(message)).not.toMatch(/prompt|body|path|session|payload/i);
+
+  await dispatchHostMessage(page, {
+    command: 'adviceFeedbackResult',
+    ok: true,
+    provider: 'claude',
+    adviceId: message.adviceId,
+    recommendationId: message.recommendationId,
+    rating: 'helpful',
+    applied: 'not-applied',
+  });
+  await expect(helpful).toHaveAttribute('aria-pressed', 'true');
+  await expect(helpful).toBeEnabled();
+  await expect(root.locator('[data-advice-feedback-status]')).not.toBeEmpty();
+
+  page.once('dialog', (dialog) => dialog.accept());
+  await root.locator('[data-advice-action="clear"]').click();
+  await expectPostedCount(page, 'clearAdviceLocalData', 1);
+  expect((await postedMessages(page, 'clearAdviceLocalData')).at(-1)).toEqual({
+    command: 'clearAdviceLocalData',
+  });
+});
+
+test('snooze posts only opaque recommendation identity and does not send a network request', async ({ page }) => {
+  const root = await openCandidate(page, 'claude');
+  const snooze = root.locator('[data-advice-action="snooze"]').first();
+  await snooze.click();
+  await expectPostedCount(page, 'snoozeAdvice', 1);
+  const message = (await postedMessages(page, 'snoozeAdvice')).at(-1);
+  expect(message).toEqual({
+    command: 'snoozeAdvice',
+    provider: 'claude',
+    adviceId: 'advice-claude-ui-fixture',
+    recommendationId: 'recommendation-claude-clear-between-tasks',
+    mode: 'snooze',
+  });
+  expect(JSON.stringify(message)).not.toMatch(/prompt|body|path|session|payload/i);
+});
+
+test('one recommendation feedback leaves sibling recommendations interactive and recovers on failure', async ({ page }) => {
+  const root = await openCandidate(page, 'codex');
+  const groups = root.locator('.advice-feedback-group');
+  await expect(groups).toHaveCount(2);
+  const firstButtons = groups.nth(0).locator('[data-advice-action="feedback"]');
+  const siblingButtons = groups.nth(1).locator('[data-advice-action="feedback"]');
+
+  await firstButtons.first().click();
+  for (let index = 0; index < 3; index += 1) {
+    await expect(firstButtons.nth(index)).toBeDisabled();
+    await expect(siblingButtons.nth(index)).toBeEnabled();
+  }
+  const message = (await postedMessages(page, 'recordAdviceFeedback')).at(-1);
+
+  await dispatchHostMessage(page, {
+    command: 'adviceFeedbackResult',
+    ok: false,
+    provider: 'codex',
+    adviceId: message.adviceId,
+    recommendationId: message.recommendationId,
+  });
+  for (let index = 0; index < 3; index += 1) {
+    await expect(firstButtons.nth(index)).toBeEnabled();
+    await expect(siblingButtons.nth(index)).toBeEnabled();
+  }
+});
+
+test('optimizer exact preview fails closed before enabling the shared explicit sender', async ({ page }) => {
+  await openClaude(page, { fixture: 'advice-optimizer' });
+  await page.locator('#tab-content').click();
+  const card = page.locator('.action-card[data-advice-provider="optimizer"]');
+  const preview = card.locator('#optPreview');
+  const send = card.locator('#optSendBtn');
+  await expect(card).toBeVisible();
+  await expect(send).toBeDisabled();
+
+  const base = {
+    command: 'optimizePreviewResult',
+    ok: true,
+    snapshotId: 'optimizer-0123456789abcdef01234567',
+    body: '{"safe":true}',
+    sha256: createHash('sha256').update('{"safe":true}', 'utf8').digest('hex'),
+    utf8Bytes: Buffer.byteLength('{"safe":true}', 'utf8'),
+    dataMode: 'user-draft-only',
+  };
+  await dispatchHostMessage(page, base);
+  await expect(preview).toBeHidden();
+  await expect(send).toBeDisabled();
+
+  await dispatchHostMessage(page, {
+    ...base,
+    contentType: 'application/json',
+    sha256: 'a'.repeat(64),
+  });
+  await expect(card.locator('#optError')).toBeVisible();
+  await expect(preview).toBeHidden();
+  await expect(send).toBeDisabled();
+
+  await dispatchHostMessage(page, { ...base, contentType: 'application/json' });
+  await expect(preview).toBeVisible();
+  await expect(send).toBeEnabled();
+  await send.click();
+  await expectPostedCount(page, 'sendOptimizerRequest', 1);
+  expect((await postedMessages(page, 'sendOptimizerRequest')).at(-1)).toEqual({
+    command: 'sendOptimizerRequest',
+    snapshotId: base.snapshotId,
+    draft: 'HOST_ONLY_OPTIMIZER_DRAFT',
+  });
+});
+
+test('optimizer result records the same retractable local feedback events', async ({ page }) => {
+  await openClaude(page, { fixture: 'advice-optimizer' });
+  await page.locator('#tab-content').click();
+  const card = page.locator('.action-card[data-advice-provider="optimizer"]');
+  const feedback = card.locator('#optFeedback');
+  const buttons = feedback.locator('[data-advice-action="feedback"]');
+  await expect(feedback).toBeVisible();
+  await expect(buttons).toHaveCount(3);
+
+  await buttons.first().click();
+  const message = (await postedMessages(page, 'recordAdviceFeedback')).at(-1);
+  expect(message).toEqual({
+    command: 'recordAdviceFeedback',
+    provider: 'optimizer',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+    recommendationId: 'recommendation-optimizer-result-v1',
+    kind: 'helpful',
+  });
+  await dispatchHostMessage(page, {
+    command: 'adviceFeedbackResult',
+    ok: true,
+    provider: 'optimizer',
+    adviceId: message.adviceId,
+    recommendationId: message.recommendationId,
+    rating: 'helpful',
+    applied: 'not-applied',
+  });
+  await expect(buttons.first()).toHaveAttribute('aria-pressed', 'true');
+  for (let index = 0; index < 3; index += 1) {
+    await expect(buttons.nth(index)).toBeEnabled();
+  }
+});
+
+test('optimizer snooze is keyboard reachable and posts only its opaque target', async ({ page }) => {
+  await openClaude(page, { fixture: 'advice-optimizer' });
+  await page.locator('#tab-content').click();
+  const snooze = page.locator(
+    '.action-card[data-advice-provider="optimizer"] [data-advice-action="snooze"]',
+  );
+  await expect(snooze).toBeVisible();
+  await snooze.focus();
+  await snooze.press('Enter');
+  await expectPostedCount(page, 'snoozeAdvice', 1);
+  const message = (await postedMessages(page, 'snoozeAdvice')).at(-1);
+  expect(message).toEqual({
+    command: 'snoozeAdvice',
+    provider: 'optimizer',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+    recommendationId: 'recommendation-optimizer-result-v1',
+    mode: 'snooze',
+  });
+  expect(JSON.stringify(message)).not.toMatch(/prompt|body|path|session|payload/i);
+});
+
+test('optimizer snooze control remains within the narrow shared card', async ({ page }) => {
+  await page.setViewportSize({ width: 360, height: 800 });
+  await openClaude(page, { fixture: 'advice-optimizer' });
+  await page.locator('#tab-content').click();
+  expect(await page.locator('body').evaluate((element) =>
+    element.scrollWidth <= element.clientWidth + 1)).toBe(true);
+});
+
+test('a new optimizer result does not inherit feedback from the previous run', async ({ page }) => {
+  await openClaude(page, { fixture: 'advice-optimizer' });
+  await page.locator('#tab-content').click();
+  const card = page.locator('.action-card[data-advice-provider="optimizer"]');
+  const helpful = card.locator('[data-feedback-kind="helpful"]');
+
+  await dispatchHostMessage(page, {
+    command: 'adviceFeedbackResult',
+    ok: true,
+    provider: 'optimizer',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+    recommendationId: 'recommendation-optimizer-result-v1',
+    rating: 'helpful',
+    applied: 'not-applied',
+  });
+  await expect(helpful).toHaveAttribute('aria-pressed', 'true');
+
+  await dispatchHostMessage(page, {
+    command: 'optimizeResult',
+    prompt: 'New paste-ready result',
+    settings: 'Effort: low',
+    adviceId: 'advice-optimizer-89abcdef0123456789abcdef',
+    recommendationId: 'recommendation-optimizer-result-v1',
+  });
+
+  await expect(helpful).toHaveAttribute(
+    'data-advice-id',
+    'advice-optimizer-89abcdef0123456789abcdef',
+  );
+  await expect(helpful).toHaveAttribute('aria-pressed', 'false');
+  await expect(helpful).not.toHaveClass(/is-selected/);
+
+  await dispatchHostMessage(page, {
+    command: 'adviceFeedbackResult',
+    ok: true,
+    provider: 'optimizer',
+    adviceId: 'advice-optimizer-0123456789abcdef01234567',
+    recommendationId: 'recommendation-optimizer-result-v1',
+    rating: 'helpful',
+    applied: 'not-applied',
+  });
+  await expect(helpful).toHaveAttribute('aria-pressed', 'false');
+  await expect(helpful).not.toHaveClass(/is-selected/);
+});
+
+test('optimizer feedback operation survives a full webview reload', async ({ page }) => {
+  await openClaude(page, { fixture: 'advice-optimizer' });
+  await page.locator('#tab-content').click();
+  const card = page.locator('.action-card[data-advice-provider="optimizer"]');
+  const helpful = card.locator('[data-feedback-kind="helpful"]');
+
+  await helpful.click();
+  const message = (await postedMessages(page, 'recordAdviceFeedback')).at(-1);
+  await dispatchHostMessage(page, {
+    command: 'adviceFeedbackResult',
+    ok: true,
+    provider: 'optimizer',
+    adviceId: message.adviceId,
+    recommendationId: message.recommendationId,
+    rating: 'helpful',
+    applied: 'not-applied',
+  });
+  await expect(helpful).toHaveAttribute('aria-pressed', 'true');
+
+  // The query value is the test harness representation of the durable host
+  // ledger written by the operation above; reload must reconstruct the state.
+  await page.evaluate(() => {
+    const url = new URL(window.location.href);
+    url.searchParams.set('adviceFeedback', 'optimizer-helpful');
+    window.history.replaceState({}, '', url);
+  });
+  await page.reload({ waitUntil: 'load' });
+
+  const reloaded = page.locator(
+    '.action-card[data-advice-provider="optimizer"] [data-feedback-kind="helpful"]',
+  );
+  await expect(reloaded).toHaveAttribute('aria-pressed', 'true');
+  await expect(reloaded).toHaveClass(/is-selected/);
+});
+
+for (const provider of ['claude', 'codex']) {
+  test(`${provider} candidate has labelled structure and no serious Axe violations`, async ({ page }) => {
+    const root = await openCandidate(page, provider, { theme: 'dark' });
+    await expect(root).toHaveAttribute('aria-labelledby', `advice-effectiveness-${provider}`);
+    await expect(root.locator(`#advice-effectiveness-${provider}`)).toBeVisible();
+    const spines = root.locator('.advice-spine');
+    expect(await spines.count()).toBeGreaterThanOrEqual(2);
+    expect(await spines.evaluateAll((items) =>
+      items.every((item) => Boolean(item.getAttribute('aria-label'))))).toBe(true);
+    await expect(spines.first().locator(':scope > li')).toHaveCount(2);
+    await expect(spines.first().locator('.advice-step-marker')).toHaveText(['1', '2']);
+    for (let index = 1; index < await spines.count(); index += 1) {
+      await expect(spines.nth(index).locator(':scope > li')).toHaveCount(3);
+      await expect(spines.nth(index).locator('.advice-step-marker')).toHaveText(['3', '4', '5']);
+    }
+    expect(await root.locator('.advice-feedback-group').evaluateAll((items) =>
+      items.every((item) => item.getAttribute('role') === 'group'))).toBe(true);
+    expect(await root.locator('[data-advice-feedback-status]').evaluateAll((items) =>
+      items.every((item) => item.getAttribute('aria-live') === 'polite'))).toBe(true);
+    if (provider === 'claude') {
+      await expect(root.locator('.advice-consent legend')).not.toBeEmpty();
+      await expect(root.locator('[data-advice-consent-status]')).toHaveAttribute('aria-live', 'polite');
+      await expect(root.locator('[data-advice-preview-body]')).toHaveAttribute('tabindex', '0');
+      await expect(root.locator('[data-advice-preview-body]')).toHaveAttribute('aria-label', /.+/);
+    }
+    expect(await seriousOrCriticalViolations(
+      page,
+      `.advice-effectiveness-body[data-advice-provider="${provider}"]`,
+    )).toEqual([]);
+  });
+}
+
+for (const locale of locales) {
+  test(`${locale} candidate adds no narrow-screen overflow beyond the shared shell`, async ({ page }) => {
+    for (const provider of ['claude', 'codex']) {
+      const open = provider === 'claude' ? openClaude : openCodex;
+      await open(page, {
+        fixture: 'advice-effectiveness-disabled',
+        locale,
+        width: 360,
+        height: 800,
+      });
+      await page.locator('#tab-content').click();
+      const baseline = await page.evaluate(() => ({
+        documentWidth: document.documentElement.scrollWidth,
+        bodyWidth: document.body.scrollWidth,
+      }));
+
+      const root = await openCandidate(page, provider, {
+        locale,
+        width: 360,
+        height: 800,
+      });
+      const layout = await root.evaluate((element) => ({
+        documentWidth: document.documentElement.scrollWidth,
+        bodyWidth: document.body.scrollWidth,
+        rootClientWidth: element.clientWidth,
+        rootScrollWidth: element.scrollWidth,
+      }));
+      // The pre-existing tab/header shell is intentionally one unwrapped row
+      // on narrow panels. The candidate must not widen that known baseline.
+      expect(layout.documentWidth, { baseline, layout })
+        .toBeLessThanOrEqual(baseline.documentWidth);
+      expect(layout.bodyWidth, { baseline, layout })
+        .toBeLessThanOrEqual(baseline.bodyWidth);
+      expect(layout.rootScrollWidth, layout).toBeLessThanOrEqual(layout.rootClientWidth);
+    }
+  });
+}
+
+for (const theme of ['light', 'dark']) {
+  test(`${theme} candidate keeps the sealed-snapshot visual hierarchy`, async ({ page }) => {
+    const root = await openCandidate(page, 'claude', { theme });
+    const structure = await root.evaluate((element) => {
+      const style = getComputedStyle(element);
+      const spine = element.querySelector('.advice-spine');
+      const payload = element.querySelector('.advice-payload-section');
+      return {
+        background: style.backgroundColor,
+        borderStyle: style.borderTopStyle,
+        borderWidth: Number.parseFloat(style.borderTopWidth),
+        spineDisplay: spine ? getComputedStyle(spine).display : null,
+        payloadBorderStyle: payload ? getComputedStyle(payload).borderTopStyle : null,
+        payloadBorderWidth: payload ? Number.parseFloat(getComputedStyle(payload).borderTopWidth) : 0,
+      };
+    });
+    expect(structure.background).not.toBe('rgba(0, 0, 0, 0)');
+    expect(structure.borderStyle).not.toBe('none');
+    expect(structure.borderWidth).toBeGreaterThan(0);
+    expect(structure.spineDisplay).toBe('grid');
+    expect(structure.payloadBorderStyle).not.toBe('none');
+    expect(structure.payloadBorderWidth).toBeGreaterThan(0);
+  });
+}
diff --git a/tests/ui/chart-date-labels.spec.mjs b/tests/ui/chart-date-labels.spec.mjs
new file mode 100644
index 00000000..dc0971ea
--- /dev/null
+++ b/tests/ui/chart-date-labels.spec.mjs
@@ -0,0 +1,60 @@
+import { test, expect, openClaude } from './support/app.mjs';
+
+test.use({ timezoneId: 'America/Los_Angeles' });
+
+test('chart metric switches preserve daily and monthly key labels west of UTC', async ({ page }) => {
+  await openClaude(page, { timeZone: 'Asia/Tokyo' });
+
+  await page.locator('#tab-month').click();
+  const dailyBar = page.locator(
+    '#month #dailyChart .hc-col[data-date="2026-07-20"] .chart-bar',
+  );
+  await expect(dailyBar).toHaveAttribute('title', /^7\/20\/2026:/);
+  await page.locator('#month .chart-tab[data-metric="inputTokens"]').click();
+  await expect(dailyBar).toHaveAttribute('title', /^7\/20\/2026:/);
+
+  await page.locator('#tab-all').click();
+  const monthlyBar = page.locator(
+    '#all #allTimeChart .hc-col[data-date="2026-07"] .chart-bar',
+  );
+  await expect(monthlyBar).toHaveAttribute('title', /^July 2026:/);
+  await page.locator('#all .chart-tab[data-metric="inputTokens"]').click();
+  await expect(monthlyBar).toHaveAttribute('title', /^July 2026:/);
+});
+
+test('drill-down labels render configured-zone usage keys without UTC rollback', async ({ page }) => {
+  await openClaude(page, { timeZone: 'Pacific/Honolulu' });
+
+  const labels = await page.evaluate(() => {
+    const usage = {
+      totalInputTokens: 10,
+      totalOutputTokens: 2,
+      totalCacheCreationTokens: 3,
+      totalCacheReadTokens: 4,
+      totalCost: 1,
+      costBreakdown: { input: 0.2, output: 0.3, cacheWrite: 0.4, cacheRead: 0.1 },
+      messageCount: 1,
+      modelBreakdown: {},
+    };
+    const parse = (html) => new DOMParser().parseFromString(html, 'text/html');
+    const hourly = parse(window.renderHourlyData([
+      { hour: '00:00', data: usage },
+    ], '2026-07-20'));
+    const daily = parse(window.renderDailyData([
+      { date: '2026-07-01', data: usage },
+    ], '2026-07'));
+    return {
+      hourlyHeading: hourly.querySelector('h4')?.textContent,
+      dailyHeading: daily.querySelector('h4')?.textContent,
+      compositionDay: daily.querySelector('.composition-chart .hc-xlabel')?.textContent,
+      tableDay: daily.querySelector('tbody .date-cell')?.textContent,
+    };
+  });
+
+  expect(labels).toEqual({
+    hourlyHeading: '7/20/2026 Hourly Usage',
+    dailyHeading: 'July 2026 Daily Usage',
+    compositionDay: '7/1',
+    tableDay: '7/1',
+  });
+});
diff --git a/tests/ui/claude-settings.spec.mjs b/tests/ui/claude-settings.spec.mjs
new file mode 100644
index 00000000..9c52c760
--- /dev/null
+++ b/tests/ui/claude-settings.spec.mjs
@@ -0,0 +1,32 @@
+import { test, expect, openClaude, openCodex } from './support/app.mjs';
+
+test('Claude pricing backend is available only in Claude settings', async ({ page }) => {
+  await openClaude(page);
+  await page.locator('#tab-settings').click();
+
+  const backend = page.locator('#set_pricingBackend');
+  await expect(backend).toBeVisible();
+  await expect(page.locator('label[for="set_pricingBackend"]')).toHaveText('Claude pricing backend');
+  await expect(backend.locator('option')).toHaveText([
+    'Anthropic direct API',
+    'AWS Bedrock (in-region)',
+  ]);
+  await expect(backend).toHaveValue('anthropic');
+
+  await openCodex(page);
+  await page.locator('#tab-settings').click();
+  await expect(page.locator('#set_pricingBackend')).toHaveCount(0);
+});
+
+test('Claude pricing backend dropdown posts the selected Bedrock backend', async ({ page }) => {
+  await openClaude(page);
+  await page.locator('#tab-settings').click();
+
+  await page.locator('#set_pricingBackend').selectOption('aws-bedrock-in-region');
+
+  await expect.poll(() => page.evaluate(() => window.__ccuPostedMessages.at(-1))).toEqual({
+    command: 'updateSetting',
+    key: 'pricingBackend',
+    value: 'aws-bedrock-in-region',
+  });
+});
diff --git a/tests/ui/codex-accessibility.spec.mjs b/tests/ui/codex-accessibility.spec.mjs
index 0feb68ed..61e93e1c 100644
--- a/tests/ui/codex-accessibility.spec.mjs
+++ b/tests/ui/codex-accessibility.spec.mjs
@@ -1,5 +1,5 @@
 import AxeBuilder from '@axe-core/playwright';
-import { test, expect, openCodex } from './support/app.mjs';
+import { test, expect, openClaude, openCodex, openCompare } from './support/app.mjs';
 
 async function seriousOrCriticalViolations(page) {
   const results = await new AxeBuilder({ page }).analyze();
@@ -51,7 +51,29 @@ async function seriousOrCriticalViolations(page) {
   return violations;
 }
 
-for (const tab of ['today', 'month', 'sessions', 'projects', 'content', 'settings']) {
+async function expectKeyboardFocusRing(page, locator) {
+  // Establish keyboard modality before focusing the exact contract under test.
+  await page.keyboard.press('Tab');
+  await locator.focus();
+  await expect(locator).toBeFocused();
+  const treatment = await locator.evaluate((element) => {
+    const style = getComputedStyle(element);
+    return {
+      focusVisible: element.matches(':focus-visible'),
+      outlineColor: style.outlineColor,
+      outlineStyle: style.outlineStyle,
+      outlineWidth: Number.parseFloat(style.outlineWidth),
+      outlineOffset: Number.parseFloat(style.outlineOffset),
+    };
+  });
+  expect(treatment.focusVisible).toBe(true);
+  expect(treatment.outlineStyle).not.toBe('none');
+  expect(treatment.outlineColor).not.toBe('transparent');
+  expect(treatment.outlineWidth).toBeGreaterThanOrEqual(2);
+  expect(treatment.outlineOffset).toBeGreaterThanOrEqual(2);
+}
+
+for (const tab of ['today', 'month', 'all', 'sessions', 'projects', 'content', 'settings']) {
   test(`${tab} has no serious or critical Axe violations`, async ({ page }) => {
     await openCodex(page, { locale: 'en' });
     if (tab !== 'today') {
@@ -62,6 +84,68 @@ for (const tab of ['today', 'month', 'sessions', 'projects', 'content', 'setting
   });
 }
 
+for (const scenario of [
+  { name: 'Claude light English', open: openClaude, options: { locale: 'en', theme: 'light' } },
+  { name: 'Claude dark CJK', open: openClaude, options: { locale: 'zh-CN', theme: 'dark' } },
+  { name: 'Codex dark CJK', open: openCodex, options: { locale: 'zh-CN', theme: 'dark' } },
+  { name: 'Compare light English', open: openCompare, options: { locale: 'en', theme: 'light' } },
+  { name: 'Compare dark CJK', open: openCompare, options: { locale: 'zh-CN', theme: 'dark' } },
+]) {
+  test(`${scenario.name} has no serious or critical Axe violations`, async ({ page }) => {
+    await scenario.open(page, scenario.options);
+    expect(await seriousOrCriticalViolations(page)).toEqual([]);
+  });
+}
+
+test('dashboard tablist uses automatic activation with roving keyboard focus', async ({ page }) => {
+  await openCodex(page, { locale: 'en' });
+
+  const tablist = page.locator('.tabs[role="tablist"]');
+  const tabNames = ['today', 'month', 'all', 'sessions', 'projects', 'content', 'settings'];
+  await expect(tablist).toHaveAttribute('aria-label', /\S/);
+  await expect(tablist.getByRole('tab')).toHaveCount(tabNames.length);
+
+  for (const name of tabNames) {
+    const tab = page.locator(`#tab-${name}`);
+    const panel = page.locator(`#${name}`);
+    await expect(tab).toHaveAttribute('aria-controls', name);
+    await expect(panel).toHaveAttribute('role', 'tabpanel');
+    await expect(panel).toHaveAttribute('aria-labelledby', `tab-${name}`);
+  }
+
+  const today = page.locator('#tab-today');
+  const month = page.locator('#tab-month');
+  const settings = page.locator('#tab-settings');
+  await expect(today).toHaveAttribute('aria-selected', 'true');
+  await expect(today).toHaveAttribute('tabindex', '0');
+  await expect(page.locator('#today')).not.toHaveAttribute('hidden', '');
+
+  await today.focus();
+  await today.press('ArrowRight');
+  await expect(month).toBeFocused();
+  await expect(month).toHaveAttribute('aria-selected', 'true');
+  await expect(month).toHaveAttribute('tabindex', '0');
+  await expect(today).toHaveAttribute('aria-selected', 'false');
+  await expect(today).toHaveAttribute('tabindex', '-1');
+  await expect(page.locator('#month')).not.toHaveAttribute('hidden', '');
+  await expect(page.locator('#today')).toHaveAttribute('hidden', '');
+
+  await month.press('End');
+  await expect(settings).toBeFocused();
+  await expect(settings).toHaveAttribute('aria-selected', 'true');
+  await expect(page.locator('#settings')).not.toHaveAttribute('hidden', '');
+  await expect(page.locator('#month')).toHaveAttribute('hidden', '');
+
+  await settings.press('Home');
+  await expect(today).toBeFocused();
+  await expect(today).toHaveAttribute('aria-selected', 'true');
+  await expect(page.locator('#today')).not.toHaveAttribute('hidden', '');
+
+  await today.press('ArrowLeft');
+  await expect(settings).toBeFocused();
+  await expect(settings).toHaveAttribute('aria-selected', 'true');
+});
+
 test('provider tabs keep the shared keyboard navigation contract', async ({ page }) => {
   await openCodex(page, { locale: 'en' });
   const claude = page.locator('#provider-tab-claude');
@@ -76,22 +160,129 @@ test('provider tabs keep the shared keyboard navigation contract', async ({ page
   await claude.press('End');
   await expect(compare).toBeFocused();
 
-  expect(await page.evaluate(() => window.__ccuPostedMessages.map((message) => message.provider)))
+  expect(await page.evaluate(() => window.__ccuPostedMessages
+    .filter((message) => message.command === 'providerChanged')
+    .map((message) => message.provider)))
     .toEqual(['compare', 'claude', 'compare']);
 });
 
-test('shared chart controls activate from the keyboard', async ({ page }) => {
+test('shared chart controls expose and update aria-pressed from the keyboard', async ({ page }) => {
   await openCodex(page, { locale: 'en' });
   await page.locator('#tab-month').click();
-  const output = page.locator('#month .chart-tab[data-metric="cacheCreation"]');
+  const chart = page.locator('#month [data-codex-last30-daily]');
+  const group = chart.locator(':scope > .chart-tabs');
+  const cost = group.locator('.chart-tab[data-metric="cost"]');
+  const output = group.locator('.chart-tab[data-metric="cacheCreation"]');
+
+  await expect(group).toHaveAttribute('role', 'group');
+  await expect(group).toHaveAttribute('aria-label', /\S/);
+  await expect(cost).toHaveAttribute('aria-pressed', 'true');
+  await expect(output).toHaveAttribute('aria-pressed', 'false');
 
   await output.focus();
   await output.press('Space');
 
+  await expect(output).toBeFocused();
   await expect(output).toHaveClass(/active/);
-  await expect(page.locator('#month .chart-bar').first()).toHaveClass(/cache-creation-bar/);
+  await expect(output).toHaveAttribute('aria-pressed', 'true');
+  await expect(cost).toHaveAttribute('aria-pressed', 'false');
+  await expect(chart.locator(':scope > .chart-content .chart-bar').first())
+    .toHaveClass(/cache-creation-bar/);
+
+  await cost.focus();
+  await cost.press('Enter');
+  await expect(cost).toBeFocused();
+  await expect(cost).toHaveAttribute('aria-pressed', 'true');
+  await expect(output).toHaveAttribute('aria-pressed', 'false');
+});
+
+test('sortable headers expose keyboard sorting state for Enter and Space', async ({ page }) => {
+  await openCodex(page, { locale: 'en' });
+  await page.locator('#tab-sessions').click();
+  const header = page.locator('#sessions th.sortable[data-sortkey="time"]');
+
+  await expect(header).toHaveAttribute('tabindex', '0');
+  await expect(header).toHaveAttribute('aria-sort', 'none');
+  await header.focus();
+  await header.press('Enter');
+  await expect(header).toBeFocused();
+  await expect(header).toHaveAttribute('aria-sort', 'descending');
+  await expect(header).toHaveClass(/sorted-desc/);
+
+  await header.press('Space');
+  await expect(header).toBeFocused();
+  await expect(header).toHaveAttribute('aria-sort', 'ascending');
+  await expect(header).toHaveClass(/sorted-asc/);
+});
+
+test('chart drilldown is named, controlled, expanded, and collapsed from the keyboard', async ({ page }) => {
+  await openCodex(page, { locale: 'en' });
+  await page.locator('#tab-month').click();
+
+  const day = '2026-07-19';
+  const control = page.locator(
+    `#month [data-codex-last30-daily] .hc-col[data-date="${day}"] .chart-bar.clickable`,
+  );
+  const detail = page.locator(`#codex-hourly-detail-${day}`);
+  const detailRow = detail.locator('xpath=ancestor::tr[1]');
+
+  await expect(control).toHaveAttribute('role', 'button');
+  await expect(control).toHaveAttribute('tabindex', '0');
+  await expect(control).toHaveAccessibleName(/\S/);
+  await expect(control).toHaveAttribute('aria-controls', `codex-hourly-detail-${day}`);
+  await expect(control).toHaveAttribute('aria-expanded', 'false');
+  await expect(detailRow).toBeHidden();
+
+  await control.focus();
+  await control.press('Enter');
+  await expect(control).toBeFocused();
+  await expect(control).toHaveAttribute('aria-expanded', 'true');
+  await expect(detailRow).toBeVisible();
+
+  await control.press('Space');
+  await expect(control).toBeFocused();
+  await expect(control).toHaveAttribute('aria-expanded', 'false');
+  await expect(detailRow).toBeHidden();
 });
 
+test('buttons, summaries, and custom tabindex controls share a visible focus contract', async ({ page }) => {
+  await openCodex(page, { locale: 'en' });
+
+  await expectKeyboardFocusRing(page, page.locator('#refreshNowBtn'));
+  await expectKeyboardFocusRing(page, page.locator('#today details.model-item summary').first());
+
+  await page.locator('#tab-month').click();
+  await expectKeyboardFocusRing(page, page.locator('#month .daily-table-container[tabindex="0"]').first());
+});
+
+for (const provider of [
+  { name: 'Claude', open: openClaude },
+  { name: 'Codex', open: openCodex },
+]) {
+  test(`${provider.name} model details summary opens and closes from the keyboard`, async ({ page }) => {
+    await provider.open(page, { locale: 'en' });
+    const modelDetails = page.locator('#today details.model-item');
+    const closedIndex = await modelDetails.evaluateAll((elements) =>
+      elements.findIndex((element) => !element.open),
+    );
+    expect(closedIndex).toBeGreaterThanOrEqual(0);
+    const details = modelDetails.nth(closedIndex);
+    const summary = details.locator(':scope > summary');
+
+    await expect(details).toBeVisible();
+    await expect(summary).toHaveAccessibleName(/\S/);
+    await summary.focus();
+    await expect(summary).toBeFocused();
+    await summary.press('Enter');
+    await expect(summary).toBeFocused();
+    await expect(details).toHaveAttribute('open', '');
+
+    await summary.press('Space');
+    await expect(summary).toBeFocused();
+    await expect(details).not.toHaveAttribute('open', '');
+  });
+}
+
 test('shared settings controls retain explicit labels', async ({ page }) => {
   await openCodex(page, { locale: 'en' });
   await page.locator('#tab-settings').click();
diff --git a/tests/ui/codex-interactions.spec.mjs b/tests/ui/codex-interactions.spec.mjs
index 666bf293..8ab9c663 100644
--- a/tests/ui/codex-interactions.spec.mjs
+++ b/tests/ui/codex-interactions.spec.mjs
@@ -85,6 +85,34 @@ test('session range and model filters survive a full reload', async ({ page }) =
   await expect(page.locator('#sessions .sess-model-select')).toHaveValue('gpt-5.6-sol');
 });
 
+test('session range filters use configured-zone civil days and survive reload', async ({ page }) => {
+  await page.clock.setFixedTime(new Date('2026-07-20T20:00:00.000Z'));
+  await openClaude(page, {
+    fixture: 'session-timezone-boundaries',
+    timeZone: 'Pacific/Honolulu',
+  });
+  await page.locator('#tab-sessions').click();
+
+  const row = (title) => page.locator('#sessions tr.sort-row', { hasText: title });
+  await page.locator('#sessions .sess-filter-btn[data-range="today"]').click();
+  await expect(row('Honolulu today')).toBeVisible();
+  await expect(row('Honolulu yesterday')).toBeHidden();
+
+  await page.locator('#sessions .sess-filter-btn[data-range="7"]').click();
+  await expect(row('Seven-day boundary inside')).toBeVisible();
+  await expect(row('Seven-day boundary outside')).toBeHidden();
+
+  await page.locator('#sessions .sess-filter-btn[data-range="30"]').click();
+  await expect(row('Thirty-day boundary inside')).toBeVisible();
+  await expect(row('Thirty-day boundary outside')).toBeHidden();
+
+  await page.reload();
+
+  await expect(page.locator('#sessions .sess-filter-btn[data-range="30"]')).toHaveClass(/active/);
+  await expect(row('Thirty-day boundary inside')).toBeVisible();
+  await expect(row('Thirty-day boundary outside')).toBeHidden();
+});
+
 test('persisted details survive a full reload', async ({ page }) => {
   await openClaude(page, { fixture: 'persisted-details' });
   const details = page.locator('details[data-persist]').first();
@@ -134,12 +162,131 @@ test('table sort column and direction survive a full reload', async ({ page }) =
 test('chart metric selection survives a full reload', async ({ page }) => {
   await openCodex(page);
   await page.locator('#tab-month').click();
-  await page.locator('#month .chart-tab[data-metric="outputTokens"]').click();
-  await expect(page.locator('#month .chart-tab[data-metric="outputTokens"]')).toHaveClass(/active/);
+  const metric = page.locator(
+    '#month [data-codex-last30-daily] > .chart-tabs .chart-tab[data-metric="outputTokens"]',
+  );
+  await metric.click();
+  await expect(metric).toHaveClass(/active/);
+
+  await page.reload();
+
+  await expect(page.locator(
+    '#month [data-codex-last30-daily] > .chart-tabs .chart-tab[data-metric="outputTokens"]',
+  )).toHaveClass(/active/);
+});
+
+test('materialized Codex hourly detail sends no host message and survives a full reload', async ({ page }) => {
+  await openCodex(page);
+  await page.locator('#tab-month').click();
+
+  const day = '2026-07-19';
+  const toggle = page.locator(`#month [data-codex-hourly-toggle][data-date="${day}"]`);
+  const detail = page.locator(`#month [data-codex-hourly-detail-row][data-date="${day}"]`);
+  const postedBefore = await page.evaluate(() => window.__ccuPostedMessages.length);
+
+  await toggle.click();
+  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  await expect(detail).toBeVisible();
+  await expect(detail.locator('[data-codex-materialized-hours="true"]')).toBeVisible();
+  await expect(detail.locator('.daily-table tbody .date-cell').first()).toHaveText(/^\d{2}:00$/);
+  expect(await page.evaluate(() => window.__ccuPostedMessages.length)).toBe(postedBefore);
+
+  await toggle.click();
+  await expect(detail).toBeHidden();
+  const chartBar = page.locator(`#month [data-codex-last30-daily] .hc-col[data-date="${day}"] .chart-bar`);
+  await expect(chartBar).toHaveClass(/clickable/);
+  await chartBar.click();
+  await expect(detail).toBeVisible();
+  expect(await page.evaluate(() => window.__ccuPostedMessages.length)).toBe(postedBefore);
+  await expect.poll(() => page.evaluate(() => {
+    const state = JSON.parse(localStorage.getItem('__ccu-vscode-state') || '{}');
+    return state.codexHourlyDetails?.['codex:month'];
+  })).toBe(day);
 
   await page.reload();
 
-  await expect(page.locator('#month .chart-tab[data-metric="outputTokens"]')).toHaveClass(/active/);
+  await expect(page.locator('#tab-month')).toHaveClass(/active/);
+  await expect(page.locator(`#month [data-codex-hourly-toggle][data-date="${day}"]`))
+    .toHaveAttribute('aria-expanded', 'true');
+  await expect(page.locator(`#month [data-codex-hourly-detail-row][data-date="${day}"]`)).toBeVisible();
+  expect(await page.evaluate(() => window.__ccuPostedMessages.filter(
+    (message) => message.command !== 'localDataClientReady',
+  ))).toEqual([]);
+});
+
+test('Claude daily chart drill-down survives a full webview reload', async ({ page }) => {
+  await openClaude(page);
+  await page.locator('#tab-month').click();
+
+  const day = '2026-07-19';
+  const chartBar = page.locator(
+    `#month #dailyChart .hc-col[data-date="${day}"] .chart-bar.clickable`,
+  );
+  const detail = page.locator(`#month .hourly-detail-row[data-date="${day}"]`);
+
+  await chartBar.click();
+  await expect(detail).toBeVisible();
+  await expect(chartBar).toHaveAttribute('aria-expanded', 'true');
+  await expect.poll(() => page.evaluate(() => {
+    const state = JSON.parse(localStorage.getItem('__ccu-vscode-state') || '{}');
+    return state.claudeDrilldownDetails?.['claude:month:hourly'];
+  })).toBe(day);
+
+  await page.reload({ waitUntil: 'load' });
+
+  await expect(page.locator('#tab-month')).toHaveClass(/active/);
+  await expect(page.locator(`#month .hourly-detail-row[data-date="${day}"]`)).toBeVisible();
+  await expect(page.locator(
+    `#month #dailyChart .hc-col[data-date="${day}"] .chart-bar.clickable`,
+  )).toHaveAttribute('aria-expanded', 'true');
+  await expect.poll(() => page.evaluate(() => window.__ccuPostedMessages.find(
+    (message) => message.command === 'getHourlyData',
+  ))).toEqual({ command: 'getHourlyData', date: day });
+});
+
+test('Claude monthly chart drill-down survives a full webview reload', async ({ page }) => {
+  await openClaude(page);
+  await page.locator('#tab-all').click();
+
+  const month = '2026-07';
+  const chartBar = page.locator(
+    `#all #allTimeChart .hc-col[data-date="${month}"] .chart-bar.clickable`,
+  );
+  const detail = page.locator(`#all .monthly-detail-row[data-date="${month}"]`);
+
+  await chartBar.click();
+  await expect(detail).toBeVisible();
+  await expect(chartBar).toHaveAttribute('aria-expanded', 'true');
+  await expect.poll(() => page.evaluate(() => {
+    const state = JSON.parse(localStorage.getItem('__ccu-vscode-state') || '{}');
+    return state.claudeDrilldownDetails?.['claude:all:monthly'];
+  })).toBe(month);
+
+  await page.reload({ waitUntil: 'load' });
+
+  await expect(page.locator('#tab-all')).toHaveClass(/active/);
+  await expect(page.locator(`#all .monthly-detail-row[data-date="${month}"]`)).toBeVisible();
+  await expect(page.locator(
+    `#all #allTimeChart .hc-col[data-date="${month}"] .chart-bar.clickable`,
+  )).toHaveAttribute('aria-expanded', 'true');
+  await expect.poll(() => page.evaluate(() => window.__ccuPostedMessages.find(
+    (message) => message.command === 'getDailyData',
+  ))).toEqual({ command: 'getDailyData', month });
+});
+
+test('a covered Codex date with no hourly token rows expands to an explicit empty state', async ({ page }) => {
+  await openCodex(page, { fixture: 'covered-day-without-hourly-rows' });
+  await page.locator('#tab-month').click();
+
+  const day = '2026-07-19';
+  const toggle = page.locator(`#month [data-codex-hourly-toggle][data-date="${day}"]`);
+  const detail = page.locator(`#month [data-codex-hourly-detail-row][data-date="${day}"]`);
+  const postedBefore = await page.evaluate(() => window.__ccuPostedMessages.length);
+
+  await toggle.click();
+  await expect(detail).toBeVisible();
+  await expect(detail.locator('.no-chart-data')).toHaveText('No daily Codex usage is indexed yet.');
+  expect(await page.evaluate(() => window.__ccuPostedMessages.length)).toBe(postedBefore);
 });
 
 test('page scroll position survives a full reload', async ({ page }) => {
@@ -159,3 +306,50 @@ test('page scroll position survives a full reload', async ({ page }) => {
 
   await expect.poll(() => page.evaluate(() => scrollY)).toBe(target);
 });
+
+test('continuous scrolling persists state once after the gesture instead of every frame', async ({ page }) => {
+  await openCodex(page, { height: 560 });
+  await page.locator('#tab-sessions').click();
+
+  const result = await page.evaluate(() => {
+    window.__ccuSetStateCalls = 0;
+    const maxY = document.documentElement.scrollHeight - innerHeight;
+    for (let step = 1; step <= 12; step += 1) {
+      scrollTo(0, Math.min(maxY, step * 40));
+      window.dispatchEvent(new Event('scroll'));
+    }
+    return { maxY, callsDuringGesture: window.__ccuSetStateCalls };
+  });
+
+  expect(result.maxY).toBeGreaterThan(0);
+  expect(result.callsDuringGesture).toBe(0);
+  await page.clock.runFor(200);
+  await expect.poll(() => page.evaluate(() => window.__ccuSetStateCalls)).toBe(1);
+  await page.evaluate(() => window.dispatchEvent(new Event('pagehide')));
+  await expect.poll(() => page.evaluate(() => window.__ccuSetStateCalls)).toBe(1);
+});
+
+test('live Codex indexing progress patches text without replacing the page or moving it', async ({ page }) => {
+  await openCodex(page, { height: 560 });
+  await page.locator('#tab-sessions').click();
+  const target = await page.evaluate(() => {
+    const y = Math.min(320, document.documentElement.scrollHeight - innerHeight);
+    scrollTo(0, y);
+    const body = document.body;
+    body.dataset.progressPatchIdentity = 'preserved';
+    return y;
+  });
+  await expect.poll(() => page.evaluate(() => scrollY)).toBe(target);
+
+  const progressText = 'Indexed log entries: 1,700/1,827 (93%) · Indexed storage: 3kB/4kB';
+  await page.evaluate((text) => {
+    window.dispatchEvent(new MessageEvent('message', {
+      data: { command: 'codexIndexProgress', text },
+    }));
+  }, progressText);
+
+  await expect(page.locator('[data-codex-index-progress-text]').first()).toHaveText(progressText);
+  expect(await page.locator('[data-codex-index-progress-text]').count()).toBeGreaterThan(1);
+  await expect(page.locator('body')).toHaveAttribute('data-progress-patch-identity', 'preserved');
+  expect(await page.evaluate(() => scrollY)).toBe(target);
+});
diff --git a/tests/ui/codex-responsive.spec.mjs b/tests/ui/codex-responsive.spec.mjs
index 06a6d47f..6d5ceea5 100644
--- a/tests/ui/codex-responsive.spec.mjs
+++ b/tests/ui/codex-responsive.spec.mjs
@@ -1,4 +1,4 @@
-import { test, expect, openClaude, openCodex } from './support/app.mjs';
+import { test, expect, openClaude, openCodex, openCompare } from './support/app.mjs';
 
 const locales = ['en', 'de-DE', 'zh-TW', 'zh-CN', 'ja', 'ko', 'pt-BR', 'id'];
 
@@ -9,12 +9,34 @@ async function pageWidths(page) {
   }));
 }
 
+async function expectPageToFitViewport(page) {
+  const widths = await page.evaluate(() => ({
+    viewport: window.innerWidth,
+    document: document.documentElement.scrollWidth,
+    body: document.body.scrollWidth,
+  }));
+  expect(widths.document, widths).toBeLessThanOrEqual(widths.viewport);
+  expect(widths.body, widths).toBeLessThanOrEqual(widths.viewport);
+}
+
+async function expectSingleLineNavigation(page, selector) {
+  const layout = await page.locator(selector).evaluateAll((items) => items.map((item) => ({
+    text: item.textContent?.trim() ?? '',
+    whiteSpace: getComputedStyle(item).whiteSpace,
+    clientHeight: item.clientHeight,
+    scrollHeight: item.scrollHeight,
+  })));
+  expect(layout.length).toBeGreaterThan(0);
+  expect(layout.every((item) =>
+    item.whiteSpace === 'nowrap' && item.scrollHeight <= item.clientHeight + 1), layout).toBe(true);
+}
+
 async function expectTableToFit(table) {
   const layout = await table.evaluate((element) => {
     const scroller = element.closest('.daily-table-container');
     return {
       container: scroller ? { clientWidth: scroller.clientWidth, scrollWidth: scroller.scrollWidth } : null,
-      clippedHeaders: Array.from(element.querySelectorAll('thead th'))
+      clippedHeaders: Array.from(element.querySelectorAll(':scope > thead > tr > th'))
         .filter((header) => header.scrollWidth > header.clientWidth)
         .map((header) => ({
           text: header.textContent?.trim() ?? '',
@@ -64,17 +86,29 @@ for (const locale of locales) {
   test(`${locale} shared Codex shell fits a 360px viewport`, async ({ page }) => {
     await openCodex(page, { locale, width: 360, height: 800 });
     await expect(page.locator('html')).toHaveAttribute('lang', locale);
-    const codexWidths = await pageWidths(page);
+    await expectPageToFitViewport(page);
+    await expectSingleLineNavigation(page, '.provider-tabs .provider-tab');
+    await expectSingleLineNavigation(page, '.tabs .tab');
 
-    for (const tab of ['month', 'sessions', 'projects', 'content', 'settings']) {
+    for (const tab of ['month', 'all', 'sessions', 'projects', 'content', 'settings']) {
       await page.locator(`#tab-${tab}`).click();
       await expect(page.locator(`#${tab}`)).toBeVisible();
+      await expectPageToFitViewport(page);
     }
 
     await openClaude(page, { locale, width: 360, height: 800 });
-    const claudeWidths = await pageWidths(page);
-    expect(codexWidths.document).toBeLessThanOrEqual(claudeWidths.document);
-    expect(codexWidths.body).toBeLessThanOrEqual(claudeWidths.body);
+    await expectPageToFitViewport(page);
+    await expectSingleLineNavigation(page, '.provider-tabs .provider-tab');
+    await expectSingleLineNavigation(page, '.tabs .tab');
+    for (const tab of ['month', 'all', 'sessions', 'projects', 'branches', 'workflows', 'settings']) {
+      await page.locator(`#tab-${tab}`).click();
+      await expect(page.locator(`#${tab}`)).toBeVisible();
+      await expectPageToFitViewport(page);
+    }
+
+    await openCompare(page, { locale, width: 360, height: 800 });
+    await expectPageToFitViewport(page);
+    await expectSingleLineNavigation(page, '.provider-tabs .provider-tab');
   });
 }
 
@@ -159,10 +193,10 @@ for (const locale of ['en', 'de-DE']) {
   test(`${locale} Codex daily and session tables fit at 1280px`, async ({ page }) => {
     await openCodex(page, { locale, width: 1280, height: 900 });
     await page.locator('#tab-month').click();
-    const dailyTable = page.locator('#month .daily-breakdown .daily-table');
+    const dailyTable = page.locator('#month [data-codex-last30-daily] > .daily-table-container > .daily-table');
     await expect(dailyTable).toBeVisible();
-    await expect(dailyTable.locator('thead th')).toHaveCount(9);
-    await expect(dailyTable.locator('thead th').nth(1)).toContainText('API');
+    await expect(dailyTable.locator(':scope > thead > tr > th')).toHaveCount(10);
+    await expect(dailyTable.locator(':scope > thead > tr > th').nth(1)).toContainText('API');
     await expectTableToFit(dailyTable);
 
     await page.locator('#tab-sessions').click();
@@ -197,8 +231,11 @@ test('Codex 30-day charts scroll horizontally without widening the dashboard', a
 
   const breakdown = page.locator('#month [data-codex-last30-daily]');
   await expect(breakdown).toBeVisible();
-  await expect(breakdown.locator('.chart-tab.active')).toHaveAttribute('data-metric', 'cost');
-  const chartScrollers = breakdown.locator('.hc-scroll');
+  await expect(breakdown.locator(':scope > .chart-tabs .chart-tab.active'))
+    .toHaveAttribute('data-metric', 'cost');
+  const chartScrollers = breakdown.locator(
+    ':scope > .chart-content .hc-scroll, :scope > .composition-chart .hc-scroll',
+  );
   await expect(chartScrollers).toHaveCount(2);
 
   const viewportWidth = page.viewportSize()?.width ?? 720;
@@ -234,9 +271,10 @@ test('Codex 30-day charts scroll horizontally without widening the dashboard', a
     expect(visibleRightEdge).toBe(true);
   }
 
-  const tableScroller = breakdown.locator('.daily-table-container');
-  await expect(tableScroller.locator('thead th')).toHaveCount(9);
-  await expect(tableScroller.locator('thead th').nth(1)).toHaveText('API-equivalent cost');
+  const tableScroller = breakdown.locator(':scope > .daily-table-container');
+  await expect(tableScroller.locator(':scope > table > thead > tr > th')).toHaveCount(10);
+  await expect(tableScroller.locator(':scope > table > thead > tr > th').nth(1))
+    .toHaveText('API-equivalent cost');
   const tableBefore = await tableScroller.evaluate((element) => ({
     clientWidth: element.clientWidth,
     scrollWidth: element.scrollWidth,
diff --git a/tests/ui/codex-visual.spec.mjs b/tests/ui/codex-visual.spec.mjs
index b774a285..d771399e 100644
--- a/tests/ui/codex-visual.spec.mjs
+++ b/tests/ui/codex-visual.spec.mjs
@@ -21,6 +21,180 @@ const REGISTERED_VSCODE_VARIABLES = new Set([
   '--vscode-textCodeBlock-background', '--vscode-textLink-foreground', '--vscode-toolbar-hoverBackground',
 ]);
 
+const SHARED_VISUAL_TOKENS = [
+  '--ccu-space-1',
+  '--ccu-space-2',
+  '--ccu-space-3',
+  '--ccu-space-4',
+  '--ccu-space-5',
+  '--ccu-space-6',
+  '--ccu-radius-control',
+  '--ccu-radius-panel',
+  '--ccu-border',
+  '--ccu-surface-raised',
+  '--ccu-surface-subtle',
+  '--ccu-data-font',
+  '--ccu-focus',
+];
+
+async function computedContract(locator, properties, rectangleProperties = []) {
+  await expect(locator).toBeVisible();
+  return locator.evaluate((element, contract) => {
+    const style = getComputedStyle(element);
+    const rectangle = element.getBoundingClientRect();
+    return {
+      styles: Object.fromEntries(contract.properties.map((property) => [
+        property,
+        style.getPropertyValue(property).trim(),
+      ])),
+      geometry: Object.fromEntries(contract.rectangleProperties.map((property) => [
+        property,
+        Number(rectangle[property].toFixed(3)),
+      ])),
+    };
+  }, { properties, rectangleProperties });
+}
+
+async function summaryCardContract(page) {
+  const card = page.locator('#today .usage-summary .summary-grid .summary-item').first();
+  return {
+    card: await computedContract(card, [
+      'display',
+      'min-height',
+      'flex-direction',
+      'justify-content',
+      'text-align',
+      'padding-top',
+      'padding-right',
+      'padding-bottom',
+      'padding-left',
+      'background-color',
+      'border-top-width',
+      'border-top-style',
+      'border-top-color',
+      'border-radius',
+    ], ['height']),
+    value: await computedContract(card.locator('.value'), [
+      'font-family',
+      'font-size',
+      'font-weight',
+      'font-variant-numeric',
+    ]),
+  };
+}
+
+async function modelSurfaceContract(page) {
+  const surface = page.locator('#today .model-breakdown details.model-item').first();
+  return {
+    surface: await computedContract(surface, [
+      'padding-top',
+      'padding-right',
+      'padding-bottom',
+      'padding-left',
+      'background-color',
+      'border-top-width',
+      'border-top-style',
+      'border-top-color',
+      'border-radius',
+    ], ['width']),
+    summary: await computedContract(surface.locator(':scope > summary'), [
+      'display',
+      'align-items',
+      'gap',
+      'margin-bottom',
+      'cursor',
+    ]),
+    details: await computedContract(surface.locator(':scope > .model-details-stacked'), [
+      'display',
+      'flex-direction',
+      'gap',
+      'margin-top',
+      'font-size',
+      'color',
+    ]),
+  };
+}
+
+async function monthChartContract(page) {
+  await page.locator('#tab-month').click();
+  const panel = page.locator('#month .daily-breakdown:has(> .chart-tabs)').first();
+  const tabs = panel.locator(':scope > .chart-tabs');
+  return {
+    tabs: await computedContract(tabs, [
+      'display',
+      'gap',
+      'margin-bottom',
+      'flex-wrap',
+    ], ['width', 'height']),
+    control: await computedContract(tabs.locator('.chart-tab').first(), [
+      'padding-top',
+      'padding-right',
+      'padding-bottom',
+      'padding-left',
+      'font-size',
+      'border-top-width',
+      'border-top-style',
+      'border-radius',
+    ], ['height']),
+    content: await computedContract(panel.locator(':scope > .chart-content'), [
+      'display',
+      'align-items',
+      'justify-content',
+      'width',
+      'height',
+    ], ['width', 'height']),
+  };
+}
+
+async function keyboardFocusContract(locator) {
+  await locator.focus();
+  // A keyboard activation puts Chromium into :focus-visible modality without
+  // depending on mouse history from selecting the containing dashboard tab.
+  await locator.press('Space');
+  await expect(locator).toBeFocused();
+  return locator.evaluate((element) => {
+    const style = getComputedStyle(element);
+    return {
+      focusVisible: element.matches(':focus-visible'),
+      outlineWidth: style.outlineWidth,
+      outlineStyle: style.outlineStyle,
+      outlineColor: style.outlineColor,
+      outlineOffset: style.outlineOffset,
+    };
+  });
+}
+
+async function responsiveShellContract(page) {
+  const grid = page.locator('#today .usage-summary .summary-grid').first();
+  const card = grid.locator('.summary-item').first();
+  const nav = page.locator('.tabs');
+  const contract = await page.evaluate((tokens) => {
+    const root = getComputedStyle(document.documentElement);
+    return {
+      tokens: Object.fromEntries(tokens.map((token) => [token, root.getPropertyValue(token).trim()])),
+      bodyPadding: getComputedStyle(document.body).padding,
+    };
+  }, SHARED_VISUAL_TOKENS);
+  return {
+    ...contract,
+    grid: await computedContract(grid, ['grid-template-columns', 'gap']),
+    card: await computedContract(card, ['min-height', 'padding', 'border-radius']),
+    value: await computedContract(card.locator('.value'), ['font-size', 'font-family']),
+    navigation: await nav.evaluate((element) => {
+      const style = getComputedStyle(element);
+      const tabStyle = getComputedStyle(element.querySelector('.tab'));
+      return {
+        display: style.display,
+        overflowX: style.overflowX,
+        overflowY: style.overflowY,
+        clientWidth: element.clientWidth,
+        scrollable: element.scrollWidth > element.clientWidth,
+        tabWhiteSpace: tabStyle.whiteSpace,
+      };
+    }),
+  };
+}
+
 test('Codex uses the shared dashboard shell and tab vocabulary', async ({ page }) => {
   await openCodex(page);
 
@@ -39,6 +213,11 @@ test('Codex uses the shared dashboard shell and tab vocabulary', async ({ page }
   await expect(page.locator('[class*="codex-"]')).toHaveCount(0);
 });
 
+test('Claude middle dashboard scope is labelled as a rolling 30-day range', async ({ page }) => {
+  await openClaude(page);
+  await expect(page.locator('#tab-month')).toHaveText('Last 30 days');
+});
+
 test('Codex header matches Claude with only Refresh and Settings actions', async ({ page }) => {
   await openCodex(page);
 
@@ -77,6 +256,38 @@ test('Codex summary leads with a clearly qualified API-equivalent cost', async (
   await expect(cards.nth(5).locator('.label')).toHaveText('Cache Hit Rate');
 });
 
+test('Codex model headlines use green API-equivalent prices while effort stays token-native', async ({ page }) => {
+  await openCodex(page);
+
+  const modelSection = page.locator('#today .model-breakdown', {
+    has: page.getByRole('heading', { name: 'Models', exact: true }),
+  });
+  const modelSummary = modelSection.locator('summary').first();
+  const modelPrice = modelSummary.locator('.model-cost');
+  await expect(modelPrice).toHaveText(/^\$[\d,.]+$/);
+  await expect(modelPrice).toHaveAttribute(
+    'title',
+    /not a bill or subscription charge.*Priced model coverage: 100%/,
+  );
+  await expect(modelSummary).not.toContainText('Uncached usage');
+  const expectedGreen = await page.evaluate(() => {
+    const probe = document.createElement('span');
+    probe.style.color = 'var(--vscode-charts-green)';
+    document.body.appendChild(probe);
+    const color = getComputedStyle(probe).color;
+    probe.remove();
+    return color;
+  });
+  expect(await modelPrice.evaluate((element) => getComputedStyle(element).color)).toBe(expectedGreen);
+
+  const effortSection = page.locator('#today .model-breakdown', {
+    has: page.getByRole('heading', { name: 'Effort', exact: true }),
+  });
+  const effortSummary = effortSection.locator('summary').first();
+  await expect(effortSummary.locator('.model-cost')).toHaveCount(0);
+  await expect(effortSummary.locator('.model-metric')).toContainText('Uncached usage');
+});
+
 test('Codex shows an unpriced marker without hiding unknown-model token totals', async ({ page }) => {
   await openCodex(page, { fixture: 'unknown-models' });
 
@@ -89,6 +300,14 @@ test('Codex shows an unpriced marker without hiding unknown-model token totals',
   expect(costText).toBe('—');
   expect(costText).not.toContain('$');
   await expect(costCard).toHaveAttribute('title', /Priced model coverage: 0%/);
+  const modelSection = page.locator('#today .model-breakdown', {
+    has: page.getByRole('heading', { name: 'Models', exact: true }),
+  });
+  await expect(modelSection.locator('summary .model-cost').first()).toHaveText('—');
+  await expect(modelSection.locator('summary .model-cost').first()).toHaveAttribute(
+    'title',
+    /Priced model coverage: 0%/,
+  );
   await expect(
     page.locator('#today [data-codex-today-hourly] .chart-content .hc-yaxis .hc-yval'),
   ).toHaveText(['—', '—', '—']);
@@ -119,9 +338,12 @@ test('Codex explains multi-sign-in usage and last-observed limits', async ({ pag
   await expect(limits).toContainText(
     'Usage combines sign-ins in this Codex home · limits are last observed, not combined',
   );
+  await expect(limits).toContainText(/\d+% used · \d+% remaining/);
+  await expect(limits).toContainText(/Last observed:/);
+  await expect(limits).toContainText(/Resets:/);
 });
 
-test('Claude and Codex receive the exact same production stylesheet', async ({ page }) => {
+test('Claude and Codex receive the exact same tokenized production stylesheet', async ({ page }) => {
   await openClaude(page);
   const claudeStyles = await page.locator('head style').first().textContent();
 
@@ -129,6 +351,174 @@ test('Claude and Codex receive the exact same production stylesheet', async ({ p
   const codexStyles = await page.locator('head style').first().textContent();
 
   expect(codexStyles).toBe(claudeStyles);
+  for (const token of SHARED_VISUAL_TOKENS) {
+    expect(codexStyles).toContain(`${token}:`);
+  }
+  expect(codexStyles).toContain('@media (max-width: 480px)');
+  expect(codexStyles).toContain('@media (prefers-reduced-motion: reduce)');
+});
+
+test('Claude and Codex summary cards share geometry and use the VS Code UI font', async ({ page }) => {
+  // Metric labels, values, semantics, and card counts intentionally remain
+  // provider-native; this samples one representative card from each shell.
+  await openClaude(page);
+  const claude = await summaryCardContract(page);
+
+  await openCodex(page);
+  const codex = await summaryCardContract(page);
+
+  expect(codex).toEqual(claude);
+  expect(codex.card.styles).toMatchObject({
+    display: 'flex',
+    'min-height': '68px',
+    'flex-direction': 'column',
+    'justify-content': 'center',
+    'text-align': 'left',
+    'padding-top': '12px',
+    'padding-bottom': '12px',
+    'border-top-width': '1px',
+    'border-top-style': 'solid',
+    'border-radius': '8px',
+  });
+  expect(codex.value.styles['font-variant-numeric']).toContain('tabular-nums');
+  const bodyFont = await page.locator('body').evaluate((element) => getComputedStyle(element).fontFamily);
+  expect(codex.value.styles['font-family']).toBe(bodyFont);
+});
+
+test('Claude and Codex model details share surface and disclosure contracts', async ({ page }) => {
+  // The expanded bodies contain different fields and therefore may have
+  // different heights. Surface width and computed component styles are the
+  // shared contract; row counts and metric equality are deliberately absent.
+  await openClaude(page);
+  const claude = await modelSurfaceContract(page);
+
+  await openCodex(page);
+  const codex = await modelSurfaceContract(page);
+
+  expect(codex).toEqual(claude);
+  expect(codex.surface.styles).toMatchObject({
+    'padding-top': '12px',
+    'padding-right': '12px',
+    'padding-bottom': '12px',
+    'padding-left': '12px',
+    'border-top-width': '1px',
+    'border-top-style': 'solid',
+    'border-radius': '6px',
+  });
+  expect(codex.summary.styles).toMatchObject({
+    display: 'flex',
+    'align-items': 'center',
+    gap: '8px',
+    cursor: 'pointer',
+  });
+  expect(codex.details.styles).toMatchObject({
+    display: 'flex',
+    'flex-direction': 'column',
+    gap: '4px',
+  });
+});
+
+test('Claude and Codex chart controls and content share visual geometry', async ({ page }) => {
+  // Control labels and available metrics are provider-specific. Width is
+  // compared for the shared rows/content, while label-driven button width and
+  // the overall panel height are intentionally outside this contract.
+  await openClaude(page);
+  const claude = await monthChartContract(page);
+
+  await openCodex(page);
+  const codex = await monthChartContract(page);
+
+  expect(codex).toEqual(claude);
+  expect(codex.tabs.styles).toMatchObject({
+    display: 'flex',
+    gap: '4px',
+    'margin-bottom': '16px',
+    'flex-wrap': 'wrap',
+  });
+  expect(codex.control.styles).toMatchObject({
+    'padding-top': '6px',
+    'padding-right': '12px',
+    'padding-bottom': '6px',
+    'padding-left': '12px',
+    'font-size': '11px',
+    'border-top-width': '1px',
+    'border-top-style': 'solid',
+    'border-radius': '4px',
+  });
+  expect(codex.content.styles).toMatchObject({
+    display: 'flex',
+    'align-items': 'end',
+    'justify-content': 'center',
+  });
+});
+
+test('Claude and Codex keyboard controls share the visible focus contract', async ({ page }) => {
+  await openClaude(page);
+  const claudeSummary = await keyboardFocusContract(
+    page.locator('#today .model-breakdown details.model-item > summary').first(),
+  );
+  await page.locator('#tab-month').click();
+  const claudeChart = await keyboardFocusContract(
+    page.locator('#month .daily-breakdown:has(> .chart-tabs) > .chart-tabs .chart-tab').first(),
+  );
+
+  await openCodex(page);
+  await page.locator('#tab-today').click();
+  const codexSummary = await keyboardFocusContract(
+    page.locator('#today .model-breakdown details.model-item > summary').first(),
+  );
+  await page.locator('#tab-month').click();
+  const codexChart = await keyboardFocusContract(
+    page.locator('#month .daily-breakdown:has(> .chart-tabs) > .chart-tabs .chart-tab').first(),
+  );
+
+  expect(codexSummary).toEqual(claudeSummary);
+  expect(codexChart).toEqual(claudeChart);
+  for (const focus of [codexSummary, codexChart]) {
+    expect(focus).toMatchObject({
+      focusVisible: true,
+      outlineWidth: '2px',
+      outlineStyle: 'solid',
+      outlineOffset: '2px',
+    });
+  }
+  expect(codexSummary.outlineColor).toBe(codexChart.outlineColor);
+});
+
+test('Claude and Codex share the 360px responsive component contract', async ({ page }) => {
+  await openClaude(page, { theme: 'dark', width: 360, height: 800 });
+  const claude = await responsiveShellContract(page);
+
+  await openCodex(page, { theme: 'dark', width: 360, height: 800 });
+  const codex = await responsiveShellContract(page);
+
+  expect(codex).toEqual(claude);
+  expect(codex.bodyPadding).toBe('12px');
+  expect(codex.grid.styles).toMatchObject({
+    'grid-template-columns': '164px 164px',
+    gap: '8px',
+  });
+  expect(codex.card.styles).toMatchObject({
+    'min-height': '58px',
+    padding: '10px 12px',
+    'border-radius': '8px',
+  });
+  expect(codex.value.styles['font-size']).toBe('17px');
+  expect(codex.navigation).toMatchObject({
+    display: 'flex',
+    overflowX: 'auto',
+    overflowY: 'hidden',
+    clientWidth: 336,
+    scrollable: true,
+    tabWhiteSpace: 'nowrap',
+  });
+  expect(codex.tokens).toMatchObject({
+    '--ccu-space-2': '8px',
+    '--ccu-space-3': '12px',
+    '--ccu-space-4': '16px',
+    '--ccu-radius-control': '4px',
+    '--ccu-radius-panel': '8px',
+  });
 });
 
 for (const theme of ['light', 'dark']) {
@@ -210,6 +600,10 @@ for (const theme of ['light', 'dark']) {
 test('Codex Today exposes hourly API-equivalent cost and token composition', async ({ page }) => {
   await openCodex(page);
 
+  const overviewComposition = page.locator('#today .cost-composition').first();
+  await expect(overviewComposition.locator('.cost-comp-head strong')).toHaveText(/^Uncached usage [\d,.]+(?:[KMB])?$/);
+  await expect(overviewComposition.locator('.cost-comp-bar .cost-comp-seg')).toHaveCount(3);
+
   const hourly = page.locator('#today .daily-breakdown', {
     has: page.getByRole('heading', { name: 'Hourly Usage', exact: true }),
   });
@@ -226,30 +620,36 @@ test('Codex Today exposes hourly API-equivalent cost and token composition', asy
 
   const table = hourly.locator('.daily-table');
   await expect(table.locator('thead th').first()).toHaveText('Hour');
-  await expect(table.locator('thead th').nth(1)).toHaveText('API-equivalent cost');
-  await expect(table.locator('tbody .cost-cell').first()).toHaveText(/^(?:\$[\d,.]+|—)$/);
+  await expect(table.locator(':scope > thead > tr > th').nth(1)).toHaveText('API-equivalent cost');
+  await expect(table.locator(':scope > tbody > tr .cost-cell').first())
+    .toHaveText(/^(?:\$[\d,.]+|—)$/);
 });
 
 test('Codex month chart defaults to API-equivalent cost and retains token switches', async ({ page }) => {
   await openCodex(page);
   await page.locator('#tab-month').click();
 
-  const chart = page.locator('#month .daily-breakdown');
+  const chart = page.locator('#month [data-codex-last30-daily]');
   await expect(chart).toBeVisible();
-  await expect(chart.locator('.chart-tab')).toHaveCount(6);
-  await expect(chart.locator('.chart-tab.active')).toHaveAttribute('data-metric', 'cost');
-  await expect(chart.locator('.chart-tab.active')).toHaveText('API-equivalent cost');
-  await expect(chart.locator('.chart-bar[data-cost]').first()).toBeVisible();
-  await expect(chart.locator('.hc-yaxis .hc-yval').first()).toHaveText(/^\$/);
-  await expect(chart.locator('.daily-table thead th').nth(1)).toHaveText('API-equivalent cost');
-  await expect(chart.locator('.daily-table tbody .cost-cell').first()).toHaveText(/^(?:\$[\d,.]+|—)$/);
-
-  await chart.locator('.chart-tab[data-metric="outputTokens"]').click();
-  await expect(chart.locator('.chart-tab[data-metric="outputTokens"]')).toHaveClass(/active/);
-  await chart.locator('.chart-tab[data-metric="cost"]').click();
-  await expect(chart.locator('.chart-tab[data-metric="cost"]')).toHaveClass(/active/);
-  await expect(chart.locator('.hc-barval').first()).toHaveText(/^(?:\$[\d,.]+|—)$/);
-  await expect(chart.locator('.chart-bar[data-cost]').first()).toHaveAttribute(
+  const tabs = chart.locator(':scope > .chart-tabs .chart-tab');
+  const mainChart = chart.locator(':scope > .chart-content');
+  const table = chart.locator(':scope > .daily-table-container > .daily-table');
+  await expect(tabs).toHaveCount(6);
+  await expect(chart.locator(':scope > .chart-tabs .chart-tab.active'))
+    .toHaveAttribute('data-metric', 'cost');
+  await expect(chart.locator(':scope > .chart-tabs .chart-tab.active')).toHaveText('API-equivalent cost');
+  await expect(mainChart.locator('.chart-bar[data-cost]').first()).toBeVisible();
+  await expect(mainChart.locator('.hc-yaxis .hc-yval').first()).toHaveText(/^\$/);
+  await expect(table.locator(':scope > thead > tr > th').nth(1)).toHaveText('API-equivalent cost');
+  await expect(table.locator(':scope > tbody > tr.daily-row .cost-cell').first())
+    .toHaveText(/^(?:\$[\d,.]+|—)$/);
+
+  await chart.locator(':scope > .chart-tabs .chart-tab[data-metric="outputTokens"]').click();
+  await expect(chart.locator(':scope > .chart-tabs .chart-tab[data-metric="outputTokens"]')).toHaveClass(/active/);
+  await chart.locator(':scope > .chart-tabs .chart-tab[data-metric="cost"]').click();
+  await expect(chart.locator(':scope > .chart-tabs .chart-tab[data-metric="cost"]')).toHaveClass(/active/);
+  await expect(mainChart.locator('.hc-barval').first()).toHaveText(/^(?:\$[\d,.]+|—)$/);
+  await expect(mainChart.locator('.chart-bar[data-cost]').first()).toHaveAttribute(
     'title',
     /Priced model coverage:/,
   );
@@ -281,15 +681,23 @@ test('weekly allowance value uses the shared all-time chart and exposes uncertai
   await page.locator('#tab-all').click();
 
   const panel = page.locator('#all .daily-breakdown').filter({
-    hasText: 'Weekly allowance value · Codex Beta',
+    hasText: 'Weekly subscription allowance · API-equivalent estimate · Codex Beta',
   });
   await expect(panel).toBeVisible();
-  await expect(panel).toContainText('Estimate, not a bill');
+  await expect(panel).toContainText('not an official balance, bill, or cash value');
   await expect(panel).toContainText('Historical used equivalents come directly from local token logs');
-  await expect(panel).toContainText('When usage cannot be reliably attributed to a single quota observation');
-  await expect(panel).toContainText('no account split or allowance estimate is invented');
-  await expect(panel).toContainText('If an official reset falls within a recorded day');
-  await expect(panel.locator('tbody')).toContainText('Usage only · Boundary approx.');
+  await expect(panel).toContainText('Full and unused estimates appear only for windows with a real quota-utilization observation');
+  await expect(panel).toContainText('current window uses the latest real quota observation for a low-confidence blended durability estimate');
+  await expect(panel).toContainText('ambiguous completed windows remain usage-only');
+  await expect(panel).toContainText('No account split or official balance is invented');
+  await expect(panel).toContainText('A reset inside a recorded day lowers confidence');
+  const details = panel.locator('.weekly-value-details');
+  await expect(details).not.toHaveAttribute('open', '');
+  await expect(details.getByText('Period details', { exact: true })).toBeVisible();
+  await expect(details.locator('.daily-table-container')).toBeHidden();
+  await details.locator('summary').click();
+  await expect(details.locator('.daily-table-container')).toBeVisible();
+  await expect(panel.locator('tbody')).toContainText('Low · Boundary approx.');
   await expect(panel.locator('.hc-col')).toHaveCount(2);
   await expect(panel.locator('tbody tr')).toHaveCount(2);
   await expect(panel.locator('thead')).toContainText('Full allowance est.');
@@ -300,7 +708,10 @@ test('weekly allowance value uses the shared all-time chart and exposes uncertai
   await expect(panel.locator('tbody').getByText('Current period')).toHaveCount(1);
 
   const bars = panel.locator('.hc-col');
-  await expect(bars.last().locator('.seg-cache-read')).toHaveCount(0);
+  await expect(bars.last().locator('.seg-cache-read')).toHaveCount(1);
+  const currentRow = panel.locator('tbody tr').filter({ hasText: 'Current period' });
+  await expect(currentRow.locator('td').nth(4)).not.toHaveText('—');
+  await expect(currentRow.locator('td').nth(5)).toContainText('Low');
 });
 
 test('a completed observed Claude period can still show its unused segment', async ({ page }) => {
@@ -308,9 +719,11 @@ test('a completed observed Claude period can still show its unused segment', asy
   await page.locator('#tab-all').click();
 
   const panel = page.locator('#all .daily-breakdown').filter({
-    hasText: 'Weekly allowance value · Claude',
+    hasText: 'Weekly subscription allowance · API-equivalent estimate · Claude',
   });
   await expect(panel.locator('.hc-col .seg-cache-read')).toHaveCount(1);
+  await expect(panel.locator('.weekly-value-details')).not.toHaveAttribute('open', '');
+  await panel.locator('.weekly-value-details summary').click();
   await expect(panel.locator('tbody tr')).toHaveCount(1);
   await expect(panel.locator('tbody tr td').nth(4)).not.toHaveText('—');
 });
@@ -319,7 +732,7 @@ test('weekly allowance value can be hidden without hiding Codex API-equivalent c
   await openCodex(page, { weeklyValue: false });
   await page.locator('#tab-all').click();
 
-  await expect(page.locator('#all')).not.toContainText('Weekly allowance value · Codex Beta');
+  await expect(page.locator('#all')).not.toContainText('Weekly subscription allowance · API-equivalent estimate · Codex Beta');
   await expect(page.locator('#all .summary-grid .summary-item').first()).toContainText(
     'API-equivalent cost',
   );
@@ -329,19 +742,19 @@ test('weekly allowance value can be hidden from Claude All time', async ({ page
   await openClaude(page, { weeklyValue: false });
   await page.locator('#tab-all').click();
 
-  await expect(page.locator('#all')).not.toContainText('Weekly allowance value · Claude');
+  await expect(page.locator('#all')).not.toContainText('Weekly subscription allowance · API-equivalent estimate · Claude');
   await expect(page.locator('#all .usage-summary').first()).toBeVisible();
 });
 
 test('Compare shows both weekly panels by default and hides only those panels when disabled', async ({ page }) => {
   await openCompare(page);
-  await expect(page.locator('#provider-panel')).toContainText('Weekly allowance value · Claude');
-  await expect(page.locator('#provider-panel')).toContainText('Weekly allowance value · Codex Beta');
+  await expect(page.locator('#provider-panel')).toContainText('Weekly subscription allowance · API-equivalent estimate · Claude');
+  await expect(page.locator('#provider-panel')).toContainText('Weekly subscription allowance · API-equivalent estimate · Codex Beta');
   await expect(page.locator('#provider-panel .usage-summary .summary-item')).toHaveCount(2);
 
   await openCompare(page, { weeklyValue: false });
-  await expect(page.locator('#provider-panel')).not.toContainText('Weekly allowance value · Claude');
-  await expect(page.locator('#provider-panel')).not.toContainText('Weekly allowance value · Codex Beta');
+  await expect(page.locator('#provider-panel')).not.toContainText('Weekly subscription allowance · API-equivalent estimate · Claude');
+  await expect(page.locator('#provider-panel')).not.toContainText('Weekly subscription allowance · API-equivalent estimate · Codex Beta');
   await expect(page.locator('#provider-panel .usage-summary .summary-item')).toHaveCount(2);
   await expect(page.locator('#provider-panel .usage-summary')).toContainText('Claude');
   await expect(page.locator('#provider-panel .usage-summary')).toContainText('Codex Beta');
@@ -351,8 +764,9 @@ test('weekly allowance table fits at 1280px in the longest locale', async ({ pag
   await openCodex(page, { locale: 'de-DE', width: 1280 });
   await page.locator('#tab-all').click();
   const panel = page.locator('#all .daily-breakdown').filter({
-    hasText: 'Wöchentlicher Gegenwert · Codex Beta',
+    hasText: 'Wöchentliches Abo-Kontingent · API-Äquivalenzschätzung · Codex Beta',
   });
+  await panel.locator('.weekly-value-details summary').click();
   const container = panel.locator('.daily-table-container');
   await expect(container).toBeVisible();
   const dimensions = await container.evaluate((element) => ({
@@ -370,7 +784,7 @@ test('weekly chart uses a non-overflowing current-period label in German', async
   await openCodex(page, { locale: 'de-DE', width: 1280 });
   await page.locator('#tab-all').click();
   const panel = page.locator('#all .daily-breakdown').filter({
-    hasText: 'Wöchentlicher Gegenwert · Codex Beta',
+    hasText: 'Wöchentliches Abo-Kontingent · API-Äquivalenzschätzung · Codex Beta',
   });
   const labels = panel.locator('.hc-xlabel');
   const layout = await labels.evaluateAll((elements) => {
@@ -403,9 +817,11 @@ test('weekly used-value history remains visible without historical quota samples
   await page.locator('#tab-all').click();
 
   const panel = page.locator('#all .daily-breakdown').filter({
-    hasText: 'Weekly allowance value · Codex Beta',
+    hasText: 'Weekly subscription allowance · API-equivalent estimate · Codex Beta',
   });
   await expect(panel).toContainText('Monday-to-Monday UTC calendar weeks');
+  await expect(panel.locator('.weekly-value-details')).not.toHaveAttribute('open', '');
+  await panel.locator('.weekly-value-details summary').click();
   await expect(panel.locator('tbody tr')).toHaveCount(2);
   await expect(panel.locator('tbody')).toContainText('Usage only');
   await expect(panel.locator('tbody')).toContainText('$12.00');
diff --git a/tests/ui/combined-heatmap.spec.mjs b/tests/ui/combined-heatmap.spec.mjs
new file mode 100644
index 00000000..b67ea383
--- /dev/null
+++ b/tests/ui/combined-heatmap.spec.mjs
@@ -0,0 +1,216 @@
+import AxeBuilder from '@axe-core/playwright';
+import { test, expect, openCompare } from './support/app.mjs';
+
+test('Compare opens with the combined Claude + Codex heatmap and privacy-bounded share card', async ({ page }) => {
+  await openCompare(page, { fixture: 'combined-heatmap', locale: 'en' });
+
+  const panel = page.locator('.combined-heatmap-panel');
+  await expect(panel).toBeVisible();
+  await expect(panel.getByRole('heading', { name: 'Combined activity heatmap and share card' })).toBeVisible();
+  await expect(page.getByRole('region', { name: 'Live preview' })).toBeVisible();
+  await expect(page.locator('#combinedHeatmapPreview svg')).toHaveAttribute('role', 'img');
+  await expect(page.getByRole('radio', { name: 'Academic Violet' })).toBeChecked();
+  const markdown = page.locator('#combinedHeatmapMarkdown');
+  await expect(markdown).toHaveAttribute('aria-label', 'README / Markdown snippet');
+  await expect(markdown).toHaveValue(
+    /^!\[Claude \+ Codex local activity\]\(claude-codex-activity-year-\d{4}-\d{2}-\d{2}\.svg\)$/,
+  );
+  await page.locator('.combined-output-panel summary').click();
+  await expect(markdown).toBeVisible();
+  const fonts = await markdown.evaluate((element) => ({
+    markdown: getComputedStyle(element).fontFamily,
+    body: getComputedStyle(document.body).fontFamily,
+  }));
+  expect(fonts.markdown).toContain('monospace');
+  expect(fonts.markdown).not.toBe(fonts.body);
+
+  const tooltips = await page.locator('#combinedHeatmapPreview svg rect title').allTextContents();
+  expect(tooltips.some((value) =>
+    value.includes('Claude:') && value.includes('Codex:') && value.includes('Combined:'),
+  )).toBe(true);
+  await expect(page.locator('#combinedHeatmapPrivacyPreview')).toContainText('accounts, projects, thread titles, local paths, and log content');
+  await expect(panel).toContainText('not productivity, subscription billing, or provider capability equivalence');
+  const desktopPreviewGeometry = await page.locator('.combined-heatmap-preview').evaluate((preview) => {
+    const svg = preview.querySelector('svg');
+    const more = [...preview.querySelectorAll('text')].find((element) => element.textContent === 'More');
+    if (!svg || !more) {
+      return null;
+    }
+    const previewRect = preview.getBoundingClientRect();
+    const svgRect = svg.getBoundingClientRect();
+    const moreRect = more.getBoundingClientRect();
+    return {
+      previewWidth: previewRect.width,
+      svgWidth: svgRect.width,
+      previewRight: previewRect.right,
+      svgRight: svgRect.right,
+      moreRight: moreRect.right,
+      overflow: preview.scrollWidth - preview.clientWidth,
+    };
+  });
+  expect(desktopPreviewGeometry).not.toBeNull();
+  expect(desktopPreviewGeometry.overflow).toBeLessThanOrEqual(1);
+  expect(desktopPreviewGeometry.svgWidth).toBeGreaterThanOrEqual(desktopPreviewGeometry.previewWidth * 0.95);
+  expect(desktopPreviewGeometry.svgRight).toBeLessThanOrEqual(desktopPreviewGeometry.previewRight);
+  expect(desktopPreviewGeometry.moreRight).toBeLessThanOrEqual(desktopPreviewGeometry.previewRight);
+  const verticalLayout = await panel.evaluate((element) => {
+    const preview = element.querySelector('.combined-preview-column');
+    const settings = element.querySelector('.combined-config-card');
+    if (!preview || !settings) return null;
+    const previewRect = preview.getBoundingClientRect();
+    const settingsRect = settings.getBoundingClientRect();
+    return {
+      previewBottom: previewRect.bottom,
+      settingsTop: settingsRect.top,
+      settingsWidth: settingsRect.width,
+      panelWidth: element.getBoundingClientRect().width,
+    };
+  });
+  expect(verticalLayout).not.toBeNull();
+  expect(verticalLayout.settingsTop).toBeGreaterThanOrEqual(verticalLayout.previewBottom);
+  expect(verticalLayout.settingsWidth).toBeLessThanOrEqual(verticalLayout.panelWidth);
+});
+
+test('sharing workspace is on by default and can be hidden without removing Compare data', async ({ page }) => {
+  await openCompare(page, { fixture: 'combined-heatmap', locale: 'en' });
+  await expect(page.locator('.combined-heatmap-panel')).toBeVisible();
+
+  await openCompare(page, {
+    fixture: 'combined-heatmap',
+    locale: 'en',
+    shareStudio: false,
+  });
+  await expect(page.locator('.combined-heatmap-panel')).toHaveCount(0);
+  await expect(page.locator('.usage-summary')).toBeVisible();
+  await expect(page.locator('.weekly-value-details')).toHaveCount(2);
+});
+
+test('combined share preferences stay local and every export action is explicit', async ({ page }) => {
+  await openCompare(page, { fixture: 'combined-heatmap', locale: 'en' });
+  expect(await page.evaluate(() => window.__ccuPostedMessages.filter(
+    (message) => message.command !== 'localDataClientReady',
+  ))).toEqual([]);
+
+  await page.locator('#combinedHeatmapTitle').fill('My local activity');
+  await page.locator('#combinedHeatmapRange').selectOption('30d');
+  await page.locator('#combinedHeatmapIntensityMode').selectOption('logarithmic');
+  await page.getByRole('radio', { name: 'Custom' }).check();
+  await page.locator('#combinedHeatmapCustomAccent').fill('#0f766e');
+  await page.locator('#combinedHeatmapPrivacy').uncheck();
+  await expect(page.locator('#combinedHeatmapPrivacyPreview')).toBeHidden();
+
+  await page.reload({ waitUntil: 'load' });
+  await expect(page.locator('#combinedHeatmapTitle')).toHaveValue('My local activity');
+  await expect(page.locator('#combinedHeatmapRange')).toHaveValue('30d');
+  await expect(page.locator('#combinedHeatmapIntensityMode')).toHaveValue('logarithmic');
+  await expect(page.getByRole('radio', { name: 'Custom' })).toBeChecked();
+  await expect(page.locator('#combinedHeatmapCustomAccent')).toHaveValue('#0f766e');
+  await expect(page.locator('#combinedHeatmapPrivacy')).not.toBeChecked();
+  await page.evaluate(() => { window.__ccuPostedMessages = []; });
+
+  await page.getByRole('button', { name: 'Update preview' }).click();
+  await page.getByRole('button', { name: 'Export SVG…' }).click();
+  await page.getByRole('button', { name: 'Copy Markdown' }).click();
+
+  const state = await page.evaluate(() => ({
+    title: localStorage.getItem('ccu.combinedHeatmap.title'),
+    range: localStorage.getItem('ccu.combinedHeatmap.range'),
+    privacy: localStorage.getItem('ccu.combinedHeatmap.privacyPreview'),
+    intensityMode: localStorage.getItem('ccu.combinedHeatmap.intensityMode'),
+    palette: localStorage.getItem('ccu.combinedHeatmap.palette'),
+    customAccent: localStorage.getItem('ccu.combinedHeatmap.customAccent'),
+    messages: window.__ccuPostedMessages.filter(
+      (message) => message.command !== 'localDataClientReady',
+    ),
+  }));
+  expect(state).toMatchObject({
+    title: 'My local activity', range: '30d', privacy: 'false',
+    intensityMode: 'logarithmic', palette: 'custom', customAccent: '#0f766e',
+  });
+  expect(state.messages).toEqual([
+    { command: 'previewCombinedHeatmap', title: 'My local activity', range: '30d', intensityMode: 'logarithmic', palette: 'custom', customAccent: '#0f766e' },
+    { command: 'exportCombinedHeatmap', title: 'My local activity', range: '30d', intensityMode: 'logarithmic', palette: 'custom', customAccent: '#0f766e' },
+    { command: 'copyCombinedHeatmapMarkdown', title: 'My local activity', range: '30d', intensityMode: 'logarithmic', palette: 'custom', customAccent: '#0f766e' },
+  ]);
+  expect(state.messages.some((message) => /publish/i.test(message.command))).toBe(false);
+
+  await page.getByRole('button', { name: 'Reset sharing preferences' }).click();
+  await expect(page.locator('#combinedHeatmapTitle')).toHaveValue('Claude + Codex local activity');
+  await expect(page.locator('#combinedHeatmapRange')).toHaveValue('year');
+  await expect(page.locator('#combinedHeatmapIntensityMode')).toHaveValue('quantile');
+  await expect(page.getByRole('radio', { name: 'Academic Violet' })).toBeChecked();
+  await expect(page.locator('#combinedHeatmapPrivacy')).toBeChecked();
+  const reset = await page.evaluate(() => ({
+    title: localStorage.getItem('ccu.combinedHeatmap.title'),
+    range: localStorage.getItem('ccu.combinedHeatmap.range'),
+    privacy: localStorage.getItem('ccu.combinedHeatmap.privacyPreview'),
+    intensityMode: localStorage.getItem('ccu.combinedHeatmap.intensityMode'),
+    palette: localStorage.getItem('ccu.combinedHeatmap.palette'),
+    customAccent: localStorage.getItem('ccu.combinedHeatmap.customAccent'),
+    messages: window.__ccuPostedMessages.slice(-2),
+  }));
+  expect(reset).toEqual({
+    title: null,
+    range: null,
+    privacy: null,
+    intensityMode: null,
+    palette: null,
+    customAccent: null,
+    messages: [
+      { command: 'previewCombinedHeatmap', title: 'Claude + Codex local activity', range: 'year', intensityMode: 'quantile', palette: 'academicViolet', customAccent: '#4f2f87' },
+      { command: 'resetCombinedHeatmapPreferences' },
+    ],
+  });
+});
+
+for (const theme of ['light', 'dark']) {
+  test(`combined heatmap controls and preview are accessible in ${theme} theme`, async ({ page }) => {
+    await openCompare(page, { fixture: 'combined-heatmap', locale: 'zh-CN', theme });
+    await expect(page.getByLabel('分享标题')).toBeVisible();
+    await expect(page.getByLabel('时间范围')).toBeVisible();
+    await expect(page.getByLabel('色阶映射')).toHaveValue('quantile');
+    await expect(page.getByRole('group', { name: '热力图配色' })).toBeVisible();
+    await expect(page.getByLabel('显示隐私预览')).toBeChecked();
+    await page.locator('.combined-output-panel').evaluate((element) => { element.open = true; });
+    await expect(page.getByLabel('README / Markdown 引用片段')).toBeVisible();
+    const results = await new AxeBuilder({ page })
+      .include('.combined-heatmap-panel')
+      // Chromium/axe cannot resolve overlapping SVG primitives reliably.
+      // Export-card text/background pairs have deterministic contrast tests
+      // in combinedHeatmap.test.ts; Axe owns the surrounding HTML controls.
+      .exclude('#combinedHeatmapPreview svg')
+      .analyze();
+    expect(results.violations).toEqual([]);
+    expect(results.incomplete.filter((item) => item.id === 'color-contrast')).toEqual([]);
+  });
+}
+
+test('Share studio copy is localized in every supported locale', async ({ page }) => {
+  const expected = {
+    en: ['Intensity scale', 'Combined activity heatmap and share card'],
+    'de-DE': ['Intensitätsskala', 'Kombinierte Aktivitäts-Heatmap und Freigabekarte'],
+    'zh-TW': ['色階映射', '綜合活動熱力圖與分享卡'],
+    'zh-CN': ['色阶映射', '综合活动热力图与分享卡'],
+    ja: ['強度スケール', '統合アクティビティヒートマップと共有カード'],
+    ko: ['강도 스케일', '통합 활동 히트맵과 공유 카드'],
+    'pt-BR': ['Escala de intensidade', 'Mapa de calor de atividade combinado e cartão de compartilhamento'],
+    id: ['Skala intensitas', 'Heatmap aktivitas gabungan dan kartu berbagi'],
+  };
+  for (const [locale, [intensityLabel, heading]] of Object.entries(expected)) {
+    await openCompare(page, { fixture: 'combined-heatmap', locale });
+    await expect(page.getByLabel(intensityLabel)).toHaveValue('quantile');
+    await expect(page.getByRole('heading', { name: heading })).toBeVisible();
+  }
+});
+
+test('combined heatmap remains usable at a 360px webview width', async ({ page }) => {
+  await openCompare(page, { fixture: 'combined-heatmap', locale: 'zh-CN', width: 360, height: 900 });
+  await expect(page.locator('.combined-heatmap-controls')).toHaveCSS('grid-template-columns', /\d+(?:\.\d+)?px/);
+  const pageOverflow = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth);
+  expect(pageOverflow).toBeLessThanOrEqual(1);
+  const previewOverflow = await page.locator('.combined-heatmap-preview').evaluate((node) => ({
+    scrollWidth: node.scrollWidth,
+    clientWidth: node.clientWidth,
+  }));
+  expect(previewOverflow.scrollWidth).toBeGreaterThan(previewOverflow.clientWidth);
+});
diff --git a/tests/ui/local-data-controls.spec.mjs b/tests/ui/local-data-controls.spec.mjs
new file mode 100644
index 00000000..881a4328
--- /dev/null
+++ b/tests/ui/local-data-controls.spec.mjs
@@ -0,0 +1,137 @@
+import { test, expect, openCodex } from './support/app.mjs';
+
+test('Settings stays concise: repository privacy controls are not rendered in the plugin', async ({ page }) => {
+  await openCodex(page);
+  await page.locator('#tab-settings').click();
+
+  await expect(page.locator('#localDataTitle')).toHaveCount(0);
+  await expect(page.locator('.local-data-controls')).toHaveCount(0);
+  await expect(page.locator('#localDataQuotaScope')).toHaveCount(0);
+  await expect(page.getByText('Enable sharing workspace', { exact: true })).toBeVisible();
+  await expect(page.locator('#set_enableShareCard')).toBeChecked();
+  expect(await page.evaluate(() => window.__ccuPostedMessages.some(
+    (message) => message.command === 'requestLocalDataInventory',
+  ))).toBe(false);
+});
+
+test('an inventory reply cannot materialize the removed settings UI', async ({ page }) => {
+  await openCodex(page);
+  await page.locator('#tab-settings').click();
+  await page.evaluate(() => {
+    window.dispatchEvent(new MessageEvent('message', {
+      data: {
+        command: 'localDataInventoryResult',
+        ok: true,
+        inventory: {
+          schemaVersion: 1,
+          generatedAt: Date.now(),
+          rows: [{
+            id: 'P2',
+            category: '<img src=x onerror="window.__inventoryInjected=true">P2 quota observations',
+            locationClass: 'Extension global storage / quota observations',
+            schema: 'schema 2',
+            approximateBytes: 512,
+            itemCount: 3,
+            oldestAt: Date.parse('2026-07-01T00:00:00Z'),
+            newestAt: Date.parse('2026-07-03T00:00:00Z'),
+            networkInteraction: 'Structured observations only',
+            clearability: 'Scoped clear',
+          }],
+          quotaScopes: [{
+            token: '0123456789abcdef0123456789abcdef0123',
+            label: 'Codex local anonymous account epoch 1 (3)',
+            provider: 'codex',
+            itemCount: 3,
+            oldestAt: null,
+            newestAt: null,
+          }],
+          exclusions: ['provider-owned source logs', 'provider credentials'],
+        },
+      },
+    }));
+  });
+
+  await expect(page.locator('#localDataInventoryBody')).toHaveCount(0);
+  expect(await page.evaluate(() => window.__inventoryInjected === true)).toBe(false);
+});
+
+test('UI and sharing resets are independent and preserve unrelated localStorage', async ({ page }) => {
+  await openCodex(page);
+  await page.locator('#tab-settings').click();
+  await page.evaluate(() => {
+    localStorage.setItem('ccu.activeTab', 'settings');
+    localStorage.setItem('ccu.sessionRange', '30');
+    localStorage.setItem('ccu.combinedHeatmap.title', 'Synthetic title');
+    localStorage.setItem('ccu.combinedHeatmap.range', '90d');
+    localStorage.setItem('unrelated-private-canary', 'preserve');
+    acquireVsCodeApi().setState({ scrollPositions: { settings: 10 } });
+    window.dispatchEvent(new MessageEvent('message', {
+      data: {
+        command: 'localDataClientAction',
+        action: 'reset-ui-state',
+        requestId: 'opaque-reset-request-1',
+      },
+    }));
+  });
+  expect(await page.evaluate(() => window.__ccuPostedMessages.findLast(
+    (message) => message.command === 'localDataClientActionAck',
+  ))).toEqual({
+    command: 'localDataClientActionAck',
+    requestId: 'opaque-reset-request-1',
+    ok: true,
+  });
+  expect(await page.evaluate(() => ({
+    active: localStorage.getItem('ccu.activeTab'),
+    range: localStorage.getItem('ccu.sessionRange'),
+    shareTitle: localStorage.getItem('ccu.combinedHeatmap.title'),
+    state: JSON.parse(localStorage.getItem('__ccu-vscode-state') || '{}'),
+    unrelated: localStorage.getItem('unrelated-private-canary'),
+  }))).toEqual({
+    active: null,
+    range: null,
+    shareTitle: 'Synthetic title',
+    state: {},
+    unrelated: 'preserve',
+  });
+
+  await page.evaluate(() => {
+    window.dispatchEvent(new MessageEvent('message', {
+      data: { command: 'localDataClientAction', action: 'reset-sharing-preferences' },
+    }));
+  });
+  expect(await page.evaluate(() => ({
+    title: localStorage.getItem('ccu.combinedHeatmap.title'),
+    range: localStorage.getItem('ccu.combinedHeatmap.range'),
+    unrelated: localStorage.getItem('unrelated-private-canary'),
+  }))).toEqual({ title: null, range: null, unrelated: 'preserve' });
+});
+
+test('client reset ACK is false when allowlisted browser storage cannot be deleted', async ({ page }) => {
+  await openCodex(page);
+  await page.locator('#tab-settings').click();
+  await page.evaluate(() => {
+    localStorage.setItem('ccu.activeTab', 'settings');
+    const original = Storage.prototype.removeItem;
+    Storage.prototype.removeItem = function failingRemoveItem() {
+      throw new Error('synthetic-storage-failure');
+    };
+    window.dispatchEvent(new MessageEvent('message', {
+      data: {
+        command: 'localDataClientAction',
+        action: 'reset-ui-state',
+        requestId: 'opaque-reset-failure-1',
+      },
+    }));
+    Storage.prototype.removeItem = original;
+  });
+
+  expect(await page.evaluate(() => window.__ccuPostedMessages.findLast(
+    (message) => message.command === 'localDataClientActionAck',
+  ))).toEqual({
+    command: 'localDataClientActionAck',
+    requestId: 'opaque-reset-failure-1',
+    ok: false,
+  });
+  await expect.poll(() => page.evaluate(() => localStorage.getItem('ccu.activeTab')))
+    .toBe('settings');
+});
diff --git a/tests/ui/support/advice-effectiveness-fixture.cjs b/tests/ui/support/advice-effectiveness-fixture.cjs
new file mode 100644
index 00000000..a7fbde27
--- /dev/null
+++ b/tests/ui/support/advice-effectiveness-fixture.cjs
@@ -0,0 +1,183 @@
+'use strict';
+
+const {
+  adaptClaudeAdvice,
+  adaptCodexLocalAdvice,
+} = require('../../../out/adviceEffectiveness/adapters.js');
+const {
+  prepareAdviceSnapshot,
+} = require('../../../out/adviceEffectiveness/integration.js');
+const {
+  buildAdviceAggregateSnapshot,
+} = require('../../../out/adviceEffectiveness/payload.js');
+
+const PROMPT_SENTINEL = 'SAFE_PROMPT_SENTINEL_測試_🚦';
+const USER_CONTEXT_SENTINEL = 'SAFE_USER_CONTEXT_SENTINEL_私人_🔒';
+const GENERATED_AT = '2026-07-20T12:00:00.000Z';
+
+function numericUsage() {
+  return {
+    totalInputTokens: 47_600,
+    totalOutputTokens: 8_300,
+    totalCacheCreationTokens: 17_900,
+    totalCacheReadTokens: 288_000,
+    totalCost: 3.05,
+    costBreakdown: {
+      input: 0.44,
+      output: 1.52,
+      cacheWrite: 0.82,
+      cacheRead: 0.27,
+    },
+    messageCount: 25,
+    modelBreakdown: {
+      'claude-sonnet-4-5-20250929': {
+        inputTokens: 38_200,
+        outputTokens: 6_100,
+        cacheCreationTokens: 14_800,
+        cacheReadTokens: 236_000,
+        cost: 2.74,
+        count: 18,
+      },
+      'claude-haiku-4-5-20251001': {
+        inputTokens: 9_400,
+        outputTokens: 2_200,
+        cacheCreationTokens: 3_100,
+        cacheReadTokens: 52_000,
+        cost: 0.31,
+        count: 7,
+      },
+    },
+  };
+}
+
+function requireAdapter(result, provider) {
+  if (!result.ok) {
+    throw new Error(`${provider} advice fixture failed: ${result.issues.join(', ')}`);
+  }
+  return result.value;
+}
+
+function requireSnapshot(result, mode) {
+  if (!result.ok) {
+    throw new Error(`${mode} advice snapshot failed: ${result.reason}`);
+  }
+  return result.value;
+}
+
+function snapshotMessage(snapshot, suffix) {
+  return {
+    command: 'adviceSnapshotResult',
+    ok: true,
+    snapshotId: `snapshot-${snapshot.preview.sha256.slice(suffix, suffix + 24)}`,
+    provider: snapshot.provider,
+    contentType: snapshot.preview.contentType,
+    dataMode: snapshot.preview.dataMode,
+    promptSampleCount: snapshot.preview.promptSampleCount,
+    utf8Bytes: snapshot.preview.utf8Bytes,
+    sha256: snapshot.preview.sha256,
+    body: snapshot.preview.body,
+  };
+}
+
+/**
+ * Test-only vertical fixture built through the production adapters and sealed
+ * snapshot helper. Inputs are numeric aggregates except for the single prompt
+ * sentinel, which remains host-side until the explicit prompt-opt-in test.
+ */
+function buildAdviceEffectivenessFixture({ locale = 'en' } = {}) {
+  const aggregate = buildAdviceAggregateSnapshot(numericUsage(), 'overall', 30);
+  const claude = requireAdapter(adaptClaudeAdvice({
+    adviceId: 'advice-claude-ui-fixture',
+    generatedAt: GENERATED_AT,
+    locale,
+    aggregate,
+    sessionSummary: {
+      scope: 'overall',
+      windowDays: 30,
+      totalSessions: 8,
+      longSessionCount: 3,
+      largeContextSessionCount: 2,
+    },
+    frameworkOverhead: {
+      frameworkEstimatedTokens: 4_760,
+      observedInputEstimatedTokens: 47_600,
+      classifiedEvents: 25,
+    },
+  }), 'Claude');
+
+  const codex = requireAdapter(adaptCodexLocalAdvice({
+    adviceId: 'advice-codex-ui-fixture',
+    generatedAt: GENERATED_AT,
+    locale,
+    scope: '30d',
+    insights: [
+      {
+        kind: 'effort-comparison',
+        severity: 'normal',
+        scope: '30d',
+        evidence: { highEffortFresh: 700, lowMediumEffortFresh: 300 },
+        proxy: true,
+      },
+      {
+        kind: 'cache-context',
+        severity: 'info',
+        scope: '30d',
+        evidence: { processedToFreshRatio: 3, cachedInputShare: 0.7 },
+        proxy: true,
+      },
+    ],
+    behavior: {
+      childFreshShare: 0.2,
+      approvalReviewerFreshShare: 0.1,
+      highEffortFreshShare: 0.7,
+      processedToFreshRatio: 3,
+      cacheShare: 0.7,
+      postPatchToolCallsPerPatchCall: 4,
+    },
+    quality: {
+      indexComplete: true,
+      identityComplete: true,
+      periodComplete: true,
+      qualityFlags: [],
+    },
+  }), 'Codex');
+
+  const claudeState = {
+    provider: 'claude',
+    contract: claude.contract,
+    remotePreviewEligible: claude.remoteEvidenceEligible,
+    aggregate: claude.aggregate,
+    userContext: USER_CONTEXT_SENTINEL,
+    promptSamples: [{ text: PROMPT_SENTINEL }],
+  };
+  const codexState = {
+    provider: 'codex',
+    contract: codex.contract,
+    remotePreviewEligible: codex.remoteEvidenceEligible,
+    promptSamples: [],
+  };
+  const aggregateOnly = requireSnapshot(prepareAdviceSnapshot(claudeState, {
+    aggregate: 'explicit',
+    promptSamples: 'not-granted',
+  }), 'aggregates-only');
+  const withPromptSamples = requireSnapshot(prepareAdviceSnapshot(claudeState, {
+    aggregate: 'explicit',
+    promptSamples: 'explicit',
+  }), 'aggregates-with-prompt-samples');
+
+  return {
+    promptSentinel: PROMPT_SENTINEL,
+    userContextSentinel: USER_CONTEXT_SENTINEL,
+    states: { claude: claudeState, codex: codexState },
+    snapshotMessages: {
+      aggregateOnly: snapshotMessage(aggregateOnly, 0),
+      withPromptSamples: snapshotMessage(withPromptSamples, 8),
+    },
+  };
+}
+
+module.exports = {
+  PROMPT_SENTINEL,
+  USER_CONTEXT_SENTINEL,
+  buildAdviceEffectivenessFixture,
+};
diff --git a/tests/ui/support/app.mjs b/tests/ui/support/app.mjs
index 1c562789..6d935c53 100644
--- a/tests/ui/support/app.mjs
+++ b/tests/ui/support/app.mjs
@@ -6,12 +6,14 @@ export const test = base.extend({
   page: async ({ page }, use) => {
     await page.addInitScript(() => {
       window.__ccuPostedMessages = [];
+      window.__ccuSetStateCalls = 0;
       window.acquireVsCodeApi = () => ({
         getState: () => {
           const raw = localStorage.getItem('__ccu-vscode-state');
           return raw ? JSON.parse(raw) : undefined;
         },
         setState: (value) => {
+          window.__ccuSetStateCalls += 1;
           localStorage.setItem('__ccu-vscode-state', JSON.stringify(value));
         },
         postMessage: (value) => {
@@ -29,11 +31,11 @@ export { expect };
 
 export async function openCodex(
   page,
-  { locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true, width = 1280, height = 900 } = {},
+  { locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true, shareStudio = true, width = 1280, height = 900 } = {},
 ) {
   await page.setViewportSize({ width, height });
   await page.goto(
-    `${uiBaseUrl}/?provider=codex&locale=${encodeURIComponent(locale)}&theme=${theme}&fixture=${encodeURIComponent(fixture)}&autoRefresh=${autoRefresh}&weeklyValue=${weeklyValue}`,
+    `${uiBaseUrl}/?provider=codex&locale=${encodeURIComponent(locale)}&theme=${theme}&fixture=${encodeURIComponent(fixture)}&autoRefresh=${autoRefresh}&weeklyValue=${weeklyValue}&shareStudio=${shareStudio}`,
     { waitUntil: 'load' },
   );
   await page.locator('.tab-content.active').waitFor();
@@ -42,11 +44,11 @@ export async function openCodex(
 
 export async function openClaude(
   page,
-  { locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true, width = 1280, height = 900 } = {},
+  { locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true, shareStudio = true, timeZone = 'Asia/Hong_Kong', width = 1280, height = 900 } = {},
 ) {
   await page.setViewportSize({ width, height });
   await page.goto(
-    `${uiBaseUrl}/?provider=claude&locale=${encodeURIComponent(locale)}&theme=${theme}&fixture=${encodeURIComponent(fixture)}&autoRefresh=${autoRefresh}&weeklyValue=${weeklyValue}`,
+    `${uiBaseUrl}/?provider=claude&locale=${encodeURIComponent(locale)}&theme=${theme}&fixture=${encodeURIComponent(fixture)}&autoRefresh=${autoRefresh}&weeklyValue=${weeklyValue}&shareStudio=${shareStudio}&timeZone=${encodeURIComponent(timeZone)}`,
     { waitUntil: 'load' },
   );
   await page.locator('.tab-content.active').waitFor();
@@ -54,11 +56,11 @@ export async function openClaude(
 
 export async function openCompare(
   page,
-  { locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true, width = 1280, height = 900 } = {},
+  { locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true, shareStudio = true, width = 1280, height = 900 } = {},
 ) {
   await page.setViewportSize({ width, height });
   await page.goto(
-    `${uiBaseUrl}/?provider=compare&locale=${encodeURIComponent(locale)}&theme=${theme}&fixture=${encodeURIComponent(fixture)}&autoRefresh=${autoRefresh}&weeklyValue=${weeklyValue}`,
+    `${uiBaseUrl}/?provider=compare&locale=${encodeURIComponent(locale)}&theme=${theme}&fixture=${encodeURIComponent(fixture)}&autoRefresh=${autoRefresh}&weeklyValue=${weeklyValue}&shareStudio=${shareStudio}`,
     { waitUntil: 'load' },
   );
   await page.locator('#provider-panel').waitFor();
diff --git a/tests/ui/support/capture-readme.mjs b/tests/ui/support/capture-readme.mjs
new file mode 100644
index 00000000..f78d2d5c
--- /dev/null
+++ b/tests/ui/support/capture-readme.mjs
@@ -0,0 +1,90 @@
+// Documentation images use the production renderer, fixed synthetic aggregates,
+// and the registered VS Code Light+/Dark+ variables from the shared UI harness.
+// Run after compile and the visual-token guard: node tests/ui/support/capture-readme.mjs
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { chromium, expect } from '@playwright/test';
+
+const require = createRequire(import.meta.url);
+const { renderHarness } = require('./render-harness.cjs');
+const fixtureNow = Date.parse('2026-07-20T12:00:00.000Z');
+const output = resolve('images/v2.3.1');
+const views = {
+  claude: { provider: 'claude', locale: 'zh-CN', theme: 'dark', fixture: 'default' },
+  codex: { provider: 'codex', locale: 'zh-CN', theme: 'dark', fixture: 'default' },
+  weekly: { provider: 'codex', locale: 'en', theme: 'dark', fixture: 'default' },
+  compare: { provider: 'compare', locale: 'en', theme: 'light', fixture: 'combined-heatmap' },
+};
+const server = createServer(async (request, response) => {
+  const options = views[request.url?.slice(1)];
+  if (!options) { response.writeHead(404); response.end(); return; }
+  const NativeDate = Date;
+  try {
+    // The shared harness freezes Date.now; documentation must also freeze the
+    // no-argument constructor used for the calendar end date.
+    globalThis.Date = class extends NativeDate {
+      constructor(...args) { super(...(args.length ? args : [fixtureNow])); }
+      static now() { return fixtureNow; }
+    };
+    const html = await renderHarness({ ...options, autoRefresh: false, weeklyValue: true, shareStudio: true });
+    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+    response.end(html);
+  } catch {
+    response.writeHead(500); response.end('Fixture rendering failed');
+  } finally {
+    globalThis.Date = NativeDate;
+  }
+});
+await new Promise((done) => server.listen(0, '127.0.0.1', done));
+const baseUrl = `http://127.0.0.1:${server.address().port}`;
+const browser = await chromium.launch();
+try {
+  await mkdir(output, { recursive: true });
+  for (const [view, options] of Object.entries(views)) {
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 940 }, deviceScaleFactor: 1,
+      locale: options.locale, timezoneId: 'Asia/Hong_Kong', reducedMotion: 'reduce',
+      colorScheme: options.theme,
+    });
+    const page = await context.newPage();
+    await page.addInitScript(() => {
+      window.acquireVsCodeApi = () => ({
+        getState: () => JSON.parse(localStorage.getItem('readme-state') ?? 'null'),
+        setState: (value) => localStorage.setItem('readme-state', JSON.stringify(value)),
+        postMessage: () => Promise.resolve(true),
+      });
+    });
+    await page.clock.install({ time: new Date('2026-07-20T12:00:00.000Z') });
+    await page.goto(`${baseUrl}/${view}`);
+    await page.locator('.provider-tabs').waitFor();
+    const screenshot = { animations: 'disabled', caret: 'hide' };
+    if (view === 'claude') {
+      await expect(page.locator('#today .summary-grid')).not.toContainText('$0.00');
+      await page.screenshot({ ...screenshot, path: resolve(output, 'claude-today-zh-CN-dark.png') });
+    } else if (view === 'codex') {
+      await page.locator('#tab-month').click();
+      await expect(page.locator('#month')).toContainText('未缓存用量');
+      await page.screenshot({ ...screenshot, path: resolve(output, 'codex-overview-zh-CN-dark.png') });
+    } else if (view === 'weekly') {
+      await page.locator('#tab-all').click();
+      const panel = page.locator('#all .daily-breakdown').filter({
+        hasText: 'Weekly subscription allowance · API-equivalent estimate · Codex Beta',
+      });
+      await expect(panel.locator('.weekly-value-details')).not.toHaveAttribute('open', '');
+      await expect(panel.locator('.seg-cache-read')).not.toHaveCount(0);
+      await panel.screenshot({ ...screenshot, path: resolve(output, 'codex-weekly-estimate-en-dark.png') });
+    } else {
+      const panel = page.locator('.combined-heatmap-panel');
+      await expect(panel.locator('#combinedHeatmapIntensityMode')).toHaveValue('quantile');
+      await expect(panel.locator('.combined-config-card')).toBeVisible();
+      await panel.screenshot({ ...screenshot, path: resolve(output, 'compare-heatmap-en-light.png') });
+    }
+    console.log(`Captured ${view}: production renderer, synthetic fixture, ${options.theme}`);
+    await context.close();
+  }
+} finally {
+  await browser.close();
+  await new Promise((done) => server.close(done));
+}
diff --git a/tests/ui/support/render-harness.cjs b/tests/ui/support/render-harness.cjs
index d8e83a2f..f2d7e582 100644
--- a/tests/ui/support/render-harness.cjs
+++ b/tests/ui/support/render-harness.cjs
@@ -41,6 +41,9 @@ const {
   rootedTaskBeyondRecentRowCapFixture,
   rootlessCrossProjectCycleFixture,
 } = require('../../../out/test/codexFixtures.js');
+const {
+  buildAdviceEffectivenessFixture,
+} = require('./advice-effectiveness-fixture.cjs');
 
 Module._load = originalLoad;
 
@@ -53,7 +56,6 @@ const THEMES = {
     '--vscode-font-size:13px;' +
     '--vscode-editor-font-family:Menlo,Monaco,"Courier New",monospace;' +
     '--vscode-editor-background:#ffffff;' +
-    '--vscode-editor-foreground:#000000;' +
     '--vscode-foreground:#616161;' +
     '--vscode-descriptionForeground:#717171;' +
     '--vscode-errorForeground:#A1260D;' +
@@ -99,7 +101,6 @@ const THEMES = {
     '--vscode-font-size:13px;' +
     '--vscode-editor-font-family:Menlo,Monaco,"Courier New",monospace;' +
     '--vscode-editor-background:#1e1e1e;' +
-    '--vscode-editor-foreground:#D4D4D4;' +
     '--vscode-foreground:#CCCCCC;' +
     '--vscode-descriptionForeground:rgba(204,204,204,0.7);' +
     '--vscode-errorForeground:#F48771;' +
@@ -142,21 +143,40 @@ const THEMES = {
     '}*,*::before,*::after{animation:none!important;transition:none!important}',
 };
 
-function settingsStore(autoRefresh = false, weeklyValue = true) {
+function settingsStore({
+  autoRefresh = false,
+  weeklyValue = true,
+  shareStudio = true,
+  adviceEffectiveness = false,
+  adviceOptimizer = false,
+} = {}) {
   const values = new Map(SETTINGS.map((definition) => [definition.key, definition.default]));
   values.set('codex.optimization.enabled', true);
   values.set('dashboardAutoRefresh', autoRefresh);
   values.set('showWeeklyEquivalentValue', weeklyValue);
+  values.set('enableShareCard', shareStudio);
+  values.set('advice.effectiveness.enabled', adviceEffectiveness);
+  values.set('advice.optimizer.enabled', adviceOptimizer);
   return {
     get: (key) => values.get(key),
     snapshot: () => SETTINGS.map((definition) => ({
       ...definition,
       value: values.get(definition.key),
-      isDefault: true,
+      isDefault: values.get(definition.key) === definition.default,
     })),
   };
 }
 
+function memoryGlobalState() {
+  const values = new Map();
+  return {
+    get: (key) => values.get(key),
+    update: async (key, value) => {
+      values.set(key, structuredClone(value));
+    },
+  };
+}
+
 function claudeUsage(multiplier = 1) {
   const modelBreakdown = {
     'claude-sonnet-4-5-20250929': {
@@ -193,11 +213,41 @@ function claudeUsage(multiplier = 1) {
   };
 }
 
-function addClaudeData(provider, fixture = 'default') {
+function addClaudeData(provider, { fixture = 'default', enableContent = false } = {}) {
   const today = claudeUsage();
   const now = new Date(CODEX_WEBVIEW_NOW);
   const completedWeeklyFixture = fixture === 'weekly-claude-completed';
   const completedResetAt = CODEX_WEBVIEW_NOW - 24 * 60 * 60_000;
+  const combinedHeatmapRecords = fixture === 'combined-heatmap'
+    ? [
+        {
+          timestamp: '2026-07-19T10:00:00.000Z',
+          _sessionId: 'privacy-safe-share-fixture-a',
+          message: {
+            model: 'claude-sonnet-4-5-20250929',
+            usage: {
+              input_tokens: 120_000,
+              output_tokens: 30_000,
+              cache_creation_input_tokens: 40_000,
+              cache_read_input_tokens: 310_000,
+            },
+          },
+        },
+        {
+          timestamp: '2026-07-20T08:00:00.000Z',
+          _sessionId: 'privacy-safe-share-fixture-b',
+          message: {
+            model: 'claude-sonnet-4-5-20250929',
+            usage: {
+              input_tokens: 180_000,
+              output_tokens: 45_000,
+              cache_creation_input_tokens: 55_000,
+              cache_read_input_tokens: 420_000,
+            },
+          },
+        },
+      ]
+    : [];
   const weeklyRecords = completedWeeklyFixture
     ? [{
         timestamp: new Date(completedResetAt - 2 * 60 * 60_000).toISOString(),
@@ -211,6 +261,25 @@ function addClaudeData(provider, fixture = 'default') {
           },
         },
       }]
+    : combinedHeatmapRecords;
+  const sessionBreakdown = fixture === 'session-timezone-boundaries'
+    ? [
+        ['honolulu-today', 'Honolulu today', '2026-07-20T10:00:00.000Z'],
+        ['honolulu-yesterday', 'Honolulu yesterday', '2026-07-19T10:00:00.000Z'],
+        ['week-inside', 'Seven-day boundary inside', '2026-07-14T10:00:00.000Z'],
+        ['week-outside', 'Seven-day boundary outside', '2026-07-14T08:00:00.000Z'],
+        ['month-inside', 'Thirty-day boundary inside', '2026-06-21T10:00:00.000Z'],
+        ['month-outside', 'Thirty-day boundary outside', '2026-06-21T08:00:00.000Z'],
+      ].map(([sessionId, title, timestamp]) => ({
+        sessionId,
+        title,
+        projectName: 'Timezone fixture',
+        projectPath: '/tmp/timezone-fixture',
+        startTime: new Date(timestamp),
+        endTime: new Date(Date.parse(timestamp) + 30 * 60_000),
+        data: claudeUsage(),
+        peakContextTokens: 180_000,
+      }))
     : [];
   provider.updateData(
     { ...today, sessionStart: new Date(now.getTime() - 3_600_000), sessionEnd: now },
@@ -232,6 +301,19 @@ function addClaudeData(provider, fixture = 'default') {
     undefined,
     undefined,
     weeklyRecords,
+    sessionBreakdown,
+    [],
+    enableContent
+      ? {
+          categories: [],
+          toolResultBreakdown: [],
+          totalEstimatedTokens: 0,
+          recentPrompts: [],
+          thinkingBySession: {},
+          thinkingByDay: {},
+          skillUses: [],
+        }
+      : null,
   );
   if (completedWeeklyFixture) {
     provider.updateWeeklyQuotaHistory([{
@@ -293,9 +375,28 @@ function withoutInputSnapshot(snapshot) {
   };
 }
 
-exports.renderHarness = function renderHarness({ provider: selectedProvider = 'codex', locale = 'en', theme = 'light', fixture = 'default', autoRefresh = false, weeklyValue = true } = {}) {
+function withoutHourlyRowsForCoveredDay(snapshot, day) {
+  for (const file of snapshot.files) {
+    if (!file.today?.days) continue;
+    delete file.today.days[day];
+    if (file.today.day === day) file.today.hours = {};
+  }
+  return snapshot;
+}
+
+exports.renderHarness = async function renderHarness({
+  provider: selectedProvider = 'codex',
+  locale = 'en',
+  theme = 'light',
+  fixture = 'default',
+  autoRefresh = false,
+  weeklyValue = true,
+  shareStudio = true,
+  adviceFeedback = 'none',
+  timeZone = 'Asia/Hong_Kong',
+} = {}) {
   I18n.setLanguage(locale);
-  I18n.setTimezone('Asia/Hong_Kong');
+  I18n.setTimezone(timeZone);
   vscodeHost.window.activeColorTheme.kind = theme === 'dark' ? 2 : 1;
   const originalNow = Date.now;
   try {
@@ -320,12 +421,62 @@ exports.renderHarness = function renderHarness({ provider: selectedProvider = 'c
         }
       : fixture === 'zero-input'
         ? withoutInputSnapshot(baseSnapshot)
+        : fixture === 'covered-day-without-hourly-rows'
+          ? withoutHourlyRowsForCoveredDay(baseSnapshot, '2026-07-19')
         : baseSnapshot;
     const view = buildCodexUsageView(snapshot, CODEX_WEBVIEW_NOW);
-    const provider = new UsageWebviewProvider({});
+    const provider = new UsageWebviewProvider({ globalState: memoryGlobalState() });
+    // The real extension loads globalState asynchronously before enabling any
+    // consent or feedback control. Let that same path settle in the harness.
+    await new Promise((resolve) => setImmediate(resolve));
     const persistedDetailsFixture = fixture === 'persisted-details';
-    provider.settings = settingsStore(autoRefresh, weeklyValue);
-    addClaudeData(provider, fixture);
+    const adviceEffectivenessFixture = fixture === 'advice-effectiveness';
+    const adviceOptimizerFixture = fixture === 'advice-optimizer';
+    const adviceContentFixture = adviceEffectivenessFixture
+      || adviceOptimizerFixture
+      || fixture === 'advice-effectiveness-disabled';
+    provider.settings = settingsStore({
+      autoRefresh,
+      weeklyValue,
+      shareStudio,
+      adviceEffectiveness: adviceEffectivenessFixture,
+      adviceOptimizer: adviceOptimizerFixture,
+    });
+    addClaudeData(provider, { fixture, enableContent: adviceContentFixture });
+    if (adviceEffectivenessFixture) {
+      provider.updateAdviceEffectivenessData(
+        buildAdviceEffectivenessFixture({ locale }).states,
+      );
+    }
+    if (adviceOptimizerFixture) {
+      provider.optimizerState = {
+        draft: 'HOST_ONLY_OPTIMIZER_DRAFT',
+        resolve: false,
+        distil: false,
+        aesthetic: false,
+        prompt: 'Paste-ready optimizer result',
+        settings: 'Effort: high',
+        adviceId: 'advice-optimizer-0123456789abcdef01234567',
+      };
+    }
+    if (adviceFeedback !== 'none') {
+      provider.adviceLocalState = {
+        ...provider.adviceLocalState,
+        featureMode: 'enabled',
+        feedback: [{
+          adviceId: adviceFeedback === 'optimizer-helpful'
+            ? 'advice-optimizer-0123456789abcdef01234567'
+            : 'advice-claude-ui-fixture',
+          recommendationId: adviceFeedback === 'optimizer-helpful'
+            ? 'recommendation-optimizer-result-v1'
+            : 'recommendation-claude-clear-between-tasks',
+          rating: 'helpful',
+          applied: 'not-applied',
+          appliedAtEpochMs: null,
+          updatedAtEpochMs: CODEX_WEBVIEW_NOW,
+        }],
+      };
+    }
     provider.updateProviderData(
       view,
       buildScopedCodexInsights(view),
diff --git a/tests/ui/support/server.mjs b/tests/ui/support/server.mjs
index 74eca816..e020b7fd 100644
--- a/tests/ui/support/server.mjs
+++ b/tests/ui/support/server.mjs
@@ -6,7 +6,7 @@ const { renderHarness } = require('./render-harness.cjs');
 const locales = new Set(['en', 'de-DE', 'zh-TW', 'zh-CN', 'ja', 'ko', 'pt-BR', 'id']);
 const uiTestPort = Number(process.env.CCU_UI_TEST_PORT ?? 4173);
 
-const server = createServer((request, response) => {
+const server = createServer(async (request, response) => {
   try {
     const url = new URL(request.url ?? '/', `http://127.0.0.1:${uiTestPort}`);
     if (url.pathname === '/health') {
@@ -28,12 +28,47 @@ const server = createServer((request, response) => {
       : 'codex';
     const theme = url.searchParams.get('theme') === 'dark' ? 'dark' : 'light';
     const requestedFixture = url.searchParams.get('fixture') ?? 'default';
-    const fixture = ['default', 'rootless-cycle', 'root-over-limit', 'persisted-details', 'weekly-usage-only', 'weekly-claude-completed', 'unknown-models', 'zero-input'].includes(requestedFixture)
+    const fixture = [
+      'default',
+      'rootless-cycle',
+      'root-over-limit',
+      'persisted-details',
+      'weekly-usage-only',
+      'weekly-claude-completed',
+      'unknown-models',
+      'zero-input',
+      'covered-day-without-hourly-rows',
+      'advice-effectiveness',
+      'advice-effectiveness-disabled',
+      'advice-optimizer',
+      'combined-heatmap',
+      'session-timezone-boundaries',
+    ].includes(requestedFixture)
       ? requestedFixture
       : 'default';
+    const requestedTimeZone = url.searchParams.get('timeZone') ?? 'Asia/Hong_Kong';
+    const timeZone = ['Asia/Hong_Kong', 'Asia/Tokyo', 'Pacific/Honolulu'].includes(requestedTimeZone)
+      ? requestedTimeZone
+      : 'Asia/Hong_Kong';
     const autoRefresh = url.searchParams.get('autoRefresh') === 'true';
     const weeklyValue = url.searchParams.get('weeklyValue') !== 'false';
-    const html = renderHarness({ provider, locale, theme, fixture, autoRefresh, weeklyValue });
+    const shareStudio = url.searchParams.get('shareStudio') !== 'false';
+    const requestedFeedback = url.searchParams.get('adviceFeedback');
+    const adviceFeedback = requestedFeedback === 'claude-helpful' ||
+      requestedFeedback === 'optimizer-helpful'
+      ? requestedFeedback
+      : 'none';
+    const html = await renderHarness({
+      provider,
+      locale,
+      theme,
+      fixture,
+      autoRefresh,
+      weeklyValue,
+      shareStudio,
+      adviceFeedback,
+      timeZone,
+    });
     response.writeHead(200, {
       'content-type': 'text/html; charset=utf-8',
       'cache-control': 'no-store',