@link-assistant/hive-mind 1.56.17 → 1.56.18

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 1.56.18
+
+### Patch Changes
+
+- 47810ae: Telegram bot: add experimental `/subscribe` + `/unsubscribe` commands so users can opt in to receive a private DM forward of the `/solve` work-session completion message (commands work in both private and group chats; subscriptions are kept in memory and reset on bot restart). The completion message now includes both an `Issue:` line (the original URL passed to `/solve`) and, when the agent created a pull request for that issue, a follow-up `Pull request:` line so reviewers see both links without leaving the chat. (#1688)
+
 ## 1.56.17
 
 ### Patch Changes

package/package.json

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

@@ -18,6 +18,7 @@
 import { promisify } from 'util';
 import { exec as execCallback } from 'child_process';
 import { formatSessionCompletionMessage, getSessionCompletionExitCode } from './work-session-formatting.lib.mjs';
+import { notifySubscribers, getSubscriberCount } from './telegram-subscribers.lib.mjs';
 
 export { formatSessionCompletionMessage, getSessionCompletionExitCode } from './work-session-formatting.lib.mjs';
 
@@ -251,6 +252,20 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
 
       try {
         const finalExitCode = getSessionCompletionExitCode({ exitCode, statusResult });
+
+        // Issue #1688: When the original /solve URL was an issue, look up the
+        //   linked PR so the completion message can include both an `Issue:` and
+        //   a `Pull request:` line. Failures are logged and ignored — the
+        //   notification still goes out without the PR line.
+        let pullRequestUrl = null;
+        try {
+          pullRequestUrl = await resolvePullRequestUrlForSession(sessionInfo, { verbose, lookupLinkedPullRequest: options.lookupLinkedPullRequest });
+        } catch (lookupError) {
+          if (verbose) {
+            console.log(`[VERBOSE] Pull request lookup failed for ${sessionName}: ${lookupError?.message || lookupError}`);
+          }
+        }
+
         const message = formatSessionCompletionMessage({
           sessionName,
           sessionInfo,
@@ -258,13 +273,44 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
           observedEndTime: new Date(),
           exitCode: finalExitCode,
           infoBlock: sessionInfo?.infoBlock || '',
+          pullRequestUrl,
         });
 
         // Update the original reply message if messageId is available, otherwise send new message
+        let notifyFromChatId = null;
+        let notifyMessageId = null;
         if (sessionInfo.messageId) {
           await bot.telegram.editMessageText(sessionInfo.chatId, sessionInfo.messageId, undefined, message, { parse_mode: 'Markdown' });
+          notifyFromChatId = sessionInfo.chatId;
+          notifyMessageId = sessionInfo.messageId;
         } else {
-          await bot.telegram.sendMessage(sessionInfo.chatId, message, { parse_mode: 'Markdown' });
+          const sent = await bot.telegram.sendMessage(sessionInfo.chatId, message, { parse_mode: 'Markdown' });
+          notifyFromChatId = sent?.chat?.id || sessionInfo.chatId;
+          notifyMessageId = sent?.message_id || null;
+        }
+
+        // Issue #1688: forward the same completion message to every /subscribe-d user
+        //   in their private chat with the bot. Failures are logged but don't block
+        //   completion of the parent session.
+        if (getSubscriberCount() > 0 && notifyFromChatId && notifyMessageId) {
+          try {
+            const skipUserIds = new Set();
+            if (sessionInfo?.requesterUserId) skipUserIds.add(sessionInfo.requesterUserId);
+            const summary = await notifySubscribers({
+              bot,
+              fromChatId: notifyFromChatId,
+              messageId: notifyMessageId,
+              fallbackText: message,
+              fallbackOptions: { parse_mode: 'Markdown' },
+              skipUserIds,
+              verbose,
+            });
+            if (verbose) {
+              console.log(`[VERBOSE] Subscribe notify summary for ${sessionName}: forwarded=${summary.forwarded}, sent=${summary.sent}, skipped=${summary.skipped}, failures=${summary.failures.length}`);
+            }
+          } catch (notifyError) {
+            console.error(`[session-monitor] notifySubscribers failed for ${sessionName}:`, notifyError);
+          }
         }
 
         completeSession(sessionName, finalExitCode || 0, verbose);
@@ -285,6 +331,51 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
   }
 }
 
+/**
+ * Look up the URL of a pull request linked to the issue this session worked on.
+ * Returns null when the session was already operating on a PR, the URL context
+ * is missing, or no linked PR exists.
+ *
+ * Lazy-loads the GitHub batch helper so unrelated tests/imports don't pull
+ * GitHub deps. Tests can override the lookup via `options.lookupLinkedPullRequest`.
+ *
+ * @param {Object} sessionInfo
+ * @param {Object} [options]
+ * @param {boolean} [options.verbose]
+ * @param {Function} [options.lookupLinkedPullRequest] - Optional override `(ctx) => Promise<string|null>`
+ * @returns {Promise<string|null>} PR URL or null
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1688
+ */
+async function resolvePullRequestUrlForSession(sessionInfo, { verbose = false, lookupLinkedPullRequest = null } = {}) {
+  const ctx = sessionInfo?.urlContext;
+  if (!ctx || ctx.type !== 'issue' || !ctx.owner || !ctx.repo || !ctx.number) {
+    return null;
+  }
+
+  if (typeof lookupLinkedPullRequest === 'function') {
+    return await lookupLinkedPullRequest(ctx);
+  }
+
+  try {
+    const { batchCheckPullRequestsForIssues } = await import('./github.lib.mjs');
+    const result = await batchCheckPullRequestsForIssues(ctx.owner, ctx.repo, [ctx.number]);
+    const linkedPRs = result?.[ctx.number]?.linkedPRs || [];
+    if (linkedPRs.length > 0 && linkedPRs[0].url) {
+      if (verbose) {
+        console.log(`[VERBOSE] Found linked PR ${linkedPRs[0].url} for issue ${ctx.owner}/${ctx.repo}#${ctx.number}`);
+      }
+      return linkedPRs[0].url;
+    }
+  } catch (error) {
+    if (verbose) {
+      console.log(`[VERBOSE] batchCheckPullRequestsForIssues failed for ${ctx.owner}/${ctx.repo}#${ctx.number}: ${error?.message || error}`);
+    }
+    throw error;
+  }
+  return null;
+}
+
 /**
  * Start the session monitoring interval
  * @param {Object} bot - Telegraf bot instance for sending messages

package/src/telegram-bot.mjs

@@ -551,7 +551,7 @@ async function safeReply(ctx, text, options = {}) {
   }
 }
 
-async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude') {
+async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude', urlContext = null) {
   const { chat, message_id: msgId } = startingMessage;
   const safeEdit = async text => {
     try {
@@ -560,22 +560,20 @@ async function executeAndUpdateMessage(ctx, startingMessage, commandName, args,
       console.error(`[telegram-bot] Failed to update message for ${commandName}: ${e.message}`);
     }
   };
+  const requesterUserId = ctx.from?.id ?? null; // Issue #1688: suppress duplicate /subscribe DM
   const iso = await resolveIsolation(perCommandIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE);
   let result, session;
   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 }, 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);
   } 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: Track non-isolation sessions with timeout-based expiry.
-    // These sessions cannot reliably detect completion (screen stays alive via
-    // `exec bash`), so active URL checks auto-expire them after 10 min.
-    // This prevents accidental duplicate commands within 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 }, VERBOSE);
+    // 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.warning) return safeEdit(`⚠️  ${result.warning}`);
   if (result.success) {
@@ -662,13 +660,14 @@ bot.command('help', async ctx => {
   message += '*/merge* - Merge queue (experimental)\n';
   message += 'Usage: `/merge <github-repo-url>`\n';
   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.\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';
   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.\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. /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';
@@ -772,6 +771,8 @@ const { registerMergeCommand } = await import('./telegram-merge-command.lib.mjs'
 registerMergeCommand(bot, sharedCommandOpts);
 const { registerSolveQueueCommand } = await import('./telegram-solve-queue-command.lib.mjs');
 const { handleSolveQueueCommand } = registerSolveQueueCommand(bot, { ...sharedCommandOpts, getSolveQueue });
+const { registerSubscribeCommands } = await import('./telegram-subscribers.lib.mjs'); // #1688
+registerSubscribeCommands(bot, sharedCommandOpts);
 
 // Named handler for /solve command - extracted for reuse by text-based fallback (issue #1207)
 async function handleSolveCommand(ctx) {
@@ -983,10 +984,10 @@ async function handleSolveCommand(ctx) {
   const normalizedUrl = validation.parsed.normalized;
 
   const requester = buildUserMention({ user: ctx.from, parseMode: 'Markdown' });
-  // Issue #1228: Show only user-provided options (exclude locked overrides to avoid duplication)
-  // Issue #1460: Escape options text to prevent Markdown parsing errors
+  // #1228: only user options; #1460: escape; #1688: 'Issue:' / 'Pull request:' label so completion can append PR link.
   const userOptionsRaw = userArgs.slice(1).join(' ');
-  let infoBlock = `Requested by: ${requester}\nURL: ${escapeMarkdown(normalizedUrl)}`;
+  const urlLabel = validation.parsed?.type === 'pull' ? 'Pull request' : 'Issue';
+  let infoBlock = `Requested by: ${requester}\n${urlLabel}: ${escapeMarkdown(normalizedUrl)}`;
   if (userOptionsRaw) infoBlock += `\n\n🛠 Options: ${escapeMarkdown(userOptionsRaw)}`;
   if (solveOverrides.length > 0) infoBlock += `${userOptionsRaw ? '\n' : '\n\n'}🔒 Locked options: ${escapeMarkdown(solveOverrides.join(' '))}`;
   const solveQueue = getSolveQueue({ verbose: VERBOSE });
@@ -1012,12 +1013,15 @@ async function handleSolveCommand(ctx) {
     return;
   }
 
+  // Issue #1688: parsed URL context lets the completion message look up linked PRs.
+  const solveUrlContext = validation.parsed ? { owner: validation.parsed.owner, repo: validation.parsed.repo, number: validation.parsed.number, type: validation.parsed.type, normalized: validation.parsed.normalized || normalizedUrl } : null;
+
   const toolQueuedCount = queueStats.queuedByTool[solveTool] || 0; // tool-specific queue count (#1551)
   if (check.canStart && toolQueuedCount === 0) {
     const startingMessage = await safeReply(ctx, formatStartingWorkSessionMessage({ infoBlock }), { reply_to_message_id: ctx.message.message_id });
-    await executeAndUpdateMessage(ctx, startingMessage, 'solve', args, infoBlock, effectiveSolveIsolation, solveTool);
+    await executeAndUpdateMessage(ctx, startingMessage, 'solve', args, infoBlock, effectiveSolveIsolation, solveTool, solveUrlContext);
   } else {
-    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args, ctx, requester, infoBlock, tool: solveTool, perCommandIsolation: effectiveSolveIsolation });
+    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args, ctx, requester, infoBlock, tool: solveTool, perCommandIsolation: effectiveSolveIsolation, urlContext: solveUrlContext });
     let queueMessage = `📋 Solve command queued (${solveTool} queue position #${toolQueuedCount + 1})\n\n${infoBlock}`; // tool-specific position (#1551)
     if (check.reason) queueMessage += `\n\n⏳ Waiting: ${escapeMarkdown(check.reason)}`;
     const queuedMessage = await safeReply(ctx, queueMessage, { reply_to_message_id: ctx.message.message_id });
@@ -1252,7 +1256,7 @@ bot.on('message', async (ctx, next) => {
     }
   }
 
-  // Check if this is a command we handle
+  // /subscribe + /unsubscribe (#1688) are intentionally not in the text fallback — Telegraf's bot.command() is sufficient.
   const solveHandlers = Object.fromEntries(SOLVE_COMMAND_NAMES.map(command => [command, handleSolveCommand]));
   const handlers = { ...solveHandlers, hive: handleHiveCommand, solve_queue: handleSolveQueueCommand, solvequeue: handleSolveQueueCommand };
 

package/src/telegram-isolation.lib.mjs

@@ -80,7 +80,27 @@ export function createIsolationAwareQueueCallback(botIsolationBackend, botIsolat
     if (iso) {
       const sid = iso.runner.generateSessionId();
       const r = await iso.runner.executeWithIsolation(item.command || 'solve', item.args, { backend: iso.backend, sessionId: sid, verbose });
-      if (r.success) trackSession(sid, { chatId: item.ctx?.chat?.id, messageId: item.messageInfo?.messageId, startTime: new Date(), url: item.url, command: item.command || 'solve', isolationBackend: iso.backend, sessionId: sid, tool: item.tool || 'claude', infoBlock: item.infoBlock }, verbose);
+      if (r.success)
+        trackSession(
+          sid,
+          {
+            chatId: item.ctx?.chat?.id,
+            messageId: item.messageInfo?.messageId,
+            startTime: new Date(),
+            url: item.url,
+            command: item.command || 'solve',
+            isolationBackend: iso.backend,
+            sessionId: sid,
+            tool: item.tool || 'claude',
+            infoBlock: item.infoBlock,
+            // Issue #1688: propagate URL context + requester through the queue so the
+            //   completion notification can append a 'Pull request:' line and skip
+            //   notifying the requester twice via /subscribe.
+            urlContext: item.urlContext || null,
+            requesterUserId: item.requesterUserId ?? null,
+          },
+          verbose
+        );
       return { ...r, sessionId: sid, isolationBackend: iso.backend, output: r.output || `session: ${sid}` };
     }
     return fallbackCallback(item);

package/src/telegram-solve-queue.lib.mjs

@@ -43,6 +43,11 @@ class SolveQueueItem {
     this.requester = options.requester;
     this.infoBlock = options.infoBlock;
     this.tool = options.tool || 'claude';
+    // Issue #1688: keep parsed URL context (owner/repo/number/type) so completion
+    //   notifications can look up linked PRs for issue URLs.
+    this.urlContext = options.urlContext || null;
+    // Issue #1688: requester user ID for /subscribe duplicate-suppression.
+    this.requesterUserId = options.ctx?.from?.id ?? null;
     this.createdAt = new Date();
     this.startedAt = null;
     this.status = QueueItemStatus.QUEUED;
@@ -1361,7 +1366,20 @@ export function createQueueExecuteCallback(executeStartScreen, trackSessionFn) {
       const match = result.output && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
       const session = match ? match[1] : null;
       if (session) {
-        trackSessionFn(session, { chatId: item.ctx?.chat?.id, messageId: item.messageInfo?.messageId, startTime: new Date(), url: item.url, command: 'solve', tool: item.tool || 'claude', infoBlock: item.infoBlock });
+        trackSessionFn(session, {
+          chatId: item.ctx?.chat?.id,
+          messageId: item.messageInfo?.messageId,
+          startTime: new Date(),
+          url: item.url,
+          command: 'solve',
+          tool: item.tool || 'claude',
+          infoBlock: item.infoBlock,
+          // Issue #1688: propagate URL context + requester so the completion
+          //   notification can append a 'Pull request:' line and skip
+          //   notifying the requester twice via /subscribe.
+          urlContext: item.urlContext || null,
+          requesterUserId: item.requesterUserId ?? null,
+        });
       }
     }
     return result;

package/src/telegram-subscribers.lib.mjs

@@ -0,0 +1,220 @@
+/**
+ * Telegram /subscribe and /unsubscribe command implementation (experimental).
+ *
+ * In-memory store of users who want to receive a private notification when
+ * a /solve (or alias) work session completes. Storage is intentionally
+ * volatile: subscriptions are cleared on bot restart since we do not yet
+ * have a database (issue #1688).
+ *
+ * /subscribe and /unsubscribe work in both private chats and public group
+ * chats. They store the Telegram user ID (not the chat ID) so a single
+ * user only ever receives one private notification, regardless of which
+ * chat they ran the command in.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1688
+ */
+
+// Map<userId, { username, firstName, subscribedAt, sourceChatId }>
+const subscribers = new Map();
+
+export function isSubscribed(userId) {
+  if (userId === null || userId === undefined) return false;
+  return subscribers.has(userId);
+}
+
+export function addSubscriber(userId, info = {}) {
+  if (userId === null || userId === undefined) return false;
+  const existed = subscribers.has(userId);
+  subscribers.set(userId, {
+    username: info.username || null,
+    firstName: info.firstName || null,
+    subscribedAt: existed ? subscribers.get(userId).subscribedAt : new Date(),
+    sourceChatId: info.sourceChatId ?? null,
+  });
+  return !existed;
+}
+
+export function removeSubscriber(userId) {
+  if (userId === null || userId === undefined) return false;
+  return subscribers.delete(userId);
+}
+
+export function getSubscribers() {
+  return Array.from(subscribers.entries()).map(([userId, info]) => ({ userId, ...info }));
+}
+
+export function getSubscriberCount() {
+  return subscribers.size;
+}
+
+export function resetSubscribersForTests() {
+  subscribers.clear();
+}
+
+/**
+ * Forward (or send) a session-completion notification to every subscribed user
+ * in their private chat with the bot.
+ *
+ * Strategy:
+ *   1. Try forwardMessage(userId, sourceChatId, messageId) — preserves the
+ *      original visual style of the reply Telegram users already see in chat.
+ *   2. If that fails (e.g. the user has never started a private chat with
+ *      the bot, or the message can't be forwarded), fall back to
+ *      sendMessage(userId, fallbackText) so the notification still arrives
+ *      when possible.
+ *
+ * Returns a summary so callers can log delivery results.
+ *
+ * @param {Object} params
+ * @param {Object} params.bot - Telegraf bot instance
+ * @param {number} params.fromChatId - Chat ID of the original /solve reply
+ * @param {number} params.messageId - Message ID of the (now-edited) reply
+ * @param {string} [params.fallbackText] - Plain-text body to send when forwardMessage is rejected
+ * @param {Object} [params.fallbackOptions] - Telegram sendMessage options for fallback
+ * @param {Set<number>} [params.skipUserIds] - Users that should not receive the notification (e.g. requester is already in the chat)
+ * @param {boolean} [params.verbose]
+ * @returns {Promise<{forwarded: number, sent: number, skipped: number, failures: Array}>}
+ */
+export async function notifySubscribers({ bot, fromChatId, messageId, fallbackText = '', fallbackOptions = {}, skipUserIds = null, verbose = false } = {}) {
+  const summary = { forwarded: 0, sent: 0, skipped: 0, failures: [] };
+  if (!bot || !bot.telegram) {
+    if (verbose) console.log('[VERBOSE] notifySubscribers: missing bot/telegram, skipping');
+    return summary;
+  }
+
+  for (const [userId, info] of subscribers.entries()) {
+    if (skipUserIds && skipUserIds.has(userId)) {
+      summary.skipped += 1;
+      if (verbose) console.log(`[VERBOSE] notifySubscribers: skipping user ${userId} (in skip set)`);
+      continue;
+    }
+
+    let forwarded = false;
+    if (fromChatId !== null && fromChatId !== undefined && messageId !== null && messageId !== undefined) {
+      try {
+        await bot.telegram.forwardMessage(userId, fromChatId, messageId);
+        summary.forwarded += 1;
+        forwarded = true;
+        if (verbose) {
+          console.log(`[VERBOSE] notifySubscribers: forwarded to user ${userId} (${info.username || info.firstName || 'unknown'})`);
+        }
+      } catch (error) {
+        if (verbose) {
+          console.log(`[VERBOSE] notifySubscribers: forwardMessage to ${userId} failed: ${error?.message || error}`);
+        }
+      }
+    }
+
+    if (forwarded) continue;
+
+    if (!fallbackText) {
+      summary.failures.push({ userId, reason: 'forwardMessage failed and no fallback text supplied' });
+      continue;
+    }
+
+    try {
+      await bot.telegram.sendMessage(userId, fallbackText, fallbackOptions);
+      summary.sent += 1;
+      if (verbose) {
+        console.log(`[VERBOSE] notifySubscribers: sent fallback message to user ${userId}`);
+      }
+    } catch (error) {
+      summary.failures.push({ userId, reason: error?.message || String(error) });
+      if (verbose) {
+        console.log(`[VERBOSE] notifySubscribers: sendMessage to ${userId} failed: ${error?.message || error}`);
+      }
+    }
+  }
+
+  return summary;
+}
+
+const SUBSCRIBE_CONFIRMATION = '🔔 *Subscribed* (experimental)\n\n' + 'You will receive a private notification each time a /solve command finishes (in any chat where this bot runs).\n\n' + '⚠️ Subscriptions are kept in memory and are cleared whenever the bot restarts.\n\n' + '💡 If notifications never arrive, open a private chat with the bot and send /start so Telegram lets the bot DM you.\n\n' + 'Use /unsubscribe to stop receiving these notifications.';
+
+const UNSUBSCRIBE_CONFIRMATION = '🔕 *Unsubscribed*\n\n' + 'You will no longer receive private notifications when /solve commands finish.\n\n' + 'Use /subscribe to resume notifications.';
+
+const NOT_SUBSCRIBED_MESSAGE = 'ℹ️ You are not subscribed.\n\nUse /subscribe to start receiving private notifications when /solve commands finish.';
+
+/**
+ * Register /subscribe and /unsubscribe handlers.
+ *
+ * @param {Object} bot - Telegraf bot instance
+ * @param {Object} options - Shared command options (VERBOSE, isOldMessage, ...)
+ */
+export function registerSubscribeCommands(bot, options = {}) {
+  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb } = options;
+
+  async function shouldHandle(ctx, cmdName) {
+    VERBOSE && console.log(`[VERBOSE] ${cmdName} command received`);
+    if (addBreadcrumb) {
+      await addBreadcrumb({
+        category: 'telegram.command',
+        message: `${cmdName} command received`,
+        level: 'info',
+        data: { chatId: ctx.chat?.id, chatType: ctx.chat?.type, userId: ctx.from?.id, username: ctx.from?.username },
+      });
+    }
+    if (isOldMessage && isOldMessage(ctx)) {
+      VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: old message`);
+      return false;
+    }
+    if (isForwardedOrReply && isForwardedOrReply(ctx)) {
+      VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: forwarded or reply`);
+      return false;
+    }
+    // Issue #1688: /subscribe and /unsubscribe work in both private and group chats.
+    // In group chats we still require chat/topic authorization so unauthorized
+    // chats cannot use the bot to spam.
+    const chatType = ctx.chat?.type;
+    const isPrivateChat = chatType === 'private';
+    if (!isPrivateChat && isTopicAuthorized && !isTopicAuthorized(ctx)) {
+      VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: not authorized`);
+      if (buildAuthErrorMessage) {
+        await ctx.reply(buildAuthErrorMessage(ctx), { reply_to_message_id: ctx.message?.message_id });
+      }
+      return false;
+    }
+    if (!ctx.from?.id) {
+      VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: no user id on update`);
+      return false;
+    }
+    return true;
+  }
+
+  bot.command('subscribe', async ctx => {
+    if (!(await shouldHandle(ctx, '/subscribe'))) return;
+
+    const userId = ctx.from.id;
+    const wasNew = addSubscriber(userId, {
+      username: ctx.from.username,
+      firstName: ctx.from.first_name,
+      sourceChatId: ctx.chat?.id ?? null,
+    });
+
+    let message = SUBSCRIBE_CONFIRMATION;
+    if (!wasNew) {
+      message = 'ℹ️ You are already subscribed.\n\nUse /unsubscribe to stop receiving private notifications when /solve commands finish.';
+    }
+
+    await ctx.reply(message, {
+      parse_mode: 'Markdown',
+      reply_to_message_id: ctx.message?.message_id,
+    });
+
+    VERBOSE && console.log(`[VERBOSE] Subscriber ${userId} (${ctx.from.username || ctx.from.first_name || 'unknown'}) added (new=${wasNew}); total=${getSubscriberCount()}`);
+  });
+
+  bot.command('unsubscribe', async ctx => {
+    if (!(await shouldHandle(ctx, '/unsubscribe'))) return;
+
+    const userId = ctx.from.id;
+    const wasRemoved = removeSubscriber(userId);
+
+    await ctx.reply(wasRemoved ? UNSUBSCRIBE_CONFIRMATION : NOT_SUBSCRIBED_MESSAGE, {
+      parse_mode: 'Markdown',
+      reply_to_message_id: ctx.message?.message_id,
+    });
+
+    VERBOSE && console.log(`[VERBOSE] Subscriber ${userId} (${ctx.from.username || ctx.from.first_name || 'unknown'}) removed=${wasRemoved}; total=${getSubscriberCount()}`);
+  });
+}

package/src/work-session-formatting.lib.mjs

@@ -52,7 +52,38 @@ export function formatExecutingWorkSessionMessage({ sessionName = 'unknown', iso
   return `⏳ Executing...\n\n📊 Session: \`${sessionName}\`${isolationInfo}${details}`;
 }
 
-export function formatSessionCompletionMessage({ sessionName, sessionInfo, statusResult = null, observedEndTime = new Date(), exitCode = null, infoBlock = '' } = {}) {
+/**
+ * Append an extra "Pull request:" line to an existing infoBlock when an issue's
+ * /solve session has produced a PR. Idempotent — already present URLs are not
+ * duplicated.
+ *
+ * @param {string} infoBlock - Existing infoBlock (already contains an Issue: line)
+ * @param {string|null} pullRequestUrl - PR URL discovered after the session completed
+ * @returns {string} New infoBlock
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1688
+ */
+export function appendPullRequestLine(infoBlock, pullRequestUrl) {
+  if (!pullRequestUrl || !infoBlock) return infoBlock || '';
+  if (infoBlock.includes(pullRequestUrl)) return infoBlock;
+
+  const lines = infoBlock.split('\n');
+  let lastUrlLineIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^(Issue|Pull request|URL):\s/.test(lines[i])) {
+      lastUrlLineIdx = i;
+    }
+  }
+  const prLine = `Pull request: ${pullRequestUrl}`;
+  if (lastUrlLineIdx === -1) {
+    return `${infoBlock}\n${prLine}`;
+  }
+  const before = lines.slice(0, lastUrlLineIdx + 1);
+  const after = lines.slice(lastUrlLineIdx + 1);
+  return [...before, prLine, ...after].join('\n');
+}
+
+export function formatSessionCompletionMessage({ sessionName, sessionInfo, statusResult = null, observedEndTime = new Date(), exitCode = null, infoBlock = '', pullRequestUrl = null } = {}) {
   const finalExitCode = getSessionCompletionExitCode({ exitCode, statusResult });
   const failed = finalExitCode !== null && finalExitCode !== 0;
   const statusEmoji = failed ? '❌' : '✅';
@@ -61,7 +92,10 @@ export function formatSessionCompletionMessage({ sessionName, sessionInfo, statu
   const startTime = parseDateValue(statusResult?.startTime) || parseDateValue(sessionInfo?.startTime) || observedEndTime;
   const endTime = parseDateValue(statusResult?.endTime) || observedEndTime;
   const durationSeconds = Math.max(0, (endTime.getTime() - startTime.getTime()) / 1000);
-  const resolvedInfoBlock = infoBlock || sessionInfo?.infoBlock || '';
+  let resolvedInfoBlock = infoBlock || sessionInfo?.infoBlock || '';
+  // Issue #1688: When the agent created a PR for an issue-driven /solve, append
+  //   a 'Pull request:' line so the completion message includes both Issue and PR links.
+  if (pullRequestUrl) resolvedInfoBlock = appendPullRequestLine(resolvedInfoBlock, pullRequestUrl);
   const details = resolvedInfoBlock ? `\n\n${resolvedInfoBlock}` : '';
 
   let message = `${statusEmoji} *${statusText}*\n\n`;