@llblab/pi-telegram 0.50.0 → 0.51.0

package/dist/lib/commands.js

@@ -3,6 +3,7 @@
  * Zones: telegram controls, pi agent commands, queue controls
  * 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, TELEGRAM_DEFAULT_PROFILE_NAME, } from "./config.js";
 import { escapeHtml } from "./rendering.js";
 import { createTelegramControlItemBuilder, createTelegramControlQueueController, createTelegramQueueAdmissionReceipt, } from "./queue.js";
@@ -241,14 +242,6 @@ function parseTelegramProfileArg(args) {
         return undefined;
     return word === TELEGRAM_DEFAULT_PROFILE_NAME ? undefined : word;
 }
-export function parseTelegramRequestedThreadName(args) {
-    const token = args
-        .trim()
-        .split(/\s+/)
-        .find((word) => /^as=/i.test(word));
-    const value = token?.slice(3).trim();
-    return value || undefined;
-}
 function formatTelegramTakeoverTitle(ctx) {
     return ctx.ui.theme.fg("accent", "pi-telegram");
 }
@@ -262,7 +255,7 @@ function formatTelegramTakeoverPrompt(ctx, owner) {
 }
 export function registerTelegramBridgeCommands(pi, deps) {
     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));
         },
@@ -275,26 +268,14 @@ export function registerTelegramBridgeCommands(pi, deps) {
         },
     });
     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) {
@@ -357,7 +338,6 @@ export function registerTelegramBridgeCommands(pi, deps) {
             };
             let result = await startWithRecovery({
                 forceFreshLeaderThread: true,
-                ...(requestedThreadName ? { requestedThreadName } : {}),
             });
             if (result && !result.ok && result.canTakeover) {
                 const confirmed = await ctx.ui.confirm(formatTelegramTakeoverTitle(ctx), formatTelegramTakeoverPrompt(ctx, result.owner));
@@ -369,7 +349,6 @@ export function registerTelegramBridgeCommands(pi, deps) {
                 result = await startWithRecovery({
                     force: true,
                     forceFreshLeaderThread: true,
-                    ...(requestedThreadName ? { requestedThreadName } : {}),
                 });
             }
             if (result?.message) {
@@ -382,7 +361,7 @@ export function registerTelegramBridgeCommands(pi, deps) {
         },
     });
     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) {
@@ -1233,7 +1212,7 @@ async function handleTelegramCommandRuntime(commandName, message, ctx, deps, com
     }, commandArgs);
 }
 export const TELEGRAM_INTERNAL_COMMAND_NAME = "telegram-internal";
-export const TELEGRAM_INTERNAL_COMMAND_DESCRIPTION = "(internal) dispatch one settled Telegram lifecycle action";
+export const TELEGRAM_INTERNAL_COMMAND_DESCRIPTION = "Internal Telegram command cannot be run manually";
 export const TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE = "This internal Telegram command cannot be run manually.";
 export function delayTelegramSessionAction(delayMs) {
     return new Promise((resolve) => setTimeout(resolve, delayMs));
@@ -1382,9 +1361,9 @@ export function createTelegramSessionActionRuntime(deps) {
             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;
                     }
@@ -1421,9 +1400,10 @@ export function createTelegramSessionActionRuntime(deps) {
             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}`, {
+                .then(() => deps.sendUserMessage(`/${TELEGRAM_INTERNAL_COMMAND_NAME} ${token}`, {
                 expandPromptTemplates: true,
             }))
                 .catch((error) => {

package/dist/lib/extension.js

@@ -79,7 +79,7 @@ export default function (pi) {
     const workspaceAdmissionRuntime = WorkspaceAdmission.createTelegramWorkspaceAdmissionRuntimeBinding({
         getProfileName: configStore.getActiveProfileName,
         getBotToken: configStore.getBotToken,
-        getPath: Paths.resolveTelegramWorkspaceAdmissionPath,
+        getPath: Paths.resolveTelegramWorkspaceAdmissionPathForProfile,
         owner: {
             processId: telegramProcessId,
             processBirthId: telegramQueueProcessBirthId,
@@ -146,7 +146,7 @@ export default function (pi) {
             },
             getWorkspaceAdmission: workspaceAdmissionRuntime.resolve,
         },
-        getLeaderJournalPath: Paths.resolveTelegramUpdateJournalPath,
+        getLeaderJournalPath: Paths.resolveTelegramUpdateJournalPathForProfile,
         getFollowerJournalPath(bindingKey, profileName) {
             return Paths.resolveTelegramFollowerJournalPath(bindingKey, undefined, profileName);
         },
@@ -295,6 +295,45 @@ export default function (pi) {
                 : "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"; },
         listBindings: threadStore.listWorkspaceBindings,
@@ -689,6 +728,7 @@ export default function (pi) {
         storeModelMenuState: modelMenuRuntime.storeState,
         updateStatusMessage: menuActions.updateStatusMessage,
         updateStatus,
+        dismissGuestPlaceholder: guestPlaceholderRuntime.dismiss,
     });
     const threadDisplaySettingsRuntime = ThreadDisplay.createTelegramThreadDisplaySettingsRuntime({
         getTarget() {
@@ -1168,6 +1208,18 @@ export default function (pi) {
         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);
         },
@@ -1281,6 +1333,15 @@ export default function (pi) {
         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,
         queue: {
@@ -1334,6 +1395,7 @@ export default function (pi) {
             capabilityMonitor: telegramThreadCapabilityMonitor,
             queueWatchdog: queueDispatchWatchdogRuntime,
             guestPlaceholder: { stopAll: guestPlaceholderRuntime.stopAll },
+            prepareThreadPreservationOnQuit,
         },
     });
     const sessionLifecycleRuntime = Lifecycle.createTelegramBridgeSessionLifecycleAssembly(telegramBridgeSessionLifecycleDeps);
@@ -1449,10 +1511,6 @@ export default function (pi) {
                 return undefined;
             return record.threadName ?? "current Telegram thread";
         },
-        setRequestedThreadNameForPollingStart: telegramThreadCapabilityState.setRequestedThreadName,
-        validateThreadName(threadName) {
-            return Threads.getTelegramTopicThreadNameValidationError(threadName, undefined);
-        },
         onTransportChanged() {
             deliveryLifecycleRuntime.onSessionStart();
             activityVerbosityRuntime.reset();

package/dist/lib/journal.d.ts

@@ -610,6 +610,9 @@ export interface TelegramUpdateJournalRuntimeBinding {
     runtimeKey: string;
     recoveryKey: string;
     journal: TelegramUpdateJournalStore;
+    readForProtection?: () => {
+        entries: readonly TelegramUpdateJournalEntry[];
+    };
 }
 export interface TelegramUpdateJournalRuntimeBindingResolverDeps {
     getProfileName: () => string | undefined;

package/dist/lib/journal.js

@@ -1443,6 +1443,19 @@ export function createTelegramUpdateJournalRuntimeBindingResolver(deps) {
                 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/dist/lib/lifecycle.d.ts

@@ -85,6 +85,7 @@ export interface TelegramBridgeSessionServiceRuntime {
     guestPlaceholder?: {
         stopAll(): void;
     };
+    prepareThreadPreservationOnQuit?: (isSessionCurrent: () => boolean) => (() => Promise<void>) | undefined;
 }
 export interface TelegramBridgeSessionLifecycleAssemblyDeps<TQueueItem, TModel = unknown> {
     contextStore: TelegramSessionContextStore<ExtensionContext>;
@@ -111,6 +112,7 @@ export interface TelegramBridgeSessionLifecyclePorts<TQueueItem, TModel = unknow
         capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
         queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];
         guestPlaceholder?: TelegramBridgeSessionServiceRuntime["guestPlaceholder"];
+        prepareThreadPreservationOnQuit?: TelegramBridgeSessionServiceRuntime["prepareThreadPreservationOnQuit"];
     };
 }
 export declare function createTelegramBridgeSessionLifecycleDeps<TQueueItem, TModel = unknown>(ports: TelegramBridgeSessionLifecyclePorts<TQueueItem, TModel>): TelegramBridgeSessionLifecycleAssemblyDeps<TQueueItem, TModel>;

package/dist/lib/lifecycle.js

@@ -91,7 +91,8 @@ export function createTelegramSessionGenerationFence(store, hooks) {
             if (!store.isCurrent(ctx, generation))
                 return;
             await hooks.onSessionShutdown(event, ctx);
-            store.clear(ctx);
+            if (store.isCurrent(ctx, generation))
+                store.clear(ctx);
         },
     };
 }
@@ -115,6 +116,7 @@ export function createTelegramBridgeSessionLifecycleDeps(ports) {
             capabilityMonitor: ports.services.capabilityMonitor,
             queueWatchdog: ports.services.queueWatchdog,
             guestPlaceholder: ports.services.guestPlaceholder,
+            prepareThreadPreservationOnQuit: ports.services.prepareThreadPreservationOnQuit,
         },
     };
 }
@@ -144,18 +146,37 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             deps.services.queueWatchdog.start(ctx);
         },
         async onSessionShutdown(event, ctx) {
-            if (!isSessionActive(ctx))
+            const generation = deps.contextStore.getGeneration();
+            const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
+            if (!isCurrent())
                 return;
+            let preserveThread;
+            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))
+            if (!isCurrent())
                 return;
             deps.services.queueWatchdog.stop();
             deps.services.capabilityMonitor.stop();
             await queueLifecycle.onSessionShutdown(event, ctx);
-            if (!isSessionActive(ctx))
+            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(servicesLifecycle, {

package/dist/lib/locks.d.ts

@@ -133,6 +133,7 @@ export interface TelegramLockedPollingRuntime<TContext extends TelegramLockConte
     start: (ctx: TContext, options?: TelegramLockedPollingStartOptions) => 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?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;

package/dist/lib/locks.js

@@ -551,7 +551,8 @@ export function isProcessAlive(pid) {
         return true;
     }
     catch (error) {
-        return error.code === "EPERM";
+        // Only an absent PID proves death; permission and unexpected failures do not.
+        return error.code !== "ESRCH";
     }
 }
 export function formatTelegramLockEntry(lock) {
@@ -835,6 +836,9 @@ export function createTelegramLockedPollingRuntime(deps) {
     let takeoverCandidate;
     let sessionAutoStartRun;
     let pollingGeneration = 0;
+    let suspendedGeneration;
+    let suspensionsInFlight = 0;
+    let startupsInFlight = 0;
     const ownershipCheckMs = deps.ownershipCheckMs ?? TELEGRAM_OWNERSHIP_CHECK_MS;
     const ownershipRefreshMs = deps.ownershipRefreshMs ?? TELEGRAM_OWNERSHIP_REFRESH_MS;
     const stopOwnershipWatcher = () => {
@@ -846,20 +850,30 @@ export function createTelegramLockedPollingRuntime(deps) {
         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;
+            }
         }
-        if (ownershipStop) {
-            await ownershipStop;
-            return;
+        finally {
+            suspensionsInFlight -= 1;
         }
-        await deps.stopPolling();
     };
     const stopAfterOwnershipLoss = () => {
         if (ownershipStop)
@@ -906,6 +920,7 @@ export function createTelegramLockedPollingRuntime(deps) {
             return false;
         activeContext = ctx;
         startOwnershipWatcher(ctx);
+        startupsInFlight += 1;
         try {
             if (!deps.lock.refresh(snapshotLockContext(ctx))) {
                 stopOwnershipWatcher();
@@ -934,6 +949,9 @@ export function createTelegramLockedPollingRuntime(deps) {
             deps.onTransportAvailabilityChanged?.();
             throw error;
         }
+        finally {
+            startupsInFlight -= 1;
+        }
         if (!isCurrent())
             return false;
         if (deps.lock.owns(ctx)) {
@@ -1075,6 +1093,8 @@ export function createTelegramLockedPollingRuntime(deps) {
             return "Telegram bridge disconnected.";
         },
         suspend: suspendPolling,
+        isSuspended: () => suspendedGeneration === pollingGeneration &&
+            suspensionsInFlight === 0 && startupsInFlight === 0 && !sessionAutoStartRun && !ownershipStop,
         onPersistentConflict: async (ctx, count) => {
             if (activeContext === undefined || ownershipStop)
                 return;

package/dist/lib/menu-queue.d.ts

@@ -33,5 +33,6 @@ export declare function createTelegramQueueMenuRuntime<Context, TModel extends M
     storeModelMenuState: (state: TelegramModelMenuState<TModel>) => void;
     updateStatusMessage: (state: TelegramModelMenuState<TModel>, ctx: Context) => Promise<void>;
     updateStatus: (ctx: Context) => void;
+    dismissGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
 }): TelegramQueueMenuRuntime<Context>;
 export {};

package/dist/lib/menu-queue.js

@@ -34,6 +34,8 @@ function toTelegramQueueMenuItems(items) {
         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,
@@ -72,7 +74,9 @@ function buildTelegramQueueMenuReplyMarkup(items, emptyRefreshIndex = 0) {
         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}`,
             },
         ];
     });
@@ -128,6 +132,19 @@ function getTelegramQueueMenuItemText(item) {
     const preview = `<pre>${escapeTelegramQueueMenuHtmlPreview(item.promptText)}</pre>`;
     return `${heading}\n${preview}`;
 }
+function buildTelegramGuestQueueItemSubmenuReplyMarkup(queueOrder) {
+    return {
+        inline_keyboard: [
+            [{ text: "⬆️ Back", callback_data: "queue:list" }],
+            [
+                {
+                    text: "🔴 Skip",
+                    callback_data: `queue:guest-skip:${queueOrder}`,
+                },
+            ],
+        ],
+    };
+}
 function buildTelegramQueueItemSubmenuReplyMarkup(chatId, replyToMessageId, isPriority, isSkipped) {
     return {
         inline_keyboard: [
@@ -171,6 +188,21 @@ async function handleTelegramQueueMenuCallback(callbackQueryId, data, replyChatI
         await updateTelegramQueueMenuList(callbackQueryId, replyChatId, replyMessageId, deps, undefined, refreshMatch[1] === undefined ? 0 : Number(refreshMatch[1]));
         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(callbackQueryId, replyChatId, replyMessageId, Number(pickMatch[1]), Number(pickMatch[2]), deps);
@@ -208,6 +240,14 @@ async function updateTelegramQueueMenuList(callbackQueryId, replyChatId, replyMe
 async function refreshStaleTelegramQueueMenuItem(callbackQueryId, replyChatId, replyMessageId, deps) {
     await updateTelegramQueueMenuList(callbackQueryId, replyChatId, replyMessageId, deps, "Item no longer in queue.");
 }
+async function handleTelegramGuestQueueMenuPick(callbackQueryId, replyChatId, replyMessageId, queueOrder, deps) {
+    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(callbackQueryId, replyChatId, replyMessageId, chatId, msgId, deps) {
     const item = deps.findItem(chatId, msgId);
     if (!item) {
@@ -272,6 +312,7 @@ export function createTelegramQueueMenuRuntime(deps) {
             updateStatusMessage: deps.updateStatusMessage,
             answerCallbackQuery: deps.answerCallbackQuery,
             updateStatus: deps.updateStatus,
+            dismissGuestPlaceholder: deps.dismissGuestPlaceholder,
         }),
     };
 }
@@ -318,9 +359,22 @@ function createQueueMenuCallbackHandler(deps) {
         const findItem = (cId, rId) => {
             return findTelegramQueueMenuItem(toMenuItems(), cId, rId);
         };
+        const findGuestItem = (queueOrder) => {
+            return toMenuItems().find((item) => {
+                return item.isGuest && item.queueOrder === queueOrder;
+            });
+        };
         return handleTelegramQueueMenuCallback(query.id, data, chatId, messageId, ctx, {
             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,
@@ -345,6 +399,23 @@ function createQueueMenuCallbackHandler(deps) {
         });
     };
 }
+async function skipQueuedTelegramGuestPrompt(queueOrder, ctx, deps) {
+    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(item, priority, skipped) {
     if (priority && skipped) {
         return {

package/dist/lib/paths.d.ts

@@ -14,6 +14,12 @@ export interface TelegramAgentDirResolutionInput {
  * 3. Fallback: `~/.pi/agent`.
  */
 export declare function resolveAgentDir(input?: TelegramAgentDirResolutionInput): string;
+/**
+ * Pure reference preflight against an independently approved resource path.
+ * Reject aliases; never repair relative historical references or redirect storage.
+ * Equality proves spelling only, not file identity, consumer closure or migration readiness.
+ */
+export declare function requireTelegramStoragePathReference(path: string, expectedPath: string): string;
 /** Telegram bridge configuration file (<agentDir>/telegram.json). */
 export declare function resolveTelegramConfigPath(): string;
 /** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
@@ -28,12 +34,16 @@ export declare function getTelegramDiagnosticsDisplayPaths(profileName?: string)
 };
 /** Durable Workspace admission ledger (<agentDir>/tmp/telegram/workspace-admission[.<profile>].json). */
 export declare function resolveTelegramWorkspaceAdmissionPath(agentDir?: string, profileName?: string): string;
+/** Profile-only callback shape; binds storage to the configured agent directory. */
+export declare function resolveTelegramWorkspaceAdmissionPathForProfile(profileName?: string): string;
 /** Durable inactive Thread cleanup work-set journal. */
 export declare function resolveTelegramThreadCleanupWorkPath(agentDir?: string, profileName?: string): string;
 /** Durable agent-authored channel post journal. */
 export declare function resolveTelegramChannelPostJournalPath(agentDir?: string, profileName?: string): string;
 /** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
 export declare function resolveTelegramUpdateJournalPath(agentDir?: string, profileName?: string): string;
+/** Profile-only callback shape; binds storage to the configured agent directory. */
+export declare function resolveTelegramUpdateJournalPathForProfile(profileName?: string): string;
 /** Durable follower delivery journal, isolated by stable recipient binding. */
 export declare function resolveTelegramFollowerJournalPath(recipientBindingKey: string, agentDir?: string, profileName?: string): string;
 /** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */