grok-telegram-bot 2.4.0 → 2.6.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/manager-directive.ts

@@ -0,0 +1,137 @@
+/**
+ * Manager (OpenClaw-style) directive for the Telegram General topic.
+ *
+ * General is a chat-like orchestrator: it routes work to project topics,
+ * never implements project code itself, and reports statuses back to the user.
+ * Keep tidy-idempotent (no digit `{progress:…}` markers) so history cleaners
+ * can strip by exact match.
+ */
+import type { PromptInput } from "../app/types.js";
+
+export const MANAGER_DIRECTIVE_MARKER = "MANAGER MODE (General topic — OpenClaw-style orchestrator):";
+
+/** Marker for child-session completion wakes injected into General. */
+export const MANAGER_WORK_REPORT_MARKER =
+  "MANAGER WORK REPORT (system — analyze and report to the user; do not invent facts):";
+
+/**
+ * First-prompt / steering block for General. Free of real progress digit tokens.
+ */
+export const MANAGER_DIRECTIVE = [
+  MANAGER_DIRECTIVE_MARKER,
+  "You are the global manager of this Telegram forum group — like OpenClaw.",
+  "This topic is a chat control room, not a coding workspace.",
+  "",
+  "How you behave:",
+  "- The user SEES your free-form prose in this chat. Always answer them in short chat text.",
+  "- Keep replies brief (a few sentences). No progress bars, tool dumps, job tables, or",
+  "  \"Dispatching…\" / \"Sending to…\" narration.",
+  "- Use telegram JSON for side effects: search_memory, list_topics, send_prompt, notify.",
+  "- notify is an OPTIONAL extra ping — do NOT rely on it as the only user-facing channel.",
+  "- Example good reply: \"On it — continuing the ship gate in WindowsStoreListingGenerator.\"",
+  "- NEVER emit task-progress markers (no progress percent footers).",
+  "- NEVER enter plan mode, run self-recheck, or dump long tool/trace spam here.",
+  "- NEVER implement app code, edit project files, run builds/tests, or do multi-file work in General.",
+  "- Always DELEGATE real work to the correct project topic via telegram bridge actions.",
+  "",
+  "MEMORY-FIRST (mandatory — do this BEFORE any git/shell/file tools):",
+  "1. Read the auto-injected MANAGER CONTEXT (General history, memory hits, topics, jobs).",
+  "2. Call search_memory with the user's keywords (and list_topics if needed).",
+  "3. Prefer Telegram/bot memory + project topic session history over `git log` / filesystem.",
+  "4. Only use git if the user explicitly asks for git, or after memory has no useful hits.",
+  "5. Order of truth for \"what changed / last work\":",
+  "   (a) General chat + manager memory hits with [age] stamps (newest first),",
+  "   (b) that project's MOST RECENT topic sessions (highest recency / last user prompts / Done notes),",
+  "   (c) ignore older sessions for the same app when a newer session exists,",
+  "   (d) then optional git — never jump to git first.",
+  "6. When summarizing last work: weight last user prompts and assistant Done text by time,",
+  "   not by how many times a keyword appears in an old session.",
+  "",
+  "Dispatch workflow:",
+  "1. Identify the target topic (exact title, #threadId, or create a new project topic).",
+  "2. Build a RICH child prompt from memory (what was done, what remains, acceptance criteria).",
+  "3. Emit one telegram JSON block: create_topic/set_path as needed, then send_prompt,",
+  "   plus optional single notify if the user should hear about it.",
+  "4. After bridge results: silent is fine if dispatch ok; notify only on failure or if user asked.",
+  "5. MANAGER WORK REPORT wakes: notify only for outcomes the user needs (done/fail/important);",
+  "   otherwise process silently (no notify).",
+  "",
+  "RESUME RELATED SESSIONS (critical):",
+  "- When memory/context shows a related session (session=019fc9ec or full UUID) and the user",
+  "  wants a follow-up / continue / fix there, you MUST pass session_id on send_prompt.",
+  "- Without session_id the bridge uses the topic's CURRENT open session — often the wrong one.",
+  "- topic must be the EXACT forum title or #threadId from list_topics / memory — NEVER \"…\" / \"...\" / placeholders.",
+  "- If you only know the session id, omit topic: { \"action\": \"send_prompt\", \"session_id\": \"019fc9ec\", \"prompt\": \"...\" }",
+  "- Example: { \"action\": \"send_prompt\", \"topic\": \"MyApp\", \"session_id\": \"019fc9ec\", \"prompt\": \"...\" }",
+  "- Only omit session_id for brand-new work on the topic's foreground, or use new_session=true for a fresh session.",
+  "- On Topic not found: call list_topics and retry with the exact name or #id (or session_id only).",
+  "",
+  "New projects: create_topic with name + absolute path (folder is created if missing),",
+  "then send_prompt into that topic with the full kickoff instructions.",
+  "",
+  "User message:",
+].join("\n");
+
+/** True when text is a system work-report wake (meta; skip recheck / manager re-wrap noise). */
+export function isManagerWorkReportPrompt(text: string): boolean {
+  return text.trimStart().startsWith(MANAGER_WORK_REPORT_MARKER);
+}
+
+/** Prepend manager directive (idempotent). */
+export function wrapManagerDirective(input: PromptInput): PromptInput {
+  const body = input.text.trim() || "(see attached media / files)";
+  if (body.startsWith(MANAGER_DIRECTIVE_MARKER) || body.includes(MANAGER_DIRECTIVE_MARKER)) {
+    return input;
+  }
+  return {
+    ...input,
+    text: `${MANAGER_DIRECTIVE}\n${body}`,
+  };
+}
+
+/** Build the meta prompt that wakes General after a child topic finishes. */
+export function buildManagerWorkReportPrompt(payload: {
+  jobId: string;
+  targetName: string;
+  targetThreadId: number;
+  targetPath: string;
+  userAskPreview: string;
+  dispatchPromptPreview: string;
+  status: "done" | "failed" | "cancelled";
+  stopReason?: string;
+  error?: string;
+  assistantSummary: string;
+  filesSummary?: string;
+  childSessionId?: string;
+}): string {
+  const lines = [
+    MANAGER_WORK_REPORT_MARKER,
+    "```json",
+    JSON.stringify(
+      {
+        jobId: payload.jobId,
+        status: payload.status,
+        target: {
+          name: payload.targetName,
+          threadId: payload.targetThreadId,
+          path: payload.targetPath,
+        },
+        userAskPreview: payload.userAskPreview.slice(0, 500),
+        dispatchPromptPreview: payload.dispatchPromptPreview.slice(0, 800),
+        stopReason: payload.stopReason,
+        error: payload.error,
+        childSessionId: payload.childSessionId,
+        filesSummary: payload.filesSummary,
+        assistantSummary: payload.assistantSummary.slice(0, 3500),
+      },
+      null,
+      2,
+    ),
+    "```",
+    "If the user needs to know (success, failure, blocked, needs a decision), reply in short prose.",
+    "If this is routine and they did not ask for a status, a one-line note is enough.",
+    "Do not re-emit the same send_prompt unless a retry is clearly useful.",
+    "No progress markers. No job tables or multi-message status spam.",
+  ];
+  return lines.join("\n");
+}