@llblab/pi-kit 0.30.0 → 0.31.0

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

@@ -38,6 +38,8 @@ export const TELEGRAM_LOCK_KEY = "default";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 8_000;
 export const TELEGRAM_OWNERSHIP_CHECK_MS = 1_000;
 export const TELEGRAM_OWNERSHIP_REFRESH_MS = 2_000;
+/** Consecutive unverified ownership checks tolerated before standing down; a concurrent shared-state replacement must not stop an owned transport. */
+export const TELEGRAM_OWNERSHIP_CHECK_FAILURE_TOLERANCE = 2;
 const TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS = 5;
 const TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS = 25;
 const TELEGRAM_LOCK_TRANSACTION_ATTEMPTS = 80;
@@ -141,6 +143,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 +1385,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 +1420,6 @@ function createLockEntry(
     instanceId?: string;
     busSocketPath?: string;
     busSecret?: string;
-    getNowMs?: () => number;
     mintLeaderEpoch?: () => number | string;
     runtimeGeneration?: number;
     journalPath?: string;
@@ -1417,9 +1428,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;
   }
@@ -1514,17 +1523,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 },
@@ -1623,7 +1636,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 +1714,6 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
           instanceId: options.instanceId,
           busSocketPath: options.busSocketPath,
           busSecret: options.busSecret,
-          getNowMs,
           mintLeaderEpoch: options.mintLeaderEpoch,
           runtimeGeneration,
         });
@@ -1846,39 +1868,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 +1954,7 @@ interface TelegramLockedPollingStartOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
   requestedThreadName?: string;
-  election?: { expectedOwner?: TelegramLockEntry };
+  election?: { expectedOwner?: TelegramLockEntry; unresponsive?: boolean };
   onAcquired?: () => Promise<void> | void;
 }
 
@@ -1966,6 +2014,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;
@@ -1991,6 +2041,7 @@ export function createTelegramLockedPollingRuntime<
   let ownershipRefreshInterval: ReturnType<typeof setInterval> | undefined;
   let ownershipStop: Promise<void> | undefined;
   let activeContext: TContext | undefined;
+  let ownershipCheckFailures = 0;
   let takeoverCandidate: TelegramLockEntry | undefined;
   let sessionAutoStartRun: Promise<void> | undefined;
   let pollingGeneration = 0;
@@ -2054,21 +2105,45 @@ export function createTelegramLockedPollingRuntime<
   const startOwnershipWatcher = (ctx: TContext) => {
     const owner = snapshotLockContext(ctx);
     stopOwnershipWatcher();
-    ownershipCheckInterval = setInterval(() => {
+    ownershipCheckFailures = 0;
+    // A serialized "not the owner" answer is definitive and stands down at once; only an observation that
+    // cannot be verified at all (both reads failed) counts toward the bounded tolerance.
+    const verifyOwnership = (observe: () => boolean): void => {
+      let owned: boolean | undefined;
+      let failure: unknown;
       try {
-        if (deps.lock.owns(owner)) return;
+        owned = observe();
       } catch (error) {
-        deps.recordRuntimeEvent?.("lock", error, { phase: "check" });
+        failure = error;
+      }
+      if (owned === true) {
+        ownershipCheckFailures = 0;
+        return;
       }
-      stopAfterOwnershipLoss();
+      if (owned === false) {
+        deps.recordRuntimeEvent?.(
+          "lock",
+          new Error("Telegram bridge ownership moved away from this instance."),
+          { phase: "ownership-lost" },
+        );
+        stopAfterOwnershipLoss();
+        return;
+      }
+      ownershipCheckFailures += 1;
+      deps.recordRuntimeEvent?.("lock", failure, {
+        phase: "ownership-check-failed",
+        consecutiveFailures: ownershipCheckFailures,
+        tolerance: TELEGRAM_OWNERSHIP_CHECK_FAILURE_TOLERANCE,
+      });
+      if (ownershipCheckFailures > TELEGRAM_OWNERSHIP_CHECK_FAILURE_TOLERANCE)
+        stopAfterOwnershipLoss();
+    };
+    ownershipCheckInterval = setInterval(() => {
+      // A lock-free miss can be a strict read racing an atomic replace; refresh confirms through the serialized path.
+      verifyOwnership(() => deps.lock.owns(owner) || deps.lock.refresh(owner));
     }, ownershipCheckMs);
     ownershipRefreshInterval = setInterval(() => {
-      try {
-        if (deps.lock.refresh(owner)) return;
-      } catch (error) {
-        deps.recordRuntimeEvent?.("lock", error, { phase: "refresh" });
-      }
-      stopAfterOwnershipLoss();
+      verifyOwnership(() => deps.lock.refresh(owner));
     }, ownershipRefreshMs);
     ownershipCheckInterval.unref?.();
     ownershipRefreshInterval.unref?.();
@@ -2187,6 +2262,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 +2309,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/node_modules/@llblab/pi-telegram/lib/outbound.ts

@@ -900,6 +900,9 @@ export function createTelegramOutboundReplyArtifactSender(
       : plan.voiceText
         ? [{ text: plan.voiceText, lang: plan.lang, rate: plan.rate }]
         : [];
+    // A plan without voice content has nothing to deliver; absence of
+    // content is not a synthesis failure.
+    if (voiceReplies.length === 0) return;
 
     let anyDelivered = false;
 

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

@@ -2356,7 +2356,11 @@ export async function handleTelegramAgentEndRuntime<
       }
     }
     if (!isDeliveryActive()) return;
-    if (outboundReply && deps.sendOutboundReplyArtifacts) {
+    if (
+      outboundReply &&
+      hasOutboundArtifacts &&
+      deps.sendOutboundReplyArtifacts
+    ) {
       try {
         await deps.sendOutboundReplyArtifacts(turn, outboundReply, {
           replyToPrompt: !finalText,

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

@@ -1008,19 +1008,38 @@ 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 = (
+        current: unknown,
+      ): current is TelegramStoredRuntimeProjection => {
+        if (!isRuntimeProjection(current)) return false;
+        const { writtenAtMs: _writtenAtMs, ...existing } = current;
+        return isDeepStrictEqual(existing, semantic);
+      };
       const publication = publicationQueue.then(() => {
         if (!isCurrent()) return false;
+        // Observational state needs no transaction when the published projection already matches.
+        try {
+          if (isUnchanged(read({ path, profile }))) return false;
+        } catch {
+          // An unreadable envelope stays with the transactional publisher's fail-closed path.
+        }
         return (
           publish(
             { path, profile },
             (current) => {
-              if (isRuntimeProjection(current)) {
-                const { writtenAtMs: _writtenAtMs, ...existing } = current;
-                if (isDeepStrictEqual(existing, semantic))
-                  return { value: current, changed: false };
-              }
+              if (isUnchanged(current))
+                return { value: current, changed: false };
               const writtenAtMs = getNowMs();
               if (!Number.isSafeInteger(writtenAtMs) || writtenAtMs < 0)
                 throw new Error(

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -47,7 +47,7 @@
     "@llblab/pi-codex-usage": "0.12.1",
     "@llblab/pi-grow-loop": "0.9.0",
     "@llblab/pi-state-flow": "0.26.4",
-    "@llblab/pi-telegram": "0.53.0",
+    "@llblab/pi-telegram": "0.54.2",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [