@link-assistant/hive-mind 2.15.0 → 2.15.2

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

@@ -50,6 +50,7 @@ const fs = (await use('fs')).promises;
 import { parseCliArgumentsWithLino } from './cli-arguments.lib.mjs';
 import { QUIET_PROBE } from './quiet-probe.lib.mjs';
 import { reportError } from './sentry.lib.mjs';
+import { ensureAuthenticatedGitTransport } from './git-auth-transport.lib.mjs'; // issue #2192
 import * as memoryCheck from './memory-check.mjs';
 
 // Import Claude execution functions
@@ -244,6 +245,11 @@ try {
   await log(`📝 Files changed: ${prDetails.files.length}`);
 
   // Clone the repository using gh tool with authentication
+  // Issue #2192: authenticate the git transport first. `gh repo clone` of a
+  // public repository sends no Authorization header (the credential helper is
+  // only consulted after a 401, and github.com answers 200), so without this the
+  // clone is anonymous and can be refused by GitHub's unauthenticated-download limiter.
+  await ensureAuthenticatedGitTransport({ $, log, reason: 'review clone' });
   await log(`\nCloning repository ${owner}/${repo} using gh tool...\n`);
   const cloneResult = await $`gh repo clone ${owner}/${repo} ${tempDir}`;
 

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: [],
     });

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { ensureUseM } from './use-m-bootstrap.lib.mjs';
+
+/**
+ * Pre-flight checks that run before the --auto-merge / --auto-restart-until-mergeable
+ * watch loop is entered: mode detection, base-branch guard, fork detection and
+ * merge-permission verification.
+ *
+ * Extracted from solve.auto-merge.lib.mjs (issue #1593) to keep that file under the
+ * 1350-line advisory threshold while the issue #2182 guard rails were added. Same
+ * pattern as solve.auto-merge-attempt.lib.mjs (issue #2144).
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1593
+ */
+
+if (typeof globalThis.use === 'undefined') {
+  await ensureUseM();
+}
+const use = globalThis.use;
+
+const { $: __rawDollar$ } = await use('command-stream');
+const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const $ = wrapDollarWithGhRetry(__rawDollar$);
+
+const lib = await import('./lib.mjs');
+const { log, formatAligned } = lib;
+
+const { checkMergePermissions } = await import('./github-merge.lib.mjs');
+const { checkForExistingComment } = await import('./solve.auto-merge-helpers.lib.mjs');
+const { READY_TO_MERGE_MARKER, postTrackedComment } = await import('./tool-comments.lib.mjs');
+const { ensurePullRequestBaseBranch } = await import('./solve.pr-base-guard.lib.mjs');
+
+/**
+ * Issue #1323: notify the maintainer on the pull request that auto-merge was
+ * requested but cannot be performed, without posting the same comment twice.
+ */
+const postManualMergeNotice = async ({ owner, repo, prNumber, reason, verbose, footer }) => {
+  try {
+    const readyToMergeSignature = `## ✅ ${READY_TO_MERGE_MARKER}`;
+    if (await checkForExistingComment(owner, repo, prNumber, readyToMergeSignature, verbose)) {
+      await log(formatAligned('', `Skipping duplicate "${READY_TO_MERGE_MARKER}" comment`, '', 2));
+      return;
+    }
+    const commentBody = `${readyToMergeSignature}\n\nThis pull request is ready to be merged. Auto-merge was requested (\`--auto-merge\`) but cannot be performed because ${reason}\n\nPlease merge manually.\n\n---\n*${footer}*`;
+    // Issue #1625: Track so this doesn't falsely count as AI-authored.
+    await postTrackedComment({ $, owner, repo, targetNumber: prNumber, body: commentBody });
+    await log(formatAligned('', '💬 Posted merge readiness notification to PR', '', 2));
+  } catch {
+    // Don't fail if comment posting fails
+  }
+};
+
+/**
+ * Run every check that can stop auto-merge before the watch loop starts.
+ *
+ * @param {Object} params - the same params object `startAutoRestartUntilMergeable` receives
+ * @returns {Promise<{stop: boolean, result?: (Object|null)}>} `stop: true` means the
+ *   caller must return `result` immediately instead of entering the watch loop.
+ */
+export const runAutoMergePreflight = async params => {
+  const { argv, owner, repo, prNumber } = params;
+  const isAutoMerge = argv.autoMerge || false;
+  const isAutoRestartUntilMergeable = argv.autoRestartUntilMergeable || false;
+
+  if (!isAutoMerge && !isAutoRestartUntilMergeable) {
+    return { stop: true, result: null }; // Neither mode enabled
+  }
+
+  if (!prNumber) {
+    await log('');
+    await log(formatAligned('⚠️', 'Auto-restart-until-mergeable:', 'Requires a pull request'));
+    await log(formatAligned('', 'Note:', 'This mode only works with existing PRs', 2));
+    return { stop: true, result: null };
+  }
+
+  await ensurePullRequestBaseBranch({
+    owner,
+    repo,
+    prNumber,
+    argv,
+    log,
+    formatAligned,
+    $,
+    onMismatch: isAutoMerge ? 'throw' : 'restore',
+    operation: isAutoMerge ? 'auto-merge' : 'auto-restart-until-mergeable',
+  });
+
+  // Issue #1226: Check if running in fork mode — auto-merge cannot work without write access
+  if (argv.fork && isAutoMerge) {
+    await log('');
+    await log(formatAligned('⚠️', 'Auto-merge:', 'Cannot auto-merge fork PRs'));
+    await log(formatAligned('', 'Reason:', 'Fork contributors do not have write access to merge PRs to upstream repositories', 2));
+    await log(formatAligned('', 'Action:', 'PR is ready for manual merge by a repository maintainer', 2));
+    await log('');
+    await postManualMergeNotice({ owner, repo, prNumber, verbose: argv.verbose, reason: 'this PR was created from a fork (no write access to the target repository).', footer: 'hive-mind with --auto-merge flag (fork mode)' });
+    return { stop: true, result: { success: false, reason: 'fork_no_write_access' } };
+  }
+
+  // Issue #1226: Verify merge permissions before entering the auto-merge/restart loop
+  if (isAutoMerge && owner && repo) {
+    const { canMerge, permission } = await checkMergePermissions(owner, repo, argv.verbose);
+    if (!canMerge) {
+      await log('');
+      await log(formatAligned('⚠️', 'Auto-merge:', 'Insufficient permissions to merge'));
+      await log(formatAligned('', 'Permission level:', permission || 'unknown', 2));
+      await log(formatAligned('', 'Required:', 'push, maintain, or admin access', 2));
+      await log(formatAligned('', 'Action:', 'PR is ready for manual merge by a repository maintainer', 2));
+      await log('');
+      await postManualMergeNotice({ owner, repo, prNumber, verbose: argv.verbose, reason: `the authenticated user lacks write access to \`${owner}/${repo}\` (current permission: \`${permission || 'unknown'}\`).`, footer: 'hive-mind with --auto-merge flag' });
+      return { stop: true, result: { success: false, reason: 'insufficient_permissions' } };
+    }
+  }
+
+  // --auto-merge implies --auto-restart-until-mergeable
+  if (isAutoMerge) {
+    argv.autoRestartUntilMergeable = true;
+  }
+
+  return { stop: false };
+};
+
+export default { runAutoMergePreflight };