happy-stacks 0.3.0 → 0.5.0

package/scripts/stack.mjs

@@ -1,7 +1,7 @@
 import './utils/env/env.mjs';
 import { spawn } from 'node:child_process';
-import { chmod, copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { chmod, copyFile, mkdir, open, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 // NOTE: random bytes usage centralized in scripts/utils/crypto/tokens.mjs
 import { homedir } from 'node:os';
@@ -9,8 +9,19 @@ import { ensureDir, readTextIfExists, readTextOrEmpty } from './utils/fs/ops.mjs
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { killProcessTree, run, runCapture } from './utils/proc/proc.mjs';
-import { getComponentDir, getComponentsDir, getHappyStacksHomeDir, getLegacyStorageRoot, getRootDir, getStacksStorageRoot, resolveStackEnvPath } from './utils/paths/paths.mjs';
-import { isTcpPortFree, pickNextFreeTcpPort } from './utils/net/ports.mjs';
+import {
+  componentDirEnvKey,
+  coerceHappyMonorepoRootFromPath,
+  getComponentDir,
+  getComponentsDir,
+  getHappyStacksHomeDir,
+  getLegacyStorageRoot,
+  getRootDir,
+  getStacksStorageRoot,
+  happyMonorepoSubdirForComponent,
+  resolveStackEnvPath,
+} from './utils/paths/paths.mjs';
+import { isTcpPortFree, listListenPids, pickNextFreeTcpPort } from './utils/net/ports.mjs';
 import {
   createWorktree,
   createWorktreeFromBaseWorktree,
@@ -19,7 +30,7 @@ import {
   resolveComponentSpecToDir,
   worktreeSpecFromDir,
 } from './utils/git/worktrees.mjs';
-import { isTty, prompt, promptWorktreeSource, withRl } from './utils/cli/wizard.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env/env_file.mjs';
@@ -27,10 +38,10 @@ import { listAllStackNames, stackExistsSync } from './utils/stack/stacks.mjs';
 import { stopStackWithEnv } from './utils/stack/stop.mjs';
 import { writeDevAuthKey } from './utils/auth/dev_key.mjs';
 import { startDevServer } from './utils/dev/server.mjs';
-import { startDevExpoWebUi } from './utils/dev/expo_web.mjs';
+import { ensureDevExpoServer } from './utils/dev/expo_dev.mjs';
 import { requireDir } from './utils/proc/pm.mjs';
 import { waitForHttpOk } from './utils/server/server.mjs';
-import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { resolveLocalhostHost, preferStackLocalhostUrl } from './utils/paths/localhost_host.mjs';
 import { openUrlInBrowser } from './utils/ui/browser.mjs';
 import { copyFileIfMissing, linkFileIfMissing, writeSecretFileIfMissing } from './utils/auth/files.mjs';
 import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './utils/auth/sources.mjs';
@@ -52,23 +63,31 @@ import {
 import { killPid } from './utils/expo/expo.mjs';
 import { getCliHomeDirFromEnvOrDefault, getServerLightDataDirFromEnvOrDefault } from './utils/stack/dirs.mjs';
 import { randomToken } from './utils/crypto/tokens.mjs';
-import { killPidOwnedByStack } from './utils/proc/ownership.mjs';
+import { killPidOwnedByStack, killProcessGroupOwnedByStack } from './utils/proc/ownership.mjs';
 import { sanitizeSlugPart } from './utils/git/refs.mjs';
 import { isCursorInstalled, openWorkspaceInEditor, writeStackCodeWorkspace } from './utils/stack/editor_workspace.mjs';
+import { readLastLines } from './utils/fs/tail.mjs';
+import { defaultStackReleaseIdentity } from './utils/mobile/identifiers.mjs';
+import { interactiveEdit, interactiveNew } from './utils/stack/interactive_stack_config.mjs';
 
 function stackNameFromArg(positionals, idx) {
   const name = positionals[idx]?.trim() ? positionals[idx].trim() : '';
   return name;
 }
 
-function getDefaultPortStart() {
+function getDefaultPortStart(stackName = null) {
   const raw = process.env.HAPPY_STACKS_STACK_PORT_START?.trim()
     ? process.env.HAPPY_STACKS_STACK_PORT_START.trim()
     : process.env.HAPPY_LOCAL_STACK_PORT_START?.trim()
       ? process.env.HAPPY_LOCAL_STACK_PORT_START.trim()
       : '';
-  const n = raw ? Number(raw) : 3005;
-  return Number.isFinite(n) ? n : 3005;
+  // Default port strategy:
+  // - main historically lives at 3005
+  // - non-main stacks should avoid 3005 to reduce accidental collisions/confusion
+  const target = (stackName ?? '').toString().trim() || (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
+  const fallback = target === 'main' ? 3005 : 3009;
+  const n = raw ? Number(raw) : fallback;
+  return Number.isFinite(n) ? n : fallback;
 }
 
 async function isPortFree(port) {
@@ -226,14 +245,48 @@ function stringifyEnv(env) {
 const readExistingEnv = readTextOrEmpty;
 
 function resolveDefaultComponentDirs({ rootDir }) {
-  const componentNames = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
-  const out = {};
-  for (const name of componentNames) {
+  function hasUnifiedLightSchema(serverDir) {
+    return (
+      existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma')) ||
+      existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))
+    );
+  }
+
+  function pickDefaultDir(name) {
     const embedded = join(rootDir, 'components', name);
     const workspace = join(getComponentsDir(rootDir), name);
-    const dir = existsSync(embedded) ? embedded : workspace;
-    out[`HAPPY_STACKS_COMPONENT_DIR_${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`] = dir;
+    // CRITICAL:
+    // In sandbox mode, never point stacks at the repo's embedded `components/*` checkouts.
+    // Sandboxes must use the sandbox workspace clones (HAPPY_STACKS_WORKSPACE_DIR/components/*),
+    // otherwise worktrees/branches collide with the user's real machine state.
+    return !isSandboxed() && existsSync(embedded) ? embedded : workspace;
   }
+
+  const out = {};
+
+  const happyRoot = pickDefaultDir('happy');
+  const monoRoot = existsSync(happyRoot) ? coerceHappyMonorepoRootFromPath(happyRoot) : null;
+
+  if (monoRoot) {
+    const subdir = (component) => happyMonorepoSubdirForComponent(component);
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY = join(monoRoot, subdir('happy'));
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = join(monoRoot, subdir('happy-cli'));
+    const serverDir = join(monoRoot, subdir('happy-server'));
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = serverDir;
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = hasUnifiedLightSchema(serverDir)
+      ? serverDir
+      : pickDefaultDir('happy-server-light');
+    return out;
+  }
+
+  // Prefer a single unified happy-server checkout for both flavors when it includes sqlite support.
+  const fullServerDir = pickDefaultDir('happy-server');
+  const hasUnifiedLight = hasUnifiedLightSchema(fullServerDir);
+
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY = pickDefaultDir('happy');
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = pickDefaultDir('happy-cli');
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = fullServerDir;
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = hasUnifiedLight ? fullServerDir : pickDefaultDir('happy-server-light');
   return out;
 }
 
@@ -264,9 +317,46 @@ async function withStackEnv({ stackName, fn, extraEnv = {} }) {
   // exported in their shell, it would otherwise "win" because utils/env.mjs only sets
   // env vars if they are missing/empty.
   const cleaned = { ...process.env };
+  const keepPrefixed = new Set([
+    // Stack/env pointers:
+    'HAPPY_LOCAL_ENV_FILE',
+    'HAPPY_STACKS_ENV_FILE',
+    'HAPPY_LOCAL_STACK',
+    'HAPPY_STACKS_STACK',
+
+    // Sandbox detection + policy (must propagate to child processes).
+    'HAPPY_STACKS_SANDBOX_DIR',
+    'HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL',
+
+    // Sandbox-enforced dirs (without these, sandbox isolation breaks).
+    'HAPPY_STACKS_CLI_ROOT_DISABLE',
+    'HAPPY_STACKS_CANONICAL_HOME_DIR',
+    'HAPPY_STACKS_HOME_DIR',
+    'HAPPY_STACKS_WORKSPACE_DIR',
+    'HAPPY_STACKS_RUNTIME_DIR',
+    'HAPPY_STACKS_STORAGE_DIR',
+    // Legacy prefix mirrors:
+    'HAPPY_LOCAL_CANONICAL_HOME_DIR',
+    'HAPPY_LOCAL_HOME_DIR',
+    'HAPPY_LOCAL_WORKSPACE_DIR',
+    'HAPPY_LOCAL_RUNTIME_DIR',
+    'HAPPY_LOCAL_STORAGE_DIR',
+
+    // Sandbox-safe UX knobs (keep consistent through stack wrappers).
+    'HAPPY_STACKS_VERBOSE',
+    'HAPPY_STACKS_UPDATE_CHECK',
+    'HAPPY_STACKS_UPDATE_CHECK_INTERVAL_MS',
+    'HAPPY_STACKS_UPDATE_NOTIFY_INTERVAL_MS',
+
+    // Guided auth flow coordination across wrappers.
+    // These are intentionally passed through even though most HAPPY_STACKS_* vars are scrubbed.
+    'HAPPY_STACKS_DAEMON_WAIT_FOR_AUTH',
+    'HAPPY_LOCAL_DAEMON_WAIT_FOR_AUTH',
+    'HAPPY_STACKS_AUTH_FLOW',
+    'HAPPY_LOCAL_AUTH_FLOW',
+  ]);
   for (const k of Object.keys(cleaned)) {
-    if (k === 'HAPPY_LOCAL_ENV_FILE' || k === 'HAPPY_STACKS_ENV_FILE') continue;
-    if (k === 'HAPPY_LOCAL_STACK' || k === 'HAPPY_STACKS_STACK') continue;
+    if (keepPrefixed.has(k)) continue;
     if (k.startsWith('HAPPY_LOCAL_') || k.startsWith('HAPPY_STACKS_')) {
       delete cleaned[k];
     }
@@ -344,110 +434,6 @@ async function withStackEnv({ stackName, fn, extraEnv = {} }) {
   return await fn({ env, envPath, stackEnv, runtimeStatePath, runtimeState });
 }
 
-async function interactiveNew({ rootDir, rl, defaults }) {
-  const out = { ...defaults };
-
-  if (!out.stackName) {
-    out.stackName = (await rl.question('Stack name: ')).trim();
-  }
-  if (!out.stackName) {
-    throw new Error('[stack] stack name is required');
-  }
-  if (out.stackName === 'main') {
-    throw new Error('[stack] stack name \"main\" is reserved (use the default stack without creating it)');
-  }
-
-  // Server component selection
-  if (!out.serverComponent) {
-    const server = (await rl.question('Server component [happy-server-light|happy-server] (default: happy-server-light): ')).trim();
-    out.serverComponent = server || 'happy-server-light';
-  }
-
-  // Port
-  if (!out.port) {
-    const want = (await rl.question('Port (empty = ephemeral): ')).trim();
-    out.port = want ? Number(want) : null;
-  }
-
-  // Remote for creating new worktrees (used by all "create new worktree" choices)
-  if (!out.createRemote) {
-    out.createRemote = await prompt(rl, 'Git remote for creating new worktrees (default: upstream): ', { defaultValue: 'upstream' });
-  }
-
-  // Component selections
-  for (const c of ['happy', 'happy-cli']) {
-    if (out.components[c] != null) continue;
-    out.components[c] = await promptWorktreeSource({
-      rl,
-      rootDir,
-      component: c,
-      stackName: out.stackName,
-      createRemote: out.createRemote,
-    });
-  }
-
-  // Server worktree selection (optional; only for the chosen server component)
-  const serverComponent = out.serverComponent === 'happy-server' ? 'happy-server' : 'happy-server-light';
-  if (out.components[serverComponent] == null) {
-    out.components[serverComponent] = await promptWorktreeSource({
-      rl,
-      rootDir,
-      component: serverComponent,
-      stackName: out.stackName,
-      createRemote: out.createRemote,
-    });
-  }
-
-  return out;
-}
-
-async function interactiveEdit({ rootDir, rl, stackName, existingEnv, defaults }) {
-  const out = { ...defaults, stackName };
-
-  // Server component selection
-  const currentServer = existingEnv.HAPPY_STACKS_SERVER_COMPONENT ?? existingEnv.HAPPY_LOCAL_SERVER_COMPONENT ?? '';
-  const server = await prompt(
-    rl,
-    `Server component [happy-server-light|happy-server] (default: ${currentServer || 'happy-server-light'}): `,
-    { defaultValue: currentServer || 'happy-server-light' }
-  );
-  out.serverComponent = server || 'happy-server-light';
-
-  // Port
-  const currentPort = existingEnv.HAPPY_STACKS_SERVER_PORT ?? existingEnv.HAPPY_LOCAL_SERVER_PORT ?? '';
-  const wantPort = await prompt(rl, `Port (empty = keep ${currentPort || 'ephemeral'}; type 'ephemeral' to unpin): `, { defaultValue: '' });
-  const wantTrimmed = wantPort.trim().toLowerCase();
-  out.port = wantTrimmed === 'ephemeral' ? null : wantPort ? Number(wantPort) : (currentPort ? Number(currentPort) : null);
-
-  // Remote for creating new worktrees
-  const currentRemote = existingEnv.HAPPY_STACKS_STACK_REMOTE ?? existingEnv.HAPPY_LOCAL_STACK_REMOTE ?? '';
-  out.createRemote = await prompt(rl, `Git remote for creating new worktrees (default: ${currentRemote || 'upstream'}): `, {
-    defaultValue: currentRemote || 'upstream',
-  });
-
-  // Worktree selections
-  for (const c of ['happy', 'happy-cli']) {
-    out.components[c] = await promptWorktreeSource({
-      rl,
-      rootDir,
-      component: c,
-      stackName,
-      createRemote: out.createRemote,
-    });
-  }
-
-  const serverComponent = out.serverComponent === 'happy-server' ? 'happy-server' : 'happy-server-light';
-  out.components[serverComponent] = await promptWorktreeSource({
-    rl,
-    rootDir,
-    component: serverComponent,
-    stackName,
-    createRemote: out.createRemote,
-  });
-
-  return out;
-}
-
 async function cmdNew({ rootDir, argv, emit = true }) {
   const { flags, kv } = parseArgs(argv);
   const positionals = argv.filter((a) => !a.startsWith('--'));
@@ -494,7 +480,7 @@ async function cmdNew({ rootDir, argv, emit = true }) {
   if (!stackName) {
     throw new Error(
       '[stack] usage: happys stack new <name> [--port=NNN] [--server=happy-server|happy-server-light] ' +
-        '[--happy=default|<owner/...>|<path>] [--happy-cli=...] [--happy-server=...] [--happy-server-light=...] ' +
+        '[--happy=default|<owner/...>|<path>] [--happy-server-light=...] ' +
         '[--copy-auth-from=<stack|legacy>] [--link-auth] [--no-copy-auth] [--interactive] [--force-port]'
     );
   }
@@ -615,24 +601,88 @@ async function cmdNew({ rootDir, argv, emit = true }) {
     }
   }
 
-  // happy
-  const happySpec = config.components.happy;
-  if (happySpec && typeof happySpec === 'object' && happySpec.create) {
-    const dir = await createWorktree({ rootDir, component: 'happy', slug: happySpec.slug, remoteName: happySpec.remote || 'upstream' });
-    stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = dir;
-  } else {
-    const dir = resolveComponentSpecToDir({ rootDir, component: 'happy', spec: happySpec });
-    if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = resolve(rootDir, dir);
+  let monorepoPinned = false;
+
+  // happy / happy-cli / happy-server can be a single monorepo (slopus/happy).
+  // Detect monorepo pinning by resolving the provided spec(s), rather than relying on the local default checkout.
+  const monoSpecs = [
+    { component: 'happy', spec: config.components.happy },
+    { component: 'happy-cli', spec: config.components['happy-cli'] },
+    { component: 'happy-server', spec: config.components['happy-server'] },
+  ].filter((x) => x.spec);
+
+  if (monoSpecs.length) {
+    const primary = monoSpecs[0];
+    const canon = (spec) => {
+      if (spec && typeof spec === 'object' && spec.create) {
+        const remote = String(spec.remote || 'upstream');
+        return `create:${String(spec.slug)}@${remote}`;
+      }
+      return String(spec);
+    };
+
+    let resolvedDir = '';
+    if (primary.spec && typeof primary.spec === 'object' && primary.spec.create) {
+      resolvedDir = await createWorktree({
+        rootDir,
+        component: primary.component,
+        slug: primary.spec.slug,
+        remoteName: primary.spec.remote || 'upstream',
+      });
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: primary.component, spec: primary.spec });
+      if (dir) resolvedDir = resolve(rootDir, dir);
+    }
+
+    const monoRoot = resolvedDir ? coerceHappyMonorepoRootFromPath(resolvedDir) : null;
+    if (monoRoot) {
+      for (const s of monoSpecs.slice(1)) {
+        if (canon(s.spec) !== canon(primary.spec)) {
+          throw new Error(
+            `[stack] conflicting monorepo component specs.\n` +
+              `- happy: ${canon(config.components.happy)}\n` +
+              `- happy-cli: ${canon(config.components['happy-cli'])}\n` +
+              `- happy-server: ${canon(config.components['happy-server'])}\n` +
+              `Fix: in monorepo mode, pass only one of --happy/--happy-cli/--happy-server (or pass the same value for all).`
+          );
+        }
+      }
+
+      const subdir = (c) => happyMonorepoSubdirForComponent(c);
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = join(monoRoot, subdir('happy'));
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = join(monoRoot, subdir('happy-cli'));
+      const serverDir = join(monoRoot, subdir('happy-server'));
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = serverDir;
+      if (
+        existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma')) ||
+        existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))
+      ) {
+        stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = serverDir;
+      }
+      monorepoPinned = true;
+    }
   }
 
-  // happy-cli
-  const cliSpec = config.components['happy-cli'];
-  if (cliSpec && typeof cliSpec === 'object' && cliSpec.create) {
-    const dir = await createWorktree({ rootDir, component: 'happy-cli', slug: cliSpec.slug, remoteName: cliSpec.remote || 'upstream' });
-    stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = dir;
-  } else {
-    const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-cli', spec: cliSpec });
-    if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = resolve(rootDir, dir);
+  if (!monorepoPinned) {
+    // happy
+    const happySpec = config.components.happy;
+    if (happySpec && typeof happySpec === 'object' && happySpec.create) {
+      const dir = await createWorktree({ rootDir, component: 'happy', slug: happySpec.slug, remoteName: happySpec.remote || 'upstream' });
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = dir;
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: 'happy', spec: happySpec });
+      if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = resolve(rootDir, dir);
+    }
+
+    // happy-cli
+    const cliSpec = config.components['happy-cli'];
+    if (cliSpec && typeof cliSpec === 'object' && cliSpec.create) {
+      const dir = await createWorktree({ rootDir, component: 'happy-cli', slug: cliSpec.slug, remoteName: cliSpec.remote || 'upstream' });
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = dir;
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-cli', spec: cliSpec });
+      if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = resolve(rootDir, dir);
+    }
   }
 
   // Server component directory override (optional)
@@ -651,13 +701,15 @@ async function cmdNew({ rootDir, argv, emit = true }) {
       if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = resolve(rootDir, dir);
     }
   } else if (serverComponent === 'happy-server') {
-    const spec = config.components['happy-server'];
-    if (spec && typeof spec === 'object' && spec.create) {
-      const dir = await createWorktree({ rootDir, component: 'happy-server', slug: spec.slug, remoteName: spec.remote || 'upstream' });
-      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = dir;
-    } else {
-      const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-server', spec });
-      if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = resolve(rootDir, dir);
+    if (!monorepoPinned) {
+      const spec = config.components['happy-server'];
+      if (spec && typeof spec === 'object' && spec.create) {
+        const dir = await createWorktree({ rootDir, component: 'happy-server', slug: spec.slug, remoteName: spec.remote || 'upstream' });
+        stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = dir;
+      } else {
+        const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-server', spec });
+        if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = resolve(rootDir, dir);
+      }
     }
   }
 
@@ -839,11 +891,83 @@ async function cmdEdit({ rootDir, argv }) {
     }
   };
 
-  await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
-  await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
-  if (serverComponent === 'happy-server') {
-    await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+  const existingHappy = String(next.HAPPY_STACKS_COMPONENT_DIR_HAPPY ?? '').trim();
+  const happyMonorepo = Boolean(coerceHappyMonorepoRootFromPath(existingHappy)) || Boolean(coerceHappyMonorepoRootFromPath(getComponentDir(rootDir, 'happy', process.env)));
+
+  if (happyMonorepo) {
+    const monoSpecs = [
+      { component: 'happy', spec: config.components.happy },
+      { component: 'happy-cli', spec: config.components['happy-cli'] },
+      { component: 'happy-server', spec: config.components['happy-server'] },
+    ].filter((x) => x.spec);
+
+    if (monoSpecs.length) {
+      const primary = monoSpecs[0];
+      const canon = (spec) => {
+        if (spec && typeof spec === 'object' && spec.create) {
+          const remote = String(spec.remote || 'upstream');
+          return `create:${String(spec.slug)}@${remote}`;
+        }
+        return String(spec);
+      };
+
+      let resolvedDir = '';
+      if (primary.spec && typeof primary.spec === 'object' && primary.spec.create) {
+        resolvedDir = await createWorktree({
+          rootDir,
+          component: primary.component,
+          slug: primary.spec.slug,
+          remoteName: primary.spec.remote || next.HAPPY_STACKS_STACK_REMOTE,
+        });
+      } else {
+        const dir = resolveComponentSpecToDir({ rootDir, component: primary.component, spec: primary.spec });
+        if (dir) resolvedDir = resolve(rootDir, dir);
+      }
+
+      const monoRoot = resolvedDir ? coerceHappyMonorepoRootFromPath(resolvedDir) : null;
+      if (monoRoot) {
+        for (const s of monoSpecs.slice(1)) {
+          if (canon(s.spec) !== canon(primary.spec)) {
+            throw new Error(
+              `[stack] edit: conflicting monorepo component specs.\n` +
+                `- happy: ${canon(config.components.happy)}\n` +
+                `- happy-cli: ${canon(config.components['happy-cli'])}\n` +
+                `- happy-server: ${canon(config.components['happy-server'])}\n` +
+                `Fix: in monorepo mode, pass only one of --happy/--happy-cli/--happy-server (or pass the same value for all).`
+            );
+          }
+        }
+
+        const subdir = (c) => happyMonorepoSubdirForComponent(c);
+        next.HAPPY_STACKS_COMPONENT_DIR_HAPPY = join(monoRoot, subdir('happy'));
+        next.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = join(monoRoot, subdir('happy-cli'));
+        const serverDir = join(monoRoot, subdir('happy-server'));
+        next.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = serverDir;
+        if (
+          existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma')) ||
+          existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))
+        ) {
+          next.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = serverDir;
+        }
+      } else {
+        await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
+        await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
+        await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+      }
+    } else {
+      await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
+      await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
+      await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+    }
   } else {
+    await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
+    await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
+    if (serverComponent === 'happy-server') {
+      await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+    }
+  }
+
+  if (serverComponent === 'happy-server-light') {
     await applyComponent('happy-server-light', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT', config.components['happy-server-light']);
   }
 
@@ -851,7 +975,7 @@ async function cmdEdit({ rootDir, argv }) {
   printResult({ json, data: { stackName, envPath: wrote, port, serverComponent }, text: `[stack] updated ${stackName}\n[stack] env: ${wrote}` });
 }
 
-async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {} }) {
+async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {}, background = false }) {
   await withStackEnv({
     stackName,
     extraEnv,
@@ -882,6 +1006,29 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
       // True restart = there was an active runner for this stack. If the stack is not running,
       // `--restart` should behave like a normal start (allocate new ephemeral ports if needed).
       const isTrueRestart = wantsRestart && wasRunning;
+
+      // Restart semantics (stack mode):
+      // - Stop stack-owned processes first (runner, daemon, Expo, etc.)
+      // - Never kill arbitrary port listeners
+      // - Preserve previous runtime ports in memory so a true restart can reuse them
+      if (wantsRestart && !wantsJson) {
+        const baseDir = resolveStackEnvPath(stackName).baseDir;
+        try {
+          await stopStackWithEnv({
+            rootDir,
+            stackName,
+            baseDir,
+            env,
+            json: false,
+            noDocker: false,
+            aggressive: false,
+            sweepOwned: true,
+          });
+        } catch {
+          // ignore (fail-closed below on port checks)
+        }
+        await deleteStackRuntimeStateFile(runtimeStatePath).catch(() => {});
+      }
       if (wasRunning) {
         if (!wantsRestart) {
           const serverPart = Number.isFinite(existingPort) && existingPort > 0 ? ` server=${existingPort}` : '';
@@ -913,12 +1060,16 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
           } else if (scriptPath === 'dev.mjs') {
             console.log(`[stack] ${stackName}: ui: unknown (missing expo.webPort in stack.runtime.json)`);
           }
+
+          // Opt-in: allow starting mobile Metro alongside an already-running stack without restarting the runner.
+          // This is important for workflows like re-running `setup-pr` with --mobile after the stack is already up.
+          const wantsMobile = args.includes('--mobile') || args.includes('--with-mobile');
+          if (wantsMobile) {
+            await run(process.execPath, [join(rootDir, 'scripts', 'mobile.mjs'), '--metro'], { cwd: rootDir, env });
+          }
           return;
         }
-        // Restart: stop the existing runner first.
-        await killPidOwnedByStack(existingOwnerPid, { stackName, envPath, cliHomeDir: (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? '').toString(), label: 'runner', json: false });
-        // Clear runtime state so we don't keep stale process PIDs; we'll re-create it for the new run below.
-        await deleteStackRuntimeStateFile(runtimeStatePath);
+        // Restart: already handled above (stopStackWithEnv is ownership-gated).
       }
 
       // Ephemeral ports: allocate at start time, store only in runtime state (not in stack env).
@@ -941,7 +1092,7 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
           }
         }
 
-        const startPort = getDefaultPortStart();
+        const startPort = getDefaultPortStart(stackName);
         const ports = {};
 
         const parsePortOrNull = (v) => {
@@ -986,6 +1137,42 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
           for (const p of toCheck) {
             // eslint-disable-next-line no-await-in-loop
             if (!(await isTcpPortFree(p))) {
+              if (isTrueRestart && !wantsJson) {
+                // Try one more safe cleanup of stack-owned processes and re-check.
+                const baseDir = resolveStackEnvPath(stackName).baseDir;
+                try {
+                  await stopStackWithEnv({
+                    rootDir,
+                    stackName,
+                    baseDir,
+                    env,
+                    json: false,
+                    noDocker: false,
+                    aggressive: false,
+                    sweepOwned: true,
+                  });
+                } catch {
+                  // ignore
+                }
+                // eslint-disable-next-line no-await-in-loop
+                if (await isTcpPortFree(p)) {
+                  continue;
+                }
+
+                // Last resort: if we can prove the listener is stack-owned, kill it.
+                // eslint-disable-next-line no-await-in-loop
+                const pids = await listListenPids(p);
+                const stackBaseDir = resolveStackEnvPath(stackName).baseDir;
+                const cliHomeDir = getCliHomeDirFromEnvOrDefault({ stackBaseDir, env });
+                for (const pid of pids) {
+                  // eslint-disable-next-line no-await-in-loop
+                  await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: `port:${p}`, json: false });
+                }
+                // eslint-disable-next-line no-await-in-loop
+                if (await isTcpPortFree(p)) {
+                  continue;
+                }
+              }
               throw new Error(
                 `[stack] ${stackName}: cannot reuse port ${p} on restart (port is not free).\n` +
                   `[stack] Fix: stop the process using it, or re-run without --restart to allocate new ports.`
@@ -1043,13 +1230,61 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
             : {}),
         };
 
+        // Background dev auth flow (automatic):
+        // If we're starting `dev.mjs` in background and the stack is not authenticated yet,
+        // keep the stack alive for guided login by marking this as an auth-flow so URL resolution
+        // fails closed (never opens server port as "UI").
+        //
+        // IMPORTANT:
+        // We must NOT start the daemon before credentials exist in orchestrated flows (setup-pr/review-pr),
+        // because the daemon can enter its own auth flow and become stranded (lock held, no machine registration).
+        if (background && scriptPath === 'dev.mjs') {
+          const startUi = !args.includes('--no-ui') && (env.HAPPY_LOCAL_UI ?? '1').toString().trim() !== '0';
+          const startDaemon = !args.includes('--no-daemon') && (env.HAPPY_LOCAL_DAEMON ?? '1').toString().trim() !== '0';
+          if (startUi && startDaemon) {
+            try {
+              const stackBaseDir = resolveStackEnvPath(stackName).baseDir;
+              const cliHomeDir = getCliHomeDirFromEnvOrDefault({ stackBaseDir, env });
+              const hasCreds = existsSync(join(cliHomeDir, 'access.key'));
+              if (!hasCreds) {
+                childEnv.HAPPY_STACKS_AUTH_FLOW = '1';
+                childEnv.HAPPY_LOCAL_AUTH_FLOW = '1';
+              }
+            } catch {
+              // If we can't resolve CLI home dir, skip auto auth-flow markers (best-effort).
+            }
+          }
+        }
+
+        // Background mode: send runner output to a stack-scoped log file so quiet flows can
+        // remain clean while still providing actionable error logs.
+        const stackBaseDir = resolveStackEnvPath(stackName).baseDir;
+        const logsDir = join(stackBaseDir, 'logs');
+        const logPath = join(logsDir, `${scriptPath.replace(/\.mjs$/, '')}.${Date.now()}.log`);
+        if (background) {
+          await ensureDir(logsDir);
+        }
+
+        let logHandle = null;
+        let outFd = null;
+        if (background) {
+          logHandle = await open(logPath, 'a');
+          outFd = logHandle.fd;
+        }
+
         // Spawn the runner (long-lived) and record its pid + ports for other stack-scoped commands.
         const child = spawn(process.execPath, [join(rootDir, 'scripts', scriptPath), ...args], {
           cwd: rootDir,
           env: childEnv,
-          stdio: 'inherit',
+          stdio: background ? ['ignore', outFd ?? 'ignore', outFd ?? 'ignore'] : 'inherit',
           shell: false,
+          detached: background && process.platform !== 'win32',
         });
+        try {
+          await logHandle?.close();
+        } catch {
+          // ignore
+        }
 
         // Record the chosen ports immediately (before the runner finishes booting), so other stack commands
         // can resolve the correct endpoints and `--restart` can reliably reuse the same ports.
@@ -1059,8 +1294,104 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
           ephemeral: true,
           ownerPid: child.pid,
           ports,
+          ...(background ? { logs: { runner: logPath } } : {}),
         }).catch(() => {});
 
+        if (background) {
+          // Keep stack.runtime.json so stack-scoped stop/restart can manage this runner.
+          // This mode is used by higher-level commands that want to run guided auth steps
+          // without mixing them into server logs.
+          const internalServerUrl = `http://127.0.0.1:${ports.server}`;
+
+          // Fail fast if the runner dies immediately or never exposes HTTP.
+          // IMPORTANT: do not treat "some process answered /health" as success unless our runner
+          // is still alive. Otherwise, if the chosen port is already in use, the runner can exit
+          // and a different stack/process could satisfy the health check (leading to confusing
+          // follow-on behavior like auth using the wrong port).
+          try {
+            let exited = null;
+            const exitPromise = new Promise((resolvePromise) => {
+              child.once('exit', (code, sig) => {
+                exited = { kind: 'exit', code: code ?? 0, sig: sig ?? null };
+                resolvePromise(exited);
+              });
+              child.once('error', (err) => {
+                exited = { kind: 'error', error: err instanceof Error ? err.message : String(err) };
+                resolvePromise(exited);
+              });
+            });
+            const readyPromise = (async () => {
+              const timeoutMsRaw =
+                (process.env.HAPPY_STACKS_STACK_BACKGROUND_READY_TIMEOUT_MS ??
+                  process.env.HAPPY_LOCAL_STACK_BACKGROUND_READY_TIMEOUT_MS ??
+                  '180000')
+                  .toString()
+                  .trim();
+              const timeoutMs = timeoutMsRaw ? Number(timeoutMsRaw) : 180_000;
+              await waitForHttpOk(`${internalServerUrl}/health`, {
+                timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 180_000,
+                intervalMs: 300,
+              });
+              return { kind: 'ready' };
+            })();
+
+            const first = await Promise.race([exitPromise, readyPromise]);
+            if (first.kind !== 'ready') {
+              throw new Error(`[stack] ${stackName}: runner exited before becoming ready. log: ${logPath}`);
+            }
+            // Even if /health responded, ensure our runner is still alive.
+            // (Prevents false positives when another process owns the port.)
+            if (exited && exited.kind !== 'ready') {
+              throw new Error(`[stack] ${stackName}: runner reported ready but exited immediately. log: ${logPath}`);
+            }
+            if (!isPidAlive(child.pid)) {
+              throw new Error(
+                `[stack] ${stackName}: runner health check passed, but runner is not running.\n` +
+                  `[stack] This usually means the chosen port (${ports.server}) is already in use by another process.\n` +
+                  `[stack] log: ${logPath}`
+              );
+            }
+          } catch (e) {
+            // Attach some log context so failures are debuggable even when a higher-level
+            // command cleans up the sandbox directory afterwards.
+            try {
+              const tail = await readLastLines(logPath, 160);
+              if (tail && e instanceof Error) {
+                e.message = `${e.message}\n\n[stack] last runner log lines:\n${tail}`;
+              }
+            } catch {
+              // ignore
+            }
+            // Best-effort cleanup on boot failure.
+            try {
+              // We spawned this runner process, so we can safely terminate it without relying
+              // on ownership heuristics (which can be unreliable on some platforms due to `ps` truncation).
+              if (background && process.platform !== 'win32') {
+                try {
+                  process.kill(-child.pid, 'SIGTERM');
+                } catch {
+                  // ignore
+                }
+              }
+              try {
+                child.kill('SIGTERM');
+              } catch {
+                // ignore
+              }
+            } catch {
+              // ignore
+            }
+            await deleteStackRuntimeStateFile(runtimeStatePath).catch(() => {});
+            throw e;
+          }
+
+          if (!wantsJson) {
+            console.log(`[stack] ${stackName}: logs: ${logPath}`);
+          }
+          try { child.unref(); } catch { /* ignore */ }
+          return;
+        }
+
         try {
           await new Promise((resolvePromise, rejectPromise) => {
             child.on('error', rejectPromise);
@@ -1079,6 +1410,28 @@ async function cmdRunScript({ rootDir, stackName, scriptPath, args, extraEnv = {
       }
 
       // Pinned port stack: run normally under the pinned env.
+      if (background) {
+        throw new Error('[stack] --background is only supported for ephemeral-port stacks');
+      }
+      if (wantsRestart && !wantsJson) {
+        const pinnedPort = coercePort(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
+        if (pinnedPort && !(await isTcpPortFree(pinnedPort))) {
+          // Last resort: kill listener only if it is stack-owned.
+          const pids = await listListenPids(pinnedPort);
+          const stackBaseDir = resolveStackEnvPath(stackName).baseDir;
+          const cliHomeDir = getCliHomeDirFromEnvOrDefault({ stackBaseDir, env });
+          for (const pid of pids) {
+            // eslint-disable-next-line no-await-in-loop
+            await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: `port:${pinnedPort}`, json: false });
+          }
+          if (!(await isTcpPortFree(pinnedPort))) {
+            throw new Error(
+              `[stack] ${stackName}: server port ${pinnedPort} is not free on restart.\n` +
+                `[stack] Refusing to kill unknown listeners. Stop the process using it, or change the pinned port.`
+            );
+          }
+        }
+      }
       await run(process.execPath, [join(rootDir, 'scripts', scriptPath), ...args], { cwd: rootDir, env });
     },
   });
@@ -1122,9 +1475,25 @@ async function cmdService({ rootDir, stackName, svcCmd }) {
   });
 }
 
+async function getRuntimePortExtraEnv(stackName) {
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  const runtimePort = Number(runtimeState?.ports?.server);
+  return Number.isFinite(runtimePort) && runtimePort > 0
+    ? {
+        // Ephemeral stacks (PR stacks) store their chosen ports in stack.runtime.json, not the env file.
+        // Ensure stack-scoped commands that compute URLs don't fall back to 3005 (main default).
+        HAPPY_STACKS_SERVER_PORT: String(runtimePort),
+        HAPPY_LOCAL_SERVER_PORT: String(runtimePort),
+      }
+    : null;
+}
+
 async function cmdTailscale({ rootDir, stackName, subcmd, args }) {
+  const extraEnv = await getRuntimePortExtraEnv(stackName);
   await withStackEnv({
     stackName,
+    ...(extraEnv ? { extraEnv } : {}),
     fn: async ({ env }) => {
       await run(process.execPath, [join(rootDir, 'scripts', 'tailscale.mjs'), subcmd, ...args], { cwd: rootDir, env });
     },
@@ -1146,7 +1515,21 @@ async function cmdWt({ rootDir, stackName, args }) {
   // Forward to scripts/worktrees.mjs under the stack env.
   // This makes `happys stack wt <name> -- ...` behave exactly like `happys wt ...`,
   // but read/write the stack env file (HAPPY_STACKS_ENV_FILE / legacy: HAPPY_LOCAL_ENV_FILE) instead of repo env.local.
-  const forwarded = args[0] === '--' ? args.slice(1) : args;
+  let forwarded = args[0] === '--' ? args.slice(1) : args;
+
+  // Stack users usually want to see what *this stack* is using (active checkout),
+  // not an exhaustive enumeration of every worktree on disk.
+  //
+  // `happys wt list` defaults to showing all worktrees. In stack mode, default to
+  // an active-only view unless the caller opts into `--all`.
+  if (forwarded[0] === 'list') {
+    const wantsAll = forwarded.includes('--all') || forwarded.includes('--all-worktrees');
+    const wantsActive = forwarded.includes('--active') || forwarded.includes('--active-only');
+    if (!wantsAll && !wantsActive) {
+      forwarded = [...forwarded, '--active'];
+    }
+  }
+
   await withStackEnv({
     stackName,
     fn: async ({ env }) => {
@@ -1159,8 +1542,10 @@ async function cmdAuth({ rootDir, stackName, args }) {
   // Forward to scripts/auth.mjs under the stack env.
   // This makes `happys stack auth <name> ...` resolve CLI home/urls for that stack.
   const forwarded = args[0] === '--' ? args.slice(1) : args;
+  const extraEnv = await getRuntimePortExtraEnv(stackName);
   await withStackEnv({
     stackName,
+    ...(extraEnv ? { extraEnv } : {}),
     fn: async ({ env }) => {
       await run(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), ...forwarded], { cwd: rootDir, env });
     },
@@ -1795,7 +2180,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
 
         const serverPort = await pickNextFreeTcpPort(3005, { host: '127.0.0.1' });
         const internalServerUrl = `http://127.0.0.1:${serverPort}`;
-        const publicServerUrl = `http://localhost:${serverPort}`;
+        const publicServerUrl = await preferStackLocalhostUrl(`http://localhost:${serverPort}`, { stackName: name });
 
         const autostart = { stackName: name, baseDir: resolveStackEnvPath(name).baseDir };
         const children = [];
@@ -1815,9 +2200,14 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
               serverComponent === 'happy-server'
                 ? env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER
                 : env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT;
-            const resolvedServerDir = serverDir || getComponentDir(rootDir, serverComponent);
-            const resolvedCliDir = env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI || getComponentDir(rootDir, 'happy-cli');
-            const resolvedUiDir = env.HAPPY_STACKS_COMPONENT_DIR_HAPPY || getComponentDir(rootDir, 'happy');
+            const resolvedServerDir =
+              (serverDir ?? env.HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER ?? env.HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT ?? '').toString().trim() ||
+              getComponentDir(rootDir, serverComponent);
+            const resolvedCliDir =
+              (env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI ?? env.HAPPY_LOCAL_COMPONENT_DIR_HAPPY_CLI ?? '').toString().trim() ||
+              getComponentDir(rootDir, 'happy-cli');
+            const resolvedUiDir =
+              (env.HAPPY_STACKS_COMPONENT_DIR_HAPPY ?? env.HAPPY_LOCAL_COMPONENT_DIR_HAPPY ?? '').toString().trim() || getComponentDir(rootDir, 'happy');
 
             await requireDir(serverComponent, resolvedServerDir);
             await requireDir('happy-cli', resolvedCliDir);
@@ -1844,9 +2234,10 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
               });
               serverProc = started.serverProc;
 
-              // Start Expo web UI so /terminal/connect exists for happy-cli web auth.
-              const uiRes = await startDevExpoWebUi({
+              // Start Expo (web) so /terminal/connect exists for happy-cli web auth.
+              const uiRes = await ensureDevExpoServer({
                 startUi: true,
+                startMobile: false,
                 uiDir: resolvedUiDir,
                 autostart,
                 baseEnv: env,
@@ -1865,10 +2256,9 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
               }
 
               console.log('');
-              const uiHost = resolveLocalhostHost({ stackMode: true, stackName: name });
               const uiPort = uiRes?.port;
-              const uiRoot = Number.isFinite(uiPort) && uiPort > 0 ? `http://${uiHost}:${uiPort}` : null;
               const uiRootLocalhost = Number.isFinite(uiPort) && uiPort > 0 ? `http://localhost:${uiPort}` : null;
+              const uiRoot = uiRootLocalhost ? await preferStackLocalhostUrl(uiRootLocalhost, { stackName: name }) : null;
               const uiSettings = uiRoot ? `${uiRoot}/settings/account` : null;
 
               console.log('[stack] step 1/3: create a dev-auth account in the UI (this generates the dev key)');
@@ -2001,6 +2391,150 @@ async function readStackEnvObject(stackName) {
   return { envPath, env };
 }
 
+function getTodayYmd() {
+  const now = new Date();
+  const y = String(now.getFullYear());
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+async function cmdArchiveStack({ rootDir, argv, stackName }) {
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  const dryRun = flags.has('--dry-run');
+  const date = (kv.get('--date') ?? '').toString().trim() || getTodayYmd();
+
+  if (!stackExistsSync(stackName)) {
+    throw new Error(`[stack] archive: stack does not exist: ${stackName}`);
+  }
+
+  const { env } = await readStackEnvObject(stackName);
+  const serverComponent = parseServerComponentFromEnv(env);
+  const components = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
+
+  const componentsDir = getComponentsDir(rootDir);
+  const workspaceDir = dirname(componentsDir);
+  const worktreesRoot = join(componentsDir, '.worktrees');
+
+  // Collect unique git worktree roots referenced by this stack.
+  const byRoot = new Map();
+  for (const component of components) {
+    const key = envKeyForComponentDir({ serverComponent, component });
+    const legacyKey = key.replace('HAPPY_STACKS_', 'HAPPY_LOCAL_');
+    const raw = (env[key] ?? env[legacyKey] ?? '').toString().trim();
+    if (!raw) continue;
+    const abs = isAbsolute(raw) ? raw : resolve(workspaceDir, raw);
+    // Only archive paths that live under components/.worktrees/.
+    const rel = relative(worktreesRoot, abs);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) continue;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const top = (await runCapture('git', ['rev-parse', '--show-toplevel'], { cwd: abs })).trim();
+      if (!top) continue;
+      if (!byRoot.has(top)) {
+        byRoot.set(top, { component, dir: top });
+      }
+    } catch {
+      // ignore invalid git dirs
+    }
+  }
+
+  const { baseDir } = resolveStackEnvPath(stackName);
+  const destStackDir = join(dirname(baseDir), '.archived', date, stackName);
+
+  // Safety: avoid archiving a worktree that is still actively referenced by other stacks.
+  // If we did, we'd break those stacks by moving their active checkout.
+  if (!dryRun && byRoot.size) {
+    const otherStacks = new Map(); // envPath -> Set(keys)
+    const otherNames = new Set();
+
+    for (const wt of byRoot.values()) {
+      // eslint-disable-next-line no-await-in-loop
+      const out = await runCapture(
+        process.execPath,
+        [join(rootDir, 'scripts', 'worktrees.mjs'), 'archive', wt.component, wt.dir, '--dry-run', `--date=${date}`, '--json'],
+        { cwd: rootDir, env: process.env }
+      );
+      const info = JSON.parse(out);
+      const linked = Array.isArray(info.linkedStacks) ? info.linkedStacks : [];
+      for (const s of linked) {
+        if (!s?.name || s.name === stackName) continue;
+        otherNames.add(s.name);
+        const envPath = String(s.envPath ?? '').trim();
+        if (!envPath) continue;
+        const set = otherStacks.get(envPath) ?? new Set();
+        for (const k of Array.isArray(s.keys) ? s.keys : []) {
+          if (k) set.add(String(k));
+        }
+        otherStacks.set(envPath, set);
+      }
+    }
+
+    if (otherNames.size) {
+      const names = Array.from(otherNames).sort().join(', ');
+      if (json || !isTty()) {
+        throw new Error(`[stack] archive: worktree(s) are still referenced by other stacks: ${names}. Resolve first (detach or archive those stacks).`);
+      }
+
+      const action = await withRl(async (rl) => {
+        return await promptSelect(rl, {
+          title: `Worktree(s) referenced by "${stackName}" are still in use by other stacks: ${names}`,
+          options: [
+            { label: 'abort (recommended)', value: 'abort' },
+            { label: 'detach those stacks from the shared worktree(s)', value: 'detach' },
+            { label: 'archive the linked stacks as well', value: 'archive-stacks' },
+          ],
+          defaultIndex: 0,
+        });
+      });
+
+      if (action === 'abort') {
+        throw new Error('[stack] archive aborted');
+      }
+      if (action === 'archive-stacks') {
+        for (const name of Array.from(otherNames).sort()) {
+          // eslint-disable-next-line no-await-in-loop
+          await run(process.execPath, [join(rootDir, 'scripts', 'stack.mjs'), 'archive', name, `--date=${date}`], { cwd: rootDir, env: process.env });
+        }
+      } else {
+        for (const [envPath, keys] of otherStacks.entries()) {
+          // eslint-disable-next-line no-await-in-loop
+          await ensureEnvFilePruned({ envPath, removeKeys: Array.from(keys) });
+        }
+      }
+    }
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      stackName,
+      date,
+      stackBaseDir: baseDir,
+      archivedStackDir: destStackDir,
+      worktrees: Array.from(byRoot.values()),
+    };
+  }
+
+  await mkdir(dirname(destStackDir), { recursive: true });
+  await rename(baseDir, destStackDir);
+
+  const archivedWorktrees = [];
+  for (const wt of byRoot.values()) {
+    if (!existsSync(wt.dir)) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const out = await runCapture(process.execPath, [join(rootDir, 'scripts', 'worktrees.mjs'), 'archive', wt.component, wt.dir, `--date=${date}`, '--json'], {
+      cwd: rootDir,
+      env: process.env,
+    });
+    archivedWorktrees.push(JSON.parse(out));
+  }
+
+  return { ok: true, dryRun: false, stackName, date, archivedStackDir: destStackDir, archivedWorktrees };
+}
+
 function envKeyForComponentDir({ serverComponent, component }) {
   if (component === 'happy') return 'HAPPY_STACKS_COMPONENT_DIR_HAPPY';
   if (component === 'happy-cli') return 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI';
@@ -2058,14 +2592,14 @@ async function cmdDuplicate({ rootDir, argv }) {
     if (!rawDir) continue;
 
     let nextDir = rawDir;
-    if (duplicateWorktrees && isComponentWorktreePath({ rootDir, component, dir: rawDir })) {
-      const spec = worktreeSpecFromDir({ rootDir, component, dir: rawDir });
+    if (duplicateWorktrees && isComponentWorktreePath({ rootDir, component, dir: rawDir, env: fromEnv })) {
+      const spec = worktreeSpecFromDir({ rootDir, component, dir: rawDir, env: fromEnv });
       if (spec) {
         const [owner, ...restParts] = spec.split('/').filter(Boolean);
         const rest = restParts.join('/');
         const slug = `dup/${sanitizeSlugPart(toStack)}/${rest}`;
 
-        const repoDir = join(getComponentsDir(rootDir), component);
+        const repoDir = join(getComponentsDir(rootDir, fromEnv), component);
         const remoteName = await inferRemoteNameForOwner({ repoDir, owner });
         // Base on the existing worktree's HEAD/branch so we get the same commit.
         nextDir = await createWorktreeFromBaseWorktree({
@@ -2075,6 +2609,7 @@ async function cmdDuplicate({ rootDir, argv }) {
           baseWorktreeSpec: spec,
           remoteName,
           depsMode,
+          env: fromEnv,
         });
       }
     }
@@ -2160,28 +2695,29 @@ async function cmdPrStack({ rootDir, argv }) {
       json,
       data: {
         usage:
-          'happys stack pr <name> --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--happy-server=<pr-url|number>|--happy-server-light=<pr-url|number>] [--server=happy-server|happy-server-light] [--remote=upstream] [--deps=none|link|install|link-or-install] [--seed-auth] [--copy-auth-from=<stack>] [--with-infra] [--auth-force] [--dev|--start] [--json] [-- <stack dev/start args...>]',
+          'happys stack pr <name> --happy=<pr-url|number> [--happy-server-light=<pr-url|number>] [--server=happy-server|happy-server-light] [--remote=upstream] [--deps=none|link|install|link-or-install] [--seed-auth] [--copy-auth-from=<stack>] [--with-infra] [--auth-force] [--dev|--start] [--background] [--mobile] [--expo-tailscale] [--json] [-- <stack dev/start args...>]',
       },
       text: [
         '[stack] usage:',
-        '  happys stack pr <name> --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev|--start]',
-        '    [--seed-auth] [--copy-auth-from=<stack|legacy>] [--link-auth] [--with-infra] [--auth-force]',
-        '    [--remote=upstream] [--deps=none|link|install|link-or-install] [--update] [--force]',
+        '  happys stack pr <name> --happy=<pr-url|number> [--happy-server-light=<pr-url|number>] [--dev|--start]',
+        '    [--seed-auth] [--copy-auth-from=<stack>] [--link-auth] [--with-infra] [--auth-force]',
+        '    [--remote=upstream] [--deps=none|link|install|link-or-install] [--update] [--force] [--background]',
+        '    [--mobile]         # also start Expo dev-client Metro for mobile',
+        '    [--expo-tailscale] # forward Expo to Tailscale interface for remote access',
         '    [--json] [-- <stack dev/start args...>]',
         '',
         'examples:',
         '  # Create stack + check out PRs + start dev UI',
         '  happys stack pr pr123 \\',
         '    --happy=https://github.com/slopus/happy/pull/123 \\',
-        '    --happy-cli=https://github.com/slopus/happy-cli/pull/456 \\',
         '    --seed-auth --copy-auth-from=dev-auth \\',
         '    --dev',
         '',
         '  # Use numeric PR refs (remote defaults to upstream)',
-        '  happys stack pr pr123 --happy=123 --happy-cli=456 --seed-auth --copy-auth-from=dev-auth --dev',
+        '  happys stack pr pr123 --happy=123 --seed-auth --copy-auth-from=dev-auth --dev',
         '',
         '  # Reuse an existing non-stacks Happy install for auth seeding',
-        '  happys stack pr pr123 --happy=123 --seed-auth --copy-auth-from=legacy --link-auth --dev',
+        '  (deprecated) legacy ~/.happy is not supported for reliable seeding',
         '',
         'notes:',
         '  - This composes existing commands: `happys stack new`, `happys stack wt ...`, and `happys stack auth ...`',
@@ -2209,7 +2745,7 @@ async function cmdPrStack({ rootDir, argv }) {
     );
   }
 
-  const remoteName = (kv.get('--remote') ?? '').trim() || 'upstream';
+  const remoteNameFromArg = (kv.get('--remote') ?? '').trim();
   const depsMode = (kv.get('--deps') ?? '').trim();
 
   const prHappy = (kv.get('--happy') ?? '').trim();
@@ -2226,6 +2762,22 @@ async function cmdPrStack({ rootDir, argv }) {
     throw new Error('[stack] pr: cannot specify both --happy-server and --happy-server-light');
   }
 
+  const happyMonorepoActive = Boolean(coerceHappyMonorepoRootFromPath(getComponentDir(rootDir, 'happy', process.env)));
+  if (happyMonorepoActive) {
+    if (prCli) {
+      throw new Error(
+        '[stack] pr: --happy-cli is not supported when using the slopus/happy monorepo.\n' +
+          'Fix: use --happy=<pr> to pin the monorepo (UI + CLI + server) in one worktree.'
+      );
+    }
+    if (prServer) {
+      throw new Error(
+        '[stack] pr: --happy-server is not supported when using the slopus/happy monorepo.\n' +
+          'Fix: use --happy=<pr> to pin the monorepo (UI + CLI + server) in one worktree.'
+      );
+    }
+  }
+
   const serverFromArg = (kv.get('--server') ?? '').trim();
   const inferredServer = prServer ? 'happy-server' : prServerLight ? 'happy-server-light' : '';
   const serverComponent = (serverFromArg || inferredServer || 'happy-server-light').trim();
@@ -2239,6 +2791,10 @@ async function cmdPrStack({ rootDir, argv }) {
     throw new Error('[stack] pr: choose either --dev or --start (not both)');
   }
 
+  const wantsMobile = flags.has('--mobile') || flags.has('--with-mobile');
+  const wantsExpoTailscale = flags.has('--expo-tailscale');
+  const background = flags.has('--background') || flags.has('--bg') || (kv.get('--background') ?? '').trim() === '1';
+
   const seedAuthFlag = flags.has('--seed-auth') ? true : flags.has('--no-seed-auth') ? false : null;
   const authFromFlag = (kv.get('--copy-auth-from') ?? '').trim();
   const withInfra = flags.has('--with-infra') || flags.has('--ensure-infra') || flags.has('--infra');
@@ -2367,14 +2923,22 @@ async function cmdPrStack({ rootDir, argv }) {
   }
 
   // 2) Checkout PR worktrees and pin them to the stack env file.
-  const prSpecs = [
-    { component: 'happy', pr: prHappy },
-    { component: 'happy-cli', pr: prCli },
-    ...(serverComponent === 'happy-server' ? [{ component: 'happy-server', pr: prServer }] : []),
-    ...(serverComponent === 'happy-server-light' ? [{ component: 'happy-server-light', pr: prServerLight }] : []),
-  ].filter((x) => x.pr);
+  const prSpecs = (
+    happyMonorepoActive
+      ? [
+          ...(prHappy ? [{ component: 'happy', pr: prHappy }] : []),
+          ...(serverComponent === 'happy-server-light' && prServerLight ? [{ component: 'happy-server-light', pr: prServerLight }] : []),
+        ]
+      : [
+          ...(prHappy ? [{ component: 'happy', pr: prHappy }] : []),
+          ...(prCli ? [{ component: 'happy-cli', pr: prCli }] : []),
+          ...(serverComponent === 'happy-server' && prServer ? [{ component: 'happy-server', pr: prServer }] : []),
+          ...(serverComponent === 'happy-server-light' && prServerLight ? [{ component: 'happy-server-light', pr: prServerLight }] : []),
+        ]
+  ).filter((x) => x.pr);
 
   const worktrees = [];
+  const stackEnvPath = resolveStackEnvPath(stackName).envPath;
   for (const { component, pr } of prSpecs) {
     progress(`[stack] pr: ${stackName}: fetching PR for ${component} (${pr})...`);
     const out = await withStackEnv({
@@ -2385,7 +2949,7 @@ async function cmdPrStack({ rootDir, argv }) {
           'pr',
           component,
           pr,
-          `--remote=${remoteName}`,
+          ...(remoteNameFromArg ? [`--remote=${remoteNameFromArg}`] : []),
           '--use',
           ...(depsMode ? [`--deps=${depsMode}`] : []),
           ...(doUpdate ? ['--update'] : []),
@@ -2393,11 +2957,36 @@ async function cmdPrStack({ rootDir, argv }) {
           '--json',
         ];
         const stdout = await runCapture(process.execPath, [join(rootDir, 'scripts', 'worktrees.mjs'), ...args], { cwd: rootDir, env });
-        return stdout.trim() ? JSON.parse(stdout.trim()) : null;
+        const parsed = stdout.trim() ? JSON.parse(stdout.trim()) : null;
+
+        // Fail-closed invariant for PR stacks:
+        // If you asked to pin a component to a PR checkout, it MUST be a worktree path under
+        // the active workspace components dir (including sandbox workspace).
+        if (parsed?.path && !isComponentWorktreePath({ rootDir, component, dir: parsed.path, env })) {
+          const expectedRepoKey = parsed?.repoKey ? String(parsed.repoKey) : component;
+          throw new Error(
+            `[stack] pr: refusing to pin ${component} because the checked out path is not a worktree.\n` +
+              `- expected under: ${join(getComponentsDir(rootDir, env), '.worktrees', expectedRepoKey)}/...\n` +
+              `- actual: ${String(parsed.path ?? '').trim()}\n` +
+              `Fix: this is a bug. Please re-run with --force, or delete/recreate the stack (${stackName}).`
+          );
+        }
+
+        return parsed;
       },
     });
-    if (json) {
+    if (out) {
       worktrees.push(out);
+      // Fail-closed invariant for PR stacks:
+      // - if you asked to pin a component to a PR checkout, the stack env file MUST point at that exact worktree dir
+      //   before we start dev/start. Otherwise the stack can accidentally run the base checkout.
+      //
+      // We intentionally do NOT rely solely on `wt pr --use` for this; we make it explicit here.
+      const key = componentDirEnvKey(component);
+      await ensureEnvFileUpdated({ envPath: stackEnvPath, updates: [{ key, value: out.path }] });
+    }
+    if (json) {
+      // collected above
     } else if (out) {
       const short = (sha) => (sha ? String(sha).slice(0, 8) : '');
       const changed = Boolean(out.updated && out.oldHead && out.newHead && out.oldHead !== out.newHead);
@@ -2414,6 +3003,70 @@ async function cmdPrStack({ rootDir, argv }) {
     }
   }
 
+  // Monorepo shortcut:
+  // If `--happy=<pr>` was provided and the local checkout is the slopus/happy monorepo, pin
+  // happy-cli and (optionally) happy-server to that same worktree without fetching separate PRs.
+  if (happyMonorepoActive && prHappy) {
+    const happyWt = worktrees.find((w) => w?.component === 'happy');
+    const happyPath = String(happyWt?.path ?? '').trim();
+    const happyRoot = happyWt?.worktreeRoot ? resolve(String(happyWt.worktreeRoot)) : happyPath ? coerceHappyMonorepoRootFromPath(happyPath) : null;
+    if (!happyRoot) {
+      throw new Error('[stack] pr: expected happy monorepo worktree root but could not resolve it from the checked out path.');
+    }
+
+    const derive = (component) => {
+      const sub = happyMonorepoSubdirForComponent(component);
+      if (!sub) return null;
+      return join(happyRoot, sub);
+    };
+
+    const derivedComponents = [
+      'happy-cli',
+      ...(serverComponent === 'happy-server' ? ['happy-server'] : []),
+    ];
+
+    for (const c of derivedComponents) {
+      const p = derive(c);
+      if (!p) continue;
+      if (!isComponentWorktreePath({ rootDir, component: c, dir: p, env: process.env })) {
+        throw new Error(`[stack] pr: refusing to pin ${c} because the derived path is not a worktree: ${p}`);
+      }
+      const key = componentDirEnvKey(c);
+      await ensureEnvFileUpdated({ envPath: stackEnvPath, updates: [{ key, value: p }] });
+      worktrees.push({ component: c, path: p });
+    }
+  }
+
+  // Validate that all PR components are pinned correctly before starting.
+  // This prevents "wrong daemon" / "wrong UI" errors that are otherwise extremely confusing in review-pr.
+  if (prSpecs.length) {
+    const afterRaw = await readExistingEnv(stackEnvPath);
+    const afterEnv = parseEnvToObject(afterRaw);
+    for (const wt of worktrees) {
+      const key = componentDirEnvKey(wt.component);
+      const val = (afterEnv[key] ?? '').toString().trim();
+      const expected = resolve(String(wt.path ?? '').trim());
+      const actual = val ? resolve(val) : '';
+      if (!actual) {
+        throw new Error(
+          `[stack] pr: failed to pin ${wt.component} to the PR checkout.\n` +
+            `- missing env key: ${key}\n` +
+            `- expected: ${expected}\n` +
+            `Fix: re-run with --force, or delete/recreate the stack (${stackName}).`
+        );
+      }
+      if (expected && actual !== expected) {
+        throw new Error(
+          `[stack] pr: stack is pinned to the wrong checkout for ${wt.component}.\n` +
+            `- env key: ${key}\n` +
+            `- expected: ${expected}\n` +
+            `- actual:   ${actual}\n` +
+            `Fix: re-run with --force, or delete/recreate the stack (${stackName}).`
+        );
+      }
+    }
+  }
+
   // 3) Optional: seed auth (copies cli creds + master secret + DB Account rows).
   let auth = null;
   if (seedAuth) {
@@ -2426,8 +3079,10 @@ async function cmdPrStack({ rootDir, argv }) {
       ...(authLink ? ['--link'] : []),
     ];
     if (json) {
+      const extraEnv = await getRuntimePortExtraEnv(stackName);
       auth = await withStackEnv({
         stackName,
+        ...(extraEnv ? { extraEnv } : {}),
         fn: async ({ env }) => {
           const stdout = await runCapture(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), ...args, '--json'], { cwd: rootDir, env });
           return stdout.trim() ? JSON.parse(stdout.trim()) : null;
@@ -2442,12 +3097,20 @@ async function cmdPrStack({ rootDir, argv }) {
   // 4) Optional: start dev / start.
   if (wantsDev) {
     progress(`[stack] pr: ${stackName}: starting dev...`);
-    const args = passthrough.length ? ['--', ...passthrough] : [];
-    await cmdRunScript({ rootDir, stackName, scriptPath: 'dev.mjs', args });
+    const args = [
+      ...(wantsMobile ? ['--mobile'] : []),
+      ...(wantsExpoTailscale ? ['--expo-tailscale'] : []),
+      ...(passthrough.length ? ['--', ...passthrough] : []),
+    ];
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'dev.mjs', args, background });
   } else if (wantsStart) {
     progress(`[stack] pr: ${stackName}: starting...`);
-    const args = passthrough.length ? ['--', ...passthrough] : [];
-    await cmdRunScript({ rootDir, stackName, scriptPath: 'run.mjs', args });
+    const args = [
+      ...(wantsMobile ? ['--mobile'] : []),
+      ...(wantsExpoTailscale ? ['--expo-tailscale'] : []),
+      ...(passthrough.length ? ['--', ...passthrough] : []),
+    ];
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'run.mjs', args, background });
   }
 
   const info = await cmdInfoInternal({ rootDir, stackName });
@@ -2500,10 +3163,15 @@ async function cmdInfoInternal({ rootDir, stackName }) {
     runtimeState?.expo && typeof runtimeState.expo === 'object' && Number(runtimeState.expo.webPort) > 0
       ? Number(runtimeState.expo.webPort)
       : null;
+  const mobilePort =
+    runtimeState?.expo && typeof runtimeState.expo === 'object' && Number(runtimeState.expo.mobilePort) > 0
+      ? Number(runtimeState.expo.mobilePort)
+      : null;
 
   const host = resolveLocalhostHost({ stackMode: true, stackName });
   const internalServerUrl = serverPort ? `http://127.0.0.1:${serverPort}` : null;
   const uiUrl = uiPort ? `http://${host}:${uiPort}` : null;
+  const mobileUrl = mobilePort ? await preferStackLocalhostUrl(`http://localhost:${mobilePort}`, { stackName }) : null;
 
   const componentSpecs = [
     { component: 'happy', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY'] },
@@ -2546,11 +3214,13 @@ async function cmdInfoInternal({ rootDir, stackName }) {
       host,
       internalServerUrl,
       uiUrl,
+      mobileUrl,
     },
     ports: {
       server: serverPort,
       backend: backendPort,
       ui: uiPort,
+      mobile: mobilePort,
     },
     components,
   };
@@ -2609,19 +3279,25 @@ async function main() {
           'list',
           'migrate',
           'audit',
-        'duplicate',
+          'archive',
+          'duplicate',
           'info',
           'pr',
           'create-dev-auth-seed',
+          'happy',
+          'env',
           'auth',
           'dev',
           'start',
           'build',
+          'review',
           'typecheck',
           'lint',
           'test',
           'doctor',
           'mobile',
+        'mobile:install',
+        'mobile-dev-client',
           'resume',
           'stop',
           'code',
@@ -2635,24 +3311,30 @@ async function main() {
       },
       text: [
         '[stack] usage:',
-        '  happys stack new <name> [--port=NNN] [--server=happy-server|happy-server-light] [--happy=default|<owner/...>|<path>] [--happy-cli=...] [--interactive] [--copy-auth-from=<stack>] [--no-copy-auth] [--force-port] [--json]',
+        '  happys stack new <name> [--port=NNN] [--server=happy-server|happy-server-light] [--happy=default|<owner/...>|<path>] [--interactive] [--copy-auth-from=<stack>] [--no-copy-auth] [--force-port] [--json]',
         '  happys stack edit <name> --interactive [--json]',
         '  happys stack list [--json]',
         '  happys stack migrate [--json]   # copy legacy env files from ~/.happy/local/stacks/* -> ~/.happy/stacks/*',
         '  happys stack audit [--fix] [--fix-main] [--fix-ports] [--fix-workspace] [--fix-paths] [--unpin-ports] [--unpin-ports-except=stack1,stack2] [--json]',
+        '  happys stack archive <name> [--dry-run] [--date=YYYY-MM-DD] [--json]',
         '  happys stack duplicate <from> <to> [--duplicate-worktrees] [--deps=none|link|install|link-or-install] [--json]',
         '  happys stack info <name> [--json]',
-        '  happys stack pr <name> --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev|--start] [--json] [-- ...]',
+        '  happys stack pr <name> --happy=<pr-url|number> [--happy-server-light=<pr-url|number>] [--dev|--start] [--json] [-- ...]',
         '  happys stack create-dev-auth-seed [name] [--server=happy-server|happy-server-light] [--non-interactive] [--json]',
+        '  happys stack happy <name> [-- ...]',
+        '  happys stack env <name> set KEY=VALUE [KEY2=VALUE2...] | unset KEY [KEY2...] | get KEY | list | path [--json]',
         '  happys stack auth <name> status|login|copy-from [--json]',
         '  happys stack dev <name> [-- ...]',
         '  happys stack start <name> [-- ...]',
         '  happys stack build <name> [-- ...]',
+        '  happys stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--chunks|--no-chunks] [--chunking=auto|head-slice|commit-window] [--chunk-max-files=N] [--json]',
         '  happys stack typecheck <name> [component...] [--json]',
         '  happys stack lint <name> [component...] [--json]',
         '  happys stack test <name> [component...] [--json]',
         '  happys stack doctor <name> [-- ...]',
         '  happys stack mobile <name> [-- ...]',
+        '  happys stack mobile:install <name> [--name="Happy (exp1)"] [--device=...] [--json]',
+        '  happys stack mobile-dev-client <name> --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
         '  happys stack resume <name> <sessionId...> [--json]',
         '  happys stack stop <name> [--aggressive] [--sweep-owned] [--no-docker] [--json]',
         '  happys stack code <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]',
@@ -2765,6 +3447,15 @@ async function main() {
                 'example:',
                 '  happys stack srv exp1 -- status',
               ]
+          : cmd === 'env'
+            ? [
+                '[stack] usage:',
+                '  happys stack env <name> set KEY=VALUE [KEY2=VALUE2...]',
+                '  happys stack env <name> unset KEY [KEY2...]',
+                '  happys stack env <name> get KEY',
+                '  happys stack env <name> list',
+                '  happys stack env <name> path',
+              ]
             : cmd.startsWith('tailscale:')
               ? [
                   '[stack] usage:',
@@ -2785,12 +3476,51 @@ async function main() {
   // Remaining args after "<cmd> <name>"
   const passthrough = argv.slice(2);
 
+  if (cmd === 'archive') {
+    const res = await cmdArchiveStack({ rootDir, argv, stackName });
+    if (json) {
+      printResult({ json, data: res });
+    } else if (res.dryRun) {
+      console.log(`[stack] would archive "${stackName}" -> ${res.archivedStackDir} (dry-run)`);
+    } else {
+      console.log(`[stack] archived "${stackName}" -> ${res.archivedStackDir}`);
+    }
+    return;
+  }
+
+  if (cmd === 'env') {
+    const hasPositional = passthrough.some((a) => !a.startsWith('-'));
+    const envArgv = hasPositional ? passthrough : ['list', ...passthrough];
+    // Forward to scripts/env.mjs under the stack env.
+    // This keeps stack env editing behavior unified with `happys env ...`.
+    await withStackEnv({
+      stackName,
+      fn: async ({ env }) => {
+        await run(process.execPath, [join(rootDir, 'scripts', 'env.mjs'), ...envArgv], { cwd: rootDir, env });
+      },
+    });
+    return;
+  }
+  if (cmd === 'happy') {
+    const args = passthrough[0] === '--' ? passthrough.slice(1) : passthrough;
+    await withStackEnv({
+      stackName,
+      fn: async ({ env }) => {
+        await run(process.execPath, [join(rootDir, 'scripts', 'happy.mjs'), ...args], { cwd: rootDir, env });
+      },
+    });
+    return;
+  }
   if (cmd === 'dev') {
-    await cmdRunScript({ rootDir, stackName, scriptPath: 'dev.mjs', args: passthrough });
+    const background = passthrough.includes('--background') || passthrough.includes('--bg');
+    const args = background ? passthrough.filter((a) => a !== '--background' && a !== '--bg') : passthrough;
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'dev.mjs', args, background });
     return;
   }
   if (cmd === 'start') {
-    await cmdRunScript({ rootDir, stackName, scriptPath: 'run.mjs', args: passthrough });
+    const background = passthrough.includes('--background') || passthrough.includes('--bg');
+    const args = background ? passthrough.filter((a) => a !== '--background' && a !== '--bg') : passthrough;
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'run.mjs', args, background });
     return;
   }
   if (cmd === 'build') {
@@ -2817,6 +3547,12 @@ async function main() {
     await cmdRunScript({ rootDir, stackName, scriptPath: 'test.mjs', args: passthrough, extraEnv: overrides });
     return;
   }
+  if (cmd === 'review') {
+    const { kv } = parseArgs(passthrough);
+    const overrides = resolveTransientComponentOverrides({ rootDir, kv });
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'review.mjs', args: passthrough, extraEnv: overrides });
+    return;
+  }
   if (cmd === 'doctor') {
     await cmdRunScript({ rootDir, stackName, scriptPath: 'doctor.mjs', args: passthrough });
     return;
@@ -2825,6 +3561,62 @@ async function main() {
     await cmdRunScript({ rootDir, stackName, scriptPath: 'mobile.mjs', args: passthrough });
     return;
   }
+  if (cmd === 'mobile-dev-client') {
+    // Stack-scoped wrapper so the dev-client can be built from the stack's active happy checkout/worktree.
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'mobile_dev_client.mjs', args: passthrough });
+    return;
+  }
+  if (cmd === 'mobile:install') {
+    const { flags: mFlags, kv: mKv } = parseArgs(passthrough);
+    const device = (mKv.get('--device') ?? '').toString();
+    const name = (mKv.get('--name') ?? mKv.get('--app-name') ?? '').toString().trim();
+    const jsonOut = wantsJson(passthrough, { flags: mFlags }) || json;
+
+    const envPath = resolveStackEnvPath(stackName).envPath;
+    const existingRaw = await readExistingEnv(envPath);
+    const existing = parseEnvToObject(existingRaw);
+
+    const priorName =
+      (existing.HAPPY_STACKS_MOBILE_RELEASE_IOS_APP_NAME ?? existing.HAPPY_LOCAL_MOBILE_RELEASE_IOS_APP_NAME ?? '').toString().trim();
+    const identity = defaultStackReleaseIdentity({
+      stackName,
+      user: process.env.USER ?? process.env.USERNAME ?? 'user',
+      appName: name || priorName || null,
+    });
+
+    // Persist the chosen identity so re-installs are stable and user-friendly.
+    await ensureEnvFileUpdated({
+      envPath,
+      updates: [
+        { key: 'HAPPY_STACKS_MOBILE_RELEASE_IOS_APP_NAME', value: identity.iosAppName },
+        { key: 'HAPPY_STACKS_MOBILE_RELEASE_IOS_BUNDLE_ID', value: identity.iosBundleId },
+        { key: 'HAPPY_STACKS_MOBILE_RELEASE_SCHEME', value: identity.scheme },
+      ],
+    });
+
+    // Install a per-stack release-configured app (isolated container) without starting Metro.
+    const args = [
+      `--app-env=production`,
+      `--ios-app-name=${identity.iosAppName}`,
+      `--ios-bundle-id=${identity.iosBundleId}`,
+      `--scheme=${identity.scheme}`,
+      '--prebuild',
+      '--run-ios',
+      '--configuration=Release',
+      '--no-metro',
+      ...(device ? [`--device=${device}`] : []),
+    ];
+
+    await cmdRunScript({ rootDir, stackName, scriptPath: 'mobile.mjs', args });
+
+    if (jsonOut) {
+      printResult({
+        json: true,
+        data: { ok: true, stackName, installed: true, identity },
+      });
+    }
+    return;
+  }
   if (cmd === 'resume') {
     const sessionIds = passthrough.filter((a) => a && a !== '--' && !a.startsWith('--'));
     if (sessionIds.length === 0) {
@@ -2841,7 +3633,9 @@ async function main() {
     const out = await withStackEnv({
       stackName,
       fn: async ({ env }) => {
-        const cliDir = getComponentDir(rootDir, 'happy-cli');
+        // IMPORTANT: use the stack's pinned happy-cli checkout if set.
+        // Do not read component dirs from this process's `process.env` (withStackEnv does not mutate it).
+        const cliDir = (env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI ?? env.HAPPY_LOCAL_COMPONENT_DIR_HAPPY_CLI ?? '').toString().trim() || getComponentDir(rootDir, 'happy-cli');
         const happyBin = join(cliDir, 'bin', 'happy.mjs');
         // Run stack-scoped happy-cli and ask the stack daemon to resume these sessions.
         return await run(process.execPath, [happyBin, 'daemon', 'resume', ...sessionIds], { cwd: rootDir, env });