@llblab/pi-kit 0.33.1 → 0.34.1

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

@@ -6,7 +6,7 @@
  */
 import { isDeepStrictEqual } from "node:util";
 import { getTelegramBusTransportRetryPolicy } from "./bus-transport.js";
-import { createTelegramBusLocalServer, createUnauthorizedBusAck, rejectTelegramBusRequest, getTelegramBusEnvelopeTrafficClass, getTelegramBusFollowerSocketPath, getTelegramBusProtocolCompatibility, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, parseTelegramBusEnvelope, sendTelegramBusLocalEnvelope, stripTelegramBusApiMetadata, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF, TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, } from "./bus.js";
+import { createTelegramBusLocalServer, createUnauthorizedBusAck, rejectTelegramBusRequest, getTelegramBusEnvelopeTrafficClass, getTelegramBusFollowerSocketPath, getTelegramBusProtocolCompatibility, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, parseTelegramBusEnvelope, sendTelegramBusLocalEnvelope, stripTelegramBusApiMetadata, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF, TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY, hasTelegramBusSteerQueueHandoffCapability, TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT, TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, } from "./bus.js";
 import { escapeHtml } from "./rendering.js";
 import * as Sync from "./sync.js";
 import { parseTelegramIntegerId as asInteger, } from "./target.js";
@@ -881,6 +881,16 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
         if (typeof chatId !== "number")
             return registration.target;
         await deps.topicTargetStore.load();
+        if (options?.recoverConnection && !options.existingWorkspaceBindingOnly) {
+            const epoch = deps.getCurrentLeaderEpoch?.();
+            await Threads.resetTelegramConnectionProvisioning({
+                store: deps.topicTargetStore, owner: "manual-follower", instanceId: registration.instanceId,
+                profileKey: registration.profileKey ?? `manual:${registration.instanceId}`,
+                isCurrent: () => !deps.getCurrentLeaderEpoch ||
+                    (epoch !== undefined && deps.getCurrentLeaderEpoch() === epoch),
+                recordEvent: deps.recordRuntimeEvent,
+            });
+        }
         let restoredPredecessor;
         if (options?.existingWorkspaceBindingOnly && registration.cwd && registration.sessionId &&
             !registration.previousInstanceId && deps.getLiveFollowers && deps.isFollowerProcessAlive) {
@@ -917,6 +927,7 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
             ? deps.topicTargetStore.claimWorkspaceIdentity(registration.cwd, registration.instanceId, registration.previousInstanceId ?? restoredPredecessor?.instanceId, {
                 existingBindingOnly: options?.existingWorkspaceBindingOnly === true,
                 sessionId: registration.sessionId,
+                provisionProfileKey: registration.profileKey ?? `manual:${registration.instanceId}`,
                 onCapacityUnavailable() {
                     capacityUnavailable = true;
                 },
@@ -1129,11 +1140,6 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
                 };
             }
             const probeRequiredRecord = reconnectRecord?.status === "probe-required";
-            const exactSessionHandoff = crossSessionReuse &&
-                !!requestedTarget &&
-                registration.previousInstanceId === reconnectRecord?.instanceId &&
-                requestedTarget.chatId === reconnectRecord.target.chatId &&
-                requestedTarget.threadId === reconnectRecord.target.threadId;
             const requiresVisibilityProbe = crossSessionReuse ||
                 probeRequiredRecord ||
                 recoverableTarget !== undefined;
@@ -1151,18 +1157,14 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
             if (requiresVisibilityProbe && connectedAnnouncement) {
                 try {
                     assertRestoreRegistration();
-                    await deps.callApi(exactSessionHandoff ? "sendChatAction" : "sendMessage", exactSessionHandoff
-                        ? {
-                            chat_id: connectedAnnouncement.target.chatId,
-                            message_thread_id: connectedAnnouncement.target.threadId,
-                            action: "typing",
-                        }
-                        : {
-                            chat_id: connectedAnnouncement.target.chatId,
-                            message_thread_id: connectedAnnouncement.target.threadId,
-                            text: connectedAnnouncement.text,
-                            parse_mode: connectedAnnouncement.parseMode,
-                        });
+                    await deps.callApi(
+                    // Typing is presence, not evidence that a retained Thread still accepts messages.
+                    "sendMessage", {
+                        chat_id: connectedAnnouncement.target.chatId,
+                        message_thread_id: connectedAnnouncement.target.threadId,
+                        text: connectedAnnouncement.text,
+                        parse_mode: connectedAnnouncement.parseMode,
+                    });
                     assertRestoreRegistration();
                     if (recoverableTarget || probeRequiredRecord) {
                         const activatedRecord = deps.topicTargetStore.upsert({
@@ -2120,6 +2122,10 @@ export function createTelegramBusLeaderEnvelopeHandler(deps) {
             !hasTelegramBusCapability(recipient?.protocol, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF)) {
             return rejectTelegramBusRequest(envelope.requestId, "Telegram queue handoff capability was not negotiated.");
         }
+        if (envelope.payload.queueLane === "steer" &&
+            ![deps.protocolIdentity, donor.protocol, recipient?.protocol].every(hasTelegramBusSteerQueueHandoffCapability)) {
+            return rejectTelegramBusRequest(envelope.requestId, "Steer queue handoff capability was not negotiated.");
+        }
         if (!recipient?.registrationGeneration ||
             envelope.recipientRegistrationGeneration !==
                 recipient.registrationGeneration) {
@@ -2257,6 +2263,9 @@ export function createTelegramBusLeaderEnvelopeHandler(deps) {
                     (hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE) &&
                         hasTelegramBusCapability(envelope.registration.protocol, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE));
                 const restoringWorkspace = envelope.kind === "follower.restoreWorkspace";
+                const recoverConnection = envelope.kind === "follower.register" && envelope.recoverConnection === true;
+                const supportsConnectionRecovery = [deps.protocolIdentity, envelope.registration.protocol]
+                    .every(identity => hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY));
                 const supportsWorkspaceAutoConnect = hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT) &&
                     hasTelegramBusCapability(envelope.registration.protocol, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT);
                 if (!compatibility.compatible ||
@@ -2264,7 +2273,8 @@ export function createTelegramBusLeaderEnvelopeHandler(deps) {
                     !readerCompatible() ||
                     (envelope.registration.cwd !== undefined &&
                         envelope.registration.sessionId === undefined) ||
-                    (restoringWorkspace && !supportsWorkspaceAutoConnect)) {
+                    (restoringWorkspace && !supportsWorkspaceAutoConnect) ||
+                    (recoverConnection && !supportsConnectionRecovery)) {
                     return {
                         kind: "bus.ack",
                         requestId: envelope.requestId,
@@ -2305,7 +2315,7 @@ export function createTelegramBusLeaderEnvelopeHandler(deps) {
                         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 });
+                        const target = await deps.provisionFollowerTarget?.(envelope.registration, { existingWorkspaceBindingOnly: restoringWorkspace, ...(recoverConnection ? { recoverConnection: true } : {}) });
                         if (restoringWorkspace && !target) {
                             return {
                                 kind: "bus.ack",
@@ -3026,6 +3036,10 @@ export function createTelegramBusLeaderRuntime(deps) {
             !hasTelegramBusCapability(recipient?.protocol, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF)) {
             return rejectTelegramBusRequest(input.requestId, "Telegram queue handoff capability was not negotiated.");
         }
+        if (input.payload.queueLane === "steer" &&
+            ![deps.protocolIdentity, recipient?.protocol].every(hasTelegramBusSteerQueueHandoffCapability)) {
+            return rejectTelegramBusRequest(input.requestId, "Steer queue handoff capability was not negotiated.");
+        }
         if (!recipient?.registrationGeneration ||
             input.recipientRegistrationGeneration !== recipient.registrationGeneration) {
             return rejectTelegramBusRequest(input.requestId, "Stale Telegram queue handoff recipient registration generation.");

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

@@ -36,6 +36,9 @@ export declare function createTelegramBusProcessRuntime(input: {
 export declare function createTelegramBusAuthSecret(): string;
 export declare const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION: "durable-follower-admission-v1";
 export declare const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF: "queue-handoff-v1";
+/** Unspent Steer lane codec; independent from baseline receipt handoff support. */
+export declare const TELEGRAM_BUS_CAPABILITY_QUEUE_STEER: "queue-steer-v1";
+export declare const TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY: "explicit-connect-recovery-v1";
 export declare const TELEGRAM_BUS_CAPABILITY_INPUT_CUSTODY_REFERENCE: "input-custody-reference-v1";
 export declare const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME: "workspace-thread-rename-v1";
 export declare const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE: "thread-display-mode-v1";
@@ -56,6 +59,9 @@ export declare const TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET: "live-thre
 /** Every live rebinding needs the save/apply/settle trio; held command selections additionally need these two. */
 export declare const TELEGRAM_BUS_LIVE_REBIND_CAPABILITIES: readonly ["live-thread-rebind-save-v1", "live-thread-rebind-apply-v1", "live-thread-rebind-settle-v1"];
 export declare const TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES: readonly ["live-thread-rebind-command-set-v1", "selected-menu-delivery-v1"];
+/** Start/help are restricted menu aliases, negotiated separately from the original held-command set. */
+export declare const TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES: "held-menu-aliases-v1";
+export declare function getTelegramBusHeldCommandCapabilities(name: string): readonly string[];
 export interface TelegramBusSelectedCommandInput {
     name: string;
     target: TelegramTarget & {
@@ -192,6 +198,7 @@ export declare function createTelegramBusProtocolIdentity(input: {
 }): TelegramBusProtocolIdentity;
 export declare function createTelegramCurrentBusProtocolIdentity(capabilities?: readonly string[]): TelegramBusProtocolIdentity;
 export declare function hasTelegramBusCapability(identity: TelegramBusProtocolIdentity | undefined, capability: string): boolean;
+export declare function hasTelegramBusSteerQueueHandoffCapability(identity: TelegramBusProtocolIdentity | undefined): boolean;
 export declare function getTelegramInputCustodyPeerReadiness(followers: readonly Pick<TelegramBusFollowerView, "registrationGeneration" | "protocol">[]): ("ready" | "legacy" | "unknown")[];
 /** Both peers advertise every required capability over a compatible protocol; reads only the two identities. */
 export declare function hasTelegramBusSharedCapabilities(local: TelegramBusProtocolIdentity, remote: TelegramBusProtocolIdentity | undefined, required: readonly string[]): boolean;
@@ -324,6 +331,7 @@ export declare function createTelegramBusFollowerSourceReferenceDeliveryIdentity
 export type TelegramBusEnvelope = ({
     kind: "follower.register";
     requestId: string;
+    recoverConnection?: true;
     registration: TelegramBusInstanceRegistration;
 } | {
     kind: "follower.restoreWorkspace";

package/node_modules/@llblab/pi-telegram/dist/lib/bus.js

@@ -50,6 +50,9 @@ export function createTelegramBusAuthSecret() {
 const TELEGRAM_BUS_PROTOCOL_VERSION = 3;
 export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION = "durable-follower-admission-v1";
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF = "queue-handoff-v1";
+/** Unspent Steer lane codec; independent from baseline receipt handoff support. */
+export const TELEGRAM_BUS_CAPABILITY_QUEUE_STEER = "queue-steer-v1";
+export const TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY = "explicit-connect-recovery-v1";
 export const TELEGRAM_BUS_CAPABILITY_INPUT_CUSTODY_REFERENCE = "input-custody-reference-v1";
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME = "workspace-thread-rename-v1";
 export const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE = "thread-display-mode-v1";
@@ -77,6 +80,13 @@ export const TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES = [
     TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET,
     TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY,
 ];
+/** Start/help are restricted menu aliases, negotiated separately from the original held-command set. */
+export const TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES = "held-menu-aliases-v1";
+export function getTelegramBusHeldCommandCapabilities(name) {
+    return name === "start" || name === "help"
+        ? [...TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES, TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES]
+        : TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES;
+}
 function parseSelectedCommandInput(value) {
     if (!isRecord(value) ||
         !hasOnlyWireKeys(value, ["name", "target"]) ||
@@ -173,6 +183,10 @@ export function createTelegramCurrentBusProtocolIdentity(capabilities = []) {
 export function hasTelegramBusCapability(identity, capability) {
     return identity?.capabilities.includes(capability) ?? false;
 }
+export function hasTelegramBusSteerQueueHandoffCapability(identity) {
+    return hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF) &&
+        hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_QUEUE_STEER);
+}
 export function getTelegramInputCustodyPeerReadiness(followers) {
     return followers.map((follower) => {
         if (!follower.registrationGeneration || !follower.protocol)
@@ -1310,12 +1324,7 @@ export function createTelegramBusLiveRebindController(deps) {
                 : []),
             ...(settling || held ? [TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SETTLE] : []),
             ...(observingHeld ? [TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND_EXECUTION] : []),
-            ...(held
-                ? [
-                    TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET,
-                    TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY,
-                ]
-                : []),
+            ...(held ? getTelegramBusHeldCommandCapabilities(held.name) : []),
         ];
         const follower = deps.getFollower(expected.instanceId), secret = deps.getAuthSecret();
         if (!isCurrent() ||
@@ -2138,8 +2147,13 @@ async function handleTelegramBusSocketLine(line, socket, handleEnvelope, recordT
     }
 }
 function parseRegisterEnvelope(value, requestId, kind) {
+    if (value.recoverConnection !== undefined &&
+        (kind !== "follower.register" || value.recoverConnection !== true))
+        return undefined;
     const registration = parseRegistration(value.registration);
-    return registration ? { kind, requestId, registration } : undefined;
+    return registration ? { kind, requestId, registration,
+        ...(kind === "follower.register" && value.recoverConnection === true ? { recoverConnection: true } : {}),
+    } : undefined;
 }
 function parseFollowerPresenceEnvelope(value, requestId, kind) {
     return typeof value.instanceId === "string" &&

package/node_modules/@llblab/pi-telegram/dist/lib/commands.d.ts

@@ -13,7 +13,7 @@ import { type TelegramBridgeStatusLineOptions } from "./status.ts";
 import { type TelegramApiCallOptions } from "./telegram-api.ts";
 import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import { type TelegramDeferredSourceEvidence, type TelegramLiveSourceCompletionReadiness, type TelegramQueueAdmissionReceiptLike } from "./updates.ts";
-export type TelegramHeldCommandName = "status" | "abort" | "stop" | "next" | "continue";
+export type TelegramHeldCommandName = "status" | "start" | "help" | "abort" | "stop" | "next" | "continue";
 /** Commands-owned no-fold admission over the ordinary recipient queue; source reporting stays separate from removal. */
 export interface TelegramHeldTurnAdmission {
     assertCurrent(): void;

package/node_modules/@llblab/pi-telegram/dist/lib/commands.js

@@ -1446,35 +1446,40 @@ export function createTelegramCommandHandler(deps) {
             },
         };
     };
-    const heldPlans = {
-        status: {
-            completion: "before-effect",
-            effect: "showStatus",
-            prepare(ctx, effects) {
-                const scopedStatus = effects?.showStatus;
-                const captured = {
-                    ...deps,
-                    showStatus: scopedStatus
-                        ? (message, context, options) => {
-                            const address = getTelegramCommandMessageTarget(message);
-                            return scopedStatus.call(effects, address.chatId, address.replyToMessageId, context, address.threadId, options);
-                        }
-                        : deps.showStatus,
-                };
-                return {
-                    captured,
-                    portsCurrent: () => !effects || effects.showStatus === scopedStatus,
-                    async run({ message, command, assertRecipient }) {
-                        const recipientOptions = { assertAuthority: assertRecipient };
-                        return handleTelegramCommandRuntime(command.name, message, ctx, {
-                            ...captured,
-                            assertExecutionCurrent: assertRecipient,
-                            showStatus: (value, context) => captured.showStatus(value, context, recipientOptions),
-                        }, command.args);
-                    },
-                };
-            },
+    // Held followers are already paired and bound. Start/help open the same restricted menu as status;
+    // they cannot pair an operator, bootstrap another Thread or invoke unrestricted Bot API effects.
+    const heldMenuPlan = {
+        completion: "before-effect",
+        effect: "showStatus",
+        prepare(ctx, effects) {
+            const scopedStatus = effects?.showStatus;
+            const captured = {
+                ...deps,
+                showStatus: scopedStatus
+                    ? (message, context, options) => {
+                        const address = getTelegramCommandMessageTarget(message);
+                        return scopedStatus.call(effects, address.chatId, address.replyToMessageId, context, address.threadId, options);
+                    }
+                    : deps.showStatus,
+            };
+            return {
+                captured,
+                portsCurrent: () => !effects || effects.showStatus === scopedStatus,
+                async run({ message, command, assertRecipient }) {
+                    const recipientOptions = { assertAuthority: assertRecipient };
+                    return handleTelegramCommandRuntime("status", message, ctx, {
+                        ...captured,
+                        assertExecutionCurrent: assertRecipient,
+                        showStatus: (value, context) => captured.showStatus(value, context, recipientOptions),
+                    }, command.args);
+                },
+            };
         },
+    };
+    const heldPlans = {
+        status: heldMenuPlan,
+        start: heldMenuPlan,
+        help: heldMenuPlan,
         abort: {
             completion: "after-semantics",
             effect: "sendTextReply",

package/node_modules/@llblab/pi-telegram/dist/lib/extension.js

@@ -59,6 +59,9 @@ import * as WorkspaceRetirement from "./workspace-retirement.js";
 const telegramBusProtocolIdentity = Bus.createTelegramCurrentBusProtocolIdentity([
     Bus.TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION,
     Bus.TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF,
+    Bus.TELEGRAM_BUS_CAPABILITY_QUEUE_STEER,
+    Bus.TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY,
+    Bus.TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
     Bus.TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
@@ -557,7 +560,6 @@ export default function (pi) {
         },
         getQueuedItems: telegramQueueStore.getQueuedItems,
         getQueuedItemCount: Queue.countExecutableTelegramQueueItems,
-        formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
         getRecentRuntimeEvents: runtimeEvents.getEvents,
         getRuntimeLockState: lockRuntime.getStatusLabel,
         ...threadStatusProjectionRuntime,
@@ -796,7 +798,7 @@ export default function (pi) {
             editMessageText: editTelegramMessageText,
         },
     });
-    const { mutation: queueMutationRuntime, dispatchNext: dispatchNextQueuedTelegramTurn, requestNextDispatchAnnouncement, cancelNextDispatchAnnouncement, watchdog: queueDispatchWatchdogRuntime, } = Bindings.createTelegramQueueBindingRuntime({
+    const { mutation: queueMutationRuntime, dispatchNext: dispatchNextQueuedTelegramTurn, requestNextDispatchAnnouncement, cancelNextDispatchAnnouncement, watchdog: queueDispatchWatchdogRuntime, onTurnEnd: onSteerTurnEnd, } = Bindings.createTelegramQueueBindingRuntime({
         store: telegramQueueStore,
         queue,
         lifecycle,
@@ -807,6 +809,8 @@ export default function (pi) {
         promptDispatch: promptDispatchRuntime,
         isIdle,
         hasPendingMessages,
+        isContextCurrent: telegramSessionContextStore.isCurrent,
+        isContextAborted: Pi.isExtensionContextAbortRequested,
         updateStatus,
         sendTextReply,
         sendUserMessage,
@@ -881,6 +885,7 @@ export default function (pi) {
     });
     // --- Queue And Settings Menus ---
     const queueMenuRuntime = MenuQueue.createTelegramQueueMenuRuntime({
+        hasPendingDispatch: lifecycle.hasDispatchPending,
         telegramQueueStore,
         queueMutationRuntime,
         sendInteractiveMessage,
@@ -973,7 +978,7 @@ export default function (pi) {
         isSelectedCommandAvailable(follower, name) {
             return (Bus.hasTelegramBusSharedCapabilities(telegramBusProtocolIdentity, follower.protocol, [
                 ...Bus.TELEGRAM_BUS_LIVE_REBIND_CAPABILITIES,
-                ...Bus.TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES,
+                ...Bus.getTelegramBusHeldCommandCapabilities(name),
             ]) &&
                 typeof selectedMenuDelivery === "function" &&
                 typeof inboundRouteRuntime.prepareHeldCommand === "function" &&
@@ -1222,6 +1227,7 @@ export default function (pi) {
         threadStore,
         runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
         liveRebindCleanupSchedule: Routing.TELEGRAM_LIVE_REBIND_CLEANUP_SCHEDULE,
+        liveRebindCommandCompletionTimeoutMs: 8_000,
         updateStatus,
         isContextActive: telegramSessionContextStore.isCurrent,
         dispatchNextQueuedTelegramTurn,
@@ -1858,6 +1864,14 @@ export default function (pi) {
         recordRuntimeEvent,
     });
     queueHandoffReconciliationBinding.set(Updates.createTelegramQueueHandoffReconciliationRuntimeAssembly({
+        hasPendingDispatch: lifecycle.hasDispatchPending,
+        canHandoffSteerWithRecipient(recipient) {
+            const live = telegramBusFollowerRegistry.get(recipient.instanceId);
+            return live?.registrationGeneration === recipient.registrationGeneration &&
+                [telegramBusProtocolIdentity, live?.protocol,
+                    ...(telegramBusFollowerRegistrationState.isRegistered() ? [telegramBusFollowerRegistrationState.getLeaderProtocol()] : [])]
+                    .every(Bus.hasTelegramBusSteerQueueHandoffCapability);
+        },
         ownsDirect: lockRuntime.owns,
         isFollowerRegistered: telegramBusFollowerRegistrationState.isRegistered,
         isBusEnabled: isTelegramBusRuntimeEnabled,
@@ -2461,6 +2475,7 @@ export default function (pi) {
         sendMarkdownReply,
         sendTextReply,
         dispatchNextQueuedTelegramTurn,
+        onSteerTurnEnd,
         onPromptHandedOff(turn, ctx) {
             updateAdmissionRuntimeBinding
                 .getSettlement()

package/node_modules/@llblab/pi-telegram/dist/lib/lifecycle.d.ts

@@ -5,7 +5,7 @@
  * Transport authority, durable bindings, and queue custody remain with their owners.
  */
 import * as BusFollower from "./bus-follower.ts";
-import type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionCompactFailedEvent, SessionShutdownEvent, SessionStartEvent, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, UIPromptEndEvent, UIPromptStartEvent } from "./pi.ts";
+import type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionCompactFailedEvent, SessionShutdownEvent, SessionStartEvent, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, TurnEndEvent, TurnEndEventResult, UIPromptEndEvent, UIPromptStartEvent } from "./pi.ts";
 import * as Machine from "./machine.ts";
 import * as Queue from "./queue.ts";
 export declare function createAgentStartDedupHook(inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>, resetReplyDedup: () => void, schedulePublication?: (task: () => Promise<void>) => void): (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
@@ -30,6 +30,7 @@ export interface TelegramLifecycleRegistrationDeps {
     onModelSelect: (event: {
         model: TelegramLifecycleModel;
     }, ctx: ExtensionContext) => Promise<void> | void;
+    onTurnEnd?: (event: TurnEndEvent, ctx: ExtensionContext) => TurnEndEventResult | undefined;
     onAgentStart: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
     onToolExecutionStart: (event: ToolExecutionStartEvent, ctx: ExtensionContext) => Promise<void> | void;
     onToolExecutionUpdate?: (event: ToolExecutionUpdateEvent, ctx: ExtensionContext) => Promise<void> | void;

package/node_modules/@llblab/pi-telegram/dist/lib/lifecycle.js

@@ -265,36 +265,47 @@ export function createTelegramBridgeSessionLifecycleDeps(ports) {
     };
 }
 export function createTelegramBridgeSessionLifecycleAssembly(deps) {
-    const isSessionActive = deps.contextStore.isCurrent;
     const suspendForReplacement = BusFollower.createTelegramBusFollowerSessionReplacementSuspender({
         registrationState: deps.follower.registrationState,
         instanceId: deps.follower.instanceId,
         suspendPolling: deps.follower.suspendPolling,
         recordRuntimeEvent: deps.follower.recordRuntimeEvent,
     });
-    let preserveTarget = true;
-    const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
+    // A reused context can be current for a successor; inner awaits need this invocation's generation too.
+    const queueLifecycle = (ctx, generation, preserveTarget = true) => Queue.createTelegramSessionLifecycleRuntime({
         ...deps.queue,
-        isSessionActive,
+        isSessionActive: () => deps.contextStore.isCurrent(ctx, generation),
         stopPolling: () => suspendForReplacement(preserveTarget),
         clearPendingMediaGroups: deps.services.suspendGroupedInput,
     });
     const servicesLifecycle = {
         async onSessionStart(event, ctx) {
+            const generation = deps.contextStore.getGeneration();
+            const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
             const resumeConnection = deps.services.connection?.prepare(event, ctx);
-            await queueLifecycle.onSessionStart(event, ctx);
-            if (!isSessionActive(ctx))
+            await queueLifecycle(ctx, generation).onSessionStart(event, ctx);
+            if (!isCurrent())
                 return;
             deps.services.resumeGroupedInput(ctx);
             await deps.services.delivery.onSessionStart();
-            if (!isSessionActive(ctx))
+            if (!isCurrent())
                 return;
             if (resumeConnection)
                 resumeConnection();
             else
                 await deps.services.polling.onSessionStart(event, ctx);
+            if (!isCurrent())
+                return;
             deps.services.capabilityMonitor.start(ctx);
             deps.services.queueWatchdog.start(ctx);
+            await BusFollower.createTelegramBusFollowerSessionRefreshHook({
+                registrationState: deps.follower.registrationState,
+                registrationRuntime: deps.follower.registrationRuntime,
+                getLeaderState: deps.follower.getLeaderState,
+                isSessionActive: isCurrent,
+                updateStatus: deps.follower.updateStatus,
+                recordRuntimeEvent: deps.follower.recordRuntimeEvent,
+            })(event, ctx);
         },
         async onSessionShutdown(event, ctx) {
             const generation = deps.contextStore.getGeneration();
@@ -302,7 +313,7 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             if (!isCurrent())
                 return;
             deps.services.connection?.onSessionShutdown(event, ctx);
-            preserveTarget = event.reason !== "resume";
+            const preserveTarget = event.reason !== "resume";
             let preserveThread;
             if (event.reason === "quit") {
                 try {
@@ -321,7 +332,7 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
                 return;
             deps.services.queueWatchdog.stop();
             deps.services.capabilityMonitor.stop();
-            await queueLifecycle.onSessionShutdown(event, ctx);
+            await queueLifecycle(ctx, generation, preserveTarget).onSessionShutdown(event, ctx);
             if (!isCurrent())
                 return;
             await deps.services.inboundWorker.onSessionShutdown();
@@ -337,17 +348,7 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             }
         },
     };
-    const followerLifecycle = appendTelegramLifecycleHooks(servicesLifecycle, {
-        onSessionStart: BusFollower.createTelegramBusFollowerSessionRefreshHook({
-            registrationState: deps.follower.registrationState,
-            registrationRuntime: deps.follower.registrationRuntime,
-            getLeaderState: deps.follower.getLeaderState,
-            isSessionActive,
-            updateStatus: deps.follower.updateStatus,
-            recordRuntimeEvent: deps.follower.recordRuntimeEvent,
-        }),
-    }, isSessionActive);
-    return createTelegramSessionGenerationFence(deps.contextStore, followerLifecycle);
+    return createTelegramSessionGenerationFence(deps.contextStore, servicesLifecycle);
 }
 function unrefTelegramLifecycleTimer(timer) {
     if (!timer || typeof timer !== "object")
@@ -605,6 +606,13 @@ export function registerTelegramLifecycleHooks(pi, deps) {
             return;
         await deps.onAgentStart(event, ctx);
     });
+    if (deps.onTurnEnd) {
+        pi.on("turn_end", (event, ctx) => {
+            if (!isActive(ctx))
+                return;
+            return deps.onTurnEnd?.(event, ctx);
+        });
+    }
     pi.on("tool_execution_start", async (event, ctx) => {
         if (!isActive(ctx))
             return;

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

@@ -259,7 +259,9 @@ export interface TelegramLockedPollingRuntime<TContext extends TelegramLockConte
     captureTransportAuthority: (ctx: TContext) => (() => boolean) | undefined;
     onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
     onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
-    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
+    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry, options?: {
+        recoverConnection?: boolean;
+    }) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
 }
@@ -274,7 +276,9 @@ interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext>
     formatStartBlockedMessage?: (ctx: TContext) => string;
     startPolling: (ctx: TContext, options?: TelegramLockedPollingStartOptions) => void | Promise<void>;
     stopPolling: () => Promise<void>;
-    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
+    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry, options?: {
+        recoverConnection?: boolean;
+    }) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
     /** Threaded Mode takeover evidence after failed follower registration; replaces the retired file heartbeat. */

package/node_modules/@llblab/pi-telegram/dist/lib/locks.js

@@ -1625,7 +1625,7 @@ export function createTelegramLockedPollingRuntime(deps) {
                 if (deps.registerFollowerWithOwner) {
                     let failureMessage;
                     try {
-                        const registered = await deps.registerFollowerWithOwner(ctx, acquired.lock);
+                        const registered = await deps.registerFollowerWithOwner(ctx, acquired.lock, options.forceFreshLeaderThread ? { recoverConnection: true } : undefined);
                         if (!isCurrent())
                             return cancelled;
                         if (registered) {
@@ -1838,8 +1838,8 @@ export function createTelegramLockedPollingRuntime(deps) {
             sessionAutoStartRun = run;
         },
         registerFollowerWithOwner: deps.registerFollowerWithOwner
-            ? async (ctx, owner) => {
-                const registered = await deps.registerFollowerWithOwner?.(ctx, owner);
+            ? async (ctx, owner, options) => {
+                const registered = await deps.registerFollowerWithOwner?.(ctx, owner, options);
                 if (registered)
                     deps.updateStatus(ctx);
                 return registered === true;

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

@@ -24,6 +24,7 @@ interface TelegramQueueMenuRuntime<Context> {
     handleCallbackQuery: (query: TelegramQueueMenuCallbackQuery, ctx: Context) => Promise<boolean>;
 }
 export declare function createTelegramQueueMenuRuntime<Context, TModel extends MenuModel = MenuModel>(deps: {
+    hasPendingDispatch?: () => boolean;
     telegramQueueStore: Queue.TelegramQueueStateStore<Context>;
     queueMutationRuntime: Queue.TelegramQueueMutationController<Context>;
     sendInteractiveMessage: TelegramMenuMessageRuntimeDeps["sendInteractiveMessage"];