@hueyexe/opencode-ensemble 0.16.0 → 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-claim.ts

@@ -1,6 +1,37 @@
+import type { Database } from "../db"
 import type { ToolDeps } from "../types"
 import { requireTeamMember } from "./shared"
 
+/**
+ * Atomically claim a pending task for an assignee. Sets status to
+ * 'in_progress' and records the assignee. Throws if the task is missing,
+ * blocked, already claimed, or no longer pending. Returns the task content
+ * on success.
+ *
+ * Shared by team_claim and team_spawn's claim_task auto-claim so both paths
+ * enforce the same atomic claim invariant.
+ */
+export function claimTask(db: Database, teamId: string, taskId: string, assignee: string): string {
+  const task = db.query("SELECT content, status, assignee FROM team_task WHERE id = ? AND team_id = ?")
+    .get(taskId, teamId) as { content: string; status: string; assignee: string | null } | null
+  if (!task) throw new Error(`Task "${taskId}" not found`)
+  if (task.status === "blocked") throw new Error(`Task "${taskId}" is blocked by unresolved dependencies`)
+  if (task.status !== "pending") throw new Error(`Task "${taskId}" is not pending (status: ${task.status})`)
+  if (task.assignee) throw new Error(`Task "${taskId}" is already claimed by ${task.assignee}`)
+
+  // Atomic claim: UPDATE only if still pending and unassigned
+  const result = db.run(
+    "UPDATE team_task SET status = 'in_progress', assignee = ?, time_updated = ? WHERE id = ? AND status = 'pending' AND assignee IS NULL",
+    [assignee, Date.now(), taskId]
+  )
+
+  if (result.changes === 0) {
+    throw new Error(`Task "${taskId}" is already claimed (race condition)`)
+  }
+
+  return task.content
+}
+
 /**
  * Execute the team_claim tool. Atomically claims a pending task.
  * Rejects if the task is already claimed, blocked, or not pending.
@@ -13,23 +44,7 @@ export async function executeTeamClaim(
   const teamInfo = requireTeamMember(deps, sessionId)
 
   const claimerName = teamInfo.role === "lead" ? "lead" : (teamInfo.memberName ?? "unknown")
+  const content = claimTask(deps.db, teamInfo.teamId, args.task_id, claimerName)
 
-  const task = deps.db.query("SELECT * FROM team_task WHERE id = ? AND team_id = ?")
-    .get(args.task_id, teamInfo.teamId) as Record<string, unknown> | null
-  if (!task) throw new Error(`Task "${args.task_id}" not found`)
-  if (task.status === "blocked") throw new Error(`Task "${args.task_id}" is blocked by unresolved dependencies`)
-  if (task.status !== "pending") throw new Error(`Task "${args.task_id}" is not pending (status: ${task.status})`)
-  if (task.assignee) throw new Error(`Task "${args.task_id}" is already claimed by ${task.assignee}`)
-
-  // Atomic claim: UPDATE only if still pending and unassigned
-  const result = deps.db.run(
-    "UPDATE team_task SET status = 'in_progress', assignee = ?, time_updated = ? WHERE id = ? AND status = 'pending' AND assignee IS NULL",
-    [claimerName, Date.now(), args.task_id]
-  )
-
-  if (result.changes === 0) {
-    throw new Error(`Task "${args.task_id}" is already claimed (race condition)`)
-  }
-
-  return `Claimed task: ${task.content}`
+  return `Claimed task: ${content}`
 }

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

@@ -1,7 +1,10 @@
 import type { ToolDeps, PermissionRule } from "../types"
 import { validateMemberName } from "../util"
 import { requireLead } from "./shared"
-import { sendMessage } from "../messaging"
+import { claimTask } from "./team-claim"
+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"
@@ -9,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.
@@ -67,9 +63,14 @@ function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise
  */
 export async function executeTeamSpawn(
   deps: ToolDeps,
-  args: { name: string; agent: string; prompt: string; model?: string; claim_task?: string; worktree?: boolean; plan_approval?: boolean },
+  args: { name: string; agent?: string | null; prompt: string; model?: string; claim_task?: string; worktree?: boolean; plan_approval?: boolean },
   sessionId: string,
 ): Promise<string> {
+  // Normalize agent: the tool schema defaults to "build", but Zod's .default()
+  // only fires on undefined — an explicit null slips through and would violate
+  // the team_member.agent NOT NULL constraint (issue #28).
+  const agent = args.agent ?? "build"
+
   const nameError = validateMemberName(args.name)
   if (nameError) throw new Error(nameError)
 
@@ -86,11 +87,11 @@ export async function executeTeamSpawn(
     .get(teamInfo.teamId, args.name)
   if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
 
-  const isReadOnly = args.agent === "plan" || args.agent === "explore"
+  const isReadOnly = agent === "plan" || agent === "explore"
   const useWorktree = args.worktree !== false && !isReadOnly && !isWorktreeDirectory(deps.directory)
   const usePlanApproval = args.plan_approval === true
 
-  log(`spawn:start name=${args.name} agent=${args.agent} worktree=${useWorktree}`)
+  log(`spawn:start name=${args.name} agent=${agent} worktree=${useWorktree}`)
 
   // Create worktree if enabled
   let worktreeDir: string | null = null
@@ -177,7 +178,7 @@ export async function executeTeamSpawn(
     const createResult = await withTimeout(
       deps.client.session.create({
         parentID: sessionId,
-        title: `${args.name} (@${args.agent} teammate)`,
+        title: `${args.name} (@${agent} teammate)`,
         permission,
         ...(workspaceId ? { workspaceID: workspaceId } : {}),
       }),
@@ -216,22 +217,43 @@ export async function executeTeamSpawn(
   const now = Date.now()
   // Resolve model before DB insert so the stored value matches what promptAsync uses
   const memberCount = (deps.db.query("SELECT COUNT(*) as c FROM team_member WHERE team_id = ?").get(teamInfo.teamId) as { c: number }).c
-  const resolvedModel = resolveModel(args.model, args.agent, memberCount, deps.config)
+  const resolvedModel = resolveModel(args.model, agent, memberCount, deps.config)
   if (resolvedModel) log(`spawn:model name=${args.name} model=${resolvedModel}`)
 
   deps.db.run(
     `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, worktree_dir, worktree_branch, workspace_id, plan_approval, time_created, time_updated)
      VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?, ?, ?, ?, ?)`,
-    [teamInfo.teamId, args.name, childSessionId, args.agent, resolvedModel ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]
+    [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)
 
+  // Auto-claim a task for this teammate when claim_task is provided (issue #27).
+  // Claims atomically so a task is never double-assigned when the lead hands out
+  // more tasks than there are teammates. Read-only agents cannot claim tasks.
+  let claimedTaskContent: string | null = null
+  let claimWarning: string | null = null
+  if (args.claim_task && !isReadOnly) {
+    try {
+      claimedTaskContent = claimTask(deps.db, teamInfo.teamId, args.claim_task, args.name)
+      log(`spawn:claim:ok name=${args.name} task=${args.claim_task}`)
+    } catch (err) {
+      claimWarning = err instanceof Error ? err.message : String(err)
+      log(`spawn:claim:failed name=${args.name} task=${args.claim_task} err=${claimWarning}`)
+    }
+  }
+
   // Build teammate context message
   const context = [
     `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
-    `Your agent type is "${args.agent}".`,
+    `Your agent type is "${agent}".`,
   ]
 
   // Show other teammates so this agent knows who to message
@@ -347,7 +369,7 @@ export async function executeTeamSpawn(
     args.prompt,
   )
 
-  if (args.claim_task) {
+  if (claimedTaskContent) {
     context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`)
   }
 
@@ -364,7 +386,7 @@ export async function executeTeamSpawn(
   deps.client.session.promptAsync({
     sessionID: childSessionId,
     parts: [{ type: "text", text: contextStr }],
-    agent: args.agent,
+    agent,
     ...(modelParam ? { model: modelParam } : {}),
   }).catch((err) => {
     const errMsg = err instanceof Error ? err.message : String(err)
@@ -372,6 +394,13 @@ export async function executeTeamSpawn(
     try {
       deps.db.run("DELETE FROM team_member WHERE team_id = ? AND session_id = ?", [teamInfo.teamId, childSessionId])
       deps.registry.unregister(childSessionId)
+      // 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 = ? AND status = 'in_progress'",
+          [Date.now(), args.claim_task, args.name]
+        )
+      }
       deps.client.session.abort({ sessionID: childSessionId }).catch(() => { /* best effort */ })
       if (workspaceId) {
         deps.client.workspace.remove({ id: workspaceId }).catch(() => { /* best effort */ })
@@ -386,19 +415,22 @@ 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 */ }
   })
 
   const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
   const planInfo = usePlanApproval ? " [plan mode — will send plan for approval]" : ""
+  const claimInfo = claimedTaskContent
+    ? ` (claimed task: ${args.claim_task})`
+    : claimWarning ? ` (could not claim task: ${claimWarning})` : ""
   // Reset circuit breaker on success
   spawnFailures.delete(teamInfo.teamId)
   log(`spawn:done name=${args.name} sessionId=${childSessionId}`)
-  return `Teammate "${args.name}" spawned (agent: ${args.agent})${branchInfo}${planInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
+  return `Teammate "${args.name}" spawned (agent: ${agent})${branchInfo}${planInfo}${claimInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
 }