@vellumai/assistant 0.4.3 → 0.4.4

package/src/runtime/channel-retry-sweep.ts

@@ -7,6 +7,7 @@ import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.
 import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
 import { getLogger } from '../util/logger.js';
 import { deliverReplyViaCallback } from './channel-reply-delivery.js';
+import { resolveRoutingStateFromRuntime } from './guardian-context-resolver.js';
 import type { MessageProcessor } from './http-types.js';
 
 const log = getLogger('runtime-http');
@@ -129,7 +130,9 @@ export async function sweepFailedEvents(
           },
           assistantId,
           guardianContext,
-          isInteractive: guardianContext?.trustClass === 'guardian',
+          isInteractive: guardianContext
+            ? resolveRoutingStateFromRuntime(guardianContext).promptWaitingAllowed
+            : false,
         },
         sourceChannel,
         sourceInterface,

package/src/runtime/confirmation-request-guardian-bridge.ts

@@ -0,0 +1,197 @@
+/**
+ * Bridge trusted-contact confirmation_request events to guardian.question notifications.
+ *
+ * When a trusted-contact channel session creates a confirmation_request (tool approval),
+ * this helper emits a guardian.question notification signal and persists canonical
+ * delivery rows to guardian destinations (Telegram/SMS/Vellum), enabling the guardian
+ * to approve via callback/request-code path.
+ *
+ * Modeled after the tool-grant-request-helper pattern. Designed to be called from
+ * both the daemon event registrar (server.ts) and the HTTP hub publisher
+ * (conversation-routes.ts) — the two paths that create confirmation_request
+ * canonical records.
+ */
+
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import {
+  type CanonicalGuardianRequest,
+  createCanonicalGuardianDelivery,
+} from '../memory/canonical-guardian-store.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
+import { getLogger } from '../util/logger.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
+import { getGuardianBinding } from './channel-guardian-service.js';
+
+const log = getLogger('confirmation-request-guardian-bridge');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BridgeConfirmationRequestParams {
+  /** The canonical guardian request already persisted for this confirmation_request. */
+  canonicalRequest: CanonicalGuardianRequest;
+  /** Guardian runtime context from the session. */
+  guardianContext: GuardianRuntimeContext;
+  /** Conversation ID where the confirmation_request was emitted. */
+  conversationId: string;
+  /** Tool name from the confirmation_request. */
+  toolName: string;
+  /** Logical assistant ID (defaults to 'self'). */
+  assistantId?: string;
+}
+
+export type BridgeConfirmationRequestResult =
+  | { bridged: true; signalId: string }
+  | { skipped: true; reason: 'not_trusted_contact' | 'no_guardian_binding' | 'missing_guardian_identity' | 'binding_identity_mismatch' };
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a trusted-contact confirmation_request to a guardian.question notification.
+ *
+ * Only emits when the session belongs to a trusted-contact actor with a
+ * resolvable guardian binding. Guardian and unknown actors are skipped — guardians
+ * self-approve, and unknown actors are already fail-closed by the routing layer.
+ *
+ * Fire-and-forget safe: notification emission errors are logged but not propagated.
+ */
+export function bridgeConfirmationRequestToGuardian(
+  params: BridgeConfirmationRequestParams,
+): BridgeConfirmationRequestResult {
+  const {
+    canonicalRequest,
+    guardianContext,
+    conversationId,
+    toolName,
+    assistantId = DAEMON_INTERNAL_ASSISTANT_ID,
+  } = params;
+
+  // Only bridge for trusted-contact sessions. Guardians self-approve and
+  // unknown actors are fail-closed by the routing layer.
+  if (guardianContext.trustClass !== 'trusted_contact') {
+    return { skipped: true, reason: 'not_trusted_contact' };
+  }
+
+  if (!guardianContext.guardianExternalUserId) {
+    log.debug(
+      { conversationId, sourceChannel: guardianContext.sourceChannel },
+      'Skipping guardian bridge: no guardian identity on trusted-contact context',
+    );
+    return { skipped: true, reason: 'missing_guardian_identity' };
+  }
+
+  const sourceChannel = guardianContext.sourceChannel;
+  const binding = getGuardianBinding(assistantId, sourceChannel);
+  if (!binding) {
+    log.debug(
+      { sourceChannel, assistantId },
+      'No guardian binding for confirmation request bridge',
+    );
+    return { skipped: true, reason: 'no_guardian_binding' };
+  }
+
+  // Validate that the binding's guardian identity matches the canonical request's
+  // guardian identity. A mismatch can occur if a guardian rebind happens between
+  // message ingress and confirmation emission — sending the notification to the
+  // new binding would leak requester/tool metadata to the wrong recipient.
+  //
+  // Both sides are canonicalized before comparison because the canonical request
+  // value was normalized by resolveGuardianContext() while the binding stores the
+  // raw identity. On phone channels the same guardian can have format variance
+  // (e.g. "+1 555-123-4567" vs "+15551234567") that would cause a false mismatch.
+  const canonicalBindingId = canonicalizeInboundIdentity(sourceChannel, binding.guardianExternalUserId);
+  const canonicalRequestId = canonicalRequest.guardianExternalUserId
+    ? canonicalizeInboundIdentity(sourceChannel, canonicalRequest.guardianExternalUserId)
+    : null;
+  if (
+    canonicalRequestId &&
+    canonicalBindingId !== canonicalRequestId
+  ) {
+    log.warn(
+      {
+        sourceChannel,
+        assistantId,
+        bindingGuardianId: binding.guardianExternalUserId,
+        expectedGuardianId: canonicalRequest.guardianExternalUserId,
+        requestId: canonicalRequest.id,
+      },
+      'Guardian binding identity does not match canonical request guardian — skipping notification to prevent misrouting',
+    );
+    return { skipped: true, reason: 'binding_identity_mismatch' };
+  }
+
+  const senderLabel = guardianContext.requesterIdentifier
+    || guardianContext.requesterExternalUserId
+    || 'unknown';
+
+  const questionText = `Tool approval request: ${toolName}`;
+
+  // Emit guardian.question notification so the guardian is alerted.
+  const signalPromise = emitNotificationSignal({
+    sourceEventName: 'guardian.question',
+    sourceChannel,
+    sourceSessionId: conversationId,
+    assistantId,
+    attentionHints: {
+      requiresAction: true,
+      urgency: 'high',
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      requestKind: 'tool_approval' as const,
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode ?? canonicalRequest.id.slice(0, 6).toUpperCase(),
+      sourceChannel,
+      requesterExternalUserId: guardianContext.requesterExternalUserId,
+      requesterChatId: guardianContext.requesterChatId ?? null,
+      requesterIdentifier: senderLabel,
+      toolName,
+      questionText,
+    },
+    dedupeKey: `tc-confirmation-request:${canonicalRequest.id}`,
+    onThreadCreated: (info) => {
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: 'vellum',
+        destinationConversationId: info.conversationId,
+      });
+    },
+  });
+
+  // Record channel deliveries from the notification pipeline (fire-and-forget).
+  void signalPromise.then((signalResult) => {
+    for (const result of signalResult.deliveryResults) {
+      if (result.channel === 'vellum') continue; // handled in onThreadCreated
+      if (result.channel !== 'telegram' && result.channel !== 'sms') continue;
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: result.channel,
+        destinationChatId: result.destination.length > 0 ? result.destination : undefined,
+      });
+    }
+  }).catch((err) => {
+    log.warn({ err, requestId: canonicalRequest.id }, 'Failed to record channel deliveries for guardian bridge');
+  });
+
+  log.info(
+    {
+      sourceChannel,
+      requesterExternalUserId: guardianContext.requesterExternalUserId,
+      toolName,
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode,
+    },
+    'Guardian notified of trusted-contact confirmation request',
+  );
+
+  // Return the signal ID synchronously from the promise-producing call.
+  // The actual signal ID is not available until the promise resolves, but
+  // callers only need to know it was bridged — the ID is for diagnostics.
+  // We use the canonical request ID as a stable correlation key.
+  return { bridged: true, signalId: canonicalRequest.id };
+}

package/src/runtime/guardian-action-followup-executor.ts

@@ -1,7 +1,7 @@
 /**
  * Guardian action follow-up executor.
  *
- * After the conversation engine (M5) classifies the guardian's reply as
+ * After the conversation engine classifies the guardian's reply as
  * `call_back` or `message_back` and transitions the follow-up state to
  * `dispatching`, this module executes the actual action:
  *

package/src/runtime/guardian-context-resolver.ts

@@ -62,6 +62,88 @@ export function resolveGuardianContext(input: ResolveGuardianContextInput): Guar
   };
 }
 
+// ---------------------------------------------------------------------------
+// Routing-state helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Routing state for a channel actor turn.
+ *
+ * Determines whether a turn should be treated as interactive (the caller
+ * can be kept waiting for a guardian to respond to an approval prompt) by
+ * combining trust class with guardian route resolvability.
+ *
+ * A guardian route is "resolvable" when a verified guardian binding exists
+ * for the channel — meaning there is a concrete destination to deliver
+ * approval notifications to. Without a resolvable guardian route, entering
+ * an interactive wait (up to 300s) is a dead-end: no guardian will ever
+ * see the prompt.
+ */
+export interface RoutingState {
+  /** Whether the actor's trust class alone permits interactive waits. */
+  canBeInteractive: boolean;
+  /** Whether a verified guardian destination exists for this channel. */
+  guardianRouteResolvable: boolean;
+  /**
+   * Whether the turn should actually enter an interactive prompt wait.
+   * True only when the actor can be interactive AND a guardian route is
+   * resolvable. This is the canonical decision used by processMessage.
+   */
+  promptWaitingAllowed: boolean;
+}
+
+/**
+ * Compute the routing state for a channel actor turn.
+ *
+ * Guardian actors are always interactive (they self-approve).
+ * Trusted contacts are only interactive when a guardian binding exists
+ * to receive approval notifications. Unknown actors are never interactive.
+ */
+export function resolveRoutingState(ctx: GuardianContext): RoutingState {
+  const isGuardian = ctx.trustClass === 'guardian';
+  const isTrustedContact = ctx.trustClass === 'trusted_contact';
+
+  // Guardians self-approve — they are always interactive and route-resolvable.
+  if (isGuardian) {
+    return {
+      canBeInteractive: true,
+      guardianRouteResolvable: true,
+      promptWaitingAllowed: true,
+    };
+  }
+
+  // Trusted contacts can be interactive only if a guardian destination
+  // exists. The guardian binding populates guardianExternalUserId during
+  // trust resolution; its presence means there is a verified guardian
+  // to route approval notifications to.
+  const guardianRouteResolvable = !!ctx.guardianExternalUserId;
+  if (isTrustedContact) {
+    return {
+      canBeInteractive: true,
+      guardianRouteResolvable,
+      promptWaitingAllowed: guardianRouteResolvable,
+    };
+  }
+
+  // Unknown actors are never interactive.
+  return {
+    canBeInteractive: false,
+    guardianRouteResolvable: !!ctx.guardianExternalUserId,
+    promptWaitingAllowed: false,
+  };
+}
+
+/**
+ * Convenience: compute routing state from a GuardianRuntimeContext
+ * (the shape persisted in stored payloads and used by the retry sweep).
+ */
+export function resolveRoutingStateFromRuntime(ctx: GuardianRuntimeContext): RoutingState {
+  return resolveRoutingState({
+    trustClass: ctx.trustClass,
+    guardianExternalUserId: ctx.guardianExternalUserId,
+  });
+}
+
 export function toGuardianRuntimeContext(sourceChannel: ChannelId, ctx: GuardianContext): GuardianRuntimeContext {
   return {
     sourceChannel,

package/src/runtime/guardian-outbound-actions.ts

@@ -94,7 +94,6 @@ function getTelegramBotUsername(): string | undefined {
 
 export interface StartOutboundParams {
   channel: ChannelId;
-  assistantId?: string;
   destination?: string;
   rebind?: boolean;
   /** Origin conversation ID so completion/failure pointers can route back. */
@@ -103,14 +102,12 @@ export interface StartOutboundParams {
 
 export interface ResendOutboundParams {
   channel: ChannelId;
-  assistantId?: string;
   /** Origin conversation ID so completion/failure pointers can route back on resend. */
   originConversationId?: string;
 }
 
 export interface CancelOutboundParams {
   channel: ChannelId;
-  assistantId?: string;
 }
 
 /**

package/src/runtime/guardian-reply-router.ts

@@ -21,13 +21,20 @@ import {
   applyCanonicalGuardianDecision,
   type CanonicalDecisionResult,
 } from '../approvals/guardian-decision-primitive.js';
-import type { ActorContext, ChannelDeliveryContext } from '../approvals/guardian-request-resolvers.js';
+import type { ActorContext, ChannelDeliveryContext, ResolverEmissionContext } from '../approvals/guardian-request-resolvers.js';
 import {
   type CanonicalGuardianRequest,
   getCanonicalGuardianRequest,
   getCanonicalGuardianRequestByCode,
   listCanonicalGuardianRequests,
 } from '../memory/canonical-guardian-store.js';
+import {
+  buildGuardianCodeOnlyClarification,
+  buildGuardianDisambiguationExample,
+  buildGuardianDisambiguationLabel,
+  buildGuardianInvalidActionReply,
+  resolveGuardianInstructionModeForRequest,
+} from '../notifications/guardian-question-mode.js';
 import { getLogger } from '../util/logger.js';
 import { runApprovalConversationTurn } from './approval-conversation-turn.js';
 import type { ApprovalAction } from './channel-approval-types.js';
@@ -60,6 +67,8 @@ export interface GuardianReplyContext {
   approvalConversationGenerator?: ApprovalConversationGenerator;
   /** Optional channel delivery context for resolver-driven side effects. */
   channelDeliveryContext?: ChannelDeliveryContext;
+  /** Optional emission context threaded to handleConfirmationResponse for correct source attribution. */
+  emissionContext?: ResolverEmissionContext;
 }
 
 export type GuardianReplyResultType =
@@ -235,9 +244,11 @@ function notConsumed(): GuardianReplyResult {
 export async function routeGuardianReply(
   ctx: GuardianReplyContext,
 ): Promise<GuardianReplyResult> {
-  const { messageText, actor, conversationId, callbackData, approvalConversationGenerator, channelDeliveryContext } = ctx;
+  const { messageText, actor, conversationId, callbackData, approvalConversationGenerator, channelDeliveryContext, emissionContext } = ctx;
   const pendingRequests = findPendingCanonicalRequests(actor, ctx.pendingRequestIds, conversationId);
-  const scopedPendingRequestIds = ctx.pendingRequestIds ? new Set(ctx.pendingRequestIds) : null;
+  const scopedPendingRequestIds = ctx.pendingRequestIds && ctx.pendingRequestIds.length > 0
+    ? new Set(ctx.pendingRequestIds)
+    : null;
 
   // ── 1. Deterministic callback parsing (button presses) ──
   // No conversationId scoping here — the guardian's reply comes from a
@@ -247,7 +258,7 @@ export async function routeGuardianReply(
   if (callbackData) {
     const parsed = parseCallbackAction(callbackData);
     if (parsed) {
-      return applyDecision(parsed.requestId, parsed.action, actor, undefined, channelDeliveryContext);
+      return applyDecision(parsed.requestId, parsed.action, actor, undefined, channelDeliveryContext, emissionContext);
     }
   }
 
@@ -280,7 +291,7 @@ export async function routeGuardianReply(
           consumed: true,
           type: 'canonical_decision_stale',
           requestId: request.id,
-          replyText: failureReplyText('already_resolved', request.requestCode),
+          replyText: failureReplyText('already_resolved', request.requestCode, request),
         };
       }
 
@@ -333,7 +344,7 @@ export async function routeGuardianReply(
       // If the text indicates rejection, use reject; otherwise approve_once.
       const action = inferActionFromText(codeResult.remainingText);
 
-      return applyDecision(request.id, action, actor, codeResult.remainingText, channelDeliveryContext);
+      return applyDecision(request.id, action, actor, codeResult.remainingText, channelDeliveryContext, emissionContext);
     }
   }
 
@@ -375,6 +386,7 @@ export async function routeGuardianReply(
           actor,
           messageText,
           channelDeliveryContext,
+          emissionContext,
         );
       }
 
@@ -475,12 +487,13 @@ export async function routeGuardianReply(
       };
     }
 
-    const result = await applyDecision(targetId, decisionAction, actor, messageText, channelDeliveryContext);
+    const result = await applyDecision(targetId, decisionAction, actor, messageText, channelDeliveryContext, emissionContext);
 
     // Attach the engine's reply text for stale/expired/identity-mismatch cases,
-    // but preserve the explicit failure text when the resolver failed — the engine
-    // reply is typically an affirmative confirmation that would be misleading.
-    if (engineResult.replyText && result.type !== 'canonical_resolver_failed') {
+    // but preserve resolver-authored replies (for example verification codes)
+    // and explicit resolver-failure text.
+    const hasResolverReplyText = Boolean(result.canonicalResult?.applied && result.canonicalResult.resolverReplyText);
+    if (engineResult.replyText && result.type !== 'canonical_resolver_failed' && !hasResolverReplyText) {
       result.replyText = engineResult.replyText;
     }
 
@@ -504,6 +517,7 @@ async function applyDecision(
   actor: ActorContext,
   userText?: string,
   channelDeliveryContext?: ChannelDeliveryContext,
+  emissionContext?: ResolverEmissionContext,
 ): Promise<GuardianReplyResult> {
   const canonicalResult = await applyCanonicalGuardianDecision({
     requestId,
@@ -511,6 +525,7 @@ async function applyDecision(
     actorContext: actor,
     userText,
     channelDeliveryContext,
+    emissionContext,
   });
 
   if (canonicalResult.applied) {
@@ -549,6 +564,7 @@ async function applyDecision(
       decisionApplied: true,
       consumed: true,
       type: 'canonical_decision_applied',
+      ...(canonicalResult.resolverReplyText ? { replyText: canonicalResult.resolverReplyText } : {}),
       requestId,
       canonicalResult,
     };
@@ -570,13 +586,15 @@ async function applyDecision(
     return notConsumed();
   }
 
+  const request = getCanonicalGuardianRequest(requestId);
+
   return {
     decisionApplied: false,
     consumed: true,
     type: 'canonical_decision_stale',
     requestId,
     canonicalResult,
-    replyText: failureReplyText(canonicalResult.reason),
+    replyText: failureReplyText(canonicalResult.reason, request?.requestCode, request ?? undefined),
   };
 }
 
@@ -643,6 +661,12 @@ function inferActionFromText(text: string): ApprovalAction {
   return 'approve_once';
 }
 
+function resolveRequestInstructionMode(
+  request?: Pick<CanonicalGuardianRequest, 'kind' | 'toolName'> | null,
+): 'approval' | 'answer' {
+  return resolveGuardianInstructionModeForRequest(request);
+}
+
 // ---------------------------------------------------------------------------
 // Failure reason reply text
 // ---------------------------------------------------------------------------
@@ -653,7 +677,11 @@ type CanonicalFailureReason = 'already_resolved' | 'identity_mismatch' | 'invali
  * Map a canonical decision failure reason to a distinct, actionable reply
  * so the guardian understands exactly what happened and what to do next.
  */
-function failureReplyText(reason: CanonicalFailureReason, requestCode?: string | null): string {
+function failureReplyText(
+  reason: CanonicalFailureReason,
+  requestCode?: string | null,
+  request?: CanonicalGuardianRequest,
+): string {
   switch (reason) {
     case 'already_resolved':
       return 'This request has already been resolved.';
@@ -662,9 +690,7 @@ function failureReplyText(reason: CanonicalFailureReason, requestCode?: string |
     case 'identity_mismatch':
       return "You don't have permission to decide on this request.";
     case 'invalid_action':
-      return requestCode
-        ? `I found request ${requestCode}, but I need to know your decision. Reply "${requestCode} approve" or "${requestCode} reject".`
-        : "I couldn't determine your intended action. Reply with the request code followed by 'approve' or 'reject' (e.g., \"ABC123 approve\").";
+      return buildGuardianInvalidActionReply(resolveRequestInstructionMode(request), requestCode ?? undefined);
     default:
       return "I couldn't process that request. Please try again.";
   }
@@ -681,15 +707,12 @@ function failureReplyText(reason: CanonicalFailureReason, requestCode?: string |
  */
 function composeCodeOnlyClarification(request: CanonicalGuardianRequest): string {
   const code = request.requestCode ?? 'unknown';
-  const toolLabel = request.toolName ?? 'an action';
-  const lines: string[] = [
-    `I found request ${code} for ${toolLabel}.`,
-  ];
-  if (request.questionText) {
-    lines.push(`Details: ${request.questionText}`);
-  }
-  lines.push(`Reply "${code} approve" to approve or "${code} reject" to reject.`);
-  return lines.join('\n');
+  const mode = resolveRequestInstructionMode(request);
+  return buildGuardianCodeOnlyClarification(mode, {
+    requestCode: code,
+    questionText: request.questionText,
+    toolName: request.toolName,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -706,6 +729,10 @@ function composeDisambiguationReply(
   engineReplyText?: string,
 ): string {
   const lines: string[] = [];
+  const requestsWithMode = pendingRequests.map((request) => ({
+    request,
+    mode: resolveRequestInstructionMode(request),
+  }));
 
   if (engineReplyText) {
     lines.push(engineReplyText);
@@ -714,16 +741,26 @@ function composeDisambiguationReply(
 
   lines.push(`You have ${pendingRequests.length} pending requests. Please specify which one:`);
 
-  for (const req of pendingRequests) {
-    const toolLabel = req.toolName ?? 'action';
-    const code = req.requestCode ?? req.id.slice(0, 6).toUpperCase();
+  for (const { request, mode } of requestsWithMode) {
+    const toolLabel = buildGuardianDisambiguationLabel(mode, {
+      questionText: request.questionText,
+      toolName: request.toolName,
+    });
+    const code = request.requestCode ?? request.id.slice(0, 6).toUpperCase();
     lines.push(`  - ${code}: ${toolLabel}`);
   }
 
-  // Include a concrete example using the first request's code
-  const exampleCode = pendingRequests[0].requestCode ?? pendingRequests[0].id.slice(0, 6).toUpperCase();
+  const questionRequest = requestsWithMode.find(({ mode }) => mode === 'answer');
+  const decisionRequest = requestsWithMode.find(({ mode }) => mode === 'approval');
   lines.push('');
-  lines.push(`Reply "${exampleCode} approve" to approve a specific request.`);
+  if (questionRequest) {
+    const exampleCode = questionRequest.request.requestCode ?? questionRequest.request.id.slice(0, 6).toUpperCase();
+    lines.push(buildGuardianDisambiguationExample(questionRequest.mode, exampleCode));
+  }
+  if (decisionRequest) {
+    const exampleCode = decisionRequest.request.requestCode ?? decisionRequest.request.id.slice(0, 6).toUpperCase();
+    lines.push(buildGuardianDisambiguationExample(decisionRequest.mode, exampleCode));
+  }
 
   return lines.join('\n');
 }

package/src/runtime/guardian-vellum-migration.ts

@@ -0,0 +1,57 @@
+/**
+ * Startup migration: backfill channel='vellum' guardian binding.
+ *
+ * On runtime start, ensures that a guardian binding exists for the
+ * 'vellum' channel with a guardianPrincipalId. This is required for
+ * the identity-bound hatch bootstrap flow.
+ *
+ * - If a vellum binding already exists, no-op.
+ * - If no vellum binding exists, creates one with a fresh principal.
+ * - Preserves existing guardian bindings for other channels unchanged.
+ */
+
+import { v4 as uuid } from 'uuid';
+
+import {
+  createBinding,
+  getActiveBinding,
+} from '../memory/guardian-bindings.js';
+import { getLogger } from '../util/logger.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
+
+const log = getLogger('guardian-vellum-migration');
+
+/**
+ * Ensure a vellum guardian binding exists for the given assistant.
+ * Called during daemon startup to backfill existing installations.
+ *
+ * Returns the guardianPrincipalId (existing or newly created).
+ */
+export function ensureVellumGuardianBinding(assistantId: string = DAEMON_INTERNAL_ASSISTANT_ID): string {
+  const existing = getActiveBinding(assistantId, 'vellum');
+  if (existing) {
+    log.debug(
+      { assistantId, guardianPrincipalId: existing.guardianExternalUserId },
+      'Vellum guardian binding already exists',
+    );
+    return existing.guardianExternalUserId;
+  }
+
+  const guardianPrincipalId = `vellum-principal-${uuid()}`;
+
+  createBinding({
+    assistantId,
+    channel: 'vellum',
+    guardianExternalUserId: guardianPrincipalId,
+    guardianDeliveryChatId: 'local',
+    verifiedVia: 'startup-migration',
+    metadataJson: JSON.stringify({ migratedAt: Date.now() }),
+  });
+
+  log.info(
+    { assistantId, guardianPrincipalId },
+    'Backfilled vellum guardian binding on startup',
+  );
+
+  return guardianPrincipalId;
+}