@link-assistant/hive-mind 1.56.18 → 1.56.19

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 1.56.19
+
+### Patch Changes
+
+- 0da8eba: Add a `/log` Telegram command that lets a chat owner pull the on-disk log of a `$` isolation session (`screen`, `tmux`, `docker`). The command accepts `/log <UUID>` directly or `/log` as a reply to any session message that contains a session UUID, validates the id with `$ --status`, derives the log path from start-command's `logPath` field, and uploads the file as a reply to the user. Logs from public GitHub repositories are uploaded to the same chat; logs from private (or unknown-visibility) repositories are sent via direct message after forwarding the originating session message into the DM, so private logs never leak into public chats. Access is restricted to the chat owner (Telegram `creator` status), matching the existing `/start`, `/stop`, and `/top` policy.
+
 ## 1.56.18
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.56.18",
+  "version": "1.56.19",
   "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-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-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/isolation-runner.lib.mjs

@@ -41,17 +41,18 @@ export function generateSessionId() {
  * Keep the parser tolerant so completion monitoring survives either format.
  *
  * @param {string} output - Raw stdout from `$ --status`
- * @returns {{exists: boolean, uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, currentTime: string|null, raw: string}}
+ * @returns {{exists: boolean, uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, currentTime: string|null, logPath: string|null, command: string|null, isolation: string|null, workingDirectory: string|null, raw: string}}
  */
 export function parseSessionStatusOutput(output) {
   const raw = (output || '').trim();
   if (!raw) {
-    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, raw: '' };
+    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, raw: '' };
   }
 
   try {
     const parsed = JSON.parse(raw);
     const data = Array.isArray(parsed) ? parsed[0] : parsed;
+    const isolationFromOptions = typeof data?.options?.isolation === 'string' ? data.options.isolation.toLowerCase() : null;
     return {
       exists: true,
       uuid: data?.uuid || null,
@@ -60,6 +61,10 @@ export function parseSessionStatusOutput(output) {
       startTime: data?.startTime || null,
       endTime: data?.endTime || null,
       currentTime: data?.currentTime || null,
+      logPath: data?.logPath || null,
+      command: data?.command || null,
+      isolation: typeof data?.isolation === 'string' ? data.isolation.toLowerCase() : isolationFromOptions,
+      workingDirectory: data?.workingDirectory || null,
       raw,
     };
   } catch {
@@ -87,6 +92,10 @@ export function parseSessionStatusOutput(output) {
     startTime: readField('startTime'),
     endTime: readField('endTime'),
     currentTime: readField('currentTime'),
+    logPath: readField('logPath'),
+    command: readField('command'),
+    isolation: readField('isolation')?.toLowerCase() || null,
+    workingDirectory: readField('workingDirectory'),
     raw,
   };
 }
@@ -213,7 +222,7 @@ export async function querySessionStatus(sessionId, verbose = false) {
     if (verbose) {
       console.log('[VERBOSE] isolation-runner: Cannot query status - $ binary not found');
     }
-    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, raw: '' };
+    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, raw: '' };
   }
 
   try {
@@ -230,7 +239,7 @@ export async function querySessionStatus(sessionId, verbose = false) {
     if (verbose) {
       console.log(`[VERBOSE] isolation-runner: Status query error: ${error.message}`);
     }
-    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, raw: '' };
+    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, raw: '' };
   }
 }
 

package/src/session-monitor.lib.mjs

@@ -89,6 +89,21 @@ export function trackSession(sessionName, sessionInfo, verbose = false) {
   }
 }
 
+/**
+ * Look up the in-memory record for a session id (UUID for isolation sessions
+ * or the screen session name for non-isolation sessions). Returns null when no
+ * record exists — for example, after a process restart or for sessions that
+ * were never tracked through the Telegram bot. Used by `/log` to discover the
+ * originating chat id and the GitHub URL associated with a session.
+ *
+ * @param {string} sessionName
+ * @returns {Object|null}
+ */
+export function getTrackedSessionInfo(sessionName) {
+  if (!sessionName) return null;
+  return activeSessions.get(sessionName) || null;
+}
+
 /**
  * Get the number of active sessions being tracked
  * @param {boolean} verbose - Whether to log verbose output

package/src/telegram-bot.mjs

@@ -662,9 +662,9 @@ bot.command('help', async ctx => {
   message += "Merges all PRs with 'ready' label sequentially.\n";
   message += '*/subscribe* / */unsubscribe* - 🔔 Get private DM forward of /solve completion (experimental, #1688)\n';
   message += '*/help* - Show this help message\n';
-  message += '*/stop* - Stop accepting new tasks (owner only)\n';
-  message += '*/start* - Resume accepting tasks (owner only)\n\n';
-  message += '🔔 *Session Notifications:* The bot monitors sessions and notifies when they complete. Use /subscribe to also get DM forwards (in-memory, resets on restart).\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 += '🔔 *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';
@@ -763,7 +763,6 @@ bot.command('version', async ctx => {
   await ctx.telegram.editMessageText(fetchingMessage.chat.id, fetchingMessage.message_id, undefined, '🤖 *Version Information*\n\n' + formatVersionMessage(result.versions), { parse_mode: 'Markdown' });
 });
 
-// Register external command modules (keeps telegram-bot.mjs under line limit)
 const { registerAcceptInvitesCommand } = await import('./telegram-accept-invitations.lib.mjs');
 const sharedCommandOpts = { VERBOSE, isOldMessage, isForwardedOrReply, isGroupChat: _isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, isChatStopped, getStoppedChatRejectMessage };
 registerAcceptInvitesCommand(bot, sharedCommandOpts);
@@ -1191,8 +1190,10 @@ bot.command(/^hive$/i, handleHiveCommand);
 
 const { registerTopCommand } = await import('./telegram-top-command.lib.mjs');
 const { registerStartStopCommands } = await import('./telegram-start-stop-command.lib.mjs');
+const { registerLogCommand } = await import('./telegram-log-command.lib.mjs');
 registerTopCommand(bot, sharedCommandOpts);
 registerStartStopCommands(bot, sharedCommandOpts);
+await registerLogCommand(bot, sharedCommandOpts);
 
 // Add message listener for verbose debugging
 if (VERBOSE) {

package/src/telegram-log-command.lib.mjs

@@ -0,0 +1,372 @@
+/**
+ * Telegram /log command implementation
+ *
+ * Lets a chat owner pull the log of an isolation session that was launched
+ * through the `$` (start-command) CLI. The session is identified by its UUID,
+ * either passed as `/log <UUID>` or extracted from a message that the
+ * `/log` command is replying to.
+ *
+ * Privacy guarantees:
+ * - Only the chat creator (`status === 'creator'`) may invoke `/log`.
+ * - Logs from public GitHub repositories may be uploaded into the chat where
+ *   `/log` was issued.
+ * - Logs from private GitHub repositories — and logs whose repository
+ *   visibility we cannot determine — are sent to the user via direct message
+ *   only, after forwarding the original message that contained the session id.
+ * - Currently only sessions launched with one of the `$` isolation backends
+ *   (`screen`, `tmux`, `docker`) are supported. Direct (non-isolation) sessions
+ *   are rejected with a clear message.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1686
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+import { constants as fsConstants } from 'fs';
+
+const UUID_RE = /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/i;
+const ISOLATION_BACKENDS = new Set(['screen', 'tmux', 'docker']);
+// Telegram bots may upload documents up to 50 MB via sendDocument.
+// https://core.telegram.org/bots/api#senddocument
+const TELEGRAM_DOCUMENT_MAX_BYTES = 50 * 1024 * 1024;
+
+/**
+ * Extract the first RFC 4122 v4-shaped UUID found in `text`.
+ *
+ * @param {string|null|undefined} text
+ * @returns {string|null}
+ */
+export function extractSessionIdFromText(text) {
+  if (!text || typeof text !== 'string') return null;
+  const match = text.match(UUID_RE);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Decide where the log for a session should be delivered.
+ *
+ * Inputs:
+ * - `statusResult`: parsed result of `$ --status <uuid>` (see
+ *   `parseSessionStatusOutput` in `isolation-runner.lib.mjs`).
+ * - `sessionInfo`: in-memory record from the Telegram session monitor, or null.
+ * - `repoVisibility`: result of `detectRepositoryVisibility(owner, repo)`, or
+ *   null when the repo could not be identified.
+ * - `chatType`: Telegram chat type where `/log` was invoked
+ *   (`'private'` | `'group'` | `'supergroup'` | `'channel'`).
+ *
+ * Output: `{ destination, reason, isolationBackend }` where `destination` is
+ * one of `'chat'` (deliver in the same chat), `'dm'` (deliver in DM),
+ * `'reject'` (don't deliver). `reason` is a short, user-facing string.
+ *
+ * @returns {{destination: 'chat'|'dm'|'reject', reason: string, isolationBackend: string|null}}
+ */
+export function decideLogDestination({ statusResult, sessionInfo, repoVisibility, chatType }) {
+  if (!statusResult || !statusResult.exists) {
+    return { destination: 'reject', reason: 'Unknown session id (start-command does not know about it).', isolationBackend: null };
+  }
+
+  // Determine isolation backend. Prefer the in-memory record (which knows what
+  // we asked `$` to use), fall back to whatever `$ --status` reports.
+  const isolationBackend = (sessionInfo?.isolationBackend || statusResult.isolation || '').toLowerCase() || null;
+  if (!isolationBackend || !ISOLATION_BACKENDS.has(isolationBackend)) {
+    return {
+      destination: 'reject',
+      reason: 'This command currently supports only sessions launched with `$` isolation (screen / tmux / docker).',
+      isolationBackend: isolationBackend || null,
+    };
+  }
+
+  // Privacy decision — fail closed when in doubt.
+  const isPublic = repoVisibility?.isPublic === true;
+  const visibilityKnown = !!repoVisibility && repoVisibility.visibility !== null;
+
+  if (isPublic && visibilityKnown) {
+    if (chatType === 'private') {
+      // /log was invoked in DM. Deliver in DM regardless of repo visibility.
+      return { destination: 'dm', reason: 'Public repository, delivering in DM (command was sent in a private chat).', isolationBackend };
+    }
+    return { destination: 'chat', reason: 'Public repository, delivering in chat.', isolationBackend };
+  }
+
+  // Private OR unknown visibility — never leak in a public chat.
+  return {
+    destination: 'dm',
+    reason: visibilityKnown ? 'Private repository — delivering via direct message.' : 'Repository visibility could not be determined — delivering via direct message (fail-closed).',
+    isolationBackend,
+  };
+}
+
+/**
+ * Resolve the on-disk log path for a session.
+ *
+ * Prefers the `logPath` field reported by `$ --status` (always correct when
+ * supported). Falls back to start-command's documented layout if the field is
+ * missing.
+ *
+ * @returns {string|null}
+ */
+export function resolveLogPath({ statusResult, isolationBackend }) {
+  if (statusResult?.logPath) return statusResult.logPath;
+  const uuid = statusResult?.uuid;
+  if (!uuid) return null;
+  if (isolationBackend && ISOLATION_BACKENDS.has(isolationBackend)) {
+    return path.join('/tmp/start-command/logs/isolation', isolationBackend, `${uuid}.log`);
+  }
+  return path.join('/tmp/start-command/logs/direct', `${uuid}.log`);
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function fileSize(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.size;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Registers the /log command handler with the bot.
+ *
+ * Dependencies (`querySessionStatus`, `getTrackedSessionInfo`,
+ * `detectRepositoryVisibility`, `parseGitHubUrl`) are lazy-loaded from the
+ * existing libraries by default; tests pass mocked versions through `options`.
+ *
+ * @param {Object} bot - Telegraf bot instance
+ * @param {Object} options
+ * @param {boolean} [options.VERBOSE]
+ * @param {Function} options.isOldMessage
+ * @param {Function} options.isChatAuthorized
+ * @param {Function} [options.isTopicAuthorized]
+ * @param {Function} [options.buildAuthErrorMessage]
+ * @param {Function} [options.querySessionStatus] - Override for tests
+ * @param {Function} [options.getTrackedSessionInfo] - Override for tests
+ * @param {Function} [options.detectRepositoryVisibility] - Override for tests
+ * @param {Function} [options.parseGitHubUrl] - Override for tests
+ */
+export async function registerLogCommand(bot, options) {
+  const { VERBOSE = false, isOldMessage, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage } = options;
+  const querySessionStatus = options.querySessionStatus || (await import('./isolation-runner.lib.mjs')).querySessionStatus;
+  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('log', async ctx => {
+    VERBOSE && console.log('[VERBOSE] /log command received');
+
+    if (isOldMessage && isOldMessage(ctx)) {
+      VERBOSE && console.log('[VERBOSE] /log ignored: old message');
+      return;
+    }
+
+    const chat = ctx.chat;
+    const message = ctx.message;
+    if (!chat || !message) return;
+
+    const chatType = chat.type;
+    const chatId = chat.id;
+
+    // Extract the session id. Priority: explicit argument, then reply text.
+    const directSessionId = extractSessionIdFromText(message.text || '');
+    const repliedTo = message.reply_to_message;
+    const replySessionId = repliedTo ? extractSessionIdFromText(repliedTo.text || repliedTo.caption || '') : null;
+    const sessionId = directSessionId || replySessionId;
+
+    if (!sessionId) {
+      await ctx.reply('❌ /log requires a session id.\n\nUsage:\n• `/log <UUID>` — fetch a specific session log\n• Reply to a session message with `/log` — fetch the session referenced in that message', {
+        parse_mode: 'Markdown',
+        reply_to_message_id: message.message_id,
+      });
+      return;
+    }
+
+    // Authorization. /log is only available to chat owners. In private chats
+    // there is no "creator" status — the user is implicitly the owner of their
+    // own DM, so we allow it. We still apply the optional allowlist used by
+    // other commands so a private bot deployment can lock /log to known users.
+    if (chatType === 'private') {
+      // No further auth required beyond the optional whitelist applied below.
+    } else {
+      try {
+        const member = await ctx.telegram.getChatMember(chatId, ctx.from.id);
+        if (!member || member.status !== 'creator') {
+          VERBOSE && console.log('[VERBOSE] /log rejected: not chat owner');
+          await ctx.reply('❌ /log is only available to the chat owner.', { reply_to_message_id: message.message_id });
+          return;
+        }
+      } catch (error) {
+        console.error('[ERROR] /log: getChatMember failed:', error);
+        await ctx.reply('❌ Failed to verify permissions for /log.', { reply_to_message_id: message.message_id });
+        return;
+      }
+    }
+
+    if (isChatAuthorized && !isChatAuthorized(chatId)) {
+      // Topic-aware fallback (used elsewhere in this repo for forum topics).
+      if (!isTopicAuthorized || !isTopicAuthorized(ctx)) {
+        VERBOSE && console.log('[VERBOSE] /log rejected: chat not authorized');
+        const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${chatId}) is not authorized.`;
+        await ctx.reply(errMsg, { reply_to_message_id: message.message_id });
+        return;
+      }
+    }
+
+    // 1. Validate the session id with $ --status.
+    let statusResult;
+    try {
+      statusResult = await querySessionStatus(sessionId, VERBOSE);
+    } catch (error) {
+      console.error('[ERROR] /log: 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 || !statusResult.exists) {
+      await ctx.reply(`❌ Session \`${sessionId}\` is not known to start-command.\n\nUse the session id from a \`📊 Session: <uuid>\` line in one of the bot's status messages.`, {
+        parse_mode: 'Markdown',
+        reply_to_message_id: message.message_id,
+      });
+      return;
+    }
+
+    // 2. Look up tracked metadata (for repo URL and original chat).
+    const sessionInfo = getTrackedSessionInfo ? getTrackedSessionInfo(sessionId) : null;
+
+    // 3. Decide repo visibility — prefer the URL we tracked at launch time.
+    let repoVisibility = null;
+    let repoUrlDescription = null;
+    const trackedUrl = sessionInfo?.url || null;
+    if (trackedUrl) {
+      const parsed = parseGitHubUrl ? parseGitHubUrl(trackedUrl) : null;
+      if (parsed && parsed.valid && parsed.owner && parsed.repo) {
+        repoUrlDescription = `${parsed.owner}/${parsed.repo}`;
+        try {
+          repoVisibility = await detectRepositoryVisibility(parsed.owner, parsed.repo);
+        } catch (error) {
+          console.error('[ERROR] /log: detectRepositoryVisibility failed:', error);
+          repoVisibility = null;
+        }
+      }
+    }
+
+    // 4. Decide the destination.
+    const decision = decideLogDestination({ statusResult, sessionInfo, repoVisibility, chatType });
+    if (decision.destination === 'reject') {
+      await ctx.reply(`❌ ${decision.reason}`, { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    // 5. Resolve and validate the on-disk log file.
+    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;
+    }
+    if (!(await fileExists(logPath))) {
+      await ctx.reply(`❌ Log file does not exist on disk:\n\`${logPath}\`\n\nThe session may have been cleaned up by the host or the isolation backend.`, {
+        parse_mode: 'Markdown',
+        reply_to_message_id: message.message_id,
+      });
+      return;
+    }
+    const size = await fileSize(logPath);
+    if (size !== null && size > TELEGRAM_DOCUMENT_MAX_BYTES) {
+      await ctx.reply(`❌ Log file is ${(size / (1024 * 1024)).toFixed(1)} MB which exceeds Telegram's 50 MB document upload limit.\n\nFile path on host: \`${logPath}\``, {
+        parse_mode: 'Markdown',
+        reply_to_message_id: message.message_id,
+      });
+      return;
+    }
+
+    const filename = path.basename(logPath);
+    const captionLines = [`📁 Log for session \`${sessionId}\``];
+    if (decision.isolationBackend) captionLines.push(`🔒 Isolation: \`${decision.isolationBackend}\``);
+    if (statusResult.status) captionLines.push(`Status: \`${statusResult.status}\``);
+    if (repoUrlDescription) captionLines.push(`Repo: \`${repoUrlDescription}\``);
+    captionLines.push(`Privacy: ${decision.reason}`);
+    const caption = captionLines.join('\n');
+
+    if (decision.destination === 'chat') {
+      // Public repository → reply with the document directly in the chat.
+      try {
+        await ctx.replyWithDocument({ source: logPath, filename }, { reply_to_message_id: message.message_id, caption, parse_mode: 'Markdown' });
+      } catch (error) {
+        console.error('[ERROR] /log: replyWithDocument failed:', error);
+        await ctx.reply(`❌ Failed to upload log: ${error.message || String(error)}`, { reply_to_message_id: message.message_id });
+      }
+      return;
+    }
+
+    // DM flow: forward the originating message into DM (so the audit chain
+    // is preserved), then reply to that forwarded message with the log file.
+    const userId = ctx.from?.id;
+    if (!userId) {
+      await ctx.reply('❌ Cannot deliver the log via DM: missing user id.', { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    let forwardedMessageId = null;
+    try {
+      // Forward the message that contains the session id (the reply target if
+      // any, otherwise the /log message itself).
+      const forwardSource = repliedTo || message;
+      const forwardedFromChatId = forwardSource === repliedTo ? chatId : chatId;
+      const forwardedSourceMessageId = forwardSource.message_id;
+      try {
+        const forwarded = await ctx.telegram.forwardMessage(userId, forwardedFromChatId, forwardedSourceMessageId);
+        forwardedMessageId = forwarded?.message_id || null;
+      } catch (forwardError) {
+        // forwardMessage can fail if the user has not opened a DM with the bot
+        // yet, or the source chat blocks forwards. Fall back to copyMessage,
+        // which works without a forward header.
+        try {
+          const copied = await ctx.telegram.copyMessage(userId, forwardedFromChatId, forwardedSourceMessageId);
+          forwardedMessageId = copied?.message_id || null;
+        } catch (copyError) {
+          console.error('[ERROR] /log: forward/copyMessage to DM failed:', forwardError, copyError);
+          // Fall through — we can still try sendDocument without a reply ref.
+        }
+      }
+    } catch (error) {
+      console.error('[ERROR] /log: DM forwarding step failed:', error);
+    }
+
+    try {
+      const replyOpts = forwardedMessageId ? { reply_to_message_id: forwardedMessageId, caption, parse_mode: 'Markdown' } : { caption, parse_mode: 'Markdown' };
+      await ctx.telegram.sendDocument(userId, { source: logPath, filename }, replyOpts);
+    } catch (error) {
+      console.error('[ERROR] /log: sendDocument to DM failed:', error);
+      // Tell the user, in their original chat, that DM delivery failed
+      // (commonly because they have not started a chat with the bot).
+      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 send the log via DM: ${error.message || String(error)}`;
+      await ctx.reply(`❌ ${friendly}`, { reply_to_message_id: message.message_id });
+      return;
+    }
+
+    // Acknowledge in the original chat (only if it wasn't already a DM).
+    if (chatType !== 'private') {
+      try {
+        await ctx.reply(`📬 Sent the log for \`${sessionId}\` to your direct messages (private repository).`, {
+          parse_mode: 'Markdown',
+          reply_to_message_id: message.message_id,
+        });
+      } catch (error) {
+        console.error('[ERROR] /log: failed to acknowledge in chat:', error);
+      }
+    }
+  });
+}
+
+export const __INTERNAL_FOR_TESTS__ = {
+  UUID_RE,
+  TELEGRAM_DOCUMENT_MAX_BYTES,
+  ISOLATION_BACKENDS,
+};