@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/utils/tui/pane_routing.mjs

@@ -0,0 +1,12 @@
+export function resolveTuiPaneIdForLabel(label) {
+  const normalized = String(label ?? '').trim().toLowerCase();
+  if (normalized === 'tauri') return 'tauri';
+  if (normalized.includes('server')) return 'server';
+  if (normalized === 'ui') return 'expo';
+  if (normalized === 'mobile') return 'expo';
+  if (normalized === 'expo') return 'expo';
+  if (normalized.includes('daemon')) return 'daemon';
+  if (normalized === 'stack') return 'stacklog';
+  if (normalized === 'local') return 'local';
+  return 'local';
+}

package/scripts/utils/tui/pane_routing.test.mjs

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveTuiPaneIdForLabel } from './pane_routing.mjs';
+
+test('resolveTuiPaneIdForLabel routes tauri logs to the tauri pane', () => {
+  assert.equal(resolveTuiPaneIdForLabel('tauri'), 'tauri');
+});
+
+test('resolveTuiPaneIdForLabel preserves the existing pane routing labels', () => {
+  assert.equal(resolveTuiPaneIdForLabel('server'), 'server');
+  assert.equal(resolveTuiPaneIdForLabel('ui'), 'expo');
+  assert.equal(resolveTuiPaneIdForLabel('mobile'), 'expo');
+  assert.equal(resolveTuiPaneIdForLabel('daemon'), 'daemon');
+  assert.equal(resolveTuiPaneIdForLabel('stack'), 'stacklog');
+  assert.equal(resolveTuiPaneIdForLabel('local'), 'local');
+  assert.equal(resolveTuiPaneIdForLabel('unknown'), 'local');
+});

package/scripts/utils/tui/stdin_error_guard.mjs

@@ -0,0 +1,47 @@
+function normalizeErrCode(err) {
+  const code = err && typeof err === 'object' ? err.code : null;
+  return typeof code === 'string' ? code : '';
+}
+
+/**
+ * Guard against `process.stdin` emitting an 'error' event (notably `read EIO` on TTY)
+ * during restart/shutdown transitions. Without a listener, Node treats it as unhandled
+ * and crashes the TUI.
+ */
+export function installTuiStdinErrorGuard({ stdin, onError } = {}) {
+  const s = stdin;
+  if (!s || typeof s.on !== 'function') {
+    return { uninstall() {} };
+  }
+
+  const cb = typeof onError === 'function' ? onError : null;
+  const handler = (err) => {
+    // Never throw from here: this is running inside an 'error' event.
+    try {
+      cb?.(err);
+    } catch {
+      // ignore
+    }
+
+    // Swallow all stdin read errors. In practice this is most often:
+    // - darwin/linux: Error: read EIO
+    // When it happens during a restart, we prefer keeping the TUI alive.
+    void normalizeErrCode(err);
+  };
+
+  try {
+    s.on('error', handler);
+  } catch {
+    return { uninstall() {} };
+  }
+
+  return {
+    uninstall() {
+      try {
+        s.off?.('error', handler);
+      } catch {
+        // ignore
+      }
+    },
+  };
+}

package/scripts/utils/tui/stdin_error_guard.test.mjs

@@ -0,0 +1,17 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+
+import { installTuiStdinErrorGuard } from './stdin_error_guard.mjs';
+
+test('installTuiStdinErrorGuard prevents unhandled error event crashes', () => {
+  const stdin = new EventEmitter();
+  const err = Object.assign(new Error('read EIO'), { code: 'EIO', errno: -5, syscall: 'read' });
+
+  assert.throws(() => stdin.emit('error', err));
+
+  const guard = installTuiStdinErrorGuard({ stdin });
+  assert.doesNotThrow(() => stdin.emit('error', err));
+
+  guard.uninstall();
+});

package/scripts/utils/tui/tauri_mode.mjs

@@ -0,0 +1,61 @@
+import { isTuiStartLikeForwardedArgs } from './args.mjs';
+import { buildTauriRuntimeEnv } from '../dev/tauri_dev.mjs';
+import { join } from 'node:path';
+import { getRepoDir } from '../paths/paths.mjs';
+
+export function buildTuiChildArgs({ forwardedArgs, withTauri } = {}) {
+  const args = Array.isArray(forwardedArgs) ? forwardedArgs.map((arg) => String(arg ?? '')).filter(Boolean) : [];
+  if (!withTauri) {
+    return args.length > 0 ? args : ['dev'];
+  }
+
+  const childArgs = args.length > 0 ? args : ['dev'];
+  if (childArgs.includes('--no-browser')) {
+    return childArgs;
+  }
+  return [...childArgs, '--no-browser'];
+}
+
+export function shouldStartTauriPane(forwardedArgs) {
+  if (!isTuiStartLikeForwardedArgs(forwardedArgs)) {
+    return false;
+  }
+
+  const args = Array.isArray(forwardedArgs) ? forwardedArgs : [];
+  const first = String(args[0] ?? '').trim();
+  if (first === 'dev') return true;
+
+  const stackIdx = args.indexOf('stack');
+  if (stackIdx < 0) return false;
+  return String(args[stackIdx + 1] ?? '').trim() === 'dev';
+}
+
+export function resolveTauriPaneCwd({ rootDir, env = process.env } = {}) {
+  return getRepoDir(rootDir, env);
+}
+
+export function resolveTauriPaneInvocation({ rootDir, env = process.env } = {}) {
+  const cwd = resolveTauriPaneCwd({ rootDir, env });
+  return {
+    command: process.execPath,
+    args: [join(cwd, 'apps', 'stack', 'scripts', 'tauri_dev.mjs')],
+    cwd,
+  };
+}
+
+export function buildTauriPaneEnv({ env = process.env, resolveUserHomeDir } = {}) {
+  return {
+    ...buildTauriRuntimeEnv({ env, resolveUserHomeDir }),
+    HAPPIER_STACK_TUI: '1',
+    COREPACK_ENABLE_AUTO_PIN: '0',
+    COREPACK_ENABLE_STRICT: '0',
+  };
+}
+
+export function resolveTauriPaneSpawnConfig({ rootDir, env = process.env, resolveUserHomeDir } = {}) {
+  const tauriEnv = buildTauriPaneEnv({ env, resolveUserHomeDir });
+  return {
+    invocation: resolveTauriPaneInvocation({ rootDir, env: tauriEnv }),
+    env: tauriEnv,
+  };
+}

package/scripts/utils/tui/tauri_mode.test.mjs

@@ -0,0 +1,109 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveTauriPaneSpawnConfig } from './tauri_mode.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const repoRootDir = resolve(join(__dirname, '../../../../..'));
+const stackRootDir = join(repoRootDir, 'apps', 'stack');
+
+function splitPathEntries(pathValue) {
+  return String(pathValue ?? '')
+    .split(process.platform === 'win32' ? ';' : ':')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+test('resolveTauriPaneSpawnConfig builds a Tauri env with cargo available even when HOME is stack-isolated', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-pane-realhome-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-pane-isolatedhome-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const { invocation, env } = resolveTauriPaneSpawnConfig({
+    rootDir: stackRootDir,
+    env: {
+      PATH: '/usr/bin:/bin',
+      HOME: isolatedHome,
+      USERPROFILE: isolatedHome,
+    },
+    resolveUserHomeDir: () => realHome,
+  });
+
+  assert.equal(invocation.command, process.execPath);
+  assert.equal(invocation.args?.[0], join(repoRootDir, 'apps', 'stack', 'scripts', 'tauri_dev.mjs'));
+  assert.equal(invocation.cwd, repoRootDir);
+
+  const escapedCargoBinDir = cargoBinDir.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  assert.match(String(env?.PATH ?? ''), new RegExp(`^${escapedCargoBinDir}`));
+  const entries = splitPathEntries(env.PATH);
+  assert.ok(entries.includes('/usr/bin'));
+  assert.ok(entries.includes('/bin'));
+  assert.equal(env.CARGO, cargoBinary);
+  assert.equal(env.HAPPIER_STACK_TUI, '1');
+});
+
+test('resolveTauriPaneSpawnConfig exports rustup homes for the real user cargo toolchain', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-pane-rustup-home-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-pane-rustup-isolated-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const { env } = resolveTauriPaneSpawnConfig({
+    rootDir: stackRootDir,
+    env: {
+      PATH: '/usr/bin:/bin',
+      HOME: isolatedHome,
+      USERPROFILE: isolatedHome,
+    },
+    resolveUserHomeDir: () => realHome,
+  });
+
+  assert.equal(env.CARGO_HOME, `${realHome}/.cargo`);
+  assert.equal(env.RUSTUP_HOME, `${realHome}/.rustup`);
+  assert.equal(env.HOME, realHome);
+  assert.equal(env.USERPROFILE, realHome);
+});
+
+test('resolveTauriPaneSpawnConfig preserves the host PATH while prepending cargo and keeping stack PATH entries', async () => {
+  const realHome = await mkdir(`${tmpdir()}/happier-tauri-pane-host-path-home-${Date.now()}`, { recursive: true });
+  const isolatedHome = await mkdir(`${tmpdir()}/happier-tauri-pane-host-path-isolated-${Date.now()}`, { recursive: true });
+  const cargoBinDir = `${realHome}/.cargo/bin`;
+  await mkdir(cargoBinDir, { recursive: true });
+  const cargoBinary = `${cargoBinDir}/${process.platform === 'win32' ? 'cargo.exe' : 'cargo'}`;
+  await writeFile(cargoBinary, '#!/bin/sh\nexit 0\n', 'utf-8');
+  await chmod(cargoBinary, 0o755);
+
+  const originalPath = process.env.PATH;
+  process.env.PATH = `/host/bin${process.platform === 'win32' ? ';' : ':'}/usr/bin`;
+  try {
+    const { env } = resolveTauriPaneSpawnConfig({
+      rootDir: stackRootDir,
+      env: {
+        PATH: '/stack/bin',
+        HOME: isolatedHome,
+        USERPROFILE: isolatedHome,
+      },
+      resolveUserHomeDir: () => realHome,
+    });
+
+    const entries = splitPathEntries(env.PATH);
+    assert.equal(entries[0], cargoBinDir);
+    assert.equal(entries[1], dirname(process.execPath));
+    assert.ok(entries.includes('/stack/bin'));
+    assert.ok(entries.includes('/host/bin'));
+    assert.ok(entries.includes('/usr/bin'));
+  } finally {
+    process.env.PATH = originalPath;
+  }
+});

package/scripts/utils/ui/ui_export_env.mjs

@@ -8,7 +8,9 @@ export function buildStackWebExportEnv({ baseEnv } = {}) {
   env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT = 'stack';
 
   // Leave empty so the web bundle uses window.location.origin at runtime.
+  env.EXPO_PUBLIC_HAPPIER_SERVER_URL = '';
   env.EXPO_PUBLIC_HAPPY_SERVER_URL = '';
+  env.EXPO_PUBLIC_SERVER_URL = env.EXPO_PUBLIC_HAPPIER_SERVER_URL;
 
   return env;
 }
@@ -21,9 +23,9 @@ export function buildStackTauriExportEnv({ baseEnv, tauriServerUrl } = {}) {
   env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT = 'stack';
 
   // In Tauri, window.location.origin is a tauri:// origin, so hardcode the API base.
-  env.EXPO_PUBLIC_HAPPY_SERVER_URL = String(tauriServerUrl || '').trim();
-  env.EXPO_PUBLIC_SERVER_URL = env.EXPO_PUBLIC_HAPPY_SERVER_URL;
+  env.EXPO_PUBLIC_HAPPIER_SERVER_URL = String(tauriServerUrl || '').trim();
+  env.EXPO_PUBLIC_HAPPY_SERVER_URL = env.EXPO_PUBLIC_HAPPIER_SERVER_URL;
+  env.EXPO_PUBLIC_SERVER_URL = env.EXPO_PUBLIC_HAPPIER_SERVER_URL;
 
   return env;
 }
-

package/scripts/utils/ui/ui_export_env.test.mjs

@@ -9,6 +9,7 @@ test('buildStackWebExportEnv forces stack server context and leaves server URL e
   assert.equal(env.NODE_ENV, 'production');
   assert.equal(env.EXPO_PUBLIC_DEBUG, '0');
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT, 'stack');
+  assert.equal(env.EXPO_PUBLIC_HAPPIER_SERVER_URL, '');
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_URL, '');
 });
 
@@ -19,7 +20,7 @@ test('buildStackTauriExportEnv forces stack server context and hardcodes API bas
   assert.equal(env.NODE_ENV, 'production');
   assert.equal(env.EXPO_PUBLIC_DEBUG, '0');
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT, 'stack');
+  assert.equal(env.EXPO_PUBLIC_HAPPIER_SERVER_URL, tauriServerUrl);
   assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_URL, tauriServerUrl);
   assert.equal(env.EXPO_PUBLIC_SERVER_URL, tauriServerUrl);
 });
-

package/scripts/utils/worktrees/reflink_copy_dir.mjs

@@ -0,0 +1,35 @@
+import { runCapture } from '../proc/proc.mjs';
+
+function trim(s) {
+  return String(s ?? '').trim();
+}
+
+export async function reflinkCopyDir({ srcDir, destDir }) {
+  const src = trim(srcDir);
+  const dest = trim(destDir);
+  if (!src || !dest) return { ok: false, reason: 'missing-path' };
+
+  // Attempt a copy-on-write clone of a directory tree.
+  // If the underlying filesystem doesn't support it, fail closed so callers can fall back.
+  const cmd = 'cp';
+  const args = (() => {
+    if (process.platform === 'darwin') {
+      // -c: clonefile(2) (APFS CoW), -R: recursive
+      return ['-cR', src, dest];
+    }
+    if (process.platform === 'linux') {
+      // --reflink=always fails if CoW isn't supported; -a preserves perms/symlinks.
+      return ['-a', '--reflink=always', src, dest];
+    }
+    return null;
+  })();
+
+  if (!args) return { ok: false, reason: 'unsupported-platform' };
+
+  try {
+    await runCapture(cmd, args, { cwd: undefined });
+    return { ok: true, reason: 'reflink' };
+  } catch (e) {
+    return { ok: false, reason: 'copy-failed', error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/worktrees/seed_node_modules.mjs

@@ -0,0 +1,35 @@
+import { join } from 'node:path';
+import { pathExists } from '../fs/fs.mjs';
+import { reflinkCopyDir } from './reflink_copy_dir.mjs';
+
+function isTruthy(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
+export async function seedNodeModulesFromBase({
+  baseDir,
+  worktreeDir,
+  env = process.env,
+  copyDir = reflinkCopyDir,
+} = {}) {
+  const enabled = (() => {
+    const raw = String(env.HAPPIER_STACK_WT_SEED_NODE_MODULES ?? '').trim();
+    if (raw) return isTruthy(raw);
+    // Default: enable in sandboxes, disable elsewhere.
+    return Boolean(String(env.HAPPIER_STACK_SANDBOX_DIR ?? '').trim());
+  })();
+
+  if (!enabled) return { ok: true, seeded: false, reason: 'disabled' };
+
+  const from = join(String(baseDir ?? ''), 'node_modules');
+  const to = join(String(worktreeDir ?? ''), 'node_modules');
+  if (!(await pathExists(from))) return { ok: true, seeded: false, reason: 'base-missing' };
+  if (await pathExists(to)) return { ok: true, seeded: false, reason: 'dest-exists' };
+
+  const res = await copyDir({ srcDir: from, destDir: to });
+  if (!res?.ok) {
+    return { ok: true, seeded: false, reason: res?.reason ?? 'copy-failed', error: res?.error ?? null };
+  }
+  return { ok: true, seeded: true, reason: 'seeded' };
+}

package/scripts/utils/worktrees/seed_node_modules.test.mjs

@@ -0,0 +1,82 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { seedNodeModulesFromBase } from './seed_node_modules.mjs';
+
+test('seedNodeModulesFromBase is disabled by default outside sandbox', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-seed-nm-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  const base = join(dir, 'base');
+  const wt = join(dir, 'wt');
+  await mkdir(join(base, 'node_modules'), { recursive: true });
+  await mkdir(wt, { recursive: true });
+
+  let called = false;
+  const res = await seedNodeModulesFromBase({
+    baseDir: base,
+    worktreeDir: wt,
+    env: {},
+    copyDir: async () => {
+      called = true;
+      return { ok: true };
+    },
+  });
+  assert.equal(res.seeded, false);
+  assert.equal(res.reason, 'disabled');
+  assert.equal(called, false);
+});
+
+test('seedNodeModulesFromBase seeds node_modules in sandbox by default', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-seed-nm-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  const base = join(dir, 'base');
+  const wt = join(dir, 'wt');
+  await mkdir(join(base, 'node_modules'), { recursive: true });
+  await writeFile(join(base, 'node_modules', 'x.txt'), 'x\n', 'utf-8');
+  await mkdir(wt, { recursive: true });
+
+  let called = false;
+  const res = await seedNodeModulesFromBase({
+    baseDir: base,
+    worktreeDir: wt,
+    env: { HAPPIER_STACK_SANDBOX_DIR: '/tmp/sandbox' },
+    copyDir: async ({ srcDir, destDir }) => {
+      called = true;
+      assert.equal(srcDir, join(base, 'node_modules'));
+      assert.equal(destDir, join(wt, 'node_modules'));
+      await mkdir(destDir, { recursive: true });
+      return { ok: true };
+    },
+  });
+  assert.equal(res.seeded, true);
+  assert.equal(called, true);
+});
+
+test('seedNodeModulesFromBase does nothing if dest already has node_modules', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-seed-nm-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  const base = join(dir, 'base');
+  const wt = join(dir, 'wt');
+  await mkdir(join(base, 'node_modules'), { recursive: true });
+  await mkdir(join(wt, 'node_modules'), { recursive: true });
+
+  let called = false;
+  const res = await seedNodeModulesFromBase({
+    baseDir: base,
+    worktreeDir: wt,
+    env: { HAPPIER_STACK_SANDBOX_DIR: '/tmp/sandbox' },
+    copyDir: async () => {
+      called = true;
+      return { ok: true };
+    },
+  });
+  assert.equal(res.seeded, false);
+  assert.equal(res.reason, 'dest-exists');
+  assert.equal(called, false);
+});

package/scripts/utils/worktrees/yarn_install_guard.mjs

@@ -0,0 +1,53 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function mtimeMs(p) {
+  try {
+    const s = await stat(p);
+    return s.mtimeMs ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function maxPatchMtimeMs(componentDir) {
+  const patchesDir = join(componentDir, 'patches');
+  const base = await mtimeMs(patchesDir);
+  if (!base) return 0;
+  try {
+    const entries = await readdir(patchesDir, { withFileTypes: true });
+    let max = 0;
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      if (!e.name.endsWith('.patch')) continue;
+      const m = await mtimeMs(join(patchesDir, e.name));
+      if (m > max) max = m;
+    }
+    return max;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Decide whether a Yarn install needs to run, based on the same timestamp heuristic
+ * used by stack bootstrap:
+ * - if node_modules missing => install
+ * - if yarn.lock/package.json/patches newer than .yarn-integrity => install
+ */
+export async function shouldRunYarnInstall({ installDir, componentDir }) {
+  const nodeModules = join(installDir, 'node_modules');
+  const nodeModulesM = await mtimeMs(nodeModules);
+  if (!nodeModulesM) return true;
+
+  const yarnIntegrity = join(nodeModules, '.yarn-integrity');
+  const intM = await mtimeMs(yarnIntegrity);
+  if (!intM) return true;
+
+  const yarnLock = join(installDir, 'yarn.lock');
+  const lockM = await mtimeMs(yarnLock);
+  const pkgM = await mtimeMs(join(installDir, 'package.json'));
+  const patchM = await maxPatchMtimeMs(componentDir);
+
+  return lockM > intM || pkgM > intM || patchM > intM;
+}

package/scripts/utils/worktrees/yarn_install_guard.test.mjs

@@ -0,0 +1,73 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile, utimes } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { shouldRunYarnInstall } from './yarn_install_guard.mjs';
+
+async function touch(path, ms) {
+  const d = new Date(ms);
+  await utimes(path, d, d);
+}
+
+test('shouldRunYarnInstall returns true when node_modules is missing', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-yarn-guard-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  await writeFile(join(dir, 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(dir, 'yarn.lock'), '#\n', 'utf-8');
+
+  assert.equal(await shouldRunYarnInstall({ installDir: dir, componentDir: dir }), true);
+});
+
+test('shouldRunYarnInstall returns false when integrity is newer than lock/pkg/patches', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-yarn-guard-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  await writeFile(join(dir, 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(dir, 'yarn.lock'), '#\n', 'utf-8');
+  await mkdir(join(dir, 'node_modules'), { recursive: true });
+  await writeFile(join(dir, 'node_modules', '.yarn-integrity'), 'x\n', 'utf-8');
+
+  const base = Date.now();
+  await touch(join(dir, 'package.json'), base - 10_000);
+  await touch(join(dir, 'yarn.lock'), base - 9_000);
+  await touch(join(dir, 'node_modules', '.yarn-integrity'), base);
+
+  assert.equal(await shouldRunYarnInstall({ installDir: dir, componentDir: dir }), false);
+});
+
+test('shouldRunYarnInstall returns true when yarn.lock is newer than integrity', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-yarn-guard-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  await writeFile(join(dir, 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(dir, 'yarn.lock'), '#\n', 'utf-8');
+  await mkdir(join(dir, 'node_modules'), { recursive: true });
+  await writeFile(join(dir, 'node_modules', '.yarn-integrity'), 'x\n', 'utf-8');
+
+  const base = Date.now();
+  await touch(join(dir, 'node_modules', '.yarn-integrity'), base - 10_000);
+  await touch(join(dir, 'yarn.lock'), base);
+
+  assert.equal(await shouldRunYarnInstall({ installDir: dir, componentDir: dir }), true);
+});
+
+test('shouldRunYarnInstall returns true when patches are newer than integrity', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-yarn-guard-'));
+  t.after(async () => rm(dir, { recursive: true, force: true }));
+
+  await writeFile(join(dir, 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(dir, 'yarn.lock'), '#\n', 'utf-8');
+  await mkdir(join(dir, 'node_modules'), { recursive: true });
+  await writeFile(join(dir, 'node_modules', '.yarn-integrity'), 'x\n', 'utf-8');
+  await mkdir(join(dir, 'patches'), { recursive: true });
+  await writeFile(join(dir, 'patches', 'a.patch'), 'diff\n', 'utf-8');
+
+  const base = Date.now();
+  await touch(join(dir, 'node_modules', '.yarn-integrity'), base - 10_000);
+  await touch(join(dir, 'patches', 'a.patch'), base);
+
+  assert.equal(await shouldRunYarnInstall({ installDir: dir, componentDir: dir }), true);
+});

package/scripts/where.mjs

@@ -73,6 +73,9 @@ async function main() {
       runtimeDir,
       workspaceDir,
       repoDir,
+      pmCacheBaseDir: (process.env.HAPPIER_STACK_PM_CACHE_BASE_DIR ?? '').trim() || null,
+      expoSharedTmpDirBaseDir: (process.env.HAPPIER_STACK_EXPO_SHARED_TMPDIR_BASE_DIR ?? '').trim() || null,
+      expoSharedTmpDirKey: (process.env.HAPPIER_STACK_EXPO_SHARED_TMPDIR_KEY ?? '').trim() || null,
       checkouts: { main: mainDir, dev: devDir },
       worktrees: worktreeCategoryDirs,
       stack: { name: stackName, label: stackLabel },

package/scripts/worktrees.mjs

@@ -33,6 +33,8 @@ import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
 import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env/env_file.mjs';
 import { isSandboxed } from './utils/env/sandbox.mjs';
 import { applyStackCacheEnv } from './utils/proc/pm.mjs';
+import { seedNodeModulesFromBase } from './utils/worktrees/seed_node_modules.mjs';
+import { shouldRunYarnInstall } from './utils/worktrees/yarn_install_guard.mjs';
 import { existsSync } from 'node:fs';
 import { getHomeEnvLocalPath, getHomeEnvPath, resolveUserConfigEnvPath } from './utils/env/config.mjs';
 import { detectServerComponentDirMismatch } from './utils/server/validate.mjs';
@@ -381,6 +383,15 @@ async function installDependencies({ dir }) {
 
   const env = await applyStackCacheEnv(process.env);
 
+  // Yarn-only, monorepo-friendly: avoid redundant installs when nothing changed.
+  // This keeps `wt pr --update` fast for the common case where PR code changed but deps did not.
+  if (pm.kind === 'yarn') {
+    const needs = await shouldRunYarnInstall({ installDir: dir, componentDir: dir });
+    if (!needs) {
+      return { installed: false, reason: 'up-to-date' };
+    }
+  }
+
   // IMPORTANT:
   // When a caller requests --json, stdout must be reserved for JSON output only.
   // Package managers (especially Yarn) write progress to stdout, which would corrupt JSON parsing
@@ -446,6 +457,11 @@ async function maybeSetupDeps({ repoRoot, baseDir, worktreeDir, depsMode, compon
     }
   }
 
+  // Install path (also used for link-or-install fallthrough).
+  // In sandbox contexts, try to seed node_modules from the base checkout first (copy-on-write reflink)
+  // to make first-time PR worktrees much faster while keeping them fully isolated (no symlinks).
+  await seedNodeModulesFromBase({ baseDir: linkFrom, worktreeDir });
+
   const inst = await installDependencies({ dir: worktreeDir });
   return { mode: depsMode, linked: false, installed: Boolean(inst.installed), message: inst.reason };
 }