happy-stacks 0.1.2 → 0.2.0

package/scripts/utils/happy_server_infra.mjs

@@ -1,12 +1,12 @@
 import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import net from 'node:net';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 
 import { parseDotenv } from './dotenv.mjs';
 import { ensureEnvFileUpdated } from './env_file.mjs';
+import { pickNextFreeTcpPort } from './ports.mjs';
 import { pmExecBin } from './pm.mjs';
 import { run, runCapture } from './proc.mjs';
 
@@ -37,29 +37,6 @@ function coercePort(v) {
   return Number.isFinite(n) && n > 0 ? n : null;
 }
 
-async function isPortFree(port) {
-  return await new Promise((resolvePromise) => {
-    const srv = net.createServer();
-    srv.unref();
-    srv.on('error', () => resolvePromise(false));
-    srv.listen({ port, host: '127.0.0.1' }, () => {
-      srv.close(() => resolvePromise(true));
-    });
-  });
-}
-
-async function pickNextFreePort(startPort, { reservedPorts = new Set() } = {}) {
-  let port = startPort;
-  for (let i = 0; i < 200; i++) {
-    // eslint-disable-next-line no-await-in-loop
-    if (!reservedPorts.has(port) && (await isPortFree(port))) {
-      return port;
-    }
-    port += 1;
-  }
-  throw new Error(`[infra] unable to find a free port starting at ${startPort}`);
-}
-
 async function readEnvObject(envPath) {
   try {
     const raw = await readFile(envPath, 'utf-8');
@@ -243,8 +220,26 @@ async function maybeStartDockerDaemon() {
   }
 }
 
-async function dockerCompose({ composePath, projectName, args, options = {} }) {
-  await run('docker', ['compose', '-f', composePath, '-p', projectName, ...args], options);
+async function dockerCompose({ composePath, projectName, args, options = {}, quiet = false, retries = 0 }) {
+  const cmdArgs = ['compose', '-f', composePath, '-p', projectName, ...args];
+  let attempt = 0;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      if (quiet) {
+        // Capture stderr so callers can surface it in structured JSON errors.
+        await runCapture('docker', cmdArgs, { timeoutMs: 120_000, ...options });
+      } else {
+        await run('docker', cmdArgs, { ...options, stdio: options?.stdio ?? 'inherit' });
+      }
+      return;
+    } catch (e) {
+      if (attempt >= retries) throw e;
+      attempt += 1;
+      // eslint-disable-next-line no-await-in-loop
+      await delay(800);
+    }
+  }
 }
 
 async function waitForHealthyPostgres({ composePath, projectName, pgUser, pgDb }) {
@@ -285,6 +280,25 @@ async function waitForHealthyRedis({ composePath, projectName }) {
   throw new Error('[infra] timed out waiting for redis to become ready');
 }
 
+async function waitForMinioReady({ composePath, projectName }) {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    try {
+      // Minio doesn't ship a healthcheck in our compose; exec'ing a trivial command is a good enough
+      // readiness proxy for running/accepting execs before we run minio-init.
+      await runCapture('docker', ['compose', '-f', composePath, '-p', projectName, 'exec', '-T', 'minio', 'sh', '-lc', 'echo ok'], {
+        timeoutMs: 5_000,
+      });
+      return;
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(600);
+  }
+  throw new Error('[infra] timed out waiting for minio to become ready');
+}
+
 export async function ensureHappyServerManagedInfra({
   stackName,
   baseDir,
@@ -292,6 +306,8 @@ export async function ensureHappyServerManagedInfra({
   publicServerUrl,
   envPath,
   env = process.env,
+  quiet = false,
+  skipMinioInit = false,
 }) {
   await ensureDockerCompose();
 
@@ -315,17 +331,21 @@ export async function ensureHappyServerManagedInfra({
   }
   if (Number.isFinite(serverPort) && serverPort > 0) reservedPorts.add(serverPort);
 
-  const pgPort = coercePort(existingEnv.HAPPY_STACKS_PG_PORT ?? env.HAPPY_STACKS_PG_PORT) ?? (await pickNextFreePort(serverPort + 1000, { reservedPorts }));
+  const pgPort =
+    coercePort(existingEnv.HAPPY_STACKS_PG_PORT ?? env.HAPPY_STACKS_PG_PORT) ??
+    (await pickNextFreeTcpPort(serverPort + 1000, { reservedPorts }));
   reservedPorts.add(pgPort);
   const redisPort =
-    coercePort(existingEnv.HAPPY_STACKS_REDIS_PORT ?? env.HAPPY_STACKS_REDIS_PORT) ?? (await pickNextFreePort(pgPort + 1, { reservedPorts }));
+    coercePort(existingEnv.HAPPY_STACKS_REDIS_PORT ?? env.HAPPY_STACKS_REDIS_PORT) ??
+    (await pickNextFreeTcpPort(pgPort + 1, { reservedPorts }));
   reservedPorts.add(redisPort);
   const minioPort =
-    coercePort(existingEnv.HAPPY_STACKS_MINIO_PORT ?? env.HAPPY_STACKS_MINIO_PORT) ?? (await pickNextFreePort(redisPort + 1, { reservedPorts }));
+    coercePort(existingEnv.HAPPY_STACKS_MINIO_PORT ?? env.HAPPY_STACKS_MINIO_PORT) ??
+    (await pickNextFreeTcpPort(redisPort + 1, { reservedPorts }));
   reservedPorts.add(minioPort);
   const minioConsolePort =
     coercePort(existingEnv.HAPPY_STACKS_MINIO_CONSOLE_PORT ?? env.HAPPY_STACKS_MINIO_CONSOLE_PORT) ??
-    (await pickNextFreePort(minioPort + 1, { reservedPorts }));
+    (await pickNextFreeTcpPort(minioPort + 1, { reservedPorts }));
   reservedPorts.add(minioConsolePort);
 
   const pgUser = (existingEnv.HAPPY_STACKS_PG_USER ?? env.HAPPY_STACKS_PG_USER ?? 'handy').trim() || 'handy';
@@ -355,27 +375,45 @@ export async function ensureHappyServerManagedInfra({
   const s3PublicUrl = `${pub}/files`;
 
   if (envPath) {
+    // Ephemeral stacks should not pin ports in env files. In stack runtime, callers set
+    // HAPPY_STACKS_EPHEMERAL_PORTS=1 (via stack.runtime.json overlay) while the stack owner is alive.
+    //
+    // For offline tooling (e.g. auth seeding) we still want to preserve the invariant:
+    // - non-main stacks are ephemeral-by-default unless the user explicitly pinned ports already.
+    const runtimeEphemeral = (env.HAPPY_STACKS_EPHEMERAL_PORTS ?? env.HAPPY_LOCAL_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+    const alreadyPinnedPorts =
+      Boolean((existingEnv.HAPPY_STACKS_PG_PORT ?? '').trim()) ||
+      Boolean((existingEnv.HAPPY_STACKS_REDIS_PORT ?? '').trim()) ||
+      Boolean((existingEnv.HAPPY_STACKS_MINIO_PORT ?? '').trim()) ||
+      Boolean((existingEnv.HAPPY_STACKS_MINIO_CONSOLE_PORT ?? '').trim());
+    const ephemeralPorts = runtimeEphemeral || (stackName !== 'main' && !alreadyPinnedPorts);
     await ensureEnvFileUpdated({
       envPath,
       updates: [
-        { key: 'HAPPY_STACKS_PG_PORT', value: String(pgPort) },
-        { key: 'HAPPY_STACKS_REDIS_PORT', value: String(redisPort) },
-        { key: 'HAPPY_STACKS_MINIO_PORT', value: String(minioPort) },
-        { key: 'HAPPY_STACKS_MINIO_CONSOLE_PORT', value: String(minioConsolePort) },
+        // Stable credentials/files: persist these so restarts keep the same DB/user and S3 creds.
         { key: 'HAPPY_STACKS_PG_USER', value: pgUser },
         { key: 'HAPPY_STACKS_PG_PASSWORD', value: pgPassword },
         { key: 'HAPPY_STACKS_PG_DATABASE', value: pgDb },
         { key: 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE', value: secretFile },
-        // Vars consumed by happy-server:
-        { key: 'DATABASE_URL', value: databaseUrl },
-        { key: 'REDIS_URL', value: redisUrl },
-        { key: 'S3_HOST', value: s3Host },
-        { key: 'S3_PORT', value: String(minioPort) },
-        { key: 'S3_USE_SSL', value: s3UseSsl },
         { key: 'S3_ACCESS_KEY', value: s3AccessKey },
         { key: 'S3_SECRET_KEY', value: s3SecretKey },
         { key: 'S3_BUCKET', value: s3Bucket },
-        { key: 'S3_PUBLIC_URL', value: s3PublicUrl },
+        // Ports + derived URLs: persist only when ports are explicitly pinned (non-ephemeral mode).
+        ...(ephemeralPorts
+          ? []
+          : [
+              { key: 'HAPPY_STACKS_PG_PORT', value: String(pgPort) },
+              { key: 'HAPPY_STACKS_REDIS_PORT', value: String(redisPort) },
+              { key: 'HAPPY_STACKS_MINIO_PORT', value: String(minioPort) },
+              { key: 'HAPPY_STACKS_MINIO_CONSOLE_PORT', value: String(minioConsolePort) },
+              // Vars consumed by happy-server:
+              { key: 'DATABASE_URL', value: databaseUrl },
+              { key: 'REDIS_URL', value: redisUrl },
+              { key: 'S3_HOST', value: s3Host },
+              { key: 'S3_PORT', value: String(minioPort) },
+              { key: 'S3_USE_SSL', value: s3UseSsl },
+              { key: 'S3_PUBLIC_URL', value: s3PublicUrl },
+            ]),
       ],
     });
   }
@@ -397,12 +435,28 @@ export async function ensureHappyServerManagedInfra({
   });
   await writeFile(composePath, yaml, 'utf-8');
 
-  await dockerCompose({ composePath, projectName, args: ['up', '-d', '--remove-orphans'], options: { cwd: baseDir } });
+  await dockerCompose({
+    composePath,
+    projectName,
+    args: ['up', '-d', '--remove-orphans'],
+    options: { cwd: baseDir, stdio: quiet ? 'ignore' : 'inherit' },
+    quiet,
+  });
   await waitForHealthyPostgres({ composePath, projectName, pgUser, pgDb });
   await waitForHealthyRedis({ composePath, projectName });
 
-  // Ensure bucket exists (idempotent)
-  await dockerCompose({ composePath, projectName, args: ['run', '--rm', 'minio-init'], options: { cwd: baseDir } });
+  if (!skipMinioInit) {
+    // Ensure bucket exists (idempotent). This can race with Minio startup; retry a few times.
+    await waitForMinioReady({ composePath, projectName });
+    await dockerCompose({
+      composePath,
+      projectName,
+      args: ['run', '--rm', '--no-deps', 'minio-init'],
+      options: { cwd: baseDir, stdio: quiet ? 'ignore' : 'inherit' },
+      quiet,
+      retries: 3,
+    });
+  }
 
   return {
     composePath,
@@ -423,8 +477,8 @@ export async function ensureHappyServerManagedInfra({
   };
 }
 
-export async function applyHappyServerMigrations({ serverDir, env }) {
+export async function applyHappyServerMigrations({ serverDir, env, quiet = false }) {
   // Non-interactive + idempotent. Safe for dev; also safe for managed stacks on start.
-  await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env });
+  await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env, quiet });
 }
 

package/scripts/utils/localhost_host.mjs

@@ -0,0 +1,17 @@
+import { getStackName } from './paths.mjs';
+
+function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
+  const s = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  return s || fallback;
+}
+
+export function resolveLocalhostHost({ stackMode, stackName = getStackName() } = {}) {
+  if (!stackMode) return 'localhost';
+  if (!stackName || stackName === 'main') return 'localhost';
+  return `happy-${sanitizeDnsLabel(stackName)}.localhost`;
+}

package/scripts/utils/ownership.mjs

@@ -0,0 +1,135 @@
+import { runCapture } from './proc.mjs';
+import { killPid } from './expo.mjs';
+
+export async function getPsEnvLine(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['eww', '-p', String(n)]);
+    // Output usually includes a header line and then a single process line.
+    const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length >= 2) return lines[1];
+    if (lines.length === 1) return lines[0];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function listPidsWithEnvNeedle(needle) {
+  const n = String(needle ?? '').trim();
+  if (!n) return [];
+  if (process.platform === 'win32') return [];
+  try {
+    // Include environment variables (eww) so we can match on HAPPY_STACKS_ENV_FILE=/.../env safely.
+    const out = await runCapture('ps', ['eww', '-ax', '-o', 'pid=,command=']);
+    const pids = [];
+    for (const line of out.split('\n')) {
+      if (!line.includes(n)) continue;
+      const m = line.trim().match(/^(\d+)\s+/);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      if (Number.isFinite(pid) && pid > 1) {
+        pids.push(pid);
+      }
+    }
+    return Array.from(new Set(pids));
+  } catch {
+    return [];
+  }
+}
+
+export async function getProcessGroupId(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['-o', 'pgid=', '-p', String(n)]);
+    const raw = out.trim();
+    const pgid = raw ? Number(raw) : NaN;
+    return Number.isFinite(pgid) && pgid > 1 ? pgid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir } = {}) {
+  const line = await getPsEnvLine(pid);
+  if (!line) return false;
+  const sn = String(stackName ?? '').trim();
+  const ep = String(envPath ?? '').trim();
+  const ch = String(cliHomeDir ?? '').trim();
+
+  // Require at least one stack identifier.
+  const hasStack =
+    (sn && (line.includes(`HAPPY_STACKS_STACK=${sn}`) || line.includes(`HAPPY_LOCAL_STACK=${sn}`))) ||
+    (!sn && (line.includes('HAPPY_STACKS_STACK=') || line.includes('HAPPY_LOCAL_STACK=')));
+  if (!hasStack) return false;
+
+  // Prefer env-file binding (strongest).
+  if (ep) {
+    if (line.includes(`HAPPY_STACKS_ENV_FILE=${ep}`) || line.includes(`HAPPY_LOCAL_ENV_FILE=${ep}`)) {
+      return true;
+    }
+  }
+
+  // Fallback: CLI home dir binding (useful for daemon-related processes).
+  if (ch) {
+    if (line.includes(`HAPPY_HOME_DIR=${ch}`) || line.includes(`HAPPY_STACKS_CLI_HOME_DIR=${ch}`) || line.includes(`HAPPY_LOCAL_CLI_HOME_DIR=${ch}`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export async function killPidOwnedByStack(pid, { stackName, envPath, cliHomeDir, label = 'process', json = false } = {}) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  await killPid(pid);
+  return { killed: true, reason: 'killed' };
+}
+
+export async function killProcessGroupOwnedByStack(
+  pid,
+  { stackName, envPath, cliHomeDir, label = 'process-group', json = false, signal = 'SIGTERM' } = {}
+) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  const pgid = await getProcessGroupId(pid);
+  if (!pgid) {
+    await killPid(pid);
+    return { killed: true, reason: 'killed_pid_only' };
+  }
+  try {
+    process.kill(-pgid, signal);
+  } catch {
+    // ignore
+  }
+  // Escalate if still alive.
+  try {
+    process.kill(pid, 0);
+    try {
+      process.kill(-pgid, 'SIGKILL');
+    } catch {
+      // ignore
+    }
+  } catch {
+    // exited
+  }
+  return { killed: true, reason: 'killed_pgid', pgid };
+}
+

package/scripts/utils/paths.mjs

@@ -2,6 +2,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 
 const PRIMARY_APP_SLUG = 'happy-stacks';
 const LEGACY_APP_SLUG = 'happy-local';
@@ -101,12 +102,13 @@ export function resolveStackBaseDir(stackName = getStackName()) {
   const preferredRoot = getStacksStorageRoot();
   const newBase = join(preferredRoot, stackName);
   const legacyBase = stackName === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', stackName);
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   // Prefer the new layout by default.
   //
   // For non-main stacks, keep legacy layout if the legacy env exists and the new env does not.
   // This avoids breaking existing stacks until `happys stack migrate` is run.
-  if (stackName !== 'main') {
+  if (allowLegacy && stackName !== 'main') {
     const newEnv = join(preferredRoot, stackName, 'env');
     const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
     if (!existsSync(newEnv) && existsSync(legacyEnv)) {
@@ -123,11 +125,12 @@ export function resolveStackEnvPath(stackName = getStackName()) {
   const newEnv = join(getStacksStorageRoot(), stackName, 'env');
   // Legacy layout: ~/.happy/local/stacks/<name>/env
   const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   if (existsSync(newEnv)) {
     return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(), stackName) };
   }
-  if (existsSync(legacyEnv)) {
+  if (allowLegacy && existsSync(legacyEnv)) {
     return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', stackName) };
   }
   return { envPath: newEnv, isLegacy, baseDir: activeBase };

package/scripts/utils/pm.mjs

@@ -1,13 +1,61 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { existsSync } from 'node:fs';
-import { chmod, mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 
 import { pathExists } from './fs.mjs';
 import { run, runCapture, spawnProc } from './proc.mjs';
 import { getDefaultAutostartPaths, getHappyStacksHomeDir } from './paths.mjs';
 import { resolveInstalledPath, resolveInstalledCliRoot } from './runtime.mjs';
 
+function sha256Hex(s) {
+  return createHash('sha256').update(String(s ?? ''), 'utf-8').digest('hex');
+}
+
+async function readJsonIfExists(path) {
+  try {
+    if (!path || !existsSync(path)) return null;
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function writeJsonAtomic(path, value) {
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.tmp.${Date.now()}.${Math.random().toString(16).slice(2)}.json`);
+  await writeFile(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+  await rename(tmp, path);
+}
+
+function resolveBuildStatePath({ label, dir }) {
+  const homeDir = getHappyStacksHomeDir();
+  const key = sha256Hex(resolve(dir));
+  return join(homeDir, 'cache', 'build', label, `${key}.json`);
+}
+
+async function computeGitWorktreeSignature(dir) {
+  try {
+    // Fast path: only if this is a git worktree.
+    const inside = (await runCapture('git', ['-C', dir, 'rev-parse', '--is-inside-work-tree'])).trim();
+    if (inside !== 'true') return null;
+    const head = (await runCapture('git', ['-C', dir, 'rev-parse', 'HEAD'])).trim();
+    // Includes staged + unstaged + untracked changes; captures “dirty” vs “clean”.
+    const status = await runCapture('git', ['-C', dir, 'status', '--porcelain=v1']);
+    return {
+      kind: 'git',
+      head,
+      statusHash: sha256Hex(status),
+      signature: sha256Hex(`${head}\n${status}`),
+    };
+  } catch {
+    return null;
+  }
+}
+
 async function commandExists(cmd, options = {}) {
   try {
     await runCapture(cmd, ['--version'], options);
@@ -53,7 +101,7 @@ export async function requireDir(label, dir) {
   );
 }
 
-export async function ensureDepsInstalled(dir, label) {
+export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
   const pkgJson = join(dir, 'package.json');
   if (!(await pathExists(pkgJson))) {
     return;
@@ -62,6 +110,7 @@ export async function ensureDepsInstalled(dir, label) {
   const nodeModules = join(dir, 'node_modules');
   const pnpmModulesMeta = join(dir, 'node_modules', '.modules.yaml');
   const pm = await getComponentPm(dir);
+  const stdio = quiet ? 'ignore' : 'inherit';
 
   if (await pathExists(nodeModules)) {
     const yarnLock = join(dir, 'yarn.lock');
@@ -71,10 +120,12 @@ export async function ensureDepsInstalled(dir, label) {
     // If this repo is Yarn-managed (yarn.lock present) but node_modules was created by pnpm,
     // reinstall with Yarn to restore upstream-locked dependency versions.
     if (pm.name === 'yarn' && (await pathExists(pnpmModulesMeta))) {
-      // eslint-disable-next-line no-console
-      console.log(`[local] converting ${label} dependencies back to yarn (reinstalling node_modules)...`);
+      if (!quiet) {
+        // eslint-disable-next-line no-console
+        console.log(`[local] converting ${label} dependencies back to yarn (reinstalling node_modules)...`);
+      }
       await rm(nodeModules, { recursive: true, force: true });
-      await run(pm.cmd, ['install'], { cwd: dir });
+      await run(pm.cmd, ['install'], { cwd: dir, stdio });
     }
 
     // If dependencies changed since the last install, re-run install even if node_modules exists.
@@ -92,9 +143,11 @@ export async function ensureDepsInstalled(dir, label) {
       const pkgM = await mtimeMs(pkgJson);
       const intM = await mtimeMs(yarnIntegrity);
       if (!intM || lockM > intM || pkgM > intM) {
-        // eslint-disable-next-line no-console
-        console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
-        await run(pm.cmd, ['install'], { cwd: dir });
+        if (!quiet) {
+          // eslint-disable-next-line no-console
+          console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
+        }
+        await run(pm.cmd, ['install'], { cwd: dir, stdio });
       }
     }
 
@@ -102,29 +155,75 @@ export async function ensureDepsInstalled(dir, label) {
       const lockM = await mtimeMs(pnpmLock);
       const metaM = await mtimeMs(pnpmModulesMeta);
       if (!metaM || lockM > metaM) {
-        // eslint-disable-next-line no-console
-        console.log(`[local] refreshing ${label} dependencies (pnpm-lock changed)...`);
-        await run(pm.cmd, ['install'], { cwd: dir });
+        if (!quiet) {
+          // eslint-disable-next-line no-console
+          console.log(`[local] refreshing ${label} dependencies (pnpm-lock changed)...`);
+        }
+        await run(pm.cmd, ['install'], { cwd: dir, stdio });
       }
     }
 
     return;
   }
 
-  // eslint-disable-next-line no-console
-  console.log(`[local] installing ${label} dependencies (first run)...`);
-  await run(pm.cmd, ['install'], { cwd: dir });
+  if (!quiet) {
+    // eslint-disable-next-line no-console
+    console.log(`[local] installing ${label} dependencies (first run)...`);
+  }
+  await run(pm.cmd, ['install'], { cwd: dir, stdio });
 }
 
 export async function ensureCliBuilt(cliDir, { buildCli }) {
   await ensureDepsInstalled(cliDir, 'happy-cli');
   if (!buildCli) {
-    return;
+    return { built: false, reason: 'disabled' };
+  }
+  // Default: build only when needed (fast + reliable for worktrees that haven't been built yet).
+  //
+  // You can force always-build by setting:
+  // - HAPPY_STACKS_CLI_BUILD_MODE=always (legacy: HAPPY_LOCAL_CLI_BUILD_MODE=always)
+  // Or disable via:
+  // - HAPPY_STACKS_CLI_BUILD=0 (legacy: HAPPY_LOCAL_CLI_BUILD=0)
+  const modeRaw = (process.env.HAPPY_STACKS_CLI_BUILD_MODE ?? process.env.HAPPY_LOCAL_CLI_BUILD_MODE ?? 'auto').trim().toLowerCase();
+  const mode = modeRaw === 'always' || modeRaw === 'auto' || modeRaw === 'never' ? modeRaw : 'auto';
+  if (mode === 'never') {
+    return { built: false, reason: 'mode_never' };
+  }
+  const distEntrypoint = join(cliDir, 'dist', 'index.mjs');
+  const buildStatePath = resolveBuildStatePath({ label: 'happy-cli', dir: cliDir });
+  const gitSig = await computeGitWorktreeSignature(cliDir);
+  const prev = await readJsonIfExists(buildStatePath);
+
+  if (mode === 'auto') {
+    // If dist doesn't exist, we must build.
+    if (!(await pathExists(distEntrypoint))) {
+      // fallthrough to build
+    } else if (gitSig && prev?.signature && prev.signature === gitSig.signature) {
+      return { built: false, reason: 'up_to_date' };
+    } else if (!gitSig) {
+      // No git info: best-effort skip if dist exists (keeps this fast outside git worktrees).
+      return { built: false, reason: 'no_git_info' };
+    }
   }
+
   // eslint-disable-next-line no-console
   console.log('[local] building happy-cli...');
   const pm = await getComponentPm(cliDir);
   await run(pm.cmd, ['build'], { cwd: cliDir });
+
+  // Persist new build state (best-effort).
+  const nowSig = gitSig ?? (await computeGitWorktreeSignature(cliDir));
+  if (nowSig) {
+    await writeJsonAtomic(buildStatePath, {
+      label: 'happy-cli',
+      dir: resolve(cliDir),
+      signature: nowSig.signature,
+      head: nowSig.head,
+      statusHash: nowSig.statusHash,
+      builtAt: new Date().toISOString(),
+    }).catch(() => {});
+  }
+  return { built: true, reason: mode === 'always' ? 'mode_always' : 'changed' };
 }
 
 function getPathEntries() {
@@ -153,8 +252,9 @@ export async function ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli }) {
 
   const shim = `#!/bin/bash
 set -euo pipefail
-HOME_DIR="\${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
-HAPPYS="$HOME_DIR/bin/happys"
+# Prefer the sibling happys shim (works for sandbox installs too).
+BIN_DIR="$(cd "$(dirname "$0")" && pwd)"
+HAPPYS="$BIN_DIR/happys"
 if [[ -x "$HAPPYS" ]]; then
   exec "$HAPPYS" happy "$@"
 fi
@@ -188,13 +288,14 @@ export async function pmSpawnBin({ label, dir, bin, args, env, options = {} }) {
   return spawnProc(label, pm.cmd, ['exec', bin, ...args], env, { ...options, cwd: dir });
 }
 
-export async function pmExecBin({ dir, bin, args, env }) {
+export async function pmExecBin({ dir, bin, args, env, quiet = false }) {
   const pm = await getComponentPm(dir);
+  const stdio = quiet ? 'ignore' : 'inherit';
   if (pm.name === 'yarn') {
-    await run(pm.cmd, [bin, ...args], { env, cwd: dir });
+    await run(pm.cmd, [bin, ...args], { env, cwd: dir, stdio });
     return;
   }
-  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir });
+  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir, stdio });
 }
 
 export async function ensureMacAutostartEnabled({ rootDir, label = 'com.happy.local', env = {} }) {