@defai.digital/automatosx 5.0.9 → 5.0.10

package/CHANGELOG.md

@@ -5,6 +5,102 @@ All notable changes to AutomatosX will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.10] - 2025-10-10
+
+### 🎯 Smart Cleanup & UX Improvements
+
+#### Added
+
+- **Smart Memory Cleanup (Phase 2)**: Intelligent threshold-based cleanup replacing unpredictable random triggers
+  - **Threshold Triggering**: Cleanup triggers at 90% capacity (default), cleans to 70% target
+  - **Three Cleanup Strategies**:
+    - `oldest`: Time-based cleanup (FIFO, default)
+    - `least_accessed`: Access-based cleanup (LRU/LFU, preserves hot data)
+    - `hybrid`: Balanced strategy (considers both age and access)
+  - **Configurable Thresholds**:
+    - `triggerThreshold`: When to start cleanup (default 0.9 = 90%)
+    - `targetThreshold`: Cleanup target (default 0.7 = 70%)
+    - `minCleanupCount`: Minimum entries to remove (default 10)
+    - `maxCleanupCount`: Maximum entries to remove (default 1000)
+  - **Smart Validation**: Comprehensive configuration validation with clear error messages
+  - **Backward Compatible**: Old `autoCleanup` and `cleanupDays` configs automatically mapped
+
+#### Fixed
+
+- **Memory Cleanup Bug Fixes (Phase 2.1)**: Ultra-deep review found and fixed 5 bugs
+  1. **Negative Cleanup Handling**: Fixed cleanup when entry count below target (prevents accidental deletion)
+  2. **Return Value Consistency**: All cleanup methods now return actual deleted count (not requested count)
+  3. **Async Operations**: Fixed missing `await` in fallback scenarios (eliminates race conditions)
+  4. **Configuration Validation**: Added validation for `maxCleanupCount` and `retentionDays` (prevents invalid configs)
+  5. **Type Design**: Unified all cleanup methods to `async Promise<number>` (consistent interface)
+
+- **Agent Not Found UX**: Restored friendly agent suggestions in `ax run` command
+  - Shows "Did you mean..." list with similar agents (Levenshtein distance ≤ 3)
+  - Displays displayName, actual name, and role for each suggestion
+  - Falls back to "Run 'ax agent list'" if no close matches
+  - Prevents regression from early agent name resolution
+
+#### Changed
+
+- **Memory Cleanup Behavior**:
+  - **Before**: Random 10% chance on each add → unpredictable timing
+  - **After**: Deterministic threshold-based → 100% predictable when cleanup occurs
+  - **Result**: Users can trust cleanup timing and configure to their needs
+
+- **Memory Manager Methods** (Phase 2.1 refactoring):
+  - `cleanupOldest()`: Now returns `Promise<number>` (actual deleted count)
+  - `cleanupLeastAccessed()`: Now async `Promise<number>` (supports proper fallback)
+  - `cleanupHybrid()`: Now async `Promise<number>` (consistent interface)
+  - `calculateCleanupCount()`: Added negative value check (safety improvement)
+  - `validateCleanupConfig()`: Enhanced with additional validations
+
+#### Performance
+
+- **Cleanup Efficiency**:
+  - 100% predictable cleanup timing (vs random)
+  - Configurable cleanup bounds prevent excessive operations
+  - Smart strategies preserve hot data when needed
+  - All cleanup methods properly await async operations
+
+### Documentation
+
+- Created comprehensive Phase 2 implementation plan (16 pages)
+- Created detailed bug analysis report (Phase 2.1, 57 pages)
+- Created bug fixes completion report
+- All documentation in `tmp/` folder (development artifacts)
+
+### Tests
+
+- All 1,207 tests passing (5 skipped)
+- Memory manager tests: 25/25 passing
+- Phase 1 tests: 13/13 passing
+- Integration tests: 106/106 passing
+- Zero regressions, fully backward compatible
+
+### Migration Notes
+
+**No migration required** - v5.0.10 is 100% backward compatible with v5.0.9 and earlier versions.
+
+**Optional**: To use new smart cleanup features, add to your config:
+```json
+{
+  "memory": {
+    "cleanup": {
+      "enabled": true,
+      "strategy": "hybrid",
+      "triggerThreshold": 0.9,
+      "targetThreshold": 0.7,
+      "minCleanupCount": 10,
+      "maxCleanupCount": 1000
+    }
+  }
+}
+```
+
+Old configs using `autoCleanup` and `cleanupDays` continue to work unchanged.
+
+---
+
 ## [5.0.9] - 2025-10-10
 
 ### Added

package/README.md

@@ -7,9 +7,9 @@
 [![npm version](https://img.shields.io/npm/v/@defai.digital/automatosx.svg)](https://www.npmjs.com/package/@defai.digital/automatosx)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-1,149%20passing-brightgreen.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-1,207%20passing-brightgreen.svg)](#)
 
-**Status**: ✅ Production Ready · v5.0.8 · October 2025
+**Status**: ✅ Production Ready · v5.0.10 · October 2025
 
 ---
 
@@ -66,13 +66,19 @@ Day 3: /ax run steve "security audit" → Steve has full context from Day 1-2
 
 ## 🚀 What's New
 
-**v5.0.8** (October 2025): Critical Fixes - Timeout & Memory
-- **CRITICAL FIX**: Multi-stage agents now respect `--timeout` flag
-- **CRITICAL FIX**: Memory system enforces `maxEntries` and `autoCleanup` limits
-- **Timeout support**: AbortSignal properly passed to all stage executors
-- **Memory limits**: Automatic cleanup prevents database growth issues
-- **100% backward compatible**: Drop-in replacement for v5.0.7
-
+**v5.0.10** (October 2025): Smart Cleanup & UX Improvements
+- **NEW**: Smart memory cleanup with threshold-based triggering (replaces random cleanup)
+- **NEW**: Three cleanup strategies: `oldest`, `least_accessed`, `hybrid`
+- **FIX**: Memory cleanup bugs (5 bugs fixed in Phase 2.1)
+  - Fixed negative cleanup count handling
+  - Fixed async operation await issues
+  - Unified cleanup method signatures
+  - Enhanced configuration validation
+- **FIX**: Restored agent suggestion list in `ax run` command
+- **IMPROVED**: Predictable cleanup behavior (90% trigger → 70% target)
+- **100% backward compatible**: All existing configurations work unchanged
+
+**v5.0.8**: Critical Fixes - Timeout & Memory
 **v5.0.6**: File Operation Tools Enabled
 **v5.0.5**: Provider Parameters & Version Management
 **v5.0.4**: Memory saving now works automatically

package/dist/index.js

@@ -3148,6 +3148,12 @@ var MemoryManager = class _MemoryManager {
   initialized = false;
   useFTS = true;
   // Use FTS5 by default
+  // Phase 1: Performance optimization
+  entryCount = 0;
+  // Internal counter to avoid repeated COUNT(*)
+  statements = {};
+  // Phase 2: Smart cleanup configuration
+  cleanupConfig;
   constructor(config) {
     this.config = {
       dbPath: config.dbPath,
@@ -3158,6 +3164,19 @@ var MemoryManager = class _MemoryManager {
       embeddingProvider: config.embeddingProvider
     };
     this.embeddingProvider = config.embeddingProvider;
+    const cleanupCfg = config.cleanup || {};
+    const enabled = cleanupCfg.enabled ?? config.autoCleanup ?? true;
+    const retentionDays = cleanupCfg.retentionDays ?? config.cleanupDays ?? 30;
+    this.cleanupConfig = {
+      enabled,
+      strategy: cleanupCfg.strategy ?? "oldest",
+      triggerThreshold: cleanupCfg.triggerThreshold ?? 0.9,
+      targetThreshold: cleanupCfg.targetThreshold ?? 0.7,
+      minCleanupCount: cleanupCfg.minCleanupCount ?? 10,
+      maxCleanupCount: cleanupCfg.maxCleanupCount ?? 1e3,
+      retentionDays
+    };
+    this.validateCleanupConfig();
     const dir = dirname4(this.config.dbPath);
     if (!existsSync3(dir)) {
       mkdirSync(dir, { recursive: true });
@@ -3223,11 +3242,37 @@ var MemoryManager = class _MemoryManager {
           WHERE rowid = old.id;
         END;
       `);
+      this.statements.countAll = this.db.prepare("SELECT COUNT(*) as count FROM memory_entries");
+      this.statements.insert = this.db.prepare(`
+        INSERT INTO memory_entries (content, metadata, created_at, last_accessed_at, access_count)
+        VALUES (?, ?, ?, ?, 0)
+      `);
+      this.statements.deleteById = this.db.prepare("DELETE FROM memory_entries WHERE id = ?");
+      this.statements.deleteOldest = this.db.prepare(`
+        DELETE FROM memory_entries
+        WHERE id IN (
+          SELECT id FROM memory_entries
+          ORDER BY created_at ASC
+          LIMIT ?
+        )
+      `);
+      this.statements.deleteBeforeCutoff = this.db.prepare(`
+        DELETE FROM memory_entries
+        WHERE created_at < ?
+      `);
+      this.statements.updateAccessCount = this.db.prepare(`
+        UPDATE memory_entries
+        SET access_count = access_count + 1, last_accessed_at = ?
+        WHERE id = ?
+      `);
+      const countResult = this.statements.countAll.get();
+      this.entryCount = countResult.count;
       this.initialized = true;
       logger.info("MemoryManager initialized successfully", {
         dbPath: this.config.dbPath,
         searchMethod: "FTS5",
-        hasEmbeddingProvider: !!this.embeddingProvider
+        hasEmbeddingProvider: !!this.embeddingProvider,
+        entryCount: this.entryCount
       });
     } catch (error) {
       logger.error("Failed to initialize MemoryManager", { error: error.message });
@@ -3241,47 +3286,60 @@ var MemoryManager = class _MemoryManager {
    * Add a new memory entry
    *
    * v4.11.0: Embedding is now optional (only needed for Plus version)
+   * v5.0.9: Phase 1 - Transaction atomicity with prepared statements
    */
   async add(content, embedding, metadata) {
     if (!this.initialized) {
       throw new MemoryError("Memory manager not initialized", "DATABASE_ERROR");
     }
-    const currentCount = this.getCount();
-    if (currentCount >= this.config.maxEntries) {
-      const entriesToRemove = Math.min(100, Math.floor(this.config.maxEntries * 0.1));
-      await this.cleanupOldest(entriesToRemove);
-      logger.warn("Memory limit approaching, auto-cleanup triggered", {
-        currentCount,
-        maxEntries: this.config.maxEntries,
-        removed: entriesToRemove
-      });
-      const newCount = this.getCount();
-      if (newCount >= this.config.maxEntries) {
-        throw new MemoryError(
-          `Memory limit reached (${this.config.maxEntries} entries). Run 'ax memory clear' or increase maxEntries in config.`,
-          "MEMORY_LIMIT"
-        );
-      }
-    }
-    if (this.config.autoCleanup && Math.random() < 0.1) {
-      this.cleanup().catch((error) => {
-        logger.debug("Background cleanup failed", {
+    if (this.shouldTriggerCleanup()) {
+      try {
+        const removed = await this.executeSmartCleanup();
+        logger.info("Smart cleanup triggered", {
+          removed,
+          currentCount: this.entryCount,
+          usage: (this.entryCount / this.config.maxEntries * 100).toFixed(1) + "%",
+          threshold: (this.cleanupConfig.triggerThreshold * 100).toFixed(0) + "%",
+          strategy: this.cleanupConfig.strategy
+        });
+      } catch (error) {
+        logger.warn("Smart cleanup failed", {
           error: error.message
         });
-      });
+      }
     }
     try {
       const now = Date.now();
-      const result = this.db.prepare(`
-        INSERT INTO memory_entries (content, metadata, created_at, access_count)
-        VALUES (?, ?, ?, 0)
-      `).run(content, JSON.stringify(metadata), now);
-      const id = Number(result.lastInsertRowid);
-      logger.debug("Memory entry added", {
-        id,
-        contentLength: content.length,
-        searchMethod: "FTS5"
+      const metadataStr = JSON.stringify(metadata);
+      const insertTxn = this.db.transaction(() => {
+        let deletedCount2 = 0;
+        if (this.entryCount >= this.config.maxEntries) {
+          const entriesToRemove = Math.min(100, Math.floor(this.config.maxEntries * 0.1));
+          const deleteInfo = this.statements.deleteOldest.run(entriesToRemove);
+          deletedCount2 = deleteInfo.changes;
+          logger.warn("Memory limit approaching, auto-cleanup triggered", {
+            currentCount: this.entryCount,
+            maxEntries: this.config.maxEntries,
+            removed: deletedCount2
+          });
+          if (this.entryCount - deletedCount2 >= this.config.maxEntries) {
+            throw new MemoryError(
+              `Memory limit reached (${this.config.maxEntries} entries). Run 'ax memory clear' or increase maxEntries in config.`,
+              "MEMORY_LIMIT"
+            );
+          }
+        }
+        const insertResult = this.statements.insert.run(content, metadataStr, now, now);
+        logger.debug("Memory entry added", {
+          id: insertResult.lastInsertRowid,
+          contentLength: content.length,
+          searchMethod: "FTS5",
+          deletedCount: deletedCount2
+        });
+        return { id: Number(insertResult.lastInsertRowid), deletedCount: deletedCount2 };
       });
+      const { id, deletedCount } = insertTxn();
+      this.entryCount = this.entryCount - deletedCount + 1;
       return {
         id,
         content,
@@ -3379,13 +3437,14 @@ var MemoryManager = class _MemoryManager {
       const finalParams = [ftsQuery, ...params, limit];
       const results = this.db.prepare(sql).all(...finalParams);
       if (this.config.trackAccess && results.length > 0) {
+        const now = Date.now();
         const ids = results.map((r) => r.id);
         const placeholders = ids.map(() => "?").join(",");
         this.db.prepare(`
           UPDATE memory_entries
           SET last_accessed_at = ?, access_count = access_count + 1
           WHERE id IN (${placeholders})
-        `).run(Date.now(), ...ids);
+        `).run(now, ...ids);
       }
       return results.map((row) => {
         const similarity = Math.max(0, Math.min(1, 1 + row.relevance / 10));
@@ -3483,8 +3542,11 @@ var MemoryManager = class _MemoryManager {
       if (!existing) {
         throw new MemoryError(`Memory entry not found: ${id}`, "ENTRY_NOT_FOUND");
       }
-      this.db.prepare("DELETE FROM memory_entries WHERE id = ?").run(id);
-      logger.debug("Memory entry deleted", { id });
+      const deleteInfo = this.statements.deleteById.run(id);
+      if (deleteInfo.changes > 0) {
+        this.entryCount -= deleteInfo.changes;
+      }
+      logger.debug("Memory entry deleted", { id, newCount: this.entryCount });
     } catch (error) {
       if (error instanceof MemoryError) throw error;
       throw new MemoryError(
@@ -3560,6 +3622,7 @@ var MemoryManager = class _MemoryManager {
     }
     try {
       this.db.prepare("DELETE FROM memory_entries").run();
+      this.entryCount = 0;
       this.db.prepare("VACUUM").run();
       logger.info("All memory entries cleared");
     } catch (error) {
@@ -3600,41 +3663,227 @@ var MemoryManager = class _MemoryManager {
    * Get total count of memory entries
    * v5.0.8: Added for maxEntries enforcement
    */
+  /**
+   * Get current entry count
+   * Phase 1: Use internal counter instead of COUNT(*) for better performance
+   */
   getCount() {
     if (!this.initialized) {
       return 0;
     }
-    try {
-      const result = this.db.prepare("SELECT COUNT(*) as count FROM memory_entries").get();
-      return result?.count ?? 0;
-    } catch (error) {
-      logger.error("Failed to get entry count", { error: error.message });
+    return this.entryCount;
+  }
+  /**
+   * Phase 2: Validate cleanup configuration
+   * v5.0.10 Phase 2.1: Added validation for maxCleanupCount and retentionDays
+   * @throws {MemoryError} if configuration is invalid
+   */
+  validateCleanupConfig() {
+    const cfg = this.cleanupConfig;
+    if (cfg.triggerThreshold < 0.5 || cfg.triggerThreshold > 1) {
+      throw new MemoryError(
+        "cleanup.triggerThreshold must be between 0.5 and 1.0",
+        "CONFIG_ERROR"
+      );
+    }
+    if (cfg.targetThreshold < 0.1 || cfg.targetThreshold > 0.9) {
+      throw new MemoryError(
+        "cleanup.targetThreshold must be between 0.1 and 0.9",
+        "CONFIG_ERROR"
+      );
+    }
+    if (cfg.targetThreshold >= cfg.triggerThreshold) {
+      throw new MemoryError(
+        "cleanup.targetThreshold must be less than triggerThreshold",
+        "CONFIG_ERROR"
+      );
+    }
+    if (cfg.minCleanupCount < 1) {
+      throw new MemoryError(
+        "cleanup.minCleanupCount must be at least 1",
+        "CONFIG_ERROR"
+      );
+    }
+    if (cfg.maxCleanupCount < 1) {
+      throw new MemoryError(
+        "cleanup.maxCleanupCount must be at least 1",
+        "CONFIG_ERROR"
+      );
+    }
+    if (cfg.maxCleanupCount < cfg.minCleanupCount) {
+      throw new MemoryError(
+        "cleanup.maxCleanupCount must be >= minCleanupCount",
+        "CONFIG_ERROR"
+      );
+    }
+    if (cfg.retentionDays < 1) {
+      throw new MemoryError(
+        "cleanup.retentionDays must be at least 1",
+        "CONFIG_ERROR"
+      );
+    }
+  }
+  /**
+   * Phase 2: Check if cleanup should be triggered based on usage threshold
+   */
+  shouldTriggerCleanup() {
+    if (!this.cleanupConfig.enabled) {
+      return false;
+    }
+    const currentUsage = this.entryCount / this.config.maxEntries;
+    return currentUsage >= this.cleanupConfig.triggerThreshold;
+  }
+  /**
+   * Phase 2: Calculate how many entries to remove to reach target threshold
+   */
+  calculateCleanupCount() {
+    const targetCount = Math.floor(
+      this.config.maxEntries * this.cleanupConfig.targetThreshold
+    );
+    const toRemove = this.entryCount - targetCount;
+    if (toRemove <= 0) {
       return 0;
     }
+    return Math.max(
+      this.cleanupConfig.minCleanupCount,
+      Math.min(this.cleanupConfig.maxCleanupCount, toRemove)
+    );
+  }
+  /**
+   * Phase 2: Execute cleanup with configured strategy
+   * @returns Number of entries removed
+   */
+  async executeSmartCleanup() {
+    const count = this.calculateCleanupCount();
+    logger.debug("Executing smart cleanup", {
+      strategy: this.cleanupConfig.strategy,
+      count,
+      currentCount: this.entryCount,
+      threshold: this.cleanupConfig.triggerThreshold
+    });
+    switch (this.cleanupConfig.strategy) {
+      case "oldest":
+        return await this.cleanupOldest(count);
+      case "least_accessed":
+        return await this.cleanupLeastAccessed(count);
+      case "hybrid":
+        return await this.cleanupHybrid(count);
+      default:
+        throw new MemoryError(
+          `Unknown cleanup strategy: ${this.cleanupConfig.strategy}`,
+          "CONFIG_ERROR"
+        );
+    }
   }
   /**
    * Remove oldest entries
    * v5.0.8: Added for automatic cleanup when approaching maxEntries
+   * v5.0.10 Phase 2: Enhanced logging with strategy info
+   * v5.0.10 Phase 2.1: Now returns actual deleted count
    */
   async cleanupOldest(count) {
     if (!this.initialized || count <= 0) {
-      return;
+      return 0;
     }
     try {
-      this.db.prepare(`
+      const deleteInfo = this.statements.deleteOldest.run(count);
+      if (deleteInfo.changes > 0) {
+        this.entryCount -= deleteInfo.changes;
+      }
+      logger.info("Cleaned up oldest entries", {
+        requested: count,
+        deleted: deleteInfo.changes,
+        newCount: this.entryCount,
+        strategy: "oldest"
+        // Phase 2: Add strategy info
+      });
+      return deleteInfo.changes;
+    } catch (error) {
+      logger.error("Failed to cleanup oldest entries", {
+        count,
+        error: error.message
+      });
+      return 0;
+    }
+  }
+  /**
+   * Phase 2: Remove least accessed entries
+   * v5.0.10 Phase 2.1: Now async to support fallback to cleanupOldest
+   * @param count Number of entries to remove
+   * @returns Number of entries actually removed
+   */
+  async cleanupLeastAccessed(count) {
+    if (!this.initialized || count <= 0) {
+      return 0;
+    }
+    if (!this.config.trackAccess) {
+      logger.warn("least_accessed strategy requires trackAccess=true, falling back to oldest");
+      return await this.cleanupOldest(count);
+    }
+    try {
+      const deleteInfo = this.db.prepare(`
         DELETE FROM memory_entries
         WHERE id IN (
           SELECT id FROM memory_entries
-          ORDER BY created_at ASC
+          ORDER BY access_count ASC, last_accessed_at ASC
           LIMIT ?
         )
       `).run(count);
-      logger.info("Cleaned up oldest entries", { count });
+      if (deleteInfo.changes > 0) {
+        this.entryCount -= deleteInfo.changes;
+      }
+      logger.info("Cleaned up least accessed entries", {
+        requested: count,
+        deleted: deleteInfo.changes,
+        newCount: this.entryCount,
+        strategy: "least_accessed"
+      });
+      return deleteInfo.changes;
     } catch (error) {
-      logger.error("Failed to cleanup oldest entries", {
+      logger.error("Failed to cleanup least accessed entries", {
         count,
         error: error.message
       });
+      return 0;
+    }
+  }
+  /**
+   * Phase 2: Remove entries using hybrid strategy (access count + age)
+   * v5.0.10 Phase 2.1: Now async for consistency with other cleanup methods
+   * @param count Number of entries to remove
+   * @returns Number of entries actually removed
+   */
+  async cleanupHybrid(count) {
+    if (!this.initialized || count <= 0) {
+      return 0;
+    }
+    try {
+      const deleteInfo = this.db.prepare(`
+        DELETE FROM memory_entries
+        WHERE id IN (
+          SELECT id FROM memory_entries
+          ORDER BY
+            access_count ASC,
+            created_at ASC
+          LIMIT ?
+        )
+      `).run(count);
+      if (deleteInfo.changes > 0) {
+        this.entryCount -= deleteInfo.changes;
+      }
+      logger.info("Cleaned up entries using hybrid strategy", {
+        requested: count,
+        deleted: deleteInfo.changes,
+        newCount: this.entryCount,
+        strategy: "hybrid"
+      });
+      return deleteInfo.changes;
+    } catch (error) {
+      logger.error("Failed to cleanup with hybrid strategy", {
+        count,
+        error: error.message
+      });
+      return 0;
     }
   }
   async cleanup(olderThanDays) {
@@ -3644,14 +3893,16 @@ var MemoryManager = class _MemoryManager {
     const days = olderThanDays || this.config.cleanupDays;
     const cutoffTime = Date.now() - days * 24 * 60 * 60 * 1e3;
     try {
-      const result = this.db.prepare(`
-        DELETE FROM memory_entries
-        WHERE created_at < ?
-      `).run(cutoffTime);
-      const deleted = result.changes;
+      const deleteInfo = this.statements.deleteBeforeCutoff.run(cutoffTime);
+      const deleted = deleteInfo.changes;
       if (deleted > 0) {
+        this.entryCount -= deleted;
         this.db.prepare("VACUUM").run();
-        logger.info("Cleanup completed", { deleted, olderThanDays: days });
+        logger.info("Cleanup completed", {
+          deleted,
+          olderThanDays: days,
+          newCount: this.entryCount
+        });
       }
       return deleted;
     } catch (error) {
@@ -3708,6 +3959,9 @@ var MemoryManager = class _MemoryManager {
         );
       }
       this.db.close();
+      this.initialized = false;
+      this.entryCount = 0;
+      this.statements = {};
       const srcDb = new Database(srcPath, { readonly: true });
       const destDb = new Database(this.config.dbPath);
       await srcDb.backup(this.config.dbPath);
@@ -3715,8 +3969,7 @@ var MemoryManager = class _MemoryManager {
       destDb.close();
       this.db = new Database(this.config.dbPath);
       this.db.pragma("journal_mode = WAL");
-      sqliteVec.load(this.db);
-      this.initialized = true;
+      await this.initialize();
       logger.info("Database restored successfully", { srcPath });
     } catch (error) {
       throw new MemoryError(
@@ -10082,11 +10335,35 @@ var runCommand = {
         // fallbackProfilesDir (uses default)
         teamManager
       );
-      resolvedAgentName = await profileLoader.resolveAgentName(argv2.agent);
-      if (argv2.verbose) {
-        if (resolvedAgentName !== argv2.agent) {
-          console.log(chalk12.gray(`Resolved agent: ${argv2.agent} \u2192 ${resolvedAgentName}`));
+      try {
+        resolvedAgentName = await profileLoader.resolveAgentName(argv2.agent);
+        if (argv2.verbose) {
+          if (resolvedAgentName !== argv2.agent) {
+            console.log(chalk12.gray(`Resolved agent: ${argv2.agent} \u2192 ${resolvedAgentName}`));
+          }
+        }
+      } catch (error) {
+        console.error(chalk12.red.bold(`
+\u274C Agent not found: ${argv2.agent}
+`));
+        try {
+          const suggestions = await profileLoader.findSimilarAgents(argv2.agent, 3);
+          const closeSuggestions = suggestions.filter((s) => s.distance <= 3);
+          if (closeSuggestions.length > 0) {
+            console.log(chalk12.yellow("\u{1F4A1} Did you mean:\n"));
+            closeSuggestions.forEach((s, i) => {
+              const displayInfo = s.displayName ? `${s.displayName} (${s.name})` : s.name;
+              const roleInfo = s.role ? ` - ${s.role}` : "";
+              console.log(chalk12.cyan(`  ${i + 1}. ${displayInfo}${roleInfo}`));
+            });
+            console.log();
+          } else {
+            console.log(chalk12.gray('Run "ax agent list" to see available agents.\n'));
+          }
+        } catch {
+          console.log(chalk12.gray('Run "ax agent list" to see available agents.\n'));
         }
+        process.exit(1);
       }
       const abilitiesManager = new AbilitiesManager(
         join8(projectDir, ".automatosx", "abilities")