@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.11

package/scripts/root_package_repo_local_scripts.test.mjs

@@ -15,6 +15,7 @@ test('repo root package.json exposes repo-local hstack scripts', async () => {
 
   // Keep it minimal: assert the stable entrypoints exist and point to the wrapper.
   assert.equal(scripts.dev, 'node ./apps/stack/scripts/repo_local.mjs dev');
+  assert.equal(scripts['dev-targets'], 'node ./apps/stack/scripts/repo_local.mjs dev-targets');
   assert.equal(scripts.stop, 'node ./apps/stack/scripts/repo_local.mjs stop');
   assert.equal(scripts.start, 'node ./apps/stack/scripts/repo_local.mjs start');
   assert.equal(scripts.build, 'node ./apps/stack/scripts/repo_local.mjs build');

package/scripts/run.mjs

@@ -3,31 +3,44 @@ import { parseArgs } from './utils/cli/args.mjs';
 import { pathExists } from './utils/fs/fs.mjs';
 import { killProcessTree, runCapture, spawnProc } from './utils/proc/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir, resolveExplicitStackEnvFilePath } from './utils/paths/paths.mjs';
-import { killPortListeners } from './utils/net/ports.mjs';
-import { getServerComponentName, isHappierServerRunning, waitForServerReady } from './utils/server/server.mjs';
-import { ensureCliBuilt, ensureDepsInstalled, pmExecBin, pmSpawnScript, requireDir } from './utils/proc/pm.mjs';
+import { killPortListeners, observeTcpPortAvailability } from './utils/net/ports.mjs';
+import { fetchHappierHealth, getServerComponentName, isHappierServerRunning, waitForServerReady } from './utils/server/server.mjs';
+import { resolveServerShutdownGraceMs } from './utils/server/shutdown_grace.mjs';
+import { ensureDepsInstalled, pmExecBin, requireDir } from './utils/proc/pm.mjs';
 import { join } from 'node:path';
 import { statSync } from 'node:fs';
 import { setTimeout as delay } from 'node:timers/promises';
 import { maybeResetTailscaleServe } from './tailscale.mjs';
-import { checkDaemonState, getDaemonEnv, isDaemonRunning, startLocalDaemonWithAuth, stopLocalDaemon } from './daemon.mjs';
+import { checkDaemonStatePingAware, daemonStateHasLiveProcess, getDaemonEnv, startLocalDaemonWithAuth, stopLocalDaemon } from './daemon.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/server/validate.mjs';
-import { resolveServerStartScript } from './utils/server/flavor_scripts.mjs';
-import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
-import { applyServerLightEnvDefaults } from './utils/server/apply_server_light_env_defaults.mjs';
+import { applyServerComponentFlavorEnv, resolveServerStartScript } from './utils/server/flavor_scripts.mjs';
+import { ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
+import { applyServerMigrations } from './utils/server/server_migrations.mjs';
+import { applyServerPresetEnvDefaults } from './utils/server/apply_server_preset_env_defaults.mjs';
+import { applyStackServerLoggingDefaults } from './utils/server/logging_env.mjs';
 import {
   getAccountCountForServerComponent,
   prepareDaemonAuthSeedIfNeeded,
   probeExistingAccountCountForServerComponent,
   resolveAutoCopyFromMainEnabled,
 } from './utils/stack/startup.mjs';
-import { readStackRuntimeStateFile, recordStackRuntimeStart, recordStackRuntimeUpdate } from './utils/stack/runtime_state.mjs';
+import {
+  captureStackRuntimeStopSnapshot,
+  finalizeStackRuntimeStop,
+  readStackRuntimeStateFile,
+  recordStackRuntimeServerActivation,
+  recordStackRuntimeServerPids,
+  recordStackRuntimeStart,
+  recordStackRuntimeUpdate,
+} from './utils/stack/runtime_state.mjs';
+import { startStackRuntimeDaemonPidReconciler } from './utils/stack/runtime_daemon_state.mjs';
 import { resolveStackContext } from './utils/stack/context.mjs';
 import { getPublicServerUrlEnvOverride, resolveServerUrls } from './utils/server/urls.mjs';
 import { preferStackLocalhostUrl } from './utils/paths/localhost_host.mjs';
 import { openUrlInBrowser } from './utils/ui/browser.mjs';
 import { ensureDevExpoServer, resolveExpoTailscaleEnabled } from './utils/dev/expo_dev.mjs';
+import { resolveStackOwnedServerListenPid } from './utils/dev/server.mjs';
 import { maybeRunInteractiveStackAuthSetup } from './utils/auth/interactive_stack_auth.mjs';
 import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
 import { daemonStartGate, formatDaemonAuthRequiredError } from './utils/auth/daemon_gate.mjs';
@@ -42,14 +55,27 @@ import { isSandboxed } from './utils/env/sandbox.mjs';
 import { installExitCleanup } from './utils/proc/exit_cleanup.mjs';
 import { expandHome } from './utils/paths/canonical_home.mjs';
 import { validateUiServingConfig } from './utils/server/ui_build_check.mjs';
-import { resolveLocalServerPortForStack } from './utils/server/resolve_stack_server_port.mjs';
+import { observeRuntimePortOwnedByStackDevProxy, selectLocalServerPortCandidateForStack } from './utils/server/resolve_stack_server_port.mjs';
+import {
+  createListenerOwnershipCommandScope,
+  resolveSpawnedProcessGroupListenPid,
+} from './utils/server/listener_ownership.mjs';
 import { findExistingStackCredentialPath } from './utils/auth/credentials_paths.mjs';
 import { createServiceDaemonAutostarter } from './utils/service/daemon_autostart.mjs';
-import { applyRuntimeServerLightSqliteEnv } from './utils/server/apply_runtime_server_light_sqlite_env.mjs';
+import { applyRuntimeServerSqliteEnv } from './utils/server/apply_runtime_server_sqlite_env.mjs';
+import { spawnSourceServerScript } from './utils/server/source_server_workspace_deps.mjs';
+import { applyEffectiveDbProviderEnv } from './utils/server/effective_db_provider.mjs';
 import { resolveStackRuntimeLaunchContext } from './runtime/launch/resolveStackRuntimeLaunchContext.mjs';
-import { resolveCliRuntimeLaunchSpec } from './runtime/launch/resolveCliRuntimeLaunchSpec.mjs';
+import {
+  resolveCliRuntimeLaunchProvenance,
+  resolveCliRuntimeLaunchSpec,
+} from './runtime/launch/resolveCliRuntimeLaunchSpec.mjs';
 import { resolveServerRuntimeLaunchSpec } from './runtime/launch/resolveServerRuntimeLaunchSpec.mjs';
+import { spawnRuntimeServerAfterMigration } from './runtime/launch/runServerRuntimeMigration.mjs';
+import { resolveServerMigrationsEnabled } from '@happier-dev/cli-common/firstPartyRuntime/selfHostServerEnv';
 import { spawnStackOwnerDeathWatchdog } from './utils/stack/owner_death_watchdog.mjs';
+import { completeInterruptedStackStopBeforeStart } from './utils/stack/stop.mjs';
+import { decideDevStartupTopology, observeDevServerStartupTopology } from './utils/dev/devStartupTopology.mjs';
 
 /**
  * Run the local stack in "production-like" mode:
@@ -142,13 +168,40 @@ async function main() {
   if (serverComponentName === 'both') {
     throw new Error(`[local] --server=both is not supported for run (pick one: happier-server-light or happier-server)`);
   }
+  const autostart = getDefaultAutostartPaths();
+  const cleanupEnv = { ...process.env };
+  const cleanupStackCtx = resolveStackContext({ env: cleanupEnv, autostart });
+  if (!json && cleanupStackCtx.stackMode && cleanupStackCtx.runtimeStatePath) {
+    await completeInterruptedStackStopBeforeStart({
+      rootDir,
+      stackName: cleanupStackCtx.stackName,
+      baseDir: autostart.baseDir,
+      env: cleanupEnv,
+      json,
+    });
+  }
   const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv, env: process.env });
   const runtimeSnapshot = runtimeLaunchContext.snapshot;
   const runtimeBackedStart = Boolean(runtimeSnapshot);
   const cliLaunchSpec = runtimeSnapshot ? resolveCliRuntimeLaunchSpec({ snapshot: runtimeSnapshot }) : null;
+  const cliRuntimeProvenance = resolveCliRuntimeLaunchProvenance(cliLaunchSpec);
+  const dbProvider = applyEffectiveDbProviderEnv({ serverComponentName, env: process.env });
   const serverLaunchSpec = runtimeSnapshot
-    ? resolveServerRuntimeLaunchSpec({ serverComponent: serverComponentName, snapshot: runtimeSnapshot })
+    ? resolveServerRuntimeLaunchSpec({
+        serverComponent: serverComponentName,
+        dbProvider,
+        snapshot: runtimeSnapshot,
+        migrationsEnabled: resolveServerMigrationsEnabled(process.env),
+      })
     : null;
+  if (dbProvider === 'mysql' && !String(process.env.DATABASE_URL ?? '').trim()) {
+    throw new Error('[local] mysql requires an explicit DATABASE_URL before startup');
+  }
+  const usesFullManagedInfra = serverComponentName === 'happier-server'
+    && (process.env.HAPPIER_STACK_MANAGED_INFRA ?? '1') !== '0';
+  if (dbProvider === 'postgres' && !usesFullManagedInfra && !String(process.env.DATABASE_URL ?? '').trim()) {
+    throw new Error('[local] postgres requires DATABASE_URL when the selected preset does not manage Postgres');
+  }
 
   const startDaemon = !flags.has('--no-daemon') && (process.env.HAPPIER_STACK_DAEMON ?? '1') !== '0';
   const serveUiWanted = !flags.has('--no-ui') && (process.env.HAPPIER_STACK_SERVE_UI ?? '1') !== '0';
@@ -161,7 +214,6 @@ async function main() {
   const expoTailscale = flags.has('--expo-tailscale') || resolveExpoTailscaleEnabled({ env: process.env });
   const noBrowser = flags.has('--no-browser') || (process.env.HAPPIER_STACK_NO_BROWSER ?? '').toString().trim() === '1';
   const uiPrefix = process.env.HAPPIER_STACK_UI_PREFIX?.trim() ? process.env.HAPPIER_STACK_UI_PREFIX.trim() : '/';
-  const autostart = getDefaultAutostartPaths();
   const uiBuildDir = runtimeSnapshot
     ? join(runtimeSnapshot.launchPath ?? runtimeSnapshot.snapshotPath, 'ui')
     : process.env.HAPPIER_STACK_UI_BUILD_DIR?.trim()
@@ -191,6 +243,7 @@ async function main() {
       data: {
         mode: 'start',
         serverComponentName,
+        dbProvider,
         serverDir,
         uiDir,
         cliDir,
@@ -248,15 +301,36 @@ async function main() {
 
 	  const children = [];
 	  let shuttingDown = false;
+    let shutdown = null;
+    let pendingShutdownSignal = null;
+    let shutdownDispatchStarted = false;
+    const dispatchShutdown = (signal) => {
+      if (shutdownDispatchStarted) return;
+      if (!shutdown) {
+        pendingShutdownSignal = signal;
+        for (const child of children.filter((candidate) => candidate?.exitCode == null)) {
+          void killProcessTree(child, 'SIGINT').catch(() => {});
+        }
+        return;
+      }
+      shutdownDispatchStarted = true;
+      shutdown({ signal }).then(() => process.exit(0)).catch((error) => {
+        console.error('[local] shutdown failed:', error);
+        process.exit(1);
+      });
+    };
+    process.on('SIGINT', () => dispatchShutdown('SIGINT'));
+    process.on('SIGTERM', () => dispatchShutdown('SIGTERM'));
 	  let ownedDaemonPid = null;
 	  let daemonAutostarter = null;
+	  let daemonRuntimeReconciler = null;
 	  installExitCleanup({ label: 'local', children });
 	  const baseEnv = { ...process.env };
 	  const stackCtx = resolveStackContext({ env: baseEnv, autostart });
 	  const { stackMode, runtimeStatePath, stackName, envPath, ephemeral } = stackCtx;
 	  const daemonScopeEnv = applyStackActiveServerScopeEnv({ env: baseEnv, stackName, cliIdentity: 'default' });
-
-  serverPort = await resolveLocalServerPortForStack({
+	  const serviceMode = (daemonScopeEnv.HAPPIER_STACK_SERVICE_MODE ?? '').toString().trim() === '1';
+  serverPort = await selectLocalServerPortCandidateForStack({
     env: baseEnv,
     stackMode,
     stackName,
@@ -271,17 +345,47 @@ async function main() {
   const { publicServerUrl: publicServerUrlPreview } = getPublicServerUrlEnvOverride({ serverPort, env: baseEnv, stackName });
   publicServerUrl = publicServerUrlPreview;
 
-  // Ensure happier-cli is install+build ready before starting the daemon.
-  const buildCli = (baseEnv.HAPPIER_STACK_CLI_BUILD ?? '1').toString().trim() !== '0';
-  if (!runtimeSnapshot) {
-    await ensureCliBuilt(cliDir, { buildCli });
-  }
+  const serverHealthObservation = await fetchHappierHealth(internalServerUrl);
+  const serverAlreadyRunning = serverHealthObservation.ok;
+  const daemonAlreadyRunning = startDaemon
+    ? daemonStateHasLiveProcess(await checkDaemonStatePingAware(cliHomeDir, { serverUrl: internalServerUrl, env: daemonScopeEnv }))
+    : false;
+  const runtimeOwnershipObservationScope = createListenerOwnershipCommandScope();
+  const serverTopologyObservation = await observeDevServerStartupTopology({
+    serverRequested: true, stackMode, serverPort, serverHealthObservation,
+    ownershipArgs: { env: baseEnv, port: serverPort, stackName, runtimeStatePath, listenerObservationScope: runtimeOwnershipObservationScope },
+  }, {
+    observeTcpPortAvailabilityImpl: observeTcpPortAvailability,
+    observeRuntimePortOwnedByStackDevProxyImpl: observeRuntimePortOwnedByStackDevProxy,
+    resolveStackOwnedServerListenPidImpl: () => resolveStackOwnedServerListenPid(
+      { serverPort, stackName, envPath }, { observationScope: runtimeOwnershipObservationScope },
+    ),
+  });
+  const serverTopology = serverTopologyObservation.topology;
+  const existingServerOwnership = serverTopologyObservation.proxyOwned
+    ? { status: 'proxy-owned', pid: null }
+    : serverTopologyObservation.listenerPid
+      ? { status: 'known', pid: serverTopologyObservation.listenerPid }
+      : { status: serverTopology === 'foreign' ? 'foreign' : 'not-running', pid: null };
+  const startupDecision = decideDevStartupTopology({
+    serverRequested: true,
+    serverTopology,
+    daemonRequested: startDaemon,
+    daemonRunning: daemonAlreadyRunning,
+    expoRequested: startMobile,
+    expoRunning: false,
+    restart,
+  });
+
+  // Source-backed daemon launch owns CLI build admission under the daemon lifecycle lock.
+  // Keeping that decision at startLocalDaemonWithAuth lets it preserve an exact manifest-valid
+  // previous dist when the current source build is unavailable instead of failing before admission.
 
   // Ensure server deps exist before any Prisma/docker work.
-  if (!runtimeSnapshot) {
+  if (!runtimeSnapshot && startupDecision.startServer) {
     await ensureDepsInstalled(serverDir, serverComponentName);
   }
-  if (startMobile) {
+  if (startupDecision.startExpo) {
     await ensureDepsInstalled(uiDir, 'happier-ui');
   }
 
@@ -303,11 +407,15 @@ async function main() {
     publicServerUrl = resolvedUrls.publicServerUrl;
   }
 
-  const serverAlreadyRunning = await isHappierServerRunning(internalServerUrl);
-  const daemonAlreadyRunning = startDaemon
-    ? isDaemonRunning(cliHomeDir, { serverUrl: internalServerUrl, env: daemonScopeEnv })
-    : false;
-  if (!restart && serverAlreadyRunning && (!startDaemon || daemonAlreadyRunning)) {
+  if (startupDecision.adoptedServer && stackMode && runtimeStatePath && existingServerOwnership.status === 'known') {
+    await recordStackRuntimeServerPids(runtimeStatePath, {
+      listenerPid: existingServerOwnership.pid,
+      wrapperPid: null,
+      serverPort,
+      clearProxyState: false,
+    });
+  }
+  if (!startupDecision.startServer && !startupDecision.startDaemon && !startupDecision.startExpo) {
     console.log(
       `${green('✓')} start: already running ${dim('(')}` +
         `${dim('server=')}${cyan(internalServerUrl)}` +
@@ -319,14 +427,15 @@ async function main() {
 
   // Stack runtime state (stack-scoped commands only): record the runner PID + chosen ports so stop/restart never kills other stacks.
   if (stackMode && runtimeStatePath) {
-    await recordStackRuntimeStart(runtimeStatePath, {
+    const startedRuntime = await recordStackRuntimeStart(runtimeStatePath, {
       stackName,
       script: 'run.mjs',
       ephemeral,
       ownerPid: process.pid,
       ports: { server: serverPort },
       runtimeSnapshotId: runtimeSnapshot?.snapshotId ?? null,
-    }).catch(() => {});
+      serveUi,
+    });
     spawnStackOwnerDeathWatchdog({
       rootDir,
       stackName,
@@ -334,6 +443,7 @@ async function main() {
       envPath,
       runtimeStatePath,
       ownerPid: process.pid,
+      ownerStartedAt: startedRuntime.startedAt,
       env: baseEnv,
     });
   }
@@ -341,7 +451,7 @@ async function main() {
   // Server
   // If a previous run left a server behind, free the port first (prevents false "ready" checks).
   // NOTE: In stack mode we avoid killing arbitrary port listeners (fail-closed instead).
-  if ((!serverAlreadyRunning || restart) && !stackMode) {
+  if (startupDecision.startServer && !stackMode) {
     await killPortListeners(serverPort, { label: 'server' });
   }
 
@@ -357,15 +467,16 @@ async function main() {
     ...(serveUi ? { HAPPIER_SERVER_UI_REQUIRED: uiRequired ? '1' : '0' } : {}),
     ...resolveServerUiEnv({ serveUi, uiBuildDir, uiPrefix, uiBuildDirExists: Boolean(serveUi && uiBuildDirExists && uiIndexExists) }),
   };
+  applyServerComponentFlavorEnv({ serverComponentName, targetEnv: serverEnv });
+  applyStackServerLoggingDefaults({ baseEnv, serverEnv });
   let serverLightAccountCount = null;
   let happierServerAccountCount = null;
+  applyServerPresetEnvDefaults({ serverComponentName, baseEnv, serverEnv, baseDir: autostart.baseDir });
+  if (runtimeBackedStart && dbProvider === 'sqlite') {
+    applyRuntimeServerSqliteEnv({ env: serverEnv, serverDir });
+  }
   if (serverComponentName === 'happier-server-light') {
-    applyServerLightEnvDefaults({ baseEnv, serverEnv, baseDir: autostart.baseDir });
-    if (runtimeBackedStart) {
-      applyRuntimeServerLightSqliteEnv({ env: serverEnv, serverDir });
-    }
-
-    if (!runtimeBackedStart) {
+    if (!runtimeBackedStart && !startupDecision.adoptedServer) {
       // Source-backed starts ensure the light DB schema exists before daemon startup.
       const acct = await getAccountCountForServerComponent({
         serverComponentName,
@@ -384,9 +495,10 @@ async function main() {
     }
   }
   let effectiveInternalServerUrl = internalServerUrl;
+  let activeServerProcess = null;
   if (serverComponentName === 'happier-server') {
     const managed = (baseEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1') !== '0';
-    if (managed) {
+    if (managed && startupDecision.startServer) {
       const envPath = resolveExplicitStackEnvFilePath(baseEnv);
       const infra = await ensureHappyServerManagedInfra({
         stackName: autostart.stackName,
@@ -394,7 +506,8 @@ async function main() {
         serverPort,
         publicServerUrl,
         envPath,
-        env: baseEnv,
+        env: serverEnv,
+        dbProvider,
       });
 
       // Backend runs on a separate port; gateway owns the public port.
@@ -409,10 +522,13 @@ async function main() {
       if (!runtimeBackedStart) {
         const autoMigrate = (baseEnv.HAPPIER_STACK_PRISMA_MIGRATE ?? '1') !== '0';
         if (autoMigrate) {
-          await applyHappyServerMigrations({ serverDir: sourceServerDir, env: backendEnv });
+          await applyServerMigrations({ serverDir: sourceServerDir, env: backendEnv, dbProvider });
         }
         // Account probe should use the *actual* DATABASE_URL/infra env (ephemeral stacks do not persist it in env files).
-        const acct = await getAccountCountForServerComponent({
+        const accountProbeImpl = startupDecision.adoptedServer
+          ? probeExistingAccountCountForServerComponent
+          : getAccountCountForServerComponent;
+        const acct = await accountProbeImpl({
           serverComponentName,
           serverDir: sourceServerDir,
           env: backendEnv,
@@ -421,16 +537,24 @@ async function main() {
         happierServerAccountCount = typeof acct.accountCount === 'number' ? acct.accountCount : null;
       }
       const backend = runtimeSnapshot
-        ? spawnProc('server', serverLaunchSpec.command, serverLaunchSpec.args, backendEnv, { cwd: serverDir })
-        : await pmSpawnScript({ label: 'server', dir: serverDir, script: 'start', env: backendEnv });
-      children.push(backend);
+        ? await spawnRuntimeServerAfterMigration({
+            serverLaunchSpec,
+            env: backendEnv,
+            children,
+            isCancellationRequested: () => pendingShutdownSignal !== null,
+          })
+        : await spawnSourceServerScript({ label: 'server', serverDir, script: 'start', env: backendEnv });
+      if (!runtimeSnapshot) children.push(backend);
+      activeServerProcess = backend;
+      await waitForServerReady(backendUrl, { childProcess: backend });
       if (stackMode && runtimeStatePath) {
-        await recordStackRuntimeUpdate(runtimeStatePath, {
-          ports: { server: serverPort, backend: backendPort },
-          processes: { happierServerBackendPid: backend.pid },
-        }).catch(() => {});
+        await recordStackRuntimeServerActivation(runtimeStatePath, {
+          stablePort: serverPort,
+          backendPort,
+          managedBackendPid: backend.pid,
+          mode: 'managed-backend',
+        });
       }
-      await waitForServerReady(backendUrl);
 
       const gatewayArgs = [
         join(rootDir, 'scripts', 'ui_gateway.mjs'),
@@ -447,10 +571,16 @@ async function main() {
 
       const gateway = spawnProc('ui', process.execPath, gatewayArgs, { ...backendEnv, PORT: String(serverPort) }, { cwd: rootDir });
       children.push(gateway);
+      await waitForServerReady(internalServerUrl, { childProcess: gateway });
       if (stackMode && runtimeStatePath) {
-        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { uiGatewayPid: gateway.pid } }).catch(() => {});
+        await recordStackRuntimeServerActivation(runtimeStatePath, {
+          stablePort: serverPort,
+          backendPort,
+          managedBackendPid: backend.pid,
+          managedGatewayPid: gateway.pid,
+          mode: 'managed-gateway',
+        });
       }
-      await waitForServerReady(internalServerUrl);
       effectiveInternalServerUrl = internalServerUrl;
 
       // Skip default server spawn below
@@ -459,15 +589,35 @@ async function main() {
 
   // Default server start (happier-server-light, or happier-server without managed infra).
   if (!(serverComponentName === 'happier-server' && (baseEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1') !== '0')) {
-    if (!serverAlreadyRunning || restart) {
+    if (startupDecision.startServer) {
       const server = runtimeSnapshot
-        ? spawnProc('server', serverLaunchSpec.command, serverLaunchSpec.args, serverEnv, { cwd: serverDir })
-        : await pmSpawnScript({ label: 'server', dir: serverDir, script: serverStartScript, env: serverEnv });
-      children.push(server);
+        ? await spawnRuntimeServerAfterMigration({
+            serverLaunchSpec,
+            env: serverEnv,
+            children,
+            isCancellationRequested: () => pendingShutdownSignal !== null,
+          })
+        : await spawnSourceServerScript({ label: 'server', serverDir, script: serverStartScript, env: serverEnv });
+      if (!runtimeSnapshot) children.push(server);
+      activeServerProcess = server;
+      await waitForServerReady(internalServerUrl, { childProcess: server });
       if (stackMode && runtimeStatePath) {
-        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: server.pid } }).catch(() => {});
+        const listenerPid = await resolveSpawnedProcessGroupListenPid({
+          port: serverPort,
+          spawnedPid: server.pid,
+        });
+        if (!(Number.isFinite(Number(listenerPid)) && Number(listenerPid) > 1)) {
+          throw new Error(
+            `[local] server readiness ownership could not be proven on port ${serverPort}: no stack-owned listener PID was discovered`
+          );
+        }
+        await recordStackRuntimeServerPids(runtimeStatePath, {
+          listenerPid: Number(listenerPid),
+          wrapperPid: server.pid,
+          serverPort,
+          clearProxyState: true,
+        });
       }
-      await waitForServerReady(internalServerUrl);
     } else {
       console.log(`${green('✓')} server: already running at ${cyan(internalServerUrl)}`);
     }
@@ -522,14 +672,13 @@ async function main() {
   }
 
   // Daemon
-  if (startDaemon) {
+  if (startupDecision.startDaemon) {
     const gate = daemonStartGate({ env: daemonScopeEnv, cliHomeDir, serverUrl: effectiveInternalServerUrl });
     if (!gate.ok) {
       const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
       // In orchestrated auth flows, keep server/UI up and let the orchestrator start daemon post-auth.
       if (gate.reason === 'auth_flow_missing_credentials') {
         console.log('[local] auth flow: skipping daemon start until credentials exist');
-        const serviceMode = (daemonScopeEnv.HAPPIER_STACK_SERVICE_MODE ?? '').toString().trim() === '1';
         if (serviceMode) {
           const pollMs = daemonScopeEnv.HAPPIER_STACK_SERVICE_DAEMON_AUTOSTART_POLL_MS ?? '';
           const maxAttemptsPerCredentials =
@@ -566,10 +715,11 @@ async function main() {
               publicServerUrl,
               runtimeStatePath,
               isShuttingDown: () => shuttingDown,
-              forceRestart: restart,
+              forceRestart: restart && !serviceMode,
               env: daemonScopeEnv,
               stackName,
               cliIdentity: 'default',
+              ...cliRuntimeProvenance,
             });
             const daemonEnvForState = getDaemonEnv({
               baseEnv: daemonScopeEnv,
@@ -579,7 +729,7 @@ async function main() {
               stackName,
               cliIdentity: 'default',
             });
-            const daemonState = checkDaemonState(cliHomeDir, { serverUrl: effectiveInternalServerUrl, env: daemonEnvForState });
+            const daemonState = await checkDaemonStatePingAware(cliHomeDir, { serverUrl: effectiveInternalServerUrl, env: daemonEnvForState });
             ownedDaemonPid = typeof daemonState?.pid === 'number' ? daemonState.pid : null;
           };
 
@@ -592,7 +742,9 @@ async function main() {
             retryBaseMs,
             retryMaxMs,
             getCredentialFingerprint,
-            isDaemonRunning: () => isDaemonRunning(cliHomeDir, { serverUrl: effectiveInternalServerUrl, env: daemonScopeEnv }),
+            isDaemonRunning: async () => daemonStateHasLiveProcess(
+              await checkDaemonStatePingAware(cliHomeDir, { serverUrl: effectiveInternalServerUrl, env: daemonScopeEnv }),
+            ),
             startDaemon: startDaemonAndRecord,
             logger: console,
           });
@@ -610,7 +762,10 @@ async function main() {
     } else {
       const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
       if (!runtimeBackedStart && serverComponentName === 'happier-server' && happierServerAccountCount == null) {
-        const acct = await getAccountCountForServerComponent({
+        const accountProbeImpl = startupDecision.adoptedServer
+          ? probeExistingAccountCountForServerComponent
+          : getAccountCountForServerComponent;
+        const acct = await accountProbeImpl({
           serverComponentName,
           serverDir: sourceServerDir,
           env: serverEnv,
@@ -651,9 +806,10 @@ async function main() {
 		      publicServerUrl,
 		      runtimeStatePath,
 		      isShuttingDown: () => shuttingDown,
-		      forceRestart: restart,
+		      forceRestart: restart && !serviceMode,
 		        env: daemonScopeEnv,
 	        stackName,
+	        ...cliRuntimeProvenance,
 	    });
 	      const daemonEnvForState = getDaemonEnv({
 	        baseEnv: daemonScopeEnv,
@@ -663,13 +819,37 @@ async function main() {
 	        stackName,
 	        cliIdentity: 'default',
 	      });
-	      const daemonState = checkDaemonState(cliHomeDir, { serverUrl: effectiveInternalServerUrl, env: daemonEnvForState });
+	      const daemonState = await checkDaemonStatePingAware(cliHomeDir, { serverUrl: effectiveInternalServerUrl, env: daemonEnvForState });
 	      ownedDaemonPid = typeof daemonState?.pid === 'number' ? daemonState.pid : null;
 	    }
 	  }
 
+  if (startDaemon && stackMode && runtimeStatePath) {
+    const daemonRuntimeEnv = getDaemonEnv({
+      baseEnv: daemonScopeEnv,
+      cliHomeDir,
+      internalServerUrl: effectiveInternalServerUrl,
+      publicServerUrl: publicServerUrl || effectiveInternalServerUrl,
+      stackName,
+      cliIdentity: 'default',
+    });
+    daemonRuntimeReconciler = startStackRuntimeDaemonPidReconciler(
+      {
+        runtimeStatePath,
+        cliHomeDir,
+        internalServerUrl: effectiveInternalServerUrl,
+        env: daemonRuntimeEnv,
+        isShuttingDown: () => shuttingDown,
+      },
+      {
+        checkDaemonStateImpl: checkDaemonStatePingAware,
+      },
+    );
+    await daemonRuntimeReconciler?.syncNow?.();
+  }
+
   // Optional: start Expo dev-client Metro for mobile reviewers.
-  if (startMobile) {
+  if (startupDecision.startExpo) {
     const expoRes = await ensureDevExpoServer({
       startUi: false,
       startMobile: true,
@@ -690,25 +870,29 @@ async function main() {
     }
   }
 
-  const shutdown = async ({ signal = 'SIGTERM' } = {}) => {
+  shutdown = async ({ signal = 'SIGTERM' } = {}) => {
     if (shuttingDown) {
       return;
     }
     shuttingDown = true;
     let shutdownRequest = null;
+    let expectedStopState = null;
     if (runtimeStatePath) {
       shutdownRequest = (await readStackRuntimeStateFile(runtimeStatePath).catch(() => null))?.stopRequest ?? null;
+      expectedStopState = await captureStackRuntimeStopSnapshot(runtimeStatePath).catch(() => null);
     }
     console.log(`\n[local] shutting down (${signal})...`);
     if (shutdownRequest) {
       const requestedBy = String(shutdownRequest.requestedBy ?? '').trim();
       const reason = String(shutdownRequest.reason ?? '').trim();
+      const preserveDaemon = shutdownRequest.preserveDaemon === true;
       const requestedAt = String(shutdownRequest.requestedAt ?? '').trim();
       console.log(
         `[local] shutdown request: ` +
           [
             requestedBy ? `requestedBy=${requestedBy}` : null,
             reason ? `reason=${reason}` : null,
+            preserveDaemon ? 'preserveDaemon=true' : null,
             requestedAt ? `requestedAt=${requestedAt}` : null,
           ]
             .filter(Boolean)
@@ -721,8 +905,15 @@ async function main() {
     } catch {
       // ignore
     }
+    try {
+      daemonRuntimeReconciler?.close?.();
+    } catch {
+      // ignore
+    }
 
-	    if (startDaemon) {
+    const preserveDaemonOnShutdown = shutdownRequest?.preserveDaemon === true;
+
+	    if (startDaemon && !preserveDaemonOnShutdown) {
 	      if (ownedDaemonPid && Number.isFinite(ownedDaemonPid) && ownedDaemonPid > 0) {
 		        await stopLocalDaemon({
 		          cliBin,
@@ -753,30 +944,40 @@ async function main() {
 	      }
 	    }
 
-    for (const child of children) {
-      if (child.exitCode == null) {
-        killProcessTree(child, 'SIGINT');
-      }
-    }
+    const serverShutdownGraceMs = resolveServerShutdownGraceMs(baseEnv);
+    const cleanupResults = await Promise.all(children
+      .filter((child) => child.exitCode == null)
+      .map((child) => killProcessTree(child, 'SIGINT',
+        child === activeServerProcess ? { graceMs: serverShutdownGraceMs } : undefined)));
 
     await delay(1500);
-    for (const child of children) {
-      if (child.exitCode == null) {
-        killProcessTree(child, 'SIGKILL');
-      }
-    }
+    cleanupResults.push(...await Promise.all(children
+      .filter((child) => child.exitCode == null)
+      .map((child) => killProcessTree(child, 'SIGKILL'))));
 
     await maybeResetTailscaleServe();
+    if (runtimeStatePath && expectedStopState) {
+      await finalizeStackRuntimeStop(runtimeStatePath, {
+        expected: expectedStopState,
+        preserveDaemon: preserveDaemonOnShutdown,
+        cleanupResults,
+        requireNoStopRequest: true,
+      }).catch(() => {});
+    }
   };
 
-  process.on('SIGINT', () => shutdown({ signal: 'SIGINT' }).then(() => process.exit(0)));
-  process.on('SIGTERM', () => shutdown({ signal: 'SIGTERM' }).then(() => process.exit(0)));
+  if (pendingShutdownSignal) dispatchShutdown(pendingShutdownSignal);
 
   // Keep running
   await new Promise(() => {});
 }
 
-main().catch((err) => {
+main().catch(async (err) => {
   console.error('[local] failed:', err);
+  if (err?.code === 'ESERVERRUNTIMEPROJECTION' && err?.serverActivationCommitted === true) {
+    process.exitCode = 1;
+    await new Promise(() => {});
+    return;
+  }
   process.exit(1);
 });