Sandbox BYO-Vercel billing (user_vercel_project): dead mode with broken auth — clean up now, keep the door open

[charlesrhoward]

Summary

user_vercel_project sandbox billing (BYO Vercel compute) is shelved but half-buried, and its auth foundation is broken. We want to keep the idea (bring your own compute is a good PAYG story) but it is not happening yet — so the codebase should stop pretending it might turn on, and the one live path that shares its broken auth needs a fix.

Current state (verified Aug 4)

1. Mode is shelved by design. #597 hid the BYO-Vercel UI and gated user_vercel_project behind NEXT_PUBLIC_SANDBOX_DISABLE_USER_BILLING; #598/#599 finished the flag mechanics.
2. It cannot work even if the flag flips. Launch would authenticate Sandbox.create() with the user's stored OAuth token (getOAuthToken(userId, "vercel")), but our Vercel OAuth flow requests only identity scopes — openid email profile offline_access (app/api/auth/vercel/route.ts:42). That token has no Vercel API access and cannot create sandboxes on the user's project/team. Un-gating the mode today would just produce auth failures at launch.
3. Live collateral bug: lib/vercel/env-vars.ts uses the same identity-scoped token for REST calls to pull env vars from a user's linked Vercel project (getUserVercelToken → Bearer header). If env sync from Vercel projects is supposed to work, it is likely failing silently behind warnAndReturnFallback. Grep prod logs for the env-sync warning prefix to confirm.
4. Dead plumbing spans ~6 files: lib/sandbox/billing.ts (mode resolution), lib/vercel/target-resolution.ts, lib/vercel/reconciliation.ts, lib/vercel/reconcile-links-runner.ts, lib/vercel/validation.ts, plus branches in lib/sandbox/reaper.ts, summary.ts, debug-presenter.ts, readiness-reconciliation.ts.

Proposed fix (keep the door, remove the theater)

• Confirm whether Vercel-project env sync is broken in prod (identity-scoped token vs REST API); fix or explicitly disable that path with a clear settings message.
• Decide: rip out user_vercel_project plumbing now, or reduce it to the enum + a NOT_IMPLEMENTED guard at launch. Either way, no half-alive branches in reaper/reconciliation.
• Remove or annotate the kill-switch so nobody "enables" a mode that cannot authenticate.
• Leave a short design note (docs/ or code comment at the enum) recording what real BYO compute requires: an API-capable Vercel token grant with project scope — i.e. a different integration, not a flag flip.
• Marketing/copy stays silent on BYO compute until this ships for real (already scrubbed from the copy rewrite).

Non-goals

Building BYO compute now. This issue is cleanup + the env-sync auth fix + preserving an honest path to do it later.