@link-assistant/hive-mind 1.69.18 → 1.71.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @link-assistant/hive-mind
 
+## 1.71.0
+
+### Minor Changes
+
+- aacdb06: Make the `--tool gemini` integration produce meaningful JSON output and reach
+  feature parity with `--tool claude` / `--tool codex`. Resolves #1809.
+  - The wrapper now feeds the prompt to gemini-cli through `command-stream`'s
+    `stdin` option instead of `cat <prompt-file> | gemini`, so the upstream
+    non-zero exit code is no longer swallowed by the pipeline.
+  - A new `detectGeminiPlainTextError` helper surfaces gemini-cli's plain-text
+    failures (auth required, quota exceeded, invalid model, unknown argument,
+    fatal error) as structured wrapper errors so headless callers stop seeing
+    silent `success: true` runs when authentication is missing. Tracked upstream
+    in [`google-gemini/gemini-cli`'s `validateNonInteractiveAuth`](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/validateNonInterActiveAuth.ts);
+    see `docs/case-studies/issue-1809/upstream-issue-draft.md` for the proposed
+    upstream fix.
+  - A run that emits zero `init`/`message`/`tool_use`/`result` JSONL events is
+    now classified as a failure regardless of exit code, so empty runs cannot be
+    reported as success anymore.
+  - New optional flags wired through to gemini-cli: `--gemini-sandbox`
+    (`--sandbox`), `--gemini-extensions` (`--extensions`),
+    `--gemini-include-directories` (`--include-directories`, in addition to
+    `tempDir`/`workspaceTmpDir` which are always included), and
+    `--gemini-allowed-mcp-servers` (`--allowed-mcp-server-names`). `--verbose`
+    now also toggles gemini-cli's own `--debug` flag.
+  - New tests in `tests/test-gemini-support.mjs` lock in plain-text auth-error
+    surfacing, zero-event failure detection, and the verbose/include-directories
+    argv plumbing.
+  - Case study published in `docs/case-studies/issue-1809/`.
+
+## 1.70.0
+
+### Minor Changes
+
+- 35dc089: Add `--auto-resolve` to the `/merge` Telegram command. After the normal queue finishes, the bot now iterates every PR that was skipped because of merge conflicts and dispatches a `solve <pr-url> --auto-merge` session through `start-screen` — the same path other commands use — so conflict resolution runs with the default `sonnet` model and the PR is merged once the session finishes. Each PR/issue reference in the `/merge` progress and final messages is now rendered as a clickable MarkdownV2 link to the actual pull request or issue. Resolves #1805.
+
 ## 1.69.18
 
 ### Patch Changes

package/package.json

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

package/src/gemini.lib.mjs

@@ -8,9 +8,6 @@ if (typeof globalThis.use === 'undefined') {
 }
 
 const { $ } = await use('command-stream');
-const fs = (await use('fs')).promises;
-const path = (await use('path')).default;
-const os = (await use('os')).default;
 
 import { log } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';
@@ -24,6 +21,80 @@ import { getCumulativeContextInputTokens, toTokenCount } from './context-fill.li
 
 const shellQuote = value => `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 
+// Patterns gemini-cli prints to stdout/stderr when no JSONL event can be emitted.
+// Issue #1809: validateNonInteractiveAuth in gemini-cli bypasses the structured
+// stream-json error path; we surface those plain-text failures ourselves until
+// the upstream fix lands. See docs/case-studies/issue-1809/upstream-issue-draft.md.
+const GEMINI_PLAIN_TEXT_ERROR_PATTERNS = [
+  { type: 'AuthenticationRequired', regex: /Please set an Auth method/i },
+  { type: 'AuthenticationRequired', regex: /authentication (?:failed|required)/i },
+  { type: 'AuthenticationRequired', regex: /invalid (?:api[_ ]?key|credentials)/i },
+  { type: 'QuotaExceeded', regex: /quota (?:exceeded|reached)/i },
+  { type: 'InvalidModel', regex: /(?:invalid|unknown) model/i },
+  { type: 'InvalidArgument', regex: /Unknown (?:argument|option)/i },
+  { type: 'FatalError', regex: /^Error:\s/m },
+];
+
+export const detectGeminiPlainTextError = text => {
+  if (!text || typeof text !== 'string') return null;
+  for (const { type, regex } of GEMINI_PLAIN_TEXT_ERROR_PATTERNS) {
+    const match = text.match(regex);
+    if (match) {
+      const line = (text.split(/\r?\n/).find(l => regex.test(l)) || match[0]).trim();
+      return { type, message: line };
+    }
+  }
+  return null;
+};
+
+// Issue #1809: Build the gemini-cli argument list once so verbose mode, includes,
+// sandbox, extensions and MCP allow-list can all be toggled by argv consistently.
+// Returns an array suitable for tagged-template interpolation through command-stream.
+export const buildGeminiArgs = (argv, mappedModel, options = {}) => {
+  const { tempDir, workspaceTmpDir } = options;
+  const args = ['--output-format', 'stream-json', '--model', mappedModel, '--approval-mode', 'yolo', '--skip-trust'];
+
+  if (argv?.verbose) args.push('--debug');
+
+  if (argv?.resume) {
+    args.unshift('--resume', String(argv.resume));
+  }
+
+  const includeDirs = [];
+  if (tempDir) includeDirs.push(tempDir);
+  if (workspaceTmpDir && workspaceTmpDir !== tempDir) includeDirs.push(workspaceTmpDir);
+  if (Array.isArray(argv?.geminiIncludeDirectories)) {
+    for (const dir of argv.geminiIncludeDirectories) if (dir) includeDirs.push(String(dir));
+  } else if (typeof argv?.geminiIncludeDirectories === 'string' && argv.geminiIncludeDirectories.trim()) {
+    includeDirs.push(
+      ...argv.geminiIncludeDirectories
+        .split(',')
+        .map(d => d.trim())
+        .filter(Boolean)
+    );
+  }
+  if (includeDirs.length > 0) {
+    args.push('--include-directories', includeDirs.join(','));
+  }
+
+  if (argv?.geminiSandbox) args.push('--sandbox');
+
+  const collectList = value => {
+    if (!value) return [];
+    if (Array.isArray(value)) return value.map(String).filter(Boolean);
+    return String(value)
+      .split(',')
+      .map(v => v.trim())
+      .filter(Boolean);
+  };
+  const extensions = collectList(argv?.geminiExtensions);
+  if (extensions.length) args.push('--extensions', extensions.join(','));
+  const allowedMcp = collectList(argv?.geminiAllowedMcpServers);
+  if (allowedMcp.length) args.push('--allowed-mcp-server-names', allowedMcp.join(','));
+
+  return args;
+};
+
 // Model mapping to translate aliases to full model IDs for Gemini.
 // Issue #1473: Uses centralized geminiModels from models/index.mjs.
 export const mapModelToId = model => {
@@ -304,6 +375,7 @@ export const executeGemini = async params => {
 
   return await executeGeminiCommand({
     tempDir,
+    workspaceTmpDir,
     branchName,
     prompt,
     systemPrompt,
@@ -321,7 +393,7 @@ export const executeGemini = async params => {
 };
 
 export const executeGeminiCommand = async params => {
-  const { tempDir, branchName, prompt, systemPrompt, argv, log, formatAligned, getResourceSnapshot, forkedRepo, feedbackLines, geminiPath, $, waitForRetryDelay = waitWithCountdown } = params;
+  const { tempDir, workspaceTmpDir, branchName, prompt, systemPrompt, argv, log, formatAligned, getResourceSnapshot, forkedRepo, feedbackLines, geminiPath, $, waitForRetryDelay = waitWithCountdown } = params;
 
   let retryCount = 0;
 
@@ -348,16 +420,15 @@ export const executeGeminiCommand = async params => {
 
     const mappedModel = mapModelToId(argv.model || defaultModels.gemini);
     const combinedPrompt = systemPrompt ? `${systemPrompt}\n\n${prompt}` : prompt;
-    const promptFile = path.join(os.tmpdir(), `gemini_prompt_${Date.now()}_${process.pid}.txt`);
-    await fs.writeFile(promptFile, combinedPrompt);
 
-    let geminiArgs = `--output-format stream-json --model ${shellQuote(mappedModel)} --approval-mode yolo --skip-trust`;
     if (argv.resume) {
       await log(`🔄 Resuming from Gemini session: ${argv.resume}`);
-      geminiArgs = `--resume ${shellQuote(argv.resume)} ${geminiArgs}`;
     }
 
-    const fullCommand = `(cd ${shellQuote(tempDir)} && cat ${shellQuote(promptFile)} | ${geminiPath} ${geminiArgs})`;
+    // Issue #1809: build args via shared helper so verbose/sandbox/include-dirs
+    // toggles stay consistent between the logged command and the real invocation.
+    const geminiArgList = buildGeminiArgs(argv, mappedModel, { tempDir, workspaceTmpDir });
+    const fullCommand = `(cd ${shellQuote(tempDir)} && ${geminiPath} ${geminiArgList.map(shellQuote).join(' ')} <<< <prompt>)`;
 
     await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
     await log(fullCommand);
@@ -370,17 +441,17 @@ export const executeGeminiCommand = async params => {
     let limitReached = false;
     let limitResetTime = null;
     let lastMessage = '';
+    let plainTextError = null;
 
     try {
-      const execCommand = argv.resume
-        ? $({
-            cwd: tempDir,
-            mirror: false,
-          })`cat ${promptFile} | ${geminiPath} --resume ${argv.resume} --output-format stream-json --model ${mappedModel} --approval-mode yolo --skip-trust`
-        : $({
-            cwd: tempDir,
-            mirror: false,
-          })`cat ${promptFile} | ${geminiPath} --output-format stream-json --model ${mappedModel} --approval-mode yolo --skip-trust`;
+      // Issue #1809: feed the prompt directly to gemini-cli stdin via command-stream
+      // instead of "cat <file> | gemini" — the pipeline form swallowed the upstream
+      // non-zero exit code (no pipefail) and yielded false success: true reports.
+      const execCommand = $({
+        cwd: tempDir,
+        stdin: combinedPrompt,
+        mirror: false,
+      })`${geminiPath} ${geminiArgList}`;
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);
       await log(formatAligned('📂', 'Working directory:', tempDir, 2));
@@ -406,21 +477,41 @@ export const executeGeminiCommand = async params => {
           } else {
             lastMessage = output;
           }
-        }
-
-        if (chunk.type === 'stderr') {
+          if (!plainTextError) plainTextError = detectGeminiPlainTextError(output);
+        } else if (chunk.type === 'stderr') {
           const errorOutput = chunk.data.toString();
           if (errorOutput) {
             await log(errorOutput, { stream: 'stderr' });
             allOutput += errorOutput;
             lastMessage = errorOutput;
+            if (!plainTextError) plainTextError = detectGeminiPlainTextError(errorOutput);
           }
         } else if (chunk.type === 'exit') {
           exitCode = chunk.code;
         }
       }
 
-      if (exitCode !== 0 || geminiJsonState.errorMessages?.length > 0) {
+      // Issue #1809: require positive evidence that gemini-cli actually ran.
+      // An empty JSONL stream + exit 0 (e.g. when stdin is closed early) used
+      // to be reported as success: true with messageCount: 0.
+      const observedJsonEvents = Object.values(geminiJsonState.eventCounts || {}).reduce((sum, count) => sum + count, 0);
+      const hasMeaningfulOutput = observedJsonEvents > 0;
+
+      // Promote the detected plain-text error into the structured error list
+      // so downstream retry / usage-limit detection picks it up.
+      if (plainTextError && !geminiJsonState.errorMessages?.some(m => m === plainTextError.message)) {
+        geminiJsonState.errorMessages = geminiJsonState.errorMessages || [];
+        geminiJsonState.errorMessages.push(plainTextError.message);
+        await log(`⚠️ Gemini CLI reported a plain-text error: [${plainTextError.type}] ${plainTextError.message}`, { level: 'warning', verbose: false });
+      }
+
+      const failedExit = exitCode !== 0;
+      const hasJsonError = (geminiJsonState.errorMessages?.length || 0) > 0;
+      // Zero JSONL events => the wrapper has nothing to attribute as model work,
+      // so this run was effectively a no-op and must be reported as failure.
+      const emittedNoEvents = !hasMeaningfulOutput;
+
+      if (failedExit || hasJsonError || emittedNoEvents) {
         const errorText = geminiJsonState.errorMessages?.length > 0 ? geminiJsonState.errorMessages.join('\n') : allOutput || lastMessage;
         const retryableError = classifyRetryableError(errorText);
         if (retryableError.isRetryable) {
@@ -522,8 +613,6 @@ export const executeGeminiCommand = async params => {
         publicPricingEstimate: null,
         resultSummary: null,
       };
-    } finally {
-      await fs.unlink(promptFile).catch(() => {});
     }
   };
 

package/src/solve.config.lib.mjs

@@ -588,6 +588,25 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Experimental and disabled by default. Automatically detect the target issue or pull request language and set the AI work language to English or Russian when one language has more than 51% of all words. Explicit --work-language or --prompt-language takes precedence.',
     default: false,
   },
+  // Issue #1809: gemini-cli native flags surfaced as solve.mjs options so users
+  // can control sandboxing, extensions and MCP server allow-lists per run.
+  'gemini-sandbox': {
+    type: 'boolean',
+    description: 'Run gemini-cli inside its sandbox (passes --sandbox to gemini-cli). Only used when --tool gemini.',
+    default: false,
+  },
+  'gemini-extensions': {
+    type: 'string',
+    description: 'Comma-separated list of gemini-cli extensions to load (passes --extensions to gemini-cli). Only used when --tool gemini.',
+  },
+  'gemini-include-directories': {
+    type: 'string',
+    description: 'Extra directories to expose to gemini-cli (passes --include-directories to gemini-cli, in addition to tempDir/workspaceTmpDir which are always included). Only used when --tool gemini.',
+  },
+  'gemini-allowed-mcp-servers': {
+    type: 'string',
+    description: 'Comma-separated list of MCP server names that gemini-cli is allowed to call (passes --allowed-mcp-server-names to gemini-cli). Only used when --tool gemini.',
+  },
 };
 
 function hasRawOption(rawArgs, optionName) {

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

@@ -20,6 +20,7 @@
 
 import { parseRepositoryUrl, checkLabelPermissions, ensureReadyLabel } from './github-merge.lib.mjs';
 import { createMergeQueueProcessor, MergeStatus, MERGE_QUEUE_CONFIG } from './telegram-merge-queue.lib.mjs';
+import { executeStartScreen } from './telegram-command-execution.lib.mjs';
 
 /**
  * Active merge operations map (repoKey -> { processor, chatId, messageId })
@@ -90,6 +91,77 @@ function parseCommandArgs(text) {
   return args;
 }
 
+/**
+ * Issue #1805: Parse boolean flags out of the tokenised `/merge` args.
+ * Supports `--flag`, `--flag=true`, `--flag=false`, `--no-flag` and the
+ * trailing positional repository URL. We keep the original positional order
+ * so callers can still treat `positionals[0]` as the repo URL.
+ *
+ * @param {string[]} args - The output of `parseCommandArgs(text)`.
+ * @returns {{ positionals: string[], flags: Record<string, boolean> }}
+ */
+export function parseMergeArgs(args) {
+  const flags = {};
+  const positionals = [];
+  for (const arg of args) {
+    if (typeof arg !== 'string') continue;
+    if (arg.startsWith('--')) {
+      const body = arg.slice(2);
+      if (!body) continue;
+      // --no-foo => foo=false
+      if (body.startsWith('no-')) {
+        const key = body.slice(3);
+        if (key) flags[key] = false;
+        continue;
+      }
+      const eqIdx = body.indexOf('=');
+      if (eqIdx === -1) {
+        flags[body] = true;
+      } else {
+        const key = body.slice(0, eqIdx);
+        const value = body.slice(eqIdx + 1).toLowerCase();
+        flags[key] = !(value === 'false' || value === '0' || value === 'no' || value === 'off');
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+/**
+ * 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
+ * the same `start-screen` runtime the bot uses everywhere else. Keeping this
+ * in one place means the per-PR sessions behave exactly like any other
+ * `/solve` invocation (same logs, same /watch, same isolation backend).
+ *
+ * @param {Object} target - Info for the conflicted PR.
+ * @param {string} target.url - PR HTML URL passed to `solve`.
+ * @param {boolean} verbose - Forwarded to the underlying spawn.
+ * @returns {Promise<{ success: boolean, sessionName: string|null, error: string|null, warning: string|null }>}
+ */
+async function spawnAutoResolveSolve(target, verbose) {
+  if (!target || !target.url) {
+    return { success: false, sessionName: null, error: 'missing PR URL', warning: null };
+  }
+  const args = [target.url, '--auto-merge'];
+  try {
+    const result = await executeStartScreen('solve', args, { verbose });
+    if (result.warning) {
+      return { success: false, sessionName: null, error: null, warning: result.warning };
+    }
+    if (!result.success) {
+      return { success: false, sessionName: null, error: result.error || 'spawn failed', warning: null };
+    }
+    const match = result.output && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
+    const sessionName = match ? match[1] : null;
+    return { success: true, sessionName, error: null, warning: null };
+  } catch (error) {
+    return { success: false, sessionName: null, error: error.message || String(error), warning: null };
+  }
+}
+
 /**
  * Format user-friendly error message
  * Hides debug info unless verbose mode is enabled
@@ -175,13 +247,17 @@ export function registerMergeCommand(bot, options) {
 
     // Parse arguments
     const args = parseCommandArgs(ctx.message.text);
+    // Issue #1805: split positional args from `--auto-resolve` style flags so
+    // the repository URL parsing still sees only the URL token.
+    const { positionals, flags } = parseMergeArgs(args);
+    const autoResolve = flags['auto-resolve'] === true;
 
-    if (args.length === 0) {
-      return await ctx.reply("Missing repository URL\\.\n\nUsage: `/merge <repository-url>`\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\\.", { parse_mode: 'MarkdownV2', reply_to_message_id: ctx.message.message_id });
+    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 });
     }
 
     // Parse and validate repository URL
-    const repoUrl = args[0];
+    const repoUrl = positionals[0];
     const parsedUrl = parseRepositoryUrl(repoUrl);
 
     if (!parsedUrl.valid) {
@@ -234,6 +310,11 @@ export function registerMergeCommand(bot, options) {
       // Create the merge queue processor
       const processor = await createMergeQueueProcessor(owner, repo, {
         verbose: VERBOSE,
+        // 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.
+        autoResolve,
+        spawnSolveSession: autoResolve ? target => spawnAutoResolveSolve(target, VERBOSE) : null,
         onProgress: async () => {
           // Update message with progress and cancel button
           try {

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

@@ -44,8 +44,24 @@ export const MergeItemStatus = {
   MERGED: 'merged',
   FAILED: 'failed',
   SKIPPED: 'skipped',
+  // Issue #1805: states reached during the post-queue `--auto-resolve` pass.
+  // RESOLVING is set while a `/solve <pr> --auto-merge` session is being
+  // spawned for a previously-skipped PR; RESOLVE_FAILED records that the
+  // spawn (or the resolution itself) didn't succeed.
+  RESOLVING: 'resolving',
+  RESOLVE_FAILED: 'resolve_failed',
 };
 
+/**
+ * Marker that identifies SKIPPED items that the auto-resolve pass should
+ * pick up. The same string is returned by `checkPRMergeable()` for
+ * `mergeStateStatus === 'DIRTY'` (see github-merge.lib.mjs), so matching
+ * on it keeps the two modules in sync without sharing extra state.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1805
+ */
+export const MERGE_CONFLICT_SKIP_REASON = 'PR has merge conflicts';
+
 /**
  * Configuration for merge queue operations
  * Values are loaded from config.lib.mjs which supports environment variable overrides.
@@ -134,6 +150,11 @@ class MergeQueueItem {
         return '❌';
       case MergeItemStatus.SKIPPED:
         return '⏭️';
+      // Issue #1805: auto-resolve pass states.
+      case MergeItemStatus.RESOLVING:
+        return '🛠️';
+      case MergeItemStatus.RESOLVE_FAILED:
+        return '⚠️';
       default:
         return '❓';
     }
@@ -152,6 +173,12 @@ export class MergeQueueProcessor {
     this.onProgress = options.onProgress || null;
     this.onComplete = options.onComplete || null;
     this.onError = options.onError || null;
+    // Issue #1805: when true the queue runs a second pass after the normal
+    // merge loop, spawning `/solve <pr> --auto-merge` for every PR that was
+    // SKIPPED due to merge conflicts. The actual spawner is injected so
+    // tests can run without touching the screen runtime.
+    this.autoResolve = options.autoResolve === true;
+    this.spawnSolveSession = typeof options.spawnSolveSession === 'function' ? options.spawnSolveSession : null;
 
     // State
     this.items = [];
@@ -161,6 +188,9 @@ export class MergeQueueProcessor {
     this.startedAt = null;
     this.completedAt = null;
     this.error = null;
+    // Issue #1805: track auto-resolve progress so the renderer can surface it.
+    this.autoResolveActive = false;
+    this.autoResolveCurrent = null;
 
     // Statistics
     this.stats = {
@@ -168,6 +198,11 @@ export class MergeQueueProcessor {
       merged: 0,
       failed: 0,
       skipped: 0,
+      // Issue #1805: number of skipped conflict PRs the auto-resolve pass
+      // successfully handed off to `solve`, and the number that failed to
+      // be handed off (e.g. screen runner missing).
+      autoResolved: 0,
+      autoResolveFailed: 0,
     };
   }
 
@@ -329,6 +364,15 @@ export class MergeQueueProcessor {
         }
       }
 
+      // Issue #1805: After the normal queue settles, optionally hand off
+      // every PR that was SKIPPED with a merge-conflict reason to the
+      // `/solve <pr> --auto-merge` flow. This lets a single `/merge`
+      // invocation both merge the easy PRs and dispatch conflict-resolution
+      // sessions for the rest.
+      if (this.autoResolve && !this.isCancelled) {
+        await this.runAutoResolve();
+      }
+
       this.completedAt = new Date();
       this.status = this.isCancelled ? MergeStatus.CANCELLED : MergeStatus.COMPLETED;
 
@@ -483,6 +527,100 @@ export class MergeQueueProcessor {
     this.log('Cancellation requested');
   }
 
+  /**
+   * Issue #1805: Return queue items that were skipped because of merge
+   * conflicts. These are the candidates the auto-resolve pass hands off
+   * to `/solve <pr> --auto-merge`.
+   *
+   * @returns {MergeQueueItem[]}
+   */
+  getConflictedItems() {
+    return this.items.filter(item => item.status === MergeItemStatus.SKIPPED && item.error === MERGE_CONFLICT_SKIP_REASON);
+  }
+
+  /**
+   * Issue #1805: Iterate every conflict-skipped item and hand it off to a
+   * `/solve <pr-url> --auto-merge` session via the injected
+   * `spawnSolveSession` callback. Each spawn is awaited so the bot doesn't
+   * fan out unbounded Claude sessions. The PR's status is updated as the
+   * spawn succeeds or fails.
+   *
+   * @returns {Promise<void>}
+   */
+  async runAutoResolve() {
+    const conflicted = this.getConflictedItems();
+    if (conflicted.length === 0) {
+      this.log('Auto-resolve: no merge-conflict skips to process');
+      return;
+    }
+
+    if (!this.spawnSolveSession) {
+      // Guard against misconfiguration — the queue can't resolve without a
+      // spawner. Surface this to the user via the same channel as other
+      // queue feedback rather than throwing.
+      this.log(`Auto-resolve: ${conflicted.length} conflict PR(s) but no spawnSolveSession callback provided`);
+      for (const item of conflicted) {
+        item.status = MergeItemStatus.RESOLVE_FAILED;
+        item.autoResolveError = 'auto-resolve is not configured';
+        this.stats.autoResolveFailed++;
+      }
+      if (this.onProgress) {
+        await this.onProgress(this.getProgressUpdate());
+      }
+      return;
+    }
+
+    this.autoResolveActive = true;
+    this.log(`Auto-resolve: dispatching ${conflicted.length} conflict PR(s) to /solve --auto-merge`);
+    try {
+      for (const item of conflicted) {
+        if (this.isCancelled) {
+          this.log('Auto-resolve: cancelled mid-pass');
+          break;
+        }
+
+        item.status = MergeItemStatus.RESOLVING;
+        this.autoResolveCurrent = item.pr.number;
+        if (this.onProgress) {
+          await this.onProgress(this.getProgressUpdate());
+        }
+
+        try {
+          const result = await this.spawnSolveSession({
+            url: item.pr.url,
+            owner: this.owner,
+            repo: this.repo,
+            prNumber: item.pr.number,
+            title: item.pr.title,
+          });
+
+          if (result && result.success) {
+            item.autoResolveSession = result.sessionName || result.session || null;
+            this.stats.autoResolved++;
+            this.log(`Auto-resolve: spawned solve session for PR #${item.pr.number}${item.autoResolveSession ? ` (session ${item.autoResolveSession})` : ''}`);
+          } else {
+            item.status = MergeItemStatus.RESOLVE_FAILED;
+            item.autoResolveError = (result && (result.error || result.warning)) || 'spawn failed';
+            this.stats.autoResolveFailed++;
+            this.log(`Auto-resolve: failed to spawn solve session for PR #${item.pr.number}: ${item.autoResolveError}`);
+          }
+        } catch (error) {
+          item.status = MergeItemStatus.RESOLVE_FAILED;
+          item.autoResolveError = error.message || String(error);
+          this.stats.autoResolveFailed++;
+          console.error(`[ERROR] /merge-queue: auto-resolve error for PR #${item.pr.number}: ${item.autoResolveError}`);
+        }
+
+        if (this.onProgress) {
+          await this.onProgress(this.getProgressUpdate());
+        }
+      }
+    } finally {
+      this.autoResolveActive = false;
+      this.autoResolveCurrent = null;
+    }
+  }
+
   /**
    * Wait for any active CI runs on the target branch to complete
    * Issue #1307: Prevents merging while post-merge CI from previous merges is still running
@@ -658,6 +796,13 @@ export class MergeQueueProcessor {
       status: this.status,
       current: currentItem ? currentItem.getDescription() : null,
       currentStatus: currentItem ? currentItem.status : null,
+      // Issue #1805: surface auto-resolve progress so renderers/tests can
+      // show what's happening during the post-queue pass.
+      autoResolve: {
+        enabled: this.autoResolve,
+        active: this.autoResolveActive,
+        currentPrNumber: this.autoResolveCurrent,
+      },
       progress: {
         processed,
         total: this.stats.total,
@@ -666,10 +811,17 @@ export class MergeQueueProcessor {
       stats: { ...this.stats },
       items: this.items.map(item => ({
         prNumber: item.pr.number,
+        // Issue #1805: expose PR/issue URLs so renderers can produce
+        // clickable links instead of plain `\#NNN` text.
+        prUrl: item.pr.url || null,
+        issueNumber: item.issue ? item.issue.number : null,
+        issueUrl: item.issue ? item.issue.url || null : null,
         title: item.pr.title,
         status: item.status,
         error: item.error,
         emoji: item.getStatusEmoji(),
+        autoResolveSession: item.autoResolveSession || null,
+        autoResolveError: item.autoResolveError || null,
       })),
     };
   }
@@ -684,13 +836,24 @@ export class MergeQueueProcessor {
       status: this.status,
       duration: `${Math.floor(duration / 60)}m ${duration % 60}s`,
       stats: { ...this.stats },
+      autoResolve: {
+        enabled: this.autoResolve,
+        resolved: this.stats.autoResolved,
+        failed: this.stats.autoResolveFailed,
+      },
       items: this.items.map(item => ({
         prNumber: item.pr.number,
+        // Issue #1805: expose PR/issue URLs so renderers can produce
+        // clickable links instead of plain `\#NNN` text.
+        prUrl: item.pr.url || null,
         title: item.pr.title,
         issueNumber: item.issue ? item.issue.number : null,
+        issueUrl: item.issue ? item.issue.url || null : null,
         status: item.status,
         error: item.error,
         emoji: item.getStatusEmoji(),
+        autoResolveSession: item.autoResolveSession || null,
+        autoResolveError: item.autoResolveError || null,
       })),
     };
   }
@@ -748,11 +911,25 @@ export class MergeQueueProcessor {
       message += `⏱️ Waiting for post\\-merge CI \\(PR \\#${this.currentPostMergePR}\\)\\.\\.\\.\n\n`;
     }
 
-    // Current item being processed
-    if (update.current && !this.waitingForTargetBranchCI && !this.waitingForPostMergeCI) {
+    // Issue #1805: surface the auto-resolve pass when it is currently
+    // active. This appears in place of "current item" because by then the
+    // main queue loop has finished.
+    if (update.autoResolve && update.autoResolve.active && update.autoResolve.currentPrNumber) {
+      const activeItem = update.items.find(it => it.prNumber === update.autoResolve.currentPrNumber);
+      const link = activeItem ? this.formatPrLink(activeItem.prNumber, activeItem.title, activeItem.prUrl) : `\\#${update.autoResolve.currentPrNumber}`;
+      message += `🛠️ Auto\\-resolving ${link}\n\n`;
+    } else if (update.current && !this.waitingForTargetBranchCI && !this.waitingForPostMergeCI) {
+      // Current item being processed
       const statusEmoji = update.currentStatus === MergeItemStatus.WAITING_CI ? '⏱️' : '🔄';
-      // Issue #1339: escape the current item description for MarkdownV2
-      message += `${statusEmoji} ${this.escapeMarkdown(update.current)}\n\n`;
+      const currentItem = this.items[this.currentIndex];
+      if (currentItem) {
+        const link = this.formatPrLink(currentItem.pr.number, currentItem.pr.title, currentItem.pr.url);
+        const issueSuffix = this.formatIssueRef(currentItem.issue ? currentItem.issue.number : null, currentItem.issue ? currentItem.issue.url : null);
+        message += `${statusEmoji} ${link}${issueSuffix}\n\n`;
+      } else {
+        // Fallback: escape the description if we somehow don't have an item handle
+        message += `${statusEmoji} ${this.escapeMarkdown(update.current)}\n\n`;
+      }
     }
 
     // Show errors/failures/skips inline so user gets immediate feedback (Issue #1269, #1294)
@@ -762,8 +939,9 @@ export class MergeQueueProcessor {
       message += `⚠️ *Issues:*\n`;
       for (const item of problemItems.slice(0, 5)) {
         const statusEmoji = item.status === MergeItemStatus.FAILED ? '❌' : '⏭️';
-        // Issue #1339: escape the ellipsis '...' for MarkdownV2 (periods are reserved)
-        message += `  ${statusEmoji} \\#${item.prNumber}: ${this.escapeMarkdown(item.error.substring(0, 50))}${item.error.length > 50 ? '\\.\\.\\.' : ''}\n`;
+        // Issue #1805: emit the PR reference as a clickable link instead of plain text.
+        const prRef = this.formatPrLink(item.prNumber, '', item.prUrl);
+        message += `  ${statusEmoji} ${prRef}: ${this.escapeMarkdown(item.error.substring(0, 50))}${item.error.length > 50 ? '\\.\\.\\.' : ''}\n`;
       }
       if (problemItems.length > 5) {
         // Issue #1339: escape the ellipsis '...' for MarkdownV2
@@ -772,11 +950,10 @@ export class MergeQueueProcessor {
       message += '\n';
     }
 
-    // PRs list with emojis
+    // PRs list with emojis (Issue #1805: render as clickable MarkdownV2 links)
     message += `*Queue:*\n`;
     for (const item of update.items.slice(0, 10)) {
-      // Issue #1339: escape the ellipsis '...' for MarkdownV2 (periods are reserved)
-      message += `${item.emoji} \\#${item.prNumber}: ${this.escapeMarkdown(item.title.substring(0, 35))}${item.title.length > 35 ? '\\.\\.\\.' : ''}\n`;
+      message += `${item.emoji} ${this.formatPrLink(item.prNumber, item.title, item.prUrl)}\n`;
     }
 
     if (update.items.length > 10) {
@@ -830,7 +1007,20 @@ export class MergeQueueProcessor {
     message += `✅ Merged: ${report.stats.merged}  `;
     message += `❌ Failed: ${report.stats.failed}  `;
     message += `⏭️ Skipped: ${report.stats.skipped}  `;
-    message += `📋 Total: ${report.stats.total}\n\n`;
+    message += `📋 Total: ${report.stats.total}\n`;
+
+    // Issue #1805: surface the auto-resolve pass summary when it ran. We
+    // always show the line when the flag was set so users see "0 dispatched"
+    // when there was nothing to do.
+    if (report.autoResolve && report.autoResolve.enabled) {
+      message += `🛠️ Auto\\-resolve dispatched: ${report.autoResolve.resolved}`;
+      if (report.autoResolve.failed > 0) {
+        message += `  ⚠️ Auto\\-resolve failed: ${report.autoResolve.failed}`;
+      }
+      message += '\n';
+    }
+
+    message += '\n';
 
     // Issue #1341: Show branch CI health failure details if applicable
     if (this.branchCIFailedRuns && this.branchCIFailedRuns.length > 0) {
@@ -862,19 +1052,25 @@ export class MergeQueueProcessor {
       message += '\n';
     }
 
-    // Details
+    // Details (Issue #1805: render PR and issue references as clickable
+    // MarkdownV2 links so the user can jump directly to the PR or issue).
     if (report.items.length > 0) {
       message += `*Results:*\n`;
       for (const item of report.items) {
-        const issueRef = item.issueNumber ? ` \\(Issue \\#${item.issueNumber}\\)` : '';
+        const prLink = this.formatPrLink(item.prNumber, item.title, item.prUrl);
+        const issueRef = this.formatIssueRef(item.issueNumber, item.issueUrl);
         // Issue #1294: Show skip/fail reason so users understand what action is required
         let reasonText = '';
-        if (item.error && (item.status === MergeItemStatus.SKIPPED || item.status === MergeItemStatus.FAILED)) {
+        const isAutoResolveState = item.status === MergeItemStatus.RESOLVING || item.status === MergeItemStatus.RESOLVE_FAILED;
+        if (item.autoResolveError && isAutoResolveState) {
+          const truncated = item.autoResolveError.length > 50 ? item.autoResolveError.substring(0, 47) + '...' : item.autoResolveError;
+          reasonText = ` \\(${this.escapeMarkdown(truncated)}\\)`;
+        } else if (item.error && (item.status === MergeItemStatus.SKIPPED || item.status === MergeItemStatus.FAILED)) {
           // Truncate long reasons and escape for MarkdownV2
           const truncatedReason = item.error.length > 50 ? item.error.substring(0, 47) + '...' : item.error;
           reasonText = `: ${this.escapeMarkdown(truncatedReason)}`;
         }
-        message += `${item.emoji} \\#${item.prNumber}${issueRef}${reasonText}\n`;
+        message += `${item.emoji} ${prLink}${issueRef}${reasonText}\n`;
       }
     }
 
@@ -888,6 +1084,43 @@ export class MergeQueueProcessor {
     return String(text).replace(/[_*[\]()~`>#+\-=|{}.!]/g, '\\$&');
   }
 
+  /**
+   * Issue #1805: Escape `)` and `\` inside a URL for a MarkdownV2 inline link.
+   * URLs must NOT be passed through `escapeMarkdown()` because that would also
+   * mangle characters that are valid inside URLs (`.`, `-`, `_`, etc.).
+   */
+  escapeMarkdownLinkUrl(url) {
+    return String(url).replace(/[\\)]/g, '\\$&');
+  }
+
+  /**
+   * Issue #1805: Build a clickable MarkdownV2 link for a PR's `\#N: title`
+   * reference. Falls back to plain escaped text when no URL is available so
+   * the message still renders correctly on legacy items.
+   */
+  formatPrLink(prNumber, title, url, options = {}) {
+    const maxTitle = typeof options.maxTitle === 'number' ? options.maxTitle : 35;
+    const trimmedTitle = title || '';
+    const truncated = trimmedTitle.length > maxTitle ? trimmedTitle.substring(0, maxTitle) : trimmedTitle;
+    const ellipsis = trimmedTitle.length > maxTitle ? '\\.\\.\\.' : '';
+    const titlePart = trimmedTitle ? `: ${this.escapeMarkdown(truncated)}${ellipsis}` : '';
+    const label = `\\#${prNumber}${titlePart}`;
+    if (!url) return label;
+    return `[${label}](${this.escapeMarkdownLinkUrl(url)})`;
+  }
+
+  /**
+   * Issue #1805: Build the ` (Issue #N)` suffix as a clickable link. The
+   * outer parentheses are literal MarkdownV2 (escaped), so the inner inline
+   * link is not nested inside another entity.
+   */
+  formatIssueRef(issueNumber, url) {
+    if (!issueNumber) return '';
+    const label = `Issue \\#${issueNumber}`;
+    if (!url) return ` \\(${label}\\)`;
+    return ` \\([${label}](${this.escapeMarkdownLinkUrl(url)})\\)`;
+  }
+
   /**
    * Sleep helper
    */