@hueyexe/opencode-ensemble 0.1.1 → 0.2.0

package/README.md

@@ -151,10 +151,11 @@ The plugin works within OpenCode's existing TUI. There's no custom team panel (t
 
 What you do get:
 
-- **Toast notifications** when teammates spawn, finish, error, or shut down
+- **Toast notifications** when teammates spawn, finish, error, shut down, or get rate-limited
+- **Working progress toasts** showing who's still active after every status change (e.g. "Working: alice, bob (2/3)")
 - **Rich tool titles** in the sidebar (e.g. "Spawned alice (build)", "Message -> bob", "Task board (3 tasks)")
 - **Session switching** via `team_view` to see any teammate's full chat log
-- **Status checks** via `team_status` for a snapshot of the whole team
+- **Status checks** via `team_status` for a snapshot of the whole team (also fires a toast)
 
 Teammate messages arrive in the lead's session as `[Team message from alice]: ...` blocks. They look like user messages in the TUI because that's how `promptAsync` delivery works. The content is clearly labeled with the sender's name.
 
@@ -163,7 +164,10 @@ Teammate messages arrive in the lead's session as `[Team message from alice]: ..
 - **SQLite** (`bun:sqlite`, WAL mode) for teams, members, tasks, and messages
 - **promptAsync** for message delivery: injects a message and starts the prompt loop in one call
 - **Sub-agent isolation**: teammates' sub-agents can't use team tools (parent chain tracking, max depth 10)
-- **Crash recovery**: stale busy members marked as errored on restart, undelivered messages redelivered
+- **Crash recovery**: stale busy members marked as errored on restart, orphaned sessions aborted, undelivered messages redelivered
+- **Spawn rollback**: if the initial prompt fails, the member is cleaned up and the session aborted
+- **Timeout watchdog**: teammates stuck busy beyond the TTL are automatically timed out and aborted
+- **Shutdown resilience**: abort failures handled gracefully, busy-after-shutdown triggers re-abort
 - **Rate limiting**: token bucket (configurable via `OPENCODE_ENSEMBLE_RATE_LIMIT`, default 10 tokens/sec)
 
 ## Configuration
@@ -174,6 +178,12 @@ OPENCODE_ENSEMBLE_RATE_LIMIT=20
 
 # Disable rate limiting
 OPENCODE_ENSEMBLE_RATE_LIMIT=0
+
+# Adjust teammate timeout (default: 1800000ms = 30 minutes)
+OPENCODE_ENSEMBLE_TIMEOUT=3600000
+
+# Disable timeout watchdog
+OPENCODE_ENSEMBLE_TIMEOUT=0
 ```
 
 ## Development

package/dist/index.js

@@ -12476,17 +12476,59 @@ function broadcastMessage(db, input) {
   db.run("INSERT INTO team_message (id, team_id, from_name, to_name, content, delivered, time_created) VALUES (?, ?, ?, NULL, ?, 0, ?)", [id, input.teamId, input.from, input.content, Date.now()]);
   return id;
 }
+function getUndeliveredMessages(db, teamId) {
+  return db.query("SELECT * FROM team_message WHERE team_id = ? AND delivered = 0 ORDER BY time_created ASC").all(teamId);
+}
 function markDelivered(db, messageId) {
   db.run("UPDATE team_message SET delivered = 1 WHERE id = ?", [messageId]);
 }
 
 // src/recovery.ts
-function recoverStaleMembers(db) {
+async function recoverStaleMembers(db, client) {
+  const stale = db.query(`SELECT tm.session_id FROM team_member tm
+     JOIN team t ON tm.team_id = t.id
+     WHERE tm.status = 'busy' AND t.status = 'active'`).all();
   const result = db.run(`UPDATE team_member SET status = 'error', execution_status = 'idle', time_updated = ?
      WHERE status = 'busy'
        AND team_id IN (SELECT id FROM team WHERE status = 'active')`, [Date.now()]);
+  if (client) {
+    for (const member of stale) {
+      try {
+        await client.session.abort({ path: { id: member.session_id } });
+      } catch {}
+    }
+  }
   return { interrupted: result.changes };
 }
+async function recoverUndeliveredMessages(db, client, registry2) {
+  const teams = db.query("SELECT id, lead_session_id FROM team WHERE status = 'active'").all();
+  let redelivered = 0;
+  for (const team of teams) {
+    const messages = getUndeliveredMessages(db, team.id);
+    for (const msg of messages) {
+      let recipientSessionId;
+      if (msg.to_name === "lead") {
+        recipientSessionId = team.lead_session_id;
+      } else if (msg.to_name) {
+        const entry = registry2.getByName(team.id, msg.to_name);
+        recipientSessionId = entry?.sessionId;
+      } else {
+        continue;
+      }
+      if (!recipientSessionId)
+        continue;
+      try {
+        await client.session.promptAsync({
+          path: { id: recipientSessionId },
+          body: { parts: [{ type: "text", text: `[Recovered team message from ${msg.from_name}]: ${msg.content}` }] }
+        });
+        markDelivered(db, msg.id);
+        redelivered++;
+      } catch {}
+    }
+  }
+  return { redelivered };
+}
 
 // src/state.ts
 class MemberRegistry {
@@ -12578,6 +12620,11 @@ function handleSessionStatusEvent(db, registry2, sessionId, status) {
       db.run("UPDATE team_member SET status = 'busy', execution_status = 'running', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), entry.teamId, entry.memberName]);
       return { memberName: entry.memberName, teamId: entry.teamId, from: member.status, to: "busy" };
     }
+    if (member.status === "shutdown_requested") {
+      return { memberName: entry.memberName, teamId: entry.teamId, from: "shutdown_requested", to: "busy_while_shutdown" };
+    }
+  } else if (status === "retry") {
+    return { memberName: entry.memberName, teamId: entry.teamId, from: member.status, to: "retry" };
   }
   return;
 }
@@ -12633,6 +12680,30 @@ async function notifyTeamEvent(client, type, data) {
     });
   } catch {}
 }
+async function notifyWorkingProgress(client, db, teamId) {
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamId);
+  if (members.length === 0)
+    return;
+  const busy = members.filter((m) => m.status === "busy");
+  try {
+    if (busy.length === 0) {
+      await client.tui.showToast({
+        title: "Team",
+        message: "All teammates finished",
+        variant: "success",
+        duration: 4000
+      });
+    } else {
+      const names = busy.map((m) => m.name).join(", ");
+      await client.tui.showToast({
+        title: "Team",
+        message: `Working: ${names} (${busy.length}/${members.length})`,
+        variant: "info",
+        duration: 5000
+      });
+    }
+  } catch {}
+}
 
 // src/types.ts
 function findTeamBySession(db, registry2, sessionId) {
@@ -12670,7 +12741,7 @@ async function executeTeamCreate(deps, args, sessionId) {
   const id = generateId("team");
   const now = Date.now();
   deps.db.run("INSERT INTO team (id, name, lead_session_id, status, delegate, time_created, time_updated) VALUES (?, ?, ?, 'active', 0, ?, ?)", [id, args.name, sessionId, now, now]);
-  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates.`;
+  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates. Teammates will message you when done \u2014 do not poll team_status repeatedly.`;
 }
 
 // src/tools/team-spawn.ts
@@ -12709,8 +12780,9 @@ async function executeTeamSpawn(deps, args, sessionId) {
     "- team_claim: claim a pending task from the shared board",
     "",
     "When you finish your task:",
-    "1. Send ONE message to the lead with your findings using team_message.",
-    "2. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
+    "1. If you claimed a task, mark it complete using team_tasks_complete.",
+    "2. Send ONE message to the lead with your findings using team_message.",
+    "3. 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.",
     "",
@@ -12718,13 +12790,26 @@ async function executeTeamSpawn(deps, args, sessionId) {
     "",
     "Your task:",
     args.prompt
-  ].join(`
+  ];
+  if (args.claim_task) {
+    context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`);
+  }
+  const contextStr = context.join(`
 `);
-  await deps.client.session.promptAsync({
-    path: { id: childSessionId },
-    body: { parts: [{ type: "text", text: context }] }
-  });
-  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""}`;
+  try {
+    await deps.client.session.promptAsync({
+      path: { id: childSessionId },
+      body: { parts: [{ type: "text", text: contextStr }] }
+    });
+  } catch (err) {
+    deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name]);
+    deps.registry.unregister(childSessionId);
+    try {
+      await deps.client.session.abort({ path: { id: childSessionId } });
+    } catch {}
+    throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""} Teammates will message you when done. Do not poll team_status to check.`;
 }
 
 // src/tools/team-message.ts
@@ -12783,7 +12868,9 @@ async function executeTeamBroadcast(deps, args, sessionId) {
       delivered++;
     } catch {}
   }
-  markDelivered(deps.db, msgId);
+  if (delivered > 0) {
+    markDelivered(deps.db, msgId);
+  }
   return `Broadcast sent to ${delivered} recipient${delivered !== 1 ? "s" : ""}.`;
 }
 
@@ -12800,7 +12887,18 @@ async function executeTeamShutdown(deps, args, sessionId) {
   if (member.status === "shutdown")
     throw new Error(`Teammate "${args.member}" is already shut down`);
   deps.db.run("UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), teamInfo.teamId, args.member]);
-  await deps.client.session.abort({ path: { id: member.session_id } });
+  try {
+    await deps.client.session.abort({ path: { id: member.session_id } });
+  } catch {
+    try {
+      await deps.client.tui.showToast({
+        title: "Team",
+        message: `Failed to abort ${args.member} session \u2014 will rely on event hook`,
+        variant: "warning",
+        duration: 4000
+      });
+    } catch {}
+  }
   try {
     const statuses = await deps.client.session.status();
     const sessionStatus = statuses.data?.[member.session_id];
@@ -12820,7 +12918,7 @@ async function executeTeamCleanup(deps, args, sessionId) {
   if (teamInfo.role !== "lead")
     throw new Error("Only the team lead can clean up the team.");
   const members = deps.db.query("SELECT name, session_id, status FROM team_member WHERE team_id = ?").all(teamInfo.teamId);
-  const active = members.filter((m) => m.status !== "shutdown");
+  const active = members.filter((m) => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error");
   if (active.length > 0 && !args.force) {
     const names = active.map((m) => m.name).join(", ");
     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.`);
@@ -12982,6 +13080,25 @@ async function executeTeamStatus(deps, sessionId) {
     lines.push("");
     lines.push(`Tasks: ${tasks.length} total (${parts.join(", ")})`);
   }
+  if (members.length > 0) {
+    const memberParts = members.map((m) => {
+      const label = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status;
+      return `${m.name} [${label}]`;
+    });
+    let toastMsg = memberParts.join(", ");
+    if (tasks.length > 0) {
+      const completed = tasks.filter((t) => t.status === "completed").length;
+      toastMsg += ` | Tasks: ${completed}/${tasks.length} done`;
+    }
+    try {
+      await deps.client.tui.showToast({
+        title: "Team",
+        message: toastMsg,
+        variant: "info",
+        duration: 4000
+      });
+    } catch {}
+  }
   return lines.join(`
 `);
 }
@@ -13061,25 +13178,86 @@ class TokenBucket {
   }
 }
 
+// src/watchdog.ts
+class Watchdog {
+  db;
+  client;
+  registry;
+  ttlMs;
+  checkIntervalMs;
+  timer;
+  constructor(opts) {
+    this.db = opts.db;
+    this.client = opts.client;
+    this.registry = opts.registry;
+    this.ttlMs = opts.ttlMs;
+    this.checkIntervalMs = opts.checkIntervalMs ?? 60000;
+  }
+  async check() {
+    if (this.ttlMs === 0)
+      return;
+    const cutoff = Date.now() - this.ttlMs;
+    const stale = this.db.query(`SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active'
+         AND tm.status = 'busy'
+         AND tm.time_updated < ?`).all(cutoff);
+    for (const member of stale) {
+      this.db.run("UPDATE team_member SET status = 'error', execution_status = 'timed_out', time_updated = ? WHERE team_id = ? AND name = ?", [Date.now(), member.team_id, member.name]);
+      try {
+        await this.client.session.abort({ path: { id: member.session_id } });
+      } catch {}
+      try {
+        await this.client.tui.showToast({
+          title: "Team",
+          message: `${member.name} timed out`,
+          variant: "warning",
+          duration: 5000
+        });
+      } catch {}
+    }
+  }
+  start() {
+    if (this.timer)
+      return;
+    if (this.ttlMs === 0)
+      return;
+    this.timer = setInterval(() => this.check(), this.checkIntervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+  isRunning() {
+    return this.timer !== undefined;
+  }
+}
+
 // src/index.ts
 var DEFAULT_RATE_LIMIT_CAPACITY = 10;
 var DEFAULT_RATE_LIMIT_REFILL = 2;
 var DEFAULT_RATE_LIMIT_INTERVAL_MS = 1000;
+var DEFAULT_WATCHDOG_TTL_MS = 30 * 60 * 1000;
+var DEFAULT_WATCHDOG_CHECK_MS = 60 * 1000;
 var plugin = async (input) => {
   const dbPath = getDbPath();
   mkdirSync(path2.dirname(dbPath), { recursive: true });
   const db = createDb(dbPath);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
-  const recovery = recoverStaleMembers(db);
+  const client = input.client;
+  const deps = { db, registry: registry2, tracker, client };
+  const recovery = await recoverStaleMembers(db, client);
   if (recovery.interrupted > 0) {
     const members = db.query("SELECT tm.team_id, tm.name, tm.session_id FROM team_member tm JOIN team t ON tm.team_id = t.id WHERE t.status = 'active'").all();
     for (const m of members) {
       registry2.register(m.team_id, m.name, m.session_id);
     }
   }
-  const client = input.client;
-  const deps = { db, registry: registry2, tracker, client };
+  recoverUndeliveredMessages(db, client, registry2).catch(() => {});
   const rateLimitEnv = process.env.OPENCODE_ENSEMBLE_RATE_LIMIT;
   const rateLimitCapacity = rateLimitEnv === "0" ? 0 : parseInt(rateLimitEnv ?? "", 10) || DEFAULT_RATE_LIMIT_CAPACITY;
   const rateLimiter = new TokenBucket({
@@ -13087,6 +13265,16 @@ var plugin = async (input) => {
     refillRate: DEFAULT_RATE_LIMIT_REFILL,
     refillIntervalMs: DEFAULT_RATE_LIMIT_INTERVAL_MS
   });
+  const timeoutEnv = process.env.OPENCODE_ENSEMBLE_TIMEOUT;
+  const watchdogTtl = timeoutEnv === "0" ? 0 : parseInt(timeoutEnv ?? "", 10) || DEFAULT_WATCHDOG_TTL_MS;
+  const watchdog = new Watchdog({
+    db,
+    client,
+    registry: registry2,
+    ttlMs: watchdogTtl,
+    checkIntervalMs: DEFAULT_WATCHDOG_CHECK_MS
+  });
+  watchdog.start();
   return {
     async event({ event }) {
       if (event.type === "session.status") {
@@ -13100,7 +13288,24 @@ var plugin = async (input) => {
             notifyTeamEvent(client, "completed", { memberName: transition.memberName });
           } else if (transition.to === "error") {
             notifyTeamEvent(client, "error", { memberName: transition.memberName });
+          } else if (transition.to === "retry") {
+            try {
+              await client.tui.showToast({
+                title: "Team",
+                message: `${transition.memberName} is being rate-limited`,
+                variant: "warning",
+                duration: 3000
+              });
+            } catch {}
+          } else if (transition.to === "busy_while_shutdown") {
+            const entry = registry2.getBySession(sessionID);
+            if (entry) {
+              try {
+                await client.session.abort({ path: { id: sessionID } });
+              } catch {}
+            }
           }
+          await notifyWorkingProgress(client, db, transition.teamId);
         }
       }
       if (event.type === "session.created") {

package/package.json

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

package/src/hooks.ts

@@ -50,6 +50,13 @@ export function handleSessionStatusEvent(
       )
       return { memberName: entry.memberName, teamId: entry.teamId, from: member.status, to: "busy" }
     }
+    // Session went busy while shutdown was requested — signal for re-abort
+    if (member.status === "shutdown_requested") {
+      return { memberName: entry.memberName, teamId: entry.teamId, from: "shutdown_requested", to: "busy_while_shutdown" }
+    }
+  } else if (status === "retry") {
+    // Session is being rate-limited — signal for toast but don't change state
+    return { memberName: entry.memberName, teamId: entry.teamId, from: member.status, to: "retry" }
   }
   return undefined
 }
@@ -71,7 +78,7 @@ export function handleSessionCreatedEvent(
 /**
  * Check whether a tool call should be blocked for sub-agent isolation.
  * Throws if the tool is a team tool and the session is a descendant of a team member.
- * OQ-11: assumes throwing inside tool.execute.before fails the tool call gracefully.
+ * OQ-11: confirmed — throwing inside tool.execute.before fails the tool call gracefully (verified in live testing).
  */
 export function checkToolIsolation(
   registry: MemberRegistry,

package/src/index.ts

@@ -3,10 +3,10 @@ import { tool } from "@opencode-ai/plugin"
 import path from "path"
 import { mkdirSync } from "node:fs"
 import { createDb, getDbPath } from "./db"
-import { recoverStaleMembers } from "./recovery"
+import { recoverStaleMembers, recoverUndeliveredMessages } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
-import { notifyTeamEvent } from "./notify"
+import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
 import { executeTeamMessage } from "./tools/team-message"
@@ -22,10 +22,13 @@ import { executeTeamStatus } from "./tools/team-status"
 import { executeTeamView } from "./tools/team-view"
 import type { ToolDeps, PluginClient } 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
 
 /**
  * opencode-ensemble plugin entry point.
@@ -42,8 +45,12 @@ const plugin: Plugin = async (input) => {
   const registry = new MemberRegistry()
   const tracker = new DescendantTracker()
 
-  // Run recovery on init — mark stale busy members as error
-  const recovery = recoverStaleMembers(db)
+  // Build shared tool dependencies
+  const client = input.client as unknown as PluginClient
+  const deps: ToolDeps = { db, registry, tracker, client }
+
+  // Run recovery on init — mark stale busy members as error + abort orphaned sessions
+  const recovery = await recoverStaleMembers(db, client)
   if (recovery.interrupted > 0) {
     // Rebuild registry from DB for recovered members
     const members = db.query(
@@ -54,9 +61,10 @@ const plugin: Plugin = async (input) => {
     }
   }
 
-  // Build shared tool dependencies
-  const client = input.client as unknown as PluginClient
-  const deps: ToolDeps = { db, registry, tracker, client }
+  // Redeliver undelivered messages from previous sessions
+  recoverUndeliveredMessages(db, client, registry).catch(() => {
+    // Best effort — don't block plugin init
+  })
 
   // Initialize rate limiter
   // OPENCODE_ENSEMBLE_RATE_LIMIT=0 disables it entirely
@@ -68,6 +76,17 @@ const plugin: Plugin = async (input) => {
     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)
+  const watchdog = new Watchdog({
+    db, client, registry,
+    ttlMs: watchdogTtl,
+    checkIntervalMs: DEFAULT_WATCHDOG_CHECK_MS,
+  })
+  watchdog.start()
+
   return {
     // Event hook — drives state machine transitions + descendant tracking + toasts
     async event({ event }) {
@@ -84,7 +103,28 @@ const plugin: Plugin = async (input) => {
             notifyTeamEvent(client, "completed", { memberName: transition.memberName })
           } else if (transition.to === "error") {
             notifyTeamEvent(client, "error", { memberName: transition.memberName })
+          } else if (transition.to === "retry") {
+            // Teammate is being rate-limited — notify user
+            try {
+              await client.tui.showToast({
+                title: "Team",
+                message: `${transition.memberName} is being rate-limited`,
+                variant: "warning",
+                duration: 3000,
+              })
+            } 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({ path: { id: sessionID } })
+              } catch { /* best effort */ }
+            }
           }
+
+          // Show working progress after every transition so the user sees who's still active
+          await notifyWorkingProgress(client, db, transition.teamId)
         }
       }
 

package/src/notify.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite"
 import type { PluginClient } from "./types"
 
 type TeamEventType = "spawn" | "message" | "completed" | "error" | "shutdown"
@@ -52,3 +53,43 @@ export async function notifyTeamEvent(
     // TUI may not be available — silently ignore
   }
 }
+
+/**
+ * Fire a toast showing which teammates are still working.
+ * Called on every session.status transition so the user sees live progress.
+ * Does nothing if the team has no members.
+ */
+export async function notifyWorkingProgress(
+  client: PluginClient,
+  db: Database,
+  teamId: string,
+): Promise<void> {
+  const members = db.query(
+    "SELECT name, status FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
+  ).all(teamId) as Array<{ name: string; status: string }>
+
+  if (members.length === 0) return
+
+  const busy = members.filter(m => m.status === "busy")
+
+  try {
+    if (busy.length === 0) {
+      await client.tui.showToast({
+        title: "Team",
+        message: "All teammates finished",
+        variant: "success",
+        duration: 4000,
+      })
+    } else {
+      const names = busy.map(m => m.name).join(", ")
+      await client.tui.showToast({
+        title: "Team",
+        message: `Working: ${names} (${busy.length}/${members.length})`,
+        variant: "info",
+        duration: 5000,
+      })
+    }
+  } catch {
+    // TUI may not be available — silently ignore
+  }
+}

package/src/recovery.ts

@@ -6,16 +6,34 @@ import { getUndeliveredMessages, markDelivered } from "./messaging"
 /**
  * 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).
  * Only processes members in active teams.
  * Returns the count of interrupted members.
  */
-export function recoverStaleMembers(db: Database): { interrupted: number } {
+export async function recoverStaleMembers(db: Database, client?: PluginClient): Promise<{ interrupted: number }> {
+  // Find stale members before updating so we can abort their sessions
+  const stale = db.query(
+    `SELECT tm.session_id 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 }>
+
   const result = db.run(
     `UPDATE team_member SET status = 'error', execution_status = 'idle', time_updated = ?
      WHERE status = 'busy'
        AND team_id IN (SELECT id FROM team WHERE status = 'active')`,
     [Date.now()]
   )
+
+  // Abort orphaned sessions (best effort)
+  if (client) {
+    for (const member of stale) {
+      try {
+        await client.session.abort({ path: { id: member.session_id } })
+      } catch { /* best effort */ }
+    }
+  }
+
   return { interrupted: result.changes }
 }
 

package/src/tools/team-broadcast.ts

@@ -53,7 +53,10 @@ export async function executeTeamBroadcast(
     }
   }
 
-  markDelivered(deps.db, msgId)
+  // Only mark delivered if at least one recipient received it
+  if (delivered > 0) {
+    markDelivered(deps.db, msgId)
+  }
 
   return `Broadcast sent to ${delivered} recipient${delivered !== 1 ? "s" : ""}.`
 }

package/src/tools/team-cleanup.ts

@@ -17,7 +17,7 @@ export async function executeTeamCleanup(
   const members = deps.db.query("SELECT name, session_id, status FROM team_member WHERE team_id = ?")
     .all(teamInfo.teamId) as Array<{ name: string; session_id: string; status: string }>
 
-  const active = members.filter(m => m.status !== "shutdown")
+  const active = members.filter(m => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error")
 
   if (active.length > 0 && !args.force) {
     const names = active.map(m => m.name).join(", ")

package/src/tools/team-create.ts

@@ -28,5 +28,5 @@ export async function executeTeamCreate(
     [id, args.name, sessionId, now, now]
   )
 
-  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates.`
+  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates. Teammates will message you when done — do not poll team_status repeatedly.`
 }

package/src/tools/team-shutdown.ts

@@ -27,8 +27,20 @@ export async function executeTeamShutdown(
     [Date.now(), teamInfo.teamId, args.member]
   )
 
-  // Call abort on the member's session
-  await deps.client.session.abort({ path: { id: member.session_id } })
+  // Call abort on the member's session (best effort)
+  try {
+    await deps.client.session.abort({ path: { id: member.session_id } })
+  } catch {
+    // Abort failed — session may already be gone. Fire a warning toast.
+    try {
+      await deps.client.tui.showToast({
+        title: "Team",
+        message: `Failed to abort ${args.member} session — will rely on event hook`,
+        variant: "warning",
+        duration: 4000,
+      })
+    } catch { /* TUI may not be available */ }
+  }
 
   // Fallback: poll session status after abort. If already idle, transition
   // directly to shutdown. This handles the case where abort() on an

package/src/tools/team-spawn.ts

@@ -54,8 +54,9 @@ export async function executeTeamSpawn(
     "- team_claim: claim a pending task from the shared board",
     "",
     "When you finish your task:",
-    "1. Send ONE message to the lead with your findings using team_message.",
-    "2. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
+    "1. If you claimed a task, mark it complete using team_tasks_complete.",
+    "2. Send ONE message to the lead with your findings using team_message.",
+    "3. 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.",
     "",
@@ -63,15 +64,29 @@ export async function executeTeamSpawn(
     "",
     "Your task:",
     args.prompt,
-  ].join("\n")
+  ]
+
+  if (args.claim_task) {
+    context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`)
+  }
+
+  const contextStr = context.join("\n")
 
   // Fire-and-forget: send prompt to teammate session
-  // OQ-1: assuming promptAsync queues when session is busy
-  // OQ-10: assuming fresh session accepts promptAsync without session.init()
-  await deps.client.session.promptAsync({
-    path: { id: childSessionId },
-    body: { parts: [{ type: "text", text: context }] },
-  })
+  // OQ-1: confirmed — promptAsync queues when session is busy (verified in live testing)
+  // OQ-10: confirmed — fresh session accepts promptAsync without session.init() (verified in live testing)
+  try {
+    await deps.client.session.promptAsync({
+      path: { id: childSessionId },
+      body: { parts: [{ type: "text", text: contextStr }] },
+    })
+  } catch (err) {
+    // Rollback: clean up DB, registry, and abort the orphaned session
+    deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name])
+    deps.registry.unregister(childSessionId)
+    try { await deps.client.session.abort({ path: { id: childSessionId } }) } catch { /* best effort */ }
+    throw new Error(`Failed to send initial prompt to teammate "${args.name}": ${err instanceof Error ? err.message : String(err)}`)
+  }
 
-  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""}`
+  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""} Teammates will message you when done. Do not poll team_status to check.`
 }

package/src/tools/team-status.ts

@@ -45,5 +45,28 @@ export async function executeTeamStatus(
     lines.push(`Tasks: ${tasks.length} total (${parts.join(", ")})`)
   }
 
+  // Fire a toast so the user (not just the model) sees the status summary
+  if (members.length > 0) {
+    const memberParts = members.map(m => {
+      const label = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status
+      return `${m.name} [${label}]`
+    })
+    let toastMsg = memberParts.join(", ")
+    if (tasks.length > 0) {
+      const completed = tasks.filter(t => t.status === "completed").length
+      toastMsg += ` | Tasks: ${completed}/${tasks.length} done`
+    }
+    try {
+      await deps.client.tui.showToast({
+        title: "Team",
+        message: toastMsg,
+        variant: "info",
+        duration: 4000,
+      })
+    } catch {
+      // TUI may not be available — silently ignore
+    }
+  }
+
   return lines.join("\n")
 }

package/src/watchdog.ts

@@ -0,0 +1,92 @@
+import type { Database } from "bun:sqlite"
+import type { PluginClient } from "./types"
+import type { MemberRegistry } from "./state"
+
+interface WatchdogOpts {
+  db: Database
+  client: PluginClient
+  registry: MemberRegistry
+  /** Maximum time a member can stay busy before being timed out. 0 disables. */
+  ttlMs: number
+  /** How often to run the check. Defaults to 60s. */
+  checkIntervalMs?: number
+}
+
+/**
+ * Periodic watchdog that times out teammates stuck in busy state.
+ * Transitions them to error/timed_out, aborts their session, and fires a toast.
+ */
+export class Watchdog {
+  private readonly db: Database
+  private readonly client: PluginClient
+  private readonly registry: MemberRegistry
+  private readonly ttlMs: number
+  private readonly checkIntervalMs: number
+  private timer: ReturnType<typeof setInterval> | undefined
+
+  constructor(opts: WatchdogOpts) {
+    this.db = opts.db
+    this.client = opts.client
+    this.registry = opts.registry
+    this.ttlMs = opts.ttlMs
+    this.checkIntervalMs = opts.checkIntervalMs ?? 60_000
+  }
+
+  /** Run a single check for stale busy members. */
+  async check(): Promise<void> {
+    if (this.ttlMs === 0) return
+
+    const cutoff = Date.now() - this.ttlMs
+    const stale = this.db.query(
+      `SELECT tm.team_id, tm.name, tm.session_id
+       FROM team_member tm
+       JOIN team t ON tm.team_id = t.id
+       WHERE t.status = 'active'
+         AND tm.status = 'busy'
+         AND tm.time_updated < ?`
+    ).all(cutoff) as Array<{ team_id: string; name: string; session_id: string }>
+
+    for (const member of stale) {
+      // Mark as timed out
+      this.db.run(
+        "UPDATE team_member SET status = 'error', execution_status = 'timed_out', time_updated = ? WHERE team_id = ? AND name = ?",
+        [Date.now(), member.team_id, member.name]
+      )
+
+      // Abort session (best effort)
+      try {
+        await this.client.session.abort({ path: { id: member.session_id } })
+      } catch { /* best effort */ }
+
+      // Notify
+      try {
+        await this.client.tui.showToast({
+          title: "Team",
+          message: `${member.name} timed out`,
+          variant: "warning",
+          duration: 5000,
+        })
+      } catch { /* TUI may not be available */ }
+    }
+  }
+
+  /** Start the periodic check. */
+  start(): void {
+    if (this.timer) return
+    if (this.ttlMs === 0) return
+    this.timer = setInterval(() => this.check(), this.checkIntervalMs)
+  }
+
+  /** Stop the periodic check. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = undefined
+    }
+  }
+
+  /** Whether the watchdog is currently running. */
+  isRunning(): boolean {
+    return this.timer !== undefined
+  }
+}