@llblab/pi-telegram 0.23.0 → 0.23.2

package/docs/outbound.md

@@ -30,7 +30,7 @@ When `assistant.rendering` is `"rich"`, a Telegram-originated turn that queues e
 
 The optimization is deliberately narrow. HTML rendering, empty final text, multiple files, documents and other unsupported formats, Guest Mode, explicit `telegram_voice`, voice-preferred turns, and OGG/Opus artifacts retain their established text/attachment/voice paths. A known-safe Rich upload rejection falls back to those paths. A `commit-unknown` transport outcome or a nominally successful upload without a verifiable message id never falls back or replays because the first non-idempotent send may already have committed.
 
-This behavior does not generate media or alter voice policy. `telegram_attach` still represents an explicit assistant artifact decision, while `manual`, `mirror`, and `always` continue to decide voice synthesis independently.
+This behavior does not generate media or alter voice policy. `telegram_attach` still represents an explicit assistant artifact decision, while `hidden`, `mirror`, and `always` continue to decide voice synthesis independently.
 
 Core assistant output accepts only the Markdown or HTML `InputRichMessage` forms and does not construct explicit block arrays or `InputRichBlockThinking`. Telegram's Thinking block is draft-only and must never become a projection of hidden reasoning or chain-of-thought. Any future use for Activity would require an explicitly public user-visible summary rather than provider reasoning content.
 

package/docs/public-api.md

@@ -93,7 +93,7 @@ interface TelegramConfig {
     proactivePush?: boolean;
   };
   voice?: {
-    replyMode?: "manual" | "mirror" | "always";
+    replyMode?: "hidden" | "mirror" | "always";
     sendTranscript?: boolean;
   };
   time?: {
@@ -106,7 +106,7 @@ interface TelegramConfig {
 Hidden/default semantics are represented by absence:
 
 - `assistant.proactivePush` defaults to `true`; omit it to keep projection enabled, or set it explicitly to `false` to disable it. When enabled, each completed public assistant text block from local or autonomous work is projected to the authorized Telegram target once and in source order. This includes visible intermediate commentary/checkpoints and the final block. It excludes token deltas, hidden reasoning, tool calls/arguments/results, Telegram-owned turns, empty blocks, and stale authority. Projection uses the configured Rich or HTML assistant renderer and binds admitted work to the exact target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation. The old top-level `proactivePush` key is ignored; move the setting manually under `assistant`.
-- Voice Reply `hidden`: no `voice.replyMode` key is persisted.
+- Voice Reply `hidden`: no `voice.replyMode` key is persisted; legacy `manual` resolves to this silent default. `mirror` adds `[voice] delivery: automatic voice` only to voice/audio-input turns, while `always` adds the same effective line to every Telegram turn.
 - Agent activity status is not configurable in this release. Telegram uses native `sendChatAction(typing)` / product `...active` status as the only automatic in-chat work signal before the final reply.
 - Time Injection `hidden`: no `time.injectionMode` key is persisted; if `time` becomes empty, the whole `time` object may be omitted.
 

package/docs/ui-style.md

@@ -171,8 +171,8 @@ Rules:
 
 Examples:
 
+- `hidden`
 - `🟢 mirror`
-- `manual`
 - `always`
 
 ## Navigation

package/docs/voice.md

@@ -33,14 +33,13 @@ Voice provider extensions can also register STT backends with `registerTelegramV
 
 ## Voice Reply Policy
 
-The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). If config does not set a valid mode, the bridge uses the `hidden` default: manual behavior without adding voice policy text to the prompt context.
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing, invalid, `hidden`, and legacy `manual` values resolve to the silent `hidden` default.
 
 ### Modes
 
-- **`hidden` (default):** no `voice.replyMode` is stored; same behavior as manual, no prompt voice context.
-- **`manual`:** only reply with voice when the agent authors `<!-- telegram_voice -->` markup; explicit prompt context is added.
-- **`mirror`:** reply with voice when the inbound message was a voice note or audio file. Text input stays on the manual path where explicit `telegram_voice` markup still works.
-- **`always`:** always reply with voice.
+- **`hidden` (default):** no `voice.replyMode` is stored and no automatic voice context is added; explicit agent-authored `telegram_voice` actions still work.
+- **`mirror`:** voice/audio input activates automatic voice delivery. Text input follows `hidden` behavior.
+- **`always`:** every Telegram turn activates automatic voice delivery.
 
 **Warning:** In `always` mode, the bridge transparently intercepts ALL text replies and converts them to voice on success. Users will only receive voice messages when voice generation succeeds. If voice generation fails, the bridge falls back to sending the planned text reply.
 
@@ -97,7 +96,7 @@ Registration returns a disposer function for cleanup. Stable provider registrati
 
 ## Outbound Voice Handlers
 
-Users can also configure `outboundHandlers` with `type: "voice"` in `telegram.json`. This is the command-template path for TTS without a provider extension. Reply modes (`manual`, `mirror`, `always`) affect these handlers the same way they affect providers: explicit `telegram_voice` blocks and automatic mirror/always interception both produce a voice reply plan, then delivery tries configured outbound voice handlers first and registered synthesis providers as progressive fallbacks.
+Users can also configure `outboundHandlers` with `type: "voice"` in `telegram.json`. This is the command-template path for TTS without a provider extension. Reply modes (`hidden`, `mirror`, `always`) affect these handlers the same way they affect providers: explicit `telegram_voice` blocks and automatic mirror/always interception both produce a voice reply plan, then delivery tries configured outbound voice handlers first and registered synthesis providers as progressive fallbacks.
 
 Voice handlers receive the text on stdin in composed pipelines and can use `{text}`, `{lang}`, `{rate}`, `{mp3}`, and `{ogg}` placeholders. Set `output` to `"ogg"` or another placeholder name when the template writes to a known path:
 
@@ -167,7 +166,7 @@ Voice provider extensions can register a Voice Extension Section (settings UI) v
 
 ## Prompt Guidance
 
-The bridge keeps voice prompt context compact and policy-owned. It adds `[voice] reply mode: ...` only when `telegram.json` explicitly contains a valid `voice.replyMode`. `hidden`/no configured mode behaves like manual, but prompts stay silent. When explicit, voice-originated `manual` turns add `[voice] reply mode: manual`, voice-originated `mirror` turns add `[voice] reply mode: mirror`, and `always` mode adds `[voice] reply mode: always` for every turn. If voice context later contains multiple fields, the bridge renders it as a `[voice]` list. The marker is appended after `[outputs]` when handler output exists, otherwise after `[attachments]`. Voice inputs also appear in `[attachments]` with their downloaded file names, MIME data, and handler output, so agents can infer concrete voice-file context from attachment metadata.
+The bridge keeps voice prompt context compact, effective, and policy-owned. `hidden` and text-originated `mirror` turns add no voice line. Voice/audio-originated `mirror` turns and every `always` turn add exactly `[voice] delivery: automatic voice`, describing the current delivery environment without exposing the underlying mode matrix or an instruction list. The marker is appended after `[outputs]` when handler output exists, otherwise after `[attachments]`. Voice inputs also appear in `[attachments]` with their downloaded file names, MIME data, and handler output, so agents can infer concrete voice-file context from attachment metadata.
 
 Voice synthesis providers can supply prompt guidance through `getVoicePromptContribution(view)`, but provider text should stay optional and provider-specific. Reply-mode context belongs to pi-telegram.
 
@@ -204,12 +203,12 @@ Voice synthesis providers can supply prompt guidance through `getVoicePromptCont
 ```json
 {
   "voice": {
-    "replyMode": "manual"
+    "replyMode": "mirror"
   }
 }
 ```
 
-Valid stored values: `"manual"`, `"mirror"`, `"always"`. Missing or invalid values are shown in Settings as `hidden`, behave like manual, and stay silent in prompt context.
+Valid modes are `"hidden"`, `"mirror"`, and `"always"`; selecting `hidden` removes the key. Missing, invalid, and legacy `"manual"` values resolve to `hidden` and stay silent in prompt context.
 
 The bridge reads `voice.replyMode` from the config when building a turn.
 

package/index.ts

@@ -155,11 +155,6 @@ export default function (pi: Pi.ExtensionAPI) {
       contextStore: telegramSessionContextStore,
     });
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
-  const proactivePushChatIdGetter =
-    Config.createTelegramProactivePushChatIdGetter({
-      getActiveTurnChatId: activeTurnRuntime.getChatId,
-      getAllowedUserId: configStore.getAllowedUserId,
-    });
   const proactivePushTargetGetter =
     Config.createTelegramProactivePushTargetGetter({
       getActiveTurnTarget: activeTurnRuntime.getTarget,
@@ -171,6 +166,8 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getAllowedUserId: configStore.getAllowedUserId,
     });
+  const proactivePushChatIdGetter =
+    Config.createTelegramProactivePushChatIdGetter(proactivePushTargetGetter);
   const buttonActionStore = Outbound.createTelegramButtonActionStore();
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
@@ -225,6 +222,11 @@ export default function (pi: Pi.ExtensionAPI) {
       persist: configStore.persist,
       markConfigChange: telegramSyncStateRuntime.markConfigChange,
     });
+  const persistTelegramPollingOffset =
+    Config.createTelegramPollingOffsetPersister(
+      configStore,
+      persistTelegramConfigWithSync,
+    );
   const currentInstanceThreadRuntime =
     Threads.createTelegramCurrentInstanceThreadRuntime({
       instanceId: telegramInstanceId,
@@ -825,7 +827,7 @@ export default function (pi: Pi.ExtensionAPI) {
     hasBotToken: configStore.hasBotToken,
     deleteWebhook,
     getUpdates,
-    persistConfig: persistTelegramConfigWithSync,
+    persistConfig: persistTelegramPollingOffset,
     prepareUpdateBatch: textGroupRuntime.prepareUpdateBatch,
     handleUpdate: Updates.createTelegramUpdateHandle({
       defaultHandle: inboundRouteRuntime.handleUpdate,
@@ -1067,7 +1069,6 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteMessage: deleteTelegramMessage,
     sendGuestReply,
     finalizeMarkdownPreview,
-    proactivePushChatIdGetter,
     proactivePushTargetGetter,
     isProactivePushEnabled: configControls.isProactivePushEnabled,
     getAssistantRenderingMode: configControls.getAssistantRenderingMode,

package/lib/bindings.ts

@@ -36,9 +36,7 @@ type TelegramRuntimeEventRecorder = (
 type TelegramBridgeStatusUpdater =
   Status.TelegramStatusRuntime<Pi.ExtensionContext>["updateStatus"];
 
-export interface TelegramAssistantOutputBindingRuntime<
-  TTransportStamp,
-> {
+export interface TelegramAssistantOutputBindingRuntime<TTransportStamp> {
   runtime: Activity.TelegramAssistantOutputRuntime;
   observeEvent: (event: Activity.TelegramActivityEvent) => void;
   authority: Routing.TelegramAssistantOutputAuthorityRuntime<TTransportStamp>;
@@ -49,7 +47,9 @@ export function createTelegramAssistantOutputBindingRuntime<
 >(deps: {
   isEnabled: () => boolean;
   authority: {
-    getPreferredTarget: () => OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"] | undefined;
+    getPreferredTarget: () =>
+      | OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"]
+      | undefined;
     getFallbackChatId: () => number | undefined;
     getTransportStamp: () => TTransportStamp;
     isTransportStampActive: (stamp: TTransportStamp) => boolean;
@@ -63,8 +63,9 @@ export function createTelegramAssistantOutputBindingRuntime<
   >[0];
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }): TelegramAssistantOutputBindingRuntime<TTransportStamp> {
-  const authority =
-    Routing.createTelegramAssistantOutputAuthorityRuntime(deps.authority);
+  const authority = Routing.createTelegramAssistantOutputAuthorityRuntime(
+    deps.authority,
+  );
   const send =
     OutboundHandlers.createTelegramAssistantOutputSender<TTransportStamp>(
       deps.sender,
@@ -344,7 +345,6 @@ interface TelegramLifecycleBindingDeps {
     Pi.AgentEndEvent["messages"][number],
     Keyboard.TelegramInlineKeyboardMarkup
   >["finalizeMarkdownPreview"];
-  proactivePushChatIdGetter: () => number | undefined;
   proactivePushTargetGetter: () => Queue.TelegramQueueTarget | undefined;
   isProactivePushEnabled: () => boolean;
   getAssistantRenderingMode: () => "rich" | "html";
@@ -387,7 +387,6 @@ export function registerTelegramLifecycleRuntimeHooks({
   deleteMessage,
   sendGuestReply,
   finalizeMarkdownPreview,
-  proactivePushChatIdGetter,
   proactivePushTargetGetter,
   isProactivePushEnabled,
   getAssistantRenderingMode,
@@ -425,7 +424,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     caption?: string,
   ): Promise<void> => {
     const stagingTarget = proactivePushTargetGetter();
-    const stagingChatId = stagingTarget?.chatId ?? proactivePushChatIdGetter();
+    const stagingChatId = stagingTarget?.chatId;
     if (stagingChatId === undefined) {
       throw new Error(
         "Guest attachment staging requires a paired Telegram chat",
@@ -470,7 +469,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     caption?: string,
   ): Promise<void> => {
     const stagingTarget = proactivePushTargetGetter();
-    const stagingChatId = stagingTarget?.chatId ?? proactivePushChatIdGetter();
+    const stagingChatId = stagingTarget?.chatId;
     if (stagingChatId === undefined) {
       throw new Error("Guest voice staging requires a paired Telegram chat");
     }
@@ -595,11 +594,9 @@ export function registerTelegramLifecycleRuntimeHooks({
     if (!canSendAgentActivity(ctx)) return false;
     const turn = activeTurnRuntime.get();
     const target = turn?.target ?? proactivePushTargetGetter();
-    promptDispatchRuntime.startTypingLoop(
-      ctx,
-      turn?.chatId ?? target?.chatId ?? proactivePushChatIdGetter(),
-      { target },
-    );
+    promptDispatchRuntime.startTypingLoop(ctx, turn?.chatId ?? target?.chatId, {
+      target,
+    });
     return true;
   };
   const startActiveTurnTypingLoop = (ctx: Pi.ExtensionContext): void => {
@@ -644,6 +641,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      agentLifecycleHooks.clearRetainedAgentEnd();
       activityRuntime.onSessionShutdown();
       assistantOutputRuntime.stop();
       compactionObserver.onSessionShutdown();
@@ -710,8 +708,9 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityRuntime.onAgentEnd();
       await agentLifecycleHooks.onAgentEnd(event, ctx);
     },
-    onAgentSettled(_event, ctx) {
+    async onAgentSettled(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      await agentLifecycleHooks.onAgentSettled(event, ctx);
       activityRuntime.onAgentSettled();
     },
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({

package/lib/bus-leader.ts

@@ -109,17 +109,10 @@ export interface TelegramBusFollowerTargetProvisionerDeps {
   ) => void;
 }
 
-export interface TelegramBusFollowerPruneHandlerDeps {
+export interface TelegramBusFollowerDisconnectHandlerDeps {
   topicTargetStore: Pick<
     Threads.TelegramTopicTargetStore,
-    | "load"
-    | "getActiveByInstanceId"
-    | "list"
-    | "listPendingProvisions"
-    | "markStaleByTarget"
-    | "markOfflineByInstanceId"
-    | "persist"
-    | "removePendingProvision"
+    "markOfflineByInstanceId" | "persist"
   >;
   callApi: <TResponse>(
     method: string,
@@ -161,11 +154,9 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
   runtime: Omit<
     TelegramBusLeaderRuntimeDeps<TContext>,
     | "callApi"
-    | "onFollowerPruned"
     | "onFollowerDisconnected"
     | "provisionFollowerTarget"
     | "provisionLeaderTarget"
-    | "reconcileFollowerBindings"
     | "recordRuntimeEvent"
   >;
   getAllowedUserId: () => number | undefined;
@@ -218,9 +209,6 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
       recordThreadReconciliationPlan: deps.recordThreadReconciliationPlan,
       setLeaderTarget: deps.setLeaderTarget,
     }),
-    onFollowerPruned: createTelegramBusFollowerPruneHandler({
-      ...provisionerPorts,
-    }),
     onFollowerDisconnected: createTelegramBusFollowerDisconnectHandler({
       ...provisionerPorts,
     }),
@@ -228,12 +216,6 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
       ...provisionerPorts,
     }),
     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
-    reconcileFollowerBindings:
-      createTelegramBusFollowerBindingRealityReconciler({
-        topicTargetStore: deps.topicTargetStore,
-        followerRegistry: deps.runtime.followerRegistry,
-        recordRuntimeEvent: deps.recordRuntimeEvent,
-      }),
     callApi: createTelegramBusLeaderApiProxy({
       call: deps.callApi,
       callMultipart: deps.callMultipart,
@@ -244,29 +226,6 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
   });
 }
 
-export const TELEGRAM_BUS_RECENT_FOLLOWER_BINDING_GRACE_MS = 10_000;
-
-export interface TelegramBusFollowerBindingRealityDeps {
-  topicTargetStore: Pick<
-    Threads.TelegramTopicTargetStore,
-    | "load"
-    | "list"
-    | "markOfflineByInstanceId"
-    | "forgetIdentityByProfileKey"
-    | "getBotState"
-    | "persist"
-    | "setBotState"
-  >;
-  followerRegistry: Pick<TelegramBusFollowerRegistry, "list">;
-  getNowMs?: () => number;
-  recentBindingGraceMs?: number;
-  recordRuntimeEvent: (
-    category: string,
-    error: unknown,
-    details?: Record<string, unknown>,
-  ) => void;
-}
-
 export interface TelegramBusFollowerMessageOwnershipRecord {
   follower: TelegramBusFollowerView;
   chatId: number;
@@ -296,15 +255,10 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     registration: TelegramBusInstanceRegistration,
   ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
   getCurrentLeaderEpoch?: () => number | string | undefined;
-  reconcileFollowerBindings?: () => Promise<unknown> | unknown;
   provisionLeaderTarget?: (ctx: TContext) => Promise<void> | void;
   getNowMs?: () => number;
   followerPruneIntervalMs?: number;
   followerStaleAfterMs?: number;
-  followerRecoveryGraceMs?: number;
-  onFollowerPruned?: (
-    follower: TelegramBusFollowerView,
-  ) => Promise<void> | void;
   onFollowerDisconnected?: (
     follower: TelegramBusFollowerView,
   ) => Promise<void> | void;
@@ -315,23 +269,11 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   ) => void;
 }
 
-export function createTelegramBusFollowerBindingRealityReconciler(
-  deps: TelegramBusFollowerBindingRealityDeps,
-): () => Promise<number> {
-  return async () => {
-    await deps.topicTargetStore.load();
-    // A missing live registration proves only that the follower process is
-    // currently absent. Keep its durable owner/target binding so a replacement
-    // process with the same manual profile can reclaim the existing thread.
-    return 0;
-  };
-}
-
 export function createTelegramBusInstanceLifecycleAnnouncement(input: {
   target: TelegramTarget & { threadId: number };
   threadName?: string;
   slot?: string;
-  state: "connected" | "disconnected";
+  state: "connected";
 }): TelegramBusFollowerLifecycleAnnouncement {
   return {
     target: { ...input.target },
@@ -340,23 +282,6 @@ export function createTelegramBusInstanceLifecycleAnnouncement(input: {
   };
 }
 
-export function createTelegramBusFollowerDisconnectedAnnouncement(input: {
-  follower: TelegramBusFollowerView;
-  threadName?: string;
-  slot?: string;
-}): TelegramBusFollowerLifecycleAnnouncement | undefined {
-  if (!input.follower.target?.threadId) return undefined;
-  return createTelegramBusInstanceLifecycleAnnouncement({
-    target: {
-      chatId: input.follower.target.chatId,
-      threadId: input.follower.target.threadId,
-    },
-    threadName: input.threadName,
-    slot: input.slot,
-    state: "disconnected",
-  });
-}
-
 const TELEGRAM_BUS_SLOW_FOLLOWER_REGISTRATION_MS = 1000;
 
 function scheduleTelegramBusLeaderBackgroundTask(
@@ -753,23 +678,8 @@ export function createTelegramBusFollowerTargetProvisioner(
   };
 }
 
-export function createTelegramBusFollowerPruneHandler(
-  deps: TelegramBusFollowerPruneHandlerDeps,
-): (follower: TelegramBusFollowerView) => Promise<void> {
-  return async (follower) => {
-    deps.recordRuntimeEvent(
-      "bus",
-      "Telegram bus follower heartbeat stale; preserving thread binding",
-      {
-        phase: "follower-pruned",
-        instanceId: follower.instanceId,
-      },
-    );
-  };
-}
-
 export function createTelegramBusFollowerDisconnectHandler(
-  deps: TelegramBusFollowerPruneHandlerDeps,
+  deps: TelegramBusFollowerDisconnectHandlerDeps,
 ): (follower: TelegramBusFollowerView) => Promise<void> {
   return async (follower) => {
     const target = follower.target;
@@ -1458,32 +1368,12 @@ export function createTelegramBusLeaderRuntime<TContext>(
   const getNowMs = deps.getNowMs ?? Date.now;
   const followerPruneIntervalMs = deps.followerPruneIntervalMs ?? 1000;
   const followerStaleAfterMs = deps.followerStaleAfterMs ?? 5000;
-  const followerRecoveryGraceMs = deps.followerRecoveryGraceMs ?? 5000;
   let pruneInterval: ReturnType<typeof setInterval> | undefined;
-  let followerRealityTimer: ReturnType<typeof setTimeout> | undefined;
   const stopPruning = () => {
     if (!pruneInterval) return;
     clearInterval(pruneInterval);
     pruneInterval = undefined;
   };
-  const stopFollowerRealityTimer = () => {
-    if (!followerRealityTimer) return;
-    clearTimeout(followerRealityTimer);
-    followerRealityTimer = undefined;
-  };
-  const scheduleFollowerBindingReality = () => {
-    stopFollowerRealityTimer();
-    if (!deps.reconcileFollowerBindings) return;
-    followerRealityTimer = setTimeout(() => {
-      followerRealityTimer = undefined;
-      void Promise.resolve(deps.reconcileFollowerBindings?.()).catch((error) =>
-        deps.recordRuntimeEvent?.("bus", error, {
-          phase: "follower-binding-reality",
-        }),
-      );
-    }, followerRecoveryGraceMs);
-    followerRealityTimer.unref?.();
-  };
   const pruneFollowers = async () => {
     try {
       await localServer.ensureEndpoint();
@@ -1497,18 +1387,14 @@ export function createTelegramBusLeaderRuntime<TContext>(
       followerStaleAfterMs,
     );
     for (const follower of removed) {
-      try {
-        await deps.onFollowerPruned?.(follower);
-      } catch (error) {
-        deps.recordRuntimeEvent?.("bus", error, {
-          phase: "follower-prune-offline",
+      deps.recordRuntimeEvent?.(
+        "bus",
+        "Telegram bus follower heartbeat stale; preserving thread binding",
+        {
+          phase: "follower-pruned",
           instanceId: follower.instanceId,
-        });
-      }
-      deps.recordRuntimeEvent?.("bus", "Telegram bus follower timed out", {
-        phase: "follower-prune",
-        instanceId: follower.instanceId,
-      });
+        },
+      );
     }
   };
   const startPruning = () => {
@@ -1542,21 +1428,18 @@ export function createTelegramBusLeaderRuntime<TContext>(
   return {
     startPolling: async (ctx) => {
       await localServer.start();
-      scheduleFollowerBindingReality();
       startPruning();
       try {
         await deps.provisionLeaderTarget?.(ctx);
         await deps.startPolling(ctx);
       } catch (error) {
         stopPruning();
-        stopFollowerRealityTimer();
         await localServer.stop();
         throw error;
       }
     },
     stopPolling: async () => {
       stopPruning();
-      stopFollowerRealityTimer();
       try {
         await deps.stopPolling();
       } finally {

package/lib/config.ts

@@ -17,8 +17,8 @@ import {
 import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
 import { resolveAgentDir, resolveTelegramConfigPath } from "./paths.ts";
 
-import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
+import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import { withTelegramFileTransaction } from "./locks.ts";
 
 const CONFIG_RUNTIME_KEY = "__piTelegramConfigRuntime__";
@@ -72,7 +72,7 @@ export interface TelegramConfig {
   /** @deprecated use assistant.rendering */
   assistantRendering?: TelegramAssistantRenderingMode;
   voice?: {
-    replyMode?: "manual" | "mirror" | "always";
+    replyMode?: "hidden" | "mirror" | "always";
     /** Whether to attach the provider's transcriptText as caption on voice messages */
     sendTranscript?: boolean;
   };
@@ -543,6 +543,27 @@ export function createTelegramConfigStore(
   };
 }
 
+export function createTelegramPollingOffsetPersister(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+  persist: () => Promise<void> = () => configStore.persist(),
+): (pollingConfig: { lastUpdateId?: number }) => Promise<void> {
+  return async (pollingConfig) => {
+    const nextOffset = pollingConfig.lastUpdateId;
+    if (typeof nextOffset === "number") {
+      const current = configStore.get();
+      const currentOffset = current.lastUpdateId;
+      configStore.set({
+        ...current,
+        lastUpdateId:
+          typeof currentOffset === "number"
+            ? Math.max(currentOffset, nextOffset)
+            : nextOffset,
+      });
+    }
+    await persist();
+  };
+}
+
 export function createTelegramProactivePushChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
@@ -625,12 +646,10 @@ export function createTelegramAssistantRenderingModeSetter(
 
 export function createTelegramVoiceReplyModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
-): () => "manual" | "mirror" | "always" {
+): () => "hidden" | "mirror" | "always" {
   return () => {
     const mode = configStore.get().voice?.replyMode;
-    return mode === "mirror" || mode === "always" || mode === "manual"
-      ? mode
-      : "manual";
+    return mode === "mirror" || mode === "always" ? mode : "hidden";
   };
 }
 
@@ -639,17 +658,17 @@ export function createTelegramVoiceReplyModeConfiguredChecker(
 ): () => boolean {
   return () => {
     const mode = configStore.get().voice?.replyMode;
-    return mode === "mirror" || mode === "always" || mode === "manual";
+    return mode === "mirror" || mode === "always";
   };
 }
 
 export function createTelegramVoiceReplyModeSetter(
   configStore: TelegramMutableConfigStore,
-): (replyMode: "manual" | "mirror" | "always" | undefined) => Promise<void> {
+): (replyMode: "hidden" | "mirror" | "always" | undefined) => Promise<void> {
   return async (replyMode) => {
     await loadLatestTelegramConfig(configStore);
     const current = configStore.get();
-    if (replyMode === undefined) {
+    if (replyMode === undefined || replyMode === "hidden") {
       const { replyMode: _replyMode, ...remainingVoice } = current.voice ?? {};
       const next = { ...current };
       if (Object.keys(remainingVoice).length > 0) next.voice = remainingVoice;
@@ -730,11 +749,10 @@ export interface TelegramProactivePushTarget {
   threadId?: number;
 }
 
-export function createTelegramProactivePushChatIdGetter(deps: {
-  getActiveTurnChatId: () => number | undefined;
-  getAllowedUserId: () => number | undefined;
-}): () => number | undefined {
-  return () => deps.getActiveTurnChatId() ?? deps.getAllowedUserId();
+export function createTelegramProactivePushChatIdGetter(
+  getTarget: () => TelegramProactivePushTarget | undefined,
+): () => number | undefined {
+  return () => getTarget()?.chatId;
 }
 
 export function createTelegramProactivePushTargetGetter(deps: {