@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/auth.mjs

@@ -12,6 +12,7 @@ import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { run, runCapture } from './utils/proc/proc.mjs';
@@ -22,11 +23,12 @@ import { clearDevAuthKey, readDevAuthKey, writeDevAuthKey } from './utils/auth/d
 import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
 import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
 import { copyFileIfMissing, linkFileIfMissing, removeFileOrSymlinkIfExists, writeSecretFileIfMissing } from './utils/auth/files.mjs';
+import { clearStackForceLoginCredentialPaths } from './utils/auth/clearStackForceLoginCredentialPaths.mjs';
 import { resolveHandyMasterSecretFromStack } from './utils/auth/handy_master_secret.mjs';
 import { ensureDir, readTextIfExists } from './utils/fs/ops.mjs';
 import { stackExistsSync } from './utils/stack/stacks.mjs';
 import { checkDaemonState } from './daemon.mjs';
-import { isTty, prompt, withRl } from './utils/cli/wizard.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
 import { parseCliIdentityOrThrow, resolveCliHomeDirForIdentity } from './utils/stack/cli_identities.mjs';
 import {
   getCliHomeDirFromEnvOrDefault,
@@ -39,6 +41,8 @@ import { bold, cyan, dim } from './utils/ui/ansi.mjs';
 import { getVerbosityLevel } from './utils/cli/verbosity.mjs';
 import { runOrchestratedGuidedAuthFlow, startDaemonPostAuth } from './utils/auth/orchestrated_stack_auth_flow.mjs';
 import { applyStackActiveServerScopeEnv } from './utils/auth/stable_scope_id.mjs';
+import { isLocalishUrl } from './utils/service/auth_guidance.mjs';
+import { resolveStackAuthCliExecutable } from './utils/auth/stack_guided_login.mjs';
 import {
   findAnyCredentialPathInCliHome,
   findExistingStackCredentialPath,
@@ -48,6 +52,7 @@ import { decodeJwtPayloadUnsafe } from './utils/auth/decode_jwt_payload_unsafe.m
 import { fileHasContent } from './utils/fs/file_has_content.mjs';
 import { buildConfigureServerLinks } from '@happier-dev/cli-common/links';
 import { getStackRuntimeStatePath, isPidAlive as isRuntimePidAlive, readStackRuntimeStateFile } from './utils/stack/runtime_state.mjs';
+import { resolveStackRuntimeLaunchContext } from './runtime/launch/resolveStackRuntimeLaunchContext.mjs';
 
 function resolveGuidedStartAction({ healthOk = false, runtimeOwnerAlive = false, autoStart = false } = {}) {
   if (healthOk) return 'proceed';
@@ -56,6 +61,17 @@ function resolveGuidedStartAction({ healthOk = false, runtimeOwnerAlive = false,
   return 'prompt';
 }
 
+function resolveGuidedStackStartCommand({ stackName, startKind = 'dev' } = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+  if (startKind === 'runtime') {
+    return `hstack stack start ${name} --background --runtime`;
+  }
+  if (startKind === 'start') {
+    return `hstack stack start ${name} --background`;
+  }
+  return `hstack stack dev ${name} --background`;
+}
+
 async function getInternalServerUrlCompat() {
   const stackName = getStackName();
   try {
@@ -229,6 +245,28 @@ function resolveGuidedServerReadyTimeoutMs(env = process.env) {
   return Number.isFinite(n) && n >= 1_000 ? n : 30_000;
 }
 
+function resolveAuthExpoSoftTimeoutMs(env = process.env) {
+  const raw = String(env.HAPPIER_STACK_AUTH_EXPO_SOFT_TIMEOUT_MS ?? '').trim();
+  if (!raw) return 120_000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 1 ? n : 120_000;
+}
+
+function resolveAuthExpoMaxTimeoutMs(env = process.env) {
+  const raw = String(env.HAPPIER_STACK_AUTH_EXPO_MAX_TIMEOUT_MS ?? '').trim();
+  if (!raw) return 900_000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 1 ? n : 900_000;
+}
+
+function formatDurationMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n <= 0) return `${ms}ms`;
+  if (n < 60_000) return `${Math.round(n / 1000)}s`;
+  const m = Math.round(n / 60_000);
+  return `${m}m`;
+}
+
 async function isStackRuntimeOwnerAlive(stackName) {
   try {
     const statePath = getStackRuntimeStatePath(stackName);
@@ -269,7 +307,7 @@ async function cmdSeed({ argv, json }) {
 }
 
 async function cmdDevKey({ argv, json }) {
-  const { flags, kv } = parseArgs(argv);
+  const { flags, kv: argKv } = parseArgs(argv);
 
   // parseArgs currently only supports --k=v, but UX/docs commonly use: --k "value".
   // Support both forms here (without changing global parsing semantics).
@@ -291,14 +329,14 @@ async function cmdDevKey({ argv, json }) {
   };
 
   const wantPrint = flags.has('--print');
-  const fmtRaw = (argvKvValue('--format') || (kv.get('--format') ?? '')).trim();
+  const fmtRaw = (argvKvValue('--format') || (argKv.get('--format') ?? '')).trim();
   // UX: the Happy UI restore screen expects the "backup" (XXXXX-...) format.
   //
   // IMPORTANT: the Happy restore screen treats any key containing '-' as "backup format",
   // so printing a base64url key (which may contain '-') is *not reliably pasteable*.
   // Default to backup always unless explicitly overridden.
   const fmt = fmtRaw || 'backup'; // base64url | backup
-  const set = (argvKvValue('--set') || (kv.get('--set') ?? '')).trim();
+  const set = (argvKvValue('--set') || (argKv.get('--set') ?? '')).trim();
   const clear = flags.has('--clear');
 
   if (set) {
@@ -461,7 +499,21 @@ function resolveLightDirsForStack({ env, baseDir }) {
   return { dataDir, filesDir, dbDir };
 }
 
-function resolveDbProviderForLightFromEnv(env) {
+export function buildLightMigrationBaseEnv(processEnv, envIn) {
+  const baseEnv = { ...(processEnv && typeof processEnv === 'object' ? processEnv : {}) };
+  delete baseEnv.DATABASE_URL;
+  delete baseEnv.HAPPIER_SERVER_LIGHT_DATA_DIR;
+  delete baseEnv.HAPPIER_SERVER_LIGHT_FILES_DIR;
+  delete baseEnv.HAPPIER_SERVER_LIGHT_DB_DIR;
+  delete baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR;
+  delete baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR;
+  delete baseEnv.HAPPY_SERVER_LIGHT_DB_DIR;
+  delete baseEnv.HAPPIER_DB_PROVIDER;
+  delete baseEnv.HAPPY_DB_PROVIDER;
+  return { ...baseEnv, ...(envIn && typeof envIn === 'object' ? envIn : {}) };
+}
+
+export function resolveDbProviderForLightFromEnv(env) {
   const raw = (env.HAPPIER_DB_PROVIDER ?? env.HAPPY_DB_PROVIDER ?? '').toString().trim().toLowerCase();
   if (raw === 'sqlite') return 'sqlite';
   if (raw === 'pglite') return 'pglite';
@@ -482,7 +534,7 @@ function resolveSqliteDatabaseUrlForLight({ dataDir }) {
 async function ensureLightMigrationsApplied({ serverDir, baseDir, envIn, quiet = false }) {
   // IMPORTANT: envIn is often parsed from a stack env file (so it does not include PATH).
   // Start from the current process env so we can spawn Yarn reliably, then overlay stack-specific vars.
-  const env = { ...process.env, ...(envIn && typeof envIn === 'object' ? envIn : {}) };
+  const env = buildLightMigrationBaseEnv(process.env, envIn);
   const { dataDir, filesDir, dbDir } = resolveLightDirsForStack({ env, baseDir });
   env.HAPPIER_SERVER_LIGHT_DATA_DIR = dataDir;
   env.HAPPIER_SERVER_LIGHT_FILES_DIR = filesDir;
@@ -1541,37 +1593,56 @@ async function cmdLogin({ argv, json }) {
 
   const webappModeRaw =
     (argvKvValue(argv, '--webapp') || (kv.get('--webapp') ?? '')).toString().trim().toLowerCase();
-  const webappMode = webappModeRaw || 'auto'; // auto|stack|public|expo|hosted
+  const requestedWebappMode = webappModeRaw || 'auto'; // auto|stack|public|expo|hosted
+  const HOSTED_WEBAPP_URL = 'https://app.happier.dev';
   const explicitWebappUrl =
     (argvKvValue(argv, '--webapp-url') || (kv.get('--webapp-url') ?? '')).toString().trim();
   const methodRaw = (argvKvValue(argv, '--method') || (kv.get('--method') ?? '')).toString().trim().toLowerCase();
-  const method = methodRaw === 'mobile' ? 'mobile' : methodRaw === 'web' || methodRaw === 'browser' ? 'web' : '';
+  let method = methodRaw === 'mobile' ? 'mobile' : methodRaw === 'web' || methodRaw === 'browser' ? 'web' : '';
   if (methodRaw && !method) {
     throw new Error(`[auth] login: invalid --method=${methodRaw} (expected: web|browser|mobile)`);
   }
 
   const { envWebappUrl } = getWebappUrlEnvOverride({ env: process.env, stackName });
   const expoWebappUrl = await resolveWebappUrlFromRunningExpo({ rootDir, stackName });
+  const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv: [], env: process.env });
+  const runtimeSnapshotActive = Boolean(runtimeLaunchContext.snapshot);
+
+  const serviceMode = (process.env.HAPPIER_STACK_SERVICE_MODE ?? '').toString().trim() === '1';
+  const wantsDefaultExpoInAuto =
+    requestedWebappMode === 'auto' &&
+    !explicitWebappUrl &&
+    !envWebappUrl &&
+    method !== 'mobile' &&
+    tty &&
+    !serviceMode &&
+    !runtimeSnapshotActive;
+  const effectiveWebappMode = wantsDefaultExpoInAuto ? 'expo' : requestedWebappMode;
+  const shouldUseRuntimeStart = runtimeSnapshotActive && effectiveWebappMode !== 'expo';
+  const guidedStartKind = shouldUseRuntimeStart ? 'runtime' : effectiveWebappMode === 'expo' ? 'dev' : 'start';
+  const guidedStartCommand = resolveGuidedStackStartCommand({
+    stackName,
+    startKind: guidedStartKind,
+  });
 
   let webappUrlRaw = '';
   let webappUrlSource = '';
   if (explicitWebappUrl) {
     webappUrlRaw = explicitWebappUrl;
     webappUrlSource = 'webapp-url flag';
-  } else if (webappMode === 'public') {
+  } else if (effectiveWebappMode === 'public') {
     webappUrlRaw = publicServerUrl;
     webappUrlSource = 'public server';
-  } else if (webappMode === 'hosted') {
-    // Use happier-cli defaults (do not force a URL here).
-    webappUrlRaw = '';
-    webappUrlSource = 'cli default';
-  } else if (webappMode === 'expo') {
+  } else if (effectiveWebappMode === 'hosted') {
+    webappUrlRaw = HOSTED_WEBAPP_URL;
+    webappUrlSource = 'hosted';
+  } else if (effectiveWebappMode === 'expo') {
     webappUrlRaw = expoWebappUrl || '';
     webappUrlSource = 'expo';
   } else {
     // auto|stack: preserve existing ordering for now (env override wins unless explicitly forced otherwise).
-    webappUrlRaw = envWebappUrl || expoWebappUrl || publicServerUrl;
-    webappUrlSource = envWebappUrl ? 'stack env override' : expoWebappUrl ? 'expo' : 'server';
+    webappUrlRaw = runtimeSnapshotActive ? envWebappUrl || publicServerUrl || expoWebappUrl : envWebappUrl || expoWebappUrl || publicServerUrl;
+    webappUrlSource = envWebappUrl ? 'stack env override' : runtimeSnapshotActive ? (publicServerUrl ? 'server' : expoWebappUrl ? 'expo' : 'server') : expoWebappUrl ? 'expo' : 'server';
   }
 
   const webappUrl = webappUrlRaw ? await preferStackLocalhostUrl(webappUrlRaw, { stackName }) : '';
@@ -1583,7 +1654,6 @@ async function cmdLogin({ argv, json }) {
 
   const identity = parseCliIdentityOrThrow((kv.get('--identity') ?? '').trim());
   const cliHomeDir = resolveCliHomeDirForIdentity({ cliHomeDir: resolveCliHomeDir(), identity });
-  const cliBin = join(getComponentDir(rootDir, 'happier-cli'), 'bin', 'happier.mjs');
 
   const force =
     argv.includes('--force') ||
@@ -1591,17 +1661,6 @@ async function cmdLogin({ argv, json }) {
   const wantPrint = argv.includes('--print');
   const noOpen = flags.has('--no-open') || flags.has('--no-browser') || flags.has('--no-browser-open');
 
-  const nodeArgs = [cliBin, 'auth', 'login'];
-  if (force || argv.includes('--force')) {
-    nodeArgs.push('--force');
-  }
-  if (noOpen) {
-    nodeArgs.push('--no-open');
-  }
-  if (method) {
-    nodeArgs.push('--method', method);
-  }
-
   let env = {
     ...process.env,
     HAPPIER_HOME_DIR: cliHomeDir,
@@ -1613,20 +1672,37 @@ async function cmdLogin({ argv, json }) {
     ...(force ? { HAPPIER_AUTH_FORCE: '1' } : {}),
   };
   env = applyStackActiveServerScopeEnv({ env, stackName, cliIdentity: identity });
+  const credentialPaths = resolveStackCredentialPaths({ cliHomeDir, serverUrl: internalServerUrl, env });
+  const loginEnv =
+    credentialPaths.activeServerId && credentialPaths.activeServerId !== env.HAPPIER_ACTIVE_SERVER_ID
+      ? { ...env, HAPPIER_ACTIVE_SERVER_ID: credentialPaths.activeServerId }
+      : env;
+
+  const cliExecutable = await resolveStackAuthCliExecutable({ rootDir, env: loginEnv });
+  const executableLooksLikeScript =
+    cliExecutable.endsWith('.mjs') || cliExecutable.endsWith('.js') || cliExecutable.endsWith('.cjs');
+  const loginCommand = executableLooksLikeScript ? process.execPath : cliExecutable;
+  let loginArgs = executableLooksLikeScript ? [cliExecutable, 'auth', 'login'] : ['auth', 'login'];
+  if (force || argv.includes('--force')) {
+    loginArgs.push('--force');
+  }
+  if (noOpen) {
+    loginArgs.push('--no-open');
+  }
+  if (method) {
+    loginArgs.push('--method', method);
+  }
 
   if (wantPrint) {
     const cmd =
       `HAPPIER_HOME_DIR="${cliHomeDir}" ` +
       `HAPPIER_SERVER_URL="${internalServerUrl}" ` +
       `HAPPIER_PUBLIC_SERVER_URL="${publicServerUrl}" ` +
-      (env.HAPPIER_ACTIVE_SERVER_ID ? `HAPPIER_ACTIVE_SERVER_ID="${env.HAPPIER_ACTIVE_SERVER_ID}" ` : '') +
+      (loginEnv.HAPPIER_ACTIVE_SERVER_ID ? `HAPPIER_ACTIVE_SERVER_ID="${loginEnv.HAPPIER_ACTIVE_SERVER_ID}" ` : '') +
       (webappUrl ? `HAPPIER_WEBAPP_URL="${webappUrl}" ` : '') +
       (noOpen ? `HAPPIER_NO_BROWSER_OPEN="1" ` : '') +
       (method ? `HAPPIER_AUTH_METHOD="${method}" ` : '') +
-      `node "${cliBin}" auth login` +
-      (nodeArgs.includes('--force') ? ' --force' : '') +
-      (noOpen ? ' --no-open' : '') +
-      (method ? ` --method ${method}` : '');
+      `"${loginCommand}" ${loginArgs.map((arg) => `"${arg}"`).join(' ')}`;
 
     const configureServer =
       webappUrl && publicServerUrl
@@ -1672,7 +1748,7 @@ async function cmdLogin({ argv, json }) {
       throw new Error(
         `[auth] ${stackName}: server did not become healthy in time (${guidedReadyTimeoutMs}ms) while ${reason}.\n` +
           `[auth] Start it manually:\n` +
-          `  hstack stack dev ${stackName} --background`
+          `  ${guidedStartCommand}`
       );
     }
   };
@@ -1689,7 +1765,42 @@ async function cmdLogin({ argv, json }) {
     if (action === 'wait') {
       // eslint-disable-next-line no-console
       console.error(`[auth] ${stackName}: stack runtime is already starting; waiting for health before guided login...`);
-      await waitForGuidedServerReadyOrThrow('already starting');
+      if (serviceMode && method !== 'web') {
+        // Service-mode stacks tend to be the crash-looping case: auth must not sit around
+        // waiting for a UI that is not going to stabilize. Fall back immediately to mobile.
+        // eslint-disable-next-line no-console
+        console.error(`[auth] ${stackName}: service-mode stack is not becoming healthy; falling back to mobile login.`);
+        method = 'mobile';
+        env.HAPPIER_AUTH_METHOD = 'mobile';
+        const methodIdx = loginArgs.indexOf('--method');
+        if (methodIdx >= 0) {
+          loginArgs[methodIdx + 1] = 'mobile';
+        } else {
+          loginArgs = [...loginArgs, '--method', 'mobile'];
+        }
+      } else {
+        try {
+          await waitForGuidedServerReadyOrThrow('already starting');
+        } catch (waitErr) {
+          if (method === 'web') {
+            throw waitErr;
+          }
+          // The runtime is alive but the UI is not becoming healthy. Fall back to mobile auth so
+          // the user can still complete authentication without a browser-backed stack UI.
+          // eslint-disable-next-line no-console
+          console.error(
+            `[auth] ${stackName}: the stack UI did not become healthy in time; falling back to mobile login.`
+          );
+          method = 'mobile';
+          env.HAPPIER_AUTH_METHOD = 'mobile';
+          const methodIdx = loginArgs.indexOf('--method');
+          if (methodIdx >= 0) {
+            loginArgs[methodIdx + 1] = 'mobile';
+          } else {
+            loginArgs = [...loginArgs, '--method', 'mobile'];
+          }
+        }
+      }
     } else {
       let startOk = action === 'start';
       if (!startOk) {
@@ -1697,7 +1808,7 @@ async function cmdLogin({ argv, json }) {
           throw new Error(
             `[auth] ${stackName}: cannot run guided login because the stack is not running in non-interactive mode.\n` +
               `[auth] Re-run with --start-if-needed or start it manually:\n` +
-              `  hstack stack dev ${stackName} --background`
+              `  ${guidedStartCommand}`
           );
         }
         startOk = await withRl(async (rl) => {
@@ -1712,22 +1823,30 @@ async function cmdLogin({ argv, json }) {
       if (!startOk) {
         throw new Error(
           `[auth] ${stackName}: cannot run guided login because the stack is not running.\n` +
-            `[auth] Start it with: hstack stack dev ${stackName} --background`
+            `[auth] Start it with: ${guidedStartCommand}`
         );
       }
 
       await run(
         process.execPath,
-        [join(rootDir, 'scripts', 'stack.mjs'), 'dev', stackName, '--background', '--no-daemon', '--no-browser'],
+        [
+          join(rootDir, 'scripts', 'stack.mjs'),
+          shouldUseRuntimeStart ? 'start' : effectiveWebappMode === 'expo' ? 'dev' : 'start',
+          stackName,
+          '--background',
+          ...(shouldUseRuntimeStart ? ['--runtime'] : []),
+          '--no-daemon',
+          '--no-browser',
+        ],
         {
           cwd: rootDir,
-          env: { ...process.env, HAPPIER_STACK_AUTH_FLOW: '1' },
+          env: { ...process.env, ...(!shouldUseRuntimeStart && effectiveWebappMode === 'expo' ? { HAPPIER_STACK_AUTH_FLOW: '1' } : {}) },
         }
       ).catch((err) => {
         const msg =
           `[auth] ${stackName}: failed to start the stack for guided login.\n` +
           `[auth] Try starting it manually:\n` +
-          `  hstack stack dev ${stackName} --background\n\n` +
+          `  ${guidedStartCommand}\n\n` +
           `${String(err?.stack ?? err)}`;
         throw new Error(msg);
       });
@@ -1737,29 +1856,169 @@ async function cmdLogin({ argv, json }) {
   }
 
   const verbosity = getVerbosityLevel(process.env);
-  const guidedEnv = applyStackActiveServerScopeEnv({
-    env: { ...env, HAPPIER_STACK_AUTH_FLOW: '1' },
-    stackName,
-    cliIdentity: identity,
-  });
-  const guided = await runOrchestratedGuidedAuthFlow({
-    rootDir,
-    stackName,
-    env: guidedEnv,
-    verbosity,
-    json: false,
-  });
+  const scopedEnv = loginEnv;
+  let clearedForceCredentials = false;
+  const runLogin = async (runEnv) => {
+    if (force && !clearedForceCredentials) {
+      await clearStackForceLoginCredentialPaths({
+        cliHomeDir,
+        serverUrl: internalServerUrl,
+        env,
+      });
+      clearedForceCredentials = true;
+    }
+    await run(loginCommand, loginArgs, { cwd: rootDir, env: runEnv });
+  };
 
-  const daemonStart = await startDaemonPostAuth({
-    rootDir,
-    stackName,
-    env: guidedEnv,
-    forceRestart: true,
-    webappUrl: guided?.webappUrl,
-  });
-  if (daemonStart?.ok === false) {
+  let webappUrlForDaemon = webappUrl;
+  if (method !== 'mobile' && effectiveWebappMode === 'expo') {
+    const guidedEnv = applyStackActiveServerScopeEnv({
+      env: { ...scopedEnv, HAPPIER_STACK_AUTH_FLOW: '1' },
+      stackName,
+      cliIdentity: identity,
+    });
+    const publicIsLocalish = isLocalishUrl(publicServerUrl);
+
+    // Auto mode is "local-first": try Expo first (but avoid making users think it's stalled).
+    // If Expo doesn't become ready within a soft timeout, offer safe fallbacks.
+    if (requestedWebappMode === 'auto') {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[auth] ${stackName}: starting guided login via the stack’s Expo web UI (local-first).\n` +
+          `[auth] This can take several minutes on the first run while the stack starts and the web bundle builds.`
+      );
+    }
+
+    const baseSoftTimeoutMs = requestedWebappMode === 'auto' ? resolveAuthExpoSoftTimeoutMs(process.env) : null;
+    const maxTimeoutMs = requestedWebappMode === 'auto' ? resolveAuthExpoMaxTimeoutMs(process.env) : null;
+    let attemptTimeoutMs = baseSoftTimeoutMs;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        const guided = await runOrchestratedGuidedAuthFlow({
+          rootDir,
+          stackName,
+          env:
+            requestedWebappMode === 'auto' && attemptTimeoutMs
+              ? {
+                  ...guidedEnv,
+                  HAPPIER_STACK_AUTH_UI_READY_TIMEOUT_MS: String(attemptTimeoutMs),
+                  HAPPIER_STACK_AUTH_EXPO_BUNDLE_READY_TIMEOUT_MS: String(attemptTimeoutMs),
+                }
+              : guidedEnv,
+          verbosity,
+          json: false,
+        });
+        webappUrlForDaemon = guided?.webappUrl || webappUrlForDaemon;
+        break;
+      } catch (e) {
+        if (requestedWebappMode === 'expo') {
+          throw e;
+        }
+        if (publicIsLocalish) {
+          // Hosted/mobile can't reach localhost; fail closed and let the error surface.
+          throw e;
+        }
+
+        if (!tty) {
+          // Non-interactive: default to the most reliable completion path.
+          // eslint-disable-next-line no-console
+          console.error(
+            `[auth] ${stackName}: Expo web UI is not ready yet.\n` +
+              `[auth] Falling back to hosted web app (${HOSTED_WEBAPP_URL}) for the approval UI (targets: ${publicServerUrl}).`
+          );
+          const hostedEnv = { ...scopedEnv, HAPPIER_WEBAPP_URL: HOSTED_WEBAPP_URL };
+          await runLogin(hostedEnv);
+          webappUrlForDaemon = HOSTED_WEBAPP_URL;
+          break;
+        }
+
+        const choice = await withRl(async (rl) => {
+          const timeoutText = attemptTimeoutMs ? formatDurationMs(attemptTimeoutMs) : '';
+          const title =
+            `[auth] ${stackName}: Expo web UI is not ready yet` +
+            (timeoutText ? ` (waited ~${timeoutText})` : '') +
+            `.\n` +
+            `[auth] First-time web builds can take several minutes.`;
+          return await promptSelect(rl, {
+            title,
+            options: [
+              { label: 'keep waiting for Expo (recommended)', value: 'wait' },
+              { label: `use hosted web app for approval UI (${HOSTED_WEBAPP_URL}) — still logs into your stack`, value: 'hosted' },
+              { label: 'use mobile QR / deep link (no browser; requires a public URL)', value: 'mobile' },
+              { label: 'cancel and show error', value: 'cancel' },
+            ],
+            defaultIndex: 0,
+          });
+        });
+
+        if (choice === 'cancel') {
+          throw e;
+        }
+        if (choice === 'hosted') {
+          // eslint-disable-next-line no-console
+          console.error(
+            `[auth] ${stackName}: falling back to hosted web app (${HOSTED_WEBAPP_URL}) for the approval UI (targets: ${publicServerUrl}).`
+          );
+          const hostedEnv = { ...scopedEnv, HAPPIER_WEBAPP_URL: HOSTED_WEBAPP_URL };
+          await runLogin(hostedEnv);
+          webappUrlForDaemon = HOSTED_WEBAPP_URL;
+          break;
+        }
+        if (choice === 'mobile') {
+          // eslint-disable-next-line no-console
+          console.error(`[auth] ${stackName}: switching to mobile login (targets: ${publicServerUrl}).`);
+          const mobileArgs = [...loginArgs];
+          if (!mobileArgs.includes('--method')) {
+            mobileArgs.push('--method', 'mobile');
+          } else {
+            const idx = mobileArgs.indexOf('--method');
+            if (idx >= 0) {
+              mobileArgs[idx + 1] = 'mobile';
+            }
+          }
+          if (force && !clearedForceCredentials) {
+            await clearStackForceLoginCredentialPaths({
+              cliHomeDir,
+              serverUrl: internalServerUrl,
+              env,
+            });
+            clearedForceCredentials = true;
+          }
+          await run(loginCommand, mobileArgs, { cwd: rootDir, env: scopedEnv });
+          break;
+        }
+
+        // wait: increase timeout and retry
+        const next = attemptTimeoutMs ? Math.min(attemptTimeoutMs * 2, maxTimeoutMs ?? attemptTimeoutMs * 2) : null;
+        attemptTimeoutMs = next;
+        // eslint-disable-next-line no-console
+        console.error(
+          `[auth] ${stackName}: continuing to wait for Expo...` +
+            (attemptTimeoutMs ? ` (next timeout: ${formatDurationMs(attemptTimeoutMs)})` : '')
+        );
+      }
+    }
+  } else {
+    await runLogin(scopedEnv);
+  }
+
+  try {
+    const daemonStart = await startDaemonPostAuth({
+      rootDir,
+      stackName,
+      env: scopedEnv,
+      forceRestart: true,
+      webappUrl: webappUrlForDaemon,
+    });
+    if (daemonStart?.ok === false) {
+      // eslint-disable-next-line no-console
+      console.error(daemonStart.error ?? `[auth] ${stackName}: post-auth daemon start verification timed out`);
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
     // eslint-disable-next-line no-console
-    console.error(daemonStart.error ?? `[auth] ${stackName}: post-auth daemon start verification timed out`);
+    console.error(`[auth] ${stackName}: post-auth daemon start failed (non-fatal): ${msg}`);
   }
   return;
 }
@@ -1853,7 +2112,10 @@ async function main() {
   throw new Error(`[auth] unknown command: ${cmd}`);
 }
 
-main().catch((err) => {
-  console.error('[auth] failed:', err);
-  process.exit(1);
-});
+const isMainModule = process.argv[1] ? fileURLToPath(import.meta.url) === process.argv[1] : false;
+if (isMainModule) {
+  main().catch((err) => {
+    console.error('[auth] failed:', err);
+    process.exit(1);
+  });
+}

package/scripts/auth_copy_from_pglite_lock_in_use.integration.test.mjs

@@ -1,11 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
 import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { authScriptPath, runNodeCapture, terminateChildProcess } from './testkit/auth_testkit.mjs';
+import { spawnTestProcess } from './testkit/core/spawn_test_process.mjs';
 
 test('hstack stack auth copy-from skips pglite DB seed when lock is held by a live pid', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
@@ -26,7 +26,7 @@ test('hstack stack auth copy-from skips pglite DB seed when lock is held by a li
   await writeFile(yarnPath, '#!/bin/bash\nexit 0\n', 'utf-8');
   await chmod(yarnPath, 0o755);
 
-  const repoRoot = dirname(rootDir); // .../apps/stack -> .../ (monorepo root)
+  const repoRoot = dirname(dirname(rootDir)); // .../apps/stack -> repo root
 
   const mkStackEnv = async (name) => {
     const baseDir = join(storageDir, name);
@@ -53,7 +53,7 @@ test('hstack stack auth copy-from skips pglite DB seed when lock is held by a li
   await mkStackEnv('dev');
 
   const lockPath = join(source.dataDir, '.happier.pglite.lock');
-  const holder = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' });
+  const holder = spawnTestProcess(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' });
   assert.ok(holder.pid && holder.pid > 1);
   try {
     await writeFile(
@@ -78,7 +78,7 @@ test('hstack stack auth copy-from skips pglite DB seed when lock is held by a li
     assert.match(combinedOutput, /\bdb seed skipped\b/i, `expected db seed to be skipped\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
     assert.match(
       combinedOutput,
-      /\bpglite db dir is in use by pid(?:=|\b)/i,
+      /\bpglite.*(?:already in use|in use)\b/i,
       `expected message about live pglite lock\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`
     );
   } finally {