fix(copilot): defer keychain auth lookup

[rNoz]

Description

Defers macOS Keychain and Linux Secret Service OAuth discovery until non-platform Copilot credentials fail during headroom wrap copilot --subscription. This prevents needless macOS Keychain prompts when saved Headroom OAuth authentication already resolves. Closes #2738.

Type of Change

• Bug fix (non-breaking change fixes an issue)
• New feature (non-breaking change adds functionality)
• Breaking change (fix or feature would cause existing functionality change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• headroom/copilot_auth.py: split subscription credential resolution into a non-platform pass and a platform-secret-store fallback pass.
• tests/test_copilot_auth.py: cover successful saved-token resolution without Keychain access, Keychain fallback, and duplicate-token avoidance.
• tests/test_copilot_subscription_smoke.py: preserve the generic-token-to-Keychain fallback smoke test for the new two-pass candidate-discovery API.
• Merged current upstream main to pick up the audited cryptography 50.0.0 lock; latest head is ec306470.

Testing

• Unit tests pass for changed behavior
• Linting passes
• Type checking passes
• New tests added
• Manual testing performed

Test Output

UV_NO_SYNC=1 uv run --no-sync pytest tests/test_copilot_auth.py tests/test_copilot_macos_keychain.py tests/test_copilot_linux_secret.py tests/test_copilot_subscription_smoke.py tests/test_cli/test_wrap_copilot.py -q
158 passed

UV_NO_SYNC=1 uv run --no-sync ruff format --check .
1333 files already formatted

UV_NO_SYNC=1 uv run --no-sync ruff check .
All checks passed

UV_NO_SYNC=1 uv run --no-sync mypy headroom
Success: no issues found in 508 source files

Real Behavior Proof

• Environment: macOS 26.5 (25F71), Python 3.14.5, Headroom topic worktree rnoz/fix-copilot-keychain-fallback, GitHub Copilot CLI 1.0.77, saved Headroom OAuth credential present.
• Exact command / steps: commands below

cd /Users/rnozal/projects/headroom/.worktrees/fix-copilot-keychain-fallback
UV_NO_SYNC=1 uv run --no-sync headroom wrap copilot --subscription --port 8795 -- --model claude-opus-4.8 --prompt 'Reply with exactly: OK' --silent --allow-all-tools --allow-all-paths --allow-all-urls

• Observed result: the command printed OK, launched against http://127.0.0.1:8795/p/fix-copilot-keychain-fallback/v1, and no macOS Keychain authorization dialog appeared.
• Not tested: an expired or revoked saved token falling back to a real macOS Keychain item, Linux Secret Service, Windows Credential Manager, and GitHub Enterprise credential hosts.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review
• I commented my code, particularly in hard-to-understand areas (not needed, the code is self-explanatory)
• I made corresponding changes to documentation (not needed, no user-facing API changes)
• My changes generate no new warnings
• I added tests to prove my fix is effective
• New and existing relevant unit tests pass locally
• I did not edit CHANGELOG.md

Screenshots (if applicable)

Not applicable.

Additional Notes

The full pytest -q run was attempted after installing the missing litellm test dependency. It reached execution but failed in five unrelated existing tests: four Kompress readiness tests depended on an already-initialized PyTorch backend, and one Windows-only selector-loop test failed under Python 3.14 on macOS. The changed Copilot suites and the live wrapped-Copilot proof passed.

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Missing required section Runtime Rollout Safety.

Please update the PR body, or move the PR back to draft while it is still in progress.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[vercel]

@rNoz is attempting to deploy a commit to the Headroom Labs Team on Vercel.

A member of the Team first needs to authorize it.

[JerrettDavis]

Reviewed the latest merged head adversarially. The two-pass discovery preserves existing candidate precedence, defers only prompt-capable macOS/Linux stores until non-platform credentials fail, avoids duplicate token exchange, and retains off-platform fallbacks. After merging current main, 158 focused auth/platform/wrapper tests and targeted Ruff checks pass locally. The prior dependency-audit failure was from the older cryptography 48.0.1 lock; this head carries main's audited 50.0.0 lock. I found no correctness or security blocker.

[JerrettDavis]

Re-reviewed the latest main merge. No feature source follows the previously approved two-pass credential discovery: saved/non-platform credentials retain precedence, prompt-capable macOS/Linux stores remain deferred, and duplicate token exchange is avoided. The branch is clean and mergeable with the current audited dependency baseline. No blocking correctness or security finding.

[rNoz]

@chopratejas ping for merge when you have a moment. Approved by @JerrettDavis, rebased onto current main today, CI fully green, mergeable: clean.

One data point consistent with this PR's premise: on a machine with multiple Copilot-capable keychain entries, a wrap launch without --subscription can end up bound to the copilot-language-server integrator, whose model allowlist 400s third-party models (kimi-*) that work fine once the correct token is resolved. Deferring the keychain lookup, as this PR does, avoids that path.

#2352 and #2723 are also approved, green, and clean if you are doing a sweep.