@vellumai/cli 0.11.7-staging.2 → 0.11.8-staging.1

package/AGENTS.md

@@ -65,7 +65,7 @@ The CLI must **never** read from or write to the `.vellum/` directory (e.g. `~/.
 
 For example, the signing key used for JWT auth between the daemon and gateway is persisted in the lockfile (`resources.signingKey`) so that client actor tokens survive daemon/gateway restarts. On first start (or when the key is missing), the CLI generates a new key via `generateLocalSigningKey()` in `lib/local.ts`, saves it to the lockfile entry, and passes it to both `startLocalDaemon` and `startGateway` as the `ACTOR_TOKEN_SIGNING_KEY` env var. The CLI does **not** read or write to the `.vellum/` directory for signing keys — it uses the lockfile instead.
 
-**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Electron main process, the host-mode assistant, and the CLI (see `clients/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
+**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Electron main process, the host-mode assistant, and the CLI (see `packages/electron-desktop/src/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
 
 ## Process liveness
 

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

@@ -7,7 +7,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./seeds": "./src/seeds.ts",
-    "./shell": "./src/shell.ts"
+    "./shell": "./src/shell.ts",
+    "./test-path-guard": "./src/test-path-guard.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertTestPathIsEphemeral,
+  canonicalizePathThroughExistingParent,
+  isBunTestProcess,
+} from "../test-path-guard.js";
+
+const OPTIONS = {
+  allowEnvVar: "TEST_PATH_GUARD_ALLOW",
+  runHint: "Run tests from the package root.",
+};
+
+describe("isBunTestProcess", () => {
+  test("detects this bun test run", () => {
+    expect(isBunTestProcess()).toBe(true);
+  });
+});
+
+describe("canonicalizePathThroughExistingParent", () => {
+  test("resolves symlinks on the deepest existing ancestor", () => {
+    const root = mkdtempSync(join(tmpdir(), "test-path-guard-"));
+    try {
+      const target = join(root, "target");
+      mkdirSync(target);
+      const link = join(root, "link");
+      symlinkSync(target, link, "dir");
+      expect(
+        canonicalizePathThroughExistingParent(join(link, "missing", "leaf")),
+      ).toBe(
+        join(canonicalizePathThroughExistingParent(target), "missing", "leaf"),
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("returns the input path when no ancestor exists", () => {
+    expect(canonicalizePathThroughExistingParent("/nonexistent-root-x/y")).toBe(
+      "/nonexistent-root-x/y",
+    );
+  });
+});
+
+describe("assertTestPathIsEphemeral", () => {
+  test("allows paths under tmpdir, existing or not", () => {
+    expect(() =>
+      assertTestPathIsEphemeral(join(tmpdir(), "guard-missing", "x"), OPTIONS),
+    ).not.toThrow();
+  });
+
+  test("refuses paths outside tmpdir, naming the escape hatch and hint", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const dir = join(homedir(), "test-path-guard-live");
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use[\s\S]*package root[\s\S]*TEST_PATH_GUARD_ALLOW/,
+    );
+  });
+
+  test("refuses a tmpdir symlink that resolves outside tmpdir", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const link = join(tmpdir(), `test-path-guard-escape-${process.pid}`);
+    rmSync(link, { force: true });
+    symlinkSync(homedir(), link);
+    try {
+      expect(() => assertTestPathIsEphemeral(link, OPTIONS)).toThrow(
+        /Refusing to use/,
+      );
+    } finally {
+      rmSync(link, { force: true });
+    }
+  });
+
+  test("the allow env var bypasses the guard, per call", () => {
+    const dir = join(homedir(), "test-path-guard-optout");
+    process.env[OPTIONS.allowEnvVar] = "1";
+    try {
+      expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).not.toThrow();
+    } finally {
+      delete process.env[OPTIONS.allowEnvVar];
+    }
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use/,
+    );
+  });
+});

package/node_modules/@vellumai/environments/src/test-path-guard.ts

@@ -0,0 +1,113 @@
+/**
+ * Live-path guard for test processes, shared by every service that resolves
+ * install-layout paths (the assistant daemon's workspace/root, the gateway's
+ * workspace and security dirs).
+ *
+ * A test process must never resolve one of those paths to a real, non-temp
+ * directory: production code exercised by a test would then read and
+ * destructively write live state. The tmpdir redirection normally comes from
+ * each package's bunfig.toml test preload, but bun only loads bunfig from
+ * the cwd, so `bun test` run from any other directory skips the preload and
+ * inherits the ambient env (or a ~/.vellum fallback). The containment
+ * assertion therefore lives in production code, where it fires no matter how
+ * the test process was launched.
+ *
+ * assistant/src/__tests__/assert-not-live-db.ts keeps its own containment
+ * check: test machinery must not import production dependencies.
+ */
+
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+
+/**
+ * Resolve symlinks in the deepest existing ancestor of `path`, then
+ * re-append the not-yet-created tail. This keeps containment checks honest
+ * both for paths under a symlinked temp root (macOS /var/folders) and for
+ * symlinks that point outside it, whether or not the leaf exists yet.
+ */
+export function canonicalizePathThroughExistingParent(path: string): string {
+  const resolvedPath = resolve(path);
+  const pendingSegments: string[] = [];
+  let currentPath = resolvedPath;
+
+  while (true) {
+    try {
+      return resolve(realpathSync(currentPath), ...pendingSegments.reverse());
+    } catch {
+      const parentPath = dirname(currentPath);
+      if (parentPath === currentPath) {
+        return resolvedPath;
+      }
+      pendingSegments.push(basename(currentPath));
+      currentPath = parentPath;
+    }
+  }
+}
+
+/** Lazily computed: is this process a `bun test` run? */
+let isTestProcess: boolean | undefined;
+
+/**
+ * True when this process is a `bun test` run. Computed once and cached for
+ * the process lifetime, so a runtime flip of NODE_ENV or BUN_TEST does not
+ * change the answer. Test-mode behavior toggles that must observe such
+ * flips read the env directly instead of calling this.
+ */
+export function isBunTestProcess(): boolean {
+  isTestProcess ??=
+    process.env.NODE_ENV === "test" ||
+    process.env.BUN_TEST === "1" ||
+    // `bun test` sets NODE_ENV=test only when unset; Bun.main being the test
+    // file itself is the backstop signal that survives a preset NODE_ENV.
+    (typeof Bun !== "undefined" &&
+      /\.(test|spec)\.[cm]?[jt]sx?$/.test(Bun.main));
+  return isTestProcess;
+}
+
+export interface EphemeralTestPathOptions {
+  /**
+   * Escape hatch for the rare intentional run against real state: setting
+   * this env var to "1" bypasses the guard. Callers reuse the variable their
+   * DB-open guard already honors. Deliberately not forwarded into
+   * agent-spawned shells (assistant/src/tools/terminal/safe-env.ts), so a
+   * daemon-level opt-out cannot disarm the guard for tests run from there.
+   */
+  allowEnvVar: string;
+  /** Package-specific line telling the reader where to run tests from. */
+  runHint: string;
+}
+
+/**
+ * Throws when called in a bun-test process and `dir` does not resolve under
+ * `os.tmpdir()`. Inert outside test processes. Canonicalizes on every call
+ * (no memo): a previously validated path could later be replaced by a
+ * symlink, and the guard only runs in test processes anyway.
+ */
+export function assertTestPathIsEphemeral(
+  dir: string,
+  options: EphemeralTestPathOptions,
+): void {
+  if (!isBunTestProcess()) {
+    return;
+  }
+  if (process.env[options.allowEnvVar] === "1") {
+    return;
+  }
+  const tmpRoot = canonicalizePathThroughExistingParent(tmpdir());
+  const resolved = canonicalizePathThroughExistingParent(dir);
+  if (resolved !== tmpRoot && !resolved.startsWith(tmpRoot + sep)) {
+    throw new Error(
+      [
+        `Refusing to use ${dir} (resolves to ${resolved}) in a test process: it is not under the temp directory (${tmpRoot}).`,
+        "",
+        "Tests must only touch ephemeral state; a real directory would expose",
+        "live install state to destructive test fixtures. This usually means",
+        "`bun test` ran from a cwd without the package's bunfig.toml, so the",
+        "test preload that redirects paths to a tmpdir never loaded.",
+        options.runHint,
+        `Set ${options.allowEnvVar}=1 to bypass deliberately.`,
+      ].join("\n"),
+    );
+  }
+}

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

@@ -7,7 +7,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./seeds": "./src/seeds.ts",
-    "./shell": "./src/shell.ts"
+    "./shell": "./src/shell.ts",
+    "./test-path-guard": "./src/test-path-guard.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/environments/src/__tests__/test-path-guard.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertTestPathIsEphemeral,
+  canonicalizePathThroughExistingParent,
+  isBunTestProcess,
+} from "../test-path-guard.js";
+
+const OPTIONS = {
+  allowEnvVar: "TEST_PATH_GUARD_ALLOW",
+  runHint: "Run tests from the package root.",
+};
+
+describe("isBunTestProcess", () => {
+  test("detects this bun test run", () => {
+    expect(isBunTestProcess()).toBe(true);
+  });
+});
+
+describe("canonicalizePathThroughExistingParent", () => {
+  test("resolves symlinks on the deepest existing ancestor", () => {
+    const root = mkdtempSync(join(tmpdir(), "test-path-guard-"));
+    try {
+      const target = join(root, "target");
+      mkdirSync(target);
+      const link = join(root, "link");
+      symlinkSync(target, link, "dir");
+      expect(
+        canonicalizePathThroughExistingParent(join(link, "missing", "leaf")),
+      ).toBe(
+        join(canonicalizePathThroughExistingParent(target), "missing", "leaf"),
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("returns the input path when no ancestor exists", () => {
+    expect(canonicalizePathThroughExistingParent("/nonexistent-root-x/y")).toBe(
+      "/nonexistent-root-x/y",
+    );
+  });
+});
+
+describe("assertTestPathIsEphemeral", () => {
+  test("allows paths under tmpdir, existing or not", () => {
+    expect(() =>
+      assertTestPathIsEphemeral(join(tmpdir(), "guard-missing", "x"), OPTIONS),
+    ).not.toThrow();
+  });
+
+  test("refuses paths outside tmpdir, naming the escape hatch and hint", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const dir = join(homedir(), "test-path-guard-live");
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use[\s\S]*package root[\s\S]*TEST_PATH_GUARD_ALLOW/,
+    );
+  });
+
+  test("refuses a tmpdir symlink that resolves outside tmpdir", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const link = join(tmpdir(), `test-path-guard-escape-${process.pid}`);
+    rmSync(link, { force: true });
+    symlinkSync(homedir(), link);
+    try {
+      expect(() => assertTestPathIsEphemeral(link, OPTIONS)).toThrow(
+        /Refusing to use/,
+      );
+    } finally {
+      rmSync(link, { force: true });
+    }
+  });
+
+  test("the allow env var bypasses the guard, per call", () => {
+    const dir = join(homedir(), "test-path-guard-optout");
+    process.env[OPTIONS.allowEnvVar] = "1";
+    try {
+      expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).not.toThrow();
+    } finally {
+      delete process.env[OPTIONS.allowEnvVar];
+    }
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use/,
+    );
+  });
+});

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/environments/src/test-path-guard.ts

@@ -0,0 +1,113 @@
+/**
+ * Live-path guard for test processes, shared by every service that resolves
+ * install-layout paths (the assistant daemon's workspace/root, the gateway's
+ * workspace and security dirs).
+ *
+ * A test process must never resolve one of those paths to a real, non-temp
+ * directory: production code exercised by a test would then read and
+ * destructively write live state. The tmpdir redirection normally comes from
+ * each package's bunfig.toml test preload, but bun only loads bunfig from
+ * the cwd, so `bun test` run from any other directory skips the preload and
+ * inherits the ambient env (or a ~/.vellum fallback). The containment
+ * assertion therefore lives in production code, where it fires no matter how
+ * the test process was launched.
+ *
+ * assistant/src/__tests__/assert-not-live-db.ts keeps its own containment
+ * check: test machinery must not import production dependencies.
+ */
+
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+
+/**
+ * Resolve symlinks in the deepest existing ancestor of `path`, then
+ * re-append the not-yet-created tail. This keeps containment checks honest
+ * both for paths under a symlinked temp root (macOS /var/folders) and for
+ * symlinks that point outside it, whether or not the leaf exists yet.
+ */
+export function canonicalizePathThroughExistingParent(path: string): string {
+  const resolvedPath = resolve(path);
+  const pendingSegments: string[] = [];
+  let currentPath = resolvedPath;
+
+  while (true) {
+    try {
+      return resolve(realpathSync(currentPath), ...pendingSegments.reverse());
+    } catch {
+      const parentPath = dirname(currentPath);
+      if (parentPath === currentPath) {
+        return resolvedPath;
+      }
+      pendingSegments.push(basename(currentPath));
+      currentPath = parentPath;
+    }
+  }
+}
+
+/** Lazily computed: is this process a `bun test` run? */
+let isTestProcess: boolean | undefined;
+
+/**
+ * True when this process is a `bun test` run. Computed once and cached for
+ * the process lifetime, so a runtime flip of NODE_ENV or BUN_TEST does not
+ * change the answer. Test-mode behavior toggles that must observe such
+ * flips read the env directly instead of calling this.
+ */
+export function isBunTestProcess(): boolean {
+  isTestProcess ??=
+    process.env.NODE_ENV === "test" ||
+    process.env.BUN_TEST === "1" ||
+    // `bun test` sets NODE_ENV=test only when unset; Bun.main being the test
+    // file itself is the backstop signal that survives a preset NODE_ENV.
+    (typeof Bun !== "undefined" &&
+      /\.(test|spec)\.[cm]?[jt]sx?$/.test(Bun.main));
+  return isTestProcess;
+}
+
+export interface EphemeralTestPathOptions {
+  /**
+   * Escape hatch for the rare intentional run against real state: setting
+   * this env var to "1" bypasses the guard. Callers reuse the variable their
+   * DB-open guard already honors. Deliberately not forwarded into
+   * agent-spawned shells (assistant/src/tools/terminal/safe-env.ts), so a
+   * daemon-level opt-out cannot disarm the guard for tests run from there.
+   */
+  allowEnvVar: string;
+  /** Package-specific line telling the reader where to run tests from. */
+  runHint: string;
+}
+
+/**
+ * Throws when called in a bun-test process and `dir` does not resolve under
+ * `os.tmpdir()`. Inert outside test processes. Canonicalizes on every call
+ * (no memo): a previously validated path could later be replaced by a
+ * symlink, and the guard only runs in test processes anyway.
+ */
+export function assertTestPathIsEphemeral(
+  dir: string,
+  options: EphemeralTestPathOptions,
+): void {
+  if (!isBunTestProcess()) {
+    return;
+  }
+  if (process.env[options.allowEnvVar] === "1") {
+    return;
+  }
+  const tmpRoot = canonicalizePathThroughExistingParent(tmpdir());
+  const resolved = canonicalizePathThroughExistingParent(dir);
+  if (resolved !== tmpRoot && !resolved.startsWith(tmpRoot + sep)) {
+    throw new Error(
+      [
+        `Refusing to use ${dir} (resolves to ${resolved}) in a test process: it is not under the temp directory (${tmpRoot}).`,
+        "",
+        "Tests must only touch ephemeral state; a real directory would expose",
+        "live install state to destructive test fixtures. This usually means",
+        "`bun test` ran from a cwd without the package's bunfig.toml, so the",
+        "test preload that redirects paths to a tmpdir never loaded.",
+        options.runHint,
+        `Set ${options.allowEnvVar}=1 to bypass deliberately.`,
+      ].join("\n"),
+    );
+  }
+}

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

@@ -11,6 +11,7 @@
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
     "./ingress": "./src/ingress.ts",
+    "./no-response": "./src/no-response.ts",
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
     "./twilio-ingress": "./src/twilio-ingress.ts",
     "./trust-rules": "./src/trust-rules.ts",

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -66,6 +66,13 @@ export function isChannelId(value: unknown): value is ChannelId {
  * That irregularity is why this is stated rather than derived from the key,
  * and it is stated here because this file already owns what a channel is.
  *
+ * Both senses can hold a user token, which is the sharpest edge. The `slack`
+ * integration's persisted token *is* the installer's user token, held on its
+ * OAuth connection. `slack_channel` holds an optional `user_token` in the
+ * credential store, beside its bot and app tokens. Same words, different
+ * homes, and only the second is a credential-store key: a pasted token is
+ * always the channel's, because the integration's never leaves the exchange.
+ *
  * Deliberately only the key. What fields each credential requires is declared
  * once already, per service, in the gateway's credential specs; restating it
  * here would be a second copy of a different fact.

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/index.ts

@@ -27,6 +27,7 @@ export * from "./handles.js";
 export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
+export * from "./no-response.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";
 export * from "./url-normalization.js";

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/no-response.ts

@@ -0,0 +1,84 @@
+/**
+ * The `<no_response/>` sentinel: the cross-service convention for a turn
+ * that deliberately produces no user-visible reply.
+ *
+ * The model emits it, the daemon stamps and strips it, channel delivery
+ * suppresses it, and clients hold live-streamed prefixes of it back from
+ * display. One definition here keeps every consumer's parsing identical;
+ * a hand-rolled copy in any one of them is how the case-sensitivity of a
+ * regex drifts.
+ */
+
+/** Matches a message whose entire content is the sentinel. */
+const NO_RESPONSE_ONLY_RE = /^\s*<no_response\s*\/?>\s*$/i;
+
+/**
+ * Whether `text` is nothing but the sentinel: the whole reply is a
+ * deliberate non-response, as opposed to real content with an inline
+ * sentinel mixed in.
+ */
+export function isNoResponseOnlyText(text: string): boolean {
+  return NO_RESPONSE_ONLY_RE.test(text);
+}
+
+/** Matches every sentinel occurrence for stripping it out of mixed content. */
+export const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
+
+/**
+ * Detection variant without the `g` flag: a `g`-flagged regex is stateful
+ * under `.test()` (it resumes from `lastIndex`), so reusing
+ * {@link NO_RESPONSE_INLINE_RE} for detection would alternate between
+ * matches and misses across calls.
+ */
+const NO_RESPONSE_MARKER_RE = new RegExp(NO_RESPONSE_INLINE_RE.source, "i");
+
+/** Whether `text` contains the sentinel anywhere. */
+export function containsNoResponseMarker(text: string): boolean {
+  return NO_RESPONSE_MARKER_RE.test(text);
+}
+
+/** Removes every sentinel occurrence, trimming the leftover whitespace. */
+export function stripNoResponseMarkers(text: string): string {
+  return text.replace(NO_RESPONSE_INLINE_RE, "").trim();
+}
+
+const NO_RESPONSE_SENTINEL_FORMS = [
+  "<no_response/>",
+  "<no_response />",
+  "<no_response>",
+] as const;
+
+/**
+ * Whether `text` could still grow into the sentinel, i.e. it is a leading
+ * substring of one of its forms. Holding on these keeps a slowly-streamed
+ * `<no_response/>` from surfacing as visible partial content.
+ */
+export function isPotentialNoResponsePrefix(text: string): boolean {
+  const lower = text.trim().toLowerCase();
+  if (lower.length === 0) {
+    return false;
+  }
+  return NO_RESPONSE_SENTINEL_FORMS.some((sentinel) =>
+    sentinel.startsWith(lower),
+  );
+}
+
+/**
+ * Whether `text` carries user-visible content worth acting on now. Returns
+ * `false` for empty text, the standalone sentinel, and any prefix that could
+ * still complete into one; returns `true` once real content remains after
+ * stripping inline sentinels.
+ */
+export function hasDeliverableAssistantText(text: string): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return false;
+  }
+  if (NO_RESPONSE_ONLY_RE.test(trimmed)) {
+    return false;
+  }
+  if (isPotentialNoResponsePrefix(trimmed)) {
+    return false;
+  }
+  return stripNoResponseMarkers(trimmed).length > 0;
+}

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

@@ -1,8 +1,19 @@
 import { spawn } from "node:child_process";
 
+import {
+  DAEMON_READINESS_WINDOW_MS,
+  DAEMON_STOP_TIMEOUT_MS,
+  HOST_WRAPPER_LONG_HEADROOM_MS,
+} from "./lifecycle-budgets";
 import type { CliInvocation } from "./util";
 
-const HATCH_TIMEOUT_MS = 120_000;
+// A hatch whose daemon comes up but never becomes ready spends the readiness
+// window first, then rolls back through the full daemon stop, so the wrapper
+// has to cover both plus the gateway and CES cleanup that follows.
+const HATCH_TIMEOUT_MS =
+  DAEMON_READINESS_WINDOW_MS +
+  DAEMON_STOP_TIMEOUT_MS +
+  HOST_WRAPPER_LONG_HEADROOM_MS;
 // Docker hatches pull images and wait up to 5 min for container readiness.
 const DOCKER_HATCH_TIMEOUT_MS = 10 * 60 * 1000;
 
@@ -85,7 +96,11 @@ export function runHatch(
     });
 
     child.on("error", (err) => {
-      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+      finish({
+        ok: false,
+        status: 500,
+        error: `Failed to spawn CLI: ${err.message}`,
+      });
     });
   });
 }

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -17,6 +17,11 @@ export {
   resolveDevCliInvocation,
 } from "./util";
 export type { CliInvocation } from "./util";
+export {
+  DAEMON_STOP_TIMEOUT_MS,
+  HOST_WRAPPER_HEADROOM_MS,
+  HOST_WRAPPER_LONG_HEADROOM_MS,
+} from "./lifecycle-budgets";
 export {
   resolveLocalConfigFromEnv,
   resolveLockfilePaths,

package/node_modules/@vellumai/local-mode/src/lifecycle-budgets.ts

@@ -0,0 +1,47 @@
+/**
+ * Timeouts shared between the CLI's lifecycle commands and the host wrappers
+ * that spawn them.
+ *
+ * A host wrapper kills the CLI subprocess when its own timeout expires, so
+ * every wrapper timeout must sit above the budget of the command it runs.
+ * Otherwise a slow-but-succeeding command is killed partway and misreported as
+ * a failure, and the SIGKILL ceiling it was waiting on is never reached.
+ * Deriving the wrapper timeouts from the same constant keeps the two from
+ * drifting apart.
+ */
+
+/**
+ * SIGKILL ceiling for stopping the assistant daemon.
+ *
+ * Derived from the daemon's own budget rather than guessed. Its shutdown arms
+ * a 30s force-exit timer; when that fires it hands the SQLite WAL fold to a
+ * detached subprocess that outlives `process.exit` and then exits. So a daemon
+ * whose event loop still runs is gone within 30s with its WAL folded, and a
+ * daemon whose event loop is blocked never fires that timer at all, which no
+ * amount of extra waiting changes. Waiting past the daemon's own ceiling plus
+ * a margin therefore buys nothing and only delays the SIGKILL.
+ *
+ * A ceiling, not a delay. The CLI returns as soon as the process exits, so
+ * this only applies to a daemon that is genuinely wedged.
+ */
+export const DAEMON_STOP_TIMEOUT_MS = 45_000;
+
+/**
+ * Headroom a host wrapper allows on top of {@link DAEMON_STOP_TIMEOUT_MS} for
+ * the rest of a command: the gateway's drain window, the CES and Qdrant stops,
+ * and any archiving or bring-up the command does around them.
+ */
+export const HOST_WRAPPER_HEADROOM_MS = 30_000;
+
+/** Headroom for commands that also archive or provision after stopping. */
+export const HOST_WRAPPER_LONG_HEADROOM_MS = 60_000;
+
+/**
+ * How long the CLI polls a freshly started daemon for readiness before giving
+ * up on it.
+ *
+ * A command that starts a daemon spends this before it can even discover it
+ * needs to stop one, so its wrapper budget has to cover the wait and the stop
+ * that may follow it, not just the stop.
+ */
+export const DAEMON_READINESS_WINDOW_MS = 60_000;