@llblab/pi-telegram 0.54.0 → 0.54.1

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## Unreleased
 
+## 0.54.1: Followers go offline when Threaded Mode is turned off
+
+- `Threaded Mode downgrade`: Turning Threaded Mode off in BotFather now takes followers offline instead of looping between `electing` and `disconnected` (and filling the log) against a leader that switched to classic polling; reconnect with `/telegram-connect` after turning it back on. `/telegram-disconnect` on a follower without a live leader now disconnects locally and reports the Thread as kept, and a pending recovery retry no longer re-registers a disconnected follower.
+- `Ownership reads`: A lock-free ownership check that races a concurrent `state.json` replacement is now retried and confirmed through the serialized path before the leader stops polling, so a transient read miss (seen on slow Windows runners) is no longer mistaken for lost ownership. The integration test for a revoked follower provisioning now waits for its asynchronous lease release.
+
 ## 0.54.0: No periodic disk writes while idle
 
 - `Journal serialization`: The update journal no longer borrows the `telegram.json` lock. Journal operations serialize on their own `tmp/pi-telegram/runtime/journals.transaction`, so receiving messages and repairing journals never touch the config file or its guard; only config writes and sender admission still take it. Bus protocol moves to v3 so 0.53.x peers, which serialize on the old lock, cannot register alongside 0.54 writers.

package/dist/lib/bus-follower.d.ts

@@ -231,6 +231,8 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
     promotionGraceMs?: number;
     /** Bus liveness proof for a live-PID leader that no longer answers; replaces the retired file heartbeat. */
     proveLeaderUnresponsive?: (owner: TelegramLockEntry) => Promise<boolean>;
+    /** Shared bot state says Threaded Mode is off: followers cannot exist, so recovery goes offline instead. */
+    isThreadModeDisabled?: () => boolean | Promise<boolean>;
     recordRuntimeEvent: (category: string, error: unknown, details?: Record<string, unknown>) => void;
 }
 export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<TContext> {
@@ -419,7 +421,12 @@ export declare function createTelegramBusFollowerControlState(): TelegramBusFoll
 export declare function createTelegramBusFollowerRegistrationState(options?: {
     onAvailabilityChanged?: () => void;
 }): TelegramBusFollowerRegistrationState;
-export declare function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(deps: TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>): (error: unknown, ctx: TContext) => Promise<void>;
+/** Heartbeat-failure recovery that a deliberate local stop halts until the next deliberate registration. */
+export type TelegramBusFollowerHeartbeatRecoveryHandler<TContext> = ((error: unknown, ctx: TContext) => Promise<void>) & {
+    halt: () => void;
+    resume: () => void;
+};
+export declare function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(deps: TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>): TelegramBusFollowerHeartbeatRecoveryHandler<TContext>;
 export declare function createTelegramBusFollowerRegistrationRuntime<TContext extends {
     cwd?: string;
 }>(deps: TelegramBusFollowerRegistrationRuntimeDeps<TContext>): TelegramBusFollowerRegistrationRuntime<TContext>;

package/dist/lib/bus-follower.js

@@ -190,7 +190,7 @@ export function createTelegramBusFollowerRuntimeAssembly(ports) {
         ...ports.recovery,
         registrationState: ports.registrationState,
         recordRuntimeEvent: ports.recordRuntimeEvent,
-        getRegistrationRuntime: () => registration,
+        getRegistrationRuntime: () => baseRegistration,
     });
     registration = createTelegramBusFollowerRegistrationRuntime({
         ...ports.registration,
@@ -203,6 +203,15 @@ export function createTelegramBusFollowerRuntimeAssembly(ports) {
     const baseRegistration = registration;
     registration = {
         ...baseRegistration,
+        // Public stop is deliberate (disconnect, suspension); recovery keeps the base stop for promotion.
+        stop() {
+            recovery.halt();
+            baseRegistration.stop();
+        },
+        registerWithLeader(ctx, leader, options) {
+            recovery.resume();
+            return baseRegistration.registerWithLeader(ctx, leader, options);
+        },
         async setContext(ctx) {
             const sessionGeneration = ports.registration.getSessionGeneration?.();
             if (ports.registration.isContextActive?.(ctx) === false)
@@ -1214,6 +1223,9 @@ export function createTelegramBusFollowerRegistrationState(options = {}) {
     };
 }
 export function createTelegramBusFollowerHeartbeatRecoveryHandler(deps) {
+    // Promotion stops registration internally and must keep retrying; only an operator stop or a confirmed
+    // switch to classic mode halts recovery, so it never re-registers behind a disconnect.
+    let halted = false;
     const promotionGraceMs = deps.promotionGraceMs ?? TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS;
     const sleep = deps.sleep ??
         ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -1246,6 +1258,10 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler(deps) {
                 .registerWithLeader(ctx, leader, binding?.target ? { target: binding.target } : undefined);
             if (!restored)
                 return false;
+            if (halted) {
+                deps.getRegistrationRuntime().stop();
+                return false;
+            }
             deps.setLifecyclePhase(undefined);
             safeUpdateStatus(ctx);
             deps.recordRuntimeEvent("bus", "Telegram follower registration restored", {
@@ -1266,6 +1282,8 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler(deps) {
     });
     const scheduleRecovery = (reason, fallbackCtx, binding) => {
         const retry = () => {
+            if (halted)
+                return;
             const activeCtx = deps.getActiveContext
                 ? deps.getActiveContext()
                 : fallbackCtx;
@@ -1336,12 +1354,29 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler(deps) {
         });
     };
     const recover = async (error, ctx, carriedBinding) => {
-        if (promotionPending)
+        if (promotionPending || halted)
             return;
         promotionPending = true;
         deps.registrationState.beginRecovery();
         const initialBinding = carriedBinding ?? snapshotBinding();
         try {
+            let threadModeDisabled = false;
+            try {
+                threadModeDisabled = (await deps.isThreadModeDisabled?.()) === true;
+            }
+            catch (stateError) {
+                deps.recordRuntimeEvent("bus", stateError, {
+                    phase: "follower-thread-mode-read",
+                });
+            }
+            if (threadModeDisabled) {
+                halted = true;
+                deps.getRegistrationRuntime().stop();
+                deps.setLifecyclePhase(undefined);
+                safeUpdateStatus(ctx);
+                deps.recordRuntimeEvent("bus", "Telegram follower went offline: Threaded Mode is off. Run /telegram-connect after turning it back on.", { phase: "follower-thread-mode-disabled" });
+                return;
+            }
             const state = deps.getLeaderState();
             if (state.kind === "active-elsewhere") {
                 clearRegisteredState(ctx);
@@ -1397,7 +1432,14 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler(deps) {
             promotionPending = false;
         }
     };
-    return recover;
+    return Object.assign(recover, {
+        halt() {
+            halted = true;
+        },
+        resume() {
+            halted = false;
+        },
+    });
 }
 export function createTelegramBusFollowerRegistrationRuntime(deps) {
     const getNowMs = deps.getNowMs ?? Date.now;

package/dist/lib/extension.js

@@ -1560,6 +1560,10 @@ export default function (pi) {
         recovery: {
             getLeaderState: lockRuntime.getState,
             proveLeaderUnresponsive: proveTelegramLeaderUnresponsive,
+            async isThreadModeDisabled() {
+                await threadStore.refresh?.();
+                return threadStore.getBotState().threadMode === "disabled";
+            },
             setLifecyclePhase: telegramBusFollowerControlState.setLifecyclePhase,
             updateStatus,
             promoteToLeader: promoteTelegramBusFollowerToLeader,

package/dist/lib/locks.js

@@ -1055,16 +1055,20 @@ export function createTelegramLockRuntime(options = {}) {
         if (!statePath)
             return readLocks(locksPath);
         // Read-only ownership queries fail closed (no owner); acquisition/publication still refuse malformed state.
-        try {
-            const transports = Object.fromEntries(Object.entries(readTelegramRuntimeState(statePath).profiles)
-                .filter(([, value]) => Object.hasOwn(value, "transport"))
-                .map(([profile, value]) => [profile, value.transport]));
-            assertTelegramStateTransport(transports[resolveEffectiveKey()]);
-            return transports;
-        }
-        catch {
-            return {};
+        // A strict read racing a concurrent atomic replace fails transiently, so retry before failing closed.
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                const transports = Object.fromEntries(Object.entries(readTelegramRuntimeState(statePath).profiles)
+                    .filter(([, value]) => Object.hasOwn(value, "transport"))
+                    .map(([profile, value]) => [profile, value.transport]));
+                assertTelegramStateTransport(transports[resolveEffectiveKey()]);
+                return transports;
+            }
+            catch {
+                // Retry; a persistent failure falls through to no owner.
+            }
         }
+        return {};
     };
     const transactOwners = (mutate) => {
         if (!statePath)
@@ -1440,7 +1444,8 @@ export function createTelegramLockedPollingRuntime(deps) {
         stopOwnershipWatcher();
         ownershipCheckInterval = setInterval(() => {
             try {
-                if (deps.lock.owns(owner))
+                // A lock-free miss can be a strict read racing an atomic replace; refresh confirms through the serialized path.
+                if (deps.lock.owns(owner) || deps.lock.refresh(owner))
                     return;
             }
             catch (error) {

package/dist/lib/sync.js

@@ -140,6 +140,7 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
         assertCurrent();
         const currentRecord = deps.getCurrentThreadRecord();
         let cleanupPending = false;
+        let followerThreadKept = false;
         if (currentRecord?.target.threadId) {
             const isManualFollower = currentRecord.owner?.kind === "manual-follower";
             const leaderEpoch = deps.getCurrentLeaderEpoch?.();
@@ -150,9 +151,8 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                 if (deps.disconnectFollowerThread) {
                     const disconnected = await deps.disconnectFollowerThread();
                     assertCurrent();
-                    if (!disconnected) {
-                        throw new Error("Telegram follower thread deletion requires a live leader registration.");
-                    }
+                    // Without a live leader the Thread cannot be deleted; still stop locally and never claim deletion.
+                    followerThreadKept = !disconnected;
                 }
             }
             else {
@@ -223,6 +223,8 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
         }
         assertCurrent();
         const stopped = await deps.stopPolling();
+        if (followerThreadKept)
+            return "Telegram bridge disconnected. Thread kept: no live leader could delete it.";
         return cleanupPending
             ? `${stopped} Telegram thread cleanup remains pending for the next leader.`
             : stopped;

package/dist/package.json

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

package/docs/multi-instance-bus.md

@@ -502,7 +502,7 @@ Named bots use sibling `profiles.<name>` entries. Shared bridge settings remain
 
 Rules:
 
-- Classic mode is selected by Telegram capability: when private-chat threads are unavailable or disabled, the polling owner uses ordinary single-DM behavior and blocked instances do not register as followers. During a live downgrade from Threaded Mode, the current bus leader becomes the classic polling owner after two 2.5-second capability-monitor probes and followers disconnect; if classic polling restore fails transiently, later monitor ticks retry the restore instead of allowing a follower takeover. Followers must not turn the downgrade into a takeover while active thread bindings prove the singleton owner was already established by the bus leader.
+- Classic mode is selected by Telegram capability: when private-chat threads are unavailable or disabled, the polling owner uses ordinary single-DM behavior and blocked instances do not register as followers. During a live downgrade from Threaded Mode, the current bus leader becomes the classic polling owner after two 2.5-second capability-monitor probes and followers disconnect; if classic polling restore fails transiently, later monitor ticks retry the restore instead of allowing a follower takeover. Followers must not turn the downgrade into a takeover while active thread bindings prove the singleton owner was already established by the bus leader. A follower that loses its leader reads the leader-persisted `threadMode`; when it is `disabled`, the follower halts recovery and goes offline with one diagnostic instead of retrying registration, keeping its Thread binding. It stays offline after Threaded Mode returns until the operator runs `/telegram-connect`. A deliberate local stop halts recovery the same way, and `/telegram-disconnect` without a live leader still stops locally, reporting the Thread as kept rather than deleted.
 - Telegram private-chat Threaded Mode enables local leader/follower behavior automatically. The leader owns `getUpdates`; registered followers route Telegram API work through the leader. `/telegram-connect` registers as follower when a live leader exists and does not offer manual takeover in that state. The TUI status bar keeps `telegram connected`, `telegram leader`, or `telegram follower` as stable transport identity during work; active work and queued items share the green Queue count instead of replacing that identity with an `active` processing label. Follower registration is unique by live profile/target: a reload or session replacement must replace stale registry entries rather than leaving multiple routable ids for one Telegram thread, and fallback target ownership must not classify leader records as followers.
 - The thread chat is the owner's private bot DM (`allowedUserId`); no `topics.chatId` config is needed. Thread names are assigned by the bridge from a baked compact per-slot palette. There is no agent-facing `telegram_rename_thread` tool and no separate user-facing slash command for manual thread renames.
 - Thread reuse is extension-owned through profile-scoped Workspace bindings; there is no separate `topics` config surface in the active private-chat thread model. Leader/follower record keys remain live role projections, while normalized exact-`cwd` bindings preserve identity and deterministic same-directory process suffixes across role and process changes.

package/lib/bus-follower.ts

@@ -572,6 +572,8 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
   promotionGraceMs?: number;
   /** Bus liveness proof for a live-PID leader that no longer answers; replaces the retired file heartbeat. */
   proveLeaderUnresponsive?: (owner: TelegramLockEntry) => Promise<boolean>;
+  /** Shared bot state says Threaded Mode is off: followers cannot exist, so recovery goes offline instead. */
+  isThreadModeDisabled?: () => boolean | Promise<boolean>;
   recordRuntimeEvent: (
     category: string,
     error: unknown,
@@ -759,7 +761,7 @@ export function createTelegramBusFollowerRuntimeAssembly<
     ...ports.recovery,
     registrationState: ports.registrationState,
     recordRuntimeEvent: ports.recordRuntimeEvent,
-    getRegistrationRuntime: () => registration,
+    getRegistrationRuntime: () => baseRegistration,
   });
   registration = createTelegramBusFollowerRegistrationRuntime({
     ...ports.registration,
@@ -772,6 +774,15 @@ export function createTelegramBusFollowerRuntimeAssembly<
   const baseRegistration = registration;
   registration = {
     ...baseRegistration,
+    // Public stop is deliberate (disconnect, suspension); recovery keeps the base stop for promotion.
+    stop() {
+      recovery.halt();
+      baseRegistration.stop();
+    },
+    registerWithLeader(ctx, leader, options) {
+      recovery.resume();
+      return baseRegistration.registerWithLeader(ctx, leader, options);
+    },
     async setContext(ctx) {
       const sessionGeneration = ports.registration.getSessionGeneration?.();
       if (ports.registration.isContextActive?.(ctx) === false) return;
@@ -2206,9 +2217,18 @@ export function createTelegramBusFollowerRegistrationState(
   };
 }
 
+/** Heartbeat-failure recovery that a deliberate local stop halts until the next deliberate registration. */
+export type TelegramBusFollowerHeartbeatRecoveryHandler<TContext> = ((
+  error: unknown,
+  ctx: TContext,
+) => Promise<void>) & { halt: () => void; resume: () => void };
+
 export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
   deps: TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>,
-): (error: unknown, ctx: TContext) => Promise<void> {
+): TelegramBusFollowerHeartbeatRecoveryHandler<TContext> {
+  // Promotion stops registration internally and must keep retrying; only an operator stop or a confirmed
+  // switch to classic mode halts recovery, so it never re-registers behind a disconnect.
+  let halted = false;
   const promotionGraceMs =
     deps.promotionGraceMs ?? TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS;
   const sleep =
@@ -2250,6 +2270,10 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
           binding?.target ? { target: binding.target } : undefined,
         );
       if (!restored) return false;
+      if (halted) {
+        deps.getRegistrationRuntime().stop();
+        return false;
+      }
       deps.setLifecyclePhase(undefined);
       safeUpdateStatus(ctx);
       deps.recordRuntimeEvent(
@@ -2277,6 +2301,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     binding: TelegramBusFollowerPromotedBinding,
   ) => {
     const retry = () => {
+      if (halted) return;
       const activeCtx = deps.getActiveContext
         ? deps.getActiveContext()
         : fallbackCtx;
@@ -2376,11 +2401,31 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     ctx: TContext,
     carriedBinding?: TelegramBusFollowerPromotedBinding,
   ): Promise<void> => {
-    if (promotionPending) return;
+    if (promotionPending || halted) return;
     promotionPending = true;
     deps.registrationState.beginRecovery();
     const initialBinding = carriedBinding ?? snapshotBinding();
     try {
+      let threadModeDisabled = false;
+      try {
+        threadModeDisabled = (await deps.isThreadModeDisabled?.()) === true;
+      } catch (stateError) {
+        deps.recordRuntimeEvent("bus", stateError, {
+          phase: "follower-thread-mode-read",
+        });
+      }
+      if (threadModeDisabled) {
+        halted = true;
+        deps.getRegistrationRuntime().stop();
+        deps.setLifecyclePhase(undefined);
+        safeUpdateStatus(ctx);
+        deps.recordRuntimeEvent(
+          "bus",
+          "Telegram follower went offline: Threaded Mode is off. Run /telegram-connect after turning it back on.",
+          { phase: "follower-thread-mode-disabled" },
+        );
+        return;
+      }
       const state = deps.getLeaderState();
       if (state.kind === "active-elsewhere") {
         clearRegisteredState(ctx);
@@ -2456,7 +2501,14 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
       promotionPending = false;
     }
   };
-  return recover;
+  return Object.assign(recover, {
+    halt() {
+      halted = true;
+    },
+    resume() {
+      halted = false;
+    },
+  });
 }
 
 export function createTelegramBusFollowerRegistrationRuntime<

package/lib/extension.ts

@@ -1996,6 +1996,10 @@ export default function (pi: Pi.ExtensionAPI) {
       recovery: {
         getLeaderState: lockRuntime.getState,
         proveLeaderUnresponsive: proveTelegramLeaderUnresponsive,
+        async isThreadModeDisabled() {
+          await threadStore.refresh?.();
+          return threadStore.getBotState().threadMode === "disabled";
+        },
         setLifecyclePhase: telegramBusFollowerControlState.setLifecyclePhase,
         updateStatus,
         promoteToLeader: promoteTelegramBusFollowerToLeader,

package/lib/locks.ts

@@ -1521,17 +1521,21 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   const readOwners = (): Record<string, unknown> => {
     if (!statePath) return readLocks(locksPath);
     // Read-only ownership queries fail closed (no owner); acquisition/publication still refuse malformed state.
-    try {
-      const transports = Object.fromEntries(
-        Object.entries(readTelegramRuntimeState(statePath).profiles)
-          .filter(([, value]) => Object.hasOwn(value, "transport"))
-          .map(([profile, value]) => [profile, value.transport]),
-      );
-      assertTelegramStateTransport(transports[resolveEffectiveKey()]);
-      return transports;
-    } catch {
-      return {};
+    // A strict read racing a concurrent atomic replace fails transiently, so retry before failing closed.
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        const transports = Object.fromEntries(
+          Object.entries(readTelegramRuntimeState(statePath).profiles)
+            .filter(([, value]) => Object.hasOwn(value, "transport"))
+            .map(([profile, value]) => [profile, value.transport]),
+        );
+        assertTelegramStateTransport(transports[resolveEffectiveKey()]);
+        return transports;
+      } catch {
+        // Retry; a persistent failure falls through to no owner.
+      }
     }
+    return {};
   };
   const transactOwners = <T>(
     mutate: (locks: Record<string, unknown>) => { result: T; changed: boolean },
@@ -2100,7 +2104,8 @@ export function createTelegramLockedPollingRuntime<
     stopOwnershipWatcher();
     ownershipCheckInterval = setInterval(() => {
       try {
-        if (deps.lock.owns(owner)) return;
+        // A lock-free miss can be a strict read racing an atomic replace; refresh confirms through the serialized path.
+        if (deps.lock.owns(owner) || deps.lock.refresh(owner)) return;
       } catch (error) {
         deps.recordRuntimeEvent?.("lock", error, { phase: "check" });
       }

package/lib/sync.ts

@@ -376,6 +376,7 @@ export function createTelegramManualThreadDisconnectHandler<
     assertCurrent();
     const currentRecord = deps.getCurrentThreadRecord();
     let cleanupPending = false;
+    let followerThreadKept = false;
     if (currentRecord?.target.threadId) {
       const isManualFollower = currentRecord.owner?.kind === "manual-follower";
       const leaderEpoch = deps.getCurrentLeaderEpoch?.();
@@ -386,11 +387,8 @@ export function createTelegramManualThreadDisconnectHandler<
         if (deps.disconnectFollowerThread) {
           const disconnected = await deps.disconnectFollowerThread();
           assertCurrent();
-          if (!disconnected) {
-            throw new Error(
-              "Telegram follower thread deletion requires a live leader registration.",
-            );
-          }
+          // Without a live leader the Thread cannot be deleted; still stop locally and never claim deletion.
+          followerThreadKept = !disconnected;
         }
       } else {
         const target = currentRecord.target as TelegramTarget & {
@@ -483,6 +481,8 @@ export function createTelegramManualThreadDisconnectHandler<
     }
     assertCurrent();
     const stopped = await deps.stopPolling();
+    if (followerThreadKept)
+      return "Telegram bridge disconnected. Thread kept: no live leader could delete it.";
     return cleanupPending
       ? `${stopped} Telegram thread cleanup remains pending for the next leader.`
       : stopped;

package/package.json

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