orchestra/orchestra-ui-spec.md

# orchestra web control ui

status: mockup specification
app: orchestra
shared design system: ethos
accent: signal violet `#8F7AE5`
motif: routing fork
primary operator: single infrastructure operator

## 1. purpose

orchestra's web ui is an operator console for understanding and steering agent work without reconstructing state from logs, tmux sessions, gitea, or the event stream.

it has three jobs:

1. show what needs the operator now.
2. show what orchestra believes and what an agent is actually doing.
3. expose intervention and forensic detail without making the default screens noisy.

it is not a generic project-management product, an analytics dashboard, or a chat-first interface.

## 2. ethos application

orchestra inherits the ethos shell and neutral system unchanged.

### fingerprint

- accent: signal violet `#8F7AE5`
- motif: routing fork
- accent use: active navigation, focus, selected phase, primary operator action, routing/transition marks
- motif use: app mark, phase transitions, routing state, empty states, one hero/detail moment

suggested token block:

```css
[data-app="orchestra"] {
  --accent:      #8F7AE5;
  --accent-hi:   #A291EC;
  --accent-dim:  rgba(143, 122, 229, 0.14);
  --accent-line: rgba(143, 122, 229, 0.32);
  --accent-glow: rgba(143, 122, 229, 0.22);
}
```

### type

- geist sans: labels, task names, explanations, buttons, headings, operator-authored prose
- geist mono: task ids, epochs, worker ids, pane ids, timestamps, percentages, context counts, revisions, paths, refs, sha values, lease durations
- machine values must never silently use sans for visual convenience

### surfaces

- page room: `--bg-0`
- normal panel: `--bg-1`
- selected/raised content: `--bg-2`
- hover: `--bg-3`
- borders: 1px `--line`, `--line-hi` only where selection or risk needs stronger separation
- no blur or glass
- accent never washes a whole content panel

### motion

all ui transitions use ethos mechanical motion: 130–170 ms, `cubic-bezier(0.2, 0, 0, 1)`, no spring or bounce.

## 3. shared shell

### desktop

- 64px vertical icon rail
- 56px top bar
- main content fills remaining viewport
- global `cmd+k` command/search surface in the top bar
- right side of top bar shows only high-value machine state: orchestra revision, live state, current time

primary navigation:

1. dashboard
2. tasks
3. decisions
4. workers
5. projects
6. review
7. settings

terminal is entered from a task or worker and does not need permanent primary navigation.

### mobile

- rail becomes bottom navigation with no more than five primary items
- secondary pages move behind task/project drill-down or header menus
- machine readouts relocate into detail screens rather than disappearing
- terminal remains a dedicated full-screen view

## 4. information hierarchy

orchestra should visually distinguish five classes of information.

| class | meaning | treatment |
|---|---|---|
| operator authority | human decision, correction, constraint | high prominence, accent signal |
| verified orchestra state | lifecycle, lease, phase, review, refs | neutral surfaces, machine values in mono |
| agent claims | proposed plan, handoff text, self-reported risk | visibly labeled as agent-supplied |
| historical/superseded | stale plan, previous handoff, old decision | muted, never visually dominant |
| fault/attention | blocked, refused, stale, mismatch | status color + explicit reason |

raw events and implementation details are drill-down evidence, not default-page content.

## 5. dashboard

mockup: `final/01-dashboard.png`

purpose: answer "what needs me, what is running, and is the system healthy?"

### layout

three primary regions only:

1. **needs your attention**
   - trajectory gate
   - blocking human decision
   - pr awaiting review
   - closed-without-merge/operator-required state
   - one line explaining why each item needs the operator

2. **running tasks**
   - task name/id
   - current phase
   - worker/harness
   - last real progress
   - context occupancy
   - lease timing
   - compact routing-fork phase indicator

3. **system state and capacity**
   - workers online/available
   - quota status
   - active leases
   - router queue/rejection state
   - source reconciliation
   - herdr health

### rules

- no disk, cpu, ram, or generic host-monitor metrics unless they directly block orchestration
- no vanity charts
- health should show actual counts/times, not vague "running" indicators
- dashboard actions should navigate to the relevant task/review/worker rather than becoming an operator-control surface itself

## 6. tasks list

mockup: `final/04-tasks.png`

purpose: browse all work under orchestra and locate a task quickly.

### groups

- needs attention
- running
- waiting/queued
- completed
- failed

### row fields

- task title/id
- project
- current phase
- compact routing-fork phase path
- worker/harness when assigned
- last update/progress
- context occupancy for active sessions
- status

### filters

- project
- phase
- worker/harness
- status
- attention state

avoid turning this into a kanban board. orchestra's lifecycle is stateful and event-backed; the list should expose state, not encourage arbitrary drag-and-drop mutation.

## 7. task detail

mockup: `final/02-task-detail.png`

purpose: provide one calm page answering "what are we doing?", "what is happening?", and "where are we in the workflow?"

### top area

- title
- task id
- project
- current phase
- steer/correct primary action
- secondary actions menu

### what we're doing

show only:

- goal
- acceptance summary
- latest effective human decisions when present
- active constraints when present

full contract, all decisions, and historical versions open in drill-down views.

### live execution

show only:

- worker/harness
- pane
- lease remaining
- context occupancy
- last progress
- one-line current activity

links:

- open live pane
- worker logs
- launch context
- git diff

### workflow

render the ace-fca path visibly:

`frame → research → plan → implement → review → pr → merged`

completed phases are quiet green, current phase uses the orchestra accent, future phases remain neutral.

phase detail, artifacts, refusal history, and raw events belong in drill-downs rather than the default task screen.

## 8. live pane / terminal

mockup: `final/03-terminal-live-pane.png`

purpose: show the actual tmux/herdr pane, not a reconstructed log view.

### behavior

- read-only by default
- exact pane dimensions and terminal rendering preserved when possible
- fit mode may scale visually but must not alter the underlying pane
- scrollback inspection must not disturb the live cursor
- `take control` explicitly enables keyboard forwarding
- strong visual state when control is captured
- escape or a fixed shortcut releases control

### why this screen exists

it must reveal real tui state such as:

- input still sitting in the editor
- queued input
- paste placeholders
- permission/approval dialogs
- `/clear`
- `@HANDOFF.md`
- agent busy/idle presentation
- tmux status line and pane identity

### surrounding chrome

keep it minimal:

- worker/pane identity
- read-only/control state
- fit/copy/scrollback controls
- lease epoch/timing
- context occupancy
- last verified progress
- pane/worker health
- small live event strip for orchestra-originated interactions and confirmations

when a pane is lost, preserve the last captured frame and state the exact loss time and lease consequence.

## 9. decisions list

mockup: `final/05-decisions.png`

purpose: inspect durable human authority and approvals across tasks.

this is not the human attention queue; that is review.

### list fields

- decision id
- short decision text
- task
- phase
- source/provenance
- requested/recorded time
- status: active, superseded, waiting, approved, rejected, auto
- operator/actor

### filters

- active/superseded
- kind: decision, correction, constraint, answer, scope change
- project
- task
- actor/source

### detail

opening a decision should show:

- exact value
- subject
- provenance
- supersedes/superseded-by links
- event sequence
- effective authority impact

machine provenance is mono; the human decision text remains sans.

## 10. workers

mockup: `final/06-workers.png`

purpose: answer "where can work run and is that execution machinery usable?"

### worker list fields

- worker/harness identity
- online/idle/busy/offline/degraded
- harness type
- current task when leased
- phase
- lease or heartbeat age

intentionally omit generic infrastructure metrics such as disk, memory, cpu, and uptime unless orchestra directly uses them for eligibility.

### worker detail

- current session/task
- pane id
- lease epoch/remaining
- last verified progress
- worker revision
- herdr status
- last heartbeat
- projects declared by the worker
- declared capabilities if orchestra actually consumes them

### capabilities

capabilities must come from worker registration/project configuration, never be guessed from host inspection.

the ui labels them **declared capabilities** and can expose registration provenance.

### registration

registration is worker-driven:

1. worker starts with coordinator credentials/configuration
2. worker announces identity, revision, harnesses, projects, capacity and declared capabilities
3. coordinator records it and heartbeat updates liveness

`add worker` should therefore be a registration guide/bootstrap flow, not a magical browser-side creation of a remote process.

## 11. projects

mockup: `final/07-projects.png`

purpose: group long-running repository/workflow configuration and its active work.

### project list

- project name
- short description
- state
- active/total task count
- attention/decision count
- last meaningful activity

avoid aggregate artifact counts or infrastructure metrics unless they help choose an action.

### project detail

- description
- source/repository identity
- configured worker/harness affinity
- workflow phases
- trajectory-gate policy
- quality gate
- human reconcile source
- safe-operation policy
- active tasks
- recent meaningful events

configuration edits belong in the project detail, while global defaults remain in settings.

## 12. review

mockup: `final/08-review.png`

purpose: the operator inbox: **what needs me to look at something and judge?**

workers show machinery. review shows human attention.

### review item types

- trajectory decision
- human blocker / decision request
- code/pr review
- ai review requiring operator override
- operator-required lifecycle state
- closed pr without merge
- information/fyi, optionally hidden by default

### list fields

- type
- task/item
- why it is here
- project
- priority
- age

worker/pane is secondary metadata, not a primary column.

### detail drawer/page

show the minimum evidence needed to act:

- why this needs the operator
- effective task goal/constraints relevant to the decision
- proposed options when applicable
- relevant plan/diff/review evidence
- provenance and age
- comments/context drill-down

primary action names must match the lifecycle action: make decision, answer blocker, review pr, request changes, retry, etc.

snooze/defer may exist for attention management but must not silently mutate underlying task truth.

## 13. settings

mockup: `final/09-settings.png`

purpose: configure orchestra itself, project-independent defaults, integrations, policies, and operator/security settings.

### tabs

1. general
2. appearance
3. notifications
4. access & security
5. integrations
6. agents & tools
7. policies
8. advanced

### general

- instance name/environment
- locale/time display
- default task preferences
- default workflow policy
- event/artifact retention
- storage/backup state only if orchestra owns it

### appearance

- theme: system/dark/light
- ethos remains fixed; no arbitrary shell redesign controls
- accessibility and reduced motion

### access & security

- surface tokens/status
- trusted review actors
- ignored actors
- operator sessions
- agent-surface auth
- secret/config source status without exposing secret values

### integrations

- gitea
- vikunja
- notification sinks
- source reconciliation state

show endpoint/identity and last successful interaction in mono.

### agents & tools

- harness definitions
- adapter/runtime configuration
- tmux/herdr ownership
- default launch behavior
- context occupancy thresholds

### policies

- work phase defaults
- trajectory gate
- bounded decision request budget
- retry policy
- reconcile failure handoff threshold
- quality/review/submission policy

### advanced

- event-store diagnostics
- snapshots/replay
- raw configuration
- migration/status information
- destructive operator actions in a visually separated danger zone

## 14. global command surface

`cmd+k` is the shared ethos command surface and should handle navigation plus safe operator actions.

examples:

- open task by id/title
- open worker/pane
- show decisions for task
- steer/correct active task
- answer current blocker
- retry failed task
- open review item

high-risk lifecycle actions require explicit confirmation and should not be the first fuzzy-search result for ordinary text.

## 15. status grammar

status is compact and consistent across screens.

recommended semantic colors:

- green: verified healthy/completed/accepted
- violet: current/selected/orchestra-controlled active state
- amber: waiting/degraded/operator attention
- red: failed/refused/danger
- gray: idle/unknown/historical

color never carries the entire meaning; every state also has text/iconography.

## 16. evidence drill-down

any important derived claim should be traceable without ssh.

from relevant detail screens the operator should be able to reach:

- event(s) that established the state
- exact generated launch context
- sealed research/plan/review/submission artifact refs
- git sha/ref
- worker journal observations
- input confirmation receipt
- pane capture/terminal
- source comment/review provenance

raw evidence is accessible but not visible by default.

## 17. copy rules

- labels describe what the operator controls, not implementation class names
- machine values remain exact and honest
- errors state what failed and what consequence follows
- no "something went wrong"
- no spinner where a queue depth, heartbeat age, poll timestamp, retry time, or progress value exists

examples:

- `source reconcile failed · retry at 14:06:00`
- `worker heartbeat 42s old · ineligible after 60s`
- `phase request refused · next phase is research`
- `pane lost at 13:42:18 · lease expires in 09:14`

## 18. responsive behavior

### tablet/mobile priorities

keep visible:

1. attention state
2. task title/phase
3. latest human authority
4. live execution state
5. primary action

collapse or drill down:

- long acceptance lists
- complete workflow history
- detailed lease metadata
- worker journal
- raw events
- project configuration

terminal becomes its own full-screen route and should not be squeezed into a card.

## 19. implementation order

recommended web-ui build order:

1. ethos shell + orchestra tokens/motif
2. dashboard
3. tasks list
4. task detail
5. live pane
6. review inbox
7. decisions list/detail
8. workers
9. projects
10. settings
11. global command surface
12. evidence/raw-event drill-down

build each screen against real orchestra api data rather than static ui-only state as early as practical.

## 20. verification

for every screen:

- render and visually inspect pixels
- check desktop and <=640px mobile layout
- assert no horizontal overflow
- verify mono/sans split visibly
- verify accent is signal-only
- verify no blur/backdrop-filter exists
- verify empty/error/loading states show real machine state
- compare implemented screen against the corresponding mockup as direction, not pixel-perfect contract

mockups communicate hierarchy, density, and interaction intent. orchestra state and the ethos design laws are the actual specification.