@hueyexe/opencode-ensemble 0.6.2 → 0.6.4

package/dist/index.js

@@ -15371,7 +15371,9 @@ var MIGRATIONS = [
 function applyMigrations(db) {
   const { user_version: current } = db.query("PRAGMA user_version").get();
   for (let i = current;i < MIGRATIONS.length; i++) {
-    db.exec(MIGRATIONS[i]);
+    const migration = MIGRATIONS[i];
+    if (migration)
+      db.exec(migration);
     db.exec(`PRAGMA user_version = ${i + 1}`);
   }
 }
@@ -15444,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`;
@@ -15478,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) {
@@ -15550,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;
@@ -15611,6 +15592,9 @@ class MemberRegistry {
   isTeamSession(sessionId) {
     return this.bySession.has(sessionId);
   }
+  allSessionIds() {
+    return new Set(this.bySession.keys());
+  }
 }
 var DEFAULT_MAX_DEPTH = 10;
 
@@ -15680,20 +15664,11 @@ function checkToolIsolation(registry2, tracker, toolName, sessionId) {
     return;
   if (registry2.isTeamSession(sessionId))
     return;
-  const allTeamSessions = new Set;
-  for (const entry of registry2["bySession"].keys()) {
-    allTeamSessions.add(entry);
-  }
+  const allTeamSessions = registry2.allSessionIds();
   if (allTeamSessions.size > 0 && tracker.isDescendantOf(sessionId, allTeamSessions)) {
     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 = {
@@ -15771,21 +15746,32 @@ function buildLeadSystemPrompt(db, teamId) {
   for (const row of taskCounts) {
     countMap[row.status] = row.count;
   }
-  const completed = countMap["completed"] ?? 0;
-  const inProgress = countMap["in_progress"] ?? 0;
-  const pending = countMap["pending"] ?? 0;
+  const completed = countMap.completed ?? 0;
+  const inProgress = countMap.in_progress ?? 0;
+  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) {
@@ -15804,9 +15790,9 @@ function buildTeamCompactionContext(db, teamId, role, memberName) {
   for (const row of taskCounts) {
     countMap[row.status] = row.count;
   }
-  const completed = countMap["completed"] ?? 0;
-  const inProgress = countMap["in_progress"] ?? 0;
-  const pending = countMap["pending"] ?? 0;
+  const completed = countMap.completed ?? 0;
+  const inProgress = countMap.in_progress ?? 0;
+  const pending = countMap.pending ?? 0;
   const roleLine = role === "lead" ? `[Team Context] You are the lead of team "${team.name}".` : `[Team Context] You are a teammate named "${memberName}" in team "${team.name}".`;
   const memberList = members.map((m) => `${m.name} (${STATUS_DISPLAY[m.status] ?? m.status})`).join(", ");
   const membersLine = members.length > 0 ? `Members: ${memberList}` : "Members: none";
@@ -15818,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);
@@ -15858,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)
@@ -15872,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",
@@ -15902,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 } });
@@ -15947,27 +15963,37 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const contextStr = context.join(`
 `);
-  try {
-    await deps.client.session.promptAsync({
-      sessionID: childSessionId,
-      parts: [{ type: "text", text: contextStr }],
-      agent: args.agent
-    });
-  } catch (err) {
-    deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name]);
-    deps.registry.unregister(childSessionId);
+  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 {
-      await deps.client.session.abort({ sessionID: childSessionId });
+      deps.db.run("DELETE FROM team_member WHERE team_id = ? AND session_id = ?", [teamInfo.teamId, childSessionId]);
+      deps.registry.unregister(childSessionId);
+      deps.client.session.abort({ sessionID: childSessionId }).catch(() => {});
+      if (worktreeDir) {
+        deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }).catch(() => {});
+      }
+      deps.client.tui.showToast({
+        title: "Team",
+        message: `Teammate "${args.name}" failed to start and was removed`,
+        variant: "error",
+        duration: 5000
+      }).catch(() => {});
+      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.`
+      });
     } catch {}
-    if (worktreeDir) {
-      try {
-        await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } });
-      } catch {}
-    }
-    throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`);
-  }
+  });
   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 ? "..." : ""}`;
 }
 
@@ -15976,7 +16002,7 @@ async function executeTeamMessage(deps, args, sessionId) {
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
   if (!teamInfo)
     throw new Error("This session is not in a team. Use team_create first.");
-  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName;
+  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to);
   if (!recipientSessionId)
     throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`);
@@ -16007,30 +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}.`;
   }
-  await deps.client.session.promptAsync({
+  const deliveryText = `[Team message from ${senderName}]: ${messageText}`;
+  deps.client.session.promptAsync({
     sessionID: recipientSessionId,
     parts: [{ type: "text", text: deliveryText }]
+  }).then(() => {
+    markDelivered(deps.db, msgId);
+  }).catch((err) => {
+    log(`team_message:deliver:failed to=${args.to} err=${err instanceof Error ? err.message : String(err)}`);
   });
-  markDelivered(deps.db, msgId);
   return `Message sent to ${args.to}.`;
 }
 
@@ -16039,7 +16060,7 @@ async function executeTeamBroadcast(deps, args, sessionId) {
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
   if (!teamInfo)
     throw new Error("This session is not in a team. Use team_create first.");
-  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName;
+  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const msgId = broadcastMessage(deps.db, {
     teamId: teamInfo.teamId,
     from: senderName,
@@ -16059,18 +16080,18 @@ async function executeTeamBroadcast(deps, args, sessionId) {
   }
   let delivered = 0;
   for (const recipient of recipients) {
-    try {
-      await deps.client.session.promptAsync({
-        sessionID: recipient.sessionId,
-        parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }]
-      });
+    deps.client.session.promptAsync({
+      sessionID: recipient.sessionId,
+      parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }]
+    }).then(() => {
       delivered++;
-    } catch {}
-  }
-  if (delivered > 0) {
-    markDelivered(deps.db, msgId);
+      if (delivered === 1)
+        markDelivered(deps.db, msgId);
+    }).catch((err) => {
+      log(`team_broadcast:deliver:failed to=${recipient.name} err=${err instanceof Error ? err.message : String(err)}`);
+    });
   }
-  return `Broadcast sent to ${delivered} recipient${delivered !== 1 ? "s" : ""}.`;
+  return `Broadcast sent to ${recipients.length} recipient${recipients.length !== 1 ? "s" : ""}.`;
 }
 
 // src/tools/team-shutdown.ts
@@ -16240,7 +16261,7 @@ async function executeTeamClaim(deps, args, sessionId) {
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
   if (!teamInfo)
     throw new Error("This session is not in a team.");
-  const claimerName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName;
+  const claimerName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName ?? "unknown";
   const task = deps.db.query("SELECT * FROM team_task WHERE id = ? AND team_id = ?").get(args.task_id, teamInfo.teamId);
   if (!task)
     throw new Error(`Task "${args.task_id}" not found`);
@@ -16484,18 +16505,31 @@ var plugin = async (input) => {
   const db = createDb(dbPath);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
-  const rawClient = new OpencodeClient({ client: input.client._client });
+  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({
@@ -16546,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") {
@@ -16570,7 +16616,9 @@ var plugin = async (input) => {
       const teamInfo = findTeamBySession(db, registry2, input2.sessionID);
       if (!teamInfo)
         return;
-      const prompt = teamInfo.role === "lead" ? buildLeadSystemPrompt(db, teamInfo.teamId) : buildTeammateSystemPrompt(db, teamInfo.teamId, teamInfo.memberName);
+      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.2",
+  "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",
@@ -26,12 +26,14 @@
     "README.md"
   ],
   "scripts": {
+    "lint": "bunx biome lint src/",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "build": "bun build src/index.ts --outdir dist --target bun",
     "prepublishOnly": "bun run typecheck && bun test && bun run build"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
     "@types/bun": "latest"
   },
   "peerDependencies": {

package/src/client.ts

@@ -6,11 +6,11 @@ function extractError(err: unknown): string {
   return String(err)
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyFn = (...args: any[]) => Promise<any>
+/** Generic async SDK method type. Actual type safety enforced by PluginClient interface. */
+type SdkMethod = (...args: unknown[]) => Promise<unknown>
 
 /** Wrap a single async SDK method to throw on { error } responses. */
-function throwing(fn: AnyFn): AnyFn {
+function throwing(fn: SdkMethod): SdkMethod {
   return async (...args: unknown[]) => {
     const result = await fn(...args)
     if (result && typeof result === "object" && "error" in result && result.error !== undefined) {
@@ -22,9 +22,9 @@ function throwing(fn: AnyFn): AnyFn {
 
 /** Shape of the raw v2 SDK client — just the methods we wrap. */
 interface RawClient {
-  session: { create: AnyFn; promptAsync: AnyFn; abort: AnyFn; status: AnyFn }
-  tui: { showToast: AnyFn; selectSession: AnyFn }
-  worktree: { create: AnyFn; remove: AnyFn; list: AnyFn; reset: AnyFn }
+  session: { create: SdkMethod; promptAsync: SdkMethod; abort: SdkMethod; status: SdkMethod }
+  tui: { showToast: SdkMethod; selectSession: SdkMethod }
+  worktree: { create: SdkMethod; remove: SdkMethod; list: SdkMethod; reset: SdkMethod }
 }
 
 /**

package/src/db.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite"
-import path from "path"
+import path from "node:path"
 import { applyMigrations } from "./schema"
 
 let instance: Database | undefined

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_"
 
@@ -94,26 +92,9 @@ export function checkToolIsolation(
   if (registry.isTeamSession(sessionId)) return
 
   // Check if this session is a descendant of any team member
-  const allTeamSessions = new Set<string>()
-  for (const entry of registry["bySession"].keys()) {
-    allTeamSessions.add(entry)
-  }
+  const allTeamSessions = registry.allSessionIds()
 
   if (allTeamSessions.size > 0 && tracker.isDescendantOf(sessionId, allTeamSessions)) {
     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

@@ -1,15 +1,17 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
-import { OpencodeClient as OpencodeClientV2 } from "@opencode-ai/sdk/v2"
-import path from "path"
+import { OpencodeClient } from "@opencode-ai/sdk/v2"
+import path from "node:path"
 import { mkdirSync } from "node:fs"
 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"
@@ -24,7 +26,7 @@ import { executeTeamClaim } from "./tools/team-claim"
 import { executeTeamResults } from "./tools/team-results"
 import { executeTeamStatus } from "./tools/team-status"
 import { executeTeamView } from "./tools/team-view"
-import type { ToolDeps, PluginClient } from "./types"
+import type { ToolDeps, } from "./types"
 import { TokenBucket } from "./rate-limit"
 import { Watchdog } from "./watchdog"
 
@@ -49,35 +51,42 @@ const plugin: Plugin = async (input) => {
   const registry = new MemberRegistry()
   const tracker = new DescendantTracker()
 
-  // Reuse the v1 client's working HTTP transport with v2's method signatures.
-  // The v1 client (input.client) has the correct connection (Unix socket/auth),
-  // while v2 gives us flat params + permission on create + agent/tools on promptAsync.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const rawClient = new OpencodeClientV2({ client: (input.client as any)._client })
+  // Extract the working HeyAPI transport from the plugin-provided v1 client and pass it
+  // to the v2 OpencodeClient. The plugin framework provides a v1 client which stores its
+  // HeyAPI transport as `_client` (underscore). The v2 constructor accepts it as `client`.
+  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
@@ -140,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)}`)
+              })
+            }
+          }
         }
       }
 
@@ -170,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!)
+        : 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/notify.ts

@@ -3,17 +3,6 @@ import type { PluginClient } from "./types"
 
 type TeamEventType = "spawn" | "message" | "completed" | "error" | "shutdown"
 
-interface SpawnEvent { memberName: string; agent: string }
-interface MessageEvent { from: string; to: string }
-interface MemberEvent { memberName: string }
-
-type TeamEventData =
-  | { type: "spawn"; data: SpawnEvent }
-  | { type: "message"; data: MessageEvent }
-  | { type: "completed"; data: MemberEvent }
-  | { type: "error"; data: MemberEvent }
-  | { type: "shutdown"; data: MemberEvent }
-
 const TOAST_CONFIG: Record<TeamEventType, { variant: "info" | "success" | "warning" | "error"; duration: number }> = {
   spawn: { variant: "success", duration: 3000 },
   message: { variant: "info", duration: 3000 },

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/schema.ts

@@ -88,7 +88,8 @@ export function applyMigrations(db: Database): void {
   const { user_version: current } = db.query("PRAGMA user_version").get() as { user_version: number }
 
   for (let i = current; i < MIGRATIONS.length; i++) {
-    db.exec(MIGRATIONS[i]!)
+    const migration = MIGRATIONS[i]
+    if (migration) db.exec(migration)
     db.exec(`PRAGMA user_version = ${i + 1}`)
   }
 }

package/src/state.ts

@@ -59,6 +59,11 @@ export class MemberRegistry {
   isTeamSession(sessionId: string): boolean {
     return this.bySession.has(sessionId)
   }
+
+  /** Get all registered session IDs. */
+  allSessionIds(): Set<string> {
+    return new Set(this.bySession.keys())
+  }
 }
 
 const DEFAULT_MAX_DEPTH = 10

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> = {
@@ -28,9 +29,9 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     countMap[row.status] = row.count
   }
 
-  const completed = countMap["completed"] ?? 0
-  const inProgress = countMap["in_progress"] ?? 0
-  const pending = countMap["pending"] ?? 0
+  const completed = countMap.completed ?? 0
+  const inProgress = countMap.in_progress ?? 0
+  const pending = countMap.pending ?? 0
 
   const memberList = members
     .map((m) => `${m.name} [${STATUS_DISPLAY[m.status] ?? m.status}]`)
@@ -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")
 }
 
 /**
@@ -87,9 +115,9 @@ export function buildTeamCompactionContext(
     countMap[row.status] = row.count
   }
 
-  const completed = countMap["completed"] ?? 0
-  const inProgress = countMap["in_progress"] ?? 0
-  const pending = countMap["pending"] ?? 0
+  const completed = countMap.completed ?? 0
+  const inProgress = countMap.in_progress ?? 0
+  const pending = countMap.pending ?? 0
 
   const roleLine = role === "lead"
     ? `[Team Context] You are the lead of team "${team.name}".`

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).
@@ -13,7 +14,7 @@ export async function executeTeamBroadcast(
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
   if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
 
-  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName!
+  const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
   const msgId = broadcastMessage(deps.db, {
     teamId: teamInfo.teamId,
@@ -39,24 +40,19 @@ export async function executeTeamBroadcast(
     }
   }
 
-  // Deliver to all recipients — partial failures logged but don't fail the broadcast
+  // Fire-and-forget: deliver to all recipients. Message is already persisted in DB.
   let delivered = 0
   for (const recipient of recipients) {
-    try {
-      await deps.client.session.promptAsync({
-        sessionID: recipient.sessionId,
-        parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }],
-      })
+    deps.client.session.promptAsync({
+      sessionID: recipient.sessionId,
+      parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }],
+    }).then(() => {
       delivered++
-    } catch {
-      // Log but don't fail
-    }
-  }
-
-  // Only mark delivered if at least one recipient received it
-  if (delivered > 0) {
-    markDelivered(deps.db, msgId)
+      if (delivered === 1) markDelivered(deps.db, msgId)
+    }).catch((err) => {
+      log(`team_broadcast:deliver:failed to=${recipient.name} err=${err instanceof Error ? err.message : String(err)}`)
+    })
   }
 
-  return `Broadcast sent to ${delivered} recipient${delivered !== 1 ? "s" : ""}.`
+  return `Broadcast sent to ${recipients.length} recipient${recipients.length !== 1 ? "s" : ""}.`
 }

package/src/tools/team-claim.ts

@@ -13,7 +13,7 @@ export async function executeTeamClaim(
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
   if (!teamInfo) throw new Error("This session is not in a team.")
 
-  const claimerName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName!
+  const claimerName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
   const task = deps.db.query("SELECT * FROM team_task WHERE id = ? AND team_id = ?")
     .get(args.task_id, teamInfo.teamId) as Record<string, unknown> | null

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.
@@ -14,7 +15,7 @@ export async function executeTeamMessage(
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
   if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
 
-  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName!
+  const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
   if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
@@ -56,41 +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}.`
   }
 
-  await deps.client.session.promptAsync({
+  // 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((err) => {
+    log(`team_message:deliver:failed to=${args.to} err=${err instanceof Error ? err.message : String(err)}`)
   })
 
-  markDelivered(deps.db, msgId)
-
   return `Message sent to ${args.to}.`
 }

package/src/tools/team-spawn.ts

@@ -1,6 +1,24 @@
 import type { ToolDeps, PermissionRule } from "../types"
-import { generateId, validateMemberName } from "../util"
+import { validateMemberName } from "../util"
 import { findTeamBySession } from "../types"
+import { sendMessage } from "../messaging"
+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.
@@ -28,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
@@ -35,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",
@@ -69,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 */ }
@@ -156,25 +187,42 @@ export async function executeTeamSpawn(
 
   const contextStr = context.join("\n")
 
-  // Fire-and-forget: send prompt to teammate session
-  try {
-    await deps.client.session.promptAsync({
-      sessionID: childSessionId,
-      parts: [{ type: "text", text: contextStr }],
-      agent: args.agent,
-    })
-  } catch (err) {
-    // Rollback: clean up DB, registry, session, and worktree
-    deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name])
-    deps.registry.unregister(childSessionId)
-    try { await deps.client.session.abort({ sessionID: childSessionId }) } catch { /* best effort */ }
-    if (worktreeDir) {
-      try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
-    }
-    throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`)
-  }
+  // Fire-and-forget: send prompt to teammate session.
+  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])
+      deps.registry.unregister(childSessionId)
+      deps.client.session.abort({ sessionID: childSessionId }).catch(() => { /* best effort */ })
+      if (worktreeDir) {
+        deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }).catch(() => { /* best effort */ })
+      }
+      // Notify user that spawn failed so the lead doesn't think the teammate is active
+      deps.client.tui.showToast({
+        title: "Team",
+        message: `Teammate "${args.name}" failed to start and was removed`,
+        variant: "error",
+        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.`,
+      })
+    } 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.