chatlab-cli 0.29.0 → 0.30.1-beta.1

package/dist/chunk-M2PXDX4G.mjs

@@ -0,0 +1,2325 @@
+import { createRequire as __createRequire } from 'module';
+import { dirname as __pathDirname } from 'path';
+import { fileURLToPath as __fileURLToPath } from 'url';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import {
+  assertCliDataDirCompatible
+} from "./chunk-326OCJOT.mjs";
+import {
+  getVersion
+} from "./chunk-5ADKYYNA.mjs";
+import {
+  resolveCliPath
+} from "./chunk-FJ35V3TE.mjs";
+import {
+  NodePathProvider,
+  PreferencesManager,
+  applyPendingNodeDataDirMigrationIfNeeded,
+  getSystemLogsDir,
+  hasPendingElectronDataWarning
+} from "./chunk-ULNRUS55.mjs";
+import {
+  AIChatManager,
+  applyPreprocessingPipeline,
+  computeWordFrequency,
+  desensitizeText,
+  logNativeParserStatus,
+  matchesBlacklist,
+  mergeRulesForLocale,
+  preprocessMessages
+} from "./chunk-36JGKW6K.mjs";
+import {
+  ConfigSetError,
+  DEFAULT_API_PORT,
+  DatabaseManager,
+  appLogger,
+  computeResponseTimeStats,
+  executeParameterizedSql,
+  executeReadonlySql,
+  getChatOverview,
+  getConfigPath,
+  getConversationBetween,
+  getDailyActivity,
+  getDatabaseSchema,
+  getHourlyActivity,
+  getMemberActivity,
+  getMemberNameHistory,
+  getMembers,
+  getMembersWithAliases,
+  getMessageContext,
+  getMonthlyActivity,
+  getSearchMessageContext,
+  getSegmentMessages,
+  getSegmentSummaries,
+  getSessionMeta,
+  getSessionOverview,
+  getWeekdayActivity,
+  initAppLogger,
+  initNlpDir,
+  loadConfig,
+  messageTypeToString,
+  resolveOwnerMember,
+  searchMessagesByKeywords,
+  searchMessagesLike,
+  setConfigField,
+  verifyCliDataPath
+} from "./chunk-LVEJHB3X.mjs";
+
+// src/cli.ts
+import * as fs2 from "fs";
+import { execSync } from "child_process";
+import { Command } from "commander";
+
+// src/http/port.ts
+import * as net from "net";
+function isPortAvailable(port, host) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        resolve(false);
+      } else {
+        reject(err);
+      }
+    });
+    server.once("listening", () => server.close(() => resolve(true)));
+    server.listen(port, host);
+  });
+}
+function formatPortInUseError(port) {
+  return [
+    ``,
+    `  \u2716 Error: port ${port} is already in use.`,
+    ``,
+    `    Another process (possibly a ChatLab instance) is using this port. You can:`,
+    `    \u2022 Use another port:   chatlab start --port <port>`,
+    `    \u2022 Find the process:   lsof -iTCP:${port} -sTCP:LISTEN`,
+    ``
+  ].join("\n");
+}
+
+// src/runtime.ts
+import * as fs from "fs";
+function resolveNativeBinding() {
+  if (process.versions.electron) return void 0;
+  const nativePath = resolveCliPath("native/better_sqlite3.node");
+  if (fs.existsSync(nativePath)) return nativePath;
+  return void 0;
+}
+function initRuntime() {
+  let config = loadConfig();
+  const pendingMigration = applyPendingNodeDataDirMigrationIfNeeded();
+  if (!pendingMigration.skipped) {
+    if (pendingMigration.success) {
+      console.error("[Migration] Pending data directory migration completed");
+      config = loadConfig();
+    } else {
+      console.error("[Migration] Pending data directory migration failed:", pendingMigration.error);
+    }
+  }
+  const userDataDir = config.data.user_data_dir || void 0;
+  const pathProvider = new NodePathProvider(userDataDir);
+  pathProvider.ensureAllDirs();
+  const runtime = assertCliDataDirCompatible(pathProvider, "cli");
+  if (hasPendingElectronDataWarning() || !verifyCliDataPath(pathProvider.getDatabaseDir())) {
+    printElectronDataError();
+    process.exit(1);
+  }
+  const nativeBinding = resolveNativeBinding();
+  const dbManager = new DatabaseManager(pathProvider, { nativeBinding, runtime });
+  return { config, pathProvider, dbManager };
+}
+function printElectronDataError() {
+  console.error("\n" + "=".repeat(68));
+  console.error("  ChatLab: Electron desktop data not found");
+  console.error("=".repeat(68));
+  console.error("");
+  console.error("  Detected that ChatLab desktop app was installed on this machine,");
+  console.error("  but could not locate your chat databases.");
+  console.error("");
+  console.error("  This usually means you changed the data directory in desktop settings.");
+  console.error("");
+  console.error("  To fix this, choose one of:");
+  console.error("");
+  console.error("  1. Open ChatLab desktop app \u2014 it will auto-migrate your data");
+  console.error("  2. Set the data directory manually:");
+  console.error('     export CHATLAB_DATA_DIR="/path/to/your/data"');
+  console.error("  3. Edit ~/.chatlab/config.toml:");
+  console.error("     [data]");
+  console.error('     user_data_dir = "/path/to/your/data"');
+  console.error("");
+  console.error("=".repeat(68) + "\n");
+}
+
+// src/query/envelope.ts
+var API_VERSION = 1;
+var QueryError = class extends Error {
+  code;
+  hint;
+  candidates;
+  constructor(shape) {
+    super(shape.message);
+    this.name = "QueryError";
+    this.code = shape.code;
+    this.hint = shape.hint;
+    this.candidates = shape.candidates;
+  }
+};
+function successEnvelope(command, data, meta) {
+  return {
+    ok: true,
+    command,
+    data,
+    meta: { ...meta ?? {}, apiVersion: API_VERSION }
+  };
+}
+function errorEnvelope(command, error, meta) {
+  const shape = {
+    code: error.code,
+    message: error.message,
+    ...error.hint !== void 0 ? { hint: error.hint } : {},
+    ...error.candidates !== void 0 ? { candidates: error.candidates } : {}
+  };
+  return {
+    ok: false,
+    command,
+    error: shape,
+    ...meta !== void 0 ? { meta } : {}
+  };
+}
+function exitCodeForError(code) {
+  if (code === "SQL_ERROR") return 5;
+  if (code.endsWith("_AMBIGUOUS")) return 4;
+  if (code.endsWith("_NOT_FOUND")) return 3;
+  if (code === "INVALID_ARGUMENT" || code === "CURSOR_INVALID" || code.endsWith("_DISABLED")) return 2;
+  return 1;
+}
+
+// src/query/runner.ts
+function resolveFormat(explicit) {
+  if (explicit !== void 0) {
+    if (explicit === "agent" || explicit === "json" || explicit === "text") return explicit;
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: `Unknown format: ${explicit}`,
+      hint: "Supported formats: agent, json, text"
+    });
+  }
+  return process.stdout.isTTY ? "text" : "agent";
+}
+async function runQuery(command, options, handler) {
+  let format;
+  try {
+    format = resolveFormat(options.format);
+  } catch (err) {
+    emitError(command, "agent", err);
+    return;
+  }
+  try {
+    const result = await handler(format);
+    if (format === "text") {
+      console.log(result.renderText ? result.renderText() : JSON.stringify(result.data, null, 2));
+    } else {
+      console.log(JSON.stringify(successEnvelope(command, result.data, result.meta)));
+    }
+  } catch (err) {
+    emitError(command, format, err);
+  }
+}
+function emitError(command, format, err) {
+  const queryError = err instanceof QueryError ? err : new QueryError({
+    code: "INTERNAL_ERROR",
+    message: err instanceof Error ? err.message : String(err)
+  });
+  if (format === "text") {
+    console.error(`Error: ${queryError.message}${queryError.hint ? `
+  ${queryError.hint}` : ""}`);
+    if (queryError.candidates) {
+      for (const candidate of queryError.candidates) {
+        console.error(`  - ${JSON.stringify(candidate)}`);
+      }
+    }
+  } else {
+    console.log(JSON.stringify(errorEnvelope(command, queryError)));
+  }
+  process.exitCode = exitCodeForError(queryError.code);
+}
+
+// src/query/context.ts
+import * as path from "path";
+
+// src/query/preprocess-config.ts
+var BUILTIN_RULE_LOCALES = ["zh-CN", "en-US", "ja-JP", "ko-KR"];
+var PRIMARY_LANG_MAP = {
+  zh: "zh-CN",
+  en: "en-US",
+  ja: "ja-JP",
+  ko: "ko-KR"
+};
+function normalizeLocale(locale) {
+  if (BUILTIN_RULE_LOCALES.includes(locale)) return locale;
+  const primary = locale.split(/[-_]/)[0].toLowerCase();
+  return PRIMARY_LANG_MAP[primary] ?? locale;
+}
+function detectSystemLocale() {
+  try {
+    const resolved = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (resolved) return resolved;
+  } catch {
+  }
+  const lang = process.env.LANG || "";
+  return lang.split(".")[0] || "";
+}
+function resolveCliLocale(configLang, systemLocale) {
+  if (configLang) return normalizeLocale(configLang);
+  const system = systemLocale !== void 0 ? systemLocale : detectSystemLocale();
+  if (system) return normalizeLocale(system);
+  return "zh-CN";
+}
+function loadCliPreprocessConfig(systemDir, locale) {
+  const preferences = new PreferencesManager(systemDir).load();
+  const config = preferences.aiPreprocessConfig;
+  return {
+    ...config,
+    desensitizeRules: mergeRulesForLocale(
+      config.desensitizeRules,
+      locale,
+      config.desensitizeBuiltinRuleOverrides ?? {}
+    )
+  };
+}
+
+// src/query/resolve.ts
+function listSessionCandidates(source) {
+  const result = [];
+  for (const id of source.listSessionIds()) {
+    const db = source.open(id);
+    if (!db) continue;
+    const meta = getSessionMeta(db);
+    if (!meta) continue;
+    result.push({ id, name: meta.name, platform: meta.platform, db });
+  }
+  return result;
+}
+function resolveSession(source, ref) {
+  if (ref) {
+    const direct = source.open(ref);
+    if (direct && getSessionMeta(direct)) {
+      const meta = getSessionMeta(direct);
+      return { id: ref, name: meta.name, db: direct };
+    }
+  }
+  const sessions = listSessionCandidates(source);
+  if (!ref) {
+    if (sessions.length === 1) {
+      return { id: sessions[0].id, name: sessions[0].name, db: sessions[0].db };
+    }
+    if (sessions.length === 0) {
+      throw new QueryError({
+        code: "SESSION_NOT_FOUND",
+        message: "No chat sessions found",
+        hint: "Import a chat export first (chatlab import <file>)"
+      });
+    }
+    throw new QueryError({
+      code: "SESSION_AMBIGUOUS",
+      message: `${sessions.length} sessions available, --session is required`,
+      hint: "Retry with --session <id>",
+      candidates: sessions.map(({ id, name, platform }) => ({ id, name, platform }))
+    });
+  }
+  const nameMatches = sessions.filter((s) => s.name === ref);
+  if (nameMatches.length === 1) {
+    return { id: nameMatches[0].id, name: nameMatches[0].name, db: nameMatches[0].db };
+  }
+  if (nameMatches.length > 1) {
+    throw new QueryError({
+      code: "SESSION_AMBIGUOUS",
+      message: `Session name '${ref}' matches ${nameMatches.length} sessions`,
+      hint: "Retry with --session <id>",
+      candidates: nameMatches.map(({ id, name, platform }) => ({ id, name, platform }))
+    });
+  }
+  const partial = sessions.filter((s) => s.name.includes(ref));
+  if (partial.length > 0) {
+    throw new QueryError({
+      code: "SESSION_AMBIGUOUS",
+      message: `Session '${ref}' not found, ${partial.length} similar session(s) exist`,
+      hint: "Retry with --session <id>",
+      candidates: partial.map(({ id, name, platform }) => ({ id, name, platform }))
+    });
+  }
+  throw new QueryError({
+    code: "SESSION_NOT_FOUND",
+    message: `Session '${ref}' not found`,
+    hint: "Run `chatlab sessions list` to see available sessions"
+  });
+}
+function resolveMember(db, ref) {
+  if (ref === "me") {
+    const owner = resolveOwnerMember(db);
+    if (!owner) {
+      throw new QueryError({
+        code: "MEMBER_NOT_FOUND",
+        message: "Owner profile is not configured for this session",
+        hint: "Set the owner in the ChatLab app, or use an explicit --member <id>"
+      });
+    }
+    return { id: owner.id, name: owner.name };
+  }
+  const members = getMembersWithAliases(db);
+  const displayName = (m) => m.groupNickname || m.accountName || m.platformId;
+  if (/^\d+$/.test(ref)) {
+    const byId = members.find((m) => m.id === Number(ref));
+    if (byId) return { id: byId.id, name: displayName(byId) };
+    throw new QueryError({
+      code: "MEMBER_NOT_FOUND",
+      message: `Member id ${ref} not found`,
+      hint: "Run `chatlab members list` to see available members"
+    });
+  }
+  const exact = members.filter(
+    (m) => m.groupNickname === ref || m.accountName === ref || m.aliases.includes(ref) || m.platformId === ref
+  );
+  if (exact.length === 1) {
+    return { id: exact[0].id, name: displayName(exact[0]) };
+  }
+  const pool = exact.length > 1 ? exact : members.filter((m) => displayName(m).includes(ref));
+  if (pool.length > 0) {
+    throw new QueryError({
+      code: "MEMBER_AMBIGUOUS",
+      message: `Member name '${ref}' matches ${pool.length} member(s)`,
+      hint: "Retry with --member <id>",
+      candidates: pool.slice(0, 10).map((m) => ({ id: m.id, name: displayName(m), messages: m.messageCount }))
+    });
+  }
+  throw new QueryError({
+    code: "MEMBER_NOT_FOUND",
+    message: `Member '${ref}' not found`,
+    hint: "Run `chatlab members list` to see available members"
+  });
+}
+
+// src/query/context.ts
+function createQueryContext(options) {
+  const { config, pathProvider, dbManager } = initRuntime();
+  const resolved = resolveSession(dbManager, options.session);
+  const locale = resolveCliLocale(config.locale.lang);
+  const preprocessConfig = loadCliPreprocessConfig(pathProvider.getSystemDir(), locale);
+  const ownerPlatformId = getSessionMeta(resolved.db)?.ownerId ?? void 0;
+  initNlpDir(path.join(pathProvider.getSystemDir(), "nlp"));
+  return {
+    db: resolved.db,
+    session: { id: resolved.id, name: resolved.name },
+    locale,
+    preprocessConfig,
+    ownerPlatformId,
+    allowRaw: config.cli.allow_raw,
+    allowSql: config.cli.allow_sql,
+    close: () => dbManager.closeAll()
+  };
+}
+function assertRawAllowed(ctx, options) {
+  if (options.raw && !ctx.allowRaw) {
+    throw new QueryError({
+      code: "RAW_DISABLED",
+      message: "--raw output is disabled by default",
+      hint: "The user must opt in: set CHATLAB_CLI_ALLOW_RAW=1 or `chatlab config set cli.allow_raw true`"
+    });
+  }
+}
+
+// src/query/parse.ts
+import { createHash } from "crypto";
+function toIsoWithOffset(date) {
+  const pad = (n, w = 2) => String(Math.abs(n)).padStart(w, "0");
+  const offsetMin = -date.getTimezoneOffset();
+  const sign = offsetMin >= 0 ? "+" : "-";
+  const offH = pad(Math.floor(Math.abs(offsetMin) / 60));
+  const offM = pad(Math.abs(offsetMin) % 60);
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${sign}${offH}:${offM}`;
+}
+function epochToIso(ts) {
+  return toIsoWithOffset(new Date(ts * 1e3));
+}
+var DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+var DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/;
+var ISO_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})T/;
+var LAST_DURATION = /^(\d+)([hdw])$/;
+function startOfDay(base, dayOffset = 0) {
+  return new Date(base.getFullYear(), base.getMonth(), base.getDate() + dayOffset);
+}
+function invalidTime(flag, value) {
+  return new QueryError({
+    code: "INVALID_ARGUMENT",
+    message: `Invalid ${flag} value: ${value}`,
+    hint: 'Use YYYY-MM-DD, "YYYY-MM-DD HH:mm", ISO 8601, or the keywords today/yesterday'
+  });
+}
+function isSameLocalDate(date, y, m, d) {
+  return date.getFullYear() === y && date.getMonth() === m - 1 && date.getDate() === d;
+}
+function isSameLocalDateTime(date, y, m, d, h, min, s) {
+  return isSameLocalDate(date, y, m, d) && date.getHours() === h && date.getMinutes() === min && date.getSeconds() === s;
+}
+function parseTimeValue(value, boundary, flag, now) {
+  if (value === "today" || value === "yesterday") {
+    const dayOffset = value === "yesterday" ? -1 : 0;
+    if (boundary === "start") return startOfDay(now, dayOffset);
+    return new Date(startOfDay(now, dayOffset + 1).getTime() - 1e3);
+  }
+  const dateOnly = DATE_ONLY.exec(value);
+  if (dateOnly) {
+    const [, y, m, d] = dateOnly;
+    const year = Number(y);
+    const month = Number(m);
+    const day = Number(d);
+    const base = new Date(year, month - 1, day);
+    if (Number.isNaN(base.getTime()) || !isSameLocalDate(base, year, month, day)) throw invalidTime(flag, value);
+    if (boundary === "start") return base;
+    return new Date(new Date(year, month - 1, day + 1).getTime() - 1e3);
+  }
+  const dateTime = DATE_TIME.exec(value);
+  if (dateTime) {
+    const [, y, m, d, h, min, s] = dateTime;
+    const year = Number(y);
+    const month = Number(m);
+    const day = Number(d);
+    const hour = Number(h);
+    const minute = Number(min);
+    const second = Number(s ?? 0);
+    const parsed2 = new Date(year, month - 1, day, hour, minute, second);
+    if (Number.isNaN(parsed2.getTime()) || !isSameLocalDateTime(parsed2, year, month, day, hour, minute, second)) {
+      throw invalidTime(flag, value);
+    }
+    return parsed2;
+  }
+  const parsed = new Date(value);
+  if (!Number.isNaN(parsed.getTime()) && /\d{4}-\d{2}-\d{2}T/.test(value)) {
+    const isoDate = ISO_DATE_PREFIX.exec(value);
+    if (isoDate) {
+      const [, y, m, d] = isoDate;
+      const year = Number(y);
+      const month = Number(m);
+      const day = Number(d);
+      const localDate = new Date(year, month - 1, day);
+      if (!isSameLocalDate(localDate, year, month, day)) throw invalidTime(flag, value);
+    }
+    return parsed;
+  }
+  throw invalidTime(flag, value);
+}
+function parseTimeOptions(options, now = /* @__PURE__ */ new Date()) {
+  const { since, until, last } = options;
+  if (last !== void 0 && (since !== void 0 || until !== void 0)) {
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: "--last cannot be combined with --since/--until",
+      hint: "Use either --last <N>h|d|w or explicit --since/--until bounds"
+    });
+  }
+  if (last !== void 0) {
+    const match = LAST_DURATION.exec(last);
+    if (!match) {
+      throw new QueryError({
+        code: "INVALID_ARGUMENT",
+        message: `Invalid --last value: ${last}`,
+        hint: "Supported units: h (hours), d (days), w (weeks), e.g. --last 30d"
+      });
+    }
+    const n = Number(match[1]);
+    const unitSeconds = match[2] === "h" ? 3600 : match[2] === "d" ? 86400 : 604800;
+    const start = new Date(now.getTime() - n * unitSeconds * 1e3);
+    return {
+      startTs: Math.floor(start.getTime() / 1e3),
+      meta: { since: toIsoWithOffset(start), until: toIsoWithOffset(now) }
+    };
+  }
+  let startTs;
+  let endTs;
+  let sinceIso = null;
+  if (since !== void 0) {
+    const parsed = parseTimeValue(since, "start", "--since", now);
+    startTs = Math.floor(parsed.getTime() / 1e3);
+    sinceIso = toIsoWithOffset(parsed);
+  }
+  if (until !== void 0) {
+    const parsed = parseTimeValue(until, "end", "--until", now);
+    endTs = Math.floor(parsed.getTime() / 1e3);
+  }
+  if (startTs !== void 0 && endTs !== void 0 && startTs > endTs) {
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: "--since is after --until",
+      hint: "Check the time range boundaries"
+    });
+  }
+  return {
+    startTs,
+    endTs,
+    meta: {
+      since: sinceIso,
+      until: endTs !== void 0 ? epochToIso(endTs) : toIsoWithOffset(now)
+    }
+  };
+}
+function parseLimit(value, defaultValue, cap, flag, min = 0) {
+  if (value === void 0) return Math.min(defaultValue, cap);
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(n) || n < min) {
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: `Invalid ${flag} value: ${value}`,
+      hint: min > 0 ? `${flag} must be an integer from ${min} to ${cap}` : `${flag} must be a non-negative integer (max ${cap})`
+    });
+  }
+  return Math.min(n, cap);
+}
+function queryFingerprint(conditions) {
+  const canonical = JSON.stringify(conditions, Object.keys(conditions).sort());
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+}
+function freezeTimeRangeForCursor(time) {
+  if (time.endTs !== void 0 || time.meta.until === null) return time;
+  const endMs = new Date(time.meta.until).getTime();
+  if (Number.isNaN(endMs)) return time;
+  return { ...time, endTs: Math.floor(endMs / 1e3) };
+}
+function resolveTimeOptionsForCursor(options, now = /* @__PURE__ */ new Date()) {
+  const snapshot = options.cursor ? getCursorSnapshot(options.cursor) : void 0;
+  return snapshot?.time ?? freezeTimeRangeForCursor(parseTimeOptions(options, now));
+}
+function encodeCursor(offset, fingerprint, snapshot) {
+  if (snapshot?.time) {
+    return Buffer.from(JSON.stringify({ v: 2, fp: fingerprint, offset, time: snapshot.time }), "utf8").toString(
+      "base64url"
+    );
+  }
+  return Buffer.from(`${fingerprint}:${offset}`, "utf8").toString("base64url");
+}
+function asObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function decodeCursorEnvelope(token) {
+  let decoded = "";
+  try {
+    decoded = Buffer.from(token, "base64url").toString("utf8");
+  } catch {
+    return null;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+  const object = asObject(payload);
+  if (!object || object.v !== 2 || typeof object.fp !== "string" || typeof object.offset !== "number" || !Number.isInteger(object.offset) || object.offset < 0) {
+    return null;
+  }
+  const snapshot = decodeCursorSnapshot(object);
+  return { fingerprint: object.fp, offset: object.offset, ...snapshot ? { snapshot } : {} };
+}
+function decodeCursorSnapshot(payload) {
+  const timeObject = asObject(payload.time);
+  if (!timeObject) return void 0;
+  const metaObject = asObject(timeObject.meta);
+  if (!metaObject) return void 0;
+  const startTs = timeObject.startTs;
+  const endTs = timeObject.endTs;
+  const since = metaObject.since;
+  const until = metaObject.until;
+  if (startTs !== void 0 && typeof startTs !== "number") return void 0;
+  if (endTs !== void 0 && typeof endTs !== "number") return void 0;
+  if (since !== null && typeof since !== "string") return void 0;
+  if (until !== null && typeof until !== "string") return void 0;
+  return {
+    time: {
+      ...startTs !== void 0 ? { startTs } : {},
+      ...endTs !== void 0 ? { endTs } : {},
+      meta: { since, until }
+    }
+  };
+}
+function getCursorSnapshot(token) {
+  return decodeCursorEnvelope(token)?.snapshot;
+}
+function decodeCursor(token, fingerprint) {
+  const envelope = decodeCursorEnvelope(token);
+  if (envelope) {
+    if (envelope.fingerprint !== fingerprint) {
+      throw new QueryError({
+        code: "CURSOR_INVALID",
+        message: "Cursor does not match the current query conditions",
+        hint: "Cursors are only valid for the exact query that produced them; re-run the query without --cursor"
+      });
+    }
+    return envelope.offset;
+  }
+  let decoded = "";
+  try {
+    decoded = Buffer.from(token, "base64url").toString("utf8");
+  } catch {
+  }
+  const match = /^([0-9a-f]{12}):(\d+)$/.exec(decoded);
+  if (!match || match[1] !== fingerprint) {
+    throw new QueryError({
+      code: "CURSOR_INVALID",
+      message: "Cursor does not match the current query conditions",
+      hint: "Cursors are only valid for the exact query that produced them; re-run the query without --cursor"
+    });
+  }
+  return Number(match[2]);
+}
+
+// src/query/commands-sessions-members.ts
+function epochOrNull(ts) {
+  return ts == null ? null : epochToIso(ts);
+}
+function registerSessionCommands(program2) {
+  const sessionsCmd = program2.command("sessions").description("Chat sessions (list, show)").option("--format <format>", "Output format (table|json for legacy list; agent|json|text for subcommands)").action((options) => {
+    console.error("[Deprecated] `chatlab sessions` \u2014 use `chatlab sessions list`; alias kept for one major version");
+    legacySessionsList(options);
+  });
+  sessionsCmd.command("list").description("List imported chat sessions").option("--query <kw>", "Filter by session name substring").option("--platform <p>", "Filter by platform id").option("--format <format>", "Output format: agent|json|text").action(async (options) => {
+    await runQuery("sessions.list", options, async () => {
+      const { dbManager } = initRuntime();
+      try {
+        const items = dbManager.listSessionIds().map((id) => {
+          const db = dbManager.open(id);
+          if (!db) return null;
+          const meta = getSessionMeta(db);
+          if (!meta) return null;
+          const overview = getSessionOverview(db);
+          return {
+            id,
+            name: meta.name,
+            platform: meta.platform,
+            type: meta.type,
+            totalMessages: overview.totalMessages,
+            totalMembers: overview.totalMembers,
+            firstMessage: epochOrNull(overview.firstMessageTs),
+            lastMessage: epochOrNull(overview.lastMessageTs)
+          };
+        }).filter((s) => s !== null).filter((s) => options.query ? s.name.includes(options.query) : true).filter((s) => options.platform ? s.platform === options.platform : true);
+        return {
+          data: { items },
+          meta: { returned: items.length },
+          renderText: () => items.map(
+            (s) => `${s.id}  ${s.name}
+  ${s.platform} | ${s.type} | ${s.totalMembers} members | ${s.totalMessages} messages`
+          ).join("\n") || "No chat sessions found."
+        };
+      } finally {
+        dbManager.closeAll();
+      }
+    });
+  });
+  sessionsCmd.command("show").description("Show one session in detail").option("--session <ref>", "Session id or unique name").option("--format <format>", "Output format: agent|json|text").action(async (options) => {
+    await runQuery("sessions.show", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const meta = getSessionMeta(ctx.db);
+        const overview = getSessionOverview(ctx.db);
+        const data = {
+          id: ctx.session.id,
+          name: meta.name,
+          platform: meta.platform,
+          type: meta.type,
+          totalMessages: overview.totalMessages,
+          totalMembers: overview.totalMembers,
+          firstMessage: epochOrNull(overview.firstMessageTs),
+          lastMessage: epochOrNull(overview.lastMessageTs)
+        };
+        return {
+          data,
+          meta: { session: ctx.session },
+          renderText: () => `${data.name} (${data.id})
+Platform: ${data.platform} | Type: ${data.type}
+Messages: ${data.totalMessages} | Members: ${data.totalMembers}
+Range: ${data.firstMessage ?? "-"} ~ ${data.lastMessage ?? "-"}`
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+}
+function registerMemberCommands(program2) {
+  const membersCmd = program2.command("members").description("Session members (list, history)").argument("[session-id]", "legacy: session id (deprecated alias)").option("--format <format>", "Output format").action((sessionId, options, command) => {
+    if (!sessionId) {
+      command.help({ error: false });
+      return;
+    }
+    console.error(
+      "[Deprecated] `chatlab members <session-id>` \u2014 use `chatlab members list --session <id>`; alias kept for one major version"
+    );
+    legacyMembersList(sessionId, options);
+  });
+  membersCmd.command("list").description("List session members").option("--session <ref>", "Session id or unique name").option("--query <kw>", "Filter by member name substring").option("--sort <by>", "Sort by: messages|name", "messages").option("--limit <n>", "Max members to return (default 50)").option("--format <format>", "Output format: agent|json|text").action(async (options) => {
+    await runQuery("members.list", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const limit = parseLimit(options.limit, 50, 500, "--limit");
+        let members = getMembersWithAliases(ctx.db).map((m) => ({
+          id: m.id,
+          name: m.groupNickname || m.accountName || m.platformId,
+          ...m.aliases.length > 0 ? { aliases: m.aliases } : {},
+          messageCount: m.messageCount
+        }));
+        if (options.query) {
+          const kw = options.query;
+          members = members.filter((m) => m.name.includes(kw) || m.aliases?.some((a) => a.includes(kw)));
+        }
+        if (options.sort === "name") {
+          members.sort((a, b) => a.name.localeCompare(b.name));
+        }
+        const total = members.length;
+        const items = members.slice(0, limit);
+        return {
+          data: { items },
+          meta: { session: ctx.session, total, returned: items.length },
+          renderText: () => items.map((m, i) => `${i + 1}. ${m.name} (#${m.id}) - ${m.messageCount} messages`).join("\n") || "No members."
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  membersCmd.command("history").description("Show name change history for a member").requiredOption("--member <ref>", "Member id, exact name, or `me`").option("--session <ref>", "Session id or unique name").option("--format <format>", "Output format: agent|json|text").action(async (options) => {
+    await runQuery("members.history", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const member = resolveMember(ctx.db, options.member);
+        const items = getMemberNameHistory(ctx.db, member.id).map((h) => ({
+          nameType: h.nameType,
+          name: h.name,
+          since: epochToIso(h.startTs),
+          until: h.endTs == null ? null : epochToIso(h.endTs)
+        }));
+        return {
+          data: { items },
+          meta: { session: ctx.session, member, returned: items.length },
+          renderText: () => items.map((h) => `${h.since} ~ ${h.until ?? "present"}  [${h.nameType}] ${h.name}`).join("\n") || "No name changes recorded."
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+}
+function legacySessionsList(options) {
+  const { dbManager } = initRuntime();
+  const sessionIds = dbManager.listSessionIds();
+  if (sessionIds.length === 0) {
+    console.log("No chat sessions found.");
+    console.log(`Data directory: ${dbManager["pathProvider"].getUserDataDir()}`);
+    dbManager.closeAll();
+    return;
+  }
+  const sessions = sessionIds.map((id) => {
+    const db = dbManager.open(id);
+    if (!db) return null;
+    const meta = getSessionMeta(db);
+    if (!meta) return null;
+    const overview = getSessionOverview(db);
+    return { id, ...meta, ...overview };
+  }).filter(Boolean);
+  if (options.format === "json") {
+    console.log(JSON.stringify(sessions, null, 2));
+  } else {
+    console.log(`${sessions.length} session(s) found:
+`);
+    for (const s of sessions) {
+      if (!s) continue;
+      const range = s.firstMessageTs && s.lastMessageTs ? `${new Date(s.firstMessageTs * 1e3).toLocaleDateString()} ~ ${new Date(s.lastMessageTs * 1e3).toLocaleDateString()}` : "";
+      console.log(`  ${s.name}`);
+      console.log(`    ID: ${s.id}`);
+      console.log(
+        `    Platform: ${s.platform} | Type: ${s.type} | Members: ${s.totalMembers} | Messages: ${s.totalMessages}`
+      );
+      if (range) console.log(`    Range: ${range}`);
+      console.log();
+    }
+  }
+  dbManager.closeAll();
+}
+function legacyMembersList(sessionId, options) {
+  const { dbManager } = initRuntime();
+  const db = dbManager.open(sessionId);
+  if (!db) {
+    console.error(`Session ${sessionId} not found`);
+    process.exit(1);
+  }
+  const members = getMembers(db);
+  if (options.format === "json") {
+    console.log(JSON.stringify(members, null, 2));
+  } else {
+    console.log(`${members.length} member(s):
+`);
+    for (const [i, m] of members.entries()) {
+      console.log(`  ${i + 1}. ${m.name} (${m.platformId}) - ${m.messageCount} messages`);
+    }
+  }
+  dbManager.closeAll();
+}
+
+// src/query/messages-output.ts
+var MAX_TOKENS_DEFAULT = 4e3;
+var MAX_TOKENS_CAP = 32e3;
+function privacyOnlyConfig(config) {
+  return { ...config, mergeConsecutive: false, denoise: false, anonymizeNames: false };
+}
+function assertRawFormatCompatible(format, options) {
+  if (options.raw && format === "agent") {
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: "--raw cannot be combined with --format agent",
+      hint: "Raw output is a debugging path; use --format json or --format text with --raw"
+    });
+  }
+}
+function buildAgentText(messages, ctx, options) {
+  const maxTokens = parseLimit(options.maxTokens, MAX_TOKENS_DEFAULT, MAX_TOKENS_CAP, "--max-tokens");
+  const maxChars = options.full ? 0 : options.maxChars !== void 0 ? parseLimit(options.maxChars, 200, 1e4, "--max-chars") : options.defaultMaxChars;
+  const result = applyPreprocessingPipeline({
+    rawMessages: messages,
+    preprocessConfig: ctx.preprocessConfig,
+    locale: ctx.locale,
+    anonymizeNames: ctx.preprocessConfig.anonymizeNames ?? false,
+    ownerPlatformId: ctx.ownerPlatformId,
+    maxToolResultTokens: maxTokens,
+    truncationStrategy: options.strategy,
+    includeMessageIds: true,
+    hitIds: options.hitIds,
+    maxContentChars: maxChars
+  });
+  const config = ctx.preprocessConfig;
+  const preprocess = {
+    cleaned: config.dataCleaning !== false,
+    denoised: !!config.denoise,
+    merged: !!config.mergeConsecutive,
+    desensitized: !!config.desensitize && config.desensitizeRules.some((r) => r.enabled),
+    truncated: result.stats.truncated
+  };
+  const preprocessDetail = options.verbose ? {
+    inputMessages: result.stats.input,
+    renderedBlocks: result.stats.renderedBlocks,
+    cleaned: result.stats.cleaned,
+    blacklistRemoved: result.stats.blacklistRemoved,
+    denoiseRemoved: result.stats.denoiseRemoved,
+    mergeCombined: result.stats.mergeCombined,
+    desensitizeRulesApplied: result.stats.desensitizeRulesApplied
+  } : void 0;
+  return { text: result.text, stats: result.stats, preprocess, preprocessDetail };
+}
+var JSON_ITEM_FIELDS = /* @__PURE__ */ new Set(["id", "time", "senderId", "senderName", "type", "content", "hit"]);
+function toJsonItems(messages, preprocessConfig, options) {
+  const visible = options.raw ? messages : preprocessMessages(messages, privacyOnlyConfig(preprocessConfig));
+  const noContent = options.content === false;
+  const maxChars = options.full ? 0 : options.maxChars !== void 0 ? parseLimit(options.maxChars, 300, 1e4, "--max-chars") : options.defaultMaxChars ?? 300;
+  let fields;
+  if (options.fields) {
+    fields = new Set(options.fields.split(",").map((f) => f.trim()));
+    for (const field of fields) {
+      if (!JSON_ITEM_FIELDS.has(field)) {
+        throw new QueryError({
+          code: "INVALID_ARGUMENT",
+          message: `Unknown field: ${field}`,
+          hint: `Supported fields: ${[...JSON_ITEM_FIELDS].join(", ")}`
+        });
+      }
+    }
+  }
+  return visible.map((msg) => {
+    let content = msg.content;
+    if (noContent) {
+      content = void 0;
+    } else if (content && maxChars > 0 && content.length > maxChars) {
+      content = content.slice(0, maxChars) + "...";
+    }
+    const item = {
+      id: msg.id,
+      time: epochToIso(msg.timestamp),
+      ...msg.senderId !== void 0 ? { senderId: msg.senderId } : {},
+      senderName: msg.senderName,
+      ...msg.type !== void 0 ? { type: messageTypeToString(msg.type) } : {},
+      ...content !== void 0 ? { content } : {},
+      ...options.hitIds?.has(msg.id) ? { hit: true } : {}
+    };
+    if (fields) {
+      for (const key of Object.keys(item)) {
+        if (!fields.has(key)) delete item[key];
+      }
+    }
+    return item;
+  });
+}
+function sortChronological(messages) {
+  return [...messages].sort((a, b) => a.timestamp - b.timestamp || a.id - b.id);
+}
+function buildMessagesResult(format, ctx, options, messages, meta, shape) {
+  const chronological = sortChronological(messages);
+  if (format === "json") {
+    const items = toJsonItems(chronological, ctx.preprocessConfig, {
+      maxChars: options.maxChars,
+      full: options.full,
+      fields: options.fields,
+      content: options.content,
+      raw: options.raw,
+      hitIds: shape.hitIds,
+      defaultMaxChars: shape.defaultMaxChars
+    });
+    return {
+      data: { items },
+      meta: {
+        ...meta,
+        returned: items.length,
+        preprocess: options.raw ? { raw: true } : {
+          cleaned: ctx.preprocessConfig.dataCleaning !== false,
+          desensitized: !!ctx.preprocessConfig.desensitize && ctx.preprocessConfig.desensitizeRules.some((r) => r.enabled)
+        }
+      }
+    };
+  }
+  if (options.raw) {
+    return {
+      data: { items: chronological },
+      renderText: () => chronological.map((m) => `[#${m.id}] ${new Date(m.timestamp * 1e3).toLocaleString()} ${m.senderName}: ${m.content ?? ""}`).join("\n") || "No messages."
+    };
+  }
+  const agent = buildAgentText(chronological, ctx, {
+    hitIds: shape.hitIds,
+    strategy: shape.strategy,
+    maxTokens: options.maxTokens,
+    maxChars: options.maxChars,
+    full: options.full,
+    verbose: options.verbose,
+    defaultMaxChars: shape.defaultMaxChars
+  });
+  return {
+    data: { text: agent.text },
+    meta: {
+      ...meta,
+      preprocess: agent.preprocess,
+      ...agent.preprocessDetail ? { preprocessDetail: agent.preprocessDetail } : {}
+    },
+    renderText: () => agent.text
+  };
+}
+
+// src/query/commands-messages.ts
+function capExpandedSearchMessages(messages, hitIds, maxMessages) {
+  if (maxMessages <= 0) return [];
+  if (messages.length <= maxMessages) return messages;
+  const capped = messages.slice(0, maxMessages);
+  const includedIds = new Set(capped.map((message) => message.id));
+  const missingHits = messages.filter((message) => hitIds.has(message.id) && !includedIds.has(message.id));
+  for (const hit of missingHits) {
+    let replaceIndex = -1;
+    for (let i = capped.length - 1; i >= 0; i--) {
+      if (!hitIds.has(capped[i].id)) {
+        replaceIndex = i;
+        break;
+      }
+    }
+    if (replaceIndex === -1) break;
+    capped[replaceIndex] = hit;
+  }
+  return capped.sort((a, b) => messages.indexOf(a) - messages.indexOf(b));
+}
+function appendUniqueTailMessages(expanded, tail) {
+  const expandedIds = new Set(expanded.map((message) => message.id));
+  return [...expanded, ...tail.filter((message) => !expandedIds.has(message.id))];
+}
+function parseContextIds(value) {
+  const tokens = value.split(",").map((token) => token.trim());
+  const ids = tokens.map((token) => token.length > 0 ? Number(token) : Number.NaN);
+  if (ids.length === 0 || ids.some((id) => !Number.isInteger(id) || id <= 0)) {
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: `Invalid --id value: ${value}`,
+      hint: "Pass positive numeric message ids, e.g. --id 1021 or --id 1021,1058"
+    });
+  }
+  return ids;
+}
+function parseSearchKeywords(values) {
+  const keywords = values.map((value) => value.trim()).filter(Boolean);
+  if (keywords.length === 0) {
+    throw new QueryError({
+      code: "INVALID_ARGUMENT",
+      message: "Invalid search keywords",
+      hint: "Pass at least one non-empty search keyword"
+    });
+  }
+  return keywords;
+}
+function searchTruncationStrategy(sort) {
+  return sort === "desc" ? "keep_last" : "keep_first";
+}
+function assertContextAnchorsPresent(ids, messages, rawValue) {
+  const returnedIds = new Set(messages.map((message) => message.id));
+  if (ids.some((id) => !returnedIds.has(id))) {
+    throw new QueryError({
+      code: "MESSAGE_NOT_FOUND",
+      message: `No messages found for id(s) ${rawValue}`,
+      hint: "Use a single numeric id from [#id]/[#id*] markers; merged [#a-b] ranges are display-only"
+    });
+  }
+}
+function addSharedOptions(cmd, options = {}) {
+  const shared = cmd.option("--session <ref>", "Session id or unique name (auto-selected when only one exists)");
+  if (options.includeTime !== false) {
+    shared.option("--since <t>", 'Start time: YYYY-MM-DD, "YYYY-MM-DD HH:mm", ISO 8601, today, yesterday').option("--until <t>", "End time (date-only values include the whole day)").option("--last <dur>", "Relative window: <N>h|d|w (mutually exclusive with --since/--until)");
+  }
+  return shared.option("--format <format>", "Output format: agent|json|text (agents should pass agent explicitly)").option("--max-tokens <n>", "Token budget for agent text (default 4000)").option("--max-chars <n>", "Per-message content char limit").option("--full", "Disable per-message content truncation").option("--fields <a,b>", "json format: only include these item fields").option("--no-content", "json format: omit message content (distribution scouting)").option("--raw", "Bypass privacy preprocessing (debugging; requires user opt-in, json/text only)").option("--verbose", "Include preprocessing diagnostics in meta");
+}
+function registerMessageCommands(program2) {
+  const messagesCmd = program2.command("messages").description("Query messages (list, search, context, between)");
+  const listCmd = messagesCmd.command("list").description("List messages in a time window (most recent page first, rendered chronologically)").option("--member <ref>", "Filter by sender (member id, exact name, or `me`)").option("--cursor <token>", "Opaque pagination cursor from meta.nextCursor").option("--limit <n>", "Messages per page (default 50, max 500)");
+  addSharedOptions(listCmd);
+  listCmd.action(async (options) => {
+    await runQuery("messages.list", options, async (format) => {
+      assertRawFormatCompatible(format, options);
+      const ctx = createQueryContext(options);
+      try {
+        assertRawAllowed(ctx, options);
+        const time = resolveTimeOptionsForCursor(options);
+        const member = options.member ? resolveMember(ctx.db, options.member) : void 0;
+        const limit = parseLimit(options.limit, 50, 500, "--limit", 1);
+        const excludeKeywords = options.raw ? void 0 : ctx.preprocessConfig.blacklistKeywords;
+        const fingerprint = queryFingerprint({
+          command: "messages.list",
+          session: ctx.session.id,
+          startTs: time.startTs ?? null,
+          endTs: time.endTs ?? null,
+          member: member?.id ?? null,
+          exclude: excludeKeywords ?? []
+        });
+        const offset = options.cursor ? decodeCursor(options.cursor, fingerprint) : 0;
+        const result = searchMessagesByKeywords(ctx.db, [], {
+          startTs: time.startTs,
+          endTs: time.endTs,
+          senderId: member?.id,
+          limit,
+          offset,
+          excludeKeywords,
+          sort: "desc"
+        });
+        const total = result.total ?? result.messages.length;
+        const hasMore = offset + result.messages.length < total;
+        const meta = {
+          session: ctx.session,
+          timeRange: time.meta,
+          ...member ? { member } : {},
+          totalHits: total,
+          returnedHits: result.messages.length,
+          hasMore,
+          ...hasMore ? { nextCursor: encodeCursor(offset + result.messages.length, fingerprint, { time }) } : {}
+        };
+        return buildMessagesResult(format, ctx, options, result.messages, meta, {
+          strategy: "keep_last"
+        });
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  const searchCmd = messagesCmd.command("search").description("Search messages by keywords (LIKE match; multiple keywords default to OR)").argument("<keywords...>", "Search keywords").option("--match <mode>", "Keyword join mode: any (OR) | all (AND)", "any").option("--member <ref>", "Filter by sender (member id, exact name, or `me`)").option("--context <n>", "Context messages before/after each hit (default 0)").option("--sort <dir>", 'Hit order by time: asc|desc (asc for "who said it first")', "desc").option("--cursor <token>", "Opaque pagination cursor from meta.nextCursor").option("--limit <n>", "Hits per page (default 20, max 500)").option("--max-messages <n>", "Cap on total messages after context expansion (default 200)");
+  addSharedOptions(searchCmd);
+  searchCmd.action(
+    async (keywords, options) => {
+      await runQuery("messages.search", options, async (format) => {
+        assertRawFormatCompatible(format, options);
+        const searchKeywords = parseSearchKeywords(keywords);
+        if (options.match !== "any" && options.match !== "all") {
+          throw new QueryError({
+            code: "INVALID_ARGUMENT",
+            message: `Invalid --match value: ${options.match}`,
+            hint: "Supported: any (OR), all (AND)"
+          });
+        }
+        if (options.sort !== "asc" && options.sort !== "desc") {
+          throw new QueryError({
+            code: "INVALID_ARGUMENT",
+            message: `Invalid --sort value: ${options.sort}`,
+            hint: "Supported: asc, desc"
+          });
+        }
+        const ctx = createQueryContext(options);
+        try {
+          assertRawAllowed(ctx, options);
+          const time = resolveTimeOptionsForCursor(options);
+          const member = options.member ? resolveMember(ctx.db, options.member) : void 0;
+          const limit = parseLimit(options.limit, 20, 500, "--limit", 1);
+          const context = parseLimit(options.context, 0, 50, "--context");
+          const maxMessages = parseLimit(options.maxMessages, 200, 2e3, "--max-messages");
+          const excludeKeywords = options.raw ? void 0 : ctx.preprocessConfig.blacklistKeywords;
+          const fingerprint = queryFingerprint({
+            command: "messages.search",
+            session: ctx.session.id,
+            keywords: searchKeywords,
+            match: options.match,
+            sort: options.sort,
+            startTs: time.startTs ?? null,
+            endTs: time.endTs ?? null,
+            member: member?.id ?? null,
+            exclude: excludeKeywords ?? []
+          });
+          const offset = options.cursor ? decodeCursor(options.cursor, fingerprint) : 0;
+          const result = searchMessagesByKeywords(ctx.db, searchKeywords, {
+            startTs: time.startTs,
+            endTs: time.endTs,
+            senderId: member?.id,
+            limit,
+            offset,
+            matchMode: options.match,
+            excludeKeywords,
+            sort: options.sort
+          });
+          const hits = result.messages;
+          const hitIds = new Set(hits.map((m) => m.id));
+          const warnings = [];
+          let pipelineMessages = hits;
+          if (context > 0 && hits.length > 0) {
+            const perHitCost = context * 2 + 1;
+            let expandableHits = hits;
+            if (hits.length * perHitCost > maxMessages) {
+              const allowed = Math.max(1, Math.floor(maxMessages / perHitCost));
+              expandableHits = hits.slice(0, allowed);
+              warnings.push(
+                `--max-messages ${maxMessages}: context expanded for the first ${allowed} of ${hits.length} hits`
+              );
+            }
+            const expanded = getSearchMessageContext(
+              ctx.db,
+              expandableHits.map((m) => m.id),
+              context,
+              context
+            );
+            const keptHits = new Set(expandableHits.map((m) => m.id));
+            const tail = hits.filter((m) => !keptHits.has(m.id));
+            pipelineMessages = appendUniqueTailMessages(expanded, tail);
+            if (pipelineMessages.length > maxMessages) {
+              pipelineMessages = capExpandedSearchMessages(pipelineMessages, hitIds, maxMessages);
+              warnings.push(`response capped at ${maxMessages} messages`);
+            }
+          }
+          const total = result.total ?? hits.length;
+          const hasMore = offset + hits.length < total;
+          const meta = {
+            session: ctx.session,
+            timeRange: time.meta,
+            query: { keywords: searchKeywords, match: options.match, engine: "like", sort: options.sort, context },
+            ...member ? { member } : {},
+            totalHits: total,
+            returnedHits: hits.length,
+            hasMore,
+            ...hasMore ? { nextCursor: encodeCursor(offset + hits.length, fingerprint, { time }) } : {},
+            ...warnings.length > 0 ? { warnings } : {}
+          };
+          return buildMessagesResult(format, ctx, options, pipelineMessages, meta, {
+            hitIds,
+            strategy: searchTruncationStrategy(options.sort),
+            defaultMaxChars: 120
+          });
+        } finally {
+          ctx.close();
+        }
+      });
+    }
+  );
+  const contextCmd = messagesCmd.command("context").description("Show messages around specific numeric message ids").requiredOption("--id <ids>", "Message id(s), comma-separated").option("--window <n>", "Messages before/after each id (default 10, max 100)");
+  addSharedOptions(contextCmd, { includeTime: false });
+  contextCmd.action(async (options) => {
+    await runQuery("messages.context", options, async (format) => {
+      assertRawFormatCompatible(format, options);
+      const ids = parseContextIds(options.id);
+      const ctx = createQueryContext(options);
+      try {
+        assertRawAllowed(ctx, options);
+        const window = parseLimit(options.window, 10, 100, "--window");
+        const messages = getMessageContext(ctx.db, ids, window);
+        assertContextAnchorsPresent(ids, messages, options.id);
+        const meta = {
+          session: ctx.session,
+          anchorIds: ids,
+          window
+        };
+        return buildMessagesResult(format, ctx, options, messages, meta, {
+          hitIds: new Set(ids),
+          strategy: "keep_last"
+        });
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  const betweenCmd = messagesCmd.command("between").description("Conversation between two members (repeat --member exactly twice)").option("--member <ref>", "Member id, exact name, or `me` (repeat twice)", collectMembers, []).option("--cursor <token>", "Opaque pagination cursor from meta.nextCursor").option("--limit <n>", "Messages per page (default 50, max 500)");
+  addSharedOptions(betweenCmd);
+  betweenCmd.action(async (options) => {
+    await runQuery("messages.between", options, async (format) => {
+      assertRawFormatCompatible(format, options);
+      if (options.member.length !== 2) {
+        throw new QueryError({
+          code: "INVALID_ARGUMENT",
+          message: `--member must be given exactly twice (got ${options.member.length})`,
+          hint: "Example: messages between --member me --member \u5C0F\u7EA2"
+        });
+      }
+      const ctx = createQueryContext(options);
+      try {
+        assertRawAllowed(ctx, options);
+        const time = resolveTimeOptionsForCursor(options);
+        const memberA = resolveMember(ctx.db, options.member[0]);
+        const memberB = resolveMember(ctx.db, options.member[1]);
+        const limit = parseLimit(options.limit, 50, 500, "--limit", 1);
+        const excludeKeywords = options.raw ? void 0 : ctx.preprocessConfig.blacklistKeywords;
+        const fingerprint = queryFingerprint({
+          command: "messages.between",
+          session: ctx.session.id,
+          members: [memberA.id, memberB.id],
+          startTs: time.startTs ?? null,
+          endTs: time.endTs ?? null,
+          exclude: excludeKeywords ?? []
+        });
+        const offset = options.cursor ? decodeCursor(options.cursor, fingerprint) : 0;
+        const timeFilter = time.startTs !== void 0 || time.endTs !== void 0 ? { startTs: time.startTs ?? 0, endTs: time.endTs ?? Math.floor(Date.now() / 1e3) } : void 0;
+        const result = getConversationBetween(ctx.db, memberA.id, memberB.id, timeFilter, limit, {
+          offset,
+          excludeKeywords
+        });
+        const returned = result.messages.length;
+        const hasMore = offset + returned < result.total;
+        const meta = {
+          session: ctx.session,
+          timeRange: time.meta,
+          members: [memberA, memberB],
+          totalHits: result.total,
+          returnedHits: returned,
+          hasMore,
+          ...hasMore ? { nextCursor: encodeCursor(offset + returned, fingerprint, { time }) } : {}
+        };
+        return buildMessagesResult(format, ctx, options, result.messages, meta, {
+          strategy: "keep_last"
+        });
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+}
+function collectMembers(value, previous) {
+  return [...previous, value];
+}
+
+// src/query/commands-stats.ts
+function addStatsOptions(cmd) {
+  return cmd.option("--session <ref>", "Session id or unique name (auto-selected when only one exists)").option("--since <t>", "Start time: YYYY-MM-DD, ISO 8601, today, yesterday").option("--until <t>", "End time (date-only values include the whole day)").option("--last <dur>", "Relative window: <N>h|d|w").option("--format <format>", "Output format: agent|json|text");
+}
+function toTimeFilter(time) {
+  if (time.startTs === void 0 && time.endTs === void 0) return void 0;
+  return { startTs: time.startTs ?? 0, endTs: time.endTs ?? Math.floor(Date.now() / 1e3) };
+}
+function responseStatsMessagesSql() {
+  return `SELECT msg.id, msg.sender_id, COALESCE(m.group_nickname, m.account_name) AS name, msg.ts
+           FROM message msg
+           JOIN member m ON msg.sender_id = m.id
+           WHERE msg.type = 0 AND msg.ts >= @startTs
+           ORDER BY msg.ts ASC, msg.id ASC`;
+}
+function registerStatsCommands(program2) {
+  const statsCmd = program2.command("stats").description("Session statistics (overview, activity, time, keywords, response)").argument("[session-id]", "legacy: session id (deprecated alias)").option("--format <format>", "Output format").option("--top <n>", "legacy: top N members", "10").action((sessionId, options, command) => {
+    if (!sessionId) {
+      command.help({ error: false });
+      return;
+    }
+    console.error(
+      "[Deprecated] `chatlab stats <session-id>` \u2014 use `chatlab stats overview --session <id>`; alias kept for one major version"
+    );
+    legacyStats(sessionId, options);
+  });
+  statsCmd.command("overview").description("Session overview: totals, time range, top members").option("--session <ref>", "Session id or unique name").option("--format <format>", "Output format: agent|json|text").action(async (options) => {
+    await runQuery("stats.overview", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const overview = getChatOverview(ctx.db);
+        if (!overview) {
+          throw new QueryError({ code: "SESSION_NOT_FOUND", message: "Session metadata missing" });
+        }
+        const data = {
+          name: overview.name,
+          platform: overview.platform,
+          type: overview.type,
+          totalMessages: overview.totalMessages,
+          totalMembers: overview.totalMembers,
+          firstMessage: overview.firstMessageTs == null ? null : epochToIso(overview.firstMessageTs),
+          lastMessage: overview.lastMessageTs == null ? null : epochToIso(overview.lastMessageTs),
+          topMembers: overview.topMembers,
+          summaryCount: overview.summaryCount
+        };
+        return {
+          data,
+          meta: { session: ctx.session },
+          renderText: () => `${data.name}
+Messages: ${data.totalMessages} | Members: ${data.totalMembers}
+Range: ${data.firstMessage ?? "-"} ~ ${data.lastMessage ?? "-"}
+` + data.topMembers.map((m, i) => `  ${i + 1}. ${m.name} - ${m.count}`).join("\n")
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  const activityCmd = statsCmd.command("activity").description("Member activity ranking");
+  addStatsOptions(activityCmd);
+  activityCmd.option("--top <n>", "Top N members (default 10, max 100)");
+  activityCmd.action(async (options) => {
+    await runQuery("stats.activity", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const time = parseTimeOptions(options);
+        const top = parseLimit(options.top, 10, 100, "--top");
+        const items = getMemberActivity(ctx.db, toTimeFilter(time)).slice(0, top).map((m) => ({ id: m.memberId, name: m.name, messageCount: m.messageCount, percentage: m.percentage }));
+        return {
+          data: { items },
+          meta: { session: ctx.session, timeRange: time.meta, returned: items.length },
+          renderText: () => items.map((m, i) => `${i + 1}. ${m.name} - ${m.messageCount} messages (${m.percentage}%)`).join("\n") || "No activity."
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  const timeCmd = statsCmd.command("time").description("Message distribution over time");
+  addStatsOptions(timeCmd);
+  timeCmd.requiredOption("--by <unit>", "Bucket unit: hour|weekday|day|month");
+  timeCmd.action(async (options) => {
+    await runQuery("stats.time", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const time = parseTimeOptions(options);
+        const filter = toTimeFilter(time);
+        let items;
+        switch (options.by) {
+          case "hour":
+            items = getHourlyActivity(ctx.db, filter);
+            break;
+          case "weekday":
+            items = getWeekdayActivity(ctx.db, filter);
+            break;
+          case "day":
+            items = getDailyActivity(ctx.db, filter);
+            break;
+          case "month":
+            items = getMonthlyActivity(ctx.db, filter);
+            break;
+          default:
+            throw new QueryError({
+              code: "INVALID_ARGUMENT",
+              message: `Invalid --by value: ${options.by}`,
+              hint: "Supported: hour, weekday, day, month"
+            });
+        }
+        return {
+          data: { items },
+          meta: { session: ctx.session, timeRange: time.meta, by: options.by, returned: items.length }
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  const keywordsCmd = statsCmd.command("keywords").description("High-frequency words (privacy-filtered)");
+  addStatsOptions(keywordsCmd);
+  keywordsCmd.option("--top <n>", "Top N words (default 20, max 100)");
+  keywordsCmd.option("--member <ref>", "Filter by sender (member id, exact name, or `me`)");
+  keywordsCmd.action(async (options) => {
+    await runQuery("stats.keywords", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const time = parseTimeOptions(options);
+        const top = parseLimit(options.top, 20, 100, "--top");
+        const member = options.member ? resolveMember(ctx.db, options.member) : void 0;
+        const fetchN = Math.max(top * 3, top + 20);
+        let result;
+        try {
+          result = computeWordFrequency(ctx.db, {
+            sessionId: ctx.session.id,
+            locale: ctx.locale,
+            timeFilter: toTimeFilter(time),
+            memberId: member?.id,
+            topN: fetchN,
+            excludeKeywords: ctx.preprocessConfig.blacklistKeywords
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (/jieba|segment/i.test(message)) {
+            return {
+              data: { items: [], status: "segmentation_unavailable" },
+              meta: {
+                session: ctx.session,
+                hint: "Word segmentation engine unavailable (optional dependency @node-rs/jieba failed to load)"
+              }
+            };
+          }
+          throw err;
+        }
+        const enabledRules2 = ctx.preprocessConfig.desensitize ? ctx.preprocessConfig.desensitizeRules.filter((r) => r.enabled) : [];
+        const items = result.words.filter((w) => enabledRules2.length === 0 || desensitizeText(w.word, enabledRules2) === w.word).slice(0, top);
+        return {
+          data: { items },
+          meta: {
+            session: ctx.session,
+            timeRange: time.meta,
+            ...member ? { member } : {},
+            totalMessages: result.totalMessages,
+            uniqueWords: result.uniqueWords,
+            returned: items.length,
+            ...items.length === 0 && result.totalMessages > 0 ? {
+              hint: "No words extracted; the zh-CN segmentation dictionary may be missing (downloadable in the ChatLab app)"
+            } : {}
+          },
+          renderText: () => items.map((w, i) => `${i + 1}. ${w.word} (${w.count})`).join("\n") || "No words."
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  const responseCmd = statsCmd.command("response").description("Reply speed ranking (median response gap)");
+  responseCmd.option("--session <ref>", "Session id or unique name").option("--last <dur>", "Relative window: <N>h|d|w (default 30d)").option("--top <n>", "Top N responders (default 10, max 100)").option("--format <format>", "Output format: agent|json|text");
+  responseCmd.action(async (options) => {
+    await runQuery("stats.response", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const time = parseTimeOptions({ last: options.last ?? "30d" });
+        const top = parseLimit(options.top, 10, 100, "--top");
+        const rows = executeParameterizedSql(
+          ctx.db,
+          responseStatsMessagesSql(),
+          { startTs: time.startTs ?? 0 }
+        );
+        const items = computeResponseTimeStats(
+          rows.map((r) => ({ senderId: r.sender_id, name: r.name, ts: r.ts })),
+          top
+        );
+        return {
+          data: { items },
+          meta: { session: ctx.session, timeRange: time.meta, returned: items.length },
+          renderText: () => items.map(
+            (s, i) => `${i + 1}. ${s.name} - median ${s.medianSeconds}s, avg ${s.avgSeconds}s (${s.responseCount})`
+          ).join("\n") || "Not enough response data."
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+}
+function legacyStats(sessionId, options) {
+  const { dbManager } = initRuntime();
+  const db = dbManager.open(sessionId);
+  if (!db) {
+    console.error(`Session ${sessionId} not found`);
+    process.exit(1);
+  }
+  const meta = getSessionMeta(db);
+  const overview = getSessionOverview(db);
+  const topMembers = getMemberActivity(db).slice(0, parseInt(options.top));
+  if (options.format === "json") {
+    console.log(JSON.stringify({ meta, overview, topMembers }, null, 2));
+  } else {
+    console.log(`
+Session: ${meta?.name}`);
+    console.log(`Platform: ${meta?.platform} | Type: ${meta?.type}`);
+    console.log(`Total messages: ${overview.totalMessages}`);
+    console.log(`Total members: ${overview.totalMembers}`);
+    const range = overview.firstMessageTs && overview.lastMessageTs ? `${new Date(overview.firstMessageTs * 1e3).toLocaleDateString()} ~ ${new Date(overview.lastMessageTs * 1e3).toLocaleDateString()}` : "Unknown";
+    console.log(`Time range: ${range}`);
+    if (topMembers.length > 0) {
+      console.log(`
+Activity ranking (Top ${options.top}):`);
+      for (const [i, m] of topMembers.entries()) {
+        console.log(`  ${i + 1}. ${m.name} - ${m.messageCount} messages (${m.percentage}%)`);
+      }
+    }
+  }
+  dbManager.closeAll();
+}
+
+// src/query/commands-topics-sql.ts
+function enabledRules(ctx) {
+  return ctx.preprocessConfig.desensitize ? ctx.preprocessConfig.desensitizeRules.filter((r) => r.enabled) : [];
+}
+function parseSqlRowLimit(value) {
+  return parseLimit(value, 100, 1e3, "--limit", 1);
+}
+function clampSqlRows(rows, maxRows, alreadyTruncated) {
+  if (maxRows <= 0 || rows.length <= maxRows) {
+    return { rows, truncated: alreadyTruncated };
+  }
+  return { rows: rows.slice(0, maxRows), truncated: true };
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var SQL_IDENTIFIER = String.raw`(?:"[^"]+"|'[^']+'|` + "`[^`]+`" + String.raw`|\[[^\]]+\]|[A-Za-z_][A-Za-z0-9_]*)`;
+var SQL_TABLE_REF_END = String.raw`(?=\s|$|[,;])`;
+var SQL_KEYWORDS = /* @__PURE__ */ new Set([
+  "where",
+  "join",
+  "left",
+  "right",
+  "inner",
+  "outer",
+  "cross",
+  "order",
+  "group",
+  "limit",
+  "on",
+  "using"
+]);
+function sqlNamePattern(name) {
+  const escaped = escapeRegExp(name);
+  return String.raw`(?:"${escaped}"|'${escaped}'|` + "`" + escaped + "`" + String.raw`|\[${escaped}\]|${escaped})`;
+}
+function unquoteSqlIdentifier(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed.slice(1, -1);
+  const quote = trimmed[0];
+  if ((quote === '"' || quote === "'" || quote === "`") && trimmed.endsWith(quote)) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function messageTablePattern() {
+  const schemaPrefix = String.raw`(?:${SQL_IDENTIFIER}\s*\.\s*)?`;
+  return `${schemaPrefix}${sqlNamePattern("message")}`;
+}
+function selectsMessageStar(query) {
+  const selectMatch = query.match(/\bselect\b([\s\S]+?)\bfrom\b/i);
+  if (!selectMatch) return false;
+  const projection = selectMatch[1];
+  const messageTable = messageTablePattern();
+  if (/(^|[,\s])\*(?=$|[,\s])/i.test(projection)) {
+    return new RegExp(String.raw`\b(?:from|join)\s+${messageTable}${SQL_TABLE_REF_END}`, "i").test(query);
+  }
+  const aliasMatches = query.matchAll(
+    new RegExp(String.raw`\b(?:from|join)\s+${messageTable}(?:\s+(?:as\s+)?(${SQL_IDENTIFIER}))?`, "gi")
+  );
+  const aliases = /* @__PURE__ */ new Set(["message"]);
+  for (const match of aliasMatches) {
+    const alias = match[1] ? unquoteSqlIdentifier(match[1]).toLowerCase() : void 0;
+    if (alias && !SQL_KEYWORDS.has(alias)) aliases.add(alias);
+  }
+  return [...aliases].some(
+    (alias) => new RegExp(`${sqlNamePattern(alias)}\\s*\\.\\s*\\*(?=$|[\\s,])`, "i").test(projection)
+  );
+}
+function assertSqlPrivacyAllowed(query, raw) {
+  if (raw) return;
+  if (!/(^|[^A-Za-z0-9_])["'`[]?content["'`\]]?(?![A-Za-z0-9_])/i.test(query) && !selectsMessageStar(query)) {
+    return;
+  }
+  throw new QueryError({
+    code: "INVALID_ARGUMENT",
+    message: "SQL queries that read message content require --raw",
+    hint: "Use dedicated message commands for privacy-processed content, or enable raw mode and pass --raw for debugging"
+  });
+}
+function assertSqlResultPrivacyAllowed(columns, raw) {
+  if (raw) return;
+  if (!columns.some((column) => unquoteSqlIdentifier(column).toLowerCase() === "content")) return;
+  throw new QueryError({
+    code: "INVALID_ARGUMENT",
+    message: "SQL results that include message content require --raw",
+    hint: "Use dedicated message commands for privacy-processed content, or enable raw mode and pass --raw for debugging"
+  });
+}
+function topicsAgentText(items) {
+  if (items.length === 0) return "No summaries.";
+  const blocks = items.map((t) => {
+    const header = `[#${t.id}] ${t.since} ~ ${t.until} (${t.messages} msgs) ${t.participants.join(", ")}`;
+    return t.summary ? `${header}
+${t.summary}` : header;
+  });
+  return `returned: ${items.length}
+
+${blocks.join("\n\n")}`;
+}
+function registerTopicCommands(program2) {
+  const topicsCmd = program2.command("topics").description("Conversation segments and AI summaries");
+  topicsCmd.command("list").description("List AI-generated segment summaries (desensitized)").option("--session <ref>", "Session id or unique name").option("--since <t>", "Start time").option("--until <t>", "End time").option("--last <dur>", "Relative window: <N>h|d|w").option("--query <kw>", "Filter summaries by substring").option("--limit <n>", "Max summaries (default 20, max 100)").option("--format <format>", "Output format: agent|json|text").action(
+    async (options) => {
+      await runQuery("topics.list", options, async (format) => {
+        const ctx = createQueryContext(options);
+        try {
+          const time = parseTimeOptions(options);
+          const limit = parseLimit(options.limit, 20, 100, "--limit");
+          const timeFilter = time.startTs !== void 0 || time.endTs !== void 0 ? { startTs: time.startTs ?? 0, endTs: time.endTs ?? Math.floor(Date.now() / 1e3) } : void 0;
+          const rows = getSegmentSummaries(ctx.db, { limit: limit + 20, timeFilter });
+          const rules = enabledRules(ctx);
+          const blacklist = ctx.preprocessConfig.blacklistKeywords;
+          let removed = 0;
+          const items = rows.filter((row) => {
+            if (row.summary && matchesBlacklist(row.summary, blacklist)) {
+              removed++;
+              return false;
+            }
+            return true;
+          }).map((row) => ({
+            id: row.id,
+            since: epochToIso(row.startTs),
+            until: epochToIso(row.endTs),
+            messages: row.messageCount,
+            participants: row.participants,
+            summary: row.summary ? desensitizeText(row.summary, rules) : row.summary
+          })).filter((row) => options.query ? (row.summary ?? "").includes(options.query) : true).slice(0, limit);
+          if (items.length === 0) {
+            const any = getSegmentSummaries(ctx.db, { limit: 1 });
+            if (any.length === 0) {
+              const hint = "Run summary generation in the ChatLab app, or use `chatlab stats keywords` as a fallback.";
+              return {
+                data: format === "agent" ? { text: "No AI summaries generated yet.", status: "summaries_not_generated" } : { items: [], status: "summaries_not_generated" },
+                meta: { session: ctx.session, hint }
+              };
+            }
+          }
+          const meta = {
+            session: ctx.session,
+            timeRange: time.meta,
+            returned: items.length,
+            ...removed > 0 ? { warnings: [`${removed} summaries removed by blacklist`] } : {}
+          };
+          return {
+            data: format === "agent" ? { text: topicsAgentText(items) } : { items },
+            meta,
+            renderText: () => topicsAgentText(items)
+          };
+        } finally {
+          ctx.close();
+        }
+      });
+    }
+  );
+  topicsCmd.command("show").description("Show original messages of one segment").requiredOption("--id <segment-id>", "Segment id from topics list").option("--session <ref>", "Session id or unique name").option("--limit <n>", "Max messages (default 200, max 500)").option("--format <format>", "Output format: agent|json|text").option("--max-tokens <n>", "Token budget for agent text (default 4000)").option("--max-chars <n>", "Per-message content char limit").option("--full", "Disable per-message content truncation").option("--fields <a,b>", "json format: only include these item fields").option("--no-content", "json format: omit message content").option("--raw", "Bypass privacy preprocessing (debugging; requires user opt-in, json/text only)").option("--verbose", "Include preprocessing diagnostics in meta").action(
+    async (options) => {
+      await runQuery("topics.show", options, async (format) => {
+        assertRawFormatCompatible(format, options);
+        const segmentId = Number(options.id);
+        if (!Number.isInteger(segmentId) || segmentId < 0) {
+          throw new QueryError({
+            code: "INVALID_ARGUMENT",
+            message: `Invalid --id value: ${options.id}`,
+            hint: "Segment ids come from `chatlab topics list`"
+          });
+        }
+        const ctx = createQueryContext(options);
+        try {
+          assertRawAllowed(ctx, options);
+          const limit = parseLimit(options.limit, 200, 500, "--limit");
+          const segment = getSegmentMessages(ctx.db, segmentId, limit);
+          if (!segment) {
+            throw new QueryError({
+              code: "SEGMENT_NOT_FOUND",
+              message: `Segment ${segmentId} not found`,
+              hint: "Run `chatlab topics list` to see available segments"
+            });
+          }
+          const meta = {
+            session: ctx.session,
+            segment: {
+              id: segment.segmentId,
+              since: epochToIso(segment.startTs),
+              until: epochToIso(segment.endTs),
+              messageCount: segment.messageCount,
+              participants: segment.participants
+            },
+            returnedHits: segment.returnedCount
+          };
+          return buildMessagesResult(format, ctx, options, segment.messages, meta, {
+            strategy: "keep_last"
+          });
+        } finally {
+          ctx.close();
+        }
+      });
+    }
+  );
+}
+function registerSqlCommands(program2) {
+  program2.command("sql").description("Read-only SQL fallback (string cells are desensitized; message content requires --raw)").argument("<query>", "SELECT / WITH statement").option("--session <ref>", "Session id or unique name").option("--limit <n>", "Max rows (default 100, max 1000)").option("--format <format>", "Output format: agent|json|text").option("--raw", "Return raw cell values (debugging; requires user opt-in)").action(async (query, options) => {
+    await runQuery("sql", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        if (!ctx.allowSql) {
+          throw new QueryError({
+            code: "SQL_DISABLED",
+            message: "The sql command is disabled by configuration",
+            hint: "The user can re-enable it with `chatlab config set cli.allow_sql true`"
+          });
+        }
+        assertRawAllowed(ctx, options);
+        assertSqlPrivacyAllowed(query, !!options.raw);
+        const limit = parseSqlRowLimit(options.limit);
+        let result;
+        try {
+          result = executeReadonlySql(ctx.db, query, limit);
+        } catch (err) {
+          throw new QueryError({
+            code: "SQL_ERROR",
+            message: err instanceof Error ? err.message : String(err),
+            hint: "Run `chatlab schema` to inspect available tables and columns"
+          });
+        }
+        assertSqlResultPrivacyAllowed(result.columns, !!options.raw);
+        const clamped = clampSqlRows(result.rows, limit, result.truncated);
+        let rows = clamped.rows;
+        let removed = 0;
+        if (!options.raw) {
+          const rules = enabledRules(ctx);
+          const blacklist = ctx.preprocessConfig.blacklistKeywords;
+          const sanitized = [];
+          for (const row of rows) {
+            let drop = false;
+            const clean = {};
+            for (const [key, value] of Object.entries(row)) {
+              if (typeof value === "string") {
+                if (matchesBlacklist(value, blacklist)) {
+                  drop = true;
+                  break;
+                }
+                clean[key] = desensitizeText(value, rules);
+              } else {
+                clean[key] = value;
+              }
+            }
+            if (drop) removed++;
+            else sanitized.push(clean);
+          }
+          rows = sanitized;
+        }
+        return {
+          data: { columns: result.columns, rows, rowCount: rows.length, truncated: clamped.truncated },
+          meta: {
+            session: ctx.session,
+            ...options.raw ? { preprocess: { raw: true } } : {},
+            ...removed > 0 ? { warnings: [`${removed} row(s) removed by blacklist`] } : {}
+          },
+          renderText: () => rows.length === 0 ? "No results." : rows.map((r) => JSON.stringify(r)).join("\n") + `
+${rows.length} row(s)${clamped.truncated ? " (truncated)" : ""}`
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+  program2.command("schema").description("Show session database schema (for the sql command)").option("--session <ref>", "Session id or unique name").option("--format <format>", "Output format: agent|json|text").action(async (options) => {
+    await runQuery("schema", options, async () => {
+      const ctx = createQueryContext(options);
+      try {
+        const items = getDatabaseSchema(ctx.db);
+        return {
+          data: { items },
+          meta: { session: ctx.session, returned: items.length },
+          renderText: () => items.map((t) => t.sql).join("\n\n")
+        };
+      } finally {
+        ctx.close();
+      }
+    });
+  });
+}
+
+// src/query/register.ts
+function registerQueryCommands(program2) {
+  registerSessionCommands(program2);
+  registerMemberCommands(program2);
+  registerMessageCommands(program2);
+  registerStatsCommands(program2);
+  registerTopicCommands(program2);
+  registerSqlCommands(program2);
+  registerLegacyAliases(program2);
+}
+function assertLegacySqlAllowed(config, sql) {
+  if (!config.cli.allow_sql) {
+    throw new QueryError({
+      code: "SQL_DISABLED",
+      message: "The sql command is disabled by configuration",
+      hint: "The user can re-enable it with `chatlab config set cli.allow_sql true`"
+    });
+  }
+  if (sql) assertSqlPrivacyAllowed(sql, false);
+}
+function registerLegacyAliases(program2) {
+  program2.command("search <session-id> <keyword>", { hidden: true }).description("Deprecated: use `chatlab messages search`").option("--limit <n>", "Max results to return", "20").option("--format <format>", "Output format (table|json)", "table").action((sessionId, keyword, options) => {
+    console.error(
+      "[Deprecated] `chatlab search` \u2014 use `chatlab messages search <keyword> --session <id>`; alias kept for one major version"
+    );
+    const { dbManager } = initRuntime();
+    const db = dbManager.open(sessionId);
+    if (!db) {
+      console.error(`Session ${sessionId} not found`);
+      process.exit(1);
+    }
+    const limit = parseInt(options.limit);
+    const result = searchMessagesLike(db, keyword, { limit });
+    if (options.format === "json") {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(
+        `Search "${keyword}" - ${result.total} result(s)${result.hasMore ? " (showing first " + limit + ")" : ""}:
+`
+      );
+      for (const msg of result.messages) {
+        const time = new Date(msg.timestamp * 1e3).toLocaleString();
+        console.log(`  [${time}] ${msg.senderName}: ${msg.content}`);
+      }
+    }
+    dbManager.closeAll();
+  });
+  program2.command("query <session-id>", { hidden: true }).description("Deprecated: use `chatlab sql`").requiredOption("--sql <sql>", "SQL query statement").option("--format <format>", "Output format (table|json)", "table").action((sessionId, options) => {
+    console.error(
+      '[Deprecated] `chatlab query` \u2014 use `chatlab sql "<SELECT ...>" --session <id>`; alias kept for one major version'
+    );
+    const { config, dbManager } = initRuntime();
+    const db = dbManager.open(sessionId);
+    if (!db) {
+      console.error(`Session ${sessionId} not found`);
+      process.exit(1);
+    }
+    try {
+      assertLegacySqlAllowed(config, options.sql);
+      const result = executeReadonlySql(db, options.sql);
+      assertSqlResultPrivacyAllowed(result.columns, false);
+      if (options.format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        if (result.rows.length === 0) {
+          console.log("No results.");
+        } else {
+          printTable(result.columns, result.rows);
+          console.log(`
+${result.rowCount} row(s)${result.truncated ? " (truncated)" : ""}`);
+        }
+      }
+    } catch (err) {
+      if (err instanceof QueryError) {
+        console.error(`${err.code}: ${err.message}`);
+        if (err.hint) console.error(`Hint: ${err.hint}`);
+        process.exit(2);
+      }
+      console.error(`SQL error: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+    dbManager.closeAll();
+  });
+}
+function printTable(columns, rows) {
+  const widths = columns.map((col) => {
+    const maxData = rows.reduce((max, row) => {
+      const val = String(row[col] ?? "");
+      return Math.max(max, val.length);
+    }, 0);
+    return Math.max(col.length, Math.min(maxData, 40));
+  });
+  const header = columns.map((col, i) => col.padEnd(widths[i])).join(" | ");
+  const separator = widths.map((w) => "-".repeat(w)).join("-+-");
+  console.log(header);
+  console.log(separator);
+  for (const row of rows) {
+    const line = columns.map((col, i) => {
+      const val = String(row[col] ?? "");
+      return val.length > 40 ? val.slice(0, 37) + "..." : val.padEnd(widths[i]);
+    }).join(" | ");
+    console.log(line);
+  }
+}
+
+// src/query/manifest.ts
+var QUERY_GROUPS = /* @__PURE__ */ new Set(["sessions", "members", "messages", "stats", "topics", "sql", "schema", "manifest"]);
+var EXIT_CODES = {
+  "0": "success",
+  "1": "internal error",
+  "2": "invalid argument, invalid cursor, or disabled capability",
+  "3": "resource not found (session/member/message/segment)",
+  "4": "ambiguous reference (see error.candidates)",
+  "5": "SQL error"
+};
+var EXAMPLES = [
+  { task: "What did this group talk about today?", command: "chatlab messages list --since today --format agent" },
+  {
+    task: "Search a topic within a time range",
+    command: "chatlab messages search \u65C5\u6E38 --since 2026-01-01 --limit 20 --format agent"
+  },
+  {
+    task: "Who mentioned it first (message ids)?",
+    command: "chatlab messages search \u62A5\u9500 --sort asc --limit 5 --format agent"
+  },
+  {
+    task: "Follow up a single [#id] marker with context",
+    command: "chatlab messages context --id 1021 --window 10 --format agent"
+  },
+  {
+    task: "Conversation between me and a member last month",
+    command: "chatlab messages between --member me --member \u5C0F\u7EA2 --last 30d --format agent"
+  },
+  { task: "Most active members", command: "chatlab stats activity --top 10 --format json" },
+  { task: "Monthly hot topics", command: "chatlab topics list --since 2026-06-01 --until 2026-06-30 --format agent" },
+  { task: "High-frequency words", command: "chatlab stats keywords --last 30d --top 20 --format json" },
+  {
+    task: "Structural scouting without content",
+    command: "chatlab messages list --last 7d --no-content --fields id,senderName,time --format json"
+  },
+  { task: "Discover sessions first", command: "chatlab sessions list --format json" }
+];
+var NOTES = [
+  "Always pass --format explicitly: agent for message bodies, json for structural data.",
+  "stdout carries exactly one JSON envelope in agent/json mode; logs go to stderr.",
+  "Success envelope: { ok, command, data, meta }; failure: { ok: false, command, error }.",
+  "Pagination: follow meta.nextCursor with --cursor; cursors are bound to the exact query.",
+  "Single-message [#id] and [#id*] markers are usable with `messages context --id`; merged [#a-b] ranges are display-only.",
+  "Privacy preprocessing (desensitize/blacklist) is always on by default."
+];
+function isHidden(cmd) {
+  return cmd._hidden === true;
+}
+function serializeCommand(cmd, prefix) {
+  const args = (cmd.registeredArguments ?? []).map((arg) => ({
+    name: arg.name(),
+    required: arg.required,
+    variadic: arg.variadic,
+    ...arg.description ? { description: arg.description } : {}
+  }));
+  const options = cmd.options.filter((opt) => !opt.hidden).map((opt) => ({
+    flags: opt.flags,
+    description: opt.description,
+    ...opt.defaultValue !== void 0 ? { default: opt.defaultValue } : {}
+  }));
+  return {
+    name: prefix ? `${prefix} ${cmd.name()}` : cmd.name(),
+    description: cmd.description(),
+    args,
+    options
+  };
+}
+function collectQueryCommands(cmd, prefix, into) {
+  if (cmd.commands.length === 0) {
+    into.push(serializeCommand(cmd, prefix));
+    return;
+  }
+  const path2 = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
+  for (const sub of cmd.commands) {
+    if (isHidden(sub)) continue;
+    collectQueryCommands(sub, path2, into);
+  }
+}
+function buildManifest(program2, version) {
+  const commands = [];
+  const appCommands = [];
+  for (const cmd of program2.commands) {
+    if (isHidden(cmd)) continue;
+    if (QUERY_GROUPS.has(cmd.name())) {
+      collectQueryCommands(cmd, "", commands);
+    } else {
+      appCommands.push({ name: cmd.name(), description: cmd.description() });
+    }
+  }
+  return {
+    name: "chatlab",
+    version,
+    apiVersion: API_VERSION,
+    formats: ["agent", "json", "text"],
+    commands,
+    appCommands,
+    exitCodes: EXIT_CODES,
+    examples: EXAMPLES,
+    notes: NOTES
+  };
+}
+function registerManifestCommand(program2, version) {
+  program2.command("manifest").description("Machine-readable command manifest for AI agents (JSON)").action(() => {
+    console.log(JSON.stringify(buildManifest(program2, version), null, 2));
+  });
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("chatlab").description("ChatLab - Chat history analysis tool").version(getVersion(), "-v, --version");
+program.hook("preAction", async (_thisCommand, actionCommand) => {
+  if (actionCommand.name() === "update") return;
+  const { checkForUpdatesInteractive } = await import("./update-checker-LGMTEKMT.mjs");
+  await checkForUpdatesInteractive();
+});
+program.command("update").description("Update ChatLab CLI to the latest version").action(async () => {
+  const { performCliSelfUpdate } = await import("./update-checker-LGMTEKMT.mjs");
+  const result = await performCliSelfUpdate({
+    write: (text) => process.stderr.write(text)
+  });
+  if (result.success) {
+    console.error("  Updated successfully. Please restart chatlab to use the new version.\n");
+    return;
+  }
+  console.error(`  Update failed: ${result.error || "unknown error"}
+`);
+  process.exitCode = 1;
+});
+registerQueryCommands(program);
+registerManifestCommand(program, getVersion());
+program.command("import <file>").description("Import a chat history file (14+ formats: QQ/WeChat/Telegram/WhatsApp/LINE/Discord/Instagram, etc.)").option("--session-id <id>", "Specify session ID (auto-generated if omitted)").option("--format <id>", "Specify format ID (skip auto-detection)").action(async (file, options) => {
+  if (!fs2.existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(1);
+  }
+  const { streamImport, detectFormat } = await import("./import-WWCSXGVS.mjs");
+  const { dbManager, pathProvider } = initRuntime();
+  const nativeBinding = resolveNativeBinding();
+  logNativeParserStatus();
+  const format = detectFormat(file);
+  if (!format && !options.format) {
+    console.error(`Unrecognized file format: ${file}`);
+    console.error('Use --format <id> to specify manually, or run "chatlab formats" to see supported formats');
+    process.exit(1);
+  }
+  console.log(`Importing: ${file}`);
+  if (format) console.log(`  Format: ${format.name} (${format.platform})`);
+  try {
+    const result = await streamImport(dbManager, file, {
+      formatId: options.format,
+      nativeBinding,
+      onProgress: (p) => {
+        process.stdout.write(`\r  ${p.stage}: ${p.progress}%`);
+      }
+    });
+    if (result.success) {
+      console.log(`
+
+Import succeeded!`);
+      console.log(`  Session ID: ${result.sessionId}`);
+      console.log(`  Messages written: ${result.diagnostics?.messagesWritten ?? 0}`);
+      console.log(`  Messages skipped: ${result.diagnostics?.messagesSkipped ?? 0}`);
+      if (result.sessionId) {
+        try {
+          const { PreferencesManager: PreferencesManager2, createDatabaseManagerAdapter, ownerProfileService } = await import("./src-MPNBTFOE.mjs");
+          const applied = ownerProfileService.tryApplyOwnerProfile(
+            createDatabaseManagerAdapter(dbManager),
+            new PreferencesManager2(pathProvider.getSystemDir()),
+            result.sessionId
+          );
+          if (applied.applied) {
+            console.log(`  Owner auto-detected: ${applied.ownerId}`);
+          }
+        } catch (ownerErr) {
+          console.warn(`  Owner profile apply skipped: ${ownerErr instanceof Error ? ownerErr.message : ownerErr}`);
+        }
+      }
+    } else {
+      console.error(`
+
+Import failed: ${result.error}`);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`
+
+Import error: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  } finally {
+    dbManager.closeAll();
+  }
+});
+program.command("formats").description("List all supported chat history formats").action(async () => {
+  const { getSupportedFormats } = await import("./import-WWCSXGVS.mjs");
+  const formats = getSupportedFormats();
+  console.log(`${formats.length} supported format(s):
+`);
+  for (const f of formats) {
+    console.log(`  ${f.id.padEnd(30)} ${f.name} (${f.platform}) [${f.extensions.join(", ")}]`);
+  }
+});
+program.command("mcp").description("Start MCP Server (stdio transport, for ClaudeCode / Cursor / AI agents)").action(async () => {
+  const { startCliMcpServer } = await import("./mcp-A4M3LT5O.mjs");
+  await startCliMcpServer();
+});
+program.command("chat").description("Ask ChatLab AI about an imported chat session").option("--session-id <id>", "Source chat session ID").option("--ai-chat-id <id>", "Existing AI chat ID to continue").option("-q, --question <text>", "Question to ask").option("--json", "Output structured JSON").option("--include-events", "Include all agent stream chunks in JSON output").option("--no-stream", "Disable streaming output").option("--locale <locale>", "AI response locale", "zh-CN").action(async (options) => {
+  const { runChatCommand } = await import("./chat-command-VBDMWOKL.mjs");
+  const { dbManager, pathProvider } = initRuntime();
+  const aiChatManager = new AIChatManager(pathProvider.getAiDataDir(), { nativeBinding: resolveNativeBinding() });
+  try {
+    await runChatCommand(
+      {
+        sessionId: options.sessionId,
+        aiChatId: options.aiChatId,
+        question: options.question,
+        json: !!options.json,
+        stream: options.stream,
+        locale: options.locale,
+        includeEvents: !!options.includeEvents
+      },
+      { dbManager, pathProvider, aiChatManager }
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  } finally {
+    aiChatManager.close();
+    dbManager.closeAll();
+  }
+});
+program.command("start").description("Start ChatLab (HTTP API + Web UI)").option("--port <port>", "Server port", String(DEFAULT_API_PORT)).option("--host <host>", "Listen address", "127.0.0.1").option("--token <token>", "Custom Bearer Token (reads from config or auto-generates if omitted)").option("--headless", "API-only mode, do not serve the Web UI").option("--require-auth", "Require Bearer token for all routes including /_web/*").option("--no-open", "Do not auto-open the browser").option("--daemon", "Run as a resident system service (auto-start on login, macOS/Linux)").action(async (options) => {
+  if (options.daemon) {
+    const { serviceInstall } = await import("./service-KGL3RAIA.mjs");
+    serviceInstall({
+      port: parseInt(options.port, 10),
+      host: options.host,
+      token: options.token || void 0,
+      headless: options.headless,
+      requireAuth: options.requireAuth || void 0
+    });
+    return;
+  }
+  const { startHttpServer } = await import("./http-L4AMELPZ.mjs");
+  const port = parseInt(options.port, 10);
+  let webRoot;
+  if (!options.headless) {
+    const webDir = resolveCliPath("dist-web");
+    if (fs2.existsSync(webDir)) {
+      webRoot = webDir;
+    } else {
+      console.warn("Warning: dist-web/ not found, starting in API-only mode");
+    }
+  }
+  try {
+    if (!await isPortAvailable(port, options.host)) {
+      console.error(formatPortInUseError(port));
+      process.exit(1);
+    }
+    const info = await startHttpServer({
+      port,
+      host: options.host,
+      token: options.token || void 0,
+      webRoot,
+      requireAuth: options.requireAuth || void 0
+    });
+    const { startPeriodicUpdateCheck } = await import("./update-checker-LGMTEKMT.mjs");
+    startPeriodicUpdateCheck();
+    const displayHost = info.host === "0.0.0.0" ? "127.0.0.1" : info.host;
+    const url = `http://${displayHost}:${info.port}`;
+    console.log(`
+ChatLab v${getVersion()}`);
+    if (webRoot) console.log(`  Web UI: ${url}/`);
+    console.log(`  API:    ${url}`);
+    console.log(`  Token:  ${info.token}`);
+    console.log(`
+Example:`);
+    console.log(`  curl -H "Authorization: Bearer ${info.token}" ${url}/api/v1/status`);
+    if (webRoot && options.open) {
+      openBrowser(url);
+      console.log(`
+Browser opened. Press Ctrl+C to stop.
+`);
+    } else {
+      console.log(`
+Press Ctrl+C to stop.
+`);
+    }
+    const shutdown = async () => {
+      console.log("\nShutting down...");
+      const { stopHttpServer } = await import("./http-L4AMELPZ.mjs");
+      await stopHttpServer();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("EADDRINUSE")) {
+      console.error(formatPortInUseError(port));
+    } else {
+      console.error(`Startup failed: ${message}`);
+    }
+    process.exit(1);
+  }
+});
+var configCmd = program.command("config").description("Configuration management");
+configCmd.command("path").description("Show config file path").action(() => {
+  console.log(getConfigPath());
+});
+configCmd.command("show").description("Show current configuration").action(() => {
+  const config = loadConfig();
+  console.log(JSON.stringify(config, null, 2));
+});
+configCmd.command("set <key> <value>").description("Set a config field, e.g. `chatlab config set cli.allow_raw true`").action((key, value) => {
+  try {
+    const result = setConfigField(key, value);
+    console.log(`${result.section}.${result.key} = ${JSON.stringify(result.value)}`);
+  } catch (err) {
+    if (err instanceof ConfigSetError) {
+      console.error(`Error: ${err.message}`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+});
+program.command("stop").description("Stop the resident service and remove auto-start (reverse of start --daemon)").action(async () => {
+  const { serviceUninstall } = await import("./service-KGL3RAIA.mjs");
+  serviceUninstall();
+});
+program.command("status").description("Show resident service status").action(async () => {
+  const { getServiceStatus } = await import("./service-KGL3RAIA.mjs");
+  const svc = getServiceStatus();
+  console.log("\nChatLab Status");
+  console.log("\u2500".repeat(36));
+  console.log(`  Logs:       ${getSystemLogsDir()}`);
+  if (svc.installed) {
+    const portStr = svc.port ? `http://${svc.host ?? "127.0.0.1"}:${svc.port}` : "";
+    console.log(`  Service:    ${svc.running ? "running" : "installed (not running)"}`);
+    if (portStr) console.log(`  Address:    ${portStr}`);
+    console.log(`  Auto-start: enabled`);
+    console.log(`
+  Use \`chatlab stop\` to remove the service.
+`);
+  } else {
+    console.log(`  Service:    not installed`);
+    console.log(`  Auto-start: disabled`);
+    console.log(`
+  Use \`chatlab start --daemon\` to install as a system service.
+`);
+  }
+});
+function openBrowser(url) {
+  try {
+    const cmd = process.platform === "darwin" ? `open "${url}"` : process.platform === "win32" ? `start "" "${url}"` : `xdg-open "${url}"`;
+    execSync(cmd, { stdio: "ignore" });
+  } catch {
+    console.log(`  Open manually: ${url}`);
+  }
+}
+function run(argv) {
+  initAppLogger(getSystemLogsDir());
+  process.on("uncaughtException", (error) => {
+    console.error("Uncaught Exception:", error);
+    appLogger.error("crash", "uncaughtException", error);
+    process.exit(1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    console.error("Unhandled Rejection:", reason);
+    appLogger.error("crash", "unhandledRejection", reason);
+    process.exit(1);
+  });
+  program.parse(argv);
+}
+var isDirectRun = process.argv[1]?.endsWith("cli.ts") || process.argv[1]?.endsWith("cli.js");
+if (isDirectRun) {
+  run();
+}
+
+export {
+  run
+};
+//# sourceMappingURL=chunk-M2PXDX4G.mjs.map