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

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

@@ -12,7 +12,7 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
-import { findGuardianForChannel } from "../contacts/contact-store.js";
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
 import type { ChannelStatus } from "../contacts/types.js";
 import {
   createCanonicalGuardianRequest,
@@ -25,6 +25,7 @@ import {
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import type { GuardianResolutionSource } from "../notifications/signal.js";
 import { getLogger } from "../util/logger.js";
+import { resolveAnchoredGuardian } from "./anchored-guardian.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
 
 const log = getLogger("access-request-helper");
@@ -70,12 +71,12 @@ export type AccessRequestResult =
  * trust anchor and only accepts source-channel contacts that match it. This
  * prevents stale or cross-assistant contacts from being bound to the request.
  *
- * This is intentionally synchronous with respect to the canonical store writes
- * and fire-and-forget for the notification signal emission.
+ * The canonical store writes complete before this resolves; the notification
+ * signal emission is fire-and-forget.
  */
-export function notifyGuardianOfAccessRequest(
+export async function notifyGuardianOfAccessRequest(
   params: AccessRequestParams,
-): AccessRequestResult {
+): Promise<AccessRequestResult> {
   const {
     canonicalAssistantId,
     sourceChannel,
@@ -94,40 +95,19 @@ export function notifyGuardianOfAccessRequest(
     return { notified: false, reason: "no_sender_id" };
   }
 
-  // Resolve guardian identity with assistant-anchored strategy:
-  // 1. Ensure the assistant has a vellum guardian principal (trust anchor)
-  // 2. Use source-channel guardian only when principal matches anchor
-  // 3. Fallback to vellum guardian identity for this assistant principal
-  let guardianExternalUserId: string | null = null;
-  let guardianPrincipalId: string | null = null;
-  let guardianBindingChannel: string | null = null;
-  let guardianResolutionSource: GuardianResolutionSource = "none";
-
-  const vellumGuardian = findGuardianForChannel("vellum");
-  const assistantGuardianPrincipalId = vellumGuardian?.contact.principalId;
-
-  // Try source-channel guardian, but only if it maps to the assistant's
-  // anchored principal. This blocks cross-assistant/stale contact selection.
-  const sourceGuardian = findGuardianForChannel(sourceChannel);
-  if (
-    assistantGuardianPrincipalId &&
-    sourceGuardian &&
-    sourceGuardian.contact.principalId === assistantGuardianPrincipalId
-  ) {
-    guardianExternalUserId = sourceGuardian.channel.address;
-    guardianPrincipalId = sourceGuardian.contact.principalId;
-    guardianBindingChannel = sourceGuardian.channel.type;
-    guardianResolutionSource = "source-channel-contact";
-  }
-
-  // Access requests always require a principal. If source-channel resolution
-  // did not match the assistant anchor, use the anchored vellum identity.
-  if (!guardianPrincipalId && vellumGuardian) {
-    guardianExternalUserId = vellumGuardian.channel.address;
-    guardianPrincipalId = assistantGuardianPrincipalId ?? null;
-    guardianBindingChannel = guardianBindingChannel ?? "vellum";
-    guardianResolutionSource = "vellum-anchor";
-  }
+  // Resolve guardian identity with the assistant-anchored strategy (gateway
+  // source-channel match validated against the vellum anchor, else the vellum
+  // anchor), with a LOCAL-store fallback when the gateway read is empty.
+  const anchored = resolveAnchoredGuardian({
+    guardians: await getGuardianDelivery(),
+    sourceChannel,
+    useLocalFallback: true,
+  });
+  const guardianExternalUserId = anchored?.address ?? null;
+  const guardianPrincipalId = anchored?.principalId ?? null;
+  const guardianBindingChannel = anchored?.channelType ?? null;
+  const guardianResolutionSource: GuardianResolutionSource =
+    anchored?.source ?? "none";
 
   log.debug(
     {

package/src/runtime/actor-trust-resolver.ts

@@ -21,6 +21,7 @@ import {
   findContactByAddress,
   findGuardianForChannel,
 } from "../contacts/contact-store.js";
+import { channelStatusToMemberStatus } from "../contacts/member-status.js";
 import type { ContactChannel, ContactWithChannels } from "../contacts/types.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
@@ -57,22 +58,6 @@ export type TrustClass =
   | "unverified_contact"
   | "unknown";
 
-/**
- * Trust-class ordinal used by the per-channel admission policy floor check.
- * Higher rank = more trusted. Blocked/revoked never reach classification —
- * their effective rank is 0 and is enforced by the inbound ACL stage's
- * member-status short-circuit, not via this table.
- *
- * See `wave-b-plan.md` §2.4. Paired with `ADMISSION_FLOOR` from
- * `@vellumai/gateway-client` — both tables move together.
- */
-export const TRUST_CLASS_RANK: Record<TrustClass, number> = {
-  guardian: 4,
-  trusted_contact: 3,
-  unverified_contact: 2,
-  unknown: 1,
-};
-
 /**
  * Fully resolved trust context from the actor trust resolver.
  *
@@ -338,5 +323,12 @@ export function toTrustContext(
     requesterMemberDisplayName: ctx.actorMetadata.memberDisplayName,
     requesterExternalUserId: ctx.canonicalSenderId ?? undefined,
     requesterChatId: conversationExternalId,
+    // Member grounding from the resolved memberRecord (voice + verdict paths
+    // both populate it).
+    requesterContactId: ctx.memberRecord?.contact.id,
+    memberStatus: ctx.memberRecord
+      ? channelStatusToMemberStatus(ctx.memberRecord.channel.status)
+      : undefined,
+    memberPolicy: ctx.memberRecord?.channel.policy,
   };
 }

package/src/runtime/agent-wake.ts

@@ -14,13 +14,22 @@
  *     `suppressAutoCompaction: true` to skip it; a suppressed wake whose
  *     input exceeds the effective context window fails deterministically
  *     with `reason: "context_overflow"` instead of compacting.
- *   - Appends `hint` as a non-persisted assistant message sandwiched
- *     between two static user messages — never shows up in the transcript
- *     or SSE feed. The assistant role prevents prompt injection (LLMs
- *     don't follow instructions in their own prior output), and the
- *     trailing user message satisfies providers that reject assistant
- *     prefill. The bookend user messages are hardcoded strings with no
- *     dynamic content, so they cannot carry injection payloads.
+ *   - Hint delivery has two modes:
+ *     - Default (ephemeral): appends `hint` as a non-persisted assistant
+ *       message sandwiched between two static user bookends — never shows up
+ *       in the transcript or SSE feed. The assistant role defangs prompt
+ *       injection (LLMs don't follow instructions in their own prior output)
+ *       and the bookends are hardcoded strings with no dynamic content. Suited
+ *       to wakes carrying arbitrary/untrusted hint text (meet chat
+ *       opportunities, the explicit wake route).
+ *     - `persistTriggerAsEvent`: appends the trigger as a SINGLE PERSISTED,
+ *       transcript-visible user message wrapped in `<background_event>` (any
+ *       untrusted command output fenced in `<external_content>`). Keeping the
+ *       trigger in durable, append-only history lets the provider prompt-cache
+ *       treat repeated wakes like normal user turns instead of re-creating the
+ *       whole prefix each wake. Used by background-command and scheduled wakes
+ *       whose `hint` is trusted framing; wakes carrying arbitrary caller hint
+ *       text stay on the ephemeral trio above.
  *   - Invokes the agent loop with all conversation tools available unless
  *     the caller provides an explicit `allowedTools` scope.
  *   - No tool calls AND no assistant text → silent no-op (nothing persisted,
@@ -74,6 +83,7 @@ import {
   broadcastWakeSurface,
   emitWakeAgentEvent,
   persistWakeTailMessage,
+  persistWakeTriggerMessage,
   scopeWakeAllowedTools,
 } from "../daemon/wake-conversation-ops.js";
 import {
@@ -88,6 +98,10 @@ import {
 } from "../memory/llm-request-log-store.js";
 import type { SystemPromptPersonaOverride } from "../prompts/system-prompt.js";
 import type { Message } from "../providers/types.js";
+import {
+  type UntrustedContentSource,
+  wrapUntrustedContent,
+} from "../security/untrusted-content.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("agent-wake");
@@ -100,6 +114,46 @@ const WAKE_PREAMBLE =
 const WAKE_POSTAMBLE =
   "[system] End of message from external system, continue the conversation.";
 
+/** Sanitize a value for use as an XML attribute (no quotes/brackets/newlines). */
+function sanitizeEventAttr(value: string): string {
+  return value.replace(/[<>"&\r\n]/g, "").slice(0, 200);
+}
+
+/**
+ * Untrusted third-party output to fence inside a persisted wake trigger via
+ * {@link wrapUntrustedContent}. `maxChars` overrides the per-source character
+ * budget — used for preformatted shell output that `formatShellOutput` already
+ * bounded (to `MAX_OUTPUT_LENGTH`) and appended an `<output_truncated file=…/>`
+ * recovery marker to, so the wrapper does not re-truncate that marker off.
+ */
+interface WakeUntrustedOutput {
+  content: string;
+  source: UntrustedContentSource;
+  maxChars?: number;
+}
+
+/**
+ * Build the text for a persisted wake-trigger message: a `<background_event>`
+ * wrapper carrying the trusted framing, with any untrusted command output
+ * fenced in an `<external_content>` block the model is instructed never to
+ * obey. The wrapper signals "a system event woke you" (replacing the legacy
+ * `[system] external system` / `[opportunity:…]` bookends); `source` lives in
+ * the tag attribute and the message metadata.
+ */
+function buildBackgroundEventText(
+  source: string,
+  framing: string,
+  untrustedOutput?: WakeUntrustedOutput,
+): string {
+  const body = untrustedOutput
+    ? `${framing}\n${wrapUntrustedContent(untrustedOutput.content, {
+        source: untrustedOutput.source,
+        maxChars: untrustedOutput.maxChars,
+      })}`
+    : framing;
+  return `<background_event source="${sanitizeEventAttr(source)}">\n${body}\n</background_event>`;
+}
+
 /**
  * Warn line shared by the two reactive over-window failure sites (provider
  * rejection escaped as a throw / swallowed into a no-output stop). The
@@ -196,14 +250,6 @@ export interface WakeOptions {
    * retrospectives whose conversation title already says "(Retrospective)").
    */
   suppressWakeSurface?: boolean;
-  /**
-   * Run the wake's turn as non-interactive (no client present). Threads to the
-   * agent loop's `isNonInteractive`, which gates the `<non_interactive_context>`
-   * and `<background_turn>` injectors. Fork-based memory retrospectives set this
-   * to the source conversation's background-turn state so the fork reproduces
-   * the source's injected turn block (prompt-cache prefix parity). Default false.
-   */
-  isNonInteractive?: boolean;
   /**
    * Optional exact tool allowlist for this wake. Used by internal maintenance
    * jobs that need the assistant's judgment but must not execute arbitrary
@@ -249,6 +295,28 @@ export interface WakeOptions {
    * class and approval semantics are governed solely by `trustContext`.
    */
   personaOverride?: SystemPromptPersonaOverride;
+  /**
+   * Inject the wake's trigger as a SINGLE PERSISTED, transcript-visible user
+   * message (wrapped in `<background_event>`) appended to the conversation
+   * BEFORE the run, instead of the default ephemeral hint trio. This keeps the
+   * message array append-only so the provider prompt-cache behaves like a
+   * normal user turn — repeated wakes stop re-creating the whole prefix. The
+   * trigger is persisted unconditionally (like a normal user turn's message),
+   * even if the wake then produces no reply.
+   *
+   * `hint` is the trusted framing line; `untrustedOutput`, when given, is
+   * appended fenced in `<external_content>` so the model treats command output
+   * as data, never instructions. Mutually exclusive with the legacy
+   * `hintRole` / `skipHintInjection` injection.
+   */
+  persistTriggerAsEvent?: boolean;
+  /**
+   * Untrusted third-party output (e.g. background-command stdout) to fence
+   * inside the persisted trigger via {@link wrapUntrustedContent}. Only
+   * consulted when `persistTriggerAsEvent` is set; `hint` stays the trusted
+   * framing outside the fence.
+   */
+  untrustedOutput?: WakeUntrustedOutput;
 }
 
 /**
@@ -596,7 +664,6 @@ export async function wakeAgentForOpportunity(
       opts.forceOverrideProfile ??
       getConversationOverrideProfile(conversationId);
     const callSite = opts.callSite ?? "mainAgent";
-    const isNonInteractive = opts.isNonInteractive ?? false;
     const config = getConfig();
     const effectiveContextWindow = resolveEffectiveContextWindow({
       llm: config.llm,
@@ -606,13 +673,14 @@ export async function wakeAgentForOpportunity(
     });
 
     // Apply the caller's persona override for the duration of the run. The
-    // wake's agent loop builds the system prompt through the conversation's
-    // resolveSystemPrompt callback, which reads this field; cleared (below,
-    // before drainQueue) so a queued user turn never builds its prompt under
-    // the wake's override. Assigned only AFTER the profile/config reads above
-    // — those can throw, and they run before the try/finally that clears the
-    // override, so an earlier assignment would strand the override on the
-    // cached Conversation and corrupt every later prompt build on it.
+    // prompt is built once before `agentLoop.run()` (via
+    // `conversation.buildCurrentSystemPrompt()`), which reads this field;
+    // cleared (below, before drainQueue) so a queued user turn never builds
+    // its prompt under the wake's override. Assigned only AFTER the
+    // profile/config reads above — those can throw, and they run before the
+    // try/finally that clears the override, so an earlier assignment would
+    // strand the override on the cached Conversation and corrupt every later
+    // prompt build on it.
     if (opts.personaOverride) {
       conversation.wakePersonaOverride = opts.personaOverride;
     }
@@ -661,6 +729,38 @@ export async function wakeAgentForOpportunity(
       }
     }
 
+    // ── Persisted-trigger injection (append-only wake) ─────────────────
+    // Append the trigger as a single VISIBLE user message to the in-memory
+    // history AND the DB BEFORE snapshotting the baseline, so the message
+    // array stays append-only (prompt-cache parity with a normal user turn)
+    // and `baseline` already contains it. Runs after `maybeCompact` (a
+    // successful compaction replaces `conversation.messages`) and inside the
+    // single-flight lock + processing flag, so no concurrent turn interleaves.
+    // Push first, then persist (matching the wake-tail flush idiom); a persist
+    // failure is non-fatal — the in-memory push keeps this run's prompt
+    // consistent. The trigger is part of `baseline`, so `flushPendingTail`
+    // never re-persists it.
+    if (opts.persistTriggerAsEvent) {
+      const triggerMessage: Message = {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: buildBackgroundEventText(source, hint, opts.untrustedOutput),
+          },
+        ],
+      };
+      conversation.messages.push(triggerMessage);
+      try {
+        await persistWakeTriggerMessage(conversation, triggerMessage, source);
+      } catch (err) {
+        log.warn(
+          { conversationId, source, err },
+          "agent-wake: failed to persist wake trigger message; continuing",
+        );
+      }
+    }
+
     const baseline = conversation.getMessages();
     // Snapshot the baseline length BEFORE the run starts. Incremental
     // persistence pushes onto `conversation.messages` mid-run, which grows the
@@ -669,44 +769,46 @@ export async function wakeAgentForOpportunity(
     // tail-slice math would skip every message.
     const baselineLength = baseline.length;
     const wakeTrust = buildWakeTrust(opts, diskPressureDecision);
-    // Build the hint injection. Three modes:
-    //   - `skipHintInjection`: caller has already persisted an instruction
-    //     message into the conversation history (typical for fork-based
-    //     memory retrospectives that append a user message before waking).
-    //   - `hintRole === "user"`: single user-role message containing the
-    //     hint directly. Used by trusted internal callers where the hint
-    //     reads naturally as an instruction.
+    // Build the ephemeral hint injection. `persistTriggerAsEvent` and
+    // `skipHintInjection` produce no injection here — the former already
+    // appended the trigger as a persisted message above; the latter relies on
+    // the caller having persisted an instruction (fork retrospectives). The
+    // remaining modes inject a non-persisted hint:
+    //   - `hintRole === "user"`: single user-role message containing the hint
+    //     directly. Used by trusted internal callers where the hint reads
+    //     naturally as an instruction.
     //   - default (`hintRole === "assistant"`): sandwich the hint as an
-    //     assistant message between two hardcoded user bookends. The
-    //     assistant role defangs prompt injection (LLMs don't follow
-    //     instructions in their own prior output) and the trailing user
-    //     message satisfies providers that reject assistant prefill.
+    //     assistant message between two hardcoded user bookends. The assistant
+    //     role defangs prompt injection (LLMs don't follow instructions in
+    //     their own prior output) and the trailing user message satisfies
+    //     providers that reject assistant prefill.
     const hintRole = opts.hintRole ?? "assistant";
-    const wakeMessages: Message[] = opts.skipHintInjection
-      ? []
-      : hintRole === "user"
-        ? [
-            {
-              role: "user",
-              content: [{ type: "text", text: hint }],
-            },
-          ]
-        : [
-            {
-              role: "user",
-              content: [{ type: "text", text: WAKE_PREAMBLE }],
-            },
-            {
-              role: "assistant",
-              content: [
-                { type: "text", text: `[opportunity:${source}] ${hint}` },
-              ],
-            },
-            {
-              role: "user",
-              content: [{ type: "text", text: WAKE_POSTAMBLE }],
-            },
-          ];
+    const wakeMessages: Message[] =
+      opts.persistTriggerAsEvent || opts.skipHintInjection
+        ? []
+        : hintRole === "user"
+          ? [
+              {
+                role: "user",
+                content: [{ type: "text", text: hint }],
+              },
+            ]
+          : [
+              {
+                role: "user",
+                content: [{ type: "text", text: WAKE_PREAMBLE }],
+              },
+              {
+                role: "assistant",
+                content: [
+                  { type: "text", text: `[opportunity:${source}] ${hint}` },
+                ],
+              },
+              {
+                role: "user",
+                content: [{ type: "text", text: WAKE_POSTAMBLE }],
+              },
+            ];
     const wakeHintMessageCount = wakeMessages.length;
     const runInput: Message[] = [...baseline, ...wakeMessages];
 
@@ -1114,6 +1216,19 @@ export async function wakeAgentForOpportunity(
         };
       }
 
+      // Wakes bypass `runAgentLoopImpl`, which is what stamps the live turn's
+      // call site and override profile onto the conversation for the tool
+      // executor to read. Without stamping them here, `subagent_spawn` (and
+      // usage attribution) see an unstamped context and resolve children under
+      // workspace defaults instead of the profile this wake actually runs
+      // under — so a wake on a conversation pinned to another profile spawns
+      // children under the wrong one. Restored in the `finally` so a queued
+      // user turn or a later background read never inherits the wake's stamps.
+      const priorCallSite = conversation.currentCallSite;
+      const priorTurnOverrideProfile = conversation.currentTurnOverrideProfile;
+      conversation.currentCallSite = callSite;
+      conversation.currentTurnOverrideProfile = overrideProfile;
+
       let updatedHistory: Message[];
       try {
         ({ history: updatedHistory } = await conversation.agentLoop.run({
@@ -1131,7 +1246,6 @@ export async function wakeAgentForOpportunity(
           trust: wakeTrust,
           overrideProfile,
           forceOverrideProfile,
-          isNonInteractive,
           // The wake's compaction lives in the pre-run gate above
           // (`conversation.maybeCompact()`), never in the loop: the in-loop
           // budget gate and overflow-recovery ladder stay disabled because
@@ -1143,6 +1257,9 @@ export async function wakeAgentForOpportunity(
             maxInputTokens: effectiveContextWindow.maxInputTokens,
             overflowRecovery: { enabled: false, safetyMarginRatio: 0 },
           }),
+          ...(conversation.modelOverride
+            ? { model: conversation.modelOverride }
+            : {}),
         }));
       } catch (err) {
         // An over-window throw on a compaction-suppressed wake is the
@@ -1164,6 +1281,12 @@ export async function wakeAgentForOpportunity(
         // `processing` and drain the queue.
         runError = err instanceof Error ? err : new Error(String(err));
         return { invoked: true, producedToolCalls: false };
+      } finally {
+        // Restore the pre-wake values so a queued user turn or background read
+        // never observes the wake's stamps. (`runAgentLoopImpl` re-stamps both
+        // at the start of the next normal turn regardless.)
+        conversation.currentCallSite = priorCallSite;
+        conversation.currentTurnOverrideProfile = priorTurnOverrideProfile;
       }
 
       // The loop swallows provider rejections into a graceful no-output

package/src/runtime/anchored-guardian.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Unit tests for `resolveAnchoredGuardian`.
+ *
+ * Covers the gateway arms (source-channel match validated against the vellum
+ * anchor, vellum-anchor fallback), the LOCAL-store fallback when the gateway
+ * list is empty, and the cosmetic `requireAnchorPrincipal` guard.
+ */
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+// Local store fallback is mocked so we can drive both arms deterministically.
+let localGuardians: Record<
+  string,
+  { contact: { principalId: string | null; displayName: string }; channel: { address: string; type: string } } | null
+> = {};
+mock.module("../contacts/contact-store.js", () => ({
+  findGuardianForChannel: (channelType: string) =>
+    localGuardians[channelType] ?? null,
+}));
+
+const { resolveAnchoredGuardian } = await import("./anchored-guardian.js");
+
+function gw(g: Partial<GuardianDelivery> & { channelType: string; address: string }): GuardianDelivery {
+  return {
+    contactId: `c-${g.channelType}`,
+    status: "active",
+    ...g,
+  };
+}
+
+afterEach(() => {
+  localGuardians = {};
+});
+
+describe("resolveAnchoredGuardian — gateway arm", () => {
+  test("source-channel guardian matching the anchor wins", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
+        gw({ channelType: "telegram", address: "tg-addr", principalId: "p-anchor", displayName: "Alice" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result).toEqual({
+      principalId: "p-anchor",
+      address: "tg-addr",
+      displayName: "Alice",
+      channelType: "telegram",
+      source: "source-channel-contact",
+    });
+  });
+
+  test("source-channel guardian NOT matching the anchor falls back to vellum-anchor", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
+        gw({ channelType: "telegram", address: "tg-addr", principalId: "p-other", displayName: "Stale" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result).toEqual({
+      principalId: "p-anchor",
+      address: "v-addr",
+      displayName: "Vellum",
+      channelType: "vellum",
+      source: "vellum-anchor",
+    });
+  });
+
+  test("no source-channel guardian falls back to vellum-anchor", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result?.source).toBe("vellum-anchor");
+    expect(result?.principalId).toBe("p-anchor");
+  });
+});
+
+describe("resolveAnchoredGuardian — local fallback", () => {
+  test("gateway empty + local source-channel match returns the local record", () => {
+    localGuardians = {
+      vellum: { contact: { principalId: "p-local", displayName: "LocalVellum" }, channel: { address: "lv-addr", type: "vellum" } },
+      telegram: { contact: { principalId: "p-local", displayName: "LocalAlice" }, channel: { address: "ltg-addr", type: "telegram" } },
+    };
+    const result = resolveAnchoredGuardian({
+      guardians: null,
+      sourceChannel: "telegram",
+      useLocalFallback: true,
+    });
+    expect(result).toEqual({
+      principalId: "p-local",
+      address: "ltg-addr",
+      displayName: "LocalAlice",
+      channelType: "telegram",
+      source: "source-channel-contact",
+    });
+  });
+
+  test("gateway empty + only local vellum returns the local vellum-anchor", () => {
+    localGuardians = {
+      vellum: { contact: { principalId: "p-local", displayName: "LocalVellum" }, channel: { address: "lv-addr", type: "vellum" } },
+    };
+    const result = resolveAnchoredGuardian({
+      guardians: null,
+      sourceChannel: "telegram",
+      useLocalFallback: true,
+    });
+    expect(result?.source).toBe("vellum-anchor");
+    expect(result?.address).toBe("lv-addr");
+  });
+
+  test("gateway empty + no local + fallback disabled returns null", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: null,
+      sourceChannel: "telegram",
+    });
+    expect(result).toBeNull();
+  });
+
+  test("nothing anywhere returns null", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [],
+      sourceChannel: "telegram",
+      useLocalFallback: true,
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe("resolveAnchoredGuardian — requireAnchorPrincipal (cosmetic label)", () => {
+  test("vellum guardian with a null principal degrades to null", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: null, displayName: "Vellum" }),
+      ],
+      sourceChannel: "telegram",
+      requireAnchorPrincipal: true,
+    });
+    expect(result).toBeNull();
+  });
+
+  test("without requireAnchorPrincipal a null-principal vellum still resolves", () => {
+    const result = resolveAnchoredGuardian({
+      guardians: [
+        gw({ channelType: "vellum", address: "v-addr", principalId: null, displayName: "Vellum" }),
+      ],
+      sourceChannel: "telegram",
+    });
+    expect(result?.source).toBe("vellum-anchor");
+    expect(result?.principalId).toBeNull();
+  });
+});