Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { describe, expect, it } from 'vitest'
import { readClaudeBackgroundAgentTasks } from './claude-background-task-inventory'
import {
claudeRosterHasRuntimeWorkingSubagent,
claudeRosterHasWorkingSubagent,
claudeRosterToSnapshots,
claudeTeammateIdMatchesName,
foldClaudeBackgroundTasksIntoRoster,
idleClaudeTeammateByName,
reapUnconfirmedRestoredClaudeSubagents,
stopClaudeSubagent,
upsertWorkingClaudeSubagent,
type ClaudeSubagentRoster
} from './claude-subagent-roster'
const task = (
over: Partial<ReturnType<typeof readClaudeBackgroundAgentTasks>['tasks'][number]>
) => ({
id: 'a1',
agentType: undefined,
description: undefined,
running: true,
teammate: false,
...over
})
describe('claude-subagent-roster', () => {
it('removes a finished one-shot subagent on stop', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', { agentType: 'general-purpose' }, 100)
expect(claudeRosterHasWorkingSubagent(roster)).toBe(true)
// Remove finished one-shots to avoid accumulating dead Idle rows.
stopClaudeSubagent(roster, 'a1')
expect(roster.size).toBe(0)
expect(claudeRosterToSnapshots(roster)).toBeUndefined()
})
it('parks a teammate-shaped named agent as idle on stop', () => {
const roster: ClaudeSubagentRoster = new Map()
// Claude 2.1.21x teammates emit SubagentStop per turn while alive; keep them idle without gating pane work.
upsertWorkingClaudeSubagent(roster, 'aprobe1-6d3cb5b5', { agentType: 'probe1' }, 100)
stopClaudeSubagent(roster, 'aprobe1-6d3cb5b5')
expect(roster.get('aprobe1-6d3cb5b5')).toMatchObject({ state: 'idle' })
expect(claudeRosterHasWorkingSubagent(roster)).toBe(false)
expect(claudeRosterToSnapshots(roster)).toEqual([
expect.objectContaining({ id: 'aprobe1-6d3cb5b5', state: 'idle' })
])
})
it('removes a stopped workflow lane despite its teammate-shaped id', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'alane-hooks-6d3cb5b5', { agentType: 'lane-hooks' }, 100)
// An id-exact subagent task proves a workflow lane; its stop is final.
foldClaudeBackgroundTasksIntoRoster(
roster,
[task({ id: 'alane-hooks-6d3cb5b5', agentType: 'lane-hooks' })],
150
)
stopClaudeSubagent(roster, 'alane-hooks-6d3cb5b5')
expect(roster.has('alane-hooks-6d3cb5b5')).toBe(false)
})
it('restores a parked workflow lane to working when the inventory reports it running', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'alane-hooks-6d3cb5b5', { agentType: 'lane-hooks' }, 100)
stopClaudeSubagent(roster, 'alane-hooks-6d3cb5b5')
// Inventory and lifecycle hooks can race; authoritative running tasks retain the working gate.
foldClaudeBackgroundTasksIntoRoster(
roster,
[task({ id: 'alane-hooks-6d3cb5b5', agentType: 'lane-hooks' })],
150
)
expect(roster.get('alane-hooks-6d3cb5b5')).toMatchObject({
state: 'working',
listedAsSubagentTask: true
})
expect(claudeRosterHasWorkingSubagent(roster)).toBe(true)
})
it('revives an idle teammate as working while keeping its first-observed startedAt', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'aprobe1-6d3cb5b5', { agentType: 'probe1' }, 100)
stopClaudeSubagent(roster, 'aprobe1-6d3cb5b5')
upsertWorkingClaudeSubagent(roster, 'aprobe1-6d3cb5b5', { description: 'round two' }, 200)
expect(roster.get('aprobe1-6d3cb5b5')).toMatchObject({
state: 'working',
startedAt: 100,
description: 'round two'
})
})
it('re-adds a resumed one-shot as working with a fresh startedAt', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', { agentType: 'general-purpose' }, 100)
stopClaudeSubagent(roster, 'a1')
upsertWorkingClaudeSubagent(roster, 'a1', { description: 'round two' }, 200)
expect(roster.get('a1')).toMatchObject({ startedAt: 200, description: 'round two' })
})
it('ignores unknown ids on stopClaudeSubagent', () => {
const roster: ClaudeSubagentRoster = new Map()
stopClaudeSubagent(roster, 'ghost')
stopClaudeSubagent(roster, 'aghost-6d3cb5b5')
expect(roster.size).toBe(0)
})
it('keeps 40 working subagents', () => {
const roster: ClaudeSubagentRoster = new Map()
for (let i = 0; i < 40; i++) {
upsertWorkingClaudeSubagent(roster, `a${i}`, {}, i)
}
expect(claudeRosterToSnapshots(roster)).toHaveLength(40)
})
it('reads only agent-typed background_tasks entries', () => {
const { present, tasks } = readClaudeBackgroundAgentTasks({
background_tasks: [
{
id: 'a1',
type: 'subagent',
status: 'running',
description: 'review loop',
agent_type: 'general-purpose'
},
{ id: 't1', type: 'teammate', status: 'idle', agent_type: 'code-reviewer' },
{ id: 's1', type: 'shell', status: 'running', description: 'npm run dev' },
{ id: '', type: 'subagent', status: 'running' },
'garbage'
]
})
expect(present).toBe(true)
expect(tasks).toEqual([
{
id: 'a1',
agentType: 'general-purpose',
description: 'review loop',
running: true,
teammate: false
},
{
id: 't1',
agentType: 'code-reviewer',
description: undefined,
running: false,
teammate: true
}
])
})
it('reports background_tasks as absent when missing or malformed', () => {
expect(readClaudeBackgroundAgentTasks({}).present).toBe(false)
expect(readClaudeBackgroundAgentTasks({ background_tasks: 'nope' }).present).toBe(false)
})
it('trusts id-exact subagent matches and ignores teammate-typed entries', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', {}, 100)
// A named agent mid-run: teammate-shaped id, never a task id.
upsertWorkingClaudeSubagent(roster, 'ateam-6d3cb5b5', { agentType: 'security-reviewer' }, 150)
foldClaudeBackgroundTasksIntoRoster(
roster,
[
task({ id: 'a1', agentType: 'general-purpose', description: 'review loop' }),
// Teammate task IDs differ from lifecycle IDs; do not create phantom duplicates.
task({ id: 'tlkjjs0jv', description: 'teammate task', teammate: true })
],
200
)
expect(roster.size).toBe(2)
expect(roster.get('a1')).toMatchObject({ description: 'review loop' })
// Teammate presence makes lifecycle-ID omission inconclusive.
expect(roster.get('ateam-6d3cb5b5')).toMatchObject({ agentType: 'security-reviewer' })
})
it('removes an id-matched subagent task reported not running', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', { agentType: 'general-purpose' }, 100)
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'a1', running: false })], 200)
expect(roster.size).toBe(0)
})
it('removes a killed one-shot missing from a present list', () => {
const roster: ClaudeSubagentRoster = new Map()
// One-shots are listed id-exact; omission proves a lost finish even while other teammates remain.
upsertWorkingClaudeSubagent(roster, 'akilled0000000001', { agentType: 'general-purpose' }, 100)
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'other', teammate: true })], 200)
expect(roster.size).toBe(0)
})
it('keeps a live named agent whose teammate-typed id never appears in the list', () => {
const roster: ClaudeSubagentRoster = new Map()
// Named lifecycle IDs are omitted from teammate task inventories; do not finish their working rows early.
upsertWorkingClaudeSubagent(
roster,
'aweb-research-8a76b7d7',
{ agentType: 'web-research' },
100
)
foldClaudeBackgroundTasksIntoRoster(
roster,
[task({ id: 't6s2brfv7', description: 'named agent task', teammate: true })],
200
)
expect(roster.has('aweb-research-8a76b7d7')).toBe(true)
})
it('removes teammate-shaped leftovers when a complete inventory lists no teammates', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'acr-triage-1-c5a0588e', { agentType: 'cr-triage-1' }, 100)
// No teammate-typed task in a complete inventory proves the named child’s lost stop.
foldClaudeBackgroundTasksIntoRoster(
roster,
[task({ id: 'aunrelated0000001', agentType: 'general-purpose' })],
200
)
expect(roster.has('acr-triage-1-c5a0588e')).toBe(false)
expect(roster.has('aunrelated0000001')).toBe(true)
})
it('removes a leftover once a subagent-typed task listed its id id-exact', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(
roster,
'av1-streaming-0b1c2d3e',
{ agentType: 'v1-streaming' },
100
)
foldClaudeBackgroundTasksIntoRoster(
roster,
[
task({ id: 'av1-streaming-0b1c2d3e', agentType: 'v1-streaming' }),
task({ id: 'tteam1', teammate: true })
],
200
)
// Id-exact listing overrides teammate-shaped-ID protection on later omission.
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'tteam1', teammate: true })], 300)
expect(roster.has('av1-streaming-0b1c2d3e')).toBe(false)
})
it('retains an unlisted live child when the background task inventory was truncated', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'alive-unlisted', {}, 100)
const parsed = readClaudeBackgroundAgentTasks({
background_tasks: [
{ id: 'a0', type: 'subagent', status: 'running' },
{ id: 'unreadable', status: 'running' }
]
})
expect(parsed.truncated).toBe(true)
foldClaudeBackgroundTasksIntoRoster(roster, parsed.tasks, 200, {
inventoryComplete: !parsed.truncated
})
expect(roster.has('alive-unlisted')).toBe(true)
})
it('recreates unmatched running one-shot subagents after a listener restart', () => {
const roster: ClaudeSubagentRoster = new Map()
foldClaudeBackgroundTasksIntoRoster(
roster,
[
task({ id: 'a9', agentType: 'general-purpose', description: 'long build' }),
task({ id: 'gone', running: false })
],
500
)
expect(roster.get('a9')).toMatchObject({ startedAt: 500 })
expect(roster.has('gone')).toBe(false)
})
it('clears the roster when background_tasks reports nothing alive', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', {}, 100)
foldClaudeBackgroundTasksIntoRoster(roster, [], 100)
expect(roster.size).toBe(0)
})
it('does not clear the roster on an empty but incomplete (truncated) inventory', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', {}, 100)
foldClaudeBackgroundTasksIntoRoster(roster, [], 200, { inventoryComplete: false })
expect(roster.has('a1')).toBe(true)
})
it('removes a seeded phantom missing from a present list', () => {
const roster: ClaudeSubagentRoster = new Map()
// Snapshot-seeded entries remain subject to complete-inventory omission even with teammate-shaped IDs.
roster.set('aprobe1-6d3cb5b5', {
state: 'working',
startedAt: 100,
agentType: 'probe1',
backgroundTasksAuthoritative: true
})
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'other', teammate: true })], 200)
expect(roster.has('aprobe1-6d3cb5b5')).toBe(false)
})
it('keeps a re-tracked working named agent missing from a present list', () => {
const roster: ClaudeSubagentRoster = new Map()
roster.set('aprobe1-6d3cb5b5', {
state: 'working',
startedAt: 100,
agentType: 'probe1',
backgroundTasksAuthoritative: true
})
// Live activity reclaims lifecycle ownership, preventing omission from reaping a busy named teammate.
upsertWorkingClaudeSubagent(roster, 'aprobe1-6d3cb5b5', { agentType: 'probe1' }, 150)
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'other', teammate: true })], 200)
expect(roster.has('aprobe1-6d3cb5b5')).toBe(true)
})
it('removes fold-recreated one-shots missing from a later present list', () => {
const roster: ClaudeSubagentRoster = new Map()
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'a9' })], 100)
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'other', teammate: true })], 200)
expect(roster.has('a9')).toBe(false)
})
it('matches teammate ids by name only up to the hyphen-free suffix', () => {
expect(claudeTeammateIdMatchesName('aprobe1-6d3cb5b5', 'probe1')).toBe(true)
expect(claudeTeammateIdMatchesName('alane-hooks-6d3cb5b5', 'lane-hooks')).toBe(true)
expect(claudeTeammateIdMatchesName('alane-hooks-6d3cb5b5', 'lane')).toBe(false)
expect(claudeTeammateIdMatchesName('aprobe1-6d3cb5b5', 'probe')).toBe(false)
expect(claudeTeammateIdMatchesName('aprobe1', 'probe1')).toBe(false)
})
it('parks teammates idle by the name embedded in agent_id and confirms them', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'aprobe1-6d3cb5b5', { agentType: 'probe1' }, 100)
upsertWorkingClaudeSubagent(roster, 'aother-123', { agentType: 'other' }, 100)
// Claude 2.1.21x TeammateIdle confirms a live teammate awaiting mail.
expect(idleClaudeTeammateByName(roster, 'probe1')).toBe(true)
expect(roster.get('aprobe1-6d3cb5b5')).toMatchObject({
state: 'idle',
confirmedTeammate: true
})
expect(roster.get('aother-123')).toMatchObject({ state: 'working' })
expect(idleClaudeTeammateByName(roster, 'probe1')).toBe(false)
expect(idleClaudeTeammateByName(roster, 'ghost')).toBe(false)
})
it('does not idle an unrelated one-shot whose agent_type matches the teammate name', () => {
const roster: ClaudeSubagentRoster = new Map()
// Without a start hook, type alone cannot identify which live child an idle event belongs to.
upsertWorkingClaudeSubagent(roster, 'aoneshot00000001', { agentType: 'reviewer' }, 100)
expect(idleClaudeTeammateByName(roster, 'reviewer')).toBe(false)
expect(roster.get('aoneshot00000001')).toMatchObject({ state: 'working' })
})
it('keeps a confirmed idle teammate through folds that list teammate tasks', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'aprobe1-6d3cb5b5', { agentType: 'probe1' }, 100)
stopClaudeSubagent(roster, 'aprobe1-6d3cb5b5')
idleClaudeTeammateByName(roster, 'probe1')
// Parked confirmed teammates remain alive while inventory still has teammate tasks.
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'tprobe1', teammate: true })], 200)
expect(roster.get('aprobe1-6d3cb5b5')).toMatchObject({ state: 'idle' })
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'aunrelated0000001' })], 300)
expect(roster.has('aprobe1-6d3cb5b5')).toBe(false)
})
it('reaps an unconfirmed idle teammate-shaped row at the next complete fold', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'alane-hooks-6d3cb5b5', { agentType: 'lane-hooks' }, 100)
stopClaudeSubagent(roster, 'alane-hooks-6d3cb5b5')
expect(roster.get('alane-hooks-6d3cb5b5')).toMatchObject({ state: 'idle' })
// Unconfirmed idle workflow lanes must leave rather than rebuild the #8825 idle pile.
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'tteam1', teammate: true })], 200)
expect(roster.has('alane-hooks-6d3cb5b5')).toBe(false)
})
it('serializes snapshots deterministically ordered by startedAt then id', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'b', {}, 200)
upsertWorkingClaudeSubagent(roster, 'z', {}, 100)
upsertWorkingClaudeSubagent(roster, 'aidle-6d3cb5b5', {}, 100)
stopClaudeSubagent(roster, 'aidle-6d3cb5b5')
const snapshots = claudeRosterToSnapshots(roster)
expect(snapshots?.map((s) => s.id)).toEqual(['aidle-6d3cb5b5', 'z', 'b'])
expect(snapshots?.map((s) => s.state)).toEqual(['idle', 'working', 'working'])
expect(claudeRosterToSnapshots(new Map())).toBeUndefined()
})
})
describe('restored-row confirmation', () => {
const restored = (id: string): ClaudeSubagentRoster =>
new Map([
[
id,
{
state: 'working' as const,
startedAt: 100,
backgroundTasksAuthoritative: true,
restoredFromSnapshot: true
}
]
])
it('drops a restored row when no agent process is left behind it', () => {
const roster = restored('areview-loop-c237a4c577493352')
expect(claudeRosterHasRuntimeWorkingSubagent(roster)).toBe(false)
expect(reapUnconfirmedRestoredClaudeSubagents(roster)).toBe(true)
expect(claudeRosterHasWorkingSubagent(roster)).toBe(false)
})
it('keeps a row a live lifecycle event re-tracked', () => {
const roster = restored('areview-loop-c237a4c577493352')
upsertWorkingClaudeSubagent(roster, 'areview-loop-c237a4c577493352', {}, 150)
expect(claudeRosterHasRuntimeWorkingSubagent(roster)).toBe(true)
expect(reapUnconfirmedRestoredClaudeSubagents(roster)).toBe(false)
expect(claudeRosterHasWorkingSubagent(roster)).toBe(true)
})
it('keeps a row a live inventory confirmed as running', () => {
const roster = restored('a9')
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'a9' })], 150)
expect(reapUnconfirmedRestoredClaudeSubagents(roster)).toBe(false)
expect(claudeRosterHasWorkingSubagent(roster)).toBe(true)
})
it('leaves rows this listener tracked from live events alone', () => {
const roster: ClaudeSubagentRoster = new Map()
upsertWorkingClaudeSubagent(roster, 'a1', {}, 100)
expect(reapUnconfirmedRestoredClaudeSubagents(roster)).toBe(false)
expect(roster.has('a1')).toBe(true)
})
it('leaves the inventory reap of a restored row working', () => {
const roster = restored('aprobe1-6d3cb5b5')
foldClaudeBackgroundTasksIntoRoster(roster, [task({ id: 'other', teammate: true })], 200)
expect(roster.has('aprobe1-6d3cb5b5')).toBe(false)
})
})