@link-assistant/hive-mind 2.0.11 → 2.0.13

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @link-assistant/hive-mind
 
+## 2.0.13
+
+### Patch Changes
+
+- ca7c412: fix(branch): validate `--base-branch` existence up-front and stop misreporting a missing base branch as an empty repository (#1959)
+
+  A `/solve` run from the Telegram bot crashed with the unactionable message
+  `Branch operation failed`. Root cause: the user passed `--base-branch issue-375-8a4323e580780`
+  — a **one-character typo** of the real branch `issue-375-8a4323e58078`. The branch did not
+  exist, but nothing validated that before the run started. The solver cloned 72 MB, then
+  `git checkout -b … origin/issue-375-8a4323e580780` failed with
+  `fatal: 'origin/…' is not a commit`. Worse, the branch-creation error handler **misdiagnosed**
+  this as "the repository appears to be empty (no commits)" and suggested `--auto-init-repository`,
+  which is wrong for a non-empty repo. The top level then collapsed everything to the bare
+  `Branch operation failed` comment on GitHub.
+
+  Defense-in-depth fix applied across the codebase:
+  - `validateGitHubEntityExistence()` (`src/github-entity-validation.lib.mjs`) gains a new
+    base-branch step: when `--base-branch` is supplied, `checkBaseBranchExists()` verifies it
+    via `gh api repos/{owner}/{repo}/branches/{branch}` **before** cloning, in the same fail-fast
+    gate that already checks user/repo/issue/PR. A definitive 404 fails the run; transient
+    errors fail open so a network hiccup never blocks a valid run.
+  - New helpers `levenshteinDistance()` and `findClosestBranchName()` power a "did you mean
+    '<closest-existing-branch>'?" suggestion built from the repo's actual branch list, so the
+    exact real-world typo points the user straight at `issue-375-8a4323e58078`.
+  - Both entry points share the gate: `src/solve.mjs` (CLI + the GitHub comment path) and
+    `src/telegram-bot.mjs` (the bot pre-flight) now pass `baseBranch` in, so a missing base
+    branch fails immediately at every level — including in Telegram, before the solve command
+    is queued or spawned.
+  - `handleBranchCreationError()` (`src/solve.branch-errors.lib.mjs`) now receives `baseBranch`
+    and `branchSource`. When a custom base branch is the missing ref it reports the real root
+    cause instead of the bogus empty-repository advice; the genuine empty-repository path
+    (creating from the default branch) is preserved. `createOrCheckoutBranch()`
+    (`src/solve.branch.lib.mjs`) threads the base branch and its source into the handler.
+
+  Adds `tests/test-base-branch-existence.mjs` (17 offline assertions covering the helpers and
+  the misdiagnosis fix), `tests/test-base-branch-existence-integration.mjs`
+  (`@hive-mind-integration`, the real `gh` gate), and a deep case study in
+  `docs/case-studies/issue-1959/`.
+
+## 2.0.12
+
+### Patch Changes
+
+- f17bac4: fix(clone): detect interrupted clones that exit 0, retry them, and explain the failure instead of the bare "Failed to get current branch" (#1957)
+
+  A `/solve` run crashed with the unactionable message `Failed to get current branch`.
+  Root cause: `gh repo clone` (and the `git clone` it wraps) **exited 0 even though the
+  transfer was interrupted** mid-stream (`fetch-pack: unexpected disconnect while reading
+sideband packet`), leaving **no `.git` directory** (`size=0 B`). The solver trusted the
+  exit code, logged `✅ Cloned to:`, then every subsequent git command failed with
+  `fatal: not a git repository`; the first to propagate it (`git branch --show-current` in
+  `verifyDefaultBranchAndStatus`) threw the bare error with no clue about what went wrong
+  or how to recover.
+
+  Defense-in-depth fix applied across the codebase:
+  - `cloneRepository()` (`src/solve.repository.lib.mjs`) no longer trusts the exit code:
+    after `gh repo clone` it validates the result with `git rev-parse --is-inside-work-tree`
+    and only treats the clone as successful when the exit code is 0 **and** a real working
+    tree exists. In `--verbose` mode it logs why a 0-exit clone was rejected.
+  - New exported helper `cleanPartialClone()` empties the target directory before each
+    retry so a partial clone does not make `gh repo clone <dir>` fail with "directory
+    exists and is not empty".
+  - `classifyCloneError()` now classifies the interrupted-transfer vocabulary
+    (`unexpected disconnect`, `sideband`, `early eof`, `the remote end hung up`,
+    `rpc failed`, `fetch-pack`, `index-pack failed`, `transfer closed`) as a retryable
+    `NETWORK` error, so the existing 3× exponential-backoff retry loop recovers from it.
+    404 / ENOSPC / auth failures stay non-retryable.
+  - `isTransientNetworkError()` (`src/lib.mjs`, shared by many gh/git retry call sites)
+    gains the same vocabulary, so the fix propagates everywhere — not just the clone path.
+  - Both failure points now print concrete, root-cause-obvious guidance: the clone-failure
+    path adds NETWORK causes/fixes, and `verifyDefaultBranchAndStatus()`
+    (`src/solve.repo-setup.lib.mjs`) detects `not a git repository` and logs an
+    `INCOMPLETE CLONE DETECTED` block (What happened / Error details / How to fix:
+    check network·VPN·proxy, re-run — clones auto-retry, verify access, check GitHub
+    status) instead of the bare message.
+
+  Adds `tests/test-issue-1957-incomplete-clone.mjs` (26 assertions) and a deep case study
+  in `docs/case-studies/issue-1957/`.
+
 ## 2.0.11
 
 ### Patch Changes

package/package.json

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

package/src/github-entity-validation.lib.mjs

@@ -10,8 +10,135 @@ import { ghCmdRetry } from './lib.mjs';
 import { ghPrView, ghIssueView } from './github.lib.mjs';
 
 /**
- * Validate existence of GitHub entities (user/org, repository, issue/PR) before executing a command.
- * Checks each level in order: user/org → repository → issue/PR, failing fast at the first missing entity.
+ * Compute the Levenshtein edit distance between two strings.
+ * Used to suggest the closest existing branch name when a requested base
+ * branch is not found (issue #1959 — typos like an extra trailing character).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} The minimum number of single-character edits
+ */
+export function levenshteinDistance(a, b) {
+  a = String(a);
+  b = String(b);
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Single-row dynamic programming to keep memory at O(min(len)).
+  let previousRow = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const currentRow = [i + 1];
+    for (let j = 0; j < b.length; j++) {
+      const insertCost = currentRow[j] + 1;
+      const deleteCost = previousRow[j + 1] + 1;
+      const replaceCost = previousRow[j] + (a[i] === b[j] ? 0 : 1);
+      currentRow.push(Math.min(insertCost, deleteCost, replaceCost));
+    }
+    previousRow = currentRow;
+  }
+  return previousRow[b.length];
+}
+
+/**
+ * Find the closest matching branch name to a (likely mistyped) target.
+ * Returns the nearest candidate only when it is close enough to be a plausible
+ * typo, so we never suggest an unrelated branch.
+ *
+ * @param {string} target - The requested (not found) branch name
+ * @param {string[]} candidates - Existing branch names to compare against
+ * @returns {string|null} The closest branch name, or null if none is close enough
+ */
+export function findClosestBranchName(target, candidates) {
+  if (!target || !Array.isArray(candidates) || candidates.length === 0) {
+    return null;
+  }
+  // Allow a larger edit budget for longer names, but cap it so unrelated
+  // branches are never suggested (e.g. a 1-char typo on a 23-char branch).
+  const maxDistance = Math.max(2, Math.floor(target.length * 0.34));
+  let best = null;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    if (!candidate || candidate === target) continue;
+    const distance = levenshteinDistance(target, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+  return bestDistance <= maxDistance ? best : null;
+}
+
+/**
+ * Check whether a branch exists in the given repository using the GitHub API.
+ * Works without cloning the repo, so it can run during early validation
+ * (before the heavy clone/spawn work) for both the CLI and the Telegram bot.
+ *
+ * @param {Object} options
+ * @param {string} options.owner - Repository owner
+ * @param {string} options.repo - Repository name
+ * @param {string} options.baseBranch - Branch name to check
+ * @param {boolean} [options.verbose=false] - Verbose logging
+ * @returns {Promise<{exists: boolean, indeterminate?: boolean}>}
+ *   - exists: true if the branch is present (or the check was inconclusive — fail open)
+ *   - indeterminate: true when a non-404 error prevented a definitive answer
+ */
+export async function checkBaseBranchExists({ owner, repo, baseBranch, verbose = false }) {
+  try {
+    const result = await ghCmdRetry(() => $`gh api repos/${owner}/${repo}/branches/${baseBranch} --jq .name`, { label: `check branch ${baseBranch}` });
+    if (result.code === 0) {
+      return { exists: true };
+    }
+    const errorOutput = (result.stderr ? result.stderr.toString() : '') + (result.stdout ? result.stdout.toString() : '');
+    if (errorOutput.includes('404') || errorOutput.includes('Not Found') || errorOutput.includes('Branch not found')) {
+      return { exists: false };
+    }
+    // Non-404 errors (network, auth, rate limit): fail open so we don't block on transient issues.
+    verbose && console.log(`[VERBOSE] Entity check: Could not verify branch '${baseBranch}': ${errorOutput.trim()}`);
+    return { exists: true, indeterminate: true };
+  } catch (e) {
+    verbose && console.log(`[VERBOSE] Entity check: Branch check error for '${baseBranch}': ${e.message}`);
+    return { exists: true, indeterminate: true };
+  }
+}
+
+/**
+ * Build a user-facing error message for a missing base branch, optionally
+ * including a "did you mean" suggestion derived from the repo's branches.
+ *
+ * @param {Object} options
+ * @param {string} options.owner
+ * @param {string} options.repo
+ * @param {string} options.baseBranch
+ * @param {boolean} [options.verbose=false]
+ * @returns {Promise<string>} The formatted error message
+ */
+export async function buildMissingBaseBranchErrorMessage({ owner, repo, baseBranch, verbose = false }) {
+  let suggestion = '';
+  try {
+    const listResult = await ghCmdRetry(() => $`gh api repos/${owner}/${repo}/branches --paginate --jq .[].name`, { label: `list branches ${owner}/${repo}` });
+    if (listResult.code === 0) {
+      const branches = listResult.stdout
+        .toString()
+        .split('\n')
+        .map(s => s.trim())
+        .filter(Boolean);
+      const closest = findClosestBranchName(baseBranch, branches);
+      if (closest) {
+        suggestion = `\n\n💡 Did you mean '${closest}'? (closest existing branch)`;
+      }
+    }
+  } catch (e) {
+    verbose && console.log(`[VERBOSE] Entity check: Could not list branches for suggestion: ${e.message}`);
+  }
+  const listCmd = `gh api repos/${owner}/${repo}/branches --paginate --jq .[].name`;
+  return `Base branch '${baseBranch}' does not exist in ${owner}/${repo}.${suggestion}\n\n💡 Please check:\n• The branch name is spelled correctly\n• The branch has not been deleted or renamed\n• Omit --base-branch to use the repository's default branch\n• List existing branches: ${listCmd}`;
+}
+
+/**
+ * Validate existence of GitHub entities (user/org, repository, base branch, issue/PR)
+ * before executing a command. Checks each level in order, failing fast at the first
+ * missing entity: user/org → repository → base branch → issue/PR.
  *
  * When autoAcceptInvite is enabled, invitations should be accepted BEFORE calling this function,
  * so that newly-accepted repos/orgs are visible to the API checks.
@@ -21,6 +148,9 @@ import { ghPrView, ghIssueView } from './github.lib.mjs';
  * @param {string} options.repo - Repository name
  * @param {number|string} [options.number] - Issue or PR number (if applicable)
  * @param {string} [options.type] - URL type: 'issue' or 'pull'
+ * @param {string} [options.baseBranch] - Custom base branch (from --base-branch/--target-branch).
+ *   When provided, its existence is verified up-front so a typo fails fast with a clear
+ *   message instead of an opaque "Branch operation failed" after cloning (issue #1959).
  * @param {boolean} [options.verbose=false] - Whether verbose logging is enabled
  * @param {boolean} [options.autoAcceptInvite=false] - Whether the caller already passed
  *   `--auto-accept-invite`. When true, the repo-404 message omits the suggestion to
@@ -28,10 +158,10 @@ import { ghPrView, ghIssueView } from './github.lib.mjs';
  * @returns {Promise<{valid: boolean, error?: string, level?: string, details?: string}>}
  *   - valid: true if all entities exist and are accessible
  *   - error: user-facing error message (when valid=false)
- *   - level: which entity level failed ('user', 'repo', 'issue', 'pull')
+ *   - level: which entity level failed ('user', 'repo', 'branch', 'issue', 'pull')
  *   - details: additional context for verbose logging
  */
-export async function validateGitHubEntityExistence({ owner, repo, number, type, verbose = false, autoAcceptInvite = false }) {
+export async function validateGitHubEntityExistence({ owner, repo, number, type, baseBranch, verbose = false, autoAcceptInvite = false }) {
   // Step 1: Check user/organization existence
   try {
     const userResult = await ghCmdRetry(() => $`gh api users/${owner} --jq .login`, { label: `check user ${owner}` });
@@ -73,6 +203,24 @@ export async function validateGitHubEntityExistence({ owner, repo, number, type,
     verbose && console.log(`[VERBOSE] Entity check: Repo check error for '${owner}/${repo}': ${e.message}`);
   }
 
+  // Step 2.5: Check base branch existence (issue #1959)
+  // When the user passes --base-branch/--target-branch, verify it exists in the
+  // canonical repository up-front. A typo (e.g. an extra trailing character) would
+  // otherwise surface only after cloning as an opaque "Branch operation failed",
+  // and was even misdiagnosed as an "empty repository". Failing here gives the
+  // same fast, explicit feedback we already provide for repo/issue/PR — in the CLI
+  // and in the GitHub comment, and BEFORE the Telegram bot starts the solve run.
+  if (baseBranch) {
+    const branchCheck = await checkBaseBranchExists({ owner, repo, baseBranch, verbose });
+    if (!branchCheck.exists) {
+      return {
+        valid: false,
+        error: await buildMissingBaseBranchErrorMessage({ owner, repo, baseBranch, verbose }),
+        level: 'branch',
+      };
+    }
+  }
+
   // Step 3: Check issue or PR existence (if number is provided)
   if (number) {
     if (type === 'pull') {

package/src/lib.mjs

@@ -471,7 +471,10 @@ export const isTransientNetworkError = error => {
   const combined = msg + ' ' + output;
 
   // Issue #1536: added 'unexpected eof' — seen in gh CLI when connection drops mid-response
-  const transientPatterns = ['i/o timeout', 'dial tcp', 'connection refused', 'connection reset', 'econnreset', 'etimedout', 'enotfound', 'ehostunreach', 'enetunreach', 'network is unreachable', 'temporary failure', 'http 502', 'http 503', 'http 504', 'bad gateway', 'service unavailable', 'gateway timeout', 'tls handshake timeout', 'ssl_error', 'socket hang up', 'unexpected eof'];
+  // Issue #1957: added git fetch-pack/sideband disconnect patterns — seen when a
+  // `gh repo clone` / `git clone` connection drops mid-transfer, leaving an incomplete
+  // (or missing) working tree even though the wrapper can exit 0.
+  const transientPatterns = ['i/o timeout', 'dial tcp', 'connection refused', 'connection reset', 'econnreset', 'etimedout', 'enotfound', 'ehostunreach', 'enetunreach', 'network is unreachable', 'temporary failure', 'http 502', 'http 503', 'http 504', 'bad gateway', 'service unavailable', 'gateway timeout', 'tls handshake timeout', 'ssl_error', 'socket hang up', 'unexpected eof', 'unexpected disconnect', 'sideband', 'early eof', 'the remote end hung up', 'rpc failed', 'fetch-pack', 'index-pack failed', 'remote end hung up unexpectedly', 'transfer closed'];
 
   return transientPatterns.some(pattern => combined.includes(pattern));
 };

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

@@ -219,7 +219,7 @@ export async function handleBranchCheckoutError({ branchName, prNumber, errorOut
   }
 }
 
-export async function handleBranchCreationError({ branchName, errorOutput, tempDir, owner, repo, formatAligned, log }) {
+export async function handleBranchCreationError({ branchName, errorOutput, tempDir, owner, repo, baseBranch, branchSource, formatAligned, log }) {
   await log(`${formatAligned('❌', 'BRANCH CREATION FAILED', '')}`, { level: 'error' });
   await log('');
   await log('  🔍 What happened:');
@@ -234,6 +234,31 @@ export async function handleBranchCreationError({ branchName, errorOutput, tempD
   }
   await log('');
 
+  // Issue #1959: A failure to create the branch from origin/<baseBranch> looks
+  // identical at the git level to an empty repository ("is not a commit"). Only
+  // treat it as "empty repo" when the failing ref is NOT a custom base branch.
+  // When a custom base branch is involved and the error references it, report the
+  // real root cause: the requested base branch does not exist on the remote.
+  const errorMentionsBaseRef = baseBranch && (errorOutput.includes(`origin/${baseBranch}`) || errorOutput.includes(`'${baseBranch}'`));
+  const looksLikeMissingRef = errorOutput.includes('is not a commit') || errorOutput.includes('not a valid object name') || errorOutput.includes('unknown revision') || errorOutput.includes('did not match any');
+  const isMissingBaseBranchError = branchSource === 'custom' && errorMentionsBaseRef && looksLikeMissingRef;
+
+  if (isMissingBaseBranchError) {
+    await log('  💡 Root cause:');
+    await log(`     The requested base branch '${baseBranch}' does not exist on the remote.`);
+    await log('     A branch cannot be created from a base branch that is not there.');
+    await log('');
+    await log('  🔧 How to fix:');
+    await log('     • Check the branch name for typos (a single extra/missing character is enough)');
+    await log('     • Omit --base-branch to use the repository default branch');
+    if (owner && repo) {
+      await log(`     • List existing branches: gh api repos/${owner}/${repo}/branches --paginate --jq .[].name`);
+    } else {
+      await log('     • List existing branches: git branch -r');
+    }
+    return;
+  }
+
   // Check if this is an empty repository error (no commits to branch from)
   const isEmptyRepoError = errorOutput.includes('is not a commit') || errorOutput.includes('not a valid object name') || errorOutput.includes('unknown revision');
   if (isEmptyRepoError) {

package/src/solve.branch.lib.mjs

@@ -308,6 +308,10 @@ export async function createOrCheckoutBranch({ isContinueMode, prBranch, issueNu
   // Create a branch for the issue or checkout existing PR branch
   let branchName;
   let checkoutResult;
+  // Tracked across the create path so the error handler can report the real
+  // root cause when branch creation fails from a missing base branch (issue #1959).
+  let baseBranchForError = null;
+  let branchSourceForError = null;
 
   if (isContinueMode && prBranch) {
     // Continue mode: checkout existing PR branch
@@ -324,6 +328,8 @@ export async function createOrCheckoutBranch({ isContinueMode, prBranch, issueNu
     // Use user-specified base branch if provided, otherwise use repository default
     const baseBranch = argv.baseBranch || defaultBranch;
     const branchSource = argv.baseBranch ? 'custom' : 'default';
+    baseBranchForError = baseBranch;
+    branchSourceForError = branchSource;
 
     // Defense-in-depth: validate base branch name even if already validated at CLI parsing (issue #1482)
     const baseBranchValidation = validateBranchName(baseBranch);
@@ -391,6 +397,8 @@ export async function createOrCheckoutBranch({ isContinueMode, prBranch, issueNu
         tempDir,
         owner,
         repo,
+        baseBranch: baseBranchForError,
+        branchSource: branchSourceForError,
         formatAligned,
         log,
       });

package/src/solve.mjs

@@ -289,7 +289,7 @@ if (!hasWriteAccess) {
 }
 
 // Issue #1552: Validate entity existence AFTER permissions (cascade: user/org → repo → issue/PR)
-const entityCheck = await (await import('./github-entity-validation.lib.mjs')).validateGitHubEntityExistence({ owner, repo, number: urlNumber, type: isIssueUrl ? 'issue' : isPrUrl ? 'pull' : undefined, verbose: argv.verbose, autoAcceptInvite: !!argv.autoAcceptInvite });
+const entityCheck = await (await import('./github-entity-validation.lib.mjs')).validateGitHubEntityExistence({ owner, repo, number: urlNumber, type: isIssueUrl ? 'issue' : isPrUrl ? 'pull' : undefined, baseBranch: argv.baseBranch, verbose: argv.verbose, autoAcceptInvite: !!argv.autoAcceptInvite });
 if (!entityCheck.valid) {
   await log(`\n❌ ${entityCheck.error}\n`, { level: 'error' });
   await safeExit(1, `GitHub entity not found (${entityCheck.level})`);

package/src/solve.repo-setup.lib.mjs

@@ -65,9 +65,44 @@ export async function verifyDefaultBranchAndStatus({ tempDir, log, formatAligned
   const defaultBranchResult = await $({ cwd: tempDir })`git branch --show-current`;
 
   if (defaultBranchResult.code !== 0) {
+    // Issue #1957: the most common cause of this failure is an interrupted/incomplete
+    // clone — `git` reports "fatal: not a git repository" because there is no `.git`
+    // directory. The previous message ("Failed to get current branch") gave the user
+    // no idea what happened or what to do. Detect the incomplete-clone case and give
+    // concrete, actionable instructions instead.
+    const branchErr = ((defaultBranchResult.stderr?.toString() || '') + (defaultBranchResult.stdout?.toString() || '')).trim();
+    const isNotAGitRepo = /not a git repository/i.test(branchErr);
+
+    await log('');
+    await log(`${formatAligned('❌', isNotAGitRepo ? 'INCOMPLETE CLONE DETECTED' : 'FAILED TO READ CURRENT BRANCH', '')}`, { level: 'error' });
+    await log('');
+    await log('  🔍 What happened:');
+    if (isNotAGitRepo) {
+      await log(`     The working directory is not a valid git repository: ${tempDir}`);
+      await log('     This almost always means the clone was interrupted before it finished');
+      await log('     (e.g. "fetch-pack: unexpected disconnect while reading sideband packet"),');
+      await log('     so no .git directory was created.');
+    } else {
+      await log(`     Could not determine the current branch in: ${tempDir}`);
+    }
+    await log('');
+    await log('  📦 Error details:');
+    for (const line of (branchErr || 'Unknown error').split('\n')) {
+      if (line.trim()) await log(`     ${line}`);
+    }
+    await log('');
+    await log('  🔧 How to fix:');
+    await log('     1. Check your network connection / VPN / proxy (interrupted transfers are usually transient)');
+    await log('     2. Re-run the command — the solver retries clones automatically and a fresh run usually succeeds');
+    if (owner && repo) await log(`     3. Verify access to the repository: gh repo view ${owner}/${repo}`);
+    await log(`     ${owner && repo ? '4' : '3'}. Check GitHub status if it keeps failing: https://www.githubstatus.com`);
+    await log('');
+    await log('  ℹ️  If this is reproducible, ask a Hive Mind administrator to inspect the solver terminal log for the clone error.');
+    await log('');
+
     await log('Error: Failed to get current branch');
-    await log(defaultBranchResult.stderr ? defaultBranchResult.stderr.toString() : 'Unknown error');
-    throw new Error('Failed to get current branch');
+    if (branchErr) await log(branchErr);
+    throw new Error(isNotAGitRepo ? 'Failed to get current branch - working directory is not a git repository (incomplete clone)' : 'Failed to get current branch');
   }
 
   let defaultBranch = defaultBranchResult.stdout.toString().trim();

package/src/solve.repository.lib.mjs

@@ -922,8 +922,12 @@ export const classifyCloneError = errorOutput => {
   }
 
   // Network-related errors - typically retryable
-  if (output.includes('connection refused') || output.includes('connection timed out') || output.includes('connection reset') || output.includes('unable to connect') || output.includes('network is unreachable') || output.includes('ssl error')) {
-    return { type: 'NETWORK', retryable: true, description: 'Network connectivity issue' };
+  // Issue #1957: git fetch-pack/sideband disconnects (e.g.
+  // "fetch-pack: unexpected disconnect while reading sideband packet",
+  // "early EOF", "the remote end hung up unexpectedly", "RPC failed",
+  // "index-pack failed") leave an incomplete or missing clone but are transient.
+  if (output.includes('connection refused') || output.includes('connection timed out') || output.includes('connection reset') || output.includes('unable to connect') || output.includes('network is unreachable') || output.includes('ssl error') || output.includes('unexpected disconnect') || output.includes('sideband') || output.includes('early eof') || output.includes('remote end hung up') || output.includes('rpc failed') || output.includes('fetch-pack') || output.includes('index-pack failed') || output.includes('transfer closed')) {
+    return { type: 'NETWORK', retryable: true, description: 'Network connectivity issue (interrupted transfer)' };
   }
 
   // Authentication/permission errors - not retryable
@@ -945,6 +949,24 @@ export const classifyCloneError = errorOutput => {
   return { type: 'UNKNOWN', retryable: true, description: 'Unknown error' };
 };
 
+// Issue #1957: remove leftovers from an interrupted clone so a retry can start clean.
+// We empty the directory in place (rather than removing it) because the path was
+// created up-front by setupTempDirectory and may be the configured working directory.
+export const cleanPartialClone = async tempDir => {
+  try {
+    const entries = await fs.readdir(tempDir);
+    for (const entry of entries) {
+      await fs.rm(path.join(tempDir, entry), { recursive: true, force: true });
+    }
+  } catch (error) {
+    // Directory may not exist yet, or be unreadable — non-fatal; the retry/clone
+    // will surface any real problem with a clearer message.
+    if (error?.code !== 'ENOENT') {
+      reportError(error, { context: 'clean_partial_clone', tempDir, operation: 'empty_directory' });
+    }
+  }
+};
+
 // Clone repository and set up remotes with retry mechanism
 export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) => {
   const maxRetries = 3;
@@ -959,9 +981,25 @@ export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) =
 
     // Use 2>&1 to capture all output and filter "Cloning into" message
     const cloneResult = await $`gh repo clone ${repoToClone} ${tempDir} 2>&1`;
-
-    // Verify clone was successful
+    const cloneOutput = (cloneResult.stdout || cloneResult.stderr || '').toString().trim();
+
+    // Issue #1957: `gh repo clone` (and the `git clone` it wraps) can exit 0 even when
+    // the underlying transfer was interrupted — e.g. "fetch-pack: unexpected disconnect
+    // while reading sideband packet" — leaving an incomplete or completely missing
+    // working tree (no `.git`). Trusting the exit code alone made the solver report
+    // "✅ Cloned to:" and then crash much later with the unhelpful "Failed to get
+    // current branch". Verify the clone actually produced a usable git repository.
+    let repoIsValid = false;
     if (cloneResult.code === 0) {
+      const validityCheck = await $({ cwd: tempDir })`git rev-parse --is-inside-work-tree 2>&1`;
+      repoIsValid = validityCheck.code === 0 && validityCheck.stdout.toString().trim() === 'true';
+      if (!repoIsValid && argv.verbose) {
+        await log(`${formatAligned('🔧', 'Clone validation:', `git rev-parse failed despite exit 0 — ${(validityCheck.stdout || validityCheck.stderr || '').toString().trim().split('\n')[0]}`)}`);
+      }
+    }
+
+    // Verify clone was successful (exit code 0 AND a valid working tree exists)
+    if (cloneResult.code === 0 && repoIsValid) {
       await log(`${formatAligned('✅', 'Cloned to:', tempDir)}`);
 
       // Verify and fix remote configuration
@@ -975,7 +1013,15 @@ export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) =
     }
 
     // Clone failed - analyze error and determine if retry is appropriate
-    const errorOutput = (cloneResult.stderr || cloneResult.stdout || 'Unknown error').toString().trim();
+    // Issue #1957: when the wrapper exited 0 but left no valid repo, surface the
+    // interrupted-transfer output (which carries the real "unexpected disconnect"
+    // reason) so it is classified as a retryable network error rather than UNKNOWN.
+    const errorOutput = cloneResult.code === 0 && !repoIsValid ? cloneOutput || 'Clone exited 0 but no valid git repository was created (interrupted transfer / incomplete clone)' : (cloneResult.stderr || cloneResult.stdout || 'Unknown error').toString().trim();
+
+    // Issue #1957: a partial clone can leave stray files behind that make a retry of
+    // `gh repo clone <dir>` fail with "directory exists and is not empty". Clean the
+    // target directory before classifying/retrying so the next attempt starts fresh.
+    await cleanPartialClone(tempDir);
 
     const errorClassification = classifyCloneError(errorOutput);
 
@@ -1015,6 +1061,9 @@ export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) =
         await log('     • Network connectivity issues');
         if (errorClassification.type === 'TRANSIENT') await log('     • GitHub server issues (temporary)');
         if (errorClassification.type === 'RATE_LIMIT') await log('     • API rate limiting exceeded');
+        // Issue #1957: the transfer started but was interrupted (e.g. the connection
+        // dropped while reading the pack). The retries above were already exhausted.
+        if (errorClassification.type === 'NETWORK') await log('     • Connection dropped mid-transfer (the clone was interrupted before completing)');
         if (argv.fork) await log('     • Fork not ready yet (try again in a moment)');
         await log('');
         await log('  🔧 How to fix:');
@@ -1024,6 +1073,11 @@ export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) =
         if (argv.fork) await log(`     4. Check fork: gh repo view ${repoToClone}`);
         if (errorClassification.type === 'TRANSIENT') await log('     5. Wait and retry / check: https://www.githubstatus.com');
         if (errorClassification.type === 'RATE_LIMIT') await log('     5. Wait for rate limit to reset or use --token with different token');
+        if (errorClassification.type === 'NETWORK') {
+          await log('     5. Check your network connection / VPN / proxy, then re-run the command');
+          await log('     6. On slow or unstable links, a shallower history transfers faster and is less');
+          await log('        likely to be interrupted; ask a Hive Mind administrator if clone tuning is available');
+        }
         await log('');
       }
       await safeExit(1, 'Repository setup failed');

package/src/telegram-bot.mjs

@@ -873,7 +873,7 @@ async function handleSolveCommand(ctx) {
   }
   // Issue #1714: read the parsed argv (default-on per #1694) instead of the raw args list,
   // so the invite hint is suppressed on the default-on path where the literal flag is absent.
-  const entityCheck = await validateGitHubEntityExistence({ owner: validation.parsed.owner, repo: validation.parsed.repo, number: validation.parsed.number, type: validation.parsed.type, verbose: VERBOSE, autoAcceptInvite: !!parsedSolveArgs?.autoAcceptInvite });
+  const entityCheck = await validateGitHubEntityExistence({ owner: validation.parsed.owner, repo: validation.parsed.repo, number: validation.parsed.number, type: validation.parsed.type, baseBranch: parsedSolveArgs?.baseBranch, verbose: VERBOSE, autoAcceptInvite: !!parsedSolveArgs?.autoAcceptInvite });
   if (!entityCheck.valid) {
     await safeReply(ctx, `❌ ${escapeMarkdown(entityCheck.error)}`, { reply_to_message_id: ctx.message.message_id });
     return;