Establish Muse Code quota acquisition and truthful native provider states #522

Description

Franz's October 26 request includes iOS. The ProviderID registry and live refresh registry do not include Muse Code. Its widget publisher and watch coordinator consume iPhone results.

Vendor-advertised contract: the official changelog describes non-inference muse usage in 1.4.13, MSP usage/read and usage/changed for last-seen five-hour/weekly windows, and run.usage with per-model tokens separately from allowance. These capabilities do not prove a current account reading.

Observed by the authorized fleet owner on Home at 05:34 EDT, October 26: pinned Muse Code 1.4.13-R6996.1; one usage --help, then one usage --json with login/auto-update disabled and environment META_API_KEY excluded. Exit 0; allowlisted payload {"schemaVersion":1,"allowance":null}. The observed schema also has reason:string and hint:string; their free-form values were omitted and raw output was not retained. This proves the command ran, not zero usage, entitlement, subscription billing or inference. Tier, billing type, pool/model scope, used/remaining units/values and reset times remain unknown. Native stored credential context can differ from an exported PAYG key. No login, auth-file read, credential transfer, config change or inference occurred; no repeat probe is authorized by this issue.

Sources: Meta subscriptions, Wonder Full availability, authentication precedence, and CLI changelog. A desktop CLI read is not proof of a supported phone authorization-to-quota flow. No such iOS acquisition contract has been verified. Repository setup rules require guided phone setup and forbid token/cookie/JSON import as routine setup. Establish that contract first and record any exact external registration/API availability block; do not promise live quota before it exists. Coordinate source semantics with https://github.com/hemsoft-dev/chief/issues/22.

This is issue intake only. Fleet CLI/provider installation, settings, authorization and inference verification belong to the existing fleet worker. No host setup, secret extraction, private endpoint discovery, purchases or implementation dispatch is authorized by this issue. Preserve existing priorities and protected work. Preserve P0 release work and PR #521. This issue does not schedule or reprioritize implementation.

Desktop source-contract peers: hemsoft-dev/codexbar#273, hemsoft-dev/codexbar-mac#199 and hemsoft-dev/hs-pi-dashboard#70. Their CLI support does not resolve the phone acquisition gate.

Why

Users need the real subscription allowance. Desktop session totals or a PAYG key would give a misleading phone experience.

Goal

Provide a compliant native Muse Code connection where supported, with verified quota semantics and explicit unavailable states wherever acquisition remains unsupported.

Acceptance Criteria

• Accept schema version 1 with nullable allowance. allowance:null with exit 0 is unavailable quota, distinct from genuine numeric zero. Handle reason/hint as untrusted diagnostics with safe allowlisting/redaction, never raw identity-bearing text. Preserve unknown billing/tier/scope/unit/reset fields and handle unsupported schema versions safely.
• Use the subscription name Muse Code. Preserve returned tier, billing mode, observation time, units and pool/model scope. Show Wonder Full only where the source identifies it; a catalog model listing alone proves neither inference nor entitlement. Keep OpenCode Muse Spark and PAYG Meta API pools separate.
• Preserve supported short-window and weekly used/remaining values and reset timestamps, including independent model-specific windows if returned. Verify fraction versus percentage and used versus remaining direction from the pinned contract. Never derive absolute caps from plan multipliers, token totals or the published prompt range; monthly renewal is not a quota reset.
• Missing, stale, malformed or unsupported readings, expired authorization, wrong billing mode, insufficient entitlement, rate limits and transport failures remain distinguishable and unavailable. Missing data never becomes zero, unlimited, a healthy state or spare capacity. Keep valid neighboring windows and last-good timestamps without claiming freshness.
• Keep consumed tokens and model/session activity separate from remaining paid-subscription quota. Any projection, alert or SUS requires the corresponding verified quota, duration, scope and reset; otherwise show unavailable and exclude that score. Never sum the same subscription across machines or models.
• Document an executable, supported iPhone authorization-to-allowance path with account binding and a sanitized production-parser fixture before claiming live support. Handle cancellation, expiration, reconnection and late responses after account switches. Protect credentials in Keychain. Do not require desktop credential export/import, a CLI on iPhone, a PAYG key or undocumented endpoints.
• If the phone acquisition contract remains unavailable, expose that exact capability limit, keep the live quota work explicitly blocked and complete independently testable native state/schema work without fabricating data. This is distinct from Franz's later live account comparison.
• Integrate verified results into account settings, dashboard, history, metric choices, alerts, widget snapshots and iPhone-to-watch/complication publication. Existing saved configurations, old snapshots and other providers remain compatible; widget/watch consumers receive no provider secrets or new provider networking.

Definition of Done

• Add sanitized contract fixtures for measured usage, genuine zero, exhausted allowance, reset rollover, partial/missing fields, malformed units/values, stale cache, PAYG, denied entitlement, expired auth, timeout and rate limiting. Prove token/activity-only data cannot become quota.
• Document the pinned CLI/schema version, field mapping, source freshness and scope, acquisition limits and known unsupported states. Include backward-compatibility coverage for old persisted data and existing providers.
• Complete the repository's applicable quality gates and current-head review. Do not claim live account compatibility from fixtures.
• Cover phone result-to-widget/watch round trips and existing CodexBar Pro access/account rules. Update the changelog and acquisition/unsupported-state documentation. Keep the automatic CI cost ceiling intact.

Validation

• On authorized Apple infrastructure, use the native build/unit, pinned lint and SwiftPM smoke commands in AGENTS.md. Run relevant watch tests if its contract changes; keep costly new checks local or manually dispatched. Do not run the full release UI gate for routine PRs.
• With sanitized fixtures, inspect the full provider-to-dashboard/widget/watch flow for valid, partial, unsupported acquisition, expired auth, exhausted and stale readings. Assert unknown values cannot trigger healthy quota alerts or SUS.
• Franz owns later real-account phone sign-in and comparison; record it as pending without making it a prerequisite for delivering independently validated app work. App registration/acquisition design remains engineering work.
• In the eventual PR, embed current-head screenshots uploaded as GitHub attachments with CLI --attach, proving measured, partial, exhausted, unavailable/auth-error and stale states. Include a short recording for setup/refresh interaction when practical, or state the concrete reason it is omitted. No runtime UI was started for this issue-only research; the provider is absent and protected owners remain active.