@happier-dev/stack 0.1.0-preview.9.1 → 0.1.0

package/scripts/utils/stack/stop.mjs

@@ -3,11 +3,12 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { getComponentDir } from '../paths/paths.mjs';
-import { isPidAlive, readPidState } from '../expo/expo.mjs';
+import { isPidAlive, killPid, readPidState } from '../expo/expo.mjs';
 import { stopLocalDaemon } from '../../daemon.mjs';
 import { stopHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
-import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './runtime_state.mjs';
-import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedles } from '../proc/ownership.mjs';
+import { deleteStackRuntimeStateFile, readStackRuntimeStateFile } from './runtime_state.mjs';
+import { getProcessGroupId, getPsEnvLine, killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedles } from '../proc/ownership.mjs';
+import { terminateProcessGroup } from '../proc/terminate.mjs';
 import { coercePort } from '../server/port.mjs';
 import { resolvePreferredStackDaemonStatePaths } from '../auth/credentials_paths.mjs';
 
@@ -155,7 +156,7 @@ export async function stopStackWithEnv({
 
   // Preferred: stop stack-started processes (by PID) recorded in stack.runtime.json.
   // This is safer than killing whatever happens to listen on a port, and doesn't rely on the runner's shutdown handler.
-  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeStatePath = join(baseDir, 'stack.runtime.json');
   const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
   const runnerPid = Number(runtimeState?.ownerPid);
   const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
@@ -170,6 +171,32 @@ export async function stopStackWithEnv({
     const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: key, json });
     if (res.killed) {
       killedProcessPids.push({ key, pid, reason: res.reason, pgid: res.pgid ?? null });
+      continue;
+    }
+
+    // Back-compat for earlier "stackless" runs:
+    // Some repo-local runs started infra without HAPPIER_STACK_ENV_FILE/HAPPIER_HOME_DIR markers.
+    // For ephemeral stacks, allow stopping runtime-recorded PIDs when the process environment still
+    // proves the stack name, to avoid leaving orphaned servers/expo after quitting the TUI.
+    if (runtimeState?.ephemeral && res.reason === 'not_owned') {
+      // eslint-disable-next-line no-await-in-loop
+      const line = await getPsEnvLine(pid);
+      if (line && line.includes(`HAPPIER_STACK_STACK=${stackName}`)) {
+        // eslint-disable-next-line no-await-in-loop
+        const pgid = await getProcessGroupId(pid);
+        if (pgid) {
+          // eslint-disable-next-line no-await-in-loop
+          const terminated = await terminateProcessGroup(pgid, { graceMs: 800, signal: 'SIGTERM' });
+          if (terminated.ok) {
+            killedProcessPids.push({ key, pid, reason: 'killed_ephemeral_runtime_pgid', pgid });
+            continue;
+          }
+        }
+        // Fallback: kill the pid directly.
+        // eslint-disable-next-line no-await-in-loop
+        await killPid(pid);
+        killedProcessPids.push({ key, pid, reason: 'killed_ephemeral_runtime_pid_only', pgid: pgid ?? null });
+      }
     }
   }
   actions.runner = { stopped: false, pid: Number.isFinite(runnerPid) ? runnerPid : null, reason: runtimeState ? 'not_running_or_not_owned' : 'missing_state' };
@@ -185,8 +212,13 @@ export async function stopStackWithEnv({
   }
 
   try {
-    await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
-    actions.daemonStopped = true;
+    // If happier-cli isn't built yet (common in repo checkouts), running `happier.mjs` can fail noisily.
+    // Stopping stack infra should still work without the daemon stop step.
+    const cliDistIndex = join(cliDir, 'dist', 'index.mjs');
+    if (existsSync(cliDistIndex)) {
+      await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
+      actions.daemonStopped = true;
+    }
   } catch (e) {
     actions.errors.push({ step: 'daemon', error: e instanceof Error ? e.message : String(e) });
   }
@@ -201,8 +233,15 @@ export async function stopStackWithEnv({
     actions.runner = { stopped: res.killed, pid: runnerPid, reason: res.reason };
   }
 
-  // Only delete runtime state if the runner is confirmed stopped (or not running).
-  if (!isPidAlive(runnerPid)) {
+  // Only delete runtime state if all runtime-tracked pids are confirmed stopped.
+  // This avoids losing the only reliable link between a stack and its infra pids.
+  const runtimeTrackedPids = [
+    runnerPid,
+    ...Object.values(processes).map((p) => Number(p)),
+  ]
+    .filter((p) => Number.isFinite(p) && p > 1);
+  const anyRuntimePidAlive = runtimeTrackedPids.some((p) => isPidAlive(p));
+  if (!anyRuntimePidAlive) {
     await deleteStackRuntimeStateFile(runtimeStatePath);
   }
 
@@ -269,6 +308,20 @@ export async function stopStackWithEnv({
       .filter((pid) => Number.isFinite(pid) && pid > 1);
 
     const swept = [];
+    const sweepPidDirect = async (pid, reason) => {
+      const pgid = await getProcessGroupId(pid);
+      if (pgid) {
+        const terminated = await terminateProcessGroup(pgid, { graceMs: 800, signal: 'SIGTERM' });
+        if (terminated.ok) {
+          swept.push({ pid, reason, pgid });
+          return true;
+        }
+      }
+      await killPid(pid);
+      swept.push({ pid, reason, pgid: pgid ?? null });
+      return true;
+    };
+
     for (const pid of Array.from(new Set(pids))) {
       if (!isPidAlive(pid)) continue;
       // eslint-disable-next-line no-await-in-loop
@@ -277,6 +330,27 @@ export async function stopStackWithEnv({
         swept.push({ pid, reason: res.reason, pgid: res.pgid ?? null });
       }
     }
+
+    // Repo-local fallback: older stackless runs may have omitted HAPPIER_STACK_ENV_FILE/HAPPIER_STACK_PROCESS_KIND markers.
+    // When runtime state is missing/stale, allow sweeping by the (stackName + repoDir) env needles for repo-local stacks.
+    // This is intentionally restricted to repo-local stack names to avoid killing unrelated long-lived processes.
+    const repoDir = String(env.HAPPIER_STACK_REPO_DIR ?? '').trim();
+    const isRepoLocalStack = stackName && stackName !== 'main' && String(stackName).startsWith('repo-');
+    if (autoSweepResolved && shouldAutoSweep && swept.length === 0 && isRepoLocalStack && repoDir) {
+      const repoLocal = await listPidsWithEnvNeedles([
+        `HAPPIER_STACK_STACK=${stackName}`,
+        `HAPPIER_STACK_REPO_DIR=${repoDir}`,
+      ]);
+      const repoLocalPids = repoLocal
+        .filter((pid) => pid !== process.pid)
+        .filter((pid) => Number.isFinite(pid) && pid > 1);
+      for (const pid of Array.from(new Set(repoLocalPids))) {
+        if (!isPidAlive(pid)) continue;
+        // eslint-disable-next-line no-await-in-loop
+        await sweepPidDirect(pid, 'killed_repo_local_stackless_sweep');
+      }
+    }
+
     actions.sweep = { pids: swept, auto: shouldAutoSweep && !sweepOwned };
   }
 

package/scripts/utils/tauri/stack_overrides.mjs

@@ -7,6 +7,8 @@ function getTrimmedEnv(env, key) {
 export function applyStackTauriOverrides({ tauriConfig, env }) {
   const identifierOverride = getTrimmedEnv(env, 'HAPPIER_STACK_TAURI_IDENTIFIER');
   const productNameOverride = getTrimmedEnv(env, 'HAPPIER_STACK_TAURI_PRODUCT_NAME');
+  const createUpdaterArtifactsOverride = getTrimmedEnv(env, 'HAPPIER_STACK_TAURI_CREATE_UPDATER_ARTIFACTS');
+  const signingPrivateKey = getTrimmedEnv(env, 'TAURI_SIGNING_PRIVATE_KEY');
 
   tauriConfig.identifier = identifierOverride || 'com.happier.stack';
   tauriConfig.productName = productNameOverride || tauriConfig.productName || 'Happier';
@@ -18,5 +20,19 @@ export function applyStackTauriOverrides({ tauriConfig, env }) {
     }));
   }
 
+  // Tauri's updater artifact bundling requires a signing private key at build time.
+  // For local user builds we keep the updater plugin configured (pubkey/endpoints) but skip generating updater artifacts
+  // unless signing is explicitly enabled.
+  if (tauriConfig.bundle && typeof tauriConfig.bundle === 'object') {
+    const shouldCreateUpdaterArtifacts =
+      createUpdaterArtifactsOverride !== ''
+        ? createUpdaterArtifactsOverride !== '0'
+        : signingPrivateKey !== ''
+          ? (tauriConfig.bundle.createUpdaterArtifacts ?? true)
+          : false;
+
+    tauriConfig.bundle.createUpdaterArtifacts = shouldCreateUpdaterArtifacts;
+  }
+
   return tauriConfig;
 }

package/scripts/utils/tui/actions.mjs

@@ -0,0 +1,22 @@
+export function buildTuiAuthArgs({ happysBin, stackName, force = false } = {}) {
+  const bin = String(happysBin ?? '').trim();
+  const name = String(stackName ?? '').trim();
+  if (!bin) throw new Error('buildTuiAuthArgs: happysBin is required');
+  if (!name) throw new Error('buildTuiAuthArgs: stackName is required');
+  return [bin, 'stack', 'auth', name, 'login', ...(force ? ['--force'] : [])];
+}
+
+export function buildTuiDaemonStartArgs({ happysBin, stackName } = {}) {
+  const bin = String(happysBin ?? '').trim();
+  const name = String(stackName ?? '').trim();
+  if (!bin) throw new Error('buildTuiDaemonStartArgs: happysBin is required');
+  if (!name) throw new Error('buildTuiDaemonStartArgs: stackName is required');
+  return [bin, 'stack', 'daemon', name, 'start'];
+}
+
+export function shouldHoldAfterAuthExit({ code, signal } = {}) {
+  // Success should return immediately to the TUI. Failures should hold so users can read the error output.
+  if (signal) return true;
+  return Number(code) !== 0;
+}
+

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

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildTuiAuthArgs, buildTuiDaemonStartArgs, shouldHoldAfterAuthExit } from './actions.mjs';
+
+test('buildTuiAuthArgs builds stack-scoped auth login args', () => {
+  assert.deepEqual(buildTuiAuthArgs({ happysBin: 'bin/hstack.mjs', stackName: 'main', force: false }), [
+    'bin/hstack.mjs',
+    'stack',
+    'auth',
+    'main',
+    'login',
+  ]);
+  assert.deepEqual(buildTuiAuthArgs({ happysBin: 'bin/hstack.mjs', stackName: 'main', force: true }), [
+    'bin/hstack.mjs',
+    'stack',
+    'auth',
+    'main',
+    'login',
+    '--force',
+  ]);
+});
+
+test('buildTuiDaemonStartArgs builds stack-scoped daemon start args', () => {
+  assert.deepEqual(buildTuiDaemonStartArgs({ happysBin: 'bin/hstack.mjs', stackName: 'main' }), [
+    'bin/hstack.mjs',
+    'stack',
+    'daemon',
+    'main',
+    'start',
+  ]);
+});
+
+test('shouldHoldAfterAuthExit holds on failure but not on success', () => {
+  assert.equal(shouldHoldAfterAuthExit({ code: 0, signal: null }), false);
+  assert.equal(shouldHoldAfterAuthExit({ code: 1, signal: null }), true);
+  assert.equal(shouldHoldAfterAuthExit({ code: 0, signal: 'SIGINT' }), true);
+});
+

package/scripts/utils/tui/args.mjs

@@ -0,0 +1,49 @@
+export function isTuiHelpRequest(argv) {
+  if (!Array.isArray(argv)) return false;
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === 'help')) return true;
+  return false;
+}
+
+export function normalizeTuiForwardedArgs(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return ['dev'];
+
+  // UX: `hstack tui -- --restart --mobile` is intended to mean "tui dev --restart --mobile".
+  // If the user only passed flags, treat them as flags for the default `dev` command.
+  const args = argv.filter((a) => String(a ?? '').trim() !== '');
+  const allFlags = args.length > 0 && args.every((a) => String(a ?? '').trim().startsWith('-'));
+  if (allFlags) return ['dev', ...args];
+
+  return args.length ? args : ['dev'];
+}
+
+export function inferTuiStackName(argv, env = process.env) {
+  const args = Array.isArray(argv) ? argv : [];
+
+  const stackIdx = args.indexOf('stack');
+  if (stackIdx >= 0) {
+    const explicitName = (args[stackIdx + 2] ?? '').toString().trim();
+    if (explicitName && !explicitName.startsWith('-')) return explicitName;
+  }
+
+  const envStack = (env.HAPPIER_STACK_STACK ?? '').toString().trim();
+  return envStack || null;
+}
+
+export function isTuiStartLikeForwardedArgs(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  if (!args.length) return false;
+
+  const first = String(args[0] ?? '').trim();
+  if (first === 'dev' || first === 'start') return true;
+
+  const stackIdx = args.indexOf('stack');
+  if (stackIdx < 0) return false;
+  const subcmd = String(args[stackIdx + 1] ?? '').trim();
+  return subcmd === 'dev' || subcmd === 'start';
+}
+
+export function isTuiRestartableForwardedArgs(argv) {
+  // Today we only support restart for long-lived stack processes (dev/start).
+  // Keeping this as a separate predicate avoids expanding restart support by accident.
+  return isTuiStartLikeForwardedArgs(argv);
+}

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

@@ -0,0 +1,70 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  inferTuiStackName,
+  isTuiHelpRequest,
+  isTuiRestartableForwardedArgs,
+  isTuiStartLikeForwardedArgs,
+  normalizeTuiForwardedArgs,
+} from './args.mjs';
+
+test('normalizeTuiForwardedArgs defaults to dev for empty args', () => {
+  assert.deepEqual(normalizeTuiForwardedArgs([]), ['dev']);
+});
+
+test('normalizeTuiForwardedArgs defaults to dev when only flags are provided', () => {
+  assert.deepEqual(normalizeTuiForwardedArgs(['--restart', '--mobile']), ['dev', '--restart', '--mobile']);
+  assert.deepEqual(normalizeTuiForwardedArgs(['--json']), ['dev', '--json']);
+});
+
+test('normalizeTuiForwardedArgs preserves explicit args', () => {
+  assert.deepEqual(normalizeTuiForwardedArgs(['stack', 'dev', 'exp1']), ['stack', 'dev', 'exp1']);
+});
+
+test('isTuiHelpRequest only matches explicit help', () => {
+  assert.equal(isTuiHelpRequest([]), false);
+  assert.equal(isTuiHelpRequest(['--help']), true);
+  assert.equal(isTuiHelpRequest(['help']), true);
+  assert.equal(isTuiHelpRequest(['stack', 'dev', 'exp1']), false);
+});
+
+test('inferTuiStackName returns explicit stack name for stack command', () => {
+  const stackName = inferTuiStackName(['stack', 'dev', 'resume-upstream'], {});
+  assert.equal(stackName, 'resume-upstream');
+});
+
+test('inferTuiStackName uses env stack only when explicitly set', () => {
+  const stackName = inferTuiStackName(['dev'], { HAPPIER_STACK_STACK: 'main' });
+  assert.equal(stackName, 'main');
+});
+
+test('inferTuiStackName stays stackless when no explicit stack context is present', () => {
+  const stackName = inferTuiStackName(['dev'], { HAPPIER_STACK_STACK: '' });
+  assert.equal(stackName, null);
+});
+
+test('isTuiStartLikeForwardedArgs matches stack dev/start forms', () => {
+  assert.equal(isTuiStartLikeForwardedArgs(['stack', 'dev', 'x']), true);
+  assert.equal(isTuiStartLikeForwardedArgs(['stack', 'start', 'x']), true);
+  assert.equal(isTuiStartLikeForwardedArgs(['stack', 'auth', 'x', 'login']), false);
+});
+
+test('isTuiStartLikeForwardedArgs matches plain dev/start forms', () => {
+  assert.equal(isTuiStartLikeForwardedArgs(['dev']), true);
+  assert.equal(isTuiStartLikeForwardedArgs(['start']), true);
+  assert.equal(isTuiStartLikeForwardedArgs(['dev', '--json']), true);
+  assert.equal(isTuiStartLikeForwardedArgs(['stop']), false);
+});
+
+test('isTuiRestartableForwardedArgs only allows restart for start-like commands', () => {
+  assert.equal(isTuiRestartableForwardedArgs(['stack', 'dev', 'x']), true);
+  assert.equal(isTuiRestartableForwardedArgs(['stack', 'start', 'x']), true);
+  assert.equal(isTuiRestartableForwardedArgs(['dev']), true);
+  assert.equal(isTuiRestartableForwardedArgs(['start']), true);
+
+  assert.equal(isTuiRestartableForwardedArgs(['stack', 'auth', 'x', 'login']), false);
+  assert.equal(isTuiRestartableForwardedArgs(['stack', 'daemon', 'x', 'start']), false);
+  assert.equal(isTuiRestartableForwardedArgs(['stack', 'summary', 'x']), false);
+  assert.equal(isTuiRestartableForwardedArgs(['stop']), false);
+});

package/scripts/utils/tui/daemon_auth_notice.mjs

@@ -0,0 +1,74 @@
+function isTruthy(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'y';
+}
+
+export function buildDaemonAuthNotice({
+  stackName,
+  internalServerUrl = '',
+  daemonPid = null,
+  authed = false,
+  // Let callers opt out if daemon isn't intended to run.
+  startDaemon = true,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+  const pid = Number(daemonPid);
+  const isRunning = Number.isFinite(pid) && pid > 1;
+  if (!startDaemon) return { show: false, summaryLines: [], paneTitle: null, paneLines: [] };
+  if (isRunning) return { show: false, summaryLines: [], paneTitle: null, paneLines: [] };
+
+  const url = String(internalServerUrl ?? '').trim();
+  if (!url) {
+    return {
+      show: true,
+      summaryLines: ['Daemon status pending', 'waiting for the stack server to start...'],
+      paneTitle: 'daemon (WAITING FOR SERVER)',
+      paneLines: [
+        'Daemon status pending',
+        '',
+        'The stack is still starting up, and the server URL is not known yet.',
+        '',
+        'Once the server is ready, this pane will update with sign-in guidance if needed.',
+      ],
+    };
+  }
+
+  if (!authed) {
+    return {
+      show: true,
+      summaryLines: ['Daemon sign-in required', `action: press "a" to sign in for stack "${name}"`],
+      paneTitle: 'daemon (SIGN-IN REQUIRED)',
+      paneLines: [
+        'Sign-in required',
+        `stack:  ${name}`,
+        `server: ${url}`,
+        '',
+        'Without daemon sign-in, the UI may show "no machine" for this stack.',
+        '',
+        `press "a" to run: hstack stack auth ${name} login`,
+      ],
+    };
+  }
+
+  return {
+    show: true,
+    summaryLines: ['Daemon not running', 'starting automatically when ready...'],
+    paneTitle: 'daemon (NOT RUNNING)',
+    paneLines: [
+      'daemon not running',
+      `stack:  ${name}`,
+      `server: ${url}`,
+      '',
+      'This TUI will try to start the daemon automatically.',
+      '',
+      `manual: hstack stack daemon ${name} start`,
+    ],
+  };
+}
+
+export function parseStartDaemonFlagFromEnv(env = process.env) {
+  // This mirrors dev.mjs default behavior: startDaemon is on unless explicitly disabled.
+  const raw = String(env?.HAPPIER_STACK_START_DAEMON ?? '').trim();
+  if (!raw) return true;
+  return isTruthy(raw);
+}

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

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildDaemonAuthNotice } from './daemon_auth_notice.mjs';
+
+test('buildDaemonAuthNotice returns an auth-required banner when daemon is not running and credentials are missing', () => {
+  const notice = buildDaemonAuthNotice({
+    stackName: 'repo-dev-abc123',
+    internalServerUrl: 'http://127.0.0.1:53288',
+    daemonPid: null,
+    authed: false,
+    startDaemon: true,
+  });
+  assert.equal(notice.show, true);
+  assert.ok(notice.summaryLines.join('\n').toLowerCase().includes('sign-in required'));
+  assert.equal(notice.paneTitle, 'daemon (SIGN-IN REQUIRED)');
+  assert.ok(notice.paneLines.join('\n').includes('press "a"'));
+});
+
+test('buildDaemonAuthNotice returns no notice when daemon is running', () => {
+  const notice = buildDaemonAuthNotice({
+    stackName: 'repo-dev-abc123',
+    internalServerUrl: 'http://127.0.0.1:53288',
+    daemonPid: 123,
+    authed: false,
+    startDaemon: true,
+  });
+  assert.equal(notice.show, false);
+});
+
+test('buildDaemonAuthNotice indicates waiting when server url is missing', () => {
+  const notice = buildDaemonAuthNotice({
+    stackName: 'repo-dev-abc123',
+    internalServerUrl: '',
+    daemonPid: null,
+    authed: false,
+    startDaemon: true,
+  });
+  assert.equal(notice.show, true);
+  assert.equal(notice.paneTitle, 'daemon (WAITING FOR SERVER)');
+  assert.ok(notice.paneLines.join('\n').toLowerCase().includes('still starting'));
+});
+
+test('buildDaemonAuthNotice returns no notice when startDaemon=false', () => {
+  const notice = buildDaemonAuthNotice({
+    stackName: 'repo-dev-abc123',
+    internalServerUrl: 'http://127.0.0.1:53288',
+    daemonPid: null,
+    authed: false,
+    startDaemon: false,
+  });
+  assert.equal(notice.show, false);
+});

package/scripts/utils/tui/daemon_autostart.mjs

@@ -0,0 +1,34 @@
+export function shouldAttemptTuiDaemonAutostart({
+  stackName,
+  isStartLike,
+  startDaemon,
+  internalServerUrl,
+  authed,
+  daemonPid,
+  inProgress,
+  lastAttemptAtMs,
+  nowMs,
+  minIntervalMs = 12_000,
+} = {}) {
+  const name = String(stackName ?? '').trim();
+  if (!name) return false;
+  if (!isStartLike) return false;
+  if (!startDaemon) return false;
+  const url = String(internalServerUrl ?? '').trim();
+  if (!url) return false;
+  if (!authed) return false;
+  const pid = Number(daemonPid);
+  const daemonRunning = Number.isFinite(pid) && pid > 1;
+  if (daemonRunning) return false;
+  if (inProgress) return false;
+
+  const now = Number(nowMs);
+  const last = Number(lastAttemptAtMs);
+  const min = Number(minIntervalMs);
+  if (Number.isFinite(now) && Number.isFinite(last) && Number.isFinite(min) && min > 0) {
+    if (last > 0 && now - last < min) return false;
+  }
+
+  return true;
+}
+

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

@@ -0,0 +1,157 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { shouldAttemptTuiDaemonAutostart } from './daemon_autostart.mjs';
+
+test('shouldAttemptTuiDaemonAutostart requires stack context and start-like invocation', () => {
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: '',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: false,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+});
+
+test('shouldAttemptTuiDaemonAutostart fails closed when daemon is not expected, server is unknown, creds missing, or daemon is running', () => {
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: false,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: '',
+      authed: true,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: false,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: 123,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+});
+
+test('shouldAttemptTuiDaemonAutostart rate limits and de-dupes concurrent attempts', () => {
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: null,
+      inProgress: true,
+      lastAttemptAtMs: 0,
+      nowMs: 1000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 5000,
+      nowMs: 1000 + 5000,
+      minIntervalMs: 10_000,
+    }),
+    false
+  );
+});
+
+test('shouldAttemptTuiDaemonAutostart allows attempt when all conditions are satisfied', () => {
+  assert.equal(
+    shouldAttemptTuiDaemonAutostart({
+      stackName: 'repo-dev-abc',
+      isStartLike: true,
+      startDaemon: true,
+      internalServerUrl: 'http://127.0.0.1:1234',
+      authed: true,
+      daemonPid: null,
+      inProgress: false,
+      lastAttemptAtMs: 0,
+      nowMs: 20_000,
+      minIntervalMs: 10_000,
+    }),
+    true
+  );
+});
+