@hueyexe/opencode-ensemble 0.13.2 → 0.14.0

package/README.md

@@ -6,7 +6,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
 [![npm downloads](https://img.shields.io/npm/dm/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
-[![tests](https://img.shields.io/badge/tests-508%20passing-brightgreen.svg)]()
+[![tests](https://img.shields.io/badge/tests-558%20passing-brightgreen.svg)]()
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)]()
 [![OpenCode SDK](https://img.shields.io/badge/deps-OpenCode%20SDK%20only-blue.svg)]()
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
@@ -19,7 +19,7 @@ Plugin built on the public OpenCode SDK. No internal dependencies.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.13.2"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.14.0"]
 }
 ```
 
@@ -140,7 +140,7 @@ Add to your OpenCode config with a pinned version. Project-level or global.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.13.2"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.14.0"]
 }
 ```
 
@@ -148,7 +148,7 @@ Add to your OpenCode config with a pinned version. Project-level or global.
 
 ```json
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.13.2"]
+  "plugin": ["@hueyexe/opencode-ensemble@0.14.0"]
 }
 ```
 
@@ -198,7 +198,7 @@ Build with `bun run build`, then restart OpenCode to pick up changes.
 
 14 tools. The lead has all of them. Teammates get 6 (messaging + tasks).
 
-**Team lifecycle** (lead only)
+**Team lifecycle** (lead only, except archived-team purge may also be run from the main session)
 
 | Tool | What it does |
 |------|-------------|
@@ -206,10 +206,12 @@ Build with `bun run build`, then restart OpenCode to pick up changes.
 | `team_spawn` | Start a new teammate with a task. Supports `plan_approval` mode. |
 | `team_shutdown` | Ask a teammate to stop. Preserves their branch before aborting. Supports `force` flag. |
 | `team_merge` | Merge a shutdown teammate's branch into working directory (unstaged). Blocks if you have local changes to overlapping files. |
-| `team_cleanup` | Remove the team when done. Safety-net merges any forgotten branches. |
+| `team_cleanup` | Remove the current team when done. Safety-net merges forgotten branches. With `purge`, previews archived-team deletion and returns exact approval labels plus a confirmation token. |
 | `team_status` | See all members, their status, and a task summary. |
 | `team_view` | Switch the TUI to a teammate's session. |
 
+Archived-team purge is intentionally two-step. First call `team_cleanup` with `purge` to get a preview, exact approval and denial option labels, and `confirm_token`; no data is deleted. Stale archived worktree/workspace references and stale Ensemble-owned branches are counted in the preview and cleaned during confirmed purge. Arbitrary non-Ensemble branches still block purge for safety. The lead must then use the question tool with those exact options. Only after the user selects the exact approval option should it call `team_cleanup` again with the same `purge`, `confirm_purge: true`, and the preview token.
+
 **Communication** (everyone)
 
 | Tool | What it does |
@@ -410,7 +412,7 @@ Same coordination model (shared tasks, peer messaging, lead coordination) with s
 ```bash
 bun install
 bun run typecheck
-bun test             # 508 tests
+bun test             # 558 tests
 bun run build
 ```
 

package/dist/index.js

@@ -15697,6 +15697,8 @@ async function recoverOrphanedBranches(db, cwd) {
 }
 
 // src/state.ts
+import { randomUUID } from "crypto";
+
 class MemberRegistry {
   bySession = new Map;
   byTeamName = new Map;
@@ -15740,6 +15742,36 @@ class MemberRegistry {
   }
 }
 var DEFAULT_MAX_DEPTH = 10;
+var DEFAULT_PURGE_APPROVAL_TTL_MS = 10 * 60 * 1000;
+function canonicalPurgeKey(purge) {
+  if (purge.includes("*"))
+    return JSON.stringify(["*"]);
+  return JSON.stringify([...new Set(purge)].sort());
+}
+function outputSelectedAnswer(output, label) {
+  const quoted = JSON.stringify(label);
+  return output.includes(`=${quoted}`) || output.includes(`=[${quoted}]`);
+}
+function optionLabels(args) {
+  if (!args || typeof args !== "object")
+    return [];
+  const questions = args.questions;
+  if (!Array.isArray(questions))
+    return [];
+  return questions.flatMap((question) => {
+    if (!question || typeof question !== "object")
+      return [];
+    const options = question.options;
+    if (!Array.isArray(options))
+      return [];
+    return options.flatMap((option) => {
+      if (!option || typeof option !== "object")
+        return [];
+      const label = option.label;
+      return typeof label === "string" ? [label] : [];
+    });
+  });
+}
 
 class DescendantTracker {
   parents = new Map;
@@ -15766,6 +15798,65 @@ class DescendantTracker {
   }
 }
 
+class PendingPurgeApprovals {
+  pending = new Map;
+  ttlMs;
+  now;
+  createToken;
+  constructor(ttlMs = DEFAULT_PURGE_APPROVAL_TTL_MS, now = () => Date.now(), createToken = randomUUID) {
+    this.ttlMs = ttlMs;
+    this.now = now;
+    this.createToken = createToken;
+  }
+  create(sessionId, purge) {
+    this.pruneExpired();
+    const token = this.createToken();
+    this.pending.set(token, {
+      sessionId,
+      purgeKey: canonicalPurgeKey(purge),
+      approved: false,
+      timeCreated: this.now()
+    });
+    return token;
+  }
+  approvalLabel(token) {
+    return `Approve purge ${token.slice(0, 8)}`;
+  }
+  denialLabel(token) {
+    return `Deny purge ${token.slice(0, 8)}`;
+  }
+  recordQuestionAnswer(sessionId, output, args) {
+    this.pruneExpired();
+    const labels = new Set(optionLabels(args));
+    for (const [token, approval] of this.pending.entries()) {
+      const approvalLabel = this.approvalLabel(token);
+      const denialLabel = this.denialLabel(token);
+      const hasRequiredOptions = labels.has(approvalLabel) && labels.has(denialLabel);
+      if (approval.sessionId === sessionId && hasRequiredOptions && outputSelectedAnswer(output, approvalLabel)) {
+        approval.approved = true;
+      }
+    }
+  }
+  consume(sessionId, token, purge) {
+    this.pruneExpired();
+    const approval = this.pending.get(token);
+    if (!approval || approval.sessionId !== sessionId || approval.purgeKey !== canonicalPurgeKey(purge)) {
+      throw new Error("Purge confirmation token is invalid or expired.");
+    }
+    if (!approval.approved) {
+      throw new Error("Purge was not approved by the user. Use the question tool with the exact approval option from the preview before confirming.");
+    }
+    this.pending.delete(token);
+  }
+  pruneExpired() {
+    const cutoff = this.now() - this.ttlMs;
+    for (const [token, approval] of this.pending.entries()) {
+      if (approval.timeCreated < cutoff)
+        this.pending.delete(token);
+    }
+  }
+}
+
 // src/hooks.ts
 var TEAM_TOOL_PREFIX = "team_";
 function handleSessionStatusEvent(db, registry2, sessionId, status) {
@@ -15983,7 +16074,7 @@ function buildLeadSystemPrompt(db, teamId, config2) {
     }
     lines.push(`If user picks "I'll choose per agent", ask for each agent's model individually before each team_spawn call.`, "Pass the chosen model via the model parameter on each team_spawn call.");
   }
-  lines.push("", "Spawn teammates ONE AT A TIME. Wait for each tool result before spawning the next.", "This avoids git worktree contention. Once all are spawned, wait for their messages.", "", "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.", "", "MERGE WORKFLOW:", "After a teammate finishes and you shut them down, use team_merge to merge their branch.", "Do NOT tell teammates to commit \u2014 they handle that themselves.", "Do NOT run git merge manually \u2014 use team_merge which squash-merges and unstages for you.", "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 \u2014 merge or commit first.");
+  lines.push("", "Spawn teammates ONE AT A TIME. Wait for each tool result before spawning the next.", "This avoids git worktree contention. Once all are spawned, wait for their messages.", "Read-only agents (explore, plan) automatically skip worktree creation.", "For other agents that only need to read, pass worktree: false to avoid unnecessary isolation.", "", "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.", "", "MERGE WORKFLOW:", "After a teammate finishes and you shut them down, use team_merge to merge their branch.", "Do NOT tell teammates to commit \u2014 they handle that themselves.", "Do NOT run git merge manually \u2014 use team_merge which squash-merges and unstages for you.", "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 \u2014 merge or commit first.", 'To permanently delete archived teams, call team_cleanup with purge: ["team-name"] or purge: ["*"] for all archived teams.', "The first purge call is preview-only and deletes nothing.", "Use the question tool to ask the user for visible human approval before deleting archived team records or preserved Ensemble branches.", "The question must include the exact approval and denial option labels shown in the preview.", "Only if the user selects that exact approval option, call team_cleanup again with the same purge value, confirm_purge: true, and the confirm_token from the preview.");
   return lines.join(`
 `);
 }
@@ -17013,6 +17104,28 @@ function requireTeamMember(deps, sessionId) {
     throw new Error("This session is not in a team.");
   return teamInfo;
 }
+function requireCanPurgeArchivedTeams(deps, sessionId) {
+  const activeMembers = deps.db.query(`SELECT tm.session_id
+     FROM team_member tm
+     JOIN team t ON tm.team_id = t.id
+     WHERE t.status = 'active'`).all();
+  if (activeMembers.some((member) => member.session_id === sessionId)) {
+    throw new Error("Team members cannot purge archived teams");
+  }
+  const activeLeads = deps.db.query("SELECT lead_session_id FROM team WHERE status = 'active'").all();
+  if (deps.tracker.getParent(sessionId)) {
+    throw new Error("Sub-agents cannot purge archived teams");
+  }
+  if (activeLeads.some((team) => team.lead_session_id === sessionId))
+    return;
+  const activeTeamSessions = new Set([
+    ...activeMembers.map((member) => member.session_id),
+    ...activeLeads.map((team) => team.lead_session_id)
+  ]);
+  if (deps.tracker.isDescendantOf(sessionId, activeTeamSessions)) {
+    throw new Error("Sub-agents cannot purge archived teams");
+  }
+}
 
 // src/tools/team-spawn.ts
 var spawnFailures = new Map;
@@ -17064,7 +17177,8 @@ async function executeTeamSpawn(deps, args, sessionId) {
   const existing = deps.db.query("SELECT name FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.name);
   if (existing)
     throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`);
-  const useWorktree = args.worktree !== false && !isWorktreeDirectory(deps.directory);
+  const isReadOnly = args.agent === "plan" || args.agent === "explore";
+  const useWorktree = args.worktree !== false && !isReadOnly && !isWorktreeDirectory(deps.directory);
   const usePlanApproval = args.plan_approval === true;
   log(`spawn:start name=${args.name} agent=${args.agent} worktree=${useWorktree}`);
   let worktreeDir = null;
@@ -17104,7 +17218,6 @@ async function executeTeamSpawn(deps, args, sessionId) {
       log(`spawn:workspace:failed name=${args.name} err=${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  const isReadOnly = args.agent === "plan" || args.agent === "explore";
   const TEAM_TOOLS = ["team_message", "team_broadcast", "team_tasks_list", "team_tasks_add", "team_tasks_complete", "team_claim"];
   const permission = [];
   if (worktreeDir) {
@@ -17467,7 +17580,340 @@ ${parts.join(`
 
 // src/tools/team-cleanup.ts
 init_merge_helper();
-async function executeTeamCleanup(deps, args, sessionId, isDirty = checkWorktreeDirty, merge2 = mergeBranch, delBranch = deleteBranch, mergeOnCleanup = true, overlapCheck = getOverlappingFiles) {
+async function listPreservedBranches(teamName, cwd) {
+  try {
+    const proc = Bun.spawn(["git", "branch", "--list", `ensemble/preserved/${teamName}/*`, "--format", "%(refname:short)"], { cwd, stdout: "pipe", stderr: "pipe" });
+    const out = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const exit = await proc.exited;
+    if (exit !== 0)
+      throw new Error(stderr.trim() || `git branch exited with code ${exit}`);
+    return out.split(`
+`).map((branch) => branch.trim()).filter(Boolean);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("not a git repository"))
+      return [];
+    throw new Error(`Failed to list preserved branches for ${teamName}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function branchExists(branch, cwd) {
+  try {
+    const proc = Bun.spawn(["git", "branch", "--list", branch, "--format", "%(refname:short)"], { cwd, stdout: "pipe", stderr: "pipe" });
+    const out = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const exit = await proc.exited;
+    if (exit !== 0) {
+      if (stderr.includes("not a git repository"))
+        return false;
+      throw new Error(stderr.trim() || `git branch exited with code ${exit}`);
+    }
+    return out.split(`
+`).map((item) => item.trim()).includes(branch);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("not a git repository"))
+      return false;
+    throw new Error(`Failed to check stale Ensemble branch ${branch}: ${message}`);
+  }
+}
+function normalizeBranchName(branch) {
+  return branch.trim().replace(/^\*\s*/, "");
+}
+function resolvePurgeTargets(deps, purge) {
+  if (purge.length === 0)
+    throw new Error("Pass at least one archived team name to purge, or ['*'] for all archived teams.");
+  if (purge.includes("*") && purge.length !== 1) {
+    throw new Error("Wildcard purge cannot be combined with explicit team names. Use purge: ['*'] by itself.");
+  }
+  if (purge.includes("*")) {
+    return deps.db.query("SELECT id, name, time_updated FROM team WHERE status = 'archived' ORDER BY time_updated DESC, name ASC").all();
+  }
+  const uniqueNames = [...new Set(purge)];
+  const rows = uniqueNames.map((name) => ({
+    name,
+    team: deps.db.query("SELECT id, name, status, time_updated FROM team WHERE name = ?").get(name)
+  }));
+  const missing = rows.filter((row) => row.team === null).map((row) => row.name);
+  if (missing.length > 0)
+    throw new Error(`Team not found: ${missing.join(", ")}`);
+  const active = rows.filter((row) => row.team?.status === "active").map((row) => row.name);
+  if (active.length > 0)
+    throw new Error(`Cannot purge active team: ${active.join(", ")}`);
+  return rows.map((row) => row.team).sort((a, b) => b.time_updated - a.time_updated || a.name.localeCompare(b.name));
+}
+function deleteArchivedTeams(deps, targets) {
+  const transaction = deps.db.transaction((teams) => {
+    teams.forEach((team) => {
+      const row = deps.db.query("SELECT status FROM team WHERE id = ?").get(team.id);
+      if (!row)
+        throw new Error(`Team not found: ${team.name}`);
+      if (row.status === "active")
+        throw new Error(`Cannot purge active team: ${team.name}`);
+    });
+    validatePurgeResources(deps, teams);
+    teams.forEach((team) => {
+      deps.db.run("DELETE FROM team WHERE id = ? AND status = 'archived'", [team.id]);
+    });
+  });
+  transaction(targets);
+  targets.forEach((team) => {
+    deps.registry.unregisterTeam(team.id);
+    spawnFailures.delete(team.id);
+  });
+}
+function getPurgeMemberResources(deps, targets) {
+  return targets.flatMap((target) => deps.db.query(`SELECT t.name as team_name,
+            tm.team_id,
+            tm.name as member_name,
+            tm.worktree_dir,
+            tm.workspace_id,
+            tm.worktree_branch
+     FROM team_member tm
+     JOIN team t ON tm.team_id = t.id
+     WHERE tm.team_id = ?`).all(target.id));
+}
+function preservedBranchPrefix(resource) {
+  return `ensemble/preserved/${resource.team_name}/`;
+}
+function staleEnsembleBranchNames(resource) {
+  return [
+    `ensemble-${resource.team_name}-${resource.member_name}`,
+    `opencode/ensemble-${resource.team_name}-${resource.member_name}`
+  ];
+}
+function isPreservedBranch(resource) {
+  return resource.worktree_branch !== null && resource.worktree_branch.startsWith(preservedBranchPrefix(resource));
+}
+function isStaleEnsembleBranch(resource) {
+  return resource.worktree_branch !== null && staleEnsembleBranchNames(resource).includes(resource.worktree_branch);
+}
+function validatePurgeResources(deps, targets) {
+  const resources = getPurgeMemberResources(deps, targets);
+  const nonPreserved = resources.filter((resource) => resource.worktree_branch !== null && !isPreservedBranch(resource) && !isStaleEnsembleBranch(resource));
+  if (nonPreserved.length > 0) {
+    const details = nonPreserved.map((resource) => `${resource.team_name}/${resource.member_name} (${resource.worktree_branch})`).join(", ");
+    throw new Error(`Cannot purge archived teams: ${details} has a non-preserved worktree branch or a branch outside its preserved namespace.`);
+  }
+  const activeResourceRefs = resources.flatMap((resource) => {
+    const worktreeRefs = resource.worktree_dir ? deps.db.query(`SELECT t.name as team_name, tm.name as member_name
+         FROM team_member tm
+         JOIN team t ON tm.team_id = t.id
+         WHERE t.status = 'active' AND tm.worktree_dir = ?`).all(resource.worktree_dir) : [];
+    const workspaceRefs = resource.workspace_id ? deps.db.query(`SELECT t.name as team_name, tm.name as member_name
+         FROM team_member tm
+         JOIN team t ON tm.team_id = t.id
+         WHERE t.status = 'active' AND tm.workspace_id = ?`).all(resource.workspace_id) : [];
+    return [
+      ...worktreeRefs.map((ref) => `${resource.team_name}/${resource.member_name} worktree is also referenced by active team ${ref.team_name}/${ref.member_name}`),
+      ...workspaceRefs.map((ref) => `${resource.team_name}/${resource.member_name} workspace is also referenced by active team ${ref.team_name}/${ref.member_name}`)
+    ];
+  });
+  if (activeResourceRefs.length > 0) {
+    throw new Error(`Cannot purge archived teams: ${[...new Set(activeResourceRefs)].join(", ")}.`);
+  }
+}
+function collectStaleEnsembleBranches(deps, targets) {
+  return [...new Set(getPurgeMemberResources(deps, targets).filter(isStaleEnsembleBranch).map((resource) => resource.worktree_branch))];
+}
+function countStaleResourceRefs(deps, target) {
+  return getPurgeMemberResources(deps, [target]).reduce((count, resource) => count + (resource.worktree_dir ? 1 : 0) + (resource.workspace_id ? 1 : 0), 0);
+}
+function countStaleBranchRefs(deps, target) {
+  return collectStaleEnsembleBranches(deps, [target]).length;
+}
+async function existingWorktreeDirs(deps, resources) {
+  if (!resources.some((resource) => resource.worktree_dir))
+    return new Set;
+  try {
+    const result = await deps.client.worktree.list();
+    return new Set((result.data ?? []).map((worktree) => worktree.directory));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot purge archived teams: failed to list worktrees before stale resource cleanup: ${message}`);
+  }
+}
+async function existingWorkspaceIds(deps, resources) {
+  if (!resources.some((resource) => resource.workspace_id))
+    return new Set;
+  try {
+    const result = await deps.client.workspace.list();
+    return new Set((result.data ?? []).map((workspace) => workspace.id));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot purge archived teams: failed to list workspaces before stale resource cleanup: ${message}`);
+  }
+}
+async function cleanupStalePurgeResources(deps, targets, isDirty) {
+  const resources = getPurgeMemberResources(deps, targets).filter((resource) => resource.worktree_dir || resource.workspace_id);
+  if (resources.length === 0)
+    return;
+  const worktreeDirs = await existingWorktreeDirs(deps, resources);
+  const workspaceIds = await existingWorkspaceIds(deps, resources);
+  for (const resource of resources) {
+    if (resource.workspace_id) {
+      if (workspaceIds.has(resource.workspace_id)) {
+        try {
+          await deps.client.workspace.remove({ id: resource.workspace_id });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          throw new Error(`Failed to remove stale workspace for ${resource.team_name}/${resource.member_name}: ${message}`);
+        }
+      }
+      deps.db.run("UPDATE team_member SET workspace_id = NULL WHERE team_id = ? AND name = ?", [resource.team_id, resource.member_name]);
+    }
+    if (resource.worktree_dir) {
+      if (worktreeDirs.has(resource.worktree_dir)) {
+        let dirty;
+        try {
+          dirty = await isDirty(resource.worktree_dir);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          throw new Error(`Cannot purge archived teams: failed to check archived worktree for uncommitted changes at ${resource.worktree_dir}: ${message}`);
+        }
+        if (dirty) {
+          throw new Error(`Cannot purge archived teams: ${resource.team_name}/${resource.member_name} has uncommitted changes in archived worktree ${resource.worktree_dir}.`);
+        }
+        try {
+          await deps.client.worktree.remove({ worktreeRemoveInput: { directory: resource.worktree_dir } });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          throw new Error(`Failed to remove stale worktree for ${resource.team_name}/${resource.member_name}: ${message}`);
+        }
+      }
+      deps.db.run("UPDATE team_member SET worktree_dir = NULL WHERE team_id = ? AND name = ?", [resource.team_id, resource.member_name]);
+    }
+  }
+}
+async function deleteStaleEnsembleBranches(branches, cwd, delBranch, exists) {
+  for (const branch of branches) {
+    if (!await exists(branch, cwd))
+      continue;
+    const ok = await delBranch(branch, cwd);
+    if (!ok)
+      throw new Error(`Failed to delete stale Ensemble branch: ${branch}`);
+  }
+}
+function validatePurgeTargetsStillArchived(deps, targets) {
+  const missing = [];
+  const active = [];
+  targets.forEach((target) => {
+    const row = deps.db.query("SELECT status FROM team WHERE id = ?").get(target.id);
+    if (!row)
+      missing.push(target.name);
+    else if (row.status === "active")
+      active.push(target.name);
+  });
+  if (missing.length > 0)
+    throw new Error(`Team not found: ${missing.join(", ")}`);
+  if (active.length > 0)
+    throw new Error(`Cannot purge active team: ${active.join(", ")}`);
+}
+async function collectPreservedBranches(targets, cwd, listBranches) {
+  const entries = await Promise.all(targets.map(async (target) => {
+    const prefix = `ensemble/preserved/${target.name}/`;
+    let listed;
+    try {
+      listed = await listBranches(target.name, cwd);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes("not a git repository"))
+        listed = [];
+      else
+        throw new Error(`Failed to list preserved branches for ${target.name}: ${message}`);
+    }
+    const branches = listed.map(normalizeBranchName).filter((branch) => branch.startsWith(prefix));
+    return [target.id, [...new Set(branches)]];
+  }));
+  return new Map(entries);
+}
+async function deletePreservedBranches(branchesByTeam, cwd, delBranch) {
+  const branches = [...branchesByTeam.values()].flat();
+  for (const branch of branches) {
+    const ok = await delBranch(branch, cwd);
+    if (!ok)
+      throw new Error(`Failed to delete preserved branch: ${branch}`);
+  }
+}
+function formatCount(count, noun, plural = `${noun}s`) {
+  return `${count} ${count === 1 ? noun : plural}`;
+}
+function buildPurgePreview(deps, targets, branchesByTeam) {
+  const rows = targets.map((target) => {
+    const members = deps.db.query("SELECT COUNT(*) as c FROM team_member WHERE team_id = ?").get(target.id).c;
+    const tasks = deps.db.query("SELECT COUNT(*) as c FROM team_task WHERE team_id = ?").get(target.id).c;
+    const messages = deps.db.query("SELECT COUNT(*) as c FROM team_message WHERE team_id = ?").get(target.id).c;
+    const branches = branchesByTeam.get(target.id)?.length ?? 0;
+    const staleResources = countStaleResourceRefs(deps, target);
+    const staleBranches = countStaleBranchRefs(deps, target);
+    return { ...target, members, tasks, messages, branches, staleResources, staleBranches };
+  });
+  const totals = rows.reduce((acc, row) => ({
+    members: acc.members + row.members,
+    tasks: acc.tasks + row.tasks,
+    messages: acc.messages + row.messages,
+    branches: acc.branches + row.branches,
+    staleResources: acc.staleResources + row.staleResources,
+    staleBranches: acc.staleBranches + row.staleBranches
+  }), { members: 0, tasks: 0, messages: 0, branches: 0, staleResources: 0, staleBranches: 0 });
+  const details = rows.slice(0, 10).map((row) => `- ${row.name}: ${formatCount(row.members, "member")}, ${formatCount(row.tasks, "task")}, ${formatCount(row.messages, "message")}, ${formatCount(row.branches, "preserved branch", "preserved branches")}, ${formatCount(row.staleResources, "stale resource")}, ${formatCount(row.staleBranches, "stale branch", "stale branches")}`);
+  const hidden = rows.length > 10 ? [`...and ${rows.length - 10} more archived team${rows.length - 10 === 1 ? "" : "s"}`] : [];
+  return [
+    "Permanently delete archived teams?",
+    "This will delete archived team records and cascade-delete their members, tasks, and messages.",
+    "",
+    ...details,
+    ...hidden,
+    "",
+    `Total: ${formatCount(rows.length, "team")}, ${formatCount(totals.members, "member")}, ${formatCount(totals.tasks, "task")}, ${formatCount(totals.messages, "message")}, ${formatCount(totals.branches, "preserved branch", "preserved branches")}, ${formatCount(totals.staleResources, "stale resource")}, ${formatCount(totals.staleBranches, "stale branch", "stale branches")}`
+  ].join(`
+`);
+}
+function buildPurgeConfirmationInstructions(preview, confirmToken) {
+  const approvalLabel = `Approve purge ${confirmToken.slice(0, 8)}`;
+  const denialLabel = `Deny purge ${confirmToken.slice(0, 8)}`;
+  return [
+    "Purge preview only \u2014 no teams were deleted.",
+    "",
+    preview,
+    "",
+    "Use the question tool to ask the user whether to permanently delete these archived teams.",
+    `The approval option label must be exactly: ${approvalLabel}`,
+    `The denial option label must be exactly: ${denialLabel}`,
+    `Confirmation token: ${confirmToken}`,
+    `Only if the user selects "${approvalLabel}", call team_cleanup again with the same purge value, confirm_purge: true, and confirm_token set to this token.`
+  ].join(`
+`);
+}
+async function executeTeamCleanup(deps, args, sessionId, isDirty = checkWorktreeDirty, merge2 = mergeBranch, delBranch = deleteBranch, mergeOnCleanup = true, overlapCheck = getOverlappingFiles, _approvePurge, _listBranches, _branchExists) {
+  if (args.purge && args.purge.length > 0) {
+    requireCanPurgeArchivedTeams(deps, sessionId);
+    const targets = resolvePurgeTargets(deps, args.purge);
+    if (targets.length === 0)
+      return "No archived teams to purge.";
+    validatePurgeTargetsStillArchived(deps, targets);
+    validatePurgeResources(deps, targets);
+    const branchesByTeam = await collectPreservedBranches(targets, deps.directory, _listBranches ?? listPreservedBranches);
+    const preview = buildPurgePreview(deps, targets, branchesByTeam);
+    if (!args.confirm_purge) {
+      const confirmToken = deps.purgeApprovals.create(sessionId, targets.map((target) => target.id));
+      return buildPurgeConfirmationInstructions(preview, confirmToken);
+    }
+    if (!args.confirm_token) {
+      throw new Error("A purge confirmation token is required. First call team_cleanup without confirm_purge, then use the question tool before confirming.");
+    }
+    deps.purgeApprovals.consume(sessionId, args.confirm_token, targets.map((target) => target.id));
+    validatePurgeTargetsStillArchived(deps, targets);
+    validatePurgeResources(deps, targets);
+    await cleanupStalePurgeResources(deps, targets, isDirty);
+    validatePurgeResources(deps, targets);
+    await deleteStaleEnsembleBranches(collectStaleEnsembleBranches(deps, targets), deps.directory, delBranch, _branchExists ?? branchExists);
+    const finalBranchesByTeam = await collectPreservedBranches(targets, deps.directory, _listBranches ?? listPreservedBranches);
+    await deletePreservedBranches(finalBranchesByTeam, deps.directory, delBranch);
+    deleteArchivedTeams(deps, targets);
+    const noun = targets.length === 1 ? "archived team" : "archived teams";
+    return `Permanently deleted ${targets.length} ${noun}: ${targets.map((target) => target.name).join(", ")}.`;
+  }
   const teamInfo = requireLead(deps, sessionId);
   const members = deps.db.query("SELECT name, session_id, status, worktree_dir, worktree_branch, workspace_id FROM team_member WHERE team_id = ?").all(teamInfo.teamId);
   const active = members.filter((m) => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error");
@@ -18067,6 +18513,7 @@ var plugin = async (input) => {
   const config2 = loadConfig(input.directory);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
+  const purgeApprovals = new PendingPurgeApprovals;
   const nudgedMembers = new Set;
   const progressTracker = new ProgressTracker;
   const wakeLeadTimestamps = new Map;
@@ -18075,7 +18522,7 @@ var plugin = async (input) => {
   const rawClient = new OpencodeClient({ client: pluginTransport });
   initLog(rawClient);
   const client3 = wrapThrowingClient(rawClient);
-  const deps = { db, registry: registry2, tracker, client: client3, directory: input.directory, config: config2 };
+  const deps = { db, registry: registry2, tracker, purgeApprovals, client: client3, directory: input.directory, config: config2 };
   if (!isWorktreeInstance(input.directory)) {
     log("init:recovery:start (main instance)");
     const recovery = await recoverStaleMembers(db, client3, input.directory);
@@ -18258,6 +18705,11 @@ var plugin = async (input) => {
         }
       }
     },
+    "tool.execute.after": async (input2, output) => {
+      if (input2.tool === "question") {
+        purgeApprovals.recordQuestionAnswer(input2.sessionID, output.output, input2.args);
+      }
+    },
     "experimental.chat.system.transform": async (input2, output) => {
       if (!input2.sessionID)
         return;
@@ -18430,15 +18882,30 @@ var plugin = async (input) => {
         }
       }),
       team_cleanup: tool({
-        description: "Clean up the team. All teammates must be shut down first. Removes team data and frees resources.",
+        description: "Clean up the current team, or purge archived teams after human approval. Omit purge for normal cleanup. Pass purge with archived team names, or ['*'] for all archived teams. First purge call returns a preview, exact approval and denial options, and confirmation token only. Archived worktree/workspace references and stale Ensemble-owned branches are shown in the preview and cleaned during confirmed purge. Use the question tool with those exact options, then call again with confirm_purge: true and confirm_token only if the user selected the exact approval option.",
         args: {
           force: tool.schema.boolean().default(false).describe("Force cleanup even if members are active (will abort them)"),
-          acknowledge_uncommitted: tool.schema.boolean().default(false)
+          acknowledge_uncommitted: tool.schema.boolean().default(false),
+          purge: tool.schema.array(tool.schema.string()).optional().describe("Archived team names to permanently delete, or ['*'] for all archived teams. Requires human approval."),
+          confirm_purge: tool.schema.boolean().default(false).describe("Set true only after the user explicitly selects the exact approval option from the purge preview via the question tool."),
+          confirm_token: tool.schema.string().optional().describe("Confirmation token from the purge preview. Valid only after the matching exact approval answer is selected in this session.")
         },
         async execute(args, ctx) {
-          const result = await executeTeamCleanup(deps, args, ctx.sessionID, undefined, undefined, undefined, config2.mergeOnCleanup);
+          const approvePurge = args.purge && args.purge.length > 0 && args.confirm_purge ? async (preview) => {
+            await ctx.ask({
+              permission: "team_cleanup.purge",
+              patterns: args.purge ?? [],
+              always: [],
+              metadata: {
+                title: "Purge archived teams",
+                preview
+              }
+            });
+          } : undefined;
+          const result = await executeTeamCleanup(deps, args, ctx.sessionID, undefined, undefined, undefined, config2.mergeOnCleanup, undefined, approvePurge);
           const blocked = result.includes("uncommitted");
-          ctx.metadata({ title: blocked ? "Cleanup blocked \u2014 uncommitted changes" : "Team cleaned up" });
+          const title = args.purge ? result.startsWith("No archived teams") ? "No archived teams to purge" : result.startsWith("Purge preview") ? "Purge confirmation required" : "Archived teams purged" : blocked ? "Cleanup blocked \u2014 uncommitted changes" : "Team cleaned up";
+          ctx.metadata({ title });
           return result;
         }
       }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "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",