@vellumai/cli 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/bun.lock

@@ -5,6 +5,8 @@
     "": {
       "name": "@vellumai/cli",
       "dependencies": {
+        "@vellumai/environments": "file:../packages/environments",
+        "@vellumai/local-mode": "file:../packages/local-mode",
         "chalk": "5.6.2",
         "ink": "6.8.0",
         "nanoid": "5.1.7",
@@ -135,6 +137,10 @@
 
     "@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.58.0", "", { "dependencies": { "@typescript-eslint/types": "8.58.0", "eslint-visitor-keys": "^5.0.0" } }, "sha512-XJ9UD9+bbDo4a4epraTwG3TsNPeiB9aShrUneAVXy8q4LuwowN+qu89/6ByLMINqvIMeI9H9hOHQtg/ijrYXzQ=="],
 
+    "@vellumai/environments": ["@vellumai/environments@file:../packages/environments", { "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
+    "@vellumai/local-mode": ["@vellumai/local-mode@file:../packages/local-mode", { "dependencies": { "@vellumai/environments": "file:../environments" }, "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
@@ -397,6 +403,8 @@
 
     "@typescript-eslint/eslint-plugin/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
+    "@vellumai/local-mode/@vellumai/environments": ["@vellumai/environments@file:../packages/environments", {}],
+
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "micromatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],

package/knip.json

@@ -8,5 +8,9 @@
     "src/lib/cli-error.ts"
   ],
   "project": ["src/**/*.ts", "src/**/*.tsx"],
-  "ignoreDependencies": ["@vellumai/web"]
+  "ignoreDependencies": [
+    "@vellumai/environments",
+    "@vellumai/local-mode",
+    "@vellumai/web"
+  ]
 }

package/node_modules/@vellumai/environments/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/environments",
+      "devDependencies": {
+        "@types/bun": "1.3.11",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+  }
+}

package/node_modules/@vellumai/environments/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/environments",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/environments/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Package boundary tests for @vellumai/environments.
+ *
+ * This package is the lowest layer of the shared-packages hierarchy: pure
+ * environment types and constants with no runtime dependencies. It must
+ * stay a leaf so any consumer (CLI, assistant, local-mode host) can depend
+ * on it without dragging in a dependency tree.
+ *
+ * Enforces that the package:
+ * 1. Imports only node builtins and its own relative modules — no `@vellumai/*`
+ *    packages and no third-party runtime imports.
+ * 2. Declares no runtime `dependencies` (devDependencies only).
+ * 3. Is marked `private`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (
+      entry.endsWith(".ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".d.ts")
+    ) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Matches the module specifier of any `import ... from "<spec>"` /
+ * `export ... from "<spec>"` / `require("<spec>")` statement.
+ */
+const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+
+/** A bare specifier is anything that is not a relative or node-builtin import. */
+function isForbiddenSpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/")) return false;
+  if (spec.startsWith("node:")) return false;
+  return true;
+}
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("imports only node builtins and relative modules", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const lines = readFileSync(file, "utf-8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const match of lines[i]!.matchAll(IMPORT_SPEC)) {
+          const spec = match[1]!;
+          if (isForbiddenSpecifier(spec)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${spec}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in @vellumai/environments:\n` +
+          violations.map((v) => `  - ${v}`).join("\n") +
+          "\n\n@vellumai/environments is a pure types/constants leaf and must\n" +
+          "import only node builtins and its own relative modules.",
+      );
+    }
+  });
+
+  test("package.json declares it as private with no runtime dependencies", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies ?? {}).toEqual({});
+  });
+});

package/node_modules/@vellumai/environments/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @vellumai/environments — the single source of truth for Vellum's known
+ * deployment environments (names, platform/web URLs, per-service port
+ * blocks). Consumed by the CLI, the assistant daemon, and the local-mode
+ * host library so the environment list is defined exactly once on the TS
+ * side. The Swift client mirrors the same set in `VellumEnvironment.swift`.
+ *
+ * Intentionally free of runtime dependencies: pure types and constants only.
+ */
+export * from "./types.js";
+export * from "./seeds.js";

package/{src/lib/environments → node_modules/@vellumai/environments/src}/seeds.ts

@@ -25,15 +25,11 @@ function portBlock(base: number): PortMap {
 }
 
 /**
- * Built-in environment definitions. Mirrors Swift's
- * `clients/macos/vellum-assistant/App/VellumEnvironment.swift` enum and is
- * the TS-side source of truth for the set of known environment names.
- * One other TS site duplicates the name list:
- *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
- * Drift between these two sites is caught at test time by
- * `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
- * list into a `packages/environments` package so both sites import
- * from one place.
+ * Built-in environment definitions and the TS-side source of truth for the
+ * set of known environment names. The Swift client mirrors this list in
+ * `clients/macos/vellum-assistant/App/VellumEnvironment.swift`; since Swift
+ * can't import TypeScript, drift between the two is caught at test time by
+ * `cli/src/__tests__/env-drift.test.ts`.
  *
  * Custom environments via a user config file are a future phase — see the
  * "Coexisting environments" design doc. Until then, a call site that needs a

package/node_modules/@vellumai/environments/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/local-mode/bun.lock

@@ -0,0 +1,29 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/local-mode",
+      "dependencies": {
+        "@vellumai/environments": "file:../environments",
+      },
+      "devDependencies": {
+        "@types/bun": "1.3.11",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
+
+    "@vellumai/environments": ["@vellumai/environments@file:../environments", { "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+  }
+}

package/node_modules/@vellumai/local-mode/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@vellumai/local-mode",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contract": "./src/lockfile-contract.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "@vellumai/environments": "file:../environments"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/local-mode/src/__tests__/environment.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  defaultEnvironmentFilePath,
+  readDefaultEnvironment,
+  resolveEnvironmentName,
+} from "../environment";
+import { resolveLockfilePaths, resolveConfigDir } from "../config";
+
+let configHome: string;
+
+/** Write the persisted default-environment file under the temp config home. */
+function persistDefault(name: string): void {
+  const file = path.join(configHome, "vellum", "environment");
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, name + "\n", "utf-8");
+}
+
+beforeEach(() => {
+  configHome = mkdtempSync(path.join(os.tmpdir(), "vellum-env-"));
+});
+
+afterEach(() => {
+  rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("defaultEnvironmentFilePath", () => {
+  test("honors XDG_CONFIG_HOME", () => {
+    expect(defaultEnvironmentFilePath({ XDG_CONFIG_HOME: configHome })).toBe(
+      path.join(configHome, "vellum", "environment"),
+    );
+  });
+
+  test("falls back to ~/.config", () => {
+    expect(defaultEnvironmentFilePath({})).toBe(
+      path.join(os.homedir(), ".config", "vellum", "environment"),
+    );
+  });
+});
+
+describe("readDefaultEnvironment", () => {
+  test("returns undefined when no file exists", () => {
+    expect(
+      readDefaultEnvironment({ XDG_CONFIG_HOME: configHome }),
+    ).toBeUndefined();
+  });
+
+  test("returns the trimmed persisted name", () => {
+    persistDefault("dev");
+    expect(readDefaultEnvironment({ XDG_CONFIG_HOME: configHome })).toBe("dev");
+  });
+
+  test("treats an empty file as no default", () => {
+    const file = path.join(configHome, "vellum", "environment");
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, "  \n", "utf-8");
+    expect(
+      readDefaultEnvironment({ XDG_CONFIG_HOME: configHome }),
+    ).toBeUndefined();
+  });
+});
+
+describe("resolveEnvironmentName", () => {
+  test("prefers VELLUM_ENVIRONMENT over the persisted default", () => {
+    persistDefault("dev");
+    expect(
+      resolveEnvironmentName({
+        XDG_CONFIG_HOME: configHome,
+        VELLUM_ENVIRONMENT: "staging",
+      }),
+    ).toBe("staging");
+  });
+
+  test("falls back to the persisted default when the env var is unset", () => {
+    persistDefault("dev");
+    expect(resolveEnvironmentName({ XDG_CONFIG_HOME: configHome })).toBe("dev");
+  });
+
+  test("falls back to production when neither is set", () => {
+    expect(resolveEnvironmentName({ XDG_CONFIG_HOME: configHome })).toBe(
+      "production",
+    );
+  });
+});
+
+describe("path resolvers honor the persisted default", () => {
+  test("resolveLockfilePaths points at the persisted environment", () => {
+    persistDefault("dev");
+    const env = { XDG_CONFIG_HOME: configHome };
+    expect(resolveLockfilePaths(env)).toEqual([
+      path.join(configHome, "vellum-dev", "lockfile.json"),
+    ]);
+  });
+
+  test("resolveConfigDir points at the persisted environment", () => {
+    persistDefault("dev");
+    expect(resolveConfigDir({ XDG_CONFIG_HOME: configHome })).toBe(
+      path.join(configHome, "vellum-dev"),
+    );
+  });
+
+  test("VELLUM_ENVIRONMENT still wins for path resolution", () => {
+    persistDefault("dev");
+    const env = {
+      XDG_CONFIG_HOME: configHome,
+      VELLUM_ENVIRONMENT: "production",
+    };
+    expect(resolveLockfilePaths(env)).toEqual([
+      path.join(os.homedir(), ".vellum.lock.json"),
+      path.join(os.homedir(), ".vellum.lockfile.json"),
+    ]);
+  });
+});

package/node_modules/@vellumai/local-mode/src/__tests__/gateway-proxy.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+
+import { resolveGatewayProxyTarget } from "../gateway-proxy";
+
+const allow =
+  (...ports: number[]) =>
+  () =>
+    new Set<number>(ports);
+
+describe("resolveGatewayProxyTarget", () => {
+  test("passes non-gateway pathnames through untouched", () => {
+    expect(resolveGatewayProxyTarget("/index.html", allow(8080))).toEqual({
+      kind: "pass",
+    });
+    expect(resolveGatewayProxyTarget("/assistant/assets/app.js", allow())).toEqual({
+      kind: "pass",
+    });
+  });
+
+  test("forwards an allowlisted port to its loopback target", () => {
+    expect(
+      resolveGatewayProxyTarget("/__gateway/8080/v1/assistants", allow(8080)),
+    ).toEqual({
+      kind: "forward",
+      target: { port: 8080, path: "/v1/assistants" },
+    });
+  });
+
+  test("accepts the renderer's `/assistant` mount prefix", () => {
+    expect(
+      resolveGatewayProxyTarget("/assistant/__gateway/8080/auth/token", allow(8080)),
+    ).toEqual({
+      kind: "forward",
+      target: { port: 8080, path: "/auth/token" },
+    });
+  });
+
+  test("defaults a portless tail to the gateway root", () => {
+    expect(resolveGatewayProxyTarget("/__gateway/8080", allow(8080))).toEqual({
+      kind: "forward",
+      target: { port: 8080, path: "/" },
+    });
+  });
+
+  test("rejects ports outside the 1024–65535 range as invalid", () => {
+    expect(resolveGatewayProxyTarget("/__gateway/80/v1", allow(80))).toEqual({
+      kind: "invalid-port",
+    });
+    expect(resolveGatewayProxyTarget("/__gateway/70000/v1", allow(70000))).toEqual({
+      kind: "invalid-port",
+    });
+  });
+
+  test("forbids a well-formed port that isn't registered in the lockfile", () => {
+    expect(
+      resolveGatewayProxyTarget("/__gateway/9999/v1", allow(8080)),
+    ).toEqual({ kind: "forbidden-port", port: 9999 });
+  });
+
+  test("forbids every gateway port when the allowlist is empty", () => {
+    expect(resolveGatewayProxyTarget("/__gateway/8080/v1", allow())).toEqual({
+      kind: "forbidden-port",
+      port: 8080,
+    });
+  });
+
+  test("never reads the allowlist for non-gateway or invalid-port paths", () => {
+    let reads = 0;
+    const counting = () => {
+      reads += 1;
+      return new Set<number>([8080]);
+    };
+    resolveGatewayProxyTarget("/index.html", counting);
+    resolveGatewayProxyTarget("/__gateway/80/v1", counting);
+    expect(reads).toBe(0);
+    resolveGatewayProxyTarget("/__gateway/8080/v1", counting);
+    expect(reads).toBe(1);
+  });
+});

package/node_modules/@vellumai/local-mode/src/__tests__/hatch.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+
+import type { CliInvocation } from "../util";
+
+class FakeChild extends EventEmitter {
+  stdout = new EventEmitter();
+  stderr = new EventEmitter();
+  kill = mock(() => true);
+}
+
+let lastChild: FakeChild;
+const spawnArgs: Array<[string, string[]]> = [];
+const spawnMock = mock((command: string, args: string[]) => {
+  spawnArgs.push([command, args]);
+  lastChild = new FakeChild();
+  return lastChild;
+});
+
+mock.module("node:child_process", () => ({ spawn: spawnMock }));
+
+let runHatch: typeof import("../hatch").runHatch;
+
+beforeAll(async () => {
+  ({ runHatch } = await import("../hatch"));
+});
+
+afterEach(() => {
+  spawnArgs.length = 0;
+  spawnMock.mockClear();
+});
+
+const invocation: CliInvocation = { command: "bun", baseArgs: ["run", "cli"] };
+
+describe("runHatch", () => {
+  test("spawns the CLI and parses the assistant id from stdout", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from("Hatching local assistant: asst-42\n"),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true, assistantId: "asst-42" });
+    expect(spawnArgs[0]).toEqual(["bun", ["run", "cli", "hatch", "vellum"]]);
+  });
+
+  test("parses the assistant id from a Docker hatch banner", async () => {
+    const pending = runHatch(invocation, "vellum", { remote: "docker" });
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from("🥚 Hatching Docker assistant: asst-docker\n"),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true, assistantId: "asst-docker" });
+    expect(spawnArgs[0]).toEqual([
+      "bun",
+      ["run", "cli", "hatch", "vellum", "--remote", "docker"],
+    ]);
+  });
+
+  test("a non-zero exit resolves to a failure carrying the CLI's output", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.stderr.emit("data", Buffer.from("daemon already running"));
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      status: 500,
+      error: "daemon already running",
+    });
+  });
+
+  test("a non-zero exit with no output carries a descriptive fallback error", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.emit("close", 1);
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("exited with code 1");
+    }
+  });
+
+  test("a zero exit whose stdout has no parseable id fails instead of returning a blank id", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.stdout.emit("data", Buffer.from("done, but no id line\n"));
+    lastChild.emit("close", 0);
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("no assistant id");
+    }
+  });
+
+  test("a spawn failure resolves to a failure rather than rejecting", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.emit("error", new Error("ENOENT"));
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("ENOENT");
+    }
+  });
+});