@vellumai/assistant 0.12.4-dev.202609232047.847daa9 → 0.12.4-dev.202609232115.73e8b74

package/docs/architecture/scheduling.md

@@ -94,11 +94,13 @@ sequenceDiagram
 
 The `enforceRoutingIntent()` step runs after the LLM produces a channel selection but before deterministic checks. It acts as a post-decision guard:
 
-| Intent           | Enforcement Rule                                                                                  |
-| ---------------- | ------------------------------------------------------------------------------------------------- |
-| `single_channel` | No override. The LLM's channel selection stands.                                                  |
-| `multi_channel`  | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels. |
-| `all_channels`   | Replace the LLM's selection with all connected channels.                                          |
+| Intent           | Enforcement Rule                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `single_channel` | Cap delivery to one channel: the signal's source channel when it is connected, otherwise the first channel the LLM selected. |
+| `multi_channel`  | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels.                            |
+| `all_channels`   | Replace the LLM's selection with all connected channels.                                                                     |
+
+A decision the LLM suppressed (`shouldNotify: false`) is left alone under every intent. A signal with no routing intent keeps the LLM's selection.
 
 When enforcement changes the decision, the updated `selectedChannels` and annotated `reasoningSummary` are re-persisted to `notification_decisions` so the audit trail reflects what was actually dispatched.
 

package/docs/guardian-request-flow.md

@@ -24,7 +24,7 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
   (generic actions[] + plainTextFallback)         resolveQuestionContext)
         │
         ▼ per-channel rendering ONLY
-  channel adapters                               (notifications/adapters/{telegram,slack,macos,platform},
+  channel adapters                               (notifications/adapters/{telegram,slack,discord,macos,platform},
   telegram: inline keyboard; slack: blocks;       vellum: conversation card via approval-card-builder)
   card deliveries recorded per channel            (guardian-delivery-recorder.ts → guardian_request_deliveries)
         │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.4-dev.202609232047.847daa9",
+  "version": "0.12.4-dev.202609232115.73e8b74",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/emit-signal-routing-intent.test.ts

@@ -359,6 +359,68 @@ describe("access-request vellum floor", () => {
     );
   });
 
+  test("an all_channels access request the decision engine suppressed still fans out", async () => {
+    evaluateSignalMock.mockResolvedValue({
+      shouldNotify: false,
+      selectedChannels: [],
+      reasoningSummary: "LLM suppressed",
+      renderedCopy: {},
+      dedupeKey: "dedupe-ar-email",
+      confidence: 0.9,
+      fallbackUsed: false,
+      persistedDecisionId: "dec-ar-email",
+    });
+    // The real enforcement leaves a suppressed decision alone and replaces
+    // the selection with every connected channel otherwise.
+    enforceRoutingIntentMock.mockImplementation(
+      (
+        decision: { shouldNotify: boolean; selectedChannels: string[] },
+        intent: string | undefined,
+        connected: string[],
+      ) =>
+        intent === "all_channels" && decision.shouldNotify
+          ? { ...decision, selectedChannels: [...connected] }
+          : decision,
+    );
+
+    await emitNotificationSignal({
+      sourceEventName: "ingress.access_request",
+      sourceChannel: "email",
+      sourceContextId: "access-req-email-stranger",
+      requiresConversation: true,
+      routingIntent: "all_channels",
+      attentionHints: {
+        requiresAction: true,
+        urgency: "high",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        requestId: "req-email",
+        requestCode: "EM12CD",
+        sourceChannel: "email",
+        conversationExternalId: "<thread-1@example.com>",
+        actorExternalId: "stranger@example.com",
+        actorDisplayName: null,
+        actorUsername: null,
+        senderIdentifier: "stranger@example.com",
+        guardianBindingChannel: null,
+        guardianResolutionSource: "vellum-anchor",
+        previousMemberStatus: null,
+        messagePreview: null,
+      },
+    });
+
+    const enforced = enforceRoutingIntentMock.mock.calls[0][0] as {
+      shouldNotify: boolean;
+    };
+    expect(enforced.shouldNotify).toBe(true);
+    const dispatched = dispatchDecisionMock.mock.calls[0][1] as {
+      selectedChannels: string[];
+    };
+    expect(dispatched.selectedChannels).toContain("vellum");
+  });
+
   test("re-adds vellum when single_channel routing enforcement strips it", async () => {
     evaluateSignalMock.mockResolvedValue({
       shouldNotify: true,

package/src/__tests__/introduction-card-resolver.test.ts

@@ -218,6 +218,29 @@ describe("introduction card decisions", () => {
     }
   });
 
+  test("handshake approval on an email sender is coerced to direct trust", async () => {
+    for (const action of ["approve_once", "verify_code"] as const) {
+      resetState();
+      const req = makeAccessRequest({ sourceChannel: "email" });
+
+      const result = await applyGuardianDecision({
+        requestId: req.id,
+        action,
+        actorContext: desktopGuardian(),
+      });
+
+      expect(result.applied).toBe(true);
+      // No code is minted: email has no route to deliver one to the sender.
+      expect(outcomesOfType("mint_outbound_session")).toHaveLength(0);
+      const activations = outcomesOfType("activate_member");
+      expect(activations).toHaveLength(1);
+      expect(activations[0].sourceChannel).toBe("email");
+      expect(activations[0].verifiedVia).toBe("manual_channel_claim");
+      // The reported and projected outcome is the trust that was applied.
+      expect(result.applied && result.decidedAction).toBe("trust");
+    }
+  });
+
   test("leave_unverified persists the sender as unverified and is silent (legacy reject path)", async () => {
     for (const action of ["leave_unverified", "reject"] as const) {
       resetState();
@@ -392,18 +415,40 @@ describe("introduction card decisions", () => {
 });
 
 describe("introductionOutcomeForAction", () => {
+  const slackStranger = {
+    sourceChannel: "slack",
+    requesterSignals: serializeRequesterSignals({ isStranger: true }) ?? null,
+  };
+
   test("folds the generic decision pair onto the introduction outcomes", () => {
     // `reject` and `leave_unverified` both park the contact at `unverified`;
     // `approve_once` starts the handshake. Introduction actions map to
     // themselves. Callers that must present the resolved outcome (the card
     // projection) rely on this so a `reject` park never reads as "Denied".
-    expect(introductionOutcomeForAction("reject")).toBe("leave_unverified");
-    expect(introductionOutcomeForAction("leave_unverified")).toBe(
-      "leave_unverified",
-    );
-    expect(introductionOutcomeForAction("approve_once")).toBe("verify_code");
-    expect(introductionOutcomeForAction("verify_code")).toBe("verify_code");
-    expect(introductionOutcomeForAction("trust")).toBe("trust");
-    expect(introductionOutcomeForAction("block")).toBe("block");
+    const outcome = (
+      action: Parameters<typeof introductionOutcomeForAction>[1],
+    ) => introductionOutcomeForAction(slackStranger, action);
+    expect(outcome("reject")).toBe("leave_unverified");
+    expect(outcome("leave_unverified")).toBe("leave_unverified");
+    expect(outcome("approve_once")).toBe("verify_code");
+    expect(outcome("verify_code")).toBe("verify_code");
+    expect(outcome("trust")).toBe("trust");
+    expect(outcome("block")).toBe("block");
+  });
+
+  test("a handshake approval resolves to trust where the handshake cannot complete", () => {
+    const email = { sourceChannel: "email", requesterSignals: null };
+    const bot = {
+      sourceChannel: "slack",
+      requesterSignals: serializeRequesterSignals({ isBot: true }) ?? null,
+    };
+    for (const request of [email, bot]) {
+      expect(introductionOutcomeForAction(request, "approve_once")).toBe(
+        "trust",
+      );
+      expect(introductionOutcomeForAction(request, "verify_code")).toBe(
+        "trust",
+      );
+    }
   });
 });

package/src/__tests__/non-member-access-request.test.ts

@@ -598,6 +598,54 @@ describe("access-request-helper unit tests", () => {
     expect(payload.guardianBindingChannel).toBe("vellum");
   });
 
+  test("an email access request routes to every channel the guardian is connected on", async () => {
+    const result = await notifyGuardianOfAccessRequest({
+      sourceChannel: "email",
+      conversationExternalId: "<thread-1@example.com>",
+      actorExternalId: "stranger@example.com",
+    });
+
+    expect(result.notified).toBe(true);
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].routingIntent).toBe("all_channels");
+  });
+
+  test("an admitted email sender's nudge keeps the default routing", async () => {
+    await maybeNotifyGuardianOfAdmittedContact({
+      sourceChannel: "email",
+      conversationExternalId: "<thread-2@example.com>",
+      actorExternalId: "admitted@example.com",
+    });
+
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].routingIntent).toBeUndefined();
+  });
+
+  test("a telegram access request with a telegram guardian stays on telegram", async () => {
+    seedGatewayGuardian({
+      channelType: "telegram",
+      address: "guardian-tg",
+      externalChatId: "tg-chat",
+      principalId: anchorPrincipalId,
+    });
+    createGuardianBinding({
+      channel: "telegram",
+      guardianExternalUserId: "guardian-tg",
+      guardianDeliveryChatId: "tg-chat",
+      guardianPrincipalId: anchorPrincipalId,
+      verifiedVia: "test",
+    });
+
+    await notifyGuardianOfAccessRequest({
+      sourceChannel: "telegram",
+      conversationExternalId: "chat-123",
+      actorExternalId: "unknown-user",
+    });
+
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].routingIntent).toBe("single_channel");
+  });
+
   test("notifyGuardianOfAccessRequest prefers source-channel binding over vellum anchor", async () => {
     // Both Telegram and voice bindings exist with the anchor principal
     seedGatewayGuardian({

package/src/__tests__/trusted-contact-inline-approval-integration.test.ts

@@ -1308,15 +1308,15 @@ describe("(g) access_request resolver: requester code delivery", () => {
     expect(verificationSent.length).toBe(1);
   });
 
-  test("off-channel approval on a channel with no deliverable callback (e.g. email) still records verification_sent", async () => {
-    // `email` has no deliver URL (resolveDeliverCallbackUrlForChannel returns
+  test("off-channel approval on a channel with no deliverable callback (e.g. a plugin channel) still records verification_sent", async () => {
+    // `plugin` has no deliver URL (resolveDeliverCallbackUrlForChannel returns
     // null), so the requester cannot be auto-notified here. The guardian still
     // receives the code inline, so the lifecycle transition must be recorded —
     // the emit must not be gated on requester deliverability.
     const req = createAccessRequest({
-      sourceChannel: "email",
-      requesterChatId: "requester@example.com",
-      sourceConversationId: "conv-access-email",
+      sourceChannel: "plugin",
+      requesterChatId: "plugin-requester-1",
+      sourceConversationId: "conv-access-plugin",
     });
 
     const result = await applyGuardianDecision({
@@ -1335,7 +1335,7 @@ describe("(g) access_request resolver: requester code delivery", () => {
     const replyText = result.applied ? result.resolverReplyText : undefined;
     expect(replyText).toContain("123456");
     const requesterDelivery = deliveredReplies.find(
-      (r) => r.payload.chatId === "requester@example.com",
+      (r) => r.payload.chatId === "plugin-requester-1",
     );
     expect(requesterDelivery).toBeUndefined();
 

package/src/approvals/guardian-decision-primitive.ts

@@ -529,12 +529,13 @@ export async function applyGuardianDecision(
   // never throws; the `.catch` is a defensive backstop.
   // For access requests the resolver folds the generic decision pair onto the
   // introduction outcomes (`reject` → `leave_unverified`, `approve_once` →
-  // `verify_code`), so the resolved card must reflect the OUTCOME, not the raw
+  // `verify_code`, or `trust` for a requester who cannot complete a code
+  // handshake), so the resolved card must reflect the OUTCOME, not the raw
   // button — otherwise a `reject` that actually parked the contact at
   // `unverified` would still render "Denied". Other kinds have no such mapping.
   const cardAction =
     request.kind === "access_request"
-      ? introductionOutcomeForAction(effectiveAction)
+      ? introductionOutcomeForAction(resolved, effectiveAction)
       : effectiveAction;
   void withdrawGuardianRequestCards({
     request: resolved,

package/src/approvals/guardian-request-resolvers.ts

@@ -46,6 +46,7 @@ import { deliverChannelReply } from "../runtime/gateway-client.js";
 import {
   introductionMode,
   parseRequesterSignals,
+  requesterCanCompleteHandshake,
   type RequesterIdentitySignals,
   resolveTrustBinding,
 } from "../runtime/introduction-policy.js";
@@ -619,20 +620,33 @@ const OUTCOME_BY_ACTION = {
 } as const satisfies Record<ApprovalAction, IntroductionOutcome>;
 
 /**
- * The introduction outcome a decision action resolves to for an access request.
- * The generic decision pair folds onto the card outcomes (`reject` →
- * `leave_unverified`, `approve_once` → `verify_code`); the introduction actions
- * map to themselves. Every outcome is itself an `ApprovalAction`, so a caller
- * that must reflect the resolved *outcome* rather than the raw button — the
- * resolved-card projection, so a `reject` that parked the contact at
- * `unverified` reads as the neutral "Left unverified" and not "Denied" — can
- * normalize through this. It does not apply the bot handshake→trust coercion,
- * which does not affect the park/deny distinction the card cares about.
+ * The introduction outcome a decision action resolves to for an access
+ * request. The generic decision pair folds onto the card outcomes (`reject` →
+ * `leave_unverified`, `approve_once` → `verify_code`) and the introduction
+ * actions map to themselves, except that a handshake approval on a requester
+ * who can never complete the handshake (a bot, an email sender) resolves to
+ * direct trust: the guardian's intent ("let them in") is unambiguous.
+ *
+ * The one derivation of the outcome: the resolver plans and follows through on
+ * it, and the decision primitive reports it (`decidedAction`) and projects it
+ * onto the resolved cards, so a `reject` that parked the contact reads as the
+ * neutral "Left unverified" and a coerced approval reads as the trust it was.
  */
 export function introductionOutcomeForAction(
+  request: Pick<GuardianRequestWire, "sourceChannel" | "requesterSignals">,
   action: ApprovalAction,
-): ApprovalAction {
-  return OUTCOME_BY_ACTION[action];
+): IntroductionOutcome {
+  const outcome = OUTCOME_BY_ACTION[action];
+  if (
+    outcome === "verify_code" &&
+    !requesterCanCompleteHandshake(
+      request.sourceChannel ?? undefined,
+      parseRequesterSignals(request.requesterSignals),
+    )
+  ) {
+    return "trust";
+  }
+  return outcome;
 }
 
 /** Derived access-request decision facts shared by `prepare` and `resolve`. */
@@ -675,15 +689,7 @@ function deriveAccessRequestDecision(
     requesterContactResult?.contact.displayName ?? null;
 
   const signals = parseRequesterSignals(request.requesterSignals);
-  let outcome: IntroductionOutcome = OUTCOME_BY_ACTION[action];
-
-  // A bot cannot return a verification code, so a handshake approval on a
-  // bot requester can never complete. Coerce it to direct trust — the
-  // guardian's intent ("let it in") is unambiguous. Logged once, in
-  // `prepare` (this derivation runs again in `resolve`).
-  if (outcome === "verify_code" && signals.isBot === true) {
-    outcome = "trust";
-  }
+  const outcome = introductionOutcomeForAction(request, action);
 
   return {
     channel,
@@ -885,8 +891,8 @@ async function notifyRequesterOfDenial(params: {
  * follow-through (requester/guardian notices, verification-code delivery
  * from the decide's `mintedSession`, lifecycle signals).
  *
- * A bot requester can never return a code, so handshake approvals are
- * coerced to direct trust.
+ * A requester who can never complete the handshake (a bot, an email
+ * sender) has handshake approvals coerced to direct trust.
  */
 const accessRequestResolver: GuardianRequestResolver = {
   kind: "access_request",
@@ -905,11 +911,12 @@ const accessRequestResolver: GuardianRequestResolver = {
     if (outcome !== OUTCOME_BY_ACTION[decision.action]) {
       log.info(
         {
-          event: "resolver_access_request_bot_coercion",
+          event: "resolver_access_request_trust_coercion",
           requestId: request.id,
           action: decision.action,
+          channel,
         },
-        "Access request resolver: handshake approval on a bot coerced to direct trust",
+        "Access request resolver: handshake approval coerced to direct trust (requester cannot complete a handshake)",
       );
     }
 

package/src/notifications/README.md

@@ -293,11 +293,11 @@ Schedules (both recurring and one-shot) carry optional routing metadata that con
 
 The `routing_intent` field on each `schedule_jobs` row specifies the desired channel coverage:
 
-| Intent           | Behavior                                              | When to use                                                         |
-| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
-| `single_channel` | Default LLM-driven routing (no override)              | Standard schedules where the decision engine picks the best channel |
-| `multi_channel`  | Ensures delivery on 2+ channels when 2+ are connected | Important schedules the user wants on both desktop and phone        |
-| `all_channels`   | Forces delivery on every connected channel            | Critical schedules that must reach the user everywhere              |
+| Intent           | Behavior                                              | When to use                                                  |
+| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+| `single_channel` | Delivers on exactly one channel                       | Schedules that should reach the user in one place            |
+| `multi_channel`  | Ensures delivery on 2+ channels when 2+ are connected | Important schedules the user wants on both desktop and phone |
+| `all_channels`   | Forces delivery on every connected channel            | Critical schedules that must reach the user everywhere       |
 
 The default is `all_channels`. Routing intent is persisted in the `schedule_jobs` table (`routing_intent` column) and carried through the notification signal as `routingIntent`.
 
@@ -325,7 +325,7 @@ The `enforceRoutingIntent()` function in `decision-engine.ts` runs after the LLM
 
 - **`all_channels`**: Replaces `selectedChannels` with all connected channels (from `getConnectedChannels()`).
 - **`multi_channel`**: If the LLM selected fewer than 2 channels but 2+ are connected, expands `selectedChannels` to at least two connected channels.
-- **`single_channel`**: No override -- the LLM's selection stands.
+- **`single_channel`**: Caps delivery to one channel: the signal's source channel when it is connected, otherwise the first channel the LLM selected. A signal with no routing intent keeps the LLM's selection.
 
 When enforcement changes the decision, the updated channel selection is re-persisted to the `notification_decisions` table so the stored decision matches what was actually dispatched. The `reasoningSummary` is annotated with the enforcement action (e.g. `[routing_intent=all_channels enforced: vellum, telegram]`).
 

package/src/notifications/emit-signal.ts

@@ -512,7 +512,22 @@ export async function emitNotificationSignal<TEventName extends string>(
     }
 
     // Step 2.5b: Enforce routing intent policy (fire-time guard).
-    // An exclusive allowlist already closed the channel set.
+    // An exclusive allowlist already closed the channel set. An access request
+    // routed to every channel is delivered even when the decision engine
+    // suppressed it (step 2.5c never lets one go undelivered), so it is made
+    // deliverable first: routing enforcement leaves a suppressed decision
+    // alone, which would leave the request on the in-app card alone.
+    if (
+      signal.sourceEventName === "ingress.access_request" &&
+      signal.routingIntent === "all_channels" &&
+      !decision.shouldNotify
+    ) {
+      decision = {
+        ...decision,
+        shouldNotify: true,
+        reasoningSummary: `${decision.reasoningSummary} (notify forced: access request routed to all channels)`,
+      };
+    }
     if (!exclusiveAllowlist) {
       decision = enforceRoutingIntent(
         decision,

package/src/runtime/access-request-helper.ts

@@ -326,14 +326,17 @@ export async function notifyGuardianOfAccessRequest(
   });
 
   let vellumDeliveryIdPromise: Promise<string | undefined> | undefined;
-  // When the access request originates from a text channel with
-  // notification delivery support (Slack, Telegram) and the guardian was
-  // resolved via a verified same-channel contact, route the notification
-  // only to that channel to reduce noise. Phone is excluded because it
-  // is not a deliverable notification channel.
-  // When the guardian was NOT verified on the source channel (e.g. resolved
-  // via vellum anchor), route to all channels so the guardian can see
-  // the request on desktop/other channels where they ARE verified.
+  // Where the card goes:
+  // - Slack or Telegram with the guardian verified on that same channel: only
+  //   that channel, where the card is answered in place.
+  // - Email, for a sender who was denied: every channel the guardian is
+  //   connected on. The card cannot be delivered or answered by email, and
+  //   the in-app copy alone is easy to miss for a guardian who handles
+  //   requests in a chat app. An admitted sender's nudge blocks nobody, so it
+  //   takes the default below.
+  // - Anywhere else: the channels the decision engine selects. The in-app
+  //   card is always among them (`emit-signal.ts` forces it for access
+  //   requests).
   const TEXT_CHANNELS_WITH_DELIVERY: ReadonlySet<string> = new Set([
     "slack",
     "telegram",
@@ -355,7 +358,11 @@ export async function notifyGuardianOfAccessRequest(
     sourceContextId: `access-req-${sourceChannel}-${actorExternalId}`,
     requiresConversation: true,
     ...(vellumConversationAffinity ?? {}),
-    ...(sameChannelOnly ? { routingIntent: "single_channel" as const } : {}),
+    ...(sameChannelOnly
+      ? { routingIntent: "single_channel" as const }
+      : sourceChannel === "email" && trigger === "denied"
+        ? { routingIntent: "all_channels" as const }
+        : {}),
     attentionHints: {
       requiresAction: true,
       // An admitted sender is already conversing — the guardian should

package/src/runtime/introduction-policy.test.ts

@@ -6,6 +6,7 @@ import {
   isHandshakeOffered,
   isWorkspaceVouchedIdentity,
   parseRequesterSignals,
+  requesterCanCompleteHandshake,
   resolveTrustBinding,
   serializeRequesterSignals,
   VERIFIED_VIA_CHANNEL_CLAIM,
@@ -117,13 +118,18 @@ describe("handshake policy", () => {
     expect(isHandshakeOffered("phone", {})).toBe(false);
   });
 
+  test("not offered on email: the code has no route to the sender", () => {
+    expect(requesterCanCompleteHandshake("email", {})).toBe(false);
+    expect(isHandshakeOffered("email", {})).toBe(false);
+    expect(isHandshakeOffered("email", { isStranger: true })).toBe(false);
+  });
+
   test("leads for externals, strangers, and identity-less channels", () => {
     expect(isHandshakeOffered("slack", { isStranger: true })).toBe(true);
     expect(isHandshakeOffered("slack", { isRestricted: true })).toBe(true);
     // Unknown signals (users.info failure) fail toward the handshake.
     expect(isHandshakeOffered("slack", {})).toBe(true);
     expect(isHandshakeOffered("telegram", {})).toBe(true);
-    expect(isHandshakeOffered("email", {})).toBe(true);
   });
 });
 
@@ -145,6 +151,16 @@ describe("introduction action lists", () => {
     }
   });
 
+  test("email sender: direct trust leads, no code option", () => {
+    const actions = buildIntroductionActions("email", {});
+    expect(actions.map((a) => a.id)).toEqual([
+      "trust",
+      "leave_unverified",
+      "block",
+    ]);
+    expect(actions[0].label).toBe("Trust");
+  });
+
   test("external: handshake leads, trust is 'Trust anyway'", () => {
     const actions = buildIntroductionActions("slack", { isStranger: true });
     expect(actions.map((a) => a.id)).toEqual([

package/src/runtime/introduction-policy.ts

@@ -198,11 +198,27 @@ export interface IntroductionActionOption {
   emphasis: GuardianActionEmphasis;
 }
 
+/**
+ * Whether this requester could ever complete the code handshake.
+ *
+ * A bot cannot return a code. An email sender cannot be sent one: approval
+ * has no delivery route for email, so the guardian would have to pass the
+ * code on outside the product, and the address the code would prove is
+ * already checked on every message (a `From:` that fails DMARC/DKIM reaches
+ * the runtime as a stranger).
+ */
+export function requesterCanCompleteHandshake(
+  sourceChannel: string | undefined,
+  signals: RequesterIdentitySignals,
+): boolean {
+  return signals.isBot !== true && sourceChannel !== "email";
+}
+
 /**
  * Whether the verification handshake is offered for this requester.
  *
  * The handshake is the exception, not the default:
- * - never for bots/integrations — a bot cannot return a code;
+ * - never where it cannot complete (see {@link requesterCanCompleteHandshake});
  * - not for workspace-vouched identities — the platform already
  *   authenticated them;
  * - not on voice — a phone call has no text handshake path;
@@ -212,7 +228,7 @@ export function isHandshakeOffered(
   sourceChannel: string | undefined,
   signals: RequesterIdentitySignals,
 ): boolean {
-  if (signals.isBot === true) {
+  if (!requesterCanCompleteHandshake(sourceChannel, signals)) {
     return false;
   }
   if (sourceChannel === "phone") {
@@ -225,15 +241,16 @@ export function isHandshakeOffered(
  * Build the ordered introduction-card action list for a requester. The first
  * action is the emphasized default:
  *
- *   workspace member / bot / voice:  [ Trust ] [ Leave unverified ] [ Block ]
- *   external / stranger / guest:     [ Verify with a code ] [ Trust anyway ]
- *                                    [ Leave unverified ] [ Block ]
+ *   workspace member / bot / voice / email:  [ Trust ] [ Leave unverified ] [ Block ]
+ *   external / stranger / guest:             [ Verify with a code ] [ Trust anyway ]
+ *                                            [ Leave unverified ] [ Block ]
  *
  * `leave_unverified` is the silent "park" outcome: it leaves the sender an
  * `unverified` contact and never notifies the requester. It is NOT a guaranteed
  * keep-out — an `unverified` contact is still admitted under the permissive
  * admission floors (`any_contact`, `strangers`); the hard keep-out is `block`
- * (→ revoked). The code option is NEVER rendered for a bot.
+ * (→ revoked). The code option is never rendered where the handshake cannot
+ * complete (a bot, an email sender; see {@link requesterCanCompleteHandshake}).
  */
 export function buildIntroductionActions(
   sourceChannel: string | undefined,