Launch agents outside the lineage, and group children in the sidebar

[selfcontained]

Builds on the lineage/provenance work (#972 era): that shipped parentAgentId/relation on list_agents; this is the launch option and UI layer on top of it.

dispatch_launch_agent gains child

Default true — today's behaviour, unchanged. child: false launches an agent that is not part of the launcher's lineage: parent_agent_id stays null, so it owns a top-level sidebar card rather than nesting under whoever launched it. It still inherits the launcher's cwd, type, and access level (fullAccess stays capped by the launcher's, so a non-child launch can't escalate).

The launcher is still recorded, in a new launched_by_agent_id column (migration 0041, backfilled from parent_agent_id). parent_agent_id answers "whose card does this render in" — exactly the question child: false says no to — but the launcher created the session, and without recording it an independent launch would have no provenance and no owner allowed to archive it. So:

• dispatch_archive_agent accepts a target the caller launched, not only one it parented.
• The parent↔child bypass in messaging visibility extends to launcher↔launched, so the two can still coordinate across repo roots.
• list_agents reports launchedByAgentId/launchedByNameonly when the launcher is not already the parent — for a child it would just repeat parentAgentId in every row.

Sidebar is now actually parent-scoped

The top-level list was never "agents with no parent": it filtered out review children only (isNestedReviewAgent), so a plain child appeared as its own card and nowhere in its parent's Sub Agents section. Now top level is agents with no parent, and every child renders as a sub agent row.

Badges are unchanged by design: the REVIEW badge still keys off role = 'review' (set only by dispatch_launch_persona), and a plain child gets no badge — the absence is the signal.

Sub agent row action gaps

Moving plain children into that section would have stripped them of controls the agent card footer carries. Audited the footer (persona launcher, resume/pause, session settings, archive) against the row (attach/detach, resume, open review); the row gains Pause, Session settings, and Archive behind an overflow menu. Persona launch is deliberately not added — a child cannot launch reviews.

Depth capped at one level of children

A sub agent row cannot host rows of its own, so a grandchild would simply stop being visible. Enforced server-side in both launch paths: a child agent gets a 409 from dispatch_launch_agent with child: true, and a refusal from dispatch_launch_persona. It can still launch independent agents with child: false, which surface as their own top-level cards. Children are told this in their initial prompt rather than discovering it at the point of use.

Two cases the cap doesn't cover, both handled in the sidebar:

• Pre-cap deep trees already exist. The card lookup walks to the root rather than stopping at the direct parent, so any depth flattens into one list instead of losing the agents in the middle.
• Orphans. Only review children cascade on archive, so a plain child routinely outlives its parent. A child whose parent is not in the list is promoted to its own card.

This does walk back part of the reasoning behind the lineage work (which chose to surface deep chains rather than disallow them) — that's an intentional tradeoff, confirmed before building.

Verification

Against an isolated dev stack, through the real MCP endpoint (POST /api/mcp/<agentId>), confirming dispatch_launch_agent carried the new child param in tools/list before calling it:

	result
default child launch	parent_agent_id and launched_by_agent_id both set to the launcher
child: false	parent_agent_id null, launched_by_agent_id set; list_agents → relation: unrelated, launchedByName present
child → child: true	refused, "cannot launch further children"
child → dispatch_launch_persona	refused, "cannot launch persona reviews"
child → child: false	launched
launcher archives its child: false agent	accepted (no parent link to authorize it)

Before/after on the same live endpoint: with the source stashed and the API reloaded, the identical child-launching-a-grandchild call succeeded and wrote parent_agent_id = <the child>; unstashed, it is refused.

UI driven in Playwright against the same stack at 1500×1000, 390×844 and 320×700: sidebar regrouping, the overflow menu in both running and stopped states, and archive/pause/session-settings each driven through to a confirmed server-side state change (status = archiving, status = stopped, dialog bound to the sub agent rather than the parent). Archiving a sub agent live-promoted its surviving grandchild to a top-level card without a reload. On a review-ready row — which renders a full-bleed overlay button — the overflow trigger opens without firing the overlay, and the overlay still fires from the rest of the row.

Live agents

The above ran on the dev stack's default inert runtime, which spawns no tmux sessions or CLI processes. Repeated on dispatch-dev up --live with real Claude CLI agents, which is the only way to exercise the parts inert cannot reach:

• A real child agent's terminal carries the injected depth-cap notice ("You are a child agent: you cannot launch child agents or persona reviews of your own"); a real child: false agent's carries "as an independent agent — you are not its child" and no notice. Read off the live panes, not asserted on the handler argument.
• From the live child: child: true and dispatch_launch_persona both refused. From the live child: false agent: dispatch_launch_personasucceeded, and its reviewer appears as that agent's own sub agent row with the REVIEW badge — the orchestrator → independent builder → reviewers chain this feature exists to enable.
• Sub agent row controls against live processes: attach connects to a real terminal; detach disconnects while leaving the agent running and its tmux session intact; Pause stops the CLI and removes the session; Resume recreates it; Archive tears it down and removes the row.

All four live agents were archived and their sessions confirmed gone afterwards.

pnpm run check, finalize:web, 951 web tests, 2797 server tests and the 181-test e2e suite pass.

🤖 Generated with Claude Code