@link-assistant/hive-mind 2.1.4 → 2.1.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.1.5
+
+### Patch Changes
+
+- 26b07f2: Extend Telegram `/merge` to accept repository, issue, and pull request targets, including reply-based GitHub link extraction, and wait for unfinished PRs to become mergeable before merging.
+
 ## 2.1.4
 
 ### Patch Changes

package/README.hi.md

@@ -511,6 +511,26 @@ Examples:
 /hive https://github.com/microsoft --all-issues --concurrency 3
 ```
 
+#### `/merge` - तैयार Pull Requests merge करें
+
+```
+/merge <repository-url|issue-url|pull-request-url> [--auto-resolve]
+
+Examples:
+/merge https://github.com/owner/repo
+/merge https://github.com/owner/repo/issues/123
+/merge https://github.com/owner/repo/pull/456
+```
+
+Repository targets `ready` label वाले PRs को क्रम से process करते हैं। Issue और
+pull request targets केवल linked या selected PR process करते हैं। आप किसी ऐसे
+message पर `/merge` से reply भी कर सकते हैं जिसमें एक GitHub repository, issue,
+या pull request link हो, जैसे कोई पुराना `/codex ...issues/123` command.
+
+अगर target PR अभी finished नहीं है, तो `/merge` merge करने से पहले उसके
+mergeable होने तक wait करता है। Merge-conflict skips अभी भी `--auto-resolve` के
+साथ काम करते हैं।
+
 #### `/limits` - उपयोग सीमाएँ दिखाएँ
 
 ```

package/README.md

@@ -532,6 +532,25 @@ Examples:
 /hive https://github.com/microsoft --all-issues --concurrency 3
 ```
 
+#### `/merge` - Merge Ready Pull Requests
+
+```
+/merge <repository-url|issue-url|pull-request-url> [--auto-resolve]
+
+Examples:
+/merge https://github.com/owner/repo
+/merge https://github.com/owner/repo/issues/123
+/merge https://github.com/owner/repo/pull/456
+```
+
+Repository targets process PRs with the `ready` label sequentially. Issue and
+pull request targets process only the linked or selected PR. You can also reply
+with `/merge` to a message containing one GitHub repository, issue, or pull
+request link, such as a previous `/codex ...issues/123` command.
+
+If a target PR is not finished yet, `/merge` waits for it to become mergeable
+before merging. Merge-conflict skips still work with `--auto-resolve`.
+
 #### `/limits` - Show Usage Limits
 
 ```

package/README.ru.md

@@ -512,6 +512,26 @@ Examples:
 /hive https://github.com/microsoft --all-issues --concurrency 3
 ```
 
+#### `/merge` — Слияние готовых Pull Request
+
+```
+/merge <repository-url|issue-url|pull-request-url> [--auto-resolve]
+
+Examples:
+/merge https://github.com/owner/repo
+/merge https://github.com/owner/repo/issues/123
+/merge https://github.com/owner/repo/pull/456
+```
+
+Цель-репозиторий обрабатывает PR с меткой `ready` последовательно. Цели issue и
+pull request обрабатывают только связанный или выбранный PR. Также можно ответить
+командой `/merge` на сообщение с одной ссылкой на GitHub repository, issue или
+pull request, например на предыдущую команду `/codex ...issues/123`.
+
+Если целевой PR ещё не завершён, `/merge` ждёт, пока он станет mergeable, и затем
+выполняет слияние. Пропуск конфликтов слияния по-прежнему работает с
+`--auto-resolve`.
+
 #### `/limits` — Показать лимиты использования
 
 ```

package/README.zh.md

@@ -508,6 +508,25 @@ Examples:
 /hive https://github.com/microsoft --all-issues --concurrency 3
 ```
 
+#### `/merge` - 合并就绪的 Pull Request
+
+```
+/merge <repository-url|issue-url|pull-request-url> [--auto-resolve]
+
+Examples:
+/merge https://github.com/owner/repo
+/merge https://github.com/owner/repo/issues/123
+/merge https://github.com/owner/repo/pull/456
+```
+
+仓库目标会按顺序处理带有 `ready` 标签的 PR。Issue 和 Pull Request
+目标只处理关联或指定的 PR。你也可以回复一条包含单个 GitHub
+仓库、Issue 或 Pull Request 链接的消息并发送 `/merge`，例如之前的
+`/codex ...issues/123` 命令。
+
+如果目标 PR 尚未完成，`/merge` 会等待它变为可合并后再合并。合并冲突跳过仍可配合
+`--auto-resolve` 使用。
+
 #### `/limits` - 显示用量限制
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/github-merge-targets.lib.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * GitHub merge target helpers for `/merge`.
+ *
+ * Repository-wide merge queues still use github-merge.lib.mjs. This module
+ * handles the narrower targets introduced in issue #2013: a single PR URL, an
+ * issue URL with linked PRs, or a GitHub URL found in a replied message.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2013
+ */
+
+import { promisify } from 'node:util';
+import { exec as execCallback } from 'node:child_process';
+
+import { githubLimits } from './config.lib.mjs';
+import { parseGitHubUrl } from './github.lib.mjs';
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
+import { getLinkedPRsFromTimeline } from './github-merge-ready-sync.lib.mjs';
+
+const execRaw = promisify(execCallback);
+const exec = (cmd, opts = {}) =>
+  ghWithRateLimitRetry(() => execRaw(cmd, { maxBuffer: githubLimits.bufferMaxSize, ...opts }), {
+    label: `gh exec (${cmd.split(/\s+/).slice(0, 3).join(' ')})`,
+  });
+
+const SUPPORTED_REPOSITORY_TYPES = new Set(['repo', 'issues_list', 'pulls_list']);
+const SUPPORTED_TARGET_TYPES = new Set([...SUPPORTED_REPOSITORY_TYPES, 'issue', 'pull']);
+
+function buildIssueUrl(owner, repo, issueNumber) {
+  return `https://github.com/${owner}/${repo}/issues/${issueNumber}`;
+}
+
+function buildPullUrl(owner, repo, prNumber) {
+  return `https://github.com/${owner}/${repo}/pull/${prNumber}`;
+}
+
+/**
+ * Parse a `/merge` target URL.
+ *
+ * @param {string} url
+ * @returns {{valid: boolean, mode?: 'repository'|'issue'|'pull', owner: string|null, repo: string|null, issueNumber?: number, prNumber?: number, url?: string, error: string|null}}
+ */
+export function parseMergeTargetUrl(url) {
+  const parsed = parseGitHubUrl(url);
+
+  if (!parsed.valid) {
+    return { valid: false, owner: null, repo: null, error: parsed.error };
+  }
+
+  if (SUPPORTED_REPOSITORY_TYPES.has(parsed.type)) {
+    return {
+      valid: true,
+      mode: 'repository',
+      owner: parsed.owner,
+      repo: parsed.repo,
+      url: `https://github.com/${parsed.owner}/${parsed.repo}`,
+      error: null,
+    };
+  }
+
+  if (parsed.type === 'issue') {
+    return {
+      valid: true,
+      mode: 'issue',
+      owner: parsed.owner,
+      repo: parsed.repo,
+      issueNumber: parsed.number,
+      url: buildIssueUrl(parsed.owner, parsed.repo, parsed.number),
+      error: null,
+    };
+  }
+
+  if (parsed.type === 'pull') {
+    return {
+      valid: true,
+      mode: 'pull',
+      owner: parsed.owner,
+      repo: parsed.repo,
+      prNumber: parsed.number,
+      url: buildPullUrl(parsed.owner, parsed.repo, parsed.number),
+      error: null,
+    };
+  }
+
+  if (parsed.type === 'user' || parsed.type === 'organization') {
+    return {
+      valid: false,
+      owner: parsed.owner,
+      repo: null,
+      error: 'URL points to a user/organization. Please provide a repository, issue, or pull request URL.',
+    };
+  }
+
+  return {
+    valid: false,
+    owner: parsed.owner || null,
+    repo: parsed.repo || null,
+    error: `URL type '${parsed.type}' is not supported for /merge. Please provide a repository, issue, or pull request URL.`,
+  };
+}
+
+function trimCandidateUrl(candidate) {
+  return String(candidate || '')
+    .trim()
+    .replace(/^[<([{'"]+/, '')
+    .replace(/[>)\]}'".,;:!?]+$/, '');
+}
+
+/**
+ * Extract a single `/merge` target URL from arbitrary text, such as a replied
+ * `/codex https://github.com/owner/repo/issues/123 --think max` message.
+ *
+ * @param {string} text
+ * @returns {{valid: boolean, url: string|null, target: Object|null, error: string|null}}
+ */
+export function extractMergeTargetUrlFromText(text) {
+  if (!text || typeof text !== 'string') {
+    return { valid: false, url: null, target: null, error: 'No text to inspect for GitHub links' };
+  }
+
+  const pattern = /(?:https?:\/\/)?github\.com\/[^\s<>)\]]+|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/(?:issues|pull)\/\d+/g;
+  const matches = text.match(pattern) || [];
+  const targetsByUrl = new Map();
+
+  for (const match of matches) {
+    const candidate = trimCandidateUrl(match);
+    const target = parseMergeTargetUrl(candidate);
+    if (target.valid && SUPPORTED_TARGET_TYPES.has(target.mode === 'repository' ? 'repo' : target.mode)) {
+      targetsByUrl.set(target.url, target);
+    }
+  }
+
+  const targets = [...targetsByUrl.values()];
+  if (targets.length === 0) {
+    return { valid: false, url: null, target: null, error: 'No GitHub repository, issue, or pull request link found' };
+  }
+  if (targets.length > 1) {
+    return { valid: false, url: null, target: null, error: `Expected one GitHub merge target, found ${targets.length}` };
+  }
+
+  const [target] = targets;
+  return { valid: true, url: target.url, target, error: null };
+}
+
+/**
+ * Fetch a PR in the shape expected by MergeQueueItem.
+ *
+ * @param {string} owner
+ * @param {string} repo
+ * @param {number} prNumber
+ * @param {Object|null} issue
+ * @param {boolean} verbose
+ * @returns {Promise<{pr: Object, issue: Object|null, sortDate: Date}>}
+ */
+export async function fetchMergeTargetPullRequest(owner, repo, prNumber, issue = null, verbose = false) {
+  const { stdout } = await exec(`gh pr view ${prNumber} --repo ${owner}/${repo} --json number,title,url,createdAt,headRefName,author,mergeable,mergeStateStatus,isDraft,state`);
+  const pr = JSON.parse(stdout.trim());
+  if (verbose) {
+    console.log(`[VERBOSE] /merge: Loaded target PR #${pr.number} from ${owner}/${repo}`);
+  }
+  return {
+    pr,
+    issue,
+    sortDate: new Date(pr.createdAt),
+  };
+}
+
+/**
+ * Resolve a non-repository merge target into queue item data.
+ *
+ * @param {{mode: string, owner: string, repo: string, issueNumber?: number, prNumber?: number, url?: string}} target
+ * @param {boolean} verbose
+ * @returns {Promise<Array<{pr: Object, issue: Object|null, sortDate: Date}>|null>}
+ */
+export async function resolveMergeTargetItems(target, verbose = false) {
+  if (!target || target.mode === 'repository') {
+    return null;
+  }
+
+  if (target.mode === 'pull') {
+    return [await fetchMergeTargetPullRequest(target.owner, target.repo, target.prNumber, null, verbose)];
+  }
+
+  if (target.mode === 'issue') {
+    const issue = {
+      number: target.issueNumber,
+      url: target.url || buildIssueUrl(target.owner, target.repo, target.issueNumber),
+    };
+    const linkedPRs = await getLinkedPRsFromTimeline(target.owner, target.repo, target.issueNumber, verbose);
+    const items = [];
+    for (const linkedPR of linkedPRs) {
+      items.push(await fetchMergeTargetPullRequest(target.owner, target.repo, linkedPR.number, issue, verbose));
+    }
+    return items.sort((a, b) => a.sortDate - b.sortDate);
+  }
+
+  throw new Error(`Unsupported merge target mode: ${target.mode}`);
+}
+
+export default {
+  parseMergeTargetUrl,
+  extractMergeTargetUrlFromText,
+  fetchMergeTargetPullRequest,
+  resolveMergeTargetItems,
+};

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

@@ -18,7 +18,8 @@
  * @see https://github.com/link-assistant/hive-mind/issues/1143
  */
 
-import { parseRepositoryUrl, checkLabelPermissions, ensureReadyLabel } from './github-merge.lib.mjs';
+import { checkLabelPermissions, ensureReadyLabel } from './github-merge.lib.mjs';
+import { extractMergeTargetUrlFromText, parseMergeTargetUrl } from './github-merge-targets.lib.mjs';
 import { createMergeQueueProcessor, MergeStatus, MERGE_QUEUE_CONFIG } from './telegram-merge-queue.lib.mjs';
 import { executeStartScreen } from './telegram-command-execution.lib.mjs';
 
@@ -129,6 +130,81 @@ export function parseMergeArgs(args) {
   return { positionals, flags };
 }
 
+/**
+ * A real user reply can carry the issue/PR URL for `/merge`; forwarded
+ * commands still must not be replayed by the bot.
+ *
+ * @param {Object} ctx - Telegraf context
+ * @param {Object} filters - Message filter callbacks
+ * @returns {boolean}
+ */
+export function shouldIgnoreMergeCommand(ctx, filters = {}) {
+  if (filters.isOldMessage && filters.isOldMessage(ctx)) {
+    return true;
+  }
+  if (typeof filters.isForwarded === 'function') {
+    return filters.isForwarded(ctx);
+  }
+  if (typeof filters.isForwardedOrReply === 'function') {
+    return filters.isForwardedOrReply(ctx);
+  }
+  return false;
+}
+
+function getMergeReplyText(message) {
+  const reply = message?.reply_to_message;
+  if (!reply || reply.forum_topic_created) {
+    return '';
+  }
+  return reply.text || reply.caption || '';
+}
+
+function getMergeUsageMessage() {
+  return "Missing merge target\\.\n\nUsage: `/merge <repository-url|issue-url|pull-request-url> [--auto-resolve]`\n\nYou can also reply with `/merge` to a message containing one GitHub repository, issue, or pull request link\\.\n\nExamples:\n`/merge https://github.com/owner/repo`\n`/merge https://github.com/owner/repo/issues/123`\n`/merge https://github.com/owner/repo/pull/456`\n\nRepository targets merge all PRs with the 'ready' label\\. Issue and pull request targets wait until the target PR is mergeable, then merge it\\.\n\nWith `--auto-resolve` the bot also dispatches `/solve <pr> --auto-merge` for every PR that was skipped because of merge conflicts\\.";
+}
+
+function getTargetFoundText(target, count) {
+  if (target.mode === 'repository') {
+    return `Found ${count} PRs with 'ready' label\\.`;
+  }
+  const plural = count === 1 ? '' : 's';
+  return `Found ${count} target PR${plural} to merge\\.`;
+}
+
+/**
+ * Resolve the merge target from explicit args, or from a replied message when
+ * `/merge` is sent without a URL.
+ *
+ * @param {string[]} positionals
+ * @param {Object} message
+ * @returns {{target: Object|null, targetUrl: string|null, fromReply: boolean, error: string|null}}
+ */
+export function resolveMergeCommandTarget(positionals, message) {
+  if (positionals.length > 0) {
+    const targetUrl = positionals[0];
+    const target = parseMergeTargetUrl(targetUrl);
+    return {
+      target,
+      targetUrl,
+      fromReply: false,
+      error: target.valid ? null : target.error,
+    };
+  }
+
+  const replyText = getMergeReplyText(message);
+  if (!replyText) {
+    return { target: null, targetUrl: null, fromReply: false, error: null };
+  }
+
+  const extracted = extractMergeTargetUrlFromText(replyText);
+  return {
+    target: extracted.target,
+    targetUrl: extracted.url,
+    fromReply: true,
+    error: extracted.valid ? null : extracted.error,
+  };
+}
+
 /**
  * Issue #1805: Spawner used by the merge queue's auto-resolve pass. For each
  * skipped PR we dispatch a `solve <pr-url> --auto-merge` session through
@@ -209,7 +285,7 @@ function formatUserError(error, verbose) {
  * @param {Function} [options.getStoppedChatRejectMessage] - Function to get stopped chat rejection message
  */
 export function registerMergeCommand(bot, options) {
-  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, isChatStopped, getStoppedChatRejectMessage } = options;
+  const { VERBOSE = false, isOldMessage, isForwarded, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, isChatStopped, getStoppedChatRejectMessage } = options;
 
   bot.command(/^merge$/i, async ctx => {
     VERBOSE && console.log('[VERBOSE] /merge command received');
@@ -222,7 +298,7 @@ export function registerMergeCommand(bot, options) {
     });
 
     // Standard checks
-    if (isOldMessage(ctx) || isForwardedOrReply(ctx)) return;
+    if (shouldIgnoreMergeCommand(ctx, { isOldMessage, isForwarded, isForwardedOrReply })) return;
 
     if (!isGroupChat(ctx)) {
       return await ctx.reply('The /merge command only works in group chats. Please add this bot to a group and make it an admin.', {
@@ -252,24 +328,25 @@ export function registerMergeCommand(bot, options) {
     const { positionals, flags } = parseMergeArgs(args);
     const autoResolve = flags['auto-resolve'] === true;
 
-    if (positionals.length === 0) {
-      return await ctx.reply("Missing repository URL\\.\n\nUsage: `/merge <repository-url> [--auto-resolve]`\n\nExample: `/merge https://github.com/owner/repo`\n\nThis will merge all PRs with the 'ready' label, one by one, waiting for CI/CD between each merge\\.\n\nWith `--auto-resolve` the bot also dispatches `/solve <pr> --auto-merge` for every PR that was skipped because of merge conflicts\\.", { parse_mode: 'MarkdownV2', reply_to_message_id: ctx.message.message_id });
-    }
+    const targetResult = resolveMergeCommandTarget(positionals, ctx.message);
 
-    // Parse and validate repository URL
-    const repoUrl = positionals[0];
-    const parsedUrl = parseRepositoryUrl(repoUrl);
+    if (!targetResult.target && !targetResult.error) {
+      return await ctx.reply(getMergeUsageMessage(), { parse_mode: 'MarkdownV2', reply_to_message_id: ctx.message.message_id });
+    }
 
-    if (!parsedUrl.valid) {
-      return await ctx.reply(`Invalid repository URL: ${escapeMarkdownV2(parsedUrl.error)}\n\nPlease provide a valid GitHub repository URL\\.`, {
+    if (!targetResult.target || !targetResult.target.valid) {
+      const invalidPrefix = targetResult.fromReply ? 'Invalid merge target in replied message' : 'Invalid merge target';
+      return await ctx.reply(`${invalidPrefix}: ${escapeMarkdownV2(targetResult.error || targetResult.target?.error || 'Unknown target error')}\n\nPlease provide a valid GitHub repository, issue, or pull request URL\\.`, {
         parse_mode: 'MarkdownV2',
         reply_to_message_id: ctx.message.message_id,
       });
     }
 
-    const { owner, repo } = parsedUrl;
+    const target = targetResult.target;
+    const targetUrl = targetResult.targetUrl || target.url;
+    const { owner, repo } = target;
     const repoKey = getRepoKey(owner, repo);
-    VERBOSE && console.log(`[VERBOSE] /merge: Processing repository ${owner}/${repo}`);
+    VERBOSE && console.log(`[VERBOSE] /merge: Processing ${target.mode} target ${targetUrl} in ${owner}/${repo}`);
 
     // Check if a merge operation is already running for this repository (per-repository concurrency)
     if (activeMergeOperations.has(repoKey)) {
@@ -310,6 +387,7 @@ export function registerMergeCommand(bot, options) {
       // Create the merge queue processor
       const processor = await createMergeQueueProcessor(owner, repo, {
         verbose: VERBOSE,
+        target,
         // Issue #1805: forward the --auto-resolve flag and inject the spawner.
         // The processor only sees the callback, so unit tests can stub it
         // without spawning real screen sessions.
@@ -384,14 +462,14 @@ export function registerMergeCommand(bot, options) {
 
       if (initResult.message) {
         // No PRs to merge
-        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${escapeMarkdownV2(initResult.message)}\n\nTo use the merge queue:\n1\\. Add the \`ready\` label to PRs you want to merge\n2\\. Run \`/merge ${escapeMarkdownV2(repoUrl)}\` again`, { parse_mode: 'MarkdownV2' });
+        await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${escapeMarkdownV2(initResult.message)}\n\nTo use the merge queue:\n1\\. Add the \`ready\` label to repository PRs, or ensure the issue has a linked open PR\n2\\. Run \`/merge ${escapeMarkdownV2(targetUrl)}\` again`, { parse_mode: 'MarkdownV2' });
         return;
       }
 
       // Update message with PR list and cancel button, start processing
       const truncatedMsg = initResult.truncated ? `\n\n_Note: Only processing first ${MERGE_QUEUE_CONFIG.MAX_PRS_PER_SESSION} PRs_` : '';
 
-      await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\nFound ${initResult.count} PRs with 'ready' label\\.${escapeMarkdownV2(truncatedMsg)}\n\nStarting merge process\\.\\.\\.`, {
+      await ctx.telegram.editMessageText(statusMessage.chat.id, statusMessage.message_id, undefined, `*Merge Queue \\- ${escapeMarkdownV2(owner)}/${escapeMarkdownV2(repo)}*${labelMsg}\n\n${getTargetFoundText(target, initResult.count)}${escapeMarkdownV2(truncatedMsg)}\n\nStarting merge process\\.\\.\\.`, {
         parse_mode: 'MarkdownV2',
         reply_markup: {
           inline_keyboard: [[{ text: '🛑 Cancel', callback_data: `merge_cancel_${repoKey}` }]],

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

@@ -17,6 +17,8 @@
  */
 
 import { getAllReadyPRs, checkPRCIStatus, checkPRMergeable, mergePullRequest, waitForCI, ensureReadyLabel, waitForBranchCI, getDefaultBranch, waitForCommitCI, checkBranchCIHealth, getMergeCommitSha, getPRStatus, syncReadyTags, closeLinkedIssueIfNotAutoClosed } from './github-merge.lib.mjs';
+import { resolveMergeTargetItems } from './github-merge-targets.lib.mjs';
+import { waitForPRReady as waitForPRReadyHelper } from './telegram-merge-wait.lib.mjs';
 import { mergeQueue as mergeQueueConfig } from './config.lib.mjs';
 import { getProgressBar } from './limits.lib.mjs';
 
@@ -38,6 +40,7 @@ export const MergeStatus = {
 export const MergeItemStatus = {
   PENDING: 'pending',
   CHECKING_CI: 'checking_ci',
+  WAITING_READY: 'waiting_ready',
   WAITING_CI: 'waiting_ci',
   READY_TO_MERGE: 'ready_to_merge',
   MERGING: 'merging',
@@ -144,6 +147,8 @@ class MergeQueueItem {
         return '⏳';
       case MergeItemStatus.CHECKING_CI:
         return '🔍';
+      case MergeItemStatus.WAITING_READY:
+        return '⏱️';
       case MergeItemStatus.WAITING_CI:
         return '⏱️';
       case MergeItemStatus.READY_TO_MERGE:
@@ -185,6 +190,8 @@ export class MergeQueueProcessor {
     // tests can run without touching the screen runtime.
     this.autoResolve = options.autoResolve === true;
     this.spawnSolveSession = typeof options.spawnSolveSession === 'function' ? options.spawnSolveSession : null;
+    this.target = options.target || { mode: 'repository', owner: this.owner, repo: this.repo, url: `https://github.com/${this.owner}/${this.repo}` };
+    this.waitForUnfinished = options.waitForUnfinished !== false;
 
     // State
     this.items = [];
@@ -208,6 +215,17 @@ export class MergeQueueProcessor {
     this.getPRStatus = typeof options.getPRStatus === 'function' ? options.getPRStatus : getPRStatus;
     // Same idea for `getMergeCommitSha` so tests don't need to stub gh.
     this.getMergeCommitSha = typeof options.getMergeCommitSha === 'function' ? options.getMergeCommitSha : getMergeCommitSha;
+    this.checkPRMergeable = typeof options.checkPRMergeable === 'function' ? options.checkPRMergeable : checkPRMergeable;
+    this.checkPRCIStatus = typeof options.checkPRCIStatus === 'function' ? options.checkPRCIStatus : checkPRCIStatus;
+    this.waitForCI = typeof options.waitForCI === 'function' ? options.waitForCI : waitForCI;
+    this.mergePullRequest = typeof options.mergePullRequest === 'function' ? options.mergePullRequest : mergePullRequest;
+    this.closeLinkedIssueIfNotAutoClosed = typeof options.closeLinkedIssueIfNotAutoClosed === 'function' ? options.closeLinkedIssueIfNotAutoClosed : closeLinkedIssueIfNotAutoClosed;
+    this.resolveMergeTargetItems = typeof options.resolveMergeTargetItems === 'function' ? options.resolveMergeTargetItems : resolveMergeTargetItems;
+    this.ensureReadyLabel = typeof options.ensureReadyLabel === 'function' ? options.ensureReadyLabel : ensureReadyLabel;
+    this.syncReadyTags = typeof options.syncReadyTags === 'function' ? options.syncReadyTags : syncReadyTags;
+    this.getAllReadyPRs = typeof options.getAllReadyPRs === 'function' ? options.getAllReadyPRs : getAllReadyPRs;
+    this.targetItemsTimeoutMs = options.targetItemsTimeoutMs ?? MERGE_QUEUE_CONFIG.CI_TIMEOUT_MS;
+    this.targetItemsPollIntervalMs = options.targetItemsPollIntervalMs ?? MERGE_QUEUE_CONFIG.CI_POLL_INTERVAL_MS;
 
     // Statistics
     this.stats = {
@@ -241,7 +259,7 @@ export class MergeQueueProcessor {
       this.log(`Initializing merge queue for ${this.owner}/${this.repo}`);
 
       // Ensure ready label exists
-      const labelResult = await ensureReadyLabel(this.owner, this.repo, this.verbose);
+      const labelResult = await this.ensureReadyLabel(this.owner, this.repo, this.verbose);
       if (!labelResult.success) {
         return { success: false, error: labelResult.error };
       }
@@ -249,21 +267,27 @@ export class MergeQueueProcessor {
         this.log("Created 'ready' label in repository");
       }
 
-      // Issue #1367: Sync 'ready' tags between linked PRs and issues before collecting the queue
-      // This ensures the final list reflects all ready work regardless of where the tag was applied
-      const syncResult = await syncReadyTags(this.owner, this.repo, this.verbose);
-      if (syncResult.synced > 0) {
-        this.log(`Synced 'ready' tag: ${syncResult.synced} item(s) updated`);
-      }
-      if (syncResult.errors > 0) {
-        this.log(`Tag sync had ${syncResult.errors} error(s) (non-fatal, proceeding)`);
-      }
+      let readyPRs;
+      if (this.target?.mode && this.target.mode !== 'repository') {
+        readyPRs = await this.resolveMergeTargetItemsWithWait();
+      } else {
+        // Issue #1367: Sync 'ready' tags between linked PRs and issues before collecting the queue
+        // This ensures the final list reflects all ready work regardless of where the tag was applied
+        const syncResult = await this.syncReadyTags(this.owner, this.repo, this.verbose);
+        if (syncResult.synced > 0) {
+          this.log(`Synced 'ready' tag: ${syncResult.synced} item(s) updated`);
+        }
+        if (syncResult.errors > 0) {
+          this.log(`Tag sync had ${syncResult.errors} error(s) (non-fatal, proceeding)`);
+        }
 
-      // Fetch all ready PRs
-      const readyPRs = await getAllReadyPRs(this.owner, this.repo, this.verbose);
+        // Fetch all ready PRs
+        readyPRs = await this.getAllReadyPRs(this.owner, this.repo, this.verbose);
+      }
 
       if (readyPRs.length === 0) {
-        return { success: true, error: null, message: "No PRs with 'ready' label found" };
+        const message = this.target?.mode === 'issue' ? `No open PRs linked to issue #${this.target.issueNumber} found` : this.target?.mode === 'pull' ? `Pull request #${this.target.prNumber} was not found` : "No PRs with 'ready' label found";
+        return { success: true, error: null, message };
       }
 
       // Limit to max PRs per session
@@ -279,6 +303,7 @@ export class MergeQueueProcessor {
         success: true,
         error: null,
         count: this.items.length,
+        targetMode: this.target?.mode || 'repository',
         truncated: readyPRs.length > MERGE_QUEUE_CONFIG.MAX_PRS_PER_SESSION,
       };
     } catch (error) {
@@ -419,6 +444,46 @@ export class MergeQueueProcessor {
     }
   }
 
+  /**
+   * Resolve targeted PR data, waiting for issue-linked PRs that may be created
+   * shortly after a replied `/codex <issue>` message.
+   *
+   * @returns {Promise<Array<{pr: Object, issue: Object|null, sortDate: Date}>>}
+   */
+  async resolveMergeTargetItemsWithWait() {
+    const maxPollInterval = Math.max(1, this.targetItemsPollIntervalMs || 1);
+    const maxAttempts = Math.max(1, Math.ceil((this.targetItemsTimeoutMs || 0) / maxPollInterval));
+
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+      if (this.isCancelled) {
+        return [];
+      }
+
+      const items = (await this.resolveMergeTargetItems(this.target, this.verbose)) || [];
+      if (items.length > 0 || this.target?.mode !== 'issue') {
+        return items;
+      }
+
+      if (attempt === maxAttempts) {
+        return [];
+      }
+
+      this.log(`Waiting for a linked PR to appear for issue #${this.target.issueNumber}`);
+      await this.sleep(this.targetItemsPollIntervalMs);
+    }
+
+    return [];
+  }
+
+  async waitForPRReady(item, initialCheck) {
+    return waitForPRReadyHelper(this, item, initialCheck, {
+      MergeItemStatus,
+      conflictSkipReason: MERGE_CONFLICT_SKIP_REASON,
+      timeoutMs: MERGE_QUEUE_CONFIG.CI_TIMEOUT_MS,
+      pollIntervalMs: MERGE_QUEUE_CONFIG.CI_POLL_INTERVAL_MS,
+    });
+  }
+
   /**
    * Process a single merge queue item
    * @param {MergeQueueItem} item
@@ -430,7 +495,7 @@ export class MergeQueueProcessor {
     try {
       // Step 1: Check if PR is mergeable
       item.status = MergeItemStatus.CHECKING_CI;
-      const mergeableCheck = await checkPRMergeable(this.owner, this.repo, item.pr.number, this.verbose);
+      const mergeableCheck = await this.checkPRMergeable(this.owner, this.repo, item.pr.number, this.verbose);
 
       if (mergeableCheck.terminal) {
         item.status = MergeItemStatus.FAILED;
@@ -441,15 +506,34 @@ export class MergeQueueProcessor {
       }
 
       if (!mergeableCheck.mergeable) {
-        item.status = MergeItemStatus.SKIPPED;
-        item.error = mergeableCheck.reason;
-        this.stats.skipped++;
-        this.log(`Skipped PR #${item.pr.number}: ${mergeableCheck.reason}`);
-        return;
+        if (!this.waitForUnfinished || mergeableCheck.reason === MERGE_CONFLICT_SKIP_REASON) {
+          item.status = MergeItemStatus.SKIPPED;
+          item.error = mergeableCheck.reason;
+          this.stats.skipped++;
+          this.log(`Skipped PR #${item.pr.number}: ${mergeableCheck.reason}`);
+          return;
+        }
+
+        const waitForReadyResult = await this.waitForPRReady(item, mergeableCheck);
+        if (!waitForReadyResult.success) {
+          if (waitForReadyResult.status === 'cancelled' || waitForReadyResult.status === 'conflict') {
+            item.status = MergeItemStatus.SKIPPED;
+            item.error = waitForReadyResult.error;
+            this.stats.skipped++;
+            this.log(`Skipped PR #${item.pr.number}: ${waitForReadyResult.error}`);
+            return;
+          }
+
+          item.status = MergeItemStatus.FAILED;
+          item.error = waitForReadyResult.error;
+          this.stats.failed++;
+          this.log(`Failed PR #${item.pr.number}: ${waitForReadyResult.error}`);
+          return;
+        }
       }
 
       // Step 2: Check CI status
-      const ciStatus = await checkPRCIStatus(this.owner, this.repo, item.pr.number, this.verbose);
+      const ciStatus = await this.checkPRCIStatus(this.owner, this.repo, item.pr.number, this.verbose);
       item.ciStatus = ciStatus;
 
       if (ciStatus.status === 'failure') {
@@ -472,7 +556,7 @@ export class MergeQueueProcessor {
       if (ciStatus.status === 'pending') {
         item.status = MergeItemStatus.WAITING_CI;
 
-        const waitResult = await waitForCI(
+        const waitResult = await this.waitForCI(
           this.owner,
           this.repo,
           item.pr.number,
@@ -512,7 +596,7 @@ export class MergeQueueProcessor {
       // Step 4: Merge the PR
       // Issue #1269: Pass the configured merge method to prevent "not running interactively" error
       item.status = MergeItemStatus.MERGING;
-      const mergeResult = await mergePullRequest(this.owner, this.repo, item.pr.number, { mergeMethod: MERGE_QUEUE_CONFIG.MERGE_METHOD }, this.verbose);
+      const mergeResult = await this.mergePullRequest(this.owner, this.repo, item.pr.number, { mergeMethod: MERGE_QUEUE_CONFIG.MERGE_METHOD }, this.verbose);
 
       if (!mergeResult.success) {
         item.status = MergeItemStatus.FAILED;
@@ -531,7 +615,7 @@ export class MergeQueueProcessor {
       // Issue #1895: GitHub does not auto-close linked issues for PRs merged into
       // a non-default branch. Close the linked issue explicitly in that case.
       try {
-        const closeResult = await closeLinkedIssueIfNotAutoClosed(this.owner, this.repo, item.pr.number, this.verbose);
+        const closeResult = await this.closeLinkedIssueIfNotAutoClosed(this.owner, this.repo, item.pr.number, this.verbose);
         if (closeResult.closed) {
           this.log(`Closed linked issue #${closeResult.issueNumber} for PR #${item.pr.number} (merged into non-default branch)`);
         }
@@ -542,7 +626,7 @@ export class MergeQueueProcessor {
       // Issue #1341: Get the merge commit SHA for post-merge CI tracking
       // Need a small delay to allow GitHub to update the PR state
       await this.sleep(5000);
-      const mergeCommitResult = await getMergeCommitSha(this.owner, this.repo, item.pr.number, this.verbose);
+      const mergeCommitResult = await this.getMergeCommitSha(this.owner, this.repo, item.pr.number, this.verbose);
       if (mergeCommitResult.sha) {
         item.mergeCommitSha = mergeCommitResult.sha;
         this.log(`PR #${item.pr.number} merge commit: ${mergeCommitResult.sha.substring(0, 7)}`);

package/src/telegram-merge-wait.lib.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Wait helpers for Telegram merge queue.
+ *
+ * Split from telegram-merge-queue.lib.mjs to keep that file under the
+ * repository line limit.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2013
+ */
+
+/**
+ * Wait for an unfinished PR to become mergeable before CI/merge processing.
+ *
+ * @param {Object} processor - MergeQueueProcessor-like object
+ * @param {Object} item - Merge queue item
+ * @param {{mergeable: boolean, terminal?: boolean, reason?: string}} initialCheck
+ * @param {Object} options
+ * @param {Object} options.MergeItemStatus
+ * @param {string} options.conflictSkipReason
+ * @param {number} options.timeoutMs
+ * @param {number} options.pollIntervalMs
+ * @returns {Promise<{success: boolean, status: string, error: string|null}>}
+ */
+export async function waitForPRReady(processor, item, initialCheck, options) {
+  const { MergeItemStatus, conflictSkipReason, timeoutMs, pollIntervalMs } = options;
+  const startedAt = Date.now();
+  let latestCheck = initialCheck;
+
+  while (true) {
+    if (processor.isCancelled) {
+      return { success: false, status: 'cancelled', error: 'Cancelled' };
+    }
+
+    if (latestCheck?.terminal) {
+      return {
+        success: false,
+        status: 'terminal',
+        error: latestCheck.reason || 'GitHub repository, pull request, issue, or branch is no longer accessible',
+      };
+    }
+
+    if (latestCheck?.mergeable) {
+      item.status = MergeItemStatus.CHECKING_CI;
+      item.error = null;
+      return { success: true, status: 'ready', error: null };
+    }
+
+    if (latestCheck?.reason === conflictSkipReason) {
+      return { success: false, status: 'conflict', error: conflictSkipReason };
+    }
+
+    if (Date.now() - startedAt >= timeoutMs) {
+      const reason = latestCheck?.reason || 'PR did not become mergeable';
+      return {
+        success: false,
+        status: 'timeout',
+        error: `Timed out waiting for PR #${item.pr.number} to become mergeable: ${reason}`,
+      };
+    }
+
+    item.status = MergeItemStatus.WAITING_READY;
+    item.error = latestCheck?.reason || 'Waiting for PR to become mergeable';
+    processor.log(`Waiting for PR #${item.pr.number} to become mergeable: ${item.error}`);
+    if (processor.onProgress) {
+      await processor.onProgress(processor.getProgressUpdate());
+    }
+
+    await processor.sleep(pollIntervalMs);
+    latestCheck = await processor.checkPRMergeable(processor.owner, processor.repo, item.pr.number, processor.verbose);
+  }
+}
+
+export default {
+  waitForPRReady,
+};