let-them-talk 3.7.0 → 3.9.0

package/server.js

@@ -72,7 +72,13 @@ function isGroupMode() {
 }
 
 function getGroupCooldown() {
-  return getConfig().group_cooldown || 3000; // default 3s
+  // Adaptive cooldown: scales with online agent count — max(500, N * 500)
+  // 2 agents = 1s, 3 = 1.5s, 4 = 2s, 6 = 3s, 10 = 5s
+  const configured = getConfig().group_cooldown;
+  if (configured) return configured; // respect explicit config
+  const agents = getAgents();
+  const aliveCount = Object.values(agents).filter(a => isPidAlive(a.pid, a.last_activity)).length;
+  return Math.max(500, aliveCount * 500);
 }
 
 // --- Managed conversation mode ---
@@ -364,21 +370,33 @@ function autoCompact() {
 
     const messages = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
 
-    // Collect ALL consumed IDs across all agents
+    // Collect consumed IDs — for __group__ messages, only check ALIVE agents
+    const agents = getAgents();
+    const aliveAgentNames = Object.keys(agents).filter(n => isPidAlive(agents[n].pid, agents[n].last_activity));
     const allConsumed = new Set();
+    const perAgentConsumed = {};
     if (fs.existsSync(DATA_DIR)) {
       for (const f of fs.readdirSync(DATA_DIR)) {
         if (f.startsWith('consumed-') && f.endsWith('.json')) {
+          const agentName = f.replace('consumed-', '').replace('.json', '');
           try {
             const ids = JSON.parse(fs.readFileSync(path.join(DATA_DIR, f), 'utf8'));
+            perAgentConsumed[agentName] = new Set(ids);
             ids.forEach(id => allConsumed.add(id));
           } catch {}
         }
       }
     }
 
-    // Keep only unconsumed messages (for direct messages, only the recipient consumes)
+    // Keep messages that are NOT fully consumed
+    // For __group__ messages: consumed when ALL ALIVE agents have consumed it (dead agents don't block)
+    // For direct messages: consumed when the recipient has consumed it
     const active = messages.filter(m => {
+      if (m.to === '__group__') {
+        // __group__: check if all alive agents (except sender) have consumed
+        return !aliveAgentNames.every(n => n === m.from || (perAgentConsumed[n] && perAgentConsumed[n].has(m.id)));
+      }
+      // Direct: standard check
       if (!allConsumed.has(m.id)) return true;
       return false;
     });
@@ -451,7 +469,9 @@ function getUnconsumedMessages(agentName, fromFilter = null) {
   const consumed = getConsumedIds(agentName);
   const perms = getPermissions();
   return messages.filter(m => {
-    if (m.to !== agentName) return false;
+    if (m.to !== agentName && m.to !== '__group__' && m.to !== '__all__') return false;
+    // Skip own group messages
+    if (m.to === '__group__' && m.from === agentName) return false;
     if (consumed.has(m.id)) return false;
     if (fromFilter && m.from !== fromFilter && !m.system) return false;
     // Permission check: skip messages from senders this agent can't read
@@ -632,12 +652,49 @@ function toolRegister(name, provider = null) {
       }
       // Clean up file locks held by dead agents
       cleanStaleLocks();
+      cleanStaleChannelMembers();
     } catch {}
   }, 10000);
   heartbeatInterval.unref(); // Don't prevent process exit
 
     // Fire join event + recovery data for returning agents
-    const result = { success: true, message: `Registered as Agent ${name} (PID ${process.pid})` };
+    const config = getConfig();
+    const mode = config.conversation_mode || 'direct';
+    const otherAgents = Object.keys(getAgents()).filter(n => n !== name);
+
+    const result = {
+      success: true,
+      message: `Registered as Agent ${name} (PID ${process.pid})`,
+      conversation_mode: mode,
+      agents_online: otherAgents,
+      guide: {
+        critical_rules: [
+          'AFTER EVERY ACTION YOU TAKE, call listen_group() (group/managed mode) or listen() (direct mode) immediately. This is how you receive messages. If you stop listening, you are invisible to the team.',
+          'Never send multiple messages in a row without calling listen_group() between them — you will miss responses.',
+          'Keep messages concise. 2-3 paragraphs max. No essays.',
+          'When you finish a task, report what you did AND what files you changed, then listen again.',
+        ],
+        first_steps: mode === 'direct'
+          ? '1. Call list_agents() to see who is online. 2. Send a message or call listen() to wait for one.'
+          : '1. Call get_briefing() for full project context. 2. Call listen_group() to join the conversation. 3. When you receive messages, respond and immediately call listen_group() again.',
+        tool_categories: {
+          'MESSAGING (always use these)': 'send_message, broadcast, listen_group (group/managed), listen (direct), check_messages, get_history, get_summary, handoff, share_file',
+          'TEAM COORDINATION': 'get_briefing (project overview), log_decision / get_decisions (prevent re-debating), kb_write / kb_read (shared knowledge), call_vote / cast_vote (team decisions)',
+          'TASK MANAGEMENT': 'create_task, update_task, list_tasks, declare_dependency, check_dependencies, suggest_task (what should I do next?)',
+          'PROGRESS & QUALITY': 'update_progress / get_progress (feature %), request_review / submit_review (code review), get_reputation (leaderboard)',
+          'FILE SAFETY': 'lock_file / unlock_file (prevent conflicts — ALWAYS lock before editing shared files)',
+          'PROFILES & WORKSPACES': 'update_profile, workspace_write / workspace_read (personal storage)',
+          'MANAGED MODE (if active)': 'claim_manager, yield_floor, set_phase — only the manager uses these',
+        },
+        patterns: {
+          'Starting work': 'get_briefing → check list_tasks → claim a task with update_task(id, "in_progress") → lock_file → do the work → unlock_file → update_task(id, "done") → listen_group',
+          'Sharing knowledge': 'kb_write("api-schema", "POST /auth → {token}") — so others can kb_read it without asking you',
+          'Making decisions': 'log_decision("Use PostgreSQL", "Better JSON support") — so no one re-debates this later',
+          'Disagreements': 'call_vote("Use Redis for caching?", ["yes", "no"]) — let the team decide democratically',
+          'Code review': 'request_review("src/auth.ts", "Check token expiry logic") — another agent will review and approve/request changes',
+        },
+      },
+    };
 
     // Recovery: if this agent has prior data, include it
     const myTasks = getTasks().filter(t => t.assignee === name && t.status !== 'done');
@@ -681,6 +738,10 @@ function setListening(isListening) {
     const agents = getAgents();
     if (agents[registeredName]) {
       agents[registeredName].listening_since = isListening ? new Date().toISOString() : null;
+      // Persist last_listened_at so other agents can detect unresponsive agents
+      if (isListening) {
+        agents[registeredName].last_listened_at = new Date().toISOString();
+      }
       saveAgents(agents);
     }
   } catch {}
@@ -703,6 +764,7 @@ function toolListAgents() {
       status: !alive ? 'dead' : idleSeconds > 60 ? 'sleeping' : 'active',
       listening_since: info.listening_since || null,
       is_listening: !!(info.listening_since && alive),
+      last_listened_at: info.last_listened_at || null,
       provider: info.provider || 'unknown',
       branch: info.branch || 'main',
       display_name: profile.display_name || name,
@@ -714,7 +776,7 @@ function toolListAgents() {
   return { agents: result };
 }
 
-async function toolSendMessage(content, to = null, reply_to = null) {
+async function toolSendMessage(content, to = null, reply_to = null, channel = null) {
   if (!registeredName) {
     return { error: 'You must call register() first' };
   }
@@ -722,9 +784,23 @@ async function toolSendMessage(content, to = null, reply_to = null) {
   const rateErr = checkRateLimit();
   if (rateErr) return rateErr;
 
-  // Group mode cooldown — prevent agents from responding too fast
+  // Group mode cooldown — split by addressing (fast lane / slow lane)
   if (isGroupMode()) {
-    const cooldown = getGroupCooldown();
+    let cooldown = getGroupCooldown(); // default: adaptive max(500, N*500)
+    // Split cooldown: if replying to a message that addressed us, use fast lane (500ms)
+    // If not addressed or no reply_to, use slow lane (higher friction)
+    if (reply_to) {
+      const allMsgs = readJsonl(getMessagesFile(currentBranch));
+      const refMsg = allMsgs.find(m => m.id === reply_to);
+      if (refMsg && refMsg.addressed_to && refMsg.addressed_to.includes(registeredName)) {
+        cooldown = 500; // fast lane: I was addressed
+      } else {
+        // Slow lane: heavier friction for unaddressed responses
+        const agents = getAgents();
+        const aliveCount = Object.values(agents).filter(a => isPidAlive(a.pid, a.last_activity)).length;
+        cooldown = Math.max(2000, aliveCount * 1000);
+      }
+    }
     const elapsed = Date.now() - lastSentAt;
     if (elapsed < cooldown) {
       await sleep(cooldown - elapsed);
@@ -827,35 +903,40 @@ async function toolSendMessage(content, to = null, reply_to = null) {
   }
 
   messageSeq++;
+  // In group mode: rewrite to → __group__, original to becomes addressed_to
+  const isGroup = isGroupMode() && !isManagedMode();
   const msg = {
     id: generateId(),
     seq: messageSeq,
     from: registeredName,
-    to,
+    to: isGroup ? '__group__' : to,
     content,
     timestamp: new Date().toISOString(),
+    ...(isGroup && to && { addressed_to: [to] }),
+    ...(channel && { channel }),
     ...(reply_to && { reply_to }),
     ...(thread_id && { thread_id }),
   };
 
+  // Validate channel exists (prevents orphan files from typos)
+  if (channel && channel !== 'general') {
+    const channels = getChannelsData();
+    if (!channels[channel]) {
+      return { error: `Channel "#${channel}" does not exist. Use join_channel("${channel}") to create it first.` };
+    }
+  }
+
   ensureDataDir();
-  fs.appendFileSync(getMessagesFile(currentBranch), JSON.stringify(msg) + '\n');
-  fs.appendFileSync(getHistoryFile(currentBranch), JSON.stringify(msg) + '\n');
+  // Write to channel-specific file if channel specified, otherwise default
+  const msgFile = channel ? getChannelMessagesFile(channel) : getMessagesFile(currentBranch);
+  const histFile = channel ? getChannelHistoryFile(channel) : getHistoryFile(currentBranch);
+  fs.appendFileSync(msgFile, JSON.stringify(msg) + '\n');
+  fs.appendFileSync(histFile, JSON.stringify(msg) + '\n');
   touchActivity();
   lastSentAt = Date.now();
 
-  // In group mode, auto-broadcast: also write to all other agents' queues
-  // Skip if this message is already a response to a broadcast (prevents cascade)
-  // NEVER auto-broadcast in managed mode — manager controls communication flow
-  if (isGroupMode() && !isManagedMode() && !reply_to && !msg.broadcast) {
-    const otherRecipients = Object.keys(getAgents()).filter(n => n !== registeredName && n !== to);
-    for (const other of otherRecipients) {
-      if (!canSendTo(registeredName, other)) continue; // respect permissions
-      const broadcastMsg = { ...msg, id: generateId(), to: other, broadcast: true, original_to: to };
-      fs.appendFileSync(getMessagesFile(currentBranch), JSON.stringify(broadcastMsg) + '\n');
-      fs.appendFileSync(getHistoryFile(currentBranch), JSON.stringify(broadcastMsg) + '\n');
-    }
-  }
+  // Group mode: O(N) auto-broadcast REMOVED. Messages now use __group__ single-write.
+  // The to→__group__ rewrite happens above when the message is created.
 
   // Managed mode: auto-advance turns after non-manager sends
   if (isManagedMode()) {
@@ -906,6 +987,12 @@ async function toolSendMessage(content, to = null, reply_to = null) {
     result.note = `Agent "${to}" is currently working (not in listen mode). Message queued — they'll see it when they finish their current task and call listen_group().`;
   }
 
+  // Mode awareness hint: warn if agent seems to be in wrong mode
+  const currentMode = getConfig().conversation_mode || 'direct';
+  if (currentMode === 'group' || currentMode === 'managed') {
+    result.mode_hint = `You're in ${currentMode} mode. Use listen_group() (or listen() — both auto-detect) to stay in the conversation.`;
+  }
+
   // Nudge: check if THIS agent has unread messages waiting
   const myPending = getUnconsumedMessages(registeredName);
   if (myPending.length > 0) {
@@ -942,6 +1029,32 @@ function toolBroadcast(content) {
   }
 
   ensureDataDir();
+
+  // In group mode: single __group__ write instead of per-agent copies
+  if (isGroupMode() && !isManagedMode()) {
+    messageSeq++;
+    const msg = {
+      id: generateId(),
+      seq: messageSeq,
+      from: registeredName,
+      to: '__group__',
+      content,
+      timestamp: new Date().toISOString(),
+      broadcast: true,
+    };
+    fs.appendFileSync(getMessagesFile(currentBranch), JSON.stringify(msg) + '\n');
+    fs.appendFileSync(getHistoryFile(currentBranch), JSON.stringify(msg) + '\n');
+    touchActivity();
+    lastSentAt = Date.now();
+    const aliveOthers = otherAgents.filter(n => { const a = agents[n]; return isPidAlive(a.pid, a.last_activity); });
+    const result = { success: true, messageId: msg.id, recipient_count: aliveOthers.length, sent_to: aliveOthers.map(n => ({ to: n, messageId: msg.id })) };
+    // Nudge for own unread messages
+    const myPending = getUnconsumedMessages(registeredName);
+    if (myPending.length > 0) { result.you_have_messages = myPending.length; result.urgent = `You have ${myPending.length} unread message(s). Call listen_group() soon.`; }
+    return result;
+  }
+
+  // Direct/managed mode: per-agent writes (original behavior)
   const ids = [];
   const skipped = [];
   for (const to of otherAgents) {
@@ -1089,6 +1202,12 @@ async function toolListen(from = null) {
     return { error: 'You must call register() first' };
   }
 
+  // Auto-detect group/managed mode and delegate to toolListenGroup
+  // This prevents agents from calling the "wrong" listen function
+  if (isGroupMode() || isManagedMode()) {
+    return toolListenGroup();
+  }
+
   setListening(true);
 
   // Check for existing unconsumed messages first
@@ -1232,6 +1351,11 @@ function toolSetConversationMode(mode) {
   }
   saveConfig(config);
 
+  // Notify all agents about mode change (managed mode already broadcasts above)
+  if (mode !== 'managed') {
+    broadcastSystemMessage(`[MODE] Conversation switched to ${mode} mode by ${registeredName}. ${mode === 'group' ? 'All messages are now shared with everyone.' : 'Messages are now point-to-point.'}`, registeredName);
+  }
+
   const messages = {
     group: 'Group mode enabled. Use listen_group() to receive batched messages. All messages are shared with everyone.',
     direct: 'Direct mode enabled. Use listen() for point-to-point messaging.',
@@ -1374,14 +1498,22 @@ function toolSetPhase(phase) {
   };
 }
 
+// Deterministic stagger delay based on agent name (500-1500ms)
+// Same agent always gets the same delay, making response ordering predictable
+function hashStagger(name) {
+  const hash = name.split('').reduce((h, c) => h + c.charCodeAt(0), 0);
+  return 500 + (hash * 137) % 1000; // 0.5-1.5s range
+}
+
 async function toolListenGroup() {
   if (!registeredName) return { error: 'You must call register() first' };
 
-  setListening(true);
+  // Auto-detect direct mode and delegate to toolListen (prevents wrong-function bugs)
+  if (!isGroupMode() && !isManagedMode()) {
+    return toolListen();
+  }
 
-  // Random stagger to prevent all agents from responding simultaneously (1-3s)
-  const stagger = 1000 + Math.random() * 2000;
-  await new Promise(r => setTimeout(r, stagger));
+  setListening(true);
 
   const consumed = getConsumedIds(registeredName);
 
@@ -1390,12 +1522,26 @@ async function toolListenGroup() {
     const chunkDeadline = Date.now() + 300000;
 
   while (Date.now() < chunkDeadline) {
-    // Collect ALL unconsumed messages addressed to us or broadcast
-    const messages = readJsonl(getMessagesFile(currentBranch));
+    // Collect ALL unconsumed messages from general + all subscribed channels
+    const myChannels = getAgentChannels(registeredName);
+    let messages = readJsonl(getMessagesFile(currentBranch));
+    // Also read from channel-specific files
+    for (const ch of myChannels) {
+      if (ch === 'general') continue; // general uses the main messages file
+      const chFile = getChannelMessagesFile(ch);
+      if (fs.existsSync(chFile)) {
+        const chMsgs = readJsonl(chFile);
+        messages = messages.concat(chMsgs);
+      }
+    }
+    // Sort by timestamp for consistent ordering
+    messages.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
     const batch = [];
     for (const msg of messages) {
       if (consumed.has(msg.id)) continue;
-      if (msg.to !== registeredName && msg.to !== '__all__') continue;
+      // Skip own messages in group mode (agent already knows what it sent)
+      if (msg.to === '__group__' && msg.from === registeredName) { consumed.add(msg.id); continue; }
+      if (msg.to !== registeredName && msg.to !== '__all__' && msg.to !== '__group__') continue;
       // Permission check
       const perms = getPermissions();
       if (perms[registeredName] && perms[registeredName].can_read) {
@@ -1412,6 +1558,42 @@ async function toolListenGroup() {
       touchActivity();
       setListening(false);
 
+      // Post-receive stagger: deterministic delay based on agent name
+      // Prevents all agents from responding simultaneously to the same batch
+      const staggerMs = hashStagger(registeredName);
+      if (staggerMs > 0) {
+        await new Promise(r => setTimeout(r, staggerMs));
+      }
+
+      // Sort batch by priority: system > threaded replies > direct > broadcast
+      // Within each category, maintain chronological order
+      function messagePriority(m) {
+        if (m.system || m.from === '__system__') return 0;
+        if (m.reply_to || m.thread_id) return 1;
+        if (!m.broadcast) return 2;
+        return 3;
+      }
+      batch.sort((a, b) => {
+        const pa = messagePriority(a), pb = messagePriority(b);
+        if (pa !== pb) return pa - pb;
+        return new Date(a.timestamp) - new Date(b.timestamp);
+      });
+
+      // Build batch summary for triage
+      const summaryCounts = {};
+      for (const m of batch) {
+        const type = m.system || m.from === '__system__' ? 'system'
+          : m.broadcast ? 'broadcast' : (m.reply_to || m.thread_id) ? 'thread' : 'direct';
+        const key = `${m.from}:${type}`;
+        summaryCounts[key] = (summaryCounts[key] || 0) + 1;
+      }
+      const summaryParts = [];
+      for (const [key, count] of Object.entries(summaryCounts)) {
+        const [from, type] = key.split(':');
+        summaryParts.push(`${count} ${type} from ${from}`);
+      }
+      const batchSummary = `${batch.length} messages: ${summaryParts.join(', ')}`;
+
       // Get recent history for context
       const history = readJsonl(getHistoryFile(currentBranch));
       const recentHistory = history.slice(-20).map(m => ({
@@ -1437,14 +1619,33 @@ async function toolListenGroup() {
             ...(ageSec > 30 && { delayed: true }),
             ...(m.reply_to && { reply_to: m.reply_to }),
             ...(m.thread_id && { thread_id: m.thread_id }),
+            // addressed_to hint for group messages
+            ...(m.addressed_to && { addressed_to: m.addressed_to }),
+            ...(m.to === '__group__' && {
+              addressed_to_you: !m.addressed_to || m.addressed_to.includes(registeredName),
+              should_respond: !m.addressed_to || m.addressed_to.includes(registeredName),
+            }),
           };
         }),
         message_count: batch.length,
+        batch_summary: batchSummary,
         context: recentHistory,
         agents_online: agentNames.length,
         agents_silent: silent,
         agents_status: agentNames.reduce(function(acc, n) {
-          acc[n] = agents[n].listening_since ? 'listening' : 'working';
+          if (agents[n].listening_since) {
+            acc[n] = 'listening';
+          } else {
+            // Check for unresponsive: not listening, >2min since last listen, has pending messages
+            const lastListened = agents[n].last_listened_at;
+            const sinceLastListen = lastListened ? Date.now() - new Date(lastListened).getTime() : Infinity;
+            const pendingForAgent = getUnconsumedMessages(n);
+            if (sinceLastListen > 120000 && pendingForAgent.length > 0) {
+              acc[n] = 'unresponsive';
+            } else {
+              acc[n] = 'working';
+            }
+          }
           return acc;
         }, {}),
         hint: silent.length > 0
@@ -1735,6 +1936,15 @@ function toolUpdateTask(taskId, status, notes = null) {
     return { error: `Task not found: ${taskId}` };
   }
 
+  // Prevent race condition: can't claim a task already in_progress by another agent
+  if (status === 'in_progress' && task.status === 'in_progress' && task.assignee && task.assignee !== registeredName) {
+    return { error: `Task already claimed by ${task.assignee}. Use suggest_task() to find another task.` };
+  }
+  // Auto-assign on claim
+  if (status === 'in_progress' && !task.assignee) {
+    task.assignee = registeredName;
+  }
+
   task.status = status;
   task.updated_at = new Date().toISOString();
   if (notes) {
@@ -2188,6 +2398,112 @@ function getVotes() { return readJsonFile(VOTES_FILE) || []; }
 function getReviews() { return readJsonFile(REVIEWS_FILE) || []; }
 function getDeps() { return readJsonFile(DEPS_FILE) || []; }
 
+// --- Channel helpers ---
+const CHANNELS_FILE_PATH = path.join(DATA_DIR, 'channels.json');
+
+function getChannelsData() {
+  const data = readJsonFile(CHANNELS_FILE_PATH);
+  if (!data) return { general: { description: 'General channel — all agents', members: ['*'], created_by: 'system', created_at: new Date().toISOString() } };
+  return data;
+}
+
+function saveChannelsData(channels) { writeJsonFile(CHANNELS_FILE_PATH, channels); }
+
+function getChannelMessagesFile(channelName) {
+  if (!channelName || channelName === 'general') return getMessagesFile(currentBranch);
+  return path.join(DATA_DIR, 'channel-' + sanitizeName(channelName) + '-messages.jsonl');
+}
+
+function getChannelHistoryFile(channelName) {
+  if (!channelName || channelName === 'general') return getHistoryFile(currentBranch);
+  return path.join(DATA_DIR, 'channel-' + sanitizeName(channelName) + '-history.jsonl');
+}
+
+function isChannelMember(channelName, agentName) {
+  const channels = getChannelsData();
+  if (!channels[channelName]) return false;
+  return channels[channelName].members.includes('*') || channels[channelName].members.includes(agentName);
+}
+
+function getAgentChannels(agentName) {
+  const channels = getChannelsData();
+  return Object.keys(channels).filter(ch => channels[ch].members.includes('*') || channels[ch].members.includes(agentName));
+}
+
+// Cleanup dead agents from channel membership (called from heartbeat)
+function cleanStaleChannelMembers() {
+  const channels = getChannelsData();
+  const agents = getAgents();
+  let changed = false;
+  for (const [name, ch] of Object.entries(channels)) {
+    if (name === 'general') continue; // general uses '*', no cleanup needed
+    const before = ch.members.length;
+    ch.members = ch.members.filter(m => m === '*' || (agents[m] && isPidAlive(agents[m].pid, agents[m].last_activity)));
+    if (ch.members.length !== before) changed = true;
+  }
+  if (changed) saveChannelsData(channels);
+}
+
+function toolJoinChannel(channelName, description) {
+  if (!registeredName) return { error: 'You must call register() first' };
+  if (typeof channelName !== 'string' || channelName.length < 1 || channelName.length > 30) return { error: 'Channel name must be 1-30 chars' };
+  sanitizeName(channelName);
+
+  const channels = getChannelsData();
+  if (!channels[channelName]) {
+    // Create new channel
+    channels[channelName] = {
+      description: (description || '').substring(0, 200),
+      members: [registeredName],
+      created_by: registeredName,
+      created_at: new Date().toISOString(),
+    };
+  } else if (!isChannelMember(channelName, registeredName)) {
+    channels[channelName].members.push(registeredName);
+  } else {
+    return { success: true, channel: channelName, message: 'Already a member of #' + channelName };
+  }
+  saveChannelsData(channels);
+  touchActivity();
+  return { success: true, channel: channelName, members: channels[channelName].members, message: 'Joined #' + channelName };
+}
+
+function toolLeaveChannel(channelName) {
+  if (!registeredName) return { error: 'You must call register() first' };
+  if (channelName === 'general') return { error: 'Cannot leave #general' };
+
+  const channels = getChannelsData();
+  if (!channels[channelName]) return { error: 'Channel not found: #' + channelName };
+  channels[channelName].members = channels[channelName].members.filter(m => m !== registeredName);
+  // Auto-delete empty channels (except general)
+  if (channels[channelName].members.length === 0) delete channels[channelName];
+  saveChannelsData(channels);
+  touchActivity();
+  return { success: true, channel: channelName, message: 'Left #' + channelName };
+}
+
+function toolListChannels() {
+  const channels = getChannelsData();
+  const result = {};
+  for (const [name, ch] of Object.entries(channels)) {
+    const msgFile = getChannelMessagesFile(name);
+    let msgCount = 0;
+    if (fs.existsSync(msgFile)) {
+      const content = fs.readFileSync(msgFile, 'utf8').trim();
+      if (content) msgCount = content.split('\n').length;
+    }
+    result[name] = {
+      description: ch.description || '',
+      members: ch.members,
+      member_count: ch.members.includes('*') ? 'all' : ch.members.length,
+      created_by: ch.created_by,
+      message_count: msgCount,
+      you_are_member: isChannelMember(name, registeredName),
+    };
+  }
+  return { channels: result, your_channels: getAgentChannels(registeredName) };
+}
+
 // Auto-cleanup dead agent locks (called from heartbeat)
 function cleanStaleLocks() {
   const locks = getLocks();
@@ -2238,6 +2554,34 @@ function fireEvent(eventName, data) {
   }
 }
 
+function toolGetGuide() {
+  if (!registeredName) return { error: 'You must call register() first' };
+  const config = getConfig();
+  const mode = config.conversation_mode || 'direct';
+  return {
+    your_name: registeredName,
+    conversation_mode: mode,
+    critical_rules: [
+      'AFTER EVERY ACTION, call listen_group() (group/managed) or listen() (direct). This is how you receive messages.',
+      'Never send multiple messages without listening between them.',
+      'Keep messages concise — 2-3 paragraphs max.',
+      'When you finish a task, report what you did + files changed, then listen again.',
+      'ALWAYS lock_file() before editing shared files, unlock_file() when done.',
+      'Use log_decision() for any team decisions so they are not re-debated.',
+      'Use kb_write() to share knowledge (API specs, conventions) so others can read without asking.',
+    ],
+    tool_categories: {
+      'MESSAGING': 'send_message, broadcast, listen_group, listen, check_messages, get_history, get_summary, handoff, share_file',
+      'COORDINATION': 'get_briefing, log_decision, get_decisions, kb_write, kb_read, kb_list, call_vote, cast_vote, vote_status',
+      'TASKS': 'create_task, update_task, list_tasks, declare_dependency, check_dependencies, suggest_task',
+      'QUALITY': 'update_progress, get_progress, request_review, submit_review, get_reputation',
+      'SAFETY': 'lock_file, unlock_file',
+      'MANAGED MODE': 'claim_manager, yield_floor, set_phase (manager only)',
+    },
+    workflow: '1. get_briefing → 2. check list_tasks/suggest_task → 3. claim task → 4. lock_file → 5. do work → 6. unlock_file → 7. update_task done → 8. listen_group',
+  };
+}
+
 function toolGetBriefing() {
   if (!registeredName) return { error: 'You must call register() first' };
 
@@ -2798,7 +3142,7 @@ function toolSuggestTask() {
 // --- MCP Server setup ---
 
 const server = new Server(
-  { name: 'agent-bridge', version: '3.7.0' },
+  { name: 'agent-bridge', version: '3.9.0' },
   { capabilities: { tools: {} } }
 );
 
@@ -2807,7 +3151,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: 'register',
-        description: 'Register this agent\'s identity (any name, e.g. "A", "Coder", "Reviewer"). Must be called before any other tool.',
+        description: 'Register this agent\'s identity. Must be called first. Returns a collaboration guide with all tool categories, critical rules, and workflow patterns — READ IT CAREFULLY before doing anything else. Then call get_briefing() for project context, then listen_group() to join the conversation.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -2849,6 +3193,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'ID of a previous message to thread this reply under (optional)',
             },
+            channel: {
+              type: 'string',
+              description: 'Channel to send to (optional — omit for #general). Use join_channel() first to create channels.',
+            },
           },
           required: ['content'],
         },
@@ -2886,7 +3234,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'listen',
-        description: 'Listen for messages indefinitely. Unlike wait_for_reply, this never times out — it blocks until a message arrives. The agent should call listen() after finishing any task to stay available. After receiving a message, process it, respond, then call listen() again.',
+        description: 'Listen for messages indefinitely. Auto-detects conversation mode: in group/managed mode, behaves like listen_group() (returns batched messages with agent statuses). In direct mode, returns one message at a time. Either listen() or listen_group() works in any mode — they auto-delegate to the correct behavior.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -3209,13 +3557,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'listen_group',
-        description: 'Listen for messages in group or managed conversation mode. Blocks indefinitely until messages arrive — never times out. Returns ALL unconsumed messages as a batch, plus conversation context, agent statuses, and hints. After processing messages and responding, call listen_group() again immediately. This is how you stay in the conversation.',
+        description: 'Listen for messages in group or managed conversation mode. Auto-detects mode: in direct mode, behaves like listen(). Returns ALL unconsumed messages as a sorted batch (system > threaded > direct > broadcast), plus batch_summary, agent statuses, and hints. Either listen() or listen_group() works in any mode — they auto-delegate. Call again immediately after responding.',
         inputSchema: {
           type: 'object',
           properties: {},
         },
       },
+      // --- Channels ---
+      {
+        name: 'join_channel',
+        description: 'Join or create a channel. Channels let sub-teams communicate without flooding the main conversation. Auto-joined to #general on register. Use channels when team size > 4.',
+        inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Channel name (1-30 chars, e.g. "backend", "testing")' }, description: { type: 'string', description: 'Channel description (optional, max 200 chars)' } }, required: ['name'] },
+      },
+      {
+        name: 'leave_channel',
+        description: 'Leave a channel. You will stop receiving messages from it. Cannot leave #general.',
+        inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Channel to leave' } }, required: ['name'] },
+      },
+      {
+        name: 'list_channels',
+        description: 'List all channels with members, message counts, and your membership status.',
+        inputSchema: { type: 'object', properties: {} },
+      },
       // --- Briefing & Recovery ---
+      {
+        name: 'get_guide',
+        description: 'Get the collaboration guide — all tool categories, critical rules, and workflow patterns. Call this if you are unsure how to use the tools or need a refresher on best practices.',
+        inputSchema: { type: 'object', properties: {} },
+      },
       {
         name: 'get_briefing',
         description: 'Get a full project briefing: who is online, active tasks, recent decisions, knowledge base, locked files, progress, and project files. Call this when joining a project or after being away. One call = fully onboarded.',
@@ -3375,7 +3744,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         result = toolListAgents();
         break;
       case 'send_message':
-        result = await toolSendMessage(args.content, args?.to, args?.reply_to);
+        result = await toolSendMessage(args.content, args?.to, args?.reply_to, args?.channel);
         break;
       case 'wait_for_reply':
         result = await toolWaitForReply(args?.timeout_seconds, args?.from);
@@ -3455,6 +3824,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'listen_group':
         result = await toolListenGroup();
         break;
+      case 'join_channel':
+        result = toolJoinChannel(args.name, args?.description);
+        break;
+      case 'leave_channel':
+        result = toolLeaveChannel(args.name);
+        break;
+      case 'list_channels':
+        result = toolListChannels();
+        break;
+      case 'get_guide':
+        result = toolGetGuide();
+        break;
       case 'get_briefing':
         result = toolGetBriefing();
         break;
@@ -3538,14 +3919,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       };
     }
 
-    // Global hook: on non-listen tools, check for pending messages and nudge the agent
+    // Global hook: on non-listen tools, check for pending messages and nudge with escalating urgency
     const listenTools = ['listen', 'listen_group', 'listen_codex', 'wait_for_reply', 'check_messages'];
     if (registeredName && !listenTools.includes(name) && (isGroupMode() || isManagedMode())) {
       try {
         const pending = getUnconsumedMessages(registeredName);
         if (pending.length > 0 && !result.you_have_messages) {
           result._pending_messages = pending.length;
-          result._nudge = `You have ${pending.length} unread message(s) from the team. Finish your current task quickly, then call listen_group() to read them.`;
+          // Escalate urgency based on oldest pending message age
+          const oldestAge = pending.reduce((max, m) => {
+            const age = Date.now() - new Date(m.timestamp).getTime();
+            return age > max ? age : max;
+          }, 0);
+          const ageSec = Math.round(oldestAge / 1000);
+          if (ageSec > 120) {
+            result._nudge = `CRITICAL: ${pending.length} message(s) waiting ${Math.round(ageSec / 60)}+ min. Team is likely blocked on you. Call listen_group() NOW.`;
+          } else if (ageSec > 30) {
+            result._nudge = `URGENT: ${pending.length} message(s) waiting ${ageSec}s. Team may be blocked. Call listen_group() soon.`;
+          } else {
+            result._nudge = `You have ${pending.length} unread message(s). Call listen_group() after this to read them.`;
+          }
         }
       } catch {}
     }
@@ -3603,7 +3996,7 @@ async function main() {
   ensureDataDir();
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('Agent Bridge MCP server v3.7.0 running (52 tools)');
+  console.error('Agent Bridge MCP server v3.9.0 running (56 tools)');
 }
 
 main().catch(console.error);