@link-assistant/hive-mind 2.1.1 → 2.1.3

package/src/live-input-capabilities.lib.mjs

@@ -0,0 +1,221 @@
+/**
+ * Shared capability matrix for live issue/PR event input.
+ *
+ * Issue #2007 asks solve to feed issue/PR events into the running AI tool "in
+ * all ways possible", and to provide a universal fallback for every tool that
+ * does not have a mid-session live input channel: wait for the current turn to
+ * finish in the JSON output, stop the process, and resume the AI session with
+ * the new events.
+ *
+ * Because of that fallback, live event input is *available* for every tool.
+ * Tools differ only in the delivery `mode`:
+ *
+ *   - `stream`  : the tool exposes a live stdin/JSON channel, so new events are
+ *                 written into the running process without restarting it. Claude
+ *                 and Agent (`--input-format stream-json`) are wired for this today.
+ *   - `fallback`: no verified mid-session input channel exists yet, so solve uses
+ *                 the restart/resume loop (`--auto-restart-until-mergeable` /
+ *                 `watchUntilMergeable`). It waits for the current session to end,
+ *                 then resumes/restarts the AI with the new issue/PR events as
+ *                 feedback. This works for every tool.
+ *
+ * Missing native live-input features for each tool are reported upstream in the
+ * https://github.com/link-assistant/agent repository so they can be implemented
+ * (see `agentIssue`), after which a tool can graduate from `fallback` to `stream`.
+ */
+
+export const ISSUE_2007_REQUIRED_EVENT_IDS = Object.freeze(['issue-title', 'issue-body', 'issue-comments', 'pull-request-comments']);
+
+export const LIVE_INPUT_EVENT_SOURCES = Object.freeze([
+  Object.freeze({
+    id: 'issue-title',
+    label: 'Issue title updates',
+    requiredByIssue2007: true,
+    note: 'User-facing issue metadata should be streamed when it changes during a run.',
+  }),
+  Object.freeze({
+    id: 'issue-body',
+    label: 'Issue description updates',
+    requiredByIssue2007: true,
+    note: 'The issue body is treated as user feedback because it can change after the agent starts.',
+  }),
+  Object.freeze({
+    id: 'issue-comments',
+    label: 'Issue comments',
+    requiredByIssue2007: true,
+    note: 'New non-system issue comments are user feedback.',
+  }),
+  Object.freeze({
+    id: 'pull-request-comments',
+    label: 'Pull request comments',
+    requiredByIssue2007: true,
+    note: 'New non-system PR conversation comments and review comments should reach the agent.',
+  }),
+  Object.freeze({
+    id: 'pull-request-description',
+    label: 'Pull request description updates',
+    requiredByIssue2007: false,
+    note: 'Issue #2007 explicitly treats the PR description as AI-owned, so it is not a required user-feedback source.',
+  }),
+]);
+
+const REQUIRED_EVENTS = ISSUE_2007_REQUIRED_EVENT_IDS;
+
+// Delivery modes for live issue/PR event input.
+export const LIVE_INPUT_MODE_STREAM = 'stream';
+export const LIVE_INPUT_MODE_FALLBACK = 'fallback';
+
+// Shared description of the universal restart/resume fallback so every tool
+// entry reports it identically.
+const FALLBACK_DESCRIPTION = 'Universal fallback: wait for the current AI turn to finish in the JSON output, stop the process, then resume/restart the AI session with the new issue/PR events as feedback via --auto-restart-until-mergeable (watchUntilMergeable). Works for every tool even without a live stdin channel.';
+
+const CAPABILITIES = Object.freeze({
+  claude: Object.freeze({
+    tool: 'claude',
+    label: 'Claude',
+    available: true,
+    mode: LIVE_INPUT_MODE_STREAM,
+    liveStreaming: true,
+    supported: true,
+    option: '--auto-input-until-mergeable',
+    protocol: 'claude --input-format stream-json stdin NDJSON',
+    currentRunner: 'src/claude.lib.mjs keeps stdin as a pipe and attaches bidirectional-interactive.lib.mjs',
+    futureProtocol: '',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: '',
+    unsupportedReason: '',
+    testing: 'Run solve with --tool claude --auto-input-until-mergeable, add an issue or PR comment while the Claude process is alive, and watch for the bidirectional handler to queue or stream a user frame into stdin.',
+  }),
+  codex: Object.freeze({
+    tool: 'codex',
+    label: 'Codex',
+    available: true,
+    mode: LIVE_INPUT_MODE_FALLBACK,
+    liveStreaming: false,
+    supported: false,
+    option: '--auto-input-until-mergeable',
+    protocol: 'Restart/resume fallback (no live stdin wired through solve for Codex yet).',
+    currentRunner: 'src/codex.lib.mjs uses codex exec with prompt/stdin context at process start',
+    futureProtocol: 'Codex app-server JSON-RPC turn/steer',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: 'https://github.com/link-assistant/agent/issues',
+    unsupportedReason: 'The current solve Codex runner uses codex exec, whose stdin is one-shot prompt/context at process start. It does not expose a live JSON input pipe for mid-session issue/PR events, so the restart/resume fallback is used. Codex app-server turn/steer is the candidate protocol for a future live-streaming Codex runner.',
+    testing: 'Passing --tool codex --auto-input-until-mergeable activates the restart/resume fallback: the run finishes the current session, then resumes with the new issue/PR events.',
+  }),
+  agent: Object.freeze({
+    tool: 'agent',
+    label: 'Agent',
+    available: true,
+    mode: LIVE_INPUT_MODE_STREAM,
+    liveStreaming: true,
+    supported: true,
+    option: '--auto-input-until-mergeable',
+    protocol: 'agent --input-format stream-json --output-format stream-json stdin/stdout NDJSON',
+    currentRunner: 'src/agent.lib.mjs keeps stdin as a pipe and attaches bidirectional-interactive.lib.mjs when live input is enabled',
+    futureProtocol: '',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: 'https://github.com/link-assistant/agent/pull/274',
+    unsupportedReason: '',
+    testing: 'Run solve with --tool agent --auto-input-until-mergeable, add an issue or PR comment while the Agent process is alive, and watch for the bidirectional handler to queue or stream a user frame into stdin.',
+  }),
+  opencode: Object.freeze({
+    tool: 'opencode',
+    label: 'OpenCode',
+    available: true,
+    mode: LIVE_INPUT_MODE_FALLBACK,
+    liveStreaming: false,
+    supported: false,
+    option: '--auto-input-until-mergeable',
+    protocol: 'Restart/resume fallback (no live JSON input channel wired through solve for OpenCode yet).',
+    currentRunner: 'src/opencode.lib.mjs uses a prompt-via-file/stdin pattern',
+    futureProtocol: '',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: 'https://github.com/link-assistant/agent/issues',
+    unsupportedReason: 'No verified live JSON input channel is wired through solve for OpenCode yet, so the restart/resume fallback is used.',
+    testing: 'Passing --tool opencode --auto-input-until-mergeable activates the restart/resume fallback.',
+  }),
+  gemini: Object.freeze({
+    tool: 'gemini',
+    label: 'Gemini',
+    available: true,
+    mode: LIVE_INPUT_MODE_FALLBACK,
+    liveStreaming: false,
+    supported: false,
+    option: '--auto-input-until-mergeable',
+    protocol: 'Restart/resume fallback (no live JSON input channel wired through solve for Gemini yet).',
+    currentRunner: 'src/gemini.lib.mjs uses a prompt-driven process invocation',
+    futureProtocol: '',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: 'https://github.com/link-assistant/agent/issues',
+    unsupportedReason: 'No verified live JSON input channel is wired through solve for Gemini yet, so the restart/resume fallback is used.',
+    testing: 'Passing --tool gemini --auto-input-until-mergeable activates the restart/resume fallback.',
+  }),
+  qwen: Object.freeze({
+    tool: 'qwen',
+    label: 'Qwen',
+    available: true,
+    mode: LIVE_INPUT_MODE_FALLBACK,
+    liveStreaming: false,
+    supported: false,
+    option: '--auto-input-until-mergeable',
+    protocol: 'Restart/resume fallback (no live JSON input channel wired through solve for Qwen yet).',
+    currentRunner: 'src/qwen.lib.mjs uses a prompt-driven process invocation',
+    futureProtocol: '',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: 'https://github.com/link-assistant/agent/issues',
+    unsupportedReason: 'No verified live JSON input channel is wired through solve for Qwen yet, so the restart/resume fallback is used.',
+    testing: 'Passing --tool qwen --auto-input-until-mergeable activates the restart/resume fallback.',
+  }),
+});
+
+const UNKNOWN_CAPABILITY = tool =>
+  Object.freeze({
+    tool,
+    label: tool,
+    available: true,
+    mode: LIVE_INPUT_MODE_FALLBACK,
+    liveStreaming: false,
+    supported: false,
+    option: '--auto-input-until-mergeable',
+    protocol: 'Restart/resume fallback (no live JSON input channel wired through solve for this tool yet).',
+    currentRunner: 'Unknown or custom solve tool runner',
+    futureProtocol: '',
+    fallback: FALLBACK_DESCRIPTION,
+    events: REQUIRED_EVENTS,
+    agentIssue: 'https://github.com/link-assistant/agent/issues',
+    unsupportedReason: `No verified live JSON input channel is wired through solve for ${tool}, so the restart/resume fallback is used. Add a live-input capability entry (and report the missing native API to link-assistant/agent) once the runner has a long-lived stdin, JSON-RPC, or SDK channel that accepts new user turns mid-session.`,
+    testing: 'The flag activates the restart/resume fallback until a live-streaming runner is implemented.',
+  });
+
+export const getLiveInputCapability = tool => {
+  const normalizedTool = String(tool || '')
+    .trim()
+    .toLowerCase();
+  return CAPABILITIES[normalizedTool] || UNKNOWN_CAPABILITY(normalizedTool || 'unknown');
+};
+
+/**
+ * Whether the tool has a live *streaming* input channel (writes events into the
+ * running process). Kept as `isLiveInputSupported` for backward compatibility;
+ * it is the stream-mode predicate, not "is live input available at all".
+ */
+export const isLiveInputSupported = tool => getLiveInputCapability(tool).mode === LIVE_INPUT_MODE_STREAM;
+
+/**
+ * Whether live issue/PR event input is available for the tool in *any* mode
+ * (streaming or restart/resume fallback). This is true for every tool.
+ */
+export const isLiveInputAvailable = tool => getLiveInputCapability(tool).available === true;
+
+/**
+ * Resolve the delivery mode ('stream' or 'fallback') for a tool.
+ */
+export const getLiveInputMode = tool => getLiveInputCapability(tool).mode;
+
+export const getLiveInputCapabilityRows = () => Object.values(CAPABILITIES);

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

@@ -956,9 +956,75 @@ export const getMergeBlockers = async (owner, repo, prNumber, verbose = false, c
   return { blockers, ciStatus, noCiConfigured: false, noCiTriggered: false, noWorkflowRunsForCommit };
 };
 
+/**
+ * Issue #2007: Detect issue title/description changes across auto-restart
+ * iterations so the restart/resume fallback can deliver them as feedback for
+ * tools without a live input channel.
+ *
+ * The issue title and body are user-owned feedback surfaces (unlike the PR
+ * description, which #2007 treats as AI-owned). When they change while the AI
+ * is not streaming input, the next session must be told, otherwise the update
+ * would be silently ignored until the agent happens to re-read the issue.
+ *
+ * The first call (previousSnapshot = null) establishes the baseline and reports
+ * no change. Subsequent calls diff against the prior snapshot.
+ *
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number} issueNumber - Linked issue number
+ * @param {Object|null} previousSnapshot - Prior { title, body } snapshot, or null on first call
+ * @param {boolean} [verbose=false]
+ * @param {Function} [commandRunner=$] - Tagged-template command runner (injectable for tests)
+ * @returns {Promise<{changed: boolean, snapshot: Object|null, changes: Array<{field: string, from: string, to: string}>}>}
+ */
+export const checkForIssueMetadataChanges = async (owner, repo, issueNumber, previousSnapshot, verbose = false, commandRunner = $) => {
+  const empty = { changed: false, snapshot: previousSnapshot || null, changes: [] };
+  if (!issueNumber) return empty;
+
+  let snapshot;
+  try {
+    const result = await commandRunner`gh api repos/${owner}/${repo}/issues/${issueNumber} --jq '{title: .title, body: .body}'`;
+    if (result.code !== 0 || !result.stdout) return empty;
+    const parsed = JSON.parse(result.stdout.toString() || '{}');
+    snapshot = {
+      title: typeof parsed.title === 'string' ? parsed.title : '',
+      body: typeof parsed.body === 'string' ? parsed.body : '',
+    };
+  } catch (error) {
+    reportError(error, {
+      context: 'check_issue_metadata_changes',
+      owner,
+      repo,
+      issueNumber,
+      operation: 'fetch_issue_metadata',
+    });
+    return empty;
+  }
+
+  // First observation: establish the baseline without reporting a change.
+  if (!previousSnapshot) {
+    return { changed: false, snapshot, changes: [] };
+  }
+
+  const changes = [];
+  if (snapshot.title !== previousSnapshot.title) {
+    changes.push({ field: 'title', from: previousSnapshot.title, to: snapshot.title });
+  }
+  if (snapshot.body !== previousSnapshot.body) {
+    changes.push({ field: 'body', from: previousSnapshot.body, to: snapshot.body });
+  }
+
+  if (verbose && changes.length > 0) {
+    console.log(`[VERBOSE] Issue #${issueNumber} metadata changed: ${changes.map(c => c.field).join(', ')}`);
+  }
+
+  return { changed: changes.length > 0, snapshot, changes };
+};
+
 export default {
   checkForExistingComment,
   checkForNonBotComments,
+  checkForIssueMetadataChanges,
   getMergeBlockers,
   shouldResetNoRunsCounter,
 };

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

@@ -59,7 +59,7 @@ import { limitReset } from './config.lib.mjs';
 
 // Import helper functions extracted for file size management (Issue #1593)
 const autoMergeHelpers = await import('./solve.auto-merge-helpers.lib.mjs');
-const { checkForExistingComment, checkForNonBotComments, getMergeBlockers, shouldResetNoRunsCounter, trackAuthenticatedUserCommentsSince, nextMonotonicCheckTime } = autoMergeHelpers;
+const { checkForExistingComment, checkForNonBotComments, checkForIssueMetadataChanges, getMergeBlockers, shouldResetNoRunsCounter, trackAuthenticatedUserCommentsSince, nextMonotonicCheckTime } = autoMergeHelpers;
 
 // Issue #1769: cancelled/stale CI re-run failures need a human action stop, not polling forever.
 const cancelledCiRerunLib = await import('./cancelled-ci-rerun.lib.mjs');
@@ -137,7 +137,7 @@ export const watchUntilMergeable = async params => {
   await log(formatAligned('', 'Max limit resumes:', formatAutoIterationLimit(maxAutoResumeIterations), 2));
   await log(formatAligned('', 'Wait for all repo actions:', waitForAllRepoActionsFlag ? 'Yes (strict repo-wide safety)' : 'No (PR-scoped CI only)', 2));
   await log(formatAligned('', 'Stop conditions:', 'PR merged, PR closed, or becomes mergeable', 2));
-  await log(formatAligned('', 'Restart triggers:', 'New non-bot comments, CI failures, merge conflicts', 2));
+  await log(formatAligned('', 'Restart triggers:', 'New non-bot comments, issue title/description edits, CI failures, merge conflicts', 2));
   // Issue #1708: Surface that --auto-input-until-mergeable streamed feedback
   // into the prior session, so any restart triggered here is a fallback.
   if (argv.autoInputUntilMergeable) {
@@ -157,6 +157,11 @@ export const watchUntilMergeable = async params => {
   let iteration = 0;
   let lastCheckTime = new Date();
 
+  // Issue #2007: Track the issue title/body across iterations so the
+  // restart/resume fallback can detect user edits to those surfaces and deliver
+  // them as feedback to the next session. The first check seeds the baseline.
+  let issueMetadataSnapshot = null;
+
   while (true) {
     iteration++;
     const currentTime = new Date();
@@ -250,6 +255,14 @@ export const watchUntilMergeable = async params => {
         trustAuthenticatedUserComments: true,
       });
 
+      // Issue #2007: Detect issue title/description edits (user-owned feedback
+      // surfaces) so the fallback resumes the AI with them. The first iteration
+      // seeds the baseline and never reports a change.
+      const metadataCheck = await checkForIssueMetadataChanges(owner, repo, issueNumber, issueMetadataSnapshot, argv.verbose, $);
+      issueMetadataSnapshot = metadataCheck.snapshot || issueMetadataSnapshot;
+      const hasIssueMetadataChanges = metadataCheck.changed === true;
+      const issueMetadataChanges = metadataCheck.changes || [];
+
       // Check for uncommitted changes using shared utility
       const hasUncommittedChanges = await checkForUncommittedChanges(tempDir, argv);
 
@@ -264,8 +277,9 @@ export const watchUntilMergeable = async params => {
         }
       }
 
-      // If PR is mergeable, no blockers, no new comments, and no uncommitted changes
-      if (blockers.length === 0 && !hasNewComments && !hasUncommittedChanges) {
+      // If PR is mergeable, no blockers, no new comments, no issue metadata
+      // edits, and no uncommitted changes
+      if (blockers.length === 0 && !hasNewComments && !hasIssueMetadataChanges && !hasUncommittedChanges) {
         // Issue #1503 (enhanced): Multi-mechanism consensus + repo-wide action check.
         // Before declaring PR mergeable, run multiple independent CI detection mechanisms
         // and require all to agree. This catches race conditions where CI starts between
@@ -420,6 +434,21 @@ export const watchUntilMergeable = async params => {
         feedbackLines.push('Please review and address the feedback from these comments.');
       }
 
+      // Issue #2007: Reason 1b: Issue title/description edited by the user.
+      if (hasIssueMetadataChanges) {
+        shouldRestart = true;
+        const changedFields = issueMetadataChanges.map(c => (c.field === 'title' ? 'title' : 'description')).join(' and ');
+        restartReason = restartReason ? `${restartReason}; Issue ${changedFields} edited` : `Issue ${changedFields} edited`;
+        feedbackLines.push(`✏️ The issue ${changedFields} was edited after the last session:`);
+        for (const change of issueMetadataChanges) {
+          const label = change.field === 'title' ? 'Issue title' : 'Issue description';
+          const updated = String(change.to ?? '');
+          feedbackLines.push(`  - ${label} is now: "${updated.substring(0, 200)}${updated.length > 200 ? '...' : ''}"`);
+        }
+        feedbackLines.push('');
+        feedbackLines.push('Please re-read the updated issue and make sure your solution still matches the requirements.');
+      }
+
       // Issue #1314: Check for billing limit errors BEFORE regular CI failures
       // Billing limits require human intervention and should NOT trigger AI restarts
       const billingBlocker = blockers.find(b => b.type === 'billing_limit');
@@ -581,7 +610,7 @@ Once the billing issue is resolved, you can re-run the CI checks or push a new c
       // take the restart path rather than the cancelled-review path.
       const ciBlocker = ciFailureBlocker;
       const hasMergeConflictBlocker = blockers.some(b => b.type === 'not_mergeable' && b.message?.includes('conflicts'));
-      if (externalReviewLimitBlocker && !ciBlocker && !billingBlocker && !cancelledBlocker && !hasNewComments && !hasUncommittedChanges && !hasMergeConflictBlocker) {
+      if (externalReviewLimitBlocker && !ciBlocker && !billingBlocker && !cancelledBlocker && !hasNewComments && !hasIssueMetadataChanges && !hasUncommittedChanges && !hasMergeConflictBlocker) {
         await log('');
         await log(formatAligned('🟡', 'READY FOR REVIEW', 'External review quota/credit limit requires human decision'));
         for (const detail of externalReviewLimitBlocker.details || []) {

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' }) {