@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/runtime/routes/inbound-stages/acl-enforcement.test.ts

@@ -19,14 +19,28 @@ mock.module("../../../util/logger.js", () => ({
 }));
 
 // Track contact-store reads to prove findContactChannel is NOT used on the
-// verdict path. findGuardianForChannel is still called by resolveGuardianLabel.
+// verdict path.
 const findContactChannelCalls: unknown[] = [];
 mock.module("../../../contacts/contact-store.js", () => ({
   findContactChannel: (params: unknown) => {
     findContactChannelCalls.push(params);
     return null;
   },
-  findGuardianForChannel: () => null,
+}));
+
+// resolveGuardianLabel resolves the guardian via the gateway delivery reader.
+let guardianDeliveryList: Array<Record<string, unknown>> = [];
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: async () => guardianDeliveryList,
+  guardianForChannel: (
+    list: Array<Record<string, unknown>>,
+    channelType: string,
+  ) => list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+mock.module("../../../prompts/user-reference.js", () => ({
+  resolveGuardianName: (displayName?: string | null) =>
+    displayName && displayName.trim().length > 0 ? displayName.trim() : "my human",
 }));
 
 const deliverReplyCalls: Array<{ url: string; payload: unknown }> = [];
@@ -126,6 +140,7 @@ beforeEach(() => {
   deliverReplyCalls.length = 0;
   accessRequestCalls.length = 0;
   inviteTokenForTest = undefined;
+  guardianDeliveryList = [];
 });
 
 afterEach(() => {
@@ -140,8 +155,8 @@ describe("enforceIngressAcl — verdict-sourced member resolution", () => {
 
     expect(result.earlyResponse).toBeUndefined();
     expect(result.resolvedMember).not.toBeNull();
-    expect(result.resolvedMember!.channel.status).toBe("active");
-    expect(result.resolvedMember!.channel.policy).toBe("allow");
+    expect(result.resolvedMember!.status).toBe("active");
+    expect(result.resolvedMember!.policy).toBe("allow");
     // Member came from the verdict, never the local contact store.
     expect(findContactChannelCalls.length).toBe(0);
   });
@@ -156,7 +171,8 @@ describe("enforceIngressAcl — verdict-sourced member resolution", () => {
     );
 
     expect(result.earlyResponse).toBeUndefined();
-    expect(result.resolvedMember!.contact.role).toBe("guardian");
+    expect(result.resolvedMember).not.toBeNull();
+    expect(result.resolvedMember!.status).toBe("active");
     expect(findContactChannelCalls.length).toBe(0);
   });
 });
@@ -249,6 +265,82 @@ describe("enforceIngressAcl — fail-closed on absent verdict", () => {
   });
 });
 
+describe("enforceIngressAcl — fail-closed on resolutionFailed verdict", () => {
+  test("resolutionFailed verdict → not_a_member deny, does not flow to intercepts", async () => {
+    inviteTokenForTest = "iv_token123";
+    const result = await enforceIngressAcl(
+      makeParams({
+        sourceMetadata: withVerdict({
+          trustClass: "unknown",
+          canonicalSenderId: "sender-1",
+          resolutionFailed: true,
+        }),
+        effectiveAdmissionPolicy: "strangers",
+      }),
+    );
+
+    expect(result.earlyResponse).toBeDefined();
+    expect(result.earlyResponse!.reason).toBe("not_a_member");
+    expect(result.resolvedMember).toBeNull();
+    // Distinct from a stranger: no invite redemption, onboarding, or
+    // guardian notification fires.
+    expect(result.earlyResponse!.inviteRedemption).toBeUndefined();
+    expect(deliverReplyCalls.length).toBe(0);
+    expect(accessRequestCalls.length).toBe(0);
+    expect(findContactChannelCalls.length).toBe(0);
+  });
+
+  test("real unknown stranger (no resolutionFailed) still redeems via intercept", async () => {
+    inviteTokenForTest = "iv_token123";
+    const result = await enforceIngressAcl(
+      makeParams({
+        sourceMetadata: withVerdict({
+          trustClass: "unknown",
+          canonicalSenderId: "sender-1",
+        }),
+      }),
+    );
+
+    expect(result.earlyResponse!.inviteRedemption).toBe("redeemed");
+    expect(result.resolvedMember).toBeNull();
+  });
+});
+
+describe("enforceIngressAcl — deny copy names the gateway guardian", () => {
+  test("non-member deny reply uses the guardian displayName from the gateway list", async () => {
+    guardianDeliveryList = [
+      {
+        channelType: "vellum",
+        contactId: "c-1",
+        principalId: "p-anchor",
+        displayName: "Alice Guardian",
+        address: "p-anchor",
+        status: "active",
+      },
+    ];
+
+    const result = await enforceIngressAcl(
+      makeParams({
+        sourceMetadata: withVerdict({
+          trustClass: "unknown",
+          canonicalSenderId: "stranger-1",
+        }),
+      }),
+    );
+
+    expect(result.earlyResponse!.reason).toBe("not_a_member");
+    const denyReply = deliverReplyCalls.find((c) =>
+      String((c.payload as { text?: string }).text ?? "").includes(
+        "tried talking to me",
+      ),
+    );
+    expect(denyReply).toBeDefined();
+    expect((denyReply!.payload as { text: string }).text).toContain(
+      "Alice Guardian",
+    );
+  });
+});
+
 describe("enforceIngressAcl — fail-closed on malformed member verdict", () => {
   test("member identity + unknown policy → not_a_member deny even under strangers", async () => {
     const result = await enforceIngressAcl(

package/src/runtime/routes/inbound-stages/acl-enforcement.ts

@@ -7,7 +7,7 @@ import type { AdmissionPolicy, SourceMetadata } from "@vellumai/gateway-client";
 
 import { isInviteCodeRedemptionEnabled } from "../../../channels/config.js";
 import type { ChannelId } from "../../../channels/types.js";
-import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import { getGuardianDelivery } from "../../../contacts/guardian-delivery-reader.js";
 import { channelStatusToMemberStatus } from "../../../contacts/member-status.js";
 import type {
   ContactChannel,
@@ -25,6 +25,7 @@ import { getLogger } from "../../../util/logger.js";
 import { truncate } from "../../../util/truncate.js";
 import { hashVoiceCode } from "../../../util/voice-code.js";
 import { notifyGuardianOfAccessRequest } from "../../access-request-helper.js";
+import { resolveAnchoredGuardian } from "../../anchored-guardian.js";
 import { getInviteAdapterRegistry } from "../../channel-invite-transport.js";
 import {
   createOutboundSession,
@@ -38,7 +39,8 @@ import {
   redeemInviteByCode,
 } from "../../invite-redemption-service.js";
 import { getInviteRedemptionReply } from "../../invite-redemption-templates.js";
-import { resolvedMemberFromVerdict } from "../../trust-verdict-consumer.js";
+import type { VerdictMember } from "../../trust-verdict-consumer.js";
+import { verdictMemberFromVerdict } from "../../trust-verdict-consumer.js";
 
 const log = getLogger("runtime-http");
 
@@ -46,28 +48,20 @@ const log = getLogger("runtime-http");
  * Resolve the guardian's display name for use in requester-facing messages.
  *
  * Uses the assistant's anchored vellum principal to validate the guardian
- * contact, matching the same strategy used by `notifyGuardianOfAccessRequest`.
- * This prevents stale or cross-assistant contacts from leaking a wrong name.
+ * binding, matching the same strategy used by `notifyGuardianOfAccessRequest`.
+ * This prevents stale or cross-assistant bindings from leaking a wrong name.
+ * Cosmetic copy, not an admission decision, so a null gateway list degrades
+ * gracefully to the default reference.
  */
-function resolveGuardianLabel(sourceChannel: ChannelId): string {
-  const vellumGuardian = findGuardianForChannel("vellum");
-  const anchoredPrincipalId = vellumGuardian?.contact.principalId;
-
-  if (!anchoredPrincipalId) {
-    return resolveGuardianName(undefined);
-  }
-
-  // Try source-channel guardian, but only accept it when the principal
-  // matches the assistant's anchor.
-  const sourceGuardian = findGuardianForChannel(sourceChannel);
-  if (
-    sourceGuardian &&
-    sourceGuardian.contact.principalId === anchoredPrincipalId
-  ) {
-    return resolveGuardianName(sourceGuardian.contact.displayName);
-  }
-
-  return resolveGuardianName(vellumGuardian.contact.displayName);
+async function resolveGuardianLabel(sourceChannel: ChannelId): Promise<string> {
+  // Cosmetic copy, not an admission decision: no local-store fallback, and a
+  // missing anchor principal degrades to the default reference.
+  const anchored = resolveAnchoredGuardian({
+    guardians: await getGuardianDelivery(),
+    sourceChannel,
+    requireAnchorPrincipal: true,
+  });
+  return resolveGuardianName(anchored?.displayName);
 }
 
 // ---------------------------------------------------------------------------
@@ -109,7 +103,7 @@ export type ResolvedMember = {
 };
 
 export interface AclResult {
-  resolvedMember: ResolvedMember | null;
+  resolvedMember: VerdictMember | null;
   /** When set, the caller must return this response immediately. */
   earlyResponse?: Record<string, unknown>;
   /**
@@ -173,9 +167,27 @@ export async function enforceIngressAcl(
     };
   }
 
+  // Gateway attempted resolution but failed (DB error) → fail-closed deny,
+  // distinct from an absent verdict and from a real stranger. TEXT does not
+  // fall back to local ACL reads; the sender can retry.
+  if (verdict.resolutionFailed === true) {
+    log.warn(
+      { sourceChannel, externalUserId: canonicalSenderId },
+      "Ingress ACL: gateway trust resolution failed, denying fail-closed",
+    );
+    return {
+      resolvedMember: null,
+      earlyResponse: {
+        accepted: true,
+        denied: true,
+        reason: "not_a_member",
+      },
+    };
+  }
+
   // Member resolved from the gateway verdict (ACL + identity only); null for a
   // stranger verdict, which falls through to the non-member intercepts.
-  const resolvedMember: ResolvedMember | null = resolvedMemberFromVerdict(verdict);
+  const resolvedMember: VerdictMember | null = verdictMemberFromVerdict(verdict);
 
   // A verdict carrying member identity but no resolvable member
   // (malformed/unknown ACL) fails closed, not treated as a stranger.
@@ -329,7 +341,7 @@ export async function enforceIngressAcl(
           if (slackVerifyResult.initiated) {
             // Still notify the guardian about the access attempt
             try {
-              notifyGuardianOfAccessRequest({
+              await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -369,7 +381,7 @@ export async function enforceIngressAcl(
               try {
                 await deliverChannelReply(dmCallbackUrl, {
                   chatId: senderUserId,
-                  text: `I don't recognize you yet! I've let ${resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
+                  text: `I don't recognize you yet! I've let ${await resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
                   assistantId,
                 });
               } catch (err) {
@@ -404,7 +416,7 @@ export async function enforceIngressAcl(
 
           if (emailVerifyResult.initiated) {
             try {
-              notifyGuardianOfAccessRequest({
+              await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -443,7 +455,7 @@ export async function enforceIngressAcl(
         // deduplication, canonical request creation, and notification emission.
         let guardianNotified = false;
         try {
-          const accessResult = notifyGuardianOfAccessRequest({
+          const accessResult = await notifyGuardianOfAccessRequest({
             canonicalAssistantId,
             sourceChannel,
             conversationExternalId,
@@ -467,7 +479,7 @@ export async function enforceIngressAcl(
         }
 
         const replyText = guardianNotified
-          ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
+          ? `Hmm looks like you don't have access to talk to me. I'll let ${await resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
           : "Sorry, you haven't been approved to message this assistant.";
         let replyDelivered = false;
         if (replyCallbackUrl) {
@@ -507,8 +519,8 @@ export async function enforceIngressAcl(
     }
 
     if (resolvedMember) {
-      if (resolvedMember.channel.status !== "active") {
-        const isBlockedMember = resolvedMember.channel.status === "blocked";
+      if (resolvedMember.status !== "active") {
+        const isBlockedMember = resolvedMember.status === "blocked";
         // Bootstrap commands must pass through for re-verifiable states
         // (pending/revoked), but never for blocked members.
         let denyInactiveMember = true;
@@ -529,7 +541,7 @@ export async function enforceIngressAcl(
             log.info(
               {
                 sourceChannel,
-                channelId: resolvedMember.channel.id,
+                channelId: resolvedMember.channelId,
                 hasValidBootstrapSession: false,
               },
               "Ingress ACL: inactive member bootstrap bypass denied",
@@ -614,11 +626,11 @@ export async function enforceIngressAcl(
         if (!isBlockedMember && denyInactiveMember) {
           if (
             (effectiveAdmissionPolicy === "strangers" &&
-              resolvedMember.channel.status !== "revoked") ||
+              resolvedMember.status !== "revoked") ||
             ((effectiveAdmissionPolicy === "any_contact" ||
               effectiveAdmissionPolicy === "guardian_only") &&
-              (resolvedMember.channel.status === "pending" ||
-                resolvedMember.channel.status === "unverified"))
+              (resolvedMember.status === "pending" ||
+                resolvedMember.status === "unverified"))
           ) {
             denyInactiveMember = false;
           }
@@ -628,8 +640,8 @@ export async function enforceIngressAcl(
           log.info(
             {
               sourceChannel,
-              channelId: resolvedMember.channel.id,
-              status: resolvedMember.channel.status,
+              channelId: resolvedMember.channelId,
+              status: resolvedMember.status,
             },
             "Ingress ACL: member not active, denying",
           );
@@ -639,7 +651,7 @@ export async function enforceIngressAcl(
           // the guardian made an explicit decision to block them.
           if (
             sourceChannel === "slack" &&
-            resolvedMember.channel.status !== "blocked" &&
+            resolvedMember.status !== "blocked" &&
             (canonicalSenderId ?? rawSenderId)
           ) {
             const slackVerifyResult = initiateSlackVerificationChallenge({
@@ -649,7 +661,7 @@ export async function enforceIngressAcl(
 
             if (slackVerifyResult.initiated) {
               try {
-                notifyGuardianOfAccessRequest({
+                await notifyGuardianOfAccessRequest({
                   canonicalAssistantId,
                   sourceChannel,
                   conversationExternalId,
@@ -657,7 +669,7 @@ export async function enforceIngressAcl(
                   actorDisplayName,
                   actorUsername,
                   previousMemberStatus: channelStatusToMemberStatus(
-                    resolvedMember.channel.status,
+                    resolvedMember.status,
                   ),
                   messagePreview: truncate(
                     trimmedContent,
@@ -688,7 +700,7 @@ export async function enforceIngressAcl(
                 try {
                   await deliverChannelReply(dmCallbackUrl, {
                     chatId: senderUserId,
-                    text: `I don't recognize you yet! I've let ${resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
+                    text: `I don't recognize you yet! I've let ${await resolveGuardianLabel(sourceChannel)} know you're trying to reach me. They'll need to share a 6-digit verification code with you — ask them directly if you know them. Once you have the code, reply here with it.`,
                     assistantId,
                   });
                 } catch (err) {
@@ -715,9 +727,9 @@ export async function enforceIngressAcl(
           // re-approve. Blocked members are intentionally excluded — the
           // guardian already made an explicit decision to block them.
           let guardianNotified = false;
-          if (resolvedMember.channel.status !== "blocked") {
+          if (resolvedMember.status !== "blocked") {
             try {
-              const accessResult = notifyGuardianOfAccessRequest({
+              const accessResult = await notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 conversationExternalId,
@@ -725,7 +737,7 @@ export async function enforceIngressAcl(
                 actorDisplayName,
                 actorUsername,
                 previousMemberStatus: channelStatusToMemberStatus(
-                  resolvedMember.channel.status,
+                  resolvedMember.status,
                 ),
                 messagePreview: truncate(
                   trimmedContent,
@@ -745,7 +757,7 @@ export async function enforceIngressAcl(
           }
 
           const inactiveReplyText = guardianNotified
-            ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
+            ? `Hmm looks like you don't have access to talk to me. I'll let ${await resolveGuardianLabel(sourceChannel)} know you tried talking to me and get back to you.`
             : "Sorry, you haven't been approved to message this assistant.";
           let inactiveReplyDelivered = false;
           if (replyCallbackUrl) {
@@ -779,16 +791,16 @@ export async function enforceIngressAcl(
             earlyResponse: {
               accepted: true,
               denied: true,
-              reason: `member_${channelStatusToMemberStatus(resolvedMember.channel.status)}`,
+              reason: `member_${channelStatusToMemberStatus(resolvedMember.status)}`,
               ...(!inactiveReplyDelivered && { replyText: inactiveReplyText }),
             },
           };
         }
       }
 
-      if (resolvedMember.channel.policy === "deny") {
+      if (resolvedMember.policy === "deny") {
         log.info(
-          { sourceChannel, channelId: resolvedMember.channel.id },
+          { sourceChannel, channelId: resolvedMember.channelId },
           "Ingress ACL: member policy deny",
         );
         const denyReplyText =

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -9,6 +9,10 @@
  */
 import type { ChannelId, InterfaceId } from "../../../channels/types.js";
 import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+} from "../../../contacts/guardian-delivery-reader.js";
 import type { ServerMessage } from "../../../daemon/message-protocol.js";
 import type { TrustContext } from "../../../daemon/trust-context.js";
 import {
@@ -960,10 +964,18 @@ function startTrustedContactApprovalNotifier(params: {
 
         if (info && !globalNotifiedApprovalRequestIds.has(info.requestId)) {
           globalNotifiedApprovalRequestIds.set(info.requestId, conversationId);
-          const guardian = findGuardianForChannel(sourceChannel);
-          const guardianName = resolveGuardianName(
-            guardian?.contact.displayName,
-          );
+          // Gateway-resolved guardian display name with the transitional
+          // local fallback on null/no-match (display-only). Removed in Combo 11.
+          const guardians = await getGuardianDelivery({
+            channelTypes: [sourceChannel],
+          });
+          const gatewayDisplayName = guardians
+            ? guardianForChannel(guardians, sourceChannel)?.displayName
+            : undefined;
+          const displayName =
+            gatewayDisplayName ??
+            findGuardianForChannel(sourceChannel)?.contact.displayName;
+          const guardianName = resolveGuardianName(displayName);
           const waitingText = `Waiting for ${guardianName}'s approval...`;
           try {
             await deliverChannelReply(replyCallbackUrl, {

package/src/runtime/routes/inbound-stages/escalation-intercept.ts

@@ -13,8 +13,8 @@ import { storePayload } from "../../../memory/delivery-crud.js";
 import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
 import { getLogger } from "../../../util/logger.js";
 import { getGuardianBinding } from "../../channel-verification-service.js";
+import type { VerdictMember } from "../../trust-verdict-consumer.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "../channel-route-shared.js";
-import type { ResolvedMember } from "./acl-enforcement.js";
 
 const log = getLogger("runtime-http");
 
@@ -23,7 +23,7 @@ const log = getLogger("runtime-http");
 // ---------------------------------------------------------------------------
 
 export interface EscalationInterceptParams {
-  resolvedMember: ResolvedMember | null;
+  resolvedMember: VerdictMember | null;
   canonicalAssistantId: string;
   sourceChannel: ChannelId;
   sourceInterface: InterfaceId;
@@ -49,9 +49,9 @@ export interface EscalationInterceptParams {
  * Returns a Response if the escalation was handled (the pipeline should
  * short-circuit), or null to continue the pipeline.
  */
-export function handleEscalationIntercept(
+export async function handleEscalationIntercept(
   params: EscalationInterceptParams,
-): Record<string, unknown> | null {
+): Promise<Record<string, unknown> | null> {
   const {
     resolvedMember,
     canonicalAssistantId,
@@ -72,15 +72,15 @@ export function handleEscalationIntercept(
     rawSenderId,
   } = params;
 
-  if (resolvedMember?.channel.policy !== "escalate") {
+  if (resolvedMember?.policy !== "escalate") {
     return null;
   }
 
-  const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
+  const binding = await getGuardianBinding(canonicalAssistantId, sourceChannel);
   if (!binding) {
     // Fail-closed: can't escalate without a guardian to route to
     log.info(
-      { sourceChannel, channelId: resolvedMember.channel.id },
+      { sourceChannel, channelId: resolvedMember.channelId },
       "Ingress ACL: escalate policy but no guardian binding, denying",
     );
     return {

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.test.ts

@@ -4,7 +4,9 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 // Mocks — must be set up before importing the module under test
 // ---------------------------------------------------------------------------
 
-let mockGuardian: { contact: unknown; channel: unknown } | null = null;
+// Gateway guardian-delivery list: empty = unbound, one entry = bound,
+// null = gateway unreachable.
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
 let mockActiveSession: Record<string, unknown> | null = null;
 let mockSessionResult = {
   sessionId: "sess-1",
@@ -20,8 +22,14 @@ let deliverChannelReplyCalls: unknown[][] = [];
 let emitNotificationSignalCalls: unknown[] = [];
 let messageIdCounter = 0;
 
-mock.module("../../../contacts/contact-store.js", () => ({
-  findGuardianForChannel: () => mockGuardian,
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  // Existence guard reads fresh (uncached) — only this variant is stubbed.
+  getGuardianDeliveryFresh: () => Promise.resolve(mockGuardianList),
+  guardianForChannel: (
+    list: Array<{ channelType: string; status: string }>,
+    channelType: string,
+  ) =>
+    list.find((g) => g.channelType === channelType && g.status === "active"),
 }));
 
 mock.module("../../channel-verification-service.js", () => ({
@@ -96,7 +104,7 @@ function makeParams(
 
 describe("handleGuardianActivationIntercept", () => {
   beforeEach(() => {
-    mockGuardian = null;
+    mockGuardianList = [];
     mockActiveSession = null;
     mockSessionResult = {
       sessionId: "sess-1",
@@ -155,10 +163,15 @@ describe("handleGuardianActivationIntercept", () => {
   });
 
   test("bare /start with existing guardian returns null", async () => {
-    mockGuardian = {
-      contact: { id: "contact-1", role: "guardian" },
-      channel: { id: "ch-1", type: "telegram" },
-    };
+    mockGuardianList = [{ channelType: "telegram", status: "active" }];
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("null guardian list (gateway unreachable) does NOT auto-start", async () => {
+    mockGuardianList = null;
 
     const result = await handleGuardianActivationIntercept(makeParams());
     expect(result).toBeNull();

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.ts

@@ -9,7 +9,10 @@
  * the guardian binding, and sends a success reply.
  */
 import type { ChannelId } from "../../../channels/types.js";
-import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import {
+  getGuardianDeliveryFresh,
+  guardianForChannel,
+} from "../../../contacts/guardian-delivery-reader.js";
 import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
 import { getLogger } from "../../../util/logger.js";
 import {
@@ -88,8 +91,16 @@ export async function handleGuardianActivationIntercept(
   // Only proceed for Telegram (can be extended later)
   if (sourceChannel !== "telegram") return null;
 
-  // If a guardian already exists for this channel, continue to normal flow
-  if (findGuardianForChannel(sourceChannel)) return null;
+  // If a guardian already exists for this channel, continue to normal flow.
+  // Null-list (gateway unreachable) is treated as guardian-present so a
+  // transient miss does NOT spuriously auto-start verification.
+  // Read fresh: gateway-side binding writes don't invalidate the daemon cache.
+  const guardianList = await getGuardianDeliveryFresh({
+    channelTypes: [sourceChannel],
+  });
+  if (guardianList === null || guardianForChannel(guardianList, sourceChannel)) {
+    return null;
+  }
 
   // Can't bind a session without sender identity
   if (!rawSenderId) return null;

package/src/runtime/routes/index.ts

@@ -102,6 +102,7 @@ import { ROUTES as OAUTH_COMMANDS_ROUTES } from "./oauth-commands-routes.js";
 import { ROUTES as OAUTH_CONNECT_ROUTES } from "./oauth-connect-routes.js";
 import { ROUTES as OAUTH_LIFECYCLE_ROUTES } from "./oauth-lifecycle-routes.js";
 import { ROUTES as OAUTH_PROVIDERS_ROUTES } from "./oauth-providers.js";
+import { ROUTES as ONBOARDING_CHECKIN_ROUTES } from "./onboarding-checkin-routes.js";
 import { ROUTES as PLATFORM_ROUTES } from "./platform-routes.js";
 import { ROUTES as PLAYGROUND_ROUTES } from "./playground/index.js";
 import { ROUTES as PLUGINS_ROUTES } from "./plugins-routes.js";
@@ -234,6 +235,7 @@ export const ROUTES: RouteDefinition[] = [
   ...OAUTH_LIFECYCLE_ROUTES,
   ...OAUTH_COMMANDS_ROUTES,
   ...OAUTH_PROVIDERS_ROUTES,
+  ...ONBOARDING_CHECKIN_ROUTES,
   ...PLATFORM_ROUTES,
   ...PLAYGROUND_ROUTES,
   ...PLUGINS_ROUTES,