Continuity: seats that outlive their sessions
Documented against OpenRig 0.7.7. 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; --existing --fresh <seats...> deliberately fresh-primes the named seats instead of resuming them, and the result is reported per seat. On a terminal, rig up asks yes or no for each seat it could not resume; answering no, the default, starts nothing for that seat.
rig down my-rig --snapshot
rig up my-rig
rig up my-rig --existing --fresh dev.qa
Check 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 (with or without caveats), 1 is not, 2 is unknown. rig restore refuses a rig that still has live sessions; stop it with rig down first.
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.
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 <seat> runs the guided compaction for one Claude seat now: prepare, /compact, restore, audit. --state shows where it stands, and --cancel disarms a prepared or pending step, though it can't undo a /compact already submitted. The order matters because compaction is a lossy event that only the compacted seat knows happened. rig seat set-terminal-policy decides who else may compact a seat or change its model (Messaging has the presets). 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.
rig seat history --rig <id> --node-id <id> lists the Claude and Codex conversations a seat could resume, read-only. Resuming the one a person chose goes through the daemon's startup review, for a client; there's no rig command for it yet. Other rig seat verbs change what a seat's next launch uses: set-runtime moves a live seat to the other runtime, successor first; set-cwd saves its working directory; set-effort saves its reasoning effort, and effort shows it four ways; restart restarts a Codex seat in place so it reads its account again.
| 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 |
Reconcile seat attention using the checks for its attention class | seat.clear-attention.txt |
rig seat continue |
Deliver pending startup context to the same fresh or forked conversation | seat.continue.txt |
rig seat effort |
Show one seat's effort four ways: requested, saved, sent at launch, and what the native session records | seat.effort.txt |
rig seat handover |
Hand a seat to a successor (two-phase). Pass --dry-run to plan without changing topology. | seat.handover.txt |
rig seat held-messages |
Read retained messages outside the protected terminal; reading never delivers them | seat.held-messages.txt |
rig seat history |
List or validate captured histories eligible for a resume attempt (read-only) | seat.history.txt |
rig seat launch |
Launch a deliberate fresh occupant for exactly one existing seat | seat.launch.txt |
rig seat restart |
Restart one Codex seat in place so it reads its Codex home's current account | seat.restart.txt |
rig seat retire-held-message |
Release one held message's active quota, preserving evidence; does not deliver or close work | seat.retire-held-message.txt |
rig seat set-cwd |
Save an existing seat's working directory for its next fresh launch or rebuild handover | seat.set-cwd.txt |
rig seat set-effort |
Save one seat's reasoning effort for its next managed continuation (audited); no restart | seat.set-effort.txt |
rig seat set-permissions |
Select native permissions for future managed launches; no relaunch or work-posture change | seat.set-permissions.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 set-runtime |
Move a live Codex or Claude Code seat to the other runtime, successor first | seat.set-runtime.txt |
rig seat set-terminal-policy |
Choose terminal interventions; managed compaction and saved model/effort changes are checked | seat.set-terminal-policy.txt |
rig seat set-typing-guard |
Choose how this seat's typing guard handles automatic input | seat.set-typing-guard.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: tasks that stay assigned across all of the above.