@controlflow-ai/daemon 0.1.2 → 0.1.4

package/src/delivery-ws.ts

@@ -0,0 +1,269 @@
+import type { Server, ServerWebSocket } from 'bun';
+import { MessageStore } from './db.js';
+import { failure, HttpError } from './http.js';
+import type { MessageDelivery } from './types.js';
+import type { DeliveryConnectionStats, DeliveryWebSocketSummary } from './messaging-status.js';
+
+export interface DeliveryWebSocketData {
+  kind: 'daemon-delivery';
+  computerId: string;
+  connectionId: string;
+}
+
+export type DeliveryWebSocketFrame =
+  | { type: 'hello'; computer_id: string; connection_id: string }
+  | { type: 'delivery'; delivery: Pick<MessageDelivery, 'id' | 'message_id' | 'chat_id' | 'agent' | 'status'> }
+  | { type: 'pending'; agent: string; pending?: number }
+  | { type: 'pong'; at: string };
+
+export interface DeliveryNotifyResult {
+  deliveries: number;
+  target_connections: number;
+  open_sockets: number;
+  websocket_frames: number;
+}
+
+export type { DeliveryConnectionStats, DeliveryWebSocketSummary } from './messaging-status.js';
+
+export interface DeliveryWebSocketHubOptions {
+  logger?: Partial<Pick<Console, 'log' | 'warn'>>;
+  staleConnectionTimeoutMs?: number | null;
+}
+
+interface DeliveryConnectionTelemetry {
+  computerId: string | null;
+  lastOpenAt: string | null;
+  lastCloseAt: string | null;
+  lastPingAt: string | null;
+  lastPongAt: string | null;
+  lastCloseCode: number | null;
+  lastCloseReason: string | null;
+}
+
+function connectionAuthFromRequest(request: Request): { computerId: string; connectionId: string; token: string } {
+  const url = new URL(request.url);
+  const computerId = request.headers.get('x-pal-computer-id')?.trim() || url.searchParams.get('computer_id')?.trim();
+  const connectionId = request.headers.get('x-pal-connection-id')?.trim() || url.searchParams.get('connection_id')?.trim();
+  const token = request.headers.get('x-pal-connection-token')?.trim() || url.searchParams.get('token')?.trim();
+  if (!computerId || !connectionId || !token) {
+    throw new HttpError(401, 'MISSING_CONNECTION_AUTH', 'computer connection auth is required');
+  }
+  return { computerId, connectionId, token };
+}
+
+function sendFrame(ws: ServerWebSocket<DeliveryWebSocketData>, frame: DeliveryWebSocketFrame): boolean {
+  try {
+    return ws.send(JSON.stringify(frame)) > 0;
+  } catch {
+    return false;
+  }
+}
+
+export class DeliveryWebSocketHub {
+  private readonly socketsByConnection = new Map<string, Set<ServerWebSocket<DeliveryWebSocketData>>>();
+  private readonly telemetryByConnection = new Map<string, DeliveryConnectionTelemetry>();
+  private readonly log: Pick<Console, 'log' | 'warn'>;
+  private readonly staleConnectionTimeoutMs: number | null;
+
+  constructor(private readonly store: MessageStore, options: DeliveryWebSocketHubOptions = {}) {
+    this.log = {
+      log: options.logger?.log ?? console.log,
+      warn: options.logger?.warn ?? console.warn,
+    };
+    this.staleConnectionTimeoutMs = typeof options.staleConnectionTimeoutMs === 'number' && Number.isFinite(options.staleConnectionTimeoutMs) && options.staleConnectionTimeoutMs >= 0
+      ? options.staleConnectionTimeoutMs
+      : null;
+  }
+
+  pruneStaleConnections(now = new Date()): number {
+    if (this.staleConnectionTimeoutMs === null) return 0;
+    const closed = this.store.closeStaleComputerConnections(this.staleConnectionTimeoutMs, now);
+    if (closed > 0) this.log.warn(`[delivery/ws] closed ${closed} stale computer connection(s)`);
+    return closed;
+  }
+
+  private telemetry(connectionId: string, computerId: string | null): DeliveryConnectionTelemetry {
+    let telemetry = this.telemetryByConnection.get(connectionId);
+    if (!telemetry) {
+      telemetry = {
+        computerId,
+        lastOpenAt: null,
+        lastCloseAt: null,
+        lastPingAt: null,
+        lastPongAt: null,
+        lastCloseCode: null,
+        lastCloseReason: null,
+      };
+      this.telemetryByConnection.set(connectionId, telemetry);
+    } else if (computerId) {
+      telemetry.computerId = computerId;
+    }
+    return telemetry;
+  }
+
+  handleUpgrade(request: Request, server: Server<DeliveryWebSocketData>): Response | null {
+    const url = new URL(request.url);
+    if (request.method !== 'GET' || url.pathname !== '/api/daemon/ws') return null;
+    try {
+      const auth = connectionAuthFromRequest(request);
+      const connection = this.store.assertActiveComputerConnection({
+        computerId: auth.computerId,
+        connectionId: auth.connectionId,
+        token: auth.token,
+      });
+      const upgraded = server.upgrade(request, {
+        data: {
+          kind: 'daemon-delivery',
+          computerId: connection.computer_id,
+          connectionId: connection.id,
+        },
+      });
+      return upgraded
+        ? new Response(null)
+        : new Response('websocket upgrade failed', { status: 400 });
+    } catch (error) {
+      return failure(error);
+    }
+  }
+
+  websocket = {
+    open: (ws: ServerWebSocket<DeliveryWebSocketData>) => {
+      const { connectionId, computerId } = ws.data;
+      let sockets = this.socketsByConnection.get(connectionId);
+      if (!sockets) {
+        sockets = new Set();
+        this.socketsByConnection.set(connectionId, sockets);
+      }
+      sockets.add(ws);
+      const telemetry = this.telemetry(connectionId, computerId);
+      telemetry.lastOpenAt = new Date().toISOString();
+      telemetry.lastCloseAt = null;
+      telemetry.lastCloseCode = null;
+      telemetry.lastCloseReason = null;
+      this.log.log(`[delivery/ws] open computer=${computerId} connection=${connectionId} sockets=${sockets.size}`);
+      sendFrame(ws, { type: 'hello', computer_id: computerId, connection_id: connectionId });
+      for (const { agent, pending } of this.store.listPendingDeliveryAgentsForConnection(connectionId)) {
+        sendFrame(ws, { type: 'pending', agent, pending });
+      }
+    },
+    message: (ws: ServerWebSocket<DeliveryWebSocketData>, data: string | Buffer) => {
+      if (String(data) === 'ping') {
+        const at = new Date().toISOString();
+        const telemetry = this.telemetry(ws.data.connectionId, ws.data.computerId);
+        telemetry.lastPingAt = at;
+        if (sendFrame(ws, { type: 'pong', at })) {
+          telemetry.lastPongAt = at;
+        }
+      }
+    },
+    close: (ws: ServerWebSocket<DeliveryWebSocketData>, code: number, reason: string) => {
+      const sockets = this.socketsByConnection.get(ws.data.connectionId);
+      if (sockets) {
+        sockets.delete(ws);
+        if (sockets.size === 0) this.socketsByConnection.delete(ws.data.connectionId);
+      }
+      const telemetry = this.telemetry(ws.data.connectionId, ws.data.computerId);
+      telemetry.lastCloseAt = new Date().toISOString();
+      telemetry.lastCloseCode = code;
+      telemetry.lastCloseReason = reason || null;
+      this.log.log(`[delivery/ws] close computer=${ws.data.computerId} connection=${ws.data.connectionId} code=${code} sockets=${sockets?.size ?? 0}`);
+    },
+  };
+
+  notifyDeliveries(deliveries: MessageDelivery[]): DeliveryNotifyResult {
+    this.pruneStaleConnections();
+    const targetConnections = new Set<string>();
+    const pendingAgentsByConnection = new Map<string, Set<string>>();
+    let pendingDeliveries = 0;
+    let openSockets = 0;
+    let websocketFrames = 0;
+    for (const delivery of deliveries) {
+      if (delivery.status !== 'pending') continue;
+      pendingDeliveries += 1;
+      for (const connectionId of this.store.listOnlineDaemonConnectionsForAgent(delivery.agent)) {
+        targetConnections.add(connectionId);
+        let pendingAgents = pendingAgentsByConnection.get(connectionId);
+        if (!pendingAgents) {
+          pendingAgents = new Set();
+          pendingAgentsByConnection.set(connectionId, pendingAgents);
+        }
+        pendingAgents.add(delivery.agent);
+      }
+    }
+
+    for (const [connectionId, agents] of pendingAgentsByConnection) {
+      const sockets = this.socketsByConnection.get(connectionId);
+      if (!sockets?.size) continue;
+      openSockets += sockets.size;
+      const pendingCounts = new Map(
+        this.store.listPendingDeliveryAgentsForConnection(connectionId).map((item) => [item.agent, item.pending]),
+      );
+      for (const agent of agents) {
+        for (const ws of sockets) {
+          if (sendFrame(ws, { type: 'pending', agent, pending: pendingCounts.get(agent) ?? 0 })) {
+            websocketFrames += 1;
+          }
+        }
+      }
+    }
+    return {
+      deliveries: pendingDeliveries,
+      target_connections: targetConnections.size,
+      open_sockets: openSockets,
+      websocket_frames: websocketFrames,
+    };
+  }
+
+  statsForConnection(connectionId: string): DeliveryConnectionStats {
+    const connection = this.store.getComputerConnection(connectionId);
+    const telemetry = this.telemetryByConnection.get(connectionId);
+    return {
+      connection_id: connectionId,
+      computer_id: connection?.computer_id ?? telemetry?.computerId ?? null,
+      open_sockets: this.socketsByConnection.get(connectionId)?.size ?? 0,
+      last_open_at: telemetry?.lastOpenAt ?? null,
+      last_close_at: telemetry?.lastCloseAt ?? null,
+      last_ping_at: telemetry?.lastPingAt ?? null,
+      last_pong_at: telemetry?.lastPongAt ?? null,
+      last_close_code: telemetry?.lastCloseCode ?? null,
+      last_close_reason: telemetry?.lastCloseReason ?? null,
+      pending_agents: this.store.listPendingDeliveryAgentsForConnection(connectionId),
+      backlog: this.store.listDeliveryBacklogForConnection(connectionId),
+    };
+  }
+
+  statsAllConnections(): DeliveryWebSocketSummary {
+    this.pruneStaleConnections();
+    const connections = this.store.listActiveComputerConnections()
+      .map((connection) => this.statsForConnection(connection.id));
+    return {
+      connections,
+      totals: connections.reduce((totals, connection) => {
+        totals.connections += 1;
+        totals.open_sockets += connection.open_sockets;
+        for (const item of connection.backlog) {
+          totals.pending_deliveries += item.pending;
+          totals.claimed_deliveries += item.claimed;
+          totals.processing_completed_deliveries += item.processing_completed;
+          totals.expired_active_deliveries += item.expired_active;
+        }
+        return totals;
+      }, {
+        connections: 0,
+        open_sockets: 0,
+        pending_deliveries: 0,
+        claimed_deliveries: 0,
+        processing_completed_deliveries: 0,
+        expired_active_deliveries: 0,
+      }),
+    };
+  }
+
+  close(): void {
+    for (const sockets of this.socketsByConnection.values()) {
+      for (const ws of sockets) ws.close(1001, 'server shutting down');
+    }
+    this.socketsByConnection.clear();
+  }
+
+}

package/src/format.ts

@@ -5,7 +5,10 @@ export function formatMessage(message: Message): string {
   const chatName = sanitizeProviderIds(message.chat_name);
   const target = message.parent_id === null ? `#${chatName}` : `#${chatName}:${message.parent_id}`;
   const to = message.recipient ? ` -> @${sanitizeProviderIds(message.recipient)}` : '';
-  return `[${message.id} ${target} ${message.created_at}] @${sanitizeProviderIds(message.sender)}${to}: ${sanitizeProviderIds(message.content)}`;
+  const mentions = message.mentions?.length
+    ? ` -> ${message.mentions.map((mention) => `@${sanitizeProviderIds(mention)}`).join(',')}`
+    : '';
+  return `[${message.id} ${target} ${message.created_at}] @${sanitizeProviderIds(message.sender)}${to || mentions}: ${sanitizeProviderIds(message.content)}`;
 }
 
 export function formatMessages(messages: Message[]): string {

package/src/lark/cli.ts

@@ -195,17 +195,17 @@ async function runDaemon(argv: LarkCliArgs, log: NonNullable<RunOptions['log']>)
   let resolvedRuntime: string | null = null;
   if (agentSpec) {
     const directRuntime = agentSpec.split(':')[0];
-    if (directRuntime === 'neeko' || directRuntime === 'coco' || directRuntime === 'coco-stream-json' || directRuntime === 'codex') {
+    if (directRuntime === 'neeko' || directRuntime === 'coco' || directRuntime === 'codex') {
       resolvedRuntime = directRuntime;
     } else {
       resolvedRuntime = msgStore.getAgentRuntime(agentSpec);
       if (!resolvedRuntime) {
-        (log.warn ?? console.warn)(`[lark] agent ${agentSpec} has no runtime configured in DB; defaulting to neeko. Run "bun run src/cli.ts agents create --key ${agentSpec} --name <name> --runtime neeko|coco|coco-stream-json|codex" to configure.`);
+        (log.warn ?? console.warn)(`[lark] agent ${agentSpec} has no runtime configured in DB; defaulting to neeko. Run "bun run src/cli.ts agents create --key ${agentSpec} --name <name> --runtime neeko|coco|codex" to configure.`);
         resolvedRuntime = 'neeko';
       }
     }
   }
-  const isDeliveryAgent = resolvedRuntime === 'neeko' || resolvedRuntime === 'coco' || resolvedRuntime === 'coco-stream-json' || resolvedRuntime === 'codex';
+  const isDeliveryAgent = resolvedRuntime === 'neeko' || resolvedRuntime === 'coco' || resolvedRuntime === 'codex';
 
   const dispatchers = new Map<string, { dispatcher: ChatDispatcher; periodic: PeriodicQueue | null; chatIdToLarkChatId: Map<string, string> }>();
   if (agentSpec && !isDeliveryAgent) {

package/src/lark/event-router.ts

@@ -14,7 +14,7 @@ import { palIdentityHandle } from '../provider-identity.js';
  * | message.chat_id                   | chatName (prefixed `lark:`) |
  * | message.message_id                | idempotencyKey            |
  * | sender.sender_id.open_id          | sender                    |
- * | message.mentions[0]?.id.open_id   | recipient (first @mention)|
+ * | message.mentions[].id.open_id      | mentions for group delivery; recipient for non-group direct routing |
  * | message.content (parsed JSON text)| content                   |
  * | message.root_id (thread reply)    | parentId via lookup       |
  *
@@ -61,10 +61,16 @@ export interface MapLarkMessageResult {
   status: 'ok' | 'skipped';
   reason?: 'missing_message_id' | 'missing_chat_id' | 'missing_sender' | 'unsupported_message_type' | 'empty_text';
   input?: CreateMessageInput;
-  /** Lark root_id when present (for thread replies). The router pre-resolves the parentId from it if possible. */
+  /** Lark root_id, or parent_id when root_id is absent, used to pre-resolve the local topic parent. */
   rootMessageId?: string;
 }
 
+export interface LarkImageResource {
+  fileKey: string;
+  filename: string;
+  mimeType: string;
+}
+
 export function buildLockChatName(appId: string, chatId: string, chatType?: string): string {
   if (chatType === 'group') {
     return `lark:group:${chatId}`;
@@ -125,6 +131,49 @@ function parseLarkTextContent(rawContent: string | undefined, messageType: strin
   }
 }
 
+function parseJsonObject(rawContent: string | undefined): Record<string, unknown> | null {
+  if (!rawContent) return null;
+  try {
+    const parsed = JSON.parse(rawContent) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+export function extractLarkImageResources(envelope: LarkMessageEnvelope): LarkImageResource[] {
+  const msg = envelope.message;
+  const out: LarkImageResource[] = [];
+  const seen = new Set<string>();
+  const add = (fileKey: unknown, filename?: unknown) => {
+    if (typeof fileKey !== 'string' || !fileKey.trim() || seen.has(fileKey)) return;
+    seen.add(fileKey);
+    out.push({
+      fileKey,
+      filename: typeof filename === 'string' && filename.trim() ? filename.trim() : `${fileKey}.jpg`,
+      mimeType: 'image/jpeg',
+    });
+  };
+  const parsed = parseJsonObject(msg?.content);
+  if (msg?.message_type === 'image') {
+    add(parsed?.image_key ?? parsed?.file_key, parsed?.file_name ?? parsed?.name);
+  }
+  if (msg?.message_type === 'post' && parsed) {
+    const content = parsed.content;
+    if (Array.isArray(content)) {
+      for (const line of content) {
+        if (!Array.isArray(line)) continue;
+        for (const item of line) {
+          if (!item || typeof item !== 'object') continue;
+          const record = item as Record<string, unknown>;
+          if (record.tag === 'img' || record.tag === 'image') add(record.image_key ?? record.file_key);
+        }
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * Pure mapper: no DB access. Returns a `CreateMessageInput` skeleton (without
  * parentId resolution — that happens in `resolveThreadParent`).
@@ -146,11 +195,14 @@ export function mapLarkMessageToCreateInput(input: MapLarkMessageInput): MapLark
     ...(mentionsAllAgents(envelope) ? [ALL_AGENTS_MENTION] : []),
     ...(msg.mentions?.map((m) => m.id?.open_id ? input.recipientByMentionOpenId?.get(m.id.open_id) ?? null : null) ?? []),
   ]);
+  const firstMappedMention = firstMention ? input.recipientByMentionOpenId?.get(firstMention) : undefined;
   const recipient = input.recipientOverride !== undefined
     ? input.recipientOverride
-    : firstMention ? input.recipientByMentionOpenId?.get(firstMention) ?? firstMention : null;
+    : msg.chat_type === 'group'
+      ? null
+      : firstMention ? firstMappedMention ?? firstMention : null;
   const chatName = buildLockChatName(input.appId, msg.chat_id, msg.chat_type);
-  const rootMessageId = msg.root_id?.trim() || undefined;
+  const rootMessageId = msg.root_id?.trim() || msg.parent_id?.trim() || undefined;
 
   const createInput: CreateMessageInput = {
     chatName,
@@ -291,6 +343,8 @@ export function ingestLarkMessage(input: IngestLarkMessageInput): IngestLarkMess
         content: mapped.input.content,
         type: mapped.input.type,
         idempotencyKey: mapped.input.idempotencyKey,
+        provider: 'lark',
+        mentions: mapped.input.mentions,
       }
     : threadOrphan
       ? {
@@ -300,6 +354,8 @@ export function ingestLarkMessage(input: IngestLarkMessageInput): IngestLarkMess
           content: mapped.input.content,
           type: mapped.input.type,
           idempotencyKey: mapped.input.idempotencyKey,
+          provider: 'lark',
+          mentions: mapped.input.mentions,
         }
       : { ...mapped.input, sender: senderHandle || mapped.input.sender };
 

package/src/lark/inbound-events.ts

@@ -10,6 +10,8 @@ export interface InboundRawEvent {
   raw_body_bytes: Uint8Array;
 }
 
+export type InboundRawEventSummary = Omit<InboundRawEvent, 'raw_body_bytes'>;
+
 export interface StoreInboundEventInput {
   appId: string;
   rawBody: string | Uint8Array;
@@ -24,6 +26,31 @@ export interface StoreInboundEventResult {
   duplicate: boolean;
 }
 
+export interface RepairInboundEventParseFailuresOptions {
+  appId?: string;
+  limit?: number;
+  dryRun?: boolean;
+}
+
+export interface RepairInboundEventParseFailuresResult {
+  dry_run: boolean;
+  scanned: number;
+  repaired: number;
+  unchanged: number;
+  conflicts: number;
+  errors: number;
+  rows: Array<{
+    id: string;
+    app_id: string;
+    old_event_id: string;
+    old_event_type: string;
+    new_event_id: string;
+    new_event_type: string;
+    status: 'repaired' | 'would_repair' | 'unchanged' | 'conflict' | 'error';
+    error?: string;
+  }>;
+}
+
 const ENCODER = new TextEncoder();
 
 function toBytes(body: string | Uint8Array): Uint8Array {
@@ -48,8 +75,9 @@ export async function parseEventEnvelope(rawBytes: Uint8Array): Promise<ParsedEn
     const text = new TextDecoder('utf8', { fatal: false }).decode(rawBytes);
     const json = JSON.parse(text) as Record<string, unknown>;
     const header = (json.header && typeof json.header === 'object') ? json.header as Record<string, unknown> : null;
-    const eventId = (header?.event_id ?? json.uuid) as unknown;
-    const eventType = (header?.event_type ?? json.type) as unknown;
+    const event = (json.event && typeof json.event === 'object') ? json.event as Record<string, unknown> : null;
+    const eventId = (header?.event_id ?? event?.event_id ?? json.uuid) as unknown;
+    const eventType = (header?.event_type ?? event?.event_type ?? json.type) as unknown;
     if (typeof eventId === 'string' && eventId.length > 0 && typeof eventType === 'string' && eventType.length > 0) {
       return { event_id: eventId, event_type: eventType, parse_ok: 1 };
     }
@@ -117,10 +145,22 @@ export function getInboundEvent(db: Database, id: string): InboundRawEvent | nul
 
 export function listRecentInboundEvents(db: Database, limit = 20): InboundRawEvent[] {
   return db
-    .query('SELECT id, received_at, app_id, event_type, event_id, parse_ok, raw_body_bytes FROM channel_inbound_raw_events ORDER BY received_at DESC, id DESC LIMIT ?')
+    .query('SELECT id, received_at, app_id, event_type, event_id, parse_ok, raw_body_bytes FROM channel_inbound_raw_events ORDER BY received_at DESC, rowid DESC LIMIT ?')
     .all(Math.max(1, Math.min(limit, 500))) as InboundRawEvent[];
 }
 
+export function latestInboundEventSummary(db: Database, appId: string): InboundRawEventSummary | null {
+  return db
+    .query("SELECT id, received_at, app_id, event_type, event_id, parse_ok FROM channel_inbound_raw_events WHERE app_id = ? AND event_type NOT LIKE 'pal.probe.%' ORDER BY received_at DESC, rowid DESC LIMIT 1")
+    .get(appId) as InboundRawEventSummary | null;
+}
+
+export function latestProbeInboundEventSummary(db: Database, appId: string): InboundRawEventSummary | null {
+  return db
+    .query("SELECT id, received_at, app_id, event_type, event_id, parse_ok FROM channel_inbound_raw_events WHERE app_id = ? AND event_type LIKE 'pal.probe.%' ORDER BY received_at DESC, rowid DESC LIMIT 1")
+    .get(appId) as InboundRawEventSummary | null;
+}
+
 export function countInboundEvents(db: Database, appId?: string): number {
   if (appId) {
     const row = db.query('SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE app_id = ?').get(appId) as { n: number };
@@ -129,3 +169,116 @@ export function countInboundEvents(db: Database, appId?: string): number {
   const row = db.query('SELECT COUNT(*) AS n FROM channel_inbound_raw_events').get() as { n: number };
   return row.n;
 }
+
+export function countProviderInboundEvents(db: Database, appId?: string): number {
+  if (appId) {
+    const row = db.query("SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE app_id = ? AND event_type NOT LIKE 'pal.probe.%'").get(appId) as { n: number };
+    return row.n;
+  }
+  const row = db.query("SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE event_type NOT LIKE 'pal.probe.%'").get() as { n: number };
+  return row.n;
+}
+
+export function countProbeInboundEvents(db: Database, appId?: string): number {
+  if (appId) {
+    const row = db.query("SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE app_id = ? AND event_type LIKE 'pal.probe.%'").get(appId) as { n: number };
+    return row.n;
+  }
+  const row = db.query("SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE event_type LIKE 'pal.probe.%'").get() as { n: number };
+  return row.n;
+}
+
+export function countInboundParseFailures(db: Database, appId?: string): number {
+  if (appId) {
+    const row = db.query('SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE app_id = ? AND parse_ok = 0').get(appId) as { n: number };
+    return row.n;
+  }
+  const row = db.query('SELECT COUNT(*) AS n FROM channel_inbound_raw_events WHERE parse_ok = 0').get() as { n: number };
+  return row.n;
+}
+
+export async function repairInboundEventParseFailures(
+  db: Database,
+  options: RepairInboundEventParseFailuresOptions = {},
+): Promise<RepairInboundEventParseFailuresResult> {
+  const limit = Math.max(1, Math.min(options.limit ?? 100, 1000));
+  const dryRun = options.dryRun ?? false;
+  const rows = options.appId
+    ? db
+      .query('SELECT id, app_id, event_type, event_id, raw_body_bytes FROM channel_inbound_raw_events WHERE app_id = ? AND parse_ok = 0 ORDER BY received_at DESC, rowid DESC LIMIT ?')
+      .all(options.appId, limit)
+    : db
+      .query('SELECT id, app_id, event_type, event_id, raw_body_bytes FROM channel_inbound_raw_events WHERE parse_ok = 0 ORDER BY received_at DESC, rowid DESC LIMIT ?')
+      .all(limit);
+  const result: RepairInboundEventParseFailuresResult = {
+    dry_run: dryRun,
+    scanned: rows.length,
+    repaired: 0,
+    unchanged: 0,
+    conflicts: 0,
+    errors: 0,
+    rows: [],
+  };
+
+  for (const row of rows as Array<{ id: string; app_id: string; event_type: string; event_id: string; raw_body_bytes: Uint8Array }>) {
+    const parsed = await parseEventEnvelope(row.raw_body_bytes);
+    if (parsed.parse_ok !== 1) {
+      result.unchanged += 1;
+      result.rows.push({
+        id: row.id,
+        app_id: row.app_id,
+        old_event_id: row.event_id,
+        old_event_type: row.event_type,
+        new_event_id: parsed.event_id,
+        new_event_type: parsed.event_type,
+        status: 'unchanged',
+      });
+      continue;
+    }
+    if (dryRun) {
+      result.repaired += 1;
+      result.rows.push({
+        id: row.id,
+        app_id: row.app_id,
+        old_event_id: row.event_id,
+        old_event_type: row.event_type,
+        new_event_id: parsed.event_id,
+        new_event_type: parsed.event_type,
+        status: 'would_repair',
+      });
+      continue;
+    }
+    try {
+      db
+        .query('UPDATE channel_inbound_raw_events SET event_id = ?, event_type = ?, parse_ok = 1 WHERE id = ?')
+        .run(parsed.event_id, parsed.event_type, row.id);
+      result.repaired += 1;
+      result.rows.push({
+        id: row.id,
+        app_id: row.app_id,
+        old_event_id: row.event_id,
+        old_event_type: row.event_type,
+        new_event_id: parsed.event_id,
+        new_event_type: parsed.event_type,
+        status: 'repaired',
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const conflict = message.toLowerCase().includes('unique') || message.toLowerCase().includes('constraint');
+      if (conflict) result.conflicts += 1;
+      else result.errors += 1;
+      result.rows.push({
+        id: row.id,
+        app_id: row.app_id,
+        old_event_id: row.event_id,
+        old_event_type: row.event_type,
+        new_event_id: parsed.event_id,
+        new_event_type: parsed.event_type,
+        status: conflict ? 'conflict' : 'error',
+        error: message,
+      });
+    }
+  }
+
+  return result;
+}