agileflow 2.94.0 → 2.95.0

package/scripts/session-manager.js

@@ -25,6 +25,7 @@ const { safeReadJSON } = require('../lib/errors');
 const { isValidBranchName, isValidSessionNickname } = require('../lib/validate');
 
 const { SessionRegistry } = require('../lib/session-registry');
+const { sessionThreadMachine } = require('../lib/state-machine');
 
 const ROOT = getProjectRoot();
 const SESSIONS_DIR = path.join(getAgileflowDir(ROOT), 'sessions');
@@ -32,6 +33,8 @@ const REGISTRY_PATH = path.join(SESSIONS_DIR, 'registry.json');
 
 // Injectable registry instance for testing
 let _registryInstance = null;
+// Track whether we've done the one-time initialization (file existence check)
+let _registryInitialized = false;
 
 /**
  * Get the registry instance (singleton, injectable for testing)
@@ -50,6 +53,18 @@ function getRegistryInstance() {
  */
 function injectRegistry(registry) {
   _registryInstance = registry;
+  _registryInitialized = false; // Reset initialization state when injecting
+}
+
+/**
+ * Reset registry cache state (for testing or forced refresh).
+ * Clears both the initialization flag and the underlying SessionRegistry cache.
+ */
+function resetRegistryCache() {
+  _registryInitialized = false;
+  if (_registryInstance) {
+    _registryInstance.invalidateCache();
+  }
 }
 
 // Ensure sessions directory exists
@@ -59,19 +74,36 @@ function ensureSessionsDir() {
   }
 }
 
-// Load or create registry (uses injectable SessionRegistry)
-// Preserves original behavior: saves default registry if file didn't exist
+/**
+ * Load registry with request-level caching.
+ *
+ * Uses SessionRegistry's built-in 10-second TTL cache for repeated reads.
+ * Only performs file existence check once per session-manager lifecycle,
+ * avoiding redundant fs.existsSync() calls on every loadRegistry() invocation.
+ *
+ * @returns {Object} Registry data
+ */
 function loadRegistry() {
   const registryInstance = getRegistryInstance();
-  const fileExistedBefore = fs.existsSync(registryInstance.registryPath);
-  const data = registryInstance.loadSync();
 
-  // If file didn't exist, save the default to disk (original behavior)
-  if (!fileExistedBefore) {
-    registryInstance.saveSync(data);
+  // One-time initialization: check if file exists and create default if needed
+  // This avoids calling fs.existsSync() on every loadRegistry() call
+  if (!_registryInitialized) {
+    const fileExistedBefore = fs.existsSync(registryInstance.registryPath);
+    const data = registryInstance.loadSync();
+
+    // If file didn't exist, save the default to disk (original behavior)
+    if (!fileExistedBefore) {
+      registryInstance.saveSync(data);
+    }
+
+    _registryInitialized = true;
+    return data;
   }
 
-  return data;
+  // Subsequent calls: rely on SessionRegistry's TTL cache (10 seconds)
+  // This avoids disk I/O for repeated reads within the same command execution
+  return registryInstance.loadSync();
 }
 
 // Save registry (uses injectable SessionRegistry)
@@ -152,6 +184,13 @@ function isSessionActive(sessionId) {
   return isPidAlive(parseInt(lock.pid, 10));
 }
 
+// Check if session is active (async version for parallel batch operations)
+async function isSessionActiveAsync(sessionId) {
+  const lock = await readLockAsync(sessionId);
+  if (!lock || !lock.pid) return false;
+  return isPidAlive(parseInt(lock.pid, 10));
+}
+
 // Clean up stale locks (with detailed tracking) - sync version for backward compatibility
 function cleanupStaleLocks(registry, options = {}) {
   const { verbose = false, dryRun = false } = options;
@@ -443,6 +482,27 @@ function getCurrentStory() {
 // Thread type enum values
 const THREAD_TYPES = ['base', 'parallel', 'chained', 'fusion', 'big', 'long'];
 
+/**
+ * Check if a directory is a git worktree (not the main repo).
+ * In a worktree, .git is a file pointing to the main repo's .git/worktrees/<name>
+ * In the main repo, .git is a directory.
+ *
+ * @param {string} dir - Directory to check
+ * @returns {boolean} True if dir is a git worktree
+ */
+function isGitWorktree(dir) {
+  const gitPath = path.join(dir, '.git');
+  try {
+    const stat = fs.lstatSync(gitPath);
+    // In a worktree, .git is a file containing "gitdir: /path/to/main/.git/worktrees/<name>"
+    // In the main repo, .git is a directory
+    return stat.isFile();
+  } catch (e) {
+    // .git doesn't exist - not a git repo at all
+    return false;
+  }
+}
+
 // Auto-detect thread type from context
 function detectThreadType(session, isWorktree = false) {
   // Worktree sessions are parallel threads
@@ -491,7 +551,9 @@ function registerSession(nickname = null, threadType = null) {
   const sessionId = String(registry.next_id);
   registry.next_id++;
 
-  const isMain = cwd === ROOT;
+  // A session is "main" only if it's at the project root AND not a git worktree
+  // Worktrees have .git as a file (not directory), pointing to the main repo
+  const isMain = cwd === ROOT && !isGitWorktree(cwd);
   const detectedType =
     threadType && THREAD_TYPES.includes(threadType) ? threadType : detectThreadType(null, !isMain);
 
@@ -817,6 +879,25 @@ async function createSession(options = {}) {
     }
   }
 
+  // Symlink .agileflow/sessions/ to main project (shared session registry across worktrees)
+  // This ensures all sessions see the same registry, preventing is_main bugs and sync issues
+  const sessionsSymlinkSrc = path.join(ROOT, '.agileflow', 'sessions');
+  const sessionsSymlinkDest = path.join(worktreePath, '.agileflow', 'sessions');
+  if (fs.existsSync(sessionsSymlinkSrc)) {
+    try {
+      // Remove the copied sessions directory (it was copied above with .agileflow)
+      if (fs.existsSync(sessionsSymlinkDest)) {
+        fs.rmSync(sessionsSymlinkDest, { recursive: true, force: true });
+      }
+      // Create relative symlink to main project's sessions directory
+      const relPath = path.relative(path.dirname(sessionsSymlinkDest), sessionsSymlinkSrc);
+      fs.symlinkSync(relPath, sessionsSymlinkDest, 'dir');
+    } catch (e) {
+      // Non-fatal: log but continue - the copied version will work, just won't be synchronized
+      console.warn(`Warning: Could not symlink sessions directory: ${e.message}`);
+    }
+  }
+
   // Symlink docs/ to main project docs (shared state: status.json, session-state.json, bus/)
   // This enables story claiming, status bus, and session coordination across worktrees
   const foldersToSymlink = ['docs'];
@@ -902,6 +983,39 @@ function getSessions() {
   };
 }
 
+// Get all sessions with status (async parallel version - faster for 10+ sessions)
+// US-0190: Uses Promise.all() to batch lock file reads instead of sequential
+async function getSessionsAsync() {
+  const registry = loadRegistry();
+  const cleanupResult = await cleanupStaleLocksAsync(registry);
+
+  const sessionEntries = Object.entries(registry.sessions);
+  const cwd = process.cwd();
+
+  // Read all locks in parallel using Promise.all()
+  const sessionResults = await Promise.all(
+    sessionEntries.map(async ([id, session]) => {
+      const active = await isSessionActiveAsync(id);
+      return {
+        id,
+        ...session,
+        active,
+        current: session.path === cwd,
+      };
+    })
+  );
+
+  // Sort by ID (numeric)
+  sessionResults.sort((a, b) => parseInt(a.id) - parseInt(b.id));
+
+  // Return count for backward compat, plus detailed info
+  return {
+    sessions: sessionResults,
+    cleaned: cleanupResult.count,
+    cleanedSessions: cleanupResult.sessions,
+  };
+}
+
 // Get count of active sessions (excluding current)
 function getActiveSessionCount() {
   const { sessions } = getSessions();
@@ -1249,6 +1363,177 @@ function integrateSession(sessionId, options = {}) {
   return result;
 }
 
+/**
+ * Generate auto commit message for session
+ * @param {Object} session - Session object
+ * @returns {string} Generated commit message
+ */
+function generateCommitMessage(session) {
+  const nickname = session.nickname || `session-${session.id || 'unknown'}`;
+  const branch = session.branch || 'unknown';
+  return `chore: commit uncommitted changes from ${nickname}\n\nBranch: ${branch}`;
+}
+
+/**
+ * Commit all changes in session worktree
+ * @param {string} sessionId - Session ID
+ * @param {Object} options - { message?: string }
+ * @returns {{ success: boolean, commitHash?: string, message?: string, error?: string }}
+ */
+function commitChanges(sessionId, options = {}) {
+  const registry = loadRegistry();
+  const session = registry.sessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session ${sessionId} not found` };
+  }
+
+  if (!fs.existsSync(session.path)) {
+    return { success: false, error: `Session directory not found: ${session.path}` };
+  }
+
+  // Stage all changes
+  const addResult = spawnSync('git', ['add', '-A'], {
+    cwd: session.path,
+    encoding: 'utf8',
+  });
+
+  if (addResult.status !== 0) {
+    return { success: false, error: `Failed to stage changes: ${addResult.stderr}` };
+  }
+
+  // Generate commit message if not provided
+  const message = options.message || generateCommitMessage({ ...session, id: sessionId });
+
+  // Create commit
+  const commitResult = spawnSync('git', ['commit', '-m', message], {
+    cwd: session.path,
+    encoding: 'utf8',
+  });
+
+  if (commitResult.status !== 0) {
+    // Check if nothing to commit (all changes already staged/committed)
+    if (commitResult.stdout && commitResult.stdout.includes('nothing to commit')) {
+      return { success: true, message: 'No changes to commit', commitHash: null };
+    }
+    return {
+      success: false,
+      error: `Failed to commit: ${commitResult.stderr || commitResult.stdout}`,
+    };
+  }
+
+  // Get commit hash
+  const hashResult = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: session.path,
+    encoding: 'utf8',
+  });
+
+  return {
+    success: true,
+    commitHash: hashResult.stdout?.trim(),
+    message,
+  };
+}
+
+/**
+ * Stash changes in session worktree
+ * @param {string} sessionId - Session ID
+ * @returns {{ success: boolean, message?: string, error?: string }}
+ */
+function stashChanges(sessionId) {
+  const registry = loadRegistry();
+  const session = registry.sessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session ${sessionId} not found` };
+  }
+
+  if (!fs.existsSync(session.path)) {
+    return { success: false, error: `Session directory not found: ${session.path}` };
+  }
+
+  const stashMsg = `AgileFlow: session ${sessionId} merge prep`;
+  const result = spawnSync('git', ['stash', 'push', '-m', stashMsg], {
+    cwd: session.path,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    return { success: false, error: `Failed to stash: ${result.stderr}` };
+  }
+
+  // Check if stash was actually created (might be "No local changes to save")
+  if (result.stdout && result.stdout.includes('No local changes to save')) {
+    return { success: true, message: 'No changes to stash', stashCreated: false };
+  }
+
+  return { success: true, message: stashMsg, stashCreated: true };
+}
+
+/**
+ * Unstash changes (pop stash)
+ * @param {string} sessionId - Session ID (for error messages, uses current cwd)
+ * @returns {{ success: boolean, error?: string }}
+ */
+function unstashChanges(sessionId) {
+  // Note: After merge, the session worktree is deleted. Stash is popped on main.
+  // So we use ROOT instead of session.path
+
+  const result = spawnSync('git', ['stash', 'pop'], {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    // Check if no stash exists
+    if (result.stderr && result.stderr.includes('No stash entries found')) {
+      return { success: true, message: 'No stash to pop' };
+    }
+    return { success: false, error: `Failed to unstash: ${result.stderr}` };
+  }
+
+  return { success: true };
+}
+
+/**
+ * Discard all uncommitted changes in session worktree
+ * @param {string} sessionId - Session ID
+ * @returns {{ success: boolean, error?: string }}
+ */
+function discardChanges(sessionId) {
+  const registry = loadRegistry();
+  const session = registry.sessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session ${sessionId} not found` };
+  }
+
+  if (!fs.existsSync(session.path)) {
+    return { success: false, error: `Session directory not found: ${session.path}` };
+  }
+
+  // Reset staged changes
+  spawnSync('git', ['reset', 'HEAD'], {
+    cwd: session.path,
+    encoding: 'utf8',
+  });
+
+  // Discard working directory changes
+  const checkoutResult = spawnSync('git', ['checkout', '--', '.'], {
+    cwd: session.path,
+    encoding: 'utf8',
+  });
+
+  if (checkoutResult.status !== 0) {
+    return { success: false, error: `Failed to discard changes: ${checkoutResult.stderr}` };
+  }
+
+  // Note: Not cleaning untracked files by default (safety measure)
+  // Users can add --clean-untracked flag if needed
+
+  return { success: true };
+}
+
 // Session phases for Kanban-style visualization
 const SESSION_PHASES = {
   TODO: 'todo',
@@ -1318,6 +1603,109 @@ function getSessionPhase(session) {
   }
 }
 
+// Execute git command asynchronously (US-0191: Promise-based, non-blocking)
+function execGitAsync(args, cwd) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', data => {
+      stdout += data;
+    });
+    proc.stderr.on('data', data => {
+      stderr += data;
+    });
+
+    proc.on('error', err => {
+      reject(err);
+    });
+
+    proc.on('close', code => {
+      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), code });
+    });
+  });
+}
+
+// Detect session phase asynchronously (US-0191: Non-blocking git calls)
+async function getSessionPhaseAsync(session) {
+  // If merged_at field exists, session was merged
+  if (session.merged_at) {
+    return SESSION_PHASES.MERGED;
+  }
+
+  // If is_main, it's the merged/main column
+  if (session.is_main) {
+    return SESSION_PHASES.MERGED;
+  }
+
+  // Check git state for the session
+  try {
+    const sessionPath = session.path;
+    if (!fs.existsSync(sessionPath)) {
+      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 commitResult = await execGitAsync(
+      ['rev-list', '--count', `${mainBranch}..HEAD`],
+      sessionPath
+    );
+    const commits = parseInt(commitResult.stdout || '0', 10);
+
+    if (commits === 0) {
+      gitCache.set(cacheKey, SESSION_PHASES.TODO);
+      return SESSION_PHASES.TODO;
+    }
+
+    // Check for uncommitted changes
+    const statusResult = await execGitAsync(['status', '--porcelain'], sessionPath);
+    const status = statusResult.stdout;
+
+    let phase;
+    if (status === '') {
+      // No uncommitted changes = ready for review
+      phase = SESSION_PHASES.REVIEW;
+    } else {
+      // Has commits but also uncommitted changes = still coding
+      phase = SESSION_PHASES.CODING;
+    }
+
+    gitCache.set(cacheKey, phase);
+    return phase;
+  } catch (e) {
+    // On error, assume coding phase
+    return SESSION_PHASES.CODING;
+  }
+}
+
+// Get phases for multiple sessions in parallel (US-0191: Promise.all batching)
+async function getSessionPhasesAsync(sessions) {
+  const phasePromises = sessions.map(async session => {
+    const phase = await getSessionPhaseAsync(session);
+    return { session, phase };
+  });
+
+  const results = await Promise.all(phasePromises);
+
+  // Return as array with phase included
+  return results.map(({ session, phase }) => ({
+    ...session,
+    phase,
+  }));
+}
+
 // Render Kanban-style board visualization
 function renderKanbanBoard(sessions) {
   const lines = [];
@@ -1425,6 +1813,115 @@ function renderKanbanBoard(sessions) {
   return lines.join('\n');
 }
 
+// Render Kanban-style board visualization (async parallel version - US-0191)
+async function renderKanbanBoardAsync(sessions) {
+  const lines = [];
+
+  // Get all phases in parallel using Promise.all
+  const sessionsWithPhases = await getSessionPhasesAsync(sessions);
+
+  // Group sessions by phase
+  const byPhase = {
+    [SESSION_PHASES.TODO]: [],
+    [SESSION_PHASES.CODING]: [],
+    [SESSION_PHASES.REVIEW]: [],
+    [SESSION_PHASES.MERGED]: [],
+  };
+
+  for (const session of sessionsWithPhases) {
+    byPhase[session.phase].push(session);
+  }
+
+  // Calculate column widths (min 12 chars)
+  const colWidth = 14;
+  const separator = '  ';
+
+  // Header
+  lines.push(`${c.cyan}Sessions (Kanban View):${c.reset}`);
+  lines.push('');
+
+  // Column headers
+  const headers = [
+    `${c.dim}TO DO${c.reset}`,
+    `${c.yellow}CODING${c.reset}`,
+    `${c.blue}REVIEW${c.reset}`,
+    `${c.green}MERGED${c.reset}`,
+  ];
+  lines.push(headers.map(h => h.padEnd(colWidth + 10)).join(separator)); // +10 for ANSI codes
+
+  // Top borders
+  const topBorder = `┌${'─'.repeat(colWidth)}┐`;
+  lines.push([topBorder, topBorder, topBorder, topBorder].join(separator));
+
+  // Find max rows needed
+  const maxRows = Math.max(
+    1,
+    byPhase[SESSION_PHASES.TODO].length,
+    byPhase[SESSION_PHASES.CODING].length,
+    byPhase[SESSION_PHASES.REVIEW].length,
+    byPhase[SESSION_PHASES.MERGED].length
+  );
+
+  // Render rows
+  for (let i = 0; i < maxRows; i++) {
+    const cells = [
+      SESSION_PHASES.TODO,
+      SESSION_PHASES.CODING,
+      SESSION_PHASES.REVIEW,
+      SESSION_PHASES.MERGED,
+    ].map(phase => {
+      const session = byPhase[phase][i];
+      if (!session) {
+        return `│${' '.repeat(colWidth)}│`;
+      }
+
+      // Format session info
+      const id = `[${session.id}]`;
+      const name = session.nickname || session.branch || '';
+      const truncName = name.length > colWidth - 5 ? name.slice(0, colWidth - 8) + '...' : name;
+      const content = `${id} ${truncName}`.slice(0, colWidth);
+
+      return `│${content.padEnd(colWidth)}│`;
+    });
+    lines.push(cells.join(separator));
+
+    // Second line with story
+    const storyCells = [
+      SESSION_PHASES.TODO,
+      SESSION_PHASES.CODING,
+      SESSION_PHASES.REVIEW,
+      SESSION_PHASES.MERGED,
+    ].map(phase => {
+      const session = byPhase[phase][i];
+      if (!session) {
+        return `│${' '.repeat(colWidth)}│`;
+      }
+
+      const story = session.story || '-';
+      const storyTrunc = story.length > colWidth - 2 ? story.slice(0, colWidth - 5) + '...' : story;
+
+      return `│${c.dim}${storyTrunc.padEnd(colWidth)}${c.reset}│`;
+    });
+    lines.push(storyCells.join(separator));
+  }
+
+  // Bottom borders
+  const bottomBorder = `└${'─'.repeat(colWidth)}┘`;
+  lines.push([bottomBorder, bottomBorder, bottomBorder, bottomBorder].join(separator));
+
+  // Summary
+  lines.push('');
+  const summary = [
+    `${c.dim}To Do: ${byPhase[SESSION_PHASES.TODO].length}${c.reset}`,
+    `${c.yellow}Coding: ${byPhase[SESSION_PHASES.CODING].length}${c.reset}`,
+    `${c.blue}Review: ${byPhase[SESSION_PHASES.REVIEW].length}${c.reset}`,
+    `${c.green}Merged: ${byPhase[SESSION_PHASES.MERGED].length}${c.reset}`,
+  ].join(' │ ');
+  lines.push(summary);
+
+  return lines.join('\n');
+}
+
 // Format sessions for display
 function formatSessionsTable(sessions) {
   const lines = [];
@@ -1629,7 +2126,9 @@ function main() {
         // Create new
         sessionId = String(registry.next_id);
         registry.next_id++;
-        const isMain = cwd === ROOT;
+        // A session is "main" only if it's at the project root AND not a git worktree
+        // Worktrees have .git as a file (not directory), pointing to the main repo
+        const isMain = cwd === ROOT && !isGitWorktree(cwd);
         registry.sessions[sessionId] = {
           path: cwd,
           branch,
@@ -1741,6 +2240,60 @@ function main() {
       break;
     }
 
+    case 'commit-changes': {
+      const sessionId = args[1];
+      if (!sessionId) {
+        console.log(JSON.stringify({ success: false, error: 'Session ID required' }));
+        return;
+      }
+      const options = {};
+      // Parse --message="..."
+      for (let i = 2; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--message=')) {
+          options.message = arg.slice(10);
+        } else if (arg === '--message' && args[i + 1]) {
+          options.message = args[++i];
+        }
+      }
+      const result = commitChanges(sessionId, options);
+      console.log(JSON.stringify(result));
+      break;
+    }
+
+    case 'stash': {
+      const sessionId = args[1];
+      if (!sessionId) {
+        console.log(JSON.stringify({ success: false, error: 'Session ID required' }));
+        return;
+      }
+      const result = stashChanges(sessionId);
+      console.log(JSON.stringify(result));
+      break;
+    }
+
+    case 'unstash': {
+      const sessionId = args[1];
+      if (!sessionId) {
+        console.log(JSON.stringify({ success: false, error: 'Session ID required' }));
+        return;
+      }
+      const result = unstashChanges(sessionId);
+      console.log(JSON.stringify(result));
+      break;
+    }
+
+    case 'discard-changes': {
+      const sessionId = args[1];
+      if (!sessionId) {
+        console.log(JSON.stringify({ success: false, error: 'Session ID required' }));
+        return;
+      }
+      const result = discardChanges(sessionId);
+      console.log(JSON.stringify(result));
+      break;
+    }
+
     case 'smart-merge': {
       const sessionId = args[1];
       if (!sessionId) {
@@ -1854,6 +2407,10 @@ ${c.cyan}Commands:${c.reset}
   integrate <id> [opts]   Merge session to main and cleanup
   smart-merge <id> [opts] Auto-resolve conflicts and merge
   merge-history           View merge audit log
+  commit-changes <id> [--message="..."]  Commit all uncommitted changes
+  stash <id>              Stash changes in session worktree
+  unstash <id>            Pop stash (after merge, on main)
+  discard-changes <id>    Discard all uncommitted changes
   help                    Show this help
 
 ${c.cyan}Merge Options (integrate & smart-merge):${c.reset}
@@ -2533,7 +3090,9 @@ function getSessionThreadType(sessionId = null) {
 }
 
 /**
- * Update thread type for a session.
+ * Update thread type for a session (without transition validation).
+ * For backward compatibility. Prefer transitionThread() for new code.
+ *
  * @param {string} sessionId - Session ID
  * @param {string} threadType - New thread type
  * @returns {{ success: boolean, error?: string }}
@@ -2557,11 +3116,104 @@ function setSessionThreadType(sessionId, threadType) {
   return { success: true, thread_type: threadType };
 }
 
+/**
+ * Transition session to a new thread type with validation.
+ *
+ * Uses sessionThreadMachine to validate that the transition is allowed.
+ * For example: parallel → fusion is valid, but chained → base is not.
+ *
+ * Thread Type Transitions:
+ * - base → parallel, big, long
+ * - parallel → base, fusion, chained
+ * - chained → parallel, fusion
+ * - fusion → base
+ * - big → parallel, fusion
+ * - long → base, parallel
+ *
+ * @param {string} sessionId - Session ID
+ * @param {string} targetType - Target thread type
+ * @param {Object} [options={}] - Transition options
+ * @param {boolean} [options.force=false] - Force transition even if invalid
+ * @returns {{ success: boolean, from?: string, to?: string, error?: string, forced?: boolean }}
+ */
+function transitionThread(sessionId, targetType, options = {}) {
+  const { force = false } = options;
+
+  const registry = loadRegistry();
+  const session = registry.sessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session ${sessionId} not found` };
+  }
+
+  // Get current thread type (default to 'base' for legacy sessions)
+  const currentType = session.thread_type || (session.is_main ? 'base' : 'parallel');
+
+  // Validate transition using state machine
+  const result = sessionThreadMachine.transition(currentType, targetType, { force });
+
+  if (!result.success) {
+    return {
+      success: false,
+      from: currentType,
+      to: targetType,
+      error: result.error,
+    };
+  }
+
+  // No-op if same type
+  if (result.noop) {
+    return {
+      success: true,
+      from: currentType,
+      to: targetType,
+      noop: true,
+    };
+  }
+
+  // Update registry
+  registry.sessions[sessionId].thread_type = targetType;
+  registry.sessions[sessionId].thread_transitioned_at = new Date().toISOString();
+  saveRegistry(registry);
+
+  return {
+    success: true,
+    from: currentType,
+    to: targetType,
+    forced: result.forced || false,
+  };
+}
+
+/**
+ * Get valid thread type transitions from current state.
+ *
+ * @param {string} sessionId - Session ID
+ * @returns {{ success: boolean, current?: string, validTransitions?: string[], error?: string }}
+ */
+function getValidThreadTransitions(sessionId) {
+  const registry = loadRegistry();
+  const session = registry.sessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session ${sessionId} not found` };
+  }
+
+  const currentType = session.thread_type || (session.is_main ? 'base' : 'parallel');
+  const validTransitions = sessionThreadMachine.getValidTransitions(currentType);
+
+  return {
+    success: true,
+    current: currentType,
+    validTransitions,
+  };
+}
+
 // Export for use as module
 module.exports = {
   // Registry injection (for testing)
   injectRegistry,
   getRegistryInstance,
+  resetRegistryCache, // US-0193: Reset initialization state for testing
   // Registry access (backward compatible)
   loadRegistry,
   saveRegistry,
@@ -2571,9 +3223,11 @@ module.exports = {
   getSession,
   createSession,
   getSessions,
+  getSessionsAsync, // US-0190: Parallel lock reads for 10+ sessions
   getActiveSessionCount,
   deleteSession,
   isSessionActive,
+  isSessionActiveAsync, // US-0190: Async version for batch operations
   cleanupStaleLocks,
   cleanupStaleLocksAsync,
   // Merge operations
@@ -2581,6 +3235,11 @@ module.exports = {
   checkMergeability,
   getMergePreview,
   integrateSession,
+  // Uncommitted changes handling (inline options for /session:end)
+  commitChanges,
+  stashChanges,
+  unstashChanges,
+  discardChanges,
   // Smart merge (auto-resolution)
   smartMerge,
   getConflictingFiles,
@@ -2596,10 +3255,17 @@ module.exports = {
   detectThreadType,
   getSessionThreadType,
   setSessionThreadType,
+  transitionThread, // US-0202: Validated thread type transitions
+  getValidThreadTransitions, // US-0202: Get valid transitions from current state
   // Kanban visualization
   SESSION_PHASES,
   getSessionPhase,
+  getSessionPhaseAsync, // US-0191: Async version with non-blocking git
+  getSessionPhasesAsync, // US-0191: Batch version with Promise.all()
   renderKanbanBoard,
+  renderKanbanBoardAsync, // US-0191: Async version using parallel git ops
+  // Internal utilities (for testing)
+  execGitAsync, // US-0191: Promise-based git command execution
 };
 
 // Run CLI if executed directly