Exit codes and diagnostics

Present state — exit codes

The current hivecast wrapper uses a flat exit-code surface. Every error path in hivecast.mjs:1738-1789 calls console.error('Fatal error:', err); process.exit(1), and the unsupported-command path (hivecast.mjs:482-492) sets process.exitCode = 1 after writing to stderr.

Exit code	Meaning today	Where set
`0`	Success	command completed; no fatal error
`1`	Generic failure	every `catch (err) → process.exit(1)` and the unsupported-command path; also propagated when a delegated host-service CLI exits non-zero

There is no current distinction between transient errors (NATS unreachable, retry helpful) and config/data errors (corrupt runtime.json, bad CLI args, unrecoverable until human edits state). systemd unit policy can use RestartPreventExitStatus to avoid restart loops, but until exit codes are classified, that policy can't distinguish "retry me" from "I'm broken."

Target state — sysexits-style classification

A future revision should classify exit codes per sysexits.h:

Exit code	Constant	When
`0`	`EX_OK`	Success
`1`	`EX_GENERIC`	Generic / unclassified failure
`64`	`EX_USAGE`	Bad CLI args (unknown command, bad flag, malformed JSON payload)
`65`	`EX_DATAERR`	Corrupt persistent data we can't auto-fix (zero-byte / unparseable `runtime.json`, `host.json`) — DO NOT retry
`69`	`EX_UNAVAILABLE`	Upstream service down (NATS unreachable, cloud endpoint timeout) — retry OK
`75`	`EX_TEMPFAIL`	Temporary failure (network blip, lock contention) — retry OK
`78`	`EX_CONFIG`	Config file invalid (bad YAML in `host.json`, missing required field) — DO NOT retry

systemd unit hardening would then read:

ini

[Service]
Restart=on-failure
RestartPreventExitStatus=64 65 78
StartLimitBurst=5
StartLimitIntervalSec=60

…so configuration errors fail loudly instead of looping forever.

Source: WORKSTREAMS/launch-readiness-atomic-writes-and-bootstrap/ — Phase 6 (unit hardening) committed StartLimitBurst/RestartPreventExitStatus against hivecast-host.service and hivecast-nats.service. The exit-code classification side is filed but not yet implemented in hivecast.mjs. The bootstrap parse-and-skip change (commit 895a0688) eliminated the original "loud failure" pattern by recovering from corrupt records instead of exiting; remaining exit-code work is decoration without callers using the codes.

Diagnostics

`hivecast doctor`

The closest thing to a unified diagnostic command today:

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

What it checks (per runHostDoctor in hivecast.mjs):

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

Use --json for machine-readable output suitable for monitoring.

`hivecast seed`

Reports runtime-record health honestly (see hivecast host). Look for non-empty runtimeRecords.corrupt[] to identify zero-byte or unparseable records that would otherwise crash bootstrap.

Reading logs

Logs are not unified under hivecast logs — see hivecast up / down / logs for the current options:

bash

journalctl -u hivecast-host.service -f               # systemd-managed Host
tail -f <host-home>/logs/host.stdout.log             # non-systemd Host
tail -f <host-home>/logs/runtimes/<runtime-id>.stdout.log  # per-runtime

Common error signatures

Error message (verbatim)	Likely cause	Fix
`Failed to parse runtime.json: Unexpected end of JSON input`	A `runtime.json` is zero bytes (the original 22h crash-loop bug)	Fixed in current code — bootstrap now parses-and-skips; `hivecast seed` reports it; `hivecast start` self-heals
`Unsupported Host-mode hivecast command: <cmd>`	Subcommand doesn't exist	Run `hivecast --help`; if it's a package command, use `matrix` instead
`HiveCast operator command requires the source checkout`	Ran `hivecast operator <cmd>` against an installed wrapper, not against the matrix-work-harness checkout	Run from a source checkout; operator commands need `scripts/` from the harness
`Host Service command exited with signal SIGTERM`	A delegated `hivecast up` / `down` / `invoke` was killed externally	Inspect `journalctl -u hivecast-host.service` for the supervisor's view

Exit codes and diagnostics ​

Present state — exit codes ​

Target state — sysexits-style classification ​

Diagnostics ​

hivecast doctor ​

hivecast seed ​

Reading logs ​

Common error signatures ​

See also ​