# 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 ` 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 ` 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 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 ` 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 [//]: # (table:start) | 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 | [//]: # (table:end) ## Where it goes next - [Continuity](/docs/continuity): snapshots, restore-check and handover. - [The terminal UI](/docs/tui): the HEALTH tab shows the same findings `rig health` lists.