feat(signup): server-driven field collection and interactive prompts for --signup

[bird-m]

Summary

Replaces the all-or-nothing --signup flag contract with a server-driven field collection flow. When --signup is passed without all required fields, the wizard now collects them interactively instead of hard-failing. The backend can also request additional fields after the initial POST via a needs_information response, enabling a retry loop.

TUI mode

Three new screens slot into the SUSI flow after RegionSelect:

• SignupFullNameScreen — prompts for full name when --signup-full-name is missing
• SignupEmailScreen — prompts for email when --signup-email is missing
• SigningUpScreen — performs the signup POST, handles needs_information responses by routing back to collection screens, and falls through to OAuth on requires_redirect

The flow pipeline in flows.ts gates each screen on whether the corresponding field is present in the session, so screens are skipped when flags are already provided.

Classic mode

New promptForMissingSignupFields helper uses @inquirer/prompts to collect missing region, signupFullName, or signupEmail in the classic (non-TUI) interactive path.

Agent / CI mode

Behavior unchanged — canPrompt: false preserves the existing hard-fail contract. Agent mode exits with AUTH_REQUIRED (exit code 3) and emits an auth_required NDJSON event when fields are missing.

Discriminated result types

performSignupOrAuth now returns a discriminated union (kind: 'success' | 'needs_information' | 'requires_redirect' | ...) instead of AmplitudeAuthResult | null, eliminating null-means-what ambiguity for callers.

State cleanup on fresh auth

New clearStaleProjectState utility wipes per-project state (API key store, .env.local, session checkpoint) when a new account is established, preventing credential inheritance across accounts. Called from direct signup success, OAuth completion, and logout.

Session extensions

WizardSession gains signup ceremony state: signupRequiredFields (server-requested fields), signupAuth (intermediate auth result), and signupAbandoned (requires_redirect fallthrough).

Test plan

• Unit tests for all three new TUI screens (validation, session writes, dispatch)
• Unit tests for promptForMissingSignupFields — all-missing / partial / no-op / email validator / name validator / trimming
• Unit tests for clearStaleProjectState
• Router parameterized cases for each signup field combination
• Flow-invariants property tests (fast-check) — signup gate + Auth unreachable until fields filled
• BDD scenarios for server-driven field collection (4 journey shapes: no flags, partial flags, all flags, requires_redirect)
• BDD scenarios for interactive TUI prompts (no flags / partial flags / all flags)
• Automated smoke of --agent --signup → exits with AUTH_REQUIRED (3)
• Automated smoke of --ci --signup → exits non-zero with clear error
• Manual smoke of pnpm try --signup (TUI) — verify screens render, submit advances
• Manual smoke of pnpm try --classic --signup — verify inquirer prompts run in order

Out of scope

A "stored user will be cleared — continue?" confirmation before direct signup. Tracked as a follow-up.

---

Note

Medium Risk
Changes core signup/auth routing and token persistence behavior (new needs_information retry loop, new TUI screens, and per-project state wipes on fresh auth), which could affect onboarding flow and credential handling if any edge case is missed.

Overview
Enables a server-driven --signup flow where the provisioning endpoint can return needs_information and the wizard collects missing fields (full name/email) and retries, instead of treating missing inputs as an all-or-nothing failure.

Adds a dedicated TUI “signup ceremony” (SignupFullName, SignupEmail, SigningUp) with new session state (signupRequiredFields, signupAuth, signupAbandoned) and updates routing/gating so OAuth doesn’t race direct-signup and direct-signup results are reused rather than re-POSTed.

Refactors the direct-signup wrapper to return a discriminated union (success/needs_information/requires_redirect/error), adds optional interactive prompting for classic mode, and introduces clearStaleProjectState to wipe install-dir keyed auth/project artifacts on successful direct signup, fresh OAuth completion, and logout. Extensive new unit/property/BDD tests cover the new states and invariants.

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

[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: needs_information re-prompt path is unreachable dead code
  • Updated setSignupRequiredFields to null the matching session value (e.g. signupFullName for full_name) so the flow re-resolves back to the collection screen, and removed the dead unmet branch in SigningUpScreen that always evaluated to empty.

Or push these changes by commenting:

@cursor push 278394f724

Preview (278394f724)

diff --git a/features/step-definitions/direct-signup-needs-information.steps.ts b/features/step-definitions/direct-signup-needs-information.steps.ts
--- a/features/step-definitions/direct-signup-needs-information.steps.ts
+++ b/features/step-definitions/direct-signup-needs-information.steps.ts
@@ -101,10 +101,10 @@
   'the first signup POST returns needs_information for {string}',
   function (field: string) {
     // Mirrors what SigningUpScreen does on a needs_information response
-    // with a known, unmet field: store.setSignupRequiredFields([...]).
+    // with a known, unmet field: store.setSignupRequiredFields([...]),
+    // which both records the requirement and nulls the matching session
+    // value so the flow re-resolves back to the collection screen.
     session.signupRequiredFields = [field];
-    // fieldPresentOnSession treats an existing signupFullName as satisfied;
-    // clear it so the router returns to SignupFullName like a fresh ask.
     if (field === 'full_name') {
       session.signupFullName = null;
     }

diff --git a/src/ui/tui/screens/SigningUpScreen.tsx b/src/ui/tui/screens/SigningUpScreen.tsx
--- a/src/ui/tui/screens/SigningUpScreen.tsx
+++ b/src/ui/tui/screens/SigningUpScreen.tsx
@@ -37,7 +37,7 @@
   performSignupOrAuth,
   trackSignupAttempt,
 } from '../../../utils/signup-or-auth.js';
-import { KNOWN_REQUIRED_FIELDS, fieldPresentOnSession } from '../flows.js';
+import { KNOWN_REQUIRED_FIELDS } from '../flows.js';
 
 interface SigningUpScreenProps {
   store: WizardStore;
@@ -117,18 +117,13 @@
             store.setSignupAbandoned(true);
             return;
           }
-          // Re-read the live session for the unmet-field check —
-          // a slash command (e.g. /region) could in principle have
-          // mutated session during the await, and we want the freshest
-          // view when deciding whether to abandon vs continue.
-          const live = store.session;
-          const unmet = result.requiredFields.filter(
-            (f) => !fieldPresentOnSession(live, f),
-          );
-          if (unmet.length === 0) {
-            store.setSignupAbandoned(true);
-            return;
-          }
+          // setSignupRequiredFields nulls the matching session values so
+          // the flow re-resolves back to the corresponding collection
+          // screen for a re-prompt. The SignupFullName predicate gates on
+          // `signupFullName === null`; without that clear, the session
+          // still carries the value we just sent, the predicate skips
+          // SignupFullName, and the router lands back on SigningUp with
+          // no way to gather a fresh value (-> infinite spinner).
           store.setSignupRequiredFields(result.requiredFields);
           return;
         }

diff --git a/src/ui/tui/store.ts b/src/ui/tui/store.ts
--- a/src/ui/tui/store.ts
+++ b/src/ui/tui/store.ts
@@ -616,6 +616,17 @@
   }
 
   setSignupRequiredFields(fields: string[]): void {
+    // Null out the previously-submitted value for any field the server is
+    // re-requesting so the flow re-resolves back to its collection screen
+    // (e.g. SignupFullName, whose `show` predicate gates on
+    // `signupFullName === null`). Without this, SigningUpScreen would
+    // record the requirement but the flow would skip the collection
+    // screen, leaving the user stuck on SigningUp with no way forward.
+    for (const field of fields) {
+      if (field === 'full_name') {
+        this.$session.setKey('signupFullName', null);
+      }
+    }
     this.$session.setKey('signupRequiredFields', fields);
     this.emitChange();
   }

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

[kelsonpw]

@cursor push 278394f

[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: Missing field-already-sent guard causes infinite re-prompt loop
  • Imported and applied fieldPresentOnSession in the needs_information branch of SigningUpScreen so that when the server requests fields the session already carries, the screen now sets signupAbandoned instead of re-prompting in a loop.

Or push these changes by commenting:

@cursor push eec3255bdd

Preview (eec3255bdd)

diff --git a/src/ui/tui/screens/SigningUpScreen.tsx b/src/ui/tui/screens/SigningUpScreen.tsx
--- a/src/ui/tui/screens/SigningUpScreen.tsx
+++ b/src/ui/tui/screens/SigningUpScreen.tsx
@@ -37,7 +37,7 @@
   performSignupOrAuth,
   trackSignupAttempt,
 } from '../../../utils/signup-or-auth.js';
-import { KNOWN_REQUIRED_FIELDS } from '../flows.js';
+import { KNOWN_REQUIRED_FIELDS, fieldPresentOnSession } from '../flows.js';
 
 interface SigningUpScreenProps {
   store: WizardStore;
@@ -117,6 +117,17 @@
             store.setSignupAbandoned(true);
             return;
           }
+          // If the server is asking for a field we already submitted,
+          // it's effectively rejecting our value. Re-prompting would
+          // just send the same value again and loop forever — bail to
+          // browser OAuth instead.
+          const allFieldsAlreadySent = result.requiredFields.every((f) =>
+            fieldPresentOnSession(s, f),
+          );
+          if (allFieldsAlreadySent) {
+            store.setSignupAbandoned(true);
+            return;
+          }
           // setSignupRequiredFields nulls the matching session values so
           // the flow re-resolves back to the corresponding collection
           // screen for a re-prompt. The SignupFullName predicate gates on

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

[kelsonpw]

@cursor push eec3255

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Auth task fires duplicate signup after SigningUpScreen succeeds
  • Added s.signupAuth === null to the inline signup guard in src/commands/default.ts so the auth task skips the duplicate performSignupOrAuth call when SigningUpScreen has already populated signupAuth.
• ✅ Fixed: Missing installDir in dashboardUrl forwarding test case
  • Added the missing installDir: '/tmp/wizard-test' property to the performSignupOrAuth call in the dashboardUrl forwarding test so it satisfies the required SignupOrAuthInput shape.

Or push these changes by commenting:

@cursor push cfb8cf9832

Preview (cfb8cf9832)

diff --git a/src/commands/default.ts b/src/commands/default.ts
--- a/src/commands/default.ts
+++ b/src/commands/default.ts
@@ -767,7 +767,8 @@
                 isCreateAccountOnboarding(s) &&
                 s.signupEmail &&
                 s.signupFullName &&
-                !s.signupTokensObtained
+                !s.signupTokensObtained &&
+                s.signupAuth === null
               ) {
                 const { performSignupOrAuth } = await import(
                   '../utils/signup-or-auth.js'

diff --git a/src/utils/__tests__/signup-or-auth.test.ts b/src/utils/__tests__/signup-or-auth.test.ts
--- a/src/utils/__tests__/signup-or-auth.test.ts
+++ b/src/utils/__tests__/signup-or-auth.test.ts
@@ -220,6 +220,7 @@
       email: 'ada@example.com',
       fullName: 'Ada Lovelace',
       zone: 'us',
+      installDir: '/tmp/wizard-test',
     });
 
     expect(result.kind).toBe('success');

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

[cursor]

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

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

• ✅ Fixed: EmailCapture isComplete doesn't account for accountCreationFlow skip
  • Updated EmailCapture's isComplete to also return true when accountCreationFlow is set, so the --signup path is semantically marked complete and back-navigation traversal isn't blocked.

Or push these changes by commenting:

@cursor push c565e46cc8

Preview (c565e46cc8)

diff --git a/src/ui/tui/flows.ts b/src/ui/tui/flows.ts
--- a/src/ui/tui/flows.ts
+++ b/src/ui/tui/flows.ts
@@ -175,7 +175,9 @@
         !s.accountCreationFlow &&
         !s.emailCaptureComplete,
       isComplete: (s) =>
-        !isCreateAccountOnboarding(s) || s.emailCaptureComplete,
+        !isCreateAccountOnboarding(s) ||
+        s.emailCaptureComplete ||
+        s.accountCreationFlow,
       revert: (store) => {
         if (!isCreateAccountOnboarding(store.session)) return false;
         store.resetEmailCapture();

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

^{Reviewed by Cursor Bugbot for commit 5bdadbe. Configure here.}

[cursor]

EmailCapture isComplete doesn't account for accountCreationFlow skip

Low Severity

EmailCapture's isComplete is !isCreateAccountOnboarding(s) || s.emailCaptureComplete. For the --signup path, isCreateAccountOnboarding is true but emailCaptureComplete is never set (the screen is hidden by !s.accountCreationFlow). isComplete returns false — the entry relies solely on show returning false to skip it. While the router's show-false-skip prevents this from blocking, the isComplete returning false is semantically incorrect for the --signup flow and could break back-navigation logic, since revert traversal walks isComplete separately from show.

 

^{Reviewed by Cursor Bugbot for commit 5bdadbe. Configure here.}

[kaiapeacock-eng]

Suggested change

	this.$session.setKey('signupEmail', email);
	this.$session.setKey('signupEmail', email.trim());

[kaiapeacock-eng]

This is okay, but reverting will send you all the way back to region select as-is. Potentially an area for follow up