parallelclaw 1.0.0

package/lib/telegram-discovery.js

@@ -0,0 +1,373 @@
+/**
+ * Telegram-Desktop discovery & preview.
+ *
+ * Three responsibilities:
+ *   1. detectTelegramDesktop()   — is the app installed, where, what kind
+ *   2. detectFirstLogin()        — when did the user log in (anti-abuse 24h window)
+ *   3. discoverExports(dirs)     — scan likely Downloads paths for ChatExport_*
+ *   4. previewExport(path)       — extract chat name, msg count, date range
+ *      without doing a full ingest. Used by `memex telegram pending`.
+ *
+ * Everything here is fast and read-only — safe to call from CLI, MCP, or daemon.
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { detectTelegramHtml, parseTelegramHtmlExport } from './parse-telegram-html.js';
+
+// ------------------------- Desktop detection -------------------------
+
+/**
+ * Detect Telegram Desktop installation.
+ *
+ * Returns {
+ *   installed: bool,
+ *   path: string|null,           // absolute path to .app / executable / install dir
+ *   variant: 'direct'|'app_store'|'snap'|'apt'|'exe'|null,
+ *   platform: 'darwin'|'linux'|'win32'|'other',
+ *   notes: string[]              // user-facing hints, e.g. App Store sandbox warning
+ * }
+ *
+ * On macOS we check /Applications/Telegram.app and /Applications/Telegram Desktop.app.
+ * The Mac App Store version is sandboxed and can have issues with the export
+ * folder — we flag that.
+ */
+export function detectTelegramDesktop() {
+  const plat = platform();
+  const out = { installed: false, path: null, variant: null, platform: plat, notes: [] };
+
+  if (plat === 'darwin') {
+    const candidates = [
+      '/Applications/Telegram.app',
+      '/Applications/Telegram Desktop.app',
+      join(homedir(), 'Applications/Telegram.app'),
+    ];
+    for (const c of candidates) {
+      if (existsSync(c)) {
+        out.installed = true;
+        out.path = c;
+        // Try to tell App Store apart from direct download by bundle receipt path
+        const receiptPath = join(c, 'Contents/_MASReceipt/receipt');
+        out.variant = existsSync(receiptPath) ? 'app_store' : 'direct';
+        if (out.variant === 'app_store') {
+          out.notes.push(
+            "App Store Telegram has sandboxed file access. Chat exports usually work but may go to a Containers/ path instead of ~/Downloads/Telegram Desktop/. If memex can't see your exports, install the direct version from telegram.org/dl/macos."
+          );
+        }
+        break;
+      }
+    }
+  } else if (plat === 'linux') {
+    // Common Linux install paths
+    const candidates = [
+      '/usr/bin/telegram-desktop',
+      '/usr/local/bin/telegram-desktop',
+      '/snap/bin/telegram-desktop',
+      join(homedir(), '.local/share/TelegramDesktop'),
+      '/var/lib/flatpak/exports/bin/org.telegram.desktop',
+    ];
+    for (const c of candidates) {
+      if (existsSync(c)) {
+        out.installed = true;
+        out.path = c;
+        out.variant = c.includes('/snap/') ? 'snap' : c.includes('flatpak') ? 'flatpak' : 'apt';
+        break;
+      }
+    }
+  } else if (plat === 'win32') {
+    const candidates = [
+      join(homedir(), 'AppData/Roaming/Telegram Desktop/Telegram.exe'),
+      'C:/Program Files/Telegram Desktop/Telegram.exe',
+    ];
+    for (const c of candidates) {
+      if (existsSync(c)) {
+        out.installed = true;
+        out.path = c;
+        out.variant = 'exe';
+        break;
+      }
+    }
+  }
+
+  return out;
+}
+
+// ------------------------- Login age (24h delay) -------------------------
+
+/**
+ * Detect when the user logged in to Telegram Desktop, by looking at the
+ * tdata directory mtime. Telegram refuses to export chats for the first
+ * ~24 hours after a fresh login (anti-abuse window).
+ *
+ * Returns {
+ *   logged_in: bool,
+ *   first_login_at: ISO string | null,
+ *   hours_since_login: number | null,
+ *   export_allowed: bool          // true iff > 24h elapsed
+ * }
+ */
+export function detectFirstLogin() {
+  const out = { logged_in: false, first_login_at: null, hours_since_login: null, export_allowed: false };
+  const plat = platform();
+  let tdataDir = null;
+
+  if (plat === 'darwin') {
+    tdataDir = join(homedir(), 'Library/Application Support/Telegram Desktop/tdata');
+  } else if (plat === 'linux') {
+    tdataDir = join(homedir(), '.local/share/TelegramDesktop/tdata');
+  } else if (plat === 'win32') {
+    tdataDir = join(homedir(), 'AppData/Roaming/Telegram Desktop/tdata');
+  }
+
+  if (!tdataDir || !existsSync(tdataDir)) return out;
+
+  try {
+    // Look for 'key_datas' or 'shortcuts-default.json' or just the dir itself.
+    // The dir creation time on Telegram-init is our login proxy.
+    const candidates = ['key_datas', 'shortcuts-default.json', ''];
+    let oldestMs = null;
+    for (const c of candidates) {
+      const p = c ? join(tdataDir, c) : tdataDir;
+      if (existsSync(p)) {
+        const s = statSync(p);
+        // Prefer birthtime if it's sensible; otherwise mtime
+        const t = s.birthtimeMs && s.birthtimeMs > 0 ? s.birthtimeMs : s.mtimeMs;
+        if (oldestMs === null || t < oldestMs) oldestMs = t;
+      }
+    }
+    if (oldestMs !== null) {
+      const ageMs = Date.now() - oldestMs;
+      out.logged_in = true;
+      out.first_login_at = new Date(oldestMs).toISOString();
+      out.hours_since_login = Math.floor(ageMs / 3600000);
+      out.export_allowed = ageMs > 24 * 3600000;
+    }
+  } catch (_) {
+    /* swallow */
+  }
+
+  return out;
+}
+
+// ------------------------- Export discovery -------------------------
+
+/**
+ * Default paths to scan for ChatExport_* folders / result.json files.
+ * Returns absolute paths that exist on disk (caller filters).
+ */
+export function defaultDownloadsPaths() {
+  const paths = [];
+  if (platform() === 'darwin') {
+    paths.push(join(homedir(), 'Downloads/Telegram Desktop'));
+    paths.push(join(homedir(), 'Downloads'));
+    paths.push(join(homedir(), 'Desktop'));
+  } else if (platform() === 'linux') {
+    paths.push(join(homedir(), 'Downloads/Telegram Desktop'));
+    paths.push(join(homedir(), 'Downloads'));
+  } else if (platform() === 'win32') {
+    paths.push(join(homedir(), 'Downloads/Telegram Desktop'));
+    paths.push(join(homedir(), 'Downloads'));
+  }
+  return paths.filter((p) => existsSync(p));
+}
+
+/**
+ * Walk the given directories looking for Telegram chat exports.
+ * A "candidate" is either a `ChatExport_*` directory (HTML or JSON export)
+ * or a bare `result.json` file (legacy single-file JSON dump).
+ *
+ * Returns an array of { path, kind: 'html-dir'|'json-file', modified_ts, size_bytes }.
+ * The caller decides whether to preview each, import, or skip.
+ */
+export function discoverExports(rootDirs) {
+  const out = [];
+  for (const root of rootDirs) {
+    if (!existsSync(root)) continue;
+    let entries = [];
+    try { entries = readdirSync(root); } catch (_) { continue; }
+    for (const name of entries) {
+      const full = join(root, name);
+      let s;
+      try { s = statSync(full); } catch (_) { continue; }
+      if (s.isDirectory()) {
+        // ChatExport_2026-05-15 style
+        if (name.startsWith('ChatExport_') || name.toLowerCase().startsWith('chatexport_')) {
+          const det = detectTelegramHtml(full);
+          if (det.type === 'dir') {
+            out.push({ path: full, kind: 'html-dir', modified_ts: Math.floor(s.mtimeMs / 1000), size_bytes: dirSizeShallow(full) });
+            continue;
+          }
+          // Maybe it's a JSON export inside the same folder name
+          const resultJson = join(full, 'result.json');
+          if (existsSync(resultJson)) {
+            out.push({ path: resultJson, kind: 'json-file', modified_ts: Math.floor(statSync(resultJson).mtimeMs / 1000), size_bytes: statSync(resultJson).size });
+          }
+        }
+      } else if (s.isFile() && name === 'result.json') {
+        // Bare result.json at the root of one of the scanned dirs
+        out.push({ path: full, kind: 'json-file', modified_ts: Math.floor(s.mtimeMs / 1000), size_bytes: s.size });
+      }
+    }
+  }
+  // Newest first
+  out.sort((a, b) => b.modified_ts - a.modified_ts);
+  return out;
+}
+
+function dirSizeShallow(dir) {
+  let total = 0;
+  try {
+    for (const name of readdirSync(dir)) {
+      try {
+        const s = statSync(join(dir, name));
+        if (s.isFile()) total += s.size;
+      } catch (_) { /* skip */ }
+    }
+  } catch (_) { /* skip */ }
+  return total;
+}
+
+// ------------------------- Preview -------------------------
+
+/**
+ * Read enough of an export to produce a UI-facing preview, WITHOUT a full
+ * ingest. Returns:
+ *   {
+ *     path,
+ *     kind: 'html-dir'|'json-file',
+ *     chat_title: string,
+ *     chat_type: 'personal_chat'|'private_group'|null,
+ *     message_count: number,
+ *     date_first: ISO string | null,
+ *     date_last: ISO string | null,
+ *     senders_sample: string[],   // up to 6 distinct senders
+ *     size_bytes: number
+ *   }
+ *
+ * The preview is fast — for HTML we run the same parser but cap at the first
+ * `messages.html` file; for JSON we do a streaming-ish read of the first chat
+ * in the list and tally.
+ */
+export function previewExport(path) {
+  const out = {
+    path,
+    kind: null,
+    chat_title: null,
+    chat_type: null,
+    message_count: 0,
+    date_first: null,
+    date_last: null,
+    senders_sample: [],
+    size_bytes: 0,
+  };
+
+  if (!existsSync(path)) return out;
+  const s = statSync(path);
+  out.size_bytes = s.isDirectory() ? dirSizeShallow(path) : s.size;
+
+  if (s.isDirectory()) {
+    // Telegram Desktop directories can contain EITHER messages.html (HTML
+    // export) OR a top-level *.json (JSON export — usually `result.json`
+    // but custom names like `kimi.json` also occur when user renamed).
+    // Try HTML first; fall back to the first JSON file we find inside.
+    out.kind = 'html-dir';
+    let parsedOk = false;
+    try {
+      const parsed = parseTelegramHtmlExport(path);
+      if (parsed && parsed.chats.list[0] && parsed.chats.list[0].messages.length > 0) {
+        const chat = parsed.chats.list[0];
+        out.chat_title = chat.name;
+        out.chat_type = chat.type;
+        out.message_count = chat.messages.length;
+        out.date_first = chat.messages[0].date || null;
+        out.date_last = chat.messages[chat.messages.length - 1].date || null;
+        const seen = new Set();
+        for (const m of chat.messages) {
+          if (m.from && m.from !== 'Unknown' && !seen.has(m.from)) {
+            seen.add(m.from);
+            out.senders_sample.push(m.from);
+            if (out.senders_sample.length >= 6) break;
+          }
+        }
+        parsedOk = true;
+      }
+    } catch (_) { /* swallow — try JSON next */ }
+
+    // JSON fallback — look for any *.json directly in the dir
+    if (!parsedOk) {
+      try {
+        const entries = readdirSync(path);
+        // Prefer result.json; otherwise first *.json
+        const jsonName = entries.find((n) => n === 'result.json')
+          || entries.find((n) => n.endsWith('.json'));
+        if (jsonName) {
+          const jsonPath = join(path, jsonName);
+          out.kind = 'json-in-dir';
+          out.inner_json_path = jsonPath;
+          const data = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+          let chat = null;
+          if (data && data.chats && Array.isArray(data.chats.list) && data.chats.list[0]) {
+            chat = data.chats.list[0];
+          } else if (data && Array.isArray(data.messages)) {
+            chat = data;
+          }
+          if (chat) {
+            out.chat_title = chat.name || 'Telegram chat';
+            out.chat_type = chat.type || null;
+            const msgs = Array.isArray(chat.messages) ? chat.messages : [];
+            out.message_count = msgs.length;
+            if (msgs.length > 0) {
+              out.date_first = msgs[0].date || null;
+              out.date_last = msgs[msgs.length - 1].date || null;
+            }
+            const seen = new Set();
+            for (const m of msgs) {
+              const from = m.from || m.actor;
+              if (from && !seen.has(from)) {
+                seen.add(from);
+                out.senders_sample.push(from);
+                if (out.senders_sample.length >= 6) break;
+              }
+            }
+          }
+        }
+      } catch (_) { /* swallow */ }
+    }
+  } else if (s.isFile() && path.endsWith('.json')) {
+    out.kind = 'json-file';
+    try {
+      // Streaming-ish: just JSON.parse the whole file; result.json size is typically
+      // a few MB, fine for preview. Telegram puts the chat list as the first key.
+      const text = readFileSync(path, 'utf-8');
+      const data = JSON.parse(text);
+      // result.json has two shapes: { chats: { list: [...] }, ... } or { name, type, messages: [...] }
+      let chat = null;
+      if (data && data.chats && Array.isArray(data.chats.list) && data.chats.list[0]) {
+        chat = data.chats.list[0];
+      } else if (data && Array.isArray(data.messages)) {
+        chat = data;
+      }
+      if (chat) {
+        out.chat_title = chat.name || 'Telegram chat';
+        out.chat_type = chat.type || null;
+        const msgs = Array.isArray(chat.messages) ? chat.messages : [];
+        out.message_count = msgs.length;
+        if (msgs.length > 0) {
+          out.date_first = msgs[0].date || null;
+          out.date_last = msgs[msgs.length - 1].date || null;
+        }
+        const seen = new Set();
+        for (const m of msgs) {
+          const from = m.from || m.actor;
+          if (from && !seen.has(from)) {
+            seen.add(from);
+            out.senders_sample.push(from);
+            if (out.senders_sample.length >= 6) break;
+          }
+        }
+      }
+    } catch (_) { /* swallow */ }
+  }
+  return out;
+}

package/lib/telegram-notify.js

@@ -0,0 +1,272 @@
+/**
+ * Cross-channel notification + dedup state for the Telegram capture flow.
+ *
+ * State file: ~/.memex/.tg-tip-state.json — small JSON the daemon and CLI
+ * both read/write to coordinate WHEN a message was last shown to the user.
+ *
+ *   {
+ *     version: 1,
+ *     cli_tip_last_shown_at: ISO-8601,           // throttle CLI tips to once/6h
+ *     notif_shown_for_ids: ["sha256(path)", …],  // skip macOS notif we already fired
+ *     notifications: { enabled: false, show_titles: false }
+ *   }
+ *
+ * Public surface:
+ *   • loadNotifyState()                          → state object (fresh on every call)
+ *   • saveNotifyState(state)                     → atomic write
+ *   • cliTipDue(state, cooldownHours=6)          → bool — should CLI tip render?
+ *   • markCliTipShown(state)                     → record now() in state
+ *   • notifShownFor(state, path)                 → bool — already sent macOS notif?
+ *   • markNotifShown(state, paths[])             → record ids
+ *   • fireMacosNotification(title, body)         → osascript shell-out (best-effort)
+ *   • setNotificationsEnabled(state, enabled, showTitles?)
+ *   • formatTelegramTip(entries, opts)           → markdown string (channel B)
+ *
+ * All of this is platform-tolerant — on Linux/Windows we don't fire native
+ * notifications (osascript is macOS-only). The CLI tip + agent injection
+ * still work everywhere.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  mkdirSync,
+  statSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { spawn } from 'node:child_process';
+
+const HOME = homedir();
+export const STATE_PATH = join(HOME, '.memex', '.tg-tip-state.json');
+
+const DEFAULT_STATE = () => ({
+  version: 1,
+  cli_tip_last_shown_at: null,
+  notif_shown_for_ids: [],
+  // v0.10.10: dashboard discovery throttle. Three-strike pattern so the tip
+  // appears on a few different terminal sessions in the first days after
+  // install, then quiets down. Becomes permanently silent once the user
+  // actually opens the dashboard at least once.
+  dashboard_tip_shown_count: 0,
+  dashboard_tip_last_shown_at: null,
+  dashboard_ever_opened: false,
+  notifications: {
+    enabled: false,    // privacy-first: opt-in for macOS notification
+    show_titles: false, // even when on, don't leak chat names by default
+    // v0.10.4+: which app to open when the user clicks the banner.
+    //   'auto'           → priority: claude-cli > claude-desktop > terminal
+    //   'claude-cli'     → force open Claude Code CLI in a new Terminal tab
+    //   'claude-desktop' → force open Claude Desktop GUI
+    //   'terminal'       → force open Terminal with `memex telegram pending`
+    //   'none'           → banner not clickable
+    // If terminal-notifier is not installed, click is impossible — banner
+    // text falls back to "Run: memex telegram pending".
+    click_target: 'auto',
+  },
+});
+
+export const VALID_CLICK_TARGETS = ['auto', 'claude-cli', 'claude-desktop', 'terminal', 'none'];
+
+export function loadNotifyState(path = STATE_PATH) {
+  if (!existsSync(path)) return DEFAULT_STATE();
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return {
+      ...DEFAULT_STATE(),
+      ...parsed,
+      notifications: { ...DEFAULT_STATE().notifications, ...(parsed.notifications || {}) },
+      notif_shown_for_ids: Array.isArray(parsed.notif_shown_for_ids)
+        ? parsed.notif_shown_for_ids
+        : [],
+    };
+  } catch (_) {
+    return DEFAULT_STATE();
+  }
+}
+
+export function saveNotifyState(state, path = STATE_PATH) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = path + '.tmp';
+  writeFileSync(tmp, JSON.stringify(state, null, 2));
+  renameSync(tmp, path);
+}
+
+// ---------------------- CLI tip throttle ----------------------
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+export function cliTipDue(state, cooldownHours = 6) {
+  if (!state.cli_tip_last_shown_at) return true;
+  const last = Date.parse(state.cli_tip_last_shown_at);
+  if (isNaN(last)) return true;
+  return Date.now() - last >= cooldownHours * ONE_HOUR_MS;
+}
+
+export function markCliTipShown(state, now = new Date()) {
+  state.cli_tip_last_shown_at = now.toISOString();
+  return state;
+}
+
+// ---------------------- Dashboard discovery tip (v0.10.10) ----------------------
+
+/**
+ * Whether the "try memex web" tip should fire on the next CLI command.
+ *
+ *   - Hard-stop once the user has actually run `memex web` (any duration)
+ *   - Cap at maxShows (default 3) total reveals
+ *   - Cooldown cooldownHours (default 12) between reveals so it doesn't
+ *     stack with the TG-pending tip on the same minute
+ */
+export function dashboardTipDue(state, opts = {}) {
+  const { maxShows = 3, cooldownHours = 12 } = opts;
+  if (state.dashboard_ever_opened) return false;
+  if ((state.dashboard_tip_shown_count || 0) >= maxShows) return false;
+  if (!state.dashboard_tip_last_shown_at) return true;
+  const last = Date.parse(state.dashboard_tip_last_shown_at);
+  if (isNaN(last)) return true;
+  return Date.now() - last >= cooldownHours * ONE_HOUR_MS;
+}
+
+export function markDashboardTipShown(state, now = new Date()) {
+  state.dashboard_tip_shown_count = (state.dashboard_tip_shown_count || 0) + 1;
+  state.dashboard_tip_last_shown_at = now.toISOString();
+  return state;
+}
+
+/**
+ * Permanently silence the dashboard tip — call this the first time the user
+ * actually runs `memex web`. They've discovered it; no need to keep nagging.
+ */
+export function markDashboardEverOpened(state) {
+  state.dashboard_ever_opened = true;
+  return state;
+}
+
+/**
+ * The tip text itself. Plain string (no ANSI) — the caller decides whether
+ * to dim it. Returns null if there is genuinely nothing to say (defensive).
+ */
+export function formatDashboardTip() {
+  return '💡 New: try `memex web --open` — browse your memory in a browser (read-only, localhost only).';
+}
+
+// ---------------------- Notification dedup ----------------------
+
+/**
+ * Stable hash of a pending export for notification dedup.
+ *
+ * v0.10.5+: hash now incorporates the file's mtime in addition to path.
+ *
+ * Why: Telegram Desktop reuses the same folder name on same-day re-exports
+ * (e.g. ChatExport_2026-05-16). After memex imports & removes that folder
+ * from pending, a fresh export with the same date creates the same path
+ * again. Path-only hash collided → notification was incorrectly deduped
+ * as "already shown".
+ *
+ * Including mtime makes the hash content-aware: same path + different
+ * mtime → fresh hash → notification fires. If the path doesn't exist
+ * (file was deleted), we fall back to path-only — it's an edge case
+ * (notifShownFor check before fire, file should exist).
+ */
+export function notifIdFor(path) {
+  let mtimeKey = '';
+  try { mtimeKey = String(Math.floor(statSync(path).mtimeMs)); } catch (_) { /* path missing — fall back to path-only */ }
+  return createHash('sha256').update(String(path) + ':' + mtimeKey).digest('hex').slice(0, 16);
+}
+
+export function notifShownFor(state, path) {
+  return state.notif_shown_for_ids.includes(notifIdFor(path));
+}
+
+export function markNotifShown(state, paths) {
+  const ids = (Array.isArray(paths) ? paths : [paths]).map(notifIdFor);
+  for (const id of ids) {
+    if (!state.notif_shown_for_ids.includes(id)) state.notif_shown_for_ids.push(id);
+  }
+  // Cap memory — keep last 200
+  if (state.notif_shown_for_ids.length > 200) {
+    state.notif_shown_for_ids = state.notif_shown_for_ids.slice(-200);
+  }
+  return state;
+}
+
+// ---------------------- macOS native notification ----------------------
+
+/**
+ * Fire a native macOS notification via osascript. Best-effort — silently
+ * no-ops on Linux/Windows. On macOS we may hit the user's notification-
+ * permission gate; we don't care to handle that synchronously.
+ *
+ * Returns true if we tried (macOS), false if we skipped (other platforms).
+ */
+export function fireMacosNotification(title, body, opts = {}) {
+  if (platform() !== 'darwin') return false;
+  // Escape double quotes for AppleScript string literals
+  const esc = (s) => String(s || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const subtitle = opts.subtitle ? ` subtitle "${esc(opts.subtitle)}"` : '';
+  const sound = opts.silent ? '' : ` sound name "Pop"`;
+  const script = `display notification "${esc(body)}" with title "${esc(title)}"${subtitle}${sound}`;
+  try {
+    // Non-blocking — fire and forget
+    spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ---------------------- Mutators for notifications config ----------------------
+
+export function setNotificationsEnabled(state, enabled, showTitles = null) {
+  state.notifications.enabled = !!enabled;
+  if (showTitles !== null) state.notifications.show_titles = !!showTitles;
+  return state;
+}
+
+export function setClickTarget(state, target) {
+  if (!VALID_CLICK_TARGETS.includes(target)) {
+    throw new Error(`Invalid click_target '${target}'. Valid: ${VALID_CLICK_TARGETS.join(', ')}`);
+  }
+  state.notifications.click_target = target;
+  return state;
+}
+
+// ---------------------- Channel B formatter ----------------------
+
+/**
+ * Render the CLI tip block (printed at the end of any non-telegram
+ * memex CLI command, suppressed if pending=0 or recently shown).
+ *
+ *   💡 3 Telegram export(s) ready to review:
+ *      • Family (1,876 msgs)
+ *      • Work team (3,221 msgs)
+ *      • … and 1 more
+ *      Run: memex telegram pending
+ *
+ * Always shows count + up to 3 chat titles + "and N more" tail. Honors
+ * `show_titles=false` setting by hiding titles entirely (just count).
+ */
+export function formatTelegramTip(entries, opts = {}) {
+  if (!entries || entries.length === 0) return '';
+  const showTitles = opts.showTitles !== false;
+  const count = entries.length;
+  const lines = [];
+  lines.push('');
+  lines.push(`💡 ${count} Telegram export${count === 1 ? '' : 's'} ready to review:`);
+  if (showTitles) {
+    const preview = entries.slice(0, 3);
+    for (const e of preview) {
+      const t = e.chat_title || '(untitled)';
+      const n = e.message_count ? `${e.message_count.toLocaleString()} msgs` : '?';
+      lines.push(`   • ${t} (${n})`);
+    }
+    if (entries.length > 3) lines.push(`   • … and ${entries.length - 3} more`);
+  }
+  lines.push('   Run: memex telegram pending');
+  return lines.join('\n');
+}