@llblab/pi-kit 0.35.1 → 0.35.3

package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts

@@ -111,6 +111,7 @@ import * as WorkspaceIdentity from "./workspace-identity.ts";
 const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
 const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30_000;
 const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30_000;
+const TELEGRAM_BUS_FOLLOWER_API_SLOW_CALL_MS = 1_500;
 const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS =
   TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS;
@@ -326,6 +327,20 @@ export interface TelegramBusFollowerClientRuntimeDeps<TMessage = unknown> {
   timeoutMs?: number;
 }
 
+/** Structural port for run-collapsing diagnostics, implemented by the logging domain. */
+export interface TelegramFailureRunLogPort {
+  record: (error: unknown, details?: Record<string, unknown>) => boolean;
+  settled: () => TelegramFailureRunSummaryPort | undefined;
+  reset: () => void;
+}
+
+export interface TelegramFailureRunSummaryPort {
+  signature: string;
+  failedAttempts: number;
+  suppressedFailures: number;
+  failedForMs: number;
+}
+
 export interface TelegramBusFollowerApiCallerDeps {
   socketPath: TelegramBusSocketPathSource;
   instanceId: string;
@@ -337,11 +352,23 @@ export interface TelegramBusFollowerApiCallerDeps {
   ) => Promise<string | undefined>;
   getNowMs?: () => number;
   timeoutMs?: number;
+  /** Receives one diagnostic per call slower than `slowCallMs`; observation only. */
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+  slowCallMs?: number;
 }
 
 export interface TelegramBusFollowerRegistrationRuntimeDeps<
   TContext extends { cwd?: string },
 > {
+  /**
+   * Collapses one sustained heartbeat failure run. Optional at this unit boundary, where an absent port records
+   * every failure; the runtime assembly requires it so production always supplies the logging domain's owner.
+   */
+  failureLog?: TelegramFailureRunLogPort;
   instanceId: string;
   createRequestId: () => string;
   protocolIdentity: TelegramBusProtocolIdentity;
@@ -673,6 +700,8 @@ export interface TelegramBusFollowerRuntimeAssemblyPorts<
   TContext extends { cwd?: string },
 > {
   instanceId: string;
+  /** Collapses one sustained heartbeat failure run; the composition root supplies the logging domain's owner. */
+  failureLog: TelegramFailureRunLogPort;
   registrationState: TelegramBusFollowerRegistrationState;
   recordRuntimeEvent: (
     category: string,
@@ -789,6 +818,7 @@ export function createTelegramBusFollowerRuntimeAssembly<
   });
   registration = createTelegramBusFollowerRegistrationRuntime({
     ...ports.registration,
+    failureLog: ports.failureLog,
     ...sharedRuntimeDeps,
     startReceiving: receiver.start,
     stopReceiving: receiver.stop,
@@ -1495,6 +1525,7 @@ export function createTelegramBusFollowerClientRuntime<
       instanceId: deps.instanceId,
       getAuthSecret: deps.getApiAuthSecret,
       getRegistrationGeneration: deps.getRegistrationGeneration,
+      recordRuntimeEvent: deps.recordRuntimeEvent,
     }),
     agentMessages: createTelegramBusAgentMessageClient({
       ...sharedClientDeps,
@@ -1881,7 +1912,13 @@ export function createTelegramBusFollowerApiCaller(
 ): (method: string, args: unknown[], localOptions?: Pick<TelegramApiCallOptions, "assertAuthority">) => Promise<unknown> {
   const getNowMs = deps.getNowMs ?? Date.now;
   const timeoutMs = deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
-  return async (method, args, localOptions) => {
+  const slowCallMs = deps.slowCallMs ?? TELEGRAM_BUS_FOLLOWER_API_SLOW_CALL_MS;
+  const caller = async (
+    method: string,
+    args: unknown[],
+    localOptions: Pick<TelegramApiCallOptions, "assertAuthority"> | undefined,
+    timing: { registeredAtMs?: number },
+  ): Promise<unknown> => {
     const assertion = localOptions?.assertAuthority;
     const assertCurrent = () => assertTelegramApiCallAuthority(assertion, false);
     assertCurrent();
@@ -1889,6 +1926,7 @@ export function createTelegramBusFollowerApiCaller(
       deps,
       timeoutMs,
     );
+    timing.registeredAtMs = getNowMs();
     assertCurrent();
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     let response: TelegramBusEnvelope | undefined;
@@ -1950,6 +1988,45 @@ export function createTelegramBusFollowerApiCaller(
     }
     throw new Error(message ?? "Telegram bus API call failed.");
   };
+  return async (method, args, localOptions) => {
+    const startedAtMs = getNowMs();
+    const timing: { registeredAtMs?: number } = {};
+    let outcome = "ok";
+    try {
+      return await caller(method, args, localOptions, timing);
+    } catch (error) {
+      outcome = "error";
+      throw error;
+    } finally {
+      const elapsedMs = getNowMs() - startedAtMs;
+      if (elapsedMs >= slowCallMs) {
+        const apiMethod =
+          (method === "call" || method === "callMultipart") &&
+          typeof args[0] === "string"
+            ? args[0]
+            : method;
+        try {
+          deps.recordRuntimeEvent?.(
+            "bus",
+            `Telegram bus follower API call was slow (${elapsedMs}ms).`,
+            {
+              phase: "follower-api-slow",
+              method: apiMethod,
+              elapsedMs,
+              registrationWaitMs:
+                (timing.registeredAtMs ?? getNowMs()) - startedAtMs,
+              ...(timing.registeredAtMs === undefined
+                ? {}
+                : { transportMs: getNowMs() - timing.registeredAtMs }),
+              outcome,
+            },
+          );
+        } catch {
+          // Diagnostics cannot change the API call outcome.
+        }
+      }
+    }
+  };
 }
 
 async function resolveTelegramBusFollowerRegistration(
@@ -2521,10 +2598,16 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
       election: TelegramBusFollowerElection,
     ) => {
       if (!isCurrent()) return;
-      const activeCtx = deps.getActiveContext?.();
-      if (deps.getActiveContext && activeCtx !== ctx) {
-        scheduleRecovery(reason, ctx, binding);
-        return;
+      if (deps.getActiveContext) {
+        // Pi hands every event and command a fresh context object, so a manually connected follower never holds
+        // the stored session object. Promote through the live session context instead of rescheduling: heartbeat
+        // failures re-request recovery faster than the retry grace, so a reschedule-only path never fires.
+        const activeCtx = deps.getActiveContext();
+        if (!activeCtx) {
+          scheduleRecovery(reason, ctx, binding);
+          return;
+        }
+        ctx = activeCtx;
       }
       deps.setLifecyclePhase("electing");
       safeUpdateStatus(ctx);
@@ -2765,6 +2848,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
     (!deps.registrationState ||
       deps.registrationState.getGeneration() === generation);
   const stopHeartbeat = () => {
+    // A stopped heartbeat ends the current failure run, so a later run logs its own first failure.
+    heartbeatFailureLog.reset();
     if (!heartbeatInterval) return;
     clearInterval(heartbeatInterval);
     heartbeatInterval = undefined;
@@ -2793,6 +2878,22 @@ export function createTelegramBusFollowerRegistrationRuntime<
       }
     });
   };
+  /** A sustained leader outage repeats one identical failure every interval; the port collapses the run. */
+  const heartbeatFailureLog: TelegramFailureRunLogPort =
+    deps.failureLog ?? {
+      record(error) {
+        try {
+          deps.recordRuntimeEvent?.("bus", error, {
+            phase: "follower-heartbeat",
+          });
+        } catch {
+          // Diagnostics cannot replace heartbeat recovery.
+        }
+        return true;
+      },
+      settled: () => undefined,
+      reset: () => undefined,
+    };
   const sendHeartbeat = async () => {
     const leaderSocketPath = activeLeaderSocketPath;
     const registrationGeneration = activeRegistrationGeneration;
@@ -2818,6 +2919,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
       );
       if (!isCurrentHeartbeat()) return;
       if (response?.kind === "bus.ack" && response.ok) {
+        heartbeatFailureLog.settled();
         const heartbeatResult = isRecord(response.result)
           ? response.result
           : undefined;
@@ -2850,13 +2952,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
       }
     } catch (error) {
       if (!isCurrentHeartbeat()) return;
-      try {
-        deps.recordRuntimeEvent?.("bus", error, {
-          phase: "follower-heartbeat",
-        });
-      } catch {
-        // Diagnostics cannot replace heartbeat recovery.
-      }
+      heartbeatFailureLog.record(error);
       if (!heartbeatContext) return;
       try {
         await deps.onHeartbeatFailure?.(error, heartbeatContext);
@@ -3120,11 +3216,11 @@ export function createTelegramBusFollowerRegistrationRuntime<
       return false;
     },
     setContext(ctx) {
+      // Pi hands every event a fresh context object. Only a replaced session drops an in-flight attempt.
       if (
         registrationAttempt &&
-        (registrationAttempt.ctx !== ctx ||
-          registrationAttempt.sessionGeneration !==
-            deps.getSessionGeneration?.() ||
+        (registrationAttempt.sessionGeneration !==
+          deps.getSessionGeneration?.() ||
           registrationAttempt.sessionId !== deps.getSessionId?.(ctx))
       )
         registrationAttempt = undefined;

package/node_modules/@llblab/pi-telegram/lib/bus-leader.ts

@@ -167,6 +167,7 @@ export interface TelegramBusFollowerTargetProvisionerDeps {
   callApi: <TResponse>(
     method: string,
     body: Record<string, unknown>,
+    options?: TelegramApiCallOptions,
   ) => Promise<TResponse>;
   getCurrentLeaderEpoch?: () => number | string | undefined;
   getSyncState: () => Sync.TelegramSyncState;
@@ -1925,6 +1926,8 @@ export function createTelegramBusFollowerTargetProvisioner(
               text: connectedAnnouncement.text,
               parse_mode: connectedAnnouncement.parseMode,
             },
+            // A deleted Thread is this probe's expected answer; the recovery below records it.
+            { isExpectedError: Threads.isTelegramTopicTargetStaleError },
           );
           assertRestoreRegistration();
           if (recoverableTarget || probeRequiredRecord) {
@@ -1968,7 +1971,19 @@ export function createTelegramBusFollowerTargetProvisioner(
               error instanceof Error ? error.message : String(error),
             );
             await deps.topicTargetStore.persist();
+            const staleTarget = result.target;
             result = await provisionTarget();
+            deps.recordRuntimeEvent(
+              "telegram",
+              "Telegram follower restore probe found its Thread deleted; re-created it.",
+              {
+                phase: "topic-lifecycle-restore-probe-recreated",
+                instanceId: registration.instanceId,
+                chatId: staleTarget.chatId,
+                staleThreadId: staleTarget.threadId,
+                threadId: result.target.threadId,
+              },
+            );
             connectedAnnouncement =
               createTelegramBusInstanceLifecycleAnnouncement({
                 target: result.target,

package/node_modules/@llblab/pi-telegram/lib/bus.ts

@@ -3297,33 +3297,42 @@ export async function sendTelegramBusLocalEnvelope(
   };
   const attempts = Math.max(1, resolvedOptions.retry?.attempts ?? 1);
   const delayMs = Math.max(0, resolvedOptions.retry?.delayMs ?? 0);
+  // Log the first failure, then only the outcome: a reloading leader would otherwise log every attempt.
   for (let attempt = 1; ; attempt += 1) {
     try {
-      return await sendTelegramBusLocalEnvelopeOnce(resolvedOptions);
+      const response = await sendTelegramBusLocalEnvelopeOnce(resolvedOptions);
+      if (attempt > 1)
+        resolvedOptions.recordTransportEvent?.("client-recovered", {
+          ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
+          ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
+          attempt,
+          attempts,
+        });
+      return response;
     } catch (error) {
       const info = classifyTelegramBusTransportError(error);
-      resolvedOptions.recordTransportEvent?.("client-failed", {
-        ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
-        ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
-        attempt,
-        attempts,
-        ...info,
-      });
-      if (
+      const final =
         error instanceof TelegramBusLocalAuthorityError ||
         attempt >= attempts ||
-        !isRetryableTelegramBusTransportError(error)
-      ) {
-        throw error;
-      }
-      resolvedOptions.recordTransportEvent?.("client-retry", {
-        ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
-        ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
-        attempt,
-        attempts,
-        delayMs,
-        ...info,
-      });
+        !isRetryableTelegramBusTransportError(error);
+      if (attempt === 1 || final)
+        resolvedOptions.recordTransportEvent?.("client-failed", {
+          ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
+          ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
+          attempt,
+          attempts,
+          ...info,
+        });
+      if (final) throw error;
+      if (attempt === 1)
+        resolvedOptions.recordTransportEvent?.("client-retry", {
+          ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
+          ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
+          attempt,
+          attempts,
+          delayMs,
+          ...info,
+        });
       await delayTelegramBusTransportRetry(delayMs);
     }
   }

package/node_modules/@llblab/pi-telegram/lib/extension.ts

@@ -861,6 +861,12 @@ export default function (pi: Pi.ExtensionAPI) {
   const promptDispatchRuntime = Runtime.createTelegramPromptDispatchRuntime({
     lifecycle,
     typing,
+    failureLog: runtimeDiagnostics.createFailureLog({
+      category: "typing",
+      failurePhase: "typing-presence",
+      outcomePhase: "typing-presence-recovered",
+      label: "typing presence",
+    }),
     getDefaultChatId: proactivePushChatIdGetter,
     isThreadedMode() {
       return deliveryTargetPolicyRuntime.getTargetPolicyView().threaded === true;
@@ -1576,12 +1582,14 @@ export default function (pi: Pi.ExtensionAPI) {
         target.threadId === undefined
       )
         return undefined;
+      // Pi creates a fresh context object per event and command, so authority follows the session, not the object.
+      const sessionGeneration = telegramSessionContextStore.getGeneration();
       return Threads.createTelegramWorkspaceThreadRenameRecipient({
         store: threadStore,
         instanceId: telegramInstanceId,
         target,
         assertAuthority() {
-          if (telegramSessionContextStore.get() !== ctx)
+          if (!telegramSessionContextStore.isCurrent(ctx, sessionGeneration))
             throw new Error("Telegram Thread name dialog lost Pi context.");
         },
         getAuthority: threadNameRecipientAuthority.getAuthority,
@@ -1968,6 +1976,12 @@ export default function (pi: Pi.ExtensionAPI) {
   const telegramBusFollowerAssembly: BusFollower.TelegramBusFollowerRuntimeAssembly<Pi.ExtensionContext> =
     BusFollower.createTelegramBusFollowerRuntimeAssembly<Pi.ExtensionContext>({
       instanceId: telegramInstanceId,
+      failureLog: runtimeDiagnostics.createFailureLog({
+        category: "bus",
+        failurePhase: "follower-heartbeat",
+        outcomePhase: "follower-heartbeat-recovered",
+        label: "follower heartbeat",
+      }),
       registrationState: telegramBusFollowerRegistrationState,
       recordRuntimeEvent,
       receiver: {
@@ -2370,6 +2384,12 @@ export default function (pi: Pi.ExtensionAPI) {
       Locks.TelegramLockEntry
     >({
       state: telegramThreadCapabilityState,
+      failureLog: runtimeDiagnostics.createFailureLog({
+        category: "bus",
+        failurePhase: "capability-monitor",
+        outcomePhase: "capability-monitor-recovered",
+        label: "Threaded Mode capability probe",
+      }),
       getAllowedUserId: configStore.getAllowedUserId,
       callApi: callTelegramApi,
       topicTargetStore: threadStore,

package/node_modules/@llblab/pi-telegram/lib/logging.ts

@@ -23,6 +23,118 @@ import {
 } from "./paths.ts";
 import * as Status from "./status.ts";
 
+/** Sink shape shared with the runtime event recorder this domain already owns. */
+export type TelegramFailureRecordSink = (
+  category: string,
+  errorOrMessage: unknown,
+  details: Record<string, unknown>,
+) => void;
+
+export interface TelegramFailureRunSummary {
+  signature: string;
+  failedAttempts: number;
+  suppressedFailures: number;
+  failedForMs: number;
+}
+
+export interface TelegramFailureRunLog {
+  /** Records one failure; a repeated identical failure only extends the current run and returns false. */
+  record: (error: unknown, details?: Record<string, unknown>) => boolean;
+  /** Closes the run after a success, emitting its single outcome record. */
+  settled: () => TelegramFailureRunSummary | undefined;
+  /** Ends the run without an outcome record, for a stop or replacement that reports its own outcome. */
+  reset: () => void;
+}
+
+export interface TelegramFailureRunLogInput {
+  category: string;
+  failurePhase: string;
+  outcomePhase: string;
+  /** Human-readable subject for the outcome record, e.g. `follower heartbeat`. */
+  label: string;
+  record?: TelegramFailureRecordSink;
+  /** Static context reapplied to every record of this phase, e.g. a session or profile key. */
+  context?: () => Record<string, unknown>;
+  getNowMs?: () => number;
+}
+
+/** Stable identity of one failure kind: errno when present, otherwise the failure text. */
+export function getTelegramFailureSignature(error: unknown): string {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  if (typeof code === "string" && code) return code;
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Consecutive identical failure runs for one diagnostic phase: a repeat extends the run instead of logging again,
+ * and a closing success or reset emits at most one outcome record. This never gates detection or recovery.
+ */
+export function createTelegramFailureRunLog(
+  input: TelegramFailureRunLogInput,
+): TelegramFailureRunLog {
+  const getNowMs = input.getNowMs ?? Date.now;
+  let run: { signature: string; suppressed: number; startedAtMs: number; details: Record<string, unknown> } | undefined;
+  const emit = (errorOrMessage: unknown, details: Record<string, unknown>): void => {
+    try {
+      input.record?.(input.category, errorOrMessage, {
+        ...(input.context?.() ?? {}),
+        ...details,
+      });
+    } catch {
+      // A diagnostic sink never converts a recorded failure into another failure.
+    }
+  };
+  return {
+    record(error, details) {
+      const signature = getTelegramFailureSignature(error);
+      const admitted = { ...(details ?? {}) };
+      if (run?.signature === signature) {
+        run.suppressed += 1;
+        Object.assign(run.details, admitted);
+        return false;
+      }
+      const previous = run;
+      run = { signature, suppressed: 0, startedAtMs: getNowMs(), details: admitted };
+      emit(error, {
+        ...admitted,
+        phase: input.failurePhase,
+        failureSignature: signature,
+        ...(previous
+          ? {
+              previousFailureSignature: previous.signature,
+              previousFailedAttempts: previous.suppressed + 1,
+              previousFailedForMs: getNowMs() - previous.startedAtMs,
+            }
+          : {}),
+      });
+      return true;
+    },
+    settled() {
+      const closed = run;
+      if (!closed) return undefined;
+      run = undefined;
+      const summary: TelegramFailureRunSummary = {
+        signature: closed.signature,
+        failedAttempts: closed.suppressed + 1,
+        suppressedFailures: closed.suppressed,
+        failedForMs: getNowMs() - closed.startedAtMs,
+      };
+      emit(`Telegram ${input.label} recovered after ${summary.failedAttempts} failed attempts.`, {
+        ...closed.details,
+        phase: input.outcomePhase,
+        failureSignature: summary.signature,
+        failedAttempts: summary.failedAttempts,
+        suppressedFailures: summary.suppressedFailures,
+        failedForMs: summary.failedForMs,
+      });
+      return summary;
+    },
+    reset() {
+      run = undefined;
+    },
+  };
+}
+
 type TelegramLogPathInput = string | (() => string);
 
 interface TelegramRuntimeJsonlEvent {
@@ -391,6 +503,10 @@ interface TelegramRuntimeDiagnosticsRuntime<TContext> {
     error: unknown,
     details?: Record<string, unknown>,
   ): void;
+  /** A phase-scoped failure log whose records travel through this runtime's own event pipeline. */
+  createFailureLog(
+    input: Omit<TelegramFailureRunLogInput, "record">,
+  ): TelegramFailureRunLog;
   bindStorage(ports: {
     getBotToken(): string | undefined;
     getProfileName(): string | undefined;
@@ -498,6 +614,12 @@ export function createTelegramRuntimeDiagnosticsRuntime<TContext>(
   };
   return {
     events,
+    createFailureLog: (input) =>
+      createTelegramFailureRunLog({
+        ...input,
+        record: (category, errorOrMessage, details) =>
+          recordRuntimeEvent(category, errorOrMessage, details),
+      }),
     recordRuntimeEvent,
     bindStorage(ports) {
       getBotToken = ports.getBotToken;

package/node_modules/@llblab/pi-telegram/lib/paths.ts

@@ -167,13 +167,32 @@ export function resolveTelegramProfileTempFilePath(
   );
 }
 
-export function getTelegramDiagnosticsDisplayPaths(_profileName?: string): {
+/** Shared state/log paths for every profile, under the resolved agent dir (honors `PI_CODING_AGENT_DIR`). */
+export function getTelegramDiagnosticsDisplayPaths(
+  _profileName?: string,
+  agentDir = resolveAgentDir(),
+): {
   state: string;
   logs: string;
 } {
+  // Storage paths are canonical, so also match a canonical home (e.g. /home -> /var/home).
+  const homes = [homedir()];
+  try {
+    homes.push(realpathSync(homes[0]!));
+  } catch {
+    /* An unreadable home only loses the ~ abbreviation. */
+  }
+  const display = (path: string): string => {
+    const home = homes.find(
+      (candidate) => path === candidate || path.startsWith(`${candidate}${sep}`),
+    );
+    return home
+      ? `~${path.slice(home.length).split(sep).join("/")}`
+      : path;
+  };
   return {
-    state: "~/.pi/agent/tmp/pi-telegram/state.json",
-    logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
+    state: display(resolveTelegramStatePath(agentDir)),
+    logs: display(resolveTelegramRuntimeLogPath(agentDir)),
   };
 }
 

package/node_modules/@llblab/pi-telegram/lib/polling.ts

@@ -6,6 +6,16 @@
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Structural port for run-collapsing diagnostics: a repeated identical failure extends its run instead of logging
+ * again, and the closing success records one outcome. The composition root owns the collapsed implementation.
+ */
+export interface TelegramRepeatedFailureLogPort {
+  record: (error: unknown, details?: Record<string, unknown>) => void;
+  settled: () => void;
+  reset: () => void;
+}
+
 export interface TelegramPollingConfig {
   botToken?: string;
 }
@@ -682,6 +692,8 @@ export interface TelegramStartupThreadCapabilityProbeDeps extends TelegramThread
 export interface TelegramThreadCapabilityRuntimeDeps<
   TContext,
 > extends TelegramThreadCapabilityReaderDeps {
+  /** Collapses one sustained probe failure run; the caller supplies its owner. */
+  failureLog: TelegramRepeatedFailureLogPort;
   lifecycle?: TelegramThreadCapabilityLifecycle;
   topicTargetStore: TelegramThreadCapabilityStore;
   ownsLock: (ctx: TContext) => boolean;
@@ -803,6 +815,8 @@ export interface TelegramThreadCapabilityOrchestrationDeps<TContext, TOwner>
   extends
     TelegramThreadCapabilityReaderDeps,
     TelegramThreadAwarePollingControls<TContext, TOwner> {
+  /** Collapses one sustained probe failure run; the composition root supplies its owner. */
+  failureLog: TelegramRepeatedFailureLogPort;
   state: TelegramThreadCapabilityStateRuntime;
   topicTargetStore: TelegramThreadCapabilityStore;
   ownsLock: (ctx: TContext) => boolean;
@@ -882,6 +896,7 @@ export function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(
     isTopicModeUnavailableError: deps.isTopicModeUnavailableError,
     updateStatus: deps.updateStatus,
     recordEvent: deps.recordEvent,
+    failureLog: deps.failureLog,
   };
   return {
     monitor: createTelegramThreadCapabilityMonitor(capabilityDeps),
@@ -1269,8 +1284,34 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
   let generation = 0;
   let transitionPromise: Promise<void> | undefined;
   let consecutiveDisabledProbes = 0;
+  // An absent leader endpoint repeats one identical probe failure every interval; the port collapses the run.
+  // Running it through one guard keeps a faulty diagnostics port from breaking probes or the interval callback.
+  const capabilityFailureLog: TelegramRepeatedFailureLogPort = {
+    record(error, details) {
+      try {
+        deps.failureLog.record(error, details);
+      } catch {
+        // Monitor diagnostics cannot create an uncaught interval exception.
+      }
+    },
+    settled() {
+      try {
+        deps.failureLog.settled();
+      } catch {
+        // Monitor diagnostics cannot fail a completed probe.
+      }
+    },
+    reset() {
+      try {
+        deps.failureLog.reset();
+      } catch {
+        // Monitor diagnostics cannot fail a monitor stop.
+      }
+    },
+  };
   const stop = (): void => {
     generation += 1;
+    capabilityFailureLog.reset();
     if (interval) clearInterval(interval);
     interval = undefined;
     deps.lifecycle?.invalidate();
@@ -1287,6 +1328,7 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
     tracked = readTelegramThreadCapability(deps)
       .then(async (threadModeEnabled) => {
         if (!isCurrent()) return;
+        capabilityFailureLog.settled();
         if (threadModeEnabled === undefined) {
           if (
             deps.topicTargetStore.getBotState().threadMode !== "enabled" &&
@@ -1357,11 +1399,7 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
       })
       .catch((error) => {
         if (!isCurrent()) return;
-        try {
-          deps.recordEvent("bus", error, { phase: "capability-monitor" });
-        } catch {
-          // Monitor diagnostics cannot create an unhandled interval rejection.
-        }
+        capabilityFailureLog.record(error);
       })
       .finally(() => {
         if (transitionPromise === tracked) transitionPromise = undefined;
@@ -1384,11 +1422,7 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
           } catch {
             /* Timer shutdown must not escape the callback. */
           }
-          try {
-            deps.recordEvent("bus", error, { phase: "capability-monitor" });
-          } catch {
-            // Monitor diagnostics cannot create an uncaught interval exception.
-          }
+          capabilityFailureLog.record(error);
         }
       }, intervalMs);
       interval.unref?.();