UX Variations — monitoring-start

1. Name & Thesis

Operator Console. The agent fleet is a NOC. One dense, sortable, filterable data table — one row per agent, 5–12 rows — with a persistent split-pane: the table holds the left column, the selected agent’s tool-adaptive detail holds the right. The fleet never leaves view. You triage like an SRE reading a monitoring dashboard: scan the status column, sort errors to the top, act inline (approve / unblock / stop) without leaving the row, and keep one agent open in the detail pane while the other eleven keep streaming beside it.

One-line thesis: Maximum-density, keyboard-driven fleet command — every agent on one screen, every action one keystroke away, drill-in without ever losing the fleet.

The design bet: a solo conductor running 12 agents does not want twelve cards to scroll through; they want a spreadsheet of their fleet and a terminal stapled to its side. Density is the feature, not a regression to apologize for.

2. Parent User Flow & Branch Relationship

This variation is one of five sibling treatments of the monitoring-start branch (Happy Path steps 3–6 + Path C “Parallel Sprint”). All five serve the same two-layer surface and contrast only in how the orchestration layer (S3/S4) connects to the deep-work layer (folded S5/S6).

Relationship to siblings: V1 sits at the explicit desktop-dense extreme of the device-posture axis (the brief’s deliberate counterweight to v5’s mobile-first). It shares v4’s keyboard-native instinct but diverges on glanceability: v4 hides the fleet behind a palette and shows a quiet list; V1 puts the entire fleet on screen at all times as structured tabular data. It is the antithesis of v2’s roomy cards. Mobile is V1’s deliberate degrade case, not its design center — that territory belongs to v5.

This spec carries the brief’s confirmed reframe (two-layer surface; folded tool-adaptive detail; all-web PWA) and does NOT silently edit the approved flow-map. Where it departs from flow-map structure, that is recorded in §11.

3. Target User Fit

Best fit: the keyboard-driven power user at peak load — the conductor running 8–12 concurrent agents across 2–3 repos from a wide desktop monitor, who lives in tmux/htop/k9s/Grafana and reads tables faster than cards. They want information per pixel, not whitespace; they sort and filter reflexively; they expect j/k to move and Enter to open.

Poor fit: a first-time user meeting agents for the first time (the table reads as intimidating cockpit chrome before there is anything to monitor); a phone-primary “quick-check” user (the table must collapse to survive small screens); a 1–3 agent light user (the density buys nothing — a card grid would serve them better, which is why v2 exists).

Fit signal: if the evaluator, during UAT, instinctively sorts the status column and uses keyboard nav to triage a 10-agent fleet faster than they did in v2/v5, this variation is earning its density.

4. Onboarding / Activation Model (first meeting + empty state)

V1 owns only the monitoring-start surface; first-run provisioning (S2 Setup Wizard, Path A) is upstream and out of scope. The activation question here is: how does a first-time user meet a NOC table with zero rows?

Empty state (zero agents): the table chrome is suppressed, not shown empty. A spreadsheet of nothing is hostile. Instead the split-pane collapses to a single centered column:

• Headline: “Your console is empty. Launch your first agent.”
• One large primary action: + New Agent (opens the inline launch row, pre-focused).
• A secondary hint line: “Press ⌘K anytime to launch, jump, or filter.” — teaching the keyboard model on day one.
• A 3-step quick-start strip (Pick repo → Pick tool → Write prompt), each step a faint preview of the inline launch row fields.
• The right detail pane shows a static legend: what each status badge means (idle / running / waiting / error / starting / stopped), so the user learns the vocabulary before the first row exists.

First-agent transition (activation moment): when the first agent launches, the empty column animates into the two-region split-pane. The first row appears with starting status and the detail pane auto-selects it (the only sensible selection), immediately showing live stdout. This is the “the console is now live” beat — the table header (sort/filter controls) fades in only once ≥1 row exists, so the user is never shown empty machinery.

Density ramp: columns are progressive. At 1–3 agents the table shows the full column set comfortably. The user is not asked to configure columns on day one; column customization is a power affordance discovered later (§14), never a setup gate.

5. Typical Workflow Sequence (orchestrate → drill-in loop)

The core loop. Numbered, keyboard-first, with mouse equivalents in parentheses.

1. Open PWA → S3 console. Returning user lands on the populated table, default sort error > waiting > running > idle. The previously-selected agent is restored into the right pane (server-canonical; survives device switch).
2. Scan the status column. Errors and approval-waits are sorted to the top and color-coded. A header chip shows counts: 2 waiting · 1 error · 7 running. Triage is a single visual sweep of the leftmost columns.
3. Triage inline without drilling in. For a clear approval, press a on the focused row (or click the inline Approve affordance) — the row’s diff micro-preview expands one tier in place; confirm. For a blocked agent, u to unblock. For a runaway, x to stop (guarded, §15). The fleet stays put; no navigation.
4. Drill in when a row needs attention. j/k (or arrow keys / click) to move the row cursor; Enter (or click the row) selects it into the right detail pane. The other 11 rows stay visible and keep streaming. This is the signature move: drill-in is selection, not navigation.
5. Work the agent in the folded detail pane. The pane renders tool-adaptively (terminal-primary for CLI tools, structured for API-native — §13). Type into the terminal, read the structured step stream, inject a prompt, approve inline. The fleet table on the left keeps updating in your peripheral vision.
6. Fan out a parallel sprint (Path C). To launch agent #2/#3 mid-flow: n (or click the inline + New Agent row pinned to the top of the table) — the top row becomes editable inputs (repo · tool · prompt). Fill and ⌘Enter to launch. New starting row drops into the table. Alternatively ⌘K → “New agent…” for a full quick-launch palette without leaving the keyboard.
7. Round-robin approvals. As more agents hit decision points they sort to the top and the header count increments. Walk them: focus top waiting row → a → confirm → focus next. Or ⌘K → “Approve all clear” for the batch path (§15).
8. Return to monitoring. Esc deselects the detail pane (collapses it wider on demand, §13) and returns focus to the table. Loop back to step 2.

The loop never leaves the single console route. Steps 2–3 are pure orchestration; steps 4–5 are deep-work; the split-pane is what fuses them.

6. Progression Model — and how it differs from the 4 siblings

How the user advances through the flow in V1: progression is lateral, not navigational. The user does not move between screens to advance; they move the selection cursor down the table and the detail pane updates underneath them. Advancement = re-sorting (state changes float rows up), selecting (binds a row to the pane), and acting inline (mutates state, which re-sorts). The flow’s S3→S5/S6 transition is collapsed into a pane-bind on one persistent route. There is no back-stack to manage because you never left the board.

Explicit contrast with each sibling:

• vs v2 Card Mosaic (route-switch): v2 advances by navigating away — click a card → full-page detail route → browser back to return. Each drill-in drops board context (you can’t watch the fleet while reading one agent). V1 keeps the fleet permanently co-visible; progression costs zero context. The price V1 pays is per-row richness — v2’s cards show more stdout per agent than V1’s one-line cell.
• vs v3 Kanban Pipeline (drawer + spatial status): v3 advances by watching cards physically move between status columns (Queued→Running→Waiting→Error→Done); progression is spatial and animated, drill-in is a drawer over the board. V1 represents the identical status transitions as sort-order changes within one table (a row floats up when it errors) — quieter, denser, no card-in-flight motion. V3’s bottlenecks are visible as tall columns; V1’s are visible as clusters at the top of the sort. V1 deliberately avoids v3’s motion-instability by keeping every agent in one stable list and only reordering, never relocating between regions.
• vs v4 Command-First (palette + focus mode): v4 hides the fleet — quiet minimal list, the verb is the ⌘K palette, detail is a focus mode with the board as a back-stack. V1 and v4 share the keyboard-native soul and both offer ⌘K, but V1 never hides the fleet — full tabular glanceability is always on screen, and ⌘K is an accelerator over an already-visible board, not the primary way to perceive state. v4 trades glanceability for calm; V1 refuses that trade.
• vs v5 Glanceable Stream (mobile-first feed): v5 advances by scrolling a prioritized vertical feed designed phone-up, launches from saved recipes, detail is a full-screen sheet. V1 is its polar opposite on the device-posture axis: desktop-dense, multi-column, designed for a wide monitor; its mobile form is an explicit degrade (§17), whereas mobile is v5’s design center. v5 optimizes for the “closed laptop, checked from phone” moment; V1 optimizes for the “ten agents, one big monitor, mid-sprint” moment.

Net: V1’s progression model is “sort + select + act-in-place on one persistent dense surface.” No other sibling keeps both the full fleet and a working agent on screen simultaneously — that simultaneity is V1’s defining progression property.

7. Sharing & Collaboration Model

N/A — single-user personal workstation. This is a solo dogfood environment; there is exactly one user (the Agent Conductor) and no second human to share with, hand off to, or collaborate alongside. There are no shared boards, comments, mentions, presence indicators, or co-editing. The only “handoff” is the same user across their own devices (cross-device continuity), which is server-canonical state, not collaboration — covered under §9 return-use. No sharing affordances are designed and none should be invented.

8. Permissions Model

N/A — single-user personal workstation. There are no roles, no per-row access control, no viewer/editor tiers, no team admin. The single user has full control of every agent in the table. The only authorization in the system is GitHub OAuth, which scopes what the agents may do to the user’s repos (pull/push/PR) — an upstream identity/repo-access concern owned by S1, not a board-level permissions model. The console exposes no permission UI and none should be invented. (The OAuth-expiry failure path — agents losing repo access mid-run — is a recovery concern, handled in §10, not a permissions model.)

9. Return-Use & Notification Model

Resume: on return, the console restores server-canonical state: same rows, same statuses, same sort, and the last-selected agent re-bound into the detail pane (its stdout buffer replayed on WebSocket attach). No reconnection ceremony — this is the flow-map’s core promise. If the user returns after a gap exceeding the recap threshold (flow-map D7), a dismissible recap strip docks above the table header — not a full-screen S8 takeover, because in the Operator Console the fleet itself is the recap. The strip summarizes “while you were away: 3 completed · 2 PRs · 1 error” with each item as a chip that, when clicked, selects the relevant row into the detail pane. Esc or “Got it” dismisses the strip and drops you onto the live table.

Approval surfacing within the board: approvals are first-class table citizens. A waiting agent sorts to the top with a waiting badge, its Approve / Reject affordances rendered inline in the row’s action cell, and a one-tier diff micro-preview expandable in place. The header carries a live approval-queue chip (2 waiting) that, when clicked or via ⌘K → “next approval”, jumps the cursor to the top waiting row. No approval ever requires leaving the console.

Error surfacing within the board: errors sort above everything, render a red error badge, and put the failure’s first line into the one-line stdout cell. The header error chip mirrors the count. Selecting the row binds the detail pane to the full error / stack trace with Retry / Restart / Open terminal actions (mapping flow-map S5 Error state).

Push notifications (PWA): web-push for approval-needed and error/completion events deep-links into the console with the relevant row pre-selected (not to a standalone approval screen — V1’s whole premise is that the board is the approval surface). On a desktop where the console is already open, the notification is redundant with the live header chips; on mobile it routes into the collapsed-list degrade view (§17) with the row expanded. Notification preferences themselves live in S10 Settings (out of scope here).

10. Failure Recovery Behavior (mapped to flow-map failure paths)

How the Operator Console surfaces and recovers each flow-map failure. The design principle: failures are table-and-pane states, surfaced where the user is already looking (header chips + row badges + detail pane), never as modal interrupts that hide the fleet.

Cross-cutting failure principle for V1: because the fleet is never hidden behind a route or modal, all of these failures remain visible in aggregate (header chips) and per-agent (row badges) at the same time. The split-pane means the user can be deep in one agent’s terminal and still see a second agent error appear at the top of the table — a property no route-switching sibling (v2) preserves.

11. Page & Flow Changes vs. the Flow-Map Baseline

The flow-map lists S3, S4, S5, S6 as four distinct screens/routes and frames Mode A (structured) vs Mode B (terminal) as a user-selectable access mode (flow-map D2). V1 carries the brief’s confirmed reframe and restructures as follows:

1. S3 + S5 + S6 collapse onto ONE persistent route. There is no navigation from board to detail; the detail pane is a region of the console, bound by selection. The flow-map’s S3→S5/S6 “Downstream” handoff becomes an in-page pane-bind.
2. S5/S6 fold into one tool-adaptive detail pane. The flow-map’s separate “S5 Structured” and “S6 Terminal” screens — and its Mode A/B user toggle (D2) — are dropped. The detail pane’s primary rendering is determined by the tool’s integration pattern, not a user choice: terminal-primary (xterm.js/WS) for headless-CLI tools, structured for API-native tools. There is no “switch to terminal” mode button as a primary affordance (an escape-hatch terminal toggle survives only for structured/API tools that also expose a shell, as a secondary control — §14).
3. S4 changes from modal to inline. The flow-map’s centered modal-with-backdrop launch (S4) is replaced by an inline editable top-of-table row plus a ⌘K quick-launch palette. Launch happens in the table’s coordinate space, not over a dimmed board — preserving the never-lose-the-fleet principle even during launch.
4. S8 Async Recap demotes from screen to strip. The full-screen recap becomes a dismissible docked strip above the table (§9), because the live table already is the recap surface in this layout.
5. S7 Approval has no standalone screen. Approvals render inline in rows + in the detail pane; the flow-map’s dedicated S7 mobile-card is realized only in the mobile degrade view (§17), not on desktop.
6. Default sort retained but extended. Flow-map’s error > waiting > running > idle is kept as the default, extended with starting/paused/stopped/done tiers and made user-resortable by any column (the flow-map sort was fixed; V1 makes it a table affordance).

These are variation-level proposals consistent with the brief’s amendment note; they do not edit the approved flow-map doc.

12. Navigation Model

Single-route, selection-driven, keyboard-first. The console is effectively a one-page app for the monitoring-start surface.

• Primary nav = the row cursor. j/k or ↑/↓ move a highlighted cursor through table rows; Enter / click binds the cursor’s row to the detail pane. Esc releases selection back to the table.
• ⌘K command palette — the universal accelerator: New agent…, Jump to agent <name>, Filter by repo/tool/status, Sort by <column>, Next approval, Approve all clear, Stop agent <name>, Open settings. Fuzzy-matched. This is the fast path, layered over an always-visible board — never the only way to perceive or reach state (the v4 contrast).
• Header controls — approval-queue chip, error chip, status-count chips, filter/sort menu, repo filter, settings gear, “Open on Mobile / QR” button (for the cross-device handoff path), connection/tunnel status indicators.
• Within the detail pane — its own local nav: terminal focus (i / click to type) vs chrome focus; Tab cycles structured sub-sections (steps / file changes / approval); a small breadcrumb shows which agent is bound.
• No browser-back dependency. Because there is no route change on drill-in, back/forward are not part of the core loop (deep-links to a specific agent still set the initial selection for QR/push handoff).
• Focus discipline: a clear single keyboard-focus ring is always visible (table-row focus vs pane focus vs palette focus are visually distinct), because a keyboard-driven dense UI lives or dies on the user always knowing where their keystrokes land.

13. Screen-by-Screen Layout (regions & proportions)

All within one persistent route. Reference frame: desktop ≥1280px wide.

S3 — Console (the table) + persistent split-pane

┌──────────────────────────────────────────────────────────────────────────────┐
│ HEADER  gblock·console   [7 running ·2 waiting ·1 error]  [⌘K] [⟳tunnel] ⚙ │  ~52px
├──────────────────────────────────────────────────────────────────────────────┤
│ [filter: repo▾ tool▾ status▾]   sort: status▾            recap-strip(opt.) │  ~40px
├──────────────────────────────────────────┼────────────────────────────┤
│  + New Agent  (inline launch row)          │                              │
│ status·name·tool·repo·el·tok·act table       │   DETAIL PANE                │
│  ●E auth… aider api 12m 41k ⟳⏹          │   (folded, tool-adaptive)    │
│  ●W pay…  cc    web  4m 88k ✓✗         │   agent header / status      │
│  ●R index codex web  9m 120k ⏹  ◀───── binds selected row           │
│  ●R migr… sdk   api  2m 30k ⏹            │   PRIMARY RENDER:            │
│  ●I docs  cont… web 1h  9k ▶            │   terminal (xterm.js)        │
│  LEFT PANE ~55–62% width                     │   OR structured stream       │
│  table scrolls independently                 │   RIGHT ~38–45% width        │
│                                             │   footer: inject ▸ / stop    │
└──────────────────────────────────────────┼────────────────────────────┘

• Header (full width, ~52px): brand, live status-count chips (clickable filters), approval chip, ⌘K affordance, connection + tunnel indicators, settings gear, QR/Open-on-Mobile.
• Toolbar (~40px): filter dropdowns (repo / tool / status), sort selector, optional recap strip.
• Left pane — the table (~55–62% width):
  • Inline launch row pinned at the top (“+ New Agent”), becomes editable on activation (§14).
  • Columns (default): status badge · agent name · tool · repo · elapsed · token usage · one-line live stdout (flex, truncating, the widest data column) · action cell (inline approve/unblock/stop/retry icons). Token + stdout columns are the first to drop at narrower widths (§17).
  • Row height ~36–40px (dense; see §16). Status-tinted left edge bar per row.
  • Scrolls independently of the detail pane.
• Right pane — folded tool-adaptive detail (~38–45% width):
  • Top chrome: agent name, tool, repo, status badge, elapsed, token usage, and a secondary “Open full terminal” / “Pop out” control.
  • Primary render region (tool-adaptive — the fold):
    • Headless-CLI tools (Claude Code CLI, Codex, Aider, Continue, Cline, Copilot CLI, Augment): terminal-primary — a live xterm.js terminal over WebSocket fills the region; structured chrome (status, approval banner, file-change rail) wraps it. The terminal IS the native interface.
    • API-native tools (Claude Agent SDK): structured — parsed step stream, progress, file-change list, inline approval card. No terminal (none exists server-side).
    • The render choice is automatic from the agent’s tool, never a user mode toggle.
  • Footer: prompt-injection input ▸, stop / restart, and (for waiting agents) inline Approve / Reject.
• Split behavior: the divider is draggable (user can rebalance 50/50 ↔ 70/30); double-click snaps to preset. Esc with nothing selected collapses the detail pane and lets the table reclaim full width (max-density monitoring mode).

S4 — Start Agent (folded into the table, two ways in)

• Inline launch row (primary): the pinned top row’s cells transform into inputs — repo picker (auto-populated from GitHub OAuth), tool selector, prompt (expanding inline textarea), optional branch. ⌘Enter launches; Esc cancels. Validation: launch disabled until repo+tool+prompt set. On launch, the row converts to a real starting agent row in place. No backdrop, no modal — the fleet stays fully visible (the deliberate departure from the flow-map’s S4 modal).
• ⌘K quick-launch (accelerator): ⌘K → “New agent” opens a palette-style launcher with the same fields, fully keyboard-drivable, for users who never want to leave the keyboard. Same validation and outcome.
• S4 states honored (flow-map): Loading-repos (skeleton in repo picker, other fields disabled), Launching (spinner, fields disabled), Error (inline error + retry), Tool-unavailable (inline warning + “Install tool” → S10).

Folded S5/S6 Detail

Already described as the right pane above. Key point: there is no separate S5 vs S6 screen and no Mode A/B user toggle — one detail pane, rendering chosen by tool integration pattern. A secondary “Open full terminal” escape hatch exists for structured/API tools that happen to expose a shell, and a “Pop out” control can promote the pane to a focused full-width terminal for heavy interactive debugging (still the same route, the table temporarily yields width).

14. Key Components & Controls

• Fleet Table — virtualized (handles 5–12 comfortably, scales past it), sticky header, per-column sort, multi-facet filter, status-tier default sort, draggable + hideable columns (power affordance), keyboard row-cursor. Each cell type:
  • Status badge — colored dot + short label (E/W/R/I/starting/paused/done) + status-tinted row edge.
  • One-line stdout cell — live-tailing last stdout line, monospace, truncated with ellipsis; hover/focus shows a 3-line tooltip peek (mitigates the truncation risk, §20). The full stream lives in the detail pane.
  • Action cell — context-sensitive inline icons: Approve (✓) / Reject (✗) for waiting; Unblock (▸); Stop (⏹) for running; Retry (⟳) for error; Resume (▶) for paused/idle.
• Inline Launch Row — top-pinned editable row (repo / tool / prompt / branch); the in-table S4.
• ⌘K Command Palette — fuzzy launcher/jumper/filter/sorter/actioner (§12).
• Detail Pane — tool-adaptive container:
  • xterm.js terminal (CLI tools) over WebSocket, with copy/paste, search, and a clear keystroke-focus indicator.
  • Structured stream (API tools) — step list, progress bar, file-change rail, inline approval card.
  • Pane chrome — agent identity header, status, metrics, Pop-out, secondary Open-terminal (escape hatch), prompt-inject footer, stop/restart.
• Header chips — clickable status-count filters, approval-queue jump, error jump, tunnel/connection indicators.
• Recap strip — dismissible docked summary on threshold return (§9).
• Diff micro-preview — one-tier inline expansion in a waiting row for fast approve-without-drill-in.

15. Button & Link Behavior

• + New Agent (inline row / ⌘K): activates the launch row / palette. Disabled-to-active validation: enables Start only when repo + tool + prompt are set. ⌘Enter = Start, Esc = cancel.
• Approve (✓): inline on waiting rows and in the detail pane footer. Single-tier diff micro-preview expands on first press for confirmation; second press (or a then Enter) commits. Sends approval over the control socket; row resumes to running sub-second; auto-advances cursor to next waiting row.
• Reject (✗): opens an inline rejection-reason input in the row’s expanded tier; submit sends feedback to the agent.
• Unblock / Resume (▸ / ▶): resumes a paused/idle agent; for paused — credential/auth rows it routes to the credential fix first.
• Stop (⏹): guarded — single click arms (icon turns red, “click again to stop”), second click within 3s confirms; x key follows the same arm-confirm pattern. Prevents fat-finger fleet damage in a dense table.
• Retry / Restart (⟳): re-runs a crashed/errored agent with the same prompt; Restart from the detail pane allows an adjusted prompt.
• Status-count chips (header): click = filter the table to that status; click again = clear. error/waiting chips also support “jump to first” via ⌘K equivalents.
• Pop-out / Open full terminal: promotes the detail pane to full-width focused terminal (same route, table yields); Esc restores the split.
• Row click vs row action-cell click: clicking anywhere in a row except the action cell selects it into the pane; clicking an action icon performs the action without changing selection — so triage clicks never disturb a deep-work selection.
• QR / Open on Mobile (header): generates the short-lived pre-authenticated deep link encoding the current selection, for cross-device handoff.
• Re-authorize GitHub / Update credential (failure banners): route to OAuth / S10; on success, affected rows auto-resume.

All destructive or fleet-affecting actions are guarded or reversible; all resume actions are non-destructive and preserve session state.

16. Spatial Density, Sizing, Hierarchy

V1 is the explicit high-density end of the posture axis — density is the thesis, tuned, not careless.

• Row height ~36–40px, ~13–14px base text, monospace for stdout/tool/repo/token cells (NOC legibility), proportional for names. 12 rows fit in a single desktop viewport without scroll.
• Column hierarchy (visual weight, high→low): status badge (color, leftmost, the eye’s anchor) → agent name (bold) → one-line stdout (the live signal, widest flex) → repo/tool (muted, monospace) → elapsed/token (smallest, right-aligned numerics) → action cell (icon-only, reveal-on-row-focus to reduce resting clutter, always-visible for error/waiting).
• Color as primary status channel (against the dark house palette --bg:#1a1a2e --card:#16213e --border:#2a2a4a --accent:#4dabf7 --text:#e0e0e0 --muted:#8b8fa3): error = red, waiting = amber, running = green/accent, idle = muted grey, paused = amber-muted, done = blue-muted. Status-tinted left row-edge gives a scannable color rail down the table.
• Split proportion defaults ~58/42 (table/detail), draggable, with a max-density mode (table full width, pane collapsed via Esc).
• Whitespace is intentionally scarce in the table and intentionally generous in the detail pane — the contrast (dense fleet ↔ focused single agent) reinforces the two-layer mental model spatially.
• Hierarchy rule: the user’s eye should land on red/amber rows at the top first, then the selected row’s highlight, then the detail pane. Sort + color do the triage work before any reading happens.

17. Responsive Behavior at 3 Breakpoints

Mobile is V1’s deliberate degrade case (the design center is desktop-dense; v5 owns mobile-first).

• Desktop > 1024px (design center): full split-pane, full column set (status · name · tool · repo · elapsed · token · stdout · actions), draggable divider. At ≥1440px the stdout column widens and an optional second metrics column (cost / message count) can be enabled. This is where V1 is meant to be lived in.
• Tablet ≤ 1024px: split-pane persists but detail pane goes overlay-on-demand rather than always-side-by-side, OR the split shifts to ~65/35 with a narrower detail pane. Columns shed in priority order: token usage drops first, then elapsed compresses to relative (“9m”), stdout truncates harder. Inline launch row stays. ⌘K remains. Still fundamentally a table.
• Mobile ≤ 640px (degrade): the table collapses to a compact stacked list — one card-ish list item per agent showing status badge + name + one-line stdout + a single primary inline action (the brief’s prescribed collapse). Columns become a two-line stacked cell. The split-pane breaks: selecting an agent pushes a full-screen detail sheet (the only place V1 uses route-like navigation, because side-by-side is impossible on a phone). On mobile, the folded detail’s terminal is read-mostly with an “Open on desktop / scan QR” handoff for heavy interactive terminal work (honoring the terminal-latency open question — a phone is a poor place to type into a low-latency-critical terminal). Approvals on mobile render as the flow-map’s large-tap-target S7-style cards. This degrade is honest: V1 on a phone is a monitoring + approve tool, not a deep-work tool — and that’s fine, because that posture is exactly what v5 is purpose-built for, and the QR handoff bridges to a desktop where V1 shines.

18. Visual Tone

NOC / server-monitoring console. Dark, dense, instrument-panel calm-under-load. Monospace data, color-coded status as the dominant signal, tight gridlines, minimal chrome, no decorative illustration once the fleet is live (illustration appears only in the empty state). The aesthetic reference set: htop / k9s / btop / Grafana / a trading terminal — tools that pack maximum signal into a glance and reward a trained eye. Motion is restrained: rows re-sort with a quick settle, they don’t fly between regions (the deliberate anti-v3 choice); status badges may pulse subtly when waiting. The dark house palette is the baseline; status colors are the accent vocabulary. Confidence over friendliness — this screen should feel like a cockpit you’ve mastered, not a dashboard you’re being onboarded to.

19. Strengths

• Maximum fleet glanceability — all 5–12 agents and their full status vocabulary visible on one screen with zero scrolling or navigation; the densest possible read of the fleet.
• Drill-in never loses the fleet — the persistent split-pane is the only sibling layout where you work one agent and watch the other eleven simultaneously. A second agent erroring while you’re deep in a terminal is still visible.
• Fastest triage and parallel-sprint launch — sort + color + inline actions + ⌘K make round-robin approvals and fanning out agents #2/#3 (Path C) extremely fast for a trained user; no modal, no route, no context loss.
• Keyboard-native end to end — j/k/Enter/a/u/x/n/⌘K make the whole loop mouse-optional, matching the power-user persona’s reflexes.
• Comparison across agents is trivial — tabular columns make “which agent is burning the most tokens / running longest / stuck” a single sort, which cards (v2) and feeds (v5) can’t do.
• Failures stay aggregate + per-agent simultaneously — header chips and row badges keep the whole fleet’s health legible even mid-deep-work.

20. Risks & Failure Modes (of the design)

• Truncated rich stdout — a one-line cell cannot convey a multi-line tool transcript; nuance is lost at the table tier. Mitigations: hover/focus 3-line peek tooltip; the full stream is always one selection away in the detail pane; stdout is the widest column. Still the sharpest tradeoff vs v2’s roomy card previews. (Also gated by the brief’s stdout-parsing-reliability open question — if parsing is unreliable, even the one-liner is noisy; V1 leans on the raw last-line as a fallback rather than promising parsed status.)
• Intimidating / steep — a NOC table reads as cockpit chrome to a newcomer and can feel hostile at 1–3 agents. Mitigations: suppressed-chrome empty state, progressive disclosure of sort/filter machinery, ⌘K hinting. But it will never be the welcoming option — that’s v2’s job, and that division of labor is intentional.
• Weak on mobile — the table genuinely doesn’t belong on a phone; the collapse is a degrade, deep-work terminal is read-mostly. Mitigation: honest QR/desktop handoff; lean on v5 for the phone-up moment. This is an accepted, scoped weakness, not a bug.
• Terminal latency in a side pane — the folded detail’s xterm.js still depends on sub-100ms echo over the tunnel (open question #1); a narrow side pane makes a laggy terminal feel even more cramped. Mitigation: Pop-out to full width for heavy interactive sessions; structured-first for API tools sidesteps it.
• Density fatigue / misclick risk — packed rows + inline destructive actions invite fat-fingers. Mitigation: guarded Stop (arm-confirm), action-cell clicks don’t change selection, reveal-on-focus action icons reduce resting clutter.
• Color-only status is an accessibility risk — color-coding is the dominant channel. Mitigation: every badge pairs color with a text/letter label and the status word; never color alone.
• Re-sort jumpiness — rows reordering as status changes can move a row out from under the cursor mid-action. Mitigation: the selected row stays bound to the pane regardless of its sort position; sort settles are debounced.

21. Implementation Complexity

Medium (matches the brief’s rating). Heavier than v2 (the card-grid control), lighter than v3 (kanban drag/animation/column state machine).

What drives the cost:

• Virtualized, sortable, multi-filter, keyboard-navigable data table with live per-row WebSocket updates and a stable selection that survives re-sort — the central non-trivial component. Off-the-shelf table libs help but the live-update + keyboard-cursor + stable-selection combination needs care.
• Persistent split-pane with draggable/collapsible divider and independent scroll regions — moderate.
• Tool-adaptive folded detail — must host both an xterm.js/WebSocket terminal (CLI tools) and a structured stream renderer (API tools), switching on tool type. The terminal + WS transport is the same cost every sibling pays; V1 adds the constraint of making it work well in a narrow pane (pop-out logic).
• ⌘K command palette with fuzzy match over launch/jump/filter/sort/action verbs — moderate, well-trodden.
• Inline launch row as an in-table editable state machine (idle → editing → validating → launching → real-row) — fiddlier than a plain modal but contained.
• Three-breakpoint responsive including the full table→stacked-list→full-screen-sheet mobile degrade — non-trivial but the mobile path is intentionally a simpler subset.

No multi-user, sharing, or permissions code (N/A) — that subtracts real complexity other product types would carry.

22. Prototype Scope (lightweight, evaluable build)

A lightweight prototype must include enough to let a solo evaluator run the §5 loop and feel the density tradeoff. Minimum:

1. Populated fleet table with ~8–10 mock agents spanning every status (error / waiting / running / idle / paused / done / starting), default error > waiting > running > idle sort, at least sort-by-status and sort-by-elapsed working, and a status/repo filter.
2. Live-ish one-line stdout per row (mock tail loop is fine) + status badges with color + text labels + status-tinted row edges.
3. Keyboard nav — j/k/Enter row cursor + selection, Esc deselect, ⌘K palette (at least New-agent + Jump-to + Filter verbs).
4. Persistent split-pane with a working selection bind: selecting a row renders the detail pane while the table stays visible and keeps updating. This simultaneity is the single most important thing to demonstrate — it’s V1’s whole thesis.
5. Tool-adaptive detail — at least two mock agents: one CLI-type rendering a (mock or real) xterm.js terminal, one API-type rendering a structured step stream. Prove the auto-render-by-tool with no user toggle.
6. Inline launch row producing a new starting row (mock launch) + ⌘K quick-launch equivalent.
7. Inline actions — Approve/Reject on a waiting row (with one-tier diff peek), guarded Stop, Retry on an error row; action-cell clicks must not disturb the current pane selection.
8. At least two failure surfaces rendered as table/pane states: backend-unreachable banner + table dim, and an agent-crash row with retry budget — to prove failures stay visible without hiding the fleet.
9. Responsive proof — resize to ≤640px and show the table collapse to the stacked list + full-screen detail sheet (the honest degrade).

Mock WebSocket/stdout and mock approvals are acceptable; the evaluation target is the interaction model and density feel, not backend fidelity.

23. Readiness Signal — what makes this branch ready for /ui-interview

This branch is ready to advance to /ui-interview [v1-operator-console] when, during /uat --variant-evaluation against its siblings, the solo evaluator gives a clear signal such as:

• Task-based: triaging a 10-agent fleet (sort errors up, approve the clear ones, drill into one crash, launch a parallel agent) is measurably faster and lower-friction in V1 than in v2/v5, and the evaluator explicitly values keeping the whole fleet visible while working a single agent (the split-pane simultaneity) — i.e. they used it and missed it elsewhere.
• Gut-check: the evaluator says some version of “this is how I want to run my fleet from my desktop — the density is a feature, not a wall,” and is willing to accept the mobile-as-degrade tradeoff (reaching for the QR/desktop handoff rather than wanting V1 itself to be phone-good).
• Negative-confirm: the intimidation/density-fatigue risk (§20) did not dominate the evaluator’s reaction for the target power-user posture; the empty-state ramp and ⌘K hinting were enough.

If instead the evaluator wants V1’s split-pane fleet-visibility but v2’s card richness, or v5’s mobile posture, that is a consolidation signal (feed /consolidate-variations), not a ready-for-interview signal for V1 standalone. Readiness for /ui-interview specifically means: the Operator Console’s dense-desktop, split-pane, inline-action model is the chosen direction for the monitoring-start surface and is ready to be pinned down visually.

1. Name & Thesis

Card Mosaic. A familiar SaaS dashboard: the fleet is a responsive grid of rich agent cards, each a self-contained status tile with a live stdout preview. You scan the mosaic, launch from a modal, and drill into a single agent by navigating to a full-page detail route. The thesis is zero learning curve — anyone who has used Vercel, Railway, GitHub Actions, or a CI dashboard already knows how to read this board. It deliberately trades cleverness for legibility so it can serve as the control the other four concepts must beat.

Design center of gravity: glanceability per agent. Each card carries enough rich context (badge, tool, repo, elapsed, tokens, multi-line stdout) that the board answers “what is each agent doing right now?” without a drill-in. The cost — accepted on purpose — is fleet density: cards are large, so 12 agents scroll.

2. Parent User Flow & Branch Relationship

This variation realizes the monitoring-start branch: Happy Path steps 3–6 (S3 Board → S4 Start → S3 new card → S5/S6 Interact) plus Path C “Parallel Sprint” (launch agent #2, #3; monitor all; round-robin approvals).

It is the baseline/control. Where the brief’s four axes are spread across siblings, V2 takes the flow-map-native position on every axis:

Because it tracks the flow-map most literally, V2 introduces the fewest net-new interaction concepts. The one deliberate divergence from the approved doc is the folded tool-adaptive detail (see §11) — a constraint carried by every variation per the brief’s confirmed reframe, not unique to V2.

3. Target User Fit

The balanced default Agent Conductor. Specifically:

• A solo dev running 5–12 agents across 1–3 repos who works across devices (desk + couch + phone) and wants one mental model that survives the switch.
• Someone who values recognition over recall — would rather see a labeled card than memorize a command palette or a column convention.
• A user whose first reaction to a new tool is “show me the dashboard,” not “show me the shortcuts.”

Best-fit summary: the persona before they have strong opinions. V2 is what you reach for when you don’t yet know whether you’re a power-keyboard user (→ V1/V4), a triage-first thinker (→ V3), or a phone-up checker (→ V5). It degrades gracefully to 1-column mobile, so it is never wrong on any device, just never maximally optimized for one.

Weak fit: a max-density NOC operator babysitting 12 agents on a single 27" screen (cards waste vertical space — that’s V1’s job).

4. Onboarding / Activation Model

Entry into this surface is post-setup: Path A (onboarding) provisions the workspace and redirects to S3 with an empty board. V2 owns the empty → first-agent moment on the board.

Empty state (S3 Empty):

• Centered illustration/glyph + headline “Start your first agent.”
• A single prominent Start Agent button (primary accent) — this is the only real CTA; nothing else competes.
• Below it, a one-line “quick-start” link → a 3-step explainer (pick repo → pick tool → describe the task) that can open the S4 modal pre-focused on the repo picker.
• Secondary, muted: “Open settings” (for users who arrived without a tool installed).
• Approval-queue badge and diff/review affordances are hidden in the empty state (per S3 matrix: “Approval/diff actions hidden”).

Activation = the first card appears. When the user completes the S4 modal, a card animates into the grid with a “starting” badge and flips to “running” within seconds, its stdout preview beginning to stream. That first live preview is the aha for this surface — the user sees the agent working without any SSH/tmux ceremony. The empty illustration is replaced by a real 1-card mosaic, which implicitly teaches the grid model.

Progressive disclosure: the modal’s “optional branch” field stays collapsed under a “More options” toggle on first run, so the first launch is the minimal repo + tool + prompt.

5. Typical Workflow Sequence

Parallel Sprint (Path C), the representative flow:

1. Open PWA → lands on S3 Agent Board (returning session). Mosaic renders all current agents, sorted error > waiting > running > idle. Header shows approval-queue badge.
2. Scan the mosaic. Each card’s badge + stdout preview answers “what’s happening” at a glance; no drill-in required for routine monitoring.
3. Click Start Agent (header button) → S4 modal opens over the dimmed board.
4. In the modal: pick repo (dropdown), pick tool (dropdown), type the prompt (textarea), optionally expand branch. Click Start Agent.
5. Modal closes; a new “starting” card appears in the grid, transitions to “running,” stdout begins streaming. (Happy Path step 5.)
6. Repeat 3–5 for agent #2 and #3 (different repos/branches). Board now shows 3+ live cards.
7. An agent hits a decision point → its card flips to a waiting badge, pulsates subtly, and re-sorts toward the top; the header approval-queue count increments.
8. Click the waiting card → navigate to the full-page detail route for that agent. The detail is folded + tool-adaptive: terminal-primary for CLI tools (xterm.js), or structured-primary for API-native tools. Handle the inline approval here.
9. Click Back to Board → return to S3 (board re-reads server-canonical state; the card is now “running” again).
10. Round-robin steps 7–9 across agents as approvals arrive.
11. When agents finish, cards show a completion summary; a Review diffs CTA surfaces (handoff to S9, out of this branch’s deep scope but linked).

6. Progression Model — and How It Differs From the 4 Siblings

How the user advances in V2: by navigation and recognition. The orchestration layer (mosaic) and the deep-work layer (detail) are two distinct places. You progress by clicking a card to travel to its detail route, and you back out to return to the board. State is server-canonical, so the round trip is lossless — but it is a round trip: the board is replaced by the detail page, not held alongside it. New work enters via the modal, which is a temporary overlay on top of wherever you are.

This is the closest-to-baseline progression: a classic two-place dashboard → detail pattern with a modal for creation. Explicit contrast:

• vs V1 Operator Console — V1 keeps the fleet and the detail on screen at once via a persistent left-board / right-detail split-pane; you progress by selecting rows without leaving the fleet. V2 instead leaves the board to enter detail (full-page route). V1 trades V2’s per-agent richness for fleet-wide density (one dense row per agent). V2 is more legible per agent; V1 never loses fleet context.
• vs V3 Kanban Pipeline — V3 makes status the spatial primary: cards physically move between lifecycle columns and detail is a drawer that slides over a board that stays behind. You progress by watching cards flow and pulling triage items out of the Waiting/Error columns. V2’s cards don’t move by status (they re-sort within one grid) and detail replaces the board rather than overlaying it. V2 is calmer (no card motion); V3 surfaces bottlenecks spatially.
• vs V4 Command-First — V4 makes the verb primary: you progress by typing into a palette (⌘K) to launch/filter/jump/approve, and detail is a focus mode with the board as a back-stack. V2 progresses by clicking visible affordances (button, card), not typing. V2 is higher-discoverability and slower for an expert; V4 is faster for a keyboard native and quieter on glance.
• vs V5 Glanceable Stream — V5 is phone-up: a prioritized vertical feed with swipe actions and template-based quick-start, detail as a full-screen sheet. V2 progresses the same on phone and desktop (responsive grid both ways) rather than optimizing the phone reading order. V5 wins the couch/phone aha; V2 wins device-neutrality.

One-line positioning: every sibling deviates from the dashboard mental model on exactly one axis to test a hypothesis; V2 holds all four axes at the flow-map default so those deviations have something to be measured against.

7. Sharing & Collaboration Model

N/A — single-user personal workstation. Per the flow-map’s explicit non-goals (“Multi-tenant / team features (personal-workstation scope only)”) and the brief’s locked constraint, this product has exactly one user — the Agent Conductor who owns the managed VM and their own GitHub OAuth + model subscriptions. There are no shared boards, no invited collaborators, no co-viewing, no comments, and no handoff-to-another-person flow. The only “handoff” in scope is the same user moving between their own devices (cross-device continuity), which is server-canonical state, not collaboration. No sharing UI is designed.

8. Permissions Model

N/A — single-user personal workstation. There are no roles, no per-resource ACLs, no seat management, and no permission tiers, because there is exactly one principal. The only authorization in the system is external: GitHub OAuth grants the single user repo read/write + PR scopes so their agents can operate on their repos (flow-map S1), and the user’s own model keys/subscriptions authorize model traffic (BYO-client; the board never proxies). Those are credentials the user holds, not in-app permissions V2 grants to others. No permissions surface is designed; failures of those external credentials are handled as recovery paths (§10), not as a permissions UI.

9. Return-Use & Notification Model

V2 is a return-heavy surface (the Conductor checks in repeatedly across a day and across devices). Return mechanics:

• Re-entry lands on S3. A returning session with valid state opens straight to the mosaic at current server-canonical state — no reconnection ceremony, no stale data (flow-map handoff: “state is server-canonical”).
• At-a-glance return read: sort (error > waiting > running > idle) + the header approval-queue badge mean the first thing the eye lands on is whatever needs the user. Waiting cards pulsate; error cards show a red badge + error summary line.
• Recap on long absence: if the device-switch/time-gap threshold is exceeded (D7), an S8 Async Recap is offered before the board — a vertical timeline of what happened while away (completed, pending approvals, errors, PRs). Dismiss → S3. V2 treats recap as an interstitial over the mosaic, consistent with the modal-and-route pattern, not a permanent board region.
• Notifications: Web Push via the PWA service worker. An approval or completion fires a push to all connected devices; tapping the push deep-links into the relevant agent’s detail route (or to S3 if the deep link can’t resolve). This is the engine of the “closed laptop, checked from phone” loop, even though the approval branch itself is owned by a sibling flow (approval).
• PWA install is offered on first mobile visit (per Path F) to enable push + home-screen re-entry.
• Push reliability on mobile (esp. iOS Safari) is a known open question (flow-map Open Q #3); V2 does not assume push is guaranteed — the board’s sort + badge make the surface usable as a pull channel even if a push is missed.

10. Failure Recovery Behavior

Mapped to the flow-map Failure & Recovery table and the per-screen matrices:

S4 modal failures (launch fails / tool unavailable): inline error in the modal with a Retry; if the selected tool isn’t installed in the workspace, a warning with an Install tool link to S10 and Start disabled until a valid tool is chosen (S4 matrix).

Recovery design principle for V2: failures are expressed on the card (badge + summary + re-sort to top) so the board itself is the recovery queue — no separate error console. Deep remediation happens by clicking through to the folded detail.

11. Page & Flow Changes vs. the Flow-Map Baseline

V2 is intentionally the minimal-divergence variation. Tracking:

• S3 Agent Board — tracks the flow-map low-fi notes essentially verbatim: responsive card grid (2–3 cols desktop / 1 col mobile), card fields (name, status badge, tool, repo, elapsed, stdout preview), sort order, empty state with “Start your first agent,” and the connection-lost banner. Addition: cards also surface token usage (Happy Path step 3 lists it) and expand the stdout preview from one line to one-to-multi-line (see §13) — a richness bump, not a structural change.
• S4 Start Agent — tracks the flow-map exactly: centered modal with backdrop; repo / tool / prompt / optional-branch fields; Start primary + Cancel secondary; validation gates Start. No divergence.
• S5/S6 Detail — THE deliberate divergence. The flow-map lists S5 (Structured) and S6 (Terminal) as two screens with Mode A/B as a user choice (D2, “Open Terminal” toggle). Per the brief’s confirmed reframe (load-bearing, applies to every variation), V2 folds these into ONE detail route whose primary rendering is tool-adaptive:
  • CLI tools (Claude Code CLI, Codex CLI, Cursor worker, Aider, Continue, Cline, Copilot CLI, Augment) → terminal-primary (xterm.js over WebSocket) wrapped in structured chrome (header: name/tool/repo/status/elapsed; side rail: approval count + quick-approve; file-change strip).
  • API-native tools (Claude Agent SDK) → structured-primary (parsed activity stream, progress, file-change list, inline approval, prompt-injection footer) — no terminal, because there is no terminal to attach to.
  There is no Mode A/B user toggle. The folding is determined by the tool’s integration pattern, not selected by the user.
• Mode C / code-server (IDE) — out of scope for V2 (flow-map Open Q #4, brief bounding question). V2 makes no IDE affordance; it does not argue the case. The “drop to terminal” escape hatch for CLI tools covers the manual-intervention need without an IDE.

Net: two screens (S3, S4) match the baseline; the detail folds two baseline screens into one tool-adaptive route. This should propagate to the flow-map as an amendment, not a silent edit (per the brief).

12. Navigation Model

Place-based, route-driven — the canonical SaaS-dashboard nav:

• Persistent header (present on board; condensed on detail): app name/logo, approval-queue badge (count), settings gear → S10, and a QR / “Open on Mobile” button (Path F).
• S3 board is the home/hub. All deep paths originate here.
• Card → detail is a full-page navigation (URL changes to /agents/:id). The board is unmounted; detail is the active view. This is the defining nav choice of V2 and the source of its main risk (board context drops on the round trip — §20).
• Detail → board via an explicit Back to Board control (and browser back). Because state is server-canonical, returning re-reads live state — no stale board.
• Start Agent is a modal overlay, not a route: it stacks on top of the current view (board or detail) and dismisses back to it. Launching never navigates away.
• Deep links resolve directly to a route: a push/QR can open /agents/:id (detail), /approvals context, or / (board). Falls back to board if a deep link can’t resolve.
• Recap (S8) appears as an interstitial over the board on long-absence re-entry, then dismisses to the board.

Routing surface (illustrative): / board · /agents/:id folded detail · S4 and S8 as overlays/interstitials over whatever route is active · /settings (S10).

13. Screen-by-Screen Layout (Regions & Proportions)

S3 — Agent Board (mosaic)

• Header (top, ~56–64px tall, full width, sticky): left = app name; right cluster = approval-queue badge, “Open on Mobile”/QR, settings gear. A secondary row or right-aligned primary button = Start Agent.
• Connection banner (conditional, directly under header, full width): reconnecting state.
• Primary content = the mosaic (fills the rest): responsive grid of cards.
  • Desktop >1024: 3 columns; tablet ≤1024: 2 columns; mobile ≤640: 1 column.
  • Gutters generous (cards breathe — this is the density tradeoff vs V1).
• Card (the core component), regions top→bottom:
  1. Top row: agent name (left) + status badge (right; color-coded: error/red, waiting/amber, running/green, idle/grey).
  2. Meta row: tool name · repo (· branch if set) — small/muted.
  3. Metrics row: elapsed time · token usage — small/muted, right-aligned.
  4. stdout preview region (the distinctive area, ~3–5 lines, monospace): live one-to-multi-line tail of the agent’s output, auto-scrolling. This is what makes a card “rich” and is V2’s signature. Truncates with a fade at the bottom.
  5. (Conditional) error/completion strip: one-line error summary, or “completed — Review diffs →” on finish.

  Whole card is the click target → detail route. Status drives a subtle left-edge accent and (for waiting) a gentle pulse.

• Empty state replaces the mosaic: centered illustration + “Start your first agent” CTA + quick-start link.

S4 — Start Agent (modal overlay)

• Backdrop: dims the board (~50% scrim), click-to-cancel.
• Modal (centered, ~480–560px wide desktop; near-full-width sheet on mobile):
  • Title: “Start Agent.”
  • Repo picker (dropdown, auto-populated from GitHub OAuth; skeleton while loading).
  • Tool selector (dropdown).
  • Prompt (textarea, the tallest field, ~4–6 rows).
  • “More options” toggle → optional branch field.
  • Footer actions: Start Agent (primary, right; disabled until repo+tool+prompt set) · Cancel (secondary, left).
  • Inline error region above the footer for launch/tool-unavailable failures.

S5/S6 — Folded Agent Detail (full-page route)

• Top bar (full width): Back to Board (left); agent name · tool · repo · status badge · elapsed/session duration (center/left); stop / restart controls (right).
• Primary region (fills the page):
  • CLI tools → terminal-primary: a large xterm.js terminal fills the main area (≈70–80% width on desktop). It is the live, interactive interface.
  • API-native tools → structured-primary: the main area is the parsed activity stream (steps, progress indicator, file-change list) in the same footprint.
• Side rail (right, ~20–30% desktop; collapses below on mobile): approval-queue count + quick-approve button when pending; file-change summary; (for the structured view) the same file-change list lives here or inline.
• Inline approval: when the agent is waiting, an approval card appears in-flow (over the terminal as an overlay/badge for CLI; inline in the stream for structured) — approve / reject / modify / defer.
• Footer: prompt-injection textarea + send (both renderings); for CLI this writes to the session, for structured it injects into the agent.

Proportions summary: board = full-bleed grid; modal = centered ~520px card; detail = top bar + dominant primary region + a slim right rail.

14. Key Components & Controls

• Agent Card — the signature component: badge + meta + metrics + live stdout preview + conditional error/completion strip. Whole-card click target. Live-updating via WebSocket.
• Status Badge — error / waiting / running / idle / starting / completed; drives color, sort priority, and pulse.
• Live stdout Preview — monospace auto-scrolling tail (3–5 lines) inside each card. Reliability is bounded by the Multica-style stdout-parsing open question (§20); preview is best-effort tail, not a guaranteed structured parse.
• Start Agent button (header) + Start Agent modal (repo dropdown, tool dropdown, prompt textarea, optional branch, Start/Cancel).
• Approval-queue badge (header) + inline approval card (detail) + quick-approve (detail side rail).
• xterm.js terminal (CLI detail) / parsed activity stream (API-native detail) — the folded tool-adaptive primary.
• prompt-injection textarea (detail footer).
• stop / restart / retry controls (card error strip + detail top bar).
• Connection/recovery banner (board) + reconnecting overlay (detail).
• Back to Board control (detail top bar).
• QR / Open on Mobile button (header) and PWA install prompt (first mobile visit).
• Async Recap interstitial (S8 timeline on long-absence re-entry).

Sort/filter: default sort error > waiting > running > idle. Filtering is deliberately light in V2 (a simple status filter / repo filter chip row is the most it should add) — heavy filtering is V1’s territory; V2 leans on big legible cards instead.

15. Button & Link Behavior

• Start Agent (header/empty-state) → opens S4 modal over the current view; does not navigate. Disabled never (always available unless connection lost, where it’s disabled with the banner).
• Start Agent (modal footer) → fires the launch REST call; button shows a spinner, fields disable, “Starting agent…”; on success the modal closes and a starting card appears; on failure an inline error + Retry. Disabled until repo + tool + prompt are all set.
• Cancel (modal) → closes modal, returns to underlying view, no side effects.
• Agent Card (whole card) → navigates to /agents/:id (full-page detail). Hover = subtle lift/accent.
• “Review diffs →” (completion strip) → routes to S9 diff review (linked, sibling-scope).
• Retry (error strip / detail) → re-launches the agent with the same prompt; card → starting.
• Back to Board (detail) → navigates to /; board re-reads live state.
• Quick-approve / Approve / Reject / Modify / Defer (detail) → posts the approval to the agent; agent resumes sub-second; UI advances to next approval or back to streaming.
• Approval-queue badge (header) → routes to the highest-priority waiting agent’s detail.
• Settings gear → S10. QR / Open on Mobile → shows QR overlay (short-lived pre-authed deep link).
• Tool-unavailable “Install tool” link (modal) → S10, with the modal’s selection remembered.
• Browser back is a first-class citizen (routes, not just modals) — back from detail returns to board.

All destructive/irreversible actions (stop, reject) get a confirmation affordance; launching and approving do not (they’re the happy path and reversible enough).

16. Spatial Density, Sizing, Hierarchy

• Density: comfortable, not dense. V2 deliberately sits in the middle of the density axis — cards are large and well-spaced so each is independently legible and tappable. This is the explicit tradeoff: it costs fleet density (12 agents scroll) to buy per-agent glanceability and co-equal touch usability.
• Card size: roomy enough for a 3–5-line stdout preview without crowding the metadata — target ~ 220–280px tall on desktop. Min tap target for any in-card control ≥ 44px (mobile).
• Hierarchy within a card: status badge + name (primary) → stdout preview (secondary, the “what’s happening”) → meta/metrics (tertiary, muted). Color is reserved almost entirely for status; everything else is grayscale so the badge carries the signal.
• Board hierarchy: sort + pulse + red badges pull the eye to what needs action; the header approval-badge is the single global alarm.
• Detail hierarchy: the primary region (terminal or stream) dominates; chrome (top bar, side rail) is quiet so the live interface owns attention.
• Type scale: card name ~15–16px; meta/metrics ~12–13px muted; stdout preview ~12px monospace. Generous line-height in the preview for scannability.
• Color: dark house palette (--bg:#1a1a2e; --card:#16213e; --border:#2a2a4a; --accent:#4dabf7; --text:#e0e0e0; --muted:#8b8fa3). Status colors layered on top: green/running, amber/waiting, red/error, grey/idle. Accent (#4dabf7) reserved for the primary CTA and links. Terminal background slightly darker than card to read as a console.

17. Responsive Behavior at 3 Breakpoints

Mobile ≤ 640px (1 column):

• Mosaic = single-column stack of full-width cards; stdout preview may trim to ~2–3 lines.
• Header condenses; Start Agent may become a sticky bottom-right FAB or a full-width button.
• S4 modal becomes a near-full-screen sheet; fields stack; Start/Cancel pinned to a bottom action bar; large tap targets.
• Detail: top bar compresses (Back as a chevron); side rail collapses below the primary region (terminal/stream full-width). For CLI tools the terminal is read-mostly with an “open on desktop” hint for heavy typing (terminal latency + soft-keyboard ergonomics are the bounding constraints — V2 does not pretend phone terminal typing is great).
• Recap and QR render as full-screen sheets.

Tablet ≤ 1024px (2 columns):

• Mosaic = 2-column grid; cards keep full richness (3–5-line preview).
• Modal centered, ~480–520px.
• Detail: terminal/stream ~70% with the side rail visible at ~30% (may be collapsible).

Desktop > 1024px (3 columns):

• Mosaic = 3-column grid, generous gutters; full card richness.
• Modal centered ~520–560px over a dimmed board.
• Detail: terminal/stream dominant (~75–80%) + persistent right rail (~20–25%); top bar full.
• At very large widths the grid can grow to a capped max (e.g., 3–4 cols) rather than sprawling — V2 caps columns to keep cards readable rather than chasing density.

Co-equal posture means no breakpoint is the “real” one — the same components reflow; the phone gets a usable read-and-approve experience, the desktop gets comfortable multi-agent monitoring, neither is the privileged target. (Contrast: V1 privileges desktop, V5 privileges phone.)

18. Visual Tone

Familiar, trustworthy, boringly competent — on purpose. It should read like a polished deploy/CI dashboard (Vercel/Railway/Render lineage) so a new user feels instant fluency. Dark house palette; calm grayscale chrome with status color as the only loud element; soft card elevation; restrained motion (cards fade in on launch, waiting cards pulse gently, stdout scrolls smoothly — no gratuitous animation). The terminal in detail reads as a real console (monospace, darker bg). The overall message: “this is the safe, legible way to watch your fleet” — which is exactly the control’s job.

19. Strengths

• Lowest learning curve in the set — universal dashboard pattern; recognition over recall.
• Richest per-agent glance — badge + tool + repo + elapsed + tokens + multi-line live stdout means routine monitoring rarely needs a drill-in.
• Truly device-neutral — one model that degrades cleanly to 1-column mobile; never wrong on any device.
• Maps almost 1:1 to the approved flow-map — fewest net-new concepts, so it’s the cleanest control to measure the other four against.
• Failures live on the card — the sorted board doubles as the recovery/triage queue; no separate error console.
• Lowest build risk / fastest to ship (see §21) — frees evaluation budget for the riskier siblings.
• Modal launch is non-disruptive — launching never costs you your place.

20. Risks & Failure Modes

• Cards waste space at scale. At 10–12 agents the comfortable cards scroll significantly; there’s no single-screen overview. (This is the explicit reason V1’s dense table exists.) Mitigation: column cap + sort-to-top for actionable agents, but the ceiling is real.
• Route-switch drops board context. Drilling into an agent unmounts the board; the user loses the at-a-glance fleet view while in detail and must travel back. (V1’s split-pane and V3’s drawer-over-board exist precisely to avoid this.) Mitigation: fast back, lossless server state, deep links — but the round-trip cost is inherent to V2’s choice.
• stdout-preview reliability is bounded. The card’s live preview leans on Multica-style stdout parsing/tailing, whose generalization across CLI tools is an open question (flow-map Open Q #2). If parsing is noisy, the previews become reassuring-but-misleading. Mitigation: treat preview as a raw best-effort tail, not a structured promise; structured fields (badge/elapsed/tokens) come from control-plane signals, not stdout.
• Terminal latency in folded CLI detail. Sub-100ms keystroke echo over the tunnel is unproven (Open Q #1); if it’s laggy, the terminal-primary detail for CLI tools feels bad, especially on mobile. Mitigation: phone detail is read-mostly with desktop handoff; this is intrinsic to CLI tools, not a V2-specific flaw.
• “Generic” risk. Being the familiar control means it may underwhelm a power user who wants density (V1) or speed (V4) — it can lose an evaluation by being merely fine.
• Modal launch friction at high volume. Repeated repo/tool re-selection in the modal is slower than a template/duplicate quick-start (V5) for batch launches. Mitigation: remember last repo/tool as defaults; but novel-prompt launches stay a few clicks.
• No fleet-bottleneck spatiality — you can’t see a pileup of waiting agents as a column the way V3 does; you infer it from the badge count + sort.

21. Implementation Complexity

Lowest of the five (baseline). Rough estimate: low.

Why it’s the floor:

• The board is a standard responsive CSS grid of card components fed by one WebSocket state stream — no split-pane synchronization (V1), no drag/column-reflow choreography or status-driven card motion (V3), no command-palette/back-stack machinery (V4), and no bespoke feed-prioritization + swipe-gesture layer (V5).
• Navigation is plain routing (/, /agents/:id) + a modal and an interstitial — no novel interaction primitives.
• The two genuinely non-trivial pieces — the folded tool-adaptive detail (xterm.js over WebSocket for CLI / structured stream for API-native) and the live stdout previews — are shared across all five variations (every sibling must serve the deep-work layer and show live status), so they are not net-new cost relative to the set. Within the set V2 adds the least on top of that shared baseline.
• Reuses the shared tech stack + design system wholesale; owns only its grid layout, card component, and modal.

Largest single risk to the estimate is external, not structural: stdout-parsing reliability and terminal latency (both shared open questions), not V2’s own UI.

22. Prototype Scope

For the serial build → /uat --variant-evaluation comparison, prototype:

• S3 board with a mosaic of 6–8 live-ish cards spanning all states (running w/ streaming preview, waiting/pulsing, error/red, idle, completed-with-Review-diffs, starting) and the correct sort order; plus the empty state; plus the connection-lost banner.
• S4 modal end-to-end: repo dropdown, tool dropdown, prompt textarea, optional-branch toggle, validation-gated Start, the launching spinner, and a launch that drops a new starting → running card into the grid. Include the tool-unavailable error path.
• Folded detail route for both renderings: at least one CLI agent (xterm.js terminal with a stubbed live stream + inline approval overlay + prompt-injection footer) and one API-native agent (structured activity stream + inline approval). Include Back to Board.
• Responsive proof: the same prototype at all three breakpoints (1-col phone, 2-col tablet, 3-col desktop), including the mobile sheet modal and the mobile read-mostly terminal.
• Approval round-trip: click a waiting card → approve in detail → back → card now running.

Out of prototype scope (linked, not built here): full S9 diff review, S8 recap timeline beyond a stub, S10 settings, real push delivery, real tunnel/auth, and Mode C/IDE (excluded).

23. Readiness Signal for /ui-interview

This spec is ready to hand to /ui-interview [v2-card-mosaic] once V2 is selected or built. It fixes, for the visual-mockup stage:

• the board representation (responsive card grid), connection (full-page detail route), launch (modal), and device posture (co-equal responsive) — all four axes at the flow-map baseline;
• the screen inventory in scope (S3 board, S4 modal, folded S5/S6 detail) with regions, proportions, and three-breakpoint behavior;
• the component set, button/link behavior, hierarchy/density, and visual tone;
• the folded tool-adaptive detail decision (no Mode A/B toggle) and the out-of-scope calls (IDE/Mode C, multi-user sharing/permissions = N/A).

Open items the UI interview should resolve (not blockers, just the live questions): exact card dimensions / preview line-count, the precise side-rail width and collapse behavior in detail, the light-filtering affordance (status/repo chips) if any, and mobile terminal ergonomics copy (“open on desktop” handoff). Bounding open questions (terminal latency, stdout-parsing reliability) are flagged as risks, not resolved here, and carry forward as evaluation criteria.