stigmergy 1.3.2-beta.3 → 1.3.2-beta.4

package/docs/LESSONS_LEARNED.md

@@ -0,0 +1,252 @@
+# 错误教训记录 (LESSONS LEARNED)
+
+本文档记录 Stigmergy 项目开发过程中遇到的重大错误和经验教训，**必须仔细阅读并避免重复犯错**。
+
+---
+
+## 🔴 致命错误 #1: 模板字符串中的正则表达式转义
+
+**日期**: 2025-12-25
+**影响**: 生产环境语法错误，所有 CLI 工具的 ResumeSession 集成失效
+**修复版本**: v1.3.2-beta.3
+**调试时间**: 约 2 小时
+**失败尝试**: 3 次
+
+### 问题描述
+
+生成的 `resumesession-history.js` 文件包含语法错误：
+
+```javascript
+SyntaxError: Invalid or unexpected token
+  at resumesession-history.js:515
+  const cleanInput = input.replace(/^\\/?stigmergy-resume\s*/i, '').trim();
+                                                            ^^^^^^^
+```
+
+### 错误代码
+
+**文件**: `src/core/coordination/nodejs/generators/ResumeSessionGenerator.js`
+**位置**: Line 537, 627
+
+```javascript
+// ❌ 错误写法
+const cleanInput = input.replace(/^\\\\/?\${commandName}\\s*/i, '').trim();
+const parts = cleanInput.split(/\\\\s+/).filter(p => p.length > 0);
+```
+
+### 根本原因分析
+
+#### 错误 #1: 阻止了模板插值
+
+```javascript
+\${commandName}  // ❌ 这会生成字面量 "${commandName}"，而不是插值后的值！
+${commandName}   // ✅ 这才会插值生成 "/stigmergy-resume"
+```
+
+**错误后果**：生成的代码中包含 `${commandName}` 字面量，导致语法错误。
+
+#### 错误 #2: 正则字面量中的 `/` 冲突
+
+```javascript
+// 当 commandName = "/stigmergy-resume" 时
+// 生成的代码：
+const cleanInput = input.replace(/^\\/?\/stigmergy-resume\s*/i, '').trim();
+//                              ↑ 第一个 / 关闭了正则字面量
+//                                stigmergy-resume\s*/i  ← 这部分变成了无关代码
+```
+
+**错误后果**：正则表达式被提前关闭，后续代码变成语法错误。
+
+#### 错误 #3: 反斜杠转义计算错误
+
+```
+模板字符串转义层级：
+源文件 → 模板字符串 → 生成代码 → 正则表达式
+
+错误的计算：
+源文件写：/^\\\\/?\${commandName}\\s*/i
+期望生成：/^\\/?stigmergy-resume\s*/i
+实际生成：/^\\/?${commandName}\s*/i  ← 未插值 + 正则破坏
+```
+
+### 正确的解决方案
+
+```javascript
+// ✅ 正确写法
+const cleanInput = input.replace(
+  new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+  ''
+).trim();
+const parts = cleanInput.split(/\\\s+/).filter(p => p.length > 0);
+```
+
+### 转义计算公式
+
+```
+源文件中的反斜杠数 = 目标反斜杠数 × 2^(嵌套层数)
+```
+
+**实际应用**：
+
+| 目标 | 在模板字符串中写 | 生成后 | 解释 |
+|------|------------------|--------|------|
+| `\s` | `\\s` | `\s` | 模板转义 1 次 |
+| `\\s` | `\\\\s` | `\\s` | 模板转义 1 次 |
+| `\\\s` | `\\\\\\s` | `\\s` | 字符串内容为 `\\s` |
+
+### 为什么使用 RegExp 构造函数？
+
+```javascript
+// ❌ 危险：正则字面量
+/^\\\\/?\/stigmergy-resume\s*/i
+//        ↑ 与命令名中的 / 冲突
+
+// ✅ 安全：RegExp 构造函数
+new RegExp('^\\\\\\\\/?' + '/stigmergy-resume' + '\\\\\s*', 'i')
+//           ↑ 通过字符串拼接避免 / 冲突
+```
+
+### 经验教训
+
+#### 1. 永远记住的规则
+
+> **在模板字符串中生成包含正则的代码时，使用 RegExp 构造函数 + 字符串拼接，永远比尝试计算正确的正则字面量转义更安全！**
+
+```javascript
+// ✅ 安全、清晰、可维护
+new RegExp('pattern' + variable + 'pattern', 'flags')
+
+// ❌ 危险、复杂、易出错
+/pattern${variable}pattern/flags
+```
+
+#### 2. 必须遵守的规则
+
+- [ ] **永远不要阻止插值**：使用 `${variable}`，而不是 `\${variable}`
+- [ ] **动态模式 → RegExp 构造函数**：避免正则字面量中的 `/` 冲突
+- [ ] **反斜杠数量必须计算**：使用公式，不能猜测
+- [ ] **必须添加语法验证**：生成代码后立即测试语法
+- [ ] **必须注释说明转义**：让其他人理解你的计算
+
+#### 3. 代码审查检查清单
+
+涉及 **模板字符串 + 正则表达式** 的代码必须检查：
+
+```javascript
+// ✅ 检查项
+- [ ] 所有 ${variable} 是否真的需要插值（不是 \${variable}）
+- [ ] 如果模式包含动态的 /，是否使用了 RegExp 构造函数
+- [ ] 反斜杠数量是否经过计算（而非猜测）
+- [ ] 是否有语法验证测试
+- [ ] 是否注释说明了转义的计算过程
+```
+
+### 验证工具
+
+```javascript
+/**
+ * 验证生成的代码是否有语法错误
+ */
+function validateGeneratedCode(code) {
+  try {
+    new Function(code);
+    return true;
+  } catch (e) {
+    console.error('❌ 语法错误:', e.message);
+    console.error('代码:', code);
+    return false;
+  }
+}
+
+/**
+ * 计算需要的反斜杠数量
+ */
+function calculateBackslashes(targetCount, nestingDepth = 1) {
+  return '\\'.repeat(targetCount * Math.pow(2, nestingDepth));
+}
+
+// 使用示例
+const generatedCode = generator.generateForCLI('claude');
+if (!validateGeneratedCode(generatedCode)) {
+  throw new Error('生成的代码有语法错误！');
+}
+```
+
+### 相关文档
+
+- [开发规范 - 代码生成规范](./development_guidelines.md#10-代码生成规范)
+- [ResumeSessionGenerator 源代码](../src/core/coordination/nodejs/generators/ResumeSessionGenerator.js)
+- [修复提交](https://github.com/your-repo/commit/6a2ee2c6)
+
+---
+
+## 📋 错误教训快速参考
+
+### 正则表达式生成
+
+| 场景 | ✅ 正确 | ❌ 错误 |
+|------|--------|--------|
+| 动态模式 | `new RegExp(pattern + var)` | `/pattern${var}/` |
+| 模板插值 | `${variable}` | `\${variable}` |
+| 反斜杠转义 | 通过公式计算 | 猜测数量 |
+| 语法验证 | 必须添加 | 跳过测试 |
+
+### 转义速查表
+
+| 生成目标 | 模板字符串中写 | 说明 |
+|----------|----------------|------|
+| `\s` | `\\s` | 匹配空白字符 |
+| `\\s` | `\\\\s` | 字符串 `"\s"` |
+| `\\\s` | `\\\\\\s` | 字符串 `"\\s"` |
+| `/stigmergy-resume` | `${commandName}` | 插值命令名 |
+| `RegExp('/stigmergy-resume')` | `new RegExp('${commandName}')` | 动态正则 |
+
+---
+
+## 🔄 如何添加新的错误教训
+
+当遇到重大错误时，请按照以下格式记录：
+
+```markdown
+## 🔴 致命错误 #N: [错误标题]
+
+**日期**: YYYY-MM-DD
+**影响**: [影响范围]
+**修复版本**: vX.X.X
+**调试时间**: 约 X 小时
+**失败尝试**: X 次
+
+### 问题描述
+[描述问题的现象和错误信息]
+
+### 错误代码
+**文件**: [文件路径]
+**位置**: Line XXX
+
+```javascript
+// ❌ 错误写法
+[错误代码]
+```
+
+### 根本原因分析
+[分析为什么会出现这个错误]
+
+### 正确的解决方案
+```javascript
+// ✅ 正确写法
+[正确代码]
+```
+
+### 经验教训
+[总结规则和检查清单]
+
+### 验证工具
+[提供验证和测试方法]
+```
+
+---
+
+**最后更新**: 2025-12-25
+**维护者**: Stigmergy 开发团队
+
+**记住这些教训，避免重复犯错！**

package/docs/development_guidelines.md

@@ -389,4 +389,280 @@ class CacheManager {
 }
 ```
 
+## 10. 代码生成规范
+
+### 10.1 模板字符串中的正则表达式 ⚠️ 极其重要！
+
+#### 🔴 致命陷阱：正则表达式字面量 vs RegExp 构造函数
+
+**问题场景**：在模板字符串中生成包含正则表达式的代码
+
+```javascript
+// ❌ 错误示例
+const code = `
+  const cleanInput = input.replace(/^\\\\/?${commandName}\\s*/i, '').trim();
+`;
+
+// 当 commandName = "/stigmergy-resume" 时
+// 生成：/^\\/?\/stigmergy-resume\s*/i
+//                        ↑ 正则被 "/stigmergy-resume" 中的 / 提前关闭！
+```
+
+**错误原因分析**：
+
+1. **正则字面量语法冲突**：`/pattern/` 首尾的 `/` 是定界符
+2. **命令名中的 `/` 破坏语法**：`/^\\/?\/stigmergy-resume` 中第一个 `/` 关闭了正则
+3. **模板字符串插值错误**：使用 `\${variable}` 会阻止插值！
+
+#### ✅ 正确做法：使用 RegExp 构造函数
+
+```javascript
+// ✅ 正确示例
+const code = `
+  const cleanInput = input.replace(
+    new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+    ''
+  ).trim();
+`;
+```
+
+**转义计算公式**：
+
+```
+源文件中的反斜杠数 = 目标反斜杠数 × 2^(嵌套层数)
+```
+
+| 目标 | 在模板字符串中写 | 生成后 | 说明 |
+|------|------------------|--------|------|
+| `\s` | `\\s` | `\s` | 模板转义一次 |
+| `\\s` | `\\\\s` | `\\s` | 模板转义一次 |
+| `\\\s` | `\\\\\\s` | `\\s` | 字符串中为 `\\s` |
+
+#### 📋 必须遵守的规则
+
+1. **动态模式 → 用 RegExp 构造函数**
+   ```javascript
+   new RegExp(pattern + variable + pattern, flags)
+   ```
+
+2. **静态模式 → 可以用正则字面量**
+   ```javascript
+   const staticRegex = /\s+/;  // 简单清晰
+   ```
+
+3. **永远不要阻止插值**
+   ```javascript
+   // ❌ 错误：阻止插值
+   \${commandName}  // 生成字面量 "${commandName}"
+
+   // ✅ 正确：允许插值
+   ${commandName}   // 生成实际值 "/stigmergy-resume"
+   ```
+
+4. **不要在字符串中转义 `/`**
+   ```javascript
+   // ❌ 不必要
+   '\/path'  // 在字符串中不需要转义 /
+
+   // ✅ 正确
+   '/path'   // 字符串中的 / 不需要转义
+   ```
+
+#### 🛠️ 调试工具
+
+```javascript
+/**
+ * 验证生成的代码是否有语法错误
+ */
+function validateGeneratedCode(code) {
+  try {
+    new Function(code);
+    return true;
+  } catch (e) {
+    console.error('语法错误:', e.message);
+    return false;
+  }
+}
+
+/**
+ * 计算需要的反斜杠数量
+ */
+function calculateBackslashes(targetCount, nestingDepth = 1) {
+  return '\\'.repeat(targetCount * Math.pow(2, nestingDepth));
+}
+```
+
+#### 📝 代码审查检查清单
+
+涉及 **模板字符串 + 正则表达式** 的代码必须检查：
+
+- [ ] 所有 `${variable}` 是否真的需要插值（不是 `\${variable}`）
+- [ ] 如果模式包含动态的 `/`，是否使用了 RegExp 构造函数
+- [ ] 反斜杠数量是否经过计算（而非猜测）
+- [ ] 是否有语法验证测试
+- [ ] 是否注释说明了转义的计算过程
+
+#### 💡 永远记住
+
+> **在模板字符串中生成包含正则的代码时，使用 RegExp 构造函数 + 字符串拼接，永远比尝试计算正确的正则字面量转义更安全！**
+
+```javascript
+// ✅ 安全、清晰、可维护
+new RegExp('pattern' + variable + 'pattern', 'flags')
+
+// ❌ 危险、复杂、易出错
+/pattern${variable}pattern/flags
+```
+
+### 10.2 代码生成最佳实践
+
+#### 10.2.1 生成器模式
+
+```javascript
+class CodeGenerator {
+  /**
+   * 生成CLI集成代码
+   * @param {string} cliName - CLI工具名称
+   * @returns {string} 生成的代码
+   */
+  generateForCLI(cliName) {
+    const commandName = this.getCommandName(cliName);
+
+    return `
+// Auto-generated by Stigmergy - DO NOT EDIT
+const handler = {
+  commandName: '${commandName}',
+
+  async handle(input) {
+    const cleanInput = input.replace(
+      new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+      ''
+    ).trim();
+
+    // 处理逻辑...
+    return { response: 'OK' };
+  }
+};
+
+module.exports = handler;
+`;
+  }
+
+  /**
+   * 获取命令名称
+   */
+  getCommandName(cliName) {
+    const needsSlash = ['claude', 'codebuddy'].includes(cliName.toLowerCase());
+    return needsSlash ? `/stigmergy-resume` : 'stigmergy-resume';
+  }
+}
+```
+
+#### 10.2.2 测试生成代码
+
+```javascript
+const { CodeGenerator } = require('./generators');
+
+describe('CodeGenerator', () => {
+  test('should generate valid JavaScript syntax', () => {
+    const generator = new CodeGenerator();
+    const code = generator.generateForCLI('claude');
+
+    // 验证语法
+    expect(() => new Function(code)).not.toThrow();
+
+    // 验证包含关键部分
+    expect(code).toContain('new RegExp');
+    expect(code).toContain('/stigmergy-resume');
+  });
+
+  test('should escape regex correctly', () => {
+    const generator = new CodeGenerator();
+    const code = generator.generateForCLI('claude');
+
+    // 提取并验证正则表达式
+    const regexMatch = code.match(/new RegExp\('([^']+)',\s*'i'\)/);
+    expect(regexMatch).toBeTruthy();
+
+    // 测试生成的正则是否工作
+    const pattern = regexMatch[1];
+    const regex = new RegExp(pattern, 'i');
+    expect(regex.test('/stigmergy-resume')).toBe(true);
+    expect(regex.test('\\/stigmergy-resume')).toBe(true);
+  });
+});
+```
+
+### 10.3 常见错误案例
+
+#### 案例1：阻止插值
+
+```javascript
+// ❌ 错误
+const commandName = '/stigmergy-resume';
+const code = `input.replace(/^\\\\/?\${commandName}\\s*/i, '')`;
+// 生成：input.replace(/^\\\\/?${commandName}\s*/i, '')
+//                                ↑ 未插值！
+```
+
+```javascript
+// ✅ 正确
+const commandName = '/stigmergy-resume';
+const code = `input.replace(new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'), '')`;
+// 生成：input.replace(new RegExp('^\\\\/?' + '/stigmergy-resume' + '\s*', 'i'), '')
+```
+
+#### 案例2：正则字面量中的 `/` 冲突
+
+```javascript
+// ❌ 错误
+const commandName = '/stigmergy-resume';
+const code = `input.replace(/\\/?${commandName}\\s*/i, '')`;
+// 生成：input.replace(/\/?\/stigmergy-resume\s*/i, '')
+//                        ↑ 第一个 / 关闭了正则
+```
+
+```javascript
+// ✅ 正确
+const commandName = '/stigmergy-resume';
+const code = `input.replace(new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'), '')`;
+```
+
+### 10.4 历史教训记录
+
+#### 2025-12-25: ResumeSessionGenerator 正则转义错误
+
+**问题描述**：
+生成的 `resumesession-history.js` 文件包含语法错误，导致无法加载。
+
+**错误代码**（Line 537, 627）：
+```javascript
+const cleanInput = input.replace(/^\\\\/?\${commandName}\\s*/i, '').trim();
+```
+
+**错误原因**：
+1. `\${commandName}` 阻止了模板插值
+2. 正则字面量中的 `/` 与命令名中的 `/` 冲突
+3. 反斜杠转义计算错误
+
+**修复方案**：
+```javascript
+const cleanInput = input.replace(
+  new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+  ''
+).trim();
+```
+
+**影响范围**：
+- 影响：所有CLI工具的ResumeSession集成
+- 修复版本：v1.3.2-beta.3
+- 调试时间：约2小时
+- 失败尝试：3次
+
+**经验总结**：
+- 永远使用 RegExp 构造函数处理动态正则
+- 永远不要在模板字符串中用 `\${` 阻止插值（除非真的需要字面量）
+- 反斜杠数量必须通过公式计算，不能猜测
+- 必须添加语法验证测试
+
 遵循这些开发规范可以确保代码质量、可维护性和团队协作效率。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stigmergy",
-  "version": "1.3.2-beta.3",
+  "version": "1.3.2-beta.4",
   "description": "Stigmergy CLI - Multi-Agents Cross-AI CLI Tools Collaboration System",
   "main": "src/index.js",
   "bin": {

package/src/core/cli_path_detector.js

@@ -373,10 +373,19 @@ class CLIPathDetector {
       if (await fs.access(this.pathCacheFile).then(() => true).catch(() => false)) {
         const data = await fs.readFile(this.pathCacheFile, 'utf8');
         const cacheData = JSON.parse(data);
-        this.detectedPaths = cacheData.detectedPaths || {};
 
-        console.log(`[DETECTOR] Loaded ${Object.keys(this.detectedPaths).length} paths from cache`);
-        return this.detectedPaths;
+        // Check if cache is too old (older than 1 hour) and skip loading if so
+        const cacheAge = Date.now() - new Date(cacheData.timestamp).getTime();
+        const maxCacheAge = 60 * 60 * 1000; // 1 hour in milliseconds
+
+        if (cacheAge < maxCacheAge) {
+          this.detectedPaths = cacheData.detectedPaths || {};
+          console.log(`[DETECTOR] Loaded ${Object.keys(this.detectedPaths).length} paths from cache (age: ${Math.floor(cacheAge/1000)}s)`);
+          return this.detectedPaths;
+        } else {
+          console.log(`[DETECTOR] Cache is too old (${Math.floor(cacheAge/1000)}s), skipping cache`);
+          return {};
+        }
       }
     } catch (error) {
       console.log(`[DETECTOR] Warning: Could not load path cache: ${error.message}`);

package/src/core/cli_tools.js

@@ -2,6 +2,7 @@ const path = require('path');
 const os = require('os');
 const { errorHandler, ERROR_TYPES } = require('./error_handler');
 const CLIPathDetector = require('./cli_path_detector');
+const StigmergyInstaller = require('./installer');
 
 // AI CLI Tools Configuration
 const CLI_TOOLS = {
@@ -140,6 +141,189 @@ async function getCLIPath(toolName) {
   return toolPath;
 }
 
+/**
+ * Check if a CLI tool is actually executable
+ * @param {string} toolName - Name of the tool to check
+ * @returns {Promise<boolean>} Whether the tool is executable
+ */
+async function checkIfCLIExecutable(toolName) {
+  const { spawnSync } = require('child_process');
+  const os = require('os');
+
+  // Special handling for codex - check if the JS file is valid
+  if (toolName === 'codex') {
+    try {
+      // First check if codex command exists
+      const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+      const whichResult = spawnSync(whichCmd, [toolName], {
+        encoding: 'utf8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: true,
+      });
+
+      if (whichResult.status === 0 && whichResult.stdout.trim()) {
+        const codexPath = whichResult.stdout.trim().split('\n')[0]; // Get first match
+
+        // If it's a shell script, check the target JS file
+        if (
+          codexPath.endsWith('.sh') ||
+          codexPath.endsWith('.cmd') ||
+          codexPath.endsWith('/codex') ||
+          codexPath.endsWith('\\codex')
+        ) {
+          // Try to verify JS file, but don't fail if we can't
+          // The actual --version test below is more reliable
+          try {
+            const fsSync = require('fs');
+            const scriptContent = fsSync.readFileSync(codexPath, 'utf8');
+
+            // Look for JS file reference in the script
+            // Match node_modules/@openai/codex/bin/codex.js pattern
+            const jsFileMatch = scriptContent.match(/node_modules\/@openai\/codex\/bin\/codex\.js/);
+            if (jsFileMatch) {
+              // Construct actual path based on npm global directory
+              const npmGlobalDir = require('path').dirname(codexPath);
+              const jsFilePath = require('path').join(npmGlobalDir, jsFileMatch[0]);
+
+              if (fsSync.existsSync(jsFilePath)) {
+                const stats = fsSync.statSync(jsFilePath);
+                if (stats.size === 0) {
+                  console.log('[DEBUG] Codex JS file is empty, marking as unavailable');
+                  return false;
+                }
+                // File exists and has content - continue to version check
+              } else {
+                console.log('[DEBUG] Codex JS file not found at expected path, will try version check');
+              }
+            }
+          } catch (scriptError) {
+            console.log(`[DEBUG] Could not verify codex script: ${scriptError.message}`);
+            // Continue anyway - the version check below is more reliable
+          }
+        }
+
+        // If we got here, the codex command exists - continue with normal checks below
+      } else {
+        // Codex command doesn't exist
+        return false;
+      }
+    } catch (error) {
+      console.log(`[DEBUG] Error checking codex: ${error.message}`);
+      return false;
+    }
+  }
+
+  // First try to find the executable using which/where command (more reliable)
+  try {
+    const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+    const whichResult = spawnSync(whichCmd, [toolName], {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'], // Use pipes to avoid file opening
+      shell: true,
+    });
+
+    if (whichResult.status === 0 && whichResult.stdout.trim()) {
+      // Found executable, now test it safely
+      const testArgs = ['--help'];
+      const testOptions = {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'], // Don't inherit from parent to avoid opening UI
+        shell: true,
+      };
+
+      // Additional protection for codex
+      // Note: codex requires shell=true on Windows to work properly
+      if (toolName === 'codex') {
+        // Keep shell=true for codex (don't override)
+        testOptions.windowsHide = true;
+        testOptions.detached = false;
+      }
+
+      const testResult = spawnSync(toolName, testArgs, testOptions);
+
+      // If command runs successfully or at least returns something (not command not found)
+      if (testResult.status === 0 || testResult.status === 1) {
+        return true;
+      }
+    }
+  } catch (error) {
+    // which/where command probably failed, continue with other checks
+    console.log(`[DEBUG] which/where check failed for ${toolName}: ${error.message}`);
+  }
+
+  // Special handling for codex to avoid opening files
+  if (toolName === 'codex') {
+    // For codex, only try --help and --version with extra precautions
+    // Note: codex requires shell=true on Windows
+    const codexChecks = [
+      { args: ['--help'], expected: 0 },
+      { args: ['--version'], expected: 0 },
+    ];
+
+    for (const check of codexChecks) {
+      try {
+        const result = spawnSync(toolName, check.args, {
+          encoding: 'utf8',
+          timeout: 10000,
+          stdio: ['pipe', 'pipe', 'pipe'], // Ensure all IO is piped
+          shell: true, // Use shell for codex compatibility
+          windowsHide: true, // Hide console window on Windows
+          detached: false, // Don't detach process
+        });
+
+        if (result.status === 0 || result.status === 1) {
+          return true;
+        }
+      } catch (error) {
+        // Continue to next check
+      }
+    }
+    return false; // If all codex checks fail
+  }
+
+  // Fallback: Try multiple ways to check if CLI is available but more safely
+  const checks = [
+    // Method 1: Try help command (most common and safe)
+    { args: ['--help'], expected: 0 },
+    // Method 2: Try help command with -h
+    { args: ['-h'], expected: 0 },
+    // Method 3: Try version command
+    { args: ['--version'], expected: 0 },
+    // Method 4: Try just the command (help case)
+    { args: [], expected: 0 },
+  ];
+
+  for (const check of checks) {
+    try {
+      const result = spawnSync(toolName, check.args, {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'], // Use pipe instead of inherit to avoid opening files
+        shell: true,
+      });
+
+      // Check if command executed successfully or at least didn't fail with "command not found"
+      if (
+        result.status === check.expected ||
+        (result.status !== 127 &&
+          result.status !== 9009 &&
+          result.status !== 1) // Also avoid status 1 (general error)
+      ) {
+        // 127 = command not found on Unix, 9009 = command not found on Windows
+        return true;
+      }
+    } catch (error) {
+      // Continue to next check method
+      continue;
+    }
+  }
+
+  return false;
+}
+
 /**
  * Update PATH configuration and run path detection
  */
@@ -157,13 +341,211 @@ async function setupCLIPaths() {
   // 3. Check and update PATH if needed
   const pathStatus = await detector.updatePATHIfMissing();
 
+  // 4. Create an enhanced report using StigmergyInstaller detection logic
+  const installer = new StigmergyInstaller();
+  const scanResult = await installer.scanCLI();
+
+  const enhancedReport = {
+    platform: detector.platform,
+    npmGlobalPaths: detector.npmGlobalPaths,
+    detectedPaths: detector.detectedPaths,
+    summary: {
+      total: Object.keys(detector.cliNameMap).length,
+      found: Object.keys(scanResult.available).length,
+      missing: Object.keys(scanResult.missing).length
+    }
+  };
+
   return {
     detectedPaths,
     pathStatus,
-    report: detector.getPathStatusReport()
+    report: enhancedReport
   };
 }
 
+/**
+ * Check if a CLI tool is actually executable
+ * @param {string} toolName - Name of the tool to check
+ * @returns {Promise<boolean>} Whether the tool is executable
+ */
+async function checkIfCLIExecutable(toolName) {
+  const { spawnSync } = require('child_process');
+  const os = require('os');
+
+  // Special handling for codex - check if the JS file is valid
+  if (toolName === 'codex') {
+    try {
+      // First check if codex command exists
+      const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+      const whichResult = spawnSync(whichCmd, [toolName], {
+        encoding: 'utf8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: true,
+      });
+
+      if (whichResult.status === 0 && whichResult.stdout.trim()) {
+        const codexPath = whichResult.stdout.trim().split('\n')[0]; // Get first match
+
+        // If it's a shell script, check the target JS file
+        if (
+          codexPath.endsWith('.sh') ||
+          codexPath.endsWith('.cmd') ||
+          codexPath.endsWith('/codex') ||
+          codexPath.endsWith('\\codex')
+        ) {
+          // Try to verify JS file, but don't fail if we can't
+          // The actual --version test below is more reliable
+          try {
+            const fsSync = require('fs');
+            const scriptContent = fsSync.readFileSync(codexPath, 'utf8');
+
+            // Look for JS file reference in the script
+            // Match node_modules/@openai/codex/bin/codex.js pattern
+            const jsFileMatch = scriptContent.match(/node_modules\/@openai\/codex\/bin\/codex\.js/);
+            if (jsFileMatch) {
+              // Construct actual path based on npm global directory
+              const npmGlobalDir = require('path').dirname(codexPath);
+              const jsFilePath = require('path').join(npmGlobalDir, jsFileMatch[0]);
+
+              if (fsSync.existsSync(jsFilePath)) {
+                const stats = fsSync.statSync(jsFilePath);
+                if (stats.size === 0) {
+                  console.log('[DEBUG] Codex JS file is empty, marking as unavailable');
+                  return false;
+                }
+                // File exists and has content - continue to version check
+              } else {
+                console.log('[DEBUG] Codex JS file not found at expected path, will try version check');
+              }
+            }
+          } catch (scriptError) {
+            console.log(`[DEBUG] Could not verify codex script: ${scriptError.message}`);
+            // Continue anyway - the version check below is more reliable
+          }
+        }
+
+        // If we got here, the codex command exists - continue with normal checks below
+      } else {
+        // Codex command doesn't exist
+        return false;
+      }
+    } catch (error) {
+      console.log(`[DEBUG] Error checking codex: ${error.message}`);
+      return false;
+    }
+  }
+
+  // First try to find the executable using which/where command (more reliable)
+  try {
+    const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+    const whichResult = spawnSync(whichCmd, [toolName], {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'], // Use pipes to avoid file opening
+      shell: true,
+    });
+
+    if (whichResult.status === 0 && whichResult.stdout.trim()) {
+      // Found executable, now test it safely
+      const testArgs = ['--help'];
+      const testOptions = {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'], // Don't inherit from parent to avoid opening UI
+        shell: true,
+      };
+
+      // Additional protection for codex
+      // Note: codex requires shell=true on Windows to work properly
+      if (toolName === 'codex') {
+        // Keep shell=true for codex (don't override)
+        testOptions.windowsHide = true;
+        testOptions.detached = false;
+      }
+
+      const testResult = spawnSync(toolName, testArgs, testOptions);
+
+      // If command runs successfully or at least returns something (not command not found)
+      if (testResult.status === 0 || testResult.status === 1) {
+        return true;
+      }
+    }
+  } catch (error) {
+    // which/where command probably failed, continue with other checks
+    console.log(`[DEBUG] which/where check failed for ${toolName}: ${error.message}`);
+  }
+
+  // Special handling for codex to avoid opening files
+  if (toolName === 'codex') {
+    // For codex, only try --help and --version with extra precautions
+    // Note: codex requires shell=true on Windows
+    const codexChecks = [
+      { args: ['--help'], expected: 0 },
+      { args: ['--version'], expected: 0 },
+    ];
+
+    for (const check of codexChecks) {
+      try {
+        const result = spawnSync(toolName, check.args, {
+          encoding: 'utf8',
+          timeout: 10000,
+          stdio: ['pipe', 'pipe', 'pipe'], // Ensure all IO is piped
+          shell: true, // Use shell for codex compatibility
+          windowsHide: true, // Hide console window on Windows
+          detached: false, // Don't detach process
+        });
+
+        if (result.status === 0 || result.status === 1) {
+          return true;
+        }
+      } catch (error) {
+        // Continue to next check
+      }
+    }
+    return false; // If all codex checks fail
+  }
+
+  // Fallback: Try multiple ways to check if CLI is available but more safely
+  const checks = [
+    // Method 1: Try help command (most common and safe)
+    { args: ['--help'], expected: 0 },
+    // Method 2: Try help command with -h
+    { args: ['-h'], expected: 0 },
+    // Method 3: Try version command
+    { args: ['--version'], expected: 0 },
+    // Method 4: Try just the command (help case)
+    { args: [], expected: 0 },
+  ];
+
+  for (const check of checks) {
+    try {
+      const result = spawnSync(toolName, check.args, {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'], // Use pipe instead of inherit to avoid opening files
+        shell: true,
+      });
+
+      // Check if command executed successfully or at least didn't fail with "command not found"
+      if (
+        result.status === check.expected ||
+        (result.status !== 127 &&
+          result.status !== 9009 &&
+          result.status !== 1) // Also avoid status 1 (general error)
+      ) {
+        // 127 = command not found on Unix, 9009 = command not found on Windows
+        return true;
+      }
+    } catch (error) {
+      // Continue to next check method
+      continue;
+    }
+  }
+
+  return false;
+}
+
 /**
  * Scan for available CLI tools
  * @param {Object} options - Scan options
@@ -172,29 +554,26 @@ async function setupCLIPaths() {
  * @returns {Promise<Object>} Scan results
  */
 async function scanForTools(options = {}) {
-  const detector = getPathDetector();
-
-  // Load cached paths first
-  await detector.loadDetectedPaths();
-
-  // Detect all CLI paths
-  const detectedPaths = await detector.detectAllCLIPaths();
+  // Use StigmergyInstaller detection logic directly
+  const installer = new StigmergyInstaller();
+  const scanResult = await installer.scanCLI();
 
   const found = [];
   const missing = [];
 
-  for (const [toolName, toolPath] of Object.entries(detectedPaths)) {
-    if (toolPath) {
-      found.push({
-        name: toolName,
-        path: toolPath,
-        type: 'cli',
-        status: 'installed',
-        description: CLI_TOOLS[toolName]?.name || toolName
-      });
-    } else {
-      missing.push(toolName);
-    }
+  // Convert scanResult to the expected format
+  for (const [toolName, toolInfo] of Object.entries(scanResult.available)) {
+    found.push({
+      name: toolName,
+      path: null, // Path is not provided by scanCLI, but we can potentially add it
+      type: 'cli',
+      status: 'installed',
+      description: CLI_TOOLS[toolName]?.name || toolName
+    });
+  }
+
+  for (const [toolName, toolInfo] of Object.entries(scanResult.missing)) {
+    missing.push(toolName);
   }
 
   return {
@@ -212,20 +591,25 @@ async function scanForTools(options = {}) {
 async function checkInstallation(toolName) {
   validateCLITool(toolName);
 
-  const detector = getPathDetector();
-  await detector.loadDetectedPaths();
+  // Use StigmergyInstaller detection logic directly
+  const installer = new StigmergyInstaller();
+  const isAvailable = await installer.checkCLI(toolName);
 
-  let toolPath = detector.getDetectedPath(toolName);
+  // If the tool is available, try to get its path and version
+  let toolPath = null;
+  let version = null;
 
-  // If not cached, detect it
-  if (!toolPath) {
-    toolPath = await detector.detectCLIPath(toolName);
-  }
+  if (isAvailable) {
+    // Get path using the detector
+    const detector = getPathDetector();
+    await detector.loadDetectedPaths();
+    toolPath = detector.getDetectedPath(toolName);
 
-  const installed = !!toolPath;
+    if (!toolPath) {
+      toolPath = await detector.detectCLIPath(toolName);
+    }
 
-  let version = null;
-  if (installed) {
+    // Get version
     try {
       const { spawnSync } = require('child_process');
       const toolConfig = CLI_TOOLS[toolName];
@@ -246,7 +630,7 @@ async function checkInstallation(toolName) {
   }
 
   return {
-    installed,
+    installed: isAvailable,
     path: toolPath,
     version,
     lastChecked: new Date().toISOString()

package/src/core/enhanced_cli_installer.js

@@ -106,6 +106,15 @@ class EnhancedCLIInstaller {
         return { success: true, mode: 'elevated' };
       }
 
+      // Check if we're in a container environment (common indicators)
+      const inContainer = await this.checkContainerEnvironment();
+      if (inContainer) {
+        this.log('info', 'Detected container environment, using user-space installation');
+        this.permissionMode = 'user-space';
+        this.permissionConfigured = true;
+        return { success: true, mode: 'user-space' };
+      }
+
       // Attempt standard installation first
       const testResult = await this.attemptTestInstallation();
 
@@ -128,9 +137,10 @@ class EnhancedCLIInstaller {
           return { success: true, mode: 'elevated' };
         } else {
           this.log('error', 'Failed to set up elevated permissions');
-          this.permissionMode = 'failed';
+          this.log('info', 'Falling back to user-space installation');
+          this.permissionMode = 'user-space';
           this.permissionConfigured = true;
-          return { success: false, mode: 'failed', error: elevatedSetup.error };
+          return { success: true, mode: 'user-space' };
         }
       }
 
@@ -142,9 +152,10 @@ class EnhancedCLIInstaller {
 
     } catch (error) {
       this.log('error', `Permission setup failed: ${error.message}`);
-      this.permissionMode = 'failed';
+      this.log('info', 'Falling back to user-space installation');
+      this.permissionMode = 'user-space';
       this.permissionConfigured = true;
-      return { success: false, mode: 'failed', error: error.message };
+      return { success: true, mode: 'user-space', error: error.message };
     }
   }
 
@@ -169,6 +180,59 @@ class EnhancedCLIInstaller {
     }
   }
 
+  /**
+   * Check if we're running in a container environment
+   */
+  async checkContainerEnvironment() {
+    try {
+      // Check for container indicators
+      const fs = require('fs');
+
+      // Check for .dockerenv file
+      if (fs.existsSync('/.dockerenv')) {
+        return true;
+      }
+
+      // Check for container environment variables
+      if (process.env.container || process.env.DOCKER_CONTAINER) {
+        return true;
+      }
+
+      // Check cgroup for container indicators
+      try {
+        if (fs.existsSync('/proc/1/cgroup')) {
+          const cgroupContent = fs.readFileSync('/proc/1/cgroup', 'utf8');
+          if (cgroupContent.includes('docker') || cgroupContent.includes('containerd')) {
+            return true;
+          }
+        }
+      } catch (e) {
+        // Ignore errors reading cgroup
+      }
+
+      // Check for container-specific files
+      const containerIndicators = [
+        '/run/.containerenv', // Podman/Docker
+        '/sys/fs/cgroup/cpu/cpu.cfs_quota_us', // Common in containers
+      ];
+
+      for (const indicator of containerIndicators) {
+        try {
+          if (fs.existsSync(indicator)) {
+            return true;
+          }
+        } catch (e) {
+          // Ignore errors
+        }
+      }
+
+      return false;
+    } catch (error) {
+      // If we can't determine, assume not in container
+      return false;
+    }
+  }
+
   /**
    * Attempt a test installation to check permissions
    */
@@ -304,6 +368,15 @@ class EnhancedCLIInstaller {
       await this.setupPermissions();
     }
 
+    // Check if we're in a container environment and force user-space mode if needed
+    if (this.permissionMode !== 'user-space') {
+      const inContainer = await this.checkContainerEnvironment();
+      if (inContainer) {
+        this.log('info', 'Detected container environment, switching to user-space installation');
+        this.permissionMode = 'user-space';
+      }
+    }
+
     this.log('info', `Installing ${toolInfo.name} (${toolName})...`);
 
     try {
@@ -358,6 +431,8 @@ class EnhancedCLIInstaller {
         return await this.executeStandardInstallation(toolInfo);
       case 'elevated':
         return await this.executeElevatedInstallation(toolInfo);
+      case 'user-space':
+        return await this.executeUserSpaceInstallation(toolInfo);
       case 'failed':
         return await this.executeFallbackInstallation(toolInfo);
       default:
@@ -412,10 +487,25 @@ class EnhancedCLIInstaller {
         return { success: true, error: null };
       } else {
         const errorMessage = result.stderr || result.stdout || `Exit code ${result.status}`;
+
+        // Check if this is a permission error and switch to user-space if needed
+        if (this.isPermissionError(errorMessage)) {
+          this.log('warn', `Standard installation failed due to permission error, switching to user-space installation...`);
+          this.permissionMode = 'user-space';
+          return await this.executeUserSpaceInstallation(toolInfo);
+        }
+
         return { success: false, error: errorMessage };
       }
 
     } catch (error) {
+      // Check if this is a permission error and switch to user-space if needed
+      if (this.isPermissionError(error.message)) {
+        this.log('warn', `Standard installation failed due to permission error, switching to user-space installation...`);
+        this.permissionMode = 'user-space';
+        return await this.executeUserSpaceInstallation(toolInfo);
+      }
+
       return { success: false, error: error.message };
     }
   }
@@ -477,12 +567,22 @@ class EnhancedCLIInstaller {
         this.log('warn', `Could not clean up temp script: ${cleanupError.message}`);
       }
 
-      return {
-        success: result.status === 0,
-        error: result.status !== 0 ? 'Windows elevated installation failed' : null
-      };
+      if (result.status === 0) {
+        return {
+          success: true,
+          error: null
+        };
+      } else {
+        // If elevated installation failed, try user-space installation
+        this.log('warn', `Elevated installation failed, trying user-space installation...`);
+        this.permissionMode = 'user-space';
+        return await this.executeUserSpaceInstallation(toolInfo);
+      }
     } catch (error) {
-      return { success: false, error: error.message };
+      // If elevated installation failed, try user-space installation
+      this.log('warn', `Elevated installation failed (${error.message}), trying user-space installation...`);
+      this.permissionMode = 'user-space';
+      return await this.executeUserSpaceInstallation(toolInfo);
     }
   }
 
@@ -490,15 +590,21 @@ class EnhancedCLIInstaller {
    * Execute Unix elevated installation
    */
   async executeUnixElevatedInstallation(toolInfo) {
-    const permissionSetup = await this.setupPermissions();
+    // Use the detected privilege escalation tool
+    const privilegeSetup = await this.setupUnixElevatedContext();
+
+    if (!privilegeSetup.success) {
+      this.log('warn', 'No privilege escalation tool available, using user-space installation...');
+      return await this.executeUserSpaceInstallation(toolInfo);
+    }
 
     // If no privilege escalation tool is available, use user-space installation
-    if (permissionSetup.userSpaceOnly) {
+    if (privilegeSetup.userSpaceOnly) {
       return await this.executeUserSpaceInstallation(toolInfo);
     }
 
     // Use the detected privilege escalation tool
-    const privilegeTool = permissionSetup.privilegeTool || 'sudo';
+    const privilegeTool = privilegeSetup.privilegeTool || 'sudo';
     const command = `${privilegeTool} ${toolInfo.install}`;
 
     try {
@@ -660,9 +766,22 @@ class EnhancedCLIInstaller {
       if (result.status === 0) {
         return { success: true, error: null };
       } else {
-        return { success: false, error: `Fallback failed: ${result.stderr}` };
+        const errorMessage = result.stderr || `Fallback failed with exit code ${result.status}`;
+        // If fallback failed due to permissions, try user-space installation
+        if (this.isPermissionError(errorMessage)) {
+          this.log('warn', `Fallback installation failed due to permission error, switching to user-space installation...`);
+          this.permissionMode = 'user-space';
+          return await this.executeUserSpaceInstallation(toolInfo);
+        }
+        return { success: false, error: errorMessage };
       }
     } catch (error) {
+      // If fallback failed due to permissions, try user-space installation
+      if (this.isPermissionError(error.message)) {
+        this.log('warn', `Fallback installation failed due to permission error, switching to user-space installation...`);
+        this.permissionMode = 'user-space';
+        return await this.executeUserSpaceInstallation(toolInfo);
+      }
       return { success: false, error: error.message };
     }
   }
@@ -769,9 +888,21 @@ class EnhancedCLIInstaller {
         continue;
       }
 
+      // Determine the appropriate upgrade command based on permission mode
+      let upgradeCommand;
+      if (this.permissionMode === 'user-space') {
+        // For user-space installations, upgrade to user directory
+        const os = require('os');
+        const path = require('path');
+        let userNpmDir = process.env.NPM_CONFIG_PREFIX || path.join(os.homedir(), '.npm-global');
+        upgradeCommand = `npm install -g --prefix "${userNpmDir}" ${toolName}`;
+      } else {
+        upgradeCommand = `npm upgrade -g ${toolName}`;
+      }
+
       const toolInfo = {
         ...originalInfo,
-        install: `npm upgrade -g ${toolName}`,
+        install: upgradeCommand,
         name: `${originalInfo.name} (Upgrade)`
       };
 
@@ -896,7 +1027,17 @@ class EnhancedCLIInstaller {
       return false;
     }
 
-    const upgradeCommand = `npm upgrade -g ${toolName}`;
+    // Determine the appropriate upgrade command based on permission mode
+    let upgradeCommand;
+    if (this.permissionMode === 'user-space') {
+      // For user-space installations, upgrade to user directory
+      const os = require('os');
+      const path = require('path');
+      let userNpmDir = process.env.NPM_CONFIG_PREFIX || path.join(os.homedir(), '.npm-global');
+      upgradeCommand = `npm install -g --prefix "${userNpmDir}" ${toolName}`;
+    } else {
+      upgradeCommand = `npm upgrade -g ${toolName}`;
+    }
 
     this.results.installations[toolName] = {
       startTime: Date.now(),