@happier-dev/stack 0.1.0-preview.74.1

package/scripts/stack_env_cmd.test.mjs

@@ -0,0 +1,107 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runNodeCapture } from './testkit/stack_script_command_testkit.mjs';
+
+const scriptsDir = dirname(fileURLToPath(import.meta.url));
+const rootDir = dirname(scriptsDir);
+
+async function createStackEnvFixture(t, { stackName = 'exp-test', initialEnv = 'FOO=bar\n' } = {}) {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-env-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(envPath, initialEnv, 'utf-8');
+
+  return {
+    envPath,
+    stackName,
+    baseEnv: {
+      ...process.env,
+      HAPPIER_STACK_HOME_DIR: homeDir,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+    },
+  };
+}
+
+test('hstack stack env set/unset writes to stack env file', async (t) => {
+  const fixture = await createStackEnvFixture(t);
+
+  const setRes = await runNodeCapture(
+    [join(rootDir, 'scripts', 'stack.mjs'), 'env', fixture.stackName, 'set', 'OPENAI_API_KEY=sk-test'],
+    { cwd: rootDir, env: fixture.baseEnv }
+  );
+  assert.equal(setRes.code, 0, `expected exit 0, got ${setRes.code}\nstdout:\n${setRes.stdout}\nstderr:\n${setRes.stderr}`);
+
+  const afterSet = await readFile(fixture.envPath, 'utf-8');
+  assert.ok(afterSet.includes('OPENAI_API_KEY=sk-test\n'), `expected env file to include OPENAI_API_KEY\n${afterSet}`);
+
+  const unsetRes = await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'env', fixture.stackName, 'unset', 'FOO'], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(
+    unsetRes.code,
+    0,
+    `expected exit 0, got ${unsetRes.code}\nstdout:\n${unsetRes.stdout}\nstderr:\n${unsetRes.stderr}`
+  );
+
+  const afterUnset = await readFile(fixture.envPath, 'utf-8');
+  assert.ok(!afterUnset.includes('FOO=bar'), `expected env file to remove FOO\n${afterUnset}`);
+});
+
+test('hstack stack env <name> defaults to list', async (t) => {
+  const fixture = await createStackEnvFixture(t);
+
+  const res = await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'env', fixture.stackName], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.ok(res.stdout.includes('FOO=bar'), `expected stdout to include FOO=bar\nstdout:\n${res.stdout}`);
+});
+
+test('hstack stack env set rejects invalid KEY=VALUE assignment form', async (t) => {
+  const fixture = await createStackEnvFixture(t);
+
+  const res = await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'env', fixture.stackName, 'set', 'INVALID_ASSIGNMENT'], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 1, `expected exit 1, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stderr, /expected KEY=VALUE/i, `expected invalid assignment guidance in stderr\n${res.stderr}`);
+});
+
+test('hstack stack env list fails for unknown stack', async (t) => {
+  const fixture = await createStackEnvFixture(t, { stackName: 'known-stack' });
+  const missingStack = 'missing-stack';
+
+  const res = await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'env', missingStack, 'list'], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 1, `expected exit 1, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stderr, /does not exist yet/i, `expected missing stack error\n${res.stderr}`);
+});
+
+test('hstack stack env unset missing key is a no-op that keeps existing entries', async (t) => {
+  const fixture = await createStackEnvFixture(t, { initialEnv: 'FOO=bar\nBAR=baz\n' });
+
+  const res = await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'env', fixture.stackName, 'unset', 'MISSING_KEY'], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const afterUnset = await readFile(fixture.envPath, 'utf-8');
+  assert.ok(afterUnset.includes('FOO=bar'), `expected existing key FOO to remain\n${afterUnset}`);
+  assert.ok(afterUnset.includes('BAR=baz'), `expected existing key BAR to remain\n${afterUnset}`);
+});

package/scripts/stack_guided_login_bundle_error_parse.test.mjs

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { parseExpoBundleErrorPayload } from './utils/auth/stack_guided_login.mjs';
+
+test('parseExpoBundleErrorPayload extracts resolver errors from Metro JSON payloads', () => {
+  const payload = JSON.stringify({
+    type: 'UnableToResolveError',
+    message: 'Unable to resolve module ../ops from /tmp/taskSessionLink.ts',
+  });
+  const parsed = parseExpoBundleErrorPayload(payload);
+  assert.equal(parsed.type, 'UnableToResolveError');
+  assert.match(parsed.message, /Unable to resolve module/i);
+  assert.equal(parsed.isResolverError, true);
+});
+
+test('parseExpoBundleErrorPayload returns null for non-json payloads', () => {
+  const parsed = parseExpoBundleErrorPayload('<html>500</html>');
+  assert.equal(parsed, null);
+});

package/scripts/stack_guided_login_inner_invocation.test.mjs

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildStackAuthLoginInvocation } from './utils/auth/stack_guided_login.mjs';
+import { getStackRootFromMeta } from './testkit/auth_testkit.mjs';
+
+test('guided stack auth login invokes core happier auth login directly', () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  const webappUrl = 'http://localhost:1234';
+  const inv = buildStackAuthLoginInvocation({ rootDir, stackName: 'main', webappUrl });
+  assert.ok(Array.isArray(inv?.args));
+  assert.match(String(inv.args[0] ?? ''), /apps\/cli\/bin\/happier\.mjs$/);
+  assert.equal(inv.args[1], 'auth');
+  assert.ok(inv.args.includes('login'));
+  assert.equal(inv?.env?.HAPPIER_WEBAPP_URL, webappUrl);
+  assert.notEqual(inv?.env?.HAPPIER_STACK_AUTH_INNER, '1');
+});
+
+test('guided stack auth login defaults stack name to main and preserves invocation ordering', () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  const webappUrl = 'http://localhost:4321';
+  const inv = buildStackAuthLoginInvocation({ rootDir, stackName: '   ', webappUrl });
+  assert.equal(inv.args[1], 'auth');
+  assert.equal(inv.args[2], 'login');
+  assert.equal(inv.env.HAPPIER_WEBAPP_URL, webappUrl);
+});
+
+test('guided stack auth login invocation merges caller env', () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  const inv = buildStackAuthLoginInvocation({
+    rootDir,
+    stackName: 'feature-1',
+    webappUrl: 'http://localhost:5555',
+    env: { CUSTOM_FLAG: 'yes', HAPPIER_STACK_AUTH_INNER: '0' },
+  });
+  assert.equal(inv.env.CUSTOM_FLAG, 'yes');
+  assert.equal(inv.env.HAPPIER_STACK_AUTH_INNER, '0');
+});
+
+test('guided stack auth login invocation rejects empty webappUrl', () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  assert.throws(
+    () => buildStackAuthLoginInvocation({ rootDir, stackName: 'main', webappUrl: '   ' }),
+    /requires a webappUrl/i
+  );
+});

package/scripts/stack_happy_cmd.integration.test.mjs

@@ -0,0 +1,263 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runNodeCapture } from './testkit/stack_script_command_testkit.mjs';
+
+const scriptsDir = dirname(fileURLToPath(import.meta.url));
+const rootDir = dirname(scriptsDir);
+
+async function ensureMinimalHappierMonorepo({ monoRoot }) {
+  await mkdir(join(monoRoot, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(monoRoot, 'apps', 'cli'), { recursive: true });
+  await mkdir(join(monoRoot, 'apps', 'server'), { recursive: true });
+  await writeFile(join(monoRoot, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+}
+
+async function writeStubHappyCli({ cliDir, message }) {
+  await mkdir(join(cliDir, 'dist'), { recursive: true });
+  await writeFile(
+    join(cliDir, 'dist', 'index.mjs'),
+    [
+      `console.log(JSON.stringify({`,
+      `  message: ${JSON.stringify(message)},`,
+      `  stack: process.env.HAPPIER_STACK_STACK || null,`,
+      `  envFile: process.env.HAPPIER_STACK_ENV_FILE || null,`,
+      `  homeDir: process.env.HAPPIER_HOME_DIR || null,`,
+      `  serverUrl: process.env.HAPPIER_SERVER_URL || null,`,
+      `  webappUrl: process.env.HAPPIER_WEBAPP_URL || null,`,
+      `}));`,
+    ].join('\n'),
+    'utf-8'
+  );
+}
+
+async function writeFailingStubHappyCli({ cliDir, errorMessage }) {
+  await mkdir(join(cliDir, 'dist'), { recursive: true });
+  await writeFile(join(cliDir, 'dist', 'index.mjs'), `console.error(${JSON.stringify(errorMessage)});\nprocess.exit(1);\n`, 'utf-8');
+}
+
+async function createHappyStackFixture(
+  t,
+  {
+    prefix,
+    stackName = 'exp-test',
+    serverPort = 3999,
+    stubType = 'success',
+    message = 'hello',
+    errorMessage = 'stub failure',
+    includePinnedServerPortInEnvFile = true,
+    runtimeOwnerPid = null,
+    runtimeServerPid = null,
+  } = {}
+) {
+  const tmp = await mkdtemp(join(tmpdir(), prefix));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const workspaceDir = join(tmp, 'workspace');
+  const monoRoot = join(workspaceDir, 'happier');
+  const cliDir = join(monoRoot, 'apps', 'cli');
+  await ensureMinimalHappierMonorepo({ monoRoot });
+
+  if (stubType === 'failing') {
+    await writeFailingStubHappyCli({ cliDir, errorMessage });
+  } else {
+    await writeStubHappyCli({ cliDir, message });
+  }
+
+  const stackCliHome = join(storageDir, stackName, 'cli');
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(
+    envPath,
+    [
+      `HAPPIER_STACK_REPO_DIR=${monoRoot}`,
+      `HAPPIER_STACK_CLI_HOME_DIR=${stackCliHome}`,
+      ...(includePinnedServerPortInEnvFile ? [`HAPPIER_STACK_SERVER_PORT=${serverPort}`] : []),
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  if (runtimeOwnerPid !== null || runtimeServerPid !== null) {
+    await writeFile(
+      join(storageDir, stackName, 'stack.runtime.json'),
+      JSON.stringify(
+        {
+          version: 1,
+          stackName,
+          ephemeral: true,
+          ownerPid: runtimeOwnerPid,
+          ports: { server: serverPort },
+          processes: { serverPid: runtimeServerPid },
+        },
+        null,
+        2
+      ) + '\n',
+      'utf-8'
+    );
+  }
+
+  return {
+    stackName,
+    storageDir,
+    baseEnv: {
+      ...process.env,
+      HAPPIER_STACK_HOME_DIR: homeDir,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_WORKSPACE_DIR: workspaceDir,
+      HAPPIER_STACK_CLI_ROOT_DISABLE: '1',
+    },
+  };
+}
+
+test('hstack stack happier <name> runs CLI under that stack env', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happier-stack-stack-happy-',
+    message: 'hello',
+    serverPort: 3999,
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'hello');
+  assert.equal(out.stack, fixture.stackName);
+  assert.ok(String(out.envFile).endsWith(`/${fixture.stackName}/env`), `expected envFile to end with /${fixture.stackName}/env, got: ${out.envFile}`);
+  assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli'));
+  assert.equal(out.serverUrl, 'http://127.0.0.1:3999');
+});
+
+test('hstack stack happier <name> overrides pre-set HAPPIER_* env vars with stack-scoped values', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happier-stack-stack-happy-override-',
+    message: 'override',
+    serverPort: 4123,
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
+    cwd: rootDir,
+    env: {
+      ...fixture.baseEnv,
+      HAPPIER_HOME_DIR: join(fixture.storageDir, 'wrong', 'cli'),
+      HAPPIER_SERVER_URL: 'http://127.0.0.1:3005',
+      HAPPIER_WEBAPP_URL: 'http://wrong-webapp.example.test',
+    },
+  });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'override');
+  assert.equal(out.stack, fixture.stackName);
+  assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli'));
+  assert.equal(out.serverUrl, 'http://127.0.0.1:4123');
+});
+
+test('hstack stack happier <name> uses stack.runtime.json ports when env file does not pin HAPPIER_STACK_SERVER_PORT', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happier-stack-stack-happy-runtime-ports-',
+    message: 'runtime-ports',
+    serverPort: 4777,
+    includePinnedServerPortInEnvFile: false,
+    // Simulate a stale owner pid but a still-running server process.
+    runtimeOwnerPid: 999999,
+    runtimeServerPid: process.pid,
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'runtime-ports');
+  assert.equal(out.stack, fixture.stackName);
+  assert.equal(out.serverUrl, 'http://127.0.0.1:4777');
+});
+
+test('hstack stack happier <name> --identity=<name> uses identity-scoped HAPPIER_HOME_DIR', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happier-stack-stack-happy-identity-',
+    message: 'identity',
+    serverPort: 3999,
+  });
+  const identity = 'account-a';
+
+  const res = await runNodeCapture(
+    [join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName, `--identity=${identity}`],
+    { cwd: rootDir, env: fixture.baseEnv }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'identity');
+  assert.equal(out.stack, fixture.stackName);
+  assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli-identities', identity));
+  assert.equal(out.serverUrl, 'http://127.0.0.1:3999');
+});
+
+test('hstack <stack> happier ... shorthand runs CLI under that stack env', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happy-stacks-stack-happy-',
+    message: 'shorthand',
+    serverPort: 4101,
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), fixture.stackName, 'happier'], { cwd: rootDir, env: fixture.baseEnv });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'shorthand');
+  assert.equal(out.stack, fixture.stackName);
+  assert.equal(out.serverUrl, 'http://127.0.0.1:4101');
+});
+
+test('hstack stack happier <name> does not print wrapper stack traces on CLI failure', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happy-stacks-stack-happy-fail-',
+    stubType: 'failing',
+    errorMessage: 'stub failure',
+    serverPort: 3999,
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName, 'attach', 'abc'], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 1, `expected exit 1, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.ok(res.stderr.includes('stub failure'), `expected stderr to include stub failure, got:\n${res.stderr}`);
+  assert.ok(!res.stderr.includes('[happier] failed:'), `expected no [happier] failed stack trace, got:\n${res.stderr}`);
+  assert.ok(!res.stderr.includes('[stack] failed:'), `expected no [stack] failed stack trace, got:\n${res.stderr}`);
+  assert.ok(!res.stderr.includes('node:internal'), `expected no node:internal stack trace, got:\n${res.stderr}`);
+});
+
+test('hstack stack <name> happier ... stack-name-first shorthand works', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happier-stack-stack-happy-name-first-',
+    message: 'name-first',
+    serverPort: 3999,
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', fixture.stackName, 'happier'], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'name-first');
+  assert.equal(out.stack, fixture.stackName);
+});

package/scripts/stack_info_snapshot_running_status.test.mjs

@@ -0,0 +1,186 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import net from 'node:net';
+
+import { readStackInfoSnapshot } from './stack/stack_info_snapshot.mjs';
+
+function withStorageDir(storageDir) {
+  const prev = process.env.HAPPIER_STACK_STORAGE_DIR;
+  process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
+  return () => {
+    if (typeof prev === 'undefined') {
+      delete process.env.HAPPIER_STACK_STORAGE_DIR;
+    } else {
+      process.env.HAPPIER_STACK_STORAGE_DIR = prev;
+    }
+  };
+}
+
+async function withListeningServer() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? Number(addr.port) : 0;
+  return {
+    port,
+    async close() {
+      await new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+async function reserveUnusedPort() {
+  const listener = await withListeningServer();
+  const port = listener.port;
+  await listener.close();
+  return port;
+}
+
+test('readStackInfoSnapshot reports running when owner pid is stale but an infra pid is alive', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-info-running-process-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'dev-auth';
+  const baseDir = join(storageDir, stackName);
+
+  await mkdir(baseDir, { recursive: true });
+  await writeFile(join(baseDir, 'env'), 'HAPPIER_STACK_SERVER_PORT=3009\n', 'utf-8');
+  await writeFile(
+    join(baseDir, 'stack.runtime.json'),
+    JSON.stringify({
+      version: 1,
+      stackName,
+      ownerPid: 999_999_999,
+      processes: { serverPid: process.pid },
+      ports: { server: 3009 },
+    }) + '\n',
+    'utf-8'
+  );
+
+  const restore = withStorageDir(storageDir);
+  try {
+    const out = await readStackInfoSnapshot({ rootDir: process.cwd(), stackName });
+    assert.equal(out.runtime.running, true);
+    assert.equal(out.runtime.runningPid, process.pid);
+  } finally {
+    restore();
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readStackInfoSnapshot reports running when owner pid is stale but stack server port is occupied', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-info-running-port-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'dev-auth';
+  const baseDir = join(storageDir, stackName);
+
+  await mkdir(baseDir, { recursive: true });
+
+  const listener = await withListeningServer();
+  await writeFile(join(baseDir, 'env'), `HAPPIER_STACK_SERVER_PORT=${listener.port}\n`, 'utf-8');
+  await writeFile(
+    join(baseDir, 'stack.runtime.json'),
+    JSON.stringify({
+      version: 1,
+      stackName,
+      ownerPid: 999_999_999,
+      processes: { serverPid: 999_999_998 },
+      ports: { server: listener.port },
+    }) + '\n',
+    'utf-8'
+  );
+
+  const restore = withStorageDir(storageDir);
+  try {
+    const out = await readStackInfoSnapshot({ rootDir: process.cwd(), stackName });
+    assert.equal(out.runtime.running, true);
+    assert.equal(out.runtime.runningPid, null);
+  } finally {
+    restore();
+    await listener.close();
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readStackInfoSnapshot marks UI as down when expo runtime metadata is stale', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-info-ui-stale-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'dev-auth';
+  const baseDir = join(storageDir, stackName);
+
+  await mkdir(baseDir, { recursive: true });
+
+  const serverListener = await withListeningServer();
+  const staleUiPort = await reserveUnusedPort();
+  await writeFile(join(baseDir, 'env'), `HAPPIER_STACK_SERVER_PORT=${serverListener.port}\n`, 'utf-8');
+  await writeFile(
+    join(baseDir, 'stack.runtime.json'),
+    JSON.stringify({
+      version: 1,
+      stackName,
+      ownerPid: 999_999_999,
+      processes: { serverPid: process.pid, expoPid: 999_999_998 },
+      ports: { server: serverListener.port },
+      expo: { webPort: staleUiPort, webEnabled: true },
+    }) + '\n',
+    'utf-8'
+  );
+
+  const restore = withStorageDir(storageDir);
+  try {
+    const out = await readStackInfoSnapshot({ rootDir: process.cwd(), stackName });
+    assert.equal(out.runtime.running, true);
+    assert.equal(out.runtime.components.server.running, true);
+    assert.equal(out.runtime.components.ui.running, false);
+    assert.equal(out.runtime.health.status, 'degraded');
+    assert.deepEqual(out.runtime.health.issues, ['ui_down']);
+  } finally {
+    restore();
+    await serverListener.close();
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readStackInfoSnapshot requires UI port reachability even when expo pid is alive', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-info-ui-unreachable-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'dev-auth';
+  const baseDir = join(storageDir, stackName);
+
+  await mkdir(baseDir, { recursive: true });
+
+  const serverListener = await withListeningServer();
+  const staleUiPort = await reserveUnusedPort();
+  await writeFile(join(baseDir, 'env'), `HAPPIER_STACK_SERVER_PORT=${serverListener.port}\n`, 'utf-8');
+  await writeFile(
+    join(baseDir, 'stack.runtime.json'),
+    JSON.stringify({
+      version: 1,
+      stackName,
+      ownerPid: 999_999_999,
+      processes: { serverPid: process.pid, expoPid: process.pid },
+      ports: { server: serverListener.port },
+      expo: { webPort: staleUiPort, webEnabled: true },
+    }) + '\n',
+    'utf-8'
+  );
+
+  const restore = withStorageDir(storageDir);
+  try {
+    const out = await readStackInfoSnapshot({ rootDir: process.cwd(), stackName });
+    assert.equal(out.runtime.running, true);
+    assert.equal(out.runtime.components.ui.pidAlive, true);
+    assert.equal(out.runtime.components.ui.running, false);
+    assert.equal(out.runtime.health.status, 'degraded');
+    assert.deepEqual(out.runtime.health.issues, ['ui_down']);
+  } finally {
+    restore();
+    await serverListener.close();
+    await rm(tmp, { recursive: true, force: true });
+  }
+});