@link-assistant/hive-mind 1.21.0 → 1.21.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @link-assistant/hive-mind
 
+## 1.21.2
+
+### Patch Changes
+
+- 586b84d: Add retry mechanism for GitHub 500 errors during repository clone
+
+  This change adds intelligent retry logic with exponential backoff to handle transient GitHub server errors during repository cloning operations.
+
+## 1.21.1
+
+### Patch Changes
+
+- fbfc0c3: Fix `--tool agent` pricing display for free models (Issue #1250)
+  - Add base model pricing lookup for free model variants (e.g., `kimi-k2.5-free` → `kimi-k2.5`)
+  - Show actual market price as "Public pricing estimate" based on the underlying paid model
+  - Display base model reference in cost output: "(based on Moonshot AI kimi-k2.5 prices)"
+  - Distinguish between truly free models and free access to paid models
+  - Fix token usage showing "0 input, 0 output" by accumulating tokens during streaming
+  - Token accumulation now happens in real-time as step_finish events arrive, avoiding NDJSON concatenation issues
+
 ## 1.21.0
 
 ### Minor Changes

package/package.json

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

package/src/agent.lib.mjs

@@ -100,11 +100,59 @@ const getOriginalProviderName = providerId => {
   return providerMap[providerId] || providerId.charAt(0).toUpperCase() + providerId.slice(1);
 };
 
+/**
+ * Issue #1250: Normalize model name and find base model for pricing lookup
+ * Free models like "kimi-k2.5-free" should use pricing from base model "kimi-k2.5"
+ *
+ * @param {string} modelName - The model name (e.g., 'kimi-k2.5-free')
+ * @returns {Object} Object with:
+ *   - baseModelName: The base model name for pricing lookup
+ *   - isFreeVariant: Whether this is a free variant
+ */
+const getBaseModelForPricing = modelName => {
+  // Known mappings for free models to their base paid versions
+  const freeToBaseMap = {
+    'kimi-k2.5-free': 'kimi-k2.5',
+    'glm-4.7-free': 'glm-4.7',
+    'minimax-m2.1-free': 'minimax-m2.1',
+    'trinity-large-preview-free': 'trinity-large-preview',
+    // Grok models don't have a paid equivalent with same name
+    // These are kept as-is since they're truly free
+  };
+
+  // Check if there's a direct mapping
+  if (freeToBaseMap[modelName]) {
+    return {
+      baseModelName: freeToBaseMap[modelName],
+      isFreeVariant: true,
+    };
+  }
+
+  // Try removing "-free" suffix
+  if (modelName.endsWith('-free')) {
+    return {
+      baseModelName: modelName.replace(/-free$/, ''),
+      isFreeVariant: true,
+    };
+  }
+
+  // Not a free variant
+  return {
+    baseModelName: modelName,
+    isFreeVariant: false,
+  };
+};
+
 /**
  * Calculate pricing for agent tool usage using models.dev API
  * Issue #1250: Shows actual provider (OpenCode Zen) and calculates public pricing estimate
  * based on original provider prices (Moonshot AI, OpenAI, Anthropic, etc.)
  *
+ * For free models like "kimi-k2.5-free", this function:
+ * 1. First fetches the free model info to get the model name
+ * 2. Then fetches the base model (e.g., "kimi-k2.5") for actual pricing
+ * 3. Calculates public pricing estimate based on the base model's cost
+ *
  * @param {string} modelId - The model ID used (e.g., 'opencode/grok-code')
  * @param {Object} tokenUsage - Token usage data from parseAgentTokenUsage
  * @returns {Object} Pricing information with:
@@ -122,40 +170,66 @@ export const calculateAgentPricing = async (modelId, tokenUsage) => {
   const providerFromModel = modelId.includes('/') ? modelId.split('/')[0] : null;
 
   // Get original provider name for pricing reference
-  const originalProvider = getOriginalProviderName(providerFromModel);
+  let originalProvider = getOriginalProviderName(providerFromModel);
 
   try {
     // Fetch model info from models.dev API
-    const modelInfo = await fetchModelInfo(modelName);
+    let modelInfo = await fetchModelInfo(modelName);
+
+    // Issue #1250: Check if model has zero pricing (free model from OpenCode Zen)
+    // If so, look up the base model for actual public pricing estimate
+    const { baseModelName, isFreeVariant } = getBaseModelForPricing(modelName);
+    let baseModelInfo = null;
+    let pricingCost = modelInfo?.cost;
+
+    if (modelInfo && modelInfo.cost && modelInfo.cost.input === 0 && modelInfo.cost.output === 0 && baseModelName !== modelName) {
+      // This is a free model with zero pricing - look up base model for public pricing
+      baseModelInfo = await fetchModelInfo(baseModelName);
+      if (baseModelInfo && baseModelInfo.cost) {
+        // Use base model pricing for public estimate
+        pricingCost = baseModelInfo.cost;
+        // Update original provider from base model if available
+        if (baseModelInfo.provider && !originalProvider) {
+          originalProvider = baseModelInfo.provider;
+        }
+      }
+    }
 
-    if (modelInfo && modelInfo.cost) {
-      const cost = modelInfo.cost;
+    if (modelInfo || baseModelInfo) {
+      const effectiveModelInfo = modelInfo || baseModelInfo;
+      const cost = pricingCost || { input: 0, output: 0, cache_read: 0, cache_write: 0, reasoning: 0 };
 
       // Calculate public pricing estimate based on original provider prices
       // Prices are per 1M tokens, so divide by 1,000,000
+      // All priced components from models.dev: input, output, cache_read, cache_write, reasoning
       const inputCost = (tokenUsage.inputTokens * (cost.input || 0)) / 1_000_000;
       const outputCost = (tokenUsage.outputTokens * (cost.output || 0)) / 1_000_000;
       const cacheReadCost = (tokenUsage.cacheReadTokens * (cost.cache_read || 0)) / 1_000_000;
       const cacheWriteCost = (tokenUsage.cacheWriteTokens * (cost.cache_write || 0)) / 1_000_000;
+      const reasoningCost = (tokenUsage.reasoningTokens * (cost.reasoning || 0)) / 1_000_000;
 
-      const totalCost = inputCost + outputCost + cacheReadCost + cacheWriteCost;
+      const totalCost = inputCost + outputCost + cacheReadCost + cacheWriteCost + reasoningCost;
 
       // Determine if this is a free model from OpenCode Zen
       // Models accessed via OpenCode Zen are free, regardless of original provider pricing
-      const isOpencodeFreeModel = providerFromModel === 'opencode' || modelName.toLowerCase().includes('free') || modelName.toLowerCase().includes('grok') || providerFromModel === 'moonshot' || providerFromModel === 'openai' || providerFromModel === 'anthropic';
+      const isOpencodeFreeModel = providerFromModel === 'opencode' || isFreeVariant || modelName.toLowerCase().includes('free') || modelName.toLowerCase().includes('grok') || providerFromModel === 'moonshot' || providerFromModel === 'openai' || providerFromModel === 'anthropic';
+
+      // Use base model's provider for original provider reference if available
+      const effectiveOriginalProvider = baseModelInfo?.provider || originalProvider || effectiveModelInfo?.provider || null;
 
       return {
         modelId,
-        modelName: modelInfo.name || modelName,
+        modelName: effectiveModelInfo?.name || modelName,
         // Issue #1250: Always show OpenCode Zen as actual provider
         provider: 'OpenCode Zen',
         // Store original provider for reference in pricing display
-        originalProvider: originalProvider || modelInfo.provider || null,
+        originalProvider: effectiveOriginalProvider,
         pricing: {
           inputPerMillion: cost.input || 0,
           outputPerMillion: cost.output || 0,
           cacheReadPerMillion: cost.cache_read || 0,
           cacheWritePerMillion: cost.cache_write || 0,
+          reasoningPerMillion: cost.reasoning || 0,
         },
         tokenUsage,
         breakdown: {
@@ -163,15 +237,18 @@ export const calculateAgentPricing = async (modelId, tokenUsage) => {
           output: outputCost,
           cacheRead: cacheReadCost,
           cacheWrite: cacheWriteCost,
+          reasoning: reasoningCost,
         },
-        // Public pricing estimate based on original provider prices
+        // Public pricing estimate based on original/base model prices
         totalCostUSD: totalCost,
         // Actual cost from OpenCode Zen (free for supported models)
         opencodeCost: isOpencodeFreeModel ? 0 : totalCost,
-        // Keep for backward compatibility - indicates if model has zero pricing
-        isFreeModel: cost.input === 0 && cost.output === 0,
+        // Keep for backward compatibility - indicates if the accessed model has zero pricing
+        isFreeModel: modelInfo?.cost?.input === 0 && modelInfo?.cost?.output === 0,
         // New flag to indicate if OpenCode Zen provides this model for free
         isOpencodeFreeModel,
+        // Issue #1250: Include base model info for transparency
+        baseModelName: baseModelName !== modelName ? baseModelName : null,
       };
     }
     // Model not found in API, return what we have
@@ -476,11 +553,39 @@ export const executeAgentCommand = async params => {
       let limitReached = false;
       let limitResetTime = null;
       let lastMessage = '';
-      let fullOutput = ''; // Collect all output for pricing calculation and error detection
+      let fullOutput = ''; // Collect all output for error detection (kept for backward compatibility)
       // Issue #1201: Track error events detected during streaming for reliable error detection
       // Post-hoc detection on fullOutput can miss errors if NDJSON lines get concatenated without newlines
       let streamingErrorDetected = false;
       let streamingErrorMessage = null;
+      // Issue #1250: Accumulate token usage during streaming instead of parsing fullOutput later
+      // This fixes the issue where NDJSON lines get concatenated without newlines, breaking JSON.parse
+      const streamingTokenUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        reasoningTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        totalCost: 0,
+        stepCount: 0,
+      };
+      // Helper to accumulate tokens from step_finish events during streaming
+      const accumulateTokenUsage = data => {
+        if (data.type === 'step_finish' && data.part?.tokens) {
+          const tokens = data.part.tokens;
+          streamingTokenUsage.stepCount++;
+          if (tokens.input) streamingTokenUsage.inputTokens += tokens.input;
+          if (tokens.output) streamingTokenUsage.outputTokens += tokens.output;
+          if (tokens.reasoning) streamingTokenUsage.reasoningTokens += tokens.reasoning;
+          if (tokens.cache) {
+            if (tokens.cache.read) streamingTokenUsage.cacheReadTokens += tokens.cache.read;
+            if (tokens.cache.write) streamingTokenUsage.cacheWriteTokens += tokens.cache.write;
+          }
+          if (data.part.cost !== undefined) {
+            streamingTokenUsage.totalCost += data.part.cost;
+          }
+        }
+      };
 
       for await (const chunk of execCommand.stream()) {
         if (chunk.type === 'stdout') {
@@ -500,6 +605,8 @@ export const executeAgentCommand = async params => {
                 sessionId = data.sessionID;
                 await log(`📌 Session ID: ${sessionId}`);
               }
+              // Issue #1250: Accumulate token usage during streaming
+              accumulateTokenUsage(data);
               // Issue #1201: Detect error events during streaming for reliable detection
               if (data.type === 'error' || data.type === 'step_error') {
                 streamingErrorDetected = true;
@@ -532,6 +639,8 @@ export const executeAgentCommand = async params => {
                   sessionId = stderrData.sessionID;
                   await log(`📌 Session ID: ${sessionId}`);
                 }
+                // Issue #1250: Accumulate token usage during streaming (stderr)
+                accumulateTokenUsage(stderrData);
                 // Issue #1201: Detect error events during streaming (stderr) for reliable detection
                 if (stderrData.type === 'error' || stderrData.type === 'step_error') {
                   streamingErrorDetected = true;
@@ -646,8 +755,9 @@ export const executeAgentCommand = async params => {
         await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
         await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
 
-        // Parse token usage even on failure (partial work may have been done)
-        const tokenUsage = parseAgentTokenUsage(fullOutput);
+        // Issue #1250: Use streaming-accumulated token usage instead of re-parsing fullOutput
+        // This fixes the issue where NDJSON lines get concatenated without newlines, breaking JSON.parse
+        const tokenUsage = streamingTokenUsage;
         const pricingInfo = await calculateAgentPricing(mappedModel, tokenUsage);
 
         return {
@@ -664,29 +774,47 @@ export const executeAgentCommand = async params => {
 
       await log('\n\n✅ Agent command completed');
 
-      // Parse token usage from collected output
-      const tokenUsage = parseAgentTokenUsage(fullOutput);
+      // Issue #1250: Use streaming-accumulated token usage instead of re-parsing fullOutput
+      // This fixes the issue where NDJSON lines get concatenated without newlines, breaking JSON.parse
+      const tokenUsage = streamingTokenUsage;
       const pricingInfo = await calculateAgentPricing(mappedModel, tokenUsage);
 
-      // Log pricing information
+      // Log pricing information (similar to --tool claude breakdown)
       if (tokenUsage.stepCount > 0) {
         await log('\n💰 Token Usage Summary:');
-        await log(`   📊 ${pricingInfo.modelName || mappedModel}:`);
-        await log(`      Input tokens: ${tokenUsage.inputTokens.toLocaleString()}`);
-        await log(`      Output tokens: ${tokenUsage.outputTokens.toLocaleString()}`);
+        await log(`   📊 ${pricingInfo.modelName || mappedModel} (${tokenUsage.stepCount} steps):`);
+        await log(`      Input tokens:     ${tokenUsage.inputTokens.toLocaleString()}`);
+        await log(`      Output tokens:    ${tokenUsage.outputTokens.toLocaleString()}`);
         if (tokenUsage.reasoningTokens > 0) {
           await log(`      Reasoning tokens: ${tokenUsage.reasoningTokens.toLocaleString()}`);
         }
         if (tokenUsage.cacheReadTokens > 0 || tokenUsage.cacheWriteTokens > 0) {
-          await log(`      Cache read: ${tokenUsage.cacheReadTokens.toLocaleString()}`);
-          await log(`      Cache write: ${tokenUsage.cacheWriteTokens.toLocaleString()}`);
+          await log(`      Cache read:       ${tokenUsage.cacheReadTokens.toLocaleString()}`);
+          await log(`      Cache write:      ${tokenUsage.cacheWriteTokens.toLocaleString()}`);
         }
 
-        if (pricingInfo.totalCostUSD !== null) {
-          if (pricingInfo.isFreeModel) {
-            await log('      Cost: $0.00 (Free model)');
-          } else {
-            await log(`      Cost: $${pricingInfo.totalCostUSD.toFixed(6)}`);
+        if (pricingInfo.totalCostUSD !== null && pricingInfo.breakdown) {
+          // Show per-component cost breakdown (similar to --tool claude)
+          await log('      Cost breakdown:');
+          await log(`        Input:      $${pricingInfo.breakdown.input.toFixed(6)} (${(pricingInfo.pricing?.inputPerMillion || 0).toFixed(2)}/M tokens)`);
+          await log(`        Output:     $${pricingInfo.breakdown.output.toFixed(6)} (${(pricingInfo.pricing?.outputPerMillion || 0).toFixed(2)}/M tokens)`);
+          if (tokenUsage.cacheReadTokens > 0) {
+            await log(`        Cache read: $${pricingInfo.breakdown.cacheRead.toFixed(6)} (${(pricingInfo.pricing?.cacheReadPerMillion || 0).toFixed(2)}/M tokens)`);
+          }
+          if (tokenUsage.cacheWriteTokens > 0) {
+            await log(`        Cache write: $${pricingInfo.breakdown.cacheWrite.toFixed(6)} (${(pricingInfo.pricing?.cacheWritePerMillion || 0).toFixed(2)}/M tokens)`);
+          }
+          if (tokenUsage.reasoningTokens > 0 && pricingInfo.breakdown.reasoning > 0) {
+            await log(`        Reasoning:  $${pricingInfo.breakdown.reasoning.toFixed(6)} (${(pricingInfo.pricing?.reasoningPerMillion || 0).toFixed(2)}/M tokens)`);
+          }
+          // Show public pricing estimate
+          const pricingRef = pricingInfo.baseModelName && pricingInfo.originalProvider ? ` (based on ${pricingInfo.originalProvider} ${pricingInfo.baseModelName} prices)` : pricingInfo.originalProvider ? ` (based on ${pricingInfo.originalProvider} prices)` : '';
+          await log(`      Public pricing estimate: $${pricingInfo.totalCostUSD.toFixed(6)}${pricingRef}`);
+          // Show actual OpenCode Zen cost
+          if (pricingInfo.isOpencodeFreeModel) {
+            await log('      Calculated by OpenCode Zen: $0.00 (Free model)');
+          } else if (pricingInfo.opencodeCost !== undefined) {
+            await log(`      Calculated by OpenCode Zen: $${pricingInfo.opencodeCost.toFixed(6)}`);
           }
           await log(`      Provider: ${pricingInfo.provider || 'OpenCode Zen'}`);
         } else {

package/src/github.lib.mjs

@@ -30,6 +30,7 @@ import { uploadLogWithGhUploadLog } from './log-upload.lib.mjs';
  *   - opencodeCost: Actual billed cost from OpenCode Zen (for agent tool)
  *   - isOpencodeFreeModel: Whether OpenCode Zen provides this model for free
  *   - originalProvider: Original provider for pricing reference
+ *   - baseModelName: Base model name if pricing was derived from base model (Issue #1250)
  * @returns {string} Formatted cost info string for markdown (empty if no data available)
  */
 const buildCostInfoString = (totalCostUSD, anthropicTotalCostUSD, pricingInfo) => {
@@ -47,13 +48,20 @@ const buildCostInfoString = (totalCostUSD, anthropicTotalCostUSD, pricingInfo) =
   }
   // Issue #1250: Show public pricing estimate based on original provider prices
   if (hasPublic) {
-    // For models with zero pricing from original provider, show as free
-    if (pricingInfo?.isFreeModel && totalCostUSD === 0) {
+    // Issue #1250: For free models accessed via OpenCode Zen, show pricing based on base model
+    // Only show as completely free if the base model also has no pricing
+    if (pricingInfo?.isFreeModel && totalCostUSD === 0 && !pricingInfo?.baseModelName) {
       costInfo += '\n- Public pricing estimate: $0.00 (Free model)';
     } else {
       // Show actual public pricing estimate with original provider reference
-      const originalProviderRef = pricingInfo?.originalProvider ? ` (based on ${pricingInfo.originalProvider} prices)` : '';
-      costInfo += `\n- Public pricing estimate: $${totalCostUSD.toFixed(6)}${originalProviderRef}`;
+      // Issue #1250: Include base model reference when pricing comes from base model
+      let pricingRef = '';
+      if (pricingInfo?.baseModelName && pricingInfo?.originalProvider) {
+        pricingRef = ` (based on ${pricingInfo.originalProvider} ${pricingInfo.baseModelName} prices)`;
+      } else if (pricingInfo?.originalProvider) {
+        pricingRef = ` (based on ${pricingInfo.originalProvider} prices)`;
+      }
+      costInfo += `\n- Public pricing estimate: $${totalCostUSD.toFixed(6)}${pricingRef}`;
     }
   } else if (hasPricing) {
     costInfo += '\n- Public pricing estimate: unknown';

package/src/solve.repository.lib.mjs

@@ -884,56 +884,140 @@ Thank you!`;
   return { repoToClone, forkedRepo, upstreamRemote, prForkOwner: forkOwner };
 };
 
-// Clone repository and set up remotes
+// Classify git clone errors to determine if they are retryable
+export const classifyCloneError = errorOutput => {
+  const output = errorOutput.toLowerCase();
+
+  // Transient server errors (5xx) - typically retryable
+  if (output.includes('error: 500') || output.includes('internal server error') || output.includes('error: 502') || output.includes('error: 503') || output.includes('error: 504')) {
+    return { type: 'TRANSIENT', retryable: true, description: 'GitHub server error' };
+  }
+
+  // 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' };
+  }
+
+  // Authentication/permission errors - not retryable
+  if (output.includes('error: 401') || output.includes('error: 403') || output.includes('authentication failed') || output.includes('permission denied')) {
+    return { type: 'PERMISSION', retryable: false, description: 'Authentication or permission error' };
+  }
+
+  // Repository not found - not retryable
+  if (output.includes('error: 404') || output.includes('not found') || output.includes('repository not found')) {
+    return { type: 'NOT_FOUND', retryable: false, description: 'Repository not found' };
+  }
+
+  // Rate limiting - retryable with backoff
+  if (output.includes('rate limit') || output.includes('too many requests') || output.includes('api rate limit exceeded')) {
+    return { type: 'RATE_LIMIT', retryable: true, description: 'Rate limit exceeded' };
+  }
+
+  // Default to retryable for unknown errors
+  return { type: 'UNKNOWN', retryable: true, description: 'Unknown error' };
+};
+
+// Clone repository and set up remotes with retry mechanism
 export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) => {
-  // Clone the repository (or fork) using gh tool with authentication
-  await log(`\n${formatAligned('📥', 'Cloning repository:', repoToClone)}`);
+  const maxRetries = 3;
+  const baseDelay = 2000; // Start with 2 seconds
 
-  // Use 2>&1 to capture all output and filter "Cloning into" message
-  const cloneResult = await $`gh repo clone ${repoToClone} ${tempDir} 2>&1`;
+  await log(`\n${formatAligned('📥', 'Cloning repository:', repoToClone)}`);
 
-  // Verify clone was successful
-  if (cloneResult.code !== 0) {
-    const errorOutput = (cloneResult.stderr || cloneResult.stdout || 'Unknown error').toString().trim();
-    await log('');
-    await log(`${formatAligned('❌', 'CLONE FAILED', '')}`, { level: 'error' });
-    await log('');
-    await log('  🔍 What happened:');
-    await log(`     Failed to clone repository ${repoToClone}`);
-    await log('');
-    await log('  📦 Error details:');
-    for (const line of errorOutput.split('\n')) {
-      if (line.trim()) await log(`     ${line}`);
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    if (attempt > 1) {
+      await log(`${formatAligned('⏳', 'Clone attempt:', `${attempt}/${maxRetries} (with retry logic)`)}`);
     }
-    await log('');
-    await log('  💡 Common causes:');
-    await log("     • Repository doesn't exist or is private");
-    await log('     • No GitHub authentication');
-    await log('     • Network connectivity issues');
-    if (argv.fork) {
-      await log('     • Fork not ready yet (try again in a moment)');
+
+    // 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
+    if (cloneResult.code === 0) {
+      await log(`${formatAligned('✅', 'Cloned to:', tempDir)}`);
+
+      // Verify and fix remote configuration
+      const remoteCheckResult = await $({ cwd: tempDir })`git remote -v 2>&1`;
+      if (!remoteCheckResult.stdout || !remoteCheckResult.stdout.toString().includes('origin')) {
+        await log('   Setting up git remote...', { verbose: true });
+        // Add origin remote manually
+        await $({ cwd: tempDir })`git remote add origin https://github.com/${repoToClone}.git 2>&1`;
+      }
+      return; // Success - exit function
     }
-    await log('');
-    await log('  🔧 How to fix:');
-    await log('     1. Check authentication: gh auth status');
-    await log('     2. Login if needed: gh auth login');
-    await log(`     3. Verify access: gh repo view ${owner}/${repo}`);
-    if (argv.fork) {
-      await log(`     4. Check fork: gh repo view ${repoToClone}`);
+
+    // Clone failed - analyze error and determine if retry is appropriate
+    const errorOutput = (cloneResult.stderr || cloneResult.stdout || 'Unknown error').toString().trim();
+
+    const errorClassification = classifyCloneError(errorOutput);
+
+    if (!errorClassification.retryable || attempt === maxRetries) {
+      // Non-retryable error or max retries reached - fail with detailed error
+      await log('');
+      await log(`${formatAligned('❌', 'CLONE FAILED', '')}`, { level: 'error' });
+      await log('');
+      await log('  🔍 What happened:');
+      await log(`     Failed to clone repository ${repoToClone}`);
+
+      if (!errorClassification.retryable) {
+        await log(`     Error type: ${errorClassification.description} (not retryable)`);
+      } else {
+        await log(`     Error type: ${errorClassification.description} (max retries exceeded)`);
+      }
+      await log('');
+      await log('  📦 Error details:');
+      for (const line of errorOutput.split('\n')) {
+        if (line.trim()) await log(`     ${line}`);
+      }
+      await log('');
+      await log('  💡 Common causes:');
+      await log("     • Repository doesn't exist or is private");
+      await log('     • No GitHub authentication');
+      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');
+      }
+      if (argv.fork) {
+        await log('     • Fork not ready yet (try again in a moment)');
+      }
+      await log('');
+      await log('  🔧 How to fix:');
+      await log('     1. Check authentication: gh auth status');
+      await log('     2. Login if needed: gh auth login');
+      await log(`     3. Verify access: gh repo view ${owner}/${repo}`);
+      if (argv.fork) {
+        await log(`     4. Check fork: gh repo view ${repoToClone}`);
+      }
+      if (errorClassification.type === 'TRANSIENT') {
+        await log('     5. Wait a few minutes and retry (GitHub server issue)');
+        await log('     6. Check GitHub status: https://www.githubstatus.com');
+      }
+      if (errorClassification.type === 'RATE_LIMIT') {
+        await log('     5. Wait for rate limit to reset (check your quota)');
+        await log('     6. Use --token flag with different token if available');
+      }
+      await log('');
+      await safeExit(1, 'Repository setup failed');
     }
-    await log('');
-    await safeExit(1, 'Repository setup failed');
-  }
 
-  await log(`${formatAligned('✅', 'Cloned to:', tempDir)}`);
+    // Retryable error and we have attempts left
+    const delay = baseDelay * Math.pow(2, attempt - 1); // Exponential backoff
+    await log(`${formatAligned('⚠️', 'Clone failed:', errorClassification.description)}`);
+    await log(`${formatAligned('⏳', 'Retrying:', `Waiting ${delay / 1000}s before attempt ${attempt + 1}/${maxRetries}...`)}`);
+
+    if (errorClassification.type === 'RATE_LIMIT') {
+      await log('     💡 Tip: Rate limiting detected - using longer delay');
+    }
 
-  // Verify and fix remote configuration
-  const remoteCheckResult = await $({ cwd: tempDir })`git remote -v 2>&1`;
-  if (!remoteCheckResult.stdout || !remoteCheckResult.stdout.toString().includes('origin')) {
-    await log('   Setting up git remote...', { verbose: true });
-    // Add origin remote manually
-    await $({ cwd: tempDir })`git remote add origin https://github.com/${repoToClone}.git 2>&1`;
+    await new Promise(resolve => setTimeout(resolve, delay));
   }
+
+  // This should never be reached due to the loop logic above
+  await log(`${formatAligned('❌', 'UNEXPECTED ERROR:', 'Clone logic failed')}`);
+  await safeExit(1, 'Repository setup failed');
 };
 
 // Set up upstream remote and sync fork