clay-server 2.26.0-beta.8 → 2.26.0

package/lib/project-debate.js

@@ -14,6 +14,13 @@ var matesModule = require("./mates");
  */
 function attachDebate(ctx) {
 
+  // For mate projects, enforce latest debate awareness prompt in CLAUDE.md
+  // so mates use the propose_debate MCP tool instead of writing files.
+  if (ctx.isMate) {
+    var _debateClaudeMdPath = path.join(ctx.cwd, "CLAUDE.md");
+    try { matesModule.enforceDebateAwareness(_debateClaudeMdPath); } catch (e) {}
+  }
+
   // --- Helpers shared with other modules ---
 
   function escapeRegex(str) {
@@ -156,14 +163,16 @@ function attachDebate(ctx) {
       setupStartedAt: d.setupStartedAt || null,
       round: d.round || 1,
       awaitingConcludeConfirm: !!d.awaitingConcludeConfirm,
+      awaitingUserFloor: !!d.awaitingUserFloor,
+      ownerId: d.ownerId || null,
     };
     ctx.sm.saveSessionFile(session);
   }
 
-  function restoreDebateFromState(session) {
+  function restoreDebateFromState(session, restoreUserId) {
     var ds = session.debateState;
     if (!ds) return null;
-    var userId = null; // Will be set when WS connects
+    var userId = restoreUserId || ds.ownerId || null;
     var mateCtx = matesModule.buildMateCtx(userId);
     var debate = {
       phase: ds.phase,
@@ -186,6 +195,8 @@ function attachDebate(ctx) {
       setupStartedAt: ds.setupStartedAt || null,
       briefPath: ds.briefPath || null,
       awaitingConcludeConfirm: !!ds.awaitingConcludeConfirm,
+      awaitingUserFloor: !!ds.awaitingUserFloor,
+      ownerId: ds.ownerId || userId,
     };
 
     // Fallback: if awaitingConcludeConfirm was not persisted, detect from history
@@ -255,26 +266,20 @@ function attachDebate(ctx) {
         debate.context = brief.context || "";
         debate.specialRequests = brief.specialRequests || null;
 
-        // Update panelists with roles from the brief
+        // Replace panelists with those selected in the brief
         if (brief.panelists && brief.panelists.length) {
-          for (var i = 0; i < brief.panelists.length; i++) {
-            var bp = brief.panelists[i];
-            for (var j = 0; j < debate.panelists.length; j++) {
-              if (debate.panelists[j].mateId === bp.mateId) {
-                debate.panelists[j].role = bp.role || "";
-                debate.panelists[j].brief = bp.brief || "";
-              }
-            }
-          }
+          debate.panelists = brief.panelists.map(function (bp) {
+            return { mateId: bp.mateId, role: bp.role || "", brief: bp.brief || "" };
+          });
         }
 
         // Rebuild name map with updated roles
         var mateCtx = debate.mateCtx || matesModule.buildMateCtx(null);
         debate.nameMap = buildDebateNameMap(debate.panelists, mateCtx);
 
-        // If debate was started from DM (no setupSessionId), go to reviewing phase
-        if (!debate.setupSessionId) {
-          console.log("[debate] Brief picked up from DM, entering review phase. Topic:", debate.topic);
+        // quickStart from DM or no setupSessionId: show brief card for user approval
+        if (!debate.setupSessionId || debate.quickStart) {
+          console.log("[debate] Brief picked up, entering review phase. Topic:", debate.topic);
           debate.phase = "reviewing";
           persistDebateState(session);
 
@@ -325,88 +330,18 @@ function attachDebate(ctx) {
   // --- Restore debate on reconnect ---
 
   function restoreDebateState(ws) {
-    var userId = ws._clayUser ? ws._clayUser.id : null;
-    var mateCtx = matesModule.buildMateCtx(userId);
-
+    // On server restart, SDK sessions are lost so debates cannot continue.
+    // Clear stale debate state instead of restoring dead UI.
     ctx.sm.sessions.forEach(function (session) {
-      // Already restored
-      if (session._debate) return;
-
-      // Has persisted debate state?
-      if (!session.debateState) return;
-
-      var phase = session.debateState.phase;
-      if (phase !== "preparing" && phase !== "reviewing" && phase !== "live") return;
-
-      // Restore _debate from persisted state
-      var debate = restoreDebateFromState(session);
-      if (!debate) return;
-
-      // Update mateCtx with the connected user's context
-      debate.mateCtx = mateCtx;
-      debate.nameMap = buildDebateNameMap(debate.panelists, mateCtx);
-
-      var moderatorProfile = ctx.getMateProfile(mateCtx, debate.moderatorId);
-
-      if (phase === "preparing") {
-        var briefPath = debate.briefPath;
-        if (!briefPath && debate.debateId) {
-          briefPath = path.join(ctx.cwd, ".clay", "debates", debate.debateId, "brief.json");
-        }
-        if (!briefPath) return;
-
-        console.log("[debate] Restoring debate (preparing). topic:", debate.topic, "briefPath:", briefPath);
-        startDebateBriefWatcher(session, debate, briefPath);
-
-        // Only show preparing indicator for quick start (standard setup shows skill in real-time)
-        if (debate.quickStart) {
-          ctx.sendTo(ws, {
-            type: "debate_preparing",
-            topic: debate.topic,
-            moderatorId: debate.moderatorId,
-            moderatorName: moderatorProfile.name,
-            setupSessionId: debate.setupSessionId,
-            panelists: debate.panelists.map(function (p) {
-              var prof = ctx.getMateProfile(mateCtx, p.mateId);
-              return { mateId: p.mateId, name: prof.name };
-            }),
-          });
-        }
-      } else if (phase === "reviewing") {
-        console.log("[debate] Restoring debate (reviewing). topic:", debate.topic);
-        ctx.sendTo(ws, {
-          type: "debate_brief_ready",
-          debateId: debate.debateId,
-          topic: debate.topic,
-          format: debate.format || "free_discussion",
-          context: debate.context || "",
-          specialRequests: debate.specialRequests || null,
-          moderatorId: debate.moderatorId,
-          moderatorName: moderatorProfile.name,
-          panelists: debate.panelists.map(function (p) {
-            var prof = ctx.getMateProfile(mateCtx, p.mateId);
-            return { mateId: p.mateId, name: prof.name, role: p.role || "", brief: p.brief || "" };
-          }),
-        });
-      } else if (phase === "live") {
-        console.log("[debate] Restoring debate (live). topic:", debate.topic, "awaitingConclude:", debate.awaitingConcludeConfirm);
-        // Debate was live when server restarted. It can't resume AI turns,
-        // but we can show the sticky and let user see history.
-        ctx.sendTo(ws, {
-          type: "debate_started",
-          topic: debate.topic,
-          format: debate.format,
-          round: debate.round,
-          moderatorId: debate.moderatorId,
-          moderatorName: moderatorProfile.name,
-          panelists: debate.panelists.map(function (p) {
-            var prof = ctx.getMateProfile(mateCtx, p.mateId);
-            return { mateId: p.mateId, name: prof.name, role: p.role, avatarColor: prof.avatarColor, avatarStyle: prof.avatarStyle, avatarSeed: prof.avatarSeed };
-          }),
-        });
-        // If moderator had concluded, re-send conclude confirm so client shows End/Continue UI
-        if (debate.awaitingConcludeConfirm) {
-          ctx.sendTo(ws, { type: "debate_conclude_confirm", topic: debate.topic, round: debate.round });
+      if (session._debate) {
+        delete session._debate;
+      }
+      if (session.debateState) {
+        var phase = session.debateState.phase;
+        if (phase === "preparing" || phase === "reviewing" || phase === "live") {
+          console.log("[debate] Clearing stale debate state:", session.debateState.topic);
+          session.debateState = null;
+          ctx.sm.saveSessionFile(session);
         }
       }
     });
@@ -470,6 +405,7 @@ function attachDebate(ctx) {
         setupSessionId: null,
         debateId: debateId,
         briefPath: briefPath,
+        ownerId: mateCtx.userId || null,
       };
       debate.nameMap = buildDebateNameMap(debate.panelists, mateCtx);
       session._debate = debate;
@@ -500,8 +436,27 @@ function attachDebate(ctx) {
     var session = ctx.getSessionForWs(ws);
     if (!session) return;
 
-    if (!msg.moderatorId || !msg.topic || !msg.panelists || !msg.panelists.length) {
-      ctx.sendTo(ws, { type: "debate_error", error: "Missing required fields: moderatorId, topic, panelists." });
+    if (!msg.moderatorId || !msg.topic) {
+      ctx.sendTo(ws, { type: "debate_error", error: "Missing required fields: moderatorId, topic." });
+      return;
+    }
+
+    // delegatePanelists: moderator picks panelists, populate all available mates
+    if (msg.delegatePanelists) {
+      var userId = ws._clayUser ? ws._clayUser.id : null;
+      var tmpCtx = matesModule.buildMateCtx(userId);
+      var matesData = matesModule.loadMates(tmpCtx);
+      var allMates = matesData.mates || [];
+      msg.panelists = [];
+      for (var mi = 0; mi < allMates.length; mi++) {
+        if (allMates[mi].id !== msg.moderatorId && allMates[mi].status !== "interviewing") {
+          msg.panelists.push({ mateId: allMates[mi].id, role: "", brief: "" });
+        }
+      }
+    }
+
+    if (!msg.panelists || !msg.panelists.length) {
+      ctx.sendTo(ws, { type: "debate_error", error: "No panelists available." });
       return;
     }
 
@@ -538,6 +493,7 @@ function attachDebate(ctx) {
       round: 1,
       history: [],
       setupSessionId: null,
+      ownerId: userId,
     };
     session._debate = debate;
 
@@ -565,7 +521,8 @@ function attachDebate(ctx) {
     var debateId = debate.debateId;
 
     // Create setup session (still needed for session grouping)
-    var setupSession = ctx.sm.createSession();
+    var setupOpts = debate.ownerId ? { ownerId: debate.ownerId } : null;
+    var setupSession = ctx.sm.createSession(setupOpts);
     setupSession.title = "Debate Setup: " + (msg.topic || "Quick").slice(0, 40);
     setupSession.debateSetupMode = true;
     setupSession.loop = { active: true, iteration: 0, role: "crafting", loopId: debateId, name: (msg.topic || "Quick").slice(0, 40), source: "debate", startedAt: Date.now() };
@@ -597,7 +554,9 @@ function attachDebate(ctx) {
       "",
       "## Your Task",
       "Based on the conversation context, create a debate brief. You know the topic well because you were just discussing it.",
-      "Assign each panelist a role and perspective that will create the most productive debate.",
+      msg.delegatePanelists
+        ? "IMPORTANT: Select only 2-4 panelists who are most relevant to this specific topic. Do NOT include all of them. Be selective. Only pick mates whose expertise or personality directly contributes to this debate."
+        : "The user already selected these panelists. Assign each one a role and perspective that will create the most productive debate.",
       "",
       "Output ONLY a valid JSON object (no markdown fences, no extra text):",
       "{",
@@ -688,7 +647,8 @@ function attachDebate(ctx) {
     var debateId = debate.debateId;
 
     // Create a new session for the setup skill (like Ralph crafting)
-    var setupSession = ctx.sm.createSession();
+    var skillSetupOpts = debate.ownerId ? { ownerId: debate.ownerId } : null;
+    var setupSession = ctx.sm.createSession(skillSetupOpts);
     setupSession.title = "Debate Setup: " + msg.topic.slice(0, 40);
     setupSession.debateSetupMode = true;
     setupSession.loop = { active: true, iteration: 0, role: "crafting", loopId: debateId, name: msg.topic.slice(0, 40), source: "debate", startedAt: Date.now() };
@@ -723,13 +683,24 @@ function attachDebate(ctx) {
     // Watch for brief.json in the debate-specific directory
     startDebateBriefWatcher(session, debate, briefPath);
 
-    // Standard setup: no preparing indicator needed because the user
-    // sees the skill working in real-time in the setup session.
+    // Notify clients that setup is in progress
+    var preparingMsg = {
+      type: "debate_preparing",
+      topic: debate.topic || "(Setting up...)",
+      moderatorId: debate.moderatorId,
+      moderatorName: moderatorProfile.name,
+      setupSessionId: setupSession.localId,
+      panelists: debate.panelists.map(function (p) {
+        var prof = ctx.getMateProfile(mateCtx, p.mateId);
+        return { mateId: p.mateId, name: prof.name };
+      }),
+    };
+    ctx.sendTo(ws, preparingMsg);
+    ctx.sendToSession(session.localId, preparingMsg);
 
-    // Start the setup skill session
-    setupSession.history.push({ type: "user_message", text: craftingPrompt });
-    ctx.sm.appendToSessionFile(setupSession, { type: "user_message", text: craftingPrompt });
-    ctx.sendToSession(setupSession.localId, { type: "user_message", text: craftingPrompt });
+    // Start the setup skill session (don't send user_message to client — it's an internal prompt)
+    setupSession.history.push({ type: "user_message", text: craftingPrompt, _internal: true });
+    ctx.sm.appendToSessionFile(setupSession, { type: "user_message", text: craftingPrompt, _internal: true });
     setupSession.isProcessing = true;
     ctx.onProcessingChanged();
     setupSession.sentToolResults = {};
@@ -737,6 +708,13 @@ function attachDebate(ctx) {
     ctx.sdk.startQuery(setupSession, craftingPrompt, undefined, ctx.getLinuxUserForSession(setupSession));
   }
 
+  // --- Mate strip processing indicator ---
+  // Broadcast mention_processing so the correct mate's active dot lights up
+  // on the mate strip during debate turns (instead of always the moderator's).
+  function debateMateProcessing(mateId, active) {
+    ctx.send({ type: "mention_processing", mateId: mateId, active: active });
+  }
+
   // --- Live debate ---
 
   function startDebateLive(session) {
@@ -751,13 +729,10 @@ function attachDebate(ctx) {
     var moderatorProfile = ctx.getMateProfile(mateCtx, debate.moderatorId);
 
     // Create a dedicated debate session, grouped with the setup session
-    var debateSession = ctx.sm.createSession();
+    var liveOpts = debate.ownerId ? { ownerId: debate.ownerId } : null;
+    var debateSession = ctx.sm.createSession(liveOpts);
     debateSession.title = debate.topic.slice(0, 50);
     debateSession.loop = { active: true, iteration: 1, role: "debate", loopId: debate.debateId, name: debate.topic.slice(0, 40), source: "debate", startedAt: debate.setupStartedAt || Date.now() };
-    // Assign cliSessionId manually so saveSessionFile works (no SDK query for debate sessions)
-    if (!debateSession.cliSessionId) {
-      debateSession.cliSessionId = crypto.randomUUID();
-    }
     ctx.sm.saveSessionFile(debateSession);
     ctx.sm.switchSession(debateSession.localId, null, ctx.hydrateImageRefs);
     debate.liveSessionId = debateSession.localId;
@@ -789,6 +764,7 @@ function attachDebate(ctx) {
     ctx.sendToSession(debateSession.localId, debateStartEntry);
 
     // Signal moderator's first turn
+    debateMateProcessing(debate.moderatorId, true);
     ctx.sendToSession(debateSession.localId, {
       type: "debate_turn",
       mateId: debate.moderatorId,
@@ -843,6 +819,7 @@ function attachDebate(ctx) {
     var debate = session._debate;
     if (!debate || debate.phase === "ended") return;
 
+    debateMateProcessing(debate.moderatorId, false);
     debate.turnInProgress = false;
 
     // Record in debate history
@@ -886,6 +863,12 @@ function attachDebate(ctx) {
       return;
     }
 
+    // Check if user raised hand
+    if (debate.handRaised) {
+      yieldFloorToUser(session);
+      return;
+    }
+
     // Trigger the first mentioned panelist
     triggerPanelist(session, mentionedIds[0], fullText);
   }
@@ -908,6 +891,7 @@ function attachDebate(ctx) {
     }
     if (!panelistInfo) {
       console.error("[debate] Panelist not found:", mateId);
+      debateMateProcessing(mateId, false);
       debate._currentTurnMateId = null;
       // Feed error back to moderator
       feedBackToModerator(session, mateId, "[This panelist is not part of the debate panel.]");
@@ -915,6 +899,7 @@ function attachDebate(ctx) {
     }
 
     // Notify clients of new turn
+    debateMateProcessing(mateId, true);
     ctx.sendToSession(session.localId, {
       type: "debate_turn",
       mateId: mateId,
@@ -943,6 +928,7 @@ function attachDebate(ctx) {
       },
       onError: function (errMsg) {
         console.error("[debate] Panelist error for " + mateId + ":", errMsg);
+        debateMateProcessing(mateId, false);
         debate.turnInProgress = false;
         // Feed error back to moderator so the debate can continue
         feedBackToModerator(session, mateId, "[" + profile.name + " encountered an error and could not respond. Please continue with other panelists or wrap up.]");
@@ -1003,6 +989,7 @@ function attachDebate(ctx) {
         }
       }).catch(function (err) {
         console.error("[debate] Failed to create panelist session for " + mateId + ":", err.message || err);
+        debateMateProcessing(mateId, false);
         debate.turnInProgress = false;
         feedBackToModerator(session, mateId, "[" + profile.name + " is unavailable. Please continue with other panelists or wrap up.]");
       });
@@ -1013,6 +1000,7 @@ function attachDebate(ctx) {
     var debate = session._debate;
     if (!debate || debate.phase === "ended") return;
 
+    debateMateProcessing(mateId, false);
     debate.turnInProgress = false;
     debate._currentTurnMateId = null;
     debate._currentTurnText = "";
@@ -1041,12 +1029,18 @@ function attachDebate(ctx) {
       return;
     }
 
-    // Check for pending user comment
+    // Check for pending user comment (legacy)
     if (debate.pendingComment) {
       injectUserComment(session);
       return;
     }
 
+    // Check if user raised hand (no comment, just wants the floor)
+    if (debate.handRaised) {
+      yieldFloorToUser(session);
+      return;
+    }
+
     // Feed panelist response back to moderator
     feedBackToModerator(session, mateId, fullText);
   }
@@ -1070,6 +1064,7 @@ function attachDebate(ctx) {
     var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
 
     // Notify clients of moderator turn
+    debateMateProcessing(debate.moderatorId, true);
     ctx.sendToSession(session.localId, {
       type: "debate_turn",
       mateId: debate.moderatorId,
@@ -1115,73 +1110,75 @@ function attachDebate(ctx) {
 
   // --- User interaction during debate ---
 
-  function handleDebateComment(ws, msg) {
+  function handleDebateHandRaise(ws) {
     var session = ctx.getSessionForWs(ws);
     if (!session) return;
 
     var debate = session._debate;
-    if (!debate || debate.phase !== "live") {
-      ctx.sendTo(ws, { type: "debate_error", error: "No active debate." });
-      return;
-    }
-
-    // If awaiting conclude confirmation, re-send the confirm prompt instead
+    if (!debate || debate.phase !== "live") return;
+    if (debate.awaitingUserFloor || debate.handRaised) return;
     if (debate.awaitingConcludeConfirm) {
       ctx.sendTo(ws, { type: "debate_conclude_confirm", topic: debate.topic, round: debate.round });
       return;
     }
 
+    debate.handRaised = true;
+    ctx.sendToSession(session.localId, { type: "debate_hand_raised" });
+
+    // If no one is speaking, yield floor immediately
+    if (!debate.turnInProgress) {
+      yieldFloorToUser(session);
+    }
+    // Otherwise: current speaker finishes -> handRaised detected -> yieldFloorToUser
+  }
+
+  function handleDebateComment(ws, msg) {
+    // Legacy: kept for compatibility but now hand raise is separate
+    var session = ctx.getSessionForWs(ws);
+    if (!session) return;
+
+    var debate = session._debate;
+    if (!debate || debate.phase !== "live") {
+      ctx.sendTo(ws, { type: "debate_error", error: "No active debate." });
+      return;
+    }
+    if (debate.awaitingUserFloor) return;
     if (!msg.text) return;
 
     debate.pendingComment = { text: msg.text };
+    debate.handRaised = true;
     ctx.sendToSession(session.localId, { type: "debate_comment_queued", text: msg.text });
 
-    // If a panelist turn is in progress, abort it and go straight to moderator
-    if (debate.turnInProgress && debate._currentTurnMateId && debate._currentTurnMateId !== debate.moderatorId) {
-      var abortMateId = debate._currentTurnMateId;
-      console.log("[debate] User raised hand during panelist turn, aborting " + abortMateId);
-
-      // Close the panelist's mention session to stop generation
-      if (debate.panelistSessions[abortMateId]) {
-        try { debate.panelistSessions[abortMateId].close(); } catch (e) {}
-        delete debate.panelistSessions[abortMateId];
-      }
+    if (!debate.turnInProgress) {
+      injectUserComment(session);
+    }
+  }
 
-      // Save partial text as interrupted turn
-      var partialText = debate._currentTurnText || "(interrupted by audience)";
-      var profile = ctx.getMateProfile(debate.mateCtx, abortMateId);
-      var panelistInfo = null;
-      for (var pi = 0; pi < debate.panelists.length; pi++) {
-        if (debate.panelists[pi].mateId === abortMateId) { panelistInfo = debate.panelists[pi]; break; }
-      }
+  function yieldFloorToUser(session) {
+    var debate = session._debate;
+    if (!debate || !debate.moderatorSession || debate.phase === "ended") return;
 
-      ctx.sendToSession(session.localId, {
-        type: "debate_turn_done",
-        mateId: abortMateId,
-        mateName: profile.name,
-        role: panelistInfo ? panelistInfo.role : "",
-        text: partialText,
-        interrupted: true,
-        avatarStyle: profile.avatarStyle,
-        avatarSeed: profile.avatarSeed,
-        avatarColor: profile.avatarColor,
-      });
+    debate.handRaised = false;
+    debate.turnInProgress = true;
+    var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
 
-      var turnEntry = { type: "debate_turn_done", mateId: abortMateId, mateName: profile.name, role: panelistInfo ? panelistInfo.role : "", round: debate.round, text: partialText, avatarStyle: profile.avatarStyle, avatarSeed: profile.avatarSeed, avatarColor: profile.avatarColor, interrupted: true };
-      session.history.push(turnEntry);
-      ctx.sm.appendToSessionFile(session, turnEntry);
-      debate.history.push({ speaker: "panelist", mateId: abortMateId, mateName: profile.name, role: panelistInfo ? panelistInfo.role : "", text: partialText });
+    ctx.sendToSession(session.localId, {
+      type: "debate_turn",
+      mateId: debate.moderatorId,
+      mateName: moderatorProfile.name,
+      role: "moderator",
+      round: debate.round,
+      avatarColor: moderatorProfile.avatarColor,
+      avatarStyle: moderatorProfile.avatarStyle,
+      avatarSeed: moderatorProfile.avatarSeed,
+    });
 
-      debate.turnInProgress = false;
-      debate._currentTurnMateId = null;
-      debate._currentTurnText = "";
-    }
+    var feedText = "[The user raised their hand to speak.]\n" +
+      "[Acknowledge this briefly and yield the floor to the user. Say something like " +
+      "\"Go ahead\" or \"The floor is yours\". Do NOT call on any panelist (no @mentions). " +
+      "The debate will pause for the user to speak.]";
 
-    // Inject to moderator immediately if no turn in progress (or just aborted)
-    if (!debate.turnInProgress) {
-      injectUserComment(session);
-    }
-    // If moderator is currently speaking, pendingComment will be picked up after moderator's onDone
+    debate.moderatorSession.pushMessage(feedText, buildModeratorYieldCallbacks(session));
   }
 
   function injectUserComment(session) {
@@ -1190,6 +1187,7 @@ function attachDebate(ctx) {
 
     var comment = debate.pendingComment;
     debate.pendingComment = null;
+    debate.handRaised = false;
 
     // Record in debate history
     debate.history.push({ speaker: "user", mateId: null, mateName: "User", text: comment.text });
@@ -1199,7 +1197,7 @@ function attachDebate(ctx) {
     ctx.sm.appendToSessionFile(session, commentEntry);
     ctx.sendToSession(session.localId, commentEntry);
 
-    // Feed to moderator
+    // Feed to moderator: yield the floor to the user
     debate.turnInProgress = true;
     var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
 
@@ -1216,9 +1214,90 @@ function attachDebate(ctx) {
 
     var feedText = "[The user raised their hand and said:]\n" +
       comment.text + "\n" +
-      "[Please acknowledge this and weave it into the discussion. Then continue the debate.]";
+      "[Acknowledge the user's input. Briefly respond, then YIELD THE FLOOR to the user by saying something like " +
+      "\"The floor is yours\" or \"Go ahead\". Do NOT call on any panelist (no @mentions). " +
+      "The debate will pause for the user to speak.]";
+
+    debate.moderatorSession.pushMessage(feedText, buildModeratorYieldCallbacks(session));
+  }
+
+  function buildModeratorYieldCallbacks(session) {
+    var debate = session._debate;
+    var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
+    return {
+      onActivity: function (activity) {
+        if (session._debate && session._debate.phase !== "ended") {
+          ctx.sendToSession(session.localId, { type: "debate_activity", mateId: debate.moderatorId, activity: activity });
+        }
+      },
+      onDelta: function (delta) {
+        if (session._debate && session._debate.phase !== "ended") {
+          ctx.sendToSession(session.localId, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
+        }
+      },
+      onDone: function (fullText) {
+        if (!debate || debate.phase === "ended") return;
+        debate.turnInProgress = false;
+
+        // Record moderator yield turn
+        debate.history.push({ speaker: "moderator", mateId: debate.moderatorId, mateName: moderatorProfile.name, text: fullText });
+        var turnEntry = { type: "debate_turn_done", mateId: debate.moderatorId, mateName: moderatorProfile.name, role: "moderator", round: debate.round, text: fullText, avatarStyle: moderatorProfile.avatarStyle, avatarSeed: moderatorProfile.avatarSeed, avatarColor: moderatorProfile.avatarColor };
+        session.history.push(turnEntry);
+        ctx.sm.appendToSessionFile(session, turnEntry);
+        ctx.sendToSession(session.localId, turnEntry);
+
+        // Enter user floor mode: pause debate and show input
+        debate.awaitingUserFloor = true;
+        persistDebateState(session);
+        ctx.sendToSession(session.localId, { type: "debate_user_floor", topic: debate.topic, round: debate.round });
+      },
+      onError: function (errMsg) {
+        console.error("[debate] Moderator yield error:", errMsg);
+        endDebate(session, "error");
+      },
+    };
+  }
+
+  function handleDebateUserFloorResponse(ws, msg) {
+    var session = ctx.getSessionForWs(ws);
+    if (!session) return;
+
+    var debate = session._debate;
+    if (!debate || !debate.awaitingUserFloor || debate.phase !== "live") return;
+
+    debate.awaitingUserFloor = false;
+    var userText = (msg && msg.text) ? msg.text.trim() : "";
+    if (!userText) return;
+
+    // Record user's floor contribution
+    debate.history.push({ speaker: "user", mateId: null, mateName: "User", text: userText });
+    var floorEntry = { type: "debate_user_floor_done", text: userText };
+    session.history.push(floorEntry);
+    ctx.sm.appendToSessionFile(session, floorEntry);
+    ctx.sendToSession(session.localId, floorEntry);
+
+    // Feed to moderator to resume debate
+    debate.turnInProgress = true;
+    var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
+
+    debateMateProcessing(debate.moderatorId, true);
+    ctx.sendToSession(session.localId, {
+      type: "debate_turn",
+      mateId: debate.moderatorId,
+      mateName: moderatorProfile.name,
+      role: "moderator",
+      round: debate.round,
+      avatarColor: moderatorProfile.avatarColor,
+      avatarStyle: moderatorProfile.avatarStyle,
+      avatarSeed: moderatorProfile.avatarSeed,
+    });
+
+    var feedText = "[The user took the floor and said:]\n" +
+      userText + "\n" +
+      "[Acknowledge the user's contribution and resume the debate. Call on the next panelist with @TheirName.]";
 
     debate.moderatorSession.pushMessage(feedText, buildModeratorCallbacks(session));
+    persistDebateState(session);
   }
 
   function handleDebateConfirmBrief(ws) {
@@ -1391,6 +1470,7 @@ function attachDebate(ctx) {
       ctx.sendToSession(session.localId, resumedMsg);
 
       debate.turnInProgress = true;
+      debateMateProcessing(debate.moderatorId, true);
       ctx.sendToSession(session.localId, {
         type: "debate_turn",
         mateId: debate.moderatorId,
@@ -1402,9 +1482,15 @@ function attachDebate(ctx) {
         avatarSeed: moderatorProfile.avatarSeed,
       });
 
+      // Build explicit panelist list so the moderator knows who to call on
+      var panelistNames = debate.panelists.map(function (p) {
+        var prof = ctx.getMateProfile(mateCtx, p.mateId);
+        return "@" + prof.name;
+      });
+      var panelistList = panelistNames.join(", ");
       var resumePrompt = instruction
-        ? "[The audience has requested the debate continue with the following direction]\nUser: " + instruction + "\n\n[As moderator, acknowledge this input and call on a panelist with @TheirName to continue the discussion.]"
-        : "[The audience has requested the debate continue. Call on the next panelist with @TheirName to explore additional perspectives.]";
+        ? "[SYSTEM: The audience has requested the debate continue with new direction. You MUST call on a panelist to continue. Available panelists: " + panelistList + "]\n\nUser direction: " + instruction + "\n\n[Acknowledge this input briefly, then call on a panelist by writing their @Name to continue the discussion on this new direction. You must @mention exactly one panelist.]"
+        : "[SYSTEM: The audience has requested the debate continue. You MUST call on the next panelist. Available panelists: " + panelistList + "]\n\n[Call on a panelist by writing their @Name to explore additional perspectives. You must @mention exactly one panelist.]";
 
       // If resuming from ended state, moderator session may be dead. Create a new one.
       if (wasEnded || !debate.moderatorSession || !debate.moderatorSession.isAlive()) {
@@ -1414,7 +1500,8 @@ function attachDebate(ctx) {
         var moderatorContext = buildModeratorContext(debate) + digests;
 
         // Include debate history so moderator has context
-        moderatorContext += "\n\nDebate history so far:\n---\n";
+        moderatorContext += "\n\nIMPORTANT: This debate was previously paused and is now being RESUMED. You must continue the debate by calling on a panelist with @TheirName. Do NOT conclude or summarize.\n";
+        moderatorContext += "\nDebate history so far:\n---\n";
         for (var hi = 0; hi < debate.history.length; hi++) {
           var h = debate.history[hi];
           moderatorContext += (h.mateName || h.speaker || "Unknown") + " (" + (h.role || "") + "): " + (h.text || "").slice(0, 500) + "\n\n";
@@ -1464,6 +1551,12 @@ function attachDebate(ctx) {
     var debate = session._debate;
     if (!debate || debate.phase === "ended") return;
 
+    // Clear all mate strip processing dots
+    debateMateProcessing(debate.moderatorId, false);
+    for (var ei = 0; ei < debate.panelists.length; ei++) {
+      debateMateProcessing(debate.panelists[ei].mateId, false);
+    }
+
     debate.phase = "ended";
     debate.turnInProgress = false;
     persistDebateState(session);
@@ -1588,16 +1681,61 @@ function attachDebate(ctx) {
     })();
   }
 
+  // --- MCP-based debate proposal approval ---
+
+  function handleMcpDebateApproval(session, briefData, mateId, ws) {
+    if (session._debate && (session._debate.phase === "preparing" || session._debate.phase === "reviewing" || session._debate.phase === "live")) {
+      console.warn("[debate] Cannot start MCP debate: another debate is active on this session");
+      return;
+    }
+
+    var userId = ws && ws._clayUser ? ws._clayUser.id : (session.ownerId || ctx.projectOwnerId || null);
+    var mateCtx = matesModule.buildMateCtx(userId);
+    var debateId = "debate_" + Date.now();
+
+    var debate = {
+      phase: "reviewing",
+      topic: briefData.topic || "Untitled debate",
+      format: briefData.format || "free_discussion",
+      context: briefData.context || "",
+      specialRequests: briefData.specialRequests || null,
+      moderatorId: mateId,
+      panelists: (briefData.panelists || []).map(function (p) {
+        return { mateId: p.mateId, role: p.role || "", brief: p.brief || "" };
+      }),
+      mateCtx: mateCtx,
+      moderatorSession: null,
+      panelistSessions: {},
+      nameMap: null,
+      turnInProgress: false,
+      pendingComment: null,
+      round: 1,
+      history: [],
+      setupSessionId: null,
+      debateId: debateId,
+      briefPath: null,
+      ownerId: userId,
+    };
+    debate.nameMap = buildDebateNameMap(debate.panelists, mateCtx);
+    session._debate = debate;
+
+    console.log("[debate] MCP debate approved. Topic:", debate.topic, "debateId:", debateId);
+    startDebateLive(session);
+  }
+
   // --- Public API ---
 
   return {
     handleDebateStart: handleDebateStart,
+    handleDebateHandRaise: handleDebateHandRaise,
     handleDebateComment: handleDebateComment,
     handleDebateStop: handleDebateStop,
     handleDebateConcludeResponse: handleDebateConcludeResponse,
     handleDebateConfirmBrief: handleDebateConfirmBrief,
+    handleDebateUserFloorResponse: handleDebateUserFloorResponse,
     restoreDebateState: restoreDebateState,
     checkForDmDebateBrief: checkForDmDebateBrief,
+    handleMcpDebateApproval: handleMcpDebateApproval,
   };
 }