# Grid-agent operator TUI

The operator TUI is a pure-Rust, cross-platform Ratatui dashboard over the
versioned control plane. Embedded and split modes use the same reducer,
snapshots, widgets, commands, and authenticated control requests; the UI never
reads private runtime state. Standalone preferences uses the same Ratatui form.

Run an embedded UI with a live-grid integrated configuration:

```sh
cargo run --locked -p metacrate-grid-agent --features live-grid -- \
  --config config/grid-agent.integrated.example.yml --tui
```

Run a separate UI against a loopback split service:

```sh
cargo run --locked -p metacrate-grid-agent -- \
  --config config/grid-agent.split.example.yml --tui-client
```

The split client reads its operator capability from the ACL-restricted
`config.yml`. It never displays or copies that value. Remote
TLS clients must embed `TuiTransport` with their explicitly configured trust
roots; the command-line client intentionally accepts loopback TCP only.

Open preferences before a service is configured with
`metacrate-grid-agent --preferences`; the same panel is available from the live
TUI. It edits the endpoint, optional model, grid identity, hidden credentials,
mode, and privileged UUID list while preserving advanced YAML settings. Use
Up/Down to select, Enter to edit/commit, `w` to save, and Esc to cancel. Changes
to connection or authorization settings apply after restart. A one-time
`--import-env /path/to/.env` migrates legacy `GRID_*` and `OPENAPI_*` values.

The Overview dashboard shows readiness, region/pose, behavior, build and visual
work, approvals, and recent failures. Queues & budgets shows real queue and
rate-limit gauges, active work, outcome counts, dropped events, aggregate
latency, and a bounded 120-refresh history. Sessions, roaming schedules,
approvals, durable memory, timeline/audit, errors, diagnostics, health, and preferences retain
focused tables or panels and contextual detail. Missing backend data is marked
unavailable rather than estimated.

The Memory panel is operator-only. Enter loads the selected agent or record,
`g` changes the explicitly mapped avatar agent, `n`/`b` page, `k` cycles record
kind, `i` cycles pinned state, `o` changes sort, and `d` confirms a durable
tombstone. `/` searches content; `source:value`, `from:unix-seconds`, and
`to:unix-seconds` tokens set provenance and creation-time filters. Empty search
text browses all non-tombstoned records. Observer clients receive aggregate
agent/record health only and never memory identity, preview, or content.

Use Tab/Shift-Tab or Left/Right to change panels and Up/Down to select rows.
`/` searches event, audit, correlation, time, duration, result, and reason data;
Enter applies the search and Esc clears it. `r` refreshes; `p`/`u` pause or
resume; `f` reconnects the grid; `a`/`d` approve or deny the selected approval;
`x` cancels the newest visible action; `e` expires the selected session; `t`
toggles the selected roaming schedule; `s` requests shutdown; and `q` or
Ctrl-C exits. Mutations other than pause/resume require confirmation, with
shutdown marked high risk. Exiting or crashing a split TUI does not stop the
service.

Ratatui's Crossterm backend provides buffered/diff rendering without clearing
the full screen on every frame. Layouts respond to resize and collapse to a
compact status view on very small terminals; focus and failure markers remain
visible without color when `NO_COLOR` is set or `TERM=dumb`. Input, refresh
work, results, event history, errors, and performance history are all bounded.
Slow snapshots run outside the input reducer, and refresh ticks are dropped
when the bounded worker queue is full. The terminal guard restores raw mode,
cursor visibility, and the alternate screen on success, error, Ctrl-C, or
panic unwinding.

Diagnostic panels show only explicitly captured redacted envelopes. Memory
content appears only in the operator-only Memory detail panel; it is never
copied into diagnostics, audit events, or observer responses. API keys, grid
passwords, operator tokens, capability URLs, and model reasoning have no TUI
representation.

Focused verification:

```sh
cargo test --locked -p metacrate-grid-agent tui --lib
cargo test --locked -p metacrate-grid-agent --test preferences_config
cargo test --locked -p metacrate-grid-agent --test dependency_policy
cargo clippy --locked -p metacrate-grid-agent --all-targets --features live-grid -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked -p metacrate-grid-agent --no-deps
```