Appearance
Continuity: seats that outlive their sessions
Documented against OpenRig 0.5.14. Help text uses "node" where these pages say seat, for a seat's position in the running rig.
What it is for
Closing the window does not end a session; the tmux session keeps running while the machine does. A session ends when its process exits, when its context fills, or when the machine restarts. A seat survives all three. Continuity is the set of verbs that keep the seat's name, role and accumulated context across those events: snapshots and restores for a whole rig, handover for one seat's occupant, compaction planning for seats near their context wall, agent images for starting a new seat from a known-good one, and restore packets for carrying what a seat knows across a runtime change.
Restore is honest by design. It reports a per-seat outcome rather than a promise: a seat can be resumed, rebuilt, started fresh or fresh-primed, left waiting on a decision or attention, or failed. A fresh start is something an operator chooses; it is never dressed up as a recovery.
The three verbs you will use first
Stop the rig, then bring it back by name. Stopping a running rig attempts a snapshot before teardown; snapshot failures are reported but do not stop the teardown, and an already-stopped rig does not take another snapshot through this path. --snapshot states the intent explicitly. rig up <name> brings the rig back; --fresh deliberately fresh-primes named seats instead of resuming them, and the result is reported per seat.
bash
rig down my-rig --snapshot
rig up my-rig
rig up my-rig --fresh dev.qaCheck before you restore.rig restore-check says what would come back across running rigs and, for anything that would not, which check fails. Exit 0 is restorable, 1 is not, 2 is unknown.
bash
rig restore-check
rig restore-check --rig my-rig
rig restore <snapshotId> --rig <rigId>Replace one seat's occupant, keep the seat.rig handover <seat> creates a successor, delivers context, verifies continuity and rebinds, with the seat's name, edges and inbound work unchanged. Sources are fresh (default), discovered:<id>, fork:<id> for a native fork of the incumbent conversation, or rebuild from the seat's durable artifacts. Use --dry-run to inspect the plan; without it, both rig handover and rig seat handover perform the handover. A reason is required, and a source that cannot proceed refuses before any mutation.
bash
rig handover dev-impl@my-rig --reason "context wall" --dry-run
rig handover dev-impl@my-rig --source fork:<id> --reason "context wall"Identifiers
rig handover and rig seat take a seat's canonical session address, pod-member@rig (for example dev-impl@my-rig), or a logical seat ref; rig launch and --fresh take the logical id pod.member (for example dev.impl). The Lifecycle page has the full mapping.
The rest of the family
rig seat status <seat> shows what the system believes about a seat's handover state; rig seat handover runs the same handover action as the top-level verb (help uses "node" where this page says seat, for a seat's position in the running rig). rig compact-plan lists Claude seats near their context threshold without compacting anything; rig compact acts on that plan, and the order matters because compaction is a lossy event that only the compacted seat knows happened. rig agent-image create <session> captures a productive seat's resumable state so a new seat can start from it; images can be listed, shown, previewed, pinned, pruned and deleted under an evidence-preservation guard. rig restore-packet write captures what a seat knows into a portable artifact when it must die or move runtimes.
| Command | What it does (from help) | Help source |
|---|---|---|
rig agent-image | Browse, snapshot, and manage agent images (PL-016) | agent-image.txt |
rig agent-image create | Capture a productive seat's resumable state into a new agent image | agent-image.create.txt |
rig agent-image delete | Delete an agent image (subject to evidence-preservation guard) | agent-image.delete.txt |
rig agent-image list | List all agent images in the library | agent-image.list.txt |
rig agent-image pin | Pin an image so prune cannot delete it | agent-image.pin.txt |
rig agent-image preview | Show manifest + sized supplementary file metadata + starter snippet | agent-image.preview.txt |
rig agent-image prune | Delete evictable images (protected by evidence-preservation guard) | agent-image.prune.txt |
rig agent-image show | Show image manifest + statistics | agent-image.show.txt |
rig agent-image sync | Re-walk discovery roots and refresh the library index | agent-image.sync.txt |
rig agent-image unpin | Unpin an image | agent-image.unpin.txt |
rig compact | Manually run the guided compaction sequence (prep → /compact → restore → audit) for one Claude seat | compact.txt |
rig compact-plan | Plan Claude compact-in-place candidates without compacting anything | compact-plan.txt |
rig handover | Hand a seat to a successor: create -> deliver context -> verify continuity -> rebind | handover.txt |
rig restore | Restore a rig from a snapshot | restore.txt |
rig restore-check | Check restore readiness across running rigs | restore-check.txt |
rig restore-packet | Generate, read, and validate cross-runtime restore packets per the v0 standard | restore-packet.txt |
rig restore-packet read | Render a restore packet contents (human or --json) | restore-packet.read.txt |
rig restore-packet validate | Validate a restore packet against the v0 schema | restore-packet.validate.txt |
rig restore-packet write | Generate a restore packet from a source session or JSONL file | restore-packet.write.txt |
rig restore status | Show the derived current receipt for one restore attempt | restore.status.txt |
rig seat | Inspect OpenRig seat observability state | seat.txt |
rig seat clean | Return a DEAD seat to launchable (clears stale binding + session records; audited) | seat.clean.txt |
rig seat clear-attention | Clear stuck attention_required startup status with evidence or operator attestation | seat.clear-attention.txt |
rig seat handover | Plan a safe two-phase seat handover (help text as printed; on 0.5.14 this performs the handover exactly like rig handover, and only --dry-run plans: EFFECT-CHECKS.md) | seat.handover.txt |
rig seat launch | Launch a deliberate fresh occupant for exactly one existing seat | seat.launch.txt |
rig seat set-model | Persist a seat's model id (audited); subsequent managed resumes use the new model | seat.set-model.txt |
rig seat set-resume-token | Set a managed seat's durable resume token (token read from stdin; attested + audited) | seat.set-resume-token.txt |
rig seat status | Show read-only seat handover observability status | seat.status.txt |
rig seat stop | Stop exactly one LIVE managed seat (kills only that seat's tmux session; audited) | seat.stop.txt |
rig seat switch-client | Retarget an attached tmux client's view to the seat's canonical session (view-only) | seat.switch-client.txt |
rig snapshot | Manage rig snapshots | snapshot.txt |
rig snapshot list | List snapshots for a rig | snapshot.list.txt |
What it does not do
- It does not promise recovery. Every restore reports the outcome per seat and never smooths a failure into a success.
- Compaction is not an unblock. On some runtimes what comes back believes it knows everything and does not; plan first, compact deliberately, and tell the fleet.
- Neither handover verb is a plan by default.
--dry-runis the plan; everything else performs. - A snapshot records the topology roster it saw;
--intended-seatslets a later restore judge which historical seats are still intended rather than treating every one as current.
Where it goes next
- Lifecycle: bringing a rig up, growing it and taking seats out while it runs.
- Troubleshooting: what to do when the daemon, tmux or a seat disagrees with the record.
- Coordination: the rows that keep their owner across all of the above.