happy-stacks 0.6.11 → 0.6.13

package/scripts/stack_daemon_cmd.test.mjs

@@ -18,6 +18,14 @@ function runNode(args, { cwd, env }) {
   });
 }
 
+async function writeDummyAuth({ cliHomeDir }) {
+  // For these tests, we don't care about the auth format—only that credentials exist.
+  // Happy Stacks will short-circuit daemon start when access.key is missing.
+  await mkdir(cliHomeDir, { recursive: true });
+  await writeFile(join(cliHomeDir, 'access.key'), 'dummy\n', 'utf-8');
+  await writeFile(join(cliHomeDir, 'settings.json'), JSON.stringify({ machineId: 'test-machine' }) + '\n', 'utf-8');
+}
+
 async function writeStubHappyCli({ cliDir }) {
   await mkdir(join(cliDir, 'bin'), { recursive: true });
   await mkdir(join(cliDir, 'dist'), { recursive: true });
@@ -107,6 +115,7 @@ test('happys stack daemon <name> restart restarts only the daemon', async () =>
   const cliDir = await writeStubHappyCli({ cliDir: join(tmp, 'stub-happy-cli') });
   const stackCliHome = join(storageDir, stackName, 'cli');
   await mkdir(stackCliHome, { recursive: true });
+  await writeDummyAuth({ cliHomeDir: stackCliHome });
 
   const envPath = join(storageDir, stackName, 'env');
   await mkdir(dirname(envPath), { recursive: true });
@@ -162,3 +171,190 @@ test('happys stack daemon <name> restart restarts only the daemon', async () =>
   await rm(tmp, { recursive: true, force: true });
 });
 
+test('happys stack <name> daemon start works (stack name first)', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-daemon-name-first-'));
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const stackName = 'exp-test';
+
+  const cliDir = await writeStubHappyCli({ cliDir: join(tmp, 'stub-happy-cli') });
+  const stackCliHome = join(storageDir, stackName, 'cli');
+  await mkdir(stackCliHome, { recursive: true });
+  await writeDummyAuth({ cliHomeDir: stackCliHome });
+
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(
+    envPath,
+    [
+      `HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI=${cliDir}`,
+      `HAPPY_STACKS_CLI_HOME_DIR=${stackCliHome}`,
+      `HAPPY_STACKS_SERVER_PORT=4101`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const baseEnv = {
+    ...process.env,
+    HAPPY_STACKS_HOME_DIR: homeDir,
+    HAPPY_STACKS_STORAGE_DIR: storageDir,
+    HAPPY_STACKS_CLI_ROOT_DISABLE: '1',
+  };
+
+  const startRes = await runNode([join(rootDir, 'bin', 'happys.mjs'), 'stack', stackName, 'daemon', 'start', '--json'], {
+    cwd: rootDir,
+    env: baseEnv,
+  });
+  assert.equal(
+    startRes.code,
+    0,
+    `expected start exit 0, got ${startRes.code}\nstdout:\n${startRes.stdout}\nstderr:\n${startRes.stderr}`
+  );
+  assert.ok(!startRes.stdout.includes('[stack] unknown command'), `unexpected unknown command output\n${startRes.stdout}`);
+
+  const logPath = join(stackCliHome, 'stub-daemon.log');
+  const logText = await (await import('node:fs/promises')).readFile(logPath, 'utf-8').then(String);
+  assert.ok(logText.includes('start'), `expected stub daemon start to be called\n${logText}`);
+
+  await runNode([join(rootDir, 'bin', 'happys.mjs'), 'stack', stackName, 'daemon', 'stop', '--json'], { cwd: rootDir, env: baseEnv });
+  await rm(tmp, { recursive: true, force: true });
+});
+
+test('happys stack daemon <name> start/stop with --identity uses an isolated cli home dir', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-daemon-identity-'));
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const stackName = 'exp-test';
+  const identity = 'account-b';
+
+  const cliDir = await writeStubHappyCli({ cliDir: join(tmp, 'stub-happy-cli') });
+  const stackCliHome = join(storageDir, stackName, 'cli');
+  await mkdir(stackCliHome, { recursive: true });
+  const identityHome = join(storageDir, stackName, 'cli-identities', identity);
+  await writeDummyAuth({ cliHomeDir: identityHome });
+
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(
+    envPath,
+    [
+      `HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI=${cliDir}`,
+      `HAPPY_STACKS_CLI_HOME_DIR=${stackCliHome}`,
+      `HAPPY_STACKS_SERVER_PORT=4101`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const baseEnv = {
+    ...process.env,
+    HAPPY_STACKS_HOME_DIR: homeDir,
+    HAPPY_STACKS_STORAGE_DIR: storageDir,
+    HAPPY_STACKS_CLI_ROOT_DISABLE: '1',
+  };
+
+  const startRes = await runNode(
+    [join(rootDir, 'bin', 'happys.mjs'), 'stack', 'daemon', stackName, 'start', `--identity=${identity}`, '--json'],
+    { cwd: rootDir, env: baseEnv }
+  );
+  assert.equal(
+    startRes.code,
+    0,
+    `expected start exit 0, got ${startRes.code}\nstdout:\n${startRes.stdout}\nstderr:\n${startRes.stderr}`
+  );
+
+  const logPath = join(identityHome, 'stub-daemon.log');
+  const logText = await (await import('node:fs/promises')).readFile(logPath, 'utf-8').then(String);
+  assert.ok(logText.includes('start'), `expected stub daemon start to be called in identity home\n${logText}`);
+
+  const stopRes = await runNode(
+    [join(rootDir, 'bin', 'happys.mjs'), 'stack', 'daemon', stackName, 'stop', `--identity=${identity}`, '--json'],
+    { cwd: rootDir, env: baseEnv }
+  );
+  assert.equal(
+    stopRes.code,
+    0,
+    `expected stop exit 0, got ${stopRes.code}\nstdout:\n${stopRes.stdout}\nstderr:\n${stopRes.stderr}`
+  );
+
+  const logTextAfter = await (await import('node:fs/promises')).readFile(logPath, 'utf-8').then(String);
+  assert.ok(logTextAfter.includes('stop'), `expected stub daemon stop to be called for identity\n${logTextAfter}`);
+
+  await rm(tmp, { recursive: true, force: true });
+});
+
+test('happys stack auth <name> login --identity=<name> --print prints identity-scoped HAPPY_HOME_DIR', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-auth-identity-'));
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const stackName = 'exp-test';
+  const identity = 'account-b';
+
+  const cliDir = await writeStubHappyCli({ cliDir: join(tmp, 'stub-happy-cli') });
+  const stackCliHome = join(storageDir, stackName, 'cli');
+  await mkdir(stackCliHome, { recursive: true });
+  await writeDummyAuth({ cliHomeDir: stackCliHome });
+
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(
+    envPath,
+    [
+      `HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI=${cliDir}`,
+      `HAPPY_STACKS_CLI_HOME_DIR=${stackCliHome}`,
+      `HAPPY_STACKS_SERVER_PORT=4101`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const baseEnv = {
+    ...process.env,
+    HAPPY_STACKS_HOME_DIR: homeDir,
+    HAPPY_STACKS_STORAGE_DIR: storageDir,
+    HAPPY_STACKS_CLI_ROOT_DISABLE: '1',
+  };
+
+  const res = await runNode(
+    [
+      join(rootDir, 'bin', 'happys.mjs'),
+      'stack',
+      'auth',
+      stackName,
+      'login',
+      `--identity=${identity}`,
+      '--no-open',
+      '--print',
+      '--json',
+    ],
+    { cwd: rootDir, env: baseEnv }
+  );
+  assert.equal(
+    res.code,
+    0,
+    `expected auth login --print exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`
+  );
+
+  const parsed = JSON.parse(res.stdout.trim());
+  assert.equal(parsed?.cliIdentity, identity);
+  assert.ok(
+    parsed?.cmd?.includes(`HAPPY_HOME_DIR="${join(storageDir, stackName, 'cli-identities', identity)}"`),
+    `expected printed cmd to include identity home dir\n${parsed?.cmd}`
+  );
+  assert.ok(
+    parsed?.cmd?.includes('--no-open'),
+    `expected printed cmd to include --no-open\n${parsed?.cmd}`
+  );
+
+  await rm(tmp, { recursive: true, force: true });
+});

package/scripts/stack_happy_cmd.test.mjs

@@ -38,6 +38,21 @@ async function writeStubHappyCli({ root, message }) {
   return cliDir;
 }
 
+async function writeFailingStubHappyCli({ root, errorMessage }) {
+  const cliDir = join(root, 'happy-cli');
+  await mkdir(join(cliDir, 'dist'), { recursive: true });
+  await writeFile(
+    join(cliDir, 'dist', 'index.mjs'),
+    [
+      `console.error(${JSON.stringify(errorMessage)});`,
+      `process.exit(1);`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+  return cliDir;
+}
+
 test('happys stack happy <name> runs happy-cli under that stack env', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
   const rootDir = dirname(scriptsDir);
@@ -82,6 +97,53 @@ test('happys stack happy <name> runs happy-cli under that stack env', async () =
   assert.equal(out.serverUrl, 'http://127.0.0.1:3999');
 });
 
+test('happys stack happy <name> --identity=<name> uses identity-scoped HAPPY_HOME_DIR', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-happy-identity-'));
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const stackName = 'exp-test';
+  const identity = 'account-a';
+
+  const stubRoot = join(tmp, 'stub-components');
+  const cliDir = await writeStubHappyCli({ root: stubRoot, message: 'identity' });
+
+  const stackCliHome = join(storageDir, stackName, 'cli');
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(
+    envPath,
+    [
+      `HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI=${cliDir}`,
+      `HAPPY_STACKS_CLI_HOME_DIR=${stackCliHome}`,
+      `HAPPY_STACKS_SERVER_PORT=3999`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const baseEnv = {
+    ...process.env,
+    HAPPY_STACKS_HOME_DIR: homeDir,
+    HAPPY_STACKS_STORAGE_DIR: storageDir,
+    HAPPY_STACKS_CLI_ROOT_DISABLE: '1',
+  };
+
+  const res = await runNode(
+    [join(rootDir, 'bin', 'happys.mjs'), 'stack', 'happy', stackName, `--identity=${identity}`],
+    { cwd: rootDir, env: baseEnv }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const out = JSON.parse(res.stdout.trim());
+  assert.equal(out.message, 'identity');
+  assert.equal(out.stack, stackName);
+  assert.equal(out.homeDir, join(storageDir, stackName, 'cli-identities', identity));
+  assert.equal(out.serverUrl, 'http://127.0.0.1:3999');
+});
+
 test('happys <stack> happy ... shorthand runs happy-cli under that stack env', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
   const rootDir = dirname(scriptsDir);
@@ -124,3 +186,44 @@ test('happys <stack> happy ... shorthand runs happy-cli under that stack env', a
   assert.equal(out.serverUrl, 'http://127.0.0.1:4101');
 });
 
+test('happys stack happy <name> does not print wrapper stack traces on happy-cli failure', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-happy-fail-'));
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const stackName = 'exp-test';
+
+  const stubRoot = join(tmp, 'stub-components');
+  const cliDir = await writeFailingStubHappyCli({ root: stubRoot, errorMessage: 'stub failure' });
+
+  const stackCliHome = join(storageDir, stackName, 'cli');
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(
+    envPath,
+    [
+      `HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI=${cliDir}`,
+      `HAPPY_STACKS_CLI_HOME_DIR=${stackCliHome}`,
+      `HAPPY_STACKS_SERVER_PORT=3999`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const baseEnv = {
+    ...process.env,
+    HAPPY_STACKS_HOME_DIR: homeDir,
+    HAPPY_STACKS_STORAGE_DIR: storageDir,
+    HAPPY_STACKS_CLI_ROOT_DISABLE: '1',
+  };  const res = await runNode([join(rootDir, 'bin', 'happys.mjs'), 'stack', 'happy', stackName, 'attach', 'abc'], {
+    cwd: rootDir,
+    env: baseEnv,
+  });
+  assert.equal(res.code, 1, `expected exit 1, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.ok(res.stderr.includes('stub failure'), `expected stderr to include stub failure, got:\n${res.stderr}`);
+  assert.ok(!res.stderr.includes('[happy] failed:'), `expected no [happy] failed stack trace, got:\n${res.stderr}`);
+  assert.ok(!res.stderr.includes('[stack] failed:'), `expected no [stack] failed stack trace, got:\n${res.stderr}`);
+  assert.ok(!res.stderr.includes('node:internal'), `expected no node:internal stack trace, got:\n${res.stderr}`);
+});

package/scripts/utils/cli/prereqs.mjs

@@ -4,7 +4,7 @@ function formatMissingTool({ name, why, install }) {
   return [`- ${name}: ${why}`, ...(install?.length ? install.map((l) => `  ${l}`) : [])].join('\n');
 }
 
-export async function assertCliPrereqs({ git = false, pnpm = false, codex = false, coderabbit = false } = {}) {
+export async function assertCliPrereqs({ git = false, pnpm = false, codex = false, coderabbit = false, augment = false } = {}) {
   const missing = [];
 
   if (git) {
@@ -65,6 +65,17 @@ export async function assertCliPrereqs({ git = false, pnpm = false, codex = fals
     }
   }
 
+  if (augment) {
+    const hasAuggie = await commandExists('auggie');
+    if (!hasAuggie) {
+      missing.push({
+        name: 'auggie',
+        why: 'required to run Augment (Auggie) review',
+        install: ['Install Auggie CLI: `npm install -g @augmentcode/auggie`', 'Then authenticate: `auggie login`'],
+      });
+    }
+  }
+
   if (!missing.length) return;
 
   throw new Error(

package/scripts/utils/cli/wizard.mjs

@@ -36,7 +36,25 @@ export async function promptSelect(rl, { title, options, defaultIndex = 0 }) {
     console.log(`  ${i + 1}) ${options[i].label}`);
   }
   const answer = (await rl.question(`Pick [1-${options.length}] (default: ${defaultIndex + 1}): `)).trim();
-  const n = answer ? Number(answer) : defaultIndex + 1;
+  const token = answer.match(/\d+/)?.[0] ?? '';
+  let n = defaultIndex + 1;
+  if (token) {
+    const parsed = Number(token);
+    if (Number.isFinite(parsed)) {
+      // Heuristic: in some nested-readline situations (or odd terminals), single-digit input can get duplicated
+      // (e.g. "2" becomes "22"). If that happens and all digits are identical, treat it as the intended single digit.
+      if (
+        token.length > 1 &&
+        token.split('').every((c) => c === token[0]) &&
+        Number(token[0]) >= 1 &&
+        Number(token[0]) <= options.length
+      ) {
+        n = Number(token[0]);
+      } else {
+        n = parsed;
+      }
+    }
+  }
   const idx = Math.max(1, Math.min(options.length, Number.isFinite(n) ? n : defaultIndex + 1)) - 1;
   return options[idx].value;
 }

package/scripts/utils/dev/daemon.mjs

@@ -47,7 +47,9 @@ export async function prepareDaemonAuthSeed({
     serverComponentName,
     serverDir,
     env: serverEnv,
-    bestEffort: serverComponentName === 'happy-server',
+    // This probe is used only for auth seeding heuristics (and should never block stack startup).
+    // For unified server-light, running migrations here can race the running server and lock SQLite.
+    bestEffort: true,
   });
   return await prepareDaemonAuthSeedIfNeeded({
     rootDir,

package/scripts/utils/llm/assist.mjs

@@ -27,8 +27,16 @@ function buildInteractiveLaunchScript({ toolCmd, cd, title, promptText }) {
   if (!cwd) throw new Error('[llm] launch: missing cwd');
   if (!cmd) throw new Error('[llm] launch: missing toolCmd');
 
-  // Best-effort: print the prompt and open the CLI.
-  // We intentionally do NOT try to auto-feed stdin for tools we don't fully control.
+  const execLine = (() => {
+    // Prefer providing the prompt directly when the CLI supports it.
+    // - Claude Code: `claude "query"` starts an interactive session with an initial prompt.
+    // - OpenCode: `opencode --prompt "..."` starts the TUI with an initial prompt.
+    if (cmd === 'claude') return 'exec command claude "$HS_PROMPT"';
+    if (cmd === 'opencode') return 'exec command opencode --prompt "$HS_PROMPT"';
+    // Fallback: start the tool and ask the user to paste.
+    return `exec command ${JSON.stringify(cmd)}`;
+  })();
+
   return [
     '#!/usr/bin/env bash',
     'set -euo pipefail',
@@ -37,20 +45,29 @@ function buildInteractiveLaunchScript({ toolCmd, cd, title, promptText }) {
     '',
     `echo ${JSON.stringify(t)}`,
     'echo',
-    'echo "Prompt (also copied to clipboard if supported by the parent process):"',
+    'echo "Prompt:"',
     'echo "------------------------------------------------------------"',
-    "cat <<'HS_PROMPT_EOF'",
+    'HS_PROMPT="$(cat <<\'HS_PROMPT_EOF\'',
     prompt,
     'HS_PROMPT_EOF',
+    ')"',
+    'echo "$HS_PROMPT"',
     'echo "------------------------------------------------------------"',
     'echo',
-    `echo "Starting: ${cmd}"`,
-    `exec command ${JSON.stringify(cmd)}`,
+    'if command -v pbcopy >/dev/null 2>&1; then',
+    '  printf "%s" "$HS_PROMPT" | pbcopy',
+    '  echo "Copied prompt to clipboard (pbcopy)."',
+    'fi',
+    'echo',
+    'echo "Press Enter to start now, or Ctrl+C to cancel."',
+    'read -r _',
+    execLine,
     '',
   ].join('\n');
 }
 
 export async function launchLlmAssistant({
+  rl: providedRl = null,
   title,
   subtitle,
   promptText,
@@ -73,27 +90,31 @@ export async function launchLlmAssistant({
     return { ok: false, reason: 'no supported LLM CLI detected', terminalSupport };
   }
 
+  const withMaybeRl = async (fn) => {
+    if (providedRl) return await fn(providedRl);
+    return await withRl(fn);
+  };
+
   const chosenTool =
     tools.length === 1
       ? tools[0]
       : tools.find((t) => t.id === preferredToolId) ||
-        (await withRl(async (rl) => {
-          const defaultIndex = Math.max(
-            0,
-            tools.findIndex((t) => t.id === 'codex')
-          );
-          const picked = await promptSelect(rl, {
-            title:
-              `${bold('Pick an LLM CLI')}\n` +
-              `${dim('We will launch it with a pre-filled migration prompt so it can run the port and resolve conflicts.')}`,
-            options: tools.map((t) => ({
-              value: t.id,
-              label: `${cyan(t.id)} — ${t.label}${t.note ? ` ${dim(`— ${t.note}`)}` : ''}`,
-            })),
-            defaultIndex,
-          });
-          return tools.find((t) => t.id === picked) || tools[0];
-        }));
+        (!isTty()
+          ? tools.find((t) => t.id === 'codex') || tools[0]
+          : await withMaybeRl(async (rl) => {
+              const defaultIndex = Math.max(0, tools.findIndex((t) => t.id === 'codex'));
+              const picked = await promptSelect(rl, {
+                title:
+                  `${bold('Pick an LLM CLI')}\n` +
+                  `${dim('We will launch it with a pre-filled migration prompt so it can run the port and resolve conflicts.')}`,
+                options: tools.map((t) => ({
+                  value: t.id,
+                  label: `${cyan(t.id)} — ${t.label}${t.note ? ` ${dim(`— ${t.note}`)}` : ''}`,
+                })),
+                defaultIndex,
+              });
+              return tools.find((t) => t.id === picked) || tools[0];
+            }));
 
   const launchOptions = [];
   if (terminalSupport.ok) {
@@ -109,20 +130,22 @@ export async function launchLlmAssistant({
   const launchMode =
     launchOptions.length === 1
       ? launchOptions[0].value
-      : await withRl(async (rl) => {
-          return await promptSelect(rl, {
-            title: `${bold('How do you want to run the migration assistant?')}`,
-            options: launchOptions,
-            defaultIndex: 0,
+      : !isTty()
+        ? launchOptions[0].value
+        : await withMaybeRl(async (rl) => {
+            return await promptSelect(rl, {
+              title: `${bold('How do you want to run the migration assistant?')}`,
+              options: launchOptions,
+              defaultIndex: 0,
+            });
           });
-        });
 
   const permissionMode =
     chosenTool.id !== 'codex'
       ? null
       : CODEX_PERMISSION_MODES.length === 1 || !isTty()
         ? defaultPermissionMode
-        : await withRl(async (rl) => {
+        : await withMaybeRl(async (rl) => {
             const opts = codexPermissionOptions();
             const v = await promptSelect(rl, {
               title:
@@ -173,7 +196,17 @@ export async function launchLlmAssistant({
     // eslint-disable-next-line no-console
     console.log(dim(`Starting: ${chosenTool.cmd}`));
 
-    await run(chosenTool.cmd, [], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    if (chosenTool.cmd === 'claude') {
+      // Claude Code supports starting interactive mode with an initial prompt:
+      // `claude "query"`.
+      await run('claude', [prompt], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    } else if (chosenTool.cmd === 'opencode') {
+      // OpenCode supports starting the TUI with an initial prompt:
+      // `opencode --prompt "..."`.
+      await run('opencode', ['--prompt', prompt], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    } else {
+      await run(chosenTool.cmd, [], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    }
     return { ok: true, launched: true, mode: 'here', tool: chosenTool.id, permissionMode, terminalSupport };
   }
 

package/scripts/utils/llm/happys_runner.mjs

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Returns an absolute path to this package's `bin/happys.mjs` if present.
+ * This is the most reliable way to re-run Happy Stacks commands from an LLM prompt
+ * when `npx` is unreliable (e.g. npm cache permission issues).
+ */
+export function resolveLocalHappyStacksHappysMjsPath() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // scripts/utils/llm
+    const root = resolve(here, '../../..'); // package root (contains bin/ and scripts/)
+    const p = join(root, 'bin', 'happys.mjs');
+    return existsSync(p) ? p : '';
+  } catch {
+    return '';
+  }
+}
+
+export function buildHappyStacksRunnerShellSnippet({ preferLocalBin = true } = {}) {
+  const localBin = preferLocalBin ? resolveLocalHappyStacksHappysMjsPath() : '';
+  const localClause = localBin
+    ? [
+        `HS_LOCAL_BIN=${JSON.stringify(localBin)}`,
+        '  if [ -f "$HS_LOCAL_BIN" ]; then',
+        '    node "$HS_LOCAL_BIN" "$@"',
+        '    return $?',
+        '  fi',
+      ].join('\n')
+    : '';
+
+  return [
+    'Happy Stacks command runner:',
+    '- In the commands below, run `hs ...`.',
+    '- This avoids `npx` flakiness by preferring a local `bin/happys.mjs` when available.',
+    '',
+    '```bash',
+    'hs() {',
+    '  # Prefer an installed `happys` if present.',
+    '  if command -v happys >/dev/null 2>&1; then',
+    '    happys "$@"',
+    '    return $?',
+    '  fi',
+    localClause,
+    '  # Fallback: npx. Work around broken ~/.npm perms by using a fresh writable cache dir.',
+    '  if command -v npx >/dev/null 2>&1; then',
+    '    local cache_dir',
+    '    cache_dir="${HAPPY_STACKS_NPX_CACHE_DIR:-$(mktemp -d)}"',
+    '    npm_config_cache="$cache_dir" npm_config_update_notifier=false npx --yes happy-stacks@latest "$@"',
+    '    return $?',
+    '  fi',
+    '  echo "Missing happys and npx. Install Node/npm or install happy-stacks."',
+    '  return 1',
+    '}',
+    '```',
+    '',
+  ].join('\n');
+}
+

package/scripts/utils/llm/tools.mjs

@@ -17,7 +17,7 @@ const KNOWN_LLM_TOOLS = [
     id: 'claude',
     cmd: 'claude',
     label: 'Claude CLI',
-    note: 'Interactive launch supported (prompt will be copied/printed).',
+    note: 'Supports starting interactive mode with an initial prompt.',
     supportsPromptStdin: false,
     supportsAutoExec: false,
   },
@@ -25,7 +25,7 @@ const KNOWN_LLM_TOOLS = [
     id: 'opencode',
     cmd: 'opencode',
     label: 'OpenCode',
-    note: 'Interactive launch supported (prompt will be copied/printed).',
+    note: 'Supports starting TUI with an initial prompt.',
     supportsPromptStdin: false,
     supportsAutoExec: false,
   },
@@ -33,7 +33,7 @@ const KNOWN_LLM_TOOLS = [
     id: 'aider',
     cmd: 'aider',
     label: 'Aider',
-    note: 'Interactive launch supported (prompt will be copied/printed).',
+    note: 'Prompt injection varies by mode; copy/paste fallback supported.',
     supportsPromptStdin: false,
     supportsAutoExec: false,
   },

package/scripts/utils/proc/pm.mjs

@@ -105,7 +105,7 @@ function resolveStackCacheBaseDirFromEnv(env) {
   }
 }
 
-async function applyStackCacheEnv(baseEnv) {
+export async function applyStackCacheEnv(baseEnv) {
   const env = { ...(baseEnv && typeof baseEnv === 'object' ? baseEnv : process.env) };
   const envFile = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim();
   const stackCacheBase = resolveStackCacheBaseDirFromEnv(env);