feat: Claude usage threshold gate

[finedesignz]

Summary

Adds a per-user Anthropic usage threshold gate over the existing OAuth usage poller. When 5h or 7d utilization crosses a user-configured percentage, remo-code pauses NEW dispatches at all 4 entry points (scheduler, pickSessionTarget, error-capture, manual chat) until the window resets. In-flight runs are NOT killed.

Architecture: .planning/phases/claude-usage-thresholds/00-architecture-review.md

Key amendments from review (all applied):

• DROP ccusage — uses existing /api/oauth/usage poller; ccusage deferred to future opt-in PR
• Per-USER (not per-agent) — usage is subscription-scoped
• Default NULL (gate OFF) — existing users not silently opted in
• 4 dispatch sites gated, not 2
• New scheduled_task_runs.status = 'skipped_quota'
• Idempotent schema (ALTER … IF NOT EXISTS + DO $$ EXCEPTION wrapper for CHECK)

Schema

ALTER TABLE users ADD COLUMN IF NOT EXISTS claude_session_threshold_pct INTEGER;
ALTER TABLE users ADD COLUMN IF NOT EXISTS claude_week_threshold_pct INTEGER;
-- CHECK 1..100 OR NULL, scheduled_task_runs CHECK rebuilt with 'skipped_quota'

Refusal shape (HTTP 503 + WS send_refused)

{
  "error": "quota_threshold_reached",
  "reason": "session_threshold",
  "utilization_pct": 92,
  "threshold_pct": 90,
  "resets_at": "2026-05-26T05:00:00Z"
}

Tests

• hub/test/threshold.test.ts — 10 cases (back-compat NULL, fail-open, session-over, week-over, both-over precedence, boundary >=, opus carve-out, single-cap modes)
• Full suite: 256 pass / 0 fail / 56 skip (e2e DB-gated)
• bun run build:web clean

Test plan

• Coolify redeploy via UUID zewfc6g9dw3c4h88z2jd2o4g
• DB migration auto-runs on hub boot (idempotent — safe on prod with existing data)
• Settings → Profile → "Claude usage threshold gate" card renders, toggles + sliders work
• PUT /api/account/claude-thresholds with {session_pct: 90, week_pct: null} persists
• Once snapshot crosses threshold, manual chat send gets WS send_refused
• Scheduled task fires while over → run row with status='skipped_quota'
• In-flight session NOT terminated when threshold crossed mid-stream
• Lowering threshold below current util immediately pauses (UI shows ⚠ warning before Save)

🤖 Generated with Claude Code