@link-assistant/hive-mind 2.0.12 → 2.0.14

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @link-assistant/hive-mind
 
+## 2.0.14
+
+### Patch Changes
+
+- 03954a9: Show fuzzy suggestions for mistyped CLI and Telegram command options, including the closest match plus up to four additional alternatives.
+
+## 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

package/package.json

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

package/src/cli-arguments.lib.mjs

@@ -1,5 +1,7 @@
 import { getenv, makeConfig, yargs as linoYargs } from 'lino-arguments';
 
+import { enhanceUnknownArgumentError } from './option-suggestions.lib.mjs';
+
 export { getenv };
 
 export const hideBin = argv => argv.slice(2);
@@ -52,17 +54,24 @@ export function addCliCompatibilityAliases(parsed, { positionalAliases = [] } =
 
 export function parseCliArgumentsWithLino({ argv = process.argv, commandName = 'cli', createYargsConfig, positionalAliases = [], lenv = { enabled: true }, env = { enabled: false }, getenv: getenvOptions = { enabled: true } } = {}) {
   const fullArgv = ensureFullArgv(argv, commandName);
-  const parsed = makeConfig({
-    argv: fullArgv,
-    lenv,
-    env,
-    getenv: getenvOptions,
-    yargs: ({ yargs, getenv: getenvHelper }) => {
-      const parser = yargs.exitProcess(false);
-      const configured = createYargsConfig ? createYargsConfig(parser, getenvHelper) : parser;
-      return configured.exitProcess(false);
-    },
-  });
+  let configuredParser = null;
+  let parsed;
+
+  try {
+    parsed = makeConfig({
+      argv: fullArgv,
+      lenv,
+      env,
+      getenv: getenvOptions,
+      yargs: ({ yargs, getenv: getenvHelper }) => {
+        const parser = yargs.exitProcess(false);
+        configuredParser = createYargsConfig ? createYargsConfig(parser, getenvHelper) : parser;
+        return configuredParser.exitProcess(false);
+      },
+    });
+  } catch (error) {
+    throw enhanceUnknownArgumentError(error, configuredParser);
+  }
 
   return addCliCompatibilityAliases(parsed, { positionalAliases });
 }

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/option-suggestions.lib.mjs

@@ -44,79 +44,97 @@ export function calculateLevenshteinDistance(a, b) {
   return matrix[b.length][a.length];
 }
 
-/**
- * Find similar option names based on Levenshtein distance
- *
- * @param {string} unknownOption - The option name that was not recognized (e.g., "branch")
- * @param {Object} yargsInstance - The yargs instance with defined options
- * @param {number} maxSuggestions - Maximum number of suggestions to return (default: 3)
- * @param {number} distanceThreshold - Maximum distance to consider for suggestions (default: 5)
- * @returns {string[]} - Array of suggested option names, sorted by similarity
- */
-export function findSimilarOptions(unknownOption, yargsInstance, maxSuggestions = 3, distanceThreshold = 5) {
-  // Remove leading dashes from the unknown option
-  const cleanUnknown = unknownOption.replace(/^-+/, '');
+const normalizeOptionName = option =>
+  String(option || '')
+    .trim()
+    .replace(/^-+/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_\s]+/g, '-')
+    .toLowerCase();
 
-  // Get all available options from yargs
+const compactOptionName = option => normalizeOptionName(option).replace(/-/g, '');
+
+function getAvailableOptionNames(yargsInstance, includeShortAliases) {
   const availableOptions = yargsInstance.getOptions();
   const allOptions = new Set();
+  const rawHiddenOptions = availableOptions.hiddenOptions || [];
+  const hiddenOptionNames = Array.isArray(rawHiddenOptions) ? rawHiddenOptions : Object.keys(rawHiddenOptions);
+  const hiddenOptions = new Set(hiddenOptionNames.map(normalizeOptionName));
+
+  const addOption = option => {
+    const normalized = normalizeOptionName(option);
+    if (!normalized || hiddenOptions.has(normalized)) return;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) return;
+    if (!includeShortAliases && normalized.length === 1) return;
+    allOptions.add(normalized);
+  };
 
-  // Collect all option names (both long form and aliases)
   if (availableOptions.key) {
-    // Ensure it's an array before iterating
     const keys = Array.isArray(availableOptions.key) ? availableOptions.key : Object.keys(availableOptions.key || {});
-    keys.forEach(opt => {
-      allOptions.add(opt);
-    });
+    keys.forEach(addOption);
   }
 
-  // Collect aliases
   if (availableOptions.alias) {
     Object.entries(availableOptions.alias).forEach(([key, aliases]) => {
-      allOptions.add(key);
+      addOption(key);
       if (Array.isArray(aliases)) {
-        aliases.forEach(alias => allOptions.add(alias));
+        aliases.forEach(addOption);
       } else if (aliases) {
-        // If it's not an array but exists, add it as a single alias
-        allOptions.add(String(aliases));
+        addOption(aliases);
       }
     });
   }
 
-  // Calculate distance for each option
+  return allOptions;
+}
+
+/**
+ * Find similar option names based on Levenshtein distance
+ *
+ * @param {string} unknownOption - The option name that was not recognized (e.g., "branch")
+ * @param {Object} yargsInstance - The yargs instance with defined options
+ * @param {number} maxSuggestions - Maximum number of suggestions to return (default: 5)
+ * @param {number} distanceThreshold - Maximum distance to consider for suggestions (default: 5)
+ * @returns {string[]} - Array of suggested option names, sorted by similarity
+ */
+export function findSimilarOptions(unknownOption, yargsInstance, maxSuggestions = 5, distanceThreshold = 5) {
+  const cleanUnknown = normalizeOptionName(unknownOption);
+  const compactUnknown = compactOptionName(unknownOption);
+  const includeShortAliases = cleanUnknown.length === 1;
+  const allOptions = getAvailableOptionNames(yargsInstance, includeShortAliases);
+
   const distances = [];
   allOptions.forEach(option => {
-    const distance = calculateLevenshteinDistance(cleanUnknown, option);
-    if (distance <= distanceThreshold) {
-      // Calculate bonus score for substring matches
-      // If the unknown option is a substring of the valid option, it's likely what the user meant
-      // Check both directions: is unknown a substring of option, or is option a substring of unknown
-      const unknownInOption = option.includes(cleanUnknown);
-      const optionInUnknown = cleanUnknown.includes(option);
-
-      // Strong bonus for when user typed a word that appears in the option name
-      // e.g., "branch" appears in "base-branch"
-      const substringBonus = unknownInOption ? -10 : optionInUnknown ? -5 : 0;
+    const distance = Math.min(calculateLevenshteinDistance(cleanUnknown, option), calculateLevenshteinDistance(compactUnknown, compactOptionName(option)));
+    const unknownInOption = option.includes(cleanUnknown) || compactOptionName(option).includes(compactUnknown);
+    const optionInUnknown = cleanUnknown.includes(option) || compactUnknown.includes(compactOptionName(option));
 
-      // Also prioritize options with similar length (user likely tried to type the full name)
+    if (distance <= distanceThreshold || unknownInOption || optionInUnknown) {
+      const substringBonus = unknownInOption ? -10 : optionInUnknown ? -5 : 0;
       const lengthDiff = Math.abs(option.length - cleanUnknown.length);
       const lengthBonus = lengthDiff < 3 ? -1 : 0;
 
       distances.push({
         option,
         distance,
+        lengthDiff,
         effectiveDistance: distance + substringBonus + lengthBonus,
       });
     }
   });
 
-  // Sort by effective distance (closest first), then by actual distance
   return distances
     .sort((a, b) => {
       if (a.effectiveDistance !== b.effectiveDistance) {
         return a.effectiveDistance - b.effectiveDistance;
       }
-      return a.distance - b.distance;
+      if (a.distance !== b.distance) {
+        return a.distance - b.distance;
+      }
+      if (a.lengthDiff !== b.lengthDiff) {
+        return a.lengthDiff - b.lengthDiff;
+      }
+      return a.option.localeCompare(b.option);
     })
     .slice(0, maxSuggestions)
     .map(item => item.option);
@@ -133,17 +151,17 @@ export function formatSuggestions(suggestions) {
     return '';
   }
 
-  if (suggestions.length === 1) {
-    return `\n\nDid you mean --${suggestions[0]}?`;
-  }
-
-  // For multiple suggestions, format them nicely
   const formattedOptions = suggestions.map(opt => {
     // If it's a single character, show as -x, otherwise --option-name
     return opt.length === 1 ? `-${opt}` : `--${opt}`;
   });
+  const [primarySuggestion, ...alternatives] = formattedOptions;
 
-  return `\n\nDid you mean one of these?\n${formattedOptions.map(opt => `  • ${opt}`).join('\n')}`;
+  if (alternatives.length === 0) {
+    return `\n\nDid you mean \`${primarySuggestion}\` option?`;
+  }
+
+  return `\n\nDid you mean \`${primarySuggestion}\` option?\n\nOther close matches:\n${alternatives.map(opt => `  • \`${opt}\``).join('\n')}`;
 }
 
 /**
@@ -300,9 +318,13 @@ export function detectMalformedFlags(args) {
  * @returns {string} - Enhanced error message with suggestions
  */
 export function enhanceErrorMessage(originalError, yargsInstance) {
+  if (/Did you mean/i.test(originalError)) {
+    return originalError;
+  }
+
   // Extract the unknown option name from the error message
   // Typical format: "Unknown argument: branch" or "Unknown arguments: branch, test"
-  const unknownMatch = originalError.match(/Unknown arguments?:\s*(.+?)(?:\s|$)/i);
+  const unknownMatch = originalError.match(/Unknown arguments?:\s*([^\n]+)/i);
 
   if (!unknownMatch) {
     return originalError;
@@ -324,3 +346,23 @@ export function enhanceErrorMessage(originalError, yargsInstance) {
 
   return enhancedMessage;
 }
+
+export function enhanceUnknownArgumentError(error, yargsInstance) {
+  if (!error || error._enhanced || !yargsInstance || !/Unknown arguments?/i.test(error.message || '')) {
+    return error;
+  }
+
+  const enhancedMessage = enhanceErrorMessage(error.message, yargsInstance);
+  if (enhancedMessage === error.message) {
+    return error;
+  }
+
+  const enhancedError = new Error(enhancedMessage);
+  enhancedError.name = error.name;
+  enhancedError.cause = error;
+  for (const key of Object.keys(error)) {
+    enhancedError[key] = error[key];
+  }
+  enhancedError._enhanced = true;
+  return enhancedError;
+}

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/telegram-bot.mjs

@@ -25,6 +25,7 @@ await loadLenvConfig({ override: true, quiet: true });
 const yargs = getLinoYargsFactory();
 const { createYargsConfig: createSolveYargsConfig, detectMalformedFlags } = await import('./solve.config.lib.mjs');
 const { createYargsConfig: createHiveYargsConfig } = await import('./hive.config.lib.mjs');
+const { enhanceUnknownArgumentError } = await import('./option-suggestions.lib.mjs');
 const { validateBranchInArgs } = await import('./solve.branch.lib.mjs');
 const { extractIsolationFromArgs, isValidPerCommandIsolation } = await import('./telegram-isolation.lib.mjs');
 
@@ -229,7 +230,8 @@ if (solveEnabled && solveOverrides.length > 0) {
       process.stderr.write = originalStderrWrite;
     }
   } catch (error) {
-    console.error(`❌ Invalid solve-overrides: ${error.message || String(error)}`);
+    const enhancedError = enhanceUnknownArgumentError(error, createSolveYargsConfig(yargs()));
+    console.error(`❌ Invalid solve-overrides: ${enhancedError.message || String(enhancedError)}`);
     console.error(`   Overrides: ${solveOverrides.join(' ')}`);
     process.exit(1);
   }
@@ -275,7 +277,8 @@ if (hiveEnabled && hiveOverrides.length > 0) {
       process.stderr.write = originalStderrWrite;
     }
   } catch (error) {
-    console.error(`❌ Invalid hive-overrides: ${error.message || String(error)}`);
+    const enhancedError = enhanceUnknownArgumentError(error, createHiveYargsConfig(yargs()));
+    console.error(`❌ Invalid hive-overrides: ${enhancedError.message || String(enhancedError)}`);
     console.error(`   Overrides: ${hiveOverrides.join(' ')}`);
     process.exit(1);
   }
@@ -873,7 +876,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;

package/src/telegram-solve-command.lib.mjs

@@ -8,6 +8,8 @@
  * @see https://github.com/link-assistant/hive-mind/issues/1618
  */
 
+import { enhanceUnknownArgumentError } from './option-suggestions.lib.mjs';
+
 export const TOOL_SOLVE_COMMAND_ALIASES = Object.freeze({
   claude: 'claude',
   codex: 'codex',
@@ -89,8 +91,9 @@ export async function parseArgsWithYargs(args, yargsFactory, createYargsConfig)
     else if (typeof callback === 'function') callback();
     return true;
   };
+  let parser = null;
   try {
-    const parser = createYargsConfig(yargsFactory());
+    parser = createYargsConfig(yargsFactory());
     parser
       .exitProcess(false)
       .showHelpOnFail(false)
@@ -98,6 +101,8 @@ export async function parseArgsWithYargs(args, yargsFactory, createYargsConfig)
         throw err || new Error(msg || 'Invalid arguments');
       });
     return await parser.parse(args);
+  } catch (error) {
+    throw enhanceUnknownArgumentError(error, parser);
   } finally {
     process.stderr.write = originalStderrWrite;
   }

package/src/telegram-task-command.lib.mjs

@@ -1,10 +1,12 @@
 import { buildUserMention } from './buildUserMention.lib.mjs';
 import { validateModelName } from './models/index.mjs';
+import { getLinoYargsFactory } from './cli-arguments.lib.mjs';
+import { createYargsConfig as createTaskYargsConfig } from './task.config.lib.mjs';
 import { createTaskIssue, parseTaskIssueCreationInput, resolveTaskIssueCreationInput } from './task.issue-creation.lib.mjs';
 import { parseTaskIssueUrl } from './task.split.lib.mjs';
 import { escapeMarkdown } from './telegram-markdown.lib.mjs';
 import { extractIsolationFromArgs, isValidPerCommandIsolation } from './telegram-isolation.lib.mjs';
-import { moveArgumentToFront, parseCommandArgs } from './telegram-solve-command.lib.mjs';
+import { moveArgumentToFront, parseArgsWithYargs, parseCommandArgs } from './telegram-solve-command.lib.mjs';
 import { formatStartingWorkSessionMessage } from './work-session-formatting.lib.mjs';
 
 export const TASK_COMMAND_NAMES = Object.freeze(['task', 'split']);
@@ -187,6 +189,13 @@ export function registerTaskCommands(bot, options) {
       return;
     }
 
+    try {
+      await parseArgsWithYargs(filteredArgs, getLinoYargsFactory(), createTaskYargsConfig);
+    } catch (error) {
+      await safeReply(ctx, `❌ Invalid options: ${escapeMarkdown(error.message || String(error))}\n\nUse /help to see available options`, { reply_to_message_id: ctx.message.message_id });
+      return;
+    }
+
     const modelError = validateTaskModel(filteredArgs);
     if (modelError) {
       await safeReply(ctx, `❌ ${escapeMarkdown(modelError)}`, { reply_to_message_id: ctx.message.message_id });