@llblab/pi-kit 0.27.6 → 0.28.0

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

@@ -5,6 +5,7 @@
  * leader activation hot-switching, local bus server startup, and stale follower pruning.
  */
 
+import { isDeepStrictEqual } from "node:util";
 import * as Sync from "./sync.ts";
 import {
   createTelegramThreadDisplayReconciler,
@@ -12,6 +13,7 @@ import {
   resolveTelegramLiveWorkspaceBindingKeys,
 } from "./thread-display.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
+import * as ThreadNaming from "./thread-naming.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import {
   getTelegramApiErrorRequestTarget,
@@ -19,7 +21,9 @@ import {
   type TelegramApiCallOptions,
 } from "./telegram-api.ts";
 import type { TelegramTarget } from "./target.ts";
+import type { TelegramAttachmentSource } from "./media.ts";
 import * as Threads from "./threads.ts";
+import * as WorkspaceIdentity from "./workspace-identity.ts";
 import {
   createTelegramBusLocalServer,
   createUnauthorizedBusAck,
@@ -39,6 +43,7 @@ import {
   TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION,
   TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF,
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT,
+  TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE,
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
   TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
   TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
@@ -218,7 +223,7 @@ export interface TelegramBusLeaderApiProxyDeps {
     fileName: string,
     options?: TelegramApiCallOptions,
   ) => Promise<unknown>;
-  downloadFile: (fileId: string, destinationDir: string) => Promise<unknown>;
+  downloadFile: (fileId: string, suggestedName: string, source?: TelegramAttachmentSource) => Promise<unknown>;
   recoverStaleTargetError?: (
     apiBody: unknown,
     error: unknown,
@@ -236,7 +241,9 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
     | "onFollowerConfirmedDead"
     | "onFollowerConfirmedDeadPreserved"
     | "getTelegramProfile"
+    | "getAllowedUserId"
     | "provisionFollowerTarget"
+    | "commitFollowerRegistration"
     | "provisionLeaderTarget"
     | "recordRuntimeEvent"
   >;
@@ -310,10 +317,10 @@ export function createTelegramBusFollowerSessionReplacementAuthority(deps: {
     intent: Threads.TelegramSessionReplacementIntent,
   ): { cwd: string; sessionId: string } => {
     const cwd = follower.cwd
-      ? Threads.normalizeTelegramWorkspacePath(follower.cwd)
+      ? WorkspaceIdentity.normalizeTelegramWorkspacePath(follower.cwd)
       : undefined;
     const sessionId = follower.sessionId
-      ? Threads.normalizeTelegramSessionId(follower.sessionId)
+      ? WorkspaceIdentity.normalizeTelegramSessionId(follower.sessionId)
       : undefined;
     const nowMs = getNowMs();
     if (
@@ -645,7 +652,7 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
     });
     if (!renamed) {
       throw new Error(
-        Threads.getTelegramTopicThreadNameValidationError(
+        ThreadNaming.getTelegramTopicThreadNameValidationError(
           threadName,
           record.slot,
         ) ?? "Telegram Workspace Thread name is already reserved.",
@@ -827,7 +834,7 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
       }
       if (!renamed) {
         throw new Error(
-          Threads.getTelegramTopicThreadNameValidationError(
+          ThreadNaming.getTelegramTopicThreadNameValidationError(
             threadName,
             follower.slot,
           ) ?? "Telegram Workspace Thread name is already reserved.",
@@ -921,8 +928,23 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
       },
       () => provisionFollowerTarget(registration, options),
     ),
+    commitFollowerRegistration: (input, publish) => runWorkspaceOperation({
+      operationId: createTelegramWorkspaceAdmissionOperationId(),
+      operationKind: "workspace.publish-follower-registration", scopes: [{ kind: "profile" }],
+    }, async () => {
+      if (!input.target) { publish(); return; }
+      await deps.topicTargetStore.load();
+      const binding = input.registration.cwd && input.registration.sessionId
+        ? deps.topicTargetStore.getWorkspaceBindingByTarget(input.target, input.registration.sessionId) : undefined;
+      const bindingKey = binding && input.registration.cwd && binding.cwd === WorkspaceIdentity.normalizeTelegramWorkspacePath(input.registration.cwd)
+        ? binding.bindingKey : undefined;
+      if (input.target.threadId !== undefined && input.registration.cwd && input.registration.sessionId && !bindingKey)
+        throw new Error("Telegram follower Workspace binding changed before registration publication.");
+      deps.topicTargetStore.commitWorkspaceRestoreRegistration({ target: input.target, slot: input.slot, bindingKey }, publish);
+    }),
     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
     getTelegramProfile: deps.getTelegramProfile,
+    getAllowedUserId: deps.getAllowedUserId,
     runWorkspaceAdmission,
     runWithWorkspaceCapacity,
     callApi: createTelegramBusLeaderApiProxy({
@@ -975,6 +997,12 @@ export type TelegramBusFollowerMessageOwnershipRecorder = (
   record: TelegramBusFollowerMessageOwnershipRecord,
 ) => void;
 
+export type TelegramBusFollowerRegistrationCommitter = (input: {
+  registration: TelegramBusInstanceRegistration;
+  target?: TelegramTarget;
+  slot?: string;
+}, publish: () => void) => Promise<void> | void;
+
 export interface TelegramBusLeaderRuntimeDeps<TContext> {
   socketPath: TelegramBusSocketPathSource;
   commitEndpointPublication?: (commit: () => void) => boolean;
@@ -1015,6 +1043,7 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     registration: TelegramBusInstanceRegistration,
     options?: { existingWorkspaceBindingOnly?: boolean },
   ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+  commitFollowerRegistration?: TelegramBusFollowerRegistrationCommitter;
   renameFollowerThread?: (
     follower: TelegramBusFollowerView,
     threadName: string,
@@ -1026,16 +1055,22 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
   getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
   onFollowerRegistered?: () => void;
+  /** Observation only: reacquire admission and inspect work, never infer completion.
+   * Listener settlement ends its currentness fence; return asynchronous work to retain that fence. */
+  onWorkspaceRestoreRecipientObserved?: (follower: TelegramBusFollowerView, isCurrent: () => boolean) => Promise<void> | void;
   applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
   getThreadDisplayMode?: () => TelegramThreadDisplayMode;
   getCurrentLeaderEpoch?: () => number | string | undefined;
   getTelegramProfile?: () => string | undefined;
+  getAllowedUserId?: () => number | undefined;
   provisionLeaderTarget?: (ctx: TContext) => Promise<void> | void;
   runWorkspaceAdmission?: TelegramBusWorkspaceAdmissionRunner;
   runWithWorkspaceCapacity?: TelegramWorkspaceCapacityRunner;
   getNowMs?: () => number;
   timeoutMs?: number;
   followerPruneIntervalMs?: number;
+  /** Leader housekeeping after each current prune pass; throttling is the callee's concern. */
+  afterFollowerPrune?: () => void;
   followerStaleAfterMs?: number;
   isFollowerProcessAlive?: (pid: number) => boolean;
   shouldCleanupConfirmedDeadFollower?: () => Promise<boolean> | boolean;
@@ -1264,13 +1299,13 @@ export function createTelegramBusFollowerTargetProvisioner(
         workspaceBinding?.threadName ?? registration.threadName;
       const requestedThreadName =
         carriedThreadName &&
-        Threads.isTelegramTopicThreadNameValidForSlot(
+        ThreadNaming.isTelegramTopicThreadNameValidForSlot(
           carriedThreadName,
           registration.slot,
         )
           ? carriedThreadName
           : recoveryHint?.threadName &&
-              Threads.isTelegramTopicThreadNameValidForSlot(
+              ThreadNaming.isTelegramTopicThreadNameValidForSlot(
                 recoveryHint.threadName,
                 recoveryHint.slot,
               )
@@ -1317,6 +1352,10 @@ export function createTelegramBusFollowerTargetProvisioner(
     const runRegistration = async (): Promise<
       (TelegramTarget & { slot?: string; threadName?: string }) | undefined
     > => {
+      if (requestedTarget) deps.topicTargetStore.assertWorkspaceRestoreRegistration({
+        target: requestedTarget, bindingKey: workspaceIdentity?.bindingKey,
+        slot: workspaceIdentity?.slot ?? workspaceBinding?.slot ?? registration.slot,
+      });
       const recoveryTarget = reconnectRecord?.target ?? recoverableTarget;
       if (recoveryTarget) {
         Threads.assertTelegramPendingTopicRecoveryAllowed(deps.topicTargetStore, recoveryTarget);
@@ -1358,6 +1397,10 @@ export function createTelegramBusFollowerTargetProvisioner(
         };
       };
       alignResultWithWorkspaceSlot();
+      const assertRestoreRegistration = (): void => deps.topicTargetStore.assertWorkspaceRestoreRegistration({
+        target: result.target, slot: result.record.slot, bindingKey: workspaceIdentity?.bindingKey,
+      });
+      assertRestoreRegistration();
       const crossSessionReuse =
         !!reconnectRecord &&
         reconnectRecord.instanceId !== registration.instanceId;
@@ -1403,6 +1446,7 @@ export function createTelegramBusFollowerTargetProvisioner(
           : undefined;
       if (requiresVisibilityProbe && connectedAnnouncement) {
         try {
+          assertRestoreRegistration();
           await deps.callApi(
             exactSessionHandoff ? "sendChatAction" : "sendMessage",
             exactSessionHandoff
@@ -1418,6 +1462,7 @@ export function createTelegramBusFollowerTargetProvisioner(
                   parse_mode: connectedAnnouncement.parseMode,
                 },
           );
+          assertRestoreRegistration();
           if (recoverableTarget || probeRequiredRecord) {
             const activatedRecord = deps.topicTargetStore.upsert({
               ...result.record,
@@ -1471,6 +1516,8 @@ export function createTelegramBusFollowerTargetProvisioner(
           }
           connectedAnnouncement = undefined;
         } catch (error) {
+          // Restore protection failures are not evidence that a Telegram topic is missing.
+          assertRestoreRegistration();
           if (Threads.isTelegramTopicTargetStaleError(error)) {
             deps.topicTargetStore.markStaleByTarget(
               result.target,
@@ -1523,7 +1570,10 @@ export function createTelegramBusFollowerTargetProvisioner(
                 ? { threadName: result.record.threadName }
                 : {}),
               slot: workspaceIdentity.slot,
-              journalBindingKeys: [followerProfileKey],
+              ...(workspaceIdentity.sessionId
+                ? { journalSources: [{ sessionId: workspaceIdentity.sessionId, recipientBindingKey: followerProfileKey }],
+                    journalBindingKeys: [] }
+                : { journalBindingKeys: [followerProfileKey] }),
               journalBindingsComplete: true,
               updatedAtMs: getNowMs(),
             },
@@ -1537,6 +1587,7 @@ export function createTelegramBusFollowerTargetProvisioner(
         deps.topicTargetStore.markWorkspaceBindingActiveByTarget(result.target);
         await deps.topicTargetStore.persist();
       }
+      assertRestoreRegistration();
       deps.setSyncState(
         Sync.markTelegramSyncSliceFresh(
           deps.getSyncState(),
@@ -1773,7 +1824,7 @@ export function createTelegramBusLeaderTargetProvisioner<TContext>(
     await deps.topicTargetStore.load();
     const cwd = deps.getCwd?.(ctx);
     const normalizedCwd = cwd
-      ? Threads.normalizeTelegramWorkspacePath(cwd)
+      ? WorkspaceIdentity.normalizeTelegramWorkspacePath(cwd)
       : undefined;
     const profileKey = Threads.getTelegramThreadOwnerKey({
       kind: "leader",
@@ -1925,6 +1976,25 @@ export function createTelegramBusLeaderTargetProvisioner<TContext>(
   };
 }
 
+/** Strict copy of a follower-supplied attachment source; anything malformed falls back to the plain generated name. */
+function parseTelegramBusAttachmentSource(value: unknown): TelegramAttachmentSource | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>, chat = raw.chat as Record<string, unknown> | undefined;
+  const text = (field: unknown) => typeof field === "string" && field.length > 0 && field.length <= 256;
+  if (!text(raw.kind) || !Number.isSafeInteger(raw.messageId) ||
+      (raw.index !== undefined && !Number.isSafeInteger(raw.index)) ||
+      (raw.userFileName !== undefined && !text(raw.userFileName)) || (raw.scope !== undefined && !text(raw.scope)) ||
+      (chat !== undefined && (!chat || typeof chat !== "object" || Array.isArray(chat) || !Number.isSafeInteger(chat.id) ||
+        (chat.type !== undefined && !text(chat.type)) || (chat.username !== undefined && !text(chat.username))))) return undefined;
+  return { kind: raw.kind as string, messageId: raw.messageId as number,
+    ...(raw.index !== undefined ? { index: raw.index as number } : {}),
+    ...(raw.userFileName !== undefined ? { userFileName: raw.userFileName as string } : {}),
+    ...(raw.scope !== undefined ? { scope: raw.scope as string } : {}),
+    ...(chat ? { chat: { id: chat.id as number,
+      ...(chat.type !== undefined ? { type: chat.type as string } : {}),
+      ...(chat.username !== undefined ? { username: chat.username as string } : {}) } } : {}) };
+}
+
 export function createTelegramBusLeaderApiProxy(
   deps: TelegramBusLeaderApiProxyDeps,
 ): (method: string, args: unknown[]) => Promise<unknown> {
@@ -1961,7 +2031,9 @@ export function createTelegramBusLeaderApiProxy(
       }
     }
     if (method === "downloadFile") {
-      return deps.downloadFile(args[0] as string, args[1] as string);
+      // Follower IPC is a trust boundary: only an exact attachment-source shape reaches the file-name builder.
+      const source = parseTelegramBusAttachmentSource(args[2]);
+      return deps.downloadFile(args[0] as string, args[1] as string, ...(source ? [source] : []));
     }
     throw new Error(`Unsupported Telegram bus API method: ${method}`);
   };
@@ -2038,6 +2110,7 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
       >
     | (TelegramTarget & { slot?: string; threadName?: string })
     | undefined;
+  commitFollowerRegistration?: TelegramBusFollowerRegistrationCommitter;
   onFollowerDisconnected?: (
     follower: TelegramBusFollowerView,
   ) => Promise<void> | void;
@@ -2052,9 +2125,14 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
   settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
   getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
   onFollowerRegistered?: () => void;
+  onWorkspaceRestoreRecipientObserved?: TelegramBusLeaderRuntimeDeps<unknown>["onWorkspaceRestoreRecipientObserved"];
+  getWorkspaceRestoreObservationGeneration?: () => number | undefined;
+  recordRuntimeEvent?: TelegramBusLeaderRuntimeDeps<unknown>["recordRuntimeEvent"];
   applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
   getThreadDisplayMode?: () => TelegramThreadDisplayMode;
   getCurrentLeaderEpoch?: () => number | string | undefined;
+  getTelegramProfile?: () => string | undefined;
+  getAllowedUserId?: () => number | undefined;
   runFollowerMutation?: TelegramBusFollowerMutationRunner;
   runWorkspaceAdmission?: TelegramBusWorkspaceAdmissionRunner;
   runWithWorkspaceCapacity?: TelegramWorkspaceCapacityRunner;
@@ -2064,6 +2142,47 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
   const getNowMs = deps.getNowMs ?? Date.now;
   const runFollowerMutation =
     deps.runFollowerMutation ?? createTelegramBusFollowerMutationRunner();
+  const recipientObservations = new Map<string, {
+    epoch: number | string; operator: number; profile: string | undefined; runtimeGeneration: number | undefined;
+    follower: Omit<TelegramBusFollowerView, "lastHeartbeatMs" | "connectedAtMs" | "threadName">;
+  }>();
+  const observeRestoreRecipient = (follower: TelegramBusFollowerView): void => {
+    if (!deps.authSecret || !deps.onWorkspaceRestoreRecipientObserved || !deps.getTelegramProfile ||
+        !hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE) ||
+        !hasTelegramBusCapability(follower.protocol, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE)) return;
+    const instanceId = follower.instanceId;
+    const report = (error: unknown): void => {
+      try { deps.recordRuntimeEvent?.("bus", error, { phase: "workspace-restore-recipient-observation", instanceId }); }
+      catch { /* Optional observation diagnostics must not break transport liveness. */ }
+    };
+    try {
+      const epoch = deps.getCurrentLeaderEpoch?.(), operator = deps.getAllowedUserId?.();
+      const runtimeGeneration = deps.getWorkspaceRestoreObservationGeneration?.();
+      if (epoch === undefined || operator === undefined ||
+          (deps.getWorkspaceRestoreObservationGeneration && runtimeGeneration === undefined)) return;
+      const snapshot = structuredClone(follower);
+      const observed = { epoch, operator, profile: deps.getTelegramProfile(), runtimeGeneration,
+        follower: { ...snapshot, lastHeartbeatMs: undefined, connectedAtMs: undefined, threadName: undefined } };
+      if (isDeepStrictEqual(recipientObservations.get(instanceId), observed)) return;
+      recipientObservations.set(instanceId, observed);
+      const isCurrent = (): boolean => {
+        const live = deps.followerRegistry.get(instanceId);
+        return recipientObservations.get(instanceId) === observed &&
+          deps.getWorkspaceRestoreObservationGeneration?.() === observed.runtimeGeneration &&
+          hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE) &&
+          deps.getCurrentLeaderEpoch?.() === observed.epoch && deps.getAllowedUserId?.() === observed.operator &&
+          deps.getTelegramProfile?.() === observed.profile && !!live &&
+          hasTelegramBusCapability(live.protocol, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE) &&
+          isDeepStrictEqual({ ...live, lastHeartbeatMs: undefined, connectedAtMs: undefined, threadName: undefined }, observed.follower);
+      };
+      // A heartbeat is a hint, not completion proof. Never await the listener before acknowledging it.
+      void Promise.resolve().then(() => {
+        if (isCurrent()) return deps.onWorkspaceRestoreRecipientObserved?.(structuredClone(snapshot), isCurrent);
+      }).catch(report).finally(() => {
+        if (recipientObservations.get(instanceId) === observed) recipientObservations.delete(instanceId);
+      });
+    } catch (error) { report(error); }
+  };
   const handleAgentRequest = async (
     envelope: Extract<
       TelegramBusEnvelope,
@@ -2393,11 +2512,19 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
           runFollowerMutation(envelope.registration, async () => {
           try {
             const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+            const telegramProfile = deps.getTelegramProfile?.();
+            const operatorUserId = deps.getAllowedUserId?.();
+            const registrationCurrent = (): boolean =>
+              (!deps.getCurrentLeaderEpoch || deps.getCurrentLeaderEpoch() === leaderEpoch) &&
+              (!deps.getTelegramProfile || deps.getTelegramProfile() === telegramProfile) &&
+              (!deps.getAllowedUserId || deps.getAllowedUserId() === operatorUserId);
             if (deps.getCurrentLeaderEpoch && leaderEpoch === undefined) {
               throw new Error(
                 "Telegram follower registration requires leader ownership.",
               );
             }
+            if (hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE) && !deps.commitFollowerRegistration)
+              throw new Error("Workspace Restore registration publication protection is unavailable.");
             const target = await deps.provisionFollowerTarget?.(
               envelope.registration,
               { existingWorkspaceBindingOnly: restoringWorkspace },
@@ -2412,14 +2539,7 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
                 message: "No remembered Telegram Workspace Thread is available.",
               };
             }
-            if (
-              deps.getCurrentLeaderEpoch &&
-              deps.getCurrentLeaderEpoch() !== leaderEpoch
-            ) {
-              throw new Error(
-                "Telegram follower registration lost leader ownership.",
-              );
-            }
+            if (!registrationCurrent()) throw new Error("Telegram follower registration lost leader ownership.");
             if (!displayCompatible()) {
               throw new Error("Thread display mode changed; update or restart this follower before connecting.");
             }
@@ -2430,20 +2550,37 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
                 (!registeredSlot || !/^[A-Z]$/u.test(registeredSlot))) {
               throw new Error("Telegram Thread slot authority is unavailable.");
             }
-            deps.followerRegistry.register({
-              ...envelope.registration,
-              connectedAtMs: getNowMs(),
-              target: registeredTarget,
-              ...(registeredSlot ? { slot: registeredSlot } : {}),
-              ...((target?.threadName ?? envelope.registration.threadName)
-                ? {
-                    threadName:
-                      target?.threadName ?? envelope.registration.threadName,
-                  }
-                : {}),
-            });
+            let publicationOpen = true;
+            let published: TelegramBusFollowerView | undefined;
+            const publish = (): void => {
+              if (!publicationOpen) throw new Error("Telegram follower registration publication is no longer available.");
+              publicationOpen = false;
+              if (!registrationCurrent()) throw new Error("Telegram follower registration lost leader ownership.");
+              if (!displayCompatible()) throw new Error("Thread display mode changed; update or restart this follower before connecting.");
+              published = deps.followerRegistry.register({
+                ...envelope.registration,
+                connectedAtMs: getNowMs(),
+                target: registeredTarget,
+                ...(registeredSlot ? { slot: registeredSlot } : {}),
+                ...((target?.threadName ?? envelope.registration.threadName)
+                  ? { threadName: target?.threadName ?? envelope.registration.threadName } : {}),
+              });
+            };
+            try {
+              if (deps.commitFollowerRegistration) await deps.commitFollowerRegistration({
+                registration: envelope.registration, target: registeredTarget, slot: registeredSlot,
+              }, publish);
+              else publish();
+            } finally { publicationOpen = false; }
+            if (!published) throw new Error("Telegram follower registration publication was not confirmed.");
+            if (!registrationCurrent()) throw new Error("Telegram follower registration lost leader ownership.");
+            if (!displayCompatible()) throw new Error("Thread display mode changed; update or restart this follower before connecting.");
             const follower = deps.followerRegistry.get(envelope.registration.instanceId);
-            const displayTitle = follower ? deps.getFollowerDisplayTitle?.(follower) : undefined;
+            if (!follower) throw new Error("Telegram follower registration changed before acknowledgement.");
+            const { lastHeartbeatMs: _publishedHeartbeat, connectedAtMs: _publishedAt, threadName: _publishedName, ...publishedIdentity } = published;
+            const { lastHeartbeatMs: _heartbeat, connectedAtMs: _connectedAt, threadName: _threadName, ...identity } = follower;
+            if (!isDeepStrictEqual(publishedIdentity, identity)) throw new Error("Telegram follower registration changed before acknowledgement.");
+            const displayTitle = deps.getFollowerDisplayTitle?.(follower);
             deps.onFollowerRegistered?.();
             return {
               kind: "bus.ack" as const,
@@ -2814,6 +2951,7 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
           envelope.instanceId,
           getNowMs(),
         );
+        if (follower) observeRestoreRecipient(follower);
         const displayTitle = follower ? deps.getFollowerDisplayTitle?.(follower) : undefined;
         return follower
           ? {
@@ -3276,6 +3414,9 @@ export function createTelegramBusLeaderRuntime<TContext>(
     const expectedGeneration = pruneGeneration;
     let tracked: Promise<void>;
     tracked = pruneFollowers(expectedGeneration)
+      .then(() => {
+        if (pruneGeneration === expectedGeneration) deps.afterFollowerPrune?.();
+      })
       .catch((error) => {
         if (pruneGeneration === expectedGeneration) {
           recordPruneEvent(error, { phase: "follower-prune-owner" });
@@ -3310,6 +3451,7 @@ export function createTelegramBusLeaderRuntime<TContext>(
       forgetPreservation(pendingPreservations.get(registration.instanceId));
       return deps.provisionFollowerTarget!(registration, options);
     } : undefined,
+    commitFollowerRegistration: deps.commitFollowerRegistration,
     onFollowerDisconnected: deps.onFollowerDisconnected,
     renameFollowerThread: deps.renameFollowerThread,
     resetFollowerThreadName: deps.resetFollowerThreadName,
@@ -3317,9 +3459,14 @@ export function createTelegramBusLeaderRuntime<TContext>(
     settleFollowerSessionReplacement: deps.settleFollowerSessionReplacement,
     getFollowerDisplayTitle: deps.getFollowerDisplayTitle,
     onFollowerRegistered: deps.onFollowerRegistered,
+    onWorkspaceRestoreRecipientObserved: deps.onWorkspaceRestoreRecipientObserved,
+    getWorkspaceRestoreObservationGeneration: () => pruneInterval ? pruneGeneration : undefined,
+    recordRuntimeEvent: deps.recordRuntimeEvent,
     applyThreadDisplayMode: deps.applyThreadDisplayMode,
     getThreadDisplayMode: deps.getThreadDisplayMode,
     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
+    getTelegramProfile: deps.getTelegramProfile,
+    getAllowedUserId: deps.getAllowedUserId,
     runFollowerMutation,
     runWorkspaceAdmission: deps.runWorkspaceAdmission,
     runWithWorkspaceCapacity: deps.runWithWorkspaceCapacity,

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

@@ -6,7 +6,17 @@
 
 import { createHash } from "node:crypto";
 import { createConnection } from "node:net";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
+import { resolveTelegramTempDir, resolveTelegramRuntimeDir } from "./paths.ts";
+
+export type TelegramBusEndpointLayout = "consolidated";
+export const TELEGRAM_BUS_MAX_DIRECT_UNIX_ENDPOINT_BYTES = 80;
+
+function requireConsolidatedUnixEndpoint(path: string): string {
+  if (!isAbsolute(path) || resolve(path) !== path) throw new Error("Consolidated Telegram IPC requires an exact absolute runtime path.");
+  // Over-budget logical paths keep their identity; socket resolution applies the bounded private external fallback.
+  return path;
+}
 
 export type TelegramBusTransportKind = "pipe" | "socket";
 
@@ -41,7 +51,7 @@ export const TELEGRAM_BUS_REGISTRATION_RETRY: TelegramBusTransportRetryPolicy =
     delayMs: 150,
   };
 
-export const TELEGRAM_BUS_OPERATION_RETRY: TelegramBusTransportRetryPolicy = {
+const TELEGRAM_BUS_OPERATION_RETRY: TelegramBusTransportRetryPolicy = {
   attempts: 3,
   delayMs: 100,
 };
@@ -103,7 +113,15 @@ export function getTelegramBusLeaderEndpoint(input: {
   agentDir: string;
   platform: NodeJS.Platform | string;
   profileName?: string;
+  layout?: TelegramBusEndpointLayout;
 }): string {
+  if (input.layout !== undefined && input.layout !== "consolidated") throw new Error("Telegram IPC layout is invalid.");
+  if (input.layout === "consolidated") {
+    const scope = createHash("sha256").update(JSON.stringify([input.profileName ?? "default"])).digest("hex").slice(0, 16);
+    return input.platform === "win32"
+      ? getTelegramBusPipePath({ agentDir: input.agentDir, scope: `bus-${scope}` })
+      : requireConsolidatedUnixEndpoint(join(resolveTelegramRuntimeDir(input.agentDir), `bus.${scope}.sock`));
+  }
   const profileScope = input.profileName
     ? normalizeTelegramBusEndpointScope(input.profileName)
     : undefined;
@@ -113,9 +131,7 @@ export function getTelegramBusLeaderEndpoint(input: {
         scope: profileScope ? `bus-${profileScope}` : "bus",
       })
     : join(
-        input.agentDir,
-        "tmp",
-        "telegram",
+        resolveTelegramTempDir(input.agentDir),
         profileScope ? `bus.${profileScope}.sock` : "bus.sock",
       );
 }
@@ -125,7 +141,15 @@ export function getTelegramBusFollowerEndpoint(input: {
   platform: NodeJS.Platform | string;
   instanceId: string;
   profileName?: string;
+  layout?: TelegramBusEndpointLayout;
 }): string {
+  if (input.layout !== undefined && input.layout !== "consolidated") throw new Error("Telegram IPC layout is invalid.");
+  if (input.layout === "consolidated") {
+    const scope = createHash("sha256").update(JSON.stringify([input.profileName ?? "default", input.instanceId])).digest("hex").slice(0, 16);
+    return input.platform === "win32"
+      ? getTelegramBusPipePath({ agentDir: input.agentDir, scope: `follower-${scope}` })
+      : requireConsolidatedUnixEndpoint(join(resolveTelegramRuntimeDir(input.agentDir), `f.${scope}.sock`));
+  }
   const instanceScope = normalizeTelegramBusEndpointScope(input.instanceId);
   const profileScope = input.profileName
     ? normalizeTelegramBusEndpointScope(input.profileName)
@@ -138,9 +162,7 @@ export function getTelegramBusFollowerEndpoint(input: {
           : `follower-${instanceScope}`,
       })
     : join(
-        input.agentDir,
-        "tmp",
-        "telegram",
+        resolveTelegramTempDir(input.agentDir),
         "followers",
         ...(profileScope ? [profileScope] : []),
         `${instanceScope}.sock`,