feat(orchestration-v2): add subagent observability data model (1/5)

[shivamhwp]

First of five stacked PRs replacing #4551, which bundled the whole subagent-observability feature into one ~3,100-line change. Splitting it out so each piece can actually be reviewed; the seams between these pieces are where the bugs were hiding.

Scope: data model, storage, and migration only. Nothing produces the new data yet. Adapters are given neutral defaults so every subagent row stays valid. Populating them for real is 2/5, and reuse semantics are 3/5.

What's here

Contracts gain a reusable subagent identity — per-activation records (SubagentActivationId, OrchestrationV2SubagentActivation), cumulative usage, a role, recent activity, and workflow grouping. A subagent can also now rest at idle between activations.

Migration 043 backfills existing rows so old events stay readable.

The status mapping is the important part

A subagent status is not a turn item status — idle has no timeline equivalent. The two are bridged by an explicit Record<subagent status, turn item status> rather than a copy, which makes the mapping total: adding a subagent status without giving it a timeline meaning is a compile error.

This is not hypothetical. An earlier iteration copied the raw status through, which wrote a turn-item.updated event that its own schema could not decode. Nothing failed at write time — but the projection rebuild runs at startup and died on that stored event, so the server became permanently unbootable with no in-app recovery. Adding idle in this PR immediately trips the new compile error at CodexAdapterV2.ts, which is the guard doing its job.

Notes for review

• Envelope attribution change: ProviderEventIngestor no longer replaces an explicit null runId/nodeId with the ambient run. Activations legitimately have no run id. The envelope is persistence metadata only (routing reads payload fields), but this does change stored metadata for existing event types that already pass explicit nulls.
• Migration risk path: the one genuinely risky case is a partially-migrated row, where already-present JSON round-trips through COALESCE. A test pins that structured values keep their JSON subtype rather than being rewritten as quoted strings.
• A database bricked by the earlier broken build is not repaired by this PR — turn items still correctly reject idle. Only relevant if that build ran anywhere beyond local dev.

Testing

Typecheck clean and lint clean across server, contracts, client-runtime, and web.

• server 1,676 passing
• contracts 223 passing
• client-runtime 481 passing
• web 1,498 passing

Also booted a server on a fresh state directory and confirmed migration 043 applies and the app starts.

Reviewed by an independent agent pass before opening; its findings on helper scope and the missing mixed-row migration test are folded in.

---

Note

Medium Risk
Touches event-sourced projections, a new migration with JSON backfill, and envelope attribution semantics; mistakes could corrupt stored events or startup rebuilds, though tests target the risky migration and status-mapping paths.

Overview
Introduces the orchestration v2 subagent observability contracts and persistence layer ahead of adapter/UI work. Subagents gain reusable identity fields (kind, role, usage, activationCount, workflow, recentActivity, etc.), a new resting idle status, and separate OrchestrationV2SubagentActivation records with a subagent-activation.updated domain event and SQLite projection table (schema version 3).

Migration 043 backfills legacy subagent JSON and creates activation storage; tests cover partial backfills and projection rebuild cleanup of stale activation rows.

Provider adapters and the orchestrator only wire neutral defaults and minimal lifecycle hooks (e.g. delegated-task spawn/terminal activation events); real population is deferred. Codex now maps subagent status to turn-item status via orchestrationV2SubagentStatusAsTurnItemStatus so idle cannot be written raw onto timeline rows.

ProviderEventIngestor stops substituting ambient runId/nodeId when the payload explicitly passes null, so detached activations and messages keep correct envelope metadata.

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

Note

Add subagent activation observability data model to orchestration-v2

• Introduces OrchestrationV2SubagentActivation as a new entity tracking per-activation lifecycle, usage, and timing separately from subagent identity, with a new SubagentActivationId branded type.
• Extends OrchestrationV2Subagent with observability fields: kind, role, usage, currentActivationId, activationCount, workflow, workflowMembership, and recentActivity (all with safe defaults for legacy rows).
• Adds database migration 044 (044_OrchestrationV2SubagentObservability.ts) creating the orchestration_v2_projection_subagent_activations table with indexes; existing subagent rows are not backfilled.
• Emits subagent-activation.updated domain events on subagent dispatch start and terminal completion in the orchestrator and all provider adapters (ACP, Claude, Codex, Cursor, OpenCode).
• Projection stores (server and client-runtime) now upsert activation records on subagent-activation.updated events; projection rebuild purges stale activation rows before replay.
• Behavioral Change: projection schema version bumped from 2 to 3; ProviderEventIngestor no longer overwrites explicit null runId/nodeId with ambient values.

^{Macroscope summarized 313ae4d. (Automatic summaries will resume when PR exits draft mode or review begins).}

[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: 0e7a5067-d3e9-4b1e-a035-bd5351b46527

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/01-contracts

---

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.}