@vellumai/cli 0.10.11-dev.202607241515.ecced08 → 0.10.11-dev.202607241637.6d2be3e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607241515.ecced08",
+  "version": "0.10.11-dev.202607241637.6d2be3e",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/local-hatch-lock.test.ts

@@ -0,0 +1,163 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import {
+  resolveLocalHatchLockPath,
+  withLocalHatchLock,
+} from "../lib/local-hatch-lock.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const tempDir of tempDirs.splice(0)) {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+});
+
+function makeLockPath(): string {
+  const tempDir = mkdtempSync(join(tmpdir(), "vellum-hatch-lock-test-"));
+  tempDirs.push(tempDir);
+  return join(tempDir, "local-hatch.lock");
+}
+
+describe("withLocalHatchLock", () => {
+  test("uses the same machine lock when callers have different temp directories", () => {
+    const originalTmpDir = process.env.TMPDIR;
+    const firstTmpDir = mkdtempSync(join(tmpdir(), "vellum-tmp-a-"));
+    const secondTmpDir = mkdtempSync(join(tmpdir(), "vellum-tmp-b-"));
+    tempDirs.push(firstTmpDir, secondTmpDir);
+
+    try {
+      process.env.TMPDIR = firstTmpDir;
+      const firstPath = resolveLocalHatchLockPath();
+      process.env.TMPDIR = secondTmpDir;
+      const secondPath = resolveLocalHatchLockPath();
+
+      expect(secondPath).toBe(firstPath);
+      expect(firstPath.startsWith(firstTmpDir)).toBe(false);
+      expect(firstPath.startsWith(secondTmpDir)).toBe(false);
+    } finally {
+      if (originalTmpDir === undefined) {
+        delete process.env.TMPDIR;
+      } else {
+        process.env.TMPDIR = originalTmpDir;
+      }
+    }
+  });
+
+  test("serializes startup work that shares the machine-wide lock", async () => {
+    const lockPath = makeLockPath();
+    let releaseFirst!: () => void;
+    let firstStarted!: () => void;
+    const firstStartedPromise = new Promise<void>((resolve) => {
+      firstStarted = resolve;
+    });
+    const firstReleasePromise = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    let secondEntered = false;
+
+    const first = withLocalHatchLock(
+      async () => {
+        firstStarted();
+        await firstReleasePromise;
+      },
+      { lockPath, timeoutMs: 1_000, retryMs: 5 },
+    );
+    await firstStartedPromise;
+
+    const second = withLocalHatchLock(
+      async () => {
+        secondEntered = true;
+      },
+      { lockPath, timeoutMs: 1_000, retryMs: 5 },
+    );
+    await Bun.sleep(20);
+    expect(secondEntered).toBe(false);
+
+    releaseFirst();
+    await Promise.all([first, second]);
+
+    expect(secondEntered).toBe(true);
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("recovers a lock owned by a dead process", async () => {
+    const lockPath = makeLockPath();
+    writeFileSync(
+      lockPath,
+      JSON.stringify({ pid: 2_147_483_647, token: "stale-owner" }) + "\n",
+    );
+
+    const result = await withLocalHatchLock(async () => "started", {
+      lockPath,
+      timeoutMs: 1_000,
+      retryMs: 5,
+    });
+
+    expect(result).toBe("started");
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("recovers an expired lock even when its PID has been reused", async () => {
+    const lockPath = makeLockPath();
+    writeFileSync(
+      lockPath,
+      JSON.stringify({
+        pid: process.pid,
+        processStartedAt: "not-the-current-process",
+        token: "reused-pid-owner",
+      }) + "\n",
+    );
+    const expired = new Date(Date.now() - 300_000);
+    utimesSync(lockPath, expired, expired);
+
+    const result = await withLocalHatchLock(async () => "started", {
+      lockPath,
+      liveOwnerRecoveryGraceMs: 0,
+      timeoutMs: 1_000,
+      retryMs: 5,
+    });
+
+    expect(result).toBe("started");
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("recovers a fresh lock when its PID has been reused", async () => {
+    const lockPath = makeLockPath();
+    writeFileSync(
+      lockPath,
+      JSON.stringify({
+        pid: process.pid,
+        processStartedAt: "not-the-current-process",
+        token: "fresh-reused-pid-owner",
+      }) + "\n",
+    );
+
+    const result = await withLocalHatchLock(async () => "started", {
+      lockPath,
+      timeoutMs: 1_000,
+      retryMs: 5,
+    });
+
+    expect(result).toBe("started");
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("releases the lock when startup fails", async () => {
+    const lockPath = makeLockPath();
+
+    await expect(
+      withLocalHatchLock(
+        async () => {
+          throw new Error("startup failed");
+        },
+        { lockPath },
+      ),
+    ).rejects.toThrow("startup failed");
+
+    expect(existsSync(lockPath)).toBe(false);
+  });
+});

package/src/lib/hatch-local.ts

@@ -46,6 +46,7 @@ import {
 import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { checkProviderApiKey } from "./api-key-check.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { withLocalHatchLock } from "./local-hatch-lock.js";
 
 /**
  * Attempts to place a symlink at the given path pointing to cliBinary.
@@ -179,89 +180,116 @@ export async function hatchLocal(
     name ?? process.env.VELLUM_ASSISTANT_NAME,
   );
 
-  reporter.progress(1, 6, "Allocating resources...");
+  const { resources, runtimeUrl, loopbackUrl, bootstrapSecret } =
+    await withLocalHatchLock(async () => {
+      reporter.progress(1, 6, "Allocating resources...");
 
-  const existing = findAssistantByName(instanceName);
-  if (existing && (!existing.cloud || existing.cloud === "local")) {
-    throw new Error(
-      `An assistant named "${instanceName}" is already hatched.\n` +
-        `Run \`vellum wake\` to restart it, or \`vellum retire ${instanceName}\` to remove it first.`,
-    );
-  }
+      const existing = findAssistantByName(instanceName);
+      if (existing && (!existing.cloud || existing.cloud === "local")) {
+        throw new Error(
+          `An assistant named "${instanceName}" is already hatched.\n` +
+            `Run \`vellum wake\` to restart it, or \`vellum retire ${instanceName}\` to remove it first.`,
+        );
+      }
 
-  const resources = await allocateLocalResources(instanceName);
+      const resources = await allocateLocalResources(instanceName);
 
-  const logsDir = join(
-    resources.instanceDir,
-    ".vellum",
-    "workspace",
-    "data",
-    "logs",
-  );
-  archiveLogFile("hatch.log", logsDir);
-  resetLogFile("hatch.log");
+      const logsDir = join(
+        resources.instanceDir,
+        ".vellum",
+        "workspace",
+        "data",
+        "logs",
+      );
+      archiveLogFile("hatch.log", logsDir);
+      resetLogFile("hatch.log");
 
-  reporter.log(`🥚 Hatching local assistant: ${instanceName}`);
-  reporter.log(`   Species: ${species}`);
-  reporter.log("");
+      reporter.log(`🥚 Hatching local assistant: ${instanceName}`);
+      reporter.log(`   Species: ${species}`);
+      reporter.log("");
 
-  const apiKeyCheck = checkProviderApiKey();
-  if (!apiKeyCheck.hasKey) {
-    reporter.warn(
-      "Warning: No LLM provider API key is configured. The assistant will fail when you try to send a message.",
-    );
-    reporter.warn("  To fix, export your key before running vellum hatch:");
-    reporter.warn("  export ANTHROPIC_API_KEY=<your-key>");
-    reporter.warn("");
-  }
+      const apiKeyCheck = checkProviderApiKey();
+      if (!apiKeyCheck.hasKey) {
+        reporter.warn(
+          "Warning: No LLM provider API key is configured. The assistant will fail when you try to send a message.",
+        );
+        reporter.warn("  To fix, export your key before running vellum hatch:");
+        reporter.warn("  export ANTHROPIC_API_KEY=<your-key>");
+        reporter.warn("");
+      }
 
-  if (!process.env.APP_VERSION) {
-    process.env.APP_VERSION = cliPkg.version;
-  }
+      if (!process.env.APP_VERSION) {
+        process.env.APP_VERSION = cliPkg.version;
+      }
 
-  reporter.progress(2, 6, "Writing configuration...");
-  const hatchConfigValues = buildHatchConfigValues(configValues, provider);
-  const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
-
-  reporter.progress(3, 6, "Starting assistant...");
-  const signingKey = generateLocalSigningKey();
-  const bootstrapSecret = generateLocalSigningKey();
-  // Launch the CES sibling alongside the daemon, in parallel — matching the
-  // Docker topology. The assistant does not spawn its own CES, so a freshly
-  // hatched instance would otherwise come up with CES unavailable.
-  // startCes always launches the CES sibling.
-  await Promise.all([
-    startCes(watch, resources),
-    startLocalDaemon(watch, resources, {
-      defaultWorkspaceConfigPath,
-      signingKey,
-    }),
-  ]);
-
-  reporter.progress(4, 6, "Starting gateway...");
-  let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
-  try {
-    runtimeUrl = await startGateway(watch, resources, {
-      signingKey,
-      bootstrapSecret,
-      envOverrides: flagEnvVars,
+      reporter.progress(2, 6, "Writing configuration...");
+      const hatchConfigValues = buildHatchConfigValues(configValues, provider);
+      const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
+
+      reporter.progress(3, 6, "Starting assistant...");
+      const signingKey = generateLocalSigningKey();
+      const bootstrapSecret = generateLocalSigningKey();
+      let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+      try {
+        // Launch the CES sibling alongside the daemon, in parallel — matching the
+        // Docker topology. The assistant does not spawn its own CES, so a freshly
+        // hatched instance would otherwise come up with CES unavailable.
+        // startCes always launches the CES sibling.
+        const startupResults = await Promise.allSettled([
+          startCes(watch, resources),
+          startLocalDaemon(watch, resources, {
+            defaultWorkspaceConfigPath,
+            requireReady: true,
+            signingKey,
+          }),
+        ]);
+        const startupFailure = startupResults.find(
+          (result): result is PromiseRejectedResult =>
+            result.status === "rejected",
+        );
+        if (startupFailure) {
+          throw startupFailure.reason;
+        }
+
+        reporter.progress(4, 6, "Starting gateway...");
+        runtimeUrl = await startGateway(watch, resources, {
+          signingKey,
+          bootstrapSecret,
+          envOverrides: flagEnvVars,
+          requireReady: true,
+        });
+      } catch (error) {
+        reporter.error(
+          `\n❌ Local assistant startup failed — stopping partial processes.`,
+        );
+        await stopLocalProcesses(resources);
+        throw error;
+      }
+
+      const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+      const localEntry: AssistantEntry = {
+        assistantId: instanceName,
+        runtimeUrl,
+        localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
+        cloud: "local",
+        species,
+        hatchedAt: new Date().toISOString(),
+        resources: { ...resources, signingKey },
+        guardianBootstrapSecret: bootstrapSecret,
+      };
+
+      reporter.progress(5, 6, "Saving configuration...");
+      saveAssistantEntry(localEntry);
+      setActiveAssistant(instanceName);
+
+      return { resources, runtimeUrl, loopbackUrl, bootstrapSecret };
     });
-  } catch (error) {
-    // Gateway failed — stop the daemon we just started so we don't leave
-    // orphaned processes with no lock file entry.
-    reporter.error(
-      `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
-    );
-    await stopLocalProcesses(resources);
-    throw error;
-  }
 
   // Lease a guardian token so the desktop app can import it on first launch
   // instead of hitting /v1/guardian/init itself. Use loopback to satisfy
   // the daemon's local-only check — the mDNS runtimeUrl resolves to a LAN
   // IP which the daemon rejects as non-loopback.
-  reporter.progress(5, 6, "Securing connection...");
-  const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+  reporter.progress(6, 6, "Securing connection...");
   const maxLeaseAttempts = 3;
   let guardianAccessToken: string | undefined;
   for (let attempt = 1; attempt <= maxLeaseAttempts; attempt++) {
@@ -290,22 +318,6 @@ export async function hatchLocal(
     }
   }
 
-  // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-  const localEntry: AssistantEntry = {
-    assistantId: instanceName,
-    runtimeUrl,
-    localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
-    cloud: "local",
-    species,
-    hatchedAt: new Date().toISOString(),
-    resources: { ...resources, signingKey },
-    guardianBootstrapSecret: bootstrapSecret,
-  };
-
-  reporter.progress(6, 6, "Saving configuration...");
-  saveAssistantEntry(localEntry);
-  setActiveAssistant(instanceName);
-
   if (process.env.VELLUM_DESKTOP_APP) {
     installCLISymlink();
   }

package/src/lib/local-hatch-lock.ts

@@ -0,0 +1,322 @@
+import { execFileSync } from "child_process";
+import { createHash, randomUUID } from "crypto";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from "fs";
+import { hostname, userInfo } from "os";
+import { dirname, join } from "path";
+
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_RETRY_MS = 100;
+const MAX_LOCK_AGE_MS = DEFAULT_TIMEOUT_MS - 60_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const LIVE_OWNER_RECOVERY_GRACE_MS = 10_000;
+
+interface LocalHatchLockOptions {
+  lockPath?: string;
+  liveOwnerRecoveryGraceMs?: number;
+  timeoutMs?: number;
+  retryMs?: number;
+}
+
+interface LockOwner {
+  pid: number;
+  processStartedAt?: string;
+  token: string;
+}
+
+interface LockSnapshot {
+  owner?: LockOwner;
+  signature: string;
+}
+
+export function resolveLocalHatchLockPath(): string {
+  const machineKey = createHash("sha256")
+    .update(hostname())
+    .digest("hex")
+    .slice(0, 12);
+  return join(
+    userInfo().homedir,
+    ".cache",
+    "vellum",
+    "runtime",
+    machineKey,
+    "local-hatch.lock",
+  );
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function processStartedAt(pid: number): string | undefined {
+  try {
+    const value = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1_000,
+    }).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseOwner(raw: string): LockOwner | undefined {
+  try {
+    const parsed = JSON.parse(raw) as {
+      pid?: unknown;
+      processStartedAt?: unknown;
+      token?: unknown;
+    };
+    if (
+      typeof parsed.pid === "number" &&
+      Number.isInteger(parsed.pid) &&
+      parsed.pid > 0 &&
+      typeof parsed.token === "string" &&
+      parsed.token.length > 0
+    ) {
+      return {
+        pid: parsed.pid,
+        processStartedAt:
+          typeof parsed.processStartedAt === "string" &&
+          parsed.processStartedAt.length > 0
+            ? parsed.processStartedAt
+            : undefined,
+        token: parsed.token,
+      };
+    }
+  } catch {}
+  return undefined;
+}
+
+function readSnapshot(path: string): LockSnapshot | undefined {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return {
+      owner: parseOwner(raw),
+      signature: createHash("sha256").update(raw).digest("hex"),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function readOwner(path: string): LockOwner | undefined {
+  return readSnapshot(path)?.owner;
+}
+
+function fileAgeMs(path: string): number | undefined {
+  try {
+    return Date.now() - statSync(path).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+const expiredLiveOwners = new Map<string, number>();
+
+function ownerIsActive(
+  path: string,
+  owner: LockOwner | undefined,
+  liveOwnerRecoveryGraceMs: number,
+): boolean {
+  const ageMs = fileAgeMs(path);
+  if (!owner) {
+    return ageMs !== undefined && ageMs < MAX_LOCK_AGE_MS;
+  }
+  if (!processIsAlive(owner.pid)) {
+    return false;
+  }
+  if (owner.processStartedAt) {
+    const currentStartedAt = processStartedAt(owner.pid);
+    if (currentStartedAt) {
+      expiredLiveOwners.delete(owner.token);
+      return currentStartedAt === owner.processStartedAt;
+    }
+  }
+  if (ageMs !== undefined && ageMs < MAX_LOCK_AGE_MS) {
+    expiredLiveOwners.delete(owner.token);
+    return true;
+  }
+
+  const firstExpiredAt = expiredLiveOwners.get(owner.token) ?? Date.now();
+  expiredLiveOwners.set(owner.token, firstExpiredAt);
+  if (Date.now() - firstExpiredAt < liveOwnerRecoveryGraceMs) {
+    return true;
+  }
+  return false;
+}
+
+function writeOwnerFile(path: string, owner: LockOwner): void {
+  const fd = openSync(path, "wx", 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify(owner) + "\n");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function acquireRecoveryClaim(
+  lockPath: string,
+  staleSignature: string,
+  owner: LockOwner,
+  liveOwnerRecoveryGraceMs: number,
+): (() => void) | undefined {
+  const recoveryKey = staleSignature.slice(0, 16);
+  for (let generation = 0; generation < 100; generation++) {
+    const claimPath = `${lockPath}.recovery-${recoveryKey}-${generation}`;
+    try {
+      writeOwnerFile(claimPath, owner);
+      return () => releaseLock(claimPath, owner.token);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (
+        ownerIsActive(claimPath, readOwner(claimPath), liveOwnerRecoveryGraceMs)
+      ) {
+        return undefined;
+      }
+    }
+  }
+  return undefined;
+}
+
+function removeStaleLock(
+  lockPath: string,
+  recoveryOwner: LockOwner,
+  liveOwnerRecoveryGraceMs: number,
+): boolean {
+  const staleSnapshot = readSnapshot(lockPath);
+  if (!staleSnapshot) {
+    return true;
+  }
+  if (ownerIsActive(lockPath, staleSnapshot.owner, liveOwnerRecoveryGraceMs)) {
+    return false;
+  }
+
+  const releaseRecoveryClaim = acquireRecoveryClaim(
+    lockPath,
+    staleSnapshot.signature,
+    recoveryOwner,
+    liveOwnerRecoveryGraceMs,
+  );
+  if (!releaseRecoveryClaim) {
+    return false;
+  }
+
+  try {
+    const currentSnapshot = readSnapshot(lockPath);
+    if (!currentSnapshot) {
+      return true;
+    }
+    if (currentSnapshot.signature !== staleSnapshot.signature) {
+      return false;
+    }
+    if (
+      ownerIsActive(lockPath, currentSnapshot.owner, liveOwnerRecoveryGraceMs)
+    ) {
+      return false;
+    }
+    try {
+      unlinkSync(lockPath);
+      return true;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "ENOENT";
+    }
+  } finally {
+    releaseRecoveryClaim();
+  }
+}
+
+function releaseLock(lockPath: string, token: string): void {
+  if (readOwner(lockPath)?.token !== token) {
+    return;
+  }
+  try {
+    unlinkSync(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function refreshLock(lockPath: string, token: string): void {
+  if (readOwner(lockPath)?.token !== token) {
+    return;
+  }
+  try {
+    const now = new Date();
+    utimesSync(lockPath, now, now);
+  } catch {}
+}
+
+/**
+ * Serialize local assistant startup across CLI processes. Port availability is
+ * machine-wide even when callers use different lockfile or XDG directories,
+ * so allocation must remain exclusive until the new services have bound their
+ * ports and the assistant entry has been persisted.
+ */
+export async function withLocalHatchLock<T>(
+  action: () => Promise<T>,
+  options: LocalHatchLockOptions = {},
+): Promise<T> {
+  const lockPath = options.lockPath ?? resolveLocalHatchLockPath();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+  const liveOwnerRecoveryGraceMs =
+    options.liveOwnerRecoveryGraceMs ?? LIVE_OWNER_RECOVERY_GRACE_MS;
+  const deadline = Date.now() + timeoutMs;
+  const owner: LockOwner = {
+    pid: process.pid,
+    processStartedAt: processStartedAt(process.pid),
+    token: `${process.pid}-${randomUUID()}`,
+  };
+
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+
+  while (true) {
+    try {
+      writeOwnerFile(lockPath, owner);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (removeStaleLock(lockPath, owner, liveOwnerRecoveryGraceMs)) {
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for another local assistant to finish starting (${lockPath})`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryMs));
+      continue;
+    }
+
+    const heartbeat = setInterval(
+      () => refreshLock(lockPath, owner.token),
+      HEARTBEAT_INTERVAL_MS,
+    );
+    try {
+      return await action();
+    } finally {
+      clearInterval(heartbeat);
+      releaseLock(lockPath, owner.token);
+    }
+  }
+}

package/src/lib/local.ts

@@ -548,6 +548,7 @@ export function generateLocalSigningKey(): string {
 type DaemonStartOptions = {
   foreground?: boolean;
   defaultWorkspaceConfigPath?: string;
+  requireReady?: boolean;
   signingKey?: string;
 };
 
@@ -597,7 +598,10 @@ function applyDaemonEnvOverrides(
   applyIpcSocketDirOverride(env);
 }
 
-function logDaemonReadiness(readiness: DaemonReadiness): void {
+function logDaemonReadiness(
+  readiness: DaemonReadiness,
+  requireReady = false,
+): void {
   switch (readiness) {
     case "ready":
       console.log("   Assistant ready\n");
@@ -613,6 +617,11 @@ function logDaemonReadiness(readiness: DaemonReadiness): void {
       );
       break;
     default:
+      if (requireReady) {
+        throw new Error(
+          "Assistant did not bind its local port within 60 seconds.",
+        );
+      }
       console.log(
         "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
       );
@@ -1320,6 +1329,7 @@ export async function startLocalDaemon(
           resources.daemonPort,
           Date.now() + 60000,
         ),
+        options?.requireReady,
       );
     }
     return;
@@ -1362,6 +1372,7 @@ export async function startLocalDaemon(
         // classifies it without blocking on an in-flight migration.
         logDaemonReadiness(
           await probeDaemonReadinessWithRetry(resources.daemonPort),
+          options?.requireReady,
         );
         return;
       }
@@ -1513,7 +1524,7 @@ export async function startLocalDaemon(
         readiness = await probeDaemonReadiness(resources.daemonPort);
       }
 
-      logDaemonReadiness(readiness);
+      logDaemonReadiness(readiness, options?.requireReady);
     }
   } else {
     console.log("🔨 Starting local assistant...");
@@ -1535,6 +1546,7 @@ export async function startLocalDaemon(
           resources.daemonPort,
           Date.now() + 60000,
         ),
+        options?.requireReady,
       );
     }
   }
@@ -1547,6 +1559,7 @@ export async function startGateway(
     signingKey?: string;
     bootstrapSecret?: string;
     envOverrides?: Record<string, string>;
+    requireReady?: boolean;
   },
 ): Promise<string> {
   const effectiveGatewayPort = resources?.gatewayPort ?? GATEWAY_PORT;
@@ -1676,6 +1689,11 @@ export async function startGateway(
   // connection-refused errors.
   const ready = await waitForDaemonReady(effectiveGatewayPort, 30000);
   if (!ready) {
+    if (options?.requireReady) {
+      throw new Error(
+        "Assistant gateway did not bind its local port within 30 seconds.",
+      );
+    }
     console.warn(
       "⚠ Gateway started but health check did not respond within 30s",
     );