Get-started residual polish from the Phase 4 re-walk (#842)

[dennisonbertram]

Why

Implements #842 (child of epic #779). The Phase 4 directed verification passed 13/13 gate-state checks, but the naive re-walks still hit real (small) confusions on the guided path itself.

Protected path: "the guided first-run flow reads coherently end to end."

What changed

All changes are in apps/web/app/get-started/get-started-flow.tsx (+ colocated test), matching the issue's declared scope:

1. Step numbering contradiction (finding 1, major) — the step-2 description said "step 1 of 2" under a card numbered 2, reading as a contradiction. Reworded to "First you'll verify your identity, then install the Open Agents GitHub App and choose which repositories it can access."
2. Accordion progress resets on remount (finding 2, major) — step 1 (Vercel account) completion previously depended solely on client click-state (completedSteps), so navigating away (e.g. bouncing off /sessions) and back re-locked/re-collapsed step 2. Step 1 is now also derived-complete whenever a session exists (Boolean(session?.user)), merged with the click-state set, so a signed-in user's step 2 is never re-locked on remount.
3. Step-1 "Continue" semantics (finding 3, minor) — the button just said "Continue" with no indication of what continuing does. Relabeled to "Continue to GitHub".
4. No arrival context on gate redirect (finding 4, major) — requireOnboarded (the /sessions gate from Onboarding gate: sign-in lands new users in /get-started, not an empty console #780) always redirects here with an explicit next param. Users who typed /sessions directly and got bounced saw a bare setup flow with no explanation. Added a one-line banner, "Finish setup to continue to your sessions.", shown whenever next is present; hidden on a direct visit with no next param.
5. Duplicate "Connect GitHub" labels (finding 5, minor) — step header, description, and action button all read "Connect GitHub" in close proximity. Renamed the step-2 header to "GitHub" so only the description ("verify your identity... install the... GitHub App") and the button ("Connect GitHub") remain, and they no longer triple-repeat the same phrase.

Verify-first findings (6–7)

6. Settings Connect click feedback latency — re-read apps/web/lib/auth/run-auth-cta.ts (the shared pending/error/retry contract used by both /get-started and /settings/connections, added in Auth CTA feedback — sign-in and GitHub connect get pending, error, and cancel states #786) and confirmed setPending(true) is called synchronously before await action(). Live-clicked "Connect" on /settings/connections in a real browser and captured the button showing a spinner icon immediately after click (screenshot 05-settings-connect-click-immediate.png). Outcome: verified correct in current code, no change needed. The Phase 4 walker's report likely predates or missed the Auth CTA feedback — sign-in and GitHub connect get pending, error, and cancel states #786 shared-helper refactor.
7. Landing "Preview example" tabs — re-read apps/web/components/landing/app-mockup.tsx and live-clicked between session tabs on the real landing page. Confirmed the entire mockup content (repo path, branch, prompt, tool count, todo progress, typed summary, file list) visibly switches on click, and the active tab gets a highlighted background (screenshots 06-landing-tab-auth-flow-active.png / 07-landing-tab-api-refactor-active.png). Outcome: verified working; no code change made. Per the issue's explicit "In scope" line (copy/state fixes in get-started-flow.tsx + colocated, verification items 6–7 only), no change was made to app-mockup.tsx — a subtle aria-current/indicator enhancement is a reasonable future follow-up but is out of this PR's scope.

Out of scope

• Gate skippability (Onboarding gate blocks GitHub-less users from sandbox-free quick chat (no skip affordance) #838, closed won't-fix — GitHub is mandatory).
• Onboarding completion definition requiring a repo passing verifyRepoAccess (Onboarding completion should require an accessible repo, not just "an installation exists" #792, sequenced after verifyRepoAccess should best-effort re-sync installations before returning no_installation #791 — not implemented in this wave).
• Nav inertness (Hidden landing-nav sign-in cluster is inert (invisible + aria-hidden) (#779) #841).
• Any change to apps/web/components/landing/app-mockup.tsx (finding 7 is verify-first only, per the issue's scope).

How it was verified

Red-first TDD in apps/web/app/get-started/get-started-flow-polish.test.tsx:

bun test apps/web/app/get-started/get-started-flow-polish.test.tsx
# observed red: 5 of 6 new tests failing before the fix (committed as
# "test: add red tests for get-started phase 4 re-walk polish (#842)")

Then the smallest green change, plus an update to one existing assertion in get-started-flow.test.tsx that hard-coded the old "step 1 of 2" copy string.

Full gate, all exit 0:

bun test --isolate apps/web/app/get-started/          # 37 pass, 0 fail
bunx turbo typecheck --filter=web                      # web:typecheck passed
bun --bun run check                                    # 0 warnings, 0 errors (ultracite/oxfmt)
bun --bun run ci                                       # format, lint, typecheck, 759 isolated test files all pass; db:check in sync
git diff --check                                       # clean

Browser evidence (authenticated local smoke, PORT=3041 bun run web, test-auth cookie open_agents_test_user_id=dev-managed-runtime-user):

• /get-started?next=%2Fsessions → arrival banner visible, step 1 shows a completed checkmark on first render (no click needed), step 2 unlocked and titled "GitHub".
• /get-started?step=github (no next) → no arrival banner, confirming the conditional.
• Step 2 expanded → reworded description, single "Connect GitHub" button (no duplicate labels).
• /settings/connections → "Connect" click shows an immediate spinner (finding 6 verified).
• / (signed out) landing mockup → clicking between session tabs visibly switches all content (finding 7 verified).
• agent-browser errors and console showed no unexpected errors; the one auth_cta_failed / 401 on /api/auth/link-social is expected (no real GitHub OAuth client configured in this local worktree).

Evidence quality

Deterministic test coverage (bun test, red-first) for findings 1–5, plus local Agent Browser smoke screenshots for the visible/state behavior and verify-first findings 6–7. Screenshots live in the epic evidence bundle at .context/onboarding-evidence/phase5/842/ in the main checkout (headless gh cannot upload images to this PR body):

• 01-gate-arrival-banner.png — arrival banner + auto-completed step 1
• 02-github-step-expanded.png — reworded copy, single-button label
• 03-direct-visit-no-banner.png — no banner without next
• 04-settings-connections.png — settings Connections page baseline
• 05-settings-connect-click-immediate.png — synchronous spinner on click (finding 6)
• 06-landing-tab-auth-flow-active.png / 07-landing-tab-api-refactor-active.png — landing tab switch (finding 7)

Risk and rollback

Pure client-side copy/state changes in one component (get-started-flow.tsx) plus its tests; no schema, API, auth, or deploy-impacting changes. No migration required. Rollback is a plain revert of this PR's commits — no data or state to unwind, since completedSteps/clickCompletedSteps remain client-only React state.

Reviewer guide

• Start with apps/web/app/get-started/get-started-flow-polish.test.tsx for the new-behavior contracts (findings 1, 2, 3, 4, 5), then apps/web/app/get-started/get-started-flow.tsx for the implementation.
• The one-line diff in apps/web/app/get-started/get-started-flow.test.tsx (finding-1 assertion update) is mechanical — it just points the existing "not-yet-linked, no reconnect copy" assertion at the new wording instead of the old "step 1 of 2" phrase.
• Pay closest attention to the completedSteps merge logic (clickCompletedSteps ∪ derived step-1-from-session) — this is the one piece of actual state-derivation logic in the diff, not just copy.
• Findings 6 and 7 involved no code changes; review the "How it was verified" section above for the reasoning and screenshots rather than a diff.

Follow-up from epic #779.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
open-agents	Ready	Preview, Comment	Jul 3, 2026 5:49pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6343540cca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Open the GitHub step when deriving step 1 complete

When a signed-in user is bounced from /sessions to /get-started?next=%2Fsessions (the gate does not add step=github), shouldAutoOpenGitHubStep is false so activeStep remains 1. This new derived-completion block only adds step 1 to completedSteps; it does not advance/open step 2 after the session arrives from /api/auth/info, so the remount still shows the completed Vercel panel and hides the GitHub panel until the user clicks Continue again—the re-collapse path this change is meant to fix.

Useful? React with 👍 / 👎.