feat(orchestration-v2): add native subagent and workflow observability

[shivamhwp]

This adds native subagent and workflow observability to Orchestrator V2. It is based directly on the V2 implementation in PR #2829; no V1 runtime or compatibility data source remains in this PR.

Why this PR exists

Orchestrator V2 has its own event model, projection, provider boundary, recovery path, and thread lifecycle. When V2 ships, provider-native child work needs V2-owned identities and activations so the Agents experience stays accurate through reuse, interruption, restart, nesting, and background completion.

Before and after

The comparison below is against the current t3code/codex-turn-mapping V2 base, not main/V1.

V2 base — before	This PR — after
Every native child renders as a separate timeline row. Internal child threads also appear in Lineage.	One compact CTA represents the spawn batch; live state, settled count, and token totals update in place. Internal provider child threads stay out of the sidebar and Lineage.
Completed children remain separate cards in the conversation.	The CTA opens one detailed Agents panel with stable rows for role, duration, progress/result, model, tokens, tools, status, and aggregate totals.

Responsive web verification at 390×844:

What changes

V2 domain and persistence. Reusable subagent identities and immutable per-activation records live in the V2 projection. Migration 050 persists activations, and schema defaults keep older V2 payloads readable without a backfill.

Provider-native projection. Claude, Codex, Cursor, OpenCode, and ACP/Grok emit V2 subagent and activation lifecycle updates, including role, usage, recent activity, workflow membership, activation counts, idle state, and provider-reported nesting.

Reuse and recovery. Reused agents bind to the run that reactivates them. Activation proof prevents stale post-interrupt traffic from attaching to a later run, and recovery retains the cumulative usage baseline.

V2-only client state. The Agents panel derives directly from OrchestrationV2Subagent[]. The V1 activity fold, dual-source fallback, and obsolete tests are removed. V2 timeline items collapse into one CTA per workflow or direct-spawn batch.

Internal thread visibility. One shared V2 predicate controls filtering on server, web, and mobile. Hidden child deep links resolve through the existing targeted projection RPC and redirect to their parent without adding child shells to the global stream. Unfiltered thread refs remain available for cleanup so hidden worktrees are not mistaken for orphans.

Explicitly not included

• No V1 orchestration runtime, V1 activity fold, or compatibility data source.
• No second Agents panel or alternate roster.
• No new targeted subagent-stop command or backend-only provider-control path.
• No replacement for background liveness or workflow script inspection already present in the V2 base.

Current stack

• Base: 4c55679fdf6387808d815b69f486b6caadadad6f (t3code/codex-turn-mapping)
• Head: 0d57bbdf838b07163c11a9b2da2914db75106fc5
• 57 commits, 89 files, +7,406 / -2,434
• Rebased onto the current V2 base; no merge conflicts remain locally

Verification

• 171/171 changed UI and client-runtime tests pass
• 179/179 focused Orchestrator V2 and provider-adapter tests pass
• Targeted formatting, lint, diff whitespace, web typecheck, client-runtime typecheck, and contracts typecheck pass
• Chrome: live and completed native-agent batches, Agents-panel open/close, keyboard focus ring and pointer affordance, responsive 390×844 layout, no horizontal overflow, no top-level child-thread leakage, and hidden-child deep-link redirect
• Clean reload and redirect flows produce no browser console errors
• Server typecheck still hits the same unrelated ProviderSessionManager.test.ts:836 error on the untouched V2 base

Provider limitation: if a provider reports a nested agent only inside its parent's final text and emits no lifecycle frame, T3 shows that summary but does not invent a nested agent row.

Built with Codex (GPT-5.6 Sol) through T3 Code.

Note

Add subagent activation tracking and observability to orchestration-v2

• Introduces OrchestrationV2SubagentActivation as a first-class contract type with id, status, usage, timestamps, and ordinal; persisted in a new orchestration_v2_projection_subagent_activations table (migration 050) and returned as part of thread projections.
• All provider adapters (Claude, Codex, Cursor, ACP, OpenCode) now emit subagent_activation.updated events, accumulate token usage per activation, track currentActivationId, and propagate terminal status on turn completion.
• Internal subagent threads (lineage subagent or node-forked) are filtered from shell snapshots, sidebar, and thread-ref lists; deep links to hidden threads redirect to the parent thread on both web and mobile.
• The messages timeline collapses per-subagent events into grouped CTA rows (AgentSpawnCtaRow) showing aggregated status buckets and token totals; the Agents panel now indents nested direct-spawn agents.
• Run execution service gains identity-based routing for reusable subagents: a run can re-adopt a subagent after idle by proving activation-count progression, and activations keep runs open while live.
• A new listAllThreadRefs WS RPC (requiring orchestration read scope) returns unfiltered thread refs including hidden subagents, used by worktree cleanup to avoid orphaning subagent worktrees.
• Risk: projection schema version bumped from 2 to 3; the ./state/subagentRuntime client-runtime export is replaced by ./state/thread-subagents.

^{Macroscope summarized 0d57bbd.}

---

Note

High Risk
Large cross-cutting changes to provider adapters, projection schema/persistence, and run attribution for reusable subagents; incorrect reuse or stale-event handling could mis-route events or strand background work.

Overview
Orchestration V2 gains per-activation subagent records (subagent_activation.updated, usage, currentActivationId, roles/kinds, workflow workers) projected from Claude, Codex, Cursor, and ACP adapters, with registry/rehydration from existingSubagents after idle or restart and race-safe resume/terminal handling (Codex idle vs completed, Claude commitClaudeSubagentRegistryEntry, nested Agent/Workflow parenting).

Clients treat internal subagent threads via isOrchestrationV2InternalSubagentThread: sidebar/list filtering, mobile deep-link redirect to parent plus a short unavailable delay, relationships banner drops stale subagent edges, and work log no longer links subagent rows as separate threads. Server adds listAllThreadRefs (orchestration read scope) so cleanup sees hidden child worktrees.

Tests/fixtures expand for activations, Codex reuse-after-idle replay, and list filtering (including node-forked children).

^{Reviewed by Cursor Bugbot for commit 0d57bbd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bde13937-a17e-478e-b7e2-db16c3d0c4b4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch subagent-obs/05-thread-visibility

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}