@happier-dev/stack 0.1.0 → 0.2.0-preview.1775370152.55749

package/scripts/utils/auth/ensure_active_access_key_valid.test.mjs

@@ -0,0 +1,208 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import http from 'node:http';
+import { resolveStackCredentialPaths } from './credentials_paths.mjs';
+import { ensureActiveAccessKeyValid } from './ensure_active_access_key_valid.mjs';
+
+function writeAccessKeyFile(path, token) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    JSON.stringify(
+      {
+        encryption: { publicKey: 'AA==', machineKey: 'AA==' },
+        token,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function readTokenFromAccessKeyFile(path) {
+  const raw = readFileSync(path, 'utf8').trim();
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.token === 'string') return parsed.token.trim();
+  } catch {
+    // fall through
+  }
+  return raw;
+}
+
+function createTestJwt({ sub, jti }) {
+  const headerJson = JSON.stringify({ alg: 'none', typ: 'JWT' });
+  const payloadJson = JSON.stringify({ sub, ...(jti ? { jti } : {}) });
+  const toB64Url = (s) =>
+    Buffer.from(s, 'utf8')
+      .toString('base64')
+      .replace(/=/g, '')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_');
+  // Signature is irrelevant for decodeJwtPayloadUnsafe (and our local test server only does string equality).
+  return `${toB64Url(headerJson)}.${toB64Url(payloadJson)}.`;
+}
+
+async function withAuthServer({ goodToken }, fn) {
+  const server = http.createServer((req, res) => {
+    if (!req.url || !req.method) {
+      res.statusCode = 400;
+      res.end();
+      return;
+    }
+    if (req.method !== 'GET' || req.url !== '/v1/account/profile') {
+      res.statusCode = 404;
+      res.end();
+      return;
+    }
+    const auth = String(req.headers.authorization ?? '').trim();
+    if (auth === `Bearer ${goodToken}`) {
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+    res.statusCode = 401;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify({ error: 'unauthorized' }));
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const port = server.address().port;
+  const serverUrl = `http://127.0.0.1:${port}`;
+  try {
+    return await fn({ serverUrl });
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}
+
+test('ensureActiveAccessKeyValid repairs server-scoped access key from url-hash key when active key is unauthorized', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-repair-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      assert.ok(resolved.urlHashServerScopedPath, 'expected url-hash server scoped path');
+      assert.ok(resolved.hostPortServerScopedPath, 'expected host-port server scoped path');
+
+      writeAccessKeyFile(resolved.serverScopedPath, 'bad-token');
+      writeAccessKeyFile(resolved.urlHashServerScopedPath, 'good-token');
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'repaired');
+      assert.equal(result.sourcePath, resolved.urlHashServerScopedPath);
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), 'good-token');
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid repairs server-scoped access key from host-port key when active key is unauthorized', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-repair-hostport-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      assert.ok(resolved.hostPortServerScopedPath, 'expected host-port server scoped path');
+
+      writeAccessKeyFile(resolved.serverScopedPath, 'bad-token');
+      writeAccessKeyFile(resolved.hostPortServerScopedPath, 'good-token');
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'repaired');
+      assert.equal(result.sourcePath, resolved.hostPortServerScopedPath);
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), 'good-token');
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid does not overwrite an already-valid server-scoped access key', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-keep-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      assert.ok(resolved.urlHashServerScopedPath, 'expected url-hash server scoped path');
+
+      writeAccessKeyFile(resolved.serverScopedPath, 'good-token');
+      writeAccessKeyFile(resolved.urlHashServerScopedPath, 'other-token');
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'ok');
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), 'good-token');
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid seeds missing server-scoped access key from legacy access.key when legacy token is valid', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-legacy-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+
+      assert.equal(existsSync(resolved.serverScopedPath), false);
+      writeAccessKeyFile(resolved.legacyPath, 'good-token');
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'repaired');
+      assert.equal(result.sourcePath, resolved.legacyPath);
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), 'good-token');
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid does not switch accounts when the active key is a JWT for a different sub', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-repair-sub-guard-'));
+  try {
+    const goodToken = createTestJwt({ sub: 'account-b' });
+    await withAuthServer({ goodToken }, async ({ serverUrl }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      assert.ok(resolved.urlHashServerScopedPath, 'expected url-hash server scoped path');
+
+      const activeToken = createTestJwt({ sub: 'account-a' });
+      writeAccessKeyFile(resolved.serverScopedPath, activeToken);
+      writeAccessKeyFile(resolved.urlHashServerScopedPath, goodToken);
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'unresolved');
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), activeToken);
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid repairs server-scoped key when both active and fallback keys share the same JWT sub', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-repair-sub-match-'));
+  try {
+    const goodToken = createTestJwt({ sub: 'account-a', jti: 'good' });
+    await withAuthServer({ goodToken }, async ({ serverUrl }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      assert.ok(resolved.urlHashServerScopedPath, 'expected url-hash server scoped path');
+
+      const activeToken = createTestJwt({ sub: 'account-a', jti: 'active' });
+      writeAccessKeyFile(resolved.serverScopedPath, activeToken);
+      writeAccessKeyFile(resolved.urlHashServerScopedPath, goodToken);
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'repaired');
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), goodToken);
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/scripts/utils/auth/format_daemon_auth_scope_diagnostic.mjs

@@ -0,0 +1,43 @@
+function safeInlineValue(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return null;
+  // Avoid newlines/log injection and keep this stable for grepping.
+  return raw.replace(/\s+/g, ' ');
+}
+
+export function formatDaemonAuthScopeDiagnostic({
+  activeServerId,
+  activeCredentialPath,
+  tokenSub,
+  tokenSubBeforeRepair,
+  repairedFromPath,
+  repairedFromSub,
+}) {
+  const serverId = safeInlineValue(activeServerId) ?? 'unknown';
+  const activePath = safeInlineValue(activeCredentialPath) ?? 'unknown';
+  const sub = safeInlineValue(tokenSub);
+  const subBefore = safeInlineValue(tokenSubBeforeRepair);
+  const repairedFrom = safeInlineValue(repairedFromPath);
+  const repairedSub = safeInlineValue(repairedFromSub);
+
+  const parts = [
+    '[local] daemon auth scope:',
+    `activeServerId=${serverId}`,
+    `activeCredential=${activePath}`,
+  ];
+  if (sub) parts.push(`tokenSub=${sub}`);
+  if (subBefore) parts.push(`tokenSubBeforeRepair=${subBefore}`);
+  if (repairedFrom) parts.push(`repairedFrom=${repairedFrom}`);
+  if (repairedSub) parts.push(`repairedFromSub=${repairedSub}`);
+  return parts.join(' ');
+}
+
+export function formatDaemonCredentialsTokenSubChangedWarning({
+  tokenSubBeforeRepair,
+  tokenSub,
+} = {}) {
+  const before = safeInlineValue(tokenSubBeforeRepair);
+  const after = safeInlineValue(tokenSub);
+  if (!before || !after) return null;
+  return `[local] daemon credentials tokenSub changed: ${before} -> ${after}`;
+}

package/scripts/utils/auth/format_daemon_auth_scope_diagnostic.test.mjs

@@ -0,0 +1,56 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as diag from './format_daemon_auth_scope_diagnostic.mjs';
+
+test('formatDaemonAuthScopeDiagnostic includes required fields', () => {
+  const out = diag.formatDaemonAuthScopeDiagnostic({
+    activeServerId: 'stack_test__id_default',
+    activeCredentialPath: '/tmp/cli/servers/stack_test__id_default/access.key',
+    tokenSub: 'acct_123',
+    tokenSubBeforeRepair: null,
+    repairedFromPath: null,
+    repairedFromSub: null,
+  });
+  assert.ok(out.includes('activeServerId=stack_test__id_default'));
+  assert.ok(out.includes('activeCredential='));
+  assert.ok(out.includes('tokenSub=acct_123'));
+  assert.ok(!out.includes('repairedFrom='));
+});
+
+test('formatDaemonAuthScopeDiagnostic includes repairedFrom when provided', () => {
+  const out = diag.formatDaemonAuthScopeDiagnostic({
+    activeServerId: 'stack_test__id_default',
+    activeCredentialPath: '/tmp/cli/servers/stack_test__id_default/access.key',
+    tokenSub: null,
+    tokenSubBeforeRepair: null,
+    repairedFromPath: '/tmp/cli/servers/env_hash/access.key',
+    repairedFromSub: 'acct_999',
+  });
+  assert.ok(out.includes('repairedFrom='));
+  assert.ok(out.includes('repairedFromSub=acct_999'));
+});
+
+test('formatDaemonAuthScopeDiagnostic labels tokenSubBeforeRepair explicitly', () => {
+  const out = diag.formatDaemonAuthScopeDiagnostic({
+    activeServerId: 'stack_test__id_default',
+    activeCredentialPath: '/tmp/cli/servers/stack_test__id_default/access.key',
+    tokenSub: 'acct_new',
+    tokenSubBeforeRepair: 'acct_old',
+    repairedFromPath: null,
+    repairedFromSub: null,
+  });
+  assert.ok(out.includes('tokenSubBeforeRepair=acct_old'));
+});
+
+test('formatDaemonCredentialsTokenSubChangedWarning sanitizes tokenSub values for logs', () => {
+  assert.equal(typeof diag.formatDaemonCredentialsTokenSubChangedWarning, 'function');
+  const out = diag.formatDaemonCredentialsTokenSubChangedWarning({
+    tokenSubBeforeRepair: 'acct_old\nINJECT',
+    tokenSub: 'acct_new\t\tOK',
+  });
+  assert.equal(typeof out, 'string');
+  assert.ok(out.includes('acct_old INJECT'));
+  assert.ok(out.includes('acct_new OK'));
+  assert.equal(out.includes('\n'), false);
+  assert.equal(out.includes('\t'), false);
+});

package/scripts/utils/auth/interactive_stack_auth.mjs

@@ -11,6 +11,12 @@ export function needsAuthSeed({ cliHomeDir, accountCount }) {
   return !hasAccessKey || hasAccounts === false;
 }
 
+export function shouldSuppressInteractiveStackAuthSetup({ env = process.env } = {}) {
+  const isTuiManaged = (env?.HAPPIER_STACK_TUI ?? '').toString().trim() === '1';
+  if (isTuiManaged) return 'tui_managed';
+  return null;
+}
+
 export async function maybeRunInteractiveStackAuthSetup({
   rootDir,
   env = process.env,
@@ -22,6 +28,8 @@ export async function maybeRunInteractiveStackAuthSetup({
   beforeLogin = null,
 } = {}) {
   if (!isInteractive) return { ok: true, skipped: true, reason: 'non_interactive' };
+  const suppressedReason = shouldSuppressInteractiveStackAuthSetup({ env });
+  if (suppressedReason) return { ok: true, skipped: true, reason: suppressedReason };
   if (autoSeedEnabled) return { ok: true, skipped: true, reason: 'auto_seed_enabled' };
   if (!needsAuthSeed({ cliHomeDir, accountCount })) return { ok: true, skipped: true, reason: 'already_initialized' };
 

package/scripts/utils/auth/interactive_stack_auth.test.mjs

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  maybeRunInteractiveStackAuthSetup,
+  shouldSuppressInteractiveStackAuthSetup,
+} from './interactive_stack_auth.mjs';
+
+test('shouldSuppressInteractiveStackAuthSetup disables startup auth inside TUI-managed child sessions', () => {
+  assert.equal(shouldSuppressInteractiveStackAuthSetup({ env: { HAPPIER_STACK_TUI: '1' } }), 'tui_managed');
+  assert.equal(shouldSuppressInteractiveStackAuthSetup({ env: {} }), null);
+});
+
+test('maybeRunInteractiveStackAuthSetup skips interactive startup auth in TUI-managed child sessions', async () => {
+  const result = await maybeRunInteractiveStackAuthSetup({
+    env: { HAPPIER_STACK_TUI: '1' },
+    stackName: 'repo-dev-a1cc5e0671',
+    cliHomeDir: '/tmp/nonexistent-cli-home',
+    accountCount: 0,
+    isInteractive: true,
+    autoSeedEnabled: false,
+  });
+
+  assert.deepEqual(result, {
+    ok: true,
+    skipped: true,
+    reason: 'tui_managed',
+  });
+});

package/scripts/utils/auth/login_ux.mjs

@@ -81,6 +81,14 @@ export function printAuthLoginInstructions({
     console.log(`${dim('Web:')}   ${cyan(links.webUrl)}`);
     // eslint-disable-next-line no-console
     console.log(`${dim('Mobile:')} ${cyan(links.mobileUrl)}`);
+    if (!links.mobileUrl.includes('url=')) {
+      // eslint-disable-next-line no-console
+      console.log('');
+      // eslint-disable-next-line no-console
+      console.log(yellow('Note: this mobile link does not include a server URL (localhost is only reachable on this machine).'));
+      // eslint-disable-next-line no-console
+      console.log(dim('Fix: set HAPPIER_PUBLIC_SERVER_URL (or the stack equivalent HAPPIER_STACK_SERVER_URL) to a shareable URL your phone can reach, then retry.'));
+    }
   }
 
   if (ctx === 'selfhost') {

package/scripts/utils/auth/orchestrated_stack_auth_flow.mjs

@@ -2,15 +2,22 @@ import { join } from 'node:path';
 
 import { createStepPrinter } from '../cli/progress.mjs';
 import { createFileLogForwarder } from '../cli/log_forwarder.mjs';
-import { getComponentDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
 import { getStackRuntimeStatePath, isPidAlive, readStackRuntimeStateFile } from '../stack/runtime_state.mjs';
 import { readEnvObjectFromFile } from '../env/read.mjs';
 import { getWebappUrlEnvOverride, resolveServerUrls } from '../server/urls.mjs';
 import { readLastLines } from '../fs/tail.mjs';
 import { run } from '../proc/proc.mjs';
 
-import { guidedStackAuthLoginNow, assertExpoWebappBundlesOrThrow, resolveStackWebappUrlForAuth } from './stack_guided_login.mjs';
+import {
+  guidedStackAuthLoginNow,
+  assertGuidedAuthWebappReadyOrThrow,
+  resolveStackWebappTargetForAuth,
+  resolveStackAuthCliExecutable,
+} from './stack_guided_login.mjs';
 import { checkDaemonState, startLocalDaemonWithAuth } from '../../daemon.mjs';
+import { isTty } from '../cli/wizard.mjs';
+import { resolveStackRuntimeLaunchContext } from '../../runtime/launch/resolveStackRuntimeLaunchContext.mjs';
 
 function appendCauseText(baseMessage, cause) {
   const msg = String(baseMessage ?? '').trim();
@@ -79,6 +86,28 @@ async function appendRuntimeHealthDiagnostics(message, stackName) {
   return `${String(message ?? '').trim()}\n\n${runtimeSummary}`;
 }
 
+function resolveAuthUiStartTimeoutMs(env = process.env) {
+  const raw = String(env?.HAPPIER_STACK_AUTH_UI_START_TIMEOUT_MS ?? '').trim();
+  const parsed = raw ? Number(raw) : NaN;
+  const timeoutMs = Number.isFinite(parsed) && parsed > 0 ? parsed : 20_000;
+  return timeoutMs;
+}
+
+function resolveAuthExpoProgressIntervalMs(env = process.env) {
+  const raw = String(env?.HAPPIER_STACK_AUTH_EXPO_PROGRESS_INTERVAL_MS ?? '').trim();
+  if (!raw) return 20_000;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 20_000;
+  if (n <= 0) return 0;
+  return n;
+}
+
+function resolveAuthExpoBundleReadyTimeoutMs(env = process.env) {
+  const raw = String(env?.HAPPIER_STACK_AUTH_EXPO_BUNDLE_READY_TIMEOUT_MS ?? '').trim();
+  const n = raw ? Number(raw) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : 60_000;
+}
+
 async function appendRunnerLogTailDiagnostics({ message, stackName, lines = 140 }) {
   const base = String(message ?? '').trim();
   const logPath = await resolveRunnerLogPathFromRuntime({ stackName, waitMs: 1000, pollMs: 100 }).catch(() => '');
@@ -94,15 +123,27 @@ async function appendRunnerLogTailDiagnostics({ message, stackName, lines = 140
 async function tryStartStackUiInBackgroundForAuth({ rootDir, stackName, env = process.env } = {}) {
   const name = String(stackName ?? '').trim() || 'main';
   try {
+    const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv: [], env });
+    const useRuntimeStart = Boolean(runtimeLaunchContext.snapshot);
+    const command = useRuntimeStart ? 'start' : 'dev';
     await run(
       process.execPath,
-      [join(rootDir, 'scripts', 'stack.mjs'), 'dev', name, '--background', '--no-daemon', '--no-browser'],
+      [
+        join(rootDir, 'scripts', 'stack.mjs'),
+        command,
+        name,
+        '--background',
+        ...(useRuntimeStart ? ['--runtime'] : []),
+        '--no-daemon',
+        '--no-browser',
+      ],
       {
         cwd: rootDir,
+        timeoutMs: resolveAuthUiStartTimeoutMs(env),
         env: {
           ...process.env,
           ...(env ?? {}),
-          HAPPIER_STACK_AUTH_FLOW: '1',
+          ...(useRuntimeStart ? {} : { HAPPIER_STACK_AUTH_FLOW: '1' }),
         },
       }
     );
@@ -142,17 +183,73 @@ export async function prepareGuidedLoginWebapp({ rootDir, stackName, env, steps
   const printer = steps && typeof steps.start === 'function' && typeof steps.stop === 'function' ? steps : null;
 
   if (printer) printer.start(label);
+  const progressIntervalMs = resolveAuthExpoProgressIntervalMs(env ?? process.env);
+  const progressEnabled = Boolean(isTty() && progressIntervalMs > 0);
+  const startedAt = Date.now();
+  let stopProgress = null;
+  if (progressEnabled) {
+    let stopped = false;
+    let printedLogHint = false;
+    const tick = async () => {
+      if (stopped) return;
+      try {
+        const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv: [], env });
+        const waitingForRuntimeUi = Boolean(runtimeLaunchContext.snapshot);
+        const st = await readStackRuntimeStateFile(getStackRuntimeStatePath(name)).catch(() => null);
+        const ownerPid = Number(st?.ownerPid);
+        const ownerAlive = Number.isFinite(ownerPid) && ownerPid > 1 ? isPidAlive(ownerPid) : null;
+        const expoPid = Number(st?.processes?.expoPid);
+        const expoAlive = Number.isFinite(expoPid) && expoPid > 1 ? isPidAlive(expoPid) : null;
+        const elapsedSec = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+        const stateText =
+          waitingForRuntimeUi
+            ? 'Stack UI is still starting; waiting for the runtime-backed web UI...'
+            : expoAlive === true
+            ? 'Expo dev server is running; waiting for the first web build to finish...'
+            : 'Stack UI is still starting; waiting for Expo dev server...';
+        // eslint-disable-next-line no-console
+        console.error(`[auth] ${name}: ${stateText} (${elapsedSec}s elapsed; this can take several minutes on first run)`);
+
+        const logPath = String(st?.logs?.runner ?? '').trim();
+        if (!printedLogHint && logPath) {
+          printedLogHint = true;
+          // eslint-disable-next-line no-console
+          console.error(`[auth] ${name}: tip: tail runner log for details: ${logPath}`);
+        }
+        if (ownerAlive === false) {
+          // eslint-disable-next-line no-console
+          console.error(`[auth] ${name}: note: stack runtime owner pid looks stale; continuing to wait...`);
+        }
+      } catch {
+        // ignore
+      } finally {
+        if (!stopped) {
+          setTimeout(tick, progressIntervalMs).unref?.();
+        }
+      }
+    };
+    setTimeout(tick, progressIntervalMs).unref?.();
+    stopProgress = () => {
+      stopped = true;
+    };
+  }
   try {
     const resolveAndAssert = async () => {
-      const webappUrl = await resolveStackWebappUrlForAuth({ rootDir, stackName: name, env });
-      await assertExpoWebappBundlesOrThrow({ rootDir, stackName: name, webappUrl });
-      return webappUrl;
+      const target = await resolveStackWebappTargetForAuth({ rootDir, stackName: name, env });
+      await assertGuidedAuthWebappReadyOrThrow({
+        rootDir,
+        stackName: name,
+        webappUrl: target.webappUrl,
+        kind: target.kind,
+        timeoutMs: resolveAuthExpoBundleReadyTimeoutMs(env ?? process.env),
+      });
+      return target;
     };
 
     try {
-      const webappUrl = await resolveAndAssert();
+      const webappTarget = await resolveAndAssert();
       if (printer) printer.stop('✓', label);
-      return webappUrl;
+      return webappTarget;
     } catch (initialErr) {
       const recovery = await tryStartStackUiInBackgroundForAuth({
         rootDir,
@@ -161,9 +258,9 @@ export async function prepareGuidedLoginWebapp({ rootDir, stackName, env, steps
       });
       if (recovery.ok) {
         try {
-          const webappUrl = await resolveAndAssert();
+          const webappTarget = await resolveAndAssert();
           if (printer) printer.stop('✓', label);
-          return webappUrl;
+          return webappTarget;
         } catch (retryErr) {
           const enriched = await appendRunnerLogTailDiagnostics({
             stackName: name,
@@ -187,12 +284,22 @@ export async function prepareGuidedLoginWebapp({ rootDir, stackName, env, steps
   } catch (e) {
     if (printer) printer.stop('x', label);
     throw e;
+  } finally {
+    try {
+      stopProgress?.();
+    } catch {
+      // ignore
+    }
   }
 }
 
 export async function runGuidedLogin({ rootDir, stackName, env, webappUrl, forwarder } = {}) {
   const name = String(stackName ?? '').trim() || 'main';
-  const url = String(webappUrl ?? '').trim();
+  const target =
+    webappUrl && typeof webappUrl === 'object'
+      ? webappUrl
+      : { webappUrl: String(webappUrl ?? '').trim(), kind: 'server' };
+  const url = String(target.webappUrl ?? '').trim();
   if (!url) {
     throw new Error('[auth] guided login requires a webappUrl');
   }
@@ -208,6 +315,7 @@ export async function runGuidedLogin({ rootDir, stackName, env, webappUrl, forwa
       stackName: name,
       env: { ...(env ?? process.env), HAPPIER_STACK_AUTH_SKIP_BUNDLE_CHECK: '1' },
       webappUrl: url,
+      webappKind: target.kind,
     });
   } finally {
     try {
@@ -254,8 +362,7 @@ export async function startDaemonPostAuth({
   const cliHomeDir =
     (mergedEnv.HAPPIER_STACK_CLI_HOME_DIR ?? '').toString().trim() ||
     join(baseDir, 'cli');
-  const cliDir = getComponentDir(rootDir, 'happier-cli', mergedEnv);
-  const cliBin = join(cliDir, 'bin', 'happier.mjs');
+  const cliBin = await resolveStackAuthCliExecutable({ rootDir, env: mergedEnv });
 
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;
   const explicitWebappUrl = String(webappUrl ?? '').trim();
@@ -334,7 +441,7 @@ export async function runOrchestratedGuidedAuthFlow({
     }
   }
 
-  let resolved = String(webappUrl ?? '').trim();
+  let resolved = String(webappUrl ?? '').trim() ? { webappUrl: String(webappUrl).trim(), kind: 'server' } : null;
   try {
     if (!resolved) {
       resolved = await prepareGuidedLoginWebapp({ rootDir, stackName: name, env, steps });
@@ -348,5 +455,5 @@ export async function runOrchestratedGuidedAuthFlow({
     }
   }
 
-  return { ok: true, webappUrl: resolved };
+  return { ok: true, webappUrl: resolved?.webappUrl ?? '', webappKind: resolved?.kind ?? 'server' };
 }

package/scripts/utils/auth/orchestrated_stack_auth_flow_start_timeout.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { prepareGuidedLoginWebapp } from './orchestrated_stack_auth_flow.mjs';
+
+test('prepareGuidedLoginWebapp times out if starting stack UI in background hangs (configurable)', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-auth-ui-start-timeout-'));
+  const rootDir = join(tmp, 'root');
+  const storageDir = join(tmp, 'storage');
+  const stackDir = join(storageDir, 'main');
+  const envPath = join(stackDir, 'env');
+
+  try {
+    await mkdir(join(rootDir, 'scripts'), { recursive: true });
+    await mkdir(stackDir, { recursive: true });
+
+    await writeFile(
+      join(rootDir, 'scripts', 'stack.mjs'),
+      [
+        "import { setTimeout as delay } from 'node:timers/promises';",
+        'await delay(200);',
+        'process.exit(0);',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    await writeFile(
+      envPath,
+      [
+        'HAPPIER_STACK_STACK=main',
+        `HAPPIER_STACK_REPO_DIR=${join(tmp, 'repo')}`,
+        'HAPPIER_STACK_TAILSCALE_PREFER_PUBLIC_URL=0',
+        'HAPPIER_STACK_TAILSCALE_SERVE=0',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: 'main',
+      HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_AUTH_FLOW: '1',
+      HAPPIER_STACK_AUTH_UI_READY_TIMEOUT_MS: '1',
+      HAPPIER_STACK_AUTH_UI_START_TIMEOUT_MS: '10',
+    };
+
+    await assert.rejects(
+      async () => {
+        await prepareGuidedLoginWebapp({ rootDir, stackName: 'main', env });
+      },
+      (err) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /startup failed/i);
+        assert.match(err.message, /timed out/i);
+        return true;
+      }
+    );
+  } finally {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  }
+});
+