@link-assistant/hive-mind 1.76.0 → 1.76.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @link-assistant/hive-mind
 
+## 1.76.1
+
+### Patch Changes
+
+- 13e7e6a: Docker isolation: reuse the host image instead of re-downloading a copy inside the (nested) Docker daemon (#1879).
+  - src/isolation-runner.lib.mjs: add `HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG` to pin the
+    isolation image tag, and `HIVE_MIND_DOCKER_ISOLATION_PULL` (always|missing|never) to emit a
+    `docker run --pull` policy. Verbose mode now logs the resolved image and pull policy.
+  - scripts/preload-dind-isolation-image.mjs: seed a DinD container's nested daemon from the
+    host (`docker save | docker exec -i … docker load`) so isolated tasks reuse the host image.
+  - .env.example: document the Docker isolation image/pull controls.
+  - Dockerfile / Dockerfile.dind / coolify/Dockerfile: bump the box base images to
+    `konard/box:2.2.0` / `konard/box-dind:2.2.0` (and the `docs/UBUNTU-SERVER*.md` examples).
+    v2.2.0 ships box's native host-image passthrough (box#94/#95), so the DinD deployment can seed
+    the nested daemon from the host automatically with
+    `-v /var/run/docker.sock:/var/run/host-docker.sock:ro -e DIND_HOST_PASSTHROUGH=public`.
+  - tests/test-issue-1879-docker-image-reuse.mjs: regression coverage.
+  - docs/case-studies/issue-1879: deep case study with logs, timeline, root causes, and runbook;
+    records that box#94 shipped in v2.2.0 and reports two upstream follow-ups — box#96
+    (public-mode passthrough test false positive) and box#97 (per-repository passthrough allowlist).
+
+- 7335a73: Continue fork PRs with "Allow edits by maintainers" instead of halting on a misclassified fork divergence (#1893).
+
+  When the solver continues a cross-repository PR opened from another contributor's fork, it
+  synced the upstream default branch and then tried to push it back to `origin` — the
+  contributor's fork, which the operating maintainer does not own. GitHub rejected the push
+  with `! [remote rejected] main -> main (permission denied)`, and the solver misclassified
+  that permission error as a fork divergence (the heuristic matched the substring `rejected`),
+  halting with `Repository setup halted - fork divergence requires user decision` and advising
+  `--allow-fork-divergence-resolution-using-force-push-with-lease` — a flag that cannot help,
+  since force-push also requires fork write access.
+  - src/solve.branch-divergence.lib.mjs: add two pure helpers —
+    `shouldPushDefaultBranchToFork({currentUser, forkedRepo})` (skip the push when the user does
+    not own the fork; fail-open when owner/user is unknown) and `isPermissionDeniedPushError()`
+    (recognize a permission-denied rejection so it is never treated as divergence).
+  - src/solve.fork-sync.lib.mjs: new module holding `setupUpstreamAndSync` (extracted from
+    solve.repository.lib.mjs to stay under the 1500-line limit, re-exported unchanged). It now
+    resolves the current user, skips the fork's default-branch push when the user is not the fork
+    owner, and on a permission-denied push warns and continues on the PR branch instead of
+    halting. Genuine non-fast-forward divergence still triggers the original guidance. Adds
+    verbose diagnostics explaining each skip/continue decision.
+  - tests/test-issue-1893-fork-pr-permission-denied.mjs: regression coverage (9 cases) using the
+    exact failure output from the run log.
+  - docs/case-studies/issue-1893: deep case study with downloaded logs/data, timeline, root
+    causes, fix, codebase-wide audit, and existing-components review.
+
 ## 1.76.0
 
 ### Minor Changes

package/package.json

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

package/src/isolation-runner.lib.mjs

@@ -28,8 +28,13 @@ const { $ } = await use('command-stream');
 const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
 const RUNNING_SESSION_STATUSES = new Set(['executing', 'running']);
 const TERMINAL_SESSION_STATUSES = new Set(['executed', 'completed', 'failed', 'cancelled', 'canceled', 'error']);
-const DEFAULT_HIVE_MIND_IMAGE = 'konard/hive-mind:latest';
-const DEFAULT_HIVE_MIND_DIND_IMAGE = 'konard/hive-mind-dind:latest';
+const HIVE_MIND_IMAGE_REPO = 'konard/hive-mind';
+const HIVE_MIND_DIND_IMAGE_REPO = 'konard/hive-mind-dind';
+const DEFAULT_HIVE_MIND_IMAGE_TAG = 'latest';
+// Docker's `--pull` accepts these policies. We only emit the flag when an
+// operator explicitly opts in; otherwise Docker's own default ("missing")
+// applies and `docker run` reuses any locally present image. See issue #1879.
+const VALID_DOCKER_PULL_POLICIES = new Set(['always', 'missing', 'never']);
 const DOCKER_ISOLATION_TRACKING_BACKEND = 'screen';
 const DOCKER_CONTAINER_HOME = '/home/box';
 const DOCKER_CONTAINER_PREFIX = 'hive-mind-isolation';
@@ -79,15 +84,52 @@ function maybeAddMount(mounts, source, target, existsSync) {
   mounts.push({ source, target });
 }
 
+/**
+ * Resolve the tag used for the Docker isolation image.
+ *
+ * Defaults to `latest`, but operators can pin it (e.g. to the exact version
+ * already present on the host) via `HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG`.
+ * Pinning matters for Docker-in-Docker deployments: the nested daemon starts
+ * with an empty image store, so an unpinned `:latest` whose registry digest has
+ * drifted from the host copy forces a fresh multi-gigabyte pull on every task.
+ * A pinned tag lets a pre-seeded image be reused instead. See issue #1879.
+ */
+export function resolveDockerIsolationImageTag({ env = process.env } = {}) {
+  const explicit = String(env.HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG || '').trim();
+  return explicit || DEFAULT_HIVE_MIND_IMAGE_TAG;
+}
+
 /**
  * Pick the Docker image used for `--isolation docker`.
  *
  * start-command defaults its Docker backend to a base OS image. Hive Mind needs
  * an image with the same CLI/tooling baseline as the parent process instead.
+ *
+ * `HIVE_MIND_DOCKER_ISOLATION_IMAGE` is a full override (repo:tag). Otherwise
+ * the repo is chosen by image variant and the tag by
+ * `resolveDockerIsolationImageTag()`.
  */
 export function getDockerIsolationImage({ env = process.env } = {}) {
   if (env.HIVE_MIND_DOCKER_ISOLATION_IMAGE) return env.HIVE_MIND_DOCKER_ISOLATION_IMAGE;
-  return String(env.HIVE_MIND_IMAGE_VARIANT || '').toLowerCase() === 'dind' ? DEFAULT_HIVE_MIND_DIND_IMAGE : DEFAULT_HIVE_MIND_IMAGE;
+  const repo = String(env.HIVE_MIND_IMAGE_VARIANT || '').toLowerCase() === 'dind' ? HIVE_MIND_DIND_IMAGE_REPO : HIVE_MIND_IMAGE_REPO;
+  return `${repo}:${resolveDockerIsolationImageTag({ env })}`;
+}
+
+/**
+ * Resolve the Docker `--pull` policy for isolated tasks.
+ *
+ * Returns one of `always` | `missing` | `never`, or `null` when unset (in which
+ * case the `--pull` flag is omitted and Docker's default applies). Operators set
+ * `HIVE_MIND_DOCKER_ISOLATION_PULL=never` to force reuse of an image already
+ * present in the (possibly nested) daemon and fail fast instead of silently
+ * re-downloading it. Invalid values are ignored. See issue #1879.
+ */
+export function getDockerIsolationPullPolicy({ env = process.env } = {}) {
+  const raw = String(env.HIVE_MIND_DOCKER_ISOLATION_PULL || '')
+    .trim()
+    .toLowerCase();
+  if (!raw) return null;
+  return VALID_DOCKER_PULL_POLICIES.has(raw) ? raw : null;
 }
 
 /**
@@ -123,7 +165,16 @@ export function buildDockerIsolationCommand(command, args = [], options = {}) {
   const { sessionId, tool = 'claude', env = process.env, homeDir = os.homedir(), existsSync = fs.existsSync } = options;
   const image = getDockerIsolationImage({ env });
   const innerCommand = buildShellCommand(command, args);
-  const dockerArgs = ['docker', 'run', '--rm', '--name', makeDockerContainerName(sessionId), '--workdir', DOCKER_CONTAINER_HOME, '-e', `HOME=${DOCKER_CONTAINER_HOME}`, '-e', `HIVE_MIND_PARENT_SESSION_ID=${sessionId || ''}`];
+  const dockerArgs = ['docker', 'run', '--rm'];
+
+  // Reuse a locally present image instead of re-downloading it when the
+  // operator opts in. Omitted by default so Docker's "missing" policy applies.
+  const pullPolicy = getDockerIsolationPullPolicy({ env });
+  if (pullPolicy) {
+    dockerArgs.push('--pull', pullPolicy);
+  }
+
+  dockerArgs.push('--name', makeDockerContainerName(sessionId), '--workdir', DOCKER_CONTAINER_HOME, '-e', `HOME=${DOCKER_CONTAINER_HOME}`, '-e', `HIVE_MIND_PARENT_SESSION_ID=${sessionId || ''}`);
 
   if (shouldRunPrivilegedDockerIsolation(image, env)) {
     dockerArgs.push('--privileged');
@@ -359,9 +410,12 @@ export async function executeWithIsolation(command, args, options = {}) {
   if (verbose) {
     console.log(`[VERBOSE] isolation-runner: ${[binPath, ...startCommandArgs].map(shellQuote).join(' ')}`);
     if (backend === 'docker') {
-      const image = getDockerIsolationImage({ env: options.env || process.env });
-      const mounts = getDockerIsolationAuthMounts({ tool: options.tool, env: options.env || process.env, homeDir: options.homeDir || os.homedir(), existsSync: options.existsSync || fs.existsSync });
+      const env = options.env || process.env;
+      const image = getDockerIsolationImage({ env });
+      const pullPolicy = getDockerIsolationPullPolicy({ env });
+      const mounts = getDockerIsolationAuthMounts({ tool: options.tool, env, homeDir: options.homeDir || os.homedir(), existsSync: options.existsSync || fs.existsSync });
       console.log(`[VERBOSE] isolation-runner: Docker isolation image: ${image}`);
+      console.log(`[VERBOSE] isolation-runner: Docker isolation pull policy: ${pullPolicy || '(docker default: missing — reuse local image if present)'}`);
       console.log(`[VERBOSE] isolation-runner: Docker isolation mounts: ${mounts.map(m => m.target).join(', ') || '(none)'}`);
     }
   }

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

@@ -38,6 +38,61 @@ export function classifyPushRejection(errorOutput = '') {
   return 'unknown';
 }
 
+/**
+ * Detect whether a push failure was caused by missing permissions rather than
+ * by branch divergence. Git surfaces this as `! [remote rejected] ...
+ * (permission denied)` (HTTP 403). This is fundamentally different from a
+ * non-fast-forward / divergence rejection: force-pushing or force-with-lease
+ * will NOT help because the user simply cannot write to the remote.
+ *
+ * Issue #1893: when continuing another contributor's fork PR, the maintainer
+ * does not own the fork, so pushing the fork's default branch is rejected with
+ * "permission denied". The old heuristic matched the substring "rejected" and
+ * misclassified this as fork divergence, halting the run and recommending a
+ * useless `--allow-fork-divergence-resolution-using-force-push-with-lease`.
+ */
+export function isPermissionDeniedPushError(errorOutput = '') {
+  const normalized = String(errorOutput || '').toLowerCase();
+  return normalized.includes('permission denied') || normalized.includes('permission to') || normalized.includes('error: 403') || normalized.includes('the requested url returned error: 403') || (normalized.includes('denied') && normalized.includes('to https://'));
+}
+
+/**
+ * Decide whether the solver should push the freshly-synced default branch to
+ * the fork's `origin` remote.
+ *
+ * We only push the default branch to keep a fork we OWN in sync with upstream.
+ * When continuing someone else's fork PR (the fork belongs to the contributor,
+ * not the current user), the maintainer has push rights only to the PR branch
+ * (via "Allow edits by maintainers"), never to the fork's default branch.
+ * Attempting the push is both impossible (permission denied) and unnecessary,
+ * so we skip it. Issue #1893.
+ *
+ * @param {object} params
+ * @param {string|null} params.currentUser - authenticated GitHub login
+ * @param {string|null} params.forkedRepo - "owner/name" of the fork (origin)
+ * @returns {{ shouldPush: boolean, reason: string, forkOwner: string|null }}
+ */
+export function shouldPushDefaultBranchToFork({ currentUser, forkedRepo } = {}) {
+  const forkOwner = forkedRepo && forkedRepo.includes('/') ? forkedRepo.split('/')[0] : null;
+
+  if (!forkOwner) {
+    // Without a parseable fork owner we cannot prove ownership; fall back to the
+    // historical behaviour of attempting the push so nothing regresses.
+    return { shouldPush: true, reason: 'fork-owner-unknown', forkOwner: null };
+  }
+
+  if (!currentUser) {
+    // Could not resolve the current user; attempt the push and let git report.
+    return { shouldPush: true, reason: 'current-user-unknown', forkOwner };
+  }
+
+  if (currentUser.toLowerCase() === forkOwner.toLowerCase()) {
+    return { shouldPush: true, reason: 'owns-fork', forkOwner };
+  }
+
+  return { shouldPush: false, reason: 'not-fork-owner', forkOwner };
+}
+
 export function shouldTreatPushRejectionAsRemoteSynchronized(divergence = null) {
   if (!divergence?.remoteExists || divergence.ahead !== 0 || divergence.behind !== 0) {
     return false;

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

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+// Fork upstream-sync module for the solve command.
+// Extracted from solve.repository.lib.mjs to keep files under 1500 lines (#1893).
+
+// Use use-m to dynamically import modules for cross-runtime compatibility
+// Check if use is already defined globally (when imported from solve.mjs)
+// If not, fetch it (when running standalone)
+if (typeof globalThis.use === 'undefined') {
+  globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
+}
+const use = globalThis.use;
+
+// Use command-stream for consistent $ behavior; wrap with rate-limit retry (#1726)
+const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const $ = wrapDollarWithGhRetry((await use('command-stream')).$);
+
+// Import shared library functions
+const lib = await import('./lib.mjs');
+const { log, formatAligned } = lib;
+
+// Import exit handler
+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');
+
+// Set up upstream remote and sync fork
+export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote, owner, repo, argv) => {
+  if (!forkedRepo || !upstreamRemote) return;
+
+  await log(`${formatAligned('🔗', 'Setting upstream:', upstreamRemote)}`);
+
+  // Check if upstream remote already exists
+  const checkUpstreamResult = await $({ cwd: tempDir })`git remote get-url upstream 2>/dev/null`;
+  let upstreamExists = checkUpstreamResult.code === 0;
+
+  if (upstreamExists) {
+    await log(`${formatAligned('ℹ️', 'Upstream exists:', 'Using existing upstream remote')}`);
+  } else {
+    // Add upstream remote since it doesn't exist
+    const upstreamResult = await $({ cwd: tempDir })`git remote add upstream https://github.com/${upstreamRemote}.git`;
+
+    if (upstreamResult.code === 0) {
+      await log(`${formatAligned('✅', 'Upstream set:', upstreamRemote)}`);
+      upstreamExists = true;
+    } else {
+      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to add upstream remote')}`);
+      if (upstreamResult.stderr) {
+        await log(`${formatAligned('', 'Error details:', upstreamResult.stderr.toString().trim())}`);
+      }
+    }
+  }
+
+  // Proceed with fork sync if upstream remote is available
+  if (upstreamExists) {
+    // Fetch upstream
+    await log(`${formatAligned('🔄', 'Fetching upstream...', '')}`);
+    const fetchResult = await $({ cwd: tempDir })`git fetch upstream`;
+    if (fetchResult.code === 0) {
+      await log(`${formatAligned('✅', 'Upstream fetched:', 'Successfully')}`);
+
+      // Sync the default branch with upstream to avoid merge conflicts
+      await log(`${formatAligned('🔄', 'Syncing default branch...', '')}`);
+
+      // Get current branch so we can return to it after sync
+      const currentBranchResult = await $({ cwd: tempDir })`git branch --show-current`;
+      if (currentBranchResult.code === 0) {
+        const currentBranch = currentBranchResult.stdout.toString().trim();
+
+        // Get the default branch name from the original repository using GitHub API
+        const repoInfoResult = await $`gh api repos/${owner}/${repo} --jq .default_branch`;
+        if (repoInfoResult.code === 0) {
+          const upstreamDefaultBranch = repoInfoResult.stdout.toString().trim();
+          await log(`${formatAligned('ℹ️', 'Default branch:', upstreamDefaultBranch)}`);
+
+          // Always sync the default branch, regardless of current branch
+          // This ensures fork is up-to-date even if we're working on a different branch
+
+          // Step 1: Switch to default branch if not already on it
+          let syncSuccessful = true;
+          if (currentBranch !== upstreamDefaultBranch) {
+            await log(`${formatAligned('🔄', 'Switching to:', `${upstreamDefaultBranch} branch`)}`);
+            const checkoutResult = await $({ cwd: tempDir })`git checkout ${upstreamDefaultBranch}`;
+            if (checkoutResult.code !== 0) {
+              await log(`${formatAligned('⚠️', 'Warning:', `Failed to checkout ${upstreamDefaultBranch}`)}`);
+              syncSuccessful = false; // Cannot proceed with sync
+            }
+          }
+
+          // Step 2: Sync default branch with upstream (only if checkout was successful)
+          if (syncSuccessful) {
+            const syncResult = await $({ cwd: tempDir })`git reset --hard upstream/${upstreamDefaultBranch}`;
+            if (syncResult.code === 0) {
+              await log(`${formatAligned('✅', 'Default branch synced:', `with upstream/${upstreamDefaultBranch}`)}`);
+
+              // Step 3: Push the updated default branch to fork to keep it in sync.
+              //
+              // Issue #1893: only push the default branch when the current user
+              // OWNS the fork. When continuing another contributor's fork PR the
+              // fork belongs to them, and "Allow edits by maintainers" grants
+              // push access only to the PR branch — never to the fork's default
+              // branch. Attempting the push there is guaranteed to be rejected
+              // with "permission denied" and is unnecessary, so we skip it and
+              // keep working on the PR branch.
+              const currentUserResult = await $`gh api user --jq .login`;
+              const currentUser = currentUserResult.code === 0 ? currentUserResult.stdout.toString().trim() : null;
+              const pushDecision = shouldPushDefaultBranchToFork({ currentUser, forkedRepo });
+
+              if (!pushDecision.shouldPush) {
+                await log(`${formatAligned('ℹ️', 'Skipping fork push:', `${upstreamDefaultBranch} synced locally only`)}`);
+                await log(`${formatAligned('', 'Reason:', `Fork ${forkedRepo} is owned by ${pushDecision.forkOwner}, not ${currentUser || 'the current user'}`)}`, {
+                  verbose: true,
+                });
+                await log(`${formatAligned('', 'Next:', 'Continuing on the PR branch (maintainer edits allowed on the PR head only)')}`, {
+                  verbose: true,
+                });
+                // Fall through to Step 4 (return to original branch) without pushing.
+                if (currentBranch !== upstreamDefaultBranch) {
+                  await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
+                  const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
+                  if (returnResult.code === 0) {
+                    await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
+                  } else {
+                    await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
+                  }
+                }
+                return;
+              }
+
+              await log(`${formatAligned('🔄', 'Pushing to fork:', `${upstreamDefaultBranch} branch`)}`);
+              const pushResult = await $({ cwd: tempDir })`git push origin ${upstreamDefaultBranch} 2>&1`;
+              if (pushResult.code === 0) {
+                await log(`${formatAligned('✅', 'Fork updated:', 'Default branch pushed to fork')}`);
+              } else {
+                // Check if it's a non-fast-forward error (fork has diverged from upstream)
+                const errorMsg = (pushResult.stderr ? pushResult.stderr.toString().trim() : '') || (pushResult.stdout ? pushResult.stdout.toString().trim() : '');
+
+                // Issue #1893: a "permission denied" rejection is NOT a divergence.
+                // It means the current user cannot write to this fork (e.g. it
+                // belongs to another contributor). Force-push / force-with-lease
+                // cannot fix that, so never recommend the divergence flag here.
+                // Syncing the default branch is best-effort, so we warn and
+                // continue working on the PR branch instead of halting.
+                if (isPermissionDeniedPushError(errorMsg)) {
+                  await log('');
+                  await log(`${formatAligned('ℹ️', 'Skipping fork sync:', `No push access to ${forkedRepo}`)}`);
+                  await log(`${formatAligned('', 'Reason:', "Fork's default branch is owned by another user; this is expected when")}`, { verbose: true });
+                  await log(`${formatAligned('', '', "continuing a contributor's fork PR (maintainer edits cover the PR branch only)")}`, { verbose: true });
+                  await log(`${formatAligned('', 'Push output:', errorMsg.split('\n')[0] || errorMsg)}`, { verbose: true });
+                  // Return to the original branch and continue without halting.
+                  if (currentBranch !== upstreamDefaultBranch) {
+                    await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
+                    const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
+                    if (returnResult.code === 0) {
+                      await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
+                    } else {
+                      await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
+                    }
+                  }
+                  return;
+                }
+
+                const isNonFastForward = errorMsg.includes('non-fast-forward') || errorMsg.includes('rejected') || errorMsg.includes('tip of your current branch is behind');
+
+                if (isNonFastForward) {
+                  // 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('');
+
+                  // Check if user has enabled automatic force push
+                  if (argv.allowForkDivergenceResolutionUsingForcePushWithLease) {
+                    await log('  🔄 Auto-resolution ENABLED (--allow-fork-divergence-resolution-using-force-push-with-lease):');
+                    await log('     Attempting to force-push with --force-with-lease...');
+                    await log('');
+
+                    // Use --force-with-lease for safer force push
+                    // This will only force push if the remote hasn't changed since our last fetch
+                    await log(`${formatAligned('🔄', 'Force pushing:', 'Syncing fork with upstream (--force-with-lease)')}`);
+                    const forcePushResult = await $({
+                      cwd: tempDir,
+                    })`git push --force-with-lease origin ${upstreamDefaultBranch} 2>&1`;
+
+                    if (forcePushResult.code === 0) {
+                      await log(`${formatAligned('✅', 'Fork synced:', 'Successfully force-pushed to align with upstream')}`);
+                      await log('');
+                    } else {
+                      // Force push also failed - this is a more serious issue
+                      await log('');
+                      await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to sync fork with upstream')}`, {
+                        level: 'error',
+                      });
+                      await log('');
+                      await log('  🔍 What happened:');
+                      await log(`     Fork branch ${upstreamDefaultBranch} has diverged from upstream`);
+                      await log('     Both normal push and force-with-lease push failed');
+                      await log('');
+                      await log('  📦 Error details:');
+                      const forceErrorMsg = forcePushResult.stderr ? forcePushResult.stderr.toString().trim() : '';
+                      for (const line of forceErrorMsg.split('\n')) {
+                        if (line.trim()) await log(`     ${line}`);
+                      }
+                      await log('');
+                      await log('  💡 Possible causes:');
+                      await log('     • Fork branch is protected (branch protection rules prevent force push)');
+                      await log('     • Someone else pushed to fork after our fetch');
+                      await log('     • Insufficient permissions to force push');
+                      await log('');
+                      await log('  🔧 Manual resolution:');
+                      await log(`     1. Visit your fork: https://github.com/${forkedRepo}`);
+                      await log('     2. Check branch protection settings');
+                      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('');
+                      await safeExit(1, 'Repository setup failed - fork sync failed');
+                    }
+                  } 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');
+                  }
+                } else {
+                  // Some other push error (not divergence-related)
+                  await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to push updated default branch to fork')}`);
+                  await log(`${formatAligned('', 'Push error:', errorMsg)}`);
+                  await log(`${formatAligned('', 'Reason:', 'Fork must be updated or process must stop')}`);
+                  await log(`${formatAligned('', 'Solution draft:', 'Fork sync is required for proper workflow')}`);
+                  await log(`${formatAligned('', 'Next steps:', '1. Check GitHub permissions for the fork')}`);
+                  await log(`${formatAligned('', '', '2. Ensure fork is not protected')}`);
+                  await log(`${formatAligned('', '', '3. Try again after resolving fork issues')}`);
+                  await safeExit(1, 'Repository setup failed');
+                }
+              }
+
+              // Step 4: Return to the original branch if it was different
+              if (currentBranch !== upstreamDefaultBranch) {
+                await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
+                const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
+                if (returnResult.code === 0) {
+                  await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
+                } else {
+                  await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
+                  // This is not fatal, continue with sync on default branch
+                }
+              }
+            } else {
+              await log(`${formatAligned('⚠️', 'Warning:', `Failed to sync ${upstreamDefaultBranch} with upstream`)}`);
+              if (syncResult.stderr) {
+                await log(`${formatAligned('', 'Sync error:', syncResult.stderr.toString().trim())}`);
+              }
+            }
+          }
+        } else {
+          await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get default branch name')}`);
+        }
+      } else {
+        await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get current branch')}`);
+      }
+    } else {
+      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to fetch upstream')}`);
+      if (fetchResult.stderr) {
+        await log(`${formatAligned('', 'Fetch error:', fetchResult.stderr.toString().trim())}`);
+      }
+    }
+  }
+};

package/src/solve.repository.lib.mjs

@@ -1045,220 +1045,10 @@ export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) =
   await safeExit(1, 'Repository setup failed');
 };
 
-// Set up upstream remote and sync fork
-export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote, owner, repo, argv) => {
-  if (!forkedRepo || !upstreamRemote) return;
-
-  await log(`${formatAligned('🔗', 'Setting upstream:', upstreamRemote)}`);
-
-  // Check if upstream remote already exists
-  const checkUpstreamResult = await $({ cwd: tempDir })`git remote get-url upstream 2>/dev/null`;
-  let upstreamExists = checkUpstreamResult.code === 0;
-
-  if (upstreamExists) {
-    await log(`${formatAligned('ℹ️', 'Upstream exists:', 'Using existing upstream remote')}`);
-  } else {
-    // Add upstream remote since it doesn't exist
-    const upstreamResult = await $({ cwd: tempDir })`git remote add upstream https://github.com/${upstreamRemote}.git`;
-
-    if (upstreamResult.code === 0) {
-      await log(`${formatAligned('✅', 'Upstream set:', upstreamRemote)}`);
-      upstreamExists = true;
-    } else {
-      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to add upstream remote')}`);
-      if (upstreamResult.stderr) {
-        await log(`${formatAligned('', 'Error details:', upstreamResult.stderr.toString().trim())}`);
-      }
-    }
-  }
-
-  // Proceed with fork sync if upstream remote is available
-  if (upstreamExists) {
-    // Fetch upstream
-    await log(`${formatAligned('🔄', 'Fetching upstream...', '')}`);
-    const fetchResult = await $({ cwd: tempDir })`git fetch upstream`;
-    if (fetchResult.code === 0) {
-      await log(`${formatAligned('✅', 'Upstream fetched:', 'Successfully')}`);
-
-      // Sync the default branch with upstream to avoid merge conflicts
-      await log(`${formatAligned('🔄', 'Syncing default branch...', '')}`);
-
-      // Get current branch so we can return to it after sync
-      const currentBranchResult = await $({ cwd: tempDir })`git branch --show-current`;
-      if (currentBranchResult.code === 0) {
-        const currentBranch = currentBranchResult.stdout.toString().trim();
-
-        // Get the default branch name from the original repository using GitHub API
-        const repoInfoResult = await $`gh api repos/${owner}/${repo} --jq .default_branch`;
-        if (repoInfoResult.code === 0) {
-          const upstreamDefaultBranch = repoInfoResult.stdout.toString().trim();
-          await log(`${formatAligned('ℹ️', 'Default branch:', upstreamDefaultBranch)}`);
-
-          // Always sync the default branch, regardless of current branch
-          // This ensures fork is up-to-date even if we're working on a different branch
-
-          // Step 1: Switch to default branch if not already on it
-          let syncSuccessful = true;
-          if (currentBranch !== upstreamDefaultBranch) {
-            await log(`${formatAligned('🔄', 'Switching to:', `${upstreamDefaultBranch} branch`)}`);
-            const checkoutResult = await $({ cwd: tempDir })`git checkout ${upstreamDefaultBranch}`;
-            if (checkoutResult.code !== 0) {
-              await log(`${formatAligned('⚠️', 'Warning:', `Failed to checkout ${upstreamDefaultBranch}`)}`);
-              syncSuccessful = false; // Cannot proceed with sync
-            }
-          }
-
-          // Step 2: Sync default branch with upstream (only if checkout was successful)
-          if (syncSuccessful) {
-            const syncResult = await $({ cwd: tempDir })`git reset --hard upstream/${upstreamDefaultBranch}`;
-            if (syncResult.code === 0) {
-              await log(`${formatAligned('✅', 'Default branch synced:', `with upstream/${upstreamDefaultBranch}`)}`);
-
-              // Step 3: Push the updated default branch to fork to keep it in sync
-              await log(`${formatAligned('🔄', 'Pushing to fork:', `${upstreamDefaultBranch} branch`)}`);
-              const pushResult = await $({ cwd: tempDir })`git push origin ${upstreamDefaultBranch} 2>&1`;
-              if (pushResult.code === 0) {
-                await log(`${formatAligned('✅', 'Fork updated:', 'Default branch pushed to fork')}`);
-              } else {
-                // Check if it's a non-fast-forward error (fork has diverged from upstream)
-                const errorMsg = (pushResult.stderr ? pushResult.stderr.toString().trim() : '') || (pushResult.stdout ? pushResult.stdout.toString().trim() : '');
-                const isNonFastForward = errorMsg.includes('non-fast-forward') || errorMsg.includes('rejected') || errorMsg.includes('tip of your current branch is behind');
-
-                if (isNonFastForward) {
-                  // 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('');
-
-                  // Check if user has enabled automatic force push
-                  if (argv.allowForkDivergenceResolutionUsingForcePushWithLease) {
-                    await log('  🔄 Auto-resolution ENABLED (--allow-fork-divergence-resolution-using-force-push-with-lease):');
-                    await log('     Attempting to force-push with --force-with-lease...');
-                    await log('');
-
-                    // Use --force-with-lease for safer force push
-                    // This will only force push if the remote hasn't changed since our last fetch
-                    await log(`${formatAligned('🔄', 'Force pushing:', 'Syncing fork with upstream (--force-with-lease)')}`);
-                    const forcePushResult = await $({
-                      cwd: tempDir,
-                    })`git push --force-with-lease origin ${upstreamDefaultBranch} 2>&1`;
-
-                    if (forcePushResult.code === 0) {
-                      await log(`${formatAligned('✅', 'Fork synced:', 'Successfully force-pushed to align with upstream')}`);
-                      await log('');
-                    } else {
-                      // Force push also failed - this is a more serious issue
-                      await log('');
-                      await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to sync fork with upstream')}`, {
-                        level: 'error',
-                      });
-                      await log('');
-                      await log('  🔍 What happened:');
-                      await log(`     Fork branch ${upstreamDefaultBranch} has diverged from upstream`);
-                      await log('     Both normal push and force-with-lease push failed');
-                      await log('');
-                      await log('  📦 Error details:');
-                      const forceErrorMsg = forcePushResult.stderr ? forcePushResult.stderr.toString().trim() : '';
-                      for (const line of forceErrorMsg.split('\n')) {
-                        if (line.trim()) await log(`     ${line}`);
-                      }
-                      await log('');
-                      await log('  💡 Possible causes:');
-                      await log('     • Fork branch is protected (branch protection rules prevent force push)');
-                      await log('     • Someone else pushed to fork after our fetch');
-                      await log('     • Insufficient permissions to force push');
-                      await log('');
-                      await log('  🔧 Manual resolution:');
-                      await log(`     1. Visit your fork: https://github.com/${forkedRepo}`);
-                      await log('     2. Check branch protection settings');
-                      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('');
-                      await safeExit(1, 'Repository setup failed - fork sync failed');
-                    }
-                  } 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');
-                  }
-                } else {
-                  // Some other push error (not divergence-related)
-                  await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to push updated default branch to fork')}`);
-                  await log(`${formatAligned('', 'Push error:', errorMsg)}`);
-                  await log(`${formatAligned('', 'Reason:', 'Fork must be updated or process must stop')}`);
-                  await log(`${formatAligned('', 'Solution draft:', 'Fork sync is required for proper workflow')}`);
-                  await log(`${formatAligned('', 'Next steps:', '1. Check GitHub permissions for the fork')}`);
-                  await log(`${formatAligned('', '', '2. Ensure fork is not protected')}`);
-                  await log(`${formatAligned('', '', '3. Try again after resolving fork issues')}`);
-                  await safeExit(1, 'Repository setup failed');
-                }
-              }
-
-              // Step 4: Return to the original branch if it was different
-              if (currentBranch !== upstreamDefaultBranch) {
-                await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
-                const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
-                if (returnResult.code === 0) {
-                  await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
-                } else {
-                  await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
-                  // This is not fatal, continue with sync on default branch
-                }
-              }
-            } else {
-              await log(`${formatAligned('⚠️', 'Warning:', `Failed to sync ${upstreamDefaultBranch} with upstream`)}`);
-              if (syncResult.stderr) {
-                await log(`${formatAligned('', 'Sync error:', syncResult.stderr.toString().trim())}`);
-              }
-            }
-          }
-        } else {
-          await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get default branch name')}`);
-        }
-      } else {
-        await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get current branch')}`);
-      }
-    } else {
-      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to fetch upstream')}`);
-      if (fetchResult.stderr) {
-        await log(`${formatAligned('', 'Fetch error:', fetchResult.stderr.toString().trim())}`);
-      }
-    }
-  }
-};
+// Set up upstream remote and sync fork.
+// Extracted into solve.fork-sync.lib.mjs (#1893) to keep this file under the
+// 1500-line limit; re-exported here so existing importers keep working.
+export { setupUpstreamAndSync } from './solve.fork-sync.lib.mjs';
 
 // Set up pr-fork remote for continuing someone else's fork PR with --fork flag
 export const setupPrForkRemote = async (tempDir, argv, prForkOwner, repo, isContinueMode, owner = null) => {