Repository navigation
design(pm-stack): browser-dependent quota watchdog — CDP scrape producers that self-repair, escalate to a browser-enabled agent #6031
Description
Directive
Drew, 2026-11-04 ~23:18 CST: for providers whose quota/plan data can only be obtained through a logged-in website (Mistral is the first case), a CDP-driven browser scrape path is accepted — "but we'll need a watchdog agent that knows how to work a browser and can fix it whenever it breaks." If the data relies on a cookie, use the cookie. If self-repair fails, the watchdog triggers a task for a browser-enabled agent to fix it.
Design (landed with this issue)
Full design note: ~/workspace/scratch/mistral-quota-watchdog-2026-11-04/design.md (sandbox workspace). Shape:
- Three parts, all on the laptop: per-provider producer (oneshot, 15-min timer, writes the code#1301 file-export documents
~/atlas/<provider>-export/latest.json+history.jsonl, classifying its own failures), a generic watchdog core (oneshot offset after the gatherer tick; health state + repair ladder + escalation), and the gatherer, which ingests each source via its existingFILE_EXPORTSmachinery (registry currently empty, ingestion code intact) with code#1268 last-known retention. - Health model per source: last-success timestamp, consecutive-failure count, failure class —
session-expired/cookie-missing/endpoint-changed/browser-down/cdp-unreachable/rate-limited/unknown— each mapped to a repair. - Repair ladder, cheapest first, attempt-capped and logged: (0) retain + disk-persisted cooldown (rate-limited only); (1) retry next tick; (2) re-validate/re-extract the session via CDP — primary pattern is the retired Meta producer's in-page fetch, where the cookie never leaves the browser; value extraction is the fallback and lands only in fleet secrets by name; (3) re-login in the browser via the standing Google SSO session ("click in and reset it") — a human-only challenge (2FA / verify-it's-you / passkey) makes the incident human-blocked and surfaces to Drew immediately; (4) escalate to a browser-enabled agent (fleet queue task with the full failure context + one deduplicated GitHub incident issue; auto-close on recovery).
- State on disk, always:
~/.local/state/pm-aggregator/quota-watchdog-state.json, atomic writes. This is the direct application of code#5928's lesson — the watchdog is a oneshot and must not repeat the in-process cooldown/cache mistake. - Cadence: producers
*:0/15, watchdog offset on the same 15-min rhythm as the gatherer. Alerting: silent while self-repair works; Drew hears only human-blocked (immediately) or an escalation unresolved >24 h. - Generality: per-provider adapter files (origins allowlist, data paths in preference order, cookie names, login hints, class map, thresholds). Mistral is adapter test #1; Claude console / Open Design (code#5060) are named later adopters.
- History: health observations feed the existing usage snapshot pipeline (code#4889) once its laptop path bug is fixed; interim is the producers'
history.jsonlconvention — no parallel store.
Position vs existing work
- This is the quota-source specialization of code#1260 (pm-stack SLOs + self-healing: remediation catalogue, attempt caps/cooldowns, escalate only when remediation fails). Its catalogue entries fold back into design(pm-stack): SLOs + self-healing for the PM stack itself — freshness SLOs with error budgets, watchdog remediates before alerting #1260; code#1283 drills should eventually exercise it.
- It revives the retired v1 Meta producer pattern (CDP scrape, code#1301) for the one case the 2026-11-03 "quota is gathered by asking OpenCode" ruling does not cover: no API path exists at the credential class held. Preference order per source stays API → usage-capable token → browser-under-watchdog.
- Division of labor with openchamber#1619: that issue adds the Mistral key-validity provider (presence/validity via API). This program adds the plan usage read id(ci): bench-compare compares medians across different units — a unit change masks a real regression as -99.8% ok (and a zero baseline prints +inf%) #1619 proved the API cannot give. Both land; neither replaces the other.
Open questions (named, per #1260's rule)
- Escalation-unresolved threshold before a NEEDS DREW line: 24 h proposed. Not blocking.
- Recovery of a human-blocked incident: stay silent (closed issue is the record) — proposed.
- Producer source home:
pm-stack/exporters/in this repo (proposed) vs beside the quota module in openchamber.
Implementation split (linked issues)
- Watchdog core: filed as a sibling issue in this repo, linked below.
- Escalation mechanism: filed as a sibling issue in this repo, linked below.
- Mistral adapter test #1: filed in developing-today-forks/openchamber, blocked on the sign-in lane's data-path outcome (Vibe token usage API vs console endpoint + cookie), linked below.
Acceptance criteria
- This design is reviewed and its open questions answered or explicitly deferred.
- The implementation issues linked from this issue exist and carry their own acceptance criteria (this issue carries no implementation work itself).
- The design's remediation-catalogue entries are reflected in code#1260's catalogue (comment or sub-issue link there).
Activity
developing-today commentedon Nov 5, 2026
CODE-1696
dezren39 commentedon Nov 5, 2026
Implementation split filed (this design carries no implementation work itself):
Design note:
~/workspace/scratch/mistral-quota-watchdog-2026-11-04/design.md. Umbrella: #1260 (noted there). Companion reads: #5928, #4889, openchamber#1619.dezren39 commentedon Nov 5, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 5, 2026
🤖 Agent note · done
Triage findings (verified fresh this shift)
held,user/owned,do-not-merge,do-not-auto-editall absent), carrying Drew's 2026-11-04 directive verbatim and a complete design (three parts on the laptop, health/failure-class model, repair ladder, disk state per issue quota: claude read needs cross-tick memory — usage-endpoint 429 (proven) + oneshot gatherer defeats the fetcher's in-process cooldown/cache #5928's lesson, alerting posture). No packet defect — this is one of the best-specified design packets in the current batch.pm-stack/exporters/here vs beside the quota module in openchamber): deferred to the claim of issue impl(pm-stack): browser-dependent quota watchdog core — disk state, failure classes, repair ladder #6032 with the design's own proposal (pm-stack/exporters/in this repo, beside the gatherer's FILE_EXPORTS machinery it feeds) as the default — the decision is cheap to reverse before code lands and should not gate the core's start. None of the three needs Drew unless he wants to override a default; if he does, this comment is the place it will be noticed.