@controlflow-ai/daemon 0.1.0

package/src/db.ts

@@ -0,0 +1,2830 @@
+import { Database, type SQLQueryBindings } from 'bun:sqlite';
+import { createHash, randomBytes } from 'node:crypto';
+import { ensureParentDir } from './config.js';
+import { runMigrations } from './migrations.js';
+import { artifactExpiry, generateArtifactToken, hashArtifactToken, validateArtifactContent } from './artifacts.js';
+import { palIdentityHandle } from './provider-identity.js';
+import type { AgentDefinition, AgentRun, AgentSession, AgentValidationResult, Artifact, ArtifactMetadata, ChannelAccount, ChannelConversation, ChannelMessageMapping, ChannelOutboxRecord, Chat, ChatKind, Computer, ComputerAgentAssignment, ComputerConnection, DaemonInstance, LarkGroupRoomMapping, LockProviderEvidence, LockTranscriptMessage, Message, MessageDelivery, MessageType, AgentRoomSubscription, AgentRoomSubscriptionMode, PendingInboundEvent, ProvisionedComputer, ProviderExternalType, ProviderIdentityBinding, PalIdentity, RoomChannel, RoomParticipant, RoomParticipantKind, RoomParticipantSource, RoomProvider, RunAction, RunStatus, TranscriptReadModel, WorkbenchArtifact } from './types.js';
+
+export interface CreateMessageInput {
+  chatId?: string;
+  chatName?: string;
+  parentId?: number;
+  sender: string;
+  recipient?: string | null;
+  content: string;
+  type?: MessageType;
+  idempotencyKey?: string | null;
+  channelId?: string | null;
+  provider?: RoomProvider;
+  mentions?: string[];
+}
+
+export interface ListMessagesInput {
+  chatId?: string;
+  chatName?: string;
+  parentId?: number | null;
+  after?: number;
+  limit?: number;
+  q?: string;
+}
+
+export interface StartRunInput {
+  messageId: number;
+  agent: string;
+  cwd: string;
+  attempt: number;
+  pid?: number | null;
+  sessionId?: string | null;
+  triggerMessageId?: number | null;
+  daemonId?: string | null;
+  connectionId?: string | null;
+  computerId?: string | null;
+  runtimeProvider?: string | null;
+  runtimeInvocationId?: string | null;
+  deliveryId?: string | null;
+}
+
+export interface FinishRunInput {
+  status: RunStatus;
+  exitCode?: number | null;
+  output?: string;
+}
+
+export interface RegisterDaemonInput {
+  id?: string;
+  name: string;
+  computerId?: string | null;
+  connectionId?: string | null;
+  host?: string;
+  localUrl?: string;
+  serverUrl?: string;
+  agents?: Array<{ agent: string; cwd?: string; capabilities?: Record<string, unknown> }>;
+}
+
+export interface ComputerAuthInput {
+  computerId: string;
+  connectionId: string;
+  token: string;
+}
+
+export interface ConnectComputerInput {
+  computerId?: string;
+  secret?: string;
+  apiKey?: string;
+  name?: string;
+  host?: string;
+  localUrl?: string;
+  serverUrl?: string;
+  agents?: RegisterDaemonInput['agents'];
+}
+
+export interface ConnectComputerResult {
+  computer: Computer;
+  connection: ComputerConnection;
+  token: string;
+  daemon: DaemonInstance;
+  agents: ComputerAgentAssignment[];
+}
+
+export interface ProvisionComputerInput {
+  name?: string;
+  serverUrl?: string;
+  packageName?: string;
+}
+
+export interface CreateDeliveryInput {
+  messageId: number;
+  agent: string;
+}
+
+export interface ClaimDeliveryInput {
+  daemonId: string;
+  connectionId?: string | null;
+  computerId?: string | null;
+  leaseMs?: number;
+}
+
+export interface FinishDeliveryInput {
+  daemonId: string;
+  connectionId?: string | null;
+  claimToken: string;
+  runId?: string;
+  error?: string;
+}
+
+export interface CreateArtifactInput {
+  title?: string;
+  filename?: string;
+  mimeType: string;
+  content: Uint8Array;
+  ttlSeconds?: number;
+}
+
+export interface RegisterChannelAccountInput {
+  name: string;
+  appId: string;
+  botOpenId?: string | null;
+  agent?: string | null;
+}
+
+export interface ResolveChannelConversationInput {
+  accountId: string;
+  chatName: string;
+  conversationKey: string;
+  externalChatId: string;
+  externalRootId?: string | null;
+  externalThreadId?: string | null;
+  scope: ChannelConversation['scope'];
+  chatType: ChannelConversation['chat_type'];
+  auditOnly?: boolean;
+}
+
+export interface CreateTranscriptInput {
+  conversationId: string;
+  lockMessageId?: number | null;
+  direction: LockTranscriptMessage['direction'];
+  senderType: LockTranscriptMessage['sender_type'];
+  senderId: string;
+  recipientRef?: string | null;
+  content: string;
+  contentType?: string;
+  sourceType: string;
+  sourceUniqueKey: string;
+  mentions?: string[];
+  replyToTranscriptId?: string | null;
+  quoteRootTranscriptId?: string | null;
+  quoteMessageTranscriptId?: string | null;
+  replyToExternalMessageId?: string | null;
+  quoteRootExternalMessageId?: string | null;
+  quoteMessageExternalMessageId?: string | null;
+}
+
+export interface AttachChannelMessageInput {
+  accountId: string;
+  conversationId: string;
+  lockMessageId?: number | null;
+  transcriptMessageId?: string | null;
+  direction: ChannelMessageMapping['direction'];
+  externalMessageId?: string | null;
+  externalChatId: string;
+  externalRootId?: string | null;
+  externalThreadId?: string | null;
+  senderOpenId?: string | null;
+  senderType?: string;
+  rawType?: string;
+  status: ChannelMessageMapping['status'];
+  reasonCode?: string | null;
+  source?: ChannelMessageMapping['source'];
+  admitted?: boolean;
+  rawPayloadRedactedJson?: string;
+}
+
+export interface IngestAuditEnvelopeInput {
+  conversation: Omit<ResolveChannelConversationInput, 'auditOnly'>;
+  envelope: AttachChannelMessageInput;
+}
+
+export interface IngestCanonicalEnvelopeInput {
+  conversation: ResolveChannelConversationInput;
+  transcript: Omit<CreateTranscriptInput, 'conversationId'>;
+  envelope: Omit<AttachChannelMessageInput, 'conversationId' | 'transcriptMessageId'>;
+}
+
+export interface IngestEnvelopeResult {
+  conversation: ChannelConversation;
+  mapping: ChannelMessageMapping;
+  transcript: LockTranscriptMessage | null;
+}
+
+export interface EnqueueChannelOutboxInput {
+  accountId: string;
+  conversationId: string;
+  transcriptMessageId: string;
+  lockMessageId: number;
+  purpose?: string;
+  idempotencyKey: string;
+}
+
+export interface ListChannelMessagesInput {
+  conversationId?: string;
+  transcriptMessageId?: string | null;
+  status?: ChannelMessageMapping['status'];
+  source?: ChannelMessageMapping['source'];
+  admitted?: boolean;
+  limit?: number;
+}
+
+export interface AddProviderEvidenceInput {
+  transcriptMessageId: string;
+  providerMessageId?: string | null;
+  providerEventId?: string | null;
+  attemptId?: string | null;
+  evidenceType: LockProviderEvidence['evidence_type'];
+  receiptState: LockProviderEvidence['receipt_state'];
+  errorCode?: string | null;
+  errorMessage?: string | null;
+  rawPayloadRedactedJson?: string;
+  observedAt?: string | null;
+}
+
+export interface GetOrCreateProviderIdentityInput {
+  provider: Exclude<RoomProvider, 'web'>;
+  providerAccountId: string;
+  externalType: ProviderExternalType;
+  externalId: string;
+  displayName?: string | null;
+}
+
+export interface BindProviderIdentityInput extends GetOrCreateProviderIdentityInput {
+  identityId: string;
+}
+
+export interface UpsertRoomParticipantInput {
+  roomId: string;
+  participantId: string;
+  kind: RoomParticipantKind;
+  displayName?: string | null;
+  source: RoomParticipantSource;
+}
+
+const agentFieldAllowlist = new Set(['id', 'agent_key', 'display_name', 'description', 'runtime', 'created_at', 'updated_at']);
+const forbiddenAgentFieldPattern = /provider|adapter|enabled|disabled|status|state|mode|config|capabilities|route|routing|binding|permission|owner|workspace|daemon|delivery|channel|lark|acl|authz/i;
+
+export type ChannelMessageConflictCode =
+  | 'CHANNEL_MESSAGE_LOCK_BINDING_CONFLICT'
+  | 'CHANNEL_MESSAGE_AUDIT_OUTCOME_CONFLICT'
+  | 'CHANNEL_MESSAGE_ATTRIBUTES_CONFLICT'
+  | 'CHANNEL_MESSAGE_UNIQUE_CONFLICT';
+
+export class ChannelMessageConflictError extends Error {
+  readonly code: ChannelMessageConflictCode;
+  readonly existing: ChannelMessageMapping | null;
+  readonly incoming: Record<string, unknown>;
+  constructor(code: ChannelMessageConflictCode, message: string, existing: ChannelMessageMapping | null, incoming: Record<string, unknown>) {
+    super(message);
+    this.name = 'ChannelMessageConflictError';
+    this.code = code;
+    this.existing = existing;
+    this.incoming = incoming;
+  }
+}
+
+function createChannelMessageConflict(code: ChannelMessageConflictCode, message: string, existing: ChannelMessageMapping | null, incoming: Record<string, unknown>): ChannelMessageConflictError {
+  return new ChannelMessageConflictError(code, message, existing, incoming);
+}
+
+export class TranscriptCrossConversationReferenceError extends Error {
+  readonly code = 'TRANSCRIPT_CROSS_CONVERSATION_REFERENCE' as const;
+  readonly column: 'reply_to_transcript_id' | 'quote_root_transcript_id' | 'quote_message_transcript_id';
+  readonly transcriptId: string | null;
+  readonly referencedTranscriptId: string;
+  readonly expectedConversationId: string;
+  readonly actualConversationId: string;
+  constructor(input: {
+    column: TranscriptCrossConversationReferenceError['column'];
+    transcriptId: string | null;
+    referencedTranscriptId: string;
+    expectedConversationId: string;
+    actualConversationId: string;
+  }) {
+    super(`transcript ${input.column} ${input.referencedTranscriptId} lives in conversation ${input.actualConversationId}, not ${input.expectedConversationId}`);
+    this.name = 'TranscriptCrossConversationReferenceError';
+    this.column = input.column;
+    this.transcriptId = input.transcriptId;
+    this.referencedTranscriptId = input.referencedTranscriptId;
+    this.expectedConversationId = input.expectedConversationId;
+    this.actualConversationId = input.actualConversationId;
+  }
+}
+
+function isUniqueConstraintError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const message = String((error as { message?: unknown }).message ?? '');
+  return message.includes('UNIQUE constraint failed');
+}
+
+function normalizeChatName(name?: string): string {
+  const raw = (name ?? 'general').trim();
+  const stripped = raw.startsWith('#') ? raw.slice(1) : raw;
+  if (!stripped) throw new Error('chat name cannot be empty');
+  return stripped;
+}
+
+function parseCapabilities(value: unknown): { topics: 'native' | 'unsupported' } {
+  if (typeof value !== 'string') return { topics: 'native' };
+  try {
+    const parsed = JSON.parse(value) as { topics?: unknown };
+    return parsed.topics === 'unsupported' ? { topics: 'unsupported' } : { topics: 'native' };
+  } catch {
+    return { topics: 'native' };
+  }
+}
+
+function hashSecret(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function generateConnectionToken(): string {
+  return randomBytes(32).toString('hex');
+}
+
+function rowToAgent(row: Record<string, unknown>): AgentDefinition {
+  return {
+    id: String(row.id),
+    agent_key: String(row.agent_key),
+    display_name: String(row.display_name),
+    description: row.description === null ? null : String(row.description),
+    runtime: row.runtime === null ? null : String(row.runtime),
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToComputerAgentAssignment(row: Record<string, unknown>): ComputerAgentAssignment {
+  return {
+    agent: String(row.agent),
+    display_name: String(row.display_name),
+    runtime: row.runtime === null ? null : String(row.runtime),
+    computer_id: String(row.computer_id),
+    cwd: String(row.cwd ?? ''),
+    status: String(row.status) as ComputerAgentAssignment['status'],
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToMessage(row: Record<string, unknown>): Message {
+  return {
+    id: Number(row.id),
+    chat_id: String(row.chat_id),
+    chat_name: String(row.chat_name),
+    parent_id: row.parent_id === null ? null : Number(row.parent_id),
+    depth: Number(row.depth) as 0 | 1,
+    sender: String(row.sender),
+    recipient: row.recipient === null ? null : String(row.recipient),
+    content: String(row.content),
+    type: String(row.type) as MessageType,
+    created_at: String(row.created_at),
+    idempotency_key: row.idempotency_key === null || row.idempotency_key === undefined ? null : String(row.idempotency_key),
+    channel_id: row.channel_id === null || row.channel_id === undefined ? null : String(row.channel_id),
+    provider: row.provider === null || row.provider === undefined ? undefined : String(row.provider) as RoomProvider,
+    mentions: parseMentionsJson(row.mentions_json),
+  };
+}
+
+function rowToRun(row: Record<string, unknown>): AgentRun {
+  return {
+    id: String(row.id),
+    message_id: Number(row.message_id),
+    agent: String(row.agent),
+    status: String(row.status) as RunStatus,
+    action: row.action === null ? null : String(row.action) as RunAction,
+    attempt: Number(row.attempt),
+    pid: row.pid === null ? null : Number(row.pid),
+    cwd: String(row.cwd),
+    started_at: String(row.started_at),
+    updated_at: String(row.updated_at),
+    ended_at: row.ended_at === null ? null : String(row.ended_at),
+    exit_code: row.exit_code === null ? null : Number(row.exit_code),
+    output: String(row.output ?? ''),
+    session_id: row.session_id === null || row.session_id === undefined ? null : String(row.session_id),
+    trigger_message_id: row.trigger_message_id === null || row.trigger_message_id === undefined ? null : Number(row.trigger_message_id),
+    daemon_id: row.daemon_id === null || row.daemon_id === undefined ? null : String(row.daemon_id),
+    connection_id: row.connection_id === null || row.connection_id === undefined ? null : String(row.connection_id),
+    computer_id: row.computer_id === null || row.computer_id === undefined ? null : String(row.computer_id),
+    runtime_provider: row.runtime_provider === null || row.runtime_provider === undefined ? null : String(row.runtime_provider),
+    runtime_invocation_id: row.runtime_invocation_id === null || row.runtime_invocation_id === undefined ? null : String(row.runtime_invocation_id),
+    delivery_id: row.delivery_id === null || row.delivery_id === undefined ? null : String(row.delivery_id),
+  };
+}
+
+function rowToSession(row: Record<string, unknown>): AgentSession {
+  return {
+    id: String(row.id),
+    chat_id: String(row.chat_id),
+    agent: String(row.agent),
+    daemon_id: String(row.daemon_id),
+    computer_id: row.computer_id === null || row.computer_id === undefined ? null : String(row.computer_id),
+    runtime_provider: row.runtime_provider === null || row.runtime_provider === undefined ? null : String(row.runtime_provider),
+    cwd: String(row.cwd),
+    session_key: String(row.session_key),
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+    last_message_id: row.last_message_id === null ? null : Number(row.last_message_id),
+    runtime_session_id: row.runtime_session_id === null || row.runtime_session_id === undefined ? null : String(row.runtime_session_id),
+  };
+}
+
+function rowToDaemon(row: Record<string, unknown>): DaemonInstance {
+  return {
+    id: String(row.id),
+    name: String(row.name),
+    host: String(row.host),
+    local_url: String(row.local_url),
+    server_url: String(row.server_url),
+    status: String(row.status) as DaemonInstance['status'],
+    created_at: String(row.created_at),
+    last_seen_at: String(row.last_seen_at),
+  };
+}
+
+function rowToComputer(row: Record<string, unknown>): Computer {
+  return {
+    id: String(row.id),
+    name: String(row.name),
+    status: String(row.status) as Computer['status'],
+    active_connection_id: row.active_connection_id === null || row.active_connection_id === undefined ? null : String(row.active_connection_id),
+    last_seen_at: row.last_seen_at === null || row.last_seen_at === undefined ? null : String(row.last_seen_at),
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToComputerConnection(row: Record<string, unknown>): ComputerConnection {
+  return {
+    id: String(row.id),
+    computer_id: String(row.computer_id),
+    epoch: Number(row.epoch),
+    status: String(row.status) as ComputerConnection['status'],
+    connected_at: String(row.connected_at),
+    last_heartbeat_at: String(row.last_heartbeat_at),
+    revoked_at: row.revoked_at === null || row.revoked_at === undefined ? null : String(row.revoked_at),
+  };
+}
+
+function rowToDelivery(row: Record<string, unknown>): MessageDelivery {
+  return {
+    id: String(row.id),
+    message_id: Number(row.message_id),
+    chat_id: String(row.chat_id),
+    agent: String(row.agent),
+    status: String(row.status) as MessageDelivery['status'],
+    daemon_id: row.daemon_id === null ? null : String(row.daemon_id),
+    connection_id: row.connection_id === null || row.connection_id === undefined ? null : String(row.connection_id),
+    claim_token: row.claim_token === null ? null : String(row.claim_token),
+    lease_until: row.lease_until === null ? null : String(row.lease_until),
+    attempts: Number(row.attempts),
+    idempotency_key: String(row.idempotency_key),
+    run_id: row.run_id === null ? null : String(row.run_id),
+    last_error: String(row.last_error ?? ''),
+    created_at: String(row.created_at),
+    claimed_at: row.claimed_at === null ? null : String(row.claimed_at),
+    acked_at: row.acked_at === null ? null : String(row.acked_at),
+    failed_at: row.failed_at === null ? null : String(row.failed_at),
+  };
+}
+
+function rowToArtifact(row: Record<string, unknown>): Artifact {
+  return {
+    id: String(row.id),
+    token_hash: String(row.token_hash),
+    title: String(row.title),
+    filename: String(row.filename),
+    mime_type: String(row.mime_type),
+    size_bytes: Number(row.size_bytes),
+    content: row.content as Uint8Array,
+    created_at: String(row.created_at),
+    expires_at: String(row.expires_at),
+    revoked_at: row.revoked_at === null ? null : String(row.revoked_at),
+  };
+}
+
+function rowToArtifactMetadata(row: Record<string, unknown>): ArtifactMetadata {
+  return {
+    id: String(row.id),
+    title: String(row.title),
+    filename: String(row.filename),
+    mime_type: String(row.mime_type),
+    size_bytes: Number(row.size_bytes),
+    created_at: String(row.created_at),
+    expires_at: String(row.expires_at),
+    revoked_at: row.revoked_at === null ? null : String(row.revoked_at),
+  };
+}
+
+function rowToWorkbenchArtifact(row: Record<string, unknown>): WorkbenchArtifact {
+  return {
+    id: String(row.id),
+    title: String(row.title),
+    filename: String(row.filename),
+    mime_type: String(row.mime_type),
+    size_bytes: Number(row.size_bytes),
+    created_at: String(row.created_at),
+  };
+}
+
+function rowToChannelAccount(row: Record<string, unknown>): ChannelAccount {
+  return {
+    id: String(row.id),
+    channel: 'lark',
+    name: String(row.name),
+    app_id: String(row.app_id),
+    bot_open_id: row.bot_open_id === null ? null : String(row.bot_open_id),
+    agent: row.agent === null || row.agent === undefined ? null : String(row.agent),
+    provider_account_id: row.provider_account_id === null || row.provider_account_id === undefined ? null : String(row.provider_account_id),
+    status: String(row.status) as ChannelAccount['status'],
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToPalIdentity(row: Record<string, unknown>): PalIdentity {
+  return {
+    id: String(row.id),
+    kind: String(row.kind) as PalIdentity['kind'],
+    display_name: row.display_name === null || row.display_name === undefined ? null : String(row.display_name),
+    stable_handle: String(row.stable_handle),
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToProviderIdentityBinding(row: Record<string, unknown>): ProviderIdentityBinding {
+  return {
+    id: String(row.id),
+    provider: String(row.provider) as ProviderIdentityBinding['provider'],
+    provider_account_id: String(row.provider_account_id),
+    external_type: String(row.external_type) as ProviderIdentityBinding['external_type'],
+    external_id: String(row.external_id),
+    identity_id: String(row.identity_id),
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToRoomParticipant(row: Record<string, unknown>): RoomParticipant {
+  return {
+    id: String(row.id),
+    room_id: String(row.room_id),
+    participant_id: String(row.participant_id),
+    kind: String(row.kind) as RoomParticipant['kind'],
+    display_name: row.display_name === null || row.display_name === undefined ? null : String(row.display_name),
+    source: String(row.source) as RoomParticipant['source'],
+    last_seen_at: String(row.last_seen_at),
+    status: row.status === null || row.status === undefined ? 'active' : String(row.status) as RoomParticipant['status'],
+    joined_at: row.joined_at === null || row.joined_at === undefined ? String(row.created_at) : String(row.joined_at),
+    delivery_cursor_message_id: row.delivery_cursor_message_id === null || row.delivery_cursor_message_id === undefined ? null : Number(row.delivery_cursor_message_id),
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function participantSourceRank(source: RoomParticipantSource): number {
+  switch (source) {
+    case 'local_agent':
+      return 4;
+    case 'known_bot':
+      return 3;
+    case 'lark_member_api':
+      return 2;
+    case 'event':
+      return 1;
+  }
+}
+
+
+function rowToAgentRoomSubscription(row: Record<string, unknown>): AgentRoomSubscription {
+  return {
+    id: String(row.id),
+    agent: String(row.agent),
+    room_id: String(row.room_id),
+    channel_id: row.channel_id === null || row.channel_id === undefined ? null : String(row.channel_id),
+    mode: String(row.mode) as AgentRoomSubscriptionMode,
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToRoomChannel(row: Record<string, unknown>): RoomChannel {
+  return {
+    id: String(row.id),
+    room_id: String(row.room_id),
+    kind: 'topic',
+    name: String(row.name),
+    external_ref: row.external_ref === null || row.external_ref === undefined ? null : String(row.external_ref),
+    created_by: row.created_by === null || row.created_by === undefined ? null : String(row.created_by),
+    created_at: String(row.created_at),
+  };
+}
+
+function rowToPendingInboundEvent(row: Record<string, unknown>): PendingInboundEvent {
+  return {
+    id: String(row.id),
+    raw_event_id: String(row.raw_event_id),
+    provider: String(row.provider) as PendingInboundEvent['provider'],
+    provider_account_id: row.provider_account_id === null || row.provider_account_id === undefined ? null : String(row.provider_account_id),
+    reason: String(row.reason),
+    retry_count: Number(row.retry_count),
+    next_retry_at: row.next_retry_at === null || row.next_retry_at === undefined ? null : String(row.next_retry_at),
+    last_error: String(row.last_error ?? ''),
+    status: String(row.status) as PendingInboundEvent['status'],
+    created_at: String(row.created_at),
+    updated_at: String(row.updated_at),
+  };
+}
+
+function rowToChannelConversation(row: Record<string, unknown>): ChannelConversation {
+  return {
+    id: String(row.id),
+    channel_account_id: String(row.channel_account_id),
+    lock_chat_id: String(row.lock_chat_id),
+    conversation_key: String(row.conversation_key),
+    external_chat_id: String(row.external_chat_id),
+    external_root_id: row.external_root_id === null ? null : String(row.external_root_id),
+    external_thread_id: row.external_thread_id === null ? null : String(row.external_thread_id),
+    scope: String(row.scope) as ChannelConversation['scope'],
+    chat_type: String(row.chat_type) as ChannelConversation['chat_type'],
+    audit_only: Number(row.audit_only ?? 0) as ChannelConversation['audit_only'],
+    created_at: String(row.created_at),
+    last_seen_at: String(row.last_seen_at),
+  };
+}
+
+function rowToTranscript(row: Record<string, unknown>): LockTranscriptMessage {
+  return {
+    id: String(row.id),
+    lock_message_id: row.lock_message_id === null ? null : Number(row.lock_message_id),
+    conversation_id: String(row.conversation_id),
+    channel_type: String(row.channel_type) as LockTranscriptMessage['channel_type'],
+    direction: String(row.direction) as LockTranscriptMessage['direction'],
+    sender_type: String(row.sender_type) as LockTranscriptMessage['sender_type'],
+    sender_id: String(row.sender_id),
+    recipient_ref: row.recipient_ref === null ? null : String(row.recipient_ref),
+    content: String(row.content),
+    content_type: String(row.content_type),
+    source_type: String(row.source_type),
+    source_unique_key: String(row.source_unique_key),
+    status: String(row.status) as LockTranscriptMessage['status'],
+    mentions: parseMentionsJson(row.mentions_json),
+    reply_to_transcript_id: row.reply_to_transcript_id === null || row.reply_to_transcript_id === undefined ? null : String(row.reply_to_transcript_id),
+    quote_root_transcript_id: row.quote_root_transcript_id === null || row.quote_root_transcript_id === undefined ? null : String(row.quote_root_transcript_id),
+    quote_message_transcript_id: row.quote_message_transcript_id === null || row.quote_message_transcript_id === undefined ? null : String(row.quote_message_transcript_id),
+    reply_to_external_message_id: row.reply_to_external_message_id === null || row.reply_to_external_message_id === undefined ? null : String(row.reply_to_external_message_id),
+    quote_root_external_message_id: row.quote_root_external_message_id === null || row.quote_root_external_message_id === undefined ? null : String(row.quote_root_external_message_id),
+    quote_message_external_message_id: row.quote_message_external_message_id === null || row.quote_message_external_message_id === undefined ? null : String(row.quote_message_external_message_id),
+    created_at: String(row.created_at),
+    recorded_at: String(row.recorded_at),
+  };
+}
+
+function parseMentionsJson(value: unknown): string[] {
+  if (value === null || value === undefined) return [];
+  if (typeof value !== 'string') return [];
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((entry): entry is string => typeof entry === 'string');
+  } catch {
+    return [];
+  }
+}
+
+function normalizeMentionsInput(value: string[] | undefined): string[] {
+  if (!value || value.length === 0) return [];
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'string') continue;
+    const trimmed = entry.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    result.push(trimmed);
+  }
+  return result;
+}
+
+function rowToTranscriptReadModel(row: Record<string, unknown>): TranscriptReadModel {
+  return {
+    id: String(row.id),
+    conversation_id: String(row.conversation_id),
+    direction: String(row.direction) as TranscriptReadModel['direction'],
+    sender_type: String(row.sender_type) as TranscriptReadModel['sender_type'],
+    sender_id: String(row.sender_id),
+    recipient_ref: row.recipient_ref === null ? null : String(row.recipient_ref),
+    content: String(row.content),
+    content_type: String(row.content_type),
+    status: String(row.status) as TranscriptReadModel['status'],
+    mentions: parseMentionsJson(row.mentions_json),
+    reply_to_transcript_id: row.reply_to_transcript_id === null || row.reply_to_transcript_id === undefined ? null : String(row.reply_to_transcript_id),
+    quote_root_transcript_id: row.quote_root_transcript_id === null || row.quote_root_transcript_id === undefined ? null : String(row.quote_root_transcript_id),
+    quote_message_transcript_id: row.quote_message_transcript_id === null || row.quote_message_transcript_id === undefined ? null : String(row.quote_message_transcript_id),
+    created_at: String(row.created_at),
+    recorded_at: String(row.recorded_at),
+  };
+}
+
+function rowToChannelMessage(row: Record<string, unknown>): ChannelMessageMapping {
+  return {
+    id: String(row.id),
+    channel_account_id: String(row.channel_account_id),
+    channel_conversation_id: String(row.channel_conversation_id),
+    lock_message_id: row.lock_message_id === null ? null : Number(row.lock_message_id),
+    transcript_message_id: row.transcript_message_id === null ? null : String(row.transcript_message_id),
+    direction: String(row.direction) as ChannelMessageMapping['direction'],
+    external_message_id: row.external_message_id === null ? null : String(row.external_message_id),
+    external_chat_id: String(row.external_chat_id),
+    external_root_id: row.external_root_id === null ? null : String(row.external_root_id),
+    external_thread_id: row.external_thread_id === null ? null : String(row.external_thread_id),
+    sender_open_id: row.sender_open_id === null ? null : String(row.sender_open_id),
+    sender_type: String(row.sender_type),
+    raw_type: String(row.raw_type),
+    status: String(row.status) as ChannelMessageMapping['status'],
+    reason_code: row.reason_code === null ? null : String(row.reason_code),
+    source: String(row.source) as ChannelMessageMapping['source'],
+    admitted: Number(row.admitted) as ChannelMessageMapping['admitted'],
+    raw_payload_redacted_json: String(row.raw_payload_redacted_json),
+    created_at: String(row.created_at),
+  };
+}
+
+function rowToChannelOutbox(row: Record<string, unknown>): ChannelOutboxRecord {
+  return {
+    id: String(row.id),
+    channel_account_id: String(row.channel_account_id),
+    channel_conversation_id: String(row.channel_conversation_id),
+    transcript_message_id: String(row.transcript_message_id),
+    lock_message_id: row.lock_message_id === null ? null : Number(row.lock_message_id),
+    purpose: String(row.purpose),
+    idempotency_key: String(row.idempotency_key),
+    created_at: String(row.created_at),
+  };
+}
+
+function rowToProviderEvidence(row: Record<string, unknown>): LockProviderEvidence {
+  return {
+    id: String(row.id),
+    transcript_message_id: String(row.transcript_message_id),
+    provider: 'lark',
+    provider_message_id: row.provider_message_id === null ? null : String(row.provider_message_id),
+    provider_event_id: row.provider_event_id === null ? null : String(row.provider_event_id),
+    attempt_id: row.attempt_id === null ? null : String(row.attempt_id),
+    evidence_type: String(row.evidence_type) as LockProviderEvidence['evidence_type'],
+    receipt_state: String(row.receipt_state) as LockProviderEvidence['receipt_state'],
+    error_code: row.error_code === null ? null : String(row.error_code),
+    error_message: row.error_message === null ? null : String(row.error_message),
+    raw_payload_redacted_json: String(row.raw_payload_redacted_json),
+    observed_at: row.observed_at === null ? null : String(row.observed_at),
+    created_at: String(row.created_at),
+  };
+}
+
+function limitValue(value: number | undefined, fallback: number): number {
+  if (!value || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.trunc(value), 1), 200);
+}
+
+export class MessageStore {
+  readonly db: Database;
+
+  constructor(path: string) {
+    ensureParentDir(path);
+    this.db = new Database(path);
+    this.db.exec('PRAGMA journal_mode = WAL');
+    this.db.exec('PRAGMA foreign_keys = ON');
+    this.db.exec('PRAGMA busy_timeout = 5000');
+    runMigrations(this.db);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  getOrCreateChat(name: string, kind: ChatKind = 'group'): Chat {
+    const chatName = normalizeChatName(name);
+    const existing = this.db.query('SELECT * FROM chat_stats WHERE name = ?').get(chatName) as Chat | null;
+    if (existing) return existing;
+
+    const id = crypto.randomUUID();
+    this.db.query("INSERT INTO chats (id, name, kind, provider, capabilities_json) VALUES (?, ?, ?, 'web', ?)").run(id, chatName, kind, kind === 'dm' ? '{"topics":"unsupported"}' : '{"topics":"native"}');
+    return this.getChatById(id)!;
+  }
+
+  updateRoomDisplayName(roomId: string, displayName: string | null): Chat {
+    const room = this.getChatById(roomId);
+    if (!room) throw new Error(`room ${roomId} was not found`);
+    const trimmed = displayName?.trim() || null;
+    this.db.query('UPDATE chats SET display_name = ? WHERE id = ?').run(trimmed, room.id);
+    return this.getChatById(room.id)!;
+  }
+
+  backfillLarkDmDisplayNames(): number {
+    const result = this.db.query(`
+      UPDATE chats
+      SET display_name = (
+        SELECT 'DM with ' || rp.display_name
+        FROM room_participants rp
+        WHERE rp.room_id = chats.id
+          AND rp.kind = 'bot'
+          AND rp.status = 'active'
+          AND rp.display_name IS NOT NULL
+          AND trim(rp.display_name) != ''
+        ORDER BY datetime(rp.updated_at) DESC, rp.participant_id ASC
+        LIMIT 1
+      )
+      WHERE provider = 'lark'
+        AND kind = 'dm'
+        AND (display_name IS NULL OR trim(display_name) = '' OR display_name LIKE 'lark:%')
+        AND EXISTS (
+          SELECT 1
+          FROM room_participants rp
+          WHERE rp.room_id = chats.id
+            AND rp.kind = 'bot'
+            AND rp.status = 'active'
+            AND rp.display_name IS NOT NULL
+            AND trim(rp.display_name) != ''
+        )
+    `).run();
+    return result.changes;
+  }
+
+  getChatById(id: string): Chat | null {
+    const row = this.db.query('SELECT * FROM chat_stats WHERE id = ?').get(id) as Chat | null;
+    return row ?? null;
+  }
+
+  getChatByName(name: string): Chat | null {
+    const row = this.db.query('SELECT * FROM chat_stats WHERE name = ?').get(normalizeChatName(name)) as Chat | null;
+    return row ?? null;
+  }
+
+  listChats(): Chat[] {
+    return this.db.query('SELECT * FROM chat_stats ORDER BY COALESCE(last_message_at, created_at) DESC').all() as Chat[];
+  }
+
+  listLarkGroupRoomMappings(): LarkGroupRoomMapping[] {
+    const rows = this.db.query(`
+      SELECT DISTINCT
+        ch.id AS room_id,
+        ch.name AS room_name,
+        ch.display_name AS display_name,
+        cc.external_chat_id AS external_chat_id,
+        ca.app_id AS app_id,
+        ca.bot_open_id AS bot_open_id,
+        ca.agent AS agent
+      FROM channel_conversations cc
+      INNER JOIN channel_accounts ca ON ca.id = cc.channel_account_id
+      INNER JOIN chats ch ON ch.id = cc.lock_chat_id
+      WHERE ca.channel = 'lark'
+        AND cc.chat_type = 'group'
+        AND cc.audit_only = 0
+        AND cc.external_chat_id IS NOT NULL
+    `).all() as Record<string, unknown>[];
+    return rows.map((row) => ({
+      room_id: String(row.room_id),
+      room_name: String(row.room_name),
+      display_name: row.display_name === null || row.display_name === undefined ? null : String(row.display_name),
+      external_chat_id: String(row.external_chat_id),
+      app_id: String(row.app_id),
+      bot_open_id: row.bot_open_id === null || row.bot_open_id === undefined ? null : String(row.bot_open_id),
+      agent: row.agent === null || row.agent === undefined ? null : String(row.agent),
+    }));
+  }
+
+  resolveRoom(identifier: string): Chat | null {
+    const raw = identifier.trim();
+    if (!raw) return null;
+    return this.getChatById(raw) ?? this.getChatByName(raw);
+  }
+
+  upsertRoomParticipant(input: UpsertRoomParticipantInput): RoomParticipant {
+    const participantId = input.participantId.trim();
+    if (!participantId) throw new Error('participant_id is required');
+    if (input.source === 'lark_member_api' && input.kind !== 'user') {
+      throw new Error('lark_member_api participants must be kind=user because Feishu filters bots from the member-list API');
+    }
+    const room = this.getChatById(input.roomId);
+    if (!room) throw new Error(`room ${input.roomId} was not found`);
+
+    const existing = this.db
+      .query('SELECT * FROM room_participants WHERE room_id = ? AND participant_id = ?')
+      .get(input.roomId, participantId) as Record<string, unknown> | null;
+    const nextSource = existing && participantSourceRank(existing.source as RoomParticipantSource) > participantSourceRank(input.source)
+      ? existing.source as RoomParticipantSource
+      : input.source;
+    const nextKind = existing && participantSourceRank(existing.source as RoomParticipantSource) > participantSourceRank(input.source)
+      ? existing.kind as RoomParticipantKind
+      : input.kind;
+    const nextName = input.displayName?.trim() || (existing?.display_name === null || existing?.display_name === undefined ? null : String(existing.display_name));
+
+    const id = existing ? String(existing.id) : crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO room_participants (id, room_id, participant_id, kind, display_name, source, last_seen_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'), datetime('now'))
+      ON CONFLICT(room_id, participant_id) DO UPDATE SET
+        kind = excluded.kind,
+        display_name = COALESCE(excluded.display_name, room_participants.display_name),
+        source = excluded.source,
+        status = 'active',
+        last_seen_at = datetime('now'),
+        updated_at = datetime('now')
+    `).run(id, input.roomId, participantId, nextKind, nextName, nextSource);
+
+    return this.getRoomParticipant(input.roomId, participantId)!;
+  }
+
+  getRoomParticipant(roomId: string, participantId: string): RoomParticipant | null {
+    const row = this.db
+      .query('SELECT * FROM room_participants WHERE room_id = ? AND participant_id = ?')
+      .get(roomId, participantId.trim()) as Record<string, unknown> | null;
+    return row ? rowToRoomParticipant(row) : null;
+  }
+
+  listRoomParticipants(roomId: string): RoomParticipant[] {
+    const rows = this.db.query(`
+      SELECT *
+      FROM room_participants
+      WHERE room_id = ? AND status = 'active'
+      ORDER BY
+        CASE kind WHEN 'user' THEN 0 WHEN 'bot' THEN 1 ELSE 2 END,
+        COALESCE(display_name, participant_id) ASC
+    `).all(roomId) as Record<string, unknown>[];
+    return rows.map(rowToRoomParticipant);
+  }
+
+  listMentionableRoomParticipants(roomId: string): RoomParticipant[] {
+    const room = this.getChatById(roomId);
+    if (!room) throw new Error(`room ${roomId} was not found`);
+    const participants = new Map<string, RoomParticipant>();
+    for (const participant of this.listRoomParticipants(room.id)) {
+      participants.set(participant.participant_id, participant);
+    }
+    return [...participants.values()].sort((left, right) => {
+      const leftName = left.display_name ?? left.participant_id;
+      const rightName = right.display_name ?? right.participant_id;
+      return leftName.localeCompare(rightName);
+    });
+  }
+
+  getLatestMessageId(roomId?: string): number {
+    const row = roomId
+      ? this.db.query('SELECT COALESCE(MAX(id), 0) AS id FROM messages WHERE chat_id = ?').get(roomId) as { id: number }
+      : this.db.query('SELECT COALESCE(MAX(id), 0) AS id FROM messages').get() as { id: number };
+    return Number(row.id ?? 0);
+  }
+
+  inviteAgentToRoom(input: { roomId: string; agent: string; mode?: AgentRoomSubscriptionMode }): { participant: RoomParticipant; subscription: AgentRoomSubscription } {
+    const room = this.getChatById(input.roomId);
+    if (!room) throw new Error(`room ${input.roomId} was not found`);
+    const agent = input.agent.trim();
+    if (!agent) throw new Error('agent is required');
+    const participant = this.upsertRoomParticipant({
+      roomId: room.id,
+      participantId: agent,
+      kind: 'agent',
+      displayName: this.getAgent(agent)?.display_name ?? agent,
+      source: 'local_agent',
+    });
+    this.db.query(`
+      UPDATE room_participants
+      SET delivery_cursor_message_id = COALESCE(delivery_cursor_message_id, ?), updated_at = datetime('now')
+      WHERE room_id = ? AND participant_id = ?
+    `).run(this.getLatestMessageId(room.id), room.id, agent);
+    return { participant, subscription: this.upsertAgentRoomSubscription({ agent, roomId: room.id, mode: input.mode ?? 'mentions' }) };
+  }
+
+  upsertAgentRoomSubscription(input: { agent: string; roomId: string; mode: AgentRoomSubscriptionMode; channelId?: string | null }): AgentRoomSubscription {
+    const agent = input.agent.trim();
+    if (!agent) throw new Error('agent is required');
+    const room = this.getChatById(input.roomId);
+    if (!room) throw new Error(`room ${input.roomId} was not found`);
+    const channelId = input.channelId ?? null;
+    const existing = this.db.query(`
+      SELECT * FROM agent_room_subscriptions
+      WHERE agent = ? AND room_id = ? AND channel_id IS ?
+      LIMIT 1
+    `).get(agent, room.id, channelId) as Record<string, unknown> | null;
+    if (existing) {
+      this.db.query(`UPDATE agent_room_subscriptions SET mode = ?, updated_at = datetime('now') WHERE id = ?`).run(input.mode, String(existing.id));
+      return this.getAgentRoomSubscription(agent, room.id)!;
+    }
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO agent_room_subscriptions (id, agent, room_id, channel_id, mode, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    `).run(id, agent, room.id, channelId, input.mode);
+    const row = this.db.query('SELECT * FROM agent_room_subscriptions WHERE id = ?').get(id) as Record<string, unknown>;
+    return rowToAgentRoomSubscription(row);
+  }
+
+  getAgentRoomSubscription(agent: string, roomId: string): AgentRoomSubscription | null {
+    const row = this.db.query(`
+      SELECT * FROM agent_room_subscriptions
+      WHERE agent = ? AND room_id = ? AND channel_id IS NULL
+      LIMIT 1
+    `).get(agent.trim(), roomId) as Record<string, unknown> | null;
+    return row ? rowToAgentRoomSubscription(row) : null;
+  }
+
+  createRoomChannel(input: { roomId: string; name: string; createdBy?: string | null; externalRef?: string | null }): RoomChannel {
+    const room = this.getChatById(input.roomId);
+    if (!room) throw new Error(`room ${input.roomId} was not found`);
+    if (room.kind === 'dm') throw new Error('ROOM_TOPICS_UNSUPPORTED: dm rooms do not support topics');
+    const capabilities = parseCapabilities(room.capabilities_json);
+    if (capabilities.topics !== 'native') throw new Error('ROOM_TOPICS_UNSUPPORTED: this room does not support topics');
+    const name = input.name.trim();
+    if (!name) throw new Error('topic name is required');
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO room_channels (id, room_id, kind, name, external_ref, created_by)
+      VALUES (?, ?, 'topic', ?, ?, ?)
+      ON CONFLICT(room_id, name) DO NOTHING
+    `).run(id, room.id, name, input.externalRef ?? null, input.createdBy ?? null);
+    const row = this.db.query('SELECT * FROM room_channels WHERE room_id = ? AND name = ?').get(room.id, name) as Record<string, unknown>;
+    return rowToRoomChannel(row);
+  }
+
+  listAgents(limit = 50): AgentDefinition[] {
+    const rows = this.db.query(`
+      SELECT id, agent_key, display_name, description, runtime, created_at, updated_at
+      FROM agents
+      ORDER BY agent_key ASC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToAgent);
+  }
+
+  getAgent(identifier: string): AgentDefinition | null {
+    const key = identifier.trim();
+    if (!key) return null;
+    const row = this.db.query(`
+      SELECT id, agent_key, display_name, description, runtime, created_at, updated_at
+      FROM agents
+      WHERE id = ? OR agent_key = ?
+      LIMIT 1
+    `).get(key, key) as Record<string, unknown> | null;
+    return row ? rowToAgent(row) : null;
+  }
+
+  getAgentRuntime(agentKey: string): string | null {
+    const row = this.db.query(`
+      SELECT runtime FROM agents WHERE agent_key = ? LIMIT 1
+    `).get(agentKey.trim()) as { runtime: string | null } | null;
+    return row?.runtime ?? null;
+  }
+
+  upsertAgent(input: { id?: string; agent_key: string; display_name: string; description?: string | null; runtime?: string | null }): AgentDefinition {
+    const id = input.id?.trim() || crypto.randomUUID();
+    const agentKey = input.agent_key.trim();
+    const displayName = input.display_name.trim();
+    if (!agentKey) throw new Error('agent_key is required');
+    if (!displayName) throw new Error('display_name is required');
+
+    this.db.query(`
+      INSERT INTO agents (id, agent_key, display_name, description, runtime, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+      ON CONFLICT(agent_key) DO UPDATE SET
+        display_name = excluded.display_name,
+        description = COALESCE(excluded.description, agents.description),
+        runtime = COALESCE(excluded.runtime, agents.runtime),
+        updated_at = datetime('now')
+    `).run(id, agentKey, displayName, input.description ?? null, input.runtime ?? null);
+
+    return this.getAgent(agentKey)!;
+  }
+
+  updateAgentRuntime(agentKey: string, runtime: string | null): AgentDefinition | null {
+    const key = agentKey.trim();
+    if (!key) throw new Error('agent_key is required');
+    const existing = this.getAgent(key);
+    if (!existing) return null;
+
+    this.db.query(`
+      UPDATE agents SET runtime = ?, updated_at = datetime('now') WHERE agent_key = ?
+    `).run(runtime, key);
+
+    return this.getAgent(key);
+  }
+
+  assignAgentToComputer(input: { agent: string; computerId: string }): ComputerAgentAssignment {
+    const agent = input.agent.trim();
+    const computerId = input.computerId.trim();
+    if (!agent) throw new Error('agent is required');
+    if (!computerId) throw new Error('computer_id is required');
+    if (!this.getAgent(agent)) throw new Error(`agent ${agent} not found`);
+    if (!this.getComputer(computerId)) throw new Error(`computer ${computerId} not found`);
+
+    this.db.query(`
+      INSERT INTO computer_agent_assignments (agent, computer_id, cwd, status, updated_at)
+      VALUES (?, ?, ?, 'active', datetime('now'))
+      ON CONFLICT(agent) DO UPDATE SET
+        computer_id = excluded.computer_id,
+        cwd = excluded.cwd,
+        status = 'active',
+        updated_at = datetime('now')
+    `).run(agent, computerId, '');
+
+    return this.getComputerAgentAssignment(agent)!;
+  }
+
+  getComputerAgentAssignment(agent: string): ComputerAgentAssignment | null {
+    const row = this.db.query(`
+      SELECT caa.*, a.display_name, a.runtime
+      FROM computer_agent_assignments caa
+      JOIN agents a ON a.agent_key = caa.agent
+      WHERE caa.agent = ?
+      LIMIT 1
+    `).get(agent.trim()) as Record<string, unknown> | null;
+    return row ? rowToComputerAgentAssignment(row) : null;
+  }
+
+  listComputerAgentAssignments(computerId: string): ComputerAgentAssignment[] {
+    const rows = this.db.query(`
+      SELECT caa.*, a.display_name, a.runtime
+      FROM computer_agent_assignments caa
+      JOIN agents a ON a.agent_key = caa.agent
+      WHERE caa.computer_id = ? AND caa.status = 'active'
+      ORDER BY caa.agent ASC
+    `).all(computerId.trim()) as Record<string, unknown>[];
+    return rows.map(rowToComputerAgentAssignment);
+  }
+
+  validateAgentSchema(input: Record<string, unknown>): AgentValidationResult {
+    const diagnostics: AgentValidationResult['diagnostics'] = [];
+
+    for (const key of Object.keys(input)) {
+      if (!agentFieldAllowlist.has(key)) {
+        diagnostics.push({
+          level: 'error',
+          code: forbiddenAgentFieldPattern.test(key) ? 'FORBIDDEN_FIELD' : 'UNKNOWN_FIELD',
+          message: `${key} is not an A0 agent field`,
+        });
+      }
+    }
+
+    for (const key of ['agent_key', 'display_name']) {
+      const value = input[key];
+      if (typeof value !== 'string' || value.trim() === '') {
+        diagnostics.push({ level: 'error', code: 'INVALID_FIELD', message: `${key} must be a non-empty string` });
+      }
+    }
+
+    if ('id' in input && (typeof input.id !== 'string' || input.id.trim() === '')) {
+      diagnostics.push({ level: 'error', code: 'INVALID_FIELD', message: 'id must be a non-empty string when provided' });
+    }
+
+    if ('description' in input && input.description !== null && typeof input.description !== 'string') {
+      diagnostics.push({ level: 'error', code: 'INVALID_FIELD', message: 'description must be a string or null' });
+    }
+
+    if ('runtime' in input && input.runtime !== null && typeof input.runtime !== 'string') {
+      diagnostics.push({ level: 'error', code: 'INVALID_FIELD', message: 'runtime must be a string or null' });
+    }
+
+    for (const key of ['created_at', 'updated_at']) {
+      if (key in input && typeof input[key] !== 'string') {
+        diagnostics.push({ level: 'error', code: 'INVALID_FIELD', message: `${key} must be a string when provided` });
+      }
+    }
+
+    return { ok: diagnostics.length === 0, diagnostics };
+  }
+
+  registerChannelAccount(input: RegisterChannelAccountInput): ChannelAccount {
+    const existing = this.db.query('SELECT * FROM channel_accounts WHERE channel = ? AND app_id = ?').get('lark', input.appId) as Record<string, unknown> | null;
+    const agent = input.agent?.trim() || null;
+    if (existing) {
+      let providerAccount: { id: string } | null = null;
+      if (agent) {
+        providerAccount = this.upsertProviderAccount({ provider: 'lark', externalAccountId: input.appId, agent, botExternalUserId: input.botOpenId ?? null });
+      }
+      if ((agent && existing.agent !== agent) || (input.botOpenId && existing.bot_open_id !== input.botOpenId)) {
+        this.db.query(`
+          UPDATE channel_accounts
+          SET agent = COALESCE(?, agent),
+              bot_open_id = COALESCE(?, bot_open_id),
+              provider_account_id = COALESCE(?, provider_account_id),
+              updated_at = datetime('now')
+          WHERE id = ?
+        `).run(agent, input.botOpenId ?? null, providerAccount?.id ?? null, String(existing.id));
+      }
+      return this.getChannelAccount(String(existing.id))!;
+    }
+
+    const id = crypto.randomUUID();
+    const providerAccount = agent ? this.upsertProviderAccount({ provider: 'lark', externalAccountId: input.appId, agent, botExternalUserId: input.botOpenId ?? null }) : null;
+    this.db.query(`
+      INSERT INTO channel_accounts (id, channel, name, app_id, bot_open_id, agent, provider_account_id)
+      VALUES (?, 'lark', ?, ?, ?, ?, ?)
+    `).run(id, input.name, input.appId, input.botOpenId ?? null, agent, providerAccount?.id ?? null);
+    return this.getChannelAccount(id)!;
+  }
+
+  upsertProviderAccount(input: { provider: Exclude<RoomProvider, 'web'>; externalAccountId: string; agent: string; botExternalUserId?: string | null }): { id: string } {
+    const externalAccountId = input.externalAccountId.trim();
+    const agent = input.agent.trim();
+    if (!externalAccountId || !agent) throw new Error('provider account requires externalAccountId and agent');
+    const existing = this.db.query('SELECT id FROM provider_accounts WHERE provider = ? AND external_account_id = ?').get(input.provider, externalAccountId) as { id: string } | null;
+    const id = existing?.id ?? crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO provider_accounts (id, provider, external_account_id, agent, bot_external_user_id, status, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 'active', datetime('now'), datetime('now'))
+      ON CONFLICT(provider, external_account_id) DO UPDATE SET
+        agent = excluded.agent,
+        bot_external_user_id = COALESCE(excluded.bot_external_user_id, provider_accounts.bot_external_user_id),
+        status = 'active',
+        updated_at = datetime('now')
+    `).run(id, input.provider, externalAccountId, agent, input.botExternalUserId ?? null);
+    return { id };
+  }
+
+  getOrCreateProviderIdentity(input: GetOrCreateProviderIdentityInput): { identity: PalIdentity; binding: ProviderIdentityBinding } {
+    const providerAccountId = input.providerAccountId.trim();
+    const externalId = input.externalId.trim();
+    if (!providerAccountId || !externalId) throw new Error('provider identity requires providerAccountId and externalId');
+
+    const existing = this.db.query(`
+      SELECT b.*, i.id AS identity_id, i.kind AS identity_kind, i.display_name AS identity_display_name,
+             i.stable_handle AS identity_stable_handle, i.created_at AS identity_created_at, i.updated_at AS identity_updated_at
+      FROM provider_identity_bindings b
+      INNER JOIN pal_identities i ON i.id = b.identity_id
+      WHERE b.provider = ? AND b.provider_account_id = ? AND b.external_type = ? AND b.external_id = ?
+      LIMIT 1
+    `).get(input.provider, providerAccountId, input.externalType, externalId) as Record<string, unknown> | null;
+    if (existing) {
+      const displayName = input.displayName?.trim() || null;
+      if (displayName) {
+        this.db.query(`
+          UPDATE pal_identities
+          SET display_name = COALESCE(?, display_name), updated_at = datetime('now')
+          WHERE id = ?
+        `).run(displayName, String(existing.identity_id));
+      }
+      return {
+        identity: rowToPalIdentity({
+          id: existing.identity_id,
+          kind: existing.identity_kind,
+          display_name: displayName ?? existing.identity_display_name,
+          stable_handle: existing.identity_stable_handle,
+          created_at: existing.identity_created_at,
+          updated_at: existing.identity_updated_at,
+        }),
+        binding: rowToProviderIdentityBinding(existing),
+      };
+    }
+
+    const identityId = crypto.randomUUID();
+    const bindingId = crypto.randomUUID();
+    const displayName = input.displayName?.trim() || null;
+    const stableHandle = palIdentityHandle(input.externalType, `${input.provider}:${providerAccountId}:${input.externalType}:${externalId}`);
+    this.db.query(`
+      INSERT INTO pal_identities (id, kind, display_name, stable_handle, created_at, updated_at)
+      VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))
+    `).run(identityId, input.externalType, displayName, stableHandle);
+    this.db.query(`
+      INSERT INTO provider_identity_bindings (id, provider, provider_account_id, external_type, external_id, identity_id, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    `).run(bindingId, input.provider, providerAccountId, input.externalType, externalId, identityId);
+
+    return {
+      identity: rowToPalIdentity(this.db.query('SELECT * FROM pal_identities WHERE id = ?').get(identityId) as Record<string, unknown>),
+      binding: rowToProviderIdentityBinding(this.db.query('SELECT * FROM provider_identity_bindings WHERE id = ?').get(bindingId) as Record<string, unknown>),
+    };
+  }
+
+  bindProviderIdentity(input: BindProviderIdentityInput): { identity: PalIdentity; binding: ProviderIdentityBinding } {
+    const providerAccountId = input.providerAccountId.trim();
+    const externalId = input.externalId.trim();
+    const identityId = input.identityId.trim();
+    if (!providerAccountId || !externalId || !identityId) throw new Error('provider identity binding requires providerAccountId, externalId, and identityId');
+    const identity = this.db.query('SELECT * FROM pal_identities WHERE id = ?').get(identityId) as Record<string, unknown> | null;
+    if (!identity) throw new Error(`PAL identity ${identityId} was not found`);
+    const displayName = input.displayName?.trim() || null;
+    if (displayName) {
+      this.db.query(`
+        UPDATE pal_identities
+        SET display_name = COALESCE(?, display_name), updated_at = datetime('now')
+        WHERE id = ?
+      `).run(displayName, identityId);
+    }
+    const bindingId = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO provider_identity_bindings (id, provider, provider_account_id, external_type, external_id, identity_id, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+      ON CONFLICT(provider, provider_account_id, external_type, external_id) DO UPDATE SET
+        identity_id = excluded.identity_id,
+        updated_at = datetime('now')
+    `).run(bindingId, input.provider, providerAccountId, input.externalType, externalId, identityId);
+    const binding = this.db.query(`
+      SELECT * FROM provider_identity_bindings
+      WHERE provider = ? AND provider_account_id = ? AND external_type = ? AND external_id = ?
+    `).get(input.provider, providerAccountId, input.externalType, externalId) as Record<string, unknown>;
+    return {
+      identity: rowToPalIdentity(this.db.query('SELECT * FROM pal_identities WHERE id = ?').get(identityId) as Record<string, unknown>),
+      binding: rowToProviderIdentityBinding(binding),
+    };
+  }
+
+  getCachedProviderUnionId(input: { provider: Exclude<RoomProvider, 'web'>; appId: string; openId: string }): string | null {
+    const row = this.db.query(`
+      SELECT union_id FROM provider_identity_cache
+      WHERE provider = ? AND app_id = ? AND open_id = ?
+        AND (expires_at IS NULL OR expires_at > datetime('now'))
+      LIMIT 1
+    `).get(input.provider, input.appId, input.openId) as { union_id: string } | null;
+    return row?.union_id ?? null;
+  }
+
+  cacheProviderUnionId(input: { provider: Exclude<RoomProvider, 'web'>; appId: string; openId: string; unionId: string; expiresAt?: string | null }): void {
+    const appId = input.appId.trim();
+    const openId = input.openId.trim();
+    const unionId = input.unionId.trim();
+    if (!appId || !openId || !unionId) return;
+    this.db.query(`
+      INSERT INTO provider_identity_cache (id, provider, app_id, open_id, union_id, fetched_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, datetime('now'), ?)
+      ON CONFLICT(provider, app_id, open_id) DO UPDATE SET
+        union_id = excluded.union_id,
+        fetched_at = datetime('now'),
+        expires_at = excluded.expires_at
+    `).run(crypto.randomUUID(), input.provider, appId, openId, unionId, input.expiresAt ?? null);
+  }
+
+  getChannelAccount(id: string): ChannelAccount | null {
+    const row = this.db.query('SELECT * FROM channel_accounts WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToChannelAccount(row) : null;
+  }
+
+  getChannelAccountByAppId(appId: string): ChannelAccount | null {
+    const row = this.db.query('SELECT * FROM channel_accounts WHERE channel = ? AND app_id = ?').get('lark', appId) as Record<string, unknown> | null;
+    return row ? rowToChannelAccount(row) : null;
+  }
+
+  resolveChannelConversation(input: ResolveChannelConversationInput): ChannelConversation {
+    // P1-4(b): pure-read on hit. last_seen_at is only written by ingest paths
+    // (ingestAuditEnvelope / ingestCanonicalEnvelope), never by resolution itself.
+    const existing = this.db.query('SELECT * FROM channel_conversations WHERE conversation_key = ?').get(input.conversationKey) as Record<string, unknown> | null;
+    if (existing) {
+      this.markRoomAsLark(String(existing.lock_chat_id), input.chatType);
+      const account = this.getChannelAccount(input.accountId);
+      if (account?.provider_account_id) {
+        this.getOrCreateProviderIdentity({
+          provider: 'lark',
+          providerAccountId: account.provider_account_id,
+          externalType: 'room',
+          externalId: input.externalChatId,
+          displayName: input.chatName,
+        });
+      }
+      if (input.chatType === 'p2p') this.backfillLarkDmDisplayNames();
+      return this.getChannelConversation(String(existing.id))!;
+    }
+
+    const chat = this.getOrCreateChat(input.chatName, input.chatType === 'p2p' ? 'dm' : 'group');
+    this.markRoomAsLark(chat.id, input.chatType);
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO channel_conversations (id, channel_account_id, lock_chat_id, conversation_key, external_chat_id, external_root_id, external_thread_id, scope, chat_type, audit_only)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.accountId, chat.id, input.conversationKey, input.externalChatId, input.externalRootId ?? null, input.externalThreadId ?? null, input.scope, input.chatType, input.auditOnly ? 1 : 0);
+    const account = this.getChannelAccount(input.accountId);
+    if (account?.provider_account_id) {
+      this.getOrCreateProviderIdentity({
+        provider: 'lark',
+        providerAccountId: account.provider_account_id,
+        externalType: 'room',
+        externalId: input.externalChatId,
+        displayName: input.chatName,
+      });
+      this.db.query(`
+        INSERT INTO provider_conversations (id, provider_account_id, room_id, channel_id, external_room_id, external_channel_id)
+        VALUES (?, ?, ?, NULL, ?, ?)
+        ON CONFLICT(provider_account_id, external_room_id, external_channel_id) DO UPDATE SET last_seen_at = datetime('now')
+      `).run(crypto.randomUUID(), account.provider_account_id, chat.id, input.externalChatId, input.externalThreadId ?? input.externalRootId ?? null);
+    }
+    if (account?.bot_open_id && account.provider_account_id) {
+      const botIdentity = this.getOrCreateProviderIdentity({
+        provider: 'lark',
+        providerAccountId: account.provider_account_id,
+        externalType: 'bot',
+        externalId: account.bot_open_id,
+        displayName: account.name,
+      }).identity;
+      this.upsertRoomParticipant({
+        roomId: chat.id,
+        participantId: botIdentity.stable_handle,
+        kind: 'bot',
+        displayName: account.name,
+        source: 'known_bot',
+      });
+    }
+    if (input.chatType === 'p2p') this.backfillLarkDmDisplayNames();
+    return this.getChannelConversation(id)!;
+  }
+
+  private markRoomAsLark(roomId: string, chatType: 'p2p' | 'group'): void {
+    const kind = chatType === 'p2p' ? 'dm' : 'group';
+    this.db.query(`
+      UPDATE chats
+      SET provider = 'lark', kind = ?, capabilities_json = ?, dm_type = CASE WHEN ? = 'dm' THEN COALESCE(dm_type, 'user_agent') ELSE dm_type END
+      WHERE id = ?
+    `).run(kind, kind === 'dm' ? '{"topics":"unsupported"}' : '{"topics":"native"}', kind, roomId);
+  }
+
+  private bumpChannelConversationLastSeen(conversationId: string): void {
+    this.db.query("UPDATE channel_conversations SET last_seen_at = datetime('now') WHERE id = ?").run(conversationId);
+  }
+
+  getChannelConversation(id: string): ChannelConversation | null {
+    const row = this.db.query('SELECT * FROM channel_conversations WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToChannelConversation(row) : null;
+  }
+
+  /**
+   * Find the Lark channel conversation associated with a lock chat.
+   * Returns null if no Lark channel is linked to this chat.
+   */
+  findLarkChannelForChat(chatId: string, appId?: string): { conversation: ChannelConversation; account: ChannelAccount } | null {
+    const params: SQLQueryBindings[] = [chatId];
+    let appFilter = '';
+    if (appId) {
+      appFilter = 'AND ca.app_id = ?';
+      params.push(appId);
+    }
+    const row = this.db.query(`
+      SELECT cc.*, ca.id as account_id, ca.channel as account_channel, ca.name as account_name, ca.app_id as account_app_id, ca.bot_open_id as account_bot_open_id, ca.agent as account_agent, ca.provider_account_id as account_provider_account_id, ca.status as account_status, ca.created_at as account_created_at, ca.updated_at as account_updated_at
+      FROM channel_conversations cc
+      JOIN channel_accounts ca ON ca.id = cc.channel_account_id
+      WHERE cc.lock_chat_id = ? AND ca.channel = 'lark' AND ca.status = 'active' ${appFilter}
+      LIMIT 1
+    `).get(...params) as Record<string, unknown> | null;
+    if (!row) return null;
+    const accountRow: Record<string, unknown> = {
+      id: row.account_id,
+      channel: row.account_channel,
+      name: row.account_name,
+      app_id: row.account_app_id,
+      bot_open_id: row.account_bot_open_id,
+      agent: row.account_agent,
+      provider_account_id: row.account_provider_account_id,
+      status: row.account_status,
+      created_at: row.account_created_at,
+      updated_at: row.account_updated_at,
+    };
+    return {
+      conversation: rowToChannelConversation(row),
+      account: rowToChannelAccount(accountRow),
+    };
+  }
+
+  createTranscript(input: CreateTranscriptInput): LockTranscriptMessage {
+    const mentions = normalizeMentionsInput(input.mentions);
+    return this.db.transaction(() => {
+      const assertSameConversation = (column: TranscriptCrossConversationReferenceError['column'], referencedId: string | null | undefined, originTranscriptId: string | null): void => {
+        if (!referencedId) return;
+        const row = this.db.query('SELECT conversation_id FROM lock_transcript_messages WHERE id = ?').get(referencedId) as { conversation_id: string } | null;
+        if (!row) return;
+        if (row.conversation_id !== input.conversationId) {
+          throw new TranscriptCrossConversationReferenceError({
+            column,
+            transcriptId: originTranscriptId,
+            referencedTranscriptId: referencedId,
+            expectedConversationId: input.conversationId,
+            actualConversationId: row.conversation_id,
+          });
+        }
+      };
+
+      const existing = this.db.query('SELECT * FROM lock_transcript_messages WHERE source_type = ? AND source_unique_key = ?').get(input.sourceType, input.sourceUniqueKey) as Record<string, unknown> | null;
+      if (existing) {
+        const merged = rowToTranscript(existing);
+        assertSameConversation('reply_to_transcript_id', input.replyToTranscriptId ?? null, merged.id);
+        assertSameConversation('quote_root_transcript_id', input.quoteRootTranscriptId ?? null, merged.id);
+        assertSameConversation('quote_message_transcript_id', input.quoteMessageTranscriptId ?? null, merged.id);
+
+        const updates: string[] = [];
+        const params: SQLQueryBindings[] = [];
+
+        const maybeMerge = (column: string, currentValue: string | null, newValue: string | null | undefined): void => {
+          if (currentValue === null && newValue !== null && newValue !== undefined) {
+            updates.push(`${column} = ?`);
+            params.push(newValue);
+          }
+        };
+        maybeMerge('reply_to_transcript_id', merged.reply_to_transcript_id, input.replyToTranscriptId ?? null);
+        maybeMerge('quote_root_transcript_id', merged.quote_root_transcript_id, input.quoteRootTranscriptId ?? null);
+        maybeMerge('quote_message_transcript_id', merged.quote_message_transcript_id, input.quoteMessageTranscriptId ?? null);
+        maybeMerge('reply_to_external_message_id', merged.reply_to_external_message_id, input.replyToExternalMessageId ?? null);
+        maybeMerge('quote_root_external_message_id', merged.quote_root_external_message_id, input.quoteRootExternalMessageId ?? null);
+        maybeMerge('quote_message_external_message_id', merged.quote_message_external_message_id, input.quoteMessageExternalMessageId ?? null);
+
+        if (updates.length > 0) {
+          params.push(merged.id);
+          this.db.query(`UPDATE lock_transcript_messages SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+          return this.getTranscript(merged.id)!;
+        }
+        return merged;
+      }
+
+      assertSameConversation('reply_to_transcript_id', input.replyToTranscriptId ?? null, null);
+      assertSameConversation('quote_root_transcript_id', input.quoteRootTranscriptId ?? null, null);
+      assertSameConversation('quote_message_transcript_id', input.quoteMessageTranscriptId ?? null, null);
+
+      const id = crypto.randomUUID();
+      const seqRow = this.db.query('SELECT COALESCE(MAX(ingest_seq), 0) + 1 AS next FROM lock_transcript_messages').get() as { next: number };
+      const nextSeq = Number(seqRow.next);
+      this.db.query(`
+        INSERT INTO lock_transcript_messages (id, lock_message_id, conversation_id, channel_type, direction, sender_type, sender_id, recipient_ref, content, content_type, source_type, source_unique_key, mentions_json, reply_to_transcript_id, quote_root_transcript_id, quote_message_transcript_id, reply_to_external_message_id, quote_root_external_message_id, quote_message_external_message_id, ingest_seq)
+        VALUES (?, ?, ?, 'lark', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        id,
+        input.lockMessageId ?? null,
+        input.conversationId,
+        input.direction,
+        input.senderType,
+        input.senderId,
+        input.recipientRef ?? null,
+        input.content,
+        input.contentType ?? 'text',
+        input.sourceType,
+        input.sourceUniqueKey,
+        JSON.stringify(mentions),
+        input.replyToTranscriptId ?? null,
+        input.quoteRootTranscriptId ?? null,
+        input.quoteMessageTranscriptId ?? null,
+        input.replyToExternalMessageId ?? null,
+        input.quoteRootExternalMessageId ?? null,
+        input.quoteMessageExternalMessageId ?? null,
+        nextSeq,
+      );
+      return this.getTranscript(id)!;
+    })();
+  }
+
+  resolvePendingTranscriptRelations(conversationId: string): number {
+    return this.db.transaction(() => {
+      const pendings = this.db.query(`
+        SELECT id, conversation_id, reply_to_transcript_id, quote_root_transcript_id, quote_message_transcript_id,
+               reply_to_external_message_id, quote_root_external_message_id, quote_message_external_message_id
+        FROM lock_transcript_messages
+        WHERE conversation_id = ?
+          AND (
+            (reply_to_transcript_id IS NULL AND reply_to_external_message_id IS NOT NULL)
+            OR (quote_root_transcript_id IS NULL AND quote_root_external_message_id IS NOT NULL)
+            OR (quote_message_transcript_id IS NULL AND quote_message_external_message_id IS NOT NULL)
+          )
+      `).all(conversationId) as Array<Record<string, unknown>>;
+      let updated = 0;
+      for (const row of pendings) {
+        const updates: string[] = [];
+        const params: SQLQueryBindings[] = [];
+        const resolveOne = (transcriptColumn: string, transcriptCurrent: unknown, externalValue: unknown): void => {
+          if (transcriptCurrent !== null && transcriptCurrent !== undefined) return;
+          if (externalValue === null || externalValue === undefined) return;
+          const parent = this.db.query(`
+            SELECT t.id FROM lock_transcript_messages t
+            INNER JOIN channel_messages cm ON cm.transcript_message_id = t.id
+            WHERE t.conversation_id = ?
+              AND cm.channel_conversation_id = ?
+              AND cm.external_message_id = ?
+            ORDER BY t.ingest_seq ASC
+            LIMIT 1
+          `).get(conversationId, conversationId, String(externalValue)) as { id: string } | null;
+          if (!parent) return;
+          updates.push(`${transcriptColumn} = ?`);
+          params.push(parent.id);
+        };
+        resolveOne('reply_to_transcript_id', row.reply_to_transcript_id, row.reply_to_external_message_id);
+        resolveOne('quote_root_transcript_id', row.quote_root_transcript_id, row.quote_root_external_message_id);
+        resolveOne('quote_message_transcript_id', row.quote_message_transcript_id, row.quote_message_external_message_id);
+        if (updates.length > 0) {
+          params.push(String(row.id));
+          this.db.query(`UPDATE lock_transcript_messages SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+          updated += 1;
+        }
+      }
+      return updated;
+    })();
+  }
+
+  getTranscript(id: string): LockTranscriptMessage | null {
+    const row = this.db.query('SELECT * FROM lock_transcript_messages WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToTranscript(row) : null;
+  }
+
+  listTranscripts(conversationId: string, limit = 50): LockTranscriptMessage[] {
+    const rows = this.db.query(`
+      SELECT * FROM lock_transcript_messages
+      WHERE conversation_id = ?
+      ORDER BY ingest_seq ASC
+      LIMIT ?
+    `).all(conversationId, limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToTranscript);
+  }
+
+  listTranscriptMessagesReadOnly(conversationId: string, limit = 50): TranscriptReadModel[] {
+    const rows = this.db.query(`
+      SELECT id, conversation_id, direction, sender_type, sender_id, recipient_ref, content, content_type, status, mentions_json, reply_to_transcript_id, quote_root_transcript_id, quote_message_transcript_id, created_at, recorded_at
+      FROM lock_transcript_messages
+      WHERE conversation_id = ?
+      ORDER BY ingest_seq ASC
+      LIMIT ?
+    `).all(conversationId, limitValue(limit, 50)) as Array<Record<string, unknown>>;
+    return rows.map(rowToTranscriptReadModel);
+  }
+
+  attachChannelMessage(input: AttachChannelMessageInput): ChannelMessageMapping {
+    try {
+      return this.attachChannelMessageInner(input);
+    } catch (error) {
+      if (error instanceof ChannelMessageConflictError) throw error;
+      if (isUniqueConstraintError(error)) {
+        throw createChannelMessageConflict('CHANNEL_MESSAGE_UNIQUE_CONFLICT', `channel message unique constraint conflict (${String((error as { message?: unknown }).message ?? '')})`, null, { input_external_message_id: input.externalMessageId ?? null, input_lock_message_id: input.lockMessageId ?? null });
+      }
+      throw error;
+    }
+  }
+
+  private attachChannelMessageInner(input: AttachChannelMessageInput): ChannelMessageMapping {
+    return this.db.transaction(() => {
+      const conflictFields = {
+        transcript_message_id: input.transcriptMessageId ?? null,
+        lock_message_id: input.lockMessageId ?? null,
+        status: input.status,
+        reason_code: input.reasonCode ?? null,
+        external_root_id: input.externalRootId ?? null,
+        external_thread_id: input.externalThreadId ?? null,
+        sender_open_id: input.senderOpenId ?? null,
+        raw_type: input.rawType ?? 'text',
+        admitted: input.admitted ? 1 : 0,
+        direction: input.direction,
+        external_chat_id: input.externalChatId,
+        source: input.source ?? 'local_fixture',
+      } as const;
+
+      const checkExisting = (mapping: ChannelMessageMapping): ChannelMessageMapping => {
+        // P1-5 priority lock: AUDIT_OUTCOME > ATTRIBUTES > LOCK_BINDING.
+        if (
+          mapping.admitted !== conflictFields.admitted ||
+          mapping.direction !== conflictFields.direction
+        ) {
+          throw createChannelMessageConflict('CHANNEL_MESSAGE_AUDIT_OUTCOME_CONFLICT', 'channel message is already mapped with a different audit outcome', mapping, conflictFields);
+        }
+        if (
+          mapping.external_root_id !== conflictFields.external_root_id ||
+          mapping.external_thread_id !== conflictFields.external_thread_id ||
+          mapping.sender_open_id !== conflictFields.sender_open_id ||
+          mapping.raw_type !== conflictFields.raw_type ||
+          mapping.external_chat_id !== conflictFields.external_chat_id ||
+          mapping.source !== conflictFields.source
+        ) {
+          throw createChannelMessageConflict('CHANNEL_MESSAGE_ATTRIBUTES_CONFLICT', 'channel message is already mapped with different envelope attributes', mapping, conflictFields);
+        }
+        if (
+          mapping.transcript_message_id !== conflictFields.transcript_message_id ||
+          mapping.lock_message_id !== conflictFields.lock_message_id ||
+          mapping.status !== conflictFields.status ||
+          mapping.reason_code !== conflictFields.reason_code
+        ) {
+          throw createChannelMessageConflict('CHANNEL_MESSAGE_LOCK_BINDING_CONFLICT', 'channel message is already mapped to a different Lock binding or audit state', mapping, conflictFields);
+        }
+        return mapping;
+      };
+
+      const reReadByExternalMessageId = (): ChannelMessageMapping | null => {
+        if (!input.externalMessageId) return null;
+        const row = this.db.query(`
+          SELECT * FROM channel_messages
+          WHERE channel_account_id = ? AND external_message_id = ?
+        `).get(input.accountId, input.externalMessageId) as Record<string, unknown> | null;
+        return row ? rowToChannelMessage(row) : null;
+      };
+
+      const reReadByLockBinding = (): ChannelMessageMapping | null => {
+        if (input.lockMessageId === null || input.lockMessageId === undefined) return null;
+        const row = this.db.query(`
+          SELECT * FROM channel_messages
+          WHERE channel_account_id = ?
+            AND channel_conversation_id = ?
+            AND direction = ?
+            AND lock_message_id = ?
+        `).get(input.accountId, input.conversationId, input.direction, input.lockMessageId) as Record<string, unknown> | null;
+        return row ? rowToChannelMessage(row) : null;
+      };
+
+      const existingByExternal = reReadByExternalMessageId();
+      if (existingByExternal) return checkExisting(existingByExternal);
+      const existingByLock = reReadByLockBinding();
+      if (existingByLock) {
+        // The lock-binding UNIQUE index would forbid inserting a new row with a different
+        // external_message_id under the same (account, conversation, direction, lock_message_id).
+        // Surface that as a structured lock-binding conflict rather than silently returning the
+        // existing row, since checkExisting no longer compares external_message_id.
+        if (existingByLock.external_message_id !== (input.externalMessageId ?? null)) {
+          throw createChannelMessageConflict('CHANNEL_MESSAGE_LOCK_BINDING_CONFLICT', 'channel message lock binding already mapped to a different external message id', existingByLock, conflictFields);
+        }
+        return checkExisting(existingByLock);
+      }
+
+      const id = crypto.randomUUID();
+      try {
+        this.db.query(`
+          INSERT INTO channel_messages (id, channel_account_id, channel_conversation_id, lock_message_id, transcript_message_id, direction, external_message_id, external_chat_id, external_root_id, external_thread_id, sender_open_id, sender_type, raw_type, status, reason_code, source, admitted, raw_payload_redacted_json)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          id,
+          input.accountId,
+          input.conversationId,
+          input.lockMessageId ?? null,
+          input.transcriptMessageId ?? null,
+          input.direction,
+          input.externalMessageId ?? null,
+          input.externalChatId,
+          input.externalRootId ?? null,
+          input.externalThreadId ?? null,
+          input.senderOpenId ?? null,
+          input.senderType ?? 'unknown',
+          input.rawType ?? 'text',
+          input.status,
+          input.reasonCode ?? null,
+          input.source ?? 'local_fixture',
+          input.admitted ? 1 : 0,
+          input.rawPayloadRedactedJson ?? '{}',
+        );
+      } catch (error) {
+        if (isUniqueConstraintError(error)) {
+          const message = String((error as { message?: unknown }).message ?? '');
+          if (message.includes('idx_channel_messages_external_id') || (input.externalMessageId && message.includes('external_message_id'))) {
+            const raced = reReadByExternalMessageId();
+            if (raced) return checkExisting(raced);
+          }
+          if (message.includes('idx_channel_messages_lock_message') || message.includes('lock_message_id')) {
+            const raced = reReadByLockBinding();
+            if (raced) throw createChannelMessageConflict('CHANNEL_MESSAGE_LOCK_BINDING_CONFLICT', 'channel message lock binding unique index conflict', raced, conflictFields);
+          }
+          const fallbackExternal = reReadByExternalMessageId();
+          if (fallbackExternal) return checkExisting(fallbackExternal);
+          const fallbackLock = reReadByLockBinding();
+          if (fallbackLock) throw createChannelMessageConflict('CHANNEL_MESSAGE_LOCK_BINDING_CONFLICT', 'channel message lock binding unique index conflict', fallbackLock, conflictFields);
+          throw createChannelMessageConflict('CHANNEL_MESSAGE_UNIQUE_CONFLICT', `channel message unique constraint conflict (${message})`, null, conflictFields);
+        }
+        throw error;
+      }
+      return this.getChannelMessage(id)!;
+    })();
+  }
+
+  getChannelMessage(id: string): ChannelMessageMapping | null {
+    const row = this.db.query('SELECT * FROM channel_messages WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToChannelMessage(row) : null;
+  }
+
+  ingestAuditEnvelope(input: IngestAuditEnvelopeInput): IngestEnvelopeResult {
+    return this.db.transaction(() => {
+      const conversation = this.resolveChannelConversation({ ...input.conversation, auditOnly: true });
+      const mapping = this.attachChannelMessage({ ...input.envelope, conversationId: conversation.id, transcriptMessageId: null });
+      this.bumpChannelConversationLastSeen(conversation.id);
+      return { conversation: this.getChannelConversation(conversation.id)!, mapping, transcript: null };
+    })();
+  }
+
+  ingestCanonicalEnvelope(input: IngestCanonicalEnvelopeInput): IngestEnvelopeResult {
+    return this.db.transaction(() => {
+      const conversation = this.resolveChannelConversation({ ...input.conversation, auditOnly: false });
+      const transcript = this.createTranscript({ ...input.transcript, conversationId: conversation.id });
+      const mapping = this.attachChannelMessage({ ...input.envelope, conversationId: conversation.id, transcriptMessageId: transcript.id });
+      this.bumpChannelConversationLastSeen(conversation.id);
+      return { conversation: this.getChannelConversation(conversation.id)!, mapping, transcript };
+    })();
+  }
+
+  listChannelMessagesForTranscript(transcriptMessageId: string): ChannelMessageMapping[] {
+    return this.listChannelMessages({ transcriptMessageId });
+  }
+
+  listChannelMessages(input: ListChannelMessagesInput = {}): ChannelMessageMapping[] {
+    if (input.limit !== undefined && input.limit <= 0) return [];
+    const conditions: string[] = [];
+    const params: SQLQueryBindings[] = [];
+
+    if (input.conversationId !== undefined) {
+      conditions.push('channel_conversation_id = ?');
+      params.push(input.conversationId);
+    }
+    if (input.transcriptMessageId !== undefined) {
+      if (input.transcriptMessageId === null) {
+        conditions.push('transcript_message_id IS NULL');
+      } else {
+        conditions.push('transcript_message_id = ?');
+        params.push(input.transcriptMessageId);
+      }
+    }
+    if (input.status !== undefined) {
+      conditions.push('status = ?');
+      params.push(input.status);
+    }
+    if (input.source !== undefined) {
+      conditions.push('source = ?');
+      params.push(input.source);
+    }
+    if (input.admitted !== undefined) {
+      conditions.push('admitted = ?');
+      params.push(input.admitted ? 1 : 0);
+    }
+
+    const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+    const rows = this.db.query(`
+      SELECT * FROM channel_messages
+      ${where}
+      ORDER BY datetime(created_at) ASC, id ASC
+      LIMIT ?
+    `).all(...params, limitValue(input.limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToChannelMessage);
+  }
+
+  enqueueChannelOutbox(input: EnqueueChannelOutboxInput): ChannelOutboxRecord {
+    const purpose = input.purpose?.trim() || 'reply';
+    if (!this.getMessage(input.lockMessageId)) throw new Error(`lock message ${input.lockMessageId} was not found`);
+
+    const existing = this.db.query('SELECT * FROM channel_outbox WHERE idempotency_key = ?').get(input.idempotencyKey) as Record<string, unknown> | null;
+    if (existing) {
+      const outbox = rowToChannelOutbox(existing);
+      if (
+        outbox.channel_account_id !== input.accountId ||
+        outbox.channel_conversation_id !== input.conversationId ||
+        outbox.transcript_message_id !== input.transcriptMessageId ||
+        outbox.lock_message_id !== input.lockMessageId ||
+        outbox.purpose !== purpose
+      ) {
+        throw new Error('channel outbox idempotency key conflicts with a different semantic payload');
+      }
+      return outbox;
+    }
+
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO channel_outbox (id, channel_account_id, channel_conversation_id, transcript_message_id, lock_message_id, purpose, idempotency_key)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.accountId, input.conversationId, input.transcriptMessageId, input.lockMessageId, purpose, input.idempotencyKey);
+    return this.getChannelOutbox(id)!;
+  }
+
+  getChannelOutbox(id: string): ChannelOutboxRecord | null {
+    const row = this.db.query('SELECT * FROM channel_outbox WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToChannelOutbox(row) : null;
+  }
+
+  getChannelOutboxByIdempotencyKey(idempotencyKey: string): ChannelOutboxRecord | null {
+    const row = this.db.query('SELECT * FROM channel_outbox WHERE idempotency_key = ?').get(idempotencyKey) as Record<string, unknown> | null;
+    return row ? rowToChannelOutbox(row) : null;
+  }
+
+  addProviderEvidence(input: AddProviderEvidenceInput): LockProviderEvidence {
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO lock_provider_evidence (id, transcript_message_id, provider_message_id, provider_event_id, attempt_id, evidence_type, receipt_state, error_code, error_message, raw_payload_redacted_json, observed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id,
+      input.transcriptMessageId,
+      input.providerMessageId ?? null,
+      input.providerEventId ?? null,
+      input.attemptId ?? null,
+      input.evidenceType,
+      input.receiptState,
+      input.errorCode ?? null,
+      input.errorMessage ?? null,
+      input.rawPayloadRedactedJson ?? '{}',
+      input.observedAt ?? null,
+    );
+    return this.getProviderEvidence(id)!;
+  }
+
+  getProviderEvidence(id: string): LockProviderEvidence | null {
+    const row = this.db.query('SELECT * FROM lock_provider_evidence WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToProviderEvidence(row) : null;
+  }
+
+  listProviderEvidence(transcriptMessageId: string): LockProviderEvidence[] {
+    const rows = this.db.query('SELECT * FROM lock_provider_evidence WHERE transcript_message_id = ? ORDER BY datetime(created_at) ASC').all(transcriptMessageId) as Record<string, unknown>[];
+    return rows.map(rowToProviderEvidence);
+  }
+
+  findChannelConversationByExternal(input: { accountId: string; externalChatId: string; externalThreadId?: string | null }): ChannelConversation | null {
+    const conditions: string[] = ['channel_account_id = ?', 'external_chat_id = ?', 'audit_only = 0'];
+    const params: SQLQueryBindings[] = [input.accountId, input.externalChatId];
+    if (input.externalThreadId === undefined) {
+      // no constraint on thread id
+    } else if (input.externalThreadId === null) {
+      conditions.push('external_thread_id IS NULL');
+    } else {
+      conditions.push('external_thread_id = ?');
+      params.push(input.externalThreadId);
+    }
+
+    const row = this.db.query(`
+      SELECT * FROM channel_conversations
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY datetime(last_seen_at) DESC, id ASC
+      LIMIT 1
+    `).get(...params) as Record<string, unknown> | null;
+    return row ? rowToChannelConversation(row) : null;
+  }
+
+  findTranscriptByExternalMessage(input: { accountId: string; externalChatId: string; externalMessageId: string }): LockTranscriptMessage | null {
+    const row = this.db.query(`
+      SELECT t.* FROM lock_transcript_messages t
+      INNER JOIN channel_messages cm ON cm.transcript_message_id = t.id
+      WHERE cm.channel_account_id = ?
+        AND cm.external_chat_id = ?
+        AND cm.external_message_id = ?
+      ORDER BY t.ingest_seq ASC
+      LIMIT 1
+    `).get(input.accountId, input.externalChatId, input.externalMessageId) as Record<string, unknown> | null;
+    return row ? rowToTranscript(row) : null;
+  }
+
+  listTranscriptsByExternalThread(input: { accountId: string; externalChatId: string; externalThreadId: string; limit?: number }): LockTranscriptMessage[] {
+    const rows = this.db.query(`
+      SELECT t.* FROM lock_transcript_messages t
+      INNER JOIN channel_conversations c ON c.id = t.conversation_id
+      WHERE c.channel_account_id = ?
+        AND c.external_chat_id = ?
+        AND c.external_thread_id = ?
+      ORDER BY t.ingest_seq ASC
+      LIMIT ?
+    `).all(input.accountId, input.externalChatId, input.externalThreadId, limitValue(input.limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToTranscript);
+  }
+
+  listTranscriptsByExternalRoot(input: { accountId: string; externalChatId: string; externalRootId: string; limit?: number }): LockTranscriptMessage[] {
+    const rows = this.db.query(`
+      SELECT t.* FROM lock_transcript_messages t
+      INNER JOIN channel_conversations c ON c.id = t.conversation_id
+      WHERE c.channel_account_id = ?
+        AND c.external_chat_id = ?
+        AND c.external_root_id = ?
+      ORDER BY t.ingest_seq ASC
+      LIMIT ?
+    `).all(input.accountId, input.externalChatId, input.externalRootId, limitValue(input.limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToTranscript);
+  }
+
+  bindTranscriptToLockMessage(transcriptId: string, lockMessageId: number): LockTranscriptMessage {
+    const transcript = this.getTranscript(transcriptId);
+    if (!transcript) throw new Error(`transcript ${transcriptId} was not found`);
+    const message = this.getMessage(lockMessageId);
+    if (!message) throw new Error(`lock message ${lockMessageId} was not found`);
+
+    if (transcript.lock_message_id !== null) {
+      if (transcript.lock_message_id !== lockMessageId) {
+        throw new Error(`transcript ${transcriptId} is already bound to lock message ${transcript.lock_message_id}`);
+      }
+      return transcript;
+    }
+
+    this.db.query('UPDATE lock_transcript_messages SET lock_message_id = ? WHERE id = ?').run(lockMessageId, transcriptId);
+    return this.getTranscript(transcriptId)!;
+  }
+
+  createMessage(input: CreateMessageInput): Message {
+    const sender = input.sender.trim();
+    const content = input.content.trim();
+    if (!sender) throw new Error('sender is required');
+    if (!content) throw new Error('content is required');
+
+    let chat: Chat | null = null;
+    let parentId: number | null = null;
+    let depth: 0 | 1 = 0;
+
+    if (input.parentId !== undefined) {
+      const parent = this.getMessage(input.parentId);
+      if (!parent) throw new Error(`parent message ${input.parentId} was not found`);
+      if (parent.parent_id !== null || parent.depth !== 0) {
+        throw new Error('topics cannot derive another topic');
+      }
+      chat = this.getChatById(parent.chat_id);
+      if (!chat) throw new Error(`chat ${parent.chat_id} was not found`);
+      parentId = parent.id;
+      depth = 1;
+    } else if (input.chatId) {
+      chat = this.getChatById(input.chatId);
+      if (!chat) throw new Error(`chat ${input.chatId} was not found`);
+    } else {
+      chat = this.getOrCreateChat(input.chatName ?? 'general');
+    }
+
+    const idempotencyKey = input.idempotencyKey?.trim() || null;
+    if (idempotencyKey) {
+      const existing = this.db.query(`
+        SELECT m.*, c.name AS chat_name
+        FROM messages m
+        JOIN chats c ON c.id = m.chat_id
+        WHERE m.idempotency_key = ?
+      `).get(idempotencyKey) as Record<string, unknown> | null;
+      if (existing) return rowToMessage(existing);
+    }
+
+    const mentions = normalizeMentionsInput(input.mentions);
+    const channelId = input.channelId?.trim() || null;
+    if (channelId) {
+      const channel = this.db.query('SELECT room_id FROM room_channels WHERE id = ?').get(channelId) as { room_id: string } | null;
+      if (!channel) throw new Error(`channel ${channelId} was not found`);
+      if (channel.room_id !== chat.id) throw new Error(`channel ${channelId} does not belong to room ${chat.id}`);
+    }
+    const provider = input.provider ?? chat.provider ?? 'web';
+    const result = this.db.query(`
+      INSERT INTO messages (chat_id, parent_id, depth, sender, recipient, content, type, idempotency_key, channel_id, provider, mentions_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      chat.id,
+      parentId,
+      depth,
+      sender,
+      input.recipient?.trim() || null,
+      content,
+      input.type ?? 'message',
+      idempotencyKey,
+      channelId,
+      provider,
+      JSON.stringify(mentions),
+    );
+
+    const id = Number(result.lastInsertRowid);
+    return this.getMessage(id)!;
+  }
+
+  getMessage(id: number): Message | null {
+    const row = this.db.query(`
+      SELECT m.*, c.name AS chat_name
+      FROM messages m
+      JOIN chats c ON c.id = m.chat_id
+      WHERE m.id = ?
+    `).get(id) as Record<string, unknown> | null;
+    return row ? rowToMessage(row) : null;
+  }
+
+  listMessages(input: ListMessagesInput = {}): Message[] {
+    const conditions: string[] = [];
+    const params: SQLQueryBindings[] = [];
+
+    if (input.chatId) {
+      conditions.push('m.chat_id = ?');
+      params.push(input.chatId);
+    } else if (input.chatName) {
+      conditions.push('c.name = ?');
+      params.push(normalizeChatName(input.chatName));
+    }
+
+    if (input.parentId !== undefined) {
+      if (input.parentId === null) {
+        conditions.push('m.parent_id IS NULL');
+      } else {
+        conditions.push('(m.id = ? OR m.parent_id = ?)');
+        params.push(input.parentId, input.parentId);
+      }
+    }
+
+    if (input.after !== undefined) {
+      conditions.push('m.id > ?');
+      params.push(input.after);
+    }
+
+    if (input.q) {
+      conditions.push('m.content LIKE ?');
+      params.push(`%${input.q}%`);
+    }
+
+    const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+    const rows = this.db.query(`
+      SELECT m.*, c.name AS chat_name
+      FROM messages m
+      JOIN chats c ON c.id = m.chat_id
+      ${where}
+      ORDER BY m.id ASC
+      LIMIT ?
+    `).all(...params, limitValue(input.limit, 50)) as Record<string, unknown>[];
+
+    return rows.map(rowToMessage);
+  }
+
+  listInbox(agent: string, after = 0, limit = 50): Message[] {
+    const rows = this.db.query(`
+      SELECT m.*, c.name AS chat_name
+      FROM messages m
+      JOIN chats c ON c.id = m.chat_id
+      WHERE m.id > ?
+        AND m.sender != ?
+        AND (m.recipient IS NULL OR m.recipient = ?)
+      ORDER BY m.id ASC
+      LIMIT ?
+    `).all(after, agent, agent, limitValue(limit, 50)) as Record<string, unknown>[];
+
+    return rows.map(rowToMessage);
+  }
+
+  getComputer(id: string): Computer | null {
+    const row = this.db.query('SELECT * FROM computers WHERE id = ?').get(id.trim()) as Record<string, unknown> | null;
+    return row ? rowToComputer(row) : null;
+  }
+
+  listComputers(limit = 50): Computer[] {
+    const rows = this.db.query(`
+      SELECT * FROM computers
+      ORDER BY datetime(updated_at) DESC, datetime(created_at) DESC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToComputer);
+  }
+
+  private getComputerByCredential(secret: string): Computer | null {
+    const row = this.db.query('SELECT * FROM computers WHERE credential_hash = ? ORDER BY created_at DESC LIMIT 1').get(hashSecret(secret.trim())) as Record<string, unknown> | null;
+    return row ? rowToComputer(row) : null;
+  }
+
+  getComputerConnection(id: string): ComputerConnection | null {
+    const row = this.db.query('SELECT * FROM computer_connections WHERE id = ?').get(id.trim()) as Record<string, unknown> | null;
+    return row ? rowToComputerConnection(row) : null;
+  }
+
+  provisionComputer(input: ProvisionComputerInput = {}): ProvisionedComputer {
+    const id = `machine_${randomBytes(8).toString('hex')}`;
+    const apiKey = `sk_machine_${randomBytes(32).toString('hex')}`;
+    const name = input.name?.trim() || id;
+    this.db.query(`
+      INSERT INTO computers (id, name, credential_hash, status, active_connection_id, last_seen_at, updated_at)
+      VALUES (?, ?, ?, 'offline', NULL, NULL, datetime('now'))
+    `).run(id, name, hashSecret(apiKey));
+
+    const packageName = input.packageName?.trim() || '@slock-ai/daemon@latest';
+    const serverUrl = input.serverUrl?.trim() || 'http://127.0.0.1:4127';
+    const command = `npx ${packageName} --server-url ${serverUrl} --api-key ${apiKey} # ${name}`;
+    return { computer: this.getComputer(id)!, api_key: apiKey, command };
+  }
+
+  connectComputer(input: ConnectComputerInput): ConnectComputerResult {
+    const apiKey = input.apiKey?.trim();
+    const provisionedComputer = apiKey ? this.getComputerByCredential(apiKey) : null;
+    const computerId = (provisionedComputer?.id ?? input.computerId ?? '').trim();
+    const secret = (apiKey ?? input.secret ?? '').trim();
+    if (!computerId) throw new Error('computer_id is required');
+    if (!secret) throw new Error('computer secret is required');
+    const credentialHash = hashSecret(secret);
+    const existing = this.db.query('SELECT credential_hash FROM computers WHERE id = ?').get(computerId) as { credential_hash: string } | null;
+    if (existing && existing.credential_hash !== credentialHash) {
+      throw new Error('invalid computer credential');
+    }
+
+    const connectionId = crypto.randomUUID();
+    const token = generateConnectionToken();
+    const tokenHash = hashSecret(token);
+    const revokedRows = this.db.query(`
+      SELECT id FROM computer_connections
+      WHERE computer_id = ? AND status = 'active'
+    `).all(computerId) as Array<{ id: string }>;
+    const revokedConnectionIds = revokedRows.map((row) => row.id);
+    const epochRow = this.db.query('SELECT COALESCE(MAX(epoch), 0) + 1 AS epoch FROM computer_connections WHERE computer_id = ?').get(computerId) as { epoch: number };
+    const epoch = Number(epochRow.epoch);
+    const name = input.name?.trim() || computerId;
+
+    this.db.transaction(() => {
+      if (!existing) {
+        this.db.query(`
+          INSERT INTO computers (id, name, credential_hash, status, active_connection_id, last_seen_at, updated_at)
+          VALUES (?, ?, ?, 'online', ?, datetime('now'), datetime('now'))
+        `).run(computerId, name, credentialHash, connectionId);
+      } else {
+        this.db.query(`
+          UPDATE computers
+          SET name = ?, status = 'online', active_connection_id = ?, last_seen_at = datetime('now'), updated_at = datetime('now')
+          WHERE id = ?
+        `).run(name, connectionId, computerId);
+      }
+      this.db.query(`
+        UPDATE computer_connections
+        SET status = 'revoked', revoked_at = COALESCE(revoked_at, datetime('now'))
+        WHERE computer_id = ? AND status = 'active'
+      `).run(computerId);
+      if (revokedConnectionIds.length > 0) {
+        for (const revokedConnectionId of revokedConnectionIds) {
+          this.db.query(`
+            UPDATE agent_runs
+            SET status = 'killed',
+                action = NULL,
+                ended_at = COALESCE(ended_at, datetime('now')),
+                updated_at = datetime('now'),
+                output = CASE WHEN output = '' THEN 'connection revoked by newer daemon connection' ELSE output END
+            WHERE connection_id = ? AND status = 'running'
+          `).run(revokedConnectionId);
+          this.db.query(`
+            UPDATE message_deliveries
+            SET status = 'pending',
+                daemon_id = NULL,
+                connection_id = NULL,
+                claim_token = NULL,
+                lease_until = NULL,
+                run_id = NULL,
+                last_error = '',
+                claimed_at = NULL
+            WHERE connection_id = ? AND status IN ('claimed', 'processing_completed')
+          `).run(revokedConnectionId);
+        }
+      }
+      this.db.query(`
+        INSERT INTO computer_connections (id, computer_id, token_hash, epoch, status, connected_at, last_heartbeat_at)
+        VALUES (?, ?, ?, ?, 'active', datetime('now'), datetime('now'))
+      `).run(connectionId, computerId, tokenHash, epoch);
+      this.db.query(`
+        INSERT INTO daemon_instances (id, name, host, local_url, server_url, status, last_seen_at)
+        VALUES (?, ?, ?, ?, ?, 'online', datetime('now'))
+        ON CONFLICT(id) DO UPDATE SET
+          name = excluded.name,
+          host = excluded.host,
+          local_url = excluded.local_url,
+          server_url = excluded.server_url,
+          status = 'online',
+          last_seen_at = datetime('now')
+      `).run(connectionId, name, input.host ?? '', input.localUrl ?? '', input.serverUrl ?? '');
+      for (const agent of input.agents ?? []) {
+        const agentName = agent.agent.trim();
+        if (!agentName) continue;
+        this.db.query(`
+          INSERT INTO daemon_agents (daemon_id, agent, cwd, capabilities, status, last_seen_at)
+          VALUES (?, ?, ?, ?, 'online', datetime('now'))
+          ON CONFLICT(daemon_id, agent) DO UPDATE SET
+            cwd = excluded.cwd,
+            capabilities = excluded.capabilities,
+            status = 'online',
+            last_seen_at = datetime('now')
+        `).run(connectionId, agentName, agent.cwd ?? '', JSON.stringify(agent.capabilities ?? {}));
+      }
+    })();
+
+    return {
+      computer: this.getComputer(computerId)!,
+      connection: this.getComputerConnection(connectionId)!,
+      token,
+      daemon: this.getDaemon(connectionId)!,
+      agents: this.listComputerAgentAssignments(computerId),
+    };
+  }
+
+  closeStaleComputerConnections(timeoutMs: number, now = new Date()): number {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error('timeoutMs must be non-negative');
+    const cutoff = new Date(now.getTime() - timeoutMs).toISOString();
+    const staleRows = this.db.query(`
+      SELECT cc.id, cc.computer_id
+      FROM computer_connections cc
+      JOIN computers c ON c.active_connection_id = cc.id
+      WHERE cc.status = 'active' AND datetime(cc.last_heartbeat_at) < datetime(?)
+    `).all(cutoff) as Array<{ id: string; computer_id: string }>;
+    if (staleRows.length === 0) return 0;
+    this.db.transaction(() => {
+      for (const row of staleRows) {
+        this.db.query(`
+          UPDATE computer_connections
+          SET status = 'closed', revoked_at = COALESCE(revoked_at, datetime('now'))
+          WHERE id = ? AND status = 'active'
+        `).run(row.id);
+        this.db.query(`
+          UPDATE computers
+          SET status = 'offline', active_connection_id = NULL, updated_at = datetime('now')
+          WHERE id = ? AND active_connection_id = ?
+        `).run(row.computer_id, row.id);
+      }
+    })();
+    return staleRows.length;
+  }
+
+  assertActiveComputerConnection(input: ComputerAuthInput): ComputerConnection {
+    const computerId = input.computerId.trim();
+    const connectionId = input.connectionId.trim();
+    const token = input.token.trim();
+    const row = this.db.query(`
+      SELECT cc.*
+      FROM computer_connections cc
+      JOIN computers c ON c.id = cc.computer_id
+      WHERE cc.id = ? AND cc.computer_id = ? AND cc.status = 'active'
+        AND cc.token_hash = ? AND c.active_connection_id = cc.id AND c.status = 'online'
+      LIMIT 1
+    `).get(connectionId, computerId, hashSecret(token)) as Record<string, unknown> | null;
+    if (!row) throw new Error('CONNECTION_REVOKED');
+    return rowToComputerConnection(row);
+  }
+
+  heartbeatComputer(input: ComputerAuthInput): { computer: Computer; connection: ComputerConnection; agents: ComputerAgentAssignment[] } {
+    const connection = this.assertActiveComputerConnection(input);
+    this.db.query(`
+      UPDATE computer_connections SET last_heartbeat_at = datetime('now') WHERE id = ?
+    `).run(connection.id);
+    this.db.query(`
+      UPDATE computers SET status = 'online', last_seen_at = datetime('now'), updated_at = datetime('now') WHERE id = ?
+    `).run(connection.computer_id);
+    return {
+      computer: this.getComputer(connection.computer_id)!,
+      connection: this.getComputerConnection(connection.id)!,
+      agents: this.listComputerAgentAssignments(connection.computer_id),
+    };
+  }
+
+  registerDaemon(input: RegisterDaemonInput): DaemonInstance {
+    const id = input.id?.trim() || crypto.randomUUID();
+    const name = input.name.trim();
+    if (!name) throw new Error('daemon name is required');
+
+    this.db.transaction(() => {
+      this.db.query(`
+        INSERT INTO daemon_instances (id, name, host, local_url, server_url, status, last_seen_at)
+        VALUES (?, ?, ?, ?, ?, 'online', datetime('now'))
+        ON CONFLICT(id) DO UPDATE SET
+          name = excluded.name,
+          host = excluded.host,
+          local_url = excluded.local_url,
+          server_url = excluded.server_url,
+          status = 'online',
+          last_seen_at = datetime('now')
+      `).run(id, name, input.host ?? '', input.localUrl ?? '', input.serverUrl ?? '');
+
+      this.db.query(`
+        UPDATE daemon_agents SET status = 'offline', last_seen_at = datetime('now') WHERE daemon_id = ?
+      `).run(id);
+
+      for (const agent of input.agents ?? []) {
+        const agentName = agent.agent.trim();
+        if (!agentName) continue;
+        this.db.query(`
+          INSERT INTO daemon_agents (daemon_id, agent, cwd, capabilities, status, last_seen_at)
+          VALUES (?, ?, ?, ?, 'online', datetime('now'))
+          ON CONFLICT(daemon_id, agent) DO UPDATE SET
+            cwd = excluded.cwd,
+            capabilities = excluded.capabilities,
+            status = 'online',
+            last_seen_at = datetime('now')
+        `).run(id, agentName, agent.cwd ?? '', JSON.stringify(agent.capabilities ?? {}));
+      }
+    })();
+
+    return this.getDaemon(id)!;
+  }
+
+  getDaemon(id: string): DaemonInstance | null {
+    const row = this.db.query('SELECT * FROM daemon_instances WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToDaemon(row) : null;
+  }
+
+  daemonHasAgent(daemonId: string, agent: string): boolean {
+    const row = this.db.query(`
+      SELECT 1 FROM daemon_agents
+      WHERE daemon_id = ? AND agent = ? AND status = 'online'
+      LIMIT 1
+    `).get(daemonId, agent.trim()) as Record<string, unknown> | null;
+    return row !== null;
+  }
+
+  hasDaemonAgent(agent: string): boolean {
+    const row = this.db.query(`
+      SELECT 1 FROM daemon_agents
+      WHERE agent = ? AND status = 'online'
+      LIMIT 1
+    `).get(agent.trim()) as Record<string, unknown> | null;
+    return row !== null;
+  }
+
+  listDeliveries(agent: string, status = 'pending', limit = 50): MessageDelivery[] {
+    const rows = this.db.query(`
+      SELECT * FROM message_deliveries
+      WHERE agent = ? AND status = ?
+      ORDER BY datetime(created_at) ASC
+      LIMIT ?
+    `).all(agent, status, limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToDelivery);
+  }
+
+  listAllDeliveries(limit = 50): MessageDelivery[] {
+    const rows = this.db.query(`
+      SELECT * FROM message_deliveries
+      ORDER BY datetime(created_at) DESC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToDelivery);
+  }
+
+  createDelivery(input: CreateDeliveryInput): MessageDelivery {
+
+    const message = this.getMessage(input.messageId);
+    if (!message) throw new Error(`message ${input.messageId} was not found`);
+    const agent = input.agent.trim();
+    if (!agent) throw new Error('delivery agent is required');
+    if (message.sender === agent) throw new Error('cannot deliver a message to its sender');
+    if (message.recipient !== null && message.recipient !== agent) {
+      throw new Error(`message ${message.id} is addressed to ${message.recipient}`);
+    }
+
+    const idempotencyKey = `${message.id}:${message.chat_id}:${agent}`;
+    const existing = this.db.query('SELECT * FROM message_deliveries WHERE idempotency_key = ?').get(idempotencyKey) as Record<string, unknown> | null;
+    if (existing) return rowToDelivery(existing);
+
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO message_deliveries (id, message_id, chat_id, agent, status, idempotency_key)
+      VALUES (?, ?, ?, ?, 'pending', ?)
+    `).run(id, message.id, message.chat_id, agent, idempotencyKey);
+
+    return this.getDelivery(id)!;
+  }
+
+
+  resolveDeliveriesForMessage(messageId: number): MessageDelivery[] {
+    const message = this.getMessage(messageId);
+    if (!message) throw new Error(`message ${messageId} was not found`);
+    const room = this.getChatById(message.chat_id);
+    if (!room) throw new Error(`room ${message.chat_id} was not found`);
+    const candidates = new Set<string>();
+    if (message.recipient && this.getAgent(message.recipient)) candidates.add(message.recipient);
+    for (const mention of message.mentions ?? []) {
+      if (this.getAgent(mention)) candidates.add(mention);
+    }
+    if (room.kind === 'dm') {
+      const rows = this.db.query(`
+        SELECT participant_id AS agent FROM room_participants
+        WHERE room_id = ? AND kind = 'agent' AND status = 'active'
+      `).all(room.id) as Array<{ agent: string }>;
+      for (const row of rows) candidates.add(row.agent);
+    }
+    const allRows = this.db.query(`
+      SELECT agent FROM agent_room_subscriptions
+      WHERE room_id = ? AND channel_id IS NULL AND mode IN ('all', 'periodic')
+    `).all(room.id) as Array<{ agent: string }>;
+    for (const row of allRows) candidates.add(row.agent);
+
+    const deliveries: MessageDelivery[] = [];
+    for (const agent of candidates) {
+      if (agent === message.sender) continue;
+      if (!this.shouldCreateDeliveryForAgent(message, room, agent)) continue;
+      try {
+        deliveries.push(this.createDelivery({ messageId: message.id, agent }));
+      } catch {
+        // createDelivery enforces recipient/idempotency constraints; resolver skips conflicts.
+      }
+    }
+    return deliveries;
+  }
+
+  private shouldCreateDeliveryForAgent(message: Message, room: Chat, agent: string): boolean {
+    if (!this.canAgentParticipateInRoom(agent, room)) return false;
+    const direct = message.recipient === agent || (message.mentions ?? []).includes(agent);
+    if (room.kind === 'dm') return direct || message.recipient === null;
+    const subscription = this.getAgentRoomSubscription(agent, room.id);
+    const mode = subscription?.mode ?? 'mentions';
+    if (mode === 'off') return false;
+    if (direct) return true;
+    if (mode === 'all') return true;
+    return false;
+  }
+
+  canAgentParticipateInRoom(agent: string, room: Chat): boolean {
+    if (!this.getAgent(agent)) return false;
+    if (room.provider === 'web') {
+      const membership = this.getRoomParticipant(room.id, agent);
+      if (membership?.kind === 'agent' && membership.status === 'active') return true;
+      const row = this.db.query("SELECT COUNT(*) AS n FROM room_participants WHERE room_id = ? AND kind = 'agent' AND status = 'active'").get(room.id) as { n: number };
+      return Number(row.n) === 0;
+    }
+    const account = this.db.query(`
+      SELECT 1 FROM provider_accounts
+      WHERE provider = ? AND agent = ? AND status = 'active'
+      LIMIT 1
+    `).get(room.provider, agent) as Record<string, unknown> | null;
+    return account !== null;
+  }
+
+  canSendWebMessageToRoom(input: { room: Chat; sender: string }): boolean {
+    if (input.room.provider === 'web') return true;
+    if (!this.getAgent(input.sender)) return false;
+    if (input.room.provider === 'lark') {
+      const route = this.findLarkChannelForChat(input.room.id);
+      return route?.account.agent === input.sender;
+    }
+    return false;
+  }
+
+  recordPendingInboundEvent(input: { rawEventId: string; provider: Exclude<RoomProvider, 'web'>; providerAccountId?: string | null; reason: string; error?: string; nextRetryAt?: string | null }): PendingInboundEvent {
+    const id = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO pending_inbound_events (id, raw_event_id, provider, provider_account_id, reason, next_retry_at, last_error, status, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', datetime('now'), datetime('now'))
+      ON CONFLICT(raw_event_id, reason) DO UPDATE SET
+        retry_count = retry_count + 1,
+        next_retry_at = excluded.next_retry_at,
+        last_error = excluded.last_error,
+        updated_at = datetime('now')
+    `).run(id, input.rawEventId, input.provider, input.providerAccountId ?? null, input.reason, input.nextRetryAt ?? null, input.error ?? '');
+    const row = this.db.query('SELECT * FROM pending_inbound_events WHERE raw_event_id = ? AND reason = ?').get(input.rawEventId, input.reason) as Record<string, unknown>;
+    return rowToPendingInboundEvent(row);
+  }
+
+  getDelivery(id: string): MessageDelivery | null {
+    const row = this.db.query('SELECT * FROM message_deliveries WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToDelivery(row) : null;
+  }
+
+  getOrCreateSession(input: { chatId: string; agent: string; daemonId: string; cwd: string; lastMessageId?: number | null; computerId?: string | null; runtimeProvider?: string | null }): AgentSession {
+    const computerId = input.computerId?.trim() || null;
+    const runtimeProvider = input.runtimeProvider?.trim() || null;
+    const existing = computerId && runtimeProvider
+      ? this.db.query(`
+        SELECT * FROM agent_sessions
+        WHERE chat_id = ? AND agent = ? AND computer_id = ? AND runtime_provider = ?
+      `).get(input.chatId, input.agent, computerId, runtimeProvider) as Record<string, unknown> | null
+      : this.db.query(`
+        SELECT * FROM agent_sessions
+        WHERE chat_id = ? AND agent = ? AND daemon_id = ?
+      `).get(input.chatId, input.agent, input.daemonId) as Record<string, unknown> | null;
+
+    if (existing) {
+      this.db.query(`
+        UPDATE agent_sessions
+        SET daemon_id = ?, cwd = ?, last_message_id = COALESCE(?, last_message_id), updated_at = datetime('now')
+        WHERE id = ?
+      `).run(input.daemonId, input.cwd, input.lastMessageId ?? null, String(existing.id));
+      return this.getSession(String(existing.id))!;
+    }
+
+    const id = crypto.randomUUID();
+    const sessionKey = computerId && runtimeProvider
+      ? `${input.chatId}:${input.agent}:${computerId}:${runtimeProvider}`
+      : `${input.chatId}:${input.agent}:${input.daemonId}`;
+    this.db.query(`
+      INSERT INTO agent_sessions (id, chat_id, agent, daemon_id, cwd, session_key, last_message_id, computer_id, runtime_provider)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.chatId, input.agent, input.daemonId, input.cwd, sessionKey, input.lastMessageId ?? null, computerId, runtimeProvider);
+    return this.getSession(id)!;
+  }
+
+  getSession(id: string): AgentSession | null {
+    const row = this.db.query('SELECT * FROM agent_sessions WHERE id = ?').get(id) as Record<string, unknown> | null;
+    return row ? rowToSession(row) : null;
+  }
+
+  updateSessionRuntimeSessionId(id: string, runtimeSessionId: string): AgentSession {
+    const trimmed = runtimeSessionId.trim();
+    if (!trimmed) throw new Error('runtimeSessionId is required');
+    const result = this.db.query(`
+      UPDATE agent_sessions
+      SET runtime_session_id = ?, updated_at = datetime('now')
+      WHERE id = ?
+    `).run(trimmed, id);
+    if (result.changes === 0) throw new Error(`session ${id} was not found`);
+    return this.getSession(id)!;
+  }
+
+  listSessions(limit = 50): AgentSession[] {
+    const rows = this.db.query(`
+      SELECT * FROM agent_sessions
+      ORDER BY datetime(updated_at) DESC, datetime(created_at) DESC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToSession);
+  }
+
+  listRunsForSession(sessionId: string, limit = 50): AgentRun[] {
+    const rows = this.db.query(`
+      SELECT * FROM agent_runs
+      WHERE session_id = ?
+      ORDER BY datetime(updated_at) DESC, datetime(started_at) DESC
+      LIMIT ?
+    `).all(sessionId, limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToRun);
+  }
+
+  claimDelivery(id: string, input: ClaimDeliveryInput): MessageDelivery {
+    const claimToken = crypto.randomUUID();
+    const leaseMs = input.leaseMs ?? 30_000;
+    const leaseUntil = new Date(Date.now() + leaseMs).toISOString();
+    const delivery = this.getDelivery(id);
+    if (!delivery) throw new Error(`pending delivery ${id} was not found`);
+    if (input.computerId) {
+      const busy = this.db.query(`
+        SELECT 1
+        FROM agent_runs r
+        JOIN agent_sessions s ON s.id = r.session_id
+        WHERE r.computer_id = ? AND r.agent = ? AND s.chat_id = ? AND r.status = 'running'
+        LIMIT 1
+      `).get(input.computerId, delivery.agent, delivery.chat_id) as Record<string, unknown> | null;
+      if (busy) throw new Error(`runtime invocation already running for computer ${input.computerId} agent ${delivery.agent} chat ${delivery.chat_id}`);
+    }
+    const connectionId = input.connectionId ?? null;
+    const result = this.db.query(`
+      UPDATE message_deliveries
+      SET status = 'claimed', daemon_id = ?, connection_id = ?, claim_token = ?, lease_until = ?, attempts = attempts + 1, claimed_at = datetime('now')
+      WHERE id = ? AND status = 'pending'
+    `).run(input.daemonId, connectionId, claimToken, leaseUntil, id);
+    if (result.changes === 0) throw new Error(`pending delivery ${id} was not found`);
+    return this.getDelivery(id)!;
+  }
+
+  markDeliveryProcessingCompleted(id: string, input: FinishDeliveryInput): MessageDelivery {
+    const result = this.db.query(`
+      UPDATE message_deliveries
+      SET status = 'processing_completed', run_id = COALESCE(?, run_id)
+      WHERE id = ? AND status = 'claimed' AND (connection_id = ? OR (connection_id IS NULL AND daemon_id = ?)) AND claim_token = ?
+    `).run(input.runId ?? null, id, input.connectionId ?? input.daemonId, input.daemonId, input.claimToken);
+    if (result.changes === 0) throw new Error(`claimed delivery ${id} was not found`);
+    return this.getDelivery(id)!;
+  }
+
+  cancelDelivery(id: string): MessageDelivery {
+    const result = this.db.query(`
+      UPDATE message_deliveries
+      SET status = 'canceled'
+      WHERE id = ? AND status IN ('pending', 'claimed', 'processing_completed')
+    `).run(id);
+    if (result.changes === 0) throw new Error(`active delivery ${id} was not found`);
+    return this.getDelivery(id)!;
+  }
+
+  ackDelivery(id: string, input: FinishDeliveryInput): MessageDelivery {
+    const existing = this.getDelivery(id);
+    if (existing?.status === 'acked') {
+      if ((existing.connection_id ?? existing.daemon_id) === (input.connectionId ?? input.daemonId) && existing.claim_token === input.claimToken && existing.run_id === (input.runId ?? null)) {
+        return existing;
+      }
+      throw new Error(`terminal delivery ${id} conflicts with ack request`);
+    }
+    if (existing && ['failed', 'canceled'].includes(existing.status)) {
+      throw new Error(`terminal delivery ${id} cannot be acked from ${existing.status}`);
+    }
+
+    const result = this.db.query(`
+      UPDATE message_deliveries
+      SET status = 'acked', run_id = COALESCE(?, run_id), acked_at = COALESCE(acked_at, datetime('now'))
+      WHERE id = ? AND status IN ('claimed', 'processing_completed') AND (connection_id = ? OR (connection_id IS NULL AND daemon_id = ?)) AND claim_token = ?
+    `).run(input.runId ?? null, id, input.connectionId ?? input.daemonId, input.daemonId, input.claimToken);
+    if (result.changes === 0) throw new Error(`claimed delivery ${id} was not found`);
+    return this.getDelivery(id)!;
+  }
+
+  failDelivery(id: string, input: FinishDeliveryInput): MessageDelivery {
+    const existing = this.getDelivery(id);
+    if (existing?.status === 'failed') {
+      if ((existing.connection_id ?? existing.daemon_id) === (input.connectionId ?? input.daemonId) && existing.claim_token === input.claimToken && existing.run_id === (input.runId ?? null)) {
+        return existing;
+      }
+      throw new Error(`terminal delivery ${id} conflicts with fail request`);
+    }
+    if (existing && ['acked', 'canceled'].includes(existing.status)) {
+      throw new Error(`terminal delivery ${id} cannot fail from ${existing.status}`);
+    }
+
+    const result = this.db.query(`
+      UPDATE message_deliveries
+      SET status = 'failed', run_id = COALESCE(?, run_id), last_error = ?, failed_at = COALESCE(failed_at, datetime('now'))
+      WHERE id = ? AND status IN ('claimed', 'processing_completed') AND (connection_id = ? OR (connection_id IS NULL AND daemon_id = ?)) AND claim_token = ?
+    `).run(input.runId ?? null, input.error ?? '', id, input.connectionId ?? input.daemonId, input.daemonId, input.claimToken);
+    if (result.changes === 0) throw new Error(`claimed delivery ${id} was not found`);
+    return this.getDelivery(id)!;
+  }
+
+  startRun(input: StartRunInput): AgentRun {
+    const runId = crypto.randomUUID();
+    this.db.query(`
+      INSERT INTO agent_runs (id, message_id, agent, status, attempt, pid, cwd, session_id, trigger_message_id, daemon_id, connection_id, computer_id, runtime_provider, runtime_invocation_id, delivery_id)
+      VALUES (?, ?, ?, 'running', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      runId,
+      input.messageId,
+      input.agent,
+      input.attempt,
+      input.pid ?? null,
+      input.cwd,
+      input.sessionId ?? null,
+      input.triggerMessageId ?? input.messageId,
+      input.daemonId ?? null,
+      input.connectionId ?? null,
+      input.computerId ?? null,
+      input.runtimeProvider ?? null,
+      input.runtimeInvocationId ?? null,
+      input.deliveryId ?? null,
+    );
+    return this.getRun(runId)!;
+  }
+
+  setRunPid(runId: string, pid: number | null): void {
+    this.db.query(`
+      UPDATE agent_runs
+      SET pid = ?, updated_at = datetime('now')
+      WHERE id = ? AND status = 'running'
+    `).run(pid, runId);
+  }
+
+  finishRun(runId: string, input: FinishRunInput): void {
+    this.db.query(`
+      UPDATE agent_runs
+      SET status = ?, action = NULL, ended_at = datetime('now'), updated_at = datetime('now'), exit_code = ?, output = ?
+      WHERE id = ?
+    `).run(input.status, input.exitCode ?? null, input.output ?? '', runId);
+  }
+
+  requestRunAction(runId: string, action: RunAction): AgentRun {
+    const result = this.db.query(`
+      UPDATE agent_runs
+      SET action = ?, updated_at = datetime('now')
+      WHERE id = ? AND status = 'running'
+    `).run(action, runId);
+    if (result.changes === 0) throw new Error(`running run ${runId} was not found`);
+    return this.getRun(runId)!;
+  }
+
+  clearRunAction(runId: string): void {
+    this.db.query(`
+      UPDATE agent_runs
+      SET action = NULL, updated_at = datetime('now')
+      WHERE id = ?
+    `).run(runId);
+  }
+
+  getRun(runId: string): AgentRun | null {
+    const row = this.db.query('SELECT * FROM agent_runs WHERE id = ?').get(runId) as Record<string, unknown> | null;
+    return row ? rowToRun(row) : null;
+  }
+
+  listRuns(limit = 50): AgentRun[] {
+    const rows = this.db.query(`
+      SELECT * FROM agent_runs
+      ORDER BY datetime(updated_at) DESC, datetime(started_at) DESC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToRun);
+  }
+
+  createArtifact(input: CreateArtifactInput): { artifact: ArtifactMetadata; token: string } {
+    validateArtifactContent(input.mimeType, input.content);
+    const id = crypto.randomUUID();
+    const token = generateArtifactToken();
+    const tokenHash = hashArtifactToken(token);
+    const expiresAt = artifactExpiry(input.ttlSeconds);
+
+    this.db.query(`
+      INSERT INTO artifacts (id, token_hash, title, filename, mime_type, size_bytes, content, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id,
+      tokenHash,
+      input.title?.trim() ?? '',
+      input.filename?.trim() ?? '',
+      input.mimeType,
+      input.content.length,
+      input.content,
+      expiresAt,
+    );
+
+    return { artifact: this.getArtifactMetadata(id)!, token };
+  }
+
+  listArtifacts(limit = 50): ArtifactMetadata[] {
+    const rows = this.db.query(`
+      SELECT id, title, filename, mime_type, size_bytes, created_at, expires_at, revoked_at
+      FROM artifacts
+      ORDER BY datetime(created_at) DESC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToArtifactMetadata);
+  }
+
+  getArtifactMetadata(id: string): ArtifactMetadata | null {
+    const row = this.db.query(`
+      SELECT id, title, filename, mime_type, size_bytes, created_at, expires_at, revoked_at
+      FROM artifacts
+      WHERE id = ?
+    `).get(id) as Record<string, unknown> | null;
+    return row ? rowToArtifactMetadata(row) : null;
+  }
+
+  listWorkbenchArtifacts(limit = 50): WorkbenchArtifact[] {
+    const rows = this.db.query(`
+      SELECT id, title, filename, mime_type, size_bytes, created_at
+      FROM artifacts
+      WHERE revoked_at IS NULL AND datetime(expires_at) > datetime('now')
+      ORDER BY datetime(created_at) DESC
+      LIMIT ?
+    `).all(limitValue(limit, 50)) as Record<string, unknown>[];
+    return rows.map(rowToWorkbenchArtifact);
+  }
+
+  getArtifactByToken(token: string): Artifact | null {
+    const row = this.db.query('SELECT * FROM artifacts WHERE token_hash = ?').get(hashArtifactToken(token)) as Record<string, unknown> | null;
+    if (!row) return null;
+    const artifact = rowToArtifact(row);
+    if (artifact.revoked_at) return null;
+    if (Date.parse(artifact.expires_at) <= Date.now()) return null;
+    return artifact;
+  }
+
+  revokeArtifact(id: string): ArtifactMetadata {
+    const result = this.db.query(`
+      UPDATE artifacts
+      SET revoked_at = COALESCE(revoked_at, datetime('now'))
+      WHERE id = ?
+    `).run(id);
+    if (result.changes === 0) throw new Error(`artifact ${id} was not found`);
+    return this.getArtifactMetadata(id)!;
+  }
+
+  cleanupArtifacts(): number {
+    const result = this.db.query(`
+      DELETE FROM artifacts
+      WHERE revoked_at IS NOT NULL OR datetime(expires_at) <= datetime('now')
+    `).run();
+    return result.changes;
+  }
+}