@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/scripts/run_effective_db_provider.test.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { join } from 'node:path';
+
+import { runNode } from './testkit/runtime_snapshot_testkit.mjs';
+
+const stackRootDir = join(import.meta.dirname, '..');
+const runScript = join(stackRootDir, 'scripts', 'run.mjs');
+
+function isolatedEnv(overrides = {}) {
+  const env = {
+    ...process.env,
+    HAPPIER_STACK_STACK: 'provider-start-test',
+    HAPPIER_STACK_ENV_FILE: join(import.meta.dirname, 'nonexistent-provider-start-env'),
+    HAPPIER_STACK_REPO_DIR: join(stackRootDir, '..', '..'),
+    HAPPIER_STACK_RUNTIME_MODE: 'source',
+    HAPPIER_STACK_SERVE_UI: '0',
+    HAPPIER_STACK_DAEMON: '0',
+    ...overrides,
+  };
+  delete env.HAPPIER_DB_PROVIDER;
+  delete env.HAPPY_DB_PROVIDER;
+  return Object.assign(env, overrides);
+}
+
+test('hstack start materializes the full server default and postgresql alias', async () => {
+  for (const [env, expectedSource] of [
+    [isolatedEnv(), 'postgres'],
+    [isolatedEnv({ HAPPY_DB_PROVIDER: ' PostgreSQL ' }), 'postgres'],
+  ]) {
+    const result = await runNode([runScript, '--server=happier-server', '--no-ui', '--json'], {
+      cwd: stackRootDir,
+      env,
+    });
+    assert.equal(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+    assert.equal(JSON.parse(result.stdout).dbProvider, expectedSource);
+  }
+});
+
+test('hstack start accepts every supported provider under the full server preset', async () => {
+  for (const provider of ['sqlite', 'pglite']) {
+    const result = await runNode([runScript, '--server=happier-server', '--no-ui', '--json'], {
+      cwd: stackRootDir,
+      env: isolatedEnv({ HAPPIER_DB_PROVIDER: provider }),
+    });
+    assert.equal(result.code, 0, `provider=${JSON.stringify(provider)}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+    assert.equal(JSON.parse(result.stdout).dbProvider, provider);
+  }
+});
+
+test('hstack start rejects empty and unsupported providers before startup', async () => {
+  for (const provider of ['', 'unsupported']) {
+    const result = await runNode([runScript, '--server=happier-server', '--no-ui', '--json'], {
+      cwd: stackRootDir,
+      env: isolatedEnv({ HAPPIER_DB_PROVIDER: provider }),
+    });
+    assert.notEqual(result.code, 0, `provider=${JSON.stringify(provider)}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+    assert.match(`${result.stdout}\n${result.stderr}`, /unsupported DB provider/i);
+  }
+});
+
+test('hstack start requires explicit mysql database authority before startup', async () => {
+  const missing = await runNode([runScript, '--server=happier-server', '--no-ui', '--json'], {
+    cwd: stackRootDir,
+    env: isolatedEnv({ HAPPIER_DB_PROVIDER: 'mysql' }),
+  });
+  assert.notEqual(missing.code, 0, `stdout:\n${missing.stdout}\nstderr:\n${missing.stderr}`);
+  assert.match(`${missing.stdout}\n${missing.stderr}`, /mysql.*explicit DATABASE_URL/i);
+
+  const explicit = await runNode([runScript, '--server=happier-server', '--no-ui', '--json'], {
+    cwd: stackRootDir,
+    env: isolatedEnv({
+      HAPPIER_DB_PROVIDER: 'mysql',
+      DATABASE_URL: 'mysql://operator/db',
+    }),
+  });
+  assert.equal(explicit.code, 0, `stdout:\n${explicit.stdout}\nstderr:\n${explicit.stderr}`);
+  assert.equal(JSON.parse(explicit.stdout).dbProvider, 'mysql');
+});

package/scripts/run_script_with_stack_env.restart_port_reuse.test.mjs

@@ -1,11 +1,58 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 import {
+  completeStackRestartStopBeforeSuccessor,
+  createOuterStackRuntimeStartPublication,
   hasRecordedRuntimePortsForRestart,
   shouldReuseRuntimePortsOnRestart,
 } from './stack/run_script_with_stack_env.mjs';
 
+test('restart stop rethrows an initial failure when no persisted cleanup can be continued', async (t) => {
+  const fixtureDir = await mkdtemp(join(tmpdir(), 'happier-stack-restart-stop-'));
+  t.after(async () => {
+    await rm(fixtureDir, { recursive: true, force: true });
+  });
+  const invalidBaseDir = join(fixtureDir, 'not-a-directory');
+  await writeFile(invalidBaseDir, 'file blocks cleanup state writes', 'utf8');
+
+  await assert.rejects(
+    () => completeStackRestartStopBeforeSuccessor({
+      rootDir: fixtureDir,
+      stackName: 'restart-stop-error',
+      baseDir: invalidBaseDir,
+      env: {},
+      json: true,
+      noDocker: true,
+      aggressive: false,
+      sweepOwned: true,
+      preserveDaemon: true,
+    }),
+    { code: 'EEXIST' },
+  );
+});
+
+test('outer start publication records requested UI truth before the child runner starts', () => {
+  const base = {
+    stackName: 'runtime-ui',
+    scriptPath: 'run.mjs',
+    ephemeral: false,
+    ownerPid: 4242,
+    ports: { server: 4101 },
+    runtimeSnapshotId: 'snapshot-1',
+  };
+
+  assert.equal(createOuterStackRuntimeStartPublication({ ...base, args: ['--no-ui'], env: {} }).serveUi, false);
+  assert.equal(
+    createOuterStackRuntimeStartPublication({ ...base, args: [], env: { HAPPIER_STACK_SERVE_UI: '0' } }).serveUi,
+    false,
+  );
+  assert.equal(createOuterStackRuntimeStartPublication({ ...base, args: [], env: {} }).serveUi, true);
+});
+
 test('hasRecordedRuntimePortsForRestart requires a positive server port', () => {
   assert.equal(hasRecordedRuntimePortsForRestart(null), false);
   assert.equal(hasRecordedRuntimePortsForRestart({ ports: {} }), false);
@@ -28,3 +75,36 @@ test('shouldReuseRuntimePortsOnRestart stays false when restart was not requeste
     false
   );
 });
+
+test('stopped-stack restart cannot authorize the outer destructive stop path', async () => {
+  assert.equal(
+    shouldReuseRuntimePortsOnRestart({ wantsRestart: true, runtimeState: null, wasRunning: false }),
+    false,
+  );
+
+  const source = await readFile(new URL('./stack/run_script_with_stack_env.mjs', import.meta.url), 'utf8');
+  const decisionBoundary = source.indexOf('const isTrueRestart =');
+  const stopBoundary = source.indexOf('await completeStackRestartStopBeforeSuccessor({', decisionBoundary);
+  const stopGuardBoundary = source.lastIndexOf('if (isTrueRestart)', stopBoundary);
+  assert.ok(
+    decisionBoundary >= 0 && stopGuardBoundary > decisionBoundary && stopBoundary > stopGuardBoundary,
+    'the canonical true-restart decision must guard the destructive outer stop',
+  );
+  assert.equal(
+    (source.match(/await completeStackRestartStopBeforeSuccessor\(/g) ?? []).length,
+    2,
+    'both restart cleanup paths must complete the canonical stop before successor admission',
+  );
+  const helperBoundary = source.indexOf('export async function completeStackRestartStopBeforeSuccessor');
+  const helperStopBoundary = source.indexOf('await stopStackWithEnv(', helperBoundary);
+  const helperContinuationBoundary = source.indexOf('return await completeInterruptedStackStopBeforeStart(', helperBoundary);
+  assert.ok(
+    helperBoundary >= 0 && helperStopBoundary > helperBoundary && helperContinuationBoundary > helperStopBoundary,
+    'restart cleanup must continue any persisted incomplete stop after the first stop attempt',
+  );
+  assert.doesNotMatch(
+    source,
+    /listListenPids\([^)]*\)[\s\S]{0,1200}killProcessGroupOwnedByStack\(/,
+    'restart wrappers must never select a termination target from a listening port',
+  );
+});

package/scripts/run_source_server_workspace_deps.test.mjs

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+
+test('hstack start routes every source-backed server spawn through the canonical declaration admission owner', async () => {
+  const source = await readFile(new URL('./run.mjs', import.meta.url), 'utf8');
+
+  assert.equal(source.includes("from './utils/server/source_server_workspace_deps.mjs'"), true);
+  assert.equal(source.includes('pmSpawnScript'), false, 'run.mjs must not bypass source-server admission');
+  assert.equal(
+    source.includes("spawnSourceServerScript({ label: 'server', serverDir, script: 'start', env: backendEnv })"),
+    true,
+  );
+  assert.equal(
+    source.includes("spawnSourceServerScript({ label: 'server', serverDir, script: serverStartScript, env: serverEnv })"),
+    true,
+  );
+});

package/scripts/run_startup_topology_side_effects.test.mjs

@@ -0,0 +1,196 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+const scriptsDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = dirname(dirname(dirname(scriptsDir)));
+const runScript = join(scriptsDir, 'run.mjs');
+const devScript = join(scriptsDir, 'dev.mjs');
+
+async function stopProcess(child) {
+  if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return;
+  const exited = new Promise((resolve) => child.once('exit', resolve));
+  try { process.kill(-child.pid, 'SIGTERM'); } catch {}
+  await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 500))]);
+  if (child.exitCode === null && child.signalCode === null) {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+    await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 500))]);
+  }
+  child.stdout?.destroy();
+  child.stderr?.destroy();
+}
+
+async function spawnForeignHealthServer({ stackName, envPath, healthStatus = 200 }) {
+  const child = spawn(process.execPath, ['-e', `
+    const { createServer } = require('node:http');
+    const server = createServer((req, res) => {
+      if (req.url === '/health') {
+        res.statusCode = ${healthStatus};
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ service: 'happier-server', status: 'ok' }));
+        return;
+      }
+      res.statusCode = 404;
+      res.end();
+    });
+    server.listen(0, '127.0.0.1', () => process.stdout.write(String(server.address().port) + '\\n'));
+    setInterval(() => {}, 1e6);
+  `], {
+    env: {
+      ...process.env,
+      HAPPIER_STACK_STACK: stackName,
+      HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_PROCESS_KIND: 'server',
+    },
+    stdio: ['ignore', 'pipe', 'ignore'],
+    detached: true,
+  });
+  child.unref();
+  const port = await new Promise((resolve, reject) => {
+    let output = '';
+    const timer = setTimeout(() => reject(new Error('foreign server fixture timed out')), 2_000);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      output += String(chunk);
+      const value = Number(output.split(/\r?\n/).find(Boolean));
+      if (Number.isInteger(value) && value > 0) {
+        clearTimeout(timer);
+        resolve(value);
+      }
+    });
+  });
+  return { child, port };
+}
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill('SIGKILL'), 8_000);
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? (signal ? 1 : 0), stdout, stderr });
+    });
+  });
+}
+
+test('run adopts exact-owned topology before package-manager or infrastructure side effects', async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'hstack-run-topology-gate-'));
+  const fakeRepo = join(tempRoot, 'repo');
+  const storageDir = join(tempRoot, 'storage');
+  const stackName = 'topology-gate';
+  const baseDir = join(storageDir, stackName);
+  const envPath = join(baseDir, 'env');
+  const foreignEnvPath = join(tempRoot, 'foreign.env');
+  const runtimeStatePath = join(baseDir, 'stack.runtime.json');
+  const binDir = join(tempRoot, 'bin');
+  const sideEffectMarker = join(tempRoot, 'side-effect');
+  let server = null;
+
+  t.after(async () => {
+    await stopProcess(server?.child);
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await mkdir(join(fakeRepo, 'apps', 'server'), { recursive: true });
+  await mkdir(join(fakeRepo, 'apps', 'cli', 'dist'), { recursive: true });
+  await mkdir(join(fakeRepo, 'apps', 'ui'), { recursive: true });
+  await mkdir(baseDir, { recursive: true });
+  await mkdir(binDir, { recursive: true });
+  await writeFile(join(fakeRepo, 'package.json'), JSON.stringify({ name: 'fake-root', private: true }) + '\n');
+  await writeFile(join(fakeRepo, 'apps', 'server', 'package.json'), JSON.stringify({
+    name: 'fake-server', private: true, scripts: { start: 'node server.mjs' },
+  }) + '\n');
+  await writeFile(join(fakeRepo, 'apps', 'cli', 'package.json'), JSON.stringify({ name: 'fake-cli', private: true }) + '\n');
+  await writeFile(join(fakeRepo, 'apps', 'ui', 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n');
+  await writeFile(join(fakeRepo, 'apps', 'cli', 'dist', 'index.mjs'), 'process.exit(0);\n');
+  await writeFile(envPath, `HAPPIER_STACK_STACK=${stackName}\n`);
+  await writeFile(foreignEnvPath, 'HAPPIER_STACK_STACK=foreign-stack\n');
+
+  server = await spawnForeignHealthServer({ stackName, envPath, healthStatus: 503 });
+  await writeFile(join(binDir, 'lsof'), '#!/bin/sh\nprintf "%s\\n" "$FAKE_LISTEN_PID"\n');
+  await writeFile(join(binDir, 'ps'), `#!/bin/sh
+case "$*" in
+  *"pgid="*) printf "%s\\n" "$FAKE_LISTEN_PID" ;;
+  *"eww -p"*)
+    printf "PID COMMAND\\n"
+    printf "%s node HAPPIER_STACK_STACK=%s HAPPIER_STACK_ENV_FILE=%s HAPPIER_STACK_PROCESS_KIND=server\\n" "$FAKE_LISTEN_PID" "$FAKE_STACK_NAME" "$FAKE_STACK_ENV_FILE"
+    ;;
+  *) exec /bin/ps "$@" ;;
+esac
+`);
+  await writeFile(join(binDir, 'yarn'), '#!/bin/sh\nprintf "yarn:%s\\n" "$*" >> "$SIDE_EFFECT_MARKER"\ncase "$*" in *install*) exit 0 ;; *) exit 1 ;; esac\n');
+  await writeFile(join(binDir, 'docker'), '#!/bin/sh\nprintf "docker:%s\\n" "$*" >> "$SIDE_EFFECT_MARKER"\nexit 0\n');
+  await Promise.all(['lsof', 'ps', 'yarn', 'docker'].map((name) => chmod(join(binDir, name), 0o755)));
+  await writeFile(runtimeStatePath, JSON.stringify({
+    version: 1,
+    stackName,
+    ownerPid: null,
+    ports: { server: server.port },
+    processes: { proxyPid: server.child.pid, serverPid: 777777, serverBackendPid: 777777 },
+    serverProxy: { enabled: true, mode: 'proxy' },
+  }) + '\n');
+
+  const result = await runNode([runScript, '--source', '--no-daemon', '--no-ui'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      PATH: `${binDir}:${process.env.PATH}`,
+      SIDE_EFFECT_MARKER: sideEffectMarker,
+      FAKE_LISTEN_PID: String(server.child.pid),
+      FAKE_STACK_NAME: stackName,
+      FAKE_STACK_ENV_FILE: envPath,
+      FOREIGN_ENV_FILE: foreignEnvPath,
+      CI: '1',
+      HAPPIER_STACK_RUNTIME_MODE: 'source',
+      HAPPIER_STACK_REPO_DIR: fakeRepo,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: stackName,
+      HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_RUNTIME_STATE_PATH: runtimeStatePath,
+      HAPPIER_STACK_SKIP_REFRESH_DEPS: '0',
+      HAPPIER_STACK_SERVER_COMPONENT: 'happier-server',
+      HAPPIER_STACK_SERVER_PORT: String(server.port),
+      HAPPIER_STACK_PRISMA_MIGRATE: '0',
+      HAPPIER_STACK_DOCKER_AUTOSTART: '0',
+      HAPPIER_STACK_SERVE_UI: '0',
+    },
+  });
+
+  assert.equal(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  assert.match(`${result.stdout}\n${result.stderr}`, /already running/i);
+  const finalRuntime = JSON.parse(await readFile(runtimeStatePath, 'utf8'));
+  assert.equal(finalRuntime.processes.proxyPid, server.child.pid);
+  assert.notEqual(finalRuntime.processes.serverPid, server.child.pid);
+  const devResult = await runNode([devScript, '--no-daemon', '--no-mobile'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      PATH: `${binDir}:${process.env.PATH}`,
+      SIDE_EFFECT_MARKER: sideEffectMarker,
+      FAKE_LISTEN_PID: String(server.child.pid),
+      FAKE_STACK_NAME: stackName,
+      FAKE_STACK_ENV_FILE: envPath,
+      CI: '1', HAPPIER_STACK_REPO_DIR: fakeRepo, HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: stackName, HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_RUNTIME_STATE_PATH: runtimeStatePath, HAPPIER_STACK_SERVER_PORT: String(server.port),
+      HAPPIER_STACK_PRISMA_MIGRATE: '0', HAPPIER_STACK_DOCKER_AUTOSTART: '0', HAPPIER_STACK_SERVE_UI: '0',
+    },
+  });
+  assert.notEqual(devResult.code, 0, 'the fake UI launcher should terminate the public dev fixture');
+  const afterDevRuntime = JSON.parse(await readFile(runtimeStatePath, 'utf8'));
+  assert.equal(afterDevRuntime.processes.proxyPid, server.child.pid);
+  assert.notEqual(afterDevRuntime.processes.serverPid, server.child.pid);
+  const sideEffects = await readFile(sideEffectMarker, 'utf8').catch((error) => error?.code === 'ENOENT' ? '' : Promise.reject(error));
+  assert.match(`${devResult.stdout}\n${devResult.stderr}`, /expo|ui|package|workspace/i);
+  assert.doesNotMatch(sideEffects, /prisma|migrat|happier-server(?:-light)?/i);
+  await assert.rejects(() => readFile(join(fakeRepo, 'yarn.lock'), 'utf8'), /ENOENT/);
+});

package/scripts/runtime/launch/inspectActiveRuntimeSnapshot.mjs

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import { getFirstPartyComponentCatalogEntry } from '@happier-dev/cli-common/firstPartyRuntime';
 
 import { pathExists } from '../../utils/fs/fs.mjs';
+import { readJsonIfExists } from '../../utils/fs/json.mjs';
 import {
   readRuntimeManifest,
   readRuntimePointer,
@@ -36,6 +37,24 @@ async function collectSnapshotRuntimePayloadErrors({ snapshotPath }) {
     : [`[runtime] active runtime snapshot is incomplete: missing daemon node entrypoint (${daemonNodeEntrypoint}).`];
 }
 
+async function inspectDaemonDistClosure({ snapshotPath }) {
+  const daemonComponent = getFirstPartyComponentCatalogEntry('happier-daemon');
+  if (!daemonComponent.nodeEntrypointRelativePath) {
+    return { fingerprint: null, errors: ['[runtime] daemon runtime has no node entrypoint identity.'] };
+  }
+  const daemonNodeEntrypoint = resolve(snapshotPath, 'cli', daemonComponent.nodeEntrypointRelativePath);
+  const buildManifestPath = resolve(daemonNodeEntrypoint, '..', '.build-manifest.json');
+  const buildManifest = await readJsonIfExists(buildManifestPath, { defaultValue: null });
+  const fingerprint = String(buildManifest?.fingerprint ?? '').trim().toLowerCase();
+  if (!/^[a-f0-9]{16}$/.test(fingerprint)) {
+    return {
+      fingerprint: null,
+      errors: [`[runtime] active runtime daemon has an invalid dist closure fingerprint (${buildManifestPath}).`],
+    };
+  }
+  return { fingerprint, errors: [] };
+}
+
 export async function inspectActiveRuntimeSnapshot({ stackBaseDir }) {
   const runtimePaths = resolveStackRuntimePaths({ stackBaseDir });
   const pointer = await readRuntimePointer({ currentPath: runtimePaths.currentPath });
@@ -69,6 +88,9 @@ export async function inspectActiveRuntimeSnapshot({ stackBaseDir }) {
   const validation = validateRuntimeManifest(manifest);
   const errors = [];
 
+  if (Number(pointer?.version) !== 1) {
+    errors.push('[runtime] active runtime pointer version must be 1.');
+  }
   if (normalizedPointerSnapshotPath !== normalizedExpectedSnapshotPath) {
     errors.push('[runtime] active runtime snapshot points outside the stack runtime builds dir.');
   }
@@ -76,6 +98,16 @@ export async function inspectActiveRuntimeSnapshot({ stackBaseDir }) {
     errors.push(`[runtime] invalid active runtime snapshot: ${validation.errors.join('; ')}`);
   }
   if (validation.ok) {
+    if (validation.manifest.snapshotId !== activeSnapshotId) {
+      errors.push('[runtime] active runtime pointer and manifest snapshot identity do not match.');
+    }
+    const pointerSourceFingerprint = String(pointer?.sourceFingerprint ?? '').trim();
+    if (
+      !pointerSourceFingerprint
+      || pointerSourceFingerprint !== validation.manifest.sourceFingerprint
+    ) {
+      errors.push('[runtime] active runtime pointer and manifest source fingerprint do not match.');
+    }
     errors.push(
       ...(await collectSnapshotEntrypointErrors({
         snapshotPath: normalizedExpectedSnapshotPath,
@@ -87,22 +119,15 @@ export async function inspectActiveRuntimeSnapshot({ stackBaseDir }) {
     );
   }
 
+  const daemonDistClosure = validation.ok
+    ? await inspectDaemonDistClosure({ snapshotPath: normalizedExpectedSnapshotPath })
+    : { fingerprint: null, errors: [] };
+  errors.push(...daemonDistClosure.errors);
+
   const sourceFingerprint =
     String(pointer?.sourceFingerprint ?? '').trim() || validation.manifest?.sourceFingerprint || null;
   const valid = errors.length === 0 && Boolean(validation.manifest);
-  let launchPath = normalizedExpectedSnapshotPath;
-  if (valid) {
-    const currentDirErrors = await collectSnapshotEntrypointErrors({
-      snapshotPath: runtimePaths.currentDir,
-      manifest: validation.manifest,
-    });
-    const currentRuntimePayloadErrors = await collectSnapshotRuntimePayloadErrors({
-      snapshotPath: runtimePaths.currentDir,
-    });
-    if (currentDirErrors.length === 0 && currentRuntimePayloadErrors.length === 0) {
-      launchPath = runtimePaths.currentDir;
-    }
-  }
+  const launchPath = normalizedExpectedSnapshotPath;
 
   return {
     missing: false,
@@ -112,6 +137,7 @@ export async function inspectActiveRuntimeSnapshot({ stackBaseDir }) {
     snapshotPath: normalizedPointerSnapshotPath,
     launchPath,
     sourceFingerprint,
+    daemonDistClosureFingerprint: daemonDistClosure.fingerprint,
     manifest: validation.manifest,
     snapshot: valid
       ? {
@@ -119,6 +145,7 @@ export async function inspectActiveRuntimeSnapshot({ stackBaseDir }) {
           snapshotPath: normalizedExpectedSnapshotPath,
           launchPath,
           sourceFingerprint,
+          daemonDistClosureFingerprint: daemonDistClosure.fingerprint,
           manifest: validation.manifest,
         }
       : null,

package/scripts/runtime/launch/resolveActiveRuntimeSnapshot.test.mjs

@@ -127,6 +127,11 @@ test('resolveActiveRuntimeSnapshot returns validated manifest and pointer data',
   await writeFile(join(paths.snapshotDir, 'server', 'dist', 'runtime', 'main.js'), 'export {};\n', 'utf-8');
   await writeFile(join(paths.snapshotDir, 'cli', 'dist', 'index.mjs'), 'export {};\n', 'utf-8');
   await writeFile(join(paths.snapshotDir, 'cli', 'package-dist', 'index.mjs'), 'export {};\n', 'utf-8');
+  await writeFile(
+    join(paths.snapshotDir, 'cli', 'package-dist', '.build-manifest.json'),
+    JSON.stringify({ fingerprint: '1111111111111111', fileCount: 1 }),
+    'utf-8',
+  );
   await writeRuntimeManifest({
     manifestPath: paths.manifestPath,
     manifest: {
@@ -157,5 +162,119 @@ test('resolveActiveRuntimeSnapshot returns validated manifest and pointer data',
 
   assert.equal(resolved.snapshotId, 'snap-1');
   assert.equal(resolved.snapshotPath, paths.snapshotDir);
+  assert.equal(resolved.launchPath, paths.snapshotDir);
+  assert.equal(resolved.daemonDistClosureFingerprint, '1111111111111111');
   assert.equal(resolved.manifest.sourceFingerprint, 'src-1');
 });
+
+test('resolveActiveRuntimeSnapshot pins an admitted launch to its immutable build after later activation', async (t) => {
+  const root = await withTempRoot(t);
+
+  const writeSnapshot = async (snapshotId, fingerprint) => {
+    const paths = resolveStackRuntimePaths({ stackBaseDir: root, snapshotId });
+    await mkdir(join(paths.snapshotDir, 'ui'), { recursive: true });
+    await mkdir(join(paths.snapshotDir, 'server'), { recursive: true });
+    await mkdir(join(paths.snapshotDir, 'cli', 'package-dist'), { recursive: true });
+    await writeFile(join(paths.snapshotDir, 'ui', 'index.html'), '<html></html>\n', 'utf-8');
+    await writeFile(join(paths.snapshotDir, 'server', 'happier-server'), 'server\n', 'utf-8');
+    await writeFile(join(paths.snapshotDir, 'cli', 'happier'), 'daemon\n', 'utf-8');
+    await writeFile(join(paths.snapshotDir, 'cli', 'package-dist', 'index.mjs'), 'export {};\n', 'utf-8');
+    await writeFile(
+      join(paths.snapshotDir, 'cli', 'package-dist', '.build-manifest.json'),
+      JSON.stringify({ fingerprint, fileCount: 1 }),
+      'utf-8',
+    );
+    await writeRuntimeManifest({
+      manifestPath: paths.manifestPath,
+      manifest: {
+        version: 1,
+        snapshotId,
+        sourceFingerprint: `src-${snapshotId}`,
+        components: {
+          web: { artifactFingerprint: `web-${snapshotId}`, entrypoint: 'ui/index.html' },
+          server: { artifactFingerprint: `srv-${snapshotId}`, entrypoint: 'server/happier-server' },
+          daemon: { artifactFingerprint: `cli-${snapshotId}`, entrypoint: 'cli/happier' },
+        },
+      },
+    });
+    return paths;
+  };
+
+  const first = await writeSnapshot('snap-1', '1111111111111111');
+  const second = await writeSnapshot('snap-2', '2222222222222222');
+  await mkdir(join(first.currentDir, 'ui'), { recursive: true });
+  await mkdir(join(first.currentDir, 'server'), { recursive: true });
+  await mkdir(join(first.currentDir, 'cli', 'package-dist'), { recursive: true });
+  await writeFile(join(first.currentDir, 'ui', 'index.html'), '<html>mutable current</html>\n', 'utf-8');
+  await writeFile(join(first.currentDir, 'server', 'happier-server'), 'current server\n', 'utf-8');
+  await writeFile(join(first.currentDir, 'cli', 'happier'), 'current daemon\n', 'utf-8');
+  await writeFile(join(first.currentDir, 'cli', 'package-dist', 'index.mjs'), 'export {};\n', 'utf-8');
+  await writeRuntimePointer({
+    currentPath: first.currentPath,
+    pointer: {
+      version: 1,
+      snapshotId: 'snap-1',
+      snapshotPath: first.snapshotDir,
+      sourceFingerprint: 'src-snap-1',
+    },
+  });
+
+  const admitted = await resolveActiveRuntimeSnapshot({ mode: 'require', stackBaseDir: root });
+
+  await writeRuntimePointer({
+    currentPath: second.currentPath,
+    pointer: {
+      version: 1,
+      snapshotId: 'snap-2',
+      snapshotPath: second.snapshotDir,
+      sourceFingerprint: 'src-snap-2',
+    },
+  });
+
+  assert.equal(admitted.launchPath, first.snapshotDir);
+  assert.equal(admitted.daemonDistClosureFingerprint, '1111111111111111');
+});
+
+test('resolveActiveRuntimeSnapshot rejects pointer and manifest source fingerprint mismatch', async (t) => {
+  const root = await withTempRoot(t);
+  const paths = resolveStackRuntimePaths({ stackBaseDir: root, snapshotId: 'snap-mismatch' });
+  await mkdir(join(paths.snapshotDir, 'ui'), { recursive: true });
+  await mkdir(join(paths.snapshotDir, 'server'), { recursive: true });
+  await mkdir(join(paths.snapshotDir, 'cli', 'package-dist'), { recursive: true });
+  await writeFile(join(paths.snapshotDir, 'ui', 'index.html'), '<html></html>\n', 'utf-8');
+  await writeFile(join(paths.snapshotDir, 'server', 'happier-server'), 'server\n', 'utf-8');
+  await writeFile(join(paths.snapshotDir, 'cli', 'happier'), 'daemon\n', 'utf-8');
+  await writeFile(join(paths.snapshotDir, 'cli', 'package-dist', 'index.mjs'), 'export {};\n', 'utf-8');
+  await writeFile(
+    join(paths.snapshotDir, 'cli', 'package-dist', '.build-manifest.json'),
+    JSON.stringify({ fingerprint: '1111111111111111', fileCount: 1 }),
+    'utf-8',
+  );
+  await writeRuntimeManifest({
+    manifestPath: paths.manifestPath,
+    manifest: {
+      version: 1,
+      snapshotId: 'snap-mismatch',
+      sourceFingerprint: 'manifest-source',
+      components: {
+        web: { artifactFingerprint: 'web-1', entrypoint: 'ui/index.html' },
+        server: { artifactFingerprint: 'srv-1', entrypoint: 'server/happier-server' },
+        daemon: { artifactFingerprint: 'cli-1', entrypoint: 'cli/happier' },
+      },
+    },
+  });
+  await writeRuntimePointer({
+    currentPath: paths.currentPath,
+    pointer: {
+      version: 1,
+      snapshotId: 'snap-mismatch',
+      snapshotPath: paths.snapshotDir,
+      sourceFingerprint: 'pointer-source',
+    },
+  });
+
+  await assert.rejects(
+    resolveActiveRuntimeSnapshot({ mode: 'require', stackBaseDir: root }),
+    /source fingerprint/i,
+  );
+});