@llblab/pi-telegram 0.18.3 → 0.18.5

package/lib/bus-transport.ts

@@ -0,0 +1,227 @@
+/**
+ * Telegram bus local transport boundary
+ * Zones: multi-instance bus, IPC transport, Windows named pipes, Unix sockets
+ * Owns endpoint derivation, transport-kind detection, retry/error classification, and small timing policy.
+ */
+
+import { createHash } from "node:crypto";
+import { createConnection } from "node:net";
+import { join, resolve } from "node:path";
+
+export type TelegramBusTransportKind = "pipe" | "socket";
+
+export type TelegramBusTransportEventRecorder = (
+  phase: string,
+  details: Record<string, unknown>,
+) => void;
+
+export type TelegramBusTransportEndpointDiagnostics = Record<
+  string,
+  unknown
+> & {
+  endpoint: string;
+  transport: TelegramBusTransportKind;
+};
+
+export interface TelegramBusTransportRetryPolicy {
+  attempts: number;
+  delayMs: number;
+}
+
+export interface TelegramBusTransportRetryPolicyOverrides {
+  attempts?: number;
+  delayMs?: number;
+}
+
+export type TelegramBusTransportOperation = "registration" | "operation";
+
+export const TELEGRAM_BUS_REGISTRATION_RETRY: TelegramBusTransportRetryPolicy = {
+  attempts: 10,
+  delayMs: 150,
+};
+
+export const TELEGRAM_BUS_OPERATION_RETRY: TelegramBusTransportRetryPolicy = {
+  attempts: 3,
+  delayMs: 100,
+};
+
+export const TELEGRAM_BUS_PIPE_REGISTRATION_RETRY =
+  TELEGRAM_BUS_REGISTRATION_RETRY;
+
+export const TELEGRAM_BUS_PIPE_OPERATION_RETRY = TELEGRAM_BUS_OPERATION_RETRY;
+
+export function getTelegramBusPipePath(input: {
+  agentDir: string;
+  scope: string;
+}): string {
+  const digest = createHash("sha256")
+    .update(resolve(input.agentDir))
+    .digest("base64url")
+    .slice(0, 16);
+  const scope = input.scope.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
+  return `\\\\.\\pipe\\pi-telegram-${digest}-${scope}`;
+}
+
+export function isTelegramBusPipePath(endpoint: string): boolean {
+  return /^\\\\[.?]\\pipe\\/i.test(endpoint);
+}
+
+export function getTelegramBusTransportKind(
+  endpoint: string,
+): TelegramBusTransportKind {
+  return isTelegramBusPipePath(endpoint) ? "pipe" : "socket";
+}
+
+export function getTelegramBusEndpointDiagnostics(
+  endpoint: string,
+): TelegramBusTransportEndpointDiagnostics {
+  return {
+    endpoint,
+    transport: getTelegramBusTransportKind(endpoint),
+  };
+}
+
+export function getTelegramBusTransportRetryPolicy(input: {
+  endpoint: string;
+  operation: TelegramBusTransportOperation;
+  overrides?: TelegramBusTransportRetryPolicyOverrides;
+}): TelegramBusTransportRetryPolicy | undefined {
+  const base =
+    input.operation === "registration"
+      ? TELEGRAM_BUS_REGISTRATION_RETRY
+      : isTelegramBusPipePath(input.endpoint)
+        ? TELEGRAM_BUS_OPERATION_RETRY
+        : undefined;
+  if (!base && !input.overrides) return undefined;
+  return {
+    attempts: Math.max(1, input.overrides?.attempts ?? base?.attempts ?? 1),
+    delayMs: Math.max(0, input.overrides?.delayMs ?? base?.delayMs ?? 0),
+  };
+}
+
+export function getTelegramBusLeaderEndpoint(input: {
+  agentDir: string;
+  platform: NodeJS.Platform | string;
+}): string {
+  return input.platform === "win32"
+    ? getTelegramBusPipePath({ agentDir: input.agentDir, scope: "bus" })
+    : join(input.agentDir, "tmp", "telegram", "bus.sock");
+}
+
+export function getTelegramBusFollowerEndpoint(input: {
+  agentDir: string;
+  platform: NodeJS.Platform | string;
+  instanceId: string;
+}): string {
+  return input.platform === "win32"
+    ? getTelegramBusPipePath({
+        agentDir: input.agentDir,
+        scope: `follower-${input.instanceId}`,
+      })
+    : join(
+        input.agentDir,
+        "tmp",
+        "telegram",
+        "followers",
+        `${input.instanceId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.sock`,
+      );
+}
+
+export interface TelegramBusTransportErrorInfo {
+  message: string;
+  code?: string;
+  syscall?: string;
+  kind: "connect" | "timeout" | "auth" | "protocol" | "unknown";
+  retryable: boolean;
+}
+
+export function classifyTelegramBusTransportError(
+  error: unknown,
+): TelegramBusTransportErrorInfo {
+  const message = error instanceof Error ? error.message : String(error);
+  const maybeNodeError = error as NodeJS.ErrnoException;
+  const code =
+    typeof maybeNodeError?.code === "string" ? maybeNodeError.code : undefined;
+  const syscall =
+    typeof maybeNodeError?.syscall === "string"
+      ? maybeNodeError.syscall
+      : undefined;
+  const timeout = code === "ETIMEDOUT" || /timed out/i.test(message);
+  const retryable =
+    code === "ENOENT" ||
+    code === "ECONNREFUSED" ||
+    code === "EPIPE" ||
+    code === "ECONNRESET" ||
+    code === "EBUSY" ||
+    timeout;
+  const kind = timeout
+    ? "timeout"
+    : code === "ENOENT" || code === "ECONNREFUSED"
+      ? "connect"
+      : "unknown";
+  return { message, code, syscall, kind, retryable };
+}
+
+export function isRetryableTelegramBusTransportError(error: unknown): boolean {
+  return classifyTelegramBusTransportError(error).retryable;
+}
+
+export function createTelegramBusTransportTimeoutError(
+  message: string,
+): NodeJS.ErrnoException {
+  const error = new Error(message) as NodeJS.ErrnoException;
+  error.code = "ETIMEDOUT";
+  return error;
+}
+
+export function delayTelegramBusTransportRetry(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+export interface TelegramBusTransportProbeResult
+  extends TelegramBusTransportEndpointDiagnostics {
+  reachable: boolean;
+  error?: TelegramBusTransportErrorInfo;
+}
+
+export function probeTelegramBusEndpoint(input: {
+  endpoint: string;
+  timeoutMs?: number;
+}): Promise<TelegramBusTransportProbeResult> {
+  const timeoutMs = input.timeoutMs ?? 250;
+  const diagnostics = getTelegramBusEndpointDiagnostics(input.endpoint);
+  return new Promise((resolve) => {
+    const socket = createConnection(input.endpoint);
+    let settled = false;
+    const settle = (result: TelegramBusTransportProbeResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      socket.destroy();
+      resolve(result);
+    };
+    const timeout = setTimeout(() => {
+      settle({
+        ...diagnostics,
+        reachable: false,
+        error: classifyTelegramBusTransportError(
+          createTelegramBusTransportTimeoutError(
+            "Timed out probing Telegram bus endpoint",
+          ),
+        ),
+      });
+    }, timeoutMs);
+    timeout.unref?.();
+    socket.once("connect", () => settle({ ...diagnostics, reachable: true }));
+    socket.once("error", (error) =>
+      settle({
+        ...diagnostics,
+        reachable: false,
+        error: classifyTelegramBusTransportError(error),
+      }),
+    );
+  });
+}

package/lib/bus.ts

@@ -5,7 +5,7 @@
  * cross-instance forwarding helpers, and the live follower registry model.
  */
 
-import { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
 import {
   createConnection,
@@ -16,6 +16,19 @@ import {
 import { homedir, platform as getPlatform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
+import {
+  classifyTelegramBusTransportError,
+  createTelegramBusTransportTimeoutError,
+  delayTelegramBusTransportRetry,
+  getTelegramBusEndpointDiagnostics,
+  getTelegramBusFollowerEndpoint,
+  getTelegramBusLeaderEndpoint,
+  getTelegramBusTransportRetryPolicy,
+  isTelegramBusPipePath,
+  isRetryableTelegramBusTransportError,
+  type TelegramBusTransportEventRecorder,
+  type TelegramBusTransportRetryPolicy,
+} from "./bus-transport.ts";
 import type { TelegramTarget } from "./target.ts";
 
 export type TelegramBusRole = "leader" | "follower";
@@ -30,30 +43,11 @@ export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }
 
-function getTelegramBusPipePath(input: {
-  agentDir: string;
-  scope: string;
-}): string {
-  const digest = createHash("sha256")
-    .update(resolve(input.agentDir))
-    .digest("base64url")
-    .slice(0, 16);
-  const scope = input.scope.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
-  return `\\\\.\\pipe\\pi-telegram-${digest}-${scope}`;
-}
-
-function isWindowsPipePath(socketPath: string): boolean {
-  return /^\\\\[.?]\\pipe\\/i.test(socketPath);
-}
-
 export function getTelegramBusSocketPath(
   agentDir = getAgentDir(),
   platform = getPlatform(),
 ): string {
-  if (platform === "win32") {
-    return getTelegramBusPipePath({ agentDir, scope: "bus" });
-  }
-  return join(agentDir, "tmp", "telegram", "bus.sock");
+  return getTelegramBusLeaderEndpoint({ agentDir, platform });
 }
 
 export function getTelegramBusFollowerSocketPath(
@@ -61,19 +55,7 @@ export function getTelegramBusFollowerSocketPath(
   agentDir = getAgentDir(),
   platform = getPlatform(),
 ): string {
-  if (platform === "win32") {
-    return getTelegramBusPipePath({
-      agentDir,
-      scope: `follower-${instanceId}`,
-    });
-  }
-  return join(
-    agentDir,
-    "tmp",
-    "telegram",
-    "followers",
-    `${instanceId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.sock`,
-  );
+  return getTelegramBusFollowerEndpoint({ agentDir, platform, instanceId });
 }
 
 export interface TelegramBusInstanceRegistration {
@@ -91,6 +73,35 @@ export interface TelegramBusFollowerView extends TelegramBusInstanceRegistration
   lastHeartbeatMs: number;
 }
 
+export function getTelegramFollowerTargetOwnership(input: {
+  target: TelegramTarget;
+  followers: TelegramBusFollowerView[];
+  activeThreadRecords?: Array<{
+    status?: string;
+    instanceId?: string;
+    target: TelegramTarget;
+  }>;
+  currentInstanceId?: string;
+}): { instanceId: string } | undefined {
+  const liveFollower = input.followers.find((follower) => {
+    return (
+      follower.target?.chatId === input.target.chatId &&
+      follower.target.threadId === input.target.threadId
+    );
+  });
+  if (liveFollower) return { instanceId: liveFollower.instanceId };
+  const record = input.activeThreadRecords?.find((candidate) => {
+    return (
+      candidate.status === "active" &&
+      candidate.instanceId &&
+      candidate.instanceId !== input.currentInstanceId &&
+      candidate.target.chatId === input.target.chatId &&
+      candidate.target.threadId === input.target.threadId
+    );
+  });
+  return record?.instanceId ? { instanceId: record.instanceId } : undefined;
+}
+
 export function isTelegramFollowerApiCallAllowed(input: {
   follower: TelegramBusFollowerView;
   method: string;
@@ -310,12 +321,15 @@ export interface TelegramBusLocalServerDeps {
     | Promise<TelegramBusEnvelope | undefined>
     | TelegramBusEnvelope
     | undefined;
+  recordTransportEvent?: TelegramBusTransportEventRecorder;
 }
 
 export interface TelegramBusLocalClientOptions {
   socketPath: string;
   envelope: TelegramBusEnvelope;
   timeoutMs?: number;
+  retry?: TelegramBusTransportRetryPolicy;
+  recordTransportEvent?: TelegramBusTransportEventRecorder;
 }
 
 export interface TelegramBusForeignOwnedForwarderDeps {
@@ -362,6 +376,10 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
       socketPath: deps.socketPath,
       envelope,
       timeoutMs: deps.timeoutMs,
+      retry: getTelegramBusTransportRetryPolicy({
+        endpoint: deps.socketPath,
+        operation: "operation",
+      }),
     });
     return response?.kind === "bus.ack" && response.ok;
   };
@@ -449,6 +467,10 @@ export function createTelegramBusFollowerTargetController(
         socketPath: follower.busSocketPath,
         envelope,
         timeoutMs: deps.timeoutMs,
+        retry: getTelegramBusTransportRetryPolicy({
+          endpoint: follower.busSocketPath,
+          operation: "operation",
+        }),
       });
       return response?.kind === "bus.ack" && response.ok;
     },
@@ -517,7 +539,11 @@ export function createTelegramBusLocalServer(
   return {
     start: async () => {
       if (server) return;
-      const usesWindowsPipe = isWindowsPipePath(deps.socketPath);
+      const usesWindowsPipe = isTelegramBusPipePath(deps.socketPath);
+      deps.recordTransportEvent?.(
+        "server-start",
+        getTelegramBusEndpointDiagnostics(deps.socketPath),
+      );
       if (!usesWindowsPipe) {
         const socketDir = dirname(deps.socketPath);
         mkdirSync(socketDir, { recursive: true, mode: 0o700 });
@@ -533,16 +559,40 @@ export function createTelegramBusLocalServer(
           const lines = buffer.split("\n");
           buffer = lines.pop() ?? "";
           for (const line of lines) {
-            void handleTelegramBusSocketLine(line, socket, deps.handleEnvelope);
+            void handleTelegramBusSocketLine(
+              line,
+              socket,
+              deps.handleEnvelope,
+              deps.recordTransportEvent,
+              deps.socketPath,
+            );
           }
         });
         socket.on("close", () => sockets.delete(socket));
-        socket.on("error", () => closeSocket(socket));
-      });
-      await new Promise<void>((resolve, reject) => {
-        server?.once("error", reject);
-        server?.listen(deps.socketPath, resolve);
+        socket.on("error", (error) => {
+          deps.recordTransportEvent?.("server-socket-error", {
+            ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+            ...classifyTelegramBusTransportError(error),
+          });
+          closeSocket(socket);
+        });
       });
+      try {
+        await new Promise<void>((resolve, reject) => {
+          server?.once("error", reject);
+          server?.listen(deps.socketPath, resolve);
+        });
+        deps.recordTransportEvent?.(
+          "server-started",
+          getTelegramBusEndpointDiagnostics(deps.socketPath),
+        );
+      } catch (error) {
+        deps.recordTransportEvent?.("server-start-failed", {
+          ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+          ...classifyTelegramBusTransportError(error),
+        });
+        throw error;
+      }
       if (!usesWindowsPipe) chmodSync(deps.socketPath, 0o600);
     },
     stop: async () => {
@@ -554,14 +604,27 @@ export function createTelegramBusLocalServer(
           activeServer.close(() => resolve()),
         );
       }
-      if (!isWindowsPipePath(deps.socketPath) && existsSync(deps.socketPath)) {
+      if (!isTelegramBusPipePath(deps.socketPath) && existsSync(deps.socketPath)) {
         unlinkSync(deps.socketPath);
       }
+      deps.recordTransportEvent?.(
+        "server-stopped",
+        getTelegramBusEndpointDiagnostics(deps.socketPath),
+      );
     },
   };
 }
 
-export function sendTelegramBusLocalEnvelope(
+function getTelegramBusEnvelopeDiagnostics(
+  envelope: TelegramBusEnvelope,
+): Record<string, unknown> {
+  return {
+    envelopeKind: envelope.kind,
+    requestId: envelope.requestId,
+  };
+}
+
+function sendTelegramBusLocalEnvelopeOnce(
   options: TelegramBusLocalClientOptions,
 ): Promise<TelegramBusEnvelope | undefined> {
   const timeoutMs = options.timeoutMs ?? 1000;
@@ -578,7 +641,11 @@ export function sendTelegramBusLocalEnvelope(
     };
     const timeout = setTimeout(() => {
       settle(() =>
-        reject(new Error("Timed out waiting for Telegram bus response")),
+        reject(
+          createTelegramBusTransportTimeoutError(
+            "Timed out waiting for Telegram bus response",
+          ),
+        ),
       );
     }, timeoutMs);
     timeout.unref?.();
@@ -598,6 +665,39 @@ export function sendTelegramBusLocalEnvelope(
   });
 }
 
+export async function sendTelegramBusLocalEnvelope(
+  options: TelegramBusLocalClientOptions,
+): Promise<TelegramBusEnvelope | undefined> {
+  const attempts = Math.max(1, options.retry?.attempts ?? 1);
+  const delayMs = Math.max(0, options.retry?.delayMs ?? 0);
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await sendTelegramBusLocalEnvelopeOnce(options);
+    } catch (error) {
+      const info = classifyTelegramBusTransportError(error);
+      options.recordTransportEvent?.("client-failed", {
+        ...getTelegramBusEndpointDiagnostics(options.socketPath),
+        ...getTelegramBusEnvelopeDiagnostics(options.envelope),
+        attempt,
+        attempts,
+        ...info,
+      });
+      if (attempt >= attempts || !isRetryableTelegramBusTransportError(error)) {
+        throw error;
+      }
+      options.recordTransportEvent?.("client-retry", {
+        ...getTelegramBusEndpointDiagnostics(options.socketPath),
+        ...getTelegramBusEnvelopeDiagnostics(options.envelope),
+        attempt,
+        attempts,
+        delayMs,
+        ...info,
+      });
+      await delayTelegramBusTransportRetry(delayMs);
+    }
+  }
+}
+
 export interface TelegramBusFollowerRegistry {
   register: (
     registration: TelegramBusInstanceRegistration,
@@ -610,6 +710,7 @@ export interface TelegramBusFollowerRegistry {
   getByTarget: (target: TelegramTarget) => TelegramBusFollowerView | undefined;
   list: () => TelegramBusFollowerView[];
   remove: (instanceId: string) => boolean;
+  clear: () => void;
   pruneStale: (
     nowMs: number,
     staleAfterMs: number,
@@ -660,6 +761,7 @@ export function createTelegramBusFollowerRegistry(): TelegramBusFollowerRegistry
     },
     list: () => [...followers.values()].map(clone),
     remove: (instanceId) => followers.delete(instanceId),
+    clear: () => followers.clear(),
     pruneStale: (nowMs, staleAfterMs) => {
       const removed: TelegramBusFollowerView[] = [];
       for (const [instanceId, follower] of followers.entries()) {
@@ -676,9 +778,15 @@ async function handleTelegramBusSocketLine(
   line: string,
   socket: Socket,
   handleEnvelope: TelegramBusLocalServerDeps["handleEnvelope"],
+  recordTransportEvent: TelegramBusTransportEventRecorder | undefined,
+  socketPath: string,
 ): Promise<void> {
   const envelope = parseTelegramBusEnvelope(line);
   if (!envelope) {
+    recordTransportEvent?.("server-invalid-envelope", {
+      ...getTelegramBusEndpointDiagnostics(socketPath),
+      byteLength: Buffer.byteLength(line),
+    });
     socket.write(
       encodeTelegramBusEnvelope({
         kind: "bus.ack",
@@ -689,8 +797,24 @@ async function handleTelegramBusSocketLine(
     );
     return;
   }
-  const response = await handleEnvelope(envelope);
-  if (response) socket.write(encodeTelegramBusEnvelope(response));
+  try {
+    const response = await handleEnvelope(envelope);
+    if (response) socket.write(encodeTelegramBusEnvelope(response));
+  } catch (error) {
+    recordTransportEvent?.("server-handler-failed", {
+      ...getTelegramBusEndpointDiagnostics(socketPath),
+      ...getTelegramBusEnvelopeDiagnostics(envelope),
+      ...classifyTelegramBusTransportError(error),
+    });
+    socket.write(
+      encodeTelegramBusEnvelope({
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Telegram bus handler failed.",
+      }),
+    );
+  }
 }
 
 function parseRegisterEnvelope(

package/lib/polling.ts

@@ -20,7 +20,7 @@ const TELEGRAM_INITIAL_SYNC_LIMIT = 1;
 const TELEGRAM_INITIAL_SYNC_TIMEOUT_SECONDS = 0;
 const TELEGRAM_LONG_POLL_LIMIT = 10;
 const TELEGRAM_LONG_POLL_TIMEOUT_SECONDS = 30;
-const TELEGRAM_THREAD_CAPABILITY_MONITOR_INTERVAL_MS = 5_000;
+const TELEGRAM_THREAD_CAPABILITY_MONITOR_INTERVAL_MS = 2_500;
 const TELEGRAM_THREAD_CAPABILITY_DISABLED_CONFIRMATION_PROBES = 2;
 const TELEGRAM_POLLING_DEFAULT_MAX_UPDATE_FAILURES = 3;
 const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_LIMIT = 3;
@@ -426,6 +426,12 @@ export async function probeTelegramStartupThreadCapability(
   return threadModeEnabled;
 }
 
+function hasTelegramClassicRestoreFailure(
+  state: TelegramThreadCapabilityState,
+): boolean {
+  return state.lastReconcileAction?.endsWith("-classic-restore-failed") ?? false;
+}
+
 function hasTelegramThreadCapabilityBindings(
   store: TelegramThreadCapabilityStore,
 ): boolean {
@@ -451,6 +457,7 @@ export async function applyTelegramThreadCapability<TContext>(
   await deps.topicTargetStore.load();
   if (!deps.isBusConfigured()) return;
   const nowMs = (deps.getNowMs ?? Date.now)();
+  const previousBotState = deps.topicTargetStore.getBotState();
   if (!threadModeEnabled) {
     if (
       hasTelegramThreadCapabilityBindings(deps.topicTargetStore) &&
@@ -470,11 +477,26 @@ export async function applyTelegramThreadCapability<TContext>(
     await deps.topicTargetStore.persist();
     deps.setTopicModeUnavailable(true);
     deps.stopFollowerRegistration();
-    if (deps.getPollingStartedWithTelegramBus()) {
+    if (
+      deps.getPollingStartedWithTelegramBus() ||
+      hasTelegramClassicRestoreFailure(previousBotState)
+    ) {
       deps.stopLeaderHealth();
       await deps.stopBusPolling();
       deps.setPollingStartedWithTelegramBus(false);
-      await deps.startClassicPolling(ctx);
+      try {
+        await deps.startClassicPolling(ctx);
+      } catch (classicError) {
+        deps.topicTargetStore.setBotState({
+          threadMode: "disabled",
+          updatedAtMs: (deps.getNowMs ?? Date.now)(),
+          lastReconcileAction: `${phase}-classic-restore-failed`,
+        });
+        await deps.topicTargetStore.persist();
+        deps.recordEvent("bus", classicError, {
+          phase: `${phase}-classic-restore`,
+        });
+      }
     }
     deps.updateStatus(ctx);
     return;
@@ -509,6 +531,12 @@ export async function applyTelegramThreadCapability<TContext>(
       try {
         await deps.startClassicPolling(ctx);
       } catch (classicError) {
+        deps.topicTargetStore.setBotState({
+          threadMode: "disabled",
+          updatedAtMs: (deps.getNowMs ?? Date.now)(),
+          lastReconcileAction: `${phase}-classic-restore-failed`,
+        });
+        await deps.topicTargetStore.persist();
         deps.recordEvent("bus", classicError, {
           phase: `${phase}-classic-restore`,
         });
@@ -583,6 +611,19 @@ export function createTelegramThreadAwarePollingPorts<TContext, TOwner>(
   ): Promise<boolean | undefined> => {
     await deps.topicTargetStore.load();
     if (deps.topicTargetStore.getBotState().threadMode !== "enabled") {
+      if (hasTelegramThreadCapabilityBindings(deps.topicTargetStore)) {
+        deps.recordEvent(
+          "bus",
+          "Telegram Threaded Mode disabled; follower takeover blocked",
+          {
+            phase: "follower-register-thread-mode-disabled",
+            reason: "active-thread-bindings-present",
+          },
+        );
+        throw new Error(
+          "Telegram Threaded Mode is disabled; the current leader remains the classic polling owner.",
+        );
+      }
       return undefined;
     }
     if (!deps.isBusRuntimeEnabled()) return undefined;
@@ -653,9 +694,21 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
           return;
         }
         if (threadModeEnabled) consecutiveDisabledProbes = 0;
-        const current = deps.topicTargetStore.getBotState().threadMode;
+        const botState = deps.topicTargetStore.getBotState();
+        const current = botState.threadMode;
         if (threadModeEnabled && current === "enabled") return;
-        if (!threadModeEnabled && current === "disabled") return;
+        if (!threadModeEnabled && current === "disabled") {
+          if (!deps.ownsLock(ctx) || !hasTelegramClassicRestoreFailure(botState)) {
+            return;
+          }
+          await applyTelegramThreadCapability(
+            ctx,
+            false,
+            "capability-monitor-disabled-confirmed",
+            deps,
+          );
+          return;
+        }
         if (
           !threadModeEnabled &&
           hasTelegramThreadCapabilityBindings(deps.topicTargetStore)