hookdeck login: guest-upgrade flow can hang on "Waiting for account creation…" with no way out

[leggetter]

hookdeck login on a guest profile has several ways to hang on "Waiting for account creation…" with no recoverable path. Found while investigating a support report (user had a guest CLI profile from hookdeck listen, plus an existing Hookdeck account).

All of these live in the guest-upgrade branch of Login (pkg/login/client_login.go:53-71 → waitForGuestUpgrade, client_login.go:242), which polls GET /cli-auth/validate every 2s waiting for user_is_guest to flip on the same user row, giving up after ~4 min (client_login.go:288-299).

Filing this to capture the failure modes and make sure each has a solution. Scenario 1 is the one hit in support; the others are latent.

---

1. A user who already has a Hookdeck account can never complete the upgrade

is_guest only flips via UserAuthService.signupGuest, and that is only reached when the browser signup resolves to a brand-new user:

• OAuth — core/server/services/UserAuth.ts:203-227: if (!user) { … signupGuest }. An existing Google/GitHub identity skips the guest entirely.
• Email — core/server/api/passport.ts:334-338: an existing email returns Email already exists; the user signs in instead, which never touches the guest.

In both cases the browser looks successful (the user lands in their real dashboard) while the CLI keeps polling a guest that will never be upgraded, then dies with exceeded max attempts waiting for guest account creation.

There is no browser-side rescue: the guest CLI key already has user_id/team_id set, so POST /cli-auth/claim rejects it with APIUnclaimableCliKey (core/server/api/routes/platform/cli.ts:167-172).

The only supported path for an existing account is hookdeck logout && hookdeck login — encoded as Journey B in core/clients/apps/dashboard/tests/acceptance/guest-cli-login-intents.spec.ts:181 and mentioned in pkg/cmd/login.go:38 — but the CLI never tells the user this at the moment they need it.

Also worth noting: /signin/guest?token= calls req.logIn, which silently signs the user out of their real dashboard session in that browser and into the guest.

Proposed fix: detect the dead end and fail fast with actionable text instead of a 4-minute silent timeout — e.g. poll for "the sign-in link was consumed but resolved to a different, non-guest user" and print That email already has a Hookdeck account. Run 'hookdeck logout && hookdeck login' to connect this CLI to it (the guest sandbox will be left behind). Better still, give the dashboard signup page a "sign in and attach this CLI to my account" path so the sandbox is not the price of already having an account.

2. The sign-in URL is never printed, so a failed browser open is invisible

• fmt.Printf("Press Enter to open the browser (^C to quit)") (client_login.go:253) has no trailing newline, so the spinner erases that line the moment it starts.
• open.Browser uses exec.Command(...).Start() (pkg/open/open.go:14-30) — it returns nil as soon as the child is spawned, so xdg-open/open failing afterwards is undetectable.
• The URL is printed only when Start() errors (client_login.go:260).

On WSL, in a container, under VS Code Remote, or over SSH via tmux/mosh where SSH_TTY/SSH_CONNECTION/SSH_CLIENT are unset, isSSH() is false, no browser appears, and the user is left with a bare spinner and no link — exactly what the support screenshot showed.

waitForGuestUpgrade also never checks stdinIsTerminal() (unlike the CI branch at client_login.go:71-77), so with non-TTY stdin Fscanln returns instantly and blows straight past the prompt.

Proposed fix: always print the URL on its own line before starting the spinner, whether or not the browser opens. Same applies to waitForLoginSession (client_login.go:108-118).

3. Stale guest sign-in link is handed out silently

RefreshGuestSigninLink falls back to the saved Profile.GuestURL on any API error (pkg/login/guest_link.go:16-23). Auth tokens have a 1-hour TTL (core/server/models/AuthToken.ts:16, enforced in alterQuery), so a link saved during an earlier listen session gives Link is invalid or expired in the browser (core/server/api/passport.ts:156) while the CLI keeps polling, unaware.

POST /cli/guest also 401s when the key's user is no longer a guest (core/server/api/routes/platform/cli.ts:412-416), triggering the same stale fallback.

Proposed fix: treat a refresh failure as fatal for this flow rather than falling back to a URL that is probably dead, or at minimum print a warning naming the fallback.

4. A refresh that is not authenticated as cli mints a different guest

If POST /cli/guest does not resolve authentication_method === 'cli', the server creates a new guest user and a new CLI key (core/server/api/routes/platform/cli.ts:417-427). RefreshGuestSigninLink reads only link from the response and discards key/id, so the browser would upgrade the new guest while the CLI polls the old one — a permanent hang.

Reaching this requires the key to validate on GET /cli-auth/validate but not on POST /cli/guest (key invalidated mid-flow, a proxy stripping the auth header), so it is an edge case, but it fails completely silently.

Proposed fix: adopt key/id from the response when they differ from the current profile, or error out when they do.

---

Cross-repo

Items 1, 3 and 4 have server-side halves in hookdeck/core (server/services/UserAuth.ts, server/api/routes/platform/cli.ts, server/api/passport.ts, server/models/AuthToken.ts). Happy to split out a core issue if that is easier to track.

[leggetter]

Two more failure modes found while tracing how the support case actually got into the guest state. These extend the catalog above.

5. listen --cli-key leaves an existing guest profile armed

applyCliKey (pkg/cmd/listen.go:69-114) clears GuestURL via ApplyValidateAPIKeyResponse(resp, true), but only saves the profile when there is no stored credential — "when a credential already exists it is left alone" (listen.go:92-95). That is a deliberate and correct choice for the "forward a Console source for a few minutes" case, but it means:

1. User runs bare hookdeck listen → guest profile written to disk, GuestURL set.
2. User goes through Outpost onboarding → Console → Add Destination → copies hookdeck listen [port] outpost-onboarding-test --cli-key <key> (core/clients/apps/console/src/Sidebar/DestinationForm.tsx:333).
3. The key is used for that run only. The guest profile stays on disk, untouched.
4. The next hookdeck login hits scenario 1 above and is unrecoverable without logout.

So the Console's own copy-paste command works fine while leaving the landmine armed. This is the likely path for the support case that prompted this issue.

Proposed fix: when --cli-key resolves to a different user than the stored profile and the stored profile is a guest, say so — or offer to replace it. A guest profile is not a login worth protecting the way a real one is.

6. POST /internal/console/sources/new can downgrade an authenticated session to a guest — latent, not currently firing

Checked against production first: this is not happening today. All 17 sources named outpost-onboarding-test in the BigQuery core replica belong to non-guest teams owned by non-guest users, including the one from the support case. The Outpost onboarding is correctly attributing the console sandbox to the signed-in dashboard user. Filing this as hardening, not as an active bug.

ConsoleController.getSession (core/server/controllers/Console.ts:99-113) does the right thing when a session is present — it reuses or creates that user's console sandbox via findOrCreateSandboxForUser. The dashboard sends credentials: 'include' (core/clients/apps/dashboard/client/Hookdeck.ts:200-208), so the happy path is correct.

But the route is AuthMiddlewares.isPublic (core/server/api/routes/gateway/console.ts:189-193) and the no-session fallback is not just "mint a guest" — it is followed by loginGuest(req, session.user.id), which calls req.logIn and replaces the browser's session with the guest (core/server/api/helpers/guest-session.ts:8). Any moment the session cookie does not reach the API on that one call — expired session, cookie blocking, the page loading before auth settles — silently converts a signed-in user into a guest and creates an orphan sandbox.

Aggravating factors:

• The result is cached in localStorage with revalidateIfStale: false (core/clients/apps/dashboard/components/scenes/OutpostScene/GetStarted/GetStartedView.tsx:245-277), so a guest-owned source_id is then reused indefinitely, with no ownership re-check, even after the user signs in properly.
• There is no test covering the authenticated-vs-guest branch of getSession.

Anyone who did land in that state would get a guest sandbox, and if they then used the CLI they would be on a one-way road into scenario 1.

Proposed fix: have the dashboard call a variant that requires a session and 4xxs rather than minting a guest, and never loginGuest when the request arrived with any session. Keep the guest fallback for the genuinely public POST /sources/new (partner embed) path only.

This one belongs in hookdeck/core rather than here.

---

What the support case actually was

For the record, since it narrows the fix. The affected user's console sandbox (outpost-onboarding-test) is owned by their real, non-guest account, created by the dashboard onboarding — exactly as designed. They also already had a claimed CLI client with device_name = 'dashboard onboarding' on their Event Gateway project, i.e. the dashboard had handed them a working --cli-key.

Their local CLI profile, though, was a guest belonging to a different user entirely — the one bare hookdeck listen creates. Nothing links that guest back to their account, which is precisely why hookdeck login could never resolve it.

So the trap is narrower and more mundane than the console-session theory: bare hookdeck listen before ever logging in, then hookdeck login. Scenarios 1, 2 and 5 are the ones that matter; 6 is hardening.

[leggetter]

Two related issues, so whoever picks this up has the context:

• hookdeck login: guest-upgrade poll is aggressive (fixed 2s, no backoff) and re-implements shared polling #317 - same loop, waitForGuestUpgradeCompletion. The generic poll helper proposed there takes a stop predicate, which is where scenario 1's fail-fast check belongs. Fixing this issue also cuts most of the event volume hookdeck login: guest-upgrade poll is aggressive (fixed 2s, no backoff) and re-implements shared polling #317 is about.
• Improve UX when stored credentials fail validation (login, whoami, MCP) #283 - same file, and the "credentials failed, here is how to recover" formatter proposed there is what scenario 1 needs. Improve UX when stored credentials fail validation (login, whoami, MCP) #283 handles the 401 case; this is the case where the key validates but is a guest, so nothing errors and it just hangs.

[leggetter]

The journey the claim-flow design missed

cli #306 and core #5233 enumerate three journeys:

• A — claim sandbox. Guest creds in the profile, browser opens signup, signupGuest upgrades the same user in place, sandbox kept.
• B — existing Platform account. hookdeck logout clears guest creds, browser opens signin, user picks a team.
• C — accidental new signup. Same setup as B, user clicks Sign up instead, new org, guest orphaned, CLI Guest Sandbox Abandoned fires.

Journey A assumes the browser signup resolves to a new person. There is no journey for guest creds present and the person already has a Hookdeck account, which is scenario 1 in this issue and the case in the support report. signupGuest is skipped, is_guest never flips, and the CLI polls until it times out.

The design anticipated this. CliAuthFlowMismatchType declares claim_to_signin alongside login_to_signup (server/helpers/cli_auth_abandon.ts:29), but getCliAuthFlowMismatch only ever returns login_to_signup (cli_auth_abandon.ts:38-44). core #5233 says as much: "CliAuthFlowMismatchType also declares claim_to_signin, but nothing produces or renders it in the final code." That unused branch is the detection hook this needs.

Can we transfer the sandbox to the existing account?

Worth recording the analysis, because it is cheaper than expected but narrower than it looks.

Cheaper: signupGuest already leaves console-mode sandbox orgs on their guest subscription - setDefaultSubscription is only called when team.mode !== 'console' (server/services/UserAuth.ts:284-291). So an existing user inheriting a sandbox needs no billing change. The transfer is: add them as org owner and team admin, drop the guest's memberships, set teams.is_guest = false, repoint cli_clients.user_id.

Narrower: two constraints.

1. ConsoleService.getSandboxForUser is results[0] off an unordered query - no ORDER BY (server/services/Console.ts:18-29). A user holding two console sandboxes gets a nondeterministic one. Transfer is only safe when the target user has none.
2. Anyone who has been through Outpost or dashboard onboarding already has one. The support case did - the outpost-onboarding-test sandbox is theirs, non-guest, created by the dashboard. So transfer would not have helped the reported case, and will not help most onboarded users.

Transfer is therefore a nice-to-have for a narrow slice, not the fix.

Full matrix and proposed behavior

#	CLI profile	Who they turn out to be	Today	Proposed
A	guest creds	new person	upgrade in place, sandbox kept	unchanged
B	cleared via logout	existing account	signin, team picker	unchanged
C	cleared via logout	new (drifted to signup)	new org, guest orphaned, event fires	unchanged
D	guest creds	existing account, no console sandbox	hangs ~4 min, then opaque timeout	transfer the sandbox, or attach and say what happened
D'	guest creds	existing account, already has a sandbox	hangs ~4 min, then opaque timeout	attach CLI to the chosen project, name the abandoned sandbox with a link
E	guest creds	already signed in as themselves in that browser	/signin/guest?token= calls req.logIn and signs them out of their real account into the guest	do not clobber an authenticated session
F	guest creds	link expired past 1h, refresh failed	dead link in browser, CLI still polling	fail the CLI rather than falling back to a stale URL
G	guest creds	abandons the browser	4-min timeout, message names no recovery	same timeout, message that names hookdeck logout && hookdeck login

D and D' are one detection with two outcomes. E, F and G are scenarios 6, 3 and 2 already described above.

Decision needed before implementing

For D', do we attempt any sandbox rescue, or state plainly that it is being left behind?

Everything else follows from that answer. My read is state it plainly: the sandbox is throwaway test traffic in the overwhelming majority of cases, and merging sources across two console projects is a lot of machinery for that. But it is a product call, not an engineering one.

If we take that route, D and D' collapse into one behavior and the fix is small: produce claim_to_signin from getCliAuthFlowMismatch, surface it on the poll so the CLI can stop, and print the recovery. Transfer can follow later for the no-sandbox slice if the numbers justify it.

[leggetter]

Note on the scenario 1 fix: the branch that selects the guest-upgrade path is keyed off the wrong field.

client_login.go:53 decides with config.Profile.GuestURL == "" || !response.UserIsGuest. GuestURL is a cached sign-in link, not a state flag, and it is only ever populated by GuestLogin (bare hookdeck listen). The authoritative signal is response.UserIsGuest, which the validate call on the line above already returned.

The gap that exposes: a Console --cli-key taken from an anonymous console.hookdeck.com session belongs to a guest (getSession mints one, core/server/controllers/Console.ts:99-103), and applyCliKey saves it with GuestURL cleared. hookdeck login then takes the first clause, prints "The Hookdeck CLI is configured with your console Sandbox" and exits 0 - parked on a guest, with waitForGuestUpgrade unreachable and RefreshGuestSigninLink bailing at guest_link.go:11, both for the same missing-GuestURL reason.

Same underlying state as scenario 1, different symptom. Keying the branch off UserIsGuest collapses it into scenario 1 rather than adding a row to the matrix, so the fix for D covers both.

[leggetter]

Separate clearing bug, found while checking whether a successful login --cli-key immunises a profile: a top-level guest_url is never cleared, by anything.

Writes are profile-scoped. SaveProfile sets <profile>.guest_url (pkg/config/profile.go:32), and setProfileFieldsInViper does the same (pkg/config/config.go:273-274).

Reads coalesce profile-scoped then top-level:

c.Profile.GuestURL = stringCoalesce(
    c.Profile.GuestURL,
    c.viper.GetString(c.Profile.getConfigField("guest_url")),
    c.viper.GetString("guest_url"),   // <- top-level, never written by current code, never cleared
    "",
)

(pkg/config/config.go:395)

removeLegacyConfigKeys strips only workspace_id, workspace_mode, team_id, team_mode (profile.go:41-44) - not guest_url. So every path that believes it has cleared the guest URL leaves a top-level one intact:

• ApplyValidateAPIKeyResponse(resp, true) sets p.GuestURL = "" in memory (profile_credentials.go:15-17), SaveProfile writes "" to the profile-scoped key, and the next run's coalesce falls straight through to the top-level value.
• zeroProfileCredentialFields (config.go:464) has the same hole, so hookdeck logout does not clear it either.

Consequence: a profile that has been fixed with login --cli-key, or cleared with logout, silently regains GuestURL on the next command. On its own that is inert - the guest-upgrade branch needs GuestURL != "" and UserIsGuest == true (client_login.go:53), and a real key fails the second test. It bites when the key is later invalidated: the 401 path clears the key and falls through to browser login, and a repopulated GuestURL puts the profile back in scope for scenarios 1 and 3 above.

Caveat on reachability: nothing in the current CLI writes a top-level guest_url, so this needs a config from an older layout or a hand-edited one. Worth fixing regardless - the asymmetry between a profile-scoped write and a profile-scoped-then-top-level read is a bug whatever populates it, and it applies to api_key, project_id, project_mode and project_type, which coalesce the same way on the lines above.

Proposed fix: clear the top-level key alongside the profile-scoped one wherever guest fields are zeroed, or drop the top-level fallback from the coalesce entirely and migrate it once, the way removeLegacyConfigKeys already does for the workspace/team keys.