@llblab/pi-telegram 0.50.0 → 0.51.0

package/lib/commands.ts

@@ -4,6 +4,8 @@
  * Owns Telegram slash-command normalization, bot command metadata, pi-side command registration, and command-initiated session replacement orchestration behind runtime ports
  */
 
+import { randomUUID } from "node:crypto";
+
 import {
   pairTelegramUserIfNeeded,
   type TelegramConfigStore,
@@ -366,7 +368,6 @@ export function createTelegramBotCommandRegistrar(
 export interface TelegramBridgeCommandStartPollingOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
-  requestedThreadName?: string;
 }
 
 export interface TelegramBridgeCommandStartPollingResult {
@@ -407,7 +408,6 @@ export interface TelegramBridgeCommandRegistrationDeps {
     ctx: ExtensionCommandContext,
     profileName: string,
   ) => Promise<boolean>;
-  validateThreadName?: (threadName: string) => string | undefined;
 }
 
 export type TelegramThreadDisplayNameRenamePort = (
@@ -466,17 +466,6 @@ function parseTelegramProfileArg(args: string): string | undefined {
   return word === TELEGRAM_DEFAULT_PROFILE_NAME ? undefined : word;
 }
 
-export function parseTelegramRequestedThreadName(
-  args: string,
-): string | undefined {
-  const token = args
-    .trim()
-    .split(/\s+/)
-    .find((word) => /^as=/i.test(word));
-  const value = token?.slice(3).trim();
-  return value || undefined;
-}
-
 function formatTelegramTakeoverTitle(ctx: ExtensionCommandContext): string {
   return ctx.ui.theme.fg("accent", "pi-telegram");
 }
@@ -498,7 +487,7 @@ export function registerTelegramBridgeCommands(
   deps: TelegramBridgeCommandRegistrationDeps,
 ): void {
   pi.registerCommand("telegram-setup", {
-    description: "Configure Telegram bot token. Use /telegram-setup <name> for named profiles.",
+    description: "<profile> — Configure Telegram bot token",
     handler: async (args, ctx) => {
       await deps.promptForConfig(ctx, parseTelegramProfileArg(args));
     },
@@ -513,28 +502,17 @@ export function registerTelegramBridgeCommands(
     },
   });
   pi.registerCommand("telegram-connect", {
-    description:
-      "Start the Telegram bridge. Use /telegram-connect <profile> and optional as=Name for a fresh Workspace Thread.",
+    description: "<profile> — Start Telegram bridge",
     handler: async (args, ctx) => {
-      const profileName = parseTelegramProfileArg(args);
-      const requestedNameTokens = args
-        .trim()
-        .split(/\s+/)
-        .filter((word) => /^as=/i.test(word));
-      const requestedThreadName = parseTelegramRequestedThreadName(args);
-      const requestedNameError =
-        requestedNameTokens.length > 1
-          ? "Specify at most one as=Name Workspace Thread name."
-          : requestedNameTokens.length === 1 && !requestedThreadName
-            ? "Usage: /telegram-connect [profile] as=Flightprice"
-            : requestedThreadName
-              ? deps.validateThreadName?.(requestedThreadName)
-              : undefined;
-      if (requestedNameError) {
-        ctx.ui.notify(requestedNameError, "warning");
+      if (args.trim().split(/\s+/).some((word) => /^as=/i.test(word))) {
+        ctx.ui.notify(
+          "Thread names are configured from Telegram, not from Pi commands.",
+          "warning",
+        );
         deps.updateStatus(ctx);
         return;
       }
+      const profileName = parseTelegramProfileArg(args);
       if (profileName && deps.activateProfileConfig) {
         const ok = await deps.activateProfileConfig(ctx, profileName);
         if (!ok) {
@@ -597,7 +575,6 @@ export function registerTelegramBridgeCommands(
       };
       let result = await startWithRecovery({
         forceFreshLeaderThread: true,
-        ...(requestedThreadName ? { requestedThreadName } : {}),
       });
       if (result && !result.ok && result.canTakeover) {
         const confirmed = await ctx.ui.confirm(
@@ -612,7 +589,6 @@ export function registerTelegramBridgeCommands(
         result = await startWithRecovery({
           force: true,
           forceFreshLeaderThread: true,
-          ...(requestedThreadName ? { requestedThreadName } : {}),
         });
       }
       if (result?.message) {
@@ -625,8 +601,7 @@ export function registerTelegramBridgeCommands(
     },
   });
   pi.registerCommand("telegram-disconnect", {
-    description:
-      "Stop Telegram; in Threaded Mode, delete this instance's current thread",
+    description: "Stop Telegram and delete current thread in Threaded Mode",
     handler: async (_args, ctx) => {
       const threadName = deps.getDisconnectThreadName?.();
       if (threadName) {
@@ -2337,7 +2312,7 @@ async function handleTelegramCommandRuntime<
 
 export const TELEGRAM_INTERNAL_COMMAND_NAME = "telegram-internal";
 export const TELEGRAM_INTERNAL_COMMAND_DESCRIPTION =
-  "(internal) dispatch one settled Telegram lifecycle action";
+  "Internal Telegram command cannot be run manually";
 export const TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE =
   "This internal Telegram command cannot be run manually.";
 
@@ -2542,6 +2517,7 @@ export function createTelegramSessionActionAssembly(
 
 type TelegramPendingInternalAction = {
   kind: "replace-session";
+  token: string;
   updateId: number;
   target: { chatId: number; threadId?: number; messageId: number };
 };
@@ -2582,9 +2558,9 @@ export function createTelegramSessionActionRuntime(
       registered = true;
       deps.registerCommand(TELEGRAM_INTERNAL_COMMAND_NAME, {
         description: TELEGRAM_INTERNAL_COMMAND_DESCRIPTION,
-        handler: async (_args, ctx) => {
+        handler: async (args, ctx) => {
           const action = pendingAction;
-          if (!action) {
+          if (!action || args.trim() !== action.token) {
             ctx.ui.notify(TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE, "warning");
             return;
           }
@@ -2616,10 +2592,11 @@ export function createTelegramSessionActionRuntime(
       const target = pendingTarget;
       pendingTarget = undefined;
       if (!target) return;
-      pendingAction = { kind: "replace-session", updateId, target };
+      const token = randomUUID();
+      pendingAction = { kind: "replace-session", token, updateId, target };
       void Promise.resolve()
         .then(() =>
-          deps.sendUserMessage(`/${TELEGRAM_INTERNAL_COMMAND_NAME}`, {
+          deps.sendUserMessage(`/${TELEGRAM_INTERNAL_COMMAND_NAME} ${token}`, {
             expandPromptTemplates: true,
           }),
         )

package/lib/extension.ts

@@ -104,7 +104,7 @@ export default function (pi: Pi.ExtensionAPI) {
     WorkspaceAdmission.createTelegramWorkspaceAdmissionRuntimeBinding({
       getProfileName: configStore.getActiveProfileName,
       getBotToken: configStore.getBotToken,
-      getPath: Paths.resolveTelegramWorkspaceAdmissionPath,
+      getPath: Paths.resolveTelegramWorkspaceAdmissionPathForProfile,
       owner: {
         processId: telegramProcessId,
         processBirthId: telegramQueueProcessBirthId,
@@ -187,7 +187,7 @@ export default function (pi: Pi.ExtensionAPI) {
         },
         getWorkspaceAdmission: workspaceAdmissionRuntime.resolve,
       },
-      getLeaderJournalPath: Paths.resolveTelegramUpdateJournalPath,
+      getLeaderJournalPath: Paths.resolveTelegramUpdateJournalPathForProfile,
       getFollowerJournalPath(bindingKey, profileName) {
         return Paths.resolveTelegramFollowerJournalPath(
           bindingKey,
@@ -387,6 +387,51 @@ export default function (pi: Pi.ExtensionAPI) {
           : "clear";
       },
     });
+  const reclaimTelegramWorkspaceDeadOwnerQueue =
+    WorkspaceRetirement.createTelegramWorkspaceDeadOwnerQueueReclaimer({
+      getExternalProtection: captureWorkspaceExternalProtection,
+      getActiveTurnTarget: activeTurnRuntime.getTarget,
+      getQueuedItems: telegramQueueStore.getQueuedItems,
+      resolveLeaderJournal: resolveTelegramUpdateJournalBinding,
+      createFollowerJournalResolver:
+        telegramJournalBindingRuntime.createRecipientResolver,
+      discoverFollowerJournals() {
+        return Journal.discoverTelegramFollowerJournalPaths({
+          directory: Paths.resolveTelegramTempDir(),
+          profileName: configStore.getActiveProfileName(),
+        });
+      },
+      createJournalPathResolver: telegramJournalBindingRuntime.createPathResolver,
+      withJournalReference(binding, operation) {
+        if (!binding.recoveryKey) throw new Error(
+          "Telegram workspace journal reference identity is unavailable.",
+        );
+        return telegramJournalReferenceRegistry.withReference({
+          referenceClass: "workspace-retirement",
+          recoveryKey: binding.recoveryKey,
+        }, operation);
+      },
+      getRecoveryOwner() {
+        return {
+          instanceId: telegramInstanceId,
+          processId: telegramProcessId,
+          processBirthId: telegramQueueProcessBirthId,
+          sessionGeneration: telegramSessionContextStore.getGeneration(),
+        };
+      },
+      getQueueOwnerLiveness: Bus.getTelegramProcessLiveness,
+      onMutationError(error) {
+        recordRuntimeEvent("Telegram dead-owner queue reclamation was refused.", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      },
+      isBindingCurrent(binding) {
+        return WorkspaceRetirement.isCurrentTelegramWorkspaceBinding(
+          threadStore,
+          binding,
+        );
+      },
+    });
   const inactiveThreadCleanupReviewRuntime =
     ThreadCleanupManager.createTelegramInactiveThreadCleanupReviewRuntime({
       getProfileName() { return configStore.getActiveProfileName() ?? "default"; },
@@ -871,6 +916,7 @@ export default function (pi: Pi.ExtensionAPI) {
     storeModelMenuState: modelMenuRuntime.storeState,
     updateStatusMessage: menuActions.updateStatusMessage,
     updateStatus,
+    dismissGuestPlaceholder: guestPlaceholderRuntime.dismiss,
   });
   const threadDisplaySettingsRuntime =
     ThreadDisplay.createTelegramThreadDisplaySettingsRuntime({
@@ -1409,6 +1455,18 @@ export default function (pi: Pi.ExtensionAPI) {
       getWorkspaceAdmission: workspaceAdmissionRuntime.resolve,
       runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
       captureWorkspaceExternalProtection,
+      workspaceRotation: {
+        getAdmission: workspaceAdmissionRuntime.resolve,
+        runExclusive: telegramWorkspaceOperationRuntime.runExclusive,
+        deleteThread: directTelegramApiRuntime.deleteWorkspaceThread,
+        reclaimDeadOwnerQueuedWork(binding, isCurrent) {
+          return telegramWorkspaceOperationRuntime.run({
+            operationId: WorkspaceAdmission.createTelegramWorkspaceAdmissionOperationId(),
+            operationKind: "workspace.reclaim-dead-owner-queue",
+            scopes: [{ kind: "target", target: binding.target }],
+          }, reclaimTelegramWorkspaceDeadOwnerQueue.bind(undefined, binding, isCurrent));
+        },
+      },
       callApi(method, body, options) {
         return directTelegramApiRuntime.call(method, body, options);
       },
@@ -1544,6 +1602,15 @@ export default function (pi: Pi.ExtensionAPI) {
     recordRuntimeEvent,
     runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
   });
+  const prepareThreadPreservationOnQuit = Sync.createTelegramPreservedLeaderQuitHandler({
+    instanceId: telegramInstanceId,
+    topicTargetStore: threadStore,
+    getCurrentLeaderEpoch,
+    getProfileName: configStore.getActiveProfileName,
+    isPollingSuspended: lockedPollingRuntime.isSuspended,
+    resolveAutomaticThreadCleanupEnabled: configControls.resolveAutomaticThreadCleanupEnabled,
+    runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
+  });
   const telegramBridgeSessionLifecycleDeps =
     Lifecycle.createTelegramBridgeSessionLifecycleDeps({
       contextStore: telegramSessionContextStore,
@@ -1598,6 +1665,7 @@ export default function (pi: Pi.ExtensionAPI) {
         capabilityMonitor: telegramThreadCapabilityMonitor,
         queueWatchdog: queueDispatchWatchdogRuntime,
         guestPlaceholder: { stopAll: guestPlaceholderRuntime.stopAll },
+        prepareThreadPreservationOnQuit,
       },
     });
   const sessionLifecycleRuntime =
@@ -1731,14 +1799,6 @@ export default function (pi: Pi.ExtensionAPI) {
       if (!record?.target.threadId) return undefined;
       return record.threadName ?? "current Telegram thread";
     },
-    setRequestedThreadNameForPollingStart:
-      telegramThreadCapabilityState.setRequestedThreadName,
-    validateThreadName(threadName) {
-      return Threads.getTelegramTopicThreadNameValidationError(
-        threadName,
-        undefined,
-      );
-    },
     onTransportChanged() {
       deliveryLifecycleRuntime.onSessionStart();
       activityVerbosityRuntime.reset();

package/lib/journal.ts

@@ -2428,6 +2428,7 @@ export interface TelegramUpdateJournalRuntimeBinding {
   runtimeKey: string;
   recoveryKey: string;
   journal: TelegramUpdateJournalStore;
+  readForProtection?: () => { entries: readonly TelegramUpdateJournalEntry[] };
 }
 
 export interface TelegramUpdateJournalRuntimeBindingResolverDeps {
@@ -2470,6 +2471,19 @@ export function createTelegramUpdateJournalRuntimeBindingResolver(
         profileName,
         botIdentity,
       }),
+      readForProtection() {
+        // Protection must never turn corruption/recovery into empty-work evidence.
+        const evidence = inspectTelegramUpdateJournalFamily({
+          directory: dirname(path), path, profile: profileName, botIdentity,
+          limits: {
+            maxFiles: 1024,
+            maxBytes: TELEGRAM_UPDATE_JOURNAL_MAX_BYTES * 2,
+            maxEntries: TELEGRAM_UPDATE_JOURNAL_MAX_ENTRIES,
+            maxWork: TELEGRAM_UPDATE_JOURNAL_MAX_ENTRIES * 1024,
+          },
+        });
+        return { entries: evidence.kind === "present" ? evidence.file.entries : [] };
+      },
       journal: createTelegramUpdateJournalStore({
         path,
         profileName,

package/lib/lifecycle.ts

@@ -244,7 +244,7 @@ export function createTelegramSessionGenerationFence(
       const generation = store.getGeneration();
       if (!store.isCurrent(ctx, generation)) return;
       await hooks.onSessionShutdown(event, ctx);
-      store.clear(ctx);
+      if (store.isCurrent(ctx, generation)) store.clear(ctx);
     },
   };
 }
@@ -266,6 +266,7 @@ export interface TelegramBridgeSessionServiceRuntime {
   capabilityMonitor: { start(ctx: ExtensionContext): void; stop(): void };
   queueWatchdog: { start(ctx: ExtensionContext): void; stop(): void };
   guestPlaceholder?: { stopAll(): void };
+  prepareThreadPreservationOnQuit?: (isSessionCurrent: () => boolean) => (() => Promise<void>) | undefined;
 }
 
 export interface TelegramBridgeSessionLifecycleAssemblyDeps<
@@ -322,6 +323,7 @@ export interface TelegramBridgeSessionLifecyclePorts<
     capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
     queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];
     guestPlaceholder?: TelegramBridgeSessionServiceRuntime["guestPlaceholder"];
+    prepareThreadPreservationOnQuit?: TelegramBridgeSessionServiceRuntime["prepareThreadPreservationOnQuit"];
   };
 }
 
@@ -350,6 +352,7 @@ export function createTelegramBridgeSessionLifecycleDeps<
       capabilityMonitor: ports.services.capabilityMonitor,
       queueWatchdog: ports.services.queueWatchdog,
       guestPlaceholder: ports.services.guestPlaceholder,
+      prepareThreadPreservationOnQuit: ports.services.prepareThreadPreservationOnQuit,
     },
   };
 }
@@ -385,15 +388,31 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       deps.services.queueWatchdog.start(ctx);
     },
     async onSessionShutdown(event, ctx) {
-      if (!isSessionActive(ctx)) return;
+      const generation = deps.contextStore.getGeneration();
+      const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
+      if (!isCurrent()) return;
+      let preserveThread: (() => Promise<void>) | undefined;
+      if (event.reason === "quit") {
+        try {
+          preserveThread = deps.services.prepareThreadPreservationOnQuit?.(isCurrent);
+        } catch (error) {
+          deps.follower.recordRuntimeEvent("session", error, { phase: "preserve-thread-on-quit" });
+        }
+      }
       deps.services.guestPlaceholder?.stopAll();
       await deps.services.delivery.onSessionShutdown();
-      if (!isSessionActive(ctx)) return;
+      if (!isCurrent()) return;
       deps.services.queueWatchdog.stop();
       deps.services.capabilityMonitor.stop();
       await queueLifecycle.onSessionShutdown(event, ctx);
-      if (!isSessionActive(ctx)) return;
+      if (!isCurrent()) return;
       await deps.services.inboundWorker.onSessionShutdown();
+      if (!isCurrent()) return;
+      try {
+        await preserveThread?.();
+      } catch (error) {
+        deps.follower.recordRuntimeEvent("session", error, { phase: "preserve-thread-on-quit" });
+      }
     },
   };
   const followerLifecycle = appendTelegramLifecycleHooks(

package/lib/locks.ts

@@ -739,7 +739,8 @@ export function isProcessAlive(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (error) {
-    return (error as { code?: string }).code === "EPERM";
+    // Only an absent PID proves death; permission and unexpected failures do not.
+    return (error as { code?: string }).code !== "ESRCH";
   }
 }
 
@@ -1126,6 +1127,7 @@ export interface TelegramLockedPollingRuntime<
   ) => Promise<TelegramLockedPollingStartResult>;
   stop: () => Promise<string>;
   suspend: () => Promise<void>;
+  isSuspended: () => boolean;
   onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
   onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
   registerFollowerWithOwner?: (
@@ -1190,6 +1192,9 @@ export function createTelegramLockedPollingRuntime<
   let takeoverCandidate: TelegramLockEntry | undefined;
   let sessionAutoStartRun: Promise<void> | undefined;
   let pollingGeneration = 0;
+  let suspendedGeneration: number | undefined;
+  let suspensionsInFlight = 0;
+  let startupsInFlight = 0;
   const ownershipCheckMs =
     deps.ownershipCheckMs ?? TELEGRAM_OWNERSHIP_CHECK_MS;
   const ownershipRefreshMs =
@@ -1201,20 +1206,29 @@ export function createTelegramLockedPollingRuntime<
     ownershipRefreshInterval = undefined;
   };
   const suspendPolling = async () => {
-    pollingGeneration += 1;
-    activeContext = undefined;
-    deps.transportMonitor?.stop();
-    deps.stopFollowerRegistration?.();
-    stopOwnershipWatcher();
-    if (sessionAutoStartRun) {
-      await sessionAutoStartRun;
+    const generation = ++pollingGeneration;
+    suspensionsInFlight += 1;
+    try {
+      activeContext = undefined;
+      deps.transportMonitor?.stop();
       deps.stopFollowerRegistration?.();
+      stopOwnershipWatcher();
+      if (sessionAutoStartRun) {
+        await sessionAutoStartRun;
+        deps.stopFollowerRegistration?.();
+      }
+      if (ownershipStop) {
+        await ownershipStop;
+        return;
+      }
+      await deps.stopPolling();
+      // Unsettled starts, overlapping stops or stale completion cannot certify quiescence.
+      if (generation === pollingGeneration && suspensionsInFlight === 1 && startupsInFlight === 0) {
+        suspendedGeneration = generation;
+      }
+    } finally {
+      suspensionsInFlight -= 1;
     }
-    if (ownershipStop) {
-      await ownershipStop;
-      return;
-    }
-    await deps.stopPolling();
   };
   const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
@@ -1261,6 +1275,7 @@ export function createTelegramLockedPollingRuntime<
     if (!isCurrent()) return false;
     activeContext = ctx;
     startOwnershipWatcher(ctx);
+    startupsInFlight += 1;
     try {
       if (!deps.lock.refresh(snapshotLockContext(ctx))) {
         stopOwnershipWatcher();
@@ -1283,6 +1298,8 @@ export function createTelegramLockedPollingRuntime<
       deps.lock.release();
       deps.onTransportAvailabilityChanged?.();
       throw error;
+    } finally {
+      startupsInFlight -= 1;
     }
     if (!isCurrent()) return false;
     if (deps.lock.owns(ctx)) {
@@ -1421,6 +1438,8 @@ export function createTelegramLockedPollingRuntime<
       return "Telegram bridge disconnected.";
     },
     suspend: suspendPolling,
+    isSuspended: () => suspendedGeneration === pollingGeneration &&
+      suspensionsInFlight === 0 && startupsInFlight === 0 && !sessionAutoStartRun && !ownershipStop,
     onPersistentConflict: async (ctx, count) => {
       if (activeContext === undefined || ownershipStop) return;
       if (!(deps.isContextCurrent?.(ctx) ?? activeContext === ctx)) return;

package/lib/menu-queue.ts

@@ -31,6 +31,8 @@ type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
   chatId: number;
   replyToMessageId: number;
+  queueOrder: number;
+  isGuest: boolean;
   queuePosition: number;
   isPriority: boolean;
   priorityEmoji?: string;
@@ -60,6 +62,8 @@ function toTelegramQueueMenuItems<Context>(
     return {
       chatId: item.chatId,
       replyToMessageId: item.replyToMessageId,
+      queueOrder: item.queueOrder,
+      isGuest: item.kind === "prompt" && item.guestQueryId !== undefined,
       queuePosition: index + 1,
       isPriority: item.queueLane === "priority",
       priorityEmoji: item.kind === "prompt" ? item.priorityEmoji : undefined,
@@ -106,7 +110,9 @@ function buildTelegramQueueMenuReplyMarkup(
     return [
       {
         text: label,
-        callback_data: `queue:pick:${item.chatId}:${item.replyToMessageId}`,
+        callback_data: item.isGuest
+          ? `queue:guest-pick:${item.queueOrder}`
+          : `queue:pick:${item.chatId}:${item.replyToMessageId}`,
       },
     ];
   });
@@ -178,6 +184,22 @@ function getTelegramQueueMenuItemText(item: TelegramQueueMenuItem): string {
   return `${heading}\n${preview}`;
 }
 
+function buildTelegramGuestQueueItemSubmenuReplyMarkup(
+  queueOrder: number,
+): TelegramQueueMenuReplyMarkup {
+  return {
+    inline_keyboard: [
+      [{ text: "⬆️ Back", callback_data: "queue:list" }],
+      [
+        {
+          text: "🔴 Skip",
+          callback_data: `queue:guest-skip:${queueOrder}`,
+        },
+      ],
+    ],
+  };
+}
+
 function buildTelegramQueueItemSubmenuReplyMarkup(
   chatId: number,
   replyToMessageId: number,
@@ -217,6 +239,8 @@ interface TelegramQueueMenuCallbackDeps<Context = unknown> {
     chatId: number,
     replyToMessageId: number,
   ) => TelegramQueueMenuItem | undefined;
+  findGuestItem: (queueOrder: number) => TelegramQueueMenuItem | undefined;
+  skipGuest: (queueOrder: number, ctx: Context) => Promise<boolean>;
   togglePriority: (chatId: number, replyToMessageId: number) => boolean;
   setPriority: (
     chatId: number,
@@ -275,6 +299,38 @@ async function handleTelegramQueueMenuCallback<Context>(
     );
     return true;
   }
+  const guestPickMatch = data.match(/^queue:guest-pick:(\d+)$/);
+  if (guestPickMatch) {
+    await handleTelegramGuestQueueMenuPick(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      Number(guestPickMatch[1]),
+      deps,
+    );
+    return true;
+  }
+  const guestSkipMatch = data.match(/^queue:guest-skip:(\d+)$/);
+  if (guestSkipMatch) {
+    const skipped = await deps.skipGuest(Number(guestSkipMatch[1]), ctx);
+    if (!skipped) {
+      await refreshStaleTelegramQueueMenuItem(
+        callbackQueryId,
+        replyChatId,
+        replyMessageId,
+        deps,
+      );
+      return true;
+    }
+    await updateTelegramQueueMenuList(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+      "Guest prompt skipped.",
+    );
+    return true;
+  }
   const pickMatch = data.match(/^queue:pick:(\d+):(\d+)$/);
   if (pickMatch) {
     await handleTelegramQueueMenuPick(
@@ -379,6 +435,31 @@ async function refreshStaleTelegramQueueMenuItem<Context>(
   );
 }
 
+async function handleTelegramGuestQueueMenuPick<Context>(
+  callbackQueryId: string,
+  replyChatId: number,
+  replyMessageId: number,
+  queueOrder: number,
+  deps: TelegramQueueMenuCallbackDeps<Context>,
+): Promise<void> {
+  const item = deps.findGuestItem(queueOrder);
+  if (!item) {
+    return refreshStaleTelegramQueueMenuItem(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+    );
+  }
+  await deps.updateQueueMessage(
+    replyChatId,
+    replyMessageId,
+    getTelegramQueueMenuItemText(item),
+    buildTelegramGuestQueueItemSubmenuReplyMarkup(queueOrder),
+  );
+  await deps.answerCallbackQuery(callbackQueryId);
+}
+
 async function handleTelegramQueueMenuPick<Context>(
   callbackQueryId: string,
   replyChatId: number,
@@ -606,6 +687,7 @@ export function createTelegramQueueMenuRuntime<
     ctx: Context,
   ) => Promise<void>;
   updateStatus: (ctx: Context) => void;
+  dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
 }): TelegramQueueMenuRuntime<Context> {
   const sendQueueMenuMessage = createQueueMenuSendMessageAdapter(
     deps.sendInteractiveMessage,
@@ -628,6 +710,7 @@ export function createTelegramQueueMenuRuntime<
       updateStatusMessage: deps.updateStatusMessage,
       answerCallbackQuery: deps.answerCallbackQuery,
       updateStatus: deps.updateStatus,
+      dismissGuestPlaceholder: deps.dismissGuestPlaceholder,
     }),
   };
 }
@@ -695,6 +778,7 @@ function createQueueMenuCallbackHandler<
     text?: string,
   ) => Promise<void>;
   updateStatus: (ctx: Context) => void;
+  dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
 }) {
   return async (
     query: TelegramQueueMenuCallbackQuery,
@@ -737,6 +821,11 @@ function createQueueMenuCallbackHandler<
     const findItem = (cId: number, rId: number) => {
       return findTelegramQueueMenuItem(toMenuItems(), cId, rId);
     };
+    const findGuestItem = (queueOrder: number) => {
+      return toMenuItems().find((item) => {
+        return item.isGuest && item.queueOrder === queueOrder;
+      });
+    };
     return handleTelegramQueueMenuCallback(
       query.id,
       data,
@@ -746,6 +835,14 @@ function createQueueMenuCallbackHandler<
       {
         getQueuedItems: toMenuItems,
         findItem,
+        findGuestItem,
+        skipGuest: (queueOrder, callbackContext) => {
+          return skipQueuedTelegramGuestPrompt(queueOrder, callbackContext, {
+            getQueueSnapshot,
+            queueMutationRuntime: deps.queueMutationRuntime,
+            dismissGuestPlaceholder: deps.dismissGuestPlaceholder,
+          });
+        },
         togglePriority: (cId, rId) => {
           return toggleQueuedTelegramPromptPriority(cId, rId, ctx, {
             getQueueSnapshot,
@@ -772,6 +869,34 @@ function createQueueMenuCallbackHandler<
   };
 }
 
+async function skipQueuedTelegramGuestPrompt<Context>(
+  queueOrder: number,
+  ctx: Context,
+  deps: {
+    getQueueSnapshot: () => Queue.TelegramQueueItem<Context>[];
+    queueMutationRuntime: Queue.TelegramQueueMutationController<Context>;
+    dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
+  },
+): Promise<boolean> {
+  const item = deps.getQueueSnapshot().find((candidate) => {
+    return candidate.kind === "prompt" &&
+      candidate.guestQueryId !== undefined &&
+      candidate.queueOrder === queueOrder;
+  });
+  if (!item || !deps.queueMutationRuntime.removeGuestPromptByQueueOrder) {
+    return false;
+  }
+  const removed = deps.queueMutationRuntime.removeGuestPromptByQueueOrder(
+    queueOrder,
+    ctx,
+  );
+  if (!removed) return false;
+  if (item.guestInlineMessageId && deps.dismissGuestPlaceholder) {
+    await deps.dismissGuestPlaceholder(item.guestInlineMessageId);
+  }
+  return true;
+}
+
 function getQueueMenuReactionDisposition<Context>(
   item: Queue.TelegramQueueItem<Context>,
   priority: boolean,