@grinev/opencode-telegram-bot 0.19.3 → 0.20.1

package/dist/bot/commands/sessions.js

@@ -4,6 +4,7 @@ import { resolveProjectAgent } from "../../agent/manager.js";
 import { setCurrentSession } from "../../session/manager.js";
 import { getCurrentProject } from "../../settings/manager.js";
 import { clearAllInteractionState } from "../../interaction/cleanup.js";
+import { interactionManager } from "../../interaction/manager.js";
 import { keyboardManager } from "../../keyboard/manager.js";
 import { appendInlineMenuCancelButton, ensureActiveInlineMenu, replyWithInlineMenu, } from "../handlers/inline-menu.js";
 import { isForegroundBusy, replyBusyBlocked } from "../utils/busy-guard.js";
@@ -12,9 +13,22 @@ import { safeBackgroundTask } from "../../utils/safe-background-task.js";
 import { config } from "../../config.js";
 import { getDateLocale, t } from "../../i18n/index.js";
 import { attachToSession } from "../../attach/service.js";
+import { renderAssistantFinalPartsSafe } from "../utils/assistant-rendering.js";
+import { sendRenderedBotPart } from "../utils/telegram-text.js";
 const SESSION_CALLBACK_PREFIX = "session:";
 const SESSION_PAGE_CALLBACK_PREFIX = "session:page:";
+const BACKGROUND_SESSION_CALLBACK_PREFIX = "background-session:";
 const SESSION_FETCH_EXTRA_COUNT = 1;
+const BACKGROUND_SESSION_KIND_CALLBACK_MARKERS = {
+    assistant_response: "a",
+    question_asked: "q",
+    permission_asked: "p",
+};
+const BACKGROUND_SESSION_KIND_BY_CALLBACK_MARKER = {
+    a: "assistant_response",
+    q: "question_asked",
+    p: "permission_asked",
+};
 function buildSessionPageCallback(page) {
     return `${SESSION_PAGE_CALLBACK_PREFIX}${page}`;
 }
@@ -39,6 +53,35 @@ function parseSessionIdCallback(data) {
     const sessionId = data.slice(SESSION_CALLBACK_PREFIX.length);
     return sessionId.length > 0 ? sessionId : null;
 }
+function parseBackgroundSessionCallback(data) {
+    if (!data.startsWith(BACKGROUND_SESSION_CALLBACK_PREFIX)) {
+        return null;
+    }
+    const payload = data.slice(BACKGROUND_SESSION_CALLBACK_PREFIX.length);
+    const markerSeparatorIndex = payload.indexOf(":");
+    if (markerSeparatorIndex < 0) {
+        return payload.length > 0 ? { sessionId: payload, kind: null } : null;
+    }
+    const marker = payload.slice(0, markerSeparatorIndex);
+    const sessionId = payload.slice(markerSeparatorIndex + 1);
+    const kind = BACKGROUND_SESSION_KIND_BY_CALLBACK_MARKER[marker];
+    if (!kind || sessionId.length === 0) {
+        return null;
+    }
+    return { sessionId, kind };
+}
+async function removeCallbackReplyMarkup(ctx) {
+    try {
+        await ctx.editMessageReplyMarkup();
+    }
+    catch (err) {
+        logger.debug("[Sessions] Failed to remove background session button:", err);
+    }
+}
+export function buildBackgroundSessionOpenKeyboard(sessionId, kind) {
+    const marker = BACKGROUND_SESSION_KIND_CALLBACK_MARKERS[kind];
+    return new InlineKeyboard().text(t("background.open_session_button"), `${BACKGROUND_SESSION_CALLBACK_PREFIX}${marker}:${sessionId}`);
+}
 function formatSessionsSelectText(page) {
     if (page === 0) {
         return t("sessions.select");
@@ -119,6 +162,140 @@ export async function sessionsCommand(ctx) {
         await ctx.reply(t("sessions.fetch_error"));
     }
 }
+async function selectSessionById(ctx, deps, sessionId, options) {
+    const currentProject = getCurrentProject();
+    if (!currentProject) {
+        clearAllInteractionState("session_select_project_missing");
+        await ctx.answerCallbackQuery();
+        await ctx.reply(t("sessions.select_project_first"));
+        return;
+    }
+    const { data: session, error } = await opencodeClient.session.get({
+        sessionID: sessionId,
+        directory: currentProject.worktree,
+    });
+    if (error || !session) {
+        throw error || new Error("Failed to get session details");
+    }
+    logger.info(`[Bot] Session selected: id=${session.id}, title="${session.title}", project=${currentProject.worktree}, source=${options.source}`);
+    const sessionInfo = {
+        id: session.id,
+        title: session.title,
+        directory: currentProject.worktree,
+    };
+    setCurrentSession(sessionInfo);
+    clearAllInteractionState("session_switched");
+    await ctx.answerCallbackQuery();
+    let loadingMessageId = null;
+    if (ctx.chat) {
+        try {
+            const loadingMessage = await ctx.api.sendMessage(ctx.chat.id, t("sessions.loading_context"));
+            loadingMessageId = loadingMessage.message_id;
+        }
+        catch (err) {
+            logger.error("[Sessions] Failed to send loading message:", err);
+        }
+    }
+    try {
+        await attachToSession({
+            bot: deps.bot,
+            chatId: ctx.chat.id,
+            session: sessionInfo,
+            ensureEventSubscription: deps.ensureEventSubscription,
+        });
+    }
+    catch (err) {
+        if (loadingMessageId) {
+            try {
+                await ctx.api.deleteMessage(ctx.chat.id, loadingMessageId);
+            }
+            catch (deleteError) {
+                logger.debug("[Sessions] Failed to delete loading message after follow error:", deleteError);
+            }
+        }
+        logger.error("[Sessions] Error following selected session:", err);
+        throw err;
+    }
+    if (ctx.chat) {
+        const chatId = ctx.chat.id;
+        const currentAgent = await resolveProjectAgent();
+        keyboardManager.updateAgent(currentAgent);
+        const contextInfo = keyboardManager.getContextInfo();
+        if (contextInfo) {
+            keyboardManager.updateContext(contextInfo.tokensUsed, contextInfo.tokensLimit);
+        }
+        if (loadingMessageId) {
+            try {
+                await ctx.api.deleteMessage(chatId, loadingMessageId);
+            }
+            catch (err) {
+                logger.debug("[Sessions] Failed to delete loading message:", err);
+            }
+        }
+        const keyboard = keyboardManager.getKeyboard();
+        try {
+            await ctx.api.sendMessage(chatId, t("sessions.selected", { title: session.title }), {
+                reply_markup: keyboard,
+            });
+        }
+        catch (err) {
+            logger.error("[Sessions] Failed to send selection message:", err);
+        }
+        if (options.postSelectAction === "preview") {
+            safeBackgroundTask({
+                taskName: "sessions.sendPreview",
+                task: () => sendSessionPreview(ctx.api, chatId, null, session.title, session.id, currentProject.worktree),
+            });
+        }
+        if (options.postSelectAction === "latest_assistant_response") {
+            safeBackgroundTask({
+                taskName: "sessions.sendLatestAssistantResponse",
+                task: () => sendLatestAssistantResponse(ctx.api, chatId, session.id, currentProject.worktree),
+            });
+        }
+    }
+    if (options.removeCallbackReplyMarkup) {
+        await removeCallbackReplyMarkup(ctx);
+    }
+    if (options.deleteCallbackMessage) {
+        await ctx.deleteMessage();
+    }
+}
+function shouldBlockBackgroundSessionOpen() {
+    const activeInteraction = interactionManager.getSnapshot();
+    return activeInteraction !== null && activeInteraction.kind !== "inline";
+}
+export async function handleBackgroundSessionOpen(ctx, deps) {
+    const data = ctx.callbackQuery?.data;
+    if (!data) {
+        return false;
+    }
+    const payload = parseBackgroundSessionCallback(data);
+    if (!payload) {
+        return false;
+    }
+    if (isForegroundBusy()) {
+        await replyBusyBlocked(ctx);
+        return true;
+    }
+    if (shouldBlockBackgroundSessionOpen()) {
+        await ctx.answerCallbackQuery({ text: t("interaction.blocked.finish_current") }).catch(() => { });
+        return true;
+    }
+    try {
+        await selectSessionById(ctx, deps, payload.sessionId, {
+            source: "background_notification",
+            deleteCallbackMessage: false,
+            removeCallbackReplyMarkup: true,
+            postSelectAction: payload.kind === "assistant_response" ? "latest_assistant_response" : "none",
+        });
+    }
+    catch (error) {
+        logger.error("[Sessions] Error selecting background session:", error);
+        await ctx.answerCallbackQuery({ text: t("sessions.select_error"), show_alert: true }).catch(() => { });
+    }
+    return true;
+}
 export async function handleSessionSelect(ctx, deps) {
     const callbackQuery = ctx.callbackQuery;
     if (!callbackQuery?.data || !callbackQuery.data.startsWith(SESSION_CALLBACK_PREFIX)) {
@@ -167,86 +344,12 @@ export async function handleSessionSelect(ctx, deps) {
             await ctx.answerCallbackQuery({ text: t("callback.processing_error") });
             return true;
         }
-        const { data: session, error } = await opencodeClient.session.get({
-            sessionID: sessionId,
-            directory: currentProject.worktree,
+        await selectSessionById(ctx, deps, sessionId, {
+            source: "menu",
+            deleteCallbackMessage: true,
+            removeCallbackReplyMarkup: false,
+            postSelectAction: "preview",
         });
-        if (error || !session) {
-            throw error || new Error("Failed to get session details");
-        }
-        logger.info(`[Bot] Session selected: id=${session.id}, title="${session.title}", project=${currentProject.worktree}`);
-        const sessionInfo = {
-            id: session.id,
-            title: session.title,
-            directory: currentProject.worktree,
-        };
-        setCurrentSession(sessionInfo);
-        clearAllInteractionState("session_switched");
-        await ctx.answerCallbackQuery();
-        let loadingMessageId = null;
-        if (ctx.chat) {
-            try {
-                const loadingMessage = await ctx.api.sendMessage(ctx.chat.id, t("sessions.loading_context"));
-                loadingMessageId = loadingMessage.message_id;
-            }
-            catch (err) {
-                logger.error("[Sessions] Failed to send loading message:", err);
-            }
-        }
-        try {
-            await attachToSession({
-                bot: deps.bot,
-                chatId: ctx.chat.id,
-                session: sessionInfo,
-                ensureEventSubscription: deps.ensureEventSubscription,
-            });
-        }
-        catch (err) {
-            if (loadingMessageId) {
-                try {
-                    await ctx.api.deleteMessage(ctx.chat.id, loadingMessageId);
-                }
-                catch (deleteError) {
-                    logger.debug("[Sessions] Failed to delete loading message after follow error:", deleteError);
-                }
-            }
-            logger.error("[Sessions] Error following selected session:", err);
-            throw err;
-        }
-        if (ctx.chat) {
-            const chatId = ctx.chat.id;
-            const currentAgent = await resolveProjectAgent();
-            keyboardManager.updateAgent(currentAgent);
-            const contextInfo = keyboardManager.getContextInfo();
-            if (contextInfo) {
-                keyboardManager.updateContext(contextInfo.tokensUsed, contextInfo.tokensLimit);
-            }
-            // Delete loading message
-            if (loadingMessageId) {
-                try {
-                    await ctx.api.deleteMessage(chatId, loadingMessageId);
-                }
-                catch (err) {
-                    logger.debug("[Sessions] Failed to delete loading message:", err);
-                }
-            }
-            // Send session selection confirmation with updated keyboard
-            const keyboard = keyboardManager.getKeyboard();
-            try {
-                await ctx.api.sendMessage(chatId, t("sessions.selected", { title: session.title }), {
-                    reply_markup: keyboard,
-                });
-            }
-            catch (err) {
-                logger.error("[Sessions] Failed to send selection message:", err);
-            }
-            // Send preview asynchronously
-            safeBackgroundTask({
-                taskName: "sessions.sendPreview",
-                task: () => sendSessionPreview(ctx.api, chatId, null, session.title, session.id, currentProject.worktree),
-            });
-        }
-        await ctx.deleteMessage();
     }
     catch (error) {
         clearAllInteractionState("session_select_error");
@@ -257,17 +360,19 @@ export async function handleSessionSelect(ctx, deps) {
     return true;
 }
 const PREVIEW_MESSAGES_LIMIT = 6;
+const LATEST_ASSISTANT_RESPONSE_MESSAGES_LIMIT = 20;
 const PREVIEW_ITEM_MAX_LENGTH = 420;
 const TELEGRAM_MESSAGE_LIMIT = 4096;
-function extractTextParts(parts) {
+function extractTextParts(parts, options = {}) {
     const textParts = parts
         .filter((part) => part.type === "text" && typeof part.text === "string")
         .map((part) => part.text);
     if (textParts.length === 0) {
         return null;
     }
-    const text = textParts.join("").trim();
-    return text.length > 0 ? text : null;
+    const text = textParts.join("");
+    const normalizedText = options.trim === false ? text : text.trim();
+    return normalizedText.trim().length > 0 ? normalizedText : null;
 }
 function truncateText(text, maxLength) {
     if (text.length <= maxLength) {
@@ -351,3 +456,49 @@ async function sendSessionPreview(api, chatId, messageId, sessionTitle, sessionI
         logger.error("[Sessions] Failed to send session preview message:", err);
     }
 }
+async function loadLatestAssistantResponse(sessionId, directory) {
+    try {
+        const { data: messages, error } = await opencodeClient.session.messages({
+            sessionID: sessionId,
+            directory,
+            limit: LATEST_ASSISTANT_RESPONSE_MESSAGES_LIMIT,
+        });
+        if (error || !messages) {
+            logger.warn("[Sessions] Failed to fetch latest assistant response:", error);
+            return null;
+        }
+        const latestResponse = messages.reduce((latest, message) => {
+            if (message.info.role !== "assistant" || message.info.summary) {
+                return latest;
+            }
+            const text = extractTextParts(message.parts, { trim: false });
+            if (!text) {
+                return latest;
+            }
+            const created = message.info.time?.created ?? 0;
+            if (!latest || created >= latest.created) {
+                return { text, created };
+            }
+            return latest;
+        }, null);
+        return latestResponse?.text ?? null;
+    }
+    catch (err) {
+        logger.error("[Sessions] Error loading latest assistant response:", err);
+        return null;
+    }
+}
+async function sendLatestAssistantResponse(api, chatId, sessionId, directory) {
+    const responseText = await loadLatestAssistantResponse(sessionId, directory);
+    if (!responseText) {
+        return;
+    }
+    const parts = renderAssistantFinalPartsSafe(responseText, TELEGRAM_MESSAGE_LIMIT);
+    for (const part of parts) {
+        await sendRenderedBotPart({
+            api,
+            chatId,
+            part,
+        });
+    }
+}

package/dist/bot/commands/worktree.js

@@ -122,7 +122,7 @@ export async function worktreeCommand(ctx) {
         await ctx.reply(t("worktree.fetch_error"));
     }
 }
-export async function handleWorktreeCallback(ctx) {
+export async function handleWorktreeCallback(ctx, deps = {}) {
     const callbackQuery = ctx.callbackQuery;
     if (!callbackQuery?.data || !callbackQuery.data.startsWith(WORKTREE_CALLBACK_PREFIX)) {
         return false;
@@ -178,7 +178,12 @@ export async function handleWorktreeCallback(ctx) {
         logger.info(`[Bot] Worktree selected: ${selectedWorktree.path}`);
         await upsertSessionDirectory(selectedWorktree.path, Date.now());
         const projectInfo = await getProjectByWorktree(selectedWorktree.path);
-        const replyKeyboard = await switchToProject(ctx, { ...projectInfo, name: selectedWorktree.path }, "worktree_switched");
+        const selectedProjectInfo = { ...projectInfo, name: selectedWorktree.path };
+        const replyKeyboard = deps.ensureEventSubscription
+            ? await switchToProject(ctx, selectedProjectInfo, "worktree_switched", {
+                ensureEventSubscription: deps.ensureEventSubscription,
+            })
+            : await switchToProject(ctx, selectedProjectInfo, "worktree_switched");
         await ctx.answerCallbackQuery();
         await ctx.reply(t("worktree.selected", { worktree: selectedWorktree.path }), {
             reply_markup: replyKeyboard,

package/dist/bot/handlers/inline-menu.js

@@ -11,6 +11,7 @@ const INLINE_MENU_KINDS = [
     "variant",
     "context",
     "open",
+    "ls",
     "worktree",
 ];
 function isInlineMenuKind(value) {

package/dist/bot/handlers/prompt.js

@@ -198,7 +198,7 @@ export async function processUserPrompt(ctx, text, deps, fileParts = [], options
             fileCount: fileParts.length,
         };
         logger.info(`[Bot] Calling session.promptAsync (start-only) with agent=${currentAgent}, fileCount=${fileParts.length}...`);
-        foregroundSessionState.markBusy(currentSession.id);
+        foregroundSessionState.markBusy(currentSession.id, currentSession.directory);
         await markAttachedSessionBusy(currentSession.id);
         assistantRunState.startRun(currentSession.id, {
             startedAt: Date.now(),

package/dist/bot/index.js

@@ -13,12 +13,14 @@ import { startCommand } from "./commands/start.js";
 import { helpCommand } from "./commands/help.js";
 import { statusCommand } from "./commands/status.js";
 import { AGENT_MODE_BUTTON_TEXT_PATTERN, MODEL_BUTTON_TEXT_PATTERN, VARIANT_BUTTON_TEXT_PATTERN, } from "./message-patterns.js";
-import { sessionsCommand, handleSessionSelect } from "./commands/sessions.js";
+import { buildBackgroundSessionOpenKeyboard, handleBackgroundSessionOpen, handleSessionSelect, sessionsCommand, } from "./commands/sessions.js";
 import { newCommand } from "./commands/new.js";
 import { projectsCommand, handleProjectSelect } from "./commands/projects.js";
 import { worktreeCommand, handleWorktreeCallback } from "./commands/worktree.js";
 import { openCommand, handleOpenCallback, clearOpenPathIndex } from "./commands/open.js";
+import { clearLsPathIndex, handleLsCallback, lsCommand } from "./commands/ls.js";
 import { abortCommand } from "./commands/abort.js";
+import { detachCommand } from "./commands/detach.js";
 import { opencodeStartCommand } from "./commands/opencode-start.js";
 import { opencodeStopCommand } from "./commands/opencode-stop.js";
 import { renameCommand, handleRenameCancel, handleRenameTextAnswer } from "./commands/rename.js";
@@ -52,10 +54,12 @@ import { safeBackgroundTask } from "../utils/safe-background-task.js";
 import { withTelegramRateLimitRetry } from "../utils/telegram-rate-limit-retry.js";
 import { pinnedMessageManager } from "../pinned/manager.js";
 import { t } from "../i18n/index.js";
+import { getCurrentProject } from "../settings/manager.js";
 import { clearPromptResponseMode, processUserPrompt } from "./handlers/prompt.js";
 import { handleVoiceMessage } from "./handlers/voice.js";
 import { handleDocumentMessage } from "./handlers/document.js";
 import { downloadTelegramFile, toDataUri } from "./utils/file-download.js";
+import { reconcileBusyState } from "./utils/busy-reconciliation.js";
 import { finalizeAssistantResponse } from "./utils/finalize-assistant-response.js";
 import { sendTtsResponseForSession } from "./utils/send-tts-response.js";
 import { deliverThinkingMessage } from "./utils/thinking-message.js";
@@ -73,6 +77,7 @@ import { markAttachedSessionBusy, markAttachedSessionIdle, restoreAttachedCurren
 import { externalUserInputSuppressionManager } from "../external-input/suppression.js";
 import { prepareAssistantFinalStreamingPayload, prepareAssistantStreamingPayload, renderAssistantFinalPartsSafe, } from "./utils/assistant-rendering.js";
 import { deliverExternalUserInputNotification } from "./utils/external-user-input.js";
+import { backgroundSessionTracker, } from "../background-session/tracker.js";
 let botInstance = null;
 let chatIdInstance = null;
 let commandsInitialized = false;
@@ -270,6 +275,35 @@ function getToolStreamKey(tool) {
     }
     return "default";
 }
+function formatShortSessionId(sessionId) {
+    return sessionId.length <= 8 ? sessionId : sessionId.slice(0, 8);
+}
+function getBackgroundSessionLabel(notification) {
+    const title = notification.sessionTitle?.trim();
+    if (title) {
+        return title;
+    }
+    return t("background.session_fallback", { id: formatShortSessionId(notification.sessionId) });
+}
+function formatBackgroundSessionNotification(notification) {
+    const session = getBackgroundSessionLabel(notification);
+    switch (notification.kind) {
+        case "assistant_response":
+            return t("background.assistant_response", { session });
+        case "question_asked":
+            return t("background.question_asked", { session });
+        case "permission_asked":
+            return t("background.permission_asked", { session });
+    }
+}
+async function deliverBackgroundSessionNotification(notification) {
+    if (!botInstance || !chatIdInstance) {
+        return;
+    }
+    await botInstance.api.sendMessage(chatIdInstance, formatBackgroundSessionNotification(notification), {
+        reply_markup: buildBackgroundSessionOpenKeyboard(notification.sessionId, notification.kind),
+    });
+}
 function getEventSessionId(event) {
     const properties = event.properties;
     return properties.sessionID || properties.info?.sessionID || properties.part?.sessionID || null;
@@ -279,7 +313,8 @@ function shouldMarkAttachedBusyFromEvent(event) {
         case "session.status":
             return event.properties.status?.type === "busy";
         case "message.updated": {
-            const info = event.properties.info;
+            const info = event.properties
+                .info;
             return info?.role === "assistant" && !info.time?.completed;
         }
         case "message.part.updated":
@@ -322,6 +357,11 @@ async function ensureEventSubscription(directory) {
         return;
     }
     summaryAggregator.setTypingIndicatorEnabled(true);
+    backgroundSessionTracker.setDirectory(directory);
+    backgroundSessionTracker.setOnNotification(deliverBackgroundSessionNotification);
+    if (!config.bot.trackBackgroundSessions) {
+        backgroundSessionTracker.clear();
+    }
     summaryAggregator.setOnCleared(() => {
         toolMessageBatcher.clearAll("summary_aggregator_clear");
         toolCallStreamer.clearAll("summary_aggregator_clear");
@@ -761,9 +801,14 @@ async function ensureEventSubscription(directory) {
     });
     logger.info(`[Bot] Subscribing to OpenCode events for project: ${directory}`);
     subscribeToEvents(directory, (event) => {
+        if (event.type === "server.heartbeat") {
+            void reconcileBusyState(directory);
+        }
         const attached = attachManager.getSnapshot();
         const eventSessionId = getEventSessionId(event);
-        if (attached && eventSessionId === attached.sessionId && shouldMarkAttachedBusyFromEvent(event)) {
+        if (attached &&
+            eventSessionId === attached.sessionId &&
+            shouldMarkAttachedBusyFromEvent(event)) {
             void markAttachedSessionBusy(attached.sessionId);
         }
         if (event.type === "session.created" || event.type === "session.updated") {
@@ -775,6 +820,9 @@ async function ensureEventSubscription(directory) {
                 });
             }
         }
+        if (config.bot.trackBackgroundSessions) {
+            backgroundSessionTracker.processEvent(event, getCurrentSession()?.id ?? null);
+        }
         summaryAggregator.processEvent(event);
     }).catch((err) => {
         logger.error("Failed to subscribe to events:", err);
@@ -785,6 +833,7 @@ export function createBot() {
     sessionCompletionTasks.clear();
     attachManager.clear("bot_startup");
     assistantRunState.clearAll("bot_startup");
+    backgroundSessionTracker.clear();
     if (heartbeatTimer) {
         clearInterval(heartbeatTimer);
         heartbeatTimer = null;
@@ -821,6 +870,12 @@ export function createBot() {
         });
         if (restored) {
             logger.info(`[Bot] Restored followed session after OpenCode ready: reason=${reason}`);
+            return;
+        }
+        const currentProject = getCurrentProject();
+        if (config.bot.trackBackgroundSessions && currentProject?.worktree) {
+            await ensureEventSubscription(currentProject.worktree);
+            logger.info(`[Bot] Started background session tracking after OpenCode ready: reason=${reason}, directory=${currentProject.worktree}`);
         }
     });
     // Heartbeat for diagnostics: verify the event loop is not blocked
@@ -880,9 +935,11 @@ export function createBot() {
     bot.command("projects", projectsCommand);
     bot.command("worktree", worktreeCommand);
     bot.command("open", openCommand);
+    bot.command("ls", lsCommand);
     bot.command("sessions", sessionsCommand);
     bot.command("new", (ctx) => newCommand(ctx, { bot, ensureEventSubscription }));
     bot.command("abort", abortCommand);
+    bot.command("detach", detachCommand);
     bot.command("task", taskCommand);
     bot.command("tasklist", taskListCommand);
     bot.command("rename", renameCommand);
@@ -898,15 +955,21 @@ export function createBot() {
             chatIdInstance = ctx.chat.id;
         }
         try {
+            const handledBackgroundSession = await handleBackgroundSessionOpen(ctx, {
+                bot,
+                ensureEventSubscription,
+            });
             const handledInlineCancel = await handleInlineMenuCancel(ctx);
             if (handledInlineCancel) {
                 // Clean up path index when the open-directory menu is cancelled
                 clearOpenPathIndex();
+                clearLsPathIndex();
             }
             const handledSession = await handleSessionSelect(ctx, { bot, ensureEventSubscription });
-            const handledProject = await handleProjectSelect(ctx);
-            const handledWorktree = await handleWorktreeCallback(ctx);
-            const handledOpen = await handleOpenCallback(ctx);
+            const handledProject = await handleProjectSelect(ctx, { ensureEventSubscription });
+            const handledWorktree = await handleWorktreeCallback(ctx, { ensureEventSubscription });
+            const handledOpen = await handleOpenCallback(ctx, { ensureEventSubscription });
+            const handledLs = await handleLsCallback(ctx);
             const handledQuestion = await handleQuestionCallback(ctx);
             const handledPermission = await handlePermissionCallback(ctx);
             const handledAgent = await handleAgentSelect(ctx);
@@ -919,12 +982,14 @@ export function createBot() {
             const handledCommands = await handleCommandsCallback(ctx, { bot, ensureEventSubscription });
             const handledSkills = await handleSkillsCallback(ctx, { bot, ensureEventSubscription });
             const handledMcps = await handleMcpsCallback(ctx);
-            logger.debug(`[Bot] Callback handled: inlineCancel=${handledInlineCancel}, session=${handledSession}, project=${handledProject}, worktree=${handledWorktree}, open=${handledOpen}, question=${handledQuestion}, permission=${handledPermission}, agent=${handledAgent}, model=${handledModel}, variant=${handledVariant}, compactConfirm=${handledCompactConfirm}, task=${handledTask}, taskList=${handledTaskList}, rename=${handledRenameCancel}, commands=${handledCommands}, skills=${handledSkills}, mcps=${handledMcps}`);
-            if (!handledInlineCancel &&
+            logger.debug(`[Bot] Callback handled: backgroundSession=${handledBackgroundSession}, inlineCancel=${handledInlineCancel}, session=${handledSession}, project=${handledProject}, worktree=${handledWorktree}, open=${handledOpen}, ls=${handledLs}, question=${handledQuestion}, permission=${handledPermission}, agent=${handledAgent}, model=${handledModel}, variant=${handledVariant}, compactConfirm=${handledCompactConfirm}, task=${handledTask}, taskList=${handledTaskList}, rename=${handledRenameCancel}, commands=${handledCommands}, skills=${handledSkills}, mcps=${handledMcps}`);
+            if (!handledBackgroundSession &&
+                !handledInlineCancel &&
                 !handledSession &&
                 !handledProject &&
                 !handledWorktree &&
                 !handledOpen &&
+                !handledLs &&
                 !handledQuestion &&
                 !handledPermission &&
                 !handledAgent &&
@@ -1156,6 +1221,7 @@ export function cleanupBotRuntime(reason) {
     unsubscribeReadyRestore = null;
     stopEventListening();
     summaryAggregator.clear();
+    backgroundSessionTracker.clear();
     responseStreamer.clearAll(reason);
     toolCallStreamer.clearAll(reason);
     toolMessageBatcher.clearAll(reason);