# Cockpit Surfaces

The web UI has **eleven tabs**, plus two app-level modals. The active tab
persists in the URL hash (`#inventory`, `#sessions`, …) so views deep-link.
The header shows a Bridge health pill, the executor URL, live counts
(`N stacks · N running · N responses needed`), a runtime-coverage mini-matrix
(`host ✓ · docker ✓ · vm ✓`), and three global verbs: **＋ Launch instance**,
**▸ Start a session**, and **Copy CLI**.

Header data degrades independently: inventory and health are load-bearing,
while the running board, approvals, and cost each fall back to empty on error
without taking the header down.

## The tabs

### Home

The operator wall. A radial topology map of the eleven surfaces around the live
stack count, a running stack-board (up to six instance cards), a telemetry
strip, a guided-start planner (pick stack → runtime → task), and a cost-quota
donut. Two review layouts — **Topology** (default) and **Handoff** (mission
route emphasis) — switchable in the UI or deep-linked with `/?wall=handoff`.
First run shows a three-point tour. Disconnected state renders a "No stack
connected" card with bring-up guidance.

### Inventory

The fleet table: one row per instance with runtime posture (isolation badge +
warning), loadout (+ image ref), transport posture (trust badge, mode, stale
flag), host-daemon status (with the documented operator command when action is
needed — never auto-run), health state, and tenant. Per-row actions:

| Action | Behavior |
|---|---|
| **Session** | Start a session on the instance; disabled until a session backend reports `available`, with the reason as tooltip |
| **Snapshot / Checkpoint** | Create a provider-backed fast-start asset when Cloud Hypervisor or libvirt advertises the required capability |
| **Restore / Fork / Warm pool** | Launch from an opaque sandbox asset through `runtime_options`, then poll the async operation to terminal state |
| **Reconnect** | Recover a stale agent — rendered for running docker/container **and vm/qemu/kvm** rows whose agent is unreachable ([Recovery](./recovery.md)) |
| **Stop / Start** | Lifecycle toggle by state |
| **Destroy** | Confirmed, irreversible; executor-owned lifecycle first, with local Docker removal only when the development fallback is explicitly enabled |

Health distinguishes a stopped runtime from a running runtime whose agent has
dropped: the latter renders **`agent unreachable`** and stays visible instead
of vanishing.

Inventory also displays executor-provided GPU/VFIO posture: provider/loadout
compatibility, assigned VFIO devices, and reasons a runtime cannot expose GPU
resources. When VFIO is requested, Cockpit sends
`required_capabilities:['device.vfio']`, excludes fast-start capabilities, and
uses `fallback_mode:'fail'`; this surfaces a safe cold-launch intent instead of
making GPU passthrough generally available.

### Running

Read-only board of active work across all stacks — instance, runtime,
transport, task, state — with a cross-stack spend line and a per-task **Stop**
control (cancels the A2A task).

### Missions

A read-only projection of Mission Control state: totals
(active / awaiting / terminal), a session list, per-session mission tables
(status, source, loop, backing), and the audit tail. Data merges durable
`aiwg mc` on-disk sessions with the live executor task session.

### Sessions

The terminal workspace — see [Sessions](./sessions.md) for the full attach
model. Two panes: an instances→sessions navigator (badges for controller,
unread output, response-needed, and live attachment) and the xterm terminal
with backend mode select, control row (Observe · Drive/Take Control ·
Keyframe · Reattach+replay · Detach · Reconnect), a capability picker, and a
composer. The panel stays mounted across tab switches so live terminals
survive navigation.

### Approvals

The unified response-needed inbox. Two sections: **Response Needed** (merged
interactive prompts detected in pty sessions and the session registry, each
with an **Open Session** deep link) and the formal **approvals table**
(`hitl-prompt/v1` requests with risk badges and **Approve / Deny** decisions).
A decision is operator authorization — it posts through the Bridge to the
executor's A2A respond surface.

### Explore

Live artifact-index operations (status summary, per-graph cards, query,
**Rebuild all**) plus read-only AIWG capability search (the same
`aiwg discover` index) with a detail viewer for any skill, agent, command,
rule, or flow. `Ctrl/⌘-K` focuses capability search from anywhere.

### Library

Your own assets, stored under `~/.aiwg/cockpit/library` — cloned from the
AIWG catalog or imported. Actions: **Clone** from the catalog, **Use** (inject
a capability reference into the active session and jump to Sessions), and
**Remove**. AIWG install files are never overwritten; the library holds
operator-owned copies only.

### Telemetry

KPI tiles (Events, Active Missions, Approvals, Spend) over a unified,
filterable event table (mission / task / approval / session / inventory) built
from the Bridge's event-snapshot model. Sandbox MCP discovery appears here as
client-safe status: protocol and transport posture, tools, resources/templates,
scopes, and principal hints. Executing MCP traffic through Cockpit uses the
Bridge proxy and a separate MCP token file; discovery metadata alone is
display-only.

### Memory

Operator notes plus auto-created Mission completion notes. Mission notes come
from durable `aiwg mc` state via the Bridge; **operator notes are
browser-local** (localStorage), scoped to the browser profile — they do not
sync across shells or machines.

### Actions

Contributed actions, first-party screens, and workflows from declarative
contribution manifests. An action **injects a command into an agentic
session** — the agent in that session runs it; Cockpit never executes CLI
commands itself. Actions that need arguments prompt for them; every injection
records an `action.inject.requested` intent in the audit log. First-party
contributions include issue-audit, address-issues, and doctor.

## App-level modals

- **Start a session** — pick instance (with runtime + posture context) and
  session backend, then create. Inline errors; a 15-second guard aborts hangs;
  offers "Start another session" when you're already attached.
- **Launch instance** — provision a new runtime target through the executor's
  v2 admin API: `host`, `docker` (image, mounts, agent-share), or `qemu`/VM
  (SSH public key required, agent-share optional). VM launches can choose an
  advertised provider and GPU/VFIO posture; Cockpit passes provider,
  required/excluded capabilities, launch strategy, and constraints through the
  sandbox `runtime_options` contract. Generates collision-resistant instance
  names, can auto-start a session once the instance is ready (readiness polling
  with fast-fail on terminal states), and never replaces an attached session.

## UX details worth knowing

- Selection is sticky: Sessions keeps your instance/session/backend choice
  across refresh polls while it remains valid or attached.
- Badges: isolation, transport trust, daemon status, `ctrl` (you hold
  control), unread output, response-needed, live ●, high-risk approvals.
- Destroy, End session, and Library remove are confirm-gated.
- `Copy CLI` copies `aiwg cockpit` for sharing the launch command.

## See also

- [Sessions](./sessions.md) — the attach model behind the Sessions tab
- [Trust & Security](./trust-and-security.md) — what the badges mean
- [Bridge API](./bridge-api.md) — the endpoints each tab consumes
# Flow / graph run view

The Missions surface includes a read-only `graph.flow.aiwg.io/v1` ledger view
when graph metadata is present. Operators can filter graph-profile runs from
ordinary Flow/Mission runs and inspect node state, runtime binding, route
reason, redacted evidence summary, HITL posture, retry count, cost/tokens, and
checkpoint/replay lineage. Missing graph metadata or node ledger rows degrade
to the ordinary Mission view. Raw route evidence is not rendered. Visual graph
editing and runtime scheduling decisions remain explicitly out of scope.
