fix(auth): structural fallback gate for env-picker so Auth blocks even when pendingEnvSelection gets clobbered

[kelsonpw]

Summary

Three prior PRs each claimed to close the recurring "stuck on Setup with no env-picker" bug:

• fix(auth): clear credentials on needs_user_choice/environment_selection #747 clears session.credentials when resolveCredentials returns needs_user_choice/environment_selection.
• fix(auth): block flow forward-walk while env selection is pending #760 adds the pendingEnvSelection flag and gates every post-Auth show: predicate on it.
• fix(tui): patch nanostores map.setKey to mutate $session in place #762 patches nanostores' map.setKey to mutate $session.value in place so bin.ts's session ref stays aligned with the store.

Each ship passed its unit tests. The bug kept reproducing in user-reported runs: successful run → git reset --hard → rerun → wizard navigates the TUI, stops at ✓ Welcome ─ ✓ Auth ─ ● Setup ←, and hangs.

What the prior PRs got right

The prior diagnoses are all internally consistent and each PR's regression test passes both before and after this PR. They form a layered defense, and they keep working.

What the prior PRs missed

Per-run logs end at [intro] no framework matched — falling back to Generic and nothing fires after. Static analysis of every write to pendingEnvSelection across src/ found exactly one set-true path (applyEnvSelectionDeferral) and four set-false paths (all inside AuthScreen, gated on the user picking an env). None of them explain how the flag flips back to false before the user has interacted with the picker — but the journey stepper's ● Setup ← state requires both Auth.isComplete=true AND pendingEnvSelection=false, so something is clobbering the flag through a path that's not yet pinned down.

The fix

Rather than ship a fourth speculative root-cause fix, this PR adds a structural fallback gate to Auth.isComplete:

!s.pendingEnvSelection &&        // primary gate (PR #760, still load-bearing)
!needsEnvPickStillRequired(s)    // new structural fallback

`needsEnvPickStillRequired` returns true iff EVERY one of these holds:

1. pendingOrgs is non-null (the resolver populated it — distinguishes deferred path from manual API key path).
2. The session has a resolved selectedOrgId and selectedProjectId.
3. That project has ≥ 2 environments with usable API keys.
4. selectedEnvName === null (the user hasn't picked one yet).

When ALL of those hold, Auth.isComplete returns false regardless of pendingEnvSelection's value. The predicate reads observable session shape — no mutable flag for a future regression to clobber.

The flag stays in place as the primary gate; the structural check is a second, redundant safety net. Both point at the same "env still needs picking" state, but one is mutable and one is derived, so any single bug that clobbers the flag is caught by the structural check and vice versa.

Carve-outs

• pendingOrgs === null short-circuits to false so the manual-API-key path (apiKeyNotice resolver outcome) passes through unchanged.
• Single-env projects don't trigger the gate.
• Stale checkpoint selectedProjectId not in pendingOrgs short-circuits to false; the existing stale-org useEffect in AuthScreen handles that case.

Test plan

• New file: src/ui/tui/__tests__/env-picker-repro.test.ts (6 tests covering the smoking-gun scenario plus all four carve-outs).
• Tests fail on origin/main (verified by stashing the flows.ts change and running the test file — both "router parks on Auth" tests fail with expected 'data-setup' to be 'auth').
• Tests pass with the fix.
• All 4112 existing tests still pass (pnpm test).
• Lint clean (pnpm lint).
• Build clean (pnpm build includes smoke test).
• src/utils/wizard-abort.ts untouched.
• No --no-verify used.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes the Auth.isComplete routing predicate, which can alter wizard navigation in auth/onboarding flows; guard conditions and targeted tests reduce but don’t eliminate risk of unintended blocking/advancing.

Overview
Prevents the recurring “stuck on Setup with no env-picker” issue by adding a defense-in-depth structural gate (needsEnvPickStillRequired) to Auth.isComplete, blocking progression when pendingOrgs indicates a multi-env project and selectedEnvName is still unset (while explicitly not affecting manual API-key, single-env, or stale-checkpoint scenarios).

Adds a new Vitest regression suite (env-picker-repro.test.ts) that reproduces the clobbered-flag scenario and asserts the intended carve-outs and unblock behavior once an env is selected.

^{Reviewed by Cursor Bugbot for commit 9ea8487. Bugbot is set up for automated code reviews on this repo. Configure here.}