@hueyexe/opencode-ensemble 0.6.3 → 0.6.4

package/dist/index.js

@@ -15446,6 +15446,9 @@ function validateTeamName(name) {
     return "Team name must be lowercase alphanumeric with hyphens only";
   return;
 }
+function isWorktreeInstance(directory) {
+  return directory.includes("/worktree/") && directory.includes("/ensemble-");
+}
 function validateMemberName(name) {
   if (name.toLowerCase() === "lead")
     return `Name "lead" is reserved`;
@@ -15480,30 +15483,6 @@ function getUndeliveredMessages(db, teamId) {
 function markDelivered(db, messageId) {
   db.run("UPDATE team_message SET delivered = 1 WHERE id = ?", [messageId]);
 }
-async function flushPendingMessages(db, client3, teamId, leadSessionId) {
-  const pending = db.query("SELECT * FROM team_message WHERE team_id = ? AND delivered = 0 AND to_name = 'lead' ORDER BY time_created ASC").all(teamId);
-  if (pending.length === 0)
-    return 0;
-  const MAX_LEAD_MSG = 500;
-  const parts = pending.map((msg) => {
-    if (msg.content.length > MAX_LEAD_MSG) {
-      return `[Team message from ${msg.from_name}]: ${msg.content.slice(0, MAX_LEAD_MSG)}... (use team_results to read full message)`;
-    }
-    return `[Team message from ${msg.from_name}]: ${msg.content}`;
-  });
-  try {
-    await client3.session.promptAsync({
-      sessionID: leadSessionId,
-      parts: [{ type: "text", text: parts.join(`
-`) }]
-    });
-    for (const msg of pending)
-      markDelivered(db, msg.id);
-    return pending.length;
-  } catch {
-    return 0;
-  }
-}
 
 // src/recovery.ts
 async function recoverStaleMembers(db, client3) {
@@ -15552,7 +15531,7 @@ async function recoverUndeliveredMessages(db, client3, registry2) {
     for (const msg of messages) {
       let recipientSessionId;
       if (msg.to_name === "lead") {
-        recipientSessionId = team.lead_session_id;
+        continue;
       } else if (msg.to_name) {
         const entry = registry2.getByName(team.id, msg.to_name);
         recipientSessionId = entry?.sessionId;
@@ -15690,12 +15669,6 @@ function checkToolIsolation(registry2, tracker, toolName, sessionId) {
     throw new Error("Team tools are not available to sub-agents. Report findings to your parent teammate via your normal output.");
   }
 }
-async function handleLeadIdleFlush(db, client3, sessionId) {
-  const team = db.query("SELECT id FROM team WHERE lead_session_id = ? AND status = 'active'").get(sessionId);
-  if (!team)
-    return 0;
-  return flushPendingMessages(db, client3, team.id, sessionId);
-}
 
 // src/notify.ts
 var TOAST_CONFIG = {
@@ -15778,16 +15751,27 @@ function buildLeadSystemPrompt(db, teamId) {
   const pending = countMap.pending ?? 0;
   const memberList = members.map((m) => `${m.name} [${STATUS_DISPLAY[m.status] ?? m.status}]`).join(", ");
   const teammateLine = members.length > 0 ? `Teammates: ${memberList}` : "Teammates: none";
-  return [
+  const pendingMessages = db.query("SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = 'lead' AND delivered = 0 ORDER BY time_created ASC").all(teamId);
+  const lines = [
     `You are leading team "${team.name}" with ${members.length} active teammates.`,
     teammateLine,
-    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
-    "",
-    "Teammates work asynchronously and message you when done.",
-    "Do NOT poll team_status or team_tasks_list repeatedly \u2014 wait for messages.",
-    "After spawning teammates, tell the user what you've set up and wait.",
-    "When all teammates finish, summarize results and suggest next steps."
-  ].join(`
+    `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`
+  ];
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Team Messages ---");
+    const MAX_MSG = 500;
+    for (const msg of pendingMessages) {
+      if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (use team_results to read full message)`);
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`);
+      }
+      markDelivered(db, msg.id);
+    }
+    lines.push("--- End Messages ---");
+  }
+  lines.push("", "CRITICAL: Spawn teammates ONE AT A TIME. Send only ONE team_spawn call per response.", "Wait for the tool result before spawning the next teammate.", "Multiple team_spawn calls in a single response will cause timeouts.", "", "Teammates work asynchronously and message you when done.", "Do NOT poll team_status or team_tasks_list repeatedly \u2014 wait for messages.", "After spawning all teammates, tell the user what you've set up and wait.", "When all teammates finish, summarize results and suggest next steps.");
+  return lines.join(`
 `);
 }
 function buildTeammateSystemPrompt(db, teamId, memberName) {
@@ -15820,6 +15804,17 @@ function buildTeamCompactionContext(db, teamId, role, memberName) {
 `);
 }
 
+// src/log.ts
+var _client = null;
+function initLog(client3) {
+  _client = client3;
+}
+function log(msg) {
+  if (!_client)
+    return;
+  _client.app.log({ service: "ensemble", level: "info", message: msg }).catch(() => {});
+}
+
 // src/types.ts
 function findTeamBySession(db, registry2, sessionId) {
   const entry = registry2.getBySession(sessionId);
@@ -15860,6 +15855,18 @@ async function executeTeamCreate(deps, args, sessionId) {
 }
 
 // src/tools/team-spawn.ts
+function getSpawnTimeout() {
+  return Number(process.env.SPAWN_TIMEOUT_MS) || 120000;
+}
+function withTimeout(promise2, ms, label) {
+  let timer;
+  return Promise.race([
+    promise2.finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    })
+  ]);
+}
 async function executeTeamSpawn(deps, args, sessionId) {
   const nameError = validateMemberName(args.name);
   if (nameError)
@@ -15874,17 +15881,21 @@ async function executeTeamSpawn(deps, args, sessionId) {
     throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`);
   const useWorktree = args.worktree !== false;
   const usePlanApproval = args.plan_approval === true;
+  log(`spawn:start name=${args.name} agent=${args.agent} worktree=${useWorktree}`);
   let worktreeDir = null;
   let worktreeBranch = null;
   if (useWorktree) {
     const worktreeName = `ensemble-${teamInfo.teamName}-${args.name}`;
     try {
-      const result = await deps.client.worktree.create({ worktreeCreateInput: { name: worktreeName } });
+      log(`spawn:worktree:start name=${args.name}`);
+      const result = await withTimeout(deps.client.worktree.create({ worktreeCreateInput: { name: worktreeName } }), getSpawnTimeout(), `worktree.create for "${args.name}"`);
       if (result.data) {
         worktreeDir = result.data.directory;
         worktreeBranch = result.data.branch;
       }
-    } catch {
+      log(`spawn:worktree:done name=${args.name} dir=${worktreeDir}`);
+    } catch (err) {
+      log(`spawn:worktree:failed name=${args.name} err=${err instanceof Error ? err.message : String(err)}`);
       try {
         await deps.client.tui.showToast({
           title: "Team",
@@ -15904,14 +15915,17 @@ async function executeTeamSpawn(deps, args, sessionId) {
   ] : undefined;
   let childSessionId;
   try {
-    const createResult = await deps.client.session.create({
+    log(`spawn:session:start name=${args.name}`);
+    const createResult = await withTimeout(deps.client.session.create({
       parentID: sessionId,
       title: `${args.name} (@${args.agent} teammate)`,
       ...permission ? { permission } : {},
       ...worktreeDir ? { directory: worktreeDir } : {}
-    });
+    }), getSpawnTimeout(), `session.create for "${args.name}"`);
     childSessionId = createResult.data?.id;
+    log(`spawn:session:done name=${args.name} sessionId=${childSessionId}`);
   } catch (err) {
+    log(`spawn:session:failed name=${args.name} err=${err instanceof Error ? err.message : String(err)}`);
     if (worktreeDir) {
       try {
         await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } });
@@ -15949,11 +15963,13 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const contextStr = context.join(`
 `);
+  log(`spawn:promptAsync:fire name=${args.name} sessionId=${childSessionId}`);
   deps.client.session.promptAsync({
     sessionID: childSessionId,
     parts: [{ type: "text", text: contextStr }],
     agent: args.agent
   }).catch(() => {
+    log(`spawn:promptAsync:failed name=${args.name} \u2014 rolling back`);
     try {
       deps.db.run("DELETE FROM team_member WHERE team_id = ? AND session_id = ?", [teamInfo.teamId, childSessionId]);
       deps.registry.unregister(childSessionId);
@@ -15973,14 +15989,11 @@ async function executeTeamSpawn(deps, args, sessionId) {
         to: "lead",
         content: `Teammate "${args.name}" failed to start and was removed. You may retry the spawn.`
       });
-      const team = deps.db.query("SELECT lead_session_id FROM team WHERE id = ?").get(teamInfo.teamId);
-      if (team) {
-        handleLeadIdleFlush(deps.db, deps.client, team.lead_session_id).catch(() => {});
-      }
     } catch {}
   });
   const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : "";
   const planInfo = usePlanApproval ? " [plan mode \u2014 will send plan for approval]" : "";
+  log(`spawn:done name=${args.name} sessionId=${childSessionId}`);
   return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}${planInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`;
 }
 
@@ -16020,31 +16033,25 @@ async function executeTeamMessage(deps, args, sessionId) {
     content: messageText
   });
   const isToLead = args.to === "lead";
-  const MAX_LEAD_MSG = 500;
-  let deliveryText;
-  if (isToLead && messageText.length > MAX_LEAD_MSG) {
-    const truncated = messageText.slice(0, MAX_LEAD_MSG);
-    deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`;
-  } else {
-    deliveryText = `[Team message from ${senderName}]: ${messageText}`;
-  }
-  let recipientBusy = false;
-  try {
-    const statusResult = await deps.client.session.status();
-    const sessionStatus = statusResult.data?.[recipientSessionId];
-    if (sessionStatus?.type === "busy") {
-      recipientBusy = true;
-    }
-  } catch {}
-  if (recipientBusy) {
-    return `Message sent to ${args.to}. (queued \u2014 recipient is busy)`;
+  if (isToLead) {
+    log(`team_message:wake-lead from=${senderName} recipientSession=${recipientSessionId}`);
+    deps.client.session.promptAsync({
+      sessionID: recipientSessionId,
+      parts: [{ type: "text", text: `[System: New team message from ${senderName}]` }]
+    }).catch((err) => {
+      log(`team_message:wake-lead:failed from=${senderName} err=${err instanceof Error ? err.message : String(err)}`);
+    });
+    return `Message sent to ${args.to}.`;
   }
+  const deliveryText = `[Team message from ${senderName}]: ${messageText}`;
   deps.client.session.promptAsync({
     sessionID: recipientSessionId,
     parts: [{ type: "text", text: deliveryText }]
   }).then(() => {
     markDelivered(deps.db, msgId);
-  }).catch(() => {});
+  }).catch((err) => {
+    log(`team_message:deliver:failed to=${args.to} err=${err instanceof Error ? err.message : String(err)}`);
+  });
   return `Message sent to ${args.to}.`;
 }
 
@@ -16080,7 +16087,9 @@ async function executeTeamBroadcast(deps, args, sessionId) {
       delivered++;
       if (delivered === 1)
         markDelivered(deps.db, msgId);
-    }).catch(() => {});
+    }).catch((err) => {
+      log(`team_broadcast:deliver:failed to=${recipient.name} err=${err instanceof Error ? err.message : String(err)}`);
+    });
   }
   return `Broadcast sent to ${recipients.length} recipient${recipients.length !== 1 ? "s" : ""}.`;
 }
@@ -16498,17 +16507,29 @@ var plugin = async (input) => {
   const tracker = new DescendantTracker;
   const pluginTransport = input.client._client;
   const rawClient = new OpencodeClient({ client: pluginTransport });
+  initLog(rawClient);
   const client3 = wrapThrowingClient(rawClient);
   const deps = { db, registry: registry2, tracker, client: client3, directory: input.directory };
-  const recovery = await recoverStaleMembers(db, client3);
-  if (recovery.interrupted > 0) {
-    const members = 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'").all();
-    for (const m of members) {
-      registry2.register(m.team_id, m.name, m.session_id);
-    }
+  if (!isWorktreeInstance(input.directory)) {
+    log("init:recovery:start (main instance)");
+    const recovery = await recoverStaleMembers(db, client3);
+    if (recovery.interrupted > 0) {
+      log(`init:recovery:interrupted=${recovery.interrupted}`);
+      const members = 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'").all();
+      for (const m of members) {
+        registry2.register(m.team_id, m.name, m.session_id);
+      }
+    }
+    recoverUndeliveredMessages(db, client3, registry2).catch((err) => {
+      log(`init:recover-messages:failed err=${err instanceof Error ? err.message : String(err)}`);
+    });
+    recoverOrphanedWorktrees(db, client3).catch((err) => {
+      log(`init:recover-worktrees:failed err=${err instanceof Error ? err.message : String(err)}`);
+    });
+    log("init:recovery:done");
+  } else {
+    log(`init:skip-recovery (worktree instance: ${input.directory})`);
   }
-  recoverUndeliveredMessages(db, client3, registry2).catch(() => {});
-  recoverOrphanedWorktrees(db, client3).catch(() => {});
   const rateLimitEnv = process.env.OPENCODE_ENSEMBLE_RATE_LIMIT;
   const rateLimitCapacity = rateLimitEnv === "0" ? 0 : parseInt(rateLimitEnv ?? "", 10) || DEFAULT_RATE_LIMIT_CAPACITY;
   const rateLimiter = new TokenBucket({
@@ -16559,7 +16580,19 @@ var plugin = async (input) => {
           await notifyWorkingProgress(client3, db, transition.teamId);
         }
         if (statusType === "idle") {
-          handleLeadIdleFlush(db, client3, sessionID).catch(() => {});
+          const team = db.query("SELECT id FROM team WHERE lead_session_id = ? AND status = 'active'").get(sessionID);
+          if (team) {
+            const pending = db.query("SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = 'lead' AND delivered = 0").get(team.id);
+            if (pending.c > 0) {
+              log(`wake-lead: ${pending.c} pending messages, sending promptAsync`);
+              client3.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${pending.c} new team message(s) available]` }]
+              }).catch((err) => {
+                log(`wake-lead:failed err=${err instanceof Error ? err.message : String(err)}`);
+              });
+            }
+          }
         }
       }
       if (event.type === "session.created") {
@@ -16583,7 +16616,9 @@ var plugin = async (input) => {
       const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
       if (!teamInfo)
         return;
+      log(`system-prompt:transform role=${teamInfo.role} session=${input2.sessionID}`);
       const prompt = teamInfo.role === "lead" ? buildLeadSystemPrompt(db, teamInfo.teamId) : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName ?? "unknown");
+      log(`system-prompt:injected role=${teamInfo.role} len=${prompt.length}`);
       output.system.push(prompt);
     },
     "experimental.session.compacting": async (input2, output) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "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/hooks.ts

@@ -1,7 +1,5 @@
 import type { Database } from "bun:sqlite"
 import type { MemberRegistry, DescendantTracker } from "./state"
-import type { PluginClient } from "./types"
-import { flushPendingMessages } from "./messaging"
 
 const TEAM_TOOL_PREFIX = "team_"
 
@@ -100,17 +98,3 @@ export function checkToolIsolation(
     throw new Error("Team tools are not available to sub-agents. Report findings to your parent teammate via your normal output.")
   }
 }
-
-/**
- * Check if a session going idle is a team lead with pending messages.
- * If so, flush them via promptAsync. Called from the event hook on idle transitions.
- */
-export async function handleLeadIdleFlush(
-  db: Database,
-  client: PluginClient,
-  sessionId: string,
-): Promise<number> {
-  const team = db.query("SELECT id FROM team WHERE lead_session_id = ? AND status = 'active'").get(sessionId) as { id: string } | null
-  if (!team) return 0
-  return flushPendingMessages(db, client, team.id, sessionId)
-}

package/src/index.ts

@@ -7,9 +7,11 @@ import { createDb, getDbPath } from "./db"
 import { wrapThrowingClient } from "./client"
 import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
-import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation, handleLeadIdleFlush } from "./hooks"
+import { isWorktreeInstance } from "./util"
+import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
 import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
 import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
+import { log, initLog } from "./log"
 import { findTeamBySession } from "./types"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
@@ -55,30 +57,36 @@ const plugin: Plugin = async (input) => {
   type V2Transport = ConstructorParameters<typeof OpencodeClient>[0] extends { client?: infer C } ? C : never
   const pluginTransport = (input.client as unknown as { _client: V2Transport })._client
   const rawClient = new OpencodeClient({ client: pluginTransport })
+  initLog(rawClient)
   const client = wrapThrowingClient(rawClient)
   const deps: ToolDeps = { db, registry, tracker, client, directory: input.directory }
 
-  // Run recovery on init — mark stale busy members as error + abort orphaned sessions
-  const recovery = await recoverStaleMembers(db, client)
-  if (recovery.interrupted > 0) {
-    // Rebuild registry from DB for recovered members
-    const members = 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'"
-    ).all() as Array<{ team_id: string; name: string; session_id: string }>
-    for (const m of members) {
-      registry.register(m.team_id, m.name, m.session_id)
+  // Recovery only runs for the main project instance — NOT for teammate worktree instances.
+  // Worktree instances are created during session.create. Running recovery there makes HTTP
+  // calls back to the server, which deadlocks because the server is still handling session.create.
+  if (!isWorktreeInstance(input.directory)) {
+    log("init:recovery:start (main instance)")
+    const recovery = await recoverStaleMembers(db, client)
+    if (recovery.interrupted > 0) {
+      log(`init:recovery:interrupted=${recovery.interrupted}`)
+      const members = 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'"
+      ).all() as Array<{ team_id: string; name: string; session_id: string }>
+      for (const m of members) {
+        registry.register(m.team_id, m.name, m.session_id)
+      }
     }
-  }
 
-  // Redeliver undelivered messages from previous sessions
-  recoverUndeliveredMessages(db, client, registry).catch(() => {
-    // Best effort — don't block plugin init
-  })
-
-  // Clean up orphaned worktrees from crashed teams
-  recoverOrphanedWorktrees(db, client).catch(() => {
-    // Best effort — don't block plugin init
-  })
+    recoverUndeliveredMessages(db, client, registry).catch((err) => {
+      log(`init:recover-messages:failed err=${err instanceof Error ? err.message : String(err)}`)
+    })
+    recoverOrphanedWorktrees(db, client).catch((err) => {
+      log(`init:recover-worktrees:failed err=${err instanceof Error ? err.message : String(err)}`)
+    })
+    log("init:recovery:done")
+  } else {
+    log(`init:skip-recovery (worktree instance: ${input.directory})`)
+  }
 
   // Initialize rate limiter
   // OPENCODE_ENSEMBLE_RATE_LIMIT=0 disables it entirely
@@ -141,9 +149,22 @@ const plugin: Plugin = async (input) => {
           await notifyWorkingProgress(client, db, transition.teamId)
         }
 
-        // Flush pending messages to the lead when their session goes idle
+        // Wake the lead when it goes idle and has pending messages.
+        // The system prompt transform delivers the actual message content.
         if (statusType === "idle") {
-          handleLeadIdleFlush(db, client, sessionID).catch(() => { /* best effort */ })
+          const team = db.query("SELECT id FROM team WHERE lead_session_id = ? AND status = 'active'").get(sessionID) as { id: string } | null
+          if (team) {
+            const pending = db.query("SELECT COUNT(*) as c FROM team_message WHERE team_id = ? AND to_name = 'lead' AND delivered = 0").get(team.id) as { c: number }
+            if (pending.c > 0) {
+              log(`wake-lead: ${pending.c} pending messages, sending promptAsync`)
+              client.session.promptAsync({
+                sessionID,
+                parts: [{ type: "text", text: `[System: ${pending.c} new team message(s) available]` }],
+              }).catch((err) => {
+                log(`wake-lead:failed err=${err instanceof Error ? err.message : String(err)}`)
+              })
+            }
+          }
         }
       }
 
@@ -171,9 +192,11 @@ const plugin: Plugin = async (input) => {
       if (!input.sessionID) return
       const teamInfo = findTeamBySession(db, registry, input.sessionID)
       if (!teamInfo) return
+      log(`system-prompt:transform role=${teamInfo.role} session=${input.sessionID}`)
       const prompt = teamInfo.role === "lead"
         ? buildLeadSystemPrompt(db, teamInfo.teamId)
         : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName ?? "unknown")
+      log(`system-prompt:injected role=${teamInfo.role} len=${prompt.length}`)
       output.system.push(prompt)
     },
 

package/src/log.ts

@@ -0,0 +1,13 @@
+/** Plugin logger using the v2 SDK's structured logging API (flat params, no body wrapper). */
+let _client: { app: { log: (params: { service: string; level: string; message: string }) => Promise<unknown> } } | null = null
+
+/** Set the SDK client for logging. Called once during plugin init with the raw v2 client. */
+export function initLog(client: unknown): void {
+  _client = client as typeof _client
+}
+
+/** Log a message via the SDK's app.log API so it appears in OpenCode's structured logs. */
+export function log(msg: string): void {
+  if (!_client) return
+  _client.app.log({ service: "ensemble", level: "info", message: msg }).catch(() => {})
+}

package/src/messaging.ts

@@ -1,5 +1,4 @@
 import type { Database } from "bun:sqlite"
-import type { PluginClient } from "./types"
 import { generateId } from "./util"
 
 const MAX_CONTENT_BYTES = 10 * 1024 // 10KB
@@ -77,40 +76,3 @@ export function getUndeliveredMessages(db: Database, teamId: string): MessageRow
 export function markDelivered(db: Database, messageId: string): void {
   db.run("UPDATE team_message SET delivered = 1 WHERE id = ?", [messageId])
 }
-
-/**
- * Flush undelivered messages addressed to the lead for a given team.
- * Batches all pending messages into a single promptAsync call to avoid
- * interrupting the lead with multiple deliveries. Returns count of delivered messages.
- */
-export async function flushPendingMessages(
-  db: Database,
-  client: PluginClient,
-  teamId: string,
-  leadSessionId: string,
-): Promise<number> {
-  const pending = db.query(
-    "SELECT * FROM team_message WHERE team_id = ? AND delivered = 0 AND to_name = 'lead' ORDER BY time_created ASC"
-  ).all(teamId) as MessageRow[]
-
-  if (pending.length === 0) return 0
-
-  const MAX_LEAD_MSG = 500
-  const parts = pending.map((msg) => {
-    if (msg.content.length > MAX_LEAD_MSG) {
-      return `[Team message from ${msg.from_name}]: ${msg.content.slice(0, MAX_LEAD_MSG)}... (use team_results to read full message)`
-    }
-    return `[Team message from ${msg.from_name}]: ${msg.content}`
-  })
-
-  try {
-    await client.session.promptAsync({
-      sessionID: leadSessionId,
-      parts: [{ type: "text", text: parts.join("\n") }],
-    })
-    for (const msg of pending) markDelivered(db, msg.id)
-    return pending.length
-  } catch {
-    return 0
-  }
-}

package/src/recovery.ts

@@ -98,7 +98,8 @@ export async function recoverUndeliveredMessages(
       let recipientSessionId: string | undefined
 
       if (msg.to_name === "lead") {
-        recipientSessionId = team.lead_session_id
+        // Skip lead-bound messages — the system prompt transform delivers them
+        continue
       } else if (msg.to_name) {
         const entry = registry.getByName(team.id, msg.to_name)
         recipientSessionId = entry?.sessionId

package/src/system-prompt.ts

@@ -1,4 +1,5 @@
 import type { Database } from "bun:sqlite"
+import { markDelivered } from "./messaging"
 
 /** Status display mapping from DB status to human-readable label. */
 const STATUS_DISPLAY: Record<string, string> = {
@@ -40,16 +41,43 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     ? `Teammates: ${memberList}`
     : "Teammates: none"
 
-  return [
+  const pendingMessages = db.query(
+    "SELECT id, from_name, content FROM team_message WHERE team_id = ? AND to_name = 'lead' AND delivered = 0 ORDER BY time_created ASC"
+  ).all(teamId) as Array<{ id: string; from_name: string; content: string }>
+
+  const lines = [
     `You are leading team "${team.name}" with ${members.length} active teammates.`,
     teammateLine,
     `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
+  ]
+
+  if (pendingMessages.length > 0) {
+    lines.push("", "--- Team Messages ---")
+    const MAX_MSG = 500
+    for (const msg of pendingMessages) {
+      if (msg.content.length > MAX_MSG) {
+        lines.push(`[From ${msg.from_name}]: ${msg.content.slice(0, MAX_MSG)}... (use team_results to read full message)`)
+      } else {
+        lines.push(`[From ${msg.from_name}]: ${msg.content}`)
+      }
+      markDelivered(db, msg.id)
+    }
+    lines.push("--- End Messages ---")
+  }
+
+  lines.push(
+    "",
+    "CRITICAL: Spawn teammates ONE AT A TIME. Send only ONE team_spawn call per response.",
+    "Wait for the tool result before spawning the next teammate.",
+    "Multiple team_spawn calls in a single response will cause timeouts.",
     "",
     "Teammates work asynchronously and message you when done.",
     "Do NOT poll team_status or team_tasks_list repeatedly — wait for messages.",
-    "After spawning teammates, tell the user what you've set up and wait.",
+    "After spawning all teammates, tell the user what you've set up and wait.",
     "When all teammates finish, summarize results and suggest next steps.",
-  ].join("\n")
+  )
+
+  return lines.join("\n")
 }
 
 /**

package/src/tools/team-broadcast.ts

@@ -1,6 +1,7 @@
 import type { ToolDeps } from "../types"
 import { findTeamBySession } from "../types"
 import { broadcastMessage, markDelivered } from "../messaging"
+import { log } from "../log"
 
 /**
  * Execute the team_broadcast tool. Sends a message to all team members + lead (excluding sender).
@@ -48,7 +49,9 @@ export async function executeTeamBroadcast(
     }).then(() => {
       delivered++
       if (delivered === 1) markDelivered(deps.db, msgId)
-    }).catch(() => { /* partial failure is expected */ })
+    }).catch((err) => {
+      log(`team_broadcast:deliver:failed to=${recipient.name} err=${err instanceof Error ? err.message : String(err)}`)
+    })
   }
 
   return `Broadcast sent to ${recipients.length} recipient${recipients.length !== 1 ? "s" : ""}.`

package/src/tools/team-message.ts

@@ -1,6 +1,7 @@
 import type { ToolDeps } from "../types"
 import { findTeamBySession, resolveRecipientSession } from "../types"
 import { sendMessage, markDelivered } from "../messaging"
+import { log } from "../log"
 
 /**
  * Execute the team_message tool. Sends a direct message to a teammate or lead.
@@ -56,43 +57,33 @@ export async function executeTeamMessage(
     content: messageText,
   })
 
-  // Deliver via promptAsync — truncate lead-bound messages over 500 chars
   const isToLead = args.to === "lead"
-  const MAX_LEAD_MSG = 500
-  let deliveryText: string
-  if (isToLead && messageText.length > MAX_LEAD_MSG) {
-    const truncated = messageText.slice(0, MAX_LEAD_MSG)
-    deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`
-  } else {
-    deliveryText = `[Team message from ${senderName}]: ${messageText}`
-  }
-
-  // Check if recipient is busy — if so, queue the message for later delivery.
-  // TOCTOU: status check and promptAsync are not atomic. A recipient can transition
-  // idle→busy between the check and delivery. This is accepted as benign — the idle-flush
-  // backstop catches anything that slips through, so no messages are lost.
-  let recipientBusy = false
-  try {
-    const statusResult = await deps.client.session.status()
-    const sessionStatus = statusResult.data?.[recipientSessionId]
-    if (sessionStatus?.type === "busy") {
-      recipientBusy = true
-    }
-  } catch { /* status check failed — deliver anyway as best effort */ }
 
-  if (recipientBusy) {
-    // Message is stored in DB with delivered=0, will be flushed when recipient goes idle
-    return `Message sent to ${args.to}. (queued — recipient is busy)`
+  // Lead-bound messages: store in DB, then wake the lead with a minimal promptAsync.
+  // The system prompt transform delivers the actual message content on the lead's next turn.
+  // This runs in the teammate's worktree instance — the event hook can't wake the lead
+  // because session.idle events are scoped per-instance.
+  if (isToLead) {
+    log(`team_message:wake-lead from=${senderName} recipientSession=${recipientSessionId}`)
+    deps.client.session.promptAsync({
+      sessionID: recipientSessionId,
+      parts: [{ type: "text", text: `[System: New team message from ${senderName}]` }],
+    }).catch((err) => {
+      log(`team_message:wake-lead:failed from=${senderName} err=${err instanceof Error ? err.message : String(err)}`)
+    })
+    return `Message sent to ${args.to}.`
   }
 
-  // Fire-and-forget: message is already persisted in DB. If delivery fails,
-  // the idle-flush backstop will redeliver it.
+  // For member-to-member messages, fire-and-forget delivery is safe.
+  const deliveryText = `[Team message from ${senderName}]: ${messageText}`
   deps.client.session.promptAsync({
     sessionID: recipientSessionId,
     parts: [{ type: "text", text: deliveryText }],
   }).then(() => {
     markDelivered(deps.db, msgId)
-  }).catch(() => { /* message stays delivered=0, idle-flush will retry */ })
+  }).catch((err) => {
+    log(`team_message:deliver:failed to=${args.to} err=${err instanceof Error ? err.message : String(err)}`)
+  })
 
   return `Message sent to ${args.to}.`
 }

package/src/tools/team-spawn.ts

@@ -2,7 +2,23 @@ import type { ToolDeps, PermissionRule } from "../types"
 import { validateMemberName } from "../util"
 import { findTeamBySession } from "../types"
 import { sendMessage } from "../messaging"
-import { handleLeadIdleFlush } from "../hooks"
+import { log } from "../log"
+
+/** Timeout for worktree.create and session.create to prevent hanging on git lock contention. */
+function getSpawnTimeout(): number {
+  return Number(process.env.SPAWN_TIMEOUT_MS) || 120_000
+}
+
+/** Race a promise against a timeout. Throws if the timeout fires first. Cleans up timer on resolution. */
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>
+  return Promise.race([
+    promise.finally(() => clearTimeout(timer)),
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
+    }),
+  ])
+}
 
 /**
  * Execute the team_spawn tool. Creates a child session and starts a teammate.
@@ -30,6 +46,8 @@ export async function executeTeamSpawn(
   const useWorktree = args.worktree !== false
   const usePlanApproval = args.plan_approval === true
 
+  log(`spawn:start name=${args.name} agent=${args.agent} worktree=${useWorktree}`)
+
   // Create worktree if enabled
   let worktreeDir: string | null = null
   let worktreeBranch: string | null = null
@@ -37,13 +55,18 @@ export async function executeTeamSpawn(
   if (useWorktree) {
     const worktreeName = `ensemble-${teamInfo.teamName}-${args.name}`
     try {
-      const result = await deps.client.worktree.create({ worktreeCreateInput: { name: worktreeName } })
+      log(`spawn:worktree:start name=${args.name}`)
+      const result = await withTimeout(
+        deps.client.worktree.create({ worktreeCreateInput: { name: worktreeName } }),
+        getSpawnTimeout(), `worktree.create for "${args.name}"`
+      )
       if (result.data) {
         worktreeDir = result.data.directory
         worktreeBranch = result.data.branch
       }
-    } catch {
-      // Worktree creation failed — fall back to shared directory with a warning
+      log(`spawn:worktree:done name=${args.name} dir=${worktreeDir}`)
+    } catch (err) {
+      log(`spawn:worktree:failed name=${args.name} err=${err instanceof Error ? err.message : String(err)}`)
       try {
         await deps.client.tui.showToast({
           title: "Team",
@@ -71,14 +94,20 @@ export async function executeTeamSpawn(
   // Create child session — use worktree directory if available
   let childSessionId: string | undefined
   try {
-    const createResult = await deps.client.session.create({
-      parentID: sessionId,
-      title: `${args.name} (@${args.agent} teammate)`,
-      ...(permission ? { permission } : {}),
-      ...(worktreeDir ? { directory: worktreeDir } : {}),
-    })
+    log(`spawn:session:start name=${args.name}`)
+    const createResult = await withTimeout(
+      deps.client.session.create({
+        parentID: sessionId,
+        title: `${args.name} (@${args.agent} teammate)`,
+        ...(permission ? { permission } : {}),
+        ...(worktreeDir ? { directory: worktreeDir } : {}),
+      }),
+      getSpawnTimeout(), `session.create for "${args.name}"`
+    )
     childSessionId = createResult.data?.id
+    log(`spawn:session:done name=${args.name} sessionId=${childSessionId}`)
   } catch (err) {
+    log(`spawn:session:failed name=${args.name} err=${err instanceof Error ? err.message : String(err)}`)
     // Rollback worktree if session creation failed
     if (worktreeDir) {
       try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
@@ -159,15 +188,13 @@ export async function executeTeamSpawn(
   const contextStr = context.join("\n")
 
   // Fire-and-forget: send prompt to teammate session.
-  // Do NOT await — promptAsync is HTTP 204 (returns immediately on the server)
-  // but awaiting it can block if the transport is slow or broken (e.g. proxy).
-  // The child session is already created and registered. If delivery fails,
-  // the async .catch() rolls back the member and the watchdog handles stale members.
+  log(`spawn:promptAsync:fire name=${args.name} sessionId=${childSessionId}`)
   deps.client.session.promptAsync({
     sessionID: childSessionId,
     parts: [{ type: "text", text: contextStr }],
     agent: args.agent,
   }).catch(() => {
+    log(`spawn:promptAsync:failed name=${args.name} — rolling back`)
     try {
       // Async rollback: clean up DB (by session_id to avoid deleting a re-spawned member with the same name), registry, session, and worktree
       deps.db.run("DELETE FROM team_member WHERE team_id = ? AND session_id = ?", [teamInfo.teamId, childSessionId])
@@ -184,21 +211,18 @@ export async function executeTeamSpawn(
         duration: 5000,
       }).catch(() => { /* TUI may not be available */ })
       // Notify the lead model so it can react (retry, adjust plan, etc.)
+      // Message delivered via system prompt transform on the lead's next turn.
       sendMessage(deps.db, {
         teamId: teamInfo.teamId,
         from: "system",
         to: "lead",
         content: `Teammate "${args.name}" failed to start and was removed. You may retry the spawn.`,
       })
-      const team = deps.db.query("SELECT lead_session_id FROM team WHERE id = ?")
-        .get(teamInfo.teamId) as { lead_session_id: string } | null
-      if (team) {
-        handleLeadIdleFlush(deps.db, deps.client, team.lead_session_id).catch(() => {})
-      }
     } catch { /* rollback failed — watchdog will clean up stale member */ }
   })
 
   const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
   const planInfo = usePlanApproval ? " [plan mode — will send plan for approval]" : ""
+  log(`spawn:done name=${args.name} sessionId=${childSessionId}`)
   return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}${planInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
 }

package/src/util.ts

@@ -23,6 +23,14 @@ export function validateTeamName(name: string): string | undefined {
   return undefined
 }
 
+/**
+ * Detect if the plugin is loading inside a teammate's worktree instance.
+ * Worktree instances should skip recovery to avoid deadlocking the server.
+ */
+export function isWorktreeInstance(directory: string): boolean {
+  return directory.includes("/worktree/") && directory.includes("/ensemble-")
+}
+
 /**
  * Validate a member name. Same rules as team name, plus "lead" is reserved.
  * Returns an error message string if invalid, undefined if valid.