@hueyexe/opencode-ensemble 0.1.2 → 0.3.0

package/README.md

@@ -125,7 +125,6 @@ export { default } from "/path/to/opencode-ensemble/src/index.ts"
 | `team_spawn` | Start a new teammate with a task. |
 | `team_shutdown` | Ask a teammate to stop. |
 | `team_cleanup` | Remove the team when done. |
-| `team_approve_plan` | Approve or reject a teammate's plan before they write code. |
 | `team_status` | See all members, their status, and a task summary. |
 | `team_view` | Switch the TUI to a teammate's session. |
 
@@ -135,6 +134,7 @@ export { default } from "/path/to/opencode-ensemble/src/index.ts"
 |------|-------------|
 | `team_message` | Send a direct message to a teammate or the lead. |
 | `team_broadcast` | Message everyone on the team. |
+| `team_results` | Retrieve full message content (messages to lead are truncated on delivery). |
 
 **Task board** (everyone)
 
@@ -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

@@ -12407,7 +12407,9 @@ var MIGRATIONS = [
   CREATE INDEX IF NOT EXISTS team_message_to_idx ON team_message(to_name);
   CREATE INDEX IF NOT EXISTS team_message_undelivered_idx ON team_message(team_id, delivered)
     WHERE delivered = 0;
-  `
+  `,
+  `ALTER TABLE team_message ADD COLUMN read INTEGER NOT NULL DEFAULT 0;
+   CREATE INDEX IF NOT EXISTS team_message_unread_idx ON team_message(team_id, read) WHERE read = 0;`
 ];
 function applyMigrations(db) {
   const { user_version: current } = db.query("PRAGMA user_version").get();
@@ -12476,17 +12478,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 +12622,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;
 }
@@ -12694,7 +12743,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. Teammates will message you when done \u2014 do not poll team_status repeatedly.`;
+  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. IMPORTANT: After spawning all teammates, do NOT call any tools. Tell the user what you've set up and STOP. You will be woken automatically.`;
 }
 
 // src/tools/team-spawn.ts
@@ -12749,11 +12798,20 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const contextStr = context.join(`
 `);
-  await deps.client.session.promptAsync({
-    path: { id: childSessionId },
-    body: { parts: [{ type: "text", text: contextStr }] }
-  });
-  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.`;
+  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 (agent: ${args.agent}). IMPORTANT: Do NOT call any tools after this. Tell the user what you've set up and STOP. You will be woken automatically when teammates message you.`;
 }
 
 // src/tools/team-message.ts
@@ -12771,9 +12829,18 @@ async function executeTeamMessage(deps, args, sessionId) {
     to: args.to,
     content: args.text
   });
+  const isToLead = args.to === "lead";
+  const MAX_LEAD_MSG = 500;
+  let deliveryText;
+  if (isToLead && args.text.length > MAX_LEAD_MSG) {
+    const truncated = args.text.slice(0, MAX_LEAD_MSG);
+    deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`;
+  } else {
+    deliveryText = `[Team message from ${senderName}]: ${args.text}`;
+  }
   await deps.client.session.promptAsync({
     path: { id: recipientSessionId },
-    body: { parts: [{ type: "text", text: `[Team message from ${senderName}]: ${args.text}` }] }
+    body: { parts: [{ type: "text", text: deliveryText }] }
   });
   markDelivered(deps.db, msgId);
   return `Message sent to ${args.to}.`;
@@ -12812,7 +12879,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" : ""}.`;
 }
 
@@ -12829,7 +12898,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];
@@ -12958,36 +13038,36 @@ async function executeTeamClaim(deps, args, sessionId) {
   return `Claimed task: ${task.content}`;
 }
 
-// src/tools/team-approve-plan.ts
-async function executeTeamApprovePlan(deps, args, sessionId) {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
-  if (!teamInfo)
-    throw new Error("This session is not in a team.");
-  if (teamInfo.role !== "lead")
-    throw new Error("Only the team lead can approve plans.");
-  const member = deps.db.query("SELECT session_id, status FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.member);
-  if (!member)
-    throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`);
-  const text = args.approved ? `Your plan has been APPROVED.${args.feedback ? ` Feedback: ${args.feedback}` : " Proceed with implementation."}` : `Your plan has been REJECTED. Please revise and resubmit.${args.feedback ? ` Feedback: ${args.feedback}` : ""}`;
-  const msgId = sendMessage(deps.db, {
-    teamId: teamInfo.teamId,
-    from: "lead",
-    to: args.member,
-    content: text
-  });
-  await deps.client.session.promptAsync({
-    path: { id: member.session_id },
-    body: { parts: [{ type: "text", text: `[Plan ${args.approved ? "approved" : "rejected"} by lead]: ${text}` }] }
-  });
-  markDelivered(deps.db, msgId);
-  return `Plan ${args.approved ? "approved" : "rejected"} for ${args.member}.${args.feedback ? ` Feedback: ${args.feedback}` : ""}`;
+// src/tools/team-results.ts
+async function executeTeamResults(deps, args, sessionId) {
+  const team = findTeamBySession(deps.db, deps.registry, sessionId);
+  if (!team)
+    throw new Error("not in a team");
+  const rows = args.from ? deps.db.query("SELECT id, from_name, content, time_created FROM team_message WHERE team_id = ? AND read = 0 AND from_name = ? ORDER BY time_created ASC").all(team.teamId, args.from) : deps.db.query("SELECT id, from_name, content, time_created FROM team_message WHERE team_id = ? AND read = 0 ORDER BY time_created ASC").all(team.teamId);
+  if (rows.length === 0)
+    return "No unread messages.";
+  const ids = rows.map((r) => r.id);
+  const placeholders = ids.map(() => "?").join(", ");
+  deps.db.run(`UPDATE team_message SET read = 1 WHERE id IN (${placeholders})`, ids);
+  return rows.map((r) => `[Message from ${r.from_name}]:
+${r.content}
+`).join(`
+`);
 }
 
 // src/tools/team-status.ts
+var lastCallTime = new Map;
+var RATE_LIMIT_MS = 30000;
 async function executeTeamStatus(deps, sessionId) {
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId);
   if (!teamInfo)
     throw new Error("This session is not in a team.");
+  const now = Date.now();
+  const last = lastCallTime.get(teamInfo.teamId);
+  if (last !== undefined && now - last < RATE_LIMIT_MS) {
+    return "Status unchanged. STOP \u2014 do not call any more tools. Tell the user you are waiting for teammates to finish. You will be woken automatically when they message you.";
+  }
+  lastCallTime.set(teamInfo.teamId, now);
   const members = deps.db.query("SELECT name, session_id, agent, status, execution_status FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamInfo.teamId);
   const tasks = deps.db.query("SELECT status FROM team_task WHERE team_id = ?").all(teamInfo.teamId);
   const lines = [];
@@ -13030,7 +13110,9 @@ async function executeTeamStatus(deps, sessionId) {
       });
     } catch {}
   }
-  return lines.join(`
+  return `[Relay this status to the user in your next message:]
+
+` + lines.join(`
 `);
 }
 
@@ -13042,8 +13124,12 @@ async function executeTeamView(deps, args, sessionId) {
   const member = deps.db.query("SELECT session_id, status, agent FROM team_member WHERE team_id = ? AND name = ?").get(teamInfo.teamId, args.member);
   if (!member)
     throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`);
-  await deps.client.tui.selectSession({ sessionID: member.session_id });
-  return `Switched view to ${args.member}'s session (${member.session_id}). Use the session picker to return to the lead session.`;
+  try {
+    if (typeof deps.client.tui.selectSession === "function") {
+      await deps.client.tui.selectSession({ sessionID: member.session_id });
+    }
+  } catch {}
+  return `View ${args.member}'s session: ${member.session_id}. Use the session picker (ctrl+p) to navigate to their session.`;
 }
 
 // src/rate-limit.ts
@@ -13109,25 +13195,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({
@@ -13135,6 +13282,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") {
@@ -13148,6 +13305,22 @@ 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);
         }
@@ -13265,16 +13438,14 @@ var plugin = async (input) => {
           return result;
         }
       }),
-      team_approve_plan: tool({
-        description: "Approve or reject a teammate's implementation plan. Only the team lead can use this.",
+      team_results: tool({
+        description: "Retrieve full message content from teammates. Returns unread messages and marks them as read. Use this after receiving a truncated message notification.",
         args: {
-          member: tool.schema.string().describe("Teammate name"),
-          approved: tool.schema.boolean().describe("true to approve, false to reject"),
-          feedback: tool.schema.string().optional().describe("Feedback message (optional)")
+          from: tool.schema.string().optional().describe("Filter messages by sender name (optional, returns all if omitted)")
         },
         async execute(args, ctx) {
-          const result = await executeTeamApprovePlan(deps, args, ctx.sessionID);
-          ctx.metadata({ title: `Plan ${args.approved ? "approved" : "rejected"}: ${args.member}` });
+          const result = await executeTeamResults(deps, args, ctx.sessionID);
+          ctx.metadata({ title: `Results${args.from ? ` from ${args.from}` : ""}` });
           return result;
         }
       }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.1.2",
+  "version": "0.3.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,7 +3,7 @@ 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, notifyWorkingProgress } from "./notify"
@@ -17,15 +17,18 @@ import { executeTeamTasksList } from "./tools/team-tasks-list"
 import { executeTeamTasksAdd } from "./tools/team-tasks-add"
 import { executeTeamTasksComplete } from "./tools/team-tasks-complete"
 import { executeTeamClaim } from "./tools/team-claim"
-import { executeTeamApprovePlan } from "./tools/team-approve-plan"
+import { executeTeamResults } from "./tools/team-results"
 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,6 +103,24 @@ 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
@@ -217,16 +254,14 @@ const plugin: Plugin = async (input) => {
         },
       }),
 
-      team_approve_plan: tool({
-        description: "Approve or reject a teammate's implementation plan. Only the team lead can use this.",
+      team_results: tool({
+        description: "Retrieve full message content from teammates. Returns unread messages and marks them as read. Use this after receiving a truncated message notification.",
         args: {
-          member: tool.schema.string().describe("Teammate name"),
-          approved: tool.schema.boolean().describe("true to approve, false to reject"),
-          feedback: tool.schema.string().optional().describe("Feedback message (optional)"),
+          from: tool.schema.string().optional().describe("Filter messages by sender name (optional, returns all if omitted)"),
         },
         async execute(args, ctx) {
-          const result = await executeTeamApprovePlan(deps, args, ctx.sessionID)
-          ctx.metadata({ title: `Plan ${args.approved ? "approved" : "rejected"}: ${args.member}` })
+          const result = await executeTeamResults(deps, args, ctx.sessionID)
+          ctx.metadata({ title: `Results${args.from ? ` from ${args.from}` : ""}` })
           return result
         },
       }),

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/schema.ts

@@ -67,6 +67,9 @@ export const MIGRATIONS: string[] = [
   CREATE INDEX IF NOT EXISTS team_message_undelivered_idx ON team_message(team_id, delivered)
     WHERE delivered = 0;
   `,
+  // Migration 2: Add read column to team_message for team_results tracking
+  `ALTER TABLE team_message ADD COLUMN read INTEGER NOT NULL DEFAULT 0;
+   CREATE INDEX IF NOT EXISTS team_message_unread_idx ON team_message(team_id, read) WHERE read = 0;`,
 ]
 
 /**

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-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. Teammates will message you when done — do not poll team_status repeatedly.`
+  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. IMPORTANT: After spawning all teammates, do NOT call any tools. Tell the user what you've set up and STOP. You will be woken automatically.`
 }

package/src/tools/team-message.ts

@@ -25,10 +25,20 @@ export async function executeTeamMessage(
     content: args.text,
   })
 
-  // Deliver via promptAsync
+  // Deliver via promptAsync — truncate lead-bound messages over 500 chars
+  const isToLead = args.to === "lead"
+  const MAX_LEAD_MSG = 500
+  let deliveryText: string
+  if (isToLead && args.text.length > MAX_LEAD_MSG) {
+    const truncated = args.text.slice(0, MAX_LEAD_MSG)
+    deliveryText = `[Team message from ${senderName}]: ${truncated}... (use team_results to read full message)`
+  } else {
+    deliveryText = `[Team message from ${senderName}]: ${args.text}`
+  }
+
   await deps.client.session.promptAsync({
     path: { id: recipientSessionId },
-    body: { parts: [{ type: "text", text: `[Team message from ${senderName}]: ${args.text}` }] },
+    body: { parts: [{ type: "text", text: deliveryText }] },
   })
 
   markDelivered(deps.db, msgId)

package/src/tools/team-results.ts

@@ -0,0 +1,45 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession } from "../types"
+
+/** Row shape for unread messages query. */
+interface UnreadMessageRow {
+  id: string
+  from_name: string
+  content: string
+  time_created: number
+}
+
+/**
+ * Retrieve unread messages from the team message store.
+ * Optionally filter by sender name. Marks returned messages as read.
+ */
+export async function executeTeamResults(
+  deps: ToolDeps,
+  args: { from?: string },
+  sessionId: string,
+): Promise<string> {
+  const team = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!team) throw new Error("not in a team")
+
+  const rows = args.from
+    ? (deps.db
+        .query(
+          "SELECT id, from_name, content, time_created FROM team_message WHERE team_id = ? AND read = 0 AND from_name = ? ORDER BY time_created ASC",
+        )
+        .all(team.teamId, args.from) as UnreadMessageRow[])
+    : (deps.db
+        .query(
+          "SELECT id, from_name, content, time_created FROM team_message WHERE team_id = ? AND read = 0 ORDER BY time_created ASC",
+        )
+        .all(team.teamId) as UnreadMessageRow[])
+
+  if (rows.length === 0) return "No unread messages."
+
+  // Mark all returned messages as read
+  const ids = rows.map((r) => r.id)
+  const placeholders = ids.map(() => "?").join(", ")
+  deps.db.run(`UPDATE team_message SET read = 1 WHERE id IN (${placeholders})`, ids)
+
+  // Format output
+  return rows.map((r) => `[Message from ${r.from_name}]:\n${r.content}\n`).join("\n")
+}

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

@@ -73,12 +73,20 @@ export async function executeTeamSpawn(
   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: contextStr }] },
-  })
+  // 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 ? "..." : ""} Teammates will message you when done. Do not poll team_status to check.`
+  return `Teammate "${args.name}" spawned (agent: ${args.agent}). IMPORTANT: Do NOT call any tools after this. Tell the user what you've set up and STOP. You will be woken automatically when teammates message you.`
 }

package/src/tools/team-status.ts

@@ -1,6 +1,11 @@
 import type { ToolDeps } from "../types"
 import { findTeamBySession } from "../types"
 
+/** Tracks the last time team_status was called per team ID (epoch ms). */
+export const lastCallTime = new Map<string, number>()
+
+const RATE_LIMIT_MS = 30_000
+
 /**
  * Execute the team_status tool. Shows team overview with member statuses and task summary.
  */
@@ -11,6 +16,13 @@ export async function executeTeamStatus(
   const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
   if (!teamInfo) throw new Error("This session is not in a team.")
 
+  const now = Date.now()
+  const last = lastCallTime.get(teamInfo.teamId)
+  if (last !== undefined && (now - last) < RATE_LIMIT_MS) {
+    return "Status unchanged. STOP — do not call any more tools. Tell the user you are waiting for teammates to finish. You will be woken automatically when they message you."
+  }
+  lastCallTime.set(teamInfo.teamId, now)
+
   const members = deps.db.query(
     "SELECT name, session_id, agent, status, execution_status FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
   ).all(teamInfo.teamId) as Array<{
@@ -68,5 +80,5 @@ export async function executeTeamStatus(
     }
   }
 
-  return lines.join("\n")
+  return "[Relay this status to the user in your next message:]\n\n" + lines.join("\n")
 }

package/src/tools/team-view.ts

@@ -17,7 +17,14 @@ export async function executeTeamView(
     .get(teamInfo.teamId, args.member) as { session_id: string; status: string; agent: string } | null
   if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
 
-  await deps.client.tui.selectSession({ sessionID: member.session_id })
+  // TUI session navigation — try selectSession if available, otherwise guide the user
+  try {
+    if (typeof deps.client.tui.selectSession === "function") {
+      await deps.client.tui.selectSession({ sessionID: member.session_id })
+    }
+  } catch {
+    // selectSession may not be available in all SDK versions — fall through to manual guidance
+  }
 
-  return `Switched view to ${args.member}'s session (${member.session_id}). Use the session picker to return to the lead session.`
+  return `View ${args.member}'s session: ${member.session_id}. Use the session picker (ctrl+p) to navigate to their session.`
 }

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
+  }
+}

package/src/tools/team-approve-plan.ts

@@ -1,42 +0,0 @@
-import type { ToolDeps } from "../types"
-import { findTeamBySession, resolveRecipientSession } from "../types"
-import { sendMessage, markDelivered } from "../messaging"
-
-/**
- * Execute the team_approve_plan tool. Approves or rejects a teammate's plan
- * and notifies them via message.
- */
-export async function executeTeamApprovePlan(
-  deps: ToolDeps,
-  args: { member: string; approved: boolean; feedback?: string },
-  sessionId: string,
-): Promise<string> {
-  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
-  if (!teamInfo) throw new Error("This session is not in a team.")
-  if (teamInfo.role !== "lead") throw new Error("Only the team lead can approve plans.")
-
-  const member = deps.db.query("SELECT session_id, status FROM team_member WHERE team_id = ? AND name = ?")
-    .get(teamInfo.teamId, args.member) as { session_id: string; status: string } | null
-  if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
-
-  const text = args.approved
-    ? `Your plan has been APPROVED.${args.feedback ? ` Feedback: ${args.feedback}` : " Proceed with implementation."}`
-    : `Your plan has been REJECTED. Please revise and resubmit.${args.feedback ? ` Feedback: ${args.feedback}` : ""}`
-
-  // Send approval/rejection message to teammate
-  const msgId = sendMessage(deps.db, {
-    teamId: teamInfo.teamId,
-    from: "lead",
-    to: args.member,
-    content: text,
-  })
-
-  await deps.client.session.promptAsync({
-    path: { id: member.session_id },
-    body: { parts: [{ type: "text", text: `[Plan ${args.approved ? "approved" : "rejected"} by lead]: ${text}` }] },
-  })
-
-  markDelivered(deps.db, msgId)
-
-  return `Plan ${args.approved ? "approved" : "rejected"} for ${args.member}.${args.feedback ? ` Feedback: ${args.feedback}` : ""}`
-}