Permanent Claude 0/0 fix: Firefox cookies + honest fallback + /health

[BlockedPath]

Why

Three rounds of "0/0 on the iPhone" all traced to the same architecture:
the AppleScript-Chrome scrape was a single point of failure (Chrome can
silently disable "Allow JavaScript from Apple Events" on update), and
when it broke the daemon fell through to a token-count fallback that
reported 0% any time you exceeded the hardcoded 200k/1M budget. The user
couldn't tell "daemon down" from "limit hit."

This PR is the permanent fix.

What changed

• New scripts/claude-plan-usage-firefox.py — reads sessionKey from
  Firefox's unencrypted cookies.sqlite and calls
  https://claude.ai/api/organizations/{org}/usage directly. No
  AppleScript, no DOM scrape; immune to page-layout changes and the
  Chrome preference. Writes a health side-file so /health can surface
  the last scrape outcome. Setup is one-time: ./scripts/claude-plan-usage-firefox.py login.
• LaunchAgent + install.sh switched to the Firefox script as primary.
  The Chrome AppleScript script stays for manual fallback only.
• Honest fallback in the daemon — when every fresh source fails, return
  the last cached claude-plan-usage.json percentages with ok=False
  and status "stale Nh" instead of the misleading token-budget 0/0.
  The token-count path is no longer reachable for the Claude provider.
• /health endpoint exposes per-source freshness, last scrape result,
  and the snapshot the daemon is currently serving.
• CLAUDE.md is the new project runbook: documents every failure
  mode I've debugged in this thread (Firefox session expired, daemon
  running stale code after pull, LaunchAgent dead, claude.ai page change,
  Chrome preference disabled, mDNS name collision) with the exact
  /health signature and the commands to fix each.

Verified live

$ curl -s http://localhost:9596/usage
{"s":63,"sr":66,"w":73,"wr":476,"st":"5h 37% used · 7d 27% used","ok":true,...}

$ curl -s http://localhost:9596/health | jq .sources.plan_usage
{ "path": ".../claude-plan-usage.json", "exists": true, "age_seconds": 8, "fresh": true }

Test plan

• ruff check daemon/ scripts/ clean
• pytest -q (11 passed)
• Restart claude daemon → /usage serves real percentages from Firefox-cookie scrape
• /health reports sources.plan_usage.fresh: true and current snapshot ok: true
• iOS app shows non-zero values after next 30 s poll
• After Firefox session expires, daemon serves last-known with ok: false and status: "stale Xh" instead of 0/0

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.