@link-assistant/hive-mind 2.14.0 → 2.15.1

package/src/merge-error-classification.lib.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * Classification helpers for pull request mergeability and merge failures.
+ *
+ * Issue #2182: `/solve ... --auto-merge --auto-restart-until-mergeable` kept a
+ * single task "processing" for 4d 12h 13m. The pull request had been converted
+ * to draft by an auto-restart iteration and never converted back, so:
+ *
+ *   1. `checkPRMergeable()` asked GitHub only for `mergeable,mergeStateStatus`.
+ *      A draft pull request with no other blockers answers
+ *      `MERGEABLE` / `CLEAN` — the `case 'DRAFT'` branch that was supposed to
+ *      catch this was dead code, because it is only reachable when
+ *      `mergeable !== 'MERGEABLE'`. The watch loop therefore declared
+ *      "PR IS MERGEABLE!" on every check.
+ *   2. `gh pr merge` then failed with
+ *      `GraphQL: Pull Request is still a draft (mergePullRequest)`.
+ *   3. The failure was logged as "Will continue monitoring..." and retried
+ *      every 120 seconds, forever (5384 identical failures in the reported run).
+ *
+ * These two pure functions are the single place where "is this pull request
+ * actually mergeable?" and "is this merge failure worth retrying?" are decided,
+ * so every merge call site can share the same answer.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2182
+ * @see docs/case-studies/issue-2182/README.md for the full timeline and evidence
+ */
+
+/**
+ * Merge failure categories.
+ *
+ * `recoverable` means hive-mind itself can fix the cause and retry (currently
+ * only the draft state). `terminal` means retrying the exact same merge cannot
+ * succeed without a human or a new AI session, so a watch loop must stop
+ * instead of hammering the API.
+ */
+export const MERGE_ERROR_CATEGORIES = {
+  DRAFT: 'draft',
+  CONFLICT: 'conflict',
+  BLOCKED: 'blocked',
+  CLOSED: 'closed',
+  PERMISSION: 'permission',
+  NOT_MERGEABLE: 'not_mergeable',
+  UNKNOWN: 'unknown',
+};
+
+/**
+ * How many consecutive failed merge attempts a watch loop may make before it
+ * gives up and reports the stop. Issue #2182: there was no such ceiling.
+ */
+export const MAX_CONSECUTIVE_MERGE_FAILURES = 3;
+
+const MERGE_ERROR_PATTERNS = [
+  // "GraphQL: Pull Request is still a draft (mergePullRequest)"
+  { category: MERGE_ERROR_CATEGORIES.DRAFT, terminal: false, recoverable: true, pattern: /still a draft|is a draft|draft state|convert(ed)? to draft/i, resolution: 'Mark the pull request as ready for review (gh pr ready <number>) before merging.' },
+  { category: MERGE_ERROR_CATEGORIES.CLOSED, terminal: true, recoverable: false, pattern: /pull request is closed|already merged|has already been merged|not open/i, resolution: 'The pull request is no longer open — nothing left to merge.' },
+  { category: MERGE_ERROR_CATEGORIES.PERMISSION, terminal: true, recoverable: false, pattern: /resource not accessible|must have (admin|write|push)|permission|403|not authorized|forbidden/i, resolution: 'Grant the token merge permission on the repository, or merge manually.' },
+  { category: MERGE_ERROR_CATEGORIES.BLOCKED, terminal: true, recoverable: false, pattern: /required status check|approving review|review is required|protected branch|branch protection|changes must be made through a pull request|merge queue/i, resolution: 'Satisfy the branch protection requirements (reviews / required checks) or merge manually.' },
+  { category: MERGE_ERROR_CATEGORIES.CONFLICT, terminal: false, recoverable: false, pattern: /merge conflict|not mergeable due to conflicts|conflicts? with the base branch/i, resolution: 'Resolve the merge conflicts with the base branch, then retry.' },
+  { category: MERGE_ERROR_CATEGORIES.NOT_MERGEABLE, terminal: false, recoverable: false, pattern: /pull request is not mergeable|is not mergeable|base branch was modified/i, resolution: 'Wait for GitHub to recompute mergeability, or update the branch from the base branch.' },
+];
+
+/**
+ * Classify a `gh pr merge` failure message.
+ *
+ * @param {string|null|undefined} errorMessage raw stderr/message from `gh pr merge`
+ * @returns {{category: string, terminal: boolean, recoverable: boolean, resolution: string|null}}
+ */
+export const classifyMergeError = errorMessage => {
+  const text = typeof errorMessage === 'string' ? errorMessage : '';
+  for (const entry of MERGE_ERROR_PATTERNS) {
+    if (entry.pattern.test(text)) {
+      return { category: entry.category, terminal: entry.terminal, recoverable: entry.recoverable, resolution: entry.resolution };
+    }
+  }
+  return { category: MERGE_ERROR_CATEGORIES.UNKNOWN, terminal: false, recoverable: false, resolution: null };
+};
+
+/**
+ * Decide whether a pull request payload describes a mergeable pull request.
+ *
+ * Expects the parsed output of
+ * `gh pr view <n> --json isDraft,mergeable,mergeStateStatus`.
+ *
+ * Issue #2182: `isDraft` is checked FIRST and independently of
+ * `mergeStateStatus`, because GitHub reports `CLEAN`/`MERGEABLE` for a draft
+ * pull request that has no other blockers, while `gh pr merge` still refuses it.
+ *
+ * @param {{isDraft?: boolean, mergeable?: string|null, mergeStateStatus?: string|null}} pr
+ * @returns {{mergeable: boolean, isDraft: boolean, mergeableState: string|null, mergeStateStatus: string|null, reason: string|null}}
+ */
+export const evaluatePullRequestMergeability = (pr = {}) => {
+  const isDraft = pr.isDraft === true;
+  const mergeableState = pr.mergeable ?? null;
+  const mergeStateStatus = pr.mergeStateStatus ?? null;
+
+  if (isDraft) {
+    return { mergeable: false, isDraft: true, mergeableState, mergeStateStatus, reason: 'PR is a draft' };
+  }
+
+  if (mergeableState === 'MERGEABLE') {
+    return { mergeable: true, isDraft: false, mergeableState, mergeStateStatus, reason: null };
+  }
+
+  let reason;
+  switch (mergeStateStatus) {
+    case 'BLOCKED':
+      reason = 'PR is blocked (possibly by branch protection rules)';
+      break;
+    case 'BEHIND':
+      reason = 'PR branch is behind the base branch';
+      break;
+    case 'DIRTY':
+      reason = 'PR has merge conflicts';
+      break;
+    case 'UNSTABLE':
+      reason = 'PR has failing required status checks';
+      break;
+    case 'DRAFT':
+      reason = 'PR is a draft';
+      break;
+    default:
+      reason = `Merge state: ${mergeStateStatus || 'unknown'}`;
+  }
+
+  return { mergeable: false, isDraft: false, mergeableState, mergeStateStatus, reason };
+};
+
+export default {
+  MERGE_ERROR_CATEGORIES,
+  MAX_CONSECUTIVE_MERGE_FAILURES,
+  classifyMergeError,
+  evaluatePullRequestMergeability,
+};

package/src/option-suggestions.lib.mjs

@@ -227,6 +227,7 @@ const KNOWN_OPTION_NAMES = [
   'allow-to-push-to-contributors-pull-requests-as-maintainer',
   'prefix-fork-name-with-owner-name',
   'auto-restart-max-iterations',
+  'auto-restart-until-mergeable-timeout-hours',
   'auto-resume-max-iterations',
   'auto-continue-only-on-new-comments',
   'auto-restart-on-limit-reset',

package/src/pr-draft-state.lib.mjs

@@ -11,7 +11,17 @@
  * keep-working, auto-ensure, PR-placeholder restart) kept the PR marked as
  * "ready for review" while the AI was actively working on it.
  *
+ * Issue #2182: the draft transition was code-driven and unconditional while the
+ * matching ready transition was delegated to the AI tool (the prompt asks it to run
+ * `gh pr ready <n>`) and to `endWorkSession()`, which only runs in continue mode and
+ * only after the auto-merge watch loop returns. When the AI simply did not run the
+ * command, the pull request stayed a draft forever. This module therefore *tracks*
+ * every draft it hands out, so the matching ready transition can be guaranteed by
+ * code — including on the interrupt and fatal-error exit paths.
+ *
  * @see https://github.com/link-assistant/hive-mind/issues/2123
+ * @see https://github.com/link-assistant/hive-mind/issues/2182
+ * @see docs/case-studies/issue-2182/README.md for the full timeline and evidence
  */
 
 // rate-limit marker (#1726): callers pass in a `$` already wrapped by wrapDollarWithGhRetry.
@@ -19,6 +29,75 @@ import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry } from './github-rate-l
 
 const noopLog = async () => {};
 
+/**
+ * Issue #2182: pull requests this process put into draft for a working session that
+ * has not been converted back to "ready for review" yet.
+ *
+ * Keyed by `owner/repo#number`, module-level on purpose: like working-session.lib.mjs
+ * this is a per-process singleton, and the safety nets that drain it (interrupt
+ * handler, fatal-error handler) have no access to the call site that drafted the PR.
+ *
+ * @type {Map<string, {owner: string, repo: string, prNumber: (number|string), reason: (string|null), since: string}>}
+ */
+const outstandingWorkingSessionDrafts = new Map();
+
+const draftKey = (owner, repo, prNumber) => `${owner}/${repo}#${prNumber}`;
+
+/**
+ * Record that a working session of this process is holding `prNumber` in draft.
+ * Also called when the pull request already was a draft: what matters for the
+ * invariant is that a session is now responsible for converting it back.
+ */
+const trackWorkingSessionDraft = ({ owner, repo, prNumber, reason }) => {
+  outstandingWorkingSessionDrafts.set(draftKey(owner, repo, prNumber), { owner, repo, prNumber, reason: reason || null, since: new Date().toISOString() });
+};
+
+/** Record that `prNumber` is no longer held in draft by this process. */
+const untrackWorkingSessionDraft = ({ owner, repo, prNumber }) => {
+  outstandingWorkingSessionDrafts.delete(draftKey(owner, repo, prNumber));
+};
+
+/**
+ * Pull requests currently held in draft by this process on behalf of a working session.
+ * @returns {Array<{owner: string, repo: string, prNumber: (number|string), reason: (string|null), since: string}>}
+ */
+export const getOutstandingWorkingSessionDrafts = () => Array.from(outstandingWorkingSessionDrafts.values());
+
+/** Forget every tracked draft (used by tests and by a clean process restart). */
+export const resetWorkingSessionDrafts = () => {
+  outstandingWorkingSessionDrafts.clear();
+};
+
+/**
+ * Issue #2182 safety net: convert back to "ready for review" every pull request this
+ * process left in draft for a working session that is now over.
+ *
+ * Called from the interrupt handler and the fatal-error handler, so an aborted session
+ * cannot leave a pull request permanently unmergeable. A no-op when nothing is
+ * outstanding, so it is safe to call on every exit path.
+ *
+ * @param {Object} options
+ * @param {Function} options.$ - command-stream style tagged template executor
+ * @param {Function} [options.log]
+ * @param {Function} [options.formatAligned]
+ * @param {string} [options.reason]
+ * @param {Function} [options.reportError]
+ * @returns {Promise<Array<Object>>} one result per restored pull request
+ */
+export const restorePullRequestsLeftInDraft = async ({ $, log = noopLog, formatAligned = null, reason = 'working session ended', reportError = null } = {}) => {
+  const pending = getOutstandingWorkingSessionDrafts();
+  if (pending.length === 0) {
+    return [];
+  }
+
+  await log(`🩹 Restoring ${pending.length} pull request(s) left in draft by this working session...`);
+  const results = [];
+  for (const entry of pending) {
+    results.push(await ensurePullRequestIsReady({ owner: entry.owner, repo: entry.repo, prNumber: entry.prNumber, $, log, formatAligned, reason, reportError }));
+  }
+  return results;
+};
+
 /**
  * Fetch the draft/open state of a pull request.
  *
@@ -83,11 +162,20 @@ const setPullRequestDraftState = async ({ target, owner, repo, prNumber, $, log
 
     // A merged or closed pull request cannot change its draft state; GitHub rejects it.
     if (status.state && status.state !== 'OPEN') {
+      // A merged/closed PR can no longer block anything, so stop tracking it (#2182).
+      untrackWorkingSessionDraft({ owner, repo, prNumber });
       await write('ℹ️', 'PR status:', `${status.state.toLowerCase()} - skipping ${label} conversion`);
       return { ok: true, changed: false, skipped: true, reason: `pr_${status.state.toLowerCase()}`, error: null };
     }
 
     if (status.isDraft === wantDraft) {
+      // Issue #2182: even when the PR already is a draft, this session now owns the
+      // obligation to convert it back, so it must be tracked like any other draft.
+      if (wantDraft) {
+        trackWorkingSessionDraft({ owner, repo, prNumber, reason });
+      } else {
+        untrackWorkingSessionDraft({ owner, repo, prNumber });
+      }
       await write('✅', 'PR status:', `Already in ${label}`);
       return { ok: true, changed: false, skipped: true, reason: 'already_in_target_state', error: null };
     }
@@ -96,6 +184,11 @@ const setPullRequestDraftState = async ({ target, owner, repo, prNumber, $, log
     const convertResult = wantDraft ? await $`gh pr ready ${prNumber} --repo ${owner}/${repo} --undo` : await $`gh pr ready ${prNumber} --repo ${owner}/${repo}`;
 
     if (convertResult.code === 0) {
+      if (wantDraft) {
+        trackWorkingSessionDraft({ owner, repo, prNumber, reason });
+      } else {
+        untrackWorkingSessionDraft({ owner, repo, prNumber });
+      }
       await write('✅', 'PR converted:', `Now in ${label}`);
       return { ok: true, changed: true, skipped: false, reason: null, error: null };
     }
@@ -134,4 +227,7 @@ export default {
   getPullRequestDraftState,
   ensurePullRequestIsDraft,
   ensurePullRequestIsReady,
+  getOutstandingWorkingSessionDrafts,
+  restorePullRequestsLeftInDraft,
+  resetWorkingSessionDrafts,
 };

package/src/qwen.lib.mjs

@@ -32,6 +32,7 @@ import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-
 import { getTerminalEventCompletionHealth } from './tool-run-health.lib.mjs'; // Issue #1990
 import { takeJsonRecords } from './json-stream.lib.mjs'; // Issue #2119
 import { stringifyErrorValue } from './error-text.lib.mjs'; // Issue #2141
+import { ensureGeminiFamilyMemoryDisabled, isAgentMemoryDisabled } from './agent-memory-policy.lib.mjs'; // Issue #2178
 
 export const mapModelToId = model => qwenModels[model] || model;
 
@@ -524,6 +525,9 @@ export const executeQwenCommand = async params => {
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
     const mappedModel = mapModelToId(argv.model || defaultModels.qwen);
+    // Issue #2178: Qwen Code still ships the `save_memory` tool it inherited from
+    // Gemini CLI. Exclude it so nothing this task learns outlives the container.
+    if (isAgentMemoryDisabled(argv)) await ensureGeminiFamilyMemoryDisabled({ tool: 'qwen', log });
     // Issue #2130: Formal AI runs the native CLI against a local Formal AI server (no argv wrapper).
     const toolInvocation = await resolveFormalAiToolExecution({ tool: 'qwen', model: argv.model || defaultModels.qwen, toolPath: qwenPath, workdir: tempDir, log, verbose: argv.verbose, prepareOnly: isPrepareOnly(argv) });
     const qwenEnv = { ...process.env, ...toolInvocation.env };

package/src/solve.auto-merge-attempt.lib.mjs

@@ -48,6 +48,23 @@ const { AUTO_MERGE_BLOCKED_MARKER, buildAutoMergeBlockedComment, reportAutomatio
 
 const { ensureLinkedIssueClosedAfterMerge } = await import('./github-issue-auto-close.lib.mjs');
 
+// Issue #2182: a pull request left in draft state by a restart iteration reports
+// mergeable=MERGEABLE/CLEAN, but `gh pr merge` refuses it with "Pull Request is
+// still a draft". Restore "ready for review" once and retry instead of failing
+// (or, in the watch loop, retrying forever).
+const { classifyMergeError, MERGE_ERROR_CATEGORIES } = await import('./merge-error-classification.lib.mjs');
+const { ensurePullRequestIsReady } = await import('./pr-draft-state.lib.mjs');
+const { reportError } = await import('./sentry.lib.mjs');
+
+/**
+ * Mark the pull request ready for review because its draft state is what blocks
+ * the merge. Returns true when the state was restored (or already correct).
+ */
+const restoreReadyForReview = async ({ owner, repo, prNumber, reason }) => {
+  const result = await ensurePullRequestIsReady({ owner, repo, prNumber, $, log, formatAligned, reason, reportError });
+  return result?.ok === true;
+};
+
 const shouldDeleteBranchAfterMerge = argv => argv.autoDeleteBranchOnMerge || argv.deleteBranchAfterMerge || false;
 
 /**
@@ -161,7 +178,7 @@ export const attemptAutoMerge = async params => {
   await log(formatAligned('✅', 'CI checks passed:', 'Checking mergeability...', 2));
 
   // Check if PR is mergeable
-  const mergeStatus = await checkPRMergeable(owner, repo, prNumber, argv.verbose);
+  let mergeStatus = await checkPRMergeable(owner, repo, prNumber, argv.verbose);
   if (mergeStatus.terminal) {
     await log(formatAligned('❌', 'GITHUB TARGET UNAVAILABLE:', mergeStatus.reason || 'GitHub repository, pull request, issue, or branch is no longer accessible', 2), { level: 'error' });
     await reportAutomationStop({
@@ -178,6 +195,15 @@ export const attemptAutoMerge = async params => {
     return { success: false, reason: 'terminal_github_entity_error', error: mergeStatus.reason };
   }
 
+  if (!mergeStatus.mergeable && mergeStatus.isDraft) {
+    // Issue #2182: the only blocker is the draft state this tool set itself.
+    await log(formatAligned('📝', 'PR is a draft:', 'restoring "ready for review" before merging', 2), { level: 'warning' });
+    const restored = await restoreReadyForReview({ owner, repo, prNumber, reason: 'auto-merge: draft blocks the merge' });
+    if (restored) {
+      mergeStatus = await checkPRMergeable(owner, repo, prNumber, argv.verbose);
+    }
+  }
+
   if (!mergeStatus.mergeable) {
     await log(formatAligned('⚠️', 'PR not mergeable:', mergeStatus.reason || 'Unknown reason', 2));
     return { success: false, reason: 'not_mergeable', error: mergeStatus.reason };
@@ -198,7 +224,17 @@ export const attemptAutoMerge = async params => {
   if (deleteAfterMerge) {
     await log(formatAligned('', 'Branch cleanup:', 'will delete branch after successful merge', 2));
   }
-  const mergeResult = await mergePullRequest(owner, repo, prNumber, { squash: argv.squash || false, deleteAfter: deleteAfterMerge }, argv.verbose);
+  let mergeResult = await mergePullRequest(owner, repo, prNumber, { squash: argv.squash || false, deleteAfter: deleteAfterMerge }, argv.verbose);
+
+  // Issue #2182: GitHub can still refuse the merge because of the draft state
+  // even when `gh pr view` already answered CLEAN/MERGEABLE (stale read).
+  // Restore "ready for review" once and retry the merge exactly once.
+  if (!mergeResult.success && classifyMergeError(mergeResult.error).category === MERGE_ERROR_CATEGORIES.DRAFT) {
+    await log(formatAligned('🔧', 'Self-healing:', 'GitHub refused the merge because the PR is a draft - marking it ready', 2), { level: 'warning' });
+    if (await restoreReadyForReview({ owner, repo, prNumber, reason: 'auto-merge: GitHub rejected the merge because the PR is a draft' })) {
+      mergeResult = await mergePullRequest(owner, repo, prNumber, { squash: argv.squash || false, deleteAfter: deleteAfterMerge }, argv.verbose);
+    }
+  }
 
   if (mergeResult.success) {
     await log(formatAligned('🎉', 'PR MERGED SUCCESSFULLY!', ''));
@@ -223,7 +259,9 @@ export const attemptAutoMerge = async params => {
 
     return { success: true, reason: 'merged' };
   } else {
-    await log(formatAligned('⚠️', 'Merge failed:', mergeResult.error || 'Unknown error', 2));
+    const classification = classifyMergeError(mergeResult.error);
+    await log(formatAligned('⚠️', 'Merge failed:', mergeResult.error || 'Unknown error', 2), { level: 'warning' });
+    await log(formatAligned('', 'Failure category:', classification.category, 2), { level: 'warning' });
     await reportAutomationStop({
       $,
       owner,
@@ -232,6 +270,7 @@ export const attemptAutoMerge = async params => {
       reason: 'merge_failed',
       mode: 'auto-merge',
       message: mergeResult.error || 'GitHub rejected the merge request.',
+      details: [classification.resolution, `Failure category: ${classification.category}`].filter(Boolean),
       verbose: argv.verbose,
       log,
     });

package/src/solve.auto-merge-guards.lib.mjs

@@ -0,0 +1,152 @@
+/**
+ * Guard rails for the --auto-merge / --auto-restart-until-mergeable watch loop.
+ *
+ * Issue #2182: a single task stayed in the "Processing" state for 4d 12h 13m 35s
+ * because the watch loop had no answer for a pull request it could never merge:
+ * no wall-clock ceiling, no classification of the merge failure and no reaction to
+ * a pull request left in draft. Those three decisions live here so that
+ * `watchUntilMergeable()` only keeps the control flow (`continue` / `return`) and
+ * the loop state.
+ *
+ * These are *defense in depth*. The root cause of #2182 is that hive-mind did not
+ * put the pull request back to "ready for review" when the working session ended;
+ * that is fixed in pr-draft-state.lib.mjs and its callers. The guards below make
+ * sure that a pull request which is a draft anyway - for instance because a human
+ * drafted it, or because the process was SIGKILLed before the safety nets ran -
+ * costs a few seconds instead of several days.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2182
+ */
+
+const { classifyMergeError, MAX_CONSECUTIVE_MERGE_FAILURES } = await import('./merge-error-classification.lib.mjs');
+const { ensurePullRequestIsReady } = await import('./pr-draft-state.lib.mjs');
+
+export { MAX_CONSECUTIVE_MERGE_FAILURES };
+
+/**
+ * How long to wait after restoring "ready for review" before the next
+ * mergeability check. Short on purpose: nothing is running, we only need GitHub
+ * to reflect the new state.
+ */
+export const DRAFT_RECHECK_DELAY_MS = 5000;
+
+/** Default wall-clock ceiling for the auto-restart-until-mergeable loop. */
+export const DEFAULT_WATCH_TIMEOUT_HOURS = 24;
+
+/** How many times the loop may restore "ready for review" before giving up. */
+export const MAX_DRAFT_SELF_HEALS = 3;
+
+/**
+ * Normalize the `--auto-restart-until-mergeable-timeout-hours` value. `0` (and
+ * any negative input) means "no wall-clock limit"; when the flag is absent the
+ * default keeps a run from silently occupying a queue slot for days, as happened
+ * in the reported 4d 12h run.
+ *
+ * @param {number|string|null|undefined} raw
+ * @returns {number} hours, 0 = unlimited
+ */
+export const normalizeWatchTimeoutHours = raw => {
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_WATCH_TIMEOUT_HOURS;
+  const parsed = Number(raw);
+  // A non-numeric value is a typo, not a request for an unlimited run: fall back
+  // to the default instead of silently disabling the timeout again (issue #2182).
+  if (!Number.isFinite(parsed)) return DEFAULT_WATCH_TIMEOUT_HOURS;
+  if (parsed <= 0) return 0;
+  return parsed;
+};
+
+/**
+ * Decide whether the watch loop has exceeded its wall-clock ceiling.
+ *
+ * @returns {{message: string, details: string[]}|null} null while within budget
+ */
+export const evaluateWatchTimeout = ({ watchTimeoutHours, watchStartedAt, now, checksCompleted }) => {
+  if (!(watchTimeoutHours > 0)) return null;
+  const elapsedHours = (now - watchStartedAt) / 3600000;
+  if (elapsedHours < watchTimeoutHours) return null;
+  return {
+    message: `Auto-restart-until-mergeable stopped after ${elapsedHours.toFixed(1)}h (limit: ${watchTimeoutHours}h, ${checksCompleted} checks). The pull request never became mergeable.`,
+    details: ['Raise or disable the limit with --auto-restart-until-mergeable-timeout-hours (0 = unlimited).'],
+  };
+};
+
+/**
+ * React to a pull request that is still a draft while no AI session is running.
+ *
+ * GitHub answers mergeable=MERGEABLE / mergeStateStatus=CLEAN for such a pull
+ * request, so nothing else in the loop notices - the merge then fails with
+ * "Pull Request is still a draft" on every single check, which is exactly the
+ * 2692-iteration loop reported in #2182.
+ *
+ * @param {Object} options
+ * @param {{draftSelfHealCount: number}} options.state - mutable loop state
+ * @returns {Promise<{action: 'stop'|'retry'|'continue', reason?: string}>}
+ */
+export const resolveDraftBlocker = async ({ owner, repo, prNumber, $, log, formatAligned, reportError, reportAutomationStop, verbose, state }) => {
+  await log(formatAligned('📝', 'PR is a draft:', 'no AI session is running - restoring "ready for review"', 2), { level: 'warning' });
+
+  if (state.draftSelfHealCount >= MAX_DRAFT_SELF_HEALS) {
+    const message = `Pull request #${prNumber} keeps returning to draft state (${state.draftSelfHealCount} restore attempts). A draft pull request cannot be merged.`;
+    await log(formatAligned('❌', 'DRAFT STATE UNRECOVERABLE:', message, 2), { level: 'error' });
+    await reportAutomationStop({ $, owner, repo, targetNumber: prNumber, reason: 'draft_pull_request', mode: 'auto-restart-until-mergeable', message, details: ['Mark the pull request as ready for review manually (gh pr ready), then rerun.'], verbose, log });
+    return { action: 'stop', reason: 'draft_pull_request' };
+  }
+
+  state.draftSelfHealCount++;
+  const readyResult = await ensurePullRequestIsReady({ owner, repo, prNumber, $, log, formatAligned, reason: 'auto-restart-until-mergeable: draft blocks the merge', reportError });
+  if (readyResult?.ok) {
+    await log(formatAligned('✅', 'Draft restored:', `PR #${prNumber} is ready for review again (attempt ${state.draftSelfHealCount}/${MAX_DRAFT_SELF_HEALS})`, 2));
+    return { action: 'retry' };
+  }
+
+  await log(formatAligned('⚠️', 'Draft restore failed:', readyResult?.error || 'unknown error', 2), { level: 'warning' });
+  return { action: 'continue' };
+};
+
+/**
+ * Classify a failed `gh pr merge` and decide what the watch loop should do next.
+ *
+ * Before #2182 every failure - terminal or not - printed "Will continue
+ * monitoring..." and was retried every 120 seconds forever (5384 identical
+ * failures in the reported run).
+ *
+ * @param {Object} options
+ * @param {{draftSelfHealCount: number, consecutiveMergeFailures: number}} options.state - mutable loop state
+ * @returns {Promise<{action: 'stop'|'retry'|'continue', reason?: string}>}
+ */
+export const resolveMergeFailure = async ({ error, owner, repo, prNumber, $, log, formatAligned, reportError, reportAutomationStop, verbose, state }) => {
+  state.consecutiveMergeFailures++;
+  const classification = classifyMergeError(error);
+  await log(formatAligned('⚠️', 'Auto-merge failed:', error || 'Unknown error', 2), { level: 'warning' });
+  await log(formatAligned('', 'Failure category:', `${classification.category} (attempt ${state.consecutiveMergeFailures}/${MAX_CONSECUTIVE_MERGE_FAILURES})`, 2), { level: 'warning' });
+  if (classification.resolution) {
+    await log(formatAligned('', 'Resolution:', classification.resolution, 2), { level: 'warning' });
+  }
+
+  if (classification.recoverable && classification.category === 'draft' && state.draftSelfHealCount < MAX_DRAFT_SELF_HEALS) {
+    state.draftSelfHealCount++;
+    await log(formatAligned('🔧', 'Self-healing:', `marking PR #${prNumber} as ready for review (attempt ${state.draftSelfHealCount}/${MAX_DRAFT_SELF_HEALS})`, 2));
+    const readyResult = await ensurePullRequestIsReady({ owner, repo, prNumber, $, log, formatAligned, reason: 'auto-merge: GitHub rejected the merge because the PR is a draft', reportError });
+    if (readyResult?.ok) return { action: 'retry' };
+  }
+
+  if (classification.terminal || state.consecutiveMergeFailures >= MAX_CONSECUTIVE_MERGE_FAILURES) {
+    const message = `GitHub refused to merge pull request #${prNumber}: ${error || 'Unknown error'}`;
+    await log(formatAligned('❌', 'AUTO-MERGE STOPPED:', classification.terminal ? 'the failure is terminal - retrying cannot succeed' : `${state.consecutiveMergeFailures} consecutive merge failures`, 2), { level: 'error' });
+    await reportAutomationStop({ $, owner, repo, targetNumber: prNumber, reason: 'merge_failed', mode: 'auto-merge', message, details: [classification.resolution || 'Merge the pull request manually after resolving the cause.', `Failure category: ${classification.category}`], verbose, log });
+    return { action: 'stop', reason: 'merge_failed' };
+  }
+
+  return { action: 'continue' };
+};
+
+export default {
+  DRAFT_RECHECK_DELAY_MS,
+  DEFAULT_WATCH_TIMEOUT_HOURS,
+  MAX_DRAFT_SELF_HEALS,
+  MAX_CONSECUTIVE_MERGE_FAILURES,
+  normalizeWatchTimeoutHours,
+  evaluateWatchTimeout,
+  resolveDraftBlocker,
+  resolveMergeFailure,
+};

package/src/solve.auto-merge-helpers.lib.mjs

@@ -504,6 +504,19 @@ export const getMergeBlockers = async (owner, repo, prNumber, verbose = false, c
     // then no CI is required and we should not block indefinitely.
     // Otherwise (e.g. mergeStateStatus === 'BLOCKED'), treat as pending race condition.
     const earlyMergeStatus = await checkPRMergeable(owner, repo, prNumber, verbose);
+    // Issue #2182: a draft pull request reports mergeable=false now, which would
+    // otherwise fall into the "checks have not started yet" race-condition branch
+    // below and hide the real reason behind a ci_pending blocker forever. The
+    // `no_checks` branch owns several early returns, so the draft blocker has to
+    // be emitted here to reach the caller through every one of them.
+    if (earlyMergeStatus.isDraft) {
+      blockers.push({
+        type: 'draft',
+        message: earlyMergeStatus.reason || 'PR is a draft',
+        details: [],
+      });
+      return { blockers, ciStatus, noCiConfigured: false, noCiTriggered: false, noWorkflowRunsForCommit };
+    }
     if (earlyMergeStatus.mergeable) {
       // Issue #1363: Before concluding "no CI configured", verify the repo actually
       // has no active GitHub Actions workflows. If workflows exist but no checks have
@@ -972,8 +985,14 @@ export const getMergeBlockers = async (owner, repo, prNumber, verbose = false, c
   }
 
   if (!mergeStatus.mergeable) {
+    // Issue #2182: a draft pull request gets its own blocker type. GitHub keeps
+    // reporting mergeable=MERGEABLE/CLEAN for drafts, so before this the loop
+    // saw no blocker at all, declared "PR IS MERGEABLE!" and then failed the
+    // actual merge with "Pull Request is still a draft" on every check for
+    // 4d 12h. The dedicated type also lets the caller self-heal (mark ready)
+    // instead of burning an AI restart iteration on it.
     blockers.push({
-      type: 'not_mergeable',
+      type: mergeStatus.isDraft ? 'draft' : 'not_mergeable',
       message: mergeStatus.reason || 'PR is not mergeable',
       details: [],
     });