nemoris 0.1.0

package/src/runtime/telegram-inbound.js

@@ -0,0 +1,1565 @@
+import { clearCache } from "./identity-cache.js";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getContextLimit } from "../utils/model-context-limits.js";
+import { inspectOutboundUrl } from "../security/ssrf-check.js";
+import { handleApproveCommand, handleClearRepairsCommand, handleHealthCommand } from "../daemon/telegram-commands.js";
+import { ExecApprovalGate } from "./exec-approvals.js";
+import { resolveModelOverride, resolveSessionStatusModel } from "./model-resolution.js";
+
+const PRE_AUTH_COMMANDS = new Set(["/start", "/help"]);
+const OPERATOR_ONLY_COMMANDS = new Set(["/logs"]);
+const THINK_LEVELS = ["off", "low", "medium", "high", "default"];
+const FOCUS_LEVELS = ["deep", "planning", "off"];
+const CALLBACK_PREFIX = {
+  modelList: "mdl:list:",
+  modelSet: "mdl:set:",
+  switchSet: "swt:set:",
+  thinkSet: "thk:set:",
+  focusSet: "fcs:set:",
+};
+
+function chunkButtons(items, size = 2) {
+  const rows = [];
+  for (let index = 0; index < items.length; index += size) {
+    rows.push(items.slice(index, index + size));
+  }
+  return rows;
+}
+
+function parseCallbackData(data) {
+  const value = String(data || "");
+  if (value.startsWith(CALLBACK_PREFIX.modelList)) {
+    return { type: "model_list", providerId: value.slice(CALLBACK_PREFIX.modelList.length) };
+  }
+  if (value.startsWith(CALLBACK_PREFIX.modelSet)) {
+    const rest = value.slice(CALLBACK_PREFIX.modelSet.length);
+    const [providerId, indexText] = rest.split(":");
+    const index = Number.parseInt(indexText, 10);
+    if (!providerId || !Number.isInteger(index)) return null;
+    return { type: "model_set", providerId, index };
+  }
+  if (value.startsWith(CALLBACK_PREFIX.switchSet)) {
+    return { type: "switch_set", agentId: value.slice(CALLBACK_PREFIX.switchSet.length) };
+  }
+  if (value.startsWith(CALLBACK_PREFIX.thinkSet)) {
+    return { type: "think_set", level: value.slice(CALLBACK_PREFIX.thinkSet.length) };
+  }
+  if (value.startsWith(CALLBACK_PREFIX.focusSet)) {
+    return { type: "focus_set", mode: value.slice(CALLBACK_PREFIX.focusSet.length) };
+  }
+  return null;
+}
+const TELEGRAM_HELP_SHORT = [
+  "/switch <agent> — Switch active agent",
+  "/who — Show current agent",
+  "/model <tier> — Switch model (sonnet, haiku, opus, default)",
+  "/status — Show agent and session status",
+  "/usage — Show token usage by model",
+  "/clear — Clear conversation context",
+  "/compact — Compact conversation context",
+  "/search <query> — Search past conversations",
+  "/cost — Show spending: today, this week, this month",
+  "/version — Show version and uptime",
+  "/help — Show this message (/help all for advanced commands)",
+];
+const TELEGRAM_HELP_ALL = [
+  ...TELEGRAM_HELP_SHORT.slice(0, 6),
+  "/stop — Stop current run",
+  "/think <level> — Set thinking: off | low | medium | high | default",
+  TELEGRAM_HELP_SHORT[6],
+  "/agents — List available agents",
+  "/inbox — Show recent inter-agent messages",
+  "/focus <mode> — Set focus mode (deep, planning, off)",
+  "/logs [n] — Tail last N daemon log lines (default 20)",
+  TELEGRAM_HELP_SHORT[7],
+  "/restart [reason] — Restart the daemon",
+  TELEGRAM_HELP_SHORT[8],
+  TELEGRAM_HELP_SHORT[9],
+  "/transfer — Migrate configuration from OpenClaw",
+  "/approve <id> — Approve a held update or staged rule",
+  "/health — Show self-healing system health",
+  "/clear_repairs — Acknowledge all unresolved repairs",
+  "/exec_approve <id> — Approve a pending exec action",
+  "/exec_deny <id> — Deny a pending exec action",
+  "/help — Show this message",
+];
+
+/**
+ * Telegram Inbound Handler — validates, deduplicates, authorizes, and enqueues
+ * incoming Telegram webhook updates as interactive jobs.
+ *
+ * Critical invariant: handleUpdate() is synchronous. All DB operations are
+ * synchronous SQLite calls. The webhook endpoint must return 200 within 5s
+ * or Telegram will retry — no async work before the response.
+ */
+
+const MAX_TURNS = 10;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function resolveRuntimeMode(pollingMode) {
+  return pollingMode === true ? "polling" : (pollingMode || "unknown");
+}
+
+export function resolveStatusModel(session, { routerConfig = null, agentConfigs = null } = {}) {
+  return resolveSessionStatusModel(session, { routerConfig, agentConfigs });
+}
+
+export function appendTurn(contextJson, role, content, imageRef = null) {
+  let turns = [];
+  if (contextJson) {
+    try {
+      turns = JSON.parse(contextJson);
+      if (!Array.isArray(turns)) turns = [];
+    } catch {
+      turns = [];
+    }
+  }
+  const turn = { role, content, timestamp: new Date().toISOString() };
+  if (imageRef) turn.imageRef = imageRef;
+  turns.push(turn);
+  if (turns.length > MAX_TURNS) {
+    turns = turns.slice(turns.length - MAX_TURNS);
+  }
+  return JSON.stringify(turns);
+}
+
+const DOWNLOAD_TIMEOUT_MS = 10000;
+
+/**
+ * Download a Telegram file by file_id, returning base64-encoded data.
+ * Returns null on any failure (network, auth, file expired).
+ *
+ * @param {string} fileId - Telegram file_id
+ * @param {string} botToken - Bot API token
+ * @param {{ fetchImpl?: Function, lookupImpl?: Function }} deps - Injectable dependencies
+ * @returns {Promise<{ base64: string, mediaType: string } | null>}
+ */
+export async function downloadTelegramFile(fileId, botToken, deps = {}) {
+  const fetchFn = deps.fetchImpl || globalThis.fetch;
+  const lookupImpl = deps.lookupImpl;
+  try {
+    // Step 1: Get file path from Telegram API
+    const getFileUrl = `https://api.telegram.org/bot${botToken}/getFile?file_id=${fileId}`;
+    const metaResponse = await fetchFn(getFileUrl, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+    if (!metaResponse.ok) {
+      console.warn(`[telegram-file] getFile failed: HTTP ${metaResponse.status}`);
+      return null;
+    }
+    const meta = await metaResponse.json();
+    if (!meta.ok || !meta.result?.file_path) {
+      console.warn(`[telegram-file] getFile returned no file_path`);
+      return null;
+    }
+
+    // Step 2: Download the binary file
+    const fileUrl = `https://api.telegram.org/file/bot${botToken}/${meta.result.file_path}`;
+    // Telegram's file_path comes from a previous API response, not local config.
+    // Re-check the resolved download host so a tampered path cannot redirect the
+    // bot into loopback, link-local, or RFC1918 destinations.
+    const inspection = await inspectOutboundUrl(fileUrl, {
+      lookupImpl,
+      privateAddressMessage: "Telegram file download blocked — target resolves to a private/reserved IP address.",
+    });
+    if (!inspection.ok) {
+      console.warn(`[telegram-file] ${inspection.reason}`);
+      return null;
+    }
+    const fileResponse = await fetchFn(fileUrl, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+    if (!fileResponse.ok) {
+      console.warn(`[telegram-file] file download failed: HTTP ${fileResponse.status}`);
+      return null;
+    }
+
+    // Step 3: Convert to base64
+    const arrayBuffer = await fileResponse.arrayBuffer();
+    const base64 = Buffer.from(arrayBuffer).toString("base64");
+
+    // Telegram compresses all message.photo to JPEG; revisit for document/sticker support
+    return { base64, mediaType: "image/jpeg" };
+  } catch (err) {
+    console.warn(`[telegram-file] download failed: ${err.message}`);
+    return null;
+  }
+}
+
+const TELEGRAM_MAX_LENGTH = 4096;
+
+/**
+ * Convert common markdown patterns to Telegram HTML.
+ * Telegram HTML supports: <b>, <i>, <code>, <pre>, <a href="">
+ * We must escape &, <, > in plain text regions first.
+ */
+export function markdownToTelegramHtml(text) {
+  if (!text) return text;
+
+  // Step 1: protect code blocks (``` ... ```) from inline processing
+  const codeBlocks = [];
+  let result = text.replace(/```(\w*)\n?([\s\S]*?)```/g, (_, _lang, code) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(`<pre><code>${escapeHtml(code.trimEnd())}</code></pre>`);
+    return `\x00CODE${idx}\x00`;
+  });
+
+  // Step 2: protect inline code (`...`) 
+  const inlineCodes = [];
+  result = result.replace(/`([^`\n]+)`/g, (_, code) => {
+    const idx = inlineCodes.length;
+    inlineCodes.push(`<code>${escapeHtml(code)}</code>`);
+    return `\x00INLINE${idx}\x00`;
+  });
+
+  // Step 3: escape HTML in remaining text
+  result = escapeHtml(result);
+
+  // Step 4: apply markdown patterns (on already-escaped text)
+  // Links: [text](url) → <a href="url">text</a>
+  result = result.replace(/\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, '<a href="$2">$1</a>');
+  // Bold: **text** or __text__
+  result = result.replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>');
+  result = result.replace(/__([^_\n]+)__/g, '<b>$1</b>');
+  // Italic: *text* or _text_ (single, not double)
+  result = result.replace(/\*([^*\n]+)\*/g, '<i>$1</i>');
+  result = result.replace(/_([^_\n]+)_/g, '<i>$1</i>');
+
+  // Step 5: restore protected blocks
+  // eslint-disable-next-line no-control-regex
+  result = result.replace(/\x00CODE(\d+)\x00/g, (_, i) => codeBlocks[i]);
+  // eslint-disable-next-line no-control-regex
+  result = result.replace(/\x00INLINE(\d+)\x00/g, (_, i) => inlineCodes[i]);
+
+  return result;
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function checkpointSqliteWal(db) {
+  if (!db || typeof db.exec !== "function") return false;
+  db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+  return true;
+}
+
+function emitStructuredLog(logger, level, payload) {
+  const message = JSON.stringify(payload);
+  if (logger && typeof logger[level] === "function") {
+    logger[level](message);
+    return;
+  }
+  if (logger && typeof logger.log === "function") {
+    logger.log(message);
+    return;
+  }
+  console.log(message);
+}
+
+function formatTelegramHelp(showAll = false) {
+  if (showAll) {
+    return TELEGRAM_HELP_ALL.join("\n");
+  }
+  return TELEGRAM_HELP_SHORT.join("\n");
+}
+
+export function splitTelegramMessage(text) {
+  if (text.length <= TELEGRAM_MAX_LENGTH) return [text];
+
+  const chunks = [];
+  let remaining = text;
+
+  while (remaining.length > TELEGRAM_MAX_LENGTH) {
+    let splitAt = remaining.lastIndexOf("\n\n", TELEGRAM_MAX_LENGTH);
+    if (splitAt <= 0) splitAt = remaining.lastIndexOf("\n", TELEGRAM_MAX_LENGTH);
+    if (splitAt <= 0) splitAt = TELEGRAM_MAX_LENGTH;
+
+    chunks.push(remaining.slice(0, splitAt).trimEnd());
+    remaining = remaining.slice(splitAt).trimStart();
+  }
+
+  if (remaining.length > 0) chunks.push(remaining);
+  return chunks;
+}
+
+async function sendSplitTelegramText(fetchImpl, url, chatId, text) {
+  const chunks = splitTelegramMessage(text);
+  for (const chunk of chunks) {
+    await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ chat_id: chatId, text: chunk }),
+    });
+  }
+}
+
+/**
+ * Parse an inter-session message header to extract source identity.
+ * Returns null if the text is not an inter-session message.
+ */
+export function parseInterSessionHeader(text) {
+  const match = text.match(/\[Inter-session message\]\s+sourceSession=([\w:.-]+)/);
+  if (!match) return null;
+  const sourceSession = match[1];
+  // e.g. "agent:content:telegram:direct:7781763328"
+  const agentMatch = sourceSession.match(/^agent:(\w+):/);
+  return {
+    sourceType: 'agent',
+    replySessionKey: sourceSession,
+    sourceAgentId: agentMatch ? agentMatch[1] : null,
+  };
+}
+
+/**
+ * Strip the [Inter-session message] header line from message text.
+ */
+export function stripInterSessionHeader(text) {
+  return text.replace(/^\[Inter-session message\]\s+sourceSession=\S+\s*/m, "").trim();
+}
+
+export async function processInteractiveHandoffs(_stateStore) {
+  // TODO: Sub-project 2 — scan pending handoff notifications where source === "telegram",
+  // rebind chat_sessions, send confirmation to user, handle validation/circular detection.
+}
+
+/**
+ * Register slash commands with Telegram. Called once on startup after token validation.
+ * Never throws — logs and returns { ok: false } on any failure so startup is never blocked.
+ */
+export async function setupBotCommands(botToken, { fetchImpl = globalThis.fetch, logger = console } = {}) {
+  const commands = [
+    { command: "switch",  description: "Switch who you're talking to" },
+    { command: "who",     description: "Show who you're currently talking to" },
+    { command: "model",   description: "Change AI model speed/quality — /model sonnet | haiku | opus | default" },
+    { command: "status",  description: "Show system status and today's usage" },
+    { command: "usage",   description: "Show token usage breakdown by model" },
+    { command: "clear",   description: "Start a fresh conversation" },
+    { command: "stop",    description: "Cancel what's happening now" },
+    { command: "think",   description: "Set thinking level: /think off | low | medium | high" },
+    { command: "compact", description: "Free up memory (keeps last 4 turns)" },
+    { command: "agents",  description: "List available agents" },
+    { command: "inbox",   description: "Show recent inter-agent messages" },
+    { command: "focus",   description: "Set focus mode: /focus [deep|planning|off]" },
+    { command: "logs",    description: "Tail last N daemon log lines (default 20)" },
+    { command: "search",  description: "Search past conversations — /search <query>" },
+    { command: "restart", description: "Restart Nemoris" },
+    { command: "version", description: "Show version and uptime" },
+    { command: "transfer", description: "Migrate configuration from OpenClaw" },
+    { command: "approve", description: "Approve a held update or staged rule — /approve <id>" },
+    { command: "health",  description: "Show self-healing system health" },
+    { command: "clear_repairs", description: "Acknowledge all unresolved repairs" },
+    { command: "cost",    description: "Show spending: today, this week, this month" },
+    { command: "exec_approve", description: "Approve a pending exec action — /exec_approve <id>" },
+    { command: "exec_deny",    description: "Deny a pending exec action — /exec_deny <id>" },
+    { command: "help",    description: "Show available commands" },
+  ];
+
+  try {
+    const res = await fetchImpl(`https://api.telegram.org/bot${botToken}/setMyCommands`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ commands }),
+    });
+    const body = await res.json();
+    if (!body.ok) {
+      logger.warn(JSON.stringify({ service: "telegram_setup", event: "setMyCommands_failed", error: body.description }));
+      return { ok: false, error: body.description };
+    }
+    return { ok: true };
+  } catch (error) {
+    logger.warn(JSON.stringify({ service: "telegram_setup", event: "setMyCommands_error", error: error.message }));
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * Validate a bot token by calling getMe. Lightweight — no side effects.
+ * Returns { ok, username, firstName, error }.
+ */
+export async function getMe(botToken, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const res = await fetchImpl(`https://api.telegram.org/bot${botToken}/getMe`, { method: "GET" });
+    const body = await res.json();
+    if (!body.ok) return { ok: false, error: body.description || "getMe failed" };
+    return { ok: true, username: body.result.username, firstName: body.result.first_name };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * Register the webhook URL with Telegram. Does not throw on failure —
+ * returns { ok: boolean, error?: string } so the caller can set a status flag.
+ */
+export async function registerWebhook(botToken, publicUrl, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const url = `https://api.telegram.org/bot${botToken}/setWebhook`;
+    // SSRF note: publicUrl is forwarded to Telegram in JSON only. Nemoris does
+    // not probe or fetch the operator callback URL on the server side.
+    const webhookBody = { url: `${publicUrl}/telegram/webhook` };
+    const webhookSecret = process.env.NEMORIS_TELEGRAM_WEBHOOK_SECRET;
+    if (webhookSecret) {
+      webhookBody.secret_token = webhookSecret;
+    }
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(webhookBody),
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+      return { ok: false, error: `setWebhook failed (${response.status}): ${raw}` };
+    }
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * Get the chat info of the most recent message sender. Used during setup.
+ * Temporarily removes the webhook, calls getUpdates, then re-registers.
+ */
+export async function whoami(botToken, { fetchImpl = globalThis.fetch, webhookUrl = null } = {}) {
+  const api = (method) => `https://api.telegram.org/bot${botToken}/${method}`;
+
+  await fetchImpl(api("deleteWebhook"), { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+
+  const updatesRes = await fetchImpl(api("getUpdates"), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ limit: 1, offset: -1 }),
+  });
+  const updatesBody = JSON.parse(await updatesRes.text());
+
+  if (webhookUrl) {
+    // Same SSRF note as registerWebhook: webhookUrl is serialized back to
+    // Telegram and never fetched by Nemoris.
+    await fetchImpl(api("setWebhook"), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ url: `${webhookUrl}/telegram/webhook` }),
+    });
+  }
+
+  const updates = updatesBody?.result || [];
+  if (updates.length === 0) return null;
+
+  const chat = updates[0]?.message?.chat;
+  if (!chat) return null;
+
+  return {
+    chatId: chat.id,
+    firstName: chat.first_name || "",
+    username: chat.username || "",
+  };
+}
+
+/**
+ * Long-polling loop: calls getUpdates with a 30s timeout, feeds each
+ * update through handler.handleUpdate(), and advances the offset.
+ * No webhook or tunnel required — ideal for home-machine deployment.
+ *
+ * Returns a stop() function that cleanly terminates the loop.
+ */
+export function startTelegramPolling({ botToken, handler, logger = console, fetchImpl = globalThis.fetch }) {
+  const api = (method) => `https://api.telegram.org/bot${botToken}/${method}`;
+  let running = true;
+  let offset = 0;
+  const stateStore = handler?.store || null;
+
+  const persistOffset = async (nextOffset) => {
+    if (!stateStore || typeof stateStore.setMeta !== "function") {
+      return;
+    }
+    try {
+      await stateStore.setMeta("telegram_polling_cursor", { offset: nextOffset });
+    } catch (err) {
+      logger.error(JSON.stringify({ service: "telegram_polling", event: "offset_persist_error", error: err.message }));
+    }
+  };
+
+  const poll = async () => {
+    if (stateStore && typeof stateStore.getMeta === "function") {
+      try {
+        const cursor = await stateStore.getMeta("telegram_polling_cursor", null);
+        const persistedOffset = Number(cursor?.offset || 0);
+        if (Number.isInteger(persistedOffset) && persistedOffset > 0) {
+          offset = persistedOffset;
+        }
+      } catch (err) {
+        logger.error(JSON.stringify({ service: "telegram_polling", event: "offset_restore_error", error: err.message }));
+      }
+    }
+
+    // Clear any existing webhook so Telegram sends updates via getUpdates
+    try {
+      await fetchImpl(api("deleteWebhook"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ drop_pending_updates: false }),
+      });
+    } catch (err) {
+      logger.error(JSON.stringify({ service: "telegram_polling", event: "deleteWebhook_failed", error: err.message }));
+    }
+
+    // Register slash commands — never blocks startup on failure
+    await setupBotCommands(botToken, { fetchImpl, logger });
+
+    while (running) {
+      try {
+        const res = await fetchImpl(api("getUpdates"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ offset, timeout: 30, allowed_updates: ["message"] }),
+          signal: AbortSignal.timeout(35000), // 30s long poll + 5s buffer
+        });
+        const body = await res.json();
+        const updates = body?.result || [];
+
+        for (const update of updates) {
+          offset = update.update_id + 1;
+          await persistOffset(offset);
+          try {
+            const result = await handler.handleUpdate(update);
+            const chatId = update?.message?.chat?.id;
+            const messageId = update?.message?.message_id;
+
+            // React 👀 on enqueue (job accepted, processing starting)
+            if (result?.action === "enqueued" && chatId && messageId) {
+              fetchImpl(`https://api.telegram.org/bot${botToken}/setMessageReaction`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ chat_id: chatId, message_id: messageId, reaction: [{ type: "emoji", emoji: "👀" }] }),
+              }).catch(() => {}); // reactions are best-effort
+            }
+
+            // Send command replies immediately (slash commands don't go through the drain loop)
+            if (result?.action === "command" && result?.reply) {
+              if (chatId) {
+                await sendSplitTelegramText(
+                  fetchImpl,
+                  `https://api.telegram.org/bot${botToken}/sendMessage`,
+                  chatId,
+                  result.reply,
+                ).catch(err => logger.error(JSON.stringify({ service: "telegram_polling", event: "command_reply_error", error: err.message })));
+              }
+            }
+            // Send rejection replies (e.g. edited messages)
+            if (result?.action === "rejected" && result?.reply) {
+              const replyChatId = chatId || update?.edited_message?.chat?.id;
+              if (replyChatId) {
+                await sendSplitTelegramText(
+                  fetchImpl,
+                  `https://api.telegram.org/bot${botToken}/sendMessage`,
+                  replyChatId,
+                  result.reply,
+                ).catch(err => logger.error(JSON.stringify({ service: "telegram_polling", event: "rejection_reply_error", error: err.message })));
+              }
+            }
+            // Send queued ack when user sends a message while a job is running
+            if (result?.queuedAck) {
+              if (chatId) {
+                await sendSplitTelegramText(
+                  fetchImpl,
+                  `https://api.telegram.org/bot${botToken}/sendMessage`,
+                  chatId,
+                  result.queuedAck,
+                ).catch(err => logger.error(JSON.stringify({ service: "telegram_polling", event: "queued_ack_error", error: err.message })));
+              }
+            }
+          } catch (err) {
+            logger.error(JSON.stringify({ service: "telegram_polling", event: "handleUpdate_error", error: err.message }));
+          }
+        }
+      } catch (err) {
+        if (!running) break;
+        // Network error or timeout — back off briefly then retry
+        logger.error(JSON.stringify({ service: "telegram_polling", event: "poll_error", error: err.message }));
+        await new Promise((r) => setTimeout(r, 2000));
+      }
+    }
+  };
+
+  const promise = poll();
+  return {
+    stop: () => { running = false; return promise; },
+  };
+}
+
+export class TelegramInboundHandler {
+  constructor({
+    stateStore,
+    telegramConfig,
+    availablePeers = [],
+    agentHealthCheck = null,
+    logger = console,
+    onRestart = null,
+    contextLedger = null,
+    agentNames = {},
+    routerConfig = null,
+    agentConfigs = null,
+    providerConfigs = null,
+    deps = null,
+    execApprovalGate = null,
+    stopPolling = null,
+  }) {
+    this.store = stateStore;
+    this.config = telegramConfig;
+    this.availablePeers = availablePeers;
+    this.agentHealthCheck = agentHealthCheck;
+    this.logger = logger;
+    this.onRestart = onRestart;
+    this.contextLedger = contextLedger;
+    this.agentNames = agentNames;
+    this.routerConfig = routerConfig;
+    this.agentConfigs = agentConfigs;
+    this.providerConfigs = providerConfigs;
+    this.deps = deps || {};
+    this.operatorChatId = String(telegramConfig?.operatorChatId || "");
+    this.botToken = telegramConfig?.botTokenEnv ? process.env[telegramConfig.botTokenEnv] || null : null;
+    this._execApprovalGate = execApprovalGate || null;
+    this.stopPolling = stopPolling || onRestart || null;
+    // Rate limiter: Map<chatId, { count, windowStart }>
+    this._rateLimitMax = Number(process.env.NEMORIS_RATE_LIMIT_MAX ?? 10);
+    this._rateLimitWindowMs = Number(process.env.NEMORIS_RATE_LIMIT_WINDOW_MS ?? 60_000);
+    this._rateBuckets = new Map();
+  }
+
+  setHealingDeps({ repairLog, ruleStaging, queueNurseJob }) {
+    this.repairLog = repairLog;
+    this.ruleStaging = ruleStaging;
+    this.queueNurseJob = queueNurseJob;
+  }
+
+  _checkRateLimit(chatId) {
+    const now = Date.now();
+    const bucket = this._rateBuckets.get(chatId);
+    if (!bucket || now - bucket.windowStart >= this._rateLimitWindowMs) {
+      this._rateBuckets.set(chatId, { count: 1, windowStart: now });
+      return true;
+    }
+    if (bucket.count >= this._rateLimitMax) {
+      return false;
+    }
+    bucket.count += 1;
+    return true;
+  }
+
+  _ensureSession(chatId) {
+    let session = this.store.getChatSession(chatId);
+    if (!session && this._isAuthorized(chatId)) {
+      this.store.bindChatSession({
+        chatId,
+        agentId: this.config.defaultAgent,
+        boundBy: "default",
+      });
+      session = this.store.getChatSession(chatId);
+    }
+    return session;
+  }
+
+  _setSessionModel(chatId, modelOverride) {
+    this.store.db.prepare("UPDATE chat_sessions SET model_override = ? WHERE chat_id = ?")
+      .run(modelOverride, chatId);
+  }
+
+  _setSessionThink(chatId, thinkMode) {
+    this.store.db.prepare("UPDATE chat_sessions SET think_mode = ? WHERE chat_id = ?")
+      .run(thinkMode, chatId);
+  }
+
+  _setSessionFocus(chatId, focusMode) {
+    this.store.db.prepare("UPDATE chat_sessions SET focus_mode = ? WHERE chat_id = ?")
+      .run(focusMode, chatId);
+  }
+
+  _buildModelCatalog() {
+    const byProvider = new Map();
+    const addModel = (providerId, modelId) => {
+      if (!providerId || !modelId) return;
+      if (!byProvider.has(providerId)) {
+        byProvider.set(providerId, new Set());
+      }
+      byProvider.get(providerId).add(modelId);
+    };
+
+    for (const [providerId, providerConfig] of Object.entries(this.providerConfigs || {})) {
+      for (const model of Object.values(providerConfig?.models || {})) {
+        if (model?.id) addModel(providerId, model.id);
+      }
+    }
+
+    for (const lane of Object.values(this.routerConfig || {})) {
+      for (const modelId of [lane?.primary, lane?.manualBump, lane?.fallback]) {
+        if (typeof modelId !== "string" || !modelId.includes("/")) continue;
+        addModel(modelId.split("/", 1)[0], modelId);
+      }
+    }
+
+    return new Map(
+      [...byProvider.entries()].map(([providerId, models]) => [
+        providerId,
+        [...models].sort((left, right) => left.localeCompare(right)),
+      ])
+    );
+  }
+
+  _buildProviderPickerReply() {
+    const catalog = this._buildModelCatalog();
+    const buttons = [...catalog.keys()].sort().map((providerId) => ({
+      text: `${providerId} (${catalog.get(providerId)?.length || 0})`,
+      callback_data: `${CALLBACK_PREFIX.modelList}${providerId}`,
+    }));
+    return {
+      action: "command",
+      command: "model",
+      reply: "Select a provider:",
+      replyMarkup: { inline_keyboard: chunkButtons(buttons, 2) },
+    };
+  }
+
+  _buildModelListReply(providerId, session) {
+    const models = this._buildModelCatalog().get(providerId) || [];
+    const buttons = models.map((modelId, index) => ({
+      text: session?.model_override === modelId ? `${modelId} ✓` : modelId,
+      callback_data: `${CALLBACK_PREFIX.modelSet}${providerId}:${index}`,
+    }));
+    return {
+      action: "command",
+      command: "model",
+      reply: `Select a model from ${providerId}:`,
+      replyMarkup: { inline_keyboard: chunkButtons(buttons, 1) },
+      editMessage: true,
+    };
+  }
+
+  _handleInlineCallback(chatId, callbackData) {
+    const session = this._ensureSession(chatId);
+    if (!session || !callbackData) {
+      return { action: "ignored", reason: "unknown_callback" };
+    }
+
+    if (callbackData.type === "model_list") {
+      return this._buildModelListReply(callbackData.providerId, session);
+    }
+
+    if (callbackData.type === "model_set") {
+      const models = this._buildModelCatalog().get(callbackData.providerId) || [];
+      const modelId = models[callbackData.index];
+      if (!modelId) {
+        return { action: "ignored", reason: "unknown_model_choice" };
+      }
+      this._setSessionModel(chatId, modelId);
+      return {
+        action: "command",
+        command: "model",
+        reply: `Model set to ${modelId} for this session.`,
+        editMessage: true,
+      };
+    }
+
+    if (callbackData.type === "switch_set") {
+      if (!this.availablePeers.includes(callbackData.agentId)) {
+        return { action: "ignored", reason: "unknown_agent_choice" };
+      }
+      this.store.bindChatSession({ chatId, agentId: callbackData.agentId, boundBy: "user" });
+      return {
+        action: "command",
+        command: "switch",
+        reply: `Switched to ${callbackData.agentId}.`,
+        editMessage: true,
+      };
+    }
+
+    if (callbackData.type === "think_set" && THINK_LEVELS.includes(callbackData.level)) {
+      const value = callbackData.level === "default" ? null : callbackData.level;
+      this._setSessionThink(chatId, value);
+      return {
+        action: "command",
+        command: "think",
+        reply: `Thinking mode set to: ${callbackData.level === "default" ? "default (off)" : callbackData.level}`,
+        editMessage: true,
+      };
+    }
+
+    if (callbackData.type === "focus_set" && FOCUS_LEVELS.includes(callbackData.mode)) {
+      const value = callbackData.mode === "off" ? null : callbackData.mode;
+      this._setSessionFocus(chatId, value);
+      return {
+        action: "command",
+        command: "focus",
+        reply: `Focus mode set to: ${callbackData.mode}`,
+        editMessage: true,
+      };
+    }
+
+    return { action: "ignored", reason: "unknown_callback" };
+  }
+
+  async handleUpdate(update) {
+    if (update?.callback_query) {
+      const callbackQuery = update.callback_query;
+      const chatId = String(callbackQuery?.message?.chat?.id || "");
+      if (!chatId) {
+        return { action: "ignored", reason: "no_callback_chat" };
+      }
+      if (!this._isAuthorized(chatId)) {
+        return { action: "rejected", reason: "unauthorized", reply: "❌ Unauthorized." };
+      }
+      return this._handleInlineCallback(chatId, parseCallbackData(callbackQuery.data));
+    }
+
+    // 1a. Detect edited messages — reply with guidance, don't enqueue
+    if (update?.edited_message) {
+      return {
+        action: "rejected",
+        reason: "edited_message",
+        reply: "I don't re-process edited messages — send a new message.",
+      };
+    }
+
+    // 1b. Validate: must have message with text or photo
+    const message = update?.message;
+    if (!message) {
+      return { action: "ignored", reason: "no_message" };
+    }
+
+    const text = message.text || message.caption || null;
+    const photo = message.photo;
+
+    if (!text && !photo) {
+      return { action: "ignored", reason: "no_content" };
+    }
+
+    const chatId = String(message.chat.id);
+    const messageId = message.message_id;
+    const jobId = `telegram-${chatId}-${messageId}`;
+
+    // 2. Deduplicate
+    if (this.store.interactiveJobExists(jobId)) {
+      return { action: "deduplicated", jobId };
+    }
+
+    let session = this._ensureSession(chatId);
+
+    // 3. Parse commands (stub — expanded in Task 8)
+    if (text && text.startsWith("/")) {
+      const commandName = text.trim().split(/\s+/, 1)[0].toLowerCase();
+      if (!this._isAuthorized(chatId) && !PRE_AUTH_COMMANDS.has(commandName)) {
+        this.logger.warn(`[telegram-inbound] Unauthorized chat_id: ${chatId} attempted ${commandName}`);
+        return { action: "rejected", reason: "unauthorized", reply: "❌ Unauthorized." };
+      }
+      if (OPERATOR_ONLY_COMMANDS.has(commandName) && chatId !== String(this.config.operatorChatId)) {
+        return { action: "command", command: commandName.slice(1), reply: "❌ This command is operator-only." };
+      }
+      const commandResult = await this._handleCommand(text, chatId);
+      if (commandResult) return commandResult;
+    }
+
+    // 3b. Detect inter-session message header
+    const interSession = text ? parseInterSessionHeader(text) : null;
+    const cleanInput = interSession ? stripInterSessionHeader(text) : (text || "[Photo]");
+
+    // 4. Look up or create session
+    session = session || this.store.getChatSession(chatId);
+
+    // 6. Reject unauthorized
+    if (!session) {
+      this.logger.warn(`[telegram-inbound] Unauthorized chat_id: ${chatId}`);
+      return { action: "rejected", reason: "unauthorized" };
+    }
+
+    const agentId = session.agent_id;
+
+    // 7. Check agent availability
+    if (this.agentHealthCheck) {
+      const health = this.agentHealthCheck(agentId);
+      if (!health.available) {
+        this.logger.warn(`[telegram-inbound] Agent unavailable: ${agentId} — ${health.reason}`);
+        return {
+          action: "agent_unavailable",
+          agentId,
+          reason: health.reason,
+          reply: `Agent ${agentId} is no longer available. Use /switch to choose another.`,
+        };
+      }
+    }
+
+    // 8. Rate limit check
+    if (!this._checkRateLimit(chatId)) {
+      this.logger.warn(`[telegram-inbound] Rate limit exceeded for chat_id: ${chatId}`);
+      return {
+        action: "rate_limited",
+        chatId,
+        reply: "Slow down — max 10 messages per minute.",
+      };
+    }
+
+    // 9. Check for running job — send queued ack if busy
+    let queuedAck;
+    try {
+      const runningJob = this.store.db.prepare(
+        "SELECT job_id FROM interactive_jobs WHERE chat_id = ? AND status = 'running' LIMIT 1"
+      ).get(chatId);
+      if (runningJob) {
+        queuedAck = "On it — finishing current task first, you're queued 🔄";
+      }
+    } catch (_) {}
+
+    // 10. Extract image refs from photo array (largest = last element)
+    let imageRefs = null;
+    if (photo && photo.length > 0) {
+      const largest = photo[photo.length - 1];
+      imageRefs = JSON.stringify([{
+        fileId: largest.file_id,
+        mediaType: "image/jpeg",
+      }]);
+    }
+
+    // 11. Enqueue job
+    this.store.enqueueInteractiveJob({
+      jobId, agentId, input: cleanInput, source: "telegram", chatId,
+      imageRefs,
+      sourceType: interSession?.sourceType || 'human',
+      replySessionKey: interSession?.replySessionKey || null,
+      sourceAgentId: interSession?.sourceAgentId || null,
+    });
+
+    return { action: "enqueued", jobId, agentId, chatId, queuedAck };
+  }
+
+  _isAuthorized(chatId) {
+    if (String(this.config.operatorChatId) === chatId) return true;
+    const authorized = this.config.authorizedChatIds || [];
+    return authorized.map(String).includes(chatId);
+  }
+
+  async _handleCommand(text, chatId) {
+    const parts = text.trim().split(/\s+/);
+    const cmd = parts[0].toLowerCase();
+
+    if (cmd === "/start") {
+      return {
+        action: "command",
+        command: "start",
+        reply: "Welcome to Nemoris. Use /help to see the available commands.",
+      };
+    }
+
+    // /version works without a session
+    if (cmd === "/version") {
+      const pkg = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url)));
+      const uptimeSecs = Math.floor(process.uptime());
+      const h = Math.floor(uptimeSecs / 3600);
+      const m = Math.floor((uptimeSecs % 3600) / 60);
+      const s = uptimeSecs % 60;
+      const uptimeStr = h > 0 ? `${h}h ${m}m` : m > 0 ? `${m}m ${s}s` : `${s}s`;
+      return { action: "command", command: "version", reply: `Nemoris v${pkg.version} • uptime ${uptimeStr}` };
+    }
+
+    // /logs works without a session
+    if (cmd === "/logs") {
+      const lineCount = Math.min(Math.max(parseInt(parts[1], 10) || 20, 1), 100);
+      const logPath = path.join(this.store.rootDir, "daemon.out.log");
+      try {
+        const content = fs.readFileSync(logPath, "utf-8");
+        const lines = content.split("\n").filter(Boolean);
+        const tail = lines.slice(-lineCount);
+        if (tail.length === 0) {
+          return { action: "command", command: "logs", reply: "Log file is empty." };
+        }
+        let output = tail.join("\n");
+        if (output.length > 4000) {
+          output = output.slice(-4000);
+          output = "…" + output.slice(output.indexOf("\n") + 1);
+        }
+        return { action: "command", command: "logs", reply: output };
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return { action: "command", command: "logs", reply: "No log file found. Is the daemon running?" };
+        }
+        return { action: "command", command: "logs", reply: `Failed to read logs: ${err.message}` };
+      }
+    }
+
+    // Commands require an existing session
+    const session = this.store.getChatSession(chatId);
+    if (!session) return null; // falls through to authorization check
+
+    switch (cmd) {
+      case "/switch": {
+        const targetAgent = parts[1];
+        if (!targetAgent) {
+          return {
+            action: "command",
+            command: "switch",
+            reply: "Select an agent:",
+            replyMarkup: {
+              inline_keyboard: chunkButtons(
+                this.availablePeers.map((agentId) => ({
+                  text: agentId,
+                  callback_data: `${CALLBACK_PREFIX.switchSet}${agentId}`,
+                })),
+                2
+              ),
+            },
+          };
+        }
+        if (!this.availablePeers.includes(targetAgent)) {
+          return { action: "command", command: "switch", reply: `Unknown agent "${targetAgent}". Use /agents to see available agents.` };
+        }
+        this.store.bindChatSession({ chatId, agentId: targetAgent, boundBy: "user" });
+        return { action: "command", command: "switch", reply: `Switched to ${targetAgent}.` };
+      }
+
+      case "/model": {
+        const requestedModel = parts[1];
+        const tier = requestedModel?.toLowerCase();
+        const validTiers = ["sonnet", "haiku", "opus", "default"];
+        if (!requestedModel) {
+          return this._buildProviderPickerReply();
+        }
+        if (!requestedModel.includes("/") && !validTiers.includes(tier)) {
+          return { action: "command", command: "model", reply: "Usage: /model <tier-or-model-id>\nAvailable tiers: sonnet, haiku, opus, default" };
+        }
+        const resolvedModel = requestedModel.includes("/")
+          ? requestedModel
+          : resolveModelOverride(tier, { routerConfig: this.routerConfig });
+
+        this._setSessionModel(chatId, resolvedModel);
+        const displayName = resolvedModel || "default";
+        return { action: "command", command: "model", reply: `Model set to ${displayName} for this session.` };
+      }
+
+      case "/who": {
+        const method = session.bound_by === "default" ? "Default"
+          : session.bound_by === "user" ? "You switched"
+          : session.bound_by === "agent_handoff" ? `Handed off by ${session.previous_agent_id || "unknown"}`
+          : session.bound_by;
+        const resolvedModelOverride = resolveModelOverride(session.model_override, { routerConfig: this.routerConfig });
+        const modelDisplay = resolvedModelOverride ? ` [model: ${resolvedModelOverride}]` : "";
+        const displayName = this.agentNames?.[session.agent_id] || session.agent_id;
+        return { action: "command", command: "who", reply: `Current agent: ${displayName}${modelDisplay} (${method})` };
+      }
+
+      case "/status": {
+        const lines = [];
+
+        // Line 1: Agent + Model
+        const modelDisplay = resolveStatusModel(session, {
+          routerConfig: this.routerConfig,
+          agentConfigs: this.agentConfigs,
+        });
+        lines.push(`🤖 Agent: ${session.agent_id}  ·  Model: ${modelDisplay}`);
+
+        // Line 2: Auth — last used provider from usage_log
+        let authLine = "🔑 Auth: unknown";
+        try {
+          const lastRow = this.store.db.prepare(
+            "SELECT provider FROM usage_log ORDER BY ts DESC LIMIT 1"
+          ).get();
+          if (lastRow) authLine = `🔑 Auth: ${lastRow.provider}:direct`;
+        } catch { /* ignore */ }
+        lines.push(authLine);
+
+        if (this.store.db) {
+          try {
+            const startOfToday = new Date();
+            startOfToday.setHours(0, 0, 0, 0);
+            const ts = startOfToday.getTime();
+
+            // Line 3: Cache hit (today's data from usage_log)
+            const cacheRow = this.store.db.prepare(`
+              SELECT
+                sum(cache_in) as total_cache_in,
+                sum(tokens_in) as total_tokens_in
+              FROM usage_log WHERE ts >= ?
+            `).get(ts);
+            if (cacheRow && (cacheRow.total_cache_in > 0 || cacheRow.total_tokens_in > 0)) {
+              const cIn = cacheRow.total_cache_in || 0;
+              const tIn = cacheRow.total_tokens_in || 0;
+              const hitPct = (cIn + tIn) > 0 ? Math.round((cIn / (cIn + tIn)) * 100) : 0;
+              lines.push(`🗄 Cache: ${hitPct}% hit  ·  ${Math.round(cIn / 1000)}k cached, ${Math.round(tIn / 1000)}k new`);
+            }
+
+            // Line 4: Context window (session lifetime) + Compactions
+            const sessionId = chatId;
+            const ctxRow = this.store.db.prepare(`
+              SELECT sum(tokens_in + tokens_out + coalesce(cache_in,0)) as ctx_tokens
+              FROM usage_log WHERE session_id = ?
+            `).get(sessionId);
+            const ctxTokens = ctxRow?.ctx_tokens || 0;
+            const ctxLimit = getContextLimit(modelDisplay);
+            const ctxPct = ctxLimit > 0 ? Math.round((ctxTokens / ctxLimit) * 100) : 0;
+            let compactCount = 0;
+            try {
+              if (this.contextLedger?.db) {
+                const cRow = this.contextLedger.db.prepare(
+                  "SELECT COUNT(*) as cnt FROM context_summaries WHERE session_id = ?"
+                ).get(sessionId);
+                compactCount = cRow?.cnt || 0;
+              }
+            } catch { /* context_summaries may not exist */ }
+            lines.push(`📚 Context: ${Math.round(ctxTokens / 1000)}k/${Math.round(ctxLimit / 1000)}k (${ctxPct}%)  ·  🧹 Compactions: ${compactCount}`);
+
+            // Today usage
+            const todayRow = this.store.db.prepare(`
+              SELECT count(*) as turns, sum(tokens_in + tokens_out) as total_tokens, sum(cost_usd) as total_cost
+              FROM usage_log WHERE ts >= ?
+            `).get(ts);
+            if (todayRow && todayRow.turns > 0) {
+              const cost = (todayRow.total_cost || 0).toFixed(2);
+              const tok = Math.round((todayRow.total_tokens || 0) / 1000);
+              lines.push(`📊 Today: ${todayRow.turns} turns  ·  ~${tok}k tokens  ·  ~$${cost}`);
+            }
+          } catch (err) {
+            this.logger.error(`[telegram-inbound] /status query failed: ${err.message}`);
+          }
+        }
+
+        // Line 5: Session + Focus
+        const focusDisplay = session.focus_mode || "off";
+        const sessionLabelPrefix = this.config.sessionLabelPrefix || "telegram";
+        lines.push(`🧵 Session: ${sessionLabelPrefix}:${chatId}  ·  Focus: ${focusDisplay}`);
+
+        // Line 6: Runtime + Queue
+        const runtimeMode = resolveRuntimeMode(this.config.pollingMode);
+        let queueCount = 0;
+        try {
+          const qRow = this.store.db.prepare(
+            "SELECT COUNT(*) as cnt FROM interactive_jobs WHERE status = 'queued'"
+          ).get();
+          queueCount = qRow?.cnt || 0;
+        } catch { /* ignore */ }
+        lines.push(`⚙️ Runtime: ${runtimeMode}  ·  Queue: ${queueCount} pending`);
+
+        return { action: "command", command: "status", reply: lines.join("\n") };
+      }
+
+      case "/usage": {
+        if (!this.store.db) {
+          return { action: "command", command: "usage", reply: "Usage data unavailable." };
+        }
+        try {
+          const startOfToday = new Date();
+          startOfToday.setHours(0, 0, 0, 0);
+          const ts = startOfToday.getTime();
+
+          const todayRows = this.store.db.prepare(`
+            SELECT model, count(*) as turns, sum(tokens_in + tokens_out) as total_tokens, sum(cost_usd) as total_cost
+            FROM usage_log WHERE ts >= ?
+            GROUP BY model ORDER BY total_tokens DESC
+          `).all(ts);
+
+          const allRows = this.store.db.prepare(`
+            SELECT model, count(*) as turns, sum(tokens_in + tokens_out) as total_tokens, sum(cost_usd) as total_cost
+            FROM usage_log
+            GROUP BY model ORDER BY total_tokens DESC
+          `).all();
+
+          const fmt = (rows) => rows.length === 0
+            ? "  (no data)"
+            : rows.map(r => {
+                const tok = Math.round((r.total_tokens || 0) / 1000);
+                const cost = (r.total_cost || 0).toFixed(2);
+                return `  ${r.model}: ${r.turns} turns · ${tok}k tokens · $${cost}`;
+              }).join("\n");
+
+          const reply = [
+            "📊 Usage — Today",
+            fmt(todayRows),
+            "",
+            "📊 Usage — All time",
+            fmt(allRows),
+          ].join("\n");
+
+          return { action: "command", command: "usage", reply };
+        } catch (err) {
+          this.logger.error(`[telegram-inbound] /usage failed: ${err.message}`);
+          return { action: "command", command: "usage", reply: "Failed to load usage data. Try /restart if this keeps happening." };
+        }
+      }
+
+      case "/clear": {
+        this.store.db.prepare(
+          "UPDATE chat_sessions SET conversation_context = NULL WHERE chat_id = ?"
+        ).run(chatId);
+        return { action: "command", command: "clear", reply: "Context cleared. Fresh start 🧹" };
+      }
+
+      case "/stop": {
+        const runningJobs = this.store.db.prepare(
+          "SELECT job_id FROM interactive_jobs WHERE status = 'running' AND chat_id = ?"
+        ).all(chatId);
+        if (runningJobs.length === 0) {
+          return { action: "command", command: "stop", reply: "No active run to stop." };
+        }
+        const ids = runningJobs.map(r => r.job_id);
+        const placeholders = ids.map(() => "?").join(", ");
+        this.store.db.prepare(
+          `UPDATE interactive_jobs SET status = 'failed' WHERE job_id IN (${placeholders})`
+        ).run(...ids);
+        return { action: "command", command: "stop", reply: `Stopping current run... ✋ (${ids.length} job(s) cancelled)` };
+      }
+
+      case "/think": {
+        const level = parts[1]?.toLowerCase();
+        if (!level) {
+          return {
+            action: "command",
+            command: "think",
+            reply: "Select a thinking level:",
+            replyMarkup: {
+              inline_keyboard: chunkButtons(
+                THINK_LEVELS.map((value) => ({
+                  text: value,
+                  callback_data: `${CALLBACK_PREFIX.thinkSet}${value}`,
+                })),
+                2
+              ),
+            },
+          };
+        }
+        if (!THINK_LEVELS.includes(level)) {
+          return { action: "command", command: "think", reply: "Usage: /think off | low | medium | high | default" };
+        }
+        const thinkValue = level === "default" ? null : level;
+        this._setSessionThink(chatId, thinkValue);
+        const display = level === "default" ? "default (off)" : level;
+        return { action: "command", command: "think", reply: `Thinking mode set to: ${display}` };
+      }
+
+      case "/focus": {
+        const mode = parts[1]?.toLowerCase();
+        if (!mode) {
+          return {
+            action: "command",
+            command: "focus",
+            reply: "Select a focus mode:",
+            replyMarkup: {
+              inline_keyboard: chunkButtons(
+                FOCUS_LEVELS.map((value) => ({
+                  text: value,
+                  callback_data: `${CALLBACK_PREFIX.focusSet}${value}`,
+                })),
+                2
+              ),
+            },
+          };
+        }
+        if (!FOCUS_LEVELS.includes(mode)) {
+          return { action: "command", command: "focus", reply: "Usage: /focus deep | planning | off" };
+        }
+        const focusValue = mode === "off" ? null : mode;
+        this._setSessionFocus(chatId, focusValue);
+        return { action: "command", command: "focus", reply: `Focus mode set to: ${mode}` };
+      }
+
+      case "/compact": {
+        const existing = session.conversation_context;
+        let turns = [];
+        try {
+          turns = existing ? JSON.parse(existing) : [];
+          if (!Array.isArray(turns)) turns = [];
+        } catch { turns = []; }
+
+        if (turns.length <= 4) {
+          return { action: "command", command: "compact", reply: "Context already compact — nothing to do." };
+        }
+
+        const beforeChars = (existing || "").length;
+        const kept = turns.slice(-4);
+        const compacted = JSON.stringify(kept);
+        const afterChars = compacted.length;
+
+        this.store.db.prepare("UPDATE chat_sessions SET conversation_context = ? WHERE chat_id = ?")
+          .run(compacted, chatId);
+
+        const beforeK = Math.round(beforeChars / 4 / 1000);
+        const afterK = Math.round(afterChars / 4 / 1000);
+        return {
+          action: "command",
+          command: "compact",
+          reply: `Compacted 🗜️ — context reduced from ~${beforeK}k to ~${afterK}k tokens (kept last 4 turns)`,
+        };
+      }
+
+      case "/agents": {
+        const list = this.availablePeers.length > 0
+          ? this.availablePeers.join(", ")
+          : "No agents configured";
+        const lines = [`Available agents: ${list}`];
+        try {
+          const recentAgentJobs = this.store.getRecentAgentJobs(5);
+          if (recentAgentJobs.length > 0) {
+            lines.push("\nRecent inter-agent messages:");
+            for (const j of recentAgentJobs) {
+              const preview = String(j.input || "").slice(0, 40).replace(/\n/g, " ");
+              const time = j.created_at ? new Date(j.created_at).toTimeString().slice(0, 5) : "?";
+              const statusIcon = j.status === "succeeded" ? "✅" : j.status === "failed" ? "❌" : "⏳";
+              lines.push(`📨 ${j.source_agent_id || "?"} → ${j.agent_id}: "${preview}..." (${time}, ${statusIcon})`);
+            }
+          }
+        } catch { /* ignore — observability only */ }
+        return { action: "command", command: "agents", reply: lines.join("\n") };
+      }
+
+      case "/inbox": {
+        const lines = ["📨 Inter-agent messages"];
+        try {
+          const jobs = this.store.getRecentAgentJobs(10);
+          if (jobs.length === 0) {
+            lines.push("\nNo pending agent messages.");
+          } else {
+            for (const j of jobs) {
+              const preview = String(j.input || "").slice(0, 80).replace(/\n/g, " ");
+              const time = j.created_at ? new Date(j.created_at).toTimeString().slice(0, 5) : "?";
+              const statusLabel = j.status === "succeeded" ? "✅ Replied" : j.status === "failed" ? "❌ Failed" : "⏳ Pending";
+              lines.push(`\nFrom: ${j.source_agent_id || "unknown"} — ${time}`);
+              lines.push(`"${preview}"`);
+              lines.push(`Status: ${statusLabel}`);
+            }
+          }
+        } catch (err) {
+          lines.push("\nFailed to load inbox data.");
+          this.logger.error(`[telegram-inbound] /inbox failed: ${err.message}`);
+        }
+        return { action: "command", command: "inbox", reply: lines.join("\n") };
+      }
+
+      case "/restart": {
+        const reason = parts.slice(1).join(" ").trim() || "telegram:/restart";
+        clearCache();
+        try {
+          checkpointSqliteWal(this.store.db);
+        } catch (error) {
+          this.logger.error?.(`[telegram-inbound] /restart checkpoint failed: ${error.message}`);
+        }
+        try {
+          this.stopPolling?.();
+        } catch (error) {
+          this.logger.error?.(`[telegram-inbound] /restart stopPolling failed: ${error.message}`);
+        }
+        try {
+          const processImpl = this.deps?.processImpl || process;
+          const spawnImpl = this.deps?.spawnImpl || spawn;
+          const installDir = processImpl.env.NEMORIS_INSTALL_DIR || path.resolve(__dirname, "../..");
+          const cliPath = path.join(installDir, "src", "cli.js");
+          const child = spawnImpl(processImpl.execPath, [cliPath, "serve-daemon", "live"], {
+            cwd: installDir,
+            detached: true,
+            stdio: "ignore",
+            env: {
+              ...processImpl.env,
+              NEMORIS_INSTALL_DIR: installDir,
+            },
+          });
+          child.unref?.();
+          const stateDir = path.join(installDir, "state");
+          fs.mkdirSync(stateDir, { recursive: true });
+          fs.writeFileSync(path.join(stateDir, "daemon.pid"), `${child.pid}\n`);
+        } catch (error) {
+          this.logger.error?.(`[telegram-inbound] /restart respawn failed: ${error.message}`);
+          return { action: "command", command: "restart", reply: `Restart failed: ${error.message}` };
+        }
+        emitStructuredLog(this.logger, "info", {
+          service: "telegram_inbound",
+          event: "restart_requested",
+          reason,
+          chatId,
+        });
+        const processImpl = this.deps?.processImpl || process;
+        setTimeout(() => processImpl.exit(0), 1000);
+        return { action: "command", command: "restart", reply: "Restarting... back in a moment." };
+      }
+
+      case "/transfer": {
+        // Async — kicks off migration and responds with result summary
+        try {
+          const { runMigration } = await import("./migration.js");
+          const liveRoot = process.env.NEMORIS_LIVE_ROOT;
+          if (!liveRoot) {
+            return { action: "command", command: "transfer", reply: "NEMORIS_LIVE_ROOT is not set. Point it at your OpenClaw directory first." };
+          }
+          const result = await runMigration({ installDir: process.cwd(), liveRoot, dryRun: false });
+          const summary = [
+            `✅ Migration complete`,
+            `Agents: ${result.agentsMigrated.length} imported, ${result.agentsSkipped.length} skipped`,
+            `Cron jobs: ${result.cronJobsMigrated.length} imported, ${result.cronJobsSkipped.length} skipped`,
+            result.memoryImported > 0 ? `Memory: ${result.memoryImported} entries imported` : null,
+            result.memorySkipped ? `Memory: skipped (already imported)` : null,
+            result.workspaceDocsImported > 0 ? `Workspace docs: ${result.workspaceDocsImported} copied` : null,
+            result.warnings.length ? `⚠️ Warnings: ${result.warnings.join("; ")}` : null,
+            result.launchctlHint ? `\n${result.launchctlHint}` : null,
+          ].filter(Boolean).join("\n");
+          return { action: "command", command: "transfer", reply: summary };
+        } catch (err) {
+          return { action: "command", command: "transfer", reply: `❌ Migration failed: ${err.message}` };
+        }
+      }
+
+      case "/cost": {
+        if (!this.store.db) {
+          return { action: "command", command: "cost", reply: "Cost data unavailable." };
+        }
+        try {
+          const now = new Date();
+          const startOfToday = new Date(now); startOfToday.setHours(0, 0, 0, 0);
+          const startOfWeek = new Date(now); startOfWeek.setDate(now.getDate() - now.getDay()); startOfWeek.setHours(0, 0, 0, 0);
+          const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1);
+
+          const sumSince = (ts) => {
+            const row = this.store.db.prepare(
+              "SELECT COALESCE(SUM(cost_usd), 0) as total, COUNT(*) as turns FROM usage_log WHERE ts >= ?"
+            ).get(ts);
+            return row;
+          };
+
+          const today = sumSince(startOfToday.getTime());
+          const week = sumSince(startOfWeek.getTime());
+          const month = sumSince(startOfMonth.getTime());
+
+          const fmt = (label, data) => `${label}: $${data.total.toFixed(2)} (${data.turns} turns)`;
+
+          const reply = [
+            "💰 Spending",
+            fmt("  Today", today),
+            fmt("  This week", week),
+            fmt("  This month", month),
+          ].join("\n");
+
+          return { action: "command", command: "cost", reply };
+        } catch (err) {
+          this.logger.error(`[telegram-inbound] /cost failed: ${err.message}`);
+          return { action: "command", command: "cost", reply: "Failed to load cost data." };
+        }
+      }
+
+      case "/search": {
+        const query = parts.slice(1).join(" ").trim();
+        if (!query) {
+          return { action: "command", command: "search", reply: "Usage: /search <query>\nExample: /search auth flow discussion" };
+        }
+        try {
+          const { SessionSearch } = await import("./session-search.js");
+          if (!this._sessionSearch && this.contextLedger) {
+            this._sessionSearch = new SessionSearch(this.contextLedger);
+            this._sessionSearch.ensureSchema();
+          }
+          if (!this._sessionSearch) {
+            return { action: "command", command: "search", reply: "Search not available — context ledger not initialized." };
+          }
+          const results = this._sessionSearch.search(query, { limit: 5 });
+          const allResults = [
+            ...results.events.map(e => ({ source: e.kind === "message_in" ? "You" : "Agent", snippet: e.snippet, ts: e.ts })),
+            ...results.summaries.map(s => ({ source: "Summary", snippet: s.snippet })),
+          ];
+          if (allResults.length === 0) {
+            return { action: "command", command: "search", reply: `No results for "${query}".` };
+          }
+          const lines = allResults.slice(0, 3).map((r, i) =>
+            `${i + 1}. [${r.source}] ${r.snippet}`
+          );
+          const reply = [`🔍 Results for "${query}":`, ...lines].join("\n");
+          return { action: "command", command: "search", reply };
+        } catch (err) {
+          this.logger.error(`[telegram-inbound] /search failed: ${err.message}`);
+          return { action: "command", command: "search", reply: "Search failed. Try again." };
+        }
+      }
+
+      case "/help": {
+        const showAll = parts[1]?.toLowerCase() === "all";
+        return { action: "command", command: "help", reply: formatTelegramHelp(showAll) };
+      }
+
+      case "/approve": {
+        const idStr = parts[1];
+        const id = parseInt(idStr, 10);
+        if (!idStr || isNaN(id)) {
+          return { action: "command", command: "approve", reply: "Usage: /approve <id>" };
+        }
+        if (!this.repairLog || !this.ruleStaging) {
+          return { action: "command", command: "approve", reply: "Self-healing system not available." };
+        }
+        const approveResult = handleApproveCommand(id, this.repairLog, this.ruleStaging);
+        if (!approveResult.found) {
+          return { action: "command", command: "approve", reply: `No held update or pending rule found with ID ${id}.` };
+        }
+        if (approveResult.needsNurseJob) {
+          this.queueNurseJob?.();
+          return { action: "command", command: "approve", reply: `Approved held update #${id}. Nurse job queued to apply it.` };
+        }
+        return { action: "command", command: "approve", reply: `Rule #${id} approved.` };
+      }
+
+      case "/health": {
+        if (!this.repairLog) {
+          return { action: "command", command: "health", reply: "Self-healing system not available." };
+        }
+        const healthReport = handleHealthCommand(this.repairLog);
+        return { action: "command", command: "health", reply: healthReport };
+      }
+
+      case "/clear-repairs":
+      case "/clear_repairs": {
+        if (!this.repairLog) {
+          return { action: "command", command: "clear-repairs", reply: "Self-healing system not available." };
+        }
+        const clearResult = handleClearRepairsCommand(this.repairLog);
+        return { action: "command", command: "clear-repairs", reply: clearResult };
+      }
+
+      case "/exec_approve": {
+        const approveId = parts[1];
+        if (!approveId) {
+          return { action: "command", command: "exec_approve", reply: "Usage: /exec_approve <id>" };
+        }
+        const gate = this._getExecApprovalGate();
+        const resolved = gate.resolve(approveId, true, "operator");
+        return { action: "command", command: "exec_approve", reply: resolved ? `Approved exec action ${approveId}.` : `No pending approval found with ID ${approveId}.` };
+      }
+
+      case "/exec_deny": {
+        const denyId = parts[1];
+        if (!denyId) {
+          return { action: "command", command: "exec_deny", reply: "Usage: /exec_deny <id>" };
+        }
+        const denyGate = this._getExecApprovalGate();
+        const denied = denyGate.resolve(denyId, false, "operator");
+        return { action: "command", command: "exec_deny", reply: denied ? `Denied exec action ${denyId}.` : `No pending approval found with ID ${denyId}.` };
+      }
+
+      default:
+        return null; // unknown /command — treat as normal message
+    }
+  }
+
+  _getExecApprovalGate() {
+    if (!this._execApprovalGate) {
+      const chatId = this.operatorChatId;
+      const token = this.botToken;
+      this._execApprovalGate = new ExecApprovalGate({
+        sendFn: async (text) => {
+          if (!chatId || !token) return;
+          const fetchFn = this.deps?.fetchImpl || globalThis.fetch;
+          await fetchFn(`https://api.telegram.org/bot${token}/sendMessage`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ chat_id: chatId, text }),
+          });
+        },
+      });
+    }
+    return this._execApprovalGate;
+  }
+
+  getExecApprovalGate() {
+    return this._getExecApprovalGate();
+  }
+}