@hueyexe/opencode-ensemble 0.7.1 → 0.9.0

package/src/config.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+
+/** Plugin configuration shape. All fields optional — defaults applied. */
+export interface EnsembleConfig {
+  /** Auto-merge worktree branches on cleanup (default: true) */
+  mergeOnCleanup?: boolean
+  /** Stall detection threshold in ms (default: 180000 = 3 min, 0 to disable) */
+  stallThresholdMs?: number
+  /** Min steps before token-based stall check (default: 3) */
+  stallMinSteps?: number
+  /** Output token threshold for stall detection (default: 500) */
+  stallTokenThreshold?: number
+  /** Hard timeout for busy members in ms (default: 1800000 = 30 min, 0 to disable) */
+  timeoutMs?: number
+  /** Rate limit capacity (default: 10, 0 to disable) */
+  rateLimitCapacity?: number
+}
+
+/** Default configuration values. */
+export const DEFAULT_CONFIG: Required<EnsembleConfig> = {
+  mergeOnCleanup: true,
+  stallThresholdMs: 180_000,
+  stallMinSteps: 3,
+  stallTokenThreshold: 500,
+  timeoutMs: 30 * 60 * 1000,
+  rateLimitCapacity: 10,
+}
+
+/** Read a JSON config file, returning an empty object on missing/invalid. */
+function readConfigFile(filePath: string): Partial<EnsembleConfig> {
+  try {
+    const text = readFileSync(filePath, "utf-8")
+    const raw = JSON.parse(text) as Record<string, unknown>
+    // Validate types — only accept numbers for numeric fields, booleans for boolean fields
+    const result: Partial<EnsembleConfig> = {}
+    if (typeof raw.mergeOnCleanup === "boolean") result.mergeOnCleanup = raw.mergeOnCleanup
+    if (typeof raw.stallThresholdMs === "number") result.stallThresholdMs = raw.stallThresholdMs
+    if (typeof raw.stallMinSteps === "number") result.stallMinSteps = raw.stallMinSteps
+    if (typeof raw.stallTokenThreshold === "number") result.stallTokenThreshold = raw.stallTokenThreshold
+    if (typeof raw.timeoutMs === "number") result.timeoutMs = raw.timeoutMs
+    if (typeof raw.rateLimitCapacity === "number") result.rateLimitCapacity = raw.rateLimitCapacity
+    return result
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return {}
+    console.warn(`[ensemble] Invalid config at ${filePath}, using defaults`)
+    return {}
+  }
+}
+
+/**
+ * Load plugin configuration. Merges global → project → env vars.
+ * Missing files are silently skipped. Invalid JSON logs a warning.
+ */
+export function loadConfig(projectDir: string): Required<EnsembleConfig> {
+  const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? ""
+  const globalPath = path.join(homeDir, ".config", "opencode", "ensemble.json")
+  const projectPath = path.join(projectDir, ".opencode", "ensemble.json")
+
+  const global = readConfigFile(globalPath)
+  const project = readConfigFile(projectPath)
+  const merged = { ...DEFAULT_CONFIG, ...global, ...project }
+
+  // Env vars override everything
+  const timeout = process.env.OPENCODE_ENSEMBLE_TIMEOUT
+  if (timeout !== undefined) merged.timeoutMs = timeout === "0" ? 0 : (parseInt(timeout, 10) || merged.timeoutMs)
+
+  const rateLimit = process.env.OPENCODE_ENSEMBLE_RATE_LIMIT
+  if (rateLimit !== undefined) merged.rateLimitCapacity = rateLimit === "0" ? 0 : (parseInt(rateLimit, 10) || merged.rateLimitCapacity)
+
+  const stall = process.env.STALL_THRESHOLD_MS
+  if (stall !== undefined) merged.stallThresholdMs = stall === "0" ? 0 : (parseInt(stall, 10) || merged.stallThresholdMs)
+
+  return merged
+}

package/src/index.ts

@@ -13,6 +13,8 @@ import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
 import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
 import { log, initLog } from "./log"
 import { findTeamBySession } from "./types"
+import { loadConfig } from "./config"
+import { ProgressTracker } from "./progress"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
 import { executeTeamMessage } from "./tools/team-message"
@@ -30,10 +32,8 @@ import type { ToolDeps, } from "./types"
 import { TokenBucket } from "./rate-limit"
 import { Watchdog } from "./watchdog"
 
-const DEFAULT_RATE_LIMIT_CAPACITY = 10
 const DEFAULT_RATE_LIMIT_REFILL = 2
 const DEFAULT_RATE_LIMIT_INTERVAL_MS = 1000
-const DEFAULT_WATCHDOG_TTL_MS = 30 * 60 * 1000 // 30 minutes
 const DEFAULT_WATCHDOG_CHECK_MS = 60 * 1000 // 60 seconds
 
 /**
@@ -47,10 +47,14 @@ const plugin: Plugin = async (input) => {
   mkdirSync(path.dirname(dbPath), { recursive: true })
   const db = createDb(dbPath)
 
+  // Load plugin configuration (global → project → env vars)
+  const config = loadConfig(input.directory)
+
   // Initialize in-memory state
   const registry = new MemberRegistry()
   const tracker = new DescendantTracker()
   const nudgedMembers = new Set<string>()
+  const progressTracker = new ProgressTracker()
 
   // 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
@@ -89,24 +93,22 @@ const plugin: Plugin = async (input) => {
     log(`init:skip-recovery (worktree instance: ${input.directory})`)
   }
 
-  // Initialize rate limiter
-  // OPENCODE_ENSEMBLE_RATE_LIMIT=0 disables it entirely
-  const rateLimitEnv = process.env.OPENCODE_ENSEMBLE_RATE_LIMIT
-  const rateLimitCapacity = rateLimitEnv === "0" ? 0 : (parseInt(rateLimitEnv ?? "", 10) || DEFAULT_RATE_LIMIT_CAPACITY)
+  // Initialize rate limiter — config value already accounts for env var override
   const rateLimiter = new TokenBucket({
-    capacity: rateLimitCapacity,
+    capacity: config.rateLimitCapacity,
     refillRate: DEFAULT_RATE_LIMIT_REFILL,
     refillIntervalMs: DEFAULT_RATE_LIMIT_INTERVAL_MS,
   })
 
-  // Initialize watchdog for teammate timeouts
-  // OPENCODE_ENSEMBLE_TIMEOUT=0 disables it entirely
-  const timeoutEnv = process.env.OPENCODE_ENSEMBLE_TIMEOUT
-  const watchdogTtl = timeoutEnv === "0" ? 0 : (parseInt(timeoutEnv ?? "", 10) || DEFAULT_WATCHDOG_TTL_MS)
+  // Initialize watchdog — config value already accounts for env var override
   const watchdog = new Watchdog({
     db, client, registry,
-    ttlMs: watchdogTtl,
+    ttlMs: config.timeoutMs,
     checkIntervalMs: DEFAULT_WATCHDOG_CHECK_MS,
+    progressTracker,
+    stallThresholdMs: config.stallThresholdMs,
+    stallMinSteps: config.stallMinSteps,
+    stallTokenThreshold: config.stallTokenThreshold,
   })
   watchdog.start()
 
@@ -185,6 +187,16 @@ const plugin: Plugin = async (input) => {
           handleSessionCreatedEvent(tracker, info.id, info.parentID)
         }
       }
+
+      // Track per-step output tokens for stall detection
+      if (event.type === "message.part.updated") {
+        const part = (event.properties as { part?: { type?: string; sessionID?: string; tokens?: { output?: number } } }).part
+        if (part?.type === "step-finish" && part.sessionID && part.tokens?.output !== undefined) {
+          if (registry.getBySession(part.sessionID)) {
+            progressTracker.recordStep(part.sessionID, part.tokens.output)
+          }
+        }
+      }
     },
 
     // Sub-agent isolation + rate limiting hook
@@ -283,6 +295,8 @@ const plugin: Plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID)
+          // Track message activity for stall detection
+          progressTracker.recordMessage(ctx.sessionID)
           ctx.metadata({ title: `Message → ${args.to}` })
           return result
         },
@@ -295,6 +309,8 @@ const plugin: Plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamBroadcast(deps, args, ctx.sessionID)
+          // Track broadcast activity for stall detection
+          progressTracker.recordMessage(ctx.sessionID)
           ctx.metadata({ title: "Broadcast to team" })
           return result
         },
@@ -334,6 +350,8 @@ const plugin: Plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamTasksComplete(deps, args, ctx.sessionID)
+          // Track task completion for stall detection
+          progressTracker.recordTaskComplete(ctx.sessionID)
           ctx.metadata({ title: `Completed task` })
           return result
         },
@@ -372,6 +390,9 @@ const plugin: Plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamShutdown(deps, args, ctx.sessionID)
+          // Clean up progress tracking for the shut-down member
+          const member = deps.db.query("SELECT session_id FROM team_member WHERE name = ? AND status IN ('shutdown', 'shutdown_requested')").get(args.member) as { session_id: string } | null
+          if (member) progressTracker.remove(member.session_id)
           const hasWarning = result.includes("uncommitted")
           ctx.metadata({ title: hasWarning ? `${args.member} shut down — uncommitted changes` : `${args.member} shut down` })
           return result
@@ -385,7 +406,7 @@ const plugin: Plugin = async (input) => {
           acknowledge_uncommitted: tool.schema.boolean().default(false),
         },
         async execute(args, ctx) {
-          const result = await executeTeamCleanup(deps, args, ctx.sessionID)
+          const result = await executeTeamCleanup(deps, args, ctx.sessionID, undefined, undefined, config.mergeOnCleanup)
           const blocked = result.includes("uncommitted")
           ctx.metadata({ title: blocked ? "Cleanup blocked — uncommitted changes" : "Team cleaned up" })
           return result

package/src/progress.ts

@@ -0,0 +1,85 @@
+/** A single model step record. */
+export interface StepRecord {
+  outputTokens: number
+  timestamp: number
+}
+
+/**
+ * In-memory tracker for teammate activity signals.
+ * Used by the watchdog for stall detection.
+ */
+export class ProgressTracker {
+  private steps = new Map<string, StepRecord[]>()
+  private lastMessageAt = new Map<string, number>()
+  private lastTaskAt = new Map<string, number>()
+  private reported = new Set<string>()
+  private readonly maxSteps: number
+
+  constructor(maxSteps = 10) {
+    this.maxSteps = maxSteps
+  }
+
+  /** Record a model step completion with output token count. Keeps last `maxSteps` entries. */
+  recordStep(sessionId: string, outputTokens: number): void {
+    const records = this.steps.get(sessionId) ?? []
+    records.push({ outputTokens, timestamp: Date.now() })
+    if (records.length > this.maxSteps) records.shift()
+    this.steps.set(sessionId, records)
+  }
+
+  /** Record that this member sent a team_message. Clears stall report. */
+  recordMessage(sessionId: string): void {
+    this.lastMessageAt.set(sessionId, Date.now())
+    this.clearReport(sessionId)
+  }
+
+  /** Record that this member completed a task. Clears stall report. */
+  recordTaskComplete(sessionId: string): void {
+    this.lastTaskAt.set(sessionId, Date.now())
+    this.clearReport(sessionId)
+  }
+
+  /** Token-based stall: last `minSteps` steps all produced < `threshold` output tokens. */
+  isTokenStalled(sessionId: string, minSteps: number, threshold: number): boolean {
+    const records = this.steps.get(sessionId)
+    if (!records || records.length < minSteps) return false
+    const recent = records.slice(-minSteps)
+    return recent.every(r => r.outputTokens < threshold)
+  }
+
+  /** Time-based stall: no message or task completion within `thresholdMs` of now. */
+  isTimeStalled(sessionId: string, thresholdMs: number): boolean {
+    const records = this.steps.get(sessionId)
+    if (!records || records.length === 0) return false
+
+    const msgAt = this.lastMessageAt.get(sessionId) ?? 0
+    const taskAt = this.lastTaskAt.get(sessionId) ?? 0
+    const lastStep = records[records.length - 1]?.timestamp ?? 0
+    const baseline = Math.max(msgAt, taskAt, lastStep)
+
+    return Date.now() - baseline >= thresholdMs
+  }
+
+  /** Mark this session as reported-stalled (avoid spam). */
+  markReported(sessionId: string): void {
+    this.reported.add(sessionId)
+  }
+
+  /** Check if already reported. */
+  isReported(sessionId: string): boolean {
+    return this.reported.has(sessionId)
+  }
+
+  /** Clear stall report (called on new activity). */
+  clearReport(sessionId: string): void {
+    this.reported.delete(sessionId)
+  }
+
+  /** Remove all tracking for a session (on shutdown). */
+  remove(sessionId: string): void {
+    this.steps.delete(sessionId)
+    this.lastMessageAt.delete(sessionId)
+    this.lastTaskAt.delete(sessionId)
+    this.reported.delete(sessionId)
+  }
+}

package/src/result-parser.ts

@@ -0,0 +1,40 @@
+/** Structured result parsed from `<task-result>` XML. */
+export interface TaskResult {
+  status: string
+  summary: string
+  details: string
+  branch?: string
+}
+
+/**
+ * Parse `<task-result>` XML from message content.
+ * Returns null if not found or missing required fields.
+ */
+export function parseTaskResult(content: string): TaskResult | null {
+  const match = content.match(/<task-result>([\s\S]*?)<\/task-result>/)
+  if (!match) return null
+
+  const inner = match[1]!
+  const status = inner.match(/<status>([\s\S]*?)<\/status>/)?.[1]?.trim()
+  const summary = inner.match(/<summary>([\s\S]*?)<\/summary>/)?.[1]?.trim()
+  const details = inner.match(/<details>([\s\S]*?)<\/details>/)?.[1]?.trim()
+  const branch = inner.match(/<branch>([\s\S]*?)<\/branch>/)?.[1]?.trim()
+
+  if (!status || !summary || !details) return null
+
+  return { status, summary, details, branch: branch || undefined }
+}
+
+/**
+ * Format a TaskResult as clean readable text.
+ */
+export function formatTaskResult(from: string, result: TaskResult): string {
+  const lines = [
+    `[Result from ${from}]:`,
+    `  Status: ${result.status}`,
+    `  Summary: ${result.summary}`,
+    `  Details: ${result.details}`,
+  ]
+  if (result.branch) lines.push(`  Branch: ${result.branch}`)
+  return lines.join("\n")
+}

package/src/system-prompt.ts

@@ -1,5 +1,11 @@
 import type { Database } from "bun:sqlite"
 import { markDelivered } from "./messaging"
+import { parseTaskResult, formatTaskResult } from "./result-parser"
+
+/** Truncate a string to maxLen chars, appending "..." if truncated. */
+function truncate(s: string, maxLen: number): string {
+  return s.length > maxLen ? `${s.slice(0, maxLen)}...` : s
+}
 
 /** Status display mapping from DB status to human-readable label. */
 const STATUS_DISPLAY: Record<string, string> = {
@@ -51,11 +57,38 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
   ]
 
+  // Inline active and recently completed tasks
+  const activeTasks = db.query(
+    "SELECT content, assignee FROM team_task WHERE team_id = ? AND status = 'in_progress' ORDER BY time_updated DESC LIMIT 5"
+  ).all(teamId) as Array<{ content: string; assignee: string | null }>
+
+  const recentCompleted = db.query(
+    "SELECT content, assignee FROM team_task WHERE team_id = ? AND status = 'completed' ORDER BY time_updated DESC LIMIT 3"
+  ).all(teamId) as Array<{ content: string; assignee: string | null }>
+
+  if (activeTasks.length > 0) {
+    lines.push("Active tasks:")
+    for (const t of activeTasks) {
+      lines.push(`  [in_progress] ${truncate(t.content, 120)}${t.assignee ? ` → ${t.assignee}` : ""}`)
+    }
+  }
+  if (recentCompleted.length > 0) {
+    lines.push("Recently completed:")
+    for (const t of recentCompleted) {
+      lines.push(`  [completed] ${truncate(t.content, 120)}${t.assignee ? ` → ${t.assignee}` : ""}`)
+    }
+  }
+
   if (pendingMessages.length > 0) {
     lines.push("", "--- Team Messages ---")
     const MAX_MSG = 500
     for (const msg of pendingMessages) {
-      if (msg.content.length > MAX_MSG) {
+      const parsed = parseTaskResult(msg.content)
+      if (parsed) {
+        // Truncate details for system prompt — full content available via team_results
+        const truncatedResult = { ...parsed, details: truncate(parsed.details, 500) }
+        lines.push(formatTaskResult(msg.from_name, truncatedResult))
+      } else 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}`)
@@ -141,8 +174,41 @@ export function buildTeamCompactionContext(
     `Tasks: ${completed} completed, ${inProgress} in progress, ${pending} pending`,
   ]
 
-  if (role === "member") {
+  if (role === "member" && memberName) {
     lines.push("IMPORTANT: You MUST send your results to the lead via team_message before stopping.")
+
+    // Include original task prompt
+    const member = db.query("SELECT prompt FROM team_member WHERE team_id = ? AND name = ?")
+      .get(teamId, memberName) as { prompt: string | null } | null
+    if (member?.prompt) {
+      lines.push(`Your original task: ${truncate(member.prompt, 300)}`)
+    }
+
+    // Include recent messages involving this member
+    const recentMsgs = db.query(
+      "SELECT from_name, content FROM team_message WHERE team_id = ? AND (from_name = ? OR to_name = ?) ORDER BY time_created DESC LIMIT 3"
+    ).all(teamId, memberName, memberName) as Array<{ from_name: string; content: string }>
+    if (recentMsgs.length > 0) {
+      lines.push("Recent context:")
+      for (const msg of recentMsgs) {
+        lines.push(`  [${msg.from_name}]: ${truncate(msg.content, 200)}`)
+      }
+    }
+  } else if (role === "member") {
+    lines.push("IMPORTANT: You MUST send your results to the lead via team_message before stopping.")
+  }
+
+  if (role === "lead") {
+    // Include recently completed tasks
+    const completedTasks = db.query(
+      "SELECT content, assignee FROM team_task WHERE team_id = ? AND status = 'completed' ORDER BY time_updated DESC LIMIT 5"
+    ).all(teamId) as Array<{ content: string; assignee: string | null }>
+    if (completedTasks.length > 0) {
+      lines.push("Recently completed:")
+      for (const t of completedTasks) {
+        lines.push(`  [completed] ${truncate(t.content, 120)}${t.assignee ? ` (by ${t.assignee})` : ""}`)
+      }
+    }
   }
 
   return lines.join("\n")

package/src/tools/team-cleanup.ts

@@ -1,8 +1,64 @@
 import type { ToolDeps } from "../types"
 import { requireLead, checkWorktreeDirty } from "./shared"
 import type { IsDirtyFn } from "./shared"
+import { spawnFailures } from "./team-spawn"
 import { log } from "../log"
 
+/** Result of merging all branches. */
+export interface MergeAllResult {
+  merged: string[]
+  conflicted: string[]
+}
+
+/** Injectable function that merges all branches into the working directory. */
+export type MergeAllFn = (branches: string[], cwd: string) => Promise<MergeAllResult>
+
+/**
+ * Default merge implementation: stash user work, squash-merge each branch,
+ * unstage merged changes, restore user work. One stash/pop cycle for all branches.
+ */
+export async function mergeAllBranches(branches: string[], cwd: string): Promise<MergeAllResult> {
+  const merged: string[] = []
+  const conflicted: string[] = []
+
+  // Stash existing work to preserve staged/unstaged state
+  const stash = Bun.spawn(["git", "stash", "--include-untracked"], { cwd, stdout: "pipe", stderr: "pipe" })
+  const stashOut = await new Response(stash.stdout).text()
+  const stashExit = await stash.exited
+  const didStash = stashExit === 0 && !stashOut.includes("No local changes")
+
+  for (const branch of branches) {
+    const merge = Bun.spawn(["git", "merge", "--squash", branch], { cwd, stdout: "pipe", stderr: "pipe" })
+    const stderrPromise = new Response(merge.stderr).text()
+    const exit = await merge.exited
+    if (exit !== 0) {
+      const stderr = await stderrPromise
+      log(`cleanup:merge:conflict branch=${branch} err=${stderr.trim()}`)
+      const abort = Bun.spawn(["git", "merge", "--abort"], { cwd, stdout: "pipe", stderr: "pipe" })
+      await abort.exited
+      conflicted.push(branch)
+    } else {
+      const del = Bun.spawn(["git", "branch", "-D", branch], { cwd, stdout: "pipe", stderr: "pipe" })
+      await del.exited
+      merged.push(branch)
+    }
+  }
+
+  // Unstage merged changes so user reviews with `git diff`
+  if (merged.length > 0) {
+    const reset = Bun.spawn(["git", "reset", "HEAD"], { cwd, stdout: "pipe", stderr: "pipe" })
+    await reset.exited
+  }
+
+  // Restore user's original staged/unstaged work
+  if (didStash) {
+    const pop = Bun.spawn(["git", "stash", "pop", "--index"], { cwd, stdout: "pipe", stderr: "pipe" })
+    await pop.exited
+  }
+
+  return { merged, conflicted }
+}
+
 /**
  * Execute the team_cleanup tool. Archives the team and cleans up resources.
  * Checks for uncommitted changes BEFORE aborting sessions or removing worktrees.
@@ -14,6 +70,8 @@ export async function executeTeamCleanup(
   args: { force: boolean; acknowledge_uncommitted?: boolean },
   sessionId: string,
   isDirty: IsDirtyFn = checkWorktreeDirty,
+  mergeAll: MergeAllFn = mergeAllBranches,
+  mergeOnCleanup = true,
 ): Promise<string> {
   const teamInfo = requireLead(deps, sessionId)
 
@@ -57,8 +115,25 @@ export async function executeTeamCleanup(
     }
   }
 
-  // Remove workspaces, worktrees, and collect branches for merging
-  const branches: string[] = []
+  // Collect branches and merge BEFORE removing worktrees (worktree.remove may delete the branch ref)
+  const branches = members
+    .map(m => m.worktree_branch)
+    .filter((b): b is string => b !== null)
+
+  let mergeResult = ""
+  if (branches.length > 0 && mergeOnCleanup) {
+    const { merged, conflicted } = await mergeAll(branches, deps.directory)
+    const parts: string[] = []
+    if (merged.length > 0) {
+      parts.push(`Merged ${merged.length} branch(es) into working directory (unstaged). Review changes with: git diff`)
+    }
+    if (conflicted.length > 0) {
+      parts.push(`Could not auto-merge: ${conflicted.join(", ")}. Merge manually with: git merge <branch>`)
+    }
+    mergeResult = parts.join("\n")
+  }
+
+  // Remove workspaces and worktrees (after merging)
   for (const member of members) {
     if (member.workspace_id) {
       try {
@@ -72,16 +147,18 @@ export async function executeTeamCleanup(
         deps.db.run("UPDATE team_member SET worktree_dir = NULL WHERE team_id = ? AND name = ?", [teamInfo.teamId, member.name])
       } catch { /* best effort — worktree may already be gone */ }
     }
-    if (member.worktree_branch) {
-      branches.push(member.worktree_branch)
-    }
   }
 
   // Archive team
   deps.db.run("UPDATE team SET status = 'archived', time_updated = ? WHERE id = ?", [Date.now(), teamInfo.teamId])
 
-  // Clean up registry
+  // Clean up in-memory state
   deps.registry.unregisterTeam(teamInfo.teamId)
+  spawnFailures.delete(teamInfo.teamId)
+
+  if (mergeResult) {
+    return `Team "${teamInfo.teamName}" cleaned up.\n${mergeResult}`
+  }
 
   if (branches.length > 0) {
     const mergeCommands = branches.map(b => `  git merge ${b}`).join("\n")

package/src/tools/team-results.ts

@@ -1,5 +1,6 @@
 import type { ToolDeps } from "../types"
 import { requireTeamMember } from "./shared"
+import { parseTaskResult, formatTaskResult } from "../result-parser"
 
 /** Row shape for unread messages query. */
 interface UnreadMessageRow {
@@ -39,6 +40,10 @@ export async function executeTeamResults(
   const placeholders = ids.map(() => "?").join(", ")
   deps.db.run(`UPDATE team_message SET read = 1 WHERE id IN (${placeholders})`, ids)
 
-  // Format output
-  return rows.map((r) => `[Message from ${r.from_name}]:\n${r.content}\n`).join("\n")
+  // Format output — parse structured task results when present
+  return rows.map((r) => {
+    const parsed = parseTaskResult(r.content)
+    if (parsed) return formatTaskResult(r.from_name, parsed)
+    return `[Message from ${r.from_name}]:\n${r.content}`
+  }).join("\n\n")
 }

package/src/tools/team-spawn.ts

@@ -4,6 +4,9 @@ import { requireLead } from "./shared"
 import { sendMessage } from "../messaging"
 import { log } from "../log"
 
+/** Tracks consecutive spawn failures per team for circuit breaker. */
+export const spawnFailures = new Map<string, { count: number; lastError: string }>()
+
 /** 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
@@ -41,6 +44,12 @@ export async function executeTeamSpawn(
 
   const teamInfo = requireLead(deps, sessionId)
 
+  // Circuit breaker — stop retrying after 3 consecutive failures
+  const failures = spawnFailures.get(teamInfo.teamId)
+  if (failures && failures.count >= 3) {
+    throw new Error(`Spawn circuit breaker tripped for team "${teamInfo.teamName}": 3 consecutive failures. Last error: ${failures.lastError}. Investigate before retrying — the circuit breaker resets on the next successful spawn.`)
+  }
+
   // Check duplicate name
   const existing = deps.db.query("SELECT name FROM team_member WHERE team_id = ? AND name = ?")
     .get(teamInfo.teamId, args.name)
@@ -146,6 +155,10 @@ export async function executeTeamSpawn(
     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)}`)
+    // Track failure for circuit breaker
+    const errMsg = err instanceof Error ? err.message : String(err)
+    const prev = spawnFailures.get(teamInfo.teamId)
+    spawnFailures.set(teamInfo.teamId, { count: (prev?.count ?? 0) + 1, lastError: errMsg })
     // Rollback workspace and worktree if session creation failed
     if (workspaceId) {
       try { await deps.client.workspace.remove({ id: workspaceId }) } catch { /* best effort */ }
@@ -184,6 +197,14 @@ export async function executeTeamSpawn(
     `Your agent type is "${args.agent}".`,
   ]
 
+  // Show other teammates so this agent knows who to message
+  const otherMembers = deps.db.query(
+    "SELECT name FROM team_member WHERE team_id = ? AND name != ? AND status NOT IN ('shutdown', 'error')"
+  ).all(teamInfo.teamId, args.name) as Array<{ name: string }>
+  if (otherMembers.length > 0) {
+    context.push(`Other teammates: ${otherMembers.map(m => m.name).join(", ")}`)
+  }
+
   if (worktreeBranch && worktreeDir && !workspaceId) {
     // Workspace binding failed — fallback to prompt-based CWD instruction
     context.push(
@@ -263,7 +284,9 @@ export async function executeTeamSpawn(
   context.push(
     `${lastStep}. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.`,
     "",
-    "If you are blocked, send ONE message to the lead describing the specific blocker.",
+    "If you are blocked:",
+    "- Send ONE message to the lead via team_message describing the specific blocker.",
+    "- Do NOT attempt workarounds or make assumptions. Wait for the lead's response.",
     "",
     "Your plain text output is NOT visible to the team. You MUST use team_message to communicate.",
   )
@@ -319,6 +342,8 @@ export async function executeTeamSpawn(
 
   const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
   const planInfo = usePlanApproval ? " [plan mode — will send plan for approval]" : ""
+  // Reset circuit breaker on success
+  spawnFailures.delete(teamInfo.teamId)
   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 ? "..." : ""}`
 }