Governance Observability
Light Station is the operator-facing console for governed AI systems. It provides a persistent operating picture of agent proposals, policy verdicts, evidence chains, and human escalations — across any jurisdiction running on the AgentVector architecture.
Architectural Constraints from the Agency Paradox are enforced in each jurisdiction as composed Codex Laws; Light Station surfaces their verdicts.
The observability gap
Light Station is not generic observability. Traditional APM tells you about performance and failure. Light Station tells you about authority, policy, verdict, and escalation.
It surfaces what the agent proposed, what law evaluated it, whether it was allowed or denied, what evidence was recorded, and where human authority intervened. These are governance-specific signals that do not exist in conventional monitoring tools.
The architectural response is a passive operator console: separate from the governing kernel, read-mostly by default, with a narrow command surface for the decisions only a Principal can make. Light Station is that console for the Vigil desktop-agent jurisdiction.
Where Light Station sits
Light Station is an application layer operating under a Vigil jurisdiction. It consumes Vigil's HTTP governance contract — it does not import the Swift kernel. The language boundary is the adapter seam: request/response shapes for state, queue, audit, budget, and the /events SSE stream.
Architecture
Light Station is a locally-hosted Node.js service with a React front end. It maintains local application state in SQLite and proxies governance state from Vigil through a State Bridge that listens to the upstream SSE stream.
Components
| Component | Role | Technology |
|---|---|---|
| React SPA | 13 lighthouse views — Lantern Room, Lookout, Clearance, Chartroom, and more | Vite, Zustand, Tailwind |
| Express API | REST endpoints + SSE fan-out to browser clients | Node 20, port 7789 |
| State Bridge | Vigil SSE listener, 500-event ring buffer, 10s state refresh, 30s disconnect detection | TypeScript |
| SQLite | Sprints, tickets, knowledge graph, logbook, signal cards | better-sqlite3 |
| Vigil adapter | Contract seam between TypeScript and Swift — mock + live clients behind one interface | interface.ts |
SSE data pipeline
Governance events flow from Vigil to the operator in real time. The State Bridge is the critical integration point — it maintains a ring buffer, refreshes full state on a schedule, and marks the connection degraded when events stop arriving.
/evaluate → verdict: ALLOW, DENY, or ESCALATE GovernanceEvent on /events SSE stream /api/stream Two pillars
Verdict stream, approval queue, audit ledger, budget posture, agent roster. Everything Vigil decides, visible to the Principal.
Structured graph (Landmarks, Chart, Soundings), write-once Logbook, Memory Proposals, and Briefing API for agent session context.
Core surfaces
Light Station organizes operator workflows around a lighthouse metaphor. Each view maps to a distinct governance or knowledge function.
| View | Lighthouse name | Function |
|---|---|---|
| Operating picture | Lantern Room | Session overview, live stats, governance feed |
| Verdict stream | Lookout | Live governance event stream with law references |
| Escalation queue | Clearance | HOLD verdicts awaiting Principal approve/reject |
| Evidence log | Logbook | Write-once steward record; auto-ingests significant events |
| Audit trail | Ledger | Hash-chained audit log proxied from Vigil |
| Composition map | Chartroom | Knowledge graph with governed Memory Proposals |
| Thermal / resource posture | Provisions | Token budget console; Normal → Degraded → Gated → Halted |
| AI intake | Beacon | Signal Cards — agent proposes triage, Principal commits |
| Deep research | Sounding Report | Research briefs promoted from Logbook or Beacon |
| Sprint board | Voyage | Kanban sprint management with token budget |
| Work items | Manifest | Ticket tracking with status workflow |
| Agent roster | Crew | Active agents under observation |
| Policy config | Registry | Vigil configuration viewer |
Live feed of agent proposals with ALLOW / DENY / ESCALATE outcomes and the law that evaluated each.
Pending human-authority decisions. Actions suspended until an authorized operator resolves them. Mobile-first for field approval.
Hash-chained record of every governed decision. Replayable on demand. Same inputs — same verdict, provably.
Landmark, Chart, and Sounding layers. Agents propose memory; the Principal commits. Briefing API feeds context back to the agent.
AI-assisted triage of inbound information. Suggests routes — create ticket, propose knowledge, log to watchlog — but never auto-acts.
Token budget enforcement ladder. System-level compute and thermal state for Apple Silicon deployments running governed workloads.
View the interactive prototype → Uses legacy view names (Command, Queue, Observe) — being updated to match the lighthouse metaphor.
Operator flows
Three flows define how the Principal exercises authority through Light Station. Each demonstrates the propose-don't-decide pattern: the agent or system proposes; only the Principal commits.
/queue/:id/approve|rejectkg_proposal with proposed edgeskg_node and edges created in knowledge graphmaybeIngestEvent() writes to Logbook./scripts/run-demo.sh against a live Vigil instance.
Fail-closed operator UX
Most dashboards degrade gracefully when upstream data is stale. Light Station refuses to. When Vigil is unreachable, the operator sees a disconnected state and Steward controls are disabled — not cached queue data from five minutes ago.
| State | UI behavior | API behavior |
|---|---|---|
| Connected | Live stream, Clearance queue actionable, enforcement level visible | 200 — proxied from Vigil |
| Degraded | SSE stale (>30s); banner shown; state refresh from /governance/state | 200 with stale indicator |
| Disconnected | Disconnected banner; approve/reject controls disabled; no stale queue data | 502 { "error": "Vigil unreachable" } |
Verdict mapping
Light Station surfaces Vigil's three verdicts with consistent operator semantics across all views.
Verdict Vigil source Operator action ALLOW allowObserve in Lookout. Agent executes. DENY deny / rejectReview in Lookout and Ledger. Agent does not execute. HOLD escalateResolve in Clearance. Agent suspended until Principal acts.
This is a P0 invariant tested in CI: queue endpoints return 502 when Vigil is unreachable. The mock client enables full development and test coverage without a live Swift daemon.
Reference implementation
Apple Silicon home lab · Forge
Light Station's first production instance runs on a Mac Mini M4 Pro cluster via launchd. Claude Code is the agent under observation. Tailscale provides remote access for field approval on Clearance — no public internet exposure.
Service Port Owner Light Station API 7789 launchd (com.agentincommand.lightstation) Vigil daemon 18820 launchd (Swift) Vite dev server 5173 Development only
This lab environment is the live proof-of-concept for governance observability at the desktop scale — the same architecture that scales to enterprise and regulated workflows.
Roadmap
Light Station is designed to scale beyond the desktop reference implementation. The following table separates what ships today from what is planned.
Shipped · v0.2.0 Roadmap macOS launchd + Tailscale deployment K3s cluster observability across runtimes Single-operator SQLite substrate Multi-tenant enterprise console OpenClaw + Claude Code lab agent Multi-agent governance dashboards 13 lighthouse views + Beacon/Signal intake Plugin architecture for custom surfaces Apple Silicon thermal monitoring (Forge lab) Regulated industry workflow integrations
Cross-runtime observability — governing agents across K3s and macOS from a single operating picture — is the long-term thesis. The macOS path is the reference proof; cluster-scale deployment follows the same constitutional pattern.
Vigil · TSVector Governing jurisdiction Light Station observes Vigil. The kernel decides; the console shows. Constitutional policy, three laws, fail-closed enforcement.
Vigil architecture → FlightLaw · SwiftVector Aviation operator surface Flightworks Sentinel provides the aviation equivalent — governing what AI proposes before it reaches the autopilot. Same pattern, different domain.
Flightworks architecture →