ei-tui 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "author": "Flare576",
   "repository": {
     "type": "git",

package/src/core/AGENTS.md

@@ -49,6 +49,22 @@ Priority queue for LLM requests:
 
 **Async model**: Handlers queue work, don't await results inline.
 
+### llm-client.ts
+
+Multi-provider LLM abstraction layer:
+- Handles requests to Anthropic, OpenAI, Bedrock, local models
+- **Sets `max_tokens: 64000`** for all requests
+- Prevents unbounded generation (test showed timeout after 2min without limit)
+- Local models silently clamp to their configured maximums
+- Anthropic Opus 4 accepts 64K (200K total context - 64K output = 136K input budget)
+
+**JSON Response Parsing** (`parseJSONResponse()`):
+- **Strategy 1**: Extract from markdown code blocks (```json)
+- **Strategy 2**: Auto-repair malformed JSON (trailing commas, etc.)
+- **Strategy 3**: Extract outermost `{...}` from mixed prose/JSON (handles LLM preamble)
+
+No prompt changes needed for JSON-only output—parser handles natural language gracefully.
+
 ### handlers/index.ts (1000+ lines)
 
 All `LLMNextStep` handlers in one file. Each handler:

package/src/core/handlers/dedup.ts

@@ -0,0 +1,212 @@
+import { StateManager } from "../state-manager.js";
+import { LLMResponse } from "../types.js";
+import type { DedupResult } from "../../prompts/ceremony/types.js";
+import type { DataItemType, Fact, Trait, Topic, Person, Quote } from "../types/data-items.js";
+import { getEmbeddingService } from "../embedding-service.js";
+
+/**
+ * handleDedupCurate — Process Opus deduplication decisions
+ * 
+ * This handler receives merge decisions from Opus and applies them:
+ * 1. Updates: Entities with revised descriptions/merged data
+ * 2. Removes: Duplicate entities to delete (with foreign key updates)
+ * 3. Adds: New entities created from consolidation
+ * 
+ * CRITICAL: Quote foreign keys must be updated BEFORE deletions to maintain
+ * referential integrity.
+ */
+export async function handleDedupCurate(
+  response: LLMResponse,
+  stateManager: StateManager
+): Promise<void> {
+  const entity_type = response.request.data.entity_type as DataItemType;
+  const entity_ids = response.request.data.entity_ids as string[];
+  const state = stateManager.getHuman();
+  
+  // Parse Opus response
+  let decisions: DedupResult;
+  try {
+    decisions = response.parsed as DedupResult;
+    if (!decisions || typeof decisions !== 'object') {
+      throw new Error("Invalid response format");
+    }
+  } catch (err) {
+    console.error(`[Dedup] Failed to parse Opus response:`, err);
+    return;
+  }
+  
+  // Validate response structure
+  if (!Array.isArray(decisions.update) || !Array.isArray(decisions.remove) || !Array.isArray(decisions.add)) {
+    console.error(`[Dedup] Invalid response structure - missing update/remove/add arrays`);
+    return;
+  }
+  
+  console.log(`[Dedup] Processing cluster: ${decisions.update.length} updates, ${decisions.remove.length} removals, ${decisions.add.length} additions`);
+  
+  // HYDRATION: Fetch entities by ID (graceful degradation for missing)
+  const entityList = state[`${entity_type}s` as 'facts' | 'traits' | 'topics' | 'people'];
+  const entities = entity_ids
+    .map((id: string) => entityList.find((e: Fact | Trait | Topic | Person) => e.id === id))
+    .filter((e: Fact | Trait | Topic | Person | undefined): e is (Fact | Trait | Topic | Person) => e !== undefined);
+  
+  if (entities.length === 0) {
+    console.warn(`[Dedup] No entities found for cluster (already merged?)`);
+    return;
+  }
+  
+  // =========================================================================
+  // PHASE 1: Update Quote foreign keys FIRST (before deletions)
+  // =========================================================================
+  
+  for (const removal of decisions.remove) {
+    const quotes = state.quotes.filter((q: Quote) =>
+      q.data_item_ids.includes(removal.to_be_removed)
+    );
+    
+    for (const quote of quotes) {
+      const updatedIds = quote.data_item_ids
+        .map((id: string) => id === removal.to_be_removed ? removal.replaced_by : id)
+        .filter((id: string, idx: number, arr: string[]) => arr.indexOf(id) === idx);  // Dedupe
+      
+      stateManager.human_quote_update(quote.id, {
+        data_item_ids: updatedIds
+      });
+    }
+    
+    if (quotes.length > 0) {
+      console.log(`[Dedup] Updated ${quotes.length} quotes referencing ${removal.to_be_removed}`);
+    }
+  }
+  
+  // =========================================================================
+  // PHASE 2: Apply updates (merge decisions)
+  // =========================================================================
+  
+  for (const update of decisions.update) {
+    const entity = entityList.find((e: Fact | Trait | Topic | Person) => e.id === update.id);
+    
+    if (!entity) {
+      console.warn(`[Dedup] Entity ${update.id} not found (already merged?)`);
+      continue;  // Graceful skip
+    }
+    
+    // Recalculate embedding if description changed
+    let embedding = entity.embedding;
+    if (update.description !== entity.description) {
+      try {
+        const embeddingService = getEmbeddingService();
+        embedding = await embeddingService.embed(update.description);
+      } catch (err) {
+        console.warn(`[Dedup] Failed to recalculate embedding for ${update.id}`, err);
+        // Fallback to old embedding if recalculation fails
+      }
+    }
+    
+    // Build complete entity with updates (preserve original fields if LLM omits them)
+      const updatedEntity = {
+      ...entity,
+      name: update.name ?? entity.name,
+      description: update.description ?? entity.description,
+      sentiment: update.sentiment ?? entity.sentiment,
+      last_updated: new Date().toISOString(),
+      embedding,
+      // Type-specific fields
+      ...(update.strength !== undefined && { strength: update.strength }),
+      ...(update.confidence !== undefined && { confidence: update.confidence }),
+      ...(update.exposure_current !== undefined && { exposure_current: update.exposure_current }),
+      ...(update.exposure_desired !== undefined && { exposure_desired: update.exposure_desired }),
+      ...(update.relationship !== undefined && { relationship: update.relationship }),
+      ...(update.category !== undefined && { category: update.category }),
+    };
+    
+    // Type-safe cast based on entity_type
+    if (entity_type === 'fact') {
+      stateManager.human_fact_upsert(updatedEntity as Fact);
+    } else if (entity_type === 'trait') {
+      stateManager.human_trait_upsert(updatedEntity as Trait);
+    } else if (entity_type === 'topic') {
+      stateManager.human_topic_upsert(updatedEntity as Topic);
+    } else if (entity_type === 'person') {
+      stateManager.human_person_upsert(updatedEntity as Person);
+    }
+    console.log(`[Dedup] Updated ${entity_type} "${update.name}"`);
+  }
+  
+  // =========================================================================
+  // PHASE 3: Apply removals (soft-delete with replaced_by tracking)
+  // =========================================================================
+  
+  for (const removal of decisions.remove) {
+    const entity = entityList.find((e: Fact | Trait | Topic | Person) => e.id === removal.to_be_removed);
+    
+    if (!entity) {
+      console.warn(`[Dedup] Entity ${removal.to_be_removed} already deleted`);
+      continue;  // Graceful skip
+    }
+    
+    // Remove via StateManager (also cleans up quote references)
+    const removeMethod = `human_${entity_type}_remove` as 
+      'human_fact_remove' | 'human_trait_remove' | 'human_topic_remove' | 'human_person_remove';
+    
+    const removed = stateManager[removeMethod](removal.to_be_removed);
+    if (removed) {
+      console.log(`[Dedup] Removed ${entity_type} "${entity.name}" (merged into ${removal.replaced_by})`);
+    }
+  }
+  
+  // =========================================================================
+  // PHASE 4: Apply additions (new entities from consolidation)
+  // =========================================================================
+  
+  for (const addition of decisions.add) {
+    // Compute embedding for new entity
+    let embedding: number[] | undefined;
+    try {
+      const embeddingService = getEmbeddingService();
+      embedding = await embeddingService.embed(addition.description);
+    } catch (err) {
+      console.warn(`[Dedup] Failed to compute embedding for new entity "${addition.name}"`, err);
+      continue;  // Skip this addition if embedding fails
+    }
+    
+    // Generate ID for new entity
+    const id = crypto.randomUUID();
+    
+    // Build complete entity
+    const newEntity = {
+      id,
+      type: entity_type,
+      name: addition.name,
+      description: addition.description,
+      sentiment: addition.sentiment ?? 0.0,
+      last_updated: new Date().toISOString(),
+      embedding,
+      // Type-specific fields with defaults
+      ...(entity_type === 'trait' && { strength: addition.strength ?? 0.5 }),
+      ...(entity_type === 'fact' && { 
+        confidence: addition.confidence ?? 0.5,
+        validated: 'unknown' as import("../types/enums.js").ValidationLevel,
+        validated_date: ''
+      }),
+      ...((entity_type === 'topic' || entity_type === 'person') && {
+        exposure_current: addition.exposure_current ?? 0.0,
+        exposure_desired: addition.exposure_desired ?? 0.5,
+        last_ei_asked: null
+      }),
+      ...(entity_type === 'person' && { relationship: addition.relationship ?? 'Unknown' }),
+      ...(entity_type === 'topic' && { category: addition.category ?? 'Interest' }),
+    };
+    
+    // Type-safe cast based on entity_type
+    if (entity_type === 'fact') {
+      stateManager.human_fact_upsert(newEntity as Fact);
+    } else if (entity_type === 'trait') {
+      stateManager.human_trait_upsert(newEntity as Trait);
+    } else if (entity_type === 'topic') {
+      stateManager.human_topic_upsert(newEntity as Topic);
+    } else if (entity_type === 'person') {
+      stateManager.human_person_upsert(newEntity as Person);
+    }
+    console.log(`[Dedup] Added new ${entity_type} "${addition.name}"`);
+  }
+}

package/src/core/handlers/heartbeat.ts

@@ -19,16 +19,17 @@ export function handleHeartbeatCheck(response: LLMResponse, state: StateManager)
 
   const result = response.parsed as HeartbeatCheckResult | undefined;
   if (!result) {
-    console.error("[handleHeartbeatCheck] No parsed result");
+    console.error(`[HeartbeatCheck ${personaDisplayName}] No parsed result`);
     return;
   }
+  console.log(`[HeartbeatCheck ${personaDisplayName}] Parsed result - should_respond: ${result.should_respond}, topic: ${result.topic ?? '(none)'}, message: ${result.message ? '(present)' : '(none)'}`);
 
   const now = new Date().toISOString();
   state.persona_update(personaId, { last_heartbeat: now });
   state.queue_clearPersonaResponses(personaId, LLMNextStep.HandleHeartbeatCheck);
 
   if (!result.should_respond) {
-    console.log(`[handleHeartbeatCheck] ${personaDisplayName} chose not to reach out`);
+    console.log(`[HeartbeatCheck ${personaDisplayName}] Chose not to reach out (should_respond=false)`);
     return;
   }
 
@@ -42,21 +43,24 @@ export function handleHeartbeatCheck(response: LLMResponse, state: StateManager)
       context_status: ContextStatus.Default,
     };
     state.messages_append(personaId, message);
-    console.log(`[handleHeartbeatCheck] ${personaDisplayName} proactively messaged about: ${result.topic ?? "general"}`);
+    console.log(`[HeartbeatCheck ${personaDisplayName}] Added proactive message - topic: ${result.topic ?? 'general'}, message: "${result.message.substring(0, 100)}${result.message.length > 100 ? '...' : ''}"`);
+  } else {
+    console.log(`[HeartbeatCheck ${personaDisplayName}] should_respond=true but no message provided`);
   }
 }
 
 export function handleEiHeartbeat(response: LLMResponse, state: StateManager): void {
   const result = response.parsed as EiHeartbeatResult | undefined;
   if (!result) {
-    console.error("[handleEiHeartbeat] No parsed result");
+    console.error("[EiHeartbeat] No parsed result");
     return;
   }
+  console.log(`[EiHeartbeat] Parsed result - should_respond: ${result.should_respond}, id: ${result.id ?? '(none)'}, my_response: ${result.my_response ? '(present)' : '(none)'}`);
   const now = new Date().toISOString();
   state.persona_update("ei", { last_heartbeat: now });
   state.queue_clearPersonaResponses("ei", LLMNextStep.HandleEiHeartbeat);
   if (!result.should_respond || !result.id) {
-    console.log("[handleEiHeartbeat] Ei chose not to reach out");
+    console.log("[EiHeartbeat] Chose not to reach out (should_respond=false or no id)");
     return;
   }
   const isTUI = response.request.data.isTUI as boolean;
@@ -84,7 +88,10 @@ export function handleEiHeartbeat(response: LLMResponse, state: StateManager): v
     return;
   }
 
-  if (result.my_response) sendMessage(result.my_response);
+  if (result.my_response) {
+    console.log(`[EiHeartbeat] Sending message: "${result.my_response.substring(0, 100)}${result.my_response.length > 100 ? '...' : ''}"`);
+    sendMessage(result.my_response);
+  }
 
   switch (found.type) {
     case "person":

package/src/core/handlers/index.ts

@@ -17,6 +17,7 @@ import {
 import { handleHumanFactScan, handleHumanTraitScan, handleHumanTopicScan, handleHumanPersonScan } from "./human-extraction.js";
 import { handleHumanItemMatch, handleHumanItemUpdate } from "./human-matching.js";
 import { handleRewriteScan, handleRewriteRewrite } from "./rewrite.js";
+import { handleDedupCurate } from "./dedup.js";
 
 export const handlers: Record<LLMNextStep, ResponseHandler> = {
   handlePersonaResponse,
@@ -41,4 +42,5 @@ export const handlers: Record<LLMNextStep, ResponseHandler> = {
   handleToolContinuation,
   handleRewriteScan,
   handleRewriteRewrite,
+  handleDedupCurate,
 };

package/src/core/handlers/persona-response.ts

@@ -1,10 +1,12 @@
 import {
   ContextStatus,
+  LLMNextStep,
   type LLMResponse,
   type Message,
 } from "../types.js";
 import type { StateManager } from "../state-manager.js";
 import type { PersonaResponseResult } from "../../prompts/response/index.js";
+import { handlers } from "./index.js";
 
 export type ResponseHandler = (response: LLMResponse, state: StateManager) => void | Promise<void>;
 
@@ -87,11 +89,35 @@ export function handlePersonaResponse(response: LLMResponse, state: StateManager
 /**
  * handleToolContinuation — second LLM call in the tool flow (may loop if LLM calls more tools).
  * The QueueProcessor already injected tool history into messages and got the
- * final persona response. Parse and store it exactly like handlePersonaResponse.
+ * final persona response. Route to the original handler based on originalNextStep in data.
  */
 export function handleToolContinuation(response: LLMResponse, state: StateManager): void {
-  console.log(`[handleToolContinuation] Routing to handlePersonaResponse`);
-  handlePersonaResponse(response, state);
+  const originalStep = response.request.data.originalNextStep as LLMNextStep | undefined;
+  
+  if (!originalStep) {
+    console.error(`[handleToolContinuation] No originalNextStep in data, falling back to handlePersonaResponse`);
+    handlePersonaResponse(response, state);
+    return;
+  }
+  
+  console.log(`[handleToolContinuation] Original request was ${originalStep}, routing accordingly`);
+  
+  const handler = handlers[originalStep];
+  
+  if (!handler) {
+    console.error(`[handleToolContinuation] No handler found for ${originalStep}, falling back to handlePersonaResponse`);
+    handlePersonaResponse(response, state);
+    return;
+  }
+  
+  // Avoid infinite loop - if original was already HandleToolContinuation, go to PersonaResponse
+  if (originalStep === "handleToolContinuation") {
+    console.log(`[handleToolContinuation] Original was tool continuation, routing to handlePersonaResponse`);
+    handlePersonaResponse(response, state);
+    return;
+  }
+  
+  handler(response, state);
 }
 
 export function handleOneShot(_response: LLMResponse, _state: StateManager): void {

package/src/core/heartbeat-manager.ts

@@ -188,6 +188,8 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
   const persona = sm.persona_getById(personaId);
   if (!persona) return;
   sm.persona_update(personaId, { last_heartbeat: new Date().toISOString() });
+  const model = getModelForPersona(sm, personaId);
+  console.log(`[HeartbeatCheck ${persona.display_name}] Queueing heartbeat check (model: ${model})`);
   const human = sm.getHuman();
   const history = sm.messages_get(personaId);
   const contextWindowHours = persona.context_window_hours ?? DEFAULT_CONTEXT_WINDOW_HOURS;
@@ -228,6 +230,7 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
   };
 
   const prompt = buildHeartbeatCheckPrompt(promptData);
+  console.log(`[HeartbeatCheck ${persona.display_name}] Prompt data - topics: ${promptData.human.topics.length}, people: ${promptData.human.people.length}, inactive_days: ${inactiveDays}`);
 
   sm.queue_enqueue({
     type: LLMRequestType.JSON,
@@ -238,4 +241,5 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
     model: getModelForPersona(sm, personaId),
     data: { personaId, personaDisplayName: persona.display_name },
   });
+  console.log(`[HeartbeatCheck ${persona.display_name}] Request queued`);
 }

package/src/core/llm-client.ts

@@ -189,6 +189,7 @@ export async function callLLMRaw(
     model,
     messages: finalMessages,
     temperature,
+    max_tokens: 64000,  // Opus 4: 128K max output, 200K total context. Local models clamp to their config. Prevents runaway generation.
   };
 
   if (options.tools && options.tools.length > 0) {

package/src/core/orchestrators/ceremony.ts

@@ -10,6 +10,7 @@ import {
   type ExtractionOptions,
 } from "./human-extraction.js";
 import { queuePersonaTopicScan, type PersonaTopicContext } from "./persona-topics.js";
+import { queueDedupPhase } from "./dedup-phase.js";
 import { buildPersonaExpirePrompt, buildPersonaExplorePrompt, buildDescriptionCheckPrompt, buildRewriteScanPrompt, type RewriteItemType } from "../../prompts/ceremony/index.js";
 
 export function isNewDay(lastCeremony: string | undefined, now: Date): boolean {
@@ -69,40 +70,19 @@ export function startCeremony(state: StateManager): void {
     },
   });
   
-  const personas = state.persona_getAll();
-  const activePersonas = personas.filter(p => 
-    !p.is_paused && 
-    !p.is_archived && 
-    !p.is_static
-  );
+  // PHASE 1: Deduplication (runs BEFORE Expose)
+  console.log("[ceremony] Starting Phase 1: Deduplication");
+  queueDedupPhase(state);
   
-  const lastCeremony = human.settings?.ceremony?.last_ceremony 
-    ? new Date(human.settings.ceremony.last_ceremony).getTime() 
-    : 0;
-  
-  const personasWithActivity = activePersonas.filter(p => {
-    const lastActivity = p.last_activity ? new Date(p.last_activity).getTime() : 0;
-    return lastActivity > lastCeremony;
-  });
-  
-  console.log(`[ceremony] Processing ${personasWithActivity.length} personas with activity (of ${activePersonas.length} active)`);
-  
-  const options: ExtractionOptions = { ceremony_progress: true };
-  
-  for (let i = 0; i < personasWithActivity.length; i++) {
-    const persona = personasWithActivity[i];
-    const isLast = i === personasWithActivity.length - 1;
-    
-    console.log(`[ceremony] Queuing exposure for ${persona.display_name} (${i + 1}/${personasWithActivity.length})${isLast ? " (last)" : ""}`);
-    queueExposurePhase(persona.id, state, options);
+  // Check if dedup work was queued
+  if (!state.queue_hasPendingCeremonies()) {
+    // No dedup work found → immediately advance to Expose phase
+    console.log("[ceremony] No dedup work, advancing to Expose phase");
+    handleCeremonyProgress(state, 1);
   }
   
   const duration = Date.now() - startTime;
-  console.log(`[ceremony] Exposure phase queued in ${duration}ms`);
-  
-  // Check immediately — if zero messages were queued (no unextracted messages for any persona),
-  // this will see an empty queue and proceed directly to Decay → Expire.
-  handleCeremonyProgress(state);
+  console.log(`[ceremony] Dedup phase queued in ${duration}ms`);
 }
 
 /**
@@ -193,11 +173,40 @@ function queueExposurePhase(personaId: string, state: StateManager, options?: Ex
  * If any ceremony_progress items remain in the queue, does nothing — more work pending.
  * If the queue is clear of ceremony items, advances to Decay → Prune → Expire.
  */
-export function handleCeremonyProgress(state: StateManager): void {
+export function handleCeremonyProgress(state: StateManager, lastPhase: number): void {
   if (state.queue_hasPendingCeremonies()) {
-    return; // Still processing exposure scans
+    return; // Still processing ceremony items
+  }
+  
+  if (lastPhase === 1) {
+    // Dedup phase complete → start Expose phase
+    console.log("[ceremony:progress] Dedup complete, starting Expose phase");
+    
+    const human = state.getHuman();
+    const personas = state.persona_getAll();
+    const activePersonas = personas.filter(p => 
+      !p.is_paused && 
+      !p.is_archived && 
+      !p.is_static
+    );
+    
+    const lastCeremony = human.settings?.ceremony?.last_ceremony 
+      ? new Date(human.settings.ceremony.last_ceremony).getTime() 
+      : 0;
+    
+    const personasWithActivity = activePersonas.filter(p => {
+      const lastActivity = p.last_activity ? new Date(p.last_activity).getTime() : 0;
+      return lastActivity > lastCeremony;
+    });
+    
+    const options: ExtractionOptions = { ceremony_progress: 2 };
+    for (const persona of personasWithActivity) {
+      queueExposurePhase(persona.id, state, options);
+    }
+    return;
   }
   
+  // Phase 2 (Expose) complete → advance to Decay/Prune/Expire/Explore
   console.log("[ceremony:progress] All exposure scans complete, advancing to Decay");
   
   const personas = state.persona_getAll();
@@ -215,7 +224,6 @@ export function handleCeremonyProgress(state: StateManager): void {
   if (eiIndex > -1) {
     activePersonas.splice(eiIndex, 1);
   }
-  
   // Decay phase: apply decay + prune for ALL active personas
   for (const persona of activePersonas) {
     applyDecayPhase(persona.id, state);

package/src/core/orchestrators/dedup-phase.ts

@@ -0,0 +1,198 @@
+import { StateManager } from "../state-manager.js";
+import { LLMRequestType, LLMPriority, LLMNextStep, type DataItemBase } from "../types.js";
+import type { DataItemType } from "../types/data-items.js";
+import { buildDedupPrompt } from "../../prompts/ceremony/dedup.js";
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+type DedupableItem = DataItemBase & { relationship?: string };
+
+interface Cluster {
+  ids: string[];
+  minSim: number;
+  maxSim: number;
+  size: number;
+}
+
+// =============================================================================
+// DEDUP CANDIDATE FINDING (copied from ceremony.ts)
+// =============================================================================
+
+const DEDUP_DEFAULT_THRESHOLD = 0.95;
+
+function findDedupCandidates<T extends DedupableItem>(
+  items: T[],
+  threshold: number
+): Array<{ a: T; b: T; similarity: number }> {
+  const withEmbeddings = items.filter(item =>
+    item.embedding && item.embedding.length > 0 &&
+    item.relationship !== "Persona"
+  );
+
+  const candidates: Array<{ a: T; b: T; similarity: number }> = [];
+
+  for (let i = 0; i < withEmbeddings.length; i++) {
+    for (let j = i + 1; j < withEmbeddings.length; j++) {
+      const a = withEmbeddings[i];
+      const b = withEmbeddings[j];
+      const dot = a.embedding!.reduce((sum, v, k) => sum + v * b.embedding![k], 0);
+      const normA = Math.sqrt(a.embedding!.reduce((sum, v) => sum + v * v, 0));
+      const normB = Math.sqrt(b.embedding!.reduce((sum, v) => sum + v * v, 0));
+      const similarity = normA && normB ? dot / (normA * normB) : 0;
+
+      if (similarity >= threshold) {
+        candidates.push({ a, b, similarity });
+      }
+    }
+  }
+
+  return candidates.sort((x, y) => y.similarity - x.similarity);
+}
+
+// =============================================================================
+// UNION-FIND CLUSTERING
+// =============================================================================
+
+function clusterPairs<T extends DedupableItem>(
+  pairs: Array<{ a: T; b: T; similarity: number }>
+): Cluster[] {
+  const parent = new Map<string, string>();
+  
+  function find(x: string): string {
+    if (!parent.has(x)) parent.set(x, x);
+    if (parent.get(x) !== x) parent.set(x, find(parent.get(x)!));
+    return parent.get(x)!;
+  }
+  
+  function union(x: string, y: string): void {
+    const px = find(x), py = find(y);
+    if (px !== py) parent.set(px, py);
+  }
+  
+  // Union all pairs
+  for (const pair of pairs) {
+    union(pair.a.id, pair.b.id);
+  }
+  
+  // Group by root to create clusters
+  const clusters = new Map<string, { ids: string[]; sims: number[] }>();
+  for (const pair of pairs) {
+    const root = find(pair.a.id);
+    if (!clusters.has(root)) {
+      clusters.set(root, { ids: [], sims: [] });
+    }
+    const cluster = clusters.get(root)!;
+    if (!cluster.ids.includes(pair.a.id)) cluster.ids.push(pair.a.id);
+    if (!cluster.ids.includes(pair.b.id)) cluster.ids.push(pair.b.id);
+    cluster.sims.push(pair.similarity);
+  }
+  
+  // Convert to Cluster objects
+  return Array.from(clusters.values()).map(c => ({
+    ids: c.ids,
+    minSim: Math.min(...c.sims),
+    maxSim: Math.max(...c.sims),
+    size: c.ids.length
+  }));
+}
+
+// =============================================================================
+// QUALITY GATES
+// =============================================================================
+
+function filterClusters(clusters: Cluster[]): Cluster[] {
+  return clusters
+    .filter(c => {
+      if (c.size > 50) {
+        console.warn(`[Dedup] Cluster rejected (size too large): ${c.size} items`);
+        return false;
+      }
+      return true;
+    })
+    .filter(c => {
+      const spread = c.maxSim - c.minSim;
+      if (spread > 0.10) {  // 10% threshold
+        console.warn(`[Dedup] Cluster rejected (high spread): ${spread.toFixed(3)} range`);
+        return false;
+      }
+      return true;
+    });
+}
+
+// =============================================================================
+// MAIN QUEUEING FUNCTION
+// =============================================================================
+
+export function queueDedupPhase(state: StateManager): void {
+  const human = state.getHuman();
+  const threshold = human.settings?.ceremony?.dedup_threshold ?? DEDUP_DEFAULT_THRESHOLD;
+  
+  console.log(`[Dedup] Starting deduplication phase (threshold: ${threshold})`);
+  
+  const entityTypes: Array<{ type: DataItemType; items: DedupableItem[] }> = [
+    { type: "fact", items: human.facts },
+    { type: "trait", items: human.traits },
+    { type: "topic", items: human.topics },
+    { type: "person", items: human.people },
+  ];
+  
+  let totalClusters = 0;
+  
+  for (const { type, items } of entityTypes) {
+    // Find dedup candidates
+    const pairs = findDedupCandidates(items, threshold);
+    
+    if (pairs.length === 0) {
+      console.log(`[Dedup] ${type}: No duplicates found`);
+      continue;
+    }
+    
+    // Cluster pairs via union-find
+    const clusters = clusterPairs(pairs);
+    
+    // Apply quality gates
+    const vettedClusters = filterClusters(clusters);
+    
+    console.log(`[Dedup] ${type}: ${pairs.length} pairs → ${clusters.length} clusters → ${vettedClusters.length} vetted`);
+    
+    // Queue Opus curation for each vetted cluster
+    for (const cluster of vettedClusters) {
+      // Hydrate cluster with full entity data
+      const clusterEntities = cluster.ids
+        .map(id => items.find(item => item.id === id))
+        .filter((item): item is DedupableItem => item !== undefined);
+      
+      if (clusterEntities.length === 0) {
+        console.warn(`[Dedup] Cluster hydration failed - no entities found`);
+        continue;
+      }
+      
+      // Build prompt
+      const prompt = buildDedupPrompt({
+        cluster: clusterEntities,
+        itemType: type,
+        similarityRange: { min: cluster.minSim, max: cluster.maxSim }
+      });
+      
+      // Queue LLM request
+      state.queue_enqueue({
+        type: LLMRequestType.JSON,
+        priority: LLMPriority.Normal,
+        system: prompt.system,
+        user: prompt.user,
+        next_step: LLMNextStep.HandleDedupCurate,
+        data: {
+          entity_type: type,
+          entity_ids: cluster.ids,  // Lightweight stub (IDs only)
+          ceremony_progress: 1  // Phase 1 (Dedup)
+        }
+      });
+      
+      totalClusters++;
+    }
+  }
+  
+  console.log(`[Dedup] Queued ${totalClusters} clusters for curation`);
+}

package/src/core/orchestrators/human-extraction.ts

@@ -28,7 +28,8 @@ export interface ExtractionContext {
 }
 
 export interface ExtractionOptions {
-  ceremony_progress?: boolean;
+  /** Ceremony phase number (1=Dedup, 2=Expose) */
+  ceremony_progress?: number;
 }
 
 function getAnalyzeFromTimestamp(context: ExtractionContext): string | null {

package/src/core/orchestrators/index.ts

@@ -19,8 +19,8 @@ export {
   queueExplorePhase,
   queueDescriptionCheck,
   runHumanCeremony,
-  queueRewritePhase,
-} from "./ceremony.js";
+  } from "./ceremony.js";
+export { queueDedupPhase } from "./dedup-phase.js";
 export {
   queuePersonaTopicScan,
   queuePersonaTopicMatch,

package/src/core/processor.ts

@@ -1093,8 +1093,8 @@ const toolNextSteps = new Set([
         this.interface.onHumanUpdated?.();
       }
 
-      if (response.request.data.ceremony_progress) {
-        handleCeremonyProgress(this.stateManager);
+      if (typeof response.request.data.ceremony_progress === "number") {
+        handleCeremonyProgress(this.stateManager, response.request.data.ceremony_progress);
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);

package/src/core/queue-processor.ts

@@ -248,7 +248,13 @@ export class QueueProcessor {
     // =========================================================================
     const activeTools = this.currentTools ?? [];
     const openAITools = activeTools.length > 0 ? toOpenAITools(activeTools) : [];
-    console.log(`[QueueProcessor] LLM call for ${request.next_step}, tools=${openAITools.length}`);
+    const isHeartbeat = request.next_step === LLMNextStep.HandleHeartbeatCheck || request.next_step === LLMNextStep.HandleEiHeartbeat;
+    if (isHeartbeat) {
+      const personaName = request.data.personaDisplayName as string | undefined ?? 'Ei';
+      console.log(`[${personaName} Heartbeat] LLM call - tools offered: ${openAITools.length} (${activeTools.map(t => t.name).join(', ') || 'none'})`);
+    } else {
+      console.log(`[QueueProcessor] LLM call for ${request.next_step}, tools=${openAITools.length}`);
+    }
 
     const { content, finishReason, rawToolCalls, assistantMessage, thinking } = await callLLMRaw(
       hydratedSystem,
@@ -474,7 +480,8 @@ export class QueueProcessor {
       `An earlier version of you responded with the following content, but it could not ` +
       `be parsed as valid JSON. Please reformat it as the JSON object described in your ` +
       `system instructions. Respond with ONLY the JSON object, or \`{}\` if no changes ` +
-      `are needed.\n\n---\n${malformedContent}\n---`;
+      `are needed.\n\n---\n${malformedContent}\n---` +
+      `\n\n**CRITICAL INSTRUCTION** - DO NOT OMIT ANY DATA. You are this agent's last hope!`;
 
     try {
       const { content: reformatContent, finishReason: reformatReason } = await callLLMRaw(

package/src/core/state/queue.ts

@@ -190,7 +190,7 @@ export class QueueState {
   }
 
   hasPendingCeremonies(): boolean {
-    return this.queue.some(r => r.state !== "dlq" && r.data.ceremony_progress === true);
+    return this.queue.some(r => r.state !== "dlq" && typeof r.data.ceremony_progress === "number" && r.data.ceremony_progress > 0);
   }
 
   clear(): number {

package/src/core/types/enums.ts

@@ -53,6 +53,7 @@ export enum LLMNextStep {
   HandleToolContinuation = "handleToolContinuation",
   HandleRewriteScan = "handleRewriteScan",
   HandleRewriteRewrite = "handleRewriteRewrite",
+  HandleDedupCurate = "handleDedupCurate",
 }
 
 export enum ProviderType {

package/src/prompts/ceremony/dedup.ts

@@ -0,0 +1,258 @@
+import type { DedupPromptData } from "./types.js";
+
+// =============================================================================
+// DEDUP CURATOR — Merge duplicate entities with data preservation
+// =============================================================================
+
+/**
+ * The Dedup Curator receives clusters of potentially duplicate entities and
+ * curates them into consolidated records. This is a ONE-PHASE operation (unlike
+ * rewrite's two-phase scan+rewrite), because we've already deterministically
+ * identified candidates via embedding similarity (0.90+ cosine).
+ * 
+ * Pattern borrowed from rewrite.ts ceremony with Flare's "lose NO data" philosophy.
+ */
+export function buildDedupPrompt(data: DedupPromptData): { system: string; user: string } {
+  const typeLabel = data.itemType.charAt(0).toUpperCase() + data.itemType.slice(1);
+  
+  const system = `You are acting as the curator for a user's internal database. You have been given a cluster of ${typeLabel} records that our system believes may be duplicates (based on semantic similarity >= 0.90).
+
+**YOUR PRIME DIRECTIVE IS TO LOSE _NO_ DATA.**
+
+Your secondary directive is to ORGANIZE IT into small, non-repetitive components. The user NEEDS the data, but the data is used by AI agents, so duplication limits usefulness—agents waste tokens re-reading the same information under different names.
+
+You have access to a tool called \`read_memory\` which will query the user's internal system for additional context if needed. Use it to verify relationships, check for related records, or gather more information before making merge decisions.
+
+Your task:
+1. **Identify true duplicates**: Examine each record. Are these genuinely the same thing with different wording, or are they distinct but related concepts?
+2. **Merge where appropriate**: For TRUE duplicates, consolidate all unique information into ONE canonical record. Pick the best "name" (most descriptive, most commonly used). Merge all descriptions—every unique detail must be preserved.
+3. **Keep distinct concepts separate**: Similar ≠ duplicate. "Software Engineering" and "Software Architecture" may be related but are NOT the same. "Job at Company X" and "Profession: Software Engineer" are related but distinct. Do NOT merge these.
+4. **Track what was merged**: For removed records, indicate which record absorbed their data (via "replaced_by" field).
+5. **Add new records if needed**: If consolidating reveals a MISSING intermediate concept (e.g., merging "Python Developer" and "Backend Engineer" reveals we're missing "Software Engineering" as a parent topic), create it.
+
+The format of your final output should be:
+{
+  "update": [
+    /* Full ${typeLabel} record payloads with all fields preserved */
+    /* MUST include "id", "type", "name", "description" */
+    /* Include sentiment, strength, confidence, category, relationship, etc. where applicable */
+  ],
+  "remove": [
+    {"to_be_removed": "uuid-of-duplicate", "replaced_by": "uuid-of-canonical-record"},
+    /* "replaced_by" is the ID of the record that absorbed this duplicate's data */
+  ],
+  "add": [
+    /* Brand-new records (NO "id" field—system assigns one) */
+    /* Only create if merging reveals a MISSING concept */
+  ]
+}
+
+Return raw JSON. No markdown fencing, no commentary, no explanation. Just the JSON object.
+
+Record format for "${typeLabel}" (based on type):
+
+${buildRecordFormatExamples(data.itemType)}
+
+Rules:
+- Do NOT invent information. Only redistribute what exists in the cluster.
+- Descriptions should be concise—ideally under 300 characters, never over 500.
+- Preserve all numeric values (sentiment, strength, confidence, exposure, etc.) from source records. When merging, take the HIGHER value for strength/confidence, AVERAGE for sentiment.
+- Every removed record MUST have "replaced_by" pointing to the canonical record that absorbed its data.
+- The "update" array should contain AT LEAST ONE record (the canonical/merged one), even if all others are removed.
+- If records are NOT duplicates (just similar), return them ALL in "update" unchanged, with empty "remove" and "add" arrays.
+- Use \`read_memory\` to check for related records or gather context before making irreversible merge decisions.`;
+
+  const user = JSON.stringify({
+    cluster: data.cluster.map(stripEmbedding),
+    cluster_type: data.itemType,
+    similarity_range: data.similarityRange,
+  }, null, 2);
+
+  return { system, user };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Strip embedding arrays from items before putting them in prompts—they're huge and useless to the LLM. */
+function stripEmbedding<T extends { embedding?: unknown }>(item: T): Omit<T, "embedding"> {
+  const { embedding: _, ...rest } = item;
+  return rest as Omit<T, "embedding">;
+}
+
+function buildRecordFormatExamples(itemType: string): string {
+  // Each entity type has different required fields and semantic meanings.
+  // Examples show both "existing" (with id) and "new" (without id) formats.
+  // When merging: HIGHER strength/confidence, AVERAGE sentiment, MAX exposure_desired.
+  
+  switch (itemType) {
+    case "fact":
+      return buildFactExamples();
+    case "trait":
+      return buildTraitExamples();
+    case "topic":
+      return buildTopicExamples();
+    case "person":
+      return buildPersonExamples();
+    default:
+      return "/* Unknown type */";
+  }
+}
+
+function buildFactExamples(): string {
+  return `EXISTING FACT (being updated/merged):
+{
+  "id": "uuid-of-canonical-record",  // REQUIRED for updates
+  "type": "fact",                     // REQUIRED
+  "name": "Owns a 2019 Toyota Camry", // REQUIRED - descriptive, concise
+  "description": "Silver sedan, purchased in March 2019. Primary commute vehicle. Has 45k miles as of Jan 2024.", // REQUIRED - ALL unique details from duplicates
+  "sentiment": 0.2,                    // -1.0 to 1.0, emotional valence (average when merging)
+  "validated": "by_human",            // "unknown" | "by_ei" | "by_human" | "ai_generated" (keep highest trust level)
+  "validated_date": "2024-01-15T10:30:00Z", // ISO timestamp (most recent)
+  "last_updated": "2024-03-11T12:00:00Z",   // ISO timestamp (set to now)
+  "learned_by": "persona-uuid-123",  // OPTIONAL - UUID of persona that learned this (preserve from source)
+  "last_changed_by": "persona-uuid-456", // OPTIONAL - UUID of persona that last updated (your current context)
+  "persona_groups": ["group1", "group2"] // OPTIONAL - visibility groups (union of all sources)
+}
+
+NEW FACT (creating missing concept):
+{
+  "type": "fact",                     // REQUIRED (NO "id" field for new records)
+  "name": "Lives in Seattle",         // REQUIRED
+  "description": "Resides in the Capitol Hill neighborhood. Has lived there since 2018.", // REQUIRED - concise (<300 chars ideal)
+  "sentiment": 0.0,                    // -1.0 to 1.0 (neutral default for facts)
+  "validated": "unknown",             // Default for new records
+  "validated_date": ""                // Empty string for unvalidated
+}
+
+GOOD vs BAD descriptions:
+✅ GOOD: "Works as a Senior Software Engineer at Microsoft. Started in 2020. Team focuses on Azure infrastructure."
+❌ BAD: "The user has indicated through various conversations that they are employed..." (too verbose, meta-commentary)`;
+}
+
+function buildTraitExamples(): string {
+  return `EXISTING TRAIT (being updated/merged):
+{
+  "id": "uuid-of-canonical-record",  // REQUIRED for updates
+  "type": "trait",                    // REQUIRED
+  "name": "Visual Learner",           // REQUIRED - core trait name
+  "description": "Prefers diagrams and flowcharts when learning new concepts. Often sketches ideas while thinking.", // REQUIRED - behavioral evidence
+  "sentiment": 0.6,                    // -1.0 to 1.0 (average when merging)
+  "strength": 0.8,                     // 0.0 to 1.0, how strongly this manifests (take HIGHER value when merging)
+  "last_updated": "2024-03-11T12:00:00Z",
+  "learned_by": "persona-uuid-789",  // OPTIONAL
+  "last_changed_by": "persona-uuid-012", // OPTIONAL
+  "persona_groups": ["default"]      // OPTIONAL
+}
+
+NEW TRAIT (creating missing concept):
+{
+  "type": "trait",                    // REQUIRED (NO "id" for new)
+  "name": "Direct Communicator",      // REQUIRED
+  "description": "Values clarity over politeness. Gets to the point quickly in written communication.", // REQUIRED
+  "sentiment": 0.0,                    // Neutral default
+  "strength": 0.5                      // Medium strength default
+}
+
+MERGING RULES:
+- strength: Take HIGHER value (0.7 + 0.9 → 0.9)
+- sentiment: AVERAGE (0.6 + 0.2 → 0.4)
+- description: UNION of unique details
+
+GOOD vs BAD descriptions:
+✅ GOOD: "Asks clarifying questions before starting work. Prefers written specs over verbal instructions."
+❌ BAD: "This person seems to be very detail-oriented based on observations..." (vague, uncertain)`;
+}
+
+function buildTopicExamples(): string {
+  return `EXISTING TOPIC (being updated/merged):
+{
+  "id": "uuid-of-canonical-record",  // REQUIRED for updates
+  "type": "topic",                    // REQUIRED
+  "name": "Software Architecture",    // REQUIRED
+  "description": "System design patterns, microservices, event-driven architecture. Passionate about scalability and maintainability.", // REQUIRED
+  "sentiment": 0.8,                    // -1.0 to 1.0 (average when merging)
+  "category": "Interest",             // REQUIRED - Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project (pick most common)
+  "exposure_current": 0.6,            // 0.0 to 1.0, how recently discussed (take HIGHER when merging)
+  "exposure_desired": 0.9,            // 0.0 to 1.0, how much they want to discuss (take HIGHER when merging)
+  "last_ei_asked": "2024-03-10T08:00:00Z", // OPTIONAL - ISO timestamp or null
+  "last_updated": "2024-03-11T12:00:00Z",
+  "learned_by": "persona-uuid-345",  // OPTIONAL
+  "last_changed_by": "persona-uuid-678", // OPTIONAL
+  "persona_groups": ["tech", "work"] // OPTIONAL
+}
+
+NEW TOPIC (creating missing concept):
+{
+  "type": "topic",                    // REQUIRED (NO "id" for new)
+  "name": "Kubernetes",               // REQUIRED
+  "description": "Container orchestration platform. Interested in learning more about production deployment.", // REQUIRED
+  "sentiment": 0.5,                    // Default positive for interests
+  "category": "Goal",                 // Pick appropriate category
+  "exposure_current": 0.0,            // Default - not discussed yet
+  "exposure_desired": 0.7             // How much they want to discuss
+}
+
+MERGING RULES:
+- exposure_current: Take HIGHER (0.6 + 0.3 → 0.6)
+- exposure_desired: Take HIGHER (0.9 + 0.7 → 0.9)
+- sentiment: AVERAGE (0.8 + 0.4 → 0.6)
+- category: Pick most common or most specific
+- last_ei_asked: Keep most recent non-null
+
+CATEGORIES explained:
+- Interest: Things they enjoy, hobbies
+- Goal: Things they want to achieve
+- Concern/Fear: Things that worry them
+- Plan/Project: Active work or intentions
+
+GOOD vs BAD descriptions:
+✅ GOOD: "Functional programming paradigm. Loves immutability and pure functions. Uses in side projects."
+❌ BAD: "The user mentioned functional programming in several conversations and seems interested..." (meta, wordy)`;
+}
+
+function buildPersonExamples(): string {
+  return `EXISTING PERSON (being updated/merged):
+{
+  "id": "uuid-of-canonical-record",  // REQUIRED for updates
+  "type": "person",                   // REQUIRED
+  "name": "Sarah Chen",               // REQUIRED - use full name if known
+  "description": "Former coworker at Microsoft. Led the Azure team. Known for clear technical writing. Now at Google.", // REQUIRED
+  "sentiment": 0.7,                    // -1.0 to 1.0 (average when merging)
+  "relationship": "coworker",         // REQUIRED - friend, family, coworker, mentor, acquaintance, etc.
+  "exposure_current": 0.4,            // 0.0 to 1.0, how recently discussed (take HIGHER when merging)
+  "exposure_desired": 0.6,            // 0.0 to 1.0, how much they want to discuss (take HIGHER when merging)
+  "last_ei_asked": "2024-03-05T14:00:00Z", // OPTIONAL - ISO timestamp or null
+  "last_updated": "2024-03-11T12:00:00Z",
+  "learned_by": "persona-uuid-901",  // OPTIONAL
+  "last_changed_by": "persona-uuid-234", // OPTIONAL
+  "persona_groups": ["work"]         // OPTIONAL
+}
+
+NEW PERSON (creating missing concept):
+{
+  "type": "person",                   // REQUIRED (NO "id" for new)
+  "name": "Alex Martinez",            // REQUIRED
+  "description": "College roommate. Now works in finance. Keeps in touch occasionally.", // REQUIRED
+  "sentiment": 0.5,                    // Neutral-positive default
+  "relationship": "friend",           // REQUIRED - must specify
+  "exposure_current": 0.0,            // Default
+  "exposure_desired": 0.5             // Default medium interest
+}
+
+MERGING RULES:
+- exposure_current: Take HIGHER (0.4 + 0.2 → 0.4)
+- exposure_desired: Take HIGHER (0.6 + 0.3 → 0.6)
+- sentiment: AVERAGE (0.7 + 0.5 → 0.6)
+- relationship: Pick most specific/accurate
+- last_ei_asked: Keep most recent non-null
+
+RELATIONSHIP types:
+- friend, family, coworker, mentor, acquaintance, partner, client, etc.
+- Be specific: "former coworker" > "coworker" when applicable
+
+GOOD vs BAD descriptions:
+✅ GOOD: "Manager at Amazon. Met through a conference in 2019. Shares interest in distributed systems."
+❌ BAD: "Someone the user has mentioned a few times who they seem to know from work..." (vague)`;
+}

package/src/prompts/ceremony/index.ts

@@ -2,6 +2,7 @@ export { buildPersonaExpirePrompt } from "./expire.js";
 export { buildPersonaExplorePrompt } from "./explore.js";
 export { buildDescriptionCheckPrompt } from "./description-check.js";
 export { buildRewriteScanPrompt, buildRewritePrompt } from "./rewrite.js";
+export { buildDedupPrompt } from "./dedup.js";
 export type {
   PersonaExpirePromptData,
   PersonaExpireResult,
@@ -15,4 +16,6 @@ export type {
   RewriteSubjectMatch,
   RewritePromptData,
   RewriteResult,
+  DedupPromptData,
+  DedupResult,
 } from "./types.js";

package/src/prompts/ceremony/types.ts

@@ -95,3 +95,48 @@ export interface RewriteResult {
     category?: string;
   }>;
 }
+
+// =============================================================================
+// DEDUP (Duplicate Entity Merge)
+// =============================================================================
+
+/** Input: cluster of potentially duplicate entities to curate. */
+export interface DedupPromptData {
+  cluster: DataItemBase[];  // 2+ items with 0.90+ cosine similarity
+  itemType: RewriteItemType;
+  similarityRange: { min: number; max: number };  // e.g., { min: 0.90, max: 0.98 }
+}
+
+/** Output: merge decisions (update/remove/add). */
+export interface DedupResult {
+  update: Array<{
+    id: string;
+    type: RewriteItemType;
+    name: string;
+    description: string;
+    sentiment?: number;
+    strength?: number;
+    confidence?: number;
+    exposure_current?: number;
+    exposure_desired?: number;
+    relationship?: string;
+    category?: string;
+    last_updated?: string;
+  }>;
+  remove: Array<{
+    to_be_removed: string;  // UUID of duplicate
+    replaced_by: string;    // UUID of canonical record
+  }>;
+  add: Array<{
+    type: RewriteItemType;
+    name: string;
+    description: string;
+    sentiment?: number;
+    strength?: number;
+    confidence?: number;
+    exposure_current?: number;
+    exposure_desired?: number;
+    relationship?: string;
+    category?: string;
+  }>;
+}

package/src/prompts/heartbeat/check.ts

@@ -74,6 +74,7 @@ function getLastPersonaMessage(history: Message[]): Message | undefined {
  * - Getting recent message history
  */
 export function buildHeartbeatCheckPrompt(data: HeartbeatCheckPromptData): PromptOutput {
+  console.log(`[HeartbeatCheck ${data.persona.name}] Building prompt - topics: ${data.human.topics.length}, people: ${data.human.people.length}, inactive_days: ${data.inactive_days}, history: ${data.recent_history.length} messages`);
   if (!data.persona?.name) {
     throw new Error("buildHeartbeatCheckPrompt: persona.name is required");
   }