happy-stacks 0.1.0 → 0.2.0

package/scripts/menubar.mjs

@@ -3,9 +3,12 @@ import { cp, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
 
 async function ensureSwiftbarAssets({ cliRootDir }) {
   const homeDir = getHappyStacksHomeDir();
@@ -34,9 +37,20 @@ function openSwiftbarPluginsDir() {
   }
 }
 
-function removeSwiftbarPlugins() {
+function sandboxPluginBasename() {
+  const sandboxDir = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
+  if (!sandboxDir) return '';
+  const hash = createHash('sha256').update(sandboxDir).digest('hex').slice(0, 10);
+  return `happy-stacks.sandbox-${hash}`;
+}
+
+function removeSwiftbarPlugins({ patterns }) {
+  const pats = (patterns ?? []).filter(Boolean);
+  const args = pats.length ? pats.map((p) => `"${p}"`).join(' ') : '"happy-stacks.*.sh" "happy-local.*.sh"';
   const s =
-    'DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; if [[ -z "$DIR" ]]; then DIR="$HOME/Library/Application Support/SwiftBar/Plugins"; fi; if [[ -d "$DIR" ]]; then rm -f "$DIR"/happy-stacks.*.sh "$DIR"/happy-local.*.sh 2>/dev/null || true; echo "$DIR"; else echo ""; fi';
+    `DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; ` +
+    `if [[ -z "$DIR" ]]; then DIR="$HOME/Library/Application Support/SwiftBar/Plugins"; fi; ` +
+    `if [[ -d "$DIR" ]]; then rm -f "$DIR"/${args} 2>/dev/null || true; echo "$DIR"; else echo ""; fi`;
   const res = spawnSync('bash', ['-lc', s], { encoding: 'utf-8' });
   if (res.status !== 0) {
     return null;
@@ -45,6 +59,14 @@ function removeSwiftbarPlugins() {
   return out || null;
 }
 
+function normalizeMenubarMode(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (!v) return '';
+  if (v === 'selfhost' || v === 'self-host' || v === 'self_host' || v === 'host') return 'selfhost';
+  if (v === 'dev' || v === 'developer') return 'dev';
+  return '';
+}
+
 async function main() {
   const rawArgv = process.argv.slice(2);
   const argv = rawArgv[0] === 'menubar' ? rawArgv.slice(1) : rawArgv;
@@ -55,16 +77,19 @@ async function main() {
   if (wantsHelp(argv, { flags }) || cmd === 'help') {
     printResult({
       json,
-      data: { commands: ['install', 'uninstall', 'open'] },
+      data: { commands: ['install', 'uninstall', 'open', 'mode', 'status'] },
       text: [
         '[menubar] usage:',
         '  happys menubar install [--json]',
         '  happys menubar uninstall [--json]',
         '  happys menubar open [--json]',
+        '  happys menubar mode <selfhost|dev> [--json]',
+        '  happys menubar status [--json]',
         '',
         'notes:',
         '  - installs SwiftBar plugin into the active SwiftBar plugin folder',
-        '  - keeps plugin source under ~/.happy-stacks/extras/swiftbar for stability',
+        '  - keeps plugin source under <homeDir>/extras/swiftbar for stability',
+        '  - sandbox mode: install/uninstall are disabled by default (set HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1 to override)',
       ].join('\n'),
     });
     return;
@@ -82,15 +107,63 @@ async function main() {
   }
 
   if (cmd === 'menubar:uninstall' || cmd === 'uninstall') {
-    const dir = removeSwiftbarPlugins();
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      printResult({ json, data: { ok: true, skipped: 'sandbox' }, text: '[menubar] uninstall skipped (sandbox mode)' });
+      return;
+    }
+    const patterns = isSandboxed()
+      ? [`${sandboxPluginBasename()}.*.sh`]
+      : ['happy-stacks.*.sh', 'happy-local.*.sh'];
+    const dir = removeSwiftbarPlugins({ patterns });
     printResult({ json, data: { ok: true, pluginsDir: dir }, text: dir ? `[menubar] removed plugins from ${dir}` : '[menubar] no plugins dir found' });
     return;
   }
 
+  if (cmd === 'status') {
+    const mode = (process.env.HAPPY_STACKS_MENUBAR_MODE ?? process.env.HAPPY_LOCAL_MENUBAR_MODE ?? 'dev').trim() || 'dev';
+    printResult({ json, data: { ok: true, mode }, text: `[menubar] mode: ${mode}` });
+    return;
+  }
+
+  if (cmd === 'mode') {
+    const positionals = argv.filter((a) => !a.startsWith('--'));
+    const raw = positionals[1] ?? '';
+    const mode = normalizeMenubarMode(raw);
+    if (!mode) {
+      throw new Error('[menubar] usage: happys menubar mode <selfhost|dev> [--json]');
+    }
+    await ensureEnvLocalUpdated({
+      rootDir: cliRootDir,
+      updates: [
+        { key: 'HAPPY_STACKS_MENUBAR_MODE', value: mode },
+        { key: 'HAPPY_LOCAL_MENUBAR_MODE', value: mode },
+      ],
+    });
+    printResult({ json, data: { ok: true, mode }, text: `[menubar] mode set: ${mode}` });
+    return;
+  }
+
   if (cmd === 'menubar:install' || cmd === 'install') {
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      throw new Error(
+        '[menubar] install is disabled in sandbox mode.\n' +
+          'Reason: SwiftBar plugin installation writes to a global user folder.\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
     const { destDir } = await ensureSwiftbarAssets({ cliRootDir });
     const installer = join(destDir, 'install.sh');
-    const res = spawnSync('bash', [installer, '--force'], { stdio: 'inherit', env: { ...process.env, HAPPY_STACKS_HOME_DIR: getHappyStacksHomeDir() } });
+    const env = {
+      ...process.env,
+      HAPPY_STACKS_HOME_DIR: getHappyStacksHomeDir(),
+      ...(isSandboxed()
+        ? {
+            HAPPY_STACKS_SWIFTBAR_PLUGIN_BASENAME: sandboxPluginBasename(),
+            HAPPY_STACKS_SWIFTBAR_PLUGIN_WRAPPER: '1',
+          }
+        : {}),
+    };
+    const res = spawnSync('bash', [installer, '--force'], { stdio: 'inherit', env });
     if (res.status !== 0) {
       process.exit(res.status ?? 1);
     }

package/scripts/migrate.mjs

@@ -0,0 +1,302 @@
+import './utils/env.mjs';
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { parseDotenv } from './utils/dotenv.mjs';
+import { ensureEnvFileUpdated } from './utils/env_file.mjs';
+import { resolveStackEnvPath } from './utils/paths.mjs';
+import { ensureDepsInstalled } from './utils/pm.mjs';
+import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/happy_server_infra.mjs';
+import { runCapture } from './utils/proc.mjs';
+import { pickNextFreeTcpPort } from './utils/ports.mjs';
+
+function usage() {
+  return [
+    '[migrate] usage:',
+    '  happys migrate light-to-server --from-stack=<name> --to-stack=<name> [--include-files] [--force] [--json]',
+    '',
+    'Notes:',
+    '- This migrates chat data from happy-server-light (SQLite) to happy-server (Postgres).',
+    '- It preserves IDs, so existing session URLs keep working on the new server.',
+    '- If --include-files is set, it mirrors server-light local files into Minio (S3) in the target stack.',
+  ].join('\n');
+}
+
+async function readEnvObject(envPath) {
+  try {
+    const raw = await readFile(envPath, 'utf-8');
+    return Object.fromEntries(parseDotenv(raw).entries());
+  } catch {
+    return {};
+  }
+}
+
+function getEnvValue(env, key) {
+  return (env?.[key] ?? '').toString().trim();
+}
+
+function parseFileDatabaseUrl(url) {
+  const raw = String(url ?? '').trim();
+  if (!raw) return null;
+  if (raw.startsWith('file:')) {
+    const path = raw.slice('file:'.length);
+    return { url: raw, path };
+  }
+  return null;
+}
+
+async function ensureTargetSecretMatchesSource({ sourceSecretPath, targetSecretPath }) {
+  try {
+    const src = (await readFile(sourceSecretPath, 'utf-8')).trim();
+    if (!src) return null;
+    await mkdir(join(targetSecretPath, '..'), { recursive: true }).catch(() => {});
+    const { rename, writeFile } = await import('node:fs/promises');
+    // Write with a trailing newline, via atomic replace.
+    const tmp = join(join(targetSecretPath, '..'), `.handy-master-secret.${Date.now()}.tmp`);
+    await writeFile(tmp, src + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await rename(tmp, targetSecretPath);
+    return src;
+  } catch {
+    return null;
+  }
+}
+
+async function importPrismaClientFrom(dir) {
+  const req = createRequire(import.meta.url);
+  const resolved = req.resolve('@prisma/client', { paths: [dir] });
+  // eslint-disable-next-line import/no-dynamic-require
+  const mod = req(resolved);
+  return mod.PrismaClient;
+}
+
+async function migrateLightToServer({ rootDir, fromStack, toStack, includeFiles, force, json }) {
+  const from = resolveStackEnvPath(fromStack);
+  const to = resolveStackEnvPath(toStack);
+
+  const fromEnv = await readEnvObject(from.envPath);
+  const toEnv = await readEnvObject(to.envPath);
+
+  const fromFlavor = getEnvValue(fromEnv, 'HAPPY_STACKS_SERVER_COMPONENT') || getEnvValue(fromEnv, 'HAPPY_LOCAL_SERVER_COMPONENT') || 'happy-server-light';
+  const toFlavor = getEnvValue(toEnv, 'HAPPY_STACKS_SERVER_COMPONENT') || getEnvValue(toEnv, 'HAPPY_LOCAL_SERVER_COMPONENT') || 'happy-server-light';
+
+  if (fromFlavor !== 'happy-server-light') {
+    throw new Error(`[migrate] from-stack must use happy-server-light (got: ${fromFlavor})`);
+  }
+  if (toFlavor !== 'happy-server') {
+    throw new Error(`[migrate] to-stack must use happy-server (got: ${toFlavor})`);
+  }
+
+  const fromDataDir = getEnvValue(fromEnv, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(from.baseDir, 'server-light');
+  const fromFilesDir = getEnvValue(fromEnv, 'HAPPY_SERVER_LIGHT_FILES_DIR') || join(fromDataDir, 'files');
+  const fromDbUrl = getEnvValue(fromEnv, 'DATABASE_URL') || `file:${join(fromDataDir, 'happy-server-light.sqlite')}`;
+  const fromParsed = parseFileDatabaseUrl(fromDbUrl);
+  if (!fromParsed?.path) {
+    throw new Error(`[migrate] from-stack DATABASE_URL must be file:... (got: ${fromDbUrl})`);
+  }
+
+  const toPortRaw = getEnvValue(toEnv, 'HAPPY_STACKS_SERVER_PORT') || getEnvValue(toEnv, 'HAPPY_LOCAL_SERVER_PORT');
+  let toPort = toPortRaw ? Number(toPortRaw) : NaN;
+  const toEphemeral = !toPortRaw;
+  if (!Number.isFinite(toPort) || toPort <= 0) {
+    // Ephemeral-port stacks don't pin ports in env. Pick a free port for this one-off migration run.
+    toPort = await pickNextFreeTcpPort(3005);
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[migrate] to-stack has no pinned port; using ephemeral port ${toPort} for this migration run`);
+    }
+  }
+
+  // Ensure target secret is the same as source so auth tokens remain valid after migration.
+  const sourceSecretPath = join(fromDataDir, 'handy-master-secret.txt');
+  const targetSecretPath = getEnvValue(toEnv, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE') || join(to.baseDir, 'happy-server', 'handy-master-secret.txt');
+  await ensureTargetSecretMatchesSource({ sourceSecretPath, targetSecretPath });
+  await ensureEnvFileUpdated({
+    envPath: to.envPath,
+    updates: [{ key: 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE', value: targetSecretPath }],
+  });
+
+  // Resolve component dirs (prefer stack-pinned dirs).
+  const lightDir = getEnvValue(fromEnv, 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT') || getEnvValue(fromEnv, 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT');
+  const fullDir = getEnvValue(toEnv, 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER') || getEnvValue(toEnv, 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER');
+  if (!lightDir || !fullDir) {
+    throw new Error('[migrate] missing component dirs in stack env (expected HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT and HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER)');
+  }
+
+  await ensureDepsInstalled(lightDir, 'happy-server-light');
+  await ensureDepsInstalled(fullDir, 'happy-server');
+
+  // Bring up infra and ensure env vars are present.
+  const infra = await ensureHappyServerManagedInfra({
+    stackName: toStack,
+    baseDir: to.baseDir,
+    serverPort: toPort,
+    publicServerUrl: `http://127.0.0.1:${toPort}`,
+    envPath: to.envPath,
+    env: {
+      ...process.env,
+      ...(toEphemeral ? { HAPPY_STACKS_EPHEMERAL_PORTS: '1', HAPPY_LOCAL_EPHEMERAL_PORTS: '1' } : {}),
+    },
+  });
+  await applyHappyServerMigrations({ serverDir: fullDir, env: { ...process.env, ...infra.env } });
+
+  // Copy sqlite DB to a snapshot so migration is consistent even if the source server is running.
+  const snapshotDir = join(to.baseDir, 'migrations');
+  await mkdir(snapshotDir, { recursive: true });
+  const snapshotPath = join(snapshotDir, `happy-server-light.${basename(fromParsed.path)}.${Date.now()}.sqlite`);
+  await copyFile(fromParsed.path, snapshotPath);
+  const snapshotDbUrl = `file:${snapshotPath}`;
+
+  const SourcePrismaClient = await importPrismaClientFrom(lightDir);
+  const TargetPrismaClient = await importPrismaClientFrom(fullDir);
+
+  const sourceDb = new SourcePrismaClient({ datasources: { db: { url: snapshotDbUrl } } });
+  const targetDb = new TargetPrismaClient({ datasources: { db: { url: infra.env.DATABASE_URL } } });
+
+  try {
+    // Fail-fast unless target is empty (keeps this safe).
+    const existingSessions = await targetDb.session.count();
+    const existingMessages = await targetDb.sessionMessage.count();
+    if (!force && (existingSessions > 0 || existingMessages > 0)) {
+      throw new Error(
+        `[migrate] target database is not empty (sessions=${existingSessions}, messages=${existingMessages}).\n` +
+          `Pass --force to attempt a merge (skipDuplicates), or migrate into a fresh stack.`
+      );
+    }
+
+    // Core entities
+    const accounts = await sourceDb.account.findMany();
+    if (accounts.length) {
+      await targetDb.account.createMany({ data: accounts, skipDuplicates: true });
+    }
+
+    const machines = await sourceDb.machine.findMany();
+    if (machines.length) {
+      await targetDb.machine.createMany({ data: machines, skipDuplicates: true });
+    }
+
+    const accessKeys = await sourceDb.accessKey.findMany();
+    if (accessKeys.length) {
+      await targetDb.accessKey.createMany({ data: accessKeys, skipDuplicates: true });
+    }
+
+    const sessions = await sourceDb.session.findMany();
+    if (sessions.length) {
+      await targetDb.session.createMany({ data: sessions, skipDuplicates: true });
+    }
+
+    // Messages: stream in batches to avoid high memory.
+    let migrated = 0;
+    const batchSize = 1000;
+    let cursor = null;
+    while (true) {
+      // eslint-disable-next-line no-await-in-loop
+      const page = await sourceDb.sessionMessage.findMany({
+        ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+        orderBy: { id: 'asc' },
+        take: batchSize,
+      });
+      if (!page.length) break;
+      cursor = page[page.length - 1].id;
+      // eslint-disable-next-line no-await-in-loop
+      await targetDb.sessionMessage.createMany({ data: page, skipDuplicates: true });
+      migrated += page.length;
+      // eslint-disable-next-line no-console
+      if (!json && migrated % (batchSize * 20) === 0) console.log(`[migrate] migrated ${migrated} messages...`);
+    }
+
+    // Pending queue (small)
+    const pending = await sourceDb.sessionPendingMessage.findMany();
+    if (pending.length) {
+      await targetDb.sessionPendingMessage.createMany({ data: pending, skipDuplicates: true });
+    }
+
+    if (includeFiles) {
+      // Mirror server-light local files (public/*) into Minio bucket root.
+      // This assumes server-light stored public files under HAPPY_SERVER_LIGHT_FILES_DIR/public/...
+      // (Matches happy-server Minio object keys).
+      const { composePath, projectName } = infra;
+      await runCapture('docker', [
+        'compose',
+        '-f',
+        composePath,
+        '-p',
+        projectName,
+        'run',
+        '--rm',
+        '-T',
+        '-v',
+        `${fromFilesDir}:/src:ro`,
+        'minio-init',
+        'sh',
+        '-lc',
+        [
+          `mc alias set local http://minio:9000 ${infra.env.S3_ACCESS_KEY} ${infra.env.S3_SECRET_KEY}`,
+          `mc mirror --overwrite /src local/${infra.env.S3_BUCKET}`,
+        ].join(' && '),
+      ]);
+    }
+
+    printResult({
+      json,
+      data: {
+        ok: true,
+        fromStack,
+        toStack,
+        snapshotPath,
+        migrated: { accounts: accounts.length, sessions: sessions.length, messages: migrated, machines: machines.length, accessKeys: accessKeys.length },
+        filesMirrored: Boolean(includeFiles),
+      },
+      text: [
+        `[migrate] ok`,
+        `[migrate] from: ${fromStack} (${fromFlavor})`,
+        `[migrate] to:   ${toStack} (${toFlavor})`,
+        `[migrate] sqlite snapshot: ${snapshotPath}`,
+        `[migrate] messages: ${migrated}`,
+        includeFiles ? `[migrate] files: mirrored from ${fromFilesDir} -> minio bucket ${infra.env.S3_BUCKET}` : `[migrate] files: skipped`,
+      ].join('\n'),
+    });
+  } finally {
+    await sourceDb.$disconnect().catch(() => {});
+    await targetDb.$disconnect().catch(() => {});
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({ json, data: { ok: true }, text: usage() });
+    return;
+  }
+
+  const cmd = argv.find((a) => !a.startsWith('--')) ?? '';
+  if (!cmd) {
+    throw new Error(usage());
+  }
+
+  if (cmd !== 'light-to-server') {
+    throw new Error(`[migrate] unknown subcommand: ${cmd}\n\n${usage()}`);
+  }
+
+  const fromStack = (kv.get('--from-stack') ?? 'main').trim();
+  const toStack = (kv.get('--to-stack') ?? '').trim();
+  const includeFiles = flags.has('--include-files') || (kv.get('--include-files') ?? '').trim() === '1';
+  const force = flags.has('--force');
+  if (!toStack) {
+    throw new Error('[migrate] --to-stack is required');
+  }
+
+  const rootDir = (await import('./utils/paths.mjs')).getRootDir(import.meta.url);
+  await migrateLightToServer({ rootDir, fromStack, toStack, includeFiles, force, json });
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});
+

package/scripts/mobile.mjs

@@ -1,10 +1,12 @@
 import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { killPortListeners } from './utils/ports.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { pickNextFreeTcpPort } from './utils/ports.mjs';
 import { run, runCapture, spawnProc } from './utils/proc.mjs';
-import { getComponentDir, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, requireDir } from './utils/pm.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/pm.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo.mjs';
+import { killProcessGroupOwnedByStack } from './utils/ownership.mjs';
 
 /**
  * Mobile dev helper for the embedded `components/happy` Expo app.
@@ -25,6 +27,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
+  const restart = flags.has('--restart');
 
   if (wantsHelp(argv, { flags })) {
     printResult({
@@ -40,6 +43,7 @@ async function main() {
           '--prebuild [--platform=ios|all] [--clean]',
           '--run-ios [--device=<id-or-name>] [--configuration=Debug|Release]',
           '--metro / --no-metro',
+          '--restart',
           '--no-signing-fix',
         ],
         json: true,
@@ -47,6 +51,7 @@ async function main() {
       text: [
         '[mobile] usage:',
         '  happys mobile [--host=lan|localhost|tunnel] [--port=8081] [--scheme=...] [--json]',
+        '  happys mobile --restart   # force-restart Metro for this stack/worktree',
         '  happys mobile --run-ios [--device=...] [--configuration=Debug|Release]',
         '  happys mobile --prebuild [--platform=ios|all] [--clean]',
         '  happys mobile --no-metro   # just build/install (if --run-ios) without starting Metro',
@@ -107,7 +112,7 @@ async function main() {
     process.env.HAPPY_LOCAL_MOBILE_SCHEME ??
     iosBundleId;
   const host = kv.get('--host') ?? process.env.HAPPY_STACKS_MOBILE_HOST ?? process.env.HAPPY_LOCAL_MOBILE_HOST ?? 'lan';
-  const port = kv.get('--port') ?? process.env.HAPPY_STACKS_MOBILE_PORT ?? process.env.HAPPY_LOCAL_MOBILE_PORT ?? '8081';
+  const portRaw = kv.get('--port') ?? process.env.HAPPY_STACKS_MOBILE_PORT ?? process.env.HAPPY_LOCAL_MOBILE_PORT ?? '8081';
   // Default behavior:
   // - `happys mobile` starts Metro and keeps running.
   // - `happys mobile --run-ios` / `happys mobile:ios` just builds/installs and exits (unless --metro is provided).
@@ -120,6 +125,20 @@ async function main() {
     APP_ENV: appEnv,
   };
 
+  const autostart = getDefaultAutostartPaths();
+  const mobilePaths = getExpoStatePaths({
+    baseDir: autostart.baseDir,
+    kind: 'mobile-dev',
+    projectDir: uiDir,
+    stateFileName: 'mobile.state.json',
+  });
+  await ensureExpoIsolationEnv({
+    env,
+    stateDir: mobilePaths.stateDir,
+    expoHomeDir: mobilePaths.expoHomeDir,
+    tmpDir: mobilePaths.tmpDir,
+  });
+
   // Allow happy-stacks to define the default server URL baked into the app bundle.
   // This is read by the app via `process.env.EXPO_PUBLIC_HAPPY_SERVER_URL`.
   const stacksServerUrl =
@@ -139,7 +158,7 @@ async function main() {
         iosBundleId,
         scheme,
         host,
-        port,
+        port: portRaw,
         shouldPrebuild: flags.has('--prebuild'),
         shouldRunIos: flags.has('--run-ios'),
         shouldStartMetro,
@@ -155,11 +174,11 @@ async function main() {
     const shouldClean = flags.has('--clean');
     // Prebuild can fail during `pod install` if deployment target mismatches.
     // We skip installs, patch deployment target + RN build mode, then run `pod install` ourselves.
-    const prebuildArgs = ['expo', 'prebuild', '--no-install', '--platform', platform];
+    const prebuildArgs = ['prebuild', '--no-install', '--platform', platform];
     if (shouldClean) {
       prebuildArgs.push('--clean');
     }
-    await run('npx', prebuildArgs, { cwd: uiDir, env });
+    await pmExecBin({ dir: uiDir, bin: 'expo', args: prebuildArgs, env });
 
     // Always patch iOS props if iOS was generated.
     if (platform === 'ios' || platform === 'all') {
@@ -266,35 +285,54 @@ async function main() {
     }
 
     const configuration = kv.get('--configuration') ?? 'Debug';
-    const args = ['expo', 'run:ios', '--no-bundler', '--no-build-cache', '--configuration', configuration];
+    const args = ['run:ios', '--no-bundler', '--no-build-cache', '--configuration', configuration];
     if (device) {
       args.push('-d', device);
     }
     // Ensure CocoaPods doesn't crash due to locale issues.
     env.LANG = env.LANG ?? 'en_US.UTF-8';
     env.LC_ALL = env.LC_ALL ?? 'en_US.UTF-8';
-    await run('npx', args, { cwd: uiDir, env });
+    await pmExecBin({ dir: uiDir, bin: 'expo', args, env });
   }
 
   if (!shouldStartMetro) {
     return;
   }
 
-  const portNumber = Number.parseInt(port, 10);
-  if (Number.isFinite(portNumber) && portNumber > 0) {
-    await killPortListeners(portNumber, { label: 'expo' });
+  const running = await isStateProcessRunning(mobilePaths.statePath);
+  if (!restart && running.running) {
+    // eslint-disable-next-line no-console
+    console.log(`[mobile] Metro already running for this stack/worktree (pid=${running.state.pid}, port=${running.state.port})`);
+    return;
+  }
+  if (restart && running.state?.pid) {
+    const prevPid = Number(running.state.pid);
+    const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || autostart.stackName;
+    const envPath = (process.env.HAPPY_STACKS_ENV_FILE ?? process.env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-mobile', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[mobile] not stopping existing Metro pid=${prevPid} because it does not look stack-owned.\n` +
+          `[mobile] continuing by starting a new Metro on a free port.`
+      );
+    }
   }
 
+  const requestedPort = Number.parseInt(String(portRaw), 10);
+  const startPort = Number.isFinite(requestedPort) && requestedPort > 0 ? requestedPort : 8081;
+  const portNumber = await pickNextFreeTcpPort(startPort);
+  env.RCT_METRO_PORT = String(portNumber);
+
   // Start Metro for a dev client.
   // The critical part is --scheme: without it, Expo defaults to `exp+<slug>` (here `exp+happy`)
   // which the App Store app also registers, so iOS can open the wrong app.
-  spawnProc(
-    'mobile',
-    'npx',
-    ['expo', 'start', '--dev-client', '--host', host, '--port', port, '--scheme', scheme],
-    env,
-    { cwd: uiDir }
-  );
+  const args = ['start', '--dev-client', '--host', host, '--port', String(portNumber), '--scheme', scheme];
+  if (wantsExpoClearCache({ env })) {
+    args.push('--clear');
+  }
+  const child = await pmSpawnBin({ label: 'mobile', dir: uiDir, bin: 'expo', args, env });
+  await writePidState(mobilePaths.statePath, { pid: child.pid, port: portNumber, uiDir, startedAt: new Date().toISOString() });
 
   await new Promise(() => {});
 }