@happier-dev/stack 0.1.0-preview.74.1

package/scripts/utils/auth/credentials_paths.mjs

@@ -0,0 +1,181 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileHasContent } from '../fs/file_has_content.mjs';
+
+const SERVER_ID_SAFE_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+function normalizeServerUrl(url) {
+  return String(url ?? '').trim().replace(/\/+$/, '');
+}
+
+function sanitizeServerIdForFilesystem(raw, fallback = 'cloud') {
+  const value = String(raw ?? '').trim();
+  if (!value) return String(fallback ?? '').trim() || 'cloud';
+  if (value === '.' || value === '..') return String(fallback ?? '').trim() || 'cloud';
+  if (value.includes('/') || value.includes('\\')) return String(fallback ?? '').trim() || 'cloud';
+  if (!SERVER_ID_SAFE_RE.test(value)) return String(fallback ?? '').trim() || 'cloud';
+  return value;
+}
+
+function resolveActiveServerIdOverride(env = process.env) {
+  const raw = String(env?.HAPPIER_ACTIVE_SERVER_ID ?? '').trim();
+  if (!raw) return '';
+  return sanitizeServerIdForFilesystem(raw, '');
+}
+
+function deriveServerIdFromUrl(url) {
+  const normalized = normalizeServerUrl(url);
+  let h = 2166136261;
+  for (let i = 0; i < normalized.length; i += 1) {
+    h ^= normalized.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `env_${(h >>> 0).toString(16)}`;
+}
+
+function requireCliHomeDir(cliHomeDir) {
+  const home = String(cliHomeDir ?? '').trim();
+  if (!home) {
+    throw new Error('cliHomeDir is required');
+  }
+  return home;
+}
+
+export function resolveStackCredentialPaths({ cliHomeDir, serverUrl = '', env = process.env }) {
+  const home = requireCliHomeDir(cliHomeDir);
+  const legacyPath = join(home, 'access.key');
+  const normalizedServerUrl = normalizeServerUrl(serverUrl);
+  const urlHashServerId = sanitizeServerIdForFilesystem(
+    normalizedServerUrl ? deriveServerIdFromUrl(normalizedServerUrl) : 'cloud',
+    'cloud'
+  );
+  const overrideServerId = resolveActiveServerIdOverride(env);
+  const activeServerId = overrideServerId || urlHashServerId;
+  const serverScopedPath = join(home, 'servers', activeServerId, 'access.key');
+  const urlHashServerScopedPath =
+    urlHashServerId && urlHashServerId !== activeServerId
+      ? join(home, 'servers', urlHashServerId, 'access.key')
+      : '';
+  const paths = [serverScopedPath, urlHashServerScopedPath, legacyPath].filter(Boolean);
+  return {
+    activeServerId,
+    urlHashServerId,
+    legacyPath,
+    serverScopedPath,
+    urlHashServerScopedPath,
+    paths,
+  };
+}
+
+export function resolveStackDaemonStatePaths({ cliHomeDir, serverUrl = '', env = process.env }) {
+  const home = requireCliHomeDir(cliHomeDir);
+  const normalizedServerUrl = normalizeServerUrl(serverUrl);
+  const urlHashServerId = sanitizeServerIdForFilesystem(
+    normalizedServerUrl ? deriveServerIdFromUrl(normalizedServerUrl) : 'cloud',
+    'cloud'
+  );
+  const overrideServerId = resolveActiveServerIdOverride(env);
+  const activeServerId = overrideServerId || urlHashServerId;
+
+  const legacyStatePath = join(home, 'daemon.state.json');
+  const legacyLockPath = join(home, 'daemon.state.json.lock');
+  const serverScopedStatePath = join(home, 'servers', activeServerId, 'daemon.state.json');
+  const serverScopedLockPath = join(home, 'servers', activeServerId, 'daemon.state.json.lock');
+  const urlHashServerScopedStatePath =
+    urlHashServerId && urlHashServerId !== activeServerId
+      ? join(home, 'servers', urlHashServerId, 'daemon.state.json')
+      : '';
+  const urlHashServerScopedLockPath =
+    urlHashServerId && urlHashServerId !== activeServerId
+      ? join(home, 'servers', urlHashServerId, 'daemon.state.json.lock')
+      : '';
+
+  return {
+    activeServerId,
+    urlHashServerId,
+    legacyStatePath,
+    legacyLockPath,
+    serverScopedStatePath,
+    serverScopedLockPath,
+    urlHashServerScopedStatePath,
+    urlHashServerScopedLockPath,
+    pairs: [
+      { statePath: serverScopedStatePath, lockPath: serverScopedLockPath },
+      ...(urlHashServerScopedStatePath
+        ? [{ statePath: urlHashServerScopedStatePath, lockPath: urlHashServerScopedLockPath }]
+        : []),
+      { statePath: legacyStatePath, lockPath: legacyLockPath },
+    ],
+  };
+}
+
+export function resolvePreferredStackDaemonStatePaths({ cliHomeDir, serverUrl = '', env = process.env }) {
+  const resolved = resolveStackDaemonStatePaths({ cliHomeDir, serverUrl, env });
+  const serverScopedExists =
+    fileHasContent(resolved.serverScopedStatePath) || existsSync(resolved.serverScopedLockPath);
+  if (serverScopedExists) {
+    return { statePath: resolved.serverScopedStatePath, lockPath: resolved.serverScopedLockPath };
+  }
+
+  if (resolved.urlHashServerScopedStatePath) {
+    const urlHashExists =
+      fileHasContent(resolved.urlHashServerScopedStatePath) || existsSync(resolved.urlHashServerScopedLockPath);
+    if (urlHashExists) {
+      return { statePath: resolved.urlHashServerScopedStatePath, lockPath: resolved.urlHashServerScopedLockPath };
+    }
+  }
+
+  const legacyExists = fileHasContent(resolved.legacyStatePath) || existsSync(resolved.legacyLockPath);
+  if (legacyExists) {
+    return { statePath: resolved.legacyStatePath, lockPath: resolved.legacyLockPath };
+  }
+
+  return { statePath: resolved.serverScopedStatePath, lockPath: resolved.serverScopedLockPath };
+}
+
+export function findExistingStackCredentialPath({ cliHomeDir, serverUrl = '', env = process.env }) {
+  const resolved = resolveStackCredentialPaths({ cliHomeDir, serverUrl, env });
+  if (fileHasContent(resolved.serverScopedPath)) return resolved.serverScopedPath;
+  if (resolved.urlHashServerScopedPath && fileHasContent(resolved.urlHashServerScopedPath)) {
+    return resolved.urlHashServerScopedPath;
+  }
+  if (fileHasContent(resolved.legacyPath)) return resolved.legacyPath;
+  return null;
+}
+
+export function findAnyCredentialPathInCliHome({ cliHomeDir }) {
+  const home = String(cliHomeDir ?? '').trim();
+  if (!home) return null;
+
+  const serversDir = join(home, 'servers');
+  try {
+    const entries = readdirSync(serversDir, { withFileTypes: true })
+      .filter((ent) => ent.isDirectory())
+      .map((ent) => ent.name)
+      .sort();
+    let best = null;
+    let bestMtimeMs = -1;
+    for (const id of entries) {
+      const candidate = join(serversDir, id, 'access.key');
+      if (!fileHasContent(candidate)) continue;
+      let mtimeMs = 0;
+      try {
+        mtimeMs = Number(statSync(candidate).mtimeMs) || 0;
+      } catch {
+        mtimeMs = 0;
+      }
+      if (!best || mtimeMs >= bestMtimeMs) {
+        best = candidate;
+        bestMtimeMs = mtimeMs;
+      }
+    }
+    if (best) return best;
+  } catch {
+    // ignore
+  }
+
+  const legacy = join(home, 'access.key');
+  if (fileHasContent(legacy)) return legacy;
+
+  return null;
+}

package/scripts/utils/auth/credentials_paths.test.mjs

@@ -0,0 +1,187 @@
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  resolveStackCredentialPaths,
+  findExistingStackCredentialPath,
+  findAnyCredentialPathInCliHome,
+  resolveStackDaemonStatePaths,
+  resolvePreferredStackDaemonStatePaths,
+} from './credentials_paths.mjs';
+
+test('resolveStackCredentialPaths returns legacy + server-scoped paths', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cred-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl });
+  assert.equal(out.legacyPath, join(dir, 'access.key'));
+  assert.ok(out.serverScopedPath.startsWith(join(dir, 'servers', 'env_')));
+  assert.ok(out.serverScopedPath.endsWith('/access.key'));
+  assert.deepEqual(out.paths, [out.serverScopedPath, out.legacyPath]);
+});
+
+test('findExistingStackCredentialPath prefers server-scoped credentials', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cred-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl });
+
+  await mkdir(join(dir, 'servers', out.activeServerId), { recursive: true });
+  await writeFile(out.legacyPath, 'legacy\n', 'utf-8');
+  await writeFile(out.serverScopedPath, 'server\n', 'utf-8');
+
+  const found = findExistingStackCredentialPath({ cliHomeDir: dir, serverUrl });
+  assert.equal(found, out.serverScopedPath);
+});
+
+test('findExistingStackCredentialPath falls back to legacy access.key', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cred-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl });
+  await writeFile(out.legacyPath, 'legacy\n', 'utf-8');
+
+  const found = findExistingStackCredentialPath({ cliHomeDir: dir, serverUrl });
+  assert.equal(found, out.legacyPath);
+});
+
+test('findExistingStackCredentialPath keeps server-url isolation and falls back to legacy when resolved scope paths are empty', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cred-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackCredentialPaths({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+
+  const otherServerScoped = join(dir, 'servers', 'stack_dev-auth__id_default', 'access.key');
+  await mkdir(join(dir, 'servers', 'stack_dev-auth__id_default'), { recursive: true });
+  await writeFile(out.legacyPath, 'legacy\n', 'utf-8');
+  await writeFile(otherServerScoped, 'server-scoped\n', 'utf-8');
+
+  const found = findExistingStackCredentialPath({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+  assert.equal(found, out.legacyPath);
+});
+
+test('findAnyCredentialPathInCliHome prefers server-scoped credentials over legacy', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-any-cred-paths-'));
+  const legacyPath = join(dir, 'access.key');
+  const serverScopedPath = join(dir, 'servers', 'stack_main__id_default', 'access.key');
+
+  await mkdir(join(dir, 'servers', 'stack_main__id_default'), { recursive: true });
+  await writeFile(legacyPath, 'legacy\n', 'utf-8');
+  await writeFile(serverScopedPath, 'server\n', 'utf-8');
+
+  const found = findAnyCredentialPathInCliHome({ cliHomeDir: dir });
+  assert.equal(found, serverScopedPath);
+});
+
+test('resolveStackCredentialPaths uses HAPPIER_ACTIVE_SERVER_ID when provided', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cred-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackCredentialPaths({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+  assert.equal(out.activeServerId, 'stack_main__id_default');
+  assert.ok(out.serverScopedPath.endsWith('/servers/stack_main__id_default/access.key'));
+  assert.ok(out.urlHashServerScopedPath.endsWith('/access.key'));
+  assert.notEqual(out.serverScopedPath, out.urlHashServerScopedPath);
+});
+
+test('findExistingStackCredentialPath falls back to url-hash path when stable scope path is empty', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cred-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackCredentialPaths({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+
+  await mkdir(join(dir, 'servers', out.urlHashServerId), { recursive: true });
+  await writeFile(out.urlHashServerScopedPath, 'legacy-hash\n', 'utf-8');
+
+  const found = findExistingStackCredentialPath({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+  assert.equal(found, out.urlHashServerScopedPath);
+});
+
+test('resolveStackDaemonStatePaths returns legacy + server-scoped state and lock paths', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-paths-'));
+  const serverUrl = 'http://127.0.0.1:3009';
+  const out = resolveStackDaemonStatePaths({ cliHomeDir: dir, serverUrl });
+
+  assert.equal(out.legacyStatePath, join(dir, 'daemon.state.json'));
+  assert.equal(out.legacyLockPath, join(dir, 'daemon.state.json.lock'));
+  assert.ok(out.serverScopedStatePath.startsWith(join(dir, 'servers', 'env_')));
+  assert.ok(out.serverScopedStatePath.endsWith('/daemon.state.json'));
+  assert.ok(out.serverScopedLockPath.endsWith('/daemon.state.json.lock'));
+});
+
+test('resolvePreferredStackDaemonStatePaths prefers server-scoped paths when present', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-paths-'));
+  const serverUrl = 'http://127.0.0.1:3010';
+  const out = resolveStackDaemonStatePaths({ cliHomeDir: dir, serverUrl });
+
+  await mkdir(join(dir, 'servers', out.activeServerId), { recursive: true });
+  await writeFile(out.serverScopedLockPath, `${process.pid}\n`, 'utf-8');
+
+  const preferred = resolvePreferredStackDaemonStatePaths({ cliHomeDir: dir, serverUrl });
+  assert.equal(preferred.statePath, out.serverScopedStatePath);
+  assert.equal(preferred.lockPath, out.serverScopedLockPath);
+});
+
+test('resolvePreferredStackDaemonStatePaths falls back to legacy paths', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-paths-'));
+  const serverUrl = 'http://127.0.0.1:3011';
+  const out = resolveStackDaemonStatePaths({ cliHomeDir: dir, serverUrl });
+
+  await writeFile(out.legacyLockPath, `${process.pid}\n`, 'utf-8');
+
+  const preferred = resolvePreferredStackDaemonStatePaths({ cliHomeDir: dir, serverUrl });
+  assert.equal(preferred.statePath, out.legacyStatePath);
+  assert.equal(preferred.lockPath, out.legacyLockPath);
+});
+
+test('resolvePreferredStackDaemonStatePaths falls back to url-hash server-scoped state when stable scope is empty', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-paths-'));
+  const serverUrl = 'http://127.0.0.1:3011';
+  const out = resolveStackDaemonStatePaths({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+
+  await mkdir(join(dir, 'servers', out.urlHashServerId), { recursive: true });
+  await writeFile(out.urlHashServerScopedLockPath, `${process.pid}\n`, 'utf-8');
+
+  const preferred = resolvePreferredStackDaemonStatePaths({
+    cliHomeDir: dir,
+    serverUrl,
+    env: { HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' },
+  });
+  assert.equal(preferred.statePath, out.urlHashServerScopedStatePath);
+  assert.equal(preferred.lockPath, out.urlHashServerScopedLockPath);
+});
+
+test('resolveStackCredentialPaths throws when cliHomeDir is empty', () => {
+  assert.throws(
+    () => resolveStackCredentialPaths({ cliHomeDir: '', serverUrl: 'http://127.0.0.1:3009' }),
+    /cliHomeDir is required/i
+  );
+});
+
+test('resolveStackDaemonStatePaths throws when cliHomeDir is empty', () => {
+  assert.throws(
+    () => resolveStackDaemonStatePaths({ cliHomeDir: '', serverUrl: 'http://127.0.0.1:3009' }),
+    /cliHomeDir is required/i
+  );
+});

package/scripts/utils/auth/daemon_gate.mjs

@@ -0,0 +1,66 @@
+import { findExistingStackCredentialPath, resolveStackCredentialPaths } from './credentials_paths.mjs';
+
+/**
+ * Shared policy for when the stack runner should start the Happier daemon.
+ *
+ * In `setup-pr` / `review-pr` guided login flows we intentionally start server+UI first,
+ * then guide authentication, then start daemon post-auth. Starting the daemon before
+ * credentials exist can strand it in its own auth flow (lock held, no machine registration),
+ * which leads to "no machines" in the UI.
+ */
+
+export function credentialsPathForCliHomeDir(cliHomeDir, serverUrl = '', env = process.env) {
+  const resolved = resolveStackCredentialPaths({ cliHomeDir, serverUrl, env });
+  return (
+    findExistingStackCredentialPath({ cliHomeDir, serverUrl, env }) ||
+    resolved.serverScopedPath
+  );
+}
+
+export function hasStackCredentials({ cliHomeDir, serverUrl = '', env = process.env }) {
+  if (!cliHomeDir) return false;
+  return Boolean(findExistingStackCredentialPath({ cliHomeDir, serverUrl, env }));
+}
+
+export function isAuthFlowEnabled(env) {
+  const v = (env?.HAPPIER_STACK_AUTH_FLOW ?? '').toString().trim();
+  const wait = (env?.HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH ?? '').toString().trim();
+  const isTrue = (s) => s === '1' || String(s).toLowerCase() === 'true';
+  return isTrue(v) || isTrue(wait);
+}
+
+/**
+ * Returns { ok: boolean, reason: string } where ok=true means it's safe to start the daemon now.
+ * When ok=false, callers should either:
+ * - run interactive auth first (TTY), or
+ * - skip daemon start without error in orchestrated auth flows, or
+ * - fail closed in non-interactive contexts.
+ */
+export function daemonStartGate({ env, cliHomeDir, serverUrl = '' }) {
+  const resolvedServerUrl = String(serverUrl ?? '').trim() || String(env?.HAPPIER_SERVER_URL ?? '').trim();
+  if (hasStackCredentials({ cliHomeDir, serverUrl: resolvedServerUrl, env })) {
+    return { ok: true, reason: 'credentials_present' };
+  }
+  if (isAuthFlowEnabled(env)) {
+    // Orchestrated auth flow (setup-pr/review-pr): keep server/UI up and let the orchestrator
+    // run guided login; starting the daemon now is counterproductive.
+    return { ok: false, reason: 'auth_flow_missing_credentials' };
+  }
+  return { ok: false, reason: 'missing_credentials' };
+}
+
+export function formatDaemonAuthRequiredError({ stackName, cliHomeDir, serverUrl = '' }) {
+  const name = (stackName ?? '').toString().trim() || 'main';
+  const resolved = resolveStackCredentialPaths({ cliHomeDir, serverUrl });
+  const path = `${resolved.legacyPath} or ${resolved.serverScopedPath}`;
+  const loginCmd =
+    name === 'main'
+      ? 'hstack auth login --no-open'
+      : `hstack stack auth ${name} login --no-open`;
+  return (
+    `[local] daemon auth required: credentials not found for stack "${name}".\n` +
+    `[local] expected: ${path}\n` +
+    `[local] fix: run \`${loginCmd}\`.\n` +
+    `[local] tip (headless servers): use \`--method=mobile\` to print a QR code / deep link for the mobile app.`
+  );
+}

package/scripts/utils/auth/daemon_gate.test.mjs

@@ -0,0 +1,116 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { daemonStartGate, formatDaemonAuthRequiredError, hasStackCredentials } from './daemon_gate.mjs';
+import { resolveStackCredentialPaths } from './credentials_paths.mjs';
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-gate-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+test('hasStackCredentials detects access.key', async (t) => {
+  const dir = await withTempRoot(t);
+  assert.equal(hasStackCredentials({ cliHomeDir: dir }), false);
+  await writeFile(join(dir, 'access.key'), 'dummy', 'utf-8');
+  assert.equal(hasStackCredentials({ cliHomeDir: dir }), true);
+});
+
+test('hasStackCredentials detects server-scoped access.key for env server urls', async (t) => {
+  const dir = await withTempRoot(t);
+  const serverUrl = 'http://127.0.0.1:3009';
+  const paths = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl });
+  const gateBefore = hasStackCredentials({ cliHomeDir: dir, serverUrl });
+  assert.equal(gateBefore, false);
+
+  await mkdir(join(dir, 'servers', paths.activeServerId), { recursive: true });
+  await writeFile(paths.serverScopedPath, 'dummy', 'utf-8');
+
+  const gateAfter = hasStackCredentials({ cliHomeDir: dir, serverUrl });
+  assert.equal(gateAfter, true);
+});
+
+test('daemonStartGate blocks daemon start in auth flow when missing credentials', async (t) => {
+  const dir = await withTempRoot(t);
+  const gate = daemonStartGate({ env: { HAPPIER_STACK_AUTH_FLOW: '1' }, cliHomeDir: dir });
+  assert.equal(gate.ok, false);
+  assert.equal(gate.reason, 'auth_flow_missing_credentials');
+});
+
+test('daemonStartGate blocks daemon start in daemon-wait auth flow when missing credentials', async (t) => {
+  const dir = await withTempRoot(t);
+  const gate = daemonStartGate({ env: { HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH: '1' }, cliHomeDir: dir });
+  assert.equal(gate.ok, false);
+  assert.equal(gate.reason, 'auth_flow_missing_credentials');
+});
+
+test('daemonStartGate blocks daemon start when missing credentials (non-auth flow)', async (t) => {
+  const dir = await withTempRoot(t);
+  const gate = daemonStartGate({ env: {}, cliHomeDir: dir });
+  assert.equal(gate.ok, false);
+  assert.equal(gate.reason, 'missing_credentials');
+});
+
+test('daemonStartGate allows daemon start when credentials exist', async (t) => {
+  const dir = await withTempRoot(t);
+  await writeFile(join(dir, 'access.key'), 'dummy', 'utf-8');
+  const gate = daemonStartGate({ env: {}, cliHomeDir: dir });
+  assert.equal(gate.ok, true);
+  assert.equal(gate.reason, 'credentials_present');
+});
+
+test('daemonStartGate resolves server-scoped credentials from env server url', async (t) => {
+  const dir = await withTempRoot(t);
+  const serverUrl = 'http://127.0.0.1:4010';
+  const paths = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl });
+  await mkdir(join(dir, 'servers', paths.activeServerId), { recursive: true });
+  await writeFile(paths.serverScopedPath, 'dummy', 'utf-8');
+
+  const gate = daemonStartGate({
+    env: { HAPPIER_SERVER_URL: serverUrl },
+    cliHomeDir: dir,
+  });
+  assert.equal(gate.ok, true);
+  assert.equal(gate.reason, 'credentials_present');
+});
+
+test('daemonStartGate resolves stable-scope credentials from HAPPIER_ACTIVE_SERVER_ID', async (t) => {
+  const dir = await withTempRoot(t);
+  const serverUrl = 'http://127.0.0.1:4010';
+  const env = { HAPPIER_SERVER_URL: serverUrl, HAPPIER_ACTIVE_SERVER_ID: 'stack_main__id_default' };
+  const paths = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl, env });
+  await mkdir(join(dir, 'servers', paths.activeServerId), { recursive: true });
+  await writeFile(paths.serverScopedPath, 'dummy', 'utf-8');
+
+  const gate = daemonStartGate({
+    env,
+    cliHomeDir: dir,
+  });
+  assert.equal(gate.ok, true);
+  assert.equal(gate.reason, 'credentials_present');
+});
+
+test('daemonStartGate prefers credentials over auth-flow toggles', async (t) => {
+  const dir = await withTempRoot(t);
+  await writeFile(join(dir, 'access.key'), 'dummy', 'utf-8');
+
+  const gate = daemonStartGate({
+    env: { HAPPIER_STACK_AUTH_FLOW: 'true', HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH: '1' },
+    cliHomeDir: dir,
+  });
+  assert.equal(gate.ok, true);
+  assert.equal(gate.reason, 'credentials_present');
+});
+
+test('formatDaemonAuthRequiredError suggests mobile QR login for headless servers', () => {
+  const msg = formatDaemonAuthRequiredError({ stackName: 'main', cliHomeDir: '/tmp/cli-home' });
+  assert.match(msg, /hstack auth login/i);
+  assert.match(msg, /--method=mobile/i);
+  assert.match(msg, /--no-open/i);
+});

package/scripts/utils/auth/decode_jwt_payload_unsafe.mjs

@@ -0,0 +1,16 @@
+export function decodeJwtPayloadUnsafe(token) {
+  const raw = String(token ?? '').trim();
+  if (!raw) return null;
+  const parts = raw.split('.');
+  if (parts.length < 2) return null;
+  try {
+    const normalized = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const padLength = normalized.length % 4 === 0 ? 0 : 4 - (normalized.length % 4);
+    const padded = normalized + '='.repeat(padLength);
+    const decoded = Buffer.from(padded, 'base64').toString('utf-8');
+    const payload = JSON.parse(decoded);
+    return payload && typeof payload === 'object' ? payload : null;
+  } catch {
+    return null;
+  }
+}