@happier-dev/stack 0.1.0-preview.96.1 → 0.2.0-preview.1775370152.55749

package/scripts/utils/tui/stack_scope_env.mjs

@@ -0,0 +1,10 @@
+import { applyStackActiveServerScopeEnv } from '../auth/stable_scope_id.mjs';
+
+export function applyTuiStackAuthScopeEnv({ env, stackName }) {
+  const base = env && typeof env === 'object' ? env : {};
+  const name = String(stackName ?? '').trim() || (base.HAPPIER_STACK_STACK ?? '').toString().trim() || 'main';
+  // Make credential/daemon state lookups stable per stack, even if the user's shell exported
+  // a different HAPPIER_ACTIVE_SERVER_ID (common when main stack is running).
+  return applyStackActiveServerScopeEnv({ env: base, stackName: name });
+}
+

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

@@ -0,0 +1,21 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { applyTuiStackAuthScopeEnv } from './stack_scope_env.mjs';
+
+test('applyTuiStackAuthScopeEnv overrides HAPPIER_ACTIVE_SERVER_ID per stack', () => {
+  const env = applyTuiStackAuthScopeEnv({
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'main', HAPPIER_STACK_CLI_IDENTITY: 'default' },
+    stackName: 'repo-dev-a1cc5e0671',
+  });
+  assert.equal(env.HAPPIER_ACTIVE_SERVER_ID, 'stack_repo-dev-a1cc5e0671__id_default');
+});
+
+test('applyTuiStackAuthScopeEnv deletes HAPPIER_ACTIVE_SERVER_ID when stable scope is disabled', () => {
+  const env = applyTuiStackAuthScopeEnv({
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'main', HAPPIER_STACK_DISABLE_STABLE_SCOPE: '1' },
+    stackName: 'repo-dev-a1cc5e0671',
+  });
+  assert.equal(env.HAPPIER_ACTIVE_SERVER_ID, undefined);
+});
+

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/stdin_handoff.mjs

@@ -0,0 +1,101 @@
+function safeSetRawMode(stdin, enabled) {
+  try {
+    if (stdin && typeof stdin.setRawMode === 'function') {
+      stdin.setRawMode(Boolean(enabled));
+    }
+  } catch {
+    // ignore
+  }
+}
+
+function safePause(stdin) {
+  try {
+    if (stdin && typeof stdin.pause === 'function') stdin.pause();
+  } catch {
+    // ignore
+  }
+}
+
+function safeResume(stdin) {
+  try {
+    if (stdin && typeof stdin.resume === 'function') stdin.resume();
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * When we spawn a child with stdio: 'inherit', the child and the TUI compete for the same stdin FD.
+ * If the TUI keeps reading, it will consume keystrokes before the child sees them.
+ *
+ * Detach the TUI's stdin handler + pause stdin so the child can read deterministically.
+ */
+export function detachTuiStdinForChild({ stdin, onData }) {
+  const hadListener = Boolean(stdin && typeof stdin.off === 'function' && typeof onData === 'function');
+  if (hadListener) {
+    try {
+      stdin.off('data', onData);
+    } catch {
+      // ignore
+    }
+  }
+
+  // Stop Node from reading stdin so the child can read directly from the terminal.
+  safePause(stdin);
+  safeSetRawMode(stdin, false);
+
+  return {
+    restoreForTui() {
+      safeSetRawMode(stdin, true);
+      safeResume(stdin);
+      if (hadListener) {
+        try {
+          stdin.on('data', onData);
+        } catch {
+          // ignore
+        }
+      }
+    },
+  };
+}
+
+export async function waitForEnter({ stdin, timeoutMs = 120_000 } = {}) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    // eslint-disable-next-line no-await-in-loop
+    const chunk = await new Promise((resolve) => {
+      const onData = (d) => {
+        cleanup();
+        resolve(d);
+      };
+      const onEnd = () => {
+        cleanup();
+        resolve(null);
+      };
+      const cleanup = () => {
+        try {
+          stdin?.off?.('data', onData);
+        } catch {
+          // ignore
+        }
+        try {
+          stdin?.off?.('end', onEnd);
+        } catch {
+          // ignore
+        }
+      };
+
+      try {
+        stdin?.on?.('data', onData);
+        stdin?.on?.('end', onEnd);
+      } catch {
+        resolve(null);
+      }
+    });
+
+    const s = chunk == null ? '' : String(chunk);
+    if (s.includes('\n') || s.includes('\r')) return true;
+  }
+  return false;
+}
+

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

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+
+import { detachTuiStdinForChild } from './stdin_handoff.mjs';
+
+test('detachTuiStdinForChild pauses stdin and detaches TUI data handler, then restores it', () => {
+  const stdin = new EventEmitter();
+
+  /** @type {string[]} */
+  const calls = [];
+  // Minimal stream-like surface.
+  stdin.pause = () => calls.push('pause');
+  stdin.resume = () => calls.push('resume');
+  stdin.setRawMode = (v) => calls.push(`raw:${String(Boolean(v))}`);
+
+  const onData = () => {};
+  stdin.on('data', onData);
+  assert.equal(stdin.listenerCount('data'), 1);
+
+  const { restoreForTui } = detachTuiStdinForChild({ stdin, onData });
+  assert.equal(stdin.listenerCount('data'), 0);
+  assert.deepEqual(calls, ['pause', 'raw:false']);
+
+  restoreForTui();
+  assert.equal(stdin.listenerCount('data'), 1);
+  assert.deepEqual(calls, ['pause', 'raw:false', 'raw:true', 'resume']);
+});
+

package/scripts/utils/tui/summary_env.mjs

@@ -0,0 +1,7 @@
+export function mergeEnvForTuiSummary({ stackEnvFromFile, processEnv = process.env } = {}) {
+  const fileEnv = stackEnvFromFile && typeof stackEnvFromFile === 'object' ? stackEnvFromFile : {};
+  const procEnv = processEnv && typeof processEnv === 'object' ? processEnv : {};
+  // Prefer process env (it reflects all overlays and wrapper overrides).
+  return { ...fileEnv, ...procEnv };
+}
+

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

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { mergeEnvForTuiSummary } from './summary_env.mjs';
+
+test('mergeEnvForTuiSummary prefers process env values over stack env file', () => {
+  const out = mergeEnvForTuiSummary({
+    stackEnvFromFile: { HAPPIER_STACK_REPO_DIR: '/from/file', HAPPIER_STACK_STACK: 'file' },
+    processEnv: { HAPPIER_STACK_REPO_DIR: '/from/process', HAPPIER_STACK_STACK: 'process' },
+  });
+  assert.equal(out.HAPPIER_STACK_REPO_DIR, '/from/process');
+  assert.equal(out.HAPPIER_STACK_STACK, 'process');
+});
+
+test('mergeEnvForTuiSummary falls back to stack env file when process env is missing', () => {
+  const out = mergeEnvForTuiSummary({
+    stackEnvFromFile: { HAPPIER_STACK_REPO_DIR: '/from/file' },
+    processEnv: {},
+  });
+  assert.equal(out.HAPPIER_STACK_REPO_DIR, '/from/file');
+});
+

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/box_line.mjs

@@ -0,0 +1,46 @@
+import { stripAnsi } from './text.mjs';
+
+function tryConsumeAnsiSequence(s, i) {
+  // Best-effort for CSI sequences like: ESC [ 1;31m
+  if (s[i] !== '\x1b' || s[i + 1] !== '[') return null;
+  let j = i + 2;
+  while (j < s.length) {
+    const ch = s[j];
+    if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z')) {
+      return { seq: s.slice(i, j + 1), next: j + 1 };
+    }
+    j += 1;
+  }
+  return null;
+}
+
+export function formatBoxLine({ text, width, allowAnsi }) {
+  const w = Math.max(0, Number(width) || 0);
+  const raw = String(text ?? '');
+
+  if (!allowAnsi) {
+    const clean = stripAnsi(raw);
+    if (clean.length >= w) return clean.slice(0, w);
+    return clean + ' '.repeat(w - clean.length);
+  }
+
+  let out = '';
+  let visible = 0;
+  for (let i = 0; i < raw.length && visible < w; ) {
+    const ansi = tryConsumeAnsiSequence(raw, i);
+    if (ansi) {
+      out += ansi.seq;
+      i = ansi.next;
+      continue;
+    }
+    out += raw[i];
+    i += 1;
+    visible += 1;
+  }
+
+  const hasAnsi = out.includes('\x1b[');
+  if (hasAnsi) out += '\x1b[0m';
+  if (visible < w) out += ' '.repeat(w - visible);
+  return out;
+}
+

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

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { stripAnsi } from './text.mjs';
+import { formatBoxLine } from './box_line.mjs';
+
+test('formatBoxLine strips ansi and pads when allowAnsi=false', () => {
+  const s = '\x1b[31mRED\x1b[0m';
+  const out = formatBoxLine({ text: s, width: 6, allowAnsi: false });
+  assert.equal(out, 'RED   ');
+});
+
+test('formatBoxLine preserves ansi and pads/clips by visible width when allowAnsi=true', () => {
+  const s = '\x1b[1;31mRED\x1b[0m!';
+  const out = formatBoxLine({ text: s, width: 4, allowAnsi: true });
+  assert.ok(out.includes('\x1b['), 'expected ansi to be preserved');
+  assert.equal(stripAnsi(out).length, 4);
+  assert.equal(stripAnsi(out), 'RED!');
+});
+

package/scripts/utils/ui/ui_export_env.mjs

@@ -0,0 +1,31 @@
+export function buildStackWebExportEnv({ baseEnv } = {}) {
+  const env = { ...(baseEnv || process.env) };
+
+  // This is a stack-built bundle (served by the stack server), so ensure the app
+  // behaves like stack context at runtime (no Cloud seeding/locking).
+  env.NODE_ENV = 'production';
+  env.EXPO_PUBLIC_DEBUG = '0';
+  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;
+}
+
+export function buildStackTauriExportEnv({ baseEnv, tauriServerUrl } = {}) {
+  const env = { ...(baseEnv || process.env) };
+
+  env.NODE_ENV = 'production';
+  env.EXPO_PUBLIC_DEBUG = '0';
+  env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT = 'stack';
+
+  // In Tauri, window.location.origin is a tauri:// origin, so hardcode the API base.
+  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

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildStackTauriExportEnv, buildStackWebExportEnv } from './ui_export_env.mjs';
+
+test('buildStackWebExportEnv forces stack server context and leaves server URL empty for runtime origin', () => {
+  const env = buildStackWebExportEnv({ baseEnv: { ...process.env } });
+
+  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, '');
+});
+
+test('buildStackTauriExportEnv forces stack server context and hardcodes API base URL', () => {
+  const tauriServerUrl = 'http://127.0.0.1:3013';
+  const env = buildStackTauriExportEnv({ baseEnv: { ...process.env }, tauriServerUrl });
+
+  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' };
+}