@wrongstack/telegram 0.287.0 → 0.291.0

package/dist/index.js

@@ -1,15 +1,266 @@
 // src/index.ts
 import { expectDefined as expectDefined2 } from "@wrongstack/core";
 
-// src/bot.ts
-import { sleep } from "@wrongstack/core/utils";
-function redactToken(url, token) {
-  return url.replace(token, "[REDACTED]");
+// src/api-client.ts
+var TelegramApiClientError = class extends Error {
+  kind;
+  method;
+  constructor(kind, method, message) {
+    super(message);
+    this.kind = kind;
+    this.method = method;
+  }
+};
+var TelegramNetworkError = class extends TelegramApiClientError {
+  detail;
+  aborted;
+  constructor(method, detail, aborted = false) {
+    super("network", method, `Telegram network error during ${method}: ${detail}`);
+    this.name = "TelegramNetworkError";
+    this.detail = detail;
+    this.aborted = aborted;
+  }
+};
+var TelegramHttpError = class extends TelegramApiClientError {
+  status;
+  constructor(method, status, statusText) {
+    const suffix = statusText ? ` ${statusText}` : "";
+    super("http", method, `Telegram HTTP error during ${method}: ${status}${suffix}`);
+    this.name = "TelegramHttpError";
+    this.status = status;
+  }
+};
+var TelegramResponseParseError = class extends TelegramApiClientError {
+  constructor(method, detail) {
+    super("parse", method, `Telegram response parse error during ${method}: ${detail}`);
+    this.name = "TelegramResponseParseError";
+  }
+};
+var TelegramBotApiError = class extends TelegramApiClientError {
+  errorCode;
+  httpStatus;
+  description;
+  retryAfterSeconds;
+  migrateToChatId;
+  constructor(method, opts) {
+    const code = opts.errorCode === void 0 ? "unknown" : String(opts.errorCode);
+    super("api", method, `Telegram API error ${code} during ${method}: ${opts.description}`);
+    this.name = "TelegramBotApiError";
+    this.errorCode = opts.errorCode;
+    this.httpStatus = opts.httpStatus;
+    this.description = opts.description;
+    this.retryAfterSeconds = opts.retryAfterSeconds;
+    this.migrateToChatId = opts.migrateToChatId;
+  }
+};
+var BACKOFF_BASE_MS = 1e3;
+var BACKOFF_MAX_MS = 3e4;
+function classifyRetry(err, attempt) {
+  if (attempt >= 3) return { retry: false, delayMs: 0 };
+  if (err instanceof TelegramHttpError) {
+    if (err.status === 429 || err.status === 409 || err.status >= 500) {
+      const delayMs2 = Math.min(
+        Math.ceil(BACKOFF_BASE_MS * 2 ** (attempt - 1) * (1 + Math.random() * 0.2)),
+        BACKOFF_MAX_MS
+      );
+      return { retry: true, delayMs: delayMs2 };
+    }
+    return { retry: false, delayMs: 0 };
+  }
+  if (err instanceof TelegramResponseParseError) return { retry: false, delayMs: 0 };
+  if (err instanceof TelegramNetworkError && err.aborted) return { retry: false, delayMs: 0 };
+  if (err instanceof TelegramBotApiError) {
+    const code = err.errorCode;
+    if (code !== void 0 && code >= 400 && code < 500 && code !== 429 && code !== 409) {
+      return { retry: false, delayMs: 0 };
+    }
+    if (code === 429) {
+      const baseDelay = err.retryAfterSeconds !== void 0 ? err.retryAfterSeconds * 1e3 : BACKOFF_BASE_MS * 2 ** (attempt - 1);
+      const delayMs2 = Math.min(Math.ceil(baseDelay * (1 + Math.random() * 0.3)), BACKOFF_MAX_MS);
+      return { retry: true, delayMs: delayMs2 };
+    }
+    if (code === 409) {
+      const delayMs2 = Math.min(BACKOFF_BASE_MS * 2 ** (attempt - 1), BACKOFF_MAX_MS);
+      return { retry: true, delayMs: delayMs2 };
+    }
+    if (code !== void 0 && code >= 500) {
+      const delayMs2 = Math.min(
+        Math.ceil(BACKOFF_BASE_MS * 2 ** (attempt - 1) * (1 + Math.random() * 0.2)),
+        BACKOFF_MAX_MS
+      );
+      return { retry: true, delayMs: delayMs2 };
+    }
+    if (code === void 0) {
+      const delayMs2 = Math.min(BACKOFF_BASE_MS * 2 ** (attempt - 1), BACKOFF_MAX_MS);
+      return { retry: true, delayMs: delayMs2 };
+    }
+  }
+  const delayMs = Math.min(
+    Math.ceil(BACKOFF_BASE_MS * 2 ** (attempt - 1) * (1 + Math.random() * 0.3)),
+    BACKOFF_MAX_MS
+  );
+  return { retry: true, delayMs };
 }
-var TelegramBot = class _TelegramBot {
-  baseUrl;
-  /** Base URL with token redacted, safe to use in log calls. */
+function buildTelegramBotApiBaseUrl(token, apiRoot = "https://api.telegram.org") {
+  return `${apiRoot.replace(/\/+$/, "")}/bot${token}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function abortableSleep(ms, signal) {
+  if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new DOMException("The operation was aborted", "AbortError"));
+      return;
+    }
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      reject(new DOMException("The operation was aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function errorDetail(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+function composedSignal(signal, deadlineMs) {
+  if (deadlineMs !== void 0 && signal) {
+    return AbortSignal.any([signal, AbortSignal.timeout(deadlineMs)]);
+  }
+  if (deadlineMs !== void 0) return AbortSignal.timeout(deadlineMs);
+  return signal;
+}
+var TelegramApiClient = class {
   safeBaseUrl;
+  token;
+  baseUrl;
+  fetchOverride;
+  constructor(opts) {
+    this.token = opts.token;
+    this.baseUrl = buildTelegramBotApiBaseUrl(opts.token, opts.apiRoot);
+    this.safeBaseUrl = this.redact(this.baseUrl);
+    this.fetchOverride = opts.fetch;
+  }
+  getMe(opts) {
+    return this.request("getMe", { signal: composedSignal(opts?.signal) });
+  }
+  getUpdates(opts) {
+    const query = new URLSearchParams({
+      offset: String(opts.offset),
+      timeout: String(opts.timeoutSeconds)
+    });
+    return this.request("getUpdates", {
+      query,
+      signal: composedSignal(opts.signal, opts.deadlineMs)
+    });
+  }
+  sendMessage(chatId, text, opts) {
+    return this.request("sendMessage", {
+      body: {
+        chat_id: String(chatId),
+        text,
+        disable_web_page_preview: true
+      },
+      signal: composedSignal(opts?.signal)
+    });
+  }
+  sendMessageWithKeyboard(chatId, text, buttons, opts) {
+    return this.request("sendMessage", {
+      body: {
+        chat_id: String(chatId),
+        text,
+        disable_web_page_preview: true,
+        reply_markup: {
+          inline_keyboard: [
+            buttons.map((button) => ({
+              text: button.text,
+              callback_data: button.callback_data
+            }))
+          ]
+        }
+      },
+      signal: composedSignal(opts?.signal)
+    });
+  }
+  answerCallbackQuery(callbackQueryId, text, showAlert, opts) {
+    return this.request("answerCallbackQuery", {
+      body: {
+        callback_query_id: callbackQueryId,
+        text,
+        show_alert: showAlert
+      },
+      signal: composedSignal(opts?.signal)
+    });
+  }
+  async request(method, opts) {
+    const query = opts?.query?.toString();
+    const url = `${this.baseUrl}/${method}${query ? `?${query}` : ""}`;
+    const init = {
+      method: opts?.body ? "POST" : "GET"
+    };
+    if (opts?.signal) init.signal = opts.signal;
+    if (opts?.body) {
+      init.headers = { "Content-Type": "application/json" };
+      init.body = JSON.stringify(opts.body);
+    }
+    let response;
+    try {
+      const fetchImpl = this.fetchOverride ?? globalThis.fetch;
+      response = await fetchImpl(url, init);
+    } catch (error) {
+      const detail = this.redact(errorDetail(error));
+      const aborted = error instanceof Error && error.name === "AbortError";
+      throw new TelegramNetworkError(method, detail, aborted);
+    }
+    let decoded;
+    try {
+      decoded = await response.json();
+    } catch (error) {
+      if (!response.ok) {
+        throw new TelegramHttpError(method, response.status, this.redact(response.statusText));
+      }
+      throw new TelegramResponseParseError(method, this.redact(errorDetail(error)));
+    }
+    if (!isRecord(decoded) || typeof decoded.ok !== "boolean") {
+      if (!response.ok) {
+        throw new TelegramHttpError(method, response.status, this.redact(response.statusText));
+      }
+      throw new TelegramResponseParseError(method, "expected a Bot API response envelope");
+    }
+    const envelope = decoded;
+    if (!envelope.ok) {
+      throw new TelegramBotApiError(method, {
+        errorCode: envelope.error_code,
+        httpStatus: response.status,
+        description: this.redact(envelope.description ?? "Unknown Bot API error"),
+        retryAfterSeconds: envelope.parameters?.retry_after,
+        migrateToChatId: envelope.parameters?.migrate_to_chat_id
+      });
+    }
+    if (!response.ok) {
+      throw new TelegramHttpError(method, response.status, this.redact(response.statusText));
+    }
+    if (envelope.result === void 0 || envelope.result === null) {
+      throw new TelegramResponseParseError(method, "successful response did not include result");
+    }
+    return envelope.result;
+  }
+  redact(value) {
+    return value.replaceAll(this.token, "[REDACTED]");
+  }
+};
+
+// src/bot.ts
+var TelegramBot = class _TelegramBot {
+  api;
   pollIntervalMs;
   allowedUsers;
   allowedChats;
@@ -30,8 +281,8 @@ var TelegramBot = class _TelegramBot {
   static CONFLICT_BACKOFF_AFTER = 3;
   static CONFLICT_POLL_MS = 6e4;
   _startedAt = null;
-  /** If set, the offset is persisted here after each successful poll. */
-  offsetStoragePath;
+  /** Typed offset store for atomic polling-cursor persistence. */
+  offsetStore;
   /** Single-poller election across wstack instances sharing this token. */
   lock;
   standbyRetryMs;
@@ -40,26 +291,25 @@ var TelegramBot = class _TelegramBot {
   // Circular buffer for incoming messages
   bufferMax;
   buffer = [];
-  // Pending callback_query waiters keyed by the `data` string they
-  // registered. Cleared on stop(). Used by `telegram_approve` to bridge a
-  // synchronous-looking API onto the async callback event.
+  // Pending approval requests keyed by request identity, not raw callback
+  // data. Each request binds both yes/no actions to its originating session,
+  // target chat, intended users, prompt message, and expiry.
   callbackWaiters = /* @__PURE__ */ new Map();
   constructor(opts) {
-    this.baseUrl = `https://api.telegram.org/bot${opts.token}`;
-    this.safeBaseUrl = redactToken(this.baseUrl, opts.token);
+    this.api = new TelegramApiClient({ token: opts.token });
     this.pollIntervalMs = opts.pollIntervalSec * 1e3;
     this.allowedUsers = opts.allowedUsers;
     this.allowedChats = opts.allowedChats;
     this.bufferMax = opts.bufferSize;
     this.log = opts.log;
     this.onMessage = opts.onMessage;
-    this.offsetStoragePath = opts.offsetStoragePath;
+    this.offsetStore = opts.offsetStore;
     this.lock = opts.lock;
     this.standbyRetryMs = opts.standbyRetryMs ?? 15e3;
     if (this.lock) {
       this.lock.onLost = () => this.handleLockLost();
     }
-    if (this.offsetStoragePath) {
+    if (this.offsetStore) {
       void this.loadOffset();
     }
   }
@@ -85,8 +335,11 @@ var TelegramBot = class _TelegramBot {
       clearTimeout(this.standbyTimer);
       this.standbyTimer = null;
     }
-    for (const key of Array.from(this.callbackWaiters.keys())) {
-      this.rejectWaiter(key, "shutdown");
+    for (const requestId of Array.from(this.callbackWaiters.keys())) {
+      this.settleApproval(requestId, "cancelled", {
+        approved: false,
+        fromUser: "shutdown"
+      });
     }
     this.lock?.release();
     this.log.info("Telegram bot stopped");
@@ -116,7 +369,7 @@ var TelegramBot = class _TelegramBot {
       this.standbyAnnounced = false;
       this.log.info("Telegram: poll lock acquired \u2014 taking over polling.");
     } else {
-      this.log.info(`Telegram bot polling started (${this.safeBaseUrl})`);
+      this.log.info(`Telegram bot polling started (${this.api.safeBaseUrl})`);
     }
     this.schedulePoll();
   }
@@ -127,7 +380,9 @@ var TelegramBot = class _TelegramBot {
       clearTimeout(this.pollTimer);
       this.pollTimer = null;
     }
-    this.log.warn("Telegram: poll lock lost to another instance \u2014 pausing polling and standing by.");
+    this.log.warn(
+      "Telegram: poll lock lost to another instance \u2014 pausing polling and standing by."
+    );
     this.standbyAnnounced = true;
     this.standbyTimer = setTimeout(() => this.acquireAndPoll(), this.standbyRetryMs);
     this.standbyTimer.unref?.();
@@ -170,34 +425,30 @@ var TelegramBot = class _TelegramBot {
   // ------------------------------------------------------------------
   // Outgoing — send a message
   // ------------------------------------------------------------------
-  async sendMessage(chatId, text) {
-    const url = `${this.baseUrl}/sendMessage`;
-    const body = JSON.stringify({
-      chat_id: String(chatId),
-      text,
-      disable_web_page_preview: true
-    });
+  async sendMessage(chatId, text, signal) {
     this.log.debug(`Sending Telegram message to ${chatId} (${text.length} chars)`);
     let lastErr;
     for (let attempt = 1; attempt <= 3; attempt++) {
       try {
-        const res = await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body,
-          signal: AbortSignal.timeout(1e4)
+        const timeout = AbortSignal.timeout(1e4);
+        const result = await this.api.sendMessage(chatId, text, {
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout
         });
-        const data = await res.json();
-        if (!data.ok) {
-          throw new Error(`Telegram API error ${data.error_code}: ${data.description}`);
-        }
-        return data;
+        return { ok: true, result };
       } catch (err) {
         lastErr = err;
-        if (attempt < 3) {
-          this.log.debug(`Telegram sendMessage attempt ${attempt} failed, retrying in 1s...`);
-          await sleep(1e3);
+        const decision = classifyRetry(err, attempt);
+        if (!decision.retry) {
+          if (attempt > 1)
+            this.log.debug(
+              `Telegram sendMessage terminal error on attempt ${attempt}, not retrying`
+            );
+          break;
         }
+        this.log.debug(
+          `Telegram sendMessage attempt ${attempt} failed, retrying in ${decision.delayMs}ms...`
+        );
+        await abortableSleep(decision.delayMs, signal);
       }
     }
     throw lastErr;
@@ -211,33 +462,26 @@ var TelegramBot = class _TelegramBot {
    * yes/no prompt. The keyboard payload is opaque to the bot — callers
    * pass already-encoded `callback_data` strings (≤ 64 bytes each).
    */
-  async sendMessageWithKeyboard(chatId, text, buttons) {
-    const url = `${this.baseUrl}/sendMessage`;
-    const body = JSON.stringify({
-      chat_id: String(chatId),
-      text,
-      disable_web_page_preview: true,
-      reply_markup: {
-        inline_keyboard: [buttons.map((b) => ({ text: b.text, callback_data: b.callback_data }))]
-      }
-    });
+  async sendMessageWithKeyboard(chatId, text, buttons, signal) {
     let lastErr;
     for (let attempt = 1; attempt <= 3; attempt++) {
       try {
-        const res = await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body,
-          signal: AbortSignal.timeout(1e4)
+        const timeout = AbortSignal.timeout(1e4);
+        const result = await this.api.sendMessageWithKeyboard(chatId, text, buttons, {
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout
         });
-        const data = await res.json();
-        if (!data.ok) {
-          throw new Error(`Telegram API error ${data.error_code}: ${data.description}`);
-        }
-        return data;
+        return { ok: true, result };
       } catch (err) {
         lastErr = err;
-        if (attempt < 3) await sleep(1e3);
+        const decision = classifyRetry(err, attempt);
+        if (!decision.retry) {
+          if (attempt > 1)
+            this.log.debug(
+              `Telegram sendMessageWithKeyboard terminal error on attempt ${attempt}, not retrying`
+            );
+          break;
+        }
+        await abortableSleep(decision.delayMs, signal);
       }
     }
     throw lastErr;
@@ -245,18 +489,18 @@ var TelegramBot = class _TelegramBot {
   // ------------------------------------------------------------------
   // Health
   // ------------------------------------------------------------------
-  async health() {
+  async health(signal) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), 5e3);
     try {
-      const url = `${this.baseUrl}/getMe`;
-      const res = await fetch(url, { signal: ctrl.signal });
-      const data = await res.json();
-      if (!data.ok || !data.result) {
-        return { ok: false, error: data.description ?? "Unknown error" };
-      }
-      return { ok: true, username: data.result.username };
+      const timeout = AbortSignal.timeout(5e3);
+      const deadline = AbortSignal.any([ctrl.signal, timeout]);
+      const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+      const user = await this.api.getMe({ signal: combined });
+      return { ok: true, username: user.username };
     } catch (err) {
+      if (err instanceof TelegramBotApiError) return { ok: false, error: err.description };
+      if (err instanceof TelegramNetworkError) return { ok: false, error: err.detail };
       return { ok: false, error: err.message };
     } finally {
       clearTimeout(timer);
@@ -275,23 +519,13 @@ var TelegramBot = class _TelegramBot {
   }
   async poll() {
     try {
-      const url = `${this.baseUrl}/getUpdates?offset=${this.offset}&timeout=10`;
-      const res = await fetch(url, { signal: this.controller.signal });
-      const data = await res.json();
-      if (!data.ok) {
-        if (data.error_code === 409) {
-          this.conflictStreak++;
-          if (this.conflictStreak === _TelegramBot.CONFLICT_BACKOFF_AFTER) {
-            this.log.warn(
-              this.lock ? "Telegram: another consumer outside this machine is polling this bot token (HTTP 409) \u2014 backing off to 60s polls. Check other machines/bots using this token, or a registered webhook (deleteWebhook)." : "Telegram: another instance is polling this bot token (HTTP 409) \u2014 backing off to 60s polls until it stops."
-            );
-          }
-        }
-        this.log.debug(`Telegram getUpdates failed: ${data.description}`);
-        return;
-      }
+      const updates = await this.api.getUpdates({
+        offset: this.offset,
+        timeoutSeconds: 10,
+        deadlineMs: 15e3,
+        signal: this.controller.signal
+      });
       this.conflictStreak = 0;
-      const updates = data.result ?? [];
       for (const upd of updates) {
         this.offset = upd.update_id + 1;
         if (upd.callback_query) {
@@ -300,26 +534,48 @@ var TelegramBot = class _TelegramBot {
         }
         const raw = upd.message ?? upd.edited_message;
         if (!raw?.text) continue;
-        const msg = { ...raw, text: raw.text };
-        this.processMessage(msg);
-      }
-      if (this.offsetStoragePath && this.offset > 0) {
-        void this.saveOffset();
+        this.processMessage({ ...raw, text: raw.text });
       }
+      if (this.offsetStore && updates.length > 0) void this.saveOffset();
     } catch (err) {
-      if (err.name === "AbortError") return;
+      if (err instanceof TelegramNetworkError && err.aborted) return;
+      if (err instanceof TelegramBotApiError && err.errorCode === 409) {
+        this.conflictStreak++;
+        if (this.conflictStreak === _TelegramBot.CONFLICT_BACKOFF_AFTER) {
+          this.log.warn(
+            this.lock ? "Telegram: another consumer outside this machine is polling this bot token (HTTP 409) \u2014 backing off to 60s polls. Check other machines/bots using this token, or a registered webhook (deleteWebhook)." : "Telegram: another instance is polling this bot token (HTTP 409) \u2014 backing off to 60s polls until it stops."
+          );
+        }
+        this.log.debug(`Telegram getUpdates failed: ${err.description}`);
+        return;
+      }
       this.log.debug(`Telegram poll error: ${err.message}`);
     }
   }
+  /**
+   * Apply the inbound identity policy to every update type. A non-empty set is
+   * a mandatory constraint: missing identity fails closed instead of bypassing
+   * the allowlist. An empty set leaves that identity dimension unrestricted.
+   */
+  inboundDenialReason(userId, chatId) {
+    if (this.allowedChats.size > 0 && (chatId === void 0 || !this.allowedChats.has(chatId))) {
+      return "chat";
+    }
+    if (this.allowedUsers.size > 0 && (userId === void 0 || !this.allowedUsers.has(userId))) {
+      return "user";
+    }
+    return void 0;
+  }
   processMessage(msg) {
     const chatId = String(msg.chat.id);
     const userId = msg.from ? String(msg.from.id) : void 0;
-    if (this.allowedUsers.size > 0 && userId && !this.allowedUsers.has(userId)) {
-      this.log.debug(`Ignoring message from user ${userId} (not in allowedUsers)`);
+    const denialReason = this.inboundDenialReason(userId, chatId);
+    if (denialReason === "user") {
+      this.log.debug(`Ignoring message from user ${userId ?? "unknown"} (not in allowedUsers)`);
       void this.sendMessage(chatId, "\u26D4 You are not authorized to interact with this bot.");
       return;
     }
-    if (this.allowedChats.size > 0 && !this.allowedChats.has(chatId)) {
+    if (denialReason === "chat") {
       this.log.debug(`Ignoring message from chat ${chatId} (not in allowedChats)`);
       return;
     }
@@ -337,59 +593,74 @@ var TelegramBot = class _TelegramBot {
     this.onMessage(incoming);
   }
   /**
-   * Handle an inbound `callback_query` update: route it to a registered
-   * waiter (if any), and acknowledge it via `answerCallbackQuery` so the
-   * client stops spinning. Telegram requires the answer within 10 s.
-   */
-  /**
-   * Resolve any pending waiter for `key` with a `{ approved: false, fromUser }`
-   * value, regardless of why the callback was rejected (allowlist, shutdown,
-   * etc.). Returns true if a waiter was found and resolved, false otherwise.
-   * This helper centralizes the race-safe `delete → resolve` pattern in one
-   * place so the deny and shutdown paths don't drift out of sync.
+   * Resolve a pending approval request exactly once and record its terminal
+   * state before removing it from the live registry.
    */
-  rejectWaiter(key, fromUser) {
-    if (key === "") return false;
-    const waiter = this.callbackWaiters.get(key);
-    if (!waiter) return false;
-    clearTimeout(waiter.timer);
-    this.callbackWaiters.delete(key);
-    waiter.resolve({ approved: false, fromUser });
+  settleApproval(requestId, state, result) {
+    const request = this.callbackWaiters.get(requestId);
+    if (request?.state !== "pending") return false;
+    request.state = state;
+    clearTimeout(request.timer);
+    if (request.signal && request.abortHandler) {
+      request.signal.removeEventListener("abort", request.abortHandler);
+    }
+    request.pendingCallbacks.length = 0;
+    this.callbackWaiters.delete(requestId);
+    request.resolve(result);
     return true;
   }
   async dispatchCallback(cq) {
     const key = cq.data ?? "";
-    if (cq.from) {
-      const userId = String(cq.from.id);
-      if (this.allowedUsers.size > 0 && !this.allowedUsers.has(userId)) {
-        this.log.warn(
-          `Ignoring callback_query from non-allowlisted user ${userId} (data="${key}") \u2014 possible hijack attempt.`
-        );
-        await this.answerCallback(cq.id, "\u26D4 Not authorized", true);
-        this.rejectWaiter(key, "blocked");
-        return;
-      }
-    }
+    const action = /^approve:([^:]+):(yes|no)$/.exec(key);
+    const requestId = action?.[1];
+    const request = requestId ? this.callbackWaiters.get(requestId) : void 0;
+    const userId = cq.from?.id !== void 0 ? String(cq.from.id) : void 0;
     const chatId = cq.message?.chat.id !== void 0 ? String(cq.message.chat.id) : void 0;
-    if (chatId !== void 0 && this.allowedChats.size > 0 && !this.allowedChats.has(chatId)) {
+    const denialReason = this.inboundDenialReason(userId, chatId);
+    if (denialReason) {
+      const identity = denialReason === "user" ? userId ?? "unknown" : chatId ?? "unknown";
       this.log.warn(
-        `Ignoring callback_query from non-allowlisted chat ${chatId} (data="${key}") \u2014 possible hijack attempt.`
+        `Ignoring callback_query from non-allowlisted ${denialReason} ${identity} (data="${key}") \u2014 possible hijack attempt.`
       );
       await this.answerCallback(cq.id, "\u26D4 Not authorized", true);
-      this.rejectWaiter(key, "blocked");
       return;
     }
-    const waiter = key !== "" ? this.callbackWaiters.get(key) : void 0;
-    const approved = key.endsWith(":yes");
-    const fromUser = cq.from?.username ?? cq.from?.first_name ?? "unknown";
-    await this.answerCallback(cq.id, approved ? "Approved \u2713" : "Denied \u2717", false);
-    if (waiter) {
-      clearTimeout(waiter.timer);
-      this.callbackWaiters.delete(key);
-      waiter.resolve({ approved, fromUser });
-    } else {
-      this.log.debug(`Unmatched callback_query data="${key}" (no pending waiter)`);
+    if (!request || !requestId || !action) {
+      await this.answerCallback(cq.id, "Approval request unavailable", true);
+      this.log.debug(`Unmatched callback_query data="${key}" (no pending approval request)`);
+      return;
+    }
+    if (Date.now() >= request.expiresAt) {
+      await this.answerCallback(cq.id, "Approval request expired", true);
+      this.settleApproval(requestId, "expired", { approved: false, fromUser: "timeout" });
+      return;
+    }
+    if (request.promptMessageId === void 0) {
+      request.pendingCallbacks.push(cq);
+      return;
     }
+    const messageId = cq.message?.message_id;
+    const chatType = cq.message?.chat.type;
+    const wrongIdentity = userId === void 0 || chatId !== request.expectedChatId || !request.expectedUserIds.has(userId) || messageId !== request.promptMessageId || chatType !== "private" && !request.allowGroup;
+    if (wrongIdentity) {
+      this.log.warn(
+        `Ignoring callback_query that does not match approval request ${request.requestId} in session ${request.sessionId}.`
+      );
+      await this.answerCallback(cq.id, "\u26D4 Not authorized for this approval", true);
+      return;
+    }
+    const approved = action[2] === "yes";
+    const fromUser = cq.from?.username ?? cq.from?.first_name ?? `user:${userId}`;
+    const resolved = this.settleApproval(requestId, "resolved", {
+      approved,
+      fromUser,
+      fromUserId: cq.from?.id
+    });
+    await this.answerCallback(
+      cq.id,
+      resolved ? approved ? "Approved \u2713" : "Denied \u2717" : "Approval request unavailable",
+      !resolved
+    );
   }
   /**
    * POST /answerCallbackQuery for a callback. Best-effort: failures are
@@ -399,14 +670,7 @@ var TelegramBot = class _TelegramBot {
    */
   async answerCallback(callbackQueryId, text, showAlert) {
     try {
-      await fetch(`${this.baseUrl}/answerCallbackQuery`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          callback_query_id: callbackQueryId,
-          text,
-          show_alert: showAlert
-        }),
+      await this.api.answerCallbackQuery(callbackQueryId, text, showAlert, {
         signal: AbortSignal.timeout(5e3)
       });
     } catch (err) {
@@ -414,51 +678,99 @@ var TelegramBot = class _TelegramBot {
     }
   }
   /**
-   * Register a waiter for a callback_query whose `data` field equals `key`.
-   * Resolves with `{ approved, fromUser }` when a matching press arrives, or
-   * with `{ approved: false, fromUser: 'timeout' }` after `timeoutMs`.
-   *
-   * Callers are responsible for not registering the same key twice — a
-   * second `awaitCallback` for an in-flight key is undefined.
+   * Register one approval request before its prompt is sent. The returned
+   * promise owns the request's only timer and resolves on one terminal event.
    */
-  awaitCallback(key, timeoutMs) {
+  awaitApproval(input) {
+    if (input.expectedUserIds.length === 0) {
+      throw new Error("Telegram approval requires at least one expected user ID.");
+    }
+    if (this.callbackWaiters.has(input.requestId)) {
+      throw new Error(`Telegram approval request ${input.requestId} is already pending.`);
+    }
     return new Promise((resolve) => {
+      const delayMs = Math.max(0, input.expiresAt - Date.now());
       const timer = setTimeout(() => {
-        if (this.callbackWaiters.delete(key)) {
-          resolve({ approved: false, fromUser: "timeout" });
-        }
-      }, timeoutMs);
-      this.callbackWaiters.set(key, { resolve, timer });
+        this.settleApproval(input.requestId, "expired", {
+          approved: false,
+          fromUser: "timeout"
+        });
+      }, delayMs);
+      const request = {
+        requestId: input.requestId,
+        sessionId: input.sessionId,
+        expectedChatId: String(input.expectedChatId),
+        expectedUserIds: new Set(input.expectedUserIds.map(String)),
+        allowGroup: input.allowGroup,
+        pendingCallbacks: [],
+        expiresAt: input.expiresAt,
+        state: "pending",
+        resolve,
+        timer,
+        signal: input.signal
+      };
+      if (input.signal) {
+        request.abortHandler = () => {
+          this.settleApproval(input.requestId, "cancelled", {
+            approved: false,
+            fromUser: "aborted"
+          });
+        };
+      }
+      this.callbackWaiters.set(input.requestId, request);
+      if (input.signal?.aborted) {
+        request.abortHandler?.();
+      } else if (input.signal && request.abortHandler) {
+        input.signal.addEventListener("abort", request.abortHandler, { once: true });
+      }
     });
   }
+  /**
+   * Attach the Bot API response's prompt message ID to an existing request.
+   * Any callback that arrived during the send is replayed against the fully
+   * bound identity without allocating a second waiter or timer.
+   */
+  bindApprovalPrompt(requestId, promptMessageId) {
+    const request = this.callbackWaiters.get(requestId);
+    if (request?.state !== "pending" || request.promptMessageId !== void 0) return false;
+    request.promptMessageId = promptMessageId;
+    const pending = request.pendingCallbacks.splice(0);
+    for (const callback of pending) {
+      void this.dispatchCallback(callback);
+    }
+    return true;
+  }
+  /** Cancel a request that cannot reach a valid terminal callback. */
+  cancelApproval(requestId, fromUser = "cancelled") {
+    return this.settleApproval(requestId, "cancelled", { approved: false, fromUser });
+  }
   async loadOffset() {
-    if (!this.offsetStoragePath) return;
+    if (!this.offsetStore) return;
     try {
-      const { readFileSync: readFileSync2 } = await import("node:fs");
-      const raw = readFileSync2(this.offsetStoragePath, "utf8").trim();
-      const n = Number.parseInt(raw, 10);
-      if (Number.isFinite(n) && n >= 0) {
-        this.offset = n;
+      const saved = this.offsetStore.read();
+      if (saved !== null) {
+        this.offset = saved;
         this.log.debug(`Telegram polling offset restored: ${this.offset}`);
       }
     } catch {
     }
   }
   async saveOffset() {
-    if (!this.offsetStoragePath) return;
+    if (!this.offsetStore) return;
     try {
-      const { writeFileSync: writeFileSync2 } = await import("node:fs");
-      writeFileSync2(this.offsetStoragePath, String(this.offset), "utf8");
+      this.offsetStore.write(this.offset);
     } catch (err) {
       this.log.debug(`Failed to persist Telegram offset: ${err}`);
     }
   }
 };
+var MAX_TELEGRAM_MESSAGE_LENGTH = 4096;
 function truncateForTelegram(text, maxLen = 4e3) {
-  if (text.length <= maxLen) return text;
-  const cutoff = maxLen - 30;
-  if (cutoff <= 0) return `${text.slice(0, maxLen - 1)}\u2026`;
-  const searchEnd = Math.min(text.length, maxLen);
+  const effectiveMaxLen = Math.min(maxLen, MAX_TELEGRAM_MESSAGE_LENGTH);
+  if (text.length <= effectiveMaxLen) return text;
+  const cutoff = effectiveMaxLen - 30;
+  if (cutoff <= 0) return `${text.slice(0, effectiveMaxLen - 1)}\u2026`;
+  const searchEnd = Math.min(text.length, effectiveMaxLen);
   const paraIdx = text.lastIndexOf("\n\n", searchEnd);
   if (paraIdx > cutoff) {
     return `${text.slice(0, paraIdx)}
@@ -486,20 +798,25 @@ function truncateForTelegram(text, maxLen = 4e3) {
   if (spaceIdx > cutoff) {
     return `${text.slice(0, spaceIdx)} \u2026`;
   }
-  return `${text.slice(0, maxLen - 20)}\u2026[+${text.length - maxLen + 20} chars]`;
+  return `${text.slice(0, effectiveMaxLen - 20)}\u2026[+${text.length - effectiveMaxLen + 20} chars]`;
 }
 
 // src/config.ts
 var PLUGIN_NAME = "telegram";
+var INBOUND_MODES = ["disabled", "paired", "allowlist", "public"];
 var DEFAULT_CONFIG = {
+  inboundMode: "disabled",
   allowedUsers: [],
   allowedChats: [],
+  allowedOutboundChats: [],
   pollIntervalSec: 2,
   notifyOnSessionEnd: false,
   longToolThresholdMs: 3e4,
   notifyOnDelegate: true,
   maxMessageLength: 4e3,
-  singleInstanceLock: true
+  singleInstanceLock: true,
+  outboundQueuePerChat: 32,
+  outboundQueueConcurrency: 4
 };
 var telegramConfigSchema = {
   type: "object",
@@ -509,15 +826,26 @@ var telegramConfigSchema = {
       oneOf: [{ type: "string" }, { type: "integer" }],
       description: "Default chat ID for outgoing notifications"
     },
+    inboundMode: {
+      type: "string",
+      enum: [...INBOUND_MODES],
+      default: "disabled",
+      description: "Inbound access: disabled, paired to notifyChatId, restricted by allowlists, or explicitly public"
+    },
     allowedUsers: {
       type: "array",
       items: { oneOf: [{ type: "string" }, { type: "integer" }] },
-      description: "User IDs allowed to interact with the bot"
+      description: "User IDs accepted when inboundMode is allowlist"
     },
     allowedChats: {
       type: "array",
       items: { oneOf: [{ type: "string" }, { type: "integer" }] },
-      description: "Chat IDs the bot is allowed to read from"
+      description: "Chat IDs accepted when inboundMode is allowlist"
+    },
+    allowedOutboundChats: {
+      type: "array",
+      items: { oneOf: [{ type: "string" }, { type: "integer" }] },
+      description: "Additional trusted targets for outbound Telegram sends"
     },
     pollIntervalSec: {
       type: "integer",
@@ -532,6 +860,18 @@ var telegramConfigSchema = {
     singleInstanceLock: {
       type: "boolean",
       description: "Elect a single getUpdates poller per bot token across wstack instances (default true)"
+    },
+    outboundQueuePerChat: {
+      type: "integer",
+      minimum: 1,
+      maximum: 1e3,
+      description: "Per-chat pending outbound-message cap (default 32)"
+    },
+    outboundQueueConcurrency: {
+      type: "integer",
+      minimum: 1,
+      maximum: 64,
+      description: "Maximum concurrent outbound sends across all chats (default 4)"
     }
   },
   required: ["botToken"]
@@ -543,15 +883,50 @@ function readTelegramConfig(api) {
   const legacyPlugins = pluginEntries;
   const legacyOpts = legacyPlugins && !Array.isArray(legacyPlugins) ? legacyPlugins[PLUGIN_NAME] : void 0;
   const entryOpts = pluginOptionsFromEntries(pluginEntries);
+  const extensionOpts = extensions?.[PLUGIN_NAME];
   const opts = {
     ...legacyOpts ?? entryOpts,
-    ...extensions?.[PLUGIN_NAME] ?? {}
+    ...extensionOpts ?? {}
   };
+  const inboundMode = resolveInboundMode(opts, {
+    configured: legacyOpts !== void 0 || entryOpts !== void 0 || extensionOpts !== void 0,
+    warn: api.log?.warn.bind(api.log)
+  });
   return {
     ...DEFAULT_CONFIG,
-    ...opts
+    ...opts,
+    inboundMode
   };
 }
+function resolveInboundMode(opts, migration) {
+  if (opts.inboundMode !== void 0) {
+    if (!INBOUND_MODES.includes(opts.inboundMode)) {
+      throw new Error(
+        `Invalid telegram inboundMode "${String(opts.inboundMode)}". Expected one of: ${INBOUND_MODES.join(", ")}.`
+      );
+    }
+    if (opts.inboundMode === "allowlist" && !hasEntries(opts.allowedUsers) && !hasEntries(opts.allowedChats)) {
+      throw new Error(
+        'Telegram inboundMode "allowlist" requires at least one allowedUsers or allowedChats entry.'
+      );
+    }
+    if (opts.inboundMode === "paired" && opts.notifyChatId === void 0) {
+      throw new Error('Telegram inboundMode "paired" requires notifyChatId.');
+    }
+    return opts.inboundMode;
+  }
+  if (hasEntries(opts.allowedUsers) || hasEntries(opts.allowedChats)) return "allowlist";
+  const inferredMode = opts.notifyChatId === void 0 ? "disabled" : "paired";
+  if (migration.configured) {
+    migration.warn?.(
+      `Telegram inbound access no longer defaults to public when allowedUsers and allowedChats are empty; inferred inboundMode "${inferredMode}". Set inboundMode "public" explicitly to preserve legacy allow-all behavior.`
+    );
+  }
+  return inferredMode;
+}
+function hasEntries(values) {
+  return Array.isArray(values) && values.length > 0;
+}
 function pluginOptionsFromEntries(entries) {
   if (!Array.isArray(entries)) return void 0;
   const found = entries.find(
@@ -788,6 +1163,130 @@ var PollLock = class {
   }
 };
 
+// src/offset-store.ts
+import { createHash as createHash2 } from "node:crypto";
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync as mkdirSync2,
+  openSync,
+  readFileSync as readFileSync2,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync2,
+  writeSync
+} from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { wstackGlobalRoot as wstackGlobalRoot2 } from "@wrongstack/core/utils";
+function offsetPathForToken(token, globalRoot = wstackGlobalRoot2()) {
+  const hash = createHash2("sha256").update(token).digest("hex").slice(0, 12);
+  return join2(globalRoot, "telegram", `offset-${hash}.json`);
+}
+var OffsetStore = class {
+  path;
+  constructor(opts = {}) {
+    if (opts.path !== void 0) {
+      this.path = opts.path;
+    } else if (opts.token) {
+      this.path = offsetPathForToken(opts.token, opts.globalRoot);
+    } else {
+      this.path = "";
+    }
+  }
+  /** The derived path for diagnostics. */
+  get storePath() {
+    return this.path;
+  }
+  /**
+   * Read the persisted offset. Returns null when the file is missing, empty,
+   * or contains a value that is not a valid non-negative integer.
+   */
+  read() {
+    if (!this.path) return null;
+    let raw;
+    try {
+      raw = readFileSync2(this.path, "utf8").trim();
+    } catch {
+      return null;
+    }
+    if (raw.length === 0) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed < 0 || parsed % 1 !== 0) {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Persist an offset value using an atomic write (temp file + rename).
+   * Creates the parent directory on first call.
+   */
+  write(offset) {
+    if (!this.path || offset < 0) return;
+    mkdirSync2(dirname2(this.path), { recursive: true });
+    const tmp = `${this.path}.${process.pid}.tmp`;
+    const fd = openSync(tmp, "w");
+    try {
+      writeSync(fd, JSON.stringify(offset));
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    try {
+      renameSync2(tmp, this.path);
+    } catch {
+      try {
+        unlinkSync2(tmp);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/security/outbound.ts
+import { DefaultSecretScrubber, ToolValidationError } from "@wrongstack/core";
+var TELEGRAM_APPROVAL_CAPABILITY = "net.outbound.telegram.approval";
+var secretScrubber = new DefaultSecretScrubber();
+var RAW_TELEGRAM_BOT_TOKEN = /(?<![A-Za-z0-9])\d{5,15}:[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/g;
+function normalizeChatId(value) {
+  return String(value).trim();
+}
+function resolveTelegramOutboundTarget(requestedChatId, policy) {
+  const defaultChatId = policy.getDefaultChatId();
+  const target = requestedChatId ?? defaultChatId;
+  if (target === void 0 || normalizeChatId(target) === "") {
+    throw new ToolValidationError({
+      field: "chat_id",
+      message: "No chat_id provided and no allowed Telegram target is configured. Pair notifyChatId or configure allowedOutboundChats."
+    });
+  }
+  const allowed = /* @__PURE__ */ new Set();
+  if (defaultChatId !== void 0 && normalizeChatId(defaultChatId) !== "") {
+    allowed.add(normalizeChatId(defaultChatId));
+  }
+  for (const chatId of policy.getAllowedOutboundChatIds?.() ?? []) {
+    const normalized = normalizeChatId(chatId);
+    if (normalized !== "") allowed.add(normalized);
+  }
+  if (!allowed.has(normalizeChatId(target))) {
+    throw new ToolValidationError({
+      field: "chat_id",
+      message: "Telegram outbound target is not paired or included in allowedOutboundChats."
+    });
+  }
+  return typeof target === "string" ? target.trim() : target;
+}
+function scrubTelegramOutboundText(text) {
+  const shared = secretScrubber.scrub(text);
+  const withoutBareBotTokens = shared.replace(
+    RAW_TELEGRAM_BOT_TOKEN,
+    "[REDACTED:telegram_bot_token]"
+  );
+  return redactSecrets(withoutBareBotTokens);
+}
+
 // src/slash-commands/index.ts
 import { expectDefined } from "@wrongstack/core";
 function tgHealthCommand(bot, cfg) {
@@ -816,7 +1315,8 @@ allowlist health, and notification settings.`,
     }
   };
 }
-function tgSendCommand(bot, defaultChatId) {
+function tgSendCommand(bot, policyOrDefault, outbound) {
+  const policy = typeof policyOrDefault === "object" && policyOrDefault !== null ? policyOrDefault : { getDefaultChatId: () => policyOrDefault };
   return {
     name: "send",
     description: "Send a message to a Telegram chat",
@@ -833,23 +1333,27 @@ Examples:
       if (!args.trim()) {
         return { message: "Usage: /telegram:send [chat_id] <message>" };
       }
-      let chatId;
+      let requestedChatId;
       let text;
       const parts = args.trim().split(/\s+/);
       const maybeId = parts[0];
-      if (/^\d+$/.test(expectDefined(maybeId)) && parts.length > 1) {
-        chatId = expectDefined(maybeId);
+      if (/^-?\d+$/.test(expectDefined(maybeId)) && parts.length > 1) {
+        requestedChatId = expectDefined(maybeId);
         text = parts.slice(1).join(" ");
-      } else if (defaultChatId) {
-        chatId = defaultChatId;
-        text = args.trim();
       } else {
-        return {
-          message: "No chat_id provided and no default notifyChatId configured.\nUsage: /telegram:send <chat_id> <message>"
-        };
+        text = args.trim();
       }
       try {
-        const res = await bot.sendMessage(chatId, text);
+        const chatId = resolveTelegramOutboundTarget(requestedChatId, policy);
+        const scrubbed = scrubTelegramOutboundText(text);
+        const truncated = truncateForTelegram(scrubbed, policy.getMaxMessageLength?.() ?? 4e3);
+        if (outbound) {
+          const res2 = await outbound.sendManual(chatId, truncated);
+          return {
+            message: `\u2705 Message sent to ${chatId} (msg_id=${res2.result?.message_id ?? "?"})`
+          };
+        }
+        const res = await bot.sendMessage(chatId, truncated);
         return {
           message: `\u2705 Message sent to ${chatId} (msg_id=${res.result?.message_id ?? "?"})`
         };
@@ -872,20 +1376,356 @@ and the \`telegram_send\` tool when no chat_id is specified.`,
       if (chatIdStr) {
         return { message: `Configured notifyChatId: ${chatIdStr}` };
       }
-      return { message: "No notifyChatId configured. Set it in the plugin config or pass chat_id explicitly to telegram_send." };
+      return {
+        message: "No notifyChatId configured. Set it in the plugin config or pass chat_id explicitly to telegram_send."
+      };
     }
   };
 }
-function registerSlashCommands(api, bot, cfg) {
-  const cmds = [
-    tgHealthCommand(bot, cfg),
-    tgSendCommand(bot, cfg.notifyChatId),
-    tgChatIdCommand(cfg.notifyChatId)
-  ];
-  for (const cmd of cmds) api.slashCommands.register(cmd);
-  return cmds.map((c) => c.name);
+
+// src/tools/telegram-approve.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+function makeTelegramApproveTool(opts) {
+  return {
+    name: "telegram_approve",
+    description: "Post a scrubbed yes/no prompt only to the paired Telegram chat or an explicitly allowed outbound chat, then wait for a button press. Returns approval state plus immutable user_id and display_name; false means timeout, rejection, or explicit deny. This narrow capability requests remote approval but does not itself authorize or perform the proposed operation.",
+    usageHint: 'telegram_approve(prompt: "Delete build artifacts?", details: "Frees 2.3 GB. Cannot be undone.", timeout_ms: 60000)',
+    category: "Telegram",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          maxLength: 200,
+          description: "Short label for what is being approved. Shown as the prompt heading."
+        },
+        details: {
+          type: "string",
+          maxLength: 1e3,
+          description: "Optional context under the heading."
+        },
+        chat_id: {
+          oneOf: [{ type: "string" }, { type: "integer" }],
+          description: "Chat to post the prompt to. Uses the plugin default when omitted."
+        },
+        timeout_ms: {
+          type: "integer",
+          minimum: 1e3,
+          maximum: 6e5,
+          description: "How long to wait before auto-denying. Default 60 000 ms, max 600 000 ms (10 min)."
+        }
+      },
+      required: ["prompt"]
+    },
+    permission: "auto",
+    mutating: true,
+    riskTier: "standard",
+    capabilities: [TELEGRAM_APPROVAL_CAPABILITY],
+    timeoutMs: 61e4,
+    async execute(input, ctx, toolOpts) {
+      const chatId = resolveTelegramOutboundTarget(input.chat_id, opts);
+      const timeoutMs = Math.min(Math.max(input.timeout_ms ?? 6e4, 1e3), 6e5);
+      const configuredUserIds = opts.getAllowedUserIds?.().map(String) ?? [];
+      const isGroup = String(chatId).startsWith("-");
+      if (isGroup && (opts.allowGroupApprovals !== true || configuredUserIds.length === 0)) {
+        throw new Error("Telegram group approvals require explicit per-user configuration.");
+      }
+      const expectedUserIds = configuredUserIds.length > 0 ? configuredUserIds : [String(chatId)];
+      const requestId = randomUUID2().slice(0, 16);
+      const yesKey = `approve:${requestId}:yes`;
+      const noKey = `approve:${requestId}:no`;
+      const prompt = scrubTelegramOutboundText(input.prompt);
+      const details = input.details ? truncateForTelegram(scrubTelegramOutboundText(input.details), 800) : void 0;
+      const heading = `\u26A0\uFE0F ${prompt}`;
+      const detailsLine = details ? `
+
+${details}` : "";
+      const text = `${heading}${detailsLine}
+
+_Reply by tapping a button. Auto-denies in ${Math.round(timeoutMs / 1e3)}s._`;
+      opts.log.info(`telegram_approve \u2192 chat_id=${chatId} (${prompt.length} prompt chars)`);
+      const approval = opts.bot.awaitApproval({
+        requestId,
+        sessionId: ctx?.session.id ?? "unknown-session",
+        expectedChatId: chatId,
+        expectedUserIds,
+        allowGroup: isGroup && opts.allowGroupApprovals === true,
+        expiresAt: Date.now() + timeoutMs,
+        signal: toolOpts?.signal
+      });
+      let promptMessageId;
+      try {
+        const sent = await opts.bot.sendMessageWithKeyboard(chatId, text, [
+          { text: "\u2705 Approve", callback_data: yesKey },
+          { text: "\u274C Deny", callback_data: noKey }
+        ], toolOpts?.signal);
+        promptMessageId = sent.result?.message_id;
+        if (promptMessageId === void 0) {
+          throw new Error("Telegram approval prompt response did not include a message ID.");
+        }
+        if (!opts.bot.bindApprovalPrompt(requestId, promptMessageId)) {
+          throw new Error("Telegram approval request ended before its prompt could be bound.");
+        }
+      } catch (err) {
+        opts.bot.cancelApproval(requestId, "send-failed");
+        await approval;
+        opts.log.debug(`telegram_approve send failed: ${err.message}`);
+        throw err;
+      }
+      const result = await approval;
+      return {
+        approved: result.approved,
+        user_id: result.fromUserId,
+        display_name: result.fromUser,
+        from: result.fromUser,
+        prompt_message_id: promptMessageId
+      };
+    }
+  };
 }
 
+// src/outbound-queue.ts
+var DEFAULT_MAX_PER_CHAT = 32;
+var DEFAULT_MAX_CONCURRENCY = 4;
+var OutboundQueue = class {
+  #opts;
+  #lanes = /* @__PURE__ */ new Map();
+  #active = 0;
+  #notificationScheduleQueued = false;
+  #stopped = false;
+  #nextId = 0;
+  #enqueued = 0;
+  #sent = 0;
+  #dropped = 0;
+  #failed = 0;
+  #resolvers = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    const maxPerChat = opts.maxPerChat ?? DEFAULT_MAX_PER_CHAT;
+    const maxConcurrency = opts.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+    this.#opts = {
+      maxPerChat,
+      maxConcurrency,
+      send: opts.send,
+      log: opts.log
+    };
+  }
+  /**
+   * Enqueue an outbound send. For manual entries the returned promise
+   * resolves with the send result (or rejects with the send error / the
+   * overflow error). For notification entries the returned promise resolves
+   * as soon as the queue accepts the entry, so callers don't block;
+   * downstream drain failures are logged and counted but do not propagate.
+   */
+  enqueue(entry) {
+    if (this.#stopped) {
+      return Promise.reject(new Error("Outbound queue is stopped"));
+    }
+    const internal = { ...entry, id: this.#mintId() };
+    const key = String(entry.chatId);
+    let lane = this.#lanes.get(key);
+    if (!lane) {
+      lane = { pending: [], running: false };
+      this.#lanes.set(key, lane);
+    }
+    if (entry.kind === "notification") {
+      if (lane.pending.length >= this.#opts.maxPerChat) {
+        const dropped = lane.pending.shift();
+        if (dropped) {
+          this.#dropped += 1;
+          const droppedResolver = this.#resolvers.get(dropped.id);
+          if (droppedResolver) {
+            this.#resolvers.delete(dropped.id);
+            droppedResolver.resolve(void 0);
+          }
+          this.#opts.log?.debug(
+            `Telegram outbound queue dropped a notification for chat ${dropped.chatId} (per-chat limit ${this.#opts.maxPerChat})`
+          );
+        }
+      }
+    } else if (lane.pending.length + (lane.running ? 1 : 0) >= this.#opts.maxPerChat) {
+      return Promise.reject(
+        new Error(
+          `Telegram outbound queue per-chat limit reached for chat ${entry.chatId} (max ${this.#opts.maxPerChat})`
+        )
+      );
+    }
+    lane.pending.push(internal);
+    this.#enqueued += 1;
+    if (entry.kind === "notification") {
+      this.#scheduleNotifications();
+      return Promise.resolve(void 0);
+    }
+    return new Promise((resolve, reject) => {
+      this.#resolvers.set(internal.id, { resolve, reject });
+      this.#schedule();
+    });
+  }
+  /** Stats snapshot for `/telegram-health` and the P3.1 metrics surface. */
+  stats() {
+    let pending = this.#active;
+    for (const lane of this.#lanes.values()) pending += lane.pending.length;
+    return {
+      enqueued: this.#enqueued,
+      sent: this.#sent,
+      dropped: this.#dropped,
+      failed: this.#failed,
+      inflight: this.#active,
+      pending
+    };
+  }
+  /**
+   * Stop accepting new entries. Returns a promise that resolves once all
+   * currently in-flight sends have settled and every per-chat lane is
+   * empty. Pending entries are rejected so their callers don't hang.
+   */
+  async stop() {
+    this.#stopped = true;
+    for (const lane of this.#lanes.values()) {
+      for (const entry of lane.pending.splice(0)) {
+        this.#dropped += 1;
+        const resolver = this.#resolvers.get(entry.id);
+        if (resolver) {
+          this.#resolvers.delete(entry.id);
+          resolver.reject(new Error("Outbound queue stopped before send"));
+        }
+        this.#opts.log?.debug(
+          `Telegram outbound queue stopped, dropped pending ${entry.kind} for chat ${entry.chatId}`
+        );
+      }
+    }
+    while (this.#active > 0) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+  }
+  #mintId() {
+    this.#nextId += 1;
+    return this.#nextId;
+  }
+  #scheduleNotifications() {
+    if (this.#notificationScheduleQueued) return;
+    this.#notificationScheduleQueued = true;
+    queueMicrotask(() => {
+      queueMicrotask(() => {
+        this.#notificationScheduleQueued = false;
+        this.#schedule();
+      });
+    });
+  }
+  #schedule() {
+    if (this.#stopped) return;
+    while (this.#active < this.#opts.maxConcurrency) {
+      const entry = this.#nextReady();
+      if (!entry) return;
+      this.#active += 1;
+      void this.#run(entry);
+    }
+  }
+  #nextReady() {
+    for (const lane of this.#lanes.values()) {
+      if (!lane.running && lane.pending.length > 0) {
+        lane.running = true;
+        return lane.pending.shift();
+      }
+    }
+    return void 0;
+  }
+  async #run(entry) {
+    const key = String(entry.chatId);
+    const lane = this.#lanes.get(key);
+    if (!lane) {
+      const resolver = this.#resolvers.get(entry.id);
+      if (resolver) {
+        this.#resolvers.delete(entry.id);
+        resolver.resolve(void 0);
+      }
+      this.#active -= 1;
+      return;
+    }
+    try {
+      const result = await this.#opts.send(entry.chatId, entry.text);
+      this.#sent += 1;
+      const resolver = this.#resolvers.get(entry.id);
+      if (resolver) {
+        this.#resolvers.delete(entry.id);
+        resolver.resolve(result);
+      }
+    } catch (err) {
+      this.#failed += 1;
+      const resolver = this.#resolvers.get(entry.id);
+      if (resolver) {
+        this.#resolvers.delete(entry.id);
+        resolver.reject(err);
+      } else if (entry.kind === "notification") {
+        this.#opts.log?.debug(
+          `Telegram outbound queue notification failed for chat ${entry.chatId}: ${err.message}`
+        );
+      }
+    } finally {
+      this.#active -= 1;
+      lane.running = false;
+      this.#schedule();
+    }
+  }
+};
+
+// src/bot-queue.ts
+var TelegramBotOutbound = class {
+  #queue;
+  #bot;
+  #log;
+  #stopped = false;
+  constructor(opts) {
+    this.#bot = opts.bot;
+    this.#log = opts.log;
+    this.#queue = new OutboundQueue({
+      maxPerChat: opts.maxPerChat,
+      maxConcurrency: opts.maxConcurrency,
+      send: (chatId, text) => this.#bot.sendMessage(chatId, text).then((res) => {
+        if (!res.ok) {
+          throw new Error(`Telegram outbound send returned ok=false for chat ${chatId}`);
+        }
+        return res;
+      }),
+      log: opts.log
+    });
+  }
+  /** Manual send (telegram_send tool, /telegram:send): never silently dropped. */
+  async sendManual(chatId, text) {
+    if (this.#stopped) {
+      throw new Error("Telegram outbound queue is stopped");
+    }
+    return await this.#queue.enqueue({
+      chatId,
+      text,
+      kind: "manual"
+    });
+  }
+  /**
+   * Notification send (session ended, long tool, delegate): fire-and-forget.
+   * The returned promise resolves as soon as the queue accepts the entry;
+   * downstream send failures are logged and counted but not surfaced.
+   */
+  enqueueNotification(chatId, text) {
+    if (this.#stopped) {
+      this.#log.debug(`Telegram outbound queue ignored notification for chat ${chatId}: stopped`);
+      return;
+    }
+    const entry = { chatId, text, kind: "notification" };
+    this.#queue.enqueue(entry).catch((err) => {
+      this.#log.debug(
+        `Telegram outbound notification enqueue rejected for chat ${chatId}: ${err.message}`
+      );
+    });
+  }
+  stats() {
+    return this.#queue.stats();
+  }
+  async stop() {
+    this.#stopped = true;
+    await this.#queue.stop();
+  }
+};
+
 // src/tools/telegram-read.ts
 function makeTelegramReadTool(opts) {
   return {
@@ -942,10 +1782,11 @@ function makeTelegramReadTool(opts) {
 }
 
 // src/tools/telegram-send.ts
+import { ToolCapabilities } from "@wrongstack/core";
 function makeTelegramSendTool(opts) {
   return {
     name: "telegram_send",
-    description: "Send a message to a Telegram chat. Write the message in natural prose \u2014 a human reads it. Summarize results, state what happened, and include only the key details. Never paste raw JSON, object dumps, or truncated tool output directly into the message field.",
+    description: "Send a scrubbed message to the paired Telegram chat or an explicitly allowed outbound chat. Write natural prose for a human reader; summarize results and never paste raw JSON, object dumps, credentials, or truncated tool output.",
     usageHint: 'telegram_send(chat_id: "123456789", message: "Build completed \u2014 12 tests passed, 0 failed. Deploying to staging now.")',
     category: "Telegram",
     inputSchema: {
@@ -964,17 +1805,14 @@ function makeTelegramSendTool(opts) {
     },
     permission: "confirm",
     mutating: true,
+    capabilities: [ToolCapabilities.NET_OUTBOUND],
     timeoutMs: 15e3,
-    async execute(input, _ctx, _opts) {
-      const chatId = input.chat_id ?? opts.getDefaultChatId();
-      if (!chatId) {
-        throw new Error(
-          "No chat_id provided and no default notifyChatId configured. Set notifyChatId in plugin config or pass chat_id."
-        );
-      }
-      const truncated = truncateForTelegram(input.message, opts.maxMessageLength);
+    async execute(input, _ctx, toolOpts) {
+      const chatId = resolveTelegramOutboundTarget(input.chat_id, opts);
+      const scrubbed = scrubTelegramOutboundText(input.message);
+      const truncated = truncateForTelegram(scrubbed, opts.maxMessageLength);
       opts.log.info(`telegram_send \u2192 chat_id=${chatId} (${truncated.length} chars)`);
-      const res = await opts.bot.sendMessage(chatId, truncated);
+      const res = toolOpts?.signal ? await opts.bot.sendMessage(chatId, truncated, toolOpts.signal) : await opts.bot.sendMessage(chatId, truncated);
       return {
         ok: res.ok,
         message_id: res.result?.message_id,
@@ -988,91 +1826,63 @@ function makeTelegramSendTool(opts) {
   };
 }
 
-// src/tools/telegram-approve.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
-function makeTelegramApproveTool(opts) {
+// src/index.ts
+var teardownState = null;
+var DENY_ALL_INBOUND = "__wrongstack_telegram_inbound_disabled__";
+function inboundAllowlist(cfg) {
+  if (cfg.inboundMode === "public") {
+    return { allowedUsers: /* @__PURE__ */ new Set(), allowedChats: /* @__PURE__ */ new Set() };
+  }
+  if (cfg.inboundMode === "paired") {
+    const pairedUsers = new Set((cfg.allowedUsers ?? []).map(String));
+    return {
+      allowedUsers: pairedUsers.size > 0 ? pairedUsers : /* @__PURE__ */ new Set([String(expectDefined2(cfg.notifyChatId))]),
+      allowedChats: /* @__PURE__ */ new Set([String(expectDefined2(cfg.notifyChatId))])
+    };
+  }
+  if (cfg.inboundMode === "allowlist") {
+    return {
+      allowedUsers: new Set((cfg.allowedUsers ?? []).map(String)),
+      allowedChats: new Set((cfg.allowedChats ?? []).map(String))
+    };
+  }
   return {
-    name: "telegram_approve",
-    description: "Post a yes/no approval prompt to a Telegram chat with inline keyboard buttons, and wait for the user to tap one. Returns { approved, from } where approved=false on timeout or explicit deny. Use this when you need explicit human confirmation before proceeding (destructive ops, irreversible deploys, ambiguous choices).",
-    usageHint: 'telegram_approve(prompt: "Delete build artifacts?", details: "Frees 2.3 GB. Cannot be undone.", timeout_ms: 60000)',
-    category: "Telegram",
-    inputSchema: {
-      type: "object",
-      properties: {
-        prompt: {
-          type: "string",
-          maxLength: 200,
-          description: "Short label for what is being approved. Shown as the prompt heading."
-        },
-        details: {
-          type: "string",
-          maxLength: 1e3,
-          description: "Optional context under the heading."
-        },
-        chat_id: {
-          oneOf: [{ type: "string" }, { type: "integer" }],
-          description: "Chat to post the prompt to. Uses the plugin default when omitted."
-        },
-        timeout_ms: {
-          type: "integer",
-          minimum: 1e3,
-          maximum: 6e5,
-          description: "How long to wait before auto-denying. Default 60 000 ms, max 600 000 ms (10 min)."
-        }
-      },
-      required: ["prompt"]
-    },
-    permission: "auto",
-    mutating: false,
-    timeoutMs: 61e4,
-    async execute(input, _ctx, _toolOpts) {
-      const chatId = input.chat_id ?? opts.getDefaultChatId();
-      if (!chatId) {
-        throw new Error(
-          "No chat_id provided and no default notifyChatId configured. Set notifyChatId in plugin config or pass chat_id."
-        );
-      }
-      const timeoutMs = Math.min(Math.max(input.timeout_ms ?? 6e4, 1e3), 6e5);
-      const token = randomUUID2().slice(0, 16);
-      const yesKey = `approve:${token}:yes`;
-      const noKey = `approve:${token}:no`;
-      const heading = `\u26A0\uFE0F ${input.prompt}`;
-      const detailsLine = input.details ? `
-
-${truncateForTelegram(input.details, 800)}` : "";
-      const text = `${heading}${detailsLine}
-
-_Reply by tapping a button. Auto-denies in ${Math.round(timeoutMs / 1e3)}s._`;
-      opts.log.info(`telegram_approve \u2192 chat_id=${chatId} prompt="${input.prompt.slice(0, 80)}" token=${token}`);
-      let promptMessageId;
-      try {
-        const sent = await opts.bot.sendMessageWithKeyboard(chatId, text, [
-          { text: "\u2705 Approve", callback_data: yesKey },
-          { text: "\u274C Deny", callback_data: noKey }
-        ]);
-        promptMessageId = sent.result?.message_id;
-      } catch (err) {
-        opts.log.debug(`telegram_approve send failed: ${err.message}`);
-      }
-      const result = await Promise.race([
-        opts.bot.awaitCallback(yesKey, timeoutMs),
-        opts.bot.awaitCallback(noKey, timeoutMs)
-      ]);
-      return {
-        approved: result.approved,
-        from: result.fromUser,
-        prompt_message_id: promptMessageId
-      };
-    }
+    allowedUsers: /* @__PURE__ */ new Set([DENY_ALL_INBOUND]),
+    allowedChats: /* @__PURE__ */ new Set([DENY_ALL_INBOUND])
   };
 }
-
-// src/index.ts
-var teardownState = null;
+function runCleanups(cleanups, log) {
+  while (cleanups.length > 0) {
+    const cleanup = cleanups.pop();
+    try {
+      cleanup?.();
+    } catch (err) {
+      log.debug(`Telegram cleanup failed: ${err.message}`);
+    }
+  }
+}
+function disposeRuntime(log) {
+  const state = teardownState;
+  teardownState = null;
+  if (state) runCleanups(state.cleanups, log);
+}
+function registerCommand(api, command, cleanups) {
+  api.slashCommands.register(command);
+  cleanups.push(() => {
+    api.slashCommands.unregister(`${PLUGIN_NAME}:${command.name}`);
+  });
+}
 function telegramFromConfig(cfg) {
   const ext = cfg.extensions?.[PLUGIN_NAME] ?? {};
   return {
     notifyChatId: ext.notifyChatId !== void 0 ? String(ext.notifyChatId) : void 0,
+    allowedOutboundChats: Array.isArray(ext.allowedOutboundChats) ? ext.allowedOutboundChats.filter(
+      (chatId) => typeof chatId === "string" || typeof chatId === "number"
+    ) : [],
+    allowedUserIds: Array.isArray(ext.allowedUsers) ? ext.allowedUsers.filter(
+      (userId) => typeof userId === "string" || typeof userId === "number"
+    ) : [],
+    allowGroupApprovals: ext.allowGroupApprovals === true,
     notifyOnSessionEnd: ext.notifyOnSessionEnd === true,
     notifyOnDelegate: ext.notifyOnDelegate !== false,
     // default true
@@ -1092,172 +1902,200 @@ var plugin = {
   },
   configSchema: telegramConfigSchema,
   defaultConfig: {
+    allowedOutboundChats: [],
     pollIntervalSec: 2,
     notifyOnSessionEnd: false,
     longToolThresholdMs: 3e4,
     maxMessageLength: 4e3
   },
   async setup(api) {
-    const cfg = readTelegramConfig(api);
     const log = api.log;
+    disposeRuntime(log);
+    const cfg = readTelegramConfig(api);
     log.info("Starting Telegram plugin...");
+    const rawCfg = cfg;
     const runtimeCfg = {
       notifyChatId: cfg.notifyChatId,
+      allowedOutboundChats: [...cfg.allowedOutboundChats ?? []],
+      allowedUserIds: [...cfg.allowedUsers ?? []],
+      allowGroupApprovals: rawCfg.allowGroupApprovals === true,
       notifyOnSessionEnd: cfg.notifyOnSessionEnd ?? false,
       notifyOnDelegate: cfg.notifyOnDelegate ?? true,
       longToolThresholdMs: cfg.longToolThresholdMs ?? 3e4,
-      maxMessageLength: cfg.maxMessageLength ?? 4e3
+      maxMessageLength: cfg.maxMessageLength ?? 4e3,
+      outboundQueuePerChat: cfg.outboundQueuePerChat ?? 32,
+      outboundQueueConcurrency: cfg.outboundQueueConcurrency ?? 4
     };
     const lock = cfg.singleInstanceLock === false ? void 0 : new PollLock(lockPathForToken(cfg.botToken), { log });
+    const offsetStore = cfg.offsetStoragePath === "" ? void 0 : new OffsetStore({ token: cfg.botToken, path: cfg.offsetStoragePath });
     const bot = new TelegramBot({
       token: cfg.botToken,
       pollIntervalSec: cfg.pollIntervalSec ?? 2,
-      allowedUsers: new Set((cfg.allowedUsers ?? []).map(String)),
-      allowedChats: new Set((cfg.allowedChats ?? []).map(String)),
+      ...inboundAllowlist(cfg),
       bufferSize: 50,
       log,
-      offsetStoragePath: cfg.offsetStoragePath,
+      offsetStore,
       lock,
       onMessage(msg) {
         api.emitCustom("telegram:message_received", msg);
-        const who = msg.userName ?? msg.userId ?? "unknown";
-        log.info(`\u{1F4E8} Telegram: ${who} (chat=${msg.chatId}): ${msg.text.slice(0, 200)}`);
+        log.info(`\u{1F4E8} Telegram message received (${Math.min(bot.bufferCount, 50)} unread)`);
       }
     });
-    const sendTool = makeTelegramSendTool({
-      bot,
-      getDefaultChatId: () => runtimeCfg.notifyChatId,
-      maxMessageLength: runtimeCfg.maxMessageLength,
-      log
-    });
-    const readTool = makeTelegramReadTool({ bot });
-    const approveTool = makeTelegramApproveTool({
-      bot,
-      getDefaultChatId: () => runtimeCfg.notifyChatId,
-      maxMessageLength: runtimeCfg.maxMessageLength,
-      log
-    });
-    api.tools.register(sendTool);
-    api.tools.register(readTool);
-    api.tools.register(approveTool);
-    const offs = [];
-    const unregisterPrompt = api.registerSystemPromptContributor(async () => {
-      const msgs = bot.getMessages({ limit: 5 });
-      if (msgs.length === 0) return [];
-      const blocks = [
-        {
-          type: "text",
-          text: [
-            "## Telegram Inbox",
-            `You have ${bot.bufferCount} unread Telegram message(s).`,
-            "Read them with `telegram_read` and reply with `telegram_send`.",
-            "",
-            "Recent messages:",
-            ...msgs.map((m) => {
-              const who = m.userName ?? `user_${m.userId ?? "unknown"}`;
-              const ts = new Date(m.timestamp).toLocaleTimeString();
-              return `- [${ts}] **${who}** (chat=${m.chatId}): ${m.text.slice(0, 200)}`;
-            }),
-            ""
-          ].join("\n")
-        }
-      ];
-      return blocks;
-    });
-    offs.push(unregisterPrompt);
-    const commandNames = registerSlashCommands(api, bot, cfg);
-    offs.push(
-      api.events.on("session.ended", (event) => {
-        if (!runtimeCfg.notifyOnSessionEnd || !runtimeCfg.notifyChatId) return;
-        const payload = {
-          id: event.id,
-          inputTokens: event.usage.input,
-          outputTokens: event.usage.output,
-          cacheRead: event.usage.cacheRead,
-          cacheWrite: event.usage.cacheWrite
-        };
-        const msg = truncateForTelegram(
-          formatSessionEnded(payload),
-          runtimeCfg.maxMessageLength
-        );
-        void bot.sendMessage(expectDefined2(runtimeCfg.notifyChatId), msg).catch((err) => {
-          log.debug(`Failed to send session end notification: ${err.message}`);
-        });
-      })
-    );
-    offs.push(
-      api.events.on("tool.executed", (event) => {
-        if (!runtimeCfg.notifyChatId || runtimeCfg.longToolThresholdMs <= 0 || event.durationMs < runtimeCfg.longToolThresholdMs) return;
-        const payload = {
-          name: event.name,
-          ok: event.ok,
-          durationMs: event.durationMs,
-          output: event.output
-        };
-        const msg = truncateForTelegram(
-          formatToolExecuted(payload),
-          runtimeCfg.maxMessageLength
-        );
-        void bot.sendMessage(expectDefined2(runtimeCfg.notifyChatId), msg).catch((err) => {
-          log.debug(`Failed to send tool notification: ${err.message}`);
-        });
-      })
-    );
-    offs.push(
-      api.events.on("delegate.completed", (event) => {
-        if (!runtimeCfg.notifyOnDelegate || !runtimeCfg.notifyChatId) return;
-        const msg = truncateForTelegram(
-          formatDelegateCompleted(event),
-          runtimeCfg.maxMessageLength
-        );
-        void bot.sendMessage(expectDefined2(runtimeCfg.notifyChatId), msg).catch((err) => {
-          log.debug(`Failed to send delegate notification: ${err.message}`);
-        });
-      })
-    );
-    const unlistenConfig = api.onConfigChange((next, _prev) => {
-      const fresh = telegramFromConfig(next);
-      runtimeCfg.notifyChatId = fresh.notifyChatId;
-      runtimeCfg.notifyOnSessionEnd = fresh.notifyOnSessionEnd;
-      runtimeCfg.notifyOnDelegate = fresh.notifyOnDelegate;
-      runtimeCfg.longToolThresholdMs = fresh.longToolThresholdMs;
-      runtimeCfg.maxMessageLength = fresh.maxMessageLength;
-      log.debug("Telegram notification settings updated from config", {
-        notifyOnSessionEnd: runtimeCfg.notifyOnSessionEnd,
-        notifyOnDelegate: runtimeCfg.notifyOnDelegate,
-        longToolThresholdMs: runtimeCfg.longToolThresholdMs,
-        notifyChatId: runtimeCfg.notifyChatId ?? "not set"
-      });
-    });
-    offs.push(unlistenConfig);
     const probe = await bot.health();
     if (!probe.ok) {
+      bot.stop();
       throw new Error(
         `Telegram plugin startup failed: ${probe.error ?? "unknown error"}. Verify botToken in extensions.telegram (token from @BotFather, format "<id>:<35+ chars>").`
       );
     }
     log.info(`Telegram self-test ok: @${probe.username ?? "unknown"} (api.telegram.org reachable)`);
-    bot.start();
-    teardownState = {
-      offs,
-      toolNames: [sendTool.name, readTool.name, approveTool.name],
-      commandNames,
-      bot,
-      runtimeCfg
-    };
-    log.info("Telegram plugin ready");
+    const cleanups = [];
+    try {
+      cleanups.push(() => bot.stop());
+      const outbound = new TelegramBotOutbound({
+        bot,
+        log,
+        maxPerChat: runtimeCfg.outboundQueuePerChat,
+        maxConcurrency: runtimeCfg.outboundQueueConcurrency
+      });
+      cleanups.push(() => {
+        void outbound.stop();
+      });
+      const sendTool = makeTelegramSendTool({
+        bot,
+        getDefaultChatId: () => runtimeCfg.notifyChatId,
+        getAllowedOutboundChatIds: () => runtimeCfg.allowedOutboundChats,
+        maxMessageLength: runtimeCfg.maxMessageLength,
+        log
+      });
+      const readTool = makeTelegramReadTool({ bot });
+      const approveTool = makeTelegramApproveTool({
+        bot,
+        getDefaultChatId: () => runtimeCfg.notifyChatId,
+        getAllowedOutboundChatIds: () => runtimeCfg.allowedOutboundChats,
+        getAllowedUserIds: () => runtimeCfg.allowedUserIds,
+        allowGroupApprovals: runtimeCfg.allowGroupApprovals,
+        maxMessageLength: runtimeCfg.maxMessageLength,
+        log
+      });
+      for (const tool of [sendTool, readTool, approveTool]) {
+        api.tools.register(tool);
+        cleanups.push(() => {
+          api.tools.unregister(tool.name);
+        });
+      }
+      const unregisterPrompt = api.registerSystemPromptContributor(async () => {
+        const unreadCount = Math.min(bot.bufferCount, 50);
+        if (unreadCount === 0) return [];
+        return [
+          {
+            type: "text",
+            text: [
+              "## Telegram Inbox",
+              `You have ${unreadCount} unread Telegram message(s).`,
+              "Use `telegram_read` to retrieve them when needed."
+            ].join("\n")
+          }
+        ];
+      });
+      cleanups.push(unregisterPrompt);
+      for (const command of [
+        tgHealthCommand(bot, cfg),
+        tgSendCommand(
+          bot,
+          {
+            getDefaultChatId: () => runtimeCfg.notifyChatId,
+            getAllowedOutboundChatIds: () => runtimeCfg.allowedOutboundChats,
+            getMaxMessageLength: () => runtimeCfg.maxMessageLength
+          },
+          outbound
+        ),
+        tgChatIdCommand(cfg.notifyChatId)
+      ]) {
+        registerCommand(api, command, cleanups);
+      }
+      cleanups.push(
+        api.events.on("session.ended", (event) => {
+          if (!runtimeCfg.notifyOnSessionEnd || !runtimeCfg.notifyChatId) return;
+          const payload = {
+            id: scrubTelegramOutboundText(event.id),
+            inputTokens: event.usage.input,
+            outputTokens: event.usage.output,
+            cacheRead: event.usage.cacheRead,
+            cacheWrite: event.usage.cacheWrite
+          };
+          const msg = truncateForTelegram(
+            scrubTelegramOutboundText(formatSessionEnded(payload)),
+            runtimeCfg.maxMessageLength
+          );
+          outbound.enqueueNotification(expectDefined2(runtimeCfg.notifyChatId), msg);
+        })
+      );
+      cleanups.push(
+        api.events.on("tool.executed", (event) => {
+          if (!runtimeCfg.notifyChatId || runtimeCfg.longToolThresholdMs <= 0 || event.durationMs < runtimeCfg.longToolThresholdMs)
+            return;
+          const payload = {
+            name: event.name,
+            ok: event.ok,
+            durationMs: event.durationMs,
+            output: event.output === void 0 ? void 0 : scrubTelegramOutboundText(event.output)
+          };
+          const msg = truncateForTelegram(
+            scrubTelegramOutboundText(formatToolExecuted(payload)),
+            runtimeCfg.maxMessageLength
+          );
+          outbound.enqueueNotification(expectDefined2(runtimeCfg.notifyChatId), msg);
+        })
+      );
+      cleanups.push(
+        api.events.on("delegate.completed", (event) => {
+          if (!runtimeCfg.notifyOnDelegate || !runtimeCfg.notifyChatId) return;
+          const safeEvent = {
+            ...event,
+            target: scrubTelegramOutboundText(event.target),
+            task: scrubTelegramOutboundText(event.task),
+            status: event.status === void 0 ? void 0 : scrubTelegramOutboundText(event.status),
+            summary: scrubTelegramOutboundText(event.summary)
+          };
+          const msg = truncateForTelegram(
+            scrubTelegramOutboundText(formatDelegateCompleted(safeEvent)),
+            runtimeCfg.maxMessageLength
+          );
+          outbound.enqueueNotification(expectDefined2(runtimeCfg.notifyChatId), msg);
+        })
+      );
+      const unlistenConfig = api.onConfigChange((next, _prev) => {
+        const fresh = telegramFromConfig(next);
+        runtimeCfg.notifyChatId = fresh.notifyChatId;
+        runtimeCfg.allowedOutboundChats = fresh.allowedOutboundChats;
+        runtimeCfg.allowedUserIds = fresh.allowedUserIds;
+        runtimeCfg.allowGroupApprovals = fresh.allowGroupApprovals;
+        runtimeCfg.notifyOnSessionEnd = fresh.notifyOnSessionEnd;
+        runtimeCfg.notifyOnDelegate = fresh.notifyOnDelegate;
+        runtimeCfg.longToolThresholdMs = fresh.longToolThresholdMs;
+        runtimeCfg.maxMessageLength = fresh.maxMessageLength;
+        log.debug("Telegram notification settings updated from config", {
+          notifyOnSessionEnd: runtimeCfg.notifyOnSessionEnd,
+          notifyOnDelegate: runtimeCfg.notifyOnDelegate,
+          longToolThresholdMs: runtimeCfg.longToolThresholdMs,
+          notifyChatId: runtimeCfg.notifyChatId ?? "not set"
+        });
+      });
+      cleanups.push(unlistenConfig);
+      bot.start();
+      teardownState = { bot, outbound, cleanups };
+      log.info("Telegram plugin ready");
+    } catch (err) {
+      teardownState = null;
+      runCleanups(cleanups, log);
+      throw err;
+    }
   },
   async teardown(api) {
-    const state = teardownState;
-    if (!state) return;
-    teardownState = null;
-    state.bot.stop();
-    for (const off of state.offs) off();
-    for (const name of state.toolNames) api.tools.unregister(name);
-    for (const name of state.commandNames) {
-      api.slashCommands.unregister(`${PLUGIN_NAME}:${name}`);
-    }
-    api.log.info("Telegram plugin torn down");
+    const hadRuntime = teardownState !== null;
+    disposeRuntime(api.log);
+    if (hadRuntime) api.log.info("Telegram plugin torn down");
   },
   async health() {
     const state = teardownState;
@@ -1268,6 +2106,7 @@ var plugin = {
 };
 var src_default = plugin;
 export {
-  src_default as default
+  src_default as default,
+  teardownState
 };
 //# sourceMappingURL=index.js.map