@venturewild/workspace 0.3.7 → 0.4.0

package/server/src/usage.mjs

@@ -1,405 +1,405 @@
-// Usage + context service — the data behind the floating "Usage" canvas block (§8 of
-// docs/agent-engine-and-commands-design.md). Two numbers, two sources:
-//
-//   1. Plan utilization (Session 5-hour + Weekly 7-day %)  — AUTHORITATIVE, from
-//      Anthropic's own OAuth usage endpoint. The same endpoint ccstatusline reads.
-//   2. Context % ("working memory")                        — LOCAL, computed from the
-//      latest assistant turn's token usage (no network). See computeContext().
-//
-// DESIGN RULES baked in here (don't relitigate — see §8):
-//   - The endpoint is UNOFFICIAL/community-documented → we DEGRADE, never throw. A
-//     failure keeps the last-good value and flips status to 'stale'/'unavailable';
-//     the UI shows that honestly. Core UX never depends on it.
-//   - `User-Agent: claude-code/<version>` is MANDATORY — omitting it is a hard 429.
-//   - Poll every 60–120s and ALWAYS re-poll: utilization climbs WITHIN a window as the
-//     user consumes, so `resets_at` only drives the countdown + a post-reset refresh —
-//     it never suppresses polling.
-//   - On 429, back off (don't hammer) and serve stale.
-//   - We READ the user's Claude OAuth token locally (new trust surface). It only ever
-//     leaves the box to api.anthropic.com — never logged, never sent elsewhere. A
-//     one-time disclosure (stored ack under ~/.wild-workspace) gates first activation.
-//
-// VERIFIED EMPIRICALLY (2026-06-11, this box, `claude` 2.1.172):
-//   - ~/.claude/.credentials.json = { claudeAiOauth: { accessToken, expiresAt, … } }.
-//   - A real turn's usage: input_tokens=2, cache_creation_input_tokens=45504 → an
-//     input-only context gauge reads ~20× too low. Numerator = sum of the three.
-//   - Records store the model as `claude-opus-4-8` with the `[1m]` suffix STRIPPED, so
-//     a 1M-context session can't be distinguished from 200k by model name alone — the
-//     window map below defaults accordingly; see WINDOW_CALIBRATION note.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { execFileSync } from 'node:child_process';
-
-const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
-const OAUTH_BETA = 'oauth-2025-04-20';
-
-// Poll cadence. The TTL *is* the cadence — we re-poll on it (see header). Kept in the
-// 60–120s band the design fixed (rate-limit-friendly); default 90s.
-export const DEFAULT_POLL_MS = 90_000;
-// After a transient 429 we back off to this before the next attempt.
-export const BACKOFF_MS = 5 * 60_000;
-// Per-request network timeout — never let a hung socket stall the timer.
-const FETCH_TIMEOUT_MS = 10_000;
-
-// --- credential resolution -------------------------------------------------
-// Order (per §8): CLAUDE_CONFIG_DIR → ~/.claude/.credentials.json → macOS keychain.
-// Returns { token, expiresAt } or null. Never throws (degrade).
-
-function readCredsFile(file) {
-  try {
-    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
-    const o = raw.claudeAiOauth || raw; // tolerate both shapes
-    const token = o.accessToken || o.access_token;
-    if (typeof token !== 'string' || !token) return null;
-    const expiresAt = o.expiresAt ?? o.expires_at ?? null;
-    return { token, expiresAt };
-  } catch {
-    return null;
-  }
-}
-
-function readKeychain() {
-  // macOS only. `security` returns the secret on stdout; any failure → null. The
-  // secret name follows Claude Code's convention ("Claude Code-credentials").
-  try {
-    const out = execFileSync(
-      'security',
-      ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
-      { encoding: 'utf8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'] },
-    );
-    const raw = JSON.parse(out.trim());
-    const o = raw.claudeAiOauth || raw;
-    const token = o.accessToken || o.access_token;
-    if (typeof token !== 'string' || !token) return null;
-    return { token, expiresAt: o.expiresAt ?? o.expires_at ?? null };
-  } catch {
-    return null;
-  }
-}
-
-export function readOAuthToken({
-  env = process.env,
-  platform = process.platform,
-  home = os.homedir(),
-} = {}) {
-  // 1. CLAUDE_CONFIG_DIR/.credentials.json
-  const configDir = env.CLAUDE_CONFIG_DIR;
-  if (configDir) {
-    const hit = readCredsFile(path.join(configDir, '.credentials.json'));
-    if (hit) return hit;
-  }
-  // 2. ~/.claude/.credentials.json
-  const hit = readCredsFile(path.join(home, '.claude', '.credentials.json'));
-  if (hit) return hit;
-  // 3. macOS keychain
-  if (platform === 'darwin') {
-    const kc = readKeychain();
-    if (kc) return kc;
-  }
-  return null;
-}
-
-// True when a token is present but already past its expiry. v1 does NOT refresh
-// tokens (out of scope) — an expired token degrades to 'unavailable' so the user
-// is told honestly rather than seeing a silent 401 loop.
-export function isExpired(cred, now = Date.now()) {
-  if (!cred || cred.expiresAt == null) return false;
-  const exp = Number(cred.expiresAt);
-  if (!Number.isFinite(exp)) return false;
-  // expiresAt is epoch ms in the credentials file.
-  return exp <= now;
-}
-
-// --- claude version (for the mandatory UA) ---------------------------------
-// Best-effort, detected once and cached. The `claude-code/` PREFIX is what the
-// endpoint requires (omit → 429); the exact version is cosmetic, so a sane fallback
-// is fine if detection fails. Override via WILD_WORKSPACE_CLAUDE_VERSION (tests do).
-
-let _versionCache;
-export function claudeVersion(env = process.env) {
-  if (env.WILD_WORKSPACE_CLAUDE_VERSION) return env.WILD_WORKSPACE_CLAUDE_VERSION;
-  if (_versionCache !== undefined) return _versionCache;
-  try {
-    const out = execFileSync('claude', ['--version'], {
-      encoding: 'utf8',
-      timeout: 5000,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    const m = out.match(/(\d+\.\d+\.\d+)/);
-    _versionCache = m ? m[1] : '2.1.172';
-  } catch {
-    _versionCache = '2.1.172'; // recent known-good fallback
-  }
-  return _versionCache;
-}
-
-export function userAgent(env = process.env) {
-  return `claude-code/${claudeVersion(env)}`;
-}
-
-// --- the network call ------------------------------------------------------
-// Returns { ok:true, status, body } on a 2xx with JSON, else { ok:false, status,
-// error }. NEVER throws — the caller's degrade logic keys off the shape.
-
-export async function fetchUsage({
-  token,
-  ua,
-  fetchImpl = globalThis.fetch,
-  timeoutMs = FETCH_TIMEOUT_MS,
-} = {}) {
-  if (!token) return { ok: false, status: 0, error: 'no_token' };
-  if (typeof fetchImpl !== 'function') return { ok: false, status: 0, error: 'no_fetch' };
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-  try {
-    const res = await fetchImpl(USAGE_ENDPOINT, {
-      method: 'GET',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'anthropic-beta': OAUTH_BETA,
-        'User-Agent': ua, //                          ← MANDATORY (omit → hard 429)
-        'Content-Type': 'application/json',
-      },
-      signal: ctrl.signal,
-    });
-    if (!res.ok) return { ok: false, status: res.status, error: `http_${res.status}` };
-    const body = await res.json();
-    return { ok: true, status: res.status, body };
-  } catch (e) {
-    return { ok: false, status: 0, error: e?.name === 'AbortError' ? 'timeout' : 'network' };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// --- parse the usage body --------------------------------------------------
-// Tolerant: any missing block degrades to null/absent rather than throwing. Shape
-// (per §8): { five_hour, seven_day, seven_day_opus, seven_day_sonnet, extra_usage }.
-
-function pctBlock(b) {
-  if (!b || typeof b !== 'object') return null;
-  const u = Number(b.utilization);
-  return {
-    utilization: Number.isFinite(u) ? Math.max(0, Math.min(100, u)) : 0,
-    resets_at: typeof b.resets_at === 'string' ? b.resets_at : null,
-  };
-}
-
-export function parseUsage(body = {}) {
-  if (!body || typeof body !== 'object') body = {};
-  const out = {
-    five_hour: pctBlock(body.five_hour),
-    seven_day: pctBlock(body.seven_day),
-    seven_day_opus: pctBlock(body.seven_day_opus),
-    seven_day_sonnet: pctBlock(body.seven_day_sonnet),
-  };
-  const ex = body.extra_usage;
-  if (ex && typeof ex === 'object') {
-    out.extra_usage = {
-      is_enabled: !!ex.is_enabled,
-      monthly_limit: Number(ex.monthly_limit) || 0,
-      used_credits: Number(ex.used_credits) || 0,
-      utilization: Number.isFinite(Number(ex.utilization)) ? Number(ex.utilization) : 0,
-    };
-  }
-  return out;
-}
-
-// --- context gauge (LOCAL, no network) -------------------------------------
-//
-// WINDOW_CALIBRATION (the documented residual — see §8/§9):
-//   - Numerator = input + cache_creation + cache_read (verified; input-only is ~10–20×
-//     low because cache dominates the prompt).
-//   - Denominator = the model's context window. Records DON'T carry context_window_size
-//     and STRIP the `[1m]` suffix, so we map by model name + detect a `[1m]` suffix when
-//     the live stream-json provides one. The 1M variant therefore UNDER-detects from
-//     historical records (defaults to 200k) — acceptable for a "working memory" gauge,
-//     not an exact clone of Claude's /context. If we adopt Claude's statusline hook
-//     later, prefer its context_window_size over this map.
-//   - Residual #2: does /context measure toward the full window or the auto-compact
-//     threshold? We measure toward the FULL window (ccstatusline's convention) and label
-//     it "working memory", not Claude's exact %.
-
-const K = 1000;
-const DEFAULT_WINDOW = 200 * K;
-const ONE_M = 1000 * K;
-// Prefix → window. Keep claude + the glm-* models this workspace has seen; unknown →
-// DEFAULT_WINDOW. (Non-Claude models get NO plan-usage, but the context gauge still works.)
-const WINDOWS = [
-  ['claude-opus', 200 * K],
-  ['claude-sonnet', 200 * K],
-  ['claude-haiku', 200 * K],
-  ['claude-fable', 200 * K],
-  ['glm', 200 * K],
-];
-
-export function windowFor(model) {
-  if (!model || typeof model !== 'string') return DEFAULT_WINDOW;
-  const m = model.toLowerCase();
-  // 1M-context variants advertise themselves with a [1m] / -1m marker WHEN present.
-  if (m.includes('[1m]') || m.includes('-1m') || m.endsWith(':1m')) return ONE_M;
-  for (const [prefix, w] of WINDOWS) if (m.startsWith(prefix)) return w;
-  return DEFAULT_WINDOW;
-}
-
-export function computeContext(usage = {}, model = '') {
-  const input = Number(usage.input_tokens) || 0;
-  const cacheCreate = Number(usage.cache_creation_input_tokens) || 0;
-  const cacheRead = Number(usage.cache_read_input_tokens) || 0;
-  const used = input + cacheCreate + cacheRead;
-  const window = windowFor(model);
-  const pct = window > 0 ? Math.max(0, Math.min(100, (used / window) * 100)) : 0;
-  return { used, window, pct, model: model || null };
-}
-
-// --- disclosure ack (server-side, one-time per USER) -----------------------
-// Stored under ~/.wild-workspace/usage/ (CLAUDE.md #1 — never the synced workspace,
-// never localStorage which would be per-browser/device). One file, last-write-wins.
-
-function defaultUsageDir(env = process.env, home = os.homedir()) {
-  const base = env.WILD_WORKSPACE_GLOBAL_DIR || path.join(home, '.wild-workspace');
-  return path.join(base, 'usage');
-}
-
-// --- the stateful service --------------------------------------------------
-// One instance per server. Owns the cached snapshot, the poll timer, the degrade
-// logic, the local context gauge, and the disclosure ack. `onUpdate(state)` fires on
-// every snapshot change (the WS push path mirrors the bazaar meter — no client poll).
-
-export function createUsageService({
-  env = process.env,
-  platform = process.platform,
-  home = os.homedir(),
-  baseDir, //                      override the ack dir (tests)
-  fetchImpl = globalThis.fetch,
-  pollMs = DEFAULT_POLL_MS,
-  onUpdate = null,
-  now = () => Date.now(),
-} = {}) {
-  const dir = baseDir || defaultUsageDir(env, home);
-  const ackFile = path.join(dir, 'disclosure.json');
-
-  // status: 'loading' (never fetched) | 'live' (fresh good data) | 'stale' (had data,
-  // last refresh failed) | 'unavailable' (no token / expired / never got data).
-  let snap = {
-    status: 'loading',
-    plan: null, //                 parsed usage blocks (five_hour, seven_day, …)
-    context: null, //              { used, window, pct, model }
-    fetchedAt: null, //            ms of the last GOOD fetch
-    error: null, //                last error marker (for the UI's honest message)
-  };
-  let timer = null;
-  let backoffUntil = 0;
-
-  function emit() {
-    if (typeof onUpdate === 'function') {
-      try { onUpdate(snapshot()); } catch { /* a bad listener never breaks the timer */ }
-    }
-  }
-
-  // One refresh cycle. NEVER throws. Returns the new snapshot.
-  async function refresh() {
-    // Respect a 429 backoff window: serve stale, don't hammer.
-    if (now() < backoffUntil) {
-      if (snap.status === 'live') snap = { ...snap, status: 'stale', error: 'backoff' };
-      return snapshot();
-    }
-    const cred = readOAuthToken({ env, platform, home });
-    if (!cred) {
-      snap = { ...snap, status: 'unavailable', error: 'no_token' };
-      emit();
-      return snapshot();
-    }
-    if (isExpired(cred, now())) {
-      // v1 does not refresh tokens — tell the user honestly.
-      snap = { ...snap, status: 'unavailable', error: 'expired_token' };
-      emit();
-      return snapshot();
-    }
-    const res = await fetchUsage({ token: cred.token, ua: userAgent(env), fetchImpl });
-    if (res.ok) {
-      snap = {
-        status: 'live',
-        plan: parseUsage(res.body),
-        context: snap.context, // context is updated separately by setContext()
-        fetchedAt: now(),
-        error: null,
-      };
-      emit();
-      return snapshot();
-    }
-    // Degrade. On 429 set a backoff. Keep last-good plan data if we had any.
-    if (res.status === 429) backoffUntil = now() + BACKOFF_MS;
-    const hadData = snap.plan != null;
-    snap = {
-      ...snap,
-      status: hadData ? 'stale' : 'unavailable',
-      error: res.error || `http_${res.status}`,
-    };
-    emit();
-    return snapshot();
-  }
-
-  // The local context gauge — fed by the server when an assistant turn reports usage
-  // (see index.mjs wiring). No network. Pushes an update so the gauge moves per-turn.
-  function setContext(usage, model) {
-    snap = { ...snap, context: computeContext(usage || {}, model || '') };
-    emit();
-    return snap.context;
-  }
-
-  function snapshot() {
-    return {
-      status: snap.status,
-      plan: snap.plan,
-      context: snap.context,
-      fetchedAt: snap.fetchedAt,
-      error: snap.error,
-      // The ack travels with the snapshot so the UI knows whether to show the
-      // one-time disclosure before first activation.
-      disclosed: isDisclosed(),
-    };
-  }
-
-  // --- disclosure ack ---
-  function isDisclosed() {
-    try {
-      const v = JSON.parse(fs.readFileSync(ackFile, 'utf8'));
-      return v?.acknowledged === true;
-    } catch {
-      return false;
-    }
-  }
-  function acknowledge() {
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-      const tmp = `${ackFile}.${process.pid}.tmp`;
-      fs.writeFileSync(tmp, JSON.stringify({ acknowledged: true, ts: now() }, null, 2));
-      fs.renameSync(tmp, ackFile);
-    } catch {
-      /* read-only fs — degrade to not-persisted (will re-ask, harmless) */
-    }
-    return true;
-  }
-
-  // --- timer ---
-  function start() {
-    if (timer) return; // idempotent
-    // Lazy first fetch (don't block startup); then the steady cadence.
-    refresh();
-    timer = setInterval(refresh, pollMs);
-    if (timer.unref) timer.unref(); // never keep the process alive for a gauge
-  }
-  function stop() {
-    if (timer) { clearInterval(timer); timer = null; }
-  }
-
-  return {
-    dir, ackFile,
-    refresh, snapshot, setContext,
-    isDisclosed, acknowledge,
-    start, stop,
-  };
-}
+// Usage + context service — the data behind the floating "Usage" canvas block (§8 of
+// docs/agent-engine-and-commands-design.md). Two numbers, two sources:
+//
+//   1. Plan utilization (Session 5-hour + Weekly 7-day %)  — AUTHORITATIVE, from
+//      Anthropic's own OAuth usage endpoint. The same endpoint ccstatusline reads.
+//   2. Context % ("working memory")                        — LOCAL, computed from the
+//      latest assistant turn's token usage (no network). See computeContext().
+//
+// DESIGN RULES baked in here (don't relitigate — see §8):
+//   - The endpoint is UNOFFICIAL/community-documented → we DEGRADE, never throw. A
+//     failure keeps the last-good value and flips status to 'stale'/'unavailable';
+//     the UI shows that honestly. Core UX never depends on it.
+//   - `User-Agent: claude-code/<version>` is MANDATORY — omitting it is a hard 429.
+//   - Poll every 60–120s and ALWAYS re-poll: utilization climbs WITHIN a window as the
+//     user consumes, so `resets_at` only drives the countdown + a post-reset refresh —
+//     it never suppresses polling.
+//   - On 429, back off (don't hammer) and serve stale.
+//   - We READ the user's Claude OAuth token locally (new trust surface). It only ever
+//     leaves the box to api.anthropic.com — never logged, never sent elsewhere. A
+//     one-time disclosure (stored ack under ~/.wild-workspace) gates first activation.
+//
+// VERIFIED EMPIRICALLY (2026-06-11, this box, `claude` 2.1.172):
+//   - ~/.claude/.credentials.json = { claudeAiOauth: { accessToken, expiresAt, … } }.
+//   - A real turn's usage: input_tokens=2, cache_creation_input_tokens=45504 → an
+//     input-only context gauge reads ~20× too low. Numerator = sum of the three.
+//   - Records store the model as `claude-opus-4-8` with the `[1m]` suffix STRIPPED, so
+//     a 1M-context session can't be distinguished from 200k by model name alone — the
+//     window map below defaults accordingly; see WINDOW_CALIBRATION note.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
+const OAUTH_BETA = 'oauth-2025-04-20';
+
+// Poll cadence. The TTL *is* the cadence — we re-poll on it (see header). Kept in the
+// 60–120s band the design fixed (rate-limit-friendly); default 90s.
+export const DEFAULT_POLL_MS = 90_000;
+// After a transient 429 we back off to this before the next attempt.
+export const BACKOFF_MS = 5 * 60_000;
+// Per-request network timeout — never let a hung socket stall the timer.
+const FETCH_TIMEOUT_MS = 10_000;
+
+// --- credential resolution -------------------------------------------------
+// Order (per §8): CLAUDE_CONFIG_DIR → ~/.claude/.credentials.json → macOS keychain.
+// Returns { token, expiresAt } or null. Never throws (degrade).
+
+function readCredsFile(file) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const o = raw.claudeAiOauth || raw; // tolerate both shapes
+    const token = o.accessToken || o.access_token;
+    if (typeof token !== 'string' || !token) return null;
+    const expiresAt = o.expiresAt ?? o.expires_at ?? null;
+    return { token, expiresAt };
+  } catch {
+    return null;
+  }
+}
+
+function readKeychain() {
+  // macOS only. `security` returns the secret on stdout; any failure → null. The
+  // secret name follows Claude Code's convention ("Claude Code-credentials").
+  try {
+    const out = execFileSync(
+      'security',
+      ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+      { encoding: 'utf8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    const raw = JSON.parse(out.trim());
+    const o = raw.claudeAiOauth || raw;
+    const token = o.accessToken || o.access_token;
+    if (typeof token !== 'string' || !token) return null;
+    return { token, expiresAt: o.expiresAt ?? o.expires_at ?? null };
+  } catch {
+    return null;
+  }
+}
+
+export function readOAuthToken({
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+} = {}) {
+  // 1. CLAUDE_CONFIG_DIR/.credentials.json
+  const configDir = env.CLAUDE_CONFIG_DIR;
+  if (configDir) {
+    const hit = readCredsFile(path.join(configDir, '.credentials.json'));
+    if (hit) return hit;
+  }
+  // 2. ~/.claude/.credentials.json
+  const hit = readCredsFile(path.join(home, '.claude', '.credentials.json'));
+  if (hit) return hit;
+  // 3. macOS keychain
+  if (platform === 'darwin') {
+    const kc = readKeychain();
+    if (kc) return kc;
+  }
+  return null;
+}
+
+// True when a token is present but already past its expiry. v1 does NOT refresh
+// tokens (out of scope) — an expired token degrades to 'unavailable' so the user
+// is told honestly rather than seeing a silent 401 loop.
+export function isExpired(cred, now = Date.now()) {
+  if (!cred || cred.expiresAt == null) return false;
+  const exp = Number(cred.expiresAt);
+  if (!Number.isFinite(exp)) return false;
+  // expiresAt is epoch ms in the credentials file.
+  return exp <= now;
+}
+
+// --- claude version (for the mandatory UA) ---------------------------------
+// Best-effort, detected once and cached. The `claude-code/` PREFIX is what the
+// endpoint requires (omit → 429); the exact version is cosmetic, so a sane fallback
+// is fine if detection fails. Override via WILD_WORKSPACE_CLAUDE_VERSION (tests do).
+
+let _versionCache;
+export function claudeVersion(env = process.env) {
+  if (env.WILD_WORKSPACE_CLAUDE_VERSION) return env.WILD_WORKSPACE_CLAUDE_VERSION;
+  if (_versionCache !== undefined) return _versionCache;
+  try {
+    const out = execFileSync('claude', ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const m = out.match(/(\d+\.\d+\.\d+)/);
+    _versionCache = m ? m[1] : '2.1.172';
+  } catch {
+    _versionCache = '2.1.172'; // recent known-good fallback
+  }
+  return _versionCache;
+}
+
+export function userAgent(env = process.env) {
+  return `claude-code/${claudeVersion(env)}`;
+}
+
+// --- the network call ------------------------------------------------------
+// Returns { ok:true, status, body } on a 2xx with JSON, else { ok:false, status,
+// error }. NEVER throws — the caller's degrade logic keys off the shape.
+
+export async function fetchUsage({
+  token,
+  ua,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = FETCH_TIMEOUT_MS,
+} = {}) {
+  if (!token) return { ok: false, status: 0, error: 'no_token' };
+  if (typeof fetchImpl !== 'function') return { ok: false, status: 0, error: 'no_fetch' };
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(USAGE_ENDPOINT, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'anthropic-beta': OAUTH_BETA,
+        'User-Agent': ua, //                          ← MANDATORY (omit → hard 429)
+        'Content-Type': 'application/json',
+      },
+      signal: ctrl.signal,
+    });
+    if (!res.ok) return { ok: false, status: res.status, error: `http_${res.status}` };
+    const body = await res.json();
+    return { ok: true, status: res.status, body };
+  } catch (e) {
+    return { ok: false, status: 0, error: e?.name === 'AbortError' ? 'timeout' : 'network' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- parse the usage body --------------------------------------------------
+// Tolerant: any missing block degrades to null/absent rather than throwing. Shape
+// (per §8): { five_hour, seven_day, seven_day_opus, seven_day_sonnet, extra_usage }.
+
+function pctBlock(b) {
+  if (!b || typeof b !== 'object') return null;
+  const u = Number(b.utilization);
+  return {
+    utilization: Number.isFinite(u) ? Math.max(0, Math.min(100, u)) : 0,
+    resets_at: typeof b.resets_at === 'string' ? b.resets_at : null,
+  };
+}
+
+export function parseUsage(body = {}) {
+  if (!body || typeof body !== 'object') body = {};
+  const out = {
+    five_hour: pctBlock(body.five_hour),
+    seven_day: pctBlock(body.seven_day),
+    seven_day_opus: pctBlock(body.seven_day_opus),
+    seven_day_sonnet: pctBlock(body.seven_day_sonnet),
+  };
+  const ex = body.extra_usage;
+  if (ex && typeof ex === 'object') {
+    out.extra_usage = {
+      is_enabled: !!ex.is_enabled,
+      monthly_limit: Number(ex.monthly_limit) || 0,
+      used_credits: Number(ex.used_credits) || 0,
+      utilization: Number.isFinite(Number(ex.utilization)) ? Number(ex.utilization) : 0,
+    };
+  }
+  return out;
+}
+
+// --- context gauge (LOCAL, no network) -------------------------------------
+//
+// WINDOW_CALIBRATION (the documented residual — see §8/§9):
+//   - Numerator = input + cache_creation + cache_read (verified; input-only is ~10–20×
+//     low because cache dominates the prompt).
+//   - Denominator = the model's context window. Records DON'T carry context_window_size
+//     and STRIP the `[1m]` suffix, so we map by model name + detect a `[1m]` suffix when
+//     the live stream-json provides one. The 1M variant therefore UNDER-detects from
+//     historical records (defaults to 200k) — acceptable for a "working memory" gauge,
+//     not an exact clone of Claude's /context. If we adopt Claude's statusline hook
+//     later, prefer its context_window_size over this map.
+//   - Residual #2: does /context measure toward the full window or the auto-compact
+//     threshold? We measure toward the FULL window (ccstatusline's convention) and label
+//     it "working memory", not Claude's exact %.
+
+const K = 1000;
+const DEFAULT_WINDOW = 200 * K;
+const ONE_M = 1000 * K;
+// Prefix → window. Keep claude + the glm-* models this workspace has seen; unknown →
+// DEFAULT_WINDOW. (Non-Claude models get NO plan-usage, but the context gauge still works.)
+const WINDOWS = [
+  ['claude-opus', 200 * K],
+  ['claude-sonnet', 200 * K],
+  ['claude-haiku', 200 * K],
+  ['claude-fable', 200 * K],
+  ['glm', 200 * K],
+];
+
+export function windowFor(model) {
+  if (!model || typeof model !== 'string') return DEFAULT_WINDOW;
+  const m = model.toLowerCase();
+  // 1M-context variants advertise themselves with a [1m] / -1m marker WHEN present.
+  if (m.includes('[1m]') || m.includes('-1m') || m.endsWith(':1m')) return ONE_M;
+  for (const [prefix, w] of WINDOWS) if (m.startsWith(prefix)) return w;
+  return DEFAULT_WINDOW;
+}
+
+export function computeContext(usage = {}, model = '') {
+  const input = Number(usage.input_tokens) || 0;
+  const cacheCreate = Number(usage.cache_creation_input_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens) || 0;
+  const used = input + cacheCreate + cacheRead;
+  const window = windowFor(model);
+  const pct = window > 0 ? Math.max(0, Math.min(100, (used / window) * 100)) : 0;
+  return { used, window, pct, model: model || null };
+}
+
+// --- disclosure ack (server-side, one-time per USER) -----------------------
+// Stored under ~/.wild-workspace/usage/ (CLAUDE.md #1 — never the synced workspace,
+// never localStorage which would be per-browser/device). One file, last-write-wins.
+
+function defaultUsageDir(env = process.env, home = os.homedir()) {
+  const base = env.WILD_WORKSPACE_GLOBAL_DIR || path.join(home, '.wild-workspace');
+  return path.join(base, 'usage');
+}
+
+// --- the stateful service --------------------------------------------------
+// One instance per server. Owns the cached snapshot, the poll timer, the degrade
+// logic, the local context gauge, and the disclosure ack. `onUpdate(state)` fires on
+// every snapshot change (the WS push path mirrors the bazaar meter — no client poll).
+
+export function createUsageService({
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  baseDir, //                      override the ack dir (tests)
+  fetchImpl = globalThis.fetch,
+  pollMs = DEFAULT_POLL_MS,
+  onUpdate = null,
+  now = () => Date.now(),
+} = {}) {
+  const dir = baseDir || defaultUsageDir(env, home);
+  const ackFile = path.join(dir, 'disclosure.json');
+
+  // status: 'loading' (never fetched) | 'live' (fresh good data) | 'stale' (had data,
+  // last refresh failed) | 'unavailable' (no token / expired / never got data).
+  let snap = {
+    status: 'loading',
+    plan: null, //                 parsed usage blocks (five_hour, seven_day, …)
+    context: null, //              { used, window, pct, model }
+    fetchedAt: null, //            ms of the last GOOD fetch
+    error: null, //                last error marker (for the UI's honest message)
+  };
+  let timer = null;
+  let backoffUntil = 0;
+
+  function emit() {
+    if (typeof onUpdate === 'function') {
+      try { onUpdate(snapshot()); } catch { /* a bad listener never breaks the timer */ }
+    }
+  }
+
+  // One refresh cycle. NEVER throws. Returns the new snapshot.
+  async function refresh() {
+    // Respect a 429 backoff window: serve stale, don't hammer.
+    if (now() < backoffUntil) {
+      if (snap.status === 'live') snap = { ...snap, status: 'stale', error: 'backoff' };
+      return snapshot();
+    }
+    const cred = readOAuthToken({ env, platform, home });
+    if (!cred) {
+      snap = { ...snap, status: 'unavailable', error: 'no_token' };
+      emit();
+      return snapshot();
+    }
+    if (isExpired(cred, now())) {
+      // v1 does not refresh tokens — tell the user honestly.
+      snap = { ...snap, status: 'unavailable', error: 'expired_token' };
+      emit();
+      return snapshot();
+    }
+    const res = await fetchUsage({ token: cred.token, ua: userAgent(env), fetchImpl });
+    if (res.ok) {
+      snap = {
+        status: 'live',
+        plan: parseUsage(res.body),
+        context: snap.context, // context is updated separately by setContext()
+        fetchedAt: now(),
+        error: null,
+      };
+      emit();
+      return snapshot();
+    }
+    // Degrade. On 429 set a backoff. Keep last-good plan data if we had any.
+    if (res.status === 429) backoffUntil = now() + BACKOFF_MS;
+    const hadData = snap.plan != null;
+    snap = {
+      ...snap,
+      status: hadData ? 'stale' : 'unavailable',
+      error: res.error || `http_${res.status}`,
+    };
+    emit();
+    return snapshot();
+  }
+
+  // The local context gauge — fed by the server when an assistant turn reports usage
+  // (see index.mjs wiring). No network. Pushes an update so the gauge moves per-turn.
+  function setContext(usage, model) {
+    snap = { ...snap, context: computeContext(usage || {}, model || '') };
+    emit();
+    return snap.context;
+  }
+
+  function snapshot() {
+    return {
+      status: snap.status,
+      plan: snap.plan,
+      context: snap.context,
+      fetchedAt: snap.fetchedAt,
+      error: snap.error,
+      // The ack travels with the snapshot so the UI knows whether to show the
+      // one-time disclosure before first activation.
+      disclosed: isDisclosed(),
+    };
+  }
+
+  // --- disclosure ack ---
+  function isDisclosed() {
+    try {
+      const v = JSON.parse(fs.readFileSync(ackFile, 'utf8'));
+      return v?.acknowledged === true;
+    } catch {
+      return false;
+    }
+  }
+  function acknowledge() {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const tmp = `${ackFile}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({ acknowledged: true, ts: now() }, null, 2));
+      fs.renameSync(tmp, ackFile);
+    } catch {
+      /* read-only fs — degrade to not-persisted (will re-ask, harmless) */
+    }
+    return true;
+  }
+
+  // --- timer ---
+  function start() {
+    if (timer) return; // idempotent
+    // Lazy first fetch (don't block startup); then the steady cadence.
+    refresh();
+    timer = setInterval(refresh, pollMs);
+    if (timer.unref) timer.unref(); // never keep the process alive for a gauge
+  }
+  function stop() {
+    if (timer) { clearInterval(timer); timer = null; }
+  }
+
+  return {
+    dir, ackFile,
+    refresh, snapshot, setContext,
+    isDisclosed, acknowledge,
+    start, stop,
+  };
+}