@link-assistant/hive-mind 1.73.1 → 1.73.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 1.73.3
+
+### Patch Changes
+
+- a3eab04: Fix `solve` aborting with `GitHub compare API not ready - cannot create PR safely` when the compare/diff endpoint returns a transient HTTP 500 (`this diff is temporarily unavailable due to heavy server load`, code `not_available`). The auto-PR readiness gate polled `/repos/{owner}/{repo}/compare/{base}...{head}` to confirm the pushed commits were visible, but GitHub renders that diff lazily and returns 500 under load even though the branch and commits were already pushed and `gh pr create` (which does not render the full diff) would have succeeded. A new `isTransientCompareApiError` detector recognises the "heavy server load" / `not_available` 500 and the standard 5xx gateway codes (but NOT 404 fork mismatch or a literal `0`), and the gate now degrades gracefully — marking the compare ready and proceeding to PR creation, still guarded by branch verification and the local `git rev-list` commit check. The fork-404 mismatch and genuine 0-commits paths remain fatal.
+
+## 1.73.2
+
+### Patch Changes
+
+- 0af65ad: Handle the auto-PR placeholder being listed in the target repository's `.gitignore` without aborting the whole run (issue #1825). Previously `git add .gitkeep` exited non-zero and the solver threw `Failed to add .gitkeep` → `FATAL ERROR: PR creation failed`. Now, when the placeholder (`.gitkeep` or `CLAUDE.md`) is gitignored, the solver by default prints a clear, environment-agnostic root-cause explanation and stops cleanly instead of forcing the commit. Two opt-in flags are added (usable with both `solve` and `/solve`): `--remove-git-keep-from-git-ignore` removes the literal placeholder entry from `.gitignore` first and then commits normally, and `--force-git-keep-commit` commits the placeholder anyway with `git add -f`.
+
 ## 1.73.1
 
 ### Patch Changes

package/package.json

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

package/src/github-rate-limit.lib.mjs

@@ -305,6 +305,43 @@ const isTransientNetworkError = error => {
   return TRANSIENT_NETWORK_PATTERNS.some(pattern => text.includes(pattern));
 };
 
+/**
+ * Patterns that identify a *transient* failure of GitHub's compare/diff
+ * rendering endpoint (`/repos/{owner}/{repo}/compare/{base}...{head}`).
+ *
+ * Issue #1829: under heavy server load GitHub returns
+ *   `HTTP 500: {"message":"...","errors":[{"code":"not_available",...}]}`
+ * with the body "this diff is temporarily unavailable due to heavy server
+ * load". This is NOT a "commits not indexed yet" condition — the branch and
+ * commits are already pushed and `gh pr create` (which does not render the
+ * full diff) would succeed. The readiness gate in `solve.auto-pr.lib.mjs`
+ * used to treat this as fatal and abort the whole session. These patterns let
+ * callers recognise the transient case and degrade gracefully instead.
+ *
+ * Note: HTTP 500 is deliberately matched here (and NOT in
+ * `TRANSIENT_NETWORK_PATTERNS`) because a bare 500 from arbitrary endpoints is
+ * too broad to retry blindly; it is only safe to treat as transient for the
+ * compare endpoint, alongside the explicit "not_available" / "heavy server
+ * load" markers.
+ */
+const TRANSIENT_COMPARE_API_PATTERNS = ['this diff is temporarily unavailable', 'temporarily unavailable due to heavy server load', 'heavy server load', 'not_available', 'http 500', 'http 502', 'http 503', 'http 504'];
+
+/**
+ * Detect whether `error` represents a transient failure of GitHub's
+ * compare/diff endpoint (issue #1829). Returns true for the documented
+ * "heavy server load" / `not_available` HTTP 500 response as well as the
+ * standard transient gateway codes (502/503/504), so the auto-PR readiness
+ * gate can fall through to PR creation rather than aborting.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+const isTransientCompareApiError = error => {
+  const text = collectErrorText(error).toLowerCase();
+  if (!text) return false;
+  return TRANSIENT_COMPARE_API_PATTERNS.some(pattern => text.includes(pattern));
+};
+
 /**
  * Wrap `fn` so that GitHub rate-limit errors are converted into a sleep until
  * (resetTime + bufferMs + jitterMs) followed by a retry. Transient network
@@ -438,11 +475,12 @@ export const wrapDollarWithGhRetry = (dollar, options = {}) => {
   return wrapped;
 };
 
-export { isTransientNetworkError };
+export { isTransientNetworkError, isTransientCompareApiError };
 
 export default {
   isRateLimitError,
   isTransientNetworkError,
+  isTransientCompareApiError,
   parseRateLimitReset,
   fetchNextRateLimitReset,
   fetchGitHubRateLimitUsage,

package/src/solve.auto-pr-compare-readiness.lib.mjs

@@ -0,0 +1,280 @@
+/**
+ * Compare-API readiness handler for the auto-PR pipeline.
+ *
+ * After a branch is pushed, the auto-PR flow polls GitHub's compare endpoint
+ * (`/repos/{owner}/{repo}/compare/{base}...{head}`) to confirm the pushed
+ * commits are visible before calling `gh pr create`. When that poll never
+ * reports commits ahead, this helper decides what the failure means:
+ *
+ *   • HTTP 404 (fork mode) → repository mismatch. Investigate the fork
+ *     relationship and abort with an actionable error (FATAL).
+ *   • Issue #1829: a transient compare/diff failure (HTTP 500 "this diff is
+ *     temporarily unavailable due to heavy server load" / code
+ *     `not_available`, or a 5xx gateway error). The branch and commits were
+ *     already pushed and `gh pr create` does not render the full diff, so this
+ *     is a diff-RENDERING failure, NOT missing commits. Degrade gracefully and
+ *     return `true` so the caller proceeds to PR creation — still guarded by
+ *     branch verification and the LOCAL `git rev-list` commit check.
+ *   • Anything else (genuinely 0 commits ahead / unknown failure) → abort with
+ *     the original "GitHub compare API not ready" error (FATAL).
+ *
+ * Extracted from solve.auto-pr.lib.mjs to keep that file under the 1500-line
+ * CI cap.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1829
+ */
+
+import { isTransientCompareApiError } from './github-rate-limit.lib.mjs'; // Issue #1829: lets the compare-API readiness gate degrade gracefully on transient diff-render failures.
+
+/**
+ * Handle the case where the compare-API readiness poll never saw commits.
+ *
+ * @param {object} params
+ * @param {object} params.argv
+ * @param {string|null} params.forkedRepo
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string|number} params.issueNumber
+ * @param {string} params.branchName
+ * @param {string} params.targetBranchForCompare
+ * @param {number} params.maxCompareAttempts
+ * @param {object} params.compareResult - last command-stream compare result.
+ * @param {(msg: string, opts?: object) => Promise<void>} params.log
+ * @param {(symbol: string, label: string, value: string) => string} params.formatAligned
+ * @param {Function} params.$ - command-stream tagged function from solve.
+ * @returns {Promise<boolean>} `true` when the failure was transient and PR
+ *   creation should proceed (degraded mode). Throws on fatal failures.
+ */
+export async function handleCompareApiNotReady({ argv, forkedRepo, owner, repo, issueNumber, branchName, targetBranchForCompare, maxCompareAttempts, compareResult, log, formatAligned, $ }) {
+  // Issue #1829: build the last compare-API output as a STRING. The
+  // command-stream result exposes stdout/stderr as Buffers, and both
+  // the 404 check below and isTransientCompareApiError expect a string
+  // (the rate-limit lib's collectErrorText returns '' for a raw Buffer).
+  const lastCompareOutput = `${compareResult?.stdout?.toString?.() ?? ''}${compareResult?.stderr?.toString?.() ?? ''}`;
+
+  // Check if this is a repository mismatch error (HTTP 404 from compare API)
+  let isRepositoryMismatch = false;
+  if (argv.fork && forkedRepo) {
+    // For fork mode, check the last compare API call result for 404
+    if (lastCompareOutput.includes('HTTP 404') || lastCompareOutput.includes('Not Found')) {
+      isRepositoryMismatch = true;
+    }
+  }
+
+  // Issue #1829: GitHub's compare/diff endpoint can return a transient
+  // HTTP 500 ("this diff is temporarily unavailable due to heavy server
+  // load" / code "not_available") or a 5xx gateway error under load.
+  // That is a diff-RENDERING failure, NOT a "commits not indexed yet"
+  // condition: the branch and commits were already pushed, and
+  // `gh pr create` does not render the full diff, so it would still
+  // succeed. Aborting here used to kill the whole session needlessly.
+  // Treat a purely transient compare failure as non-fatal and fall
+  // through to PR creation — still guarded by the branch verification
+  // and the LOCAL `git rev-list` commit check below (and `gh pr create`
+  // itself retries transient 5xx via execGhWithRetry).
+  const compareFailedTransiently = !isRepositoryMismatch && isTransientCompareApiError(lastCompareOutput);
+
+  if (isRepositoryMismatch) {
+    // BEFORE showing any error, verify if the repository is actually a GitHub fork
+    await log('');
+    await log(formatAligned('🔍', 'Investigating:', 'Checking fork relationship...'));
+
+    const forkInfoResult = await $({
+      silent: true,
+    })`gh api repos/${forkedRepo} --jq '{fork: .fork, parent: .parent.full_name, source: .source.full_name}' 2>&1`;
+
+    let isFork = false;
+    let parentRepo = null;
+    let sourceRepo = null;
+
+    if (forkInfoResult.code === 0) {
+      try {
+        const forkInfo = JSON.parse(forkInfoResult.stdout.toString().trim());
+        isFork = forkInfo.fork === true;
+        parentRepo = forkInfo.parent || null;
+        sourceRepo = forkInfo.source || null;
+      } catch {
+        // Failed to parse fork info
+      }
+    }
+
+    if (!isFork) {
+      // Repository is NOT a fork at all
+      await log('');
+      await log(formatAligned('❌', 'NOT A GITHUB FORK:', 'Repository is not a fork'), { level: 'error' });
+      await log('');
+      await log('  🔍 What happened:');
+      await log(`     The repository ${forkedRepo} is NOT a GitHub fork.`);
+      await log('     GitHub API reports: fork=false, parent=null');
+      await log('');
+      await log('  💡 Why this happens:');
+      await log('     This repository was likely created by cloning and pushing (git clone + git push)');
+      await log("     instead of using GitHub's Fork button or API.");
+      await log('');
+      await log('     When a repository is created this way:');
+      await log('     • GitHub does not track it as a fork');
+      await log('     • It has no parent relationship with the original repository');
+      await log('     • Pull requests cannot be created to the original repository');
+      await log('     • Compare API returns 404 when comparing with unrelated repositories');
+      await log('');
+      await log('  📦 Repository details:');
+      await log('     • Target repository: ' + `${owner}/${repo}`);
+      await log('     • Your repository: ' + forkedRepo);
+      await log('     • Fork status: false (NOT A FORK)');
+      await log('');
+      await log('  🔧 How to fix:');
+      await log('     Option 1: Delete the non-fork repository and create a proper fork');
+      await log(`        gh repo delete ${forkedRepo}`);
+      await log(`        Then run this command again to create a proper GitHub fork of ${owner}/${repo}`);
+      await log('');
+      await log('     Option 2: Use --prefix-fork-name-with-owner-name to avoid name conflicts');
+      await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --prefix-fork-name-with-owner-name`);
+      await log('        This creates forks with names like "owner-repo" instead of just "repo"');
+      await log('');
+      await log('     Option 3: Work directly on the repository (if you have write access)');
+      await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --no-fork`);
+      await log('');
+
+      throw new Error('Repository is not a GitHub fork - cannot create PR to unrelated repository');
+    } else if (parentRepo !== `${owner}/${repo}` && sourceRepo !== `${owner}/${repo}`) {
+      // Repository IS a fork, but of a different repository
+      await log('');
+      await log(formatAligned('❌', 'WRONG FORK PARENT:', 'Fork is from different repository'), {
+        level: 'error',
+      });
+      await log('');
+      await log('  🔍 What happened:');
+      await log(`     The repository ${forkedRepo} IS a GitHub fork,`);
+      await log(`     but it's a fork of a DIFFERENT repository than ${owner}/${repo}.`);
+      await log('');
+      await log('  📦 Fork relationship:');
+      await log('     • Your fork: ' + forkedRepo);
+      await log('     • Fork parent: ' + (parentRepo || 'unknown'));
+      await log('     • Fork source: ' + (sourceRepo || 'unknown'));
+      await log('     • Target repository: ' + `${owner}/${repo}`);
+      await log('');
+      await log('  💡 Why this happens:');
+      await log('     You have an existing fork from a different repository');
+      await log('     that shares the same name but is from a different source.');
+      await log('     GitHub treats forks hierarchically - each fork tracks its root repository.');
+      await log('');
+      await log('  🔧 How to fix:');
+      await log('     Option 1: Delete the conflicting fork and create a new one');
+      await log(`        gh repo delete ${forkedRepo}`);
+      await log(`        Then run this command again to create a proper fork of ${owner}/${repo}`);
+      await log('');
+      await log('     Option 2: Use --prefix-fork-name-with-owner-name to avoid conflicts');
+      await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --prefix-fork-name-with-owner-name`);
+      await log('        This creates forks with names like "owner-repo" instead of just "repo"');
+      await log('');
+      await log('     Option 3: Work directly on the repository (if you have write access)');
+      await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --no-fork`);
+      await log('');
+
+      throw new Error('Fork parent mismatch - fork is from different repository tree');
+    } else {
+      // Repository is a fork of the correct parent, but compare API still failed
+      // This is unexpected - show detailed error
+      await log('');
+      await log(formatAligned('❌', 'COMPARE API ERROR:', 'Unexpected failure'), { level: 'error' });
+      await log('');
+      await log('  🔍 What happened:');
+      await log(`     The repository ${forkedRepo} is a valid fork of ${owner}/${repo},`);
+      await log("     but GitHub's compare API still returned an error.");
+      await log('');
+      await log('  📦 Fork verification:');
+      await log('     • Your fork: ' + forkedRepo);
+      await log('     • Fork status: true (VALID FORK)');
+      await log('     • Fork parent: ' + (parentRepo || 'unknown'));
+      await log('     • Target repository: ' + `${owner}/${repo}`);
+      await log('');
+      await log('  💡 This is unexpected:');
+      await log('     The fork relationship is correct, but the compare API failed.');
+      await log('     This might be a temporary GitHub API issue.');
+      await log('');
+      await log('  🔧 How to fix:');
+      await log('     1. Wait a minute and try creating the PR manually:');
+      if (argv.fork && forkedRepo) {
+        const forkUser = forkedRepo.split('/')[0];
+        await log(`        gh pr create --draft --repo ${owner}/${repo} --base ${targetBranchForCompare} --head ${forkUser}:${branchName}`);
+      }
+      await log('     2. Check if the issue persists - it might be a GitHub API outage');
+      await log('');
+
+      throw new Error('Compare API failed unexpectedly despite valid fork relationship');
+    }
+  } else if (compareFailedTransiently) {
+    // Issue #1829: the compare API failed only with a transient server
+    // error. Degrade gracefully — proceed to PR creation rather than
+    // aborting the whole session.
+    await log('');
+    await log(formatAligned('⚠️', 'COMPARE API DEGRADED:', 'Transient server error — proceeding'), {
+      level: 'warning',
+    });
+    await log('');
+    await log('  🔍 What happened:');
+    await log(`     GitHub's compare API failed with a transient server error after ${maxCompareAttempts} attempts`);
+    await log('     (e.g. HTTP 500 "this diff is temporarily unavailable due to heavy server');
+    await log('     load", or a 5xx gateway error).');
+    await log('');
+    await log('  💡 Why this is safe to ignore:');
+    await log('     • The branch and commits were already pushed successfully.');
+    await log('     • This is a diff-RENDERING failure, not missing commits.');
+    await log('     • `gh pr create` does not render the full diff, so it can still succeed.');
+    await log('     • The branch is verified on GitHub and the local commit count is');
+    await log('       re-checked before PR creation; `gh pr create` retries 5xx errors too.');
+    await log('');
+    await log('  ➡️  Proceeding to PR creation despite the compare API error (issue #1829).');
+    await log('');
+    const firstLine =
+      lastCompareOutput
+        .split('\n')
+        .map(s => s.trim())
+        .filter(Boolean)[0] || 'unknown';
+    await log(`   Last compare API output: ${firstLine}`, { verbose: true });
+    // Fall through to branch verification + local commit check + PR creation.
+    return true;
+  } else {
+    // Original timeout error for other cases
+    await log('');
+    await log(formatAligned('❌', 'GITHUB SYNC TIMEOUT:', 'Compare API not ready after retries'), {
+      level: 'error',
+    });
+    await log('');
+    await log('  🔍 What happened:');
+    await log(`     After ${maxCompareAttempts} attempts, GitHub's compare API still shows no commits`);
+    await log(`     between ${targetBranchForCompare} and ${branchName}.`);
+    await log('');
+    await log('  💡 This usually means:');
+    await log("     • GitHub's backend systems haven't finished indexing the push");
+    await log("     • There's a temporary issue with GitHub's API");
+    await log('     • The commits may not have been pushed correctly');
+    await log('');
+    await log('  🔧 How to fix:');
+    await log('     1. Wait a minute and try creating the PR manually:');
+    // For fork mode, use the correct head reference format
+    if (argv.fork && forkedRepo) {
+      const forkUser = forkedRepo.split('/')[0];
+      await log(`        gh pr create --draft --repo ${owner}/${repo} --base ${targetBranchForCompare} --head ${forkUser}:${branchName}`);
+    } else {
+      await log(`        gh pr create --draft --repo ${owner}/${repo} --base ${targetBranchForCompare} --head ${branchName}`);
+    }
+    await log('     2. Check if the branch exists on GitHub:');
+    // Show the correct repository where the branch was pushed
+    const branchRepo = argv.fork && forkedRepo ? forkedRepo : `${owner}/${repo}`;
+    await log(`        https://github.com/${branchRepo}/tree/${branchName}`);
+    await log('     3. Check the commit is on GitHub:');
+    // Use the correct head reference for the compare API check
+    if (argv.fork && forkedRepo) {
+      const forkUser = forkedRepo.split('/')[0];
+      await log(`        gh api repos/${owner}/${repo}/compare/${targetBranchForCompare}...${forkUser}:${branchName} --paginate`);
+    } else {
+      await log(`        gh api repos/${owner}/${repo}/compare/${targetBranchForCompare}...${branchName} --paginate`);
+    }
+    await log('');
+
+    throw new Error('GitHub compare API not ready - cannot create PR safely');
+  }
+}
+
+export default { handleCompareApiNotReady };

package/src/solve.auto-pr-placeholder.lib.mjs

@@ -5,6 +5,263 @@
  * the max-lines lint budget.
  */
 
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Decide whether a single .gitignore line is a literal entry for `fileName`.
+ *
+ * We only auto-remove exact placeholder entries (e.g. a line that is just
+ * `.gitkeep`, `/.gitkeep`, `.gitkeep/` or `/.gitkeep/`). Glob rules such as
+ * `.git*` are intentionally left untouched: removing them could un-ignore
+ * unrelated files, which the user did not ask for.
+ *
+ * @param {string} line - raw .gitignore line.
+ * @param {string} fileName - placeholder file name (e.g. `.gitkeep`).
+ * @returns {boolean}
+ */
+function isLiteralIgnoreEntry(line, fileName) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return false;
+  }
+  // Normalize away an optional leading "/" (anchored) and trailing "/" (dir).
+  const normalized = trimmed.replace(/^\//, '').replace(/\/$/, '');
+  return normalized === fileName;
+}
+
+/**
+ * Parse a single `git check-ignore -v <file>` output line.
+ *
+ * Format (when the rule comes from a file):
+ *   <source>:<linenum>:<pattern>\t<pathname>
+ *
+ * @param {string} output - raw stdout from `git check-ignore -v`.
+ * @returns {{source: string, lineNum: number, pattern: string} | null}
+ */
+function parseCheckIgnoreVerbose(output) {
+  const firstLine = (output || '')
+    .split('\n')
+    .map(l => l.trim())
+    .find(Boolean);
+  if (!firstLine) {
+    return null;
+  }
+  // Split off the trailing "\t<pathname>" so colons in the pathname can't confuse us.
+  const meta = firstLine.split('\t')[0];
+  // Greedy source match lets us tolerate paths containing ":" (rare); the
+  // line number is the last ":<digits>:" group before the pattern.
+  const match = meta.match(/^(.*):(\d+):(.*)$/);
+  if (!match) {
+    return null;
+  }
+  return { source: match[1], lineNum: Number(match[2]), pattern: match[3] };
+}
+
+/**
+ * Remove the literal placeholder entry (e.g. `.gitkeep`) from whatever
+ * .gitignore file currently causes `fileName` to be ignored, used by the
+ * opt-in `--remove-git-keep-from-git-ignore` flow (issue #1825).
+ *
+ * Walks the ignore chain (`git check-ignore -v`) and strips each literal
+ * matching line until the placeholder is no longer ignored. Glob rules and
+ * ignore sources outside the working tree (global excludes file) are left
+ * untouched and cause the removal to report failure so the caller can fall
+ * back to a clear message instead of silently mangling the repo.
+ *
+ * @returns {Promise<{removed: boolean, reason?: string, modifiedFiles: string[], stagedFiles: string[]}>}
+ */
+export async function removePlaceholderFromGitignore({ $, tempDir, fileName }) {
+  const repoRoot = path.resolve(tempDir);
+  const modifiedFiles = [];
+  const stagedFiles = [];
+
+  for (let i = 0; i < 50; i++) {
+    const stillIgnored = await $({ cwd: tempDir, silent: true })`git check-ignore ${fileName}`;
+    if (stillIgnored.code !== 0) {
+      // No longer ignored — done.
+      return { removed: true, modifiedFiles, stagedFiles };
+    }
+
+    const verbose = await $({ cwd: tempDir, silent: true })`git check-ignore -v ${fileName}`;
+    const parsed = parseCheckIgnoreVerbose(verbose.stdout ? verbose.stdout.toString() : '');
+    if (!parsed) {
+      return { removed: false, reason: 'could-not-locate-rule', modifiedFiles, stagedFiles };
+    }
+
+    // Only edit ignore files that live inside the working tree.
+    const sourcePath = path.resolve(repoRoot, parsed.source);
+    if (sourcePath !== repoRoot && !sourcePath.startsWith(repoRoot + path.sep)) {
+      return { removed: false, reason: 'rule-outside-worktree', modifiedFiles, stagedFiles };
+    }
+
+    let content;
+    try {
+      content = await fs.readFile(sourcePath, 'utf8');
+    } catch {
+      return { removed: false, reason: 'cannot-read-ignore-file', modifiedFiles, stagedFiles };
+    }
+
+    const lines = content.split('\n');
+    const targetLine = lines[parsed.lineNum - 1];
+    if (targetLine === undefined || !isLiteralIgnoreEntry(targetLine, fileName)) {
+      // The rule is a glob (e.g. ".git*") or otherwise not a literal entry we
+      // can safely remove — refuse rather than over-editing the user's config.
+      return { removed: false, reason: 'rule-not-literal', modifiedFiles, stagedFiles, pattern: parsed.pattern };
+    }
+
+    lines.splice(parsed.lineNum - 1, 1);
+    await fs.writeFile(sourcePath, lines.join('\n'));
+
+    const relSource = path.relative(repoRoot, sourcePath);
+    if (!modifiedFiles.includes(relSource)) {
+      modifiedFiles.push(relSource);
+    }
+
+    // Stage committable ignore files (.gitignore); skip non-committable sources
+    // such as .git/info/exclude which the un-ignore already takes effect for.
+    const insideGitDir = relSource.split(path.sep)[0] === '.git';
+    if (!insideGitDir) {
+      const addIgnore = await $({ cwd: tempDir, silent: true })`git add ${relSource}`;
+      if (addIgnore.code === 0 && !stagedFiles.includes(relSource)) {
+        stagedFiles.push(relSource);
+      }
+    }
+  }
+
+  return { removed: false, reason: 'too-many-rules', modifiedFiles, stagedFiles };
+}
+
+/**
+ * Convenience wrapper: stage the placeholder and, if it failed solely because
+ * the repository gitignores it, stop with a clear user-facing explanation
+ * (issue #1825). Keeps the auto-PR caller small (it is near the max-lines
+ * budget). Returns the {@link addPlaceholderFileToGit} result for any other
+ * outcome so the caller can handle genuine failures as before.
+ *
+ * @returns {Promise<{code: number, ignored: boolean, action: string, stderr: string, removal?: object}>}
+ */
+export async function stagePlaceholderFileOrExplain(params) {
+  const addResult = await addPlaceholderFileToGit(params);
+  if (addResult.code !== 0 && addResult.ignored) {
+    await reportIgnoredPlaceholderAndThrow({
+      fileName: params.fileName,
+      issueUrl: params.issueUrl,
+      addResult,
+      log: params.log,
+      formatAligned: params.formatAligned,
+    });
+  }
+  return addResult;
+}
+
+/**
+ * Log a clear, friendly explanation of why the auto-PR placeholder could not be
+ * committed (it is listed in the repository's .gitignore) and then throw a
+ * user-facing error so the run stops without a scary stack trace.
+ *
+ * This is the default behaviour for issue #1825's follow-up: instead of forcing
+ * the commit through, we explain the root cause and let the user choose how to
+ * proceed (manual fix, or one of the two opt-in flags). The message deliberately
+ * stays environment-agnostic — it only mentions the `solve` / `/solve` options.
+ *
+ * @param {object} params
+ * @param {string} params.fileName - placeholder file name (e.g. `.gitkeep`).
+ * @param {string} params.issueUrl - issue URL, used to build copy-paste commands.
+ * @param {object} [params.addResult] - result from addPlaceholderFileToGit (for the remove-failed reason).
+ * @param {Function} params.log - async logger.
+ * @param {Function} params.formatAligned - log line formatter.
+ * @throws always — the thrown error carries `hiveMindUserFacingLogged = true`.
+ */
+export async function reportIgnoredPlaceholderAndThrow({ fileName, issueUrl, addResult, log, formatAligned }) {
+  const url = issueUrl || '<issue-url>';
+  await log('');
+  await log(formatAligned('🛑', 'Cannot add placeholder:', `${fileName} is listed in .gitignore`), { level: 'error' });
+  await log('');
+  await log('  🔍 Root cause:');
+  await log(`     The repository's .gitignore matches the temporary placeholder file "${fileName}".`);
+  await log('     The placeholder is created only to seed the initial draft pull request and is');
+  await log('     removed automatically when the task completes — but git refuses to add an ignored');
+  await log('     file, so the initial commit cannot be created.');
+
+  if (addResult?.action === 'remove-failed') {
+    await log('');
+    await log('  ⚠️  The ignore rule is not a plain "' + fileName + '" entry, so it cannot be removed');
+    await log('     automatically (removing it might un-ignore unrelated files). Resolve it manually');
+    await log('     or use --force-git-keep-commit.');
+  }
+
+  await log('');
+  await log('  💡 How to resolve (pick one):');
+  await log(`     1. Remove "${fileName}" from .gitignore in the repository, then re-run.`);
+  await log('     2. Let the tool remove it for you before committing:');
+  await log(`          solve ${url} --remove-git-keep-from-git-ignore`);
+  await log(`          /solve ${url} --remove-git-keep-from-git-ignore`);
+  await log('     3. Commit the placeholder anyway, ignoring the .gitignore rule:');
+  await log(`          solve ${url} --force-git-keep-commit`);
+  await log(`          /solve ${url} --force-git-keep-commit`);
+  await log('');
+
+  const error = new Error(`Placeholder "${fileName}" is listed in .gitignore; use --remove-git-keep-from-git-ignore or --force-git-keep-commit, or remove it from .gitignore manually.`);
+  error.hiveMindUserFacingLogged = true;
+  throw error;
+}
+
+/**
+ * Emit the verbose "git add staged nothing" troubleshooting report and throw.
+ *
+ * Reached by auto-PR creation when the placeholder file was written but git did
+ * not stage any change (e.g. identical content is already tracked, or the file
+ * is gitignored in .gitkeep mode). Extracted from solve.auto-pr.lib.mjs to keep
+ * that module under the max-lines budget.
+ *
+ * @param {object} params
+ * @param {string} params.fileName - placeholder file name.
+ * @param {boolean} params.useClaudeFile - true for CLAUDE.md mode, false for .gitkeep mode.
+ * @param {string} params.tempDir - repository working directory.
+ * @param {string} params.branchName - target branch (debug info).
+ * @param {boolean} params.existingContent - whether the file already existed.
+ * @param {Function} params.log - async logger.
+ * @param {Function} params.formatAligned - log line formatter.
+ * @throws always.
+ */
+export async function explainNothingStagedAndThrow({ fileName, useClaudeFile, tempDir, branchName, existingContent, log, formatAligned }) {
+  await log('');
+  await log(formatAligned('❌', 'GIT ADD FAILED:', 'Nothing was staged'), { level: 'error' });
+  await log('');
+  await log('  🔍 What happened:');
+  await log(`     ${fileName} was created but git did not stage any changes.`);
+  await log('');
+  await log('  💡 Possible causes:');
+  await log(`     • ${fileName} already exists with identical content`);
+  await log('     • File system sync issue');
+  if (!useClaudeFile) {
+    await log(`     • ${fileName} is in .gitignore`);
+  }
+  await log('');
+  await log('  🔧 Troubleshooting steps:');
+  await log(`     1. Check file exists: ls -la "${tempDir}/${fileName}"`);
+  await log(`     2. Check git status: cd "${tempDir}" && git status`);
+  if (useClaudeFile) {
+    await log(`     3. Force add: cd "${tempDir}" && git add -f ${fileName}`);
+  } else {
+    await log(`     3. Check if ignored: cd "${tempDir}" && git check-ignore ${fileName}`);
+    await log(`     4. Force add: cd "${tempDir}" && git add -f ${fileName}`);
+  }
+  await log('');
+  await log('  📂 Debug information:');
+  await log(`     Working directory: ${tempDir}`);
+  await log(`     Branch: ${branchName}`);
+  if (!useClaudeFile) {
+    await log('     Mode: .gitkeep');
+  }
+  if (existingContent) {
+    await log(`     Note: ${fileName} already existed (attempted to update with timestamp)`);
+  }
+  await log('');
+  throw new Error(`Git add staged nothing - ${fileName} may be unchanged${useClaudeFile ? '' : ' or ignored'}`);
+}
+
 /**
  * Stage the temporary placeholder file (CLAUDE.md or .gitkeep) used to seed the
  * initial auto-PR commit.
@@ -14,13 +271,18 @@
  * cleanupClaudeFile in solve.results.lib.mjs). When the target repository's
  * .gitignore matches the placeholder — issue #1825: e.g. rumaster/tg-games
  * ignores `.gitkeep` — a plain `git add <file>` exits non-zero with
- * "The following paths are ignored by one of your .gitignore files", which
- * previously aborted PR creation with a fatal "Failed to add .gitkeep".
+ * "The following paths are ignored by one of your .gitignore files".
+ *
+ * Behaviour when the placeholder is git-ignored (issue #1825 follow-up):
+ *   - Default: do NOT force anything. Return `action: 'blocked'` so the caller
+ *     can explain the root cause and offer the opt-in flags below.
+ *   - `--remove-git-keep-from-git-ignore`: strip the literal placeholder entry
+ *     from .gitignore, then add normally (`action: 'removed-from-gitignore'`).
+ *   - `--force-git-keep-commit`: keep the previous behaviour and force-add with
+ *     `git add -f` (`action: 'forced'`).
  *
- * Because the placeholder belongs to us and is short-lived, we confirm the path
- * is actually ignored with `git check-ignore` and then retry with
- * `git add -f`. Force-adding only happens for the ignored-placeholder case;
- * any other add failure is surfaced unchanged so genuine errors are not masked.
+ * Any add failure that is NOT caused by .gitignore is surfaced unchanged
+ * (`action: 'failed'`) so genuine errors are not masked.
  *
  * @param {object} params
  * @param {Function} params.$ - command-stream tagged-template runner.
@@ -29,15 +291,17 @@
  * @param {Function} [params.log] - async logger.
  * @param {Function} [params.formatAligned] - log line formatter.
  * @param {boolean} [params.verbose] - emit verbose diagnostics.
- * @returns {Promise<{code: number, forced: boolean, ignored: boolean, stderr: string}>}
+ * @param {boolean} [params.forceGitKeepCommit] - force-add even when ignored.
+ * @param {boolean} [params.removeGitKeepFromGitIgnore] - remove the .gitignore entry first.
+ * @returns {Promise<{code: number, ignored: boolean, action: string, stderr: string, removal?: object}>}
  */
-export async function addPlaceholderFileToGit({ $, tempDir, fileName, log, formatAligned, verbose = false }) {
+export async function addPlaceholderFileToGit({ $, tempDir, fileName, log, formatAligned, verbose = false, forceGitKeepCommit = false, removeGitKeepFromGitIgnore = false }) {
   // Run silently: `git add` is quiet on success and only emits the noisy
   // "paths are ignored ... Use -f" hint on failure, which we capture in
   // `stderr` and re-surface from the caller only when the failure is genuine.
   const addResult = await $({ cwd: tempDir, silent: true })`git add ${fileName}`;
   if (addResult.code === 0) {
-    return { code: 0, forced: false, ignored: false, stderr: '' };
+    return { code: 0, ignored: false, action: 'added', stderr: '' };
   }
 
   const stderr = addResult.stderr ? addResult.stderr.toString() : '';
@@ -50,21 +314,50 @@ export async function addPlaceholderFileToGit({ $, tempDir, fileName, log, forma
   if (!ignored) {
     // The failure was not caused by .gitignore — surface the original error so
     // genuine problems (permissions, corrupt index, ...) are not masked.
-    return { code: addResult.code, forced: false, ignored: false, stderr };
+    return { code: addResult.code, ignored: false, action: 'failed', stderr };
   }
 
-  if (log && formatAligned) {
-    await log(formatAligned('ℹ️', `${fileName} is ignored:`, 'Force-adding placeholder (git add -f)'));
+  // The placeholder is ignored. Resolve based on the opt-in flags.
+  if (removeGitKeepFromGitIgnore) {
+    if (log && formatAligned) {
+      await log(formatAligned('ℹ️', `${fileName} is ignored:`, 'Removing it from .gitignore (--remove-git-keep-from-git-ignore)'));
+    }
+    const removal = await removePlaceholderFromGitignore({ $, tempDir, fileName });
+    if (!removal.removed) {
+      // Could not safely remove (glob rule, external source, ...). Block with
+      // detail so the caller can explain and suggest --force-git-keep-commit.
+      return { code: addResult.code, ignored: true, action: 'remove-failed', stderr, removal };
+    }
+    if (verbose && log) {
+      await log(`   Removed ${fileName} from: ${removal.modifiedFiles.join(', ') || '(none)'}`, { verbose: true });
+    }
+    const retry = await $({ cwd: tempDir, silent: true })`git add ${fileName}`;
+    return {
+      code: retry.code,
+      ignored: true,
+      action: 'removed-from-gitignore',
+      stderr: retry.stderr ? retry.stderr.toString() : '',
+      removal,
+    };
   }
-  if (verbose && log) {
-    await log(`   ${fileName} matched a .gitignore rule; retrying with: git add -f ${fileName}`, { verbose: true });
+
+  if (forceGitKeepCommit) {
+    if (log && formatAligned) {
+      await log(formatAligned('ℹ️', `${fileName} is ignored:`, 'Force-adding placeholder (--force-git-keep-commit)'));
+    }
+    if (verbose && log) {
+      await log(`   ${fileName} matched a .gitignore rule; --force-git-keep-commit is set, retrying with: git add -f ${fileName}`, { verbose: true });
+    }
+    const forcedResult = await $({ cwd: tempDir, silent: true })`git add -f ${fileName}`;
+    return {
+      code: forcedResult.code,
+      ignored: true,
+      action: 'forced',
+      stderr: forcedResult.stderr ? forcedResult.stderr.toString() : '',
+    };
   }
 
-  const forcedResult = await $({ cwd: tempDir, silent: true })`git add -f ${fileName}`;
-  return {
-    code: forcedResult.code,
-    forced: true,
-    ignored: true,
-    stderr: forcedResult.stderr ? forcedResult.stderr.toString() : '',
-  };
+  // Default: do not force through. Let the caller explain the root cause and
+  // offer the opt-in flags or a manual fix (issue #1825 follow-up).
+  return { code: addResult.code, ignored: true, action: 'blocked', stderr };
 }

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

@@ -6,9 +6,10 @@
 import { closingIssueNumbersContain, parseClosingIssueNumbers } from './pr-issue-linking.lib.mjs';
 import { handleRejectedPushForAutoPr, synchronizeExistingIssueBranchBeforeAutoPrCreation } from './solve.branch-divergence.lib.mjs';
 import { emitForkAwareDiagnostic } from './solve.auto-pr-fork-diagnostic.lib.mjs';
+import { handleCompareApiNotReady } from './solve.auto-pr-compare-readiness.lib.mjs'; // Issue #1829: decides whether a failed compare-API readiness poll is fatal (fork mismatch / 0 commits) or a transient diff-render failure to degrade past.
 
-import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry, execGhWithRetry } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller. Issue #1756: execGhWithRetry retries on transient 5xx (504) too.
-import { addPlaceholderFileToGit } from './solve.auto-pr-placeholder.lib.mjs'; // Issue #1825: force-adds the seed placeholder when the target repo gitignores it.
+import { wrapDollarWithGhRetry as _wrapDollarWithGhRetry, execGhWithRetry, isTransientCompareApiError } from './github-rate-limit.lib.mjs'; // rate-limit marker (#1726): gh API calls flow through $ wrapped by caller. Issue #1756: execGhWithRetry retries on transient 5xx (504) too. Issue #1829: isTransientCompareApiError lets the compare-API readiness gate degrade gracefully on transient diff-render failures.
+import { stagePlaceholderFileOrExplain, explainNothingStagedAndThrow } from './solve.auto-pr-placeholder.lib.mjs'; // Issue #1825: handles the seed placeholder when the target repo gitignores it.
 
 export async function handleAutoPrCreation({ argv, tempDir, branchName, issueNumber, owner, repo, defaultBranch, forkedRepo, isContinueMode, prNumber, log, formatAligned, $, reportError, path, fs }) {
   // Skip auto-PR creation if:
@@ -167,9 +168,22 @@ Proceed.
     // Add and commit the file
     await log(formatAligned('📦', 'Adding file:', 'To git staging'));
 
-    // Issue #1825: force-adds the placeholder when the target repo gitignores
-    // it (e.g. ignores `.gitkeep`), so PR creation is no longer aborted.
-    const addResult = await addPlaceholderFileToGit({ $, tempDir, fileName, log, formatAligned, verbose: argv.verbose });
+    // Issue #1825: by default we no longer force the placeholder through when
+    // the target repo gitignores it. stagePlaceholderFileOrExplain stops with a
+    // clear root-cause message unless --force-git-keep-commit /
+    // --remove-git-keep-from-git-ignore is set. Shared opts are reused by the
+    // .gitkeep fallback below.
+    const placeholderStageOpts = {
+      $,
+      tempDir,
+      log,
+      formatAligned,
+      verbose: argv.verbose,
+      issueUrl,
+      forceGitKeepCommit: argv.forceGitKeepCommit,
+      removeGitKeepFromGitIgnore: argv.removeGitKeepFromGitIgnore,
+    };
+    const addResult = await stagePlaceholderFileOrExplain({ ...placeholderStageOpts, fileName });
 
     if (addResult.code !== 0) {
       await log(`❌ Failed to add ${fileName}`, { level: 'error' });
@@ -214,14 +228,13 @@ Proceed.
           await fs.writeFile(gitkeepPath, gitkeepContent);
           await log(formatAligned('✅', 'Created:', '.gitkeep file'));
 
-          // Try to add .gitkeep (force-added if it too is gitignored — issue #1825)
-          const gitkeepAddResult = await addPlaceholderFileToGit({ $, tempDir, fileName: '.gitkeep', log, formatAligned, verbose: argv.verbose });
+          // Try to add .gitkeep. If it too is gitignored, honor the opt-in
+          // flags or explain the root cause (issue #1825).
+          const gitkeepAddResult = await stagePlaceholderFileOrExplain({ ...placeholderStageOpts, fileName: '.gitkeep' });
 
           if (gitkeepAddResult.code !== 0) {
             await log('❌ Failed to add .gitkeep', { level: 'error' });
-            await log(`   Error: ${gitkeepAddResult.stderr || 'Unknown error'}`, {
-              level: 'error',
-            });
+            await log(`   Error: ${gitkeepAddResult.stderr || 'Unknown error'}`, { level: 'error' });
             throw new Error('Failed to add .gitkeep');
           }
 
@@ -231,9 +244,7 @@ Proceed.
 
           if (!gitStatus || gitStatus.length === 0) {
             await log('');
-            await log(formatAligned('❌', 'GIT ADD FAILED:', 'Neither CLAUDE.md nor .gitkeep could be staged'), {
-              level: 'error',
-            });
+            await log(formatAligned('❌', 'GIT ADD FAILED:', 'Neither CLAUDE.md nor .gitkeep could be staged'), { level: 'error' });
             await log('');
             await log('  🔍 What happened:');
             await log('     Both CLAUDE.md and .gitkeep failed to stage.');
@@ -249,58 +260,11 @@ Proceed.
           commitFileName = '.gitkeep';
           await log(formatAligned('✅', 'File staged:', '.gitkeep'));
         } else {
-          await log('');
-          await log(formatAligned('❌', 'GIT ADD FAILED:', 'Nothing was staged'), { level: 'error' });
-          await log('');
-          await log('  🔍 What happened:');
-          await log('     CLAUDE.md was created but git did not stage any changes.');
-          await log('');
-          await log('  💡 Possible causes:');
-          await log('     • CLAUDE.md already exists with identical content');
-          await log('     • File system sync issue');
-          await log('');
-          await log('  🔧 Troubleshooting steps:');
-          await log(`     1. Check file exists: ls -la "${tempDir}/CLAUDE.md"`);
-          await log(`     2. Check git status: cd "${tempDir}" && git status`);
-          await log(`     3. Force add: cd "${tempDir}" && git add -f CLAUDE.md`);
-          await log('');
-          await log('  📂 Debug information:');
-          await log(`     Working directory: ${tempDir}`);
-          await log(`     Branch: ${branchName}`);
-          if (existingContent) {
-            await log('     Note: CLAUDE.md already existed (attempted to update with timestamp)');
-          }
-          await log('');
-          throw new Error('Git add staged nothing - CLAUDE.md may be unchanged');
+          await explainNothingStagedAndThrow({ fileName: 'CLAUDE.md', useClaudeFile: true, tempDir, branchName, existingContent, log, formatAligned });
         }
       } else {
         // In --gitkeep-file mode, if .gitkeep couldn't be staged, this is an error
-        await log('');
-        await log(formatAligned('❌', 'GIT ADD FAILED:', 'Nothing was staged'), { level: 'error' });
-        await log('');
-        await log('  🔍 What happened:');
-        await log(`     ${fileName} was created but git did not stage any changes.`);
-        await log('');
-        await log('  💡 Possible causes:');
-        await log(`     • ${fileName} already exists with identical content`);
-        await log('     • File system sync issue');
-        await log(`     • ${fileName} is in .gitignore`);
-        await log('');
-        await log('  🔧 Troubleshooting steps:');
-        await log(`     1. Check file exists: ls -la "${tempDir}/${fileName}"`);
-        await log(`     2. Check git status: cd "${tempDir}" && git status`);
-        await log(`     3. Check if ignored: cd "${tempDir}" && git check-ignore ${fileName}`);
-        await log(`     4. Force add: cd "${tempDir}" && git add -f ${fileName}`);
-        await log('');
-        await log('  📂 Debug information:');
-        await log(`     Working directory: ${tempDir}`);
-        await log(`     Branch: ${branchName}`);
-        await log(`     Mode: ${useClaudeFile ? 'CLAUDE.md' : '.gitkeep'}`);
-        if (existingContent) {
-          await log(`     Note: ${fileName} already existed (attempted to update with timestamp)`);
-        }
-        await log('');
-        throw new Error(`Git add staged nothing - ${fileName} may be unchanged or ignored`);
+        await explainNothingStagedAndThrow({ fileName, useClaudeFile: false, tempDir, branchName, existingContent, log, formatAligned });
       }
     }
 
@@ -419,9 +383,7 @@ Proceed.
 
         // Check for archived repository error
         if (errorOutput.includes('archived') && errorOutput.includes('read-only')) {
-          await log(`\n${formatAligned('❌', 'REPOSITORY ARCHIVED:', 'Cannot push to archived repository')}`, {
-            level: 'error',
-          });
+          await log(`\n${formatAligned('❌', 'REPOSITORY ARCHIVED:', 'Cannot push to archived repository')}`, { level: 'error' });
           await log('');
           await log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
           await log('');
@@ -635,193 +597,40 @@ Proceed.
               await log(`   ⚠️ GitHub compare API shows 0 commits ahead (attempt ${compareAttempts}/${maxCompareAttempts})`, { level: 'warning' });
             }
           } else {
-            if (argv.verbose) {
-              await log(`   Compare API error (attempt ${compareAttempts}/${maxCompareAttempts}): ${compareResult.stdout || compareResult.stderr || 'unknown'}`, { verbose: true });
+            // Issue #1829: surface compare-API failures in normal output (not
+            // only verbose) so the degraded-mode decision below is explainable
+            // from the logs. Build the text as a STRING — the command-stream
+            // result exposes stdout/stderr as Buffers, and the transient
+            // detectors call String.prototype.toLowerCase().
+            const errorText = `${compareResult.stdout?.toString?.() ?? ''}${compareResult.stderr?.toString?.() ?? ''}`.trim();
+            const firstLine =
+              errorText
+                .split('\n')
+                .map(s => s.trim())
+                .filter(Boolean)[0] || 'unknown';
+            const transientNote = isTransientCompareApiError(errorText) ? ' (transient server error)' : '';
+            await log(`   ⚠️ GitHub compare API error${transientNote} (attempt ${compareAttempts}/${maxCompareAttempts}): ${firstLine}`, { level: 'warning' });
+            if (argv.verbose && errorText) {
+              await log(`   Compare API full output: ${errorText}`, { verbose: true });
             }
           }
         }
 
         if (!compareReady) {
-          // Check if this is a repository mismatch error (HTTP 404 from compare API)
-          let isRepositoryMismatch = false;
-          if (argv.fork && forkedRepo) {
-            // For fork mode, check the last compare API call result for 404
-            const lastCompareOutput = compareResult.stdout || compareResult.stderr || '';
-            if (lastCompareOutput.includes('HTTP 404') || lastCompareOutput.includes('Not Found')) {
-              isRepositoryMismatch = true;
-            }
-          }
-
-          if (isRepositoryMismatch) {
-            // BEFORE showing any error, verify if the repository is actually a GitHub fork
-            await log('');
-            await log(formatAligned('🔍', 'Investigating:', 'Checking fork relationship...'));
-
-            const forkInfoResult = await $({
-              silent: true,
-            })`gh api repos/${forkedRepo} --jq '{fork: .fork, parent: .parent.full_name, source: .source.full_name}' 2>&1`;
-
-            let isFork = false;
-            let parentRepo = null;
-            let sourceRepo = null;
-
-            if (forkInfoResult.code === 0) {
-              try {
-                const forkInfo = JSON.parse(forkInfoResult.stdout.toString().trim());
-                isFork = forkInfo.fork === true;
-                parentRepo = forkInfo.parent || null;
-                sourceRepo = forkInfo.source || null;
-              } catch {
-                // Failed to parse fork info
-              }
-            }
-
-            if (!isFork) {
-              // Repository is NOT a fork at all
-              await log('');
-              await log(formatAligned('❌', 'NOT A GITHUB FORK:', 'Repository is not a fork'), { level: 'error' });
-              await log('');
-              await log('  🔍 What happened:');
-              await log(`     The repository ${forkedRepo} is NOT a GitHub fork.`);
-              await log('     GitHub API reports: fork=false, parent=null');
-              await log('');
-              await log('  💡 Why this happens:');
-              await log('     This repository was likely created by cloning and pushing (git clone + git push)');
-              await log("     instead of using GitHub's Fork button or API.");
-              await log('');
-              await log('     When a repository is created this way:');
-              await log('     • GitHub does not track it as a fork');
-              await log('     • It has no parent relationship with the original repository');
-              await log('     • Pull requests cannot be created to the original repository');
-              await log('     • Compare API returns 404 when comparing with unrelated repositories');
-              await log('');
-              await log('  📦 Repository details:');
-              await log('     • Target repository: ' + `${owner}/${repo}`);
-              await log('     • Your repository: ' + forkedRepo);
-              await log('     • Fork status: false (NOT A FORK)');
-              await log('');
-              await log('  🔧 How to fix:');
-              await log('     Option 1: Delete the non-fork repository and create a proper fork');
-              await log(`        gh repo delete ${forkedRepo}`);
-              await log(`        Then run this command again to create a proper GitHub fork of ${owner}/${repo}`);
-              await log('');
-              await log('     Option 2: Use --prefix-fork-name-with-owner-name to avoid name conflicts');
-              await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --prefix-fork-name-with-owner-name`);
-              await log('        This creates forks with names like "owner-repo" instead of just "repo"');
-              await log('');
-              await log('     Option 3: Work directly on the repository (if you have write access)');
-              await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --no-fork`);
-              await log('');
-
-              throw new Error('Repository is not a GitHub fork - cannot create PR to unrelated repository');
-            } else if (parentRepo !== `${owner}/${repo}` && sourceRepo !== `${owner}/${repo}`) {
-              // Repository IS a fork, but of a different repository
-              await log('');
-              await log(formatAligned('❌', 'WRONG FORK PARENT:', 'Fork is from different repository'), {
-                level: 'error',
-              });
-              await log('');
-              await log('  🔍 What happened:');
-              await log(`     The repository ${forkedRepo} IS a GitHub fork,`);
-              await log(`     but it's a fork of a DIFFERENT repository than ${owner}/${repo}.`);
-              await log('');
-              await log('  📦 Fork relationship:');
-              await log('     • Your fork: ' + forkedRepo);
-              await log('     • Fork parent: ' + (parentRepo || 'unknown'));
-              await log('     • Fork source: ' + (sourceRepo || 'unknown'));
-              await log('     • Target repository: ' + `${owner}/${repo}`);
-              await log('');
-              await log('  💡 Why this happens:');
-              await log('     You have an existing fork from a different repository');
-              await log('     that shares the same name but is from a different source.');
-              await log('     GitHub treats forks hierarchically - each fork tracks its root repository.');
-              await log('');
-              await log('  🔧 How to fix:');
-              await log('     Option 1: Delete the conflicting fork and create a new one');
-              await log(`        gh repo delete ${forkedRepo}`);
-              await log(`        Then run this command again to create a proper fork of ${owner}/${repo}`);
-              await log('');
-              await log('     Option 2: Use --prefix-fork-name-with-owner-name to avoid conflicts');
-              await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --prefix-fork-name-with-owner-name`);
-              await log('        This creates forks with names like "owner-repo" instead of just "repo"');
-              await log('');
-              await log('     Option 3: Work directly on the repository (if you have write access)');
-              await log(`        ./solve.mjs "https://github.com/${owner}/${repo}/issues/${issueNumber}" --no-fork`);
-              await log('');
-
-              throw new Error('Fork parent mismatch - fork is from different repository tree');
-            } else {
-              // Repository is a fork of the correct parent, but compare API still failed
-              // This is unexpected - show detailed error
-              await log('');
-              await log(formatAligned('❌', 'COMPARE API ERROR:', 'Unexpected failure'), { level: 'error' });
-              await log('');
-              await log('  🔍 What happened:');
-              await log(`     The repository ${forkedRepo} is a valid fork of ${owner}/${repo},`);
-              await log("     but GitHub's compare API still returned an error.");
-              await log('');
-              await log('  📦 Fork verification:');
-              await log('     • Your fork: ' + forkedRepo);
-              await log('     • Fork status: true (VALID FORK)');
-              await log('     • Fork parent: ' + (parentRepo || 'unknown'));
-              await log('     • Target repository: ' + `${owner}/${repo}`);
-              await log('');
-              await log('  💡 This is unexpected:');
-              await log('     The fork relationship is correct, but the compare API failed.');
-              await log('     This might be a temporary GitHub API issue.');
-              await log('');
-              await log('  🔧 How to fix:');
-              await log('     1. Wait a minute and try creating the PR manually:');
-              if (argv.fork && forkedRepo) {
-                const forkUser = forkedRepo.split('/')[0];
-                await log(`        gh pr create --draft --repo ${owner}/${repo} --base ${targetBranchForCompare} --head ${forkUser}:${branchName}`);
-              }
-              await log('     2. Check if the issue persists - it might be a GitHub API outage');
-              await log('');
-
-              throw new Error('Compare API failed unexpectedly despite valid fork relationship');
-            }
-          } else {
-            // Original timeout error for other cases
-            await log('');
-            await log(formatAligned('❌', 'GITHUB SYNC TIMEOUT:', 'Compare API not ready after retries'), {
-              level: 'error',
-            });
-            await log('');
-            await log('  🔍 What happened:');
-            await log(`     After ${maxCompareAttempts} attempts, GitHub's compare API still shows no commits`);
-            await log(`     between ${targetBranchForCompare} and ${branchName}.`);
-            await log('');
-            await log('  💡 This usually means:');
-            await log("     • GitHub's backend systems haven't finished indexing the push");
-            await log("     • There's a temporary issue with GitHub's API");
-            await log('     • The commits may not have been pushed correctly');
-            await log('');
-            await log('  🔧 How to fix:');
-            await log('     1. Wait a minute and try creating the PR manually:');
-            // For fork mode, use the correct head reference format
-            if (argv.fork && forkedRepo) {
-              const forkUser = forkedRepo.split('/')[0];
-              await log(`        gh pr create --draft --repo ${owner}/${repo} --base ${targetBranchForCompare} --head ${forkUser}:${branchName}`);
-            } else {
-              await log(`        gh pr create --draft --repo ${owner}/${repo} --base ${targetBranchForCompare} --head ${branchName}`);
-            }
-            await log('     2. Check if the branch exists on GitHub:');
-            // Show the correct repository where the branch was pushed
-            const branchRepo = argv.fork && forkedRepo ? forkedRepo : `${owner}/${repo}`;
-            await log(`        https://github.com/${branchRepo}/tree/${branchName}`);
-            await log('     3. Check the commit is on GitHub:');
-            // Use the correct head reference for the compare API check
-            if (argv.fork && forkedRepo) {
-              const forkUser = forkedRepo.split('/')[0];
-              await log(`        gh api repos/${owner}/${repo}/compare/${targetBranchForCompare}...${forkUser}:${branchName} --paginate`);
-            } else {
-              await log(`        gh api repos/${owner}/${repo}/compare/${targetBranchForCompare}...${branchName} --paginate`);
-            }
-            await log('');
-
-            throw new Error('GitHub compare API not ready - cannot create PR safely');
-          }
+          compareReady = await handleCompareApiNotReady({
+            argv,
+            forkedRepo,
+            owner,
+            repo,
+            issueNumber,
+            branchName,
+            targetBranchForCompare,
+            maxCompareAttempts,
+            compareResult,
+            log,
+            formatAligned,
+            $,
+          });
         }
 
         // Verify the push actually worked by checking GitHub API

package/src/solve.config.lib.mjs

@@ -110,6 +110,16 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Automatically use .gitkeep if CLAUDE.md is in .gitignore (pre-checks before creating file)',
     default: true,
   },
+  'force-git-keep-commit': {
+    type: 'boolean',
+    description: 'If the auto-PR placeholder (.gitkeep) is listed in .gitignore, commit it anyway with `git add -f` instead of stopping (issue #1825). Off by default.',
+    default: false,
+  },
+  'remove-git-keep-from-git-ignore': {
+    type: 'boolean',
+    description: 'If the auto-PR placeholder (.gitkeep) is listed in .gitignore, remove that entry from .gitignore first, then commit normally (issue #1825). Off by default.',
+    default: false,
+  },
   'auto-support-agents-md-as-claude-md': {
     type: 'boolean',
     description: '[EXPERIMENTAL] Temporarily copy AGENTS.md/agents.md to CLAUDE.md while Claude runs, then remove the temporary copy',