@llblab/pi-telegram 0.51.5 → 0.52.0

package/dist/lib/bus-follower.js

@@ -6,21 +6,23 @@
  * It must not spawn Pi processes or create hidden Telegram-originated instances.
  */
 import { basename } from "node:path";
-import * as Sync from "./sync.js";
+import { isDeepStrictEqual } from "node:util";
 import * as Threads from "./threads.js";
+import * as WorkspaceIdentity from "./workspace-identity.js";
+import { isWireRecord as isRecord } from "./wire.js";
 import { parseTelegramUpdateJournalQueueOwner } from "./journal.js";
 import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, } from "./locks.js";
 import { isTelegramApiMethodRetrySafe, TelegramApiCommitUnknownError, TelegramApiStaleTargetError, } from "./telegram-api.js";
-import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusFollowerTargetController, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT, } from "./bus.js";
+import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE, } from "./bus.js";
 import { getTelegramBusTransportRetryPolicy, TELEGRAM_BUS_REGISTRATION_RETRY, } from "./bus-transport.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
-export const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
-export const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30_000;
-export const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30_000;
-export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30_000;
+const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
+const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30_000;
+const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30_000;
+const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS = TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS;
-export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS = TELEGRAM_BUS_REGISTRATION_RETRY.attempts;
-export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS = TELEGRAM_BUS_REGISTRATION_RETRY.delayMs;
+const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS = TELEGRAM_BUS_REGISTRATION_RETRY.attempts;
+const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS = TELEGRAM_BUS_REGISTRATION_RETRY.delayMs;
 const TELEGRAM_FOLLOWER_SESSION_HANDOFF_KEY = "__piTelegramFollowerSessionHandoff";
 export function getTelegramFollowerSessionHandoff() {
     const value = globalThis[TELEGRAM_FOLLOWER_SESSION_HANDOFF_KEY];
@@ -44,7 +46,7 @@ export function setTelegramFollowerSessionHandoff(handoff) {
     else
         store[TELEGRAM_FOLLOWER_SESSION_HANDOFF_KEY] = handoff;
 }
-export function isTelegramFollowerSessionHandoffFresh(handoff, options = {}) {
+function isTelegramFollowerSessionHandoffFresh(handoff, options = {}) {
     if (!handoff)
         return false;
     const pid = options.pid ?? process.pid;
@@ -147,16 +149,21 @@ export function createTelegramBusFollowerRuntimeAssembly(ports) {
         (ctx === undefined || readyContext.ctx === ctx) &&
         ports.registrationState.getGeneration() === readyContext.generation &&
         ports.registration.getSessionGeneration?.() === readyContext.sessionGeneration &&
+        ports.registration.getSessionId?.(readyContext.ctx) === readyContext.sessionId &&
         ports.registration.isContextActive?.(readyContext.ctx) !== false);
     const prepareContext = async (ctx) => {
         const generation = ports.registrationState.getGeneration();
         const sessionGeneration = ports.registration.getSessionGeneration?.();
+        const sessionId = ports.registration.getSessionId?.(ctx);
         readyContext = undefined;
+        if (!generation || (sessionId !== undefined && ports.registrationState.getSessionId(sessionId) !== sessionId))
+            throw new Error("Telegram follower session change requires acknowledged leader registration.");
         await ports.registration.onRegistered?.(ctx);
         if (generation && ports.registrationState.getGeneration() === generation &&
             ports.registration.getSessionGeneration?.() === sessionGeneration &&
+            ports.registration.getSessionId?.(ctx) === sessionId &&
             ports.registration.isContextActive?.(ctx) !== false)
-            readyContext = { generation, ctx, sessionGeneration };
+            readyContext = { generation, ctx, sessionGeneration, sessionId };
     };
     const sharedRuntimeDeps = {
         instanceId: ports.instanceId,
@@ -170,10 +177,6 @@ export function createTelegramBusFollowerRuntimeAssembly(ports) {
         getRegistrationGeneration() {
             return isReadyContext() ? readyContext?.generation : undefined;
         },
-        handleReplaceTarget: createTelegramBusFollowerTargetReplacementHandler({
-            ...ports.targetReplacement,
-            ...sharedRuntimeDeps,
-        }),
     });
     let registration;
     const recovery = createTelegramBusFollowerHeartbeatRecoveryHandler({
@@ -205,83 +208,123 @@ export function createTelegramBusFollowerRuntimeAssembly(ports) {
                 await prepareContext(ctx);
         },
     };
-    return { receiver, registration };
+    return { receiver, registration, getReadySessionId: () => isReadyContext() ? readyContext?.sessionId : undefined };
 }
-export function createTelegramBusFollowerTargetReplacementHandler(deps) {
-    const getNowMs = deps.getNowMs ?? Date.now;
-    return (input, ctx) => runTelegramBusFollowerWorkspaceMutation(deps, "workspace.replace-follower-target", async () => {
-        const assertCurrent = (expectedTarget = input.oldTarget) => {
-            const target = deps.registrationState.getTarget();
-            if (!input.registrationGeneration ||
-                deps.registrationState.getGeneration() !==
-                    input.registrationGeneration ||
-                !input.oldTarget ||
-                !expectedTarget ||
-                target?.chatId !== expectedTarget.chatId ||
-                target.threadId !== expectedTarget.threadId ||
-                input.target.chatId !== input.oldTarget.chatId ||
-                input.target.threadId === input.oldTarget.threadId) {
-                throw new Error("Stale Telegram follower target replacement authority.");
-            }
+/** Binds Restore to real Pi lifetime and the current authenticated transport owner, not request fields. */
+export function createTelegramBusFollowerRestoreContextGetter(deps) {
+    return (ctx) => {
+        if (!deps.isContextCurrent(ctx))
+            return undefined;
+        const leader = deps.getLeaderState();
+        const secret = deps.getAuthenticatedSecret();
+        const leaderProtocol = deps.getLeaderProtocol();
+        if (!leaderProtocol || !hasTelegramBusCapability(leaderProtocol, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE))
+            return undefined;
+        if (leader.kind !== "active-elsewhere" || !secret || leader.lock.busSecret !== secret ||
+            !leader.lock.instanceId || leader.lock.leaderEpoch === undefined)
+            return undefined;
+        const profileBindingKey = deps.getProfileBindingKey();
+        const operatorUserId = deps.getOperatorUserId();
+        const sessionId = deps.getSessionId(ctx);
+        const cwd = deps.getCwd(ctx);
+        const generation = deps.getGeneration();
+        if (!profileBindingKey || !sessionId || !cwd || typeof operatorUserId !== "number" ||
+            !Number.isSafeInteger(operatorUserId) || operatorUserId <= 0 ||
+            !Number.isSafeInteger(generation) || generation < 0 || !deps.isContextCurrent(ctx))
+            return undefined;
+        return { executor: { instanceId: leader.lock.instanceId, leaderEpoch: String(leader.lock.leaderEpoch) },
+            profileBindingKey, operatorUserId, sessionId, cwd, generation, leaderProtocol: structuredClone(leaderProtocol) };
+    };
+}
+/** Prepared receiver: its caller authenticates the envelope; no canonical writes, dispatch or cleanup. */
+export function createTelegramBusFollowerWorkspaceRestoreHandler(deps) {
+    return async (input, ctx) => {
+        const captured = deps.getContextAuthority(ctx);
+        if (!captured)
+            throw new Error("Stale Telegram follower Restore context.");
+        const authority = structuredClone(captured);
+        const request = structuredClone(input);
+        if (!authority.profileBindingKey || !authority.sessionId || !authority.cwd ||
+            !authority.executor?.instanceId || !authority.executor.leaderEpoch ||
+            !(typeof authority.generation === "string" ? authority.generation.length > 0 :
+                Number.isSafeInteger(authority.generation) && authority.generation >= 0) ||
+            !Number.isSafeInteger(authority.operatorUserId) || authority.operatorUserId <= 0 ||
+            !request.operationId || !request.registrationGeneration || !["apply", "inspect"].includes(request.mode))
+            throw new Error("Invalid Telegram follower Restore authority.");
+        const assertCurrent = () => {
+            if (!isDeepStrictEqual(deps.getContextAuthority(ctx), authority) ||
+                deps.registrationState.getGeneration() !== request.registrationGeneration)
+                throw new Error("Stale Telegram follower Restore authority.");
         };
         assertCurrent();
-        await deps.topicTargetStore.load();
-        assertCurrent();
-        const nowMs = getNowMs();
-        const currentRecord = Threads.findCurrentTelegramInstanceThreadRecord({
-            records: deps.topicTargetStore.list(),
-            instanceId: deps.instanceId,
-            preferredTarget: input.oldTarget,
-        });
-        if (currentRecord &&
-            (currentRecord.target.chatId !== input.oldTarget.chatId ||
-                currentRecord.target.threadId !== input.oldTarget.threadId)) {
-            throw new Error("Stale Telegram follower binding replacement target.");
-        }
-        const currentSlot = currentRecord?.slot ?? deps.registrationState.getSlot();
-        if (!currentSlot || !/^[A-Z]$/u.test(currentSlot)) {
-            throw new Error("Telegram Thread slot authority is unavailable.");
-        }
-        deps.topicTargetStore.markStaleByTarget(input.oldTarget, "deleted", "Follower thread was replaced by thread restore.");
-        const profileKey = currentRecord?.profileKey ?? deps.getManualFollowerProfileKey();
-        deps.topicTargetStore.upsert({
-            profileKey,
-            owner: {
-                kind: "manual-follower",
-                instanceId: deps.manualFollowerOwnerId,
-            },
-            target: input.target,
-            status: "active",
-            syncStatus: "open",
-            createdAtMs: currentRecord?.createdAtMs ?? nowMs,
-            updatedAtMs: nowMs,
-            lastSyncObservedAtMs: nowMs,
-            lastReconcileAction: "follower-thread-restore",
-            instanceId: deps.instanceId,
-            slot: currentSlot,
-            threadName: currentRecord?.threadName,
-            rerouteConfirmedAtMs: nowMs,
-        });
-        deps.registrationState.setRegistered(true, input.target, {
-            slot: currentSlot,
-            threadName: currentRecord?.threadName,
-            generation: input.registrationGeneration,
-        });
-        await deps.topicTargetStore.persist();
-        assertCurrent(input.target);
-        deps.setSyncState(Sync.markTelegramSyncSliceFresh(deps.getSyncState(), "target-bindings", {
-            nowMs,
-            action: "follower-thread-restore",
-        }));
-        deps.updateStatus(ctx);
-        deps.recordRuntimeEvent?.("bus", "Telegram follower thread target replaced", {
-            phase: "follower-thread-restore",
-            chatId: input.target.chatId,
-            threadId: input.target.threadId,
-            oldThreadId: input.oldTarget?.threadId ?? currentRecord?.target.threadId,
-            slot: currentSlot,
+        if (!deps.getWorkspaceAdmission)
+            throw new Error("Telegram Workspace admission authority is unavailable.");
+        const result = await runTelegramBusFollowerWorkspaceMutation(deps, "workspace.restore-follower-target", async () => {
+            assertCurrent();
+            const intent = deps.readRestoreIntent(request.operationId, authority.profileBindingKey);
+            assertCurrent();
+            if (!intent || intent.request.operationId !== request.operationId ||
+                (intent.phase !== "recipient-issued" && intent.phase !== "ready") ||
+                !isDeepStrictEqual(intent.executor, authority.executor) ||
+                intent.operatorUserId !== authority.operatorUserId || !intent.recipient ||
+                (request.mode === "apply" && (intent.recipient.kind !== "follower" || intent.recipient.instanceId !== deps.instanceId ||
+                    intent.recipient.generation !== request.registrationGeneration)) ||
+                intent.recipient.sessionId !== authority.sessionId || intent.request.binding.sessionId !== authority.sessionId ||
+                intent.request.binding.cwd !== WorkspaceIdentity.normalizeTelegramWorkspacePath(authority.cwd))
+                throw new Error("Telegram follower Restore intent does not match this recipient.");
+            const expected = structuredClone(intent);
+            await deps.topicTargetStore.load();
+            assertCurrent();
+            const observe = (canonical) => {
+                if (!isDeepStrictEqual(deps.readRestoreIntent(request.operationId, authority.profileBindingKey), expected))
+                    throw new Error("Telegram follower Restore intent changed.");
+                assertCurrent();
+                const { binding, target } = expected.request;
+                const bindings = (canonical.workspaceBindings ?? []).filter(value => value.bindingKey === binding.bindingKey);
+                const snapshot = canonical.threads;
+                const records = snapshot.filter(value => value.instanceId === deps.instanceId);
+                const owners = snapshot.filter(value => value.status === "active" &&
+                    (value.slot === binding.slot || isDeepStrictEqual(value.target, target)));
+                if (bindings.length !== 1 || records.length !== 1 || owners.length !== 1 || bindings[0]?.cwd !== binding.cwd ||
+                    bindings[0]?.sessionId !== binding.sessionId || bindings[0]?.slot !== binding.slot || bindings[0]?.inactiveSinceMs !== undefined ||
+                    !isDeepStrictEqual(bindings[0]?.target, target) || records[0]?.status !== "active" ||
+                    records[0]?.owner?.kind !== "manual-follower" ||
+                    records[0]?.slot !== binding.slot || !isDeepStrictEqual(records[0]?.target, target) ||
+                    deps.registrationState.getSlot() !== binding.slot)
+                    throw new Error("Telegram follower Restore canonical binding is not committed.");
+                const localTarget = deps.registrationState.getTarget();
+                const alreadyReady = isDeepStrictEqual(localTarget, target);
+                if (!alreadyReady && !isDeepStrictEqual(localTarget, binding.target))
+                    throw new Error("Telegram follower Restore local target changed.");
+                assertCurrent();
+                if (!alreadyReady && request.mode === "apply") {
+                    if (expected.phase !== "recipient-issued")
+                        throw new Error("Telegram follower Restore readiness regressed.");
+                    deps.registrationState.setRegistered(true, target, { slot: binding.slot,
+                        threadName: records[0]?.threadName, generation: request.registrationGeneration,
+                        leaderProtocol: deps.registrationState.getLeaderProtocol() });
+                }
+                assertCurrent();
+                const observedTarget = deps.registrationState.getTarget();
+                if (!observedTarget || (!isDeepStrictEqual(observedTarget, target) && !isDeepStrictEqual(observedTarget, binding.target)))
+                    throw new Error("Telegram follower Restore local target changed.");
+                const ready = isDeepStrictEqual(observedTarget, target);
+                assertCurrent();
+                return { operationId: request.operationId, recipient: { kind: "follower", instanceId: deps.instanceId,
+                        sessionId: authority.sessionId, generation: request.registrationGeneration },
+                    target: { chatId: observedTarget.chatId, threadId: observedTarget.threadId }, slot: binding.slot, ready };
+            };
+            let result;
+            deps.topicTargetStore.withWorkspaceRestoreSnapshot(expected, snapshot => { result = observe(snapshot); });
+            if (!result)
+                throw new Error("Telegram follower Restore observation was not completed.");
+            return result;
         });
-    });
+        assertCurrent();
+        if (!isDeepStrictEqual(deps.registrationState.getTarget(), result.target) || deps.registrationState.getSlot() !== result.slot)
+            throw new Error("Telegram follower Restore local registration changed after admission release.");
+        return result;
+    };
 }
 export function createTelegramBusFollowerClientRuntime(deps) {
     const createRequestId = createTelegramBusRequestIdFactory(deps.instanceId);
@@ -319,10 +362,6 @@ export function createTelegramBusFollowerClientRuntime(deps) {
             getAuthSecret: deps.getApiAuthSecret,
             getRegistrationGeneration: deps.getRegistrationGeneration,
         }),
-        targetController: createTelegramBusFollowerTargetController({
-            ...sharedClientDeps,
-            getAuthSecret: deps.getForwardingAuthSecret,
-        }),
     };
 }
 export function createTelegramBusFollowerQueueHandoffClient(deps) {
@@ -377,7 +416,7 @@ export function createTelegramBusFollowerQueueHandoffClient(deps) {
             : "Telegram queue handoff did not return an acknowledgement.");
     };
 }
-export function createTelegramBusAgentMessageClient(deps) {
+function createTelegramBusAgentMessageClient(deps) {
     const getNowMs = deps.getNowMs ?? Date.now;
     const timeoutMs = deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
     const request = async (envelope, requestTimeoutMs = timeoutMs) => {
@@ -519,7 +558,13 @@ function isTelegramStaleContextError(error) {
 export function createTelegramBusFollowerSessionReplacementSuspender(deps) {
     const getNowMs = deps.getNowMs ?? Date.now;
     const getPid = deps.getPid ?? (() => process.pid);
-    return async () => {
+    return async (preserveTarget = true) => {
+        if (!preserveTarget) {
+            setTelegramFollowerSessionHandoff(undefined);
+            Threads.setTelegramLeaderSessionHandoff(undefined);
+            await deps.suspendPolling();
+            return;
+        }
         const target = deps.registrationState.getTarget();
         if (deps.registrationState.isRegistered() && target) {
             setTelegramFollowerSessionHandoff({
@@ -646,6 +691,7 @@ export function createTelegramBusFollowerRegistrationState(options = {}) {
     let threadName;
     let displayTitle;
     let generation;
+    let sessionId;
     let leaderProtocol;
     let eligibleElectionSlots = [];
     let recoveryEpoch = 0;
@@ -671,6 +717,7 @@ export function createTelegramBusFollowerRegistrationState(options = {}) {
             return true;
         },
         getGeneration: () => generation,
+        getSessionId: currentSessionId => registered && generation && currentSessionId === sessionId ? sessionId : undefined,
         beginRecovery: () => {
             if (activeRecoveryEpoch !== undefined)
                 return activeRecoveryEpoch;
@@ -714,6 +761,7 @@ export function createTelegramBusFollowerRegistrationState(options = {}) {
                 generation === metadata?.generation &&
                 target?.chatId === nextTarget?.chatId && target?.threadId === nextTarget?.threadId
                 ? displayTitle : undefined;
+            const retainedSessionId = next && registered && generation === metadata?.generation ? sessionId : undefined;
             const availabilityChanged = registered !== next;
             registered = next;
             target = next ? (nextTarget ? { ...nextTarget } : undefined) : undefined;
@@ -723,6 +771,7 @@ export function createTelegramBusFollowerRegistrationState(options = {}) {
                 metadata.displayTitle?.trim() && metadata.displayTitle.length <= 128
                 ? metadata.displayTitle : retainedDisplayTitle;
             generation = next ? metadata?.generation : undefined;
+            sessionId = next ? metadata?.sessionId ?? retainedSessionId : undefined;
             leaderProtocol =
                 next && metadata?.leaderProtocol
                     ? {
@@ -1080,10 +1129,12 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
             if (deps.isContextActive?.(ctx) === false)
                 return false;
             const sessionGeneration = deps.getSessionGeneration?.();
-            const attempt = { ctx, sessionGeneration };
+            const sessionId = deps.getSessionId?.(ctx);
+            const attempt = { ctx, sessionGeneration, sessionId };
             registrationAttempt = attempt;
             const isCurrentRequest = () => registrationAttempt === attempt &&
-                deps.getSessionGeneration?.() === sessionGeneration && deps.isContextActive?.(ctx) !== false;
+                deps.getSessionGeneration?.() === sessionGeneration && deps.getSessionId?.(ctx) === sessionId &&
+                deps.isContextActive?.(ctx) !== false;
             const abandonOwnedRequest = async () => {
                 if (registrationAttempt !== attempt)
                     return;
@@ -1141,7 +1192,7 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
                         ? { slot: deps.registrationState?.getSlot() ?? lastKnownSlot }
                         : {}),
                     cwd: ctx.cwd,
-                    sessionId: deps.getSessionId?.(ctx),
+                    sessionId,
                     pid: getPid(),
                     processBirthId: deps.getProcessBirthId?.(),
                     sessionGeneration,
@@ -1197,7 +1248,9 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
                 local: deps.protocolIdentity,
                 remote: response?.kind === "bus.ack" ? response.protocol : undefined,
             });
-            if (!compatibility.compatible) {
+            // An identity-less error ACK is a rejection/transport failure, not evidence of an incompatible leader.
+            const unidentifiedRejection = response?.kind === "bus.ack" && !response.ok && response.protocol === undefined;
+            if (!compatibility.compatible && !unidentifiedRejection) {
                 stopHeartbeat();
                 activeLeaderSocketPath = undefined;
                 activeAuthSecret = undefined;
@@ -1229,6 +1282,7 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
                 deps.registrationState?.setRegistered(true, registrationResult.target, {
                     ...registrationResult,
                     generation: registrationGeneration,
+                    sessionId,
                     ...(response.protocol
                         ? { leaderProtocol: response.protocol }
                         : {}),
@@ -1283,7 +1337,8 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
         },
         setContext(ctx) {
             if (registrationAttempt && (registrationAttempt.ctx !== ctx ||
-                registrationAttempt.sessionGeneration !== deps.getSessionGeneration?.()))
+                registrationAttempt.sessionGeneration !== deps.getSessionGeneration?.() ||
+                registrationAttempt.sessionId !== deps.getSessionId?.(ctx)))
                 registrationAttempt = undefined;
             activeContext = ctx;
         },
@@ -1551,6 +1606,17 @@ export function prepareTelegramBusFollowerJournaledUpdateForExecution(update, pr
     return prepared;
 }
 export function createTelegramBusFollowerDurableAdmissionRuntime(deps) {
+    // The journal forgets a delivery once its worker completes; this window absorbs a leader retry after a lost ACK.
+    const recentDeliveries = new Map();
+    const getNowMs = deps.getNowMs ?? Date.now;
+    const limit = deps.recentDeliveryLimit ?? { maxAgeMs: 24 * 60 * 60 * 1000, maxEntries: 4096 };
+    const pruneRecentDeliveries = (nowMs) => {
+        for (const [deliveryId, admittedAtMs] of recentDeliveries) {
+            if (recentDeliveries.size <= limit.maxEntries && nowMs - admittedAtMs < limit.maxAgeMs)
+                break;
+            recentDeliveries.delete(deliveryId);
+        }
+    };
     return {
         async admit(envelope, ctx) {
             const delivery = envelope.delivery;
@@ -1592,12 +1658,18 @@ export function createTelegramBusFollowerDurableAdmissionRuntime(deps) {
                             ? { message: carrier }
                             : { edited_message: carrier }),
             };
-            deps.journal.appendBatch([update]);
-            deps.signalWorker(ctx);
-            return {
+            const result = {
                 deliveryId: delivery.deliveryId,
                 sourceUpdateId: delivery.sourceUpdateId,
             };
+            pruneRecentDeliveries(getNowMs());
+            if (recentDeliveries.has(delivery.deliveryId))
+                return result;
+            deps.journal.appendBatch([update]);
+            recentDeliveries.set(delivery.deliveryId, getNowMs());
+            pruneRecentDeliveries(getNowMs());
+            deps.signalWorker(ctx);
+            return result;
         },
     };
 }
@@ -1674,7 +1746,7 @@ export function createTelegramBusForwardedUpdateReceiverRuntime(deps) {
                 envelope.kind !== "leader.forwardEditedMessage" &&
                 envelope.kind !== "leader.wakeInputCustody" &&
                 envelope.kind !== "leader.offerInputCustodyHandoff" &&
-                envelope.kind !== "leader.replaceFollowerTarget" &&
+                envelope.kind !== "leader.workspaceRestore" &&
                 envelope.kind !== "leader.offerQueueHandoff") ||
                 envelope.recipientInstanceId !== deps.instanceId) {
                 return {
@@ -1694,14 +1766,33 @@ export function createTelegramBusForwardedUpdateReceiverRuntime(deps) {
                     message: "Stale Telegram bus follower registration generation.",
                 };
             }
+            if (envelope.kind === "leader.workspaceRestore") {
+                const ctx = deps.getContext();
+                if (!authSecret || !ctx || !deps.isWorkspaceRestoreEnabled?.() || !deps.handleWorkspaceRestore)
+                    return {
+                        kind: "bus.ack", requestId: envelope.requestId, ok: false, message: "Workspace Restore capability is unavailable.",
+                    };
+                try {
+                    const result = await deps.handleWorkspaceRestore({ operationId: envelope.operationId,
+                        registrationGeneration, mode: envelope.mode }, ctx);
+                    if (deps.getAuthSecret?.() !== authSecret || deps.getRegistrationGeneration() !== registrationGeneration ||
+                        deps.getContext() !== ctx || !deps.isWorkspaceRestoreEnabled())
+                        throw new Error("Workspace Restore receiver authority changed.");
+                    return { kind: "bus.ack", requestId: envelope.requestId, ok: true, result };
+                }
+                catch (error) {
+                    deps.recordRuntimeEvent?.("bus", error, { phase: "follower-workspace-restore" });
+                    return { kind: "bus.ack", requestId: envelope.requestId, ok: false,
+                        message: error instanceof Error ? error.message : "Workspace Restore failed." };
+                }
+            }
             if (envelope.kind === "leader.offerInputCustodyHandoff" &&
                 envelope.recipientBindingKey !== deps.getRecipientBindingKey())
                 return {
                     kind: "bus.ack", requestId: envelope.requestId, ok: false,
                     message: "Mismatched Telegram follower handoff recipient identity.",
                 };
-            if (envelope.kind !== "leader.replaceFollowerTarget" &&
-                envelope.kind !== "leader.offerQueueHandoff" &&
+            if (envelope.kind !== "leader.offerQueueHandoff" &&
                 envelope.kind !== "leader.offerInputCustodyHandoff" &&
                 (!envelope.delivery ||
                     envelope.delivery.recipientBindingKey !==
@@ -1733,8 +1824,7 @@ export function createTelegramBusForwardedUpdateReceiverRuntime(deps) {
                     const result = await deps.handleInputCustodyHandoff(envelope, ctx);
                     return { kind: "bus.ack", requestId: envelope.requestId, ok: true, result };
                 }
-                if (envelope.kind !== "leader.replaceFollowerTarget" &&
-                    envelope.kind !== "leader.offerQueueHandoff") {
+                if (envelope.kind !== "leader.offerQueueHandoff") {
                     const sourceReferenceEnabled = envelope.kind === "leader.wakeInputCustody" ||
                         (deps.isSourceReferenceAdmissionEnabled?.() ?? false);
                     if (sourceReferenceEnabled &&
@@ -1752,39 +1842,25 @@ export function createTelegramBusForwardedUpdateReceiverRuntime(deps) {
                         result: receipt,
                     };
                 }
-                if (envelope.kind === "leader.offerQueueHandoff") {
-                    if (!deps.handleQueueHandoff) {
-                        throw new Error("Telegram bus receiver cannot accept queue handoff payloads.");
-                    }
-                    const result = await deps.handleQueueHandoff(envelope, ctx);
-                    const receipt = envelope.payload.admissionReceipts[0];
-                    if (envelope.payload.admissionReceipts.length !== 1 ||
-                        !receipt ||
-                        result.status !== "staged" ||
-                        result.receiptId !== receipt.receiptId ||
-                        result.sourceUpdateIds.length !== receipt.sourceUpdateIds.length ||
-                        result.sourceUpdateIds.some((updateId, index) => updateId !== receipt.sourceUpdateIds[index])) {
-                        throw new Error("Telegram queue handoff staging returned a mismatched receipt.");
-                    }
-                    return {
-                        kind: "bus.ack",
-                        requestId: envelope.requestId,
-                        ok: true,
-                        result,
-                    };
+                if (!deps.handleQueueHandoff) {
+                    throw new Error("Telegram bus receiver cannot accept queue handoff payloads.");
                 }
-                {
-                    if (!deps.handleReplaceTarget) {
-                        throw new Error("Telegram bus receiver cannot replace follower target.");
-                    }
-                    await deps.handleReplaceTarget({
-                        target: envelope.target,
-                        ...(envelope.oldTarget ? { oldTarget: envelope.oldTarget } : {}),
-                        reason: envelope.reason,
-                        registrationGeneration,
-                    }, ctx);
+                const result = await deps.handleQueueHandoff(envelope, ctx);
+                const receipt = envelope.payload.admissionReceipts[0];
+                if (envelope.payload.admissionReceipts.length !== 1 ||
+                    !receipt ||
+                    result.status !== "staged" ||
+                    result.receiptId !== receipt.receiptId ||
+                    result.sourceUpdateIds.length !== receipt.sourceUpdateIds.length ||
+                    result.sourceUpdateIds.some((updateId, index) => updateId !== receipt.sourceUpdateIds[index])) {
+                    throw new Error("Telegram queue handoff staging returned a mismatched receipt.");
                 }
-                return { kind: "bus.ack", requestId: envelope.requestId, ok: true };
+                return {
+                    kind: "bus.ack",
+                    requestId: envelope.requestId,
+                    ok: true,
+                    result,
+                };
             }
             catch (error) {
                 deps.recordRuntimeEvent?.("bus", error, { phase: "follower-forward" });
@@ -1826,6 +1902,3 @@ function parseTarget(value) {
         target.threadId = value.threadId;
     return target;
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

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

@@ -9,6 +9,7 @@ import type { TelegramThreadDisplayMode } from "./config.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 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 { type TelegramBusEnvelope, type TelegramBusFollowerRegistry, type TelegramBusFollowerView, type TelegramBusInstanceRegistration, type TelegramBusProtocolIdentity, type TelegramBusSocketPathSource } from "./bus.ts";
 import type { TelegramQueueHandoffPayload } from "./queue.ts";
@@ -101,14 +102,14 @@ export interface TelegramBusFollowerDisconnectHandlerDeps {
 export interface TelegramBusLeaderApiProxyDeps {
     call: (method: string, body: Record<string, unknown>, options?: TelegramApiCallOptions) => Promise<unknown>;
     callMultipart: (method: string, fields: Record<string, string>, fieldName: string, filePath: string, 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) => Promise<unknown> | unknown;
 }
 export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
     getThreadDisplayMode?: () => TelegramThreadDisplayMode;
     persistThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
     onThreadDisplayChanged?: () => void;
-    runtime: Omit<TelegramBusLeaderRuntimeDeps<TContext>, "callApi" | "onFollowerDisconnected" | "onFollowerConfirmedDead" | "onFollowerConfirmedDeadPreserved" | "getTelegramProfile" | "provisionFollowerTarget" | "provisionLeaderTarget" | "recordRuntimeEvent">;
+    runtime: Omit<TelegramBusLeaderRuntimeDeps<TContext>, "callApi" | "onFollowerDisconnected" | "onFollowerConfirmedDead" | "onFollowerConfirmedDeadPreserved" | "getTelegramProfile" | "getAllowedUserId" | "provisionFollowerTarget" | "commitFollowerRegistration" | "provisionLeaderTarget" | "recordRuntimeEvent">;
     getAllowedUserId: () => number | undefined;
     instanceId: string;
     getCwd?: (ctx: TContext) => string | undefined;
@@ -168,6 +169,11 @@ export interface TelegramBusFollowerMessageOwnershipRecord {
     target?: TelegramTarget;
 }
 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;
@@ -195,6 +201,7 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     provisionFollowerTarget?: (registration: TelegramBusInstanceRegistration, options?: {
         existingWorkspaceBindingOnly?: boolean;
     }) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+    commitFollowerRegistration?: TelegramBusFollowerRegistrationCommitter;
     renameFollowerThread?: (follower: TelegramBusFollowerView, threadName: string) => Promise<{
         threadName: string;
     }> | {
@@ -209,16 +216,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;
@@ -281,6 +294,7 @@ export declare function createTelegramBusLeaderEnvelopeHandler(deps: {
         slot?: string;
         threadName?: string;
     }) | undefined;
+    commitFollowerRegistration?: TelegramBusFollowerRegistrationCommitter;
     onFollowerDisconnected?: (follower: TelegramBusFollowerView) => Promise<void> | void;
     renameFollowerThread?: (follower: TelegramBusFollowerView, threadName: string) => Promise<{
         threadName: string;
@@ -296,9 +310,14 @@ export declare 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;