@link-assistant/hive-mind 2.15.0 → 2.15.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @link-assistant/hive-mind
 
+## 2.15.1
+
+### Patch Changes
+
+- 98fb373: Guarantee that a working session converts its pull request back to "ready for review" (issue #2182).
+
+  A task ran for 4d 12h 13m 35s and printed `✅ PR IS MERGEABLE!` 2692 times, each followed by `GraphQL: Pull Request is still a draft (mergePullRequest)`. The pull request was a draft because hive-mind had put it there and never took it back out: over the whole 102 244-line run it performed exactly one draft/ready conversion — `Converting PR: To draft mode` — and zero conversions back. The only draft → ready transition came from the AI model itself, running `gh pr ready 142` because the prompt asked it to.
+
+  **The state machine is now symmetric.** `pr-draft-state.lib.mjs` tracks every draft it hands out, so the matching ready conversion is guaranteed by code rather than requested from the AI:
+
+  - `executeToolIteration` converts the pull request back to ready in a `finally` block, so a crash, an API error or an aborted tool process still ends the iteration with a mergeable pull request. Previously it drafted the pull request (issue #2123) and had no counterpart at all.
+  - `endWorkSession` performs the ready conversion unconditionally. It used to be gated behind `isContinueMode`, which was `false` for the entire reported run, so the one place responsible for the transition never ran. Only the session _comments_ stay gated — they are `--watch`/`--auto-continue` reporting, not state.
+  - `solve.mjs` converts the pull request to ready **before** starting the auto-merge watch loop. The AI working session is over at that point; the loop that follows can run for days, and `endWorkSession()` sits behind it.
+  - The CTRL+C handler and the fatal-error handler drain the outstanding-draft registry, so an aborted session cannot leave a pull request permanently unmergeable. On interrupt this runs before the log upload, which can be cut off by the isolation backend's SIGKILL (issue #2052).
+  - `solve.results.lib.mjs` no longer shells out to `gh pr ready` inline; every transition goes through the state machine, so merged/closed pull requests are skipped and the registry stays accurate.
+
+  The prompt line asking the AI to mark the pull request ready stays, but nothing depends on it any more.
+
+  **Defence in depth** — each of these alone would also have ended the reported run, and they bound the damage of a draft pull request whatever its origin:
+
+  - **`checkPRMergeable` ignored `isDraft`.** A draft pull request with no other blockers reports `mergeable: MERGEABLE` with `mergeStateStatus: CLEAN` — GitHub does not return `DRAFT` there — so the old `mergeable === 'MERGEABLE'` test said yes. Mergeability is now decided by `evaluatePullRequestMergeability`, which treats a draft as not mergeable and reports why. `getMergeBlockers` emits a `draft` blocker on both its normal path and the early "checks have not started yet" path.
+  - **Merge failures were unclassified.** Every failed `gh pr merge` was logged as "Will continue monitoring...", regardless of cause. `classifyMergeError` now sorts the error into draft/conflict/blocked/closed/permission/not-mergeable/unknown, the loop self-heals a draft up to three times by marking the pull request ready, and any category stops after `MAX_CONSECUTIVE_MERGE_FAILURES` (3) instead of retrying indefinitely.
+  - **The watch loop had no wall-clock limit.** `--auto-restart-until-mergeable-timeout-hours` is new and defaults to 24; the loop now checks elapsed time on every pass and stops with a `watch_timeout` reason.
+
+  The single-shot merge attempt, the Telegram merge queue and its wait loop use the same classification, so a draft is skipped with the real reason instead of timing out. Every draft/ready conversion now logs the reason it was made, so the log answers "who drafted this and who was supposed to undo it" directly. Full analysis, the run log excerpts and a reproduction script are in `docs/case-studies/issue-2182/`.
+
 ## 2.15.0
 
 ### Minor Changes

package/package.json

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

package/src/github-merge.lib.mjs

@@ -21,6 +21,9 @@ import { githubLimits } from './config.lib.mjs';
 import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
 import { getTerminalGitHubEntityErrorMessage, isTerminalGitHubEntityError } from './github-terminal-state.lib.mjs';
 import { cancellableSleep } from './interruptible-sleep.lib.mjs';
+// Issue #2182: draft detection and merge-failure classification live in one
+// pure module shared by every merge call site.
+import { classifyMergeError, evaluatePullRequestMergeability } from './merge-error-classification.lib.mjs';
 
 // Issue #1722: gh api `--paginate --slurp` responses for repos with many
 // historical workflow runs can easily exceed Node's default 1 MB exec buffer
@@ -466,7 +469,12 @@ export async function checkPRMergeable(owner, repo, prNumber, verbose = false, o
   for (let attempt = 0; attempt < MAX_UNKNOWN_RETRIES; attempt++) {
     if (isCancelled?.()) return { mergeable: false, reason: 'Operation was cancelled', cancelled: true };
     try {
-      const { stdout } = await exec(`gh pr view ${prNumber} --repo ${owner}/${repo} --json mergeable,mergeStateStatus`);
+      // Issue #2182: `isDraft` MUST be part of this query. GitHub answers
+      // mergeable=MERGEABLE / mergeStateStatus=CLEAN for a draft pull request
+      // with no other blockers, so without this field a draft PR was declared
+      // mergeable and `gh pr merge` failed forever with
+      // "Pull Request is still a draft".
+      const { stdout } = await exec(`gh pr view ${prNumber} --repo ${owner}/${repo} --json isDraft,mergeable,mergeStateStatus`);
       const pr = JSON.parse(stdout.trim());
 
       // Issue #1339: If mergeStateStatus is 'UNKNOWN', GitHub is still computing.
@@ -486,36 +494,16 @@ export async function checkPRMergeable(owner, repo, prNumber, verbose = false, o
         return { mergeable: false, mergeableState: pr.mergeable, mergeStateStatus: pr.mergeStateStatus, reason: `Merge state: UNKNOWN (GitHub could not compute mergeability after ${MAX_UNKNOWN_RETRIES} attempts)` };
       }
 
-      const mergeable = pr.mergeable === 'MERGEABLE';
-      let reason = null;
-
-      if (!mergeable) {
-        switch (pr.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: ${pr.mergeStateStatus || 'unknown'}`;
-        }
-      }
+      const evaluation = evaluatePullRequestMergeability(pr);
 
       if (verbose) {
-        console.log(`[VERBOSE] /merge: PR #${prNumber} mergeable: ${mergeable}, state: ${pr.mergeStateStatus}`);
+        // Issue #2182: isDraft is logged explicitly. In the reported 4.5-day run
+        // the log only ever showed "mergeable: true, state: CLEAN", which hid the
+        // actual blocker.
+        console.log(`[VERBOSE] /merge: PR #${prNumber} mergeable: ${evaluation.mergeable}, state: ${pr.mergeStateStatus}, isDraft: ${pr.isDraft === true}`);
       }
 
-      return { mergeable, mergeableState: pr.mergeable, mergeStateStatus: pr.mergeStateStatus, reason };
+      return { mergeable: evaluation.mergeable, isDraft: evaluation.isDraft, mergeableState: evaluation.mergeableState, mergeStateStatus: evaluation.mergeStateStatus, reason: evaluation.reason };
     } catch (error) {
       if (isTerminalGitHubEntityError(error)) {
         const terminalError = getTerminalGitHubEntityErrorMessage(error);
@@ -607,13 +595,21 @@ export async function mergePullRequest(owner, repo, prNumber, options = {}, verb
 
     return { success: true, error: null };
   } catch (error) {
+    // Issue #2182: classify the failure so watch loops can stop (or self-heal)
+    // instead of retrying an impossible merge every 120 seconds forever.
+    const classification = classifyMergeError(error.message);
     if (verbose) {
       console.log(`[VERBOSE] /merge: Failed to merge PR #${prNumber}: ${error.message}`);
+      console.log(`[VERBOSE] /merge: Failure category: ${classification.category} (terminal=${classification.terminal}, recoverable=${classification.recoverable})`);
     }
-    return { success: false, error: error.message };
+    return { success: false, error: error.message, category: classification.category, terminal: classification.terminal, recoverable: classification.recoverable, resolution: classification.resolution };
   }
 }
 
+// Issue #2182: re-exported so merge call sites can import classification from
+// the same module they already use for merging.
+export { classifyMergeError, evaluatePullRequestMergeability, MERGE_ERROR_CATEGORIES, MAX_CONSECUTIVE_MERGE_FAILURES } from './merge-error-classification.lib.mjs';
+
 /**
  * Parse and validate a repository URL for the merge command
  * @param {string} url - Repository URL

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/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,
+};