fix: Add serialized installation with retry logic to prevent cache race conditions

Fixes #72 - The root cause was race conditions when multiple provider packages
are installed in parallel, causing Bun cache corruption ("FileNotFound: failed
copying files from cache").

Changes:
- Add write lock to serialize package installations
- Add retry logic (up to 3 attempts) for cache-related errors
- Improve error detection for ENOENT, EACCES, EBUSY errors
- Add 500ms delay between retry attempts
- Remove fallback behavior - opencode/grok-code remains the default

This ensures the first run after installation works reliably.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: konard

.changeset/graceful-provider-fallback.md

@@ -2,19 +2,24 @@
 '@link-assistant/agent': patch
 ---
 
-fix: Add graceful fallback when provider initialization fails
+fix: Add retry logic and serialized installation for reliable provider initialization
 
-Fixes issue #72 where version 0.3.0 appeared "completely broken" due to Bun package cache corruption preventing opencode provider initialization. The agent now gracefully falls back to alternative providers when initialization fails, improving resilience and user experience.
+Fixes issue #72 where version 0.3.0 appeared "completely broken" due to race conditions in parallel package installations causing Bun cache corruption.
+
+Root Cause:
+
+- When multiple provider packages (e.g., @ai-sdk/openai-compatible, @ai-sdk/openai) are installed concurrently, they can cause race conditions in Bun's package cache
+- This leads to "FileNotFound: failed copying files from cache" errors on first run after update
 
 Changes:
 
-- Test provider initialization before selecting it as default
-- Fall back to alternative providers if opencode provider fails to initialize
-- Add helpful error messages when Bun cache corruption is detected
-- Log warnings with detailed error information for troubleshooting
+- Add write lock to serialize package installations (prevents concurrent bun add commands)
+- Add retry logic with up to 3 attempts for cache-related errors
+- Improve error detection to catch ENOENT, EACCES, EBUSY errors
+- Add delay between retries to allow filesystem operations to complete
 
 Impact:
 
-- Agent no longer crashes when provider initialization fails
-- Better error messages guide users to recovery steps
-- Improved stability in production environments
+- opencode/grok-code remains the default provider and works reliably
+- Agent handles transient cache issues gracefully with automatic retries
+- Better stability during first run after installation/update

docs/case-studies/issue-72/README.md

@@ -199,66 +199,57 @@ FileNotFound: failed copying files from cache to destination for package zod
 
 ## Proposed Solutions
 
-### Solution 1: Add Graceful Fallback (Recommended)
+### Solution 1: Serialized Installation with Retry Logic (Implemented)
 
 **Priority:** High
-**Effort:** Low
-**Impact:** Fixes the issue for all users
+**Effort:** Medium
+**Impact:** Fixes the issue for all users while keeping opencode as default
 
-Modify provider initialization to:
+The root cause was identified as race conditions when multiple packages are installed in parallel. The fix:
 
-1. Catch provider init failures
-2. Log warning instead of crashing
-3. Try next available provider
-4. Only crash if NO providers can be initialized
+1. Serialize package installations using a write lock
+2. Add retry logic for cache-related errors
+3. Improve error detection for various cache corruption symptoms
 
-**Implementation location:** `src/provider/provider.ts:781-790`
+**Implementation location:** `src/bun/index.ts:68-220`
 
 **Benefits:**
 
-- Resilient to transient installation failures
-- Better user experience
-- Maintains backward compatibility
-- Users can still use the agent with other providers
+- opencode/grok-code remains the default provider
+- Resilient to transient cache issues
+- Automatic retry handles temporary failures
+- No fallback to other providers needed
 
 **Code change:**
 
 ```typescript
-// In defaultModel() function
-try {
-  const opencodeProvider = providers.find((p) => p.info.id === 'opencode');
-  if (opencodeProvider) {
-    const [model] = sort(Object.values(opencodeProvider.info.models));
-    if (model) {
-      try {
-        // Verify provider can be initialized
-        await getSDK(opencodeProvider.info, model);
-        return {
-          providerID: opencodeProvider.info.id,
-          modelID: model.id,
-        };
-      } catch (initError) {
-        log.warn(
-          'Failed to initialize preferred opencode provider, falling back',
-          {
-            error:
-              initError instanceof Error
-                ? initError.message
-                : String(initError),
-          }
-        );
-      }
+// Use a write lock to serialize all package installations
+using _ = await Lock.write(INSTALL_LOCK_KEY);
+
+// Retry logic for cache-related errors
+let lastError: Error | undefined;
+for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+  try {
+    await BunProc.run(args, { cwd: Global.Path.cache });
+    log.info('package installed successfully', { pkg, version, attempt });
+    return mod;
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    const isCacheError = isCacheRelatedError(errorMsg);
+
+    if (isCacheError && attempt < MAX_RETRIES) {
+      log.info('retrying installation after cache-related error', {
+        pkg,
+        version,
+        attempt,
+        nextAttempt: attempt + 1,
+      });
+      await delay(RETRY_DELAY_MS);
+      continue;
     }
+    throw new InstallFailedError({ pkg, version, details: errorMsg });
   }
-} catch (e) {
-  log.warn('Error checking opencode provider, continuing with fallback');
 }
-
-// Fall back to any available provider
-const provider = providers.find(
-  (p) => !cfg.provider || Object.keys(cfg.provider).includes(p.info.id)
-);
-// ... rest of existing fallback logic
 ```
 
 ### Solution 2: Provide Cache Clear Instructions
@@ -348,8 +339,12 @@ bun install -g @link-assistant/agent@0.2.1
 
 ## Conclusion
 
-Version 0.3.0 is NOT fundamentally broken in code, but **fails due to Bun runtime cache corruption** when trying to initialize the new default opencode provider. The issue is **environmental** rather than a code defect.
+Version 0.3.0 is NOT fundamentally broken in code, but **fails due to race conditions in parallel package installations** causing Bun cache corruption when trying to initialize the new default opencode provider. The issue is **environmental** rather than a code defect.
+
+**Implemented Fix:**
 
-**Implemented Fix:** Added graceful fallback in `Provider.defaultModel()` to try opencode provider first, and if it fails, skip it and fall back to other available providers. This makes the agent resilient to provider initialization failures.
+1. **Serialized package installations** - Added a write lock to ensure only one `bun add` command runs at a time, preventing race conditions
+2. **Retry logic for cache errors** - Added automatic retry (up to 3 attempts) for cache-related errors with a 500ms delay between attempts
+3. **Improved error detection** - Enhanced detection of cache-related errors (FileNotFound, ENOENT, EACCES, EBUSY)
 
-**Status:** Fix implemented and tested. Issue should be resolved for users with working alternative providers.
+**Status:** Fix implemented and tested. The opencode/grok-code provider remains the default and will work reliably even with transient cache issues.

src/bun/index.ts

@@ -5,10 +5,14 @@ import path from 'path';
 import { NamedError } from '../util/error';
 import { readableStreamToText } from 'bun';
 import { Flag } from '../flag/flag';
+import { Lock } from '../util/lock';
 
 export namespace BunProc {
   const log = Log.create({ service: 'bun' });
 
+  // Lock key for serializing package installations to prevent race conditions
+  const INSTALL_LOCK_KEY = 'bun-install';
+
   export async function run(
     cmd: string[],
     options?: Bun.SpawnOptions.OptionsObject<any, any, any>
@@ -65,8 +69,38 @@ export namespace BunProc {
     })
   );
 
+  // Maximum number of retry attempts for cache-related errors
+  const MAX_RETRIES = 3;
+  // Delay between retries in milliseconds
+  const RETRY_DELAY_MS = 500;
+
+  /**
+   * Check if an error is related to Bun cache issues
+   */
+  function isCacheRelatedError(errorMsg: string): boolean {
+    return (
+      errorMsg.includes('failed copying files from cache') ||
+      errorMsg.includes('FileNotFound') ||
+      errorMsg.includes('ENOENT') ||
+      errorMsg.includes('EACCES') ||
+      errorMsg.includes('EBUSY')
+    );
+  }
+
+  /**
+   * Wait for a specified duration
+   */
+  function delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
   export async function install(pkg: string, version = 'latest') {
     const mod = path.join(Global.Path.cache, 'node_modules', pkg);
+
+    // Use a write lock to serialize all package installations
+    // This prevents race conditions when multiple packages are installed concurrently
+    using _ = await Lock.write(INSTALL_LOCK_KEY);
+
     const pkgjson = Bun.file(path.join(Global.Path.cache, 'package.json'));
     const parsed = await pkgjson.json().catch(async () => {
       const result = { dependencies: {} };
@@ -108,39 +142,78 @@ export namespace BunProc {
       version,
     });
 
-    await BunProc.run(args, {
-      cwd: Global.Path.cache,
-    }).catch((e) => {
-      const errorMsg = e instanceof Error ? e.message : String(e);
-      const isCacheError =
-        errorMsg.includes('failed copying files from cache') ||
-        errorMsg.includes('FileNotFound');
+    // Retry logic for cache-related errors
+    let lastError: Error | undefined;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        await BunProc.run(args, {
+          cwd: Global.Path.cache,
+        });
 
-      log.error('package installation failed', {
-        pkg,
-        version,
-        error: errorMsg,
-        stack: e instanceof Error ? e.stack : undefined,
-        possibleCacheCorruption: isCacheError,
-      });
-
-      // Provide helpful recovery instructions for cache-related errors
-      if (isCacheError) {
-        log.error(
-          'Bun package cache may be corrupted. Try clearing the cache with: bun pm cache rm'
+        log.info('package installed successfully', { pkg, version, attempt });
+        parsed.dependencies[pkg] = version;
+        await Bun.write(pkgjson.name!, JSON.stringify(parsed, null, 2));
+        return mod;
+      } catch (e) {
+        const errorMsg = e instanceof Error ? e.message : String(e);
+        const isCacheError = isCacheRelatedError(errorMsg);
+
+        log.warn('package installation attempt failed', {
+          pkg,
+          version,
+          attempt,
+          maxRetries: MAX_RETRIES,
+          error: errorMsg,
+          isCacheError,
+        });
+
+        if (isCacheError && attempt < MAX_RETRIES) {
+          log.info('retrying installation after cache-related error', {
+            pkg,
+            version,
+            attempt,
+            nextAttempt: attempt + 1,
+            delayMs: RETRY_DELAY_MS,
+          });
+          await delay(RETRY_DELAY_MS);
+          lastError = e instanceof Error ? e : new Error(errorMsg);
+          continue;
+        }
+
+        // Non-cache error or final attempt - log and throw
+        log.error('package installation failed', {
+          pkg,
+          version,
+          error: errorMsg,
+          stack: e instanceof Error ? e.stack : undefined,
+          possibleCacheCorruption: isCacheError,
+          attempts: attempt,
+        });
+
+        // Provide helpful recovery instructions for cache-related errors
+        if (isCacheError) {
+          log.error(
+            'Bun package cache may be corrupted. Try clearing the cache with: bun pm cache rm'
+          );
+        }
+
+        throw new InstallFailedError(
+          { pkg, version, details: errorMsg },
+          {
+            cause: e,
+          }
         );
       }
+    }
 
-      throw new InstallFailedError(
-        { pkg, version, details: errorMsg },
-        {
-          cause: e,
-        }
-      );
-    });
-    log.info('package installed successfully', { pkg, version });
-    parsed.dependencies[pkg] = version;
-    await Bun.write(pkgjson.name!, JSON.stringify(parsed, null, 2));
-    return mod;
+    // This should not be reached, but handle it just in case
+    throw new InstallFailedError(
+      {
+        pkg,
+        version,
+        details: lastError?.message ?? 'Installation failed after all retries',
+      },
+      { cause: lastError }
+    );
   }
 }

src/provider/provider.ts

@@ -899,37 +899,26 @@ export namespace Provider {
     const cfg = await Config.get();
     if (cfg.model) return parseModel(cfg.model);
 
-    // Prefer opencode provider if available, but verify it can be initialized
+    // Prefer opencode provider if available
     const providers = await list().then((val) => Object.values(val));
     const opencodeProvider = providers.find((p) => p.info.id === 'opencode');
     if (opencodeProvider) {
       const [model] = sort(Object.values(opencodeProvider.info.models));
       if (model) {
-        try {
-          // Try to initialize the opencode provider to ensure it works
-          await getSDK(opencodeProvider.info, model);
-          log.info('using preferred opencode provider as default');
-          return {
-            providerID: opencodeProvider.info.id,
-            modelID: model.id,
-          };
-        } catch (error) {
-          // If opencode provider fails to initialize, log warning and fall back
-          log.warn(
-            'failed to initialize preferred opencode provider, falling back to alternative',
-            {
-              error: error instanceof Error ? error.message : String(error),
-              provider: opencodeProvider.info.id,
-              model: model.id,
-            }
-          );
-        }
+        log.info('using opencode provider as default', {
+          provider: opencodeProvider.info.id,
+          model: model.id,
+        });
+        return {
+          providerID: opencodeProvider.info.id,
+          modelID: model.id,
+        };
       }
     }
 
-    // Fall back to any available provider (skip opencode since it failed)
+    // Fall back to any available provider if opencode is not available
     const provider = providers.find(
-      (p) => p.info.id !== 'opencode' && (!cfg.provider || Object.keys(cfg.provider).includes(p.info.id))
+      (p) => !cfg.provider || Object.keys(cfg.provider).includes(p.info.id)
     );
     if (!provider) throw new Error('no providers found');
     const [model] = sort(Object.values(provider.info.models));