@hueyexe/opencode-ensemble 0.9.0 → 0.9.1

package/src/index.ts

@@ -5,7 +5,7 @@ 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 { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees, recoverOrphanedBranches } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
 import { isWorktreeInstance } from "./util"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation, shouldNudgeIdleMember } from "./hooks"
@@ -21,6 +21,7 @@ import { executeTeamMessage } from "./tools/team-message"
 import { executeTeamBroadcast } from "./tools/team-broadcast"
 import { executeTeamShutdown } from "./tools/team-shutdown"
 import { executeTeamCleanup } from "./tools/team-cleanup"
+import { executeTeamMerge } from "./tools/team-merge"
 import { executeTeamTasksList } from "./tools/team-tasks-list"
 import { executeTeamTasksAdd } from "./tools/team-tasks-add"
 import { executeTeamTasksComplete } from "./tools/team-tasks-complete"
@@ -71,7 +72,7 @@ const plugin: Plugin = async (input) => {
   // 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)
+    const recovery = await recoverStaleMembers(db, client, input.directory)
     if (recovery.interrupted > 0) {
       log(`init:recovery:interrupted=${recovery.interrupted}`)
       const members = db.query(
@@ -88,6 +89,9 @@ const plugin: Plugin = async (input) => {
     recoverOrphanedWorktrees(db, client).catch((err) => {
       log(`init:recover-worktrees:failed err=${err instanceof Error ? err.message : String(err)}`)
     })
+    recoverOrphanedBranches(db, input.directory).catch((err) => {
+      log(`init:recover-branches:failed err=${err instanceof Error ? err.message : String(err)}`)
+    })
     log("init:recovery:done")
   } else {
     log(`init:skip-recovery (worktree instance: ${input.directory})`)
@@ -109,6 +113,7 @@ const plugin: Plugin = async (input) => {
     stallThresholdMs: config.stallThresholdMs,
     stallMinSteps: config.stallMinSteps,
     stallTokenThreshold: config.stallTokenThreshold,
+    cwd: input.directory,
   })
   watchdog.start()
 
@@ -150,12 +155,27 @@ const plugin: Plugin = async (input) => {
             } catch { /* TUI may not be available */ }
           } else if (transition.to === "busy_while_shutdown") {
             // Session went busy after shutdown was requested — re-issue abort
-            const entry = registry.getBySession(sessionID)
-            if (entry) {
-              try {
-                await client.session.abort({ sessionID })
-              } catch { /* best effort */ }
+            // Branch should already be preserved by the graceful shutdown path,
+            // but verify and re-preserve if needed
+            const member = deps.db.query(
+              "SELECT worktree_branch, name, team_id FROM team_member WHERE session_id = ?"
+            ).get(sessionID) as { worktree_branch: string | null; name: string; team_id: string } | null
+            if (member?.worktree_branch && !member.worktree_branch.startsWith("ensemble/preserved/")) {
+              const teamRow = deps.db.query("SELECT name FROM team WHERE id = ?").get(member.team_id) as { name: string } | null
+              if (teamRow) {
+                const { preserveBranch: preserve, preservedBranchName: branchName } = await import("./tools/merge-helper")
+                const safeBranch = branchName(teamRow.name, member.name)
+                const ok = await preserve(member.worktree_branch, safeBranch, deps.directory)
+                if (ok) {
+                  deps.db.run("UPDATE team_member SET worktree_branch = ? WHERE team_id = ? AND name = ?",
+                    [safeBranch, member.team_id, member.name])
+                  log(`busy_while_shutdown:branch:preserved src=${member.worktree_branch} target=${safeBranch}`)
+                }
+              }
             }
+            try {
+              await client.session.abort({ sessionID })
+            } catch { /* best effort */ }
           }
 
           // Show working progress after every transition so the user sees who's still active
@@ -406,13 +426,28 @@ const plugin: Plugin = async (input) => {
           acknowledge_uncommitted: tool.schema.boolean().default(false),
         },
         async execute(args, ctx) {
-          const result = await executeTeamCleanup(deps, args, ctx.sessionID, undefined, undefined, config.mergeOnCleanup)
+          const result = await executeTeamCleanup(deps, args, ctx.sessionID, undefined, undefined, undefined, config.mergeOnCleanup)
           const blocked = result.includes("uncommitted")
           ctx.metadata({ title: blocked ? "Cleanup blocked — uncommitted changes" : "Team cleaned up" })
           return result
         },
       }),
 
+      team_merge: tool({
+        description: "Merge a shutdown teammate's branch into the working directory as unstaged changes. " +
+          "Use this after team_shutdown to review and integrate a teammate's work. " +
+          "The teammate must be shut down first.",
+        args: {
+          member: tool.schema.string().describe("Teammate name whose branch to merge"),
+        },
+        async execute(args, ctx) {
+          const result = await executeTeamMerge(deps, args, ctx.sessionID)
+          const conflict = result.includes("conflict")
+          ctx.metadata({ title: conflict ? `Merge conflict: ${args.member}` : `Merged ${args.member}` })
+          return result
+        },
+      }),
+
       team_status: tool({
         description: "View team members with their current status, agent type, and session IDs. " +
           "Use this to check who is working, idle, or shut down. Includes a task summary.",

package/src/recovery.ts

@@ -2,21 +2,24 @@ import type { Database } from "bun:sqlite"
 import type { PluginClient } from "./types"
 import type { MemberRegistry } from "./state"
 import { getUndeliveredMessages, markDelivered } from "./messaging"
+import { preserveBranch, preservedBranchName } from "./tools/merge-helper"
+import { log } from "./log"
 
 /**
  * Scan for team members stuck in 'busy' status (stale from a crash)
  * and mark them as 'error' with execution_status 'idle'.
- * Also aborts their orphaned sessions (best effort).
+ * Preserves worktree branches before aborting orphaned sessions.
  * Only processes members in active teams.
  * Returns the count of interrupted members.
  */
-export async function recoverStaleMembers(db: Database, client?: PluginClient): Promise<{ interrupted: number }> {
-  // Find stale members before updating so we can abort their sessions
+export async function recoverStaleMembers(db: Database, client?: PluginClient, cwd?: string): Promise<{ interrupted: number }> {
+  // Find stale members with branch info so we can preserve before aborting
   const stale = db.query(
-    `SELECT tm.session_id FROM team_member tm
+    `SELECT tm.session_id, tm.worktree_branch, tm.name, tm.team_id, t.name as team_name
+     FROM team_member tm
      JOIN team t ON tm.team_id = t.id
      WHERE tm.status = 'busy' AND t.status = 'active'`
-  ).all() as Array<{ session_id: string }>
+  ).all() as Array<{ session_id: string; worktree_branch: string | null; name: string; team_id: string; team_name: string }>
 
   const result = db.run(
     `UPDATE team_member SET status = 'error', execution_status = 'idle', time_updated = ?
@@ -25,9 +28,19 @@ export async function recoverStaleMembers(db: Database, client?: PluginClient):
     [Date.now()]
   )
 
-  // Abort orphaned sessions (best effort)
+  // Preserve branches then abort orphaned sessions
   if (client) {
     for (const member of stale) {
+      // Preserve branch BEFORE abort — session.abort() may destroy the worktree + branch
+      if (cwd && member.worktree_branch && !member.worktree_branch.startsWith("ensemble/preserved/")) {
+        const safeBranch = preservedBranchName(member.team_name, member.name)
+        const ok = await preserveBranch(member.worktree_branch, safeBranch, cwd)
+        if (ok) {
+          db.run("UPDATE team_member SET worktree_branch = ? WHERE team_id = ? AND name = ?",
+            [safeBranch, member.team_id, member.name])
+          log(`recovery:branch:preserved src=${member.worktree_branch} target=${safeBranch}`)
+        }
+      }
       try {
         await client.session.abort({ sessionID: member.session_id })
       } catch { /* best effort */ }
@@ -125,3 +138,53 @@ export async function recoverUndeliveredMessages(
 
   return { redelivered }
 }
+
+/**
+ * Clean up orphaned ensemble/preserved/* branches that belong to archived teams
+ * with no active members. Scoped carefully to avoid interfering with other
+ * running OpenCode sessions that may have active teams.
+ */
+export async function recoverOrphanedBranches(db: Database, cwd: string): Promise<{ removed: number }> {
+  let removed = 0
+
+  // Get archived team names that have NO active members
+  const archivedTeams = db.query(
+    `SELECT t.name FROM team t
+     WHERE t.status = 'archived'
+     AND NOT EXISTS (
+       SELECT 1 FROM team_member tm
+       WHERE tm.team_id = t.id AND tm.status NOT IN ('shutdown', 'error')
+     )`
+  ).all() as Array<{ name: string }>
+
+  if (archivedTeams.length === 0) return { removed: 0 }
+
+  const archivedNames = new Set(archivedTeams.map(t => t.name))
+
+  // List all local branches matching ensemble/preserved/*
+  const proc = Bun.spawn(["git", "branch", "--list", "ensemble/preserved/*"], { cwd, stdout: "pipe", stderr: "pipe" })
+  const stdoutPromise = new Response(proc.stdout).text()
+  await proc.exited
+  const stdout = await stdoutPromise
+
+  const branches = stdout.split("\n").map(b => b.trim().replace(/^\* /, "")).filter(Boolean)
+
+  for (const branch of branches) {
+    // Parse team name from branch: ensemble/preserved/{teamName}/{memberName}
+    const parts = branch.split("/")
+    if (parts.length < 4) continue
+    const teamName = parts[2]
+    if (!teamName || !archivedNames.has(teamName)) continue
+
+    try {
+      const del = Bun.spawn(["git", "branch", "-D", branch], { cwd, stdout: "pipe", stderr: "pipe" })
+      const exitCode = await del.exited
+      if (exitCode === 0) {
+        removed++
+        log(`recovery:branch:deleted branch=${branch}`)
+      }
+    } catch { /* best effort */ }
+  }
+
+  return { removed }
+}

package/src/system-prompt.ts

@@ -109,6 +109,12 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     "After spawning all teammates, tell the user what you've set up and wait.",
     "When all teammates finish, summarize results and suggest next steps.",
     "",
+    "MERGE WORKFLOW:",
+    "After a teammate finishes and you shut them down, use team_merge to merge their branch.",
+    "Do NOT tell teammates to commit — they handle that themselves.",
+    "Do NOT run git merge manually — use team_merge which handles stashing and unstaging.",
+    "team_cleanup will safety-net merge any branches you forgot, but prefer explicit team_merge.",
+    "",
     "Before calling team_cleanup, verify teammates have committed their work.",
     "team_shutdown will warn you if a teammate has uncommitted changes.",
     "team_cleanup will block if any worktree has uncommitted changes — merge or commit first.",

package/src/tools/merge-helper.ts

@@ -0,0 +1,126 @@
+import { log } from "../log"
+
+/** Result of merging a single branch. */
+export interface MergeResult {
+  ok: boolean
+  error?: string
+}
+
+/** Injectable function for testing. */
+export type MergeBranchFn = (branch: string, cwd: string) => Promise<MergeResult>
+
+/** Injectable function for preserving a branch before worktree deletion. */
+export type PreserveBranchFn = (sourceBranch: string, targetBranch: string, cwd: string) => Promise<boolean>
+
+/** Injectable function for deleting a branch. */
+export type DeleteBranchFn = (branch: string, cwd: string) => Promise<boolean>
+
+/**
+ * Copy a git branch to a new ref. Used to preserve worktree branches
+ * before session.abort() which may delete the worktree and its branch.
+ * Returns true if the branch was successfully copied.
+ */
+export async function preserveBranch(sourceBranch: string, targetBranch: string, cwd: string): Promise<boolean> {
+  const proc = Bun.spawn(["git", "branch", targetBranch, sourceBranch], { cwd, stdout: "pipe", stderr: "pipe" })
+  const exit = await proc.exited
+  if (exit !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    log(`merge-helper:preserve:failed src=${sourceBranch} target=${targetBranch} err=${stderr.trim()}`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Delete a git branch. Returns true if successful.
+ */
+export async function deleteBranch(branch: string, cwd: string): Promise<boolean> {
+  const proc = Bun.spawn(["git", "branch", "-D", branch], { cwd, stdout: "pipe", stderr: "pipe" })
+  const exit = await proc.exited
+  if (exit !== 0) {
+    log(`merge-helper:delete:failed branch=${branch}`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Raw squash merge of a single branch. No stash/pop — caller handles that.
+ * Used by mergeBranch (single) and mergeMultipleBranches (batch).
+ */
+export async function mergeBranchRaw(branch: string, cwd: string): Promise<MergeResult> {
+  const merge = Bun.spawn(["git", "merge", "--squash", branch], { cwd, stdout: "pipe", stderr: "pipe" })
+  const stderrPromise = new Response(merge.stderr).text()
+  const mergeExit = await merge.exited
+
+  if (mergeExit !== 0) {
+    const stderr = await stderrPromise
+    log(`merge-helper:merge:conflict branch=${branch} err=${stderr.trim()}`)
+    const abort = Bun.spawn(["git", "merge", "--abort"], { cwd, stdout: "pipe", stderr: "pipe" })
+    await abort.exited
+    return { ok: false, error: stderr.trim() || `merge exited with code ${mergeExit}` }
+  }
+
+  return { ok: true }
+}
+
+/** Stash existing work. Returns true if something was stashed. */
+export async function gitStash(cwd: string): Promise<boolean> {
+  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
+  return stashExit === 0 && !stashOut.includes("No local changes")
+}
+
+/** Unstage all changes. */
+export async function gitReset(cwd: string): Promise<void> {
+  const reset = Bun.spawn(["git", "reset", "HEAD"], { cwd, stdout: "pipe", stderr: "pipe" })
+  await reset.exited
+}
+
+/** Restore stashed work, preserving staged/unstaged state. Returns true if successful. */
+export async function gitStashPop(cwd: string): Promise<boolean> {
+  const pop = Bun.spawn(["git", "stash", "pop", "--index"], { cwd, stdout: "pipe", stderr: "pipe" })
+  const exit = await pop.exited
+  if (exit !== 0) {
+    // --index is strict about staged/unstaged distinction — fall back to plain pop
+    const fallback = Bun.spawn(["git", "stash", "pop"], { cwd, stdout: "pipe", stderr: "pipe" })
+    const fallbackExit = await fallback.exited
+    if (fallbackExit !== 0) {
+      log("merge-helper:stash-pop:failed — stashed work remains in git stash list")
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Stash-safe squash merge of a single branch into the working directory.
+ * Stashes existing work, merges, unstages, restores stash.
+ */
+export async function mergeBranch(branch: string, cwd: string): Promise<MergeResult> {
+  const didStash = await gitStash(cwd)
+
+  const result = await mergeBranchRaw(branch, cwd)
+  if (!result.ok) {
+    if (didStash) {
+      const restored = await gitStashPop(cwd)
+      if (!restored) return { ok: false, error: `${result.error}. WARNING: stashed work could not be restored — check git stash list` }
+    }
+    return result
+  }
+
+  await gitReset(cwd)
+  if (didStash) {
+    const restored = await gitStashPop(cwd)
+    if (!restored) return { ok: true, error: "Merge succeeded but stashed work could not be restored — check git stash list" }
+  }
+  return { ok: true }
+}
+
+/**
+ * Build the preserved branch name for a team member.
+ */
+export function preservedBranchName(teamName: string, memberName: string): string {
+  return `ensemble/preserved/${teamName}/${memberName}`
+}

package/src/tools/team-cleanup.ts

@@ -2,75 +2,22 @@ import type { ToolDeps } from "../types"
 import { requireLead, checkWorktreeDirty } from "./shared"
 import type { IsDirtyFn } from "./shared"
 import { spawnFailures } from "./team-spawn"
+import { mergeBranch, deleteBranch, preserveBranch, preservedBranchName } from "./merge-helper"
+import type { MergeBranchFn, DeleteBranchFn, PreserveBranchFn } from "./merge-helper"
 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.
- * If force=true, aborts active sessions but still blocks on dirty worktrees.
- * Pass acknowledge_uncommitted=true to remove dirty worktrees.
+ * Acts as a safety net: merges any remaining unmerged preserved branches
+ * that the lead forgot to merge with team_merge.
  */
 export async function executeTeamCleanup(
   deps: ToolDeps,
   args: { force: boolean; acknowledge_uncommitted?: boolean },
   sessionId: string,
   isDirty: IsDirtyFn = checkWorktreeDirty,
-  mergeAll: MergeAllFn = mergeAllBranches,
+  merge: MergeBranchFn = mergeBranch,
+  delBranch: DeleteBranchFn = deleteBranch,
   mergeOnCleanup = true,
 ): Promise<string> {
   const teamInfo = requireLead(deps, sessionId)
@@ -85,7 +32,7 @@ export async function executeTeamCleanup(
     throw new Error(`Cannot clean up team "${teamInfo.teamName}": ${active.length} member(s) still active: ${names}. Use team_shutdown on each member first, or call team_cleanup with force: true to abort them immediately.`)
   }
 
-  // Check for uncommitted changes BEFORE aborting sessions — agents can still commit if warned
+  // Check for uncommitted changes BEFORE aborting sessions
   if (!args.acknowledge_uncommitted) {
     const dirty: Array<{ name: string; branch: string }> = []
     for (const member of members) {
@@ -99,53 +46,64 @@ export async function executeTeamCleanup(
         }
       }
     }
-
     if (dirty.length > 0) {
       const warnings = dirty.map(d => `  - ${d.name} (branch: ${d.branch})`).join("\n")
       return `Warning: ${dirty.length} teammate(s) have uncommitted changes in their worktrees:\n${warnings}\n\nCommit or merge their work first, then call team_cleanup with acknowledge_uncommitted: true to proceed.`
     }
   }
 
-  // Force-abort active members (only reached if worktrees are clean or acknowledged)
+  // Force-abort active members — preserve branches BEFORE aborting
   if (args.force) {
     for (const member of active) {
+      // Preserve branch before abort — session.abort() may destroy the worktree + branch
+      if (member.worktree_branch && !member.worktree_branch.startsWith("ensemble/preserved/")) {
+        const safeBranch = preservedBranchName(teamInfo.teamName, member.name)
+        const ok = await preserveBranch(member.worktree_branch, safeBranch, deps.directory)
+        if (ok) {
+          deps.db.run("UPDATE team_member SET worktree_branch = ? WHERE team_id = ? AND name = ?",
+            [safeBranch, teamInfo.teamId, member.name])
+          member.worktree_branch = safeBranch
+        }
+      }
       try {
         await deps.client.session.abort({ sessionID: member.session_id })
       } catch { /* best effort */ }
     }
   }
 
-  // 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)
+  // Safety net: merge any remaining unmerged preserved branches
+  const unmerged = members.filter(m => m.worktree_branch !== null)
+  const merged: string[] = []
+  const conflicted: string[] = []
 
-  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>`)
+  if (unmerged.length > 0 && mergeOnCleanup) {
+    for (const member of unmerged) {
+      const branch = member.worktree_branch!
+      const result = await merge(branch, deps.directory)
+      if (result.ok) {
+        await delBranch(branch, deps.directory)
+        deps.db.run("UPDATE team_member SET worktree_branch = NULL WHERE team_id = ? AND name = ?", [teamInfo.teamId, member.name])
+        merged.push(`${member.name} (${branch})`)
+      } else {
+        log(`cleanup:merge:conflict member=${member.name} branch=${branch} err=${result.error}`)
+        conflicted.push(`${member.name} (${branch})`)
+      }
     }
-    mergeResult = parts.join("\n")
   }
 
-  // Remove workspaces and worktrees (after merging)
+  // Remove workspaces and worktrees
   for (const member of members) {
     if (member.workspace_id) {
       try {
         await deps.client.workspace.remove({ id: member.workspace_id })
         deps.db.run("UPDATE team_member SET workspace_id = NULL WHERE team_id = ? AND name = ?", [teamInfo.teamId, member.name])
-      } catch { /* best effort — workspace may already be gone */ }
+      } catch { /* best effort */ }
     }
     if (member.worktree_dir) {
       try {
         await deps.client.worktree.remove({ worktreeRemoveInput: { directory: member.worktree_dir } })
         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 */ }
+      } catch { /* best effort */ }
     }
   }
 
@@ -156,14 +114,13 @@ export async function executeTeamCleanup(
   deps.registry.unregisterTeam(teamInfo.teamId)
   spawnFailures.delete(teamInfo.teamId)
 
-  if (mergeResult) {
-    return `Team "${teamInfo.teamName}" cleaned up.\n${mergeResult}`
+  // Build response
+  const parts: string[] = [`Team "${teamInfo.teamName}" cleaned up.`]
+  if (merged.length > 0) {
+    parts.push(`Safety-net merged ${merged.length} unmerged branch(es): ${merged.join(", ")}. Review with: git diff`)
   }
-
-  if (branches.length > 0) {
-    const mergeCommands = branches.map(b => `  git merge ${b}`).join("\n")
-    return `Team "${teamInfo.teamName}" cleaned up. Worktrees removed.\n\nMerge teammate branches:\n${mergeCommands}`
+  if (conflicted.length > 0) {
+    parts.push(`Could not auto-merge: ${conflicted.join(", ")}. Merge manually.`)
   }
-
-  return `Team "${teamInfo.teamName}" cleaned up.`
+  return parts.join("\n")
 }

package/src/tools/team-merge.ts

@@ -0,0 +1,49 @@
+import type { ToolDeps } from "../types"
+import { requireLead } from "./shared"
+import { mergeBranch, deleteBranch } from "./merge-helper"
+import type { MergeBranchFn, DeleteBranchFn } from "./merge-helper"
+import { log } from "../log"
+
+/**
+ * Execute the team_merge tool. Merges a shutdown teammate's preserved
+ * branch into the working directory as unstaged changes.
+ */
+export async function executeTeamMerge(
+  deps: ToolDeps,
+  args: { member: string },
+  sessionId: string,
+  merge: MergeBranchFn = mergeBranch,
+  delBranch: DeleteBranchFn = deleteBranch,
+): Promise<string> {
+  const teamInfo = requireLead(deps, sessionId)
+
+  const member = deps.db.query("SELECT status, worktree_branch FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamInfo.teamId, args.member) as { status: string; worktree_branch: string | null } | null
+  if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
+
+  if (member.status !== "shutdown" && member.status !== "error") {
+    throw new Error(`Teammate "${args.member}" is still active (status: ${member.status}). Shut them down first with team_shutdown.`)
+  }
+
+  if (!member.worktree_branch) {
+    throw new Error(`No branch to merge for "${args.member}". They may not have a worktree, or their work was already merged.`)
+  }
+
+  const branch = member.worktree_branch
+  log(`merge:start member=${args.member} branch=${branch}`)
+
+  const result = await merge(branch, deps.directory)
+  if (!result.ok) {
+    return `Merge conflict with ${args.member}'s branch (${branch}). Resolve manually:\n  git merge --squash ${branch}\n\nError: ${result.error}`
+  }
+
+  // Merge succeeded — delete the preserved branch and clear DB
+  await delBranch(branch, deps.directory)
+  deps.db.run(
+    "UPDATE team_member SET worktree_branch = NULL WHERE team_id = ? AND name = ?",
+    [teamInfo.teamId, args.member],
+  )
+
+  log(`merge:done member=${args.member} branch=${branch}`)
+  return `Merged ${args.member}'s changes into working directory (unstaged). Review with: git diff`
+}