fix: stop transient ineligibility from permanently completing the first-run tour (Comfy-Org#15173)

## Summary

`handleStartupOutcome` treated "not a tour candidate on this boot" as
"already onboarded", permanently writing `Comfy.TutorialCompleted` for
users who were only transiently ineligible.

## Changes

- **What**: `isFirstRunCandidate()` returns false for five reasons, only
one of which is stable. `handleStartupOutcome` marked the tutorial
completed for all five. `Comfy.TutorialCompleted` is persisted
server-side against the user record and is only ever set to `true`, so a
single ineligible boot removed onboarding from that account forever.
Replaced the boolean with a three-way decision: `complete` (mark +
template browser), `defer` (template browser only, flag untouched),
`getting-started`. `isFirstRunCandidate()` is now derived from it, so
`handleUrlWorkflow` is unchanged.

Classification:

| condition | decision | why |
| -------------------------- | -------- |
---------------------------------------------------------------------------------
|
| `!isCloud` | complete | build-time `__DISTRIBUTION__`; cannot change
for this deployment |
| `isNewUser() === false` | complete | a determined returning user does
not become new again |
| `!onboardingTourEnabled` | defer | server flag, defaults false before
`/features` resolves, and flips during rollout |
| `!isDesktopWidth` | defer | viewport |
| `!isSubscriptionEnabled()` | defer | reads `window.__CONFIG__`,
written by the same `/features` fetch |
| `isNewUser() === null` | defer | undetermined is not a determination |

Two reachable cases this fixes. Signing up on a phone and returning on a
laptop is ordinary behaviour, and today it costs the user onboarding
permanently — raised by @MaanilVerma on
Comfy-Org#15091. The broader
variant, found while verifying that one: every boot taken while
`onboarding_tour_enabled` is off marks _every_ new user completed, so
the entire cohort onboarded before the rollout can never see the tour
once it is turned on.

## Review Focus

`isSubscriptionEnabled()` is `isCloud &&
window.__CONFIG__?.subscription_required` — deployment config, not
per-user subscription state, so "permanent" is arguable. It is
classified transient because `window.__CONFIG__` is populated by the
async `/features` fetch in `refreshRemoteConfig`, which sets it to `{}`
on timeout (5s), on 401/403, and on any network error. A wedged features
endpoint would otherwise burn the tour for every user who booted during
the outage. The cost of being wrong is asymmetric: a wrong `defer`
reopens the template browser one extra time, a wrong `complete` is
unrecoverable.

The `url-intent` branch still marks completed, unchanged. That user got
a real first-run experience — their workflow loaded, and
`handleUrlWorkflow` offers the tour over it — so it is a genuine
completion, not an environmental miss.

Candidacy is still read once per startup: `decideFirstRun()` is called a
single time in `handleStartupOutcome`, so a later resize, flag refresh,
or subscription change cannot unmount the Getting Started screen
mid-interaction. Covered by the existing test.

Non-candidates still get `Comfy.BrowseTemplates` on both paths.

## Tests

Existing disqualifier table split into permanent and transient. Four new
transient cases assert the flag is not written, plus an end-to-end case
that runs two boots through a `setSetting` mock that actually persists:
narrow viewport, then desktop. All five fail on `main` (`expected
"vi.fn()" to not be called at all, but actually been called 1 times`,
and `expected false to be true` for the two-boot case).

Co-authored-by: Connor Byrne <c.byrne@comfy.org>

Author: christian-byrne

src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.test.ts

@@ -85,6 +85,9 @@ describe('useFirstRunEntry', () => {
     mocks.isNewUser = true
     mocks.tourFlag = true
     mocks.settings = {}
+    mocks.setSetting.mockImplementation((key: string, value: unknown) => {
+      mocks.settings[key] = value
+    })
   })
 
   describe('what a fresh user sees', () => {
@@ -97,16 +100,19 @@ describe('useFirstRunEntry', () => {
       expect(mocks.execute).not.toHaveBeenCalled()
     })
 
-    const disqualifiers: [string, () => void][] = [
+    const permanentDisqualifiers: [string, () => void][] = [
       ['not on cloud', () => void (mocks.isCloud = false)],
+      ['a returning user', () => void (mocks.isNewUser = false)]
+    ]
+
+    const transientDisqualifiers: [string, () => void][] = [
       ['below the md breakpoint', () => void (mocks.isDesktopWidth = false)],
       ['subscription disabled', () => void (mocks.subscriptionEnabled = false)],
-      ['a returning user', () => void (mocks.isNewUser = false)],
       ['new-user state undetermined', () => void (mocks.isNewUser = null)],
       ['the tour flag off', () => void (mocks.tourFlag = false)]
     ]
 
-    it.for(disqualifiers)(
+    it.for([...permanentDisqualifiers, ...transientDisqualifiers])(
       'opens the template browser instead, with %s',
       async ([, disqualify]) => {
         disqualify()
@@ -119,12 +125,53 @@ describe('useFirstRunEntry', () => {
           'A non-candidate must keep the existing template-browser flow'
         ).toBe(false)
         expect(mocks.execute).toHaveBeenCalledWith('Comfy.BrowseTemplates')
+      }
+    )
+
+    it.for(permanentDisqualifiers)(
+      'marks the tutorial completed for %s, which no later boot can lift',
+      async ([, disqualify]) => {
+        disqualify()
+        const entry = await freshEntry()
+
+        await entry.handleStartupOutcome('fresh')
+
         expect(
           mocks.setSetting,
           'Without this the browser reopens on every launch, forever'
         ).toHaveBeenCalledWith('Comfy.TutorialCompleted', true)
       }
     )
+
+    it.for(transientDisqualifiers)(
+      'leaves the tutorial unmarked for %s, so a later boot can still onboard',
+      async ([, disqualify]) => {
+        disqualify()
+        const entry = await freshEntry()
+
+        await entry.handleStartupOutcome('fresh')
+
+        expect(
+          mocks.setSetting,
+          'Comfy.TutorialCompleted is write-once and server-side; setting it here burns the tour for an account that was only ineligible this boot'
+        ).not.toHaveBeenCalled()
+      }
+    )
+
+    it('onboards a user whose earlier boot was only transiently ineligible', async () => {
+      mocks.isDesktopWidth = false
+      const phone = await freshEntry()
+      await phone.handleStartupOutcome('fresh')
+
+      mocks.isDesktopWidth = true
+      const laptop = await freshEntry()
+      await laptop.handleStartupOutcome('fresh')
+
+      expect(
+        laptop.gettingStartedVisible.value,
+        'signing up on a phone and returning on a laptop is ordinary behaviour'
+      ).toBe(true)
+    })
   })
 
   it('marks a url-intent startup completed without taking over the screen', async () => {
@@ -167,8 +214,9 @@ describe('useFirstRunEntry', () => {
 
       expect(
         entry.gettingStartedVisible.value ||
-          mocks.setSetting.mock.calls.length > 0,
-        'a startup that opened a blank canvas must either offer onboarding or record that it is done; anything else strands the user with no screen and no flag'
+          mocks.setSetting.mock.calls.length > 0 ||
+          mocks.execute.mock.calls.length > 0,
+        'a startup that opened a blank canvas must offer onboarding, record that it is done, or open the template browser; anything else strands the user with an empty screen'
       ).toBe(true)
     }
   )

src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts

@@ -27,12 +27,29 @@ export const useFirstRunEntry = createSharedComposable(() => {
   const isDesktopWidth =
     useBreakpoints(breakpointsTailwind).greaterOrEqual('md')
 
+  /**
+   * `defer` is ineligibility a later boot can lift — the tour flag, the
+   * viewport, remote config that has not arrived. `Comfy.TutorialCompleted` is
+   * write-once and server-side, so only `complete` may set it.
+   */
+  type FirstRunDecision = 'getting-started' | 'defer' | 'complete'
+
+  function decideFirstRun(): FirstRunDecision {
+    if (!isCloud) return 'complete'
+
+    const isNewUser = useNewUserService().isNewUser()
+    if (isNewUser === false) return 'complete'
+
+    if (!useFeatureFlags().flags.onboardingTourEnabled) return 'defer'
+    if (!isDesktopWidth.value) return 'defer'
+    if (!useSubscription().isSubscriptionEnabled()) return 'defer'
+    if (isNewUser === null) return 'defer'
+
+    return 'getting-started'
+  }
+
   function isFirstRunCandidate(): boolean {
-    if (!useFeatureFlags().flags.onboardingTourEnabled) return false
-    if (!isCloud) return false
-    if (!isDesktopWidth.value) return false
-    if (!useSubscription().isSubscriptionEnabled()) return false
-    return useNewUserService().isNewUser() === true
+    return decideFirstRun() === 'getting-started'
   }
 
   /**
@@ -51,12 +68,13 @@ export const useFirstRunEntry = createSharedComposable(() => {
       return
     }
 
-    if (isFirstRunCandidate()) {
+    const decision = decideFirstRun()
+    if (decision === 'getting-started') {
       gettingStartedVisible.value = true
       return
     }
 
-    await markTutorialCompleted()
+    if (decision === 'complete') await markTutorialCompleted()
     await useCommandStore().execute('Comfy.BrowseTemplates')
   }