create-walle 0.9.25 → 0.9.26

package/template/wall-e/brain.js

@@ -30,6 +30,7 @@ const {
 const {
   createSqliteOwnerWriteQueue,
 } = require('./shared/sqlite-owner-write-queue');
+const runtimeHealth = require('./lib/runtime-health');
 const _brainEvents = new EventEmitter();
 _brainEvents.setMaxListeners(20);
 let _stripNoise;
@@ -166,7 +167,7 @@ function _applyPersistedBackupDirSetting() {
 }
 
 // --- Schema versioning via PRAGMA user_version ---
-const SCHEMA_VERSION = 18; // Bump on every migration addition
+const SCHEMA_VERSION = 25; // Bump on every migration addition
 
 const MIGRATIONS = {
   1: (d) => {
@@ -571,6 +572,150 @@ const MIGRATIONS = {
     };
     addCol('chat_branches', 'updated_at_ms', 'INTEGER NOT NULL DEFAULT 0');
   },
+  19: (d) => {
+    d.exec(`
+      CREATE TABLE IF NOT EXISTS chat_branch_events (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        seq INTEGER NOT NULL,
+        type TEXT NOT NULL,
+        payload TEXT NOT NULL DEFAULT '{}',
+        created_at_ms INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now')),
+        UNIQUE(session_id, seq)
+      );
+      CREATE INDEX IF NOT EXISTS idx_chat_branch_events_session
+        ON chat_branch_events(session_id, seq);
+      CREATE INDEX IF NOT EXISTS idx_chat_branch_events_type
+        ON chat_branch_events(session_id, type, seq);
+
+      CREATE TABLE IF NOT EXISTS chat_branch_state (
+        session_id TEXT PRIMARY KEY,
+        state TEXT NOT NULL DEFAULT '{}',
+        updated_at_ms INTEGER NOT NULL DEFAULT 0
+      );
+    `);
+  },
+  20: (d) => {
+    // Durable parentUuid tree for the default chat: each message records the id of
+    // its parent message so the conversation is a branchable tree (the same model the
+    // session view uses), replacing the index-keyed branch blob. NULL = a root prompt.
+    const addCol = (table, col, type) => {
+      try { d.prepare(`SELECT ${col} FROM ${table} LIMIT 0`).run(); } catch (_) {
+        d.prepare(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`).run();
+      }
+    };
+    addCol('chat_messages', 'parent_uuid', 'TEXT');
+  },
+  21: (d) => {
+    // Retire the index-blob branch persistence: the default chat is now a durable
+    // parentUuid tree (chat_messages.parent_uuid) and the only mutable branch state is
+    // the head-leaf KV walle_session_head:<sid>. Drop the unused blob/event tables.
+    // (Data is reconstructable from chat_messages; the head KV survives.)
+    d.exec(`
+      DROP TABLE IF EXISTS chat_branch_state;
+      DROP TABLE IF EXISTS chat_branch_events;
+    `);
+  },
+  22: (d) => {
+    // Backfill parent_uuid for EXISTING chat_messages so an upgrading user's history
+    // renders as a tree instead of a pile of roots. The pre-tree default chat persisted
+    // only the ACTIVE path to chat_messages (it cleared + reinserted on edit; alternate
+    // branches lived in the now-dropped blob), so chaining each session's rows in
+    // insertion order exactly reproduces the user's current linear thread. Idempotent:
+    // only fills NULLs, and the first row of each session legitimately stays NULL (root).
+    backfillChatMessageParents(d);
+  },
+  23: (d) => {
+    // Corrective re-derive: an early build backfilled parent_uuid in rowid (insertion)
+    // order, which disagrees with the chat's (created_at, id) display order for same-second
+    // imported rows and produced spurious branch pagers. Re-chain every row in display
+    // order. Safe: at the tree rollout boundary the chat is still purely linear (no genuine
+    // edit-resend siblings yet), and migrations run once so post-rollout branches are never
+    // touched. A no-op for a DB whose migration 22 already used the correct order.
+    backfillChatMessageParents(d, { overwrite: true });
+  },
+  24: (d) => {
+    // Durable structured parts for Wall-E chat turns. chat_messages remains the
+    // compatibility transcript; parts persist live context/tool results in a
+    // provider-neutral shape so UI/history/model-projection do not depend on
+    // prose parsing.
+    d.exec(`
+      CREATE TABLE IF NOT EXISTS chat_message_parts (
+        id TEXT PRIMARY KEY,
+        session_id TEXT,
+        message_id TEXT,
+        parent_message_id TEXT,
+        turn_id TEXT,
+        role TEXT,
+        part_type TEXT NOT NULL,
+        tool_name TEXT,
+        status TEXT,
+        ordinal INTEGER NOT NULL DEFAULT 0,
+        title TEXT,
+        summary TEXT,
+        content TEXT,
+        data_json TEXT NOT NULL DEFAULT '{}',
+        model_projection TEXT,
+        created_at TEXT DEFAULT (datetime('now')),
+        FOREIGN KEY(message_id) REFERENCES chat_messages(id) ON DELETE CASCADE
+      );
+      CREATE INDEX IF NOT EXISTS idx_chat_message_parts_session
+        ON chat_message_parts(session_id, created_at, ordinal);
+      CREATE INDEX IF NOT EXISTS idx_chat_message_parts_message
+        ON chat_message_parts(message_id, ordinal, created_at);
+      CREATE INDEX IF NOT EXISTS idx_chat_message_parts_type
+        ON chat_message_parts(part_type, tool_name, status);
+    `);
+  },
+  25: (d) => {
+    d.exec(`
+      CREATE TABLE IF NOT EXISTS model_routing_policies (
+        id TEXT PRIMARY KEY,
+        mode TEXT NOT NULL DEFAULT 'smart',
+        cli_tail_enabled INTEGER NOT NULL DEFAULT 1,
+        finalization_fallback_enabled INTEGER NOT NULL DEFAULT 1,
+        generated_refresh_interval_ms INTEGER,
+        last_generated_at TEXT,
+        last_effective_at TEXT,
+        last_error TEXT,
+        stale_reason TEXT,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS model_routing_policy_routes (
+        policy_id TEXT NOT NULL REFERENCES model_routing_policies(id) ON DELETE CASCADE,
+        source TEXT NOT NULL,
+        route_order INTEGER NOT NULL,
+        provider_id TEXT,
+        provider_type TEXT NOT NULL,
+        runtime_type TEXT,
+        provider_name TEXT,
+        label TEXT,
+        model_registry_id TEXT,
+        model_id TEXT,
+        role TEXT,
+        candidate_source TEXT,
+        connection_kind TEXT,
+        route_policy TEXT,
+        runtime_access TEXT,
+        health_status TEXT,
+        health_json TEXT,
+        reason TEXT,
+        score REAL,
+        enabled INTEGER NOT NULL DEFAULT 1,
+        generated_at TEXT,
+        updated_at TEXT DEFAULT (datetime('now')),
+        metadata_json TEXT,
+        PRIMARY KEY(policy_id, source, route_order)
+      );
+      CREATE INDEX IF NOT EXISTS idx_model_routing_policy_routes_lookup
+        ON model_routing_policy_routes(policy_id, source, enabled, route_order);
+      CREATE INDEX IF NOT EXISTS idx_model_routing_policy_routes_provider
+        ON model_routing_policy_routes(provider_type, model_id);
+    `);
+  },
 };
 
 // Schema invariants — columns/tables that MUST exist after the named migration.
@@ -591,6 +736,11 @@ const SCHEMA_INVARIANTS = [
   { migration: 15, table: 'model_registry', column: 'source' },
   { migration: 17, table: 'model_usage_ledger', column: 'id' },
   { migration: 18, table: 'chat_branches', column: 'updated_at_ms' },
+  // (migration 19's chat_branch_events/chat_branch_state are dropped in migration 21)
+  { migration: 20, table: 'chat_messages', column: 'parent_uuid' },
+  { migration: 24, table: 'chat_message_parts', column: 'part_type' },
+  { migration: 25, table: 'model_routing_policies', column: 'id' },
+  { migration: 25, table: 'model_routing_policy_routes', column: 'policy_id' },
 ];
 
 function _columnExists(d, table, column) {
@@ -1143,7 +1293,20 @@ function enqueueOwnerWrite(labelOrFn, fnOrOptions, maybeOptions) {
   const fn = typeof labelOrFn === 'function' ? labelOrFn : fnOrOptions;
   const options = typeof labelOrFn === 'function' ? (fnOrOptions || {}) : (maybeOptions || {});
   if (typeof fn !== 'function') throw new TypeError('enqueueOwnerWrite requires a function');
-  return _getOwnerWriteQueue().enqueue(() => fn(getDb()), { ...options, label });
+  const queuedAt = Date.now();
+  return _getOwnerWriteQueue().enqueue(async () => {
+    const op = runtimeHealth.beginOperation(`brain.write.${label}`, {
+      queueWaitMs: Date.now() - queuedAt,
+    });
+    try {
+      const value = await fn(getDb());
+      op.end({ ok: true });
+      return value;
+    } catch (error) {
+      op.end({ ok: false, error });
+      throw error;
+    }
+  }, { ...options, label });
 }
 
 function getOwnerWriteQueueStatus() {
@@ -1429,6 +1592,23 @@ function createTables() {
       created_at TEXT DEFAULT (datetime('now'))
     );
 
+    CREATE TABLE IF NOT EXISTS runtime_events (
+      id TEXT PRIMARY KEY,
+      source TEXT NOT NULL,
+      event_type TEXT NOT NULL,
+      session_id TEXT,
+      channel TEXT,
+      turn_id TEXT,
+      message_id TEXT,
+      tool_name TEXT,
+      status TEXT,
+      summary TEXT,
+      duration_ms INTEGER,
+      payload_json TEXT,
+      occurred_at TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
     -- Indexes
     CREATE INDEX IF NOT EXISTS idx_memories_source ON memories(source, source_id);
     CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(memory_type, timestamp);
@@ -1461,6 +1641,9 @@ function createTables() {
 
     CREATE INDEX IF NOT EXISTS idx_exchanges_person ON agent_exchanges(person_id);
     CREATE INDEX IF NOT EXISTS idx_exchanges_remote ON agent_exchanges(remote_agent_id);
+    CREATE INDEX IF NOT EXISTS idx_runtime_events_session ON runtime_events(session_id, occurred_at);
+    CREATE INDEX IF NOT EXISTS idx_runtime_events_type ON runtime_events(event_type, occurred_at);
+    CREATE INDEX IF NOT EXISTS idx_runtime_events_tool ON runtime_events(tool_name, occurred_at);
 
     CREATE TABLE IF NOT EXISTS daily_summaries (
       id TEXT PRIMARY KEY,
@@ -1487,6 +1670,32 @@ function createTables() {
     CREATE INDEX IF NOT EXISTS idx_chat_messages_session ON chat_messages(session_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_chat_messages_time ON chat_messages(created_at);
 
+    CREATE TABLE IF NOT EXISTS chat_message_parts (
+      id TEXT PRIMARY KEY,
+      session_id TEXT,
+      message_id TEXT,
+      parent_message_id TEXT,
+      turn_id TEXT,
+      role TEXT,
+      part_type TEXT NOT NULL,
+      tool_name TEXT,
+      status TEXT,
+      ordinal INTEGER NOT NULL DEFAULT 0,
+      title TEXT,
+      summary TEXT,
+      content TEXT,
+      data_json TEXT NOT NULL DEFAULT '{}',
+      model_projection TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY(message_id) REFERENCES chat_messages(id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_chat_message_parts_session ON chat_message_parts(session_id, created_at, ordinal);
+    CREATE INDEX IF NOT EXISTS idx_chat_message_parts_message ON chat_message_parts(message_id, ordinal, created_at);
+    CREATE INDEX IF NOT EXISTS idx_chat_message_parts_type ON chat_message_parts(part_type, tool_name, status);
+
+    -- Legacy index-blob branch snapshot (pre-tree). Retained for old DBs; no longer
+    -- written. The chat_branch_state/chat_branch_events blob+event tables are retired
+    -- (tree-only branching via chat_messages.parent_uuid; head in KV) — migration 21.
     CREATE TABLE IF NOT EXISTS chat_branches (
       session_id TEXT PRIMARY KEY,
       branches TEXT NOT NULL DEFAULT '{}',
@@ -1792,6 +2001,47 @@ function createTables() {
       updated_at TEXT DEFAULT (datetime('now'))
     );
 
+    CREATE TABLE IF NOT EXISTS model_routing_policies (
+      id TEXT PRIMARY KEY,
+      mode TEXT NOT NULL DEFAULT 'smart',
+      cli_tail_enabled INTEGER NOT NULL DEFAULT 1,
+      finalization_fallback_enabled INTEGER NOT NULL DEFAULT 1,
+      generated_refresh_interval_ms INTEGER,
+      last_generated_at TEXT,
+      last_effective_at TEXT,
+      last_error TEXT,
+      stale_reason TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS model_routing_policy_routes (
+      policy_id TEXT NOT NULL REFERENCES model_routing_policies(id) ON DELETE CASCADE,
+      source TEXT NOT NULL,
+      route_order INTEGER NOT NULL,
+      provider_id TEXT,
+      provider_type TEXT NOT NULL,
+      runtime_type TEXT,
+      provider_name TEXT,
+      label TEXT,
+      model_registry_id TEXT,
+      model_id TEXT,
+      role TEXT,
+      candidate_source TEXT,
+      connection_kind TEXT,
+      route_policy TEXT,
+      runtime_access TEXT,
+      health_status TEXT,
+      health_json TEXT,
+      reason TEXT,
+      score REAL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      generated_at TEXT,
+      updated_at TEXT DEFAULT (datetime('now')),
+      metadata_json TEXT,
+      PRIMARY KEY(policy_id, source, route_order)
+    );
+
     CREATE INDEX IF NOT EXISTS idx_model_registry_provider ON model_registry(provider_id);
     CREATE INDEX IF NOT EXISTS idx_model_evaluations_model ON model_evaluations(model_registry_id);
     CREATE INDEX IF NOT EXISTS idx_model_evaluations_created ON model_evaluations(created_at);
@@ -1804,6 +2054,10 @@ function createTables() {
     CREATE INDEX IF NOT EXISTS idx_model_usage_ledger_registry ON model_usage_ledger(model_registry_id, occurred_at);
     CREATE INDEX IF NOT EXISTS idx_agent_runner_eval_runner ON agent_runner_evaluations(runner_id, task_type);
     CREATE INDEX IF NOT EXISTS idx_agent_runner_eval_created ON agent_runner_evaluations(created_at);
+    CREATE INDEX IF NOT EXISTS idx_model_routing_policy_routes_lookup
+      ON model_routing_policy_routes(policy_id, source, enabled, route_order);
+    CREATE INDEX IF NOT EXISTS idx_model_routing_policy_routes_provider
+      ON model_routing_policy_routes(provider_type, model_id);
 
     -- Benchmark evaluation runs
     CREATE TABLE IF NOT EXISTS eval_benchmark_runs (
@@ -3266,24 +3520,288 @@ function listExchanges({ limit } = {}) {
   return getDb().prepare(sql).all();
 }
 
+// -- Runtime Event Ledger --
+
+const RUNTIME_EVENT_TEXT_LIMIT = 240;
+const RUNTIME_EVENT_PAYLOAD_LIMIT = 2000;
+
+function _safeRuntimeText(value, limit = RUNTIME_EVENT_TEXT_LIMIT) {
+  if (value == null) return null;
+  return String(value)
+    .replace(/\/Users\/[^/\s]+/g, '/Users/<user>')
+    .replace(/[A-Za-z]:\\Users\\[^\\\s]+/g, 'C:\\Users\\<user>')
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<uuid>')
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '<email>')
+    .slice(0, limit);
+}
+
+function _safeRuntimeDuration(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(0, Math.trunc(n)) : null;
+}
+
+function _runtimeEventPayload(event = {}) {
+  const payload = {};
+  const scalarKeys = [
+    'provider',
+    'model',
+    'reason',
+    'route',
+    'attempt',
+    'turn',
+    'progressId',
+    'approvalId',
+    'runtimeProfile',
+  ];
+  for (const key of scalarKeys) {
+    const value = event[key];
+    if (value == null) continue;
+    if (typeof value === 'number' || typeof value === 'boolean') {
+      payload[key] = value;
+    } else if (typeof value === 'string') {
+      payload[key] = _safeRuntimeText(value, 160);
+    }
+  }
+  if (event.detail && typeof event.detail === 'object') {
+    const detail = {};
+    for (const key of ['tool', 'status', 'kind', 'phase']) {
+      if (event.detail[key] != null) detail[key] = _safeRuntimeText(event.detail[key], 120);
+    }
+    if (Object.keys(detail).length) payload.detail = detail;
+  }
+  let text = JSON.stringify(payload);
+  if (text.length > RUNTIME_EVENT_PAYLOAD_LIMIT) {
+    text = JSON.stringify({ truncated: true, size: text.length });
+  }
+  return text === '{}' ? null : text;
+}
+
+function appendRuntimeEvent(event = {}, dbHandle = null) {
+  const d = dbHandle || getDb();
+  const id = event.id || uuidv4();
+  const eventType = _safeRuntimeText(event.event_type || event.type || 'event', 80) || 'event';
+  const source = _safeRuntimeText(event.source || 'wall-e', 80) || 'wall-e';
+  const occurredAt = event.occurred_at || new Date().toISOString();
+  const toolName = _safeRuntimeText(event.tool_name || event.tool || event.toolName || event.detail?.tool, 120);
+  const summary = _safeRuntimeText(event.summary || event.message || event.title, RUNTIME_EVENT_TEXT_LIMIT);
+  const status = _safeRuntimeText(event.status || event.state, 80);
+  const durationMs = _safeRuntimeDuration(event.duration_ms ?? event.durationMs ?? event.elapsedMs);
+  const payloadJson = _runtimeEventPayload(event);
+  d.prepare(`
+    INSERT INTO runtime_events (
+      id, source, event_type, session_id, channel, turn_id, message_id,
+      tool_name, status, summary, duration_ms, payload_json, occurred_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    source,
+    eventType,
+    _safeRuntimeText(event.session_id || event.sessionId, 120),
+    _safeRuntimeText(event.channel, 80),
+    _safeRuntimeText(event.turn_id || event.turnId, 120),
+    _safeRuntimeText(event.message_id || event.messageId, 120),
+    toolName,
+    status,
+    summary,
+    durationMs,
+    payloadJson,
+    occurredAt
+  );
+  return { id };
+}
+
+function listRuntimeEvents({ session_id, channel, event_type, tool_name, limit } = {}) {
+  const params = [];
+  const conditions = [];
+  if (session_id) { conditions.push('session_id = ?'); params.push(session_id); }
+  if (channel) { conditions.push('channel = ?'); params.push(channel); }
+  if (event_type) { conditions.push('event_type = ?'); params.push(event_type); }
+  if (tool_name) { conditions.push('tool_name = ?'); params.push(tool_name); }
+  const lim = Math.min(Math.max(Number(limit) || 100, 1), 1000);
+  params.push(lim);
+  const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+  return getDb().prepare(`
+    SELECT * FROM runtime_events
+    ${where}
+    ORDER BY occurred_at DESC, created_at DESC
+    LIMIT ?
+  `).all(...params);
+}
+
 // ── Chat Messages ──
 
-function insertChatMessage({ role, content, channel, session_id, id, attachments, model_id, model_provider }) {
+function insertChatMessage({ role, content, channel, session_id, id, parent_uuid, attachments, model_id, model_provider }) {
   const messageId = id || uuidv4();
   const attachmentsJson = attachments
     ? (typeof attachments === 'string' ? attachments : JSON.stringify(attachments))
     : null;
+  // parent_uuid threads the durable branch tree (the same model the session view uses):
+  // each message points at the message it follows. When the caller doesn't specify one,
+  // default to the session's current newest message (linear append). An explicit value
+  // (incl. null for a root, or a prior message's id for an edit-resend sibling) wins.
+  const parentUuid = parent_uuid !== undefined
+    ? (parent_uuid || null)
+    : _latestChatMessageId(session_id);
+  // INSERT OR REPLACE keeps a client-minted id idempotent (a re-sent same-id is a no-op
+  // update, not a duplicate) — append-only with stable identity, no destructive re-sync.
   // model_id / model_provider record which model produced an assistant turn so the
-  // conversation log / token badge can attribute it. Columns exist (migrations 84-85)
-  // but were never written; null-coalesced so user/system rows stay NULL.
+  // conversation log / token badge can attribute it.
   getDb().prepare(`
-    INSERT INTO chat_messages (id, role, content, channel, session_id, attachments, model_id, model_provider, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+    INSERT OR REPLACE INTO chat_messages (id, role, content, channel, session_id, parent_uuid, attachments, model_id, model_provider, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
   `).run(
-    messageId, role, content, channel || 'ctm', session_id || null, attachmentsJson,
+    messageId, role, content, channel || 'ctm', session_id || null, parentUuid, attachmentsJson,
     model_id || null, model_provider || null,
   );
-  return { id: messageId };
+  return { id: messageId, parent_uuid: parentUuid };
+}
+
+// Chain each session's messages by their parent_uuid in the SAME order the chat displays
+// them — listChatMessages renders by (created_at ASC, id ASC), so the tree MUST chain in
+// that order too, or the edges contradict the visual order and buildMessageTree's bridge
+// invents a spurious fork (observed on real imported data whose rowid order ≠ created_at
+// order for same-second rows). Each row points at its display-predecessor; the first
+// displayed row of a session stays NULL = a root.
+//
+// Default (overwrite:false) only fills NULLs — the one-time forward backfill for upgraders
+// whose rows have no parent yet; idempotent and safe to re-run. overwrite:true re-derives
+// EVERY row's parent — a corrective pass for a DB that was backfilled in the wrong order
+// before this fix. Overwrite is only safe at the tree rollout boundary, where the chat is
+// still purely linear (no genuine edit-resend siblings exist yet); migrations run once, so
+// branches created AFTER the rollout are never touched. Pass the migrating db handle, or
+// omit to use the live db.
+function backfillChatMessageParents(db, { overwrite = false } = {}) {
+  const d = db || getDb();
+  // overwrite: re-derive EVERY row (the display-first row of each session is reset to NULL =
+  // root). Default: only fill rows that are still NULL and have a display-predecessor (the
+  // first row legitimately stays NULL, so it is left untouched).
+  const where = overwrite
+    ? ''
+    : 'WHERE parent_uuid IS NULL AND (SELECT prev_id FROM ordered o WHERE o.id = chat_messages.id) IS NOT NULL';
+  d.exec(`
+    WITH ordered AS (
+      SELECT id, LAG(id) OVER (PARTITION BY session_id ORDER BY created_at ASC, id ASC) AS prev_id
+      FROM chat_messages
+    )
+    UPDATE chat_messages
+    SET parent_uuid = (SELECT prev_id FROM ordered o WHERE o.id = chat_messages.id)
+    ${where};
+  `);
+}
+
+// The newest message id for a session (its current head), used as the default parent
+// for a linearly-appended message. Orders by the implicit rowid (true insertion order):
+// a new send always has the max rowid AND the max created_at, so this returns the row the
+// user sees last — and unlike (created_at, id) it is immune to the same-second tiebreak
+// where a user's 'umsg-…' id sorts above the assistant's hex uuid (which would wrongly
+// make the user the head and fork the next turn). The one-time historical backfill, by
+// contrast, must follow the DISPLAY order — see backfillChatMessageParents.
+// Returns null when the session has no messages yet.
+function _latestChatMessageId(session_id) {
+  if (!session_id) return null;
+  const row = getDb().prepare(
+    'SELECT id FROM chat_messages WHERE session_id = ? ORDER BY rowid DESC LIMIT 1'
+  ).get(session_id);
+  return row ? row.id : null;
+}
+
+function _jsonString(value) {
+  if (typeof value === 'string') return value;
+  try { return JSON.stringify(value == null ? {} : value); } catch (_) { return '{}'; }
+}
+
+function _jsonValue(value, fallback) {
+  if (value == null || value === '') return fallback;
+  if (typeof value !== 'string') return value;
+  try { return JSON.parse(value); } catch (_) { return fallback; }
+}
+
+function _nextChatPartOrdinal({ message_id, session_id }) {
+  const db = getDb();
+  if (message_id) {
+    const row = db.prepare(
+      'SELECT COALESCE(MAX(ordinal) + 1, 0) AS next FROM chat_message_parts WHERE message_id = ?'
+    ).get(message_id);
+    return row?.next || 0;
+  }
+  if (session_id) {
+    const row = db.prepare(
+      'SELECT COALESCE(MAX(ordinal) + 1, 0) AS next FROM chat_message_parts WHERE session_id = ? AND message_id IS NULL'
+    ).get(session_id);
+    return row?.next || 0;
+  }
+  return 0;
+}
+
+function _hydrateChatPart(row) {
+  if (!row) return null;
+  return {
+    ...row,
+    data: _jsonValue(row.data_json, {}),
+  };
+}
+
+function insertChatMessagePart({
+  id,
+  session_id,
+  message_id,
+  parent_message_id,
+  turn_id,
+  role,
+  part_type,
+  tool_name,
+  status,
+  ordinal,
+  title,
+  summary,
+  content,
+  data,
+  data_json,
+  model_projection,
+}) {
+  const partType = String(part_type || '').trim();
+  if (!partType) throw new Error('Chat message part requires part_type');
+  const partId = id || uuidv4();
+  const ord = Number.isInteger(ordinal)
+    ? ordinal
+    : _nextChatPartOrdinal({ message_id, session_id });
+  getDb().prepare(`
+    INSERT OR REPLACE INTO chat_message_parts (
+      id, session_id, message_id, parent_message_id, turn_id, role, part_type,
+      tool_name, status, ordinal, title, summary, content, data_json,
+      model_projection, created_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+  `).run(
+    partId,
+    session_id || null,
+    message_id || null,
+    parent_message_id || null,
+    turn_id || null,
+    role || null,
+    partType,
+    tool_name || null,
+    status || null,
+    ord,
+    title || null,
+    summary || null,
+    content || null,
+    data_json != null ? _jsonString(data_json) : _jsonString(data),
+    model_projection || null,
+  );
+  return { id: partId, ordinal: ord };
+}
+
+function listChatMessageParts({ session_id, message_id, limit } = {}) {
+  const params = [];
+  let where = ' WHERE 1=1';
+  if (session_id) { where += ' AND session_id = ?'; params.push(session_id); }
+  if (message_id) { where += ' AND message_id = ?'; params.push(message_id); }
+  const lim = limit ? Math.min(Math.max(Number(limit) || 0, 1), 1000) : 0;
+  const sql = `SELECT * FROM chat_message_parts${where} ORDER BY created_at ASC, ordinal ASC, id ASC${lim ? ' LIMIT ?' : ''}`;
+  if (lim) params.push(lim);
+  return getDb().prepare(sql).all(...params).map(_hydrateChatPart).filter(Boolean);
 }
 
 function listChatMessages({ session_id, channel, limit } = {}) {
@@ -3302,6 +3820,26 @@ function listChatMessages({ session_id, channel, limit } = {}) {
   return getDb().prepare(`SELECT * FROM chat_messages${where} ORDER BY created_at ASC, id ASC`).all(...params);
 }
 
+function listChatMessagesWithParts({ session_id, channel, limit } = {}) {
+  const rows = listChatMessages({ session_id, channel, limit });
+  if (rows.length === 0) return rows;
+  const messageIds = rows.map((r) => r.id).filter(Boolean);
+  if (messageIds.length === 0) return rows.map((r) => ({ ...r, parts: [] }));
+  const placeholders = messageIds.map(() => '?').join(',');
+  const parts = getDb().prepare(`
+    SELECT * FROM chat_message_parts
+    WHERE message_id IN (${placeholders})
+    ORDER BY created_at ASC, ordinal ASC, id ASC
+  `).all(...messageIds).map(_hydrateChatPart).filter(Boolean);
+  const byMessage = new Map();
+  for (const part of parts) {
+    const key = part.message_id || '';
+    if (!byMessage.has(key)) byMessage.set(key, []);
+    byMessage.get(key).push(part);
+  }
+  return rows.map((row) => ({ ...row, parts: byMessage.get(row.id) || [] }));
+}
+
 function searchChatMessages({ query, limit } = {}) {
   if (!query || !query.trim()) return [];
   const terms = query.trim().split(/\s+/).filter(Boolean);
@@ -3329,35 +3867,16 @@ function deleteChatMessages({ session_id, user_content, assistant_content }) {
 }
 
 function clearChatSession(session_id) {
-  getDb().prepare('DELETE FROM chat_messages WHERE session_id = ?').run(session_id);
-}
-
-// ── Chat Branches (ChatGPT-style edit/resend) ──
-
-function saveChatBranches(session_id, branches, active, history, updated_at_ms) {
-  const updatedAtMs = Number.isFinite(Number(updated_at_ms)) && Number(updated_at_ms) > 0
-    ? Math.floor(Number(updated_at_ms))
-    : Date.now();
-  getDb().prepare(`
-    INSERT INTO chat_branches (session_id, branches, active, history, updated_at_ms)
-    VALUES (?, ?, ?, ?, ?)
-    ON CONFLICT(session_id) DO UPDATE SET branches = excluded.branches, active = excluded.active, history = excluded.history, updated_at_ms = excluded.updated_at_ms
-  `).run(session_id, JSON.stringify(branches), JSON.stringify(active), JSON.stringify(history || []), updatedAtMs);
+  const db = getDb();
+  runImmediateTransaction(db, (targetSessionId) => {
+    db.prepare('DELETE FROM chat_message_parts WHERE session_id = ?').run(targetSessionId);
+    db.prepare('DELETE FROM chat_messages WHERE session_id = ?').run(targetSessionId);
+  }, session_id);
 }
 
-function loadChatBranches(session_id) {
-  const row = getDb().prepare('SELECT branches, active, history, updated_at_ms FROM chat_branches WHERE session_id = ?').get(session_id);
-  if (!row) return { branches: {}, active: {}, history: [], exists: false };
-  try {
-    return {
-      branches: JSON.parse(row.branches),
-      active: JSON.parse(row.active),
-      history: JSON.parse(row.history || '[]'),
-      updated_at_ms: Number(row.updated_at_ms || 0) || 0,
-      exists: true,
-    };
-  } catch (e) { return { branches: {}, active: {}, history: [], exists: true }; }
-}
+// ── Chat Branches ── (retired: the conversation is a durable parentUuid tree built
+// from chat_messages.parent_uuid; the only persisted branch state is the head-leaf
+// KV walle_session_head:<sid>. The index-blob tables are dropped in migration 21.)
 
 // -- Skills CRUD --
 
@@ -4499,6 +5018,10 @@ function _normalizeUsageTokens({ usage, inputTokens, outputTokens, cachedInputTo
       ?? raw.cached_input
       ?? raw.cachedInput
       ?? raw.cached_input_tokens
+      ?? raw.cache_read_input_tokens
+      ?? raw.cacheReadInputTokens
+      ?? raw.cache_read
+      ?? raw.cacheRead
       ?? raw.prompt_tokens_details?.cached_tokens
   );
   const reasoning = _nonNegativeInteger(
@@ -4648,7 +5171,7 @@ function recordModelUsage({
       modelId,
       modelRegistryId,
       inputTokens: tokens.inputTokens,
-      outputTokens: tokens.outputTokens,
+      outputTokens: tokens.outputTokens + tokens.reasoningOutputTokens,
     })
     : {
       costUsd: explicitCost,
@@ -4786,6 +5309,172 @@ function summarizeModelUsageLedger(filters = {}) {
   return rows;
 }
 
+function _compactUsageTokens(n) {
+  const v = Math.max(0, Math.round(Number(n) || 0));
+  if (v < 1000) return String(v);
+  if (v < 1_000_000) {
+    const k = v / 1000;
+    return (k < 10 ? k.toFixed(1) : Math.round(k)) + 'k';
+  }
+  const m = v / 1_000_000;
+  return (m < 10 ? m.toFixed(1) : Math.round(m)) + 'M';
+}
+
+function _ledgerCountedTokens(row) {
+  if (!row) return 0;
+  const input = _nonNegativeInteger(row.input_tokens);
+  const cached = _nonNegativeInteger(row.cached_input_tokens);
+  const output = _nonNegativeInteger(row.output_tokens);
+  const reasoning = _nonNegativeInteger(row.reasoning_output_tokens);
+  return Math.max(0, input - cached) + output + reasoning;
+}
+
+function _usageRouteLabel(row) {
+  const provider = String(row?.provider_type || row?.provider_id || '').trim();
+  const model = String(row?.model_id || row?.model_registry_id || '').trim();
+  if (provider && model) return `${provider} / ${model}`;
+  return model || provider || 'unknown route';
+}
+
+function _modelContextWindowForUsageRow(row) {
+  const registry = findModelRegistryForUsage({
+    providerType: row?.provider_type,
+    providerId: row?.provider_id,
+    modelId: row?.model_id,
+    modelRegistryId: row?.model_registry_id,
+  });
+  return _nonNegativeInteger(registry?.max_context_tokens || registry?.context_window || registry?.contextWindow);
+}
+
+function summarizeSessionModelUsage({ sessionId } = {}) {
+  const id = String(sessionId || '').trim();
+  if (!id) return null;
+  const db = getDb();
+  const tokenWhere = `
+    session_id = ?
+    AND (
+      input_tokens > 0
+      OR output_tokens > 0
+      OR total_tokens > 0
+      OR cached_input_tokens > 0
+      OR reasoning_output_tokens > 0
+    )
+  `;
+  const grouped = db.prepare(`
+    SELECT
+      provider_type,
+      provider_id,
+      model_id,
+      model_registry_id,
+      gateway_type,
+      route_label,
+      COUNT(*) AS calls,
+      SUM(input_tokens) AS input_tokens,
+      SUM(output_tokens) AS output_tokens,
+      SUM(total_tokens) AS raw_total_tokens,
+      SUM(cached_input_tokens) AS cached_input_tokens,
+      SUM(reasoning_output_tokens) AS reasoning_output_tokens,
+      SUM(cost_usd) AS cost_usd,
+      SUM(CASE WHEN cost_usd IS NULL THEN 1 ELSE 0 END) AS missing_cost_rows,
+      MIN(occurred_at) AS first_seen_at,
+      MAX(occurred_at) AS last_seen_at
+    FROM model_usage_ledger
+    WHERE ${tokenWhere}
+    GROUP BY provider_type, provider_id, model_id, model_registry_id, gateway_type, route_label
+    ORDER BY datetime(last_seen_at) DESC, provider_type, model_id
+  `).all(id);
+  if (!grouped.length) return null;
+
+  const latest = db.prepare(`
+    SELECT *
+    FROM model_usage_ledger
+    WHERE ${tokenWhere}
+    ORDER BY datetime(occurred_at) DESC, id DESC
+    LIMIT 1
+  `).get(id) || null;
+
+  let totalTokens = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cachedInputTokens = 0;
+  let reasoningOutputTokens = 0;
+  let calls = 0;
+  let costUsd = 0;
+  let hasCost = false;
+  let missingCostRows = 0;
+  const routes = grouped.map((row) => {
+    const routeTotal = _ledgerCountedTokens(row);
+    const rowCost = _finiteNumberOrNull(row.cost_usd);
+    const rowMissingCost = _nonNegativeInteger(row.missing_cost_rows);
+    totalTokens += routeTotal;
+    inputTokens += _nonNegativeInteger(row.input_tokens);
+    outputTokens += _nonNegativeInteger(row.output_tokens);
+    cachedInputTokens += _nonNegativeInteger(row.cached_input_tokens);
+    reasoningOutputTokens += _nonNegativeInteger(row.reasoning_output_tokens);
+    calls += _nonNegativeInteger(row.calls);
+    missingCostRows += rowMissingCost;
+    if (rowCost != null) {
+      hasCost = true;
+      costUsd += rowCost;
+    }
+    return {
+      provider_type: row.provider_type || null,
+      provider_id: row.provider_id || null,
+      model_id: row.model_id || null,
+      model_registry_id: row.model_registry_id || null,
+      gateway_type: row.gateway_type || null,
+      route_label: row.route_label || _usageRouteLabel(row),
+      calls: _nonNegativeInteger(row.calls),
+      total_tokens: routeTotal,
+      raw_total_tokens: _nonNegativeInteger(row.raw_total_tokens),
+      input_tokens: _nonNegativeInteger(row.input_tokens),
+      output_tokens: _nonNegativeInteger(row.output_tokens),
+      cached_input_tokens: _nonNegativeInteger(row.cached_input_tokens),
+      reasoning_output_tokens: _nonNegativeInteger(row.reasoning_output_tokens),
+      cost_usd: rowCost,
+      missing_cost_rows: rowMissingCost,
+      first_seen_at: row.first_seen_at || null,
+      last_seen_at: row.last_seen_at || null,
+    };
+  });
+
+  const latestContextTokens = latest
+    ? Math.max(
+      _nonNegativeInteger(latest.total_tokens),
+      _nonNegativeInteger(latest.input_tokens) + _nonNegativeInteger(latest.output_tokens) + _nonNegativeInteger(latest.reasoning_output_tokens),
+    )
+    : 0;
+  const contextWindow = latest ? _modelContextWindowForUsageRow(latest) : 0;
+  const contextPct = contextWindow > 0
+    ? Math.round((Math.min(latestContextTokens, contextWindow) / contextWindow) * 100)
+    : 0;
+
+  return {
+    session_id: id,
+    source: 'walle-ledger',
+    exact: true,
+    calls,
+    total_tokens: totalTokens,
+    label: _compactUsageTokens(totalTokens),
+    context_tokens: latestContextTokens,
+    latest_context_tokens: latestContextTokens,
+    context_window: contextWindow,
+    context_pct: contextPct,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cached_input_tokens: cachedInputTokens,
+    reasoning_output_tokens: reasoningOutputTokens,
+    cost_usd: hasCost ? costUsd : null,
+    missing_cost_rows: missingCostRows,
+    latest_provider_type: latest?.provider_type || null,
+    latest_provider_id: latest?.provider_id || null,
+    latest_model_id: latest?.model_id || null,
+    latest_model_registry_id: latest?.model_registry_id || null,
+    latest_at: latest?.occurred_at || null,
+    routes,
+  };
+}
+
 // -- Model Evaluations --
 
 function getEvaluationDaysCutoff(days) {
@@ -4823,6 +5512,43 @@ function getModelScorecard(modelRegistryId, days = 30) {
   `).get(...params);
 }
 
+// Batched scorecard: one GROUP BY for ALL models instead of N per-model queries
+// (the scorecard tab has thousands of models). Returns a Map keyed by
+// model_registry_id with the SAME column shape as getModelScorecard(); callers
+// fill missing models with emptyModelScorecardStats().
+function getModelScorecardsBatch(days = 30) {
+  const cutoff = getEvaluationDaysCutoff(days);
+  const where = cutoff ? 'WHERE created_at >= ?' : '';
+  const params = cutoff ? [cutoff] : [];
+  const rows = getDb().prepare(`
+    SELECT
+      model_registry_id AS id,
+      COUNT(*) AS total_evals,
+      AVG(quality_score) AS avg_quality,
+      AVG(latency_ms) AS avg_latency_ms,
+      SUM(cost_estimate) AS total_cost,
+      SUM(CASE WHEN was_selected = 1 THEN 1 ELSE 0 END) AS wins
+    FROM model_evaluations
+    ${where}
+    GROUP BY model_registry_id
+  `).all(...params);
+  const map = new Map();
+  for (const row of rows) {
+    const id = row.id;
+    delete row.id;
+    map.set(id, row);
+  }
+  return map;
+}
+
+// Zero row matching what getModelScorecard returns for a model with no evals
+// (SQLite aggregates over zero rows: COUNT=0, AVG/SUM=null).
+function emptyModelScorecardStats() {
+  // Matches getModelScorecard() over zero rows exactly: COUNT=0, all SUM/AVG=null
+  // (SQLite SUM over no rows is NULL, not 0).
+  return { total_evals: 0, avg_quality: null, avg_latency_ms: null, total_cost: null, wins: null };
+}
+
 function getModelScorecardForTask(modelRegistryId, taskType, days = 30) {
   const cutoff = getEvaluationDaysCutoff(days);
   let where = 'model_registry_id = ? AND task_type = ?';
@@ -4959,6 +5685,276 @@ function listModelDefaults() {
   `).all();
 }
 
+// -- Model Routing Policy --
+
+const DEFAULT_MODEL_ROUTING_POLICY_ID = 'default';
+const VALID_MODEL_ROUTING_ROUTE_SOURCES = new Set(['user', 'generated', 'effective']);
+
+function _normalizeModelRoutingPolicyId(policyId) {
+  const id = String(policyId || DEFAULT_MODEL_ROUTING_POLICY_ID).trim();
+  return id || DEFAULT_MODEL_ROUTING_POLICY_ID;
+}
+
+function _boolToInt(value, fallback = true) {
+  if (value === undefined || value === null || value === '') return fallback ? 1 : 0;
+  return value === false || value === 0 || value === '0' || String(value).toLowerCase() === 'false' ? 0 : 1;
+}
+
+function _routingPolicySettingsFromKv() {
+  const rawMode = String(getKv('model_routing_policy_mode') || 'smart').trim().toLowerCase();
+  const mode = rawMode === 'strict' ? 'strict' : 'smart';
+  return {
+    mode,
+    cliTailEnabled: _boolToInt(getKv('model_routing_policy_cli_tail'), true),
+    finalizationFallbackEnabled: _boolToInt(getKv('model_routing_policy_finalization_fallback'), true),
+    lastGeneratedAt: getKv('model_routing_policy_last_refresh_at') || null,
+  };
+}
+
+function _modelRoutingPolicyRowToPublic(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    mode: row.mode || 'smart',
+    fallback_enabled: (row.mode || 'smart') !== 'strict',
+    cli_tail: row.cli_tail_enabled !== 0,
+    finalization_fallback: row.finalization_fallback_enabled !== 0,
+    generated_refresh_interval_ms: row.generated_refresh_interval_ms == null ? null : Number(row.generated_refresh_interval_ms),
+    last_generated_at: row.last_generated_at || null,
+    last_effective_at: row.last_effective_at || null,
+    last_error: row.last_error || null,
+    stale_reason: row.stale_reason || null,
+    created_at: row.created_at || null,
+    updated_at: row.updated_at || null,
+  };
+}
+
+function ensureModelRoutingPolicy(policyId = DEFAULT_MODEL_ROUTING_POLICY_ID) {
+  const id = _normalizeModelRoutingPolicyId(policyId);
+  const legacy = _routingPolicySettingsFromKv();
+  getDb().prepare(`
+    INSERT OR IGNORE INTO model_routing_policies
+      (id, mode, cli_tail_enabled, finalization_fallback_enabled, last_generated_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, datetime('now'))
+  `).run(
+    id,
+    legacy.mode,
+    legacy.cliTailEnabled,
+    legacy.finalizationFallbackEnabled,
+    legacy.lastGeneratedAt
+  );
+  return _modelRoutingPolicyRowToPublic(getDb().prepare('SELECT * FROM model_routing_policies WHERE id = ?').get(id));
+}
+
+function updateModelRoutingPolicy(policyId = DEFAULT_MODEL_ROUTING_POLICY_ID, patch = {}) {
+  const id = _normalizeModelRoutingPolicyId(policyId);
+  ensureModelRoutingPolicy(id);
+  const current = getDb().prepare('SELECT * FROM model_routing_policies WHERE id = ?').get(id);
+  const next = {
+    mode: patch.mode === undefined ? current.mode : String(patch.mode || 'smart').trim().toLowerCase(),
+    cliTailEnabled: patch.cli_tail === undefined && patch.cliTail === undefined
+      ? current.cli_tail_enabled
+      : _boolToInt(patch.cli_tail === undefined ? patch.cliTail : patch.cli_tail, true),
+    finalizationFallbackEnabled: patch.finalization_fallback === undefined && patch.finalizationFallback === undefined
+      ? current.finalization_fallback_enabled
+      : _boolToInt(patch.finalization_fallback === undefined ? patch.finalizationFallback : patch.finalization_fallback, true),
+    generatedRefreshIntervalMs: patch.generated_refresh_interval_ms === undefined
+      ? current.generated_refresh_interval_ms
+      : patch.generated_refresh_interval_ms,
+    lastGeneratedAt: patch.last_generated_at === undefined ? current.last_generated_at : patch.last_generated_at,
+    lastEffectiveAt: patch.last_effective_at === undefined ? current.last_effective_at : patch.last_effective_at,
+    lastError: patch.last_error === undefined ? current.last_error : patch.last_error,
+    staleReason: patch.stale_reason === undefined ? current.stale_reason : patch.stale_reason,
+  };
+  if (!['smart', 'strict'].includes(next.mode)) next.mode = 'smart';
+  getDb().prepare(`
+    UPDATE model_routing_policies
+    SET mode = ?,
+        cli_tail_enabled = ?,
+        finalization_fallback_enabled = ?,
+        generated_refresh_interval_ms = ?,
+        last_generated_at = ?,
+        last_effective_at = ?,
+        last_error = ?,
+        stale_reason = ?,
+        updated_at = datetime('now')
+    WHERE id = ?
+  `).run(
+    next.mode,
+    next.cliTailEnabled,
+    next.finalizationFallbackEnabled,
+    next.generatedRefreshIntervalMs == null ? null : Number(next.generatedRefreshIntervalMs),
+    next.lastGeneratedAt || null,
+    next.lastEffectiveAt || null,
+    next.lastError || null,
+    next.staleReason || null,
+    id
+  );
+  // Mirror the legacy KV contract while client/chat code transitions to the
+  // policy row. Existing scripts that read these keys keep working.
+  setKv('model_routing_policy_mode', next.mode);
+  setKv('model_routing_policy_cli_tail', next.cliTailEnabled ? '1' : '0');
+  setKv('model_routing_policy_finalization_fallback', next.finalizationFallbackEnabled ? '1' : '0');
+  if (next.lastGeneratedAt) setKv('model_routing_policy_last_refresh_at', next.lastGeneratedAt);
+  return ensureModelRoutingPolicy(id);
+}
+
+function _safeParseModelRoutingJson(raw, fallback) {
+  if (!raw) return fallback;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed == null ? fallback : parsed;
+  } catch {
+    return fallback;
+  }
+}
+
+function _modelRoutingRouteRowToPublic(row) {
+  const health = _safeParseModelRoutingJson(row.health_json, null);
+  const metadata = _safeParseModelRoutingJson(row.metadata_json, {});
+  return {
+    policy_id: row.policy_id,
+    policy_source: row.source,
+    order: row.route_order,
+    provider_id: row.provider_id || null,
+    provider_type: row.provider_type || null,
+    runtime_type: row.runtime_type || row.provider_type || null,
+    provider_name: row.provider_name || null,
+    label: row.label || row.provider_name || row.provider_type || null,
+    model_registry_id: row.model_registry_id || null,
+    model: row.model_id || null,
+    model_id: row.model_id || null,
+    role: row.role || (row.route_order === 1 ? 'primary' : 'fallback'),
+    source: row.candidate_source || null,
+    connection_kind: row.connection_kind || null,
+    route_policy: row.route_policy || null,
+    runtime_access: row.runtime_access || null,
+    health_status: row.health_status || (health && health.status) || null,
+    health: health || (row.health_status ? { status: row.health_status } : null),
+    reason: row.reason || metadata.reason || metadata.excluded_reason || '',
+    score: row.score == null ? null : Number(row.score),
+    enabled: row.enabled !== 0,
+    generated_at: row.generated_at || null,
+    updated_at: row.updated_at || null,
+    metadata,
+  };
+}
+
+function listModelRoutingPolicyRoutes(policyId = DEFAULT_MODEL_ROUTING_POLICY_ID, source = null) {
+  const id = _normalizeModelRoutingPolicyId(policyId);
+  ensureModelRoutingPolicy(id);
+  const normalizedSource = source ? String(source).trim().toLowerCase() : null;
+  const rows = normalizedSource
+    ? getDb().prepare(`
+        SELECT * FROM model_routing_policy_routes
+        WHERE policy_id = ? AND source = ?
+        ORDER BY route_order
+      `).all(id, normalizedSource)
+    : getDb().prepare(`
+        SELECT * FROM model_routing_policy_routes
+        WHERE policy_id = ?
+        ORDER BY source, route_order
+      `).all(id);
+  return rows.map(_modelRoutingRouteRowToPublic);
+}
+
+function hasModelRoutingPolicyRoutes(policyId = DEFAULT_MODEL_ROUTING_POLICY_ID, source = 'effective') {
+  const id = _normalizeModelRoutingPolicyId(policyId);
+  const normalizedSource = String(source || 'effective').trim().toLowerCase();
+  const row = getDb().prepare(`
+    SELECT 1
+    FROM model_routing_policy_routes
+    WHERE policy_id = ? AND source = ? AND enabled = 1
+    LIMIT 1
+  `).get(id, normalizedSource);
+  return !!row;
+}
+
+function _stringOrNull(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+function _jsonOrNull(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'string') return value || null;
+  try { return JSON.stringify(value); } catch { return null; }
+}
+
+function replaceModelRoutingPolicyRoutes(policyId = DEFAULT_MODEL_ROUTING_POLICY_ID, source = 'generated', routes = []) {
+  const id = _normalizeModelRoutingPolicyId(policyId);
+  const normalizedSource = String(source || '').trim().toLowerCase();
+  if (!VALID_MODEL_ROUTING_ROUTE_SOURCES.has(normalizedSource)) {
+    throw new Error(`Invalid model routing route source: ${source}`);
+  }
+  ensureModelRoutingPolicy(id);
+  const db = getDb();
+  const now = new Date().toISOString();
+  return runImmediateTransaction(db, () => {
+    db.prepare('DELETE FROM model_routing_policy_routes WHERE policy_id = ? AND source = ?').run(id, normalizedSource);
+    const insert = db.prepare(`
+      INSERT INTO model_routing_policy_routes
+        (policy_id, source, route_order, provider_id, provider_type, runtime_type,
+         provider_name, label, model_registry_id, model_id, role, candidate_source,
+         connection_kind, route_policy, runtime_access, health_status, health_json,
+         reason, score, enabled, generated_at, updated_at, metadata_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    let count = 0;
+    (Array.isArray(routes) ? routes : []).forEach((route, index) => {
+      if (!route) return;
+      const providerType = _stringOrNull(route.provider_type || route.providerType || route.type);
+      if (!providerType) return;
+      const order = count + 1;
+      const health = route.health || (route.health_status ? { status: route.health_status } : null);
+      const metadata = {
+        ...(route.metadata && typeof route.metadata === 'object' ? route.metadata : {}),
+      };
+      if (route.excluded_reason && metadata.excluded_reason === undefined) metadata.excluded_reason = route.excluded_reason;
+      if (route.reason && metadata.reason === undefined) metadata.reason = route.reason;
+      insert.run(
+        id,
+        normalizedSource,
+        Number.isFinite(order) ? Math.max(1, Math.trunc(order)) : index + 1,
+        _stringOrNull(route.provider_id || route.providerId),
+        providerType,
+        _stringOrNull(route.runtime_type || route.runtimeType || providerType),
+        _stringOrNull(route.provider_name || route.providerName),
+        _stringOrNull(route.label || route.provider_name || route.providerName || providerType),
+        _stringOrNull(route.model_registry_id || route.modelRegistryId),
+        _stringOrNull(route.model_id || route.modelId || route.model),
+        _stringOrNull(route.role || (order === 1 ? 'primary' : 'fallback')),
+        _stringOrNull(route.candidate_source || route.candidateSource || route.source),
+        _stringOrNull(route.connection_kind || route.connectionKind),
+        _stringOrNull(route.route_policy || route.routePolicy),
+        _stringOrNull(route.runtime_access || route.runtimeAccess),
+        _stringOrNull(route.health_status || (health && health.status)),
+        _jsonOrNull(health),
+        _stringOrNull(route.reason || route.excluded_reason || route.excludedReason),
+        route.score == null ? null : Number(route.score),
+        route.enabled === false || route.enabled === 0 ? 0 : 1,
+        route.generated_at || route.generatedAt || now,
+        now,
+        _jsonOrNull(Object.keys(metadata).length ? metadata : null)
+      );
+      count += 1;
+    });
+    return { policy_id: id, source: normalizedSource, count };
+  });
+}
+
+function getModelRoutingPolicy(policyId = DEFAULT_MODEL_ROUTING_POLICY_ID) {
+  const id = _normalizeModelRoutingPolicyId(policyId);
+  const policy = ensureModelRoutingPolicy(id);
+  const routes = {
+    user: listModelRoutingPolicyRoutes(id, 'user'),
+    generated: listModelRoutingPolicyRoutes(id, 'generated'),
+    effective: listModelRoutingPolicyRoutes(id, 'effective'),
+  };
+  return { policy, routes };
+}
+
 // -- Benchmark Evaluations --
 
 function _benchmarkHash(value) {
@@ -5991,14 +6987,19 @@ module.exports = {
   updateActionStatus,
   // Agent Exchanges
   listExchanges,
+  // Runtime Event Ledger
+  appendRuntimeEvent,
+  listRuntimeEvents,
   // Chat Messages
   insertChatMessage,
+  insertChatMessagePart,
   listChatMessages,
+  listChatMessagesWithParts,
+  listChatMessageParts,
   searchChatMessages,
   deleteChatMessages,
   clearChatSession,
-  saveChatBranches,
-  loadChatBranches,
+  backfillChatMessageParents,
   // Backup
   checkpointWalOrThrow,
   createBackup,
@@ -6109,11 +7110,14 @@ module.exports = {
   getModelUsageLedgerEntry,
   listModelUsageLedger,
   summarizeModelUsageLedger,
+  summarizeSessionModelUsage,
   estimateModelUsageCost,
   findModelRegistryForUsage,
   // Model Evaluations
   insertModelEvaluation,
   getModelScorecard,
+  getModelScorecardsBatch,
+  emptyModelScorecardStats,
   getModelScorecardForTask,
   insertAgentRunnerEvaluation,
   getAgentRunnerScorecard,
@@ -6122,6 +7126,12 @@ module.exports = {
   setTaskModelDefault,
   getModelDefault,
   listModelDefaults,
+  ensureModelRoutingPolicy,
+  updateModelRoutingPolicy,
+  listModelRoutingPolicyRoutes,
+  hasModelRoutingPolicyRoutes,
+  replaceModelRoutingPolicyRoutes,
+  getModelRoutingPolicy,
   // Benchmark Evaluations
   insertBenchmarkResult,
   getBenchmarkResults,