topology-mutation-and-seat-management

Topology Mutation and Seat Management

The ability to change a rig while it is alive: expand, shrink, launch, remove, discover, bind, adopt, and attach seats or sessions. Seat management includes the stable identifiers, edges, roles, and startup context that make those mutations coherent.

OpenRig should be easy to reach for. A user should be able to add capacity, retire capacity, adopt an existing session, or attach a terminal without rebuilding the whole topology. If mutation is rarely tested, users avoid it and the product collapses back into static launch scripts.

Use this when

• Adding capacity to a running rig (rig expand <rig> <pod-fragment-path>)
• Removing capacity (rig shrink / rig remove)
• Launching/relaunching a node in a running rig (rig launch)
• Binding a discovered session into an existing logical node (rig bind)
• Adopting a topology + binding live sessions (rig adopt)
• Attaching a shell or agent into a rig node (rig attach --self)

Don't use this when

• The rig is being created fresh from scratch — use rig up (lifecycle, not mutation)
• The intent is to scale specifically (add specialized capacity) — use seat-scaling-and-specialization skill
• The intent is occupant replacement on a stable seat — use seat-continuity-and-handover skill

Failure modes (4)

1. A newly created seat lacks the queue, startup context, or role files it needs to operate. Topology mutation creates the seat, but the seat needs more than a tmux session to be useful.
2. Edges and permissions are not updated when a seat is added or removed. Topology references go stale; later workflows route to nonexistent seats.
3. Adopt/bind succeeds at the tmux/session layer but not at the OpenRig identity layer. The session is attached but rig whoami doesn't know about it; downstream consumers see partial state.
4. Shrink/remove leaves stale topology references that later workflows route into. Cleanup is part of the operation, not an afterthought.