polygram 0.1.0

package/scripts/split-db.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Phase 8 - one-time migration: split shared `bridge.db` into per-bot DBs.
+ *
+ * Usage:
+ *   node scripts/split-db.js --config config.json [--src bridge.db] [--dry-run]
+ *
+ * Behaviour:
+ *   1. Reads config.json to learn the bot set and which chat belongs to whom.
+ *   2. For each bot:
+ *        - Creates <bot>.db by opening it (runs all migrations via lib/db.open).
+ *        - Copies sessions, messages, events, chat_migrations, config_changes,
+ *          pair_codes, pairings, pending_approvals scoped to that bot.
+ *   3. Renames the source DB to bridge.db.archived-<ISO-date> unless --dry-run.
+ *
+ * Idempotent: INSERT OR IGNORE / INSERT OR REPLACE throughout. Safe to re-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { open } = require('../lib/db');
+
+function parseArg(argv, flag, required = false) {
+  const i = argv.indexOf(flag);
+  if (i === -1) {
+    if (required) { console.error(`${flag} required`); process.exit(2); }
+    return null;
+  }
+  const v = argv[i + 1];
+  if (!v || v.startsWith('--')) {
+    console.error(`${flag} requires a value`); process.exit(2);
+  }
+  return v;
+}
+
+function hasFlag(argv, flag) {
+  return argv.includes(flag);
+}
+
+function main() {
+  const configPath = parseArg(process.argv, '--config', true);
+  const srcPath = parseArg(process.argv, '--src') || path.join(path.dirname(path.resolve(configPath)), 'bridge.db');
+  const dryRun = hasFlag(process.argv, '--dry-run');
+
+  if (!fs.existsSync(configPath)) { console.error(`config missing: ${configPath}`); process.exit(2); }
+  if (!fs.existsSync(srcPath))    { console.error(`src missing: ${srcPath}`);     process.exit(2); }
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const bots = Object.keys(config.bots || {});
+  if (!bots.length) { console.error('no bots in config'); process.exit(2); }
+
+  const chatToBot = {};
+  for (const [chatId, chat] of Object.entries(config.chats || {})) {
+    chatToBot[chatId] = chat.bot;
+  }
+
+  console.log(`[split-db] src: ${srcPath}`);
+  console.log(`[split-db] bots: ${bots.join(', ')}`);
+  if (dryRun) console.log('[split-db] DRY RUN - no files written or renamed');
+
+  // Refuse to split if a live bridge is writing to srcPath. The WAL file's
+  // presence + recent mtime is a strong proxy: SQLite WAL checkpoints after
+  // ~1000 pages or a clean close, so a hot WAL means an active writer.
+  refuseIfActiveWriter(srcPath);
+
+  const src = open(srcPath);
+  const stats = {};
+
+  // One BEGIN IMMEDIATE transaction over the source gives us a consistent
+  // read snapshot across all per-bot copies. Without this, rows inserted
+  // between bot-A's SELECT and bot-B's SELECT could vanish in the archive.
+  const srcTx = src.raw.transaction(() => {
+    for (const bot of bots) {
+      const target = path.join(path.dirname(srcPath), `${bot}.db`);
+      console.log(`[split-db] ${bot} -> ${target}`);
+      if (dryRun) {
+        stats[bot] = count(src, bot, chatToBot);
+        continue;
+      }
+      const dst = open(target);
+      try {
+        stats[bot] = copy(src, dst, bot, chatToBot);
+      } finally {
+        dst.raw.close();
+      }
+    }
+  });
+  // `transaction` runs deferred by default; we want immediate write-lock
+  // on the source to block any concurrent bridge from slipping in.
+  srcTx.immediate();
+
+  src.raw.close();
+
+  console.log('\n[split-db] copied rows:');
+  for (const [bot, s] of Object.entries(stats)) {
+    console.log(`  ${bot}: messages=${s.messages} sessions=${s.sessions} pairings=${s.pairings} approvals=${s.approvals} pair_codes=${s.pair_codes} config_changes=${s.config_changes} events=${s.events} chat_migrations=${s.chat_migrations}`);
+  }
+
+  if (!dryRun) {
+    const stamp = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19);
+    const archivePath = `${srcPath}.archived-${stamp}`;
+    fs.renameSync(srcPath, archivePath);
+    for (const suf of ['-wal', '-shm']) {
+      if (fs.existsSync(srcPath + suf)) fs.renameSync(srcPath + suf, archivePath + suf);
+    }
+    console.log(`\n[split-db] archived source -> ${archivePath}`);
+  }
+}
+
+function refuseIfActiveWriter(srcPath) {
+  const wal = `${srcPath}-wal`;
+  if (!fs.existsSync(wal)) return;
+  const age = Date.now() - fs.statSync(wal).mtimeMs;
+  // 60s is generous — a clean bridge shutdown checkpoints the WAL.
+  // A hot WAL (< 60s) strongly suggests a live writer.
+  if (age < 60_000) {
+    console.error(`[split-db] refusing: ${wal} is active (mtime ${Math.round(age/1000)}s ago)`);
+    console.error('[split-db] stop the bridge process(es) first: launchctl unload ...');
+    process.exit(3);
+  }
+}
+
+function count(src, bot, chatToBot) {
+  const chatIds = chatIdsForBot(chatToBot, bot);
+  const q = (sql, params = []) => src.raw.prepare(sql).get(...params).n;
+  return {
+    messages:         chatIds.length ? q(`SELECT COUNT(*) AS n FROM messages WHERE chat_id IN (${ph(chatIds.length)}) OR bot_name = ?`, [...chatIds, bot]) : 0,
+    sessions:         chatIds.length ? q(`SELECT COUNT(*) AS n FROM sessions WHERE chat_id IN (${ph(chatIds.length)})`, chatIds) : 0,
+    pair_codes:       q(`SELECT COUNT(*) AS n FROM pair_codes WHERE bot_name = ?`, [bot]),
+    pairings:         q(`SELECT COUNT(*) AS n FROM pairings WHERE bot_name = ?`, [bot]),
+    approvals:        q(`SELECT COUNT(*) AS n FROM pending_approvals WHERE bot_name = ?`, [bot]),
+    config_changes:   chatIds.length ? q(`SELECT COUNT(*) AS n FROM config_changes WHERE chat_id IN (${ph(chatIds.length)})`, chatIds) : 0,
+    events:           q(`SELECT COUNT(*) AS n FROM events`),
+    chat_migrations:  q(`SELECT COUNT(*) AS n FROM chat_migrations`),
+  };
+}
+
+function copy(src, dst, bot, chatToBot) {
+  const chatIds = chatIdsForBot(chatToBot, bot);
+  const stats = {
+    messages: 0, sessions: 0, pair_codes: 0, pairings: 0, approvals: 0,
+    config_changes: 0, events: 0, chat_migrations: 0,
+  };
+
+  const tx = dst.raw.transaction(() => {
+    if (chatIds.length) {
+      const rows = src.raw.prepare(
+        `SELECT * FROM messages WHERE chat_id IN (${ph(chatIds.length)}) OR bot_name = ?`,
+      ).all(...chatIds, bot);
+      const ins = dst.raw.prepare(`
+        INSERT OR IGNORE INTO messages
+          (id, chat_id, thread_id, msg_id, user, user_id, text, reply_to_id,
+           direction, source, bot_name, attachments_json, session_id,
+           model, effort, turn_id, status, error, cost_usd, ts, edited_ts)
+        VALUES
+          (@id, @chat_id, @thread_id, @msg_id, @user, @user_id, @text, @reply_to_id,
+           @direction, @source, @bot_name, @attachments_json, @session_id,
+           @model, @effort, @turn_id, @status, @error, @cost_usd, @ts, @edited_ts)
+      `);
+      for (const r of rows) { if (ins.run(r).changes) stats.messages++; }
+
+      const srows = src.raw.prepare(`SELECT * FROM sessions WHERE chat_id IN (${ph(chatIds.length)})`).all(...chatIds);
+      const sins = dst.raw.prepare(`
+        INSERT OR REPLACE INTO sessions
+          (session_key, chat_id, thread_id, claude_session_id,
+           agent, cwd, model, effort, created_ts, last_active_ts)
+        VALUES
+          (@session_key, @chat_id, @thread_id, @claude_session_id,
+           @agent, @cwd, @model, @effort, @created_ts, @last_active_ts)
+      `);
+      for (const r of srows) { if (sins.run(r).changes) stats.sessions++; }
+
+      const crows = src.raw.prepare(`SELECT * FROM config_changes WHERE chat_id IN (${ph(chatIds.length)})`).all(...chatIds);
+      const cins = dst.raw.prepare(`
+        INSERT OR IGNORE INTO config_changes
+          (id, chat_id, thread_id, field, old_value, new_value, user_id, user, source, ts)
+        VALUES
+          (@id, @chat_id, @thread_id, @field, @old_value, @new_value, @user_id, @user, @source, @ts)
+      `);
+      for (const r of crows) { if (cins.run(r).changes) stats.config_changes++; }
+    }
+
+    copyTable(src, dst,
+      `SELECT * FROM pair_codes WHERE bot_name = ?`, [bot],
+      `INSERT OR IGNORE INTO pair_codes
+        (code, bot_name, chat_id, scope, issued_by_user_id, issued_ts,
+         expires_ts, used_by_user_id, used_ts, note)
+       VALUES
+        (@code, @bot_name, @chat_id, @scope, @issued_by_user_id, @issued_ts,
+         @expires_ts, @used_by_user_id, @used_ts, @note)`,
+      stats, 'pair_codes');
+
+    copyTable(src, dst,
+      `SELECT * FROM pairings WHERE bot_name = ?`, [bot],
+      `INSERT OR IGNORE INTO pairings
+        (id, bot_name, user_id, chat_id, granted_ts, granted_by_user_id, revoked_ts, note)
+       VALUES
+        (@id, @bot_name, @user_id, @chat_id, @granted_ts, @granted_by_user_id, @revoked_ts, @note)`,
+      stats, 'pairings');
+
+    copyTable(src, dst,
+      `SELECT * FROM pending_approvals WHERE bot_name = ?`, [bot],
+      `INSERT OR IGNORE INTO pending_approvals
+        (id, bot_name, turn_id, requester_chat_id, approver_chat_id, approver_msg_id,
+         tool_name, tool_input_json, tool_input_digest, callback_token,
+         status, requested_ts, decided_ts, decided_by_user_id, decided_by_user,
+         timeout_ts, reason)
+       VALUES
+        (@id, @bot_name, @turn_id, @requester_chat_id, @approver_chat_id, @approver_msg_id,
+         @tool_name, @tool_input_json, @tool_input_digest, @callback_token,
+         @status, @requested_ts, @decided_ts, @decided_by_user_id, @decided_by_user,
+         @timeout_ts, @reason)`,
+      stats, 'approvals');
+
+    copyTable(src, dst,
+      `SELECT * FROM events`, [],
+      `INSERT OR IGNORE INTO events
+        (id, ts, chat_id, kind, detail_json)
+       VALUES (@id, @ts, @chat_id, @kind, @detail_json)`,
+      stats, 'events');
+
+    copyTable(src, dst,
+      `SELECT * FROM chat_migrations`, [],
+      `INSERT OR IGNORE INTO chat_migrations
+        (old_chat_id, new_chat_id, migrated_ts)
+       VALUES (@old_chat_id, @new_chat_id, @migrated_ts)`,
+      stats, 'chat_migrations');
+  });
+  tx();
+
+  return stats;
+}
+
+function copyTable(src, dst, selectSql, selectParams, insertSql, stats, statKey) {
+  const rows = src.raw.prepare(selectSql).all(...selectParams);
+  const ins = dst.raw.prepare(insertSql);
+  for (const r of rows) {
+    if (ins.run(r).changes) stats[statKey]++;
+  }
+}
+
+function chatIdsForBot(chatToBot, bot) {
+  return Object.entries(chatToBot).filter(([, b]) => b === bot).map(([id]) => id);
+}
+
+function ph(n) { return new Array(n).fill('?').join(','); }
+
+if (require.main === module) main();
+
+module.exports = { copy, count, chatIdsForBot };

package/skills/telegram-history/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: telegram-history
+description: Query the Telegram transcript database. Use when asked about past chat activity, summaries of topics, who said what, historical references to old messages, or searches across conversation history. Not needed for replies to directly-quoted messages (bridge already embeds them).
+---
+
+# Usage
+
+Invoke via: `node skills/telegram-history/scripts/query.js <subcmd> [args]`
+
+Subcommands return JSON unless `--format pretty`. All chat IDs and thread IDs are strings.
+
+Bot scope: the skill filters results to the current bot's chat allowlist. Scope is derived from `process.cwd()` — each bot's Claude project dir maps to a chat.cwd in `config.json`. When invoked from an unmapped cwd the skill refuses to run unless `BRIDGE_ADMIN=1` is set (admin-only override).
+
+DB resolution (post Phase 8): the skill reads the bot's own `<bot>.db` file when scope is known. With `BRIDGE_ADMIN=1` it opens every `<bot>.db` that exists and unions results (sorted by ts desc, re-capped at `--limit`). If no per-bot DB is found the skill falls back to a legacy `bridge.db` (pre-cutover). Override the resolution with `BRIDGE_DB=/abs/path.db` for one-off queries against an archived file.
+
+## recent <chat_id> [thread_id]
+Last N messages. Default limit 20, hard cap 500.
+Flags: `--limit N`, `--since 6h|1d|7d`, `--include-outbound` (default true), `--format pretty`
+
+## around --chat X --msg-id N
+Context window around a specific message.
+Flags: `--before 5`, `--after 5`, `--format pretty`
+
+## search <term> [chat_id] [thread_id]
+FTS5 search on text + user. Operators (AND/OR/*) are treated as literal tokens.
+Flags: `--user U` (substring), `--days 30`, `--limit 20`, `--format pretty`
+
+## by-user <user_display_name> [chat_id] [thread_id]
+All messages by a user. Substring match on display name.
+Flags: `--days 7`, `--limit 50`, `--format pretty`
+
+## msg <msg_id> [chat_id]
+Fetch single message. Useful when a reply_to_id surfaces in context.
+
+## stats [chat_id] [thread_id]
+Per-user + per-direction counts within the window.
+Flags: `--days 7`
+
+# Examples
+
+"Summarize Orders topic today" →
+  `node skills/telegram-history/scripts/query.js recent -1000000000001 5379 --since 24h --format pretty`
+
+"When did Maria first mention the collaboration?" →
+  `node skills/telegram-history/scripts/query.js search "collaboration" --chat -1000000000001 --user Maria --format pretty`
+
+"What was said around message 12345?" →
+  `node skills/telegram-history/scripts/query.js around --chat -1000000000001 --msg-id 12345 --before 10 --after 10 --format pretty`
+
+"Who's been posting the most in UMI Group this week?" →
+  `node skills/telegram-history/scripts/query.js stats -1000000000001 --days 7`
+
+# Notes
+
+- DB opened read-only — safe to run alongside the live bridge.
+- Output capped at 500 rows. Narrow with `--since` or `--days` for wide queries.
+- Times in `ts` are ms epoch. `formatPretty` shows local HH:MM.

package/skills/telegram-history/scripts/query.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * telegram-history skill CLI.
+ *
+ *   node query.js <subcmd> [positional args] [--flag value]
+ *
+ * Subcommands: recent | around | search | by-user | msg | stats
+ *
+ * Opens bridge.db read-only. Bot scope is derived from process.cwd() —
+ * each bot's Claude project dir maps to a chat.cwd in config.json, so a
+ * partner-spawned skill invocation cannot escape its bot's chat allowlist.
+ * Set BRIDGE_ADMIN=1 for unrestricted queries from unmapped cwd.
+ *
+ * Default output: JSON (one row per message). Pass --format pretty for
+ * human-readable lines.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Database = require('better-sqlite3');
+
+const history = require('../lib/history');
+
+const BRIDGE_DIR = process.env.BRIDGE_DIR || path.resolve(__dirname, '../../../../polygram');
+const CONFIG_PATH = process.env.BRIDGE_CONFIG || path.join(BRIDGE_DIR, 'config.json');
+// BRIDGE_DB overrides auto-resolution. Otherwise the skill reads one DB per
+// bot (<bot>.db) when the bot scope is known, or all bot DBs for admin.
+// Legacy `bridge.db` is used as a fallback when per-bot DBs don't exist yet.
+const DB_OVERRIDE = process.env.BRIDGE_DB || null;
+
+function die(msg, code = 1) {
+  process.stderr.write(`history: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  } catch (err) {
+    die(`cannot read config at ${CONFIG_PATH}: ${err.message}`);
+  }
+}
+
+/**
+ * Derive bot scope from the current working directory.
+ * Each chat in config.json has a `cwd` pointing at the bot's Claude project
+ * root. process.cwd() is set by the bridge when it spawns Claude, so this
+ * cannot be spoofed from inside a prompt. Fails closed: if no chat's cwd
+ * matches and no admin override is set, we refuse to run.
+ */
+function deriveBotScope(cfg) {
+  const cwd = path.resolve(process.cwd());
+  const matching = Object.entries(cfg.chats || {})
+    .filter(([, c]) => c.cwd && path.resolve(c.cwd) === cwd);
+
+  if (matching.length) {
+    const bots = new Set(matching.map(([, c]) => c.bot).filter(Boolean));
+    if (bots.size !== 1) {
+      die(`cwd ${cwd} maps to multiple bots (${[...bots].join(', ')}) — refusing`);
+    }
+    return {
+      bot: [...bots][0],
+      allowedChatIds: matching.map(([id]) => id),
+    };
+  }
+
+  // No cwd match. Allow explicit admin override via env var, which the bridge
+  // never sets and thus cannot be triggered from a bot-spawned subprocess.
+  if (process.env.BRIDGE_ADMIN === '1') {
+    return { bot: null, allowedChatIds: null };
+  }
+
+  // Legacy fallback: respect CLAUDE_CHANNEL_BOT ONLY if it matches a known bot
+  // in the config. This preserves manual shumabit/umi-assistant invocation via
+  // the bridge env var without opening an admin-by-default hole.
+  const envBot = process.env.CLAUDE_CHANNEL_BOT;
+  if (envBot && cfg.bots?.[envBot]) {
+    const allowed = Object.entries(cfg.chats || {})
+      .filter(([, c]) => c.bot === envBot)
+      .map(([id]) => id);
+    if (allowed.length) return { bot: envBot, allowedChatIds: allowed };
+  }
+
+  die(`cannot determine bot scope for cwd ${cwd}; set BRIDGE_ADMIN=1 for unrestricted access`);
+}
+
+function openDbReadOnly(dbPath) {
+  if (!fs.existsSync(dbPath)) die(`bridge DB not found at ${dbPath}`);
+  const raw = new Database(dbPath, { readonly: true, fileMustExist: true });
+  return { raw };
+}
+
+/**
+ * Post-Phase-8: pick the right DB file(s) to query.
+ *  - If BRIDGE_DB is set, use it (explicit override).
+ *  - If bot scope is known and <bot>.db exists, use that single file.
+ *  - If bot scope is known but per-bot DB is missing, fall back to legacy
+ *    bridge.db (pre-cutover state).
+ *  - If admin (bot null): open every <bot>.db that exists; if none, fall
+ *    back to bridge.db.
+ */
+function resolveDbPaths(cfg, bot) {
+  if (DB_OVERRIDE) return [DB_OVERRIDE];
+  const perBot = (b) => path.join(BRIDGE_DIR, `${b}.db`);
+  const legacy = path.join(BRIDGE_DIR, 'bridge.db');
+
+  if (bot) {
+    const p = perBot(bot);
+    if (fs.existsSync(p)) return [p];
+    if (fs.existsSync(legacy)) return [legacy];
+    die(`no DB found for bot "${bot}" (tried ${p} and ${legacy})`);
+  }
+
+  // Admin: union across all bots that have a DB.
+  const paths = Object.keys(cfg.bots || {})
+    .map(perBot)
+    .filter((p) => fs.existsSync(p));
+  if (paths.length) return paths;
+  if (fs.existsSync(legacy)) return [legacy];
+  die(`no per-bot DBs found in ${BRIDGE_DIR} and no legacy bridge.db either`);
+}
+
+/**
+ * Call a history helper once per DB and merge results.
+ *  - For array-returning helpers (recent/around/search/by-user/stats),
+ *    concat, re-sort by ts desc, and re-apply the requested limit.
+ *  - For single-row helpers (msg), return the first non-null hit.
+ */
+function queryAcross(dbs, fn, { limit } = {}) {
+  const out = [];
+  for (const db of dbs) {
+    const rows = fn(db);
+    if (Array.isArray(rows)) out.push(...rows);
+    else if (rows) return rows;
+  }
+  if (!out.length) return out;
+  if (out[0] && typeof out[0].ts === 'number') {
+    out.sort((a, b) => b.ts - a.ts);
+  }
+  if (limit && out.length > limit) out.length = limit;
+  return out;
+}
+
+function emit(rows, format) {
+  if (format === 'pretty') {
+    if (!Array.isArray(rows)) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return; }
+    process.stdout.write(history.formatPretty(rows) + '\n');
+    return;
+  }
+  process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+}
+
+function runSub(sub, positional, flags, dbs, allowedChatIds) {
+  const format = flags.format || 'json';
+  const limit = flags.limit ? Number(flags.limit) : undefined;
+
+  switch (sub) {
+    case 'recent': {
+      const chatId = positional[0];
+      const threadId = positional[1] || null;
+      if (!chatId) die('recent: <chat_id> required');
+      const rows = queryAcross(dbs, (db) => history.recent(db, {
+        chatId,
+        threadId,
+        limit: flags.limit,
+        since: flags.since || null,
+        includeOutbound: flags['include-outbound'] !== false && flags['include-outbound'] !== 'false',
+        allowedChatIds,
+      }), { limit });
+      return emit(rows, format);
+    }
+
+    case 'around': {
+      const chatId = flags.chat;
+      const msgId = Number(flags['msg-id']);
+      if (!chatId) die('around: --chat required');
+      if (!msgId) die('around: --msg-id required');
+      const rows = queryAcross(dbs, (db) => history.around(db, {
+        chatId,
+        msgId,
+        before: Number(flags.before) || 5,
+        after: Number(flags.after) || 5,
+        allowedChatIds,
+      }));
+      return emit(rows, format);
+    }
+
+    case 'search': {
+      const query = positional[0];
+      const chatId = positional[1] || flags.chat || null;
+      const threadId = positional[2] || flags.thread || null;
+      if (!query) die('search: <term> required');
+      const rows = queryAcross(dbs, (db) => history.search(db, {
+        query,
+        chatId,
+        threadId,
+        user: flags.user || null,
+        days: flags.days ? Number(flags.days) : null,
+        limit: flags.limit,
+        allowedChatIds,
+      }), { limit });
+      return emit(rows, format);
+    }
+
+    case 'by-user': {
+      const user = positional[0];
+      const chatId = positional[1] || flags.chat || null;
+      const threadId = positional[2] || flags.thread || null;
+      if (!user) die('by-user: <user> required');
+      const rows = queryAcross(dbs, (db) => history.byUser(db, {
+        user,
+        chatId,
+        threadId,
+        days: flags.days !== undefined ? Number(flags.days) : 7,
+        limit: flags.limit,
+        allowedChatIds,
+      }), { limit });
+      return emit(rows, format);
+    }
+
+    case 'msg': {
+      const msgId = Number(positional[0]);
+      const chatId = positional[1] || flags.chat || null;
+      if (!msgId) die('msg: <msg_id> required');
+      const row = queryAcross(dbs, (db) => history.getMsg(db, { msgId, chatId, allowedChatIds }));
+      return emit(row ? [row] : [], format);
+    }
+
+    case 'stats': {
+      const chatId = positional[0] || flags.chat || null;
+      const threadId = positional[1] || flags.thread || null;
+      // stats returns aggregates — merging naively concatenates the per-DB
+      // breakdown. That's what we want when admin queries across bots.
+      const rows = queryAcross(dbs, (db) => history.stats(db, {
+        chatId,
+        threadId,
+        days: flags.days !== undefined ? Number(flags.days) : 7,
+        allowedChatIds,
+      }));
+      return emit(rows, format);
+    }
+
+    default:
+      die(`unknown subcommand: ${sub}. Try: recent|around|search|by-user|msg|stats`);
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(`usage: query.js <recent|around|search|by-user|msg|stats> [args]\n`);
+    process.exit(0);
+  }
+  const sub = argv[0];
+  const { positional, flags } = parseArgs(argv.slice(1));
+
+  const cfg = loadConfig();
+  const { bot, allowedChatIds } = deriveBotScope(cfg);
+  const dbPaths = resolveDbPaths(cfg, bot);
+  const dbs = dbPaths.map(openDbReadOnly);
+  try {
+    runSub(sub, positional, flags, dbs, allowedChatIds);
+  } finally {
+    for (const db of dbs) { try { db.raw.close(); } catch {} }
+  }
+}
+
+main();