grok-telegram-bot 2.4.0 → 2.5.0

package/src/index.ts

@@ -6,35 +6,114 @@
  * Lifetime rules (critical):
  *  - Prefer staying up over clean-but-dead exits.
  *  - Uncaught errors are logged; the process keeps polling Telegram.
- *  - grammY long-poll is restarted on transport/network death.
- *  - Supervised launches (GROK_TG_SUPERVISED=1 / service) may exit for relaunch;
- *    bare/manual runs re-exec when possible rather than dying silently.
+ *  - grammY long-poll is restarted on transport/network death, 429, 409, etc.
+ *  - Never exit without a clear stderr + log line.
+ *  - Interactive `npm start` stays in-process (no silent detach re-exec).
+ *  - Supervised launches (GROK_TG_SUPERVISED=1) may exit for external relaunch.
  */
-import { spawn } from "node:child_process";
 import { join } from "node:path";
 import type { Bot } from "grammy";
+import { GrammyError, HttpError } from "grammy";
 import { GrokClient } from "./grok/client.js";
 import { createBot } from "./bot/bot.js";
-import { CANONICAL_DIR, INSTANCE_DIR, loadConfig } from "./config.js";
+import { CANONICAL_DIR, loadConfig } from "./config.js";
 import { InstanceLock } from "./app/instance-lock.js";
+import {
+  isIntentionalShutdown,
+  markIntentionalShutdown,
+} from "./app/lifetime-flag.js";
 import { createLogger, enableFileLogging, setLogLevel } from "./logger.js";
 
+/** Last known reason for process end (read by exit/beforeExit handlers). */
+let exitReason = "unknown";
+/** Intentional exit in progress (SIGINT, fatal, lock, supervised relaunch). */
+let shuttingDown = false;
+/** beforeExit keep-alive armed at most once (avoid infinite 60s re-arm spam). */
+let beforeExitKeepalive: ReturnType<typeof setInterval> | undefined;
+/** Set immediately after config load; used by scream/shutdown. */
+let log!: ReturnType<typeof createLogger>;
+
+function noteExit(reason: string): void {
+  exitReason = reason;
+}
+
+function beginShutdown(reason: string): void {
+  shuttingDown = true;
+  markIntentionalShutdown(reason);
+  noteExit(reason);
+  if (beforeExitKeepalive) {
+    clearInterval(beforeExitKeepalive);
+    beforeExitKeepalive = undefined;
+  }
+}
+
+function scream(msg: string): void {
+  try {
+    process.stderr.write(`${msg}\n`);
+  } catch {
+    /* ignore */
+  }
+  try {
+    process.stdout.write(`${msg}\n`);
+  } catch {
+    /* ignore */
+  }
+  try {
+    log?.error(msg);
+  } catch {
+    /* ignore */
+  }
+}
+
 async function main(): Promise<void> {
   process.stdout.write("\u{1F916} Grok Telegram Bot — starting…\n");
 
   const cfg = loadConfig();
   setLogLevel(cfg.logLevel);
   enableFileLogging(cfg.logFile);
-  const log = createLogger("main");
+  log = createLogger("main");
+
+  // Always leave a trail — silent process death was the top reliability bug.
+  process.on("exit", (code) => {
+    const line = `[main] process exit code=${code} reason=${exitReason}`;
+    try {
+      // File logger may already be gone; still try console.
+      console.error(line);
+    } catch {
+      /* ignore */
+    }
+  });
+  process.on("beforeExit", (code) => {
+    // Never fight an intentional shutdown / fatal exit / updater re-exec.
+    if (shuttingDown || isIntentionalShutdown()) return;
+    if (beforeExitKeepalive) return; // already holding the process open
+    // Event loop emptied without an intentional shutdown — keep a handle alive
+    // so we don't vanish with code 0 and no explanation.
+    scream(
+      `\u26A0\uFE0F Event loop emptying (beforeExit code=${code}, reason=${exitReason}). ` +
+        `Keeping process alive — this usually means polling stopped unexpectedly.`,
+    );
+    noteExit(`beforeExit:${exitReason}`);
+    // One ref'd interval (not stacking setTimeouts that re-fire beforeExit forever).
+    beforeExitKeepalive = setInterval(() => {
+      if (shuttingDown || isIntentionalShutdown()) {
+        if (beforeExitKeepalive) clearInterval(beforeExitKeepalive);
+        return;
+      }
+      log?.warn(`beforeExit keepalive still holding process (reason=${exitReason})`);
+    }, 60_000);
+    beforeExitKeepalive.ref?.();
+  });
 
   // Single-instance guard: kill any ghost/duplicate already polling this token.
   const lock = new InstanceLock(cfg.token, join(CANONICAL_DIR, "locks"), process.env.GROK_TG_SUPERVISED === "1");
   if (cfg.singleInstance && !(await lock.acquire())) {
     const msg =
       "Another Grok Telegram Bot is already running for this token (a background service). Use `grok-tg restart`, or `grok-tg stop` first.";
+    beginShutdown("instance-lock-held");
     log.warn(msg);
-    process.stdout.write(`\u26D4 ${msg}\n`);
-    process.exit(0);
+    scream(`\u26D4 ${msg}`);
+    process.exit(1);
   }
 
   log.info("starting Grok Telegram Bot");
@@ -47,13 +126,15 @@ async function main(): Promise<void> {
   // partially inconsistent one. Registering these handlers overrides Node's
   // default "print and exit" for uncaughtException.
   process.on("uncaughtException", (err) => {
+    noteExit(`uncaughtException:${err.message}`);
     log.error("uncaughtException (process stays up):", err);
+    scream(`\u26A0\uFE0F uncaughtException (staying up): ${err.stack || err.message}`);
   });
   process.on("unhandledRejection", (reason) => {
-    log.error(
-      "unhandledRejection (process stays up):",
-      reason instanceof Error ? reason : String(reason),
-    );
+    const msg = reason instanceof Error ? reason.stack || reason.message : String(reason);
+    noteExit(`unhandledRejection:${msg.slice(0, 120)}`);
+    log.error("unhandledRejection (process stays up):", reason instanceof Error ? reason : String(reason));
+    scream(`\u26A0\uFE0F unhandledRejection (staying up): ${msg}`);
   });
 
   const grok = new GrokClient({
@@ -75,6 +156,7 @@ async function main(): Promise<void> {
     } catch (e) {
       const wait = Math.min(60_000, 1000 * 2 ** Math.min(attempt, 5));
       log.error(`Grok ACP start failed (attempt ${attempt}): ${(e as Error).message}; retry in ${wait}ms`);
+      scream(`\u26A0\uFE0F Grok ACP start failed (attempt ${attempt}): ${(e as Error).message}; retry in ${wait}ms`);
       await sleep(wait);
     }
   }
@@ -94,7 +176,9 @@ async function main(): Promise<void> {
       break;
     } catch (e) {
       const wait = Math.min(60_000, 1000 * 2 ** Math.min(attempt, 5));
-      log.error(`createBot failed (attempt ${attempt}): ${(e as Error).message}; retry in ${wait}ms`);
+      const detail = formatTelegramError(e);
+      log.error(`createBot failed (attempt ${attempt}): ${detail}; retry in ${wait}ms`);
+      scream(`\u26A0\uFE0F createBot failed (attempt ${attempt}): ${detail}; retry in ${wait}ms`);
       await sleep(wait);
     }
   }
@@ -102,11 +186,11 @@ async function main(): Promise<void> {
   scheduler!.start();
   await updater!.start();
 
-  let shuttingDown = false;
-  const shutdown = (code: number): void => {
+  const shutdown = (code: number, reason: string): void => {
     if (shuttingDown) return;
-    shuttingDown = true;
-    log.info("shutting down…");
+    beginShutdown(reason);
+    log.info(`shutting down (code=${code}, reason=${reason})…`);
+    scream(`\u{1F6D1} Shutting down (code=${code}, reason=${reason})`);
     try {
       scheduler!.stop();
     } catch {
@@ -130,45 +214,66 @@ async function main(): Promise<void> {
 
   grok.on("restarted", () => log.info("Grok bridge re-bound; sessions continue on next message."));
 
-  process.on("SIGINT", () => shutdown(0));
-  process.on("SIGTERM", () => shutdown(0));
+  process.on("SIGINT", () => shutdown(0, "SIGINT"));
+  process.on("SIGTERM", () => shutdown(0, "SIGTERM"));
 
-  // Refresh the single-instance lock periodically so a long-running process
-  // stays clearly "alive" on disk (start time + pid).
-  const lockHeartbeat = setInterval(() => {
+  // Keepalive + lock heartbeat — REF'd so the process cannot exit with an empty
+  // event loop while we still intend to run (unref was a silent-death footgun).
+  let botUsername = "?";
+  const keepalive = setInterval(() => {
     try {
-      if (!shuttingDown) lock.touch();
-    } catch {
-      /* non-fatal */
+      if (shuttingDown || isIntentionalShutdown()) return;
+      lock.touch();
+      log.info(
+        `keepalive: alive as @${botUsername} polling=${bot!.isRunning()} ` +
+          `pid=${process.pid} uptime=${Math.floor(process.uptime())}s`,
+      );
+    } catch (e) {
+      log.warn(`keepalive tick failed: ${(e as Error).message}`);
     }
-  }, 60_000);
-  lockHeartbeat.unref?.();
-
-  // Keep long-polling forever. On network / 409 / grammY fatal, wait and restart
-  // the poller instead of ending the process (silent death was a critical bug).
-  // If the inner loop still returns without shutdown, attempt self-relaunch; if
-  // that fails, resume polling rather than dying.
-  while (!shuttingDown) {
-    await runPollingForever(bot!, log, () => shuttingDown);
-    if (shuttingDown) break;
-    log.error("Telegram polling loop exited unexpectedly; attempting self-relaunch");
-    const replaced = await selfRelaunch(cfg.projectRoot, log);
-    if (replaced) {
-      clearInterval(lockHeartbeat);
-      shutdown(1);
+  }, 5 * 60_000);
+  // Explicitly ref — do not unref.
+  keepalive.ref?.();
+
+  // Keep long-polling forever. On network / 409 / 429 / grammY fatal, wait and
+  // restart the poller in-process. Interactive runs never detach-relaunch
+  // (that looked like a silent death in the terminal).
+  while (!shuttingDown && !isIntentionalShutdown()) {
+    await runPollingForever(
+      bot!,
+      log,
+      () => shuttingDown || isIntentionalShutdown(),
+      (name) => {
+        botUsername = name;
+      },
+    );
+    if (shuttingDown || isIntentionalShutdown()) break;
+
+    // runPollingForever should only return when shuttingDown; if not, recover.
+    scream("\u26A0\uFE0F Telegram polling loop returned unexpectedly; recovering in-process");
+    log.error("Telegram polling loop returned unexpectedly; recovering in-process (no silent exit)");
+    noteExit("polling-loop-returned");
+
+    if (process.env.GROK_TG_SUPERVISED === "1") {
+      log.info("supervised mode — exiting for external relaunch");
+      noteExit("supervised-relaunch");
+      clearInterval(keepalive);
+      shutdown(1, "supervised-relaunch");
       return;
     }
-    log.error("self-relaunch failed; resuming Telegram polling in 5s");
-    await sleep(5000);
+
+    // Stay in this process — re-enter polling after a short pause.
+    await sleep(3000);
   }
-  clearInterval(lockHeartbeat);
+  clearInterval(keepalive);
 }
 
-/** grammY start with automatic recovery. */
+/** grammY start with automatic recovery and loud classification of API errors. */
 async function runPollingForever(
   bot: Bot,
   log: ReturnType<typeof createLogger>,
   isShuttingDown: () => boolean,
+  onOnline: (username: string) => void,
 ): Promise<void> {
   let attempt = 0;
   while (!isShuttingDown()) {
@@ -176,20 +281,25 @@ async function runPollingForever(
       attempt = 0;
       await bot.start({
         onStart: (info) => {
+          onOnline(info.username);
           log.info(`bot online as @${info.username}`);
           process.stdout.write(`\u2705 Online as @${info.username}. Send it a message on Telegram.\n`);
         },
       });
-      // bot.start resolves when polling is stopped (bot.stop).
+      // bot.start resolves when polling is stopped (bot.stop) or loop ends.
       if (isShuttingDown()) return;
       log.warn("bot.start resolved without shutdown; restarting polling in 2s");
+      scream("\u26A0\uFE0F bot.start resolved without shutdown; restarting polling in 2s");
       await sleep(2000);
     } catch (e) {
       attempt++;
-      const wait = Math.min(60_000, 2000 * 2 ** Math.min(attempt, 5));
-      log.error(
-        `Telegram polling failed (attempt ${attempt}): ${(e as Error).message}; retry in ${wait}ms`,
-      );
+      const classified = classifyPollingError(e);
+      const wait = classified.waitMs ?? Math.min(60_000, 2000 * 2 ** Math.min(attempt, 5));
+      const line =
+        `Telegram polling failed (attempt ${attempt}, ${classified.kind}): ${classified.message}; ` +
+        `retry in ${wait}ms`;
+      log.error(line);
+      scream(`\u26A0\uFE0F ${line}`);
       try {
         await bot.stop();
       } catch {
@@ -200,32 +310,49 @@ async function runPollingForever(
   }
 }
 
-/**
- * Spawn a fresh bot process then let the caller exit (manual / non-supervised).
- * Returns true when a replacement was started (or supervised exit is expected).
- */
-async function selfRelaunch(projectRoot: string, log: ReturnType<typeof createLogger>): Promise<boolean> {
-  if (process.env.GROK_TG_SUPERVISED === "1") {
-    log.info("supervised mode — exiting for external relaunch");
-    return true;
-  }
-  try {
-    const child = spawn(
-      process.execPath,
-      ["--import", "tsx", join(projectRoot, "src", "index.ts"), "--instance", INSTANCE_DIR],
-      { detached: true, stdio: "ignore", cwd: projectRoot, env: process.env },
-    );
-    child.unref();
-    if (!child.pid) {
-      log.error("self-relaunch spawn produced no pid — staying alive");
-      return false;
+function classifyPollingError(e: unknown): { kind: string; message: string; waitMs?: number } {
+  const message = formatTelegramError(e);
+  if (e instanceof GrammyError) {
+    if (e.error_code === 429) {
+      const ra = e.parameters?.retry_after;
+      const waitMs = typeof ra === "number" ? (ra + 1) * 1000 : 10_000;
+      return { kind: "429-rate-limit", message, waitMs };
+    }
+    if (e.error_code === 409) {
+      return {
+        kind: "409-conflict",
+        message: `${message} (another getUpdates consumer for this token?)`,
+        waitMs: 15_000,
+      };
+    }
+    if (e.error_code === 401) {
+      return {
+        kind: "401-unauthorized",
+        message: `${message} (check TELEGRAM_BOT_TOKEN)`,
+        waitMs: 60_000,
+      };
     }
-    log.info(`spawned replacement pid ${child.pid}`);
-    return true;
-  } catch (e) {
-    log.error(`self-relaunch failed: ${(e as Error).message} — staying alive`);
-    return false;
+    return { kind: `grammy-${e.error_code}`, message };
+  }
+  if (e instanceof HttpError) {
+    return { kind: "http-network", message, waitMs: 5_000 };
+  }
+  const msg = (e as Error)?.message ?? String(e);
+  if (/ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang|fetch failed|network/i.test(msg)) {
+    return { kind: "network", message: msg, waitMs: 5_000 };
+  }
+  return { kind: "unknown", message: msg };
+}
+
+function formatTelegramError(e: unknown): string {
+  if (e instanceof GrammyError) {
+    const ra = e.parameters?.retry_after;
+    const extra = typeof ra === "number" ? ` retry_after=${ra}s` : "";
+    return `${e.message} (code ${e.error_code}${extra})`;
   }
+  if (e instanceof HttpError) return `HttpError: ${e.message}`;
+  if (e instanceof Error) return e.message;
+  return String(e);
 }
 
 function sleep(ms: number): Promise<void> {
@@ -233,7 +360,10 @@ function sleep(ms: number): Promise<void> {
 }
 
 main().catch((err) => {
-  console.error("Fatal:", err instanceof Error ? err.stack || err.message : err);
-  // Delay exit so logs flush; VBS restart loop / supervisor can bring us back.
+  // Mark intentional exit so beforeExit keep-alive cannot swallow a real fatal.
+  beginShutdown(`fatal:${err instanceof Error ? err.message : String(err)}`);
+  const text = err instanceof Error ? err.stack || err.message : String(err);
+  console.error("Fatal:", text);
+  scream(`\u274C Fatal (exiting in 1s): ${text}`);
   setTimeout(() => process.exit(1), 1000);
 });

package/src/projects/manager.ts

@@ -34,6 +34,13 @@ export class ProjectManager {
 
   /** List projects, de-duplicated by (case-insensitive) name. */
   list(limit = 100): ProjectEntry[] {
+    const out = this.listAll();
+    if (!Number.isFinite(limit) || limit <= 0 || limit >= out.length) return out;
+    return out.slice(0, limit);
+  }
+
+  /** Full catalog (no slice). Used by forum topic setup for 1000+ projects. */
+  listAll(): ProjectEntry[] {
     const byName = new Map<string, ProjectEntry>();
 
     for (const root of this.roots) {
@@ -62,17 +69,23 @@ export class ProjectManager {
 
     // Freshest first (directory mtime); callers may refine `lastUsed` with
     // session activity and re-sort. Alphabetical as a stable tiebreak.
-    const out = [...byName.values()].sort(
+    return [...byName.values()].sort(
       (a, b) => b.lastUsed - a.lastUsed || a.name.localeCompare(b.name),
     );
-    return out.slice(0, limit);
+  }
+
+  /** Exact catalog name match (case-insensitive). */
+  findExactByName(name: string): ProjectEntry | undefined {
+    const key = name.trim().toLowerCase();
+    if (!key) return undefined;
+    return this.listAll().find((p) => p.name.toLowerCase() === key);
   }
 
   /** Projects whose name contains the query (case-insensitive). */
   search(query: string, limit = 100): ProjectEntry[] {
     const q = query.trim().toLowerCase();
     if (!q) return this.list(limit);
-    return this.list(1000)
+    return this.listAll()
       .filter((p) => p.name.toLowerCase().includes(q))
       .slice(0, limit);
   }

package/src/render/chunk.ts

@@ -1,7 +1,7 @@
 /**
  * Split a MarkdownV2 string into Telegram-sized chunks (<= 4096 chars) without
- * breaking code fences. If a split happens inside a ``` block, the block is
- * closed before the boundary and reopened in the next chunk.
+ * breaking code fences. If a split happens inside a fenced block, the block is
+ * closed before the boundary and reopened in the next chunk (same tick length).
  */
 const LIMIT = 4000; // headroom under Telegram's 4096 hard limit
 
@@ -12,18 +12,19 @@ export function chunkMarkdown(text: string, limit = LIMIT): string[] {
   const chunks: string[] = [];
   let current: string[] = [];
   let size = 0;
-  let fenceLang: string | null = null; // non-null => currently inside a fence
+  /** Open fence: tick count + optional lang; null when outside a fence. */
+  let openFence: { ticks: number; lang: string } | null = null;
 
   const flush = (): void => {
     if (current.length === 0) return;
     let body = current.join("\n");
-    if (fenceLang !== null) body += "\n```"; // close dangling fence
+    if (openFence) body += "\n" + "`".repeat(openFence.ticks); // close dangling fence
     chunks.push(body);
     current = [];
     size = 0;
-    if (fenceLang !== null) {
-      // Reopen the fence at the top of the next chunk.
-      const reopen = "```" + fenceLang;
+    if (openFence) {
+      // Reopen the fence at the top of the next chunk (preserve tick length).
+      const reopen = "`".repeat(openFence.ticks) + openFence.lang;
       current.push(reopen);
       size = reopen.length + 1;
     }
@@ -31,9 +32,9 @@ export function chunkMarkdown(text: string, limit = LIMIT): string[] {
 
   for (const rawLine of lines) {
     const line = rawLine;
-    const fenceMatch = /^```(.*)$/.exec(line);
+    const fenceMatch = /^(```+)(.*)$/.exec(line);
 
-    // Hard-split a single oversized line.
+    // Hard-split a single oversized line (never mid-fence marker line).
     if (line.length + 1 > limit && fenceMatch === null) {
       flush();
       for (let i = 0; i < line.length; i += limit) {
@@ -48,7 +49,13 @@ export function chunkMarkdown(text: string, limit = LIMIT): string[] {
     size += line.length + 1;
 
     if (fenceMatch) {
-      fenceLang = fenceLang === null ? (fenceMatch[1] ?? "").trim() : null;
+      const ticks = fenceMatch[1]!.length;
+      const lang = (fenceMatch[2] ?? "").trim();
+      if (!openFence) {
+        openFence = { ticks, lang };
+      } else if (ticks >= openFence.ticks) {
+        openFence = null;
+      }
     }
   }
 

package/src/render/hashtags.ts

@@ -10,6 +10,8 @@ export interface TagInput {
   projectName?: string;
   cwd?: string;
   sessionId?: string;
+  /** Short id for a single user turn; becomes `#prompt_<id>`. */
+  promptId?: string;
 }
 
 /** Sanitise a value into a Telegram-safe hashtag body (letters/digits/_ only). */
@@ -25,10 +27,12 @@ export function tagSafe(v: string): string {
 /**
  * Build the hashtag footer. `#proj_` is always present; `#sess_` is added only
  * when the session id is known, so partial callers (e.g. a static /history view)
- * still tag consistently. Order: project · session.
+ * still tag consistently. `#prompt_` is added when a turn-level id is known.
+ * Order: project · session · prompt.
  */
 export function sessionHashtags(input: TagInput): string {
   const tags = [`#proj_${tagSafe(input.projectName || basename(input.cwd || "") || "none")}`];
   if (input.sessionId) tags.push(`#sess_${tagSafe(input.sessionId.slice(0, 8))}`);
+  if (input.promptId) tags.push(`#prompt_${tagSafe(input.promptId)}`);
   return tags.join(" ");
 }

package/src/render/session-comment.ts

@@ -1,7 +1,7 @@
 /**
  * Session "comment" shown on Running / Sessions cards:
- *   • while busy  — current step (tool / thinking / working on …)
- *   • when idle   — what the last turn solved (assistant result + files)
+ *   • always     — last user prompt (≤ COMMENT_MAX)
+ *   • while busy — also last AI agent thinking (≤ COMMENT_MAX), second line
  *
  * Built only from data already in the turn — no extra agent prompt (those
  * leaked into chat/history). Display-only; never truncates agent context.
@@ -18,8 +18,8 @@ import {
 } from "./tool-call-detail.js";
 import type { FileOp } from "./file-summary.js";
 
-/** Max length of a card comment line (room for a real one-sentence outcome). */
-export const COMMENT_MAX = 200;
+/** Max length of each card comment line (user prompt or thinking). */
+export const COMMENT_MAX = 250;
 
 /**
  * Legacy marker for the removed silent AI card-summary prompt. Kept only so
@@ -55,13 +55,24 @@ export function stripDirectiveWrappers(raw: string): string {
   const marker = "User's new message:";
   const i = t.lastIndexOf(marker);
   if (i !== -1) t = t.slice(i + marker.length);
-  t = t.replace(/^TASK COMPLEXITY:[\s\S]*?User task:\s*/i, "");
-  t = t.replace(/^COMPLEXITY \(decide yourself[\s\S]*?User task:\s*/i, "");
+  // Continued marker first — it contains the substring "User task:".
+  const cont = "User task (continued):";
+  const ci = t.lastIndexOf(cont);
+  if (ci !== -1) {
+    t = t.slice(ci + cont.length);
+  } else {
+    t = t.replace(/^TASK COMPLEXITY:[\s\S]*?User task:\s*/i, "");
+    t = t.replace(/^COMPLEXITY \(decide yourself[\s\S]*?User task:\s*/i, "");
+    if (/TELEGRAM BRIDGE \(how to work/i.test(t)) {
+      t = t.replace(/TELEGRAM BRIDGE \(how to work[\s\S]*?(?=\n\n[A-Za-z]|$)/i, "");
+    }
+  }
+  if (/^TELEGRAM BRIDGE RESULTS \(system/i.test(t.trim())) t = "";
   return t.trim();
 }
 
 /** Strip bot directives so a user prompt is card-friendly. */
-export function cleanUserPreview(raw: string, max = 80): string {
+export function cleanUserPreview(raw: string, max = COMMENT_MAX): string {
   let t = stripDirectiveWrappers(raw);
   // Import confirm prompts are noise on cards.
   if (/session import complete/i.test(t)) return "";
@@ -69,9 +80,55 @@ export function cleanUserPreview(raw: string, max = 80): string {
   if (/^SELF-RECHECK \(automatic quality pass/i.test(t)) return "Self-recheck";
   if (/^SELF-RECHECK DECISION \(meta only\)/i.test(t)) return "";
   if (/^FOLLOW-UP SUGGESTIONS \(meta only\)/i.test(t)) return "";
+  if (/^TELEGRAM BRIDGE RESULTS \(system/i.test(t)) return "Telegram bridge";
   return cleanCommentLine(t, max);
 }
 
+/**
+ * Format the session-card comment body:
+ *   idle  → last user prompt (≤ max)
+ *   busy  → user prompt + last agent thinking on the next line (each ≤ max)
+ *
+ * Returns "" when neither line has content. Caller adds icons per line.
+ */
+export function buildSessionCardComment(opts: {
+  userPrompt?: string;
+  thinking?: string;
+  busy?: boolean;
+  max?: number;
+}): string {
+  const max = opts.max ?? COMMENT_MAX;
+  const user = opts.userPrompt?.trim()
+    ? cleanUserPreview(opts.userPrompt, max)
+    : "";
+  const thinkRaw = opts.busy && opts.thinking?.trim() ? opts.thinking.trim() : "";
+  const thinking = thinkRaw ? clampThinking(thinkRaw, max) : "";
+
+  if (user && thinking) return `${user}\n${thinking}`;
+  if (user) return user;
+  if (thinking) return thinking;
+  return "";
+}
+
+/**
+ * Prefer the latest portion of accumulated thought text (streaming chunks
+ * append; conclusions land at the end). Collapse whitespace and clamp.
+ */
+export function clampThinking(raw: string, max = COMMENT_MAX): string {
+  let t = extractProgress(raw).cleaned;
+  t = t.replace(/```[\s\S]*?```/g, " ");
+  t = t.replace(/\s+/g, " ").trim();
+  if (!t) return "";
+  if (t.length <= max) return t;
+  // Prefer the ending (most recent thinking).
+  if (t.length > max + 40) {
+    const tail = t.slice(-(max - 1));
+    const sp = tail.indexOf(" ");
+    return "\u2026" + (sp > 0 && sp < 40 ? tail.slice(sp + 1) : tail);
+  }
+  return t.slice(0, max - 1) + "\u2026";
+}
+
 /**
  * Pull a human-useful outcome snippet from the assistant's streamed reply.
  * Prefers the closing sentences (where conclusions land) over mid-turn "I'll…".