@llblab/pi-kit 0.30.1 → 0.31.0

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

@@ -385,6 +385,8 @@ export function createTelegramManualFollowerProfileKeyResolver(input: {
 
 export interface TelegramBusFollowerElection {
   expectedOwner?: TelegramLockEntry;
+  /** The expected owner is bus-proven unresponsive; the lock CAS still requires it to be the current owner. */
+  unresponsive?: boolean;
 }
 
 export type TelegramBusFollowerPromotionHandler<TContext> = (
@@ -568,6 +570,10 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
   scheduleRetry?: (retry: () => void, delayMs: number) => void;
   getActiveContext?: () => TContext | undefined;
   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,
@@ -755,7 +761,7 @@ export function createTelegramBusFollowerRuntimeAssembly<
     ...ports.recovery,
     registrationState: ports.registrationState,
     recordRuntimeEvent: ports.recordRuntimeEvent,
-    getRegistrationRuntime: () => registration,
+    getRegistrationRuntime: () => baseRegistration,
   });
   registration = createTelegramBusFollowerRegistrationRuntime({
     ...ports.registration,
@@ -768,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;
@@ -2202,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 =
@@ -2246,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(
@@ -2273,6 +2301,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     binding: TelegramBusFollowerPromotedBinding,
   ) => {
     const retry = () => {
+      if (halted) return;
       const activeCtx = deps.getActiveContext
         ? deps.getActiveContext()
         : fallbackCtx;
@@ -2372,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);
@@ -2410,6 +2459,13 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
           ) {
             return;
           }
+          if (await deps.proveLeaderUnresponsive?.(graceState.lock)) {
+            await promoteToLeader(error, ctx, initialBinding, {
+              expectedOwner: graceState.lock,
+              unresponsive: true,
+            });
+            return;
+          }
           deps.setLifecyclePhase(undefined);
           safeUpdateStatus(ctx);
           deps.recordRuntimeEvent(
@@ -2445,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/node_modules/@llblab/pi-telegram/lib/bus-leader.ts

@@ -3371,6 +3371,14 @@ export function createTelegramBusLeaderEnvelopeHandler(
       return createUnauthorizedBusAck(envelope.requestId);
     }
     switch (envelope.kind) {
+      case "bus.probe":
+        // Liveness only: no registry, routing, journal or Bot API effect.
+        return {
+          kind: "bus.ack" as const,
+          requestId: envelope.requestId,
+          ok: true,
+          protocol: deps.protocolIdentity,
+        };
       case "follower.register":
       case "follower.restoreWorkspace": {
         const compatibility = getTelegramBusProtocolCompatibility({

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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,11 @@ 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,
@@ -2347,6 +2359,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/node_modules/@llblab/pi-telegram/lib/generative-app-worker.mjs

@@ -22,6 +22,11 @@ parentPort.on("message", (message) => {
 });
 
 function runBoundedProcess(input) {
+  // After an abort the parent may terminate this worker before execFile's own abort kill runs, which
+  // would orphan a freshly spawned child; never start a process once cancelled.
+  if (controller.signal.aborted) {
+    return Promise.reject(new Error("Generative App method was cancelled."));
+  }
   if (!input || typeof input !== "object") {
     throw new Error("Generative App run input must be an object.");
   }

package/node_modules/@llblab/pi-telegram/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 {
@@ -5591,36 +5607,40 @@ function createJournalStoreCore(
     }
   };
 
+  const acquireSource = (): JournalSourceAcquisition | undefined =>
+    sourceAccess
+      ? acquireTelegramUpdateJournalFamily(
+          {
+            ...sourceAccess,
+            path,
+            profile,
+            botIdentity: expectedIdentity,
+          },
+          version,
+        )
+      : undefined;
+  const readAcquiredSource = (
+    source: JournalSourceAcquisition,
+  ): ReadTelegramUpdateJournalResult => {
+    const file =
+      source.evidence.kind === "present" ? source.evidence.file : emptyFile();
+    return {
+      file,
+      exists: source.evidence.kind === "present",
+      serializedBytes: assertCapacity(file),
+      source,
+    };
+  };
+
   const runJournalTransaction = <T>(
     operation: (read: typeof readCurrent) => T,
   ): T => {
     try {
       // Acquire before the transaction helper can create parents or staging names.
       // The config continuation excludes participating writers through consumption.
-      const source = sourceAccess
-        ? acquireTelegramUpdateJournalFamily(
-            {
-              ...sourceAccess,
-              path,
-              profile,
-              botIdentity: expectedIdentity,
-            },
-            version,
-          )
-        : undefined;
-      const readSource = (): ReadTelegramUpdateJournalResult => {
-        if (!source) return readCurrent();
-        const file =
-          source.evidence.kind === "present"
-            ? source.evidence.file
-            : emptyFile();
-        return {
-          file,
-          exists: source.evidence.kind === "present",
-          serializedBytes: assertCapacity(file),
-          source,
-        };
-      };
+      const source = acquireSource();
+      const readSource = (): ReadTelegramUpdateJournalResult =>
+        source ? readAcquiredSource(source) : readCurrent();
       return withTelegramFileTransaction(`${path}.transaction`, () =>
         operation(readSource),
       );
@@ -7024,16 +7044,30 @@ function createJournalStoreCore(
       assertCurrent();
       return { issued, entries: result };
     });
+  const projectRead = (current: ReadTelegramUpdateJournalResult) => ({
+    ...cloneFile(current.file),
+    exists: current.exists,
+    serializedBytes: current.serializedBytes,
+  });
   const journal: TelegramUpdateJournalStore = {
     read() {
-      return runMutation((readCurrent) => {
-        const current = readCurrent();
-        return {
-          ...cloneFile(current.file),
-          exists: current.exists,
-          serializedBytes: current.serializedBytes,
-        };
-      });
+      // Atomic publication makes a repair-free read safe without serialization, so idle
+      // status and polling cursor reads create no guards. Any read that needs reconciliation,
+      // or races a compaction, falls back to the serialized path that owns repair.
+      const attempt = (): ReadTelegramUpdateJournalResult | undefined => {
+        try {
+          const source = acquireSource();
+          return source ? readAcquiredSource(source) : readCurrentStrict(false);
+        } catch {
+          return undefined;
+        }
+      };
+      const current = options.withWriterAdmission
+        ? options.withWriterAdmission(attempt)
+        : attempt();
+      return current
+        ? projectRead(current)
+        : runMutation((readCurrent) => projectRead(readCurrent()));
     },
     appendBatch(updates, requestedAcceptedThroughUpdateId) {
       const canonicalUpdates = updates.map((update) =>
@@ -7199,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(
@@ -7213,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();