Diagnostics

Runtime Host troubleshooting today is a small toolbox: hivecast doctor, hivecast seed, hivecast status, matrix invoke host.control runtime.list, and the runtime stderr files. There is no unified "support bundle" command yet.

hivecast doctor

hivecast doctor [--cloud <url>] [--repair] [--json]

Audits the local Host home for known failure modes. Implementation in projects/matrix-3/packages/hivecast/bin/hivecast.mjs (handler runHostDoctor). Checks include:

• host.json exists and parses.
• credentials/hivecast-install.json is present and valid.
• The bundled bin/nats-server[.exe] is executable.
• packages/system/ contains the expected default packages.
• (with --cloud <url>) The cloud endpoint is reachable and the link is healthy.
• (with --repair) Attempts to re-seed missing files where possible.

hivecast doctor --home /tmp/matrix-home --json | jq .
hivecast doctor --home /tmp/matrix-home --repair --json | jq .
hivecast doctor --home /tmp/matrix-home --cloud https://hivecast.ai --json | jq .

hivecast seed

hivecast seed [--home <home>]

Reseed the bundled package store and report runtime-record health (hivecast.mjs:494-554):

{
  "ok": true,
  "home": "/var/lib/hivecast",
  "seeded": true,
  "runtimeRecords": {
    "healthy": 9,
    "corrupt": [
      { "runtimeId": "RUNTIME-...-HOST-CONTROL", "path": "...", "kind": "empty", "size": 0 }
    ]
  }
}

Use seed whenever you suspect:

• The system package store is missing or corrupt.
• Runtime records are degraded by zero-byte writes (the original crash-loop bug; "kind: empty" is its signature).
• The bundled NATS binary was deleted.

seed is idempotent and safe to run repeatedly.

hivecast status / matrix status

hivecast status --home <home>          # shorthand, JSON output
matrix status --control supervisor     # bypass host.control, talk straight to supervisor

Combines:

• host.status.json if the Host is live.
• host.control.status RPC to enrich with current runtime records and control-mount health.
• host.supervisor.status (with --control supervisor) for the unfiltered supervisor view.

The CLI's logic is at cli.ts:53-98. If the supervisor RPC fails, the CLI gracefully falls back to the on-disk records and includes a supervisorError field — this is how you tell "Host is dead" from "NATS is broken but the Host process is alive."

Reading per-runtime health

matrix invoke host.control runtime.list '{}' | jq \
  '.runtimes[] | { runtimeId, status, pid, ch: .metadata.controlHealthStatus, why: .metadata.controlHealthReason }'

Common results:

status	controlHealthStatus	Meaning
running	(absent)	healthy
running	degraded	pid alive but runtime.health did not respond cleanly. See controlHealthReason
failed	(any)	runtime crashed. See metadata.failedReason and the per-runtime stderr.log
stopped	(any)	runtime exited cleanly (matrix down or restart: never exit-0)

Common error signatures

First line of error	Likely cause	Fix
Matrix Host Service is not running; start it with matrix start	host.status.json missing or pid dead	hivecast start --home <home>; check journalctl
host-service status reports corrupt: [...]	zero-byte / parse-broken runtime.json	hivecast seed; delete corrupt directories if seed cannot recover
Failed to spawn nats-server: ENOENT	bin/nats-server missing	hivecast install --home <home> re-drops it
nats-server exited early	port in use, or wrong binary path	check lsof -i :4270; check host.json transport.nats.binaryPath
Runtime ... cannot start: logical mount "..." is already owned by ...	mount conflict, see Start runtime	matrix down the conflicting runtime, or pick a different mount
Timed out waiting for runtime control actor ... after ...ms	runtime spawned but never bound runtime.ready. See log tail in error message	check the runtime's stderr; package bug
runtime.health did not respond (in controlHealthReason)	runtime alive but unresponsive on its control mount	check the runtime; restart it via matrix down + matrix up

Filing a bug

A useful bug report includes:

• hivecast --version
• hivecast doctor --json
• hivecast status output
• matrix invoke host.control runtime.list '{}' | jq .
• The last 200 lines of journalctl -u hivecast-host.service (or hivecast.mjs stderr for wrapper installs).
• The last 200 lines of any failing runtime's <home>/logs/runtimes/<id>/stderr.log.

Strip credentials before sharing — credentials/ files contain secret material per repo CLAUDE.md Rule 4.

See also

• Failure modes
• Backup
• Runtime health
• docs-hivecast/content/cli/exit-codes-and-diagnostics.md