@link-assistant/hive-mind 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.1.2
+
+### Patch Changes
+
+- 39164e5: Improve fork-divergence failure comments and logs with inspected branch state, actor-aware admin guidance, exact fork-only commit lists, and less generic repository setup wording.
+
 ## 2.1.1
 
 ### Patch Changes

package/package.json

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

package/src/exit-handler.lib.mjs

@@ -235,14 +235,16 @@ export const logActiveHandles = async (log = null) => {
  * @param {object} [options]
  * @param {boolean} [options.skipPreExit=false] - Issue #1823: skip the pre-exit failure notifier
  *   (e.g. on graceful shutdown, which is NOT a failure and must not post a "solver failed" comment).
+ * @param {string|null} [options.failureActionSection=null] - Optional prebuilt user-facing recovery
+ *   guidance for the pre-exit notifier.
  */
-export const safeExit = async (code = 0, reason = 'Process completed', { skipPreExit = false } = {}) => {
+export const safeExit = async (code = 0, reason = 'Process completed', { skipPreExit = false, failureActionSection = null } = {}) => {
   await showExitMessage(reason, code);
 
   if (!skipPreExit && code !== 0 && preExitFunction && !preExitHandlerRan) {
     preExitHandlerRan = true;
     try {
-      await preExitFunction({ code, reason });
+      await preExitFunction({ code, reason, failureActionSection });
     } catch (error) {
       const message = error && error.message ? error.message : String(error);
       if (logFunction) {

package/src/github.lib.mjs

@@ -31,10 +31,8 @@ const buildIssueFailureActionSection = targetType => {
 
 ### What you can do
 - Resolve the repository, account, permissions, or environment problem described above, then rerun the solver.
-- If this requires elevated Hive Mind access, ask a Hive Mind administrator to handle the specific failure described above.
-- Repository deletion can require a separate GitHub account or token with repository deletion permission; Hive Mind does not rely on that permission by default.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this issue comment.`;
+- Repository owner or Hive Mind administrator path: handle manual recreation or fix of the repository when the required action is outside the requester access.
+- Repository deletion can require a separate GitHub account or token with repository deletion permission; Hive Mind does not rely on that permission by default.`;
 };
 const normalizeFailureActionSection = section => {
   const text = section || '';

package/src/solve.branch-divergence.lib.mjs

@@ -11,11 +11,243 @@ const outputOf = result => {
 
 const shortSha = sha => (sha ? String(sha).slice(0, 12) : null);
 
+export const FORK_DIVERGENCE_RESOLUTION_OPTION = '--allow-fork-divergence-resolution-using-force-push-with-lease';
+
 const encodeRefForGitHubUrl = ref =>
   encodeURI(String(ref || ''))
     .replaceAll('#', '%23')
     .replaceAll('?', '%3F');
 
+const firstLine = value =>
+  String(value || '')
+    .split('\n')
+    .map(line => line.trim())
+    .find(Boolean) || '';
+
+const sameLogin = (left, right) => Boolean(left && right && String(left).toLowerCase() === String(right).toLowerCase());
+
+const formatCommitLine = commit => {
+  const sha = commit?.shortSha || shortSha(commit?.sha) || 'unknown';
+  const author = String(commit?.author || 'unknown author').trim();
+  const subject = String(commit?.subject || 'no subject').trim();
+  return `${sha} ${author} ${subject}`;
+};
+
+const formatCommitBullets = commits => {
+  const safeCommits = Array.isArray(commits) ? commits : [];
+  if (safeCommits.length === 0) return ['- No fork-only commits were returned by the inspection.'];
+  return safeCommits.map(commit => `- \`${formatCommitLine(commit)}\``);
+};
+
+const buildForkCompareUrl = ({ upstreamRepo, forkedRepo, branchName }) => {
+  const [upstreamOwner, upstreamName] = String(upstreamRepo || '').split('/');
+  const [forkOwner] = String(forkedRepo || '').split('/');
+  if (!upstreamOwner || !upstreamName || !forkOwner || !branchName) return null;
+  return `https://github.com/${upstreamRepo}/compare/${encodeRefForGitHubUrl(branchName)}...${encodeRefForGitHubUrl(`${forkOwner}:${branchName}`)}`;
+};
+
+const normalizeForkDivergenceSnapshot = (snapshot = {}) => {
+  const branchName = snapshot.branchName || 'the default branch';
+  const upstreamRepo = snapshot.upstreamRepo || 'the upstream repository';
+  const forkedRepo = snapshot.forkedRepo || 'the fork repository';
+  const forkRef = snapshot.forkRef || `origin/${branchName}`;
+  const upstreamRef = snapshot.upstreamRef || `upstream/${branchName}`;
+  const compareUrl = snapshot.compareUrl || buildForkCompareUrl({ upstreamRepo, forkedRepo, branchName });
+  const uniqueCommits = Array.isArray(snapshot.uniqueCommits) ? snapshot.uniqueCommits : [];
+
+  return {
+    ...snapshot,
+    branchName,
+    upstreamRepo,
+    forkedRepo,
+    forkRef,
+    upstreamRef,
+    compareUrl,
+    uniqueCommits,
+    forkUniqueCount: Number.isFinite(snapshot.forkUniqueCount) ? snapshot.forkUniqueCount : null,
+    upstreamUniqueCount: Number.isFinite(snapshot.upstreamUniqueCount) ? snapshot.upstreamUniqueCount : null,
+  };
+};
+
+const buildActorLine = ({ currentUser, taskRequester }) => {
+  if (sameLogin(currentUser, taskRequester)) {
+    return `Hive Mind is authenticated as \`${currentUser}\`, the same GitHub user that requested this task.`;
+  }
+
+  if (currentUser && taskRequester) {
+    return `Hive Mind is authenticated as \`${currentUser}\`; the task requester is \`${taskRequester}\`.`;
+  }
+
+  if (currentUser) {
+    return `Hive Mind is authenticated as \`${currentUser}\`; the task requester could not be resolved.`;
+  }
+
+  if (taskRequester) {
+    return `The task requester is \`${taskRequester}\`; the authenticated Hive Mind user could not be resolved.`;
+  }
+
+  return 'Hive Mind could not resolve the authenticated user or task requester.';
+};
+
+const buildManualForkRepairCommands = ({ snapshot, solveCommand }) => {
+  const { branchName, forkedRepo, upstreamRef } = snapshot;
+  const commands = ['```bash', `gh repo delete ${forkedRepo} --yes`, `${solveCommand || 'solve <issue-url>'}`, '', '# Manual branch repair after preserving any fork-only commits:', 'git fetch upstream', `git reset --hard ${upstreamRef}`, `git push --force-with-lease origin ${branchName}`, '```'];
+  return commands.join('\n');
+};
+
+export async function getForkDefaultBranchDivergenceSnapshot({ $, tempDir, branchName, forkedRepo, upstreamRepo }) {
+  const forkRef = `origin/${branchName}`;
+  const upstreamRef = `upstream/${branchName}`;
+  const compareUrl = buildForkCompareUrl({ upstreamRepo, forkedRepo, branchName });
+
+  const forkFetchResult = await $({ cwd: tempDir, silent: true })`git fetch origin refs/heads/${branchName}:refs/remotes/origin/${branchName} 2>&1`;
+  if (forkFetchResult.code !== 0) {
+    return {
+      branchName,
+      forkedRepo,
+      upstreamRepo,
+      forkRef,
+      upstreamRef,
+      compareUrl,
+      forkUniqueCount: null,
+      upstreamUniqueCount: null,
+      uniqueCommits: [],
+      fetchError: outputOf(forkFetchResult) || `failed to fetch ${forkRef}`,
+    };
+  }
+
+  const upstreamFetchResult = await $({ cwd: tempDir, silent: true })`git fetch upstream refs/heads/${branchName}:refs/remotes/upstream/${branchName} 2>&1`;
+  if (upstreamFetchResult.code !== 0) {
+    return {
+      branchName,
+      forkedRepo,
+      upstreamRepo,
+      forkRef,
+      upstreamRef,
+      compareUrl,
+      forkUniqueCount: null,
+      upstreamUniqueCount: null,
+      uniqueCommits: [],
+      fetchError: outputOf(upstreamFetchResult) || `failed to fetch ${upstreamRef}`,
+    };
+  }
+
+  const forkUniqueResult = await $({ cwd: tempDir, silent: true })`git rev-list --count ${upstreamRef}..${forkRef} 2>&1`;
+  const upstreamUniqueResult = await $({ cwd: tempDir, silent: true })`git rev-list --count ${forkRef}..${upstreamRef} 2>&1`;
+  const forkHeadResult = await $({ cwd: tempDir, silent: true })`git rev-parse ${forkRef} 2>&1`;
+  const upstreamHeadResult = await $({ cwd: tempDir, silent: true })`git rev-parse ${upstreamRef} 2>&1`;
+  const commitsResult = await $({ cwd: tempDir, silent: true })`git log --format=%H%x09%an%x09%s --max-count=20 ${upstreamRef}..${forkRef} 2>&1`;
+
+  const uniqueCommits =
+    commitsResult.code === 0
+      ? commitsResult.stdout
+          .toString()
+          .trim()
+          .split('\n')
+          .filter(Boolean)
+          .map(line => {
+            const [sha, author, ...subjectParts] = line.split('\t');
+            return {
+              sha,
+              shortSha: shortSha(sha),
+              author,
+              subject: subjectParts.join('\t'),
+            };
+          })
+      : [];
+
+  return {
+    branchName,
+    forkedRepo,
+    upstreamRepo,
+    forkRef,
+    upstreamRef,
+    compareUrl,
+    forkUniqueCount: forkUniqueResult.code === 0 ? toCount(forkUniqueResult.stdout) : null,
+    upstreamUniqueCount: upstreamUniqueResult.code === 0 ? toCount(upstreamUniqueResult.stdout) : null,
+    forkHead: forkHeadResult.code === 0 ? firstLine(forkHeadResult.stdout) : null,
+    upstreamHead: upstreamHeadResult.code === 0 ? firstLine(upstreamHeadResult.stdout) : null,
+    uniqueCommits,
+    inspectError: commitsResult.code === 0 ? null : outputOf(commitsResult),
+  };
+}
+
+export function buildForkDivergenceBlockedReason({ snapshot }) {
+  const details = normalizeForkDivergenceSnapshot(snapshot);
+  const lines = ['Repository setup halted - fork divergence requires user decision.', `Fork: ${details.forkedRepo}`, `Upstream: ${details.upstreamRepo}`, `Branch: ${details.branchName}`];
+
+  if (details.fetchError || details.inspectError) {
+    lines.push(`Inspection error: ${details.fetchError || details.inspectError}`);
+    lines.push('Hive Mind did not recommend automatic force-with-lease because it could not prove whether fork-only commits would be lost.');
+    return lines.join('\n');
+  }
+
+  lines.push(`Fork-only commits that would be overwritten: ${details.forkUniqueCount ?? 'unknown'}`);
+  lines.push(`Upstream-only commits missing from fork: ${details.upstreamUniqueCount ?? 'unknown'}`);
+  if (details.compareUrl) lines.push(`Compare: ${details.compareUrl}`);
+
+  if ((details.forkUniqueCount ?? 0) > 0) {
+    lines.push('Fork-only commit list:');
+    for (const commit of details.uniqueCommits) {
+      lines.push(`- ${formatCommitLine(commit)}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function buildForkDivergenceFailureActionSection({ snapshot = {}, currentUser = null, taskRequester = null, solveCommand = null } = {}) {
+  const details = normalizeForkDivergenceSnapshot(snapshot);
+  const actorLine = buildActorLine({ currentUser, taskRequester });
+  const sameUser = sameLogin(currentUser, taskRequester);
+  const hasInspectionError = Boolean(details.fetchError || details.inspectError);
+  const forkUniqueCount = details.forkUniqueCount;
+  const upstreamUniqueCount = details.upstreamUniqueCount;
+
+  const header = ['### What happened', `- Hive Mind checked \`${details.forkRef}\` in \`${details.forkedRepo}\` against \`${details.upstreamRef}\` in \`${details.upstreamRepo}\`.`, `- ${actorLine}`];
+  if (details.compareUrl) {
+    header.push(`- Compare the branch state: ${details.compareUrl}`);
+  }
+
+  if (hasInspectionError) {
+    header.push(`- The safety inspection failed: ${details.fetchError || details.inspectError}`);
+    return `${header.join('\n')}
+
+### What you can do
+- Hive Mind did not recommend automatic force-with-lease because it could not prove whether fork-only commits would be overwritten.
+- Ask a Hive Mind administrator to handle manual recreation or fix of the repository.
+- Repository owner path: inspect \`${details.forkedRepo}\`, preserve any needed commits, then recreate or repair the fork default branch.`;
+  }
+
+  if (forkUniqueCount === 0) {
+    const rerunLine = sameUser ? `Rerun with \`${FORK_DIVERGENCE_RESOLUTION_OPTION}\` to let Hive Mind update \`${details.forkedRepo}\` using \`git push --force-with-lease origin ${details.branchName}\`.` : `Ask a Hive Mind administrator to rerun with \`${FORK_DIVERGENCE_RESOLUTION_OPTION}\` so Hive Mind can update \`${details.forkedRepo}\` using \`git push --force-with-lease origin ${details.branchName}\`.`;
+
+    return `${header.join('\n')}
+- GitHub inspection found 0 commit(s) unique to \`${details.forkRef}\`; \`${details.forkRef}\` is ${upstreamUniqueCount ?? 'an unknown number of'} commit(s) behind \`${details.upstreamRef}\`.
+
+### What you can do
+- ${rerunLine}
+- Delete or recreate the fork repository, or fix the repository manually, using these commands when you own the fork or are acting as the Hive Mind administrator:
+
+${buildManualForkRepairCommands({ snapshot: details, solveCommand })}`;
+  }
+
+  const administratorLine = sameUser ? 'Delete or recreate the fork repository, or fix the repository manually, after preserving the fork-only commits listed above.' : 'Ask a Hive Mind administrator to handle manual recreation or fix of the repository.';
+
+  return `${header.join('\n')}
+- \`${details.forkRef}\` has ${forkUniqueCount ?? 'an unknown number of'} commit(s) unique to \`${details.forkRef}\`; replacing it with \`${details.upstreamRef}\` would remove them from the fork default branch history.
+
+### Commits that would be lost
+${formatCommitBullets(details.uniqueCommits).join('\n')}
+
+### What you can do
+- ${administratorLine}
+- Preserve the listed commit(s) first by moving them to another branch, cherry-picking them later, or confirming they are disposable.
+- Manual repair example after preserving the listed commits:
+
+${buildManualForkRepairCommands({ snapshot: details, solveCommand })}`;
+}
+
 export function classifyPushRejection(errorOutput = '') {
   const normalized = String(errorOutput || '').toLowerCase();
 
@@ -138,9 +370,7 @@ export function buildPushRejectionFailureActionSection({ owner, repo, branchName
 - Inspect the remote branch: ${links.branchUrl}
 - Compare the base and head branches: ${links.compareUrl}
 - If the remote branch already contains the intended commit, rerun the solver. Matching remote branches are treated as usable after this fix.
-- If the histories differ, merge or resolve \`${links.headBranchRef}\` against \`${links.baseBranchRef}\`, then rerun the solver.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this GitHub comment.`;
+- Diverged-history path: merge or resolve \`${links.headBranchRef}\` against \`${links.baseBranchRef}\`, then rerun the solver.`;
 }
 
 export function buildPushRejectionExplanation({ branchName, isContinueMode, prNumber, divergence = null, owner = null, repo = null, defaultBranch = null, forkedRepo = null, classification = 'unknown' }) {

package/src/solve.fork-sync.lib.mjs

@@ -26,7 +26,80 @@ import { safeExit } from './exit-handler.lib.mjs';
 // Issue #1893: helpers that decide whether the fork's default branch may be
 // pushed and that distinguish a permission-denied rejection from a genuine
 // fork divergence.
-const { isPermissionDeniedPushError, shouldPushDefaultBranchToFork } = await import('./solve.branch-divergence.lib.mjs');
+const { buildForkDivergenceBlockedReason, buildForkDivergenceFailureActionSection, getForkDefaultBranchDivergenceSnapshot, isPermissionDeniedPushError, shouldPushDefaultBranchToFork } = await import('./solve.branch-divergence.lib.mjs');
+
+const firstNonEmptyLine = value =>
+  String(value || '')
+    .split('\n')
+    .map(line => line.trim())
+    .find(Boolean) || '';
+
+const resolveSolveCommand = argv => {
+  const issueUrl = argv.url || argv['issue-url'] || argv._?.[0] || '<issue-url>';
+  return `solve ${issueUrl}`;
+};
+
+const extractGitHubUrlNumber = argv => {
+  const url = String(argv.url || argv['issue-url'] || argv._?.[0] || '');
+  const match = url.match(/github\.com\/[^/]+\/[^/]+\/(issues|pull)\/(\d+)/i);
+  return match ? { type: match[1] === 'pull' ? 'pulls' : 'issues', number: match[2] } : null;
+};
+
+const resolveTaskRequester = async ({ $, owner, repo, argv }) => {
+  const target = extractGitHubUrlNumber(argv);
+  if (!target) return null;
+  const result = await $({ silent: true })`gh api repos/${owner}/${repo}/${target.type}/${target.number} --jq .user.login 2>&1`;
+  return result.code === 0 ? firstNonEmptyLine(result.stdout) : null;
+};
+
+const logForkDivergenceDetails = async ({ snapshot, currentUser, taskRequester, solveCommand, includeAction = true }) => {
+  await log('');
+  await log('  🔍 What happened:');
+  await log(`     Git rejected updating ${snapshot.forkedRepo}:${snapshot.branchName} after Hive Mind synced the local branch to ${snapshot.upstreamRepo}:${snapshot.branchName}.`);
+  await log('');
+  await log('  📦 Current state:');
+  await log(`     Fork: ${snapshot.forkedRepo}`);
+  await log(`     Upstream: ${snapshot.upstreamRepo}`);
+  await log(`     Branch: ${snapshot.branchName}`);
+  if (currentUser) await log(`     Authenticated user: ${currentUser}`);
+  if (taskRequester) await log(`     Task requester: ${taskRequester}`);
+  if (snapshot.compareUrl) await log(`     Compare: ${snapshot.compareUrl}`);
+
+  if (snapshot.fetchError || snapshot.inspectError) {
+    await log('');
+    await log('  ⚠️  Safety check incomplete:');
+    await log(`     ${snapshot.fetchError || snapshot.inspectError}`);
+    await log('     Hive Mind cannot prove whether force-with-lease would overwrite fork-only commits.');
+  } else {
+    await log(`     Fork-only commits: ${snapshot.forkUniqueCount ?? 'unknown'}`);
+    await log(`     Upstream-only commits missing from fork: ${snapshot.upstreamUniqueCount ?? 'unknown'}`);
+    if ((snapshot.forkUniqueCount ?? 0) > 0) {
+      await log('');
+      await log('  ⚠️  Commits that would be lost from the fork default branch:');
+      for (const commit of snapshot.uniqueCommits) {
+        await log(`     - ${commit.shortSha || commit.sha} ${commit.author || 'unknown author'} ${commit.subject || 'no subject'}`);
+      }
+      if (snapshot.uniqueCommits.length < snapshot.forkUniqueCount) {
+        await log(`     - ... ${snapshot.forkUniqueCount - snapshot.uniqueCommits.length} more commit(s) not shown`);
+      }
+    } else {
+      await log('');
+      await log('  ✅ Safety check:');
+      await log(`     No commits unique to ${snapshot.forkRef} were found.`);
+    }
+  }
+
+  const actionSection = buildForkDivergenceFailureActionSection({ snapshot, currentUser, taskRequester, solveCommand });
+  if (includeAction) {
+    await log('');
+    await log('  🔧 GitHub comment guidance:');
+    for (const line of actionSection.split('\n')) {
+      await log(`     ${line}`);
+    }
+  }
+  await log('');
+  return actionSection;
+};
 
 // Set up upstream remote and sync fork
 export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote, owner, repo, argv) => {
@@ -170,16 +243,23 @@ export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote,
                   // Fork has diverged from upstream
                   await log('');
                   await log(`${formatAligned('⚠️', 'FORK DIVERGENCE DETECTED', '')}`, { level: 'warn' });
-                  await log('');
-                  await log('  🔍 What happened:');
-                  await log(`     Your fork's ${upstreamDefaultBranch} branch has different commits than upstream`);
-                  await log('     This typically occurs when upstream had a force push (e.g., git reset --hard)');
-                  await log('');
-                  await log('  📦 Current state:');
-                  await log(`     • Fork: ${forkedRepo}`);
-                  await log(`     • Upstream: ${owner}/${repo}`);
-                  await log(`     • Branch: ${upstreamDefaultBranch}`);
-                  await log('');
+                  const taskRequester = await resolveTaskRequester({ $, owner, repo, argv });
+                  const solveCommand = resolveSolveCommand(argv);
+                  const divergenceSnapshot = await getForkDefaultBranchDivergenceSnapshot({
+                    $,
+                    tempDir,
+                    branchName: upstreamDefaultBranch,
+                    forkedRepo,
+                    upstreamRepo: `${owner}/${repo}`,
+                  });
+                  const failureActionSection = await logForkDivergenceDetails({
+                    snapshot: divergenceSnapshot,
+                    currentUser,
+                    taskRequester,
+                    solveCommand,
+                    includeAction: !argv.allowForkDivergenceResolutionUsingForcePushWithLease,
+                  });
+                  const blockedReason = buildForkDivergenceBlockedReason({ snapshot: divergenceSnapshot });
 
                   // Check if user has enabled automatic force push
                   if (argv.allowForkDivergenceResolutionUsingForcePushWithLease) {
@@ -225,36 +305,12 @@ export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote,
                       await log('     3. Manually sync fork with upstream:');
                       await log('        git fetch upstream');
                       await log(`        git reset --hard upstream/${upstreamDefaultBranch}`);
-                      await log(`        git push --force origin ${upstreamDefaultBranch}`);
+                      await log(`        git push --force-with-lease origin ${upstreamDefaultBranch}`);
                       await log('');
-                      await safeExit(1, 'Repository setup failed - fork sync failed');
+                      await safeExit(1, 'Repository setup failed - fork sync failed', { failureActionSection });
                     }
                   } else {
-                    // Flag is not enabled - provide guidance
-                    await log('  💡 Your options:');
-                    await log('');
-                    await log('     Option 1: Delete your fork and recreate it (SIMPLEST)');
-                    await log(`              gh repo delete ${forkedRepo}`);
-                    await log('              Then run the solve command again - the fork will be recreated automatically');
-                    await log('              ⚠️  Only use this if your fork has no unique commits you need to preserve');
-                    await log('');
-                    await log('     Option 2: Enable automatic force-push (DANGEROUS)');
-                    await log('              Add --allow-fork-divergence-resolution-using-force-push-with-lease flag to your command');
-                    await log('              This will automatically sync your fork with upstream using force-with-lease');
-                    await log('              ⚠️  Overwrites fork history - any unique commits will be LOST');
-                    await log('');
-                    await log('     Option 3: Manually resolve the divergence');
-                    await log('              1. Decide if you need any commits unique to your fork');
-                    await log('              2. If yes, cherry-pick them after syncing');
-                    await log('              3. If no, manually force-push:');
-                    await log('                 git fetch upstream');
-                    await log(`                 git reset --hard upstream/${upstreamDefaultBranch}`);
-                    await log(`                 git push --force origin ${upstreamDefaultBranch}`);
-                    await log('');
-                    await log('  🔧 To proceed with auto-resolution, restart with:');
-                    await log(`     solve ${argv.url || argv['issue-url'] || argv._[0] || '<issue-url>'} --allow-fork-divergence-resolution-using-force-push-with-lease`);
-                    await log('');
-                    await safeExit(1, 'Repository setup halted - fork divergence requires user decision');
+                    await safeExit(1, blockedReason, { failureActionSection });
                   }
                 } else {
                   // Some other push error (not divergence-related)

package/src/solve.mjs

@@ -163,7 +163,7 @@ const cleanupWrapper = async () => {
   }
 };
 const interruptWrapper = createInterruptWrapper({ cleanupContext, checkForUncommittedChanges, shouldAttachLogs, attachLogToGitHub, getLogFile, sanitizeLogContent, $, log });
-initializeExitHandler(getAbsoluteLogPath, log, cleanupWrapper, interruptWrapper, ({ code, reason }) => notifyIssueAboutPrePullRequestFailure({ code, reason, argv, globalState: global, $, log, getLogFile, shouldAttachLogs, attachLogToGitHub, sanitizeLogContent, rawCommand }));
+initializeExitHandler(getAbsoluteLogPath, log, cleanupWrapper, interruptWrapper, ({ code, reason, failureActionSection }) => notifyIssueAboutPrePullRequestFailure({ code, reason, failureActionSection, argv, globalState: global, $, log, getLogFile, shouldAttachLogs, attachLogToGitHub, sanitizeLogContent, rawCommand }));
 installGlobalExitHandlers();
 // Issue #1823: Configure the working-session guard. When the experimental
 // --do-not-shutdown-in-the-middle-of-working-session flag is set (hive passes it to every

package/src/solve.pre-pr-failure-notifier.lib.mjs

@@ -1,7 +1,8 @@
 import { getTrackedToolCommentIds, postTrackedComment, SOLUTION_DRAFT_FAILED_MARKER } from './tool-comments.lib.mjs';
 import { extractForkReplacementBlockedDetails, isForkReplacementBlockedReason } from './solve.repository-recovery-message.lib.mjs';
+import { FORK_DIVERGENCE_RESOLUTION_OPTION, buildForkDivergenceFailureActionSection } from './solve.branch-divergence.lib.mjs';
 
-export const FORK_DIVERGENCE_RESOLUTION_OPTION = '--allow-fork-divergence-resolution-using-force-push-with-lease';
+export { FORK_DIVERGENCE_RESOLUTION_OPTION };
 
 const truncate = (value, maxLength = 2000) => {
   const text = value === null || value === undefined ? '' : String(value);
@@ -40,20 +41,17 @@ export function buildPrePullRequestFailureActionSection(reason = '') {
 - It could not prove whether the existing repository has unique commits, so it did not delete it automatically.
 
 ### What you can do
-- If you control \`${repository}\`, back up any needed work, then delete, rename, archive, or repair it in GitHub and rerun the solver.
-- If you do not control \`${repository}\`, ask the repository owner or a Hive Mind administrator to clean it up and rerun the solver.
-- Use \`--allow-force-non-fork-repository-deletion\` only after confirming that deleting \`${repository}\` is acceptable and any unique commits can be lost.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this GitHub comment.`;
+- Repository owner path: back up any needed work, then delete, rename, archive, or repair \`${repository}\` in GitHub and rerun the solver.
+- External-owner path: ask the repository owner or a Hive Mind administrator to clean it up and rerun the solver.
+- Use \`--allow-force-non-fork-repository-deletion\` only after confirming that deleting \`${repository}\` is acceptable and any unique commits can be lost.`;
   }
 
   if (isForkDivergenceFailure(reason)) {
-    return `### What you can do
-- If the fork's default branch can be overwritten safely, rerun with \`${FORK_DIVERGENCE_RESOLUTION_OPTION}\` to allow a guarded force-with-lease sync.
-- If the fork has commits you need to preserve, resolve the divergence manually, then rerun the solver.
-- If this requires elevated Hive Mind access, ask a Hive Mind administrator to handle the affected fork or repository.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this GitHub comment.`;
+    return buildForkDivergenceFailureActionSection({
+      snapshot: {
+        fetchError: 'No fork divergence inspection data was attached to this failure reason.',
+      },
+    });
   }
 
   if (isPushRejectionFailure(reason)) {
@@ -62,26 +60,20 @@ Administrator-only CLI details, if any, are printed in the solver terminal log r
     return `### What you can do
 - Inspect the remote branch${branchUrl ? `: ${branchUrl}` : ' named in the failure'}.
 - Compare the base and head histories${compareUrl ? `: ${compareUrl}` : ' using the compare link named in the failure'}.
-- If the branch belongs to you, merge the remote branch state or choose a new branch name, then rerun the solver.
-- Do not force-push unless you have manually confirmed that overwriting the remote branch is safe.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this GitHub comment.`;
+- Branch owner path: merge the remote branch state or choose a new branch name, then rerun the solver.
+- Manual force-push remains blocked until a human confirms that overwriting the remote branch is safe.`;
   }
 
   if (isForkOrRecoveryFailure) {
     return `### What you can do
-- If the affected fork or repository belongs to you, remove, rename, archive, initialize, or otherwise repair it in GitHub, then rerun the solver.
-- If the action requires elevated Hive Mind access, ask a Hive Mind administrator to handle the affected fork or repository and rerun the solver.
-- Repository deletion can require a separate GitHub account or token with repository deletion permission; Hive Mind does not rely on that permission by default.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this issue comment.`;
+- Repository owner path: remove, rename, archive, initialize, or otherwise repair the affected fork or repository in GitHub, then rerun the solver.
+- External-owner path: ask a Hive Mind administrator to handle manual recreation or fix of the repository and rerun the solver.
+- Repository deletion can require a separate GitHub account or token with repository deletion permission; Hive Mind does not rely on that permission by default.`;
   }
 
   return `### What you can do
 - Resolve the repository, account, permissions, or environment problem described above, then rerun the solver.
-- If this requires elevated Hive Mind access, ask a Hive Mind administrator to handle the specific failure described above.
-
-Administrator-only CLI details, if any, are printed in the solver terminal log rather than in this issue comment.`;
+- Repository owner or Hive Mind administrator path: handle manual recreation or fix of the repository when the required action is outside the requester access.`;
 }
 
 export function shouldNotifyIssueAboutPrePullRequestFailure({ code, globalState }) {
@@ -128,11 +120,11 @@ export function resolvePreExitFailureNotificationTarget({ code, globalState }) {
   };
 }
 
-export function buildPrePullRequestFailureComment({ reason, owner, repo, issueNumber, argv = {}, logAttachmentAttempted = false }) {
+export function buildPrePullRequestFailureComment({ reason, owner, repo, issueNumber, argv = {}, logAttachmentAttempted = false, failureActionSection = null }) {
   const tool = argv.tool || 'claude';
   const modelLine = argv.model ? `\n- **Requested model**: \`${argv.model}\`` : '';
   const logLine = logAttachmentAttempted ? 'Log attachment was attempted but failed. Check the solver terminal log for the complete failure output.' : 'Logs were not attached because `--attach-logs` was not enabled.';
-  const actionSection = buildPrePullRequestFailureActionSection(reason);
+  const actionSection = failureActionSection || buildPrePullRequestFailureActionSection(reason);
 
   return `## 🚨 ${SOLUTION_DRAFT_FAILED_MARKER}
 
@@ -154,12 +146,12 @@ ${logLine}
 `;
 }
 
-export function buildExistingPullRequestFailureComment({ reason, owner, repo, prNumber, issueNumber = null, argv = {}, logAttachmentAttempted = false }) {
+export function buildExistingPullRequestFailureComment({ reason, owner, repo, prNumber, issueNumber = null, argv = {}, logAttachmentAttempted = false, failureActionSection = null }) {
   const tool = argv.tool || 'claude';
   const modelLine = argv.model ? `\n- **Requested model**: \`${argv.model}\`` : '';
   const issueLine = issueNumber ? `\n- **Linked issue**: #${issueNumber}` : '';
   const logLine = logAttachmentAttempted ? 'Log attachment was attempted but failed. Check the solver terminal log for the complete failure output.' : 'Logs were not attached because `--attach-logs` was not enabled.';
-  const actionSection = buildPrePullRequestFailureActionSection(reason);
+  const actionSection = failureActionSection || buildPrePullRequestFailureActionSection(reason);
 
   return `## 🚨 ${SOLUTION_DRAFT_FAILED_MARKER}
 
@@ -191,7 +183,7 @@ const markNotificationPosted = ({ globalState, targetType }) => {
 };
 
 export async function notifyIssueAboutPrePullRequestFailure(options) {
-  const { code, reason, argv = {}, globalState = globalThis, $, log = async () => {}, getLogFile, shouldAttachLogs = false, attachLogToGitHub, sanitizeLogContent, rawCommand = null, postComment = postTrackedComment } = options;
+  const { code, reason, failureActionSection = null, argv = {}, globalState = globalThis, $, log = async () => {}, getLogFile, shouldAttachLogs = false, attachLogToGitHub, sanitizeLogContent, rawCommand = null, postComment = postTrackedComment } = options;
 
   const target = resolvePreExitFailureNotificationTarget({ code, globalState });
   if (!target) {
@@ -200,6 +192,7 @@ export async function notifyIssueAboutPrePullRequestFailure(options) {
 
   const { owner, repo, issueNumber, prNumber, targetType, targetNumber } = target;
   const targetLabel = targetType === 'pr' ? `pull request #${targetNumber}` : `issue #${targetNumber}`;
+  const actionSection = failureActionSection || buildPrePullRequestFailureActionSection(reason);
   globalState.preExitFailureNotificationInProgress = true;
   if (targetType === 'pr') {
     globalState.pullRequestFailureNotificationInProgress = true;
@@ -223,7 +216,7 @@ export async function notifyIssueAboutPrePullRequestFailure(options) {
           sanitizeLogContent,
           verbose: argv.verbose,
           errorMessage: `${errorPrefix}\n\nReason: ${reason || 'Unknown error'}`,
-          failureActionSection: buildPrePullRequestFailureActionSection(reason),
+          failureActionSection: actionSection,
           argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
@@ -250,6 +243,7 @@ export async function notifyIssueAboutPrePullRequestFailure(options) {
             argv,
             rawCommand,
             logAttachmentAttempted: shouldAttachLogs,
+            failureActionSection: actionSection,
           })
         : buildPrePullRequestFailureComment({
             reason,
@@ -259,6 +253,7 @@ export async function notifyIssueAboutPrePullRequestFailure(options) {
             argv,
             rawCommand,
             logAttachmentAttempted: shouldAttachLogs,
+            failureActionSection: actionSection,
           });
     const posted = await postComment({ $, owner, repo, targetNumber, body });
     if (posted.ok) {