@jlongo78/agent-spaces 0.10.0-beta.2 → 0.10.0-beta.4

package/.next/standalone/docs/superpowers/plans/2026-04-22-claude-usage-display.md

@@ -1,749 +0,0 @@
-# Claude Usage Display Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Show a compact Anthropic plan-usage readout (mirroring `/usage` in Claude Code) in the Spaces terminal page header, visible when the active workspace has at least one Claude pane.
-
-**Architecture:** Spaces reads the OAuth access token from `~/.claude/.credentials.json` (already maintained by Claude Code), calls `https://api.anthropic.com/api/oauth/usage`, caches 30s server-side, and polls the route every 60s from a React hook. A three-bar strip component renders in the header; clicking expands a popover with all windows. Passive refresh: if the access token is expired or missing, the strip shows a "sign in via Claude Code" hint.
-
-**Tech Stack:** Next.js App Router, React 18 client components, Node `fetch` with `AbortController`, TypeScript, Tailwind, lucide-react.
-
-**Spec:** `docs/superpowers/specs/2026-04-22-claude-usage-display-design.md`
-
-**Repo workflow note:** Commit directly to `main`. No feature branch, no PR. Each task ends with a commit.
-
----
-
-## File Structure
-
-**Create:**
-- `src/lib/claude/credentials.ts` — reads `.credentials.json`, extracts and validates the `claudeAiOauth` block.
-- `src/lib/claude/usage.ts` — calls Anthropic's `/api/oauth/usage`, caches 30s.
-- `src/app/api/claude/usage/route.ts` — `GET` handler wiring the above together.
-- `src/hooks/use-claude-usage.ts` — 60s polling hook.
-- `src/components/claude/claude-usage-strip.tsx` — compact 3-bar strip + expanded popover.
-- `docs/features/claude-usage.md` — feature doc.
-
-**Modify:**
-- `src/types/claude.ts` — add `RateLimit`, `ExtraUsage`, `Utilization`, `UsageResponse` types.
-- `src/app/(desktop)/terminal/page.tsx` — mount `<ClaudeUsageStrip>` conditionally in the header.
-
----
-
-## Task 1: Types + credentials reader
-
-**Files:**
-- Modify: `src/types/claude.ts`
-- Create: `src/lib/claude/credentials.ts`
-
-- [ ] **Step 1: Add types to `src/types/claude.ts`**
-
-Append at the end of the file:
-
-```ts
-// ─── Claude plan-usage (mirrors /usage in Claude Code) ───────
-
-export interface RateLimit {
-  utilization: number | null; // 0-100
-  resets_at: string | null;   // ISO 8601
-}
-
-export interface ExtraUsage {
-  is_enabled: boolean;
-  monthly_limit: number | null;
-  used_credits: number | null;
-  utilization: number | null;
-}
-
-export interface Utilization {
-  five_hour?: RateLimit | null;
-  seven_day?: RateLimit | null;
-  seven_day_oauth_apps?: RateLimit | null;
-  seven_day_opus?: RateLimit | null;
-  seven_day_sonnet?: RateLimit | null;
-  extra_usage?: ExtraUsage | null;
-}
-
-export type UsageResponse =
-  | { status: 'ok'; data: Utilization }
-  | { status: 'unauthenticated' }
-  | { status: 'expired' }
-  | { status: 'upstream_error' };
-```
-
-- [ ] **Step 2: Create `src/lib/claude/credentials.ts`**
-
-```ts
-import path from 'path';
-import os from 'os';
-import { readFile } from 'fs/promises';
-
-export interface ClaudeAiOAuthTokens {
-  accessToken: string;
-  refreshToken: string | null;
-  expiresAt: number | null; // epoch ms
-  scopes?: string[];
-}
-
-function getCredentialsPath(): string {
-  const home = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
-  return path.join(home, '.credentials.json');
-}
-
-/**
- * Reads ~/.claude/.credentials.json and returns the claudeAiOauth block.
- * Returns null on any read/parse failure or if the block is absent.
- */
-export async function readClaudeAiOauthTokens(): Promise<ClaudeAiOAuthTokens | null> {
-  try {
-    const raw = await readFile(getCredentialsPath(), 'utf8');
-    const parsed = JSON.parse(raw) as { claudeAiOauth?: ClaudeAiOAuthTokens };
-    const tokens = parsed.claudeAiOauth;
-    if (!tokens?.accessToken) return null;
-    return tokens;
-  } catch {
-    return null;
-  }
-}
-
-export function isTokenExpired(tokens: ClaudeAiOAuthTokens, nowMs = Date.now()): boolean {
-  if (!tokens.expiresAt) return false; // no expiry set → treat as valid
-  return nowMs >= tokens.expiresAt;
-}
-```
-
-- [ ] **Step 3: Type-check**
-
-```bash
-cd /home/jlongo/development/spaces && npx tsc --noEmit
-```
-
-Expected: no new errors.
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add src/types/claude.ts src/lib/claude/credentials.ts
-git commit -m "feat(claude): read OAuth tokens from .credentials.json"
-```
-
----
-
-## Task 2: Anthropic usage fetcher + cache
-
-**Files:**
-- Create: `src/lib/claude/usage.ts`
-
-- [ ] **Step 1: Create the fetcher**
-
-```ts
-import type { Utilization } from '@/types/claude';
-
-const ANTHROPIC_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
-const REQUEST_TIMEOUT_MS = 5_000;
-const CACHE_TTL_MS = 30_000;
-
-// UA matches the Claude Code format because Anthropic's endpoint classifies
-// the caller by UA. Kept in sync manually if upstream ever changes.
-const USER_AGENT = 'claude-code/spaces-integration';
-
-interface CacheEntry {
-  fetchedAt: number;
-  data: Utilization;
-}
-
-const cache = new Map<string, CacheEntry>();
-
-function cacheKey(accessToken: string): string {
-  return accessToken.slice(0, 16);
-}
-
-export type FetchOutcome =
-  | { ok: true; data: Utilization }
-  | { ok: false; reason: 'upstream_error' };
-
-export async function fetchUtilization(accessToken: string): Promise<FetchOutcome> {
-  const key = cacheKey(accessToken);
-  const cached = cache.get(key);
-  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-    return { ok: true, data: cached.data };
-  }
-
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-
-  try {
-    const res = await fetch(ANTHROPIC_USAGE_URL, {
-      method: 'GET',
-      headers: {
-        'Authorization': `Bearer ${accessToken}`,
-        'Content-Type': 'application/json',
-        'User-Agent': USER_AGENT,
-      },
-      signal: controller.signal,
-    });
-
-    if (!res.ok) {
-      return { ok: false, reason: 'upstream_error' };
-    }
-
-    const data = (await res.json()) as Utilization;
-    cache.set(key, { fetchedAt: Date.now(), data });
-    return { ok: true, data };
-  } catch {
-    return { ok: false, reason: 'upstream_error' };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/** Testing/hot-reload helper. */
-export function __clearUsageCache() {
-  cache.clear();
-}
-```
-
-- [ ] **Step 2: Type-check**
-
-```bash
-cd /home/jlongo/development/spaces && npx tsc --noEmit
-```
-
-Expected: no new errors.
-
-- [ ] **Step 3: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add src/lib/claude/usage.ts
-git commit -m "feat(claude): fetch Anthropic plan-usage with 30s cache"
-```
-
----
-
-## Task 3: API route `GET /api/claude/usage`
-
-**Files:**
-- Create: `src/app/api/claude/usage/route.ts`
-
-- [ ] **Step 1: Create the route**
-
-```ts
-import { NextRequest, NextResponse } from 'next/server';
-import { getAuthUser, withUser } from '@/lib/auth';
-import { ensureInitialized } from '@/lib/db/init';
-import { readClaudeAiOauthTokens, isTokenExpired } from '@/lib/claude/credentials';
-import { fetchUtilization } from '@/lib/claude/usage';
-import type { UsageResponse } from '@/types/claude';
-
-export async function GET(request: NextRequest) {
-  const user = getAuthUser(request);
-  return withUser(user, async () => {
-    await ensureInitialized();
-
-    const tokens = await readClaudeAiOauthTokens();
-    if (!tokens) {
-      const body: UsageResponse = { status: 'unauthenticated' };
-      return NextResponse.json(body);
-    }
-
-    if (isTokenExpired(tokens)) {
-      const body: UsageResponse = { status: 'expired' };
-      return NextResponse.json(body);
-    }
-
-    const outcome = await fetchUtilization(tokens.accessToken);
-    if (!outcome.ok) {
-      const body: UsageResponse = { status: 'upstream_error' };
-      return NextResponse.json(body);
-    }
-
-    const body: UsageResponse = { status: 'ok', data: outcome.data };
-    return NextResponse.json(body);
-  });
-}
-```
-
-- [ ] **Step 2: Smoke test against the running dev server**
-
-Determine which dev server is listening (3458 for turbopack is typical; 3457 for production build):
-
-```bash
-curl -sS http://localhost:3458/api/workspaces -o /dev/null -w '%{http_code}\n' 2>/dev/null
-curl -sS http://localhost:3457/api/workspaces -o /dev/null -w '%{http_code}\n' 2>/dev/null
-```
-
-Use whichever returns `200`. Then:
-
-```bash
-BASE=http://localhost:3458
-curl -s "$BASE/api/claude/usage"
-```
-
-Expected: JSON with one of the four statuses. If you're logged in, it should be `{"status":"ok","data":{...}}` with `five_hour`, `seven_day_opus`, etc. If logged out or no credentials file, it should be `{"status":"unauthenticated"}`.
-
-Don't start a new dev server; use whatever is already running. If the only listener is a production build that won't hot-reload, report BLOCKED.
-
-- [ ] **Step 3: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add src/app/api/claude/usage/route.ts
-git commit -m "feat(api): add GET /api/claude/usage"
-```
-
----
-
-## Task 4: `useClaudeUsage` hook
-
-**Files:**
-- Create: `src/hooks/use-claude-usage.ts`
-
-- [ ] **Step 1: Create the hook**
-
-```ts
-'use client';
-
-import { useEffect, useState } from 'react';
-import { api } from '@/lib/api';
-import type { UsageResponse } from '@/types/claude';
-
-const POLL_INTERVAL_MS = 60_000;
-
-export function useClaudeUsage(enabled: boolean): UsageResponse | null {
-  const [response, setResponse] = useState<UsageResponse | null>(null);
-
-  useEffect(() => {
-    if (!enabled) {
-      setResponse(null);
-      return;
-    }
-
-    let cancelled = false;
-
-    async function load() {
-      try {
-        const res = await fetch(api('/api/claude/usage'));
-        if (!res.ok) return;
-        const data: UsageResponse = await res.json();
-        if (!cancelled) setResponse(data);
-      } catch {
-        // Silent — the UI handles undefined state gracefully.
-      }
-    }
-
-    load();
-    const timer = setInterval(load, POLL_INTERVAL_MS);
-
-    return () => {
-      cancelled = true;
-      clearInterval(timer);
-    };
-  }, [enabled]);
-
-  return response;
-}
-```
-
-- [ ] **Step 2: Type-check**
-
-```bash
-cd /home/jlongo/development/spaces && npx tsc --noEmit
-```
-
-Expected: no new errors.
-
-- [ ] **Step 3: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add src/hooks/use-claude-usage.ts
-git commit -m "feat(hooks): add useClaudeUsage polling hook"
-```
-
----
-
-## Task 5: `<ClaudeUsageStrip />` component
-
-**Files:**
-- Create: `src/components/claude/claude-usage-strip.tsx`
-
-- [ ] **Step 1: Create the component**
-
-```tsx
-'use client';
-
-import { useEffect, useRef, useState } from 'react';
-import { Zap, LogIn } from 'lucide-react';
-import { useClaudeUsage } from '@/hooks/use-claude-usage';
-import type { RateLimit } from '@/types/claude';
-
-interface Props {
-  enabled: boolean;
-}
-
-function utilizationColor(pct: number | null): string {
-  if (pct == null) return '#52525b'; // zinc-600 — unknown
-  if (pct <= 70) return '#22c55e';    // green-500
-  if (pct <= 90) return '#f59e0b';    // amber-500
-  return '#ef4444';                    // red-500
-}
-
-function formatReset(resetsAt: string | null): string {
-  if (!resetsAt) return '';
-  const ms = new Date(resetsAt).getTime() - Date.now();
-  if (ms <= 0) return 'now';
-  const h = Math.floor(ms / 3_600_000);
-  const m = Math.floor((ms % 3_600_000) / 60_000);
-  if (h >= 24) {
-    const d = Math.floor(h / 24);
-    const rh = h - d * 24;
-    return `${d}d ${rh}h`;
-  }
-  if (h > 0) return `${h}h ${m}m`;
-  return `${m}m`;
-}
-
-function Bar({ label, limit }: { label: string; limit: RateLimit | null | undefined }) {
-  if (!limit || limit.utilization == null) return null;
-  const pct = Math.min(100, Math.max(0, limit.utilization));
-  const color = utilizationColor(pct);
-  const reset = formatReset(limit.resets_at);
-  return (
-    <div
-      className="flex items-center gap-1.5 text-[10px]"
-      title={reset ? `${label}: ${Math.floor(pct)}% used · resets in ${reset}` : `${label}: ${Math.floor(pct)}% used`}
-    >
-      <span className="text-zinc-400 font-medium">{label}</span>
-      <div className="w-12 h-1 bg-zinc-800 rounded-full overflow-hidden">
-        <div
-          className="h-full transition-all"
-          style={{ width: `${pct}%`, backgroundColor: color }}
-        />
-      </div>
-      <span className="text-zinc-500 tabular-nums w-7 text-right">{Math.floor(pct)}%</span>
-    </div>
-  );
-}
-
-export function ClaudeUsageStrip({ enabled }: Props) {
-  const response = useClaudeUsage(enabled);
-  const [expanded, setExpanded] = useState(false);
-  const popoverRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!expanded) return;
-    function handleClick(e: MouseEvent) {
-      if (popoverRef.current && !popoverRef.current.contains(e.target as Node)) {
-        setExpanded(false);
-      }
-    }
-    document.addEventListener('mousedown', handleClick);
-    return () => document.removeEventListener('mousedown', handleClick);
-  }, [expanded]);
-
-  if (!enabled || !response) return null;
-
-  if (response.status === 'unauthenticated' || response.status === 'expired') {
-    return (
-      <div
-        className="flex items-center gap-1.5 px-2 py-1 text-[10px] text-zinc-500 border border-zinc-800 rounded-md"
-        title={response.status === 'expired' ? 'OAuth token expired — run any Claude Code command to refresh' : 'No Claude.ai credentials found'}
-      >
-        <LogIn className="w-3 h-3" />
-        sign in via Claude Code
-      </div>
-    );
-  }
-
-  if (response.status === 'upstream_error') {
-    return null; // Silent — per spec.
-  }
-
-  const { data } = response;
-  const extra = data.extra_usage;
-  const hasOverage = !!(extra?.is_enabled && extra?.used_credits && extra.used_credits > 0);
-
-  return (
-    <div className="relative">
-      <button
-        onClick={() => setExpanded(v => !v)}
-        className="flex items-center gap-2.5 px-2.5 py-1 border border-zinc-800 rounded-md hover:border-zinc-700 transition-colors"
-        title="Click for full usage detail"
-      >
-        <Zap className="w-3 h-3 text-amber-400" />
-        <Bar label="5h" limit={data.five_hour} />
-        <Bar label="Opus" limit={data.seven_day_opus} />
-        <Bar label="Sonnet" limit={data.seven_day_sonnet} />
-        {hasOverage && extra?.used_credits != null && (
-          <span className="text-[10px] text-amber-400 border-l border-zinc-800 pl-2">
-            +${extra.used_credits.toFixed(2)} overage
-          </span>
-        )}
-      </button>
-
-      {expanded && (
-        <div
-          ref={popoverRef}
-          className="absolute top-full right-0 mt-1.5 z-50 w-80 p-3 bg-zinc-900 border border-zinc-700 rounded-md shadow-xl"
-        >
-          <div className="text-[10px] uppercase tracking-wider text-zinc-500 font-medium mb-2">
-            Plan Usage
-          </div>
-          <div className="space-y-2">
-            <ExpandedRow label="5-hour window" limit={data.five_hour} />
-            <ExpandedRow label="7-day (overall)" limit={data.seven_day} />
-            <ExpandedRow label="7-day · Opus" limit={data.seven_day_opus} />
-            <ExpandedRow label="7-day · Sonnet" limit={data.seven_day_sonnet} />
-            <ExpandedRow label="7-day · OAuth apps" limit={data.seven_day_oauth_apps} />
-          </div>
-          {extra?.is_enabled && (
-            <div className="mt-3 pt-3 border-t border-zinc-800">
-              <div className="text-[10px] uppercase tracking-wider text-zinc-500 font-medium mb-1.5">
-                Overage credits
-              </div>
-              <div className="text-xs text-zinc-300">
-                {extra.used_credits != null ? `$${extra.used_credits.toFixed(2)}` : '—'}
-                {extra.monthly_limit != null && (
-                  <span className="text-zinc-500"> / ${extra.monthly_limit.toFixed(2)} monthly</span>
-                )}
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  );
-}
-
-function ExpandedRow({ label, limit }: { label: string; limit: RateLimit | null | undefined }) {
-  if (!limit || limit.utilization == null) {
-    return (
-      <div className="flex items-center justify-between text-xs">
-        <span className="text-zinc-400">{label}</span>
-        <span className="text-zinc-600">—</span>
-      </div>
-    );
-  }
-  const pct = Math.min(100, Math.max(0, limit.utilization));
-  const color = utilizationColor(pct);
-  const reset = formatReset(limit.resets_at);
-  return (
-    <div>
-      <div className="flex items-center justify-between text-xs mb-1">
-        <span className="text-zinc-300">{label}</span>
-        <span className="text-zinc-500 tabular-nums">
-          {Math.floor(pct)}%{reset && <span className="ml-1.5 text-zinc-600">· {reset}</span>}
-        </span>
-      </div>
-      <div className="h-1.5 bg-zinc-800 rounded-full overflow-hidden">
-        <div
-          className="h-full transition-all"
-          style={{ width: `${pct}%`, backgroundColor: color }}
-        />
-      </div>
-    </div>
-  );
-}
-```
-
-- [ ] **Step 2: Type-check**
-
-```bash
-cd /home/jlongo/development/spaces && npx tsc --noEmit
-```
-
-- [ ] **Step 3: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add src/components/claude/claude-usage-strip.tsx
-git commit -m "feat(ui): add ClaudeUsageStrip component"
-```
-
----
-
-## Task 6: Mount `<ClaudeUsageStrip />` in the terminal header
-
-**Files:**
-- Modify: `src/app/(desktop)/terminal/page.tsx`
-
-- [ ] **Step 1: Add the import**
-
-At the top of `src/app/(desktop)/terminal/page.tsx`, near the other component imports (around the `WorkspaceTodos` / `ProjectWizard` imports), add:
-
-```tsx
-import { ClaudeUsageStrip } from '@/components/claude/claude-usage-strip';
-```
-
-- [ ] **Step 2: Mount conditionally in the header**
-
-Find the header's right-hand button cluster — the `<div className="flex items-center gap-2">` that contains the `Files`, `Collab`, `Close`, and `Add Pane` buttons (around lines 863-922, inside the entered-workspace `return`). Insert the strip **as the first child** of that cluster, before the `Files` button:
-
-```tsx
-        <div className="flex items-center gap-2">
-          <ClaudeUsageStrip enabled={panes.some(p => p.agentType === 'claude' && !poppedOut.has(p.id))} />
-          <button
-            onClick={() => setShowFiles(!showFiles)}
-            ...
-```
-
-The `enabled` prop is `true` when the current workspace has at least one visible (not popped-out) Claude pane. `panes` is already in scope in `TerminalPageInner`.
-
-- [ ] **Step 3: Type-check**
-
-```bash
-cd /home/jlongo/development/spaces && npx tsc --noEmit
-```
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add "src/app/(desktop)/terminal/page.tsx"
-git commit -m "feat(terminal): mount ClaudeUsageStrip in header when Claude panes exist"
-```
-
----
-
-## Task 7: Feature doc
-
-**Files:**
-- Create: `docs/features/claude-usage.md`
-
-- [ ] **Step 1: Write the doc**
-
-```markdown
-# Claude Plan-Usage Display
-
-**Status:** stable
-**Owner:** jlongo
-**Last updated:** 2026-04-22
-
-## Overview
-
-A compact readout of the user's Anthropic plan-usage rate limits, surfaced in the terminal page header whenever the active workspace has at least one Claude pane. Shows 5-hour, 7-day Opus, and 7-day Sonnet windows at a glance; click expands to all windows plus overage credits. Data matches what `/usage` shows inside Claude Code.
-
-## User-facing behavior
-
-- Open any workspace on `/terminal` that has a Claude pane.
-- A horizontal strip appears in the header (right side, before Files / Collab / Close / Add Pane).
-- Three thin progress bars: **5h**, **Opus**, **Sonnet** — each with a percent label and a color that escalates green → amber → red.
-- Hover a bar → tooltip `{label}: X% used · resets in 2h 14m`.
-- Click the strip → popover with all five rate-limit windows + an overage-credits block if the account has overage enabled.
-- If the OAuth token is missing or expired, the strip shows `sign in via Claude Code` with a small login icon. No auto-refresh.
-- If the Anthropic endpoint fails or times out, the strip hides silently.
-
-## Architecture
-
-UI (`src/components/claude/claude-usage-strip.tsx`) → polling hook (`src/hooks/use-claude-usage.ts`) → API route (`src/app/api/claude/usage/route.ts`) → credentials reader (`src/lib/claude/credentials.ts`) + Anthropic fetcher with 30s cache (`src/lib/claude/usage.ts`) → `https://api.anthropic.com/api/oauth/usage`.
-
-Polling: hook calls the route on mount and every 60s while the strip is enabled. Server caches the Anthropic response 30s per access-token prefix so rapid re-polls don't hammer Anthropic.
-
-## Key files
-
-| Path | Role |
-|---|---|
-| `src/lib/claude/credentials.ts` | Reads `~/.claude/.credentials.json`, extracts `claudeAiOauth`, exposes `isTokenExpired()`. |
-| `src/lib/claude/usage.ts` | Calls Anthropic's `/api/oauth/usage`, 5s timeout, 30s in-memory cache. |
-| `src/app/api/claude/usage/route.ts` | `GET` handler; returns one of `ok` / `unauthenticated` / `expired` / `upstream_error`. |
-| `src/hooks/use-claude-usage.ts` | 60s polling hook, toggled by `enabled` arg. |
-| `src/components/claude/claude-usage-strip.tsx` | Compact 3-bar strip + expanded popover. |
-| `src/app/(desktop)/terminal/page.tsx` | Mounts the strip conditionally in the header. |
-| `src/types/claude.ts` | `RateLimit`, `ExtraUsage`, `Utilization`, `UsageResponse`. |
-
-## Data model
-
-No DB tables. All state is transient:
-- Server-side: in-memory `Map<tokenPrefix, { fetchedAt, data }>` in `src/lib/claude/usage.ts` with 30s TTL. Process-local; resets on server restart.
-- Client-side: React state in the hook.
-
-## APIs / contracts
-
-### Internal endpoints
-
-- `GET /api/claude/usage` — returns `UsageResponse`:
-  - `200 { status: "ok", data: Utilization }` — happy path.
-  - `200 { status: "unauthenticated" }` — no credentials file or no `claudeAiOauth`.
-  - `200 { status: "expired" }` — access token past `expiresAt`.
-  - `200 { status: "upstream_error" }` — Anthropic non-2xx or timeout.
-
-Auth: same `withUser`/`getAuthUser` wrapping as every other `/api/*` route.
-
-### External calls
-
-- **Anthropic `GET https://api.anthropic.com/api/oauth/usage`** — uses the user's own OAuth access token read from `~/.claude/.credentials.json`. No secret of our own. User-Agent `claude-code/spaces-integration`.
-
-## Configuration & environment
-
-- `CLAUDE_CONFIG_DIR` — respected (defaults to `~/.claude`). Same semantics as Claude Code.
-- No env vars, feature flags, or tier gates specific to this feature.
-
-## How to run / test locally
-
-```bash
-npm install
-npm run build
-npm start
-# visit http://localhost:3457/terminal, enter a workspace, add a Claude pane
-```
-
-Manual QA checklist:
-
-1. With a valid OAuth session (logged in via any recent Claude Code run): the strip appears in the header; percents match `/usage` inside Claude Code.
-2. Hover each bar → tooltip shows the reset timing.
-3. Click → popover with all five windows and overage block (if applicable).
-4. Delete the Claude pane from the workspace → strip disappears.
-5. Set `claudeAiOauth.expiresAt` to a past timestamp in `.credentials.json`, reload → strip shows "sign in via Claude Code".
-6. Move `.credentials.json` aside temporarily, reload → same sign-in hint.
-7. Disconnect network → within ~90s the strip silently hides (`upstream_error` → null render).
-
-No automated tests for v1.
-
-## Known quirks & decisions
-
-- **Passive refresh.** We do not refresh the OAuth access token. Claude Code owns the refresh lifecycle and writes `.credentials.json`; racing with it would corrupt the shared file.
-- **Account-wide data, not per-pane.** The Anthropic endpoint returns account-level rate limits. Rendering once in the header (not per-pane) is intentional.
-- **User-Agent string.** Anthropic classifies callers by UA; we send `claude-code/spaces-integration`. If upstream changes expectations, bump the constant in `src/lib/claude/usage.ts`.
-- **30s cache + 60s poll.** Outer-bound staleness is ~90s; fine for windows that move in hours.
-- **Token-prefix cache key.** First 16 chars of `accessToken`. Collision probability is effectively nil; avoids holding full tokens in the cache structure beyond the single request.
-- **Silent upstream failure.** Errors hide the strip rather than showing a red toast — rate-limit info is nice-to-have, not mission-critical.
-- **Ships direct to `main`.** Per repo convention.
-
-## Open questions / TODOs
-
-- [ ] Active OAuth refresh — mirror Claude Code's `/oauth/token` dance to keep the widget live past expiry. Deferred for v1.
-- [ ] Session-cost complement using local JSONL token counts (different data source).
-- [ ] Consider surfacing 7-day-overall alongside the current three for users who care.
-
-## Changelog
-
-- 2026-04-22 — Initial implementation. v1 ships direct to `main`.
-```
-
-- [ ] **Step 2: Commit**
-
-```bash
-cd /home/jlongo/development/spaces
-git add docs/features/claude-usage.md
-git commit -m "docs(features): add claude-usage feature doc"
-```
-
----
-
-## Self-Review Notes
-
-**Spec coverage:** every section of `docs/superpowers/specs/2026-04-22-claude-usage-display-design.md` is implemented:
-- Types → Task 1
-- Credentials reader → Task 1
-- Anthropic fetcher + cache → Task 2
-- API route with four structured statuses → Task 3
-- 60s polling hook → Task 4
-- Component (compact + expanded) → Task 5
-- Conditional header mount → Task 6
-- Feature doc → Task 7
-
-**Placeholder scan:** no TBD/TODO outside the feature doc's explicit "Open questions / TODOs" section.
-
-**Type consistency:** `Utilization`, `RateLimit`, `ExtraUsage`, `UsageResponse` are defined once in Task 1 and referenced by the same names in Tasks 2 / 3 / 4 / 5 / 7.