@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/tools/workflows/run-workflow.test.ts

@@ -27,7 +27,9 @@ mock.module("../../daemon/conversation-registry.js", () => ({
 let lastStartArgs: Record<string, unknown> | null = null;
 let startThrows: Error | null = null;
 const startMock = mock((opts: Record<string, unknown>) => {
-  if (startThrows) throw startThrows;
+  if (startThrows) {
+    throw startThrows;
+  }
   lastStartArgs = opts;
   return { runId: "run-123" };
 });
@@ -36,7 +38,9 @@ const abortMock = mock(() => {});
 const listMock = mock(() => [] as unknown[]);
 let resumeThrows: Error | null = null;
 const resumeMock = mock((runId: string) => {
-  if (resumeThrows) throw resumeThrows;
+  if (resumeThrows) {
+    throw resumeThrows;
+  }
   return { runId };
 });
 
@@ -421,3 +425,51 @@ describe("manage_workflows", () => {
     expect(abortMock).toHaveBeenCalledWith("mine");
   });
 });
+
+// ── model-input schema validation (LUM-2855) ────────────────────────
+
+describe("workflow tools — model-input schema validation", () => {
+  test("run_workflow rejects a non-string script", async () => {
+    const result = await executeRunWorkflow({ script: 42 }, makeContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "run_workflow"');
+    expect(result.content).toContain("script");
+    expect(startMock).not.toHaveBeenCalled();
+  });
+
+  test("run_workflow treats explicit null script/name as omitted (bespoke exactly-one error)", async () => {
+    const result = await executeRunWorkflow(
+      { script: null, name: null },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("exactly one");
+  });
+
+  test("run_workflow passes args through unvalidated (workflow runtime accepts any JSON)", async () => {
+    const result = await executeRunWorkflow(
+      { script: "export const meta = {}", args: ["positional"] },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(lastStartArgs?.args).toEqual(["positional"]);
+  });
+
+  test("manage_workflows rejects a non-string run_id", async () => {
+    const result = await executeManageWorkflows(
+      { action: "status", run_id: 42 },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      'Invalid input for tool "manage_workflows"',
+    );
+    expect(result.content).toContain("run_id");
+  });
+
+  test("manage_workflows keeps the bespoke unknown-action error", async () => {
+    const result = await executeManageWorkflows({ action: 42 }, makeContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Unknown action");
+  });
+});

package/src/tools/workflows/run-workflow.ts

@@ -15,13 +15,37 @@
  * of truth the model reads when generating the `script`.
  */
 
+import { z } from "zod";
+
 import { findConversation } from "../../daemon/conversation-registry.js";
 import { FALLBACK_TURN_TRUST } from "../../daemon/trust-context.js";
 import type { TrustContext } from "../../daemon/trust-context-types.js";
 import { CapabilityManifestSchema } from "../../workflows/capabilities.js";
 import { getWorkflowRunManager } from "../../workflows/run-manager.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeRunWorkflow}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools — see the schema block in `tools/document/document-tool.ts` for the
+ * framework.
+ *
+ * `args` (the workflow runtime accepts any JSON value) and `capabilities`
+ * (`CapabilityManifestSchema` is the single validation authority, and
+ * `executor.ts` reads it pre-execution for the requireFreshApproval
+ * promotion) are deliberately UNDECLARED — loose passthrough. The
+ * exactly-one-of script/name rule stays a bespoke check below.
+ */
+export const runWorkflowInputSchema = z.looseObject({
+  script: nullAsOmitted(z.string()),
+  name: nullAsOmitted(z.string()),
+  label: nullAsOmitted(z.string()),
+});
+
 /**
  * Resolve the {@link TrustContext} to forward to the run's leaves. Prefer the
  * originating conversation's per-turn snapshot (the same context the live turn
@@ -33,7 +57,9 @@ function resolveTrustContext(context: ToolContext): TrustContext {
   const conversation = findConversation(context.conversationId);
   const fromConversation =
     conversation?.currentTurnTrustContext ?? conversation?.trustContext;
-  if (fromConversation) return fromConversation;
+  if (fromConversation) {
+    return fromConversation;
+  }
   return { ...FALLBACK_TURN_TRUST, trustClass: context.trustClass };
 }
 
@@ -41,8 +67,11 @@ export async function executeRunWorkflow(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const script = input.script as string | undefined;
-  const name = input.name as string | undefined;
+  const parsedInput = runWorkflowInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("run_workflow", parsedInput.error);
+  }
+  const { script, name, label } = parsedInput.data;
 
   // Exactly one of script/name is required.
   if ((script == null) === (name == null)) {
@@ -54,7 +83,6 @@ export async function executeRunWorkflow(
   }
 
   const args = (input.args as Record<string, unknown> | undefined) ?? {};
-  const label = input.label as string | undefined;
   const trustContext = resolveTrustContext(context);
 
   try {

package/src/util/fs-symlinks.ts

@@ -0,0 +1,30 @@
+import { lstatSync, readlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/**
+ * Follow a trailing symlink chain manually so a DANGLING link reports its
+ * destination. `realpathSync` throws on a link whose destination does not
+ * exist, which makes canonicalization fall back to the benign link path —
+ * but a write through the link creates the destination, so containment and
+ * security checks must see it. The bound sits above every supported
+ * platform's own traversal limit (Linux follows at most 40 links per
+ * resolution, macOS 32), so any chain this loop cannot exhaust is one the
+ * filesystem itself refuses to follow (ELOOP) — the eventual operation
+ * fails rather than writing through an unchecked destination.
+ */
+export function resolveTrailingLinkTarget(path: string): string {
+  let current = path;
+  for (let depth = 0; depth < 64; depth++) {
+    let linkTarget: string;
+    try {
+      if (!lstatSync(current).isSymbolicLink()) {
+        return current;
+      }
+      linkTarget = readlinkSync(current);
+    } catch {
+      return current;
+    }
+    current = resolve(dirname(current), linkTarget);
+  }
+  return current;
+}

package/src/util/log-redact.ts

@@ -11,15 +11,19 @@
  */
 
 import { memoizePluginPatternDerivation } from "../security/plugin-secret-patterns.js";
-import { PREFIX_PATTERNS } from "../security/secret-patterns.js";
+import { REDACTION_PREFIX_PATTERNS } from "../security/secret-patterns.js";
 
 // ---------------------------------------------------------------------------
-// Sensitive-value patterns (derived from shared PREFIX_PATTERNS)
+// Sensitive-value patterns (derived from shared REDACTION_PREFIX_PATTERNS)
 // ---------------------------------------------------------------------------
 
 const BEARER_RE = /Bearer [A-Za-z0-9._\-]+/g;
 
-const STATIC_API_KEY_PATTERNS: RegExp[] = PREFIX_PATTERNS.map(
+// This serializer redacts by replacing the matched span in place, so it uses
+// the bounded whole-block private-key matcher (via REDACTION_PREFIX_PATTERNS):
+// the match must cover header → body → footer or the key body would survive
+// redaction. The body bound keeps it O(n) on large serialized strings.
+const STATIC_API_KEY_PATTERNS: RegExp[] = REDACTION_PREFIX_PATTERNS.map(
   (p) => new RegExp(p.regex.source, "g"),
 );
 

package/src/vellum-assistant-namespace.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The single shape of `globalThis.vellumAssistant` — the per-process namespace
+ * that holds the assistant's process-global singletons.
+ *
+ * Several modules keep process-global state on `globalThis.vellumAssistant.*`
+ * (see the slots below). Each such slot is read/written by a production module
+ * AND, independently, by a test helper in `src/__tests__/` that must NOT import
+ * that production module (importing it would run its load-time side effects
+ * before the test preload establishes the per-process workspace override — the
+ * coupling behind the May 2026 DB-ghost incidents). This file is how both sides
+ * agree on the shape without a runtime import between them.
+ *
+ * It is an **ambient** declaration (no top-level `import`/`export`), so
+ * `VellumAssistantNamespace`, the slot types, and the `vellumAssistant` binding
+ * are global — every module and test helper refers to them by name with zero
+ * imports, and nothing here reaches into a `src/` module even at the type
+ * level. Referring to these types therefore never adds anything to any file's
+ * runtime import graph, so the test-machinery isolation invariant holds.
+ *
+ * Adding a slot: declare its value type here, add the optional property to
+ * `VellumAssistantNamespace`, and have the owning module + its test helper
+ * reference these globals instead of declaring their own copies.
+ */
+
+/** Slot value: the encrypted credential store path override. Managed by `security/store-path-override.ts`. */
+interface VellumStorePathOverride {
+  storePath: string | null;
+  storeKeyPath: string | null;
+}
+
+/** Which assistant DB connection a singleton slot holds. */
+type VellumDbSlotKey =
+  | "main"
+  | "main-readonly"
+  | "logs"
+  | "memory"
+  | "telemetry";
+
+/**
+ * Slot value: one lazily-opened DB connection and the closer that drops it.
+ * `db` is `unknown` so this shape never has to name a Drizzle type; callers in
+ * `persistence/db-connection.ts` narrow it via `getStoredDb<T>()`.
+ */
+interface VellumDbSlot {
+  db: unknown;
+  closer: (() => void) | null;
+}
+
+/** Slot value: the assistant DB connection singletons, keyed by connection. Managed by `persistence/db-singleton.ts`. */
+type VellumDbSlots = Record<VellumDbSlotKey, VellumDbSlot>;
+
+/** Slot value: the resolved feature-flag override cache. Managed by `config/feature-flag-cache.ts`. */
+interface VellumFeatureFlagCache {
+  overrides: Record<string, boolean | string> | null;
+  fromGateway: boolean;
+}
+
+/** The per-process `globalThis.vellumAssistant` namespace. */
+interface VellumAssistantNamespace {
+  /**
+   * Whether this OS process is the main assistant daemon. Set once by the
+   * daemon entrypoint; absent elsewhere. See `runtime/process-role.ts`.
+   */
+  mainDaemonProcess?: boolean;
+  /** See `security/store-path-override.ts`. */
+  storePathOverride?: VellumStorePathOverride;
+  /** See `persistence/db-singleton.ts`. */
+  dbSingletons?: VellumDbSlots;
+  /** See `config/feature-flag-cache.ts`. */
+  featureFlagCache?: VellumFeatureFlagCache;
+}
+
+/**
+ * Types `globalThis.vellumAssistant`. Undefined until the first slot accessor
+ * seeds it (`globalThis.vellumAssistant ??= {}`). Must be `var`: only `var`
+ * declarations at global scope become typed properties of `globalThis`
+ * (`let`/`const` do not), so this is the one idiomatic way to type the binding.
+ */
+// eslint-disable-next-line no-var
+declare var vellumAssistant: VellumAssistantNamespace | undefined;

package/src/watcher/watcher-store.ts

@@ -2,6 +2,7 @@ import { and, asc, desc, eq, gte, lte } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "../persistence/db-connection.js";
+import { isLifecycleQuiesced } from "../persistence/lifecycle-quiesce.js";
 import { rawChanges } from "../persistence/raw-query.js";
 import { watcherEvents, watchers } from "../persistence/schema/index.js";
 import { truncate } from "../util/truncate.js";
@@ -158,6 +159,13 @@ export function deleteWatcher(id: string): boolean {
  * to 'polling' using optimistic locking on the current nextPollAt.
  */
 export function claimDueWatchers(now: number): Watcher[] {
+  // Drain gate: while a quiesce lease is active, claim nothing — a watcher
+  // poll runs provider requests that create no row the drain snapshot can
+  // see, so it must not start at all. Fail-open via the lease read.
+  if (isLifecycleQuiesced()) {
+    return [];
+  }
+
   const db = getDb();
   const candidates = db
     .select()

package/src/workflows/leaf-runner.test.ts

@@ -472,6 +472,105 @@ describe("runLeaf — tool path", () => {
     expect(countConversations()).toBe(before);
   });
 
+  test("rejects out-of-workspace paths for sandbox file tools", async () => {
+    // Leaf tool calls bypass the ToolExecutor permission lane, so the file
+    // tools' out-of-workspace host fallback must be unreachable from a leaf.
+    const calls: Array<Record<string, unknown>> = [];
+    const fileRead: Tool = {
+      name: "file_read",
+      description: "Tool file_read",
+      category: "filesystem",
+      defaultRiskLevel: "low" as never,
+      executionTarget: "sandbox",
+      input_schema: { type: "object", properties: {}, required: [] },
+      async execute(
+        input: Record<string, unknown>,
+      ): Promise<ToolExecutionResult> {
+        calls.push(input);
+        return { content: "read ok", isError: false };
+      },
+    };
+
+    responseQueue = [
+      {
+        content: [
+          {
+            type: "tool_use",
+            name: "file_read",
+            id: "tu-1",
+            input: { path: "/etc/hosts" },
+          },
+        ],
+        model: "test",
+        usage: { inputTokens: 5, outputTokens: 2 },
+        stopReason: "tool_use",
+      },
+      {
+        content: [{ type: "text", text: "done" }],
+        model: "test",
+        usage: { inputTokens: 2, outputTokens: 1 },
+        stopReason: "end_turn",
+      },
+    ];
+
+    const result = await runLeaf({
+      prompt: "read the file",
+      tools: [fileRead],
+      trustContext,
+    });
+    expect(result.output).toBe("done");
+    // The workspace-bound guard fired before execute — the tool never ran.
+    expect(calls).toEqual([]);
+  });
+
+  test("in-workspace file tool paths still execute from a leaf", async () => {
+    const calls: Array<Record<string, unknown>> = [];
+    const fileRead: Tool = {
+      name: "file_read",
+      description: "Tool file_read",
+      category: "filesystem",
+      defaultRiskLevel: "low" as never,
+      executionTarget: "sandbox",
+      input_schema: { type: "object", properties: {}, required: [] },
+      async execute(
+        input: Record<string, unknown>,
+      ): Promise<ToolExecutionResult> {
+        calls.push(input);
+        return { content: "read ok", isError: false };
+      },
+    };
+
+    responseQueue = [
+      {
+        content: [
+          {
+            type: "tool_use",
+            name: "file_read",
+            id: "tu-1",
+            input: { path: "notes.txt" },
+          },
+        ],
+        model: "test",
+        usage: { inputTokens: 5, outputTokens: 2 },
+        stopReason: "tool_use",
+      },
+      {
+        content: [{ type: "text", text: "done" }],
+        model: "test",
+        usage: { inputTokens: 2, outputTokens: 1 },
+        stopReason: "end_turn",
+      },
+    ];
+
+    const result = await runLeaf({
+      prompt: "read the file",
+      tools: [fileRead],
+      trustContext,
+    });
+    expect(result.output).toBe("done");
+    expect(calls).toEqual([{ path: "notes.txt" }]);
+  });
+
   test("a leaf with no schema and an empty tool set runs the tool path (no throw)", async () => {
     // An empty resolved tool set with no schema must NOT fall through to the
     // schema path (where schemaToInputSchema(undefined) throws) — it runs the
@@ -702,8 +801,11 @@ describe("runLeaf — persona path", () => {
       }>;
       expect(messages[0]?.content[0]?.text).not.toBe(MEMORY_BLOCK_TEXT);
     } finally {
-      if (savedAuth === undefined) delete process.env.DISABLE_HTTP_AUTH;
-      else process.env.DISABLE_HTTP_AUTH = savedAuth;
+      if (savedAuth === undefined) {
+        delete process.env.DISABLE_HTTP_AUTH;
+      } else {
+        process.env.DISABLE_HTTP_AUTH = savedAuth;
+      }
     }
   });
 });

package/src/workflows/leaf-runner.ts

@@ -24,7 +24,7 @@
  *   `tool_choice` provider call whose synthetic tool's input schema is the
  *   caller's Zod schema. The returned tool input is Zod-validated and returned
  *   as `output`. Copies the proven pattern from `memory/v2/router.ts` and
- *   `memory/graph/extraction.ts`.
+ *   `memory/v1/graph/extraction.ts`.
  * - **Tool path** (`tools` provided, no `schema`): a real {@link AgentLoop} with
  *   a minimal task-scoped system prompt and a tool-executor restricted to the
  *   supplied registry tools. No conversation is bootstrapped — the loop runs
@@ -42,11 +42,13 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 
 import { type AgentEvent, AgentLoop } from "../agent/loop.js";
+import type { AssistantEvent } from "../api/index.js";
 import { getEffectiveProfile } from "../config/default-profile-catalog.js";
 import { getConfig } from "../config/loader.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import { isMemoryEnabled } from "../config/memory-v3-gate.js";
 import { isPersonalMemoryAllowed } from "../daemon/trust-context.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
+import { isOutOfWorkspaceFileInvocation } from "../permissions/workspace-policy.js";
 import { ConversationGraphMemory } from "../plugins/defaults/memory/graph/conversation-graph-memory.js";
 import { buildSystemPrompt } from "../prompts/system-prompt.js";
 import {
@@ -128,21 +130,31 @@ async function resolveLeafContext(
  * persona leaf still gets the assistant's identity system prompt but NO personal
  * memory. Without this, a workflow launched by an untrusted actor whose manifest
  * grants `persona` could exfiltrate private memory in its output.
+ *
+ * On a v3-live assistant a persona leaf receives no injected memory at all:
+ * `prepareMemory`'s v2 route is gated on `isV2InjectionEngineActive` (v3 live
+ * suppresses it), the v1 retriever short-circuits to empty under the
+ * concept-page substrate, and v3 orchestration is conversation-turn-scoped so
+ * it does not run for workflow leaves.
  */
 async function injectPersonaMemory(
   opts: RunLeafOptions,
   messages: Message[],
 ): Promise<Message[]> {
-  if (!isPersonalMemoryAllowed(opts.trustContext)) return messages;
+  if (!isPersonalMemoryAllowed(opts.trustContext)) {
+    return messages;
+  }
 
   const config = getConfig();
-  if (config.memory?.enabled === false) return messages;
+  if (!isMemoryEnabled(config)) {
+    return messages;
+  }
 
   const ephemeralConversationId = `workflow-leaf:${randomUUID()}`;
   const graphMemory = new ConversationGraphMemory(ephemeralConversationId);
   // The memory pipeline broadcasts retrieval progress to the shared event hub
   // (matching the main-agent hook); a leaf has no per-turn event callback.
-  const onEvent = (msg: ServerMessage): void => {
+  const onEvent = (msg: AssistantEvent): void => {
     broadcastMessage(msg);
   };
   // `prepareMemory` requires a non-aborting signal; reuse the caller's when
@@ -525,6 +537,17 @@ async function executeLeafTool(
     };
   }
 
+  // Leaf tool calls bypass the ToolExecutor's permission lane, so the file
+  // tools' out-of-workspace host fallback must not be reachable from here:
+  // the manifest consent covers workspace-scoped operation only, and leaves
+  // reject host tools outright. Keep the leaf workspace-bound.
+  if (isOutOfWorkspaceFileInvocation(name, input, ctx.workingDir)) {
+    return {
+      content: `Tool "${name}" may only access paths inside the workspace when invoked from a workflow leaf.`,
+      isError: true,
+    };
+  }
+
   const toolContext: ToolContext = {
     conversationId: ctx.ephemeralConversationId,
     workingDir: ctx.workingDir,
@@ -552,7 +575,9 @@ async function executeLeafTool(
 function finalAssistantText(history: Message[]): string {
   for (let i = history.length - 1; i >= 0; i--) {
     const msg = history[i];
-    if (msg.role !== "assistant") continue;
+    if (msg.role !== "assistant") {
+      continue;
+    }
     const text = msg.content
       .filter(
         (b): b is Extract<typeof b, { type: "text" }> => b.type === "text",

package/src/workspace/migrations/070-memory-v2-summary-schema-rebuild.ts

@@ -4,8 +4,8 @@ import type { WorkspaceMigration } from "./types.js";
  * Audit-only entry for the v2 concept-page schema upgrade introduced in PR
  * #29823 (summary_dense / summary_sparse named vectors). The destructive
  * collection rebuild and reembed enqueue both run inside the daemon at
- * Qdrant init time — see `maybeRebuildMemoryV2Concepts` in
- * `assistant/src/plugins/defaults/memory/v2/memory-v2-startup.ts`. The "exactly-once" fence is
+ * Qdrant init time — see `maybeRebuildConceptCollection` in
+ * `assistant/src/plugins/defaults/memory/substrate/boot-maintenance.ts`. The "exactly-once" fence is
  * per-collection schema introspection, not per-workspace checkpoint, so
  * users who wipe Qdrant separately still get re-rebuilt without resetting
  * any workspace flag.

package/src/workspace/migrations/134-image-generation-mode-to-provider.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Fold `services["image-generation"].mode` into the provider field.
+ *
+ * Configs written by older versions carry two axes: `mode: "managed"` routes
+ * generation through the Vellum platform runtime proxy while `provider`
+ * names the backend the proxy fronts (gemini or openai). The schema treats
+ * `provider` as the only axis, with `"vellum"` meaning managed and the
+ * backend derived from the selected model's prefix at request time, so this
+ * migration rewrites every managed service to `provider: "vellum"`. There is
+ * no per-provider exemption: the stored backend value under managed mode is
+ * itself derived from the model on every model write, so replacing it loses
+ * nothing — `model` is preserved verbatim and keeps routing the managed
+ * request to the same backend.
+ *
+ * Idempotent: a config with no `mode` key is left untouched.
+ */
+export const imageGenerationModeToProviderMigration: WorkspaceMigration = {
+  id: "134-image-generation-mode-to-provider",
+  description:
+    "Fold services.image-generation mode into provider (managed -> provider: vellum)",
+  run(workspaceDir: string): void {
+    const configPath = join(workspaceDir, "config.json");
+    if (!existsSync(configPath)) {
+      return;
+    }
+
+    let config: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return;
+      }
+      config = raw as Record<string, unknown>;
+    } catch {
+      return; // Malformed JSON — skip
+    }
+
+    const services = readObj(config, "services");
+    if (!services) {
+      return;
+    }
+
+    const service = readObj(services, "image-generation");
+    if (!service || !("mode" in service)) {
+      return;
+    }
+
+    if (service.mode === "managed") {
+      service.provider = "vellum";
+    } else if (!("provider" in service)) {
+      // An explicit non-managed mode with no persisted provider resolves to
+      // the gemini schema default. Pin that choice: with `mode` gone, an
+      // absent provider leaf would otherwise be context-filled to "vellum"
+      // on platform deployments, silently flipping a your-own config to
+      // managed billing.
+      service.provider = "gemini";
+    }
+    delete service.mode;
+
+    // Write-then-rename keeps the migration rerunnable: a crash mid-write
+    // must not leave a truncated config.json that a retry reads as malformed
+    // and "completes" past, quarantining the user's unrelated settings.
+    const tmpPath = `${configPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2) + "\n");
+    renameSync(tmpPath, configPath);
+  },
+  down(workspaceDir: string): void {
+    const configPath = join(workspaceDir, "config.json");
+    if (!existsSync(configPath)) {
+      return;
+    }
+
+    let config: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return;
+      }
+      config = raw as Record<string, unknown>;
+    } catch {
+      return;
+    }
+
+    const services = readObj(config, "services");
+    if (!services) {
+      return;
+    }
+
+    const service = readObj(services, "image-generation");
+    if (!service || "mode" in service) {
+      return;
+    }
+
+    // Schemas that predate this migration accept provider "vellum" alongside
+    // mode "managed", so the managed pair round-trips exactly. The backend
+    // provider a managed service holds before `run()` is not recoverable —
+    // `run()` overwrites it with "vellum". That value is derived from the
+    // model prefix, so it re-derives on the next model write.
+    service.mode = service.provider === "vellum" ? "managed" : "your-own";
+
+    // Write-then-rename keeps the migration rerunnable: a crash mid-write
+    // must not leave a truncated config.json that a retry reads as malformed
+    // and "completes" past, quarantining the user's unrelated settings.
+    const tmpPath = `${configPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2) + "\n");
+    renameSync(tmpPath, configPath);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers (self-contained per migration AGENTS.md)
+// ---------------------------------------------------------------------------
+
+function readObj(
+  parent: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> | undefined {
+  const value = parent[key];
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}