feat(app-server): render live Spine agent trees in Codex App

[kabxx]

Summary

This PR adds a strict opt-in, read-only live Spine task-tree view for Codex App.

• Each Spine-active turn gets one transient MCP App card.
• Updates in the same turn replace the same item through a monotonic revision.
• A later Spine-active turn gets a new card containing the complete tree accumulated by the active listener.
• Agent subtrees show child-owned nodes and nested agents without repeating the parent fork baseline.
• The UI projection is not written to rollout history or model context.

Implementation

• Adds an app-server-owned Spine UI runtime with generation-aware child routes, revision coalescing, terminal acknowledgements, timeout handling, rollback cleanup, and late-terminal refresh.
• Serves a self-contained ui://spine/tree.html MCP App resource with compact, validated payloads.
• Emits live Agent Running progress for agents that do not create Spine nodes.
• Filters the exact internal MCP carrier from TUI live items, Agent activity, and /mcp inventory while preserving ordinary MCP items.

Behavior

• Disabled by default; enable with CODEX_SPINE_APP_UI=1, true, or on.
• Same-turn updates are live-only and do not create history items.
• Cold resume can rebuild parent Core Spine nodes from ordinary rollout; those nodes can appear in a later new card.
• Old live cards, Agent live subtrees, routes, and live status are intentionally not restored after reload or restart.
• The TUI keeps its native Spine view and does not display the Desktop-only internal carrier.

Validation

• App-server Spine UI: 40/40 passed.
• Internal Spine MCP: 5/5 passed.
• Runtime/manager: 21/21 passed.
• Cold-resume E2E passed: live card, no internal rollout/history item, and rebuilt parent Core nodes in the next card.
• Core and TUI targeted regressions passed: 3/3 and 2/2.
• Formatting, checks, fix, build, and git diff --check passed with 8 jobs.
• Full app-server: 948 passed, 10 failures, 8 skipped. Full TUI: 3173 passed, 6 failures, 10 skipped. Every failure was reproduced on the latest main baseline and is outside this change.

Known limitation

Each new card contains the complete accumulated tree, so keeping many cards open can increase frontend memory and network usage with session length. The cards add no rollout or on-disk growth.

[Copilot]

Pull request overview

Adds an opt-in, live-only Spine task-tree visualization for Codex App by introducing an internal MCP App resource (ui://spine/tree.html) and app-server-side transient state/routing to keep the rendered tree current during a running turn without persisting it into thread history or model context.

Changes:

• Introduces a new internal Spine UI module in app-server that accumulates Spine tree + spawn progress + nested agent subtrees, emits live item/started + item/completed notifications, and exposes the UI via an internal MCP server/tool/resource when CODEX_SPINE_APP_UI is enabled.
• Adds robust routing/synchronization logic for nested agents (generation-aware forwarding, terminal acknowledgements, timeout barrier, and invalidation on rollback/listener lifecycle changes).
• Updates TUI rendering/filters to hide the internal Spine UI carrier items and internal MCP inventory entries, while keeping ordinary MCP tool calls visible; adds snapshot/test coverage and improves spawn progress “Running” reporting in core.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
codex-rs/tui/src/snapshots/codex_tui__multi_agents__tests__activity_preview_filters_internal_spine_ui_item.snap	Adds snapshot coverage ensuring internal Spine UI items are filtered from activity preview.
codex-rs/tui/src/multi_agents.rs	Hides internal Spine UI items from multi-agent activity summaries.
codex-rs/tui/src/lib.rs	Registers the new internal_spine_ui module.
codex-rs/tui/src/internal_spine_ui.rs	Implements exact-match detection for internal Spine UI items and server-status fingerprinting.
codex-rs/tui/src/history_cell/tests.rs	Extends MCP inventory tests to include internal Spine UI server status input (and validate filtering).
codex-rs/tui/src/history_cell/mcp.rs	Filters the internal Spine UI server from /mcp inventory output in the TUI.
codex-rs/tui/src/chatwidget/tool_lifecycle.rs	Drops internal Spine UI tool-call lifecycle items from live transcript rendering.
codex-rs/tui/src/chatwidget/tests/app_server.rs	Adds test ensuring live internal Spine UI items are not rendered into the transcript.
codex-rs/core/tests/suite/spine_spawn.rs	Adds integration coverage for spawn progress reporting Running even when children emit no Spine nodes.
codex-rs/core/src/spine/spawn.rs	Improves spawn progress emission by watching child status transitions and emitting progress updates accordingly.
codex-rs/core/src/spine/spawn_tests.rs	Adds focused unit tests for the terminal-status watch behavior.
codex-rs/core/src/session/mod.rs	Adjusts spawn progress delivery to be non-persistent and lightweight to emit.
codex-rs/app-server/tests/suite/v2/spine_ui_live.rs	Adds end-to-end v2 tests asserting Spine UI items are live-only and not restored after cold resume (while Core tree can be rebuilt).
codex-rs/app-server/tests/suite/v2/mod.rs	Wires the new Spine UI live test module into the suite.
codex-rs/app-server/tests/suite/v2/mcp_tool.rs	Adds tests for internal Spine tool-call behavior, collision behavior, and soft-off disabling.
codex-rs/app-server/tests/suite/v2/mcp_server_status.rs	Updates MCP server status tests to account for internal Spine server injection and pagination behavior.
codex-rs/app-server/tests/suite/v2/mcp_resource.rs	Adds resource-read collision tests ensuring internal resource wins only when enabled.
codex-rs/app-server/src/thread_state.rs	Introduces Spine UI runtime wiring into per-thread state and listener lifecycle cleanup/invalidation paths.
codex-rs/app-server/src/thread_state_spine_ui.rs	Implements per-thread Spine UI accumulation, revisions, terminal tracking, and carry-forward behavior.
codex-rs/app-server/src/thread_state_spine_ui_tests.rs	Adds comprehensive tests for Spine UI thread/runtime behavior, routing, coalescing, and race handling.
codex-rs/app-server/src/thread_state_spine_ui_manager.rs	Implements the manager-level routing, queuing, terminal barrier, and invalidation orchestration for child/parent Spine UI state.
codex-rs/app-server/src/spine_ui/tree.html	Adds the self-contained MCP App HTML UI for rendering the Spine tree, agents, disclosure behavior, and intrinsic height reporting.
codex-rs/app-server/src/spine_ui/render.rs	Defines the compact structured-content render payload for the UI (snapshot + spawn calls + agent subtrees).
codex-rs/app-server/src/spine_ui/mcp.rs	Implements enablement parsing, internal MCP server/tool/resource plumbing, and live-only item carrier creation.
codex-rs/app-server/src/spine_ui.rs	Adds core Spine UI state model, revisioning, filtering, and snapshot/spawn reconciliation logic.
codex-rs/app-server/src/spine_ui_tests.rs	Adds unit tests for activation rules, payload privacy/shape, stable IDs, parent filtering, and sync-timeout semantics.
codex-rs/app-server/src/request_processors/thread_lifecycle.rs	Integrates Spine UI routing/barrier behavior into listener task lifecycle and command handling.
codex-rs/app-server/src/request_processors/mcp_processor.rs	Injects the internal Spine MCP server/status/resource/tool-call handling when enabled.
codex-rs/app-server/src/outgoing_message.rs	Exposes subscribed connection IDs needed to target late terminal refresh notifications correctly.
codex-rs/app-server/src/message_processor.rs	Passes ThreadStateManager into MCP request processing to serve internal Spine tool calls.
codex-rs/app-server/src/lib.rs	Registers the new spine_ui module.
codex-rs/app-server/src/bespoke_event_handling.rs	Emits Spine UI live item notifications on SpineTreeUpdate/SpineSpawnProgress and completes the item on turn completion/interruption.
codex-rs/app-server/BUILD.bazel	Adds tree.html as compile_data to satisfy Bazel build-time file access for include_str!.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.