@hueyexe/opencode-ensemble 0.1.0

package/src/recovery.ts

@@ -0,0 +1,71 @@
+import type { Database } from "bun:sqlite"
+import type { PluginClient } from "./types"
+import type { MemberRegistry } from "./state"
+import { getUndeliveredMessages, markDelivered } from "./messaging"
+
+/**
+ * Scan for team members stuck in 'busy' status (stale from a crash)
+ * and mark them as 'error' with execution_status 'idle'.
+ * Only processes members in active teams.
+ * Returns the count of interrupted members.
+ */
+export function recoverStaleMembers(db: Database): { interrupted: number } {
+  const result = db.run(
+    `UPDATE team_member SET status = 'error', execution_status = 'idle', time_updated = ?
+     WHERE status = 'busy'
+       AND team_id IN (SELECT id FROM team WHERE status = 'active')`,
+    [Date.now()]
+  )
+  return { interrupted: result.changes }
+}
+
+/**
+ * Redeliver undelivered messages (delivered=0) via promptAsync.
+ * Resolves recipient session IDs from the member registry or team lead.
+ * Continues on partial failure — logs but doesn't abort.
+ */
+export async function recoverUndeliveredMessages(
+  db: Database,
+  client: PluginClient,
+  registry: MemberRegistry,
+): Promise<{ redelivered: number }> {
+  // Get all active teams
+  const teams = db.query("SELECT id, lead_session_id FROM team WHERE status = 'active'")
+    .all() as Array<{ id: string; lead_session_id: string }>
+
+  let redelivered = 0
+
+  for (const team of teams) {
+    const messages = getUndeliveredMessages(db, team.id)
+
+    for (const msg of messages) {
+      // Resolve recipient session ID
+      let recipientSessionId: string | undefined
+
+      if (msg.to_name === "lead") {
+        recipientSessionId = team.lead_session_id
+      } else if (msg.to_name) {
+        const entry = registry.getByName(team.id, msg.to_name)
+        recipientSessionId = entry?.sessionId
+      } else {
+        // Broadcast — skip for now, broadcasts are best-effort
+        continue
+      }
+
+      if (!recipientSessionId) continue
+
+      try {
+        await client.session.promptAsync({
+          path: { id: recipientSessionId },
+          body: { parts: [{ type: "text", text: `[Recovered team message from ${msg.from_name}]: ${msg.content}` }] },
+        })
+        markDelivered(db, msg.id)
+        redelivered++
+      } catch {
+        // Continue on failure — message stays undelivered for next recovery
+      }
+    }
+  }
+
+  return { redelivered }
+}

package/src/schema.ts

@@ -0,0 +1,83 @@
+import type { Database } from "bun:sqlite"
+
+/** Migration SQL statements, applied in order. Version = index + 1. */
+export const MIGRATIONS: string[] = [
+  // Migration 1: Initial schema — 4 tables
+  `
+  CREATE TABLE IF NOT EXISTS team (
+    id              TEXT PRIMARY KEY,
+    name            TEXT NOT NULL UNIQUE,
+    lead_session_id TEXT NOT NULL,
+    status          TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'archived')),
+    delegate        INTEGER NOT NULL DEFAULT 0,
+    time_created    INTEGER NOT NULL,
+    time_updated    INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS team_lead_idx ON team(lead_session_id);
+  CREATE INDEX IF NOT EXISTS team_status_idx ON team(status);
+
+  CREATE TABLE IF NOT EXISTS team_member (
+    team_id          TEXT NOT NULL REFERENCES team(id) ON DELETE CASCADE,
+    name             TEXT NOT NULL,
+    session_id       TEXT NOT NULL,
+    agent            TEXT NOT NULL,
+    status           TEXT NOT NULL DEFAULT 'ready'
+                       CHECK(status IN ('ready', 'busy', 'shutdown_requested', 'shutdown', 'error')),
+    execution_status TEXT NOT NULL DEFAULT 'idle'
+                       CHECK(execution_status IN ('idle', 'starting', 'running',
+                         'cancel_requested', 'cancelling', 'cancelled',
+                         'completing', 'completed', 'failed', 'timed_out')),
+    model            TEXT,
+    prompt           TEXT,
+    time_created     INTEGER NOT NULL,
+    time_updated     INTEGER NOT NULL,
+    PRIMARY KEY (team_id, name)
+  );
+  CREATE INDEX IF NOT EXISTS team_member_session_idx ON team_member(session_id);
+  CREATE INDEX IF NOT EXISTS team_member_status_idx ON team_member(team_id, status);
+
+  CREATE TABLE IF NOT EXISTS team_task (
+    id            TEXT PRIMARY KEY,
+    team_id       TEXT NOT NULL REFERENCES team(id) ON DELETE CASCADE,
+    content       TEXT NOT NULL,
+    status        TEXT NOT NULL DEFAULT 'pending'
+                    CHECK(status IN ('pending', 'in_progress', 'completed', 'cancelled', 'blocked')),
+    priority      TEXT NOT NULL DEFAULT 'medium'
+                    CHECK(priority IN ('high', 'medium', 'low')),
+    assignee      TEXT,
+    depends_on    TEXT,
+    time_created  INTEGER NOT NULL,
+    time_updated  INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS team_task_team_idx ON team_task(team_id);
+  CREATE INDEX IF NOT EXISTS team_task_assignee_idx ON team_task(assignee);
+  CREATE INDEX IF NOT EXISTS team_task_status_idx ON team_task(team_id, status);
+
+  CREATE TABLE IF NOT EXISTS team_message (
+    id            TEXT PRIMARY KEY,
+    team_id       TEXT NOT NULL REFERENCES team(id) ON DELETE CASCADE,
+    from_name     TEXT NOT NULL,
+    to_name       TEXT,
+    content       TEXT NOT NULL,
+    delivered     INTEGER NOT NULL DEFAULT 0,
+    time_created  INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS team_message_team_idx ON team_message(team_id);
+  CREATE INDEX IF NOT EXISTS team_message_to_idx ON team_message(to_name);
+  CREATE INDEX IF NOT EXISTS team_message_undelivered_idx ON team_message(team_id, delivered)
+    WHERE delivered = 0;
+  `,
+]
+
+/**
+ * Apply pending migrations to the database.
+ * Uses PRAGMA user_version to track which migrations have been applied.
+ */
+export function applyMigrations(db: Database): void {
+  const { user_version: current } = db.query("PRAGMA user_version").get() as { user_version: number }
+
+  for (let i = current; i < MIGRATIONS.length; i++) {
+    db.exec(MIGRATIONS[i]!)
+    db.exec(`PRAGMA user_version = ${i + 1}`)
+  }
+}

package/src/state.ts

@@ -0,0 +1,103 @@
+/** Info about a registered team member in the in-memory registry. */
+export interface MemberEntry {
+  teamId: string
+  memberName: string
+  sessionId: string
+}
+
+/**
+ * In-memory registry of team members, indexed by sessionID and by (teamId, name).
+ * This is the fast-path lookup used by hooks and tools — SQLite is the source of truth.
+ */
+export class MemberRegistry {
+  private bySession = new Map<string, MemberEntry>()
+  private byTeamName = new Map<string, MemberEntry>()
+
+  /** Register a member. */
+  register(teamId: string, name: string, sessionId: string): void {
+    const entry: MemberEntry = { teamId, memberName: name, sessionId }
+    this.bySession.set(sessionId, entry)
+    this.byTeamName.set(`${teamId}:${name}`, entry)
+  }
+
+  /** Look up a member by session ID. */
+  getBySession(sessionId: string): MemberEntry | undefined {
+    return this.bySession.get(sessionId)
+  }
+
+  /** Look up a member by team ID and name. */
+  getByName(teamId: string, name: string): MemberEntry | undefined {
+    return this.byTeamName.get(`${teamId}:${name}`)
+  }
+
+  /** List all members for a team. */
+  listByTeam(teamId: string): MemberEntry[] {
+    const result: MemberEntry[] = []
+    for (const entry of this.bySession.values()) {
+      if (entry.teamId === teamId) result.push(entry)
+    }
+    return result
+  }
+
+  /** Remove a member by session ID. */
+  unregister(sessionId: string): void {
+    const entry = this.bySession.get(sessionId)
+    if (!entry) return
+    this.bySession.delete(sessionId)
+    this.byTeamName.delete(`${entry.teamId}:${entry.memberName}`)
+  }
+
+  /** Remove all members for a team. */
+  unregisterTeam(teamId: string): void {
+    for (const entry of this.listByTeam(teamId)) {
+      this.bySession.delete(entry.sessionId)
+      this.byTeamName.delete(`${teamId}:${entry.memberName}`)
+    }
+  }
+
+  /** Check if a session ID belongs to a registered team member. */
+  isTeamSession(sessionId: string): boolean {
+    return this.bySession.has(sessionId)
+  }
+}
+
+const DEFAULT_MAX_DEPTH = 10
+
+/**
+ * Tracks parent-child session relationships for sub-agent isolation.
+ * Used to walk the parent chain and determine if a session is a descendant
+ * of a team member session.
+ */
+export class DescendantTracker {
+  private parents = new Map<string, string>()
+
+  /** Record that childId's parent is parentId. */
+  track(childId: string, parentId: string): void {
+    this.parents.set(childId, parentId)
+  }
+
+  /** Get the parent of a session. */
+  getParent(sessionId: string): string | undefined {
+    return this.parents.get(sessionId)
+  }
+
+  /**
+   * Walk the parent chain from sessionId. Returns true if any ancestor
+   * (up to maxDepth) is in the given set of session IDs.
+   */
+  isDescendantOf(sessionId: string, ancestors: Set<string>, maxDepth = DEFAULT_MAX_DEPTH): boolean {
+    let current = sessionId
+    for (let i = 0; i < maxDepth; i++) {
+      const parent = this.parents.get(current)
+      if (!parent) return false
+      if (ancestors.has(parent)) return true
+      current = parent
+    }
+    return false
+  }
+
+  /** Remove a session from tracking. */
+  remove(sessionId: string): void {
+    this.parents.delete(sessionId)
+  }
+}

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

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

package/src/tools/team-broadcast.ts

@@ -0,0 +1,59 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession } from "../types"
+import { broadcastMessage, markDelivered } from "../messaging"
+
+/**
+ * Execute the team_broadcast tool. Sends a message to all team members + lead (excluding sender).
+ */
+export async function executeTeamBroadcast(
+  deps: ToolDeps,
+  args: { text: string },
+  sessionId: string,
+): Promise<string> {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
+
+  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName!
+
+  const msgId = broadcastMessage(deps.db, {
+    teamId: teamInfo.teamId,
+    from: senderName,
+    content: args.text,
+  })
+
+  // Collect all recipient session IDs (excluding sender)
+  const recipients: Array<{ name: string; sessionId: string }> = []
+
+  // Add lead if sender is not lead
+  if (teamInfo.role !== "lead") {
+    const leadSession = deps.db.query("SELECT lead_session_id FROM team WHERE id = ?")
+      .get(teamInfo.teamId) as { lead_session_id: string } | null
+    if (leadSession) recipients.push({ name: "lead", sessionId: leadSession.lead_session_id })
+  }
+
+  // Add all members except sender
+  const members = deps.registry.listByTeam(teamInfo.teamId)
+  for (const member of members) {
+    if (member.sessionId !== sessionId) {
+      recipients.push({ name: member.memberName, sessionId: member.sessionId })
+    }
+  }
+
+  // Deliver to all recipients — partial failures logged but don't fail the broadcast
+  let delivered = 0
+  for (const recipient of recipients) {
+    try {
+      await deps.client.session.promptAsync({
+        path: { id: recipient.sessionId },
+        body: { parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }] },
+      })
+      delivered++
+    } catch {
+      // Log but don't fail
+    }
+  }
+
+  markDelivered(deps.db, msgId)
+
+  return `Broadcast sent to ${delivered} recipient${delivered !== 1 ? "s" : ""}.`
+}

package/src/tools/team-claim.ts

@@ -0,0 +1,36 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession } from "../types"
+
+/**
+ * Execute the team_claim tool. Atomically claims a pending task.
+ * Rejects if the task is already claimed, blocked, or not pending.
+ */
+export async function executeTeamClaim(
+  deps: ToolDeps,
+  args: { task_id: string },
+  sessionId: string,
+): Promise<string> {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team.")
+
+  const claimerName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName!
+
+  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}`
+}

package/src/tools/team-cleanup.ts

@@ -0,0 +1,45 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession } from "../types"
+
+/**
+ * Execute the team_cleanup tool. Archives the team and cleans up resources.
+ * If force=true, aborts all active member sessions first.
+ */
+export async function executeTeamCleanup(
+  deps: ToolDeps,
+  args: { force: boolean },
+  sessionId: string,
+): Promise<string> {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team.")
+  if (teamInfo.role !== "lead") throw new Error("Only the team lead can clean up the team.")
+
+  const members = deps.db.query("SELECT name, session_id, status FROM team_member WHERE team_id = ?")
+    .all(teamInfo.teamId) as Array<{ name: string; session_id: string; status: string }>
+
+  const active = members.filter(m => m.status !== "shutdown")
+
+  if (active.length > 0 && !args.force) {
+    const names = active.map(m => m.name).join(", ")
+    throw new Error(`Cannot clean up team "${teamInfo.teamName}": ${active.length} member(s) still active: ${names}. Use team_shutdown on each member first, or call team_cleanup with force: true to abort them immediately.`)
+  }
+
+  // Force-abort active members
+  if (args.force) {
+    for (const member of active) {
+      try {
+        await deps.client.session.abort({ path: { id: member.session_id } })
+      } catch {
+        // Best effort
+      }
+    }
+  }
+
+  // Archive team
+  deps.db.run("UPDATE team SET status = 'archived', time_updated = ? WHERE id = ?", [Date.now(), teamInfo.teamId])
+
+  // Clean up registry
+  deps.registry.unregisterTeam(teamInfo.teamId)
+
+  return `Team "${teamInfo.teamName}" cleaned up.`
+}

package/src/tools/team-create.ts

@@ -0,0 +1,32 @@
+import type { ToolDeps } from "../types"
+import { generateId, validateTeamName } from "../util"
+import { findTeamBySession } from "../types"
+
+/**
+ * Execute the team_create tool. Creates a new team with the caller as lead.
+ */
+export async function executeTeamCreate(
+  deps: ToolDeps,
+  args: { name: string },
+  sessionId: string,
+): Promise<string> {
+  const nameError = validateTeamName(args.name)
+  if (nameError) throw new Error(nameError)
+
+  // Check if team name already exists
+  const existing = deps.db.query("SELECT id FROM team WHERE name = ? AND status = 'active'").get(args.name)
+  if (existing) throw new Error(`Team "${args.name}" already exists`)
+
+  // Check if session already leads a team
+  const lead = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (lead) throw new Error(`This session already belongs to team "${lead.teamName}"`)
+
+  const id = generateId("team")
+  const now = Date.now()
+  deps.db.run(
+    "INSERT INTO team (id, name, lead_session_id, status, delegate, time_created, time_updated) VALUES (?, ?, ?, 'active', 0, ?, ?)",
+    [id, args.name, sessionId, now, now]
+  )
+
+  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates.`
+}

package/src/tools/team-message.ts

@@ -0,0 +1,37 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession, resolveRecipientSession } from "../types"
+import { sendMessage, markDelivered } from "../messaging"
+
+/**
+ * Execute the team_message tool. Sends a direct message to a teammate or lead.
+ */
+export async function executeTeamMessage(
+  deps: ToolDeps,
+  args: { to: string; text: string },
+  sessionId: string,
+): Promise<string> {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
+
+  const senderName = teamInfo.role === "lead" ? "lead" : teamInfo.memberName!
+
+  const recipientSessionId = resolveRecipientSession(deps.db, deps.registry, teamInfo.teamId, args.to)
+  if (!recipientSessionId) throw new Error(`Recipient "${args.to}" not found in team "${teamInfo.teamName}"`)
+
+  const msgId = sendMessage(deps.db, {
+    teamId: teamInfo.teamId,
+    from: senderName,
+    to: args.to,
+    content: args.text,
+  })
+
+  // Deliver via promptAsync
+  await deps.client.session.promptAsync({
+    path: { id: recipientSessionId },
+    body: { parts: [{ type: "text", text: `[Team message from ${senderName}]: ${args.text}` }] },
+  })
+
+  markDelivered(deps.db, msgId)
+
+  return `Message sent to ${args.to}.`
+}

package/src/tools/team-shutdown.ts

@@ -0,0 +1,51 @@
+import type { ToolDeps } from "../types"
+import { findTeamBySession } from "../types"
+
+/**
+ * Execute the team_shutdown tool. Requests a teammate to shut down.
+ * Sets status to shutdown_requested, calls abort, then polls session status.
+ * If the session is already idle after abort, transitions directly to shutdown.
+ * Otherwise the event hook handles the transition when the session goes idle.
+ */
+export async function executeTeamShutdown(
+  deps: ToolDeps,
+  args: { member: string },
+  sessionId: string,
+): Promise<string> {
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team.")
+  if (teamInfo.role !== "lead") throw new Error("Only the team lead can shut down teammates.")
+
+  const member = deps.db.query("SELECT session_id, status FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamInfo.teamId, args.member) as { session_id: string; status: string } | null
+  if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
+  if (member.status === "shutdown") throw new Error(`Teammate "${args.member}" is already shut down`)
+
+  // Set to shutdown_requested
+  deps.db.run(
+    "UPDATE team_member SET status = 'shutdown_requested', time_updated = ? WHERE team_id = ? AND name = ?",
+    [Date.now(), teamInfo.teamId, args.member]
+  )
+
+  // Call abort on the member's session
+  await deps.client.session.abort({ path: { id: member.session_id } })
+
+  // Fallback: poll session status after abort. If already idle, transition
+  // directly to shutdown. This handles the case where abort() on an
+  // already-idle session doesn't fire a session.status event.
+  try {
+    const statuses = await deps.client.session.status()
+    const sessionStatus = statuses.data?.[member.session_id]
+    if (!sessionStatus || sessionStatus.type === "idle") {
+      deps.db.run(
+        "UPDATE team_member SET status = 'shutdown', execution_status = 'idle', time_updated = ? WHERE team_id = ? AND name = ?",
+        [Date.now(), teamInfo.teamId, args.member]
+      )
+      return `Teammate "${args.member}" has been shut down.`
+    }
+  } catch {
+    // Status poll failed — fall through to eventual consistency
+  }
+
+  return `Shutdown requested for ${args.member}. Will complete when current work finishes.`
+}

package/src/tools/team-spawn.ts

@@ -0,0 +1,77 @@
+import type { ToolDeps } from "../types"
+import { generateId, validateMemberName } from "../util"
+import { findTeamBySession } from "../types"
+
+/**
+ * Execute the team_spawn tool. Creates a child session and starts a teammate.
+ */
+export async function executeTeamSpawn(
+  deps: ToolDeps,
+  args: { name: string; agent: string; prompt: string; model?: string; claim_task?: string },
+  sessionId: string,
+): Promise<string> {
+  const nameError = validateMemberName(args.name)
+  if (nameError) throw new Error(nameError)
+
+  const teamInfo = findTeamBySession(deps.db, deps.registry, sessionId)
+  if (!teamInfo) throw new Error("This session is not in a team. Use team_create first.")
+  if (teamInfo.role !== "lead") throw new Error("Only the team lead can spawn teammates.")
+
+  // Check duplicate name
+  const existing = deps.db.query("SELECT name FROM team_member WHERE team_id = ? AND name = ?")
+    .get(teamInfo.teamId, args.name)
+  if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
+
+  // Create child session via SDK
+  const createResult = await deps.client.session.create({
+    body: { parentID: sessionId, title: `${args.name} (@${args.agent} teammate)` },
+  })
+  const childSessionId = createResult.data?.id
+  if (!childSessionId) throw new Error("Failed to create teammate session")
+
+  // Register in DB
+  const now = Date.now()
+  deps.db.run(
+    `INSERT INTO team_member (team_id, name, session_id, agent, status, execution_status, model, prompt, time_created, time_updated)
+     VALUES (?, ?, ?, ?, 'busy', 'starting', ?, ?, ?, ?)`,
+    [teamInfo.teamId, args.name, childSessionId, args.agent, args.model ?? null, args.prompt, now, now]
+  )
+
+  // Register in memory
+  deps.registry.register(teamInfo.teamId, args.name, childSessionId)
+
+  // Build teammate context message per AGENTS.md Teammate Context Message Design
+  const context = [
+    `You are "${args.name}", a teammate in team "${teamInfo.teamName}".`,
+    `Your agent type is "${args.agent}".`,
+    "",
+    "Tools available to you:",
+    "- team_message: send a message to the lead or another teammate",
+    "- team_broadcast: send a message to all team members",
+    "- team_tasks_list: view the shared team task board",
+    "- team_tasks_add: add tasks to the shared board",
+    "- team_tasks_complete: mark a task complete on the shared board",
+    "- team_claim: claim a pending task from the shared board",
+    "",
+    "When you finish your task:",
+    "1. Send ONE message to the lead with your findings using team_message.",
+    "2. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
+    "",
+    "If you are blocked, send ONE message to the lead describing the specific blocker.",
+    "",
+    "Your plain text output is NOT visible to the team. You MUST use team_message to communicate.",
+    "",
+    "Your task:",
+    args.prompt,
+  ].join("\n")
+
+  // Fire-and-forget: send prompt to teammate session
+  // OQ-1: assuming promptAsync queues when session is busy
+  // OQ-10: assuming fresh session accepts promptAsync without session.init()
+  await deps.client.session.promptAsync({
+    path: { id: childSessionId },
+    body: { parts: [{ type: "text", text: context }] },
+  })
+
+  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""}`
+}