@aion0/forge 0.5.21 → 0.5.23

package/lib/workspace/orchestrator.ts

@@ -11,7 +11,7 @@
  */
 
 import { EventEmitter } from 'node:events';
-import { readFileSync, existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, unlinkSync, mkdirSync, statSync, readdirSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { resolve, join } from 'node:path';
 import { homedir } from 'node:os';
@@ -39,6 +39,7 @@ import {
   loadMemory, saveMemory, createMemory, formatMemoryForPrompt,
   addObservation, addSessionSummary, parseStepToObservations, buildSessionSummary,
 } from './smith-memory';
+import { getFixedSession } from '../project-sessions';
 
 // ─── Orchestrator Events ─────────────────────────────────
 
@@ -66,6 +67,9 @@ export class WorkspaceOrchestrator extends EventEmitter {
   private daemonActive = false;
   private createdAt = Date.now();
   private healthCheckTimer: NodeJS.Timeout | null = null;
+  private settingsValidCache = new Map<string, number>(); // filePath → mtime (validated ok)
+  private agentRunningMsg = new Map<string, string>(); // agentId → messageId currently being processed
+  private reconcileTick = 0; // counts health check ticks for 60s reconcile
 
   /** Emit a log event (auto-persisted via constructor listener) */
   emitLog(agentId: string, entry: any): void {
@@ -304,6 +308,18 @@ export class WorkspaceOrchestrator extends EventEmitter {
   updateAgentConfig(id: string, config: WorkspaceAgentConfig): void {
     const entry = this.agents.get(id);
     if (!entry) return;
+    // Validate agentId exists — fallback to default if deleted from Settings
+    if (config.agentId) {
+      try {
+        const { listAgents, getDefaultAgentId } = require('../agents/index');
+        const validAgents = new Set((listAgents() as any[]).map((a: any) => a.id));
+        if (!validAgents.has(config.agentId)) {
+          const fallback = getDefaultAgentId() || 'claude';
+          console.log(`[workspace] ${config.label}: agent "${config.agentId}" not found, falling back to "${fallback}"`);
+          config.agentId = fallback;
+        }
+      } catch {}
+    }
     const conflict = this.validateOutputs(config, id);
     if (conflict) throw new Error(conflict);
     const cycleErr = this.detectCycle(id, config.dependsOn);
@@ -328,6 +344,11 @@ export class WorkspaceOrchestrator extends EventEmitter {
       }
       entry.state.tmuxSession = undefined;
       config.boundSessionId = undefined;
+    } else {
+      // Preserve server-managed fields the client doesn't track
+      if (!config.boundSessionId && entry.config.boundSessionId) {
+        config.boundSessionId = entry.config.boundSessionId;
+      }
     }
 
     entry.config = config;
@@ -341,19 +362,23 @@ export class WorkspaceOrchestrator extends EventEmitter {
     entry.worker = null;
 
     if (this.daemonActive) {
-      // Rebuild worker + message loop
-      this.enterDaemonListening(id);
-      entry.state.smithStatus = 'active';
+      // Set 'starting' BEFORE creating worker — worker.executeDaemon emits 'active' synchronously
+      // which would cause a race: frontend sees active before boundSessionId is ready
+      entry.state.smithStatus = 'starting';
+      this.emit('event', { type: 'smith_status', agentId: id, smithStatus: 'starting' } as any);
       // Restart watch if config changed
       this.watchManager.startWatch(id, config);
-      // Create persistent session if configured (before message loop so inject works)
-      if (config.persistentSession) {
-        this.ensurePersistentSession(id, config).then(() => {
-          this.startMessageLoop(id);
-        });
-      } else {
+      this.ensurePersistentSession(id, config).then(() => {
+        const e = this.agents.get(id);
+        if (e) {
+          // Rebuild worker + message loop AFTER session is ready (boundSessionId set)
+          this.enterDaemonListening(id);
+          e.state.smithStatus = 'active';
+          this.emit('event', { type: 'smith_status', agentId: id, smithStatus: 'active' } as any);
+          this.emitAgentsChanged();
+        }
         this.startMessageLoop(id);
-      }
+      });
     }
     this.saveNow();
     this.emitAgentsChanged();
@@ -706,7 +731,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
     }
 
     // Ensure smith is active when daemon starts this agent
-    if (this.daemonActive && entry.state.smithStatus !== 'active') {
+    // Skip if 'starting': ensurePersistentSession is in progress and will set 'active' when done.
+    if (this.daemonActive && entry.state.smithStatus !== 'active' && entry.state.smithStatus !== 'starting') {
       entry.state.smithStatus = 'active';
       this.emit('event', { type: 'smith_status', agentId, smithStatus: 'active' } satisfies WorkerEvent);
     }
@@ -730,6 +756,9 @@ export class WorkspaceOrchestrator extends EventEmitter {
       }
     }
 
+    // Sync role → CLAUDE.md so CLI agents (Claude Code) see it as system instructions
+    this.syncRoleToClaudeMd(config);
+
     let upstreamContext = this.buildUpstreamContext(config);
     if (userInput) {
       const prefix = '## Additional Instructions:\n' + userInput;
@@ -816,6 +845,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
         this.handleAgentDone(agentId, entry, event.summary);
       }
       if (event.type === 'error') {
+        this.agentRunningMsg.delete(agentId);
         this.bus.notifyError(agentId, event.error);
         this.emitWorkspaceStatus();
       }
@@ -839,6 +869,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
     // Execute in daemon mode (non-blocking)
     worker.executeDaemon(0, upstreamContext).catch(err => {
       if (entry.state.taskStatus !== 'failed') {
+        this.agentRunningMsg.delete(agentId);
         entry.state.taskStatus = 'failed';
         entry.state.error = err?.message || String(err);
         this.emit('event', { type: 'error', agentId, error: entry.state.error! } satisfies WorkerEvent);
@@ -860,6 +891,23 @@ export class WorkspaceOrchestrator extends EventEmitter {
       installForgeSkills(this.projectPath, this.workspaceId, '', Number(process.env.PORT) || 8403);
     } catch {}
 
+    // Validate agent IDs — fallback to default if configured agent was deleted from Settings
+    let defaultAgentId = 'claude';
+    try {
+      const { listAgents, getDefaultAgentId } = await import('../agents/index') as any;
+      const validAgents = new Set((listAgents() as any[]).map(a => a.id));
+      defaultAgentId = getDefaultAgentId() || 'claude';
+      for (const [id, entry] of this.agents) {
+        if (entry.config.type === 'input') continue;
+        if (entry.config.agentId && !validAgents.has(entry.config.agentId)) {
+          console.log(`[daemon] ${entry.config.label}: agent "${entry.config.agentId}" not found, falling back to "${defaultAgentId}"`);
+          entry.config.agentId = defaultAgentId;
+          this.emit('event', { type: 'log', agentId: id, entry: { type: 'system', subtype: 'warning', content: `Agent "${entry.config.agentId}" not found in Settings — using default "${defaultAgentId}"`, timestamp: new Date().toISOString() } } as any);
+          this.saveNow();
+        }
+      }
+    } catch {}
+
     // Start each smith one by one, verify each starts correctly
     let started = 0;
     let failed = 0;
@@ -1033,6 +1081,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
         this.handleAgentDone(agentId, entry, event.summary);
       }
       if (event.type === 'error') {
+        this.agentRunningMsg.delete(agentId);
         this.bus.notifyError(agentId, event.error);
       }
     });
@@ -1100,6 +1149,10 @@ export class WorkspaceOrchestrator extends EventEmitter {
     if (this.sessionMonitor) { this.sessionMonitor.stopAll(); this.sessionMonitor = null; }
     this.stopHealthCheck();
     this.forgeActedMessages.clear();
+    this.busMarkerScanned.clear();
+    this.forgeAgentStartTime = 0;
+    this.agentRunningMsg.clear();
+    this.reconcileTick = 0;
     console.log('[workspace] Daemon stopped');
   }
 
@@ -1168,16 +1221,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
     let sessionId: string | undefined;
 
     if (config.primary) {
-      try {
-        const psPath = join(homedir(), '.forge', 'data', 'project-sessions.json');
-        if (existsSync(psPath)) {
-          const psData = JSON.parse(readFileSync(psPath, 'utf-8'));
-          sessionId = psData[this.projectPath];
-        }
-        console.log(`[session-monitor] ${config.label}: primary fixedSession=${sessionId || 'NONE'}`);
-      } catch (err: any) {
-        console.log(`[session-monitor] ${config.label}: failed to read fixedSession: ${err.message}`);
-      }
+      sessionId = getFixedSession(this.projectPath);
+      console.log(`[session-monitor] ${config.label}: primary fixedSession=${sessionId || 'NONE'}`);
     } else {
       sessionId = config.boundSessionId;
       console.log(`[session-monitor] ${config.label}: boundSession=${sessionId || 'NONE'}`);
@@ -1185,23 +1230,12 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
     if (!sessionId) {
       // Try to auto-bind from session files on disk
-      try {
-        const sessionDir = this.getCliSessionDir(config.workDir);
-        if (existsSync(sessionDir)) {
-          const files = require('node:fs').readdirSync(sessionDir).filter((f: string) => f.endsWith('.jsonl'));
-          if (files.length > 0) {
-            const sorted = files
-              .map((f: string) => ({ name: f, mtime: require('node:fs').statSync(join(sessionDir, f)).mtimeMs }))
-              .sort((a: any, b: any) => b.mtime - a.mtime);
-            sessionId = sorted[0].name.replace('.jsonl', '');
-            if (!config.primary) {
-              config.boundSessionId = sessionId;
-              this.saveNow();
-              console.log(`[session-monitor] ${config.label}: auto-bound to ${sessionId}`);
-            }
-          }
-        }
-      } catch {}
+      sessionId = this.getLatestSessionId(config.workDir);
+      if (sessionId && !config.primary) {
+        config.boundSessionId = sessionId;
+        this.saveNow();
+        console.log(`[session-monitor] ${config.label}: auto-bound to ${sessionId}`);
+      }
       if (!sessionId) {
         console.log(`[session-monitor] ${config.label}: no sessionId, skipping`);
         return;
@@ -1231,6 +1265,20 @@ export class WorkspaceOrchestrator extends EventEmitter {
   private runHealthCheck(): void {
     if (!this.daemonActive) return;
 
+    // Every 60s (6 ticks × 10s): reconcile agentRunningMsg cache with actual bus log
+    this.reconcileTick++;
+    if (this.reconcileTick >= 6) {
+      this.reconcileTick = 0;
+      const log = this.bus.getLog();
+      for (const [agentId, messageId] of this.agentRunningMsg) {
+        const msg = log.find(m => m.id === messageId);
+        if (!msg || msg.status !== 'running') {
+          console.log(`[health] reconcile: clearing stale agentRunningMsg for ${agentId} (msg=${messageId.slice(0, 8)}, status=${msg?.status || 'not found'})`);
+          this.agentRunningMsg.delete(agentId);
+        }
+      }
+    }
+
     for (const [id, entry] of this.agents) {
       if (entry.config.type === 'input') continue;
 
@@ -1244,7 +1292,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
       }
 
       // Check 2: SmithStatus should be active
-      if (entry.state.smithStatus !== 'active') {
+      // Skip: 'starting' means ensurePersistentSession is in progress — overriding would race with it.
+      if (entry.state.smithStatus !== 'active' && entry.state.smithStatus !== 'starting') {
         console.log(`[health] ${entry.config.label}: smith=${entry.state.smithStatus} — setting active`);
         entry.state.smithStatus = 'active';
         this.emit('event', { type: 'smith_status', agentId: id, smithStatus: 'active' } as any);
@@ -1272,7 +1321,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
       // Check 5: Pending messages but agent idle — try wake
       if (entry.state.taskStatus !== 'running') {
         const pending = this.bus.getPendingMessagesFor(id).filter(m => m.from !== id && m.type !== 'ack');
-        if (pending.length > 0 && entry.worker.isListening()) {
+        if (pending.length > 0 && entry.worker?.isListening()) {
           // Message loop should handle this, but if it didn't, log it
           const age = Date.now() - pending[0].timestamp;
           if (age > 30_000) { // stuck for 30+ seconds
@@ -1282,7 +1331,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
       }
 
       // Check 6: persistentSession agent without tmux → auto-restart terminal
-      if (entry.config.persistentSession && !entry.state.tmuxSession) {
+      // Skip if smithStatus='starting': ensurePersistentSession is already in progress.
+      if (entry.config.persistentSession && !entry.state.tmuxSession && entry.state.smithStatus === 'active') {
         console.log(`[health] ${entry.config.label}: persistentSession but no tmux — restarting terminal`);
         this.ensurePersistentSession(id, entry.config).catch(err => {
           console.error(`[health] ${entry.config.label}: failed to restart terminal: ${err.message}`);
@@ -1304,6 +1354,16 @@ export class WorkspaceOrchestrator extends EventEmitter {
     const log = this.bus.getLog();
     const now = Date.now();
 
+    // Pre-build reply index: "from→to" → latest non-ack message timestamp (only after daemon start)
+    // Used for O(1) hasReply lookups instead of O(n) log.some() per message
+    const replyIndex = new Map<string, number>();
+    for (const r of log) {
+      if (r.timestamp < this.forgeAgentStartTime) continue;
+      if (r.type === 'ack') continue;
+      const key = `${r.from}→${r.to}`;
+      if ((replyIndex.get(key) || 0) < r.timestamp) replyIndex.set(key, r.timestamp);
+    }
+
     // Only scan messages from after daemon start (skip all history)
     for (const msg of log) {
       if (msg.timestamp < this.forgeAgentStartTime) continue;
@@ -1323,10 +1383,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
         const nudgeKey = `nudge-${msg.to}->${msg.from}`;
         if (this.forgeActedMessages.has(nudgeKey)) { this.forgeActedMessages.add(msg.id); continue; }
 
-        const hasReply = log.some(r =>
-          r.from === msg.to && r.to === msg.from &&
-          r.timestamp > msg.timestamp && r.type !== 'ack'
-        );
+        const hasReply = (replyIndex.get(`${msg.to}→${msg.from}`) || 0) > msg.timestamp;
         if (!hasReply) {
           const senderLabel = this.agents.get(msg.from)?.config.label || msg.from;
           const targetEntry = this.agents.get(msg.to);
@@ -1812,6 +1869,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
   /** Stop all agents, save final state, and clean up */
   shutdown(): void {
+    this.daemonActive = false;
+    this.stopHealthCheck();
     this.stopAllMessageLoops();
     stopAutoSave(this.workspaceId);
     // Sync save — must complete before process exits
@@ -1826,6 +1885,72 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
   // ─── Private ───────────────────────────────────────────
 
+  /** Sync agent role description into CLAUDE.md so CLI agents read it natively */
+  private syncRoleToClaudeMd(config: WorkspaceAgentConfig): void {
+    if (!config.role?.trim()) return;
+    const workDir = join(this.projectPath, config.workDir || '');
+    const claudeMdPath = join(workDir, 'CLAUDE.md');
+
+    // Build plugin docs from agent's plugins
+    let pluginDocs = '';
+    if (config.plugins?.length) {
+      try {
+        const { getInstalledPlugin, listInstalledPlugins } = require('../plugins/registry');
+        const installed = listInstalledPlugins();
+        const agentPlugins = config.plugins;
+        // Find all instances that match agent's plugin list (by source or direct id)
+        const relevant = installed.filter((p: any) =>
+          agentPlugins.includes(p.id) || agentPlugins.includes(p.source || p.id)
+        );
+        if (relevant.length > 0) {
+          pluginDocs = '\n\n## Available Plugins (via MCP run_plugin)\n';
+          for (const p of relevant) {
+            const def = p.definition;
+            const name = p.instanceName || def.name;
+            pluginDocs += `\n### ${def.icon} ${name} (id: "${p.id}")\n`;
+            if (def.description) pluginDocs += `${def.description}\n`;
+            pluginDocs += '\nActions:\n';
+            for (const [actionName, action] of Object.entries(def.actions) as any[]) {
+              pluginDocs += `- **${actionName}** (${action.run})`;
+              if (def.defaultAction === actionName) pluginDocs += ' [default]';
+              pluginDocs += '\n';
+            }
+            if (Object.keys(def.params).length > 0) {
+              pluginDocs += 'Params: ' + Object.entries(def.params).map(([k, v]: any) =>
+                `${k}${v.required ? '*' : ''} (${v.type})`
+              ).join(', ') + '\n';
+            }
+            pluginDocs += `\nUsage: run_plugin({ plugin: "${p.id}", action: "<action>", params: { ... } })\n`;
+          }
+        }
+      } catch {}
+    }
+
+    const MARKER_START = '<!-- forge:agent-role -->';
+    const MARKER_END = '<!-- /forge:agent-role -->';
+    const roleBlock = `${MARKER_START}\n## Agent Role (managed by Forge)\n\n${config.role.trim()}${pluginDocs}\n${MARKER_END}`;
+
+    try {
+      let content = '';
+      if (existsSync(claudeMdPath)) {
+        content = readFileSync(claudeMdPath, 'utf-8');
+        // Replace existing forge block
+        const regex = new RegExp(`${MARKER_START}[\\s\\S]*?${MARKER_END}`);
+        if (regex.test(content)) {
+          const updated = content.replace(regex, roleBlock);
+          if (updated !== content) writeFileSync(claudeMdPath, updated);
+          return;
+        }
+      }
+      // Append
+      mkdirSync(workDir, { recursive: true });
+      const separator = content && !content.endsWith('\n') ? '\n\n' : content ? '\n' : '';
+      writeFileSync(claudeMdPath, content + separator + roleBlock + '\n');
+    } catch (err) {
+      console.warn(`[workspace] Failed to sync role to CLAUDE.md for ${config.label}:`, err);
+    }
+  }
+
   private createBackend(config: WorkspaceAgentConfig, agentId?: string) {
     switch (config.backend) {
       case 'api':
@@ -1932,6 +2057,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
   /** Unified done handler: broadcast downstream or reply to sender based on message source */
   private handleAgentDone(agentId: string, entry: { config: WorkspaceAgentConfig; worker: AgentWorker | null; state: AgentState }, summary?: string): void {
+    this.agentRunningMsg.delete(agentId);
     const files = entry.state.artifacts.filter(a => a.path).map(a => a.path!);
     console.log(`[workspace] Agent "${entry.config.label}" (${agentId}) completed. Artifacts: ${files.length}.`);
 
@@ -1959,12 +2085,24 @@ export class WorkspaceOrchestrator extends EventEmitter {
       .filter(h => h.subtype === 'final_summary' || h.subtype === 'step_summary')
       .slice(-1)[0]?.content || '';
 
+    // Keep notification concise — agent can read files/git diff for details
+    const shortSummary = summary.split('\n')[0]?.slice(0, 100) || '';
     const content = files.length > 0
-      ? `${completedLabel} completed: ${files.length} files changed. ${summary.slice(0, 200)}. If you are currently processing a task or have seen this before, ignore this notification.`
-      : `${completedLabel} completed. ${summary.slice(0, 300) || 'If you are currently processing a task or have seen this before, ignore this notification.'}`;
+      ? `${completedLabel} completed: ${files.length} files changed.${shortSummary ? ' ' + shortSummary : ''} Run \`git diff --stat HEAD~1\` for details.`
+      : `${completedLabel} completed.${shortSummary ? ' ' + shortSummary : ''}`;
 
     // Find all downstream agents — skip if already sent upstream_complete recently (60s)
     const now = Date.now();
+
+    // Pre-scan log once: build dedup set and pending-to-complete list
+    const recentSentTo = new Set<string>(); // agentIds that received upstream_complete within 60s
+    const pendingToComplete: { m: any; to: string }[] = [];
+    for (const m of this.bus.getLog()) {
+      if (m.from !== completedAgentId || m.payload?.action !== 'upstream_complete') continue;
+      if (now - m.timestamp < 60_000) recentSentTo.add(m.to);
+      if (m.status === 'pending') pendingToComplete.push({ m, to: m.to });
+    }
+
     let sent = 0;
     for (const [id, entry] of this.agents) {
       if (id === completedAgentId) continue;
@@ -1972,19 +2110,14 @@ export class WorkspaceOrchestrator extends EventEmitter {
       if (!entry.config.dependsOn.includes(completedAgentId)) continue;
 
       // Dedup: skip if upstream_complete was sent to this target within last 60s
-      const recentDup = this.bus.getLog().some(m =>
-        m.from === completedAgentId && m.to === id &&
-        m.payload?.action === 'upstream_complete' &&
-        now - m.timestamp < 60_000
-      );
-      if (recentDup) {
+      if (recentSentTo.has(id)) {
         console.log(`[bus] ${completedLabel} → ${entry.config.label}: upstream_complete skipped (sent <60s ago)`);
         continue;
       }
 
-      // Merge: auto-complete older pending upstream_complete from same sender
-      for (const m of this.bus.getLog()) {
-        if (m.from === completedAgentId && m.to === id && m.status === 'pending' && m.payload?.action === 'upstream_complete') {
+      // Merge: auto-complete older pending upstream_complete from same sender to this target
+      for (const { m, to } of pendingToComplete) {
+        if (to === id) {
           m.status = 'done' as any;
           this.emit('event', { type: 'bus_message_status', messageId: m.id, status: 'done' } as any);
         }
@@ -2017,20 +2150,109 @@ export class WorkspaceOrchestrator extends EventEmitter {
     return join(homedir(), '.claude', 'projects', encoded);
   }
 
+  /** Return the latest session ID (by mtime) from the CLI session dir, or undefined if none. */
+  private getLatestSessionId(workDir?: string): string | undefined {
+    try {
+      const sessionDir = this.getCliSessionDir(workDir);
+      if (!existsSync(sessionDir)) return undefined;
+      const files = readdirSync(sessionDir).filter(f => f.endsWith('.jsonl'));
+      if (files.length === 0) return undefined;
+      const latest = files
+        .map(f => ({ name: f, mtime: statSync(join(sessionDir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime)[0];
+      return latest.name.replace('.jsonl', '');
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Lightweight session bind for non-persistentSession agents.
+   *  Checks if the tmux session already exists and sets entry.state.tmuxSession.
+   *  Also auto-binds boundSessionId from the latest session file if not already set.
+   *  Does NOT create any session or run any launch script.
+   */
+  private tryBindExistingSession(agentId: string, config: WorkspaceAgentConfig): void {
+    const entry = this.agents.get(agentId);
+    if (!entry) return;
+
+    const safeName = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').slice(0, 20);
+    const sessionName = `mw-forge-${safeName(this.projectName)}-${safeName(config.label)}`;
+
+    // Check if tmux session is alive → set tmuxSession so open_terminal can return it
+    try {
+      execSync(`tmux has-session -t "${sessionName}" 2>/dev/null`, { timeout: 3000 });
+      if (entry.state.tmuxSession !== sessionName) {
+        entry.state.tmuxSession = sessionName;
+        this.saveNow();
+        console.log(`[daemon] ${config.label}: found existing tmux session, bound tmuxSession`);
+      }
+    } catch {
+      // No existing session — leave tmuxSession undefined, open_terminal will let FloatingTerminal create one
+    }
+
+    // Auto-bind boundSessionId from latest session file if not already set
+    if (!config.boundSessionId) {
+      const sessionId = this.getLatestSessionId(config.workDir);
+      if (sessionId) {
+        config.boundSessionId = sessionId;
+        this.saveNow();
+        console.log(`[daemon] ${config.label}: auto-bound boundSessionId=${sessionId}`);
+      }
+    }
+  }
+
+  /**
+   * Create or attach to the tmux session for an agent (terminal-open path).
+   * Unlike ensurePersistentSession, skips the 3s startup verification so the
+   * HTTP response is fast. Returns the session name, or null on failure.
+   */
+  async openTerminalSession(agentId: string, forceRestart = false): Promise<string | null> {
+    const entry = this.agents.get(agentId);
+    if (!entry || entry.config.type === 'input') return null;
+    const config = entry.config;
+
+    const safeName = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').slice(0, 20);
+    const sessionName = `mw-forge-${safeName(this.projectName)}-${safeName(config.label)}`;
+
+    if (forceRestart) {
+      // Kill existing tmux session so ensurePersistentSession rewrites the launch script
+      // with the current boundSessionId (--resume flag). Safe — claude session data is in jsonl files.
+      try { execSync(`tmux kill-session -t "${sessionName}" 2>/dev/null`, { timeout: 3000 }); } catch {}
+      entry.state.tmuxSession = undefined;
+    } else if (entry.state.tmuxSession) {
+      // Attach to existing session if still alive
+      try {
+        execSync(`tmux has-session -t "${entry.state.tmuxSession}" 2>/dev/null`, { timeout: 3000 });
+        return entry.state.tmuxSession;
+      } catch {
+        entry.state.tmuxSession = undefined;
+      }
+    }
+
+    // Create (or recreate) session without startup verification delay
+    await this.ensurePersistentSession(agentId, config, true);
+    return entry.state.tmuxSession || null;
+  }
+
   /** Create a persistent tmux session with the CLI agent */
-  private async ensurePersistentSession(agentId: string, config: WorkspaceAgentConfig): Promise<void> {
+  private async ensurePersistentSession(agentId: string, config: WorkspaceAgentConfig, skipStartupCheck = false): Promise<void> {
     const safeName = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').slice(0, 20);
     const sessionName = `mw-forge-${safeName(this.projectName)}-${safeName(config.label)}`;
 
-    // Pre-flight: check project's .claude/settings.json is valid
+    // Pre-flight: check project's .claude/settings.json is valid (cached by mtime)
     const workDir = config.workDir && config.workDir !== './' && config.workDir !== '.'
       ? `${this.projectPath}/${config.workDir}` : this.projectPath;
     const projectSettingsFile = join(workDir, '.claude', 'settings.json');
     if (existsSync(projectSettingsFile)) {
       try {
-        const raw = readFileSync(projectSettingsFile, 'utf-8');
-        JSON.parse(raw);
+        const mtime = statSync(projectSettingsFile).mtimeMs;
+        if (this.settingsValidCache.get(projectSettingsFile) !== mtime) {
+          const raw = readFileSync(projectSettingsFile, 'utf-8');
+          JSON.parse(raw);
+          this.settingsValidCache.set(projectSettingsFile, mtime);
+        }
       } catch (err: any) {
+        this.settingsValidCache.delete(projectSettingsFile);
         const errorMsg = `Invalid .claude/settings.json: ${err.message}`;
         console.error(`[daemon] ${config.label}: ${errorMsg}`);
         const entry = this.agents.get(agentId);
@@ -2048,8 +2270,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
     // Write agent context file for hooks to read (workDir/.forge/agent-context.json)
     try {
       const forgeDir = join(workDir, '.forge');
-      const { mkdirSync: mkdirS } = require('node:fs');
-      mkdirS(forgeDir, { recursive: true });
+      mkdirSync(forgeDir, { recursive: true });
       const ctxPath = join(forgeDir, 'agent-context.json');
       writeFileSync(ctxPath, JSON.stringify({
         workspaceId: this.workspaceId,
@@ -2062,22 +2283,53 @@ export class WorkspaceOrchestrator extends EventEmitter {
       console.error(`[daemon] ${config.label}: failed to write agent-context.json: ${err.message}`);
     }
 
-    // Check if tmux session already exists
+    // Check if tmux session already exists and Claude is still alive inside
     let sessionAlreadyExists = false;
+    let tmuxSessionExists = false;
+    console.log(`[daemon] ${config.label}: ensurePersistentSession called — sessionName=${sessionName} boundSessionId=${config.boundSessionId || 'NONE'} skipStartupCheck=${skipStartupCheck}`);
     try {
       execSync(`tmux has-session -t "${sessionName}" 2>/dev/null`, { timeout: 3000 });
-      sessionAlreadyExists = true;
-      console.log(`[daemon] ${config.label}: persistent session already exists (${sessionName})`);
-      // Ensure FORGE env vars are set in the tmux session environment
-      // (for hooks that read them — set-environment makes them available to new processes in this session)
+      tmuxSessionExists = true;
+    } catch {}
+    console.log(`[daemon] ${config.label}: tmuxSessionExists=${tmuxSessionExists}`);
+
+    if (tmuxSessionExists) {
+      // Check if Claude process is still alive inside the tmux pane
+      let claudeAlive = true;
       try {
-        execSync(`tmux set-environment -t "${sessionName}" FORGE_WORKSPACE_ID "${this.workspaceId}"`, { timeout: 3000 });
-        execSync(`tmux set-environment -t "${sessionName}" FORGE_AGENT_ID "${config.id}"`, { timeout: 3000 });
-        execSync(`tmux set-environment -t "${sessionName}" FORGE_PORT "${Number(process.env.PORT) || 8403}"`, { timeout: 3000 });
-      } catch {}
-      // Note: set-environment affects new processes in this tmux session.
-      // Claude Code hooks run as child processes of the shell, which inherits tmux environment.
-    } catch {
+        const paneContent = execSync(`tmux capture-pane -t "${sessionName}" -p -S -5`, { timeout: 3000, encoding: 'utf-8' });
+        const exitedPatterns = [/^\$\s*$/, /\$ $/m, /Process exited/i, /command not found/i];
+        if (exitedPatterns.some(p => p.test(paneContent))) {
+          console.log(`[daemon] ${config.label}: Claude appears to have exited, recreating session`);
+          try { execSync(`tmux kill-session -t "${sessionName}" 2>/dev/null`, { timeout: 3000 }); } catch {}
+          claudeAlive = false;
+        }
+      } catch {
+        // pane capture failed — assume alive
+      }
+
+      if (claudeAlive) {
+        sessionAlreadyExists = true;
+        console.log(`[daemon] ${config.label}: persistent session alive (${sessionName}) — skipping script generation`);
+        // Ensure FORGE env vars are set in the tmux session environment
+        try {
+          execSync(`tmux set-environment -t "${sessionName}" FORGE_WORKSPACE_ID "${this.workspaceId}" && tmux set-environment -t "${sessionName}" FORGE_AGENT_ID "${config.id}" && tmux set-environment -t "${sessionName}" FORGE_PORT "${Number(process.env.PORT) || 8403}"`, { timeout: 5000 });
+        } catch {}
+      }
+    }
+
+    if (!sessionAlreadyExists) {
+      // Pre-bind: find existing session file BEFORE starting CLI so --resume is available from the start.
+      // This avoids starting a fresh CLI then restarting it after polling finds the session.
+      if (!config.primary && !config.boundSessionId) {
+        const existingSessionId = this.getLatestSessionId(config.workDir);
+        if (existingSessionId) {
+          config.boundSessionId = existingSessionId;
+          this.saveNow();
+          console.log(`[daemon] ${config.label}: pre-bound to existing session ${existingSessionId}`);
+        }
+      }
+
       // Create new tmux session and start the CLI agent
       try {
         // Resolve agent launch info
@@ -2103,7 +2355,9 @@ export class WorkspaceOrchestrator extends EventEmitter {
               .join(' && ');
             if (envExports) envExports += ' && ';
           }
-          if (info.model) modelFlag = ` --model ${info.model}`;
+          // Workspace agent model takes priority over profile/settings model
+          const effectiveModel = config.model || info.model;
+          if (effectiveModel) modelFlag = ` --model ${effectiveModel}`;
         } catch {}
 
         // Generate MCP config for Claude Code agents
@@ -2120,8 +2374,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
                 },
               },
             };
-            const { mkdirSync: mkdirS } = await import('node:fs');
-            mkdirS(join(workDir, '.forge'), { recursive: true });
+            mkdirSync(join(workDir, '.forge'), { recursive: true });
             writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
             mcpConfigFlag = ` --mcp-config "${mcpConfigPath}"`;
           } catch (err: any) {
@@ -2150,27 +2403,22 @@ export class WorkspaceOrchestrator extends EventEmitter {
         if (supportsSession) {
           let sessionId: string | undefined;
           if (config.primary) {
-            // Read fixedSessionId directly from file (avoid dynamic import issues in production build)
-            try {
-              const psPath = join(homedir(), '.forge', 'data', 'project-sessions.json');
-              if (existsSync(psPath)) {
-                const psData = JSON.parse(readFileSync(psPath, 'utf-8'));
-                sessionId = psData[this.projectPath];
-              }
-              console.log(`[daemon] ${config.label}: fixedSession=${sessionId || 'NONE'} for ${this.projectPath}`);
-            } catch (err: any) {
-              console.error(`[daemon] ${config.label}: failed to read fixedSession: ${err.message}`);
-            }
+            sessionId = getFixedSession(this.projectPath);
+            console.log(`[daemon] ${config.label}: fixedSession=${sessionId || 'NONE'} for ${this.projectPath}`);
           } else {
             sessionId = config.boundSessionId;
+            console.log(`[daemon] ${config.label}: script-gen boundSessionId=${sessionId || 'NONE'}`);
           }
           if (sessionId) {
             const sessionFile = join(this.getCliSessionDir(config.workDir), `${sessionId}.jsonl`);
             if (existsSync(sessionFile)) {
               cmd += ` --resume ${sessionId}`;
+              console.log(`[daemon] ${config.label}: script-gen adding --resume ${sessionId}`);
             } else {
               console.log(`[daemon] ${config.label}: bound session ${sessionId} missing, starting fresh`);
             }
+          } else {
+            console.log(`[daemon] ${config.label}: script-gen no boundSessionId → no --resume (skipStartupCheck=${skipStartupCheck})`);
           }
         }
         if (modelFlag) cmd += modelFlag;
@@ -2180,12 +2428,54 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
         // Write script and execute in tmux
         const scriptPath = `/tmp/forge-launch-${config.id.replace(/[^a-z0-9-]/g, '')}.sh`;
+        console.log(`[daemon] ${config.label}: writing launch script ${scriptPath}`);
+        console.log(`[daemon] ${config.label}: exec line → ${cmd}`);
         writeFileSync(scriptPath, scriptLines.join('\n'), { mode: 0o755 });
         execSync(`tmux send-keys -t "${sessionName}" 'bash ${scriptPath}' Enter`, { timeout: 5000 });
 
         console.log(`[daemon] ${config.label}: persistent session created (${sessionName}) [${cliType}: ${cliCmd}]`);
 
         // Verify CLI started successfully (check after 3s if process is still alive)
+        // Skip when called from openTerminalSession (terminal-open path) for fast response.
+        if (skipStartupCheck) {
+          // Set tmuxSession here only — normal path sets it after startup verification passes.
+          const entrySkip = this.agents.get(agentId);
+          if (entrySkip) {
+            entrySkip.state.tmuxSession = sessionName;
+            this.saveNow();
+            this.emitAgentsChanged();
+          }
+          // Fire boundSessionId binding in background (no await — don't block terminal open)
+          if (!config.primary && !config.boundSessionId) {
+            const bgScriptPath = `/tmp/forge-launch-${config.id.replace(/[^a-z0-9-]/g, '')}.sh`;
+            setTimeout(() => {
+              const sid = this.getLatestSessionId(config.workDir);
+              if (sid) {
+                config.boundSessionId = sid;
+                this.saveNow();
+                console.log(`[daemon] ${config.label}: background bound to session ${sid}`);
+                // Also update launch script for future restarts
+                if (existsSync(bgScriptPath)) {
+                  try {
+                    const lines = readFileSync(bgScriptPath, 'utf-8').split('\n');
+                    const execIdx = lines.findIndex(l => l.startsWith('exec '));
+                    if (execIdx >= 0) {
+                      const withoutResume = lines[execIdx].replace(/\s--resume\s+\S+/, '');
+                      const afterExec = withoutResume.startsWith('exec ') ? 5 : 0;
+                      const cmdEnd = withoutResume.indexOf(' ', afterExec);
+                      lines[execIdx] = cmdEnd >= 0
+                        ? withoutResume.slice(0, cmdEnd) + ` --resume ${sid}` + withoutResume.slice(cmdEnd)
+                        : withoutResume + ` --resume ${sid}`;
+                      writeFileSync(bgScriptPath, lines.join('\n'), { mode: 0o755 });
+                      console.log(`[daemon] ${config.label}: background updated launch script with --resume ${sid}`);
+                    }
+                  } catch {}
+                }
+              }
+            }, 5000);
+          }
+          return;
+        }
         await new Promise(resolve => setTimeout(resolve, 3000));
         try {
           const paneContent = execSync(`tmux capture-pane -t "${sessionName}" -p -S -20`, { timeout: 3000, encoding: 'utf-8' });
@@ -2220,26 +2510,6 @@ export class WorkspaceOrchestrator extends EventEmitter {
             return;
           }
         } catch {}
-        // Auto-bind session: if no boundSessionId, detect new session file after 5s
-        if (!config.primary && !config.boundSessionId && supportsSession) {
-          setTimeout(() => {
-            try {
-              const sessionDir = this.getCliSessionDir(config.workDir);
-              if (existsSync(sessionDir)) {
-                const { readdirSync, statSync: statS } = require('node:fs');
-                const files = readdirSync(sessionDir).filter((f: string) => f.endsWith('.jsonl'));
-                if (files.length > 0) {
-                  const latest = files
-                    .map((f: string) => ({ name: f, mtime: statS(join(sessionDir, f)).mtimeMs }))
-                    .sort((a: any, b: any) => b.mtime - a.mtime)[0];
-                  config.boundSessionId = latest.name.replace('.jsonl', '');
-                  this.saveNow();
-                  console.log(`[daemon] ${config.label}: auto-bound to session ${config.boundSessionId}`);
-                }
-              }
-            } catch {}
-          }, 5000);
-        }
       } catch (err: any) {
         console.error(`[daemon] ${config.label}: failed to create persistent session: ${err.message}`);
         const entry = this.agents.get(agentId);
@@ -2261,34 +2531,66 @@ export class WorkspaceOrchestrator extends EventEmitter {
       this.emitAgentsChanged();
     }
 
-    // Start session monitor only for newly created sessions (not existing ones)
-    if (!sessionAlreadyExists) {
-      this.startAgentSessionMonitor(agentId, config);
+    // Ensure boundSessionId is set before returning (required for session monitor + --resume)
+    // Also re-bind if existing boundSessionId points to a deleted session file
+    if (!config.primary && config.boundSessionId) {
+      const boundFile = join(this.getCliSessionDir(config.workDir), `${config.boundSessionId}.jsonl`);
+      if (!existsSync(boundFile)) {
+        console.log(`[daemon] ${config.label}: boundSession ${config.boundSessionId} file missing, re-binding`);
+        config.boundSessionId = undefined;
+      }
     }
-
-    // Ensure boundSessionId is set (required for session monitor + --resume)
     if (!config.primary && !config.boundSessionId) {
-      const bindDelay = sessionAlreadyExists ? 500 : 5000;
-      setTimeout(() => {
-        try {
-          const sessionDir = this.getCliSessionDir(config.workDir);
-          if (existsSync(sessionDir)) {
-            const { readdirSync, statSync: statS } = require('node:fs');
-            const files = readdirSync(sessionDir).filter((f: string) => f.endsWith('.jsonl'));
-            if (files.length > 0) {
-              const latest = files
-                .map((f: string) => ({ name: f, mtime: statS(join(sessionDir, f)).mtimeMs }))
-                .sort((a: any, b: any) => b.mtime - a.mtime)[0];
-              config.boundSessionId = latest.name.replace('.jsonl', '');
-              this.saveNow();
-              console.log(`[daemon] ${config.label}: bound to session ${config.boundSessionId}`);
-              this.startAgentSessionMonitor(agentId, config);
-            } else {
-              console.log(`[daemon] ${config.label}: no session files yet, will bind on next check`);
+      const pollStart = Date.now();
+      const pollDelay = sessionAlreadyExists ? 500 : 2000;
+      await new Promise<void>(resolve => {
+        const attempt = () => {
+          if (!this.daemonActive) { resolve(); return; }
+          const sessionId = this.getLatestSessionId(config.workDir);
+          if (sessionId) {
+            config.boundSessionId = sessionId;
+            this.saveNow();
+            console.log(`[daemon] ${config.label}: bound to session ${config.boundSessionId}`);
+            // Update launch script with the now-known sessionId — script was written before
+            // polling completed so it had no --resume flag. Fix it for future restarts.
+            const scriptPath = `/tmp/forge-launch-${config.id.replace(/[^a-z0-9-]/g, '')}.sh`;
+            if (existsSync(scriptPath)) {
+              try {
+                const lines = readFileSync(scriptPath, 'utf-8').split('\n');
+                const execIdx = lines.findIndex(l => l.startsWith('exec '));
+                if (execIdx >= 0) {
+                  // Remove any existing --resume flag, then re-insert after command name.
+                  // Line format: 'exec <cmd> [args...]'
+                  // Insert after cmd (skip 'exec ' prefix + cmd word) so bash doesn't
+                  // misinterpret --resume as an exec builtin option.
+                  const withoutResume = lines[execIdx].replace(/\s--resume\s+\S+/, '');
+                  const afterExec = withoutResume.startsWith('exec ') ? 5 : 0;
+                  const cmdEnd = withoutResume.indexOf(' ', afterExec);
+                  lines[execIdx] = cmdEnd >= 0
+                    ? withoutResume.slice(0, cmdEnd) + ` --resume ${sessionId}` + withoutResume.slice(cmdEnd)
+                    : withoutResume + ` --resume ${sessionId}`;
+                  writeFileSync(scriptPath, lines.join('\n'), { mode: 0o755 });
+                  console.log(`[daemon] ${config.label}: updated launch script with --resume ${sessionId}`);
+                }
+              } catch {}
             }
+            return resolve();
           }
-        } catch {}
-      }, bindDelay);
+          if (Date.now() - pollStart < 10_000) {
+            setTimeout(attempt, 1000);
+          } else {
+            console.log(`[daemon] ${config.label}: no session file after 10s, skipping bind`);
+            const entry = this.agents.get(agentId);
+            if (entry) {
+              entry.state.error = 'Terminal session not ready — click "Open Terminal" to start it manually';
+              this.emit('event', { type: 'smith_status', agentId, smithStatus: entry.state.smithStatus } as any);
+              this.emitAgentsChanged();
+            }
+            resolve();
+          }
+        };
+        setTimeout(attempt, pollDelay);
+      });
     }
   }
 
@@ -2465,9 +2767,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
       // Skip if already busy
       if (entry.state.taskStatus === 'running') return;
 
-      // Skip if any message is already running for this agent
-      const hasRunning = this.bus.getLog().some(m => m.to === agentId && m.status === 'running' && m.type !== 'ack');
-      if (hasRunning) return;
+      // Skip if any message is already running for this agent (O(1) cache lookup)
+      if (this.agentRunningMsg.has(agentId)) return;
 
       // Execution path determined by config, not runtime tmux state
       const isTerminalMode = entry.config.persistentSession;
@@ -2558,6 +2859,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
       // Mark message as running (being processed)
       nextMsg.status = 'running' as any;
+      this.agentRunningMsg.set(agentId, nextMsg.id);
       this.emit('event', { type: 'bus_message_status', messageId: nextMsg.id, status: 'running' } as any);
 
       const logEntry = {
@@ -2571,6 +2873,8 @@ export class WorkspaceOrchestrator extends EventEmitter {
       if (isTerminalMode) {
         const injected = this.injectIntoSession(agentId, nextMsg.payload.content || nextMsg.payload.action);
         if (injected) {
+          entry.state.taskStatus = 'running';
+          this.emit('event', { type: 'task_status', agentId, taskStatus: 'running' } as any);
           this.emit('event', { type: 'log', agentId, entry: { type: 'system', subtype: 'execution_method', content: '📺 Injected into terminal, monitoring for completion...', timestamp: new Date().toISOString() } } as any);
           console.log(`[inbox] ${entry.config.label}: injected into terminal, starting completion monitor`);
           entry.state.currentMessageId = nextMsg.id;
@@ -2580,6 +2884,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
           // Health check will auto-restart the terminal session
           entry.state.tmuxSession = undefined;
           nextMsg.status = 'pending' as any; // revert to pending for retry
+          this.agentRunningMsg.delete(agentId);
           this.emit('event', { type: 'bus_message_status', messageId: nextMsg.id, status: 'pending' } as any);
           this.emit('event', { type: 'log', agentId, entry: { type: 'system', subtype: 'warning', content: '⚠️ Terminal session down — waiting for auto-restart, message will retry', timestamp: new Date().toISOString() } } as any);
           console.log(`[inbox] ${entry.config.label}: terminal inject failed, cleared session — waiting for health check restart`);
@@ -2668,6 +2973,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
           if (promptCount >= CONFIRM_CHECKS) {
             clearInterval(timer);
             this.terminalMonitors.delete(agentId);
+            this.agentRunningMsg.delete(agentId);
 
             // Extract output summary (skip prompt lines)
             const contentLines = lines.filter(l => !PROMPT_PATTERNS.some(p => p.test(l)));
@@ -2698,6 +3004,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
         // Session died
         clearInterval(timer);
         this.terminalMonitors.delete(agentId);
+        this.agentRunningMsg.delete(agentId);
         const msg = this.bus.getLog().find(m => m.id === messageId);
         if (msg && msg.status !== 'done' && msg.status !== 'failed') {
           msg.status = 'failed' as any;