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

package/scripts/dev.mjs

@@ -3,28 +3,61 @@ import { parseArgs } from './utils/cli/args.mjs';
 import { killProcessTree } from './utils/proc/proc.mjs';
 import { spawnProc } from './utils/proc/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
-import { killPortListeners } from './utils/net/ports.mjs';
-import { getServerComponentName, isHappierServerRunning } from './utils/server/server.mjs';
+import { killPortListeners, observeTcpPortAvailability } from './utils/net/ports.mjs';
+import { fetchHappierHealth, getServerComponentName } from './utils/server/server.mjs';
+import { resolveServerShutdownGraceMs } from './utils/server/shutdown_grace.mjs';
 import { requireDir } from './utils/proc/pm.mjs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { isDaemonRunning, stopLocalDaemon } from './daemon.mjs';
+import { checkDaemonStatePingAware, getDaemonEnv, stopLocalDaemon } from './daemon.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/server/validate.mjs';
 import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
-import { isPidAlive, readStackRuntimeStateFile, recordStackRuntimeStart } from './utils/stack/runtime_state.mjs';
+import { selectExpoDevMetroPort } from './utils/expo/metro_ports.mjs';
+import {
+  captureStackRuntimeStopSnapshot,
+  createStackServerRuntimeProcessPatch,
+  finalizeStackRuntimeStop,
+  readStackRuntimeStateFile,
+  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 { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
-import { ensureDevCliReady, prepareDaemonAuthSeed, startDevDaemon, watchHappyCliAndRestartDaemon } from './utils/dev/daemon.mjs';
-import { startDevServer, watchDevServerAndRestart } from './utils/dev/server.mjs';
+import {
+  prepareDaemonAuthSeed,
+  startDevDaemon,
+} from './utils/dev/daemon.mjs';
+import { startDevDaemonLifecycleReconciler } from './utils/dev/daemonLifecycleReconciler.mjs';
+import {
+  resolveStackOwnedServerListenPid,
+  resolveStackOwnedServerRuntimePid,
+  startDevServer,
+} from './utils/dev/server.mjs';
+import {
+  decideDevStartupTopology,
+  observeDevServerStartupTopology,
+  shouldExitAdoptedDevRuntime,
+} from './utils/dev/devStartupTopology.mjs';
+import { resolveDevReloadPollIntervalMs } from './utils/dev/devReloadCoordinator.mjs';
+import { startDevReloadComposition } from './utils/dev/devReloadComposition.mjs';
+import { prepareDevProxyStartup, resolveDevProxyStableHost, shouldEnableStackDevProxy } from './utils/dev/devProxy.mjs';
+import { createDevProxyUnexpectedExitHandler } from './utils/dev/devProxyLifecycle.mjs';
 import { resolveDevServerConnection } from './utils/dev/resolveDevServerConnection.mjs';
-import { resolveLocalServerPortForStack } from './utils/server/resolve_stack_server_port.mjs';
-import { ensureDevExpoServer, resolveExpoTailscaleEnabled } from './utils/dev/expo_dev.mjs';
+import { observeRuntimePortOwnedByStackDevProxy, selectLocalServerPortCandidateForStack } from './utils/server/resolve_stack_server_port.mjs';
+import { createListenerOwnershipCommandScope } from './utils/server/listener_ownership.mjs';
+import {
+  ensureDevExpoServer,
+  resolveExpoDevHost,
+  resolveExpoTailscaleEnabled,
+} from './utils/dev/expo_dev.mjs';
 import { preferStackLocalhostUrl } from './utils/paths/localhost_host.mjs';
 import { openUrlInBrowser } from './utils/ui/browser.mjs';
 import { waitForHttpOk } from './utils/server/server.mjs';
 import { sanitizeDnsLabel } from './utils/net/dns.mjs';
-import { getAccountCountForServerComponent, resolveAutoCopyFromMainEnabled } from './utils/stack/startup.mjs';
+import { getAccountCountForServerComponent, probeExistingAccountCountForServerComponent, resolveAutoCopyFromMainEnabled } from './utils/stack/startup.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';
@@ -38,8 +71,28 @@ import { installExitCleanup } from './utils/proc/exit_cleanup.mjs';
 import { expandHome } from './utils/paths/canonical_home.mjs';
 import { buildConfigureServerLinks } from '@happier-dev/cli-common/links';
 import { spawnStackOwnerDeathWatchdog } from './utils/stack/owner_death_watchdog.mjs';
+import { completeInterruptedStackStopBeforeStart } from './utils/stack/stop.mjs';
 import { resolveTauriPaneInvocation } from './utils/tui/tauri_mode.mjs';
 import { resolveReactNativeDevtoolsUrl } from './utils/dev/react_native_devtools.mjs';
+import {
+  loadDevTargetsConfig,
+  resolveDevTargetExecutionPolicy,
+} from './utils/dev_targets/config.mjs';
+import { runDevTargetsDoctor } from './utils/dev_targets/doctor.mjs';
+import {
+  resolveDevTargetServicePlans,
+  resolveServicePlansAfterTargetPreflight,
+} from './utils/dev_targets/service_placement.mjs';
+import { resolveRemoteServerRuntimeConfig } from './utils/dev_targets/remote_commands.mjs';
+import {
+  startStackDevTargets,
+  startStackDevTargetsInBackground,
+} from './utils/dev_targets/supervisor.mjs';
+import { findExistingStackCredentialPath } from './utils/auth/credentials_paths.mjs';
+import {
+  hasExplicitMobileReachableHost,
+  resolveMobileReachableServerUrl,
+} from './utils/server/mobile_api_url.mjs';
 
  /**
   * Dev mode stack:
@@ -66,10 +119,12 @@ async function main() {
               '--no-server',
 		          '--no-ui',
 		          '--no-daemon',
+          '--no-dev-targets',
           '--restart',
           '--watch',
           '--no-watch',
           '--no-browser',
+          '--no-proxy',
           '--mobile',
           '--rn-devtools',
           '--react-native-devtools',
@@ -87,6 +142,8 @@ async function main() {
 		        '  hstack dev --watch         # rebuild/restart happier-cli daemon on file changes (TTY default)',
 	        '  hstack dev --no-watch      # disable watch mode (always disabled in non-interactive mode)',
 	        '  hstack dev --no-browser    # do not open the UI in your browser automatically',
+          '  hstack dev --no-dev-targets # skip configured Mutagen-backed remote daemons for this run',
+	        '  hstack dev --no-proxy      # bind the dev server directly instead of using the stable-port proxy',
 	        '  hstack dev --mobile        # also start Expo dev-client Metro for mobile',
 	        '  hstack dev --rn-devtools   # open React Native DevTools (Metro debugger UI) in your browser',
 	        '  hstack dev --tauri         # start the desktop Tauri shell against this stack',
@@ -147,11 +204,12 @@ async function main() {
 
   const startTauri = flags.has('--tauri') || flags.has('--with-tauri');
   const startUi = !flags.has('--no-ui');
-  const startDaemon = !flags.has('--no-daemon');
-  const startMobile = flags.has('--mobile') || flags.has('--with-mobile');
+  const requestedStartDaemon = !flags.has('--no-daemon');
   const openReactNativeDevtools = flags.has('--rn-devtools') || flags.has('--react-native-devtools');
   const noBrowser = startTauri || flags.has('--no-browser') || (process.env.HAPPIER_STACK_NO_BROWSER ?? '').toString().trim() === '1';
   const expoTailscale = flags.has('--expo-tailscale') || resolveExpoTailscaleEnabled({ env: process.env });
+  const startMobile = flags.has('--mobile') || flags.has('--with-mobile') || expoTailscale;
+  const requestedStartExpo = startUi || startMobile;
 
   if (startTauri && !startUi) {
     throw new Error('[local] --tauri requires the ui');
@@ -164,10 +222,15 @@ async function main() {
 	  const cliBin = join(cliDir, 'bin', 'happier.mjs');
   const autostart = getDefaultAutostartPaths();
   const baseEnv = { ...process.env };
+  const parentServerRestartPreflightAlreadyDone = String(
+    baseEnv.HAPPIER_STACK_SERVER_RESTART_PREFLIGHT_ALREADY_DONE ?? '',
+  ).trim() === '1';
+  delete baseEnv.HAPPIER_STACK_SERVER_RESTART_PREFLIGHT_ALREADY_DONE;
   const stackCtx = resolveStackContext({ env: baseEnv, autostart });
   const { stackMode, runtimeStatePath, stackName, envPath, ephemeral } = stackCtx;
-
-  const serverPort = await resolveLocalServerPortForStack({
+  const devTargetsEnabled = !flags.has('--no-dev-targets');
+  const loadedDevTargets = await loadDevTargetsConfig({ stackName, env: baseEnv, allowMissing: true });
+  const serverPort = await selectLocalServerPortCandidateForStack({
     env: baseEnv,
     stackMode,
     stackName,
@@ -189,11 +252,11 @@ async function main() {
     env: baseEnv,
     resolvedLocalUrls: resolvedUrls,
   });
-  const startServer = serverConnection.startServer;
+  const requestedStartServer = serverConnection.startServer;
   const localInternalServerUrl = resolvedUrls.internalServerUrl;
   const internalServerUrl = serverConnection.internalServerUrl;
   let publicServerUrl = serverConnection.publicServerUrl;
-  if (startServer && stackMode && stackName !== 'main' && !resolvedUrls.envPublicUrl) {
+  if (requestedStartServer && !serverConnection.hasExplicitPublicServerUrl && stackMode && stackName !== 'main' && !resolvedUrls.envPublicUrl) {
     const src = String(resolvedUrls.publicServerUrlSource ?? '');
     const hasStackScopedTailscale = src.startsWith('tailscale-');
     if (!hasStackScopedTailscale) {
@@ -202,13 +265,68 @@ async function main() {
   }
   // Expo app config: this is what both web + native app use to reach the Happy server.
   // LAN rewrite (for dev-client) is centralized in ensureDevExpoServer.
-  const uiApiUrl = startServer ? resolvedUrls.defaultPublicUrl : serverConnection.uiApiUrl;
+  const uiApiUrl = requestedStartServer ? resolvedUrls.defaultPublicUrl : serverConnection.uiApiUrl;
   const serverConnectionSource = serverConnection.source;
   const restart = flags.has('--restart');
   const cliHomeDir = process.env.HAPPIER_STACK_CLI_HOME_DIR?.trim()
     ? expandHome(process.env.HAPPIER_STACK_CLI_HOME_DIR.trim())
     : join(autostart.baseDir, 'cli');
 
+  const executionPolicy = resolveDevTargetExecutionPolicy(loadedDevTargets.config, {
+    targetsEnabled: devTargetsEnabled,
+    serverRequested: requestedStartServer,
+  });
+  const devTargets = devTargetsEnabled ? loadedDevTargets.config.targets : [];
+  const configuredServicePlans = resolveDevTargetServicePlans({
+    targets: devTargets,
+    policy: executionPolicy,
+    requested: {
+      server: requestedStartServer,
+      expo: requestedStartExpo,
+      daemon: requestedStartDaemon,
+    },
+  });
+  if (
+    configuredServicePlans.targets.some((plan) => Object.values(plan.services).some(Boolean))
+    && !requestedStartServer
+  ) {
+    throw new Error(
+      '[dev-targets] remote runtime placement cannot consume an external --server-url; '
+        + 'set runtime placement to local or use --no-dev-targets for this run',
+    );
+  }
+  const remoteServerRuntimeConfig = configuredServicePlans.targets.some((plan) => plan.services.server)
+    ? resolveRemoteServerRuntimeConfig({ serverComponentName, env: baseEnv })
+    : null;
+  let servicePlans = configuredServicePlans;
+  const exclusiveTargetPlans = configuredServicePlans.targets.filter((plan) => (
+    Object.entries(plan.services).some(([service, enabled]) => enabled && !configuredServicePlans.local[service])
+  ));
+  if (!json && exclusiveTargetPlans.length > 0) {
+    const diagnosis = await runDevTargetsDoctor({
+      targets: exclusiveTargetPlans.map((plan) => plan.target),
+      env: baseEnv,
+    });
+    const reachableTargets = new Set(
+      diagnosis.targets.filter((target) => target.ok).map((target) => target.name),
+    );
+    servicePlans = resolveServicePlansAfterTargetPreflight({
+      configured: configuredServicePlans,
+      mutagenAvailable: diagnosis.mutagen.ok,
+      reachableTargets,
+    });
+  }
+  const remoteServerPlan = servicePlans.targets.find((plan) => plan.services.server) ?? null;
+  if (!json && remoteServerPlan && (await fetchHappierHealth(localInternalServerUrl)).ok) {
+    throw new Error(
+      `[dev-targets] the local stable server listener at ${localInternalServerUrl} is still active; `
+        + 'stop the current Stack before starting its authoritative remote server',
+    );
+  }
+  const startServer = servicePlans.local.server;
+  const startDaemon = servicePlans.local.daemon;
+  const startExpo = servicePlans.local.expo;
+
   if (json) {
     printResult({
       json,
@@ -227,6 +345,9 @@ async function main() {
         startMobile,
         startTauri,
         startDaemon,
+        devTargets,
+        executionPolicy,
+        servicePlans,
         openReactNativeDevtools,
         cliHomeDir,
       },
@@ -234,6 +355,16 @@ async function main() {
     return;
   }
 
+  if (stackMode && runtimeStatePath) {
+    await completeInterruptedStackStopBeforeStart({
+      rootDir,
+      stackName,
+      baseDir: autostart.baseDir,
+      env: baseEnv,
+      json,
+    });
+  }
+
   if (startServer) {
     assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir });
     assertServerPrismaProviderMatches({ serverComponentName, serverDir });
@@ -243,28 +374,63 @@ async function main() {
   await requireDir('happier-cli', cliDir);
 
   const children = [];
+  let devTargetsController = null;
   let shuttingDown = false;
+  let shutdown = null;
+  let pendingShutdownSignal = null;
+  let shutdownDispatchStarted = false;
+  const dispatchShutdown = (signal) => {
+    if (shutdownDispatchStarted) return;
+    if (!shutdown) {
+      pendingShutdownSignal = signal;
+      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'));
   installExitCleanup({ label: 'local', children });
 
-  // Ensure happier-cli is install+build ready before starting the daemon.
-  // Worktrees often don't have dist/ built yet, which causes MODULE_NOT_FOUND on dist/index.mjs.
   const buildCli = (baseEnv.HAPPIER_STACK_CLI_BUILD ?? '1').toString().trim() !== '0';
-  await ensureDevCliReady({ cliDir, buildCli });
 
   // Watch mode (interactive only by default): rebuild happier-cli and restart daemon when code changes.
   const watchEnabled =
     flags.has('--watch') || (!flags.has('--no-watch') && Boolean(process.stdin.isTTY && process.stdout.isTTY));
   const watchers = [];
 
-  const serverAlreadyRunning = startServer
-    ? await isHappierServerRunning(localInternalServerUrl)
-    : false;
+  const serverHealthObservation = startServer
+    ? await fetchHappierHealth(localInternalServerUrl)
+    : null;
+  const serverAlreadyRunning = serverHealthObservation?.ok === true;
+  let serverRuntimeProxyAlreadyOwned = false;
+  let serverTopology = 'absent';
+  if (startServer) {
+    const topologyScope = createListenerOwnershipCommandScope();
+    const serverTopologyObservation = await observeDevServerStartupTopology({
+      serverRequested: true, stackMode, serverPort, serverHealthObservation,
+      ownershipArgs: { env: baseEnv, port: serverPort, stackName, runtimeStatePath, listenerObservationScope: topologyScope },
+    }, {
+      observeTcpPortAvailabilityImpl: observeTcpPortAvailability,
+      observeRuntimePortOwnedByStackDevProxyImpl: observeRuntimePortOwnedByStackDevProxy,
+      resolveStackOwnedServerListenPidImpl: () => resolveStackOwnedServerListenPid(
+        { serverPort, stackName, envPath }, { observationScope: topologyScope },
+      ),
+    });
+    serverTopology = serverTopologyObservation.topology;
+    serverRuntimeProxyAlreadyOwned = serverTopologyObservation.proxyOwned;
+  }
   const daemonAlreadyRunning = startDaemon
-    ? isDaemonRunning(cliHomeDir, { serverUrl: internalServerUrl, env: baseEnv })
+    ? ['running', 'starting'].includes((await checkDaemonStatePingAware(cliHomeDir, {
+        serverUrl: internalServerUrl,
+        env: baseEnv,
+        stackName,
+      })).status)
     : false;
-
   // Expo dev server state (worktree-scoped): single Expo process per stack/worktree.
-  const startExpo = startUi || startMobile;
   const expoPaths = getExpoStatePaths({
     baseDir: autostart.baseDir,
     kind: 'expo-dev',
@@ -273,8 +439,27 @@ async function main() {
   });
   const expoRunning = startExpo ? await isStateProcessRunning(expoPaths.statePath) : { running: false, state: null };
   let expoAlreadyRunning = Boolean(expoRunning.running);
+  const startupDecision = decideDevStartupTopology({
+    serverRequested: startServer,
+    serverTopology,
+    daemonRequested: startDaemon,
+    daemonRunning: daemonAlreadyRunning,
+    expoRequested: startExpo,
+    expoRunning: expoAlreadyRunning,
+    restart,
+  });
 
-  if (!restart && (!startServer || serverAlreadyRunning) && (!startDaemon || daemonAlreadyRunning) && (!startExpo || expoAlreadyRunning)) {
+  if (shouldExitAdoptedDevRuntime({
+    devTargetCount: servicePlans.targets.length,
+    restart,
+    watchEnabled,
+    serverRequested: startServer,
+    adoptedServer: startupDecision.adoptedServer,
+    daemonRequested: startDaemon,
+    daemonRunning: daemonAlreadyRunning,
+    expoRequested: startExpo,
+    expoRunning: expoAlreadyRunning,
+  })) {
     console.log(
       `${green('✓')} dev: already running ${dim('(')}` +
         `${dim('server=')}${cyan(internalServerUrl)}${startServer ? '' : dim(' (external)')}` +
@@ -286,14 +471,33 @@ async function main() {
     return;
   }
 
+  const remoteExpoPlan = servicePlans.targets.find((plan) => plan.services.expo) ?? null;
+  const configuredRemoteExpoPort = Number(baseEnv.HAPPIER_STACK_EXPO_DEV_PORT);
+  const initialRemoteExpoProjection = remoteExpoPlan
+    && Number.isInteger(configuredRemoteExpoPort)
+    && configuredRemoteExpoPort > 0
+    ? {
+        port: configuredRemoteExpoPort,
+        webPort: startUi ? configuredRemoteExpoPort : null,
+        mobilePort: startMobile ? configuredRemoteExpoPort : null,
+        webEnabled: startUi,
+        devClientEnabled: startMobile,
+        host: resolveExpoDevHost({ env: baseEnv }),
+        remoteTarget: remoteExpoPlan.target.name,
+      }
+    : null;
+
   if (stackMode && runtimeStatePath) {
-    await recordStackRuntimeStart(runtimeStatePath, {
+    const startedRuntime = await recordStackRuntimeStart(runtimeStatePath, {
       stackName,
       script: 'dev.mjs',
       ephemeral,
       ownerPid: process.pid,
-      ports: startServer ? { server: serverPort } : {},
-    }).catch(() => {});
+      ports: requestedStartServer ? { server: serverPort } : {},
+      ...(initialRemoteExpoProjection ? { expo: initialRemoteExpoProjection } : {}),
+      runtimeSnapshotId: null,
+      serveUi: null,
+    });
     spawnStackOwnerDeathWatchdog({
       rootDir,
       stackName,
@@ -301,24 +505,139 @@ async function main() {
       envPath,
       runtimeStatePath,
       ownerPid: process.pid,
+      ownerStartedAt: startedRuntime.startedAt,
       env: baseEnv,
     });
   }
 
+  const remoteExpoPort = remoteExpoPlan
+    ? initialRemoteExpoProjection?.port ?? (await selectExpoDevMetroPort({
+        env: baseEnv,
+        stackMode,
+        stackName,
+        host: resolveExpoDevHost({ env: baseEnv }) === 'lan' ? '0.0.0.0' : '127.0.0.1',
+      })).port
+    : null;
+  const remotePublicServerUrl = startMobile
+    ? resolveMobileReachableServerUrl({
+        env: baseEnv,
+        serverUrl: publicServerUrl,
+        serverPort,
+      })
+    : remoteServerPlan ? publicServerUrl : uiApiUrl;
+  const expoPublicUrl = remoteExpoPort
+    ? resolveMobileReachableServerUrl({
+        env: baseEnv,
+        serverUrl: `http://localhost:${remoteExpoPort}`,
+        serverPort: remoteExpoPort,
+      })
+    : '';
+  const resolveMobilePublicUrlsOnTarget =
+    startMobile
+    && !serverConnection.hasExplicitPublicServerUrl
+    && !resolvedUrls.envPublicUrl
+    && !hasExplicitMobileReachableHost({ env: baseEnv });
+
+  const buildDevTargetsStartOptions = () => {
+    if (servicePlans.targets.length === 0) return null;
+    const credentialPath = servicePlans.targets.some((plan) => plan.services.daemon)
+      ? findExistingStackCredentialPath({
+          cliHomeDir,
+          serverUrl: internalServerUrl,
+          env: baseEnv,
+        })
+      : null;
+    return {
+      stackName,
+      stackBaseDir: loadedDevTargets.path ? dirname(loadedDevTargets.path) : autostart.baseDir,
+      sourceDir: resolve(cliDir, '..', '..'),
+      localServerPort: serverPort,
+      localExpoPort: remoteExpoPort,
+      publicServerUrl: remotePublicServerUrl,
+      expoPublicUrl,
+      resolveMobilePublicUrlsOnTarget,
+      expoListenHost: resolveExpoDevHost({ env: baseEnv }) === 'lan' ? '0.0.0.0' : '127.0.0.1',
+      startMobile,
+      activeServerId: resolveStackActiveServerId({ env: baseEnv, stackName }),
+      credentialPath,
+      remoteServerRuntimeConfig,
+      syncTargets: devTargets,
+      targetPlans: servicePlans.targets,
+      onTargetStateChange: async ({ name, ...state }) => {
+        if (!stackMode || !runtimeStatePath) return;
+        const ownsServer = state.services?.server === true;
+        await recordStackRuntimeUpdate(runtimeStatePath, {
+          remoteTargets: { [name]: state },
+          ...(ownsServer && state.status === 'running'
+            ? {
+                placement: {
+                  server: name,
+                  daemon: startDaemon ? 'local' : name,
+                  expo: startExpo ? 'local' : remoteExpoPlan?.target.name ?? 'disabled',
+                },
+                ...createStackServerRuntimeProcessPatch({
+                  listenerPid: null,
+                  wrapperPid: null,
+                  serverPort,
+                  clearProxyState: true,
+                }),
+              }
+            : {}),
+        }).catch(() => {});
+      },
+      env: baseEnv,
+    };
+  };
+
   // Start server (only if not already healthy)
   // NOTE: In stack mode we avoid killing arbitrary port listeners (fail-closed instead).
   if (startServer && (!serverAlreadyRunning || restart) && !stackMode) {
     await killPortListeners(serverPort, { label: 'server' });
   }
 
-  const { serverEnv, serverScript, serverProc } = startServer
+  const devProxyEnabled = shouldEnableStackDevProxy({ startServer, flags, env: baseEnv });
+  let proxyPlan = {
+    mode: 'direct',
+    stablePort: serverPort,
+    backendPort: serverPort,
+    proxyController: null,
+    fallbackReason: null,
+  };
+  if (startServer && devProxyEnabled && startupDecision.startServer) {
+    const stableHost = resolveDevProxyStableHost({ env: baseEnv });
+    const onUnexpectedExit = createDevProxyUnexpectedExitHandler({
+      stackMode,
+      runtimeStatePath,
+      requestShutdownImpl: () => {
+        process.exitCode = 1;
+        process.kill(process.pid, 'SIGTERM');
+      },
+      logger: console,
+    });
+    proxyPlan = await prepareDevProxyStartup({
+      enabled: true,
+      stablePort: serverPort,
+      stableHost,
+      targetHost: '127.0.0.1',
+      label: `${stackName ?? 'stack'}-server-proxy`,
+      logger: console,
+      onUnexpectedExit,
+    });
+  }
+  const serverBindPort = proxyPlan.backendPort;
+  const serverBackendInternalUrl = `http://127.0.0.1:${serverBindPort}`;
+
+  const { serverEnv, serverScript, serverProc } = startServer && startupDecision.startServer
     ? await startDevServer({
         serverComponentName,
         serverDir,
         autostart,
-        baseEnv,
+        baseEnv: parentServerRestartPreflightAlreadyDone
+          ? { ...baseEnv, HAPPIER_STACK_SERVER_RESTART_PREFLIGHT_ALREADY_DONE: '1' }
+          : baseEnv,
         serverPort,
-        internalServerUrl: localInternalServerUrl,
+        serverBindPort,
+        internalServerUrl: serverBackendInternalUrl,
         publicServerUrl,
         envPath,
         stackMode,
@@ -326,12 +645,27 @@ async function main() {
         serverAlreadyRunning,
         restart,
         children,
+        serverProxyRuntime: proxyPlan.mode === 'proxy'
+          ? {
+              enabled: true,
+              proxyPid: proxyPlan.proxyController?.pid,
+              mode: 'proxy',
+            }
+          : proxyPlan.mode === 'directFallback'
+            ? {
+                enabled: true,
+                proxyPid: null,
+                mode: 'directFallback',
+                fallbackReason: proxyPlan.fallbackReason,
+              }
+            : null,
       })
     : { serverEnv: baseEnv, serverScript: null, serverProc: null };
-
-  if (!startServer) {
+  if (remoteServerPlan) {
+    console.log(`${green('✓')} server: remote startup through ${cyan(internalServerUrl)}`);
+  } else if (!startServer) {
     console.log(`${green('✓')} server: external ${cyan(internalServerUrl)}`);
-  } else if (!serverAlreadyRunning || restart) {
+  } else if (startupDecision.startServer) {
     console.log(`${green('✓')} server: ready at ${cyan(internalServerUrl)}`);
   } else {
     console.log(`${green('✓')} server: already running at ${cyan(internalServerUrl)}`);
@@ -346,12 +680,44 @@ async function main() {
     }).join('\n'),
   );
 
+  if (remoteServerPlan) {
+    const devTargetsStartOptions = buildDevTargetsStartOptions();
+    if (stackMode && runtimeStatePath) {
+      await recordStackRuntimeUpdate(runtimeStatePath, {
+        placement: {
+          server: remoteServerPlan.target.name,
+          daemon: startDaemon ? 'local' : remoteServerPlan.target.name,
+          expo: startExpo ? 'local' : remoteExpoPlan?.target.name ?? 'disabled',
+        },
+        remoteTargets: Object.fromEntries(servicePlans.targets.map((plan) => [
+          plan.target.name,
+          {
+            services: plan.services,
+            serviceStatus: Object.fromEntries(
+              Object.entries(plan.services)
+                .filter(([, enabled]) => enabled)
+                .map(([service]) => [service, 'starting']),
+            ),
+            status: 'starting',
+          },
+        ])),
+      });
+    }
+    devTargetsController = await startStackDevTargets(devTargetsStartOptions);
+    console.log(
+      `${green('✓')} server: remote ${remoteServerPlan.target.name} ready through ${cyan(internalServerUrl)}`,
+    );
+  }
+
   // Reliability before daemon start:
-  // - Ensure schema exists (server-light: prisma migrate deploy; happier-server: migrate deploy if tables missing)
+  // - Ensure schema exists (server-light: canonical provider migration script; happier-server: migrate deploy if tables missing)
   // - Auto-seed from main only when needed (non-main + non-interactive default, and only if missing creds or 0 accounts)
   const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const accountProbeImpl = startupDecision.adoptedServer
+    ? probeExistingAccountCountForServerComponent
+    : getAccountCountForServerComponent;
   const accountProbe = startServer
-    ? await getAccountCountForServerComponent({
+    ? await accountProbeImpl({
         serverComponentName,
         serverDir,
         env: serverEnv,
@@ -430,7 +796,7 @@ async function main() {
       env: baseEnv,
       stackName,
       cliHomeDir,
-      startDaemon,
+      startDaemon: startupDecision.startDaemon,
       isInteractive,
       serverComponentName,
       serverDir,
@@ -439,7 +805,7 @@ async function main() {
     });
   }
 
-  if (startDaemon) {
+  if (startupDecision.startDaemon) {
     const gate = daemonStartGate({ env: baseEnv, cliHomeDir, serverUrl: internalServerUrl });
     if (!gate.ok) {
       // In orchestrated auth flows (setup-pr/review-pr), we intentionally keep server/UI up
@@ -454,13 +820,15 @@ async function main() {
       }
     } else {
       await startDevDaemon({
-        startDaemon,
+        startDaemon: true,
         cliBin,
         cliHomeDir,
         internalServerUrl,
         publicServerUrl,
         runtimeStatePath,
         restart,
+        startLastGreen: watchEnabled,
+        keepServerRunningOnFailure: baseEnv.HAPPIER_STACK_TUI === '1',
         isShuttingDown: () => shuttingDown,
         env: baseEnv,
         stackName,
@@ -468,50 +836,130 @@ async function main() {
     }
   }
 
-  const cliWatcher = watchHappyCliAndRestartDaemon({
-    enabled: watchEnabled,
-    startDaemon: startDaemon && daemonStartGate({ env: baseEnv, cliHomeDir, serverUrl: internalServerUrl }).ok,
-    buildCli,
-    cliDir,
-    cliBin,
-    cliHomeDir,
-    internalServerUrl,
-    publicServerUrl,
-    runtimeStatePath,
-    isShuttingDown: () => shuttingDown,
-    env: baseEnv,
-    stackName,
-  });
-  if (cliWatcher) watchers.push(cliWatcher);
+  if (startDaemon && stackMode && runtimeStatePath) {
+    const daemonRuntimeEnv = getDaemonEnv({
+      baseEnv,
+      cliHomeDir,
+      internalServerUrl,
+      publicServerUrl: publicServerUrl || internalServerUrl,
+      stackName,
+      cliIdentity: 'default',
+    });
+    const daemonRuntimeReconciler = startStackRuntimeDaemonPidReconciler(
+      {
+        runtimeStatePath,
+        cliHomeDir,
+        internalServerUrl,
+        env: daemonRuntimeEnv,
+        isShuttingDown: () => shuttingDown,
+      },
+      {
+        checkDaemonStateImpl: checkDaemonStatePingAware,
+      },
+    );
+    if (daemonRuntimeReconciler) {
+      watchers.push(daemonRuntimeReconciler);
+      await daemonRuntimeReconciler.syncNow();
+    }
+
+    const daemonLifecycleReconciler = startDevDaemonLifecycleReconciler({
+      enabled: true,
+      isShuttingDown: () => shuttingDown,
+      observe: async () => {
+        const gate = daemonStartGate({ env: baseEnv, cliHomeDir, serverUrl: internalServerUrl });
+        if (!gate.ok) return { status: 'inconclusive', reason: gate.reason };
+        return await checkDaemonStatePingAware(cliHomeDir, {
+          serverUrl: internalServerUrl,
+          env: daemonRuntimeEnv,
+          stackName,
+        });
+      },
+      recover: async () => {
+        await startDevDaemon({
+          startDaemon: true,
+          cliBin,
+          cliHomeDir,
+          internalServerUrl,
+          publicServerUrl,
+          runtimeStatePath,
+          restart: false,
+          startLastGreen: watchEnabled,
+          isShuttingDown: () => shuttingDown,
+          env: baseEnv,
+          stackName,
+        });
+        return { started: true };
+      },
+    });
+    if (daemonLifecycleReconciler) watchers.push(daemonLifecycleReconciler);
+  }
 
   const serverProcRef = { current: serverProc };
-  if (startServer && stackMode && runtimeStatePath && !serverProcRef.current?.pid) {
+  if (startServer && stackMode && runtimeStatePath && !serverProcRef.current?.pid && !serverRuntimeProxyAlreadyOwned) {
     // If the server was already running when we started dev, `startDevServer` won't spawn a new process
     // (and therefore we don't have a ChildProcess handle). For safe watch/restart we need a PID.
-    const state = await readStackRuntimeStateFile(runtimeStatePath);
-    const pid = state?.processes?.serverPid;
-    if (isPidAlive(pid)) {
+    const pid = await resolveStackOwnedServerRuntimePid({
+      runtimeStatePath,
+      serverPort: proxyPlan.mode === 'proxy' ? serverBindPort : serverPort,
+      stackName,
+      envPath,
+    }, { observationScope: createListenerOwnershipCommandScope() });
+    if (Number.isFinite(pid) && pid > 1) {
       serverProcRef.current = { pid: Number(pid), exitCode: null };
+      await recordStackRuntimeServerPids(runtimeStatePath, {
+        listenerPid: Number(pid),
+        wrapperPid: null,
+        serverPort,
+        clearProxyState: proxyPlan.mode !== 'proxy',
+      });
     }
   }
-  const serverWatcher = watchDevServerAndRestart({
-    enabled: startServer && watchEnabled && Boolean(serverProcRef.current?.pid),
-    stackMode,
-    serverComponentName,
-    serverDir,
-    serverPort,
-    internalServerUrl,
-    serverScript,
-    serverEnv,
-    runtimeStatePath,
-    stackName,
-    envPath,
-    children,
-    serverProcRef,
+
+  const daemonReloadEnabled = watchEnabled && startDaemon && daemonStartGate({ env: baseEnv, cliHomeDir, serverUrl: internalServerUrl }).ok;
+  const serverReloadEnabled = startServer && watchEnabled && Boolean(serverProcRef.current?.pid);
+  const reloadWatcher = startDevReloadComposition({
+    watchEnabled,
+    daemonReloadEnabled,
+    daemonOptions: {
+      startDaemon,
+      buildCli,
+      cliDir,
+      cliBin,
+      cliHomeDir,
+      internalServerUrl,
+      publicServerUrl,
+      runtimeStatePath,
+      isShuttingDown: () => shuttingDown,
+      env: baseEnv,
+      stackName,
+    },
+    serverReloadEnabled,
+    serverOptions: {
+      enabled: true,
+      stackMode,
+      serverComponentName,
+      serverDir,
+      serverPort,
+      serverBindPort,
+      internalServerUrl,
+      serverScript,
+      serverEnv,
+      runtimeStatePath,
+      stackName,
+      envPath,
+      children,
+      serverProcRef,
+      isShuttingDown: () => shuttingDown,
+      proxyController: proxyPlan.mode === 'proxy' ? proxyPlan.proxyController : null,
+    },
+    debounceMs: 500,
+    pollIntervalMs: resolveDevReloadPollIntervalMs(baseEnv),
     isShuttingDown: () => shuttingDown,
+    logger: console,
   });
-  if (serverWatcher) watchers.push(serverWatcher);
-  if (startServer && watchEnabled && stackMode && serverComponentName === 'happier-server' && !serverWatcher) {
+  if (reloadWatcher) watchers.push(reloadWatcher);
+
+  if (startServer && watchEnabled && stackMode && serverComponentName === 'happier-server' && !serverReloadEnabled) {
     console.warn(
       `[local] watch: server restart is disabled because the running server PID is unknown.\n` +
         `[local] watch: fix: re-run with --restart so hstack can (re)spawn the server and track its PID.`
@@ -520,7 +968,15 @@ async function main() {
 
   const expoRes =
     expoResEarly ??
-    (await ensureDevExpoServer({
+    (remoteExpoPlan
+      ? {
+          ok: true,
+          skipped: true,
+          reason: 'remote_target',
+          port: remoteExpoPort,
+          target: remoteExpoPlan.target.name,
+        }
+      : await ensureDevExpoServer({
       startUi,
       startMobile,
       uiDir,
@@ -534,7 +990,7 @@ async function main() {
       envPath,
       children,
       expoTailscale,
-    }));
+      }));
   if (startUi) {
     const uiPort = expoRes?.port;
     const uiUrlRaw = uiPort ? `http://localhost:${uiPort}` : '';
@@ -586,6 +1042,14 @@ async function main() {
     console.log(`[local] mobile: metro ${metroUrl}`);
   }
 
+  if (daemonReloadEnabled && reloadWatcher?.requestReload) {
+    void reloadWatcher.requestReload('daemon');
+  }
+
+  if (servicePlans.targets.length > 0 && !devTargetsController) {
+    devTargetsController = startStackDevTargetsInBackground(buildDevTargetsStartOptions());
+  }
+
   if (startTauri) {
     const invocation = resolveTauriPaneInvocation({ rootDir, env: baseEnv });
     const tauri = spawnProc('tauri', invocation.command, invocation.args, baseEnv, {
@@ -602,46 +1066,79 @@ async function main() {
     console.log(`[local] expo tailscale: http://${expoRes.tailscale.tailscaleIp}:${expoRes.port}`);
   }
 
-  const shutdown = async () => {
+  shutdown = async () => {
     if (shuttingDown) {
       return;
     }
     shuttingDown = true;
+    const shutdownRequest = runtimeStatePath
+      ? (await readStackRuntimeStateFile(runtimeStatePath).catch(() => null))?.stopRequest ?? null
+      : null;
+    const expectedStopState = runtimeStatePath
+      ? await captureStackRuntimeStopSnapshot(runtimeStatePath).catch(() => null)
+      : null;
+    const preserveDaemonOnShutdown = shutdownRequest?.preserveDaemon === true;
     console.log('\n[local] shutting down...');
 
+    if (devTargetsController) {
+      await devTargetsController.close().catch(() => {});
+    }
+
     for (const w of watchers) {
       try {
-        w.close();
+        await w.close?.();
       } catch {
         // ignore
       }
     }
 
-    if (startDaemon) {
-      await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir, runtimeStatePath });
+    if (proxyPlan?.proxyController) {
+      await proxyPlan.proxyController.stop().catch(() => {});
     }
 
-    for (const child of children) {
-      if (child.exitCode == null) {
-        killProcessTree(child, 'SIGINT');
-      }
+    if (startDaemon && !preserveDaemonOnShutdown) {
+      await stopLocalDaemon({
+        cliBin,
+        internalServerUrl,
+        cliHomeDir,
+        runtimeStatePath,
+        env: baseEnv,
+        stackName,
+        cliIdentity: String(baseEnv.HAPPIER_STACK_CLI_IDENTITY ?? '').trim() || 'default',
+      });
     }
 
+    const serverShutdownGraceMs = resolveServerShutdownGraceMs(baseEnv);
+    const cleanupResults = await Promise.all(children
+      .filter((child) => child.exitCode == null)
+      .map((child) => killProcessTree(child, 'SIGINT',
+        child === serverProcRef.current ? { 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'))));
+    if (runtimeStatePath && expectedStopState) {
+      await finalizeStackRuntimeStop(runtimeStatePath, {
+        expected: expectedStopState,
+        preserveDaemon: preserveDaemonOnShutdown,
+        cleanupResults,
+        requireNoStopRequest: true,
+      }).catch(() => {});
     }
   };
 
-  process.on('SIGINT', () => shutdown().then(() => process.exit(0)));
-  process.on('SIGTERM', () => shutdown().then(() => process.exit(0)));
+  if (pendingShutdownSignal) dispatchShutdown(pendingShutdownSignal);
 
   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);
 });