[cliffhall]

Closes #2410

What changed

• clients/cli/src/open-url.ts: openUrl now races open() against a timeout (OPEN_URL_TIMEOUT_MS, 5s). open 10.x resolves as soon as it has launched the opener, but before that it probes the environment (WSL default browser, PowerShell path). On a headless box or in a container any of those can stall. The OAuth flow does not wait on this call (CallbackNavigation discards the promise), but without a timeout a stalled open never settles, so the fallback line below would never print. The timer is cleared on every path.
• clients/cli/src/cli-oauth-navigation.ts: the URL was already printed before the open, and a failure was swallowed silently. Now a failed or timed-out open writes one more stderr line: Could not open a browser automatically (<reason>). Open the URL above manually. The issue asked for a "print the URL as a fallback" path, and that already existed because the URL is always printed first. This change makes a failed open visible instead of looking like the flow is waiting on a browser.
• clients/cli/README.md: the MCP_AUTO_OPEN_ENABLED row now describes this behavior.

Nothing changes when the open succeeds. The TUI has its own openUrl (clients/tui/src/utils/openUrl.ts); it is out of scope because the issue is filed against the CLI.

Tests

• open-url.test.ts: a rejection propagates, a never-settling opener times out (fake timers), and the timer is cleared after a successful open.
• cli-oauth-navigation.test.ts: the old "swallows failures" case now asserts the exact fallback line. A new case covers a non-Error rejection.

npm run local:gate passed locally. There is no UI change, so no screenshots.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟢 Approval recommended

The behavior is correctly implemented and tested; only a non-blocking documentation correction remains.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify timeout purpose: OAuth flow does not await openUrl · New

What changed in this PR

Adds bounded CLI browser opening and a visible manual fallback for OAuth.

Changes:

• Adds a five-second timeout to openUrl.
• Reports browser-open failures to stderr.
• Documents and tests timeout/fallback behavior.

File	Description
clients/​cli/​src/​open-url.ts	Adds the browser-open timeout.
clients/​cli/​src/​cli-oauth-navigation.ts	Prints manual-open guidance on failure.
clients/​cli/​README.md	Documents fallback behavior.
clients/​cli/​__tests__/​open-url.test.ts	Tests rejection, timeout, and cleanup.
clients/​cli/​__tests__/​cli-oauth-navigation.test.ts	Tests failure messages.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[cliffhall]

Copilot round 1 — 1 finding (low), no suppressed comments.

• open-url.ts timeout rationale was wrong: the OAuth flow does not await openUrl (CallbackNavigation discards the promise). Fixed in f3e7c66. The comment now says the timeout exists so a stalled open settles and the manual-open line prints. The PR body is corrected too. The change is comment-only, so behavior and tests are unchanged.

[Copilot]

Copilot review overview

🟢 Approval recommended

The focused implementation satisfies the linked issue and is adequately tested and documented.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Clarify timeout purpose: OAuth flow does not await openUrl

[cliffhall]

Copilot round 2 — clean: no findings, no inline comments, no suppressed block. The round-1 finding is marked resolved. The review loop is closed (exit: first clean round).