@appoly/multiagent-chat 1.0.3 → 1.0.7

package/main.js

@@ -22,6 +22,7 @@ const fsSync = require('fs');
 const os = require('os');
 const yaml = require('yaml');
 const chokidar = require('chokidar');
+const crypto = require('crypto');
 
 // Home config directory: ~/.multiagent-chat/
 const HOME_CONFIG_DIR = path.join(os.homedir(), '.multiagent-chat');
@@ -34,8 +35,9 @@ const execAsync = promisify(exec);
 let mainWindow;
 let agents = [];
 let config;
-let workspacePath;
-let agentCwd;  // Parent directory of workspace - where agents are launched
+let workspacePath;        // Points to current session dir (e.g. .multiagent-chat/sessions/<id>/)
+let workspaceBasePath;    // Points to .multiagent-chat/ inside project root
+let agentCwd;             // Parent directory of workspace - where agents are launched
 let fileWatcher;
 let outboxWatcher;
 let customWorkspacePath = null;
@@ -43,14 +45,355 @@ let customConfigPath = null;  // CLI --config path
 let messageSequence = 0;  // For ordering messages in chat
 let agentColors = {};     // Map of agent name -> color
 let sessionBaseCommit = null;  // Git commit hash at session start for diff baseline
+let currentSessionId = null;  // Current active session ID
 
+function sendToRenderer(channel, payload) {
+  if (!mainWindow || mainWindow.isDestroyed()) return;
+  const wc = mainWindow.webContents;
+  if (!wc || wc.isDestroyed()) return;
+  wc.send(channel, payload);
+}
+
+// ═══════════════════════════════════════════════════════════
+// Session Storage Functions
+// ═══════════════════════════════════════════════════════════
+
+function generateSessionId() {
+  const now = new Date();
+  const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const hex = crypto.randomBytes(2).toString('hex');
+  return `${ts}-${hex}`;
+}
+
+function generateSessionTitle(prompt) {
+  if (!prompt) return 'Untitled Session';
+  // Truncate at ~60 chars on a word boundary
+  if (prompt.length <= 60) return prompt.split('\n')[0];
+  const truncated = prompt.slice(0, 60);
+  const lastSpace = truncated.lastIndexOf(' ');
+  return (lastSpace > 30 ? truncated.slice(0, lastSpace) : truncated) + '...';
+}
+
+function getSessionsIndexPath(projectRoot) {
+  const wsName = (config && config.workspace) || '.multiagent-chat';
+  return path.join(projectRoot, wsName, 'sessions.json');
+}
+
+function getSessionsDir(projectRoot) {
+  const wsName = (config && config.workspace) || '.multiagent-chat';
+  return path.join(projectRoot, wsName, 'sessions');
+}
+
+async function loadSessionsIndex(projectRoot) {
+  const indexPath = getSessionsIndexPath(projectRoot);
+  try {
+    const content = await fs.readFile(indexPath, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      console.error('Corrupt sessions.json - failed to parse:', indexPath, error.message);
+    }
+    return { version: 1, sessions: [] };
+  }
+}
+
+async function saveSessionsIndex(projectRoot, index) {
+  const indexPath = getSessionsIndexPath(projectRoot);
+  await fs.mkdir(path.dirname(indexPath), { recursive: true });
+  // Atomic write: write to temp file then rename (rename is atomic on all platforms)
+  const tmpPath = indexPath + '.tmp';
+  await fs.writeFile(tmpPath, JSON.stringify(index, null, 2));
+  await fs.rename(tmpPath, indexPath);
+}
+
+// Async mutex to serialize all sessions.json read-modify-write cycles
+let sessionsWriteQueue = Promise.resolve();
+
+function withSessionsLock(fn) {
+  const next = sessionsWriteQueue.then(fn, fn);
+  sessionsWriteQueue = next.catch(() => {});
+  return next;
+}
+
+async function addSessionToIndex(projectRoot, sessionMeta) {
+  return withSessionsLock(async () => {
+    const index = await loadSessionsIndex(projectRoot);
+    index.sessions.unshift(sessionMeta);
+    await saveSessionsIndex(projectRoot, index);
+    return index;
+  });
+}
+
+async function updateSessionInIndex(projectRoot, sessionId, updates) {
+  return withSessionsLock(async () => {
+    const index = await loadSessionsIndex(projectRoot);
+    const session = index.sessions.find(s => s.id === sessionId);
+    if (session) {
+      Object.assign(session, updates);
+      await saveSessionsIndex(projectRoot, index);
+    }
+    return index;
+  });
+}
+
+async function setupSessionDirectory(projectRoot, sessionId) {
+  const sessionsDir = getSessionsDir(projectRoot);
+  const sessionDir = path.join(sessionsDir, sessionId);
+
+  await fs.mkdir(sessionDir, { recursive: true });
+
+  // Initialize chat.jsonl
+  const chatPath = path.join(sessionDir, config.chat_file || 'chat.jsonl');
+  await fs.writeFile(chatPath, '');
+
+  // Initialize PLAN_FINAL.md
+  const planPath = path.join(sessionDir, config.plan_file || 'PLAN_FINAL.md');
+  await fs.writeFile(planPath, '');
+
+  // Create outbox directory and per-agent outbox files
+  const outboxDir = path.join(sessionDir, config.outbox_dir || 'outbox');
+  await fs.mkdir(outboxDir, { recursive: true });
+
+  for (const agentConfig of config.agents) {
+    const outboxFile = path.join(outboxDir, `${agentConfig.name.toLowerCase()}.md`);
+    await fs.writeFile(outboxFile, '');
+  }
+
+  return sessionDir;
+}
+
+async function loadSessionData(projectRoot, sessionId) {
+  const sessionsDir = getSessionsDir(projectRoot);
+  const sessionDir = path.join(sessionsDir, sessionId);
+
+  // Read chat
+  let messages = [];
+  const chatPath = path.join(sessionDir, config.chat_file || 'chat.jsonl');
+  try {
+    const content = await fs.readFile(chatPath, 'utf8');
+    if (content.trim()) {
+      messages = content.trim().split('\n').map(line => {
+        try { return JSON.parse(line); }
+        catch (e) { return null; }
+      }).filter(Boolean);
+    }
+  } catch (e) {
+    // No chat file
+  }
+
+  // Read plan
+  let plan = '';
+  const planPath = path.join(sessionDir, config.plan_file || 'PLAN_FINAL.md');
+  try {
+    plan = await fs.readFile(planPath, 'utf8');
+  } catch (e) {
+    // No plan file
+  }
+
+  return { messages, plan, sessionDir };
+}
+
+// Migrate from old flat .multiagent-chat/ to session-based structure
+async function migrateFromFlatWorkspace(projectRoot) {
+  const wsName = (config && config.workspace) || '.multiagent-chat';
+  const wsBase = path.join(projectRoot, wsName);
+
+  // Check if old flat structure exists (chat.jsonl directly in .multiagent-chat/)
+  const oldChatPath = path.join(wsBase, config.chat_file || 'chat.jsonl');
+  const sessionsDir = path.join(wsBase, 'sessions');
+
+  try {
+    await fs.access(oldChatPath);
+    // Old flat structure exists - check if sessions dir already exists
+    try {
+      await fs.access(sessionsDir);
+      // Sessions dir exists, already migrated or mixed state - skip
+      return;
+    } catch (e) {
+      // Sessions dir doesn't exist, migrate
+    }
+  } catch (e) {
+    // No old chat file, nothing to migrate
+    return;
+  }
+
+  console.log('Migrating flat workspace to session-based structure...');
+
+  // Read old chat to determine session metadata
+  let oldMessages = [];
+  try {
+    const content = await fs.readFile(oldChatPath, 'utf8');
+    if (content.trim()) {
+      oldMessages = content.trim().split('\n').map(line => {
+        try { return JSON.parse(line); }
+        catch (e) { return null; }
+      }).filter(Boolean);
+    }
+  } catch (e) {
+    // Empty or unreadable
+  }
+
+  // Create a session for the old data
+  const sessionId = generateSessionId();
+  const sessionDir = path.join(sessionsDir, sessionId);
+  await fs.mkdir(sessionDir, { recursive: true });
+
+  // Move chat.jsonl
+  try {
+    await fs.rename(oldChatPath, path.join(sessionDir, config.chat_file || 'chat.jsonl'));
+  } catch (e) {
+    // Copy instead if rename fails (cross-device)
+    try {
+      await fs.copyFile(oldChatPath, path.join(sessionDir, config.chat_file || 'chat.jsonl'));
+      await fs.unlink(oldChatPath);
+    } catch (copyErr) {
+      console.warn('Could not migrate chat file:', copyErr.message);
+    }
+  }
+
+  // Move PLAN_FINAL.md
+  const oldPlanPath = path.join(wsBase, config.plan_file || 'PLAN_FINAL.md');
+  try {
+    await fs.rename(oldPlanPath, path.join(sessionDir, config.plan_file || 'PLAN_FINAL.md'));
+  } catch (e) {
+    // Create empty if not found
+    await fs.writeFile(path.join(sessionDir, config.plan_file || 'PLAN_FINAL.md'), '');
+  }
+
+  // Move outbox directory
+  const oldOutboxDir = path.join(wsBase, config.outbox_dir || 'outbox');
+  const newOutboxDir = path.join(sessionDir, config.outbox_dir || 'outbox');
+  try {
+    await fs.rename(oldOutboxDir, newOutboxDir);
+  } catch (e) {
+    // Create fresh outbox
+    await fs.mkdir(newOutboxDir, { recursive: true });
+    for (const agentConfig of config.agents) {
+      await fs.writeFile(path.join(newOutboxDir, `${agentConfig.name.toLowerCase()}.md`), '');
+    }
+  }
+
+  // Create sessions.json index
+  const firstPrompt = oldMessages.find(m => m.type === 'user')?.content || '';
+  const firstTs = oldMessages.length > 0 ? oldMessages[0].timestamp : new Date().toISOString();
+  const lastTs = oldMessages.length > 0 ? oldMessages[oldMessages.length - 1].timestamp : new Date().toISOString();
+
+  const sessionMeta = {
+    id: sessionId,
+    title: generateSessionTitle(firstPrompt),
+    firstPrompt: firstPrompt.slice(0, 200),
+    workspace: projectRoot,
+    createdAt: firstTs,
+    lastActiveAt: lastTs,
+    messageCount: oldMessages.length,
+    status: 'completed'
+  };
+
+  await withSessionsLock(async () => {
+    await saveSessionsIndex(projectRoot, { version: 1, sessions: [sessionMeta] });
+  });
+  console.log('Migration complete. Created session:', sessionId);
+}
+
+function generateChatSummary(messages) {
+  // Take last ~20 messages and create a condensed summary
+  const recent = messages.slice(-20);
+  if (recent.length === 0) return 'No previous messages.';
+
+  return recent.map(m => {
+    const content = (m.content || '').slice(0, 200);
+    return `[${m.agent}]: ${content}${m.content && m.content.length > 200 ? '...' : ''}`;
+  }).join('\n\n');
+}
+
+function buildResumePrompt(chatSummary, plan, newMessage, agentName) {
+  const template = config.resume_template || `## Multi-Agent Collaboration Session (Resumed)
+**You are: {agent_name}**
+You are collaborating with: {agent_names}
+
+### Previous Discussion Summary
+{chat_summary}
+
+### Existing Plan
+{existing_plan}
+
+### How to Send Messages
+\`\`\`bash
+cat << 'EOF' > {outbox_file}
+Your message here.
+EOF
+\`\`\`
+
+## New Message from User
+{new_message}
+
+### Behavior on Resume
+- Default to discussion-first collaboration with the other agents
+- Do NOT implement or edit files unless the newest user message explicitly asks for implementation
+- If intent is ambiguous, ask a quick clarification before making code changes
+
+Please respond taking into account the context above.`;
+
+  const relFromProject = path.relative(agentCwd, workspacePath);
+  const outboxDir = config.outbox_dir || 'outbox';
+  const outboxFile = `${relFromProject}/${outboxDir}/${agentName.toLowerCase()}.md`;
+  const planFile = `${relFromProject}/${config.plan_file || 'PLAN_FINAL.md'}`;
+
+  return template
+    .replace(/{agent_name}/g, agentName)
+    .replace(/{agent_names}/g, config.agents.map(a => a.name).join(', '))
+    .replace(/{chat_summary}/g, chatSummary)
+    .replace(/{existing_plan}/g, plan || 'No plan yet.')
+    .replace(/{new_message}/g, newMessage)
+    .replace(/{outbox_file}/g, outboxFile)
+    .replace(/{plan_file}/g, planFile);
+}
+
+// ═══════════════════════════════════════════════════════════
+// Init workspace base (just ensures dirs exist, sets agentCwd)
+// ═══════════════════════════════════════════════════════════
+
+async function initWorkspaceBase(projectRoot) {
+  agentCwd = projectRoot;
+
+  const wsName = (config && config.workspace) || '.multiagent-chat';
+  workspaceBasePath = path.join(projectRoot, wsName);
+  await fs.mkdir(workspaceBasePath, { recursive: true });
+  await fs.mkdir(path.join(workspaceBasePath, 'sessions'), { recursive: true });
+
+  // Build agent colors map from config
+  const defaultColors = config.default_agent_colors || ['#667eea', '#f093fb', '#4fd1c5', '#f6ad55', '#68d391', '#fc8181'];
+  agentColors = {};
+  config.agents.forEach((agentConfig, index) => {
+    agentColors[agentConfig.name.toLowerCase()] = agentConfig.color || defaultColors[index % defaultColors.length];
+  });
+  agentColors['user'] = config.user_color || '#a0aec0';
+
+  // Capture git base commit for diff baseline
+  try {
+    const { stdout } = await execAsync('git rev-parse HEAD', { cwd: agentCwd });
+    sessionBaseCommit = stdout.trim();
+    console.log('Session base commit:', sessionBaseCommit);
+  } catch (error) {
+    try {
+      await execAsync('git rev-parse --git-dir', { cwd: agentCwd });
+      sessionBaseCommit = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+      console.log('Git repo with no commits, using empty tree hash for diff baseline');
+    } catch (e) {
+      console.log('Not a git repository:', e.message);
+      sessionBaseCommit = null;
+    }
+  }
+
+  console.log('Workspace base initialized:', workspaceBasePath);
+  console.log('Agent working directory:', agentCwd);
+}
+
+// ═══════════════════════════════════════════════════════════
 // Parse command-line arguments
-// Usage: npm start /path/to/workspace
-// Or: npm start --workspace /path/to/workspace
-// Or: npm start --config /path/to/config.yaml
-// Or: WORKSPACE=/path/to/workspace npm start
+// ═══════════════════════════════════════════════════════════
+
 function parseCommandLineArgs() {
-  // Check environment variables first
   if (process.env.WORKSPACE) {
     customWorkspacePath = process.env.WORKSPACE;
     console.log('Using workspace from environment variable:', customWorkspacePath);
@@ -61,48 +404,40 @@ function parseCommandLineArgs() {
     console.log('Using config from environment variable:', customConfigPath);
   }
 
-  // Then check command-line arguments
-  // process.argv looks like: [electron, main.js, ...args]
   const args = process.argv.slice(2);
 
   for (let i = 0; i < args.length; i++) {
-    // Parse --workspace flag
     if (args[i] === '--workspace' && args[i + 1]) {
       customWorkspacePath = args[i + 1];
       console.log('Using workspace from --workspace flag:', customWorkspacePath);
-      i++; // Skip next arg
-    }
-    // Parse --config flag
-    else if (args[i] === '--config' && args[i + 1]) {
+      i++;
+    } else if (args[i] === '--config' && args[i + 1]) {
       customConfigPath = args[i + 1];
       console.log('Using config from --config flag:', customConfigPath);
-      i++; // Skip next arg
-    }
-    // Positional arg (assume workspace path if not a flag)
-    else if (!args[i].startsWith('--') && !customWorkspacePath) {
+      i++;
+    } else if (!args[i].startsWith('--') && !customWorkspacePath) {
       customWorkspacePath = args[i];
       console.log('Using workspace from positional argument:', customWorkspacePath);
     }
   }
 }
 
-// Ensure home config directory exists and set up first-run defaults
+// ═══════════════════════════════════════════════════════════
+// Home config directory setup
+// ═══════════════════════════════════════════════════════════
+
 async function ensureHomeConfigDir() {
   try {
-    // Create ~/.multiagent-chat/ if it doesn't exist
     await fs.mkdir(HOME_CONFIG_DIR, { recursive: true });
     console.log('Home config directory ensured:', HOME_CONFIG_DIR);
 
-    // Migration: check for existing data in Electron userData
     const userDataDir = app.getPath('userData');
     const oldRecentsFile = path.join(userDataDir, 'recent-workspaces.json');
 
-    // Check if config.yaml exists in home dir, if not copy default
     try {
       await fs.access(HOME_CONFIG_FILE);
       console.log('Home config exists:', HOME_CONFIG_FILE);
     } catch (e) {
-      // Copy bundled default config to home dir
       const bundledConfig = path.join(__dirname, 'config.yaml');
       try {
         await fs.copyFile(bundledConfig, HOME_CONFIG_FILE);
@@ -112,17 +447,14 @@ async function ensureHomeConfigDir() {
       }
     }
 
-    // Initialize or migrate recent-workspaces.json
     try {
       await fs.access(RECENT_WORKSPACES_FILE);
     } catch (e) {
-      // Try to migrate from old location first
       try {
         await fs.access(oldRecentsFile);
         await fs.copyFile(oldRecentsFile, RECENT_WORKSPACES_FILE);
         console.log('Migrated recent workspaces from:', oldRecentsFile);
       } catch (migrateError) {
-        // No old file, create new empty one
         await fs.writeFile(RECENT_WORKSPACES_FILE, JSON.stringify({ recents: [] }, null, 2));
         console.log('Initialized recent workspaces file:', RECENT_WORKSPACES_FILE);
       }
@@ -132,7 +464,10 @@ async function ensureHomeConfigDir() {
   }
 }
 
-// Load recent workspaces from JSON file
+// ═══════════════════════════════════════════════════════════
+// Recent workspaces (kept for backward compat / sidebar)
+// ═══════════════════════════════════════════════════════════
+
 async function loadRecentWorkspaces() {
   try {
     const content = await fs.readFile(RECENT_WORKSPACES_FILE, 'utf8');
@@ -144,7 +479,6 @@ async function loadRecentWorkspaces() {
   }
 }
 
-// Save recent workspaces to JSON file
 async function saveRecentWorkspaces(recents) {
   try {
     await fs.writeFile(RECENT_WORKSPACES_FILE, JSON.stringify({ recents }, null, 2));
@@ -153,98 +487,68 @@ async function saveRecentWorkspaces(recents) {
   }
 }
 
-// Add or update a workspace in recents
-async function addRecentWorkspace(workspacePath) {
+async function addRecentWorkspace(wsPath) {
   const recents = await loadRecentWorkspaces();
   const now = new Date().toISOString();
-
-  // Remove existing entry with same path (case-insensitive on Windows)
-  const filtered = recents.filter(r =>
-    r.path.toLowerCase() !== workspacePath.toLowerCase()
-  );
-
-  // Add new entry at the beginning
-  filtered.unshift({
-    path: workspacePath,
-    lastUsed: now
-  });
-
-  // Limit to max entries
+  const filtered = recents.filter(r => r.path.toLowerCase() !== wsPath.toLowerCase());
+  filtered.unshift({ path: wsPath, lastUsed: now });
   const limited = filtered.slice(0, MAX_RECENT_WORKSPACES);
-
   await saveRecentWorkspaces(limited);
   return limited;
 }
 
-// Remove a workspace from recents
-async function removeRecentWorkspace(workspacePath) {
+async function removeRecentWorkspace(wsPath) {
   const recents = await loadRecentWorkspaces();
-  const filtered = recents.filter(r =>
-    r.path.toLowerCase() !== workspacePath.toLowerCase()
-  );
+  const filtered = recents.filter(r => r.path.toLowerCase() !== wsPath.toLowerCase());
   await saveRecentWorkspaces(filtered);
   return filtered;
 }
 
-// Update path of a workspace in recents (for "Locate" functionality)
-async function updateRecentWorkspacePath(oldPath, newPath) {
-  const recents = await loadRecentWorkspaces();
-  const now = new Date().toISOString();
-
-  const updated = recents.map(r => {
-    if (r.path.toLowerCase() === oldPath.toLowerCase()) {
-      return { path: newPath, lastUsed: now };
-    }
-    return r;
-  });
-
-  await saveRecentWorkspaces(updated);
-  return updated;
-}
-
-// Validate if a workspace path exists and is a directory
-async function validateWorkspacePath(workspacePath) {
+async function validateWorkspacePath(wsPath) {
   try {
-    const stats = await fs.stat(workspacePath);
+    const stats = await fs.stat(wsPath);
     return stats.isDirectory();
   } catch (error) {
     return false;
   }
 }
 
-// Get current working directory info
-function getCurrentDirectoryInfo() {
-  const cwd = process.cwd();
-  const appDir = __dirname;
-
-  // Check if cwd is different from app directory and exists
-  const isUsable = cwd !== appDir && fsSync.existsSync(cwd);
+// ═══════════════════════════════════════════════════════════
+// Browser window
+// ═══════════════════════════════════════════════════════════
 
-  return {
-    path: cwd,
-    isUsable,
-    appDir
-  };
-}
-
-// Create the browser window
 function createWindow() {
   console.log('Creating window...');
 
   const iconPath = path.join(__dirname, 'robot.png');
 
-  mainWindow = new BrowserWindow({
+  const windowOptions = {
     width: 1400,
     height: 900,
     icon: iconPath,
+    show: false,
+    backgroundColor: '#0b0e11',
     webPreferences: {
       preload: path.join(__dirname, 'preload.js'),
       contextIsolation: true,
       nodeIntegration: false
     }
+  };
+
+  if (process.platform === 'darwin') {
+    windowOptions.titleBarStyle = 'hiddenInset';
+    windowOptions.trafficLightPosition = { x: 16, y: 16 };
+  }
+
+  mainWindow = new BrowserWindow(windowOptions);
+
+  mainWindow.once('ready-to-show', () => {
+    mainWindow.show();
+  });
+  mainWindow.on('closed', () => {
+    mainWindow = null;
   });
 
-  // Set dock icon on macOS
   if (process.platform === 'darwin' && app.dock) {
     app.dock.setIcon(iconPath);
   }
@@ -259,122 +563,143 @@ function createWindow() {
   console.log('Window setup complete');
 }
 
-// Load configuration with priority: CLI arg > home config > bundled default
-async function loadConfig(configPath = null) {
-  try {
-    let fullPath;
-
-    // Priority 1: CLI argument (--config flag or CONFIG env var)
-    if (configPath) {
-      fullPath = path.isAbsolute(configPath) ? configPath : path.join(process.cwd(), configPath);
-      console.log('Loading config from CLI arg:', fullPath);
-    }
-    // Priority 2: Home directory config (~/.multiagent-chat/config.yaml)
-    else if (fsSync.existsSync(HOME_CONFIG_FILE)) {
-      fullPath = HOME_CONFIG_FILE;
-      console.log('Loading config from home dir:', fullPath);
-    }
-    // Priority 3: Bundled default (fallback)
-    else {
-      fullPath = path.join(__dirname, 'config.yaml');
-      console.log('Loading bundled config from:', fullPath);
+// ═══════════════════════════════════════════════════════════
+// Config loading
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * Deep-merge two objects. Objects are merged recursively;
+ * arrays and primitives from `override` replace `base` wholesale.
+ */
+function deepMerge(base, override) {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    if (
+      override[key] !== null &&
+      typeof override[key] === 'object' &&
+      !Array.isArray(override[key]) &&
+      typeof result[key] === 'object' &&
+      result[key] !== null &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(result[key], override[key]);
+    } else {
+      result[key] = override[key];
     }
-
-    const configFile = await fs.readFile(fullPath, 'utf8');
-    config = yaml.parse(configFile);
-    console.log('Config loaded successfully');
-    return config;
-  } catch (error) {
-    console.error('Error loading config:', error);
-    throw error;
   }
+  return result;
 }
 
-// Setup workspace directory and files
-// customPath = project root selected by user (or from CLI)
-async function setupWorkspace(customPath = null) {
-  // Determine project root (agentCwd) and workspace path (.multiagent-chat inside it)
-  let projectRoot;
-
-  if (customPath && path.isAbsolute(customPath)) {
-    projectRoot = customPath;
-  } else if (customPath) {
-    projectRoot = path.join(process.cwd(), customPath);
-  } else {
-    // Fallback: use current directory as project root
-    projectRoot = process.cwd();
+/**
+ * Collect dot-paths present in `base` but missing from `obj`.
+ */
+function findMissingKeys(base, obj, prefix = '') {
+  const missing = [];
+  for (const key of Object.keys(base)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (!(key in obj)) {
+      missing.push(fullKey);
+    } else if (
+      typeof base[key] === 'object' &&
+      base[key] !== null &&
+      !Array.isArray(base[key]) &&
+      typeof obj[key] === 'object' &&
+      obj[key] !== null &&
+      !Array.isArray(obj[key])
+    ) {
+      missing.push(...findMissingKeys(base[key], obj[key], fullKey));
+    }
   }
+  return missing;
+}
 
-  // Set agent working directory to the project root
-  agentCwd = projectRoot;
-
-  // Set workspace path to .multiagent-chat inside the project root
-  const workspaceName = config.workspace || '.multiagent-chat';
-  workspacePath = path.join(projectRoot, workspaceName);
+/**
+ * Validate that required config fields are present after merge.
+ */
+function validateConfig(cfg) {
+  if (!cfg.agents || !Array.isArray(cfg.agents) || cfg.agents.length === 0) {
+    throw new Error('Config validation failed: "agents" must be a non-empty array.');
+  }
+  for (let i = 0; i < cfg.agents.length; i++) {
+    const agent = cfg.agents[i];
+    if (!agent.name || typeof agent.name !== 'string') {
+      throw new Error(`Config validation failed: agents[${i}] is missing a valid "name".`);
+    }
+    if (!agent.command || typeof agent.command !== 'string') {
+      throw new Error(`Config validation failed: agents[${i}] ("${agent.name}") is missing a valid "command".`);
+    }
+  }
+}
 
+async function loadConfig(configPath = null) {
   try {
-    await fs.mkdir(workspacePath, { recursive: true });
+    // Always load bundled config as the defaults base
+    const bundledPath = path.join(__dirname, 'config.yaml');
+    const bundledFile = await fs.readFile(bundledPath, 'utf8');
+    const defaults = yaml.parse(bundledFile);
+    console.log('Loaded bundled defaults from:', bundledPath);
 
-    // Initialize chat.jsonl (empty file - JSONL format)
-    const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
-    await fs.writeFile(chatPath, '');
-
-    // Clear PLAN_FINAL.md if it exists
-    const planPath = path.join(workspacePath, config.plan_file || 'PLAN_FINAL.md');
-    await fs.writeFile(planPath, '');
-
-    // Create outbox directory and per-agent outbox files
-    const outboxDir = path.join(workspacePath, config.outbox_dir || 'outbox');
-    await fs.mkdir(outboxDir, { recursive: true });
-
-    // Build agent colors map from config
-    const defaultColors = config.default_agent_colors || ['#667eea', '#f093fb', '#4fd1c5', '#f6ad55', '#68d391', '#fc8181'];
-    agentColors = {};
-    config.agents.forEach((agentConfig, index) => {
-      agentColors[agentConfig.name.toLowerCase()] = agentConfig.color || defaultColors[index % defaultColors.length];
-    });
-    // Add user color
-    agentColors['user'] = config.user_color || '#a0aec0';
+    // Determine the user config path
+    let userConfigPath = null;
+    let isHomeConfig = false;
 
-    // Create empty outbox file for each agent
-    for (const agentConfig of config.agents) {
-      const outboxFile = path.join(outboxDir, `${agentConfig.name.toLowerCase()}.md`);
-      await fs.writeFile(outboxFile, '');
+    if (configPath) {
+      userConfigPath = path.isAbsolute(configPath) ? configPath : path.join(process.cwd(), configPath);
+      console.log('Loading user config from CLI arg:', userConfigPath);
+    } else if (fsSync.existsSync(HOME_CONFIG_FILE)) {
+      userConfigPath = HOME_CONFIG_FILE;
+      isHomeConfig = true;
+      console.log('Loading user config from home dir:', userConfigPath);
     }
 
-    // Reset message sequence
-    messageSequence = 0;
-
-    // Capture git base commit for diff baseline
-    try {
-      const { stdout } = await execAsync('git rev-parse HEAD', { cwd: agentCwd });
-      sessionBaseCommit = stdout.trim();
-      console.log('Session base commit:', sessionBaseCommit);
-    } catch (error) {
-      // Check if it's a git repo with no commits yet
-      try {
-        await execAsync('git rev-parse --git-dir', { cwd: agentCwd });
-        // It's a git repo but no commits - use empty tree hash
-        sessionBaseCommit = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
-        console.log('Git repo with no commits, using empty tree hash for diff baseline');
-      } catch (e) {
-        console.log('Not a git repository:', e.message);
-        sessionBaseCommit = null;
+    if (userConfigPath) {
+      const userFile = await fs.readFile(userConfigPath, 'utf8');
+      const userConfig = yaml.parse(userFile);
+
+      // Detect keys that will be backfilled from defaults
+      const missingKeys = findMissingKeys(defaults, userConfig);
+      if (missingKeys.length > 0) {
+        console.log('Config: backfilling missing keys from defaults:', missingKeys.join(', '));
+
+        // Write back merged config for home config only (not --config custom paths)
+        if (isHomeConfig) {
+          const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+          const backupPath = path.join(HOME_CONFIG_DIR, `config.yaml.bak.${timestamp}`);
+          await fs.copyFile(HOME_CONFIG_FILE, backupPath);
+          console.log('Config: backed up existing config to:', backupPath);
+
+          const merged = deepMerge(defaults, userConfig);
+          const tmpPath = HOME_CONFIG_FILE + '.tmp';
+          const yamlStr = '# Multi-Agent Chat Configuration\n'
+            + '# Auto-updated with new defaults. Your values have been preserved.\n'
+            + '# Backup of previous config: ' + path.basename(backupPath) + '\n\n'
+            + yaml.stringify(merged, { indent: 2, lineWidth: 0 });
+          await fs.writeFile(tmpPath, yamlStr, 'utf8');
+          await fs.rename(tmpPath, HOME_CONFIG_FILE);
+          console.log('Config: wrote merged config back to:', HOME_CONFIG_FILE);
+        }
       }
+
+      // Deep-merge: user values override defaults
+      config = deepMerge(defaults, userConfig);
+    } else {
+      console.log('No user config found, using bundled defaults');
+      config = defaults;
     }
 
-    console.log('Workspace setup complete:', workspacePath);
-    console.log('Agent working directory:', agentCwd);
-    console.log('Outbox directory created:', outboxDir);
-    console.log('Agent colors:', agentColors);
-    return workspacePath;
+    validateConfig(config);
+    console.log('Config loaded and validated successfully');
+    return config;
   } catch (error) {
-    console.error('Error setting up workspace:', error);
+    console.error('Error loading config:', error);
     throw error;
   }
 }
 
+// ═══════════════════════════════════════════════════════════
 // Agent Process Management
+// ═══════════════════════════════════════════════════════════
+
 class AgentProcess {
   constructor(agentConfig, index) {
     this.name = agentConfig.name;
@@ -384,14 +709,21 @@ class AgentProcess {
     this.index = index;
     this.process = null;
     this.outputBuffer = [];
+    this.lastPrompt = null;
+    this.intentionalStop = false;
+    this.restartCount = 0;
+    this.maxRestarts = 3;
+    this.initDelay = agentConfig.init_delay_ms || (agentConfig.name === 'Codex' ? 5000 : 3000);
   }
 
   async start(prompt) {
+    this.lastPrompt = prompt;
+    this.intentionalStop = false;
+
     return new Promise((resolve, reject) => {
       console.log(`Starting agent ${this.name} with PTY: ${this.use_pty}`);
 
       if (this.use_pty) {
-        // Use PTY for interactive TUI agents
         const shell = process.env.SHELL || '/bin/bash';
 
         this.process = pty.spawn(this.command, this.args, {
@@ -414,95 +746,60 @@ class AgentProcess {
 
         console.log(`PTY spawned for ${this.name}, PID: ${this.process.pid}`);
 
-        // Respond to cursor position query immediately
-        // This helps with terminal capability detection (needed for Codex)
         setTimeout(() => {
-          this.process.write('\x1b[1;1R'); // Report cursor at position 1,1
+          this.process.write('\x1b[1;1R');
         }, 100);
 
-        // Capture all output from PTY
         this.process.onData((data) => {
           const output = data.toString();
           this.outputBuffer.push(output);
-
-          if (mainWindow) {
-            mainWindow.webContents.send('agent-output', {
-              agentName: this.name,
-              output: output,
-              isPty: true
-            });
-          }
+          sendToRenderer('agent-output', {
+            agentName: this.name,
+            output: output,
+            isPty: true
+          });
         });
 
-        // Handle exit - trigger resume if enabled
         this.process.onExit(({ exitCode, signal }) => {
           console.log(`Agent ${this.name} exited with code ${exitCode}, signal ${signal}`);
           this.handleExit(exitCode);
         });
 
-        // Inject prompt via PTY after TUI initializes (original working pattern)
-        const initDelay = this.name === 'Codex' ? 5000 : 3000;
         setTimeout(() => {
           console.log(`Injecting prompt into ${this.name} PTY`);
           this.process.write(prompt + '\n');
-
-          // Send Enter key after a brief delay to submit
           setTimeout(() => {
             this.process.write('\r');
           }, 500);
-
           resolve();
-        }, initDelay);
+        }, this.initDelay);
 
       } else {
-        // Use regular spawn for non-interactive agents
         const options = {
           cwd: agentCwd,
-          env: {
-            ...process.env,
-            AGENT_NAME: this.name
-          }
+          env: { ...process.env, AGENT_NAME: this.name }
         };
 
         this.process = spawn(this.command, this.args, options);
-
         console.log(`Process spawned for ${this.name}, PID: ${this.process.pid}`);
 
-        // Capture stdout
         this.process.stdout.on('data', (data) => {
           const output = data.toString();
           this.outputBuffer.push(output);
-
-          if (mainWindow) {
-            mainWindow.webContents.send('agent-output', {
-              agentName: this.name,
-              output: output,
-              isPty: false
-            });
-          }
+          sendToRenderer('agent-output', { agentName: this.name, output, isPty: false });
         });
 
-        // Capture stderr
         this.process.stderr.on('data', (data) => {
           const output = data.toString();
           this.outputBuffer.push(`[stderr] ${output}`);
-
-          if (mainWindow) {
-            mainWindow.webContents.send('agent-output', {
-              agentName: this.name,
-              output: `[stderr] ${output}`,
-              isPty: false
-            });
-          }
+          sendToRenderer('agent-output', { agentName: this.name, output: `[stderr] ${output}`, isPty: false });
         });
 
-        // Handle process exit - trigger resume if enabled
         this.process.on('close', (code) => {
           console.log(`Agent ${this.name} exited with code ${code}`);
           this.handleExit(code);
         });
 
-        // Handle errors
         this.process.on('error', (error) => {
           console.error(`Error starting agent ${this.name}:`, error);
           reject(error);
@@ -513,10 +810,51 @@ class AgentProcess {
     });
   }
 
-  // Handle agent exit
   handleExit(exitCode) {
-    if (mainWindow) {
-      mainWindow.webContents.send('agent-status', {
+    if (this.intentionalStop) {
+      console.log(`Agent ${this.name} stopped intentionally`);
+      sendToRenderer('agent-status', {
+        agentName: this.name,
+        status: 'stopped',
+        exitCode: exitCode
+      });
+      return;
+    }
+
+    // Unexpected exit - attempt relaunch
+    if (this.restartCount < this.maxRestarts && this.lastPrompt) {
+      this.restartCount++;
+      console.log(`Agent ${this.name} exited unexpectedly (code ${exitCode}), restarting (attempt ${this.restartCount}/${this.maxRestarts})...`);
+
+      sendToRenderer('agent-status', {
+        agentName: this.name,
+        status: 'restarting',
+        exitCode: exitCode,
+        restartCount: this.restartCount
+      });
+
+      // Wait a moment before relaunching (give time for auto-updates etc.)
+      const delay = 2000 * this.restartCount;
+      setTimeout(() => {
+        this.start(this.lastPrompt).then(() => {
+          console.log(`Agent ${this.name} restarted successfully (attempt ${this.restartCount})`);
+          sendToRenderer('agent-status', {
+            agentName: this.name,
+            status: 'running'
+          });
+        }).catch(err => {
+          console.error(`Failed to restart agent ${this.name}:`, err);
+          sendToRenderer('agent-status', {
+            agentName: this.name,
+            status: 'stopped',
+            exitCode: exitCode,
+            error: `Restart failed: ${err.message}`
+          });
+        });
+      }, delay);
+    } else {
+      console.log(`Agent ${this.name} exited (code ${exitCode}), max restarts reached or no prompt stored`);
+      sendToRenderer('agent-status', {
         agentName: this.name,
         status: 'stopped',
         exitCode: exitCode
@@ -528,10 +866,7 @@ class AgentProcess {
     if (this.use_pty) {
       if (this.process && this.process.write) {
         this.process.write(message + '\n');
-        // Send Enter key to submit for PTY
-        setTimeout(() => {
-          this.process.write('\r');
-        }, 300);
+        setTimeout(() => { this.process.write('\r'); }, 300);
       }
     } else {
       if (this.process && this.process.stdin) {
@@ -541,6 +876,7 @@ class AgentProcess {
   }
 
   stop() {
+    this.intentionalStop = true;
     if (this.process) {
       if (this.use_pty) {
         this.process.kill();
@@ -551,71 +887,69 @@ class AgentProcess {
   }
 }
 
-// Initialize agents from config
 function initializeAgents() {
   agents = config.agents.map((agentConfig, index) => {
     return new AgentProcess(agentConfig, index);
   });
-
   console.log(`Initialized ${agents.length} agents`);
   return agents;
 }
 
-// Get agent by name
 function getAgentByName(name) {
   return agents.find(a => a.name.toLowerCase() === name.toLowerCase());
 }
 
-// Send a message to all agents EXCEPT the sender
-function sendMessageToOtherAgents(senderName, message) {
-  const workspaceFolder = path.basename(workspacePath);
+// ═══════════════════════════════════════════════════════════
+// Message routing
+// ═══════════════════════════════════════════════════════════
+
+function getOutboxRelativePath(agentName) {
+  // Build path relative to agentCwd: sessions/<id>/outbox/<agent>.md
+  // But we need it relative from agentCwd perspective
+  const relFromProject = path.relative(agentCwd, workspacePath);
   const outboxDir = config.outbox_dir || 'outbox';
+  return `${relFromProject}/${outboxDir}/${agentName.toLowerCase()}.md`;
+}
 
+function sendMessageToOtherAgents(senderName, message) {
+  const timestamp = new Date().toISOString();
   for (const agent of agents) {
     if (agent.name.toLowerCase() !== senderName.toLowerCase()) {
-      // Path relative to agentCwd (includes workspace folder)
-      const outboxFile = `${workspaceFolder}/${outboxDir}/${agent.name.toLowerCase()}.md`;
-      const formattedMessage = `\n---\n📨 MESSAGE FROM ${senderName.toUpperCase()}:\n\n${message}\n\n---\n(Respond via: cat << 'EOF' > ${outboxFile})\n`;
-
+      const outboxFile = getOutboxRelativePath(agent.name);
+      const formattedMessage = `\n---\n📨 MESSAGE FROM ${senderName.toUpperCase()}:\n🕐 ${timestamp}\n\n${message}\n\n---\n(Respond via: cat << 'EOF' > ${outboxFile})\n`;
       console.log(`Delivering message from ${senderName} to ${agent.name}`);
       agent.sendMessage(formattedMessage);
     }
   }
 }
 
-// Send a message to ALL agents (for user messages)
 function sendMessageToAllAgents(message) {
-  const workspaceFolder = path.basename(workspacePath);
-  const outboxDir = config.outbox_dir || 'outbox';
-
+  const timestamp = new Date().toISOString();
   for (const agent of agents) {
-    // Path relative to agentCwd (includes workspace folder)
-    const outboxFile = `${workspaceFolder}/${outboxDir}/${agent.name.toLowerCase()}.md`;
-    const formattedMessage = `\n---\n📨 MESSAGE FROM USER:\n\n${message}\n\n---\n(Respond via: cat << 'EOF' > ${outboxFile})\n`;
-
+    const outboxFile = getOutboxRelativePath(agent.name);
+    const formattedMessage = `\n---\n📨 MESSAGE FROM USER:\n🕐 ${timestamp}\n\n${message}\n\n---\n(Respond via: cat << 'EOF' > ${outboxFile})\n`;
     console.log(`Delivering user message to ${agent.name}`);
     agent.sendMessage(formattedMessage);
   }
 }
 
-// Build prompt for a specific agent
 function buildAgentPrompt(challenge, agentName) {
-  const workspaceFolder = path.basename(workspacePath);
+  const relFromProject = path.relative(agentCwd, workspacePath);
   const outboxDir = config.outbox_dir || 'outbox';
-  // Path relative to agentCwd (includes workspace folder)
-  const outboxFile = `${workspaceFolder}/${outboxDir}/${agentName.toLowerCase()}.md`;
-  const planFile = `${workspaceFolder}/${config.plan_file || 'PLAN_FINAL.md'}`;
+  const outboxFile = `${relFromProject}/${outboxDir}/${agentName.toLowerCase()}.md`;
+  const planFile = `${relFromProject}/${config.plan_file || 'PLAN_FINAL.md'}`;
+
+  const template = config.prompt_template || `## Multi-Agent Collaboration Session\n\n**You are: {agent_name}**\nYou are collaborating with: {agent_names}\n\n## Topic\n\n{challenge}\n\nSend messages by writing to: {outbox_file}\nFinal plan goes in: {plan_file}\n`;
 
-  return config.prompt_template
+  return template
     .replace('{challenge}', challenge)
     .replace('{workspace}', workspacePath)
-    .replace(/{outbox_file}/g, outboxFile)  // Replace all occurrences
-    .replace(/{plan_file}/g, planFile)  // Replace all occurrences
+    .replace(/{outbox_file}/g, outboxFile)
+    .replace(/{plan_file}/g, planFile)
     .replace('{agent_names}', agents.map(a => a.name).join(', '))
     .replace('{agent_name}', agentName);
 }
 
-// Start all agents with their individual prompts
 async function startAgents(challenge) {
   console.log('Starting agents with prompts...');
 
@@ -625,27 +959,25 @@ async function startAgents(challenge) {
       await agent.start(prompt);
       console.log(`Started agent: ${agent.name}`);
 
-      if (mainWindow) {
-        mainWindow.webContents.send('agent-status', {
-          agentName: agent.name,
-          status: 'running'
-        });
-      }
+      sendToRenderer('agent-status', {
+        agentName: agent.name,
+        status: 'running'
+      });
     } catch (error) {
       console.error(`Failed to start agent ${agent.name}:`, error);
-
-      if (mainWindow) {
-        mainWindow.webContents.send('agent-status', {
-          agentName: agent.name,
-          status: 'error',
-          error: error.message
-        });
-      }
+      sendToRenderer('agent-status', {
+        agentName: agent.name,
+        status: 'error',
+        error: error.message
+      });
     }
   }
 }
 
-// Watch chat.jsonl for changes (backup - real-time updates via chat-message event)
+// ═══════════════════════════════════════════════════════════
+// File watchers
+// ═══════════════════════════════════════════════════════════
+
 function startFileWatcher() {
   const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
 
@@ -654,14 +986,10 @@ function startFileWatcher() {
     ignoreInitial: true
   });
 
-  // Note: Primary updates happen via 'chat-message' events sent when outbox is processed
-  // This watcher is a backup for any external modifications
   fileWatcher.on('change', async () => {
     try {
       const messages = await getChatContent();
-      if (mainWindow) {
-        mainWindow.webContents.send('chat-updated', messages);
-      }
+      sendToRenderer('chat-updated', messages);
     } catch (error) {
       console.error('Error reading chat file:', error);
     }
@@ -670,47 +998,38 @@ function startFileWatcher() {
   console.log('File watcher started for:', chatPath);
 }
 
-// Watch outbox directory and merge messages into chat.jsonl
 function startOutboxWatcher() {
   const outboxDir = path.join(workspacePath, config.outbox_dir || 'outbox');
   const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
 
-  // Track which files we're currently processing to avoid race conditions
   const processing = new Set();
 
   outboxWatcher = chokidar.watch(outboxDir, {
     persistent: true,
     ignoreInitial: true,
     awaitWriteFinish: {
-      stabilityThreshold: 500,  // Wait for file to be stable for 500ms
+      stabilityThreshold: 500,
       pollInterval: 100
     }
   });
 
   outboxWatcher.on('change', async (filePath) => {
-    // Only process .md files
     if (!filePath.endsWith('.md')) return;
-
-    // Avoid processing the same file concurrently
     if (processing.has(filePath)) return;
     processing.add(filePath);
 
     try {
-      // Read the outbox file
       const content = await fs.readFile(filePath, 'utf8');
       const trimmedContent = content.trim();
 
-      // Skip if empty
       if (!trimmedContent) {
         processing.delete(filePath);
         return;
       }
 
-      // Extract agent name from filename (e.g., "claude.md" -> "Claude")
       const filename = path.basename(filePath, '.md');
       const agentName = filename.charAt(0).toUpperCase() + filename.slice(1);
 
-      // Increment sequence and create message object
       messageSequence++;
       const timestamp = new Date().toISOString();
       const message = {
@@ -722,21 +1041,22 @@ function startOutboxWatcher() {
         color: agentColors[agentName.toLowerCase()] || '#667eea'
       };
 
-      // Append to chat.jsonl
       await fs.appendFile(chatPath, JSON.stringify(message) + '\n');
       console.log(`Merged message from ${agentName} (#${messageSequence}) into chat.jsonl`);
 
-      // Clear the outbox file
       await fs.writeFile(filePath, '');
 
-      // PUSH message to other agents' PTYs
       sendMessageToOtherAgents(agentName, trimmedContent);
 
-      // Notify renderer with the new message
-      if (mainWindow) {
-        mainWindow.webContents.send('chat-message', message);
+      // Update session index with message count and lastActiveAt
+      if (currentSessionId && agentCwd) {
+        updateSessionInIndex(agentCwd, currentSessionId, {
+          lastActiveAt: timestamp,
+          messageCount: messageSequence
+        }).catch(e => console.warn('Failed to update session index:', e.message));
       }
 
+      sendToRenderer('chat-message', message);
     } catch (error) {
       console.error(`Error processing outbox file ${filePath}:`, error);
     } finally {
@@ -747,7 +1067,6 @@ function startOutboxWatcher() {
   console.log('Outbox watcher started for:', outboxDir);
 }
 
-// Stop outbox watcher
 function stopOutboxWatcher() {
   if (outboxWatcher) {
     outboxWatcher.close();
@@ -755,7 +1074,10 @@ function stopOutboxWatcher() {
   }
 }
 
-// Append user message to chat.jsonl and push to all agents
+// ═══════════════════════════════════════════════════════════
+// Chat / Plan / Diff
+// ═══════════════════════════════════════════════════════════
+
 async function sendUserMessage(messageText) {
   const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
   messageSequence++;
@@ -771,39 +1093,35 @@ async function sendUserMessage(messageText) {
   };
 
   try {
-    // Append to chat.jsonl
     await fs.appendFile(chatPath, JSON.stringify(message) + '\n');
     console.log(`User message #${messageSequence} appended to chat`);
 
-    // PUSH message to all agents' PTYs
     sendMessageToAllAgents(messageText);
 
-    // Notify renderer with the new message
-    if (mainWindow) {
-      mainWindow.webContents.send('chat-message', message);
+    // Update session index
+    if (currentSessionId && agentCwd) {
+      updateSessionInIndex(agentCwd, currentSessionId, {
+        lastActiveAt: timestamp,
+        messageCount: messageSequence
+      }).catch(e => console.warn('Failed to update session index:', e.message));
     }
 
+    sendToRenderer('chat-message', message);
   } catch (error) {
     console.error('Error appending user message:', error);
     throw error;
   }
 }
 
-// Read current chat content (returns array of message objects)
 async function getChatContent() {
   const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
   try {
     const content = await fs.readFile(chatPath, 'utf8');
     if (!content.trim()) return [];
 
-    // Parse JSONL (one JSON object per line)
     const messages = content.trim().split('\n').map(line => {
-      try {
-        return JSON.parse(line);
-      } catch (e) {
-        console.error('Failed to parse chat line:', line);
-        return null;
-      }
+      try { return JSON.parse(line); }
+      catch (e) { console.error('Failed to parse chat line:', line); return null; }
     }).filter(Boolean);
 
     return messages;
@@ -813,7 +1131,6 @@ async function getChatContent() {
   }
 }
 
-// Read final plan
 async function getPlanContent() {
   const planPath = path.join(workspacePath, config.plan_file || 'PLAN_FINAL.md');
   try {
@@ -823,14 +1140,11 @@ async function getPlanContent() {
   }
 }
 
-// Get git diff - shows uncommitted changes only (git diff HEAD)
 async function getGitDiff() {
-  // Not a git repo or session hasn't started
   if (!agentCwd) {
     return { isGitRepo: false, error: 'No session active' };
   }
 
-  // Check if git repo
   try {
     await execAsync('git rev-parse --git-dir', { cwd: agentCwd });
   } catch (error) {
@@ -845,7 +1159,6 @@ async function getGitDiff() {
       untracked: []
     };
 
-    // Check if HEAD exists (repo might have no commits)
     let hasHead = true;
     try {
       await execAsync('git rev-parse HEAD', { cwd: agentCwd });
@@ -853,17 +1166,13 @@ async function getGitDiff() {
       hasHead = false;
     }
 
-    // Determine diff target - use empty tree hash if no commits yet
     const diffTarget = hasHead ? 'HEAD' : '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 
-    // Get diff stats
     try {
       const { stdout: statOutput } = await execAsync(
         `git diff ${diffTarget} --stat`,
         { cwd: agentCwd, maxBuffer: 10 * 1024 * 1024 }
       );
-
-      // Parse stats from last line (e.g., "3 files changed, 10 insertions(+), 5 deletions(-)")
       const statMatch = statOutput.match(/(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?/);
       if (statMatch) {
         result.stats.filesChanged = parseInt(statMatch[1]) || 0;
@@ -871,10 +1180,9 @@ async function getGitDiff() {
         result.stats.deletions = parseInt(statMatch[3]) || 0;
       }
     } catch (e) {
-      // No changes or other error
+      // No changes
     }
 
-    // Get full diff
     try {
       const { stdout: diffOutput } = await execAsync(
         `git diff ${diffTarget}`,
@@ -885,7 +1193,6 @@ async function getGitDiff() {
       result.diff = '';
     }
 
-    // Get untracked files
     try {
       const { stdout: untrackedOutput } = await execAsync(
         'git ls-files --others --exclude-standard',
@@ -903,7 +1210,10 @@ async function getGitDiff() {
   }
 }
 
+// ═══════════════════════════════════════════════════════════
 // Stop all agents and watchers
+// ═══════════════════════════════════════════════════════════
+
 function stopAllAgents() {
   agents.forEach(agent => agent.stop());
   if (fileWatcher) {
@@ -913,7 +1223,10 @@ function stopAllAgents() {
   stopOutboxWatcher();
 }
 
+// ═══════════════════════════════════════════════════════════
 // IPC Handlers
+// ═══════════════════════════════════════════════════════════
+
 ipcMain.handle('load-config', async () => {
   try {
     console.log('IPC: load-config called');
@@ -926,41 +1239,232 @@ ipcMain.handle('load-config', async () => {
   }
 });
 
-ipcMain.handle('start-session', async (event, { challenge, workspace: selectedWorkspace }) => {
+// Returns CWD (or CLI workspace) as the default workspace
+ipcMain.handle('get-current-workspace', async () => {
+  const ws = customWorkspacePath || process.cwd();
+  const resolved = path.isAbsolute(ws) ? ws : path.resolve(ws);
+  return {
+    path: resolved,
+    name: path.basename(resolved)
+  };
+});
+
+// Returns sessions for a given workspace/project root
+ipcMain.handle('get-sessions-for-workspace', async (event, projectRoot) => {
   try {
-    // Use selected workspace if provided, otherwise fall back to customWorkspacePath
-    const workspaceToUse = selectedWorkspace || customWorkspacePath;
-    await setupWorkspace(workspaceToUse);
+    // Migrate from flat workspace if needed
+    await migrateFromFlatWorkspace(projectRoot);
+
+    const index = await withSessionsLock(async () => {
+      const idx = await loadSessionsIndex(projectRoot);
+
+      // Reconcile stale active sessions: if no agents are running for a session,
+      // downgrade it from 'active' to 'completed'
+      let reconciled = false;
+      for (const session of idx.sessions) {
+        if (session.status === 'active' && session.id !== currentSessionId) {
+          session.status = 'completed';
+          reconciled = true;
+        }
+      }
+      if (reconciled) {
+        await saveSessionsIndex(projectRoot, idx);
+      }
+
+      return idx;
+    });
+
+    return index.sessions || [];
+  } catch (error) {
+    console.error('Error getting sessions:', error);
+    return [];
+  }
+});
+
+// Load session data (chat, plan) without starting agents
+ipcMain.handle('load-session', async (event, { projectRoot, sessionId }) => {
+  try {
+    const data = await loadSessionData(projectRoot, sessionId);
+
+    // Set workspace path to session dir so getChatContent/getPlanContent work
+    workspacePath = data.sessionDir;
+    agentCwd = projectRoot;
+    currentSessionId = sessionId;
+
+    // Build agent colors
+    const defaultColors = config.default_agent_colors || ['#667eea', '#f093fb', '#4fd1c5', '#f6ad55', '#68d391', '#fc8181'];
+    agentColors = {};
+    config.agents.forEach((agentConfig, index) => {
+      agentColors[agentConfig.name.toLowerCase()] = agentConfig.color || defaultColors[index % defaultColors.length];
+    });
+    agentColors['user'] = config.user_color || '#a0aec0';
+
+    // Set messageSequence to last message's seq
+    if (data.messages.length > 0) {
+      messageSequence = data.messages[data.messages.length - 1].seq || data.messages.length;
+    } else {
+      messageSequence = 0;
+    }
+
+    return {
+      success: true,
+      messages: data.messages,
+      plan: data.plan,
+      colors: agentColors,
+      sessionDir: data.sessionDir
+    };
+  } catch (error) {
+    console.error('Error loading session:', error);
+    return { success: false, error: error.message };
+  }
+});
+
+// Resume session - initialize agents with resume context
+ipcMain.handle('resume-session', async (event, { projectRoot, sessionId, newMessage }) => {
+  try {
+    const data = await loadSessionData(projectRoot, sessionId);
+
+    // Set workspace path and agentCwd
+    workspacePath = data.sessionDir;
+    agentCwd = projectRoot;
+    currentSessionId = sessionId;
+
+    await initWorkspaceBase(projectRoot);
+
+    // Set messageSequence
+    if (data.messages.length > 0) {
+      messageSequence = data.messages[data.messages.length - 1].seq || data.messages.length;
+    } else {
+      messageSequence = 0;
+    }
+
+    // Ensure outbox files are clean
+    const outboxDir = path.join(workspacePath, config.outbox_dir || 'outbox');
+    await fs.mkdir(outboxDir, { recursive: true });
+    for (const agentConfig of config.agents) {
+      const outboxFile = path.join(outboxDir, `${agentConfig.name.toLowerCase()}.md`);
+      await fs.writeFile(outboxFile, '');
+    }
+
+    // Initialize agents
     initializeAgents();
-    await startAgents(challenge);
-    startFileWatcher();
-    startOutboxWatcher();  // Watch for agent messages and merge into chat.jsonl
 
-    // Add workspace to recents (agentCwd is the project root)
-    if (agentCwd) {
-      await addRecentWorkspace(agentCwd);
+    // Build resume prompts and start agents
+    const chatSummary = generateChatSummary(data.messages);
+    console.log('Starting agents with resume prompts...');
+
+    for (const agent of agents) {
+      try {
+        const prompt = buildResumePrompt(chatSummary, data.plan, newMessage, agent.name);
+        await agent.start(prompt);
+        console.log(`Started agent: ${agent.name} (resumed)`);
+
+        sendToRenderer('agent-status', {
+          agentName: agent.name,
+          status: 'running'
+        });
+      } catch (error) {
+        console.error(`Failed to start agent ${agent.name}:`, error);
+        sendToRenderer('agent-status', {
+          agentName: agent.name,
+          status: 'error',
+          error: error.message
+        });
+      }
     }
 
-    // Check if this session was started with CLI workspace (and user didn't change it)
-    const isFromCli = customWorkspacePath && (
-      workspaceToUse === customWorkspacePath ||
-      agentCwd === customWorkspacePath ||
-      agentCwd === path.resolve(customWorkspacePath)
-    );
+    // Append user message to chat
+    await sendUserMessage(newMessage);
+
+    // Start watchers
+    startFileWatcher();
+    startOutboxWatcher();
+
+    // Update session index
+    await updateSessionInIndex(projectRoot, sessionId, {
+      lastActiveAt: new Date().toISOString(),
+      status: 'active'
+    });
+
+    // Add to recent workspaces
+    await addRecentWorkspace(projectRoot);
 
     return {
       success: true,
       agents: agents.map(a => ({ name: a.name, use_pty: a.use_pty })),
-      workspace: agentCwd,  // Show the project root, not the internal .multiagent-chat folder
+      workspace: agentCwd,
       colors: agentColors,
-      fromCli: isFromCli
+      sessionId: sessionId
     };
   } catch (error) {
-    console.error('Error starting session:', error);
+    console.error('Error resuming session:', error);
+    return { success: false, error: error.message };
+  }
+});
+
+// Start new session - creates session dir, starts agents
+ipcMain.handle('start-session', async (event, { challenge, workspace: selectedWorkspace }) => {
+  try {
+    const projectRoot = selectedWorkspace || customWorkspacePath || process.cwd();
+    const resolvedRoot = path.isAbsolute(projectRoot) ? projectRoot : path.resolve(projectRoot);
+
+    await initWorkspaceBase(resolvedRoot);
+
+    // Migrate if needed
+    await migrateFromFlatWorkspace(resolvedRoot);
+
+    // Create new session
+    const sessionId = generateSessionId();
+    currentSessionId = sessionId;
+    const sessionDir = await setupSessionDirectory(resolvedRoot, sessionId);
+    workspacePath = sessionDir;
+    const initialTimestamp = new Date().toISOString();
+
+    // Seed chat history with the initial user challenge so it appears in UI immediately.
+    messageSequence = 1;
+    const initialMessage = {
+      seq: messageSequence,
+      type: 'user',
+      agent: 'User',
+      timestamp: initialTimestamp,
+      content: challenge,
+      color: agentColors['user'] || '#a0aec0'
+    };
+    const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
+    await fs.appendFile(chatPath, JSON.stringify(initialMessage) + '\n');
+
+    // Add to session index
+    const sessionMeta = {
+      id: sessionId,
+      title: generateSessionTitle(challenge),
+      firstPrompt: challenge.slice(0, 200),
+      workspace: resolvedRoot,
+      createdAt: initialTimestamp,
+      lastActiveAt: initialTimestamp,
+      messageCount: 1,
+      status: 'active'
+    };
+    await addSessionToIndex(resolvedRoot, sessionMeta);
+
+    initializeAgents();
+    await startAgents(challenge);
+    startFileWatcher();
+    startOutboxWatcher();
+
+    // Add workspace to recents
+    await addRecentWorkspace(resolvedRoot);
+
     return {
-      success: false,
-      error: error.message
+      success: true,
+      agents: agents.map(a => ({ name: a.name, use_pty: a.use_pty })),
+      workspace: agentCwd,
+      colors: agentColors,
+      sessionId: sessionId,
+      initialMessage
     };
+  } catch (error) {
+    console.error('Error starting session:', error);
+    return { success: false, error: error.message };
   }
 });
 
@@ -990,46 +1494,24 @@ ipcMain.handle('stop-agents', async () => {
   return { success: true };
 });
 
+// Reset session - marks current session as completed, stops agents
 ipcMain.handle('reset-session', async () => {
   try {
-    // Stop all agents and watchers
     stopAllAgents();
 
-    // Clear chat file (handle missing file gracefully)
-    if (workspacePath) {
-      const chatPath = path.join(workspacePath, config.chat_file || 'chat.jsonl');
-      try {
-        await fs.writeFile(chatPath, '');
-      } catch (e) {
-        if (e.code !== 'ENOENT') throw e;
-      }
-
-      // Clear plan file (handle missing file gracefully)
-      const planPath = path.join(workspacePath, config.plan_file || 'PLAN_FINAL.md');
-      try {
-        await fs.writeFile(planPath, '');
-      } catch (e) {
-        if (e.code !== 'ENOENT') throw e;
-      }
-
-      // Clear outbox files
-      const outboxDir = path.join(workspacePath, config.outbox_dir || 'outbox');
-      try {
-        const files = await fs.readdir(outboxDir);
-        for (const file of files) {
-          if (file.endsWith('.md')) {
-            await fs.writeFile(path.join(outboxDir, file), '');
-          }
-        }
-      } catch (e) {
-        if (e.code !== 'ENOENT') throw e;
-      }
+    // Mark current session as completed in index
+    if (currentSessionId && agentCwd) {
+      await updateSessionInIndex(agentCwd, currentSessionId, {
+        status: 'completed',
+        lastActiveAt: new Date().toISOString()
+      });
     }
 
     // Reset state
     messageSequence = 0;
     agents = [];
     sessionBaseCommit = null;
+    currentSessionId = null;
 
     return { success: true };
   } catch (error) {
@@ -1038,19 +1520,15 @@ ipcMain.handle('reset-session', async () => {
   }
 });
 
-// Handle start implementation request
 ipcMain.handle('start-implementation', async (event, selectedAgent, otherAgents) => {
   try {
-    // Get the implementation handoff prompt from config
     const promptTemplate = config.prompts?.implementation_handoff ||
       '{selected_agent}, please now implement this plan. {other_agents} please wait for confirmation from {selected_agent} that they have completed the implementation. You should then check the changes, and provide feedback if necessary. Keep iterating together until you are all happy with the implementation.';
 
-    // Substitute placeholders
     const prompt = promptTemplate
       .replace(/{selected_agent}/g, selectedAgent)
       .replace(/{other_agents}/g, otherAgents.join(', '));
 
-    // Send as user message (this handles chat log + delivery to all agents)
     await sendUserMessage(prompt);
 
     console.log(`Implementation started with ${selectedAgent} as implementer`);
@@ -1064,7 +1542,6 @@ ipcMain.handle('start-implementation', async (event, selectedAgent, otherAgents)
 // Workspace Management IPC Handlers
 ipcMain.handle('get-recent-workspaces', async () => {
   const recents = await loadRecentWorkspaces();
-  // Add validation info for each workspace
   const withValidation = await Promise.all(
     recents.map(async (r) => ({
       ...r,
@@ -1075,24 +1552,22 @@ ipcMain.handle('get-recent-workspaces', async () => {
   return withValidation;
 });
 
-ipcMain.handle('add-recent-workspace', async (event, workspacePath) => {
-  return await addRecentWorkspace(workspacePath);
-});
-
-ipcMain.handle('remove-recent-workspace', async (event, workspacePath) => {
-  return await removeRecentWorkspace(workspacePath);
+ipcMain.handle('add-recent-workspace', async (event, wsPath) => {
+  return await addRecentWorkspace(wsPath);
 });
 
-ipcMain.handle('update-recent-workspace-path', async (event, oldPath, newPath) => {
-  return await updateRecentWorkspacePath(oldPath, newPath);
-});
-
-ipcMain.handle('validate-workspace-path', async (event, workspacePath) => {
-  return await validateWorkspacePath(workspacePath);
+ipcMain.handle('remove-recent-workspace', async (event, wsPath) => {
+  return await removeRecentWorkspace(wsPath);
 });
 
 ipcMain.handle('get-current-directory', async () => {
-  return getCurrentDirectoryInfo();
+  const cwd = process.cwd();
+  const appDir = __dirname;
+  return {
+    path: cwd,
+    isUsable: cwd !== appDir && fsSync.existsSync(cwd),
+    appDir
+  };
 });
 
 ipcMain.handle('browse-for-workspace', async () => {
@@ -1105,10 +1580,7 @@ ipcMain.handle('browse-for-workspace', async () => {
     return { canceled: true };
   }
 
-  return {
-    canceled: false,
-    path: result.filePaths[0]
-  };
+  return { canceled: false, path: result.filePaths[0] };
 });
 
 ipcMain.handle('open-config-folder', async () => {
@@ -1136,7 +1608,10 @@ ipcMain.on('pty-input', (event, { agentName, data }) => {
   }
 });
 
+// ═══════════════════════════════════════════════════════════
 // App lifecycle
+// ═══════════════════════════════════════════════════════════
+
 app.whenReady().then(async () => {
   console.log('App ready, setting up...');
   parseCommandLineArgs();
@@ -1157,7 +1632,6 @@ app.on('activate', () => {
   }
 });
 
-// Cleanup on quit
 app.on('before-quit', () => {
   stopAllAgents();
 });