@vellumai/assistant 0.4.6 → 0.4.7

package/src/__tests__/notification-guardian-path.test.ts

@@ -37,24 +37,43 @@ mock.module('../util/logger.js', () => ({
 }));
 
 let mockTelegramBinding: unknown = null;
+let mockVellumBinding: unknown = null;
 
 mock.module('../memory/channel-guardian-store.js', () => ({
   getActiveBinding: (_assistantId: string, channel: string) => {
     if (channel === 'telegram') return mockTelegramBinding;
+    if (channel === 'vellum') return mockVellumBinding;
     return null;
   },
+  createBinding: (params: Record<string, unknown>) => ({
+    id: `binding-${Date.now()}`,
+    ...params,
+    status: 'active',
+    verifiedAt: Date.now(),
+    verifiedVia: 'test',
+    metadataJson: null,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  }),
+  listActiveBindingsByAssistant: () => mockVellumBinding ? [mockVellumBinding] : [],
 }));
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
     ui: {},
-    
+
     calls: {
       userConsultTimeoutSeconds: 120,
     },
   }),
 }));
 
+// Mock guardian-vellum-migration to use a stable principal, avoiding UNIQUE
+// constraint errors when ensureVellumGuardianBinding is called across tests.
+mock.module('../runtime/guardian-vellum-migration.js', () => ({
+  ensureVellumGuardianBinding: () => 'test-principal-id',
+}));
+
 const emitCalls: unknown[] = [];
 let mockThreadCreated: ThreadCreatedInfo | null = null;
 let mockEmitResult: {
@@ -114,12 +133,30 @@ function resetTables(): void {
   db.run('DELETE FROM canonical_guardian_requests');
   db.run('DELETE FROM guardian_action_deliveries');
   db.run('DELETE FROM guardian_action_requests');
+  db.run('DELETE FROM channel_guardian_bindings');
   db.run('DELETE FROM call_pending_questions');
   db.run('DELETE FROM call_events');
   db.run('DELETE FROM call_sessions');
   db.run('DELETE FROM conversations');
+
   emitCalls.length = 0;
   mockTelegramBinding = null;
+  // Pre-seed vellum binding so the self-healing path in dispatchGuardianQuestion
+  // never triggers (avoids UNIQUE constraint violations on repeated dispatches).
+  mockVellumBinding = {
+    id: 'binding-vellum-test',
+    assistantId: 'self',
+    channel: 'vellum',
+    guardianExternalUserId: 'vellum-guardian',
+    guardianDeliveryChatId: 'local',
+    guardianPrincipalId: 'test-principal-id',
+    status: 'active',
+    verifiedAt: Date.now(),
+    verifiedVia: 'test',
+    metadataJson: null,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
   mockThreadCreated = null;
   mockEmitResult = {
     signalId: 'sig-1',

package/src/__tests__/relay-server.test.ts

@@ -44,6 +44,13 @@ mock.module('../util/logger.js', () => ({
     }),
 }));
 
+// ── Identity helpers mock ─────────────────────────────────────────────
+
+let mockAssistantName: string | null = 'Vellum';
+mock.module('../daemon/identity-helpers.js', () => ({
+  getAssistantName: () => mockAssistantName,
+}));
+
 // ── Config mock ─────────────────────────────────────────────────────
 
 const mockConfig = {
@@ -1915,10 +1922,11 @@ describe('relay-server', () => {
     // Should be in the name capture state (not denied)
     expect(relay.getConnectionState()).toBe('awaiting_name');
 
-    // Should have sent the name capture prompt
+    // Should have sent the name capture prompt with assistant name + guardian label
     const textMessages = ws.sentMessages
       .map((raw) => JSON.parse(raw) as { type: string; token?: string })
       .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('Hi, this is Vellum,'))).toBe(true);
     expect(textMessages.some((m) => (m.token ?? '').includes("don't recognize this number"))).toBe(true);
     expect(textMessages.some((m) => (m.token ?? '').includes('Can I get your name'))).toBe(true);
 
@@ -1929,6 +1937,46 @@ describe('relay-server', () => {
     relay.destroy();
   });
 
+  test('inbound voice: unknown caller name capture uses fallback when assistant name is unavailable', async () => {
+    const prevName = mockAssistantName;
+    mockAssistantName = null;
+    try {
+      ensureConversation('conv-invite-no-name');
+      const session = createCallSession({
+        conversationId: 'conv-invite-no-name',
+        provider: 'twilio',
+        fromNumber: '+15558885556',
+        toNumber: '+15551111111',
+        assistantId: 'self',
+      });
+
+      const { ws, relay } = createMockWs(session.id);
+
+      await relay.handleMessage(JSON.stringify({
+        type: 'setup',
+        callSid: 'CA_invite_no_name',
+        from: '+15558885556',
+        to: '+15551111111',
+      }));
+
+      expect(relay.getConnectionState()).toBe('awaiting_name');
+
+      // Fallback prompt should NOT include assistant name but should include guardian label
+      const textMessages = ws.sentMessages
+        .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+        .filter((m) => m.type === 'text');
+      const promptText = textMessages.map((m) => m.token ?? '').join('');
+      expect(promptText).toContain("Hi, this is my guardian's assistant.");
+      expect(promptText).not.toContain('Vellum');
+      expect(promptText).toContain("don't recognize this number");
+      expect(promptText).toContain('Can I get your name');
+
+      relay.destroy();
+    } finally {
+      mockAssistantName = prevName;
+    }
+  });
+
   // ── Friend-initiated in-call guardian approval flow ────────────────────
 
   test('name capture flow: caller provides name and enters guardian decision wait', async () => {
@@ -2156,7 +2204,7 @@ describe('relay-server', () => {
     relay.destroy();
   });
 
-  test('name capture flow: approved access request activates caller and continues call', async () => {
+  test('name capture flow: approved access request activates caller with deterministic handoff copy', async () => {
     ensureConversation('conv-access-approved');
     const session = createCallSession({
       conversationId: 'conv-access-approved',
@@ -2166,9 +2214,10 @@ describe('relay-server', () => {
       assistantId: 'self',
     });
 
-    mockSendMessage.mockImplementation(createMockProviderResponse(['I can help you with that.']));
+    // Track provider calls to verify no LLM turn is triggered on approval
+    const providerCallCountBefore = mockSendMessage.mock.calls.length;
 
-    const { relay } = createMockWs(session.id);
+    const { ws, relay } = createMockWs(session.id);
 
     await relay.handleMessage(JSON.stringify({
       type: 'setup',
@@ -2209,9 +2258,20 @@ describe('relay-server', () => {
     // Should have transitioned to connected state
     expect(relay.getConnectionState()).toBe('connected');
 
-    // Verify events
+    // Verify deterministic handoff copy was sent (not an LLM-generated response)
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('said I can speak with you. How can I help?'))).toBe(true);
+
+    // Verify no provider (LLM) call was made as part of the approval handoff
+    expect(mockSendMessage.mock.calls.length).toBe(providerCallCountBefore);
+
+    // Verify events — including assistant_spoke for transcript parity
     const events = getCallEvents(session.id);
     expect(events.some((e) => e.eventType === 'inbound_acl_access_approved')).toBe(true);
+    expect(events.some((e) => e.eventType === 'assistant_spoke')).toBe(true);
+    expect(events.some((e) => e.eventType === 'inbound_acl_post_approval_handoff_spoken')).toBe(true);
 
     // Session should be in_progress
     const updated = getCallSession(session.id);

package/src/__tests__/send-endpoint-busy.test.ts

@@ -15,6 +15,7 @@ import { afterAll, beforeEach, describe, expect, mock,test } from 'bun:test';
 import type { ServerMessage } from '../daemon/ipc-protocol.js';
 import type { Session } from '../daemon/session.js';
 import { createCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
+import { createBinding } from '../memory/channel-guardian-store.js';
 import { getOrCreateConversation } from '../memory/conversation-key-store.js';
 
 const testDir = realpathSync(mkdtempSync(join(tmpdir(), 'send-endpoint-busy-test-')));
@@ -41,7 +42,7 @@ mock.module('../util/logger.js', () => ({
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
     ui: {},
-    
+
     model: 'test',
     provider: 'test',
     apiKeys: {},
@@ -51,6 +52,23 @@ mock.module('../config/loader.js', () => ({
   }),
 }));
 
+// Mock guardian-vellum-migration to use a stable principal matching the one
+// in createCanonicalGuardianRequest calls below ('test-principal-id').
+mock.module('../runtime/guardian-vellum-migration.js', () => ({
+  ensureVellumGuardianBinding: () => 'test-principal-id',
+}));
+
+// Mock local-actor-identity to return a stable guardian context that uses
+// the same principal as the canonical requests created in tests.
+mock.module('../runtime/local-actor-identity.js', () => ({
+  resolveLocalIpcGuardianContext: () => ({
+    sourceChannel: 'vellum',
+    trustClass: 'guardian',
+    guardianPrincipalId: 'test-principal-id',
+    guardianExternalUserId: 'test-principal-id',
+  }),
+}));
+
 import { getDb, initializeDb, resetDb } from '../memory/db.js';
 import type { AssistantEvent } from '../runtime/assistant-event.js';
 import { AssistantEventHub } from '../runtime/assistant-event-hub.js';
@@ -217,7 +235,17 @@ describe('POST /v1/messages — queue-if-busy and hub publishing', () => {
     db.run('DELETE FROM conversation_keys');
     db.run('DELETE FROM canonical_guardian_deliveries');
     db.run('DELETE FROM canonical_guardian_requests');
+    db.run('DELETE FROM channel_guardian_bindings');
     pendingInteractions.clear();
+
+    createBinding({
+      assistantId: 'self',
+      channel: 'vellum',
+      guardianExternalUserId: 'guardian-vellum',
+      guardianDeliveryChatId: 'vellum',
+      guardianPrincipalId: 'test-principal-id',
+    });
+
     eventHub = new AssistantEventHub();
   });
 

package/src/__tests__/tool-grant-request-escalation.test.ts

@@ -84,6 +84,7 @@ mock.module('../runtime/channel-guardian-service.js', () => ({
         channel: 'telegram',
         guardianExternalUserId: 'guardian-1',
         guardianDeliveryChatId: 'guardian-chat-1',
+        guardianPrincipalId: 'test-principal-id',
         status: 'active',
       };
     }

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

@@ -103,6 +103,7 @@ let mockGuardianBinding: Record<string, unknown> | null = {
   channel: 'telegram',
   guardianExternalUserId: 'guardian-1',
   guardianDeliveryChatId: 'guardian-chat-1',
+  guardianPrincipalId: 'test-principal-id',
   status: 'active',
 };
 
@@ -259,6 +260,7 @@ describe('(a) target flow: trusted-contact inline guardian approval end-to-end',
       channel: 'telegram',
       guardianExternalUserId: 'guardian-1',
       guardianDeliveryChatId: 'guardian-chat-1',
+      guardianPrincipalId: 'test-principal-id',
       status: 'active',
     };
   });
@@ -368,6 +370,7 @@ describe('(b) prompt-path flow: confirmation_request bridges to guardian', () =>
       channel: 'telegram',
       guardianExternalUserId: 'guardian-1',
       guardianDeliveryChatId: 'guardian-chat-1',
+      guardianPrincipalId: 'test-principal-id',
       status: 'active',
     };
   });
@@ -550,6 +553,7 @@ describe('(d) unknown actor flow: fail-closed with no interactive approval', ()
       channel: 'telegram',
       guardianExternalUserId: 'guardian-1',
       guardianDeliveryChatId: 'guardian-chat-1',
+      guardianPrincipalId: 'test-principal-id',
       status: 'active',
     };
   });
@@ -734,6 +738,7 @@ describe('(f) timeout/stale flow: stale guardian decision after inline wait time
       channel: 'telegram',
       guardianExternalUserId: 'guardian-1',
       guardianDeliveryChatId: 'guardian-chat-1',
+      guardianPrincipalId: 'test-principal-id',
       status: 'active',
     };
   });
@@ -948,6 +953,7 @@ describe('cross-milestone integration checks', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-1',
       guardianDeliveryChatId: 'guardian-chat-1',
+      guardianPrincipalId: 'test-principal-id',
       status: 'active',
     };
   });

package/src/__tests__/trusted-contact-lifecycle-notifications.test.ts

@@ -405,8 +405,8 @@ describe('trusted contact activated notification signal', () => {
     // Verify payload
     const payload = activatedSignals[0].contextPayload as Record<string, unknown>;
     expect(payload.sourceChannel).toBe('telegram');
-    expect(payload.externalUserId).toBe('requester-user-456');
-    expect(payload.externalChatId).toBe('chat-123');
+    expect(payload.actorExternalId).toBe('requester-user-456');
+    expect(payload.conversationExternalId).toBe('chat-123');
 
     // Verify deduplication key includes the user identity
     const dedupeKey = activatedSignals[0].dedupeKey as string;

package/src/__tests__/trusted-contact-multichannel.test.ts

@@ -221,7 +221,7 @@ for (const config of CHANNEL_CONFIGS) {
       // Guardian notification helper was called for the correct channel
       expect(notifyGuardianCalls.length).toBe(1);
       expect(notifyGuardianCalls[0].sourceChannel).toBe(config.channel);
-      expect(notifyGuardianCalls[0].senderExternalUserId).toBe(config.senderExternalUserId);
+      expect(notifyGuardianCalls[0].actorExternalId).toBe(config.senderExternalUserId);
     });
 
     test('verification creates active member for channel', () => {

package/src/calls/call-controller.ts

@@ -281,6 +281,21 @@ export class CallController {
     this.guardianContext = ctx;
   }
 
+  /**
+   * Mark the next caller utterance as an opening acknowledgment so it
+   * receives the [CALL_OPENING_ACK] marker. Used after deterministic
+   * transitions (e.g. post-approval handoff) to ensure the next LLM
+   * turn continues naturally without reintroduction.
+   *
+   * Also resets the silence timer so the "Are you still there?" nudge
+   * fires at the correct interval after the deterministic handoff copy.
+   */
+  markNextCallerTurnAsOpeningAck(): void {
+    this.awaitingOpeningAck = true;
+    this.lastSentWasOpener = false;
+    this.resetSilenceTimer();
+  }
+
   /**
    * Kick off the first outbound call utterance from the assistant.
    */

package/src/calls/relay-server.ts

@@ -11,6 +11,7 @@ import { randomInt } from 'node:crypto';
 import type { ServerWebSocket } from 'bun';
 
 import { getConfig } from '../config/loader.js';
+import { getAssistantName } from '../daemon/identity-helpers.js';
 import { getCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
 import { listActiveBindingsByAssistant } from '../memory/channel-guardian-store.js';
 import * as conversationStore from '../memory/conversation-store.js';
@@ -1104,10 +1105,14 @@ export class RelayConnection {
     this.accessRequestFromNumber = fromNumber;
     this.connectionState = 'awaiting_name';
 
-    this.sendTextToken(
-      "Sorry, I don't recognize this number. I'll let my guardian know you called and see if I have permission to speak with you. Can I get your name?",
-      true,
-    );
+    const guardianLabel = this.resolveGuardianLabel();
+    const assistantName = this.resolveAssistantLabel();
+
+    const greeting = assistantName
+      ? `Hi, this is ${assistantName}, ${guardianLabel}'s assistant. Sorry, I don't recognize this number. I'll let ${guardianLabel} know you called and see if I have permission to speak with you. Can I get your name?`
+      : `Hi, this is ${guardianLabel}'s assistant. Sorry, I don't recognize this number. I'll let ${guardianLabel} know you called and see if I have permission to speak with you. Can I get your name?`;
+
+    this.sendTextToken(greeting, true);
 
     // Start a timeout so silent callers don't keep the call open indefinitely.
     // Uses a 30-second window — enough time to speak a name but short enough
@@ -1325,15 +1330,31 @@ export class RelayConnection {
       'Access request approved — caller activated and continuing call',
     );
 
-    // Use handleUserInstruction to deliver the approval-aware greeting
-    // through the normal session pipeline.
+    // Deliver deterministic transition copy directly via TTS instead of
+    // routing through handleUserInstruction, which would start a fresh
+    // model turn and risk reintroduction/disclosure reset.
     const guardianLabel = this.resolveGuardianLabel();
+    const handoffText = `Great! ${guardianLabel} said I can speak with you. How can I help?`;
+    this.sendTextToken(handoffText, true);
+
+    // Record the deterministic handoff as an assistant_spoke event and
+    // fire the transcript notifier so it appears in conversation history
+    // and real-time transcript subscribers — matching the parity of text
+    // spoken through the normal runTurn() pipeline.
+    recordCallEvent(this.callSessionId, 'assistant_spoke', { text: handoffText });
+    const session = getCallSession(this.callSessionId);
+    if (session) {
+      fireCallTranscriptNotifier(session.conversationId, this.callSessionId, 'assistant', handoffText);
+    }
+
+    recordCallEvent(this.callSessionId, 'inbound_acl_post_approval_handoff_spoken', {
+      from: fromNumber,
+    });
+
+    // Mark the next caller utterance as an opening acknowledgment so the
+    // LLM continues naturally without emitting a fresh introduction.
     if (this.controller) {
-      this.controller.handleUserInstruction(
-        `Great, ${guardianLabel} approved! Now how can I help you?`,
-      ).catch((err) => {
-        log.error({ err, callSessionId: this.callSessionId }, 'Failed to deliver approval greeting');
-      });
+      this.controller.markNextCallerTurnAsOpeningAck();
     }
   }
 
@@ -1672,6 +1693,19 @@ export class RelayConnection {
     return 'my guardian';
   }
 
+  /**
+   * Resolve the assistant's display name from identity configuration.
+   * Returns the trimmed name or null if unavailable.
+   */
+  private resolveAssistantLabel(): string | null {
+    try {
+      const name = getAssistantName();
+      return name?.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Generate a non-repetitive heartbeat message for the caller based
    * on the current sequence counter and guardian label.

package/src/calls/types.ts

@@ -1,5 +1,6 @@
 export type CallStatus = 'initiated' | 'ringing' | 'in_progress' | 'waiting_on_user' | 'completed' | 'failed' | 'cancelled';
 export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed' | 'callee_verification_started' | 'callee_verification_succeeded' | 'callee_verification_failed' | 'guardian_voice_verification_started' | 'guardian_voice_verification_succeeded' | 'guardian_voice_verification_failed' | 'outbound_guardian_voice_verification_started' | 'outbound_guardian_voice_verification_succeeded' | 'outbound_guardian_voice_verification_failed' | 'guardian_consultation_timed_out' | 'guardian_unavailable_skipped' | 'guardian_consult_deferred' | 'guardian_consult_coalesced' | 'inbound_acl_denied' | 'inbound_acl_name_capture_started' | 'inbound_acl_name_captured' | 'inbound_acl_name_capture_timeout' | 'inbound_acl_access_approved' | 'inbound_acl_access_denied' | 'inbound_acl_access_timeout' | 'invite_redemption_started' | 'invite_redemption_succeeded' | 'invite_redemption_failed' | 'voice_guardian_wait_heartbeat_sent' | 'voice_guardian_wait_prompt_classified' | 'voice_guardian_wait_callback_offer_sent' | 'voice_guardian_wait_callback_opt_in_set' | 'voice_guardian_wait_callback_opt_in_declined'
+  | 'inbound_acl_post_approval_handoff_spoken'
   | 'callback_handoff_notified'
   | 'callback_handoff_failed';
 export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';

package/src/daemon/providers-setup.ts

@@ -21,32 +21,24 @@ import { slackProvider as slackWatcherProvider } from '../watcher/providers/slac
 const log = getLogger('lifecycle');
 
 export async function initializeProvidersAndTools(config: AssistantConfig): Promise<void> {
-  console.log('[Daemon] Initializing providers and tools...');
   log.info('Daemon startup: initializing providers and tools');
   initializeProviders(config);
-  console.log('[Daemon] Providers initialized');
   await initializeTools();
-  console.log('[Daemon] Tools initialized');
 
   // Start MCP servers and register their tools
   if (config.mcp?.servers && Object.keys(config.mcp.servers).length > 0) {
-    console.log('[MCP] Initializing MCP servers:', Object.keys(config.mcp.servers).join(', '));
     const manager = getMcpServerManager();
     try {
       const serverToolInfos = await manager.start(config.mcp);
       for (const { serverId, serverConfig, tools } of serverToolInfos) {
-        console.log(`[MCP] Server "${serverId}" connected — discovered ${tools.length} tools:`, tools.map(t => t.name).join(', '));
         const mcpTools = createMcpToolsFromServer(tools, serverId, serverConfig, manager);
         registerMcpTools(mcpTools);
-        console.log(`[MCP] Registered ${mcpTools.length} tools from "${serverId}":`, mcpTools.map(t => t.name).join(', '));
       }
     } catch (err) {
-      console.error('[MCP] Server initialization failed:', err);
       log.error({ err }, 'MCP server initialization failed — continuing without MCP tools');
     }
   }
 
-  console.log('[Daemon] Providers and tools initialization complete');
   log.info('Daemon startup: providers and tools initialized');
 }
 

package/src/daemon/session-slash.ts

@@ -1,4 +1,8 @@
 import { randomBytes, randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import QRCode from 'qrcode';
 
 import { getGatewayPort, getIngressPublicBaseUrl } from '../config/env.js';
 import { getConfig, loadRawConfig, saveRawConfig } from '../config/loader.js';
@@ -11,13 +15,14 @@ import {
   rewriteKnownSlashCommandPrompt,
 } from '../skills/slash-commands.js';
 import { getLocalIPv4 } from '../util/network-info.js';
+import { getWorkspaceDir } from '../util/platform.js';
 import { getAssistantName } from './identity-helpers.js';
 import type { PairingStore } from './pairing-store.js';
 
 export type SlashResolution =
   | { kind: 'passthrough'; content: string }
   | { kind: 'rewritten'; content: string; skillId: string }
-  | { kind: 'unknown'; message: string };
+  | { kind: 'unknown'; message: string; qrFilename?: string };
 
 // ── /pair command — module-level pairing context ────────────────────
 
@@ -349,6 +354,27 @@ export function resolveSlash(content: string, context?: SlashContext): SlashReso
 
 // ── /pair command ────────────────────────────────────────────────────
 
+function buildPairingQRCodeFilename(): string {
+  const now = new Date();
+  const ts = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+    String(now.getHours()).padStart(2, '0'),
+    String(now.getMinutes()).padStart(2, '0'),
+    String(now.getSeconds()).padStart(2, '0'),
+  ].join('');
+  return `code${ts}.png`;
+}
+
+async function savePairingQRCodePng(payloadJson: string, filename: string): Promise<void> {
+  const qrDir = join(getWorkspaceDir(), 'pairing-qr');
+  mkdirSync(qrDir, { recursive: true });
+  const qrPngPath = join(qrDir, filename);
+  const pngBuffer = await QRCode.toBuffer(payloadJson, { type: 'png', width: 512 });
+  writeFileSync(qrPngPath, pngBuffer);
+}
+
 function resolvePairCommand(content: string): SlashResolution | null {
   if (content.trim() !== '/pair') return null;
 
@@ -402,6 +428,12 @@ function resolvePairCommand(content: string): SlashResolution | null {
     payload.localLanUrl = localLanUrl;
   }
 
+  // Save QR code as PNG to the workspace pairing-qr folder (fire-and-forget
+  // so the synchronous slash resolution is not blocked).
+  const payloadJson = JSON.stringify(payload);
+  const qrFilename = buildPairingQRCodeFilename();
+  savePairingQRCodePng(payloadJson, qrFilename).catch(() => {});
+
   const lines = [
     'Pairing Ready\n',
     'Scan the QR code below with the Vellum iOS app, or use the pairing payload to connect manually.\n',
@@ -414,10 +446,11 @@ function resolvePairCommand(content: string): SlashResolution | null {
     lines.push(`LAN URL:  ${localLanUrl}`);
   }
   lines.push(
+    `\nQR code saved to pairing-qr/${qrFilename}`,
     '\nThis pairing request expires in 5 minutes. Run `/pair` again to generate a new one.',
   );
 
-  return { kind: 'unknown', message: lines.join('\n') };
+  return { kind: 'unknown', message: lines.join('\n'), qrFilename };
 }
 
 // ── Provider Ordering Error Detection ────────────────────────────────

package/src/memory/db-init.ts

@@ -1,6 +1,7 @@
 import { getDb } from './db-connection.js';
 import {
   addCoreColumns,
+  createActorRefreshTokenRecordsTable,
   createActorTokenRecordsTable,
   createAssistantInboxTables,
   createCallSessionsTables,
@@ -175,6 +176,9 @@ export function initializeDb(): void {
   // 28. Actor token records (hash-only actor token persistence)
   createActorTokenRecordsTable(database);
 
+  // 28b. Actor refresh token records (rotating refresh tokens with family tracking)
+  createActorRefreshTokenRecordsTable(database);
+
   // 29. Guardian principal ID columns on channel_guardian_bindings and canonical_guardian_requests
   migrateGuardianPrincipalIdColumns(database);
 

package/src/memory/migrations/039-actor-refresh-token-records.ts

@@ -0,0 +1,51 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Create the actor_refresh_token_records table for hash-only refresh token persistence.
+ *
+ * Stores the SHA-256 hash of each refresh token with family tracking,
+ * device binding, and dual expiry (absolute + inactivity).
+ * The raw token plaintext is never stored.
+ */
+export function createActorRefreshTokenRecordsTable(database: DrizzleDb): void {
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS actor_refresh_token_records (
+      id TEXT PRIMARY KEY,
+      token_hash TEXT NOT NULL,
+      family_id TEXT NOT NULL,
+      assistant_id TEXT NOT NULL,
+      guardian_principal_id TEXT NOT NULL,
+      hashed_device_id TEXT NOT NULL,
+      platform TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      issued_at INTEGER NOT NULL,
+      absolute_expires_at INTEGER NOT NULL,
+      inactivity_expires_at INTEGER NOT NULL,
+      last_used_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  // Token hash lookup (any status — needed for replay detection)
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_refresh_tokens_hash
+      ON actor_refresh_token_records(token_hash)`,
+  );
+
+  // Unique active refresh token per device binding.
+  // DROP first so that databases that already created the older non-unique
+  // index with the same name get upgraded to UNIQUE.
+  database.run(/*sql*/ `DROP INDEX IF EXISTS idx_refresh_tokens_active_device`);
+  database.run(
+    /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_refresh_tokens_active_device
+      ON actor_refresh_token_records(assistant_id, guardian_principal_id, hashed_device_id)
+      WHERE status = 'active'`,
+  );
+
+  // Family lookup for replay detection (revoke entire family)
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_refresh_tokens_family
+      ON actor_refresh_token_records(family_id)`,
+  );
+}

package/src/memory/migrations/index.ts

@@ -40,6 +40,7 @@ export { migrateGuardianActionSupersession } from './035-guardian-action-superse
 export { migrateNormalizePhoneIdentities } from './036-normalize-phone-identities.js';
 export { migrateVoiceInviteColumns } from './037-voice-invite-columns.js';
 export { createActorTokenRecordsTable } from './038-actor-token-records.js';
+export { createActorRefreshTokenRecordsTable } from './039-actor-refresh-token-records.js';
 export { createCoreTables } from './100-core-tables.js';
 export { createWatchersAndLogsTables } from './101-watchers-and-logs.js';
 export { addCoreColumns } from './102-alter-table-columns.js';

package/src/memory/migrations/registry.ts

@@ -96,7 +96,7 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     description: 'Normalize phone-like identity fields to E.164 format across guardian bindings, verification challenges, canonical requests, ingress members, and rate limits',
   },
   {
-    key: 'migration_backfill_guardian_principal_id_v2',
+    key: 'migration_backfill_guardian_principal_id_v3',
     version: 15,
     description: 'Backfill guardianPrincipalId for existing channel_guardian_bindings and canonical_guardian_requests rows, expire unresolvable pending requests',
   },