fix(cli): probe port 3847 before spawning a daemon — stop duplicate daemons (INT-2473) (#228)

Daemon detection was PID-file-only, but a launchd-managed instance never
writes the PID file. Every bare `openswarm` launch therefore auto-started a
SECOND daemon next to the launchd one, and both worked the same Linear queue
in parallel (observed 2026-07-05: two daemons, 8 duplicated in-flight tasks).

- daemon.ts: add probeDaemonPort() (GET /api/stats, short timeout) and
  getDaemonStatusFull() which ORs the PID file with the port probe.
- startDaemon(): async; refuses with a clear launchctl hint when the port
  already answers. PID-file check still short-circuits without probing.
- cli.ts: TUI auto-start gates on getDaemonStatusFull(); `status` reports
  externally managed daemons as running; `stop` points at launchctl instead
  of a misleading "not running".

Verified live against the running launchd daemon: `status` → "externally
managed", `start` → refused, `stop` → launchctl guidance; daemon stayed
single. Hermetic tests (fetch stub + homedir isolation, no sockets) pin the
refusal, external status, and PID-file short-circuit: 9 pass.

Author: unohee

src/cli.ts

@@ -421,7 +421,7 @@ program
 
     const { startDaemon, getDaemonStatus, readLogTail } = await import('./cli/daemon.js');
     try {
-      const { pid, logFile } = startDaemon();
+      const { pid, logFile } = await startDaemon();
       // The child can die immediately on a startup error (bad config, port in
       // use, throwing dependency). Spawning only proves the OS forked it — wait
       // briefly and confirm it's actually alive before claiming success, so we
@@ -453,10 +453,18 @@ program
   .option('-t, --timeout <ms>', 'Max time to wait for graceful shutdown (default 10000)', '10000')
   .action(async (opts: { timeout: string }) => {
     const timeoutMs = parseInt(opts.timeout, 10);
-    const { stopDaemon } = await import('./cli/daemon.js');
+    const { stopDaemon, probeDaemonPort } = await import('./cli/daemon.js');
     try {
       const stopped = await stopDaemon(Number.isFinite(timeoutMs) ? timeoutMs : 10_000);
       if (!stopped) {
+        // No PID file — but an externally managed (launchd) daemon may still be
+        // serving. Point at the right lever instead of a misleading "not running".
+        if (await probeDaemonPort()) {
+          console.log('OpenSwarm is running but externally managed (no PID file — e.g. launchd).');
+          console.log('  stop: launchctl bootout gui/$UID/com.intrect.openswarm');
+          console.log('  restart: launchctl kickstart -k gui/$UID/com.intrect.openswarm');
+          return;
+        }
         console.log('OpenSwarm is not running.');
         return;
       }
@@ -473,14 +481,20 @@ program
   .command('status')
   .description('Report daemon status (pid, uptime, log path)')
   .action(async () => {
-    const { getDaemonStatus } = await import('./cli/daemon.js');
-    const status = getDaemonStatus();
+    const { getDaemonStatusFull } = await import('./cli/daemon.js');
+    const status = await getDaemonStatusFull();
     if (!status.running) {
       console.log('OpenSwarm is not running.');
       console.log(`  pid file: ${status.pidFile}`);
       console.log(`  log file: ${status.logFile}`);
       return;
     }
+    if (status.external) {
+      console.log('OpenSwarm is running (externally managed — e.g. launchd).');
+      console.log('  port 3847 is responding; no PID file for this instance.');
+      console.log(`  restart: launchctl kickstart -k gui/$UID/com.intrect.openswarm`);
+      return;
+    }
     const uptime = status.uptimeSeconds ?? 0;
     const h = Math.floor(uptime / 3600);
     const m = Math.floor((uptime % 3600) / 60);
@@ -664,9 +678,13 @@ async function launchChatTui(sessionId?: string): Promise<void> {
   // agent itself doesn't depend on the daemon. Done before console muting so the
   // one-line status is visible.
   try {
-    const { getDaemonStatus, startDaemon } = await import('./cli/daemon.js');
-    if (!getDaemonStatus().running) {
-      const { pid } = startDaemon();
+    const { getDaemonStatus, getDaemonStatusFull, startDaemon } = await import('./cli/daemon.js');
+    // Port-probe-aware check: a launchd-managed daemon has no PID file, and
+    // spawning a second daemon next to it double-processes the same task
+    // queue (INT-2473). Only spawn when neither the PID file nor the API port
+    // shows a live daemon.
+    if (!(await getDaemonStatusFull()).running) {
+      const { pid } = await startDaemon();
       process.stdout.write(`Starting OpenSwarm daemon (pid ${pid}) for the monitor tabs…\n`);
       await new Promise((r) => setTimeout(r, 1500));
       if (!getDaemonStatus().running) {

src/cli/daemon.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeAll, afterEach, vi } from 'vitest';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Isolate the PID file: daemon.ts derives its state dir from homedir() at
+// module load, so point homedir at a temp dir BEFORE importing the module.
+const TEST_HOME = join(tmpdir(), `osw-daemon-test-home-${process.pid}`);
+vi.mock('node:os', async () => {
+  const actual = await vi.importActual<typeof import('node:os')>('node:os');
+  return { ...actual, homedir: () => TEST_HOME };
+});
+
+// No real sockets: probeDaemonPort goes through global fetch, which each test
+// stubs. This keeps the suite runnable in sandboxes that forbid listen().
+function stubFetch(impl: (url: string, init?: { signal?: AbortSignal }) => Promise<Response>): ReturnType<typeof vi.fn> {
+  const fn = vi.fn(impl);
+  vi.stubGlobal('fetch', fn);
+  return fn;
+}
+
+const PID_FILE = join(TEST_HOME, '.config', 'openswarm', 'openswarm.pid');
+
+beforeAll(() => {
+  mkdirSync(join(TEST_HOME, '.config', 'openswarm'), { recursive: true });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  rmSync(PID_FILE, { force: true });
+});
+
+describe('probeDaemonPort', () => {
+  it('returns true when the daemon API answers 200', async () => {
+    const { probeDaemonPort } = await import('./daemon.js');
+    const fetchFn = stubFetch(async (url) => {
+      expect(url).toBe('http://127.0.0.1:3847/api/stats');
+      return new Response('{}', { status: 200 });
+    });
+    expect(await probeDaemonPort()).toBe(true);
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns false on a non-OK response', async () => {
+    const { probeDaemonPort } = await import('./daemon.js');
+    stubFetch(async () => new Response('', { status: 500 }));
+    expect(await probeDaemonPort()).toBe(false);
+  });
+
+  it('returns false when the connection is refused', async () => {
+    const { probeDaemonPort } = await import('./daemon.js');
+    stubFetch(async () => {
+      throw new TypeError('fetch failed: ECONNREFUSED');
+    });
+    expect(await probeDaemonPort()).toBe(false);
+  });
+
+  it('returns false when the server hangs past the timeout', async () => {
+    const { probeDaemonPort } = await import('./daemon.js');
+    stubFetch(
+      (_url, init) =>
+        new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener('abort', () => reject(new DOMException('timeout', 'TimeoutError')));
+        })
+    );
+    expect(await probeDaemonPort(3847, 50)).toBe(false);
+  });
+});
+
+describe('getDaemonStatusFull', () => {
+  it('reports an externally managed daemon when the port answers without a PID file', async () => {
+    const { getDaemonStatusFull } = await import('./daemon.js');
+    stubFetch(async () => new Response('{}', { status: 200 }));
+    const status = await getDaemonStatusFull();
+    expect(status.running).toBe(true);
+    expect(status.external).toBe(true);
+  });
+
+  it('reports not running when neither the PID file nor the port shows a daemon', async () => {
+    const { getDaemonStatusFull } = await import('./daemon.js');
+    stubFetch(async () => {
+      throw new TypeError('fetch failed: ECONNREFUSED');
+    });
+    const status = await getDaemonStatusFull();
+    expect(status.running).toBe(false);
+    expect(status.external).toBeUndefined();
+  });
+
+  it('prefers the PID file and skips the port probe when the PID is alive', async () => {
+    const { getDaemonStatusFull } = await import('./daemon.js');
+    writeFileSync(PID_FILE, String(process.pid));
+    const fetchFn = stubFetch(async () => new Response('{}', { status: 200 }));
+    const status = await getDaemonStatusFull();
+    expect(status.running).toBe(true);
+    expect(status.external).toBeUndefined();
+    expect(status.pid).toBe(process.pid);
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+});
+
+describe('startDaemon duplicate prevention (INT-2473)', () => {
+  it('refuses to spawn when the daemon port is already serving (launchd case)', async () => {
+    const { startDaemon } = await import('./daemon.js');
+    stubFetch(async () => new Response('{}', { status: 200 }));
+    await expect(startDaemon()).rejects.toThrow(/already serving port 3847/);
+  });
+
+  it('refuses via the PID file without probing when a spawned daemon is alive', async () => {
+    const { startDaemon } = await import('./daemon.js');
+    writeFileSync(PID_FILE, String(process.pid));
+    const fetchFn = stubFetch(async () => new Response('{}', { status: 200 }));
+    await expect(startDaemon()).rejects.toThrow(/already running \(pid/);
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+});

src/cli/daemon.ts

@@ -18,13 +18,16 @@ const STATE_DIR = join(homedir(), '.config', 'openswarm');
 const LOG_DIR = join(STATE_DIR, 'logs');
 const PID_FILE = join(STATE_DIR, 'openswarm.pid');
 const LOG_FILE = join(LOG_DIR, 'openswarm.log');
+const DAEMON_PORT = 3847;
 
 export interface DaemonStatus {
   running: boolean;
   pid?: number;
   uptimeSeconds?: number;
   pidFile: string;
   logFile: string;
+  /** True when no PID file matched but the daemon API answered — a launchd-managed or manually started instance. */
+  external?: boolean;
 }
 
 function ensureStateDirs(): void {
@@ -49,6 +52,25 @@ function readPidFile(): number | null {
   return pid;
 }
 
+/**
+ * Probe the daemon's HTTP API directly. The PID file only tracks daemons
+ * spawned by `openswarm start` — a launchd-managed (or manually run) instance
+ * never writes it, so PID-file-only detection reports "not running" while a
+ * daemon is actively serving. That mis-detection made the TUI auto-start spawn
+ * a SECOND daemon working the same Linear queue in parallel (INT-2473).
+ * The port answers for any daemon regardless of how it was started.
+ */
+export async function probeDaemonPort(port = DAEMON_PORT, timeoutMs = 800): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/stats`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve the path to dist/index.js. daemon.js lives at dist/cli/daemon.js,
  * so index.js is one level up.
@@ -65,9 +87,9 @@ function closeFdQuietly(fd: number): void {
 /**
  * Start the service as a detached background process.
  * Returns the child PID on success.
- * Throws if a daemon is already running.
+ * Throws if a daemon is already running (PID file OR port 3847 responding).
  */
-export function startDaemon(): { pid: number; logFile: string } {
+export async function startDaemon(): Promise<{ pid: number; logFile: string }> {
   ensureStateDirs();
 
   const existing = readPidFile();
@@ -82,6 +104,15 @@ export function startDaemon(): { pid: number; logFile: string } {
     try { unlinkSync(PID_FILE); } catch { /* ignore */ }
   }
 
+  // No PID file, but the API may still be live: a launchd-managed or manually
+  // started daemon. Spawning another would double-process the same task queue.
+  if (await probeDaemonPort()) {
+    throw new Error(
+      `OpenSwarm is already serving port ${DAEMON_PORT} (externally managed — e.g. launchd). ` +
+      `Not spawning a duplicate. Use 'launchctl kickstart -k gui/$UID/com.intrect.openswarm' to restart it.`
+    );
+  }
+
   const indexPath = resolveIndexPath();
   if (!existsSync(indexPath)) {
     throw new Error(`Service entrypoint not found: ${indexPath}`);
@@ -184,4 +215,18 @@ export function getDaemonStatus(): DaemonStatus {
   return { running: true, pid, uptimeSeconds, pidFile: PID_FILE, logFile: LOG_FILE };
 }
 
+/**
+ * Like getDaemonStatus, but also detects daemons the PID file can't see
+ * (launchd-managed / manually started) by probing the API port. Prefer this
+ * anywhere the answer gates spawning a new daemon.
+ */
+export async function getDaemonStatusFull(): Promise<DaemonStatus> {
+  const base = getDaemonStatus();
+  if (base.running) return base;
+  if (await probeDaemonPort()) {
+    return { running: true, external: true, pidFile: PID_FILE, logFile: LOG_FILE };
+  }
+  return base;
+}
+
 export const DAEMON_PATHS = { STATE_DIR, LOG_DIR, PID_FILE, LOG_FILE } as const;