Auth reliability + error handling alignment + request integrity fixes

[numman-ali]

Summary
Numman has been tied up the last couple of weeks, so I handled this on his behalf and consolidated the scattered fixes into one coherent, fully‑tested implementation. This lands the missing headless auth fallback, aligns error handling with OpenCode conventions, maps usage‑limit 404s to retryable 429s, and preserves AGENTS/tool‑call integrity in the request transformer. It also adds OpenCode variants support (modern config) and a cross‑platform one‑command installer that safely updates the global config and clears plugin cache. The result is fewer auth failures, correct retries, no more silent loss of instructions, and an easier install/update path for users.

Fixes / How it’s rectified

• Closes [BUG] Auth flow crashes when xdg-open is not installed in headless environments #83 — Headless OAuth no longer crashes when xdg-open is missing. We now detect missing openers and safely skip spawn, letting users open the URL manually while the callback server stays alive.
• Closes [BUG] Error handling pattern doesn't match OpenCode plugin conventions (#81) #80 — Error handling now follows OpenCode conventions: refresh failures throw; error responses pass through unaltered, so UI behavior is consistent and retry logic works as designed.
• Closes [BUG] Usage limit reached on new MAX models #50 — Usage‑limit 404s are mapped to 429 only when the response body indicates a usage/rate‑limit condition, which unlocks OpenCode’s retry flow without masking real 404s.
• Closes [BUG] Request transformer removes ~/.config/opencode/AGENTS.md #68 — AGENTS.md content is preserved: we protect instruction markers and only filter exact OpenCode system prompts (case‑insensitive signatures), so custom instructions stay intact.
• Closes [BUG] Plugin output "bleeds" into other instances, even when not using OpenAI models #66 — Plugin logging is now gated to debug flags only; no more stdout “bleed” into unrelated sessions.
• Closes [BUG] No tool call found for function call output with call_id #48 — Orphan tool outputs are handled correctly: function_call_output matches function_call and local_shell_call (Codex‑CLI parity); custom_tool_call_output matches custom_tool_call. Unmatched outputs are converted to assistant messages to preserve context rather than dropped.
• Addresses [BUG] Route Error (400 Invalid Session): "Your authorization session was not initialized or has expired" #89 — Added manual URL‑paste login + troubleshooting guidance for “Invalid/Expired Session”; users are directed to generate a fresh URL and, when needed, paste the redirect manually.

Adds / Enhancements

• Adds OpenCode v1.0.210+ variants support with a modern config preset and a legacy config for older versions; request transformer now respects provider‑supplied variant options before falling back to defaults.
• Adds cross‑platform installer/update command: npx -y opencode-openai-codex-auth@latest (global config only, backs up config, clears plugin cache). Includes --legacy for old OpenCode.
• Config templates now default to unpinned plugin entry for “latest” installs, with docs updated accordingly.

PRs re‑implemented (no direct merge)
Supersedes: #84 #81 #52 #88 #86 #59 #63 #73 #90 #91
This PR incorporates the intent of each, with additional edge‑case handling and tests.

Tests

• npm test
• npm run build
• ./scripts/test-all-models.sh

CC / Thanks
@christso @CasualDeveloper @paflopes @connorads @mosfor @paarth-a @code-yeongyu @llajas @aryasaatvik @cau1k
and contributors in the threads:
@daniel-sc @kearygriffin @haininhhoang94 @kim0 @Srini-B @hyprbased @emrosenf @tbrandenburg @jhartumc @ramarivera @mariomeissner @EvanZhouDev @mrairdon-midmark @mkoorn @EvanNotFound @jasonish @igormaneschy @Tarquinen @mikhail-shemelin @junhoyeo @tayiorbeii @ivankazzzz

[junhoyeo]

Congrats on the fix!