@oar-sh/oar 0.9.0

package/server/repositories/message-repository.mjs

@@ -0,0 +1,434 @@
+'use strict';
+
+import { createShareVisibilityStatements } from './share-visibility-statements.mjs';
+import { sessionWorkerProviderSqlList } from '../../shared/provider-routing.mjs';
+
+export function createMessageRepository(db) {
+    const shareVisibility = createShareVisibilityStatements(db);
+    const queueHasImageOperationId = db.prepare(`PRAGMA table_info(queue)`).all()
+        .some((column) => column.name === 'image_operation_id');
+    const insertQueueSql = queueHasImageOperationId
+        ? `INSERT INTO queue (id, conversation_id, runtime_session_id, is_new_conversation, model, model_variant_id, reasoning_effort, context_tier, relay_mode, text, attachments, status, timestamp, retry_count, next_attempt_at, owner_sdk_session_id, owner_assigned_at, owner_lease_expires_at, owner_last_claimed_at, image_operation_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, 0, NULL, ?, ?, ?, ?, ?)`
+        : `INSERT INTO queue (id, conversation_id, runtime_session_id, is_new_conversation, model, model_variant_id, reasoning_effort, context_tier, relay_mode, text, attachments, status, timestamp, retry_count, next_attempt_at, owner_sdk_session_id, owner_assigned_at, owner_lease_expires_at, owner_last_claimed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, 0, NULL, ?, ?, ?, ?)`;
+    return {
+        // messages
+        getMessages:    db.prepare(`SELECT * FROM messages WHERE conversation_id = ? ORDER BY timestamp ASC`),
+        getSharedMessages: shareVisibility.getSharedMessages,
+        getMessageByConversation: db.prepare(`SELECT * FROM messages WHERE id = ? AND conversation_id = ? LIMIT 1`),
+        setMessageShareVisibility: shareVisibility.setMessageShareVisibility,
+        getLatestConversationModel: db.prepare(`SELECT model FROM messages WHERE conversation_id = ? AND model IS NOT NULL AND model != '' ORDER BY timestamp DESC LIMIT 1`),
+        getRecentMessagesDesc: db.prepare(`SELECT role, text, timestamp FROM messages WHERE conversation_id = ? ORDER BY timestamp DESC LIMIT ?`),
+        insertMsg:      db.prepare(`INSERT INTO messages (id, conversation_id, role, text, model, mode, attachments, timestamp, model_requested, model_actual, model_origin) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        // Provenance is derived from the authenticated responder identity at
+        // /api/response time, never from the response payload.
+        setMessageExecutedProvider: db.prepare(`UPDATE messages SET executed_provider = ? WHERE id = ?`),
+        searchMessagesCount: db.prepare(`
+          SELECT COUNT(*) AS cnt
+          FROM messages_fts fts
+          INNER JOIN messages m
+            ON m.rowid = fts.rowid
+          INNER JOIN conversations c
+            ON c.id = m.conversation_id
+          WHERE fts.text MATCH ?
+            AND c.status != 'deleted'
+        `),
+        searchMessagesPage: db.prepare(`
+          SELECT
+            m.id AS message_id,
+            m.conversation_id AS conversation_id,
+            c.title AS conversation_title,
+            m.role AS role,
+            m.timestamp AS timestamp,
+            m.text AS raw_text,
+            snippet(messages_fts, 0, '<mark>', '</mark>', '…', 18) AS snippet,
+            bm25(messages_fts) AS score
+          FROM messages_fts fts
+          INNER JOIN messages m
+            ON m.rowid = fts.rowid
+          INNER JOIN conversations c
+            ON c.id = m.conversation_id
+          WHERE fts.text MATCH ?
+            AND c.status != 'deleted'
+          ORDER BY score ASC, m.timestamp DESC, m.id DESC
+          LIMIT ? OFFSET ?
+        `),
+        upsertMessageUsageSnapshot: db.prepare(`
+          INSERT INTO message_usage_snapshots (
+            response_message_id,
+            queue_message_id,
+            conversation_id,
+            source,
+            stale,
+            premium_remaining,
+            premium_entitlement,
+            premium_used_percent,
+            premium_delta_used,
+            chat_remaining,
+            chat_entitlement,
+            chat_used_percent,
+            chat_delta_used,
+            plan_remaining,
+            plan_entitlement,
+            plan_used_percent,
+            plan_delta_used,
+            captured_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(response_message_id) DO UPDATE SET
+            queue_message_id = excluded.queue_message_id,
+            conversation_id = excluded.conversation_id,
+            source = excluded.source,
+            stale = excluded.stale,
+            premium_remaining = excluded.premium_remaining,
+            premium_entitlement = excluded.premium_entitlement,
+            premium_used_percent = excluded.premium_used_percent,
+            premium_delta_used = excluded.premium_delta_used,
+            chat_remaining = excluded.chat_remaining,
+            chat_entitlement = excluded.chat_entitlement,
+            chat_used_percent = excluded.chat_used_percent,
+            chat_delta_used = excluded.chat_delta_used,
+            plan_remaining = excluded.plan_remaining,
+            plan_entitlement = excluded.plan_entitlement,
+            plan_used_percent = excluded.plan_used_percent,
+            plan_delta_used = excluded.plan_delta_used,
+            captured_at = excluded.captured_at
+        `),
+        getLatestMessageUsageSnapshotByConversation: db.prepare(`
+          SELECT *
+          FROM message_usage_snapshots
+          WHERE conversation_id = ?
+          ORDER BY captured_at DESC
+          LIMIT 1
+        `),
+        listMessageUsageSnapshotsByConversation: db.prepare(`
+          SELECT *
+          FROM message_usage_snapshots
+          WHERE conversation_id = ?
+          ORDER BY captured_at ASC
+        `),
+
+        // queue
+        insertQ:        db.prepare(insertQueueSql),
+        queueHasImageOperationId,
+        // A background-continuation turn: born 'processing' and owned by its
+        // session worker — the CLI already started it on its own, so it must
+        // never be handed out as deliverable work.
+        insertContinuationQ: db.prepare(`INSERT INTO queue (id, conversation_id, runtime_session_id, is_new_conversation, model, relay_mode, text, status, kind, timestamp, processing_at, retry_count, owner_sdk_session_id, owner_assigned_at, owner_lease_expires_at, owner_last_claimed_at) VALUES (?, ?, ?, 0, ?, ?, ?, 'processing', 'continuation', ?, ?, 0, ?, ?, ?, ?)`),
+        setMessageKind: db.prepare(`UPDATE messages SET kind = ? WHERE id = ?`),
+        // Quiet teardown for a continuation whose worker died: there is no
+        // user to answer, so it fails without the terminal-failure ceremony.
+        dropStaleContinuation: db.prepare(`UPDATE queue SET status = 'failed', processing_at = NULL, next_attempt_at = NULL, owner_lease_expires_at = NULL WHERE id = ? AND status = 'processing' AND kind = 'continuation'`),
+        findPending:    db.prepare(`SELECT * FROM queue WHERE status = 'pending' AND COALESCE(kind, '') != 'continuation' AND (next_attempt_at IS NULL OR next_attempt_at <= ?) ORDER BY retry_count ASC, CASE WHEN next_attempt_at IS NULL THEN 0 ELSE 1 END ASC, COALESCE(next_attempt_at, timestamp) ASC, timestamp ASC LIMIT 1`),
+        // Global fallback for requesters without a session identity (the legacy
+        // Copilot relay CLI). Conversations bound to a session-worker provider
+        // (claude/cursor/grok) are excluded outright: handing one of their turns
+        // to the relay executes it on the Copilot plan under whatever model the
+        // id happens to resolve to there, invisibly to the user.
+        //
+        // Owned rows are excluded too. An owner means a session worker is
+        // responsible for the turn, and the relay polls every 2s while a worker
+        // takes ~a minute to become ready — so without this the relay wins that
+        // race and fails a turn it cannot run (an OpenAI image model is not a
+        // Copilot model), costing a retry and a backoff. Owners are only
+        // assigned when session-worker routing is enabled
+        // (resolveInitialQueueOwnerSessionId returns null otherwise), so
+        // routing-disabled installs still hand the relay every row.
+        findPendingForLegacyRelay: db.prepare(`
+          SELECT q.*
+          FROM queue q
+          LEFT JOIN runtime_sessions rs
+            ON rs.id = q.runtime_session_id
+          LEFT JOIN runtime_sessions rsc
+            ON rsc.conversation_id = q.conversation_id
+          WHERE q.status = 'pending'
+            AND COALESCE(q.kind, '') != 'continuation'
+            AND (q.next_attempt_at IS NULL OR q.next_attempt_at <= ?)
+            AND NULLIF(q.owner_sdk_session_id, '') IS NULL
+            AND LOWER(COALESCE(
+              NULLIF(rs.provider_type, ''),
+              NULLIF(rsc.provider_type, ''),
+              'github'
+            )) NOT IN (${sessionWorkerProviderSqlList()})
+          ORDER BY
+            q.retry_count ASC,
+            CASE WHEN q.next_attempt_at IS NULL THEN 0 ELSE 1 END ASC,
+            COALESCE(q.next_attempt_at, q.timestamp) ASC,
+            q.timestamp ASC
+          LIMIT 1
+        `),
+        findPendingForWorker: db.prepare(`
+          SELECT q.*
+          FROM queue q
+          LEFT JOIN runtime_sessions rs
+            ON rs.id = q.runtime_session_id
+          LEFT JOIN conversations c
+            ON c.id = q.conversation_id
+          WHERE q.status = 'pending'
+            AND COALESCE(q.kind, '') != 'continuation'
+            AND (q.next_attempt_at IS NULL OR q.next_attempt_at <= ?)
+            AND (
+              (
+                COALESCE(
+                  NULLIF(q.owner_sdk_session_id, ''),
+                  NULLIF(rs.sdk_session_id, ''),
+                  NULLIF(c.sdk_session_id, '')
+                ) IS NULL
+                -- Defense in depth: session-worker-provider turns are always
+                -- born owned, so an unowned one is a routing anomaly — it must
+                -- never be claimable by an arbitrary worker of a different
+                -- provider (isolation would otherwise rest on owner assignment
+                -- alone).
+                AND LOWER(COALESCE(NULLIF(rs.provider_type, ''), 'github'))
+                  NOT IN (${sessionWorkerProviderSqlList()})
+              )
+              OR COALESCE(
+                NULLIF(q.owner_sdk_session_id, ''),
+                NULLIF(rs.sdk_session_id, ''),
+                NULLIF(c.sdk_session_id, '')
+              ) = ?
+            )
+          ORDER BY
+            CASE
+              WHEN COALESCE(
+                NULLIF(q.owner_sdk_session_id, ''),
+                NULLIF(rs.sdk_session_id, ''),
+                NULLIF(c.sdk_session_id, '')
+              ) = ? THEN 0
+              ELSE 1
+            END ASC,
+            q.retry_count ASC,
+            CASE WHEN q.next_attempt_at IS NULL THEN 0 ELSE 1 END ASC,
+            COALESCE(q.next_attempt_at, q.timestamp) ASC,
+            q.timestamp ASC
+          LIMIT 1
+        `),
+        findPendingForSessionAffinity: db.prepare(`
+          SELECT q.*
+          FROM queue q
+          LEFT JOIN runtime_sessions rs
+            ON rs.id = q.runtime_session_id
+          LEFT JOIN conversations c
+            ON c.id = q.conversation_id
+          WHERE q.status = 'pending'
+            AND COALESCE(q.kind, '') != 'continuation'
+            AND (q.next_attempt_at IS NULL OR q.next_attempt_at <= ?)
+            AND COALESCE(
+              NULLIF(q.owner_sdk_session_id, ''),
+              NULLIF(rs.sdk_session_id, ''),
+              NULLIF(c.sdk_session_id, '')
+            ) = ?
+          ORDER BY
+            q.retry_count ASC,
+            CASE WHEN q.next_attempt_at IS NULL THEN 0 ELSE 1 END ASC,
+            COALESCE(q.next_attempt_at, q.timestamp) ASC,
+            q.timestamp ASC
+          LIMIT 1
+        `),
+        countQueueWorkForSessionAffinity: db.prepare(`
+          SELECT COUNT(*) AS cnt
+          FROM queue q
+          LEFT JOIN runtime_sessions rs
+            ON rs.id = q.runtime_session_id
+          LEFT JOIN conversations c
+            ON c.id = q.conversation_id
+          WHERE (
+            (q.status = 'pending' AND (q.next_attempt_at IS NULL OR q.next_attempt_at <= ?))
+            OR q.status = 'processing'
+          )
+            AND COALESCE(
+              NULLIF(q.owner_sdk_session_id, ''),
+              NULLIF(rs.sdk_session_id, ''),
+              NULLIF(c.sdk_session_id, '')
+            ) = ?
+        `),
+        listPendingWorkerOwnerSessionIds: db.prepare(`
+          SELECT COALESCE(
+            NULLIF(q.owner_sdk_session_id, ''),
+            NULLIF(rs.sdk_session_id, ''),
+            NULLIF(c.sdk_session_id, '')
+          ) AS sdk_session_id
+          FROM queue q
+          LEFT JOIN runtime_sessions rs
+            ON rs.id = q.runtime_session_id
+          LEFT JOIN conversations c
+            ON c.id = q.conversation_id
+          WHERE q.status = 'pending'
+            AND COALESCE(
+              NULLIF(q.owner_sdk_session_id, ''),
+              NULLIF(rs.sdk_session_id, ''),
+              NULLIF(c.sdk_session_id, '')
+            ) IS NOT NULL
+          GROUP BY COALESCE(
+            NULLIF(q.owner_sdk_session_id, ''),
+            NULLIF(rs.sdk_session_id, ''),
+            NULLIF(c.sdk_session_id, '')
+          )
+          ORDER BY MIN(q.timestamp) ASC
+          LIMIT ?
+        `),
+        countStatus:    db.prepare(`SELECT status, COUNT(*) as cnt FROM queue WHERE status IN ('pending','processing','parked') GROUP BY status`),
+        countRuntimeSessions: db.prepare(`SELECT COUNT(*) AS cnt FROM runtime_sessions WHERE status = 'active'`),
+        setProcessing:  db.prepare(`UPDATE queue SET status = 'processing', processing_at = ? WHERE id = ?`),
+        setProcessingWithWorkerLease: db.prepare(`
+          UPDATE queue
+          SET
+            status = 'processing',
+            processing_at = ?,
+            owner_sdk_session_id = COALESCE(NULLIF(owner_sdk_session_id, ''), ?),
+            owner_assigned_at = COALESCE(owner_assigned_at, ?),
+            owner_lease_expires_at = ?,
+            owner_last_claimed_at = ?
+          WHERE id = ?
+        `),
+        setQueueRuntimeSession: db.prepare(`UPDATE queue SET runtime_session_id = ? WHERE id = ?`),
+        setQueueResponseMessageId: db.prepare(`UPDATE queue SET response_message_id = ? WHERE id = ?`),
+        setDone:        db.prepare(`UPDATE queue SET status = 'done', response = ?, processing_at = NULL, next_attempt_at = NULL, owner_lease_expires_at = NULL WHERE id = ? AND status IN ('processing', 'pending')`),
+        setFailed:      db.prepare(`UPDATE queue SET status = 'failed', response = ?, processing_at = NULL, next_attempt_at = NULL, owner_lease_expires_at = NULL WHERE id = ?`),
+        deleteConvQ:    db.prepare(`DELETE FROM queue WHERE conversation_id = ?`),
+        findQById:      db.prepare(`SELECT * FROM queue WHERE id = ?`),
+        pruneQueue:     db.prepare(`DELETE FROM queue WHERE status = 'done' AND id NOT IN (SELECT id FROM queue WHERE status = 'done' ORDER BY timestamp DESC LIMIT 200)`),
+        // Recovery clears only the lease, never the owner: a recovered row must
+        // stay routed to its provider worker so the primer respawns that worker
+        // instead of the row becoming claimable by the global relay poll.
+        recoverStale:   db.prepare(`UPDATE queue SET status = 'pending', processing_at = NULL, next_attempt_at = ?, owner_lease_expires_at = NULL, owner_last_claimed_at = NULL WHERE status = 'processing' AND COALESCE(kind, '') != 'continuation' AND processing_at < ?`),
+        // Staleness is inactivity, not elapsed turn time: owner_last_claimed_at is
+        // refreshed by every worker heartbeat for the message it is working on, so a
+        // long-but-alive turn keeps moving the cutoff. processing_at is only the
+        // fallback for rows without an owner (session-worker routing disabled), and
+        // it is what the separate absolute ceiling measures.
+        //
+        // A turn blocked on an unanswered AskUserQuestion is never stale — it is
+        // waiting on the human, and relay_questions carries its own expiry.
+        listRecoverableProcessing: db.prepare(`
+          SELECT id, conversation_id, kind, relay_mode, model, retry_count
+          FROM queue
+          WHERE status = 'processing'
+            AND COALESCE(kind, '') != 'continuation'
+            AND (
+              COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
+              OR (@ceilingBefore IS NOT NULL AND COALESCE(processing_at, timestamp) < @ceilingBefore)
+            )
+            AND id NOT IN (SELECT queue_id FROM relay_questions WHERE status = 'pending')
+        `),
+        recoverProcessingBefore: db.prepare(`
+          UPDATE queue
+          SET status = 'pending',
+              processing_at = NULL,
+              next_attempt_at = @requeueAt,
+              owner_lease_expires_at = NULL,
+              owner_last_claimed_at = NULL,
+              retry_count = retry_count + 1
+          WHERE status = 'processing'
+            AND COALESCE(kind, '') != 'continuation'
+            AND (
+              COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
+              OR (@ceilingBefore IS NOT NULL AND COALESCE(processing_at, timestamp) < @ceilingBefore)
+            )
+            AND id NOT IN (SELECT queue_id FROM relay_questions WHERE status = 'pending')
+        `),
+        // Dead-worker recovery: the owner's process is provably gone, so its
+        // in-flight rows go back to pending — owner intact (the primer
+        // respawns that worker; the row must never become global prey) and
+        // retry_count incremented so a worker that dies on every delivery
+        // eventually exhausts the same budget as any other retry loop. The
+        // pending-question exemption deliberately does NOT apply here: a dead
+        // worker can never collect its answer, so holding the row would leak
+        // both the row and the question.
+        listProcessingRowsForOwner: db.prepare(`
+          SELECT id, conversation_id, kind, retry_count
+          FROM queue
+          WHERE status = 'processing'
+            AND NULLIF(owner_sdk_session_id, '') = ?
+        `),
+        recoverProcessingRowKeepOwner: db.prepare(`
+          UPDATE queue
+          SET status = 'pending',
+              processing_at = NULL,
+              next_attempt_at = ?,
+              owner_lease_expires_at = NULL,
+              owner_last_claimed_at = NULL,
+              retry_count = retry_count + 1
+          WHERE id = ? AND status = 'processing'
+        `),
+        listProcessingOwnerSessionIds: db.prepare(`
+          SELECT DISTINCT NULLIF(owner_sdk_session_id, '') AS sdk_session_id
+          FROM queue
+          WHERE status = 'processing'
+            AND NULLIF(owner_sdk_session_id, '') IS NOT NULL
+          LIMIT ?
+        `),
+        // A continuation with no live worker can only be torn down — replaying
+        // it as deliverable work would send the CLI's own bookkeeping text back
+        // to the CLI as a user prompt.
+        listStaleProcessingContinuations: db.prepare(`
+          SELECT id, conversation_id
+          FROM queue
+          WHERE status = 'processing'
+            AND kind = 'continuation'
+            AND (
+              COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
+              OR (@ceilingBefore IS NOT NULL AND COALESCE(processing_at, timestamp) < @ceilingBefore)
+            )
+        `),
+        listQueueForPauseDrop: db.prepare(`SELECT id, conversation_id FROM queue WHERE status IN ('pending', 'processing', 'parked')`),
+        // Authoritative "is a turn in flight" signal for the conversation list.
+        // Clients otherwise track this from one-shot message_status socket events,
+        // which are lost if the socket drops between the final status and delivery.
+        listConversationIdsWithActiveQueue: db.prepare(`SELECT DISTINCT conversation_id FROM queue WHERE status IN ('pending', 'processing', 'parked')`),
+        deleteQueueById: db.prepare(`DELETE FROM queue WHERE id = ?`),
+        getLatestProcessingQueueByConversation: db.prepare(`SELECT id, relay_mode, timestamp, processing_at FROM queue WHERE conversation_id = ? AND status = 'processing' ORDER BY COALESCE(processing_at, timestamp) DESC LIMIT 1`),
+        parkPendingQueueForRestart: db.prepare(`
+          UPDATE queue
+          SET
+            status = 'parked',
+            next_attempt_at = NULL,
+            parked_at = COALESCE(parked_at, @parkedAt),
+            parked_target_session_id = @targetSessionId,
+            parked_transaction_id = @transactionId,
+            parked_reason = @reason
+          WHERE status = 'pending'
+        `),
+        listParkedQueueForRelease: db.prepare(`
+          SELECT id, conversation_id
+          FROM queue
+          WHERE status = 'parked'
+            AND (
+              parked_transaction_id IS NULL
+              OR parked_transaction_id = ?
+              OR parked_target_session_id = ?
+            )
+          ORDER BY COALESCE(parked_at, timestamp) ASC, timestamp ASC
+        `),
+        listAllParkedQueueForRelease: db.prepare(`
+          SELECT id, conversation_id
+          FROM queue
+          WHERE status = 'parked'
+          ORDER BY COALESCE(parked_at, timestamp) ASC, timestamp ASC
+        `),
+        releaseParkedQueueByIds: db.prepare(`
+          UPDATE queue
+          SET
+            status = 'pending',
+            parked_at = NULL,
+            parked_target_session_id = NULL,
+            parked_transaction_id = NULL,
+            parked_reason = NULL
+          WHERE id = ? AND status = 'parked'
+        `),
+
+
+        // uploads
+        getUploadFile: db.prepare(`SELECT * FROM uploaded_files WHERE sha256 = ?`),
+        insertUploadFile: db.prepare(`INSERT OR IGNORE INTO uploaded_files (sha256, original_name, mime_type, size_bytes, created_at) VALUES (?, ?, ?, ?, ?)`),
+        insertUploadRef: db.prepare(`INSERT OR IGNORE INTO upload_refs (file_sha256, conversation_id, message_id, created_at) VALUES (?, ?, ?, ?)`),
+        listUploadHashesByConversation: db.prepare(`SELECT DISTINCT file_sha256 FROM upload_refs WHERE conversation_id = ?`),
+        deleteUploadRefsByConversation: db.prepare(`DELETE FROM upload_refs WHERE conversation_id = ?`),
+        countUploadRefsBySha: db.prepare(`SELECT COUNT(*) AS cnt FROM upload_refs WHERE file_sha256 = ?`),
+        deleteUploadFile: db.prepare(`DELETE FROM uploaded_files WHERE sha256 = ?`),
+
+        // Draft attachment references use a sentinel message id so a composer
+        // draft can hold a blob alive before any message exists.
+        listDraftUploadHashes: db.prepare(`SELECT file_sha256 FROM upload_refs WHERE conversation_id = ? AND message_id = '__draft__'`),
+        deleteDraftUploadRefs: db.prepare(`DELETE FROM upload_refs WHERE conversation_id = ? AND message_id = '__draft__'`),
+        deleteDraftUploadRef: db.prepare(`DELETE FROM upload_refs WHERE conversation_id = ? AND message_id = '__draft__' AND file_sha256 = ?`),
+    };
+}

package/server/repositories/question-repository.mjs

@@ -0,0 +1,161 @@
+'use strict';
+
+export function createQuestionRepository(db) {
+    return {
+        // relay questions
+        insertQuestion: db.prepare(`INSERT INTO relay_questions (id, queue_id, conversation_id, message_id, relay_mode, prompt, choices, request, request_schema, status, answer, structured_answer, sdk_session_id, owner_worker_id, continuation_id, continuation_question_id, created_at, answered_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, ?, ?, ?, ?, ?, NULL, ?)`),
+        getQuestion:    db.prepare(`SELECT * FROM relay_questions WHERE id = ?`),
+        findPendingQuestionByMessage: db.prepare(`SELECT * FROM relay_questions WHERE message_id = ? AND status = 'pending' ORDER BY created_at DESC LIMIT 1`),
+        listPendingQuestionsByMessage: db.prepare(`SELECT * FROM relay_questions WHERE message_id = ? AND status = 'pending' ORDER BY created_at ASC`),
+        findRecentlyAnsweredQuestionByMessage: db.prepare(`SELECT * FROM relay_questions WHERE message_id = ? AND status = 'answered' AND answered_at >= ? ORDER BY answered_at DESC LIMIT 1`),
+        listQuestions:  db.prepare(`SELECT * FROM relay_questions WHERE status = ? AND (? IS NULL OR conversation_id = ?) ORDER BY created_at ASC`),
+        timeoutQuestion:db.prepare(`UPDATE relay_questions SET status = 'timed_out' WHERE id = ? AND status = 'pending'`),
+        cancelPendingQuestionsByMessage: db.prepare(`UPDATE relay_questions SET status = 'cancelled', answered_at = COALESCE(answered_at, ?) WHERE message_id = ? AND status = 'pending'`),
+        deleteConvQuestions: db.prepare(`DELETE FROM relay_questions WHERE conversation_id = ?`),
+        // RETURNING (run via .all) so the expiry log names exactly the rows
+        // that flipped — a separate pre-SELECT could race an answer landing
+        // between the two statements.
+        expireQuestions: db.prepare(`UPDATE relay_questions SET status = 'timed_out' WHERE status = 'pending' AND expires_at < ? RETURNING id, created_at`),
+
+        // relay activity
+        insertActivity: db.prepare(`INSERT INTO relay_activity (queue_message_id, response_message_id, conversation_id, relay_mode, text, created_at, subagent_run_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`),
+        linkActivityToResponse: db.prepare(`UPDATE relay_activity SET response_message_id = ? WHERE queue_message_id = ? AND response_message_id IS NULL`),
+        listActivityByResponse: db.prepare(`SELECT text, subagent_run_id, metadata_json FROM relay_activity WHERE response_message_id = ? ORDER BY id ASC`),
+        listActivityByQueueMessage: db.prepare(`SELECT text, subagent_run_id, metadata_json FROM relay_activity WHERE queue_message_id = ? ORDER BY id ASC`),
+        deleteConvActivity: db.prepare(`DELETE FROM relay_activity WHERE conversation_id = ?`),
+
+        // relay stream events — every update carries the full text-so-far
+        // (all workers publish cumulative snapshots), so the store keeps ONE
+        // row per (queue message, subagent thread) and replaces it in place.
+        getLastStreamSeqByQueueMessage: db.prepare(`SELECT COALESCE(MAX(seq), 0) AS max_seq FROM relay_stream_events WHERE queue_message_id = ?`),
+        getStreamEventByQueueAndThread: db.prepare(`SELECT id, seq, done FROM relay_stream_events WHERE queue_message_id = ? AND subagent_run_id IS ? LIMIT 1`),
+        insertStreamEvent: db.prepare(`INSERT INTO relay_stream_events (queue_message_id, response_message_id, conversation_id, relay_mode, seq, text, done, created_at, subagent_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        updateStreamEventByQueueAndThread: db.prepare(`
+          UPDATE relay_stream_events
+          SET response_message_id = COALESCE(response_message_id, ?),
+              conversation_id = ?,
+              relay_mode = ?,
+              seq = ?,
+              text = ?,
+              done = CASE WHEN done = 1 OR ? = 1 THEN 1 ELSE 0 END,
+              created_at = ?
+          WHERE queue_message_id = ?
+            AND subagent_run_id IS ?
+        `),
+        linkStreamEventsToResponse: db.prepare(`UPDATE relay_stream_events SET response_message_id = ? WHERE queue_message_id = ? AND response_message_id IS NULL`),
+        listStreamEventsByResponse: db.prepare(`SELECT seq, text, done, created_at, subagent_run_id FROM relay_stream_events WHERE response_message_id = ? ORDER BY seq ASC, id ASC`),
+        listStreamEventsByQueueMessage: db.prepare(`SELECT seq, text, done, created_at, subagent_run_id FROM relay_stream_events WHERE queue_message_id = ? ORDER BY seq ASC, id ASC`),
+        deleteConvStreamEvents: db.prepare(`DELETE FROM relay_stream_events WHERE conversation_id = ?`),
+
+        // relay thoughts (agent reasoning)
+        getLastThoughtSeqByQueueMessage: db.prepare(`SELECT COALESCE(MAX(seq), 0) AS max_seq FROM relay_thought WHERE queue_message_id = ?`),
+        getThoughtByQueueAndReasoning: db.prepare(`SELECT seq FROM relay_thought WHERE queue_message_id = ? AND reasoning_id = ? LIMIT 1`),
+        insertThought: db.prepare(`INSERT INTO relay_thought (queue_message_id, response_message_id, conversation_id, relay_mode, reasoning_id, seq, text, done, created_at, subagent_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        updateThoughtByQueueAndReasoning: db.prepare(`
+          UPDATE relay_thought
+          SET response_message_id = COALESCE(response_message_id, ?),
+              conversation_id = ?,
+              relay_mode = ?,
+              text = ?,
+              done = CASE WHEN done = 1 OR ? = 1 THEN 1 ELSE 0 END,
+              created_at = ?,
+              subagent_run_id = COALESCE(?, subagent_run_id)
+          WHERE queue_message_id = ?
+            AND reasoning_id = ?
+        `),
+        linkThoughtsToResponse: db.prepare(`UPDATE relay_thought SET response_message_id = ? WHERE queue_message_id = ? AND response_message_id IS NULL`),
+        listThoughtsByResponse: db.prepare(`SELECT reasoning_id, seq, text, done, created_at, subagent_run_id FROM relay_thought WHERE response_message_id = ? ORDER BY seq ASC, id ASC`),
+        listThoughtsByQueueMessage: db.prepare(`SELECT reasoning_id, seq, text, done, created_at, subagent_run_id FROM relay_thought WHERE queue_message_id = ? ORDER BY seq ASC, id ASC`),
+        deleteConvThoughts: db.prepare(`DELETE FROM relay_thought WHERE conversation_id = ?`),
+
+        // subagent runs
+        insertSubagentRun: db.prepare(`
+          INSERT INTO subagent_runs (
+            id, queue_message_id, conversation_id, parent_subagent_id, display_name, status, started_at, updated_at, completed_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)
+        `),
+        getSubagentRun: db.prepare(`SELECT * FROM subagent_runs WHERE id = ?`),
+        updateSubagentRunStatus: db.prepare(`
+          UPDATE subagent_runs
+          SET status = ?, updated_at = ?, completed_at = COALESCE(?, completed_at)
+          WHERE id = ?
+        `),
+        listSubagentRunsByQueueMessage: db.prepare(`
+          SELECT id, queue_message_id, conversation_id, parent_subagent_id, display_name, status, started_at, updated_at, completed_at
+          FROM subagent_runs
+          WHERE queue_message_id = ?
+          ORDER BY started_at ASC, id ASC
+        `),
+        // Terminal-state reconciliation: whatever ends a turn (response, fail,
+        // abort) also ends its subagent runs — nothing else ever will, and an
+        // un-reconciled row renders as a bubble stuck "running" forever.
+        listRunningSubagentRunsByQueueMessage: db.prepare(`
+          SELECT id, conversation_id, parent_subagent_id, display_name
+          FROM subagent_runs
+          WHERE queue_message_id = ? AND status = 'running'
+        `),
+        closeRunningSubagentRunsByQueueMessage: db.prepare(`
+          UPDATE subagent_runs
+          SET status = ?, updated_at = ?, completed_at = COALESCE(completed_at, ?)
+          WHERE queue_message_id = ? AND status = 'running'
+        `),
+        listSubagentRunsByResponse: db.prepare(`
+          SELECT sr.id, sr.queue_message_id, sr.conversation_id, sr.parent_subagent_id, sr.display_name, sr.status, sr.started_at, sr.updated_at, sr.completed_at
+          FROM subagent_runs sr
+          WHERE sr.queue_message_id IN (
+            SELECT id FROM queue WHERE response_message_id = ?
+            UNION
+            SELECT DISTINCT queue_message_id FROM relay_activity WHERE response_message_id = ? AND queue_message_id IS NOT NULL
+            UNION
+            SELECT DISTINCT queue_message_id FROM relay_thought WHERE response_message_id = ? AND queue_message_id IS NOT NULL
+          )
+          ORDER BY sr.started_at ASC, sr.id ASC
+        `),
+        deleteConvSubagentRuns: db.prepare(`DELETE FROM subagent_runs WHERE conversation_id = ?`),
+
+        // workflow runs — final digests of settled background workflows,
+        // attached to the assistant message that reports the completion.
+        // Inserted inside the /api/response finalize transaction, so rows key
+        // directly on the response message id (unlike subagent_runs, which are
+        // written before the response id exists and need queue-id resolution).
+        insertWorkflowRun: db.prepare(`
+          INSERT INTO workflow_runs (
+            id, response_message_id, conversation_id, run_index, digest_json, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?)
+        `),
+        listWorkflowRunsByResponse: db.prepare(`
+          SELECT id, response_message_id, conversation_id, run_index, digest_json, created_at
+          FROM workflow_runs
+          WHERE response_message_id = ?
+          ORDER BY run_index ASC, id ASC
+        `),
+        deleteConvWorkflowRuns: db.prepare(`DELETE FROM workflow_runs WHERE conversation_id = ?`),
+
+        // preview cards — snapshots of previews published mid-turn, written
+        // with the queue id and linked to the response at finalize (the same
+        // two-step relay_activity uses, because the response id does not exist
+        // while the turn is still running).
+        insertPreviewCard: db.prepare(`
+          INSERT INTO preview_cards (
+            id, queue_message_id, response_message_id, conversation_id, preview_json, created_at
+          ) VALUES (?, ?, NULL, ?, ?, ?)
+        `),
+        linkPreviewCardsToResponse: db.prepare(`UPDATE preview_cards SET response_message_id = ? WHERE queue_message_id = ? AND response_message_id IS NULL`),
+        listPreviewCardsByResponse: db.prepare(`
+          SELECT id, preview_json, created_at
+          FROM preview_cards
+          WHERE response_message_id = ?
+          ORDER BY created_at ASC, id ASC
+        `),
+        deleteConvPreviewCards: db.prepare(`DELETE FROM preview_cards WHERE conversation_id = ?`),
+
+        // relay boards
+        insertBoard: db.prepare(`INSERT INTO relay_boards (id, queue_id, conversation_id, message_id, board_type, relay_mode, title, body, actions_json, recommended_action, context_json, status, selected_action, acted_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, ?, ?)`),
+        getBoard: db.prepare(`SELECT * FROM relay_boards WHERE id = ?`),
+        findBoardByMessageType: db.prepare(`SELECT * FROM relay_boards WHERE message_id = ? AND board_type = ? ORDER BY created_at DESC LIMIT 1`),
+        listBoards: db.prepare(`SELECT * FROM relay_boards WHERE status = ? AND (? IS NULL OR conversation_id = ?) ORDER BY created_at ASC`),
+        markBoardAction: db.prepare(`UPDATE relay_boards SET status = 'acted', selected_action = ?, acted_at = ?, updated_at = ? WHERE id = ? AND status = 'pending'`),
+        dismissBoard: db.prepare(`UPDATE relay_boards SET status = 'dismissed', selected_action = ?, acted_at = ?, updated_at = ? WHERE id = ? AND status = 'pending'`),
+        deleteConvBoards: db.prepare(`DELETE FROM relay_boards WHERE conversation_id = ?`),
+    };
+}