@hueyexe/opencode-ensemble 0.16.1 → 0.17.0

package/src/recovery.ts

@@ -2,18 +2,104 @@ import type { Database } from "./db"
 import type { PluginClient } from "./types"
 import type { MemberRegistry } from "./state"
 import { getUndeliveredMessages, markDelivered, hasReportedCompletion } from "./messaging"
+import { releaseMemberTasks } from "./tasks"
+import { getMemberModel } from "./member-model"
 import { preserveBranch, preservedBranchName, teamResourceSegment } from "./tools/merge-helper"
 import { log } from "./log"
 import { runCommand } from "./process"
 
+/**
+ * Whether a session still exists in OpenCode. `client.session.get` throws for a
+ * deleted/unknown session rather than returning empty data -- see dashboard.ts's
+ * existing best-effort usage of the same call.
+ *
+ * Bounded by a timeout: a `session.get` call made from within this plugin's own
+ * init sequence, before the server has finished bootstrapping, can hang the
+ * request indefinitely rather than resolve or reject -- the same class of
+ * self-referential-HTTP-call deadlock team-spawn.ts's own `withTimeout` exists
+ * to guard against for `worktree.create`/`session.create` ("makes HTTP calls
+ * back to the server, which deadlocks because the server is still handling
+ * session.create"). On timeout, treat liveness as UNKNOWN (return true, i.e.
+ * "assume alive, don't archive") rather than assuming dead -- a false negative
+ * here just means the orphan isn't reconciled this pass; a false positive means
+ * archiving a team that might still be genuinely active.
+ */
+export async function isSessionAlive(client: PluginClient, sessionId: string, timeoutMs = 5000): Promise<boolean> {
+  try {
+    await Promise.race([
+      client.session.get({ sessionID: sessionId }),
+      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("isSessionAlive timed out")), timeoutMs)),
+    ])
+    return true
+  } catch (err) {
+    if (err instanceof Error && err.message === "isSessionAlive timed out") {
+      log(`recovery:team:liveness-check-timeout session=${sessionId}`)
+      return true
+    }
+    return false
+  }
+}
+
+/**
+ * Reconcile 'active' teams whose lead session no longer exists in OpenCode --
+ * e.g. the user deleted the session via OpenCode's own session UI/API, not via
+ * team_cleanup. Ensemble's own bookkeeping has no way to learn about that on its
+ * own: nothing tells it the session is gone, so the team row stays 'active'
+ * forever, blocking team_create ("already exists") and team_cleanup's purge path
+ * ("cannot purge active team" -- purge only operates on archived teams) for that
+ * name indefinitely. A team with no live lead session is unrecoverable through
+ * any legitimate path (there is no "reassign lead" tool), so archiving it directly
+ * is safe regardless of member state -- the existing recoverOrphanedWorktrees/
+ * recoverOrphanedBranches passes then naturally sweep up its resources on the same
+ * recovery cycle, since those already scope to archived teams with no active
+ * members.
+ *
+ * Scoped by cwd the same way recoverStaleMembers is, to avoid reconciling other
+ * projects' teams when multiple projects share one DB.
+ */
+export async function recoverOrphanedTeams(
+  db: Database,
+  client: PluginClient,
+  cwd?: string,
+  registry?: MemberRegistry,
+): Promise<{ archived: number }> {
+  const active = db.query(
+    `SELECT id, lead_session_id FROM team
+     WHERE status = 'active' AND (? IS NULL OR project_id = ? OR project_id = 'default')`
+  ).all(cwd ?? null, cwd ?? null) as Array<{ id: string; lead_session_id: string }>
+
+  let archived = 0
+  for (const team of active) {
+    if (await isSessionAlive(client, team.lead_session_id)) continue
+
+    db.run("UPDATE team SET status = 'archived', time_updated = ? WHERE id = ?", [Date.now(), team.id])
+    registry?.unregisterTeam(team.id)
+    archived++
+    log(`recovery:team:orphaned team_id=${team.id} lead_session=${team.lead_session_id}`)
+  }
+
+  return { archived }
+}
+
 /**
  * Scan for team members stuck in 'busy' status (stale from a crash)
  * and mark them as 'error' with execution_status 'idle'.
  * Preserves worktree branches before aborting orphaned sessions.
  * Only processes members in active teams.
  * Returns the count of interrupted members.
+ *
+ * `abortTimeoutMs` bounds each `client.session.abort()` call -- the same
+ * self-referential-HTTP-call-back-to-this-server shape as
+ * `isSessionAlive()`'s `client.session.get()` (see that function's doc
+ * comment for the full deadlock mechanism, confirmed live 2026-08-17). This
+ * function is awaited synchronously in plugin init (unlike
+ * `recoverOrphanedTeams`, which is fire-and-forget) because
+ * `rehydrateRegistry` depends on it completing first, so a bounded timeout on
+ * the network call -- not restructuring the await -- is the fix here: the
+ * DB-only work (marking members 'error') always completes and is reflected in
+ * the returned count regardless of whether any individual abort call settles.
  */
-export async function recoverStaleMembers(db: Database, client?: PluginClient, cwd?: string): Promise<{ interrupted: number }> {
+export async function recoverStaleMembers(db: Database, client?: PluginClient, cwd?: string, abortTimeoutMs = 5000): Promise<{ interrupted: number }> {
   // Find stale members with branch info so we can preserve before aborting
   const stale = db.query(
     `SELECT tm.session_id, tm.worktree_branch, tm.name, tm.team_id, t.name as team_name, p.name as project_name
@@ -31,6 +117,13 @@ export async function recoverStaleMembers(db: Database, client?: PluginClient, c
     [Date.now(), cwd ?? null, cwd ?? null]
   )
 
+  // Release each stale member's in_progress tasks back to the pool so their
+  // unfinished work is reclaimable after a crash (issue #27).
+  for (const member of stale) {
+    const released = releaseMemberTasks(db, member.team_id, member.name)
+    if (released > 0) log(`recovery:tasks:released name=${member.name} count=${released}`)
+  }
+
   // Preserve branches then abort orphaned sessions
   if (client) {
     for (const member of stale) {
@@ -45,8 +138,16 @@ export async function recoverStaleMembers(db: Database, client?: PluginClient, c
         }
       }
       try {
-        await client.session.abort({ sessionID: member.session_id })
-      } catch { /* best effort */ }
+        await Promise.race([
+          client.session.abort({ sessionID: member.session_id }),
+          new Promise<never>((_, reject) => setTimeout(() => reject(new Error("session.abort timed out")), abortTimeoutMs)),
+        ])
+      } catch (err) {
+        if (err instanceof Error && err.message === "session.abort timed out") {
+          log(`recovery:stale-members:abort-timeout session=${member.session_id}`)
+        }
+        /* best effort */
+      }
     }
   }
 
@@ -133,9 +234,11 @@ export async function recoverUndeliveredMessages(
       }
 
       try {
+        const recipientModel = getMemberModel(db, team.id, msg.to_name)
         await client.session.promptAsync({
           sessionID: recipientSessionId,
           parts: [{ type: "text", text: `[Recovered team message from ${msg.from_name}]: ${msg.content}` }],
+          ...(recipientModel ? { model: recipientModel } : {}),
         })
         markDelivered(db, msg.id)
         redelivered++

package/src/schema.ts

@@ -186,6 +186,24 @@ export const MIGRATIONS: string[] = [
    CREATE INDEX IF NOT EXISTS team_message_undelivered_idx ON team_message(team_id, delivered) WHERE delivered = 0;
    CREATE INDEX IF NOT EXISTS team_message_unread_idx ON team_message(team_id, read) WHERE read = 0;
    PRAGMA foreign_keys=ON;`,
+  // Migration 9: Add last_nudged_at to team_member — additive-only display-staleness
+  // signal for the watchdog's soft stall-nudge path. Deliberately NOT a new status
+  // enum value (see checkStalled() in watchdog.ts for the rationale): a 6th CHECK
+  // constraint literal would require a table-rebuild migration and touch every
+  // consumer that switches on the 5 known status strings. This column is additive —
+  // existing consumers that don't know about it simply don't render it.
+  `ALTER TABLE team_member ADD COLUMN last_nudged_at INTEGER;`,
+  // Migration 10: Add retry_* columns to team_member — additive-only provider-retry
+  // display signal (see hooks.ts's "retry" branch). Same non-negotiable as Migration
+  // 9: no 6th status/execution_status literal, no table rebuild. retry_until is a
+  // TTL, not a stored enum — "currently retrying" is derived at read time
+  // (retry_until > Date.now()), so there is no explicit clear-write anywhere in this
+  // fix; it simply becomes stale and gets superseded by real activity or by time
+  // elapsing.
+  `ALTER TABLE team_member ADD COLUMN retry_until INTEGER;
+   ALTER TABLE team_member ADD COLUMN retry_attempt INTEGER;
+   ALTER TABLE team_member ADD COLUMN retry_provider TEXT;
+   ALTER TABLE team_member ADD COLUMN retry_message TEXT;`,
 ]
 
 /**

package/src/tasks.ts

@@ -0,0 +1,19 @@
+import type { Database } from "./db"
+
+/**
+ * Release all in-progress tasks assigned to a departing member back to the
+ * shared pool. Sets status to 'pending' and clears the assignee so another
+ * teammate can claim the work. Completed, cancelled, and blocked tasks are
+ * left untouched. Returns the number of tasks released.
+ *
+ * Call this whenever a member reaches a terminal state (shutdown, timeout,
+ * crash recovery, or spawn rollback) so their unfinished work is not stranded
+ * as permanently in_progress with a dead assignee (issue #27).
+ */
+export function releaseMemberTasks(db: Database, teamId: string, memberName: string): number {
+  const result = db.run(
+    "UPDATE team_task SET status = 'pending', assignee = NULL, time_updated = ? WHERE team_id = ? AND assignee = ? AND status = 'in_progress'",
+    [Date.now(), teamId, memberName],
+  )
+  return result.changes
+}

package/src/tools/team-create.ts

@@ -1,6 +1,7 @@
 import type { ToolDeps } from "../types"
 import { generateId, generateProjectName, validateProjectName, validateTeamName } from "../util"
 import { findTeamBySession } from "../types"
+import { isSessionAlive } from "../recovery"
 
 /**
  * Execute the team_create tool. Creates a new team with the caller as lead.
@@ -19,8 +20,20 @@ export async function executeTeamCreate(
 
   // Check if team name already exists
   const projectId = deps.directory
-  const existing = deps.db.query("SELECT id FROM team WHERE name = ? AND project_id = ? AND status = 'active'").get(args.name, projectId)
-  if (existing) throw new Error(`Team "${args.name}" already exists`)
+  const existing = deps.db.query("SELECT id, lead_session_id FROM team WHERE name = ? AND project_id = ? AND status = 'active'")
+    .get(args.name, projectId) as { id: string; lead_session_id: string } | undefined
+  if (existing) {
+    // The existing team's lead session may have been deleted externally (via
+    // OpenCode's own session UI/API, not team_cleanup) rather than genuinely
+    // still being in use. Reconcile on demand rather than block this call on a
+    // team nobody can ever be lead of again -- don't wait for the next plugin
+    // restart's periodic recoverOrphanedTeams pass to notice.
+    if (await isSessionAlive(deps.client, existing.lead_session_id)) {
+      throw new Error(`Team "${args.name}" already exists`)
+    }
+    deps.db.run("UPDATE team SET status = 'archived', time_updated = ? WHERE id = ?", [Date.now(), existing.id])
+    deps.registry.unregisterTeam(existing.id)
+  }
 
   // Check if session already leads a team
   const lead = findTeamBySession(deps.db, deps.registry, sessionId)

package/src/tools/team-merge.ts

@@ -1,5 +1,6 @@
 import type { ToolDeps } from "../types"
-import { requireLead } from "./shared"
+import { requireLead, checkWorktreeDirty, countBranchCommits } from "./shared"
+import type { IsDirtyFn, CommitCountFn } from "./shared"
 import { mergeBranch, deleteBranch, getOverlappingFiles } from "./merge-helper"
 import type { MergeBranchFn, DeleteBranchFn, OverlapCheckFn } from "./merge-helper"
 import { log } from "../log"
@@ -15,11 +16,13 @@ export async function executeTeamMerge(
   merge: MergeBranchFn = mergeBranch,
   delBranch: DeleteBranchFn = deleteBranch,
   overlapCheck: OverlapCheckFn = getOverlappingFiles,
+  commitCount: CommitCountFn = countBranchCommits,
+  isDirty: IsDirtyFn = checkWorktreeDirty,
 ): Promise<string> {
   const teamInfo = requireLead(deps, sessionId)
 
-  const member = deps.db.query("SELECT status, worktree_branch FROM team_member WHERE team_id = ? AND name = ?")
-    .get(teamInfo.teamId, args.member) as { status: string; worktree_branch: string | null } | null
+  const member = deps.db.query("SELECT status, worktree_branch, worktree_dir FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamInfo.teamId, args.member) as { status: string; worktree_branch: string | null; worktree_dir: string | null } | null
   if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
 
   if (member.status !== "shutdown" && member.status !== "error") {
@@ -33,6 +36,30 @@ export async function executeTeamMerge(
   const branch = member.worktree_branch
   log(`merge:start member=${args.member} branch=${branch}`)
 
+  // A branch with zero new commits produces a trivially "successful" no-op squash merge --
+  // there is genuinely nothing to apply. Reporting that as "Merged ... changes" is
+  // misleading: if the teammate's worktree still has uncommitted work, that work was never
+  // captured on the branch at all and is about to be permanently lost the moment the
+  // worktree is removed (e.g. by team_cleanup). Say so plainly instead of a false success,
+  // and don't tear down the branch/worktree while it may be the only copy of the work.
+  // A commit-count check failure returns -1 (unknown) -- never treat that as "nothing to
+  // merge"; fall through to the real merge attempt so a check failure can't silently skip
+  // real work.
+  const commits = await commitCount(branch, deps.directory)
+  if (commits === 0) {
+    const dirty = member.worktree_dir ? await isDirty(member.worktree_dir).catch(() => false) : false
+    if (dirty) {
+      return [
+        `Nothing to merge for "${args.member}" — their branch (${branch}) has no commits.`,
+        `Their worktree still has uncommitted changes that were never captured on the branch.`,
+        `This work will be permanently lost if the worktree is removed (e.g. via team_cleanup).`,
+        member.worktree_dir ? `Worktree: ${member.worktree_dir}` : ``,
+        `Recover manually (copy files out of the worktree) before shutting down/cleaning up, or re-spawn and instruct them to commit their changes before reporting done.`,
+      ].filter(Boolean).join("\n")
+    }
+    return `Nothing to merge for "${args.member}" — their branch (${branch}) has no commits and no uncommitted changes. They made no changes.`
+  }
+
   // Block merge if lead has local changes to files the agent also modified
   try {
     const overlap = await overlapCheck(branch, deps.directory)

package/src/tools/team-message.ts

@@ -2,21 +2,62 @@ import type { ToolDeps } from "../types"
 import { resolveRecipientSession } from "../types"
 import { requireTeamMember } from "./shared"
 import { sendMessage, markDelivered, hasReportedCompletion } from "../messaging"
+import { parseModelId, getMemberModel } from "../member-model"
 import { log } from "../log"
 
 /**
  * Execute the team_message tool. Sends a direct message to a teammate or lead.
  * Optionally approves or rejects a teammate's plan (lead only).
+ * Optionally forces delivery to a teammate who already reported completion (lead only) —
+ * see the `force` guard below.
+ * Optionally updates a teammate's model in-place (lead only) via the `model`
+ * param — see #26. When `model` is set, `text` is optional: if omitted, the
+ * model is updated without delivering a message.
  */
 export async function executeTeamMessage(
   deps: ToolDeps,
-  args: { to: string; text: string; approve?: boolean; reject?: string },
+  args: { to: string; text?: string; approve?: boolean; reject?: string; force?: boolean; model?: string },
   sessionId: string,
 ): Promise<string> {
   const teamInfo = requireTeamMember(deps, sessionId)
 
+  if (args.force && teamInfo.role !== "lead") {
+    throw new Error("Only the lead can force-deliver a message to a completed teammate.")
+  }
+
   const senderName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
 
+  // In-place model update (lead only). Handled before recipient session
+  // resolution so it works even when the member is idle/not in the registry,
+  // and rejects terminal members explicitly. See #26.
+  if (args.model !== undefined) {
+    if (teamInfo.role !== "lead") throw new Error("Only the lead can update a teammate's model.")
+    const parsed = parseModelId(args.model)
+    if (!parsed) throw new Error(`Invalid model "${args.model}" — expected "provider/model" format (e.g. "anthropic/claude-sonnet").`)
+    const member = deps.db.query("SELECT status FROM team_member WHERE team_id = ? AND name = ?")
+      .get(teamInfo.teamId, args.to) as { status: string } | null
+    if (!member) throw new Error(`Teammate "${args.to}" not found in team "${teamInfo.teamName}".`)
+    if (member.status === "shutdown" || member.status === "error") {
+      throw new Error(`Teammate "${args.to}" is shut down — spawn a new teammate instead of updating the model.`)
+    }
+    deps.db.run(
+      "UPDATE team_member SET model = ?, time_updated = ? WHERE team_id = ? AND name = ?",
+      [args.model, Date.now(), teamInfo.teamId, args.to],
+    )
+    log(`team_message:model-update to=${args.to} model=${args.model}`)
+
+    // If there's no accompanying message, we're done — the new model applies
+    // on the teammate's next natural delivery.
+    if (!args.text) {
+      return `Updated ${args.to}'s model to ${args.model}. It applies on their next turn.`
+    }
+  }
+
+  if (args.text === undefined) {
+    throw new Error("team_message requires either 'text' or 'model'.")
+  }
+  const text = args.text
+
   const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
 
   // If recipient not found, store the message for later delivery (they may not be spawned yet)
@@ -29,7 +70,7 @@ export async function executeTeamMessage(
       teamId: teamInfo.teamId,
       from: senderName,
       to: args.to,
-      content: args.text,
+      content: text,
     })
     log(`team_message:queued from=${senderName} to=${args.to} (recipient not yet spawned)`)
     return `Message queued for ${args.to} — they haven't been spawned yet. It will be delivered when they join the team.`
@@ -37,7 +78,7 @@ export async function executeTeamMessage(
   if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
 
   // Handle plan approval/rejection
-  let messageText = args.text
+  let messageText = text
   if (args.approve || args.reject) {
     if (args.approve && args.reject) {
       throw new Error("Cannot both approve and reject a plan.")
@@ -90,16 +131,23 @@ export async function executeTeamMessage(
     return `Message sent to ${args.to}.`
   }
 
-  // Guard: skip promptAsync delivery to teammates who have already reported completion (issue #3)
-  if (hasReportedCompletion(deps.db, teamInfo.teamId, args.to)) {
-    return `Message stored for ${args.to} (teammate has completed their task — message will not wake them).`
+  // Guard: skip promptAsync delivery to teammates who have already reported completion (issue #3),
+  // unless the lead explicitly forces it. Forcing wakes the session; the natural busy transition
+  // (handleSessionStatusEvent) resets the completion flag when the teammate next goes idle, the
+  // same reset that already happens for a normal re-activation — this just gives the lead a way
+  // to trigger it deliberately instead of it being unreachable once the guard is set.
+  if (hasReportedCompletion(deps.db, teamInfo.teamId, args.to) && !args.force) {
+    return `Message stored for ${args.to} (teammate has completed their task — message will not wake them). Pass force:true to re-activate them.`
   }
 
   // For member-to-member messages, fire-and-forget delivery is safe.
+  // Deliver on the recipient's configured model, if any (#26).
   const deliveryText = `[Team message from ${senderName}]: ${messageText}`
+  const recipientModel = getMemberModel(deps.db, teamInfo.teamId, args.to)
   deps.client.session.promptAsync({
     sessionID: recipientSessionId,
     parts: [{ type: "text", text: deliveryText }],
+    ...(recipientModel ? { model: recipientModel } : {}),
   }).then(() => {
     markDelivered(deps.db, msgId)
   }).catch((err) => {

package/src/tools/team-shutdown.ts

@@ -3,6 +3,7 @@ import { requireLead, checkWorktreeDirty, countBranchCommits } from "./shared"
 import type { IsDirtyFn, CommitCountFn } from "./shared"
 import { getTeamResourceParts, preserveBranch, preservedBranchName } from "./merge-helper"
 import type { PreserveBranchFn } from "./merge-helper"
+import { releaseMemberTasks } from "../tasks"
 import { log } from "../log"
 
 /**
@@ -127,6 +128,11 @@ async function preserveAndAbort(
     "UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?",
     [Date.now(), teamId, memberName],
   )
+
+  // Release any tasks this member was working — they are gone now, so their
+  // in_progress work must return to the pool for another teammate (issue #27).
+  const released = releaseMemberTasks(deps.db, teamId, memberName)
+  if (released > 0) log(`shutdown:tasks:released name=${memberName} count=${released}`)
 }
 
 /** Build a status line describing the teammate's work: commit count, dirty state, next step. */

package/src/tools/team-spawn.ts

@@ -2,7 +2,9 @@ import type { ToolDeps, PermissionRule } from "../types"
 import { validateMemberName } from "../util"
 import { requireLead } from "./shared"
 import { claimTask } from "./team-claim"
-import { sendMessage } from "../messaging"
+import { notifyLead } from "../notify"
+import { releaseMemberTasks } from "../tasks"
+import { parseModelId } from "../member-model"
 import { log } from "../log"
 import type { EnsembleConfig } from "../config"
 import { getTeamResourceParts, teamWorktreeName } from "./merge-helper"
@@ -10,13 +12,6 @@ import { getTeamResourceParts, teamWorktreeName } from "./merge-helper"
 /** Tracks consecutive spawn failures per team for circuit breaker. */
 export const spawnFailures = new Map<string, { count: number; lastError: string }>()
 
-/** Parse "provider/model" string into { providerID, modelID } for the SDK. */
-function parseModelId(model: string): { providerID: string; modelID: string } | 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) }
-}
-
 /**
  * Resolve which model to use for a spawned agent.
  * Priority: explicit arg > modelsByAgent > rotation/random > defaultModel > undefined.
@@ -231,6 +226,12 @@ export async function executeTeamSpawn(
     [teamInfo.teamId, args.name, childSessionId, agent, resolvedModel ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]
   )
 
+  // Row is inserted as 'busy' directly -- there is no ready->busy status-event
+  // transition for a fresh spawn, so the watchdog's usual hook point never fires.
+  // Record the baseline here instead, or a member stalled on its first action
+  // is invisible to checkStalled() until its first step-finish event lands.
+  deps.progressTracker.recordBusyStart(childSessionId)
+
   // Register in memory
   deps.registry.register(teamInfo.teamId, args.name, childSessionId)
 
@@ -396,7 +397,7 @@ export async function executeTeamSpawn(
       // Release any task auto-claimed for this teammate so it returns to the pool.
       if (claimedTaskContent) {
         deps.db.run(
-          "UPDATE team_task SET status = 'pending', assignee = NULL, time_updated = ? WHERE id = ? AND assignee = ?",
+          "UPDATE team_task SET status = 'pending', assignee = NULL, time_updated = ? WHERE id = ? AND assignee = ? AND status = 'in_progress'",
           [Date.now(), args.claim_task, args.name]
         )
       }
@@ -414,12 +415,12 @@ export async function executeTeamSpawn(
         variant: "error",
         duration: 8000,
       }).catch(() => { /* TUI may not be available */ })
-      sendMessage(deps.db, {
-        teamId: teamInfo.teamId,
-        from: "system",
-        to: "lead",
-        content: `Teammate "${args.name}" failed to start and was removed${modelInfo}. Error: ${errMsg}. You may retry the spawn.`,
-      })
+      notifyLead(
+        deps.client,
+        deps.db,
+        teamInfo.teamId,
+        `Teammate "${args.name}" failed to start and was removed${modelInfo}. Error: ${errMsg}. You may retry the spawn.`,
+      )
     } catch { /* rollback failed — watchdog will clean up stale member */ }
   })
 

package/src/tools/team-status.ts

@@ -4,8 +4,28 @@ import { requireTeamMember } from "./shared"
 /** Tracks the last time team_status was called per team ID (epoch ms). */
 export const lastCallTime = new Map<string, number>()
 
+/** Tracks the state marker (see computeStateMarker) observed at the last real read per team. */
+export const lastKnownState = new Map<string, number>()
+
 const RATE_LIMIT_MS = 30_000
 
+/**
+ * Cheap per-team "has anything changed" fingerprint — the max time_updated/time_created
+ * across the three tables team_status reports on. One MAX() query, no hashing: the
+ * throttle only needs to detect "something changed," not what, so this is deliberately
+ * the simplest sufficient version (see Fix 3 in the spec).
+ */
+function computeStateMarker(deps: ToolDeps, teamId: string): number {
+  const row = deps.db.query(
+    `SELECT MAX(x) as marker FROM (
+       SELECT MAX(time_updated) as x FROM team_member WHERE team_id = ?
+       UNION SELECT MAX(time_updated) FROM team_task WHERE team_id = ?
+       UNION SELECT MAX(time_created) FROM team_message WHERE team_id = ?
+     )`
+  ).get(teamId, teamId, teamId) as { marker: number | null } | null
+  return row?.marker ?? 0
+}
+
 /** Format a duration in ms to a human-readable string. */
 export function formatDuration(ms: number): string {
   if (ms < 60_000) return `${Math.floor(ms / 1000)}s`
@@ -24,15 +44,20 @@ export async function executeTeamStatus(
 
   const now = Date.now()
   const last = lastCallTime.get(teamInfo.teamId)
-  if (last !== undefined && (now - last) < RATE_LIMIT_MS) {
+  const currentMarker = computeStateMarker(deps, teamInfo.teamId)
+  // The 30s throttle's purpose is preventing hammering, not lying about state — only
+  // short-circuit when nothing has actually changed since the last real read.
+  if (last !== undefined && (now - last) < RATE_LIMIT_MS && lastKnownState.get(teamInfo.teamId) === currentMarker) {
     return "No changes since last check."
   }
   lastCallTime.set(teamInfo.teamId, now)
+  lastKnownState.set(teamInfo.teamId, currentMarker)
 
   const members = deps.db.query(
-    "SELECT name, session_id, agent, status, execution_status, worktree_branch, worktree_dir, plan_approval, time_updated FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
+    "SELECT name, session_id, agent, status, execution_status, worktree_branch, worktree_dir, plan_approval, time_updated, last_nudged_at, retry_until, retry_attempt FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
   ).all(teamInfo.teamId) as Array<{
-    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; worktree_dir: string | null; plan_approval: string; time_updated: number
+    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; worktree_dir: string | null; plan_approval: string; time_updated: number; last_nudged_at: number | null
+    retry_until: number | null; retry_attempt: number | null
   }>
 
   const tasks = deps.db.query(
@@ -52,13 +77,22 @@ export async function executeTeamStatus(
       const duration = formatDuration(now - m.time_updated)
       const branch = m.worktree_branch ? `  branch: ${m.worktree_branch}` : ""
       const plan = m.plan_approval !== "none" ? `, plan: ${m.plan_approval}` : ""
+      // Additive display-staleness annotation (Fix 1) — surfaces a soft stall-nudge
+      // without inventing a new status value. Annotates the existing status, doesn't
+      // replace it.
+      const nudged = m.last_nudged_at ? `, nudged ${formatDuration(now - m.last_nudged_at)} ago` : ""
+      // Additive provider-retry annotation (Fix 4) — derived at read time from the
+      // retry_until TTL (Fix 3), same annotation pattern as `nudged` above. Generic
+      // "retrying" label, no rate-limit-specific wording (Fix 2).
+      const isRetrying = m.retry_until !== null && m.retry_until > now
+      const retrying = isRetrying ? `, retrying (attempt ${m.retry_attempt}, ~${formatDuration(m.retry_until! - now)})` : ""
 
       // Last message time
       const lastMsg = deps.db.query("SELECT MAX(time_created) as last_msg FROM team_message WHERE team_id = ? AND from_name = ?")
         .get(teamInfo.teamId, m.name) as { last_msg: number | null } | null
       const msgInfo = lastMsg?.last_msg ? `last msg: ${formatDuration(now - lastMsg.last_msg)} ago` : "no messages yet"
 
-      lines.push(`  ${m.name}  [${statusIcon} ${duration}, ${msgInfo}${plan}]  agent: ${m.agent}${branch}`)
+      lines.push(`  ${m.name}  [${statusIcon} ${duration}, ${msgInfo}${plan}${nudged}${retrying}]  agent: ${m.agent}${branch}`)
 
       // Current task
       const task = deps.db.query("SELECT content FROM team_task WHERE team_id = ? AND assignee = ? AND status = 'in_progress' LIMIT 1")

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { Database } from "./db"
 import type { MemberRegistry, DescendantTracker, PendingPurgeApprovals } from "./state"
 import type { EnsembleConfig } from "./config"
+import type { ProgressTracker } from "./progress"
 
 /**
  * Shared dependencies injected into every tool's execute function.
@@ -17,6 +18,8 @@ export interface ToolDeps {
   directory: string
   /** Plugin configuration. */
   config: Required<EnsembleConfig>
+  /** Stall/activity tracker — shared with the Watchdog. */
+  progressTracker: ProgressTracker
 }
 
 /** A single permission rule for session-level enforcement. */