clawport-ui 0.5.1 → 0.5.2

package/lib/agents-registry.ts

@@ -111,6 +111,25 @@ function scanSubAgentDir(dirPath: string): { fileName: string; content: string }
   }
 }
 
+/**
+ * Scan a parent agent directory for child subdirectories containing SOUL.md.
+ * Skips sub-agents/ and members/ (already handled by scanSubAgentDir).
+ */
+function scanSubdirAgents(parentDir: string): { dirName: string; content: string }[] {
+  if (!existsSync(parentDir)) return []
+  try {
+    return readdirSync(parentDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== 'sub-agents' && e.name !== 'members')
+      .map(e => {
+        const content = safeRead(join(parentDir, e.name, 'SOUL.md'))
+        return content ? { dirName: e.name, content } : null
+      })
+      .filter((x): x is { dirName: string; content: string } => x !== null)
+  } catch {
+    return []
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Auto-discovery
 // ---------------------------------------------------------------------------
@@ -147,6 +166,7 @@ function discoverAgents(workspacePath: string): AgentEntry[] | null {
 
   const discovered: AgentEntry[] = []
   let colorIndex = 0
+  const directReportIds: string[] = []
 
   // --- Root agent ---
   let rootId = 'main'
@@ -177,9 +197,6 @@ function discoverAgents(workspacePath: string): AgentEntry[] | null {
       }
     }
 
-    // Collect all agent IDs that report to root (including those without SOUL.md but with sub-agents)
-    const directReportIds: string[] = []
-
     discovered.push({
       id: rootId,
       name: rootName,
@@ -197,6 +214,7 @@ function discoverAgents(workspacePath: string): AgentEntry[] | null {
 
     // We'll fill directReportIds as we discover agents below
     for (const dirName of allAgentDirs) {
+      if (dirName === rootId) continue // root-matching dir scanned in main loop
       const hasSoul = existsSync(join(agentsDir, dirName, 'SOUL.md'))
       const hasSubAgents = existsSync(join(agentsDir, dirName, 'sub-agents'))
       const hasMembers = existsSync(join(agentsDir, dirName, 'members'))
@@ -208,8 +226,61 @@ function discoverAgents(workspacePath: string): AgentEntry[] | null {
 
   // --- Top-level agents ---
   for (const dirName of allAgentDirs) {
-    // Skip if directory name matches the root agent ID (already added above)
-    if (hasRoot && dirName === rootId) continue
+    // Root-matching directory: scan for sub-agents but don't create a duplicate root entry
+    if (hasRoot && dirName === rootId) {
+      const rootAgentDir = join(agentsDir, dirName)
+      const rootSubFiles = [
+        ...scanSubAgentDir(join(rootAgentDir, 'sub-agents')),
+        ...scanSubAgentDir(join(rootAgentDir, 'members')),
+      ]
+      const rootSubIds = new Set<string>()
+      for (const sub of rootSubFiles) {
+        const subId = `${rootId}-${basename(sub.fileName, '.md').toLowerCase()}`
+        rootSubIds.add(subId)
+        directReportIds.push(subId)
+        const subParsed = parseSoulHeading(sub.content)
+        const subName = subParsed.name || slugToName(basename(sub.fileName, '.md'))
+        const subTitle = subParsed.title || 'Agent'
+        discovered.push({
+          id: subId,
+          name: subName,
+          title: subTitle,
+          reportsTo: rootId,
+          directReports: [],
+          soulPath: null,
+          voiceId: null,
+          color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
+          emoji: subName.charAt(0).toUpperCase(),
+          tools: ['read', 'write'],
+          memoryPath: null,
+          description: `${subName} agent.`,
+        })
+      }
+
+      for (const sub of scanSubdirAgents(rootAgentDir)) {
+        const subId = `${rootId}-${sub.dirName}`
+        if (rootSubIds.has(subId)) continue
+        directReportIds.push(subId)
+        const subParsed = parseSoulHeading(sub.content)
+        const subName = subParsed.name || slugToName(sub.dirName)
+        const subTitle = subParsed.title || 'Agent'
+        discovered.push({
+          id: subId,
+          name: subName,
+          title: subTitle,
+          reportsTo: rootId,
+          directReports: [],
+          soulPath: `agents/${rootId}/${sub.dirName}/SOUL.md`,
+          voiceId: null,
+          color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
+          emoji: subName.charAt(0).toUpperCase(),
+          tools: ['read', 'write'],
+          memoryPath: null,
+          description: `${subName} agent.`,
+        })
+      }
+      continue
+    }
 
     const soulFile = join(agentsDir, dirName, 'SOUL.md')
     const hasSoul = existsSync(soulFile)
@@ -277,6 +348,32 @@ function discoverAgents(workspacePath: string): AgentEntry[] | null {
       })
     }
 
+    // Discover subdirectory agents (child dirs with SOUL.md)
+    const subdirAgents = scanSubdirAgents(join(agentsDir, dirName))
+    const existingSubIds = new Set(subAgentIds)
+    for (const sub of subdirAgents) {
+      const subId = `${dirName}-${sub.dirName}`
+      if (existingSubIds.has(subId)) continue
+      subAgentIds.push(subId)
+      const subParsed = parseSoulHeading(sub.content)
+      const subName = subParsed.name || slugToName(sub.dirName)
+      const subTitle = subParsed.title || 'Agent'
+      discovered.push({
+        id: subId,
+        name: subName,
+        title: subTitle,
+        reportsTo: dirName,
+        directReports: [],
+        soulPath: `agents/${dirName}/${sub.dirName}/SOUL.md`,
+        voiceId: null,
+        color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
+        emoji: subName.charAt(0).toUpperCase(),
+        tools: ['read', 'write'],
+        memoryPath: null,
+        description: `${subName} agent.`,
+      })
+    }
+
     discovered.push({
       id: dirName,
       name,
@@ -297,80 +394,98 @@ function discoverAgents(workspacePath: string): AgentEntry[] | null {
 }
 
 // ---------------------------------------------------------------------------
-// CLI-based discovery (openclaw agents list)
+// CLI-based multi-workspace discovery (openclaw agents list)
 // ---------------------------------------------------------------------------
 
 /**
- * Discover agents via `openclaw agents list --json`.
- * Returns AgentEntry[] for any agents found, or null on failure.
- * This catches agents defined in openclaw.json that don't have
- * filesystem directories under agents/.
+ * Raw entry from `openclaw agents list --json`.
+ *
+ * Real CLI output shape (verified against OpenClaw docs + live CLI):
+ *   { id, identityName, identityEmoji, identitySource,
+ *     workspace, agentDir, model, bindings, isDefault, routes }
+ */
+interface CliAgentEntry {
+  id: string
+  identityName?: string
+  identityEmoji?: string
+  workspace?: string
+  isDefault?: boolean
+}
+
+/**
+ * Call `openclaw agents list --json` and return parsed entries.
+ * Returns null on any failure (CLI not found, bad JSON, timeout).
  */
-function discoverAgentsViaCli(openclawBin: string): AgentEntry[] | null {
+export function listCliAgents(openclawBin: string): CliAgentEntry[] | null {
   try {
     const raw = execSync(`${openclawBin} agents list --json`, {
       encoding: 'utf-8',
       timeout: 10000,
     })
     const parsed = JSON.parse(raw)
-    const agents: unknown[] = Array.isArray(parsed)
-      ? parsed
-      : parsed.agents ?? parsed.data ?? []
-
+    const agents: unknown[] = Array.isArray(parsed) ? parsed : []
     if (agents.length === 0) return null
-
-    let colorIndex = 0
-    return agents.map((entry) => {
-      const a = entry as Record<string, unknown>
-      const id = String(a.id ?? a.name ?? a.slug ?? '')
-      const name = String(a.name ?? a.displayName ?? slugToName(id))
-      const title = String(a.title ?? a.role ?? 'Agent')
-      const reportsTo = a.reportsTo != null ? String(a.reportsTo) : null
-      const directReports = Array.isArray(a.directReports)
-        ? a.directReports.map(String)
-        : []
-      const tools = Array.isArray(a.tools) ? a.tools.map(String) : ['read', 'write']
-
-      return {
-        id,
-        name,
-        title,
-        reportsTo,
-        directReports,
-        soulPath: typeof a.soulPath === 'string' ? a.soulPath : null,
-        voiceId: typeof a.voiceId === 'string' ? a.voiceId : null,
-        color: typeof a.color === 'string' ? a.color : DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
-        emoji: typeof a.emoji === 'string' ? a.emoji : name.charAt(0).toUpperCase(),
-        tools,
-        memoryPath: typeof a.memoryPath === 'string' ? a.memoryPath : null,
-        description: typeof a.description === 'string' ? a.description : `${name} agent.`,
-      }
-    })
+    return agents as CliAgentEntry[]
   } catch {
     return null
   }
 }
 
 /**
- * Merge CLI-discovered agents into an existing registry.
- * Only adds agents whose IDs are not already present.
- * Also patches directReports on existing agents to include new CLI agents.
+ * Scan additional workspaces found via CLI that differ from the primary
+ * WORKSPACE_PATH. For each extra workspace, run discoverAgents() and
+ * merge results into the existing registry.
+ *
+ * Agents from other workspaces are independent (no cross-workspace hierarchy).
+ * If the other workspace has a root orchestrator, it becomes a top-level peer
+ * in the primary workspace's registry.
  */
-function mergeCliAgents(existing: AgentEntry[], cliAgents: AgentEntry[]): AgentEntry[] {
+function mergeExtraWorkspaces(
+  existing: AgentEntry[],
+  cliAgents: CliAgentEntry[],
+  primaryWorkspace: string,
+): AgentEntry[] {
   const existingIds = new Set(existing.map(a => a.id))
   const added: AgentEntry[] = []
-
-  for (const ca of cliAgents) {
-    if (existingIds.has(ca.id)) continue
-    added.push(ca)
-    existingIds.add(ca.id)
-
-    // If the CLI agent reports to an existing agent, add it to that agent's directReports
-    if (ca.reportsTo) {
-      const parent = existing.find(a => a.id === ca.reportsTo)
-      if (parent && !parent.directReports.includes(ca.id)) {
-        parent.directReports.push(ca.id)
+  let colorIndex = existing.length
+
+  for (const cli of cliAgents) {
+    const ws = cli.workspace
+    // Skip agents whose workspace matches the primary (already discovered)
+    if (!ws || ws === primaryWorkspace) continue
+
+    // Try discovering agents from this workspace's filesystem
+    const discovered = discoverAgents(ws)
+    if (discovered) {
+      for (const agent of discovered) {
+        if (existingIds.has(agent.id)) continue
+        // Agents from other workspaces are top-level peers (no cross-workspace hierarchy)
+        if (agent.reportsTo && !existingIds.has(agent.reportsTo)) {
+          agent.reportsTo = null
+        }
+        added.push(agent)
+        existingIds.add(agent.id)
       }
+    } else {
+      // Workspace has no agents/ dir — create a minimal entry from CLI identity
+      const id = cli.id
+      if (existingIds.has(id)) continue
+      const name = cli.identityName || slugToName(id)
+      added.push({
+        id,
+        name,
+        title: 'Agent',
+        reportsTo: null,
+        directReports: [],
+        soulPath: null,
+        voiceId: null,
+        color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
+        emoji: cli.identityEmoji || name.charAt(0).toUpperCase(),
+        tools: ['read', 'write'],
+        memoryPath: null,
+        description: `${name} agent.`,
+      })
+      existingIds.add(id)
     }
   }
 
@@ -383,8 +498,8 @@ function mergeCliAgents(existing: AgentEntry[], cliAgents: AgentEntry[]): AgentE
  * Resolution order:
  *   1. $WORKSPACE_PATH/clawport/agents.json  (user's own config)
  *   2. Auto-discovered from $WORKSPACE_PATH   (agents/ directory scan)
- *      + merged with `openclaw agents list --json` (catches config-only agents)
- *   3. CLI-only discovery via `openclaw agents list --json`
+ *      + merged with other workspaces from `openclaw agents list --json`
+ *   3. CLI-only discovery (scans each agent's workspace)
  *   4. Bundled lib/agents.json               (default example registry)
  */
 export function loadRegistry(): AgentEntry[] {
@@ -403,21 +518,25 @@ export function loadRegistry(): AgentEntry[] {
       }
     }
 
-    // 2. Auto-discover from workspace filesystem
+    // 2. Auto-discover from primary workspace filesystem
     const discovered = discoverAgents(workspacePath)
 
-    // 2b. Merge in any agents known to OpenClaw CLI but missing from filesystem
+    // 2b. Merge agents from other workspaces known to the CLI
     if (discovered && openclawBin) {
-      const cliAgents = discoverAgentsViaCli(openclawBin)
-      if (cliAgents) return mergeCliAgents(discovered, cliAgents)
+      const cliAgents = listCliAgents(openclawBin)
+      if (cliAgents && cliAgents.length > 1) {
+        return mergeExtraWorkspaces(discovered, cliAgents, workspacePath)
+      }
       return discovered
     }
     if (discovered) return discovered
 
-    // 3. CLI-only discovery (no workspace agents/ dir, but CLI knows about agents)
+    // 3. CLI-only: no primary workspace agents, scan each CLI agent's workspace
     if (openclawBin) {
-      const cliAgents = discoverAgentsViaCli(openclawBin)
-      if (cliAgents) return cliAgents
+      const cliAgents = listCliAgents(openclawBin)
+      if (cliAgents) {
+        return mergeExtraWorkspaces([], cliAgents, '')
+      }
     }
   }
 

package/lib/agents.test.ts

@@ -1,10 +1,11 @@
 // @vitest-environment node
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 
-const { mockReadFileSync, mockExistsSync, mockReaddirSync, bundledAgents } = vi.hoisted(() => ({
+const { mockReadFileSync, mockExistsSync, mockReaddirSync, mockExecSync, bundledAgents } = vi.hoisted(() => ({
   mockReadFileSync: vi.fn(),
   mockExistsSync: vi.fn(),
   mockReaddirSync: vi.fn(),
+  mockExecSync: vi.fn(),
   bundledAgents: [
     {
       id: 'jarvis',
@@ -115,6 +116,12 @@ vi.mock('fs', () => ({
   default: { readFileSync: mockReadFileSync, existsSync: mockExistsSync, readdirSync: mockReaddirSync },
 }))
 
+// Mock child_process for CLI discovery
+vi.mock('child_process', () => ({
+  execSync: mockExecSync,
+  default: { execSync: mockExecSync },
+}))
+
 // Mock the bundled agents.json
 vi.mock('@/lib/agents.json', () => ({
   default: bundledAgents,
@@ -705,6 +712,209 @@ describe('auto-discovery from workspace', () => {
     expect(kaze.name).toBe('KAZE')
     expect(kaze.title).toBe('Flight Research Agent')
   })
+
+  it('discovers subdirectory agents with SOUL.md (outpost pattern)', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/outpost/SOUL.md') return true
+      if (p === '/tmp/ws/agents/outpost') return true
+      if (p === '/tmp/ws/agents/outpost/sub-agents') return false
+      if (p === '/tmp/ws/agents/outpost/members') return false
+      if (p === '/tmp/ws/agents/outpost/scout/SOUL.md') return true
+      if (p === '/tmp/ws/agents/outpost/mirror/SOUL.md') return true
+      return false
+    })
+
+    mockReaddirSync.mockImplementation((p: string) => {
+      if (String(p) === '/tmp/ws/agents') {
+        return [{ name: 'outpost', isDirectory: () => true }]
+      }
+      if (String(p) === '/tmp/ws/agents/outpost') {
+        return [
+          { name: 'scout', isDirectory: () => true },
+          { name: 'mirror', isDirectory: () => true },
+        ]
+      }
+      return []
+    })
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/agents/outpost/SOUL.md') return '# OUTPOST — Forward Operations'
+      if (p === '/tmp/ws/agents/outpost/scout/SOUL.md') return '# SCOUT — Reconnaissance Agent'
+      if (p === '/tmp/ws/agents/outpost/mirror/SOUL.md') return '# MIRROR — Reflection Agent'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const outpost = agents.find(a => a.id === 'outpost')!
+    expect(outpost.name).toBe('OUTPOST')
+    expect(outpost.directReports).toContain('outpost-scout')
+    expect(outpost.directReports).toContain('outpost-mirror')
+
+    const scout = agents.find(a => a.id === 'outpost-scout')!
+    expect(scout.name).toBe('SCOUT')
+    expect(scout.title).toBe('Reconnaissance Agent')
+    expect(scout.reportsTo).toBe('outpost')
+    expect(scout.soulPath).toBe('agents/outpost/scout/SOUL.md')
+
+    const mirror = agents.find(a => a.id === 'outpost-mirror')!
+    expect(mirror.name).toBe('MIRROR')
+    expect(mirror.title).toBe('Reflection Agent')
+    expect(mirror.reportsTo).toBe('outpost')
+    expect(mirror.soulPath).toBe('agents/outpost/mirror/SOUL.md')
+  })
+
+  it('scans sub-agents from root-matching directory', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/IDENTITY.md') return true
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/jarvis/SOUL.md') return true
+      if (p === '/tmp/ws/agents/jarvis') return true
+      if (p === '/tmp/ws/agents/jarvis/sub-agents') return true
+      if (p === '/tmp/ws/agents/jarvis/sub-agents/SCRIBE.md') return true
+      if (p === '/tmp/ws/agents/jarvis/members') return false
+      if (p === '/tmp/ws/agents/vera/SOUL.md') return true
+      if (p === '/tmp/ws/agents/vera/sub-agents') return false
+      if (p === '/tmp/ws/agents/vera/members') return false
+      return false
+    })
+
+    mockReaddirSync.mockImplementation((p: string) => {
+      if (String(p) === '/tmp/ws/agents') {
+        return [
+          { name: 'jarvis', isDirectory: () => true },
+          { name: 'vera', isDirectory: () => true },
+        ]
+      }
+      if (String(p) === '/tmp/ws/agents/jarvis/sub-agents') {
+        return ['SCRIBE.md']
+      }
+      return []
+    })
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/IDENTITY.md') return '- **Name:** Jarvis\n- **Emoji:** 🤖'
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md - Who You Are'
+      if (p === '/tmp/ws/agents/jarvis/SOUL.md') return '# SOUL.md — Jarvis'
+      if (p === '/tmp/ws/agents/jarvis/sub-agents/SCRIBE.md') return '# SCRIBE — Documentation Writer'
+      if (p === '/tmp/ws/agents/vera/SOUL.md') return '# SOUL.md — VERA'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const root = agents.find(a => a.id === 'jarvis')!
+    expect(root.reportsTo).toBeNull()
+    expect(root.directReports).toContain('jarvis-scribe')
+    expect(root.directReports).toContain('vera')
+
+    const scribe = agents.find(a => a.id === 'jarvis-scribe')!
+    expect(scribe.name).toBe('SCRIBE')
+    expect(scribe.title).toBe('Documentation Writer')
+    expect(scribe.reportsTo).toBe('jarvis')
+
+    expect(agents.filter(a => a.id === 'jarvis')).toHaveLength(1)
+  })
+
+  it('ignores data directories without SOUL.md', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/robin/SOUL.md') return true
+      if (p === '/tmp/ws/agents/robin/sub-agents') return false
+      if (p === '/tmp/ws/agents/robin/members') return false
+      return false
+    })
+
+    mockReaddirSync.mockImplementation((p: string) => {
+      if (String(p) === '/tmp/ws/agents') {
+        return [{ name: 'robin', isDirectory: () => true }]
+      }
+      if (String(p) === '/tmp/ws/agents/robin') {
+        return [
+          { name: 'briefs', isDirectory: () => true },
+          { name: 'state.json', isDirectory: () => false },
+        ]
+      }
+      return []
+    })
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/agents/robin/SOUL.md') return '# ROBIN — Field Intel Operator'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const robin = agents.find(a => a.id === 'robin')!
+    expect(robin.name).toBe('ROBIN')
+    expect(robin.directReports).toEqual([])
+    expect(agents.find(a => a.id === 'robin-briefs')).toBeUndefined()
+  })
+
+  it('discovers both flat sub-agents and subdirectory agents', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/herald/SOUL.md') return true
+      if (p === '/tmp/ws/agents/herald') return true
+      if (p === '/tmp/ws/agents/herald/sub-agents') return true
+      if (p === '/tmp/ws/agents/herald/sub-agents/MAVEN.md') return true
+      if (p === '/tmp/ws/agents/herald/members') return false
+      if (p === '/tmp/ws/agents/herald/quill/SOUL.md') return true
+      return false
+    })
+
+    mockReaddirSync.mockImplementation((p: string) => {
+      if (String(p) === '/tmp/ws/agents') {
+        return [{ name: 'herald', isDirectory: () => true }]
+      }
+      if (String(p) === '/tmp/ws/agents/herald/sub-agents') {
+        return ['MAVEN.md']
+      }
+      if (String(p) === '/tmp/ws/agents/herald') {
+        return [
+          { name: 'sub-agents', isDirectory: () => true },
+          { name: 'quill', isDirectory: () => true },
+        ]
+      }
+      return []
+    })
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/agents/herald/SOUL.md') return '# SOUL.md — HERALD'
+      if (p === '/tmp/ws/agents/herald/sub-agents/MAVEN.md') return '# MAVEN — LinkedIn Strategist'
+      if (p === '/tmp/ws/agents/herald/quill/SOUL.md') return '# QUILL — Content Writer'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const herald = agents.find(a => a.id === 'herald')!
+    expect(herald.directReports).toContain('herald-maven')
+    expect(herald.directReports).toContain('herald-quill')
+
+    const maven = agents.find(a => a.id === 'herald-maven')!
+    expect(maven.name).toBe('MAVEN')
+    expect(maven.reportsTo).toBe('herald')
+    expect(maven.soulPath).toBeNull()
+
+    const quill = agents.find(a => a.id === 'herald-quill')!
+    expect(quill.name).toBe('QUILL')
+    expect(quill.reportsTo).toBe('herald')
+    expect(quill.soulPath).toBe('agents/herald/quill/SOUL.md')
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -855,3 +1065,346 @@ describe('getAgent', () => {
     expect(jarvis!.reportsTo).toBeNull()
   })
 })
+
+// ---------------------------------------------------------------------------
+// CLI-based multi-workspace discovery (openclaw agents list --json)
+//
+// Real CLI output format (verified against live `openclaw agents list --json`):
+//   [{ id, identityName, identityEmoji, identitySource,
+//      workspace, agentDir, model, bindings, isDefault, routes }]
+//
+// Key insight: OpenClaw "agents" are isolated workspaces, not hierarchical
+// team members. Each has its own workspace path. ClawPort scans each
+// workspace for sub-agent hierarchies via discoverAgents().
+// ---------------------------------------------------------------------------
+
+describe('CLI agent discovery (multi-workspace)', () => {
+  /**
+   * Primary workspace at /tmp/ws with root Jarvis + echo agent.
+   * OPENCLAW_BIN set so CLI calls are attempted.
+   */
+  function setupPrimaryWorkspace() {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    vi.stubEnv('OPENCLAW_BIN', '/usr/local/bin/openclaw')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/IDENTITY.md') return true
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/echo/SOUL.md') return true
+      if (p === '/tmp/ws/agents/echo/sub-agents') return false
+      if (p === '/tmp/ws/agents/echo/members') return false
+      return false
+    })
+
+    mockReaddirSync.mockReturnValue([
+      { name: 'echo', isDirectory: () => true },
+    ])
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/IDENTITY.md') return '- **Name:** Jarvis\n- **Emoji:** 🤖'
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md - Who You Are'
+      if (p === '/tmp/ws/agents/echo/SOUL.md') return '# ECHO — Community Voice Monitor'
+      throw new Error('ENOENT')
+    })
+  }
+
+  /** CLI output for a single agent (matches the primary workspace) */
+  function cliOutput(entries: Array<{
+    id: string
+    identityName?: string
+    identityEmoji?: string
+    workspace?: string
+    isDefault?: boolean
+  }>) {
+    return JSON.stringify(entries.map(e => ({
+      id: e.id,
+      identityName: e.identityName ?? null,
+      identityEmoji: e.identityEmoji ?? null,
+      identitySource: 'identity',
+      workspace: e.workspace ?? '/tmp/ws',
+      agentDir: `/home/.openclaw/agents/${e.id}/agent`,
+      model: 'anthropic/claude-sonnet-4-6',
+      bindings: 0,
+      isDefault: e.isDefault ?? false,
+      routes: ['default (no explicit rules)'],
+    })))
+  }
+
+  it('skips CLI merge when only one agent exists (same workspace)', async () => {
+    setupPrimaryWorkspace()
+
+    // CLI returns one agent pointing at the same workspace — no extra workspaces to scan
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'main', identityName: 'Jarvis', identityEmoji: '🤖', workspace: '/tmp/ws', isDefault: true },
+    ]))
+
+    const agents = await getAgents()
+    const ids = agents.map(a => a.id)
+    expect(ids).toContain('jarvis')
+    expect(ids).toContain('echo')
+    // Should NOT have a duplicate 'main' entry since only 1 CLI agent (no merge triggered)
+  })
+
+  it('discovers agents from a second workspace via CLI', async () => {
+    // Primary workspace has Jarvis + echo
+    // CLI shows a second agent "work" with a different workspace at /tmp/ws-work
+    // That workspace has a SOUL.md + a "helper" agent
+    setupPrimaryWorkspace()
+
+    // Extend existsSync to handle the second workspace
+    const origExists = mockExistsSync.getMockImplementation()!
+    mockExistsSync.mockImplementation((p: string) => {
+      // Second workspace paths
+      if (p === '/tmp/ws-work/SOUL.md') return true
+      if (p === '/tmp/ws-work/IDENTITY.md') return true
+      if (p === '/tmp/ws-work/agents') return true
+      if (p === '/tmp/ws-work/agents/helper/SOUL.md') return true
+      if (p === '/tmp/ws-work/agents/helper/sub-agents') return false
+      if (p === '/tmp/ws-work/agents/helper/members') return false
+      if (p === '/tmp/ws-work/clawport/agents.json') return false
+      return origExists(p)
+    })
+
+    // Extend readdirSync to handle the second workspace agents/ dir
+    mockReaddirSync.mockImplementation((p: string) => {
+      if (String(p) === '/tmp/ws-work/agents') {
+        return [{ name: 'helper', isDirectory: () => true }]
+      }
+      return [{ name: 'echo', isDirectory: () => true }]
+    })
+
+    const origRead = mockReadFileSync.getMockImplementation()!
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws-work/IDENTITY.md') return '- **Name:** WorkBot\n- **Emoji:** 🔧'
+      if (p === '/tmp/ws-work/SOUL.md') return '# SOUL.md - Who You Are'
+      if (p === '/tmp/ws-work/agents/helper/SOUL.md') return '# HELPER — Task Assistant'
+      return origRead(p)
+    })
+
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'main', identityName: 'Jarvis', identityEmoji: '🤖', workspace: '/tmp/ws', isDefault: true },
+      { id: 'work', identityName: 'WorkBot', identityEmoji: '🔧', workspace: '/tmp/ws-work' },
+    ]))
+
+    const agents = await getAgents()
+    const ids = agents.map(a => a.id)
+    // Primary workspace agents
+    expect(ids).toContain('jarvis')
+    expect(ids).toContain('echo')
+    // Second workspace agents discovered via filesystem scan
+    expect(ids).toContain('workbot') // root of second workspace (from IDENTITY.md)
+    expect(ids).toContain('helper')
+  })
+
+  it('second workspace root becomes top-level peer (reportsTo=null)', async () => {
+    setupPrimaryWorkspace()
+
+    const origExists = mockExistsSync.getMockImplementation()!
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws2/SOUL.md') return true
+      if (p === '/tmp/ws2/IDENTITY.md') return false
+      if (p === '/tmp/ws2/agents') return false
+      if (p === '/tmp/ws2/clawport/agents.json') return false
+      return origExists(p)
+    })
+
+    const origRead = mockReadFileSync.getMockImplementation()!
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws2/SOUL.md') return '# SOUL.md — SecondBot'
+      return origRead(p)
+    })
+
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'main', workspace: '/tmp/ws', isDefault: true },
+      { id: 'second', workspace: '/tmp/ws2' },
+    ]))
+
+    const agents = await getAgents()
+    const secondBot = agents.find(a => a.id === 'secondbot')
+    expect(secondBot).toBeDefined()
+    expect(secondBot!.reportsTo).toBeNull() // independent, not under Jarvis
+  })
+
+  it('creates minimal entry when extra workspace has no discoverable agents', async () => {
+    setupPrimaryWorkspace()
+
+    // Second workspace has nothing discoverable (no SOUL.md, no agents/ dir)
+    const origExists = mockExistsSync.getMockImplementation()!
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.startsWith('/tmp/ws-empty')) return false
+      return origExists(p)
+    })
+
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'main', workspace: '/tmp/ws', isDefault: true },
+      { id: 'empty-bot', identityName: 'EmptyBot', identityEmoji: '🤷', workspace: '/tmp/ws-empty' },
+    ]))
+
+    const agents = await getAgents()
+    const emptyBot = agents.find(a => a.id === 'empty-bot')
+    expect(emptyBot).toBeDefined()
+    expect(emptyBot!.name).toBe('EmptyBot')
+    expect(emptyBot!.emoji).toBe('🤷')
+    expect(emptyBot!.reportsTo).toBeNull()
+    expect(emptyBot!.tools).toEqual(['read', 'write'])
+  })
+
+  it('does not duplicate agents already found in primary workspace', async () => {
+    setupPrimaryWorkspace()
+
+    // CLI returns two agents both pointing at the SAME workspace
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'main', workspace: '/tmp/ws', isDefault: true },
+      { id: 'alias', workspace: '/tmp/ws' }, // same workspace, should be skipped
+    ]))
+
+    const agents = await getAgents()
+    // No extra agents added since both workspaces are the same
+    const ids = agents.map(a => a.id)
+    expect(ids).toContain('jarvis')
+    expect(ids).toContain('echo')
+    expect(ids).not.toContain('alias')
+  })
+
+  it('gracefully handles CLI failure (falls back to filesystem only)', async () => {
+    setupPrimaryWorkspace()
+
+    mockExecSync.mockImplementation(() => {
+      throw new Error('command not found: openclaw')
+    })
+
+    const agents = await getAgents()
+    const ids = agents.map(a => a.id)
+    expect(ids).toContain('jarvis')
+    expect(ids).toContain('echo')
+  })
+
+  it('gracefully handles CLI returning invalid JSON', async () => {
+    setupPrimaryWorkspace()
+    mockExecSync.mockReturnValue('not valid json {{{}')
+
+    const agents = await getAgents()
+    expect(agents.map(a => a.id)).toContain('jarvis')
+    expect(agents.map(a => a.id)).toContain('echo')
+  })
+
+  it('gracefully handles CLI returning empty array', async () => {
+    setupPrimaryWorkspace()
+    mockExecSync.mockReturnValue('[]')
+
+    const agents = await getAgents()
+    expect(agents.map(a => a.id)).toContain('jarvis')
+    expect(agents.map(a => a.id)).toContain('echo')
+  })
+
+  it('gracefully handles non-array CLI output', async () => {
+    setupPrimaryWorkspace()
+    mockExecSync.mockReturnValue('{"status":"ok"}')
+
+    const agents = await getAgents()
+    expect(agents.map(a => a.id)).toContain('jarvis')
+  })
+
+  it('does not call CLI when OPENCLAW_BIN is not set', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    vi.stubEnv('OPENCLAW_BIN', '')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/IDENTITY.md') return false
+      if (p === '/tmp/ws/agents') return false
+      return false
+    })
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md — Root'
+      throw new Error('ENOENT')
+    })
+
+    await getAgents()
+    expect(mockExecSync).not.toHaveBeenCalled()
+  })
+
+  it('falls back to bundled when CLI fails and no filesystem agents', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    vi.stubEnv('OPENCLAW_BIN', '/usr/local/bin/openclaw')
+    mockExistsSync.mockReturnValue(false)
+    mockReaddirSync.mockReturnValue([])
+    mockExecSync.mockImplementation(() => { throw new Error('timeout') })
+
+    const agents = await getAgents()
+    expect(agents.length).toBe(bundledAgents.length)
+  })
+
+  it('CLI-only: scans each workspace when primary has no agents', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    vi.stubEnv('OPENCLAW_BIN', '/usr/local/bin/openclaw')
+
+    // Primary workspace has nothing
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/agents') return false
+      // Remote workspace
+      if (p === '/tmp/remote/SOUL.md') return true
+      if (p === '/tmp/remote/IDENTITY.md') return false
+      if (p === '/tmp/remote/agents') return false
+      if (p === '/tmp/remote/clawport/agents.json') return false
+      return false
+    })
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/remote/SOUL.md') return '# SOUL.md — RemoteBot'
+      throw new Error('ENOENT')
+    })
+
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'remote', identityName: 'RemoteBot', workspace: '/tmp/remote' },
+    ]))
+
+    const agents = await getAgents()
+    expect(agents.map(a => a.id)).toContain('remotebot')
+  })
+
+  it('handles three workspaces with independent hierarchies', async () => {
+    setupPrimaryWorkspace()
+
+    // Extend filesystem mocks for two extra workspaces
+    const origExists = mockExistsSync.getMockImplementation()!
+    mockExistsSync.mockImplementation((p: string) => {
+      // Workspace B
+      if (p === '/tmp/ws-b/SOUL.md') return true
+      if (p === '/tmp/ws-b/IDENTITY.md') return false
+      if (p === '/tmp/ws-b/agents') return false
+      if (p === '/tmp/ws-b/clawport/agents.json') return false
+      // Workspace C — empty
+      if (p.startsWith('/tmp/ws-c')) return false
+      return origExists(p)
+    })
+
+    const origRead = mockReadFileSync.getMockImplementation()!
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws-b/SOUL.md') return '# SOUL.md — BotB'
+      return origRead(p)
+    })
+
+    mockExecSync.mockReturnValue(cliOutput([
+      { id: 'main', workspace: '/tmp/ws', isDefault: true },
+      { id: 'b', identityName: 'BotB', workspace: '/tmp/ws-b' },
+      { id: 'c', identityName: 'BotC', identityEmoji: '🎯', workspace: '/tmp/ws-c' },
+    ]))
+
+    const agents = await getAgents()
+    const ids = agents.map(a => a.id)
+    expect(ids).toContain('jarvis')  // primary root
+    expect(ids).toContain('echo')    // primary sub-agent
+    expect(ids).toContain('botb')    // workspace B root (from SOUL.md heading)
+    expect(ids).toContain('c')       // workspace C (minimal entry, no SOUL.md)
+
+    const botC = agents.find(a => a.id === 'c')!
+    expect(botC.name).toBe('BotC')
+    expect(botC.emoji).toBe('🎯')
+  })
+})

package/lib/teams.test.ts

@@ -0,0 +1,305 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest'
+import { buildTeams, type Team } from './teams'
+import type { Agent } from './types'
+
+/** Helper to create a minimal agent */
+function agent(overrides: Partial<Agent> & { id: string }): Agent {
+  return {
+    name: overrides.id.toUpperCase(),
+    title: 'Agent',
+    reportsTo: null,
+    directReports: [],
+    soulPath: null,
+    soul: null,
+    voiceId: null,
+    color: '#000',
+    emoji: 'A',
+    tools: [],
+    crons: [],
+    memoryPath: null,
+    description: '',
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Basic team grouping
+// ---------------------------------------------------------------------------
+
+describe('buildTeams', () => {
+  it('returns null root and empty arrays for empty input', () => {
+    const result = buildTeams([])
+    expect(result.root).toBeNull()
+    expect(result.teams).toEqual([])
+    expect(result.soloOps).toEqual([])
+  })
+
+  it('returns null root when no agent has reportsTo=null', () => {
+    const agents = [
+      agent({ id: 'a', reportsTo: 'b' }),
+      agent({ id: 'b', reportsTo: 'a' }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.root).toBeNull()
+  })
+
+  it('identifies root agent (reportsTo=null)', () => {
+    const agents = [
+      agent({ id: 'root', reportsTo: null, directReports: [] }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.root).not.toBeNull()
+    expect(result.root!.id).toBe('root')
+    expect(result.teams).toEqual([])
+    expect(result.soloOps).toEqual([])
+  })
+
+  it('classifies direct reports with children as team managers', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr'] }),
+      agent({ id: 'mgr', reportsTo: 'root', directReports: ['worker'] }),
+      agent({ id: 'worker', reportsTo: 'mgr' }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    expect(result.teams[0].manager.id).toBe('mgr')
+    expect(result.teams[0].members).toHaveLength(1)
+    expect(result.teams[0].members[0].id).toBe('worker')
+    expect(result.soloOps).toHaveLength(0)
+  })
+
+  it('classifies direct reports without children as solo ops', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['solo1', 'solo2'] }),
+      agent({ id: 'solo1', reportsTo: 'root' }),
+      agent({ id: 'solo2', reportsTo: 'root' }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(0)
+    expect(result.soloOps).toHaveLength(2)
+    expect(result.soloOps.map(a => a.id)).toContain('solo1')
+    expect(result.soloOps.map(a => a.id)).toContain('solo2')
+  })
+
+  it('separates managers from solo ops correctly', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr', 'solo'] }),
+      agent({ id: 'mgr', reportsTo: 'root', directReports: ['worker'] }),
+      agent({ id: 'worker', reportsTo: 'mgr' }),
+      agent({ id: 'solo', reportsTo: 'root' }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    expect(result.teams[0].manager.id).toBe('mgr')
+    expect(result.soloOps).toHaveLength(1)
+    expect(result.soloOps[0].id).toBe('solo')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Deep hierarchy traversal
+// ---------------------------------------------------------------------------
+
+describe('buildTeams — deep hierarchy', () => {
+  it('collects all nested members via BFS', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr'] }),
+      agent({ id: 'mgr', reportsTo: 'root', directReports: ['mid'] }),
+      agent({ id: 'mid', reportsTo: 'mgr', directReports: ['leaf'] }),
+      agent({ id: 'leaf', reportsTo: 'mid' }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    const members = result.teams[0].members.map(m => m.id)
+    expect(members).toContain('mid')
+    expect(members).toContain('leaf')
+    expect(members).toHaveLength(2)
+  })
+
+  it('handles wide teams (manager with many direct members)', () => {
+    const memberIds = Array.from({ length: 10 }, (_, i) => `m${i}`)
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr'] }),
+      agent({ id: 'mgr', reportsTo: 'root', directReports: memberIds }),
+      ...memberIds.map(id => agent({ id, reportsTo: 'mgr' })),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams[0].members).toHaveLength(10)
+  })
+
+  it('handles multiple teams with nested members', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr-a', 'mgr-b'] }),
+      agent({ id: 'mgr-a', reportsTo: 'root', directReports: ['a1', 'a2'] }),
+      agent({ id: 'a1', reportsTo: 'mgr-a' }),
+      agent({ id: 'a2', reportsTo: 'mgr-a' }),
+      agent({ id: 'mgr-b', reportsTo: 'root', directReports: ['b1'] }),
+      agent({ id: 'b1', reportsTo: 'mgr-b', directReports: ['b1-sub'] }),
+      agent({ id: 'b1-sub', reportsTo: 'b1' }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(2)
+
+    const teamA = result.teams.find(t => t.manager.id === 'mgr-a')!
+    expect(teamA.members.map(m => m.id)).toEqual(['a1', 'a2'])
+
+    const teamB = result.teams.find(t => t.manager.id === 'mgr-b')!
+    expect(teamB.members.map(m => m.id)).toContain('b1')
+    expect(teamB.members.map(m => m.id)).toContain('b1-sub')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Cycle protection
+// ---------------------------------------------------------------------------
+
+describe('buildTeams — cycle protection', () => {
+  it('does not infinite loop on self-referencing agent', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr'] }),
+      agent({ id: 'mgr', reportsTo: 'root', directReports: ['mgr'] }), // self-ref
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    // mgr references itself, but visited set prevents infinite loop
+    // mgr is already the manager so it's in visited — members should be empty
+    expect(result.teams[0].members).toHaveLength(0)
+  })
+
+  it('does not infinite loop on circular directReports', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['a'] }),
+      agent({ id: 'a', reportsTo: 'root', directReports: ['b'] }),
+      agent({ id: 'b', reportsTo: 'a', directReports: ['a'] }), // cycle back to a
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    const members = result.teams[0].members.map(m => m.id)
+    expect(members).toContain('b')
+    // 'a' should NOT appear as a member (it's the manager, and visited prevents re-add)
+    expect(members).not.toContain('a')
+  })
+
+  it('handles mutual cycle between two agents', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['x'] }),
+      agent({ id: 'x', reportsTo: 'root', directReports: ['y'] }),
+      agent({ id: 'y', reportsTo: 'x', directReports: ['x'] }),
+    ]
+    // Should not throw or hang
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    expect(result.teams[0].members).toHaveLength(1)
+    expect(result.teams[0].members[0].id).toBe('y')
+  })
+
+  it('handles longer cycle (a → b → c → a)', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['a'] }),
+      agent({ id: 'a', reportsTo: 'root', directReports: ['b'] }),
+      agent({ id: 'b', reportsTo: 'a', directReports: ['c'] }),
+      agent({ id: 'c', reportsTo: 'b', directReports: ['a'] }),
+    ]
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    const memberIds = result.teams[0].members.map(m => m.id)
+    expect(memberIds).toContain('b')
+    expect(memberIds).toContain('c')
+    // 'a' is the manager, should not be in members even with cycle
+    expect(memberIds).not.toContain('a')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+
+describe('buildTeams — edge cases', () => {
+  it('skips directReports that reference nonexistent agent IDs', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['real', 'ghost'] }),
+      agent({ id: 'real', reportsTo: 'root' }),
+      // 'ghost' does not exist in agents array
+    ]
+    const result = buildTeams(agents)
+    expect(result.soloOps).toHaveLength(1)
+    expect(result.soloOps[0].id).toBe('real')
+    // ghost is silently skipped
+  })
+
+  it('manager with only nonexistent children is classified as solo op', () => {
+    const agents = [
+      agent({ id: 'root', directReports: ['mgr'] }),
+      agent({ id: 'mgr', reportsTo: 'root', directReports: ['ghost1', 'ghost2'] }),
+    ]
+    // mgr has directReports.length > 0 so it's treated as a manager
+    const result = buildTeams(agents)
+    expect(result.teams).toHaveLength(1)
+    // But the team has no real members (ghosts not found in byId map)
+    expect(result.teams[0].members).toHaveLength(0)
+  })
+
+  it('root with no directReports results in empty teams and soloOps', () => {
+    const agents = [agent({ id: 'root' })]
+    const result = buildTeams(agents)
+    expect(result.root!.id).toBe('root')
+    expect(result.teams).toHaveLength(0)
+    expect(result.soloOps).toHaveLength(0)
+  })
+
+  it('uses first agent with reportsTo=null when multiple roots exist', () => {
+    const agents = [
+      agent({ id: 'root1' }),
+      agent({ id: 'root2' }),
+    ]
+    const result = buildTeams(agents)
+    // Array.find returns the first match
+    expect(result.root!.id).toBe('root1')
+  })
+
+  it('handles the full bundled agents.json structure', () => {
+    // Simulate the real Jarvis org: root + 3 managers + 6 solo ops
+    const agents = [
+      agent({ id: 'jarvis', directReports: ['vera', 'lumen', 'herald', 'pulse', 'echo', 'sage'] }),
+      agent({ id: 'vera', reportsTo: 'jarvis', directReports: ['robin'] }),
+      agent({ id: 'robin', reportsTo: 'vera', directReports: ['trace', 'proof'] }),
+      agent({ id: 'trace', reportsTo: 'robin' }),
+      agent({ id: 'proof', reportsTo: 'robin' }),
+      agent({ id: 'lumen', reportsTo: 'jarvis', directReports: ['scout', 'writer'] }),
+      agent({ id: 'scout', reportsTo: 'lumen' }),
+      agent({ id: 'writer', reportsTo: 'lumen' }),
+      agent({ id: 'herald', reportsTo: 'jarvis', directReports: ['quill'] }),
+      agent({ id: 'quill', reportsTo: 'herald' }),
+      agent({ id: 'pulse', reportsTo: 'jarvis' }),
+      agent({ id: 'echo', reportsTo: 'jarvis' }),
+      agent({ id: 'sage', reportsTo: 'jarvis' }),
+    ]
+    const result = buildTeams(agents)
+
+    expect(result.root!.id).toBe('jarvis')
+    expect(result.teams).toHaveLength(3)
+    expect(result.soloOps).toHaveLength(3)
+
+    // Team VERA includes robin, trace, proof (nested)
+    const teamVera = result.teams.find(t => t.manager.id === 'vera')!
+    expect(teamVera.members.map(m => m.id)).toEqual(
+      expect.arrayContaining(['robin', 'trace', 'proof']),
+    )
+
+    // Team LUMEN includes scout, writer
+    const teamLumen = result.teams.find(t => t.manager.id === 'lumen')!
+    expect(teamLumen.members.map(m => m.id)).toEqual(
+      expect.arrayContaining(['scout', 'writer']),
+    )
+
+    // Team HERALD includes quill
+    const teamHerald = result.teams.find(t => t.manager.id === 'herald')!
+    expect(teamHerald.members.map(m => m.id)).toEqual(['quill'])
+
+    // Solo ops
+    expect(result.soloOps.map(a => a.id)).toEqual(
+      expect.arrayContaining(['pulse', 'echo', 'sage']),
+    )
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawport-ui",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.",
   "homepage": "https://clawport.dev",
   "repository": {