Mission Control: Dashboard, macOS App & Activity Spine

A local, real-time view of what your agents are doing, who asked for it, and what happened next — without moving task state off your machine.

Early release. The dashboard, native app and event spine are new in the 3.10 line. The wire contract is frozen (docs/local-dashboard.md), but expect rough edges while the UI settles.

What it is

Sugar already keeps a durable task queue on disk. Mission Control adds two things on top of it: a loopback HTTP + SSE API that observes that queue (and can drive the same writes the CLI and MCP server use), and clients — a browser UI and a native macOS app — that show the work live. It is deliberately not a second task store: the dashboard reads the canonical database read-only and every write goes through the same code paths as sugar add.

Quick start

pip install 'sugarai[dashboard]'
# or, if you installed with pipx:
pipx inject sugarai 'sugarai[dashboard]'

cd /path/to/your/project
sugar dashboard

The UI is served at http://127.0.0.1:7331. The server binds loopback only; it is not intended to be exposed to a network. Useful flags: --port, --db, --read-only, --board kanban, --events-db.

Board sources

Sugar queue (default) — --board sugar reads .sugar/sugar.db.
Hermes Kanban — --board kanban (with --kanban-board, --hermes-bin) serves a board through a read-only SQLite connection; every write shells out to hermes kanban so the board keeps its single write path.

GET /api/meta describes the active board (statuses, columns, capabilities) so one UI renders both state machines.

The macOS app

SugarDash is a dependency-free SwiftUI client that talks to the same API. It runs from source (apps/macos/build-app.sh) or as a drag-to-Applications DMG (apps/macos/build-dmg.sh --universal). It shows the live task list, lets you create/edit/hold/release tasks, keeps a menu-bar pending count, and has an Activity feed. Build requirements: macOS 14 or newer and Xcode command line tools.

Provenance: who created and who claimed

Work items record created_by, created_by_kind (human/agent/system), created_by_session, claimed_by and lease_expires_at. The claim and lease are written in the same transaction as the claim, so two workers can never both think they own a task. Identity resolution order: explicit actor → $SUGAR_ACTOR → $SUGAR_AGENT_ID → $USER@$host. The CLI accepts --actor/--actor-kind, the MCP server derives the actor from the initialize handshake, and the dashboard accepts X-Sugar-Actor. Provenance is provenance, not authorization.

The event spine

A separate append-only events.db (default ~/.sugar/events.db, 30-day retention) records task transitions and harness telemetry. Two best-effort observers feed it — the Kanban source tails the board's own task_events, the Sugar source records snapshot diffs — and any harness can post to POST /api/events. Read it forward with GET /api/activity?since_id=&limit= or subscribe to the SSE activity channel. If the spine fails, tasks and the dashboard keep working.

Security model

Loopback binding is enforced; non-loopback hosts are rejected.
State-changing requests with a foreign Origin are refused, so a random web page cannot POST to the local API.
Request bodies are capped at 1 MB; responses carry standard security headers.
The event database is created 0600.
No authentication in the early-release loopback model — do not expose the port.