mopac-pmo/inbox-work/TASK-20260829-0500-quota.md

TASK: Quota monitoring + back-pressure + usage mgmt + resource gate (Redmine 490+491)

Context

Charles's spec of record: docs/SPEC-20260829-charles-brief.md (READ IT FIRST, esp. "It's a marathon" + Roadmap 1). Last night the z.ai quota wall killed two dispatched turns at 19:00 — this system prevents that class of failure and maximizes the flat-rate plan 24x7 (legacy plan ends 9/22). Redmine tickets: 490 (quota) + 491 (resource monitor).

Scope — internal/quota + harness quota + loop integration

1. z.ai usage polling: research the z.ai coding-plan usage/limits endpoint (it exists per Charles; find the API surface from public docs
   • the z.ai provider behavior we already see). Poll on interval; parse buckets/limits/reset times; expose QuotaSnapshot (struct: per-bucket used/limit/window-reset).
   • Auth via key_ref (never logged, same discipline as keyproxy).
   • If the endpoint proves unreachable/undocumented: build against a documented interface + fake server, flag LIVE VERIFICATION as open.
2. Central state decision (Charles leaves it to us): Redis container vs LiteLLM-native (postgres spend tracking already live at 192.168.3.78:4001). Decide with rationale in the REPORT; implement the chosen one. Requirements: multiple harness instances (9 accounts, 2 hosts) share quota state; redis (if chosen) runs as a docker container on this host, config in harness.toml, no host packages.
3. Back-pressure in the loop (internal/loop): before dispatching a turn, consult quota snapshot + schedule:
   • Peak window (config, default 0100-0500 CST — VERIFY empirically if possible; Charles sleeps 2300-0500): restrict to flash-tier classes; defer heavy classes with a logged reason; prefer LLM-lite work.
   • Quota nearly exhausted: defer + surface status; never hard-fail the loop.
   • Schedule + thresholds all in [quota] harness.toml section (TZ-aware, CST default).
4. Resource gate (ticket 491): read-only system monitor (load avg, mem available, disk free, IO delay from /proc + /sys) with configurable busy thresholds; loop defers dispatch when busy. cgroup enforcement is deploy-time — document the runbook section only.
5. Usage accounting: per vertical/class token+model accounting into the JSONL state (extend loop state) — feeds the eventual per-instance Discourse usage reports.
6. TDD red/green: quota parser, schedule logic (peak/offpeak across TZ edges), back-pressure decisions, resource thresholds — table-driven + fake clock. Docker dev discipline. Docs standard (README + config table). Push to origin main.

Deliverable

REPORT-20260829-0500-quota.md in ~/.coordinate/inbox-pmo/: the Redis vs LiteLLM decision + rationale, endpoint findings, config surface, test results, and how the loop now behaves at quota exhaustion (the 19:00-wall scenario replayed as a test).

ADDENDUM (redispatch, ~05:10 CST)

• Previous attempt died on a sourcegraph.com timeout — do NOT use sourcegraph; research the z.ai usage endpoint via direct fetch of z.ai docs / the API itself.
• BE QUOTA-LEAN (weekly bucket at 93%): minimal exploration, write code in large correct chunks, one test pass, no gold-plating, finish and report.