@oar-sh/oar 0.9.8 → 0.9.10

package/server/cursor-worker/cursor-sdk-adapter.mjs

@@ -209,12 +209,66 @@ export function startCursorRun({
   };
   // A tool call is reported on both surfaces (the delta hook and the message
   // stream) under the same id; either one opens and closes it.
+  //
+  // Not every tool call is reported. The SDK translates only the tools it has
+  // a type for and drops the rest on both surfaces: among them the wait on a
+  // background shell (`awaitToolCall`), web fetches and input to a running
+  // shell. All a dropped call leaves is the step's `tool-requests-listed`
+  // count, sent once the model has finished requesting tools; from there the
+  // run waits for them without a single event, for as long as the command it
+  // waits on takes. So the calls listed beyond those reported count as one
+  // open tool, which closes when the model writes again: the SDK tells
+  // nothing about such a call ending, and the next step is the first sign.
+  // A step without such calls keeps the model window once its reported
+  // tools have ended. Steps are told from the delta hook alone: it carries
+  // the count, the reported calls and the model's output in step order.
+  const stepCalls = new Set();
+  let stepListed = false;
+  let unreportedCalls = 0;
+  const UNREPORTED_TOOLS = 'unreported-tools';
+  const noteCallStarted = (callId) => {
+    const key = String(callId || '').trim();
+    if (!key || stepCalls.has(key)) return;
+    stepCalls.add(key);
+    // Reported after the count: it was one of the calls counted as unreported.
+    if (stepListed && unreportedCalls > 0 && --unreportedCalls === 0) liveness.end('tool', UNREPORTED_TOOLS);
+  };
+  const noteToolsListed = (callCount) => {
+    stepListed = true;
+    unreportedCalls = Math.max(0, (Number(callCount) || 0) - stepCalls.size);
+    if (unreportedCalls > 0) liveness.begin('tool', UNREPORTED_TOOLS, 'unreported tool');
+  };
+  const noteModelWriting = () => {
+    if (!stepListed) return;
+    stepListed = false;
+    unreportedCalls = 0;
+    stepCalls.clear();
+    liveness.end('tool', UNREPORTED_TOOLS);
+  };
   const observe = (event) => {
     if (event.source === 'delta') {
       const update = event.update || {};
       liveness.traffic(update.type);
-      if (update.type === 'tool-call-started') liveness.begin('tool', update.callId, update.toolCall?.type);
-      else if (update.type === 'tool-call-completed') liveness.end('tool', update.callId);
+      switch (update.type) {
+        case 'tool-call-started':
+          noteCallStarted(update.callId);
+          liveness.begin('tool', update.callId, update.toolCall?.type);
+          break;
+        case 'tool-call-completed':
+          liveness.end('tool', update.callId);
+          break;
+        case 'tool-requests-listed':
+          noteToolsListed(update.callCount);
+          break;
+        case 'text-delta':
+        case 'thinking-delta':
+        case 'thinking-completed':
+        case 'partial-tool-call':
+          noteModelWriting();
+          break;
+        default:
+          break;
+      }
       return;
     }
     const message = event.message || {};

package/server/db-schema.mjs

@@ -13,6 +13,11 @@ import { migrateSteerSettleMarkers } from './migrations/0004-steer-settle-marker
 import { migrateRemoteRelays } from './migrations/0005-remote-relays.mjs';
 import { migrateWorkspaceRootSettings } from './migrations/0006-workspace-root-settings.mjs';
 import { migrateClaudeCloud } from './migrations/0007-claude-cloud.mjs';
+import { migrateMessagePins } from './migrations/0008-message-pins.mjs';
+import { migrateSubagentTimeline } from './migrations/0009-subagent-timeline.mjs';
+import { migrateSubagentTimelinePruning } from './migrations/0010-subagent-timeline-pruning.mjs';
+import { migrateRelayEventSubscriptions } from './migrations/0011-relay-event-subscriptions.mjs';
+import { migrateCrossRelayEventSubscriptions } from './migrations/0012-cross-relay-event-subscriptions.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -734,6 +739,45 @@ try {
 } catch (error) {
   console.warn(`[claude-cloud] migration 0007 failed; retrying on next boot: ${error?.message || error}`);
 }
+// Pinned messages: one additive column and its partial index. Readers tolerate
+// their absence (no pins), so a failure is logged and retried next boot like 0007.
+try {
+  migrateMessagePins(db);
+} catch (error) {
+  console.warn(`[message-pins] migration 0008 failed; retrying on next boot: ${error?.message || error}`);
+}
+// Sub-agent viewer: the timeline table and the run header columns. Readers
+// tolerate their absence (runs fall back to the activity, thought and stream
+// rows), so a failure is logged and retried next boot like 0008.
+try {
+  migrateSubagentTimeline(db);
+} catch (error) {
+  console.warn(`[subagent-timeline] migration 0009 failed; retrying on next boot: ${error?.message || error}`);
+}
+// Sub-agent record retention: the pruned marker and the sweep's index. The
+// sweep checks for the column and does nothing without it, so a failure is
+// logged and retried next boot like 0009.
+try {
+  migrateSubagentTimelinePruning(db);
+} catch (error) {
+  console.warn(`[subagent-timeline] migration 0010 failed; retrying on next boot: ${error?.message || error}`);
+}
+// Relay event subscriptions: two new tables. The event service checks for
+// them and stays off without them, so a failure is logged and retried next
+// boot like 0010.
+try {
+  migrateRelayEventSubscriptions(db);
+} catch (error) {
+  console.warn(`[relay-events] migration 0011 failed; retrying on next boot: ${error?.message || error}`);
+}
+// Relay event subscriptions across paired relays: columns on 0011's table and
+// the link table. Without them the event service keeps to this relay's own
+// sessions, so a failure is logged and retried next boot like 0011.
+try {
+  migrateCrossRelayEventSubscriptions(db);
+} catch (error) {
+  console.warn(`[relay-events] migration 0012 failed; retrying on next boot: ${error?.message || error}`);
+}
 
 const runtimeSessionColumns = db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((c) => c.name);
 if (runtimeSessionColumns.length) {

package/server/migrations/0008-message-pins.mjs

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Migration: pinned messages.
+ *
+ * 1. `messages.pinned_at` — when the user pinned the message (ISO time); NULL
+ *    means not pinned. A pin is a property of the message row, like
+ *    `hidden_from_shares`, so it goes away with the row.
+ * 2. `idx_messages_pinned` — a partial index over the pinned rows only: the
+ *    pin list travels with every conversation load.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0008-message-pins.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function indexExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => String(column.name)));
+}
+
+export function migrateMessagePins(db) {
+  if (!tableExists(db, 'messages')) return { applied: false, columnsAdded: 0, indexesAdded: 0 };
+  let columnsAdded = 0;
+  let indexesAdded = 0;
+  if (!columnNames(db, 'messages').has('pinned_at')) {
+    db.exec(`ALTER TABLE messages ADD COLUMN pinned_at TEXT`);
+    columnsAdded += 1;
+  }
+  if (!indexExists(db, 'idx_messages_pinned')) {
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_messages_pinned
+      ON messages(conversation_id, timestamp)
+      WHERE pinned_at IS NOT NULL
+    `);
+    indexesAdded += 1;
+  }
+  return { applied: columnsAdded + indexesAdded > 0, columnsAdded, indexesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateMessagePins(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0008 on ${dbPath}`);
+    console.log(result.applied
+      ? `  message pins: columns added ${result.columnsAdded}, indexes added ${result.indexesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0008 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0009-subagent-timeline.mjs

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Migration: sub-agent timeline.
+ *
+ * 1. `subagent_timeline` — one row per entry of a sub-agent's record (a
+ *    thought, a tool call, a tool result, reply text, a child agent, a note),
+ *    in the order the relay first saw it (`seq`, per run). A writer names each
+ *    entry with its own `entry_key`; a second write under the same key updates
+ *    the entry in place (live text, a thought that is still streaming) and
+ *    keeps its place in the order.
+ * 2. Header columns on `subagent_runs`: what the task panel shows (model,
+ *    type, tokens) and what the viewer needs to know about the run (task id,
+ *    background, whether the record was cut, who writes the timeline). The
+ *    panel's own copy lives in memory only and is gone when the task settles.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0009-subagent-timeline.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function indexExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => String(column.name)));
+}
+
+export const SUBAGENT_RUN_HEADER_COLUMNS = Object.freeze([
+  ['model', 'TEXT'],
+  ['model_inherited', 'INTEGER'],
+  ['subagent_type', 'TEXT'],
+  ['task_id', 'TEXT'],
+  ['total_tokens', 'INTEGER'],
+  ['background', 'INTEGER NOT NULL DEFAULT 0'],
+  ['truncated', 'INTEGER NOT NULL DEFAULT 0'],
+  ['timeline_owner', 'TEXT'],
+]);
+
+export function migrateSubagentTimeline(db) {
+  if (!tableExists(db, 'subagent_runs')) return { applied: false, tablesAdded: 0, columnsAdded: 0, indexesAdded: 0 };
+  let tablesAdded = 0;
+  let columnsAdded = 0;
+  let indexesAdded = 0;
+
+  const runColumns = columnNames(db, 'subagent_runs');
+  for (const [name, type] of SUBAGENT_RUN_HEADER_COLUMNS) {
+    if (runColumns.has(name)) continue;
+    db.exec(`ALTER TABLE subagent_runs ADD COLUMN ${name} ${type}`);
+    columnsAdded += 1;
+  }
+  if (!indexExists(db, 'idx_subagent_runs_parent')) {
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_subagent_runs_parent ON subagent_runs(parent_subagent_id)`);
+    indexesAdded += 1;
+  }
+
+  if (!tableExists(db, 'subagent_timeline')) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS subagent_timeline (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        run_id           TEXT NOT NULL,
+        conversation_id  TEXT NOT NULL,
+        queue_message_id TEXT,
+        entry_key        TEXT NOT NULL,
+        seq              INTEGER NOT NULL,
+        kind             TEXT NOT NULL,
+        text             TEXT,
+        tool_name        TEXT,
+        tool_use_id      TEXT,
+        metadata_json    TEXT,
+        done             INTEGER NOT NULL DEFAULT 1,
+        created_at       TEXT NOT NULL,
+        updated_at       TEXT NOT NULL,
+        UNIQUE (run_id, entry_key),
+        UNIQUE (run_id, seq),
+        FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
+      )
+    `);
+    tablesAdded += 1;
+  }
+  if (!indexExists(db, 'idx_subagent_timeline_conversation')) {
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_subagent_timeline_conversation ON subagent_timeline(conversation_id)`);
+    indexesAdded += 1;
+  }
+  return {
+    applied: tablesAdded + columnsAdded + indexesAdded > 0,
+    tablesAdded,
+    columnsAdded,
+    indexesAdded,
+  };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateSubagentTimeline(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0009 on ${dbPath}`);
+    console.log(result.applied
+      ? `  sub-agent timeline: tables added ${result.tablesAdded}, columns added ${result.columnsAdded}, indexes added ${result.indexesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0009 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0010-subagent-timeline-pruning.mjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * Migration: pruning old sub-agent records.
+ *
+ * After the retention period the relay strips a finished run's tool inputs
+ * and tool results (services/subagent-record-retention.mjs). `pruned_at`
+ * marks an entry it already stripped, and a partial index over the tool
+ * entries not stripped yet, by age, lets the daily sweep go straight to its
+ * candidates instead of reading the whole table every day.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0010-subagent-timeline-pruning.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const PRUNABLE_INDEX_NAME = 'idx_subagent_timeline_prunable';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function indexExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => String(column.name)));
+}
+
+export function migrateSubagentTimelinePruning(db) {
+  if (!tableExists(db, 'subagent_timeline')) return { applied: false, columnsAdded: 0, indexesAdded: 0 };
+  let columnsAdded = 0;
+  let indexesAdded = 0;
+  if (!columnNames(db, 'subagent_timeline').has('pruned_at')) {
+    db.exec(`ALTER TABLE subagent_timeline ADD COLUMN pruned_at TEXT`);
+    columnsAdded += 1;
+  }
+  if (!indexExists(db, PRUNABLE_INDEX_NAME)) {
+    // The sweep's WHERE repeats this condition word for word, so SQLite can
+    // use the partial index.
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS ${PRUNABLE_INDEX_NAME}
+      ON subagent_timeline(updated_at)
+      WHERE pruned_at IS NULL AND kind IN ('tool_call', 'tool_result')
+    `);
+    indexesAdded += 1;
+  }
+  return { applied: columnsAdded + indexesAdded > 0, columnsAdded, indexesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateSubagentTimelinePruning(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0010 on ${dbPath}`);
+    console.log(result.applied
+      ? `  sub-agent timeline pruning: columns added ${result.columnsAdded}, indexes added ${result.indexesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0010 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0011-relay-event-subscriptions.mjs

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Migration: relay event subscriptions.
+ *
+ * 1. `relay_event_subscriptions` — what a conversation (the watcher) asked
+ *    the relay to tell it about: which sessions (listed ids or all), which
+ *    events, one-shot or not. A row stays after it ended (`ended_at`), so
+ *    list_subscriptions can say why one is gone. `heartbeat_minutes` (NULL =
+ *    off) and `last_heartbeat_at` drive the heartbeat while work runs.
+ * 2. `relay_events` — events recorded for a watcher and not yet written into
+ *    its conversation (`delivered_at` NULL), then the ones that were, for a
+ *    couple of hours. The relay rebuilds its flush timers from the
+ *    undelivered rows at boot.
+ *
+ * `relay_id` names the relay a watched session lives on: 'self' today, a
+ * paired relay's registry id once events cross relays.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0011-relay-event-subscriptions.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateRelayEventSubscriptions(db) {
+  let tablesAdded = 0;
+  if (!tableExists(db, 'relay_event_subscriptions')) {
+    db.exec(`
+      CREATE TABLE relay_event_subscriptions (
+        id                      TEXT PRIMARY KEY,
+        watcher_conversation_id TEXT NOT NULL,
+        relay_id                TEXT NOT NULL DEFAULT 'self',
+        scope                   TEXT NOT NULL,
+        session_ids_json        TEXT,
+        events_json             TEXT NOT NULL,
+        once                    INTEGER NOT NULL DEFAULT 0,
+        match                   TEXT,
+        stalled_minutes         INTEGER NOT NULL DEFAULT 15,
+        heartbeat_minutes       INTEGER,
+        last_heartbeat_at       TEXT,
+        created_at              TEXT NOT NULL,
+        ended_at                TEXT,
+        end_reason              TEXT,
+        fired_count             INTEGER NOT NULL DEFAULT 0,
+        last_event_at           TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_subscriptions_watcher
+    ON relay_event_subscriptions(watcher_conversation_id)
+    WHERE ended_at IS NULL
+  `);
+  if (!tableExists(db, 'relay_events')) {
+    db.exec(`
+      CREATE TABLE relay_events (
+        id                      INTEGER PRIMARY KEY AUTOINCREMENT,
+        subscription_id         TEXT NOT NULL,
+        watcher_conversation_id TEXT NOT NULL,
+        relay_id                TEXT NOT NULL DEFAULT 'self',
+        session_id              TEXT NOT NULL,
+        type                    TEXT NOT NULL,
+        urgent                  INTEGER NOT NULL DEFAULT 0,
+        payload_json            TEXT NOT NULL,
+        created_at              TEXT NOT NULL,
+        delivered_at            TEXT,
+        message_id              TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_events_undelivered
+    ON relay_events(watcher_conversation_id, created_at)
+    WHERE delivered_at IS NULL
+  `);
+  // Delivered events are pruned by age (relay-event-service pruneDelivered).
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_events_delivered
+    ON relay_events(delivered_at)
+    WHERE delivered_at IS NOT NULL
+  `);
+  return { applied: tablesAdded > 0, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateRelayEventSubscriptions(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0011 on ${dbPath}`);
+    console.log(result.applied
+      ? `  relay event subscriptions: tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0011 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0012-cross-relay-event-subscriptions.mjs

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Migration: relay event subscriptions across paired relays.
+ *
+ * The watching relay (it holds the watcher) and the watched relay (it holds
+ * the sessions) both keep a row in `relay_event_subscriptions`:
+ *
+ * - On the watching relay `relay_id` is the paired relay's registry id,
+ *   `remote_subscription_id` that relay's id for the subscription,
+ *   `remote_meta_json` the watched sessions' titles, and `remote_sync` says
+ *   that an end still has to reach the other relay ('unsubscribe').
+ * - On the watched relay `subscriber_relay_id` is the watching relay's own
+ *   id (as it states it), `subscriber_watcher_id` / `_title` name its
+ *   watcher, `last_pull_at` is its last fetch and `dropped_count` the events
+ *   not kept for it since then.
+ *
+ * `relay_event_links` (watching relay): per paired relay the cursor of the
+ * events fetched there and the link's health, so a gap is noticed across
+ * restarts.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0012-cross-relay-event-subscriptions.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+const SUBSCRIPTION_COLUMNS = Object.freeze([
+  ['remote_subscription_id', 'TEXT'],
+  ['remote_meta_json', 'TEXT'],
+  ['remote_sync', 'TEXT'],
+  ['subscriber_relay_id', 'TEXT'],
+  ['subscriber_relay_name', 'TEXT'],
+  ['subscriber_watcher_id', 'TEXT'],
+  ['subscriber_watcher_title', 'TEXT'],
+  ['last_pull_at', 'TEXT'],
+  ['dropped_count', 'INTEGER NOT NULL DEFAULT 0'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateCrossRelayEventSubscriptions(db) {
+  if (!tableExists(db, 'relay_event_subscriptions')) {
+    throw new Error('relay_event_subscriptions is missing (migration 0011 has not run)');
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(relay_event_subscriptions)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  for (const [name, type] of SUBSCRIPTION_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE relay_event_subscriptions ADD COLUMN ${name} ${type}`);
+    columnsAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_subscriptions_remote
+    ON relay_event_subscriptions(relay_id, remote_subscription_id)
+    WHERE remote_subscription_id IS NOT NULL
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_subscriptions_subscriber
+    ON relay_event_subscriptions(subscriber_relay_id)
+    WHERE subscriber_relay_id IS NOT NULL
+  `);
+  let tablesAdded = 0;
+  if (!tableExists(db, 'relay_event_links')) {
+    db.exec(`
+      CREATE TABLE relay_event_links (
+        relay_id      TEXT PRIMARY KEY,
+        cursor        INTEGER NOT NULL DEFAULT 0,
+        last_ok_at    TEXT,
+        first_fail_at TEXT,
+        lost_at       TEXT,
+        last_error    TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  return { applied: columnsAdded > 0 || tablesAdded > 0, columnsAdded, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateCrossRelayEventSubscriptions(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0012 on ${dbPath}`);
+    console.log(result.applied
+      ? `  cross-relay event subscriptions: columns added ${result.columnsAdded}, tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0012 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}