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

package/scripts/repo_local.mjs

@@ -1,16 +1,17 @@
 import { spawnSync } from 'node:child_process';
-import { createHash, randomBytes } from 'node:crypto';
-import { homedir } from 'node:os';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { scrubHappierStackEnv, STACK_WRAPPER_PRESERVE_KEYS } from './utils/env/scrub_env.mjs';
 import { applyStackActiveServerScopeEnv } from './utils/auth/stable_scope_id.mjs';
 import { ensureDepsInstalled } from './utils/proc/pm.mjs';
-import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { ensureEnvFileMutated } from './utils/env/env_file.mjs';
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
-import { resolveLocalServerPortForStack } from './utils/server/resolve_stack_server_port.mjs';
+import { selectLocalServerPortCandidateForStack } from './utils/server/resolve_stack_server_port.mjs';
+import { resolveEffectiveDbProviderTransition } from './utils/server/effective_db_provider.mjs';
+import { resolveExecutionHostController, runExecutionHostAdapter } from './utils/execution_host_adapter.mjs';
+import { resolveRepoStackIdentity, resolveStacksStorageRoot } from './utils/stack/repo_stack_identity.mjs';
 
 function shouldAutoInstallDepsForRepoLocalCommand(cmd) {
   const c = String(cmd ?? '').trim();
@@ -30,6 +31,12 @@ async function maybeAutoInstallRepoDeps({ repoRoot, cmd, env, autoInstallOverrid
   // Test hook: allow validating auto-install behavior without mutating the real repo checkout.
   const preflightRoot = String(preflightRootOverride ?? '').trim() || repoRoot;
 
+  // This wrapper owns only clean-checkout bootstrap. Once a dependency tree exists, the
+  // component startup owner performs the canonical freshness check after hstack is running.
+  // Repeating that admission here can hold the CLI publication lock before the TUI or stack
+  // lifecycle has even had an opportunity to preserve/adopt an incumbent runtime.
+  if (existsSync(join(preflightRoot, 'node_modules'))) return;
+
   await ensureDepsInstalled(preflightRoot, 'happier-monorepo', { quiet: false, env });
 }
 
@@ -81,43 +88,6 @@ function isPortWithinRange(port, base, range) {
   return p >= b && p < b + r;
 }
 
-function sanitizeStackNameToken(s) {
-  const raw = String(s ?? '').trim().toLowerCase();
-  const cleaned = raw.replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
-  return cleaned || 'repo';
-}
-
-function isHexToken(s, { minLen = 6 } = {}) {
-  const raw = String(s ?? '').trim().toLowerCase();
-  if (!raw || raw.length < minLen) return false;
-  return /^[a-f0-9]+$/.test(raw);
-}
-
-function resolveGitDir(repoRoot) {
-  try {
-    const gitPath = join(repoRoot, '.git');
-    if (!existsSync(gitPath)) return null;
-
-    // Common case: .git is a directory.
-    try {
-      const stat = readFileSync(gitPath, { encoding: 'utf-8' });
-      void stat;
-    } catch {
-      return gitPath;
-    }
-
-    // Worktree case: .git is a file like "gitdir: /path/to/actual/git/dir".
-    const raw = readFileSync(gitPath, 'utf-8').trim();
-    const m = raw.match(/^gitdir:\s*(.+)\s*$/i);
-    if (!m) return null;
-    const p = m[1].trim();
-    if (!p) return null;
-    return p.startsWith('/') ? p : join(repoRoot, p);
-  } catch {
-    return null;
-  }
-}
-
 function readTextFile(path) {
   try {
     if (!path || !existsSync(path)) return '';
@@ -137,15 +107,6 @@ function readEnvFileObject(path) {
   }
 }
 
-function writeTextFileBestEffort(path, contents) {
-  try {
-    if (!path) return;
-    writeFileSync(path, String(contents ?? ''), { encoding: 'utf-8' });
-  } catch {
-    // ignore
-  }
-}
-
 async function syncRepoLocalEnvFile({ envPath, managedEnv = {}, pruneKeys = [] } = {}) {
   const target = String(envPath ?? '').trim();
   if (!target) return;
@@ -154,74 +115,9 @@ async function syncRepoLocalEnvFile({ envPath, managedEnv = {}, pruneKeys = [] }
     .map(([k, v]) => ({ key: String(k ?? '').trim(), value: v == null ? '' : String(v) }))
     .filter((u) => u.key && u.value.trim() !== '');
 
-  // Preserve user keys: only upsert a small managed keyset, and prune specific stale managed keys.
-  if (updates.length) {
-    await ensureEnvFileUpdated({ envPath: target, updates });
-  }
   const removeKeys = Array.from(new Set((pruneKeys ?? []).map((k) => String(k ?? '').trim()).filter(Boolean)));
-  if (removeKeys.length) {
-    await ensureEnvFilePruned({ envPath: target, removeKeys });
-  }
-}
-
-function stacklessIdForRepo({ repoRoot, stacksStorageRoot, createIfMissing }) {
-  const oldHash = createHash('sha256').update(String(repoRoot)).digest('hex').slice(0, 10);
-  const base = sanitizeStackNameToken(repoRoot.split('/').filter(Boolean).at(-1));
-  const oldName = `repo-${base}-${oldHash}`;
-
-  const gitDir = resolveGitDir(repoRoot);
-  if (!gitDir) {
-    // Best-effort fallback when .git is unavailable (e.g. a tarball checkout).
-    // This keeps behavior stable for a given path without creating new local state.
-    return oldHash;
-  }
-
-  const idPath = gitDir ? join(gitDir, 'happier-stack-stackless-id') : null;
-  const existing = readTextFile(idPath);
-  if (isHexToken(existing, { minLen: 8 })) {
-    return existing.slice(0, 20);
-  }
-
-  // Back-compat: if the old stack dir exists, pin the id to the previous hash to keep ports/state stable.
-  try {
-    const oldDir = join(stacksStorageRoot, oldName);
-    if (existsSync(oldDir)) {
-      if (createIfMissing) writeTextFileBestEffort(idPath, oldHash);
-      return oldHash;
-    }
-  } catch {
-    // ignore
-  }
-
-  if (!createIfMissing) {
-    // Dry-run / read-only mode: do not create new local state.
-    return oldHash;
-  }
-
-  // Fresh repo-local stack: generate a persistent id under git metadata (so it survives repo moves).
-  const generated = randomBytes(8).toString('hex');
-  writeTextFileBestEffort(idPath, generated);
-  return generated;
-}
-
-function stacklessStackNameForRepo({ repoRoot, stacksStorageRoot, createIfMissing }) {
-  const base = sanitizeStackNameToken(repoRoot.split('/').filter(Boolean).at(-1));
-  const id = stacklessIdForRepo({ repoRoot, stacksStorageRoot, createIfMissing });
-  return `repo-${base}-${id.slice(0, 10)}`;
-}
-
-function expandHomePath(p) {
-  const s = String(p ?? '').trim();
-  if (!s) return '';
-  if (s === '~') return homedir();
-  if (s.startsWith('~/')) return join(homedir(), s.slice(2));
-  return s;
-}
-
-function resolveStacksStorageRoot(env) {
-  const raw = (env.HAPPIER_STACK_STORAGE_DIR ?? '').toString().trim();
-  if (raw) return expandHomePath(raw);
-  return join(homedir(), '.happier', 'stacks');
+  // Preserve user keys while applying the managed projection atomically.
+  await ensureEnvFileMutated({ envPath: target, updates, removeKeys });
 }
 
 function readRuntimeServerPort(runtimeStatePath) {
@@ -254,6 +150,34 @@ async function main() {
   const preflightOnly = String(process.env.HAPPIER_STACK_REPO_LOCAL_PREFLIGHT_ONLY ?? '').trim();
 
   const argvRaw = process.argv.slice(2);
+  const scriptsDir = dirname(fileURLToPath(import.meta.url)); // <repo>/apps/stack/scripts
+  const repoRoot = dirname(dirname(dirname(scriptsDir))); // <repo>
+  const invokedCwd =
+    (process.env.HAPPIER_STACK_INVOKED_CWD ?? '').toString().trim() ||
+    (process.env.INIT_CWD ?? '').toString().trim() ||
+    process.cwd();
+  const executionHostController = resolveExecutionHostController({ env: process.env });
+  if (executionHostController) {
+    const { stackName } = resolveRepoStackIdentity({
+      repoRoot,
+      stacksStorageRoot: resolveStacksStorageRoot(process.env),
+      createIfMissing: false,
+    });
+    const outcome = await runExecutionHostAdapter({
+      controllerEntrypoint: executionHostController,
+      localEntrypoint: fileURLToPath(import.meta.url),
+      stackName,
+      argv: argvRaw,
+      cwd: invokedCwd,
+      env: process.env,
+    });
+    if (outcome.signal) {
+      process.kill(process.pid, outcome.signal);
+      return;
+    }
+    process.exit(outcome.exitCode ?? 1);
+  }
+
   const firstArg = argvRaw[0];
   const showWrapperHelp =
     argvRaw.length === 0 || firstArg === 'help' || firstArg === '--help' || firstArg === '-h';
@@ -267,25 +191,18 @@ async function main() {
 
   // Root script convenience:
   // `yarn tui` should work from monorepo checkout without additional args.
-  // Default to `hstack tui dev` while preserving explicit forwarded args.
+  // Default to `hstack tui dev --mobile` while preserving explicit forwarded args.
   let argv = argvWithoutDryRun;
   if (argvWithoutDryRun[0] === 'tui') {
     const forwarded = argvWithoutDryRun.slice(1);
     if (forwarded.length === 0) {
-      argv = ['tui', 'dev', ...forwarded];
+      argv = ['tui', 'dev', '--mobile'];
     }
   }
   const wantsTuiMobile = argv[0] === 'tui' && argv.some((arg) => String(arg ?? '').trim() === '--mobile' || String(arg ?? '').trim() === '--with-mobile');
 
-  const scriptsDir = dirname(fileURLToPath(import.meta.url)); // <repo>/apps/stack/scripts
-  const repoRoot = dirname(dirname(dirname(scriptsDir))); // <repo>
   const hstackBin = join(repoRoot, 'apps', 'stack', 'bin', 'hstack.mjs');
 
-  const invokedCwd =
-    (process.env.HAPPIER_STACK_INVOKED_CWD ?? '').toString().trim() ||
-    (process.env.INIT_CWD ?? '').toString().trim() ||
-    process.cwd();
-
   const subcommand = String(argv[0] ?? '').trim();
   const isStop = subcommand === 'stop';
   const isStackManagement =
@@ -295,7 +212,7 @@ async function main() {
     subcommand === 'worktrees';
 
   const stacksStorageRoot = resolveStacksStorageRoot(process.env);
-  const stacklessName = stacklessStackNameForRepo({
+  const { stackName: stacklessName } = resolveRepoStackIdentity({
     repoRoot,
     stacksStorageRoot,
     createIfMissing: !dryRun && !isStop,
@@ -418,7 +335,37 @@ async function main() {
       // ignore (best-effort)
     }
 
-	    const serverComponent = (effectiveEnv.HAPPIER_STACK_SERVER_COMPONENT ?? 'happier-server-light').toString().trim() || 'happier-server-light';
+	    const previousServerComponent = (existingStacklessEnv.HAPPIER_STACK_SERVER_COMPONENT ?? 'happier-server-light').toString().trim() || 'happier-server-light';
+	    const serverComponent = (
+	      effectiveEnv.HAPPIER_STACK_SERVER_COMPONENT ??
+	      existingStacklessEnv.HAPPIER_STACK_SERVER_COMPONENT ??
+	      'happier-server-light'
+	    ).toString().trim() || 'happier-server-light';
+	    const dbTransition = resolveEffectiveDbProviderTransition({
+	      previousServerComponentName: previousServerComponent,
+	      nextServerComponentName: serverComponent,
+	      env: existingStacklessEnv,
+	    });
+	    if (!dbTransition.ok) {
+	      if (dbTransition.reason === 'missing_mysql_database_url') {
+	        throw new Error('[repo-local] mysql requires an explicit DATABASE_URL');
+	      }
+	      if (dbTransition.reason === 'missing_postgres_database_url') {
+	        throw new Error('[repo-local] postgres requires an explicit DATABASE_URL with the light preset');
+	      }
+	      if (dbTransition.reason === 'invalid_postgres_database_url') {
+	        throw new Error('[repo-local] postgres DATABASE_URL must use postgres:// or postgresql://');
+	      }
+	      throw new Error(`[repo-local] invalid DB provider for ${serverComponent}: ${dbTransition.input ?? dbTransition.reason}`);
+	    }
+	    effectiveEnv.HAPPIER_STACK_SERVER_COMPONENT = serverComponent;
+	    effectiveEnv.HAPPIER_DB_PROVIDER = dbTransition.provider;
+	    effectiveEnv.HAPPY_DB_PROVIDER = dbTransition.provider;
+	    if (dbTransition.databaseUrl) {
+	      effectiveEnv.DATABASE_URL = dbTransition.databaseUrl;
+	    } else {
+	      delete effectiveEnv.DATABASE_URL;
+	    }
 	    const serverBase = effectiveEnv.HAPPIER_STACK_SERVER_PORT_BASE;
 	    const serverRange = effectiveEnv.HAPPIER_STACK_SERVER_PORT_RANGE;
 	    const expoBase = effectiveEnv.HAPPIER_STACK_EXPO_DEV_PORT_BASE;
@@ -432,7 +379,7 @@ async function main() {
 	      if (runtimeServerPort && isPortWithinRange(runtimeServerPort, serverBase, serverRange)) {
 	        persistedServerPort = runtimeServerPort;
 	      } else {
-	        persistedServerPort = await resolveLocalServerPortForStack({
+		        persistedServerPort = await selectLocalServerPortCandidateForStack({
 	          env: {
 	            ...effectiveEnv,
 	            HAPPIER_STACK_SERVER_PORT_BASE: (effectiveEnv.HAPPIER_STACK_SERVER_PORT_BASE ?? '52005').toString(),
@@ -450,6 +397,9 @@ async function main() {
 	    // If a stale pinned port exists in the stackless env file but it doesn't match the configured stable range,
 	    // prune it so dev/start can pick a stable high port again.
 	    const pruneKeys = [];
+    if (dbTransition.removeDatabaseUrl) {
+      pruneKeys.push('DATABASE_URL');
+    }
     if (
       existingPinnedServerPort &&
       existingPinnedServerPort < 5000 &&
@@ -464,6 +414,8 @@ async function main() {
       HAPPIER_STACK_STACK: stacklessName,
       HAPPIER_STACK_REPO_DIR: repoRoot,
       HAPPIER_STACK_SERVER_COMPONENT: serverComponent,
+      HAPPIER_DB_PROVIDER: dbTransition.provider,
+      ...(dbTransition.provider === 'mysql' ? { DATABASE_URL: dbTransition.databaseUrl } : {}),
       HAPPIER_STACK_CLI_HOME_DIR: stacklessCliHomeDir,
       HAPPIER_STACK_SERVER_PORT_BASE: effectiveEnv.HAPPIER_STACK_SERVER_PORT_BASE,
       HAPPIER_STACK_SERVER_PORT_RANGE: effectiveEnv.HAPPIER_STACK_SERVER_PORT_RANGE,

package/scripts/repo_local_effective_db_provider.test.mjs

@@ -0,0 +1,161 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { runNodeCapture } from './testkit/core/run_node_capture.mjs';
+import { resolveRepoStackIdentity } from './utils/stack/repo_stack_identity.mjs';
+
+const repoRoot = join(import.meta.dirname, '..', '..', '..');
+const repoLocalScript = join(import.meta.dirname, 'repo_local.mjs');
+
+async function createFixture(t, lines) {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-repo-local-provider-'));
+  t.after(async () => rm(root, { recursive: true, force: true }));
+  const storageDir = join(root, 'storage');
+  const { stackBaseDir: stackDir } = resolveRepoStackIdentity({
+    repoRoot,
+    stacksStorageRoot: storageDir,
+  });
+  const envPath = join(stackDir, 'env');
+  await mkdir(stackDir, { recursive: true });
+  await writeFile(envPath, [...lines, ''].join('\n'), 'utf8');
+
+  const env = { ...process.env };
+  for (const key of ['HAPPIER_STACK_SERVER_COMPONENT', 'HAPPIER_DB_PROVIDER', 'HAPPY_DB_PROVIDER', 'DATABASE_URL', 'HAPPIER_STACK_ENV_FILE', 'HAPPIER_STACK_STACK']) {
+    delete env[key];
+  }
+  Object.assign(env, {
+    HAPPIER_STACK_STORAGE_DIR: storageDir,
+    HAPPIER_STACK_HOME_DIR: join(root, 'stack-home'),
+    HAPPIER_STACK_REPO_LOCAL_AUTO_INSTALL: '0',
+    HAPPIER_STACK_REPO_LOCAL_PREFLIGHT_ONLY: '1',
+  });
+  return { env, envPath, root };
+}
+
+async function runRepoLocal(fixture) {
+  return await runNodeCapture([repoLocalScript, 'dev'], { cwd: repoRoot, env: fixture.env });
+}
+
+async function runRepoLocalCapturingSpawn(fixture) {
+  const markerPath = join(fixture.root, 'spawn-env.json');
+  const loaderPath = join(fixture.root, 'loader.mjs');
+  const registerPath = join(fixture.root, 'register.mjs');
+  const childProcessStub = `data:text/javascript,${encodeURIComponent(`
+import { writeFileSync } from 'node:fs';
+export function spawnSync(_command, _args, options = {}) {
+  const env = options.env ?? {};
+  writeFileSync(${JSON.stringify(markerPath)}, JSON.stringify({
+    component: env.HAPPIER_STACK_SERVER_COMPONENT ?? null,
+    primary: env.HAPPIER_DB_PROVIDER ?? null,
+    legacy: env.HAPPY_DB_PROVIDER ?? null,
+    databaseUrl: env.DATABASE_URL ?? null,
+  }), 'utf8');
+  return { status: 0 };
+}
+`)}`;
+  await writeFile(loaderPath, `
+export async function resolve(specifier, context, defaultResolve) {
+  if (specifier === 'node:child_process' && context.parentURL?.endsWith('/scripts/repo_local.mjs')) {
+    return { url: ${JSON.stringify(childProcessStub)}, shortCircuit: true };
+  }
+  return defaultResolve(specifier, context, defaultResolve);
+}
+`, 'utf8');
+  await writeFile(registerPath, [
+    `import { register } from 'node:module';`,
+    `register(${JSON.stringify(pathToFileURL(loaderPath).href)}, import.meta.url);`,
+    '',
+  ].join('\n'), 'utf8');
+  const env = { ...fixture.env };
+  delete env.HAPPIER_STACK_REPO_LOCAL_PREFLIGHT_ONLY;
+  const result = await runNodeCapture(['--import', registerPath, repoLocalScript, 'dev'], { cwd: repoRoot, env });
+  return { result, captured: JSON.parse(await readFile(markerPath, 'utf8')) };
+}
+
+test('repo-local writer preserves compatible PGlite and prunes light DATABASE_URL', async (t) => {
+  const fixture = await createFixture(t, [
+    'HAPPIER_STACK_SERVER_COMPONENT=happier-server-light',
+    'HAPPIER_DB_PROVIDER=pglite',
+    'DATABASE_URL=mysql://stale-shell/db',
+  ]);
+  const result = await runRepoLocal(fixture);
+  assert.equal(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  const raw = await readFile(fixture.envPath, 'utf8');
+  assert.match(raw, /^HAPPIER_DB_PROVIDER=pglite$/m);
+  assert.doesNotMatch(raw, /^DATABASE_URL=/m);
+});
+
+test('repo-local writer preserves compatible MySQL provider and DATABASE_URL', async (t) => {
+  const databaseUrl = 'mysql://operator:secret@db.example.test:3306/happier';
+  const fixture = await createFixture(t, [
+    'HAPPIER_STACK_SERVER_COMPONENT=happier-server',
+    'HAPPIER_DB_PROVIDER=mysql',
+    `DATABASE_URL=${databaseUrl}`,
+  ]);
+  const result = await runRepoLocal(fixture);
+  assert.equal(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  const raw = await readFile(fixture.envPath, 'utf8');
+  assert.match(raw, /^HAPPIER_STACK_SERVER_COMPONENT=happier-server$/m);
+  assert.match(raw, /^HAPPIER_DB_PROVIDER=mysql$/m);
+  assert.match(raw, new RegExp(`^DATABASE_URL=${databaseUrl}$`, 'm'));
+});
+
+test('repo-local writer fails closed on corrupt explicit provider metadata', async (t) => {
+  const fixture = await createFixture(t, [
+    'HAPPIER_STACK_SERVER_COMPONENT=happier-server-light',
+    'HAPPIER_DB_PROVIDER=unsupported',
+  ]);
+  const before = await readFile(fixture.envPath, 'utf8');
+  const result = await runRepoLocal(fixture);
+  assert.notEqual(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  assert.match(`${result.stdout}\n${result.stderr}`, /invalid DB provider/i);
+  assert.equal(await readFile(fixture.envPath, 'utf8'), before);
+});
+
+test('repo-local child receives canonical persisted authority instead of exported shell provider state', async (t) => {
+  const fixture = await createFixture(t, [
+    'HAPPIER_STACK_SERVER_COMPONENT=happier-server-light',
+    'HAPPIER_DB_PROVIDER=sqlite',
+  ]);
+  Object.assign(fixture.env, {
+    HAPPIER_DB_PROVIDER: 'mysql',
+    HAPPY_DB_PROVIDER: 'mysql',
+    DATABASE_URL: 'mysql://shell-override/db',
+  });
+
+  const { result, captured } = await runRepoLocalCapturingSpawn(fixture);
+  assert.equal(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  assert.deepEqual(captured, {
+    component: 'happier-server-light',
+    primary: 'sqlite',
+    legacy: 'sqlite',
+    databaseUrl: null,
+  });
+});
+
+test('repo-local child retains compatible persisted external Postgres authority', async (t) => {
+  const databaseUrl = 'postgresql://operator:secret@db.example.test:5432/happier';
+  const fixture = await createFixture(t, [
+    'HAPPIER_STACK_SERVER_COMPONENT=happier-server',
+    'HAPPIER_DB_PROVIDER=postgres',
+    `DATABASE_URL=${databaseUrl}`,
+  ]);
+  Object.assign(fixture.env, {
+    HAPPIER_DB_PROVIDER: 'mysql',
+    HAPPY_DB_PROVIDER: 'mysql',
+    DATABASE_URL: 'mysql://shell-override/db',
+  });
+
+  const { result, captured } = await runRepoLocalCapturingSpawn(fixture);
+  assert.equal(result.code, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  assert.deepEqual(captured, {
+    component: 'happier-server',
+    primary: 'postgres',
+    legacy: 'postgres',
+    databaseUrl,
+  });
+});

package/scripts/repo_local_wrapper.test.mjs

@@ -86,7 +86,7 @@ test('repo-local wrapper dry-run prints hstack invocation with repo-local env',
   assert.ok(String(data.env.HAPPIER_STACK_INVOKED_CWD ?? '').trim() !== '');
 });
 
-test('repo-local wrapper defaults `tui` to `tui dev` when no forwarded args are provided', async () => {
+test('repo-local wrapper defaults `tui` to mobile-capable `tui dev` when no forwarded args are provided', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
   const packageRoot = dirname(scriptsDir); // apps/stack
   const repoRoot = dirname(dirname(packageRoot)); // repo root
@@ -104,6 +104,41 @@ test('repo-local wrapper defaults `tui` to `tui dev` when no forwarded args are
   assert.equal(data.ok, true);
   assert.equal(data.args[1], 'tui');
   assert.equal(data.args[2], 'dev');
+  assert.equal(data.args[3], '--mobile');
+});
+
+test('repo-local execution-host adapter receives the exact original argv before wrapper normalization', { skip: process.platform !== 'darwin' }, async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(scriptsDir);
+  const repoRoot = dirname(dirname(packageRoot));
+  const root = mkdtempSync(join(tmpdir(), 'happier-repo-local-controller-'));
+  const controller = join(root, 'controller.mjs');
+  const stackHome = join(root, 'stack-home');
+  mkdirSync(stackHome, { recursive: true });
+  writeFileSync(controller, 'process.stdout.write(JSON.stringify(process.argv.slice(2)));\n');
+  writeFileSync(join(stackHome, 'execution-host.json'), JSON.stringify({
+    version: 2,
+    controllerEntrypoint: controller,
+  }));
+  try {
+    const result = await runNode(
+      [join(packageRoot, 'scripts', 'repo_local.mjs'), 'tui', '--dry-run'],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, HAPPIER_STACK_HOME_DIR: stackHome },
+      },
+    );
+    assert.equal(result.code, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), [
+      '--workspace-id=0.2',
+      `--local-entrypoint=${join(packageRoot, 'scripts', 'repo_local.mjs')}`,
+      '--',
+      'tui',
+      '--dry-run',
+    ]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
 });
 
 test('repo-local wrapper preserves explicit `tui` forwarded args', async () => {
@@ -311,6 +346,45 @@ test('repo-local wrapper auto-installs deps when node_modules are missing', asyn
   }
 });
 
+test('repo-local wrapper leaves existing dependency freshness admission to the stack owner', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(scriptsDir);
+  const repoRoot = dirname(dirname(packageRoot));
+  const preflightRoot = mkdtempSync(join(tmpdir(), 'happier-repo-local-existing-deps-'));
+  try {
+    writeFileSync(join(preflightRoot, 'package.json'), JSON.stringify({ name: 'tmp', private: true }));
+    mkdirSync(join(preflightRoot, 'node_modules'), { recursive: true });
+    const binDir = join(preflightRoot, 'bin');
+    mkdirSync(binDir, { recursive: true });
+    const logPath = join(preflightRoot, 'yarn.log');
+    writeFileSync(logPath, '');
+    const yarnBin = join(binDir, 'yarn');
+    writeFileSync(
+      yarnBin,
+      '#!/usr/bin/env node\n' +
+        "import { appendFileSync } from 'node:fs';\n" +
+        "appendFileSync(process.env.YARN_LOG, process.argv.slice(2).join(' ') + '\\n');\n",
+    );
+    chmodSync(yarnBin, 0o755);
+
+    const res = await runNode([join(packageRoot, 'scripts', 'repo_local.mjs'), 'dev'], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        PATH: `${binDir}:${process.env.PATH ?? ''}`,
+        YARN_LOG: logPath,
+        HAPPIER_STACK_REPO_LOCAL_PREFLIGHT_ROOT: preflightRoot,
+        HAPPIER_STACK_REPO_LOCAL_PREFLIGHT_ONLY: '1',
+      },
+    });
+
+    assert.equal(res.code, 0, res.stderr || res.stdout);
+    assert.equal(readFileSync(logPath, 'utf-8'), '');
+  } finally {
+    rmSync(preflightRoot, { recursive: true, force: true });
+  }
+});
+
 test('repo-local wrapper preserves user-defined env keys while managing stack-owned keys', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
   const packageRoot = dirname(scriptsDir); // apps/stack

package/scripts/review_pr.mjs

@@ -19,7 +19,7 @@ import { bold, cyan, dim } from './utils/ui/ansi.mjs';
 import { expandHome } from './utils/paths/canonical_home.mjs';
 import { fastForwardBranchToRemote } from './utils/git/fast_forward_to_remote.mjs';
 import { resolveDefaultRemoteBranch } from './utils/git/default_branch.mjs';
-import { shouldRunYarnInstall } from './utils/worktrees/yarn_install_guard.mjs';
+import { withYarnInstallGuard } from './utils/worktrees/yarn_install_guard.mjs';
 import { run } from './utils/proc/proc.mjs';
 import { applyStackCacheEnv } from './utils/proc/pm.mjs';
  
@@ -469,10 +469,7 @@ async function main() {
           const depsLabel = 'warm cached workspace deps (yarn)';
           updateSteps.start(depsLabel);
           try {
-            const needs = await shouldRunYarnInstall({ installDir: mainDir, componentDir: mainDir });
-            if (!needs) {
-              updateSteps.stop('✓', depsLabel);
-            } else {
+            await withYarnInstallGuard({ installDir: mainDir, componentDir: mainDir }, async () => {
               const pmCacheBaseDir = resolvePmCacheBaseDirFromWorkspaceDir(workspaceCache.workspaceDir);
               const env = await applyStackCacheEnv({
                 ...process.env,
@@ -482,26 +479,20 @@ async function main() {
               const quiet = verbosity === 0 && !json;
               try {
                 await run('yarn', ['install', '--frozen-lockfile'], { cwd: mainDir, env, stdio: quiet ? 'ignore' : 'inherit' });
-                updateSteps.stop('✓', depsLabel);
               } catch (e) {
                 // Re-run once with logs for diagnosis, then warn and continue.
                 if (quiet) {
                   try {
                     await run('yarn', ['install', '--frozen-lockfile'], { cwd: mainDir, env, stdio: 'inherit' });
-                  } catch {
-                    // ignore
+                    return;
+                  } catch (retryError) {
+                    throw retryError;
                   }
                 }
-                updateSteps.stop('!', depsLabel);
-                if (!json) {
-                  // eslint-disable-next-line no-console
-                  console.warn(
-                    `[review-pr] warning: failed to warm cached workspace deps (${mainDir}).\n` +
-                      `${e instanceof Error ? e.message : String(e)}`
-                  );
-                }
+                throw e;
               }
-            }
+            });
+            updateSteps.stop('✓', depsLabel);
           } catch (e) {
             updateSteps.stop('!', depsLabel);
             if (!json) {

package/scripts/review_pr.warm_base_deps.test.mjs

@@ -69,6 +69,10 @@ export function spawn(cmd, args, options = {}) {
   queueMicrotask(() => child.emit('close', 0, null));
   return child;
 }
+
+export function spawnSync() {
+  throw new Error('unexpected spawnSync call in review-pr fixture');
+}
 `),
     './utils/cli/prereqs.mjs': toDataUrl(`
 export async function assertCliPrereqs() {}
@@ -84,7 +88,10 @@ export async function resolveDefaultRemoteBranch() {
 }
 `),
     './utils/worktrees/yarn_install_guard.mjs': toDataUrl(`
-export async function shouldRunYarnInstall() { return true; }
+export async function withYarnInstallGuard(_options, install) {
+  await install();
+  return { refreshed: true, reason: 'stale-inputs' };
+}
 `),
     './utils/proc/pm.mjs': toDataUrl(`
 export async function applyStackCacheEnv(env) { return env; }

package/scripts/review_pr.workspace_cache.test.mjs

@@ -66,6 +66,14 @@ export function spawn(cmd, args, options = {}) {
   queueMicrotask(() => child.emit('close', 0, null));
   return child;
 }
+
+export function spawnSync() {
+  throw new Error('unexpected spawnSync call in review-pr fixture');
+}
+
+export function execFileSync() {
+  throw new Error('unexpected execFileSync call in review-pr fixture');
+}
 `),
     './utils/cli/prereqs.mjs': toDataUrl(`
 export async function assertCliPrereqs() {}
@@ -145,6 +153,14 @@ export function spawn(cmd, args, options = {}) {
   queueMicrotask(() => child.emit('close', 0, null));
   return child;
 }
+
+export function spawnSync() {
+  throw new Error('unexpected spawnSync call in review-pr fixture');
+}
+
+export function execFileSync() {
+  throw new Error('unexpected execFileSync call in review-pr fixture');
+}
 `),
     './utils/cli/prereqs.mjs': toDataUrl(`
 export async function assertCliPrereqs() {}