Troubleshooting

Documented against OpenRig 0.5.14. Help text uses "node" where these pages say seat, for a seat's position in the running rig.

This is a revision of the existing troubleshooting page: it keeps that page's shape (the symptom, the surface that shows the truth, the recovery command) and adds the verbs the old page did not know about.

Start with the installation, not the rig

rig preflight asks whether this machine can run OpenRig at all. rig doctor verifies the install: packaged assets, Node, tmux, writable state paths and the daemon port; --spec compares a spec against the running rig of the same name. Both work without a running daemon.

rig preflight
rig doctor
rig doctor --spec ./rig.yaml

The daemon

rig daemon status says whether it is up; logs --follow reads what it tried and refused, in its own voice. stop has a shutdown budget and exits non-zero on an incomplete drain, so a non-zero stop is a fact to inspect, not a failure to retry blindly. After a reboot, rig start brings the daemon, the kernel rig and the rigs that were last running back in one move; --last, --all and --rigs are the headless forms. When the daemon is down, rig crash-cart emits the recovery verdict and discovery as JSON without changing anything, and bare rig opens the same recovery cockpit interactively.

rig daemon status
rig daemon logs --follow
rig start --last
rig crash-cart

A seat looks stuck

Read the record before the pane. rig parked diagnoses stopped seats that owe work; a held row is healthy only while its recorded wake is live. rig heartbeat shows whether in-flight work is being proven, and --nudge sends informational reminders without touching the rows. rig health lists read-only, explainable findings for a seat, a rig or the instance, with severity and status, and rig health explain <finding-id> shows the window, source, rule, evidence and confidence behind one. Empty output is never a healthy assertion. Then, and only then, tmux attach or rig capture the pane, and rig launch <rig> <seat> to relaunch one seat without disturbing the rest.

rig parked --rig my-rig
rig heartbeat --rig my-rig
rig health --rig my-rig
rig health explain <finding-id>
rig launch my-rig dev.impl

Help uses "node" where this page says seat, for a seat's position in the running rig.

Restore came back mixed

A restore is not all-or-nothing. Outcomes are reported per seat: resumed or rebuilt, started fresh or fresh-primed, waiting on a decision or attention, or failed. Mixed outcomes are normal output. Use rig ps --nodes for the live state of the current rig (-A for all rigs), then decide whether to keep a fresh seat, relaunch one, or restore again from a specific snapshot with rig restore-check first.

Service-backed rigs

For a rig that manages an application, rig env status <rig> is the honest health surface; rig env logs and rig env down follow. Do not infer environment truth from rig ps alone.

Last resort

rig destroy is the guarded destructive surface for bad local state: --state recreates an empty state root, --all also removes managed tmux sessions, --backup moves state aside instead of deleting it, and both --yes and --confirm destroy-openrig-state are required. It is the end of the list, not the start.

The web UI

rig ui open still exists as a verb. It is unmaintained and replaced by the terminal UI; never diagnose product behaviour from it.

The troubleshooting family

Command	What it does (from help)	Help source
rig crash-cart	Emit the daemon-down recovery verdict + discovery as JSON (read-only).	crash-cart.txt
rig daemon	Manage the OpenRig daemon	daemon.txt
rig daemon logs	Show daemon logs	daemon.logs.txt
rig daemon start	Start the daemon	daemon.start.txt
rig daemon status	Show daemon status	daemon.status.txt
rig daemon stop	Stop the daemon (10s shutdown budget; 12s process wait; incomplete drain exits nonzero)	daemon.stop.txt
rig destroy	Destroy OpenRig local state for recovery	destroy.txt
rig doctor	Verify OpenRig install health	doctor.txt
rig health	Inspect read-only, explainable system health records	health.txt
rig health checkpoint	Inspect or submit an outcome-boundary lineage census (not a per-edit ritual)	health.checkpoint.txt
rig health diagnose	Preview policy admission; --apply creates or re-presents bounded diagnostic context	health.diagnose.txt
rig health diagnosis	Read occurrences and record agent-owned dispositions	health.diagnosis.txt
rig health diagnosis list	List occurrence summaries; evidence payloads require --full	health.diagnosis.list.txt
rig health diagnosis notify	Explicitly request human delivery under policy and verified connector readiness	health.diagnosis.notify.txt
rig health diagnosis record		health.diagnosis.record.txt
rig health diagnosis show	Inspect current state and decisions; expand retained evidence deliberately	health.diagnosis.show.txt
rig health explain	Explain one health finding from its canonical bounded record	health.explain.txt
rig health policy	Inspect effective policy and engine state; apply edited JSON with --file	health.policy.txt
rig heartbeat	Show workflow execution proof state from queue files	heartbeat.txt
rig parked	Are we parked? Derived diagnosis: stopped seats owing work; HELD is healthy only while its recorded wake is live	parked.txt
rig preflight	Check system readiness for OpenRig	preflight.txt
rig start	Start the daemon, verify kernel, and restore rigs that were last running	start.txt
rig ui	UI commands	ui.txt
rig ui open	Open the OpenRig UI in the default browser	ui.open.txt
rig usage	Per-seat token telemetry over time (series + top-N burn) , facts for the oversight detector	usage.txt
rig usage series	raw per-seat usage samples, oldest first	usage.series.txt
rig usage top	top-N seats by token burn over the window	usage.top.txt

Where it goes next

• Continuity: snapshots, restore-check and handover.
• The terminal UI: the HEALTH tab shows the same findings rig health lists.

Read as Markdown