vellum 0.2.1 → 0.2.7

package/src/calls/call-orchestrator.ts

@@ -16,9 +16,10 @@ import {
   createPendingQuestion,
   expirePendingQuestions,
 } from './call-store.js';
-import { MAX_CALL_DURATION_MS, USER_CONSULTATION_TIMEOUT_MS, SILENCE_TIMEOUT_MS } from './call-constants.js';
+import { getMaxCallDurationMs, getUserConsultationTimeoutMs, SILENCE_TIMEOUT_MS } from './call-constants.js';
 import type { RelayConnection } from './relay-server.js';
 import { registerCallOrchestrator, unregisterCallOrchestrator, fireCallQuestionNotifier, fireCallCompletionNotifier } from './call-state.js';
+import type { PromptSpeakerContext } from './speaker-identification.js';
 
 const log = getLogger('call-orchestrator');
 
@@ -60,7 +61,7 @@ export class CallOrchestrator {
   /**
    * Handle a final caller utterance from the ConversationRelay.
    */
-  async handleCallerUtterance(transcript: string): Promise<void> {
+  async handleCallerUtterance(transcript: string, speaker?: PromptSpeakerContext): Promise<void> {
     // If we're already processing or speaking, abort the in-flight generation
     if (this.state === 'processing' || this.state === 'speaking') {
       this.abortController.abort();
@@ -71,7 +72,10 @@ export class CallOrchestrator {
     this.resetSilenceTimer();
 
     // Append caller utterance
-    this.conversationHistory.push({ role: 'user', content: transcript });
+    this.conversationHistory.push({
+      role: 'user',
+      content: this.formatCallerUtterance(transcript, speaker),
+    });
 
     await this.runLlm();
   }
@@ -100,7 +104,11 @@ export class CallOrchestrator {
     // Append the user's answer as a special message the model recognizes
     this.conversationHistory.push({ role: 'user', content: `[USER_ANSWERED: ${answerText}]` });
 
-    await this.runLlm();
+    // Fire-and-forget: unblock the caller so the HTTP response and answer
+    // persistence happen immediately, before LLM streaming begins.
+    this.runLlm().catch((err) =>
+      log.error({ err, callSessionId: this.callSessionId }, 'runLlm failed after user answer'),
+    );
     return true;
   }
 
@@ -130,6 +138,11 @@ export class CallOrchestrator {
   // ── Private ──────────────────────────────────────────────────────
 
   private buildSystemPrompt(): string {
+    const config = getConfig();
+    const disclosureRule = config.calls.disclosure.enabled
+      ? `1. ${config.calls.disclosure.text}`
+      : '1. Begin the conversation naturally.';
+
     return [
       'You are on a live phone call on behalf of your user.',
       this.task ? `Task: ${this.task}` : '',
@@ -138,18 +151,27 @@ export class CallOrchestrator {
       'Respond naturally and conversationally — speak as you would in a real phone conversation.',
       '',
       'IMPORTANT RULES:',
-      '1. At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+      disclosureRule,
       '2. Be concise — phone conversations should be brief and natural.',
       '3. If the callee asks something you don\'t know, include [ASK_USER: your question here] in your response along with a hold message like "Let me check on that for you."',
       '4. If the callee provides information preceded by [USER_ANSWERED: ...], use that answer naturally in the conversation.',
       '5. When the call\'s purpose is fulfilled, include [END_CALL] in your response along with a polite goodbye.',
       '6. Do not make up information — ask the user if unsure.',
       '7. Keep responses short — 1-3 sentences is ideal for phone conversation.',
+      '8. When caller text includes [SPEAKER id="..." label="..."], treat each speaker as a distinct person and personalize responses using that speaker\'s prior context in this call.',
     ]
       .filter(Boolean)
       .join('\n');
   }
 
+  private formatCallerUtterance(transcript: string, speaker?: PromptSpeakerContext): string {
+    if (!speaker) return transcript;
+    const safeId = speaker.speakerId.replaceAll('"', '\'');
+    const safeLabel = speaker.speakerLabel.replaceAll('"', '\'');
+    const confidencePart = speaker.speakerConfidence !== null ? ` confidence="${speaker.speakerConfidence.toFixed(2)}"` : '';
+    return `[SPEAKER id="${safeId}" label="${safeLabel}" source="${speaker.source}"${confidencePart}] ${transcript}`;
+  }
+
   /**
    * Run the LLM with the current conversation history and stream
    * the response back through the relay.
@@ -215,7 +237,8 @@ export class CallOrchestrator {
             '[ASK_USER:'.startsWith(afterBracket) ||
             '[END_CALL]'.startsWith(afterBracket) ||
             afterBracket.startsWith('[ASK_USER:') ||
-            afterBracket.startsWith('[END_CALL');
+            afterBracket === '[END_CALL' ||
+            afterBracket.startsWith('[END_CALL]');
 
           if (!couldBeControl) {
             // Not a control marker prefix — flush up to the next '[' (if any)
@@ -295,7 +318,7 @@ export class CallOrchestrator {
             updateCallSession(this.callSessionId, { status: 'in_progress' });
             expirePendingQuestions(this.callSessionId);
           }
-        }, USER_CONSULTATION_TIMEOUT_MS);
+        }, getUserConsultationTimeoutMs());
         return;
       }
 
@@ -329,15 +352,18 @@ export class CallOrchestrator {
   }
 
   private startDurationTimer(): void {
-    const warningMs = MAX_CALL_DURATION_MS - 2 * 60 * 1000; // 2 minutes before max
-
-    this.durationWarningTimer = setTimeout(() => {
-      log.info({ callSessionId: this.callSessionId }, 'Call duration warning');
-      this.relay.sendTextToken(
-        'Just to let you know, we\'re running low on time for this call.',
-        true,
-      );
-    }, warningMs);
+    const maxDurationMs = getMaxCallDurationMs();
+    const warningMs = maxDurationMs - 2 * 60 * 1000; // 2 minutes before max
+
+    if (warningMs > 0) {
+      this.durationWarningTimer = setTimeout(() => {
+        log.info({ callSessionId: this.callSessionId }, 'Call duration warning');
+        this.relay.sendTextToken(
+          'Just to let you know, we\'re running low on time for this call.',
+          true,
+        );
+      }, warningMs);
+    }
 
     this.durationTimer = setTimeout(() => {
       log.info({ callSessionId: this.callSessionId }, 'Call duration limit reached');
@@ -351,7 +377,7 @@ export class CallOrchestrator {
         updateCallSession(this.callSessionId, { status: 'completed', endedAt: Date.now() });
         recordCallEvent(this.callSessionId, 'call_ended', { reason: 'max_duration' });
       }, 3000);
-    }, MAX_CALL_DURATION_MS);
+    }, maxDurationMs);
   }
 
   private resetSilenceTimer(): void {

package/src/calls/call-recovery.ts

@@ -0,0 +1,207 @@
+/**
+ * Call recovery — reconciles in-flight calls on daemon restart.
+ *
+ * When the daemon restarts, any calls left in non-terminal states may be stale
+ * (the daemon crashed mid-call) or still active on the provider side. This
+ * module fetches the actual provider status and transitions each call
+ * accordingly.
+ */
+
+import { getLogger } from '../util/logger.js';
+import { listRecoverableCalls, updateCallSession, expirePendingQuestions } from './call-store.js';
+import type { VoiceProvider } from './voice-provider.js';
+import type { CallStatus } from './types.js';
+
+type Logger = ReturnType<typeof getLogger>;
+
+const defaultLog = getLogger('call-recovery');
+
+/**
+ * Grace period (in ms) for no-SID sessions during startup recovery.
+ *
+ * A daemon crash can leave a live Twilio call without a persisted SID
+ * (crash after `initiateCall` succeeds but before the SID is written).
+ * Webhooks carrying the SID may still arrive after restart.
+ *
+ * Sessions younger than this threshold are annotated but left in their
+ * current non-terminal state so incoming webhooks can still deliver the
+ * SID and resume the call normally.
+ *
+ * Sessions older than this threshold are transitioned to `failed` to
+ * prevent orphan sessions from creating false "active call" state
+ * indefinitely. 5 minutes is long enough for any legitimate webhook
+ * to arrive; after that the session is considered abandoned.
+ */
+export const NO_SID_GRACE_PERIOD_MS = 5 * 60_000;
+
+/**
+ * Map a Twilio provider status string to our internal CallStatus.
+ * Returns the mapped status or null if the status is unrecognised.
+ */
+function mapProviderStatus(providerStatus: string): CallStatus | null {
+  switch (providerStatus) {
+    case 'queued':
+    case 'ringing':
+      return 'ringing';
+    case 'in-progress':
+      return 'in_progress';
+    case 'completed':
+      return 'completed';
+    case 'failed':
+    case 'busy':
+    case 'no-answer':
+    case 'canceled':
+      return 'failed';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Check whether a CallStatus is terminal (no further transitions allowed).
+ */
+function isTerminal(status: CallStatus): boolean {
+  return status === 'completed' || status === 'failed' || status === 'cancelled';
+}
+
+/**
+ * Reconcile all non-terminal call sessions at daemon startup.
+ *
+ * For each recoverable call:
+ * - If it has a provider SID, fetch the current status from the provider
+ *   and transition the call to match.
+ * - If no provider SID exists and the session is older than the grace
+ *   period, transition it to `failed` to prevent orphan sessions from
+ *   creating false "active call" state indefinitely.
+ * - If no provider SID exists but the session is within the grace period,
+ *   leave it non-terminal so webhooks can still deliver the SID.
+ * - If the call transitions to a terminal state, expire any pending questions.
+ */
+export async function reconcileCallsOnStartup(
+  provider: VoiceProvider,
+  log: Logger = defaultLog,
+): Promise<void> {
+  const recoverableCalls = listRecoverableCalls();
+
+  if (recoverableCalls.length === 0) {
+    log.info('No recoverable calls found at startup');
+    return;
+  }
+
+  log.info({ count: recoverableCalls.length }, 'Reconciling non-terminal calls at startup');
+
+  for (const session of recoverableCalls) {
+    try {
+      if (!session.providerCallSid) {
+        const sessionAgeMs = Date.now() - session.createdAt;
+        const isStale = sessionAgeMs >= NO_SID_GRACE_PERIOD_MS;
+
+        if (isStale) {
+          // Session is old enough that any legitimate webhook should
+          // have arrived by now.  Transition to `failed` so it no
+          // longer appears as an active call.
+          log.info(
+            { callSessionId: session.id, previousStatus: session.status, sessionAgeMs },
+            'No-SID session past grace period — failing orphan session',
+          );
+          updateCallSession(session.id, {
+            status: 'failed',
+            endedAt: Date.now(),
+            lastError: 'Daemon restarted before provider SID persisted; grace period expired — orphan session failed',
+          });
+          expirePendingQuestions(session.id);
+        } else {
+          // Recent session — webhooks carrying the SID may still arrive.
+          // Leave in its current non-terminal state.
+          log.info(
+            { callSessionId: session.id, previousStatus: session.status, sessionAgeMs },
+            'Skipping recent no-SID session (within grace period, webhooks may still arrive)',
+          );
+          updateCallSession(session.id, {
+            lastError: 'Daemon restarted before provider SID persisted; awaiting webhook',
+          });
+        }
+        continue;
+      }
+
+      // Fetch actual status from provider
+      let providerStatus: string;
+      try {
+        providerStatus = await provider.getCallStatus(session.providerCallSid);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.warn(
+          { callSessionId: session.id, callSid: session.providerCallSid, err },
+          'Failed to fetch provider status during recovery — failing call',
+        );
+        updateCallSession(session.id, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: `Recovery: failed to fetch provider status: ${msg}`,
+        });
+        expirePendingQuestions(session.id);
+        continue;
+      }
+
+      const mappedStatus = mapProviderStatus(providerStatus);
+
+      if (!mappedStatus) {
+        log.warn(
+          { callSessionId: session.id, providerStatus },
+          'Unrecognised provider status during recovery — failing call',
+        );
+        updateCallSession(session.id, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: `Recovery: unrecognised provider status '${providerStatus}'`,
+        });
+        expirePendingQuestions(session.id);
+        continue;
+      }
+
+      if (isTerminal(mappedStatus)) {
+        // Provider says the call has ended
+        log.info(
+          { callSessionId: session.id, providerStatus, mappedStatus },
+          'Provider reports call ended — transitioning to terminal state',
+        );
+        updateCallSession(session.id, {
+          status: mappedStatus,
+          endedAt: Date.now(),
+        });
+        expirePendingQuestions(session.id);
+      } else {
+        // Provider says call is still active — leave it for webhooks to handle
+        log.info(
+          { callSessionId: session.id, providerStatus, mappedStatus },
+          'Provider reports call still active — leaving for webhook handling',
+        );
+      }
+    } catch (err) {
+      log.error(
+        { callSessionId: session.id, err },
+        'Unexpected error during call recovery',
+      );
+    }
+  }
+
+  log.info('Call recovery reconciliation complete');
+}
+
+/**
+ * Log a dead-letter provider event — a provider callback payload that
+ * could not be processed (malformed, unknown format, etc.).
+ *
+ * Rather than silently dropping these events, we log the full payload
+ * so operators can investigate later.
+ */
+export function logDeadLetterEvent(
+  reason: string,
+  payload: unknown,
+  log: Logger = defaultLog,
+): void {
+  log.error(
+    { reason, payload },
+    'Dead-letter provider event: callback could not be processed',
+  );
+}

package/src/calls/call-state-machine.ts

@@ -0,0 +1,68 @@
+/**
+ * Call state machine — defines allowed status transitions and validates
+ * all state changes in a single place.
+ *
+ * Terminal states (completed, failed, cancelled) are immutable: no further
+ * transitions are permitted once a call reaches one of these states.
+ */
+
+import type { CallStatus } from './types.js';
+
+// ── Transition table ─────────────────────────────────────────────────
+
+/**
+ * Maps each call status to the set of statuses it may transition to.
+ * Terminal states map to an empty set.
+ */
+const ALLOWED_TRANSITIONS: Record<CallStatus, Set<CallStatus>> = {
+  initiated: new Set<CallStatus>(['ringing', 'in_progress', 'waiting_on_user', 'completed', 'failed', 'cancelled']),
+  ringing: new Set<CallStatus>(['in_progress', 'waiting_on_user', 'completed', 'failed', 'cancelled']),
+  in_progress: new Set<CallStatus>(['waiting_on_user', 'completed', 'failed', 'cancelled']),
+  waiting_on_user: new Set<CallStatus>(['in_progress', 'completed', 'failed', 'cancelled']),
+  // Terminal states — no further transitions allowed
+  completed: new Set<CallStatus>(),
+  failed: new Set<CallStatus>(),
+  cancelled: new Set<CallStatus>(),
+};
+
+const TERMINAL_STATES: Set<CallStatus> = new Set(['completed', 'failed', 'cancelled']);
+
+// ── Public API ───────────────────────────────────────────────────────
+
+export interface TransitionResult {
+  valid: boolean;
+  reason?: string;
+}
+
+/**
+ * Check whether a transition from `current` to `next` is allowed.
+ */
+export function validateTransition(current: CallStatus, next: CallStatus): TransitionResult {
+  if (current === next) {
+    return { valid: true };
+  }
+
+  if (isTerminalState(current)) {
+    return {
+      valid: false,
+      reason: `Cannot transition from terminal state '${current}'`,
+    };
+  }
+
+  const allowed = ALLOWED_TRANSITIONS[current];
+  if (!allowed || !allowed.has(next)) {
+    return {
+      valid: false,
+      reason: `Invalid transition from '${current}' to '${next}'`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Returns true if the given status is a terminal (immutable) state.
+ */
+export function isTerminalState(status: CallStatus): boolean {
+  return TERMINAL_STATES.has(status);
+}

package/src/calls/call-store.ts

@@ -2,7 +2,8 @@ import { eq, and, notInArray, desc } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb } from '../memory/db.js';
 import { callSessions, callEvents, callPendingQuestions } from '../memory/schema.js';
-import type { CallSession, CallEvent, CallPendingQuestion, CallEventType } from './types.js';
+import type { CallSession, CallEvent, CallPendingQuestion, CallEventType, CallStatus } from './types.js';
+import { validateTransition } from './call-state-machine.js';
 import { getLogger } from '../util/logger.js';
 
 const log = getLogger('call-store');
@@ -105,7 +106,7 @@ export function getActiveCallSessionForConversation(conversationId: string): Cal
     .where(
       and(
         eq(callSessions.conversationId, conversationId),
-        notInArray(callSessions.status, ['completed', 'failed']),
+        notInArray(callSessions.status, ['completed', 'failed', 'cancelled']),
       ),
     )
     .orderBy(desc(callSessions.createdAt))
@@ -119,12 +120,44 @@ export function updateCallSession(
   updates: Partial<Pick<CallSession, 'status' | 'providerCallSid' | 'startedAt' | 'endedAt' | 'lastError'>>,
 ): void {
   const db = getDb();
+
+  // Validate status transition when a new status is provided
+  if (updates.status) {
+    const current = getCallSession(id);
+    if (current) {
+      const result = validateTransition(current.status, updates.status as CallStatus);
+      if (!result.valid) {
+        log.warn({ callSessionId: id, from: current.status, to: updates.status, reason: result.reason }, 'Invalid call status transition — skipping update');
+        return;
+      }
+    }
+  }
+
   db.update(callSessions)
     .set({ ...updates, updatedAt: Date.now() })
     .where(eq(callSessions.id, id))
     .run();
 }
 
+// ── Recovery queries ─────────────────────────────────────────────────
+
+/**
+ * Returns all call sessions that are in a non-terminal state
+ * (i.e. not completed, failed, or cancelled). Used during daemon startup
+ * to reconcile in-flight calls.
+ */
+export function listRecoverableCalls(): CallSession[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(callSessions)
+    .where(
+      notInArray(callSessions.status, ['completed', 'failed', 'cancelled']),
+    )
+    .all();
+  return rows.map(parseCallSession);
+}
+
 // ── Call Events ──────────────────────────────────────────────────────
 
 export function recordCallEvent(
@@ -207,10 +240,10 @@ export function answerPendingQuestion(id: string, answerText: string): void {
       ),
     )
     .run();
-  // Drizzle's .run() returns void for bun:sqlite, so verify via raw client.
+  // Drizzle's .run() returns void for bun:sqlite, so check affected rows via raw client.
   const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
-  const check = raw.query('SELECT status FROM call_pending_questions WHERE id = ?').get(id) as { status: string } | null;
-  if (!check || check.status !== 'answered') {
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  if (changes.c === 0) {
     log.warn({ questionId: id }, 'answerPendingQuestion: no rows updated — question may have already been answered or expired');
   }
 }
@@ -227,3 +260,157 @@ export function expirePendingQuestions(callSessionId: string): void {
     )
     .run();
 }
+
+// ── Callback Idempotency ─────────────────────────────────────────────
+
+/** Claims older than this are considered orphaned (crashed mid-processing) and can be reclaimed. */
+const CLAIM_EXPIRY_MS = 60_000; // 60 seconds
+
+/**
+ * Build a dedupe key for a Twilio status callback.
+ * Combines CallSid + CallStatus + Timestamp (or SequenceNumber if present)
+ * to uniquely identify each callback.
+ */
+export function buildCallbackDedupeKey(
+  callSid: string,
+  callStatus: string,
+  timestamp?: string | null,
+  sequenceNumber?: string | null,
+): string {
+  const discriminator = sequenceNumber ?? timestamp ?? '';
+  return `${callSid}:${callStatus}:${discriminator}`;
+}
+
+/**
+ * Check whether a callback dedupe key has already been processed (read-only).
+ * Returns true if the key already exists, false otherwise.
+ */
+export function isCallbackProcessed(dedupeKey: string): boolean {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  const row = raw.query(
+    `SELECT 1 FROM processed_callbacks WHERE dedupe_key = ?`,
+  ).get(dedupeKey);
+  return row != null;
+}
+
+/**
+ * Record a callback as processed. Should be called AFTER downstream writes
+ * (session updates, event recording) have succeeded so that Twilio retries
+ * are not silently dropped if those writes fail.
+ *
+ * Uses INSERT OR IGNORE so concurrent calls for the same key are safe.
+ */
+export function recordProcessedCallback(
+  dedupeKey: string,
+  callSessionId: string,
+): void {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  raw.query(
+    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, created_at) VALUES (?, ?, ?, ?)`,
+  ).run(uuid(), dedupeKey, callSessionId, Date.now());
+}
+
+/**
+ * Try to record a processed callback. Returns true if this is a new callback
+ * (inserted successfully). Returns false if the callback was already processed
+ * (dedupe key already exists), indicating a replay.
+ *
+ * Uses INSERT ... ON CONFLICT DO NOTHING pattern for atomicity.
+ *
+ * @deprecated Use claimCallback + releaseCallbackClaim instead to
+ * atomically claim a callback and release on failure.
+ */
+export function tryRecordProcessedCallback(
+  dedupeKey: string,
+  callSessionId: string,
+): boolean {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  raw.query(
+    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, created_at) VALUES (?, ?, ?, ?)`,
+  ).run(uuid(), dedupeKey, callSessionId, Date.now());
+
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  return changes.c > 0;
+}
+
+/**
+ * Atomically claim a callback for processing. Returns a unique claim ID
+ * (string) if this caller won the claim, or null if another caller already
+ * claimed it (dedupe_key conflict).
+ *
+ * Expired orphaned claims (older than CLAIM_EXPIRY_MS) are automatically
+ * cleared before attempting the insert, so crashes mid-processing don't
+ * permanently block retries.
+ *
+ * If processing fails, call `releaseCallbackClaim(dedupeKey, claimId)` to allow retries.
+ * On success, call `finalizeCallbackClaim(dedupeKey, claimId)` to make the claim permanent.
+ *
+ * The returned claim ID acts as an ownership token: release and finalize
+ * operations require it so that handler A cannot accidentally release or
+ * finalize a claim that was reclaimed by handler B after expiry.
+ */
+export function claimCallback(dedupeKey: string, callSessionId: string): string | null {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+
+  // Clear any expired orphaned claims so they can be reprocessed
+  raw.query(
+    `DELETE FROM processed_callbacks WHERE dedupe_key = ? AND created_at < ?`,
+  ).run(dedupeKey, Date.now() - CLAIM_EXPIRY_MS);
+
+  const claimId = uuid();
+  raw.query(
+    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, claim_id, created_at) VALUES (?, ?, ?, ?, ?)`,
+  ).run(uuid(), dedupeKey, callSessionId, claimId, Date.now());
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  return changes.c > 0 ? claimId : null;
+}
+
+/**
+ * Release a callback claim so that retries can reprocess it.
+ * Called when processing fails after a successful claim.
+ *
+ * Only deletes the row if both dedupe_key AND claim_id match, preventing
+ * handler A from releasing a claim that was reclaimed by handler B.
+ */
+export function releaseCallbackClaim(dedupeKey: string, claimId: string): void {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+  raw.query(`DELETE FROM processed_callbacks WHERE dedupe_key = ? AND claim_id = ?`).run(dedupeKey, claimId);
+}
+
+/**
+ * Finalize a callback claim after successful processing.
+ * Sets the created_at to a far-future value so the claim never expires,
+ * distinguishing it from in-flight claims that may need to be reclaimed.
+ *
+ * Only updates the row if both dedupe_key AND claim_id match, preventing
+ * handler A from finalizing a claim that was reclaimed by handler B.
+ *
+ * Returns true if the claim was successfully finalized, or false if 0 rows
+ * were updated — meaning the claim was reclaimed by another handler after
+ * expiry. Callers should treat a false return as a lost-claim signal: the
+ * business writes already happened but the dedupe row belongs to someone
+ * else, so duplicate processing may occur on later retries.
+ */
+export function finalizeCallbackClaim(dedupeKey: string, claimId: string): boolean {
+  const db = getDb();
+  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+  // Set created_at far in the future so expiry check never matches
+  const NEVER_EXPIRE = Date.now() + 100 * 365 * 24 * 60 * 60 * 1000; // ~100 years
+  raw.query(
+    `UPDATE processed_callbacks SET created_at = ? WHERE dedupe_key = ? AND claim_id = ?`,
+  ).run(NEVER_EXPIRE, dedupeKey, claimId);
+  const changes = raw.query('SELECT changes() as c').get() as { c: number };
+  if (changes.c === 0) {
+    log.warn({ dedupeKey, claimId }, 'finalizeCallbackClaim: claim was lost — another handler reclaimed this key after expiry');
+    return false;
+  }
+  return true;
+}