@hueyexe/opencode-ensemble 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.16.1",
+  "version": "0.17.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/dashboard-js-render.ts

@@ -81,7 +81,7 @@ function rAgents(t){
       '<div class="flex items-center gap-2">'+
         '<span class="w-[8px] h-[8px] rounded-full '+s.d+(m.status==='busy'?' pulse':'')+' shrink-0"></span>'+
         '<span class="font-mono font-semibold text-[14px] truncate">'+E(m.name)+'</span>'+
-        '<span class="text-[10px] px-1.5 py-[1px] rounded '+s.t+' bg-base-800/80 shrink-0">'+s.l+'</span>'+
+        '<span class="text-[10px] px-1.5 py-[1px] rounded '+s.t+' bg-base-800/80 shrink-0">'+s.l+(m.lastNudgedAt?', nudged '+relT(m.lastNudgedAt):'')+'</span>'+
         spark+
         '<span class="text-[10px] text-txt-500 ml-auto shrink-0">'+E(m.agent)+'</span>'+
         (m.model?chip(E(m.model),'muted'):'')+
@@ -90,6 +90,7 @@ function rAgents(t){
       (mp?'<div class="mt-1 text-[12px] text-txt-400 truncate">Latest: '+E(mp)+'</div>':'')+
       '<div class="mt-2 flex items-center gap-1.5 flex-wrap">'+
         chip('status '+d,'muted')+chip('msg '+mi,'muted')+chip(E(m.executionStatus||m.status),m.status==='busy'?'blue':m.status==='error'?'red':'muted')+
+        (m.isRetrying?chip('retrying'+(m.retryAttempt!=null?' (attempt '+m.retryAttempt+')':''),'amber'):'')+
         (m.worktreeBranch?chip(E(m.worktreeBranch),'muted'):'')+
       '</div></button>';
   }).join('');
@@ -113,6 +114,8 @@ function openDrawer(name){
   meta.push(chip(E(m.executionStatus||m.status),m.status==='busy'?'blue':m.status==='error'?'red':'muted'));
   if(m.planApproval&&m.planApproval!=='none')meta.push(chip(E(m.planApproval),m.planApproval==='approved'?'green':m.planApproval==='rejected'?'red':'amber'));
   meta.push(chip('spawned '+relT(m.timeCreated),'muted'));
+  if(m.lastNudgedAt)meta.push(chip('nudged '+relT(m.lastNudgedAt),'amber'));
+  if(m.isRetrying)meta.push(chip('retrying'+(m.retryAttempt!=null?' (attempt '+m.retryAttempt+')':'')+(m.retryMessage?': '+E(m.retryMessage):''),'amber'));
   if(m.worktreeBranch)meta.push(chip(E(m.worktreeBranch),'muted'));
   h+='<div class="flex flex-wrap gap-1.5 mb-4 pb-4 border-b border-base-800/50">'+meta.join('')+'</div>';
   // Prompt
@@ -180,7 +183,7 @@ function rDrawerActivityUpdate(){
     el.innerHTML='<div class="text-txt-500 text-[12px]">No activity recorded</div>';
     return;
   }
-  var html=drawerActivity.map(function(a){
+  var html=drawerActivity.slice().reverse().map(function(a){
     var icon='\\u25CF',color='text-txt-500',label=a.type;
     if(a.type==='tool_call'){icon='\\u25B8';color='text-blue-400';label=a.tool||'tool'}
     if(a.type==='tool_result'){icon='\\u25B8';color=a.error?'text-red-400':'text-emerald-400';label=a.tool||'tool'}

package/src/dashboard.ts

@@ -16,6 +16,7 @@ interface TeamRow {
   id: string
   name: string
   project_id: string
+  lead_session_id: string
   status: string
   lead_agent: string | null
   time_created: number
@@ -43,6 +44,11 @@ interface MemberRow {
   plan_approval: string
   time_created: number
   time_updated: number
+  last_nudged_at: number | null
+  retry_until: number | null
+  retry_attempt: number | null
+  retry_provider: string | null
+  retry_message: string | null
 }
 
 interface TaskRow {
@@ -81,10 +87,31 @@ function parseDependsOn(value: string | null): string[] {
   return []
 }
 
-function buildState(db: Database): { projects: unknown[]; teams: unknown[] } {
+/**
+ * Bare-integer version of the `/api/state` response shape. Bump on any
+ * breaking change to the payload (field removed/renamed/retyped, not
+ * additive fields). Consumers outside this repo compare this field with
+ * strict equality — no semver ranges. Currently consumed externally by the
+ * OpenCode sidebar TUI plugin that renders Team status from this endpoint.
+ */
+export const ENSEMBLE_STATE_VERSION = 1
+
+/**
+ * `/api/state` response shape. Exported and versioned because at least one
+ * consumer outside this repo (an OpenCode sidebar TUI plugin) polls this
+ * endpoint and depends on its shape. Treat additive-only changes as safe;
+ * bump {@link ENSEMBLE_STATE_VERSION} for anything else.
+ */
+export interface EnsembleDashboardState {
+  version: number
+  projects: unknown[]
+  teams: unknown[]
+}
+
+function buildState(db: Database): EnsembleDashboardState {
   const projects = db.query("SELECT id, name, path, status, time_created, time_updated FROM project ORDER BY time_updated DESC").all() as ProjectRow[]
-  const teams = db.query("SELECT id, name, project_id, status, lead_agent, time_created, time_updated FROM team ORDER BY time_created DESC").all() as TeamRow[]
-  const memberStmt = db.query("SELECT name, agent, status, execution_status, session_id, worktree_branch, prompt, model, plan_approval, time_created, time_updated FROM team_member WHERE team_id = ?")
+  const teams = db.query("SELECT id, name, project_id, lead_session_id, status, lead_agent, time_created, time_updated FROM team ORDER BY time_created DESC").all() as TeamRow[]
+  const memberStmt = db.query("SELECT name, agent, status, execution_status, session_id, worktree_branch, prompt, model, plan_approval, time_created, time_updated, last_nudged_at, retry_until, retry_attempt, retry_provider, retry_message FROM team_member WHERE team_id = ?")
   const taskStmt = db.query("SELECT id, content, status, priority, assignee, depends_on, time_created, time_updated FROM team_task WHERE team_id = ?")
   const msgStmt = db.query("SELECT id, from_name, to_name, content, delivered, read, time_created FROM team_message WHERE team_id = ? ORDER BY time_created DESC LIMIT 50")
 
@@ -101,11 +128,21 @@ function buildState(db: Database): { projects: unknown[]; teams: unknown[] } {
       planApproval: m.plan_approval,
       timeCreated: m.time_created,
       timeUpdated: m.time_updated,
+      lastNudgedAt: m.last_nudged_at,
+      // Fix 4: derived, read-time TTL boolean (Fix 3) — never a stored enum.
+      // Additive fields; existing consumers that don't know about them simply
+      // don't render them.
+      isRetrying: m.retry_until !== null && m.retry_until > Date.now(),
+      retryUntil: m.retry_until,
+      retryAttempt: m.retry_attempt,
+      retryProvider: m.retry_provider,
+      retryMessage: m.retry_message,
     }))
     return {
       id: t.id,
       name: t.name,
       projectId: t.project_id,
+      leadSessionId: t.lead_session_id,
       status: t.status,
       leadAgent: t.lead_agent,
       timeCreated: t.time_created,
@@ -140,6 +177,7 @@ function buildState(db: Database): { projects: unknown[]; teams: unknown[] } {
   })
 
   return {
+    version: ENSEMBLE_STATE_VERSION,
     projects: projects.flatMap(project => {
       const projectTeams = teamsByProject.get(project.id) ?? []
       if (projectTeams.length === 0) return []
@@ -183,11 +221,30 @@ function sendJson(res: ServerResponse, data: unknown): void {
   res.end(JSON.stringify(data))
 }
 
+/**
+ * Resolve a message's creation timestamp (Unix ms) from an SDK message's
+ * `info.time`. The SDK shape is an object `{ created: number }`; older/other
+ * shapes (a numeric epoch or an ISO string) are tolerated. Falls back to
+ * `Date.now()` when the value is missing or unparseable — never returns NaN.
+ */
+export function parseMessageTime(time: unknown): number {
+  if (typeof time === "object" && time !== null) {
+    const created = (time as { created?: unknown }).created
+    if (typeof created === "number" && Number.isFinite(created)) return created
+  }
+  if (typeof time === "number" && Number.isFinite(time)) return time
+  if (typeof time === "string") {
+    const ms = new Date(time).getTime()
+    if (!Number.isNaN(ms)) return ms
+  }
+  return Date.now()
+}
+
 /** Parse SDK message parts into ActivityEntry format for the fallback path. */
 export function parseMessageParts(parts: unknown[], msgInfo: unknown): ActivityEntry[] {
   const entries: ActivityEntry[] = []
-  const info = (msgInfo ?? {}) as { time?: string; role?: string; tokens?: { input?: number; output?: number } }
-  const timestamp = info.time ? new Date(info.time).getTime() : Date.now()
+  const info = (msgInfo ?? {}) as { time?: unknown; role?: string; tokens?: { input?: number; output?: number } }
+  const timestamp = parseMessageTime(info.time)
 
   for (const part of parts) {
     if (typeof part !== "object" || part === null) continue

package/src/hooks.ts

@@ -1,10 +1,38 @@
 import type { Database } from "./db"
 import type { MemberRegistry, DescendantTracker } from "./state"
-import { sendMessage } from "./messaging"
+import type { PluginClient } from "./types"
+import { notifyLead } from "./notify"
+import { releaseMemberTasks } from "./tasks"
 import { findTeamBySession } from "./types"
 
 const TEAM_TOOL_PREFIX = "team_"
 
+/**
+ * Retry-specific payload carried by a `session.status` event when
+ * `status === "retry"`. Mirrors the SDK's `SessionStatus` retry variant.
+ * `action` is optional and free-form (not rate-limit-specific) — see Fix 2
+ * in the retry-observability spec.
+ */
+export interface RetryStatusPayload {
+  attempt: number
+  message: string
+  action?: {
+    reason: string
+    provider: string
+    title: string
+    message: string
+    label: string
+    link?: string
+  }
+  /**
+   * Absolute epoch-ms timestamp of the next retry attempt — NOT a relative
+   * delta. Confirmed against the opencode server/TUI source (session.retry.scheduled
+   * emits `{attempt, at, error}` mapped straight onto `next`, and the built-in
+   * TUI computes remaining seconds as `Math.round((next - Date.now()) / 1000)`).
+   */
+  next: number
+}
+
 /** Result of a session status event — tells the caller what transition happened. */
 export interface StatusTransition {
   memberName: string
@@ -18,12 +46,17 @@ export interface StatusTransition {
  * in SQLite based on the new session status.
  * Ignores events for unknown sessions or archived teams.
  * Returns the transition if one occurred, for toast notifications.
+ *
+ * `retryPayload` is only consulted when `status === "retry"` — it persists
+ * the four additive retry_* columns (Fix 2) without changing `status`/
+ * `execution_status` at all (Fix 1's non-goal: no FSM change).
  */
 export function handleSessionStatusEvent(
   db: Database,
   registry: MemberRegistry,
   sessionId: string,
   status: "idle" | "busy" | "retry",
+  retryPayload?: RetryStatusPayload,
 ): StatusTransition | undefined {
   const entry = registry.getBySession(sessionId)
   if (!entry) return undefined
@@ -43,6 +76,11 @@ export function handleSessionStatusEvent(
       "UPDATE team_member SET status = ?, execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?",
       [newStatus, Date.now(), entry.teamId, entry.memberName]
     )
+    // A gracefully shut-down member has actually stopped now — release any
+    // tasks they left in_progress back to the pool so nothing is stranded (issue #27).
+    if (newStatus === "shutdown") {
+      releaseMemberTasks(db, entry.teamId, entry.memberName)
+    }
     // Mark teammate as having reported if they sent at least one message to lead (issue #3).
     // Set on busy→ready transition so Q&A messages during work don't prematurely block delivery.
     if (member.status === "busy" && newStatus === "ready") {
@@ -67,12 +105,46 @@ export function handleSessionStatusEvent(
       )
       return { memberName: entry.memberName, teamId: entry.teamId, from: member.status, to: "busy" }
     }
+    // Freshly-spawned member: inserted as busy/starting before the session's
+    // first busy event. Advance execution_status to running and refresh
+    // time_updated so the dashboard shows accurate progress instead of a
+    // frozen "starting" state (do NOT reset reported_to_lead — status is
+    // already busy, so this is not a re-activation).
+    if (member.status === "busy" && member.execution_status === "starting") {
+      db.run(
+        "UPDATE team_member SET 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" }
+    }
     // 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
+    // Session is being rate-limited — signal for toast but don't change state.
+    // Persist the retry_* columns so the signal survives past the toast (Fix 2)
+    // — status/execution_status are untouched, and there is no "provider
+    // throttled" language baked in here: the SDK's retry status is generic,
+    // so we surface whatever action.message/status.message actually says.
+    if (retryPayload) {
+      // Coerce before binding: older server versions may emit a partial retry
+      // payload, and an undefined bind throws synchronously inside this event
+      // handler, discarding the event's remaining processing.
+      const next = typeof retryPayload.next === "number" && Number.isFinite(retryPayload.next) ? retryPayload.next : null
+      const attempt = typeof retryPayload.attempt === "number" && Number.isFinite(retryPayload.attempt) ? retryPayload.attempt : null
+      db.run(
+        "UPDATE team_member SET retry_until = ?, retry_attempt = ?, retry_provider = ?, retry_message = ? WHERE team_id = ? AND name = ?",
+        [
+          next,
+          attempt,
+          retryPayload.action?.provider ?? null,
+          retryPayload.action?.message ?? retryPayload.message ?? null,
+          entry.teamId,
+          entry.memberName,
+        ]
+      )
+    }
     return { memberName: entry.memberName, teamId: entry.teamId, from: member.status, to: "retry" }
   }
   return undefined
@@ -169,6 +241,11 @@ export interface SessionErrorPayload {
  * Handle a session.error event. Surfaces tool/model failures from a teammate
  * as a system message to the lead, so otherwise-silent failures are visible.
  *
+ * The lead is actively woken via notifyLead so the message is delivered even
+ * when the errored teammate was the last busy member (the "all done" gate in
+ * the passive wake path would otherwise strand the message). The teammate
+ * itself is NOT auto-resumed — recovery is left to the lead's judgement.
+ *
  * Ignored when:
  * - sessionID is undefined
  * - the session is not a registered teammate (leads are not in the registry)
@@ -176,6 +253,7 @@ export interface SessionErrorPayload {
 export function handleSessionErrorEvent(
   db: Database,
   registry: MemberRegistry,
+  client: PluginClient,
   sessionId: string | undefined,
   error: SessionErrorPayload | undefined,
 ): void {
@@ -187,10 +265,10 @@ export function handleSessionErrorEvent(
   if (!teamInfo || teamInfo.role !== "member" || !teamInfo.memberName) return
 
   const errMsg = error?.data?.message ?? error?.name ?? "unknown error"
-  sendMessage(db, {
-    teamId: teamInfo.teamId,
-    from: "system",
-    to: "lead",
-    content: `Teammate "${teamInfo.memberName}" had a session error: ${errMsg}. Check their session for details. They may be stuck and need investigation or shutdown.`,
-  })
+  notifyLead(
+    client,
+    db,
+    teamInfo.teamId,
+    `Teammate "${teamInfo.memberName}" had a session error: ${errMsg}. Check their session for details. They may be stuck and need investigation or shutdown.`,
+  )
 }

package/src/index.ts

@@ -5,12 +5,13 @@ import path from "node:path"
 import { mkdirSync } from "node:fs"
 import { createDb, getDbPath } from "./db"
 import { wrapThrowingClient } from "./client"
-import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees, recoverOrphanedBranches, rehydrateRegistry } from "./recovery"
+import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees, recoverOrphanedBranches, recoverOrphanedTeams, rehydrateRegistry } from "./recovery"
 import { MemberRegistry, DescendantTracker, PendingPurgeApprovals } from "./state"
 import { isWorktreeInstance } from "./util"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation, shouldNudgeIdleMember, handleSessionErrorEvent } from "./hooks"
-import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
-import { sendMessage, hasReportedCompletion } from "./messaging"
+import { notifyTeamEvent, notifyWorkingProgress, notifyLead } from "./notify"
+import { hasReportedCompletion } from "./messaging"
+import { getMemberModel } from "./member-model"
 import { buildLeadSystemPrompt, buildTeammateSystemPrompt, buildTeamCompactionContext } from "./system-prompt"
 import { log, initLog } from "./log"
 import { findTeamBySession } from "./types"
@@ -72,13 +73,35 @@ const plugin: Plugin = async (input) => {
   const rawClient = new OpencodeClient({ client: pluginTransport })
   initLog(rawClient)
   const client = wrapThrowingClient(rawClient)
-  const deps: ToolDeps = { db, registry, tracker, purgeApprovals, client, directory: input.directory, config }
+  const deps: ToolDeps = { db, registry, tracker, purgeApprovals, client, directory: input.directory, config, progressTracker }
 
   // Recovery only runs for the main project instance — NOT for teammate worktree instances.
   // Worktree instances are created during session.create. Running recovery there makes HTTP
   // calls back to the server, which deadlocks because the server is still handling session.create.
   if (!isWorktreeInstance(input.directory)) {
     log("init:recovery:start (main instance)")
+
+    // Reconciles teams whose lead session was deleted externally (not via
+    // team_cleanup) -- otherwise they stay 'active' forever, blocking
+    // team_create/team_cleanup for that name across restarts. See
+    // recoverOrphanedTeams' own doc comment for the full mechanism.
+    //
+    // Fire-and-forget, NOT awaited: isSessionAlive() calls client.session.get(),
+    // an HTTP call back to this same server. Awaiting it synchronously here --
+    // before the server has finished bootstrapping -- reproduced a real,
+    // confirmed deadlock (server never responds to ANY request, including
+    // unrelated ones like /config) when a stale team from a prior run exists
+    // for this project. Matches the existing pattern for the other three
+    // non-critical recovery passes below, and the documented reason
+    // recoverStaleMembers is skipped entirely for worktree instances two lines
+    // up ("makes HTTP calls back to the server, which deadlocks"). isSessionAlive
+    // itself also carries a bounded timeout as defense in depth.
+    recoverOrphanedTeams(db, client, input.directory, registry).then((result) => {
+      if (result.archived > 0) log(`init:recovery:orphaned-teams-archived=${result.archived}`)
+    }).catch((err) => {
+      log(`init:recover-orphaned-teams:failed err=${err instanceof Error ? err.message : String(err)}`)
+    })
+
     const recovery = await recoverStaleMembers(db, client, input.directory)
     if (recovery.interrupted > 0) {
       log(`init:recovery:interrupted=${recovery.interrupted}`)
@@ -142,7 +165,10 @@ const plugin: Plugin = async (input) => {
       if (event.type === "session.status") {
         const { sessionID, status } = event.properties
         const statusType = status.type as "idle" | "busy" | "retry"
-        const transition = handleSessionStatusEvent(db, registry, sessionID, statusType)
+        const retryPayload = statusType === "retry"
+          ? (status as { attempt: number; message: string; action?: { reason: string; provider: string; title: string; message: string; label: string; link?: string }; next: number })
+          : undefined
+        const transition = handleSessionStatusEvent(db, registry, sessionID, statusType, retryPayload)
 
         // Fire toast notifications for meaningful transitions
         if (transition) {
@@ -167,12 +193,12 @@ const plugin: Plugin = async (input) => {
                   nudgedMembers.add(fastIdleKey)
                   const modelInfo = memberInfo.model ? ` (model: ${memberInfo.model})` : ""
                   log(`fast-idle: ${transition.memberName} went idle ${Math.round(spawnAge / 1000)}s after spawn with 0 messages${modelInfo}`)
-                  sendMessage(db, {
-                    teamId: transition.teamId,
-                    from: "system",
-                    to: "lead",
-                    content: `Warning: Teammate "${transition.memberName}" went idle immediately after spawning with no output${modelInfo}. This usually means the model failed to start (authentication error, invalid model, or provider issue). Check your API key and model configuration, then retry the spawn.`,
-                  })
+                  notifyLead(
+                    client,
+                    db,
+                    transition.teamId,
+                    `Warning: Teammate "${transition.memberName}" went idle immediately after spawning with no output${modelInfo}. This usually means the model failed to start (authentication error, invalid model, or provider issue). Check your API key and model configuration, then retry the spawn.`,
+                  )
                   client.tui.showToast({
                     title: "Team",
                     message: `${transition.memberName} failed to produce output${modelInfo}`,
@@ -189,13 +215,23 @@ const plugin: Plugin = async (input) => {
             if (!nudgedMembers.has(nudgeKey) && shouldNudgeIdleMember(db, transition.teamId, transition.memberName) && !hasReportedCompletion(db, transition.teamId, transition.memberName)) {
               nudgedMembers.add(nudgeKey)
               log(`nudge:idle-without-report name=${transition.memberName}`)
+              const nudgeModel = getMemberModel(db, transition.teamId, transition.memberName)
               client.session.promptAsync({
                 sessionID,
                 parts: [{ type: "text", text: "[System]: You completed your work but did not report results. Send your findings to the lead via team_message now." }],
-              }).catch(() => { /* best effort */ })
+                ...(nudgeModel ? { model: nudgeModel } : {}),
+              }).catch((err) => {
+                log(`nudge:idle-without-report:failed name=${transition.memberName} team=${transition.teamId} err=${err instanceof Error ? err.message : String(err)}`)
+              })
             }
           } else if (transition.to === "error") {
             notifyTeamEvent(client, "error", { memberName: transition.memberName })
+          } else if (transition.to === "busy") {
+            // Fresh busy period (ready/error -> busy) — give checkStalled a baseline
+            // that doesn't depend on a step-finish event having landed yet. Without
+            // this, a member whose first action is one long-running tool call is
+            // never detected as stalled until that call itself returns.
+            progressTracker.recordBusyStart(sessionID)
           } else if (transition.to === "retry") {
             // Teammate is being rate-limited — notify user
             try {
@@ -270,9 +306,11 @@ const plugin: Plugin = async (input) => {
             ).get(member.team_id, member.name, staleThreshold) as { c: number }
             if (peerMsgs.c > 0) {
               log(`wake-peer: ${member.name} has ${peerMsgs.c} pending peer messages`)
+              const peerModel = getMemberModel(db, member.team_id, member.name)
               client.session.promptAsync({
                 sessionID,
                 parts: [{ type: "text", text: `[System: ${peerMsgs.c} new message(s) from teammates]` }],
+                ...(peerModel ? { model: peerModel } : {}),
               }).catch((err) => {
                 log(`wake-peer:failed err=${err instanceof Error ? err.message : String(err)}`)
               })
@@ -294,7 +332,7 @@ const plugin: Plugin = async (input) => {
       // teammate just appears stuck.
       if (event.type === "session.error") {
         const props = event.properties as { sessionID?: string; error?: { name?: string; data?: { message?: string } } }
-        handleSessionErrorEvent(db, registry, props.sessionID, props.error)
+        handleSessionErrorEvent(db, registry, client, props.sessionID, props.error)
       }
 
       // Track per-step output tokens for stall detection
@@ -415,12 +453,16 @@ const plugin: Plugin = async (input) => {
       }),
 
       team_message: tool({
-        description: "Send a message to a specific teammate or to the lead. Use 'lead' to message the team lead.",
+        description: "Send a message to a specific teammate or to the lead. Use 'lead' to message the team lead. " +
+          "Lead only: pass 'model' (provider/model) to update a teammate's model in-place — it applies on their next turn. " +
+          "When updating a model, 'text' is optional; omit it to change the model without sending a message.",
         args: {
           to: tool.schema.string().describe("Recipient name ('lead' or teammate name)"),
-          text: tool.schema.string().describe("Message content (max 10KB)"),
+          text: tool.schema.string().optional().describe("Message content (max 10KB). Optional only when 'model' is provided."),
           approve: tool.schema.boolean().optional().describe("Approve a teammate's plan (only when recipient has plan_approval='pending')"),
           reject: tool.schema.string().optional().describe("Reject a teammate's plan with reason (only when recipient has plan_approval='pending')"),
+          force: tool.schema.boolean().optional().describe("Lead only. Re-activate a teammate who already reported task completion (normally their session won't be woken again). Use for legitimate follow-on work — e.g. the next round of a multi-round debate — not for courtesy replies."),
+          model: tool.schema.string().optional().describe("Lead only: update the recipient teammate's model in-place, in 'provider/model' format (e.g. 'anthropic/claude-sonnet')."),
         },
         async execute(args, ctx) {
           const result = await executeTeamMessage(deps, args, ctx.sessionID)
@@ -428,7 +470,7 @@ const plugin: Plugin = async (input) => {
           progressTracker.recordMessage(ctx.sessionID)
           // Track peer messages for chatty detection
           if (args.to !== "lead") progressTracker.recordPeerMessage(ctx.sessionID)
-          ctx.metadata({ title: `Message → ${args.to}` })
+          ctx.metadata({ title: args.model ? `Set ${args.to} model → ${args.model}` : `Message → ${args.to}` })
           return result
         },
       }),
@@ -440,8 +482,13 @@ const plugin: Plugin = async (input) => {
         },
         async execute(args, ctx) {
           const result = await executeTeamBroadcast(deps, args, ctx.sessionID)
-          // Track broadcast activity for stall detection
+          // Track broadcast activity for stall detection AND chatty detection --
+          // a broadcast reaches every teammate at once, arguably the most
+          // "chatty" action possible, and was previously invisible to
+          // checkChatty()'s peer-message rate limit (recordPeerMessage was never
+          // called here, only recordMessage).
           progressTracker.recordMessage(ctx.sessionID)
+          progressTracker.recordPeerMessage(ctx.sessionID)
           ctx.metadata({ title: "Broadcast to team" })
           return result
         },

package/src/member-model.ts

@@ -0,0 +1,30 @@
+import type { Database } from "./db"
+
+/** A parsed provider/model pair, as accepted by session.promptAsync. */
+export interface ParsedModel {
+  providerID: string
+  modelID: string
+}
+
+/**
+ * Parse a "provider/model" string into { providerID, modelID } for the SDK.
+ * Returns undefined if the string is not in "provider/model" form (empty
+ * provider or empty model). The model portion may itself contain slashes.
+ */
+export function parseModelId(model: string): ParsedModel | undefined {
+  const slash = model.indexOf("/")
+  if (slash <= 0 || slash === model.length - 1) return undefined
+  return { providerID: model.slice(0, slash), modelID: model.slice(slash + 1) }
+}
+
+/**
+ * Read a team member's stored model and parse it for session.promptAsync.
+ * Returns undefined when the member is unknown, has no model set, or the
+ * stored value is malformed. Never throws — safe to call from delivery paths.
+ */
+export function getMemberModel(db: Database, teamId: string, memberName: string): ParsedModel | undefined {
+  const row = db.query("SELECT model FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamId, memberName) as { model: string | null } | null
+  if (!row?.model) return undefined
+  return parseModelId(row.model)
+}

package/src/notify.ts

@@ -1,5 +1,7 @@
 import type { Database } from "./db"
 import type { PluginClient } from "./types"
+import { sendMessage } from "./messaging"
+import { log } from "./log"
 
 type TeamEventType = "spawn" | "message" | "completed" | "error" | "shutdown"
 
@@ -82,3 +84,45 @@ export async function notifyWorkingProgress(
     // TUI may not be available — silently ignore
   }
 }
+
+/**
+ * Persist a system-generated message to the lead AND actively wake the lead
+ * so the message is delivered on the lead's next turn.
+ *
+ * This is the delivery path for system events (teammate errors, timeouts,
+ * stalls, spawn failures). Unlike the passive wake-lead path in the event
+ * hook, this ALWAYS fires a promptAsync regardless of whether teammates are
+ * still busy — an errored/aborted teammate is precisely the case where the
+ * "all teammates done" gate would otherwise suppress the wake and strand the
+ * message in the DB with delivered=0.
+ *
+ * The message is persisted first; the promptAsync wake is fire-and-forget
+ * (never awaited, per the plugin's promptAsync invariant). If the wake fails,
+ * the message is still in the DB and the passive backstop / recovery paths
+ * remain available.
+ *
+ * Returns the persisted message id.
+ */
+export function notifyLead(
+  client: PluginClient,
+  db: Database,
+  teamId: string,
+  content: string,
+): string {
+  const id = sendMessage(db, { teamId, from: "system", to: "lead", content })
+
+  const team = db.query("SELECT lead_session_id FROM team WHERE id = ?")
+    .get(teamId) as { lead_session_id: string } | null
+  if (!team?.lead_session_id) return id
+
+  // Fire-and-forget wake — the system prompt transform delivers the actual
+  // content on the lead's next turn.
+  client.session.promptAsync({
+    sessionID: team.lead_session_id,
+    parts: [{ type: "text", text: "[System: New team message from system]" }],
+  }).catch((err) => {
+    log(`notifyLead:wake:failed team=${teamId} err=${err instanceof Error ? err.message : String(err)}`)
+  })
+
+  return id
+}

package/src/progress.ts

@@ -12,6 +12,7 @@ export class ProgressTracker {
   private steps = new Map<string, StepRecord[]>()
   private lastMessageAt = new Map<string, number>()
   private lastTaskAt = new Map<string, number>()
+  private busySince = new Map<string, number>()
   private peerMessages = new Map<string, number[]>()
   private reported = new Set<string>()
   private chattyReported = new Set<string>()
@@ -83,15 +84,32 @@ export class ProgressTracker {
     return recent.every(r => r.outputTokens < threshold)
   }
 
-  /** Time-based stall: no message or task completion within `thresholdMs` of now. */
-  isTimeStalled(sessionId: string, thresholdMs: number): boolean {
+  /**
+   * Record that this member transitioned to busy. Gives isTimeStalled a baseline
+   * independent of step records, so a member whose first (or only) action is one
+   * long-running tool call is still subject to time-based stall detection before
+   * any step-finish event has landed.
+   */
+  recordBusyStart(sessionId: string): void {
+    this.busySince.set(sessionId, Date.now())
+  }
+
+  /** Latest activity timestamp across all tracked signals (0 when nothing recorded). */
+  lastActivityAt(sessionId: string): number {
     const records = this.steps.get(sessionId)
-    if (!records || records.length === 0) return false
+    const lastStepAt = records && records.length > 0 ? records[records.length - 1]!.timestamp : 0
+    return Math.max(
+      this.lastMessageAt.get(sessionId) ?? 0,
+      this.lastTaskAt.get(sessionId) ?? 0,
+      lastStepAt,
+      this.busySince.get(sessionId) ?? 0,
+    )
+  }
 
-    const msgAt = this.lastMessageAt.get(sessionId) ?? 0
-    const taskAt = this.lastTaskAt.get(sessionId) ?? 0
-    const lastStep = records[records.length - 1]?.timestamp ?? 0
-    const baseline = Math.max(msgAt, taskAt, lastStep)
+  /** Time-based stall: no message, task completion, step, or busy-transition within `thresholdMs` of now. */
+  isTimeStalled(sessionId: string, thresholdMs: number): boolean {
+    const baseline = this.lastActivityAt(sessionId)
+    if (baseline === 0) return false // no activity or busy signal recorded at all yet
 
     return Date.now() - baseline >= thresholdMs
   }
@@ -116,6 +134,7 @@ export class ProgressTracker {
     this.steps.delete(sessionId)
     this.lastMessageAt.delete(sessionId)
     this.lastTaskAt.delete(sessionId)
+    this.busySince.delete(sessionId)
     this.peerMessages.delete(sessionId)
     this.reported.delete(sessionId)
     this.chattyReported.delete(sessionId)