Seat Continuity and Handover

Seat Continuity and Handover

A pair of primitive families that separate who is sitting in a seat from what the seat itself is:

1. Occupant-creation primitives — resume, fork, rebuild, fresh — produce a candidate new occupant. Answer: "where did the new occupant come from?"
2. Seat-binding operations — handover binds a candidate occupant into the topology. Answer: "what happened to the stable seat identity?" Inspect the current CLI for executable operations; design vocabulary alone does not establish a command.

Core architectural decision: stable seat identity, fluid occupant identity, explicit provenance. Do not encode successive occupants into live seat names. Keep the stable address and record lineage separately.

Use this when

• Replacing a seat's occupant via rebuild, fork, fresh, or seat-handover
• Choosing old-occupant disposition: retire / advise / shadow
• Reasoning about whether a seat's lineage is stable or has drifted
• Reading or writing the provenance record for a seat
• Designing or auditing topology stability across an occupant change

Don't use this when

• The seat is freshly created (no occupant to replace) — use rig launch / rig expand directly
• The intent is to change topology shape (add/remove seats), not replace an occupant — use topology-mutation primitives

The two-outcome honesty model

Every seat-binding operation produces two independent outcomes:

continuityOutcome: rebuilt | resumed | forked | fresh | failed
seatBindingOutcome: handed_over | partial | failed | unchanged

These can disagree honestly. Examples:

• continuityOutcome: failed + seatBindingOutcome: unchanged — new occupant didn't materialize; seat correctly retains old occupant.
• continuityOutcome: rebuilt + seatBindingOutcome: failed — candidate created OK; bind failed mid-flight; provenance records the gap.

Don't collapse these into one outcome. The system can describe what actually happened only if the two are recorded independently.

Provenance record (durable, queryable)

Every handover writes:

• seat id
• old occupant id
• new occupant id
• creation mode (resume/fork/rebuild/fresh)
• source artifacts used
• whether old occupant remains alive as advisor/shadow
• operator or loop that initiated the motion
• timestamp
• result (handed_over / partial / failed)

This is the system's truth-source for "how did the current occupant get there." Without it, the control plane shows the current occupant but not the legitimacy of the transition.

State models — independent

Occupant-creation state (per candidate)

1. Requested — input to rebuild/fork/fresh/resume
2. Realized — runtime/artifact path produced an occupant with managed-seat shape
3. Failed — candidate didn't materialize; continuityOutcome: failed

Seat-binding state (per seat)

1. Stable — current occupant attached, no in-flight binding
2. Binding — handover in progress
3. Bound — handover succeeded; provenance record written
4. Unchanged — bind failed before completion; seat retains old occupant

A seat stays Stable even if multiple candidate-occupants were produced and discarded.

Failure modes (5)

1. Candidate creation failed — rebuild couldn't synthesize from artifacts; fork couldn't resolve session_source; fresh couldn't launch. Action: bind operation does not begin; seat unchanged; provenance records the failed candidate-creation step.
2. Old occupant cannot be detached cleanly — runtime hung, tmux locked, etc. Action: bind halts mid-flight; seat enters Binding state with explicit "halted" sub-status; operator alerted. Do NOT auto-rollback by reattaching old-occupant if detach didn't complete cleanly.
3. Bind succeeded but provenance write failed — disk/db error. Action: not durable until provenance writes; treat as Binding halted, not Bound.
4. Old occupant disposition unfulfillable — operator requested advise (keep alive as advisor) but runtime can't keep old alive. Action: degrade to retire with explicit notification, OR fail if operator passed strict-disposition flag.
5. Concurrent handover attempts — two operations target the same seat. Action: serialize by seat-id lock; second attempt refuses with clear error.

Hard boundaries (do-not list; verbatim)

• Do NOT collapse rebuild and seat handover into one primitive. The design specifically separates them so the system can describe what actually happened.

• Do NOT introduce successor-suffix seat names (lead2/lead3). Stable seat identity is the architectural goal. The live address stays stable. A retired tenure is distinguished by its ledger generation and exact history token; preserving it does not require a renamed live pane.

• Do NOT report seatBindingOutcome: handed_over if the provenance record didn't write durably.

• Do NOT auto-rollback a half-completed handover by re-attaching the old occupant unless detach completed cleanly first.

Composition and current command surface

A fork can create a candidate occupant; handover binds it into an existing seat. The continuity outcome is forked; the binding outcome is independent.

The packaged rig handover <seat> and rig seat handover <seat> accept fresh, discovered:<id>, fork:<id> and rebuild sources. Use --dry-run to request planning only. Without it, these surfaces can execute; do not infer read-only behavior from the shorter seat command's planning-oriented description. rig seat status <seat> is the read-only observability surface.

Source support is declared by the running daemon and depends on actual identity, history and artifact prerequisites. Read the returned source, continuity, binding and provenance results independently. A help listing or dry-run is not proof of a successful transition. The linked cutover SOP supplies the operator mechanics and required effect checks after the named owner authorizes the action.