@clawchatsai/connector 0.0.1

package/server.js

@@ -0,0 +1,4058 @@
+// ShellChat Backend Server
+// Single-file Node.js HTTP server with SQLite storage
+// See specs/backend-session-architecture.md for full spec
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+import { execSync } from 'node:child_process';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import Database from 'better-sqlite3';
+import { WebSocket as WS, WebSocketServer } from 'ws';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+const PORT = parseInt(process.env.SHELLCHAT_PORT || '3001', 10);
+const DATA_DIR = path.join(__dirname, 'data');
+const UPLOADS_DIR = path.join(__dirname, 'uploads');
+const WORKSPACES_FILE = path.join(DATA_DIR, 'workspaces.json');
+
+// --- Debug Recording (isolated module) ---
+class DebugLogger {
+  constructor(baseDir) {
+    this.baseDir = path.join(baseDir, '..', 'debug');
+    this.active = false;
+    this.sessionId = null;
+    this.wsStream = null;
+    this.originatingClient = null;
+  }
+
+  start(ts, originatingClient) {
+    if (this.active) {
+      return { error: 'already-active', sessionId: this.sessionId };
+    }
+    this.sessionId = ts.replace(/[:.]/g, '-');
+    this.originatingClient = originatingClient;
+    fs.mkdirSync(this.baseDir, { recursive: true });
+    const wsLogPath = path.join(this.baseDir, `session-${this.sessionId}-ws.log`);
+    this.wsStream = fs.createWriteStream(wsLogPath, { flags: 'a' });
+    this.active = true;
+    console.log(`Debug recording started: ${this.sessionId}`);
+    return { sessionId: this.sessionId };
+  }
+
+  logFrame(direction, data) {
+    if (!this.active || !this.wsStream) return;
+    this.wsStream.write(`${new Date().toISOString()} ${direction} ${data}\n`);
+  }
+
+  saveDump(payload) {
+    if (!this.sessionId) return { sessionId: null, files: [] };
+    const files = [];
+    const id = this.sessionId;
+
+    if (this.wsStream) {
+      this.wsStream.end();
+      this.wsStream = null;
+      files.push(`session-${id}-ws.log`);
+    }
+
+    const clientLogPath = path.join(this.baseDir, `session-${id}-client.log`);
+    let logContent = '';
+    for (const entry of (payload.console || [])) {
+      const args = entry.args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ');
+      logContent += `${entry.ts} [${entry.level.toUpperCase()}] ${args}\n`;
+    }
+    for (const err of (payload.errors || [])) {
+      logContent += `${err.ts} [UNHANDLED] ${err.message}\n${err.stack || ''}\n`;
+    }
+    if (logContent) {
+      fs.writeFileSync(clientLogPath, logContent);
+      files.push(`session-${id}-client.log`);
+    }
+
+    if (payload.state) {
+      const statePath = path.join(this.baseDir, `session-${id}-state.json`);
+      fs.writeFileSync(statePath, JSON.stringify(payload.state, null, 2));
+      files.push(`session-${id}-state.json`);
+    }
+
+    if (payload.screenshot) {
+      const ssPath = path.join(this.baseDir, `session-${id}-screenshot.jpg`);
+      fs.writeFileSync(ssPath, Buffer.from(payload.screenshot, 'base64'));
+      files.push(`session-${id}-screenshot.jpg`);
+    }
+
+    const savedId = id;
+    this.active = false;
+    this.sessionId = null;
+    this.originatingClient = null;
+    console.log(`Debug session saved: ${files.join(', ')}`);
+    return { sessionId: savedId, files };
+  }
+
+  handleClientDisconnect(ws) {
+    if (this.active && this.originatingClient === ws) {
+      console.log(`Debug session ${this.sessionId} auto-closed: client disconnected`);
+      if (this.wsStream) {
+        this.wsStream.write(`${new Date().toISOString()} SYSTEM Client disconnected — session auto-closed\n`);
+        this.wsStream.end();
+        this.wsStream = null;
+      }
+      this.active = false;
+      this.sessionId = null;
+      this.originatingClient = null;
+    }
+  }
+}
+
+const debugLogger = new DebugLogger(DATA_DIR);
+const HOME = os.homedir();
+const MAX_PREAMBLE_CHARS = 50000;
+
+// ─── Config.js Parser ────────────────────────────────────────────────────────
+
+function parseConfigField(field) {
+  try {
+    const configPath = path.join(__dirname, 'config.js');
+    const configText = fs.readFileSync(configPath, 'utf8');
+    const match = configText.match(new RegExp(`${field}:\\s*['"]([^'"]+)['"]`));
+    return match ? match[1] : null;
+  } catch { return null; }
+}
+
+// Load auth token from config.js or env var
+let AUTH_TOKEN = process.env.SHELLCHAT_AUTH_TOKEN || parseConfigField('authToken') || '';
+if (!AUTH_TOKEN) {
+  console.error('WARNING: No auth token configured. Set SHELLCHAT_AUTH_TOKEN or create config.js');
+}
+
+// Load gateway WebSocket URL
+// Priority: env var → OpenClaw config (local) → conventional default
+// NOTE: Do NOT use config.js gatewayUrl — that's the browser's external-facing URL.
+// server.js needs the internal/local gateway address.
+function discoverGatewayWsUrl() {
+  if (process.env.GATEWAY_WS_URL) return process.env.GATEWAY_WS_URL;
+  // Read OpenClaw's own config for the local gateway port
+  const candidates = [
+    path.join(os.homedir(), '.openclaw', 'openclaw.json'),
+    '/etc/openclaw/openclaw.json'
+  ];
+  for (const cfgPath of candidates) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      const port = raw.gateway?.port || raw.port;
+      const host = raw.gateway?.host || raw.host || 'localhost';
+      if (port) return `ws://${host}:${port}`;
+    } catch {}
+  }
+  return 'ws://localhost:18789';
+}
+const GATEWAY_WS_URL = discoverGatewayWsUrl();
+
+// ─── Sessions Directory Discovery ────────────────────────────────────────────
+
+function discoverViaCliSync() {
+  try {
+    const output = execSync('openclaw status --json', { encoding: 'utf8', timeout: 5000 });
+    const status = JSON.parse(output);
+    if (status.sessions?.paths?.[0]) {
+      return path.dirname(status.sessions.paths[0]);
+    }
+  } catch { /* cli not available or failed */ }
+  return null;
+}
+
+const OPENCLAW_SESSIONS_DIR = (() => {
+  if (process.env.OPENCLAW_SESSIONS_DIR) {
+    console.log(`Sessions dir: ${process.env.OPENCLAW_SESSIONS_DIR} (source: env)`);
+    return process.env.OPENCLAW_SESSIONS_DIR;
+  }
+  const configDir = parseConfigField('sessionsDir');
+  if (configDir) {
+    console.log(`Sessions dir: ${configDir} (source: config)`);
+    return configDir;
+  }
+  const cliDir = discoverViaCliSync();
+  if (cliDir) {
+    console.log(`Sessions dir: ${cliDir} (source: cli)`);
+    return cliDir;
+  }
+  const fallback = path.join(HOME, '.openclaw', 'agents', 'main', 'sessions');
+  console.log(`Sessions dir: ${fallback} (source: fallback)`);
+  return fallback;
+})();
+
+// ─── Workspace Management ───────────────────────────────────────────────────
+
+function ensureDirs() {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.mkdirSync(UPLOADS_DIR, { recursive: true });
+}
+
+function loadWorkspaces() {
+  try {
+    return JSON.parse(fs.readFileSync(WORKSPACES_FILE, 'utf8'));
+  } catch {
+    const initial = {
+      active: 'default',
+      workspaces: {
+        default: {
+          name: 'default',
+          label: 'Default',
+          createdAt: Date.now()
+        }
+      }
+    };
+    fs.writeFileSync(WORKSPACES_FILE, JSON.stringify(initial, null, 2));
+    return initial;
+  }
+}
+
+function saveWorkspaces(data) {
+  fs.writeFileSync(WORKSPACES_FILE, JSON.stringify(data, null, 2));
+}
+
+let workspacesConfig = null;
+
+function getWorkspaces() {
+  if (!workspacesConfig) workspacesConfig = loadWorkspaces();
+  return workspacesConfig;
+}
+
+function setWorkspaces(data) {
+  workspacesConfig = data;
+  saveWorkspaces(data);
+}
+
+// ─── Database Management ────────────────────────────────────────────────────
+
+const dbCache = new Map(); // name → Database instance
+
+function getDb(workspaceName) {
+  if (dbCache.has(workspaceName)) return dbCache.get(workspaceName);
+  const dbPath = path.join(DATA_DIR, `${workspaceName}.db`);
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  migrate(db);
+  dbCache.set(workspaceName, db);
+  return db;
+}
+
+function getActiveDb() {
+  return getDb(getWorkspaces().active);
+}
+
+function closeDb(workspaceName) {
+  const db = dbCache.get(workspaceName);
+  if (db) {
+    db.close();
+    dbCache.delete(workspaceName);
+  }
+}
+
+function closeAllDbs() {
+  for (const [name, db] of dbCache) {
+    db.close();
+  }
+  dbCache.clear();
+}
+
+function migrate(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS threads (
+      id TEXT PRIMARY KEY,
+      session_key TEXT UNIQUE NOT NULL,
+      title TEXT DEFAULT 'New chat',
+      pinned INTEGER DEFAULT 0,
+      pin_order INTEGER DEFAULT 0,
+      model TEXT,
+      last_session_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      status TEXT DEFAULT 'sent',
+      metadata TEXT,
+      seq INTEGER,
+      timestamp INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (thread_id) REFERENCES threads(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages(thread_id, timestamp);
+    CREATE INDEX IF NOT EXISTS idx_messages_dedup ON messages(thread_id, role, timestamp);
+  `);
+
+  // Migration: add sort_order column if missing
+  try {
+    db.exec('ALTER TABLE threads ADD COLUMN sort_order INTEGER DEFAULT 0');
+  } catch (e) {
+    // Column already exists — ignore
+  }
+
+  // Migration: add unread_count column if missing
+  try {
+    db.exec('ALTER TABLE threads ADD COLUMN unread_count INTEGER DEFAULT 0');
+  } catch (e) {
+    // Column already exists — ignore
+  }
+
+  // Migration: unread_messages table for per-message read tracking
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS unread_messages (
+      thread_id TEXT NOT NULL,
+      message_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (thread_id, message_id),
+      FOREIGN KEY (thread_id) REFERENCES threads(id) ON DELETE CASCADE
+    )
+  `);
+  db.exec('CREATE INDEX IF NOT EXISTS idx_unread_thread ON unread_messages(thread_id)');
+
+  // FTS5 table — CREATE VIRTUAL TABLE doesn't support IF NOT EXISTS in all versions,
+  // so check if it exists first
+  const hasFts = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'"
+  ).get();
+  if (!hasFts) {
+    db.exec(`
+      CREATE VIRTUAL TABLE messages_fts USING fts5(
+        content,
+        content=messages,
+        content_rowid=rowid,
+        tokenize='porter unicode61'
+      );
+
+      CREATE TRIGGER messages_ai AFTER INSERT ON messages BEGIN
+        INSERT INTO messages_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+      CREATE TRIGGER messages_ad AFTER DELETE ON messages BEGIN
+        INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+      END;
+      CREATE TRIGGER messages_au AFTER UPDATE ON messages BEGIN
+        INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+        INSERT INTO messages_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+    `);
+  }
+}
+
+// ─── HTTP Helpers ───────────────────────────────────────────────────────────
+
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString();
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); }
+      catch { reject(new Error('Invalid JSON')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function send(res, status, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+  });
+  res.end(body);
+}
+
+function sendError(res, status, message) {
+  send(res, status, { error: message });
+}
+
+function setCors(res) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+}
+
+function uuid() {
+  return crypto.randomUUID();
+}
+
+// ─── Route matching ─────────────────────────────────────────────────────────
+
+function matchRoute(method, url, pattern) {
+  // pattern like "GET /api/threads/:id/messages/:messageId"
+  const [pMethod, pPath] = pattern.split(' ');
+  if (method !== pMethod) return null;
+  const pParts = pPath.split('/').filter(Boolean);
+  const uParts = url.split('/').filter(Boolean);
+  if (pParts.length !== uParts.length) return null;
+  const params = {};
+  for (let i = 0; i < pParts.length; i++) {
+    if (pParts[i].startsWith(':')) {
+      params[pParts[i].slice(1)] = decodeURIComponent(uParts[i]);
+    } else if (pParts[i] !== uParts[i]) {
+      return null;
+    }
+  }
+  return params;
+}
+
+// ─── Auth Middleware ─────────────────────────────────────────────────────────
+
+function checkAuth(req, res) {
+  if (!AUTH_TOKEN) return true; // no token configured = open
+  const auth = req.headers.authorization;
+  if (!auth || !auth.startsWith('Bearer ')) {
+    sendError(res, 401, 'Missing or invalid Authorization header');
+    return false;
+  }
+  const token = auth.slice(7);
+  if (token !== AUTH_TOKEN) {
+    sendError(res, 401, 'Invalid auth token');
+    return false;
+  }
+  return true;
+}
+
+// ─── Multipart Parser (minimal, for file uploads) ───────────────────────────
+
+function parseMultipart(req) {
+  return new Promise((resolve, reject) => {
+    const contentType = req.headers['content-type'] || '';
+    const boundaryMatch = contentType.match(/boundary=(?:"([^"]+)"|([^\s;]+))/);
+    if (!boundaryMatch) return reject(new Error('No boundary in content-type'));
+    const boundary = boundaryMatch[1] || boundaryMatch[2];
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('end', () => {
+      const buf = Buffer.concat(chunks);
+      const files = [];
+      const delimiter = Buffer.from(`--${boundary}`);
+      const end = Buffer.from(`--${boundary}--`);
+
+      let pos = 0;
+      while (pos < buf.length) {
+        const start = buf.indexOf(delimiter, pos);
+        if (start === -1) break;
+        const nextStart = buf.indexOf(delimiter, start + delimiter.length);
+        if (nextStart === -1) break;
+
+        const part = buf.subarray(start + delimiter.length, nextStart);
+        const headerEnd = part.indexOf('\r\n\r\n');
+        if (headerEnd === -1) { pos = nextStart; continue; }
+
+        const headerStr = part.subarray(0, headerEnd).toString();
+        let body = part.subarray(headerEnd + 4);
+        // Trim trailing \r\n
+        if (body.length >= 2 && body[body.length - 2] === 0x0d && body[body.length - 1] === 0x0a) {
+          body = body.subarray(0, body.length - 2);
+        }
+
+        const filenameMatch = headerStr.match(/filename="([^"]+)"/);
+        const ctMatch = headerStr.match(/Content-Type:\s*(\S+)/i);
+        if (filenameMatch) {
+          files.push({
+            filename: filenameMatch[1],
+            mimeType: ctMatch ? ctMatch[1] : 'application/octet-stream',
+            data: body,
+          });
+        }
+        pos = nextStart;
+      }
+      resolve(files);
+    });
+    req.on('error', reject);
+  });
+}
+
+// ─── Context Fill Helper ────────────────────────────────────────────────────
+
+function buildContextPreamble(db, threadId, lastSessionId) {
+  let summary = null;
+  let method = 'raw';
+
+  // Try to read old JSONL transcript
+  if (lastSessionId) {
+    const jsonlPath = path.join(OPENCLAW_SESSIONS_DIR, `${lastSessionId}.jsonl`);
+    try {
+      const content = fs.readFileSync(jsonlPath, 'utf8');
+      const lines = content.split('\n').filter(Boolean);
+      // Find last compaction entry
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          const entry = JSON.parse(lines[i]);
+          if (entry.type === 'compaction' && entry.summary) {
+            summary = entry.summary;
+            method = 'compaction';
+            break;
+          }
+        } catch { /* skip malformed lines */ }
+      }
+    } catch { /* file not found, fall back to raw */ }
+  }
+
+  // Build preamble
+  let preamble = '';
+
+  if (method === 'compaction' && summary) {
+    preamble += '[CONTEXT RECOVERY — This thread\'s agent session was reset. Below is a summary of the previous conversation followed by recent messages to restore context.]\n\n';
+    preamble += '[CONVERSATION SUMMARY]\n';
+    preamble += summary + '\n\n';
+
+    // Last 10 messages from SQLite
+    const msgs = db.prepare(
+      'SELECT role, content, timestamp FROM messages WHERE thread_id = ? ORDER BY timestamp DESC LIMIT 10'
+    ).all(threadId).reverse();
+
+    if (msgs.length) {
+      preamble += '[RECENT MESSAGES]\n';
+      for (const m of msgs) {
+        const d = new Date(m.timestamp);
+        const ts = d.toISOString().replace('T', ' ').slice(0, 16);
+        const role = m.role.charAt(0).toUpperCase() + m.role.slice(1);
+        preamble += `${role} (${ts}): ${m.content}\n`;
+      }
+    }
+  } else {
+    preamble += '[CONTEXT RECOVERY — This thread\'s agent session was reset. Below are recent messages from the previous conversation to restore context.]\n\n';
+
+    // Last 25 messages from SQLite
+    const msgs = db.prepare(
+      'SELECT role, content, timestamp FROM messages WHERE thread_id = ? ORDER BY timestamp DESC LIMIT 25'
+    ).all(threadId).reverse();
+
+    if (msgs.length) {
+      preamble += '[PREVIOUS MESSAGES]\n';
+      for (const m of msgs) {
+        const d = new Date(m.timestamp);
+        const ts = d.toISOString().replace('T', ' ').slice(0, 16);
+        const role = m.role.charAt(0).toUpperCase() + m.role.slice(1);
+        preamble += `${role} (${ts}): ${m.content}\n`;
+      }
+    }
+  }
+
+  // Enforce token budget
+  if (preamble.length > MAX_PREAMBLE_CHARS) {
+    preamble = preamble.slice(preamble.length - MAX_PREAMBLE_CHARS);
+  }
+
+  return { preamble, method };
+}
+
+// ─── Gateway Session Cleanup ─────────────────────────────────────────────────
+
+function cleanGatewaySession(sessionKey) {
+  try {
+    const sessionsPath = path.join(OPENCLAW_SESSIONS_DIR, 'sessions.json');
+    const raw = fs.readFileSync(sessionsPath, 'utf8');
+    const store = JSON.parse(raw);
+    const entry = store[sessionKey];
+    if (!entry) return null;
+
+    // Delete .jsonl transcript
+    if (entry.sessionId) {
+      const jsonlPath = path.join(OPENCLAW_SESSIONS_DIR, `${entry.sessionId}.jsonl`);
+      try { fs.unlinkSync(jsonlPath); } catch { /* ok */ }
+    }
+
+    // Remove entry from store and write back
+    const sessionId = entry.sessionId || null;
+    delete store[sessionKey];
+    fs.writeFileSync(sessionsPath, JSON.stringify(store, null, 2));
+    return sessionId;
+  } catch (err) {
+    console.warn(`cleanGatewaySession(${sessionKey}):`, err.message);
+    return null;
+  }
+}
+
+function cleanGatewaySessionsByPrefix(prefix) {
+  try {
+    const sessionsPath = path.join(OPENCLAW_SESSIONS_DIR, 'sessions.json');
+    const raw = fs.readFileSync(sessionsPath, 'utf8');
+    const store = JSON.parse(raw);
+    let cleaned = 0;
+
+    for (const key of Object.keys(store)) {
+      if (!key.startsWith(prefix)) continue;
+      const entry = store[key];
+      if (entry?.sessionId) {
+        const jsonlPath = path.join(OPENCLAW_SESSIONS_DIR, `${entry.sessionId}.jsonl`);
+        try { fs.unlinkSync(jsonlPath); } catch { /* ok */ }
+      }
+      delete store[key];
+      cleaned++;
+    }
+
+    if (cleaned > 0) {
+      fs.writeFileSync(sessionsPath, JSON.stringify(store, null, 2));
+    }
+    return cleaned;
+  } catch (err) {
+    console.warn(`cleanGatewaySessionsByPrefix(${prefix}):`, err.message);
+    return 0;
+  }
+}
+
+// ─── Route Handlers ─────────────────────────────────────────────────────────
+
+// --- User settings (synced across devices) ---
+const SETTINGS_FILE = path.join(DATA_DIR, 'settings.json');
+
+function handleGetSettings(req, res) {
+  try {
+    const data = fs.existsSync(SETTINGS_FILE)
+      ? JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'))
+      : {};
+    return send(res, 200, data);
+  } catch {
+    return send(res, 200, {});
+  }
+}
+
+async function handleSaveSettings(req, res) {
+  const body = await parseBody(req);
+  try {
+    // Merge with existing settings
+    const existing = fs.existsSync(SETTINGS_FILE)
+      ? JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'))
+      : {};
+    const merged = { ...existing, ...body };
+    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(merged, null, 2));
+    return send(res, 200, merged);
+  } catch (err) {
+    return send(res, 500, { error: err.message });
+  }
+}
+
+// --- Workspaces ---
+
+function handleGetWorkspaces(req, res) {
+  const ws = getWorkspaces();
+  const sorted = Object.values(ws.workspaces).sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+
+  // Add unread_count for each workspace (from thread unread_count column, kept in sync by mark-read + WS handler)
+  for (const workspace of sorted) {
+    try {
+      const db = getDb(workspace.name);
+      const result = db.prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get();
+      workspace.unread_count = result.total;
+    } catch (e) {
+      workspace.unread_count = 0;
+    }
+  }
+
+  send(res, 200, {
+    active: ws.active,
+    workspaces: sorted,
+  });
+}
+
+async function handleCreateWorkspace(req, res) {
+  const body = await parseBody(req);
+  const { name, label } = body;
+  if (!name || !/^[a-z0-9-]{1,32}$/.test(name)) {
+    return sendError(res, 400, 'Name must be [a-z0-9-], 1-32 chars');
+  }
+  const ws = getWorkspaces();
+  if (ws.workspaces[name]) {
+    return sendError(res, 409, 'Workspace already exists');
+  }
+  const workspace = { name, label: label || name, color: body.color || null, icon: body.icon || null, createdAt: Date.now() };
+  ws.workspaces[name] = workspace;
+  setWorkspaces(ws);
+  // Initialize DB
+  getDb(name);
+  send(res, 201, { workspace });
+}
+
+async function handleUpdateWorkspace(req, res, params) {
+  const body = await parseBody(req);
+  const ws = getWorkspaces();
+  if (!ws.workspaces[params.name]) {
+    return sendError(res, 404, 'Workspace not found');
+  }
+  if (body.label !== undefined) {
+    ws.workspaces[params.name].label = body.label;
+  }
+  if (body.color !== undefined) {
+    ws.workspaces[params.name].color = body.color;
+  }
+  if (body.icon !== undefined) {
+    ws.workspaces[params.name].icon = body.icon;
+  }
+  setWorkspaces(ws);
+  send(res, 200, { workspace: ws.workspaces[params.name] });
+}
+
+function handleDeleteWorkspace(req, res, params) {
+  const ws = getWorkspaces();
+  console.log('DELETE workspace:', params.name, 'workspaces:', Object.keys(ws.workspaces), 'active:', ws.active);
+  if (!ws.workspaces[params.name]) {
+    return sendError(res, 404, 'Workspace not found');
+  }
+  if (Object.keys(ws.workspaces).length <= 1) {
+    return sendError(res, 400, 'Cannot delete the only workspace');
+  }
+  if (ws.active === params.name) {
+    return sendError(res, 400, 'Cannot delete the active workspace');
+  }
+  // Close and remove DB
+  closeDb(params.name);
+  const dbPath = path.join(DATA_DIR, `${params.name}.db`);
+  try { fs.unlinkSync(dbPath); } catch { /* ok */ }
+  try { fs.unlinkSync(dbPath + '-wal'); } catch { /* ok */ }
+  try { fs.unlinkSync(dbPath + '-shm'); } catch { /* ok */ }
+
+  // Clean all gateway sessions for this workspace
+  const cleaned = cleanGatewaySessionsByPrefix(`agent:main:${params.name}:chat:`);
+  if (cleaned > 0) {
+    console.log(`Cleaned ${cleaned} gateway sessions for workspace: ${params.name}`);
+  }
+
+  delete ws.workspaces[params.name];
+  setWorkspaces(ws);
+  send(res, 200, { ok: true });
+}
+
+async function handleReorderWorkspaces(req, res) {
+  const body = await parseBody(req);
+  const { order } = body;
+  if (!Array.isArray(order)) {
+    return sendError(res, 400, 'order must be an array of workspace names');
+  }
+  const ws = getWorkspaces();
+  // Assign order index to each workspace
+  order.forEach((name, i) => {
+    if (ws.workspaces[name]) {
+      ws.workspaces[name].order = i;
+    }
+  });
+  setWorkspaces(ws);
+  send(res, 200, { ok: true, workspaces: Object.values(ws.workspaces) });
+}
+
+function handleActivateWorkspace(req, res, params) {
+  const ws = getWorkspaces();
+  if (!ws.workspaces[params.name]) {
+    return sendError(res, 404, 'Workspace not found');
+  }
+  ws.active = params.name;
+  setWorkspaces(ws);
+  // Pre-open the DB
+  getDb(params.name);
+  send(res, 200, { ok: true, workspace: ws.workspaces[params.name] });
+}
+
+// --- Threads ---
+
+function handleGetThreads(req, res, params, query) {
+  const db = getActiveDb();
+  const page = parseInt(query.page || '1', 10);
+  const limit = Math.min(parseInt(query.limit || '50', 10), 200);
+  const offset = (page - 1) * limit;
+  const search = query.search || '';
+
+  let threads, total;
+  if (search) {
+    // FTS5 search across messages, return matching thread IDs
+    const ftsQuery = `
+      SELECT DISTINCT m.thread_id
+      FROM messages m
+      JOIN messages_fts ON messages_fts.rowid = m.rowid
+      WHERE messages_fts MATCH ?
+    `;
+    const matchingIds = db.prepare(ftsQuery).all(search).map(r => r.thread_id);
+    if (matchingIds.length === 0) {
+      return send(res, 200, { threads: [], total: 0, page });
+    }
+    const placeholders = matchingIds.map(() => '?').join(',');
+    total = db.prepare(
+      `SELECT COUNT(*) as c FROM threads WHERE id IN (${placeholders})`
+    ).get(...matchingIds).c;
+    threads = db.prepare(
+      `SELECT * FROM threads WHERE id IN (${placeholders}) ORDER BY pinned DESC, sort_order DESC, updated_at DESC LIMIT ? OFFSET ?`
+    ).all(...matchingIds, limit, offset);
+  } else {
+    total = db.prepare('SELECT COUNT(*) as c FROM threads').get().c;
+    threads = db.prepare(
+      'SELECT * FROM threads ORDER BY pinned DESC, sort_order DESC, updated_at DESC LIMIT ? OFFSET ?'
+    ).all(limit, offset);
+  }
+
+  send(res, 200, { threads, total, page });
+}
+
+function handleGetUnreadThreads(req, res) {
+  const db = getActiveDb();
+  const threads = db.prepare(`
+    SELECT t.id, t.title, t.unread_count, m.content as lastMessage
+    FROM threads t
+    LEFT JOIN messages m ON m.thread_id = t.id
+    WHERE t.unread_count > 0
+    AND m.timestamp = (SELECT MAX(timestamp) FROM messages WHERE thread_id = t.id)
+    ORDER BY t.updated_at DESC
+  `).all();
+
+  // Attach unread message IDs to each thread
+  for (const thread of threads) {
+    const rows = db.prepare('SELECT message_id FROM unread_messages WHERE thread_id = ?').all(thread.id);
+    thread.unreadMessageIds = rows.map(r => r.message_id);
+  }
+
+  send(res, 200, { threads });
+}
+
+async function handleMarkMessagesRead(req, res, params) {
+  const body = await parseBody(req);
+  const db = getActiveDb();
+  const threadId = params.id;
+  const messageIds = body.messageIds;
+
+  if (!Array.isArray(messageIds) || messageIds.length === 0) {
+    return send(res, 400, { error: 'messageIds array required' });
+  }
+
+  const placeholders = messageIds.map(() => '?').join(',');
+  db.prepare(`DELETE FROM unread_messages WHERE thread_id = ? AND message_id IN (${placeholders})`).run(threadId, ...messageIds);
+
+  // Sync unread_count from actual unread_messages table
+  const remaining = syncThreadUnreadCount(db, threadId);
+
+  // Broadcast unread-update to ALL browser clients (so other tabs/devices sync)
+  const workspace = getWorkspaces().active;
+  gatewayClient.broadcastToBrowsers(JSON.stringify({
+    type: 'shellchat',
+    event: 'unread-update',
+    workspace,
+    threadId,
+    action: 'read',
+    messageIds,
+    unreadCount: remaining,
+    timestamp: Date.now()
+  }));
+
+  send(res, 200, { unread_count: remaining });
+}
+
+async function handleCreateThread(req, res) {
+  const body = await parseBody(req);
+  const db = getActiveDb();
+  const ws = getWorkspaces();
+  const id = body.id || uuid();
+  const now = Date.now();
+  const sessionKey = `agent:main:${ws.active}:chat:${id}`;
+
+  try {
+    db.prepare(
+      'INSERT INTO threads (id, session_key, title, created_at, updated_at) VALUES (?, ?, ?, ?, ?)'
+    ).run(id, sessionKey, 'New chat', now, now);
+  } catch (e) {
+    if (e.message.includes('UNIQUE constraint')) {
+      return sendError(res, 409, 'Thread already exists');
+    }
+    throw e;
+  }
+
+  const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(id);
+  send(res, 201, { thread });
+}
+
+function handleGetThread(req, res, params) {
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+  send(res, 200, { thread });
+}
+
+async function handleUpdateThread(req, res, params) {
+  const body = await parseBody(req);
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+
+  const fields = [];
+  const values = [];
+  if (body.title !== undefined) { fields.push('title = ?'); values.push(body.title); }
+  if (body.pinned !== undefined) { fields.push('pinned = ?'); values.push(body.pinned ? 1 : 0); }
+  if (body.pin_order !== undefined) { fields.push('pin_order = ?'); values.push(body.pin_order); }
+  if (body.sort_order !== undefined) { fields.push('sort_order = ?'); values.push(body.sort_order); }
+  if (body.model !== undefined) { fields.push('model = ?'); values.push(body.model); }
+  if (body.last_session_id !== undefined) { fields.push('last_session_id = ?'); values.push(body.last_session_id); }
+  if (body.unread_count !== undefined) { fields.push('unread_count = ?'); values.push(body.unread_count); }
+
+  if (fields.length > 0) {
+    fields.push('updated_at = ?');
+    values.push(Date.now());
+    values.push(params.id);
+    db.prepare(`UPDATE threads SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+  }
+
+  const updated = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+  send(res, 200, { thread: updated });
+}
+
+function handleDeleteThread(req, res, params) {
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+
+  // Delete from SQLite (CASCADE deletes messages)
+  db.prepare('DELETE FROM threads WHERE id = ?').run(params.id);
+
+  // Look up sessionId from SQLite or sessions.json as fallback
+  let sessionIdToDelete = thread.last_session_id;
+  if (!sessionIdToDelete) {
+    try {
+      const raw = fs.readFileSync(path.join(OPENCLAW_SESSIONS_DIR, 'sessions.json'), 'utf8');
+      const store = JSON.parse(raw);
+      const entry = store[thread.session_key];
+      if (entry?.sessionId) sessionIdToDelete = entry.sessionId;
+    } catch { /* ok */ }
+  }
+
+  // Clean gateway session (deletes .jsonl + sessions.json entry)
+  cleanGatewaySession(thread.session_key);
+
+  // If cleanGatewaySession didn't find it but we have a sessionId, delete transcript directly
+  if (sessionIdToDelete) {
+    const jsonlPath = path.join(OPENCLAW_SESSIONS_DIR, `${sessionIdToDelete}.jsonl`);
+    try { fs.unlinkSync(jsonlPath); } catch { /* ok */ }
+  }
+
+  // Delete uploaded files
+  const uploadDir = path.join(UPLOADS_DIR, params.id);
+  try { fs.rmSync(uploadDir, { recursive: true }); } catch { /* ok */ }
+
+  send(res, 200, { ok: true });
+}
+
+// --- Messages ---
+
+function handleGetMessages(req, res, params, query) {
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+
+  const limit = Math.min(parseInt(query.limit || '100', 10), 500);
+  const before = query.before ? parseInt(query.before, 10) : null;
+  const after = query.after ? parseInt(query.after, 10) : null;
+
+  let sql = 'SELECT * FROM messages WHERE thread_id = ?';
+  const sqlParams = [params.id];
+
+  if (before) {
+    sql += ' AND timestamp < ?';
+    sqlParams.push(before);
+  }
+  if (after) {
+    sql += ' AND timestamp > ?';
+    sqlParams.push(after);
+  }
+
+  // Count total matching for hasMore
+  const countSql = sql.replace('SELECT *', 'SELECT COUNT(*) as c');
+  const total = db.prepare(countSql).get(...sqlParams).c;
+
+  sql += ' ORDER BY timestamp DESC LIMIT ?';
+  sqlParams.push(limit + 1);
+
+  const rows = db.prepare(sql).all(...sqlParams);
+  const hasMore = rows.length > limit;
+  const messages = rows.slice(0, limit).reverse(); // Return chronological order
+
+  // Parse metadata JSON
+  for (const m of messages) {
+    if (m.metadata) {
+      try { m.metadata = JSON.parse(m.metadata); } catch { /* leave as string */ }
+    }
+  }
+
+  send(res, 200, { messages, hasMore });
+}
+
+async function handleCreateMessage(req, res, params) {
+  const body = await parseBody(req);
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+
+  if (!body.id || !body.role || body.content === undefined || !body.timestamp) {
+    return sendError(res, 400, 'Required: id, role, content, timestamp');
+  }
+
+  const metadata = body.metadata ? JSON.stringify(body.metadata) : null;
+
+  // Idempotent upsert: insert or update status if it changed
+  const existing = db.prepare('SELECT id, status FROM messages WHERE id = ?').get(body.id);
+  if (existing) {
+    // Only update if status changes
+    if (body.status && body.status !== existing.status) {
+      db.prepare('UPDATE messages SET status = ?, content = ?, metadata = ? WHERE id = ?')
+        .run(body.status, body.content, metadata, body.id);
+    }
+  } else {
+    db.prepare(
+      'INSERT INTO messages (id, thread_id, role, content, status, metadata, seq, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)'
+    ).run(body.id, params.id, body.role, body.content, body.status || 'sent', metadata, body.seq || null, body.timestamp, Date.now());
+
+    // Bump thread updated_at
+    db.prepare('UPDATE threads SET updated_at = ? WHERE id = ?').run(Date.now(), params.id);
+  }
+
+  const message = db.prepare('SELECT * FROM messages WHERE id = ?').get(body.id);
+  if (message && message.metadata) {
+    try { message.metadata = JSON.parse(message.metadata); } catch { /* ok */ }
+  }
+  send(res, existing ? 200 : 201, { message });
+}
+
+function handleDeleteMessage(req, res, params) {
+  const db = getActiveDb();
+  const msg = db.prepare('SELECT id FROM messages WHERE id = ? AND thread_id = ?').get(params.messageId, params.id);
+  if (!msg) return sendError(res, 404, 'Message not found');
+  db.prepare('DELETE FROM messages WHERE id = ?').run(params.messageId);
+  send(res, 200, { ok: true });
+}
+
+// --- Context Fill ---
+
+function handleContextFill(req, res, params) {
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+
+  const { preamble, method } = buildContextPreamble(db, params.id, thread.last_session_id);
+  send(res, 200, { preamble, method });
+}
+
+// --- Search ---
+
+function handleSearch(req, res, params, query) {
+  const db = getActiveDb();
+  const q = query.q || '';
+  if (!q) return send(res, 200, { results: [], total: 0 });
+
+  const page = parseInt(query.page || '1', 10);
+  const limit = Math.min(parseInt(query.limit || '20', 10), 100);
+  const offset = (page - 1) * limit;
+
+  // FTS5 search with snippet
+  const results = db.prepare(`
+    SELECT
+      m.id as messageId,
+      m.thread_id as threadId,
+      t.title as threadTitle,
+      m.role,
+      snippet(messages_fts, 0, '<mark>', '</mark>', '...', 40) as content,
+      m.timestamp
+    FROM messages_fts
+    JOIN messages m ON messages_fts.rowid = m.rowid
+    JOIN threads t ON m.thread_id = t.id
+    WHERE messages_fts MATCH ?
+    ORDER BY rank
+    LIMIT ? OFFSET ?
+  `).all(q, limit, offset);
+
+  const totalRow = db.prepare(`
+    SELECT COUNT(*) as c
+    FROM messages_fts
+    WHERE messages_fts MATCH ?
+  `).get(q);
+
+  send(res, 200, { results, total: totalRow.c });
+}
+
+// --- Export ---
+
+function handleExport(req, res) {
+  const db = getActiveDb();
+  const ws = getWorkspaces();
+  const threads = db.prepare('SELECT * FROM threads ORDER BY updated_at DESC').all();
+  const data = {
+    workspace: ws.active,
+    exportedAt: Date.now(),
+    threads: threads.map(t => {
+      const messages = db.prepare(
+        'SELECT * FROM messages WHERE thread_id = ? ORDER BY timestamp ASC'
+      ).all(t.id);
+      // Parse metadata
+      for (const m of messages) {
+        if (m.metadata) {
+          try { m.metadata = JSON.parse(m.metadata); } catch { /* ok */ }
+        }
+      }
+      return { ...t, messages };
+    }),
+  };
+  send(res, 200, data);
+}
+
+// --- Import ---
+
+async function handleImport(req, res) {
+  const body = await parseBody(req);
+  const db = getActiveDb();
+  const ws = getWorkspaces();
+
+  if (!body.threads || !Array.isArray(body.threads)) {
+    return sendError(res, 400, 'Expected { threads: [...] }');
+  }
+
+  let threadsImported = 0;
+  let messagesImported = 0;
+
+  const insertThread = db.prepare(
+    'INSERT OR IGNORE INTO threads (id, session_key, title, pinned, pin_order, model, last_session_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)'
+  );
+  const insertMsg = db.prepare(
+    'INSERT OR IGNORE INTO messages (id, thread_id, role, content, status, metadata, seq, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)'
+  );
+
+  const importAll = db.transaction(() => {
+    for (const t of body.threads) {
+      if (!t.id) continue;
+      const sessionKey = t.session_key || `agent:main:${ws.active}:chat:${t.id}`;
+      const result = insertThread.run(
+        t.id, sessionKey, t.title || 'Imported chat',
+        t.pinned || 0, t.pin_order || 0, t.model || null,
+        t.last_session_id || null, t.created_at || Date.now(), t.updated_at || Date.now()
+      );
+      if (result.changes > 0) threadsImported++;
+
+      const messages = t.messages || [];
+      for (const m of messages) {
+        if (!m.id || !m.role) continue;
+        const metadata = m.metadata ? (typeof m.metadata === 'string' ? m.metadata : JSON.stringify(m.metadata)) : null;
+        const r = insertMsg.run(
+          m.id, t.id, m.role, m.content || '', m.status || 'sent',
+          metadata, m.seq || null, m.timestamp || Date.now(), m.created_at || Date.now()
+        );
+        if (r.changes > 0) messagesImported++;
+      }
+    }
+  });
+
+  importAll();
+  send(res, 200, { ok: true, threadsImported, messagesImported });
+}
+
+// --- File Upload ---
+
+async function handleUpload(req, res, params) {
+  const db = getActiveDb();
+  const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id);
+  if (!thread) return sendError(res, 404, 'Thread not found');
+
+  const files = await parseMultipart(req);
+  const threadUploadDir = path.join(UPLOADS_DIR, params.id);
+  fs.mkdirSync(threadUploadDir, { recursive: true });
+
+  const savedFiles = [];
+  for (const file of files) {
+    const fileId = uuid();
+    const ext = path.extname(file.filename) || '';
+    const savedName = fileId + ext;
+    const filePath = path.join(threadUploadDir, savedName);
+    fs.writeFileSync(filePath, file.data);
+    savedFiles.push({
+      id: fileId,
+      filename: file.filename,
+      path: `/api/uploads/${params.id}/${fileId}${ext}`,
+      mimeType: file.mimeType,
+      size: file.data.length,
+    });
+  }
+
+  send(res, 200, { files: savedFiles });
+}
+
+function handleServeUpload(req, res, params) {
+  const filePath = path.join(UPLOADS_DIR, params.threadId, params.fileId);
+  // Also try with common extensions
+  let resolved = filePath;
+  if (!fs.existsSync(resolved)) {
+    // Scan directory for file starting with fileId
+    const dir = path.join(UPLOADS_DIR, params.threadId);
+    try {
+      const entries = fs.readdirSync(dir);
+      const match = entries.find(e => e.startsWith(params.fileId.replace(/\.[^.]+$/, '')));
+      if (match) resolved = path.join(dir, match);
+    } catch { /* dir not found */ }
+  }
+
+  if (!fs.existsSync(resolved)) {
+    return sendError(res, 404, 'File not found');
+  }
+
+  const ext = path.extname(resolved).toLowerCase();
+  const mimeTypes = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf', '.txt': 'text/plain', '.json': 'application/json',
+  };
+  const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+  const stat = fs.statSync(resolved);
+  res.writeHead(200, {
+    'Content-Type': contentType,
+    'Content-Length': stat.size,
+    'Cache-Control': 'public, max-age=86400',
+    'Access-Control-Allow-Origin': '*',
+  });
+  fs.createReadStream(resolved).pipe(res);
+}
+
+// ─── Intelligence (per-thread, per-workspace) ──────────────────────────────
+
+const INTELLIGENCE_DIR = path.join(DATA_DIR, 'intelligence');
+
+function getIntelligencePath(threadId) {
+  const workspace = getWorkspaces().active;
+  return path.join(INTELLIGENCE_DIR, workspace, `${threadId}.json`);
+}
+
+function handleGetIntelligence(req, res, params) {
+  const filePath = getIntelligencePath(params.id);
+  if (!fs.existsSync(filePath)) {
+    return send(res, 200, { versions: [], currentVersion: -1 });
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return send(res, 200, data);
+  } catch (err) {
+    return send(res, 200, { versions: [], currentVersion: -1 });
+  }
+}
+
+async function handleSaveIntelligence(req, res, params) {
+  const body = await parseBody(req);
+  const filePath = getIntelligencePath(params.id);
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // body should have { versions, currentVersion }
+  const data = {
+    versions: body.versions || [],
+    currentVersion: body.currentVersion ?? -1,
+    updatedAt: Date.now()
+  };
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+  return send(res, 200, data);
+}
+
+// ─── File Serving (restricted to ~/.openclaw/media/) ────────────────────────
+
+const ALLOWED_FILE_DIRS = [
+  path.join(HOME, '.openclaw', 'media'),
+  path.join(HOME, '.openclaw', 'workspace'),
+  '/tmp',
+];
+
+function handleServeFile(req, res, query) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+
+  // Resolve to prevent traversal attacks
+  const resolved = path.resolve(filePath);
+
+  // Security: only serve files from allowed directories
+  const allowed = ALLOWED_FILE_DIRS.some(dir => resolved.startsWith(dir + '/') || resolved === dir);
+  if (!allowed) {
+    return sendError(res, 403, 'Access denied: path not in allowed directories');
+  }
+
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+    return sendError(res, 404, 'File not found');
+  }
+
+  const ext = path.extname(resolved).toLowerCase();
+  const mimeTypes = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf', '.txt': 'text/plain', '.json': 'application/json',
+    '.md': 'text/markdown', '.csv': 'text/csv', '.xml': 'text/xml',
+    '.html': 'text/html', '.css': 'text/css', '.js': 'text/javascript',
+    '.py': 'text/x-python', '.sh': 'text/x-shellscript',
+    '.yaml': 'text/yaml', '.yml': 'text/yaml', '.toml': 'text/toml',
+    '.zip': 'application/zip', '.gz': 'application/gzip', '.tar': 'application/x-tar',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+    '.mp4': 'video/mp4', '.webm': 'video/webm',
+  };
+  const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+  const stat = fs.statSync(resolved);
+  res.writeHead(200, {
+    'Content-Type': contentType,
+    'Content-Length': stat.size,
+    'Cache-Control': 'public, max-age=86400',
+    'Access-Control-Allow-Origin': '*',
+  });
+  fs.createReadStream(resolved).pipe(res);
+}
+
+// ─── Workspace File Browser ─────────────────────────────────────────────────
+
+const WORKSPACE_ROOT = HOME;
+
+function handleWorkspaceList(req, res, query) {
+  const reqPath = query.path || '~/.openclaw/workspace';
+  const depth = parseInt(query.depth || '2', 10);
+  const showHidden = query.hidden === '1' || query.hidden === 'true';
+
+  // Resolve ~ to HOME
+  const resolved = path.resolve(reqPath.replace(/^~/, HOME));
+
+  // Security: only allow listing under home directory
+  if (!resolved.startsWith(HOME)) {
+    return sendError(res, 403, 'Access denied');
+  }
+
+  if (!fs.existsSync(resolved)) {
+    return sendError(res, 404, 'Path not found');
+  }
+
+  const files = [];
+
+  function walk(dir, currentDepth) {
+    if (currentDepth > depth) return;
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        // Skip hidden files unless showHidden (always show .openclaw)
+        if (entry.name.startsWith('.') && entry.name !== '.openclaw' && !showHidden) continue;
+        if (entry.name === 'node_modules') continue;
+
+        const fullPath = path.join(dir, entry.name);
+        const isDir = entry.isDirectory();
+        files.push({
+          path: fullPath + (isDir ? '/' : ''),
+          type: isDir ? 'dir' : 'file',
+          name: entry.name,
+          size: isDir ? 0 : (() => { try { return fs.statSync(fullPath).size; } catch { return 0; } })(),
+        });
+        if (isDir) walk(fullPath, currentDepth + 1);
+      }
+    } catch { /* permission denied, etc. */ }
+  }
+
+  // Add root entry
+  files.unshift({ path: resolved + '/', type: 'dir', name: path.basename(resolved), size: 0 });
+  walk(resolved, 1);
+
+  send(res, 200, { files, cwd: resolved });
+}
+
+function handleWorkspaceFileRead(req, res, query) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+
+  const resolved = path.resolve(filePath.replace(/^~/, HOME));
+
+  // Security: only allow reading under home directory
+  if (!resolved.startsWith(HOME)) {
+    return sendError(res, 403, 'Access denied');
+  }
+
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+    return sendError(res, 404, 'File not found');
+  }
+
+  // Limit file size to 1MB
+  const stat = fs.statSync(resolved);
+  if (stat.size > 1024 * 1024) {
+    return sendError(res, 413, 'File too large (max 1MB)');
+  }
+
+  const content = fs.readFileSync(resolved, 'utf8');
+  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end(content);
+}
+
+async function handleWorkspaceFileWrite(req, res, query) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+
+  const resolved = path.resolve(filePath.replace(/^~/, HOME));
+
+  // Security: only allow writing under workspace
+  if (!resolved.startsWith(WORKSPACE_ROOT)) {
+    return sendError(res, 403, 'Can only write to workspace directory');
+  }
+
+  // Read body as text
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const content = Buffer.concat(chunks).toString('utf8');
+
+  // Ensure parent directory exists
+  const dir = path.dirname(resolved);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  fs.writeFileSync(resolved, content, 'utf8');
+  send(res, 200, { ok: true });
+}
+
+async function handleWorkspaceUpload(req, res, query) {
+  const targetDir = query.path;
+  if (!targetDir) return sendError(res, 400, 'Missing path parameter');
+
+  const resolved = path.resolve(targetDir.replace(/^~/, HOME));
+
+  // Security: only allow uploading under home directory
+  if (!resolved.startsWith(HOME)) {
+    return sendError(res, 403, 'Access denied');
+  }
+
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    return sendError(res, 404, 'Target directory not found');
+  }
+
+  // Parse multipart form data manually (no dependency needed for simple case)
+  const contentType = req.headers['content-type'] || '';
+  if (!contentType.includes('multipart/form-data')) {
+    return sendError(res, 400, 'Expected multipart/form-data');
+  }
+
+  const boundary = contentType.split('boundary=')[1];
+  if (!boundary) return sendError(res, 400, 'Missing boundary');
+
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const body = Buffer.concat(chunks);
+
+  // Parse multipart parts
+  const boundaryBuf = Buffer.from('--' + boundary);
+  const uploaded = [];
+  let start = 0;
+
+  while (true) {
+    const idx = body.indexOf(boundaryBuf, start);
+    if (idx === -1) break;
+
+    if (start > 0) {
+      // Extract the part between previous boundary and this one
+      const partData = body.slice(start, idx - 2); // -2 for \r\n before boundary
+      const headerEnd = partData.indexOf('\r\n\r\n');
+      if (headerEnd !== -1) {
+        const headerStr = partData.slice(0, headerEnd).toString('utf8');
+        const fileContent = partData.slice(headerEnd + 4);
+
+        const filenameMatch = headerStr.match(/filename="([^"]+)"/);
+        if (filenameMatch && fileContent.length > 0) {
+          const filename = path.basename(filenameMatch[1]); // sanitize
+          const filePath = path.join(resolved, filename);
+
+          // Don't overwrite — add suffix if exists
+          let finalPath = filePath;
+          let counter = 1;
+          while (fs.existsSync(finalPath)) {
+            const ext = path.extname(filename);
+            const base = path.basename(filename, ext);
+            finalPath = path.join(resolved, `${base} (${counter})${ext}`);
+            counter++;
+          }
+
+          fs.writeFileSync(finalPath, fileContent);
+          uploaded.push({ name: path.basename(finalPath), size: fileContent.length });
+        }
+      }
+    }
+
+    start = idx + boundaryBuf.length + 2; // +2 for \r\n after boundary
+  }
+
+  send(res, 200, { ok: true, uploaded });
+}
+
+// ─── Memory (configurable backend) ──────────────────────────────────────────
+
+function discoverMemoryConfig() {
+  // Priority: env vars → openclaw.json → defaults
+  const defaults = { provider: 'qdrant', host: 'localhost', port: 6333, collection: null };
+
+  // Try reading openclaw.json
+  let oc = null;
+  const candidates = [
+    path.join(os.homedir(), '.openclaw', 'openclaw.json'),
+    '/etc/openclaw/openclaw.json'
+  ];
+  for (const cfgPath of candidates) {
+    try {
+      oc = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      break;
+    } catch {}
+  }
+
+  let cfg = { ...defaults };
+
+  if (oc) {
+    const memSlot = oc.plugins?.slots?.memory;
+    const vs = memSlot ? oc.plugins?.entries?.[memSlot]?.config?.oss?.vectorStore : null;
+    if (vs) {
+      if (vs.provider) cfg.provider = vs.provider;
+      if (vs.config?.host) cfg.host = vs.config.host;
+      if (vs.config?.port) cfg.port = vs.config.port;
+      if (vs.config?.collectionName) cfg.collection = vs.config.collectionName;
+      // Postgres-specific fields
+      if (vs.config?.user) cfg.pgUser = vs.config.user;
+      if (vs.config?.password) cfg.pgPassword = vs.config.password;
+      if (vs.config?.dbname) cfg.pgDbName = vs.config.dbname;
+    }
+
+    // Derive workspace dir from openclaw.json
+    const wsDir = oc.agents?.defaults?.workspace;
+    if (wsDir) cfg.workspaceDir = wsDir;
+  }
+
+  // Env var overrides (MEMORY_* take priority, then Qdrant-specific fallbacks)
+  if (process.env.MEMORY_PROVIDER) cfg.provider = process.env.MEMORY_PROVIDER;
+  if (process.env.MEMORY_HOST || process.env.QDRANT_HOST) cfg.host = process.env.MEMORY_HOST || process.env.QDRANT_HOST;
+  if (process.env.MEMORY_PORT || process.env.QDRANT_PORT) cfg.port = parseInt(process.env.MEMORY_PORT || process.env.QDRANT_PORT, 10);
+  if (process.env.MEMORY_COLLECTION || process.env.QDRANT_COLLECTION) cfg.collection = process.env.MEMORY_COLLECTION || process.env.QDRANT_COLLECTION;
+  if (process.env.MEMORY_PG_URL) cfg.pgUrl = process.env.MEMORY_PG_URL;
+  // QDRANT_URL (e.g. "http://myhost:6333") — parse host and port from it
+  if (process.env.QDRANT_URL && !process.env.MEMORY_HOST) {
+    try {
+      const u = new URL(process.env.QDRANT_URL);
+      cfg.host = u.hostname;
+      if (u.port) cfg.port = parseInt(u.port, 10);
+    } catch {}
+  }
+
+  if (!cfg.workspaceDir) {
+    cfg.workspaceDir = path.join(os.homedir(), '.openclaw', 'workspace');
+  }
+
+  return cfg;
+}
+
+const MEMORY_CONFIG = discoverMemoryConfig();
+
+// Auto-detect Qdrant collection if not explicitly configured
+async function autoDetectQdrantCollection(config) {
+  if (config.collection) return config.collection;
+  const baseUrl = `http://${config.host}:${config.port}`;
+  try {
+    const r = await fetch(`${baseUrl}/collections`, { signal: AbortSignal.timeout(3000) });
+    const data = await r.json();
+    const collections = (data.result?.collections || []).map(c => c.name);
+    const found = collections.find(name => !name.includes('migration'));
+    if (found) {
+      console.log(`Memory: auto-detected Qdrant collection "${found}"`);
+      return found;
+    }
+  } catch {}
+  console.log('Memory: Qdrant unreachable or no collections, falling back to "memories"');
+  return 'memories';
+}
+
+// ─── Memory Providers ─────────────────────────────────────────────────────────
+
+function createQdrantProvider(config) {
+  const baseUrl = `http://${config.host}:${config.port}`;
+  let collection = config.collection; // may be null until init()
+
+  return {
+    name: 'qdrant',
+    config,
+    async init() {
+      collection = await autoDetectQdrantCollection(config);
+      config.collection = collection;
+    },
+    async list(limit, offset) {
+      const body = { limit, with_payload: true, with_vector: false };
+      if (offset) body.offset = offset;
+      const r = await fetch(`${baseUrl}/collections/${collection}/points/scroll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      const data = await r.json();
+      const points = data.result?.points || [];
+      return {
+        memories: points.map(p => ({ id: p.id, ...p.payload })),
+        next_offset: data.result?.next_page_offset || null,
+      };
+    },
+    async search(query) {
+      const q = query.toLowerCase();
+      const matches = [];
+      let offset = null;
+      do {
+        const body = { limit: 100, with_payload: true, with_vector: false };
+        if (offset) body.offset = offset;
+        const r = await fetch(`${baseUrl}/collections/${collection}/points/scroll`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        });
+        const data = await r.json();
+        const points = data.result?.points || [];
+        for (const p of points) {
+          if ((p.payload?.data || '').toLowerCase().includes(q)) {
+            matches.push({ id: p.id, ...p.payload });
+          }
+        }
+        offset = data.result?.next_page_offset || null;
+      } while (offset);
+      return { memories: matches, next_offset: null };
+    },
+    async update(id, newData) {
+      const r = await fetch(`${baseUrl}/collections/${collection}/points/payload`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ points: [id], payload: { data: newData } }),
+      });
+      const data = await r.json();
+      if (data.status?.error) throw new Error(data.status.error);
+      return data.result;
+    },
+    async delete(id) {
+      const r = await fetch(`${baseUrl}/collections/${collection}/points/delete`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ points: [id] }),
+      });
+      const data = await r.json();
+      return data.result;
+    },
+    async status() {
+      try {
+        const r = await fetch(`${baseUrl}/collections/${collection}`, { signal: AbortSignal.timeout(3000) });
+        const data = await r.json();
+        return { reachable: true, pointsCount: data.result?.points_count ?? null };
+      } catch {
+        return { reachable: false };
+      }
+    },
+  };
+}
+
+function createPgProvider(config) {
+  // Lazy-load pg — no crash if not installed and user runs Qdrant
+  // NOTE: Postgres schema based on mem0 SDK pgvector patterns; needs verification against a real setup.
+  let _pool = null;
+  const table = config.collection || 'memories';
+
+  async function getPool() {
+    if (_pool) return _pool;
+    let pg;
+    try {
+      pg = await import('pg');
+    } catch {
+      throw new Error('pg package not installed. Run: npm install pg');
+    }
+    const Pool = pg.default?.Pool || pg.Pool;
+    if (config.pgUrl) {
+      _pool = new Pool({ connectionString: config.pgUrl });
+    } else {
+      _pool = new Pool({
+        host: config.host,
+        port: config.port || 5432,
+        user: config.pgUser || 'mem0',
+        password: config.pgPassword || '',
+        database: config.pgDbName || 'mem0',
+      });
+    }
+    return _pool;
+  }
+
+  return {
+    name: 'postgres',
+    config,
+    async init() { /* pool created lazily on first query */ },
+    async list(limit, offset) {
+      const pool = await getPool();
+      const offsetVal = offset ? parseInt(offset, 10) : 0;
+      const { rows } = await pool.query(
+        `SELECT id, payload FROM ${table} ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
+        [limit, offsetVal]
+      );
+      return {
+        memories: rows.map(r => ({ id: r.id, ...(typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) })),
+        next_offset: rows.length === limit ? offsetVal + limit : null,
+      };
+    },
+    async search(query) {
+      const pool = await getPool();
+      const { rows } = await pool.query(
+        `SELECT id, payload FROM ${table} WHERE payload->>'data' ILIKE $1 LIMIT 100`,
+        [`%${query}%`]
+      );
+      return {
+        memories: rows.map(r => ({ id: r.id, ...(typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload) })),
+        next_offset: null,
+      };
+    },
+    async update(id, newData) {
+      const pool = await getPool();
+      const { rowCount } = await pool.query(
+        `UPDATE ${table} SET payload = jsonb_set(payload, '{data}', $1::jsonb) WHERE id = $2`,
+        [JSON.stringify(newData), id]
+      );
+      if (rowCount === 0) throw new Error('Memory not found');
+      return { updated: true };
+    },
+    async delete(id) {
+      const pool = await getPool();
+      await pool.query(`DELETE FROM ${table} WHERE id = $1`, [id]);
+      return { deleted: true };
+    },
+    async status() {
+      try {
+        const pool = await getPool();
+        const { rows } = await pool.query(`SELECT COUNT(*) as count FROM ${table}`);
+        return { reachable: true, pointsCount: parseInt(rows[0].count, 10) };
+      } catch (err) {
+        return { reachable: false, error: err.message };
+      }
+    },
+  };
+}
+
+function createMemoryProvider(config) {
+  if (config.provider === 'postgres' || config.provider === 'pgvector')
+    return createPgProvider(config);
+  return createQdrantProvider(config);
+}
+
+const memoryProvider = createMemoryProvider(MEMORY_CONFIG);
+// Initialize provider (auto-detect collection etc.) — runs async at startup
+memoryProvider.init().catch(err => console.error('Memory provider init error:', err.message));
+
+console.log(`Memory: provider=${MEMORY_CONFIG.provider} host=${MEMORY_CONFIG.host}:${MEMORY_CONFIG.port} collection=${MEMORY_CONFIG.collection || '(auto-detect)'}`);
+
+// ─── Memory Handlers ────────────────────────────────────────────────────────
+
+async function handleMemoryList(req, res, query) {
+  const limit = Math.min(parseInt(query.limit) || 20, 100);
+  try {
+    const result = await memoryProvider.list(limit, query.offset || null);
+    send(res, 200, result);
+  } catch (err) {
+    send(res, 502, { error: `Failed to reach ${memoryProvider.name}`, detail: err.message });
+  }
+}
+
+async function handleMemorySearch(req, res, query) {
+  const q = (query.query || '').toLowerCase().trim();
+  if (!q) return send(res, 400, { error: 'Missing query parameter' });
+  try {
+    const result = await memoryProvider.search(q);
+    send(res, 200, result);
+  } catch (err) {
+    send(res, 502, { error: `Failed to reach ${memoryProvider.name}`, detail: err.message });
+  }
+}
+
+const MEMORY_FILES_DIR = path.join(MEMORY_CONFIG.workspaceDir, 'memory');
+
+function parseMemoryFiles() {
+  const memories = [];
+  let files;
+  try {
+    files = fs.readdirSync(MEMORY_FILES_DIR);
+  } catch { return memories; }
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const filePath = path.join(MEMORY_FILES_DIR, file);
+    let stat;
+    try { stat = fs.statSync(filePath); } catch { continue; }
+    if (!stat.isFile()) continue;
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const basename = file.replace(/\.md$/, '');
+
+    // Extract date from filename (e.g. 2026-02-14 or 2026-02-09-topic-name)
+    const dateMatch = basename.match(/^(\d{4}-\d{2}-\d{2})/);
+    const fileDate = dateMatch ? dateMatch[1] : null;
+
+    // Split by ## headings into sections
+    const sections = content.split(/^(?=## )/m);
+    for (const section of sections) {
+      const trimmed = section.trim();
+      if (!trimmed) continue;
+
+      // Extract heading
+      const headingMatch = trimmed.match(/^##\s+(.+)/);
+      const heading = headingMatch ? headingMatch[1].trim() : null;
+      // Body is everything after heading line (or whole section if top-level)
+      const body = headingMatch ? trimmed.slice(trimmed.indexOf('\n') + 1).trim() : trimmed;
+
+      // Skip if it's just the top-level # heading with no real content
+      if (!heading && body.match(/^#\s+/) && body.split('\n').length <= 2) continue;
+
+      const title = heading || basename;
+      const id = `file:${basename}:${title}`;
+      memories.push({
+        id,
+        source: 'file',
+        file: basename,
+        title,
+        data: heading ? `**${title}**\n${body}` : body,
+        createdAt: fileDate ? `${fileDate}T00:00:00Z` : stat.mtime.toISOString(),
+      });
+    }
+  }
+
+  // Also scan subdirectories one level deep
+  try {
+    for (const entry of fs.readdirSync(MEMORY_FILES_DIR)) {
+      const subdir = path.join(MEMORY_FILES_DIR, entry);
+      if (!fs.statSync(subdir).isDirectory()) continue;
+      for (const file of fs.readdirSync(subdir)) {
+        if (!file.endsWith('.md')) continue;
+        const filePath = path.join(subdir, file);
+        const content = fs.readFileSync(filePath, 'utf8');
+        const basename = file.replace(/\.md$/, '');
+        const relPath = `${entry}/${basename}`;
+        const stat = fs.statSync(filePath);
+
+        memories.push({
+          id: `file:${relPath}`,
+          source: 'file',
+          file: relPath,
+          title: basename,
+          data: content.trim(),
+          createdAt: stat.mtime.toISOString(),
+        });
+      }
+    }
+  } catch { /* ignore */ }
+
+  return memories;
+}
+
+function handleMemoryFiles(req, res, query) {
+  const q = (query.query || '').toLowerCase().trim();
+  const memories = parseMemoryFiles();
+  const filtered = q
+    ? memories.filter(m => m.data.toLowerCase().includes(q) || m.title.toLowerCase().includes(q))
+    : memories;
+  // Sort newest first
+  filtered.sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+  send(res, 200, { memories: filtered });
+}
+
+async function handleMemoryUpdate(req, res, params) {
+  const id = params.id;
+  try {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    const body = JSON.parse(Buffer.concat(chunks).toString());
+    const newData = (body.data || '').trim();
+    if (!newData) return send(res, 400, { error: 'Missing data field' });
+
+    const result = await memoryProvider.update(id, newData);
+    send(res, 200, { ok: true, result });
+  } catch (err) {
+    send(res, 502, { error: 'Failed to update memory', detail: err.message });
+  }
+}
+
+async function handleMemoryDelete(req, res, params) {
+  const id = params.id;
+  try {
+    const result = await memoryProvider.delete(id);
+    send(res, 200, { ok: true, result });
+  } catch (err) {
+    send(res, 502, { error: `Failed to reach ${memoryProvider.name}`, detail: err.message });
+  }
+}
+
+async function handleMemoryStatus(req, res) {
+  const status = await memoryProvider.status();
+  const filesExist = fs.existsSync(MEMORY_FILES_DIR);
+  send(res, 200, {
+    provider: memoryProvider.name,
+    host: MEMORY_CONFIG.host,
+    port: MEMORY_CONFIG.port,
+    collection: MEMORY_CONFIG.collection,
+    backend: status,
+    memoryFilesDir: MEMORY_FILES_DIR,
+    memoryFilesDirExists: filesExist,
+  });
+}
+
+// ─── Router ─────────────────────────────────────────────────────────────────
+
+// ─── Speech-to-text (Whisper API proxy) ─────────────────────────────────────
+
+async function handleTranscribe(req, res) {
+  try {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    const audioBuffer = Buffer.concat(chunks);
+
+    if (audioBuffer.length === 0) return send(res, 400, { error: 'No audio data' });
+    if (audioBuffer.length > 25 * 1024 * 1024) return send(res, 400, { error: 'Audio too large (max 25MB)' });
+
+    // Read OpenAI API key from OpenClaw config
+    let apiKey;
+    try {
+      const ocConfig = JSON.parse(fs.readFileSync(
+        path.join(os.homedir(), '.openclaw', 'openclaw.json'), 'utf8'));
+      apiKey = ocConfig?.skills?.entries?.['openai-whisper-api']?.apiKey;
+    } catch {}
+    if (!apiKey) apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) return send(res, 500, { error: 'No OpenAI API key configured' });
+
+    const contentType = req.headers['content-type'] || 'audio/webm';
+    const ext = contentType.includes('wav') ? 'wav'
+      : contentType.includes('mp4') || contentType.includes('m4a') ? 'm4a'
+      : contentType.includes('ogg') ? 'ogg' : 'webm';
+
+    const boundary = '----WhisperBoundary' + Date.now();
+    const parts = [
+      `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="audio.${ext}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+      audioBuffer,
+      `\r\n--${boundary}\r\nContent-Disposition: form-data; name="model"\r\n\r\nwhisper-1\r\n`,
+      `--${boundary}\r\nContent-Disposition: form-data; name="response_format"\r\n\r\njson\r\n`,
+      `--${boundary}--\r\n`
+    ];
+    const body = Buffer.concat(parts.map(p => typeof p === 'string' ? Buffer.from(p) : p));
+
+    const resp = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+      },
+      body
+    });
+
+    if (!resp.ok) {
+      const errText = await resp.text();
+      console.error('Whisper API error:', resp.status, errText);
+      return send(res, 502, { error: `Whisper API error: ${resp.status}` });
+    }
+
+    const result = await resp.json();
+    return send(res, 200, { text: result.text || '' });
+  } catch (err) {
+    console.error('Transcribe error:', err);
+    return send(res, 500, { error: err.message });
+  }
+}
+
+async function handleRequest(req, res) {
+  // Parse URL and query string
+  const [urlPath, queryString] = (req.url || '/').split('?');
+  const query = {};
+  if (queryString) {
+    for (const pair of queryString.split('&')) {
+      const [k, v] = pair.split('=');
+      if (k) query[decodeURIComponent(k)] = decodeURIComponent(v || '');
+    }
+  }
+  const method = req.method;
+
+  // CORS preflight
+  if (method === 'OPTIONS') {
+    setCors(res);
+    res.writeHead(204);
+    return res.end();
+  }
+
+  // Serve static assets (no auth — browser authenticates via WS/API headers)
+  if (method === 'GET' && !urlPath.startsWith('/api/')) {
+    const STATIC_FILES = {
+      '/': 'index.html',
+      '/index.html': 'index.html',
+      '/app.js': 'app.js',
+      '/style.css': 'style.css',
+      '/error-handler.js': 'error-handler.js',
+      '/manifest.json': 'manifest.json',
+      '/favicon.ico': 'favicon.ico',
+    };
+    const fileName = STATIC_FILES[urlPath];
+    // Also serve /icons/*, /lib/*, /frontend/*, and /config.js
+    const isIcon = urlPath.startsWith('/icons/');
+    const isLib = urlPath.startsWith('/lib/');
+    const isFrontend = urlPath.startsWith('/frontend/');
+    const isConfig = urlPath === '/config.js';
+    const staticPath = fileName ? path.join(__dirname, fileName)
+      : (isIcon || isLib || isFrontend || isConfig) ? path.join(__dirname, urlPath.slice(1))
+      : null;
+    if (staticPath && fs.existsSync(staticPath) && fs.statSync(staticPath).isFile()) {
+      const ext = path.extname(staticPath).toLowerCase();
+      const mimeMap = {
+        '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css',
+        '.json': 'application/json', '.ico': 'image/x-icon',
+        '.png': 'image/png', '.svg': 'image/svg+xml',
+      };
+      const ct = mimeMap[ext] || 'application/octet-stream';
+      const stat = fs.statSync(staticPath);
+      res.writeHead(200, {
+        'Content-Type': ct,
+        'Content-Length': stat.size,
+        'Cache-Control': ext === '.html' ? 'no-cache' : 'public, max-age=3600',
+      });
+      return fs.createReadStream(staticPath).pipe(res);
+    }
+  }
+
+  // Serve uploaded files (no auth required — files are accessed by URL)
+  let p;
+  if ((p = matchRoute(method, urlPath, 'GET /api/uploads/:threadId/:fileId'))) {
+    return handleServeUpload(req, res, p);
+  }
+
+  // Auth check for all other routes
+  if (!checkAuth(req, res)) return;
+
+  try {
+    // --- File serving (absolute paths from gateway) ---
+    if (method === 'GET' && urlPath === '/api/file') {
+      return handleServeFile(req, res, query);
+    }
+
+    // --- Workspace file browser ---
+    if (method === 'GET' && urlPath === '/api/workspace') {
+      return handleWorkspaceList(req, res, query);
+    }
+    if (method === 'GET' && urlPath === '/api/workspace/file') {
+      return handleWorkspaceFileRead(req, res, query);
+    }
+    if (method === 'PUT' && urlPath === '/api/workspace/file') {
+      return await handleWorkspaceFileWrite(req, res, query);
+    }
+    if (method === 'POST' && urlPath === '/api/workspace/upload') {
+      return await handleWorkspaceUpload(req, res, query);
+    }
+
+    // --- Memory (configurable backend) ---
+    if (method === 'GET' && urlPath === '/api/memory/status') {
+      return await handleMemoryStatus(req, res);
+    }
+    if (method === 'GET' && urlPath === '/api/memory/list') {
+      return await handleMemoryList(req, res, query);
+    }
+    if (method === 'GET' && urlPath === '/api/memory/search') {
+      return await handleMemorySearch(req, res, query);
+    }
+    if (method === 'GET' && urlPath === '/api/memory/files') {
+      return handleMemoryFiles(req, res, query);
+    }
+    if ((p = matchRoute(method, urlPath, 'PUT /api/memory/:id'))) {
+      return await handleMemoryUpdate(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'DELETE /api/memory/:id'))) {
+      return await handleMemoryDelete(req, res, p);
+    }
+
+    // --- User settings ---
+    if (method === 'GET' && urlPath === '/api/settings') {
+      return handleGetSettings(req, res);
+    }
+    if (method === 'PUT' && urlPath === '/api/settings') {
+      return await handleSaveSettings(req, res);
+    }
+
+    // --- Speech-to-text ---
+    if (method === 'POST' && urlPath === '/api/transcribe') {
+      return await handleTranscribe(req, res);
+    }
+
+    // --- Workspaces ---
+    if (method === 'GET' && urlPath === '/api/workspaces') {
+      return handleGetWorkspaces(req, res);
+    }
+    if (method === 'POST' && urlPath === '/api/workspaces') {
+      return await handleCreateWorkspace(req, res);
+    }
+    if ((p = matchRoute(method, urlPath, 'PATCH /api/workspaces/:name'))) {
+      return await handleUpdateWorkspace(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'DELETE /api/workspaces/:name'))) {
+      return handleDeleteWorkspace(req, res, p);
+    }
+    if (method === 'POST' && urlPath === '/api/workspaces/reorder') {
+      return await handleReorderWorkspaces(req, res);
+    }
+    if ((p = matchRoute(method, urlPath, 'POST /api/workspaces/:name/activate'))) {
+      return handleActivateWorkspace(req, res, p);
+    }
+
+    // --- Threads ---
+    if (method === 'GET' && urlPath === '/api/threads') {
+      return handleGetThreads(req, res, {}, query);
+    }
+    if (method === 'GET' && urlPath === '/api/threads/unread') {
+      return handleGetUnreadThreads(req, res);
+    }
+    if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/mark-read'))) {
+      return await handleMarkMessagesRead(req, res, p);
+    }
+    if (method === 'POST' && urlPath === '/api/threads') {
+      return await handleCreateThread(req, res);
+    }
+    // Thread-specific routes (must check more specific paths first)
+    if ((p = matchRoute(method, urlPath, 'GET /api/threads/:id/messages'))) {
+      return handleGetMessages(req, res, p, query);
+    }
+    if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/messages'))) {
+      return await handleCreateMessage(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'DELETE /api/threads/:id/messages/:messageId'))) {
+      return handleDeleteMessage(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/context-fill'))) {
+      return handleContextFill(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/upload'))) {
+      return await handleUpload(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'GET /api/threads/:id/intelligence'))) {
+      return handleGetIntelligence(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/intelligence'))) {
+      return await handleSaveIntelligence(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'GET /api/threads/:id'))) {
+      return handleGetThread(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'PATCH /api/threads/:id'))) {
+      return await handleUpdateThread(req, res, p);
+    }
+    if ((p = matchRoute(method, urlPath, 'DELETE /api/threads/:id'))) {
+      return handleDeleteThread(req, res, p);
+    }
+
+    // --- Search ---
+    if (method === 'GET' && urlPath === '/api/search') {
+      return handleSearch(req, res, {}, query);
+    }
+
+    // --- Export / Import ---
+    if (method === 'GET' && urlPath === '/api/export') {
+      return handleExport(req, res);
+    }
+    if (method === 'POST' && urlPath === '/api/import') {
+      return await handleImport(req, res);
+    }
+
+    // --- Health check ---
+    if (method === 'GET' && urlPath === '/api/health') {
+      return send(res, 200, { ok: true, workspace: getWorkspaces().active, uptime: process.uptime() });
+    }
+
+    // Not found
+    sendError(res, 404, `Not found: ${method} ${urlPath}`);
+  } catch (err) {
+    console.error(`Error handling ${method} ${urlPath}:`, err);
+    if (err.message && err.message.includes('UNIQUE constraint')) {
+      sendError(res, 409, 'Conflict: ' + err.message);
+    } else {
+      sendError(res, 500, err.message || 'Internal server error');
+    }
+  }
+}
+
+// ─── Gateway WebSocket Client ───────────────────────────────────────────────
+
+class GatewayClient {
+  constructor() {
+    this.ws = null;
+    this.connected = false;
+    this.reconnectAttempts = 0;
+    this.maxReconnectDelay = 30000;
+    this.browserClients = new Map(); // Map<WebSocket, { activeWorkspace, activeThreadId }>
+    this.streamState = new Map(); // Map<sessionKey, { state, buffer, threadId }>
+    this.activityLogs = new Map(); // Map<runId, { sessionKey, steps, startTime }>
+
+    // Clean up stale activity logs every 5 minutes (runs that never completed)
+    setInterval(() => {
+      const cutoff = Date.now() - 10 * 60 * 1000; // 10 minutes
+      for (const [runId, log] of this.activityLogs) {
+        if (log.startTime < cutoff) {
+          this.activityLogs.delete(runId);
+        }
+      }
+    }, 5 * 60 * 1000);
+  }
+
+  connect() {
+    if (this.ws && (this.ws.readyState === WS.CONNECTING || this.ws.readyState === WS.OPEN)) {
+      return; // Already connecting or connected
+    }
+
+    console.log(`Connecting to gateway at ${GATEWAY_WS_URL}...`);
+    this.ws = new WS(GATEWAY_WS_URL);
+
+    this.ws.on('open', () => {
+      console.log('Gateway WebSocket connected');
+      this.reconnectAttempts = 0;
+    });
+
+    this.ws.on('message', (data) => {
+      this.handleGatewayMessage(data.toString());
+    });
+
+    this.ws.on('close', () => {
+      console.log('Gateway WebSocket closed');
+      this.connected = false;
+      this.broadcastGatewayStatus(false);
+      this.scheduleReconnect();
+    });
+
+    this.ws.on('error', (err) => {
+      console.error('Gateway WebSocket error:', err.message);
+    });
+  }
+
+  handleGatewayMessage(data) {
+    debugLogger.logFrame('GW→SRV', data);
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch (e) {
+      console.error('Invalid JSON from gateway:', data);
+      return;
+    }
+
+    // Handle connect.challenge (handshake)
+    if (msg.type === 'event' && msg.event === 'connect.challenge') {
+      console.log('Received connect.challenge, sending auth...');
+      this.ws.send(JSON.stringify({
+        type: 'req',
+        id: 'gw-connect-1',
+        method: 'connect',
+        params: {
+          minProtocol: 3,
+          maxProtocol: 3,
+          client: { id: 'gateway-client', version: '0.1.0', platform: 'node', mode: 'backend' },
+          role: 'operator',
+          scopes: ['operator.read', 'operator.write', 'operator.admin'],
+          auth: { token: AUTH_TOKEN },
+          caps: ['tool-events']
+        }
+      }));
+      return;
+    }
+
+    // Handle connect response (hello-ok)
+    if (msg.type === 'res' && msg.payload?.type === 'hello-ok') {
+      console.log('Gateway handshake complete');
+      this.connected = true;
+      this.broadcastGatewayStatus(true);
+    }
+
+    // Handle activity log history responses
+    if (msg.type === 'res' && msg.id && this._pendingActivityCallbacks?.has(msg.id)) {
+      const callback = this._pendingActivityCallbacks.get(msg.id);
+      this._pendingActivityCallbacks.delete(msg.id);
+      if (msg.ok) {
+        callback(msg.payload);
+      } else {
+        callback(null);
+      }
+    }
+
+    // Forward all messages to browser clients
+    this.broadcastToBrowsers(data);
+
+    // Process chat events for persistence
+    if (msg.type === 'event' && msg.event === 'chat' && msg.payload) {
+      this.handleChatEvent(msg.payload);
+    }
+
+    // Process agent events for activity log
+    if (msg.type === 'event' && msg.event === 'agent' && msg.payload) {
+      this.handleAgentEvent(msg.payload);
+    }
+  }
+
+  handleChatEvent(params) {
+    const { sessionKey, state, message, seq } = params;
+
+    // Update streaming state
+    if (state === 'delta') {
+      const parsed = parseSessionKey(sessionKey);
+      if (parsed) {
+        const existing = this.streamState.get(sessionKey) || { buffer: '', threadId: parsed.threadId, state: 'streaming' };
+        const deltaText = extractContent(message);
+        existing.buffer += deltaText;
+        this.streamState.set(sessionKey, existing);
+      }
+      return;
+    }
+
+    // Clear stream state on final/aborted/error
+    if (state === 'final' || state === 'aborted' || state === 'error') {
+      this.streamState.delete(sessionKey);
+    }
+
+    // Save assistant messages on final
+    if (state === 'final') {
+      this.saveAssistantMessage(sessionKey, message, seq);
+    }
+
+    // Save error markers
+    if (state === 'error') {
+      this.saveErrorMarker(sessionKey, message);
+    }
+  }
+
+  saveAssistantMessage(sessionKey, message, seq) {
+    const parsed = parseSessionKey(sessionKey);
+    if (!parsed) return; // Non-ShellChat session key, silently ignore
+
+    // Guard: verify workspace still exists
+    const ws = getWorkspaces();
+    if (!ws.workspaces[parsed.workspace]) {
+      console.log(`Ignoring response for deleted workspace: ${parsed.workspace}`);
+      return;
+    }
+
+    const db = getDb(parsed.workspace);
+
+    // Guard: verify thread still exists
+    const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(parsed.threadId);
+    if (!thread) {
+      console.log(`Ignoring response for deleted thread: ${parsed.threadId}`);
+      return;
+    }
+
+    // Extract content
+    const content = extractContent(message);
+
+    // Guard: skip empty content
+    if (!content || !content.trim()) {
+      console.log(`Skipping empty assistant response for thread ${parsed.threadId}`);
+      return;
+    }
+
+    // Deterministic message ID from seq (deduplicates tool-call loops)
+    const now = Date.now();
+    const messageId = seq != null ? `gw-${parsed.threadId}-${seq}` : `gw-${parsed.threadId}-${now}`;
+
+    // Upsert message: INSERT OR REPLACE (same seq → same messageId → update content)
+    try {
+      db.prepare(`
+        INSERT INTO messages (id, thread_id, role, content, status, timestamp, created_at)
+        VALUES (?, ?, 'assistant', ?, 'sent', ?, ?)
+        ON CONFLICT(id) DO UPDATE SET content = excluded.content, timestamp = excluded.timestamp
+      `).run(messageId, parsed.threadId, content, now, now);
+
+      // Update thread updated_at
+      db.prepare('UPDATE threads SET updated_at = ? WHERE id = ?').run(now, parsed.threadId);
+
+      // Check if thread is active in any browser client
+      const isActive = [...this.browserClients.values()].some(
+        c => c.activeWorkspace === parsed.workspace && c.activeThreadId === parsed.threadId
+      );
+
+      // Track unread message if thread not active in any browser
+      if (!isActive) {
+        db.prepare('INSERT OR IGNORE INTO unread_messages (thread_id, message_id, created_at) VALUES (?, ?, ?)').run(parsed.threadId, messageId, now);
+        // Recount from table (always accurate)
+        syncThreadUnreadCount(db, parsed.threadId);
+      }
+
+      // Get thread title and unread info for notification
+      const threadInfo = db.prepare('SELECT title FROM threads WHERE id = ?').get(parsed.threadId);
+      const unreadCount = db.prepare('SELECT COUNT(*) as c FROM unread_messages WHERE thread_id = ?').get(parsed.threadId).c;
+      const preview = content.length > 120 ? content.substring(0, 120) + '...' : content;
+
+      // Broadcast message-saved for active thread reload
+      this.broadcastToBrowsers(JSON.stringify({
+        type: 'shellchat',
+        event: 'message-saved',
+        threadId: parsed.threadId,
+        workspace: parsed.workspace,
+        messageId,
+        timestamp: now,
+        title: threadInfo?.title || 'Chat',
+        preview,
+        unreadCount
+      }));
+
+      // Broadcast unread-update for badge/notification sync (all clients)
+      if (!isActive) {
+        const workspaceUnreadTotal = db.prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get().total;
+        this.broadcastToBrowsers(JSON.stringify({
+          type: 'shellchat',
+          event: 'unread-update',
+          workspace: parsed.workspace,
+          threadId: parsed.threadId,
+          messageId,
+          action: 'new',
+          unreadCount,
+          workspaceUnreadTotal,
+          title: threadInfo?.title || 'Chat',
+          preview,
+          timestamp: now
+        }));
+      }
+
+      console.log(`Saved assistant message to ${parsed.workspace}/${parsed.threadId} (seq: ${seq})`);
+    } catch (e) {
+      console.error(`Failed to save assistant message:`, e.message);
+    }
+  }
+
+  saveErrorMarker(sessionKey, message) {
+    const parsed = parseSessionKey(sessionKey);
+    if (!parsed) return;
+
+    const ws = getWorkspaces();
+    if (!ws.workspaces[parsed.workspace]) return;
+
+    const db = getDb(parsed.workspace);
+    const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(parsed.threadId);
+    if (!thread) return;
+
+    const errorText = message?.error || message?.content || 'Unknown error';
+    const content = `[error] ${errorText}`;
+    const now = Date.now();
+    const messageId = `gw-error-${parsed.threadId}-${now}`;
+
+    try {
+      db.prepare(
+        'INSERT INTO messages (id, thread_id, role, content, status, metadata, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'
+      ).run(messageId, parsed.threadId, 'system', content, 'sent', '{"transient":true}', now, now);
+
+      console.log(`Saved error marker for ${parsed.workspace}/${parsed.threadId}`);
+    } catch (e) {
+      console.error(`Failed to save error marker:`, e.message);
+    }
+  }
+
+  handleAgentEvent(payload) {
+    const { runId, stream, data, sessionKey } = payload;
+    if (!runId) return;
+
+    // Initialize log if needed
+    if (!this.activityLogs.has(runId)) {
+      this.activityLogs.set(runId, { sessionKey, steps: [], startTime: Date.now() });
+    }
+    const log = this.activityLogs.get(runId);
+
+    if (stream === 'assistant') {
+      // Capture intermediate text turns (narration between tool calls)
+      const text = data?.text || '';
+      if (text) {
+        // Update or create the current assistant text segment
+        // Each new assistant segment starts after a tool call
+        let currentSegment = log._currentAssistantSegment;
+        if (!currentSegment || currentSegment._sealed) {
+          currentSegment = {
+            type: 'assistant',
+            timestamp: Date.now(),
+            text: text,
+            _sealed: false
+          };
+          log._currentAssistantSegment = currentSegment;
+          log.steps.push(currentSegment);
+        } else {
+          currentSegment.text = text;
+        }
+      }
+      // Don't broadcast on every assistant delta — too noisy
+      // We'll broadcast when a tool starts (which seals the current segment)
+      return;
+    }
+
+    if (stream === 'thinking') {
+      // Reasoning/thinking text from the model (requires reasoningLevel: "stream")
+      const thinkingText = data?.text || '';
+      const delta = data?.delta || '';
+      // Update or create thinking step — we keep a single thinking step that accumulates
+      let thinkingStep = log.steps.find(s => s.type === 'thinking');
+      if (thinkingStep) {
+        thinkingStep.text = thinkingText;
+      } else {
+        log.steps.push({
+          type: 'thinking',
+          timestamp: Date.now(),
+          text: thinkingText
+        });
+      }
+      // Broadcast to browser for live display (throttled — thinking events come fast)
+      const now = Date.now();
+      if (!log._lastThinkingBroadcast || now - log._lastThinkingBroadcast >= 300) {
+        log._lastThinkingBroadcast = now;
+        this.broadcastActivityUpdate(runId, log);
+      }
+    }
+
+    if (stream === 'tool') {
+      // Seal any current assistant text segment (narration before this tool call)
+      if (log._currentAssistantSegment && !log._currentAssistantSegment._sealed) {
+        log._currentAssistantSegment._sealed = true;
+        // Broadcast the narration + upcoming tool
+        this.broadcastActivityUpdate(runId, log);
+      }
+
+      const step = {
+        type: 'tool',
+        timestamp: Date.now(),
+        name: data?.name || 'unknown',
+        phase: data?.phase || 'start',
+        toolCallId: data?.toolCallId,
+        meta: data?.meta,
+        isError: data?.isError || false
+      };
+
+      // On result phase, update the existing start step or add new
+      if (data?.phase === 'result') {
+        const existing = log.steps.findLast(s => s.toolCallId === data.toolCallId && (s.phase === 'start' || s.phase === 'running'));
+        if (existing) {
+          existing.phase = 'done';
+          existing.resultMeta = data?.meta;
+          existing.isError = data?.isError || false;
+          existing.durationMs = Date.now() - existing.timestamp;
+        } else {
+          step.phase = 'done';
+          log.steps.push(step);
+        }
+      } else if (data?.phase === 'update') {
+        // Merge update events into the existing step — don't create new entries
+        const existing = log.steps.findLast(s => s.toolCallId === data.toolCallId);
+        if (existing) {
+          // Update meta if the update carries new info
+          if (data?.meta) existing.resultMeta = data.meta;
+          if (data?.isError) existing.isError = true;
+          existing.phase = 'running';
+        }
+        // If no existing step found, silently ignore the orphaned update
+      } else {
+        log.steps.push(step);
+      }
+
+      // Forward to browser for real-time display
+      this.broadcastActivityUpdate(runId, log);
+    }
+
+    if (stream === 'lifecycle') {
+      if (data?.phase === 'end' || data?.phase === 'error') {
+        // Seal any remaining assistant segment
+        if (log._currentAssistantSegment && !log._currentAssistantSegment._sealed) {
+          log._currentAssistantSegment._sealed = true;
+        }
+        // Remove the final assistant segment — that's the actual response, not narration
+        // The last assistant segment is the final reply text, which is displayed as the message itself
+        const lastAssistantIdx = log.steps.findLastIndex(s => s.type === 'assistant');
+        if (lastAssistantIdx >= 0) {
+          log.steps.splice(lastAssistantIdx, 1);
+        }
+
+        log.steps.push({ type: 'lifecycle', timestamp: Date.now(), phase: data.phase });
+
+        // Finalize: save to message metadata
+        this.finalizeActivityLog(runId, log);
+      }
+    }
+  }
+
+  broadcastActivityUpdate(runId, log) {
+    const parsed = log.sessionKey ? parseSessionKey(log.sessionKey) : null;
+    if (!parsed) return;
+
+    this.broadcastToBrowsers(JSON.stringify({
+      type: 'shellchat',
+      event: 'agent-activity',
+      workspace: parsed.workspace,
+      threadId: parsed.threadId,
+      runId,
+      steps: log.steps,
+      summary: this.generateActivitySummary(log.steps)
+    }));
+  }
+
+  finalizeActivityLog(runId, log) {
+    const parsed = log.sessionKey ? parseSessionKey(log.sessionKey) : null;
+    if (!parsed) return;
+
+    const db = getDb(parsed.workspace);
+    if (!db) return;
+
+    const hasToolSteps = log.steps.some(s => s.type === 'tool');
+
+    // If we got no tool events (e.g., webchat session where we're not a registered recipient),
+    // try to extract tool calls from the session history via Gateway API
+    if (!hasToolSteps && this.ws && this.ws.readyState === 1 /* OPEN */) {
+      this.fetchToolCallsFromHistory(log.sessionKey, parsed, db, log, runId);
+      return;
+    }
+
+    // Save activity log to message metadata (delay to ensure final message is saved first)
+    this.saveActivityToMessage(parsed, db, log, runId);
+  }
+
+  fetchToolCallsFromHistory(sessionKey, parsed, db, log, runId) {
+    const reqId = `activity-hist-${runId}`;
+
+    const timeout = setTimeout(() => {
+      // Timeout: save what we have (even if empty)
+      this._pendingActivityCallbacks?.delete(reqId);
+      this.saveActivityToMessage(parsed, db, log, runId);
+    }, 5000);
+
+    // Register callback for when the gateway responds
+    if (!this._pendingActivityCallbacks) this._pendingActivityCallbacks = new Map();
+    this._pendingActivityCallbacks.set(reqId, (payload) => {
+      clearTimeout(timeout);
+
+      // Extract tool calls and narration from the last assistant message in history
+      if (payload?.messages) {
+        for (let i = payload.messages.length - 1; i >= 0; i--) {
+          const m = payload.messages[i];
+          if (m.role === 'assistant' && Array.isArray(m.content)) {
+            let hasToolUse = false;
+            for (const block of m.content) {
+              if (block.type === 'text' && block.text?.trim() && hasToolUse) {
+                // Text after a tool_use = intermediate narration (not the first text which is part of the response)
+                // Actually, text BEFORE a tool_use is narration too
+              }
+              if (block.type === 'text' && block.text?.trim()) {
+                // We'll collect all text blocks, then trim the last one (that's the actual response)
+                log.steps.push({
+                  type: 'assistant',
+                  timestamp: Date.now(),
+                  text: block.text.trim()
+                });
+              }
+              if (block.type === 'tool_use') {
+                hasToolUse = true;
+                log.steps.push({
+                  type: 'tool',
+                  timestamp: Date.now(),
+                  name: block.name || 'unknown',
+                  phase: 'done',
+                  toolCallId: block.id,
+                  meta: this.extractToolMeta(block),
+                  isError: false
+                });
+              }
+            }
+            // Remove the last assistant text — that's the final response, not narration
+            if (hasToolUse) {
+              const lastAssistantIdx = log.steps.findLastIndex(s => s.type === 'assistant');
+              if (lastAssistantIdx >= 0) {
+                log.steps.splice(lastAssistantIdx, 1);
+              }
+            } else {
+              // No tool calls — remove all assistant narration (nothing interesting to show)
+              log.steps = log.steps.filter(s => s.type !== 'assistant');
+            }
+            break; // Only process the last assistant message
+          }
+        }
+      }
+
+      this.saveActivityToMessage(parsed, db, log, runId);
+      this.broadcastActivityUpdate(runId, log);
+    });
+
+    // Request session history from gateway
+    this.ws.send(JSON.stringify({
+      type: 'req',
+      id: reqId,
+      method: 'sessions.history',
+      params: { key: sessionKey, limit: 3, includeTools: true }
+    }));
+  }
+
+  extractToolMeta(toolUseBlock) {
+    if (!toolUseBlock.input) return '';
+    const input = toolUseBlock.input;
+    // Generate a brief description from the tool input
+    if (input.query) return input.query;
+    if (input.command) return input.command.substring(0, 80);
+    if (input.file_path || input.path) return input.file_path || input.path;
+    if (input.url) return input.url;
+    if (input.text) return input.text.substring(0, 60);
+    return '';
+  }
+
+  saveActivityToMessage(parsed, db, log, runId) {
+    // Delay to ensure the assistant message is saved first (from handleChatEvent final)
+    setTimeout(() => {
+      try {
+        const msg = db.prepare(
+          'SELECT id, metadata FROM messages WHERE thread_id = ? AND role = ? ORDER BY timestamp DESC LIMIT 1'
+        ).get(parsed.threadId, 'assistant');
+
+        if (msg) {
+          const toolSteps = log.steps.filter(s => s.type === 'tool' && s.phase !== 'update');
+          const thinkingSteps = log.steps.filter(s => s.type === 'thinking');
+          const narrativeSteps = log.steps.filter(s => s.type === 'assistant' && s.text?.trim());
+          // Only save if we have meaningful activity
+          if (toolSteps.length > 0 || thinkingSteps.length > 0 || narrativeSteps.length > 0) {
+            const metadata = msg.metadata ? JSON.parse(msg.metadata) : {};
+            // Clean internal fields before persisting
+            metadata.activityLog = log.steps.map(s => {
+              const clean = { ...s };
+              delete clean._sealed;
+              return clean;
+            });
+            metadata.activitySummary = this.generateActivitySummary(log.steps);
+            db.prepare('UPDATE messages SET metadata = ? WHERE id = ?')
+              .run(JSON.stringify(metadata), msg.id);
+
+            console.log(`[ActivityLog] Saved ${toolSteps.length} tool steps for message ${msg.id}`);
+
+            // Notify browsers to re-render this message with activity data
+            this.broadcastToBrowsers(JSON.stringify({
+              type: 'shellchat',
+              event: 'activity-saved',
+              workspace: parsed.workspace,
+              threadId: parsed.threadId,
+              messageId: msg.id
+            }));
+          }
+        }
+      } catch (e) {
+        console.error('Failed to save activity log:', e.message);
+      }
+
+      this.activityLogs.delete(runId);
+    }, 1000); // 1s delay — must happen after message-saved (which fires on chat:final)
+  }
+
+  generateActivitySummary(steps) {
+    const toolSteps = steps.filter(s => s.type === 'tool' && s.phase !== 'result' && s.phase !== 'update');
+    const hasThinking = steps.some(s => s.type === 'thinking' && s.text);
+    const hasNarration = steps.some(s => s.type === 'assistant' && s.text?.trim());
+    if (toolSteps.length === 0 && !hasThinking && !hasNarration) return null;
+    if (toolSteps.length === 0 && hasThinking) return 'Reasoned through the problem';
+    if (toolSteps.length === 0 && hasNarration) return 'Processed in multiple steps';
+
+    // Count by tool name
+    const counts = {};
+    for (const s of toolSteps) {
+      const name = s.name || 'unknown';
+      counts[name] = (counts[name] || 0) + 1;
+    }
+
+    // Build description
+    const parts = [];
+    const toolNames = {
+      'web_search': 'searched the web',
+      'web_fetch': 'fetched web pages',
+      'Read': 'read files',
+      'read': 'read files',
+      'Write': 'wrote files',
+      'write': 'wrote files',
+      'Edit': 'edited files',
+      'edit': 'edited files',
+      'exec': 'ran commands',
+      'Bash': 'ran commands',
+      'browser': 'browsed the web',
+      'memory_search': 'searched memory',
+      'memory_store': 'saved to memory',
+      'image': 'analyzed images',
+      'message': 'sent messages',
+      'sessions_spawn': 'spawned sub-agents',
+      'cron': 'managed cron jobs',
+      'Grep': 'searched code',
+      'grep': 'searched code',
+      'Glob': 'found files',
+      'glob': 'found files'
+    };
+
+    for (const [name, count] of Object.entries(counts)) {
+      const friendly = toolNames[name];
+      if (friendly) {
+        parts.push(count > 1 ? `${friendly} (${count}×)` : friendly);
+      } else {
+        parts.push(count > 1 ? `used ${name} (${count}×)` : `used ${name}`);
+      }
+    }
+
+    if (parts.length === 0) return null;
+    if (parts.length === 1) return parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+    const last = parts.pop();
+    return (parts.join(', ') + ' and ' + last).replace(/^./, c => c.toUpperCase());
+  }
+
+  broadcastToBrowsers(data) {
+    debugLogger.logFrame('SRV→BR', data);
+    for (const client of this.browserClients.keys()) {
+      if (client.readyState === WS.OPEN) {
+        client.send(data);
+      }
+    }
+  }
+
+  broadcastGatewayStatus(connected) {
+    const msg = JSON.stringify({
+      type: 'shellchat',
+      event: 'gateway-status',
+      connected
+    });
+    this.broadcastToBrowsers(msg);
+  }
+
+  sendToGateway(data) {
+    debugLogger.logFrame('SRV→GW', data);
+    if (this.ws && this.ws.readyState === WS.OPEN) {
+      this.ws.send(data);
+    } else {
+      console.error('Cannot send to gateway: not connected');
+    }
+  }
+
+  scheduleReconnect() {
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay);
+    this.reconnectAttempts++;
+    console.log(`Reconnecting to gateway in ${delay}ms (attempt ${this.reconnectAttempts})...`);
+    setTimeout(() => this.connect(), delay);
+  }
+
+  addBrowserClient(ws) {
+    this.browserClients.set(ws, { activeWorkspace: null, activeThreadId: null });
+
+    // Send current gateway status
+    if (ws.readyState === WS.OPEN) {
+      ws.send(JSON.stringify({
+        type: 'shellchat',
+        event: 'gateway-status',
+        connected: this.connected
+      }));
+
+      // Send stream-sync with current streaming states
+      const streams = [];
+      for (const [sessionKey, state] of this.streamState.entries()) {
+        if (state.state === 'streaming') {
+          streams.push({ sessionKey, threadId: state.threadId, buffer: state.buffer });
+        }
+      }
+      if (streams.length > 0) {
+        ws.send(JSON.stringify({
+          type: 'shellchat',
+          event: 'stream-sync',
+          streams
+        }));
+      }
+    }
+  }
+
+  removeBrowserClient(ws) {
+    this.browserClients.delete(ws);
+  }
+
+  setActiveThread(ws, workspace, threadId) {
+    const client = this.browserClients.get(ws);
+    if (client) {
+      client.activeWorkspace = workspace;
+      client.activeThreadId = threadId;
+    }
+
+    // Auto-clear unreads: opening a thread = reading it
+    if (workspace && threadId) {
+      try {
+        const wsData = getWorkspaces();
+        if (!wsData.workspaces[workspace]) return;
+
+        const db = getDb(workspace);
+        const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(threadId);
+        if (!thread) return;
+
+        // Delete all unread entries for this thread
+        const deleted = db.prepare('DELETE FROM unread_messages WHERE thread_id = ?').run(threadId);
+        if (deleted.changes > 0) {
+          syncThreadUnreadCount(db, threadId);
+
+          // Broadcast unread-update clear to ALL browser clients
+          const workspaceUnreadTotal = db.prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get().total;
+          this.broadcastToBrowsers(JSON.stringify({
+            type: 'shellchat',
+            event: 'unread-update',
+            workspace,
+            threadId,
+            action: 'clear',
+            unreadCount: 0,
+            workspaceUnreadTotal,
+            timestamp: Date.now()
+          }));
+        }
+      } catch (e) {
+        console.error('Failed to auto-clear unreads on active-thread:', e.message);
+      }
+    }
+  }
+}
+
+// Helper: Recount unread_messages and sync threads.unread_count
+function syncThreadUnreadCount(db, threadId) {
+  const count = db.prepare('SELECT COUNT(*) as c FROM unread_messages WHERE thread_id = ?').get(threadId).c;
+  db.prepare('UPDATE threads SET unread_count = ? WHERE id = ?').run(count, threadId);
+  return count;
+}
+
+// Helper: Parse session key
+function parseSessionKey(sessionKey) {
+  if (!sessionKey) return null;
+  const match = sessionKey.match(/^agent:main:([^:]+):chat:([^:]+)$/);
+  if (!match) return null; // Non-ShellChat keys — silently ignore
+  return { workspace: match[1], threadId: match[2] };
+}
+
+// Helper: Extract content from message
+function extractContent(message) {
+  if (!message) return '';
+  if (typeof message.content === 'string') return message.content;
+  if (Array.isArray(message.content)) {
+    return message.content
+      .filter(part => part.type === 'text')
+      .map(part => part.text)
+      .join('');
+  }
+  return '';
+}
+
+const gatewayClient = new GatewayClient();
+
+// ─── createApp Factory ───────────────────────────────────────────────────────
+// Returns an isolated instance of the app state + handlers.
+// Used by the plugin (signaling/index.js) to embed ShellChat logic without
+// spinning up a standalone HTTP server.
+
+export function createApp(config = {}) {
+  // ── Config-dependent constants ─────────────────────────────────────────────
+  const _DATA_DIR = config.dataDir || path.join(__dirname, 'data');
+  const _UPLOADS_DIR = config.uploadsDir || path.join(__dirname, 'uploads');
+  const _WORKSPACES_FILE = path.join(_DATA_DIR, 'workspaces.json');
+  const _SETTINGS_FILE = path.join(_DATA_DIR, 'settings.json');
+  const _INTELLIGENCE_DIR = path.join(_DATA_DIR, 'intelligence');
+
+  let _AUTH_TOKEN = config.authToken !== undefined
+    ? config.authToken
+    : (process.env.SHELLCHAT_AUTH_TOKEN || parseConfigField('authToken') || '');
+
+  // Separate token for gateway WS auth (falls back to _AUTH_TOKEN for direct mode)
+  const _GATEWAY_TOKEN = config.gatewayToken !== undefined
+    ? config.gatewayToken
+    : _AUTH_TOKEN;
+
+  const _GATEWAY_WS_URL = config.gatewayUrl || discoverGatewayWsUrl();
+
+  // ── Mutable singleton state ────────────────────────────────────────────────
+  const _dbCache = new Map();
+  let _workspacesConfig = null;
+  const _debugLogger = new DebugLogger(_DATA_DIR);
+
+  const _MEMORY_CONFIG = discoverMemoryConfig();
+  const _memoryProvider = createMemoryProvider(_MEMORY_CONFIG);
+  _memoryProvider.init().catch(err => console.error('[createApp] Memory provider init error:', err.message));
+
+  const _MEMORY_FILES_DIR = path.join(_MEMORY_CONFIG.workspaceDir, 'memory');
+
+  // ── Workspace helpers ──────────────────────────────────────────────────────
+  function _loadWorkspaces() {
+    try {
+      return JSON.parse(fs.readFileSync(_WORKSPACES_FILE, 'utf8'));
+    } catch {
+      const initial = {
+        active: 'default',
+        workspaces: {
+          default: { name: 'default', label: 'Default', createdAt: Date.now() }
+        }
+      };
+      fs.writeFileSync(_WORKSPACES_FILE, JSON.stringify(initial, null, 2));
+      return initial;
+    }
+  }
+
+  function _saveWorkspaces(data) {
+    fs.writeFileSync(_WORKSPACES_FILE, JSON.stringify(data, null, 2));
+  }
+
+  function _getWorkspaces() {
+    if (!_workspacesConfig) _workspacesConfig = _loadWorkspaces();
+    return _workspacesConfig;
+  }
+
+  function _setWorkspaces(data) {
+    _workspacesConfig = data;
+    _saveWorkspaces(data);
+  }
+
+  // ── Database helpers ───────────────────────────────────────────────────────
+  function _getDb(workspaceName) {
+    if (_dbCache.has(workspaceName)) return _dbCache.get(workspaceName);
+    const dbPath = path.join(_DATA_DIR, `${workspaceName}.db`);
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    migrate(db);
+    _dbCache.set(workspaceName, db);
+    return db;
+  }
+
+  function _getActiveDb() {
+    return _getDb(_getWorkspaces().active);
+  }
+
+  function _closeDb(workspaceName) {
+    const db = _dbCache.get(workspaceName);
+    if (db) { db.close(); _dbCache.delete(workspaceName); }
+  }
+
+  function _closeAllDbs() {
+    for (const [, db] of _dbCache) db.close();
+    _dbCache.clear();
+  }
+
+  function _ensureDirs() {
+    fs.mkdirSync(_DATA_DIR, { recursive: true });
+    fs.mkdirSync(_UPLOADS_DIR, { recursive: true });
+  }
+
+  // ── Auth (closes over _AUTH_TOKEN) ─────────────────────────────────────────
+  function _checkAuth(req, res) {
+    if (!_AUTH_TOKEN) return true;
+    const auth = req.headers.authorization;
+    if (!auth || !auth.startsWith('Bearer ')) {
+      sendError(res, 401, 'Missing or invalid Authorization header');
+      return false;
+    }
+    const token = auth.slice(7);
+    if (token !== _AUTH_TOKEN) {
+      sendError(res, 401, 'Invalid auth token');
+      return false;
+    }
+    return true;
+  }
+
+  // ── Route handlers (all close over _getDb, _getActiveDb, _getWorkspaces, etc.) ──
+
+  function _handleGetSettings(req, res) {
+    try {
+      const data = fs.existsSync(_SETTINGS_FILE)
+        ? JSON.parse(fs.readFileSync(_SETTINGS_FILE, 'utf8'))
+        : {};
+      return send(res, 200, data);
+    } catch { return send(res, 200, {}); }
+  }
+
+  async function _handleSaveSettings(req, res) {
+    const body = await parseBody(req);
+    try {
+      const existing = fs.existsSync(_SETTINGS_FILE)
+        ? JSON.parse(fs.readFileSync(_SETTINGS_FILE, 'utf8'))
+        : {};
+      const merged = { ...existing, ...body };
+      fs.writeFileSync(_SETTINGS_FILE, JSON.stringify(merged, null, 2));
+      return send(res, 200, merged);
+    } catch (err) { return send(res, 500, { error: err.message }); }
+  }
+
+  function _handleGetWorkspaces(req, res) {
+    const ws = _getWorkspaces();
+    const sorted = Object.values(ws.workspaces).sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+    for (const workspace of sorted) {
+      try {
+        const db = _getDb(workspace.name);
+        const result = db.prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get();
+        workspace.unread_count = result.total;
+      } catch { workspace.unread_count = 0; }
+    }
+    send(res, 200, { active: ws.active, workspaces: sorted });
+  }
+
+  async function _handleCreateWorkspace(req, res) {
+    const body = await parseBody(req);
+    const { name, label } = body;
+    if (!name || !/^[a-z0-9-]{1,32}$/.test(name)) {
+      return sendError(res, 400, 'Name must be [a-z0-9-], 1-32 chars');
+    }
+    const ws = _getWorkspaces();
+    if (ws.workspaces[name]) return sendError(res, 409, 'Workspace already exists');
+    const workspace = { name, label: label || name, color: body.color || null, icon: body.icon || null, createdAt: Date.now() };
+    ws.workspaces[name] = workspace;
+    _setWorkspaces(ws);
+    _getDb(name);
+    send(res, 201, { workspace });
+  }
+
+  async function _handleUpdateWorkspace(req, res, params) {
+    const body = await parseBody(req);
+    const ws = _getWorkspaces();
+    if (!ws.workspaces[params.name]) return sendError(res, 404, 'Workspace not found');
+    if (body.label !== undefined) ws.workspaces[params.name].label = body.label;
+    if (body.color !== undefined) ws.workspaces[params.name].color = body.color;
+    if (body.icon !== undefined) ws.workspaces[params.name].icon = body.icon;
+    _setWorkspaces(ws);
+    send(res, 200, { workspace: ws.workspaces[params.name] });
+  }
+
+  function _handleDeleteWorkspace(req, res, params) {
+    const ws = _getWorkspaces();
+    if (!ws.workspaces[params.name]) return sendError(res, 404, 'Workspace not found');
+    if (Object.keys(ws.workspaces).length <= 1) return sendError(res, 400, 'Cannot delete the only workspace');
+    if (ws.active === params.name) return sendError(res, 400, 'Cannot delete the active workspace');
+    _closeDb(params.name);
+    const dbPath = path.join(_DATA_DIR, `${params.name}.db`);
+    try { fs.unlinkSync(dbPath); } catch { /* ok */ }
+    try { fs.unlinkSync(dbPath + '-wal'); } catch { /* ok */ }
+    try { fs.unlinkSync(dbPath + '-shm'); } catch { /* ok */ }
+    const cleaned = cleanGatewaySessionsByPrefix(`agent:main:${params.name}:chat:`);
+    if (cleaned > 0) console.log(`Cleaned ${cleaned} gateway sessions for workspace: ${params.name}`);
+    delete ws.workspaces[params.name];
+    _setWorkspaces(ws);
+    send(res, 200, { ok: true });
+  }
+
+  async function _handleReorderWorkspaces(req, res) {
+    const body = await parseBody(req);
+    const { order } = body;
+    if (!Array.isArray(order)) return sendError(res, 400, 'order must be an array of workspace names');
+    const ws = _getWorkspaces();
+    order.forEach((name, i) => { if (ws.workspaces[name]) ws.workspaces[name].order = i; });
+    _setWorkspaces(ws);
+    send(res, 200, { ok: true, workspaces: Object.values(ws.workspaces) });
+  }
+
+  function _handleActivateWorkspace(req, res, params) {
+    const ws = _getWorkspaces();
+    if (!ws.workspaces[params.name]) return sendError(res, 404, 'Workspace not found');
+    ws.active = params.name;
+    _setWorkspaces(ws);
+    _getDb(params.name);
+    send(res, 200, { ok: true, workspace: ws.workspaces[params.name] });
+  }
+
+  function _handleGetThreads(req, res, params, query) {
+    const db = _getActiveDb();
+    const page = parseInt(query.page || '1', 10);
+    const limit = Math.min(parseInt(query.limit || '50', 10), 200);
+    const offset = (page - 1) * limit;
+    const search = query.search || '';
+    let threads, total;
+    if (search) {
+      const ftsQuery = `SELECT DISTINCT m.thread_id FROM messages m JOIN messages_fts ON messages_fts.rowid = m.rowid WHERE messages_fts MATCH ?`;
+      const matchingIds = db.prepare(ftsQuery).all(search).map(r => r.thread_id);
+      if (matchingIds.length === 0) return send(res, 200, { threads: [], total: 0, page });
+      const placeholders = matchingIds.map(() => '?').join(',');
+      total = db.prepare(`SELECT COUNT(*) as c FROM threads WHERE id IN (${placeholders})`).get(...matchingIds).c;
+      threads = db.prepare(`SELECT * FROM threads WHERE id IN (${placeholders}) ORDER BY pinned DESC, sort_order DESC, updated_at DESC LIMIT ? OFFSET ?`).all(...matchingIds, limit, offset);
+    } else {
+      total = db.prepare('SELECT COUNT(*) as c FROM threads').get().c;
+      threads = db.prepare('SELECT * FROM threads ORDER BY pinned DESC, sort_order DESC, updated_at DESC LIMIT ? OFFSET ?').all(limit, offset);
+    }
+    send(res, 200, { threads, total, page });
+  }
+
+  function _handleGetUnreadThreads(req, res) {
+    const db = _getActiveDb();
+    const threads = db.prepare(`
+      SELECT t.id, t.title, t.unread_count, m.content as lastMessage
+      FROM threads t
+      LEFT JOIN messages m ON m.thread_id = t.id
+      WHERE t.unread_count > 0
+      AND m.timestamp = (SELECT MAX(timestamp) FROM messages WHERE thread_id = t.id)
+      ORDER BY t.updated_at DESC
+    `).all();
+    for (const thread of threads) {
+      const rows = db.prepare('SELECT message_id FROM unread_messages WHERE thread_id = ?').all(thread.id);
+      thread.unreadMessageIds = rows.map(r => r.message_id);
+    }
+    send(res, 200, { threads });
+  }
+
+  async function _handleMarkMessagesRead(req, res, params) {
+    const body = await parseBody(req);
+    const db = _getActiveDb();
+    const threadId = params.id;
+    const messageIds = body.messageIds;
+    if (!Array.isArray(messageIds) || messageIds.length === 0) {
+      return send(res, 400, { error: 'messageIds array required' });
+    }
+    const placeholders = messageIds.map(() => '?').join(',');
+    db.prepare(`DELETE FROM unread_messages WHERE thread_id = ? AND message_id IN (${placeholders})`).run(threadId, ...messageIds);
+    const remaining = syncThreadUnreadCount(db, threadId);
+    const workspace = _getWorkspaces().active;
+    _gatewayClient.broadcastToBrowsers(JSON.stringify({
+      type: 'shellchat', event: 'unread-update', workspace, threadId,
+      action: 'read', messageIds, unreadCount: remaining, timestamp: Date.now()
+    }));
+    send(res, 200, { unread_count: remaining });
+  }
+
+  async function _handleCreateThread(req, res) {
+    const body = await parseBody(req);
+    const db = _getActiveDb();
+    const ws = _getWorkspaces();
+    const id = body.id || uuid();
+    const now = Date.now();
+    const sessionKey = `agent:main:${ws.active}:chat:${id}`;
+    try {
+      db.prepare('INSERT INTO threads (id, session_key, title, created_at, updated_at) VALUES (?, ?, ?, ?, ?)').run(id, sessionKey, 'New chat', now, now);
+    } catch (e) {
+      if (e.message.includes('UNIQUE constraint')) return sendError(res, 409, 'Thread already exists');
+      throw e;
+    }
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(id);
+    send(res, 201, { thread });
+  }
+
+  function _handleGetThread(req, res, params) {
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    send(res, 200, { thread });
+  }
+
+  async function _handleUpdateThread(req, res, params) {
+    const body = await parseBody(req);
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    const fields = [], values = [];
+    if (body.title !== undefined) { fields.push('title = ?'); values.push(body.title); }
+    if (body.pinned !== undefined) { fields.push('pinned = ?'); values.push(body.pinned ? 1 : 0); }
+    if (body.pin_order !== undefined) { fields.push('pin_order = ?'); values.push(body.pin_order); }
+    if (body.sort_order !== undefined) { fields.push('sort_order = ?'); values.push(body.sort_order); }
+    if (body.model !== undefined) { fields.push('model = ?'); values.push(body.model); }
+    if (body.last_session_id !== undefined) { fields.push('last_session_id = ?'); values.push(body.last_session_id); }
+    if (body.unread_count !== undefined) { fields.push('unread_count = ?'); values.push(body.unread_count); }
+    if (fields.length > 0) {
+      fields.push('updated_at = ?'); values.push(Date.now()); values.push(params.id);
+      db.prepare(`UPDATE threads SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+    }
+    const updated = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    send(res, 200, { thread: updated });
+  }
+
+  function _handleDeleteThread(req, res, params) {
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    db.prepare('DELETE FROM threads WHERE id = ?').run(params.id);
+    let sessionIdToDelete = thread.last_session_id;
+    if (!sessionIdToDelete) {
+      try {
+        const raw = fs.readFileSync(path.join(OPENCLAW_SESSIONS_DIR, 'sessions.json'), 'utf8');
+        const store = JSON.parse(raw);
+        const entry = store[thread.session_key];
+        if (entry?.sessionId) sessionIdToDelete = entry.sessionId;
+      } catch { /* ok */ }
+    }
+    cleanGatewaySession(thread.session_key);
+    if (sessionIdToDelete) {
+      const jsonlPath = path.join(OPENCLAW_SESSIONS_DIR, `${sessionIdToDelete}.jsonl`);
+      try { fs.unlinkSync(jsonlPath); } catch { /* ok */ }
+    }
+    const uploadDir = path.join(_UPLOADS_DIR, params.id);
+    try { fs.rmSync(uploadDir, { recursive: true }); } catch { /* ok */ }
+    send(res, 200, { ok: true });
+  }
+
+  function _handleGetMessages(req, res, params, query) {
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    const limit = Math.min(parseInt(query.limit || '100', 10), 500);
+    const before = query.before ? parseInt(query.before, 10) : null;
+    const after = query.after ? parseInt(query.after, 10) : null;
+    let sql = 'SELECT * FROM messages WHERE thread_id = ?';
+    const sqlParams = [params.id];
+    if (before) { sql += ' AND timestamp < ?'; sqlParams.push(before); }
+    if (after) { sql += ' AND timestamp > ?'; sqlParams.push(after); }
+    const countSql = sql.replace('SELECT *', 'SELECT COUNT(*) as c');
+    const total = db.prepare(countSql).get(...sqlParams).c;
+    sql += ' ORDER BY timestamp DESC LIMIT ?';
+    sqlParams.push(limit + 1);
+    const rows = db.prepare(sql).all(...sqlParams);
+    const hasMore = rows.length > limit;
+    const messages = rows.slice(0, limit).reverse();
+    for (const m of messages) {
+      if (m.metadata) { try { m.metadata = JSON.parse(m.metadata); } catch { /* ok */ } }
+    }
+    send(res, 200, { messages, hasMore });
+  }
+
+  async function _handleCreateMessage(req, res, params) {
+    const body = await parseBody(req);
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    if (!body.id || !body.role || body.content === undefined || !body.timestamp) {
+      return sendError(res, 400, 'Required: id, role, content, timestamp');
+    }
+    const metadata = body.metadata ? JSON.stringify(body.metadata) : null;
+    const existing = db.prepare('SELECT id, status FROM messages WHERE id = ?').get(body.id);
+    if (existing) {
+      if (body.status && body.status !== existing.status) {
+        db.prepare('UPDATE messages SET status = ?, content = ?, metadata = ? WHERE id = ?').run(body.status, body.content, metadata, body.id);
+      }
+    } else {
+      db.prepare('INSERT INTO messages (id, thread_id, role, content, status, metadata, seq, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)').run(body.id, params.id, body.role, body.content, body.status || 'sent', metadata, body.seq || null, body.timestamp, Date.now());
+      db.prepare('UPDATE threads SET updated_at = ? WHERE id = ?').run(Date.now(), params.id);
+    }
+    const message = db.prepare('SELECT * FROM messages WHERE id = ?').get(body.id);
+    if (message && message.metadata) { try { message.metadata = JSON.parse(message.metadata); } catch { /* ok */ } }
+    send(res, existing ? 200 : 201, { message });
+  }
+
+  function _handleDeleteMessage(req, res, params) {
+    const db = _getActiveDb();
+    const msg = db.prepare('SELECT id FROM messages WHERE id = ? AND thread_id = ?').get(params.messageId, params.id);
+    if (!msg) return sendError(res, 404, 'Message not found');
+    db.prepare('DELETE FROM messages WHERE id = ?').run(params.messageId);
+    send(res, 200, { ok: true });
+  }
+
+  function _handleContextFill(req, res, params) {
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    const { preamble, method } = buildContextPreamble(db, params.id, thread.last_session_id);
+    send(res, 200, { preamble, method });
+  }
+
+  function _handleSearch(req, res, params, query) {
+    const db = _getActiveDb();
+    const q = query.q || '';
+    if (!q) return send(res, 200, { results: [], total: 0 });
+    const page = parseInt(query.page || '1', 10);
+    const limit = Math.min(parseInt(query.limit || '20', 10), 100);
+    const offset = (page - 1) * limit;
+    const results = db.prepare(`
+      SELECT m.id as messageId, m.thread_id as threadId, t.title as threadTitle, m.role,
+        snippet(messages_fts, 0, '<mark>', '</mark>', '...', 40) as content, m.timestamp
+      FROM messages_fts JOIN messages m ON messages_fts.rowid = m.rowid JOIN threads t ON m.thread_id = t.id
+      WHERE messages_fts MATCH ? ORDER BY rank LIMIT ? OFFSET ?
+    `).all(q, limit, offset);
+    const totalRow = db.prepare(`SELECT COUNT(*) as c FROM messages_fts WHERE messages_fts MATCH ?`).get(q);
+    send(res, 200, { results, total: totalRow.c });
+  }
+
+  function _handleExport(req, res) {
+    const db = _getActiveDb();
+    const ws = _getWorkspaces();
+    const threads = db.prepare('SELECT * FROM threads ORDER BY updated_at DESC').all();
+    const data = {
+      workspace: ws.active, exportedAt: Date.now(),
+      threads: threads.map(t => {
+        const messages = db.prepare('SELECT * FROM messages WHERE thread_id = ? ORDER BY timestamp ASC').all(t.id);
+        for (const m of messages) { if (m.metadata) { try { m.metadata = JSON.parse(m.metadata); } catch { /* ok */ } } }
+        return { ...t, messages };
+      }),
+    };
+    send(res, 200, data);
+  }
+
+  async function _handleImport(req, res) {
+    const body = await parseBody(req);
+    const db = _getActiveDb();
+    const ws = _getWorkspaces();
+    if (!body.threads || !Array.isArray(body.threads)) return sendError(res, 400, 'Expected { threads: [...] }');
+    let threadsImported = 0, messagesImported = 0;
+    const insertThread = db.prepare('INSERT OR IGNORE INTO threads (id, session_key, title, pinned, pin_order, model, last_session_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    const insertMsg = db.prepare('INSERT OR IGNORE INTO messages (id, thread_id, role, content, status, metadata, seq, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    const importAll = db.transaction(() => {
+      for (const t of body.threads) {
+        if (!t.id) continue;
+        const sessionKey = t.session_key || `agent:main:${ws.active}:chat:${t.id}`;
+        const result = insertThread.run(t.id, sessionKey, t.title || 'Imported chat', t.pinned || 0, t.pin_order || 0, t.model || null, t.last_session_id || null, t.created_at || Date.now(), t.updated_at || Date.now());
+        if (result.changes > 0) threadsImported++;
+        for (const m of (t.messages || [])) {
+          if (!m.id || !m.role) continue;
+          const metadata = m.metadata ? (typeof m.metadata === 'string' ? m.metadata : JSON.stringify(m.metadata)) : null;
+          const r = insertMsg.run(m.id, t.id, m.role, m.content || '', m.status || 'sent', metadata, m.seq || null, m.timestamp || Date.now(), m.created_at || Date.now());
+          if (r.changes > 0) messagesImported++;
+        }
+      }
+    });
+    importAll();
+    send(res, 200, { ok: true, threadsImported, messagesImported });
+  }
+
+  async function _handleUpload(req, res, params) {
+    const db = _getActiveDb();
+    const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    const files = await parseMultipart(req);
+    const threadUploadDir = path.join(_UPLOADS_DIR, params.id);
+    fs.mkdirSync(threadUploadDir, { recursive: true });
+    const savedFiles = [];
+    for (const file of files) {
+      const fileId = uuid();
+      const ext = path.extname(file.filename) || '';
+      const savedName = fileId + ext;
+      const filePath = path.join(threadUploadDir, savedName);
+      fs.writeFileSync(filePath, file.data);
+      savedFiles.push({ id: fileId, filename: file.filename, path: `/api/uploads/${params.id}/${fileId}${ext}`, mimeType: file.mimeType, size: file.data.length });
+    }
+    send(res, 200, { files: savedFiles });
+  }
+
+  function _handleServeUpload(req, res, params) {
+    const filePath = path.join(_UPLOADS_DIR, params.threadId, params.fileId);
+    let resolved = filePath;
+    if (!fs.existsSync(resolved)) {
+      const dir = path.join(_UPLOADS_DIR, params.threadId);
+      try {
+        const entries = fs.readdirSync(dir);
+        const match = entries.find(e => e.startsWith(params.fileId.replace(/\.[^.]+$/, '')));
+        if (match) resolved = path.join(dir, match);
+      } catch { /* dir not found */ }
+    }
+    if (!fs.existsSync(resolved)) return sendError(res, 404, 'File not found');
+    const ext = path.extname(resolved).toLowerCase();
+    const mimeTypes = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf', '.txt': 'text/plain', '.json': 'application/json' };
+    const contentType = mimeTypes[ext] || 'application/octet-stream';
+    const stat = fs.statSync(resolved);
+    res.writeHead(200, { 'Content-Type': contentType, 'Content-Length': stat.size, 'Cache-Control': 'public, max-age=86400', 'Access-Control-Allow-Origin': '*' });
+    fs.createReadStream(resolved).pipe(res);
+  }
+
+  function _getIntelligencePath(threadId) {
+    const workspace = _getWorkspaces().active;
+    return path.join(_INTELLIGENCE_DIR, workspace, `${threadId}.json`);
+  }
+
+  function _handleGetIntelligence(req, res, params) {
+    const filePath = _getIntelligencePath(params.id);
+    if (!fs.existsSync(filePath)) return send(res, 200, { versions: [], currentVersion: -1 });
+    try { return send(res, 200, JSON.parse(fs.readFileSync(filePath, 'utf8'))); }
+    catch { return send(res, 200, { versions: [], currentVersion: -1 }); }
+  }
+
+  async function _handleSaveIntelligence(req, res, params) {
+    const body = await parseBody(req);
+    const filePath = _getIntelligencePath(params.id);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const data = { versions: body.versions || [], currentVersion: body.currentVersion ?? -1, updatedAt: Date.now() };
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    return send(res, 200, data);
+  }
+
+  async function _handleMemoryList(req, res, query) {
+    const limit = Math.min(parseInt(query.limit) || 20, 100);
+    try {
+      const result = await _memoryProvider.list(limit, query.offset || null);
+      send(res, 200, result);
+    } catch (err) { send(res, 502, { error: `Failed to reach ${_memoryProvider.name}`, detail: err.message }); }
+  }
+
+  async function _handleMemorySearch(req, res, query) {
+    const q = (query.query || '').toLowerCase().trim();
+    if (!q) return send(res, 400, { error: 'Missing query parameter' });
+    try {
+      const result = await _memoryProvider.search(q);
+      send(res, 200, result);
+    } catch (err) { send(res, 502, { error: `Failed to reach ${_memoryProvider.name}`, detail: err.message }); }
+  }
+
+  function _handleMemoryFiles(req, res, query) {
+    const q = (query.query || '').toLowerCase().trim();
+    // Use _MEMORY_FILES_DIR scoped to this factory instance
+    const memories = _parseMemoryFiles();
+    const filtered = q ? memories.filter(m => m.data.toLowerCase().includes(q) || m.title.toLowerCase().includes(q)) : memories;
+    filtered.sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+    send(res, 200, { memories: filtered });
+  }
+
+  function _parseMemoryFiles() {
+    const memories = [];
+    let files;
+    try { files = fs.readdirSync(_MEMORY_FILES_DIR); } catch { return memories; }
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      const filePath = path.join(_MEMORY_FILES_DIR, file);
+      let stat;
+      try { stat = fs.statSync(filePath); } catch { continue; }
+      if (!stat.isFile()) continue;
+      const content = fs.readFileSync(filePath, 'utf8');
+      const basename = file.replace(/\.md$/, '');
+      const dateMatch = basename.match(/^(\d{4}-\d{2}-\d{2})/);
+      const fileDate = dateMatch ? dateMatch[1] : null;
+      const sections = content.split(/^(?=## )/m);
+      for (const section of sections) {
+        const trimmed = section.trim();
+        if (!trimmed) continue;
+        const headingMatch = trimmed.match(/^##\s+(.+)/);
+        const heading = headingMatch ? headingMatch[1].trim() : null;
+        const body = headingMatch ? trimmed.slice(trimmed.indexOf('\n') + 1).trim() : trimmed;
+        if (!heading && body.match(/^#\s+/) && body.split('\n').length <= 2) continue;
+        const title = heading || basename;
+        const id = `file:${basename}:${title}`;
+        memories.push({ id, source: 'file', file: basename, title, data: heading ? `**${title}**\n${body}` : body, createdAt: fileDate ? `${fileDate}T00:00:00Z` : stat.mtime.toISOString() });
+      }
+    }
+    try {
+      for (const entry of fs.readdirSync(_MEMORY_FILES_DIR)) {
+        const subdir = path.join(_MEMORY_FILES_DIR, entry);
+        if (!fs.statSync(subdir).isDirectory()) continue;
+        for (const file of fs.readdirSync(subdir)) {
+          if (!file.endsWith('.md')) continue;
+          const filePath = path.join(subdir, file);
+          const content = fs.readFileSync(filePath, 'utf8');
+          const basename = file.replace(/\.md$/, '');
+          const relPath = `${entry}/${basename}`;
+          const stat = fs.statSync(filePath);
+          memories.push({ id: `file:${relPath}`, source: 'file', file: relPath, title: basename, data: content.trim(), createdAt: stat.mtime.toISOString() });
+        }
+      }
+    } catch { /* ignore */ }
+    return memories;
+  }
+
+  async function _handleMemoryUpdate(req, res, params) {
+    const id = params.id;
+    try {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      const body = JSON.parse(Buffer.concat(chunks).toString());
+      const newData = (body.data || '').trim();
+      if (!newData) return send(res, 400, { error: 'Missing data field' });
+      const result = await _memoryProvider.update(id, newData);
+      send(res, 200, { ok: true, result });
+    } catch (err) { send(res, 502, { error: 'Failed to update memory', detail: err.message }); }
+  }
+
+  async function _handleMemoryDelete(req, res, params) {
+    const id = params.id;
+    try {
+      const result = await _memoryProvider.delete(id);
+      send(res, 200, { ok: true, result });
+    } catch (err) { send(res, 502, { error: `Failed to reach ${_memoryProvider.name}`, detail: err.message }); }
+  }
+
+  async function _handleMemoryStatus(req, res) {
+    const status = await _memoryProvider.status();
+    const filesExist = fs.existsSync(_MEMORY_FILES_DIR);
+    send(res, 200, { provider: _memoryProvider.name, host: _MEMORY_CONFIG.host, port: _MEMORY_CONFIG.port, collection: _MEMORY_CONFIG.collection, backend: status, memoryFilesDir: _MEMORY_FILES_DIR, memoryFilesDirExists: filesExist });
+  }
+
+  // ── GatewayClient (scoped to this factory instance) ───────────────────────
+  class _GatewayClient {
+    constructor() {
+      this.ws = null;
+      this.connected = false;
+      this.reconnectAttempts = 0;
+      this.maxReconnectDelay = 30000;
+      this.browserClients = new Map();
+      this._externalBroadcastTargets = [];
+      this.streamState = new Map();
+      this.activityLogs = new Map();
+      setInterval(() => {
+        const cutoff = Date.now() - 10 * 60 * 1000;
+        for (const [runId, log] of this.activityLogs) {
+          if (log.startTime < cutoff) this.activityLogs.delete(runId);
+        }
+      }, 5 * 60 * 1000);
+    }
+
+    connect() {
+      if (this.ws && (this.ws.readyState === WS.CONNECTING || this.ws.readyState === WS.OPEN)) return;
+      console.log(`Connecting to gateway at ${_GATEWAY_WS_URL}...`);
+      this.ws = new WS(_GATEWAY_WS_URL);
+      this.ws.on('open', () => { console.log('Gateway WebSocket connected'); this.reconnectAttempts = 0; });
+      this.ws.on('message', (data) => { this.handleGatewayMessage(data.toString()); });
+      this.ws.on('close', () => { console.log('Gateway WebSocket closed'); this.connected = false; this.broadcastGatewayStatus(false); this.scheduleReconnect(); });
+      this.ws.on('error', (err) => { console.error('Gateway WebSocket error:', err.message); });
+    }
+
+    handleGatewayMessage(data) {
+      _debugLogger.logFrame('GW→SRV', data);
+      let msg;
+      try { msg = JSON.parse(data); } catch { console.error('Invalid JSON from gateway:', data); return; }
+      if (msg.type === 'event' && msg.event === 'connect.challenge') {
+        console.log('Received connect.challenge, sending auth...');
+        this.ws.send(JSON.stringify({ type: 'req', id: 'gw-connect-1', method: 'connect', params: { minProtocol: 3, maxProtocol: 3, client: { id: 'gateway-client', version: '0.1.0', platform: 'node', mode: 'backend' }, role: 'operator', scopes: ['operator.read', 'operator.write', 'operator.admin'], auth: { token: _GATEWAY_TOKEN }, caps: ['tool-events'] } }));
+        return;
+      }
+      if (msg.type === 'res' && msg.payload?.type === 'hello-ok') { console.log('Gateway handshake complete'); this.connected = true; this.broadcastGatewayStatus(true); }
+      if (msg.type === 'res' && msg.id && this._pendingActivityCallbacks?.has(msg.id)) {
+        const callback = this._pendingActivityCallbacks.get(msg.id);
+        this._pendingActivityCallbacks.delete(msg.id);
+        if (msg.ok) callback(msg.payload); else callback(null);
+      }
+      this.broadcastToBrowsers(data);
+      if (msg.type === 'event' && msg.event === 'chat' && msg.payload) this.handleChatEvent(msg.payload);
+      if (msg.type === 'event' && msg.event === 'agent' && msg.payload) this.handleAgentEvent(msg.payload);
+    }
+
+    handleChatEvent(params) {
+      const { sessionKey, state, message, seq } = params;
+      if (state === 'delta') {
+        const parsed = parseSessionKey(sessionKey);
+        if (parsed) {
+          const existing = this.streamState.get(sessionKey) || { buffer: '', threadId: parsed.threadId, state: 'streaming' };
+          existing.buffer += extractContent(message);
+          this.streamState.set(sessionKey, existing);
+        }
+        return;
+      }
+      if (state === 'final' || state === 'aborted' || state === 'error') this.streamState.delete(sessionKey);
+      if (state === 'final') this.saveAssistantMessage(sessionKey, message, seq);
+      if (state === 'error') this.saveErrorMarker(sessionKey, message);
+    }
+
+    saveAssistantMessage(sessionKey, message, seq) {
+      const parsed = parseSessionKey(sessionKey);
+      if (!parsed) return;
+      const ws = _getWorkspaces();
+      if (!ws.workspaces[parsed.workspace]) { console.log(`Ignoring response for deleted workspace: ${parsed.workspace}`); return; }
+      const db = _getDb(parsed.workspace);
+      const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(parsed.threadId);
+      if (!thread) { console.log(`Ignoring response for deleted thread: ${parsed.threadId}`); return; }
+      const content = extractContent(message);
+      if (!content || !content.trim()) { console.log(`Skipping empty assistant response for thread ${parsed.threadId}`); return; }
+      const now = Date.now();
+      const messageId = seq != null ? `gw-${parsed.threadId}-${seq}` : `gw-${parsed.threadId}-${now}`;
+      try {
+        db.prepare(`INSERT INTO messages (id, thread_id, role, content, status, timestamp, created_at) VALUES (?, ?, 'assistant', ?, 'sent', ?, ?) ON CONFLICT(id) DO UPDATE SET content = excluded.content, timestamp = excluded.timestamp`).run(messageId, parsed.threadId, content, now, now);
+        db.prepare('UPDATE threads SET updated_at = ? WHERE id = ?').run(now, parsed.threadId);
+        const isActive = [...this.browserClients.values()].some(c => c.activeWorkspace === parsed.workspace && c.activeThreadId === parsed.threadId);
+        if (!isActive) {
+          db.prepare('INSERT OR IGNORE INTO unread_messages (thread_id, message_id, created_at) VALUES (?, ?, ?)').run(parsed.threadId, messageId, now);
+          syncThreadUnreadCount(db, parsed.threadId);
+        }
+        const threadInfo = db.prepare('SELECT title FROM threads WHERE id = ?').get(parsed.threadId);
+        const unreadCount = db.prepare('SELECT COUNT(*) as c FROM unread_messages WHERE thread_id = ?').get(parsed.threadId).c;
+        const preview = content.length > 120 ? content.substring(0, 120) + '...' : content;
+        this.broadcastToBrowsers(JSON.stringify({ type: 'shellchat', event: 'message-saved', threadId: parsed.threadId, workspace: parsed.workspace, messageId, timestamp: now, title: threadInfo?.title || 'Chat', preview, unreadCount }));
+        if (!isActive) {
+          const workspaceUnreadTotal = db.prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get().total;
+          this.broadcastToBrowsers(JSON.stringify({ type: 'shellchat', event: 'unread-update', workspace: parsed.workspace, threadId: parsed.threadId, messageId, action: 'new', unreadCount, workspaceUnreadTotal, title: threadInfo?.title || 'Chat', preview, timestamp: now }));
+        }
+        console.log(`Saved assistant message to ${parsed.workspace}/${parsed.threadId} (seq: ${seq})`);
+      } catch (e) { console.error(`Failed to save assistant message:`, e.message); }
+    }
+
+    saveErrorMarker(sessionKey, message) {
+      const parsed = parseSessionKey(sessionKey);
+      if (!parsed) return;
+      const ws = _getWorkspaces();
+      if (!ws.workspaces[parsed.workspace]) return;
+      const db = _getDb(parsed.workspace);
+      const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(parsed.threadId);
+      if (!thread) return;
+      const errorText = message?.error || message?.content || 'Unknown error';
+      const content = `[error] ${errorText}`;
+      const now = Date.now();
+      const messageId = `gw-error-${parsed.threadId}-${now}`;
+      try {
+        db.prepare('INSERT INTO messages (id, thread_id, role, content, status, metadata, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(messageId, parsed.threadId, 'system', content, 'sent', '{"transient":true}', now, now);
+        console.log(`Saved error marker for ${parsed.workspace}/${parsed.threadId}`);
+      } catch (e) { console.error(`Failed to save error marker:`, e.message); }
+    }
+
+    handleAgentEvent(payload) {
+      const { runId, stream, data, sessionKey } = payload;
+      if (!runId) return;
+      if (!this.activityLogs.has(runId)) this.activityLogs.set(runId, { sessionKey, steps: [], startTime: Date.now() });
+      const log = this.activityLogs.get(runId);
+      if (stream === 'assistant') {
+        const text = data?.text || '';
+        if (text) {
+          let currentSegment = log._currentAssistantSegment;
+          if (!currentSegment || currentSegment._sealed) {
+            currentSegment = { type: 'assistant', timestamp: Date.now(), text, _sealed: false };
+            log._currentAssistantSegment = currentSegment;
+            log.steps.push(currentSegment);
+          } else { currentSegment.text = text; }
+        }
+        return;
+      }
+      if (stream === 'thinking') {
+        const thinkingText = data?.text || '';
+        let thinkingStep = log.steps.find(s => s.type === 'thinking');
+        if (thinkingStep) { thinkingStep.text = thinkingText; }
+        else { log.steps.push({ type: 'thinking', timestamp: Date.now(), text: thinkingText }); }
+        const now = Date.now();
+        if (!log._lastThinkingBroadcast || now - log._lastThinkingBroadcast >= 300) {
+          log._lastThinkingBroadcast = now;
+          this.broadcastActivityUpdate(runId, log);
+        }
+      }
+      if (stream === 'tool') {
+        if (log._currentAssistantSegment && !log._currentAssistantSegment._sealed) { log._currentAssistantSegment._sealed = true; this.broadcastActivityUpdate(runId, log); }
+        const step = { type: 'tool', timestamp: Date.now(), name: data?.name || 'unknown', phase: data?.phase || 'start', toolCallId: data?.toolCallId, meta: data?.meta, isError: data?.isError || false };
+        if (data?.phase === 'result') {
+          const existing = log.steps.findLast(s => s.toolCallId === data.toolCallId && (s.phase === 'start' || s.phase === 'running'));
+          if (existing) { existing.phase = 'done'; existing.resultMeta = data?.meta; existing.isError = data?.isError || false; existing.durationMs = Date.now() - existing.timestamp; }
+          else { step.phase = 'done'; log.steps.push(step); }
+        } else if (data?.phase === 'update') {
+          const existing = log.steps.findLast(s => s.toolCallId === data.toolCallId);
+          if (existing) { if (data?.meta) existing.resultMeta = data.meta; if (data?.isError) existing.isError = true; existing.phase = 'running'; }
+        } else { log.steps.push(step); }
+        this.broadcastActivityUpdate(runId, log);
+      }
+      if (stream === 'lifecycle') {
+        if (data?.phase === 'end' || data?.phase === 'error') {
+          if (log._currentAssistantSegment && !log._currentAssistantSegment._sealed) log._currentAssistantSegment._sealed = true;
+          const lastAssistantIdx = log.steps.findLastIndex(s => s.type === 'assistant');
+          if (lastAssistantIdx >= 0) log.steps.splice(lastAssistantIdx, 1);
+          log.steps.push({ type: 'lifecycle', timestamp: Date.now(), phase: data.phase });
+          this.finalizeActivityLog(runId, log);
+        }
+      }
+    }
+
+    broadcastActivityUpdate(runId, log) {
+      const parsed = log.sessionKey ? parseSessionKey(log.sessionKey) : null;
+      if (!parsed) return;
+      this.broadcastToBrowsers(JSON.stringify({ type: 'shellchat', event: 'agent-activity', workspace: parsed.workspace, threadId: parsed.threadId, runId, steps: log.steps, summary: this.generateActivitySummary(log.steps) }));
+    }
+
+    finalizeActivityLog(runId, log) {
+      const parsed = log.sessionKey ? parseSessionKey(log.sessionKey) : null;
+      if (!parsed) return;
+      const db = _getDb(parsed.workspace);
+      if (!db) return;
+      const hasToolSteps = log.steps.some(s => s.type === 'tool');
+      if (!hasToolSteps && this.ws && this.ws.readyState === 1) { this.fetchToolCallsFromHistory(log.sessionKey, parsed, db, log, runId); return; }
+      this.saveActivityToMessage(parsed, db, log, runId);
+    }
+
+    fetchToolCallsFromHistory(sessionKey, parsed, db, log, runId) {
+      const reqId = `activity-hist-${runId}`;
+      const timeout = setTimeout(() => { this._pendingActivityCallbacks?.delete(reqId); this.saveActivityToMessage(parsed, db, log, runId); }, 5000);
+      if (!this._pendingActivityCallbacks) this._pendingActivityCallbacks = new Map();
+      this._pendingActivityCallbacks.set(reqId, (payload) => {
+        clearTimeout(timeout);
+        if (payload?.messages) {
+          for (let i = payload.messages.length - 1; i >= 0; i--) {
+            const m = payload.messages[i];
+            if (m.role === 'assistant' && Array.isArray(m.content)) {
+              let hasToolUse = false;
+              for (const block of m.content) {
+                if (block.type === 'text' && block.text?.trim()) log.steps.push({ type: 'assistant', timestamp: Date.now(), text: block.text.trim() });
+                if (block.type === 'tool_use') { hasToolUse = true; log.steps.push({ type: 'tool', timestamp: Date.now(), name: block.name || 'unknown', phase: 'done', toolCallId: block.id, meta: this.extractToolMeta(block), isError: false }); }
+              }
+              if (hasToolUse) { const lastAssistantIdx = log.steps.findLastIndex(s => s.type === 'assistant'); if (lastAssistantIdx >= 0) log.steps.splice(lastAssistantIdx, 1); }
+              else log.steps = log.steps.filter(s => s.type !== 'assistant');
+              break;
+            }
+          }
+        }
+        this.saveActivityToMessage(parsed, db, log, runId);
+        this.broadcastActivityUpdate(runId, log);
+      });
+      this.ws.send(JSON.stringify({ type: 'req', id: reqId, method: 'sessions.history', params: { key: sessionKey, limit: 3, includeTools: true } }));
+    }
+
+    extractToolMeta(toolUseBlock) {
+      if (!toolUseBlock.input) return '';
+      const input = toolUseBlock.input;
+      if (input.query) return input.query;
+      if (input.command) return input.command.substring(0, 80);
+      if (input.file_path || input.path) return input.file_path || input.path;
+      if (input.url) return input.url;
+      if (input.text) return input.text.substring(0, 60);
+      return '';
+    }
+
+    saveActivityToMessage(parsed, db, log, runId) {
+      setTimeout(() => {
+        try {
+          const msg = db.prepare('SELECT id, metadata FROM messages WHERE thread_id = ? AND role = ? ORDER BY timestamp DESC LIMIT 1').get(parsed.threadId, 'assistant');
+          if (msg) {
+            const toolSteps = log.steps.filter(s => s.type === 'tool' && s.phase !== 'update');
+            const thinkingSteps = log.steps.filter(s => s.type === 'thinking');
+            const narrativeSteps = log.steps.filter(s => s.type === 'assistant' && s.text?.trim());
+            if (toolSteps.length > 0 || thinkingSteps.length > 0 || narrativeSteps.length > 0) {
+              const metadata = msg.metadata ? JSON.parse(msg.metadata) : {};
+              metadata.activityLog = log.steps.map(s => { const clean = { ...s }; delete clean._sealed; return clean; });
+              metadata.activitySummary = this.generateActivitySummary(log.steps);
+              db.prepare('UPDATE messages SET metadata = ? WHERE id = ?').run(JSON.stringify(metadata), msg.id);
+              console.log(`[ActivityLog] Saved ${toolSteps.length} tool steps for message ${msg.id}`);
+              this.broadcastToBrowsers(JSON.stringify({ type: 'shellchat', event: 'activity-saved', workspace: parsed.workspace, threadId: parsed.threadId, messageId: msg.id }));
+            }
+          }
+        } catch (e) { console.error('Failed to save activity log:', e.message); }
+        this.activityLogs.delete(runId);
+      }, 1000);
+    }
+
+    generateActivitySummary(steps) {
+      const toolSteps = steps.filter(s => s.type === 'tool' && s.phase !== 'result' && s.phase !== 'update');
+      const hasThinking = steps.some(s => s.type === 'thinking' && s.text);
+      const hasNarration = steps.some(s => s.type === 'assistant' && s.text?.trim());
+      if (toolSteps.length === 0 && !hasThinking && !hasNarration) return null;
+      if (toolSteps.length === 0 && hasThinking) return 'Reasoned through the problem';
+      if (toolSteps.length === 0 && hasNarration) return 'Processed in multiple steps';
+      const counts = {};
+      for (const s of toolSteps) { const name = s.name || 'unknown'; counts[name] = (counts[name] || 0) + 1; }
+      const parts = [];
+      const toolNames = { 'web_search': 'searched the web', 'web_fetch': 'fetched web pages', 'Read': 'read files', 'read': 'read files', 'Write': 'wrote files', 'write': 'wrote files', 'Edit': 'edited files', 'edit': 'edited files', 'exec': 'ran commands', 'Bash': 'ran commands', 'browser': 'browsed the web', 'memory_search': 'searched memory', 'memory_store': 'saved to memory', 'image': 'analyzed images', 'message': 'sent messages', 'sessions_spawn': 'spawned sub-agents', 'cron': 'managed cron jobs', 'Grep': 'searched code', 'grep': 'searched code', 'Glob': 'found files', 'glob': 'found files' };
+      for (const [name, count] of Object.entries(counts)) { const friendly = toolNames[name]; if (friendly) parts.push(count > 1 ? `${friendly} (${count}x)` : friendly); else parts.push(count > 1 ? `used ${name} (${count}x)` : `used ${name}`); }
+      if (parts.length === 0) return null;
+      if (parts.length === 1) return parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+      const last = parts.pop();
+      return (parts.join(', ') + ' and ' + last).replace(/^./, c => c.toUpperCase());
+    }
+
+    addBroadcastTarget(fn) { this._externalBroadcastTargets.push(fn); }
+    removeBroadcastTarget(fn) { this._externalBroadcastTargets = this._externalBroadcastTargets.filter(f => f !== fn); }
+
+    broadcastToBrowsers(data) {
+      _debugLogger.logFrame('SRV→BR', data);
+      for (const client of this.browserClients.keys()) {
+        if (client.readyState === WS.OPEN) client.send(data);
+      }
+      for (const fn of this._externalBroadcastTargets) {
+        try { fn(data); } catch { /* target disconnected */ }
+      }
+    }
+
+    broadcastGatewayStatus(connected) {
+      this.broadcastToBrowsers(JSON.stringify({ type: 'shellchat', event: 'gateway-status', connected }));
+    }
+
+    sendToGateway(data) {
+      _debugLogger.logFrame('SRV→GW', data);
+      if (this.ws && this.ws.readyState === WS.OPEN) this.ws.send(data);
+      else console.error('Cannot send to gateway: not connected');
+    }
+
+    scheduleReconnect() {
+      const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay);
+      this.reconnectAttempts++;
+      console.log(`Reconnecting to gateway in ${delay}ms (attempt ${this.reconnectAttempts})...`);
+      setTimeout(() => this.connect(), delay);
+    }
+
+    addBrowserClient(ws) {
+      this.browserClients.set(ws, { activeWorkspace: null, activeThreadId: null });
+      if (ws.readyState === WS.OPEN) {
+        ws.send(JSON.stringify({ type: 'shellchat', event: 'gateway-status', connected: this.connected }));
+        const streams = [];
+        for (const [sessionKey, state] of this.streamState.entries()) {
+          if (state.state === 'streaming') streams.push({ sessionKey, threadId: state.threadId, buffer: state.buffer });
+        }
+        if (streams.length > 0) ws.send(JSON.stringify({ type: 'shellchat', event: 'stream-sync', streams }));
+      }
+    }
+
+    removeBrowserClient(ws) { this.browserClients.delete(ws); }
+
+    setActiveThread(ws, workspace, threadId) {
+      const client = this.browserClients.get(ws);
+      if (client) { client.activeWorkspace = workspace; client.activeThreadId = threadId; }
+      if (workspace && threadId) {
+        try {
+          const wsData = _getWorkspaces();
+          if (!wsData.workspaces[workspace]) return;
+          const db = _getDb(workspace);
+          const thread = db.prepare('SELECT id FROM threads WHERE id = ?').get(threadId);
+          if (!thread) return;
+          const deleted = db.prepare('DELETE FROM unread_messages WHERE thread_id = ?').run(threadId);
+          if (deleted.changes > 0) {
+            syncThreadUnreadCount(db, threadId);
+            const workspaceUnreadTotal = db.prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get().total;
+            this.broadcastToBrowsers(JSON.stringify({ type: 'shellchat', event: 'unread-update', workspace, threadId, action: 'clear', unreadCount: 0, workspaceUnreadTotal, timestamp: Date.now() }));
+          }
+        } catch (e) { console.error('Failed to auto-clear unreads on active-thread:', e.message); }
+      }
+    }
+  }
+
+  const _gatewayClient = new _GatewayClient();
+
+  // ── handleRequest (scoped to factory state) ────────────────────────────────
+  async function _handleRequest(req, res) {
+    const [urlPath, queryString] = (req.url || '/').split('?');
+    const query = {};
+    if (queryString) {
+      for (const pair of queryString.split('&')) {
+        const [k, v] = pair.split('=');
+        if (k) query[decodeURIComponent(k)] = decodeURIComponent(v || '');
+      }
+    }
+    const method = req.method;
+
+    if (method === 'OPTIONS') { setCors(res); res.writeHead(204); return res.end(); }
+
+    if (method === 'GET' && !urlPath.startsWith('/api/')) {
+      const STATIC_FILES = { '/': 'index.html', '/index.html': 'index.html', '/app.js': 'app.js', '/style.css': 'style.css', '/error-handler.js': 'error-handler.js', '/manifest.json': 'manifest.json', '/favicon.ico': 'favicon.ico' };
+      const fileName = STATIC_FILES[urlPath];
+      const isIcon = urlPath.startsWith('/icons/');
+      const isLib = urlPath.startsWith('/lib/');
+      const isFrontend = urlPath.startsWith('/frontend/');
+      const isConfig = urlPath === '/config.js';
+      const staticPath = fileName ? path.join(__dirname, fileName) : (isIcon || isLib || isFrontend || isConfig) ? path.join(__dirname, urlPath.slice(1)) : null;
+      if (staticPath && fs.existsSync(staticPath) && fs.statSync(staticPath).isFile()) {
+        const ext = path.extname(staticPath).toLowerCase();
+        const mimeMap = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.ico': 'image/x-icon', '.png': 'image/png', '.svg': 'image/svg+xml' };
+        const ct = mimeMap[ext] || 'application/octet-stream';
+        const stat = fs.statSync(staticPath);
+        res.writeHead(200, { 'Content-Type': ct, 'Content-Length': stat.size, 'Cache-Control': ext === '.html' ? 'no-cache' : 'public, max-age=3600' });
+        return fs.createReadStream(staticPath).pipe(res);
+      }
+    }
+
+    let p;
+    if ((p = matchRoute(method, urlPath, 'GET /api/uploads/:threadId/:fileId'))) return _handleServeUpload(req, res, p);
+
+    if (!_checkAuth(req, res)) return;
+
+    try {
+      if (method === 'GET' && urlPath === '/api/file') return handleServeFile(req, res, query);
+      if (method === 'GET' && urlPath === '/api/workspace') return handleWorkspaceList(req, res, query);
+      if (method === 'GET' && urlPath === '/api/workspace/file') return handleWorkspaceFileRead(req, res, query);
+      if (method === 'PUT' && urlPath === '/api/workspace/file') return await handleWorkspaceFileWrite(req, res, query);
+      if (method === 'POST' && urlPath === '/api/workspace/upload') return await handleWorkspaceUpload(req, res, query);
+      if (method === 'GET' && urlPath === '/api/memory/status') return await _handleMemoryStatus(req, res);
+      if (method === 'GET' && urlPath === '/api/memory/list') return await _handleMemoryList(req, res, query);
+      if (method === 'GET' && urlPath === '/api/memory/search') return await _handleMemorySearch(req, res, query);
+      if (method === 'GET' && urlPath === '/api/memory/files') return _handleMemoryFiles(req, res, query);
+      if ((p = matchRoute(method, urlPath, 'PUT /api/memory/:id'))) return await _handleMemoryUpdate(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'DELETE /api/memory/:id'))) return await _handleMemoryDelete(req, res, p);
+      if (method === 'GET' && urlPath === '/api/settings') return _handleGetSettings(req, res);
+      if (method === 'PUT' && urlPath === '/api/settings') return await _handleSaveSettings(req, res);
+      if (method === 'POST' && urlPath === '/api/transcribe') return await handleTranscribe(req, res);
+      if (method === 'GET' && urlPath === '/api/workspaces') return _handleGetWorkspaces(req, res);
+      if (method === 'POST' && urlPath === '/api/workspaces') return await _handleCreateWorkspace(req, res);
+      if ((p = matchRoute(method, urlPath, 'PATCH /api/workspaces/:name'))) return await _handleUpdateWorkspace(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'DELETE /api/workspaces/:name'))) return _handleDeleteWorkspace(req, res, p);
+      if (method === 'POST' && urlPath === '/api/workspaces/reorder') return await _handleReorderWorkspaces(req, res);
+      if ((p = matchRoute(method, urlPath, 'POST /api/workspaces/:name/activate'))) return _handleActivateWorkspace(req, res, p);
+      if (method === 'GET' && urlPath === '/api/threads') return _handleGetThreads(req, res, {}, query);
+      if (method === 'GET' && urlPath === '/api/threads/unread') return _handleGetUnreadThreads(req, res);
+      if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/mark-read'))) return await _handleMarkMessagesRead(req, res, p);
+      if (method === 'POST' && urlPath === '/api/threads') return await _handleCreateThread(req, res);
+      if ((p = matchRoute(method, urlPath, 'GET /api/threads/:id/messages'))) return _handleGetMessages(req, res, p, query);
+      if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/messages'))) return await _handleCreateMessage(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'DELETE /api/threads/:id/messages/:messageId'))) return _handleDeleteMessage(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/context-fill'))) return _handleContextFill(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/upload'))) return await _handleUpload(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'GET /api/threads/:id/intelligence'))) return _handleGetIntelligence(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'POST /api/threads/:id/intelligence'))) return await _handleSaveIntelligence(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'GET /api/threads/:id'))) return _handleGetThread(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'PATCH /api/threads/:id'))) return await _handleUpdateThread(req, res, p);
+      if ((p = matchRoute(method, urlPath, 'DELETE /api/threads/:id'))) return _handleDeleteThread(req, res, p);
+      if (method === 'GET' && urlPath === '/api/search') return _handleSearch(req, res, {}, query);
+      if (method === 'GET' && urlPath === '/api/export') return _handleExport(req, res);
+      if (method === 'POST' && urlPath === '/api/import') return await _handleImport(req, res);
+      if (method === 'POST' && urlPath === '/api/active-thread') {
+        const body = JSON.parse(await parseBody(req));
+        const { threadId, workspace } = body;
+        if (threadId && workspace) _gatewayClient.setActiveThread(null, workspace, threadId);
+        return send(res, 200, { ok: true });
+      }
+      if (method === 'GET' && urlPath === '/api/health') return send(res, 200, { ok: true, workspace: _getWorkspaces().active, uptime: process.uptime() });
+      sendError(res, 404, `Not found: ${method} ${urlPath}`);
+    } catch (err) {
+      console.error(`Error handling ${method} ${urlPath}:`, err);
+      if (err.message && err.message.includes('UNIQUE constraint')) sendError(res, 409, 'Conflict: ' + err.message);
+      else sendError(res, 500, err.message || 'Internal server error');
+    }
+  }
+
+  // ── Browser WebSocket setup (shared logic for standalone and plugin) ────────
+  function _setupBrowserWs(wssInstance) {
+    wssInstance.on('connection', (ws) => {
+      console.log('Browser client connected');
+      _gatewayClient.addBrowserClient(ws);
+      const nonce = crypto.randomUUID();
+      ws.send(JSON.stringify({ type: 'event', event: 'connect.challenge', payload: { nonce, ts: Date.now() } }));
+
+      ws.on('message', (data) => {
+        const msgStr = data.toString();
+        _debugLogger.logFrame('BR→SRV', msgStr);
+        try {
+          const msg = JSON.parse(msgStr);
+          if (msg.type === 'req' && msg.method === 'connect') {
+            const token = msg.params?.auth?.token;
+            if (token === _AUTH_TOKEN || !_AUTH_TOKEN) {
+              console.log('Browser client authenticated');
+              ws.send(JSON.stringify({ type: 'res', id: msg.id, ok: true, payload: { type: 'hello-ok', protocol: 3, server: { version: '0.1.0', host: 'shellchat-backend' } } }));
+            } else {
+              console.log('Browser client auth failed');
+              ws.send(JSON.stringify({ type: 'res', id: msg.id, ok: false, error: { code: 'AUTH_FAILED', message: 'Invalid auth token' } }));
+              ws.close();
+            }
+            return;
+          }
+          if (msg.type === 'shellchat') {
+            if (msg.action === 'active-thread') { _gatewayClient.setActiveThread(ws, msg.workspace, msg.threadId); console.log(`Browser client set active thread: ${msg.workspace}/${msg.threadId}`); return; }
+            if (msg.action === 'debug-start') { const result = _debugLogger.start(msg.ts, ws); if (result.error === 'already-active') ws.send(JSON.stringify({ type: 'shellchat', event: 'debug-error', error: 'Recording already active in another tab', sessionId: result.sessionId })); else ws.send(JSON.stringify({ type: 'shellchat', event: 'debug-started', sessionId: result.sessionId })); return; }
+            if (msg.action === 'debug-dump') { const { sessionId, files } = _debugLogger.saveDump(msg); ws.send(JSON.stringify({ type: 'shellchat', event: 'debug-saved', sessionId, files })); return; }
+          }
+        } catch { /* Not JSON or not a ShellChat message, forward to gateway */ }
+        _gatewayClient.sendToGateway(msgStr);
+      });
+
+      ws.on('close', () => { console.log('Browser client disconnected'); _debugLogger.handleClientDisconnect(ws); _gatewayClient.removeBrowserClient(ws); });
+      ws.on('error', (err) => { console.error('Browser WebSocket error:', err.message); });
+    });
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+  _ensureDirs();
+
+  return {
+    handleRequest: _handleRequest,
+    getDb: _getDb,
+    getActiveDb: _getActiveDb,
+    migrate,
+    getWorkspaces: _getWorkspaces,
+    setWorkspaces: _setWorkspaces,
+    shutdown: _closeAllDbs,
+    closeAllDbs: _closeAllDbs,
+    gatewayClient: _gatewayClient,
+    setupBrowserWs: _setupBrowserWs,
+    dataDir: _DATA_DIR,
+  };
+}
+
+// ─── Server Startup (standalone mode only) ───────────────────────────────────
+
+const isDirectRun = import.meta.url === `file://${process.argv[1]}`;
+if (isDirectRun) {
+  const app = createApp();
+  app.getActiveDb(); // Eagerly open active workspace DB
+
+  const server = http.createServer(app.handleRequest);
+
+  // ─── Browser WebSocket Server ───────────────────────────────────────────────
+
+  const wss = new WebSocketServer({ noServer: true });
+  app.setupBrowserWs(wss);
+
+  // Handle WebSocket upgrade requests
+  server.on('upgrade', (req, socket, head) => {
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit('connection', ws, req);
+    });
+  });
+
+  server.listen(PORT, () => {
+    console.log(`ShellChat backend listening on port ${PORT}`);
+    console.log(`Active workspace: ${app.getWorkspaces().active}`);
+    console.log(`Data dir: ${app.dataDir}`);
+
+    // Connect to gateway
+    app.gatewayClient.connect();
+  });
+
+  // Graceful shutdown
+  function shutdown() {
+    console.log('Shutting down...');
+    app.shutdown();
+    server.close(() => process.exit(0));
+    // Force exit after 5s
+    setTimeout(() => process.exit(1), 5000);
+  }
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+}