@vellumai/cli 0.11.4-dev.202608201710.fcf0423 → 0.11.4-dev.202608201915.5ca6ffa

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.4-dev.202608201710.fcf0423",
+  "version": "0.11.4-dev.202608201915.5ca6ffa",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/wake.test.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import * as assistantConfig from "../lib/assistant-config.js";
 import * as docker from "../lib/docker.js";
 import * as guardianToken from "../lib/guardian-token.js";
+import * as httpClient from "../lib/http-client.js";
 import * as ingressConfig from "../lib/ingress-config.js";
 import * as local from "../lib/local.js";
 import * as nginxIngress from "../lib/nginx-ingress.js";
@@ -167,12 +168,28 @@ mock.module("../lib/nginx-ingress.js", () => ({
   readIngressState: readIngressStateMock,
 }));
 
+const realHttpClient = { ...httpClient };
+
+const probeDaemonReadinessWithRetryMock = mock<
+  typeof httpClient.probeDaemonReadinessWithRetry
+>(async () => "ready");
+const waitForDaemonMigrationsReadyMock = mock<
+  typeof httpClient.waitForDaemonMigrationsReady
+>(async () => "ready");
+
+mock.module("../lib/http-client.js", () => ({
+  ...realHttpClient,
+  probeDaemonReadinessWithRetry: probeDaemonReadinessWithRetryMock,
+  waitForDaemonMigrationsReady: waitForDaemonMigrationsReadyMock,
+}));
+
 const { wake } = await import("../commands/wake.js");
 
 let tempDir: string;
 let originalArgv: string[];
 let logSpy: ReturnType<typeof spyOn>;
 let warnSpy: ReturnType<typeof spyOn>;
+let errorSpy: ReturnType<typeof spyOn>;
 let localEntry: AssistantEntry;
 
 function makeLocalEntry(): AssistantEntry {
@@ -199,6 +216,7 @@ beforeEach(() => {
   process.argv = ["bun", "vellum", "wake", "--watch", "local-assistant"];
   logSpy = spyOn(console, "log").mockImplementation(() => {});
   warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  errorSpy = spyOn(console, "error").mockImplementation(() => {});
 
   localEntry = makeLocalEntry();
   resolveTargetAssistantMock.mockReset();
@@ -231,6 +249,10 @@ beforeEach(() => {
   startCesMock.mockResolvedValue(undefined);
   isProcessAliveMock.mockReset();
   isProcessAliveMock.mockReturnValue({ alive: false, pid: null });
+  probeDaemonReadinessWithRetryMock.mockReset();
+  probeDaemonReadinessWithRetryMock.mockResolvedValue("ready");
+  waitForDaemonMigrationsReadyMock.mockReset();
+  waitForDaemonMigrationsReadyMock.mockResolvedValue("ready");
   seedGuardianTokenFromSiblingEnvMock.mockReset();
   seedGuardianTokenFromSiblingEnvMock.mockReturnValue(false);
   loadGuardianTokenMock.mockReset();
@@ -263,6 +285,7 @@ afterEach(() => {
   process.argv = originalArgv;
   logSpy.mockRestore();
   warnSpy.mockRestore();
+  errorSpy.mockRestore();
   if (tempDir) {
     rmSync(tempDir, { recursive: true, force: true });
   }
@@ -277,6 +300,7 @@ afterAll(() => {
   mock.module("../lib/ngrok", () => realNgrok);
   mock.module("../lib/ingress-config.js", () => realIngressConfig);
   mock.module("../lib/nginx-ingress.js", () => realNginxIngress);
+  mock.module("../lib/http-client.js", () => realHttpClient);
 });
 
 describe("vellum wake", () => {
@@ -456,6 +480,102 @@ describe("vellum wake", () => {
   });
 });
 
+describe("vellum wake: daemon startup failure", () => {
+  const daemonPidOf = (dir: string) => join(dir, ".vellum", "daemon.pid");
+
+  beforeEach(() => {
+    process.argv = ["bun", "vellum", "wake", "local-assistant"];
+    // The daemon needs starting; the gateway is already serving.
+    resolveProcessStateMock.mockImplementation(
+      async (_pidFile, _port, label) =>
+        label === "Gateway"
+          ? { status: "healthy", pid: 456 }
+          : { status: "needs_start", pid: null },
+    );
+  });
+
+  test("fails when the freshly spawned daemon is not running", async () => {
+    /**
+     * Tests that a daemon which aborts during startup (an occupied runtime
+     * HTTP port) fails the command instead of reporting a successful wake.
+     */
+
+    // GIVEN the spawned daemon left no live process behind
+    isProcessAliveMock.mockReturnValue({ alive: false, pid: null });
+
+    // AND a foreign listener on the runtime HTTP port answers readiness in
+    // the dead daemon's place
+    probeDaemonReadinessWithRetryMock.mockResolvedValue("ready");
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`process.exit:${code}`);
+    }) as never);
+
+    // WHEN wake runs
+    const result = wake();
+
+    // THEN it exits nonzero, names the port on stderr, and never claims
+    // the wake completed
+    await expect(result).rejects.toThrow("process.exit:1");
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("exited during startup"),
+    );
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("7821"));
+    expect(logSpy).not.toHaveBeenCalledWith("Wake complete.");
+    expect(startGatewayMock).not.toHaveBeenCalled();
+    exitSpy.mockRestore();
+  });
+
+  test("completes when the freshly spawned daemon is running", async () => {
+    /**
+     * Tests that a healthy fresh spawn still reports a completed wake.
+     */
+
+    // GIVEN the spawned daemon is alive and ready
+    isProcessAliveMock.mockImplementation((pidFile) =>
+      pidFile === daemonPidOf(tempDir)
+        ? { alive: true, pid: 123 }
+        : { alive: false, pid: null },
+    );
+    probeDaemonReadinessWithRetryMock.mockResolvedValue("ready");
+
+    // WHEN wake runs
+    await wake();
+
+    // THEN it reports success and starts the gateway
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("completes when the freshly spawned daemon is still migrating", async () => {
+    /**
+     * Tests that a live daemon running database migrations is reported as a
+     * degraded success, not a failure.
+     */
+
+    // GIVEN the spawned daemon is alive but still migrating past the
+    // gateway-coordination wait
+    isProcessAliveMock.mockImplementation((pidFile) =>
+      pidFile === daemonPidOf(tempDir)
+        ? { alive: true, pid: 123 }
+        : { alive: false, pid: null },
+    );
+    probeDaemonReadinessWithRetryMock.mockResolvedValue("migrating");
+    waitForDaemonMigrationsReadyMock.mockResolvedValue("migrating");
+
+    // WHEN wake runs
+    await wake();
+
+    // THEN it reports the migration state and completes
+    expect(logSpy).toHaveBeenCalledWith(
+      "Assistant is still running database migrations; DB-backed routes return 503 until they finish.",
+    );
+    expect(logSpy).toHaveBeenCalledWith("Wake complete.");
+  });
+});
+
 describe("vellum wake — tunnel edge restore", () => {
   const webhookConfig = { telegram: { botUsername: "bot" } };
   const enabledConfig = {

package/src/commands/wake.ts

@@ -229,7 +229,19 @@ export async function wake(): Promise<void> {
       startCes(watch, resources),
       startLocalDaemon(watch, resources, { foreground, signingKey }),
     ]);
-    // startLocalDaemon's post-spawn wait is bounded (60s) — a longer
+    // A daemon that aborts during startup (an occupied runtime HTTP port, a
+    // fatal subsystem failure) leaves no process behind, and readiness alone
+    // cannot see that: whatever foreign listener holds the port answers the
+    // probe in its place. Liveness is the authoritative signal, so check it
+    // first and fail the command instead of reporting a successful wake for
+    // an assistant that is not running.
+    if (!isProcessAlive(pidFile).alive) {
+      console.error(
+        `Error: the assistant exited during startup and is not running. Its runtime HTTP port ${resources.daemonPort} may be held by another process (check \`lsof -i :${resources.daemonPort}\`); the daemon log records the startup error it reported.`,
+      );
+      process.exit(1);
+    }
+    // startLocalDaemon's post-spawn wait is bounded (60s), and a longer
     // migration outlives it. Classify the fresh spawn the same way the
     // attach path does, so the gateway-coordination wait below applies to
     // both paths and wake's closing summary stays honest.

package/src/lib/__tests__/local-daemon-readiness.test.ts

@@ -0,0 +1,128 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+
+import { type DaemonSpawn, reportFreshSpawnReadiness } from "../local.js";
+
+// Above every platform default pid ceiling, so no live process owns it.
+const DEAD_PID = 999999;
+// No daemon listens here, so port ownership can never be confirmed and the
+// settle window decides the outcome.
+const UNSERVED_PORT = 7999;
+
+describe("reportFreshSpawnReadiness", () => {
+  let tempDir: string;
+  let pidFile: string;
+  let logSpy: ReturnType<typeof spyOn>;
+
+  const spawnHandle = (exited: boolean): DaemonSpawn => ({
+    hasExited: () => exited,
+  });
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "vellum-readiness-"));
+    pidFile = join(tempDir, "daemon.pid");
+    logSpy = spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("reports the readiness of a daemon that survived its spawn", async () => {
+    /**
+     * Tests that a daemon still running after the settle window has its
+     * probed state reported.
+     */
+
+    // GIVEN the spawned daemon is running
+    writeFileSync(pidFile, String(process.pid), "utf-8");
+
+    // WHEN its readiness is reported
+    await reportFreshSpawnReadiness(
+      spawnHandle(false),
+      pidFile,
+      UNSERVED_PORT,
+      "ready",
+    );
+
+    // THEN the probed state reaches the operator
+    expect(logSpy).toHaveBeenCalledWith("   Assistant ready\n");
+  });
+
+  test("reports a startup failure instead of a probe answered by a foreign listener", async () => {
+    /**
+     * Tests that a daemon which aborted during startup is reported as not
+     * running, even when the probe reports it as up.
+     */
+
+    // GIVEN the spawned daemon exited, while a foreign listener holding its
+    // runtime HTTP port answered the readiness probe in its place
+    writeFileSync(pidFile, String(DEAD_PID), "utf-8");
+
+    // WHEN its readiness is reported
+    await reportFreshSpawnReadiness(
+      spawnHandle(true),
+      pidFile,
+      UNSERVED_PORT,
+      "migrating",
+    );
+
+    // THEN the failure is reported rather than the probe's optimistic state
+    expect(logSpy).toHaveBeenCalledWith(
+      "   ⚠️  Assistant exited during startup and is not running\n",
+    );
+    expect(logSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining("database migrations still running"),
+    );
+  });
+
+  test("reports a startup failure when the spawn dies during the settle window", async () => {
+    /**
+     * Tests that a daemon which is still alive when its readiness is probed,
+     * and aborts moments later, is reported as not running.
+     */
+
+    // GIVEN a spawn that is alive when reported and exits shortly after
+    writeFileSync(pidFile, String(process.pid), "utf-8");
+    let exited = false;
+    const spawn: DaemonSpawn = { hasExited: () => exited };
+    setTimeout(() => {
+      exited = true;
+    }, 150);
+
+    // WHEN its readiness is reported
+    await reportFreshSpawnReadiness(spawn, pidFile, UNSERVED_PORT, "ready");
+
+    // THEN the failure is reported rather than the probe's optimistic state
+    expect(logSpy).toHaveBeenCalledWith(
+      "   ⚠️  Assistant exited during startup and is not running\n",
+    );
+    expect(logSpy).not.toHaveBeenCalledWith("   Assistant ready\n");
+  });
+
+  test("throws for a failed spawn when the caller requires readiness", async () => {
+    /**
+     * Tests that callers which cannot continue without a running assistant
+     * (hatch) fail rather than proceeding on a foreign listener's probe.
+     */
+
+    // GIVEN the spawned daemon exited and the caller requires readiness
+    writeFileSync(pidFile, String(DEAD_PID), "utf-8");
+
+    // WHEN its readiness is reported
+    const report = reportFreshSpawnReadiness(
+      spawnHandle(true),
+      pidFile,
+      UNSERVED_PORT,
+      "ready",
+      true,
+    );
+
+    // THEN startup fails loudly
+    await expect(report).rejects.toThrow("exited during startup");
+  });
+});

package/src/lib/local.ts

@@ -1,4 +1,10 @@
-import { execFileSync, execSync, spawn, spawnSync } from "child_process";
+import {
+  type ChildProcess,
+  execFileSync,
+  execSync,
+  spawn,
+  spawnSync,
+} from "child_process";
 import { createHash, randomBytes } from "crypto";
 import {
   existsSync,
@@ -40,6 +46,7 @@ import { stopIngressNginx } from "./nginx-ingress.js";
 import {
   type ProcessState,
   executableName,
+  isProcessAlive,
   pathListDelimiter,
   resolveProcessState,
   stopProcess,
@@ -637,12 +644,12 @@ function logDaemonReadiness(
       break;
     case "migrating":
       console.log(
-        "   Assistant is up — database migrations still running; DB-backed commands return 503 until they finish\n",
+        "   Assistant is up. Database migrations still running; DB-backed commands return 503 until they finish\n",
       );
       break;
     case "failed":
       console.log(
-        "   ⚠️  Assistant database migrations FAILED — DB-backed commands return 503 until the assistant is restarted\n",
+        "   ⚠️  Assistant database migrations FAILED. DB-backed commands return 503 until the assistant is restarted\n",
       );
       break;
     default:
@@ -652,11 +659,100 @@ function logDaemonReadiness(
         );
       }
       console.log(
-        "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
+        "   ⚠️  Assistant did not become ready within 60s, continuing anyway\n",
       );
   }
 }
 
+/**
+ * Handle to a daemon this process spawned, reporting whether that child has
+ * since exited. Attach paths have no handle, since the daemon they found is
+ * not a child of this process.
+ */
+export type DaemonSpawn = { hasExited: () => boolean };
+
+function trackDaemonSpawn(child: ChildProcess): DaemonSpawn {
+  let exited = false;
+  child.once("exit", () => {
+    exited = true;
+  });
+  return { hasExited: () => exited };
+}
+
+/** How long a fresh spawn gets to abort before its readiness is trusted. */
+const FRESH_SPAWN_SETTLE_MS = 2000;
+const FRESH_SPAWN_POLL_MS = 100;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * True when a freshly spawned daemon is the process serving its runtime HTTP
+ * port.
+ *
+ * A readiness answer proves only that something listens on the port: a foreign
+ * listener holding it answers in the daemon's place, so a daemon aborting over
+ * the collision still reads as "up" or "migrating". Ownership is confirmed
+ * from the listening PID where the platform can report it. Otherwise the spawn
+ * gets a short settle window, which is long enough because transports bind
+ * before migrations run, so an address collision aborts the daemon early.
+ */
+async function freshSpawnServesRuntimePort(
+  spawn: DaemonSpawn,
+  pidFile: string,
+  daemonPort: number,
+): Promise<boolean> {
+  const spawnPid = (): number | null => {
+    if (spawn.hasExited()) {
+      return null;
+    }
+    return isProcessAlive(pidFile).pid;
+  };
+
+  const pid = spawnPid();
+  if (pid === null) {
+    return false;
+  }
+  if (findPidListeningOnPort(daemonPort) === pid) {
+    return true;
+  }
+
+  const deadline = Date.now() + FRESH_SPAWN_SETTLE_MS;
+  while (Date.now() < deadline) {
+    await sleep(FRESH_SPAWN_POLL_MS);
+    if (spawnPid() === null) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Report a freshly spawned daemon's readiness, gated on that daemon serving
+ * the runtime HTTP port the readiness was probed on.
+ *
+ * A daemon that aborts during startup (an occupied runtime HTTP port, a fatal
+ * subsystem failure) is reported as the startup failure it is instead of an
+ * optimistic line about an assistant that is not running.
+ */
+export async function reportFreshSpawnReadiness(
+  spawn: DaemonSpawn,
+  pidFile: string,
+  daemonPort: number,
+  readiness: DaemonReadiness,
+  requireReady = false,
+): Promise<void> {
+  if (!(await freshSpawnServesRuntimePort(spawn, pidFile, daemonPort))) {
+    if (requireReady) {
+      throw new Error("Assistant exited during startup and is not running.");
+    }
+    console.log("   ⚠️  Assistant exited during startup and is not running\n");
+    return;
+  }
+  logDaemonReadiness(readiness, requireReady);
+}
+
 function logAssistantAlreadyRunning(
   pid: number,
   status: ProcessState["status"],
@@ -676,7 +772,7 @@ async function startDaemonFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
   options?: DaemonStartOptions,
-): Promise<boolean> {
+): Promise<DaemonSpawn | null> {
   const foreground = options?.foreground ?? false;
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
 
@@ -686,7 +782,9 @@ async function startDaemonFromSource(
   mkdirSync(dirname(pidFile), { recursive: true });
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
-  if (await awaitStartingSentinel(pidFile, resources.daemonPort)) return false;
+  if (await awaitStartingSentinel(pidFile, resources.daemonPort)) {
+    return null;
+  }
 
   const daemonState = await resolveProcessState(
     pidFile,
@@ -697,10 +795,12 @@ async function startDaemonFromSource(
   );
   if (daemonState.status !== "needs_start") {
     logAssistantAlreadyRunning(daemonState.pid, daemonState.status);
-    return false;
+    return null;
   }
 
-  if (await checkOrphanedDaemon(pidFile, resources.daemonPort)) return false;
+  if (await checkOrphanedDaemon(pidFile, resources.daemonPort)) {
+    return null;
+  }
 
   const env: Record<string, string | undefined> = {
     ...process.env,
@@ -744,14 +844,14 @@ async function startDaemonFromSource(
         return c;
       })();
 
-  if (child.pid) {
-    writeFileSync(pidFile, String(child.pid), "utf-8");
-  } else {
+  if (!child.pid) {
     try {
       unlinkSync(pidFile);
     } catch {}
+    return null;
   }
-  return true;
+  writeFileSync(pidFile, String(child.pid), "utf-8");
+  return trackDaemonSpawn(child);
 }
 
 // NOTE: startDaemonWatchFromSource() is the CLI-side watch-mode daemon
@@ -762,7 +862,7 @@ async function startDaemonWatchFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
   options?: DaemonStartOptions,
-): Promise<boolean> {
+): Promise<DaemonSpawn | null> {
   const mainPath = resolveDaemonMainPath(assistantIndex);
   if (!existsSync(mainPath)) {
     throw new Error(`Daemon main.ts not found at ${mainPath}`);
@@ -772,7 +872,9 @@ async function startDaemonWatchFromSource(
   mkdirSync(dirname(pidFile), { recursive: true });
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
-  if (await awaitStartingSentinel(pidFile, resources.daemonPort)) return false;
+  if (await awaitStartingSentinel(pidFile, resources.daemonPort)) {
+    return null;
+  }
 
   const daemonState = await resolveProcessState(
     pidFile,
@@ -783,10 +885,12 @@ async function startDaemonWatchFromSource(
   );
   if (daemonState.status !== "needs_start") {
     logAssistantAlreadyRunning(daemonState.pid, daemonState.status);
-    return false;
+    return null;
   }
 
-  if (await checkOrphanedDaemon(pidFile, resources.daemonPort)) return false;
+  if (await checkOrphanedDaemon(pidFile, resources.daemonPort)) {
+    return null;
+  }
 
   const env: Record<string, string | undefined> = {
     ...process.env,
@@ -811,16 +915,16 @@ async function startDaemonWatchFromSource(
   const daemonPid = child.pid;
 
   // Overwrite sentinel with real PID, or clean up on spawn failure.
-  if (daemonPid) {
-    writeFileSync(pidFile, String(daemonPid), "utf-8");
-  } else {
+  if (!daemonPid) {
     try {
       unlinkSync(pidFile);
     } catch {}
+    return null;
   }
+  writeFileSync(pidFile, String(daemonPid), "utf-8");
 
   console.log("   Assistant started in watch mode (bun --watch)");
-  return true;
+  return trackDaemonSpawn(child);
 }
 
 function resolveGatewayDir(resources?: LocalInstanceResources): string {
@@ -1394,10 +1498,16 @@ export async function startLocalDaemon(
     // already-running daemon was classified and logged inside
     // startDaemonFromSource, and re-waiting would just block on a migration
     // the user was already told about.
-    if (
-      await startDaemonFromSource(runtimeAssistantIndex, resources, options)
-    ) {
-      logDaemonReadiness(
+    const runtimeSpawn = await startDaemonFromSource(
+      runtimeAssistantIndex,
+      resources,
+      options,
+    );
+    if (runtimeSpawn) {
+      await reportFreshSpawnReadiness(
+        runtimeSpawn,
+        getDaemonPidPath(resources),
+        resources.daemonPort,
         await waitForDaemonMigrationsReady(
           resources.daemonPort,
           Date.now() + 60000,
@@ -1437,6 +1547,7 @@ export async function startLocalDaemon(
     if (daemonAlive) {
       logAssistantAlreadyRunning(daemonState.pid, daemonState.status);
     }
+    let daemonSpawn: DaemonSpawn | null = null;
 
     if (!daemonAlive) {
       if (await checkOrphanedDaemon(pidFile, resources.daemonPort)) {
@@ -1558,6 +1669,7 @@ export async function startLocalDaemon(
       // Overwrite sentinel with real PID, or clean up on spawn failure.
       if (daemonPid) {
         writeFileSync(pidFile, String(daemonPid), "utf-8");
+        daemonSpawn = trackDaemonSpawn(child);
       } else {
         try {
           unlinkSync(pidFile);
@@ -1596,19 +1708,17 @@ export async function startLocalDaemon(
         const assistantIndex = resolveAssistantIndexPath(resources);
         if (assistantIndex) {
           console.log(
-            "   Bundled assistant not healthy after 60s — falling back to source assistant...",
+            "   Bundled assistant not healthy after 60s, falling back to source assistant...",
           );
           // Kill the bundled daemon to avoid two processes competing for the same port
           await stopProcessByPidFile(pidFile, "bundled daemon");
-          if (watch) {
-            await startDaemonWatchFromSource(
-              assistantIndex,
-              resources,
-              options,
-            );
-          } else {
-            await startDaemonFromSource(assistantIndex, resources, options);
-          }
+          daemonSpawn = watch
+            ? await startDaemonWatchFromSource(
+                assistantIndex,
+                resources,
+                options,
+              )
+            : await startDaemonFromSource(assistantIndex, resources, options);
           readiness = await waitForDaemonMigrationsReady(
             resources.daemonPort,
             Date.now() + 60000,
@@ -1621,7 +1731,17 @@ export async function startLocalDaemon(
         readiness = await probeDaemonReadiness(resources.daemonPort);
       }
 
-      logDaemonReadiness(readiness, options?.requireReady);
+      if (daemonSpawn) {
+        await reportFreshSpawnReadiness(
+          daemonSpawn,
+          pidFile,
+          resources.daemonPort,
+          readiness,
+          options?.requireReady,
+        );
+      } else {
+        logDaemonReadiness(readiness, options?.requireReady);
+      }
     }
   } else {
     console.log("🔨 Starting local assistant...");
@@ -1633,12 +1753,15 @@ export async function startLocalDaemon(
           "  Ensure the daemon binary is bundled alongside the CLI, or run from the source tree.",
       );
     }
-    const spawned = watch
+    const sourceSpawn = watch
       ? await startDaemonWatchFromSource(assistantIndex, resources, options)
       : await startDaemonFromSource(assistantIndex, resources, options);
     // Attach case was classified and logged inside the start function.
-    if (spawned) {
-      logDaemonReadiness(
+    if (sourceSpawn) {
+      await reportFreshSpawnReadiness(
+        sourceSpawn,
+        getDaemonPidPath(resources),
+        resources.daemonPort,
         await waitForDaemonMigrationsReady(
           resources.daemonPort,
           Date.now() + 60000,