> 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/phases/phase_21/prd_phase_21.md). # PRD Phase 21: Non-Hermes v2.3 Usage Accuracy **Status**: Complete **Sessions**: 3 (initial estimate) **Estimated Duration**: 4-7 days **Source Code Roots**: `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`; diff reference = `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/`. **Progress**: 3/3 sessions (100%) *** ## Overview Phase 21 starts the final non-Hermes v2.3 migration tranche. It ports the dashboard accuracy work that makes usage, spend, ROI, daily activity, and recent project counts honest, while preserving aios's current pricing table, script architecture, validators, and privacy posture. This phase and Phases 22-23 replace `docs/ongoing-projects/v2_3-port-remaining.md` as the durable source of truth. The old document can be deleted after these phase PRDs and session stubs are reviewed because every remaining item, already-done item, skip decision, caveat, validation rule, and source-code anchor from that document is folded into the phase artifacts. Phase 21 owns workstream A items A1-A5: * A1: pricing robustness with family fallback, 3.x rows, and null-for-unknown. * A2: authoritative Claude usage through OAuth `/usage`, with safe fallback. * A3: real per-day session counts. * A4: true 7-day `recentProjects` plus `allProjects`. * A5: per-skill default minutes-per-run. Phases 22 and 23 own the dependent Antigravity consumers, multi-agent surfaces, Claude Code route, UI polish, optional housekeeping, and final non-Hermes parity closeout. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | -------------------------------------- | -------- | ---------- | ---------- | | 01 | Pricing And Daily Activity Accuracy | Complete | \~18-24 | 2026-06-02 | | 02 | Project Windows And Skill ROI Defaults | Complete | \~16-22 | 2026-06-02 | | 03 | Authoritative Claude Usage OAuth | Complete | \~18-25 | 2026-06-02 | *** ## Completed Sessions 1. `phase21-session01-pricing-daily-activity-accuracy` - Pricing And Daily Activity Accuracy, completed 2026-06-02 2. `phase21-session02-project-windows-skill-roi-defaults` - Project Windows And Skill ROI Defaults, completed 2026-06-02 3. `phase21-session03-authoritative-claude-usage-oauth` - Authoritative Claude Usage OAuth, completed 2026-06-02 *** ## Upcoming Sessions * None *** ## Source Reference Legend All file references in Phases 21-23 use these roots: * `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/` - the source. * `AIOS/` = `/home/aiwithapex/projects/aios/` - the target repo. * Diff source of truth: `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/` ([full.diff](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/diff-v1-v2.3/full.diff), [SUMMARY.md](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/diff-v1-v2.3/SUMMARY.md), [changed-text.txt](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/diff-v1-v2.3/changed-text.txt), [added-text.txt](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/diff-v1-v2.3/added-text.txt)). `file:line` anchors are accurate as of the original v2.3 indexing pass. Treat them as "start reading here," not exact post-edit positions. *** ## Migration Audit Preservation The non-Hermes v2.3 sweep classified every non-binary file in the v1 to v2.3 diff as Hermes-owned, already done in aios, or a genuine remaining gap. The finding was that aios already ported most non-Hermes improvements and has also diverged forward with Opus 4.8 pricing, Codex, OpenClaw, extensions, a scheduler, and a modular `scripts/lib/` aggregator that v2.3 did not have. ### Already Done In aios - Do Not Re-Port | v2.3 improvement | V23 source | aios state | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Hermes filesystem snapshot (`gatherHermes`) | [V23/scripts/aggregate.ts:978](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:978) | [AIOS/scripts/lib/hermes-scanner.ts:233](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-scanner.ts:233), emitted by [AIOS/scripts/lib/aggregate-orchestration.ts:1132](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/aggregate-orchestration.ts:1132) | | Hermes app detection (`hermes: AppDetection`) | [V23/scripts/aggregate.ts:916](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:916) | [AIOS/scripts/lib/app-detection.ts:63](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/app-detection.ts:63), [AIOS/scripts/lib/app-detection.ts:114](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/app-detection.ts:114) | | Dream cron resolves `claude` absolute path (`CLAUDE_BIN`) and warns | [V23/scripts/install-dream-cron.ts:52](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/install-dream-cron.ts:52), [V23/scripts/install-dream-cron.ts:219](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/install-dream-cron.ts:219) | [AIOS/scripts/install-dream-cron.ts:54](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/install-dream-cron.ts:54), [AIOS/scripts/install-dream-cron.ts:63](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/install-dream-cron.ts:63), [AIOS/scripts/install-dream-cron.ts:220](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/install-dream-cron.ts:220), [AIOS/scripts/install-dream-cron.ts:287](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/install-dream-cron.ts:287) | | `copyPersonasSkill` into `~/.hermes/skills/` | [V23/scripts/setup.ts:96](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/setup.ts:96), [V23/scripts/setup.ts:212](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/setup.ts:212) | [AIOS/scripts/setup.ts:98](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/setup.ts:98), [AIOS/scripts/setup.ts:233](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/setup.ts:233); aios copies only if absent | | Dream `SKILL.md` plan-aware cost framing and Hermes signal source | [V23/skills/dream/SKILL.md:76](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/skills/dream/SKILL.md:76), [V23/skills/dream/SKILL.md:25](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/skills/dream/SKILL.md:25) | [AIOS/skills/dream/SKILL.md:38](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/skills/dream/SKILL.md:38), [AIOS/skills/dream/SKILL.md:90](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/skills/dream/SKILL.md:90) | | `js-yaml` and `@types/js-yaml` dependencies | [V23/package.json:60](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/package.json:60), [V23/package.json:68](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/package.json:68) | [AIOS/package.json:101](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/package.json:101), [AIOS/package.json:133](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/package.json:133) | | Global `HermesStatusPill` in top bar | [V23/src/routes/\_\_root.tsx:146](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/__root.tsx:146) | [AIOS/src/routes/\_\_root.tsx:16](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/routes/__root.tsx:16), [AIOS/src/routes/\_\_root.tsx:217](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/routes/__root.tsx:217) | | Removed dead `poll-existing.ts` | V23 deleted file | Absent in aios | | `recentProjects[].sessions` is a real unique-session count | [V23/scripts/aggregate.ts:1306](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:1306) | [AIOS/scripts/lib/aggregate-orchestration.ts:1118](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/aggregate-orchestration.ts:1118), backed by [AIOS/scripts/lib/session-scanner.ts:447](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/session-scanner.ts:447) | | usage-panel product names, with Codex split from ChatGPT | [V23/src/components/usage-panel.tsx:90](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/usage-panel.tsx:90) | [AIOS/src/components/usage-panel.tsx:23](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/usage-panel.tsx:23), already has `Codex` | ### Covered By Hermes Phases 16-20 The following are cross-referenced to the Hermes feature port and must not be duplicated in Phases 21-23: `hermes-mission-control.tsx`, `hermes-mnemosyne.tsx`, `hermes-documents-gallery.tsx`, `hermes-status-pill.tsx`, all `agents.hermes.tsx` features, the `vite.config.ts` Hermes bridge, `hermes-art/` assets, `personas/SKILL.md`, the `.hermes-skin` CSS block, and the Fraunces/Courier Prime web-fonts. The Phase 16 PRD is the master Hermes reference and already points directly to `V23/`, `AIOS/`, and the diff artifacts. If a remaining non-Hermes item depends on one of those deliverables, its session stub states that dependency. *** ## Cross-Phase Sequencing 1. Phase 21 Session 01 ports A1 and A3 first because they are pure data-layer accuracy changes with high trust value and low UI risk. 2. Phase 21 Session 02 ports A4 and A5, completing local ROI and activity accuracy that does not depend on Antigravity. 3. Phase 22 Session 01 ports B1, the Antigravity data prerequisite for A6, A7, and the Antigravity tile in B3. 4. Phase 22 Session 02 ports A6 and A7 as data consumers after B1. 5. Phase 22 Session 03 ports B2 and B3, including the home `DreamSourcesStrip`. 6. Phase 21 Session 03 ports A2 deliberately with redaction, timeout, and fallback tests because OAuth usage is the highest-value and most sensitive item. 7. Phase 23 Session 01 ports the Claude Code route only after Hermes Mission Control exists from Phase 19. 8. Phase 23 Sessions 02-03 close out UI polish, optional housekeeping, docs, no-action items, and final non-Hermes parity validation. *** ## Objectives 1. Make Claude model pricing and spend computation robust without adopting stale v2.3 Opus pricing. 2. Replace daily activity session heuristics with real per-day unique-session counts while preserving backwards-compatible fallback behavior. 3. Correct recent project semantics to a true seven-day window and add long-tail project history. 4. Restore practical per-skill saved-time defaults so ROI rows do not show avoidable zero-dollar saved values. 5. Add authoritative Claude usage through OAuth `/usage` with fully safe credential reads, token redaction, short timeouts, and silent fallback. *** ## Prerequisites * Phases 16-20 may remain pending; Phase 21 does not require Hermes UI parity. * The aggregate split from Phase 15 remains the current script architecture: keep changes inside `scripts/lib/` helpers and aggregator orchestration rather than restoring the v2.3 monolith. * Active security considerations still apply: no raw credentials in logs, generated live data must stay sanitized, and browser-visible output must be validated. *** ## Technical Considerations ### Architecture All script work should extend the modular aios aggregator: `AIOS/scripts/lib/session-scanner.ts`, `AIOS/scripts/lib/aggregate-orchestration.ts`, `AIOS/scripts/lib/usage-assembly.ts`, and `AIOS/scripts/lib/subscription-detection.ts`. Browser consumers must use `AIOS/src/lib/live-data-types.ts`, `AIOS/src/lib/validate-live-data.ts`, `AIOS/src/lib/home-transforms.ts`, and existing usage-panel/home rendering boundaries. ### Session Source Map **Session 01: A1 and A3** * A1 source: [V23/scripts/aggregate.ts:463](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:463) through `:522` for table and family fallback, and `:560` for `computeCost` use. * A1 target: [AIOS/scripts/lib/session-scanner.ts:6](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/session-scanner.ts:6) through `:12` for the current 4.x table including `claude-opus-4-8`, and [AIOS/scripts/lib/session-scanner.ts:112](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/session-scanner.ts:112) for the current unknown-model zero fallback. * A1 caveat: port the mechanism, not v2.3's prices. v2.3 uses Opus `$15/$75`; aios currently uses `$5/$25` for Opus 4.8 era pricing. Family fallback rates must be derived from the current aios table. * A3 source: [V23/scripts/aggregate.ts:535](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:535), [V23/scripts/aggregate.ts:553](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:553), [V23/scripts/aggregate.ts:1283](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:1283), and [V23/src/routes/index.tsx:16115](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/index.tsx:16115) through `:16168` for `computeDailyActivity`. * A3 target: [AIOS/scripts/lib/session-scanner.ts:568](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/session-scanner.ts:568), [AIOS/scripts/lib/aggregate-orchestration.ts:1094](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/aggregate-orchestration.ts:1094), [AIOS/src/lib/home-transforms.ts:373](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/home-transforms.ts:373), plus `DailyEntry` and validation in `AIOS/src/lib/live-data-types.ts` and `AIOS/src/lib/validate-live-data.ts`. **Session 02: A4 and A5** * A4 source: [V23/scripts/aggregate.ts:1288](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:1288) through `:1323`. * A4 target: [AIOS/scripts/lib/aggregate-orchestration.ts:1112](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/aggregate-orchestration.ts:1112) through `:1122`, plus `live-data-types.ts`, `validate-live-data.ts`, and example data. * A4 rationale: the old top-10-ever list was labeled 7d and could silently include projects 17-28 days old. `recentProjects` must become a true modified-within-seven-days list, and `allProjects` should carry long-tail history, top 30 unless implementation proves uncapped is safe. * A5 source: [V23/src/lib/time-saved.ts:8](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/lib/time-saved.ts:8) through `:89`, with home wiring at [V23/src/routes/index.tsx:16088](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/index.tsx:16088) and [V23/src/routes/index.tsx:16108](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/index.tsx:16108). * A5 target: [AIOS/src/lib/time-saved.ts:23](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/time-saved.ts:23) and [AIOS/src/lib/time-saved.ts:91](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/time-saved.ts:91). * A5 decision: port v2.3's `SKILL_MINUTE_DEFAULTS` table verbatim as the starting point. Change an individual default only if it is objectively wrong for a corresponding aios skill. The prefix-regex matcher should degrade gracefully to a generic five-minute fallback for aios-only skills. **Session 03: A2** * A2 source: [V23/scripts/aggregate.ts:588](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:588) through `:755` for `ClaudeAuthoritativeUsage`, `readClaudeCredential`, `detectClaudeCodeVersion`, and `fetchClaudeOAuthUsage`; [V23/scripts/aggregate.ts:1153](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:1153) for the call site; and [V23/scripts/aggregate.ts:1191](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/aggregate.ts:1191) through `:1267` for the `claudeWindow` rebuild with `source`, `resetsAt`, and authoritative payload. * A2 target: new `AIOS/scripts/lib/claude-oauth-usage.ts`, orchestration wiring in `AIOS/scripts/lib/aggregate-orchestration.ts`, usage assembly in `AIOS/scripts/lib/usage-assembly.ts` and `AIOS/scripts/lib/subscription-detection.ts`, and a live-vs-estimate badge in [AIOS/src/components/usage-panel.tsx:23](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/usage-panel.tsx:23). * A2 aios convention: follow [AIOS/scripts/lib/subscription-detection.ts:40](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/subscription-detection.ts:40) through `:61` for `IS_MACOS`, `Bun.spawn`, two-second timeout race, and Keychain probing; follow [AIOS/scripts/lib/subscription-detection.ts:67](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/subscription-detection.ts:67) through `:89` for safe validators. Do not use v2.3's `execSync` pattern or `process.platform === "darwin"` style. * A2 decision: full platform scope. Read `~/.claude/.credentials.json` first, then macOS Keychain with `security find-generic-password -s "Claude Code-credentials" -a "$USER" -w`; return null on any miss or failure. * A2 safety: read-only outbound call to Anthropic's own API with the operator's own token; redact the token from all logs; use a short six-second timeout; silently fall back to local heuristics; add the token to bridge redaction. ### Relevant Considerations * \[P01] Bundle budget watch: changes should not add heavy client bundles. * \[P02] Typed degradation over throws: OAuth and model-price failures return explicit fallback/uncounted states instead of blocking aggregate output. * \[P08] Local agent privacy/readiness boundary: never expose prompts, transcripts, auth payloads, raw paths, or credentials. * \[P15] Aggregate collection must stay budgeted: added remote usage fetches need short timeouts and must not stall scheduled aggregate jobs. *** ## Success Criteria Phase complete when: * [ ] All three sessions completed and validated. * [ ] `computeCost` uses `priceForModel` with exact, family fallback, old 3.x, and unknown-null semantics while preserving current aios prices. * [ ] `daily[].sessions` emits real unique-session counts and home transforms prefer it with old-data fallback. * [ ] `recentProjects` is truly seven-day filtered, and `allProjects` carries long-tail project history. * [ ] Skill ROI defaults use the v2.3 prefix-regex table and a five-minute generic fallback. * [ ] Claude OAuth usage can prefer authoritative server-side `pct` and `resetsAt` data, labels live vs estimate, never logs credentials, and falls back silently on any failure. * [ ] Added fields are represented in `live-data-types.ts`, `validate-live-data.ts`, `src/data/live-data.example.json`, and relevant script/UI tests. *** ## Dependencies ### Depends On * Phase 15: Scheduler Config And Aggregate Split * Existing aios aggregate modularization under `scripts/lib/` ### Enables * Phase 22: Non-Hermes Multi-Agent Detection And Home Surfaces * Phase 23: Non-Hermes Routes, Polish And Closeout --- # 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/phases/phase_21/prd_phase_21.md?ask=&goal= ``` `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.