@oar-sh/oar 0.9.0

package/server/services/relay-singleton-guard.mjs

@@ -0,0 +1,124 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+
+function hashToken(value) {
+  const token = String(value || "").trim();
+  if (!token) return "";
+  return crypto.createHash("sha256").update(token).digest("hex");
+}
+
+function safeReadLock(lockPath) {
+  try {
+    const raw = fs.readFileSync(lockPath, "utf8");
+    const parsed = JSON.parse(raw);
+    // Prefer the hashed field; fall back to hashing a legacy plaintext `token`
+    // so a lock written by an older build still matches (and is rewritten 0600).
+    const tokenHash = typeof parsed?.tokenHash === "string" && parsed.tokenHash
+      ? parsed.tokenHash
+      : hashToken(parsed?.token);
+    return {
+      pid: Number.parseInt(String(parsed?.pid ?? ""), 10),
+      tokenHash,
+      startedAt: typeof parsed?.startedAt === "string" ? parsed.startedAt : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function createRelaySingletonGuard({
+  lockPath,
+  pid,
+  token,
+  now = () => new Date().toISOString(),
+  isProcessAlive,
+  logger = console,
+}) {
+  const lockFilePath = path.resolve(String(lockPath || ""));
+  const currentPid = Number.parseInt(String(pid || process.pid), 10);
+  const currentTokenHash = hashToken(token);
+  const processAlive = typeof isProcessAlive === "function"
+    ? isProcessAlive
+    : (candidatePid) => {
+      if (!Number.isInteger(candidatePid) || candidatePid <= 0) return false;
+      try {
+        process.kill(candidatePid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+
+  function writeLock() {
+    fs.mkdirSync(path.dirname(lockFilePath), { recursive: true });
+    const payload = {
+      pid: currentPid,
+      // Store only a hash of the auth token: the guard needs equality for the
+      // self-ownership check, never the token itself. Keeps the master
+      // credential out of a file that has historically been world-readable.
+      tokenHash: currentTokenHash,
+      startedAt: now(),
+    };
+    const fd = fs.openSync(lockFilePath, "wx", 0o600);
+    try {
+      fs.writeFileSync(fd, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    } finally {
+      try { fs.closeSync(fd); } catch {}
+    }
+    return payload;
+  }
+
+  function acquire() {
+    try {
+      return writeLock();
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        throw error;
+      }
+    }
+
+    const existingLock = safeReadLock(lockFilePath);
+    const existingPid = Number.isInteger(existingLock?.pid) ? existingLock.pid : null;
+    const existingTokenHash = typeof existingLock?.tokenHash === "string" ? existingLock.tokenHash : "";
+    const existingStartedAt = existingLock?.startedAt || "unknown";
+
+    if (existingPid && processAlive(existingPid)) {
+      if (existingTokenHash && existingTokenHash === currentTokenHash) {
+        throw new Error(`Relay already running (pid=${existingPid}, startedAt=${existingStartedAt}).`);
+      }
+      throw new Error(
+        `Relay appears to be owned by another live process (pid=${existingPid}, startedAt=${existingStartedAt}).`
+      );
+    }
+
+    try {
+      fs.unlinkSync(lockFilePath);
+      logger?.warn?.(`[server] Recovered stale singleton lock: ${lockFilePath}`);
+    } catch (unlinkError) {
+      if (unlinkError?.code !== "ENOENT") throw unlinkError;
+    }
+
+    return writeLock();
+  }
+
+  function release() {
+    const existingLock = safeReadLock(lockFilePath);
+    if (!existingLock) return false;
+    if (existingLock.pid !== currentPid) return false;
+    if (String(existingLock.tokenHash || "") !== currentTokenHash) return false;
+    try {
+      fs.unlinkSync(lockFilePath);
+      return true;
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+  }
+
+  return {
+    lockFilePath,
+    acquire,
+    release,
+  };
+}

package/server/services/safe-served-content.mjs

@@ -0,0 +1,57 @@
+// Safe headers for streaming stored bytes (workspace files, uploads, shared
+// attachments) back to the browser.
+//
+// The threat: a semi-trusted producer (an AI worker writing a workspace file, or
+// an uploaded attachment) can supply content whose MIME type the browser will
+// execute as markup/script on THIS origin — `text/html`, `image/svg+xml`, XML
+// with embedded script. Served inline, that is stored XSS against the app (and,
+// via the unauthenticated /api/shared/* routes, against share viewers). We
+// neutralize such types to `text/plain` and always send `nosniff`, and we attach
+// a locked-down CSP + `sandbox` so anything that still reaches the browser as a
+// document can neither run script nor navigate.
+
+// Types the browser renders as active documents on this origin.
+const ACTIVE_MARKUP_PATTERN = /^text\/html\b|svg|xhtml|(^|\/)xml\b|\+xml\b/i;
+
+// Types safe to preview inline with their real Content-Type.
+const INLINE_SAFE_PREFIXES = ['image/', 'video/', 'audio/'];
+const INLINE_SAFE_EXACT = new Set(['application/pdf']);
+
+/**
+ * Resolve the Content-Type to send for stored bytes, neutralizing types the
+ * browser would execute. Returns the (possibly coerced) type plus whether it is
+ * safe to display inline.
+ */
+export function safeServedContentType(mimeType) {
+  const type = String(mimeType || '').trim().toLowerCase().split(';')[0].slice(0, 127)
+    || 'application/octet-stream';
+  if (ACTIVE_MARKUP_PATTERN.test(type)) {
+    // Render markup/script content as its own source text instead of executing it.
+    return { contentType: 'text/plain; charset=utf-8', inlineSafe: false, neutralized: true };
+  }
+  const inlineSafe = INLINE_SAFE_PREFIXES.some((prefix) => type.startsWith(prefix))
+    || INLINE_SAFE_EXACT.has(type);
+  return { contentType: type, inlineSafe, neutralized: false };
+}
+
+/**
+ * Apply the safe Content-Type plus the hardening headers to a response that is
+ * about to stream stored bytes. Returns the resolved descriptor so callers can
+ * choose an inline vs. attachment disposition.
+ */
+export function applySafeServedContentHeaders(res, mimeType, { fileName = '' } = {}) {
+  const resolved = safeServedContentType(mimeType);
+  res.setHeader('Content-Type', resolved.contentType);
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  // Belt-and-braces: a served file is never part of the app UI, so forbid it
+  // from loading anything or being framed, and sandbox it so it cannot run
+  // script or navigate even if a browser would otherwise treat it as active.
+  res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox; frame-ancestors 'none'");
+  const safeName = String(fileName || '').replace(/[\r\n"\\]/g, '').slice(0, 255);
+  const disposition = resolved.inlineSafe ? 'inline' : 'attachment';
+  res.setHeader(
+    'Content-Disposition',
+    safeName ? `${disposition}; filename="${safeName}"` : disposition,
+  );
+  return resolved;
+}

package/server/services/sdk-session-import-service.mjs

@@ -0,0 +1,271 @@
+'use strict';
+
+function text(value) {
+  return String(value || '').trim();
+}
+
+function iso(value, fallback = null) {
+  const parsed = value instanceof Date ? value.getTime() : Date.parse(String(value || ''));
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : fallback;
+}
+
+function sessionIdOf(session) {
+  return text(session?.sessionId || session?.id || session?.session_id);
+}
+
+function sessionMetadata(session) {
+  return session?.metadata || session || {};
+}
+
+function sourceTimestamps(session) {
+  const metadata = sessionMetadata(session);
+  return {
+    startedAt: iso(
+      metadata.startTime
+      || metadata.start_time
+      || metadata.createdAt
+      || metadata.created_at
+      || session?.startTime
+      || session?.createdAt,
+    ),
+    modifiedAt: iso(
+      metadata.modifiedTime
+      || metadata.modified_time
+      || metadata.updatedAt
+      || metadata.updated_at
+      || session?.modifiedTime
+      || session?.updatedAt,
+    ),
+  };
+}
+
+function sessionTitle(session, messages) {
+  const metadata = session?.metadata || session || {};
+  const summary = text(metadata.summary || metadata.title || metadata.name);
+  if (summary) return summary.slice(0, 240);
+  const firstUser = (Array.isArray(messages) ? messages : []).find((message) => message?.role === 'user');
+  return text(firstUser?.text).replace(/\s+/g, ' ').slice(0, 240) || 'Session';
+}
+
+async function normalizeEvents(value) {
+  if (Array.isArray(value)) return value;
+  if (Array.isArray(value?.sessions)) return value.sessions;
+  if (Array.isArray(value?.events)) return value.events;
+  if (value?.[Symbol.asyncIterator]) {
+    const events = [];
+    for await (const event of value) events.push(event);
+    return events;
+  }
+  if (value?.[Symbol.iterator]) return [...value];
+  return [];
+}
+
+function boundedError(error) {
+  return text(error?.message || error).slice(0, 1000) || 'Unknown SDK session import failure';
+}
+
+export function createSdkSessionImportService({
+  db,
+  stmts,
+  createClient,
+  parseSessionEventsToMessages,
+  replaceRetrievableHistory,
+  ensureRuntimeSessionBinding,
+  logger = console,
+} = {}) {
+  if (!db || !stmts || typeof createClient !== 'function') throw new Error('SDK session importer requires database, statements, and a client factory');
+  let runtime = null;
+  let activeRun = null;
+  const countConversationMessages = db.prepare(`
+    SELECT COUNT(*) AS count
+    FROM messages
+    WHERE conversation_id = ?
+  `);
+
+  const upsertConversation = db.prepare(`
+    INSERT INTO conversations (id, title, sdk_session_id, configured_workspace_root_path, runtime_workspace_root_path, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      sdk_session_id = excluded.sdk_session_id,
+      title = CASE WHEN conversations.title_source = 'manual' THEN conversations.title ELSE excluded.title END,
+      configured_workspace_root_path = COALESCE(conversations.configured_workspace_root_path, excluded.configured_workspace_root_path),
+      runtime_workspace_root_path = COALESCE(conversations.runtime_workspace_root_path, excluded.runtime_workspace_root_path),
+      updated_at = excluded.updated_at
+  `);
+
+  async function getRuntime() {
+    if (!runtime) runtime = await createClient();
+    return runtime;
+  }
+
+  function isTombstoned(sdkSessionId) {
+    return !!stmts.getDeletedSdkSession.get(sdkSessionId);
+  }
+
+  function claim(sdkSessionId, session, { force = false } = {}) {
+    const now = new Date().toISOString();
+    return db.transaction(() => {
+      const existing = stmts.getSdkSessionImport.get(sdkSessionId);
+      const { modifiedAt } = sourceTimestamps(session);
+      const hasNewerSource = modifiedAt
+        && (!existing?.source_modified_at || modifiedAt > existing.source_modified_at);
+      if (!force && existing?.status === 'completed' && !hasNewerSource) {
+        return { claimed: null, category: 'unchanged' };
+      }
+      stmts.upsertSdkSessionImport.run(sdkSessionId, existing?.conversation_id || sdkSessionId, now);
+      const claimed = stmts.claimSdkSessionImport.run(
+        now,
+        now,
+        sdkSessionId,
+        force || hasNewerSource ? 1 : 0,
+      );
+      if (claimed.changes === 0) return { claimed: null, category: 'unchanged' };
+      return {
+        claimed: stmts.getSdkSessionImport.get(sdkSessionId),
+        category: existing?.status === 'completed' ? 'changed' : 'new',
+      };
+    })();
+  }
+
+  function persistCompletedImport({ sdkSessionId, session, messages }) {
+    const now = new Date().toISOString();
+    const metadata = sessionMetadata(session);
+    const { startedAt: sourceStartedAt, modifiedAt: sourceModifiedAt } = sourceTimestamps(session);
+    const updatedAt = sourceModifiedAt || now;
+    const createdAt = sourceStartedAt || updatedAt;
+    const workspaceRoot = text(metadata.workspaceRootPath || metadata.workspace_root_path || metadata.cwd) || null;
+    const title = sessionTitle(session, messages);
+    db.transaction(() => {
+      upsertConversation.run(sdkSessionId, title, sdkSessionId, workspaceRoot, workspaceRoot, createdAt, updatedAt);
+      ensureRuntimeSessionBinding(sdkSessionId, null, updatedAt, sdkSessionId);
+      replaceRetrievableHistory(sdkSessionId, messages);
+      stmts.completeSdkSessionImport.run(
+        sdkSessionId,
+        now,
+        sourceStartedAt,
+        sourceModifiedAt,
+        now,
+        sdkSessionId,
+      );
+    })();
+  }
+
+  async function importSession(session, { force = false } = {}) {
+    const sdkSessionId = sessionIdOf(session);
+    if (!sdkSessionId) return { status: 'skipped', category: 'unchanged', reason: 'missing-session-id' };
+    if (isTombstoned(sdkSessionId)) return { sdkSessionId, status: 'skipped', category: 'tombstoned', reason: 'tombstoned' };
+    // Sessions the relay created to execute an existing conversation's turns
+    // are vehicles, not conversations: their history already lives in the
+    // conversation they ran for. Importing them creates duplicate "shadow"
+    // conversations in the list.
+    const relayLink = stmts.getRelaySessionLink?.get?.(sdkSessionId) || null;
+    if (relayLink && text(relayLink.conversation_id) && text(relayLink.conversation_id) !== sdkSessionId) {
+      return { sdkSessionId, status: 'skipped', category: 'relay-owned', reason: 'relay-execution-session' };
+    }
+    // The SDK-engine workers (Copilot SDK, Claude, Cursor, Grok) run a
+    // conversation's turns in a CLI session that shares the conversation's OWN
+    // id — the exact equality the guard above reads as "external". A runtime
+    // binding for that conversation means the relay executes it and already
+    // owns its history: importing would overwrite relay messages with the raw
+    // runtime transcript, instruction preambles included (burn-in incident
+    // 2026-08-31: "[Relay mode: autopilot] …" surfaced as user bubbles and
+    // conversation titles after a restart). This also protects an imported
+    // conversation the user later CONTINUED in the relay — from that moment
+    // the relay's history is authoritative, not the CLI transcript.
+    const runtimeSession = stmts.getRuntimeSessionByConversation?.get?.(sdkSessionId) || null;
+    if (runtimeSession) {
+      return { sdkSessionId, status: 'skipped', category: 'relay-owned', reason: 'relay-execution-session' };
+    }
+    // Same protection when a live conversation already claims this session id
+    // as its transcript binding under a different conversation id.
+    const owningConversation = stmts.getConvBySdkSessionId?.get?.(sdkSessionId) || null;
+    if (owningConversation && text(owningConversation.id) && text(owningConversation.id) !== sdkSessionId) {
+      return { sdkSessionId, status: 'skipped', category: 'bound-elsewhere', reason: 'session-bound-to-existing-conversation' };
+    }
+    const claimed = claim(sdkSessionId, session, { force });
+    if (!claimed.claimed) return { sdkSessionId, status: 'skipped', category: claimed.category, reason: 'unchanged-or-active' };
+
+    let resumed = null;
+    try {
+      const client = await getRuntime();
+      resumed = await client.client.resumeSession(sdkSessionId, {
+        suppressResumeEvent: true,
+        availableTools: [],
+      });
+      const events = await normalizeEvents(await resumed.getEvents());
+      const messages = parseSessionEventsToMessages?.(events);
+      if (!Array.isArray(messages)) throw new Error('SDK session import returned an invalid history snapshot');
+      const existingMessageCount = Number(countConversationMessages.get(sdkSessionId)?.count || 0);
+      if (messages.length === 0 && existingMessageCount > 0) {
+        throw new Error('SDK session import returned an empty history snapshot for an existing conversation');
+      }
+      persistCompletedImport({ sdkSessionId, session, messages });
+      return { sdkSessionId, status: 'completed', category: claimed.category, messageCount: messages.length };
+    } catch (error) {
+      stmts.failSdkSessionImport.run(new Date().toISOString(), boundedError(error), sdkSessionId);
+      return { sdkSessionId, status: 'failed', category: 'failed', error: boundedError(error) };
+    } finally {
+      try { await resumed?.stop?.(); } catch {}
+      try { await resumed?.dispose?.(); } catch {}
+    }
+  }
+
+  async function runStartupImport() {
+    if (activeRun) return activeRun;
+    activeRun = (async () => {
+      const summary = {
+        listed: 0,
+        new: 0,
+        changed: 0,
+        unchanged: 0,
+        failed: 0,
+        tombstoned: 0,
+        'relay-owned': 0,
+        'bound-elsewhere': 0,
+      };
+      try {
+        stmts.resetInterruptedSdkSessionImports.run(new Date().toISOString());
+        const client = await getRuntime();
+        const sessions = await normalizeEvents(await client.client.listSessions());
+        summary.listed = sessions.length;
+        for (const session of sessions) {
+          const result = await importSession(session);
+          summary[result.category] = Number(summary[result.category] || 0) + 1;
+        }
+      } catch (error) {
+        summary.failed += 1;
+        summary.error = boundedError(error);
+      } finally {
+        activeRun = null;
+      }
+      logger.info?.(
+        `[sdk-session-import] listed=${summary.listed} new=${summary.new} changed=${summary.changed}`
+        + ` unchanged=${summary.unchanged} failed=${summary.failed} tombstoned=${summary.tombstoned}`
+        + ` relay-owned=${summary['relay-owned']} bound-elsewhere=${summary['bound-elsewhere']}`,
+      );
+      return summary;
+    })();
+    return activeRun;
+  }
+
+  async function refreshConversation(conversation) {
+    const sdkSessionId = text(conversation?.sdk_session_id || conversation?.sdkSessionId || conversation?.id);
+    if (!sdkSessionId || isTombstoned(sdkSessionId)) {
+      const error = new Error('Conversation not found');
+      error.statusCode = 404;
+      throw error;
+    }
+    return importSession({ sessionId: sdkSessionId, metadata: conversation }, { force: true });
+  }
+
+  return {
+    runStartupImport,
+    importSession,
+    refreshConversation,
+    async dispose() {
+      const current = runtime;
+      runtime = null;
+      await current?.dispose?.();
+    },
+  };
+}

package/server/services/sdk-session-sync-service.mjs

@@ -0,0 +1,207 @@
+'use strict';
+
+import { v4 as uuidv4 } from 'uuid';
+
+function normalizeId(value) {
+  return String(value || '').trim();
+}
+
+function makeError(message, statusCode) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+export function createSdkSessionSyncService(db) {
+  const runtimeSessionColumns = new Set(
+    db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((column) => String(column?.name || '').trim()),
+  );
+  const runtimeSessionsSupportProviders = runtimeSessionColumns.has('provider_type')
+    && runtimeSessionColumns.has('provider_model');
+  const providerSelect = runtimeSessionsSupportProviders
+    ? 'provider_type, provider_model'
+    : `'github' AS provider_type, NULL AS provider_model`;
+  const getConversation = db.prepare(`
+    SELECT id, sdk_session_id, status
+    FROM conversations
+    WHERE id = ?
+    LIMIT 1
+  `);
+
+  const getConversationBySdkSessionId = db.prepare(`
+    SELECT id, sdk_session_id, status
+    FROM conversations
+    WHERE sdk_session_id = ?
+      AND id != ?
+    LIMIT 1
+  `);
+
+  const getRuntimeSessionByConversation = db.prepare(`
+    SELECT id, conversation_id, sdk_session_id, status, strategy, runtime_key, model, ${providerSelect}
+    FROM runtime_sessions
+    WHERE conversation_id = ?
+    LIMIT 1
+  `);
+
+  const getRuntimeSessionBySdkSessionId = db.prepare(`
+    SELECT id, conversation_id, sdk_session_id, status, strategy, runtime_key, model, ${providerSelect}
+    FROM runtime_sessions
+    WHERE sdk_session_id = ?
+    LIMIT 1
+  `);
+
+  const updateConversationSdkSession = db.prepare(`
+    UPDATE conversations
+    SET sdk_session_id = ?, updated_at = ?
+    WHERE id = ?
+  `);
+
+  const updateRuntimeSessionSdkSession = db.prepare(`
+    UPDATE runtime_sessions
+    SET conversation_id = ?,
+        sdk_session_id = ?,
+        last_used_at = ?,
+        status = COALESCE(status, 'active')
+    WHERE id = ?
+  `);
+
+  const migrateQueueOwnerSessionId = db.prepare(`
+    UPDATE queue
+    SET owner_sdk_session_id = ?
+    WHERE status = 'pending'
+      AND owner_sdk_session_id = ?
+      AND conversation_id = ?
+  `);
+
+  const insertRuntimeSession = db.prepare(runtimeSessionsSupportProviders
+    ? `
+      INSERT INTO runtime_sessions (
+        id, conversation_id, strategy, runtime_key, model, status, created_at, last_used_at, sdk_session_id, provider_type, provider_model
+      ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, 'github', NULL)
+    `
+    : `
+      INSERT INTO runtime_sessions (
+        id, conversation_id, strategy, runtime_key, model, status, created_at, last_used_at, sdk_session_id
+      ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?)
+    `);
+
+  const syncSessionTx = db.transaction((sdkSessionIdRaw, conversationIdRaw) => {
+    const sdkSessionId = normalizeId(sdkSessionIdRaw);
+    const conversationId = normalizeId(conversationIdRaw);
+    const nowIso = new Date().toISOString();
+
+    if (!sdkSessionId || !conversationId) {
+      throw makeError('Missing sdk_session_id or conversation_id', 400);
+    }
+
+    const conversation = getConversation.get(conversationId);
+    if (!conversation || String(conversation.status || '').trim() === 'deleted') {
+      throw makeError('Conversation not found', 404);
+    }
+
+    const existingConversationSdkSessionId = normalizeId(conversation.sdk_session_id);
+    const placeholderConversationBinding = existingConversationSdkSessionId
+      && existingConversationSdkSessionId === conversationId
+      && existingConversationSdkSessionId !== sdkSessionId;
+    if (existingConversationSdkSessionId && existingConversationSdkSessionId !== sdkSessionId && !placeholderConversationBinding) {
+      throw makeError(
+        `Conversation ${conversationId} is already bound to SDK session ${existingConversationSdkSessionId}`,
+        409,
+      );
+    }
+
+    const otherConversation = getConversationBySdkSessionId.get(sdkSessionId, conversationId);
+    if (otherConversation) {
+      throw makeError(
+        `SDK session ${sdkSessionId} is already bound to conversation ${otherConversation.id}`,
+        409,
+      );
+    }
+
+    const runtimeSessionByConversation = getRuntimeSessionByConversation.get(conversationId) || null;
+    const runtimeSessionBySdkSessionId = getRuntimeSessionBySdkSessionId.get(sdkSessionId) || null;
+
+    if (runtimeSessionByConversation && runtimeSessionBySdkSessionId) {
+      const sameRuntimeSession = String(runtimeSessionByConversation.id || '') === String(runtimeSessionBySdkSessionId.id || '');
+      const sameConversation = String(runtimeSessionBySdkSessionId.conversation_id || '') === conversationId;
+      const sameSdkSession = normalizeId(runtimeSessionByConversation.sdk_session_id) === sdkSessionId;
+      const placeholderRuntimeBinding = normalizeId(runtimeSessionByConversation.sdk_session_id) === conversationId
+        && normalizeId(runtimeSessionByConversation.sdk_session_id) !== sdkSessionId;
+      if (!sameRuntimeSession && !sameConversation && !placeholderRuntimeBinding) {
+        throw makeError(
+          `SDK session ${sdkSessionId} is already bound to another runtime session`,
+          409,
+        );
+      }
+      if (!sameSdkSession && normalizeId(runtimeSessionByConversation.sdk_session_id)) {
+        throw makeError(
+          `Runtime session ${runtimeSessionByConversation.id} is already bound to SDK session ${normalizeId(runtimeSessionByConversation.sdk_session_id)}`,
+          409,
+        );
+      }
+    } else if (runtimeSessionBySdkSessionId && normalizeId(runtimeSessionBySdkSessionId.conversation_id) !== conversationId) {
+      throw makeError(
+        `SDK session ${sdkSessionId} is already bound to runtime session ${runtimeSessionBySdkSessionId.id}`,
+        409,
+      );
+    }
+
+    updateConversationSdkSession.run(sdkSessionId, nowIso, conversationId);
+    if (placeholderConversationBinding) {
+      migrateQueueOwnerSessionId.run(sdkSessionId, conversationId, conversationId);
+    }
+
+    let runtimeSessionId = null;
+    let createdRuntimeSession = false;
+
+    if (runtimeSessionByConversation) {
+      const currentSdkSessionId = normalizeId(runtimeSessionByConversation.sdk_session_id);
+      if (currentSdkSessionId && currentSdkSessionId !== sdkSessionId && currentSdkSessionId !== conversationId) {
+        throw makeError(
+          `Runtime session ${runtimeSessionByConversation.id} is already bound to SDK session ${currentSdkSessionId}`,
+          409,
+        );
+      }
+
+      updateRuntimeSessionSdkSession.run(conversationId, sdkSessionId, nowIso, runtimeSessionByConversation.id);
+      runtimeSessionId = runtimeSessionByConversation.id;
+    } else if (runtimeSessionBySdkSessionId) {
+      const currentConversationId = normalizeId(runtimeSessionBySdkSessionId.conversation_id);
+      if (currentConversationId && currentConversationId !== conversationId) {
+        throw makeError(
+          `SDK session ${sdkSessionId} is already bound to conversation ${currentConversationId}`,
+          409,
+        );
+      }
+
+      updateRuntimeSessionSdkSession.run(conversationId, sdkSessionId, nowIso, runtimeSessionBySdkSessionId.id);
+      runtimeSessionId = runtimeSessionBySdkSessionId.id;
+    } else {
+      runtimeSessionId = uuidv4();
+      createdRuntimeSession = true;
+      insertRuntimeSession.run(
+        runtimeSessionId,
+        conversationId,
+        'isolated',
+        runtimeSessionId,
+        null,
+        nowIso,
+        nowIso,
+        sdkSessionId,
+      );
+    }
+
+    return {
+      conversationId,
+      sdkSessionId,
+      runtimeSessionId,
+      createdRuntimeSession,
+    };
+  });
+
+  return {
+    syncSession({ sdk_session_id, conversation_id }) {
+      return syncSessionTx(sdk_session_id, conversation_id);
+    },
+  };
+}