> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase21-session03-authoritative-claude-usage-oauth/tasks.md).

# Task Checklist

**Session ID**: `phase21-session03-authoritative-claude-usage-oauth` **Total Tasks**: 22 **Estimated Duration**: 3.5-4 hours **Created**: 2026-06-02

***

## Legend

* `[x]` = Completed
* `[ ]` = Pending
* `[P]` = Parallelizable (can run with other \[P] tasks)
* `[SNNMM]` = Session reference (NN=phase number, MM=session number)
* `TNNN` = Task ID

***

## Progress Summary

| Category       | Total  | Done   | Remaining |
| -------------- | ------ | ------ | --------- |
| Setup          | 2      | 2      | 0         |
| Foundation     | 6      | 6      | 0         |
| Implementation | 10     | 10     | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **22** | **22** | **0**     |

***

## Setup (2 tasks)

Initial configuration and environment preparation.

* [x] T001 \[S2103] Record source-map, prerequisite, and no-live-credential assumptions (`.spec_system/specs/phase21-session03-authoritative-claude-usage-oauth/implementation-notes.md`)
* [x] T002 \[S2103] Create OAuth privacy, redaction, and fallback baseline (`.spec_system/specs/phase21-session03-authoritative-claude-usage-oauth/security-compliance.md`)

***

## Foundation (6 tasks)

Core structures and base implementations.

* [x] T003 \[S2103] \[P] Create Claude OAuth usage module contract with credential, authoritative payload, and injectable dependency types (`scripts/lib/claude-oauth-usage.ts`)
* [x] T004 \[S2103] Implement file and macOS Keychain credential readers with schema-validated input, `Bun.spawn`, timeout cleanup, raw/JSON handling, and null fallback (`scripts/lib/claude-oauth-usage.ts`)
* [x] T005 \[S2103] Implement Claude CLI version detection with `Bun.spawn`, timeout cleanup, safe version validation, and null fallback on missing CLI (`scripts/lib/claude-oauth-usage.ts`)
* [x] T006 \[S2103] Implement OAuth usage fetch with contained authorization header, six-second timeout, schema-validated response, explicit error mapping to null, and no credential logging (`scripts/lib/claude-oauth-usage.ts`)
* [x] T007 \[S2103] Extend Claude window builder with authoritative input, `source`, `resetsAt`, bounded payload, estimate fallback, and exhaustive source handling (`scripts/lib/usage-assembly.ts`)
* [x] T008 \[S2103] Extend browser live-data contract with Claude usage source/reset/authoritative fields that cannot carry credentials (`src/lib/live-data-types.ts`)

***

## Implementation (10 tasks)

Main feature implementation.

* [x] T009 \[S2103] Update live-data validation with bounded additive Claude usage fields and legacy payload compatibility (`src/lib/validate-live-data.ts`)
* [x] T010 \[S2103] Extend free-form script redaction for representative Claude OAuth token shapes without redacting legitimate token counts (`scripts/lib/ai-runtime/providers.ts`)
* [x] T011 \[S2103] Wire authoritative usage fetch into aggregate orchestration with timeout-bounded call, silent fallback, sanitized log summaries, and source switching (`scripts/lib/aggregate-orchestration.ts`)
* [x] T012 \[S2103] Update safe generated example data for estimate/live-compatible Claude usage fields (`src/data/live-data.example.json`)
* [x] T013 \[S2103] Update usage-panel service and window view models for live/estimate source and reset data with validated fallback on re-entry (`src/components/usage-panel.tsx`)
* [x] T014 \[S2103] Render Claude live versus estimate badge and reset labels with accessible labels and no layout overflow (`src/components/usage-panel.tsx`)
* [x] T015 \[S2103] \[P] Add OAuth helper tests for file, Keychain, missing credential, missing CLI, non-200, timeout, parse failure, and token non-exposure (`scripts/lib/__tests__/claude-oauth-usage.test.ts`)
* [x] T016 \[S2103] \[P] Add Claude window projection tests for source switching, reset propagation, bounded payload, and estimate fallback (`scripts/lib/__tests__/usage-assembly.test.ts`)
* [x] T017 \[S2103] \[P] Add aggregate orchestration and redaction regression tests for authoritative wiring and token filtering (`scripts/lib/__tests__/aggregate-orchestration.test.ts`, `scripts/lib/__tests__/ai-runtime-providers.test.ts`)
* [x] T018 \[S2103] \[P] Add live-data validation and usage-panel tests for legacy payloads, live badge, and reset labels (`src/lib/__tests__/nested-validation.test.ts`, `src/components/__tests__/usage-panel.test.tsx`)

***

## Testing (4 tasks)

Verification and quality assurance.

* [x] T019 \[S2103] Run focused script tests for OAuth helper, usage assembly, aggregate orchestration, and redaction (`scripts/lib/__tests__/claude-oauth-usage.test.ts`)
* [x] T020 \[S2103] Run focused browser contract and usage-panel tests for validation, legacy payloads, live badge, and reset labels (`src/components/__tests__/usage-panel.test.tsx`)
* [x] T021 \[S2103] Run script typecheck, app typecheck, and full test suite (`package.json`)
* [x] T022 \[S2103] Validate ASCII/LF output and record commands, results, residual risks, and privacy evidence (`.spec_system/specs/phase21-session03-authoritative-claude-usage-oauth/implementation-notes.md`)

***

## Completion Checklist

Before marking session complete:

* [x] All tasks marked `[x]`
* [x] All tests passing
* [x] All files ASCII-encoded
* [x] implementation-notes.md updated
* [x] security-compliance.md updated
* [x] Ready for the validate workflow step

***

## Next Steps

Run the validate workflow step to verify session completeness.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase21-session03-authoritative-claude-usage-oauth/tasks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.