agileflow 2.92.0 → 2.93.0

package/scripts/lib/configure-features.js

@@ -65,7 +65,14 @@ const PROFILES = {
   minimal: {
     description: 'SessionStart + archival only',
     enable: ['sessionstart', 'archival'],
-    disable: ['precompact', 'statusline', 'ralphloop', 'selfimprove', 'askuserquestion', 'tmuxautospawn'],
+    disable: [
+      'precompact',
+      'statusline',
+      'ralphloop',
+      'selfimprove',
+      'askuserquestion',
+      'tmuxautospawn',
+    ],
     archivalDays: 30,
   },
   none: {

package/scripts/lib/context-loader.js

@@ -63,22 +63,22 @@ const SAFEEXEC_ALLOWED_COMMANDS = [
  * Dangerous patterns that should never be executed
  */
 const SAFEEXEC_BLOCKED_PATTERNS = [
-  /\|/,         // Pipe
-  /;/,          // Command separator
-  /&&/,         // AND operator
-  /\|\|/,       // OR operator
-  /`/,          // Backticks
-  /\$\(/,       // Command substitution
-  />/,          // Redirect output
-  /</,          // Redirect input
-  /\bsudo\b/,   // Sudo
-  /\brm\b/,     // Remove
-  /\bmv\b/,     // Move
-  /\bcp\b/,     // Copy
-  /\bchmod\b/,  // Change permissions
-  /\bchown\b/,  // Change owner
-  /\bcurl\b/,   // curl (network)
-  /\bwget\b/,   // wget (network)
+  /\|/, // Pipe
+  /;/, // Command separator
+  /&&/, // AND operator
+  /\|\|/, // OR operator
+  /`/, // Backticks
+  /\$\(/, // Command substitution
+  />/, // Redirect output
+  /</, // Redirect input
+  /\bsudo\b/, // Sudo
+  /\brm\b/, // Remove
+  /\bmv\b/, // Move
+  /\bcp\b/, // Copy
+  /\bchmod\b/, // Change permissions
+  /\bchown\b/, // Change owner
+  /\bcurl\b/, // curl (network)
+  /\bwget\b/, // wget (network)
 ];
 
 /**

package/scripts/query-codebase.js

@@ -114,7 +114,7 @@ function explainWorkflow(queryType, queryValue, projectRoot) {
       lines.push('# This tool adds: index awareness, budget truncation, structured output.');
       break;
 
-    case 'tag':
+    case 'tag': {
       const tagPatterns = {
         api: '/api/|/routes/|/controllers/',
         ui: '/components/|/views/|/pages/',
@@ -123,10 +123,13 @@ function explainWorkflow(queryType, queryValue, projectRoot) {
         test: '/test/|/__tests__/|/spec/',
       };
       lines.push('# Equivalent to find with path patterns:');
-      lines.push(`find ${projectRoot} -type f | grep -E "${tagPatterns[queryValue] || queryValue}"`);
+      lines.push(
+        `find ${projectRoot} -type f | grep -E "${tagPatterns[queryValue] || queryValue}"`
+      );
       lines.push('');
       lines.push('# This tool uses pre-indexed tags for instant lookup.');
       break;
+    }
 
     case 'export':
       lines.push('# Equivalent to grep for export statements:');
@@ -140,7 +143,9 @@ function explainWorkflow(queryType, queryValue, projectRoot) {
       lines.push(`grep -n "import.*from" ${queryValue}`);
       lines.push('');
       lines.push('# Plus reverse search for files importing this one:');
-      lines.push(`grep -rl "${path.basename(queryValue, path.extname(queryValue))}" ${projectRoot}/src/`);
+      lines.push(
+        `grep -rl "${path.basename(queryValue, path.extname(queryValue))}" ${projectRoot}/src/`
+      );
       lines.push('');
       lines.push('# This tool tracks bidirectional dependencies in index.');
       break;

package/scripts/session-manager.js

@@ -11,11 +11,16 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync, spawnSync } = require('child_process');
+const { execSync, spawnSync, spawn } = require('child_process');
 
 // Shared utilities
 const { c } = require('../lib/colors');
-const { getProjectRoot, getStatusPath, getSessionStatePath, getAgileflowDir } = require('../lib/paths');
+const {
+  getProjectRoot,
+  getStatusPath,
+  getSessionStatePath,
+  getAgileflowDir,
+} = require('../lib/paths');
 const { safeReadJSON } = require('../lib/errors');
 const { isValidBranchName, isValidSessionNickname } = require('../lib/validate');
 
@@ -226,6 +231,161 @@ async function cleanupStaleLocksAsync(registry, options = {}) {
   return { count: cleanedSessions.length, sessions: cleanedSessions };
 }
 
+/**
+ * Get detailed file information for a session's changes
+ * @param {string} sessionPath - Path to session worktree
+ * @param {string[]} changes - Array of git status lines
+ * @returns {Object[]} Array of file details with analysis
+ */
+function getFileDetails(sessionPath, changes) {
+  return changes.map((change) => {
+    const status = change.substring(0, 2).trim();
+    const file = change.substring(3);
+
+    const detail = { status, file, trivial: false, existsInMain: false, diffLines: 0 };
+
+    // For modified files, get diff stats
+    if (status === 'M') {
+      try {
+        const diffStat = spawnSync('git', ['diff', '--numstat', file], {
+          cwd: sessionPath,
+          encoding: 'utf8',
+          timeout: 3000,
+        });
+        if (diffStat.stdout) {
+          const parts = diffStat.stdout.trim().split('\t');
+          const added = parseInt(parts[0], 10) || 0;
+          const removed = parseInt(parts[1], 10) || 0;
+          detail.diffLines = added + removed;
+          // Trivial if only 1-2 lines changed (likely whitespace)
+          detail.trivial = detail.diffLines <= 2;
+        }
+      } catch (e) {
+        // Can't get diff, assume not trivial
+      }
+    }
+
+    // For untracked files, check if exists in main
+    if (status === '??') {
+      detail.existsInMain = fs.existsSync(path.join(ROOT, file));
+      // Trivial if it's a duplicate
+      detail.trivial = detail.existsInMain;
+    }
+
+    // Config/cache files are trivial
+    if (file.includes('.claude/') || file.includes('.agileflow/cache')) {
+      detail.trivial = true;
+    }
+
+    return detail;
+  });
+}
+
+/**
+ * Get health status for all sessions
+ * Detects: stale sessions, uncommitted changes, orphaned entries
+ * @param {Object} options - { staleDays: 7, detailed: false }
+ * @returns {Object} Health report
+ */
+function getSessionsHealth(options = {}) {
+  const { staleDays = 7, detailed = false } = options;
+  const registry = loadRegistry();
+  const now = Date.now();
+  const staleThreshold = staleDays * 24 * 60 * 60 * 1000;
+
+  const health = {
+    stale: [],           // Sessions with no activity > staleDays
+    uncommitted: [],     // Sessions with uncommitted git changes
+    orphanedRegistry: [], // Registry entries where path doesn't exist
+    orphanedWorktrees: [], // Worktrees not in registry
+    healthy: 0,
+  };
+
+  // Check each registered session
+  for (const [id, session] of Object.entries(registry.sessions)) {
+    if (session.is_main) continue; // Skip main session
+
+    const age = now - new Date(session.last_active).getTime();
+    const pathExists = fs.existsSync(session.path);
+
+    // Check for orphaned registry entry (path missing)
+    if (!pathExists) {
+      health.orphanedRegistry.push({ id, ...session, reason: 'path_missing' });
+      continue;
+    }
+
+    // Check for stale session
+    if (age > staleThreshold) {
+      health.stale.push({
+        id,
+        ...session,
+        ageDays: Math.floor(age / (24 * 60 * 60 * 1000)),
+      });
+    }
+
+    // Check for uncommitted changes
+    try {
+      const result = spawnSync('git', ['status', '--porcelain'], {
+        cwd: session.path,
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+      if (result.stdout && result.stdout.trim()) {
+        // Don't use trim() on the whole string - it removes leading space from first status
+        // Split by newline and filter empty lines instead
+        const changes = result.stdout.split('\n').filter((line) => line.length > 0);
+        const sessionData = {
+          id,
+          ...session,
+          changeCount: changes.length,
+          changes: detailed ? changes : changes.slice(0, 5), // All or first 5
+        };
+
+        // Add detailed file analysis if requested
+        if (detailed) {
+          sessionData.fileDetails = getFileDetails(session.path, changes);
+          // Calculate if session is safe to delete (all changes trivial)
+          sessionData.allTrivial = sessionData.fileDetails.every((f) => f.trivial);
+        }
+
+        health.uncommitted.push(sessionData);
+      } else {
+        health.healthy++;
+      }
+    } catch (e) {
+      // Can't check, skip
+    }
+  }
+
+  // Check for orphaned worktrees (directories not in registry)
+  try {
+    const worktreeList = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+      encoding: 'utf8',
+    });
+    if (worktreeList.stdout) {
+      const worktrees = worktreeList.stdout
+        .split('\n')
+        .filter((line) => line.startsWith('worktree '))
+        .map((line) => line.replace('worktree ', ''));
+
+      const mainPath = ROOT;
+      for (const wtPath of worktrees) {
+        const inRegistry = Object.values(registry.sessions).some((s) => s.path === wtPath);
+        if (!inRegistry && wtPath !== mainPath) {
+          // Check if it's an AgileFlow worktree (has .agileflow folder)
+          if (fs.existsSync(path.join(wtPath, '.agileflow'))) {
+            health.orphanedWorktrees.push({ path: wtPath });
+          }
+        }
+      }
+    }
+  } catch (e) {
+    // Can't list worktrees, skip
+  }
+
+  return health;
+}
+
 // Git command cache (10 second TTL to avoid stale data)
 const gitCache = {
   data: new Map(),
@@ -380,8 +540,165 @@ function getSession(sessionId) {
   };
 }
 
+// Default worktree timeout (2 minutes)
+const DEFAULT_WORKTREE_TIMEOUT_MS = 120000;
+
+/**
+ * Display progress feedback during long operations.
+ * Returns a function to stop the progress indicator.
+ *
+ * @param {string} message - Progress message
+ * @returns {function} Stop function
+ */
+function progressIndicator(message) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let frameIndex = 0;
+  let elapsed = 0;
+
+  // For TTY (interactive terminal), show spinner
+  if (process.stderr.isTTY) {
+    const interval = setInterval(() => {
+      process.stderr.write(`\r${frames[frameIndex++ % frames.length]} ${message}`);
+    }, 80);
+    return () => {
+      clearInterval(interval);
+      process.stderr.write(`\r${' '.repeat(message.length + 2)}\r`);
+    };
+  }
+
+  // For non-TTY (Claude Code, piped output), emit periodic updates to stderr
+  process.stderr.write(`⏳ ${message}...\n`);
+  const interval = setInterval(() => {
+    elapsed += 10;
+    process.stderr.write(`⏳ Still working... (${elapsed}s elapsed)\n`);
+  }, 10000); // Update every 10 seconds
+
+  return () => {
+    clearInterval(interval);
+  };
+}
+
+/**
+ * Create a git worktree with timeout and progress feedback.
+ * Uses async spawn instead of spawnSync for timeout support.
+ *
+ * @param {string} worktreePath - Path for the new worktree
+ * @param {string} branchName - Branch name for the worktree
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+function createWorktreeWithTimeout(
+  worktreePath,
+  branchName,
+  timeoutMs = DEFAULT_WORKTREE_TIMEOUT_MS
+) {
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const proc = spawn('git', ['worktree', 'add', worktreePath, branchName], {
+      cwd: ROOT,
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill('SIGTERM');
+      // Give it a moment to terminate gracefully, then SIGKILL
+      setTimeout(() => {
+        try {
+          proc.kill('SIGKILL');
+        } catch (e) {
+          // Process may have already exited
+        }
+      }, 1000);
+    }, timeoutMs);
+
+    proc.stdout.on('data', data => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', data => {
+      stderr += data.toString();
+    });
+
+    proc.on('error', err => {
+      clearTimeout(timer);
+      reject(new Error(`Failed to spawn git: ${err.message}`));
+    });
+
+    proc.on('close', (code, signal) => {
+      clearTimeout(timer);
+
+      if (timedOut) {
+        reject(
+          new Error(
+            `Worktree creation timed out after ${timeoutMs / 1000}s. Try increasing timeout or check disk space.`
+          )
+        );
+        return;
+      }
+
+      if (signal) {
+        reject(new Error(`Worktree creation was terminated by signal: ${signal}`));
+        return;
+      }
+
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        reject(new Error(`Failed to create worktree: ${stderr || 'unknown error'}`));
+      }
+    });
+  });
+}
+
+/**
+ * Clean up partial state after failed worktree creation.
+ * Removes partial directory and prunes git worktree registry.
+ *
+ * @param {string} worktreePath - Path of the failed worktree
+ * @param {string} branchName - Branch name that was being used
+ * @param {boolean} branchCreatedByUs - Whether we created the branch
+ */
+function cleanupFailedWorktree(worktreePath, branchName, branchCreatedByUs = false) {
+  // Remove partial worktree directory if it exists
+  if (fs.existsSync(worktreePath)) {
+    try {
+      fs.rmSync(worktreePath, { recursive: true, force: true });
+      process.stderr.write(`🧹 Cleaned up partial worktree directory\n`);
+    } catch (e) {
+      process.stderr.write(`⚠️  Could not remove partial directory: ${e.message}\n`);
+    }
+  }
+
+  // Prune git worktree registry to clean up any references
+  try {
+    spawnSync('git', ['worktree', 'prune'], { cwd: ROOT, encoding: 'utf8' });
+  } catch (e) {
+    // Non-fatal
+  }
+
+  // If we created the branch and the worktree failed, optionally clean up the branch too
+  // But only if it has no commits beyond the parent (i.e., we just created it)
+  if (branchCreatedByUs) {
+    try {
+      // Check if branch exists and has no unique commits
+      const result = spawnSync('git', ['branch', '-d', branchName], {
+        cwd: ROOT,
+        encoding: 'utf8',
+      });
+      if (result.status === 0) {
+        process.stderr.write(`🧹 Cleaned up unused branch: ${branchName}\n`);
+      }
+    } catch (e) {
+      // Non-fatal - branch may have commits or not exist
+    }
+  }
+}
+
 // Create new session with worktree
-function createSession(options = {}) {
+async function createSession(options = {}) {
   const registry = loadRegistry();
   const sessionId = String(registry.next_id);
   const projectName = registry.project_name;
@@ -426,6 +743,7 @@ function createSession(options = {}) {
     }
   );
 
+  let branchCreatedByUs = false;
   if (checkRef.status !== 0) {
     // Branch doesn't exist, create it
     const createBranch = spawnSync('git', ['branch', branchName], {
@@ -439,18 +757,27 @@ function createSession(options = {}) {
         error: `Failed to create branch: ${createBranch.stderr || 'unknown error'}`,
       };
     }
+    branchCreatedByUs = true;
   }
 
-  // Create worktree (using spawnSync for safety)
-  const createWorktree = spawnSync('git', ['worktree', 'add', worktreePath, branchName], {
-    cwd: ROOT,
-    encoding: 'utf8',
-  });
+  // Get timeout from options (default: 2 minutes)
+  const timeoutMs = options.timeout || DEFAULT_WORKTREE_TIMEOUT_MS;
 
-  if (createWorktree.status !== 0) {
+  // Create worktree with timeout and progress feedback
+  const stopProgress = progressIndicator(
+    'Creating worktree (this may take a while for large repos)'
+  );
+  try {
+    await createWorktreeWithTimeout(worktreePath, branchName, timeoutMs);
+    stopProgress();
+    process.stderr.write(`✓ Worktree created successfully\n`);
+  } catch (error) {
+    stopProgress();
+    // Clean up partial state
+    cleanupFailedWorktree(worktreePath, branchName, branchCreatedByUs);
     return {
       success: false,
-      error: `Failed to create worktree: ${createWorktree.stderr || 'unknown error'}`,
+      error: error.message,
     };
   }
 
@@ -471,9 +798,10 @@ function createSession(options = {}) {
     }
   }
 
-  // Copy Claude Code and AgileFlow config folders (gitignored contents won't copy with worktree)
+  // Copy Claude Code, AgileFlow config, and docs folders (gitignored contents won't copy with worktree)
   // Note: The folder may exist with some tracked files, but gitignored subfolders (commands/, agents/) won't be there
-  const configFolders = ['.claude', '.agileflow'];
+  // docs/ contains gitignored state files like status.json, session-state.json that need to be shared
+  const configFolders = ['.claude', '.agileflow', 'docs'];
   const copiedFolders = [];
   for (const folder of configFolders) {
     const src = path.join(ROOT, folder);
@@ -1115,7 +1443,7 @@ function main() {
     case 'create': {
       const options = {};
       // SECURITY: Only accept whitelisted option keys
-      const allowedKeys = ['nickname', 'branch'];
+      const allowedKeys = ['nickname', 'branch', 'timeout'];
       for (let i = 1; i < args.length; i++) {
         const arg = args[i];
         if (arg.startsWith('--')) {
@@ -1133,8 +1461,27 @@ function main() {
           }
         }
       }
-      const result = createSession(options);
-      console.log(JSON.stringify(result));
+      // Parse timeout as number (milliseconds)
+      if (options.timeout) {
+        options.timeout = parseInt(options.timeout, 10);
+        if (isNaN(options.timeout) || options.timeout < 1000) {
+          console.log(
+            JSON.stringify({
+              success: false,
+              error: 'Timeout must be a number >= 1000 (milliseconds)',
+            })
+          );
+          return;
+        }
+      }
+      // Handle async createSession
+      createSession(options)
+        .then(result => {
+          console.log(JSON.stringify(result));
+        })
+        .catch(err => {
+          console.log(JSON.stringify({ success: false, error: err.message }));
+        });
       break;
     }
 
@@ -1186,6 +1533,17 @@ function main() {
       break;
     }
 
+    case 'health': {
+      // Get health status for all sessions
+      // Usage: health [staleDays] [--detailed]
+      const staleDaysArg = args.find((a) => /^\d+$/.test(a));
+      const staleDays = staleDaysArg ? parseInt(staleDaysArg, 10) : 7;
+      const detailed = args.includes('--detailed');
+      const health = getSessionsHealth({ staleDays, detailed });
+      console.log(JSON.stringify(health));
+      break;
+    }
+
     case 'get': {
       const sessionId = args[1];
       if (!sessionId) {
@@ -1448,7 +1806,7 @@ ${c.brand}${c.bold}Session Manager${c.reset} - Multi-session coordination for Cl
 ${c.cyan}Commands:${c.reset}
   register [nickname]     Register current directory as a session
   unregister <id>         Unregister a session (remove lock)
-  create [--nickname X]   Create new session with git worktree
+  create [--nickname X] [--timeout MS]  Create session with worktree (default timeout: 120000ms)
   list [--json]           List all sessions
   count                   Count other active sessions
   delete <id> [--remove-worktree]  Delete session