Function ensureDaemon

design/src/daemon-client.ts:89–169

(
  opts: EnsureDaemonOptions = {},
)

 * branch — that's a user-actionable situation, not a programming error.
 */
export async function ensureDaemon(
  opts: EnsureDaemonOptions = {},
): Promise<EnsureDaemonResult> {
  const verbose = opts.verbose !== false;
  const expectedVersion = opts.version ?? readPackageVersion();
  const stateFile = opts.stateFile ?? resolveStateFilePath();

  const existing = readStateFile(stateFile);
  if (existing) {
    const health = await healthCheck(existing.port);
    if (health) {
      if (health.version === expectedVersion) {
        log(verbose, `attached to existing daemon pid=${existing.pid} port=${existing.port}`);
        return { port: existing.port, version: health.version, spawned: false };
      }
      // Version mismatch: refuse if active boards exist (Codex finding).
      if (health.activeBoards > 0) {
        process.stderr.write(
          `[design-daemon] WARNING: existing daemon is gstack ${health.version}; this CLI is ${expectedVersion}.\n` +
            `[design-daemon] ${health.activeBoards} active board(s) detected. Refusing to auto-kill.\n` +
            `[design-daemon] Submit or close the open boards, then re-run.\n` +
            `[design-daemon] Or force restart: $D daemon stop (will drop in-memory history).\n`,
        );
        process.exit(1);
      }
      // No active boards — safe to graceful-shutdown and respawn.
      log(verbose, `daemon version mismatch (${health.version} vs ${expectedVersion}); shutting down`);
      await gracefulShutdownExistingDaemon(existing.port);
      await killByPidWithIdentity(existing.pid, existing.cmdlineMarker, verbose);
    } else {
      // State file points at an unresponsive port. Either the daemon
      // crashed or the PID got reused. Identity-verify before any SIGTERM
      // so we don't kill an unrelated process (Codex finding).
      log(verbose, `state file present (pid=${existing.pid}) but /health unresponsive`);
      await killByPidWithIdentity(existing.pid, existing.cmdlineMarker, verbose);
    }
  }

  // Spawn under exclusive lock; re-read state INSIDE the lock so we don't
  // race a concurrent CLI that won the lock first.
  const lockPath = resolveLockFilePath(stateFile);
  const release = acquireLock(lockPath);
  if (!release) {
    // Another process is starting the daemon. Wait for it.
    log(verbose, "another CLI is spawning the daemon; waiting…");
    const start = Date.now();
    while (Date.now() - start < MAX_START_WAIT_MS) {
      const fresh = readStateFile(stateFile);
      if (fresh) {
        const h = await healthCheck(fresh.port);
        if (h) return { port: fresh.port, version: h.version, spawned: false };
      }
      await delay(POLL_INTERVAL_MS);
    }
    throw new Error("Timed out waiting for concurrent daemon spawn");
  }

  try {