fix(tui): stabilize intro screen layout during startup detection

[bird-m]

Summary

Signed-in users saw four distinct visual states in the ~1-2s after launching the wizard: marketing tagline → welcome-back panel → red Generic glyph with "No framework detected" → green framework glyph with "(detected) · beta". Layout jumped on every transition.

Three root causes, all fixed:

1. Late display-field hydration. userEmail / selectedProjectName were populated by resolveCredentials (async), so the TUI rendered the marketing tagline for ~1s before swapping to the welcome-back panel. Added a sync prefill (prePopulateDisplayFields) that runs inside buildSessionFromOptions and reads the same fields from local cache, gated to interactive mode only. Region is intentionally NOT prefilled — session.region is reserved for explicit user intent, and populating it from cache silently defeats gateAgentSignupArguments / gateCiSignupAcceptToS (would misroute signup into the wrong DC). IntroScreen instead reads the displayed region via tryResolveZone directly (documented carve-out from the useResolvedZone "no disk in render" rule; long-term fix tracked in project_zone_hoist_followup memory).
2. Mid-write state visible to subscribers. runFrameworkDetection performed four separate store mutations (setDetectionResults, setFrameworkConfig, setDetectedFramework, setDetectionComplete) with an emitChange after each. The render window between setDetectionComplete and setFrameworkConfig saw detectionComplete=true && frameworkConfig=null, which fired IntroScreen's useEffect that auto-selects Generic — briefly clobbering the real framework with a red glyph before the real config landed. Introduced WizardStore.applyDetectionResult() that writes all five fields under a single emitChange. Also hardened the autoFallback gate to require positive evidence (detectionResults populated with no winner) instead of trusting the detectionComplete && !frameworkConfig intermediate state.
3. Framework row materialized late. The row was conditional on !detecting && frameworkLabel, so it appeared only after detection settled — a visible vertical shift, paired with a separate "Scanning ~/path…" line that duplicated the Target row. Framework row now always renders; during detection it shows an inline spinner + "Detecting…" in the value column.

The atomic-write discipline is now applied uniformly: detection runner, manual framework picker, and the Generic autoFallback effect all route through applyDetectionResult. An overwriteLabel flag distinguishes the manual-pick case (user explicitly replaces the label) from auto-detection (preserves variant labels like "Flask-RESTX").

Test plan

• pnpm test — full suite passes (3234 tests)
• pnpm lint — clean
• pnpm build — type check + smoke test pass
• Manual: launch pnpm try as a signed-in user; verify the intro screen renders the welcome-back panel + Target/Framework rows in a single stable layout (no marketing-tagline flash, no red-glyph intermediate state, no Framework row materializing late)
• Manual: launch pnpm try as a signed-out user; verify the marketing tagline still appears (welcomeBack is signed-in-only)
• Manual: wizard --auth-onboarding create-account --agent --email X --full-name Y --accept-tos (no --region) on a machine with a stored zone; verify it still emits signup_input_required for --region rather than silently using the cached zone

Notable commits

• 2ff34925 — root layout-stability fix (atomic write + Framework row reservation + prefill)
• fdf56c85 — silent-misroute fix for agent/CI signup (skip prefill in non-interactive modes)
• d35ce512 — keep session.region off the prefill write list; read via tryResolveZone in IntroScreen
• 0b8fa7b1 / 94fa5ad1 — atomic-write discipline extended to autoFallback + manual picker
• 25228cf6 — reverted an earlier "stuck-detection timeout" guard after review surfaced a mid-flow framework-swap race; the existing atomic-write + autoFallback hardening already cover realistic failure modes

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches wizard startup/detection state handling and IntroScreen effects; mistakes could regress framework selection or region gating, though changes are well-covered by new unit/snapshot tests.

Overview
Stabilizes the IntroScreen startup experience by avoiding transient states during framework detection and by reserving the Framework row layout while detection runs.

Framework detection now commits results via a single atomic store.applyDetectionResult(...) call (used by runFrameworkDetection, the Generic auto-fallback, and the manual framework picker), preventing subscribers from seeing partial mid-write state and tightening the auto-fallback gate to only trigger when detection produced non-empty results with no winner.

Adds an interactive-only cache prefill in buildSessionFromOptions to populate display fields (userEmail, selectedProjectName) for the first TUI frame without writing session.region; IntroScreen instead resolves a display-only region via tryResolveZone. Tests were updated/added to pin the new atomic detection contract and the prefill/region invariants, plus snapshot updates for the new inline “Detecting…” UI.

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

[bird-m]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Auto-fallback overwrites manual framework pick on remount
  • Added the !session.frameworkConfig guard (and matching dep) back to the auto-fallback useEffect so a remount after a manual framework pick can't overwrite the selection with Generic.

Or push these changes by commenting:

@cursor push e93b142757

Preview (e93b142757)

diff --git a/src/ui/tui/screens/IntroScreen.tsx b/src/ui/tui/screens/IntroScreen.tsx
--- a/src/ui/tui/screens/IntroScreen.tsx
+++ b/src/ui/tui/screens/IntroScreen.tsx
@@ -204,8 +204,20 @@
   // Atomic apply (same discipline as the runner and the manual picker)
   // keeps every detection-related write going through one path. Reuses
   // the existing detectionResults so the diagnostics table survives.
+  //
+  // The `!session.frameworkConfig` guard is load-bearing: a manual pick
+  // via FrameworkPicker leaves `detectionResults` unchanged (no winner),
+  // so `detectionFoundNothing` stays true after the user chose e.g.
+  // Next.js. Without this gate, a component remount (ScreenErrorBoundary
+  // retry) would re-fire the effect and overwrite the manual selection
+  // with Generic.
   useEffect(() => {
-    if (detectionFoundNothing && !session.menu && !showResume) {
+    if (
+      detectionFoundNothing &&
+      !session.frameworkConfig &&
+      !session.menu &&
+      !showResume
+    ) {
       void import('../../../lib/registry.js').then(({ FRAMEWORK_REGISTRY }) => {
         const genericConfig = FRAMEWORK_REGISTRY[Integration.generic];
         store.applyDetectionResult({
@@ -217,7 +229,12 @@
         logToFile('[intro] no framework matched — falling back to Generic');
       });
     }
-  }, [detectionFoundNothing, session.menu, showResume]);
+  }, [
+    detectionFoundNothing,
+    session.frameworkConfig,
+    session.menu,
+    showResume,
+  ]);
 
   const showContinue =
     session.frameworkConfig !== null && !detecting && !pickingFramework;

_{You can send follow-ups to the cloud agent here.}

[bird-m]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6a0250d. Configure here.}