@zgeoff/atc 2.10.0 → 2.10.2

package/README.md

@@ -93,7 +93,8 @@ list.
 
 If the daemon dies, press `R` on the home screen and every session respawns from its transcript.
 After you upgrade atc, the status bar shows `⟳ update ready`, and `u` restarts the daemon and
-restores the fleet when you are ready.
+restores the fleet when you are ready. The bar shows `⟳ restarting daemon` until the restart
+finishes.
 
 atc runs inside zellij or tmux. Give the pane locked mode so the leader key reaches atc.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.10.0",
+  "version": "2.10.2",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/cli.ts

@@ -191,24 +191,37 @@ const main = defineCommand({
               ),
           );
 
-          const handle = await daemon.startDaemon({
-            socketPath: config.daemonSocketPath,
-            reporterSocketPath: config.socketPath,
-            eventsSocketPath: config.eventsSocketPath,
-            build: getBuild(),
-            adapter: claudeAdapter,
-            adapters: [claudeAdapter, grokAdapter, codexAdapter, ...gatewayAdapters],
-            dbPath: config.dbFile,
-            legacyFleetPath: config.legacyFleetFile,
-            pidPath: config.daemonPidFile,
-            hooks: cfg.hooks,
-            restoreBootTimeoutMs,
-            ...(Number.isFinite(graceOverride) && graceOverride >= 0
-              ? { tapGraceMs: graceOverride }
-              : {}),
-            ...(Number.isFinite(queueBytes) && queueBytes > 0 ? { queueBytes } : {}),
-            onQuit: () => process.exit(0),
-          });
+          let handle: Awaited<ReturnType<typeof daemon.startDaemon>>;
+
+          try {
+            handle = await daemon.startDaemon({
+              socketPath: config.daemonSocketPath,
+              reporterSocketPath: config.socketPath,
+              eventsSocketPath: config.eventsSocketPath,
+              build: getBuild(),
+              adapter: claudeAdapter,
+              adapters: [claudeAdapter, grokAdapter, codexAdapter, ...gatewayAdapters],
+              dbPath: config.dbFile,
+              legacyFleetPath: config.legacyFleetFile,
+              pidPath: config.daemonPidFile,
+              hooks: cfg.hooks,
+              restoreBootTimeoutMs,
+              ...(Number.isFinite(graceOverride) && graceOverride >= 0
+                ? { tapGraceMs: graceOverride }
+                : {}),
+              ...(Number.isFinite(queueBytes) && queueBytes > 0 ? { queueBytes } : {}),
+              onQuit: () => process.exit(0),
+            });
+          } catch (error) {
+            // A second daemon on the same state directory refuses to start
+            // and touches nothing; any other startup failure stays a crash.
+            if (error instanceof Error && Reflect.get(error, 'code') === 'daemon_locked') {
+              console.error(error.message);
+              process.exit(1);
+            }
+
+            throw error;
+          }
 
           process.on('SIGTERM', () => {
             void (async () => {

package/src/client/boot-daemon.ts

@@ -1,23 +1,32 @@
 import { spawn as spawnChild } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { toAgentID } from '../agents/agent-adapter';
 import type { AgentID } from '../agents/agent-adapter';
-import { daemonPidFile, daemonSocketPath } from '../shared/config';
+import { daemonPidFile, daemonRecordFile, daemonSocketPath } from '../shared/config';
+import { findDaemonRecord } from '../shared/find-daemon-record';
 import { getBuild } from '../shared/get-build';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
+import { makeSingleFlight } from '../shared/make-single-flight';
 import { isRecord } from '../shared/report';
 import { DaemonClient } from './daemon-client';
+import { pickStaleDaemonPID } from './pick-stale-daemon-pid';
 
 export interface DaemonBoot {
   readonly client: DaemonClient;
   readonly stale: boolean;
   readonly lastUsedAgent: AgentID;
+
+  // The socket the client reached, which differs from the computed one when
+  // the daemon was found through its record in the state directory.
+  readonly socketPath: string;
 }
 
 /**
- * Opens a handshaken client to the daemon, booting the daemon first when its
- * socket is absent. A daemon from an older build stays in service — killing
+ * Opens a handshaken client to the daemon, booting the daemon first when
+ * neither the computed socket nor the one in the daemon's record answers.
+ * Overlapping calls in one process share a single boot. A daemon from an older build stays in service — killing
  * it would kill every hosted session — and is reported as stale so the
  * caller can offer a deliberate restart. Only a protocol mismatch, where
  * talking would misbehave, forces the restart immediately. The expected
@@ -29,7 +38,9 @@ export async function bootDaemonClient(): Promise<DaemonBoot> {
   for (let attempt = 0; attempt < 2; attempt++) {
     const build = getBuild();
 
-    const client = await openOrBootDaemon();
+    const opened = await openOrBootDaemon();
+
+    const client = opened.client;
 
     try {
       const hello = await client.sendHello(build);
@@ -38,6 +49,7 @@ export async function bootDaemonClient(): Promise<DaemonBoot> {
         client,
         stale: hello['daemon'] !== build,
         lastUsedAgent: toAgentID(hello['lastUsedAgent']),
+        socketPath: opened.socketPath,
       };
     } catch (error) {
       client.stop();
@@ -46,7 +58,7 @@ export async function bootDaemonClient(): Promise<DaemonBoot> {
         throw error;
       }
 
-      await stopStaleDaemon();
+      await stopStaleDaemon(opened.socketPath);
     }
   }
 
@@ -57,46 +69,117 @@ function isProtocolMismatch(error: unknown): boolean {
   return isRecord(error) && error['code'] === 'protocol_mismatch';
 }
 
-async function openOrBootDaemon(): Promise<DaemonClient> {
-  let opened = await tryOpenDaemon();
+interface OpenedDaemon {
+  readonly client: DaemonClient;
+  readonly socketPath: string;
+}
 
-  if (opened === null) {
-    spawnDaemonDetached();
+async function openOrBootDaemon(): Promise<OpenedDaemon> {
+  const opened = await tryOpenKnownDaemon();
 
-    const deadline = Date.now() + 5000;
+  if (opened !== null) {
+    return opened;
+  }
 
-    while (opened === null && Date.now() < deadline) {
-      await Bun.sleep(100);
+  await bootDaemonOnce();
 
-      opened = await tryOpenDaemon();
-    }
+  const booted = await tryOpenKnownDaemon();
+
+  if (booted === null) {
+    throw new Error(formatBootFailure());
+  }
+
+  return booted;
+}
+
+/**
+ * Tries the socket this environment computes, then the one the running
+ * daemon recorded in the state directory: a client whose environment lacks
+ * XDG_RUNTIME_DIR computes a different path from the daemon's.
+ */
+async function tryOpenKnownDaemon(): Promise<OpenedDaemon | null> {
+  const computed = await tryOpenDaemon(daemonSocketPath);
+
+  if (computed !== null) {
+    return computed;
   }
 
-  if (opened === null) {
-    throw new Error('the atc daemon did not come up; try `atc daemon` for its output');
+  const record = findDaemonRecord(daemonRecordFile);
+
+  if (record === null || record.socketPath === daemonSocketPath) {
+    return null;
   }
 
-  return opened;
+  return tryOpenDaemon(record.socketPath);
 }
 
-async function tryOpenDaemon(): Promise<DaemonClient | null> {
+async function tryOpenDaemon(socketPath: string): Promise<OpenedDaemon | null> {
   try {
-    return await DaemonClient.open(daemonSocketPath);
+    return { client: await DaemonClient.open(socketPath), socketPath };
   } catch {
     return null;
   }
 }
 
-async function stopStaleDaemon(): Promise<void> {
-  let pid = 0;
+// How long a boot waits for a daemon to answer. It covers a daemon that
+// waits out the state lock of one still shutting down.
+const BOOT_DEADLINE_MS = 8000;
+
+const bootDaemonOnce = makeSingleFlight(async () => {
+  let child = spawnDaemonDetached();
+  const deadline = Date.now() + BOOT_DEADLINE_MS;
+
+  while (Date.now() < deadline) {
+    await Bun.sleep(100);
+
+    const probe = await tryOpenKnownDaemon();
+
+    if (probe !== null) {
+      probe.client.stop();
+
+      return;
+    }
+
+    // A daemon that found the state lock still held by one shutting down
+    // exits; once the old one is gone, a fresh spawn takes the lock.
+    if (child.exitCode !== null || child.signalCode !== null) {
+      child = spawnDaemonDetached();
+    }
+  }
+});
+
+// A live daemon this process cannot reach, such as one whose runtime
+// directory a sandbox hides, needs a different fix than one that never
+// started, so the message tells them apart.
+function formatBootFailure(): string {
+  const record = findDaemonRecord(daemonRecordFile);
 
+  if (record !== null && isProcessAlive(record.pid)) {
+    return `the atc daemon (pid ${record.pid}) is running, but its socket ${record.socketPath} is unreachable from here`;
+  }
+
+  return 'the atc daemon did not come up; try `atc daemon` for its output';
+}
+
+function isProcessAlive(pid: number): boolean {
   try {
-    pid = Number(readFileSync(daemonPidFile, 'utf8'));
+    process.kill(pid, 0);
+
+    return true;
   } catch {
-    return;
+    return false;
   }
+}
+
+async function stopStaleDaemon(socketPath: string): Promise<void> {
+  const pid = pickStaleDaemonPID({
+    socketPath,
+    record: findDaemonRecord(daemonRecordFile),
+    pidFileSocketPath: daemonSocketPath,
+    pidFilePID: findPidFilePID(),
+  });
 
-  if (!Number.isInteger(pid) || pid <= 1) {
+  if (pid === null) {
     return;
   }
 
@@ -119,8 +202,22 @@ async function stopStaleDaemon(): Promise<void> {
   }
 }
 
-function spawnDaemonDetached() {
+// The pid file beside the sockets this environment computes.
+function findPidFilePID(): number | null {
+  try {
+    const pid = Number(readFileSync(daemonPidFile, 'utf8'));
+
+    return Number.isInteger(pid) && pid > 1 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function spawnDaemonDetached(): ChildProcess {
   const args = isCompiledBinary() ? ['daemon'] : [join(import.meta.dir, '..', 'cli.ts'), 'daemon'];
+  const child = spawnChild(process.execPath, args, { detached: true, stdio: 'ignore' });
+
+  child.unref();
 
-  spawnChild(process.execPath, args, { detached: true, stdio: 'ignore' }).unref();
+  return child;
 }

package/src/client/index.ts

@@ -4,6 +4,7 @@ import type { AgentID } from '../agents/agent-adapter';
 import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from '../daemon/sessions';
 import type { EventMsg } from '../protocol/protocol';
 import { loadConfig } from '../shared/config';
+import { makeSingleFlight } from '../shared/make-single-flight';
 import { bootDaemonClient } from './boot-daemon';
 import { buildClientMachine } from './build-client-machine';
 import { buildLeaderChords } from './build-leader-chords';
@@ -82,6 +83,7 @@ function scheduleStatus() {
         urgentName: urgent === undefined ? null : urgent.name,
         leaderLabel: leader.label,
         stale: daemonStale,
+        restarting: daemonRestarting,
       });
     }
   }, 50);
@@ -214,7 +216,7 @@ function renderOverlay() {
     selected: overlaySelected,
     confirmKill,
     filter: overlayFilter,
-    stale: daemonStale,
+    stale: daemonStale && !daemonRestarting,
     grouped: overlayGrouped,
   });
 
@@ -616,7 +618,7 @@ function applyOverlayKey(buf: Buffer) {
   }
 
   if (ch === 'u' && daemonStale) {
-    void restartDaemon();
+    void restartDaemonOnce();
 
     return;
   }
@@ -734,6 +736,7 @@ const boot = await bootDaemonClient();
 
 let client = boot.client;
 let daemonStale = boot.stale;
+let daemonRestarting = false;
 
 lastUsedAgent = boot.lastUsedAgent;
 client.onEvent = applyDaemonEvent;
@@ -767,8 +770,24 @@ async function refreshMirror() {
 /**
  * The deliberate half of the stale-daemon story: quits the old daemon,
  * boots one from the current build, and restores the whole fleet, so an
- * update never interrupts sessions until the user picks the moment.
+ * update never interrupts sessions until the user picks the moment. A
+ * press while a restart runs joins it rather than starting another, and
+ * the status bar says a restart is running until it finishes.
  */
+const restartDaemonOnce = makeSingleFlight(async () => {
+  daemonRestarting = true;
+
+  renderOverlay();
+
+  try {
+    await restartDaemon();
+  } finally {
+    daemonRestarting = false;
+
+    scheduleStatus();
+  }
+});
+
 async function restartDaemon() {
   try {
     await client.sendRequest('daemon.quit');

package/src/client/pick-stale-daemon-pid.ts

@@ -0,0 +1,31 @@
+import type { DaemonRecord } from '../shared/find-daemon-record';
+
+export interface StaleDaemonEvidence {
+  // The socket whose daemon refused the handshake.
+  readonly socketPath: string;
+  readonly record: DaemonRecord | null;
+
+  // The socket the pid file sits beside, and the pid it holds.
+  readonly pidFileSocketPath: string;
+  readonly pidFilePID: number | null;
+}
+
+/**
+ * Picks the pid of the daemon behind the socket that refused the
+ * handshake, from whichever source belongs to that socket: the state
+ * directory's record when it lists that socket, else the pid file beside
+ * it. A record for any other socket belongs to a different daemon, so it
+ * never supplies the pid; with no source for that socket, there is no pid
+ * to stop.
+ */
+export function pickStaleDaemonPID(evidence: StaleDaemonEvidence): number | null {
+  if (evidence.record !== null && evidence.record.socketPath === evidence.socketPath) {
+    return evidence.record.pid;
+  }
+
+  if (evidence.socketPath === evidence.pidFileSocketPath) {
+    return evidence.pidFilePID;
+  }
+
+  return null;
+}

package/src/client/ui.ts

@@ -75,6 +75,7 @@ export interface StatusView {
   readonly urgentName: string | null;
   readonly leaderLabel: string;
   readonly stale: boolean;
+  readonly restarting: boolean;
 }
 
 export function drawStatusBar(view: StatusView) {
@@ -101,7 +102,9 @@ export function drawStatusBar(view: StatusView) {
     parts.push(`✗ ${c.exited}`);
   }
 
-  if (view.stale) {
+  if (view.restarting) {
+    parts.push('⟳ restarting daemon');
+  } else if (view.stale) {
     parts.push('⟳ update ready');
   }
 

package/src/daemon/claim-daemon-lock.ts

@@ -0,0 +1,76 @@
+import { FFIType, dlopen, ptr } from 'bun:ffi';
+import { closeSync, writeFileSync } from 'node:fs';
+
+export interface DaemonLock {
+  // Releases the lock; safe to call more than once.
+  readonly dispose: () => void;
+}
+
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const O_RDWR = 2;
+
+// Kept off every child the daemon spawns, so an orphaned agent process can
+// never hold a dead daemon's lock.
+const O_CLOEXEC = process.platform === 'darwin' ? 0x01_00_00_00 : 0o200_0000;
+const RETRY_MS = 50;
+
+/**
+ * Takes the exclusive daemon lock on the file at `lockPath`, waiting up to
+ * `waitMs` for a daemon that is shutting down to let go, and resolves null
+ * while another daemon holds it.
+ *
+ * The lock is a kernel `flock` on an open file description: two daemons
+ * racing at the same instant cannot both win, and the kernel drops it when
+ * the holding process dies, so a crashed daemon never blocks the next one.
+ * The file is never removed: removing it would let a newcomer lock a fresh
+ * inode while an older daemon still holds the unlinked one.
+ */
+export async function claimDaemonLock(
+  lockPath: string,
+  waitMs: number,
+): Promise<DaemonLock | null> {
+  writeFileSync(lockPath, '', { flag: 'a' });
+
+  const libc = openLibc();
+  const fd = libc.symbols.open(ptr(Buffer.from(`${lockPath}\0`)), O_RDWR | O_CLOEXEC);
+
+  if (fd < 0) {
+    throw new Error(`atc daemon: cannot open the lock file ${lockPath}`);
+  }
+
+  const deadline = Date.now() + waitMs;
+
+  while (libc.symbols.flock(fd, LOCK_EX | LOCK_NB) !== 0) {
+    if (Date.now() >= deadline) {
+      closeSync(fd);
+
+      return null;
+    }
+
+    await Bun.sleep(RETRY_MS);
+  }
+
+  let held = true;
+
+  return {
+    dispose: () => {
+      if (held) {
+        held = false;
+
+        closeSync(fd);
+      }
+    },
+  };
+}
+
+// `open` is variadic in C; it is declared here with two arguments, which is
+// sound because the lock file already exists and no mode is passed.
+function openLibc() {
+  const libcPath = process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : 'libc.so.6';
+
+  return dlopen(libcPath, {
+    open: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+  });
+}

package/src/daemon/daemon.ts

@@ -1,8 +1,10 @@
 import { unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import type { AdapterEvent, AgentAdapter } from '../agents/agent-adapter';
 import { MAX_CHUNK, PROTOCOL_V } from '../protocol/protocol';
 import type { EventMsg } from '../protocol/protocol';
 import type { HooksConfig } from '../shared/collect-hooks';
+import { findDaemonRecord } from '../shared/find-daemon-record';
 import type { SessionID } from '../shared/session-id';
 import { truncateToBytes } from '../shared/truncate-to-bytes';
 import type { MessageOwner } from '../store/message-owner';
@@ -17,6 +19,7 @@ import { buildReportTrailEntry } from './build-report-trail-entry';
 import { buildSessionEvent } from './build-session-event';
 import { buildSessionMessageEvent } from './build-session-message-event';
 import { buildSessionReportEvent } from './build-session-report-event';
+import { claimDaemonLock } from './claim-daemon-lock';
 import { DaemonConnection } from './daemon-connection';
 import type { DaemonContext, OutputClient, TapClient } from './daemon-connection';
 import { EventSignal } from './event-signal';
@@ -37,6 +40,7 @@ import type { Session, SessionDescriptor, SessionState } from './sessions';
 import { startEventsServer } from './start-events-server';
 import { startHeadlessTurn } from './start-headless-turn';
 import { TapRegistry } from './tap-registry';
+import { writeDaemonRecord } from './write-daemon-record';
 
 export interface DaemonOptions {
   readonly socketPath: string;
@@ -101,6 +105,10 @@ export interface DaemonHandle {
 // it is refused.
 const TAP_GRACE_MS = 15_000;
 
+// How long startup waits for a daemon that is shutting down to release the
+// state lock before refusing to start.
+const LOCK_WAIT_MS = 2000;
+
 /**
  * The daemon: owns the sessions, the client-protocol listener, and the
  * reporter listener. Protocol requests are NDJSON lines, one response per
@@ -113,6 +121,23 @@ const TAP_GRACE_MS = 15_000;
 export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   let stopDaemon: (() => Promise<void>) | null = null;
 
+  // One daemon per state directory: the lock comes before the store, the
+  // sockets, or the fleet, so a second daemon touches none of them.
+  const stateDir = dirname(opts.dbPath);
+  const recordPath = join(stateDir, 'daemon.json');
+
+  const lock = await claimDaemonLock(join(stateDir, 'daemon.lock'), LOCK_WAIT_MS);
+
+  if (lock === null) {
+    const holder = findDaemonRecord(recordPath);
+    const where = holder === null ? '' : ` (pid ${holder.pid}, socket ${holder.socketPath})`;
+
+    throw Object.assign(
+      new Error(`atc daemon: another daemon already serves ${stateDir}${where}`),
+      { code: 'daemon_locked' },
+    );
+  }
+
   if (opts.pidPath !== undefined) {
     writeFileSync(opts.pidPath, String(process.pid));
   }
@@ -1068,13 +1093,26 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
     await store.stop();
 
+    try {
+      unlinkSync(recordPath);
+    } catch {}
+
     if (opts.pidPath !== undefined) {
       try {
         unlinkSync(opts.pidPath);
       } catch {}
     }
+
+    lock.dispose();
   };
 
+  writeDaemonRecord(recordPath, {
+    pid: process.pid,
+    socketPath: opts.socketPath,
+    reporterSocketPath: opts.reporterSocketPath,
+    eventsSocketPath: opts.eventsSocketPath ?? null,
+  });
+
   return { stop: stopDaemon, countClients: () => clients.size };
 }
 

package/src/daemon/start-headless-run.ts

@@ -1,4 +1,3 @@
-import { query } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { socketPath } from '../shared/config';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
@@ -55,7 +54,12 @@ export function startHeadlessRun(
       const mode = PERMISSION_MODES.find((m) => m === opts.permissionMode);
       let stderrTail = '';
 
-      const stream = query({
+      // The SDK is the heaviest module in the daemon's graph, and only a
+      // headless turn needs it, so loading it here keeps it off the daemon's
+      // cold start.
+      const sdk = await import('@anthropic-ai/claude-agent-sdk');
+
+      const stream = sdk.query({
         prompt: opts.prompt,
         options: {
           cwd: opts.cwd,

package/src/daemon/write-daemon-record.ts

@@ -0,0 +1,13 @@
+import { renameSync, writeFileSync } from 'node:fs';
+import type { DaemonRecord } from '../shared/find-daemon-record';
+
+/**
+ * Writes the running daemon's record through a temporary file and a
+ * rename, so a reader never sees half of it.
+ */
+export function writeDaemonRecord(recordPath: string, record: DaemonRecord): void {
+  const tmpPath = `${recordPath}.${process.pid}.tmp`;
+
+  writeFileSync(tmpPath, `${JSON.stringify(record)}\n`);
+  renameSync(tmpPath, recordPath);
+}

package/src/mcp-http-server.ts

@@ -4,7 +4,7 @@ import { collectClients } from './mcp/collect-clients';
 import { openMCPAuth } from './mcp/open-mcp-auth';
 import { ReconnectingCaller } from './mcp/reconnecting-caller';
 import { startMCPHTTPServer } from './mcp/start-mcp-http-server';
-import { daemonSocketPath, mcpAuthDBFile, stateDir } from './shared/config';
+import { mcpAuthDBFile, stateDir } from './shared/config';
 import { loadMCPHTTPConfig } from './shared/load-mcp-http-config';
 
 interface MCPHTTPFlags {
@@ -27,7 +27,7 @@ export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Prom
 
   mkdirSync(stateDir, { recursive: true });
 
-  const caller = new ReconnectingCaller(daemonSocketPath, build);
+  const caller = new ReconnectingCaller(boot.socketPath, build);
 
   const server = await startMCPHTTPServer({
     caller,

package/src/shared/config.ts

@@ -62,6 +62,10 @@ export const mcpAuthDBFile = join(stateDir, 'mcp-auth.db');
 export const legacyFleetFile = join(stateDir, 'fleet.json');
 export const daemonPidFile = join(process.env['XDG_RUNTIME_DIR'] ?? stateDir, 'atc-daemon.pid');
 
+// Written by the running daemon: its pid and the socket paths it listens
+// on, for a client whose environment computes other socket paths.
+export const daemonRecordFile = join(stateDir, 'daemon.json');
+
 // A user-written config.json's top-level keys. An absent or wrong-typed
 // field parses to undefined rather than failing the file, so a bad config
 // falls back to a default instead of refusing to start atc.

package/src/shared/find-daemon-record.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+
+export interface DaemonRecord {
+  readonly pid: number;
+  readonly socketPath: string;
+  readonly reporterSocketPath: string;
+  readonly eventsSocketPath: string | null;
+}
+
+const RECORD_SCHEMA = z.object({
+  pid: z.number().int().positive(),
+  socketPath: z.string().min(1),
+  reporterSocketPath: z.string().min(1),
+  eventsSocketPath: z.string().min(1).nullable(),
+});
+
+/**
+ * Reads the record a running daemon keeps in its state directory: its pid
+ * and the socket paths it listens on, which a client whose environment
+ * computes other socket paths uses to find it. A missing, torn, or
+ * malformed record reads as null; a record left by a crashed daemon still
+ * parses, so a caller proves liveness by connecting.
+ */
+export function findDaemonRecord(recordPath: string): DaemonRecord | null {
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(readFileSync(recordPath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  const parsed = RECORD_SCHEMA.safeParse(raw);
+
+  return parsed.success ? parsed.data : null;
+}

package/src/shared/make-single-flight.ts

@@ -0,0 +1,22 @@
+/**
+ * Wraps an async function so overlapping calls share one run: a call made
+ * while a run is in flight gets that run's promise instead of starting
+ * another, and the first call after it settles starts a fresh run.
+ */
+export function makeSingleFlight<T>(run: () => Promise<T>): () => Promise<T> {
+  let inFlight: Promise<T> | null = null;
+
+  const runAndClear = async (): Promise<T> => {
+    try {
+      return await run();
+    } finally {
+      inFlight = null;
+    }
+  };
+
+  return () => {
+    inFlight ??= runAndClear();
+
+    return inFlight;
+  };
+}