@ian2018cs/agenthub 0.1.26 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian2018cs/agenthub",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "A web-based UI for AI Agents",
   "type": "module",
   "main": "server/index.js",
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.50",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.61",
     "@codemirror/lang-css": "^6.3.1",
     "@codemirror/lang-html": "^6.4.9",
     "@codemirror/lang-javascript": "^6.2.4",

package/server/claude-sdk.js

@@ -263,6 +263,18 @@ function getAllSessions() {
   return Array.from(activeSessions.keys());
 }
 
+// Periodic cleanup of stale sessions (every 5 minutes, remove sessions older than 2 hours)
+const SESSION_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+setInterval(() => {
+  const now = Date.now();
+  for (const [sessionId, session] of activeSessions) {
+    if (now - session.startTime > SESSION_MAX_AGE_MS) {
+      console.log(`[WARN] Cleaning up stale active session: ${sessionId} (age: ${Math.round((now - session.startTime) / 60000)}min)`);
+      activeSessions.delete(sessionId);
+    }
+  }
+}, 5 * 60 * 1000);
+
 /**
  * Transforms SDK messages to WebSocket format expected by frontend
  * @param {Object} sdkMessage - SDK message object
@@ -662,32 +674,32 @@ async function queryClaudeSDK(command, options = {}, ws) {
                 cacheCreationTokens: hasPreciseCacheData ? undefined : cacheCreationTokens
               });
 
-              // Insert usage record
-              usageDb.insertRecord({
-                user_uuid: userUuid,
-                session_id: capturedSessionId,
-                model: normalizedModel,
-                raw_model: modelKey,
-                input_tokens: inputTokens,
-                output_tokens: outputTokens,
-                cache_read_tokens: cacheReadTokens,
-                cache_creation_tokens: cacheCreationTokens,
-                cost_usd: cost,
-                source: 'sdk'
-              });
-
-              // Update daily summary
+              // Atomically insert usage record + update daily summary in a single transaction
               const today = new Date().toISOString().split('T')[0];
-              usageDb.upsertDailySummary({
-                user_uuid: userUuid,
-                date: today,
-                model: normalizedModel,
-                total_input_tokens: inputTokens,
-                total_output_tokens: outputTokens,
-                total_cost_usd: cost,
-                session_count: 0, // Session count updated separately
-                request_count: 1
-              });
+              usageDb.recordUsageTransaction(
+                {
+                  user_uuid: userUuid,
+                  session_id: capturedSessionId,
+                  model: normalizedModel,
+                  raw_model: modelKey,
+                  input_tokens: inputTokens,
+                  output_tokens: outputTokens,
+                  cache_read_tokens: cacheReadTokens,
+                  cache_creation_tokens: cacheCreationTokens,
+                  cost_usd: cost,
+                  source: 'sdk'
+                },
+                {
+                  user_uuid: userUuid,
+                  date: today,
+                  model: normalizedModel,
+                  total_input_tokens: inputTokens,
+                  total_output_tokens: outputTokens,
+                  total_cost_usd: cost,
+                  session_count: 0, // Session count updated separately
+                  request_count: 1
+                }
+              );
 
               console.log(`Recorded usage for user ${userUuid}: ${normalizedModel}, cost: $${cost.toFixed(6)}`);
             }

package/server/database/db.js

@@ -45,6 +45,11 @@ try {
 // Create database connection
 const db = new Database(DB_PATH);
 
+// Optimize SQLite for concurrent access
+db.pragma('journal_mode = WAL');       // Write-Ahead Logging for concurrent reads during writes
+db.pragma('busy_timeout = 5000');      // Wait up to 5s when database is locked instead of failing immediately
+db.pragma('synchronous = NORMAL');     // Balance between safety and performance with WAL
+
 // Show app installation path prominently
 const appInstallPath = path.join(__dirname, '../..');
 console.log('');
@@ -675,6 +680,48 @@ const usageDb = {
     }
   },
 
+  // Atomic transaction: insert usage record + upsert daily summary
+  recordUsageTransaction: db.transaction((record, summary) => {
+    const insertStmt = db.prepare(`
+      INSERT INTO usage_records (user_uuid, session_id, model, raw_model, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, cost_usd, source, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    insertStmt.run(
+      record.user_uuid,
+      record.session_id || null,
+      record.model,
+      record.raw_model || null,
+      record.input_tokens || 0,
+      record.output_tokens || 0,
+      record.cache_read_tokens || 0,
+      record.cache_creation_tokens || 0,
+      record.cost_usd || 0,
+      record.source || 'sdk',
+      record.created_at || new Date().toISOString()
+    );
+
+    const upsertStmt = db.prepare(`
+      INSERT INTO usage_daily_summary (user_uuid, date, model, total_input_tokens, total_output_tokens, total_cost_usd, session_count, request_count)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(user_uuid, date, model) DO UPDATE SET
+        total_input_tokens = total_input_tokens + excluded.total_input_tokens,
+        total_output_tokens = total_output_tokens + excluded.total_output_tokens,
+        total_cost_usd = total_cost_usd + excluded.total_cost_usd,
+        session_count = session_count + excluded.session_count,
+        request_count = request_count + excluded.request_count
+    `);
+    upsertStmt.run(
+      summary.user_uuid,
+      summary.date,
+      summary.model,
+      summary.total_input_tokens || 0,
+      summary.total_output_tokens || 0,
+      summary.total_cost_usd || 0,
+      summary.session_count || 0,
+      summary.request_count || 0
+    );
+  }),
+
   // Get all users usage summary
   getAllUsersSummary: () => {
     try {

package/server/index.js

@@ -131,9 +131,7 @@ async function setupUserProjectsWatcher(userUuid, ws) {
                     const userWatcher = userWatchers.get(userUuid);
                     if (userWatcher) {
                         userWatcher.clients.forEach(client => {
-                            if (client.readyState === WebSocket.OPEN) {
-                                client.send(updateMessage);
-                            }
+                            safeSend(client, updateMessage);
                         });
                     }
                 } catch (error) {
@@ -178,6 +176,23 @@ function cleanupUserProjectsWatcher(userUuid, ws) {
     }
 }
 
+// Periodic cleanup of dead connections from userWatchers (every 5 minutes)
+const WATCHER_CLEANUP_INTERVAL = 5 * 60 * 1000;
+setInterval(() => {
+    for (const [userUuid, { watcher, clients }] of userWatchers) {
+        for (const client of clients) {
+            if (client.readyState !== 1) { // Not WebSocket.OPEN
+                clients.delete(client);
+            }
+        }
+        if (clients.size === 0) {
+            console.log(`[INFO] Cleaning up orphaned watcher for user ${userUuid}`);
+            watcher.close();
+            userWatchers.delete(userUuid);
+        }
+    }
+}, WATCHER_CLEANUP_INTERVAL);
+
 
 const app = express();
 const server = http.createServer(app);
@@ -186,6 +201,18 @@ const ptySessionsMap = new Map();
 const codexPtySessionsMap = new Map();
 const geminiPtySessionsMap = new Map();
 const PTY_SESSION_TIMEOUT = 30 * 60 * 1000;
+const MAX_BUFFER_SIZE = 5 * 1024 * 1024; // 5MB per PTY session buffer
+
+// Safe WebSocket send - prevents crashes when connection is already closed
+function safeSend(ws, data) {
+    try {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(typeof data === 'string' ? data : JSON.stringify(data));
+        }
+    } catch (err) {
+        console.error('[WARN] WebSocket send failed:', err.message);
+    }
+}
 
 // Single WebSocket server that handles both paths
 const wss = new WebSocketServer({
@@ -228,6 +255,23 @@ const wss = new WebSocketServer({
 // Make WebSocket server available to routes
 app.locals.wss = wss;
 
+// WebSocket heartbeat to detect and clean up dead connections
+const HEARTBEAT_INTERVAL = 30000; // 30 seconds
+const heartbeatInterval = setInterval(() => {
+    wss.clients.forEach(ws => {
+        if (ws.isAlive === false) {
+            console.log('[INFO] Terminating dead WebSocket connection');
+            return ws.terminate();
+        }
+        ws.isAlive = false;
+        ws.ping();
+    });
+}, HEARTBEAT_INTERVAL);
+
+wss.on('close', () => {
+    clearInterval(heartbeatInterval);
+});
+
 app.use(cors());
 app.use(express.json({
     limit: '50mb',
@@ -592,6 +636,10 @@ wss.on('connection', (ws, request) => {
     const url = request.url;
     console.log('[INFO] Client connected to:', url);
 
+    // Initialize heartbeat tracking
+    ws.isAlive = true;
+    ws.on('pong', () => { ws.isAlive = true; });
+
     // Get user data from WebSocket authentication
     const userData = request.user;
 
@@ -624,9 +672,13 @@ class WebSocketWriter {
     }
 
     send(data) {
-        if (this.ws.readyState === 1) { // WebSocket.OPEN
-            // Providers send raw objects, we stringify for WebSocket
-            this.ws.send(JSON.stringify(data));
+        try {
+            if (this.ws.readyState === 1) { // WebSocket.OPEN
+                // Providers send raw objects, we stringify for WebSocket
+                this.ws.send(JSON.stringify(data));
+            }
+        } catch (err) {
+            console.error('[WARN] WebSocketWriter send failed:', err.message);
         }
     }
 
@@ -733,6 +785,15 @@ function handleChatConnection(ws, userData) {
             cleanupUserProjectsWatcher(userUuid, ws);
         }
     });
+
+    ws.on('error', (error) => {
+        console.error('[ERROR] Chat WebSocket error:', error.message);
+        // Ensure cleanup on error as well (close may not fire after error)
+        connectedClients.delete(ws);
+        if (userUuid) {
+            cleanupUserProjectsWatcher(userUuid, ws);
+        }
+    });
 }
 
 // Handle shell WebSocket connections
@@ -786,18 +847,18 @@ function handleShellConnection(ws, userData) {
 
                     clearTimeout(existingSession.timeoutId);
 
-                    ws.send(JSON.stringify({
+                    safeSend(ws, {
                         type: 'output',
                         data: `\x1b[36m[Reconnected to existing session]\x1b[0m\r\n`
-                    }));
+                    });
 
                     if (existingSession.buffer && existingSession.buffer.length > 0) {
                         console.log(`📜 Sending ${existingSession.buffer.length} buffered messages`);
                         existingSession.buffer.forEach(bufferedData => {
-                            ws.send(JSON.stringify({
+                            safeSend(ws, {
                                 type: 'output',
                                 data: bufferedData
-                            }));
+                            });
                         });
                     }
 
@@ -899,6 +960,7 @@ function handleShellConnection(ws, userData) {
                         pty: shellProcess,
                         ws: ws,
                         buffer: [],
+                        bufferSize: 0,
                         timeoutId: null,
                         projectPath,
                         sessionId
@@ -909,11 +971,17 @@ function handleShellConnection(ws, userData) {
                         const session = ptySessionsMap.get(ptySessionKey);
                         if (!session) return;
 
-                        if (session.buffer.length < 5000) {
+                        // Byte-size limited buffer (MAX_BUFFER_SIZE)
+                        if (session.bufferSize + data.length <= MAX_BUFFER_SIZE) {
                             session.buffer.push(data);
+                            session.bufferSize += data.length;
                         } else {
-                            session.buffer.shift();
+                            while (session.buffer.length > 0 && session.bufferSize + data.length > MAX_BUFFER_SIZE) {
+                                const removed = session.buffer.shift();
+                                session.bufferSize -= removed.length;
+                            }
                             session.buffer.push(data);
+                            session.bufferSize += data.length;
                         }
 
                         if (session.ws && session.ws.readyState === WebSocket.OPEN) {
@@ -940,10 +1008,10 @@ function handleShellConnection(ws, userData) {
                                     console.log('[DEBUG] Detected URL for opening:', url);
 
                                     // Send URL opening message to client
-                                    session.ws.send(JSON.stringify({
+                                    safeSend(session.ws, {
                                         type: 'url_open',
                                         url: url
-                                    }));
+                                    });
 
                                     // Replace the OPEN_URL pattern with a user-friendly message
                                     if (pattern.source.includes('OPEN_URL')) {
@@ -953,10 +1021,10 @@ function handleShellConnection(ws, userData) {
                             });
 
                             // Send regular output
-                            session.ws.send(JSON.stringify({
+                            safeSend(session.ws, {
                                 type: 'output',
                                 data: outputData
-                            }));
+                            });
                         }
                     });
 
@@ -964,14 +1032,14 @@ function handleShellConnection(ws, userData) {
                     shellProcess.onExit((exitCode) => {
                         console.log('🔚 Shell process exited with code:', exitCode.exitCode, 'signal:', exitCode.signal);
                         const session = ptySessionsMap.get(ptySessionKey);
-                        if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
-                            session.ws.send(JSON.stringify({
+                        if (session) {
+                            safeSend(session.ws, {
                                 type: 'output',
                                 data: `\r\n\x1b[33mProcess exited with code ${exitCode.exitCode}${exitCode.signal ? ` (${exitCode.signal})` : ''}\x1b[0m\r\n`
-                            }));
-                        }
-                        if (session && session.timeoutId) {
-                            clearTimeout(session.timeoutId);
+                            });
+                            if (session.timeoutId) {
+                                clearTimeout(session.timeoutId);
+                            }
                         }
                         ptySessionsMap.delete(ptySessionKey);
                         shellProcess = null;
@@ -979,10 +1047,10 @@ function handleShellConnection(ws, userData) {
 
                 } catch (spawnError) {
                     console.error('[ERROR] Error spawning process:', spawnError);
-                    ws.send(JSON.stringify({
+                    safeSend(ws, {
                         type: 'output',
                         data: `\r\n\x1b[31mError: ${spawnError.message}\x1b[0m\r\n`
-                    }));
+                    });
                 }
 
             } else if (data.type === 'input') {
@@ -1020,12 +1088,10 @@ function handleShellConnection(ws, userData) {
             }
         } catch (error) {
             console.error('[ERROR] Shell WebSocket error:', error.message);
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({
-                    type: 'output',
-                    data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
-                }));
-            }
+            safeSend(ws, {
+                type: 'output',
+                data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
+            });
         }
     });
 
@@ -1038,6 +1104,10 @@ function handleShellConnection(ws, userData) {
                 console.log('⏳ PTY session kept alive, will timeout in 30 minutes:', ptySessionKey);
                 session.ws = null;
 
+                // Clear any existing timeout before setting a new one (prevent race condition)
+                if (session.timeoutId) {
+                    clearTimeout(session.timeoutId);
+                }
                 session.timeoutId = setTimeout(() => {
                     console.log('⏰ PTY session timeout, killing process:', ptySessionKey);
                     if (session.pty && session.pty.kill) {
@@ -1077,15 +1147,15 @@ function handleCodexConnection(ws, userData) {
                     codexProcess = existingSession.pty;
                     clearTimeout(existingSession.timeoutId);
 
-                    ws.send(JSON.stringify({
+                    safeSend(ws, {
                         type: 'output',
                         data: `\x1b[36m[Reconnected to existing Codex session]\x1b[0m\r\n`
-                    }));
+                    });
 
                     if (existingSession.buffer && existingSession.buffer.length > 0) {
                         console.log(`📜 Sending ${existingSession.buffer.length} buffered Codex messages`);
                         existingSession.buffer.forEach(bufferedData => {
-                            ws.send(JSON.stringify({ type: 'output', data: bufferedData }));
+                            safeSend(ws, { type: 'output', data: bufferedData });
                         });
                     }
 
@@ -1095,10 +1165,10 @@ function handleCodexConnection(ws, userData) {
 
                 console.log('[INFO] Starting Codex in:', projectPath);
 
-                ws.send(JSON.stringify({
+                safeSend(ws, {
                     type: 'output',
                     data: `\x1b[36mStarting Codex in: ${projectPath}\x1b[0m\r\n`
-                }));
+                });
 
                 try {
                     const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
@@ -1161,6 +1231,7 @@ function handleCodexConnection(ws, userData) {
                         pty: codexProcess,
                         ws: ws,
                         buffer: [],
+                        bufferSize: 0,
                         timeoutId: null,
                         projectPath
                     });
@@ -1169,11 +1240,17 @@ function handleCodexConnection(ws, userData) {
                         const session = codexPtySessionsMap.get(ptySessionKey);
                         if (!session) return;
 
-                        if (session.buffer.length < 5000) {
+                        // Byte-size limited buffer (MAX_BUFFER_SIZE)
+                        if (session.bufferSize + rawData.length <= MAX_BUFFER_SIZE) {
                             session.buffer.push(rawData);
+                            session.bufferSize += rawData.length;
                         } else {
-                            session.buffer.shift();
+                            while (session.buffer.length > 0 && session.bufferSize + rawData.length > MAX_BUFFER_SIZE) {
+                                const removed = session.buffer.shift();
+                                session.bufferSize -= removed.length;
+                            }
                             session.buffer.push(rawData);
+                            session.bufferSize += rawData.length;
                         }
 
                         if (session.ws && session.ws.readyState === WebSocket.OPEN) {
@@ -1191,28 +1268,28 @@ function handleCodexConnection(ws, userData) {
                                 let match;
                                 while ((match = pattern.exec(rawData)) !== null) {
                                     const url = match[1];
-                                    session.ws.send(JSON.stringify({ type: 'url_open', url }));
+                                    safeSend(session.ws, { type: 'url_open', url });
                                     if (pattern.source.includes('OPEN_URL')) {
                                         outputData = outputData.replace(match[0], `[INFO] Opening in browser: ${url}`);
                                     }
                                 }
                             });
 
-                            session.ws.send(JSON.stringify({ type: 'output', data: outputData }));
+                            safeSend(session.ws, { type: 'output', data: outputData });
                         }
                     });
 
                     codexProcess.onExit((exitCode) => {
                         console.log('🔚 Codex process exited with code:', exitCode.exitCode);
                         const session = codexPtySessionsMap.get(ptySessionKey);
-                        if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
-                            session.ws.send(JSON.stringify({
+                        if (session) {
+                            safeSend(session.ws, {
                                 type: 'output',
                                 data: `\r\n\x1b[33mCodex exited with code ${exitCode.exitCode}${exitCode.signal ? ` (${exitCode.signal})` : ''}\x1b[0m\r\n`
-                            }));
-                        }
-                        if (session && session.timeoutId) {
-                            clearTimeout(session.timeoutId);
+                            });
+                            if (session.timeoutId) {
+                                clearTimeout(session.timeoutId);
+                            }
                         }
                         codexPtySessionsMap.delete(ptySessionKey);
                         codexProcess = null;
@@ -1220,10 +1297,10 @@ function handleCodexConnection(ws, userData) {
 
                 } catch (spawnError) {
                     console.error('[ERROR] Error spawning Codex process:', spawnError);
-                    ws.send(JSON.stringify({
+                    safeSend(ws, {
                         type: 'output',
                         data: `\r\n\x1b[31mError starting Codex: ${spawnError.message}\x1b[0m\r\n`
-                    }));
+                    });
                 }
 
             } else if (data.type === 'input') {
@@ -1250,12 +1327,10 @@ function handleCodexConnection(ws, userData) {
             }
         } catch (error) {
             console.error('[ERROR] Codex WebSocket error:', error.message);
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({
-                    type: 'output',
-                    data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
-                }));
-            }
+            safeSend(ws, {
+                type: 'output',
+                data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
+            });
         }
     });
 
@@ -1266,6 +1341,10 @@ function handleCodexConnection(ws, userData) {
             if (session) {
                 console.log('⏳ Codex PTY session kept alive, will timeout in 30 minutes:', ptySessionKey);
                 session.ws = null;
+                // Clear any existing timeout before setting a new one (prevent race condition)
+                if (session.timeoutId) {
+                    clearTimeout(session.timeoutId);
+                }
                 session.timeoutId = setTimeout(() => {
                     console.log('⏰ Codex PTY session timeout, killing process:', ptySessionKey);
                     if (session.pty && session.pty.kill) {
@@ -1304,15 +1383,15 @@ function handleGeminiConnection(ws, userData) {
                     geminiProcess = existingSession.pty;
                     clearTimeout(existingSession.timeoutId);
 
-                    ws.send(JSON.stringify({
+                    safeSend(ws, {
                         type: 'output',
                         data: `\x1b[36m[Reconnected to existing Gemini session]\x1b[0m\r\n`
-                    }));
+                    });
 
                     if (existingSession.buffer && existingSession.buffer.length > 0) {
                         console.log(`📜 Sending ${existingSession.buffer.length} buffered Gemini messages`);
                         existingSession.buffer.forEach(bufferedData => {
-                            ws.send(JSON.stringify({ type: 'output', data: bufferedData }));
+                            safeSend(ws, { type: 'output', data: bufferedData });
                         });
                     }
 
@@ -1322,10 +1401,10 @@ function handleGeminiConnection(ws, userData) {
 
                 console.log('[INFO] Starting Gemini in:', projectPath);
 
-                ws.send(JSON.stringify({
+                safeSend(ws, {
                     type: 'output',
                     data: `\x1b[36mStarting Gemini in: ${projectPath}\x1b[0m\r\n`
-                }));
+                });
 
                 try {
                     const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
@@ -1387,6 +1466,7 @@ function handleGeminiConnection(ws, userData) {
                         pty: geminiProcess,
                         ws: ws,
                         buffer: [],
+                        bufferSize: 0,
                         timeoutId: null,
                         projectPath
                     });
@@ -1395,11 +1475,17 @@ function handleGeminiConnection(ws, userData) {
                         const session = geminiPtySessionsMap.get(ptySessionKey);
                         if (!session) return;
 
-                        if (session.buffer.length < 5000) {
+                        // Byte-size limited buffer (MAX_BUFFER_SIZE)
+                        if (session.bufferSize + rawData.length <= MAX_BUFFER_SIZE) {
                             session.buffer.push(rawData);
+                            session.bufferSize += rawData.length;
                         } else {
-                            session.buffer.shift();
+                            while (session.buffer.length > 0 && session.bufferSize + rawData.length > MAX_BUFFER_SIZE) {
+                                const removed = session.buffer.shift();
+                                session.bufferSize -= removed.length;
+                            }
                             session.buffer.push(rawData);
+                            session.bufferSize += rawData.length;
                         }
 
                         if (session.ws && session.ws.readyState === WebSocket.OPEN) {
@@ -1417,28 +1503,28 @@ function handleGeminiConnection(ws, userData) {
                                 let match;
                                 while ((match = pattern.exec(rawData)) !== null) {
                                     const url = match[1];
-                                    session.ws.send(JSON.stringify({ type: 'url_open', url }));
+                                    safeSend(session.ws, { type: 'url_open', url });
                                     if (pattern.source.includes('OPEN_URL')) {
                                         outputData = outputData.replace(match[0], `[INFO] Opening in browser: ${url}`);
                                     }
                                 }
                             });
 
-                            session.ws.send(JSON.stringify({ type: 'output', data: outputData }));
+                            safeSend(session.ws, { type: 'output', data: outputData });
                         }
                     });
 
                     geminiProcess.onExit((exitCode) => {
                         console.log('🔚 Gemini process exited with code:', exitCode.exitCode);
                         const session = geminiPtySessionsMap.get(ptySessionKey);
-                        if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
-                            session.ws.send(JSON.stringify({
+                        if (session) {
+                            safeSend(session.ws, {
                                 type: 'output',
                                 data: `\r\n\x1b[33mGemini exited with code ${exitCode.exitCode}${exitCode.signal ? ` (${exitCode.signal})` : ''}\x1b[0m\r\n`
-                            }));
-                        }
-                        if (session && session.timeoutId) {
-                            clearTimeout(session.timeoutId);
+                            });
+                            if (session.timeoutId) {
+                                clearTimeout(session.timeoutId);
+                            }
                         }
                         geminiPtySessionsMap.delete(ptySessionKey);
                         geminiProcess = null;
@@ -1446,10 +1532,10 @@ function handleGeminiConnection(ws, userData) {
 
                 } catch (spawnError) {
                     console.error('[ERROR] Error spawning Gemini process:', spawnError);
-                    ws.send(JSON.stringify({
+                    safeSend(ws, {
                         type: 'output',
                         data: `\r\n\x1b[31mError starting Gemini: ${spawnError.message}\x1b[0m\r\n`
-                    }));
+                    });
                 }
 
             } else if (data.type === 'input') {
@@ -1476,12 +1562,10 @@ function handleGeminiConnection(ws, userData) {
             }
         } catch (error) {
             console.error('[ERROR] Gemini WebSocket error:', error.message);
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({
-                    type: 'output',
-                    data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
-                }));
-            }
+            safeSend(ws, {
+                type: 'output',
+                data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
+            });
         }
     });
 
@@ -1492,6 +1576,10 @@ function handleGeminiConnection(ws, userData) {
             if (session) {
                 console.log('⏳ Gemini PTY session kept alive, will timeout in 30 minutes:', ptySessionKey);
                 session.ws = null;
+                // Clear any existing timeout before setting a new one (prevent race condition)
+                if (session.timeoutId) {
+                    clearTimeout(session.timeoutId);
+                }
                 session.timeoutId = setTimeout(() => {
                     console.log('⏰ Gemini PTY session timeout, killing process:', ptySessionKey);
                     if (session.pty && session.pty.kill) {

package/server/routes/skills.js

@@ -29,31 +29,24 @@ const upload = multer({
 });
 
 /**
- * Parse skill metadata from SKILLS.md file
+ * Parse skill metadata from SKILL.md YAML frontmatter
  */
 async function parseSkillMetadata(skillPath) {
   try {
     const skillsFile = path.join(skillPath, 'SKILL.md');
     const content = await fs.readFile(skillsFile, 'utf-8');
 
-    // Extract title from first # heading
-    const titleMatch = content.match(/^#\s+(.+)$/m);
-    const title = titleMatch ? titleMatch[1].trim() : path.basename(skillPath);
-
-    // Extract description from content after title (first paragraph)
-    const lines = content.split('\n');
+    let title = path.basename(skillPath);
     let description = '';
-    let foundTitle = false;
-    for (const line of lines) {
-      if (line.startsWith('#')) {
-        if (foundTitle) break;
-        foundTitle = true;
-        continue;
-      }
-      if (foundTitle && line.trim()) {
-        description = line.trim();
-        break;
-      }
+
+    // Parse YAML frontmatter (between --- delimiters)
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      const fm = fmMatch[1];
+      const nameMatch = fm.match(/^name:\s*(.+)$/m);
+      const descMatch = fm.match(/^description:\s*(.+)$/m);
+      if (nameMatch) title = nameMatch[1].trim();
+      if (descMatch) description = descMatch[1].trim();
     }
 
     return { title, description };