Summary

WSL2 ships with the Hyper-V Firewall DefaultInboundAction=Block (Microsoft's current default with mirrored networking). xAI's OAuth redirect to http://127.0.0.1:56121/callback is silently dropped before reaching the WSL VM. xAI then renders its "Could not establish connection" fallback page showing the auth code as text — but stock Hermes has no way to accept that code, so the listener times out and the code is orphaned.

This PR adds the --code-flag-equivalent that PR #27305 mentioned was needed but not yet shipped.

Changes

• New --paste-code flag on hermes auth add (auto-enabled when --no-browser is set, so the existing remote-session UX gets the fix for free)
• _xai_wait_for_callback spins up a daemon thread that reads one line from stdin and feeds the pasted code into the same callback handler via internal HTTP (127.0.0.1:<port>/callback?code=...&state=...)
• First-write-wins: whichever channel (browser redirect or stdin paste) delivers a code first short-circuits the wait loop
• No behavior change when the flag is absent — strict superset

UX

hermes auth add xai-oauth --type oauth --no-browser --paste-code
# → Open this URL: https://auth.x.ai/...
# → Waiting for callback on http://127.0.0.1:56121/callback
# → If your browser shows "Could not establish connection" with a code,
# → paste the code here and press Enter (or wait for browser callback):
# (user pastes "abc-123-xyz", hits Enter)
# → Login successful!

Why it works

The stdin reader doesn't bypass any OAuth security — the pasted code still flows through the same _make_xai_callback_handler that the browser redirect would hit, which validates state and exchanges the code via PKCE. We just route the code over loopback inside the same kernel that's running the listener, avoiding the Windows-side firewall entirely.

Affected platforms

• WSL2 + Hyper-V Firewall (this PR's primary target)
• GCP Cloud Shell / GitHub Codespaces / AWS Instance Connect — browser-only consoles where there's no ssh -L tunnel option (parallel solution to OAuth loopback login broken for remote/browser-based consoles (GCP, Codespaces, etc.) #26923)
• Anywhere a tunnel isn't possible (corporate proxies, ZTNA agents, etc.)

Refs

• PR docs(README): link community fix for xAI OAuth callback failure on WSL2 #27305 (jett22JOE) — README callout linking community wrapper; mentions a follow-up PR for --code. This is that PR.
• Issue [Bug]: xAI OAuth loopback on macOS: local callback received, but Hermes times out #27385 (Jind0la) — macOS variant where the browser callback succeeds locally but Hermes still times out. The stdin-paste path is a clean fallback for this and similar edge cases.
• Issue OAuth loopback login broken for remote/browser-based consoles (GCP, Codespaces, etc.) #26923 (welliv) — remote-console OAuth flow; this is a complementary approach to the manual-code helper proposed there.

Test plan

• hermes auth add xai-oauth --type oauth --no-browser --paste-code on Beelink WSL2 — paste-from-fallback-page completes auth, auth.json populated
• hermes auth add --help shows the new --paste-code flag
• Backwards compat: hermes auth add xai-oauth --type oauth without --paste-code behaves identically to before
• First-write-wins: if both browser callback AND stdin paste arrive, the handler short-circuits on whichever lands first
• No stdin available (non-TTY background process): paste reader skipped silently, listener runs as before

🤖 Generated with Claude Code