Grok Auth And Quota

Every lane runs the same grok binary against the same $GROK_HOME (default ~/.grok) and the same xAI quota. T3 Code spawns it as grok agent stdio (ACP) for the grok provider instance; a headless sidecar runs grok -p. The transport differs — the auth file, the billing, and the failure codes below do not.

Invocation is not this skill's job. Under t3-dispatch, T3 Code owns the process, session, and permissions: pick the grok row in docs/agents/delegation.md. This skill is what to do when that run comes back red.

Read the failure code before you touch anything

• 401 — missing or invalid authentication. Real auth problem; continue to the gate.
• 402 Payment Required (Grok Build usage balance exhausted) — quota, not auth. The credential is valid and there is nothing to recover: no probe, no rotation, and never grok login. Logging in again cannot buy quota, and it risks a working auth file to fix a billing condition. Read the reset time from the provider usage window and route the task to another delegation.md row until then.
• 403 permission-denied — xAI rejected the selected credential or team for that endpoint. Wrong principal/policy, a stale cloud seed, or transient provider-side state. It does not by itself prove a lapsed subscription.

Auth precedence in the CLI: per-model api_key → per-model env_key → active session token → global XAI_API_KEY. A plain global key does not override a working OAuth session. Treat auth.json as an opaque whole file: never extract, merge, or document its fields.

Empty output is a failure to diagnose, never an empty answer

A failed run still exits the JSON contract. It prints {"type":"error","message":"…"} with exit 1 and carries no .text and no .stopReason. A caller that reads only .text gets null and reports "no assistant output" — indistinguishable from a model that said nothing. Observed 2026-08-04: a quota exhaustion presented as a mystery DOA for hours.

Check .type before .text. The reason is always in .message. Exit code cuts both ways: a refusal or tool loop exits 0 with real .text, so exit 0 is not proof of a finished reply either — check .stopReason is end_turn (or the older EndTurn).