@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/runtime/migrations/__tests__/vbundle-builder-fd-leak.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Regression test for descriptor hygiene in the vbundle export path.
+ *
+ * `streamExportVBundle` opens every file in the workspace twice — once to hash
+ * it (Pass 1) and once to stream it into the tar (Pass 2). This test pins the
+ * invariant that those reads release their descriptors: the number of open
+ * descriptors held by the process must not grow proportionally to the number
+ * of files exported. Without that guarantee a workspace-sized export exhausts
+ * the daemon's descriptor limit (EMFILE) and every subsequent subprocess spawn
+ * fails.
+ *
+ * Descriptor counting uses `/proc/self/fd`, which only exists on Linux. The
+ * assertion is skipped on platforms without it (e.g. macOS dev machines); CI
+ * runs on Linux, so the regression stays covered there.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import { assertNotLiveDb } from "../../../__tests__/assert-not-live-db.js";
+import { streamExportVBundle } from "../vbundle-builder.js";
+import { defaultV1Options } from "./v1-test-helpers.js";
+
+const PROC_SELF_FD = "/proc/self/fd";
+const hasProcFd = existsSync(PROC_SELF_FD);
+
+/** Count the descriptors currently open by this process. */
+function openFdCount(): number {
+  return readdirSync(PROC_SELF_FD).length;
+}
+
+/**
+ * Build a workspace with enough distinct files (across nested directories) that
+ * a per-file descriptor leak would be obvious against the assertion bound.
+ */
+function createPopulatedWorkspace(fileCount: number): {
+  dir: string;
+  cleanup: () => void;
+} {
+  const dir = join(
+    tmpdir(),
+    `vbundle-fd-leak-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "config.json"), JSON.stringify({ test: true }));
+  const dbDir = join(dir, "data", "db");
+  mkdirSync(dbDir, { recursive: true });
+  writeFileSync(join(dbDir, "assistant.db"), "fake-db-content");
+
+  // A spread of files under a few nested directories, each with non-trivial
+  // (multi-chunk) content so the read loop iterates more than once.
+  const filler = "x".repeat(200 * 1024);
+  for (let i = 0; i < fileCount; i++) {
+    const sub = join(dir, "data", "files", `dir-${i % 5}`);
+    mkdirSync(sub, { recursive: true });
+    writeFileSync(join(sub, `file-${i}.txt`), `${filler}\n${i}`);
+  }
+
+  return {
+    dir,
+    cleanup: () => {
+      assertNotLiveDb(dir);
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("streamExportVBundle — descriptor lifecycle", () => {
+  test.skipIf(!hasProcFd)(
+    "does not leak a file descriptor per exported file",
+    async () => {
+      const fileCount = 60;
+      const workspace = createPopulatedWorkspace(fileCount);
+
+      // Warm-up export: first run can open and cache descriptors that legitimately
+      // persist (loggers, the daemon DB, etc.). Measuring the delta around a
+      // second export isolates per-file leakage from one-time setup.
+      let warmup: Awaited<ReturnType<typeof streamExportVBundle>> | undefined;
+      try {
+        warmup = await streamExportVBundle({
+          workspaceDir: workspace.dir,
+          ...defaultV1Options(),
+        });
+      } finally {
+        await warmup?.cleanup();
+      }
+
+      const before = openFdCount();
+
+      let result: Awaited<ReturnType<typeof streamExportVBundle>> | undefined;
+      try {
+        result = await streamExportVBundle({
+          workspaceDir: workspace.dir,
+          ...defaultV1Options(),
+        });
+        // Manifest covers every file we wrote — proves the walk actually read
+        // them (otherwise a no-op export would trivially leak nothing).
+        expect(result.manifest.contents.length).toBeGreaterThanOrEqual(
+          fileCount,
+        );
+      } finally {
+        await result?.cleanup();
+        workspace.cleanup();
+      }
+
+      const after = openFdCount();
+      const delta = after - before;
+
+      // Each export reads 2×fileCount files (hash pass + tar pass). A per-file
+      // leak would push the delta past `fileCount`. Allow a small constant for
+      // incidental descriptors (temp output file already cleaned up, jitter).
+      expect(delta).toBeLessThan(8);
+    },
+  );
+});

package/src/runtime/migrations/vbundle-builder.ts

@@ -11,7 +11,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
   closeSync,
-  createReadStream,
   createWriteStream,
   existsSync,
   lstatSync,
@@ -21,7 +20,7 @@ import {
   readSync,
   realpathSync,
 } from "node:fs";
-import { stat, unlink } from "node:fs/promises";
+import { type FileHandle, open, stat, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -886,9 +885,10 @@ export function walkDirectoryForMetadata(
 }
 
 /**
- * Compute SHA-256 hex digest of a file by streaming — never buffers the
- * entire file in memory. When `size` is provided, only hashes the first
- * `size` bytes to match what will be archived in the tar entry.
+ * Compute SHA-256 hex digest of a file by reading it in bounded chunks —
+ * never buffers the entire file in memory. When `size` is provided, only
+ * hashes the first `size` bytes to match what will be archived in the tar
+ * entry.
  */
 async function computeFileSha256(
   filePath: string,
@@ -896,11 +896,28 @@ async function computeFileSha256(
 ): Promise<string> {
   const hash = createHash("sha256");
   if (size === 0) return hash.digest("hex");
-  const streamOpts =
-    size !== undefined ? { start: 0, end: size - 1 } : undefined;
-  const stream = createReadStream(filePath, streamOpts);
-  for await (const chunk of stream) {
-    hash.update(chunk);
+
+  // Read through an explicitly-managed FileHandle so the descriptor is
+  // always released in `finally`. This pass opens every file in the
+  // workspace, so any per-file descriptor leak here would exhaust the
+  // daemon's file-descriptor limit (EMFILE). A bounded read loop keeps peak
+  // memory flat regardless of file size.
+  const readChunkBytes = 64 * 1024;
+  const handle = await open(filePath, "r");
+  try {
+    const chunk = Buffer.allocUnsafe(readChunkBytes);
+    let position = 0;
+    for (;;) {
+      const remaining = size !== undefined ? size - position : Infinity;
+      if (remaining <= 0) break;
+      const toRead = Math.min(chunk.length, remaining);
+      const { bytesRead } = await handle.read(chunk, 0, toRead, position);
+      if (bytesRead === 0) break;
+      hash.update(chunk.subarray(0, bytesRead));
+      position += bytesRead;
+    }
+  } finally {
+    await handle.close();
   }
   return hash.digest("hex");
 }
@@ -1056,21 +1073,33 @@ async function* generateTarStream(
       // alignment. The WAL checkpoint before export is the primary
       // consistency mechanism for the database.
       let bytesWritten = 0;
-      if (file.size > 0) {
+      if (entrySize > 0) {
+        // Read through an explicitly-managed FileHandle so the descriptor is
+        // released in `finally` even when the consumer abandons the generator
+        // mid-file. Each read uses a fresh buffer so a yielded chunk is never
+        // overwritten by the next read before the consumer drains it.
+        let handle: FileHandle | undefined;
         try {
-          const stream = createReadStream(file.diskPath, {
-            start: 0,
-            end: file.size - 1,
-          });
-          for await (const chunk of stream) {
-            const data =
-              chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
-            bytesWritten += data.length;
-            yield data;
+          handle = await open(file.diskPath, "r");
+          const readChunkBytes = 64 * 1024;
+          while (bytesWritten < entrySize) {
+            const toRead = Math.min(readChunkBytes, entrySize - bytesWritten);
+            const buf = Buffer.allocUnsafe(toRead);
+            const { bytesRead } = await handle.read(
+              buf,
+              0,
+              toRead,
+              bytesWritten,
+            );
+            if (bytesRead === 0) break;
+            bytesWritten += bytesRead;
+            yield bytesRead === buf.length ? buf : buf.subarray(0, bytesRead);
           }
         } catch {
           // File was deleted or rotated between passes — emit zeros for
           // the full declared size so the tar structure stays valid
+        } finally {
+          if (handle) await handle.close();
         }
       }
 

package/src/runtime/pending-interactions.ts

@@ -19,6 +19,7 @@
  */
 
 import type { InteractionResolutionState } from "../api/events/interaction-resolved.js";
+import type { QuestionEntry } from "../api/events/question-request.js";
 import type { UserDecision } from "../permissions/types.js";
 import { getLogger } from "../util/logger.js";
 import { broadcastMessage } from "./assistant-event-hub.js";
@@ -50,6 +51,18 @@ export interface ConfirmationDetails {
   }>;
 }
 
+/**
+ * Full batched question payload carried on a pending `question` interaction, so
+ * a history-load render can stamp the outstanding prompt back onto its tool
+ * call and rehydrate the question card on a cold reconnect. Mirrors the
+ * `question_request` event's `questions[]` — `metadata` only retains the
+ * `orderedIds`/`optionsById` the response route needs to validate submissions,
+ * which is insufficient to reconstruct the card.
+ */
+export interface QuestionDetails {
+  entries: QuestionEntry[];
+}
+
 export interface PendingInteraction {
   /**
    * Owning conversation, when the interaction was raised inside one. Absent
@@ -69,6 +82,8 @@ export interface PendingInteraction {
     | "host_transfer"
     | "acp_confirmation";
   confirmationDetails?: ConfirmationDetails;
+  /** For a pending `question`: the full batched entries, so a history-load render can rehydrate the question card. */
+  questionDetails?: QuestionDetails;
   /** For ACP permissions: resolves directly without a Conversation object. */
   directResolve?: (decision: UserDecision) => void;
   /** When set, the host_bash request should be routed to this specific client. */

package/src/runtime/routes/__tests__/client-routes.test.ts

@@ -51,6 +51,7 @@ type ListClientsResponse = {
     machineName?: string;
     connectedAt: string;
     lastActiveAt: string;
+    degraded?: boolean;
   }>;
 };
 
@@ -152,4 +153,16 @@ describe("list_clients route — same-user filter", () => {
     const ids = result.clients.map((c) => c.clientId).sort();
     expect(ids).toEqual(["client-A1", "client-B1", "client-noprincipal"]);
   });
+
+  test("includes a degraded flag (false for a freshly connected client)", () => {
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+
+    const handler = findHandler("list_clients");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-A" },
+    }) as ListClientsResponse;
+
+    expect(result.clients).toHaveLength(1);
+    expect(result.clients[0].degraded).toBe(false);
+  });
 });

package/src/runtime/routes/__tests__/conversation-management-routes.test.ts

@@ -26,6 +26,8 @@ mock.module("../../assistant-event-hub.js", () => ({
   broadcastMessage: () => {},
 }));
 
+import { eq } from "drizzle-orm";
+
 import { getDb } from "../../../memory/db-connection.js";
 import { initializeDb } from "../../../memory/db-init.js";
 import { conversations } from "../../../memory/schema.js";
@@ -71,6 +73,10 @@ function findHandler(routes: RouteDefinition[], operationId: string) {
   return route.handler;
 }
 
+const createHandler = findHandler(
+  CONVERSATION_MANAGEMENT_ROUTES,
+  "createConversation",
+);
 const putHandler = findHandler(
   CONVERSATION_MANAGEMENT_ROUTES,
   "setConversationInferenceProfile",
@@ -112,6 +118,67 @@ function seedConversation(id: string): void {
 // Tests
 // ---------------------------------------------------------------------------
 
+describe("POST /v1/conversations (createConversation)", () => {
+  beforeEach(() => {
+    clearConversations();
+  });
+
+  function readConversation(id: string) {
+    return getDb()
+      .select({
+        title: conversations.title,
+        isAutoTitle: conversations.isAutoTitle,
+      })
+      .from(conversations)
+      .where(eq(conversations.id, id))
+      .get();
+  }
+
+  test("with a title → persists it as a user-set title (isAutoTitle = 0)", async () => {
+    const result = (await createHandler({
+      body: { conversationType: "standard", title: "Setting up your check-in" },
+    })) as { id: string; created: boolean };
+
+    expect(result.created).toBe(true);
+    const row = readConversation(result.id);
+    expect(row?.title).toBe("Setting up your check-in");
+    // isAutoTitle = 0 keeps the async LLM titler from overwriting it.
+    expect(row?.isAutoTitle).toBe(0);
+  });
+
+  test("blank title falls back to the replaceable 'New Conversation' placeholder", async () => {
+    const result = (await createHandler({
+      body: { conversationType: "standard", title: "   " },
+    })) as { id: string; created: boolean };
+
+    expect(result.created).toBe(true);
+    const row = readConversation(result.id);
+    expect(row?.title).toBe("New Conversation");
+    // Default auto-title flag (1) leaves it replaceable by the auto-titler.
+    expect(row?.isAutoTitle).toBe(1);
+  });
+
+  test("no title → 'New Conversation' placeholder", async () => {
+    const result = (await createHandler({
+      body: { conversationType: "standard" },
+    })) as { id: string; created: boolean };
+
+    expect(result.created).toBe(true);
+    const row = readConversation(result.id);
+    expect(row?.title).toBe("New Conversation");
+    expect(row?.isAutoTitle).toBe(1);
+  });
+
+  test("non-string title → BadRequestError (not a 500), no row created", () => {
+    // The shared route adapter doesn't runtime-validate the body, so the
+    // handler must reject a malformed title before `.trim()` throws.
+    expect(() =>
+      createHandler({ body: { conversationType: "standard", title: 123 } }),
+    ).toThrow(/title must be a string/);
+    expect(getDb().select().from(conversations).all()).toHaveLength(0);
+  });
+});
+
 describe("PUT /v1/conversations/:id/inference-profile", () => {
   beforeEach(() => {
     clearConversations();

package/src/runtime/routes/__tests__/plugins-routes.test.ts

@@ -34,6 +34,12 @@
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import {
+  type DiffPluginDeps,
+  type DiffPluginOptions,
+  type PluginDiffResult,
+  PluginDiffUnavailableError,
+} from "../../../cli/lib/diff-plugin.js";
 import {
   type InspectPluginDeps,
   type InspectPluginOptions,
@@ -66,6 +72,7 @@ import {
   type UninstallPluginResult,
 } from "../../../cli/lib/uninstall-plugin.js";
 import {
+  PluginMergeBaselineError,
   PluginNotUpgradableError,
   type PluginUpgradeResult,
   type UpgradePluginDeps,
@@ -173,10 +180,28 @@ const upgradeSpy = mock(
 );
 
 mock.module("../../../cli/lib/upgrade-plugin.js", () => ({
+  PluginMergeBaselineError,
   PluginNotUpgradableError,
   upgradePlugin: upgradeSpy,
 }));
 
+// Mock diffPlugin: the lib re-materializes the install commit and computes the
+// per-file unified diff (covered by diff-plugin.test.ts); the route forwards
+// the name and maps the lib's error taxonomy to HTTP status codes.
+const diffSpy = mock(
+  async (
+    _opts: DiffPluginOptions,
+    _deps: DiffPluginDeps,
+  ): Promise<PluginDiffResult> => {
+    throw new Error("diffSpy default impl not configured");
+  },
+);
+
+mock.module("../../../cli/lib/diff-plugin.js", () => ({
+  PluginDiffUnavailableError,
+  diffPlugin: diffSpy,
+}));
+
 import {
   BadRequestError,
   ConflictError,
@@ -200,6 +225,7 @@ const getHandler = findHandler("plugins_get");
 const installHandler = findHandler("plugins_install");
 const inspectHandler = findHandler("plugins_inspect");
 const upgradeHandler = findHandler("plugins_upgrade");
+const diffHandler = findHandler("plugins_diff");
 
 function invoke(args: RouteHandlerArgs = {}): {
   plugins: Array<Record<string, unknown>>;
@@ -976,6 +1002,10 @@ function inspection(
           }
         : overrides.remote,
     remoteError: overrides.remoteError ?? null,
+    surfaces:
+      overrides.surfaces === undefined
+        ? { skills: [], hooks: ["post-model-call"], tools: [] }
+        : overrides.surfaces,
   };
 }
 
@@ -1080,6 +1110,9 @@ function upgradeResult(
     target: overrides.target ?? "/workspace/.vellum/plugins/level-up",
     fileCount: overrides.fileCount === undefined ? 12 : overrides.fileCount,
     dryRun: overrides.dryRun ?? false,
+    strategy: overrides.strategy ?? "overwrite",
+    conflicts: overrides.conflicts ?? [],
+    binaryConflicts: overrides.binaryConflicts ?? [],
     provenanceWasUnknown: overrides.provenanceWasUnknown ?? false,
   };
 }
@@ -1094,6 +1127,9 @@ async function invokeUpgrade(args: RouteHandlerArgs = {}): Promise<{
   target: string;
   fileCount: number | null;
   dryRun: boolean;
+  strategy: string;
+  conflicts: readonly string[];
+  binaryConflicts: readonly string[];
   provenanceWasUnknown: boolean;
 }> {
   return (await upgradeHandler(args)) as {
@@ -1106,6 +1142,9 @@ async function invokeUpgrade(args: RouteHandlerArgs = {}): Promise<{
     target: string;
     fileCount: number | null;
     dryRun: boolean;
+    strategy: string;
+    conflicts: readonly string[];
+    binaryConflicts: readonly string[];
     provenanceWasUnknown: boolean;
   };
 }
@@ -1136,13 +1175,83 @@ describe("POST /v1/plugins/:name/upgrade", () => {
       target: "/workspace/.vellum/plugins/level-up",
       fileCount: 12,
       dryRun: false,
+      strategy: "overwrite",
+      conflicts: [],
+      binaryConflicts: [],
       provenanceWasUnknown: false,
     });
-    // AND the name + dryRun are forwarded to the lib
+    // AND the name + dryRun are forwarded to the lib (strategy omitted)
     expect(upgradeSpy.mock.calls[0]?.[0]).toEqual({
       name: "level-up",
       dryRun: false,
+      strategy: undefined,
+    });
+  });
+
+  test("forwards a requested strategy to the lib and projects it", async () => {
+    // GIVEN upgradePlugin merges local edits forward via the `ours` strategy
+    upgradeSpy.mockImplementation(async () =>
+      upgradeResult({ strategy: "ours" }),
+    );
+
+    // WHEN the handler runs with a strategy in the body
+    const result = await invokeUpgrade({
+      pathParams: { name: "level-up" },
+      body: { strategy: "ours" },
+    });
+
+    // THEN the strategy is forwarded to the lib and surfaced on the wire
+    expect(result.strategy).toBe("ours");
+    expect(upgradeSpy.mock.calls[0]?.[0]).toEqual({
+      name: "level-up",
+      dryRun: undefined,
+      strategy: "ours",
+    });
+  });
+
+  test("projects conflicts + binaryConflicts from the assistant strategy onto the wire", async () => {
+    // GIVEN upgradePlugin merges with conflict markers under `assistant`
+    upgradeSpy.mockImplementation(async () =>
+      upgradeResult({
+        strategy: "assistant",
+        conflicts: ["hooks/post-model-call.ts"],
+        binaryConflicts: ["assets/icon.png"],
+      }),
+    );
+
+    // WHEN the handler runs with the `assistant` strategy
+    const result = await invokeUpgrade({
+      pathParams: { name: "level-up" },
+      body: { strategy: "assistant" },
+    });
+
+    // THEN the conflicted paths are surfaced for the assistant to resolve
+    expect(result.strategy).toBe("assistant");
+    expect(result.conflicts).toEqual(["hooks/post-model-call.ts"]);
+    expect(result.binaryConflicts).toEqual(["assets/icon.png"]);
+    expect(upgradeSpy.mock.calls[0]?.[0]).toEqual({
+      name: "level-up",
+      dryRun: undefined,
+      strategy: "assistant",
+    });
+  });
+
+  test("PluginMergeBaselineError \u2192 ConflictError (409)", async () => {
+    // A merge strategy whose install-time baseline can't be reconstructed: a
+    // well-formed request that isn't actionable in the current state.
+    upgradeSpy.mockImplementation(async () => {
+      throw new PluginMergeBaselineError(
+        "level-up",
+        "the install-time baseline could not be faithfully reconstructed",
+      );
     });
+
+    await expect(
+      invokeUpgrade({
+        pathParams: { name: "level-up" },
+        body: { strategy: "ours" },
+      }),
+    ).rejects.toBeInstanceOf(ConflictError);
   });
 
   test("omits dryRun (passes undefined) when the body flag is absent", async () => {
@@ -1246,3 +1355,133 @@ describe("POST /v1/plugins/:name/upgrade", () => {
     expect((caught as Error).message).toContain("ECONNRESET");
   });
 });
+
+function diffResult(
+  overrides: Partial<PluginDiffResult> = {},
+): PluginDiffResult {
+  return {
+    name: overrides.name ?? "level-up",
+    target: overrides.target ?? "/workspace/.vellum/plugins/level-up",
+    commit: overrides.commit ?? "60a392b0000000000000000000000000000000aa",
+    committedAt: overrides.committedAt ?? "2026-06-01T12:34:56.000Z",
+    clean: overrides.clean ?? false,
+    files: overrides.files ?? [
+      {
+        path: "src/skill.ts",
+        status: "modified",
+        diff: "--- a/src/skill.ts\n+++ b/src/skill.ts\n@@ -1 +1 @@\n-old\n+new\n",
+        binary: false,
+        reconstructed: true,
+      },
+    ],
+  };
+}
+
+async function invokeDiff(
+  args: RouteHandlerArgs = {},
+): Promise<PluginDiffResult> {
+  return (await diffHandler(args)) as PluginDiffResult;
+}
+
+describe("POST /v1/plugins/:name/diff", () => {
+  beforeEach(() => {
+    diffSpy.mockReset();
+  });
+
+  test("forwards the name to diffPlugin and returns the diff verbatim", async () => {
+    // GIVEN diffPlugin reports a single modified file against the install commit
+    const view = diffResult();
+    diffSpy.mockImplementation(async () => view);
+
+    // WHEN the route handler is invoked with the path name
+    const result = await invokeDiff({ pathParams: { name: "level-up" } });
+
+    // THEN the diff is returned unchanged
+    expect(result).toEqual(view);
+    // AND only the name is forwarded to the lib (ref is never caller-supplied)
+    expect(diffSpy.mock.calls[0]?.[0]).toEqual({ name: "level-up" });
+  });
+
+  test("InvalidPluginNameError → BadRequestError (400)", async () => {
+    diffSpy.mockImplementation(async () => {
+      throw new InvalidPluginNameError("../escape");
+    });
+
+    await expect(
+      invokeDiff({ pathParams: { name: "../escape" } }),
+    ).rejects.toBeInstanceOf(BadRequestError);
+  });
+
+  test("PluginNotInstalledError → NotFoundError (404)", async () => {
+    diffSpy.mockImplementation(async () => {
+      throw new PluginNotInstalledError(
+        "ghost",
+        "/workspace/.vellum/plugins/ghost",
+      );
+    });
+
+    await expect(
+      invokeDiff({ pathParams: { name: "ghost" } }),
+    ).rejects.toBeInstanceOf(NotFoundError);
+  });
+
+  test("PluginNotFoundError → NotFoundError (404)", async () => {
+    // The recorded commit no longer resolves to a tree (source/commit gone).
+    diffSpy.mockImplementation(async () => {
+      throw new PluginNotFoundError(
+        "level-up",
+        "deadbeef",
+        "vellum-ai/level-up",
+      );
+    });
+
+    await expect(
+      invokeDiff({ pathParams: { name: "level-up" } }),
+    ).rejects.toBeInstanceOf(NotFoundError);
+  });
+
+  test("PluginDiffUnavailableError → ConflictError (409)", async () => {
+    // The install recorded no commit, so there is no baseline to diff against:
+    // a well-formed request that is not actionable in the current state.
+    diffSpy.mockImplementation(async () => {
+      throw new PluginDiffUnavailableError(
+        "level-up",
+        "no install commit was recorded",
+      );
+    });
+
+    await expect(
+      invokeDiff({ pathParams: { name: "level-up" } }),
+    ).rejects.toBeInstanceOf(ConflictError);
+  });
+
+  test("PluginSourceUnavailableError → ServiceUnavailableError (503)", async () => {
+    // Re-materializing the baseline can hit a rate-limited/down GitHub; that is
+    // retryable, so surface 503 rather than a misleading 500.
+    diffSpy.mockImplementation(async () => {
+      throw new PluginSourceUnavailableError(
+        "git clone failed for vellum-ai/level-up: HTTP 403",
+        503,
+      );
+    });
+
+    await expect(
+      invokeDiff({ pathParams: { name: "level-up" } }),
+    ).rejects.toBeInstanceOf(ServiceUnavailableError);
+  });
+
+  test("unknown errors → InternalError with original message preserved", async () => {
+    diffSpy.mockImplementation(async () => {
+      throw new Error("ECONNRESET");
+    });
+
+    let caught: unknown;
+    try {
+      await invokeDiff({ pathParams: { name: "level-up" } });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(InternalError);
+    expect((caught as Error).message).toContain("ECONNRESET");
+  });
+});