agileflow 2.99.1 → 2.99.3

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.99.3] - 2026-02-09
+
+### Fixed
+- Auto-heal tmux socket directory after macOS reboot
+
+## [2.99.2] - 2026-02-09
+
+### Added
+- Documentation overhaul with teams commands, frontmatter fixes, and damage control resilience
+
 ## [2.99.1] - 2026-02-08
 
 ### Added

package/lib/dashboard-server.js

@@ -1310,8 +1310,10 @@ class DashboardServer extends EventEmitter {
           title: e.title || id,
           status: e.status || 'unknown',
           storyCount: (e.stories || []).length,
-          doneCount: (e.stories || []).filter(sid =>
-            stories[sid] && (stories[sid].status === 'done' || stories[sid].status === 'completed')
+          doneCount: (e.stories || []).filter(
+            sid =>
+              stories[sid] &&
+              (stories[sid].status === 'done' || stories[sid].status === 'completed')
           ).length,
         })),
       };
@@ -1353,11 +1355,15 @@ class DashboardServer extends EventEmitter {
 
         // Get ahead/behind counts relative to upstream
         try {
-          const counts = execFileSync('git', ['rev-list', '--left-right', '--count', 'HEAD...@{u}'], {
-            cwd,
-            encoding: 'utf8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-          }).trim();
+          const counts = execFileSync(
+            'git',
+            ['rev-list', '--left-right', '--count', 'HEAD...@{u}'],
+            {
+              cwd,
+              encoding: 'utf8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+            }
+          ).trim();
           const [ahead, behind] = counts.split(/\s+/).map(Number);
           entry.ahead = ahead || 0;
           entry.behind = behind || 0;
@@ -1433,7 +1439,9 @@ class DashboardServer extends EventEmitter {
         }
       }
 
-      session.send(createNotification('info', 'Editor', `Opened ${require('path').basename(fullPath)}`));
+      session.send(
+        createNotification('info', 'Editor', `Opened ${require('path').basename(fullPath)}`)
+      );
     } catch (error) {
       console.error('[Open File Error]', error.message);
       session.send(createError('OPEN_FILE_ERROR', `Failed to open file: ${error.message}`));

package/lib/feedback.js

@@ -72,9 +72,10 @@ class Feedback {
   constructor(options = {}) {
     this.isTTY = options.isTTY !== undefined ? options.isTTY : process.stdout.isTTY;
     this.indent = options.indent || 0;
-    this.quiet = options.quiet !== undefined
-      ? options.quiet
-      : (process.env.AGILEFLOW_QUIET === '1' || process.env.AGILEFLOW_QUIET === 'true');
+    this.quiet =
+      options.quiet !== undefined
+        ? options.quiet
+        : process.env.AGILEFLOW_QUIET === '1' || process.env.AGILEFLOW_QUIET === 'true';
     this.verbose = options.verbose || false;
   }
 

package/lib/merge-operations.js

@@ -270,14 +270,23 @@ function integrateSession(sessionId, options = {}, loadRegistry, saveRegistry, r
       fs.mkdirSync(notifyDir, { recursive: true });
     }
     const notifyPath = path.join(notifyDir, 'last-merge.json');
-    fs.writeFileSync(notifyPath, JSON.stringify({
-      merged_at: new Date().toISOString(),
-      session_id: sessionId,
-      branch: branchName,
-      strategy,
-      commit_message: commitMessage,
-    }, null, 2));
-  } catch (e) { /* ignore notification write failures */ }
+    fs.writeFileSync(
+      notifyPath,
+      JSON.stringify(
+        {
+          merged_at: new Date().toISOString(),
+          session_id: sessionId,
+          branch: branchName,
+          strategy,
+          commit_message: commitMessage,
+        },
+        null,
+        2
+      )
+    );
+  } catch (e) {
+    /* ignore notification write failures */
+  }
 
   // Delete worktree first (before branch, as worktree holds ref)
   if (deleteWorktree && session.path !== ROOT && fs.existsSync(session.path)) {

package/lib/session-operations.js

@@ -178,7 +178,9 @@ function createSessionOperations(deps) {
     registry.next_id++;
     const isMain = cwd === ROOT && !isGitWorktree(cwd);
     const detectedType =
-      threadType && THREAD_TYPES.includes(threadType) ? threadType : detectThreadType(null, !isMain);
+      threadType && THREAD_TYPES.includes(threadType)
+        ? threadType
+        : detectThreadType(null, !isMain);
 
     registry.sessions[sessionId] = {
       path: cwd,
@@ -210,7 +212,12 @@ function createSessionOperations(deps) {
     const session = registry.sessions[sessionId];
     if (!session) return null;
     const threadType = session.thread_type || (session.is_main ? 'base' : 'parallel');
-    return { id: sessionId, ...session, thread_type: threadType, active: isSessionActive(sessionId) };
+    return {
+      id: sessionId,
+      ...session,
+      thread_type: threadType,
+      active: isSessionActive(sessionId),
+    };
   }
 
   async function createSession(options = {}) {
@@ -248,7 +255,10 @@ function createSessionOperations(deps) {
     );
     let branchCreatedByUs = false;
     if (checkRef.status !== 0) {
-      const createBranch = spawnSync('git', ['branch', branchName], { cwd: ROOT, encoding: 'utf8' });
+      const createBranch = spawnSync('git', ['branch', branchName], {
+        cwd: ROOT,
+        encoding: 'utf8',
+      });
       if (createBranch.status !== 0) {
         return {
           success: false,

package/lib/session-switching.js

@@ -127,7 +127,12 @@ function createSessionSwitching(deps) {
       return { success: false, error: 'Session not found' };
     const session = registry.sessions[targetId];
     const threadType = session.thread_type || (session.is_main ? 'base' : 'parallel');
-    return { success: true, thread_type: threadType, session_id: targetId, is_main: session.is_main };
+    return {
+      success: true,
+      thread_type: threadType,
+      session_id: targetId,
+      is_main: session.is_main,
+    };
   }
 
   function setSessionThreadType(sessionId, threadType) {

package/package.json

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

package/scripts/agileflow-configure.js

@@ -323,7 +323,8 @@ function main() {
 
   // Enable/disable specific features with progress tracking
   const totalChanges = enable.length + disable.length;
-  const featureTask = totalChanges > 1 ? feedback.task('Applying feature changes', totalChanges) : null;
+  const featureTask =
+    totalChanges > 1 ? feedback.task('Applying feature changes', totalChanges) : null;
 
   // Enable specific features
   enable.forEach(f => {

package/scripts/agileflow-welcome.js

@@ -1965,9 +1965,12 @@ async function main() {
   // Check for multiple Claude processes in the same working directory
   if (processCleanup) {
     try {
-      // Check if auto-kill is enabled in metadata
+      // Auto-kill is explicitly opt-in at runtime.
+      // Even if metadata has autoKill=true from older configs, we require
+      // AGILEFLOW_PROCESS_CLEANUP_AUTOKILL=1 to prevent accidental session kills.
       const metadata = cache?.metadata;
-      const autoKill = metadata?.features?.processCleanup?.autoKill === true;
+      const autoKillConfigured = metadata?.features?.processCleanup?.autoKill === true;
+      const autoKill = autoKillConfigured && process.env.AGILEFLOW_PROCESS_CLEANUP_AUTOKILL === '1';
 
       const cleanupResult = processCleanup.cleanupDuplicateProcesses({
         rootDir,
@@ -1987,15 +1990,17 @@ async function main() {
             console.log(`${c.dim}   └─ PID ${proc.pid} (${proc.method})${c.reset}`);
           });
         } else {
-          // Warn only (auto-kill not enabled)
+          // Warn only (auto-kill disabled or skipped by safety guards)
           console.log(
             `${c.amber}⚠️  ${cleanupResult.duplicates} other Claude process(es) in same directory${c.reset}`
           );
           console.log(`${c.slate}   This may cause slowdowns and freezing. Options:${c.reset}`);
           console.log(`${c.slate}   • Close duplicate Claude windows/tabs${c.reset}`);
-          console.log(
-            `${c.slate}   • Run ${c.skyBlue}/agileflow:configure --enable=processcleanup${c.slate} for auto-cleanup${c.reset}`
-          );
+          if (autoKillConfigured) {
+            console.log(
+              `${c.slate}   • Auto-kill configured but runtime opt-in is off (safer default)${c.reset}`
+            );
+          }
         }
 
         if (cleanupResult.errors.length > 0) {

package/scripts/claude-tmux.sh

@@ -122,6 +122,27 @@ if [ "$NO_TMUX" = true ]; then
   exec claude "$@"
 fi
 
+# ── Self-healing: ensure tmux socket directory exists ──────────────────────
+# macOS clears /private/tmp/ on reboot, which removes the tmux socket dir.
+# This causes "error connecting to ... (No such file or directory)" on every
+# tmux command. We fix it automatically so users never see this error.
+# Must run BEFORE any tmux command (including --kill, --attach, --refresh).
+if command -v tmux &> /dev/null; then
+  _TMUX_BASE="${TMUX_TMPDIR:-${TMPDIR:-/tmp}}"
+  # Strip trailing slash(es) to avoid double-slash in path
+  _TMUX_BASE="${_TMUX_BASE%/}"
+  _TMUX_SOCK_DIR="${_TMUX_BASE}/tmux-$(id -u)"
+  if [ ! -d "$_TMUX_SOCK_DIR" ]; then
+    mkdir -p "$_TMUX_SOCK_DIR" 2>/dev/null && chmod 700 "$_TMUX_SOCK_DIR" 2>/dev/null
+    if [ ! -d "$_TMUX_SOCK_DIR" ]; then
+      echo "Warning: Could not create tmux socket directory ($_TMUX_SOCK_DIR)."
+      echo "Running claude without tmux."
+      exec claude "$@"
+    fi
+  fi
+  unset _TMUX_BASE _TMUX_SOCK_DIR
+fi
+
 # Generate directory name (used for session name patterns)
 DIR_NAME=$(basename "$(pwd)")
 

package/scripts/damage-control-bash.js

@@ -15,7 +15,37 @@
  * Usage: Configured as PreToolUse hook in .claude/settings.json
  */
 
-const { createBashHook } = require('./lib/damage-control-utils');
+const fs = require('fs');
+const path = require('path');
 
-// Run the hook using factory
-createBashHook()();
+function loadDamageControlUtils() {
+  const candidates = [
+    path.join(__dirname, 'lib', 'damage-control-utils.js'),
+    path.join(process.cwd(), '.agileflow', 'scripts', 'lib', 'damage-control-utils.js'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        return require(candidate);
+      }
+    } catch (e) {
+      // Try next candidate
+    }
+  }
+
+  return null;
+}
+
+const utils = loadDamageControlUtils();
+if (!utils || typeof utils.createBashHook !== 'function') {
+  // Fail-open: never block Bash tool because hook bootstrap failed.
+  process.exit(0);
+}
+
+try {
+  utils.createBashHook()();
+} catch (e) {
+  // Fail-open on runtime errors to avoid breaking CLI workflows.
+  process.exit(0);
+}

package/scripts/damage-control-edit.js

@@ -12,7 +12,37 @@
  * Usage: Configured as PreToolUse hook in .claude/settings.json
  */
 
-const { createPathHook } = require('./lib/damage-control-utils');
+const fs = require('fs');
+const path = require('path');
 
-// Run the hook using factory
-createPathHook('edit')();
+function loadDamageControlUtils() {
+  const candidates = [
+    path.join(__dirname, 'lib', 'damage-control-utils.js'),
+    path.join(process.cwd(), '.agileflow', 'scripts', 'lib', 'damage-control-utils.js'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        return require(candidate);
+      }
+    } catch (e) {
+      // Try next candidate
+    }
+  }
+
+  return null;
+}
+
+const utils = loadDamageControlUtils();
+if (!utils || typeof utils.createPathHook !== 'function') {
+  // Fail-open: never block Edit tool because hook bootstrap failed.
+  process.exit(0);
+}
+
+try {
+  utils.createPathHook('edit')();
+} catch (e) {
+  // Fail-open on runtime errors to avoid breaking CLI workflows.
+  process.exit(0);
+}

package/scripts/damage-control-write.js

@@ -12,7 +12,37 @@
  * Usage: Configured as PreToolUse hook in .claude/settings.json
  */
 
-const { createPathHook } = require('./lib/damage-control-utils');
+const fs = require('fs');
+const path = require('path');
 
-// Run the hook using factory
-createPathHook('write')();
+function loadDamageControlUtils() {
+  const candidates = [
+    path.join(__dirname, 'lib', 'damage-control-utils.js'),
+    path.join(process.cwd(), '.agileflow', 'scripts', 'lib', 'damage-control-utils.js'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        return require(candidate);
+      }
+    } catch (e) {
+      // Try next candidate
+    }
+  }
+
+  return null;
+}
+
+const utils = loadDamageControlUtils();
+if (!utils || typeof utils.createPathHook !== 'function') {
+  // Fail-open: never block Write tool because hook bootstrap failed.
+  process.exit(0);
+}
+
+try {
+  utils.createPathHook('write')();
+} catch (e) {
+  // Fail-open on runtime errors to avoid breaking CLI workflows.
+  process.exit(0);
+}

package/scripts/lib/configure-features.js

@@ -287,7 +287,7 @@ function enableFeature(feature, options = {}, version) {
         features: {
           processCleanup: {
             enabled: true,
-            autoKill: true,
+            autoKill: false,
             version,
             at: new Date().toISOString(),
           },
@@ -296,9 +296,10 @@ function enableFeature(feature, options = {}, version) {
       version
     );
     success('Process cleanup enabled');
-    warn('⚠️  Duplicate Claude processes will be automatically terminated on session start');
+    info('Duplicate Claude processes will be detected and reported on session start');
+    info('Auto-kill is disabled by default for safety');
     info('   Only affects processes in the SAME working directory (worktrees are safe)');
-    info('   Prevents freezing caused by multiple Claude instances competing for resources');
+    info('   Set AGILEFLOW_PROCESS_CLEANUP_AUTOKILL=1 to opt in to auto-kill at runtime');
     return true;
   }
 

package/scripts/lib/configure-repair.js

@@ -265,9 +265,10 @@ function repairScripts(targetFeature = null) {
   // Ensure scripts directory exists
   ensureDir(scriptsDir);
 
-  const bar = scriptsToCheck.length > 5
-    ? feedback.progressBar('Checking scripts', scriptsToCheck.length)
-    : null;
+  const bar =
+    scriptsToCheck.length > 5
+      ? feedback.progressBar('Checking scripts', scriptsToCheck.length)
+      : null;
 
   for (const [script, scriptInfo] of scriptsToCheck) {
     const destPath = path.join(scriptsDir, script);

package/scripts/lib/process-cleanup.js

@@ -82,6 +82,153 @@ function getCwdForPid(pid) {
   }
 }
 
+/**
+ * Get process start time in milliseconds.
+ * Used for safety checks when deciding whether a process is older/newer.
+ *
+ * @param {number} pid - Process ID
+ * @returns {number|null}
+ */
+function getProcessStartTime(pid) {
+  if (!pid || typeof pid !== 'number') return null;
+
+  if (process.platform === 'linux') {
+    try {
+      const stat = fs.statSync(`/proc/${pid}`);
+      return Number.isFinite(stat.ctimeMs) ? stat.ctimeMs : null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  if (process.platform === 'darwin') {
+    try {
+      const output = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+        encoding: 'utf8',
+        timeout: 2000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const ts = new Date(output.trim()).getTime();
+      return Number.isFinite(ts) ? ts : null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get parent PID for a process.
+ * Works on Linux (/proc) and macOS (ps).
+ *
+ * @param {number} pid - Process ID
+ * @returns {number|null}
+ */
+function getParentPid(pid) {
+  if (!pid || typeof pid !== 'number') return null;
+
+  if (process.platform === 'linux') {
+    try {
+      // /proc/<pid>/stat format:
+      // pid (comm) state ppid ...
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const closeParen = stat.lastIndexOf(')');
+      if (closeParen === -1) return null;
+      const remainder = stat.slice(closeParen + 2).trim(); // state ppid ...
+      const fields = remainder.split(/\s+/);
+      const ppid = parseInt(fields[1], 10);
+      return Number.isFinite(ppid) ? ppid : null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  if (process.platform === 'darwin') {
+    try {
+      const output = execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], {
+        encoding: 'utf8',
+        timeout: 2000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const ppid = parseInt(output.trim(), 10);
+      return Number.isFinite(ppid) ? ppid : null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get command-line args for a PID.
+ *
+ * @param {number} pid - Process ID
+ * @returns {string[]}
+ */
+function getArgsForPid(pid) {
+  if (!pid || typeof pid !== 'number') return [];
+
+  if (process.platform === 'linux') {
+    try {
+      const cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+      return parseCmdline(cmdline);
+    } catch (e) {
+      return [];
+    }
+  }
+
+  if (process.platform === 'darwin') {
+    try {
+      const output = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], {
+        encoding: 'utf8',
+        timeout: 2000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const cmd = output.trim();
+      return cmd ? [cmd] : [];
+    } catch (e) {
+      return [];
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Walk process ancestry and find the nearest Claude process.
+ *
+ * Hooks are typically executed as:
+ *   claude -> shell (bash/sh) -> hook command (node)
+ * so `process.ppid` is often the shell, not Claude.
+ *
+ * @param {number} startPid - PID to start from (defaults to current process)
+ * @param {number} maxDepth - Max parent hops
+ * @returns {number|null}
+ */
+function findClaudeAncestorPid(startPid = process.pid, maxDepth = 12) {
+  let pid = startPid;
+  const visited = new Set();
+
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const parentPid = getParentPid(pid);
+    if (!parentPid || parentPid <= 1 || visited.has(parentPid)) {
+      return null;
+    }
+    visited.add(parentPid);
+
+    const parentArgs = getArgsForPid(parentPid);
+    if (isClaudeProcess(parentArgs)) {
+      return parentPid;
+    }
+
+    pid = parentPid;
+  }
+
+  return null;
+}
+
 /**
  * Find all Claude Code processes on the system
  * @returns {Array<{pid: number, cwd: string|null, cmdline: string, startTime: number}>}
@@ -195,14 +342,14 @@ function findClaudeProcesses() {
  *
  * @param {string} currentCwd - Current working directory
  * @param {number} currentPid - Current session's PID (to exclude)
- * @returns {Array} Duplicate processes (excluding current)
+ * @returns {Array} Duplicate processes (excluding current if known)
  */
 function findDuplicatesInCwd(currentCwd, currentPid) {
   const allClaude = findClaudeProcesses();
 
   return allClaude.filter(proc => {
-    // Exclude current session
-    if (proc.pid === currentPid) return false;
+    // Exclude current session when known
+    if (currentPid && proc.pid === currentPid) return false;
 
     // Must have cwd to compare
     if (!proc.cwd || !currentCwd) return false;
@@ -274,14 +421,15 @@ function killProcessGracefully(pid, options = {}) {
 /**
  * Get current session's PID from process ancestry
  *
- * The Claude Code process is typically the parent of this script.
- * We use process.ppid to identify it.
+ * The Claude process is usually an ancestor (often grandparent):
+ *   claude -> bash -> node hook
  *
- * @returns {number}
+ * If no Claude ancestor is found, returns null.
+ *
+ * @returns {number|null}
  */
 function getCurrentSessionPid() {
-  // The claude process is our parent (this script is run by claude)
-  return process.ppid || process.pid;
+  return findClaudeAncestorPid(process.pid);
 }
 
 /**
@@ -298,6 +446,7 @@ function cleanupDuplicateProcesses(options = {}) {
 
   const currentCwd = rootDir || process.cwd();
   const currentPid = getCurrentSessionPid();
+  const currentStartTime = getProcessStartTime(currentPid);
   const duplicates = findDuplicatesInCwd(currentCwd, currentPid);
 
   const result = {
@@ -305,8 +454,9 @@ function cleanupDuplicateProcesses(options = {}) {
     processes: duplicates,
     killed: [],
     errors: [],
-    autoKillEnabled: autoKill,
+    autoKillEnabled: autoKill && !!currentPid,
     currentPid,
+    currentStartTime,
   };
 
   if (duplicates.length === 0) {
@@ -318,8 +468,32 @@ function cleanupDuplicateProcesses(options = {}) {
     return result;
   }
 
+  // Safety gate: if we can't identify the current Claude session PID,
+  // never auto-kill anything.
+  if (!currentPid) {
+    result.errors.push({
+      error: 'Could not determine current Claude session PID; auto-kill skipped',
+    });
+    return result;
+  }
+
+  // Safety gate: only kill processes that are clearly older than current session.
+  // This prevents terminating the session that just started.
+  const olderDuplicates = duplicates.filter(proc => {
+    if (!proc || !proc.pid || proc.pid === currentPid) return false;
+    if (!currentStartTime || !proc.startTime) return false;
+    return proc.startTime < currentStartTime;
+  });
+
+  if (olderDuplicates.length === 0) {
+    result.errors.push({
+      error: 'No clearly older duplicate processes found; auto-kill skipped',
+    });
+    return result;
+  }
+
   // Safety limit - don't kill more than MAX_PROCESSES_TO_KILL
-  const toKill = duplicates.slice(0, MAX_PROCESSES_TO_KILL);
+  const toKill = olderDuplicates.slice(0, MAX_PROCESSES_TO_KILL);
 
   for (const proc of toKill) {
     const killResult = killProcessGracefully(proc.pid, { dryRun });
@@ -364,6 +538,10 @@ module.exports = {
   parseCmdline,
   isClaudeProcess,
   getCwdForPid,
+  getProcessStartTime,
+  getParentPid,
+  getArgsForPid,
+  findClaudeAncestorPid,
 
   // Constants
   KILL_GRACE_PERIOD_MS,