[Feature] Add read-only agent monitor TUI (Graph + Timeline) - #5339

Summary

Add an independent, read-only terminal viewer under tools/agent-monitor for one explicitly selected local Copilot CLI session, styled with Copilot CLI's own interface language. It answers the questions in the feature request: which agent launched which, who waited on whom and for how long, and what each finished execution produced.

Related: #1783

This is a standalone sidecar TUI, not a change to the Copilot CLI runtime or its built-in /tasks interface.

Screenshots

From a fictional demo session (synthetic events, no real transcript).

Graph (default view): spawn tree with launch modes and recorded wait durations; the dialog shows the selected agent's task, result and relationships.

Graph, selecting an agent that is blocked on the sync agent it launched:

Timeline: one swimlane per execution plus the main session's turns, waiting segments (╍), wait connectors (▾), a later turn of a reused agent, and the now cursor.

Open it from Copilot CLI

tools/agent-monitor/extension is an experimental Copilot CLI extension that adds /agent-monitor [graph|timeline|text] to the session you are working in. It prints the session's agent tree in the conversation, then opens the interactive Graph or Timeline beside the CLI as a Windows Terminal (or tmux) split pane:

● Agents · 7 executions: 1 running, 1 waiting, 3 done, 1 replied, 1 failed
  ○ main session · idle · 2m 41s
  ├─ ✓ api-consumers · explore · 9.0s · done
  │  └─ ↩ api-consumers · explore · turn · 6.7s · replied
  ├─ ✓ paging-scout · explore · 6.3s · done
  ├─ ✓ plan-critic · rubber-duck · 17.1s · done
  ├─ ◌ paging-impl · general-purpose · waiting on unit-tests 42.8s
  │  └─ ◐ unit-tests · task · 42.7s · running
  └─ ✗ web-build · task · 53.5s · failed

Proposal: a built-in Agents tab

The extension API has no way to add a tab to Copilot CLI's own tab bar, so the views open beside it. Built into the CLI, they could be one more tab next to Current and Sessions, with Graph and Timeline as sub-views:

What changed

• Copilot CLI look: tab bar, blue query chips, ·-separated key hints, bordered detail dialog, and Primer semantic colors for the /theme modes (--theme default|light|dim|high-contrast|colorblind).
• Graph (default view): spawn tree with automatic layout. Edges show bg / sync plus recorded wait durations, naming the waiter when it is not the edge's parent. A reused agent's later turns sit side by side under its first turn. Cards narrow to fit a wide fan-out; beyond that the graph scrolls with the selection.
• Timeline view: swimlanes for every execution plus the main session's turns, waiting segments and connectors, a now cursor, and zoom/pan. The default window focuses on agent activity.
• Detail dialog: task prompt, final message or error (latest message while running), and recorded relationships. Tool calls stay hidden until t is pressed. Below 100 columns the dialog uses one column.
• Statuses: done, failed, cancelled (recorded cancelled: true, not a failure), replied (final answer and turn end recorded without a lifecycle event), and last-observed running / waiting.
• Replay and live follow remain read-only; partial records, source resets, session shutdown/resume, unsupported agent data, and source errors stay explicit.
• Copilot CLI extension (experimental): /agent-monitor [graph|timeline|text] prints the agent tree in the conversation and opens the interactive view beside the CLI; the viewer also takes --view graph|timeline.

Review

Reviewed adversarially by two opposing agent groups, each with a separate production-code and test-code reviewer: one group argued for defects, the other challenged each claim against the event schema, synthetic reproductions, and aggregate counts from local logs. Confirmed findings were fixed in e40bc24. All 13 findings from the automated Copilot review on this PR were confirmed and fixed in f1b635c (control-sequence cleaning for every drawn string, read-failure reporting, shutdown/resume and superseded-turn lifecycle cases, early waits, multi-day timeline ticks, and tree-build cost).

Validation

• npm run typecheck and the strict unused-code check (--noUnusedLocals --noUnusedParameters) pass.
• npm test: 37/37 pass. The 10 tests for the review fixes fail on the previous commit; each of the 5 new guard tests fails when its guard is removed; the 8 tests added for the automated review findings fail without f1b635c.
• npm run build passes; built --help verified.
• Replay of 219 local session logs (aggregate counts only, no content committed): 5,040 Graph/Timeline frames at 80×24, 120×36 and 160×48 rendered with 0 errors and 0 mis-sized rows; maximum tree depth is now 6. Of 9 recorded cancellations, 1 cancels a follow-up turn (now cancelled); 8 arrive after the agent had already completed with no follow-up turn and now keep completed instead of moving its end time to the cancellation. One CLI 1.0.21 log is rejected with an explicit diagnostic.
• Windows ConPTY end-to-end run of the built CLI on this branch: Graph/Timeline switching, resizing through a too-small terminal and back, live follow of session.shutdown (ended) and session.resume (following again), quit with exit code 0 and alternate-screen restore, the source log left byte-for-byte unchanged, and a malformed record stopping the source with exit code 1. The run also found that keys arriving in one input chunk (a held key during a slow render) were dropped; fixed in e021792 with a test.
• Extension, in a real Copilot CLI 1.0.105 session started with --experimental under ConPTY: /extensions manage lists agent-monitor as running, and /agent-monitor text prints the tree in the conversation. The split-pane launch was checked in Windows Terminal: the pane's process received the viewer arguments intact, including a Node.js path containing spaces.
• Only synthetic fixtures and fictional screenshots are committed; private session logs are not.

Local preview

Requires Node.js 22+ and a truecolor terminal (Windows Terminal works). In a separate terminal tab:

Set-Location "<checkout>\tools\agent-monitor"
npm ci
npm run build
node .\dist\cli.js --session "<absolute-session-directory>"

Keys: j/k select, Tab or v switches Graph/Timeline, f filters, t toggles tool calls, Page Up/Down scrolls the result, +/- and ←/→ zoom and pan the Timeline, q quits. To use it from inside Copilot CLI, see the extension section of the README.

Limitations

• The verified on-disk format is Copilot CLI 1.0.104 and 1.0.105 and is version-sensitive.
• Copilot CLI extensions are experimental, and the extension API cannot add tabs to the CLI's own tab bar.
• Spawn edges and recorded waits are not a complete prerequisite DAG. Unrecorded dependencies are labeled not recorded rather than inferred.
• Ephemeral events, such as live shell output, and unrecorded results, cancellation, or liveness cannot be reconstructed.
• Building this package does not rebuild or replace the copilot executable.