@hueyexe/opencode-ensemble 0.1.2 → 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;
 }
@@ -12749,10 +12796,19 @@ async function executeTeamSpawn(deps, args, sessionId) {
   }
   const contextStr = context.join(`
 `);
-  await deps.client.session.promptAsync({
-    path: { id: childSessionId },
-    body: { parts: [{ type: "text", text: contextStr }] }
-  });
+  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.`;
 }
 
@@ -12812,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" : ""}.`;
 }
 
@@ -12829,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];
@@ -13109,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({
@@ -13135,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") {
@@ -13148,6 +13288,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);
         }

package/package.json

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

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-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.`
 }

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