@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/__tests__/client-os-metadata-persistence.test.ts

@@ -201,6 +201,22 @@ describe("client OS per-row evidence marker", () => {
     expect(isMacOriginatedUserMessage(lastUserMetadata())).toBe(true);
   });
 
+  // Mirrors the Mac-originated case above: a plain browser tab reports
+  // `client.os: "web"`, while the Electron desktop renderer resolves its own
+  // host OS first and persists `macos`/`windows` instead.
+  test("marks an OS this row's own transport reported (web)", async () => {
+    const ctx = createWebTurnContext("web");
+    await persistQueuedMessageBody(ctx, {
+      content: "hello",
+      requestId: "req-transport-os-web",
+      requestClientOs: "web",
+    });
+
+    expect(lastUserMetadata().client).toEqual({ os: "web" });
+    expect(lastUserMetadata().clientOsFromRequest).toBe(true);
+    expect(isMacOriginatedUserMessage(lastUserMetadata())).toBe(false);
+  });
+
   test("marks an OS this row's own request headers reported", async () => {
     const ctx = createWebTurnContext(undefined);
     await persistQueuedMessageBody(ctx, {

package/src/__tests__/compactor-retained-image-validation.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Compaction must never bake invalid image bytes into the rebuilt history.
+ *
+ * Retained images are re-hydrated from the attachment store and re-optimized
+ * at compaction time. If that pipeline yields bytes that no longer parse as an
+ * image (e.g. a corrupt conversion-cache entry), embedding them would make the
+ * provider reject EVERY subsequent turn with a 400: the conversation wedges
+ * until the block is manually removed. `buildRetainedImageBlocks` drops such
+ * payloads instead.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  buildRetainedImageBlocks,
+  collectImageManifest,
+} from "../context/compactor.js";
+import { attachInlineAttachmentToMessage } from "../persistence/attachments-store.js";
+import {
+  addMessage,
+  createConversation,
+} from "../persistence/conversation-crud.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+
+await initializeDb();
+
+// 1x1 transparent PNG.
+const PNG_1X1_BASE64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+
+// Declared image/png, but the bytes are not any known image format:
+// the stand-in for a corrupted payload surviving in the pipeline.
+const GARBAGE_BASE64 = Buffer.from("definitely not an image").toString(
+  "base64",
+);
+
+function resetTables(): void {
+  const db = getDb();
+  db.run("DELETE FROM message_attachments");
+  db.run("DELETE FROM attachments");
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+async function addImageMessage(
+  conversationId: string,
+  filename: string,
+  dataBase64: string,
+): Promise<void> {
+  const inserted = await addMessage(
+    conversationId,
+    "user",
+    JSON.stringify([{ type: "text", text: filename }]),
+    {
+      metadata: { provenanceTrustClass: "guardian" },
+      skipIndexing: true,
+    },
+  );
+  await attachInlineAttachmentToMessage(
+    inserted.id,
+    0,
+    filename,
+    "image/png",
+    dataBase64,
+  );
+}
+
+describe("buildRetainedImageBlocks corrupt-bytes gate", () => {
+  beforeEach(resetTables);
+
+  test("valid image bytes are retained", async () => {
+    const conv = createConversation();
+    await addImageMessage(conv.id, "good.png", PNG_1X1_BASE64);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["good.png"],
+      manifest,
+    );
+
+    expect(resolved).toEqual(["good.png"]);
+    expect(missing).toEqual([]);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].source.type).toBe("base64");
+  });
+
+  test("bytes that do not parse as an image are dropped, not embedded", async () => {
+    const conv = createConversation();
+    await addImageMessage(conv.id, "corrupt.png", GARBAGE_BASE64);
+    await addImageMessage(conv.id, "good.png", PNG_1X1_BASE64);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["corrupt.png", "good.png"],
+      manifest,
+    );
+
+    // The corrupt payload is dropped (not listed as manifest-missing, since
+    // it resolved fine; its bytes were the problem) and the valid one
+    // survives.
+    expect(resolved).toEqual(["good.png"]);
+    expect(missing).toEqual([]);
+    expect(blocks).toHaveLength(1);
+  });
+
+  test("a truncated JPEG (valid SOI header, no EOI) is dropped", async () => {
+    // A JPEG torn mid-write keeps its SOI header, so a format sniff alone
+    // accepts it; the gate must also require an EOI marker.
+    const tornJpeg = Buffer.concat([
+      Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10]),
+      Buffer.from("JFIF\0"),
+      Buffer.alloc(64),
+    ]).toString("base64");
+    const conv = createConversation();
+    await addImageMessage(conv.id, "torn.jpg", tornJpeg);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["torn.jpg"],
+      manifest,
+    );
+
+    expect(resolved).toEqual([]);
+    expect(missing).toEqual([]);
+    expect(blocks).toHaveLength(0);
+  });
+
+  test("unresolvable filenames still land in missing", async () => {
+    const conv = createConversation();
+    await addImageMessage(conv.id, "good.png", PNG_1X1_BASE64);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["never-uploaded.png", "good.png"],
+      manifest,
+    );
+
+    expect(missing).toEqual(["never-uploaded.png"]);
+    expect(resolved).toEqual(["good.png"]);
+    expect(blocks).toHaveLength(1);
+  });
+});

package/src/__tests__/container-cpu-sampler.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  __resetContainerCpuSamplerForTests,
+  __runContainerCpuSamplerTickForTests,
+  computeCpuPercent,
+  computeDurationWeightedMeanPercent,
+  getAverageContainerCpuPercentOrNull,
+  getCachedContainerCpuPercent,
+  getCachedContainerCpuPercentOrNull,
+} from "../util/container-cpu-sampler.js";
+
+describe("computeCpuPercent", () => {
+  test("computes percent of the full allocation from a CPU-time delta", () => {
+    // 2.5s of CPU over a 5s window on 1 core is 50% of the allocation.
+    expect(computeCpuPercent(2_500_000, 5_000, 1)).toBe(50);
+    // The same delta on 2 cores is half the utilization.
+    expect(computeCpuPercent(2_500_000, 5_000, 2)).toBe(25);
+    // Fully saturating 4 cores for the whole window is 100%.
+    expect(computeCpuPercent(20_000_000, 5_000, 4)).toBe(100);
+  });
+
+  test("rounds to 2 decimal places", () => {
+    expect(computeCpuPercent(123_456, 5_000, 2)).toBe(1.23);
+    expect(computeCpuPercent(123_999, 5_000, 2)).toBe(1.24);
+    expect(computeCpuPercent(0, 5_000, 1)).toBe(0);
+  });
+
+  test("yields a non-finite result for zero cores, which callers must guard", () => {
+    expect(Number.isFinite(computeCpuPercent(1_000_000, 5_000, 0))).toBe(false);
+    expect(Number.isFinite(computeCpuPercent(0, 5_000, 0))).toBe(false);
+  });
+});
+
+describe("getCachedContainerCpuPercent", () => {
+  test("returns a finite number", () => {
+    expect(Number.isFinite(getCachedContainerCpuPercent())).toBe(true);
+  });
+});
+
+describe("getCachedContainerCpuPercentOrNull", () => {
+  test("returns null until the sampler computes its first delta", () => {
+    __resetContainerCpuSamplerForTests();
+
+    expect(getCachedContainerCpuPercentOrNull()).toBeNull();
+    // The plain accessor keeps its 0 placeholder for /v1/health.
+    expect(getCachedContainerCpuPercent()).toBe(0);
+
+    // Drive one sampler tick a full interval ahead of the reset baseline so
+    // it computes a real delta from process.cpuUsage().
+    __runContainerCpuSamplerTickForTests(Date.now() + 5_000);
+
+    const sampled = getCachedContainerCpuPercentOrNull();
+    expect(sampled).not.toBeNull();
+    expect(Number.isFinite(sampled!)).toBe(true);
+    expect(sampled).toBe(getCachedContainerCpuPercent());
+  });
+});
+
+describe("computeDurationWeightedMeanPercent", () => {
+  test("weights each percent by the wall time its delta spanned", () => {
+    // 25s at 80% then 5s at 100% is 83.33% of the half minute, not the 90%
+    // an equal-weight mean would report.
+    expect(
+      computeDurationWeightedMeanPercent(
+        [
+          { at: 25_000, percent: 80, elapsedMs: 25_000 },
+          { at: 30_000, percent: 100, elapsedMs: 5_000 },
+        ],
+        0,
+      ),
+    ).toBe(83.33);
+    // Equal durations degrade to the plain mean.
+    expect(
+      computeDurationWeightedMeanPercent(
+        [
+          { at: 5_000, percent: 40, elapsedMs: 5_000 },
+          { at: 10_000, percent: 60, elapsedMs: 5_000 },
+        ],
+        0,
+      ),
+    ).toBe(50);
+  });
+
+  test("clips a delayed tick's contribution to its overlap with the window", () => {
+    // A 25s CPU-bound stall at 100% ends 1s into the window; only that 1s
+    // may count. With 29s of idle at 10% after it, the window reads 13%,
+    // not the 52.8% an unclipped duration weighting would report.
+    expect(
+      computeDurationWeightedMeanPercent(
+        [
+          { at: 1_000, percent: 100, elapsedMs: 25_000 },
+          { at: 30_000, percent: 10, elapsedMs: 29_000 },
+        ],
+        0,
+      ),
+    ).toBe(13);
+    // A tick entirely before the window contributes nothing.
+    expect(
+      computeDurationWeightedMeanPercent(
+        [
+          { at: -1_000, percent: 100, elapsedMs: 5_000 },
+          { at: 10_000, percent: 20, elapsedMs: 10_000 },
+        ],
+        0,
+      ),
+    ).toBe(20);
+  });
+
+  test("returns null without any overlapping samples", () => {
+    expect(computeDurationWeightedMeanPercent([], 0)).toBeNull();
+    expect(
+      computeDurationWeightedMeanPercent(
+        [{ at: 5_000, percent: 50, elapsedMs: 0 }],
+        0,
+      ),
+    ).toBeNull();
+    expect(
+      computeDurationWeightedMeanPercent(
+        [{ at: -1_000, percent: 50, elapsedMs: 5_000 }],
+        0,
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("getAverageContainerCpuPercentOrNull", () => {
+  test("returns null until a tick lands inside the window", () => {
+    __resetContainerCpuSamplerForTests();
+
+    expect(getAverageContainerCpuPercentOrNull(60_000)).toBeNull();
+  });
+
+  test("averages the ticks recorded within the trailing window", () => {
+    __resetContainerCpuSamplerForTests();
+
+    // A single recorded tick makes the average equal the last cached value.
+    __runContainerCpuSamplerTickForTests(Date.now() + 5_000);
+    const single = getAverageContainerCpuPercentOrNull(60_000);
+    expect(single).not.toBeNull();
+    expect(single).toBe(getCachedContainerCpuPercentOrNull());
+
+    // More ticks keep the average finite and within the recorded range; the
+    // exact value depends on real process CPU deltas, so only the invariant
+    // is asserted.
+    __runContainerCpuSamplerTickForTests(Date.now() + 10_000);
+    __runContainerCpuSamplerTickForTests(Date.now() + 15_000);
+    const averaged = getAverageContainerCpuPercentOrNull(60_000);
+    expect(averaged).not.toBeNull();
+    expect(Number.isFinite(averaged!)).toBe(true);
+    expect(averaged!).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/__tests__/context-search-memory-v2-source.test.ts

@@ -71,7 +71,6 @@ mock.module("../plugins/defaults/memory/substrate/edge-index.js", () => ({
   getEdgeIndex: async (): Promise<EdgeIndex> => edgeIndex,
   invalidateEdgeIndex: () => {},
   getReachable: () => new Set<string>(),
-  validateEdgeTargets: () => ({ ok: true, missing: [] }),
   totalEdgeCount: () => 0,
 }));
 

package/src/__tests__/conversation-attachments.test.ts

@@ -15,7 +15,6 @@ mock.module("../permissions/checker.js", () => ({
   isDynamicSkillLoadInvocation: () => false,
   check: checkSpy,
   classifyRisk: () => Promise.resolve({ level: "low" }),
-  generateAllowlistOptions: () => Promise.resolve([]),
   generateScopeOptions: () => [],
 }));
 

package/src/__tests__/conversation-error.test.ts

@@ -521,6 +521,23 @@ describe("classifyConversationError", () => {
       expect(result.userMessage.toLowerCase()).toContain("image");
     });
 
+    it("classifies an OpenAI-compatible 400 for an unreadable image as image_unsupported_format (non-retryable)", () => {
+      // The rejection an OpenAI-compatible endpoint returns when any image in
+      // the request is not one of the formats it decodes (a HEIC photo renamed
+      // to .png, say). It names no index, so the whole turn dies unless it is
+      // classified for the image-recovery path with actionable copy.
+      const err = new ProviderError(
+        "The image data you provided does not represent a valid image. Please check your input and try again with one of the supported image formats: [image/jpeg, image/png, image/gif, image/webp]",
+        "openai",
+        400,
+      );
+      const result = classifyConversationError(err, baseCtx);
+      expect(result.code).toBe("IMAGE_TOO_LARGE");
+      expect(result.errorCategory).toBe("image_unsupported_format");
+      expect(result.retryable).toBe(false);
+      expect(result.userMessage.toLowerCase()).toContain("image");
+    });
+
     it("does not steal generic 400s that happen to mention 'image'", () => {
       const err = new ProviderError(
         "invalid request: image source is missing",

package/src/__tests__/conversation-lifecycle.test.ts

@@ -652,14 +652,12 @@ describe("loadFromDb metadata injection rehydration", () => {
     expect(messages[2].content).toEqual([{ type: "text", text: "Tail" }]);
   });
 
-  test("internal-channel trusted_contact view still rehydrates memoryV2StaticBlock", async () => {
-    // Rehydration keys on `sourceChannel`, not `trustClass`: injection uses
-    // `shouldExposePersonalMemory`, which exposes personal memory whenever
-    // `sourceChannel === "vellum"` regardless of actor trust class. So a
-    // trusted_contact view arriving over the internal `"vellum"` channel
-    // rehydrates `memoryV2StaticBlock`. The rehydrate gate must match
-    // injection so a daemon-restart reload of the same conversation produces
-    // an identical prefix.
+  test("internal-channel trusted_contact view does not rehydrate memoryV2StaticBlock", async () => {
+    // Rehydration keys on the actor, not the surface: a trusted_contact is
+    // denied personal memory on the internal `"vellum"` channel exactly as it
+    // is on a remote one. Injection and rehydration share
+    // `canSeePersonalMemory`, so a daemon-restart reload of the same
+    // conversation produces an identical prefix.
     mockConversation = defaultConv();
     mockDbMessages = [
       {
@@ -697,13 +695,8 @@ describe("loadFromDb metadata injection rehydration", () => {
     const messages = conversation.getMessages();
 
     expect(messages).toHaveLength(3);
-    expect(messages[0].content).toEqual([
-      {
-        type: "text",
-        text: "<info>\n## Essentials\n\nAlice prefers VS Code.\n</info>",
-      },
-      { type: "text", text: "First" },
-    ]);
+    // The persisted block stays out: the console is a surface, not an actor.
+    expect(messages[0].content).toEqual([{ type: "text", text: "First" }]);
   });
 
   test("rehydration order matches injection-time order for the full personal-memory set", async () => {
@@ -1047,12 +1040,14 @@ describe("loadFromDb metadata injection rehydration", () => {
     expect(messages[2].content).toEqual([{ type: "text", text: "Tail" }]);
   });
 
-  test("ensureActorScopedHistory reloads when sourceChannel changes within the same trust class", async () => {
-    // Regression: cache invalidation previously keyed only on trust class.
-    // `loadFromDb` gates `memoryV2StaticBlock` rehydration on `sourceChannel`
-    // via `shouldExposePersonalMemory`, so a same-trust-class reuse from a
-    // different channel (e.g. internal `vellum` → remote channel) must
-    // re-run `loadFromDb` or stale personal-memory exposure persists.
+  test("ensureActorScopedHistory reloads when the actor's memory visibility changes", async () => {
+    // Reuse of a resident conversation by a different actor must re-run
+    // `loadFromDb`, or the incoming actor inherits the previous actor's
+    // transcript with its personal-memory blocks still spliced in.
+    //
+    // Driven by a trust-class change rather than a channel change: personal
+    // memory is keyed on the actor, so two channels at the same class are the
+    // same view and reloading between them would prove nothing.
     mockConversation = defaultConv();
     mockDbMessages = [
       {
@@ -1080,10 +1075,9 @@ describe("loadFromDb metadata injection rehydration", () => {
     ];
 
     const conversation = makeConversation();
-    // First load: internal channel, trusted_contact actor → personal memory
-    // exposed via `shouldExposePersonalMemory({sourceChannel: "vellum", ...})`.
+    // First load: guardian actor → personal memory exposed.
     conversation.setTrustContext({
-      trustClass: "trusted_contact",
+      trustClass: "guardian",
       sourceChannel: "vellum",
     });
     await conversation.ensureActorScopedHistory();
@@ -1095,8 +1089,8 @@ describe("loadFromDb metadata injection rehydration", () => {
       { type: "text", text: "First" },
     ]);
 
-    // Reuse with the same trust class but a remote channel. The cache must
-    // invalidate and trigger a reload that strips the personal-memory block.
+    // Reuse by a contact. The cache must invalidate and trigger a reload that
+    // strips the personal-memory block.
     conversation.setTrustContext({
       trustClass: "trusted_contact",
       sourceChannel: "telegram",

package/src/__tests__/conversation-pairing.test.ts

@@ -47,6 +47,14 @@ const getConversationMock = mock((id: string) => {
   return mockExistingConversations[id] ?? null;
 });
 
+const messagesInvalidated: string[] = [];
+
+mock.module("../runtime/sync/resource-sync-events.js", () => ({
+  publishConversationMessagesChanged: (conversationId: string) => {
+    messagesInvalidated.push(conversationId);
+  },
+}));
+
 mock.module("../persistence/conversation-crud.js", () => ({
   setConversationProcessingStartedAt: () => {},
   isConversationProcessing: () => false,
@@ -144,6 +152,7 @@ describe("pairDeliveryWithConversation", () => {
   beforeEach(() => {
     createConversationMock.mockClear();
     addMessageMock.mockClear();
+    messagesInvalidated.length = 0;
     getConversationMock.mockClear();
     getBindingByChannelChatMock.mockClear();
     upsertOutboundBindingMock.mockClear();
@@ -870,6 +879,183 @@ describe("pairDeliveryWithConversation", () => {
     expect(addMessageMock).not.toHaveBeenCalled();
   });
 
+  // ── Passive default: body appended to the producing conversation ───
+  //
+  // The home feed points "Go to Conversation" at `sourceContextId`, so the
+  // body has to land there for that button to open something that contains
+  // the notification the user tapped.
+
+  test("passive vellum signal appends the body to the producing conversation", async () => {
+    mockExistingConversations["conv-producer"] = {
+      id: "conv-producer",
+      source: "schedule",
+      title: "Daily Briefing Delivery",
+    };
+    const signal = makeSignal({
+      requiresConversation: undefined,
+      sourceContextId: "conv-producer",
+    });
+    const copy = makeCopy({ body: "Daily Briefing for Tuesday." });
+
+    const result = await pairDeliveryWithConversation(
+      signal,
+      "vellum" as NotificationChannel,
+      copy,
+    );
+
+    expect(result.conversationId).toBe("conv-producer");
+    expect(result.messageId).toBe("msg-001");
+    expect(result.createdNewConversation).toBe(false);
+    expect(result.conversationFallbackUsed).toBe(false);
+    // Appending must never mint a sidebar entry.
+    expect(createConversationMock).not.toHaveBeenCalled();
+    expect(addMessageMock).toHaveBeenCalledTimes(1);
+    const [conversationId, role] = addMessageMock.mock.calls[0]!;
+    expect(conversationId).toBe("conv-producer");
+    expect(role).toBe("assistant");
+    // `addMessage` publishes the metadata tag alone, so a client holding this
+    // conversation open needs the messages tag to refetch the transcript.
+    expect(messagesInvalidated).toContain("conv-producer");
+  });
+
+  test("appends for a foreground producer the home feed will not mirror", async () => {
+    // `resolveHomeFeedMirror` declines a signal that is neither
+    // `assistant_tool`, nor flagged async-background, nor produced by a
+    // background-typed conversation, so no card is written for this one. The
+    // append is deliberately not gated on that: the vellum banner still
+    // deep-links to this conversation, and the client suppresses the banner
+    // entirely when the user is already viewing it, leaving the transcript as
+    // the only place the notification can land.
+    mockExistingConversations["conv-foreground"] = {
+      id: "conv-foreground",
+      source: "user",
+      title: "An ordinary chat",
+    };
+    const signal = makeSignal({
+      requiresConversation: undefined,
+      sourceChannel: "plugin",
+      sourceContextId: "conv-foreground",
+      attentionHints: {
+        requiresAction: false,
+        urgency: "medium",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+    const copy = makeCopy({ body: "Something you asked to watch changed." });
+
+    const result = await pairDeliveryWithConversation(
+      signal,
+      "vellum" as NotificationChannel,
+      copy,
+    );
+
+    expect(result.conversationId).toBe("conv-foreground");
+    expect(createConversationMock).not.toHaveBeenCalled();
+    expect(addMessageMock).toHaveBeenCalledTimes(1);
+    expect(messagesInvalidated).toContain("conv-foreground");
+  });
+
+  test("appended notification body skips indexing", async () => {
+    mockExistingConversations["conv-producer"] = {
+      id: "conv-producer",
+      source: "schedule",
+      title: null,
+    };
+    const signal = makeSignal({
+      requiresConversation: undefined,
+      sourceContextId: "conv-producer",
+    });
+
+    await pairDeliveryWithConversation(
+      signal,
+      "vellum" as NotificationChannel,
+      makeCopy(),
+    );
+
+    const options = addMessageMock.mock.calls[0]![3] as {
+      skipIndexing?: boolean;
+    };
+    expect(options.skipIndexing).toBe(true);
+  });
+
+  test("passive vellum signal appends regardless of the producing conversation's source", async () => {
+    // The reuse_existing branch requires a source match; appending to the
+    // producing conversation does not, since the row already exists and the
+    // feed links to it either way.
+    mockExistingConversations["conv-producer"] = {
+      id: "conv-producer",
+      source: "user",
+      title: null,
+    };
+    const signal = makeSignal({
+      requiresConversation: undefined,
+      sourceContextId: "conv-producer",
+      conversationMetadata: { source: "notification" },
+    });
+
+    const result = await pairDeliveryWithConversation(
+      signal,
+      "vellum" as NotificationChannel,
+      makeCopy(),
+    );
+
+    expect(result.conversationId).toBe("conv-producer");
+    expect(createConversationMock).not.toHaveBeenCalled();
+  });
+
+  test("passive vellum signal with a sentinel sourceContextId appends nothing", async () => {
+    // Producers pass job ids, call session ids and `access-req-*` strings
+    // here. Those resolve to no row, which matches the feed hiding the button.
+    const signal = makeSignal({
+      requiresConversation: undefined,
+      sourceContextId: "job-1234",
+    });
+
+    const result = await pairDeliveryWithConversation(
+      signal,
+      "vellum" as NotificationChannel,
+      makeCopy(),
+    );
+
+    expect(result.conversationId).toBeNull();
+    expect(result.messageId).toBeNull();
+    expect(createConversationMock).not.toHaveBeenCalled();
+    expect(addMessageMock).not.toHaveBeenCalled();
+  });
+
+  test("passive vellum signal appends to the producer, not the reuse_existing target", async () => {
+    mockExistingConversations["conv-producer"] = {
+      id: "conv-producer",
+      source: "schedule",
+      title: null,
+    };
+    mockExistingConversations["conv-hinted"] = {
+      id: "conv-hinted",
+      source: "notification",
+      title: null,
+    };
+    const signal = makeSignal({
+      requiresConversation: undefined,
+      sourceContextId: "conv-producer",
+    });
+    const conversationAction: ConversationAction = {
+      action: "reuse_existing",
+      conversationId: "conv-hinted",
+    };
+
+    const result = await pairDeliveryWithConversation(
+      signal,
+      "vellum" as NotificationChannel,
+      makeCopy(),
+      { conversationAction },
+    );
+
+    expect(result.conversationId).toBe("conv-producer");
+    expect(addMessageMock).toHaveBeenCalledTimes(1);
+    expect(addMessageMock.mock.calls[0]![0]).toBe("conv-producer");
+  });
+
   // ── conversationMetadata.conversationType override ─────────────────
 
   test("uses conversationMetadata.conversationType when set, overriding channel strategy", async () => {