memhouse 0.18.12 → 0.20.1

package/memhouse/house/queries-v3.js

@@ -0,0 +1,1013 @@
+// The named queries of memhouse's read layer, over harness-sessions-sql's profile tables (step B4;
+// docs/design/source-identity.md §6 for the rules, harness-sessions-sql §3–4 for the tables).
+//
+// Four tables, harness-agnostic, one set per member, each keyed by the session key first:
+//
+//   <m>_sessions       one row per session: the spec columns and memhouse's totals (the rollup)
+//   <m>_session_parts  one row per message part, keyed (session, message_id, part_id); read in
+//                      order_key order
+//   <m>_session_usage  one row per usage record, keyed (session, usage_id); a reader applies the
+//                      flags and counts a per_record response once (harness-sessions-sql §4.4)
+//   <m>_calls          one row per tool call (memhouse's convenience table), keyed (session, call_id)
+//
+// All four are ReplacingMergeTree(rev, is_deleted). Two rules hold for every query here,
+// and each builder states how it meets them:
+//
+//   1. EVERY READ FILTERS `is_deleted = 0 AND removed = 0`. FINAL already hides a row whose newest version is
+//      a tombstone (measured on 26.7.4.58: FINAL and FINAL + is_deleted = 0 AND removed = 0 return the same
+//      417,087 of 490,427 rows), so under FINAL the predicate is belt and braces; WITHOUT
+//      FINAL it is what keeps a tombstone out of a candidate set.
+//   2. FINAL IS PER TABLE, IN THE SQL, NEVER A SESSION SETTING. The 0.18 read layer ran every
+//      query with `final=1`, which put FINAL on subqueries that did not want it (the epoch
+//      scan) and kept the text indexes off (search). Here each builder says which table it
+//      reads FINAL and why; the client that runs them must NOT set `final`.
+//
+// SKIP INDEXES UNDER FINAL. 26.7 enables `use_skip_indexes_if_final` AND
+// `use_skip_indexes_if_final_exact_mode` by default. Exact mode matters: a tombstone is the
+// old KEY at a higher rev, and nothing obliges it to repeat non-key columns. Measured on a
+// key-only call tombstone (tool_name = ''): `calls FINAL WHERE tool_name = 'Bash'` returned
+// 7,404 rows with skip indexes off or exact, and 9,357 with exact mode off — the index
+// skipped the tombstone's granule and the deleted calls came back. So every builder that
+// reads FINAL pins the two settings explicitly instead of trusting a server default:
+// `tools` turns them on (exact), `search` stage 2 turns them off (its key set already prunes).
+//
+// SHAPE. Each builder is pure: it returns `{ query, sql, params, settings, final }` and
+// touches no server, so the unit tests can assert the SQL. The orchestrators at the bottom
+// (`readSession`, `listSessionsPage`, …) take an `exec(spec) -> rows` function, which the
+// dashboard backs with @clickhouse/client and misc/v3-read-check.js with plain HTTP.
+
+'use strict';
+
+const EXCLUDED_MODELS = ['', '<synthetic>'];
+const FAR_FUTURE_MS = 7258118400000; // 2200-01-01, an upper bound for open windows
+// A session store's display label, as before layout 3.2: the playbook name for a data folder under
+// ~/.claude-playbooks/<name>, 'default' for any other (convert-v3 rootSQL over harness_path).
+const ROOT_LABEL = (col) => require('./convert-v3').rootSQL(col);
+// A session's identity is its store and id (layout 3.2, sessions-model §1): every read that names,
+// joins or filters a session uses the whole key, so two sessions sharing an id on two hosts, in two
+// stores or as two incarnations are never mixed.
+const SKEY = ['harness', 'host', 'harness_path', 'session_id', 'incarnation'];
+const skeyOf = (a = '') => SKEY.map((c) => `${a}${c}`).join(', ');
+const hasStore = (r) => r && r.host != null && r.harness_path != null;
+/** The store a read names: nested under `store`, or flat on the ref itself (a session ref). */
+const storeOf = (o) => (o && o.store != null ? o.store : o);
+/** host / harness_path / incarnation predicates for a ref that names its store ('' otherwise). */
+function storePred(ref, a = '', p = 'r') {
+  // Half a store is refused, never read as no store: a session is its store in every read.
+  if (ref && (ref.host != null) !== (ref.harness_path != null)) throw new QueryInputError('a session names its store with both host and harness_path');
+  if (!hasStore(ref)) return { sql: '', params: {} };
+  return {
+    sql: ` AND ${a}host = {${p}_host:String} AND ${a}harness_path = {${p}_hp:String} AND ${a}incarnation = {${p}_inc:String}`,
+    params: { [`${p}_host`]: String(ref.host), [`${p}_hp`]: String(ref.harness_path), [`${p}_inc`]: String(ref.incarnation || '') },
+  };
+}
+
+class QueryInputError extends Error {
+  constructor(msg) { super(msg); this.name = 'QueryInputError'; this.status = 400; }
+}
+
+/** The member's four conversation tables. `db` qualifies them when the client's default
+ *  database is not the house (the check script); the dashboard connects with database = house. */
+function v3Rooms(member, db = null) {
+  if (!member || !/^[A-Za-z][A-Za-z0-9_]*$/.test(member)) throw new QueryInputError(`'${member}' is not a member name`);
+  if (db && !/^[A-Za-z][A-Za-z0-9_]*$/.test(db)) throw new QueryInputError(`'${db}' is not a database name`);
+  const q = (t) => `${db ? `${db}.` : ''}${member}_${t}`;
+  // meta: where the member's machines record their two host ids (host-alias.js); readers load
+  // those into rooms.hostAliases and fold the 0.18 id's rows into the machine's.
+  return { member, db, sessions: q('sessions'), parts: q('session_parts'), usage: q('session_usage'), calls: q('calls'), meta: q('meta') };
+}
+
+// ── small helpers ─────────────────────────────────────────────────────────────────
+
+function clampInt(v, dflt, min, max) {
+  if (v === undefined || v === null || v === '') return dflt;
+  const n = Number(v);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.min(Math.max(Math.trunc(n), min), max);
+}
+
+/** Opaque keyset cursor: base64url(JSON array). Validated on the way back in. */
+function encodeCursor(parts) { return Buffer.from(JSON.stringify(parts)).toString('base64url'); }
+function decodeCursor(s, shape) {
+  if (s === undefined || s === null || s === '') return null;
+  let v;
+  try { v = JSON.parse(Buffer.from(String(s), 'base64url').toString('utf-8')); } catch { throw new QueryInputError('bad cursor'); }
+  if (!Array.isArray(v) || v.length !== shape.length) throw new QueryInputError('bad cursor');
+  shape.forEach((t, i) => {
+    if (t === 'n' && !Number.isFinite(v[i])) throw new QueryInputError('bad cursor');
+    if (t === 's' && typeof v[i] !== 'string') throw new QueryInputError('bad cursor');
+  });
+  return v;
+}
+
+/** LIKE pattern for a literal substring: escape the LIKE metacharacters, then wrap. */
+function likeContains(term) { return `%${String(term).replace(/[\\%_]/g, (c) => `\\${c}`)}%`; }
+
+const toDay = (ms) => new Date(ms).toISOString().slice(0, 10);
+
+// ── the session filter ────────────────────────────────────────────────────────────
+
+/**
+ * WHERE fragments over `<m>_sessions` (alias optional). Every key is optional:
+ *
+ *   harness       exact (or an array: IN)          harnessLike  substring (legacy `editor`)
+ *   folder        exact                            folderLike   substring (legacy Sessions page)
+ *   project, host exact                            hidden       folders to exclude
+ *   from, to      ms; a session is IN the window when it was ACTIVE in it:
+ *                 `ended >= from AND started <= to` (see the report: 0.18 used last-updated)
+ *   named         true -> drop placeholders (no name and no messages), as 0.18 did
+ *   minMessages   messages >= n
+ *   session       { harness, session_id }          one session
+ *   keys          [{ harness, session_id }]        an explicit set
+ *   latest        n: only the n most recently ended sessions matching the rest
+ *
+ * Returns { sql: ' AND …' (always starts with is_deleted = 0 AND removed = 0), params }.
+ */
+function sessionWhere(f = {}, rooms, alias = '') {
+  const a = alias ? `${alias}.` : '';
+  const parts = [`${a}is_deleted = 0`, `${a}removed = 0`];
+  const params = {};
+  if (Array.isArray(f.harness) && f.harness.length) { parts.push(`${a}harness IN {f_harnesses:Array(String)}`); params.f_harnesses = f.harness.map(String); }
+  else if (f.harness) { parts.push(`${a}harness = {f_harness:String}`); params.f_harness = String(f.harness); }
+  if (f.harnessLike) { parts.push(`${a}harness LIKE {f_harness_like:String}`); params.f_harness_like = likeContains(f.harnessLike); }
+  if (f.folder) { parts.push(`${a}folder = {f_folder:String}`); params.f_folder = String(f.folder); }
+  if (f.folderLike) { parts.push(`${a}folder LIKE {f_folder_like:String}`); params.f_folder_like = likeContains(f.folderLike); }
+  if (f.project) { parts.push(`${a}project = {f_project:String}`); params.f_project = String(f.project); }
+  // A machine's rows include those under its 0.18 id when the member recorded the pair (host-alias.js).
+  if (f.host) { parts.push(`${a}host IN {f_hosts:Array(String)}`); params.f_hosts = require('./host-alias').idsOf(String(f.host), rooms && rooms.hostAliases); }
+  if (Array.isArray(f.hidden) && f.hidden.length) { parts.push(`${a}folder NOT IN {f_hidden:Array(String)}`); params.f_hidden = f.hidden.map(String); }
+  if (f.from != null) { parts.push(`${a}ended >= fromUnixTimestamp64Milli({f_from:Int64}, 'UTC')`); params.f_from = Number(f.from); }
+  if (f.to != null) { parts.push(`${a}started <= fromUnixTimestamp64Milli({f_to:Int64}, 'UTC')`); params.f_to = Number(f.to); }
+  if (f.named) parts.push(`(${a}title != '' OR ${a}messages > 0)`);
+  if (f.minMessages != null) { parts.push(`${a}messages >= {f_min_messages:UInt32}`); params.f_min_messages = clampInt(f.minMessages, 0, 0, 4294967295); }
+  if (f.session) {
+    parts.push(`${a}harness = {f_s_harness:String} AND ${a}session_id = {f_s_id:String}`);
+    params.f_s_harness = String(f.session.harness); params.f_s_id = String(f.session.session_id);
+    const sp = storePred(f.session, a, 'f_s');
+    if (sp.sql) { parts.push(sp.sql.replace(/^ AND /, '')); Object.assign(params, sp.params); }
+  }
+  if (Array.isArray(f.keys)) {
+    // arrayZip, not two INs: the identity is the PAIR, and matching the columns separately
+    // would admit (codex, X) because (claude-code, X) was asked for.
+    parts.push(`(${a}harness, ${a}session_id) IN arrayZip({f_k_harness:Array(String)}, {f_k_id:Array(String)})`);
+    params.f_k_harness = f.keys.map((k) => String(k.harness)); params.f_k_id = f.keys.map((k) => String(k.session_id));
+  }
+  if (f.latest) {
+    if (!rooms) throw new QueryInputError('latest needs the rooms');
+    // Its own alias, so no alias of the outer query can capture a column name in here.
+    const inner = sessionWhere({ ...f, latest: undefined }, rooms, 'ls');
+    parts.push(`(${skeyOf(a)}) IN (SELECT ${skeyOf('ls.')} FROM ${rooms.sessions} AS ls FINAL WHERE ${inner.sql}`
+      + ` ORDER BY ls.ended DESC, ls.session_id DESC, ls.harness DESC LIMIT {f_latest:UInt32})`);
+    Object.assign(params, inner.params); params.f_latest = clampInt(f.latest, 500, 1, 100000);
+  }
+  return { sql: parts.join(' AND '), params };
+}
+
+// ── listSessions ──────────────────────────────────────────────────────────────────
+
+const SESSION_COLUMNS = `
+    harness, session_id, incarnation, title AS name, mode, folder, project, host, host_label, harness_path, ${ROOT_LABEL('harness_path')} AS root, git_branch, harness_version, origin,
+    toUnixTimestamp64Milli(created_at) AS created_ms, toUnixTimestamp64Milli(updated_at) AS updated_ms,
+    toUnixTimestamp64Milli(started) AS started_ms, toUnixTimestamp64Milli(ended) AS ended_ms,
+    messages, user_messages, assistant_messages, agent_messages, tool_calls,
+    input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens,
+    user_chars, assistant_chars, first_prompt, models, dominant_model,
+    toString(rev) AS rev`;
+
+// Each session priced from its OWN usage (§6: no P1–P5 chunks). sumMap folds the per-hour
+// rows into one entry per model, so a 200-hour session sends a handful of numbers, not 200.
+const USAGE_BY_MODEL = `
+    arrayReduce('sumMap', [usage.model], [arrayMap(x -> toUInt64(x), usage.messages)], [usage.input], [usage.output],
+                [usage.cache_read], [usage.cache_write], [usage.reasoning]) AS usage_by_model`;
+
+const SORTS = {
+  ended: { col: 'ended', cur: (v) => `fromUnixTimestamp64Milli(${v}, 'UTC')`, type: 'Int64', of: (r) => Number(r.ended_ms) },
+  started: { col: 'started', cur: (v) => `fromUnixTimestamp64Milli(${v}, 'UTC')`, type: 'Int64', of: (r) => Number(r.started_ms) },
+  messages: { col: 'messages', cur: (v) => v, type: 'UInt32', of: (r) => Number(r.messages) },
+};
+
+/**
+ * listSessions — `sessions FINAL` (≤ one row per session; the table is small, so a top-N
+ * over it is a full read of a few thousand rows, which is the point of the table).
+ *
+ * Keyset pagination on (sort, session_id, harness), descending by default: the cursor is the
+ * last row's triple, and the next page is everything strictly after it. Total order, so no
+ * page repeats or skips a row (the 0.18 ORDER BY ts, LIMIT/OFFSET did, on ties).
+ *
+ * opts: { filters, sort: 'ended'|'started'|'messages', dir: 'desc'|'asc', limit, cursor, withUsage }
+ * The caller asks for limit+1 rows (done here) so `finish` can say whether a next page exists.
+ */
+function listSessions(rooms, opts = {}) {
+  const sort = SORTS[opts.sort || 'ended'];
+  if (!sort) throw new QueryInputError(`sort must be one of ${Object.keys(SORTS).join(', ')}`);
+  const dir = opts.dir === 'asc' ? 'ASC' : 'DESC';
+  const limit = clampInt(opts.limit, 50, 1, 5000);
+  const w = sessionWhere(opts.filters, rooms);
+  const params = { ...w.params, limit: limit + 1 };
+  let keyset = '';
+  const cur = decodeCursor(opts.cursor, ['n', 's', 's']);
+  if (cur) {
+    keyset = ` AND (${sort.col}, session_id, harness) ${dir === 'DESC' ? '<' : '>'} (${sort.cur(`{c_v:${sort.type}}`)}, {c_s:String}, {c_h:String})`;
+    Object.assign(params, { c_v: cur[0], c_s: cur[1], c_h: cur[2] });
+  }
+  const sql = `SELECT ${SESSION_COLUMNS}${opts.withUsage ? `,${USAGE_BY_MODEL}` : ''}
+FROM ${rooms.sessions} FINAL
+WHERE ${w.sql}${keyset}
+ORDER BY ${sort.col} ${dir}, session_id ${dir}, harness ${dir}
+LIMIT {limit:UInt32}`;
+  return {
+    query: 'listSessions', final: 'sessions', sql, params, settings: {},
+    finish(rows) {
+      const more = rows.length > limit;
+      const page = more ? rows.slice(0, limit) : rows;
+      const last = page[page.length - 1];
+      return { rows: page, nextCursor: more && last ? encodeCursor([sort.of(last), last.session_id, last.harness]) : null };
+    },
+  };
+}
+
+/** The count that goes with a listSessions filter. `sessions FINAL`, one number. */
+function countSessions(rooms, filters = {}) {
+  const w = sessionWhere(filters, rooms);
+  return {
+    query: 'countSessions', final: 'sessions', settings: {}, params: w.params,
+    sql: `SELECT count() AS n FROM ${rooms.sessions} FINAL WHERE ${w.sql}`,
+    finish: (rows) => Number(rows[0] ? rows[0].n : 0),
+  };
+}
+
+// ── readSession ───────────────────────────────────────────────────────────────────
+
+/** Step 1: the header — a point read on the sessions key. `sessions FINAL`. */
+function sessionHeader(rooms, ref) {
+  const { harness, session_id } = ref || {};
+  if (!harness || !session_id) throw new QueryInputError('harness and session_id are required');
+  const sp = storePred(ref);
+  return {
+    query: 'sessionHeader', final: 'sessions', settings: {},
+    params: { h: String(harness), s: String(session_id), ...sp.params },
+    sql: `SELECT ${SESSION_COLUMNS}, days,
+    agents.agent_id AS agent_ids, agents.type AS agent_types, agents.description AS agent_descriptions,
+    agents.workflow AS agent_workflows, agents.messages AS agent_message_counts,
+    arrayMap(x -> toUnixTimestamp64Milli(x), agents.first_ts) AS agent_first_ms,
+    tools.name AS tool_names, tools.calls AS tool_call_counts, tools.errors AS tool_error_counts
+FROM ${rooms.sessions} FINAL
+WHERE harness = {h:String} AND session_id = {s:String}${sp.sql} AND is_deleted = 0 AND removed = 0
+ORDER BY ended DESC, host, harness_path, incarnation
+LIMIT 1`,
+    finish(rows) {
+      const r = rows[0];
+      if (!r) return null;
+      const agents = (r.agent_ids || []).map((id, i) => ({
+        agent_id: id, type: r.agent_types[i], description: r.agent_descriptions[i], workflow: r.agent_workflows[i],
+        messages: Number(r.agent_message_counts[i]), first_ms: Number(r.agent_first_ms[i]),
+      }));
+      const tools = (r.tool_names || []).map((name, i) => ({ name, calls: Number(r.tool_call_counts[i]), errors: Number(r.tool_error_counts[i]) }));
+      for (const k of ['agent_ids', 'agent_types', 'agent_descriptions', 'agent_workflows', 'agent_message_counts', 'agent_first_ms', 'tool_names', 'tool_call_counts', 'tool_error_counts']) delete r[k];
+      return { ...r, agents, tools };
+    },
+  };
+}
+
+// The session's order: the adapter's order_key, then the message and the part (sessions-model §2).
+const PART_ORDER = ['order_key', 'message_id', 'part_index'];
+// What a read of parts returns per row (partsPage, and q-cli's window).
+const PART_SELECT = `agent_id, message_id, part_index AS part, part_id, parent_id, response_id, order_key,
+    toUnixTimestamp64Milli(ts) AS ts_ms, role, kind, state, status, if(served_model != '', served_model, requested_model) AS model, effort,
+    text, text_len, call_id, tool_name, args, output, output_len, is_error, error_kind, error_message, origin`;
+
+/** The days of `days` that can hold rows in [lowerMs, upperMs). Strings 'YYYY-MM-DD'. */
+function daysWithin(days, lowerMs, upperMs) {
+  const lo = lowerMs == null ? null : toDay(lowerMs);
+  const hi = upperMs == null ? null : toDay(upperMs);
+  return (days || []).map(String).filter((d) => (lo === null || d >= lo) && (hi === null || d <= hi));
+}
+
+/**
+ * Step 2: one page of a session's parts. `session_parts FINAL` on the leading key columns (the
+ * session), in the session's order (PART_ORDER), which is total, so a keyset cursor can stand on
+ * any row. `dir: 'backward'` reads the page BEFORE the cursor (or the tail when there is none):
+ * what a sidebar wants.
+ */
+function partsPage(rooms, opts) {
+  const { harness, session_id, cursor = null, dir = 'forward', limit = 500, agent_id = null } = opts;
+  const lim = clampInt(limit, 500, 1, 5000);
+  const back = dir === 'backward';
+  const cur = Array.isArray(cursor) ? cursor : decodeCursor(cursor, ['s', 's', 'n']);
+  const params = { h: String(harness), s: String(session_id), limit: lim + 1 };
+  const sp = storePred(storeOf(opts));
+  let where = `harness = {h:String} AND session_id = {s:String}${sp.sql} AND is_deleted = 0 AND removed = 0`;
+  Object.assign(params, sp.params);
+  if (agent_id !== null && agent_id !== undefined) { where += ' AND agent_id = {agent:String}'; params.agent = String(agent_id); }
+  if (cur) {
+    where += ` AND (order_key, message_id, part_index) ${back ? '<' : '>'} ({c_ok:String}, {c_mid:String}, {c_part:UInt32})`;
+    Object.assign(params, { c_ok: String(cur[0]), c_mid: String(cur[1]), c_part: Number(cur[2]) });
+  }
+  const d = back ? 'DESC' : 'ASC';
+  return {
+    query: 'partsPage', final: 'session_parts', settings: {}, params,
+    sql: `SELECT ${PART_SELECT}
+FROM ${rooms.parts} FINAL
+WHERE ${where}
+ORDER BY ${PART_ORDER.map((c) => `${c} ${d}`).join(', ')}
+LIMIT {limit:UInt32}`,
+  };
+}
+
+/**
+ * Step 3: the calls of the messages that START on a page (their part 0 is on it), so consecutive
+ * pages partition the session's calls exactly. `calls FINAL` within the session.
+ */
+function callsOf(rooms, opts) {
+  const { harness, session_id, message_ids } = opts;
+  const params = { h: String(harness), s: String(session_id), mids: (message_ids || []).map(String) };
+  const sp = storePred(storeOf(opts));
+  Object.assign(params, sp.params);
+  return {
+    query: 'callsOf', final: 'calls', settings: {}, params,
+    sql: `SELECT agent_id, call_id, message_id, toUnixTimestamp64Milli(ts) AS ts_ms, tool_name, args,
+    toUnixTimestamp64Milli(result_ts) AS result_ts_ms, is_error, output_len AS result_len, model
+FROM ${rooms.calls} FINAL
+WHERE harness = {h:String} AND session_id = {s:String}${sp.sql} AND message_id IN {mids:Array(String)} AND is_deleted = 0 AND removed = 0
+ORDER BY ts, call_id`,
+    empty: params.mids.length === 0,
+  };
+}
+
+/**
+ * Step 4: the usage rows of a page: those anchored on its messages, and on its responses. Each row
+ * names its `target`, the message it is shown on: its own message, or a response's first message
+ * in the session's order (so a response's usage is shown once, on the page that starts it).
+ */
+function usageOf(rooms, opts) {
+  const { harness, session_id, message_ids, response_ids } = opts;
+  const params = { h: String(harness), s: String(session_id), mids: (message_ids || []).map(String), rids: (response_ids || []).map(String) };
+  const sp = storePred(storeOf(opts));
+  Object.assign(params, sp.params);
+  const session = `harness = {h:String} AND session_id = {s:String}${sp.sql} AND is_deleted = 0 AND removed = 0`;
+  return {
+    query: 'usageOf', final: 'session_usage, session_parts', settings: {}, params,
+    sql: `SELECT u.usage_id AS usage_id, u.anchor_kind AS anchor_kind, u.anchor_id AS anchor_id, u.input AS input, u.output AS output,
+    u.cache_read AS cache_read, u.cache_write AS cache_write, u.reasoning AS reasoning, u.tool_prompt AS tool_prompt,
+    u.input_includes_cache AS input_includes_cache, u.output_includes_reasoning AS output_includes_reasoning, u.granularity AS granularity,
+    u.model AS model, if(u.anchor_kind = 'response', h.head, u.anchor_id) AS target
+FROM (
+    SELECT *, toString(anchor_kind) AS ak, if(ak = 'response', anchor_id, '') AS rkey FROM ${rooms.usage} FINAL
+    WHERE ${session} AND ((ak = 'message' AND anchor_id IN {mids:Array(String)}) OR (ak = 'response' AND anchor_id IN {rids:Array(String)}))
+) AS u
+LEFT JOIN (
+    SELECT response_id AS hr, argMin(message_id, (order_key, message_id)) AS head FROM ${rooms.parts} FINAL
+    WHERE ${session} AND response_id IN {rids:Array(String)}
+    GROUP BY hr
+) AS h ON h.hr = u.rkey`,
+    empty: params.mids.length === 0,
+  };
+}
+
+/** A usage row in the house split (sessions-model §2.4; profile-rollup.js applies the same). */
+function houseTokens(u) {
+  const n = (x) => (x == null ? 0 : Number(x));
+  return {
+    input_tokens: Math.max(u.input_includes_cache === true ? n(u.input) - n(u.cache_read) - n(u.cache_write) : n(u.input), 0) + n(u.tool_prompt),
+    output_tokens: n(u.output) + (u.output_includes_reasoning === false ? n(u.reasoning) : 0),
+    cache_read_tokens: n(u.cache_read), cache_write_tokens: n(u.cache_write), reasoning_tokens: n(u.reasoning),
+  };
+}
+const TOKEN_FIELDS = ['input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens'];
+/**
+ * Put the page's usage on its rows: every row gets the token fields (0 by default), and a usage
+ * row's tokens go on the first part (part 0) of its target message when that part is on the page. A
+ * per_record response counts once, from its record with the greatest n (harness-sessions-sql §4.4).
+ */
+function attachUsage(page, usage) {
+  for (const r of page) for (const k of TOKEN_FIELDS) r[k] = 0;
+  const nOf = (u) => Number(String(u.usage_id).split('#').pop()) || 0;
+  const last = new Map();
+  for (const u of usage) if (u.anchor_kind === 'response') last.set(u.anchor_id, Math.max(last.has(u.anchor_id) ? last.get(u.anchor_id) : -1, nOf(u)));
+  const head = new Map();
+  for (const r of page) if (Number(r.part) === 0 && !head.has(r.message_id)) head.set(r.message_id, r);
+  for (const u of usage) {
+    if (u.granularity === 'per_record' && u.anchor_kind === 'response' && nOf(u) !== last.get(u.anchor_id)) continue;
+    const r = head.get(u.target);
+    if (!r) continue;
+    const t = houseTokens(u);
+    for (const k of TOKEN_FIELDS) r[k] += t[k];
+  }
+  return page;
+}
+
+/**
+ * readSession(page) — the header, a page of parts, the calls of the messages that start on the
+ * page, and its usage. The page and the header are key reads; calls and usage are read within the
+ * session for the page's messages only.
+ *
+ * Returns null when the session does not exist or is deleted.
+ */
+async function readSession(exec, rooms, { harness, session_id, host = null, harness_path = null, incarnation = null, cursor = null, dir = 'forward', limit = 500, agent_id = null }) {
+  const header = await run(exec, sessionHeader(rooms, { harness, session_id, host, harness_path, incarnation }));
+  if (!header) return null;
+  const back = dir === 'backward';
+  const lim = clampInt(limit, 500, 1, 5000);
+  const cur = decodeCursor(cursor, ['s', 's', 'n']);
+  // The header names the store; parts, calls and usage are read from that store only.
+  const store = { host: header.host, harness_path: header.harness_path, incarnation: header.incarnation };
+  const raw = await exec(partsPage(rooms, { harness, session_id, cursor: cur, dir, limit: lim, agent_id, store }));
+  const more = raw.length > lim;
+  const page = more ? raw.slice(0, lim) : raw.slice();
+  if (back) page.reverse();
+  const starts = [...new Set(page.filter((r) => Number(r.part) === 0).map((r) => r.message_id))];
+  const responses = [...new Set(page.map((r) => r.response_id).filter(Boolean))];
+  const calls = await run(exec, callsOf(rooms, { harness, session_id, store, message_ids: starts }));
+  attachUsage(page, await run(exec, usageOf(rooms, { harness, session_id, store, message_ids: starts, response_ids: responses })));
+  const key = (r) => encodeCursor([r.order_key, r.message_id, Number(r.part)]);
+  return {
+    header,
+    turns: page,
+    calls,
+    // forward: the next page continues after the last row; backward: the previous page ends
+    // before the first row. Either way the cursor is a row's full order key.
+    nextCursor: !back && more && page.length ? key(page[page.length - 1]) : null,
+    prevCursor: back && more && page.length ? key(page[0]) : null,
+  };
+}
+
+// ── sessionVersion ────────────────────────────────────────────────────────────────
+
+/**
+ * The sidebar poll (§6): one point read of `sessions.rev`. `sessions FINAL` on the full
+ * sorting key. `rev = Σ files.ver` rises whenever any file of the session changes, so an
+ * unchanged rev means an unchanged session — the client refetches turns only when it moves.
+ */
+function sessionVersion(rooms, ref) {
+  const { harness, session_id } = ref || {};
+  if (!harness || !session_id) throw new QueryInputError('harness and session_id are required');
+  const sp = storePred(ref);
+  return {
+    query: 'sessionVersion', final: 'sessions', settings: {},
+    params: { h: String(harness), s: String(session_id), ...sp.params },
+    sql: `SELECT toString(rev) AS rev, toUnixTimestamp64Milli(ended) AS ended_ms, messages
+FROM ${rooms.sessions} FINAL
+WHERE harness = {h:String} AND session_id = {s:String}${sp.sql} AND is_deleted = 0 AND removed = 0
+ORDER BY ended DESC, host, harness_path, incarnation
+LIMIT 1`,
+    finish: (rows) => (rows[0] ? { rev: rows[0].rev, ended_ms: Number(rows[0].ended_ms), messages: Number(rows[0].messages) } : null),
+  };
+}
+
+/**
+ * The house-wide token for Live: changes when any session changes, is added or is dropped.
+ * `sessions FINAL` — a full read of the small table; stable across merges (a raw count is not).
+ */
+function houseVersion(rooms) {
+  return {
+    query: 'houseVersion', final: 'sessions', settings: {}, params: {},
+    sql: `SELECT count() AS n, toString(sum(rev)) AS rev_sum, toUnixTimestamp64Milli(max(ended)) AS last_ms
+FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0`,
+    finish: (rows) => {
+      const r = rows[0] || { n: 0, rev_sum: '0', last_ms: null };
+      return { token: `${r.n}:${r.rev_sum}`, sessions: Number(r.n), last_ms: r.last_ms == null ? null : Number(r.last_ms) };
+    },
+  };
+}
+
+// ── search ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Split a search string into terms: whitespace-separated, "quoted phrases" kept whole,
+ * lowercased (the indexed columns are lower(text)), deduplicated, at most 8.
+ */
+function searchTerms(q) {
+  const out = [];
+  const re = /"([^"]+)"|(\S+)/g;
+  let m;
+  while ((m = re.exec(String(q || ''))) !== null) {
+    const t = (m[1] || m[2]).toLowerCase().trim();
+    if (t && !out.includes(t)) out.push(t);
+  }
+  if (!out.length) throw new QueryInputError('search needs at least one term');
+  if (out.length > 8) throw new QueryInputError('at most 8 search terms');
+  return out;
+}
+
+// What the indexed copies hold: a part's text and a tool result's output, lowercased.
+const BODY = "lower(concat(text, '\\n', output))";
+// A part's time for "newest" without nulls (ts is null where the source gave none), then its order.
+const AT = "(ifNull(ts, toDateTime64(0, 3, 'UTC')), order_key)";
+
+// One token for the splitByNonAlpha tokenizer: ASCII alphanumerics, or any non-ASCII byte.
+const SINGLE_TOKEN = /^(?:[a-z0-9]|[^\x00-\x7f])+$/;
+
+/**
+ * The predicate for one term, and which index it can use. Substring semantics for every
+ * term (what 0.18's search and /mem:recall mean by a match):
+ *
+ *   single token, ≥ 4 chars  `search_word LIKE '%t%'`  the word index answers it by scanning its
+ *                            token dictionary (26.7: use_text_index_like_evaluation_by_dictionary_scan,
+ *                            min pattern length 4) — measured 5 ms vs 182 ms on the ngram index
+ *   anything else (≥ 3)      `search_ngram LIKE '%t%'` the ngram index (phrases, 'a-b', 3 chars)
+ *   1–2 chars                the same predicate, no index; still exact
+ *
+ * `match: 'word'` asks for whole tokens instead: `hasToken(search_word, t)` (single-token terms only).
+ */
+function termPredicate(term, i, match) {
+  const p = `t${i}`;
+  // stage1 uses the indexed copies; stage2 re-checks the SAME predicate on what both copies hold
+  // (MATERIALIZED lower(concat(text, '\n', output)): a part's text and a tool result's output), so
+  // stage 2 reads the two columns once instead of a stored copy per term.
+  if (match === 'word') {
+    if (!SINGLE_TOKEN.test(term)) throw new QueryInputError(`'${term}' is not a single word — use substring search`);
+    return { stage1: `hasToken(search_word, {${p}:String})`, stage2: `hasToken(${BODY}, {${p}:String})`, params: { [p]: term }, index: 'idx_search_word' };
+  }
+  const like = { [p]: likeContains(term) };
+  if (SINGLE_TOKEN.test(term) && term.length >= 4) {
+    return { stage1: `search_word LIKE {${p}:String}`, stage2: `${BODY} LIKE {${p}:String}`, params: like, index: 'idx_search_word' };
+  }
+  return { stage1: `search_ngram LIKE {${p}:String}`, stage2: `${BODY} LIKE {${p}:String}`, params: like, index: term.length >= 3 ? 'idx_search_ngram' : null };
+}
+
+/**
+ * search — rewritten 2026-10-16 after measuring where its time went on a real house. The text
+ * index was never the cost: it keeps exactly the granules that hold a term (10–33 ms, < 1 MiB).
+ * The cost was reading those granules three times — a session restriction, the candidate keys
+ * (which ran the restriction again), and a FINAL re-check with skip indexes OFF that read `text`
+ * for every row of every candidate granule ('replacingmergetree': 366 ms, 1.03M rows, 193 MiB).
+ *
+ * Skip indexes were off under FINAL because, without exact mode, a text index can skip the granule
+ * of a newer revision that lost the term, and FINAL would then keep the old matching version — a
+ * false hit. `use_skip_indexes_if_final_exact_mode` (on by default in 26.7) closes that: the ranges
+ * the index keeps are widened to every range that intersects them in primary key, so FINAL sees
+ * each key's newest version. So the whole search is now ONE FINAL pass with the index on:
+ *
+ *   hits     (MATERIALIZED: one row per session, at most `limit`) turns FINAL where every term
+ *            matches, is_deleted = 0 AND removed = 0, live sessions only, grouped per session, newest hit first.
+ *   snippet  `text` read for those `limit` newest hits only, by full sorting key.
+ *
+ * Measured on the dev house: identical results to the two-stage statement on every term tried,
+ * 46–102 ms against 41–203 ms. A session's hit count is now every live hit, not the hits among
+ * the first 50,000 candidates. Servers without materialized CTEs or exact mode run the previous
+ * statement (searchTwoStage, below) via `fallback`.
+ *
+ * opts: { q, match: 'substring'|'word', filters: { harness, folder, project, from, to }, limit }
+ */
+function search(rooms, opts = {}) {
+  const terms = searchTerms(opts.q);
+  const limit = clampInt(opts.limit, 20, 1, 200);
+  const preds = terms.map((t, i) => termPredicate(t, i, opts.match));
+  const params = Object.assign({ limit, snip: terms[0] }, ...preds.map((p) => p.params));
+  const f = opts.filters || {};
+  const scope = [];
+  if (f.harness) { scope.push('harness = {f_harness:String}'); params.f_harness = String(f.harness); }
+  if (f.folder) { scope.push('folder = {f_folder:String}'); params.f_folder = String(f.folder); }
+  if (f.project) { scope.push('project = {f_project:String}'); params.f_project = String(f.project); }
+  if (f.from != null) { scope.push(tsBound('>=', `fromUnixTimestamp64Milli({f_from:Int64}, 'UTC')`)); params.f_from = Number(f.from); }
+  if (f.to != null) { scope.push(tsBound('<=', `fromUnixTimestamp64Milli({f_to:Int64}, 'UTC')`)); params.f_to = Number(f.to); }
+  // Every term on the indexed copies; under FINAL they are evaluated on each key's newest version.
+  const match = preds.map((p) => p.stage1).join(' AND ');
+  const scopeSql = scope.length ? ` AND ${scope.join(' AND ')}` : '';
+  const sql = `WITH hits AS MATERIALIZED (
+    SELECT harness AS ah, host AS ahost, harness_path AS ahp, session_id AS asid, incarnation AS ainc, count() AS hits, min(ts) AS first_hit, max(ts) AS last_hit,
+           argMax(message_id, ${AT}) AS hit_message_id, argMax(part_id, ${AT}) AS hit_part,
+           argMax(agent_id, ${AT}) AS hit_agent_id, argMax(role, ${AT}) AS hit_role
+    FROM ${rooms.parts} FINAL
+    WHERE ${match} AND is_deleted = 0 AND removed = 0${scopeSql}
+      AND (${skeyOf()}) IN (SELECT ${skeyOf()} FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0)
+    GROUP BY ah, ahost, ahp, asid, ainc
+    ORDER BY last_hit DESC, ah, asid, ahost, ahp, ainc
+    LIMIT {limit:UInt32}
+)
+SELECT a.ah AS harness, a.asid AS session_id, a.ahost AS host, a.ahp AS harness_path, a.ainc AS incarnation,
+       s.title AS name, s.folder AS folder, s.project AS project, toUnixTimestamp64Milli(s.ended) AS ended_ms,
+       a.hits AS hits, toUnixTimestamp64Milli(a.first_hit) AS first_hit_ms, toUnixTimestamp64Milli(a.last_hit) AS last_hit_ms,
+       a.hit_message_id AS message_id, a.hit_agent_id AS agent_id, a.hit_role AS role, n.snippet AS snippet
+FROM hits AS a
+INNER JOIN (
+    SELECT harness AS sh, host AS shost, harness_path AS shp, session_id AS ss, incarnation AS sinc, title, folder, project, ended
+    FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0
+) AS s ON s.sh = a.ah AND s.shost = a.ahost AND s.shp = a.ahp AND s.ss = a.asid AND s.sinc = a.ainc
+LEFT JOIN (
+    SELECT harness AS nh, host AS nhost, harness_path AS nhp, session_id AS ns, incarnation AS ninc,
+           argMax(substring(body, greatest(1, toInt64(positionCaseInsensitiveUTF8(body, {snip:String})) - 80), 240), rev) AS snippet
+    FROM (SELECT harness, host, harness_path, session_id, incarnation, rev, concat(text, '\\n', output) AS body FROM ${rooms.parts}
+          WHERE (host, harness, harness_path, session_id, incarnation, message_id, part_id)
+                IN (SELECT ahost, ah, ahp, asid, ainc, hit_message_id, hit_part FROM hits))
+    GROUP BY nh, nhost, nhp, ns, ninc
+) AS n ON n.nh = a.ah AND n.nhost = a.ahost AND n.nhp = a.ahp AND n.ns = a.asid AND n.ninc = a.ainc
+ORDER BY last_hit_ms DESC, harness, session_id, host, harness_path, incarnation
+LIMIT {limit:UInt32}`;
+  return {
+    query: 'search', final: 'session_parts FINAL (skip indexes in exact mode), sessions FINAL; snippet by argMax(rev)', sql, params,
+    settings: { enable_materialized_cte: 1, use_skip_indexes_if_final: 1, use_skip_indexes_if_final_exact_mode: 1 },
+    terms, indexes: preds.map((p) => p.index),
+    // A server without materialized CTEs or exact mode runs the previous two-stage statement.
+    fallback: searchTwoStage(rooms, opts),
+  };
+}
+
+/**
+ * searchTwoStage — the previous search (the fallback): the two stages of §6, in ONE statement so it costs one round trip:
+ *
+ *   stage 1  `turns` WITHOUT FINAL: the text indexes prune, is_deleted = 0 AND removed = 0 drops tombstones,
+ *            and the matching rows of the newest 3×limit matching SESSIONS (at most `cap`)
+ *            give their full sorting keys — candidates only, since an old revision may match
+ *            while its replacement does not. Restricting to the sessions the answer can hold
+ *            bounds stage 2 by the size of the answer, not by how widely a term is spread:
+ *            a rare term in 40% of granules read 250 MiB / 271 ms unrestricted, 65 MiB / 121 ms
+ *            restricted (synthetic house, 2,000 sessions). The index scan runs twice; with the
+ *            word index each run is ~5–15 ms.
+ *   stage 2  `turns FINAL` on exactly those keys (the tuple is the whole ORDER BY, so the set
+ *            is a primary-key lookup), is_deleted = 0 AND removed = 0, and EVERY term re-checked on the newest
+ *            version. Skip indexes are switched OFF for this FINAL: with exact mode off, a
+ *            text index would skip the granule of a new revision that lost the term and FINAL
+ *            would keep the old one — the very false hit stage 2 exists to remove.
+ *
+ * Hits are grouped per session and joined to live sessions (`sessions FINAL`, is_deleted = 0 AND removed = 0),
+ * newest hit first. Measured on the synthetic house: 'platypus' matches 4,163 raw rows and
+ * 208 live ones; stage 2 is what tells them apart.
+ *
+ * Completeness: a session whose every raw hit is superseded still takes one of the 3×limit
+ * slots and then drops out in stage 2, so a page can hold fewer than `limit` sessions when
+ * more exist. Never a false hit; the over-fetch makes a short page rare.
+ *
+ * opts: { q, match: 'substring'|'word', filters: { harness, folder, project, from, to }, limit, cap }
+ */
+function searchTwoStage(rooms, opts = {}) {
+  const terms = searchTerms(opts.q);
+  const limit = clampInt(opts.limit, 20, 1, 200);
+  // The row cap is a safety bound only: stage 2 is bounded by the session restriction. A low
+  // cap lost live hits — superseded versions crowd the newest-first candidate list (measured:
+  // 'platypus', 3,955 stale rows + 208 live; a 2,000 cap returned 100 of the 208).
+  const cap = clampInt(opts.cap, 50000, 1, 200000);
+  const preds = terms.map((t, i) => termPredicate(t, i, opts.match));
+  const params = Object.assign({ limit, cap, scap: Math.min(limit * 3, 600), snip: terms[0] }, ...preds.map((p) => p.params));
+  const f = opts.filters || {};
+  const scope = [];
+  if (f.harness) { scope.push('harness = {f_harness:String}'); params.f_harness = String(f.harness); }
+  if (f.folder) { scope.push('folder = {f_folder:String}'); params.f_folder = String(f.folder); }
+  if (f.project) { scope.push('project = {f_project:String}'); params.f_project = String(f.project); }
+  if (f.from != null) { scope.push(tsBound('>=', `fromUnixTimestamp64Milli({f_from:Int64}, 'UTC')`)); params.f_from = Number(f.from); }
+  if (f.to != null) { scope.push(tsBound('<=', `fromUnixTimestamp64Milli({f_to:Int64}, 'UTC')`)); params.f_to = Number(f.to); }
+  const stage1 = preds.map((p) => p.stage1).join(' AND ');
+  const stage2 = preds.map((p) => p.stage2).join(' AND ');
+  const scopeSql = scope.length ? ` AND ${scope.join(' AND ')}` : '';
+  const sql = `SELECT h.harness AS harness, h.session_id AS session_id, h.host AS host, h.harness_path AS harness_path, h.incarnation AS incarnation,
+       s.title AS name, s.folder AS folder, s.project AS project, toUnixTimestamp64Milli(s.ended) AS ended_ms,
+       h.hits AS hits, toUnixTimestamp64Milli(h.first_hit) AS first_hit_ms, toUnixTimestamp64Milli(h.last_hit) AS last_hit_ms,
+       h.hit_message_id AS message_id, h.hit_agent_id AS agent_id, h.hit_role AS role, h.snippet AS snippet
+FROM (
+    SELECT ${skeyOf()}, count() AS hits, min(ts) AS first_hit, max(ts) AS last_hit,
+           -- aliases must not reuse column names: ClickHouse aliases are query-global, and
+           -- argMax(message_id, ts) AS message_id would replace the column in the WHERE below
+           argMax(message_id, ${AT}) AS hit_message_id, argMax(agent_id, ${AT}) AS hit_agent_id, argMax(role, ${AT}) AS hit_role,
+           argMax(substring(concat(text, '\\n', output), greatest(1, toInt64(positionCaseInsensitiveUTF8(concat(text, '\\n', output), {snip:String})) - 80), 240), ${AT}) AS snippet
+    FROM ${rooms.parts} FINAL
+    WHERE (host, harness, harness_path, session_id, incarnation, message_id, part_id) IN (
+            SELECT host, harness, harness_path, session_id, incarnation, message_id, part_id
+            FROM ${rooms.parts}
+            WHERE ${stage1} AND is_deleted = 0 AND removed = 0${scopeSql}
+              AND (${skeyOf()}) IN (
+                    SELECT ${skeyOf()} FROM ${rooms.parts}
+                    WHERE ${stage1} AND is_deleted = 0 AND removed = 0${scopeSql}
+                      AND (${skeyOf()}) IN (SELECT ${skeyOf()} FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0)
+                    GROUP BY ${skeyOf()}
+                    ORDER BY max(${AT}) DESC
+                    LIMIT {scap:UInt32})
+            ORDER BY ${AT} DESC
+            LIMIT {cap:UInt32})
+      AND is_deleted = 0 AND removed = 0 AND ${stage2}
+    GROUP BY ${skeyOf()}
+) AS h
+INNER JOIN (
+    SELECT ${skeyOf()}, title, folder, project, ended FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0
+) AS s ON s.harness = h.harness AND s.host = h.host AND s.harness_path = h.harness_path AND s.session_id = h.session_id AND s.incarnation = h.incarnation
+ORDER BY last_hit_ms DESC, harness, session_id, host, harness_path, incarnation
+LIMIT {limit:UInt32}`;
+  return {
+    query: 'search', final: 'session_parts (stage 2), sessions', sql, params,
+    settings: { use_skip_indexes_if_final: 0 },
+    terms, indexes: preds.map((p) => p.index),
+  };
+}
+
+// ── aggregate ─────────────────────────────────────────────────────────────────────
+
+// Dimensions. `s` = the session row, `u` = one usage entry (ARRAY JOIN s.usage AS u), `t` = one
+// tools entry (ARRAY JOIN s.tools AS t). Session-grain time dims bucket by `started` (§3: session
+// counts keep counting by start); usage-grain time dims bucket by the usage hour.
+//
+// EVERY column is qualified (`s.messages`, never `messages`). ClickHouse aliases are global to
+// the query: with a metric `sum(messages) AS messages` in the SELECT, a bare `messages` anywhere
+// else — another metric, the depth dimension, the WHERE of the `named` filter — resolves to the
+// ALIAS, and the query fails with "aggregate function found inside another aggregate function".
+// A qualified name always means the column.
+const SESSION_DIMS = {
+  harness: 's.harness', mode: 's.mode', folder: 's.folder', project: 's.project', host: 's.host', root: ROOT_LABEL('s.harness_path'), harness_path: 's.harness_path',
+  origin: 's.origin', dominant_model: 's.dominant_model',
+  day: "formatDateTime(s.started, '%Y-%m-%d', {tz:String})",
+  hour: 'toHour(s.started, {tz:String})',
+  dow: 'toDayOfWeek(s.started, 0, {tz:String}) % 7',
+  month: "formatDateTime(s.started, '%Y-%m', {tz:String})",
+  end_month: "formatDateTime(s.ended, '%Y-%m', {tz:String})",
+  depth: "multiIf(s.messages <= 1, '1', s.messages <= 5, '2-5', s.messages <= 10, '6-10', s.messages <= 20, '11-20', s.messages <= 50, '21-50', s.messages <= 100, '51-100', '100+')",
+};
+const USAGE_DIMS = {
+  model: 'u.model',
+  // The model a usage entry is PRICED at: its own, or the session's dominant one when the
+  // source recorded none (0.18's orphan rule, now per session from its own row).
+  price_model: `if(u.model IN ('${EXCLUDED_MODELS.join("', '")}'), s.dominant_model, u.model)`,
+  day: "formatDateTime(u.hour, '%Y-%m-%d', {tz:String})",
+  hour: 'toHour(u.hour, {tz:String})',
+  month: "formatDateTime(u.hour, '%Y-%m', {tz:String})",
+};
+const TOOL_DIMS = { tool: 't.name' };
+
+const SESSION_METRICS = {
+  sessions: 'count()',
+  named_sessions: "countIf(s.title != '' OR s.messages > 0)",
+  messages: 'sum(s.messages)', user_messages: 'sum(s.user_messages)', assistant_messages: 'sum(s.assistant_messages)',
+  agent_messages: 'sum(s.agent_messages)', tool_calls: 'sum(s.tool_calls)',
+  input_tokens: 'sum(s.input_tokens)', output_tokens: 'sum(s.output_tokens)',
+  cache_read_tokens: 'sum(s.cache_read_tokens)', cache_write_tokens: 'sum(s.cache_write_tokens)',
+  reasoning_tokens: 'sum(s.reasoning_tokens)',
+  user_chars: 'sum(s.user_chars)', assistant_chars: 'sum(s.assistant_chars)',
+  first_started_ms: 'toUnixTimestamp64Milli(minIf(s.started, toUnixTimestamp64Milli(s.started) > 0))', last_ended_ms: 'toUnixTimestamp64Milli(max(s.ended))',
+  avg_messages: 'avg(s.messages)', avg_tokens: 'avg(s.input_tokens + s.output_tokens)',
+};
+const USAGE_METRICS = {
+  sessions: 'uniqExact(s.harness, s.session_id)',
+  messages: 'sum(u.messages)', input_tokens: 'sum(u.input)', output_tokens: 'sum(u.output)',
+  cache_read_tokens: 'sum(u.cache_read)', cache_write_tokens: 'sum(u.cache_write)', reasoning_tokens: 'sum(u.reasoning)',
+  first_hour_ms: 'toUnixTimestamp(min(u.hour)) * 1000', last_hour_ms: 'toUnixTimestamp(max(u.hour)) * 1000',
+};
+const TOOL_METRICS = {
+  sessions: 'uniqExact(s.harness, s.session_id)', calls: 'sum(t.calls)', errors: 'sum(t.errors)',
+};
+
+const SOURCES = {
+  sessions: { dims: SESSION_DIMS, metrics: SESSION_METRICS, join: '' },
+  usage: { dims: { ...SESSION_DIMS, ...USAGE_DIMS }, metrics: USAGE_METRICS, join: ' ARRAY JOIN s.usage AS u' },
+  tools: { dims: { ...SESSION_DIMS, ...TOOL_DIMS }, metrics: TOOL_METRICS, join: ' ARRAY JOIN s.tools AS t' },
+};
+
+/**
+ * aggregate — dims × metrics over `sessions FINAL` (≤ one row per session, is_deleted = 0 AND removed = 0).
+ *
+ *   source 'sessions'  one row per session
+ *   source 'usage'     ARRAY JOIN usage: one row per (session, hour, model) — message-grain
+ *                      series, tokens and cost. With from/to, usage hours outside the window
+ *                      are dropped too, so tokens and cost are the window's, not whole sessions'.
+ *   source 'tools'     ARRAY JOIN tools: one row per (session, tool)
+ *
+ * usage and tools are never expanded in the same query (§3: their product is meaningless).
+ * Dims and metrics are names from the registries above — never SQL from the caller.
+ *
+ * opts: { source, dims: [...], metrics: [...], filters, where: { excludeModels }, order: [[name, 'asc'|'desc']], limit, tz }
+ */
+function aggregate(rooms, opts = {}) {
+  const src = SOURCES[opts.source || 'sessions'];
+  if (!src) throw new QueryInputError(`source must be one of ${Object.keys(SOURCES).join(', ')}`);
+  const dims = opts.dims || [];
+  const metrics = opts.metrics && opts.metrics.length ? opts.metrics : ['sessions'];
+  for (const d of dims) if (!src.dims[d]) throw new QueryInputError(`unknown dimension '${d}' for ${opts.source || 'sessions'}`);
+  for (const m of metrics) if (!src.metrics[m]) throw new QueryInputError(`unknown metric '${m}' for ${opts.source || 'sessions'}`);
+  const w = sessionWhere(opts.filters, rooms, 's');
+  const params = { ...w.params };
+  const uses = (x) => x.includes('{tz:String}');
+  const extra = [];
+  if (opts.source === 'usage') {
+    const f = opts.filters || {};
+    if (f.from != null) extra.push(`u.hour >= toStartOfHour(fromUnixTimestamp64Milli({f_from:Int64}, 'UTC'))`);
+    if (f.to != null) extra.push(`u.hour <= fromUnixTimestamp64Milli({f_to:Int64}, 'UTC')`);
+    if (opts.where && opts.where.excludeModels) extra.push(`u.model NOT IN ('${EXCLUDED_MODELS.join("', '")}')`);
+  }
+  const select = [...dims.map((d) => `${src.dims[d]} AS ${d}`), ...metrics.map((m) => `${src.metrics[m]} AS ${m}`)];
+  if (select.some(uses)) params.tz = opts.tz || 'UTC';
+  let sql = `SELECT ${select.join(', ')}
+FROM ${rooms.sessions} AS s FINAL${src.join}
+WHERE ${w.sql}${extra.length ? ` AND ${extra.join(' AND ')}` : ''}`;
+  if (dims.length) sql += `\nGROUP BY ${dims.join(', ')}`;
+  const order = (opts.order || []).map(([name, d]) => {
+    if (!dims.includes(name) && !metrics.includes(name)) throw new QueryInputError(`cannot order by '${name}'`);
+    return `${name} ${d === 'desc' ? 'DESC' : 'ASC'}`;
+  });
+  // A total order whenever the caller asked for one, so a top-N cut never depends on arrival.
+  if (order.length) sql += `\nORDER BY ${[...order, ...dims.filter((d) => !order.some((o) => o.startsWith(`${d} `))).map((d) => `${d} ASC`)].join(', ')}`;
+  else if (dims.length) sql += `\nORDER BY ${dims.join(', ')}`;
+  if (opts.limit) { sql += '\nLIMIT {limit:UInt32}'; params.limit = clampInt(opts.limit, 100, 1, 100000); }
+  return { query: `aggregate:${opts.source || 'sessions'}`, final: 'sessions', settings: {}, params, sql };
+}
+
+// ── tools (drill-down) ────────────────────────────────────────────────────────────
+
+/**
+ * tools — the calls of one tool, newest first. `calls FINAL` by tool_name (the set skip index)
+ * and the time window, with skip indexes ON under FINAL in EXACT mode
+ * (see the header: exact mode is what keeps a key-only tombstone from being skipped), joined
+ * to live sessions for their names.
+ *
+ * opts: { tool, filters: { harness, folder, hidden, from, to }, limit }
+ */
+function tools(rooms, opts = {}) {
+  if (!opts.tool) throw new QueryInputError('tool is required');
+  const limit = clampInt(opts.limit, 200, 1, 1000);
+  const f = opts.filters || {};
+  const params = { tool: String(opts.tool), limit };
+  // Live sessions only, decided BEFORE the LIMIT: joining them afterwards returned short pages
+  // (996 of 1,000) whenever a dropped session's calls were among the newest.
+  const where = ['tool_name = {tool:String}', 'is_deleted = 0 AND removed = 0',
+    `(${skeyOf()}) IN (SELECT ${skeyOf()} FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0)`];
+  if (f.from != null) { where.unshift(tsBound('>=', `fromUnixTimestamp64Milli({f_from:Int64}, 'UTC')`)); params.f_from = Number(f.from); }
+  if (f.to != null) { where.unshift(tsBound('<=', `fromUnixTimestamp64Milli({f_to:Int64}, 'UTC')`)); params.f_to = Number(f.to); }
+  if (f.harness) { where.push('harness = {f_harness:String}'); params.f_harness = String(f.harness); }
+  if (f.harnessLike) { where.push('harness LIKE {f_harness_like:String}'); params.f_harness_like = likeContains(f.harnessLike); }
+  if (f.folder) { where.push('folder = {f_folder:String}'); params.f_folder = String(f.folder); }
+  if (Array.isArray(f.hidden) && f.hidden.length) { where.push('folder NOT IN {f_hidden:Array(String)}'); params.f_hidden = f.hidden.map(String); }
+  return {
+    query: 'tools', final: 'calls, sessions',
+    settings: { use_skip_indexes_if_final: 1, use_skip_indexes_if_final_exact_mode: 1 },
+    params,
+    sql: `SELECT c.harness AS harness, c.session_id AS session_id, c.agent_id AS agent_id, c.call_id AS call_id,
+       c.message_id AS message_id, toUnixTimestamp64Milli(c.ts) AS ts_ms, c.tool_name AS tool_name, c.args AS args,
+       toUnixTimestamp64Milli(c.result_ts) AS result_ts_ms, c.is_error AS is_error, c.output_len AS result_len,
+       c.model AS model, c.folder AS folder, c.project AS project, c.host AS host, c.harness_path AS harness_path, c.incarnation AS incarnation, s.title AS session_name
+FROM (
+    SELECT harness, session_id, harness_path, incarnation, agent_id, call_id, message_id, ts, tool_name, args, result_ts, is_error, output_len,
+           model, folder, project, host
+    FROM ${rooms.calls} FINAL
+    WHERE ${where.join(' AND ')}
+    ORDER BY ts DESC, call_id
+    LIMIT {limit:UInt32}
+) AS c
+INNER JOIN (SELECT ${skeyOf()}, title FROM ${rooms.sessions} FINAL WHERE is_deleted = 0 AND removed = 0) AS s
+  ON s.harness = c.harness AND s.host = c.host AND s.harness_path = c.harness_path AND s.session_id = c.session_id AND s.incarnation = c.incarnation
+ORDER BY ts_ms DESC, call_id`,
+  };
+}
+
+// ── coverage / machines ───────────────────────────────────────────────────────────
+
+/** What the house holds, per harness: sessions, span, hosts, origins. `sessions FINAL`; per_record_sessions from `session_usage FINAL`. */
+function coverage(rooms) {
+  return {
+    query: 'coverage', final: 'sessions', settings: {}, params: {},
+    sql: `SELECT harness, count() AS sessions, sum(messages) AS messages, sum(tool_calls) AS tool_calls,
+       toUnixTimestamp64Milli(minIf(started, toUnixTimestamp64Milli(started) > 0)) AS first_ms, toUnixTimestamp64Milli(max(ended)) AS last_ms,
+       arraySort(groupUniqArray(host)) AS hosts, arraySort(groupUniqArray(origin)) AS origins,
+       countIf((${skeyOf()}) IN (SELECT ${skeyOf()} FROM ${rooms.usage} FINAL WHERE granularity = 'per_record' AND is_deleted = 0 AND removed = 0)) AS per_record_sessions
+FROM ${rooms.sessions} FINAL
+WHERE is_deleted = 0 AND removed = 0
+GROUP BY harness
+ORDER BY sessions DESC, harness`,
+    finish(rows) {
+      const total = { sessions: 0, messages: 0, tool_calls: 0, first_ms: null, last_ms: null };
+      for (const r of rows) {
+        total.sessions += Number(r.sessions); total.messages += Number(r.messages); total.tool_calls += Number(r.tool_calls);
+        if (total.first_ms === null || Number(r.first_ms) < total.first_ms) total.first_ms = Number(r.first_ms);
+        if (total.last_ms === null || Number(r.last_ms) > total.last_ms) total.last_ms = Number(r.last_ms);
+      }
+      return { harnesses: rows, total };
+    },
+  };
+}
+
+/** The machines that wrote sessions. `sessions FINAL`. */
+function machines(rooms) {
+  return {
+    query: 'machines', final: 'sessions', settings: {}, params: {},
+    sql: `SELECT host, anyIf(host_label, host_label != '') AS label, count() AS sessions, arraySort(groupUniqArray(harness)) AS harnesses,
+       toUnixTimestamp64Milli(max(ended)) AS last_ms
+FROM ${rooms.sessions} FINAL
+WHERE is_deleted = 0 AND removed = 0
+GROUP BY host
+ORDER BY last_ms DESC, host`,
+  };
+}
+
+// ── running a spec ────────────────────────────────────────────────────────────────
+
+async function run(exec, spec) {
+  const rows = spec.empty ? [] : await exec(spec);
+  return spec.finish ? spec.finish(rows) : rows;
+}
+
+// A spec may carry `fallback`: the same answer for a server without a feature the spec needs
+// (search: materialized CTEs, skip indexes under FINAL in exact mode). The first refusal switches
+// that query to its fallback for the life of the process; any other error is the caller's.
+const FEATURE_REFUSED = /UNKNOWN_SETTING|Unknown setting|SYNTAX_ERROR|Syntax error|NOT_IMPLEMENTED|materialized/i;
+const onFallback = new Set();
+function withFallback(exec) {
+  return async (spec) => {
+    if (!spec || !spec.fallback) return exec(spec);
+    if (onFallback.has(spec.query)) return exec(spec.fallback);
+    try { return await exec(spec); } catch (e) {
+      if (!FEATURE_REFUSED.test(String(e && e.message))) throw e;
+      onFallback.add(spec.query);
+      return exec(spec.fallback);
+    }
+  };
+}
+
+/** usage_by_model (a sumMap tuple) -> [{ model, messages, input, output, cache_read, cache_write, reasoning }] */
+function usageByModel(t) {
+  if (!t) return [];
+  const [models, msgs, inp, outp, cr, cw, rs] = Array.isArray(t) ? t : [t[0], t[1], t[2], t[3], t[4], t[5], t[6]];
+  return (models || []).map((model, i) => ({
+    model, messages: Number(msgs[i]) || 0, input: Number(inp[i]) || 0, output: Number(outp[i]) || 0,
+    cache_read: Number(cr[i]) || 0, cache_write: Number(cw[i]) || 0, reasoning: Number(rs[i]) || 0,
+  }));
+}
+
+// A session reference: `<harness>:<session_id>`, then `~<store>` when it names its store — the
+// base64url of [host, harness_path, incarnation]. Without a store (a 0.18 link, a typed id) the
+// newest session of that harness and id is read, and then only its own store's rows.
+const STORE_SEP = '~';
+function storeToken(r) { return Buffer.from(JSON.stringify([String(r.host), String(r.harness_path), String(r.incarnation || '')]), 'utf-8').toString('base64url'); }
+function parseStoreToken(t) {
+  try {
+    const v = JSON.parse(Buffer.from(t, 'base64url').toString('utf-8'));
+    return Array.isArray(v) && v.length === 3 && v.every((x) => typeof x === 'string') ? { host: v[0], harness_path: v[1], incarnation: v[2] } : null;
+  } catch { return null; }
+}
+/** Parse a session reference (above) or an object. */
+function parseSessionRef(ref, harness = null) {
+  if (ref && typeof ref === 'object') {
+    const o = { harness: String(ref.harness), session_id: String(ref.session_id) };
+    return hasStore(ref) ? { ...o, host: String(ref.host), harness_path: String(ref.harness_path), incarnation: String(ref.incarnation || '') } : o;
+  }
+  let s = String(ref || '');
+  let store = null;
+  const at = s.lastIndexOf(STORE_SEP);
+  if (at > 0) { const st = parseStoreToken(s.slice(at + 1)); if (st) { store = st; s = s.slice(0, at); } }
+  let out;
+  if (harness) out = { harness: String(harness), session_id: s };
+  else {
+    const cut = s.indexOf(':');
+    if (cut <= 0) throw new QueryInputError(`'${s}' is not <harness>:<session_id>`);
+    out = { harness: s.slice(0, cut), session_id: s.slice(cut + 1) };
+  }
+  return store ? { ...out, ...store } : out;
+}
+const sessionRef = (r) => `${r.harness}:${r.session_id}${hasStore(r) ? `${STORE_SEP}${storeToken(r)}` : ''}`;
+
+/**
+ * removedContent — the messages kept as removed versions (plan v4: a key that left its source on a
+ * rewrite — a revert, a rewind, a deleted message — is written again with removed = 1, never
+ * deleted). One row per removed message, newest first: the one read that shows them, since every
+ * other read filters removed = 0. Optional: one session (`store` names its store) or one harness,
+ * and a day window (`days`, by the message's own date).
+ */
+/**
+ * A time bound on a part or call: its own ts, or when it has none (a harness that keeps no time) the
+ * first_seen of the pass that captured it.
+ */
+/**
+ * What a part says, as text: a call its name and arguments, a result its output, an error its message
+ * (the profile keeps an error's content in error_message, its text empty), anything else its text.
+ */
+function partText(t) {
+  if (t.kind === 'tool_call') return `${t.tool_name || ''} ${t.args || ''}`.trim();
+  if (t.kind === 'tool_result') return t.output || '';
+  if (t.kind === 'error') return t.error_message || t.text || (t.error_kind ? `[${t.error_kind}]` : '');
+  return t.text;
+}
+
+function tsBound(op, at) { return `(ts ${op} ${at} OR (ts IS NULL AND first_seen ${op} ${at}))`; }
+
+function removedContent(rooms, opts = {}) {
+  const limit = clampInt(opts.limit, 50, 1, 1000);
+  const chars = clampInt(opts.chars, 200, 0, 100000);
+  const params = { limit, chars };
+  const where = ['removed = 1', 'is_deleted = 0'];
+  if (opts.days != null) { where.unshift(tsBound('>=', 'now64(3) - toIntervalDay({days:UInt32})')); params.days = clampInt(opts.days, 14, 1, 100000); }
+  if (opts.harness) { where.push('harness = {h:String}'); params.h = String(opts.harness); }
+  if (opts.session_id) {
+    where.push('session_id = {s:String}'); params.s = String(opts.session_id);
+    const sp = storePred(opts.store || null);
+    if (sp.sql) { where.push(sp.sql.replace(/^ AND /, '')); Object.assign(params, sp.params); }
+  }
+  return {
+    query: 'removedContent', final: 'session_parts', params,
+    sql: `SELECT toString(harness) AS harness, host, toString(harness_path) AS harness_path, session_id, incarnation, message_id,
+       any(role) AS role, any(state) AS state, toUnixTimestamp64Milli(min(ts)) AS ts_ms, count() AS parts,
+       substring(argMinIf(text, part_index, kind IN ('text', 'summary', 'reasoning')), 1, {chars:UInt32}) AS snippet
+FROM ${rooms.parts} FINAL
+WHERE ${where.join(' AND ')}
+GROUP BY harness, host, harness_path, session_id, incarnation, message_id
+ORDER BY ts_ms DESC
+LIMIT {limit:UInt32}`,
+  };
+}
+
+const NAMED = {
+  listSessions, countSessions, sessionHeader, partsPage, callsOf, usageOf, sessionVersion, houseVersion,
+  search, aggregate, tools, coverage, machines, removedContent,
+};
+
+module.exports = {
+  ROOT_LABEL,
+  withFallback,
+  v3Rooms, NAMED, QueryInputError, EXCLUDED_MODELS, FAR_FUTURE_MS,
+  sessionWhere, listSessions, countSessions, sessionHeader, partsPage, callsOf, usageOf, attachUsage, houseTokens, readSession,
+  sessionVersion, houseVersion, search, searchTerms, termPredicate, aggregate, tools, coverage, machines, removedContent,
+  run, usageByModel, parseSessionRef, sessionRef, encodeCursor, decodeCursor, likeContains, daysWithin, PART_SELECT, storePred, tsBound, partText,
+  SESSION_DIMS, USAGE_DIMS, TOOL_DIMS, SESSION_METRICS, USAGE_METRICS, TOOL_METRICS,
+};