@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/runtime/local-actor-identity.ts

@@ -14,6 +14,11 @@
 import type { ChannelId } from "../channels/types.js";
 import { isHttpAuthDisabled } from "../config/env.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+  peekCachedGuardianDelivery,
+} from "../contacts/guardian-delivery-reader.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { getLogger } from "../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
@@ -45,13 +50,48 @@ export function buildLocalAuthContext(conversationId: string): AuthContext {
 }
 
 /**
- * Look up the local vellum guardian's principalId from the contacts table.
+ * Resolve the local vellum guardian's principalId from the gateway.
  *
- * Returns `undefined` when no vellum guardian binding exists (e.g. fresh
- * install before bootstrap). Callers should treat that case as
+ * The gateway owns guardian binding; this reads it through the cached
+ * `getGuardianDelivery` reader (PR-3 TTL + single-flight) so hot paths don't
+ * storm the IPC. Falls back to the local contacts table for the bootstrap /
+ * first-run window where the gateway has no guardian yet or is unreachable
+ * (the reader returns `null`).
+ *
+ * Returns `undefined` when no vellum guardian binding exists in either source
+ * (e.g. fresh install before bootstrap). Callers should treat that case as
  * "not yet available" and either fall back or proceed without a principalId.
  */
-export function findLocalGuardianPrincipalId(): string | undefined {
+export async function findLocalGuardianPrincipalId(): Promise<
+  string | undefined
+> {
+  const list = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (list) {
+    const principalId = guardianForChannel(list, "vellum")?.principalId;
+    if (principalId) return principalId;
+  }
+
+  return findLocalGuardianPrincipalIdFromStore();
+}
+
+/**
+ * Synchronous read of the vellum guardian's principalId for paths that cannot
+ * await {@link findLocalGuardianPrincipalId} — namely the SSE eager-subscribe
+ * path (`events-routes`), which registers before the stream is created.
+ *
+ * Reads the same gateway-owned binding as the async path via a sync, IO-free
+ * snapshot of the guardian-delivery cache (kept fresh by the async hot paths
+ * and event-driven invalidation), so SSE registers the SAME principal the
+ * send/result routes resolve. Falls back to the local store when the cache is
+ * cold — the same fallback the async path lands on during bootstrap.
+ */
+export function findLocalGuardianPrincipalIdFromStore(): string | undefined {
+  const cached = peekCachedGuardianDelivery({ channelTypes: ["vellum"] });
+  if (cached) {
+    const principalId = guardianForChannel(cached, "vellum")?.principalId;
+    if (principalId) return principalId;
+  }
+
   return findGuardianForChannel("vellum")?.contact.principalId ?? undefined;
 }
 
@@ -76,12 +116,35 @@ export function findLocalGuardianPrincipalId(): string | undefined {
  * yet (e.g. fresh install before bootstrap); callers must treat this the
  * same as a missing principal.
  */
-export function resolveActorPrincipalIdForLocalGuardian(
+export async function resolveActorPrincipalIdForLocalGuardian(
+  rawHeader: string | undefined,
+): Promise<string | undefined> {
+  if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) return rawHeader;
+
+  const guardianPrincipalId = await findLocalGuardianPrincipalId();
+  if (guardianPrincipalId) return guardianPrincipalId;
+
+  log.warn(
+    "dev-bypass actor principal received but no vellum guardian binding found; returning undefined",
+  );
+  return undefined;
+}
+
+/**
+ * Synchronous variant of {@link resolveActorPrincipalIdForLocalGuardian} for
+ * the SSE eager-subscribe path, which registers before the response stream is
+ * created and cannot await. Resolves the guardian from the IO-free gateway
+ * cache snapshot first (same source the async path reads), falling back to the
+ * local store when the cache is cold — so SSE registers the SAME principal the
+ * send/result routes resolve and host-proxy targeting matches the same-user
+ * client even when the local contact row is stale.
+ */
+export function resolveActorPrincipalIdForLocalGuardianSync(
   rawHeader: string | undefined,
 ): string | undefined {
   if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) return rawHeader;
 
-  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  const guardianPrincipalId = findLocalGuardianPrincipalIdFromStore();
   if (guardianPrincipalId) return guardianPrincipalId;
 
   log.warn(
@@ -102,12 +165,12 @@ export function resolveActorPrincipalIdForLocalGuardian(
  * bootstrap), falls back to a minimal guardian context so the local
  * user is not incorrectly denied.
  */
-export function resolveLocalTrustContext(
+export async function resolveLocalTrustContext(
   sourceChannel: ChannelId = "vellum",
-): TrustContext {
+): Promise<TrustContext> {
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
 
-  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  const guardianPrincipalId = await findLocalGuardianPrincipalId();
   if (guardianPrincipalId) {
     const trustCtx = resolveTrustContext({
       assistantId,
@@ -139,10 +202,12 @@ export function resolveLocalTrustContext(
  * downstream code to resolve guardian context using the same
  * `authContext.actorPrincipalId` path as HTTP sessions.
  */
-export function resolveLocalAuthContext(conversationId: string): AuthContext {
+export async function resolveLocalAuthContext(
+  conversationId: string,
+): Promise<AuthContext> {
   const authContext = buildLocalAuthContext(conversationId);
 
-  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  const guardianPrincipalId = await findLocalGuardianPrincipalId();
   if (guardianPrincipalId) {
     return { ...authContext, actorPrincipalId: guardianPrincipalId };
   }

package/src/runtime/local-principal-trust.ts

@@ -0,0 +1,52 @@
+/**
+ * Derives a local principal's {@link TrustContext} from the gateway guardian
+ * binding. Fails closed to unknown on a missing or null read.
+ */
+
+import type { ChannelId } from "../channels/types.js";
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
+import type { TrustContext } from "../daemon/trust-context.js";
+import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
+
+export interface ResolveLocalPrincipalTrustInput {
+  actorPrincipalId: string;
+  sourceChannel: ChannelId;
+  conversationExternalId: string;
+}
+
+/** Guardian match → guardian ctx; miss or null read → unknown (fail closed). */
+export async function resolveLocalPrincipalTrustContext(
+  input: ResolveLocalPrincipalTrustInput,
+): Promise<TrustContext> {
+  const unknownContext: TrustContext = {
+    sourceChannel: input.sourceChannel,
+    trustClass: "unknown",
+    requesterExternalUserId: input.actorPrincipalId,
+    requesterChatId: input.conversationExternalId,
+  };
+
+  // Fail closed: a null read means the gateway is unreachable — never grant
+  // guardian on a miss.
+  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!guardians) return unknownContext;
+
+  const guardian = guardians.find(
+    (g) => g.principalId === input.actorPrincipalId,
+  );
+  if (!guardian) return unknownContext;
+
+  return {
+    sourceChannel: input.sourceChannel,
+    trustClass: "guardian",
+    guardianChatId: guardian.externalChatId ?? input.conversationExternalId,
+    guardianExternalUserId:
+      canonicalizeInboundIdentity(input.sourceChannel, guardian.address) ??
+      undefined,
+    guardianPrincipalId: guardian.principalId ?? undefined,
+    // Mirror toTrustContext: with no username the requester identifier is the
+    // canonical sender id, which for a vellum principal is actorPrincipalId.
+    requesterIdentifier: input.actorPrincipalId,
+    requesterExternalUserId: input.actorPrincipalId,
+    requesterChatId: input.conversationExternalId,
+  };
+}

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

@@ -119,5 +119,8 @@ describe("streamExportVBundle — descriptor lifecycle", () => {
       // incidental descriptors (temp output file already cleaned up, jitter).
       expect(delta).toBeLessThan(8);
     },
+    // Two full exports of a multi-megabyte workspace (hash pass + tar pass each)
+    // do real disk I/O; the default 5s budget is tight under loaded CI runners.
+    30_000,
   );
 });

package/src/runtime/pending-interactions.ts

@@ -229,6 +229,15 @@ export function getByConversation(
  * /v1/host-browser-result, /v1/host-app-control-result, or
  * /v1/host-transfer-result after completing the operation, get a 404, and the
  * proxy timer would fire with a spurious timeout error.
+ *
+ * `question` interactions are also skipped: a new message supersedes an open
+ * ask_question by steering to it (see the enqueue path in
+ * conversation-routes.ts), which aborts the parked turn and settles the
+ * question via its abort signal. Clearing the entry here instead would drop it
+ * without settling the prompt's Promise (questions carry no `rpcResolve`
+ * fallback like secrets do) and would strip the steer of the entry it needs to
+ * fire — which can co-occur with a confirmation, since one model response can
+ * open both tools concurrently.
  */
 export function removeByConversation(
   conversationId: string,
@@ -244,7 +253,8 @@ export function removeByConversation(
       interaction.kind !== "host_browser" &&
       interaction.kind !== "host_app_control" &&
       interaction.kind !== "host_transfer" &&
-      interaction.kind !== "acp_confirmation"
+      interaction.kind !== "acp_confirmation" &&
+      interaction.kind !== "question"
     ) {
       // resolve() clears the stored timer and detaches abort listeners.
       resolve(requestId, state);

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

@@ -133,7 +133,7 @@ const { ROUTES } = await import("../acp-routes.js");
 const { _resetAdapterInstallCacheForTests } =
   await import("../../../acp/auto-install.js");
 
-initializeDb();
+await initializeDb();
 
 afterAll(() => {
   which.restore();

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

@@ -39,7 +39,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "../types.js";
 // DB bootstrap
 // ---------------------------------------------------------------------------
 
-initializeDb();
+await initializeDb();
 
 // ---------------------------------------------------------------------------
 // Helpers

package/src/runtime/routes/__tests__/channel-verification-revoke.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for the verification-revoke route relay.
+ *
+ * The revoke route downgrades the channel's ACL status through the gateway
+ * (source of truth) via `ipcCallPersistent("mark_channel_revoked", ...)` while
+ * keeping session teardown (`cancelOutbound`, `revokePendingSessions`)
+ * assistant-side. The gateway enforces the guardian guard; a rejected guardian
+ * downgrade surfaces here as a relayed IpcCallError.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
+
+type IpcCall = { method: string; params?: Record<string, unknown> };
+
+let ipcCalls: IpcCall[] = [];
+let ipcError: Error | undefined;
+
+const ipcCallPersistentMock = mock(
+  async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (ipcError) throw ipcError;
+    return {
+      ok: true,
+      didWrite: true,
+      channel: {
+        id: (params?.contactChannelId as string) ?? "ch1",
+        contactId: "c1",
+        type: "telegram",
+        address: "addr",
+        status: "revoked",
+        revokedReason: (params?.reason as string) ?? null,
+      },
+    };
+  },
+);
+
+const actualGatewayClient = await import("../../../ipc/gateway-client.js");
+mock.module("../../../ipc/gateway-client.js", () => ({
+  ...actualGatewayClient,
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
+
+// Session teardown — assert these still run locally on every revoke.
+const cancelOutboundMock = mock((_args: { channel: string }) => {});
+const actualOutboundActions = await import(
+  "../../verification-outbound-actions.js"
+);
+mock.module("../../verification-outbound-actions.js", () => ({
+  ...actualOutboundActions,
+  cancelOutbound: cancelOutboundMock,
+}));
+
+const revokePendingSessionsMock = mock((_channel: string) => {});
+const revokeBindingMock = mock((_assistantId: string, _channel: string) => {
+  revokeGuardianBindingMock();
+  return true;
+});
+let guardianBinding:
+  | {
+      guardianExternalUserId: string;
+      guardianDeliveryChatId?: string;
+    }
+  | null = null;
+const actualVerificationService = await import(
+  "../../channel-verification-service.js"
+);
+mock.module("../../channel-verification-service.js", () => ({
+  ...actualVerificationService,
+  revokePendingSessions: revokePendingSessionsMock,
+  revokeBinding: revokeBindingMock,
+  getGuardianBinding: mock(() => guardianBinding),
+}));
+
+// Contact-store lookup that resolves the guardian's channel to downgrade.
+let contactChannel: { id: string; status: string } | null = null;
+const actualContactStore = await import("../../../contacts/contact-store.js");
+mock.module("../../../contacts/contact-store.js", () => ({
+  ...actualContactStore,
+  findContactChannel: mock(() =>
+    contactChannel ? { channel: contactChannel, contact: { id: "c1" } } : null,
+  ),
+}));
+
+// Guard: the contact-channel ACL write moves to the gateway relay and must
+// never run locally. The assistant-owned guardian-binding teardown
+// (revokeGuardianBinding) still runs locally — assert it is invoked.
+const localAclWrite = mock(() => {
+  throw new Error("local ACL write must not happen on relayed revoke");
+});
+const revokeGuardianBindingMock = mock(() => true);
+const actualContactsWrite = await import("../../../contacts/contacts-write.js");
+mock.module("../../../contacts/contacts-write.js", () => ({
+  ...actualContactsWrite,
+  revokeMember: localAclWrite,
+  revokeGuardianBinding: revokeGuardianBindingMock,
+}));
+
+// Contact-change invalidation — emitted explicitly on relay success so open
+// client views stop showing the channel as active (the gateway dual-write to
+// "revoked" precedes binding teardown, so revokeGuardianBinding no longer
+// fires it).
+const emitContactChangeMock = mock(() => {});
+const actualContactEvents = await import("../../../contacts/contact-events.js");
+mock.module("../../../contacts/contact-events.js", () => ({
+  ...actualContactEvents,
+  emitContactChange: emitContactChangeMock,
+}));
+
+const { ROUTES } = await import("../channel-verification-routes.js");
+
+const revokeHandler = ROUTES.find(
+  (r) => r.operationId === "channel_verification_sessions_revoke",
+)!.handler;
+
+describe("verification revoke relay", () => {
+  beforeEach(() => {
+    ipcCalls = [];
+    ipcError = undefined;
+    guardianBinding = {
+      guardianExternalUserId: "guardian-user",
+      guardianDeliveryChatId: "chat-1",
+    };
+    contactChannel = { id: "ch1", status: "active" };
+    ipcCallPersistentMock.mockClear();
+    cancelOutboundMock.mockClear();
+    revokePendingSessionsMock.mockClear();
+    revokeBindingMock.mockClear();
+    revokeGuardianBindingMock.mockClear();
+    localAclWrite.mockClear();
+    emitContactChangeMock.mockClear();
+  });
+
+  test("relays the downgrade outcome to the gateway and tears down sessions locally", async () => {
+    const result = (await revokeHandler({
+      body: { channel: "telegram" },
+    })) as { success: boolean; bound: boolean; channel: string };
+
+    // ACL downgrade relayed to the gateway (source of truth).
+    expect(ipcCalls).toEqual([
+      {
+        method: "mark_channel_revoked",
+        params: {
+          contactChannelId: "ch1",
+          reason: "guardian_binding_revoked",
+        },
+      },
+    ]);
+
+    // Session teardown stays assistant-side.
+    expect(cancelOutboundMock).toHaveBeenCalledTimes(1);
+    expect(revokePendingSessionsMock).toHaveBeenCalledTimes(1);
+
+    // Assistant-owned guardian binding torn down locally.
+    expect(revokeBindingMock).toHaveBeenCalledTimes(1);
+    expect(revokeGuardianBindingMock).toHaveBeenCalledTimes(1);
+
+    // The contact-channel ACL write does not fall back to the assistant.
+    expect(localAclWrite).not.toHaveBeenCalled();
+
+    // Invalidation emitted explicitly on relay success: the gateway dual-write
+    // to "revoked" precedes binding teardown, so revokeGuardianBinding's own
+    // emit no longer fires.
+    expect(emitContactChangeMock).toHaveBeenCalledTimes(1);
+
+    expect(result.success).toBe(true);
+    expect(result.bound).toBe(false);
+  });
+
+  test("emits the invalidation even when the gateway dual-write already revoked the channel", async () => {
+    // Simulate the gateway having dual-written the assistant row to "revoked"
+    // before binding teardown: findGuardianForChannel (active-only) now finds
+    // nothing, so revokeGuardianBinding is a no-op and never emits.
+    revokeGuardianBindingMock.mockImplementationOnce(() => false);
+
+    await revokeHandler({ body: { channel: "telegram" } });
+
+    expect(ipcCalls).toHaveLength(1);
+    expect(emitContactChangeMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("malformed gateway response surfaces as an error", async () => {
+    // Deliberately malformed shape: must fail schema validation, not pass.
+    ipcCallPersistentMock.mockImplementationOnce(
+      async () => ({ ok: "nope" }) as never,
+    );
+
+    let thrown: Error | undefined;
+    try {
+      await revokeHandler({ body: { channel: "telegram" } });
+    } catch (err) {
+      thrown = err as Error;
+    }
+
+    expect(thrown).toBeDefined();
+    // Invalidation must not fire when the relay response is invalid.
+    expect(emitContactChangeMock).not.toHaveBeenCalled();
+    expect(revokeBindingMock).not.toHaveBeenCalled();
+  });
+
+  test("ok: false gateway response surfaces as an error", async () => {
+    ipcCallPersistentMock.mockImplementationOnce(async (_m, params) => ({
+      ok: false,
+      didWrite: false,
+      channel: {
+        id: (params?.contactChannelId as string) ?? "ch1",
+        contactId: "c1",
+        type: "telegram",
+        address: "addr",
+        status: "active",
+        revokedReason: "still_active",
+      },
+    }));
+
+    let thrown: Error | undefined;
+    try {
+      await revokeHandler({ body: { channel: "telegram" } });
+    } catch (err) {
+      thrown = err as Error;
+    }
+
+    expect(thrown).toBeDefined();
+    expect(emitContactChangeMock).not.toHaveBeenCalled();
+    expect(revokeBindingMock).not.toHaveBeenCalled();
+  });
+
+  test("guardian guard rejection from the gateway surfaces as an error", async () => {
+    ipcError = new IpcCallError("Cannot downgrade a guardian channel.", {
+      statusCode: 409,
+      errorCode: "CONFLICT",
+    });
+
+    let thrown: { statusCode?: number; message: string } | undefined;
+    try {
+      await revokeHandler({ body: { channel: "telegram" } });
+    } catch (err) {
+      thrown = err as { statusCode?: number; message: string };
+    }
+
+    expect(thrown).toBeDefined();
+    expect(thrown!.statusCode).toBe(409);
+    // Session teardown ran before the relay rejected; the binding teardown
+    // does not run when the gateway refuses the downgrade.
+    expect(cancelOutboundMock).toHaveBeenCalledTimes(1);
+    expect(revokePendingSessionsMock).toHaveBeenCalledTimes(1);
+    expect(revokeBindingMock).not.toHaveBeenCalled();
+    expect(localAclWrite).not.toHaveBeenCalled();
+  });
+
+  test("no binding present: tears down sessions and skips the relay", async () => {
+    guardianBinding = null;
+
+    const result = (await revokeHandler({
+      body: { channel: "telegram" },
+    })) as { success: boolean; bound: boolean };
+
+    expect(ipcCalls).toEqual([]);
+    expect(cancelOutboundMock).toHaveBeenCalledTimes(1);
+    expect(revokePendingSessionsMock).toHaveBeenCalledTimes(1);
+    expect(revokeBindingMock).not.toHaveBeenCalled();
+    expect(result.success).toBe(true);
+    expect(result.bound).toBe(false);
+  });
+
+  test("skips the relay when the resolved channel is already revoked", async () => {
+    contactChannel = { id: "ch1", status: "revoked" };
+
+    await revokeHandler({ body: { channel: "telegram" } });
+
+    expect(ipcCalls).toEqual([]);
+    expect(cancelOutboundMock).toHaveBeenCalledTimes(1);
+    expect(revokePendingSessionsMock).toHaveBeenCalledTimes(1);
+    // Binding teardown still runs even when the channel is already revoked.
+    expect(revokeBindingMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/runtime/routes/__tests__/channel-verification-routes.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Tests for the trusted-contact branch of the channel-verification create
+ * route.
+ *
+ * Pins the invariant that the trusted-contact create path performs no
+ * assistant-side activation write (no `updateChannelStatus`): it only creates an
+ * outbound session and sends a code. The verified outcome flows exclusively
+ * through the inbound gateway code-match path, so it is never double-written.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const verifyTrustedContactCalls: Array<[string, string]> = [];
+let verifyTrustedContactImpl: (
+  contactChannelId: string,
+  assistantId: string,
+) => Promise<Record<string, unknown>> = async () => ({ success: true });
+
+const updateChannelStatusCalls: unknown[] = [];
+const ipcCalls: Array<[string, unknown]> = [];
+
+mock.module("../../../daemon/handlers/config-channels.js", () => ({
+  verifyTrustedContact: async (contactChannelId: string, assistantId: string) => {
+    verifyTrustedContactCalls.push([contactChannelId, assistantId]);
+    return verifyTrustedContactImpl(contactChannelId, assistantId);
+  },
+  createInboundChallenge: async () => ({ success: true }),
+  getVerificationStatus: () => ({ success: true }),
+  revokeVerificationForChannel: () => ({ success: true }),
+}));
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  updateChannelStatus: (...args: unknown[]) => {
+    updateChannelStatusCalls.push(args);
+    return null;
+  },
+}));
+
+mock.module("../../ipc/gateway-client.js", () => ({
+  ipcCallPersistent: async (method: string, params: unknown) => {
+    ipcCalls.push([method, params]);
+    return { ok: true, didWrite: true, channel: {} };
+  },
+}));
+
+import { handleCreateVerificationSession } from "../channel-verification-routes.js";
+import { ConflictError, TooManyRequestsError } from "../errors.js";
+
+beforeEach(() => {
+  verifyTrustedContactCalls.length = 0;
+  updateChannelStatusCalls.length = 0;
+  ipcCalls.length = 0;
+  verifyTrustedContactImpl = async () => ({ success: true });
+});
+
+describe("handleCreateVerificationSession — trusted_contact", () => {
+  test("sends the verification session without writing the activation outcome assistant-side", async () => {
+    verifyTrustedContactImpl = async () => ({
+      success: true,
+      verificationSessionId: "sess-1",
+      expiresAt: Date.now() + 600_000,
+      sendCount: 1,
+      channel: "phone",
+    });
+
+    const result = (await handleCreateVerificationSession({
+      body: { purpose: "trusted_contact", contactChannelId: "cc-1" },
+    })) as Record<string, unknown>;
+
+    expect(result.success).toBe(true);
+    expect(result.verificationSessionId).toBe("sess-1");
+    expect(verifyTrustedContactCalls).toEqual([["cc-1", expect.any(String)]]);
+
+    // No assistant-side activation outcome write on the create path — the
+    // outcome flows through the inbound gateway code-match path instead.
+    expect(updateChannelStatusCalls).toEqual([]);
+  });
+
+  test("does not double-write the outcome via the gateway relay on the create path", async () => {
+    verifyTrustedContactImpl = async () => ({
+      success: true,
+      verificationSessionId: "sess-2",
+      channel: "telegram",
+    });
+
+    await handleCreateVerificationSession({
+      body: { purpose: "trusted_contact", contactChannelId: "cc-2" },
+    });
+
+    // The activation outcome is owned by the inbound gateway path; the create
+    // path must not relay a `mark_channel_verified` write (no double-write).
+    expect(
+      ipcCalls.filter(([method]) => method === "mark_channel_verified"),
+    ).toEqual([]);
+  });
+
+  test("propagates an already-verified short-circuit as a ConflictError (no silent success)", async () => {
+    verifyTrustedContactImpl = async () => ({
+      success: false,
+      error: "already_verified",
+      message: "Channel is already verified",
+    });
+
+    await expect(
+      handleCreateVerificationSession({
+        body: { purpose: "trusted_contact", contactChannelId: "cc-3" },
+      }),
+    ).rejects.toBeInstanceOf(ConflictError);
+
+    expect(updateChannelStatusCalls).toEqual([]);
+  });
+
+  test("propagates a rate-limit failure rather than silently succeeding", async () => {
+    verifyTrustedContactImpl = async () => ({
+      success: false,
+      error: "rate_limited",
+      message: "Too many attempts",
+    });
+
+    await expect(
+      handleCreateVerificationSession({
+        body: { purpose: "trusted_contact", contactChannelId: "cc-4" },
+      }),
+    ).rejects.toBeInstanceOf(TooManyRequestsError);
+  });
+
+  test("a failure in the trusted-contact path propagates, never a silent success", async () => {
+    verifyTrustedContactImpl = async () => {
+      throw new Error("gateway relay failed");
+    };
+
+    await expect(
+      handleCreateVerificationSession({
+        body: { purpose: "trusted_contact", contactChannelId: "cc-5" },
+      }),
+    ).rejects.toThrow("gateway relay failed");
+
+    expect(updateChannelStatusCalls).toEqual([]);
+  });
+});