@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/dev_cli_build_ownership.test.mjs

@@ -0,0 +1,191 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ensureCliBuilt } from './utils/proc/pm.mjs';
+
+const scriptsDir = dirname(fileURLToPath(import.meta.url));
+
+test('dev publishes a configured remote Expo service in its initial runtime declaration', async () => {
+  const source = await readFile(join(scriptsDir, 'dev.mjs'), 'utf-8');
+  const remoteExpoPlanIndex = source.indexOf('const remoteExpoPlan = servicePlans.targets.find((plan) => plan.services.expo) ?? null;');
+  const configuredRemoteExpoIndex = source.indexOf('const initialRemoteExpoProjection =');
+  const runtimeStartIndex = source.indexOf('await recordStackRuntimeStart(runtimeStatePath, {');
+  const watchdogIndex = source.indexOf('spawnStackOwnerDeathWatchdog({');
+
+  assert.notEqual(remoteExpoPlanIndex, -1, 'expected the resolved remote Expo plan');
+  assert.notEqual(configuredRemoteExpoIndex, -1, 'expected an initial configured remote Expo projection');
+  assert.notEqual(runtimeStartIndex, -1, 'expected the canonical Stack runtime start publication');
+  assert.notEqual(watchdogIndex, -1, 'expected the initial runtime publication boundary');
+  assert.ok(
+    configuredRemoteExpoIndex < runtimeStartIndex,
+    'the initial remote Expo declaration must exist before a service tunnel can discover the Stack runtime',
+  );
+  const initialRuntimePublication = source.slice(runtimeStartIndex, watchdogIndex);
+  assert.match(
+    initialRuntimePublication,
+    /\.\.\.\(initialRemoteExpoProjection \? \{ expo: initialRemoteExpoProjection \} : \{\}\)/u,
+    'the first runtime declaration must expose the configured remote Expo service',
+  );
+  assert.match(
+    source.slice(remoteExpoPlanIndex, runtimeStartIndex),
+    /remoteExpoPlan[\s\S]*HAPPIER_STACK_EXPO_DEV_PORT[\s\S]*remoteTarget/u,
+    'only a configured remote Expo plan may be published before target startup',
+  );
+});
+
+function applyEnv(t, entries) {
+  for (const [key, value] of Object.entries(entries)) {
+    const previous = process.env[key];
+    if (value == null) delete process.env[key];
+    else process.env[key] = String(value);
+    t.after(() => {
+      if (previous == null) delete process.env[key];
+      else process.env[key] = previous;
+    });
+  }
+}
+
+async function createCliBuildFixture(t) {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-dev-cli-build-owner-'));
+  t.after(async () => rm(root, { recursive: true, force: true }));
+
+  const cliDir = join(root, 'apps', 'cli');
+  const agentsDir = join(root, 'packages', 'agents');
+  const binDir = join(root, 'bin');
+  const eventsPath = join(root, 'events.txt');
+  await mkdir(join(cliDir, 'src'), { recursive: true });
+  await mkdir(join(cliDir, 'node_modules'), { recursive: true });
+  await mkdir(join(agentsDir, 'src'), { recursive: true });
+  await mkdir(join(root, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(root, 'apps', 'server'), { recursive: true });
+  await mkdir(binDir, { recursive: true });
+  await writeFile(join(root, 'package.json'), '{"private":true}\n');
+  await writeFile(join(root, 'yarn.lock'), '# yarn\n');
+  await writeFile(join(root, 'apps', 'ui', 'package.json'), '{"name":"@happier-dev/ui"}\n');
+  await writeFile(join(root, 'apps', 'server', 'package.json'), '{"name":"@happier-dev/server"}\n');
+  await writeFile(join(cliDir, 'src', 'index.ts'), 'export const cli = true;\n');
+  await writeFile(join(cliDir, 'package.json'), JSON.stringify({
+    name: '@happier-dev/cli',
+    dependencies: { '@happier-dev/agents': '0.0.0' },
+  }));
+  await writeFile(join(cliDir, 'node_modules', '.yarn-integrity'), 'ok\n');
+  await writeFile(join(agentsDir, 'src', 'index.ts'), 'export const version = 1;\n');
+  await writeFile(join(agentsDir, 'package.json'), JSON.stringify({
+    name: '@happier-dev/agents',
+    main: './dist/index.js',
+    exports: { '.': './dist/index.js' },
+    scripts: { build: 'node scripts/build.mjs' },
+  }));
+  await writeFile(eventsPath, '');
+
+  const yarnPath = join(binDir, 'yarn');
+  await writeFile(yarnPath, [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    'if [ "${1:-}" = "--version" ]; then echo "1.22.22"; exit 0; fi',
+    'repo="${FIXTURE_ROOT:?}"',
+    'case "$PWD" in',
+    '*/packages/agents)',
+    '  echo "shared:agents" >> "${EVENTS_PATH:?}"',
+    '  out="${HAPPIER_WORKSPACE_DIST_OUTPUT_DIR:-dist}"',
+    '  mkdir -p "$out"',
+    '  printf "export const agents = true;\\n" > "$out/index.js"',
+    '  exit 0',
+    ';;',
+    'esac',
+    'case "$PWD" in',
+    '*/apps/cli)',
+    'if [ "${1:-}" = "build" ]; then',
+    '  # Yarn runs prebuild before build; model the real CLI build:shared owner.',
+    '  echo "shared:agents" >> "${EVENTS_PATH:?}"',
+    '  mkdir -p "$repo/packages/agents/dist"',
+    '  printf "export const agents = true;\\n" > "$repo/packages/agents/dist/index.js"',
+    '  echo "cli:build" >> "${EVENTS_PATH:?}"',
+    '  out="${HAPPIER_CLI_BUILD_OUTPUT_DIR:-dist}"',
+    '  mkdir -p "$out"',
+    '  printf "export const cli = true;\\n" > "$out/index.mjs"',
+    '  printf "{\\"fingerprint\\":\\"abcdef1234567890\\",\\"fileCount\\":1}\\n" > "$out/.build-manifest.json"',
+    '  if [ "${MUTATE_CLI_SOURCE_DURING_BUILD:-0}" = "1" ]; then',
+    '    printf "// changed while build was running\\n" >> "$repo/apps/cli/src/index.ts"',
+    '  fi',
+    '  exit 0',
+    'fi',
+    ';;',
+    'esac',
+    'exit 0',
+  ].join('\n') + '\n');
+  await chmod(yarnPath, 0o755);
+
+  applyEnv(t, {
+    PATH: `${binDir}:/usr/bin:/bin`,
+    FIXTURE_ROOT: root,
+    EVENTS_PATH: eventsPath,
+    HAPPIER_STACK_CLI_BUILD_MODE: 'auto',
+    HAPPIER_STACK_HOME_DIR: join(root, 'home'),
+    HAPPIER_STACK_ENV_FILE: null,
+    HAPPIER_STACK_SKIP_REFRESH_DEPS: '1',
+  });
+  return { cliDir, agentsDir, eventsPath };
+}
+
+function countEvent(events, expected) {
+  return events.split('\n').filter((event) => event.trim() === expected).length;
+}
+
+test('dev cold-start delegates CLI build admission exclusively to the daemon launch owner', async () => {
+  const source = await readFile(join(scriptsDir, 'dev.mjs'), 'utf-8');
+  assert.doesNotMatch(
+    source,
+    /ensureDevCliReady/,
+    'dev must not eagerly build before startDevDaemon re-enters canonical daemon generation admission',
+  );
+  assert.match(source, /await startDevDaemon\(/);
+});
+
+test('dev reaches Expo before starting remote development targets', async () => {
+  const source = await readFile(join(scriptsDir, 'dev.mjs'), 'utf-8');
+  const expoStartIndex = source.lastIndexOf('await ensureDevExpoServer({');
+  const devTargetsStartIndex = source.lastIndexOf('startStackDevTargetsInBackground(');
+
+  assert.notEqual(expoStartIndex, -1, 'expected the canonical Expo startup call');
+  assert.notEqual(devTargetsStartIndex, -1, 'expected background dev-target startup');
+  assert.ok(
+    expoStartIndex < devTargetsStartIndex,
+    'remote target bootstrap must not delay local Expo startup',
+  );
+});
+
+test('one CLI admission builds each missing or changed shared workspace once', async (t) => {
+  const { cliDir, agentsDir, eventsPath } = await createCliBuildFixture(t);
+
+  await ensureCliBuilt(cliDir, { buildCli: true, quiet: true, env: process.env });
+  let events = await readFile(eventsPath, 'utf-8');
+  assert.equal(countEvent(events, 'shared:agents'), 1, `cold build events:\n${events}`);
+  assert.equal(countEvent(events, 'cli:build'), 1, `cold build events:\n${events}`);
+
+  await writeFile(eventsPath, '');
+  await writeFile(join(agentsDir, 'src', 'index.ts'), 'export const version = 2;\n');
+  await ensureCliBuilt(cliDir, { buildCli: true, quiet: true, env: process.env });
+  events = await readFile(eventsPath, 'utf-8');
+  assert.equal(countEvent(events, 'shared:agents'), 1, `changed-input build events:\n${events}`);
+  assert.equal(countEvent(events, 'cli:build'), 1, `changed-input build events:\n${events}`);
+});
+
+test('one successful atomic CLI build is admitted as usable when later edits supersede it', async (t) => {
+  const { cliDir, eventsPath } = await createCliBuildFixture(t);
+  applyEnv(t, { MUTATE_CLI_SOURCE_DURING_BUILD: '1' });
+
+  const result = await ensureCliBuilt(cliDir, { buildCli: true, quiet: true, env: process.env });
+  const events = await readFile(eventsPath, 'utf-8');
+
+  assert.equal(countEvent(events, 'cli:build'), 1, `build events:\n${events}`);
+  assert.deepEqual(result, {
+    built: true,
+    current: false,
+    reason: 'inputs_changed_during_build',
+  });
+});

package/scripts/dev_external_server_flags.test.mjs

@@ -3,6 +3,8 @@ import assert from 'node:assert/strict';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 
 function runNode(args, { cwd, env }) {
   return new Promise((resolve, reject) => {
@@ -35,7 +37,10 @@ test('dev --no-server --json fails without an external server URL', async () =>
   const repoRoot = dirname(dirname(packageRoot)); // repo root
   const devScript = join(packageRoot, 'scripts', 'dev.mjs');
 
-  const res = await runNode([devScript, '--no-server', '--json'], { cwd: repoRoot, env: process.env });
+  const res = await runNode([devScript, '--no-server', '--json'], {
+    cwd: repoRoot,
+    env: { ...process.env, HAPPIER_SERVER_URL: '' },
+  });
   assert.equal(res.code, 1);
   assert.match(res.stderr, /--no-server requires an external server URL/);
 });
@@ -47,7 +52,7 @@ test('dev --server-url uses remote server mode', async () => {
   const devScript = join(packageRoot, 'scripts', 'dev.mjs');
 
   const res = await runNode(
-    [devScript, '--json', '--server-url=https://api.example.com'],
+    [devScript, '--json', '--server-url=https://api.example.com', '--no-dev-targets'],
     { cwd: repoRoot, env: process.env }
   );
   assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
@@ -58,6 +63,28 @@ test('dev --server-url uses remote server mode', async () => {
   assert.equal(parsed.publicServerUrl, 'https://api.example.com');
 });
 
+test('external-server startup sanitizes parent preflight authority before descendant orchestration', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const source = await readFile(join(scriptsDir, 'dev.mjs'), 'utf8');
+  const orchestrationEnvBoundary = source.indexOf('const baseEnv = { ...process.env };');
+  const runtimeStartBoundary = source.indexOf('await recordStackRuntimeStart');
+  const watchdogBoundary = source.indexOf('spawnStackOwnerDeathWatchdog({');
+  const optionalServerBoundary = source.indexOf('const { serverEnv, serverScript, serverProc }');
+  const descendantBoundary = source.indexOf('const accountProbe');
+  const sanitationBoundary = source.indexOf('delete baseEnv.HAPPIER_STACK_SERVER_RESTART_PREFLIGHT_ALREADY_DONE');
+
+  assert.ok(
+    orchestrationEnvBoundary >= 0
+      && sanitationBoundary > orchestrationEnvBoundary
+      && runtimeStartBoundary > sanitationBoundary
+      && watchdogBoundary > runtimeStartBoundary
+      && optionalServerBoundary > watchdogBoundary
+      && descendantBoundary > optionalServerBoundary,
+    'the long-lived env must be sanitized before runtime publication, watchdog spawn, and optional descendants',
+  );
+  assert.match(source.slice(optionalServerBoundary, descendantBoundary), /parentServerRestartPreflightAlreadyDone/);
+});
+
 test('dev --tauri --json reports desktop tauri mode', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
   const packageRoot = dirname(scriptsDir); // apps/stack
@@ -73,3 +100,116 @@ test('dev --tauri --json reports desktop tauri mode', async () => {
   assert.equal(parsed.startTauri, true);
   assert.equal(parsed.startUi, true);
 });
+
+test('dev --expo-tailscale --json enables mobile dev-client mode', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(scriptsDir); // apps/stack
+  const repoRoot = dirname(dirname(packageRoot)); // repo root
+  const devScript = join(packageRoot, 'scripts', 'dev.mjs');
+
+  const res = await runNode(
+    [
+      devScript,
+      '--json',
+      '--expo-tailscale',
+      '--server-url=https://api.example.com',
+      '--no-daemon',
+      '--no-dev-targets',
+    ],
+    { cwd: repoRoot, env: process.env }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  const parsed = JSON.parse(res.stdout);
+  assert.equal(parsed.startMobile, true);
+});
+
+test('dev --json discovers stack-scoped remote development targets without starting Mutagen', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(scriptsDir);
+  const repoRoot = dirname(dirname(packageRoot));
+  const devScript = join(packageRoot, 'scripts', 'dev.mjs');
+  const storageDir = await mkdtemp(join(tmpdir(), 'hstack-dev-json-targets-'));
+  const stackName = 'repo-json-targets';
+  try {
+    const stackDir = join(storageDir, stackName);
+    await mkdir(stackDir, { recursive: true });
+    await writeFile(
+      join(stackDir, 'dev-targets.json'),
+      JSON.stringify({
+        version: 1,
+        targets: [
+          {
+            name: 'linux',
+            platform: 'posix',
+            ssh: 'happier-stack-linux',
+            repoDir: '/home/dev/happier',
+            cliHomeDir: '/home/dev/.happier/linux',
+          },
+        ],
+      }),
+    );
+    const res = await runNode([devScript, '--json'], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        HAPPIER_STACK_STACK: stackName,
+        HAPPIER_STACK_HOME_DIR: join(storageDir, 'home'),
+        HAPPIER_STACK_STORAGE_DIR: storageDir,
+        HAPPIER_STACK_SANDBOX_DIR: join(storageDir, 'sandbox'),
+        HAPPIER_STACK_REPO_DIR: '',
+        HAPPIER_STACK_ENV_FILE: '',
+        HAPPIER_STACK_DISABLE_STACK_ENV_AUTOLOAD: '1',
+      },
+    });
+    assert.equal(res.code, 0, res.stderr);
+    const parsed = JSON.parse(res.stdout);
+    assert.deepEqual(parsed.devTargets.map((target) => target.name), ['linux']);
+  } finally {
+    await rm(storageDir, { recursive: true, force: true });
+  }
+});
+
+test('configured dev targets fail closed when dev uses an external server', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(scriptsDir);
+  const repoRoot = dirname(dirname(packageRoot));
+  const devScript = join(packageRoot, 'scripts', 'dev.mjs');
+  const storageDir = await mkdtemp(join(tmpdir(), 'hstack-dev-external-targets-'));
+  const stackName = 'repo-external-targets';
+  try {
+    const stackDir = join(storageDir, stackName);
+    await mkdir(stackDir, { recursive: true });
+    await writeFile(
+      join(stackDir, 'dev-targets.json'),
+      JSON.stringify({
+        version: 1,
+        targets: [
+          {
+            name: 'linux',
+            platform: 'posix',
+            ssh: 'happier-stack-linux',
+            repoDir: '/home/dev/happier',
+            cliHomeDir: '/home/dev/.happier/linux',
+          },
+        ],
+      }),
+    );
+    const res = await runNode([devScript, '--json', '--server-url=https://api.example.com'], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        HAPPIER_STACK_STACK: stackName,
+        HAPPIER_STACK_HOME_DIR: join(storageDir, 'home'),
+        HAPPIER_STACK_STORAGE_DIR: storageDir,
+        HAPPIER_STACK_SANDBOX_DIR: join(storageDir, 'sandbox'),
+        HAPPIER_STACK_REPO_DIR: '',
+        HAPPIER_STACK_ENV_FILE: '',
+        HAPPIER_STACK_DISABLE_STACK_ENV_AUTOLOAD: '1',
+      },
+    });
+    assert.equal(res.code, 1);
+    assert.match(res.stderr, /remote runtime placement cannot consume an external --server-url/);
+  } finally {
+    await rm(storageDir, { recursive: true, force: true });
+  }
+});

package/scripts/dev_preserve_daemon_shutdown.integration.test.mjs

@@ -0,0 +1,238 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createTempFixture } from './testkit/core/temp_fixture.mjs';
+import { writeStubHappierCliFiles } from './testkit/core/stub_happier_cli_files.mjs';
+import { resolvePreferredStackDaemonStatePaths } from './utils/auth/credentials_paths.mjs';
+import { applyStackActiveServerScopeEnv } from './utils/auth/stable_scope_id.mjs';
+import {
+  isPidAlive,
+  readStackRuntimeStateFile,
+  recordStackRuntimeStopRequest,
+} from './utils/stack/runtime_state.mjs';
+import { sanitizeStackTestRunnerEnv } from './utils/test/test_env.mjs';
+
+function stackRootDirFromMeta(metaUrl) {
+  return dirname(dirname(fileURLToPath(metaUrl)));
+}
+
+async function waitFor(check, { timeoutMs = 15_000, intervalMs = 25, label }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await check();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  throw new Error(`Timed out waiting for ${label}`);
+}
+
+async function startAuthServer(t) {
+  const server = createServer((req, res) => {
+    if (req.url === '/v1/account/profile') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+    res.writeHead(404).end();
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  t.after(() => new Promise((resolve) => server.close(resolve)));
+  const address = server.address();
+  assert.ok(address && typeof address === 'object');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+function createDaemonCliSource() {
+  const daemonSource = String.raw`
+const { createServer } = require('node:http');
+const { mkdirSync, writeFileSync } = require('node:fs');
+const { dirname } = require('node:path');
+const statePath = process.env.HAPPIER_TEST_DAEMON_STATE_PATH;
+const token = 'dev-preserve-daemon-control';
+const server = createServer((req, res) => {
+  const authenticated = req.headers['x-happier-daemon-token'] === token;
+  if (req.method === 'POST' && req.url === '/ping' && authenticated) {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, distClosureFingerprint: '0000000000000000' }));
+    return;
+  }
+  if (req.method === 'POST' && req.url === '/stop' && authenticated) {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+    res.once('finish', () => server.close());
+    return;
+  }
+  res.writeHead(404).end();
+});
+server.listen(0, '127.0.0.1', () => {
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify({
+    pid: process.pid,
+    httpPort: server.address().port,
+    controlToken: token,
+    startedAt: Date.now(),
+    startedWithCliVersion: 'test',
+  }) + '\n');
+});
+const shutdown = () => server.close(() => process.exit(0));
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+`;
+  return `
+import { spawn } from 'node:child_process';
+import { appendFileSync, readFileSync } from 'node:fs';
+
+const [command, subcommand] = process.argv.slice(2);
+const statePath = process.env.HAPPIER_TEST_DAEMON_STATE_PATH;
+const stopMarkerPath = process.env.HAPPIER_TEST_DAEMON_STOP_MARKER_PATH;
+
+if (command !== 'daemon') process.exit(0);
+if (subcommand === 'status') process.exit(0);
+if (subcommand === 'stop') {
+  appendFileSync(stopMarkerPath, 'stop\\n');
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    process.kill(Number(state.pid), 'SIGTERM');
+  } catch {}
+  process.exit(0);
+}
+
+if (subcommand === 'start') {
+  const source = ${JSON.stringify(daemonSource)};
+  const child = spawn(process.execPath, ['-e', source], {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  });
+  child.unref();
+  process.exit(0);
+}
+process.exit(1);
+`;
+}
+
+async function admitCurrentStubCli(repoDir) {
+  const cliDir = join(repoDir, 'apps', 'cli');
+  await mkdir(join(cliDir, 'node_modules'), { recursive: true });
+  await writeFile(join(cliDir, 'node_modules', '.yarn-integrity'), 'ok\n', 'utf8');
+  await writeFile(join(cliDir, 'yarn.lock'), '# fixture lock\n', 'utf8');
+  await writeFile(
+    join(cliDir, 'dist', '.build-manifest.json'),
+    JSON.stringify({ fingerprint: '0000000000000000', fileCount: 1 }) + '\n',
+    'utf8',
+  );
+}
+
+test('dev lifecycle-owner shutdown consumes a fresh preserveDaemon request', { timeout: 30_000 }, async (t) => {
+  const stackRootDir = stackRootDirFromMeta(import.meta.url);
+  const fixture = await createTempFixture(t, { prefix: 'hstack-dev-preserve-daemon-' });
+  const repoDir = join(fixture.root, 'repo');
+  const stackName = 'preserve-daemon';
+  const runtimeStatePath = join(fixture.root, 'stack.runtime.json');
+  const cliHomeDir = join(fixture.root, 'cli-home');
+  const stopMarkerPath = join(fixture.root, 'daemon-stop-called');
+  const serverUrl = await startAuthServer(t);
+
+  await mkdir(join(repoDir, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(repoDir, 'apps', 'server'), { recursive: true });
+  await writeStubHappierCliFiles(repoDir, {
+    packageJsonContent: JSON.stringify({ name: '@fixture/cli', version: '0.0.0' }),
+    distIndexScript: createDaemonCliSource(),
+    binHappierScript: "import '../dist/index.mjs';\n",
+  });
+  await admitCurrentStubCli(repoDir);
+  await mkdir(cliHomeDir, { recursive: true });
+  await writeFile(join(cliHomeDir, 'access.key'), 'test-token\n', 'utf8');
+  await writeFile(join(cliHomeDir, 'settings.json'), JSON.stringify({ machineId: 'test-machine' }) + '\n', 'utf8');
+
+  const baseEnv = {
+    ...sanitizeStackTestRunnerEnv(process.env, { isolatedStackRoot: fixture.root, repoDir }),
+    HAPPIER_STACK_STACK: stackName,
+    HAPPIER_STACK_RUNTIME_STATE_PATH: runtimeStatePath,
+    HAPPIER_STACK_CLI_HOME_DIR: cliHomeDir,
+    HAPPIER_STACK_CLI_BUILD: '1',
+    HAPPIER_STACK_SKIP_REFRESH_DEPS: '1',
+    HAPPIER_STACK_MIGRATE_CREDENTIALS: '0',
+    HAPPIER_STACK_AUTO_AUTH_SEED: '0',
+    HAPPIER_STACK_CREDENTIAL_VALIDATE_TIMEOUT_MS: '1000',
+    HAPPIER_STACK_DAEMON_START_VERIFY_TIMEOUT_MS: '5000',
+    HAPPIER_STACK_DAEMON_START_VERIFY_POLL_MS: '25',
+    HAPPIER_STACK_DAEMON_START_VERIFY_STABLE_MS: '0',
+    HAPPIER_STACK_NO_BROWSER: '1',
+    HAPPIER_TEST_DAEMON_STOP_MARKER_PATH: stopMarkerPath,
+  };
+  const daemonEnv = applyStackActiveServerScopeEnv({ env: baseEnv, stackName, cliIdentity: 'default' });
+  const { statePath: daemonStatePath } = resolvePreferredStackDaemonStatePaths({
+    cliHomeDir,
+    serverUrl,
+    env: daemonEnv,
+  });
+  baseEnv.HAPPIER_TEST_DAEMON_STATE_PATH = daemonStatePath;
+
+  const owner = spawn(process.execPath, [
+    join(stackRootDir, 'scripts', 'dev.mjs'),
+    '--no-server',
+    '--no-ui',
+    '--no-watch',
+    `--server-url=${serverUrl}`,
+  ], {
+    cwd: repoDir,
+    env: baseEnv,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let stdout = '';
+  let stderr = '';
+  owner.stdout.on('data', (chunk) => { stdout += String(chunk); });
+  owner.stderr.on('data', (chunk) => { stderr += String(chunk); });
+  const ownerExit = new Promise((resolve) => owner.once('exit', (code, signal) => resolve({ code, signal })));
+  let daemonPid = null;
+  t.after(async () => {
+    if (owner.exitCode == null && owner.signalCode == null) owner.kill('SIGKILL');
+    if (Number(daemonPid) > 1 && isPidAlive(daemonPid)) {
+      try { process.kill(daemonPid, 'SIGTERM'); } catch {}
+    }
+  });
+
+  const runtime = await waitFor(async () => {
+    if (owner.exitCode != null || owner.signalCode != null) {
+      throw new Error(`dev owner exited before daemon startup\nstdout:\n${stdout}\nstderr:\n${stderr}`);
+    }
+    const state = await readStackRuntimeStateFile(runtimeStatePath).catch(() => null);
+    const pid = Number(state?.processes?.daemonPid);
+    return Number.isFinite(pid) && pid > 1 && isPidAlive(pid) ? state : null;
+  }, { label: 'dev owner to publish a live daemon pid' });
+  daemonPid = Number(runtime.processes.daemonPid);
+  // Runtime daemon publication happens just before the owner finishes installing
+  // its reload composition and signal handlers. Let that bounded synchronous tail settle.
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  const stopMarkerBeforeShutdown = await readFile(stopMarkerPath, 'utf8').catch(() => '');
+
+  await recordStackRuntimeStopRequest(runtimeStatePath, {
+    signal: 'SIGTERM',
+    requestedBy: 'integration test',
+    reason: 'restart while preserving daemon',
+    preserveDaemon: true,
+  });
+  owner.kill('SIGTERM');
+  const exit = await waitFor(async () => {
+    const result = await Promise.race([
+      ownerExit,
+      new Promise((resolve) => setTimeout(() => resolve(null), 25)),
+    ]);
+    return result;
+  }, { label: 'dev owner shutdown' });
+
+  assert.equal(exit.code, 0, `stdout:\n${stdout}\nstderr:\n${stderr}`);
+  assert.equal(isPidAlive(daemonPid), true, 'fresh preserveDaemon request must keep the daemon alive');
+  assert.equal(await readFile(stopMarkerPath, 'utf8').catch(() => ''), stopMarkerBeforeShutdown);
+  const finalized = await readStackRuntimeStateFile(runtimeStatePath);
+  assert.ok(finalized?.processes?.daemonPids?.includes(daemonPid));
+});