@link-assistant/hive-mind 1.56.19 → 1.57.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @link-assistant/hive-mind
 
+## 1.57.1
+
+### Patch Changes
+
+- e4ece4d: Treat Codex app-server stream-lag item errors as non-fatal warnings when the turn otherwise completes successfully, preventing successful Codex runs from being reported as failed solution drafts.
+
+## 1.57.0
+
+### Minor Changes
+
+- 272a2d4: Add live terminal watch support for hive-telegram-bot
+
+  This feature adds `/terminal_watch` plus the experimental `--auto-start-screen-watch-message` option. The command watches the log reported by `$ --status <uuid>` and updates a separate Telegram message with a terminal-sized text snapshot.
+
+  Key features:
+  - Manual `/terminal_watch <uuid>` command, including reply-based usage
+  - Configurable terminal snapshot size with `--size`, `--width`, and `--height`
+  - Auto-freezes the watch message and attaches the full log when the session ends
+  - Public repository logs can update in chat; private/unknown visibility uses DM for manual watches
+  - Auto-start remains off by default and never starts for private or unknown-visibility repositories
+
+  Based on the proof-of-concept from konard/telegram-terminal-bot.
+
 ## 1.56.19
 
 ### Patch Changes

package/README.hi.md

@@ -431,9 +431,21 @@ Hive Mind को क्रिया में देखना चाहते
    hive-telegram-bot 2>&1 | tee -a "logs/bot-$(date +%Y%m%d-%H%M%S).log"
    ```
 
+   **Experimental: live terminal watch**
+
+   ```bash
+   hive-telegram-bot --auto-start-screen-watch-message
+   ```
+
+   यह opt-in flag सार्वजनिक `/solve` sessions के लिए एक अलग live terminal
+   message शुरू करता है। Private या unknown-visibility repositories के लिए watch
+   message अपने आप शुरू नहीं होता।
+
 ### बॉट कमांड
 
-सभी कमांड केवल **ग्रुप चैट में** काम करते हैं (बॉट के साथ निजी संदेशों में नहीं):
+अधिकांश operational commands केवल **ग्रुप चैट में** काम करते हैं (बॉट के साथ
+निजी संदेशों में नहीं)। `/terminal_watch` जैसे commands, जो जानबूझकर private
+updates भेजते हैं, direct messages में भी उपयोग किए जा सकते हैं:
 
 #### `/solve` - GitHub इश्यू हल करें
 
@@ -494,6 +506,22 @@ Shows:
 - Claude usage limits (session and weekly)
 ```
 
+#### `/terminal_watch` - Live Session Log
+
+```
+/terminal_watch <uuid> [--size 120x25]
+
+Examples:
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12 --width 100 --height 20
+```
+
+आप bot session message पर `/terminal_watch` के साथ reply भी कर सकते हैं। यह
+command `$ --status <uuid>` द्वारा report किए गए session log की latest lines के
+साथ एक अलग Telegram message update करता है और session खत्म होने पर पूरी log file
+attach करता है। Public repository logs chat में watch किए जा सकते हैं; private या
+unknown-visibility repository logs केवल direct message से भेजे जाते हैं।
+
 #### `/help` - सहायता और डायग्नोस्टिक जानकारी प्राप्त करें
 
 ```
@@ -508,12 +536,25 @@ Shows:
 
 ### विशेषताएँ
 
-- ✅ **केवल ग्रुप चैट**: कमांड केवल ग्रुप चैट में काम करते हैं (निजी संदेश नहीं)
+- ✅ **Group Chat Execution**: `/solve` और `/hive` workflows authorized group chats से चलते हैं
 - ✅ **पूर्ण विकल्प सपोर्ट**: सभी कमांड-लाइन विकल्प Telegram में काम करते हैं
 - ✅ **Screen सत्र**: कमांड डिटैच्ड screen सत्रों में चलते हैं
+- ✅ **Live Terminal Watch**: `/terminal_watch` और opt-in auto-start live session logs दिखाते हैं
 - ✅ **चैट प्रतिबंध**: अनुमत चैट ID की वैकल्पिक सफेद सूची
 - ✅ **डायग्नोस्टिक टूल**: चैट ID और कॉन्फ़िगरेशन जानकारी प्राप्त करें
 
+#### Live Terminal Watch
+
+`--auto-start-screen-watch-message` से enabled होने पर, bot public `/solve`
+sessions के लिए अपने आप एक अलग live terminal watch message शुरू करता है:
+
+- **Manual Watch**: `/terminal_watch <uuid>` या `/terminal_watch` के साथ reply
+- **Real-time Updates**: Commands execute होते समय live session log output देखें
+- **Auto-freeze**: Command पूरा होने पर message freeze हो जाता है
+- **Log Attachment**: Session खत्म होने पर full logs अपने आप attach होते हैं
+- **Security**: Private या unknown-visibility repositories के लिए auto-start disabled है
+- **Smart Updates**: केवल वास्तविक बदलाव मिलने पर update करता है (API limits से बचने के लिए rate-limited)
+
 ### सुरक्षा नोट
 
 - केवल उन ग्रुप चैट में काम करता है जहाँ बॉट एडमिन है

package/README.md

@@ -440,9 +440,19 @@ Want to see the Hive Mind in action? Request a free demo or get faster support b
    hive-telegram-bot 2>&1 | tee -a "logs/bot-$(date +%Y%m%d-%H%M%S).log"
    ```
 
+   **Experimental: live terminal watch**
+
+   ```bash
+   hive-telegram-bot --auto-start-screen-watch-message
+   ```
+
+   This opt-in flag starts a separate live terminal message for public `/solve`
+   sessions. Private or unknown-visibility repositories never auto-start a
+   watch message.
+
 ### Bot Commands
 
-All commands work in **group chats only** (not in private messages with the bot):
+Most operational commands work in **group chats only** (not in private messages with the bot). Commands that intentionally deliver private updates, such as `/terminal_watch`, may also be used in direct messages:
 
 #### `/solve` - Solve GitHub Issues
 
@@ -514,6 +524,22 @@ Shows:
 - Claude usage limits (session and weekly)
 ```
 
+#### `/terminal_watch` - Live Session Log
+
+```
+/terminal_watch <uuid> [--size 120x25]
+
+Examples:
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12 --width 100 --height 20
+```
+
+You can also reply to a bot session message with `/terminal_watch`. The command
+updates a separate Telegram message with the latest lines from the session log
+reported by `$ --status <uuid>` and attaches the full log file when the session
+finishes. Public repository logs can be watched in the chat; private or
+unknown-visibility repository logs are delivered by direct message only.
+
 #### `/help` - Get Help and Diagnostic Info
 
 ```
@@ -528,12 +554,24 @@ Shows:
 
 ### Features
 
-- ✅ **Group Chat Only**: Commands work only in group chats (not private messages)
+- ✅ **Group Chat Execution**: `/solve` and `/hive` workflows run from authorized group chats
 - ✅ **Full Options Support**: All command-line options work in Telegram
 - ✅ **Screen Sessions**: Commands run in detached screen sessions
+- ✅ **Live Terminal Watch**: `/terminal_watch` and opt-in auto-start show live session logs
 - ✅ **Chat Restrictions**: Optional whitelist of allowed chat IDs
 - ✅ **Diagnostic Tools**: Get chat ID and configuration info
 
+#### Live Terminal Watch
+
+When enabled with `--auto-start-screen-watch-message`, the bot automatically starts a separate live terminal watch message for public `/solve` sessions:
+
+- **Manual Watch**: `/terminal_watch <uuid>` or reply with `/terminal_watch`
+- **Real-time Updates**: See live session log output as commands execute
+- **Auto-freeze**: Message freezes when command completes
+- **Log Attachment**: Full logs attached automatically when session ends
+- **Security**: Auto-start is disabled for private or unknown-visibility repositories
+- **Smart Updates**: Only updates when actual changes detected (rate-limited to avoid API limits)
+
 ### Security Notes
 
 - Only works in group chats where the bot is admin

package/README.ru.md

@@ -431,9 +431,22 @@ Hive Mind включает интерфейс Telegram-бота (SwarmMindBot)
    hive-telegram-bot 2>&1 | tee -a "logs/bot-$(date +%Y%m%d-%H%M%S).log"
    ```
 
+   **Экспериментально: live terminal watch**
+
+   ```bash
+   hive-telegram-bot --auto-start-screen-watch-message
+   ```
+
+   Этот opt-in флаг запускает отдельное live terminal сообщение для публичных
+   сессий `/solve`. Для приватных репозиториев или репозиториев с неизвестной
+   видимостью watch-сообщение автоматически не запускается.
+
 ### Команды бота
 
-Все команды работают **только в групповых чатах** (не в личных сообщениях боту):
+Большинство операционных команд работают **только в групповых чатах** (не в
+личных сообщениях боту). Команды, которые намеренно доставляют приватные
+обновления, например `/terminal_watch`, также можно использовать в личных
+сообщениях:
 
 #### `/solve` — Решение задач GitHub
 
@@ -494,6 +507,23 @@ Shows:
 - Claude usage limits (session and weekly)
 ```
 
+#### `/terminal_watch` — Live Session Log
+
+```
+/terminal_watch <uuid> [--size 120x25]
+
+Examples:
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12 --width 100 --height 20
+```
+
+Также можно ответить на сообщение сессии бота командой `/terminal_watch`. Команда
+обновляет отдельное сообщение Telegram последними строками лога сессии,
+полученного через `$ --status <uuid>`, и прикрепляет полный файл лога после
+завершения сессии. Логи публичных репозиториев можно смотреть в чате; логи
+приватных репозиториев или репозиториев с неизвестной видимостью доставляются
+только личным сообщением.
+
 #### `/help` — Получить справку и диагностическую информацию
 
 ```
@@ -508,12 +538,25 @@ Shows:
 
 ### Возможности
 
-- ✅ **Только групповые чаты**: команды работают исключительно в групповых чатах (не в личных сообщениях)
+- ✅ **Запуск из групповых чатов**: workflows `/solve` и `/hive` запускаются из авторизованных групповых чатов
 - ✅ **Полная поддержка параметров**: все параметры командной строки работают в Telegram
 - ✅ **Screen-сессии**: команды запускаются в отсоединённых screen-сессиях
+- ✅ **Live Terminal Watch**: `/terminal_watch` и opt-in auto-start показывают live session logs
 - ✅ **Ограничения по чатам**: опциональный белый список разрешённых ID чатов
 - ✅ **Диагностические инструменты**: получение ID чата и информации о конфигурации
 
+#### Live Terminal Watch
+
+Если включить `--auto-start-screen-watch-message`, бот автоматически запускает
+отдельное live terminal watch сообщение для публичных сессий `/solve`:
+
+- **Manual Watch**: `/terminal_watch <uuid>` или ответ командой `/terminal_watch`
+- **Real-time Updates**: смотрите live session log output во время выполнения команд
+- **Auto-freeze**: сообщение замораживается после завершения команды
+- **Log Attachment**: полные логи автоматически прикрепляются после завершения сессии
+- **Security**: auto-start отключён для приватных репозиториев и репозиториев с неизвестной видимостью
+- **Smart Updates**: обновляет сообщение только при реальных изменениях (rate-limited для защиты от API limits)
+
 ### Замечания по безопасности
 
 - Работает только в групповых чатах, где бот является администратором

package/README.zh.md

@@ -431,9 +431,18 @@ Hive Mind 内置 Telegram 机器人接口（SwarmMindBot），支持远程命令
    hive-telegram-bot 2>&1 | tee -a "logs/bot-$(date +%Y%m%d-%H%M%S).log"
    ```
 
+   **实验性：live terminal watch**
+
+   ```bash
+   hive-telegram-bot --auto-start-screen-watch-message
+   ```
+
+   这个 opt-in 标志会为公开仓库的 `/solve` 会话启动一条单独的 live terminal
+   消息。私有仓库或可见性未知的仓库不会自动启动 watch 消息。
+
 ### 机器人命令
 
-所有命令仅在**群聊中**有效（不支持与机器人的私聊）：
+大多数操作类命令仅在**群聊中**有效（不支持与机器人的私聊）。有意发送私密更新的命令（例如 `/terminal_watch`）也可以在私聊中使用：
 
 #### `/solve` - 解决 GitHub Issue
 
@@ -494,6 +503,21 @@ Shows:
 - Claude usage limits (session and weekly)
 ```
 
+#### `/terminal_watch` - Live Session Log
+
+```
+/terminal_watch <uuid> [--size 120x25]
+
+Examples:
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12
+/terminal_watch 4d934f71-4cdb-4b8c-b474-582116d12c12 --width 100 --height 20
+```
+
+您也可以回复机器人会话消息并发送 `/terminal_watch`。该命令会用
+`$ --status <uuid>` 报告的会话日志最新内容更新一条单独的 Telegram
+消息，并在会话结束时附加完整日志文件。公开仓库日志可以在群聊中 watch；
+私有仓库或可见性未知仓库的日志只会通过私聊发送。
+
 #### `/help` - 获取帮助和诊断信息
 
 ```
@@ -508,12 +532,25 @@ Shows:
 
 ### 功能特性
 
-- ✅ **仅限群聊**：命令仅在群聊中有效（不支持私聊）
+- ✅ **群聊执行**：`/solve` 和 `/hive` workflow 从已授权群聊中运行
 - ✅ **完整选项支持**：所有命令行选项均可在 Telegram 中使用
 - ✅ **Screen 会话**：命令在后台 Screen 会话中运行
+- ✅ **Live Terminal Watch**：`/terminal_watch` 和 opt-in auto-start 显示 live session logs
 - ✅ **聊天限制**：可选配置允许的聊天 ID 白名单
 - ✅ **诊断工具**：获取聊天 ID 和配置信息
 
+#### Live Terminal Watch
+
+启用 `--auto-start-screen-watch-message` 后，机器人会为公开仓库的 `/solve`
+会话自动启动一条单独的 live terminal watch 消息：
+
+- **Manual Watch**：`/terminal_watch <uuid>` 或回复 `/terminal_watch`
+- **Real-time Updates**：在命令执行时查看 live session log output
+- **Auto-freeze**：命令完成时消息会被冻结
+- **Log Attachment**：会话结束时自动附加完整日志
+- **Security**：私有仓库或可见性未知的仓库禁用 auto-start
+- **Smart Updates**：仅在实际内容变化时更新（rate-limited 以避免 API limits）
+
 ### 安全注意事项
 
 - 仅在机器人为管理员的群聊中有效

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.56.19",
+  "version": "1.57.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -15,7 +15,7 @@
     "hive-telegram-bot": "./src/telegram-bot.mjs"
   },
   "scripts": {
-    "test": "node tests/solve-queue.test.mjs && node tests/limits-display.test.mjs && node tests/test-usage-limit.mjs && node tests/test-codex-support.mjs && node tests/test-build-cost-info-string.mjs && node tests/test-claude-code-install-method.mjs && node tests/test-claude-quiet-config.mjs && node tests/test-configure-claude-bin.mjs && node tests/test-docker-release-order.mjs && node tests/test-docker-box-migration.mjs && node tests/test-hive-screens.mjs && node tests/test-issue-1616-pr-issue-link-preservation.mjs && node tests/test-pre-pr-failure-notifier-1640.mjs && node tests/test-ready-to-merge-pagination-1645.mjs && node tests/test-require-gh-paginate-rule.mjs && node tests/test-auto-restart-limits-1664.mjs && node tests/test-log-upload-output-1678.mjs && node tests/test-log-upload-output-1682.mjs && node tests/test-telegram-message-filters.mjs && node tests/test-telegram-bot-command-aliases.mjs && node tests/test-telegram-options-before-url.mjs && node tests/test-telegram-bot-configuration-isolation-links-notation.mjs && node tests/test-extract-isolation-from-args.mjs && node tests/test-solve-queue-command.mjs && node tests/test-queue-display-1267.mjs && node tests/test-issue-1670-screen-status-monitoring.mjs && node tests/test-issue-1680-session-monitoring.mjs && node tests/test-issue-1684-message-formatting.mjs && node tests/test-issue-1686-log-command.mjs && node tests/test-issue-1688-subscribe-and-pr-link.mjs && node tests/test-issue-1694-stabilized-defaults.mjs && node tests/test-telegram-bot-launcher.mjs",
+    "test": "node tests/solve-queue.test.mjs && node tests/limits-display.test.mjs && node tests/test-usage-limit.mjs && node tests/test-codex-support.mjs && node tests/test-build-cost-info-string.mjs && node tests/test-claude-code-install-method.mjs && node tests/test-claude-quiet-config.mjs && node tests/test-configure-claude-bin.mjs && node tests/test-docker-release-order.mjs && node tests/test-docker-box-migration.mjs && node tests/test-hive-screens.mjs && node tests/test-issue-1616-pr-issue-link-preservation.mjs && node tests/test-pre-pr-failure-notifier-1640.mjs && node tests/test-ready-to-merge-pagination-1645.mjs && node tests/test-require-gh-paginate-rule.mjs && node tests/test-auto-restart-limits-1664.mjs && node tests/test-log-upload-output-1678.mjs && node tests/test-log-upload-output-1682.mjs && node tests/test-telegram-message-filters.mjs && node tests/test-telegram-bot-command-aliases.mjs && node tests/test-telegram-options-before-url.mjs && node tests/test-telegram-bot-configuration-isolation-links-notation.mjs && node tests/test-extract-isolation-from-args.mjs && node tests/test-solve-queue-command.mjs && node tests/test-queue-display-1267.mjs && node tests/test-issue-467-terminal-watch.mjs && node tests/test-issue-1670-screen-status-monitoring.mjs && node tests/test-issue-1680-session-monitoring.mjs && node tests/test-issue-1684-message-formatting.mjs && node tests/test-issue-1686-log-command.mjs && node tests/test-issue-1688-subscribe-and-pr-link.mjs && node tests/test-issue-1694-stabilized-defaults.mjs && node tests/test-telegram-bot-launcher.mjs",
     "test:queue": "node tests/solve-queue.test.mjs",
     "test:limits-display": "node tests/limits-display.test.mjs",
     "test:usage-limit": "node tests/test-usage-limit.mjs",

package/src/codex.lib.mjs

@@ -210,12 +210,23 @@ const unwrapCodexErrorMessage = value => {
   return text;
 };
 
+const isNonFatalCodexItemErrorMessage = message => /^in-process app-server event stream lagged; dropped \d+ events?$/i.test(message || '');
+
 export const getCodexErrorEventSummary = codexJsonState => {
   const events = [];
+  const ignoredEvents = [];
   const addEvents = (type, items = []) => {
     for (const item of items) {
       const message = unwrapCodexErrorMessage(item?.message);
-      events.push({ type, message: message || 'Codex emitted an error event' });
+      const event = { type, message: message || 'Codex emitted an error event' };
+      if (type === 'item' && isNonFatalCodexItemErrorMessage(message)) {
+        ignoredEvents.push({
+          ...event,
+          reason: 'Codex app-server backpressure warning; the turn can still complete successfully',
+        });
+        continue;
+      }
+      events.push(event);
     }
   };
 
@@ -223,11 +234,20 @@ export const getCodexErrorEventSummary = codexJsonState => {
   addEvents('turn', codexJsonState?.turnFailures);
   addEvents('stream', codexJsonState?.streamErrors);
 
+  const countByType = items => ({
+    item: items.filter(item => item.type === 'item').length,
+    turn: items.filter(item => item.type === 'turn').length,
+    stream: items.filter(item => item.type === 'stream').length,
+  });
+
   return {
     hasError: events.length > 0,
     message: events[0]?.message || null,
     events,
-    counts: {
+    ignoredEvents,
+    counts: countByType(events),
+    ignoredCounts: countByType(ignoredEvents),
+    observedCounts: {
       item: codexJsonState?.itemErrors?.length || 0,
       turn: codexJsonState?.turnFailures?.length || 0,
       stream: codexJsonState?.streamErrors?.length || 0,
@@ -928,6 +948,10 @@ export const executeCodexCommand = async params => {
       }
 
       const codexErrorSummary = getCodexErrorEventSummary(codexJsonState);
+      if (codexErrorSummary.ignoredEvents.length > 0) {
+        const ignoredMessages = [...new Set(codexErrorSummary.ignoredEvents.map(event => event.message))].join('; ');
+        await log(`⚠️ Ignoring non-fatal Codex item error event(s): ${ignoredMessages}`, { level: 'warning', verbose: true });
+      }
       if (codexErrorSummary.hasError) {
         const limitInfo = detectUsageLimit(codexErrorSummary.message || lastMessage);
         const retryableError = classifyRetryableError(codexErrorSummary.message || lastMessage);

package/src/telegram-bot.mjs

@@ -49,6 +49,8 @@ const { getSolveQueue, createQueueExecuteCallback } = await import('./telegram-s
 const { applySolveToolAlias, getFirstParsedPositionalArg, getSolveCommandNameFromText, getSolveToolAliasFromText, moveArgumentToFront, parseArgsWithYargs, parseCommandArgs, SOLVE_COMMAND_NAMES } = await import('./telegram-solve-command.lib.mjs');
 const { isChatStopped, getChatStopInfo, getStoppedChatRejectMessage, DEFAULT_STOP_REASON } = await import('./telegram-start-stop-command.lib.mjs');
 const { isOldMessage: _isOldMessage, isGroupChat: _isGroupChat, isChatAuthorized: _isChatAuthorized, isForwardedOrReply: _isForwardedOrReply, extractCommandFromText, extractGitHubUrl: _extractGitHubUrl } = await import('./telegram-message-filters.lib.mjs');
+const { safeReply } = await import('./telegram-safe-reply.lib.mjs');
+const { registerTerminalWatchCommand, startAutoTerminalWatchForSession } = await import('./telegram-terminal-watch-command.lib.mjs');
 const { launchBotWithRetry } = await import('./telegram-bot-launcher.lib.mjs');
 const { trackSession, startSessionMonitoring, hasActiveSessionForUrlAsync } = await import('./session-monitor.lib.mjs');
 const { formatExecutingWorkSessionMessage, formatStartingWorkSessionMessage } = await import('./work-session-formatting.lib.mjs');
@@ -113,6 +115,7 @@ const config = yargs(hideBin(process.argv))
     alias: 'v',
     default: getenv('TELEGRAM_BOT_VERBOSE', 'false') === 'true',
   })
+  .option('autoStartScreenWatchMessage', { type: 'boolean', description: 'Experimental: auto-start separate /terminal_watch messages for public /solve sessions', alias: 'auto-start-screen-watch-message', default: getenv('TELEGRAM_AUTO_START_SCREEN_WATCH_MESSAGE', getenv('TELEGRAM_AUTO_WATCH_MESSAGE', 'false')) === 'true' })
   .option('isolation', { type: 'string', description: "Isolation backend (screen/tmux/docker). Defaults to 'screen' so Telegram-bot work sessions survive bot restarts; pass --isolation '' (or set TELEGRAM_ISOLATION='') to disable.", default: getenv('TELEGRAM_ISOLATION', 'screen') })
   .help('h')
   .alias('h', 'help')
@@ -130,6 +133,7 @@ if (config.configuration) {
 
 const BOT_TOKEN = config.token || getenv('TELEGRAM_BOT_TOKEN', '');
 const VERBOSE = config.verbose || getenv('TELEGRAM_BOT_VERBOSE', 'false') === 'true';
+const AUTO_WATCH_MESSAGE = config.autoStartScreenWatchMessage === true;
 if (!BOT_TOKEN) {
   console.error('Error: TELEGRAM_BOT_TOKEN not set. Use --token or TELEGRAM_BOT_TOKEN env var.');
   process.exit(1);
@@ -532,25 +536,6 @@ async function validateGitHubUrl(args, options = {}) {
   return { valid: true, parsed, normalizedUrl: url };
 }
 
-// Issue #1460/#1497: safeReply - try Markdown first, fall back to plain text on parsing errors
-async function safeReply(ctx, text, options = {}) {
-  try {
-    return await ctx.reply(text, { parse_mode: 'Markdown', ...options });
-  } catch (error) {
-    const isParsingError = error.message && (error.message.includes("can't parse entities") || error.message.includes("Can't parse entities") || error.message.includes("can't find end of") || (error.message.includes('Bad Request') && error.message.includes('400')));
-    if (!isParsingError) throw error;
-    console.error(`[telegram-bot] safeReply: Markdown parsing failed: ${error.message}`);
-    console.error(`[telegram-bot] safeReply: Failing message (${Buffer.byteLength(text, 'utf-8')} bytes): ${text}`);
-    const plainText = text
-      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1 ($2)')
-      .replace(/\\_/g, '_')
-      .replace(/\\\*/g, '*')
-      .replace(/\*([^*]+)\*/g, '$1')
-      .replace(/`([^`]+)`/g, '$1');
-    return await ctx.reply(plainText, { ...options, parse_mode: undefined });
-  }
-}
-
 async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude', urlContext = null) {
   const { chat, message_id: msgId } = startingMessage;
   const safeEdit = async text => {
@@ -562,18 +547,24 @@ async function executeAndUpdateMessage(ctx, startingMessage, commandName, args,
   };
   const requesterUserId = ctx.from?.id ?? null; // Issue #1688: suppress duplicate /subscribe DM
   const iso = await resolveIsolation(perCommandIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE);
-  let result, session;
+  let result, session, sessionInfo;
   if (iso) {
     session = iso.runner.generateSessionId();
     VERBOSE && console.log(`[VERBOSE] Using isolation (${iso.backend}), session: ${session}`);
     result = await iso.runner.executeWithIsolation(commandName, args, { backend: iso.backend, sessionId: session, verbose: VERBOSE });
-    if (result.success) trackSession(session, { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, isolationBackend: iso.backend, sessionId: session, tool, infoBlock, urlContext, requesterUserId }, VERBOSE);
+    if (result.success) {
+      sessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, isolationBackend: iso.backend, sessionId: session, tool, infoBlock, urlContext, requesterUserId };
+      trackSession(session, sessionInfo, VERBOSE);
+    }
   } else {
     result = await executeStartScreen(commandName, args);
     const match = result.success && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
     session = match ? match[1] : 'unknown';
     // Issue #1586: Non-isolation sessions auto-expire after 10 min — screen stays alive via `exec bash` so completion can't be detected reliably; this still blocks duplicate commands in the timeout window.
-    if (result.success && session !== 'unknown') trackSession(session, { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, tool, infoBlock, urlContext, requesterUserId }, VERBOSE);
+    if (result.success && session !== 'unknown') {
+      sessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, tool, infoBlock, urlContext, requesterUserId };
+      trackSession(session, sessionInfo, VERBOSE);
+    }
   }
   if (result.warning) return safeEdit(`⚠️  ${result.warning}`);
   if (result.success) {
@@ -584,6 +575,7 @@ async function executeAndUpdateMessage(ctx, startingMessage, commandName, args,
         infoBlock,
       })
     );
+    if (AUTO_WATCH_MESSAGE && commandName === 'solve' && sessionInfo?.isolationBackend) await startAutoTerminalWatchForSession({ bot, ctx, sessionId: session, sessionInfo, verbose: VERBOSE });
   } else await safeEdit(`❌ Error executing ${commandName} command:\n\n\`\`\`\n${result.error || result.output}\n\`\`\`\n\n${infoBlock}`);
 }
 
@@ -663,11 +655,12 @@ bot.command('help', async ctx => {
   message += '*/subscribe* / */unsubscribe* - 🔔 Get private DM forward of /solve completion (experimental, #1688)\n';
   message += '*/help* - Show this help message\n';
   message += '*/stop* / */start* - Stop or resume accepting new tasks (owner only)\n';
-  message += '*/log* - Fetch isolation session log (owner only). Usage: `/log <uuid>` or reply with `/log`\n\n';
+  message += '*/log* - Fetch isolation session log (owner only). Usage: `/log <uuid>` or reply with `/log`\n';
+  message += '*/terminal\\_watch* - Live-update an isolation session log (owner only). Usage: `/terminal_watch <uuid>` or reply with `/terminal_watch`\n\n';
   message += '🔔 *Session Notifications:* Completion notifications are automatic; use /subscribe for private DM forwards.\n';
   if (ISOLATION_BACKEND) message += `🔒 *Isolation Mode:* \`${ISOLATION_BACKEND}\` (experimental)\n`;
   message += '\n';
-  message += '⚠️ *Note:* /solve, /do, /continue, /claude, /codex, /opencode, /agent, /hive, /solve\\_queue, /limits, /version, /accept\\_invites, /merge, /stop and /start commands only work in group chats. /subscribe and /unsubscribe work in private and group chats.\n\n';
+  message += '⚠️ *Note:* /solve, /do, /continue, /claude, /codex, /opencode, /agent, /hive, /solve\\_queue, /limits, /version, /accept\\_invites, /merge, /stop and /start commands only work in group chats. /terminal\\_watch, /subscribe and /unsubscribe work in private and group chats.\n\n';
   message += '🔧 *Common Options:*\n';
   message += `• \`--model <model>\` or \`-m\` - ${buildModelOptionDescription()}\n`;
   message += '• `--base-branch <branch>` or `-b` - Target branch for PR (default: repo default branch)\n';
@@ -1194,6 +1187,7 @@ const { registerLogCommand } = await import('./telegram-log-command.lib.mjs');
 registerTopCommand(bot, sharedCommandOpts);
 registerStartStopCommands(bot, sharedCommandOpts);
 await registerLogCommand(bot, sharedCommandOpts);
+await registerTerminalWatchCommand(bot, sharedCommandOpts);
 
 // Add message listener for verbose debugging
 if (VERBOSE) {

package/src/telegram-safe-reply.lib.mjs

@@ -0,0 +1,19 @@
+// Issue #1460/#1497: safeReply - try Markdown first, fall back to plain text on parsing errors.
+export async function safeReply(ctx, text, options = {}) {
+  try {
+    return await ctx.reply(text, { parse_mode: 'Markdown', ...options });
+  } catch (error) {
+    const message = error?.message || '';
+    const isParsingError = message.includes("can't parse entities") || message.includes("Can't parse entities") || message.includes("can't find end of") || (message.includes('Bad Request') && message.includes('400'));
+    if (!isParsingError) throw error;
+    console.error(`[telegram-bot] safeReply: Markdown parsing failed: ${message}`);
+    console.error(`[telegram-bot] safeReply: Failing message (${Buffer.byteLength(text, 'utf-8')} bytes): ${text}`);
+    const plainText = text
+      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1 ($2)')
+      .replace(/\\_/g, '_')
+      .replace(/\\\*/g, '*')
+      .replace(/\*([^*]+)\*/g, '$1')
+      .replace(/`([^`]+)`/g, '$1');
+    return await ctx.reply(plainText, { ...options, parse_mode: undefined });
+  }
+}

package/src/telegram-terminal-watch-command.lib.mjs

@@ -0,0 +1,412 @@
+/**
+ * Telegram /terminal_watch command.
+ *
+ * Watches the text log reported by `$ --status <uuid>` and edits a separate
+ * Telegram message with the latest terminal-sized snapshot.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { constants as fsConstants } from 'fs';
+import { extractSessionIdFromText, decideLogDestination, resolveLogPath } from './telegram-log-command.lib.mjs';
+
+const DEFAULT_WIDTH = 120;
+const DEFAULT_HEIGHT = 25;
+const DEFAULT_INTERVAL_MS = 2500;
+const DEFAULT_MAX_CHARS = 3400;
+const TELEGRAM_DOCUMENT_MAX_BYTES = 50 * 1024 * 1024;
+const GITHUB_URL_RE = /https:\/\/github\.com\/[^\s"'`<>]+/i;
+const activeWatches = new Map();
+
+function splitCommandArgs(text) {
+  const body = String(text || '')
+    .replace(/^\/terminal_watch(?:@\w+)?\b/i, '')
+    .trim();
+  return body.match(/"[^"]*"|'[^']*'|\S+/g)?.map(token => token.replace(/^(['"])(.*)\1$/, '$2')) || [];
+}
+
+function readOptionValue(tokens, index, inlineValue, optionName, errors) {
+  if (inlineValue !== null) return { value: inlineValue, nextIndex: index };
+  const next = tokens[index + 1];
+  if (!next || next.startsWith('--')) {
+    errors.push(`${optionName} requires a value`);
+    return { value: null, nextIndex: index };
+  }
+  return { value: next, nextIndex: index + 1 };
+}
+
+function parseIntegerOption(value, optionName, errors, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || String(parsed) !== String(value).trim() || parsed < min || parsed > max) {
+    errors.push(`${optionName} must be an integer from ${min} to ${max}`);
+    return null;
+  }
+  return parsed;
+}
+
+export function parseTerminalWatchArgs(text) {
+  const tokens = splitCommandArgs(text);
+  const options = { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, intervalMs: DEFAULT_INTERVAL_MS, maxChars: DEFAULT_MAX_CHARS };
+  const errors = [];
+  let sessionId = extractSessionIdFromText(text);
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (extractSessionIdFromText(token)) {
+      sessionId ||= extractSessionIdFromText(token);
+      continue;
+    }
+    if (!token.startsWith('--')) {
+      errors.push(`Unexpected argument: ${token}`);
+      continue;
+    }
+
+    const eq = token.indexOf('=');
+    const name = eq === -1 ? token : token.slice(0, eq);
+    const inlineValue = eq === -1 ? null : token.slice(eq + 1);
+    const read = () => {
+      const result = readOptionValue(tokens, i, inlineValue, name, errors);
+      i = result.nextIndex;
+      return result.value;
+    };
+
+    if (['--width', '--columns', '--cols', '--terminal-width'].includes(name)) {
+      const value = read();
+      if (value !== null) options.width = parseIntegerOption(value, name, errors, { min: 20, max: 240 }) || options.width;
+    } else if (['--height', '--lines', '--rows', '--terminal-height'].includes(name)) {
+      const value = read();
+      if (value !== null) options.height = parseIntegerOption(value, name, errors, { min: 5, max: 80 }) || options.height;
+    } else if (['--interval', '--interval-ms'].includes(name)) {
+      const value = read();
+      if (value !== null) options.intervalMs = parseIntegerOption(value, name, errors, { min: 1000, max: 60000 }) || options.intervalMs;
+    } else if (name === '--max-chars') {
+      const value = read();
+      if (value !== null) options.maxChars = parseIntegerOption(value, name, errors, { min: 500, max: 3800 }) || options.maxChars;
+    } else if (name === '--size') {
+      const value = read();
+      const match = value?.match(/^(\d+)x(\d+)$/i);
+      if (!match) errors.push('--size must use WIDTHxHEIGHT format, for example --size 120x25');
+      else {
+        options.width = parseIntegerOption(match[1], '--size width', errors, { min: 20, max: 240 }) || options.width;
+        options.height = parseIntegerOption(match[2], '--size height', errors, { min: 5, max: 80 }) || options.height;
+      }
+    } else {
+      errors.push(`Unknown option: ${name}`);
+    }
+  }
+
+  return { sessionId, options, errors };
+}
+
+export function tailTextForTerminal(text, { width = DEFAULT_WIDTH, height = DEFAULT_HEIGHT, maxChars = DEFAULT_MAX_CHARS } = {}) {
+  const normalized = String(text || '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n');
+  const lines = normalized.split('\n');
+  const visibleLines = lines.slice(-height).map(line => {
+    const expanded = line.replace(/\t/g, '    ');
+    return expanded.length > width ? `...${expanded.slice(-(width - 3))}` : expanded;
+  });
+  let result = visibleLines.join('\n').trimEnd();
+  if (!result) return '(no log output yet)';
+  if (result.length > maxChars) {
+    result = result.slice(-maxChars);
+    const firstNewline = result.indexOf('\n');
+    if (firstNewline > 0) result = result.slice(firstNewline + 1);
+    result = `...[truncated]\n${result}`;
+  }
+  return result;
+}
+
+function sanitizeCodeBlock(text) {
+  return String(text || '').replace(/```/g, "'''");
+}
+
+export function formatTerminalWatchMessage({ sessionId, statusResult = null, logText = '', options = {}, updateCount = 0, completed = false, repoDescription = null }) {
+  const status = statusResult?.status || 'unknown';
+  const width = options.width || DEFAULT_WIDTH;
+  const height = options.height || DEFAULT_HEIGHT;
+  const snapshot = sanitizeCodeBlock(tailTextForTerminal(logText, options));
+  const title = completed ? '✅ Terminal watch complete' : '🔄 Live terminal watch';
+  const lines = [title, `Session: \`${sessionId}\``, `Status: \`${status}\``, `Terminal: \`${width}x${height}\``];
+  if (repoDescription) lines.push(`Repo: \`${repoDescription}\``);
+  if (!completed) lines.push(`Updates: ${updateCount}`);
+  lines.push('', '```', snapshot, '```');
+  return lines.join('\n');
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function fileSize(filePath) {
+  try {
+    return (await fs.stat(filePath)).size;
+  } catch {
+    return null;
+  }
+}
+
+async function readLogFile(logPath) {
+  try {
+    return await fs.readFile(logPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return '';
+    throw error;
+  }
+}
+
+function extractGitHubUrlFromStatus(statusResult) {
+  const match = String(statusResult?.command || '').match(GITHUB_URL_RE);
+  return match ? match[0].replace(/[),.;]+$/, '') : null;
+}
+
+export async function resolveTerminalWatchRepository({ sessionInfo = null, statusResult = null, parseGitHubUrl, detectRepositoryVisibility }) {
+  const url = sessionInfo?.url || extractGitHubUrlFromStatus(statusResult);
+  if (!url || !parseGitHubUrl || !detectRepositoryVisibility) return { repoVisibility: null, repoDescription: null };
+  const parsed = parseGitHubUrl(url);
+  if (!parsed?.valid || !parsed.owner || !parsed.repo) return { repoVisibility: null, repoDescription: null };
+  try {
+    return {
+      repoVisibility: await detectRepositoryVisibility(parsed.owner, parsed.repo),
+      repoDescription: `${parsed.owner}/${parsed.repo}`,
+    };
+  } catch (error) {
+    console.error('[ERROR] /terminal_watch: detectRepositoryVisibility failed:', error);
+    return { repoVisibility: null, repoDescription: `${parsed.owner}/${parsed.repo}` };
+  }
+}
+
+async function sendLogDocument({ bot, chatId, logPath, sessionId, statusResult }) {
+  if (!(await fileExists(logPath))) return;
+  const size = await fileSize(logPath);
+  if (size !== null && size > TELEGRAM_DOCUMENT_MAX_BYTES) {
+    await bot.telegram.sendMessage(chatId, `⚠️ Full log for \`${sessionId}\` is ${(size / (1024 * 1024)).toFixed(1)} MB, above Telegram's 50 MB upload limit.`, { parse_mode: 'Markdown' });
+    return;
+  }
+  await bot.telegram.sendDocument(chatId, { source: logPath, filename: path.basename(logPath) }, { caption: `📄 Full log for session \`${sessionId}\`${statusResult?.status ? `\nStatus: \`${statusResult.status}\`` : ''}`, parse_mode: 'Markdown' });
+}
+
+async function querySessionStatusWithRetry(querySessionStatus, sessionId, verbose, attempts = 3) {
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const statusResult = await querySessionStatus(sessionId, verbose);
+    if (statusResult?.exists || attempt === attempts) return statusResult;
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  return null;
+}
+
+export function watchTerminalLogSession({ bot, chatId, messageId, sessionId, logPath, querySessionStatus, isTerminalSessionStatus, options = {}, repoDescription = null, verbose = false, attachLogOnComplete = true }) {
+  const key = `${chatId}:${messageId}:${sessionId}`;
+  activeWatches.get(key)?.stop();
+
+  let stopped = false;
+  let lastMessage = '';
+  let updateCount = 0;
+  let timer = null;
+  const intervalMs = options.intervalMs || DEFAULT_INTERVAL_MS;
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const statusResult = await querySessionStatus(sessionId, verbose);
+      const completed = !!statusResult?.status && isTerminalSessionStatus(statusResult.status);
+      const logText = await readLogFile(logPath);
+      const message = formatTerminalWatchMessage({ sessionId, statusResult, logText, options, updateCount: ++updateCount, completed, repoDescription });
+      if (message !== lastMessage) {
+        await bot.telegram.editMessageText(chatId, messageId, undefined, message, { parse_mode: 'Markdown' });
+        lastMessage = message;
+      }
+      if (completed) {
+        stopped = true;
+        activeWatches.delete(key);
+        if (attachLogOnComplete) await sendLogDocument({ bot, chatId, logPath, sessionId, statusResult });
+        return;
+      }
+    } catch (error) {
+      console.error(`[terminal-watch] Error while watching ${sessionId}:`, error);
+    }
+    if (!stopped) timer = setTimeout(tick, intervalMs);
+  };
+
+  const control = {
+    stop: () => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      activeWatches.delete(key);
+    },
+  };
+  activeWatches.set(key, control);
+  timer = setTimeout(tick, 0);
+  return control;
+}
+
+function buildUsage() {
+  return 'Usage:\n• `/terminal_watch <UUID>`\n• Reply to a session message with `/terminal_watch`\n\nOptions: `--size 120x25`, `--width 120`, `--height 25`, `--interval-ms 2500`, `--max-chars 3400`';
+}
+
+async function createWatchMessage({ ctx, targetChatId, replyToMessageId, text }) {
+  if (targetChatId === ctx.chat.id) {
+    return await ctx.reply(text, { parse_mode: 'Markdown', reply_to_message_id: replyToMessageId });
+  }
+  return await ctx.telegram.sendMessage(targetChatId, text, replyToMessageId ? { parse_mode: 'Markdown', reply_to_message_id: replyToMessageId } : { parse_mode: 'Markdown' });
+}
+
+async function forwardOrCopyToDm(ctx, sourceMessage) {
+  const userId = ctx.from?.id;
+  if (!userId || !sourceMessage) return null;
+  try {
+    const forwarded = await ctx.telegram.forwardMessage(userId, ctx.chat.id, sourceMessage.message_id);
+    return forwarded?.message_id || null;
+  } catch (forwardError) {
+    try {
+      const copied = await ctx.telegram.copyMessage(userId, ctx.chat.id, sourceMessage.message_id);
+      return copied?.message_id || null;
+    } catch (copyError) {
+      console.error('[ERROR] /terminal_watch: forward/copyMessage to DM failed:', forwardError, copyError);
+      return null;
+    }
+  }
+}
+
+async function startWatchFromResolvedSession({ bot, ctx, sessionId, statusResult, sessionInfo, decision, logPath, watchOptions, querySessionStatus, isTerminalSessionStatus, repoDescription, auto = false, verbose = false }) {
+  if (auto && decision.destination !== 'chat') {
+    verbose && console.log(`[VERBOSE] Auto terminal watch skipped for ${sessionId}: ${decision.reason}`);
+    return { started: false, reason: decision.reason };
+  }
+
+  const targetChatId = decision.destination === 'chat' ? ctx.chat.id : ctx.from?.id;
+  if (!targetChatId) return { started: false, reason: 'Missing target chat id' };
+
+  const initialLogText = await readLogFile(logPath);
+  const initialText = formatTerminalWatchMessage({ sessionId, statusResult, logText: initialLogText, options: watchOptions, repoDescription });
+  let replyToMessageId = ctx.message?.message_id || undefined;
+  if (decision.destination === 'dm' && ctx.chat.type !== 'private') {
+    replyToMessageId = await forwardOrCopyToDm(ctx, ctx.message?.reply_to_message || ctx.message);
+  }
+
+  const watchMessage = await createWatchMessage({ ctx, targetChatId, replyToMessageId, text: initialText });
+  watchTerminalLogSession({ bot, chatId: targetChatId, messageId: watchMessage.message_id, sessionId, logPath, querySessionStatus, isTerminalSessionStatus, options: watchOptions, repoDescription, verbose });
+
+  if (!auto && decision.destination === 'dm' && ctx.chat.type !== 'private') {
+    await ctx.reply(`📬 Started terminal watch for \`${sessionId}\` in your direct messages.`, { parse_mode: 'Markdown', reply_to_message_id: ctx.message.message_id });
+  }
+  return { started: true, messageId: watchMessage.message_id, sessionInfo };
+}
+
+export async function startAutoTerminalWatchForSession({ bot, ctx, sessionId, sessionInfo, verbose = false, options = {} }) {
+  try {
+    const runner = await import('./isolation-runner.lib.mjs');
+    const { parseGitHubUrl, detectRepositoryVisibility } = await import('./github.lib.mjs');
+    const statusResult = await querySessionStatusWithRetry(runner.querySessionStatus, sessionId, verbose);
+    if (!statusResult?.exists) return { started: false, reason: 'Unknown session id' };
+    const { repoVisibility, repoDescription } = await resolveTerminalWatchRepository({ sessionInfo, statusResult, parseGitHubUrl, detectRepositoryVisibility });
+    const decision = decideLogDestination({ statusResult, sessionInfo, repoVisibility, chatType: ctx.chat?.type });
+    if (decision.destination !== 'chat') return { started: false, reason: decision.reason };
+    const logPath = resolveLogPath({ statusResult, isolationBackend: decision.isolationBackend });
+    if (!logPath) return { started: false, reason: 'Missing log path' };
+    return await startWatchFromResolvedSession({ bot, ctx, sessionId, statusResult, sessionInfo, decision, logPath, watchOptions: { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, intervalMs: DEFAULT_INTERVAL_MS, maxChars: DEFAULT_MAX_CHARS, ...options }, querySessionStatus: runner.querySessionStatus, isTerminalSessionStatus: runner.isTerminalSessionStatus, repoDescription, auto: true, verbose });
+  } catch (error) {
+    console.error('[terminal-watch] Auto-start failed:', error);
+    return { started: false, reason: error.message || String(error) };
+  }
+}
+
+export async function registerTerminalWatchCommand(bot, options) {
+  const { VERBOSE = false, isOldMessage, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage } = options;
+  const runner = await import('./isolation-runner.lib.mjs');
+  const getTrackedSessionInfo = options.getTrackedSessionInfo || (await import('./session-monitor.lib.mjs')).getTrackedSessionInfo;
+  const detectRepositoryVisibility = options.detectRepositoryVisibility || (await import('./github.lib.mjs')).detectRepositoryVisibility;
+  const parseGitHubUrl = options.parseGitHubUrl || (await import('./github.lib.mjs')).parseGitHubUrl;
+
+  bot.command('terminal_watch', async ctx => {
+    VERBOSE && console.log('[VERBOSE] /terminal_watch command received');
+    if (isOldMessage && isOldMessage(ctx)) return;
+
+    const chat = ctx.chat;
+    const message = ctx.message;
+    if (!chat || !message) return;
+
+    const parsedArgs = parseTerminalWatchArgs(message.text || '');
+    if (parsedArgs.errors.length > 0) {
+      await ctx.reply(`❌ Invalid /terminal_watch options:\n${parsedArgs.errors.map(e => `• ${e}`).join('\n')}\n\n${buildUsage()}`, { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      return;
+    }
+
+    const sessionId = parsedArgs.sessionId || extractSessionIdFromText(message.reply_to_message?.text || message.reply_to_message?.caption || '');
+    if (!sessionId) {
+      await ctx.reply(`❌ /terminal_watch requires a session id.\n\n${buildUsage()}`, { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      return;
+    }
+
+    if (chat.type !== 'private') {
+      try {
+        const member = await ctx.telegram.getChatMember(chat.id, ctx.from.id);
+        if (!member || member.status !== 'creator') {
+          await ctx.reply('❌ /terminal_watch is only available to the chat owner.', { reply_to_message_id: message.message_id });
+          return;
+        }
+      } catch (error) {
+        console.error('[ERROR] /terminal_watch: getChatMember failed:', error);
+        await ctx.reply('❌ Failed to verify permissions for /terminal_watch.', { reply_to_message_id: message.message_id });
+        return;
+      }
+    }
+
+    if (isChatAuthorized && !isChatAuthorized(chat.id) && (!isTopicAuthorized || !isTopicAuthorized(ctx))) {
+      const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${chat.id}) is not authorized.`;
+      await ctx.reply(errMsg, { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    let statusResult;
+    try {
+      statusResult = await runner.querySessionStatus(sessionId, VERBOSE);
+    } catch (error) {
+      console.error('[ERROR] /terminal_watch: querySessionStatus failed:', error);
+      await ctx.reply(`❌ Failed to query session status: ${error.message || String(error)}`, { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    if (!statusResult?.exists) {
+      await ctx.reply(`❌ Session \`${sessionId}\` is not known to start-command.`, { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      return;
+    }
+
+    const sessionInfo = getTrackedSessionInfo ? getTrackedSessionInfo(sessionId) : null;
+    const { repoVisibility, repoDescription } = await resolveTerminalWatchRepository({ sessionInfo, statusResult, parseGitHubUrl, detectRepositoryVisibility });
+    const decision = decideLogDestination({ statusResult, sessionInfo, repoVisibility, chatType: chat.type });
+    if (decision.destination === 'reject') {
+      await ctx.reply(`❌ ${decision.reason}`, { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    const logPath = resolveLogPath({ statusResult, isolationBackend: decision.isolationBackend });
+    if (!logPath) {
+      await ctx.reply('❌ Could not determine the log file path for this session.', { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    try {
+      await startWatchFromResolvedSession({ bot, ctx, sessionId, statusResult, sessionInfo, decision, logPath, watchOptions: parsedArgs.options, querySessionStatus: runner.querySessionStatus, isTerminalSessionStatus: runner.isTerminalSessionStatus, repoDescription, verbose: VERBOSE });
+    } catch (error) {
+      console.error('[ERROR] /terminal_watch: failed to start watch:', error);
+      const friendly = error?.code === 403 || /chat not found|bot can't initiate conversation/i.test(error?.message || '') ? 'I could not send you a DM. Please open a private chat with me and send /start, then try again.' : `Failed to start terminal watch: ${error.message || String(error)}`;
+      await ctx.reply(`❌ ${friendly}`, { reply_to_message_id: message.message_id });
+    }
+  });
+}
+
+export const __INTERNAL_FOR_TESTS__ = {
+  DEFAULT_WIDTH,
+  DEFAULT_HEIGHT,
+  DEFAULT_INTERVAL_MS,
+  DEFAULT_MAX_CHARS,
+  TELEGRAM_DOCUMENT_MAX_BYTES,
+  GITHUB_URL_RE,
+};