@llblab/pi-kit 0.1.8 → 0.1.10

package/node_modules/@llblab/pi-telegram/docs/voice.md

@@ -43,12 +43,12 @@ 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`). Missing, invalid, `hidden`, and legacy `manual` values resolve to the silent `hidden` default.
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing and invalid values resolve to the `manual` default; the former `hidden` value remains a read-only compatibility alias for `manual`.
 
 ### Modes
 
-- **`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.
+- **`manual` (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 `manual` 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.
@@ -70,7 +70,7 @@ A voice extension may combine three public seams:
 
 - `registerTelegramVoiceTranscriptionProvider()` for inbound STT fallback on voice/audio files
 - `registerTelegramVoiceSynthesisProvider()` for outbound TTS/synthesis fallback to Telegram voice messages
-- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, transcript, or provider on/off controls
+- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, or provider on/off controls
 
 The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode`) rather than a provider-owned menu.
 
@@ -81,10 +81,8 @@ Voice synthesis provider extensions register themselves through `registerTelegra
 - Text optimisation / speech-style rewriting
 - Adding speech tags (when desired)
 - Running TTS + ffmpeg conversion to OGG/Opus
-- Deciding whether to return `transcriptText` at all based on the bridge-owned `voice.sendTranscript` preference when the provider has access to the current Telegram config
-- `transcriptText` (when returned) is attached by the bridge as the voice message **caption** only. Separate transcript messages are no longer sent.
 
-The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`. When a provider returns `transcriptText`, the bridge attaches it as the voice caption.
+The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`.
 
 Providers can implement `getVoicePromptContribution(view)` to inject voice-specific instructions into voice-tagged prompts (for example: "Reply only with the spoken text"). The bridge appends the first non-empty provider contribution when `mirror` or `always` mode tags the turn.
 
@@ -95,7 +93,6 @@ The provider receives the raw agent text plus optional `{ lang?, rate? }`.
 It must return one of:
 
 - `string` — path to a ready `.ogg` or `.opus` file
-- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. Providers should treat pi-telegram's `voice.sendTranscript` as the bridge-owned transcript preference instead of inventing a second reply-policy UI.
 - `undefined` — skip this text block
 
 **Important:** Providers are fully responsible for producing a clean, TTS-optimised native voice file. The bridge may also run configured outbound voice command templates for users who prefer process-boundary handlers instead of provider extensions.
@@ -106,7 +103,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 (`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.
+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.
 
 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:
 
@@ -128,31 +125,6 @@ Voice handlers receive the text on stdin in composed pipelines and can use `{tex
 
 Priority for outbound voice delivery is: configured `outboundHandlers` with `type: "voice"` in their `telegram.json` order, then programmatic `voice` outbound handlers, then registered voice synthesis providers. Provider extensions are the zero-config tail of the same pipeline: they handle voice when no explicit configured handler succeeds, but they do not override operator-configured handlers. If multiple providers are registered, only one handles a given voice reply: the first provider that returns a valid `.ogg`/`.opus` artifact wins. Providers that return `undefined` explicitly pass to the next provider; providers that throw or return invalid output are recorded and the next fallback is tried.
 
-### Provider with transcript caption (controlled by user toggle)
-
-When the user's "Send Transcript" toggle is ON, return the clean spoken text as `transcriptText`. The bridge attaches it as the caption on the voice message. When the toggle is OFF, return only the audio path (no `transcriptText`).
-
-```typescript
-import {
-  getTelegramVoiceSendTranscript,
-  registerTelegramVoiceSynthesisProvider,
-} from "@llblab/pi-telegram/voice";
-
-registerTelegramVoiceSynthesisProvider(
-  async (text, options) => {
-    const rewritten = rewriteWithSpeechTags(text);
-    const audioPath = await myTTS(rewritten, { language: options?.lang });
-    const sendTranscript = getTelegramVoiceSendTranscript(
-      getCurrentTelegramConfigView(),
-    );
-    return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
-  },
-  { id: "my-voice-provider/tts" },
-);
-```
-
-`getCurrentTelegramConfigView()` represents whatever current `TelegramConfig` view your extension already owns or receives; pi-telegram does not require providers to read config directly. The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
-
 ### Surfacing provider diagnostics
 
 Voice provider extensions can record runtime events that appear in `/telegram-status` alongside pi-telegram's own events:
@@ -170,13 +142,13 @@ recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
 
 ## Voice Extension Section
 
-Voice provider extensions can register a Voice Extension Section (settings UI) via `registerTelegramSection`. The section can expose provider-specific controls such as TTS voice, language, speech style, transcript behavior, or STT/TTS enablement. Reply mode is a core pi-telegram setting and belongs in the built-in Settings menu.
+Voice provider extensions can register a Voice Extension Section (settings UI) via `registerTelegramSection`. The section can expose provider-specific controls such as TTS voice, language, speech style, or STT/TTS enablement. Reply mode is a core pi-telegram setting and belongs in the built-in Settings menu.
 
 **Note on resume:** Because the previous automatic persistent re-registration system has been removed, extensions are responsible for re-registering their Voice Extension Section on `session_start` if they want the menu to survive a `pi resume`. See `registerTelegramSection` from `@llblab/pi-telegram/sections`.
 
 ## Prompt Guidance
 
-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.
+The bridge keeps voice prompt context compact, effective, and policy-owned. `manual` 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.
 
@@ -224,4 +196,4 @@ The bridge reads `voice.replyMode` from the config when building a turn.
 
 ### Provider config
 
-Provider-specific settings (voice ID, language, speech style, transcript behavior, STT/TTS enablement) are owned by the voice provider extension. Reply mode is owned by pi-telegram's `voice.replyMode` and configured from the built-in pi-telegram Settings menu, not duplicated in provider UIs.
+Provider-specific settings (voice ID, language, speech style, STT/TTS enablement) are owned by the voice provider extension. Reply mode is owned by pi-telegram's `voice.replyMode` and configured from the built-in pi-telegram Settings menu, not duplicated in provider UIs.

package/node_modules/@llblab/pi-telegram/index.ts

@@ -359,6 +359,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,
     hasPendingModelSwitch: pendingModelSwitchStore.has,
     getQueuedItems: telegramQueueStore.getQueuedItems,
+    getQueuedItemCount: Queue.countExecutableTelegramQueueItems,
     formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
     getRecentRuntimeEvents: runtimeEvents.getEvents,
     getRuntimeLockState: lockRuntime.getStatusLabel,
@@ -415,6 +416,8 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getRegistrationGeneration:
         telegramBusFollowerRegistrationState.getGeneration,
+      waitForRegistrationGeneration:
+        telegramBusFollowerRegistrationState.waitForGeneration,
       getForwardCommentBatchPosition:
         textGroupRuntime.getPreparedForwardingPosition,
       recordRuntimeEvent,
@@ -841,6 +844,16 @@ export default function (pi: Pi.ExtensionAPI) {
         });
       },
     );
+  const staleTopicApiErrorRecoveryDeps = {
+    topicTargetStore: threadStore,
+    getSyncState: telegramSyncStateRuntime.getState,
+    setSyncState: telegramSyncStateRuntime.setState,
+    recordEvent: recordRuntimeEvent,
+  };
+  const recoverStaleTelegramTopicApiError =
+    Sync.createTelegramStaleTopicApiErrorRecoveryRuntime(
+      staleTopicApiErrorRecoveryDeps,
+    );
   const {
     owner: updateWorkerOwnerRuntime,
     leader: updateAdmissionLifecycleRuntime,
@@ -864,6 +877,12 @@ export default function (pi: Pi.ExtensionAPI) {
     worker: {
       defaultHandle: inboundRouteRuntime.handleUpdate,
       onStateChange: runtimeDiagnostics.scheduleSnapshotPersist,
+      settleTerminalExecutionFailure(error) {
+        return Sync.settleStaleTelegramTopicExecutionFailure(
+          error,
+          staleTopicApiErrorRecoveryDeps,
+        );
+      },
     },
     leader: {
       resolveBinding: resolveTelegramUpdateJournalBinding,
@@ -1053,13 +1072,6 @@ export default function (pi: Pi.ExtensionAPI) {
       onPollingStateChange: runtimeDiagnostics.scheduleSnapshotPersist,
       recordRuntimeEvent,
     });
-  const recoverStaleTelegramTopicApiError =
-    Sync.createTelegramStaleTopicApiErrorRecoveryRuntime({
-      topicTargetStore: threadStore,
-      getSyncState: telegramSyncStateRuntime.getState,
-      setSyncState: telegramSyncStateRuntime.setState,
-      recordEvent: recordRuntimeEvent,
-    });
   const authorizeFollowerApiCall = Bus.createTelegramFollowerApiCallAuthorizer({
     isMessageOwned: messageOwnershipRuntime.isOwnedByFollower,
   });
@@ -1232,6 +1244,7 @@ export default function (pi: Pi.ExtensionAPI) {
         prepareTempDir,
         updateStatus,
         unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
+        discardQueuedItems: queueMutationRuntime.clear,
         clearModelMenuState: modelMenuRuntime.clear,
         getActiveTurnChatId: activeTurnRuntime.getChatId,
         getActiveTurnTarget: activeTurnRuntime.getTarget,

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

@@ -95,11 +95,28 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
   sendUserMessage: Queue.TelegramQueueDispatchRuntimeDeps<TContext>["sendUserMessage"];
   recordRuntimeEvent?: TelegramRuntimeEventRecorder;
 }): TelegramQueueBindingRuntime<TContext> {
+  const settleDiscardedItems = (
+    items: readonly Queue.TelegramQueueItem<TContext>[],
+    ctx: TContext,
+  ): boolean => {
+    const durableItems = items.filter(
+      (item) => (item.admissionReceipts?.length ?? 0) > 0,
+    );
+    if (durableItems.length === 0) return true;
+    const settlement = deps.admission.getSettlement();
+    if (!settlement) return false;
+    settlement.onItemsDiscarded(durableItems, ctx);
+    return durableItems.every((item) => !settlement.isItemReady(item));
+  };
   const mutation = Queue.createTelegramQueueMutationController({
     ...deps.store,
     allocateLaneOrder: deps.queue.allocateItemOrder,
     onItemsDiscarded(items, ctx) {
-      deps.admission.getSettlement()?.onItemsDiscarded(items, ctx);
+      if (!settleDiscardedItems(items, ctx)) {
+        throw new Error(
+          "Telegram queue items could not be discarded durably.",
+        );
+      }
     },
     updateStatus: deps.updateStatus,
     recordRuntimeEvent: deps.recordRuntimeEvent,
@@ -136,6 +153,9 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
     onControlSettled(item, ctx) {
       deps.admission.getSettlement()?.onControlSettled(item, ctx);
     },
+    onPromptSkipped(item, ctx) {
+      return settleDiscardedItems([item], ctx);
+    },
     updateStatus: deps.updateStatus,
     sendTextReply: deps.sendTextReply,
     recordRuntimeEvent: deps.recordRuntimeEvent,
@@ -909,6 +929,25 @@ export function registerTelegramLifecycleRuntimeHooks({
       { replyToPrompt: false },
     );
   };
+  let activeTurnDeliveryTail = Promise.resolve();
+  const scheduleActiveTurnDelivery = (task: () => Promise<void>): void => {
+    const previous = activeTurnDeliveryTail;
+    activeTurnDeliveryTail = (async () => {
+      await previous;
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, 0);
+        timer.unref?.();
+      });
+      await task();
+    })().catch((error) => {
+      recordRuntimeEvent("delivery", error, {
+        phase: "agent-end-background-delivery",
+      });
+    });
+  };
+  const waitForActiveTurnDelivery = async (): Promise<void> => {
+    await activeTurnDeliveryTail;
+  };
   const agentLifecycleHooks = Queue.createTelegramAgentLifecycleHooks<
     Queue.PendingTelegramTurn,
     Pi.ExtensionContext,
@@ -950,16 +989,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     dispatchNextQueuedTelegramTurn,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
-    scheduleActiveTurnDelivery(task) {
-      const timer = setTimeout(() => {
-        void task().catch((error) => {
-          recordRuntimeEvent("delivery", error, {
-            phase: "agent-end-background-delivery",
-          });
-        });
-      }, 0);
-      timer.unref?.();
-    },
+    scheduleActiveTurnDelivery,
     clearPreview: previewRuntime.clear,
     setPreviewPendingText: previewRuntime.setPendingText,
     finalizeMarkdownPreview,
@@ -1079,7 +1109,11 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityRuntime.onCompactionStart(Pi.getSessionCompactionReason(event));
       compactionObserver.onSessionBeforeCompact(event, ctx);
       if (shouldNotify) {
-        await sendCompactionNotice(Commands.TELEGRAM_COMPACTION_STARTED_TEXT);
+        await waitForActiveTurnDelivery();
+        if (!isSessionContextActive(ctx)) return;
+        await sendCompactionNotice(
+          Commands.TELEGRAM_COMPACTION_STARTED_MARKDOWN,
+        );
       }
     },
     async onSessionCompact(event, ctx) {
@@ -1088,7 +1122,9 @@ export function registerTelegramLifecycleRuntimeHooks({
       compactionObserver.onSessionCompact(event, ctx);
       if (observedAutomaticCompaction) {
         observedAutomaticCompaction = false;
-        await sendCompactionNotice(Commands.TELEGRAM_COMPACTION_COMPLETED_TEXT);
+        await sendCompactionNotice(
+          Commands.TELEGRAM_COMPACTION_COMPLETED_MARKDOWN,
+        );
       }
     },
     async onAgentStart(event, ctx) {

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

@@ -20,6 +20,7 @@ import type { TelegramTarget } from "./target.ts";
 import {
   isTelegramApiMethodRetrySafe,
   TelegramApiCommitUnknownError,
+  TelegramApiStaleTargetError,
 } from "./telegram-api.ts";
 import {
   createTelegramBusFollowerDeliveryIdentity,
@@ -47,6 +48,7 @@ import {
 export const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
 export const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30_000;
+export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS =
   TELEGRAM_BUS_REGISTRATION_RETRY.attempts;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS =
@@ -167,6 +169,9 @@ export interface TelegramBusFollowerRegistrationState {
   getSlot: () => string | undefined;
   getThreadName: () => string | undefined;
   getGeneration: () => string | undefined;
+  beginRecovery: () => number;
+  cancelRecovery: () => void;
+  waitForGeneration: (timeoutMs?: number) => Promise<string | undefined>;
   getLeaderProtocol: () => TelegramBusProtocolIdentity | undefined;
   getEligibleElectionSlots: () => readonly string[];
   setEligibleElectionSlots: (slots: readonly string[]) => void;
@@ -214,6 +219,9 @@ export interface TelegramBusFollowerClientRuntimeDeps<TMessage = unknown> {
   getApiAuthSecret?: () => string | undefined;
   getForwardingAuthSecret?: () => string | undefined;
   getRegistrationGeneration: () => string | undefined;
+  waitForRegistrationGeneration?: (
+    timeoutMs?: number,
+  ) => Promise<string | undefined>;
   getForwardCommentBatchPosition?: (
     message: TMessage,
   ) => "comment" | "forward" | undefined;
@@ -231,6 +239,9 @@ export interface TelegramBusFollowerApiCallerDeps {
   createRequestId: () => string;
   getAuthSecret?: () => string | undefined;
   getRegistrationGeneration: () => string | undefined;
+  waitForRegistrationGeneration?: (
+    timeoutMs?: number,
+  ) => Promise<string | undefined>;
   getNowMs?: () => number;
   timeoutMs?: number;
 }
@@ -417,6 +428,7 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
     | "getSlot"
     | "getThreadName"
     | "getEligibleElectionSlots"
+    | "beginRecovery"
     | "setRegistered"
   >;
   getRegistrationRuntime: () => TelegramBusFollowerRegistrationRuntime<TContext>;
@@ -638,6 +650,7 @@ export function createTelegramBusFollowerClientRuntime<
     socketPath: deps.socketPath,
     createRequestId,
     timeoutMs,
+    waitForRegistrationGeneration: deps.waitForRegistrationGeneration,
   };
   return {
     createRequestId,
@@ -695,14 +708,14 @@ export function createTelegramBusFollowerQueueHandoffClient(
   const timeoutMs =
     deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
   return async (input) => {
-    const registrationGeneration = deps.getRegistrationGeneration();
-    if (!registrationGeneration) {
-      throw new Error("Telegram bus follower is not registered.");
-    }
+    const registration = await resolveTelegramBusFollowerRegistration(
+      deps,
+      timeoutMs,
+    );
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
       socketPath,
-      timeoutMs,
+      timeoutMs: registration.remainingTimeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
         endpoint: socketPath,
         operation: "operation",
@@ -712,7 +725,7 @@ export function createTelegramBusFollowerQueueHandoffClient(
         requestId: deps.createRequestId(),
         auth: deps.getAuthSecret?.(),
         instanceId: deps.instanceId,
-        registrationGeneration,
+        registrationGeneration: registration.generation,
         ...input,
         sentAtMs: getNowMs(),
       },
@@ -770,11 +783,12 @@ export function createTelegramBusAgentMessageClient(
     envelope:
       | Extract<TelegramBusEnvelope, { kind: "follower.resolveAgentTarget" }>
       | Extract<TelegramBusEnvelope, { kind: "follower.routeAgentMessage" }>,
+    requestTimeoutMs = timeoutMs,
   ): Promise<unknown> => {
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
       socketPath,
-      timeoutMs,
+      timeoutMs: requestTimeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
         endpoint: socketPath,
         operation: "operation",
@@ -788,26 +802,30 @@ export function createTelegramBusAgentMessageClient(
         : "Telegram bus agent message did not return an acknowledgement.",
     );
   };
-  const registrationFields = () => {
-    const registrationGeneration = deps.getRegistrationGeneration();
-    if (!registrationGeneration) {
-      throw new Error("Telegram bus follower is not registered.");
-    }
+  const registrationFields = async () => {
+    const registration = await resolveTelegramBusFollowerRegistration(
+      deps,
+      timeoutMs,
+    );
     return {
-      auth: deps.getAuthSecret?.(),
-      instanceId: deps.instanceId,
-      registrationGeneration,
+      fields: {
+        auth: deps.getAuthSecret?.(),
+        instanceId: deps.instanceId,
+        registrationGeneration: registration.generation,
+      },
+      remainingTimeoutMs: registration.remainingTimeoutMs,
     };
   };
   return {
     async resolveTarget(selector) {
+      const registration = await registrationFields();
       const result = await request({
         kind: "follower.resolveAgentTarget",
         requestId: deps.createRequestId(),
-        ...registrationFields(),
+        ...registration.fields,
         selector,
         sentAtMs: getNowMs(),
-      });
+      }, registration.remainingTimeoutMs);
       if (!result || typeof result !== "object" || Array.isArray(result)) {
         throw new Error("Telegram bus returned an invalid agent target.");
       }
@@ -821,13 +839,14 @@ export function createTelegramBusAgentMessageClient(
       return { chatId: target.chatId, threadId: target.threadId };
     },
     async routeMessage(message) {
+      const registration = await registrationFields();
       await request({
         kind: "follower.routeAgentMessage",
         requestId: deps.createRequestId(),
-        ...registrationFields(),
+        ...registration.fields,
         message,
         sentAtMs: getNowMs(),
-      });
+      }, registration.remainingTimeoutMs);
     },
   };
 }
@@ -839,16 +858,16 @@ export function createTelegramBusFollowerApiCaller(
   const timeoutMs =
     deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
   return async (method, args) => {
+    const registration = await resolveTelegramBusFollowerRegistration(
+      deps,
+      timeoutMs,
+    );
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
-    const registrationGeneration = deps.getRegistrationGeneration();
-    if (!registrationGeneration) {
-      throw new Error("Telegram bus follower is not registered.");
-    }
     let response: TelegramBusEnvelope | undefined;
     try {
       response = await sendTelegramBusLocalEnvelope({
         socketPath,
-        timeoutMs,
+        timeoutMs: registration.remainingTimeoutMs,
         retry: getTelegramBusTransportRetryPolicy({
           endpoint: socketPath,
           operation: "operation",
@@ -858,7 +877,7 @@ export function createTelegramBusFollowerApiCaller(
           requestId: deps.createRequestId(),
           auth: deps.getAuthSecret?.(),
           instanceId: deps.instanceId,
-          registrationGeneration,
+          registrationGeneration: registration.generation,
           method,
           args,
           sentAtMs: getNowMs(),
@@ -880,6 +899,20 @@ export function createTelegramBusFollowerApiCaller(
       response?.kind === "bus.ack"
         ? response.message
         : "Telegram bus API call did not return an acknowledgement.";
+    if (
+      response?.kind === "bus.ack" &&
+      response.error?.code === "stale-target" &&
+      response.error.chatId !== undefined &&
+      response.error.threadId !== undefined
+    ) {
+      throw new TelegramApiStaleTargetError(
+        message ?? "Telegram thread target is stale.",
+        {
+          chatId: response.error.chatId,
+          threadId: response.error.threadId,
+        },
+      );
+    }
     if (
       response?.kind === "bus.ack" &&
       response.error?.code === "commit-unknown"
@@ -893,6 +926,29 @@ export function createTelegramBusFollowerApiCaller(
   };
 }
 
+async function resolveTelegramBusFollowerRegistration(
+  deps: Pick<
+    TelegramBusFollowerApiCallerDeps,
+    | "getRegistrationGeneration"
+    | "waitForRegistrationGeneration"
+    | "getNowMs"
+  >,
+  timeoutMs: number,
+): Promise<{ generation: string; remainingTimeoutMs: number }> {
+  const current = deps.getRegistrationGeneration();
+  if (current) return { generation: current, remainingTimeoutMs: timeoutMs };
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const startedAtMs = getNowMs();
+  const restored = await deps.waitForRegistrationGeneration?.(
+    timeoutMs,
+  );
+  const remainingTimeoutMs = Math.max(0, timeoutMs - (getNowMs() - startedAtMs));
+  if (restored && remainingTimeoutMs > 0) {
+    return { generation: restored, remainingTimeoutMs };
+  }
+  throw new Error("Telegram bus follower is not registered.");
+}
+
 function isTelegramStaleContextError(error: unknown): boolean {
   return (
     error instanceof Error &&
@@ -1046,12 +1102,52 @@ export function createTelegramBusFollowerRegistrationState(
   let generation: string | undefined;
   let leaderProtocol: TelegramBusProtocolIdentity | undefined;
   let eligibleElectionSlots: string[] = [];
+  let recoveryEpoch = 0;
+  let activeRecoveryEpoch: number | undefined;
+  const generationWaiters = new Set<{
+    epoch: number;
+    settle: (value: string | undefined) => void;
+  }>();
+  const settleGenerationWaiters = (
+    value: string | undefined,
+    epoch?: number,
+  ) => {
+    for (const waiter of [...generationWaiters]) {
+      if (epoch === undefined || waiter.epoch === epoch) waiter.settle(value);
+    }
+  };
   return {
     isRegistered: () => registered,
     getTarget: () => (target ? { ...target } : undefined),
     getSlot: () => slot,
     getThreadName: () => threadName,
     getGeneration: () => generation,
+    beginRecovery: () => {
+      if (activeRecoveryEpoch !== undefined) return activeRecoveryEpoch;
+      activeRecoveryEpoch = ++recoveryEpoch;
+      return activeRecoveryEpoch;
+    },
+    cancelRecovery: () => {
+      const epoch = activeRecoveryEpoch;
+      activeRecoveryEpoch = undefined;
+      if (epoch !== undefined) settleGenerationWaiters(undefined, epoch);
+    },
+    waitForGeneration: (timeoutMs = TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS) => {
+      if (generation) return Promise.resolve(generation);
+      const epoch = activeRecoveryEpoch;
+      if (epoch === undefined) return Promise.resolve(undefined);
+      return new Promise((resolve) => {
+        let timer: NodeJS.Timeout | undefined;
+        const settle = (value: string | undefined) => {
+          generationWaiters.delete(waiter);
+          if (timer) clearTimeout(timer);
+          resolve(value);
+        };
+        const waiter = { epoch, settle };
+        generationWaiters.add(waiter);
+        timer = setTimeout(() => settle(undefined), Math.max(0, timeoutMs));
+      });
+    },
     getLeaderProtocol: () =>
       leaderProtocol
         ? { ...leaderProtocol, capabilities: [...leaderProtocol.capabilities] }
@@ -1077,6 +1173,10 @@ export function createTelegramBusFollowerRegistrationState(
             }
           : undefined;
       if (availabilityChanged) options.onAvailabilityChanged?.();
+      if (generation) {
+        activeRecoveryEpoch = undefined;
+        settleGenerationWaiters(generation);
+      }
     },
   };
 }
@@ -1253,6 +1353,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
   ): Promise<void> => {
     if (promotionPending) return;
     promotionPending = true;
+    deps.registrationState.beginRecovery();
     try {
       const initialBinding = carriedBinding ?? snapshotBinding();
       const state = deps.getLeaderState();
@@ -1366,6 +1467,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
     heartbeatPromise = undefined;
     heartbeatPromiseGeneration = undefined;
     deps.setActiveAuthSecret?.(undefined);
+    deps.registrationState?.cancelRecovery();
     deps.registrationState?.setRegistered(false);
     lastKnownTarget = undefined;
     lastKnownSlot = undefined;

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

@@ -8,6 +8,7 @@
 import * as Sync from "./sync.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import {
+  getTelegramApiErrorRequestTarget,
   isTelegramApiCommitUnknownError,
   type TelegramApiCallOptions,
 } from "./telegram-api.ts";
@@ -1756,6 +1757,10 @@ async function handleFollowerApiCall(
       result,
     };
   } catch (error) {
+    const staleTarget =
+      Threads.isTelegramTopicTargetStaleError(error)
+        ? getTelegramApiErrorRequestTarget(error)
+        : undefined;
     return {
       kind: "bus.ack",
       requestId: envelope.requestId,
@@ -1764,14 +1769,22 @@ async function handleFollowerApiCall(
         error instanceof Error
           ? error.message
           : "Telegram bus API call failed.",
-      ...(isTelegramApiCommitUnknownError(error)
+      ...(staleTarget
         ? {
             error: {
-              code: "commit-unknown" as const,
-              method: error.method,
+              code: "stale-target" as const,
+              chatId: staleTarget.chatId,
+              threadId: staleTarget.threadId,
             },
           }
-        : {}),
+        : isTelegramApiCommitUnknownError(error)
+          ? {
+              error: {
+                code: "commit-unknown" as const,
+                method: error.method,
+              },
+            }
+          : {}),
     };
   }
 }