fix(oauth): sign-in failed on first launch (oauth flow) (#1689)

[CodeGhost21]

Summary

• Add an OAuth auth-readiness gate that waits for BootCheckGate’s persisted core mode, a successful core.ping, and CoreStateProvider bootstrap before consuming login tokens.
• Start deep-link auth processing when the user clicks Google/GitHub (not only when the callback arrives) so Welcome shows “Signing you in…” and focus handlers do not drop the loading state early.
• Preflight local core startup before opening the system browser on desktop.
• Replace the generic “Sign-in failed. Please try again.” with actionable messages when the runtime is not ready yet.

Problem

Fresh Windows/macOS installs reported Google/GitHub sign-in failing on the Welcome screen with a generic error (#1689). The auth deep-link handler only waited ~1.5s for bootstrap while BootCheckGate was still up or the embedded core had not answered RPC, then called consume_login_token / auth_store_session against an unreachable core.

Solution

Introduce waitForOAuthAuthReadiness() (owned under app/src/components/oauth/) and wire it from desktopDeepLinkListener and OAuthProviderButton. The gate polls until openhuman_core_mode is set, invokes start_core_process for local mode, confirms core.ping, and waits for isBootstrapping to clear. Failures return user-visible guidance instead of proceeding into a doomed RPC path.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• Diff coverage ≥ 80% — focused Vitest coverage run on changed OAuth modules locally; full pnpm test:coverage + pnpm test:rust deferred to CI (no Rust changes in this PR)
• Coverage matrix updated — N/A: behaviour-only change on existing Welcome OAuth flow; no new matrix row
• All affected feature IDs from the matrix are listed in the PR description under ## Related
• No new external network dependencies introduced (mock backend used per Testing Strategy)
• Manual smoke checklist updated if this touches release-cut surfaces (docs/RELEASE-MANUAL-SMOKE.md) — N/A: automated regression only
• Linked issue closed via Closes #NNN in the ## Related section

Impact

• Desktop OAuth sign-in on first launch after the runtime picker.
• No migration or API contract changes.

Related

• Closes Signing in for first time issue #1689

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

• Key: N/A (GitHub Signing in for first time issue #1689)
• URL: Signing in for first time issue #1689

Commit & Branch

• Branch: cursor/a02-1689-signin-failed-first-time
• Commit SHA: 6019ea2

Validation Run

• pnpm --filter openhuman-app format:check
• pnpm typecheck
• Focused tests: pnpm debug unit src/components/oauth/__tests__/oauthAuthReadiness.test.ts src/components/oauth/__tests__/OAuthProviderButton.test.tsx src/utils/__tests__/desktopDeepLinkListener.test.ts (18 passed)
• Rust fmt/check (if changed): N/A — no Rust files changed
• Tauri fmt/check (if changed): N/A

Validation Blocked

• command: pnpm test:coverage and pnpm test:rust (full merge-gate suite)
• error: Not run locally in this session due to runtime cost; CI coverage.yml / test.yml will execute on the PR.
• impact: Diff-coverage gate validated in CI; changed lines covered by new/updated unit tests listed above.

Behavior Changes

• Intended behavior change: OAuth sign-in waits for runtime readiness and reports specific errors when the core is not up yet.
• User-visible effect: First-launch Google/GitHub sign-in should succeed after choosing Local runtime; failures explain setup/runtime issues instead of a generic retry message.

Parity Contract

• Legacy behavior preserved: Successful sign-in still stores session via auth_store_session and routes to /home.
• Guard/fallback/dispatch parity checks: Deep-link openhuman://auth and openhuman://oauth/* routing unchanged; only readiness timing and error copy changed.

Duplicate / Superseded PR Handling

• Duplicate PR(s): none
• Canonical PR: this PR
• Resolution (closed/superseded/updated): N/A

Made with Cursor

Summary by CodeRabbit

• New Features

  • OAuth sign-in now includes a runtime readiness gate and a preflight launch step before opening the browser, with user-facing messages explaining block reasons and recovery steps.
  • Deep-link auth flow respects the OAuth readiness gate but still allows direct-session injection paths.

• Bug Fixes

  • Clearer deep-link auth start/stop behavior and improved error reporting.
  • More robust boot-check dismissal in end-to-end flows.

• Tests

  • Expanded tests covering readiness validation, deep-link handling, and the OAuth startup preflight.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds an OAuth readiness gate that ensures core mode is set, optionally starts the local core (Tauri), verifies RPC reachability, exposes failure reasons and messages, provides a short preflight for browser OAuth launch, and integrates these checks into the OAuth button and deep-link flows with tests and re-exports.

Changes

OAuth readiness gating and integration

Layer / File(s)	Summary
Core OAuth readiness module app/src/components/oauth/oauthAuthReadiness.ts	Implements waitForOAuthAuthReadiness() that polls for stored core mode, starts local core in Tauri/local mode, pings core RPC, and returns { ready: true } or { ready: false; reason } (core_mode_unset, core_unreachable, bootstrap_timeout). Adds oauthAuthReadinessUserMessage() and prepareOAuthLoginLaunch() preflight.
Readiness module test coverage app/src/components/oauth/__tests__/oauthAuthReadiness.test.ts	Vitest suite covering unset core mode, successful readiness (and start_core_process side-effect), RPC unreachable, bootstrapping-to-ready transitions, bootstrap timeout messaging, and non-Tauri behavior.
Gateway re-export for readiness helpers app/src/utils/oauthAppVersionGate.ts	Re-exports readiness functions and types (waitForOAuthAuthReadiness, prepareOAuthLoginLaunch, oauthAuthReadinessUserMessage, and associated types) for centralized access.
OAuth button readiness coordination app/src/components/oauth/OAuthProviderButton.tsx, app/src/components/oauth/__tests__/OAuthProviderButton.test.tsx	Button calls beginDeepLinkAuthProcessing() before startup, awaits prepareOAuthLoginLaunch() in Tauri flows, and invokes completeDeepLinkAuthProcessing() on startup error. Tests assert lifecycle and preflight calls.
Deep-link listener readiness gating app/src/utils/desktopDeepLinkListener.ts, app/src/utils/__tests__/desktopDeepLinkListener.test.ts	openhuman://auth handler now uses waitForOAuthAuthReadiness() (skips when key=auth), surfaces oauthAuthReadinessUserMessage() on block, aborts processing, and tests verify blocked and bypass behaviors.
UI OAuth tests: preflight mock wiring app/test/*OAuth*.test.tsx, app/test/OAuthLoginSection.test.tsx	Multiple provider test suites hoist and reset a mockPrepareOAuthLoginLaunch and mock oauthAppVersionGate.prepareOAuthLoginLaunch to prevent the readiness preflight from blocking tests in jsdom.
E2E helper: BootCheckGate picker regex app/test/e2e/helpers/app-helpers.ts	Updates BootCheckGate dismissal helper to use a shared heading regex (BOOT_CHECK_GATE_PICKER_HEADING_REGEX), improves polling to handle mid-mount timing, and re-checks presence after clicking continue.

Sequence Diagram(s)

sequenceDiagram
  participant Button as OAuthProviderButton
  participant DeepLink as deepLinkAuthState
  participant Preflight as prepareOAuthLoginLaunch
  participant Readiness as waitForOAuthAuthReadiness
  participant Core as Local Core Process
  Button->>DeepLink: beginDeepLinkAuthProcessing()
  Button->>Preflight: prepareOAuthLoginLaunch()
  activate Preflight
  Preflight->>Core: request start (Tauri/local)
  Preflight->>Readiness: short readiness check
  deactivate Preflight
  Readiness->>Readiness: poll core mode & RPC ping
  Button->>Button: Build & launch OAuth URL
  alt OAuth success (deep-link callback)
    DeepLink->>DeepLink: storeSession(...)
  else Error
    Button->>DeepLink: completeDeepLinkAuthProcessing()
    Button->>Button: Set error state
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• tinyhumansai/openhuman#2147: Adds a preflight check before building/opening OAuth URLs (similar preflight pattern).
• tinyhumansai/openhuman#1779: Related changes to E2E BootCheckGate dismissal and use of dismissBootCheckGate helper.

Suggested reviewers

• senamakel

"🐰
I nudge the core awake with care,
A tiny hop, a breath of air.
Poll, prepare, then open the gate —
OAuth starts; the sign-in's fate."

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'fix(oauth): sign-in failed on first launch (oauth flow)' accurately summarizes the main change—fixing OAuth sign-in failures on first launch by adding readiness checks before OAuth operations.
Linked Issues check	✅ Passed	The PR successfully addresses all coding requirements from issue #1689: adds OAuth readiness gate with core mode validation, implements local core startup preflight, confirms core.ping success, waits for bootstrap completion, provides user-facing error messages, and includes comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly related to the OAuth sign-in readiness fix. E2E helper updates (dismissBootCheckGate) support the readiness workflow; test mocks appropriately handle the new preflight step across OAuth provider tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

app/src/components/oauth/__tests__/oauthAuthReadiness.test.ts (1)

25-126: ⚡ Quick win

Add test coverage for the bootstrap_timeout failure scenario.

The test suite covers core_mode_unset and core_unreachable, but is missing a test for the bootstrap_timeout case. This distinct failure mode occurs when the core RPC ping succeeds but isBootstrapping remains true (with no sessionToken) until timeout. Since it has its own user-facing message and represents a real failure path, it should be tested to prevent regressions.

✅ Suggested test case

Add this test after line 117:

it('returns bootstrap_timeout when ping succeeds but bootstrap never finishes', async () => {
  vi.mocked(getCoreStateSnapshot).mockReturnValue({
    isBootstrapping: true,
    isReady: false,
    snapshot: {
      sessionToken: null,
      auth: { isAuthenticated: false, userId: null, user: null, profileId: null },
      currentUser: null,
      onboardingCompleted: false,
      chatOnboardingCompleted: false,
      analyticsEnabled: false,
      meetAutoOrchestratorHandoff: false,
      localState: { encryptionKey: null, onboardingTasks: null },
      runtime: { screenIntelligence: null, localAi: null, autocomplete: null, service: null },
    },
    teams: [],
    teamMembersById: {},
    teamInvitesById: {},
  });

  const result = await waitForOAuthAuthReadiness(600);

  expect(result).toEqual({ ready: false, reason: 'bootstrap_timeout' });
  expect(oauthAuthReadinessUserMessage('bootstrap_timeout')).toMatch(/wait a few seconds/i);
});

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/src/components/oauth/__tests__/oauthAuthReadiness.test.ts` around lines
25 - 126, Add a new test for waitForOAuthAuthReadiness that simulates a
successful core ping but a forever-bootstrapping core: mock
testCoreRpcConnection to resolve { ok: true } and mock getCoreStateSnapshot to
always return isBootstrapping: true, isReady: false with snapshot.sessionToken:
null; call waitForOAuthAuthReadiness with a short timeout and assert the result
equals { ready: false, reason: 'bootstrap_timeout' } and that
oauthAuthReadinessUserMessage('bootstrap_timeout') matches the expected
user-facing text.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@app/src/components/oauth/__tests__/oauthAuthReadiness.test.ts`:
- Around line 25-126: Add a new test for waitForOAuthAuthReadiness that
simulates a successful core ping but a forever-bootstrapping core: mock
testCoreRpcConnection to resolve { ok: true } and mock getCoreStateSnapshot to
always return isBootstrapping: true, isReady: false with snapshot.sessionToken:
null; call waitForOAuthAuthReadiness with a short timeout and assert the result
equals { ready: false, reason: 'bootstrap_timeout' } and that
oauthAuthReadinessUserMessage('bootstrap_timeout') matches the expected
user-facing text.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2d067b72-3b8b-4ae4-8fc0-6cf1e86ab982

📥 Commits

Reviewing files that changed from the base of the PR and between 71526ea and 6019ea2.

📒 Files selected for processing (7)

• app/src/components/oauth/OAuthProviderButton.tsx
• app/src/components/oauth/__tests__/OAuthProviderButton.test.tsx
• app/src/components/oauth/__tests__/oauthAuthReadiness.test.ts
• app/src/components/oauth/oauthAuthReadiness.ts
• app/src/utils/__tests__/desktopDeepLinkListener.test.ts
• app/src/utils/desktopDeepLinkListener.ts
• app/src/utils/oauthAppVersionGate.ts

[YOMXXX]

I could not push the CI fix directly to this PR head branch (CodeGhost21/openhuman:cursor/a02-1689-signin-failed-first-time): GitHub rejected the push with Permission denied to YOMXXX despite maintainerCanModify=true.

I opened #2267 as a replacement PR with this PR's first-launch OAuth readiness fix plus the CI stabilization commits:

• mocks the new Tauri OAuth readiness preflight in the legacy provider tests
• makes the E2E-only window.__simulateDeepLink helper fire-and-forget so WebDriver does not wait on the full auth readiness path
• adds regression coverage for the non-blocking helper behavior

Local validation on #2267 passed: full Vitest, coverage, typecheck, focused ESLint, format checks, and GGML_NATIVE=OFF pnpm rust:check.