@happier-dev/stack 0.2.12 → 0.2.13

package/scripts/stack_happy_cmd.integration.test.mjs

@@ -6,20 +6,18 @@ import { fileURLToPath } from 'node:url';
 import { runNodeCapture } from './testkit/stack_script_command_testkit.mjs';
 import { createStackHappierCliCommandFixture } from './testkit/stack_happier_cli_command_testkit.mjs';
 import { createRuntimeSnapshotFixture } from './testkit/runtime_snapshot_testkit.mjs';
+import { buildStubHappierServerSetSource } from './testkit/core/stub_happier_cli_server_set.mjs';
 import { buildStackStableScopeId } from './utils/auth/stable_scope_id.mjs';
 
 const scriptsDir = dirname(fileURLToPath(import.meta.url));
 const rootDir = dirname(scriptsDir);
 
-function buildStubHappyCliScript({ message }) {
+const SERVER_SET_CALL_LOG_FILE_NAME = '.hstack-test-server-set-calls.ndjson';
+
+function buildStubHappyCliScript({ message, ignoreServerSet = false }) {
   return [
-      `import { appendFileSync } from 'node:fs';`,
-      `import { join } from 'node:path';`,
       `const args = process.argv.slice(2);`,
-      `if (args[0] === 'server' && args[1] === 'set') {`,
-      `  appendFileSync(join(process.env.HAPPIER_HOME_DIR, '.hstack-test-server-set-calls.ndjson'), JSON.stringify(args) + '\\n');`,
-      `  process.exit(0);`,
-      `}`,
+      buildStubHappierServerSetSource({ ignoreServerSet, callLogFileName: SERVER_SET_CALL_LOG_FILE_NAME }),
       `console.log(JSON.stringify({`,
       `  message: ${JSON.stringify(message)},`,
       `  args,`,
@@ -42,7 +40,7 @@ async function createHappyStackFixture(
   {
     prefix,
     stackName = 'exp-test',
-    serverPort = 3999,
+    serverPort,
     stubType = 'success',
     message = 'hello',
     errorMessage = 'stub failure',
@@ -59,17 +57,23 @@ async function createHappyStackFixture(
     distIndexScript:
       stubType === 'failing'
         ? buildFailingStubHappyCliScript({ errorMessage })
-        : buildStubHappyCliScript({ message }),
+        : buildStubHappyCliScript({
+            message,
+            ignoreServerSet: stubType === 'legacy-ignore-server-set',
+          }),
   });
   if (!includePinnedServerPortInEnvFile) {
     await fixture.writeStackEnv({ port: '' });
   }
 
-  if (stackCliSettings) {
+  const resolvedStackCliSettings = typeof stackCliSettings === 'function'
+    ? stackCliSettings({ serverPort: fixture.serverPort })
+    : stackCliSettings;
+  if (resolvedStackCliSettings) {
     await mkdir(join(fixture.storageDir, stackName, 'cli'), { recursive: true });
     await writeFile(
       join(fixture.storageDir, stackName, 'cli', 'settings.json'),
-      JSON.stringify(stackCliSettings, null, 2) + '\n',
+      JSON.stringify(resolvedStackCliSettings, null, 2) + '\n',
       'utf-8',
     );
   }
@@ -83,7 +87,7 @@ async function createHappyStackFixture(
           stackName,
           ephemeral: true,
           ownerPid: runtimeOwnerPid,
-          ports: { server: serverPort },
+          ports: { server: fixture.serverPort },
           processes: { serverPid: runtimeServerPid },
         },
         null,
@@ -95,6 +99,7 @@ async function createHappyStackFixture(
 
   return {
     stackName: fixture.stackName,
+    serverPort: fixture.serverPort,
     storageDir: fixture.storageDir,
     baseEnv: fixture.baseEnv,
   };
@@ -104,7 +109,6 @@ test('hstack stack happier <name> runs CLI under that stack env', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-',
     message: 'hello',
-    serverPort: 3999,
   });
 
   const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
@@ -118,14 +122,13 @@ test('hstack stack happier <name> runs CLI under that stack env', async (t) => {
   assert.equal(out.stack, fixture.stackName);
   assert.ok(String(out.envFile).endsWith(`/${fixture.stackName}/env`), `expected envFile to end with /${fixture.stackName}/env, got: ${out.envFile}`);
   assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli'));
-  assert.equal(out.serverUrl, 'http://127.0.0.1:3999');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
 });
 
 test('hstack stack happier <name> overrides pre-set HAPPIER_* env vars with stack-scoped values', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-override-',
     message: 'override',
-    serverPort: 4123,
   });
 
   const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
@@ -143,14 +146,13 @@ test('hstack stack happier <name> overrides pre-set HAPPIER_* env vars with stac
   assert.equal(out.message, 'override');
   assert.equal(out.stack, fixture.stackName);
   assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli'));
-  assert.equal(out.serverUrl, 'http://127.0.0.1:4123');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
 });
 
 test('hstack stack happier <name> ignores stale cloud settings defaults and keeps stack-local server urls', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-ignore-settings-',
     message: 'ignore-settings-defaults',
-    serverPort: 44123,
     stackCliSettings: {
       schemaVersion: 6,
       onboardingCompleted: false,
@@ -179,15 +181,14 @@ test('hstack stack happier <name> ignores stale cloud settings defaults and keep
   assert.equal(out.message, 'ignore-settings-defaults');
   assert.equal(out.stack, fixture.stackName);
   assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli'));
-  assert.equal(out.serverUrl, 'http://127.0.0.1:44123');
-  assert.equal(out.webappUrl, 'http://localhost:44123');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
+  assert.equal(out.webappUrl, `http://localhost:${fixture.serverPort}`);
 });
 
 test('hstack stack happier <name> delegates stack profile reconciliation to the selected CLI runtime', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-seed-settings-',
     message: 'seed-settings',
-    serverPort: 45123,
     stackCliSettings: {
       schemaVersion: 6,
       onboardingCompleted: false,
@@ -207,7 +208,7 @@ test('hstack stack happier <name> delegates stack profile reconciliation to the
   });
 
   const settingsPath = join(fixture.storageDir, fixture.stackName, 'cli', 'settings.json');
-  const serverSetCallsPath = join(fixture.storageDir, fixture.stackName, 'cli', '.hstack-test-server-set-calls.ndjson');
+  const serverSetCallsPath = join(fixture.storageDir, fixture.stackName, 'cli', SERVER_SET_CALL_LOG_FILE_NAME);
 
   const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
     cwd: rootDir,
@@ -226,24 +227,60 @@ test('hstack stack happier <name> delegates stack profile reconciliation to the
     '--server-id',
     out.activeServerId,
     '--server-url',
-    'http://127.0.0.1:45123',
+    `http://127.0.0.1:${fixture.serverPort}`,
     '--local-server-url',
-    'http://127.0.0.1:45123',
+    `http://127.0.0.1:${fixture.serverPort}`,
     '--webapp-url',
-    'http://localhost:45123',
+    `http://localhost:${fixture.serverPort}`,
     '--migrate-matching-profile-state',
     '--json',
   ]]);
 
   const settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-  assert.equal(settings.activeServerId, 'cloud', 'the wrapper must not mutate settings behind the CLI owner');
+  assert.equal(settings.activeServerId, out.activeServerId, 'the selected CLI must own the reconciled active profile');
+  assert.equal(settings.servers[out.activeServerId].serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
+  // The CLI collapses a local URL equal to the relay URL; only the relay URL is persisted.
+  assert.equal(settings.servers[out.activeServerId].localServerUrl, undefined);
+  assert.equal(settings.servers[out.activeServerId].webappUrl, `http://localhost:${fixture.serverPort}`);
+});
+
+test('hstack stack happier <name> rejects a CLI that exits successfully without reconciling the stack profile', async (t) => {
+  const fixture = await createHappyStackFixture(t, {
+    prefix: 'happier-stack-stack-happy-legacy-server-set-',
+    message: 'must-not-run',
+    stubType: 'legacy-ignore-server-set',
+    stackCliSettings: {
+      schemaVersion: 6,
+      onboardingCompleted: false,
+      activeServerId: 'cloud',
+      servers: {
+        cloud: {
+          id: 'cloud',
+          name: 'Happier Cloud',
+          serverUrl: 'https://api.happier.dev',
+          webappUrl: 'https://app.happier.dev',
+          createdAt: 0,
+          updatedAt: 0,
+          lastUsedAt: 0,
+        },
+      },
+    },
+  });
+
+  const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName], {
+    cwd: rootDir,
+    env: fixture.baseEnv,
+  });
+
+  assert.notEqual(res.code, 0, `expected reconciliation verification to fail\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stderr, /did not apply the requested stack relay profile/i);
+  assert.doesNotMatch(res.stdout, /must-not-run/);
 });
 
 test('hstack stack happier <name> uses stack.runtime.json ports when env file does not pin HAPPIER_STACK_SERVER_PORT', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-runtime-ports-',
     message: 'runtime-ports',
-    serverPort: 4777,
     includePinnedServerPortInEnvFile: false,
     // Simulate a stale owner pid but a still-running server process.
     runtimeOwnerPid: 999999,
@@ -259,7 +296,7 @@ test('hstack stack happier <name> uses stack.runtime.json ports when env file do
   const out = JSON.parse(res.stdout.trim());
   assert.equal(out.message, 'runtime-ports');
   assert.equal(out.stack, fixture.stackName);
-  assert.equal(out.serverUrl, 'http://127.0.0.1:4777');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
 });
 
 test('hstack stack happier <name> forwards wrapper runtime flags to happier.mjs', async (t) => {
@@ -290,7 +327,6 @@ test('hstack happier (HAPPIER_STACK_STACK set) uses stack.runtime.json ports whe
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-happy-runtime-ports-',
     message: 'runtime-ports-env',
-    serverPort: 4888,
     includePinnedServerPortInEnvFile: false,
     // Simulate a stale owner pid but a still-running server process.
     runtimeOwnerPid: 999999,
@@ -315,16 +351,15 @@ test('hstack happier (HAPPIER_STACK_STACK set) uses stack.runtime.json ports whe
   const out = JSON.parse(res.stdout.trim());
   assert.equal(out.message, 'runtime-ports-env');
   assert.equal(out.stack, fixture.stackName);
-  assert.equal(out.serverUrl, 'http://127.0.0.1:4888');
-  assert.equal(out.webappUrl, 'http://localhost:4888');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
+  assert.equal(out.webappUrl, `http://localhost:${fixture.serverPort}`);
 });
 
 test('hstack happier keeps the stable scope when another settings profile matches the stack URL', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-explicit-stack-scope-',
     message: 'explicit-stack-scope',
-    serverPort: 5123,
-    stackCliSettings: {
+    stackCliSettings: ({ serverPort }) => ({
       schemaVersion: 6,
       onboardingCompleted: true,
       activeServerId: 'stack-local',
@@ -332,14 +367,14 @@ test('hstack happier keeps the stable scope when another settings profile matche
         'stack-local': {
           id: 'stack-local',
           name: 'Stack Local',
-          serverUrl: 'http://127.0.0.1:5123',
-          webappUrl: 'http://localhost:5123',
+          serverUrl: `http://127.0.0.1:${serverPort}`,
+          webappUrl: `http://localhost:${serverPort}`,
           createdAt: 0,
           updatedAt: 0,
           lastUsedAt: 0,
         },
       },
-    },
+    }),
   });
 
   const env = {
@@ -360,8 +395,8 @@ test('hstack happier keeps the stable scope when another settings profile matche
   assert.equal(out.stack, fixture.stackName);
   assert.ok(String(out.envFile).endsWith(`/${fixture.stackName}/env`), `expected envFile to end with /${fixture.stackName}/env, got: ${out.envFile}`);
   assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli'));
-  assert.equal(out.serverUrl, 'http://127.0.0.1:5123');
-  assert.equal(out.webappUrl, 'http://localhost:5123');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
+  assert.equal(out.webappUrl, `http://localhost:${fixture.serverPort}`);
   assert.equal(
     out.activeServerId,
     buildStackStableScopeId({ stackName: fixture.stackName, cliIdentity: 'default' }),
@@ -372,7 +407,6 @@ test('hstack stack happier <name> --identity=<name> uses identity-scoped HAPPIER
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-identity-',
     message: 'identity',
-    serverPort: 3999,
   });
   const identity = 'account-a';
 
@@ -386,14 +420,13 @@ test('hstack stack happier <name> --identity=<name> uses identity-scoped HAPPIER
   assert.equal(out.message, 'identity');
   assert.equal(out.stack, fixture.stackName);
   assert.equal(out.homeDir, join(fixture.storageDir, fixture.stackName, 'cli-identities', identity));
-  assert.equal(out.serverUrl, 'http://127.0.0.1:3999');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
 });
 
 test('hstack <stack> happier ... shorthand runs CLI under that stack env', async (t) => {
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happy-stacks-stack-happy-',
     message: 'shorthand',
-    serverPort: 4101,
   });
 
   const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), fixture.stackName, 'happier'], { cwd: rootDir, env: fixture.baseEnv });
@@ -402,7 +435,7 @@ test('hstack <stack> happier ... shorthand runs CLI under that stack env', async
   const out = JSON.parse(res.stdout.trim());
   assert.equal(out.message, 'shorthand');
   assert.equal(out.stack, fixture.stackName);
-  assert.equal(out.serverUrl, 'http://127.0.0.1:4101');
+  assert.equal(out.serverUrl, `http://127.0.0.1:${fixture.serverPort}`);
 });
 
 test('hstack stack happier <name> does not print wrapper stack traces on CLI failure', async (t) => {
@@ -410,7 +443,6 @@ test('hstack stack happier <name> does not print wrapper stack traces on CLI fai
     prefix: 'happy-stacks-stack-happy-fail-',
     stubType: 'failing',
     errorMessage: 'stub failure',
-    serverPort: 3999,
   });
 
   const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', 'happier', fixture.stackName, 'attach', 'abc'], {
@@ -428,7 +460,6 @@ test('hstack stack <name> happier ... stack-name-first shorthand works', async (
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-happy-name-first-',
     message: 'name-first',
-    serverPort: 3999,
   });
 
   const res = await runNodeCapture([join(rootDir, 'bin', 'hstack.mjs'), 'stack', fixture.stackName, 'happier'], {
@@ -446,7 +477,6 @@ test('hstack stack bug-report <name> forwards bug-report command under stack env
   const fixture = await createHappyStackFixture(t, {
     prefix: 'happier-stack-stack-bug-report-',
     message: 'bug-report-alias',
-    serverPort: 4099,
   });
 
   const res = await runNodeCapture(

package/scripts/testkit/core/lima_guest_harness.mjs

@@ -0,0 +1,32 @@
+import { filterEnvForSpawn } from './env_scope.mjs';
+
+export function createLimaTestEnv(parentEnv = process.env) {
+  // These shell fixtures run on the host, not in a VM. Inheriting stack or
+  // provider settings can give a fixture access to the developer's live daemon.
+  return {
+    ...filterEnvForSpawn(parentEnv, { keepKeys: ['TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL'] }),
+    PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+  };
+}
+
+// A real Lima guest has its own login files and PATH. Our process-boundary fake
+// must not source the host's /etc/profile, which can restore the real Happier CLI
+// ahead of fixture executables (including when the caller prefixes bash with env).
+export const limaGuestExec = `
+if [[ "\${1:-}" == "env" ]]; then
+  shift
+  while [[ "\${1:-}" == *=* ]]; do export "$1"; shift; done
+fi
+unset BASH_ENV ENV
+if [[ "\${1:-}" != "bash" || ( "\${2:-}" != "-lc" && "\${2:-}" != "-c" && "\${2:-}" != "-s" ) ]]; then
+  echo "unsupported fake Lima guest command: $*" >&2
+  exit 2
+fi
+shift
+if [[ "$1" == "-lc" ]]; then shift; set -- -c "$@"; fi
+# Guest daemon process matching belongs to the VM's process namespace. These
+# fixtures have no real guest processes and must never match host daemons.
+pkill() { return 0; }
+export -f pkill
+exec /bin/bash --noprofile --norc "$@"
+`;

package/scripts/testkit/core/lima_guest_harness.test.mjs

@@ -0,0 +1,61 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, writeFile, access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createLimaTestEnv, limaGuestExec } from './lima_guest_harness.mjs';
+
+test('Lima fixtures exclude ambient stack, provider, shell, and executable selection', () => {
+  const env = createLimaTestEnv({
+    PATH: '/real/user/bin',
+    HOME: '/real/user',
+    HAPPIER_HOME_DIR: '/real/stack/cli',
+    HAPPIER_ACTIVE_SERVER_ID: 'live-server',
+    HAPPIER_QA_STACK_NAME: 'live-stack',
+    WSREPL_QA_VM_HAPPIER_MODE: 'autoupdate',
+    CLAUDE_CONFIG_DIR: '/real/claude',
+    CODEX_HOME: '/real/codex',
+    BASH_ENV: '/real/shell-startup',
+    NODE_OPTIONS: '--import=/real/preload.mjs',
+    TMPDIR: '/tmp/fixture-parent',
+    LANG: 'en_US.UTF-8',
+  });
+  assert.equal(env.HAPPIER_HOME_DIR, undefined);
+  assert.equal(env.HAPPIER_ACTIVE_SERVER_ID, undefined);
+  assert.equal(env.HAPPIER_QA_STACK_NAME, undefined);
+  assert.equal(env.HOME, undefined);
+  assert.equal(env.CLAUDE_CONFIG_DIR, undefined);
+  assert.equal(env.CODEX_HOME, undefined);
+  assert.equal(env.BASH_ENV, undefined);
+  assert.equal(env.NODE_OPTIONS, undefined);
+  assert.equal(env.WSREPL_QA_VM_HAPPIER_MODE, undefined);
+  assert.ok(!env.PATH.includes('/real/user/bin'));
+  assert.equal(env.TMPDIR, '/tmp/fixture-parent');
+  assert.equal(env.LANG, 'en_US.UTF-8');
+});
+
+test('fake Lima executes guest scripts without a host login shell, preserving explicit guest environment and argv', () => {
+  for (const prefix of [[], ['env', 'LIMA_INSTANCE=fixture-vm']]) {
+    const result = spawnSync('/bin/bash', ['--noprofile', '--norc', '-c', limaGuestExec, 'fake-lima',
+      ...prefix, 'bash', '-lc',
+      'if shopt -q login_shell; then exit 42; fi; printf "%s\\n" "${LIMA_INSTANCE:-}" "$1"',
+      'guest', 'argument with spaces',
+    ], { env: { PATH: '/usr/bin:/bin', HOME: '/tmp' }, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, `${prefix.length ? 'fixture-vm' : ''}\nargument with spaces\n`);
+  }
+});
+
+test('fake guest daemon cleanup cannot invoke host process matching', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'lima-guest-process-boundary-'));
+  const marker = join(root, 'host-pkill-invoked');
+  await writeFile(join(root, 'pkill'), '#!/bin/bash\nprintf called > "$HOST_KILL_MARKER"\n', { mode: 0o755 });
+  const result = spawnSync('/bin/bash', ['-c', limaGuestExec, 'fake-lima', 'bash', '-lc',
+    'pkill -f "package-dist/index.mjs daemon start-sync"; printf done',
+  ], { env: { PATH: `${root}:/usr/bin:/bin`, HOME: root, HOST_KILL_MARKER: marker }, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout, 'done');
+  await assert.rejects(access(marker), { code: 'ENOENT' });
+});

package/scripts/testkit/core/stub_happier_cli_server_set.mjs

@@ -0,0 +1,51 @@
+/**
+ * Source fragment that gives a stub Happier CLI script a `server set` implementation.
+ *
+ * The fragment expects `args` (the CLI argv slice) to be in scope and runs inside an ESM script,
+ * so it may use top-level `await`. It persists the profile the way the real CLI profile writer does
+ * (`apps/cli/src/server/serverProfiles.ts`): the active profile switches to the requested id,
+ * unrelated profile fields survive, the settings schema is stamped to the supported version, and a
+ * `localServerUrl` equal to `serverUrl` is not written because the CLI collapses that split.
+ * Keep it aligned with that writer; stack reconciliation checks read the persisted shape.
+ *
+ * - `ignoreServerSet`: exit successfully without touching settings, like a legacy CLI that does not
+ *   understand the stack profile flags.
+ * - `callLogFileName`: when set, append each `server set` argv as one JSON line to this file inside
+ *   the CLI home before handling the command.
+ */
+export function buildStubHappierServerSetSource({ ignoreServerSet = false, callLogFileName = null } = {}) {
+  return `
+if (args[0] === 'server' && args[1] === 'set') {
+  const { appendFileSync, readFileSync, writeFileSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const home = process.env.HAPPIER_HOME_DIR || process.env.HAPPIER_STACK_CLI_HOME_DIR;
+  if (!home) process.exit(2);
+  ${callLogFileName ? `appendFileSync(join(home, ${JSON.stringify(callLogFileName)}), JSON.stringify(args) + '\\n');` : ''}
+  ${ignoreServerSet ? 'process.exit(0);' : ''}
+  const value = (name) => {
+    const index = args.indexOf(name);
+    return index >= 0 ? String(args[index + 1] || '') : '';
+  };
+  const serverId = value('--server-id');
+  const serverUrl = value('--server-url');
+  const localServerUrl = value('--local-server-url');
+  const settingsPath = join(home, 'settings.json');
+  const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  const { localServerUrl: previousLocalServerUrl, ...current } = settings.servers?.[serverId] ?? {};
+  settings.schemaVersion = Math.max(Number(settings.schemaVersion || 0), 6);
+  settings.activeServerId = serverId;
+  settings.servers = {
+    ...(settings.servers ?? {}),
+    [serverId]: {
+      ...current,
+      id: serverId,
+      serverUrl,
+      ...(localServerUrl && localServerUrl !== serverUrl ? { localServerUrl } : {}),
+      webappUrl: value('--webapp-url'),
+    },
+  };
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\\n', 'utf-8');
+  process.exit(0);
+}
+`;
+}

package/scripts/testkit/stack_happier_cli_command_testkit.mjs

@@ -1,20 +1,37 @@
 import { mkdir, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
 import { join } from 'node:path';
 
 import { ensureMinimalMonorepoLayout } from './core/minimal_monorepo_layout.mjs';
 import { writeStubHappierCliFiles } from './core/stub_happier_cli_files.mjs';
 import { createTempFixture } from './core/temp_fixture.mjs';
 
+async function allocateAvailableLocalhostPort() {
+  const server = createServer();
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    await new Promise((resolve) => server.close(resolve));
+    throw new Error('expected an allocated localhost TCP port');
+  }
+  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  return address.port;
+}
+
 export async function createStackHappierCliCommandFixture(
   t,
   {
     prefix,
     stackName = 'exp-test',
-    serverPort = 4101,
+    serverPort,
     distIndexScript,
     binHappierScript = "import '../dist/index.mjs';\n",
   } = {},
 ) {
+  const resolvedServerPort = serverPort ?? await allocateAvailableLocalhostPort();
   const fixture = await createTempFixture(t, { prefix });
   const tmp = fixture.root;
   const storageDir = join(tmp, 'storage');
@@ -36,7 +53,7 @@ export async function createStackHappierCliCommandFixture(
   async function writeStackEnv({
     name = stackName,
     cliHomeDir = stackCliHome,
-    port = serverPort,
+    port = resolvedServerPort,
     repoDir = monoRoot,
   } = {}) {
     const envPath = join(storageDir, name, 'env');
@@ -64,6 +81,7 @@ export async function createStackHappierCliCommandFixture(
     workspaceDir,
     monoRoot,
     stackName,
+    serverPort: resolvedServerPort,
     stackCliHome,
     envPath,
     writeStackEnv,

package/scripts/utils/dev_targets/mutagen_project.mjs

@@ -40,6 +40,12 @@ const DEFAULT_IGNORES = [
   // Expo prebuild generates this entire Git-ignored tree for the target's
   // native identity and toolchain. Replication would undo its Info.plist.
   'apps/ui/ios',
+  // Desktop preparation owns these generated sidecars and their JS runtime companions.
+  // Replicating a local build would replace the target-native executable after Cargo builds it.
+  'apps/ui/src-tauri/binaries',
+  'apps/ui/src-tauri/systemTasks',
+  'apps/ui/src-tauri/ssh',
+  'apps/ui/src-tauri/integrations',
   'apps/ui/android/app/build',
   'apps/ui/android/build',
   'apps/ui/android/.gradle',

package/scripts/utils/dev_targets/mutagen_project.test.mjs

@@ -77,6 +77,10 @@ test('renderMutagenProject creates one-way source replicas while retaining targe
     '.dist.hstack-*',
     '.cxx',
     'apps/ui/ios',
+    'apps/ui/src-tauri/binaries',
+    'apps/ui/src-tauri/systemTasks',
+    'apps/ui/src-tauri/ssh',
+    'apps/ui/src-tauri/integrations',
     'apps/ui/android/app/build',
     'apps/ui/android/build',
     'apps/ui/android/.gradle',

package/scripts/utils/dev_targets/remote_commands.mjs

@@ -1,5 +1,7 @@
 import { resolveEffectiveDbProvider } from '../server/effective_db_provider.mjs';
 
+export const DEFAULT_REMOTE_STACK_STARTUP_TIMEOUT_MS = 30 * 60_000;
+
 function posixQuote(value) {
   return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
 }
@@ -299,7 +301,7 @@ function resolveRemoteStackInvocation(target, {
     ]),
     ...(stablePublicExpoPort == null ? [] : [`HAPPIER_STACK_EXPO_PUBLIC_PORT=${stablePublicExpoPort}`]),
     ...(expoPublicUrl && !resolveExpoPublicUrlOnTarget ? [`EXPO_PACKAGER_PROXY_URL=${expoPublicUrl}`] : []),
-    'HAPPIER_CLI_PKGROLL_TIMEOUT_MS=1800000',
+    `HAPPIER_CLI_PKGROLL_TIMEOUT_MS=${DEFAULT_REMOTE_STACK_STARTUP_TIMEOUT_MS}`,
     ...(normalizedServices.daemon && deferDaemonStartUntilCredentials
       ? ['HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH=1']
       : []),

package/scripts/utils/dev_targets/supervisor.mjs

@@ -12,6 +12,7 @@ import {
   resolveMutagenSessionName,
 } from './mutagen_project.mjs';
 import {
+  DEFAULT_REMOTE_STACK_STARTUP_TIMEOUT_MS,
   buildRemoteBootstrapCommand,
   buildRemoteStackCommand,
   buildRemoteStackStopCommand,
@@ -22,6 +23,13 @@ import {
   buildSshWorkerArgs,
 } from './remote_commands.mjs';
 
+export function resolveRemoteServerReadyTimeoutMs(env = process.env) {
+  const configured = Number.parseInt(String(env.HAPPIER_STACK_SERVER_READY_TIMEOUT_MS ?? ''), 10);
+  return Number.isFinite(configured) && configured >= 1_000
+    ? configured
+    : DEFAULT_REMOTE_STACK_STARTUP_TIMEOUT_MS;
+}
+
 export function resolveDefaultRemoteServerPort({
   localServerPort,
   targetIndex,
@@ -65,8 +73,7 @@ async function defaultWaitForProcess(child) {
 }
 
 async function defaultWaitForServerReady({ url, env = process.env, signal } = {}) {
-  const configured = Number.parseInt(String(env.HAPPIER_STACK_SERVER_READY_TIMEOUT_MS ?? ''), 10);
-  const timeoutMs = Number.isFinite(configured) && configured >= 1_000 ? configured : 120_000;
+  const timeoutMs = resolveRemoteServerReadyTimeoutMs(env);
   const deadline = Date.now() + timeoutMs;
   while (!signal?.aborted && Date.now() < deadline) {
     if ((await fetchHappierHealth(url)).ok) return;
@@ -137,12 +144,12 @@ async function prepareOpenSsh({ targets, mutagenDir, env }) {
   for (const executable of ['ssh', 'scp']) {
     await writeFile(
       join(opensshDir, executable),
-      `#!/bin/sh\nexec /usr/bin/${executable} -F ${shellQuote(configPath)} -o ControlMaster=no "$@"\n`,
+      `#!/bin/sh\nexec /usr/bin/${executable} -F ${shellQuote(configPath)} -o ControlMaster=no -o ControlPath=none "$@"\n`,
       { mode: 0o700 },
     );
   }
   return {
-    sshArgs: ['-F', configPath, '-o', 'ControlMaster=no'],
+    sshArgs: ['-F', configPath, '-o', 'ControlMaster=no', '-o', 'ControlPath=none'],
     mutagenEnv: { ...env, MUTAGEN_SSH_PATH: opensshDir },
   };
 }
@@ -542,8 +549,11 @@ export async function startStackDevTargets(
           tunnelsByTarget.set(target.name, tunnel);
         }
         if (!services.server) {
-          requireSuccessful(
-            await runProcess({
+          const readinessDeadline = Date.now() + resolveRemoteServerReadyTimeoutMs(env);
+          let readinessAttempt = 0;
+          let readinessResult;
+          do {
+            readinessResult = await runProcess({
               label: `remote:${target.name}`,
               command: 'ssh',
               args: [
@@ -554,7 +564,19 @@ export async function startStackDevTargets(
                 buildRemoteForwardProbeCommand(target, { remoteServerPort }),
               ],
               env: infraEnv,
-            }),
+            });
+            if (readinessResult?.code === 0 || tunnel.exitCode != null || Date.now() >= readinessDeadline) {
+              break;
+            }
+            readinessAttempt += 1;
+            const retryOutcome = await Promise.race([
+              waitForRetry({ attempt: readinessAttempt, delayMs: 5_000, target }).then(() => 'retry'),
+              closeRequested.then(() => 'close'),
+            ]);
+            if (retryOutcome === 'close' || closed) return null;
+          } while (!closed);
+          requireSuccessful(
+            readinessResult,
             `${target.name} reverse tunnel readiness`,
           );
         }