fix(core): degrade build state persistence gracefully (#695)

Author: rafaelscosta

.aiox-core/core/execution/build-state-manager.js

@@ -308,6 +308,8 @@ class BuildStateManager {
     // Internal state
     this._state = null;
     this._logBuffer = [];
+    this._persistenceAvailable = true;
+    this._persistenceError = null;
   }
 
   // ─────────────────────────────────────────────────────────────────────────────────
@@ -367,14 +369,24 @@ class BuildStateManager {
    * @returns {Object|null} Loaded state or null if not exists
    */
   loadState() {
+    if (!this._persistenceAvailable) {
+      return this._state;
+    }
+
     if (!fs.existsSync(this.stateFilePath)) {
       return null;
     }
 
+    let content;
     try {
-      const content = fs.readFileSync(this.stateFilePath, 'utf-8');
-      const state = JSON.parse(content);
+      content = fs.readFileSync(this.stateFilePath, 'utf-8');
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+      return this._state;
+    }
 
+    try {
+      const state = JSON.parse(content);
       // Validate
       const validation = validateBuildState(state);
       if (!validation.valid) {
@@ -400,11 +412,6 @@ class BuildStateManager {
       throw new Error('No state to save. Call createState() or loadState() first.');
     }
 
-    // Ensure directory exists
-    if (!fs.existsSync(this.planDir)) {
-      fs.mkdirSync(this.planDir, { recursive: true });
-    }
-
     // Only update timestamp if explicitly requested (via saveCheckpoint)
     if (options.updateCheckpoint) {
       this._state.lastCheckpoint = new Date().toISOString();
@@ -416,11 +423,24 @@ class BuildStateManager {
       throw new Error(`Invalid state: ${validation.errors.join(', ')}`);
     }
 
-    // Write state file
-    fs.writeFileSync(this.stateFilePath, JSON.stringify(this._state, null, 2), 'utf-8');
+    if (!this._persistenceAvailable) {
+      return this._state;
+    }
 
-    // Flush log buffer
-    this._flushLogBuffer();
+    try {
+      // Ensure directory exists
+      if (!fs.existsSync(this.planDir)) {
+        fs.mkdirSync(this.planDir, { recursive: true });
+      }
+
+      // Write state file
+      fs.writeFileSync(this.stateFilePath, JSON.stringify(this._state, null, 2), 'utf-8');
+
+      // Flush log buffer
+      this._flushLogBuffer();
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+    }
 
     return this._state;
   }
@@ -464,11 +484,6 @@ class BuildStateManager {
       throw new Error('No state loaded');
     }
 
-    // Ensure checkpoint directory exists
-    if (!fs.existsSync(this.checkpointDir)) {
-      fs.mkdirSync(this.checkpointDir, { recursive: true });
-    }
-
     const checkpointId = this._generateCheckpointId();
     const now = new Date().toISOString();
 
@@ -499,8 +514,19 @@ class BuildStateManager {
     this._updateMetrics(checkpoint);
 
     // Save checkpoint file
-    const checkpointPath = path.join(this.checkpointDir, `${checkpointId}.json`);
-    fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    if (this._persistenceAvailable) {
+      try {
+        // Ensure checkpoint directory exists
+        if (!fs.existsSync(this.checkpointDir)) {
+          fs.mkdirSync(this.checkpointDir, { recursive: true });
+        }
+
+        const checkpointPath = path.join(this.checkpointDir, `${checkpointId}.json`);
+        fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+      } catch (error) {
+        this._markPersistenceUnavailable(error);
+      }
+    }
 
     // Save main state with checkpoint timestamp update
     this.saveState({ updateCheckpoint: true });
@@ -1041,6 +1067,8 @@ class BuildStateManager {
    * @private
    */
   _logAttempt(subtaskId, action, details = {}) {
+    if (!this._persistenceAvailable) return;
+
     const entry = {
       timestamp: new Date().toISOString(),
       storyId: this.storyId,
@@ -1066,15 +1094,20 @@ class BuildStateManager {
    */
   _flushLogBuffer() {
     if (this._logBuffer.length === 0) return;
+    if (!this._persistenceAvailable) return;
 
-    // Ensure directory exists
-    if (!fs.existsSync(this.planDir)) {
-      fs.mkdirSync(this.planDir, { recursive: true });
-    }
+    try {
+      // Ensure directory exists
+      if (!fs.existsSync(this.planDir)) {
+        fs.mkdirSync(this.planDir, { recursive: true });
+      }
 
-    // Append to log file
-    fs.appendFileSync(this.logFilePath, this._logBuffer.join(''), 'utf-8');
-    this._logBuffer = [];
+      // Append to log file
+      fs.appendFileSync(this.logFilePath, this._logBuffer.join(''), 'utf-8');
+      this._logBuffer = [];
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+    }
   }
 
   /**
@@ -1084,11 +1117,22 @@ class BuildStateManager {
    * @returns {string[]} Log lines
    */
   getAttemptLog(options = {}) {
+    if (!this._persistenceAvailable) {
+      return [];
+    }
+
     if (!fs.existsSync(this.logFilePath)) {
       return [];
     }
 
-    const content = fs.readFileSync(this.logFilePath, 'utf-8');
+    let content;
+    try {
+      content = fs.readFileSync(this.logFilePath, 'utf-8');
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+      return [];
+    }
+
     let lines = content.split('\n').filter((l) => l.trim());
 
     // Filter by subtask if specified
@@ -1266,6 +1310,39 @@ class BuildStateManager {
     // Silent by default - can be overridden
   }
 
+  /**
+   * Check if file-backed persistence is still available.
+   *
+   * @returns {boolean} True when state/checkpoint/log writes are available.
+   */
+  isPersistenceAvailable() {
+    return this._persistenceAvailable;
+  }
+
+  /**
+   * Get the first persistence error that disabled file-backed writes.
+   *
+   * @returns {Error|null} Persistence error or null when persistence is available.
+   */
+  getPersistenceError() {
+    return this._persistenceError;
+  }
+
+  /**
+   * Disable file-backed persistence after an I/O failure.
+   *
+   * @param {Error} error - Underlying persistence error.
+   * @private
+   */
+  _markPersistenceUnavailable(error) {
+    if (!this._persistenceAvailable) return;
+
+    this._persistenceAvailable = false;
+    this._persistenceError = error instanceof Error ? error : new Error(String(error));
+    this._logBuffer = [];
+    this._log(`Persistence unavailable: ${this._persistenceError.message}`);
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────────
   //                              CLI FORMATTING
   // ─────────────────────────────────────────────────────────────────────────────────

.aiox-core/install-manifest.yaml

@@ -8,7 +8,7 @@
 # - File types for categorization
 #
 version: 5.1.15
-generated_at: "2026-05-08T04:27:49.896Z"
+generated_at: "2026-05-08T04:49:28.006Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1111
 files:
@@ -409,9 +409,9 @@ files:
     type: core
     size: 33071
   - path: core/execution/build-state-manager.js
-    hash: sha256:a6a3ed85ff040fd8338ec31eaf8729050e58216c873f5e0e80f2fbda89234b73
+    hash: sha256:7a6127abb4cd23b83563e55065b6a4771764972d40d87ba08117ee8c0c48980e
     type: core
-    size: 52112
+    size: 54015
   - path: core/execution/context-injector.js
     hash: sha256:7654f6e6c3d555f3963369e71edf84b15c0fdec53bd161800b71782f78275244
     type: core

tests/core/build-state-manager.test.js

@@ -41,6 +41,8 @@ describe('BuildStateManager', () => {
   });
 
   afterEach(() => {
+    jest.restoreAllMocks();
+
     // Cleanup temp directory
     if (testDir && fs.existsSync(testDir)) {
       fs.rmSync(testDir, { recursive: true, force: true });
@@ -157,6 +159,20 @@ describe('BuildStateManager', () => {
       expect(state2.metrics.totalSubtasks).toBe(7); // Should be original value
     });
 
+    test('should keep state in memory when persistence fails during save', () => {
+      manager.createState({ totalSubtasks: 3 });
+      jest.spyOn(fs, 'writeFileSync').mockImplementation(() => {
+        throw new Error('EACCES: permission denied');
+      });
+
+      expect(() => manager.saveState()).not.toThrow();
+
+      expect(manager.isPersistenceAvailable()).toBe(false);
+      expect(manager.getPersistenceError().message).toContain('EACCES');
+      expect(manager.getState().metrics.totalSubtasks).toBe(3);
+      expect(fs.existsSync(path.join(testDir, 'plan', 'build-state.json'))).toBe(false);
+    });
+
     test('should throw when storyId not provided', () => {
       expect(() => new BuildStateManager(null)).toThrow('storyId is required');
     });
@@ -230,6 +246,25 @@ describe('BuildStateManager', () => {
       expect(state.completedSubtasks).toEqual(['1.1']);
       expect(state.checkpoints).toHaveLength(2); // Still records checkpoint
     });
+
+    test('should keep checkpoint state in memory when checkpoint persistence fails', () => {
+      const originalWriteFileSync = fs.writeFileSync;
+      jest.spyOn(fs, 'writeFileSync').mockImplementation((filePath, ...args) => {
+        if (String(filePath).includes('checkpoints')) {
+          throw new Error('ENOSPC: no space left on device');
+        }
+        return originalWriteFileSync.call(fs, filePath, ...args);
+      });
+
+      expect(() => manager.saveCheckpoint('1.persistence')).not.toThrow();
+
+      const state = manager.getState();
+      expect(manager.isPersistenceAvailable()).toBe(false);
+      expect(manager.getPersistenceError().message).toContain('ENOSPC');
+      expect(state.checkpoints).toHaveLength(1);
+      expect(state.completedSubtasks).toContain('1.persistence');
+      expect(state.metrics.completedSubtasks).toBe(1);
+    });
   });
 
   // ─────────────────────────────────────────────────────────────────────────────────