memhouse 0.18.12 → 0.20.1

package/memhouse/house/q-cli.js

@@ -0,0 +1,863 @@
+// `memhouse q` and the CLI's other schema-3 reads — the named queries of
+// docs/design/source-identity.md §6 (memhouse/house/queries-v3.js), reachable from a shell. The
+// tables are harness-sessions-sql's profile (sessions, session_parts, session_usage, calls).
+//
+// This is what the /mem skills call on a schema-3 house instead of hand-written SQL over the
+// 0.18 rooms: `memhouse q search …`, `memhouse q window …`, `memhouse q spend …`. Each name
+// maps to one or more builders in queries-v3.js, so the FINAL / is_deleted = 0 AND removed = 0 / skip-index
+// rules those builders state hold here too — nothing in this file writes its own FROM over
+// parts or calls except where noted (the window's pivot lookup and the bounded doctor checks),
+// and those follow the same rules.
+//
+// Three layers, so the unit tests can hold each one without a server:
+//   parseQ(positional, flags)   -> { name, ref?, terms?, opts }   pure; throws QueryInputError
+//   runQ(exec, rooms, parsed)   -> a JSON-able result               takes an injected exec
+//   renderQ(name, result)       -> lines for a human                 pure
+// plus the transport (httpTransport — node's fetch, no node_modules, and NEVER `final=1`),
+// the room-name rewrite behind `memhouse room-sql`, and the schema switch the skills read.
+
+'use strict';
+
+const Q = require('./queries-v3');
+const HA = require('./host-alias');
+
+const { QueryInputError } = Q;
+
+// ── the schema switch ─────────────────────────────────────────────────────────────
+
+/**
+ * Which schema this install reads: MEMHOUSE_SCHEMA from the process env, else the env file,
+ * else 2. Only '3' selects the conversation layer; anything else is the 0.18 rooms.
+ * @returns {{ schema: 2|3, source: 'flag'|'env'|'env-file'|'default', raw: string|null }}
+ */
+function schemaOf({ flag = undefined, env = process.env, file = {} } = {}) {
+  let raw = null; let source = 'default';
+  if (flag !== undefined && flag !== null && flag !== true && flag !== '') { raw = String(flag); source = 'flag'; }
+  else if (env.MEMHOUSE_SCHEMA !== undefined && env.MEMHOUSE_SCHEMA !== '') { raw = String(env.MEMHOUSE_SCHEMA); source = 'env'; }
+  else if (file.MEMHOUSE_SCHEMA !== undefined && file.MEMHOUSE_SCHEMA !== '') { raw = String(file.MEMHOUSE_SCHEMA); source = 'env-file'; }
+  return { schema: raw === '3' ? 3 : 2, source, raw };
+}
+
+// ── transport ─────────────────────────────────────────────────────────────────────
+
+// Query parameters in the text form @clickhouse/client sends (same as misc/v3-read-check.js).
+function fmtInner(v) {
+  if (Array.isArray(v)) return `[${v.map(fmtInner).join(',')}]`;
+  if (typeof v === 'string') return `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  if (typeof v === 'boolean') return v ? '1' : '0';
+  if (v === null || v === undefined) return 'NULL';
+  return String(v);
+}
+function fmtTop(v) {
+  if (Array.isArray(v)) return fmtInner(v);
+  if (typeof v === 'string') return v.replace(/\\/g, '\\\\').replace(/\t/g, '\\t').replace(/\n/g, '\\n');
+  if (typeof v === 'boolean') return v ? '1' : '0';
+  return String(v);
+}
+
+/**
+ * HTTP to ClickHouse with node's fetch. Reads only: every request carries `readonly=2` (reads
+ * and per-query settings, no writes, no DDL) unless the caller is the schema step, which
+ * passes `write: true`. It never sets `final` — FINAL is per table, in the SQL (queries-v3.js).
+ *
+ * @returns {{ exec(spec), q: {sql, rows}, raw(text, opts), close() }}
+ */
+function httpTransport({ url, user, password = '', db = 'mem', timeout = 60000, fetchImpl = null } = {}) {
+  if (!url) throw new Error('no house URL');
+  const base = String(url).replace(/\/+$/, '');
+  const doFetch = fetchImpl || fetch;
+  async function post(body, { params = {}, settings = {}, database = db, write = false, ms = timeout } = {}) {
+    const u = new URL(`${base}/`);
+    if (database) u.searchParams.set('database', database);
+    if (!write) u.searchParams.set('readonly', '2');
+    u.searchParams.set('output_format_json_quote_64bit_integers', '0');
+    for (const [k, v] of Object.entries(settings || {})) u.searchParams.set(k, String(v));
+    for (const [k, v] of Object.entries(params || {})) u.searchParams.set(`param_${k}`, fmtTop(v));
+    let res;
+    try {
+      res = await doFetch(u, {
+        method: 'POST', body,
+        headers: { 'X-ClickHouse-User': user || 'default', 'X-ClickHouse-Key': password || '' },
+        signal: AbortSignal.timeout(ms),
+      });
+    } catch (e) {
+      const c = e && e.cause && (e.cause.code || e.cause.message);
+      throw new Error(`cannot reach ${base}: ${c || (e && e.name === 'TimeoutError' ? 'timed out' : e.message)}`);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+      const err = new Error(text.trim().split('\n')[0].slice(0, 600) || `HTTP ${res.status}`); err.http = res.status;
+      // ClickHouse's exception code, as bin/memhouse.js ch() carries it (schema-choice.js isAuthFailure).
+      const code = Number(res.headers && res.headers.get && res.headers.get('x-clickhouse-exception-code'));
+      if (code) err.chCode = code;
+      throw err;
+    }
+    return text;
+  }
+  const lines = (t) => t.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  return {
+    exec: Q.withFallback(async (spec) => (spec.empty ? [] : lines(await post(`${spec.sql}\nFORMAT JSONEachRow`, { params: spec.params, settings: spec.settings })))),
+    // The transport-free interface of memhouse/house/{schema,reconcile}-v3.js. DDL needs write.
+    q: {
+      sql: (text, settings) => post(text, { settings: dropFinal(settings), write: true }),
+      rows: async (text, settings) => lines(await post(`${text}\nFORMAT JSONEachRow`, { settings: dropFinal(settings) })),
+    },
+    raw: (text, opts = {}) => post(text, opts),
+  };
+}
+// The schema/reconcile modules pass `final: 0` defensively; a readonly=2 request may change it,
+// but there is no reason to send it at all.
+function dropFinal(s) { if (!s) return {}; const o = { ...s }; delete o.final; delete o.join_use_nulls; return o; }
+
+// ── small parsers ─────────────────────────────────────────────────────────────────
+
+const DAY = 86400000;
+
+/**
+ * A point in time from the command line, as epoch ms. Accepts 'YYYY-MM-DD' (UTC midnight; as an
+ * upper bound, the END of that day), an ISO datetime, epoch seconds or ms, 'today', 'yesterday',
+ * and relative spans back from now: '30m', '24h', '7d', '2w', '3mo', '1y'.
+ */
+function parseWhen(s, { end = false, now = Date.now() } = {}) {
+  if (s === undefined || s === null || s === true || s === '') return null;
+  const v = String(s).trim().toLowerCase();
+  if (v === 'now') return now;
+  if (v === 'today' || v === 'yesterday') {
+    const d = new Date(now); d.setUTCHours(0, 0, 0, 0);
+    const start = d.getTime() - (v === 'yesterday' ? DAY : 0);
+    return end ? start + DAY - 1 : start;
+  }
+  let m = /^(\d+)\s*(m|min|h|d|w|mo|y)$/.exec(v);
+  if (m) {
+    const n = Number(m[1]);
+    const unit = { m: 60000, min: 60000, h: 3600000, d: DAY, w: 7 * DAY, mo: 30 * DAY, y: 365 * DAY }[m[2]];
+    return now - n * unit;
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(v)) {
+    const t = Date.parse(`${v}T00:00:00Z`);
+    if (Number.isFinite(t)) return end ? t + DAY - 1 : t;
+  }
+  if (/^\d{9,13}$/.test(v)) { const n = Number(v); return n < 1e11 ? n * 1000 : n; }
+  const t = Date.parse(String(s).trim());
+  if (Number.isFinite(t)) return t;
+  throw new QueryInputError(`'${s}' is not a time — use YYYY-MM-DD, an ISO time, or a span like 7d`);
+}
+
+function intFlag(v, name, dflt, min = 0, max = 1e9) {
+  if (v === undefined || v === null || v === true) return dflt;
+  const n = Number(v);
+  if (!Number.isFinite(n) || Math.trunc(n) !== n || n < min || n > max) throw new QueryInputError(`--${name} must be an integer from ${min} to ${max}`);
+  return n;
+}
+function listFlag(v) { return v === undefined || v === null || v === true ? [] : String(v).split(',').map((x) => x.trim()).filter(Boolean); }
+function strFlag(v, name) {
+  if (v === undefined || v === null) return null;
+  if (v === true) throw new QueryInputError(`--${name} needs a value`);
+  return String(v);
+}
+
+/** The session filter of queries-v3 from command-line flags. */
+function filtersFrom(flags, { now = Date.now(), named = false } = {}) {
+  const f = {};
+  const h = listFlag(flags.harness);
+  if (h.length === 1) f.harness = h[0]; else if (h.length > 1) f.harness = h;
+  for (const k of ['project', 'folder', 'host']) { const v = strFlag(flags[k], k); if (v !== null) f[k] = v; }
+  const from = parseWhen(flags.since, { now }); if (from !== null) f.from = from;
+  const to = parseWhen(flags.until, { end: true, now }); if (to !== null) f.to = to;
+  if (flags['min-messages'] !== undefined) f.minMessages = intFlag(flags['min-messages'], 'min-messages', 0);
+  if (named && flags.all !== true) f.named = true;
+  return f;
+}
+
+/** A session reference: `<harness>:<session_id>`, or a bare id with --harness. */
+function parseRef(ref, flags = {}) {
+  if (!ref) throw new QueryInputError('which session? give <harness>:<session_id> (the `ref` that search and recent print)');
+  const h = listFlag(flags.harness);
+  const s = String(ref);
+  // A ref may name its store (`~<token>`, what search and recent print): Q.parseSessionRef reads it.
+  if (h.length === 1) return Q.parseSessionRef(s.startsWith(`${h[0]}:`) ? s.slice(h[0].length + 1) : s, h[0]);
+  if (s.indexOf(':') <= 0) return { harness: null, session_id: s }; // bare: looked up in sessions
+  return Q.parseSessionRef(s);
+}
+
+// ── the registry ──────────────────────────────────────────────────────────────────
+
+const FILTER_FLAGS = ['harness', 'project', 'folder', 'host', 'since', 'until'];
+const NAMES = {
+  schema: { usage: 'q schema', what: 'which schema this install reads: 3 (harness-sessions-sql\'s profile: sessions, session_parts, session_usage, calls) or 2 (the 0.18 rooms)', house: false, flags: [] },
+  search: { usage: 'q search <terms…> [--match word] [--limit N]', what: 'sessions whose live text holds EVERY term (substring, lowercase-insensitive), newest hit first', flags: [...FILTER_FLAGS, 'match', 'limit'] },
+  recent: { aliases: ['sessions', 'listSessions', 'list'], usage: 'q recent [--limit N] [--sort ended|started|messages] [--cursor C] [--all]', what: 'sessions by most recent activity (placeholders hidden unless --all)', flags: [...FILTER_FLAGS, 'limit', 'sort', 'dir', 'cursor', 'min-messages', 'all'] },
+  session: { aliases: ['readSession', 'read', 'transcript'], usage: 'q session <ref> [--limit N] [--cursor C] [--dir forward|backward] [--agent ID|main] [--chars N]', what: 'one session: header, a page of turns in order, and the tool calls of that page', flags: ['harness', 'limit', 'cursor', 'dir', 'agent', 'chars'] },
+  window: { usage: 'q window <ref> [--at <message_id> | --ts <time>] [--before 3] [--after 12] [--agent ID|main] [--chars N]', what: 'the turns around one message (a search hit) — what led to it and what resolved it; with neither --at nor --ts, the session\'s opening turns', flags: ['harness', 'at', 'ts', 'before', 'after', 'agent', 'chars'] },
+  agents: { usage: 'q agents <ref>', what: 'the sub-agents a session spawned: id, type, what it was asked, turns', flags: ['harness'] },
+  aggregate: { usage: 'q aggregate --source sessions|usage|tools --dims a,b --metrics x,y [--order m:desc] [--limit N] [--tz Z]', what: 'any registered dims × metrics over sessions FINAL (names from queries-v3.js, never SQL)', flags: [...FILTER_FLAGS, 'source', 'dims', 'metrics', 'order', 'limit', 'tz', 'exclude-models', 'min-messages', 'all'] },
+  spend: { usage: 'q spend [--by model|harness|project|folder|host|day|month] [--since 30d]', what: 'tokens and derived cost (pricing.json), each usage entry priced at its own model', flags: [...FILTER_FLAGS, 'by', 'limit', 'tz'] },
+  models: { usage: 'q models', what: 'model mix: sessions, messages, tokens and cost per model', flags: [...FILTER_FLAGS, 'limit'] },
+  tools: { usage: 'q tools [--limit 25]', what: 'tool ranking: calls, errors, sessions per tool', flags: [...FILTER_FLAGS, 'limit'] },
+  tool: { usage: 'q tool <name> [--limit N] [--chars N]', what: 'the calls of one tool, newest first, with their arguments', flags: [...FILTER_FLAGS, 'limit', 'chars'] },
+  activity: { usage: 'q activity [--by day|month|hour|dow|host|harness|project][,…] [--grain sessions|usage] [--tz Z]', what: 'activity over time (sessions by start, or messages/tokens by usage hour)', flags: [...FILTER_FLAGS, 'by', 'grain', 'limit', 'tz'] },
+  hosts: { usage: 'q hosts', what: 'per machine: sessions, messages, tokens, first and last activity', flags: [...FILTER_FLAGS] },
+  coverage: { usage: 'q coverage', what: 'what the house holds per harness: sessions, span, hosts, origins', flags: [] },
+  machines: { usage: 'q machines', what: 'the machines that wrote sessions, and when last', flags: [] },
+  count: { usage: 'q count', what: 'how many sessions match the filters', flags: [...FILTER_FLAGS, 'min-messages', 'all'] },
+  removed: { usage: 'q removed [<ref>] [--harness H] [--days N] [--limit 50] [--chars 200]', what: 'messages kept as removed versions (a revert, a rewind, a message deleted at the source), newest first: what every other read hides', flags: ['harness', 'days', 'limit', 'chars'] },
+  version: { usage: 'q version [<ref>]', what: "the house's change token, or one session's rev", flags: ['harness'] },
+};
+const ALIASES = Object.fromEntries(Object.entries(NAMES).flatMap(([n, d]) => (d.aliases || []).map((a) => [a.toLowerCase(), n])));
+const COMMON_FLAGS = ['json', 'member', 'schema', 'list', 'yes', 'help', 'version'];
+
+function canonicalName(n) {
+  if (!n) return null;
+  if (NAMES[n]) return n;
+  return ALIASES[String(n).toLowerCase()] || null;
+}
+
+/** Every flag any q name takes — what memhouse/flags.js declares for the `q` command. */
+function allQFlags() { return [...new Set(Object.values(NAMES).flatMap((d) => d.flags).concat(['member', 'schema', 'list']))]; }
+
+/**
+ * positional (after `q`) + flags -> what to run. Pure. Unknown names and flags a name does not
+ * take are refused here with the usage line, so a typo is never a silently different query.
+ */
+function parseQ(positional, flags = {}) {
+  if (flags.schema !== undefined && !positional.length) return { name: 'schema', opts: {} };
+  if (flags.list === true && !positional.length) return { name: 'list', opts: {} };
+  const name = canonicalName(positional[0]);
+  if (!positional.length) return { name: 'list', opts: {} };
+  if (!name) throw new QueryInputError(`no named query '${positional[0]}' — known: ${Object.keys(NAMES).join(', ')}`);
+  const def = NAMES[name];
+  const bad = Object.keys(flags).filter((f) => !def.flags.includes(f) && !COMMON_FLAGS.includes(f));
+  if (bad.length) throw new QueryInputError(`q ${name} does not take --${bad.join(', --')} — usage: memhouse ${def.usage}`);
+  const args = positional.slice(1);
+  const out = { name, opts: {}, member: strFlag(flags.member, 'member') };
+  switch (name) {
+    case 'schema': case 'coverage': case 'machines':
+      if (args.length) throw new QueryInputError(`q ${name} takes no arguments`);
+      break;
+    case 'search': {
+      if (!args.length) throw new QueryInputError('q search needs at least one term');
+      // A positional that holds a space was quoted on the command line: keep it a phrase.
+      out.q = args.map((t) => (/\s/.test(t) ? `"${t.replace(/"/g, '')}"` : t)).join(' ');
+      out.terms = Q.searchTerms(out.q);
+      const f = filtersFrom(flags);
+      if (Array.isArray(f.harness)) throw new QueryInputError('search takes one --harness');
+      if (f.host) throw new QueryInputError('search filters by --harness, --project, --folder, --since, --until');
+      out.opts = { q: out.q, filters: f, limit: intFlag(flags.limit, 'limit', 10, 1, 200) };
+      if (flags.match !== undefined) {
+        const m = strFlag(flags.match, 'match');
+        if (!['word', 'substring'].includes(m)) throw new QueryInputError('--match is word or substring');
+        out.opts.match = m;
+      }
+      break;
+    }
+    case 'recent': {
+      if (args.length) throw new QueryInputError('q recent takes no positional arguments — filter with --harness/--project/--since …');
+      const sort = flags.sort === undefined ? 'ended' : strFlag(flags.sort, 'sort');
+      if (!['ended', 'started', 'messages'].includes(sort)) throw new QueryInputError('--sort is ended, started or messages');
+      const dir = flags.dir === undefined ? 'desc' : strFlag(flags.dir, 'dir');
+      if (!['asc', 'desc'].includes(dir)) throw new QueryInputError('--dir is asc or desc for recent');
+      out.opts = { filters: filtersFrom(flags, { named: true }), sort, dir, limit: intFlag(flags.limit, 'limit', 20, 1, 5000), cursor: strFlag(flags.cursor, 'cursor') };
+      break;
+    }
+    case 'session': case 'window': case 'agents': {
+      if (args.length !== 1) throw new QueryInputError(`q ${name} takes one session: <harness>:<session_id>`);
+      out.ref = parseRef(args[0], flags);
+      out.opts.agent_id = agentFlag(flags.agent);
+      out.opts.chars = intFlag(flags.chars, 'chars', 2000, 0, 10000000);
+      if (name === 'session') {
+        const dir = flags.dir === undefined ? 'forward' : strFlag(flags.dir, 'dir');
+        if (!['forward', 'backward'].includes(dir)) throw new QueryInputError('--dir is forward or backward for session');
+        Object.assign(out.opts, { dir, limit: intFlag(flags.limit, 'limit', 200, 1, 5000), cursor: strFlag(flags.cursor, 'cursor') });
+      }
+      if (name === 'window') {
+        // A ref straight from a listing (q recent) reads too: with neither --at nor --ts the window
+        // opens at the session's first turn. It used to refuse, and a reader holding only the ref
+        // had to invent a time.
+        const at = strFlag(flags.at, 'at'); const ts = flags.ts === undefined ? null : parseWhen(flags.ts);
+        Object.assign(out.opts, { at, ts, start: !at && ts === null, before: intFlag(flags.before, 'before', 3, 0, 500), after: intFlag(flags.after, 'after', 12, 0, 2000) });
+      }
+      break;
+    }
+    case 'aggregate': {
+      if (args.length) throw new QueryInputError('q aggregate takes flags only');
+      const source = flags.source === undefined ? 'sessions' : strFlag(flags.source, 'source');
+      const order = listFlag(flags.order).map((o) => { const [n, d] = o.split(':'); return [n, d === 'desc' ? 'desc' : 'asc']; });
+      out.opts = {
+        source, dims: listFlag(flags.dims), metrics: listFlag(flags.metrics), order,
+        filters: filtersFrom(flags, { named: false }), tz: strFlag(flags.tz, 'tz') || 'UTC',
+        where: flags['exclude-models'] === true ? { excludeModels: true } : undefined,
+      };
+      if (flags.limit !== undefined) out.opts.limit = intFlag(flags.limit, 'limit', 100, 1, 100000);
+      if (flags.all !== true && flags['min-messages'] === undefined) { /* every live session; placeholders count too */ }
+      Q.aggregate(Q.v3Rooms('m'), out.opts); // validate dims/metrics/order now, against the real registry
+      break;
+    }
+    case 'spend': {
+      if (args.length) throw new QueryInputError('q spend takes flags only');
+      const by = flags.by === undefined ? 'model' : strFlag(flags.by, 'by');
+      if (!['model', 'harness', 'project', 'folder', 'host', 'day', 'month', 'root'].includes(by)) throw new QueryInputError('--by is model, harness, project, folder, host, root, day or month');
+      out.opts = { by, filters: filtersFrom(flags), tz: strFlag(flags.tz, 'tz') || 'UTC', limit: flags.limit === undefined ? null : intFlag(flags.limit, 'limit', 50, 1, 100000) };
+      break;
+    }
+    case 'models': case 'tools': case 'hosts': case 'count': {
+      if (args.length) throw new QueryInputError(`q ${name} takes flags only`);
+      out.opts = { filters: filtersFrom(flags, { named: name === 'count' }), limit: flags.limit === undefined ? (name === 'tools' ? 25 : null) : intFlag(flags.limit, 'limit', 25, 1, 100000) };
+      break;
+    }
+    case 'tool': {
+      if (args.length !== 1) throw new QueryInputError('q tool takes one tool name (q tools lists them)');
+      const f = filtersFrom(flags);
+      if (Array.isArray(f.harness)) throw new QueryInputError('q tool takes one --harness');
+      out.opts = { tool: args[0], filters: f, limit: intFlag(flags.limit, 'limit', 50, 1, 1000), chars: intFlag(flags.chars, 'chars', 300, 0, 10000000) };
+      break;
+    }
+    case 'activity': {
+      if (args.length) throw new QueryInputError('q activity takes flags only');
+      const grain = flags.grain === undefined ? 'sessions' : strFlag(flags.grain, 'grain');
+      if (!['sessions', 'usage'].includes(grain)) throw new QueryInputError('--grain is sessions or usage');
+      const by = flags.by === undefined ? ['day'] : listFlag(flags.by);
+      const allowed = grain === 'usage' ? Object.keys({ ...Q.SESSION_DIMS, ...Q.USAGE_DIMS }) : Object.keys(Q.SESSION_DIMS);
+      for (const d of by) if (!allowed.includes(d)) throw new QueryInputError(`--by ${d}: not a ${grain} dimension (${allowed.join(', ')})`);
+      out.opts = { grain, by, filters: filtersFrom(flags), tz: strFlag(flags.tz, 'tz') || 'UTC', limit: flags.limit === undefined ? null : intFlag(flags.limit, 'limit', 100, 1, 100000) };
+      break;
+    }
+    case 'removed':
+      if (args.length > 1) throw new QueryInputError('q removed takes at most one session');
+      if (args.length) out.ref = parseRef(args[0], flags);
+      out.opts = {
+        harness: strFlag(flags.harness, 'harness'), days: flags.days === undefined ? null : intFlag(flags.days, 'days', 14, 1, 100000),
+        limit: intFlag(flags.limit, 'limit', 50, 1, 1000), chars: intFlag(flags.chars, 'chars', 200, 0, 100000),
+      };
+      break;
+    case 'version':
+      if (args.length > 1) throw new QueryInputError('q version takes at most one session');
+      if (args.length) out.ref = parseRef(args[0], flags);
+      break;
+    default: break;
+  }
+  return out;
+}
+
+function agentFlag(v) {
+  if (v === undefined || v === null) return null;
+  if (v === true) throw new QueryInputError('--agent needs an agent id, or main for the main conversation');
+  return String(v) === 'main' ? '' : String(v);
+}
+
+// ── running ───────────────────────────────────────────────────────────────────────
+
+const iso = (ms) => (ms === null || ms === undefined || ms === '' || !Number.isFinite(Number(ms)) ? null : new Date(Number(ms)).toISOString());
+const num = (v) => Number(v) || 0;
+const cap = (s, n) => (n && typeof s === 'string' && s.length > n ? `${s.slice(0, n)}… [${s.length - n} more chars]` : s);
+
+/** Every `<x>_ms` field gets a readable `<x>_at` beside it (agents read ISO, not epoch ms). */
+function withIso(row) {
+  const out = { ...row };
+  for (const [k, v] of Object.entries(row)) if (k.endsWith('_ms') && v !== null && v !== undefined) out[`${k.slice(0, -3)}_at`] = iso(v);
+  return out;
+}
+const refOf = (r) => Q.sessionRef(r);
+
+/** A bare session id (no harness) resolved through sessions FINAL: unique, or a clear error. */
+function lookupSpec(rooms, sessionId) {
+  return {
+    query: 'lookupSession', final: 'sessions', settings: {}, params: { s: String(sessionId) },
+    sql: `SELECT harness, session_id, host, harness_path, incarnation FROM ${rooms.sessions} FINAL WHERE session_id = {s:String} AND is_deleted = 0 AND removed = 0 ORDER BY harness, ended DESC LIMIT 5`,
+  };
+}
+async function resolveRef(exec, rooms, ref) {
+  if (ref.harness) return ref;
+  const rows = await exec(lookupSpec(rooms, ref.session_id));
+  if (!rows.length) { const e = new QueryInputError(`no live session '${ref.session_id}' (give <harness>:<session_id>)`); e.notFound = true; throw e; }
+  // One id in several harnesses or stores (two hosts, two incarnations): each is its own session.
+  if (rows.length > 1) throw new QueryInputError(`'${ref.session_id}' names ${rows.length} sessions (${rows.map((r) => `${r.harness}${r.host ? ` on ${String(r.host).slice(0, 8)}` : ''}`).join(', ')}) — name one: ${rows.map(refOf).join(', ')}`);
+  return Q.parseSessionRef(rows[0]);
+}
+
+/**
+ * The part a window centres on: a message's first part (`at`), or the session's first part at or
+ * after an instant (`ts`). `session_parts FINAL` within the session, is_deleted = 0 AND removed = 0;
+ * the same rows readSession's pages return.
+ */
+function hitSpec(rooms, { harness, session_id, message_id = null, ts = null, agent_id = null, store = null }) {
+  const params = { h: harness, s: session_id };
+  const sp = Q.storePred(store);
+  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 (message_id !== null) { where += ' AND message_id = {mid:String}'; params.mid = String(message_id); }
+  // An untimed part counts by its first_seen, as every other time-bounded read does, but only where no
+  // part with a time qualifies: a session captured late gives its untimed parts the capture day.
+  else { where += ` AND ${Q.tsBound('>=', `fromUnixTimestamp64Milli({at:Int64}, 'UTC')`)}`; params.at = Number(ts); }
+  if (agent_id !== null && agent_id !== undefined) { where += ' AND agent_id = {agent:String}'; params.agent = agent_id; }
+  return {
+    query: 'windowHit', final: 'session_parts', settings: {}, params,
+    sql: `SELECT ${Q.PART_SELECT}
+FROM ${rooms.parts} FINAL
+WHERE ${where}
+ORDER BY ${message_id !== null ? '' : 'ts IS NULL, '}order_key, message_id, part_index
+LIMIT 1`,
+  };
+}
+
+/** A part's readable text: a tool call's name and arguments, a tool result's output, else its text. */
+const partText = (t) => Q.partText(t);
+function turnOut(t, chars) {
+  const text = partText(t);
+  return withIso({
+    ts_ms: t.ts_ms === null || t.ts_ms === undefined ? null : num(t.ts_ms), role: t.role, kind: t.kind, agent_id: t.agent_id, message_id: t.message_id, part: num(t.part),
+    model: t.model, text: cap(text, chars), text_len: [...String(text || '')].length,
+    ...(num(t.input_tokens) || num(t.output_tokens) ? { tokens: { input: num(t.input_tokens), output: num(t.output_tokens), cache_read: num(t.cache_read_tokens), cache_write: num(t.cache_write_tokens), reasoning: num(t.reasoning_tokens) } } : {}),
+  });
+}
+function callOut(c, chars) {
+  return withIso({
+    ts_ms: num(c.ts_ms), tool_name: c.tool_name, agent_id: c.agent_id, call_id: c.call_id, message_id: c.message_id,
+    args: cap(c.args, chars), is_error: Boolean(c.is_error === true || c.is_error === 1 || c.is_error === '1'),
+    result_len: num(c.result_len), result_ts_ms: c.result_ts_ms === null || c.result_ts_ms === undefined ? null : num(c.result_ts_ms),
+  });
+}
+function headerOut(h) {
+  const { days, ...rest } = h;
+  return { ref: refOf(h), ...withIso(rest), days: (days || []).map(String) };
+}
+
+function priceRow(model, r) {
+  const { calculateCost } = require('../../pricing');
+  return calculateCost(model, num(r.input_tokens), num(r.output_tokens), num(r.cache_read_tokens), num(r.cache_write_tokens));
+}
+
+/** Run one parsed q against an exec. Returns the JSON-able result. */
+async function runQ(exec, rooms, p, { schema = 3 } = {}) {
+  const o = p.opts || {};
+  switch (p.name) {
+    case 'schema': return { schema };
+    case 'list': return { names: Object.entries(NAMES).map(([name, d]) => ({ name, aliases: d.aliases || [], usage: `memhouse ${d.usage}`, what: d.what })) };
+    case 'search': {
+      const spec = Q.search(rooms, o);
+      const rows = await exec(spec);
+      return {
+        query: 'search', terms: spec.terms,
+        hits: rows.map((h) => ({ ref: refOf(h), ...withIso({ ...h, hits: num(h.hits) }) })),
+        next: 'read a hit with: memhouse q window <ref> --at <message_id>',
+      };
+    }
+    case 'recent': {
+      const r = await Q.run(exec, Q.listSessions(rooms, o));
+      return {
+        query: 'recent', sessions: r.rows.map((s) => ({ ref: refOf(s), ...withIso(s) })), nextCursor: r.nextCursor,
+        next: 'read one with: memhouse q session <ref>, or its opening turns: memhouse q window <ref> (--ts <time> for a moment in it)',
+      };
+    }
+    case 'session': {
+      const ref = await resolveRef(exec, rooms, p.ref);
+      const r = await Q.readSession(exec, rooms, { ...ref, cursor: o.cursor, dir: o.dir, limit: o.limit, agent_id: o.agent_id });
+      if (!r) return notFound(ref);
+      return {
+        query: 'session', header: headerOut(r.header),
+        turns: r.turns.map((t) => turnOut(t, o.chars)), calls: r.calls.map((c) => callOut(c, o.chars)),
+        nextCursor: r.nextCursor, prevCursor: r.prevCursor,
+      };
+    }
+    case 'window': {
+      const ref = await resolveRef(exec, rooms, p.ref);
+      const header = await Q.run(exec, Q.sessionHeader(rooms, ref));
+      if (!header) return notFound(ref);
+      // The header names the store; the hit and its window are read from that store only.
+      const store = { host: header.host, harness_path: header.harness_path, incarnation: header.incarnation };
+      let center = null;
+      if (o.at) {
+        const [hit] = await exec(hitSpec(rooms, { ...ref, message_id: o.at, agent_id: o.agent_id, store }));
+        if (!hit) throw Object.assign(new QueryInputError(`no live turn '${o.at}' in ${refOf(ref)}`), { notFound: true });
+        center = hit;
+      }
+      // The window pivots on the hit, or with --ts on the first part at or after that instant (none:
+      // the window is the session's tail before it). The cursor is the pivot's full order key.
+      // With neither: the first part from the beginning of time, so nothing comes before it.
+      const [pivot] = center ? [center] : await exec(hitSpec(rooms, { ...ref, ts: o.start ? 0 : o.ts, agent_id: o.agent_id, store }));
+      const key = pivot ? [pivot.order_key, pivot.message_id, num(pivot.part)] : null;
+      const page = async (dir, limit) => {
+        if (!limit || (!key && dir === 'forward')) return [];
+        const rows = await exec(Q.partsPage(rooms, { ...ref, cursor: key, dir, limit, agent_id: o.agent_id, store }));
+        return rows.slice(0, limit);
+      };
+      const before = (await page('backward', o.before)).reverse();
+      const after = await page('forward', o.after);
+      const turns = [...before, ...(pivot ? [pivot] : []), ...after];
+      // Tokens on the messages that start in the window (a response's on its first message).
+      const starts = [...new Set(turns.filter((t) => num(t.part) === 0).map((t) => t.message_id))];
+      Q.attachUsage(turns, await Q.run(exec, Q.usageOf(rooms, { ...ref, store, message_ids: starts, response_ids: [...new Set(turns.map((t) => t.response_id).filter(Boolean))] })));
+      return {
+        query: 'window', ref: refOf(ref), name: header.name, folder: header.folder, project: header.project,
+        at: center ? center.message_id : null, at_ts: center ? iso(center.ts_ms) : o.start ? null : iso(o.ts), ...(o.start ? { from: 'start' } : {}),
+        turns: turns.map((t) => ({ ...turnOut(t, o.chars), ...(center && t.message_id === center.message_id && num(t.part) === num(center.part) && t.agent_id === center.agent_id ? { hit: true } : {}) })),
+        agents: header.agents,
+      };
+    }
+    case 'agents': {
+      const ref = await resolveRef(exec, rooms, p.ref);
+      const header = await Q.run(exec, Q.sessionHeader(rooms, ref));
+      if (!header) return notFound(ref);
+      return { query: 'agents', ref: refOf(ref), name: header.name, agents: header.agents.map(withIso) };
+    }
+    case 'aggregate': {
+      const rows = await exec(Q.aggregate(rooms, o));
+      return { query: `aggregate:${o.source}`, rows: rows.map(withIso) };
+    }
+    case 'spend': {
+      const dims = o.by === 'model' ? ['price_model'] : [o.by, 'price_model'];
+      const rows = await exec(Q.aggregate(rooms, {
+        source: 'usage', dims, filters: o.filters, tz: o.tz,
+        metrics: ['sessions', 'messages', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens'],
+      }));
+      const groups = new Map();
+      const unpriced = new Set();
+      let total = 0;
+      for (const r of rows) {
+        const g = o.by === 'model' ? r.price_model : r[o.by];
+        const cost = r.price_model ? priceRow(r.price_model, r) : null;
+        const toks = num(r.input_tokens) + num(r.output_tokens) + num(r.cache_read_tokens) + num(r.cache_write_tokens);
+        if (cost === null && toks) unpriced.add(r.price_model || '(no model)');
+        if (cost !== null) total += cost;
+        const x = groups.get(g) || { [o.by]: g, messages: 0, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, reasoning_tokens: 0, cost: 0, priced: true };
+        for (const k of ['messages', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens']) x[k] += num(r[k]);
+        if (cost === null) { if (toks) x.priced = false; } else x.cost += cost;
+        groups.set(g, x);
+      }
+      let out = [...groups.values()].map((x) => ({ ...x, cost: Math.round(x.cost * 100) / 100 }));
+      out.sort((a, b) => (o.by === 'day' || o.by === 'month') ? String(b[o.by]).localeCompare(String(a[o.by])) : (b.cost - a.cost) || (b.output_tokens - a.output_tokens));
+      if (o.limit) out = out.slice(0, o.limit);
+      return {
+        query: 'spend', by: o.by, rows: out, total_cost: Math.round(total * 100) / 100, unpriced: [...unpriced].sort(),
+        note: 'cost is derived (pricing.json × tokens); an unpriced model costs nothing here — it is unknown, not free. Converted 0.18 Claude Code sessions count usage once per inferred response run (about 1.1× the billed figure where the transcript is gone); captured ones per real response.',
+      };
+    }
+    case 'models': {
+      const rows = await exec(Q.aggregate(rooms, {
+        source: 'usage', dims: ['model'], filters: o.filters, where: { excludeModels: true },
+        metrics: ['sessions', 'messages', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens', 'first_hour_ms', 'last_hour_ms'],
+        order: [['messages', 'desc']], ...(o.limit ? { limit: o.limit } : {}),
+      }));
+      let total = 0;
+      const out = rows.map((r) => { const cost = priceRow(r.model, r); if (cost !== null) total += cost; return withIso({ ...r, cost: cost === null ? null : Math.round(cost * 100) / 100 }); });
+      return { query: 'models', rows: out, total_cost: Math.round(total * 100) / 100 };
+    }
+    case 'tools': {
+      const rows = await exec(Q.aggregate(rooms, { source: 'tools', dims: ['tool'], metrics: ['calls', 'errors', 'sessions'], filters: o.filters, order: [['calls', 'desc']], limit: o.limit || 25 }));
+      return { query: 'tools', rows, next: 'one tool\'s calls: memhouse q tool <name>' };
+    }
+    case 'tool': {
+      const rows = await exec(Q.tools(rooms, o));
+      return { query: 'tool', tool: o.tool, calls: rows.map((c) => ({ ref: refOf(c), session_name: c.session_name, folder: c.folder, project: c.project, host: c.host, ...callOut(c, o.chars) })) };
+    }
+    case 'activity': {
+      const usage = o.grain === 'usage';
+      const metrics = usage ? ['sessions', 'messages', 'input_tokens', 'output_tokens'] : ['sessions', 'messages', 'tool_calls', 'input_tokens', 'output_tokens'];
+      const timeDims = ['day', 'month', 'hour', 'dow'];
+      const order = o.by.map((d) => [d, timeDims.includes(d) && (d === 'day' || d === 'month') ? 'desc' : 'asc']);
+      const rows = await exec(Q.aggregate(rooms, { source: usage ? 'usage' : 'sessions', dims: o.by, metrics, filters: o.filters, tz: o.tz, order, ...(o.limit ? { limit: o.limit } : {}) }));
+      return { query: `activity:${o.grain}`, by: o.by, rows, note: usage ? 'messages and tokens bucketed by the hour they happened' : 'sessions bucketed by when they started' };
+    }
+    case 'hosts': {
+      const rows = await exec(Q.aggregate(rooms, {
+        dims: ['host'], filters: o.filters,
+        metrics: ['sessions', 'messages', 'tool_calls', 'input_tokens', 'output_tokens', 'first_started_ms', 'last_ended_ms'],
+        order: [['last_ended_ms', 'desc']],
+      }));
+      // One machine under its 0.18 id and its new one reads as one (host-alias.js).
+      const folded = HA.foldRows(rows, rooms.hostAliases, { sum: ['sessions', 'messages', 'tool_calls', 'input_tokens', 'output_tokens'], min: ['first_started_ms'], max: ['last_ended_ms'] })
+        .sort((a, b) => Number(b.last_ended_ms || 0) - Number(a.last_ended_ms || 0));
+      return { query: 'hosts', rows: folded.map(withIso) };
+    }
+    case 'coverage': {
+      const r = await Q.run(exec, Q.coverage(rooms));
+      const hosts = (h) => [...new Set((h || []).map((x) => HA.fold(x, rooms.hostAliases)))].sort();
+      return { query: 'coverage', harnesses: r.harnesses.map((x) => withIso({ ...x, hosts: hosts(x.hosts) })), total: withIso(r.total) };
+    }
+    case 'machines': return { query: 'machines', rows: machinesFolded(await exec(Q.machines(rooms)), rooms).map(withIso) };
+    case 'count': return { query: 'count', sessions: await Q.run(exec, Q.countSessions(rooms, o.filters)) };
+    case 'removed': {
+      const o2 = { ...o };
+      if (p.ref) {
+        const ref = await resolveRef(exec, rooms, p.ref);
+        Object.assign(o2, { harness: ref.harness, session_id: ref.session_id, store: ref.host != null && ref.harness_path != null ? ref : null });
+      }
+      const rows = await exec(Q.removedContent(rooms, o2));
+      return { query: 'removed', messages: rows.map((r) => ({ ref: refOf(r), message_id: r.message_id, role: r.role, state: r.state, ts_at: iso(r.ts_ms), parts: Number(r.parts), snippet: r.snippet })) };
+    }
+    case 'version': {
+      if (!p.ref) return { query: 'version', ...(await Q.run(exec, Q.houseVersion(rooms))) };
+      const ref = await resolveRef(exec, rooms, p.ref);
+      const v = await Q.run(exec, Q.sessionVersion(rooms, ref));
+      return v ? { query: 'version', ref: refOf(ref), ...withIso(v) } : notFound(ref);
+    }
+    default: throw new QueryInputError(`no named query '${p.name}'`);
+  }
+}
+function notFound(ref) { return { error: 'not_found', ref: refOf(ref), message: `no live session ${refOf(ref)}` }; }
+
+// ── rendering for a human ─────────────────────────────────────────────────────────
+
+function table(rows, cols) {
+  if (!rows.length) return ['  (no rows)'];
+  const cells = rows.map((r) => cols.map((c) => { const v = typeof c.get === 'function' ? c.get(r) : r[c.key]; return v === null || v === undefined ? '' : String(v); }));
+  const w = cols.map((c, i) => Math.min(c.max || 60, Math.max(c.title.length, ...cells.map((x) => x[i].length))));
+  const fit = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+  const line = (vals) => `  ${vals.map((v, i) => (cols[i].right ? fit(v, w[i]).padStart(w[i]) : fit(v, w[i]).padEnd(w[i]))).join('  ')}`.trimEnd();
+  return [line(cols.map((c) => c.title)), ...cells.map(line)];
+}
+const day = (s) => (s ? String(s).slice(0, 16).replace('T', ' ') : '');
+const oneLine = (s, n = 160) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, n);
+
+function renderQ(name, r) {
+  if (r && r.error) return [`  ${r.message || r.error}`];
+  switch (name) {
+    case 'schema': return [String(r.schema)];
+    case 'list': return ['memhouse q <name> [--json] — the named queries:', '',
+      ...r.names.map((n) => `  ${n.name.padEnd(9)} ${n.what}\n            ${n.usage}${n.aliases.length ? `   (also: ${n.aliases.join(', ')})` : ''}`),
+      '', '  Every name takes --member <name> to read a housemate\'s tables you were granted, and --json.'];
+    case 'search': {
+      if (!r.hits.length) return [`  no live turn holds ${r.terms.map((t) => `'${t}'`).join(' and ')}`];
+      const out = [];
+      for (const h of r.hits) {
+        out.push(`\x1b[1m${h.ref}\x1b[0m  ${h.project || h.folder || '-'}  ${day(h.last_hit_at)}  (${h.hits} hit${h.hits === 1 ? '' : 's'}${h.name ? ` · ${oneLine(h.name, 60)}` : ''})`);
+        out.push(`  ${h.role}${h.agent_id ? ` [agent ${h.agent_id}]` : ''} ${h.message_id}: ${oneLine(h.snippet)}`);
+      }
+      out.push('', `  ${r.next}`);
+      return out;
+    }
+    case 'recent': return [...table(r.sessions, [
+      { title: 'ref', key: 'ref', max: 50 }, { title: 'last active', get: (s) => day(s.ended_at) }, { title: 'msgs', key: 'messages', right: true },
+      { title: 'host', key: 'host', max: 24 }, { title: 'project', get: (s) => s.project || s.folder, max: 30 }, { title: 'name', get: (s) => oneLine(s.name || s.first_prompt, 60) },
+    ]), ...(r.nextCursor ? ['', `  more: --cursor ${r.nextCursor}`] : []), ...(r.sessions.length && r.next ? ['', `  ${r.next}`] : [])];
+    case 'session': case 'window': {
+      const h = name === 'session' ? r.header : r;
+      const out = [`\x1b[1m${h.ref}\x1b[0m  ${h.name ? oneLine(h.name, 80) : ''}`, `  ${h.project || h.folder || ''}${name === 'session' ? `  ${day(h.started_at)} → ${day(h.ended_at)}  ${h.messages} messages` : ''}`, ''];
+      const calls = name === 'session' ? r.calls : [];
+      // The parts in the order the read gave (the session's order_key: a part may have no time), each
+      // call after the part of its message, or by its time when its message is not on the page.
+      const pos = new Map(r.turns.map((t, i) => [String(t.message_id), i]));
+      const after = (c) => {
+        if (pos.has(String(c.message_id))) return pos.get(String(c.message_id)) + 0.5;
+        let k = -1;
+        r.turns.forEach((t, i) => { if (t.ts_ms != null && c.ts_ms != null && t.ts_ms <= c.ts_ms) k = i; });
+        return k + 0.5;
+      };
+      const items = [...r.turns.map((t, i) => ({ t, at: i })), ...calls.map((c) => ({ c, at: after(c) }))].sort((a, b) => a.at - b.at);
+      for (const it of items) {
+        if (it.t) {
+          const t = it.t;
+          out.push(`${t.hit ? '\x1b[1m>>' : '  '} ${day(t.ts_at)} ${t.role}${t.kind !== 'text' ? `/${t.kind}` : ''}${t.agent_id ? ` [agent ${t.agent_id}]` : ''}${t.hit ? '\x1b[0m' : ''}`);
+          for (const l of String(t.text || '').split('\n')) out.push(`     ${l}`);
+        } else out.push(`   ${day(it.c.ts_at)} tool ${it.c.tool_name}${it.c.is_error ? ' (error)' : ''}: ${oneLine(it.c.args, 200)}`);
+      }
+      if (r.nextCursor) out.push('', `  next page: --cursor ${r.nextCursor}`);
+      if (r.prevCursor) out.push('', `  previous page: --cursor ${r.prevCursor} --dir backward`);
+      return out;
+    }
+    case 'agents': return [`${r.ref}  ${oneLine(r.name, 80)}`, ...table(r.agents, [
+      { title: 'agent', key: 'agent_id', max: 40 }, { title: 'type', key: 'type', max: 24 }, { title: 'turns', key: 'messages', right: true },
+      { title: 'first', get: (a) => day(a.first_at) }, { title: 'asked to', get: (a) => oneLine(a.description, 70) }])];
+    case 'spend': return [...table(r.rows, [
+      { title: r.by, key: r.by, max: 40 }, { title: 'messages', key: 'messages', right: true }, { title: 'input', key: 'input_tokens', right: true },
+      { title: 'output', key: 'output_tokens', right: true }, { title: 'cache read', key: 'cache_read_tokens', right: true },
+      { title: 'cache write', key: 'cache_write_tokens', right: true }, { title: 'cost $', get: (x) => (x.priced ? x.cost.toFixed(2) : `${x.cost.toFixed(2)}+?`), right: true }]),
+    '', `  total $${r.total_cost.toFixed(2)}${r.unpriced.length ? `   unpriced (cost unknown): ${r.unpriced.join(', ')}` : ''}`, `  ${r.note}`];
+    case 'models': return [...table(r.rows, [
+      { title: 'model', key: 'model', max: 40 }, { title: 'sessions', key: 'sessions', right: true }, { title: 'messages', key: 'messages', right: true },
+      { title: 'input', key: 'input_tokens', right: true }, { title: 'output', key: 'output_tokens', right: true },
+      { title: 'cost $', get: (x) => (x.cost === null ? 'unpriced' : x.cost.toFixed(2)), right: true }, { title: 'last', get: (x) => day(x.last_hour_at) }]),
+    '', `  total $${r.total_cost.toFixed(2)}`];
+    case 'tools': return table(r.rows, [{ title: 'tool', key: 'tool', max: 50 }, { title: 'calls', key: 'calls', right: true }, { title: 'errors', key: 'errors', right: true }, { title: 'sessions', key: 'sessions', right: true }]);
+    case 'tool': return table(r.calls, [{ title: 'when', get: (c) => day(c.ts_at) }, { title: 'ref', key: 'ref', max: 50 }, { title: 'err', get: (c) => (c.is_error ? 'x' : '') }, { title: 'args', get: (c) => oneLine(c.args, 100) }]);
+    case 'hosts': return table(r.rows, [{ title: 'host', key: 'host', max: 40 }, { title: 'sessions', key: 'sessions', right: true }, { title: 'messages', key: 'messages', right: true }, { title: 'first', get: (x) => day(x.first_started_at) }, { title: 'last', get: (x) => day(x.last_ended_at) }]);
+    case 'machines': return table(r.rows, [{ title: 'host', key: 'host', max: 40 }, { title: 'sessions', key: 'sessions', right: true }, { title: 'harnesses', get: (x) => (x.harnesses || []).join(',') }, { title: 'last', get: (x) => day(x.last_at) }]);
+    case 'coverage': return [...table(r.harnesses, [{ title: 'harness', key: 'harness' }, { title: 'sessions', key: 'sessions', right: true }, { title: 'messages', key: 'messages', right: true }, { title: 'first', get: (x) => day(x.first_at) }, { title: 'last', get: (x) => day(x.last_at) }, { title: 'hosts', get: (x) => (x.hosts || []).join(',') }, { title: 'origins', get: (x) => (x.origins || []).join(',') }]),
+      '', `  total: ${r.total.sessions} sessions, ${r.total.messages} messages, ${day(r.total.first_at)} → ${day(r.total.last_at)}`];
+    case 'count': return [String(r.sessions)];
+    case 'removed': return r.messages.length ? table(r.messages, [{ title: 'when', get: (m) => day(m.ts_at) }, { title: 'ref', key: 'ref', max: 50 }, { title: 'message', key: 'message_id', max: 28 }, { title: 'role', key: 'role' }, { title: 'state', get: (m) => m.state || 'removed' }, { title: 'text', get: (m) => oneLine(m.snippet, 80) }]) : ['  (no removed content)'];
+    case 'version': return [r.ref ? `${r.ref} rev ${r.rev} (${r.messages} messages, last ${day(r.ended_at)})` : `${r.token}  (${r.sessions} sessions, last ${day(iso(r.last_ms))})`];
+    case 'aggregate': case 'activity': {
+      const rows = r.rows || [];
+      if (!rows.length) return ['  (no rows)'];
+      const cols = Object.keys(rows[0]).filter((k) => !k.endsWith('_ms')).map((k) => ({ title: k, key: k, right: typeof rows[0][k] === 'number' }));
+      return table(rows, cols);
+    }
+    default: return [JSON.stringify(r, null, 2)];
+  }
+}
+
+// ── room-sql: SQL over the member's tables by their bare names ────────────────────
+
+const V3_BARE = ['session_parts', 'session_usage', 'session_links', 'session_lifecycle', 'calls', 'sessions', 'meta', 'events'];
+const V2_BARE = ['messages', 'tool_calls', 'sessions', 'meta', 'events'];
+
+/**
+ * Rewrite bare table names after FROM / JOIN to the member's physical names, OUTSIDE string
+ * literals and quoted identifiers (a needle like '%from sessions%' is text, not a table). A name
+ * already qualified (`mem.x`) or prefixed (`bob_sessions`) is left alone: the match needs
+ * whitespace before the bare word and a boundary after it. The statement's own head names a table
+ * too — `DESCRIBE sessions`, `DESC TABLE calls`, `SHOW CREATE sessions`, `EXISTS TABLE meta` — and
+ * left bare it reached the server as `<db>.sessions`, which no member may read, so a member asking
+ * for its own columns was told it lacked the privilege.
+ *
+ * @param {string} sql
+ * @param {{ member, db, schema }} o  schema 3 → the profile's tables, meta and events; 2 → the 0.18 rooms
+ */
+function rewriteRooms(sql, { member, db = null, schema = 3 }) {
+  if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(String(member || ''))) throw new QueryInputError(`'${member}' is not a member name`);
+  const names = schema === 3 ? V3_BARE : V2_BARE;
+  const qual = (t) => `${db ? `${db}.` : ''}${member}_${t}`;
+  const re = new RegExp(`(^|[\\s(,])(FROM|JOIN)(\\s+)(${names.join('|')})(?=$|[\\s;,)])`, 'gi');
+  const head = new RegExp(`^(\\s*)((?:DESCRIBE|DESC|EXISTS|SHOW\\s+CREATE)(?:\\s+TABLE)?)(\\s+)(${names.join('|')})(?=$|[\\s;,)])`, 'i');
+  let out = ''; let i = 0; let buf = ''; let atHead = true;   // nothing but comments and blanks so far
+  const flush = () => {
+    let b = buf;
+    if (atHead && /\S/.test(b)) { b = b.replace(head, (m, pre, kw, sp, t) => `${pre}${kw}${sp}${qual(t.toLowerCase())}`); atHead = false; }
+    out += b.replace(re, (m, pre, kw, sp, t) => `${pre}${kw}${sp}${qual(t.toLowerCase())}`); buf = '';
+  };
+  while (i < sql.length) {
+    const c = sql[i];
+    if (c === "'" || c === '"' || c === '`') {
+      flush(); atHead = false;
+      let j = i + 1;
+      while (j < sql.length) {
+        if (sql[j] === '\\') { j += 2; continue; }
+        if (sql[j] === c) { if (sql[j + 1] === c) { j += 2; continue; } break; }
+        j++;
+      }
+      out += sql.slice(i, j + 1); i = j + 1; continue;
+    }
+    if (c === '-' && sql[i + 1] === '-') { flush(); const j = sql.indexOf('\n', i); const e = j === -1 ? sql.length : j; out += sql.slice(i, e); i = e; continue; }
+    if (c === '/' && sql[i + 1] === '*') { flush(); const j = sql.indexOf('*/', i + 2); const e = j === -1 ? sql.length : j + 2; out += sql.slice(i, e); i = e; continue; }
+    buf += c; i++;
+  }
+  flush();
+  return out;
+}
+
+/** Does this statement already name its output FORMAT? (trailing, after comments are gone) */
+function hasFormat(sql) {
+  const s = String(sql).replace(/--[^\n]*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '').trim().replace(/;\s*$/, '');
+  return /\bFORMAT\s+[A-Za-z0-9_]+\s*$/i.test(s);
+}
+
+/** Refuse what is not a read before it leaves the machine (the server's readonly=2 refuses it too). */
+function assertRead(sql) {
+  const s = String(sql).replace(/--[^\n]*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '').trim();
+  if (!s) throw new QueryInputError('no SQL given');
+  if (!/^(SELECT|WITH|SHOW|DESCRIBE|DESC|EXPLAIN|EXISTS|\()/i.test(s)) throw new QueryInputError('room-sql runs reads only (SELECT, WITH, SHOW, DESCRIBE, EXPLAIN)');
+  if (/;\s*\S/.test(s.replace(/'(?:[^'\\]|\\.|'')*'/g, "''"))) throw new QueryInputError('one statement at a time');
+}
+
+// ── stats / status / sessions-query on schema 3 ───────────────────────────────────
+
+/** `memhouse stats`: per harness, from sessions FINAL (≤ one row per session). */
+async function statsV3(exec, rooms) {
+  const rows = await exec(Q.aggregate(rooms, {
+    dims: ['harness'], order: [['sessions', 'desc']],
+    metrics: ['sessions', 'messages', 'tool_calls', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'last_ended_ms'],
+  }));
+  const out = rows.map((r) => withIso({ ...r, tokens: num(r.input_tokens) + num(r.output_tokens) + num(r.cache_read_tokens) + num(r.cache_write_tokens) }));
+  const total = out.reduce((a, r) => ({ sessions: a.sessions + num(r.sessions), messages: a.messages + num(r.messages), tool_calls: a.tool_calls + num(r.tool_calls), tokens: a.tokens + r.tokens }), { sessions: 0, messages: 0, tool_calls: 0, tokens: 0 });
+  return { schema: 3, harnesses: out, total };
+}
+function renderStats(s) {
+  if (!s.harnesses.length) return ['house is empty'];
+  return table([...s.harnesses, { harness: 'total', ...s.total }], [
+    { title: 'harness', key: 'harness' }, { title: 'sessions', key: 'sessions', right: true }, { title: 'messages', key: 'messages', right: true },
+    { title: 'tool calls', key: 'tool_calls', right: true }, { title: 'tokens', key: 'tokens', right: true }, { title: 'last active', get: (r) => day(r.last_ended_at) }]).map((l) => l.slice(2));
+}
+
+/**
+ * What `status` reads on schema 3: counts, freshness and the machines, all from sessions FINAL
+ * (one row per session — the table is small by design). The freshest write is max(ingested_at)
+ * over the session rows: the capture rewrites a session's row on every change.
+ */
+function statusSpec(rooms) {
+  return {
+    query: 'status', final: 'sessions', settings: {}, params: {},
+    sql: `SELECT host, count() AS sessions, sum(messages) AS messages, sum(tool_calls) AS tool_calls,
+       toUnixTimestamp64Milli(max(ingested_at)) AS last_write_ms, toUnixTimestamp64Milli(max(ended)) AS last_active_ms,
+       arraySort(groupUniqArray(harness)) AS harnesses
+FROM ${rooms.sessions} FINAL
+WHERE is_deleted = 0 AND removed = 0
+GROUP BY host
+ORDER BY last_write_ms DESC, host`,
+  };
+}
+/** Q.machines rows with a machine's 0.18 id folded into it (host-alias.js); doctor uses the same. */
+function machinesFolded(rows, rooms) {
+  return HA.foldRows(rows, rooms && rooms.hostAliases, { sum: ['sessions'], max: ['last_ms'], union: ['harnesses'], any: ['label'] })
+    .sort((a, b) => Number(b.last_ms || 0) - Number(a.last_ms || 0));
+}
+
+async function statusV3(exec, rooms) {
+  const hosts = HA.foldRows(await exec(statusSpec(rooms)), rooms.hostAliases, {
+    sum: ['sessions', 'messages', 'tool_calls'], max: ['last_write_ms', 'last_active_ms'], union: ['harnesses'],
+  }).sort((a, b) => Number(b.last_write_ms || 0) - Number(a.last_write_ms || 0)).map(withIso);
+  const t = hosts.reduce((a, h) => ({
+    sessions: a.sessions + num(h.sessions), messages: a.messages + num(h.messages), tool_calls: a.tool_calls + num(h.tool_calls),
+    last_write_ms: Math.max(a.last_write_ms, num(h.last_write_ms)),
+  }), { sessions: 0, messages: 0, tool_calls: 0, last_write_ms: 0 });
+  return { ...t, freshest: t.last_write_ms ? iso(t.last_write_ms) : null, hosts };
+}
+
+/**
+ * `memhouse sessions-query` on schema 3. The sessions table IS the rollup now (exact totals,
+ * one row per session), so this is that table read FINAL with tombstones dropped — plus the
+ * 0.18 rollup's column names as aliases, so `FROM $(memhouse sessions-query) AS c` keeps working
+ * for the common columns. `session_id` is the NATIVE id now; `id` is `<harness>:<session_id>`.
+ */
+function sessionsQueryV3(rooms) {
+  return `(
+    SELECT concat(harness, ':', session_id) AS id, harness, session_id, harness AS source, ${Q.ROOT_LABEL('harness_path')} AS root, harness_path, host, title AS name, mode,
+           folder, project, git_branch, created_at, updated_at, updated_at AS last_updated_at, started, ended,
+           dateDiff('second', started, ended) AS duration_sec,
+           messages, messages AS total_msgs, user_messages, user_messages AS user_msgs,
+           assistant_messages, assistant_messages AS assistant_msgs, agent_messages, agent_messages AS subagent_msgs,
+           tool_calls, models, dominant_model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+           reasoning_tokens, user_chars, assistant_chars, first_prompt, days, origin, writer AS user_id
+    FROM ${rooms.sessions} FINAL
+    WHERE is_deleted = 0 AND removed = 0
+  )`;
+}
+
+/** `memhouse resume` on schema 3: the session row, by `<harness>:<id>` or a bare native id. */
+function resumeSpec(rooms, ref) {
+  const params = { s: ref.session_id };
+  let where = 'session_id = {s:String} AND is_deleted = 0 AND removed = 0';
+  if (ref.harness) { where = `harness = {h:String} AND ${where}`; params.h = ref.harness; }
+  if (ref.host != null) {
+    where += ' AND host = {r_host:String} AND harness_path = {r_hp:String} AND incarnation = {r_inc:String}';
+    Object.assign(params, { r_host: String(ref.host), r_hp: String(ref.harness_path), r_inc: String(ref.incarnation || '') });
+  }
+  return {
+    query: 'resume', final: 'sessions', settings: {}, params,
+    sql: `SELECT harness, session_id, host, harness_path, incarnation, folder, title AS name, origin, toUnixTimestamp64Milli(ended) AS ended_ms
+FROM ${rooms.sessions} FINAL
+WHERE ${where}
+ORDER BY ended DESC
+LIMIT 5`,
+  };
+}
+
+/**
+ * Keep the blocks of a delivery text that belong to this schema. A block is
+ *   <!-- schema 3 --> … <!-- end schema 3 -->
+ * and is dropped, markers and all, when the install is on the other schema; the markers of a
+ * kept block are dropped too. Text outside any block is kept as is. (PROMPT.md is rendered
+ * this way by `memhouse prompt`; the plugin skills, which are copied verbatim, carry both and
+ * choose at run time with `memhouse q schema`.)
+ */
+function renderSchemaBlocks(text, schema) {
+  const re = /^<!-- schema ([23]) -->\n([\s\S]*?)^<!-- end schema \1 -->\n?/gm;
+  return String(text).replace(re, (m, which, body) => (Number(which) === Number(schema) ? body : ''));
+}
+
+module.exports = {
+  renderSchemaBlocks,
+  NAMES, ALIASES, FILTER_FLAGS, QueryInputError,
+  schemaOf, httpTransport, fmtTop, fmtInner, parseWhen, filtersFrom, parseRef, parseQ, runQ, renderQ, allQFlags, canonicalName,
+  resolveRef, hitSpec, lookupSpec, withIso, rewriteRooms, hasFormat, assertRead, statsV3, renderStats, statusV3, statusSpec, machinesFolded,
+  sessionsQueryV3, resumeSpec, table,
+};