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

package/scripts/utils/dev/daemon.mjs

@@ -6,6 +6,27 @@ import { watchDebounced } from '../proc/watch.mjs';
 import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from '../stack/startup.mjs';
 import { startLocalDaemonWithAuth } from '../../daemon.mjs';
 
+function resolveHappyCliWatchPaths({ cliDir, existsSyncImpl = existsSync }) {
+  const repoRoot = resolve(cliDir, '..', '..');
+  const sharedPackages = ['agents', 'cli-common', 'protocol'];
+  const cliPaths = [
+    join(cliDir, 'src'),
+    join(cliDir, 'bin'),
+    join(cliDir, 'codex'),
+    join(cliDir, 'package.json'),
+    join(cliDir, 'tsconfig.json'),
+    join(cliDir, 'tsconfig.build.json'),
+    join(cliDir, 'pkgroll.config.mjs'),
+  ];
+  const sharedPaths = sharedPackages.flatMap((pkg) => ([
+    join(repoRoot, 'packages', pkg, 'src'),
+    join(repoRoot, 'packages', pkg, 'package.json'),
+    join(repoRoot, 'packages', pkg, 'tsconfig.json'),
+  ]));
+
+  return [...cliPaths, ...sharedPaths].filter((p) => existsSyncImpl(p));
+}
+
 export async function ensureDevCliReady(
   { cliDir, buildCli, env = process.env },
   { logger = console } = {}
@@ -98,6 +119,7 @@ export async function startDevDaemon({
   cliHomeDir,
   internalServerUrl,
   publicServerUrl,
+  runtimeStatePath = null,
   restart,
   isShuttingDown,
   env = process.env,
@@ -113,6 +135,7 @@ export async function startDevDaemon({
     cliHomeDir,
     internalServerUrl,
     publicServerUrl,
+    runtimeStatePath,
     isShuttingDown,
     forceRestart: Boolean(restart),
     env,
@@ -130,6 +153,7 @@ export function watchHappyCliAndRestartDaemon({
   cliHomeDir,
   internalServerUrl,
   publicServerUrl,
+  runtimeStatePath = null,
   isShuttingDown,
   env = process.env,
   stackName = null,
@@ -150,16 +174,7 @@ export function watchHappyCliAndRestartDaemon({
   // Watch only source/config paths, not build outputs. Watching the whole repo can
   // trigger rebuild loops because `yarn build` writes to `dist/` (and may touch other
   // generated files), which then retriggers the watcher.
-  const watchPaths = [
-    join(cliDir, 'src'),
-    join(cliDir, 'bin'),
-    join(cliDir, 'codex'),
-    join(cliDir, 'package.json'),
-    join(cliDir, 'tsconfig.json'),
-    join(cliDir, 'tsconfig.build.json'),
-    join(cliDir, 'pkgroll.config.mjs'),
-    join(cliDir, 'yarn.lock'),
-  ].filter((p) => existsSyncImpl(p));
+  const watchPaths = resolveHappyCliWatchPaths({ cliDir, existsSyncImpl });
 
   return watchDebouncedImpl({
     paths: (watchPaths.length ? watchPaths : [cliDir]).map((p) => resolve(p)),
@@ -206,6 +221,7 @@ export function watchHappyCliAndRestartDaemon({
               cliHomeDir,
               internalServerUrl,
               publicServerUrl,
+              runtimeStatePath,
               isShuttingDown,
               forceRestart: true,
               env,

package/scripts/utils/dev/daemon_watch_resilience.test.mjs

@@ -173,6 +173,70 @@ test('watch forwards stack context to daemon restart', async () => {
   assert.equal(restartArgs.env?.TEST_ENV, '1');
 });
 
+test('watch does not include cliDir/yarn.lock in watched paths (prevents rebuild loops)', async () => {
+  let capturedPaths = null;
+
+  watchHappyCliAndRestartDaemon(
+    {
+      enabled: true,
+      startDaemon: true,
+      buildCli: true,
+      cliDir: '/tmp/happy-cli',
+      cliBin: '/tmp/happy-cli/bin/happier.mjs',
+      cliHomeDir: '/tmp/happy-cli-home',
+      internalServerUrl: 'http://127.0.0.1:3009',
+      publicServerUrl: 'http://localhost:3009',
+      isShuttingDown: () => false,
+    },
+    {
+      watchDebouncedImpl: ({ paths }) => {
+        capturedPaths = paths;
+        return { close() {} };
+      },
+      ensureCliBuiltImpl: async () => ({ built: true, reason: 'test' }),
+      startLocalDaemonWithAuthImpl: async () => {},
+      existsSyncImpl: () => true,
+      logger: { log() {}, warn() {}, error() {} },
+    },
+  );
+
+  assert.ok(Array.isArray(capturedPaths));
+  assert.ok(!capturedPaths.includes('/tmp/happy-cli/yarn.lock'));
+});
+
+test('watch includes shared CLI runtime packages so daemon restarts on shared source edits', async () => {
+  let capturedPaths = null;
+
+  watchHappyCliAndRestartDaemon(
+    {
+      enabled: true,
+      startDaemon: true,
+      buildCli: true,
+      cliDir: '/tmp/repo/apps/cli',
+      cliBin: '/tmp/repo/apps/cli/bin/happier.mjs',
+      cliHomeDir: '/tmp/happy-cli-home',
+      internalServerUrl: 'http://127.0.0.1:3009',
+      publicServerUrl: 'http://localhost:3009',
+      isShuttingDown: () => false,
+    },
+    {
+      watchDebouncedImpl: ({ paths }) => {
+        capturedPaths = paths;
+        return { close() {} };
+      },
+      ensureCliBuiltImpl: async () => ({ built: true, reason: 'test' }),
+      startLocalDaemonWithAuthImpl: async () => {},
+      existsSyncImpl: () => true,
+      logger: { log() {}, warn() {}, error() {} },
+    },
+  );
+
+  assert.ok(Array.isArray(capturedPaths));
+  assert.ok(capturedPaths.includes('/tmp/repo/packages/agents/src'));
+  assert.ok(capturedPaths.includes('/tmp/repo/packages/cli-common/src'));
+  assert.ok(capturedPaths.includes('/tmp/repo/packages/protocol/src'));
+});
+
 test('ensureDevCliReady keeps existing dist output when build fails', async (t) => {
   const root = await mkdtemp(join(tmpdir(), 'hs-daemon-cli-ready-'));
   t.after(async () => {

package/scripts/utils/dev/expo_dev.buildEnv.test.mjs

@@ -20,7 +20,9 @@ test('buildExpoDevEnv does not inject auth auto-restore env vars', () => {
     stackName: 'qa-agent-x',
   });
 
+  assert.equal(env.EXPO_PUBLIC_HAPPIER_SERVER_URL, 'http://localhost:3010');
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_URL, 'http://localhost:3010');
+  assert.equal(env.EXPO_PUBLIC_SERVER_URL, 'http://localhost:3010');
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT, 'stack');
   assert.equal(env.EXPO_NO_BROWSER, '1');
   assert.equal(env.BROWSER, 'none');
@@ -50,3 +52,21 @@ test('buildExpoDevEnv forces stack context in stack mode even when base env sets
 
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT, 'stack');
 });
+
+test('buildExpoDevEnv does not set EXPO_APP_SLUG in dev-client mode (slug must match EAS project)', () => {
+  const baseEnv = {
+    ...process.env,
+    EXPO_APP_SLUG: undefined,
+  };
+
+  const env = buildExpoDevEnv({
+    baseEnv,
+    apiServerUrl: 'http://localhost:3013',
+    wantDevClient: true,
+    wantWeb: false,
+    stackMode: true,
+    stackName: 'qa-agent-2',
+  });
+
+  assert.equal(env.EXPO_APP_SLUG, undefined);
+});

package/scripts/utils/dev/expo_dev.ensure_workspace_built.test.mjs

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile, chmod, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { ensureDevExpoServer } from './expo_dev.mjs';
+
+test('ensureDevExpoServer runs the UI workspace build preflight before starting Expo', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-preflight-'));
+  try {
+    const uiDir = join(tmp, 'ui');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+    await mkdir(join(uiDir, 'scripts'), { recursive: true });
+    await writeFile(join(uiDir, 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n', 'utf-8');
+
+    const marker = join(tmp, 'workspace-preflight-ran.txt');
+    await writeFile(join(uiDir, 'scripts', 'ensureWorkspacePackagesBuilt.mjs'), [
+      "import { writeFileSync } from 'node:fs';",
+      `writeFileSync(${JSON.stringify(marker)}, 'ok\\n', 'utf-8');`,
+    ].join('\n') + '\n', 'utf-8');
+
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await writeFile(
+      expoBin,
+      [
+        '#!/usr/bin/env node',
+        "const fs = require('node:fs');",
+        `const marker = ${JSON.stringify(marker)};`,
+        "console.log(fs.existsSync(marker) ? 'preflight-ok' : 'preflight-missing');",
+        "setTimeout(() => process.exit(0), 100);",
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    await chmod(expoBin, 0o755);
+
+    const teeFile = join(tmp, 'expo.log');
+    const children = [];
+    await ensureDevExpoServer({
+      startUi: true,
+      startMobile: false,
+      uiDir,
+      autostart: { baseDir: tmp },
+      baseEnv: { ...process.env, HAPPIER_STACK_VERBOSE: '1' },
+      apiServerUrl: 'http://127.0.0.1:1',
+      restart: true,
+      stackMode: false,
+      runtimeStatePath: null,
+      stackName: 'test',
+      envPath: '',
+      children,
+      spawnOptions: {
+        silent: true,
+        teeFile,
+        teeLabel: 'expo',
+      },
+      quiet: true,
+    });
+
+    const deadlineMs = Date.now() + 3000;
+    let log = '';
+    while (Date.now() < deadlineMs) {
+      log = await readFile(teeFile, 'utf-8').catch(() => '');
+      if (/preflight-/.test(log)) break;
+      await delay(100);
+    }
+
+    assert.match(log, /preflight-ok/);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+

package/scripts/utils/dev/expo_dev.mjs

@@ -2,22 +2,27 @@ import { fork } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import net from 'node:net';
+import { existsSync } from 'node:fs';
 import {
   ensureExpoIsolationEnv,
   getExpoStatePaths,
   isStateProcessRunning,
+  resolveExpoTmpDir,
   wantsExpoClearCache,
   writePidState,
 } from '../expo/expo.mjs';
 import { pickExpoDevMetroPort } from '../expo/metro_ports.mjs';
 import { ensureEnvFileUpdated } from '../env/env_file.mjs';
 import { isPidAlive, recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
-import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
+import { getProcessGroupId, getPsEnvLine, killProcessGroupOwnedByStack, listPidsWithEnvNeedle } from '../proc/ownership.mjs';
+import { terminateProcessGroup } from '../proc/terminate.mjs';
 import { expoSpawn } from '../expo/command.mjs';
+import { run } from '../proc/proc.mjs';
 import { resolveMobileExpoConfig } from '../mobile/config.mjs';
 import { resolveMobileReachableServerUrl } from '../server/mobile_api_url.mjs';
 import { getTailscaleStatus } from '../tailscale/ip.mjs';
 import { pickLanIpv4 } from '../net/lan_ip.mjs';
+import { isTcpPortFree } from '../net/ports.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -28,6 +33,19 @@ function normalizeExpoHost(raw) {
   return 'lan';
 }
 
+async function ensureWorkspacePackagesBuiltForExpoProject({ projectDir, env, quiet }) {
+  const scriptPath = join(projectDir, 'scripts', 'ensureWorkspacePackagesBuilt.mjs');
+  if (!existsSync(scriptPath)) {
+    return;
+  }
+  await run(process.execPath, [scriptPath], {
+    cwd: projectDir,
+    env,
+    stdio: quiet ? 'ignore' : 'inherit',
+    timeoutMs: 10 * 60_000,
+  });
+}
+
 /**
  * Resolve whether Tailscale forwarding for Expo is enabled.
  *
@@ -233,7 +251,11 @@ export function buildExpoDevEnv({
       })
     : apiServerUrl;
 
+  // The UI prefers EXPO_PUBLIC_HAPPIER_SERVER_URL. Keep legacy aliases in sync to avoid
+  // accidental precedence from a leaked shell env var (or from older tooling).
+  env.EXPO_PUBLIC_HAPPIER_SERVER_URL = effectiveApiServerUrl;
   env.EXPO_PUBLIC_HAPPY_SERVER_URL = effectiveApiServerUrl;
+  env.EXPO_PUBLIC_SERVER_URL = effectiveApiServerUrl;
   if (stackMode) {
     env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT = 'stack';
   }
@@ -315,11 +337,16 @@ export async function ensureDevExpoServer({
     projectDir,
     stateFileName: 'expo.state.json',
   });
-  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+  const tmpDir = resolveExpoTmpDir({ env, defaultTmpDir: paths.tmpDir, kind: 'expo-dev', projectDir });
+  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir });
 
   const running = await isStateProcessRunning(paths.statePath);
   const alreadyRunning = Boolean(running.running);
   const desiredApiServerUrl = normalizeApiServerUrl(apiServerUrl);
+  const cliHomeDir = (baseEnv?.HAPPIER_STACK_CLI_HOME_DIR ?? '').toString().trim();
+  const stablePortMode =
+    stackMode &&
+    ((baseEnv?.HAPPIER_STACK_EXPO_DEV_PORT_STRATEGY ?? 'ephemeral').toString().trim() || 'ephemeral') === 'stable';
 
   // Resolve Tailscale forwarding preference
   const wantTailscale = resolveExpoTailscaleEnabled({ env: baseEnv, expoTailscale });
@@ -410,35 +437,71 @@ export async function ensureDevExpoServer({
   if (restart && running.state?.pid) {
     const prevPid = Number(running.state.pid);
     const prevPort = Number(running.state?.port);
-    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo', json: true });
-    if (!res.killed) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[local] expo: not stopping existing Expo pid=${prevPid} because it does not look stack-owned.\n` +
-          `[local] expo: continuing by starting a new Expo process on a free port.`
-      );
-      if (Number.isFinite(prevPort) && prevPort > 0) {
-        reservedMetroPorts.add(prevPort);
+    const prevPidAlive = Number.isFinite(prevPid) && prevPid > 1 && isPidAlive(prevPid);
+    if (prevPidAlive) {
+      const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, cliHomeDir, label: 'expo', json: true });
+      if (!res.killed) {
+        const portInUse =
+          Number.isFinite(prevPort) && prevPort > 0 ? !(await isTcpPortFree(prevPort, { host: '127.0.0.1' })) : false;
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[local] expo: not stopping existing Expo pid=${prevPid} because it does not look stack-owned.\n` +
+            `[local] expo: continuing by starting a new Expo process on a free port.`
+        );
+        if (portInUse && !stablePortMode) {
+          reservedMetroPorts.add(prevPort);
+        }
       }
     }
   }
 
-  const metroPort = await pickExpoDevMetroPort({
-    env: baseEnv,
-    stackMode,
-    stackName,
-    reservedPorts: reservedMetroPorts,
-  });
   const forcedPortRaw = (baseEnv?.HAPPIER_STACK_EXPO_DEV_PORT ?? '').toString().trim();
   const forcedPortNum = Number(forcedPortRaw);
-  if (
-    stackMode &&
-    envPath &&
-    forcedPortRaw &&
-    Number.isFinite(forcedPortNum) &&
-    forcedPortNum > 0 &&
-    forcedPortNum !== metroPort
-  ) {
+  const hasForcedPort = forcedPortRaw && Number.isFinite(forcedPortNum) && forcedPortNum > 0;
+
+  if (stablePortMode && hasForcedPort) {
+    if (reservedMetroPorts.has(forcedPortNum)) {
+      throw new Error(
+        `[expo] stable expo port ${forcedPortNum} is reserved due to an existing process; refusing to bump the expo port.`
+      );
+    }
+    let free = await isTcpPortFree(forcedPortNum, { host: '127.0.0.1' });
+    if (!free) {
+      const needle = `__UNSAFE_EXPO_HOME_DIRECTORY=${paths.expoHomeDir}`;
+      const candidates = await listPidsWithEnvNeedle(needle);
+      const selfPgid = await getProcessGroupId(process.pid);
+      for (const pid of candidates) {
+        // eslint-disable-next-line no-await-in-loop
+        const line = await getPsEnvLine(pid);
+        if (!line) continue;
+        if (stackName && !line.includes(`HAPPIER_STACK_STACK=${stackName}`)) continue;
+        // eslint-disable-next-line no-await-in-loop
+        const pgid = await getProcessGroupId(pid);
+        if (!pgid) continue;
+        if (selfPgid && pgid === selfPgid) continue;
+        // eslint-disable-next-line no-await-in-loop
+        await terminateProcessGroup(pgid, { graceMs: 800, signal: 'SIGTERM' }).catch(() => {});
+      }
+      free = await isTcpPortFree(forcedPortNum, { host: '127.0.0.1' });
+    }
+    if (!free) {
+      throw new Error(
+        `[expo] stable expo port ${forcedPortNum} is already in use; refusing to bump the expo port. ` +
+          `Stop the process using it or run with --restart after ensuring the previous stack process is stopped.`
+      );
+    }
+  }
+
+  const metroPort = stablePortMode && hasForcedPort
+    ? forcedPortNum
+    : await pickExpoDevMetroPort({
+        env: baseEnv,
+        stackMode,
+        stackName,
+        reservedPorts: reservedMetroPorts,
+      });
+
+  if (stackMode && envPath && hasForcedPort && forcedPortNum !== metroPort) {
     if (!quiet) {
       // eslint-disable-next-line no-console
       console.warn(
@@ -475,6 +538,7 @@ export async function ensureDevExpoServer({
     delete normalizedSpawnOptions.stdio;
   }
   // Run the Expo CLI from the runner dir (where deps/bins live), but target the actual Expo project dir.
+  await ensureWorkspacePackagesBuiltForExpoProject({ projectDir, env, quiet });
   const proc = await expoSpawn({ label: 'expo', dir: uiDir, projectDir, args, env, options: normalizedSpawnOptions, quiet });
   children.push(proc);
 

package/scripts/utils/dev/expo_dev_restart_port_reservation.test.mjs

@@ -3,11 +3,11 @@ import assert from 'node:assert/strict';
 import { mkdtemp, mkdir, rm, writeFile, chmod, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { spawn } from 'node:child_process';
 import net from 'node:net';
 
 import { ensureDevExpoServer } from './expo_dev.mjs';
 import { getExpoStatePaths, writePidState } from '../expo/expo.mjs';
+import { spawnDetachedInlineNodeTestProcess, spawnDetachedTestProcess } from '../../testkit/core/spawn_test_process.mjs';
 
 function listenEphemeralPort() {
   return new Promise((resolve, reject) => {
@@ -68,7 +68,7 @@ function listenMetroStatusServer() {
   });
 }
 
-test('ensureDevExpoServer reserves prior metro port when restart cannot kill previous pid', async () => {
+test('ensureDevExpoServer does not reserve prior metro port when restart cannot kill previous pid but the port is free', async () => {
   const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-reserve-port-'));
   const children = [];
   let foreignPid = null;
@@ -89,11 +89,9 @@ test('ensureDevExpoServer reserves prior metro port when restart cannot kill pre
     );
     await chmod(expoBin, 0o755);
 
-    const foreign = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
-      detached: true,
+    const foreign = spawnDetachedInlineNodeTestProcess('setInterval(() => {}, 1000)', {
       stdio: 'ignore',
     });
-    foreign.unref();
     foreignPid = foreign.pid;
 
     const priorPort = await listenEphemeralPort();
@@ -135,7 +133,7 @@ test('ensureDevExpoServer reserves prior metro port when restart cannot kill pre
     });
 
     assert.equal(result.ok, true);
-    assert.notEqual(result.port, priorPort);
+    assert.equal(result.port, priorPort);
   } finally {
     for (const child of children) {
       killProcessTreeByPid(child?.pid);
@@ -298,7 +296,7 @@ test('ensureDevExpoServer in stack mode does not adopt port-only fallback as alr
   }
 });
 
-test('ensureDevExpoServer updates envPath when forced expo port is occupied', async () => {
+test('ensureDevExpoServer fails closed in stable port mode when forced expo port is occupied (does not rewrite envPath)', async () => {
   const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-update-env-port-'));
   const children = [];
   let metro = null;
@@ -323,6 +321,101 @@ test('ensureDevExpoServer updates envPath when forced expo port is occupied', as
     const envPath = join(tmp, 'stack.env');
     await writeFile(envPath, `CUSTOM_KEY=1\nHAPPIER_STACK_EXPO_DEV_PORT=${occupiedPort}\n`, 'utf-8');
 
+    await assert.rejects(
+      () =>
+        ensureDevExpoServer({
+          startUi: true,
+          startMobile: false,
+          uiDir,
+          autostart: { baseDir: tmp },
+          baseEnv: {
+            ...process.env,
+            HAPPIER_STACK_EXPO_DEV_PORT: String(occupiedPort),
+            HAPPIER_STACK_EXPO_DEV_PORT_STRATEGY: 'stable',
+            HAPPIER_STACK_EXPO_DEV_PORT_BASE: '51000',
+            HAPPIER_STACK_EXPO_DEV_PORT_RANGE: '2000',
+          },
+          apiServerUrl: 'http://127.0.0.1:1',
+          restart: false,
+          stackMode: true,
+          runtimeStatePath: null,
+          stackName: 'qa-agent-update-env',
+          envPath,
+          children,
+          quiet: true,
+        }),
+      /expo port/i
+    );
+
+    const updated = await readFile(envPath, 'utf-8');
+    assert.match(updated, /\bCUSTOM_KEY=1\b/);
+    assert.match(updated, new RegExp(`\\bHAPPIER_STACK_EXPO_DEV_PORT=${occupiedPort}\\b`));
+  } finally {
+    for (const child of children) {
+      killProcessTreeByPid(child?.pid);
+    }
+    await new Promise((resolve) => metro?.close(() => resolve())).catch(() => {});
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('ensureDevExpoServer in stable port mode stops stack-owned leftover Expo processes holding the forced port (no bump)', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-stable-stop-leftovers-'));
+  const children = [];
+  let holderPid = null;
+  try {
+    const uiDir = join(tmp, 'ui');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+    await mkdir(join(uiDir, 'node_modules'), { recursive: true });
+    await writeFile(join(uiDir, 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n', 'utf-8');
+
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await writeFile(expoBin, ['#!/usr/bin/env node', "setInterval(() => {}, 1000);"].join('\n') + '\n', 'utf-8');
+    await chmod(expoBin, 0o755);
+
+    const occupiedPort = await listenEphemeralPort();
+    const projectDir = uiDir;
+    const paths = getExpoStatePaths({
+      baseDir: tmp,
+      kind: 'expo-dev',
+      projectDir,
+      stateFileName: 'expo.state.json',
+    });
+
+    const stackName = 'qa-owned-expo-leftover';
+    const cliHomeDir = join(tmp, 'cli');
+    await mkdir(cliHomeDir, { recursive: true });
+
+    // Spawn a process that (1) holds the port and (2) carries the same Expo isolation env marker,
+    // so ensureDevExpoServer can identify and stop it without bumping the stable port.
+    const holder = spawnDetachedTestProcess(
+      process.execPath,
+      [
+        '-e',
+        [
+          "const net = require('net');",
+          'const port = Number(process.env.TEST_PORT);',
+          "const srv = net.createServer(() => {});",
+          "srv.listen(port, '127.0.0.1');",
+          "setInterval(() => {}, 1000);",
+        ].join(''),
+      ],
+      {
+        stdio: 'ignore',
+        env: {
+          ...process.env,
+          TEST_PORT: String(occupiedPort),
+          __UNSAFE_EXPO_HOME_DIRECTORY: paths.expoHomeDir,
+          HAPPIER_STACK_STACK: stackName,
+          HAPPIER_STACK_CLI_HOME_DIR: cliHomeDir,
+        },
+      }
+    );
+    holderPid = holder.pid;
+
+    const envPath = join(tmp, 'stack.env');
+    await writeFile(envPath, `HAPPIER_STACK_EXPO_DEV_PORT=${occupiedPort}\n`, 'utf-8');
+
     const result = await ensureDevExpoServer({
       startUi: true,
       startMobile: false,
@@ -332,30 +425,25 @@ test('ensureDevExpoServer updates envPath when forced expo port is occupied', as
         ...process.env,
         HAPPIER_STACK_EXPO_DEV_PORT: String(occupiedPort),
         HAPPIER_STACK_EXPO_DEV_PORT_STRATEGY: 'stable',
-        HAPPIER_STACK_EXPO_DEV_PORT_BASE: '51000',
-        HAPPIER_STACK_EXPO_DEV_PORT_RANGE: '2000',
+        HAPPIER_STACK_CLI_HOME_DIR: cliHomeDir,
       },
       apiServerUrl: 'http://127.0.0.1:1',
       restart: false,
       stackMode: true,
       runtimeStatePath: null,
-      stackName: 'qa-agent-update-env',
+      stackName,
       envPath,
       children,
       quiet: true,
     });
 
     assert.equal(result.ok, true);
-    assert.notEqual(result.port, occupiedPort);
-
-    const updated = await readFile(envPath, 'utf-8');
-    assert.match(updated, /\bCUSTOM_KEY=1\b/);
-    assert.match(updated, new RegExp(`\\bHAPPIER_STACK_EXPO_DEV_PORT=${result.port}\\b`));
+    assert.equal(result.port, occupiedPort);
   } finally {
     for (const child of children) {
       killProcessTreeByPid(child?.pid);
     }
-    await new Promise((resolve) => metro?.close(() => resolve())).catch(() => {});
+    killProcessTreeByPid(holderPid);
     await rm(tmp, { recursive: true, force: true });
   }
 });

package/scripts/utils/dev/react_native_devtools.mjs

@@ -0,0 +1,27 @@
+function normalizePath(raw) {
+  const p = String(raw ?? '').trim();
+  if (!p) return null;
+  if (p.startsWith('/')) return p;
+  return `/${p}`;
+}
+
+export function resolveReactNativeDevtoolsUrl({
+  metroUrl,
+  env = process.env,
+} = {}) {
+  const base = String(metroUrl ?? '').trim();
+  if (!base) return null;
+  let u;
+  try {
+    u = new URL(base);
+  } catch {
+    return null;
+  }
+
+  const path = normalizePath(env.HAPPIER_STACK_RN_DEVTOOLS_PATH) ?? '/debugger-ui';
+  u.pathname = path;
+  u.search = '';
+  u.hash = '';
+  return u.toString();
+}
+

package/scripts/utils/dev/react_native_devtools.test.mjs

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveReactNativeDevtoolsUrl } from './react_native_devtools.mjs';
+
+test('resolveReactNativeDevtoolsUrl defaults to /debugger-ui', () => {
+  const url = resolveReactNativeDevtoolsUrl({ metroUrl: 'http://localhost:8081' });
+  assert.equal(url, 'http://localhost:8081/debugger-ui');
+});
+
+test('resolveReactNativeDevtoolsUrl respects HAPPIER_STACK_RN_DEVTOOLS_PATH', () => {
+  const url = resolveReactNativeDevtoolsUrl({
+    metroUrl: 'http://localhost:8081',
+    env: { ...process.env, HAPPIER_STACK_RN_DEVTOOLS_PATH: '/_expo/debugger-ui' },
+  });
+  assert.equal(url, 'http://localhost:8081/_expo/debugger-ui');
+});
+
+test('resolveReactNativeDevtoolsUrl normalizes missing leading slash', () => {
+  const url = resolveReactNativeDevtoolsUrl({
+    metroUrl: 'http://localhost:8081',
+    env: { ...process.env, HAPPIER_STACK_RN_DEVTOOLS_PATH: 'debugger-ui' },
+  });
+  assert.equal(url, 'http://localhost:8081/debugger-ui');
+});
+