fleet:request — Balanced token utilization: auto-spend idle quota on follow-up tasks

[sahajamoth]

Federation Request from Fleet v0.8.1

Problem

Anthropic subscriptions have rolling quota windows (5-hour, 7-day). Most users chronically underutilize — working in bursts, leaving large quota gaps overnight and between sessions. Unused tokens expire when the window rolls forward.

Vibe already tracks utilization via GET /api/oauth/usage but only uses it reactively (pause on breach). The opportunity: proactively fill idle capacity with valuable work.

Proposal: Quota-Aware Auto-Scheduling

1. Idle Capacity Detection

Extend _provider_auto_unblock_loop to detect idle capacity:

headroom_5h = 1.0 - utilization.five_hour   # e.g., 0.77
headroom_7d = 1.0 - utilization.seven_day   # e.g., 0.69

if headroom_5h > 0.40 and headroom_7d > 0.30:
    suggest_or_dispatch_followups(available_budget)

2. Follow-Up Task Queue

Fleet produces structured follow-ups (v0.8.1):

• Officer findings at critical/warning severity
• Long-tail items promoted when 3+ point at same module
• Explicit crew follow_ups recommendations

These accumulate in .fleet/tasks/*/follow-ups.yaml. Vibe reads this queue, prioritizes by severity and age, and dispatches during idle windows.

3. Three Modes

# vibe.yaml
auto_utilization:
  mode: suggest          # suggest | auto | off
  min_headroom_5h: 0.40
  min_headroom_7d: 0.30
  max_auto_cost_usd: 3.00
  sources:
    - fleet_follow_ups
    - fleet_long_tail
    - deviation_checks
    - backlog
  quiet_hours:
    - "22:00-08:00"
  notify: desktop

• suggest: Surface notification: "77% headroom, 3 follow-ups pending. Run vibe auto-spend"
• auto: Dispatch automatically, show toast. Jobs tagged auto_utilization: true
• off: Disabled

4. Smart Scheduling

• Never use more than half the headroom (leave room for manual work)
• Prefer jobs that fit within window reset timing
• Manual work always takes priority over auto-dispatched work
• Respect quiet hours
• Cost estimation via budget profiles

5. Utilization Dashboard

Quota Utilization (last 7 days)
  ████████░░  78% average 5h utilization
  ██████░░░░  61% average 7d utilization
  Estimated waste: ~$12.40/week
  
  Auto-spend this week: 3 jobs ($4.00)
  Pending follow-ups: 5 (est. $8.50)

Implementation ask (vibe side)

Component	Change
worker.py	Idle capacity detection in auto-unblock loop
server.py	GET /auto-utilization/status, POST /auto-utilization/dispatch
features.py	Read Fleet follow-ups, create auto-dispatched jobs
config.py	auto_utilization config section
CLI	vibe auto-spend [--dry-run], vibe utilization
Desktop	Utilization dashboard, auto-spend notifications
anthropic_usage.py	Historical utilization snapshots for trend analysis

Why this matters

The gap between "what you pay for" and "what you use" is pure waste. This turns that waste into value — critical bugs get fixed, tech debt gets investigated, docs get updated — all during hours when tokens would expire unused. The combination of vibe (quota state + job queue) and Fleet (structured follow-ups with priority) makes this uniquely possible.

Full spec: https://github.com/sahajamoth/fleet/blob/master/.fleet/federation/outbox/2026-04-04-vibe-balanced-token-utilization.md