feat(agents): add Grok usage collector

[pmcclelland]

Why

Grok is already a first-party default coding agent (omarchy default agent grok), but the agents bar widget never appears for it. Collectors are discovered from $OMARCHY_PATH/bin/omarchy-agent-usage-*; Claude, Codex, and Fireworks ship one, Grok did not. On a machine that only uses Grok the panel stays hidden, even when there are weeks of local session history and a live SuperGrok weekly allowance.

The panel itself does not need QML changes. It already watches whatever JSON records land in ~/.local/state/omarchy/agents/usage/. This PR adds the missing collector plus the optional mark and docs so that file appears.

What it shows

Once omarchy-agent-usage-grok has written grok.json, the existing panel grows a Grok tab with:

• Plan label (e.g. SuperGrok Plus)
• Weekly credit-pool meter and reset time
• Grok Build slice of that same week (the coding-agent product, not chat/imagine/tasks)
• Tokens by day for the last week, and tokens by model

Verified on a live SuperGrok Plus session: Weekly 5% (reset in ~5d 15h), Grok Build 4%, local history for grok-4.6.

How the numbers are made

Local stats come from $GROK_HOME/sessions (default ~/.grok/sessions/<cwd>/<id>/updates.jsonl). Grok records billed usage on turn_completed rows, not on events.jsonl / chat_history.jsonl.

• Each distinct prompt_id is one prompt; duplicates in the same file are ignored
• session_kind / session_relationship values that start with subagent are skipped so parent totals are not counted twice
• Token buckets stay mutually exclusive: input, output (including reasoning), cache read, cache write
• The -build model suffix is stripped for display (grok-4.6-build → Grok 4.6)

Limits come from the same billing endpoint Grok's own /usage command uses, authenticated with the OAuth session in ~/.grok/auth.json:

• GET https://cli-chat-proxy.grok.com/v1/billing?format=credits → creditUsagePercent (weekly pool) and productUsage[GrokBuild].usagePercent
• GET https://cli-chat-proxy.grok.com/v1/user?include=subscription → subscriptionTier (SuperGrokPlus → SuperGrok Plus)
• Expired access tokens are refreshed via https://auth.x.ai/oauth2/token and written back to auth.json at 0600
• A failed or unreachable probe keeps the last still-open cached window and still shows local token stats

Without a signed-in Grok CLI the collector still prints a valid hidden-by-default record (ready: false, Waiting for auth) so the update runner has something to write.

Files

File	Change
bin/omarchy-agent-usage-grok	New hidden collector (omarchy agent usage-update already globs omarchy-agent-usage-*)
shell/plugins/agents/assets/grok.svg (+ -light twin)	Optional mark from the official Grok favicon; the bar glyph still stands in without them
shell/plugins/agents/manifest.json	Enable grok by default and mention it in the widget description
shell/plugins/agents/README.md	Document the Grok collector, GROK_HOME, and providers example
manual/17-ai.md	List Grok next to Claude, Codex, and Fireworks
test/shell.d/agent-usage-grok-scanner-test.sh	Scanner + billing-shape tests

Test plan

• bash test/shell.d/agent-usage-grok-scanner-test.sh — 8 assertions: empty record without auth, one-count per prompt_id, subagent skip, exclusive token buckets, SuperGrok Plus label, weekly 5 → 0.05 meter, Grok Build slice only (chat/imagine ignored)
• Live panel on Omarchy 4.0.2 with Grok as the default agent: icon appeared, SuperGrok Plus, Weekly 5%, Grok Build 4%, tokens by day and model
• ./test/all on CI

Related: #7200, #6902, #9924, #9840.