# Delegation viewer

The delegation viewer is a second-terminal live view of orchestrator delegation: keep the parent Pi TUI in one pane and run the viewer beside it. It renders the lifecycle DAG (explore → analyze → plan → implement → verify → deploy), the background-job lane, the routing rungs actually walked per phase, and a scrubbable timeline — all from the same privacy-safe snapshots the parent TUI already shows.

It is a small Rust/ratatui binary in [`tui/`](../tui/), built separately from the npm package:

```sh
cargo install --path tui           # or: cd tui && cargo build --release
```

`arc-pi monitor tui` resolves the binary from `ARC_PI_MONITOR_TUI`, then the in-repo `tui/target/{release,debug}` build, then `arc-pi-monitor-tui` on `PATH`, and fails with build instructions if none exists.

```sh
./bin/arc-pi monitor tui --session-id <id>   # watch one session
./bin/arc-pi monitor tui --follow            # newest session; reattaches after idle
ARC_PI_SESSION_ID=<id> arc-pi-monitor-tui    # session inferred from the environment
```

Useful flags: `--theme <path>` loads any Pi theme JSON (`github-dark-default` and `steel` are built in), `--interval-ms` sets the monitor poll interval, `--arc-pi-home` points `--follow` at another registry root, and `--stdin` reads `watch --json` NDJSON instead of spawning the monitor — which also gives you an offline demo:

```sh
arc-pi-monitor-tui --stdin < tui/fixtures/live.ndjson      # full lifecycle to completion
arc-pi-monitor-tui --stdin < tui/fixtures/blocked.ndjson   # terminal verify failure
```

## Reading the viewer

Each node is one delegated run for a lifecycle phase. `analyze` always renders as a parent node, never a worker. Under the status row are that phase's routing rungs from [ARC Delegate v4](arc-delegate.md): **✓** produced the result, **✗** advanced past for an availability reason, **●** currently active, **◇** never reached. A verify failure is terminal — it draws a red `fail → terminal` edge into a blocked `revise-contract` node and dims the deploy gate, never a silent retry edge. Opt-in `arc-bg-…` jobs get their own right-hand lane.

The inspector tabs are Steps, Activity, Files, Diffs, Contract, Routing, and Info. Contract shows bounded registry metadata (label, phase, route, workload class, tokens) — raw task text, absolute paths, and transcripts are never sent to the viewer, and redacted or omitted diffs show a count or reason instead of content.

## Keys

| Key             | Action               | Key           | Action                |
| --------------- | -------------------- | ------------- | --------------------- |
| `q`             | quit                 | `Space`       | play / pause replay   |
| `Tab` / `1`–`7` | inspector tabs       | `←` `→`       | previous / next event |
| `↑` `↓`         | focus a node         | `Home`        | first event           |
| `l`             | jump back to live    | `f`           | toggle follow         |
| `−` `+`         | playback speed       | `;`           | cycle theme           |
| `z`             | density              | `PgUp` `PgDn` | scroll the graph      |
| `[` `]`         | scroll the inspector |               |                       |

## With Herdr

Herdr manages agent terminals as workspaces, tabs, and panes, which makes it the natural home for a viewer pane next to the parent session (verified against `herdr` 0.8.0). From the pane running ARC Pi, split beside it and start the viewer without moving your focus:

```sh
pane=$(herdr pane split --current --direction right --cwd "$PWD" --no-focus \
  | jq -r .result.pane.pane_id)
herdr pane rename "$pane" arc-viewer
herdr pane run "$pane" ./bin/arc-pi monitor tui --follow
```

Split `right` from a wide pane and `down` from a narrow one. `--follow` is the right mode here: the viewer attaches to the newest session in the run registry and reattaches on its own after the monitor stops on idle, so the pane keeps working across successive delegations without being restarted.

Inside a Herdr-managed pane the session is already in the environment, so `arc-pi-monitor-tui` on its own picks up `ARC_PI_SESSION_ID` when ARC Pi exported it. To pin the viewer to one specific session instead of following the newest, pass `--session-id` explicitly.