Diagnostics

"Diagnostics" in Director means: can I tell from this page what root I'm connected to, whether the runtime is reachable, and what's failing? Director does not have a dedicated "diagnostics" tab today; the diagnostic surface is distributed across the top bar, the attention strip, the package status row, and the ops feed.

Connection identity (top bar)

Two strings, computed by DirectorTopology.resolveDirectorTopology:

Browser label — "signed in as <authorityRoot>", or "browser session active" if no authority root is bound, or "browser session unknown" if the bootstrap didn't populate it.
Runtime label — one of:
- "runtime: <runtimeRoot>" (normal)
- "attached runtime for <authorityRoot>" (when bootstrap targeted a leaf)
- "no live runtime attached for <authorityRoot>" (no runtime found)
- Optional " · via: <platformRoot>" suffix when a platform forwarder is in front

The <matrix-dsl-host> element status (data-status="connected"|"connecting"|"error") is what monitorMatrixAppReady (src/index.ts) watches before deciding Director's matrix-app-ready event. If data-status never becomes connected, the app stays in the loading screen.

App readiness signal

Director declares readinessLevel: 'shell' in its directorReadiness() callback (src/index.ts:81-114). That means Director only signals "ready" when:

<matrix-dsl-host> is connected.
#root-tag text contains "runtime: " (i.e., DirectorTopology resolved a runtime label).
The host element has root, data-address-root, and data-runtime-target-root populated.

requiredActorsReachable: false and an empty actorProbes: [] mean Director currently does not probe specific actors before declaring shell-readiness. That fits its observation-only role; it doesn't need system.runtimes to be alive to render the shell, just for the tree to populate.

Attention strip

DirectorApp renders an attention strip at the top of the layout (the styles begin around DirectorApp.ts:242-301). Three classes — informational, warn, error — are populated from:

Failed RPC calls (e.g., a registry probe timing out).
Compat-only package detection (warning level).
Adapter errors surfaced from DirectorRuntimeAdapter catch paths.

These chips are clickable; some open the relevant Ops Feed view, others open the affected actor. The exact wiring lives in DirectorApp but is private to that class.

Package status row

The package strip in Explorer Mode is a per-family diagnostic (see Packages). For each of agents, observability, sqlite:

mode: 'package-root' — green dot, canonical root reachable.
mode: 'compat' — yellow dot, only the compat alias responded.
mode: 'missing' — red dot, neither responded.

This is the cleanest "is the platform alive" check Director offers from its own UI.

Diagnostic flows

Symptom	First check
Tree is empty after refresh	Runtime label shows "no live runtime attached" → confirm with `hivecast runtimes`.
Tree shows runtime root only	`system.registry registry.list` returned no claims → check that runtimes called `runtimes.register` after starting.
All packages show `compat`	Deployment exposes legacy aliases instead of canonical roots.
Ops feed empty	`system.observability.tracing $introspect` to confirm the actor is mounted; the compat fallback `system.tracing` is also tried.
Memory tab returns nothing	Adapter prefers `system.agents.memory`; verify with `matrix invoke system.agents.memory $introspect`.
Chat tab shows "unavailable"	`@open-matrix/chat-component/surface` lazy chunk failed to load. Rebuild Director, hard-reload.

What Director does not yet have

A self-diagnose page that runs $ping/$introspect against every adapter target.
A live "actor latency" gauge per mount.
A connection log with reconnect attempts.

These would be straightforward additions; today the operator gets them via hivecast doctor and journalctl.

Diagnostics ​

Connection identity (top bar) ​

App readiness signal ​

Attention strip ​

Package status row ​

Diagnostic flows ​

What Director does not yet have ​

See also ​