Add subagent activity visibility

[Quicksaver]

Summary

This branch turns Codex subagent work into first-class, routeable child threads instead of mixing every child output item into the parent timeline. Parent conversations now show compact subagent activity blocks, while each child thread owns its prompt, output, tool activity, file changes, and nested child summaries.

The implementation is Codex-scoped. Providers without durable child-thread lineage continue using the previous fallback behavior.

Fixes #538.

What Changed

• Added persisted projection-thread parent relations with root thread ids, direct parent thread ids, parent activity metadata, provider child thread ids, depth, start/completion timestamps, and subagent status.
• Added migrations and backfill coverage for projection-thread parent/root relation fields and lookup indexes.
• Extended Codex adapter and provider ingestion to map Codex child sessions into deterministic local child thread ids, preserve raw child prompts separately from title seeds, carry parent-collab lineage metadata, synthesize early child shells, append launch prompts into child timelines, and update resumed child work as new parent activity blocks.
• Added orchestration safeguards so normal root/default projection upserts do not overwrite existing subagent relations.
• Added subagent lifecycle handling for terminal status updates, stop/interrupt targeting, missing-child-turn failure handling, and root archive/delete cascades through active descendant subagent threads.
• Updated parent timeline rendering so child output/actions no longer jumble into the parent view; parent rows render compact subagent blocks with status and duration.
• Updated child thread routing so hidden terminal subagent threads remain openable from parent blocks and show a subagent control bar instead of the normal composer.
• Updated sidebar rendering so running subagents nest under their direct parent, terminal subagents normally hide from the sidebar, the active terminal-child path remains visible while selected, hidden terminal ancestors remain structural for descendant indentation, and the active route shell is retained while sidebar state catches up.
• Hardened resumed-child rendering so same-turn subagent activities remain separate when Codex reports distinct parent collab item ids, live status only follows the matching parent item/turn, and legacy rows without item ids still fall back to turn matching.
• Added shared subagent display helpers for status tones, duration labels, and active/terminal wording.
• Added web/client-runtime tests for subagent timeline rendering, duplicate parent rows, sidebar hidden-ancestor traversal, active terminal child path retention, subagent sibling ordering, child composer suppression, duration labels, and retained stream-backed thread state.
• Added SUBAGENTS.md to document the implemented behavior, provider scope, decisions, verification, and remaining hardening areas.

Why

Subagent output currently becomes very jumbled and impossible to follow when child work, tool calls, diffs, and parent activity all render in the same parent conversation stream. This change gives subagent activity proper visibility: the parent remains readable, active child work is discoverable, and detailed child output is still reachable in its own thread.

Validation

• pnpm exec vp check passed. It reported 20 existing lint warnings in unrelated mobile/markdown/command-palette files and 0 errors.
• pnpm exec vp run typecheck passed across all 15 packages.
• pnpm --filter t3 exec vp test run src/provider/Layers/CodexAdapter.test.ts src/orchestration/Layers/ProviderCommandReactor.test.ts src/orchestration/Layers/ProviderRuntimeIngestion.test.ts --reporter=dot passed: 3 files, 103 tests.
• pnpm --filter @t3tools/web exec vp test run src/session-logic.test.ts --reporter=dot passed: 1 file, 66 tests.
• pnpm --filter @t3tools/web exec vp test run src/components/Sidebar.logic.test.ts src/components/chat/MessagesTimeline.test.tsx --reporter=dot passed: 2 files, 71 tests.
• pnpm exec vp test apps/web/src/components/Sidebar.logic.test.ts apps/web/src/components/chat/MessagesTimeline.test.tsx passed after the final review fixes.
• coderabbit review --agent --base-commit f744946f16b1858f2bd52b702949f97a9ab31a69 -c AGENTS.md passed with 0 findings after a rate-limit retry.
• codex exec --sandbox read-only --json --output-last-message /dev/fd/3 review --base f744946f16b1858f2bd52b702949f97a9ab31a69 found two edge cases that were fixed in f282a2bf.
• $blast-review found additional parent-collab/sidebar/doc hardening that was fixed in 20c2897f.
• Cursor Bugbot follow-up review on 20c2897f found three sidebar/status edge cases that were fixed in 8516959, 2ef7d4d, 92b6596, and 498a130.
• CodeRabbit review on 8516959 found 0 issues.
• Codex review on 8516959 found one legacy fallback issue that was fixed in 2ef7d4d.
• $blast-review on 2ef7d4d found additional matching/readability/test/performance hardening that was fixed in 92b6596.
• Final CodeRabbit review on 92b6596 found 0 issues.
• Final Codex review on 92b6596 found one item-id-only compatibility issue that was fixed in 498a130.

Proof

subagents.mp4

---

Note

High Risk
Large cross-cutting change to orchestration, persistence migrations, provider ingestion, and thread lifecycle; incorrect subagent routing or cascade delete/archive could affect live sessions and data integrity.

Overview
Codex subagent work is modeled as first-class child threads with persisted parentRelation metadata, instead of mixing child output into the parent timeline.

Server / data: Projection threads gain parent/root lineage columns (migrations 33–34), snapshot queries expose parentRelation, and upserts preserve existing subagent rows. Codex runtime maps collab child sessions to deterministic local thread ids, attaches subagentChildren / parentCollab on events, buffers child deltas until the parent collab item completes, and ingestion creates or updates child shells, appends raw launch prompts via thread.message.user.append, generates child titles, and tracks terminal status. Subagent interrupts go through the provider-bound root session; archive/delete cascades to descendants.

Web: The sidebar nests running subagents under parents, hides terminal children unless on the active path, and parent timelines show compact subagent blocks (not child tool/diff noise). Child views use a SubagentControlBar (stop + parent navigation) instead of the composer.

Scope is Codex-only; other providers keep prior inline behavior. SUBAGENTS.md documents the implemented plan and remaining hardening items.

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

Note

Add subagent thread visibility with hierarchical sidebar display and cascading lifecycle operations

• Introduces OrchestrationThreadParentRelation to the contracts layer, adding parent/child relationship metadata to thread models, commands, and event payloads across the stack.
• Server-side ingestion in ProviderRuntimeIngestion now creates and tracks subagent child threads from provider collab events, generating deterministic child thread IDs and maintaining parentRelation state through the projection pipeline.
• thread.delete and thread.archive commands now cascade to subagent descendants in depth-first order; project.delete with force targets lifecycle root threads first.
• The sidebar renders subagent threads as nested children with depth-based indentation, hides terminal subagents unless on the active navigation path, and prevents archive/delete actions on subagent rows.
• The chat view renders a SubagentControlBar for active subagent threads showing live status, elapsed duration, and a Stop button; the messages timeline shows per-child subagent rows with navigation to child threads.
• Two database migrations (033, 034) add and backfill parent_kind, root_thread_id, and related subagent columns on projection_threads.
• Risk: The upsert conflict logic preserves existing subagent relation values when an update arrives without subagent context; incorrect event ordering could leave stale subagent metadata in the projection.

^{Macroscope summarized 62c9a54.}

[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

Run ID: f7f09c6e-bf82-49ff-a57b-f3269b131e64

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

---

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 and usage tips.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 20c2897. Configure here.}

[juliusmarminge]

#2829