@vellumai/assistant 0.3.16 → 0.3.18

package/src/__tests__/voice-session-bridge.test.ts

@@ -8,6 +8,18 @@ import type { ServerMessage } from '../daemon/ipc-protocol.js';
 import type { Session } from '../daemon/session.js';
 
 const testDir = mkdtempSync(join(tmpdir(), 'voice-bridge-test-'));
+let mockedConfig: {
+  secretDetection: { enabled: boolean };
+  calls: { disclosure: { enabled: boolean; text: string } };
+} = {
+  secretDetection: { enabled: false },
+  calls: {
+    disclosure: {
+      enabled: false,
+      text: '',
+    },
+  },
+};
 
 mock.module('../util/platform.js', () => ({
   getRootDir: () => testDir,
@@ -29,15 +41,7 @@ mock.module('../util/logger.js', () => ({
 }));
 
 mock.module('../config/loader.js', () => ({
-  getConfig: () => ({
-    secretDetection: { enabled: false },
-    calls: {
-      disclosure: {
-        enabled: false,
-        text: '',
-      },
-    },
-  }),
+  getConfig: () => mockedConfig,
 }));
 
 import { setVoiceBridgeDeps, startVoiceTurn } from '../calls/voice-session-bridge.js';
@@ -85,6 +89,15 @@ function injectDeps(sessionFactory: () => Session): void {
 
 describe('voice-session-bridge', () => {
   beforeEach(() => {
+    mockedConfig = {
+      secretDetection: { enabled: false },
+      calls: {
+        disclosure: {
+          enabled: false,
+          text: '',
+        },
+      },
+    };
     const db = getDb();
     db.run('DELETE FROM messages');
     db.run('DELETE FROM conversations');
@@ -415,6 +428,93 @@ describe('voice-session-bridge', () => {
     expect(capturedGuardianContext).toEqual(guardianCtx);
   });
 
+  test('inbound non-guardian opener prompt uses pickup framing instead of outbound phrasing', async () => {
+    const conversation = createConversation('voice bridge inbound opener framing test');
+    const events: ServerMessage[] = [
+      { type: 'message_complete', sessionId: conversation.id },
+    ];
+
+    let capturedPrompt: string | null = null;
+    const session = {
+      ...makeStreamingSession(events),
+      setVoiceCallControlPrompt: (prompt: string | null) => {
+        if (prompt != null) capturedPrompt = prompt;
+      },
+    } as unknown as Session;
+
+    injectDeps(() => session);
+
+    await startVoiceTurn({
+      conversationId: conversation.id,
+      content: 'Hello there',
+      isInbound: true,
+      guardianContext: {
+        sourceChannel: 'voice',
+        actorRole: 'non-guardian',
+      },
+      onTextDelta: () => {},
+      onComplete: () => {},
+      onError: () => {},
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+    if (!capturedPrompt) throw new Error('Expected voice call control prompt to be set');
+    const prompt: string = capturedPrompt;
+
+    expect(prompt).toContain('this is an inbound call you are answering (not a call you initiated)');
+    expect(prompt).toContain('Introduce yourself once at the start using your assistant name if you know it');
+    expect(prompt).toContain('If your assistant name is not known, skip the name and just identify yourself as the guardian\'s assistant.');
+    expect(prompt).toContain('Do NOT say "I\'m calling" or "I\'m calling on behalf of".');
+  });
+
+  test('inbound disclosure guidance is rewritten for pickup context', async () => {
+    mockedConfig = {
+      secretDetection: { enabled: false },
+      calls: {
+        disclosure: {
+          enabled: true,
+          text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent.',
+        },
+      },
+    };
+
+    const conversation = createConversation('voice bridge inbound disclosure rewrite test');
+    const events: ServerMessage[] = [
+      { type: 'message_complete', sessionId: conversation.id },
+    ];
+
+    let capturedPrompt: string | null = null;
+    const session = {
+      ...makeStreamingSession(events),
+      setVoiceCallControlPrompt: (prompt: string | null) => {
+        if (prompt != null) capturedPrompt = prompt;
+      },
+    } as unknown as Session;
+
+    injectDeps(() => session);
+
+    await startVoiceTurn({
+      conversationId: conversation.id,
+      content: 'Hi',
+      isInbound: true,
+      guardianContext: {
+        sourceChannel: 'voice',
+        actorRole: 'non-guardian',
+      },
+      onTextDelta: () => {},
+      onComplete: () => {},
+      onError: () => {},
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+    if (!capturedPrompt) throw new Error('Expected voice call control prompt to be set');
+    const prompt: string = capturedPrompt;
+
+    expect(prompt).toContain('At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent.');
+    expect(prompt).toContain('rewrite any disclosure naturally for pickup context');
+    expect(prompt).toContain('Do NOT say "I\'m calling", "I called you", or "I\'m calling on behalf of".');
+  });
+
   test('auto-denies confirmation requests for non-guardian voice turns', async () => {
     const conversation = createConversation('voice bridge auto-deny non-guardian test');
 

package/src/calls/call-controller.ts

@@ -8,6 +8,7 @@
  * barge-in, state machine, guardian verification).
  */
 
+import { getGatewayInternalBaseUrl } from '../config/env.js';
 import type { ServerMessage } from '../daemon/ipc-contract.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 import {
@@ -16,6 +17,7 @@ import {
   markTimedOutWithReason,
 } from '../memory/guardian-action-store.js';
 import { getLogger } from '../util/logger.js';
+import { readHttpToken } from '../util/platform.js';
 import { getMaxCallDurationMs, getUserConsultationTimeoutMs, SILENCE_TIMEOUT_MS } from './call-constants.js';
 import { persistCallCompletionMessage } from './call-conversation-messages.js';
 import { addPointerMessage, formatDuration } from './call-pointer-messages.js';
@@ -27,10 +29,8 @@ import {
   recordCallEvent,
   updateCallSession,
 } from './call-store.js';
-import { getGatewayInternalBaseUrl } from '../config/env.js';
-import { readHttpToken } from '../util/platform.js';
-import { dispatchGuardianQuestion } from './guardian-dispatch.js';
 import { sendGuardianExpiryNotices } from './guardian-action-sweep.js';
+import { dispatchGuardianQuestion } from './guardian-dispatch.js';
 import type { RelayConnection } from './relay-server.js';
 import type { PromptSpeakerContext } from './speaker-identification.js';
 import { startVoiceTurn, type VoiceTurnHandle } from './voice-session-bridge.js';
@@ -41,6 +41,104 @@ type ControllerState = 'idle' | 'processing' | 'waiting_on_user' | 'speaking';
 
 const ASK_GUARDIAN_CAPTURE_REGEX = /\[ASK_GUARDIAN:\s*(.+?)\]/;
 const ASK_GUARDIAN_MARKER_REGEX = /\[ASK_GUARDIAN:\s*.+?\]/g;
+
+// Flexible prefix for ASK_GUARDIAN_APPROVAL — tolerates variable whitespace
+// after the colon so the marker is recognized even if the model omits the
+// space or inserts a newline.
+const ASK_GUARDIAN_APPROVAL_PREFIX_RE = /\[ASK_GUARDIAN_APPROVAL:\s*/;
+
+/**
+ * Extract a balanced JSON object from text that starts with an
+ * ASK_GUARDIAN_APPROVAL prefix. Uses brace counting with string-literal
+ * awareness so that `}` or `}]` inside JSON string values does not
+ * terminate the match prematurely.
+ *
+ * Returns the extracted JSON string, the full marker text
+ * (prefix + JSON + "]"), and the start index — or null when:
+ *   - no prefix is found,
+ *   - braces are unbalanced (still streaming), or
+ *   - the closing `]` has not yet arrived (prevents stripping
+ *     the marker body while the bracket leaks into TTS in a later delta).
+ */
+function extractBalancedJson(
+  text: string,
+): { json: string; fullMatch: string; startIndex: number } | null {
+  const prefixMatch = ASK_GUARDIAN_APPROVAL_PREFIX_RE.exec(text);
+  if (!prefixMatch) return null;
+
+  const prefixIdx = prefixMatch.index;
+  const jsonStart = prefixIdx + prefixMatch[0].length;
+  if (jsonStart >= text.length || text[jsonStart] !== '{') return null;
+
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+
+  for (let i = jsonStart; i < text.length; i++) {
+    const ch = text[i];
+
+    if (escape) {
+      escape = false;
+      continue;
+    }
+
+    if (ch === '\\' && inString) {
+      escape = true;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+
+    if (inString) continue;
+
+    if (ch === '{') {
+      depth++;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        const jsonEnd = i + 1;
+        const json = text.slice(jsonStart, jsonEnd);
+        // Skip any whitespace between the closing '}' and the expected ']'.
+        // Models sometimes emit formatted markers with spaces or newlines
+        // before the bracket (e.g. `{ ... }\n]` or `{ ... } ]`).
+        let bracketIdx = jsonEnd;
+        while (bracketIdx < text.length && /\s/.test(text[bracketIdx])) {
+          bracketIdx++;
+        }
+        // Require the closing ']' to be present before considering this
+        // a complete match. If it hasn't arrived yet (streaming), return
+        // null so the caller keeps buffering.
+        if (bracketIdx >= text.length || text[bracketIdx] !== ']') {
+          return null;
+        }
+        const fullMatchEnd = bracketIdx + 1;
+        const fullMatch = text.slice(prefixIdx, fullMatchEnd);
+        return { json, fullMatch, startIndex: prefixIdx };
+      }
+    }
+  }
+
+  return null; // Unbalanced braces — still streaming
+}
+
+/**
+ * Strip all balanced ASK_GUARDIAN_APPROVAL markers from text, handling
+ * nested braces, string literals, and flexible whitespace correctly.
+ * Only strips complete markers (prefix + balanced JSON + closing `]`).
+ */
+function stripGuardianApprovalMarkers(text: string): string {
+  let result = text;
+  for (;;) {
+    const match = extractBalancedJson(result);
+    if (!match) break;
+    result = result.slice(0, match.startIndex) + result.slice(match.startIndex + match.fullMatch.length);
+  }
+  return result;
+}
+
 const USER_ANSWERED_MARKER_REGEX = /\[USER_ANSWERED:\s*.+?\]/g;
 const USER_INSTRUCTION_MARKER_REGEX = /\[USER_INSTRUCTION:\s*.+?\]/g;
 const CALL_OPENING_MARKER_REGEX = /\[CALL_OPENING\]/g;
@@ -53,7 +151,8 @@ const CALL_OPENING_ACK_MARKER = '[CALL_OPENING_ACK]';
 const END_CALL_MARKER = '[END_CALL]';
 
 function stripInternalSpeechMarkers(text: string): string {
-  return text
+  let result = stripGuardianApprovalMarkers(text);
+  result = result
     .replace(ASK_GUARDIAN_MARKER_REGEX, '')
     .replace(USER_ANSWERED_MARKER_REGEX, '')
     .replace(USER_INSTRUCTION_MARKER_REGEX, '')
@@ -62,6 +161,7 @@ function stripInternalSpeechMarkers(text: string): string {
     .replace(END_CALL_MARKER_REGEX, '')
     .replace(GUARDIAN_TIMEOUT_MARKER_REGEX, '')
     .replace(GUARDIAN_UNAVAILABLE_MARKER_REGEX, '');
+  return result;
 }
 
 export class CallController {
@@ -414,6 +514,7 @@ export class CallController {
           // bracketed text (e.g. "[A]", "[note]") doesn't stall TTS.
           const afterBracket = ttsBuffer;
           const couldBeControl =
+            '[ASK_GUARDIAN_APPROVAL:'.startsWith(afterBracket) ||
             '[ASK_GUARDIAN:'.startsWith(afterBracket) ||
             '[USER_ANSWERED:'.startsWith(afterBracket) ||
             '[USER_INSTRUCTION:'.startsWith(afterBracket) ||
@@ -422,6 +523,7 @@ export class CallController {
             '[END_CALL]'.startsWith(afterBracket) ||
             '[GUARDIAN_TIMEOUT]'.startsWith(afterBracket) ||
             '[GUARDIAN_UNAVAILABLE]'.startsWith(afterBracket) ||
+            afterBracket.startsWith('[ASK_GUARDIAN_APPROVAL:') ||
             afterBracket.startsWith('[ASK_GUARDIAN:') ||
             afterBracket.startsWith('[USER_ANSWERED:') ||
             afterBracket.startsWith('[USER_INSTRUCTION:') ||
@@ -528,11 +630,30 @@ export class CallController {
         }
       }
 
-      // Check for ASK_GUARDIAN pattern
-      const askMatch = responseText.match(ASK_GUARDIAN_CAPTURE_REGEX);
-      if (askMatch) {
-        const questionText = askMatch[1];
+      // Check for structured tool-approval ASK_GUARDIAN_APPROVAL first,
+      // then informational ASK_GUARDIAN. Uses brace-balanced extraction so
+      // `}]` inside JSON string values does not truncate the payload or
+      // leak partial JSON into TTS output.
+      const approvalMatch = extractBalancedJson(responseText);
+      let approvalQuestion: string | null = null;
+      if (approvalMatch) {
+        try {
+          const parsed = JSON.parse(approvalMatch.json) as { question?: string };
+          if (parsed.question) {
+            approvalQuestion = parsed.question;
+          }
+        } catch {
+          log.warn({ callSessionId: this.callSessionId }, 'Failed to parse ASK_GUARDIAN_APPROVAL JSON payload');
+        }
+      }
+
+      const askMatch = approvalQuestion
+        ? null // structured approval takes precedence
+        : responseText.match(ASK_GUARDIAN_CAPTURE_REGEX);
+
+      const questionText = approvalQuestion ?? (askMatch ? askMatch[1] : null);
 
+      if (questionText) {
         if (this.isCallerGuardian()) {
           // Caller IS the guardian — don't dispatch cross-channel.
           // Queue an instruction so the next turn asks them directly.

package/src/calls/guardian-action-sweep.ts

@@ -17,8 +17,8 @@ import {
   getExpiredGuardianActionRequests,
 } from '../memory/guardian-action-store.js';
 import { deliverChannelReply } from '../runtime/gateway-client.js';
-import type { GuardianActionCopyGenerator } from '../runtime/http-types.js';
 import { composeGuardianActionMessageGenerative } from '../runtime/guardian-action-message-composer.js';
+import type { GuardianActionCopyGenerator } from '../runtime/http-types.js';
 import { getLogger } from '../util/logger.js';
 import { expirePendingQuestions } from './call-store.js';
 

package/src/calls/guardian-dispatch.ts

@@ -9,6 +9,7 @@
 
 import { getActiveBinding } from '../memory/channel-guardian-store.js';
 import {
+  countPendingRequestsByCallSessionId,
   createGuardianActionDelivery,
   createGuardianActionRequest,
   updateDeliveryStatus,
@@ -69,6 +70,12 @@ export async function dispatchGuardianQuestion(params: GuardianDispatchParams):
       'Created guardian action request',
     );
 
+    // Count how many guardian requests are already pending for this call.
+    // This count is a candidate-affinity hint: the decision engine uses it
+    // to prefer reusing an existing thread when multiple questions arise
+    // in the same call session.
+    const activeGuardianRequestCount = countPendingRequestsByCallSessionId(callSessionId);
+
     // Route through the canonical notification pipeline. The paired vellum
     // conversation from this pipeline is the canonical guardian thread.
     let vellumDeliveryId: string | null = null;
@@ -90,6 +97,7 @@ export async function dispatchGuardianQuestion(params: GuardianDispatchParams):
         callSessionId,
         questionText: pendingQuestion.questionText,
         pendingQuestionId: pendingQuestion.id,
+        activeGuardianRequestCount,
       },
       dedupeKey: `guardian:${request.id}`,
       onThreadCreated: (info) => {

package/src/calls/voice-session-bridge.ts

@@ -129,7 +129,9 @@ function buildVoiceCallControlPrompt(opts: {
   const disclosureEnabled = config.calls?.disclosure?.enabled === true;
   const disclosureText = config.calls?.disclosure?.text?.trim();
   const disclosureRule = disclosureEnabled && disclosureText
-    ? `0. ${disclosureText}`
+    ? opts.isInbound
+      ? `0. ${disclosureText} This is an inbound call you are answering, so rewrite any disclosure naturally for pickup context. Do NOT say "I'm calling", "I called you", or "I'm calling on behalf of".`
+      : `0. ${disclosureText}`
     : '0. Begin the conversation naturally.';
 
   const lines: string[] = ['<voice_call_control>'];
@@ -174,7 +176,7 @@ function buildVoiceCallControlPrompt(opts: {
       );
     } else {
       lines.push(
-        '7. If the latest user turn is "(call connected — deliver opening greeting)", greet the caller warmly and ask how you can help. Vary the wording; do not use a fixed template.',
+        '7. If the latest user turn is "(call connected — deliver opening greeting)", this is an inbound call you are answering (not a call you initiated). Greet the caller warmly and ask how you can help. Introduce yourself once at the start using your assistant name if you know it (for example: "Hey there, this is Ava, Sam\'s assistant. How can I help?"). If your assistant name is not known, skip the name and just identify yourself as the guardian\'s assistant. Do NOT say "I\'m calling" or "I\'m calling on behalf of". Vary the wording; do not use a fixed template.',
       );
     }
     lines.push(

package/src/cli/core-commands.ts

@@ -109,7 +109,7 @@ export function registerDevCommand(program: Command): void {
     .command('dev')
     .description('Run the daemon in dev mode with auto-restart on file changes')
     .action(async () => {
-      const status = await getDaemonStatus();
+      let status = await getDaemonStatus();
       if (status.running) {
         log.info('Stopping existing daemon...');
         const stopResult = await stopDaemon();
@@ -117,6 +117,46 @@ export function registerDevCommand(program: Command): void {
           log.error('Failed to stop existing daemon — process survived SIGKILL');
           process.exit(1);
         }
+      } else if (status.pid) {
+        // PID file references a live process but the socket is unresponsive.
+        // This can happen during the daemon startup window before the socket
+        // is bound. Wait briefly for it to come up before replacing.
+        log.info('Daemon process alive but socket unresponsive — waiting for startup...');
+        const maxWait = 5000;
+        const interval = 500;
+        let waited = 0;
+        let resolved = false;
+        while (waited < maxWait) {
+          await new Promise((r) => setTimeout(r, interval));
+          waited += interval;
+          status = await getDaemonStatus();
+          if (status.running) {
+            // Socket came up — stop the daemon normally.
+            log.info('Daemon became responsive, stopping it...');
+            const stopResult = await stopDaemon();
+            if (!stopResult.stopped && stopResult.reason === 'stop_failed') {
+              log.error('Failed to stop existing daemon — process survived SIGKILL');
+              process.exit(1);
+            }
+            resolved = true;
+            break;
+          }
+          if (!status.pid) {
+            // Process exited on its own — PID file already cleaned up.
+            resolved = true;
+            break;
+          }
+        }
+        if (!resolved) {
+          // Still alive but unresponsive after waiting — stop it via stopDaemon()
+          // which handles SIGTERM → SIGKILL escalation and PID file cleanup.
+          log.info('Daemon still unresponsive after wait — stopping it...');
+          const stopResult = await stopDaemon();
+          if (!stopResult.stopped && stopResult.reason === 'stop_failed') {
+            log.error('Failed to stop existing daemon — process survived SIGKILL');
+            process.exit(1);
+          }
+        }
       }
 
       const mainPath = `${import.meta.dirname}/../daemon/main.ts`;

package/src/config/templates/UPDATES.md

@@ -1,7 +1,5 @@
 _ Lines starting with _ are comments — they won't appear in the system prompt
-
-# UPDATES.md
-
+_
 _ This file contains release update notes for the assistant.
 _ Each release block is wrapped with HTML comment markers:
 _   <!-- vellum-update-release:<version> -->
@@ -11,6 +9,7 @@ _
 _ Format is freeform markdown. Write notes that help the assistant
 _ understand what changed and how it affects behavior, capabilities,
 _ or available tools. Focus on what matters to the user experience.
-
-## What's New
-
+_
+_ To add release notes, replace this content with real markdown
+_ describing what changed. The sync will only materialize a bulletin
+_ when non-comment content is present.

package/src/config/update-bulletin-format.ts

@@ -44,7 +44,9 @@ export function appendReleaseBlock(
 /** Extracts all version strings from release markers found in `content`. */
 export function extractReleaseIds(content: string): string[] {
   const ids: string[] = [];
+  MARKER_REGEX.lastIndex = 0;
   let match: RegExpExecArray | null;
+  // eslint-disable-next-line no-restricted-syntax -- RegExp.exec returns null
   while ((match = MARKER_REGEX.exec(content)) !== null) {
     ids.push(match[1]);
   }

package/src/config/update-bulletin-state.ts

@@ -4,7 +4,7 @@ const ACTIVE_RELEASES_KEY = 'updates:active_releases';
 const COMPLETED_RELEASES_KEY = 'updates:completed_releases';
 
 function parseReleaseArray(raw: string | null): string[] {
-  if (raw === null) return [];
+  if (!raw) return [];
   try {
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed)) return [];

package/src/config/update-bulletin-template-path.ts

@@ -0,0 +1,6 @@
+import { join } from 'node:path';
+
+/** Returns the path to the bundled UPDATES.md template. Extracted for testability. */
+export function getTemplatePath(): string {
+  return join(import.meta.dirname ?? __dirname, 'templates', 'UPDATES.md');
+}

package/src/config/update-bulletin.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 
+import { getWorkspacePromptPath } from '../util/platform.js';
+import { APP_VERSION } from '../version.js';
 import { stripCommentLines } from './system-prompt.js';
 import { appendReleaseBlock, hasReleaseBlock } from './update-bulletin-format.js';
 import {
@@ -10,8 +11,7 @@ import {
   markReleasesCompleted,
   setActiveReleases,
 } from './update-bulletin-state.js';
-import { APP_VERSION } from '../version.js';
-import { getWorkspacePromptPath } from '../util/platform.js';
+import { getTemplatePath } from './update-bulletin-template-path.js';
 
 /**
  * Writes content to a file via a temp-file + rename to prevent partial/truncated
@@ -21,7 +21,22 @@ function atomicWriteFileSync(filePath: string, content: string): void {
   const tmpPath = `${filePath}.tmp.${process.pid}`;
   try {
     writeFileSync(tmpPath, content, 'utf-8');
-    renameSync(tmpPath, filePath);
+    // Resolve symlinks so we rename to the real target, preserving the link.
+    // If the symlink is dangling (target doesn't exist), fall back to writing
+    // through the symlink path directly — realpathSync throws ENOENT for dangling links.
+    let targetPath = filePath;
+    try {
+      if (lstatSync(filePath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        targetPath = realpathSync(filePath);
+      }
+    } catch (err: unknown) {
+      // Dangling symlink — fall back to writing through the symlink path.
+      // Only swallow ENOENT (dangling target); re-throw ELOOP, EACCES, I/O faults, etc.
+      if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw err;
+      }
+    }
+    renameSync(tmpPath, targetPath);
   } catch (err) {
     try {
       unlinkSync(tmpPath);
@@ -57,7 +72,7 @@ export function syncUpdateBulletinOnStartup(): void {
   }
 
   // --- Template materialization ---
-  const templatePath = join(import.meta.dirname ?? __dirname, 'templates', 'UPDATES.md');
+  const templatePath = getTemplatePath();
   if (!existsSync(templatePath)) return;
 
   const rawTemplate = readFileSync(templatePath, 'utf-8');

package/src/daemon/config-watcher.ts

@@ -90,8 +90,9 @@ export class ConfigWatcher {
   /**
    * Start all file watchers. `onSessionEvict` is called when watched
    * files change and sessions need to be evicted for reload.
+   * `onIdentityChanged` is called when IDENTITY.md changes on disk.
    */
-  start(onSessionEvict: () => void): void {
+  start(onSessionEvict: () => void, onIdentityChanged?: () => void): void {
     const workspaceDir = getWorkspaceDir();
     const protectedDir = join(getRootDir(), 'protected');
 
@@ -106,7 +107,7 @@ export class ConfigWatcher {
         }
       },
       'SOUL.md': () => onSessionEvict(),
-      'IDENTITY.md': () => onSessionEvict(),
+      'IDENTITY.md': () => { onSessionEvict(); onIdentityChanged?.(); },
       'USER.md': () => onSessionEvict(),
       'LOOKS.md': () => onSessionEvict(),
       'UPDATES.md': () => onSessionEvict(),