feat(usage-queue): dev-gated usage-limit simulation control for demos

[aterrylu]

Why

Follow-up so the queue-send-on-usage-clear feature (#232) can be seen working without waiting hours to actually hit a real limit. Requested by Terry: drive the real dashboard button + watch a real agent auto-submit, on demand.

What

POST /api/usage-queue/_simulate?state=capped|cleared|off sets an in-memory usage override that getRateLimits() returns verbatim — so the dashboard usage panel and the queue watcher both see the simulated value — then invalidates the usage cache and kicks an immediate queue evaluation (no 60s poll wait).

• capped → 100% on the 5-hour window (button shows a ~2h ETA; armed panes latch seenBlocked)
• cleared → a small non-zero below the queue's exit threshold (the high→low edge fires armed panes)
• off → clears the override, resuming real usage reads

Safety: gated behind AUTONOMOS_ENABLE_USAGE_SIMULATION. The endpoint 404s and sets nothing in normal/prod runs, and the override code path is never reached unless the endpoint sets it.

Demo runbook

# 1. Run the dev server with simulation enabled
AUTONOMOS_ENABLE_USAGE_SIMULATION=1 <your usual dev start command>

# 2. In the dashboard: spawn/select an agent, type a prompt into its input box, DON'T send.
#    Click the bottom-right hourglass to arm the pane.

# 3. Simulate hitting the limit (button shows "queued · ~2h13m"):
curl -X POST "http://localhost:<port>/api/usage-queue/_simulate?state=capped" \
  -H "Cookie: autonomos_token=<token>"

# 4. Simulate the limit clearing — the agent auto-submits the buffered prompt:
curl -X POST "http://localhost:<port>/api/usage-queue/_simulate?state=cleared" \
  -H "Cookie: autonomos_token=<token>"

# 5. Reset back to real usage:
curl -X POST "http://localhost:<port>/api/usage-queue/_simulate?state=off" \
  -H "Cookie: autonomos_token=<token>"

The order matters: arm → capped → cleared (the pane must observe "blocked" before a clear can fire it — same as the real flow).

Testing

• Scanner: override short-circuits getRateLimits (a throwing fetcher proves no network), and clearing it resumes real reads.
• Route: 404 + no-op when the flag is unset; sets capped/cleared overrides when enabled; off clears; invalid state → 400.
• Full suite green: server + 254 dashboard.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UpGRD3fxgWmCKyp9nZtrQs

[nox-0x]

Approving — clean dev-gated demo control, well scoped and tested.

The design is tight: the override short-circuits getRateLimits before the cache so an in-flight real fetch refilling cached can't displace it, the route is double-gated (AUTONOMOS_ENABLE_USAGE_SIMULATION env + the existing /api/* requireAuth middleware), and tick()'s early-exit on armed.size === 0 keeps the immediate-kick a no-op when nothing is queued. Tests cover gate-off → 404, capped/cleared/off transitions, bogus state → 400, and the cache short-circuit (proven with a throwing fetcher).

Minor non-blocking note for a follow-up if it ever matters: !!process.env.AUTONOMOS_ENABLE_USAGE_SIMULATION treats =0/=false as enabled. Conventional gotcha but irrelevant here since the flag is set explicitly during demos.