@vellumai/cli 0.4.56 → 0.5.0

package/src/lib/docker.ts

@@ -1,15 +1,20 @@
-import { spawn as nodeSpawn } from "child_process";
-import { existsSync, watch as fsWatch } from "fs";
+import { chmodSync, existsSync, mkdirSync, watch as fsWatch } from "fs";
+import { arch, platform } from "os";
 import { dirname, join } from "path";
 
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
 import cliPkg from "../../package.json";
 
-import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
+import {
+  findAssistantByName,
+  saveAssistantEntry,
+  setActiveAssistant,
+} from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { DEFAULT_GATEWAY_PORT } from "./constants";
 import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
+import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
 import { exec, execOutput } from "./step-runner";
 import {
@@ -19,73 +24,217 @@ import {
   writeToLogFile,
 } from "./xdg-log";
 
-type ServiceName = "assistant" | "credential-executor" | "gateway";
+export type ServiceName = "assistant" | "credential-executor" | "gateway";
 
 const DOCKERHUB_ORG = "vellumai";
-const DOCKERHUB_IMAGES: Record<ServiceName, string> = {
+export const DOCKERHUB_IMAGES: Record<ServiceName, string> = {
   assistant: `${DOCKERHUB_ORG}/vellum-assistant`,
   "credential-executor": `${DOCKERHUB_ORG}/vellum-credential-executor`,
   gateway: `${DOCKERHUB_ORG}/vellum-gateway`,
 };
 
 /** Internal ports exposed by each service's Dockerfile. */
-const ASSISTANT_INTERNAL_PORT = 3001;
-const GATEWAY_INTERNAL_PORT = 7830;
+export const ASSISTANT_INTERNAL_PORT = 3001;
+export const GATEWAY_INTERNAL_PORT = 7830;
+
+/** Max time to wait for the assistant container to emit the readiness sentinel. */
+export const DOCKER_READY_TIMEOUT_MS = 3 * 60 * 1000;
+
+/** Directory for user-local binary installs (no sudo required). */
+const LOCAL_BIN_DIR = join(
+  process.env.HOME || process.env.USERPROFILE || ".",
+  ".local",
+  "bin",
+);
 
 /**
- * Checks whether the `docker` CLI and daemon are available on the system.
- * Installs Colima and Docker via Homebrew if the CLI is missing, and starts
- * Colima if the Docker daemon is not reachable.
+ * Returns the macOS architecture suffix used by GitHub release artifacts.
+ * Maps Node's `arch()` values to the names used in release URLs.
  */
-async function ensureDockerInstalled(): Promise<void> {
-  let installed = false;
+function releaseArch(): string {
+  const a = arch();
+  if (a === "arm64") return "aarch64";
+  if (a === "x64") return "x86_64";
+  return a;
+}
+
+/**
+ * Downloads a file from `url` to `destPath`, makes it executable, and returns
+ * the destination path. Throws on failure.
+ */
+async function downloadBinary(
+  url: string,
+  destPath: string,
+  label: string,
+): Promise<void> {
+  console.log(`  ⬇ Downloading ${label}...`);
+  await exec("bash", [
+    "-c",
+    `curl -fsSL -o "${destPath}" "${url}" && chmod +x "${destPath}"`,
+  ]);
+}
+
+/**
+ * Downloads and extracts a `.tar.gz` archive into `destDir`.
+ */
+async function downloadAndExtract(
+  url: string,
+  destDir: string,
+  label: string,
+): Promise<void> {
+  console.log(`  ⬇ Downloading ${label}...`);
+  await exec("bash", ["-c", `curl -fsSL "${url}" | tar xz -C "${destDir}"`]);
+}
+
+/**
+ * Installs Docker CLI, Colima, and Lima by downloading pre-built binaries
+ * directly into ~/.vellum/bin/. No Homebrew or sudo required.
+ *
+ * Falls back to Homebrew if available (e.g. admin users who prefer it).
+ */
+async function installDockerToolchain(): Promise<void> {
+  // Try Homebrew first if available — it handles updates and dependencies.
+  let hasBrew = false;
   try {
-    await execOutput("docker", ["--version"]);
-    installed = true;
+    await execOutput("brew", ["--version"]);
+    hasBrew = true;
   } catch {
-    // docker CLI not found — install it
+    // brew not found
   }
 
-  if (!installed) {
-    // Check whether Homebrew is available before attempting to use it.
-    let hasBrew = false;
+  if (hasBrew) {
+    console.log("🐳 Docker not found. Installing via Homebrew...");
     try {
-      await execOutput("brew", ["--version"]);
-      hasBrew = true;
+      await exec("brew", ["install", "colima", "docker"]);
+      return;
     } catch {
-      // brew not found
+      console.log(
+        "  ⚠ Homebrew install failed, falling back to direct binary download...",
+      );
     }
+  }
 
-    if (!hasBrew) {
-      console.log("🍺 Homebrew not found. Installing Homebrew...");
-      try {
-        await exec("bash", [
-          "-c",
-          'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
-        ]);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(
-          `Failed to install Homebrew. Please install Docker manually from https://www.docker.com/products/docker-desktop/\n${message}`,
-        );
-      }
+  // Direct binary install — no sudo required.
+  console.log(
+    "🐳 Docker not found. Installing Docker, Colima, and Lima to ~/.local/bin/...",
+  );
 
-      // Homebrew on Apple Silicon installs to /opt/homebrew; add it to PATH
-      // so subsequent brew/colima/docker invocations work in this session.
-      if (!process.env.PATH?.includes("/opt/homebrew")) {
-        process.env.PATH = `/opt/homebrew/bin:/opt/homebrew/sbin:${process.env.PATH}`;
-      }
-    }
+  mkdirSync(LOCAL_BIN_DIR, { recursive: true });
 
-    console.log("🐳 Docker not found. Installing via Homebrew...");
-    try {
-      await exec("brew", ["install", "colima", "docker"]);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+  const cpuArch = releaseArch();
+  const isMac = platform() === "darwin";
+
+  if (!isMac) {
+    throw new Error(
+      "Automatic Docker installation is only supported on macOS. " +
+        "Please install Docker manually: https://docs.docker.com/engine/install/",
+    );
+  }
+
+  // --- Docker CLI ---
+  // Docker publishes static binaries at download.docker.com.
+  const dockerArch = cpuArch === "aarch64" ? "aarch64" : "x86_64";
+  const dockerTarUrl = `https://download.docker.com/mac/static/stable/${dockerArch}/docker-27.5.1.tgz`;
+  const dockerTmpDir = join(LOCAL_BIN_DIR, ".docker-tmp");
+  mkdirSync(dockerTmpDir, { recursive: true });
+  try {
+    await downloadAndExtract(dockerTarUrl, dockerTmpDir, "Docker CLI");
+    // The archive extracts to docker/docker — move it to our bin dir.
+    await exec("mv", [
+      join(dockerTmpDir, "docker", "docker"),
+      join(LOCAL_BIN_DIR, "docker"),
+    ]);
+    chmodSync(join(LOCAL_BIN_DIR, "docker"), 0o755);
+  } finally {
+    await exec("rm", ["-rf", dockerTmpDir]).catch(() => {});
+  }
+
+  // --- Colima ---
+  const colimaArch = cpuArch === "aarch64" ? "arm64" : "x86_64";
+  const colimaUrl = `https://github.com/abiosoft/colima/releases/latest/download/colima-Darwin-${colimaArch}`;
+  await downloadBinary(colimaUrl, join(LOCAL_BIN_DIR, "colima"), "Colima");
+
+  // --- Lima ---
+  // Lima publishes tar.gz archives with bin/limactl and other tools.
+  const limaArch = cpuArch === "aarch64" ? "arm64" : "x86_64";
+  const limaVersionUrl =
+    "https://api.github.com/repos/lima-vm/lima/releases/latest";
+  let limaVersion: string;
+  try {
+    const resp = await fetch(limaVersionUrl);
+    if (!resp.ok) {
+      throw new Error(
+        `GitHub API returned ${resp.status}` +
+          (resp.status === 403
+            ? " (rate-limited) — try again later."
+            : `. Check your network connection.`),
+      );
+    }
+    const data = (await resp.json()) as { tag_name?: string };
+    if (!data.tag_name) {
+      throw new Error("GitHub API response missing tag_name.");
+    }
+    limaVersion = data.tag_name; // e.g. "v1.0.3"
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to fetch latest Lima version: ${message}`);
+  }
+  const limaVersionNum = limaVersion.replace(/^v/, ""); // "1.0.3"
+  const limaTarUrl = `https://github.com/lima-vm/lima/releases/download/${limaVersion}/lima-${limaVersionNum}-Darwin-${limaArch}.tar.gz`;
+  // Lima archives contain bin/limactl, bin/lima, share/lima/..., so extract
+  // into the parent (~/.local/) so that limactl lands in ~/.local/bin/.
+  const localDir = dirname(LOCAL_BIN_DIR);
+  await downloadAndExtract(limaTarUrl, localDir, "Lima");
+
+  // Verify all binaries are in place.
+  for (const bin of ["docker", "colima", "limactl"]) {
+    if (!existsSync(join(LOCAL_BIN_DIR, bin))) {
       throw new Error(
-        `Failed to install Docker via Homebrew. Please install Docker manually.\n${message}`,
+        `${bin} binary not found after installation. Please install Docker manually.`,
       );
     }
+  }
+
+  console.log("  ✅ Docker toolchain installed to ~/.local/bin/");
+}
+
+/**
+ * Ensures ~/.local/bin/ is on PATH for this process so that docker, colima,
+ * and limactl are discoverable.
+ */
+function ensureLocalBinOnPath(): void {
+  const currentPath = process.env.PATH || "";
+  if (!currentPath.includes(LOCAL_BIN_DIR)) {
+    process.env.PATH = `${LOCAL_BIN_DIR}:${currentPath}`;
+  }
+}
+
+/**
+ * Checks whether the `docker` CLI and daemon are available on the system.
+ * Installs Colima and Docker via direct binary download if missing (no sudo
+ * required), and starts Colima if the Docker daemon is not reachable.
+ */
+async function ensureDockerInstalled(): Promise<void> {
+  // Always add ~/.local/bin to PATH so previously installed binaries are found.
+  ensureLocalBinOnPath();
+
+  // Check that docker, colima, and limactl are all available. If any is
+  // missing (e.g. partial install from a previous failure), re-run install.
+  const toolchainComplete = await (async () => {
+    try {
+      await execOutput("docker", ["--version"]);
+      await execOutput("colima", ["version"]);
+      await execOutput("limactl", ["--version"]);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+
+  if (!toolchainComplete) {
+    await installDockerToolchain();
+    // Re-check PATH after install.
+    ensureLocalBinOnPath();
 
     try {
       await execOutput("docker", ["--version"]);
@@ -97,7 +246,7 @@ async function ensureDockerInstalled(): Promise<void> {
     }
   }
 
-  // Verify the Docker daemon is reachable; start Colima if it isn't
+  // Verify the Docker daemon is reachable; start Colima if it isn't.
   try {
     await exec("docker", ["info"]);
   } catch {
@@ -128,51 +277,20 @@ async function ensureDockerInstalled(): Promise<void> {
   }
 }
 
-/**
- * Creates a line-buffered output prefixer that prepends a tag to each
- * line from a container's stdout/stderr. Calls `onLine` for each complete
- * line so the caller can detect sentinel output (e.g. hatch completion).
- */
-function createLinePrefixer(
-  stream: NodeJS.WritableStream,
-  prefix: string,
-  onLine?: (line: string) => void,
-): { write(data: Buffer): void; flush(): void } {
-  let remainder = "";
-  return {
-    write(data: Buffer) {
-      const text = remainder + data.toString();
-      const lines = text.split("\n");
-      remainder = lines.pop() ?? "";
-      for (const line of lines) {
-        stream.write(`   [${prefix}] ${line}\n`);
-        onLine?.(line);
-      }
-    },
-    flush() {
-      if (remainder) {
-        stream.write(`   [${prefix}] ${remainder}\n`);
-        onLine?.(remainder);
-        remainder = "";
-      }
-    },
-  };
-}
-
 /** Derive the Docker resource names from the instance name. */
-function dockerResourceNames(instanceName: string) {
+export function dockerResourceNames(instanceName: string) {
   return {
     assistantContainer: `${instanceName}-assistant`,
     cesContainer: `${instanceName}-credential-executor`,
-    dataVolume: `vellum-data-${instanceName}`,
+    dataVolume: `${instanceName}-data`,
     gatewayContainer: `${instanceName}-gateway`,
-    network: `vellum-net-${instanceName}`,
-    socketVolume: `vellum-ces-bootstrap-${instanceName}`,
+    network: `${instanceName}-net`,
+    socketVolume: `${instanceName}-socket`,
   };
 }
 
 /** Silently attempt to stop and remove a Docker container. */
-async function removeContainer(containerName: string): Promise<void> {
+export async function removeContainer(containerName: string): Promise<void> {
   try {
     await exec("docker", ["stop", containerName]);
   } catch {
@@ -188,6 +306,20 @@ async function removeContainer(containerName: string): Promise<void> {
 export async function retireDocker(name: string): Promise<void> {
   console.log(`\u{1F5D1}\ufe0f  Stopping Docker containers for '${name}'...\n`);
 
+  // Stop the file watcher process if one is tracked for this instance.
+  const entry = findAssistantByName(name);
+  const watcherPid =
+    typeof entry?.watcherPid === "number" ? entry.watcherPid : null;
+  if (watcherPid !== null) {
+    if (isVellumProcess(watcherPid)) {
+      await stopProcess(watcherPid, "file-watcher");
+    } else {
+      console.log(
+        `PID ${watcherPid} is not a vellum process — skipping stale file-watcher PID.`,
+      );
+    }
+  }
+
   const res = dockerResourceNames(name);
 
   await removeContainer(res.cesContainer);
@@ -197,7 +329,7 @@ export async function retireDocker(name: string): Promise<void> {
   // Also clean up a legacy single-container instance if it exists
   await removeContainer(name);
 
-  // Remove shared network and volumes
+  // Remove network and volumes
   try {
     await exec("docker", ["network", "rm", res.network]);
   } catch {
@@ -303,13 +435,14 @@ function serviceImageConfigs(
 async function buildAllImages(
   repoRoot: string,
   imageTags: Record<ServiceName, string>,
+  log: (msg: string) => void,
 ): Promise<void> {
   const configs = serviceImageConfigs(repoRoot, imageTags);
-  console.log("🔨 Building all images in parallel...");
+  log("🔨 Building all images in parallel...");
   await Promise.all(
     Object.entries(configs).map(async ([name, config]) => {
       await buildImage(config);
-      console.log(`✅ ${name} built`);
+      log(`✅ ${name} built`);
     }),
   );
 }
@@ -319,13 +452,14 @@ async function buildAllImages(
  * service. Each container joins a shared Docker bridge network so they
  * can be restarted independently.
  */
-function serviceDockerRunArgs(opts: {
+export function serviceDockerRunArgs(opts: {
+  extraAssistantEnv?: Record<string, string>;
   gatewayPort: number;
   imageTags: Record<ServiceName, string>;
   instanceName: string;
   res: ReturnType<typeof dockerResourceNames>;
 }): Record<ServiceName, () => string[]> {
-  const { gatewayPort, imageTags, instanceName, res } = opts;
+  const { extraAssistantEnv, gatewayPort, imageTags, instanceName, res } = opts;
   return {
     assistant: () => {
       const args: string[] = [
@@ -349,6 +483,11 @@ function serviceDockerRunArgs(opts: {
           args.push("-e", `${envVar}=${process.env[envVar]}`);
         }
       }
+      if (extraAssistantEnv) {
+        for (const [key, value] of Object.entries(extraAssistantEnv)) {
+          args.push("-e", `${key}=${value}`);
+        }
+      }
       args.push(imageTags.assistant);
       return args;
     },
@@ -371,6 +510,8 @@ function serviceDockerRunArgs(opts: {
       `ASSISTANT_HOST=${res.assistantContainer}`,
       "-e",
       `RUNTIME_HTTP_PORT=${ASSISTANT_INTERNAL_PORT}`,
+      "-e",
+      "RUNTIME_PROXY_ENABLED=true",
       imageTags.gateway,
     ],
     "credential-executor": () => [
@@ -379,7 +520,6 @@ function serviceDockerRunArgs(opts: {
       "-d",
       "--name",
       res.cesContainer,
-      `--network=${res.network}`,
       "-v",
       `${res.socketVolume}:/run/ces-bootstrap`,
       "-v",
@@ -396,28 +536,32 @@ function serviceDockerRunArgs(opts: {
 }
 
 /** The order in which services must be started. */
-const SERVICE_START_ORDER: ServiceName[] = [
+export const SERVICE_START_ORDER: ServiceName[] = [
   "assistant",
   "gateway",
   "credential-executor",
 ];
 
 /** Start all three containers in dependency order. */
-async function startContainers(opts: {
-  gatewayPort: number;
-  imageTags: Record<ServiceName, string>;
-  instanceName: string;
-  res: ReturnType<typeof dockerResourceNames>;
-}): Promise<void> {
+export async function startContainers(
+  opts: {
+    extraAssistantEnv?: Record<string, string>;
+    gatewayPort: number;
+    imageTags: Record<ServiceName, string>;
+    instanceName: string;
+    res: ReturnType<typeof dockerResourceNames>;
+  },
+  log: (msg: string) => void,
+): Promise<void> {
   const runArgs = serviceDockerRunArgs(opts);
   for (const service of SERVICE_START_ORDER) {
-    console.log(`🚀 Starting ${service} container...`);
+    log(`🚀 Starting ${service} container...`);
     await exec("docker", runArgs[service]());
   }
 }
 
 /** Stop and remove all three containers (ignoring errors). */
-async function stopContainers(
+export async function stopContainers(
   res: ReturnType<typeof dockerResourceNames>,
 ): Promise<void> {
   await removeContainer(res.cesContainer);
@@ -586,250 +730,257 @@ export async function hatchDocker(
 ): Promise<void> {
   resetLogFile("hatch.log");
 
-  await ensureDockerInstalled();
-
-  const instanceName = generateInstanceName(species, name);
-  const gatewayPort = DEFAULT_GATEWAY_PORT;
-
-  const imageTags: Record<ServiceName, string> = {
-    assistant: "",
-    "credential-executor": "",
-    gateway: "",
+  let logFd = openLogFile("hatch.log");
+  const log = (msg: string): void => {
+    console.log(msg);
+    writeToLogFile(logFd, `${new Date().toISOString()} ${msg}\n`);
   };
 
-  let repoRoot: string | undefined;
-
-  if (watch) {
-    repoRoot = findRepoRoot();
-    const localTag = `local-${instanceName}`;
-    imageTags.assistant = `vellum-assistant:${localTag}`;
-    imageTags.gateway = `vellum-gateway:${localTag}`;
-    imageTags["credential-executor"] = `vellum-credential-executor:${localTag}`;
-
-    console.log(`🥚 Hatching Docker assistant: ${instanceName}`);
-    console.log(`   Species: ${species}`);
-    console.log(`   Mode: development (watch)`);
-    console.log(`   Repo: ${repoRoot}`);
-    console.log(`   Images (local build):`);
-    console.log(`     assistant:            ${imageTags.assistant}`);
-    console.log(`     gateway:              ${imageTags.gateway}`);
-    console.log(
-      `     credential-executor:  ${imageTags["credential-executor"]}`,
-    );
-    console.log("");
+  try {
+    await ensureDockerInstalled();
 
-    const logFd = openLogFile("hatch.log");
-    try {
-      await buildAllImages(repoRoot, imageTags);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      writeToLogFile(
-        logFd,
-        `[docker-build] ${new Date().toISOString()} ERROR\n${message}\n`,
-      );
-      closeLogFile(logFd);
-      throw err;
-    }
-    closeLogFile(logFd);
-    console.log("✅ Docker images built\n");
-  } else {
-    const version = cliPkg.version;
-    const versionTag = version ? `v${version}` : "latest";
-    imageTags.assistant = `${DOCKERHUB_IMAGES.assistant}:${versionTag}`;
-    imageTags.gateway = `${DOCKERHUB_IMAGES.gateway}:${versionTag}`;
-    imageTags["credential-executor"] =
-      `${DOCKERHUB_IMAGES["credential-executor"]}:${versionTag}`;
-
-    console.log(`🥚 Hatching Docker assistant: ${instanceName}`);
-    console.log(`   Species: ${species}`);
-    console.log(`   Images:`);
-    console.log(`     assistant:            ${imageTags.assistant}`);
-    console.log(`     gateway:              ${imageTags.gateway}`);
-    console.log(
-      `     credential-executor:  ${imageTags["credential-executor"]}`,
-    );
-    console.log("");
+    const instanceName = generateInstanceName(species, name);
+    const gatewayPort = DEFAULT_GATEWAY_PORT;
 
-    const logFd = openLogFile("hatch.log");
-    console.log("📦 Pulling Docker images...");
-    try {
+    const imageTags: Record<ServiceName, string> = {
+      assistant: "",
+      "credential-executor": "",
+      gateway: "",
+    };
+
+    let repoRoot: string | undefined;
+
+    if (watch) {
+      repoRoot = findRepoRoot();
+      const localTag = `local-${instanceName}`;
+      imageTags.assistant = `vellum-assistant:${localTag}`;
+      imageTags.gateway = `vellum-gateway:${localTag}`;
+      imageTags["credential-executor"] =
+        `vellum-credential-executor:${localTag}`;
+
+      log(`🥚 Hatching Docker assistant: ${instanceName}`);
+      log(`   Species: ${species}`);
+      log(`   Mode: development (watch)`);
+      log(`   Repo: ${repoRoot}`);
+      log(`   Images (local build):`);
+      log(`     assistant:            ${imageTags.assistant}`);
+      log(`     gateway:              ${imageTags.gateway}`);
+      log(`     credential-executor:  ${imageTags["credential-executor"]}`);
+      log("");
+
+      await buildAllImages(repoRoot, imageTags, log);
+      log("✅ Docker images built");
+    } else {
+      const version = cliPkg.version;
+      const versionTag = version ? `v${version}` : "latest";
+      imageTags.assistant = `${DOCKERHUB_IMAGES.assistant}:${versionTag}`;
+      imageTags.gateway = `${DOCKERHUB_IMAGES.gateway}:${versionTag}`;
+      imageTags["credential-executor"] =
+        `${DOCKERHUB_IMAGES["credential-executor"]}:${versionTag}`;
+
+      log(`🥚 Hatching Docker assistant: ${instanceName}`);
+      log(`   Species: ${species}`);
+      log(`   Images:`);
+      log(`     assistant:            ${imageTags.assistant}`);
+      log(`     gateway:              ${imageTags.gateway}`);
+      log(`     credential-executor:  ${imageTags["credential-executor"]}`);
+      log("");
+
+      log("📦 Pulling Docker images...");
       await exec("docker", ["pull", imageTags.assistant]);
       await exec("docker", ["pull", imageTags.gateway]);
       await exec("docker", ["pull", imageTags["credential-executor"]]);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      writeToLogFile(
-        logFd,
-        `[docker-pull] ${new Date().toISOString()} ERROR\n${message}\n`,
-      );
-      closeLogFile(logFd);
-      throw err;
+      log("✅ Docker images pulled");
     }
-    closeLogFile(logFd);
-    console.log("✅ Docker images pulled\n");
-  }
 
-  const res = dockerResourceNames(instanceName);
+    const res = dockerResourceNames(instanceName);
 
-  // Create shared network and volumes
-  console.log("📁 Creating shared network and volumes...");
-  await exec("docker", ["network", "create", res.network]);
-  await exec("docker", ["volume", "create", res.dataVolume]);
-  await exec("docker", ["volume", "create", res.socketVolume]);
+    log("📁 Creating network and volumes...");
+    await exec("docker", ["network", "create", res.network]);
+    await exec("docker", ["volume", "create", res.dataVolume]);
+    await exec("docker", ["volume", "create", res.socketVolume]);
 
-  await startContainers({ gatewayPort, imageTags, instanceName, res });
+    await startContainers({ gatewayPort, imageTags, instanceName, res }, log);
 
-  const runtimeUrl = `http://localhost:${gatewayPort}`;
-  const dockerEntry: AssistantEntry = {
-    assistantId: instanceName,
-    runtimeUrl,
-    cloud: "docker",
-    species,
-    hatchedAt: new Date().toISOString(),
-    volume: res.dataVolume,
-  };
-  saveAssistantEntry(dockerEntry);
-  setActiveAssistant(instanceName);
-
-  // The assistant image runs the daemon directly (not via the CLI hatch
-  // command), so we watch for the DaemonServer readiness message instead
-  // of the CLI's "Local assistant hatched!" sentinel.
-  await tailContainerUntilReady({
-    containerName: res.assistantContainer,
-    detached: watch ? false : detached,
-    dockerEntry,
-    instanceName,
-    runtimeUrl,
-    sentinel: "DaemonServer started",
-  });
+    const runtimeUrl = `http://localhost:${gatewayPort}`;
+    const dockerEntry: AssistantEntry = {
+      assistantId: instanceName,
+      runtimeUrl,
+      cloud: "docker",
+      species,
+      hatchedAt: new Date().toISOString(),
+      volume: res.dataVolume,
+    };
+    saveAssistantEntry(dockerEntry);
+    setActiveAssistant(instanceName);
 
-  if (watch && repoRoot) {
-    const stopWatcher = startFileWatcher({
-      gatewayPort,
-      imageTags,
+    const { ready } = await waitForGatewayAndLease({
+      containerName: res.assistantContainer,
+      detached: watch ? false : detached,
       instanceName,
-      repoRoot,
-      res,
+      logFd,
+      runtimeUrl,
     });
 
-    await new Promise<void>((resolve) => {
-      const cleanup = async () => {
-        console.log("\n🛑 Shutting down...");
-        stopWatcher();
-        await stopContainers(res);
-        console.log("✅ Docker instance stopped.");
-        resolve();
-      };
-
-      process.on("SIGINT", () => void cleanup());
-      process.on("SIGTERM", () => void cleanup());
-    });
+    if (!ready && !(watch && repoRoot)) {
+      throw new Error("Timed out waiting for assistant to become ready");
+    }
+
+    if (watch && repoRoot) {
+      saveAssistantEntry({ ...dockerEntry, watcherPid: process.pid });
+
+      const stopWatcher = startFileWatcher({
+        gatewayPort,
+        imageTags,
+        instanceName,
+        repoRoot,
+        res,
+      });
+
+      await new Promise<void>((resolve) => {
+        const cleanup = async () => {
+          log("\n🛑 Shutting down...");
+          stopWatcher();
+          await stopContainers(res);
+          saveAssistantEntry({ ...dockerEntry, watcherPid: undefined });
+          log("✅ Docker instance stopped.");
+          resolve();
+        };
+
+        // SIGINT (Ctrl+C): full cleanup including stopping containers.
+        process.on("SIGINT", () => void cleanup());
+
+        // SIGTERM (from `vellum retire`): exit quickly — the caller
+        // handles container teardown, so we only need to close the
+        // file watchers and let the process terminate.
+        process.on("SIGTERM", () => {
+          stopWatcher();
+          saveAssistantEntry({ ...dockerEntry, watcherPid: undefined });
+          resolve();
+        });
+      });
+    }
+  } finally {
+    closeLogFile(logFd);
+    logFd = "ignore";
   }
 }
 
 /**
  * In detached mode, print instance details and return immediately.
- * Otherwise, tail the given container's logs until the sentinel string
- * appears, then attempt to lease a guardian token and report readiness.
+ * Otherwise, poll the gateway health check until it responds, then
+ * lease a guardian token.
  */
-async function tailContainerUntilReady(opts: {
+async function waitForGatewayAndLease(opts: {
   containerName: string;
   detached: boolean;
-  dockerEntry: AssistantEntry;
   instanceName: string;
+  logFd: number | "ignore";
   runtimeUrl: string;
-  sentinel: string;
-}): Promise<void> {
-  const {
-    containerName,
-    detached,
-    dockerEntry,
-    instanceName,
-    runtimeUrl,
-    sentinel,
-  } = opts;
+}): Promise<{ ready: boolean }> {
+  const { containerName, detached, instanceName, logFd, runtimeUrl } = opts;
+
+  const log = (msg: string): void => {
+    console.log(msg);
+    writeToLogFile(logFd, `${new Date().toISOString()} ${msg}\n`);
+  };
 
   if (detached) {
-    console.log("\n✅ Docker assistant hatched!\n");
-    console.log("Instance details:");
-    console.log(`  Name: ${instanceName}`);
-    console.log(`  Runtime: ${runtimeUrl}`);
-    console.log(`  Container: ${containerName}`);
-    console.log("");
-    console.log(`Stop with: vellum retire ${instanceName}`);
-    return;
+    log("\n✅ Docker assistant hatched!\n");
+    log("Instance details:");
+    log(`  Name: ${instanceName}`);
+    log(`  Runtime: ${runtimeUrl}`);
+    log(`  Container: ${containerName}`);
+    log("");
+    log(`Stop with: vellum retire ${instanceName}`);
+    return { ready: true };
   }
 
-  console.log(`  Container: ${containerName}`);
-  console.log(`  Runtime: ${runtimeUrl}`);
-  console.log("");
+  log(`  Container: ${containerName}`);
+  log(`  Runtime: ${runtimeUrl}`);
+  log("");
+  log("Waiting for assistant to become ready...");
 
-  await new Promise<void>((resolve, reject) => {
-    const child = nodeSpawn("docker", ["logs", "-f", containerName], {
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+  const readyUrl = `${runtimeUrl}/readyz`;
+  const start = Date.now();
+  let ready = false;
 
-    const handleLine = (line: string): void => {
-      if (line.includes(sentinel)) {
-        process.nextTick(async () => {
-          try {
-            const tokenData = await leaseGuardianToken(
-              runtimeUrl,
-              instanceName,
-            );
-            dockerEntry.bearerToken = tokenData.accessToken;
-            saveAssistantEntry(dockerEntry);
-          } catch (err) {
-            console.warn(
-              `\u26a0\ufe0f  Could not lease guardian token: ${err instanceof Error ? err.message : err}`,
-            );
-          }
-
-          console.log("");
-          console.log(`\u2705 Docker containers are up and running!`);
-          console.log(`   Name: ${instanceName}`);
-          console.log(`   Runtime: ${runtimeUrl}`);
-          console.log("");
-          child.kill();
-          resolve();
-        });
+  while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
+    try {
+      const resp = await fetch(readyUrl, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (resp.ok) {
+        ready = true;
+        break;
       }
-    };
+      const body = await resp.text();
+      let detail = "";
+      try {
+        const json = JSON.parse(body);
+        const parts = [json.status];
+        if (json.upstream != null) parts.push(`upstream=${json.upstream}`);
+        detail = ` — ${parts.join(", ")}`;
+      } catch {}
+      log(`Readiness check: ${resp.status}${detail} (retrying...)`);
+    } catch {
+      // Connection refused / timeout — not up yet
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
 
-    const stdoutPrefixer = createLinePrefixer(
-      process.stdout,
-      "docker",
-      handleLine,
-    );
-    const stderrPrefixer = createLinePrefixer(
-      process.stderr,
-      "docker",
-      handleLine,
-    );
+  if (!ready) {
+    log("");
+    log(`   \u26a0\ufe0f  Timed out waiting for assistant to become ready.`);
+    log(`   The container is still running.`);
+    log(`   Check logs with: docker logs -f ${containerName}`);
+    log("");
+    return { ready: false };
+  }
 
-    child.stdout?.on("data", (data: Buffer) => stdoutPrefixer.write(data));
-    child.stderr?.on("data", (data: Buffer) => stderrPrefixer.write(data));
-    child.stdout?.on("end", () => stdoutPrefixer.flush());
-    child.stderr?.on("end", () => stderrPrefixer.flush());
+  const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+  log(`Assistant ready after ${elapsedSec}s`);
 
-    child.on("close", (code) => {
-      if (
-        code === 0 ||
-        code === null ||
-        code === 130 ||
-        code === 137 ||
-        code === 143
-      ) {
-        resolve();
-      } else {
-        reject(new Error(`Docker container exited with code ${code}`));
-      }
-    });
-    child.on("error", reject);
+  // Lease guardian token. The /readyz check confirms both gateway and
+  // assistant are reachable. Retry with backoff in case there is a brief
+  // window where readiness passes but the guardian endpoint is not yet ready.
+  log(`Guardian token lease: starting for ${instanceName} at ${runtimeUrl}`);
+  const leaseStart = Date.now();
+  const leaseDeadline = start + DOCKER_READY_TIMEOUT_MS;
+  let leaseSuccess = false;
+  let lastLeaseError: string | undefined;
 
-    process.on("SIGINT", () => {
-      child.kill();
-      resolve();
-    });
-  });
+  while (Date.now() < leaseDeadline) {
+    try {
+      const tokenData = await leaseGuardianToken(runtimeUrl, instanceName);
+      const leaseElapsed = ((Date.now() - leaseStart) / 1000).toFixed(1);
+      log(
+        `Guardian token lease: success after ${leaseElapsed}s (principalId=${tokenData.guardianPrincipalId}, expiresAt=${tokenData.accessTokenExpiresAt})`,
+      );
+      leaseSuccess = true;
+      break;
+    } catch (err) {
+      lastLeaseError =
+        err instanceof Error ? (err.stack ?? err.message) : String(err);
+      // Log periodically so the user knows we're still trying
+      const elapsed = ((Date.now() - leaseStart) / 1000).toFixed(0);
+      log(
+        `Guardian token lease: attempt failed after ${elapsed}s (${lastLeaseError.split("\n")[0]}), retrying...`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+
+  if (!leaseSuccess) {
+    log(
+      `\u26a0\ufe0f  Guardian token lease: FAILED after ${((Date.now() - leaseStart) / 1000).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
+    );
+  }
+
+  log("");
+  log(`\u2705 Docker containers are up and running!`);
+  log(`   Name: ${instanceName}`);
+  log(`   Runtime: ${runtimeUrl}`);
+  log("");
+  return { ready: true };
 }