@llblab/pi-telegram 0.37.0 → 0.37.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.37.2: Follower Recovery Delivery Hotfix
+
+- `Follower Recovery Delivery`: Holds follower Bot API calls behind a bounded registration wait when heartbeat recovery temporarily clears local authority, then sends once with the restored exact generation. Calls still fail closed if registration is not restored, and acknowledgement ambiguity remains non-retryable.
+
+## 0.37.1: Settings Manager Compatibility Hotfix
+
+- `Menu Compatibility`: Keeps `/start`, model, and queue menu rendering compatible with Pi settings-manager implementations that do not expose `reload()`. Hosts with reload retain explicit refresh behavior; other hosts use the freshly constructed settings snapshot instead of failing with `settingsManager.reload is not a function`.
+
 ## 0.37.0: Journal-Owned Telegram Admission
 
 - `Configuration-Only State`: Moves the per-profile polling cursor out of `telegram.json` into atomic durable journal revisions, including cursor-only initial sync, compaction, reconstruction, and recovery. A journal-first one-shot cutover removes legacy config state idempotently, exact bot/profile fences remain enforced, status reads journal authority, and unsafe downgrade now fails closed.

package/docs/multi-instance-bus.md

@@ -157,7 +157,7 @@ Leader election is heartbeat-gated and lock-backed. The polling owner checks exa
 4. If the leader heartbeat is stale, attempt an atomic leadership takeover; ordinary `/telegram-connect` on a follower is not a leadership move while the leader is live.
 5. Heartbeat acknowledgements carry the authenticated live follower-slot roster. If several followers detect stale leadership, the lowest observed live slot attempts promotion immediately; higher slots defer one bounded election grace and re-check the lock. Atomic compare/write acquisition remains the final ownership authority, and a missing lower-slot follower cannot block a higher survivor beyond that grace.
 
-Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. After the grace window they promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries and leader reloads must probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
+Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. Follower Bot API calls already admitted by the active Pi turn wait for that bounded re-registration and capture its new exact generation before entering transport; they do not fail merely because recovery temporarily cleared local registration, and they never replay after an ambiguous transport commit. After the grace window followers promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries and leader reloads must probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
 
 ## Leader/Follower Communication
 

package/index.ts

@@ -415,6 +415,8 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getRegistrationGeneration:
         telegramBusFollowerRegistrationState.getGeneration,
+      waitForRegistrationGeneration:
+        telegramBusFollowerRegistrationState.waitForGeneration,
       getForwardCommentBatchPosition:
         textGroupRuntime.getPreparedForwardingPosition,
       recordRuntimeEvent,

package/lib/bus-follower.ts

@@ -47,6 +47,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 +168,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 +218,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 +238,9 @@ export interface TelegramBusFollowerApiCallerDeps {
   createRequestId: () => string;
   getAuthSecret?: () => string | undefined;
   getRegistrationGeneration: () => string | undefined;
+  waitForRegistrationGeneration?: (
+    timeoutMs?: number,
+  ) => Promise<string | undefined>;
   getNowMs?: () => number;
   timeoutMs?: number;
 }
@@ -417,6 +427,7 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
     | "getSlot"
     | "getThreadName"
     | "getEligibleElectionSlots"
+    | "beginRecovery"
     | "setRegistered"
   >;
   getRegistrationRuntime: () => TelegramBusFollowerRegistrationRuntime<TContext>;
@@ -638,6 +649,7 @@ export function createTelegramBusFollowerClientRuntime<
     socketPath: deps.socketPath,
     createRequestId,
     timeoutMs,
+    waitForRegistrationGeneration: deps.waitForRegistrationGeneration,
   };
   return {
     createRequestId,
@@ -695,14 +707,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 +724,7 @@ export function createTelegramBusFollowerQueueHandoffClient(
         requestId: deps.createRequestId(),
         auth: deps.getAuthSecret?.(),
         instanceId: deps.instanceId,
-        registrationGeneration,
+        registrationGeneration: registration.generation,
         ...input,
         sentAtMs: getNowMs(),
       },
@@ -770,11 +782,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 +801,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 +838,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 +857,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 +876,7 @@ export function createTelegramBusFollowerApiCaller(
           requestId: deps.createRequestId(),
           auth: deps.getAuthSecret?.(),
           instanceId: deps.instanceId,
-          registrationGeneration,
+          registrationGeneration: registration.generation,
           method,
           args,
           sentAtMs: getNowMs(),
@@ -893,6 +911,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 +1087,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 +1158,10 @@ export function createTelegramBusFollowerRegistrationState(
             }
           : undefined;
       if (availabilityChanged) options.onAvailabilityChanged?.();
+      if (generation) {
+        activeRecoveryEpoch = undefined;
+        settleGenerationWaiters(generation);
+      }
     },
   };
 }
@@ -1253,6 +1338,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 +1452,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
     heartbeatPromise = undefined;
     heartbeatPromiseGeneration = undefined;
     deps.setActiveAuthSecret?.(undefined);
+    deps.registrationState?.cancelRecovery();
     deps.registrationState?.setRegistered(false);
     lastKnownTarget = undefined;
     lastKnownSlot = undefined;

package/lib/menu-model.ts

@@ -103,7 +103,7 @@ export interface TelegramModelMenuRuntimeOptions<
 }
 
 export interface MenuSettingsManager {
-  reload: () => Promise<void>;
+  reload?: () => Promise<void>;
   flush?: () => Promise<void>;
   getEnabledModels: () => string[] | undefined;
   setEnabledModels?: (patterns: string[] | undefined) => void;
@@ -498,7 +498,9 @@ export function createTelegramModelMenuStateBuilder<
       threadId,
       activeModel: deps.getActiveModel(ctx),
       ctx,
-      reloadSettings: () => settingsManager.reload(),
+      reloadSettings: async () => {
+        await settingsManager.reload?.();
+      },
       getConfiguredScopedModelPatterns: () =>
         settingsManager.getEnabledModels(),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.37.0",
+  "version": "0.37.2",
   "private": false,
   "publishConfig": {
     "access": "public"