# 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.

```
rig down my-rig --snapshot
rig up my-rig
rig up my-rig --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, 1 is not, 2 is unknown.

```
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` 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.

[//]: # (table:start)
| 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 |

[//]: # (table:end)

## 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-run` is the plan; everything else performs.
- A snapshot records the topology roster it saw; `--intended-seats` lets a later restore judge which historical seats are still intended rather than treating every one as current.

## Where it goes next

- [Lifecycle](/docs/lifecycle): bringing a rig up, growing it and taking seats out while it runs.
- [Troubleshooting](/docs/troubleshooting): what to do when the daemon, tmux or a seat disagrees with the record.
- [Coordination](/docs/coordination): the rows that keep their owner across all of the above.