fix(passport): silent refresh on expired access — restore the 90-day re-verify UX

[vvillait88]

Summary

Two related bugs in the silent-refresh path were forcing verify-URL prompts every 24h. Confirmed live by reproducing the user-visible flow against martin-estate, fixed, and re-verified end-to-end.

Bug A — attach.ts:48 short-circuited and returned kind: 'expired' BEFORE attempting to use the still-valid refresh_token. Pay's caller (pay.ts) then drove bootstrap reauth via the verify-URL flow, even though a silent exchange would have worked.

Bug B — REFRESH_THRESHOLD_MS = 60 * 1000 (60 seconds). Proactive refresh window was unreachably short on a 24h access TTL — only fired if pay happened to be invoked in the last 60 seconds of the access token's lifetime.

Fix

Restructured attachPassport to evaluate accessExpired and accessNearExpiry up-front, then attempt refresh in either case when refresh_token is still valid. Only after refresh has been tried (or skipped) do we surface kind: 'expired', and only when access is genuinely expired post-attempt — the path that drives bootstrap reauth.

Refresh failures are now graceful when access is still valid: a proactive failure with 30s remaining attaches the existing token rather than driving eager bootstrap. A reactive failure with already-expired access surfaces 'expired' and bootstraps as before.

REFRESH_THRESHOLD_MS bumped from 60s to 5 minutes (clock-skew + on-the-wire-latency headroom for proactive refreshes).

Downstream effects (also in this PR)

expiringSoon predicate — after silent refresh works, every refresh issues a 24h access token, so the existing predicate (access_remaining < 5d) was always true. The "Passport expires soon — run passport login to renew" warning would print on every pay call telling users to do something they don't need to. Tightened the predicate to gate on refresh state: expiringSoon = true only when refresh isn't going to bail us out (no refresh_token, or refresh itself within the 5-day window).

passport status output — was reporting only access-token expiry. Agents reading expires_in_days: 0 would think they had to act when actually 89 days of effective life remained via refresh. Extended the output with silent_refresh_available, refresh_expires_at, refresh_expires_in_days (additive — existing fields unchanged). Same shape extension to passport login output via a shared buildPassportSummary helper.

agent-guide — golden_path step 1 now describes the access + refresh lifecycle explicitly. Auxiliary passport status step describes the new fields and gives an unambiguous instruction: do not surface expires_in_days: 0 as actionable when silent_refresh_available: true.

README.md — passport status row mentions the new fields.

Tests

tests/passport-attach.test.ts rewritten:

• Reactive path — silently refreshes when access already expired but refresh_token still valid (the dominant real-world case)
• Proactive path — refreshes within the 5-min threshold of expiry
• Refresh failure paths — proactive failure with valid access stays attached; reactive failure with expired access surfaces 'expired'
• Legacy / refresh-expired / skipRefresh paths unchanged
• expiringSoon=false with short-lived access + valid refresh (the post-fix case that would've spammed warnings)
• expiringSoon=true when both access AND refresh are within the 5d window (the genuinely-actionable case)

Old tests pinned the broken 60s window and the early short-circuit; new tests cover both paths.

Live verification

End-to-end against the published agents.martinestate.com API:

$ # Force-set passport access expired 1h ago, refresh still valid for 89 days
$ ./dist/index.js pay POST https://agents.martinestate.com/purchase ... --dry-run --json

# stderr: empty (no "Stored Passport has expired" prompt)
# Tokens rotated: opc_old → opc_new, prt_old → prt_new
# silent_refresh_available stays true

Pre-fix: this would have printed Open this URL to renew: and forced a browser click. Post-fix: silent rotation happens transparently.

Test plan

• bun run typecheck clean
• bun run lint clean
• bunx vitest run — 438+ tests pass (4 new on the silent-refresh + expiringSoon paths; existing tests rewritten for the new contract)
• Lefthook pre-commit + pre-push pass
• Live smoke against agents.martinestate.com: forced expiry → silent refresh fires → tokens rotated → no user prompt
• CI green
• Tag v0.1.1 after merge → npm publish to latest dist-tag (no - in version, publish workflow takes the stable branch)

Cross-repo follow-up

Mintlify docs in agentscore/core (docs/integrations/pay-cli.mdx line 141, docs/passport.mdx lines 60 + 76) had pre-existing inaccuracies about the token TTL ("Tokens default to a 30-day TTL" — wrong; was always 24h access + 90d refresh). Will be addressed in a separate core PR.

🤖 Generated with Claude Code