happy-stacks 0.1.2 → 0.2.0

package/scripts/utils/proc.mjs

@@ -1,5 +1,23 @@
 import { spawn } from 'node:child_process';
 
+function writeWithPrefix(stream, prefix, bufState, chunk) {
+  const s = chunk.toString();
+  bufState.buf += s;
+  while (true) {
+    const idx = bufState.buf.indexOf('\n');
+    if (idx < 0) break;
+    const line = bufState.buf.slice(0, idx);
+    bufState.buf = bufState.buf.slice(idx + 1);
+    stream.write(`${prefix}${line}\n`);
+  }
+}
+
+function flushPrefixed(stream, prefix, bufState) {
+  if (!bufState.buf) return;
+  stream.write(`${prefix}${bufState.buf}\n`);
+  bufState.buf = '';
+}
+
 export function spawnProc(label, cmd, args, env, options = {}) {
   const child = spawn(cmd, args, {
     env,
@@ -10,8 +28,17 @@ export function spawnProc(label, cmd, args, env, options = {}) {
     ...options,
   });
 
-  child.stdout?.on('data', (d) => process.stdout.write(`[${label}] ${d.toString()}`));
-  child.stderr?.on('data', (d) => process.stderr.write(`[${label}] ${d.toString()}`));
+  const outState = { buf: '' };
+  const errState = { buf: '' };
+  const outPrefix = `[${label}] `;
+  const errPrefix = `[${label}] `;
+
+  child.stdout?.on('data', (d) => writeWithPrefix(process.stdout, outPrefix, outState, d));
+  child.stderr?.on('data', (d) => writeWithPrefix(process.stderr, errPrefix, errState, d));
+  child.on('close', () => {
+    flushPrefixed(process.stdout, outPrefix, outState);
+    flushPrefixed(process.stderr, errPrefix, errState);
+  });
   child.on('exit', (code, sig) => {
     if (code !== 0) {
       process.stderr.write(`[${label}] exited (code=${code}, sig=${sig})\n`);

package/scripts/utils/runtime.mjs

@@ -2,9 +2,7 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { expandHome } from './canonical_home.mjs';
 
 export function getRuntimeDir() {
   const fromEnv = (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim();

package/scripts/utils/sandbox.mjs

@@ -0,0 +1,14 @@
+export function getSandboxDir() {
+  const v = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
+  return v || '';
+}
+
+export function isSandboxed() {
+  return Boolean(getSandboxDir());
+}
+
+export function sandboxAllowsGlobalSideEffects() {
+  const raw = (process.env.HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL ?? '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y';
+}
+

package/scripts/utils/server.mjs

@@ -76,3 +76,27 @@ export async function waitForServerReady(url) {
   throw new Error(`Timed out waiting for server at ${url}`);
 }
 
+// Used for UI readiness checks (Expo / gateway / server). Treat any HTTP response as "up".
+export async function waitForHttpOk(url, { timeoutMs = 15_000, intervalMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const ctl = new AbortController();
+      const t = setTimeout(() => ctl.abort(), Math.min(2500, Math.max(250, intervalMs)));
+      try {
+        const res = await fetch(url, { method: 'GET', signal: ctl.signal });
+        if (res.status >= 100 && res.status < 600) {
+          return;
+        }
+      } finally {
+        clearTimeout(t);
+      }
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(intervalMs);
+  }
+  throw new Error(`Timed out waiting for HTTP response from ${url} after ${timeoutMs}ms`);
+}
+

package/scripts/utils/server_port.mjs

@@ -0,0 +1,9 @@
+export function resolveServerPortFromEnv({ env = process.env, defaultPort = 3005 } = {}) {
+  const raw =
+    (env.HAPPY_STACKS_SERVER_PORT ?? '').toString().trim() ||
+    (env.HAPPY_LOCAL_SERVER_PORT ?? '').toString().trim() ||
+    '';
+  const n = raw ? Number(raw) : Number(defaultPort);
+  return Number.isFinite(n) && n > 0 ? n : Number(defaultPort);
+}
+

package/scripts/utils/server_urls.mjs

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+import { getStackName, resolveStackEnvPath } from './paths.mjs';
+import { resolvePublicServerUrl } from '../tailscale.mjs';
+import { resolveServerPortFromEnv } from './server_port.mjs';
+
+function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
+  try {
+    const envPath =
+      (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+      resolveStackEnvPath(stackName).envPath;
+    if (!envPath || !existsSync(envPath)) return false;
+    const raw = readFileSync(envPath, 'utf-8');
+    return /^(HAPPY_STACKS_SERVER_URL|HAPPY_LOCAL_SERVER_URL)=/m.test(raw);
+  } catch {
+    return false;
+  }
+}
+
+export function getPublicServerUrlEnvOverride({ env = process.env, serverPort } = {}) {
+  const defaultPublicUrl = `http://localhost:${serverPort}`;
+  const stackName = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() || getStackName();
+
+  let envPublicUrl =
+    (env.HAPPY_STACKS_SERVER_URL ?? env.HAPPY_LOCAL_SERVER_URL ?? '').toString().trim() || '';
+
+  // Safety: for non-main stacks, ignore a global SERVER_URL unless it was explicitly set in the stack env file.
+  if (stackName !== 'main' && envPublicUrl && !stackEnvExplicitlySetsPublicUrl({ env, stackName })) {
+    envPublicUrl = '';
+  }
+
+  return { defaultPublicUrl, envPublicUrl, publicServerUrl: envPublicUrl || defaultPublicUrl };
+}
+
+export async function resolveServerUrls({ env = process.env, serverPort, allowEnable = true } = {}) {
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env, serverPort });
+  const resolved = await resolvePublicServerUrl({
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    allowEnable,
+  });
+  return {
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    publicServerUrl: resolved.publicServerUrl,
+    publicServerUrlSource: resolved.source,
+  };
+}
+
+export { resolveServerPortFromEnv };
+

package/scripts/utils/stack_context.mjs

@@ -0,0 +1,23 @@
+import { getStackName, resolveStackEnvPath } from './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();
+  const stackMode = Boolean(explicitStack);
+
+  const envPath =
+    (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+    resolveStackEnvPath(stackName).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.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
+  }
+}
+

package/scripts/utils/stack_startup.mjs

@@ -0,0 +1,208 @@
+import { runCapture } from './proc.mjs';
+import { ensureDepsInstalled, pmExecBin } from './pm.mjs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+function looksLikeMissingTableError(msg) {
+  const s = String(msg ?? '').toLowerCase();
+  return s.includes('does not exist') || s.includes('no such table');
+}
+
+async function probeAccountCount({ serverDir, env }) {
+  const probe = `
+	let db;
+	try {
+	  const { PrismaClient } = await import('@prisma/client');
+	  db = new PrismaClient();
+	  const accountCount = await db.account.count();
+	  console.log(JSON.stringify({ accountCount }));
+	} catch (e) {
+	  console.log(
+	    JSON.stringify({
+	      error: {
+	        name: e?.name,
+	        message: e?.message,
+	        code: e?.code,
+	      },
+	    })
+	  );
+	} finally {
+	  try {
+	    await db?.$disconnect();
+	  } catch {
+	    // ignore
+	  }
+	}
+	`.trim();
+
+  const out = await runCapture(process.execPath, ['--input-type=module', '-e', probe], { cwd: serverDir, env, timeoutMs: 15_000 });
+  const parsed = out.trim() ? JSON.parse(out.trim()) : {};
+  if (parsed?.error) {
+    const e = new Error(parsed.error.message || 'unknown prisma probe error');
+    if (typeof parsed.error.name === 'string' && parsed.error.name) e.name = parsed.error.name;
+    if (typeof parsed.error.code === 'string' && parsed.error.code) e.code = parsed.error.code;
+    throw e;
+  }
+  return Number(parsed.accountCount ?? 0);
+}
+
+export function resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive }) {
+  const raw = (env.HAPPY_STACKS_AUTO_AUTH_SEED ?? env.HAPPY_LOCAL_AUTO_AUTH_SEED ?? '').toString().trim();
+  if (raw) return raw !== '0';
+
+  // Legacy toggle (kept for existing setups):
+  // - if set, it only controls enable/disable; source stack remains configurable via HAPPY_STACKS_AUTH_SEED_FROM.
+  const legacy = (env.HAPPY_STACKS_AUTO_COPY_FROM_MAIN ?? env.HAPPY_LOCAL_AUTO_COPY_FROM_MAIN ?? '').toString().trim();
+  if (legacy) return legacy !== '0';
+
+  if (stackName === 'main') return false;
+
+  // Default:
+  // - always auto-seed in non-interactive contexts (agents/services)
+  // - in interactive shells, auto-seed only when the user explicitly configured a non-main seed stack
+  //   (this avoids silently spreading main identity for users who haven't opted in yet).
+  if (!isInteractive) return true;
+  const seed = (env.HAPPY_STACKS_AUTH_SEED_FROM ?? env.HAPPY_LOCAL_AUTH_SEED_FROM ?? '').toString().trim();
+  return Boolean(seed && seed !== 'main');
+}
+
+export function resolveAuthSeedFromEnv(env) {
+  // Back-compat for an earlier experimental var name:
+  // - if set to a non-bool-ish stack name, treat it as the seed source
+  // - if set to "1"/"true", ignore (source comes from HAPPY_STACKS_AUTH_SEED_FROM)
+  const legacyAutoFrom = (env.HAPPY_STACKS_AUTO_AUTH_SEED_FROM ?? env.HAPPY_LOCAL_AUTO_AUTH_SEED_FROM ?? '').toString().trim();
+  if (legacyAutoFrom && legacyAutoFrom !== '0' && legacyAutoFrom !== '1' && legacyAutoFrom.toLowerCase() !== 'true') {
+    return legacyAutoFrom;
+  }
+  // Legacy toggle: "on" implies main (historical behavior).
+  const legacy = (env.HAPPY_STACKS_AUTO_COPY_FROM_MAIN ?? env.HAPPY_LOCAL_AUTO_COPY_FROM_MAIN ?? '').toString().trim();
+  if (legacy && legacy !== '0') return 'main';
+  // Otherwise, use the general default seed stack.
+  const seed = (env.HAPPY_STACKS_AUTH_SEED_FROM ?? env.HAPPY_LOCAL_AUTH_SEED_FROM ?? '').toString().trim();
+  return seed || 'main';
+}
+
+export async function ensureServerLightSchemaReady({ serverDir, env }) {
+  await ensureDepsInstalled(serverDir, 'happy-server-light');
+
+  try {
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, pushed: false, accountCount };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!looksLikeMissingTableError(msg)) {
+      throw e;
+    }
+    await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['db', 'push'], env });
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, pushed: true, accountCount };
+  }
+}
+
+export async function ensureHappyServerSchemaReady({ serverDir, env }) {
+  await ensureDepsInstalled(serverDir, 'happy-server');
+
+  try {
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, migrated: false, accountCount };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!looksLikeMissingTableError(msg)) {
+      throw e;
+    }
+    // If tables are missing, try migrations (safe for postgres). Then re-probe.
+    await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env });
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, migrated: true, accountCount };
+  }
+}
+
+export async function getAccountCountForServerComponent({ serverComponentName, serverDir, env, bestEffort = false }) {
+  if (serverComponentName === 'happy-server-light') {
+    const ready = await ensureServerLightSchemaReady({ serverDir, env });
+    return { ok: true, accountCount: Number.isFinite(ready.accountCount) ? ready.accountCount : 0 };
+  }
+  if (serverComponentName === 'happy-server') {
+    try {
+      const ready = await ensureHappyServerSchemaReady({ serverDir, env });
+      return { ok: true, accountCount: Number.isFinite(ready.accountCount) ? ready.accountCount : 0 };
+    } catch (e) {
+      if (!bestEffort) throw e;
+      return { ok: false, accountCount: null, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  return { ok: false, accountCount: null, error: `unknown server component: ${serverComponentName}` };
+}
+
+export async function maybeAutoCopyAuthFromMainIfNeeded({
+  rootDir,
+  env,
+  enabled,
+  stackName,
+  cliHomeDir,
+  accountCount,
+  quiet = false,
+  authEnv = null,
+}) {
+  const accessKeyPath = join(cliHomeDir, 'access.key');
+  const hasAccessKey = existsSync(accessKeyPath);
+
+  // "Initialized" heuristic:
+  // - if we have credentials AND (when known) at least one Account row, we don't need to seed from main.
+  const hasAccounts = typeof accountCount === 'number' ? accountCount > 0 : null;
+  const needsSeed = !hasAccessKey || hasAccounts === false;
+
+  if (!enabled || !needsSeed) {
+    return { ok: true, skipped: true, reason: !enabled ? 'disabled' : 'already_initialized' };
+  }
+
+  const reason = !hasAccessKey ? 'missing_credentials' : 'no_accounts';
+  const fromStackName = resolveAuthSeedFromEnv(env);
+  const linkAuth =
+    (env.HAPPY_STACKS_AUTH_LINK ?? env.HAPPY_LOCAL_AUTH_LINK ?? '').toString().trim() === '1' ||
+    (env.HAPPY_STACKS_AUTH_MODE ?? env.HAPPY_LOCAL_AUTH_MODE ?? '').toString().trim() === 'link';
+  if (!quiet) {
+    console.log(`[local] auth: auto seed from ${fromStackName} for ${stackName} (${reason})`);
+  }
+
+  // Best-effort: copy credentials/master secret + seed accounts from the configured seed stack.
+  // Keep this non-fatal; the daemon will emit actionable errors if it still can't authenticate.
+  try {
+    const out = await runCapture(
+      process.execPath,
+      [`${rootDir}/scripts/auth.mjs`, 'copy-from', fromStackName, '--json', ...(linkAuth ? ['--link'] : [])],
+      {
+      cwd: rootDir,
+      env: authEnv && typeof authEnv === 'object' ? authEnv : env,
+      }
+    );
+    return { ok: true, skipped: false, reason, out: out.trim() ? JSON.parse(out) : null };
+  } catch (e) {
+    return { ok: false, skipped: false, reason, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function prepareDaemonAuthSeedIfNeeded({
+  rootDir,
+  env,
+  stackName,
+  cliHomeDir,
+  startDaemon,
+  isInteractive,
+  accountCount,
+  quiet = false,
+  authEnv = null,
+}) {
+  if (!startDaemon) return { ok: true, skipped: true, reason: 'no_daemon' };
+  const enabled = resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive });
+  return await maybeAutoCopyAuthFromMainIfNeeded({
+    rootDir,
+    env,
+    enabled,
+    stackName,
+    cliHomeDir,
+    accountCount,
+    quiet,
+    authEnv,
+  });
+}

package/scripts/utils/stack_stop.mjs

@@ -3,10 +3,11 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { getComponentDir } from './paths.mjs';
-import { killPortListeners } from './ports.mjs';
-import { isPidAlive, killPid, readPidState } from './expo.mjs';
+import { isPidAlive, readPidState } from './expo.mjs';
 import { stopLocalDaemon } from '../daemon.mjs';
 import { stopHappyServerManagedInfra } from './happy_server_infra.mjs';
+import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './stack_runtime_state.mjs';
+import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedle } from './ownership.mjs';
 
 function parseIntOrNull(raw) {
   const s = String(raw ?? '').trim();
@@ -89,7 +90,7 @@ async function stopDaemonTrackedSessions({ cliHomeDir, json }) {
   return { ok: true, skipped: false, stoppedSessionIds };
 }
 
-async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, json }) {
+async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, envPath, json }) {
   const root = join(baseDir, kind);
   let entries = [];
   try {
@@ -106,31 +107,28 @@ async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, json
     const state = await readPidState(statePath);
     if (!state) continue;
     const pid = Number(state.pid);
-    const port = parseIntOrNull(state.port);
 
     if (!Number.isFinite(pid) || pid <= 1) continue;
     if (!isPidAlive(pid)) continue;
 
     if (!json) {
       // eslint-disable-next-line no-console
-      console.log(`[stack] stopping ${kind} (pid=${pid}${port ? ` port=${port}` : ''}) for ${stackName}`);
-    }
-    if (port) {
-      // eslint-disable-next-line no-await-in-loop
-      await killPortListeners(port, { label: `${stackName} ${kind}` });
+      console.log(`[stack] stopping ${kind} (pid=${pid}) for ${stackName}`);
     }
     // eslint-disable-next-line no-await-in-loop
-    await killPid(pid);
-    killed.push({ pid, port, statePath });
+    await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: kind, json });
+    killed.push({ pid, port: null, statePath });
   }
   return killed;
 }
 
-export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json, noDocker = false, aggressive = false }) {
+export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json, noDocker = false, aggressive = false, sweepOwned = false }) {
   const actions = {
     stackName,
     baseDir,
     aggressive,
+    sweepOwned,
+    runner: null,
     daemonSessionsStopped: null,
     daemonStopped: false,
     killedPorts: [],
@@ -145,6 +143,30 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
   const backendPort = parseIntOrNull(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');
+  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.
+  // This is safer than killing whatever happens to listen on a port, and doesn't rely on the runner's shutdown handler.
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  const runnerPid = Number(runtimeState?.ownerPid);
+  const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
+
+  // Kill known child processes first (process groups), then stop daemon, then stop runner.
+  const killedProcessPids = [];
+  for (const [key, rawPid] of Object.entries(processes)) {
+    const pid = Number(rawPid);
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    if (!isPidAlive(pid)) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: key, json });
+    if (res.killed) {
+      killedProcessPids.push({ key, pid, reason: res.reason, pgid: res.pgid ?? null });
+    }
+  }
+  actions.runner = { stopped: false, pid: Number.isFinite(runnerPid) ? runnerPid : null, reason: runtimeState ? 'not_running_or_not_owned' : 'missing_state' };
+  actions.killedPorts = actions.killedPorts ?? [];
+  actions.processes = { killed: killedProcessPids };
 
   if (aggressive) {
     try {
@@ -162,33 +184,36 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
     actions.errors.push({ step: 'daemon', error: e instanceof Error ? e.message : String(e) });
   }
 
+  // Now stop the runner PID last (if it exists). This should clean up any remaining state files it owns.
+  if (Number.isFinite(runnerPid) && runnerPid > 1 && isPidAlive(runnerPid)) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[stack] stopping runner (pid=${runnerPid}) for ${stackName}`);
+    }
+    const res = await killPidOwnedByStack(runnerPid, { stackName, envPath, cliHomeDir, label: 'runner', json });
+    actions.runner = { stopped: res.killed, pid: runnerPid, reason: res.reason };
+  }
+
+  // Only delete runtime state if the runner is confirmed stopped (or not running).
+  if (!isPidAlive(runnerPid)) {
+    await deleteStackRuntimeStateFile(runtimeStatePath);
+  }
+
   try {
-    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', json });
+    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', envPath, json });
   } catch (e) {
     actions.errors.push({ step: 'expo-ui', error: e instanceof Error ? e.message : String(e) });
   }
   try {
-    actions.mobile = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', json });
+    actions.mobile = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', envPath, json });
   } catch (e) {
     actions.errors.push({ step: 'expo-mobile', error: e instanceof Error ? e.message : String(e) });
   }
 
-  if (backendPort) {
-    try {
-      const pids = await killPortListeners(backendPort, { label: `${stackName} happy-server-backend` });
-      actions.killedPorts.push({ port: backendPort, pids, label: 'happy-server-backend' });
-    } catch (e) {
-      actions.errors.push({ step: 'backend-port', error: e instanceof Error ? e.message : String(e) });
-    }
-  }
-  if (port) {
-    try {
-      const pids = await killPortListeners(port, { label: `${stackName} server` });
-      actions.killedPorts.push({ port, pids, label: 'server' });
-    } catch (e) {
-      actions.errors.push({ step: 'server-port', error: e instanceof Error ? e.message : String(e) });
-    }
-  }
+  // IMPORTANT:
+  // Never kill "whatever is listening on a port" in stack mode.
+  void backendPort;
+  void port;
 
   const managed = (env.HAPPY_STACKS_MANAGED_INFRA ?? env.HAPPY_LOCAL_MANAGED_INFRA ?? '1').toString().trim() !== '0';
   if (!noDocker && serverComponent === 'happy-server' && managed) {
@@ -201,6 +226,30 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
     actions.infra = { ok: true, skipped: true, reason: noDocker ? 'no_docker' : 'not_managed_or_not_happy_server' };
   }
 
+  // Last resort: sweep any remaining processes that still carry this stack env file in their environment.
+  // This is still safe because envPath is unique per stack; we also exclude our own PID.
+  if (sweepOwned && envPath) {
+    const needle1 = `HAPPY_STACKS_ENV_FILE=${envPath}`;
+    const needle2 = `HAPPY_LOCAL_ENV_FILE=${envPath}`;
+    const pids = [
+      ...(await listPidsWithEnvNeedle(needle1)),
+      ...(await listPidsWithEnvNeedle(needle2)),
+    ]
+      .filter((pid) => pid !== process.pid)
+      .filter((pid) => Number.isFinite(pid) && pid > 1);
+
+    const swept = [];
+    for (const pid of Array.from(new Set(pids))) {
+      if (!isPidAlive(pid)) continue;
+      // eslint-disable-next-line no-await-in-loop
+      const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: 'sweep', json });
+      if (res.killed) {
+        swept.push({ pid, reason: res.reason, pgid: res.pgid ?? null });
+      }
+    }
+    actions.sweep = { pids: swept };
+  }
+
   return actions;
 }