agileflow 3.1.0 → 3.2.1

package/scripts/agileflow-welcome.js

@@ -9,6 +9,17 @@
  * - Archival status
  * - Session cleanup status
  * - Last commit
+ *
+ * PERFORMANCE OPTIMIZATION (US-0356):
+ * Phase 1: Table display + instant notifications (~300-350ms)
+ * Phase 2: Cached update check + instant post-table notifications
+ * Phase 3: Background deferred work via welcome-deferred.js
+ *   - npm update check (with cache write)
+ *   - Session health warnings
+ *   - Duplicate process detection
+ *   - Story claiming/file tracking cleanup
+ *   - Epic completion, ideation sync, automations
+ *   Deferred warnings saved to session-state.json, displayed next session.
  */
 
 const fs = require('fs');
@@ -26,22 +37,34 @@ const {
   getClaudeDir,
 } = require('../lib/paths');
 const { readJSONCached, readFileCached } = require('../lib/file-cache');
-
-// Session manager path (relative to script location)
-const SESSION_MANAGER_PATH = path.join(__dirname, 'session-manager.js');
-
-// PERFORMANCE OPTIMIZATION: Lazy-loaded session-manager module
-// Importing directly avoids ~50-150ms subprocess overhead per call.
-let _sessionManager;
-function getSessionManager() {
-  if (_sessionManager === undefined) {
-    try {
-      _sessionManager = require('./session-manager.js');
-    } catch (e) {
-      _sessionManager = null;
-    }
+const { tryOptional } = require('../lib/errors');
+const { createLogger } = require('../lib/logger');
+const log = createLogger('welcome');
+
+// PERFORMANCE OPTIMIZATION (US-0356): Profiling helper
+// Only active when AGILEFLOW_DEBUG=welcome is set
+const _profiling = process.env.AGILEFLOW_DEBUG === 'welcome';
+const _timings = {};
+function _mark(label) {
+  if (_profiling) _timings[label] = process.hrtime.bigint();
+}
+function _elapsed(from, to) {
+  if (!_profiling) return '';
+  const ns = Number((_timings[to] || process.hrtime.bigint()) - (_timings[from] || 0n));
+  return `${(ns / 1e6).toFixed(1)}ms`;
+}
+function _logTimings() {
+  if (!_profiling) return;
+  const labels = Object.keys(_timings);
+  const pairs = [];
+  for (let i = 1; i < labels.length; i++) {
+    pairs.push(`${labels[i]}=${_elapsed(labels[i - 1], labels[i])}`);
   }
-  return _sessionManager;
+  if (labels.length >= 2) {
+    pairs.push(`TOTAL=${_elapsed(labels[0], labels[labels.length - 1])}`);
+  }
+  // Output to stderr so it doesn't mix with the welcome table
+  console.error(`[welcome:timing] ${pairs.join(' ')}`);
 }
 
 // Hook metrics module (kept at top level - needed early for timer)
@@ -136,7 +159,11 @@ function checkTmuxAvailability(cache) {
   // Check session state cache first (tmux availability doesn't change within a session)
   if (cache?.sessionState?.tmux_available !== undefined) {
     if (cache.sessionState.tmux_available) return { available: true };
-    return { available: false, platform: detectPlatform(), noSudoCmd: 'conda install -c conda-forge tmux' };
+    return {
+      available: false,
+      platform: detectPlatform(),
+      noSudoCmd: 'conda install -c conda-forge tmux',
+    };
   }
 
   // Actually check (first run or no cache)
@@ -157,7 +184,11 @@ function checkTmuxAvailability(cache) {
   }
 
   if (available) return { available: true };
-  return { available: false, platform: detectPlatform(), noSudoCmd: 'conda install -c conda-forge tmux' };
+  return {
+    available: false,
+    platform: detectPlatform(),
+    noSudoCmd: 'conda install -c conda-forge tmux',
+  };
 }
 
 /**
@@ -289,7 +320,9 @@ function getProjectInfo(rootDir, cache = null) {
         }
       }
     }
-  } catch (e) {}
+  } catch (e) {
+    log.debug('getProjectInfo:', e?.message || String(e));
+  }
 
   return info;
 }
@@ -353,7 +386,9 @@ function runArchival(rootDir, cache = null) {
         result.remaining -= toArchiveCount;
       }
     }
-  } catch (e) {}
+  } catch (e) {
+    log.debug('runArchival:', e?.message || String(e));
+  }
 
   return result;
 }
@@ -426,20 +461,31 @@ function clearActiveCommands(rootDir, cache = null) {
     if (result.cleared > 0) {
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
     }
-  } catch (e) {}
+  } catch (e) {
+    log.debug('clearActiveCommands:', e?.message || String(e));
+  }
 
   return result;
 }
 
-function checkParallelSessions(rootDir) {
+/**
+ * PERFORMANCE OPTIMIZATION (US-0356): Lightweight session check
+ *
+ * Replaces the full session-manager require chain (~3,600 lines across 8 modules)
+ * with direct file I/O on the registry.json and lock files (~30 lines).
+ * Only checks active session count and current session info.
+ * Full registration, cleanup, and worktree detection deferred to Phase 3 (welcome-deferred.js).
+ *
+ * Estimated savings: 100-200ms
+ */
+function checkParallelSessionsFast(rootDir) {
   const result = {
     available: false,
     registered: false,
     otherActive: 0,
     currentId: null,
     cleaned: 0,
-    cleanedSessions: [], // Detailed info about cleaned sessions
-    // Extended session info for non-main sessions
+    cleanedSessions: [],
     isMain: true,
     nickname: null,
     branch: null,
@@ -448,60 +494,67 @@ function checkParallelSessions(rootDir) {
   };
 
   try {
-    // PERFORMANCE OPTIMIZATION: Import session-manager directly instead of subprocess
-    // Saves ~50-150ms by avoiding Node subprocess spawn overhead
-    const sm = getSessionManager();
-    if (sm && sm.fullStatus) {
-      result.available = true;
-      const data = sm.fullStatus();
-      result.registered = data.registered;
-      result.currentId = data.id;
-      result.otherActive = data.otherActive || 0;
-      result.cleaned = data.cleaned || 0;
-      result.cleanedSessions = data.cleanedSessions || [];
-
-      if (data.current) {
-        result.isMain = data.current.is_main === true;
-        result.nickname = data.current.nickname;
-        result.branch = data.current.branch;
-        result.sessionPath = data.current.path;
-      }
-      return result;
-    }
+    const sessionsDir = path.join(getAgileflowDir(rootDir), 'sessions');
+    const registryPath = path.join(sessionsDir, 'registry.json');
 
-    // Fallback: check if session manager script exists for subprocess call
-    const managerPath = path.join(getAgileflowDir(rootDir), 'scripts', 'session-manager.js');
-    if (!fs.existsSync(managerPath) && !fs.existsSync(SESSION_MANAGER_PATH)) {
-      return result;
-    }
+    if (!fs.existsSync(registryPath)) return result;
 
-    result.available = true;
-    const scriptPath = fs.existsSync(managerPath) ? managerPath : SESSION_MANAGER_PATH;
+    const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    if (!registry.sessions) return result;
 
-    const fullStatusResult = executeCommandSync('node', [scriptPath, 'full-status'], {
-      cwd: rootDir,
-      fallback: null,
-    });
+    result.available = true;
+    const cwd = process.cwd();
+    const staleLocks = [];
+
+    for (const [id, session] of Object.entries(registry.sessions)) {
+      if (session.path === cwd) {
+        // Found current session
+        result.registered = true;
+        result.currentId = id;
+        result.isMain = session.is_main === true;
+        result.nickname = session.nickname || null;
+        result.branch = session.branch || null;
+        result.sessionPath = session.path;
+      } else {
+        // Check if other session is alive via lock file
+        const lockPath = path.join(sessionsDir, `${id}.lock`);
+        if (fs.existsSync(lockPath)) {
+          try {
+            const content = fs.readFileSync(lockPath, 'utf8');
+            const pidMatch = content.match(/^pid=(\d+)/m);
+            if (pidMatch) {
+              const pid = parseInt(pidMatch[1], 10);
+              try {
+                process.kill(pid, 0); // Signal 0 = check alive
+                result.otherActive++;
+              } catch (e) {
+                // Process dead - collect for cleanup
+                staleLocks.push({ id, lockPath, pid });
+              }
+            }
+          } catch (e) {
+            // Lock read failed
+          }
+        }
+      }
+    }
 
-    if (fullStatusResult.data) {
+    // Quick cleanup of stale locks (prevents ghost session counts)
+    for (const stale of staleLocks) {
       try {
-        const data = JSON.parse(fullStatusResult.data);
-        result.registered = data.registered;
-        result.currentId = data.id;
-        result.otherActive = data.otherActive || 0;
-        result.cleaned = data.cleaned || 0;
-        result.cleanedSessions = data.cleanedSessions || [];
-
-        if (data.current) {
-          result.isMain = data.current.is_main === true;
-          result.nickname = data.current.nickname;
-          result.branch = data.current.branch;
-          result.sessionPath = data.current.path;
-        }
-      } catch (e) {}
+        fs.unlinkSync(stale.lockPath);
+        result.cleaned++;
+        result.cleanedSessions.push({
+          id: stale.id,
+          pid: stale.pid,
+          reason: 'pid_dead',
+        });
+      } catch (e) {
+        // Cleanup failed, deferred will retry
+      }
     }
   } catch (e) {
-    // Session system not available
+    log.debug('checkParallelSessionsFast:', e?.message || String(e));
   }
 
   return result;
@@ -560,7 +613,9 @@ function checkPreCompact(rootDir, cache = null) {
         }
       }
     }
-  } catch (e) {}
+  } catch (e) {
+    log.debug('checkPreCompact:', e?.message || String(e));
+  }
 
   return result;
 }
@@ -633,7 +688,9 @@ function checkDamageControl(rootDir, cache = null) {
         break;
       }
     }
-  } catch (e) {}
+  } catch (e) {
+    log.debug('checkDamageControl:', e?.message || String(e));
+  }
 
   return result;
 }
@@ -911,7 +968,9 @@ ${marker}
             const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
             currentVersion = pkg.version;
           }
-        } catch (e) {}
+        } catch (e) {
+          log.debug('getPackageVersion:', e?.message || String(e));
+        }
 
         // Update config_schema_version
         metadata.config_schema_version = currentVersion;
@@ -939,7 +998,115 @@ ${marker}
   return applied;
 }
 
-// Check for updates (async but we'll use sync approach for welcome)
+/**
+ * PERFORMANCE OPTIMIZATION: Check update cache in session-state.json (1-hour TTL)
+ * Avoids ~139ms npm registry network call when cache is fresh.
+ * Returns cached update result or null if stale/missing.
+ */
+function getUpdateFromCache(cache) {
+  try {
+    const updateCache = cache?.sessionState?.update_cache;
+    if (!updateCache || typeof updateCache !== 'object') return null;
+    if (!updateCache.checked_at || !updateCache.result) return null;
+
+    const checkedAt = new Date(updateCache.checked_at).getTime();
+    if (!Number.isFinite(checkedAt)) return null;
+
+    const age = Date.now() - checkedAt;
+    const ONE_HOUR = 60 * 60 * 1000;
+
+    // Reject negative age (future timestamps from clock skew) or absurdly old
+    if (age < 0 || age > 24 * ONE_HOUR) return null;
+
+    if (age < ONE_HOUR) {
+      return updateCache.result;
+    }
+  } catch (e) {
+    // Cache read failed
+  }
+  return null;
+}
+
+/**
+ * Display deferred warnings from previous session's background work.
+ * Warnings are saved by welcome-deferred.js and displayed here on next start.
+ * Clears warnings after display.
+ */
+function displayDeferredWarnings(rootDir) {
+  try {
+    const sessionStatePath = getSessionStatePath(rootDir);
+    if (!fs.existsSync(sessionStatePath)) return;
+
+    const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+    const deferredWarnings = state.deferred_warnings;
+    if (!deferredWarnings || !Array.isArray(deferredWarnings) || deferredWarnings.length === 0)
+      return;
+
+    for (const warning of deferredWarnings) {
+      if (!warning.lines || warning.lines.length === 0) continue;
+
+      console.log('');
+      switch (warning.type) {
+        case 'update_available':
+          console.log(`${c.amber}↑ ${warning.lines[0]}${c.reset}`);
+          if (warning.lines[1]) console.log(`  ${c.skyBlue}${warning.lines[1]}${c.reset}`);
+          break;
+        case 'session_health':
+          for (const line of warning.lines) {
+            if (line.startsWith('  ')) {
+              console.log(`${c.dim}   └─ ${line.trim()}${c.reset}`);
+            } else {
+              console.log(`${c.coral}⚠️  ${line}${c.reset}`);
+            }
+          }
+          break;
+        case 'process_cleanup':
+          console.log(`${c.amber}⚠️  ${warning.lines[0]}${c.reset}`);
+          if (warning.lines.length > 1) {
+            for (const line of warning.lines.slice(1)) {
+              console.log(`${c.slate}   ${line}${c.reset}`);
+            }
+          }
+          break;
+        case 'epic_completion':
+          for (const line of warning.lines) {
+            console.log(`${c.mintGreen}✅ ${line}${c.reset}`);
+          }
+          break;
+        case 'ideation_sync':
+          console.log(`${c.dim}📊 ${warning.lines[0]}${c.reset}`);
+          break;
+        case 'automations':
+          console.log(`${c.teal}🤖 ${warning.lines[0]}${c.reset}`);
+          for (const line of warning.lines.slice(1)) {
+            console.log(`${c.dim}   └─ ${line}${c.reset}`);
+          }
+          break;
+        case 'story_claiming':
+          console.log(`${c.amber}🔒 ${warning.lines[0]}${c.reset}`);
+          for (const line of warning.lines.slice(1)) {
+            console.log(`${c.dim}   └─ ${line.trim()}${c.reset}`);
+          }
+          break;
+        case 'file_tracking':
+          console.log(`${c.amber}📁 ${warning.lines[0]}${c.reset}`);
+          break;
+        default:
+          for (const line of warning.lines) {
+            console.log(`${c.dim}${line}${c.reset}`);
+          }
+      }
+    }
+
+    // Clear deferred warnings after display
+    delete state.deferred_warnings;
+    fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+  } catch (e) {
+    // Display failed, non-critical
+  }
+}
+
+// Check for updates (now handled by welcome-deferred.js, kept for backward compatibility)
 async function checkUpdates() {
   const result = {
     available: false,
@@ -951,10 +1118,7 @@ async function checkUpdates() {
     changelog: [],
   };
 
-  let updateChecker;
-  try {
-    updateChecker = require('./check-update.js');
-  } catch (e) {}
+  const updateChecker = tryOptional(() => require('./check-update.js'), 'check-update');
   if (!updateChecker) return result;
 
   try {
@@ -1266,7 +1430,9 @@ function getFeatureVersions(rootDir) {
         }
       }
     }
-  } catch (e) {}
+  } catch (e) {
+    log.debug('getFeatureVersions:', e?.message || String(e));
+  }
 
   return result;
 }
@@ -1636,8 +1802,10 @@ function formatSessionBanner(parallelSessions) {
   return lines.join('\n');
 }
 
-// Main
-async function main() {
+// Main (synchronous - async work deferred to welcome-deferred.js)
+function main() {
+  _mark('start');
+
   // Start hook timer for metrics
   const timer = hookMetrics ? hookMetrics.startHookTimer('SessionStart', 'welcome') : null;
 
@@ -1646,26 +1814,36 @@ async function main() {
   // PERFORMANCE: Load all project files once into cache
   // This eliminates 6-8 duplicate file reads across functions
   const cache = loadProjectFiles(rootDir);
+  _mark('loadFiles');
 
   // ============================================
   // PHASE 1: INSTANT WELCOME (< 300ms)
   // All fast operations - no network, no auto-update
   // ============================================
   const info = getProjectInfo(rootDir, cache);
+  _mark('getInfo');
 
-  // Smart hook scheduling: skip archival for micro/small projects (EP-0033)
-  // Scale detection is done early to inform hook scheduling
+  // PERFORMANCE OPTIMIZATION (US-0356): Read scale from session-state cache
+  // Avoids requiring scale-detector module + git subprocess when cache is fresh (< 5 min)
   let earlyScale = null;
-  try {
-    const scaleDetector = require('./lib/scale-detector');
-    // Check cache only (fast path, no full detection yet)
-    earlyScale = scaleDetector.detectScale({
-      rootDir,
-      statusJson: cache?.status,
-      sessionState: cache?.sessionState,
-    });
-  } catch (e) {
-    // Scale detection not available
+  const cachedScale = cache?.sessionState?.scale_detection;
+  const scaleFresh =
+    cachedScale &&
+    cachedScale.detected_at &&
+    Date.now() - new Date(cachedScale.detected_at).getTime() < 300000; // 5 min
+  if (scaleFresh) {
+    earlyScale = { ...cachedScale, fromCache: true };
+  } else {
+    try {
+      const scaleDetector = require('./lib/scale-detector');
+      earlyScale = scaleDetector.detectScale({
+        rootDir,
+        statusJson: cache?.status,
+        sessionState: cache?.sessionState,
+      });
+    } catch (e) {
+      // Scale detection not available
+    }
   }
 
   const scaleRecommendations = earlyScale
@@ -1677,94 +1855,127 @@ async function main() {
         }
       })()
     : null;
+  _mark('scale');
 
   const archival =
     scaleRecommendations && scaleRecommendations.skipArchival
       ? { ran: false, threshold: 0, archived: 0, remaining: 0, skippedByScale: true }
       : runArchival(rootDir, cache);
+  _mark('archival');
+
   const session = clearActiveCommands(rootDir, cache);
+  _mark('clearCmds');
+
   const precompact = checkPreCompact(rootDir, cache);
-  const parallelSessions = checkParallelSessions(rootDir);
-  // PERFORMANCE: Use fast expertise count (directory scan only, ~3 file samples)
-  // Full validation available via /agileflow:validate-expertise
-  const expertise = getExpertiseCountFast(rootDir);
+  _mark('precompact');
+
+  // PERFORMANCE OPTIMIZATION (US-0356): Use lightweight session check
+  // Reads registry.json + lock files directly (~30 lines) instead of
+  // requiring the full session-manager module chain (~3,600 lines across 8 modules).
+  // Full session registration deferred to Phase 3 (welcome-deferred.js).
+  const parallelSessions = checkParallelSessionsFast(rootDir);
+  _mark('sessions');
+
+  // PERFORMANCE OPTIMIZATION (US-0356): Defer expertise count to Phase 3
+  // Directory scan with file reads is non-critical for the table.
+  // Use cached result from session-state if available, otherwise show placeholder.
+  let expertise;
+  const cachedExpertise = cache?.sessionState?.expertise_count;
+  const validExpertiseCache =
+    cachedExpertise &&
+    cachedExpertise.total > 0 &&
+    typeof cachedExpertise.passed === 'number' &&
+    typeof cachedExpertise.warnings === 'number' &&
+    typeof cachedExpertise.failed === 'number';
+  if (validExpertiseCache) {
+    expertise = cachedExpertise;
+  } else {
+    expertise = getExpertiseCountFast(rootDir);
+  }
+  _mark('expertise');
+
   const damageControl = checkDamageControl(rootDir, cache);
+  _mark('damageCtl');
 
   // Use early scale detection result (already computed for hook scheduling)
   const scaleDetection = earlyScale || { scale: 'medium' };
 
-  // Agent Teams feature flag detection
-  let featureFlags;
-  try {
-    featureFlags = require('../lib/feature-flags');
-  } catch (e) {}
+  // PERFORMANCE OPTIMIZATION (US-0356): Read Agent Teams mode from metadata cache
+  // Avoids requiring feature-flags module when metadata is already loaded.
+  // Uses same { label, value, status } format as getAgentTeamsDisplayInfo().
   let agentTeamsInfo = {};
-  if (featureFlags) {
-    try {
-      agentTeamsInfo = featureFlags.getAgentTeamsDisplayInfo({
-        rootDir,
-        metadata: cache?.metadata,
-      });
-    } catch (e) {
-      // Silently fail - Agent Teams info is non-critical
-    }
+  const envTeams = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+  const envTeamsEnabled = envTeams === '1' || envTeams === 'true' || envTeams === 'yes';
+  const metaTeamsEnabled = cache?.metadata?.features?.agentTeams?.enabled === true;
+  if (envTeamsEnabled || metaTeamsEnabled) {
+    agentTeamsInfo = { label: 'Agent Teams', value: 'ENABLED (native)', status: 'enabled' };
+  } else {
+    agentTeamsInfo = { label: 'Agent Teams', value: 'subagent mode', status: 'fallback' };
   }
+  _mark('agentTeams');
 
   // Check if a previous background update completed successfully
   // This allows us to show "just updated" even for background updates
   let updateInfo = {};
   try {
-    const sessionStatePath = getSessionStatePath(rootDir);
-    if (fs.existsSync(sessionStatePath)) {
-      const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
-
-      // Check if pending update from previous session completed
-      if (state.pending_update) {
-        const pendingUpdate = state.pending_update;
-        const startedAt = new Date(pendingUpdate.started_at);
-        const minutesAgo = (Date.now() - startedAt.getTime()) / (1000 * 60);
-
-        // If current version matches target, update succeeded
-        if (info.version === pendingUpdate.to) {
-          updateInfo.justUpdated = true;
-          updateInfo.previousVersion = pendingUpdate.from;
-          updateInfo.changelog = getChangelogEntries(info.version);
-          // Clear pending update
-          delete state.pending_update;
-          fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
-        } else if (minutesAgo > 5) {
-          // Update timed out (5 minutes) - clear it
-          delete state.pending_update;
-          fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
-        }
-        // If still pending and < 5 minutes, leave it (update may still be running)
+    // Use already-loaded session state from cache instead of re-reading
+    const state = cache?.sessionState;
+    if (state?.pending_update) {
+      const pendingUpdate = state.pending_update;
+      const startedAt = new Date(pendingUpdate.started_at);
+      const minutesAgo = (Date.now() - startedAt.getTime()) / (1000 * 60);
+
+      if (info.version === pendingUpdate.to) {
+        updateInfo.justUpdated = true;
+        updateInfo.previousVersion = pendingUpdate.from;
+        updateInfo.changelog = getChangelogEntries(info.version);
+        // Clear pending update
+        const sessionStatePath = getSessionStatePath(rootDir);
+        delete state.pending_update;
+        fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+      } else if (minutesAgo > 5) {
+        const sessionStatePath = getSessionStatePath(rootDir);
+        delete state.pending_update;
+        fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
       }
     }
   } catch (e) {
     // Silently continue - pending update check is non-critical
   }
+  _mark('updateInfo');
 
-  // Check for new config options
+  // PERFORMANCE OPTIMIZATION (US-0356): Defer config staleness to Phase 3
+  // Only produces a notification; not needed for the main table.
+  // Read cached result from session-state if available.
   let configStaleness = { outdated: false, autoApply: false };
   let configAutoApplied = 0;
-  try {
-    configStaleness = checkConfigStaleness(rootDir, info.version, cache);
-
-    // Auto-apply new options if profile is "full" (only auto-applyable ones)
-    if (configStaleness.autoApply && configStaleness.autoApplyOptions?.length > 0) {
-      configAutoApplied = autoApplyConfigOptions(rootDir, configStaleness.autoApplyOptions);
-      if (configAutoApplied > 0) {
-        // Remove auto-applied options from the list, keep non-auto-applyable ones
-        configStaleness.newOptions = configStaleness.newOptions.filter(o => !o.autoApplyable);
-        configStaleness.newOptionsCount = configStaleness.newOptions.length;
-        if (configStaleness.newOptionsCount === 0) {
-          configStaleness.outdated = false;
+  const cachedConfigStaleness = cache?.sessionState?.config_staleness;
+  const configCacheAge = cachedConfigStaleness?.cached_at
+    ? Date.now() - new Date(cachedConfigStaleness.cached_at).getTime()
+    : Infinity;
+  const configCacheFresh = configCacheAge < 300000; // 5 min TTL
+  if (cachedConfigStaleness && configCacheFresh) {
+    configStaleness = cachedConfigStaleness;
+  } else {
+    try {
+      configStaleness = checkConfigStaleness(rootDir, info.version, cache);
+
+      // Auto-apply new options if profile is "full" (only auto-applyable ones)
+      if (configStaleness.autoApply && configStaleness.autoApplyOptions?.length > 0) {
+        configAutoApplied = autoApplyConfigOptions(rootDir, configStaleness.autoApplyOptions);
+        if (configAutoApplied > 0) {
+          configStaleness.newOptions = configStaleness.newOptions.filter(o => !o.autoApplyable);
+          configStaleness.newOptionsCount = configStaleness.newOptions.length;
+          if (configStaleness.newOptionsCount === 0) {
+            configStaleness.outdated = false;
+          }
         }
       }
+    } catch (e) {
+      // Config check failed - continue without it
     }
-  } catch (e) {
-    // Config check failed - continue without it
   }
+  _mark('configStale');
 
   // Check tmux availability (only if tmuxAutoSpawn is enabled)
   let tmuxCheck = { available: true };
@@ -1772,6 +1983,7 @@ async function main() {
   if (tmuxAutoSpawnEnabled) {
     tmuxCheck = checkTmuxAvailability(cache);
   }
+  _mark('tmux');
 
   // Show session banner FIRST if in a non-main session
   const sessionBanner = formatSessionBanner(parallelSessions);
@@ -1795,48 +2007,31 @@ async function main() {
   );
 
   // ============================================
-  // PHASE 2: BACKGROUND UPDATE CHECK (after table displays)
-  // This runs async and shows notification AFTER the table
+  // PHASE 2: FAST POST-TABLE NOTIFICATIONS + DEFERRED BACKGROUND WORK
+  // Only instant operations here. Expensive work deferred to welcome-deferred.js
   // ============================================
-  try {
-    // Only check for updates if we didn't already detect a "just updated" from previous session
-    if (!updateInfo.justUpdated) {
-      const freshUpdateInfo = await checkUpdates();
 
-      // If update is available, show notification AFTER the table
-      if (freshUpdateInfo.available && freshUpdateInfo.latest) {
+  // Display deferred warnings from previous session's background work
+  displayDeferredWarnings(rootDir);
+
+  // Check update cache (1-hour TTL) - instant if cached, skipped if stale
+  let skipUpdateInDeferred = false;
+  try {
+    const cachedUpdate = getUpdateFromCache(cache);
+    if (cachedUpdate) {
+      skipUpdateInDeferred = true;
+      // Use cached result for notification
+      if (cachedUpdate.available && cachedUpdate.latest && !updateInfo.justUpdated) {
         console.log('');
         console.log(
-          `${c.amber}↑ Update available:${c.reset} v${info.version} → ${c.softGold}v${freshUpdateInfo.latest}${c.reset}`
+          `${c.amber}↑ Update available:${c.reset} v${info.version} → ${c.softGold}v${cachedUpdate.latest}${c.reset}`
         );
         console.log(`  Run: ${c.skyBlue}npx agileflow update${c.reset}`);
-
-        // If auto-update is enabled, spawn it in background (non-blocking)
-        if (freshUpdateInfo.autoUpdate) {
-          spawnAutoUpdateInBackground(rootDir, info.version, freshUpdateInfo.latest);
-        }
-      }
-
-      // Mark current version as seen to track for next update
-      let updateChecker;
-      try {
-        updateChecker = require('./check-update.js');
-      } catch (e) {}
-      if (freshUpdateInfo.justUpdated && updateChecker) {
-        updateChecker.markVersionSeen(info.version);
-      }
-    } else {
-      // Mark current version as seen (for "just updated" case)
-      let updateChecker;
-      try {
-        updateChecker = require('./check-update.js');
-      } catch (e) {}
-      if (updateChecker) {
-        updateChecker.markVersionSeen(info.version);
       }
     }
+    // If no cache or stale, the deferred script will check and cache the result
   } catch (e) {
-    // Update check failed - continue without it (non-critical)
+    // Cache check failed, deferred script will handle it
   }
 
   // Show config auto-apply confirmation (for "full" profile)
@@ -1913,272 +2108,52 @@ async function main() {
     );
   }
 
-  // === SESSION HEALTH WARNINGS ===
-  // Check for forgotten sessions with uncommitted changes, stale sessions, orphaned entries
-  // PERFORMANCE OPTIMIZATION: Direct function call instead of subprocess (~50-100ms savings)
-  try {
-    const sm = getSessionManager();
-    const health = sm ? sm.getSessionsHealth({ staleDays: 7 }) : null;
-
-    if (health) {
-      const hasIssues =
-        health.uncommitted.length > 0 ||
-        health.stale.length > 0 ||
-        health.orphanedRegistry.length > 0;
-
-      if (hasIssues) {
-        console.log('');
+  _mark('postTable');
 
-        // Uncommitted changes - MOST IMPORTANT (potential data loss)
-        if (health.uncommitted.length > 0) {
-          console.log(
-            `${c.coral}⚠️  ${health.uncommitted.length} session(s) have uncommitted changes:${c.reset}`
-          );
-          health.uncommitted.slice(0, 3).forEach(sess => {
-            const name = sess.nickname ? `"${sess.nickname}"` : `Session ${sess.id}`;
-            console.log(`${c.dim}   └─ ${name}: ${sess.changeCount} file(s)${c.reset}`);
-          });
-          if (health.uncommitted.length > 3) {
-            console.log(`${c.dim}   └─ ... and ${health.uncommitted.length - 3} more${c.reset}`);
-          }
-          console.log(
-            `${c.slate}   Run: ${c.skyBlue}/agileflow:session:status${c.slate} to see details${c.reset}`
-          );
-        }
-
-        // Stale sessions (inactive 7+ days)
-        if (health.stale.length > 0) {
-          console.log(
-            `${c.amber}📅 ${health.stale.length} session(s) inactive for 7+ days${c.reset}`
-          );
-        }
-
-        // Orphaned registry entries (path doesn't exist)
-        if (health.orphanedRegistry.length > 0) {
-          console.log(
-            `${c.peach}🗑️  ${health.orphanedRegistry.length} session(s) have missing directories${c.reset}`
-          );
-        }
-      }
-    }
-  } catch (e) {
-    // Health check failed, skip silently
-  }
-
-  // === DUPLICATE CLAUDE PROCESS DETECTION ===
-  // Check for multiple Claude processes in the same working directory
-  let processCleanup;
-  try {
-    processCleanup = require('./lib/process-cleanup.js');
-  } catch (e) {}
-  if (processCleanup) {
-    try {
-      // 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 autoKillConfigured = metadata?.features?.processCleanup?.autoKill === true;
-      const autoKill = autoKillConfigured && process.env.AGILEFLOW_PROCESS_CLEANUP_AUTOKILL === '1';
-
-      const cleanupResult = processCleanup.cleanupDuplicateProcesses({
-        rootDir,
-        autoKill,
-        dryRun: false,
-      });
-
-      if (cleanupResult.duplicates > 0) {
-        console.log('');
-
-        if (cleanupResult.killed.length > 0) {
-          // Auto-kill was enabled and processes were terminated
-          console.log(
-            `${c.mintGreen}🔧 Cleaned ${cleanupResult.killed.length} duplicate Claude process(es)${c.reset}`
-          );
-          cleanupResult.killed.forEach(proc => {
-            console.log(`${c.dim}   └─ PID ${proc.pid} (${proc.method})${c.reset}`);
-          });
-        } else {
-          // 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}`);
-          if (autoKillConfigured) {
-            console.log(
-              `${c.slate}   • Auto-kill configured but runtime opt-in is off (safer default)${c.reset}`
-            );
-          }
-        }
-
-        if (cleanupResult.errors.length > 0) {
-          cleanupResult.errors.forEach(err => {
-            console.log(`${c.coral}   ⚠ Failed to kill PID ${err.pid}: ${err.error}${c.reset}`);
-          });
-        }
-      }
-    } catch (e) {
-      // Silently ignore process cleanup errors
-    }
-  }
-
-  // Story claiming: cleanup stale claims and show warnings
-  let storyClaiming;
-  try {
-    storyClaiming = require('./lib/story-claiming.js');
-  } catch (e) {}
-  if (storyClaiming) {
-    try {
-      // Clean up stale claims (dead PIDs, expired TTL)
-      const cleanupResult = storyClaiming.cleanupStaleClaims({ rootDir });
-      if (cleanupResult.ok && cleanupResult.cleaned > 0) {
-        console.log('');
-        console.log(`${c.dim}Cleaned ${cleanupResult.cleaned} stale story claim(s)${c.reset}`);
-      }
-
-      // Show stories claimed by other sessions
-      const othersResult = storyClaiming.getStoriesClaimedByOthers({ rootDir });
-      if (othersResult.ok && othersResult.stories && othersResult.stories.length > 0) {
-        console.log('');
-        console.log(storyClaiming.formatClaimedStories(othersResult.stories));
-        console.log('');
-        console.log(
-          `${c.slate}   These stories are locked - pick a different one to avoid conflicts.${c.reset}`
-        );
-      }
-    } catch (e) {
-      // Silently ignore story claiming errors
-    }
-  }
-
-  // File tracking: cleanup stale touches and show overlap warnings
-  let fileTracking;
+  // ============================================
+  // PHASE 3: SPAWN DEFERRED BACKGROUND WORK
+  // Session health, process cleanup, story claiming, file tracking,
+  // epic completion, ideation sync, automations, update check (if stale)
+  // Also: full session registration, expertise re-scan, config staleness check
+  // Results saved to session-state.json for next session display.
+  // ============================================
   try {
-    fileTracking = require('./lib/file-tracking.js');
-  } catch (e) {}
-  if (fileTracking) {
-    try {
-      // Clean up stale file touches (dead PIDs, expired TTL)
-      const cleanupResult = fileTracking.cleanupStaleTouches({ rootDir });
-      if (cleanupResult.ok && cleanupResult.cleaned > 0) {
-        console.log('');
-        console.log(
-          `${c.dim}Cleaned ${cleanupResult.cleaned} stale file tracking session(s)${c.reset}`
-        );
+    const deferredScript = path.join(__dirname, 'welcome-deferred.js');
+    if (fs.existsSync(deferredScript)) {
+      const deferredArgs = [deferredScript, rootDir, `--version=${info.version}`];
+      if (skipUpdateInDeferred) {
+        deferredArgs.push('--skip-update');
       }
-
-      // Show file overlaps with other sessions
-      const overlapsResult = fileTracking.getMyFileOverlaps({ rootDir });
-      if (overlapsResult.ok && overlapsResult.overlaps && overlapsResult.overlaps.length > 0) {
-        console.log('');
-        console.log(fileTracking.formatFileOverlaps(overlapsResult.overlaps));
-      }
-    } catch (e) {
-      // Silently ignore file tracking errors
-    }
-  }
-
-  // Epic completion check: auto-complete epics where all stories are done
-  let storyStateMachine;
-  try {
-    storyStateMachine = require('./lib/story-state-machine.js');
-  } catch (e) {}
-  if (storyStateMachine && cache.status) {
-    try {
-      const statusPath = getStatusPath(rootDir);
-      const statusData = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-      const incompleteEpics = storyStateMachine.findIncompleteEpics(statusData);
-
-      if (incompleteEpics.length > 0) {
-        let autoCompleted = 0;
-        for (const { epicId, completed, total } of incompleteEpics) {
-          const result = storyStateMachine.autoCompleteEpic(statusData, epicId);
-          if (result.updated) {
-            autoCompleted++;
-            console.log('');
-            console.log(
-              `${c.mintGreen}✅ Auto-completed ${c.bold}${epicId}${c.reset}${c.mintGreen} (${completed}/${total} stories done)${c.reset}`
-            );
-          }
-        }
-        if (autoCompleted > 0) {
-          fs.writeFileSync(statusPath, JSON.stringify(statusData, null, 2) + '\n');
-        }
+      if (updateInfo.justUpdated) {
+        deferredArgs.push('--just-updated');
       }
-    } catch (e) {
-      // Silently ignore epic completion errors
-    }
-  }
-
-  // Ideation sync: mark ideas as implemented when linked epics complete
-  let syncIdeationStatus;
-  try {
-    syncIdeationStatus = require('./lib/sync-ideation-status.js');
-  } catch (e) {}
-  if (syncIdeationStatus) {
-    try {
-      const syncResult = syncIdeationStatus.syncImplementedIdeas(rootDir);
-      if (syncResult.ok && syncResult.updated > 0) {
-        console.log('');
-        console.log(`${c.dim}📊 Synced ${syncResult.updated} idea(s) as implemented${c.reset}`);
+      // US-0356: Signal deferred to run full session registration and expertise scan
+      deferredArgs.push('--run-session-register');
+      deferredArgs.push('--run-expertise-scan');
+      if (!cachedConfigStaleness || !configCacheFresh) {
+        deferredArgs.push('--run-config-staleness');
       }
-    } catch (e) {
-      // Silently ignore ideation sync errors
+      spawnBackground('node', deferredArgs, { cwd: rootDir });
     }
-  }
-
-  // === SCHEDULED AUTOMATIONS ===
-  // Check for and run due automations (non-blocking)
-  let automationRegistry, automationRunner;
-  try {
-    automationRegistry = require('./lib/automation-registry.js');
-    automationRunner = require('./lib/automation-runner.js');
   } catch (e) {
-    // Automation system not available
+    // Deferred script spawn failed, non-critical
   }
-  if (automationRegistry && automationRunner) {
-    try {
-      const registry = automationRegistry.getAutomationRegistry({ rootDir });
-      const runner = automationRunner.getAutomationRunner({ rootDir });
-      const dueStatus = runner.getDueStatus();
 
-      if (dueStatus.due > 0) {
-        console.log('');
-        console.log(`${c.teal}🤖 ${dueStatus.due} automation(s) due to run${c.reset}`);
-
-        // Show what's due
-        for (const auto of dueStatus.dueAutomations.slice(0, 3)) {
-          console.log(`${c.dim}   └─ ${auto.name}${c.reset}`);
-        }
-        if (dueStatus.due > 3) {
-          console.log(`${c.dim}   └─ ... and ${dueStatus.due - 3} more${c.reset}`);
-        }
-
-        // Run due automations in background (spawn detached process)
-        // This prevents blocking the welcome hook
-        const runnerScriptPath = path.join(__dirname, 'automation-run-due.js');
-
-        // Only spawn if the runner script exists
-        if (fs.existsSync(runnerScriptPath)) {
-          spawnBackground('node', [runnerScriptPath], { cwd: rootDir });
-          console.log(`${c.dim}   Running in background...${c.reset}`);
-        } else {
-          console.log(`${c.slate}   Run: ${c.skyBlue}/agileflow:automate ACTION=run-due${c.reset}`);
-        }
-      }
-    } catch (e) {
-      // Silently ignore automation errors
-    }
-  }
+  _mark('deferred');
 
   // Record hook metrics
   if (timer && hookMetrics) {
     hookMetrics.recordHookMetrics(timer, 'success', null, { rootDir });
   }
+
+  // Output profiling data if enabled
+  _logTimings();
 }
 
-main().catch(err => {
-  console.error(err);
+try {
+  main();
+} catch (err) {
+  log.error(err.message || String(err));
   // Record error in metrics if possible
   if (hookMetrics) {
     try {
@@ -2189,4 +2164,4 @@ main().catch(err => {
       // Silently ignore metrics errors
     }
   }
-});
+}