# SPEC-005: Machines List View — Dual Connection Indicators + Rich Rows

**Status:** Proposed
**Priority:** P2
**Requested By:** Mike (2026-05-30)
**Estimated Effort:** Medium

## Overview

Bring the Operator Console Machines list to ScreenConnect "Access"-list parity: each row
gains (1) **dual connection indicators** — a two-segment bar showing Host and Guest
connection state at a glance — and (2) **rich inline metadata** (company, site, device
type, tags, logged-on user + idle, client version) instead of today's bare
status-dot / hostname / OS / last-seen table. An operator should be able to scan the
list and instantly see which machines are online, which have a tech actively connected,
who's logged in, and which agents are running stale clients — without opening the detail
drawer. Success = the list conveys the same at-a-glance operational state as the
reference console.

**Reference (screenshot 2026-05-30, "Arizona Computer Guru" company):** `GURU-BEAST-ROG`
shows a green **Host** segment ("Computer Guru - SysAdmin") *and* a green **Guest**
segment ("Guest - 9h 21m"); most rows show only a green "Guest - Xh Ym" (agent online,
no tech connected); `ACG-TECH-01L` shows neither (offline). Rows carry "Company: …",
"Site: …", "Device Type: …", "Tag …", "User: … (Idle …)", and "Client Version: …" (in
red when out of date).

> Terminology: the requester's "dial" was a typo for **dual** — two indicators
> (Host + Guest), not a dial gauge.

## Scope

### Included in v1

- **Dual connection indicators per row:**
  - **Guest segment** (monitor icon): green when the endpoint agent is connected
    (`SessionInfo.is_online == true`); label "Guest - <duration online>"; grey when
    offline.
  - **Host segment** (person icon): green when a viewer/operator is actively connected
    (`SessionInfo.viewer_count > 0`); label = the viewer name(s)
    (`SessionInfo.viewers[].viewer_name`) + duration since join; grey when none.
  - Both states come from **live** session state, refreshed on the existing dashboard
    poll/refresh.
- **Rich inline row metadata** (from SPEC-003 inventory + existing columns): Company
  (`organization`), Site (`site`), Device Type (`device_type`), Tag(s) (`tags`),
  Logged-On User + Idle (`logged_on_user`, `idle_secs`), and **Client Version**
  (`agent_version`) rendered in a warning/red style when the agent build is **outdated**
  (below the latest stable `releases.version`, or below `min_version` → stronger
  "mandatory update" emphasis).
- **Server enrichment:** extend the machines list response so each machine carries its
  live Host/Guest state and the inventory fields in one payload (avoid N client-side
  joins). See Architecture.

### Explicitly out of scope

- The left-nav **"All Machines by Company" tree** with per-company counts (the
  screenshot's grouping sidebar) — captured as a follow-up sub-item in the roadmap;
  v1 may ship simple client-side grouping/sort by company but not the full tree nav.
- Editable inline fields (rename, set device type/tag from the row) — display only in
  v1; editing is a separate concern (and overlaps SPEC-003's operator-editable note).
- The per-row action menu beyond what exists (Join/Control/keys/remove already covered
  by other specs).
- Native viewer changes — dashboard only.

## Architecture

- **Data sources today are split:** `GET /api/machines` (`list_machines`,
  `main.rs:636`) returns `MachineInfo` from the **DB** (`connect_machines`), while live
  online/viewer state lives in the **in-memory `SessionManager`** and is exposed by
  `GET /api/sessions` (`SessionInfo`: `is_online`, `viewer_count`, `viewers`,
  `agent_name`, `started_at`). The list view needs both.
- **Relay-server (preferred):** enrich the machines list with live state server-side —
  join each `connect_machines` row (by `agent_id`/`machine_uid`) to its current
  `SessionManager` session, and add to `MachineInfo` (`api/mod.rs:117`): `is_online`,
  `viewer_count`, `viewers` (names), `online_since`, `host_since`, plus the SPEC-003
  inventory fields (`device_type`, `logged_on_user`, `idle_secs`, `agent_version`).
  Compute `client_outdated` / `client_update_mandatory` by comparing `agent_version` to
  the latest stable / `min_version` from `db::releases` (`releases.rs`). One request,
  fully-rendered rows.
  - Alternative (lighter, more chatter): dashboard fetches `/api/machines` +
    `/api/sessions` and joins client-side by agent_id. Acceptable for v1 if server
    enrichment is deferred, but the join + outdated-version logic then lives in TS.
- **Dashboard:** replace the plain `DataTable` columns in
  `dashboard/src/features/machines/MachinesPage.tsx` with a richer row: a
  `ConnectionIndicator` component (Host/Guest two-segment bar) + a metadata block.
  Reuse `StatusDot`/`machineTone` semantics. New `dashboard/src/api/types.ts` fields
  mirror the enriched `MachineInfo`.
- **Protobuf / DB:** none new — relies on SPEC-003's inventory columns and existing
  session state. (`online_since`/`host_since` may need a timestamp the SessionManager
  isn't tracking yet — see Open Questions.)

## Implementation details

- Files to touch: `server/src/api/mod.rs:117,130` (enrich `MachineInfo` + `From`);
  `server/src/main.rs:636` (`list_machines` — join live `SessionManager` state, compute
  outdated flag via `db::releases`); `server/src/session/mod.rs` (expose a
  by-agent_id/`machine_uid` lookup + `online_since`/`host_since` if added);
  `dashboard/src/features/machines/MachinesPage.tsx` (row layout),
  new `dashboard/src/features/machines/ConnectionIndicator.tsx`,
  `dashboard/src/api/types.ts` / `machines.ts` (new fields), `machines`/`status` CSS.
- Key logic: Guest green = `is_online`; Host green = `viewer_count > 0` (label from
  `viewers`); client-version tone = compare to latest stable release (red if below;
  stronger if below `min_version`).

## Security considerations

- No new endpoints beyond enriching an already admin-authenticated list
  (`AuthenticatedUser` guard on `list_machines`); no new unauthenticated surface.
- `logged_on_user`, viewer names, and inventory are already admin-only data — same
  trust level as the existing detail drawer; the list merely surfaces it earlier.
- Treat agent-reported strings (user, version, device type) as untrusted display data —
  length-cap/escape in the dashboard (no HTML injection via a rogue agent's reported
  fields).

## Testing strategy

- **Unit:** Host/Guest indicator state derives correctly (online+no viewer = Guest only;
  online+viewer = both; offline = neither). `client_outdated` flag true when
  `agent_version` < latest stable and when < `min_version`.
- **Integration:** a machine with a live viewer returns `viewer_count>0` + viewer name in
  the enriched list payload; an offline machine returns `is_online=false`; the list joins
  DB machines to live sessions without dropping rows that have no session.
- **Manual:** against the live console, confirm a row with an active Control session shows
  the green Host segment with the tech's name, agent-online rows show the green Guest
  segment + duration, and an out-of-date agent shows the client version in red.
  Cross-check a few rows against the reference screenshot's layout.

## Effort estimate & dependencies

- **Size: Medium.** Most effort is the dashboard row redesign + the
  `ConnectionIndicator` component and the server-side machines/sessions join; the data
  largely exists.
- **Depends on:** **SPEC-003** (inventory fields: device_type, logged_on_user,
  idle_secs, agent_version) for the rich metadata. Live Host/Guest state needs nothing
  new. Reads cleanest **after SPEC-004** (so the list isn't padded with duplicate ghost
  machines) and dovetails with **SPEC-002 Phase 2**'s dashboard work — coordinate so this
  is the machines-list increment of that surface, not a parallel rebuild.
- **Unblocks:** at-a-glance fleet operability; foundation for the company-tree nav
  follow-up.

## Open questions

1. **`online_since` / `host_since` timestamps.** The dual-indicator durations ("Guest -
   9h 21m", host join time) need an "online since" and "viewer joined at" the
   `SessionManager` may not track today (`started_at` is session creation, not last
   went-online). Add these timestamps, or approximate from `started_at`/`last_heartbeat`?
2. **Enrich server-side vs. join in the dashboard.** Preferred is one enriched
   `/api/machines` payload; confirm we don't want to keep the machines/sessions split and
   join in TS (simpler server, chattier client).
3. **"Outdated" definition.** Below latest *stable* release, below `min_version`
   (mandatory), or a configurable lag (e.g. > N versions behind)? Proposed: red if below
   latest stable, stronger emphasis if below `min_version`.
4. **Company grouping in v1.** Ship simple sort/group-by-company now, or defer all
   grouping to the company-tree follow-up?