agileflow 2.92.0 → 2.92.1

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.92.1] - 2026-01-23
+
+### Added
+- Session worktree timeout, progress feedback, and docs folder copy
+
 ## [2.92.0] - 2026-01-23
 
 ### Added

package/README.md

@@ -3,8 +3,8 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-76-blue)](docs/04-architecture/commands.md)
-[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-30-orange)](docs/04-architecture/subagents.md)
+[![Commands](https://img.shields.io/badge/commands-77-blue)](docs/04-architecture/commands.md)
+[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-31-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.md)
 
 **AI-driven agile development for Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and more.** Combining Scrum, Kanban, ADRs, and docs-as-code principles into one framework-agnostic system.
@@ -65,8 +65,8 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 76 | Slash commands for agile workflows |
-| [Agents/Experts](docs/04-architecture/subagents.md) | 30 | Specialized agents with self-improving knowledge bases |
+| [Commands](docs/04-architecture/commands.md) | 77 | Slash commands for agile workflows |
+| [Agents/Experts](docs/04-architecture/subagents.md) | 31 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
 ---
@@ -76,8 +76,8 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 76 slash commands
-- [Agents/Experts](docs/04-architecture/subagents.md) - 30 specialized agents with self-improving knowledge
+- [Commands](docs/04-architecture/commands.md) - All 77 slash commands
+- [Agents/Experts](docs/04-architecture/subagents.md) - 31 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 
 ### Architecture

package/lib/codebase-indexer.js

@@ -643,7 +643,8 @@ function updateIndex(projectRoot, options = {}) {
         existingIndex.tags[tag].push(filePath);
       }
       for (const exp of fileData.exports || []) {
-        if (!Object.hasOwn(existingIndex.symbols.exports, exp)) existingIndex.symbols.exports[exp] = [];
+        if (!Object.hasOwn(existingIndex.symbols.exports, exp))
+          existingIndex.symbols.exports[exp] = [];
         existingIndex.symbols.exports[exp].push(filePath);
       }
     }

package/package.json

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

package/scripts/agileflow-welcome.js

@@ -102,10 +102,20 @@ function detectPlatform() {
     // Try to detect Linux distribution
     try {
       const osRelease = fs.readFileSync('/etc/os-release', 'utf8');
-      if (osRelease.includes('Ubuntu') || osRelease.includes('Debian') || osRelease.includes('Pop!_OS') || osRelease.includes('Mint')) {
+      if (
+        osRelease.includes('Ubuntu') ||
+        osRelease.includes('Debian') ||
+        osRelease.includes('Pop!_OS') ||
+        osRelease.includes('Mint')
+      ) {
         return { os: 'Ubuntu/Debian', installCmd: 'sudo apt install tmux', hasSudo: true };
       }
-      if (osRelease.includes('Fedora') || osRelease.includes('Red Hat') || osRelease.includes('CentOS') || osRelease.includes('Rocky')) {
+      if (
+        osRelease.includes('Fedora') ||
+        osRelease.includes('Red Hat') ||
+        osRelease.includes('CentOS') ||
+        osRelease.includes('Rocky')
+      ) {
         return { os: 'Fedora/RHEL', installCmd: 'sudo dnf install tmux', hasSudo: true };
       }
       if (osRelease.includes('Arch')) {
@@ -662,15 +672,43 @@ function compareVersions(a, b) {
  * These are the options that can be configured through /agileflow:configure
  */
 const ALL_CONFIG_OPTIONS = {
-  claudeMdReinforcement: { since: '2.92.0', description: 'Add /babysit rules to CLAUDE.md', autoApplyable: true },
-  sessionStartHook: { since: '2.35.0', description: 'Welcome display on session start', autoApplyable: false },
-  precompactHook: { since: '2.40.0', description: 'Context preservation during /compact', autoApplyable: false },
-  damageControlHooks: { since: '2.50.0', description: 'Block destructive commands', autoApplyable: false },
+  claudeMdReinforcement: {
+    since: '2.92.0',
+    description: 'Add /babysit rules to CLAUDE.md',
+    autoApplyable: true,
+  },
+  sessionStartHook: {
+    since: '2.35.0',
+    description: 'Welcome display on session start',
+    autoApplyable: false,
+  },
+  precompactHook: {
+    since: '2.40.0',
+    description: 'Context preservation during /compact',
+    autoApplyable: false,
+  },
+  damageControlHooks: {
+    since: '2.50.0',
+    description: 'Block destructive commands',
+    autoApplyable: false,
+  },
   statusLine: { since: '2.35.0', description: 'Custom status bar display', autoApplyable: false },
-  autoArchival: { since: '2.35.0', description: 'Auto-archive completed stories', autoApplyable: false },
-  autoUpdate: { since: '2.70.0', description: 'Auto-update on session start', autoApplyable: false },
+  autoArchival: {
+    since: '2.35.0',
+    description: 'Auto-archive completed stories',
+    autoApplyable: false,
+  },
+  autoUpdate: {
+    since: '2.70.0',
+    description: 'Auto-update on session start',
+    autoApplyable: false,
+  },
   ralphLoop: { since: '2.60.0', description: 'Autonomous story processing', autoApplyable: false },
-  tmuxAutoSpawn: { since: '2.92.0', description: 'Auto-start Claude in tmux session', autoApplyable: true },
+  tmuxAutoSpawn: {
+    since: '2.92.0',
+    description: 'Auto-start Claude in tmux session',
+    autoApplyable: true,
+  },
 };
 
 /**
@@ -719,7 +757,10 @@ function checkConfigStaleness(rootDir, currentVersion, cache = null) {
       // Check for unconfigured options in metadata
       for (const [name, option] of Object.entries(configOptions)) {
         if (option.configured === false) {
-          const optionInfo = ALL_CONFIG_OPTIONS[name] || { description: name, autoApplyable: false };
+          const optionInfo = ALL_CONFIG_OPTIONS[name] || {
+            description: name,
+            autoApplyable: false,
+          };
           result.outdated = true;
           result.newOptionsCount++;
           result.newOptions.push({
@@ -776,22 +817,24 @@ function isOptionActuallyConfigured(optionName, hooks, settings) {
     case 'precompactHook':
       return hooks.PreCompact && hooks.PreCompact.length > 0;
     case 'damageControlHooks':
-      return hooks.PreToolUse && hooks.PreToolUse.some(h =>
-        h.hooks?.some(hk => hk.command?.includes('damage-control'))
+      return (
+        hooks.PreToolUse &&
+        hooks.PreToolUse.some(h => h.hooks?.some(hk => hk.command?.includes('damage-control')))
       );
     case 'statusLine':
       return settings.statusLine && settings.statusLine.command;
     case 'autoArchival':
       // Archival is tied to SessionStart hook running archive script
-      return hooks.SessionStart && hooks.SessionStart.some(h =>
-        h.hooks?.some(hk => hk.command?.includes('archive'))
+      return (
+        hooks.SessionStart &&
+        hooks.SessionStart.some(h => h.hooks?.some(hk => hk.command?.includes('archive')))
       );
     case 'autoUpdate':
       // Would need to check metadata for autoUpdate setting
       return false; // Default to not configured
     case 'ralphLoop':
-      return hooks.Stop && hooks.Stop.some(h =>
-        h.hooks?.some(hk => hk.command?.includes('ralph-loop'))
+      return (
+        hooks.Stop && hooks.Stop.some(h => h.hooks?.some(hk => hk.command?.includes('ralph-loop')))
       );
     case 'claudeMdReinforcement':
       // Check if CLAUDE.md has the marker - can't easily check from here
@@ -848,7 +891,10 @@ ${marker}
         if (fs.existsSync(metadataPath)) {
           const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
           if (!metadata.features) metadata.features = {};
-          if (!metadata.features.tmuxAutoSpawn || metadata.features.tmuxAutoSpawn.enabled === undefined) {
+          if (
+            !metadata.features.tmuxAutoSpawn ||
+            metadata.features.tmuxAutoSpawn.enabled === undefined
+          ) {
             metadata.features.tmuxAutoSpawn = {
               enabled: true,
               version: metadata.version || '2.92.0',
@@ -1636,24 +1682,32 @@ async function main() {
   // Show config auto-apply confirmation (for "full" profile)
   if (configAutoApplied > 0) {
     console.log('');
-    console.log(`${c.mintGreen}✨ Auto-applied ${configAutoApplied} new config option(s)${c.reset}`);
+    console.log(
+      `${c.mintGreen}✨ Auto-applied ${configAutoApplied} new config option(s)${c.reset}`
+    );
     console.log(`   ${c.slate}Profile "full" enables all new features automatically.${c.reset}`);
   }
 
   // Show config staleness notification (for custom profiles)
   if (configStaleness.outdated && configStaleness.newOptionsCount > 0) {
     console.log('');
-    console.log(`${c.amber}⚙️  ${configStaleness.newOptionsCount} new configuration option(s) available${c.reset}`);
+    console.log(
+      `${c.amber}⚙️  ${configStaleness.newOptionsCount} new configuration option(s) available${c.reset}`
+    );
     for (const opt of configStaleness.newOptions.slice(0, 3)) {
       console.log(`   ${c.dim}• ${opt.description}${c.reset}`);
     }
-    console.log(`   ${c.slate}Run ${c.skyBlue}/agileflow:configure${c.reset}${c.slate} to enable them.${c.reset}`);
+    console.log(
+      `   ${c.slate}Run ${c.skyBlue}/agileflow:configure${c.reset}${c.slate} to enable them.${c.reset}`
+    );
   }
 
   // Show tmux installation notice if tmux auto-spawn is enabled but tmux not installed
   if (tmuxAutoSpawnEnabled && !tmuxCheck.available) {
     console.log('');
-    console.log(`${c.amber}📦 tmux not installed${c.reset} ${c.dim}(enables parallel sessions in one terminal)${c.reset}`);
+    console.log(
+      `${c.amber}📦 tmux not installed${c.reset} ${c.dim}(enables parallel sessions in one terminal)${c.reset}`
+    );
 
     // Show platform-specific install command
     if (tmuxCheck.platform?.installCmd) {
@@ -1668,7 +1722,9 @@ async function main() {
       console.log(`   ${c.dim}• Ubuntu:${c.reset} ${c.cyan}sudo apt install tmux${c.reset}`);
       console.log(`   ${c.dim}• No sudo:${c.reset} ${c.cyan}${tmuxCheck.noSudoCmd}${c.reset}`);
     }
-    console.log(`   ${c.dim}Or disable this notice: ${c.skyBlue}/agileflow:configure --disable=tmuxautospawn${c.reset}`);
+    console.log(
+      `   ${c.dim}Or disable this notice: ${c.skyBlue}/agileflow:configure --disable=tmuxautospawn${c.reset}`
+    );
   }
 
   // Show warning and tip if other sessions are active (vibrant colors)

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');
 
@@ -380,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;
@@ -426,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], {
@@ -439,18 +594,25 @@ 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 +633,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 +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('--')) {
@@ -1133,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;
     }
 
@@ -1448,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

package/scripts/spawn-parallel.js

@@ -296,10 +296,7 @@ function spawn(args) {
     });
 
     // Show what was copied
-    const copied = [
-      ...(result.envFilesCopied || []),
-      ...(result.foldersCopied || []),
-    ];
+    const copied = [...(result.envFilesCopied || []), ...(result.foldersCopied || [])];
     const copyInfo = copied.length ? dim(` (copied: ${copied.join(', ')})`) : '';
     console.log(success(`  ✓ Session ${result.sessionId}: ${sessionSpec.nickname}${copyInfo}`));
   }
@@ -341,16 +338,22 @@ function spawn(args) {
     console.log(`  ${c.cyan}No sudo?${c.reset}      conda install -c conda-forge tmux`);
     console.log('');
     console.log(dim('Or use --no-tmux to get manual commands instead:'));
-    console.log(`  ${c.cyan}node spawn-parallel.js spawn --count ${createdSessions.length} --no-tmux${c.reset}`);
+    console.log(
+      `  ${c.cyan}node spawn-parallel.js spawn --count ${createdSessions.length} --no-tmux${c.reset}`
+    );
     console.log('');
-    console.log(warning('Worktrees created but Claude not spawned. Install tmux or use --no-tmux.'));
+    console.log(
+      warning('Worktrees created but Claude not spawned. Install tmux or use --no-tmux.')
+    );
   }
 
   // Summary
   console.log(bold('\n📊 Session Summary:'));
   console.log(dim('─'.repeat(50)));
   for (const session of createdSessions) {
-    console.log(`  ${c.cyan}${session.sessionId}${c.reset} │ ${session.nickname} │ ${dim(session.branch)}`);
+    console.log(
+      `  ${c.cyan}${session.sessionId}${c.reset} │ ${session.nickname} │ ${dim(session.branch)}`
+    );
   }
   console.log(dim('─'.repeat(50)));
   console.log(`${c.cyan}Use /agileflow:session:status to view all sessions.${c.reset}`);
@@ -397,7 +400,9 @@ function addWindow(args) {
   const tmuxEnv = process.env.TMUX;
   if (!tmuxEnv) {
     console.log(error('\n❌ Not in a tmux session.\n'));
-    console.log(`${c.cyan}Use /agileflow:session:spawn to create a new tmux session first.${c.reset}`);
+    console.log(
+      `${c.cyan}Use /agileflow:session:spawn to create a new tmux session first.${c.reset}`
+    );
     console.log(`${dim('Or run: node .agileflow/scripts/spawn-parallel.js spawn --count 1')}`);
     return { success: false, error: 'Not in tmux' };
   }
@@ -436,9 +441,13 @@ function addWindow(args) {
   const cmd = buildClaudeCommand(result.path, {});
 
   // Create new window in current tmux session
-  const newWindowResult = spawnSync('tmux', ['new-window', '-t', currentSession, '-n', windowName], {
-    encoding: 'utf8',
-  });
+  const newWindowResult = spawnSync(
+    'tmux',
+    ['new-window', '-t', currentSession, '-n', windowName],
+    {
+      encoding: 'utf8',
+    }
+  );
 
   if (newWindowResult.status !== 0) {
     console.error(error(`Failed to create tmux window: ${newWindowResult.stderr}`));
@@ -453,10 +462,13 @@ function addWindow(args) {
   // Get window number
   let windowIndex;
   try {
-    windowIndex = execSync(`tmux list-windows -t ${currentSession} -F "#I:#W" | grep ":${windowName}$" | cut -d: -f1`, {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+    windowIndex = execSync(
+      `tmux list-windows -t ${currentSession} -F "#I:#W" | grep ":${windowName}$" | cut -d: -f1`,
+      {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    ).trim();
   } catch {
     windowIndex = '?';
   }
@@ -493,7 +505,10 @@ function killAll() {
       stdio: ['pipe', 'pipe', 'pipe'],
     });
 
-    const sessions = result.trim().split('\n').filter(s => s.startsWith('claude-parallel-'));
+    const sessions = result
+      .trim()
+      .split('\n')
+      .filter(s => s.startsWith('claude-parallel-'));
 
     if (sessions.length === 0) {
       console.log(`${c.cyan}No claude-parallel tmux sessions found.${c.reset}`);

package/src/core/commands/session/new.md

@@ -226,11 +226,30 @@ To switch to this session, run:
 - One short command to type
 - Immediately enables file access to the new session directory
 
+## Worktree Creation Timeout
+
+By default, worktree creation has a 2-minute (120000ms) timeout. For large repositories with many files, you can increase this:
+
+```bash
+# Increase timeout to 5 minutes (300000ms)
+node .agileflow/scripts/session-manager.js create --timeout 300000
+```
+
+During worktree creation, progress feedback is displayed:
+- **TTY (terminal)**: Animated spinner
+- **Non-TTY (Claude Code)**: Periodic "still working" messages every 10 seconds
+
+If worktree creation times out or fails, the script automatically cleans up:
+- Removes any partial worktree directory
+- Prunes git worktree registry
+- Removes the branch if we just created it
+
 ## Error Handling
 
 - **Directory exists**: Suggest different name or manual cleanup
 - **Branch conflict**: Offer to use existing branch or create new one
 - **Git errors**: Display error message and suggest manual resolution
+- **Timeout**: Suggest increasing timeout for large repos
 
 ## Related Commands
 

package/tools/cli/commands/setup.js

@@ -185,7 +185,12 @@ ${claudeMdMarker}
 
       // Update metadata with config tracking
       try {
-        const metadataPath = path.join(config.directory, config.docsFolder, '00-meta', 'agileflow-metadata.json');
+        const metadataPath = path.join(
+          config.directory,
+          config.docsFolder,
+          '00-meta',
+          'agileflow-metadata.json'
+        );
         if (fs.existsSync(metadataPath)) {
           const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
           const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
@@ -223,8 +228,12 @@ ${claudeMdMarker}
       // Shell alias reload reminder
       if (coreResult.shellAliases?.configured?.length > 0) {
         console.log(chalk.bold('\nShell aliases:'));
-        info(`Reload shell to use: ${chalk.cyan('source ~/.bashrc')} or ${chalk.cyan('source ~/.zshrc')}`);
-        info(`Then run ${chalk.cyan('af')} to start Claude in tmux (or ${chalk.cyan('claude')} for normal)`);
+        info(
+          `Reload shell to use: ${chalk.cyan('source ~/.bashrc')} or ${chalk.cyan('source ~/.zshrc')}`
+        );
+        info(
+          `Then run ${chalk.cyan('af')} to start Claude in tmux (or ${chalk.cyan('claude')} for normal)`
+        );
       }
 
       console.log(chalk.dim(`\nInstalled to: ${coreResult.path}\n`));

package/tools/cli/installers/ide/windsurf.js

@@ -15,7 +15,7 @@ const { BaseIdeSetup } = require('./_base-ide');
  */
 class WindsurfSetup extends BaseIdeSetup {
   constructor() {
-    super('windsurf', 'Windsurf', true);
+    super('windsurf', 'Windsurf', false);
     this.configDir = '.windsurf';
     this.workflowsDir = 'workflows';
   }

package/tools/cli/lib/ide-registry.js

@@ -83,7 +83,7 @@ const IDE_REGISTRY = {
     commandsSubdir: 'workflows',
     agileflowFolder: 'agileflow',
     targetSubdir: 'workflows/agileflow', // lowercase
-    preferred: true,
+    preferred: false,
     description: "Codeium's AI IDE",
     handler: 'WindsurfSetup',
     labels: {
@@ -287,9 +287,7 @@ class IdeRegistry {
    */
   static getLabels(ideName) {
     const ide = IDE_REGISTRY[ideName];
-    return ide && ide.labels
-      ? ide.labels
-      : { commands: 'commands', agents: 'agents' };
+    return ide && ide.labels ? ide.labels : { commands: 'commands', agents: 'agents' };
   }
 }
 

package/tools/cli/lib/ui.js

@@ -174,7 +174,8 @@ async function promptInstall() {
     {
       type: 'confirm',
       name: 'claudeMdReinforcement',
-      message: 'Add /babysit AskUserQuestion rules to CLAUDE.md? (recommended for context preservation)',
+      message:
+        'Add /babysit AskUserQuestion rules to CLAUDE.md? (recommended for context preservation)',
       default: true,
     },
   ]);