add scope-aware daemon pointer and automatic port fallback

Author: RhysSullivan

README.md

@@ -89,6 +89,7 @@ executor tools invoke gmail.send --input '{"to":"alice@example.com","subject":"H
 ```
 
 `executor call`, `executor resume`, and `executor tools ...` commands auto-start a local daemon if needed.
+If the default port is busy, the CLI will pick an available local port and track it automatically.
 
 If an execution pauses for auth or approval, resume it:
 

apps/cli/src/daemon-state.ts

@@ -16,6 +16,23 @@ export interface DaemonRecord {
   readonly scopeDir: string | null;
 }
 
+export interface DaemonPointer {
+  readonly version: 1;
+  readonly hostname: string;
+  readonly port: number;
+  readonly pid: number;
+  readonly startedAt: string;
+  readonly scopeId: string;
+  readonly scopeDir: string | null;
+  readonly token: string;
+}
+
+export interface DaemonStartLock {
+  readonly path: string;
+  readonly hostname: string;
+  readonly scopeId: string;
+}
+
 // ---------------------------------------------------------------------------
 // Host normalization
 // ---------------------------------------------------------------------------
@@ -27,6 +44,14 @@ export const canonicalDaemonHost = (hostname: string): string => {
   return LOCAL_HOST_ALIASES.has(normalized) ? "localhost" : normalized;
 };
 
+export const currentDaemonScopeId = (): string => {
+  const explicitScope = process.env.EXECUTOR_SCOPE_DIR?.trim();
+  if (explicitScope && explicitScope.length > 0) {
+    return `scope:${explicitScope}`;
+  }
+  return `cwd:${process.cwd()}`;
+};
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -35,12 +60,22 @@ const resolveDaemonDataDir = (path: Path.Path): string =>
   process.env.EXECUTOR_DATA_DIR ?? path.join(homedir(), ".executor");
 
 const sanitizeHostForPath = (hostname: string): string => hostname.replaceAll(/[^a-z0-9.-]+/gi, "_");
+const sanitizeScopeForPath = (scopeId: string): string => scopeId.replaceAll(/[^a-z0-9.-]+/gi, "_");
 
 const daemonRecordPath = (path: Path.Path, input: { hostname: string; port: number }): string => {
   const host = sanitizeHostForPath(canonicalDaemonHost(input.hostname));
   return path.join(resolveDaemonDataDir(path), `daemon-${host}-${input.port}.json`);
 };
 
+const daemonPointerPath = (path: Path.Path, input: { hostname: string; scopeId: string }): string => {
+  const host = sanitizeHostForPath(canonicalDaemonHost(input.hostname));
+  const scope = sanitizeScopeForPath(input.scopeId);
+  return path.join(resolveDaemonDataDir(path), `daemon-active-${host}-${scope}.json`);
+};
+
+const daemonStartLockPath = (path: Path.Path, input: { hostname: string; scopeId: string }): string =>
+  `${daemonPointerPath(path, input)}.lock`;
+
 // ---------------------------------------------------------------------------
 // Persistence
 // ---------------------------------------------------------------------------
@@ -111,6 +146,48 @@ const parseRecord = (raw: string): DaemonRecord | null => {
   };
 };
 
+const parsePointer = (raw: string): DaemonPointer | null => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    !("version" in parsed) ||
+    (parsed as { version?: unknown }).version !== 1
+  ) {
+    return null;
+  }
+
+  const r = parsed as Record<string, unknown>;
+  if (
+    typeof r.hostname !== "string" ||
+    typeof r.port !== "number" ||
+    typeof r.pid !== "number" ||
+    typeof r.startedAt !== "string" ||
+    typeof r.scopeId !== "string" ||
+    !(typeof r.scopeDir === "string" || r.scopeDir === null) ||
+    typeof r.token !== "string"
+  ) {
+    return null;
+  }
+
+  return {
+    version: 1,
+    hostname: canonicalDaemonHost(r.hostname),
+    port: r.port,
+    pid: r.pid,
+    startedAt: r.startedAt,
+    scopeId: r.scopeId,
+    scopeDir: r.scopeDir,
+    token: r.token,
+  };
+};
+
 export const readDaemonRecord = (input: {
   hostname: string;
   port: number;
@@ -135,6 +212,148 @@ export const removeDaemonRecord = (input: {
     yield* fs.remove(daemonRecordPath(path, input), { force: true });
   });
 
+export const writeDaemonPointer = (input: {
+  hostname: string;
+  port: number;
+  pid: number;
+  scopeId: string;
+  scopeDir: string | null;
+  token: string;
+}): Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const dataDir = resolveDaemonDataDir(path);
+    yield* fs.makeDirectory(dataDir, { recursive: true });
+
+    const payload: DaemonPointer = {
+      version: 1,
+      hostname: canonicalDaemonHost(input.hostname),
+      port: input.port,
+      pid: input.pid,
+      startedAt: new Date().toISOString(),
+      scopeId: input.scopeId,
+      scopeDir: input.scopeDir,
+      token: input.token,
+    };
+
+    yield* fs.writeFileString(
+      daemonPointerPath(path, { hostname: input.hostname, scopeId: input.scopeId }),
+      `${JSON.stringify(payload, null, 2)}\n`,
+    );
+  });
+
+export const readDaemonPointer = (input: {
+  hostname: string;
+  scopeId: string;
+}): Effect.Effect<DaemonPointer | null, never, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const raw = yield* fs
+      .readFileString(daemonPointerPath(path, input))
+      .pipe(Effect.catchAll(() => Effect.succeed(null)));
+    if (raw === null) return null;
+    return parsePointer(raw);
+  });
+
+export const removeDaemonPointer = (input: {
+  hostname: string;
+  scopeId: string;
+}): Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* fs.remove(daemonPointerPath(path, input), { force: true });
+  });
+
+const parseLockPid = (raw: string): number | null => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof (parsed as Record<string, unknown>).pid !== "number"
+  ) {
+    return null;
+  }
+
+  return (parsed as Record<string, number>).pid;
+};
+
+export const acquireDaemonStartLock = (input: {
+  hostname: string;
+  scopeId: string;
+}): Effect.Effect<DaemonStartLock, Error, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const dataDir = resolveDaemonDataDir(path);
+    yield* fs.makeDirectory(dataDir, { recursive: true });
+
+    const lockPath = daemonStartLockPath(path, input);
+    const lockPayload = JSON.stringify(
+      {
+        pid: process.pid,
+        hostname: canonicalDaemonHost(input.hostname),
+        scopeId: input.scopeId,
+        startedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    );
+
+    const tryAcquire = () =>
+      fs.writeFileString(lockPath, `${lockPayload}\n`, { flag: "wx" }).pipe(
+        Effect.as(true),
+        Effect.catchAll(() => Effect.succeed(false)),
+      );
+
+    if (yield* tryAcquire()) {
+      return {
+        path: lockPath,
+        hostname: canonicalDaemonHost(input.hostname),
+        scopeId: input.scopeId,
+      };
+    }
+
+    const existingRaw = yield* fs.readFileString(lockPath).pipe(Effect.catchAll(() => Effect.succeed(null)));
+    if (existingRaw !== null) {
+      const existingPid = parseLockPid(existingRaw);
+      if (existingPid !== null && !isPidAlive(existingPid)) {
+        yield* fs.remove(lockPath, { force: true });
+        if (yield* tryAcquire()) {
+          return {
+            path: lockPath,
+            hostname: canonicalDaemonHost(input.hostname),
+            scopeId: input.scopeId,
+          };
+        }
+      }
+    }
+
+    return yield* Effect.fail(
+      new Error(
+        `Another daemon startup is already in progress for ${canonicalDaemonHost(input.hostname)} (${input.scopeId}).`,
+      ),
+    );
+  });
+
+export const releaseDaemonStartLock = (input: DaemonStartLock): Effect.Effect<
+  void,
+  PlatformError,
+  FileSystem.FileSystem | Path.Path
+> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.remove(input.path, { force: true });
+  });
+
 // ---------------------------------------------------------------------------
 // Process helpers
 // ---------------------------------------------------------------------------

apps/cli/src/daemon.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { createServer } from "node:net";
 import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
 
@@ -142,3 +143,82 @@ export const waitForUnreachable = <E, R>(input: {
     timeoutMs: input.timeoutMs,
     intervalMs: input.intervalMs,
   });
+
+const toProbeHost = (hostname: string): string => {
+  const normalized = hostname.trim().toLowerCase();
+  if (normalized === "localhost" || normalized === "0.0.0.0") {
+    return "127.0.0.1";
+  }
+  return hostname;
+};
+
+const isPortAvailable = (input: { hostname: string; port: number }): Effect.Effect<boolean, Error> =>
+  Effect.tryPromise({
+    try: () =>
+      new Promise<boolean>((resolve) => {
+        const server = createServer() as any;
+        const cleanup = () => {
+          if (typeof server.removeAllListeners === "function") {
+            server.removeAllListeners();
+          }
+        };
+
+        server.once("error", () => {
+          cleanup();
+          resolve(false);
+        });
+
+        server.once("listening", () => {
+          cleanup();
+          server.close(() => resolve(true));
+        });
+
+        server.listen({ port: input.port, host: toProbeHost(input.hostname) });
+      }),
+    catch: (cause) =>
+      cause instanceof Error
+        ? cause
+        : new Error(`Failed probing port availability: ${String(cause)}`),
+  });
+
+const pickEphemeralPort = (hostname: string): Effect.Effect<number, Error> =>
+  Effect.tryPromise({
+    try: () =>
+      new Promise<number>((resolve, reject) => {
+        const server = createServer() as any;
+
+        server.once("error", (error: unknown) => {
+          reject(error);
+        });
+
+        server.once("listening", () => {
+          const address = server.address();
+          const port = typeof address === "object" && address !== null ? address.port : 0;
+          server.close(() => resolve(port));
+        });
+
+        server.listen({ port: 0, host: toProbeHost(hostname) });
+      }),
+    catch: (cause) =>
+      cause instanceof Error ? cause : new Error(`Failed selecting ephemeral port: ${String(cause)}`),
+  });
+
+export const chooseDaemonPort = (input: {
+  preferredPort: number;
+  hostname: string;
+}): Effect.Effect<number, Error> =>
+  Effect.gen(function* () {
+    const preferredAvailable = yield* isPortAvailable({
+      hostname: input.hostname,
+      port: input.preferredPort,
+    });
+    if (preferredAvailable) return input.preferredPort;
+
+    const fallbackPort = yield* pickEphemeralPort(input.hostname);
+    if (!Number.isFinite(fallbackPort) || fallbackPort <= 0 || fallbackPort > 65535) {
+      return yield* Effect.fail(
+        new Error(`Could not find an available daemon port for host ${input.hostname}`),
+      );
+    }
+    return fallbackPort;
+  });