agileflow 2.91.0 → 2.92.1

package/scripts/session-manager.js

@@ -11,18 +11,47 @@
 
 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 } = require('../lib/paths');
+const {
+  getProjectRoot,
+  getStatusPath,
+  getSessionStatePath,
+  getAgileflowDir,
+} = require('../lib/paths');
 const { safeReadJSON } = require('../lib/errors');
 const { isValidBranchName, isValidSessionNickname } = require('../lib/validate');
 
+const { SessionRegistry } = require('../lib/session-registry');
+
 const ROOT = getProjectRoot();
-const SESSIONS_DIR = path.join(ROOT, '.agileflow', 'sessions');
+const SESSIONS_DIR = path.join(getAgileflowDir(ROOT), 'sessions');
 const REGISTRY_PATH = path.join(SESSIONS_DIR, 'registry.json');
 
+// Injectable registry instance for testing
+let _registryInstance = null;
+
+/**
+ * Get the registry instance (singleton, injectable for testing)
+ * @returns {SessionRegistry}
+ */
+function getRegistryInstance() {
+  if (!_registryInstance) {
+    _registryInstance = new SessionRegistry(ROOT);
+  }
+  return _registryInstance;
+}
+
+/**
+ * Inject a mock registry for testing
+ * @param {SessionRegistry|null} registry - Registry to inject, or null to reset
+ */
+function injectRegistry(registry) {
+  _registryInstance = registry;
+}
+
 // Ensure sessions directory exists
 function ensureSessionsDir() {
   if (!fs.existsSync(SESSIONS_DIR)) {
@@ -30,35 +59,25 @@ function ensureSessionsDir() {
   }
 }
 
-// Load or create registry
+// Load or create registry (uses injectable SessionRegistry)
+// Preserves original behavior: saves default registry if file didn't exist
 function loadRegistry() {
-  ensureSessionsDir();
+  const registryInstance = getRegistryInstance();
+  const fileExistedBefore = fs.existsSync(registryInstance.registryPath);
+  const data = registryInstance.loadSync();
 
-  if (fs.existsSync(REGISTRY_PATH)) {
-    try {
-      return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));
-    } catch (e) {
-      console.error(`${c.red}Error loading registry: ${e.message}${c.reset}`);
-    }
+  // If file didn't exist, save the default to disk (original behavior)
+  if (!fileExistedBefore) {
+    registryInstance.saveSync(data);
   }
 
-  // Create default registry
-  const registry = {
-    schema_version: '1.0.0',
-    next_id: 1,
-    project_name: path.basename(ROOT),
-    sessions: {},
-  };
-
-  saveRegistry(registry);
-  return registry;
+  return data;
 }
 
-// Save registry
-function saveRegistry(registry) {
-  ensureSessionsDir();
-  registry.updated = new Date().toISOString();
-  fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+// Save registry (uses injectable SessionRegistry)
+function saveRegistry(registryData) {
+  const registry = getRegistryInstance();
+  return registry.saveSync(registryData);
 }
 
 // Check if PID is alive
@@ -77,7 +96,7 @@ function getLockPath(sessionId) {
   return path.join(SESSIONS_DIR, `${sessionId}.lock`);
 }
 
-// Read lock file
+// Read lock file (sync version for backward compatibility)
 function readLock(sessionId) {
   const lockPath = getLockPath(sessionId);
   if (!fs.existsSync(lockPath)) return null;
@@ -95,6 +114,22 @@ function readLock(sessionId) {
   }
 }
 
+// Read lock file (async version for parallel operations)
+async function readLockAsync(sessionId) {
+  const lockPath = getLockPath(sessionId);
+  try {
+    const content = await fs.promises.readFile(lockPath, 'utf8');
+    const lock = {};
+    content.split('\n').forEach(line => {
+      const [key, value] = line.split('=');
+      if (key && value) lock[key.trim()] = value.trim();
+    });
+    return lock;
+  } catch (e) {
+    return null;
+  }
+}
+
 // Write lock file
 function writeLock(sessionId, pid) {
   const lockPath = getLockPath(sessionId);
@@ -117,7 +152,7 @@ function isSessionActive(sessionId) {
   return isPidAlive(parseInt(lock.pid, 10));
 }
 
-// Clean up stale locks (with detailed tracking)
+// Clean up stale locks (with detailed tracking) - sync version for backward compatibility
 function cleanupStaleLocks(registry, options = {}) {
   const { verbose = false, dryRun = false } = options;
   let cleaned = 0;
@@ -152,10 +187,84 @@ function cleanupStaleLocks(registry, options = {}) {
   return { count: cleaned, sessions: cleanedSessions };
 }
 
-// Get current git branch
+// Clean up stale locks (async parallel version - faster for many sessions)
+async function cleanupStaleLocksAsync(registry, options = {}) {
+  const { verbose = false, dryRun = false } = options;
+  const cleanedSessions = [];
+
+  const sessionEntries = Object.entries(registry.sessions);
+  if (sessionEntries.length === 0) {
+    return { count: 0, sessions: [] };
+  }
+
+  // Read all locks in parallel
+  const lockResults = await Promise.all(
+    sessionEntries.map(async ([id, session]) => {
+      const lock = await readLockAsync(id);
+      return { id, session, lock };
+    })
+  );
+
+  // Process results (sequential - fast since it's just memory operations)
+  for (const { id, session, lock } of lockResults) {
+    if (lock) {
+      const pid = parseInt(lock.pid, 10);
+      const isAlive = isPidAlive(pid);
+
+      if (!isAlive) {
+        cleanedSessions.push({
+          id,
+          nickname: session.nickname,
+          branch: session.branch,
+          pid,
+          reason: 'pid_dead',
+          path: session.path,
+        });
+
+        if (!dryRun) {
+          removeLock(id);
+        }
+      }
+    }
+  }
+
+  return { count: cleanedSessions.length, sessions: cleanedSessions };
+}
+
+// Git command cache (10 second TTL to avoid stale data)
+const gitCache = {
+  data: new Map(),
+  ttlMs: 10000,
+  get(key) {
+    const entry = this.data.get(key);
+    if (entry && Date.now() - entry.timestamp < this.ttlMs) {
+      return entry.value;
+    }
+    this.data.delete(key);
+    return null;
+  },
+  set(key, value) {
+    this.data.set(key, { value, timestamp: Date.now() });
+  },
+  invalidate(key) {
+    if (key) {
+      this.data.delete(key);
+    } else {
+      this.data.clear();
+    }
+  },
+};
+
+// Get current git branch (cached for performance)
 function getCurrentBranch() {
+  const cacheKey = `branch:${ROOT}`;
+  const cached = gitCache.get(cacheKey);
+  if (cached !== null) return cached;
+
   try {
-    return execSync('git branch --show-current', { cwd: ROOT, encoding: 'utf8' }).trim();
+    const branch = execSync('git branch --show-current', { cwd: ROOT, encoding: 'utf8' }).trim();
+    gitCache.set(cacheKey, branch);
+    return branch;
   } catch (e) {
     return 'unknown';
   }
@@ -163,7 +272,7 @@ function getCurrentBranch() {
 
 // Get current story from status.json
 function getCurrentStory() {
-  const statusPath = path.join(ROOT, 'docs', '09-agents', 'status.json');
+  const statusPath = getStatusPath(ROOT);
   const result = safeReadJSON(statusPath, { defaultValue: null });
 
   if (!result.ok || !result.data) return null;
@@ -276,8 +385,157 @@ 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;
@@ -322,6 +580,7 @@ function createSession(options = {}) {
     }
   );
 
+  let branchCreatedByUs = false;
   if (checkRef.status !== 0) {
     // Branch doesn't exist, create it
     const createBranch = spawnSync('git', ['branch', branchName], {
@@ -335,21 +594,65 @@ 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,
     };
   }
 
+  // Copy environment files to new worktree (they don't copy automatically)
+  const envFiles = ['.env', '.env.local', '.env.development', '.env.test', '.env.production'];
+  const copiedEnvFiles = [];
+  for (const envFile of envFiles) {
+    const src = path.join(ROOT, envFile);
+    const dest = path.join(worktreePath, envFile);
+    if (fs.existsSync(src) && !fs.existsSync(dest)) {
+      try {
+        fs.copyFileSync(src, dest);
+        copiedEnvFiles.push(envFile);
+      } catch (e) {
+        // Non-fatal: log but continue
+        console.warn(`Warning: Could not copy ${envFile}: ${e.message}`);
+      }
+    }
+  }
+
+  // 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
+  // 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);
+    const dest = path.join(worktreePath, folder);
+    if (fs.existsSync(src)) {
+      try {
+        // Use force to overwrite existing files, recursive for subdirs
+        fs.cpSync(src, dest, { recursive: true, force: true });
+        copiedFolders.push(folder);
+      } catch (e) {
+        // Non-fatal: log but continue
+        console.warn(`Warning: Could not copy ${folder}: ${e.message}`);
+      }
+    }
+  }
+
   // Register session - worktree sessions are always parallel threads
   registry.next_id++;
   registry.sessions[sessionId] = {
@@ -372,6 +675,8 @@ function createSession(options = {}) {
     branch: branchName,
     thread_type: registry.sessions[sessionId].thread_type,
     command: `cd "${worktreePath}" && claude`,
+    envFilesCopied: copiedEnvFiles,
+    foldersCopied: copiedFolders,
   };
 }
 
@@ -445,22 +750,33 @@ function deleteSession(sessionId, removeWorktree = false) {
   return { success: true };
 }
 
-// Get main branch name (main or master)
+// Get main branch name (main or master) - cached since it rarely changes
 function getMainBranch() {
+  const cacheKey = `mainBranch:${ROOT}`;
+  const cached = gitCache.get(cacheKey);
+  if (cached !== null) return cached;
+
   const checkMain = spawnSync('git', ['show-ref', '--verify', '--quiet', 'refs/heads/main'], {
     cwd: ROOT,
     encoding: 'utf8',
   });
 
-  if (checkMain.status === 0) return 'main';
+  if (checkMain.status === 0) {
+    gitCache.set(cacheKey, 'main');
+    return 'main';
+  }
 
   const checkMaster = spawnSync('git', ['show-ref', '--verify', '--quiet', 'refs/heads/master'], {
     cwd: ROOT,
     encoding: 'utf8',
   });
 
-  if (checkMaster.status === 0) return 'master';
+  if (checkMaster.status === 0) {
+    gitCache.set(cacheKey, 'master');
+    return 'master';
+  }
 
+  gitCache.set(cacheKey, 'main');
   return 'main'; // Default fallback
 }
 
@@ -745,7 +1061,7 @@ const SESSION_PHASES = {
   MERGED: 'merged',
 };
 
-// Detect session phase based on git state
+// Detect session phase based on git state (with caching for performance)
 function getSessionPhase(session) {
   // If merged_at field exists, session was merged
   if (session.merged_at) {
@@ -764,6 +1080,11 @@ function getSessionPhase(session) {
       return SESSION_PHASES.TODO;
     }
 
+    // Cache key for this session's git state
+    const cacheKey = `phase:${sessionPath}`;
+    const cached = gitCache.get(cacheKey);
+    if (cached !== null) return cached;
+
     // Count commits since branch diverged from main
     const mainBranch = getMainBranch();
     const commitCount = execSync(`git rev-list --count ${mainBranch}..HEAD 2>/dev/null || echo 0`, {
@@ -774,6 +1095,7 @@ function getSessionPhase(session) {
     const commits = parseInt(commitCount, 10);
 
     if (commits === 0) {
+      gitCache.set(cacheKey, SESSION_PHASES.TODO);
       return SESSION_PHASES.TODO;
     }
 
@@ -783,13 +1105,17 @@ function getSessionPhase(session) {
       encoding: 'utf8',
     }).trim();
 
+    let phase;
     if (status === '') {
       // No uncommitted changes = ready for review
-      return SESSION_PHASES.REVIEW;
+      phase = SESSION_PHASES.REVIEW;
+    } else {
+      // Has commits but also uncommitted changes = still coding
+      phase = SESSION_PHASES.CODING;
     }
 
-    // Has commits but also uncommitted changes = still coding
-    return SESSION_PHASES.CODING;
+    gitCache.set(cacheKey, phase);
+    return phase;
   } catch (e) {
     // On error, assume coding phase
     return SESSION_PHASES.CODING;
@@ -952,7 +1278,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('--')) {
@@ -970,8 +1296,20 @@ 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;
     }
 
@@ -1046,12 +1384,11 @@ function main() {
 
       // Register in single pass (combines register + count + status)
       const registry = loadRegistry();
-      const cleanupResult = cleanupStaleLocks(registry);
       const branch = getCurrentBranch();
       const story = getCurrentStory();
       const pid = process.ppid || process.pid;
 
-      // Find or create session
+      // Find or create session FIRST (so we don't clean our own stale lock)
       let sessionId = null;
       let isNew = false;
       for (const [id, session] of Object.entries(registry.sessions)) {
@@ -1094,6 +1431,16 @@ function main() {
       }
       saveRegistry(registry);
 
+      // Clean up stale locks AFTER registering current session (so we don't clean our own lock)
+      const cleanupResult = cleanupStaleLocks(registry);
+
+      // Filter out the current session from cleanup reports (its lock was just refreshed)
+      // Use String() to ensure consistent comparison (sessionId is string, cleanup.id may vary)
+      const filteredCleanup = {
+        count: cleanupResult.sessions.filter(s => String(s.id) !== String(sessionId)).length,
+        sessions: cleanupResult.sessions.filter(s => String(s.id) !== String(sessionId)),
+      };
+
       // Build session list and counts
       const sessions = [];
       let otherActive = 0;
@@ -1114,8 +1461,8 @@ function main() {
           current,
           otherActive,
           total: sessions.length,
-          cleaned: cleanupResult.count,
-          cleanedSessions: cleanupResult.sessions,
+          cleaned: filteredCleanup.count,
+          cleanedSessions: filteredCleanup.sessions,
         })
       );
       break;
@@ -1276,7 +1623,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
@@ -1815,7 +2162,7 @@ function getMergeHistory() {
 }
 
 // Session state file path
-const SESSION_STATE_PATH = path.join(ROOT, 'docs', '09-agents', 'session-state.json');
+const SESSION_STATE_PATH = getSessionStatePath(ROOT);
 
 /**
  * Switch active session context (for use with /add-dir).
@@ -1998,8 +2345,13 @@ function setSessionThreadType(sessionId, threadType) {
 
 // Export for use as module
 module.exports = {
+  // Registry injection (for testing)
+  injectRegistry,
+  getRegistryInstance,
+  // Registry access (backward compatible)
   loadRegistry,
   saveRegistry,
+  // Session management
   registerSession,
   unregisterSession,
   getSession,
@@ -2009,6 +2361,7 @@ module.exports = {
   deleteSession,
   isSessionActive,
   cleanupStaleLocks,
+  cleanupStaleLocksAsync,
   // Merge operations
   getMainBranch,
   checkMergeability,