@link-assistant/hive-mind 2.15.0 → 2.15.2

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @link-assistant/hive-mind
 
+## 2.15.2
+
+### Patch Changes
+
+- c1f6a41: Authenticate git downloads so a run no longer dies with `Reason: Repository setup failed` (issue #2192).
+
+  A run ended after three clone attempts, each answered by GitHub with `fatal: remote error: GitHub is temporarily limiting some unauthenticated downloads to protect the stability of the platform. Please retry later or authenticate.` — while every `gh api` call in the same process succeeded. Three defects lined up, and each is fixed:
+
+  - **Public clones were sent anonymously even though a token was available.** `gh auth setup-git` installs a credential helper, but git only consults a helper after the server answers `401`, and github.com answers `200` for a public repository. Measured with `GIT_TRACE_CURL=1`, a public `git clone`/`gh repo clone` sent **0** `Authorization` headers. The new `src/git-auth-transport.lib.mjs` sends the token preemptively via `http.https://github.com/.extraheader`, injected through `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n` environment variables (**3** headers now sent) — so the token never reaches `.git/config` or a command line, and every git child process (`clone`, `fetch`, `pull`, `push`, `gh repo clone`) inherits it. `HIVE_MIND_DISABLE_GIT_AUTH_TRANSPORT=1` opts out.
+  - **The refusal was reported as `Unknown error`.** `classifyCloneError` now returns `ANONYMOUS_RATE_LIMIT`, and `src/transient-errors.lib.mjs` gains the shared `github-anonymous-rate-limit` category, so the log names the real cause and the "How to fix" section stops suggesting `gh auth login` to an already-logged-in run.
+  - **Retries only slept.** The clone loop and `gitCmdRetry` now upgrade the transport before the next attempt, falling back to `gh-setup-git-identity --repair` (non-interactive) when no token is reachable; only a genuinely absent token still fails.
+
+  Authentication now happens _before_ the first clone in `setupRepositoryAndClone`, `review`, and `create-test-repo`. Full analysis, the run log excerpts and a reproduction script are in `docs/case-studies/issue-2192/`.
+
+## 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.2",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/git-auth-transport.lib.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+/**
+ * Authenticated git HTTPS transport for github.com (issue #2192).
+ *
+ * A `solve` run died with `Reason: Repository setup failed` after three clone
+ * attempts, each rejected by GitHub with:
+ *
+ *   fatal: remote error: GitHub is temporarily limiting some unauthenticated
+ *   downloads to protect the stability of the platform. Please retry later or
+ *   authenticate.
+ *
+ * The container *was* authenticated: every `gh` API call in the same run
+ * succeeded, and `gh auth setup-git` had installed
+ * `credential.https://github.com.helper = !gh auth git-credential`.
+ *
+ * A credential helper does not help here. git only asks the helper for
+ * credentials **after** the server answers `401`, and github.com answers `200`
+ * for a public repository — so a public clone is performed anonymously even
+ * when a token is sitting right there. Verified with `GIT_TRACE_CURL=1`:
+ * `git clone` and `gh repo clone` of a public repository send zero
+ * `Authorization` headers with the helper configured (see
+ * `experiments/issue-2192-anonymous-clone-auth.mjs`). Anonymous traffic is what
+ * GitHub throttles, so the run hit the limit and no amount of retrying or
+ * credential-helper repair could have fixed it.
+ *
+ * The remedy is the one GitHub's own `actions/checkout` uses: send the token
+ * preemptively via `http.<host>.extraheader`. Two properties matter here:
+ *
+ *   1. The header is injected through `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_n` /
+ *      `GIT_CONFIG_VALUE_n` environment variables (git >= 2.31) rather than
+ *      written into `.git/config` or passed as `-c` arguments. The token never
+ *      lands in a file the AI session can read back, never appears in a
+ *      process command line visible to `ps`, and is inherited by every git
+ *      child process — `gh repo clone`, `git fetch`, `git pull`, `git push` —
+ *      without touching those ~36 call sites.
+ *   2. Existing `GIT_CONFIG_*` entries are preserved: the new keys are appended
+ *      after whatever the operator (or an outer container) already configured.
+ *
+ * The token value is protected in logs by the existing sanitizer: base64 forms
+ * of known local tokens are masked by `findEncodedKnownTokenRuns`
+ * (issue #2156), and the header is never logged by this module in any case.
+ *
+ * @see docs/case-studies/issue-2192/README.md
+ * @module git-auth-transport
+ */
+
+import { ANONYMOUS_DOWNLOAD_LIMIT_PATTERNS, isAnonymousDownloadLimit } from './transient-errors.lib.mjs';
+
+/** Hosts whose HTTPS git traffic is authenticated by default. */
+export const DEFAULT_AUTHENTICATED_HOSTS = Object.freeze(['github.com']);
+
+/** Env var used as the idempotency marker / diagnostic breadcrumb. */
+export const GIT_AUTH_TRANSPORT_MARKER = 'HIVE_MIND_GIT_AUTH_TRANSPORT';
+
+/** Env var an operator can set to opt out of forced authentication. */
+export const GIT_AUTH_TRANSPORT_DISABLE = 'HIVE_MIND_DISABLE_GIT_AUTH_TRANSPORT';
+
+// GitHub's wording when it refuses an *anonymous* git download lives in the
+// shared transient vocabulary (`transient-errors.lib.mjs`) so classification
+// and repair can never drift apart; re-exported for callers that only import
+// this module.
+export { ANONYMOUS_DOWNLOAD_LIMIT_PATTERNS, isAnonymousDownloadLimit };
+
+/**
+ * Build the `Authorization` header value git should send to github.com.
+ *
+ * GitHub accepts the token as the *password* of HTTP Basic auth with any
+ * username; `x-access-token` is the username `actions/checkout` uses.
+ *
+ * @param {string} token
+ * @returns {string} e.g. `Authorization: Basic eC1hY2Nlc3M...`
+ */
+export const buildAuthorizationHeader = token => `Authorization: Basic ${Buffer.from(`x-access-token:${token}`, 'utf8').toString('base64')}`;
+
+/**
+ * Read the number of `GIT_CONFIG_*` pairs already present in `env`.
+ *
+ * Anything unparseable is treated as zero rather than throwing: a malformed
+ * outer environment must not stop the solver from cloning.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @returns {number}
+ */
+export const readGitConfigCount = env => {
+  const parsed = Number.parseInt(String(env?.GIT_CONFIG_COUNT ?? ''), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+};
+
+/**
+ * True when `env` already carries an `extraheader` entry for every host.
+ *
+ * Recognises entries installed by this module *and* by an outer environment
+ * (a CI runner, a parent container), so authentication configured upstream is
+ * never duplicated.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @param {string[]} [hosts]
+ * @returns {boolean}
+ */
+export const hasGitAuthConfig = (env, hosts = DEFAULT_AUTHENTICATED_HOSTS) => {
+  const count = readGitConfigCount(env);
+  const configuredKeys = new Set();
+  for (let index = 0; index < count; index++) {
+    const key = env?.[`GIT_CONFIG_KEY_${index}`];
+    const value = env?.[`GIT_CONFIG_VALUE_${index}`];
+    if (typeof key === 'string' && typeof value === 'string' && value.trim()) configuredKeys.add(key.toLowerCase());
+  }
+  return hosts.every(host => configuredKeys.has(gitAuthConfigKey(host).toLowerCase()));
+};
+
+/**
+ * git config key that carries the preemptive `Authorization` header for `host`.
+ *
+ * The trailing slash matters: git matches `http.<url>.*` by URL prefix, so
+ * `https://github.com/` covers every repository on the host and nothing else.
+ *
+ * @param {string} host
+ * @returns {string}
+ */
+export const gitAuthConfigKey = host => `http.https://${host}/.extraheader`;
+
+/**
+ * Compute the `GIT_CONFIG_*` variables that add preemptive authentication for
+ * `hosts`, preserving any entries already present in `env`.
+ *
+ * Pure: returns a patch, mutates nothing.
+ *
+ * @param {object} params
+ * @param {string} params.token - GitHub token
+ * @param {string[]} [params.hosts]
+ * @param {Record<string, string|undefined>} [params.env] - environment to extend
+ * @returns {Record<string, string>} variables to merge into the environment
+ */
+export const buildGitAuthConfigEnv = ({ token, hosts = DEFAULT_AUTHENTICATED_HOSTS, env = {} }) => {
+  if (!token) throw new TypeError('buildGitAuthConfigEnv requires a GitHub token');
+  const header = buildAuthorizationHeader(token);
+  const patch = {};
+  let index = readGitConfigCount(env);
+  for (const host of hosts) {
+    patch[`GIT_CONFIG_KEY_${index}`] = gitAuthConfigKey(host);
+    patch[`GIT_CONFIG_VALUE_${index}`] = header;
+    index++;
+  }
+  patch.GIT_CONFIG_COUNT = String(index);
+  patch[GIT_AUTH_TRANSPORT_MARKER] = hosts.join(',');
+  return patch;
+};
+
+/**
+ * True when the operator disabled forced authentication.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @returns {boolean}
+ */
+export const isGitAuthTransportDisabled = (env = process.env) => {
+  const raw = String(env?.[GIT_AUTH_TRANSPORT_DISABLE] ?? '')
+    .trim()
+    .toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes';
+};
+
+/**
+ * Resolve a GitHub token without ever printing it.
+ *
+ * Order: explicit env vars first (an operator override beats stored state),
+ * then `gh auth token`. Returns `{ token, source }` or `{ token: null }`.
+ *
+ * @param {object} params
+ * @param {Function} params.$ - command-stream `$` tag
+ * @param {Record<string, string|undefined>} [params.env]
+ * @returns {Promise<{token: string|null, source: string|null, error: string|null}>}
+ */
+/**
+ * Return the caller's `$` or load command-stream's on demand.
+ *
+ * @param {Function|undefined} provided
+ * @returns {Promise<Function>} command-stream `$` tag
+ */
+export const resolveDollar = async provided => {
+  if (typeof provided === 'function') return provided;
+  // Call sites deep in the retry helpers do not carry a `$` of their own; fall
+  // back to the same command-stream instance the rest of the codebase loads.
+  const { ensureUseM } = await import('./use-m-bootstrap.lib.mjs');
+  const use = globalThis.use || (await ensureUseM());
+  return (await use('command-stream')).$;
+};
+
+export const resolveGitHubToken = async ({ $, env = process.env }) => {
+  for (const name of ['GH_TOKEN', 'GITHUB_TOKEN']) {
+    const value = env?.[name];
+    if (typeof value === 'string' && value.trim()) return { token: value.trim(), source: name, error: null };
+  }
+  try {
+    // `quietProbe` keeps the token out of the mirrored output that becomes the
+    // attached log (issue #2130); the value is only ever used in memory.
+    const { quietProbe } = await import('./quiet-probe.lib.mjs');
+    const result = await quietProbe(await resolveDollar($))`gh auth token`;
+    const token = (result?.stdout?.toString() || '').trim();
+    if (result?.code === 0 && token) return { token, source: 'gh auth token', error: null };
+    return { token: null, source: null, error: (result?.stderr?.toString() || '').trim() || `gh auth token exited ${result?.code}` };
+  } catch (error) {
+    return { token: null, source: null, error: error?.message || String(error) };
+  }
+};
+
+/**
+ * Ensure git sends credentials to github.com preemptively.
+ *
+ * Idempotent, never throws, and safe to call from any entry point: the worst
+ * case (no token, gh not installed, operator opt-out) leaves the environment
+ * exactly as it was and reports why.
+ *
+ * @param {object} params
+ * @param {Function} [params.$] - command-stream `$` tag (loaded on demand when omitted)
+ * @param {Function} [params.log] - logger; called with human-readable lines
+ * @param {Record<string, string|undefined>} [params.env] - environment to mutate (default `process.env`)
+ * @param {string[]} [params.hosts]
+ * @param {string} [params.reason] - short phrase explaining why it was invoked
+ * @param {boolean} [params.repair] - when true, try `gh-setup-git-identity --repair` if no token is found
+ * @returns {Promise<{status: 'applied'|'already-configured'|'disabled'|'no-token', hosts: string[], source?: string|null, error?: string|null}>}
+ */
+export const ensureAuthenticatedGitTransport = async ({ $, log = async () => {}, env = process.env, hosts = DEFAULT_AUTHENTICATED_HOSTS, reason = '', repair = false } = {}) => {
+  if (isGitAuthTransportDisabled(env)) {
+    await log(`ℹ️  Authenticated git transport disabled via ${GIT_AUTH_TRANSPORT_DISABLE}; git will download from github.com anonymously`, { verbose: true });
+    return { status: 'disabled', hosts };
+  }
+
+  if (hasGitAuthConfig(env, hosts)) {
+    // Issue #2192 asks for enough diagnostics to reconstruct the transport state
+    // from a log. Verbose-only: on the happy path this fires before every clone.
+    await log(`🔐 Authenticated git transport already configured for ${hosts.join(', ')}${reason ? ` - ${reason}` : ''}`, { verbose: true });
+    return { status: 'already-configured', hosts };
+  }
+
+  let { token, source, error } = await resolveGitHubToken({ $, env });
+
+  if (!token && repair) {
+    // Issue #2192 asks for auto-recovery of the git/gh state when it is
+    // repairable without interactive credentials. `gh-setup-git-identity`
+    // derives the identity and the credential helper from the authenticated
+    // gh account; it cannot invent a token, so this only helps when gh state
+    // is broken rather than logged out.
+    const { repairGitIdentity } = await import('./git.lib.mjs');
+    const repaired = await repairGitIdentity();
+    await log(repaired.success ? '🔧 Repaired git/gh configuration with gh-setup-git-identity --repair' : `ℹ️  gh-setup-git-identity repair unavailable: ${repaired.error}`, { verbose: !repaired.success });
+    if (repaired.success) ({ token, source, error } = await resolveGitHubToken({ $, env }));
+  }
+
+  if (!token) {
+    await log(`⚠️  No GitHub token available for git transport${error ? ` (${error.split('\n')[0]})` : ''} - downloads from ${hosts.join(', ')} stay anonymous and can be throttled`, { level: 'warning' });
+    return { status: 'no-token', hosts, error };
+  }
+
+  Object.assign(env, buildGitAuthConfigEnv({ token, hosts, env }));
+  await log(`🔐 Authenticated git transport enabled for ${hosts.join(', ')} (token source: ${source})${reason ? ` - ${reason}` : ''}`, { verbose: true });
+  return { status: 'applied', hosts, source };
+};
+
+/**
+ * Point git at `gh` for credentials when nothing is configured yet.
+ *
+ * This is the *401* half of authentication (private repositories, pushes); the
+ * `extraheader` above is the *200* half (public downloads). Both are needed:
+ * neither can replace the other.
+ *
+ * @param {object} params
+ * @param {Function} params.$ - command-stream `$` tag
+ * @param {Function} [params.log]
+ * @param {string} [params.host]
+ * @returns {Promise<{status: 'present'|'configured'|'failed', error?: string}>}
+ */
+export const ensureGlobalCredentialHelper = async ({ $, log = async () => {}, host = 'github.com' }) => {
+  const { quietProbe } = await import('./quiet-probe.lib.mjs');
+  const dollar = await resolveDollar($);
+  const existing = await quietProbe(dollar)`git config --get-all ${`credential.https://${host}.helper`}`;
+  const configured = (existing?.stdout?.toString() || '')
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean);
+  if (configured.length > 0) return { status: 'present' };
+
+  const setup = await quietProbe(dollar)`gh auth setup-git 2>&1`;
+  if (setup?.code === 0) {
+    await log(`🔑 Configured the gh credential helper for ${host}`, { verbose: true });
+    return { status: 'configured' };
+  }
+  const reason = (setup?.stdout?.toString() || setup?.stderr?.toString() || '').trim().split('\n')[0];
+  await log(`ℹ️  Could not configure a global git credential helper for ${host}${reason ? `: ${reason}` : ''}`, { verbose: true });
+  return { status: 'failed', error: reason };
+};
+
+export default {
+  ANONYMOUS_DOWNLOAD_LIMIT_PATTERNS,
+  DEFAULT_AUTHENTICATED_HOSTS,
+  GIT_AUTH_TRANSPORT_DISABLE,
+  GIT_AUTH_TRANSPORT_MARKER,
+  buildAuthorizationHeader,
+  buildGitAuthConfigEnv,
+  ensureAuthenticatedGitTransport,
+  ensureGlobalCredentialHelper,
+  gitAuthConfigKey,
+  hasGitAuthConfig,
+  resolveDollar,
+  isAnonymousDownloadLimit,
+  isGitAuthTransportDisabled,
+  readGitConfigCount,
+  resolveGitHubToken,
+};

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/lib.mjs

@@ -710,6 +710,13 @@ export const gitCmdRetry = async (cmdFn, options = {}) => {
     const description = describeTransientError({ message: combinedOutput });
 
     if (description.transient && attempt < maxAttempts) {
+      // Issue #2192: GitHub rejected the request because it arrived
+      // *unauthenticated*. Waiting does not change that, so authenticate the
+      // transport (repairing the gh state if needed) before the next attempt.
+      if (description.category === 'github-anonymous-rate-limit') {
+        const { ensureAuthenticatedGitTransport } = await import('./git-auth-transport.lib.mjs');
+        await ensureAuthenticatedGitTransport({ log: logFn, repair: true, reason: `${label} rejected as unauthenticated` });
+      }
       const waitTime = delay * Math.pow(backoff, attempt - 1);
       await logFn(`⚠️ ${label}: transient git error (attempt ${attempt}/${maxAttempts}), retrying in ${Math.round(waitTime / 1000)}s... [${formatTransientDiagnostics(description)}]`, { level: 'warn' });
       await sleep(waitTime);

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',