@llblab/pi-telegram 0.53.2 → 0.54.0

package/lib/bus.ts

@@ -45,7 +45,12 @@ import {
   type TelegramBusTransportRetryPolicy,
 } from "./bus-transport.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
-import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS } from "./locks.ts";
+import {
+  isSameTelegramLockOwner,
+  TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS,
+  type TelegramLockEntry,
+  type TelegramLockState,
+} from "./locks.ts";
 import { resolveAgentDir } from "./paths.ts";
 import { getTelegramProcessBirthIdentity } from "./process-identity.ts";
 import {
@@ -131,7 +136,8 @@ export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }
 
-const TELEGRAM_BUS_PROTOCOL_VERSION = 2 as const;
+// v3: journal source serialization left the config transaction; mixed v2/v3 peers would not exclude each other.
+const TELEGRAM_BUS_PROTOCOL_VERSION = 3 as const;
 export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION =
   "durable-follower-admission-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF =
@@ -1222,6 +1228,11 @@ export type TelegramBusEnvelope = (
       args: unknown[];
       sentAtMs: number;
     }
+  | {
+      /** Side-effect-free leader liveness probe; any acknowledgement proves a responsive event loop. */
+      kind: "bus.probe";
+      requestId: string;
+    }
   | {
       kind: "bus.ack";
       requestId: string;
@@ -1269,7 +1280,8 @@ export function getTelegramBusEnvelopeTrafficClass(
 ): TelegramBusEnvelopeTrafficClass {
   if (
     envelope.kind === "follower.register" ||
-    envelope.kind === "follower.restoreWorkspace"
+    envelope.kind === "follower.restoreWorkspace" ||
+    envelope.kind === "bus.probe"
   )
     return "bootstrap";
   if (envelope.kind === "bus.ack") return "response";
@@ -1579,6 +1591,9 @@ export function parseTelegramBusEnvelope(
     case "follower.callApi":
       envelope = parseCallApiEnvelope(value, requestId);
       break;
+    case "bus.probe":
+      envelope = { kind, requestId };
+      break;
     case "bus.ack":
       envelope = parseAckEnvelope(value, requestId);
       break;
@@ -1590,6 +1605,112 @@ export function parseTelegramBusEnvelope(
   return envelope;
 }
 
+/**
+ * One leader liveness observation. `silent` (connected or connecting, no answer within the window) and
+ * `unreachable` (an endpoint that refuses connections: nobody listens) can support a takeover. A missing endpoint is
+ * `unknown`: a live classic-mode leader has no socket at all. Any bytes or an orderly close prove the peer's event
+ * loop handled the connection, so even an older leader rejecting the unknown kind is `responsive`.
+ */
+export type TelegramBusLeaderProbeResult =
+  | "responsive"
+  | "silent"
+  | "unreachable"
+  | "unknown";
+
+export function probeTelegramBusLeader(input: {
+  socketPath: TelegramBusSocketPathSource;
+  secret?: string;
+  timeoutMs?: number;
+}): Promise<TelegramBusLeaderProbeResult> {
+  const timeoutMs = input.timeoutMs ?? TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    let socket: Socket | undefined;
+    const finish = (result: TelegramBusLeaderProbeResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket?.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(() => finish("silent"), timeoutMs);
+    let connected = false;
+    try {
+      socket = createConnection(resolveTelegramBusSocketPath(input.socketPath));
+    } catch {
+      finish("unknown");
+      return;
+    }
+    socket.once("connect", () => {
+      connected = true;
+      socket!.write(
+        encodeTelegramBusEnvelope({
+          kind: "bus.probe",
+          requestId: `probe:${randomBytes(8).toString("hex")}`,
+          ...(input.secret ? { auth: input.secret } : {}),
+        }),
+      );
+    });
+    socket.once("data", () => finish("responsive"));
+    socket.once("end", () => finish("responsive"));
+    socket.once("error", (error) => {
+      const code = (error as NodeJS.ErrnoException).code;
+      finish(
+        !connected && code === "ECONNREFUSED" ? "unreachable" : "unknown",
+      );
+    });
+  });
+}
+
+/**
+ * Takeover evidence replacing the retired file heartbeat: a full silent window, or an unreachable endpoint
+ * confirmed again after one more window (a just-started leader binds its socket well within it). The owner must
+ * stay the same throughout; the lock acquisition then CAS-checks that exact owner.
+ */
+export async function proveTelegramBusLeaderUnresponsive(input: {
+  probe: () => Promise<TelegramBusLeaderProbeResult>;
+  isSameOwner: () => boolean;
+  sleep: (ms: number) => Promise<void>;
+  windowMs?: number;
+}): Promise<boolean> {
+  const first = await input.probe();
+  if (first === "silent") return input.isSameOwner();
+  if (first !== "unreachable") return false;
+  await input.sleep(input.windowMs ?? TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS);
+  if (!input.isSameOwner()) return false;
+  const second = await input.probe();
+  return (second === "silent" || second === "unreachable") && input.isSameOwner();
+}
+
+/** Composition-ready takeover proof for one profile's leader lock and endpoint. */
+export function createTelegramBusLeaderUnresponsivenessProof(deps: {
+  getLeaderState: () => TelegramLockState;
+  getLeaderSocketPath: () => string;
+  probe?: typeof probeTelegramBusLeader;
+  sleep?: (ms: number) => Promise<void>;
+}): (owner: TelegramLockEntry) => Promise<boolean> {
+  const probe = deps.probe ?? probeTelegramBusLeader;
+  const sleep =
+    deps.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  return (owner) =>
+    proveTelegramBusLeaderUnresponsive({
+      probe: () =>
+        probe({
+          socketPath: owner.busSocketPath ?? deps.getLeaderSocketPath(),
+          secret: owner.busSecret,
+        }),
+      isSameOwner: () => {
+        const state = deps.getLeaderState();
+        return (
+          state.kind === "active-elsewhere" &&
+          isSameTelegramLockOwner(state.lock, owner)
+        );
+      },
+      sleep,
+    });
+}
+
 interface TelegramBusLocalServer {
   start: () => Promise<void>;
   stop: () => Promise<void>;

package/lib/config.ts

@@ -289,12 +289,6 @@ export interface TelegramConfigStore {
     assertExecutionCurrent?: () => void,
     commitIfOwned?: (commit: () => void) => boolean,
   ) => Promise<boolean>;
-  /** Lock-only serialization for trusted synchronous source operations, not authorization.
-   * Does not read/adopt config. Acquire required Workspace admission first; never
-   * acquire owners or nest config admission here. Do not pass async callbacks:
-   * returned promises are not protected after their synchronous prefix.
-   */
-  withSourceSerialization: <T>(operation: () => T) => T;
   /** Trusted synchronous publication only; caller acquires Workspace admission before this config transaction. */
   withPairingAdmission: <T>(
     profileName: string,
@@ -779,8 +773,6 @@ export function createTelegramConfigStore(
       nextConfig.allowedUserId = userId;
       setEffectiveConfig(nextConfig);
     },
-    withSourceSerialization: (operation) =>
-      withTelegramFileTransaction(`${configPath}.transaction`, operation),
     withPairingAdmission: (profileName, tokenSha256, publish) =>
       withPersistedPairingProfile(
         profileName,

package/lib/extension.ts

@@ -181,13 +181,15 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getProfileName: configStore.getActiveProfileName,
     });
+  const withTelegramJournalSourceSerialization =
+    Journal.createTelegramJournalSourceSerialization();
   const telegramJournalBindingRuntime =
     Journal.createTelegramUpdateJournalBindingRuntime({
       base: {
         getProfileName: configStore.getActiveProfileName,
         getBotToken: configStore.getBotToken,
         getBotId: getTelegramBotId,
-        withSourceSerialization: configStore.withSourceSerialization,
+        withSourceSerialization: withTelegramJournalSourceSerialization,
         onRecovery(event) {
           recordRuntimeEvent(
             "recovery",
@@ -259,6 +261,11 @@ export default function (pi: Pi.ExtensionAPI) {
       return telegramLeaderJournalPath.createJournalPath();
     },
   });
+  const proveTelegramLeaderUnresponsive =
+    Bus.createTelegramBusLeaderUnresponsivenessProof({
+      getLeaderState: lockRuntime.getState,
+      getLeaderSocketPath: getTelegramBusSocketPath,
+    });
   const telegramSessionContextStore =
     Lifecycle.createTelegramSessionContextStore<Pi.ExtensionContext>({
       getIdentity(ctx) {
@@ -1368,7 +1375,7 @@ export default function (pi: Pi.ExtensionAPI) {
         botToken,
         botId: getTelegramBotId(),
       });
-      return configStore.withSourceSerialization(function () {
+      return withTelegramJournalSourceSerialization(function () {
         return Journal.isTelegramThreadCleanupJournalNamespaceClear({
           directory: Paths.resolveTelegramTempDir(),
           profile,
@@ -1988,6 +1995,7 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       recovery: {
         getLeaderState: lockRuntime.getState,
+        proveLeaderUnresponsive: proveTelegramLeaderUnresponsive,
         setLifecyclePhase: telegramBusFollowerControlState.setLifecyclePhase,
         updateStatus,
         promoteToLeader: promoteTelegramBusFollowerToLeader,
@@ -2347,6 +2355,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const threadAwarePollingPorts = telegramThreadCapabilityRuntime.pollingPorts;
   const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
     lock: lockRuntime,
+    proveOwnerUnresponsive: proveTelegramLeaderUnresponsive,
     resetDamagedState() {
       return Locks.resetDamagedTelegramRuntimeState(
         Paths.resolveTelegramStatePath(),

package/lib/journal.ts

@@ -46,6 +46,7 @@ import {
 import {
   decodeTelegramSessionDirectoryName,
   getTelegramProfilePathSuffix,
+  resolveTelegramRuntimeDir,
   TELEGRAM_DEFAULT_PROFILE_NAME,
 } from "./paths.ts";
 import {
@@ -4889,6 +4890,21 @@ export function createTelegramUpdateJournalBindingRuntime(deps: {
   return runtime;
 }
 
+/**
+ * Journal-owned cross-family source serializer, lock-only and never authorization. Its guard lives
+ * in the runtime service directory, so journal work never touches `telegram.json` or its
+ * transaction. Acquire Workspace admission and any sender (config) admission first; never acquire
+ * owners inside it. Callbacks must be synchronous: a returned promise is unprotected after its
+ * synchronous prefix.
+ */
+export function createTelegramJournalSourceSerialization(
+  getTransactionPath: () => string = () =>
+    join(resolveTelegramRuntimeDir(), "journals.transaction"),
+): <T>(operation: () => T) => T {
+  return (operation) =>
+    withTelegramFileTransaction(getTransactionPath(), operation);
+}
+
 export function createTelegramUpdateJournalStore(
   options: TelegramUpdateJournalStoreOptions,
 ): TelegramUpdateJournalStore {
@@ -7217,10 +7233,17 @@ function createJournalStoreCore(
             serializedBytes: published.serializedBytes,
           };
         });
+      // Sender admission is the outer config authority; journal serialization nests inside it.
+      const serializedAppend = (preApprovalExcluded?: boolean) =>
+        withSourceSerialization
+          ? withSourceSerialization(() =>
+              appendWithEvidence(preApprovalExcluded),
+            )
+          : appendWithEvidence(preApprovalExcluded);
       const append = () => {
         if (withPairedAdmission) {
           const result = withPairedAdmission(normalizedUpdates, () =>
-            appendWithEvidence(),
+            serializedAppend(),
           );
           if (!result.admitted)
             throw createJournalError(
@@ -7231,10 +7254,8 @@ function createJournalStoreCore(
           return result.value;
         }
         if (withPairingAdmission)
-          return withPairingAdmission(appendWithEvidence);
-        return withSourceSerialization
-          ? withSourceSerialization(() => appendWithEvidence())
-          : appendWithEvidence();
+          return withPairingAdmission(serializedAppend);
+        return serializedAppend();
       };
       const admittedAppend = () => {
         if (!workspaceAdmission) return append();

package/lib/locks.ts

@@ -141,6 +141,8 @@ interface TelegramLockAcquireOptions {
   force?: boolean;
   expectedOwner?: TelegramLockEntry;
   election?: boolean;
+  /** Bus-proven unresponsive owner: treated as stale only while it is still exactly the current owner. */
+  unresponsiveOwner?: TelegramLockEntry;
 }
 
 type TelegramLockAcquireResult =
@@ -1381,6 +1383,14 @@ function hasSameLockOwner(
   );
 }
 
+/** Exact owner identity (pid, cwd, instance, leader epoch, runtime generation); absent entries never match. */
+export function isSameTelegramLockOwner(
+  current: TelegramLockEntry | undefined,
+  expected: TelegramLockEntry | undefined,
+): boolean {
+  return hasSameLockOwner(current, expected);
+}
+
 function canSupersedeSameProcessOwner(
   current: TelegramLockEntry,
   pid: number,
@@ -1408,7 +1418,6 @@ function createLockEntry(
     instanceId?: string;
     busSocketPath?: string;
     busSecret?: string;
-    getNowMs?: () => number;
     mintLeaderEpoch?: () => number | string;
     runtimeGeneration?: number;
     journalPath?: string;
@@ -1417,9 +1426,7 @@ function createLockEntry(
   const lock: TelegramLockEntry = { pid, cwd: ctx.cwd };
   if (options.journalPath) lock.journalPath = options.journalPath;
   if (options.instanceId) {
-    const nowMs = options.getNowMs?.();
     lock.instanceId = options.instanceId;
-    lock.heartbeatMs = nowMs;
     lock.leaderEpoch = options.mintLeaderEpoch?.() ?? randomUUID();
     lock.runtimeGeneration = options.runtimeGeneration;
   }
@@ -1623,7 +1630,17 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
             changed: false,
           };
         const current = parseTelegramLockEntry(locks[effectiveKey]);
-        const state = getLockState(current, pid, isAlive, stateOptions());
+        const observedState = getLockState(
+          current,
+          pid,
+          isAlive,
+          stateOptions(),
+        );
+        const state: TelegramLockState =
+          observedState.kind === "active-elsewhere" &&
+          hasSameLockOwner(current, acquireOptions.unresponsiveOwner)
+            ? { kind: "stale", lock: observedState.lock }
+            : observedState;
         const expectedOwned = adoptCompatibleOwnedLock(
           effectiveKey,
           current,
@@ -1691,7 +1708,6 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
           instanceId: options.instanceId,
           busSocketPath: options.busSocketPath,
           busSecret: options.busSecret,
-          getNowMs,
           mintLeaderEpoch: options.mintLeaderEpoch,
           runtimeGeneration,
         });
@@ -1846,39 +1862,65 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
         { ...publication, isCurrent },
       );
     },
-    refresh: (ctx) =>
-      !deliveryRevoked &&
-      transactOwners((locks) => {
-        const effectiveKey = resolveEffectiveKey();
-        const lock = parseTelegramLockEntry(locks[effectiveKey]);
-        const expectedOwner = adoptCompatibleOwnedLock(effectiveKey, lock, ctx);
-        if (!lock || !hasSameLockOwner(lock, expectedOwner)) {
-          if (ownedLockKey === effectiveKey) {
-            ownedLockKey = undefined;
-            ownedLock = undefined;
-          }
-          return { result: false, changed: false };
-        }
-        if (!options.instanceId) return { result: true, changed: false };
-        const refreshedLock: TelegramLockEntry = {
+    refresh: (ctx) => {
+      if (deliveryRevoked) return false;
+      // Owner fields only, never a timestamp: liveness is proven over the bus, so an exact owner needs no write.
+      const refreshedEntry = (lock: TelegramLockEntry): TelegramLockEntry => {
+        const busSecret = options.busSecret ?? lock.busSecret;
+        return {
           pid: lock.pid,
           ...(lock.cwd ? { cwd: lock.cwd } : {}),
           instanceId: options.instanceId,
-          heartbeatMs: getNowMs(),
           leaderEpoch:
             lock.leaderEpoch ?? options.mintLeaderEpoch?.() ?? randomUUID(),
           runtimeGeneration: lock.runtimeGeneration ?? runtimeGeneration,
           ...(options.busSocketPath
             ? { busSocketPath: options.busSocketPath }
             : {}),
-          busSecret: options.busSecret ?? lock.busSecret,
+          ...(busSecret !== undefined ? { busSecret } : {}),
           ...(lock.journalPath ? { journalPath: lock.journalPath } : {}),
         };
+      };
+      // Parsed entries carry explicit `undefined` fields; compare only the published ones.
+      const isCurrentEntry = (lock: TelegramLockEntry): boolean =>
+        lock.leaderEpoch !== undefined &&
+        isDeepStrictEqual(
+          Object.fromEntries(
+            Object.entries(lock).filter(([, value]) => value !== undefined),
+          ),
+          refreshedEntry(lock),
+        );
+      const effectiveKey = resolveEffectiveKey();
+      const observed = readLock();
+      if (
+        observed &&
+        hasSameLockOwner(
+          observed,
+          adoptCompatibleOwnedLock(effectiveKey, observed, ctx),
+        ) &&
+        (!options.instanceId || isCurrentEntry(observed))
+      ) {
+        return true;
+      }
+      return transactOwners((locks) => {
+        const lock = parseTelegramLockEntry(locks[effectiveKey]);
+        const expectedOwner = adoptCompatibleOwnedLock(effectiveKey, lock, ctx);
+        if (!lock || !hasSameLockOwner(lock, expectedOwner)) {
+          if (ownedLockKey === effectiveKey) {
+            ownedLockKey = undefined;
+            ownedLock = undefined;
+          }
+          return { result: false, changed: false };
+        }
+        if (!options.instanceId) return { result: true, changed: false };
+        if (isCurrentEntry(lock)) return { result: true, changed: false };
+        const refreshedLock = refreshedEntry(lock);
         locks[effectiveKey] = refreshedLock;
         ownedLockKey = effectiveKey;
         ownedLock = refreshedLock;
         return { result: true, changed: true };
-      }),
+      });
+    },
   };
 }
 
@@ -1906,7 +1948,7 @@ interface TelegramLockedPollingStartOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
   requestedThreadName?: string;
-  election?: { expectedOwner?: TelegramLockEntry };
+  election?: { expectedOwner?: TelegramLockEntry; unresponsive?: boolean };
   onAcquired?: () => Promise<void> | void;
 }
 
@@ -1966,6 +2008,8 @@ interface TelegramLockedPollingRuntimeDeps<
     owner: TelegramLockEntry,
   ) => boolean | undefined | Promise<boolean | undefined>;
   stopFollowerRegistration?: () => void;
+  /** Threaded Mode takeover evidence after failed follower registration; replaces the retired file heartbeat. */
+  proveOwnerUnresponsive?: (owner: TelegramLockEntry) => Promise<boolean>;
   onTransportAvailabilityChanged?: () => void;
   transportMonitor?: { start: (ctx: TContext) => void; stop: () => void };
   updateStatus: (ctx: TContext) => void;
@@ -2187,6 +2231,9 @@ export function createTelegramLockedPollingRuntime<
           options.election?.expectedOwner ??
           (options.force ? takeoverCandidate : undefined),
         election: options.election !== undefined,
+        unresponsiveOwner: options.election?.unresponsive
+          ? options.election.expectedOwner
+          : undefined,
       });
       if (!acquired.ok && !options.election) {
         const currentState = deps.lock.getState();
@@ -2231,22 +2278,34 @@ export function createTelegramLockedPollingRuntime<
             });
           }
           if (failureMessage) {
-            const owner = formatTelegramLockEntry(acquired.lock);
-            return {
-              ok: false,
-              canTakeover: false,
-              owner,
-              message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${formatTelegramFollowerRegistrationFailure(failureMessage)}.`,
-            };
+            const unresponsiveOwner = acquired.lock;
+            if (
+              deps.proveOwnerUnresponsive &&
+              (await deps.proveOwnerUnresponsive(unresponsiveOwner))
+            ) {
+              if (!isCurrent()) return cancelled;
+              acquired = deps.lock.acquire(ctx, { unresponsiveOwner });
+            }
+            if (!acquired.ok) {
+              const owner = formatTelegramLockEntry(acquired.lock);
+              return {
+                ok: false,
+                canTakeover: false,
+                owner,
+                message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${formatTelegramFollowerRegistrationFailure(failureMessage)}.`,
+              };
+            }
           }
         }
-        const owner = formatTelegramLockEntry(acquired.lock);
-        return {
-          ok: false,
-          canTakeover: true,
-          owner,
-          message: `Telegram bridge is active in another Pi instance (${owner}).`,
-        };
+        if (!acquired.ok) {
+          const owner = formatTelegramLockEntry(acquired.lock);
+          return {
+            ok: false,
+            canTakeover: true,
+            owner,
+            message: `Telegram bridge is active in another Pi instance (${owner}).`,
+          };
+        }
       }
       takeoverCandidate = undefined;
       if (!(await runOwnedPollingStart(ctx, options, isCurrent))) {

package/lib/status.ts

@@ -1008,6 +1008,15 @@ export function createTelegramRuntimeProjectionStore(
       if (!isRuntimeProjection({ ...semantic, writtenAtMs: 0 }))
         throw new Error("Telegram runtime projection is malformed.");
       delete semantic.diagnostics.recentRuntimeEvents;
+      // Poll-cycle timestamps change on every response; live status renders them from memory,
+      // so persisting them would rewrite state.json each poll for no reader.
+      const polling = semantic.runtime.polling;
+      if (polling && typeof polling === "object" && !Array.isArray(polling)) {
+        const volatile = polling as Record<string, unknown>;
+        delete volatile.phaseStartedAtMs;
+        delete volatile.lastSuccessfulResponseAtMs;
+        delete volatile.lastSuccessfulResponseUpdateCount;
+      }
       const isCurrent = (): boolean =>
         getPath() === path && getProfile() === profile && authority() === true;
       const isUnchanged = (

package/package.json

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