@hamp10/agentforge 0.1.0

package/src/worker.js

@@ -0,0 +1,1791 @@
+#!/usr/bin/env node
+
+import WebSocket from 'ws';
+import { OpenClawCLI } from './OpenClawCLI.js';
+import { HampAgentCLI } from './HampAgentCLI.js';
+import { OllamaAgent } from './OllamaAgent.js';
+import EventEmitter from 'events';
+import path from 'path';
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, copyFileSync, statSync, unlinkSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { homedir, hostname } from 'os';
+import { spawn } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class AgentForgeWorker extends EventEmitter {
+  constructor(token, railwayUrl = 'wss://agentforgeai-production.up.railway.app/socket', workerConfig = {}) {
+    super();
+    this.token = token;
+    this.railwayUrl = railwayUrl;
+    this.ws = null;
+
+    // Pick agent backend from config
+    if (workerConfig.provider === 'local') {
+      const url = workerConfig.localUrl || 'http://localhost:11434';
+      const model = workerConfig.localModel || 'llama3.1:8b';
+      console.log(`🦙 Using local model backend: ${url} / ${model}`);
+      this.cli = new OllamaAgent(url, model);
+    } else if (OpenClawCLI.isAvailable()) {
+      this.cli = new OpenClawCLI();
+      // Wire in the OpenClaw Gateway streaming config so OpenClawCLI can use
+      // per-token SSE streaming instead of waiting for subprocess to exit
+      try {
+        const cfgPath = path.join(homedir(), '.openclaw', 'openclaw.json');
+        if (existsSync(cfgPath)) {
+          const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+          const port = cfg?.gateway?.port || 18789;
+          const token = cfg?.gateway?.auth?.token;
+          if (port && token) {
+            this.cli.gatewayPort = port;
+            this.cli.gatewayToken = token;
+            console.log(`🌊 OpenClaw Gateway streaming enabled (port ${port})`);
+          }
+        }
+      } catch (err) {
+        console.warn(`⚠️ Could not load gateway config for streaming: ${err.message}`);
+      }
+    } else {
+      // openclaw not installed — cannot run without a configured backend
+      console.error('');
+      console.error('❌ No AI backend configured.');
+      console.error('');
+      console.error('   AgentForge needs an AI model to run agents.');
+      console.error('   Configure a local model server (Ollama, LM Studio, Jan, etc.):');
+      console.error('');
+      console.error('     agentforge local --url http://localhost:11434 --model llama3.1:8b');
+      console.error('');
+      console.error('   Then run:  agentforge start');
+      console.error('');
+      process.exit(1);
+    }
+    // Hampagent — always available alongside openclaw
+    this.hampagent = new HampAgentCLI();
+
+    this.activeAgents = new Map();
+    this.reconnectAttempts = 0;
+    this.maxReconnectAttempts = 10;
+
+    // Per-agent task queues to prevent concurrent openclaw processes
+    this.agentQueues = new Map(); // agentId -> array of tasks
+    this.agentProcessing = new Map(); // agentId -> boolean (is currently processing)
+    this.processingStartTime = new Map(); // agentId -> timestamp when processing started
+    this.PROCESSING_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes max for stale processing state (large projects with Opus can be slow)
+    
+    // Track running tasks for cancellation
+    this.runningTasks = new Map(); // taskId -> { agentId, cancelled }
+    
+    // Queue for messages that couldn't be sent while disconnected
+    this.pendingMessages = [];
+    this.maxPendingMessages = 100; // Prevent unbounded growth
+    
+    // Track recently sent completions to prevent duplicates
+    this.recentCompletions = new Set();
+    this.completionTTL = 30000; // 30 seconds
+    
+    // Track agent activity for stuck detection
+    this.lastAgentActivity = new Map(); // agentId -> timestamp
+    this.pingsSinceActivity = new Map(); // agentId -> count
+    this.STUCK_PING_THRESHOLD = 2; // 2 pings with no activity = stuck (~60s since server pings every 30s)
+  }
+
+  speakTextOutLoud(utterance) {
+    if (!utterance || typeof utterance !== 'string') return;
+    const text = utterance.trim();
+    if (!text) return;
+
+    if (process.platform !== 'darwin') {
+      console.log('🔇 TTS requested but platform is not macOS; skipping local audio playback.');
+      return;
+    }
+
+    try {
+      const volumeProc = spawn('osascript', ['-e', 'set volume without output muted', '-e', 'set volume output volume 80'], {
+        stdio: 'ignore'
+      });
+      volumeProc.on('error', (err) => console.warn('⚠️ Unable to adjust volume:', err.message));
+    } catch (err) {
+      console.warn('⚠️ Volume adjustment failed:', err.message);
+    }
+
+    try {
+      const sayProc = spawn('say', [text], { stdio: 'ignore' });
+      sayProc.on('error', (err) => console.warn('⚠️ "say" command failed:', err.message));
+      console.log(`🔊 Speaking aloud: "${text.slice(0, 80)}${text.length > 80 ? '…' : ''}"`);
+    } catch (err) {
+      console.warn('⚠️ Unable to invoke "say":', err.message);
+    }
+  }
+
+  extractSpeechText(toolInput) {
+    if (!toolInput) return '';
+
+    const preferredKeys = ['text', 'input', 'message', 'utterance', 'prompt', 'transcript', 'content'];
+    const visited = new Set();
+
+    const readValue = (value) => {
+      if (value == null) return '';
+      if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : '';
+      }
+      if (typeof value === 'number') {
+        return String(value);
+      }
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          const result = readValue(item);
+          if (result) return result;
+        }
+        return '';
+      }
+      if (typeof value === 'object') {
+        if (visited.has(value)) return '';
+        visited.add(value);
+
+        if (typeof value.text === 'string' && value.text.trim()) {
+          return value.text.trim();
+        }
+        if (value.type === 'text' && typeof value.text === 'string' && value.text.trim()) {
+          return value.text.trim();
+        }
+
+        for (const key of preferredKeys) {
+          if (key in value) {
+            const result = readValue(value[key]);
+            if (result) return result;
+          }
+        }
+
+        for (const nested of Object.values(value)) {
+          const result = readValue(nested);
+          if (result) return result;
+        }
+      }
+      return '';
+    };
+
+    return readValue(toolInput);
+  }
+
+  async initialize() {
+    this._killOrphanedAgents();
+    this.installPreviewServer();
+    this._startAutoUpdateCheck();
+    console.log('✅ Worker initialized');
+  }
+
+  _killOrphanedAgents() {
+    // Kill any openclaw agent processes left over from a previous worker session.
+    // Without this, orphaned processes reconnect to the gateway and block the task queue.
+    for (const name of ['openclaw-agent', 'openclaw-gateway']) {
+      try {
+        const p = spawn('pkill', ['-f', name], { stdio: 'ignore' });
+        p.on('close', (code) => {
+          if (code === 0) console.log(`🧹 Killed orphaned ${name} processes`);
+        });
+      } catch {}
+    }
+  }
+
+  /**
+   * Guard against bloated OpenClaw sessions causing API failures.
+   * OpenClaw sessions accumulate ALL messages (tool calls, results, thinking blocks).
+   * Once a session hits ~400KB the Anthropic API starts returning internal server errors
+   * and the agent deadlocks — it can't respond or terminate.
+   *
+   * Strategy: keep the most recent messages from the session JSONL so the agent
+   * retains recent context (roughly the last N turns), rather than wiping it entirely.
+   * This minimises context loss while preventing unbounded growth.
+   */
+  _guardOpenClawSession(agentId) {
+    const MAX_SESSION_BYTES = 400_000;   // ~400KB — trim above this
+    const KEEP_BYTES = 150_000;          // keep last ~150KB of messages
+    const sessionsDir = path.join(homedir(), '.openclaw', 'agents', agentId, 'sessions');
+    if (!existsSync(sessionsDir)) return;
+
+    let trimmed = false;
+    for (const file of readdirSync(sessionsDir)) {
+      if (!file.endsWith('.jsonl')) continue;
+      const filePath = path.join(sessionsDir, file);
+      let size;
+      try { size = statSync(filePath).size; } catch { continue; }
+      if (size <= MAX_SESSION_BYTES) continue;
+
+      // Trim: keep the session header line(s) + the tail of the file
+      try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const lines = raw.split('\n').filter(l => l.trim());
+        // Always keep the first line (session metadata)
+        const header = lines[0] || '';
+        // Rebuild from the tail until we have roughly KEEP_BYTES
+        const tail = [];
+        let kept = 0;
+        for (let i = lines.length - 1; i >= 1; i--) {
+          kept += Buffer.byteLength(lines[i], 'utf-8') + 1;
+          if (kept > KEEP_BYTES) break;
+          tail.unshift(lines[i]);
+        }
+        const trimmedContent = [header, ...tail].join('\n') + '\n';
+        writeFileSync(filePath, trimmedContent, 'utf-8');
+        console.log(`✂️  [${agentId}] Trimmed session ${file} from ${Math.round(size/1024)}KB → ${Math.round(Buffer.byteLength(trimmedContent,'utf-8')/1024)}KB (kept last ${tail.length} msgs)`);
+        trimmed = true;
+      } catch (e) {
+        // If trimming fails, delete entirely — a fresh session is better than a deadlock
+        try { unlinkSync(filePath); console.log(`🗑️  [${agentId}] Deleted oversized session ${file} (${Math.round(size/1024)}KB) — trim failed`); } catch {}
+      }
+    }
+    return trimmed;
+  }
+
+  installPreviewServer() {
+    try {
+      const src = path.join(__dirname, 'preview-server.js');
+      const destDir = path.join(homedir(), '.agentforge');
+      const dest = path.join(destDir, 'preview-server.js');
+      if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+      copyFileSync(src, dest);
+      console.log('🔍 Preview server installed at ~/.agentforge/preview-server.js');
+    } catch (e) {
+      console.warn('⚠️  Could not install preview server:', e.message);
+    }
+  }
+
+  async connect() {
+    // Start periodic queue health check (every 10 seconds)
+    if (!this.queueHealthInterval) {
+      this.queueHealthInterval = setInterval(() => {
+        // Log current state
+        const processing = [];
+        const queued = [];
+        for (const [agentId, isProcessing] of this.agentProcessing.entries()) {
+          if (isProcessing) {
+            const elapsed = Date.now() - (this.processingStartTime.get(agentId) || Date.now());
+            processing.push(`${agentId.slice(-8)}(${Math.round(elapsed/1000)}s)`);
+          }
+        }
+        for (const [agentId, queue] of this.agentQueues.entries()) {
+          if (queue.length > 0) {
+            queued.push(`${agentId.slice(-8)}:${queue.length}`);
+          }
+        }
+        if (processing.length > 0 || queued.length > 0) {
+          console.log(`📊 State: processing=[${processing.join(',')}] queued=[${queued.join(',')}]`);
+        }
+        
+        this.resetStaleProcessingStates();
+        this.processAllQueues();
+      }, 10000);
+    }
+    
+    return new Promise((resolve, reject) => {
+      console.log(`🔄 Connecting to ${this.railwayUrl}...`);
+
+      this.ws = new WebSocket(this.railwayUrl, {
+        headers: {
+          'Authorization': `Bearer ${this.token}`,
+          'X-Worker-Type': 'agentforge'
+        }
+      });
+
+      this.ws.on('open', () => {
+        console.log('✅ Connected to AgentForge');
+        const wasReconnect = this.reconnectAttempts > 0;
+        this.reconnectAttempts = 0;
+
+        // Collect any tasks still running on this machine so the server doesn't
+        // falsely declare them idle when it processes the reconnect.
+        const liveTaskIds = [];
+        for (const [taskId, taskInfo] of this.runningTasks.entries()) {
+          if (!taskInfo.cancelled) liveTaskIds.push(taskId);
+        }
+
+        // Register worker
+        this.send({
+          type: 'worker_register',
+          capabilities: {
+            maxAgents: 100, // API limits support 100+, real limit is local resources
+            openclawConfigured: true, // Uses OpenClaw with Claude Max (browser OAuth, no API key needed)
+            platform: process.platform,
+            arch: process.arch,
+            deviceName: homedir().split('/').pop() + '@' + hostname(),
+            hostname: hostname(),
+            anthropicApiKey: process.env.ANTHROPIC_API_KEY || this.cli?.anthropicApiKey || null
+          },
+          // Tasks still running locally — server should keep them active, not broadcast idle
+          liveTaskIds
+        });
+
+        // On reconnect, reset stale processing states and flush pending messages
+        if (wasReconnect) {
+          this.resetStaleProcessingStates();
+          setTimeout(() => {
+            this.flushPendingMessages();
+            this.processAllQueues(); // Kick-start any stalled queues
+          }, 500);
+        }
+
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const message = JSON.parse(data.toString());
+          this.handleMessage(message);
+        } catch (error) {
+          console.error('❌ Failed to parse message:', error);
+        }
+      });
+
+      this.ws.on('close', () => {
+        console.log('❌ Disconnected from AgentForge');
+        this.handleDisconnect();
+      });
+
+      this.ws.on('error', (error) => {
+        console.error('❌ WebSocket error:', error.message);
+        reject(error);
+      });
+    });
+  }
+
+  handleDisconnect() {
+    // Warn about running tasks that might have results queued
+    const runningCount = this.runningTasks.size;
+    const pendingCount = this.pendingMessages.length;
+    if (runningCount > 0 || pendingCount > 0) {
+      console.log(`⚠️  Disconnect with ${runningCount} running tasks, ${pendingCount} pending messages`);
+    }
+
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts++;
+      const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000);
+      console.log(`🔄 Reconnecting in ${delay / 1000}s (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);
+      setTimeout(() => this.connect(), delay);
+    } else {
+      console.error('❌ Max reconnection attempts reached. Please restart the worker.');
+      process.exit(1);
+    }
+  }
+
+  async handleMessage(message) {
+    // Don't log pings — they flood the terminal every 30s with no useful info
+    if (message.type !== 'ping') {
+      console.log(`📨 Received: ${message.type}`);
+    }
+
+    switch (message.type) {
+      case 'task_assign':
+        // Inject API key from server if provided — ensures even workers without local key config work
+        if (message.anthropicApiKey) {
+          if (!process.env.ANTHROPIC_API_KEY) {
+            process.env.ANTHROPIC_API_KEY = message.anthropicApiKey;
+            console.log('🔑 Using API key from server task_assign');
+          }
+          if (this.cli && typeof this.cli === 'object' && 'anthropicApiKey' in this.cli) {
+            if (this.cli.anthropicApiKey !== message.anthropicApiKey) {
+              this.cli.anthropicApiKey = message.anthropicApiKey;
+            }
+          }
+          // Also wire key to hampagent
+          if (!this.hampagent.anthropicApiKey) {
+            this.hampagent.anthropicApiKey = message.anthropicApiKey;
+          }
+        }
+        await this.executeTask(message);
+        break;
+
+      case 'task_cancel':
+        // Support cancellation by taskId or agentId
+        console.log(`📨 CANCEL REQUEST: taskId=${message.taskId} agentId=${message.agentId}`);
+        if (message.taskId) {
+          await this.cancelTask(message.taskId);
+        } else if (message.agentId) {
+          await this.cancelTaskByAgent(message.agentId);
+        } else {
+          console.log(`⚠️  task_cancel received without taskId or agentId!`);
+        }
+        break;
+
+      case 'ping':
+        this.send({ type: 'pong' });
+        // Check for stuck agents - if processing but no activity for 2+ pings
+        this.checkForStuckAgents();
+        break;
+
+      case 'worker_restart':
+        console.log('🔄 Received worker_restart command — pulling latest code then restarting...');
+        this.send({ type: 'worker_restarting' });
+        setTimeout(() => this._updateAndRestart(), 200);
+        break;
+
+      case 'read_agent_files':
+        await this.handleReadAgentFiles(message);
+        break;
+
+      case 'write_agent_file':
+        await this.handleWriteAgentFile(message);
+        break;
+
+      case 'shell_exec': {
+        const { execId, command } = message;
+        console.log(`🖥️  shell_exec [${execId}]: ${command}`);
+        try {
+          const { execSync } = await import('child_process');
+          const output = execSync(command, { encoding: 'utf-8', timeout: 30000 });
+          this.send({ type: 'shell_exec_result', execId, success: true, output });
+        } catch (e) {
+          this.send({ type: 'shell_exec_result', execId, success: false, output: e.message });
+        }
+        break;
+      }
+
+      default:
+        console.log(`⚠️  Unknown message type: ${message.type}`);
+    }
+  }
+
+  async executeTask(taskData) {
+    const { agentId, taskId } = taskData;
+    console.log(`📬 Task received: ${taskId} for agent ${agentId}`);
+
+    // Initialize queue for this agent if it doesn't exist
+    if (!this.agentQueues.has(agentId)) {
+      this.agentQueues.set(agentId, []);
+      this.agentProcessing.set(agentId, false);
+    }
+
+    // Add task to queue
+    const queue = this.agentQueues.get(agentId);
+    queue.push(taskData);
+
+    const queueLength = queue.length;
+    const isProcessing = this.agentProcessing.get(agentId);
+    
+    if (queueLength > 1 || isProcessing) {
+      console.log(`📥 Queued: ${taskId} (${queueLength} in queue, processing=${isProcessing})`);
+    }
+
+    // Start processing queue if not already processing
+    this.processQueue(agentId);
+  }
+
+  async processQueue(agentId) {
+    // If already processing, check if it's stale
+    if (this.agentProcessing.get(agentId)) {
+      const startTime = this.processingStartTime.get(agentId);
+      const elapsed = startTime ? Date.now() - startTime : Infinity;
+      const queueLen = this.agentQueues.get(agentId)?.length || 0;
+      
+      if (elapsed > this.PROCESSING_TIMEOUT_MS) {
+        console.log(`⚠️ Agent ${agentId} stuck for ${Math.round(elapsed/1000)}s, forcing reset`);
+        this.agentProcessing.set(agentId, false);
+        this.processingStartTime.delete(agentId);
+        // Kill the stuck process
+        this.cli.cancelAgent(agentId);
+      } else {
+        // Log that we're waiting (every 30s to avoid spam)
+        if (elapsed > 0 && elapsed % 30000 < 1000 && queueLen > 0) {
+          console.log(`⏳ Agent ${agentId} busy (${Math.round(elapsed/1000)}s), ${queueLen} task(s) waiting`);
+        }
+        return; // Still processing, task will trigger next when done
+      }
+    }
+
+    const queue = this.agentQueues.get(agentId);
+    if (!queue || queue.length === 0) {
+      return; // Queue empty, nothing to do
+    }
+
+    // Mark as processing with timestamp
+    this.agentProcessing.set(agentId, true);
+    this.processingStartTime.set(agentId, Date.now());
+    console.log(`🚀 Starting task for ${agentId} (${queue.length} in queue)`);
+
+    // Get next task from queue
+    const taskData = queue.shift();
+
+    // Guard against undefined task data (can happen during reconnection race)
+    if (!taskData) {
+      console.warn(`⚠️ Queue shift returned undefined for agent ${agentId}, clearing processing flag`);
+      this.agentProcessing.set(agentId, false);
+      return;
+    }
+
+    // Wrap execution with a hard timeout that ALWAYS resolves
+    // This ensures processQueue ALWAYS completes and clears state
+    // Should fire AFTER the task hard timeout but BEFORE the task truly hangs forever
+    const QUEUE_TIMEOUT_MS = 31 * 60 * 1000; // 31 minutes (slightly longer than 30 min task timeout)
+    
+    let executeTaskCompleted = false;
+    let queueTimeoutFired = false;
+    let queueTimeoutTimer = null;
+    
+    try {
+      await Promise.race([
+        this.executeTaskNow(taskData).then(result => {
+          executeTaskCompleted = true;
+          // CRITICAL: Clear the queue timeout since task completed successfully
+          if (queueTimeoutTimer) {
+            clearTimeout(queueTimeoutTimer);
+            queueTimeoutTimer = null;
+          }
+          console.log(`[${agentId}] executeTaskNow completed normally`);
+          return result;
+        }).catch(error => {
+          executeTaskCompleted = true;
+          // CRITICAL: Clear the queue timeout since task completed (with error)
+          if (queueTimeoutTimer) {
+            clearTimeout(queueTimeoutTimer);
+            queueTimeoutTimer = null;
+          }
+          console.log(`[${agentId}] executeTaskNow rejected with error: ${error.message}`);
+          throw error;
+        }),
+        new Promise((resolve) => {
+          queueTimeoutTimer = setTimeout(() => {
+            // Don't fire if task already completed
+            if (executeTaskCompleted) {
+              console.log(`⏰ Queue timeout fired but task already completed, ignoring`);
+              return;
+            }
+            
+            queueTimeoutFired = true;
+            console.log(`⏰ QUEUE TIMEOUT: Task ${taskData.taskId} exceeded ${QUEUE_TIMEOUT_MS/1000}s`);
+            console.log(`⏰ executeTaskCompleted: ${executeTaskCompleted}`);
+            console.log(`⏰ This indicates executeTaskNow Promise never settled - likely OpenClawCLI.runAgentTask hung`);
+            
+            // Force kill the agent process
+            const killed = this.cli.cancelAgent(agentId);
+            console.log(`⏰ cancelAgent result: ${killed}`);
+            
+            // Send debug report for queue timeout (different from task timeout)
+            const diagnostics = this.collectDiagnostics(
+              agentId,
+              taskData.taskId,
+              new Error(`Queue timeout - Promise hung for ${QUEUE_TIMEOUT_MS/1000}s after task should have completed`),
+              'queue_timeout'
+            );
+            this.sendDebugReport(diagnostics, `QUEUE TIMEOUT: Task ${taskData.taskId} Promise never resolved. This usually means the OpenClaw process close event didn't fire. cancelAgent: ${killed}`);
+            
+            resolve({ timeout: true });
+          }, QUEUE_TIMEOUT_MS);
+        })
+      ]);
+    } catch (error) {
+      console.error(`❌ Task execution error for ${taskData.taskId}:`, error);
+    } finally {
+      // Clear timeout if still pending
+      if (queueTimeoutTimer) {
+        clearTimeout(queueTimeoutTimer);
+        queueTimeoutTimer = null;
+      }
+      // Log which path we took
+      if (queueTimeoutFired && !executeTaskCompleted) {
+        console.log(`[${agentId}] ⚠️ Queue timeout won the race - executeTaskNow never completed`);
+      }
+      // ALWAYS clear processing state - this is critical
+      console.log(`🧹 Clearing processing state for ${agentId}`);
+      this.agentProcessing.set(agentId, false);
+      this.processingStartTime.delete(agentId);
+
+      // Process next task if queue is not empty
+      if (queue.length > 0) {
+        if (queueTimeoutFired) {
+          // After a force-kill, wait 3s for the dead process to release openclaw's workspace
+          // locks before starting the next task — avoids "Agent failed: Unknown error" on restart
+          console.log(`📤 Waiting 3s for killed process cleanup before next task for ${agentId}...`);
+          setTimeout(() => this.processQueue(agentId), 3000);
+        } else {
+          console.log(`📤 Processing next queued task for ${agentId} (${queue.length} remaining)...`);
+          setImmediate(() => this.processQueue(agentId));
+        }
+      }
+    }
+  }
+
+  async executeTaskNow({ taskId, agentId, sessionId, message: userMessage, workDir, defaultProjectsPath, image, roomId, roomContext, isMaestro, conversationHistory, browserProfile, agentName, agentEmoji, runnerType }) {
+    const isMaestroTask = isMaestro || agentId === 'maestro';
+    console.log(`🤖 Executing task ${taskId} for agent ${agentId}${isMaestroTask ? ' (MAESTRO)' : ''}${browserProfile ? ` [browser: ${browserProfile}]` : ''}`);
+    if (sessionId) {
+      console.log(`   Session: ${sessionId} (resuming conversation)`);
+    }
+    if (image) {
+      console.log(`   Image: Provided`);
+    }
+    if (roomId) {
+      console.log(`   Room: ${roomId}`);
+    }
+
+    // Track this running task for cancellation support
+    this.runningTasks.set(taskId, { agentId, cancelled: false, isMaestro: isMaestroTask });
+    
+    // Hard timeout for entire task - 30 minutes max (large projects with Opus can be slow)
+    const TASK_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes hard timeout
+    console.log(`⏱️ Task ${taskId} timeout set for ${TASK_TIMEOUT_MS/1000}s`);
+    const taskTimeoutTimer = setTimeout(() => {
+      console.log(`⏰ TIMEOUT FIRED for ${taskId}`);
+      const taskInfo = this.runningTasks.get(taskId);
+      console.log(`⏰ taskInfo: ${JSON.stringify(taskInfo)}`);
+      if (taskInfo && !taskInfo.cancelled) {
+        console.log(`⏰ Task ${taskId} hit hard timeout (${TASK_TIMEOUT_MS/1000}s), force killing`);
+        const killed = this.cli.cancelAgent(agentId);
+        console.log(`⏰ cancelAgent returned: ${killed}`);
+        
+        // Collect diagnostics for debug agent BEFORE cleanup
+        const diagnostics = this.collectDiagnostics(
+          agentId,
+          taskId,
+          new Error(`Task exceeded ${TASK_TIMEOUT_MS/1000}s hard timeout`),
+          'timeout'
+        );
+        
+        // CRITICAL: Reset processing state so queue can continue
+        // even if executeTaskNow is still hanging
+        this.agentProcessing.set(agentId, false);
+        this.processingStartTime.delete(agentId);
+        this.runningTasks.delete(taskId);
+        console.log(`⏰ Reset processing state for ${agentId}`);
+        taskInfo.cancelled = true;
+        this.send({
+          type: 'task_failed',
+          taskId,
+          agentId,
+          roomId,
+          error: `Task timed out after ${TASK_TIMEOUT_MS/1000} seconds`
+        });
+        
+        // Send debug report so debug-agent-system can investigate
+        this.sendDebugReport(diagnostics, `Task ${taskId} for agent ${agentId} hit hard timeout (${TASK_TIMEOUT_MS/1000}s). cancelAgent returned: ${killed}`);
+      }
+    }, TASK_TIMEOUT_MS);
+
+    // Closure set once wrapped handlers are created; callable from both try and catch paths
+    let _cleanup = null;
+
+    try {
+      // Agent workspace: always the dedicated /tmp folder for this agent
+      // This is where MEMORY.md, AGENTS.md, .canary, identity files live - never pollute user's projects folder
+      const agentWorkspaceDir = workDir || process.cwd();
+
+      // Task cwd: where the agent actually runs commands and reads/writes files
+      // If user configured a defaultProjectsPath in settings AND it exists locally, use that
+      // so the agent can see all the user's projects without needing to be told where they are
+      let taskCwd = agentWorkspaceDir;
+      if (defaultProjectsPath && defaultProjectsPath.trim()) {
+        const { existsSync } = await import('fs');
+        if (existsSync(defaultProjectsPath)) {
+          taskCwd = defaultProjectsPath;
+          console.log(`📁 Using configured projects path as task cwd: ${taskCwd}`);
+        } else {
+          console.log(`⚠️ Configured projects path not found locally (${defaultProjectsPath}), using default cwd: ${taskCwd}`);
+        }
+      }
+      // Keep actualWorkDir pointing to the agent's workspace for backward compat
+      const actualWorkDir = agentWorkspaceDir;
+
+      // Select runner — hampagent or openclaw
+      const useHampagent = runnerType === 'hampagent';
+      const activeRunner = useHampagent ? this.hampagent : this.cli;
+
+      if (useHampagent) {
+        // Pass identity so system prompt knows the agent's name/emoji
+        this.hampagent._agentName = agentName || null;
+        this.hampagent._agentEmoji = agentEmoji || null;
+        console.log(`🦅 Using Hampagent runner for ${agentId}`);
+      } else {
+        // Guard against bloated OpenClaw sessions — trim tail, preserve recent context
+        this._guardOpenClawSession(agentId);
+      }
+
+      // Create agent if not exists (always in its dedicated workspace, not the projects folder)
+      if (!this.activeAgents.has(agentId)) {
+        console.log(`📦 Creating agent ${agentId} workspace in ${actualWorkDir}`);
+        await activeRunner.createAgent(agentId, actualWorkDir);
+        this.activeAgents.set(agentId, { workDir: actualWorkDir, taskCwd });
+      }
+
+      // Set up output streaming
+      const outputHandler = (data) => {
+        if (data.agentId === agentId) {
+          // Check if task was cancelled - don't send any more output
+          const taskInfo = this.runningTasks.get(taskId);
+          if (!taskInfo || taskInfo.cancelled) {
+            return; // Task cancelled, drop all output
+          }
+          
+          // Record activity to prevent stuck detection from firing
+          this.recordAgentActivity(agentId);
+          
+          // Filter out tool error stack traces from room chat
+          const text = data.output?.trim();
+          if (text && roomId) {
+            // Don't broadcast internal tool errors to room chat
+            const isToolError = text.includes('tools:') && text.includes('failed stack:') ||
+                               text.includes('Error:') && text.includes('at file:///') ||
+                               text.includes('at async') && text.includes('.js:');
+            if (isToolError) {
+              console.log(`   [Filtered tool error from room broadcast]`);
+              return;
+            }
+          }
+
+          // Send maestro-specific output for maestro tasks
+          if (isMaestroTask) {
+            // Detect when maestro spawns agents
+            const spawnMatch = text.match(/sessions_spawn\s+--id\s+([^\s]+)\s+--message\s+"([^"]+)"/);
+            if (spawnMatch) {
+              const spawnedAgentId = spawnMatch[1];
+              const spawnedTask = spawnMatch[2];
+              console.log(`🎼 Maestro spawned agent: ${spawnedAgentId}`);
+
+              // Emit agent spawned event
+              this.send({
+                type: 'maestro_agent_spawned',
+                taskId,
+                agentId: spawnedAgentId,
+                task: spawnedTask
+              });
+            }
+
+            this.send({
+              type: 'maestro_output',
+              taskId,
+              agentId,
+              output: data.output
+            });
+          } else {
+            this.send({
+              type: 'task_progress',
+              taskId,
+              agentId,
+              roomId,
+              output: data.output,
+              isChunk: true
+            });
+          }
+        }
+      };
+
+      // Handle agent_image events — screenshot the agent wants to send to the user's chat
+      const imageHandler = (data) => {
+        if (data.agentId === agentId) {
+          const taskInfo = this.runningTasks.get(taskId);
+          if (!taskInfo || taskInfo.cancelled) return;
+          this.send({
+            type: 'task_progress',
+            taskId,
+            agentId,
+            roomId,
+            output: '',
+            image: data.image
+          });
+        }
+      };
+      activeRunner.on('agent_image', imageHandler);
+
+      // Set up error streaming (stderr)
+      const errorHandler = (data) => {
+        if (data.agentId === agentId) {
+          // Check if task was cancelled - don't send any more errors
+          const taskInfo = this.runningTasks.get(taskId);
+          if (!taskInfo || taskInfo.cancelled) {
+            return; // Task cancelled, drop all output
+          }
+          
+          // Filter out common non-critical stderr noise
+          const text = data.error?.trim();
+          if (!text) return;
+          
+          const isNoise = text.includes('[Canary]') ||
+                          text.includes('Plugin registered') ||
+                          text.includes('browser/service') ||
+                          text.includes('Debugger listening') ||
+                          text.includes('EADDRINUSE') ||
+                          text.includes('[openclaw]') ||
+                          text.includes('Unhandled promise rejection') ||
+                          text.includes('shared_storage_worklet') ||
+                          text.includes('playwright-core') ||
+                          text.includes('targetInfo') ||
+                          text.includes('[diagnostic]') ||
+                          text.includes('[stderr]') ||
+                          text.includes('crBrowser') ||
+                          text.includes('crConnection');
+          
+          if (!isNoise) {
+            this.send({
+              type: 'task_error',
+              taskId,
+              agentId,
+              roomId,
+              error: text
+            });
+          }
+        }
+      };
+
+      // Set up tool activity streaming (shows what tool agent is using)
+      const toolActivityHandler = (data) => {
+        if (data.agentId === agentId) {
+          // Record activity to prevent stuck detection from firing
+          this.recordAgentActivity(agentId);
+
+          // tts tool is handled natively by openclaw — do not intercept or emit anything
+          
+          let toolInputPreview;
+          if (data.toolInput) {
+            try {
+              toolInputPreview = JSON.stringify(data.toolInput).slice(0, 2000);
+            } catch {
+              toolInputPreview = undefined;
+            }
+          }
+
+          this.send({
+            type: 'tool_activity',
+            taskId,
+            agentId,
+            roomId,
+            event: data.event,
+            tool: data.tool,
+            description: data.description,
+            input: toolInputPreview
+          });
+        }
+      };
+
+      activeRunner.on('agent_output', outputHandler);
+      activeRunner.on('agent_error', errorHandler);
+      activeRunner.on('tool_activity', toolActivityHandler);
+
+      // Listen for raw alive signals (any stdout, even filtered) to prevent false stuck detection
+      const aliveHandler = (data) => {
+        if (data.agentId === agentId) {
+          this.recordAgentActivity(agentId);
+        }
+      };
+      activeRunner.on('agent_alive', aliveHandler);
+
+      // Inactivity: warn at 60s, KILL at 10 minutes of silence (no stdout at all)
+      const INACTIVITY_WARN_MS = 60000;
+      const INACTIVITY_KILL_MS = 2 * 60 * 1000; // 2 minutes — kill truly hung openclaw
+      let lastActivityTime = Date.now();
+      let inactivityTimer = null;
+      let inactivityKillTimer = null;
+      let currentTool = null; // Track which tool is currently running
+      let promiseSettled = false; // Prevent kill timer from firing after task completes
+
+      // Tools that are expected to take a while - don't warn about these
+      const QUIET_TOOLS = ['Editing file', 'Writing file', 'Reading file', 'edit', 'write', 'read'];
+
+      const clearInactivityTimers = () => {
+        if (inactivityTimer) { clearTimeout(inactivityTimer); inactivityTimer = null; }
+        if (inactivityKillTimer) { clearTimeout(inactivityKillTimer); inactivityKillTimer = null; }
+      };
+
+      const resetInactivityTimer = () => {
+        lastActivityTime = Date.now();
+        // Also reset the ping-based stuck detector so 300s kill doesn't fire during active work
+        this.lastAgentActivity.set(agentId, Date.now());
+        this.pingsSinceActivity.set(agentId, 0);
+        clearInactivityTimers();
+
+        // Warn at 30s
+        inactivityTimer = setTimeout(() => {
+          const taskInfo = this.runningTasks.get(taskId);
+          if (taskInfo && !taskInfo.cancelled) {
+            if (currentTool && QUIET_TOOLS.some(t => currentTool.toLowerCase().includes(t.toLowerCase()))) {
+              resetInactivityTimer(); // quiet tool — just reset and check again later
+              return;
+            }
+            const stuckTool = currentTool ? ` while running "${currentTool}"` : '';
+            this.send({
+              type: 'task_warning',
+              taskId,
+              agentId,
+              roomId,
+              warning: `No activity for ${INACTIVITY_WARN_MS/1000} seconds${stuckTool} - agent may be stuck`,
+              lastTool: currentTool
+            });
+          }
+        }, INACTIVITY_WARN_MS);
+
+        // Kill at 10 minutes — openclaw is definitely hung
+        inactivityKillTimer = setTimeout(() => {
+          if (promiseSettled) return;
+          const taskInfo = this.runningTasks.get(taskId);
+          if (taskInfo && !taskInfo.cancelled) {
+            console.warn(`[${agentId}] ⚠️ No output for ${INACTIVITY_KILL_MS/1000}s — openclaw hung mid-task, killing`);
+            promiseSettled = true;
+            // cancelAgent kills the process tree; OpenClawCLI's close handler will reject runAgentTask
+            activeRunner.cancelAgent(agentId);
+          }
+        }, INACTIVITY_KILL_MS);
+      };
+      
+      // Track tool lifecycle
+      const toolLifecycleHandler = (data) => {
+        if (data.agentId === agentId && data.event) {
+          if (data.event === 'start') {
+            currentTool = data.description || data.tool;
+          } else if (data.event === 'complete') {
+            currentTool = null;
+          }
+        }
+      };
+      activeRunner.on('tool_activity', toolLifecycleHandler);
+      
+      // Reset timer on any activity
+      const activityWrapper = (handler) => (data) => {
+        resetInactivityTimer();
+        handler(data);
+      };
+      
+      // Wrap handlers to track activity
+      const wrappedOutputHandler = activityWrapper(outputHandler);
+      const wrappedToolHandler = activityWrapper(toolActivityHandler);
+      const wrappedAliveHandler = activityWrapper(aliveHandler);
+      
+      activeRunner.off('agent_output', outputHandler);
+      activeRunner.off('tool_activity', toolActivityHandler);
+      activeRunner.off('agent_alive', aliveHandler);
+      activeRunner.on('agent_output', wrappedOutputHandler);
+      activeRunner.on('tool_activity', wrappedToolHandler);
+      activeRunner.on('agent_alive', wrappedAliveHandler);
+
+      // Capture cleanup as a callable closure so both try and catch paths can use it
+      _cleanup = () => {
+        promiseSettled = true; // Prevent inactivity kill timer from firing after task ends
+        clearInactivityTimers();
+        activeRunner.off('agent_output', wrappedOutputHandler);
+        activeRunner.off('agent_error', errorHandler);
+        activeRunner.off('tool_activity', wrappedToolHandler);
+        activeRunner.off('tool_activity', toolLifecycleHandler);
+        activeRunner.off('agent_alive', wrappedAliveHandler);
+        activeRunner.off('agent_image', imageHandler);
+      };
+
+      resetInactivityTimer(); // Start the timer
+
+      // Build message with room context if in a room
+      let finalMessage = userMessage;
+      if (roomContext) {
+        // Prepend room context to message
+        const contextInfo = [
+          `You are in a multi-agent room: ${roomContext.roomName}`,
+          `Participants: ${roomContext.participants.map(p => `${p.emoji} ${p.name}${p.isYou ? ' (you)' : ''}`).join(', ')}`,
+          roomContext.instructions,
+          '',
+          `User message: ${userMessage}`
+        ].join('\n');
+        finalMessage = contextInfo;
+      }
+
+      // Inject platform context into EVERY message so the agent always knows:
+      // 1. What platform it's running on and its URL
+      // 2. Where the user's projects folder is
+      // 3. Screenshot capabilities
+      const platformContext = [
+        `[System context:`,
+        `- Platform: AgentForge.ai. Dashboard: https://agentforgeai-production.up.railway.app/dashboard. CRITICAL: Always use the built-in 'browser' tool for ALL web browsing AND web searches — NEVER use the 'web_search' tool (no API keys are configured), NEVER run shell commands like 'open', 'google-chrome', 'chromium', or any OS command to launch a browser. The browser tool connects to AgentForge Browser (port 9223) automatically. To search: use browser to navigate to google.com or perplexity.ai.`,
+        `- Your runner: ${useHampagent ? 'Hampagent' : 'OpenClaw'}.`,
+        (!conversationHistory || conversationHistory.length === 0)
+          ? `- This is the first message. When greeting, say: "I'm [your name] — your ${useHampagent ? 'Hampagent' : 'OpenClaw'} agent running on AgentForge." Never say "autonomous AI agent". Never list capabilities in an intro.`
+          : `- This is a continuing conversation. Do NOT re-introduce yourself.`,
+        agentName
+          ? `- Your name is "${agentName}"${agentEmoji ? ` ${agentEmoji}` : ''}. This is your AgentForge identity. Do not ask the user who you are or what your name is — you already know.`
+          : null,
+        taskCwd && taskCwd !== agentWorkspaceDir
+          ? `- Working directory: "${taskCwd}" — user's projects folder. Check here first for any project by name.`
+          : null,
+        agentWorkspaceDir
+          ? `- Screenshots: screencapture -x ${agentWorkspaceDir}/ss1.png && sips -Z 1280 ${agentWorkspaceDir}/ss1.png (MUST resize — API rejects images over 5MB). Send to chat with: echo "AGENTFORGE_IMAGE:${agentWorkspaceDir}/ss1.png". Always screenshot visual work before saying done. NEVER use "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless for screenshots — use screencapture only.`
+          : `- Screenshots: screencapture -x /tmp/ss1.png && sips -Z 1280 /tmp/ss1.png (MUST resize — API rejects images over 5MB). Send to chat with: echo "AGENTFORGE_IMAGE:/tmp/ss1.png". Always screenshot visual work before saying done. NEVER use "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless for screenshots — use screencapture only.`,
+        `]`
+      ].filter(Boolean).join('\n');
+      finalMessage = platformContext + '\n\n' + finalMessage;
+
+      // If conversation history was loaded from DB (e.g. session expired, worker restarted,
+      // or user returning hours later), prepend it so the agent has full context.
+      // Only do this for non-room tasks and when we actually have history.
+      if (!roomContext && conversationHistory && conversationHistory.length > 0) {
+        // When the gateway is configured, openclaw maintains session state natively via the
+        // x-openclaw-session-key header — no need to inject history manually.
+        // Only inject history when gateway is unavailable (subprocess fallback).
+        // Hampagent manages its own session history natively — never inject DB history for it
+        const gatewayActive = !!(this.cli.gatewayPort && this.cli.gatewayToken);
+        const sessionExists = useHampagent || gatewayActive;
+
+        if (!sessionExists) {
+          // Session is gone — inject DB history as context prefix so the agent remembers
+          console.log(`📚 Session workspace not found for ${agentId}, injecting ${conversationHistory.length} messages from DB history`);
+          // Strip tool errors and stack traces from stored assistant messages before injecting
+          const stripHistoryNoise = (text) => {
+            if (!text) return text;
+            return text.split('\n').filter(line => {
+              const t = line.trim();
+              return !(
+                t.startsWith('tools:') ||
+                t.includes('failed stack:') ||
+                /^\s*at\s+\S/.test(line) ||
+                t.startsWith('at file:///') || t.startsWith('at async ') || t.startsWith('at Object.')
+              );
+            }).join('\n').trim();
+          };
+          const stripSystemContext = (text) => {
+            if (!text) return text;
+            // Remove stale [System context: ...] blocks injected by older worker builds
+            // (e.g. old Chrome screenshot instructions). Current context is always re-injected fresh.
+            return text.replace(/\[System context:[\s\S]*?\n\]/g, '').trim();
+          };
+          const historyText = conversationHistory
+            .slice(-5) // last 5 messages — keep context small to prevent API hangs
+            .map(msg => {
+              const role = msg.role === 'user' ? 'User' : 'Assistant';
+              const content = msg.role === 'user'
+                ? stripSystemContext(msg.content)
+                : stripHistoryNoise(msg.content);
+              return `${role}: ${content}`;
+            })
+            .join('\n\n');
+          // Prepend history to finalMessage (which already contains platform context + userMessage)
+          finalMessage = `[Conversation history — you are resuming a prior session]\n\n${historyText}\n\n[End of history]\n\n${finalMessage}`;
+        } else {
+          console.log(`📚 Session workspace found for ${agentId}, openclaw will use its own session memory`);
+        }
+      }
+
+      // ── Skills: load matching skill files from agent workspace ──────────────
+      // Skills are .md files in {workspace}/skills/ with YAML frontmatter.
+      // Matching ones are prepended so the agent has relevant context upfront.
+      if (!isMaestroTask && !roomContext) {
+        const skillContext = this.loadMatchingSkills(actualWorkDir, userMessage);
+        if (skillContext) {
+          console.log(`[${taskId}] 📚 Injecting matching skill(s)`);
+          finalMessage = `[Relevant skill from your skills library]\n${skillContext}\n\n---\n\n${finalMessage}`;
+        }
+
+        // No verification protocol — it adds tokens and causes openclaw to hang on large contexts
+      }
+
+      // ── Iteration loop: run up to 3 times, refining based on agent feedback ─
+      const MAX_ITERATIONS = isMaestroTask || roomContext ? 1 : 3;
+      let iteration = 0;
+      let taskResult;
+      let iterationMessage = finalMessage;
+
+      while (iteration < MAX_ITERATIONS) {
+        iteration++;
+
+        if (iteration > 1) {
+          console.log(`[${taskId}] 🔄 Iteration ${iteration}/${MAX_ITERATIONS}`);
+          this.send({
+            type: 'task_iteration',
+            taskId,
+            agentId,
+            roomId,
+            iteration,
+            maxIterations: MAX_ITERATIONS
+          });
+        }
+
+        console.log(`[${taskId}] 🏃 Runner: ${useHampagent ? '⚡ HAMPAGENT' : '🔧 OPENCLAW'} — agent ${agentId} iteration ${iteration}`);
+        const runAgentStart = Date.now();
+        taskResult = await activeRunner.runAgentTask(
+          agentId, iterationMessage, taskCwd, sessionId, iteration === 1 ? image : null, browserProfile, actualWorkDir
+        );
+        const runAgentDuration = Date.now() - runAgentStart;
+        console.log(`[${taskId}] runAgentTask iteration ${iteration} returned after ${runAgentDuration}ms, success=${taskResult?.success}`);
+
+        const output = taskResult?.result?.output || '';
+
+        if (output.includes('✓ TASK_COMPLETE')) {
+          if (iteration > 1) {
+            // Save a skill stub so future similar tasks start better
+            this.saveIteratedSkill(agentId, actualWorkDir, userMessage, iteration).catch(() => {});
+            this.send({
+              type: 'task_skill_saved',
+              taskId,
+              agentId,
+              roomId,
+              iterations: iteration
+            });
+          }
+          break;
+        }
+
+        // Check for iterate signal — if present and iterations remain, continue
+        const iterateMatch = output.match(/↻ ITERATE:\s*(.+?)(?:\n|$)/);
+        if (iterateMatch && iteration < MAX_ITERATIONS) {
+          const feedback = iterateMatch[1].trim();
+          console.log(`[${taskId}] Agent self-correcting: ${feedback}`);
+          iterationMessage = `Your previous attempt had this issue: "${feedback}"\n\nPlease revise your work to fix it. When done, end with ✓ TASK_COMPLETE or ↻ ITERATE: [remaining issue].`;
+        } else {
+          break; // No iterate signal or max iterations reached
+        }
+      }
+
+      // Clean up listeners and timer
+      if (_cleanup) { _cleanup(); _cleanup = null; }
+
+      // Check if task was cancelled or already handled by timeout
+      const taskInfo = this.runningTasks.get(taskId);
+      if (!taskInfo || taskInfo.cancelled) {
+        console.log(`⚠️  Task ${taskId} was already handled (cancelled/timeout), skipping`);
+        return;
+      }
+
+      // Use AgentForge-assigned identity when provided (from task_assign).
+      // Fall back to querying OpenClaw only when no name was supplied.
+      let identity = { identityName: agentId, identityEmoji: '🤖' };
+      if (agentName) {
+        identity = { identityName: agentName, identityEmoji: agentEmoji || '🤖' };
+        console.log(`[${taskId}] Using AgentForge identity: ${identity.identityName}`);
+      } else {
+        console.log(`[${taskId}] Getting agent identity from OpenClaw...`);
+        const identityStart = Date.now();
+        try {
+          const identityPromise = this.cli.getAgentIdentity(agentId);
+          const timeoutPromise = new Promise(r => setTimeout(() => r(null), 5000)); // 5s max
+          const result = await Promise.race([identityPromise, timeoutPromise]);
+          if (result) {
+            identity = result;
+          } else {
+            console.log(`[${taskId}] ⚠️ getAgentIdentity timed out after ${Date.now() - identityStart}ms`);
+          }
+        } catch (e) {
+          console.log(`[${taskId}] ⚠️ getAgentIdentity failed after ${Date.now() - identityStart}ms: ${e.message}`);
+        }
+        console.log(`[${taskId}] Got identity in ${Date.now() - identityStart}ms: ${identity.identityName}`);
+      }
+
+      // Send completion with identity info, final response text, and sessionId for maestro
+      // Filter openclaw's "No reply from agent." placeholder — it appears when the agent only
+      // used tools with no text response (e.g. TTS-only tasks). If we send it, the browser's
+      // filterAgentMarkers will strip it, leaving a blank bubble. Instead, leave response
+      // undefined so the server falls back to the accumulated task_progress text (e.g. "🔊 Spoke aloud: ...").
+      const rawOutput = taskResult?.result?.output || '';
+      console.log(`[${taskId}] 🔍 taskResult.result.output (${rawOutput.length} chars): "${rawOutput.slice(0, 200)}"`);
+      let finalOutput = rawOutput.trim();
+      if (/^no reply from agent\.?$/i.test(finalOutput)) {
+        console.log(`[${taskId}] 🔕 Filtered "No reply from agent." from finalOutput`);
+        finalOutput = '';
+      }
+      // If the output is just an error stack trace / tool failure message, clear it
+      // so the server falls back to accumulated task_progress text instead
+      if (finalOutput &&
+          (finalOutput.startsWith('tools:') || finalOutput.startsWith('Error:') ||
+           finalOutput.includes('failed stack:') || finalOutput.includes('at file:///') ||
+           /^\s*at\s+/.test(finalOutput))) {
+        console.log(`[${taskId}] 🔕 Filtered error-only output from finalOutput: "${finalOutput.slice(0,100)}"`);
+        finalOutput = '';
+      }
+      // If the task succeeded but produced no text, emit a minimal completion token
+      // so the browser never shows "No response received" for a successful task.
+      if (!finalOutput && taskResult?.success) {
+        finalOutput = '✓ Done.';
+        console.log(`[${taskId}] ℹ️ Task succeeded with no text output — using default completion message`);
+      }
+      console.log(`[${taskId}] 📤 finalOutput="${finalOutput.slice(0,100)}" response=${finalOutput ? `"${finalOutput.slice(0,80)}"` : 'undefined'}`);
+      const completionMessage = {
+        type: 'task_complete',
+        taskId,
+        agentId,
+        roomId,
+        identity,
+        response: finalOutput || undefined
+      };
+
+      // Include sessionId for maestro to maintain conversation
+      if (isMaestroTask && sessionId) {
+        completionMessage.sessionId = sessionId;
+      }
+
+      console.log(`[${taskId}] Sending completion message...`);
+      this.send(completionMessage);
+
+      console.log(`✅ Task ${taskId} completed (${identity.identityName})`);
+      
+      // Clear hard timeout and clean up
+      console.log(`[${taskId}] Clearing timeout and task tracking...`);
+      clearTimeout(taskTimeoutTimer);
+      this.runningTasks.delete(taskId);
+      console.log(`[${taskId}] executeTaskNow DONE - returning normally`);
+    } catch (error) {
+      // Always clean up listeners — this path was previously missing cleanup,
+      // causing stacked listeners across multiple task runs
+      if (_cleanup) { _cleanup(); _cleanup = null; }
+
+      // Clear hard timeout
+      clearTimeout(taskTimeoutTimer);
+      
+      // Check if this was a cancellation or timeout
+      // If taskInfo is missing, timeout already handled it
+      const taskInfo = this.runningTasks.get(taskId);
+      if (!taskInfo || taskInfo.cancelled) {
+        console.log(`⚠️  Task ${taskId} was already cancelled/timed out, ignoring error`);
+        return;
+      }
+      
+      console.error(`❌ Task ${taskId} failed:`, error);
+
+      // Collect detailed diagnostics
+      const diagnostics = this.collectDiagnostics(agentId, taskId, error, 'error');
+
+      // Kill the agent process — try both runners (only one will be active)
+      this.cli.cancelAgent(agentId);
+      this.hampagent?.cancelAgent(agentId);
+
+      this.send({
+        type: 'task_failed',
+        taskId,
+        agentId,
+        roomId,
+        error: error.message,
+        stack: error.stack
+      });
+
+      // Send debug report for investigation
+      this.sendDebugReport(diagnostics, `Agent ${agentId} failed during task ${taskId}: ${error.message}`);
+
+      // Clean up task tracking
+      this.runningTasks.delete(taskId);
+    }
+  }
+
+  async cancelTask(taskId) {
+    console.log(`🛑 CANCEL RECEIVED for task ${taskId}`);
+    
+    const taskInfo = this.runningTasks.get(taskId);
+    if (!taskInfo) {
+      console.log(`⚠️  Task ${taskId} not found in runningTasks (size: ${this.runningTasks.size})`);
+      console.log(`   runningTasks keys: ${[...this.runningTasks.keys()].join(', ')}`);
+      // Still send cancelled message to browser to clear UI state
+      this.send({
+        type: 'task_cancelled',
+        taskId
+      });
+      return;
+    }
+
+    const { agentId } = taskInfo;
+    console.log(`🛑 Found task for agent ${agentId}, cancelling...`);
+    
+    // Mark as cancelled so completion handler knows
+    taskInfo.cancelled = true;
+    
+    // Kill the running process — try both runners (only one will be active)
+    console.log(`🛑 Calling cancelAgent for ${agentId}...`);
+    const killed = this.cli.cancelAgent(agentId) || this.hampagent?.cancelAgent(agentId) || false;
+    console.log(`🛑 cancelAgent returned: ${killed}`);
+    
+    // Always clear state and notify browser, regardless of kill success
+    this.agentQueues.set(agentId, []);
+    this.agentProcessing.set(agentId, false);
+    this.processingStartTime.delete(agentId);
+    
+    // Notify the server that the task was cancelled
+    this.send({
+      type: 'task_cancelled',
+      taskId,
+      agentId
+    });
+    
+    console.log(`✅ Task ${taskId} cancelled, kill result: ${killed}`);
+    
+    // Clean up
+    this.runningTasks.delete(taskId);
+  }
+
+  async cancelTaskByAgent(agentId) {
+    console.log(`🛑 Cancelling task for agent ${agentId}`);
+    
+    // Find the running task for this agent
+    let taskId = null;
+    for (const [tid, info] of this.runningTasks.entries()) {
+      if (info.agentId === agentId) {
+        taskId = tid;
+        break;
+      }
+    }
+    
+    if (taskId) {
+      await this.cancelTask(taskId);
+    } else {
+      // Still try to kill the process even if we don't have a taskId — try both runners
+      const killed = this.cli.cancelAgent(agentId) || this.hampagent?.cancelAgent(agentId) || false;
+
+      // Always clear the queue and state for this agent
+      this.agentQueues.set(agentId, []);
+      this.agentProcessing.set(agentId, false);
+      this.processingStartTime.delete(agentId);
+
+      if (killed) {
+        console.log(`✅ Agent ${agentId} task cancelled successfully`);
+      } else {
+        console.log(`⚠️  No running task found for agent ${agentId}, clearing state anyway`);
+      }
+
+      // ALWAYS send task_cancelled to clear browser UI state, regardless of kill success
+      this.send({
+        type: 'task_cancelled',
+        agentId
+      });
+    }
+  }
+
+  // ── Skills System ─────────────────────────────────────────────────────────
+
+  /**
+   * Load skill files from agent workspace that match the current task.
+   * Skills are .md files in {agentWorkspaceDir}/skills/ with YAML frontmatter.
+   * Matching: description field must share 2+ words (>4 chars) with the task.
+   */
+  loadMatchingSkills(agentWorkspaceDir, task) {
+    try {
+      const skillsDir = path.join(agentWorkspaceDir, 'skills');
+      if (!existsSync(skillsDir)) return '';
+
+      const files = readdirSync(skillsDir).filter(f => f.endsWith('.md'));
+      if (files.length === 0) return '';
+
+      const taskWords = new Set(
+        task.toLowerCase().split(/\W+/).filter(w => w.length > 4)
+      );
+      const matched = [];
+
+      for (const file of files) {
+        try {
+          const content = readFileSync(path.join(skillsDir, file), 'utf-8');
+          const descMatch = content.match(/^---[\s\S]*?\ndescription:\s*["']?(.+?)["']?\s*\n[\s\S]*?---/m);
+          if (descMatch) {
+            const descWords = descMatch[1].toLowerCase().split(/\W+/).filter(w => w.length > 4);
+            const overlap = descWords.filter(w => taskWords.has(w)).length;
+            if (overlap >= 2) {
+              matched.push(content.replace(/^---[\s\S]*?---\n/, '').trim());
+            }
+          }
+        } catch { /* skip unreadable files */ }
+      }
+
+      return matched.join('\n\n---\n\n');
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Generate a short kebab-case name from a task description.
+   */
+  generateSkillName(task) {
+    const stopwords = new Set(['that', 'this', 'with', 'from', 'have', 'been', 'your', 'will', 'would', 'could', 'should', 'please', 'make', 'create', 'build', 'system', 'context']);
+    const words = task.toLowerCase()
+      .replace(/[^a-z0-9\s]/g, '')
+      .split(/\s+/)
+      .filter(w => w.length > 3 && !stopwords.has(w))
+      .slice(0, 3);
+    return words.length > 0 ? words.join('-') : 'task-skill';
+  }
+
+  /**
+   * After a task that required >1 iteration succeeds, write a skill stub
+   * to the agent workspace so future similar tasks start from a better position.
+   */
+  async saveIteratedSkill(agentId, agentWorkspaceDir, originalTask, iterations) {
+    try {
+      const skillsDir = path.join(agentWorkspaceDir, 'skills');
+      mkdirSync(skillsDir, { recursive: true });
+
+      const skillName = this.generateSkillName(originalTask);
+      const skillPath = path.join(skillsDir, `${skillName}.md`);
+      if (existsSync(skillPath)) return; // Don't overwrite existing skill
+
+      // Strip injected context markers from the saved task description
+      const taskPreview = originalTask
+        .replace(/\[System context[\s\S]*?\]/g, '')
+        .replace(/\[Relevant skill\][\s\S]*?---\n\n/g, '')
+        .replace(/---\n\[VERIFICATION PROTOCOL\][\s\S]*$/m, '')
+        .trim()
+        .slice(0, 300);
+
+      const content = `---
+name: ${skillName}
+description: "Use for tasks involving: ${taskPreview.slice(0, 120).replace(/"/g, "'")}"
+---
+
+## Task That Triggered This Skill
+${taskPreview}
+
+## Notes
+This skill was auto-generated after the task required ${iterations} iterations.
+Review and add specific steps, pitfalls, and patterns that helped succeed.
+`;
+      writeFileSync(skillPath, content, 'utf-8');
+      console.log(`[${agentId}] 📚 Auto-saved skill: skills/${skillName}.md`);
+    } catch (e) {
+      console.log(`⚠️ Skill save failed: ${e.message}`);
+    }
+  }
+
+  // ── End Skills System ──────────────────────────────────────────────────────
+
+  // ── Designer file relay ────────────────────────────────────────────────────
+
+  async handleReadAgentFiles(message) {
+    const { requestId, agentId } = message;
+    const workDir = `/tmp/agentforge/agents/${agentId}`;
+    const DEFAULT_FILES = ['IDENTITY.md', 'SOUL.md', 'AGENTS.md', 'MEMORY.md', 'AGENTFORGE.md', 'BOOTSTRAP.md', 'HEARTBEAT.md', 'TOOLS.md', 'USER.md'];
+    const results = {};
+
+    for (const filename of DEFAULT_FILES) {
+      try {
+        results[filename] = readFileSync(path.join(workDir, filename), 'utf8');
+      } catch {
+        results[filename] = null;
+      }
+    }
+
+    // Also pick up any extra .md files in the workspace
+    try {
+      const entries = readdirSync(workDir).filter(e => e.endsWith('.md') && !DEFAULT_FILES.includes(e));
+      for (const entry of entries) {
+        try {
+          results[entry] = readFileSync(path.join(workDir, entry), 'utf8');
+        } catch {
+          results[entry] = null;
+        }
+      }
+    } catch { /* workspace may not exist yet */ }
+
+    this.send({ type: 'agent_files_result', requestId, files: results });
+  }
+
+  async handleWriteAgentFile(message) {
+    const { requestId, agentId, filename, content } = message;
+    const workDir = `/tmp/agentforge/agents/${agentId}`;
+    try {
+      if (!existsSync(workDir)) mkdirSync(workDir, { recursive: true });
+      writeFileSync(path.join(workDir, filename), content, 'utf8');
+      this.send({ type: 'write_agent_file_result', requestId, success: true });
+    } catch (err) {
+      this.send({ type: 'write_agent_file_result', requestId, success: false, error: err.message });
+    }
+  }
+
+  send(message) {
+    // Deduplicate task completions to prevent double-sends
+    if (message.type === 'task_complete' && message.taskId) {
+      if (this.recentCompletions.has(message.taskId)) {
+        console.log(`⚠️ Skipping duplicate task_complete for ${message.taskId}`);
+        return;
+      }
+      this.recentCompletions.add(message.taskId);
+      // Clean up after TTL
+      setTimeout(() => this.recentCompletions.delete(message.taskId), this.completionTTL);
+    }
+
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message));
+    } else {
+      // Queue important messages (completions, failures) for retry after reconnect
+      const importantTypes = ['task_complete', 'task_failed', 'task_cancelled'];
+      if (importantTypes.includes(message.type)) {
+        if (this.pendingMessages.length < this.maxPendingMessages) {
+          console.log(`📦 Queuing ${message.type} for ${message.taskId || message.agentId} (websocket disconnected)`);
+          this.pendingMessages.push(message);
+        } else {
+          console.warn(`⚠️ Pending message queue full, dropping ${message.type}`);
+        }
+      }
+    }
+  }
+
+  resetStaleProcessingStates() {
+    const now = Date.now();
+    let resetCount = 0;
+    
+    for (const [agentId, isProcessing] of this.agentProcessing.entries()) {
+      if (isProcessing) {
+        const startTime = this.processingStartTime.get(agentId);
+        const elapsed = startTime ? now - startTime : Infinity;
+        
+        // Reset if processing for too long OR if we just reconnected (previous task is dead)
+        if (elapsed > this.PROCESSING_TIMEOUT_MS || !startTime) {
+          console.log(`🔄 Resetting stale processing state for ${agentId} (was stuck for ${Math.round(elapsed/1000)}s)`);
+          this.agentProcessing.set(agentId, false);
+          this.processingStartTime.delete(agentId);
+          resetCount++;
+        }
+      }
+    }
+    
+    if (resetCount > 0) {
+      console.log(`🔄 Reset ${resetCount} stale processing states`);
+    }
+  }
+
+  processAllQueues() {
+    // Kick-start processing for any queues that have pending tasks
+    for (const [agentId, queue] of this.agentQueues.entries()) {
+      if (queue.length > 0 && !this.agentProcessing.get(agentId)) {
+        console.log(`📤 Resuming queue for ${agentId} (${queue.length} tasks waiting)`);
+        this.processQueue(agentId);
+      }
+    }
+  }
+
+  flushPendingMessages() {
+    if (this.pendingMessages.length === 0) return;
+    
+    console.log(`📤 Flushing ${this.pendingMessages.length} pending messages...`);
+    const messages = [...this.pendingMessages];
+    this.pendingMessages = [];
+    
+    for (const message of messages) {
+      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        console.log(`   → Sending queued ${message.type} for ${message.taskId || message.agentId}`);
+        this.ws.send(JSON.stringify(message));
+      } else {
+        // Still not connected, re-queue
+        this.pendingMessages.push(message);
+        break;
+      }
+    }
+  }
+
+  // Record that an agent produced output (reset stuck detection)
+  recordAgentActivity(agentId) {
+    this.lastAgentActivity.set(agentId, Date.now());
+    this.pingsSinceActivity.set(agentId, 0);
+  }
+
+  // Collect detailed diagnostics for debug agent
+  collectDiagnostics(agentId, taskId, error, reason) {
+    const taskInfo = this.runningTasks.get(taskId);
+    const lastActivity = this.lastAgentActivity.get(agentId);
+    const pings = this.pingsSinceActivity.get(agentId) || 0;
+    const processingTime = this.processingStartTime.get(agentId);
+
+    return {
+      timestamp: new Date().toISOString(),
+      reason, // 'error', 'stuck', 'timeout'
+      agentId,
+      taskId,
+      error: error ? {
+        message: error.message,
+        stack: error.stack,
+        name: error.name
+      } : null,
+      activity: {
+        lastActivityTime: lastActivity,
+        timeSinceActivity: lastActivity ? Date.now() - lastActivity : null,
+        pingsSinceActivity: pings,
+        processingStartTime: processingTime,
+        processingDuration: processingTime ? Date.now() - processingTime : null
+      },
+      task: taskInfo ? {
+        agentId: taskInfo.agentId,
+        roomId: taskInfo.roomId,
+        cancelled: taskInfo.cancelled
+      } : null,
+      process: {
+        hasProcess: this.cli.activeAgents ? this.cli.activeAgents.has(agentId) : false,
+        pid: this.cli.activeAgents ? this.cli.activeAgents.get(agentId)?.proc?.pid : null
+      }
+    };
+  }
+
+  // Send debug report to server for investigation by debug agent
+  sendDebugReport(diagnostics, userMessage) {
+    this.send({
+      type: 'debug_report',
+      diagnostics,
+      userMessage,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  // Check for stuck agents on each ping
+  checkForStuckAgents() {
+    for (const [agentId, isProcessing] of this.agentProcessing.entries()) {
+      if (isProcessing) {
+        // First, check if the process is still alive - if so, it's probably just thinking
+        const agentInfo = this.cli.activeAgents?.get(agentId);
+        const pid = agentInfo?.proc?.pid;
+        if (pid) {
+          try {
+            // process.kill(pid, 0) checks if process exists without killing it
+            process.kill(pid, 0);
+            // Process is alive - record activity to prevent false stuck detection
+            // This handles cases where the CLI is blocking on API calls with no stdout
+            this.recordAgentActivity(agentId);
+          } catch (e) {
+            // Process is dead - let stuck detection proceed
+            console.log(`⚠️  Agent ${agentId} process (PID ${pid}) appears dead`);
+          }
+        }
+
+        // Increment ping counter for this agent
+        const pings = (this.pingsSinceActivity.get(agentId) || 0) + 1;
+        this.pingsSinceActivity.set(agentId, pings);
+        
+        // Check if there's an active task for this agent
+        let hasActiveTask = false;
+        for (const [taskId, taskInfo] of this.runningTasks.entries()) {
+          if (taskInfo.agentId === agentId && !taskInfo.cancelled) {
+            hasActiveTask = true;
+            break;
+          }
+        }
+
+        // Use very long threshold if task is active (10 pings = 300s / 5 min)
+        // OpenClaw embedded agents can spend 2-3+ minutes on complex reasoning
+        // Only mark as stuck if truly unresponsive (no output for 5+ minutes)
+        const threshold = hasActiveTask ? 10 : this.STUCK_PING_THRESHOLD;
+
+        // Log warning when agent is quiet but not yet stuck (helps with debugging)
+        if (pings >= this.STUCK_PING_THRESHOLD && pings < threshold) {
+          console.log(`⚠️  Agent ${agentId} quiet for ${pings} pings (${Math.round((Date.now() - this.lastAgentActivity.get(agentId)) / 1000)}s), but task is active - waiting...`);
+        }
+
+        if (pings >= threshold) {
+          const lastActivity = this.lastAgentActivity.get(agentId);
+          const elapsed = lastActivity ? Math.round((Date.now() - lastActivity) / 1000) : '?';
+          const reason = hasActiveTask ? 'no output for 300s+ AND process dead' : 'no active task';
+          console.log(`🚨 STUCK DETECTED: Agent ${agentId} has had ${pings} pings with no activity (${reason}, last activity: ${elapsed}s ago)`);
+          console.log(`🚨 Force resetting agent ${agentId} to accept new tasks`);
+
+          // Find the task for diagnostics
+          let stuckTaskId = null;
+          for (const [taskId, taskInfo] of this.runningTasks.entries()) {
+            if (taskInfo.agentId === agentId && !taskInfo.cancelled) {
+              stuckTaskId = taskId;
+              break;
+            }
+          }
+
+          // Collect diagnostics before cleanup
+          const diagnostics = this.collectDiagnostics(
+            agentId,
+            stuckTaskId,
+            new Error(`Agent unresponsive for ${elapsed}s`),
+            'stuck'
+          );
+
+          // Force kill the process — try both runners
+          this.cli.cancelAgent(agentId);
+          this.hampagent?.cancelAgent(agentId);
+
+          // Clear all state for this agent
+          this.agentProcessing.set(agentId, false);
+          this.processingStartTime.delete(agentId);
+          this.pingsSinceActivity.set(agentId, 0);
+
+          // Find and cancel any running task for this agent
+          for (const [taskId, taskInfo] of this.runningTasks.entries()) {
+            if (taskInfo.agentId === agentId && !taskInfo.cancelled) {
+              taskInfo.cancelled = true;
+              this.runningTasks.delete(taskId);
+              this.send({
+                type: 'task_failed',
+                taskId,
+                agentId,
+                error: 'Agent became unresponsive (stuck detection triggered)'
+              });
+            }
+          }
+
+          // Send debug report
+          this.sendDebugReport(diagnostics, `Agent ${agentId} became unresponsive after ${elapsed}s with no activity`);
+
+          // Process any queued tasks
+          const queue = this.agentQueues.get(agentId);
+          if (queue && queue.length > 0) {
+            console.log(`📤 Processing ${queue.length} queued tasks after stuck recovery`);
+            setImmediate(() => this.processQueue(agentId));
+          }
+        }
+      }
+    }
+  }
+
+  async shutdown() {
+    console.log('🛑 Shutting down worker...');
+    // Kill all active agent processes so they don't become orphans on restart
+    if (this.cli && typeof this.cli.cancelAgent === 'function') {
+      for (const agentId of this.agentProcessing.keys()) {
+        if (this.agentProcessing.get(agentId)) {
+          console.log(`🔪 Killing agent process: ${agentId}`);
+          try { this.cli.cancelAgent(agentId); } catch (e) { /* already dead */ }
+        }
+      }
+    }
+    if (this.ws) {
+      this.ws.close();
+    }
+    process.exit(0);
+  }
+
+  // Find the AgentForge git repo root, regardless of whether worker is globally installed or run from source
+  _findRepoRoot() {
+    const home = homedir();
+    const candidates = [
+      path.resolve(__dirname, '../../..'),                                  // running from source
+      path.join(home, 'Desktop', 'Projects', 'AgentForge.ai'),
+      path.join(home, 'Desktop', 'projects', 'AgentForge.ai'),
+      path.join(home, 'Projects', 'AgentForge.ai'),
+      path.join(home, 'projects', 'AgentForge.ai'),
+    ];
+    for (const candidate of candidates) {
+      if (existsSync(path.join(candidate, '.git'))) return candidate;
+    }
+    return null;
+  }
+
+  // Auto-update: git pull the repo, reinstall the global package, then exit so process manager restarts
+  async _updateAndRestart() {
+    const { execSync } = await import('child_process');
+    const repoRoot = this._findRepoRoot();
+    if (repoRoot) {
+      try {
+        console.log(`📦 git pull in ${repoRoot}...`);
+        const out = execSync('git pull', { cwd: repoRoot, encoding: 'utf-8', timeout: 30000 });
+        console.log(out.trim() || '(already up to date)');
+        // Reinstall global package so updated source is picked up on next start
+        try {
+          console.log('📦 Reinstalling agentforge package...');
+          execSync('npm install -g ./packages/worker', { cwd: repoRoot, encoding: 'utf-8', timeout: 60000, stdio: 'pipe' });
+          console.log('✅ Package reinstalled');
+        } catch (e) {
+          console.warn('⚠️  npm install failed (will restart anyway):', e.message);
+        }
+      } catch (e) {
+        console.warn('⚠️  git pull failed (will restart anyway):', e.message);
+      }
+    } else {
+      console.log('ℹ️  No git repo found — restarting with current code');
+    }
+    console.log('🔄 Auto-update complete — exiting so you can restart: agentforge start');
+    process.exit(0);
+  }
+
+  // Periodically check for updates and restart if new commits are available
+  _startAutoUpdateCheck(intervalMs = 10 * 60 * 1000) {
+    setInterval(async () => {
+      const { execSync } = await import('child_process');
+      const repoRoot = this._findRepoRoot();
+      if (!repoRoot) return;
+      try {
+        execSync('git fetch --quiet', { cwd: repoRoot, timeout: 15000 });
+        const status = execSync('git rev-list HEAD..origin/master --count', { cwd: repoRoot, encoding: 'utf-8', timeout: 5000 }).trim();
+        if (parseInt(status) > 0) {
+          console.log(`🆕 ${status} new commit(s) on origin/master — auto-updating (worker will restart)...`);
+          if (this.ws?.readyState === 1) this.send({ type: 'worker_restarting' });
+          setTimeout(() => this._updateAndRestart(), 300);
+        }
+      } catch (e) {
+        // Non-fatal — network may be down, skip this check
+      }
+    }, intervalMs);
+  }
+}