@fyresmith/hive-server 2.3.1 → 2.4.0

package/lib/socketHandler.js

@@ -1,24 +1,46 @@
 import { socketMiddleware } from './auth.js';
 import * as vault from './vaultManager.js';
+import { serverAdapterRegistry } from './adapterRegistry.js';
+import { negotiateProtocol, PROTOCOL_V1 } from './collabProtocol.js';
+import { createCollabStore } from './collabStore.js';
+import { parseMentions } from './mentionUtils.js';
+import { sendDiscordWebhook } from './discordWebhook.js';
 
 /**
- * presenceByFile: file path → Set of socket IDs
+ * presenceByFile: file path -> Set of socket IDs
  * @type {Map<string, Set<string>>}
  */
 const presenceByFile = new Map();
 
 /**
- * socketToFiles: socket ID → Set of file paths (for cleanup on disconnect)
+ * socketToFiles: socket ID -> Set of file paths
  * @type {Map<string, Set<string>>}
  */
 const socketToFiles = new Map();
 
 /**
- * userBySocket: socket ID → user object
+ * userBySocket: socket ID -> user object
  * @type {Map<string, object>}
  */
 const userBySocket = new Map();
 
+/**
+ * presenceStateBySocket: socket ID -> transient presence state
+ * @type {Map<string, { lastSeenAt: number, protocolVersion: number, activeFile: string|null, cursor: any, viewport: any }>}
+ */
+const presenceStateBySocket = new Map();
+
+const collabStore = createCollabStore();
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/;
+
+const PRESENCE_STALE_MS = Math.max(
+  15000,
+  parseInt(process.env.HIVE_PRESENCE_STALE_MS ?? '45000', 10) || 45000,
+);
+const PRESENCE_SWEEP_MS = Math.min(15000, Math.max(5000, Math.trunc(PRESENCE_STALE_MS / 3)));
+
+let staleSweepTimer = null;
+
 function respond(cb, payload) {
   if (typeof cb === 'function') cb(payload);
 }
@@ -38,17 +60,243 @@ function normalizeHexColor(color) {
   return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed.toLowerCase() : null;
 }
 
+function normalizeExpectedHash(value) {
+  if (value === null) return null;
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (!SHA256_HEX_RE.test(normalized)) return undefined;
+  return normalized;
+}
+
+function parseHistoryLimit(raw) {
+  if (raw === undefined || raw === null) return 50;
+  const num = Number(raw);
+  if (!Number.isFinite(num)) return 50;
+  const int = Math.trunc(num);
+  if (int < 1) return 1;
+  if (int > 500) return 500;
+  return int;
+}
+
+function actorFromUser(user) {
+  return {
+    id: user?.id ?? null,
+    username: user?.username ?? null,
+  };
+}
+
+function getWorkspaceKey(filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return 'root';
+  const normalized = filePath.replace(/\\/g, '/');
+  const [head] = normalized.split('/');
+  return head || 'root';
+}
+
+function normalizeAdapterContent(relPath, content, cb) {
+  const adapter = serverAdapterRegistry.getByPath(relPath);
+  if (!adapter) return true;
+
+  const ok = adapter.validateContent(content);
+  if (!ok) {
+    respond(cb, {
+      ok: false,
+      code: 'BAD_REQUEST',
+      error: `Invalid payload for adapter ${adapter.adapterId}`,
+      adapterId: adapter.adapterId,
+    });
+  }
+  return ok;
+}
+
+function ensureState(socketId) {
+  let state = presenceStateBySocket.get(socketId);
+  if (!state) {
+    state = {
+      lastSeenAt: Date.now(),
+      protocolVersion: PROTOCOL_V1,
+      activeFile: null,
+      cursor: null,
+      viewport: null,
+    };
+    presenceStateBySocket.set(socketId, state);
+  }
+  return state;
+}
+
+function touchPresence(socketId, patch = null) {
+  const state = ensureState(socketId);
+  state.lastSeenAt = Date.now();
+  if (patch && typeof patch === 'object') {
+    if (patch.activeFile === null || typeof patch.activeFile === 'string') {
+      state.activeFile = patch.activeFile;
+    }
+    if (patch.cursor !== undefined) {
+      state.cursor = patch.cursor;
+    }
+    if (patch.viewport !== undefined) {
+      state.viewport = patch.viewport;
+    }
+    if (Number.isInteger(patch.protocolVersion)) {
+      state.protocolVersion = patch.protocolVersion;
+    }
+  }
+  presenceStateBySocket.set(socketId, state);
+  return state;
+}
+
+function presenceList() {
+  const out = [];
+  for (const [socketId, user] of userBySocket) {
+    const state = presenceStateBySocket.get(socketId);
+    const openFiles = [...(socketToFiles.get(socketId) ?? new Set())];
+    out.push({
+      socketId,
+      user,
+      openFiles,
+      activeFile: state?.activeFile ?? openFiles[0] ?? null,
+      cursor: state?.cursor ?? null,
+      viewport: state?.viewport ?? null,
+      lastSeenAt: state?.lastSeenAt ?? null,
+      stale: state ? (Date.now() - state.lastSeenAt) > PRESENCE_STALE_MS : true,
+    });
+  }
+  return out;
+}
+
+function getSocketsByUserId(userId) {
+  const out = [];
+  for (const [socketId, user] of userBySocket) {
+    if (user?.id === userId) out.push(socketId);
+  }
+  return out;
+}
+
+function getUsersByMention(mentionUsername) {
+  const username = String(mentionUsername).toLowerCase();
+  const seen = new Set();
+  const users = [];
+
+  for (const user of userBySocket.values()) {
+    if (!user?.id || !user?.username) continue;
+    if (String(user.username).toLowerCase() !== username) continue;
+    if (seen.has(user.id)) continue;
+    seen.add(user.id);
+    users.push(user);
+  }
+
+  return users;
+}
+
+async function maybeDeliverNotifyEvent(io, event) {
+  const decision = await collabStore.shouldDeliverNotification(event.targetUser.id, event.filePath, event.kind);
+  if (!decision.deliver) {
+    return;
+  }
+
+  const payload = {
+    ...event,
+    mode: decision.mode,
+    ts: Date.now(),
+  };
+
+  const targetSockets = getSocketsByUserId(event.targetUser.id);
+  for (const socketId of targetSockets) {
+    io.to(socketId).emit('collab:notify:event', payload);
+  }
+
+  await sendDiscordWebhook(payload);
+}
+
+function activityRoomForWorkspace() {
+  return 'collab:activity:workspace';
+}
+
+function activityRoomForFile(filePath) {
+  return `collab:activity:file:${filePath}`;
+}
+
+function publishActivity(io, activity) {
+  io.to(activityRoomForWorkspace()).emit('collab:activity:event', { activity });
+  if (activity?.filePath) {
+    io.to(activityRoomForFile(activity.filePath)).emit('collab:activity:event', { activity });
+  }
+}
+
+async function recordActivity(io, { type, filePath = null, actor = null, payload = null, groupKey = null }) {
+  const activity = await collabStore.recordActivity({
+    type,
+    filePath,
+    actor,
+    payload,
+    groupKey,
+  });
+  publishActivity(io, activity);
+  return activity;
+}
+
+async function getCurrentHash(relPath) {
+  try {
+    const currentContent = await vault.readFile(relPath);
+    return vault.hashContent(currentContent);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function ensureStaleSweep(io) {
+  if (staleSweepTimer) return;
+
+  staleSweepTimer = setInterval(() => {
+    const now = Date.now();
+
+    for (const [socketId, state] of presenceStateBySocket) {
+      if (state.protocolVersion < 2) continue;
+      if (now - state.lastSeenAt <= PRESENCE_STALE_MS) continue;
+
+      const user = userBySocket.get(socketId);
+      const openFiles = socketToFiles.get(socketId) ?? new Set();
+
+      for (const relPath of openFiles) {
+        presenceByFile.get(relPath)?.delete(socketId);
+        io.emit('presence-file-closed', {
+          relPath,
+          user,
+          stale: true,
+        });
+      }
+
+      openFiles.clear();
+      socketToFiles.set(socketId, openFiles);
+      state.activeFile = null;
+      state.cursor = null;
+      state.viewport = null;
+      state.lastSeenAt = now;
+
+      io.emit('collab:presence:stale', {
+        user,
+        socketId,
+        ts: now,
+      });
+    }
+  }, PRESENCE_SWEEP_MS);
+
+  if (typeof staleSweepTimer.unref === 'function') {
+    staleSweepTimer.unref();
+  }
+}
+
 /**
  * Attach all Socket.IO event handlers.
  *
  * @param {import('socket.io').Server} io
- * @param {() => Set<string>} getActiveRooms  - returns encoded docNames currently in Yjs
+ * @param {() => Set<string>} getActiveRooms - returns encoded docNames currently in Yjs
  * @param {(relPath: string, hash: string, excludeSocketId: string|null) => void} broadcastFileUpdated
  * @param {(relPath: string) => Promise<void>} forceCloseRoom
  */
 export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCloseRoom) {
-  // Auth middleware for every socket connection
   io.use(socketMiddleware);
+  ensureStaleSweep(io);
 
   io.on('connection', (socket) => {
     const user = socket.user;
@@ -56,14 +304,99 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
 
     userBySocket.set(socket.id, user);
     socketToFiles.set(socket.id, new Set());
+    touchPresence(socket.id);
 
-    // Notify others this user joined
     socket.broadcast.emit('user-joined', { user });
 
+    socket.on('collab:hello', (payload, cb) => {
+      try {
+        const negotiated = negotiateProtocol(payload, serverAdapterRegistry);
+        const protocolVersion = negotiated.negotiatedProtocol;
+        touchPresence(socket.id, { protocolVersion });
+        respond(cb, { ok: true, ...negotiated });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:presence:heartbeat', (payload, cb) => {
+      const relPath = typeof payload?.activeFile === 'string' ? payload.activeFile : null;
+      if (relPath && !isAllowedPath(relPath)) {
+        rejectPath(cb, relPath);
+        return;
+      }
+
+      const state = touchPresence(socket.id, {
+        activeFile: relPath,
+        cursor: payload?.cursor ?? null,
+        viewport: payload?.viewport ?? null,
+      });
+
+      socket.broadcast.emit('collab:presence:heartbeat', {
+        user,
+        location: {
+          activeFile: state.activeFile,
+          cursor: state.cursor,
+          viewport: state.viewport,
+        },
+        ts: state.lastSeenAt,
+      });
+
+      respond(cb, {
+        ok: true,
+        lastSeenAt: state.lastSeenAt,
+      });
+    });
+
+    socket.on('collab:presence:list', (_payload, cb) => {
+      respond(cb, {
+        ok: true,
+        users: presenceList(),
+      });
+    });
+
+    socket.on('collab:presence:jump', (payload, cb) => {
+      const userId = payload?.userId;
+      if (typeof userId !== 'string' || userId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing userId' });
+        return;
+      }
+
+      let target = null;
+      for (const [socketId, currentUser] of userBySocket) {
+        if (currentUser?.id !== userId) continue;
+        const state = presenceStateBySocket.get(socketId);
+        const openFiles = [...(socketToFiles.get(socketId) ?? new Set())];
+        const activeFile = state?.activeFile ?? openFiles[0] ?? null;
+        if (!activeFile) continue;
+        target = {
+          user: currentUser,
+          location: {
+            activeFile,
+            cursor: state?.cursor ?? null,
+            viewport: state?.viewport ?? null,
+          },
+        };
+        break;
+      }
+
+      if (!target) {
+        respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Collaborator location unavailable' });
+        return;
+      }
+
+      respond(cb, {
+        ok: true,
+        ...target,
+      });
+    });
+
     // -----------------------------------------------------------------------
-    // vault-sync-request
+    // Legacy sync events (kept for v1 compatibility)
     // -----------------------------------------------------------------------
+
     socket.on('vault-sync-request', async (cb) => {
+      touchPresence(socket.id);
       try {
         const manifest = await vault.getManifest();
         respond(cb, { ok: true, manifest });
@@ -73,10 +406,8 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
     });
 
-    // -----------------------------------------------------------------------
-    // file-read
-    // -----------------------------------------------------------------------
     socket.on('file-read', async (relPath, cb) => {
+      touchPresence(socket.id);
       if (!isAllowedPath(relPath)) {
         rejectPath(cb, relPath);
         return;
@@ -91,21 +422,56 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
     });
 
-    // -----------------------------------------------------------------------
-    // file-write
-    // -----------------------------------------------------------------------
     socket.on('file-write', async (payload, cb) => {
+      touchPresence(socket.id);
       const relPath = payload?.relPath;
       const content = payload?.content;
+      const expectedHash = normalizeExpectedHash(payload?.expectedHash);
       if (!isAllowedPath(relPath) || typeof content !== 'string') {
         rejectPath(cb, relPath);
         return;
       }
+      if (payload?.expectedHash !== undefined && expectedHash === undefined) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Invalid expectedHash' });
+        return;
+      }
+      if (!normalizeAdapterContent(relPath, content, cb)) {
+        return;
+      }
+
       try {
-        await vault.writeFile(relPath, content);
+        const currentHash = await getCurrentHash(relPath);
+        if (expectedHash !== undefined && expectedHash !== currentHash) {
+          respond(cb, {
+            ok: false,
+            code: 'CONFLICT',
+            error: 'Write conflict: file changed on server',
+            relPath,
+            currentHash,
+          });
+          return;
+        }
+
+        await vault.writeFile(relPath, content, {
+          history: {
+            action: 'write',
+            source: 'socket',
+            actor: actorFromUser(user),
+          },
+        });
         const hash = vault.hashContent(content);
         socket.broadcast.emit('file-updated', { relPath, hash, user });
-        respond(cb, { ok: true, hash });
+        broadcastFileUpdated?.(relPath, hash, socket.id);
+        respond(cb, { ok: true, hash, previousHash: currentHash });
+
+        await recordActivity(io, {
+          type: 'edit',
+          filePath: relPath,
+          actor: actorFromUser(user),
+          payload: { source: 'socket', adapterId: serverAdapterRegistry.getByPath(relPath)?.adapterId ?? null },
+          groupKey: `${user.id}:${relPath}:edit`,
+        });
+
         console.log(`[socket] file-write: ${relPath} by ${user.username}`);
       } catch (err) {
         console.error(`[socket] file-write error (${relPath}):`, err);
@@ -113,20 +479,38 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
     });
 
-    // -----------------------------------------------------------------------
-    // file-create
-    // -----------------------------------------------------------------------
     socket.on('file-create', async (payload, cb) => {
+      touchPresence(socket.id);
       const relPath = payload?.relPath;
       const content = payload?.content;
       if (!isAllowedPath(relPath) || typeof content !== 'string') {
         rejectPath(cb, relPath);
         return;
       }
+      if (!normalizeAdapterContent(relPath, content, cb)) {
+        return;
+      }
+
       try {
-        await vault.writeFile(relPath, content);
+        await vault.writeFile(relPath, content, {
+          history: {
+            action: 'create',
+            source: 'socket',
+            actor: actorFromUser(user),
+          },
+        });
+        const hash = vault.hashContent(content);
         io.emit('file-created', { relPath, user });
-        respond(cb, { ok: true });
+        respond(cb, { ok: true, hash });
+
+        await recordActivity(io, {
+          type: 'create',
+          filePath: relPath,
+          actor: actorFromUser(user),
+          payload: { source: 'socket' },
+          groupKey: `${user.id}:${relPath}:create`,
+        });
+
         console.log(`[socket] file-create: ${relPath} by ${user.username}`);
       } catch (err) {
         console.error(`[socket] file-create error (${relPath}):`, err);
@@ -134,23 +518,35 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
     });
 
-    // -----------------------------------------------------------------------
-    // file-delete
-    // -----------------------------------------------------------------------
     socket.on('file-delete', async (relPath, cb) => {
+      touchPresence(socket.id);
       if (!isAllowedPath(relPath)) {
         rejectPath(cb, relPath);
         return;
       }
       try {
-        // Force-close active Yjs room first
         const docName = encodeURIComponent(relPath);
         if (getActiveRooms().has(docName)) {
           await forceCloseRoom(relPath);
         }
-        await vault.deleteFile(relPath);
+        await vault.deleteFile(relPath, {
+          history: {
+            action: 'delete',
+            source: 'socket',
+            actor: actorFromUser(user),
+          },
+        });
         io.emit('file-deleted', { relPath, user });
         respond(cb, { ok: true });
+
+        await recordActivity(io, {
+          type: 'delete',
+          filePath: relPath,
+          actor: actorFromUser(user),
+          payload: { source: 'socket' },
+          groupKey: `${user.id}:${relPath}:delete`,
+        });
+
         console.log(`[socket] file-delete: ${relPath} by ${user.username}`);
       } catch (err) {
         console.error(`[socket] file-delete error (${relPath}):`, err);
@@ -158,10 +554,8 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
     });
 
-    // -----------------------------------------------------------------------
-    // file-rename
-    // -----------------------------------------------------------------------
     socket.on('file-rename', async (payload, cb) => {
+      touchPresence(socket.id);
       const oldPath = payload?.oldPath;
       const newPath = payload?.newPath;
       if (!isAllowedPath(oldPath) || !isAllowedPath(newPath)) {
@@ -169,48 +563,506 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
         return;
       }
       try {
-        // Force-close active Yjs room for old path
         const docName = encodeURIComponent(oldPath);
         if (getActiveRooms().has(docName)) {
           await forceCloseRoom(oldPath);
         }
-        await vault.renameFile(oldPath, newPath);
+        await vault.renameFile(oldPath, newPath, {
+          history: {
+            source: 'socket',
+            actor: actorFromUser(user),
+          },
+        });
         io.emit('file-renamed', { oldPath, newPath, user });
         respond(cb, { ok: true });
-        console.log(`[socket] file-rename: ${oldPath} → ${newPath} by ${user.username}`);
+
+        await recordActivity(io, {
+          type: 'rename',
+          filePath: newPath,
+          actor: actorFromUser(user),
+          payload: { oldPath, newPath, source: 'socket' },
+          groupKey: `${user.id}:${oldPath}:rename`,
+        });
+
+        console.log(`[socket] file-rename: ${oldPath} -> ${newPath} by ${user.username}`);
       } catch (err) {
         console.error(`[socket] file-rename error (${oldPath}):`, err);
         respond(cb, { ok: false, error: err.message });
       }
     });
 
-    // -----------------------------------------------------------------------
-    // presence-file-opened
-    // -----------------------------------------------------------------------
+    socket.on('file-history-list', async (payload, cb) => {
+      touchPresence(socket.id);
+      const relPath = payload?.relPath;
+      if (!isAllowedPath(relPath)) {
+        rejectPath(cb, relPath);
+        return;
+      }
+      try {
+        const limit = parseHistoryLimit(payload?.limit);
+        const versions = await vault.listFileHistory(relPath, limit);
+        respond(cb, { ok: true, versions });
+      } catch (err) {
+        console.error(`[socket] file-history-list error (${relPath}):`, err);
+        respond(cb, { ok: false, error: err.message });
+      }
+    });
+
+    socket.on('file-history-read', async (payload, cb) => {
+      touchPresence(socket.id);
+      const relPath = payload?.relPath;
+      const versionId = payload?.versionId;
+      if (!isAllowedPath(relPath)) {
+        rejectPath(cb, relPath);
+        return;
+      }
+      if (typeof versionId !== 'string' || versionId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing versionId' });
+        return;
+      }
+      try {
+        const version = await vault.readFileHistoryVersion(relPath, versionId);
+        respond(cb, { ok: true, version });
+      } catch (err) {
+        console.error(`[socket] file-history-read error (${relPath} @ ${versionId}):`, err);
+        respond(cb, { ok: false, error: err.message });
+      }
+    });
+
     socket.on('presence-file-opened', (payload) => {
       const relPath = typeof payload === 'string' ? payload : payload?.relPath;
       const color = normalizeHexColor(typeof payload === 'string' ? null : payload?.color);
       if (!isAllowedPath(relPath)) return;
+
       if (!presenceByFile.has(relPath)) presenceByFile.set(relPath, new Set());
       presenceByFile.get(relPath).add(socket.id);
       socketToFiles.get(socket.id)?.add(relPath);
+
+      touchPresence(socket.id, { activeFile: relPath });
       const presenceUser = color ? { ...user, color } : user;
       socket.broadcast.emit('presence-file-opened', { relPath, user: presenceUser });
     });
 
-    // -----------------------------------------------------------------------
-    // presence-file-closed
-    // -----------------------------------------------------------------------
     socket.on('presence-file-closed', (relPath) => {
       if (!isAllowedPath(relPath)) return;
       presenceByFile.get(relPath)?.delete(socket.id);
       socketToFiles.get(socket.id)?.delete(relPath);
+
+      const state = touchPresence(socket.id);
+      if (state.activeFile === relPath) {
+        state.activeFile = null;
+      }
+
       socket.broadcast.emit('presence-file-closed', { relPath, user });
     });
 
     // -----------------------------------------------------------------------
-    // disconnect
+    // Collaboration artifacts / activity / notifications
     // -----------------------------------------------------------------------
+
+    socket.on('collab:thread:list', async (payload, cb) => {
+      touchPresence(socket.id);
+      const filePath = payload?.filePath;
+      if (filePath && !isAllowedPath(filePath)) {
+        rejectPath(cb, filePath);
+        return;
+      }
+
+      try {
+        const threads = await collabStore.listThreads({
+          filePath: filePath ?? null,
+          status: payload?.status ?? null,
+        });
+        respond(cb, { ok: true, threads });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:thread:create', async (payload, cb) => {
+      touchPresence(socket.id);
+      const filePath = payload?.filePath;
+      if (!isAllowedPath(filePath)) {
+        rejectPath(cb, filePath);
+        return;
+      }
+
+      try {
+        const body = typeof payload?.body === 'string' ? payload.body : '';
+        const mentions = parseMentions(body);
+        const thread = await collabStore.createThread({
+          filePath,
+          anchor: payload?.anchor ?? null,
+          author: actorFromUser(user),
+          body,
+          mentions,
+        });
+
+        io.emit('collab:thread:created', { thread });
+        await recordActivity(io, {
+          type: 'comment',
+          filePath,
+          actor: actorFromUser(user),
+          payload: { threadId: thread.threadId, kind: 'thread-created' },
+          groupKey: `${user.id}:${filePath}:comment`,
+        });
+
+        if (mentions.length > 0) {
+          for (const mention of mentions) {
+            const targets = getUsersByMention(mention);
+            for (const targetUser of targets) {
+              if (targetUser.id === user.id) continue;
+              await maybeDeliverNotifyEvent(io, {
+                kind: 'mention',
+                filePath,
+                actor: actorFromUser(user),
+                targetUser,
+                threadId: thread.threadId,
+                body,
+              });
+            }
+          }
+        }
+
+        respond(cb, { ok: true, thread });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:thread:update', async (payload, cb) => {
+      touchPresence(socket.id);
+      const threadId = payload?.threadId;
+      if (typeof threadId !== 'string' || threadId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing threadId' });
+        return;
+      }
+
+      try {
+        const thread = await collabStore.updateThread({
+          threadId,
+          patch: payload?.patch ?? {},
+        });
+        if (!thread) {
+          respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Thread not found' });
+          return;
+        }
+
+        io.emit('collab:thread:updated', { thread });
+        await recordActivity(io, {
+          type: 'comment',
+          filePath: thread.filePath,
+          actor: actorFromUser(user),
+          payload: { threadId: thread.threadId, kind: 'thread-updated' },
+          groupKey: `${user.id}:${thread.filePath}:comment`,
+        });
+
+        respond(cb, { ok: true, thread });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:thread:delete', async (payload, cb) => {
+      touchPresence(socket.id);
+      const threadId = payload?.threadId;
+      if (typeof threadId !== 'string' || threadId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing threadId' });
+        return;
+      }
+
+      try {
+        const thread = await collabStore.deleteThread(threadId);
+        if (!thread) {
+          respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Thread not found' });
+          return;
+        }
+
+        io.emit('collab:thread:deleted', { thread });
+        await recordActivity(io, {
+          type: 'comment',
+          filePath: thread.filePath,
+          actor: actorFromUser(user),
+          payload: { threadId, kind: 'thread-archived' },
+          groupKey: `${user.id}:${thread.filePath}:comment`,
+        });
+
+        respond(cb, { ok: true, thread });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:comment:create', async (payload, cb) => {
+      touchPresence(socket.id);
+      const threadId = payload?.threadId;
+      const body = typeof payload?.body === 'string' ? payload.body : '';
+      if (typeof threadId !== 'string' || threadId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing threadId' });
+        return;
+      }
+      if (body.trim().length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing comment body' });
+        return;
+      }
+
+      try {
+        const mentions = parseMentions(body);
+        const result = await collabStore.createComment({
+          threadId,
+          author: actorFromUser(user),
+          body,
+          mentions,
+        });
+        if (!result) {
+          respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Thread not found' });
+          return;
+        }
+
+        io.emit('collab:comment:created', {
+          threadId,
+          comment: result.comment,
+          thread: result.thread,
+        });
+
+        await recordActivity(io, {
+          type: 'comment',
+          filePath: result.thread.filePath,
+          actor: actorFromUser(user),
+          payload: { threadId, commentId: result.comment.commentId, kind: 'comment-created' },
+          groupKey: `${user.id}:${result.thread.filePath}:comment`,
+        });
+
+        if (mentions.length > 0) {
+          for (const mention of mentions) {
+            const targets = getUsersByMention(mention);
+            for (const targetUser of targets) {
+              if (targetUser.id === user.id) continue;
+              await maybeDeliverNotifyEvent(io, {
+                kind: 'mention',
+                filePath: result.thread.filePath,
+                actor: actorFromUser(user),
+                targetUser,
+                threadId,
+                body,
+              });
+            }
+          }
+        }
+
+        respond(cb, { ok: true, ...result });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:comment:update', async (payload, cb) => {
+      touchPresence(socket.id);
+      const threadId = payload?.threadId;
+      const commentId = payload?.commentId;
+      const body = typeof payload?.body === 'string' ? payload.body : '';
+      if (typeof threadId !== 'string' || threadId.length === 0 || typeof commentId !== 'string' || commentId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing threadId/commentId' });
+        return;
+      }
+
+      try {
+        const result = await collabStore.updateComment({ threadId, commentId, body });
+        if (!result) {
+          respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Comment not found' });
+          return;
+        }
+
+        io.emit('collab:comment:updated', {
+          threadId,
+          comment: result.comment,
+          thread: result.thread,
+        });
+
+        await recordActivity(io, {
+          type: 'comment',
+          filePath: result.thread.filePath,
+          actor: actorFromUser(user),
+          payload: { threadId, commentId, kind: 'comment-updated' },
+          groupKey: `${user.id}:${result.thread.filePath}:comment`,
+        });
+
+        respond(cb, { ok: true, ...result });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:comment:delete', async (payload, cb) => {
+      touchPresence(socket.id);
+      const threadId = payload?.threadId;
+      const commentId = payload?.commentId;
+      if (typeof threadId !== 'string' || threadId.length === 0 || typeof commentId !== 'string' || commentId.length === 0) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Missing threadId/commentId' });
+        return;
+      }
+
+      try {
+        const result = await collabStore.deleteComment({ threadId, commentId });
+        if (!result) {
+          respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Comment not found' });
+          return;
+        }
+
+        io.emit('collab:comment:deleted', {
+          threadId,
+          commentId,
+          thread: result.thread,
+        });
+
+        await recordActivity(io, {
+          type: 'comment',
+          filePath: result.thread.filePath,
+          actor: actorFromUser(user),
+          payload: { threadId, commentId, kind: 'comment-deleted' },
+          groupKey: `${user.id}:${result.thread.filePath}:comment`,
+        });
+
+        respond(cb, { ok: true, ...result });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:task:set-state', async (payload, cb) => {
+      touchPresence(socket.id);
+      const threadId = payload?.threadId;
+      const status = payload?.status;
+      if (typeof threadId !== 'string' || threadId.length === 0 || (status !== 'open' && status !== 'resolved')) {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'Invalid threadId/status' });
+        return;
+      }
+
+      try {
+        const result = await collabStore.setTaskState({
+          threadId,
+          status,
+          assignee: payload?.assignee ?? null,
+          dueAt: payload?.dueAt ?? null,
+        });
+        if (!result) {
+          respond(cb, { ok: false, code: 'NOT_FOUND', error: 'Thread not found' });
+          return;
+        }
+
+        io.emit('collab:task:updated', {
+          threadId,
+          task: result.task,
+          thread: result.thread,
+        });
+
+        await recordActivity(io, {
+          type: 'task',
+          filePath: result.thread.filePath,
+          actor: actorFromUser(user),
+          payload: { threadId, taskId: result.task.taskId, status },
+          groupKey: `${user.id}:${result.thread.filePath}:task`,
+        });
+
+        if (result.task.assignee?.username) {
+          const assigneeName = String(result.task.assignee.username).toLowerCase();
+          const targets = getUsersByMention(assigneeName);
+          for (const targetUser of targets) {
+            if (targetUser.id === user.id) continue;
+            await maybeDeliverNotifyEvent(io, {
+              kind: 'task',
+              filePath: result.thread.filePath,
+              actor: actorFromUser(user),
+              targetUser,
+              threadId,
+              body: `Task set to ${status}`,
+            });
+          }
+        }
+
+        respond(cb, { ok: true, ...result });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:activity:list', async (payload, cb) => {
+      touchPresence(socket.id);
+      const filePath = payload?.filePath ?? null;
+      if (filePath && !isAllowedPath(filePath)) {
+        rejectPath(cb, filePath);
+        return;
+      }
+
+      try {
+        const result = await collabStore.listActivity({
+          filePath,
+          types: Array.isArray(payload?.types) ? payload.types : null,
+          limit: payload?.limit,
+          cursor: payload?.cursor ?? null,
+        });
+        respond(cb, { ok: true, ...result });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:activity:subscribe', (payload, cb) => {
+      touchPresence(socket.id);
+      const scope = payload?.scope === 'file' ? 'file' : 'workspace';
+      const filePath = payload?.filePath ?? null;
+
+      if (scope === 'file') {
+        if (!isAllowedPath(filePath)) {
+          rejectPath(cb, filePath);
+          return;
+        }
+        socket.join(activityRoomForFile(filePath));
+      }
+
+      socket.join(activityRoomForWorkspace());
+      respond(cb, { ok: true, scope, filePath: filePath ?? null });
+    });
+
+    socket.on('collab:notify:preferences:get', async (_payload, cb) => {
+      touchPresence(socket.id);
+      try {
+        const preferences = await collabStore.getNotifyPreferences(user.id);
+        respond(cb, { ok: true, preferences });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
+    socket.on('collab:notify:preferences:set', async (payload, cb) => {
+      touchPresence(socket.id);
+      const scope = payload?.scope;
+      const key = payload?.key ?? null;
+      const mode = payload?.mode;
+
+      if (scope === 'file' && key && !isAllowedPath(key)) {
+        rejectPath(cb, key);
+        return;
+      }
+      if (scope === 'workspace' && typeof key !== 'string') {
+        respond(cb, { ok: false, code: 'BAD_REQUEST', error: 'workspace scope requires key' });
+        return;
+      }
+
+      try {
+        const preferences = await collabStore.setNotifyPreference({
+          userId: user.id,
+          scope,
+          key,
+          mode,
+        });
+
+        respond(cb, { ok: true, preferences });
+      } catch (err) {
+        respond(cb, { ok: false, error: err?.message ?? String(err) });
+      }
+    });
+
     socket.on('disconnect', () => {
       console.log(`[socket] Disconnected: ${user.username} (${socket.id})`);
       const openFiles = socketToFiles.get(socket.id) ?? new Set();
@@ -220,6 +1072,7 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
       socketToFiles.delete(socket.id);
       userBySocket.delete(socket.id);
+      presenceStateBySocket.delete(socket.id);
       socket.broadcast.emit('user-left', { user });
     });
   });