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