agileflow 2.91.0 → 2.92.0

package/lib/validate-commands.js

@@ -0,0 +1,308 @@
+/**
+ * validate-commands.js - Command Validation for Shell Execution
+ *
+ * Validates and sanitizes commands before shell execution to prevent
+ * command injection attacks. Uses allowlist approach for safe commands
+ * and rejects dangerous shell metacharacters.
+ *
+ * Usage:
+ *   const { validateCommand, ALLOWED_COMMANDS } = require('./validate-commands');
+ *
+ *   const result = validateCommand('npm test');
+ *   if (result.ok) {
+ *     // Safe to execute
+ *     const { command, args } = result.data;
+ *   } else {
+ *     console.error(result.error);
+ *   }
+ */
+
+const { debugLog, sanitizeForShell } = require('./errors');
+
+/**
+ * Allowed command prefixes for agent-loop execution
+ * These are the only commands that can be executed
+ */
+const ALLOWED_COMMANDS = {
+  // Package managers
+  npm: ['test', 'run', 'run-script'],
+  npx: ['jest', 'tsc', 'eslint', 'prettier', 'playwright', 'vitest'],
+  yarn: ['test', 'run'],
+  pnpm: ['test', 'run'],
+  bun: ['test', 'run'],
+
+  // Direct test runners (for projects not using npm scripts)
+  jest: true, // Allow all jest args
+  vitest: true,
+  mocha: true,
+  playwright: ['test'],
+
+  // Build tools
+  tsc: ['--noEmit', '--build', '-b'],
+
+  // Linters
+  eslint: true,
+  prettier: ['--check', '--write'],
+};
+
+/**
+ * Dangerous shell metacharacters that could enable injection
+ */
+const DANGEROUS_PATTERNS = [
+  /[;&|`$(){}]/g, // Shell operators, substitution
+  /\$\{/g, // Variable expansion
+  /\$\(/g, // Command substitution
+  /`[^`]*`/g, // Backtick substitution
+  />\s/g, // Redirection
+  /<\s/g, // Input redirection
+  /\n/g, // Newlines (could chain commands)
+  /\r/g, // Carriage return
+  /\\$/g, // Line continuation
+];
+
+/**
+ * Parse a command string into executable and arguments
+ * @param {string} cmdString - Full command string
+ * @returns {{ executable: string, args: string[] }}
+ */
+function parseCommand(cmdString) {
+  // Handle quoted arguments properly
+  const parts = [];
+  let current = '';
+  let inQuote = null;
+
+  for (let i = 0; i < cmdString.length; i++) {
+    const char = cmdString[i];
+
+    if (inQuote) {
+      if (char === inQuote) {
+        inQuote = null;
+      } else {
+        current += char;
+      }
+    } else if (char === '"' || char === "'") {
+      inQuote = char;
+    } else if (char === ' ' || char === '\t') {
+      if (current) {
+        parts.push(current);
+        current = '';
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) {
+    parts.push(current);
+  }
+
+  return {
+    executable: parts[0] || '',
+    args: parts.slice(1),
+  };
+}
+
+/**
+ * Check if an argument contains dangerous patterns
+ * @param {string} arg - Argument to check
+ * @returns {{ safe: boolean, pattern?: string }}
+ */
+function checkArgSafety(arg) {
+  for (const pattern of DANGEROUS_PATTERNS) {
+    if (pattern.test(arg)) {
+      return { safe: false, pattern: pattern.source };
+    }
+  }
+  return { safe: true };
+}
+
+/**
+ * Validate a command against the allowlist
+ * @param {string} cmdString - Full command string to validate
+ * @param {Object} [options={}] - Validation options
+ * @param {boolean} [options.strict=true] - Require command in allowlist
+ * @param {boolean} [options.logBlocked=true] - Log blocked commands
+ * @returns {{ ok: boolean, data?: { command: string, args: string[] }, error?: string, severity?: string }}
+ */
+function validateCommand(cmdString, options = {}) {
+  const { strict = true, logBlocked = true } = options;
+
+  // Must be a string
+  if (typeof cmdString !== 'string') {
+    return {
+      ok: false,
+      error: `Command must be a string, got ${typeof cmdString}`,
+      severity: 'high',
+    };
+  }
+
+  // Trim and check for empty
+  const trimmed = cmdString.trim();
+  if (!trimmed) {
+    return {
+      ok: false,
+      error: 'Command cannot be empty',
+      severity: 'medium',
+    };
+  }
+
+  // Parse the command
+  const { executable, args } = parseCommand(trimmed);
+
+  if (!executable) {
+    return {
+      ok: false,
+      error: 'No executable found in command',
+      severity: 'medium',
+    };
+  }
+
+  // Check executable against allowlist
+  const allowedSubcommands = ALLOWED_COMMANDS[executable];
+
+  if (strict && !allowedSubcommands) {
+    const error = `Command '${executable}' not in allowlist. Allowed: ${Object.keys(ALLOWED_COMMANDS).join(', ')}`;
+    if (logBlocked) {
+      debugLog('validateCommand', {
+        blocked: true,
+        command: executable,
+        reason: 'not_in_allowlist',
+      });
+    }
+    return {
+      ok: false,
+      error,
+      severity: 'high',
+    };
+  }
+
+  // If allowedSubcommands is an array, check the first argument
+  if (Array.isArray(allowedSubcommands) && args.length > 0) {
+    const subcommand = args[0];
+    if (!allowedSubcommands.includes(subcommand)) {
+      const error = `Subcommand '${subcommand}' not allowed for '${executable}'. Allowed: ${allowedSubcommands.join(', ')}`;
+      if (logBlocked) {
+        debugLog('validateCommand', {
+          blocked: true,
+          command: `${executable} ${subcommand}`,
+          reason: 'subcommand_not_allowed',
+        });
+      }
+      return {
+        ok: false,
+        error,
+        severity: 'high',
+      };
+    }
+  }
+
+  // Check all arguments for dangerous patterns
+  for (const arg of args) {
+    const argCheck = checkArgSafety(arg);
+    if (!argCheck.safe) {
+      const error = `Dangerous pattern in argument: '${arg}' matches ${argCheck.pattern}`;
+      if (logBlocked) {
+        debugLog('validateCommand', {
+          blocked: true,
+          command: executable,
+          arg,
+          pattern: argCheck.pattern,
+          reason: 'dangerous_pattern',
+        });
+      }
+      return {
+        ok: false,
+        error,
+        severity: 'critical',
+      };
+    }
+  }
+
+  // Additional check with sanitizeForShell for the full command
+  const fullCmdCheck = sanitizeForShell(trimmed, { context: 'command' });
+  if (!fullCmdCheck.ok) {
+    if (logBlocked) {
+      debugLog('validateCommand', {
+        blocked: true,
+        command: trimmed.slice(0, 50),
+        reason: 'shell_unsafe',
+        detected: fullCmdCheck.detected,
+      });
+    }
+    return {
+      ok: false,
+      error: fullCmdCheck.error,
+      severity: 'critical',
+    };
+  }
+
+  return {
+    ok: true,
+    data: {
+      command: executable,
+      args,
+    },
+  };
+}
+
+/**
+ * Build a safe command array for spawn()
+ * @param {string} cmdString - Command string
+ * @param {Object} [options={}] - Options
+ * @returns {{ ok: boolean, data?: { file: string, args: string[] }, error?: string }}
+ */
+function buildSpawnArgs(cmdString, options = {}) {
+  const validation = validateCommand(cmdString, options);
+
+  if (!validation.ok) {
+    return validation;
+  }
+
+  return {
+    ok: true,
+    data: {
+      file: validation.data.command,
+      args: validation.data.args,
+    },
+  };
+}
+
+/**
+ * Check if a command would be allowed (without modifying)
+ * @param {string} cmdString - Command to check
+ * @returns {boolean}
+ */
+function isAllowedCommand(cmdString) {
+  return validateCommand(cmdString, { logBlocked: false }).ok;
+}
+
+/**
+ * Get a list of all allowed command patterns
+ * @returns {string[]}
+ */
+function getAllowedCommandList() {
+  const list = [];
+
+  for (const [exe, subcommands] of Object.entries(ALLOWED_COMMANDS)) {
+    if (subcommands === true) {
+      list.push(`${exe} *`);
+    } else if (Array.isArray(subcommands)) {
+      for (const sub of subcommands) {
+        list.push(`${exe} ${sub}`);
+      }
+    }
+  }
+
+  return list;
+}
+
+module.exports = {
+  ALLOWED_COMMANDS,
+  DANGEROUS_PATTERNS,
+  validateCommand,
+  buildSpawnArgs,
+  isAllowedCommand,
+  getAllowedCommandList,
+  parseCommand,
+  checkArgSafety,
+};

package/lib/validate.js

@@ -4,67 +4,131 @@
  * Centralized validation patterns and helpers to prevent
  * command injection, path traversal, and invalid input handling.
  *
- * This module re-exports from split validation modules for backward compatibility.
- * For better performance, import directly from:
- *   - validate-names.js - Name/ID validation patterns
- *   - validate-args.js  - CLI argument validation
- *   - validate-paths.js - Path traversal protection
+ * Usage patterns:
+ *
+ * 1. Namespace import (recommended - clear, discoverable):
+ *    const { names, args, paths, commands } = require('./validate');
+ *    names.isValidStoryId('US-0001')
+ *    paths.validatePath('/some/path')
+ *    args.validateArgs(schema, input)
+ *
+ * 2. Flat import (backwards compatible):
+ *    const { isValidStoryId, validatePath } = require('./validate');
+ *
+ * 3. Direct import (best performance):
+ *    const { isValidStoryId } = require('./validate-names');
+ *    const { validatePath } = require('./validate-paths');
  */
 
-// Re-export name validators
-const {
-  PATTERNS,
-  isValidBranchName,
-  isValidStoryId,
-  isValidEpicId,
-  isValidFeatureName,
-  isValidProfileName,
-  isValidCommandName,
-  isValidSessionNickname,
-  isValidMergeStrategy,
-} = require('./validate-names');
+// Import all validators
+const validateNames = require('./validate-names');
+const validateArgs = require('./validate-args');
+const validatePaths = require('./validate-paths');
+const validateCommands = require('./validate-commands');
 
-// Re-export argument validators
-const {
-  isPositiveInteger,
-  parseIntBounded,
-  isValidOption,
-  validateArgs,
-} = require('./validate-args');
+// ============================================================================
+// Namespace exports (recommended for new code)
+// ============================================================================
 
-// Re-export path validators
-const {
-  PathValidationError,
-  checkSymlinkChainDepth,
-  validatePath,
-  validatePathSync,
-  hasUnsafePathPatterns,
-  sanitizeFilename,
-} = require('./validate-paths');
+/**
+ * Name/ID validation namespace
+ * @namespace names
+ */
+const names = {
+  PATTERNS: validateNames.PATTERNS,
+  isValidBranchName: validateNames.isValidBranchName,
+  isValidStoryId: validateNames.isValidStoryId,
+  isValidEpicId: validateNames.isValidEpicId,
+  isValidFeatureName: validateNames.isValidFeatureName,
+  isValidProfileName: validateNames.isValidProfileName,
+  isValidCommandName: validateNames.isValidCommandName,
+  isValidSessionNickname: validateNames.isValidSessionNickname,
+  isValidMergeStrategy: validateNames.isValidMergeStrategy,
+};
+
+/**
+ * CLI argument validation namespace
+ * @namespace args
+ */
+const args = {
+  isPositiveInteger: validateArgs.isPositiveInteger,
+  parseIntBounded: validateArgs.parseIntBounded,
+  isValidOption: validateArgs.isValidOption,
+  validateArgs: validateArgs.validateArgs,
+};
+
+/**
+ * Path traversal protection namespace
+ * @namespace paths
+ */
+const paths = {
+  PathValidationError: validatePaths.PathValidationError,
+  checkSymlinkChainDepth: validatePaths.checkSymlinkChainDepth,
+  validatePath: validatePaths.validatePath,
+  validatePathSync: validatePaths.validatePathSync,
+  hasUnsafePathPatterns: validatePaths.hasUnsafePathPatterns,
+  sanitizeFilename: validatePaths.sanitizeFilename,
+};
+
+/**
+ * Command validation namespace
+ * @namespace commands
+ */
+const commands = {
+  ALLOWED_COMMANDS: validateCommands.ALLOWED_COMMANDS,
+  DANGEROUS_PATTERNS: validateCommands.DANGEROUS_PATTERNS,
+  validateCommand: validateCommands.validateCommand,
+  buildSpawnArgs: validateCommands.buildSpawnArgs,
+  isAllowedCommand: validateCommands.isAllowedCommand,
+  getAllowedCommandList: validateCommands.getAllowedCommandList,
+  parseCommand: validateCommands.parseCommand,
+  checkArgSafety: validateCommands.checkArgSafety,
+};
+
+// ============================================================================
+// Flat exports (backwards compatible)
+// ============================================================================
 
 module.exports = {
+  // Namespaces (recommended for new code)
+  names,
+  args,
+  paths,
+  commands,
+
+  // Flat exports (backwards compatible)
   // Patterns and basic validators (from validate-names.js)
-  PATTERNS,
-  isValidBranchName,
-  isValidStoryId,
-  isValidEpicId,
-  isValidFeatureName,
-  isValidProfileName,
-  isValidCommandName,
-  isValidSessionNickname,
-  isValidMergeStrategy,
+  PATTERNS: validateNames.PATTERNS,
+  isValidBranchName: validateNames.isValidBranchName,
+  isValidStoryId: validateNames.isValidStoryId,
+  isValidEpicId: validateNames.isValidEpicId,
+  isValidFeatureName: validateNames.isValidFeatureName,
+  isValidProfileName: validateNames.isValidProfileName,
+  isValidCommandName: validateNames.isValidCommandName,
+  isValidSessionNickname: validateNames.isValidSessionNickname,
+  isValidMergeStrategy: validateNames.isValidMergeStrategy,
 
   // Argument validators (from validate-args.js)
-  isPositiveInteger,
-  parseIntBounded,
-  isValidOption,
-  validateArgs,
+  isPositiveInteger: validateArgs.isPositiveInteger,
+  parseIntBounded: validateArgs.parseIntBounded,
+  isValidOption: validateArgs.isValidOption,
+  validateArgs: validateArgs.validateArgs,
 
   // Path traversal protection (from validate-paths.js)
-  PathValidationError,
-  validatePath,
-  validatePathSync,
-  hasUnsafePathPatterns,
-  sanitizeFilename,
-  checkSymlinkChainDepth,
+  PathValidationError: validatePaths.PathValidationError,
+  validatePath: validatePaths.validatePath,
+  validatePathSync: validatePaths.validatePathSync,
+  hasUnsafePathPatterns: validatePaths.hasUnsafePathPatterns,
+  sanitizeFilename: validatePaths.sanitizeFilename,
+  checkSymlinkChainDepth: validatePaths.checkSymlinkChainDepth,
+
+  // Command validation (from validate-commands.js)
+  ALLOWED_COMMANDS: validateCommands.ALLOWED_COMMANDS,
+  DANGEROUS_PATTERNS: validateCommands.DANGEROUS_PATTERNS,
+  validateCommand: validateCommands.validateCommand,
+  buildSpawnArgs: validateCommands.buildSpawnArgs,
+  isAllowedCommand: validateCommands.isAllowedCommand,
+  getAllowedCommandList: validateCommands.getAllowedCommandList,
+  parseCommand: validateCommands.parseCommand,
+  checkArgSafety: validateCommands.checkArgSafety,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.91.0",
+  "version": "2.92.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/af

@@ -0,0 +1,34 @@
+#!/bin/bash
+# af - Short alias for Claude Code with tmux integration
+#
+# This is a convenience wrapper that:
+# 1. Auto-starts Claude in a tmux session (for parallel sessions support)
+# 2. Attaches to existing session if one exists for this directory
+# 3. Falls back to regular claude if tmux isn't available
+#
+# Usage:
+#   af              # Start Claude in tmux
+#   af --no-tmux    # Start without tmux
+#   af -h           # Show help
+#
+# To install globally:
+#   sudo ln -s $(pwd)/.agileflow/scripts/af /usr/local/bin/af
+#   # Or add to your PATH
+
+set -e
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Check if claude-tmux.sh exists in the same directory
+if [ -f "$SCRIPT_DIR/claude-tmux.sh" ]; then
+  exec "$SCRIPT_DIR/claude-tmux.sh" "$@"
+fi
+
+# Fallback: try to find claude-tmux.sh in .agileflow/scripts
+if [ -f ".agileflow/scripts/claude-tmux.sh" ]; then
+  exec ".agileflow/scripts/claude-tmux.sh" "$@"
+fi
+
+# Last resort: just run claude directly
+exec claude "$@"

package/scripts/agent-loop.js

@@ -25,7 +25,14 @@ const crypto = require('crypto');
 // Shared utilities
 const { c } = require('../lib/colors');
 const { getProjectRoot } = require('../lib/paths');
-const { safeReadJSON, safeWriteJSON } = require('../lib/errors');
+const { safeReadJSON, safeWriteJSON, debugLog } = require('../lib/errors');
+const { validateCommand, buildSpawnArgs } = require('../lib/validate-commands');
+const {
+  initializeForProject,
+  injectCorrelation,
+  startSpan,
+  getContext,
+} = require('../lib/correlation');
 
 const ROOT = getProjectRoot();
 const LOOPS_DIR = path.join(ROOT, '.agileflow', 'sessions', 'agent-loops');
@@ -85,11 +92,13 @@ function emitEvent(event) {
     fs.mkdirSync(busDir, { recursive: true });
   }
 
-  const line =
-    JSON.stringify({
-      ...event,
-      timestamp: new Date().toISOString(),
-    }) + '\n';
+  // Inject correlation IDs (trace_id, session_id, span_id)
+  const correlatedEvent = injectCorrelation({
+    ...event,
+    timestamp: new Date().toISOString(),
+  });
+
+  const line = JSON.stringify(correlatedEvent) + '\n';
 
   fs.appendFileSync(BUS_PATH, line);
 }
@@ -128,12 +137,51 @@ function getCoverageReportPath() {
   return 'coverage/coverage-summary.json';
 }
 
+/**
+ * Run a command safely using spawn with validated arguments
+ * @param {string} cmd - Command string to run
+ * @returns {{ passed: boolean, exitCode: number, error?: string, blocked?: boolean }}
+ */
 function runCommand(cmd) {
+  // Validate command against allowlist
+  const validation = buildSpawnArgs(cmd, { strict: true, logBlocked: true });
+
+  if (!validation.ok) {
+    console.error(
+      `${c.red}Command blocked: ${validation.error}${c.reset}` +
+        (validation.severity ? ` [${validation.severity}]` : '')
+    );
+    debugLog('runCommand', {
+      blocked: true,
+      command: cmd.slice(0, 50),
+      error: validation.error,
+      severity: validation.severity,
+    });
+    return { passed: false, exitCode: 1, error: validation.error, blocked: true };
+  }
+
+  const { file, args } = validation.data;
+
   try {
-    execSync(cmd, { cwd: ROOT, stdio: 'inherit' });
-    return { passed: true, exitCode: 0 };
+    // Use spawnSync with array arguments (no shell injection possible)
+    const result = spawnSync(file, args, {
+      cwd: ROOT,
+      stdio: 'inherit',
+      shell: false, // CRITICAL: Do not use shell to prevent injection
+    });
+
+    if (result.error) {
+      // spawn itself failed (e.g., command not found)
+      console.error(`${c.red}Spawn error: ${result.error.message}${c.reset}`);
+      return { passed: false, exitCode: 1, error: result.error.message };
+    }
+
+    return {
+      passed: result.status === 0,
+      exitCode: result.status || 0,
+    };
   } catch (error) {
-    return { passed: false, exitCode: error.status || 1 };
+    return { passed: false, exitCode: error.status || 1, error: error.message };
   }
 }
 
@@ -265,6 +313,9 @@ function initLoop(options) {
     parentId = null,
   } = options;
 
+  // Initialize correlation context (trace_id, session_id)
+  const { traceId, sessionId } = initializeForProject(ROOT);
+
   // Validate gate
   if (!GATES[gate]) {
     console.error(`${c.red}Invalid gate: ${gate}${c.reset}`);
@@ -295,6 +346,8 @@ function initLoop(options) {
 
   const state = {
     loop_id: loopId,
+    trace_id: traceId,
+    session_id: sessionId,
     agent_type: agentType,
     parent_orchestration: parentId,
     quality_gate: gate,
@@ -324,6 +377,7 @@ function initLoop(options) {
   console.log(`${c.green}${c.bold}Agent Loop Initialized${c.reset}`);
   console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
   console.log(`  Loop ID: ${c.cyan}${loopId}${c.reset}`);
+  console.log(`  Trace ID: ${c.dim}${traceId}${c.reset}`);
   console.log(`  Gate: ${c.magenta}${GATES[gate].name}${c.reset}`);
   console.log(`  Threshold: ${threshold > 0 ? threshold + '%' : 'pass/fail'}`);
   console.log(`  Max Iterations: ${maxIter}`);

package/scripts/agileflow-configure.js

@@ -23,7 +23,7 @@
  *   --detect                            Show current status
  *   --help                              Show help
  *
- * Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate, damagecontrol, askuserquestion
+ * Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate, damagecontrol, askuserquestion, tmuxautospawn
  */
 
 const fs = require('fs');
@@ -130,7 +130,7 @@ ${c.cyan}Feature Control:${c.reset}
   --enable=<list>     Enable features (comma-separated)
   --disable=<list>    Disable features (comma-separated)
 
-  Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, damagecontrol, askuserquestion
+  Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, damagecontrol, askuserquestion, tmuxautospawn
 
 ${c.cyan}Statusline Components:${c.reset}
   --show=<list>       Show statusline components (comma-separated)