PENDING: feat(hermes-agent): add usage rollups, budget policies, alerts, incidents, and retention jobs #677

Parent epic: #668
Depends on: #672, #675, #676

Context

OpenCode Go limits, model prices, and catalogs can change. Hermes/provider responses may expose token usage but AWCMS-Mini has no guaranteed authoritative OpenCode account-quota API. Operations must distinguish provider-reported data, locally observed usage, configured tariff estimates, and unknown values.

Objective

Add provenance-aware usage rollups, configurable budget policies, alert/incident records, and privacy-safe retention/purge jobs.

Scope

Tables

• awcms_mini_hermes_usage_rollups
• awcms_mini_hermes_budget_policies
• awcms_mini_hermes_incidents

Usage provenance

Every metric is tagged as one of:

• provider_reported
• hermes_reported
• locally_observed
• configured_estimate
• unknown

Never label a local estimate as provider billing truth.

Policies and jobs

• Per tenant/agent/model warning and critical thresholds.
• Configurable windows including five-hour, weekly, monthly, and custom operational windows; defaults must not pretend to mirror a live provider contract.
• Versioned tariff/config metadata with effective dates.
• Rollups by tenant/agent/model/channel/source and time window.
• Alert/incident types for unavailable agent, auth failure, model mismatch, repeated timeout, circuit open, Telegram mismatch, budget warning/critical, and telemetry stale.
• Acknowledgement/resolution with actor, reason, and audit.
• bun run hermes:usage:rollup
• bun run hermes:telemetry:purge
• Retention defaults for health snapshots, run events, usage, and incidents.

Privacy/security requirements

• No prompts, responses, memory, Telegram content, raw credentials, or full upstream error bodies in rollups/incidents.
• Rate/volume alerts cannot leak cross-tenant counts.
• Purge is idempotent, bounded, observable, and self-audited.
• Retention configuration enforces safe minimum/maximum ranges.
• Incident notification uses existing provider-neutral email/outbox only if configured and must not block collection.

Acceptance criteria

• Dashboard/API clearly identifies metric provenance and stale/unknown status.
• Missing provider usage is represented as unknown, not zero.
• Budget policies are tenant-scoped and RLS-protected.
• Threshold evaluation is deterministic and safe to rerun.
• Incident creation is deduplicated/idempotent.
• Rollup/purge jobs isolate tenant failures and respect retention policy.
• Tests cover window boundaries, tariff version change, missing usage, incident deduplication, RLS, purge, and secret redaction.
• OpenAPI/AsyncAPI, job descriptors, security readiness, docs, and changeset are updated.
• bun run check passes.

Out of scope

• Claiming to replace OpenCode billing/account dashboards.
• Automatic subscription purchase/top-up.