@hueyexe/opencode-ensemble 0.9.0 → 0.10.0

package/src/dashboard.ts

@@ -0,0 +1,166 @@
+import type { Database } from "bun:sqlite"
+import { DASHBOARD_HEAD } from "./dashboard-html"
+import { DASHBOARD_JS_PART1 } from "./dashboard-js-part1"
+import { DASHBOARD_JS_PART2 } from "./dashboard-js-part2"
+import { DASHBOARD_JS_PART3 } from "./dashboard-js-part3"
+import { log } from "./log"
+
+/** Assemble the full dashboard HTML from parts. */
+const DASHBOARD_HTML = DASHBOARD_HEAD + "\n<script>" + DASHBOARD_JS_PART1 + DASHBOARD_JS_PART2 + DASHBOARD_JS_PART3 + "<\/script>\n</body></html>"
+
+interface TeamRow {
+  id: string
+  name: string
+  status: string
+  lead_agent: string | null
+  time_created: number
+  time_updated: number
+}
+
+interface MemberRow {
+  name: string
+  agent: string
+  status: string
+  execution_status: string
+  worktree_branch: string | null
+  prompt: string | null
+  model: string | null
+  plan_approval: string
+  time_created: number
+  time_updated: number
+}
+
+interface TaskRow {
+  id: string
+  content: string
+  status: string
+  priority: string
+  assignee: string | null
+  depends_on: string | null
+  time_created: number
+  time_updated: number
+}
+
+interface MessageRow {
+  id: string
+  from_name: string
+  to_name: string | null
+  content: string
+  delivered: number
+  read: number
+  time_created: number
+}
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+  })
+}
+
+function buildState(db: Database): { teams: unknown[] } {
+  const teams = db.query("SELECT id, name, status, lead_agent, time_created, time_updated FROM team ORDER BY time_created DESC").all() as TeamRow[]
+  const memberStmt = db.query("SELECT name, agent, status, execution_status, worktree_branch, prompt, model, plan_approval, time_created, time_updated FROM team_member WHERE team_id = ?")
+  const taskStmt = db.query("SELECT id, content, status, priority, assignee, depends_on, time_created, time_updated FROM team_task WHERE team_id = ?")
+  const msgStmt = db.query("SELECT id, from_name, to_name, content, delivered, read, time_created FROM team_message WHERE team_id = ? ORDER BY time_created DESC LIMIT 50")
+
+  return {
+    teams: teams.map((t) => ({
+      id: t.id,
+      name: t.name,
+      status: t.status,
+      leadAgent: t.lead_agent,
+      timeCreated: t.time_created,
+      timeUpdated: t.time_updated,
+      members: (memberStmt.all(t.id) as MemberRow[]).map((m) => ({
+        name: m.name,
+        agent: m.agent,
+        status: m.status,
+        executionStatus: m.execution_status,
+        worktreeBranch: m.worktree_branch,
+        prompt: m.prompt,
+        model: m.model,
+        planApproval: m.plan_approval,
+        timeCreated: m.time_created,
+        timeUpdated: m.time_updated,
+      })),
+      tasks: (taskStmt.all(t.id) as TaskRow[]).map((tk) => ({
+        id: tk.id,
+        content: tk.content,
+        status: tk.status,
+        priority: tk.priority,
+        assignee: tk.assignee,
+        dependsOn: tk.depends_on,
+        timeCreated: tk.time_created,
+        timeUpdated: tk.time_updated,
+      })),
+      messages: (msgStmt.all(t.id) as MessageRow[]).map((msg) => ({
+        id: msg.id,
+        fromName: msg.from_name,
+        toName: msg.to_name,
+        content: msg.content,
+        delivered: msg.delivered === 1,
+        read: msg.read === 1,
+        timeCreated: msg.time_created,
+      })),
+    })),
+  }
+}
+
+/**
+ * Start the dashboard HTTP server.
+ * Serves a JSON API for team state and the dashboard HTML.
+ * Singleton: if the port is already in use by another ensemble instance, skips silently.
+ * Returns the server instance, or null if skipped.
+ */
+export async function startDashboard(db: Database, port: number): Promise<ReturnType<typeof Bun.serve> | null> {
+  try {
+    const server = Bun.serve({
+      port,
+      fetch(req) {
+        const url = new URL(req.url)
+
+        if (url.pathname === "/api/health") {
+          return jsonResponse({ ensemble: true, pid: process.pid })
+        }
+
+        if (url.pathname === "/api/state") {
+          return jsonResponse(buildState(db))
+        }
+
+        if (url.pathname === "/") {
+          return new Response(DASHBOARD_HTML, {
+            headers: { "Content-Type": "text/html" },
+          })
+        }
+
+        return new Response("Not Found", { status: 404 })
+      },
+    })
+    log(`dashboard:started port=${port} url=http://localhost:${port}`)
+    return server
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
+      try {
+        const res = await fetch(`http://localhost:${port}/api/health`)
+        const data = await res.json() as { ensemble?: boolean; pid?: number }
+        if (data.ensemble && data.pid) {
+          // Check if the other process is still alive
+          let alive = false
+          try { process.kill(data.pid, 0); alive = true } catch { /* process is dead */ }
+          if (alive && data.pid !== process.pid) {
+            log(`dashboard:already-running port=${port} pid=${data.pid}`)
+            return null
+          }
+          // Stale server from a dead process — warn the user
+          log(`dashboard:stale-server port=${port} stale-pid=${data.pid} — run: kill -9 ${data.pid} || lsof -ti:${port} | xargs kill -9`)
+          return null
+        }
+      } catch { /* health check failed — port held by something else */ }
+      log(`dashboard:port-in-use port=${port} (not an ensemble instance)`)
+      return null
+    }
+    log(`dashboard:failed err=${err instanceof Error ? err.message : String(err)}`)
+    return null
+  }
+}

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"
@@ -15,12 +15,14 @@ import { log, initLog } from "./log"
 import { findTeamBySession } from "./types"
 import { loadConfig } from "./config"
 import { ProgressTracker } from "./progress"
+import { startDashboard } from "./dashboard"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
 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 +73,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,7 +90,17 @@ 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")
+
+    // Start dashboard server (main instance only, not worktree instances)
+    if (config.dashboardPort !== 0) {
+      startDashboard(db, config.dashboardPort).catch((err) => {
+        log(`init:dashboard:failed err=${err instanceof Error ? err.message : String(err)}`)
+      })
+    }
   } else {
     log(`init:skip-recovery (worktree instance: ${input.directory})`)
   }
@@ -109,6 +121,7 @@ const plugin: Plugin = async (input) => {
     stallThresholdMs: config.stallThresholdMs,
     stallMinSteps: config.stallMinSteps,
     stallTokenThreshold: config.stallTokenThreshold,
+    cwd: input.directory,
   })
   watchdog.start()
 
@@ -150,12 +163,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 +434,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}`
+}