@hueyexe/opencode-ensemble 0.10.0 → 0.11.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
 [![npm downloads](https://img.shields.io/npm/dm/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
-[![tests](https://img.shields.io/badge/tests-460%20passing-brightgreen.svg)]()
+[![tests](https://img.shields.io/badge/tests-471%20passing-brightgreen.svg)]()
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)]()
 [![OpenCode SDK](https://img.shields.io/badge/deps-OpenCode%20SDK%20only-blue.svg)]()
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
@@ -126,7 +126,7 @@ Add to your OpenCode config with a pinned version. Project-level or global.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.10.0"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.11.0"]
 }
 ```
 
@@ -134,7 +134,7 @@ Add to your OpenCode config with a pinned version. Project-level or global.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.10.0"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.11.0"]
 }
 ```
 
@@ -242,6 +242,7 @@ Teammate messages arrive in the lead's session as `[Team message from alice]: ..
 - **Spawn rollback**: if the initial prompt fails, the member, session, and worktree are all cleaned up
 - **Timeout watchdog**: teammates stuck busy beyond the TTL are automatically timed out and aborted
 - **Stall detection**: detects teammates making no progress (low output tokens or no communication) and escalates to the lead
+- **Peer-to-peer communication**: teammates can message each other directly, with idle-flush delivery and chatty agent detection
 - **Auto-merge on cleanup**: worktree branches are squash-merged into your working directory as unstaged changes for review
 - **Spawn circuit breaker**: stops retrying after 3 consecutive spawn failures
 - **Graceful shutdown**: busy teammates receive a shutdown message and finish their current work. Use `force: true` to abort immediately.
@@ -336,7 +337,7 @@ Same coordination model (shared tasks, peer messaging, lead coordination) with s
 ```bash
 bun install
 bun run typecheck
-bun test             # 460 tests
+bun test             # 471 tests
 bun run build
 ```
 

package/dist/index.js

@@ -15987,7 +15987,28 @@ function buildTeammateSystemPrompt(db, teamId, memberName) {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
   if (!team)
     return "";
-  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`;
+  const lines = [
+    `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`
+  ];
+  const pendingMessages = db.query("SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 ORDER BY time_created ASC").all(teamId, memberName);
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Messages for you ---");
+    const MAX_MSG = 500;
+    for (const msg of pendingMessages) {
+      const parsed = parseTaskResult(msg.content);
+      if (parsed) {
+        lines.push(formatTaskResult(msg.from_name, { ...parsed, details: truncate(parsed.details, MAX_MSG) }));
+      } else if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (truncated)`);
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`);
+      }
+      markDelivered(db, msg.id);
+    }
+    lines.push("--- End Messages ---");
+  }
+  return lines.join(`
+`);
 }
 function buildTeamCompactionContext(db, teamId, role, memberName) {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId);
@@ -16070,7 +16091,9 @@ var DEFAULT_CONFIG = {
   stallTokenThreshold: 500,
   timeoutMs: 30 * 60 * 1000,
   rateLimitCapacity: 10,
-  dashboardPort: 4747
+  dashboardPort: 4747,
+  peerMessageLimit: 5,
+  peerMessageWindowMs: 300000
 };
 function readConfigFile(filePath) {
   try {
@@ -16091,6 +16114,10 @@ function readConfigFile(filePath) {
       result.rateLimitCapacity = raw.rateLimitCapacity;
     if (typeof raw.dashboardPort === "number")
       result.dashboardPort = raw.dashboardPort;
+    if (typeof raw.peerMessageLimit === "number")
+      result.peerMessageLimit = raw.peerMessageLimit;
+    if (typeof raw.peerMessageWindowMs === "number")
+      result.peerMessageWindowMs = raw.peerMessageWindowMs;
     return result;
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
@@ -16123,7 +16150,9 @@ class ProgressTracker {
   steps = new Map;
   lastMessageAt = new Map;
   lastTaskAt = new Map;
+  peerMessages = new Map;
   reported = new Set;
+  chattyReported = new Set;
   maxSteps;
   constructor(maxSteps = 10) {
     this.maxSteps = maxSteps;
@@ -16135,6 +16164,31 @@ class ProgressTracker {
       records.shift();
     this.steps.set(sessionId, records);
   }
+  recordPeerMessage(sessionId) {
+    const timestamps = this.peerMessages.get(sessionId) ?? [];
+    timestamps.push(Date.now());
+    this.peerMessages.set(sessionId, timestamps);
+  }
+  isChatty(sessionId, limit, windowMs) {
+    if (limit === 0)
+      return false;
+    const timestamps = this.peerMessages.get(sessionId);
+    if (!timestamps)
+      return false;
+    const cutoff = Date.now() - windowMs;
+    const recent = timestamps.filter((t) => t >= cutoff);
+    this.peerMessages.set(sessionId, recent);
+    return recent.length >= limit;
+  }
+  markChattyReported(sessionId) {
+    this.chattyReported.add(sessionId);
+  }
+  isChattyReported(sessionId) {
+    return this.chattyReported.has(sessionId);
+  }
+  clearChattyReport(sessionId) {
+    this.chattyReported.delete(sessionId);
+  }
   recordMessage(sessionId) {
     this.lastMessageAt.set(sessionId, Date.now());
     this.clearReport(sessionId);
@@ -16173,7 +16227,9 @@ class ProgressTracker {
     this.steps.delete(sessionId);
     this.lastMessageAt.delete(sessionId);
     this.lastTaskAt.delete(sessionId);
+    this.peerMessages.delete(sessionId);
     this.reported.delete(sessionId);
+    this.chattyReported.delete(sessionId);
   }
 }
 
@@ -16558,16 +16614,17 @@ function rActivity(t){
     const p=parseR(m.content);
     const deliv=m.delivered?(m.read?'\\u2713\\u2713':'\\u2713'):'';
     const isFromAgent=m.fromName!=='lead'&&m.fromName!=='system';
+    const isPeer=isFromAgent&&m.toName&&m.toName!=='lead'&&m.toName!=='all';
     const align=isFromAgent?'mr-6':'ml-6';
-    const bubbleBg=isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
+    const bubbleBg=isPeer?'bg-violet-500/[0.06] border-violet-500/15':isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
     const initial=m.fromName.charAt(0).toUpperCase();
-    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
+    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isPeer?'bg-violet-500/20 text-violet-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
     html+='<div class="'+align+(isNew?' hl':'')+' cursor-pointer" data-msg="'+E(m.id)+'" onclick="toggleMsg(\\''+E(m.id)+'\\')">';
     html+='<div class="flex items-start gap-2">';
     html+='<span class="w-5 h-5 rounded-full '+avatarColor+' flex items-center justify-center text-[9px] font-semibold shrink-0 mt-0.5">'+E(initial)+'</span>';
     html+='<div class="flex-1 min-w-0 rounded-xl border '+bubbleBg+' px-3 py-2">';
     html+='<div class="flex items-center gap-1.5 mb-1">';
-    html+='<span class="text-[11px] font-medium '+(isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
+    html+='<span class="text-[11px] font-medium '+(isPeer?'text-violet-400':isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
     if(m.toName)html+=chip('\\u2192 '+E(m.toName),'muted');
     html+=chip(relT(m.timeCreated),'muted');
     if(deliv)html+='<span class="text-txt-500 text-[10px] ml-auto">'+deliv+'</span>';
@@ -16953,6 +17010,9 @@ async function executeTeamSpawn(deps, args, sessionId) {
   } else {
     context.push("", "Tools available to you:", "- team_message: send a message to the lead or another teammate", "- team_broadcast: send a message to all team members", "- team_tasks_list: view the shared team task board", "- team_tasks_add: add tasks to the shared board", "- team_tasks_complete: mark a task complete on the shared board", "- team_claim: claim a pending task from the shared board");
   }
+  if (otherMembers.length > 0) {
+    context.push("", "Collaboration:", "- Check team_tasks_list to see what other teammates are working on.", "- If you need information another teammate has, message them directly via team_message.", "- If you discover something relevant to another teammate's task, share it with them.", "- Use team_broadcast for updates that affect the whole team.", "- Keep peer messages focused and actionable \u2014 coordinate, don't chat.");
+  }
   context.push("", "When you finish your task:");
   if (!isReadOnly && worktreeBranch) {
     context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`);
@@ -17020,6 +17080,19 @@ async function executeTeamMessage(deps, args, sessionId) {
   const teamInfo = requireTeamMember(deps, sessionId);
   const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to);
+  if (!recipientSessionId && args.to !== "lead") {
+    if (args.approve || args.reject) {
+      throw new Error(`Cannot approve/reject plan for "${args.to}" \u2014 they haven't been spawned yet.`);
+    }
+    sendMessage(deps.db, {
+      teamId: teamInfo.teamId,
+      from: senderName,
+      to: args.to,
+      content: args.text
+    });
+    log(`team_message:queued from=${senderName} to=${args.to} (recipient not yet spawned)`);
+    return `Message queued for ${args.to} \u2014 they haven't been spawned yet. It will be delivered when they join the team.`;
+  }
   if (!recipientSessionId)
     throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`);
   let messageText = args.text;
@@ -17580,6 +17653,8 @@ class Watchdog {
   stallMinSteps;
   stallTokenThreshold;
   cwd;
+  peerMessageLimit;
+  peerMessageWindowMs;
   timer;
   constructor(opts) {
     this.db = opts.db;
@@ -17592,6 +17667,8 @@ class Watchdog {
     this.stallMinSteps = opts.stallMinSteps ?? 3;
     this.stallTokenThreshold = opts.stallTokenThreshold ?? 500;
     this.cwd = opts.cwd;
+    this.peerMessageLimit = opts.peerMessageLimit ?? 0;
+    this.peerMessageWindowMs = opts.peerMessageWindowMs ?? 300000;
   }
   static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300000;
   async cleanupStaleWorktrees() {
@@ -17649,9 +17726,36 @@ class Watchdog {
       } catch {}
     }
   }
+  async checkChatty() {
+    if (!this.progressTracker || this.peerMessageLimit === 0)
+      return;
+    const busy = this.db.query(`SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active' AND tm.status = 'busy'`).all();
+    for (const member of busy) {
+      if (this.progressTracker.isChattyReported(member.session_id))
+        continue;
+      if (!this.progressTracker.isChatty(member.session_id, this.peerMessageLimit, this.peerMessageWindowMs))
+        continue;
+      this.progressTracker.markChattyReported(member.session_id);
+      this.client.session.promptAsync({
+        sessionID: member.session_id,
+        parts: [{ type: "text", text: "[System]: You've sent several messages to teammates. Focus on completing your task and send your results to the lead via team_message." }]
+      }).catch(() => {});
+      sendMessage(this.db, {
+        teamId: member.team_id,
+        from: "system",
+        to: "lead",
+        content: `Agent "${member.name}" is sending many peer messages and may be over-coordinating. Consider checking on them.`
+      });
+      log(`watchdog:chatty member=${member.name} limit=${this.peerMessageLimit}`);
+    }
+  }
   async check() {
     await this.cleanupStaleWorktrees();
     await this.checkStalled();
+    await this.checkChatty();
     if (this.ttlMs === 0)
       return;
     const cutoff = Date.now() - this.ttlMs;
@@ -17761,7 +17865,9 @@ var plugin = async (input) => {
     stallThresholdMs: config2.stallThresholdMs,
     stallMinSteps: config2.stallMinSteps,
     stallTokenThreshold: config2.stallTokenThreshold,
-    cwd: input.directory
+    cwd: input.directory,
+    peerMessageLimit: config2.peerMessageLimit,
+    peerMessageWindowMs: config2.peerMessageWindowMs
   });
   watchdog.start();
   return {
@@ -17829,6 +17935,22 @@ var plugin = async (input) => {
               });
             }
           }
+          const member = db.query(`SELECT tm.team_id, tm.name FROM team_member tm
+             JOIN team t ON tm.team_id = t.id
+             WHERE tm.session_id = ? AND t.status = 'active'`).get(sessionID);
+          if (member) {
+            const staleThreshold = Date.now() - 5000;
+            const peerMsgs = db.query("SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 AND time_created < ?").get(member.team_id, member.name, staleThreshold);
+            if (peerMsgs.c > 0) {
+              log(`wake-peer: ${member.name} has ${peerMsgs.c} pending peer messages`);
+              client3.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${peerMsgs.c} new message(s) from teammates]` }]
+              }).catch((err) => {
+                log(`wake-peer:failed err=${err instanceof Error ? err.message : String(err)}`);
+              });
+            }
+          }
         }
       }
       if (event.type === "session.created") {
@@ -17931,6 +18053,8 @@ var plugin = async (input) => {
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID);
           progressTracker.recordMessage(ctx.sessionID);
+          if (args.to !== "lead")
+            progressTracker.recordPeerMessage(ctx.sessionID);
           ctx.metadata({ title: `Message \u2192 ${args.to}` });
           return result;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",

package/src/config.ts

@@ -17,6 +17,10 @@ export interface EnsembleConfig {
   rateLimitCapacity?: number
   /** Dashboard server port (default: 4747, 0 to disable) */
   dashboardPort?: number
+  /** Max peer messages per agent per window before nudge (default: 5, 0 to disable) */
+  peerMessageLimit?: number
+  /** Time window for peer message rate limiting in ms (default: 300000 = 5 min) */
+  peerMessageWindowMs?: number
 }
 
 /** Default configuration values. */
@@ -28,6 +32,8 @@ export const DEFAULT_CONFIG: Required<EnsembleConfig> = {
   timeoutMs: 30 * 60 * 1000,
   rateLimitCapacity: 10,
   dashboardPort: 4747,
+  peerMessageLimit: 5,
+  peerMessageWindowMs: 300_000,
 }
 
 /** Read a JSON config file, returning an empty object on missing/invalid. */
@@ -44,6 +50,8 @@ function readConfigFile(filePath: string): Partial<EnsembleConfig> {
     if (typeof raw.timeoutMs === "number") result.timeoutMs = raw.timeoutMs
     if (typeof raw.rateLimitCapacity === "number") result.rateLimitCapacity = raw.rateLimitCapacity
     if (typeof raw.dashboardPort === "number") result.dashboardPort = raw.dashboardPort
+    if (typeof raw.peerMessageLimit === "number") result.peerMessageLimit = raw.peerMessageLimit
+    if (typeof raw.peerMessageWindowMs === "number") result.peerMessageWindowMs = raw.peerMessageWindowMs
     return result
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return {}

package/src/dashboard-js-part2.ts

@@ -189,16 +189,17 @@ function rActivity(t){
     const p=parseR(m.content);
     const deliv=m.delivered?(m.read?'\\u2713\\u2713':'\\u2713'):'';
     const isFromAgent=m.fromName!=='lead'&&m.fromName!=='system';
+    const isPeer=isFromAgent&&m.toName&&m.toName!=='lead'&&m.toName!=='all';
     const align=isFromAgent?'mr-6':'ml-6';
-    const bubbleBg=isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
+    const bubbleBg=isPeer?'bg-violet-500/[0.06] border-violet-500/15':isFromAgent?'bg-blue-500/[0.06] border-blue-500/15':'bg-base-800/40 border-base-700/30';
     const initial=m.fromName.charAt(0).toUpperCase();
-    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
+    const avatarColor=m.fromName==='system'?'bg-amber-500/20 text-amber-400':isPeer?'bg-violet-500/20 text-violet-400':isFromAgent?'bg-blue-500/20 text-blue-400':'bg-emerald-500/20 text-emerald-400';
     html+='<div class="'+align+(isNew?' hl':'')+' cursor-pointer" data-msg="'+E(m.id)+'" onclick="toggleMsg(\\''+E(m.id)+'\\')">';
     html+='<div class="flex items-start gap-2">';
     html+='<span class="w-5 h-5 rounded-full '+avatarColor+' flex items-center justify-center text-[9px] font-semibold shrink-0 mt-0.5">'+E(initial)+'</span>';
     html+='<div class="flex-1 min-w-0 rounded-xl border '+bubbleBg+' px-3 py-2">';
     html+='<div class="flex items-center gap-1.5 mb-1">';
-    html+='<span class="text-[11px] font-medium '+(isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
+    html+='<span class="text-[11px] font-medium '+(isPeer?'text-violet-400':isFromAgent?'text-blue-400':'text-txt-300')+'">'+E(m.fromName)+'</span>';
     if(m.toName)html+=chip('\\u2192 '+E(m.toName),'muted');
     html+=chip(relT(m.timeCreated),'muted');
     if(deliv)html+='<span class="text-txt-500 text-[10px] ml-auto">'+deliv+'</span>';

package/src/index.ts

@@ -122,6 +122,8 @@ const plugin: Plugin = async (input) => {
     stallMinSteps: config.stallMinSteps,
     stallTokenThreshold: config.stallTokenThreshold,
     cwd: input.directory,
+    peerMessageLimit: config.peerMessageLimit,
+    peerMessageWindowMs: config.peerMessageWindowMs,
   })
   watchdog.start()
 
@@ -206,6 +208,29 @@ const plugin: Plugin = async (input) => {
               })
             }
           }
+
+          // Also flush peer messages for teammates that just went idle
+          // Only flush messages older than 5s to avoid double-delivery with the direct promptAsync path
+          const member = db.query(
+            `SELECT tm.team_id, tm.name FROM team_member tm
+             JOIN team t ON tm.team_id = t.id
+             WHERE tm.session_id = ? AND t.status = 'active'`
+          ).get(sessionID) as { team_id: string; name: string } | null
+          if (member) {
+            const staleThreshold = Date.now() - 5000
+            const peerMsgs = db.query(
+              "SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 AND time_created < ?"
+            ).get(member.team_id, member.name, staleThreshold) as { c: number }
+            if (peerMsgs.c > 0) {
+              log(`wake-peer: ${member.name} has ${peerMsgs.c} pending peer messages`)
+              client.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${peerMsgs.c} new message(s) from teammates]` }],
+              }).catch((err) => {
+                log(`wake-peer:failed err=${err instanceof Error ? err.message : String(err)}`)
+              })
+            }
+          }
         }
       }
 
@@ -325,6 +350,8 @@ const plugin: Plugin = async (input) => {
           const result = await executeTeamMessage(deps, args, ctx.sessionID)
           // Track message activity for stall detection
           progressTracker.recordMessage(ctx.sessionID)
+          // Track peer messages for chatty detection
+          if (args.to !== "lead") progressTracker.recordPeerMessage(ctx.sessionID)
           ctx.metadata({ title: `Message → ${args.to}` })
           return result
         },

package/src/progress.ts

@@ -12,7 +12,9 @@ export class ProgressTracker {
   private steps = new Map<string, StepRecord[]>()
   private lastMessageAt = new Map<string, number>()
   private lastTaskAt = new Map<string, number>()
+  private peerMessages = new Map<string, number[]>()
   private reported = new Set<string>()
+  private chattyReported = new Set<string>()
   private readonly maxSteps: number
 
   constructor(maxSteps = 10) {
@@ -27,6 +29,40 @@ export class ProgressTracker {
     this.steps.set(sessionId, records)
   }
 
+  /** Record a peer message (not to lead). Used for chatty detection. */
+  recordPeerMessage(sessionId: string): void {
+    const timestamps = this.peerMessages.get(sessionId) ?? []
+    timestamps.push(Date.now())
+    this.peerMessages.set(sessionId, timestamps)
+  }
+
+  /** Check if agent is chatty: more than `limit` peer messages within `windowMs`. */
+  isChatty(sessionId: string, limit: number, windowMs: number): boolean {
+    if (limit === 0) return false
+    const timestamps = this.peerMessages.get(sessionId)
+    if (!timestamps) return false
+    const cutoff = Date.now() - windowMs
+    const recent = timestamps.filter(t => t >= cutoff)
+    // Prune old timestamps
+    this.peerMessages.set(sessionId, recent)
+    return recent.length >= limit
+  }
+
+  /** Mark chatty as reported (avoid spam). */
+  markChattyReported(sessionId: string): void {
+    this.chattyReported.add(sessionId)
+  }
+
+  /** Check if chatty already reported. */
+  isChattyReported(sessionId: string): boolean {
+    return this.chattyReported.has(sessionId)
+  }
+
+  /** Clear chatty report (e.g., when agent sends result to lead). */
+  clearChattyReport(sessionId: string): void {
+    this.chattyReported.delete(sessionId)
+  }
+
   /** Record that this member sent a team_message. Clears stall report. */
   recordMessage(sessionId: string): void {
     this.lastMessageAt.set(sessionId, Date.now())
@@ -80,6 +116,8 @@ export class ProgressTracker {
     this.steps.delete(sessionId)
     this.lastMessageAt.delete(sessionId)
     this.lastTaskAt.delete(sessionId)
+    this.peerMessages.delete(sessionId)
     this.reported.delete(sessionId)
+    this.chattyReported.delete(sessionId)
   }
 }

package/src/system-prompt.ts

@@ -125,13 +125,39 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
 
 /**
  * Build the system prompt injected into a teammate's session.
- * Short role reminder with name, team name, and communication tool.
+ * Includes role reminder and delivers any pending peer messages.
  */
 export function buildTeammateSystemPrompt(db: Database, teamId: string, memberName: string): string {
   const team = db.query("SELECT name FROM team WHERE id = ?").get(teamId) as { name: string } | null
   if (!team) return ""
 
-  return `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`
+  const lines = [
+    `You are "${memberName}", a teammate in team "${team.name}". Use team_message to communicate. You MUST send your results to the lead via team_message before stopping.`,
+  ]
+
+  // Deliver pending peer messages addressed to this teammate
+  const pendingMessages = db.query(
+    "SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = ? AND delivered = 0 ORDER BY time_created ASC"
+  ).all(teamId, memberName) as Array<{ id: string; from_name: string; content: string }>
+
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Messages for you ---")
+    const MAX_MSG = 500
+    for (const msg of pendingMessages) {
+      const parsed = parseTaskResult(msg.content)
+      if (parsed) {
+        lines.push(formatTaskResult(msg.from_name, { ...parsed, details: truncate(parsed.details, MAX_MSG) }))
+      } else if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (truncated)`)
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`)
+      }
+      markDelivered(db, msg.id)
+    }
+    lines.push("--- End Messages ---")
+  }
+
+  return lines.join("\n")
 }
 
 /**

package/src/tools/team-message.ts

@@ -18,6 +18,22 @@ export async function executeTeamMessage(
   const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
+
+  // If recipient not found, store the message for later delivery (they may not be spawned yet)
+  // Reject approve/reject flags for unspawned recipients — plan approval requires the member to exist
+  if (!recipientSessionId && args.to !== "lead") {
+    if (args.approve || args.reject) {
+      throw new Error(`Cannot approve/reject plan for "${args.to}" — they haven't been spawned yet.`)
+    }
+    sendMessage(deps.db, {
+      teamId: teamInfo.teamId,
+      from: senderName,
+      to: args.to,
+      content: args.text,
+    })
+    log(`team_message:queued from=${senderName} to=${args.to} (recipient not yet spawned)`)
+    return `Message queued for ${args.to} — they haven't been spawned yet. It will be delivered when they join the team.`
+  }
   if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
 
   // Handle plan approval/rejection

package/src/tools/team-spawn.ts

@@ -253,6 +253,19 @@ export async function executeTeamSpawn(
     )
   }
 
+  // Collaboration guidance for peer-to-peer communication
+  if (otherMembers.length > 0) {
+    context.push(
+      "",
+      "Collaboration:",
+      "- Check team_tasks_list to see what other teammates are working on.",
+      "- If you need information another teammate has, message them directly via team_message.",
+      "- If you discover something relevant to another teammate's task, share it with them.",
+      "- Use team_broadcast for updates that affect the whole team.",
+      "- Keep peer messages focused and actionable — coordinate, don't chat.",
+    )
+  }
+
   context.push("", "When you finish your task:")
   if (!isReadOnly && worktreeBranch) {
     context.push(`1. Commit your changes: git add -A && git commit -m "your summary"`)

package/src/watchdog.ts

@@ -24,6 +24,10 @@ interface WatchdogOpts {
   stallTokenThreshold?: number
   /** Project directory for git operations. */
   cwd?: string
+  /** Max peer messages per agent per window before nudge. 0 disables. */
+  peerMessageLimit?: number
+  /** Time window for peer message rate limiting in ms. */
+  peerMessageWindowMs?: number
 }
 
 /**
@@ -41,6 +45,8 @@ export class Watchdog {
   private readonly stallMinSteps: number
   private readonly stallTokenThreshold: number
   private readonly cwd?: string
+  private readonly peerMessageLimit: number
+  private readonly peerMessageWindowMs: number
   private timer: ReturnType<typeof setInterval> | undefined
 
   constructor(opts: WatchdogOpts) {
@@ -54,6 +60,8 @@ export class Watchdog {
     this.stallMinSteps = opts.stallMinSteps ?? 3
     this.stallTokenThreshold = opts.stallTokenThreshold ?? 500
     this.cwd = opts.cwd
+    this.peerMessageLimit = opts.peerMessageLimit ?? 0
+    this.peerMessageWindowMs = opts.peerMessageWindowMs ?? 300_000
   }
 
   private static STALE_THRESHOLD_MS = Number(process.env.STALE_WORKTREE_THRESHOLD_MS) || 300_000
@@ -133,10 +141,46 @@ export class Watchdog {
     }
   }
 
+  /** Check for chatty agents sending too many peer messages. */
+  async checkChatty(): Promise<void> {
+    if (!this.progressTracker || this.peerMessageLimit === 0) return
+
+    const busy = this.db.query(
+      `SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active' AND tm.status = 'busy'`
+    ).all() as Array<{ team_id: string; name: string; session_id: string }>
+
+    for (const member of busy) {
+      if (this.progressTracker.isChattyReported(member.session_id)) continue
+      if (!this.progressTracker.isChatty(member.session_id, this.peerMessageLimit, this.peerMessageWindowMs)) continue
+
+      this.progressTracker.markChattyReported(member.session_id)
+
+      // Nudge the agent
+      this.client.session.promptAsync({
+        sessionID: member.session_id,
+        parts: [{ type: "text", text: "[System]: You've sent several messages to teammates. Focus on completing your task and send your results to the lead via team_message." }],
+      }).catch(() => { /* best effort */ })
+
+      // Notify the lead
+      sendMessage(this.db, {
+        teamId: member.team_id,
+        from: "system",
+        to: "lead",
+        content: `Agent "${member.name}" is sending many peer messages and may be over-coordinating. Consider checking on them.`,
+      })
+
+      log(`watchdog:chatty member=${member.name} limit=${this.peerMessageLimit}`)
+    }
+  }
+
   /** Run a single check for stale busy members. */
   async check(): Promise<void> {
     await this.cleanupStaleWorktrees()
     await this.checkStalled()
+    await this.checkChatty()
     if (this.ttlMs === 0) return
 
     const cutoff = Date.now() - this.ttlMs