[dawsontoth]

⊙ Problem

HarperFast/central-manager#785 makes PUT /VerifyEmail/ with only the token replace the sign-up password and email a link to set a new one. Studio's verify page ignores the response and sends everyone to sign in with the old password, which fails. #785 can't deploy until Studio handles this, and Studio must still work with today's central-manager, which sends no outcome.

🤔 Is this the right first step?

Yes, as specified for step C1 of #1697: handle every outcome and send no newPassword. Asking for a password on this page is the second half. Splitting it keeps this change small and safe to ship before #785.

💡 Solution

The verify page now follows the response's outcome:

• None (today) or password_set: toast and go to sign in, as before.
• reset_email_sent, password_reset_required, already_verified or an unknown outcome: stay on the page and say how to get a working password.
• 503: retried 3 times. Any verify still unanswered (503, 502, 504, no response) or sent offline gets Try again with the same link.
• Each token is sent once per arrival, so StrictMode's second effect can't replace the first answer.

Screenshots: the new states (light theme, dev server, response answered locally)

reset_email_sent

already_verified

A 503 after three retries

Sent while offline

🤔 Should already_verified stay on the page?

The suggested design toasted and went to sign in. But a reload, a second click, a mail scanner or a retry gets that answer after the first visit may have replaced the password, so the page stays and points at the set-password email. Keeping the first answer instead is #2029.

⚖️ Alternatives

• Only picking a toast per outcome in the existing onSuccess: a toast is too brief to be the only notice that the password was replaced, and the new-link form can't retry the same link as a 503 asks.

🔧 Changes

• src/features/auth/hooks/useVerifyEmail.ts: response type with an optional outcome (and the useId typo fixed); isVerifyEmailUnavailable (503, retried) and isVerifyEmailUnconfirmed (isUnansweredWrite or an offline send, shown as Try again with no toast). reportAuthFailure still sends the unanswered ones to RUM and keeps an offline one out.
• src/features/auth/VerifyEmail.tsx: the outcome views, the retry panel's offline copy and sign-in links, the once-per-arrival guard (a late answer for a token the route dropped is ignored), and "Verifying" from the first render instead of a flash of the resend form. A token is used only when the router hands it over as a string, which a JWT always is; the router's JSON parse of other values is Auth pages read token through the router's JSON parse of search values #2026.
• DESIGN.md: notes why this one write is repeated, under "A write with no verdict never reads as failed". The Try again copy still claims no outcome.
• e2e/tests/signup-verification.anon.spec.ts: follows either answer. On the set-password view it reads the email, sets a new password on /#/reset-password and signs in with that. Timeout sum redone (705s, limit now 840s).
• e2e/tests/mail.ts: waitForSetPasswordEmail matches the "Set your Fabric password" subject, returns only the extracted link, and names the subject when nothing arrives.
• src/features/auth/VerifyEmail.test.tsx, src/features/auth/hooks/useVerifyEmail.test.tsx: every outcome, 503 retry timing, Try again for each unanswered kind, offline then reconnect then Try again with the same token, a retry that finds the email verified, other errors, StrictMode and token changes, a late answer, both predicates.
• src/features/auth/failFastOffline.test.tsx: email verification now shows an offline failure on the page, not in a toast. The hook's own test pins its refusal toast and single RUM report instead.
• src/features/auth/AuthStatus.test.tsx: its hook mock now matches the hook's new shape.

🤔 Should automatic retries stay 503-only?

Only a 503 retries on its own, because central-manager says to retry it; a 502, 504 or no answer goes straight to Try again. Studio can't tell central-manager's 503 from a gateway's, so both get the 14 seconds of retries. #2027 tracks narrowing that.

🤔 Should the e2e drop the legacy branch after #785 ships?

It accepts either answer, so it passes on both sides of the deploy. Once #785 is everywhere, a central-manager that regressed to the old answer would still pass. Removing the sign-in branch then is a small follow-up.

✅ Verification

• vitest run: 590 files, 6,094 tests pass. tsc -b, oxlint, dprint check and e2e tsc --noEmit are clean.
• Mutation check: removing any guard this adds (once per arrival, late answer, retry, toast suppression, RUM report, string-only token, offline in the predicate, the offline copy, the panel's links), narrowing Try again to 503, sending already_verified to sign in, or reporting a refusal twice turns a test red.
• Browser (dev server under StrictMode, PUT /VerifyEmail/ answered locally): one PUT per token; each view renders; four 503s led to Try again with no toast; a 503 then already_verified explained the repeat; an offline send showed the offline copy, and Try again after reconnecting resent the same token.
• The @roundtrip e2e did not run: it needs Mailosaur credentials and the dev environment, which this machine lacks. It typechecks and lists.
• The first commit went in with --no-verify: at machine load 30–90 the husky hook's unbounded vitest run segfaulted once and once failed entityAuthCheckScope.test.ts (untouched; passes alone). Its steps passed by hand. The two follow-up commits ran the full hook.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: none found (partial scan: issue #2026 search truncated at 20 of 82)
Complexity: medium

Deferred findings

• 10faec7ad8362e92 nit reliability — src/features/auth/hooks/useVerifyEmail.ts — every 503 on /VerifyEmail/, including a gateway's, is auto-retried and offered Try again — filed Verify page retries every 503, not only central-manager's own #2027
• 8735edf8a60533bd nit correctness — src/features/auth/VerifyEmail.tsx — router-parsed non-string token (0, numeric, over 2^53) treated as absent — filed Auth pages read token through the router's JSON parse of search values #2026
• ef8b2b248908c683 nit correctness — src/features/auth/VerifyEmail.tsx — last-token ref: A to B to A re-PUTs A; removed-then-re-added token not resubmitted — filed Verify page re-sends a token that returns after another instead of keeping its first answer #2029

_{Review-Coverage: authored=claude; ran=gemini,codex,cursor-composer,cursor-grok; pending=cursor-grok; late=cursor-grok:pending; adjudicated=domain; blocked=cursor-muse(failed); declined=cursor-kimi,muse; rounds=7; full=3 @ 8b76766}

_{Review-Attention: deep ~30m (sensitive: VerifyEmail.tsx, useVerifyEmail.ts; decisions: do-less-alternative, offline-in-unconfirmed-predicate, reload-copy-vs-persisted-outcome, hook-level-503-retry, e2e-accepts-either-cm) @ 8b76766}

[gemini-code-assist]

Code Review

This pull request updates the email verification flow to support a new central-manager behavior where the sign-up password is replaced and a set-password email is sent upon verification. It updates the VerifyEmail component and its hook to handle various verification outcomes (such as reset_email_sent and already_verified), implements automatic retries for 503 errors, and adds comprehensive unit and E2E tests. Feedback on the changes suggests correcting the generic type parameter on the apiClient.put call in useVerifyEmail.ts to ensure correct typing, and forwarding all arguments (error, variables, context) to the parent onError handler in the mutation hook to prevent potential runtime issues.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	82.08%	16683 / 20324
🔵	Statements	81.97%	17704 / 21598
🔵	Functions	77.49%	4534 / 5851
🔵	Branches	76.95%	13280 / 17257

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/auth/VerifyEmail.tsx	90.56%	97.05%	77.77%	90.56%	47-56, 208
src/features/auth/hooks/useVerifyEmail.ts	100%	100%	100%	100%

Generated in workflow #2478 for commit 892dc0f by the Vitest Coverage Report Action

[kriszyp]

_{🤖 Reviewed with Muse}