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 observability data model with activation tracking to orchestration-v2

• Introduces OrchestrationV2SubagentActivation as a new schema and domain event type (subagent-activation.updated), tracked per subagent by ordinal with status, usage, and timestamps.
• Extends OrchestrationV2Subagent with new fields: kind, role, usage, currentActivationId, activationCount, workflow, workflowMembership, and recentActivity, all with decoding defaults for backward compatibility.
• Adds migration 44 (044_OrchestrationV2SubagentObservability.ts) that creates the orchestration_v2_projection_subagent_activations table and backfills missing fields in existing subagent payload rows.
• The orchestrator now emits subagent-activation.updated events when delegated subagent tasks start and reach terminal status; all provider adapters (Claude, Codex, ACP, Cursor, OpenCode) populate the new fields on subagent nodes.
• Client-side and server-side projection stores handle the new event type, upserting activation records into subagentActivations on the thread projection.
• Behavioral Change: orchestrationV2SubagentStatusAsTurnItemStatus maps the new idle status to completed; Codex adapter now routes subagent turn item statuses through this mapping rather than passing them directly.

^{Macroscope summarized 12b0111.}

[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: 48543b9f-bd9d-4032-99d6-e72115c3018a

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

[shivamhwp]

Not actually merged by review — a mistaken push put this branch's commits directly onto t3code/codex-turn-mapping, and GitHub inferred the merge from commit containment. The base branch has been restored to f117a4aa4. Continues as #4779.