happy-stacks 0.3.0 → 0.4.0

package/scripts/utils/sandbox/review_pr_sandbox.mjs

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+
+export const REVIEW_PR_MARKER_FILENAME = '.happy-stacks-sandbox-marker';
+export const REVIEW_PR_META_FILENAME = '.happy-stacks-review-pr.json';
+
+export function reviewPrSandboxPrefixBase(baseStackName) {
+  const base = String(baseStackName ?? '').trim() || 'pr';
+  // Keep prefix stable for listing/reuse; mkdtemp adds a random suffix.
+  return `happy-stacks-review-pr-${base}-`;
+}
+
+export function reviewPrSandboxPrefixPath(baseStackName) {
+  return join(tmpdir(), reviewPrSandboxPrefixBase(baseStackName));
+}
+
+async function readJsonBestEffort(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function listReviewPrSandboxes({ baseStackName }) {
+  const prefixBase = reviewPrSandboxPrefixBase(baseStackName);
+  const root = tmpdir();
+  let entries = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!e.name.startsWith(prefixBase)) continue;
+    const dir = resolve(join(root, e.name));
+    const markerPath = join(dir, REVIEW_PR_MARKER_FILENAME);
+    if (!existsSync(markerPath)) continue;
+
+    let markerOk = false;
+    try {
+      const marker = await readFile(markerPath, 'utf-8');
+      markerOk = marker.trim().startsWith('review-pr');
+    } catch {
+      markerOk = false;
+    }
+    if (!markerOk) continue;
+
+    const metaPath = join(dir, REVIEW_PR_META_FILENAME);
+    const meta = await readJsonBestEffort(metaPath);
+
+    let mtimeMs = 0;
+    try {
+      mtimeMs = (await stat(dir)).mtimeMs;
+    } catch {
+      mtimeMs = 0;
+    }
+
+    out.push({
+      dir,
+      name: basename(dir),
+      markerPath,
+      metaPath,
+      baseStackName: String(meta?.baseStackName ?? '').trim() || String(baseStackName ?? '').trim() || null,
+      stackName: String(meta?.stackName ?? '').trim() || null,
+      createdAtMs: typeof meta?.createdAtMs === 'number' ? meta.createdAtMs : null,
+      lastTouchedAtMs: Number.isFinite(mtimeMs) ? mtimeMs : null,
+    });
+  }
+
+  out.sort((a, b) => (b.lastTouchedAtMs ?? 0) - (a.lastTouchedAtMs ?? 0));
+  return out;
+}
+
+export async function writeReviewPrSandboxMeta({ sandboxDir, baseStackName, stackName, argv }) {
+  const dir = resolve(String(sandboxDir ?? '').trim());
+  const markerPath = join(dir, REVIEW_PR_MARKER_FILENAME);
+  const metaPath = join(dir, REVIEW_PR_META_FILENAME);
+
+  // Marker (for safe deletion) + meta (for reuse menu).
+  await writeFile(markerPath, 'review-pr\n', 'utf-8');
+  await writeFile(
+    metaPath,
+    JSON.stringify(
+      {
+        kind: 'review-pr',
+        createdAtMs: Date.now(),
+        baseStackName: String(baseStackName ?? '').trim() || null,
+        stackName: String(stackName ?? '').trim() || null,
+        argv: Array.isArray(argv) ? argv : null,
+      },
+      null,
+      2
+    ) + '\n',
+    'utf-8'
+  );
+
+  return { markerPath, metaPath };
+}
+

package/scripts/utils/server/mobile_api_url.mjs

@@ -0,0 +1,61 @@
+import { pickLanIpv4 } from '../net/lan_ip.mjs';
+import { normalizeUrlNoTrailingSlash } from '../net/url.mjs';
+
+function resolveLanIp({ env = process.env } = {}) {
+  const raw = (env.HAPPY_STACKS_LAN_IP ?? env.HAPPY_LOCAL_LAN_IP ?? '').toString().trim();
+  return raw || pickLanIpv4() || '';
+}
+
+function isLocalHostName(hostname) {
+  const h = String(hostname ?? '').trim().toLowerCase();
+  if (!h) return false;
+  if (h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0') return true;
+  if (h.endsWith('.localhost')) return true;
+  return false;
+}
+
+/**
+ * For mobile devices, `localhost` and `*.localhost` are not reachable.
+ *
+ * This helper rewrites any local server URL to a LAN-reachable URL using the machine's LAN IPv4.
+ * It preserves protocol, port, and path/query.
+ *
+ * Notes:
+ * - If the URL is already non-local (e.g. Tailscale HTTPS), it is returned unchanged.
+ * - If LAN IP cannot be determined, it returns the original URL unchanged.
+ */
+export function resolveMobileReachableServerUrl({
+  env = process.env,
+  serverUrl,
+  serverPort,
+} = {}) {
+  const raw = String(serverUrl ?? '').trim();
+  const fallbackPort = Number(serverPort);
+  const fallback = Number.isFinite(fallbackPort) && fallbackPort > 0 ? `http://localhost:${fallbackPort}` : '';
+  const base = raw || fallback;
+  if (!base) return '';
+
+  let parsed;
+  try {
+    parsed = new URL(base);
+  } catch {
+    return base;
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return base;
+  }
+
+  if (!isLocalHostName(parsed.hostname)) {
+    return normalizeUrlNoTrailingSlash(parsed.toString());
+  }
+
+  const lanIp = resolveLanIp({ env });
+  if (!lanIp) {
+    return normalizeUrlNoTrailingSlash(parsed.toString());
+  }
+
+  parsed.hostname = lanIp;
+  return normalizeUrlNoTrailingSlash(parsed.toString());
+}
+

package/scripts/utils/server/mobile_api_url.test.mjs

@@ -0,0 +1,41 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveMobileReachableServerUrl } from './mobile_api_url.mjs';
+
+test('resolveMobileReachableServerUrl rewrites localhost to LAN IP (env override)', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '192.168.0.50' },
+    serverUrl: 'http://localhost:3005',
+    serverPort: 3005,
+  });
+  assert.equal(out, 'http://192.168.0.50:3005');
+});
+
+test('resolveMobileReachableServerUrl rewrites *.localhost to LAN IP (env override)', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '10.0.0.12' },
+    serverUrl: 'http://happy-exp1.localhost:3009/',
+    serverPort: 3009,
+  });
+  assert.equal(out, 'http://10.0.0.12:3009');
+});
+
+test('resolveMobileReachableServerUrl preserves path and query', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '10.0.0.12' },
+    serverUrl: 'http://127.0.0.1:3005/api?x=1',
+    serverPort: 3005,
+  });
+  assert.equal(out, 'http://10.0.0.12:3005/api?x=1');
+});
+
+test('resolveMobileReachableServerUrl does not rewrite non-local URLs', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '192.168.0.50' },
+    serverUrl: 'https://my-machine.tailnet.ts.net',
+    serverPort: 3005,
+  });
+  assert.equal(out, 'https://my-machine.tailnet.ts.net');
+});
+

package/scripts/utils/server/urls.mjs

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 
 import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { preferStackLocalhostUrl } from '../paths/localhost_host.mjs';
 import { resolvePublicServerUrl } from '../../tailscale.mjs';
 import { resolveServerPortFromEnv } from './port.mjs';
+import { normalizeUrlNoTrailingSlash } from '../net/url.mjs';
 
 function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
   try {
@@ -31,14 +33,15 @@ function stackEnvExplicitlySetsWebappUrl({ env, stackName }) {
 }
 
 export function getPublicServerUrlEnvOverride({ env = process.env, serverPort, stackName = null } = {}) {
-  const defaultPublicUrl = `http://localhost:${serverPort}`;
   const name =
     (stackName ?? '').toString().trim() ||
     (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
-    getStackName();
+    getStackName(env);
+  const defaultPublicUrl = `http://localhost:${serverPort}`;
 
   let envPublicUrl =
     (env.HAPPY_STACKS_SERVER_URL ?? env.HAPPY_LOCAL_SERVER_URL ?? '').toString().trim() || '';
+  envPublicUrl = normalizeUrlNoTrailingSlash(envPublicUrl);
 
   // Safety: for non-main stacks, ignore a global SERVER_URL unless it was explicitly set in the stack env file.
   if (name !== 'main' && envPublicUrl && !stackEnvExplicitlySetsPublicUrl({ env, stackName: name })) {
@@ -52,7 +55,7 @@ export function getWebappUrlEnvOverride({ env = process.env, stackName = null }
   const name =
     (stackName ?? '').toString().trim() ||
     (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
-    getStackName();
+    getStackName(env);
 
   let envWebappUrl = (env.HAPPY_WEBAPP_URL ?? '').toString().trim() || '';
 
@@ -66,18 +69,25 @@ export function getWebappUrlEnvOverride({ env = process.env, stackName = null }
 
 export async function resolveServerUrls({ env = process.env, serverPort, allowEnable = true } = {}) {
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const stackName =
+    (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
+    getStackName(env);
   const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env, serverPort });
   const resolved = await resolvePublicServerUrl({
     internalServerUrl,
     defaultPublicUrl,
     envPublicUrl,
     allowEnable,
+    stackName,
   });
+  const publicServerUrl = normalizeUrlNoTrailingSlash(
+    await preferStackLocalhostUrl(resolved.publicServerUrl, { stackName })
+  );
   return {
     internalServerUrl,
     defaultPublicUrl,
     envPublicUrl,
-    publicServerUrl: resolved.publicServerUrl,
+    publicServerUrl,
     publicServerUrlSource: resolved.source,
   };
 }

package/scripts/utils/service/autostart_darwin.mjs

@@ -1,15 +1,54 @@
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 
 import { runCapture } from '../proc/proc.mjs';
 import { getDefaultAutostartPaths } from '../paths/paths.mjs';
 import { resolveInstalledCliRoot, resolveInstalledPath } from '../paths/runtime.mjs';
+import { getCanonicalHomeDir } from '../env/config.mjs';
 
 function plistPathForLabel(label) {
   return join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
 }
 
+function splitPath(p) {
+  return String(p ?? '')
+    .split(':')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function buildLaunchdPath({ execPath = process.execPath, basePath = process.env.PATH } = {}) {
+  // launchd starts with a minimal environment; ensure common tool paths exist,
+  // and include the current Node binary directory so shell shims that exec `node`
+  // still work (e.g. nvm-managed installs).
+  const nodeDir = execPath ? dirname(execPath) : '';
+  const defaults = splitPath('/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin');
+  const fromNode = nodeDir ? [nodeDir] : [];
+  const fromEnv = splitPath(basePath);
+
+  const seen = new Set();
+  const out = [];
+  for (const part of [...fromNode, ...fromEnv, ...defaults]) {
+    if (seen.has(part)) continue;
+    seen.add(part);
+    out.push(part);
+  }
+  return out.join(':') || '/usr/bin:/bin:/usr/sbin:/sbin';
+}
+
+export function pickLaunchdProgramArgs({ rootDir, execPath = process.execPath } = {}) {
+  // Prefer the stable shim under the canonical home dir (used by selfhost installs).
+  // This keeps the LaunchAgent pointing at a stable path while allowing runtime updates.
+  const happysShim = join(getCanonicalHomeDir(), 'bin', 'happys');
+  if (existsSync(happysShim)) {
+    return [happysShim, 'start'];
+  }
+  // Fallback: call the Node entry directly (works in repo-only installs).
+  return [execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+}
+
 function xmlEscape(s) {
   return String(s ?? '')
     .replaceAll('&', '&')
@@ -72,11 +111,12 @@ export async function ensureMacAutostartEnabled({ rootDir, label, env }) {
   await mkdir(dirname(stdoutPath), { recursive: true }).catch(() => {});
   await mkdir(dirname(stderrPath), { recursive: true }).catch(() => {});
 
-  const programArgs = [process.execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+  const programArgs = pickLaunchdProgramArgs({ rootDir, execPath: process.execPath });
   const mergedEnv = {
     ...(env ?? {}),
     // Ensure a reasonable PATH for subprocesses (git/docker/etc) in launchd’s minimal environment.
-    PATH: (process.env.PATH ?? '').trim() || '/usr/bin:/bin:/usr/sbin:/sbin',
+    // Also ensure Node is on PATH for shell shims that exec `node` (common with nvm installs).
+    PATH: buildLaunchdPath({ execPath: process.execPath, basePath: process.env.PATH }),
   };
 
   const xml = plistXml({

package/scripts/utils/service/autostart_darwin.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { buildLaunchdPath, pickLaunchdProgramArgs } from './autostart_darwin.mjs';
+
+test('buildLaunchdPath includes node dir and common tool paths', () => {
+  const execPath = '/Users/me/.nvm/versions/node/v22.14.0/bin/node';
+  const p = buildLaunchdPath({ execPath, basePath: '' });
+
+  assert.ok(p.includes('/Users/me/.nvm/versions/node/v22.14.0/bin'), 'includes node dir');
+  assert.ok(p.includes('/usr/bin'), 'includes /usr/bin');
+  assert.ok(p.includes('/bin'), 'includes /bin');
+});
+
+test('pickLaunchdProgramArgs uses stable happys shim when present', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-home-'));
+  const shim = join(dir, 'bin', 'happys');
+  await mkdir(join(dir, 'bin'), { recursive: true });
+  await writeFile(shim, '#!/bin/sh\necho ok\n', { encoding: 'utf-8' });
+
+  // Temporarily point canonical home at our temp dir via env var used by getCanonicalHomeDirFromEnv().
+  const prev = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = dir;
+  try {
+    const args = pickLaunchdProgramArgs({ rootDir: '/fake/root' });
+    assert.deepEqual(args, [shim, 'start']);
+  } finally {
+    if (prev == null) delete process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+    else process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = prev;
+  }
+});
+
+test('pickLaunchdProgramArgs falls back to node + happys.mjs when shim missing', () => {
+  const prev = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = '/definitely-not-a-real-path';
+  try {
+    const execPath = '/usr/local/bin/node';
+    const args = pickLaunchdProgramArgs({ rootDir: '/cli/root', execPath });
+    assert.equal(args[0], execPath);
+    assert.ok(String(args[1]).endsWith('/bin/happys.mjs'));
+    assert.equal(args[2], 'start');
+  } finally {
+    if (prev == null) delete process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+    else process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = prev;
+  }
+});
+

package/scripts/utils/stack/context.mjs

@@ -3,12 +3,12 @@ import { getStackRuntimeStatePath } from './runtime_state.mjs';
 
 export function resolveStackContext({ env = process.env, autostart = null } = {}) {
   const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();
-  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName(env);
   const stackMode = Boolean(explicitStack);
 
   const envPath =
     (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
-    resolveStackEnvPath(stackName).envPath;
+    resolveStackEnvPath(stackName, env).envPath;
 
   const runtimeStatePath =
     (env.HAPPY_STACKS_RUNTIME_STATE_PATH ?? env.HAPPY_LOCAL_RUNTIME_STATE_PATH ?? '').toString().trim() ||

package/scripts/utils/stack/editor_workspace.mjs

@@ -13,7 +13,7 @@ import { getCliHomeDirFromEnvOrDefault } from './dirs.mjs';
 function resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv }) {
   const raw = getEnvValueAny(stackEnv, ['HAPPY_STACKS_WORKSPACE_DIR', 'HAPPY_LOCAL_WORKSPACE_DIR']);
   if (!raw) {
-    return getWorkspaceDir(rootDir);
+    return getWorkspaceDir(rootDir, stackEnv);
   }
   const expanded = expandHome(raw);
   return expanded.startsWith('/') ? expanded : resolve(rootDir, expanded);
@@ -21,7 +21,7 @@ function resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv }) {
 
 function resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component }) {
   const raw = getEnvValueAny(stackEnv, keys);
-  if (!raw) return getComponentDir(rootDir, component);
+  if (!raw) return getComponentDir(rootDir, component, stackEnv);
   const expanded = expandHome(raw);
   if (expanded.startsWith('/')) return expanded;
   const workspaceDir = resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv });

package/scripts/utils/stack/pr_stack_name.mjs

@@ -0,0 +1,16 @@
+import { parseGithubPullRequest } from '../git/refs.mjs';
+import { sanitizeStackName } from './names.mjs';
+
+export function inferPrStackBaseName({ happy, happyCli, server, serverLight, fallback = 'pr' }) {
+  const parts = [];
+  const hn = parseGithubPullRequest(happy)?.number ?? null;
+  const cn = parseGithubPullRequest(happyCli)?.number ?? null;
+  const sn = parseGithubPullRequest(server)?.number ?? null;
+  const sln = parseGithubPullRequest(serverLight)?.number ?? null;
+  if (hn) parts.push(`happy${hn}`);
+  if (cn) parts.push(`cli${cn}`);
+  if (sn) parts.push(`server${sn}`);
+  if (sln) parts.push(`light${sln}`);
+  return sanitizeStackName(parts.length ? `pr-${parts.join('-')}` : fallback, { fallback, maxLen: 64 });
+}
+

package/scripts/utils/stack/runtime_state.mjs

@@ -51,7 +51,7 @@ export async function updateStackRuntimeStateFile(statePath, patch) {
   return next;
 }
 
-export async function recordStackRuntimeStart(statePath, { stackName, script, ephemeral, ownerPid, ports } = {}) {
+export async function recordStackRuntimeStart(statePath, { stackName, script, ephemeral, ownerPid, ports, ...rest } = {}) {
   const now = new Date().toISOString();
   const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
   const startedAt = typeof existing.startedAt === 'string' && existing.startedAt.trim() ? existing.startedAt : now;
@@ -64,6 +64,7 @@ export async function recordStackRuntimeStart(statePath, { stackName, script, ep
     ports: ports ?? {},
     startedAt,
     updatedAt: now,
+    ...(rest ?? {}),
   });
   await writeStackRuntimeStateFile(statePath, next);
   return next;

package/scripts/utils/stack/startup.mjs

@@ -1,5 +1,6 @@
 import { runCapture } from '../proc/proc.mjs';
 import { ensureDepsInstalled, pmExecBin } from '../proc/pm.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from '../env/sandbox.mjs';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -47,6 +48,12 @@ async function probeAccountCount({ serverDir, env }) {
 }
 
 export function resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive }) {
+  // Sandboxes should be isolated by default.
+  // Auto auth seeding can copy credentials/account rows from another stack (global state),
+  // which breaks isolation and can confuse guided auth flows (setup-pr/review-pr).
+  if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+    return false;
+  }
   const raw = (env.HAPPY_STACKS_AUTO_AUTH_SEED ?? env.HAPPY_LOCAL_AUTO_AUTH_SEED ?? '').toString().trim();
   if (raw) return raw !== '0';
 

package/scripts/utils/stack/stop.mjs

@@ -126,6 +126,7 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
     daemonSessionsStopped: null,
     daemonStopped: false,
     killedPorts: [],
+    expoDev: [],
     uiDev: [],
     mobile: [],
     infra: null,
@@ -136,7 +137,13 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
   const port = coercePort(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
   const backendPort = coercePort(env.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? env.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT);
   const cliHomeDir = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? join(baseDir, 'cli')).toString();
-  const cliBin = join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs');
+  // IMPORTANT:
+  // When stopping a stack, always prefer the stack's pinned happy-cli checkout/worktree.
+  // Otherwise, PR stacks can accidentally run the base checkout's CLI bin, which may not be built
+  // (we intentionally skip building base checkouts in some sandbox PR flows).
+  const pinnedCliDir = (env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI ?? env.HAPPY_LOCAL_COMPONENT_DIR_HAPPY_CLI ?? '').toString().trim();
+  const cliDir = pinnedCliDir || getComponentDir(rootDir, 'happy-cli');
+  const cliBin = join(cliDir, 'bin', 'happy.mjs');
   const envPath = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
 
   // Preferred: stop stack-started processes (by PID) recorded in stack.runtime.json.
@@ -194,12 +201,16 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
   }
 
   try {
-    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', envPath, json });
+    actions.expoDev = await stopExpoStateDir({ stackName, baseDir, kind: 'expo-dev', stateFileName: 'expo.state.json', envPath, json });
   } catch (e) {
-    actions.errors.push({ step: 'expo-ui', error: e instanceof Error ? e.message : String(e) });
+    actions.errors.push({ step: 'expo-dev', error: e instanceof Error ? e.message : String(e) });
   }
   try {
-    actions.mobile = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', envPath, json });
+    // Legacy cleanups (best-effort): older runs used separate state dirs.
+    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', envPath, json });
+    const killedDev = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile-dev', stateFileName: 'mobile.state.json', envPath, json });
+    const killedLegacy = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', envPath, json });
+    actions.mobile = [...killedDev, ...killedLegacy];
   } catch (e) {
     actions.errors.push({ step: 'expo-mobile', error: e instanceof Error ? e.message : String(e) });
   }

package/scripts/utils/stack_context.mjs

@@ -0,0 +1,23 @@
+import { getStackName, resolveStackEnvPath } from './paths/paths.mjs';
+import { getStackRuntimeStatePath } from './stack_runtime_state.mjs';
+
+export function resolveStackContext({ env = process.env, autostart = null } = {}) {
+  const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName(env);
+  const stackMode = Boolean(explicitStack);
+
+  const envPath =
+    (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+    resolveStackEnvPath(stackName, env).envPath;
+
+  const runtimeStatePath =
+    (env.HAPPY_STACKS_RUNTIME_STATE_PATH ?? env.HAPPY_LOCAL_RUNTIME_STATE_PATH ?? '').toString().trim() ||
+    getStackRuntimeStatePath(stackName);
+
+  const explicitEphemeral =
+    (env.HAPPY_STACKS_EPHEMERAL_PORTS ?? env.HAPPY_LOCAL_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+  const ephemeral = explicitEphemeral || (stackMode && stackName !== 'main');
+
+  return { stackMode, stackName, envPath, runtimeStatePath, ephemeral };
+}
+

package/scripts/utils/stack_runtime_state.mjs

@@ -0,0 +1,104 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { resolveStackEnvPath } from './paths/paths.mjs';
+
+export function getStackRuntimeStatePath(stackName) {
+  const { baseDir } = resolveStackEnvPath(stackName);
+  return join(baseDir, 'stack.runtime.json');
+}
+
+export function isPidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return null;
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeStackRuntimeStateFile(statePath, state) {
+  if (!statePath) {
+    throw new Error('[stack] missing runtime state path');
+  }
+  const dir = dirname(statePath);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.stack.runtime.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+  await writeFile(tmp, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+  await rename(tmp, statePath);
+}
+
+function isPlainObject(v) {
+  return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(a, b) {
+  if (!isPlainObject(a) || !isPlainObject(b)) {
+    return b;
+  }
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    if (isPlainObject(out[k]) && isPlainObject(v)) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function updateStackRuntimeStateFile(statePath, patch) {
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const next = deepMerge(existing, patch ?? {});
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeStart(statePath, { stackName, script, ephemeral, ownerPid, ports } = {}) {
+  const now = new Date().toISOString();
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const startedAt = typeof existing.startedAt === 'string' && existing.startedAt.trim() ? existing.startedAt : now;
+  const next = deepMerge(existing, {
+    version: 1,
+    stackName,
+    script,
+    ephemeral: Boolean(ephemeral),
+    ownerPid,
+    ports: ports ?? {},
+    startedAt,
+    updatedAt: now,
+  });
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeUpdate(statePath, patch = {}) {
+  return await updateStackRuntimeStateFile(statePath, {
+    ...(patch ?? {}),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function deleteStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return;
+    await unlink(statePath);
+  } catch {
+    // ignore
+  }
+}
+