@openrig/cli 0.5.2 → 0.5.3

package/daemon/context-packs/skills/core/rig-lifecycle/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: rig-lifecycle
+description: Use when reasoning about the rig lifecycle operations family (create / start / stop / resume / restore / snapshot / release / unclaim / destroy), reading or trusting `rig ps` / lifecycle projections after recovery, or designing proof for a lifecycle scenario. Covers the 4 failure modes (auto-restore creates partial rig; projections report healthier than reality; provider auth treated as impl work; resume succeeds for one runtime fails another) plus the restore-honesty rule (failed resume is FAILED loudly — no auto fresh fallback).
+metadata:
+  cli_surfaces_referenced:
+    - destroy
+    - down
+    - ps
+    - release
+    - restore
+    - restore-check
+    - resume
+    - snapshot
+    - unclaim
+    - up
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - topology-mutation-and-seat-management
+      - seat-scaling-and-specialization
+      - cross-host-rig-commands
+      - sidecar-operator
+      - rig-bundles-and-shareable-artifacts
+      - specification-system
+      - extension-and-user-workspace
+---
+
+# Rig Lifecycle
+
+The family of operations that **create, start, stop, resume, restore,
+snapshot, release, unclaim, and destroy** OpenRig-managed topologies.
+Includes the user story after reboot: **"bring my work back without
+turning a clean recovery into a cleanup project."**
+
+If lifecycle is brittle, every higher-level primitive inherits that
+brittleness. Queue, workflow, seat continuity, cross-host operation,
+and RSI all assume that rigs and seats can be restored into known
+states.
+
+## Use this when
+
+- Operating `rig up / down / restore / resume / snapshot / release / unclaim / destroy`
+- Reading `rig ps` after a reboot or recovery and deciding what to trust
+- Designing proof for a lifecycle scenario (clean start / warm resume / host reboot / provider auth loss / partial boot / operator recovery)
+- Reasoning about restore-outcome semantics (`resumed` / `rebuilt` / `fresh` / `failed` / `attention_required`)
+- Auditing whether a lifecycle proof is in-process bedrock vs requires real reboot evidence
+
+## Don't use this when
+
+- The operation is single-command and deterministic — use `openrig-user` skill for CLI surface
+- The work is operator-level configuration of OpenRig itself — use `openrig-operator`
+- The work is rig spec authoring — use `openrig-architect`
+
+## Failure modes (4)
+
+1. **Auto-restore creates a partially restored rig that must be cleaned up before real recovery.** Partial restore looks like recovery but isn't; cleanup-before-recovery becomes the actual workload.
+2. **`rig ps` or lifecycle projections report a healthier state than the runtime actually has.** Projections are summaries; the runtime is truth. Don't trust projections silently.
+3. **Provider auth is unavailable after reboot and the system treats that as implementation work** instead of a human/environment decision. Auth issues are environmental; route to human.
+4. **Resume succeeds for one runtime/provider but fails for another scenario that was never tested.** Per-runtime parity assumptions break silently; matrix proof catches them.
+
+## Restore-honesty rule (load-bearing)
+
+**Failed resume is FAILED loudly.** No automatic fresh fallback. Fresh
+launch is **explicit follow-up only.** This is enforced architecturally
+at the daemon level (per `architecture.md` §7 rule 15).
+
+The locked restore-outcome vocabulary:
+
+| Outcome | Meaning |
+|---|---|
+| `resumed` | Native runtime resumed the same conversation |
+| `rebuilt` | New process assembled from artifacts (`session_source: mode: rebuild`) |
+| `fresh` | New process with no prior continuity |
+| `failed` | Restore attempted and failed; no automatic fallback |
+| `attention_required` | Recoverable blocker (provider auth refused, etc.); needs operator action |
+| `n-a` | Not applicable (terminal nodes, etc.) |
+
+Codex auth-refusal returns `attention_required` (recoverable); Claude
+`looksLikeClaudeLoginPrompt` returns `failed/login_required` (terminal).
+Cross-runtime alignment is an open follow-up question.
+
+## Proof standard
+
+Lifecycle proof should include **real reboot or VM-reboot evidence**,
+not only daemon-unit evidence. The minimum useful matrix covers:
+
+| Scenario | What it proves |
+|---|---|
+| Clean start | Boot from spec into known state |
+| Warm resume | `rig down` → `rig up <name>` resumes seats |
+| Host reboot / tmux socket absence | Recovery from lost tmux connection |
+| Provider auth loss | Codex/Claude auth refusal handled honestly |
+| Partial boot / partial failure | Some seats up, some failed; honest reporting |
+| Intentional operator recovery | Operator-initiated restore from snapshot |
+
+Tier 1: in-process bedrock (daemon-unit evidence). Tier 2: real reboot
+or disposable Tart VM. Tier 1 alone is not lifecycle proof; it's
+bedrock.
+
+## Default policy is part of the primitive
+
+**Treat default policy as part of the primitive, not an afterthought.**
+Lifecycle defaults that are too optimistic for the reliability level
+actually proven create silent harm:
+
+- `auto-restore` defaults that mask failure modes
+- Implicit fresh-fallback that hides resume failure
+- Permissive verification that doesn't distinguish honest success from "appeared to work"
+
+## Total-Host Restore Product Rail v2
+
+The rail sequences restore truth into **four rungs**:
+
+- `fully_restored` is a **Rung 3 execution rollup**
+- "fully back" is **reserved for Rung 4 only**
+
+Naming discipline matters. "Fully restored" and "fully back" are
+different claims; don't conflate.
+
+## See also
+
+- `openrig-user` skill — CLI surface for `rig up / down / restore / etc.`
+- `openrig-operator` skill — operator-level discipline for OpenRig itself
+- `seat-continuity-and-handover` skill — sub-primitive: occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
+- `session-source-fork` skill — `forked` continuity outcome for fork-based restore
+- `permission-and-capability-preflight` skill — provider-auth blocker → escalation path
+- `openrig/docs/as-built/architecture/lifecycle-snapshot-restore.md` (product reference doc) — daemon enforcement of restore-honesty rule

package/daemon/context-packs/skills/core/rig-lifecycle/manifest.yaml

@@ -0,0 +1,9 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "rig-lifecycle"
+version: "0.5.3"
+purpose: "Use when reasoning about the rig lifecycle operations family (create / start / stop / resume / restore / snapshot / release / unclaim / destroy), reading or trusting `rig ps` / lifecycle projections after recovery, or designing proof for a lifecycle scenario. Covers the 4 failure modes (auto-restore creates partial rig; projections report healthier than reality; provider auth treated as impl work; resume succeeds for one runtime fails another) plus the restore-honesty rule (failed resume is FAIL"
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when reasoning about the rig lifecycle operations family (create / start / stop / resume / restore / snapshot / release / unclaim / destroy), reading or trusting `rig ps` / lifecycle projections after recovery, or designing proof for a lifecycle scenario. Covers the 4 failure modes (auto-restore creates partial rig; projections report healthier than reality; provider auth treated as impl work; resume succeeds for one runtime fails another) plus the restore-honesty rule (failed resume is FAIL"

package/daemon/context-packs/skills/core/session-source-fork/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: session-source-fork
+description: |
+  Use when authoring a rig spec member or `rig expand` payload that needs to start a new managed seat from a prior runtime conversation source — `session_source: { mode: fork, ref: { kind, value } }`. v1 supports `mode: fork` with `ref.kind: native_id` for Claude and Codex. The new seat persists a NEW post-fork token; the parent token is NEVER written onto the new seat. NOT for restoring an existing seat or for artifact-backed mental-model rebuild.
+metadata:
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - claude-compaction-restore
+      - mental-model-ha
+      - scope-recovery
+      - session-compaction-and-restore
+      - agent-startup-and-context-ingestion
+      - agent-starters
+      - composable-priming-packs
+      - seat-continuity-and-handover
+      - claude-compact-in-place
+      - pre-maintenance-agent-preservation
+---
+
+# session_source Fork
+
+`session_source` is a **member-level OpenRig field** that declares how a
+newly-launched managed seat should derive its initial conversation
+continuity from a prior runtime conversation source.
+
+v1 supports one mode: **`fork`** — start a *new* managed seat from a
+prior native runtime conversation source without claiming the original
+seat continued.
+
+The schema is runtime-neutral; implementation is runtime-specific (Claude
+and Codex have their own native fork commands).
+
+## Use this when
+
+- Authoring a rig spec member that should fork from a prior session
+- Authoring a `rig expand` payload with `session_source`
+- Reasoning about whether to use `fork` vs `rebuild` vs `resume` vs `fresh` for a new seat
+- Composing fork + handover (seat-handover-over-fork) — see `seat-continuity-and-handover` skill
+
+## Don't use this when
+
+- The seat is being **restored**, not created. Restore continues an existing managed seat. Fork creates a new seat.
+- The continuity is **artifact-backed mental-model rebuild** (packet-derived understanding, not native runtime continuity). Use `mode: rebuild` (see `seat-continuity-and-handover` for the rebuild surface) — do NOT collapse fork into artifact-backed reentry; the distinction is load-bearing.
+- The runtime is `terminal`. Terminal runtime rejects `session_source`.
+
+## The shape (canonical YAML)
+
+```yaml
+members:
+  - id: reviewer-2
+    runtime: claude-code        # or "codex"; not valid on terminal
+    agent_ref: specs/agents/reviewer.yaml
+    profile: reviewer
+    cwd: .
+    session_source:
+      mode: fork
+      ref:
+        kind: native_id          # v1 fork mode supports native_id only
+        value: "0b0165d7-cb4d-4650-90de-15c0a1ede9e6"
+```
+
+Rules:
+- `mode` v1 only valid value: `fork`.
+- `ref.kind` v1 supports `native_id` only. Schema rejects `artifact_path`, `name`, `last`, and `artifact_set` pre-launch with explicit deferred/weaker/wrong-mode error messages (see `packages/daemon/src/domain/rigspec-schema.ts` validateSessionSourceFork). Adapter-level refusal exists as defensive handling but should not be reachable in v1 because schema rejects first.
+- `value` required for `ref.kind: native_id` in v1 (the only schema-accepted kind). Future-state value semantics for `artifact_path` / `name` / `last` are not active in v1 because schema rejects those kinds pre-launch.
+- `rig expand` accepts the same shape so dynamically-added members can carry session-source attribution.
+
+The primitive does NOT introduce a new top-level command. It flows
+through existing rig spec and expansion pathways.
+
+## State model
+
+`session_source` is a **launch-time input**, not a long-lived stateful field:
+
+1. **Declared** — present in member config or expansion payload
+2. **Resolved** — at launch time, OpenRig resolves the `ref` against the runtime
+3. **Realized** — runtime fork succeeds; new managed seat receives a **NEW** native continuity token (Claude session id or Codex thread id). OpenRig persists that NEW token. **Parent token is NEVER written onto the new seat.**
+4. **Failed** — resolution or fork failed; seat not launched as a fork; clear error names the resolution step that failed
+
+Once realized, `session_source` is essentially history. Restoring the
+seat later is `restore` of the new seat, not re-fork-from-parent.
+
+## Failure modes (5)
+
+1. **Source session id not found** — runtime cannot resolve `native_id`. **Action**: emit error naming runtime + missing id; do NOT silently launch fresh. (Future-state note: when `artifact_path` is supported in a follow-up slice, it could become a candidate fallback for Claude; in v1 schema rejects `artifact_path` pre-launch so no fallback path exists.)
+2. **Source artifact path missing** *(out of v1 scope)* — would apply once `ref.kind: artifact_path` becomes schema-accepted. v1 schema rejects this kind pre-launch.
+3. **Unsupported runtime/kind combination** *(largely pre-empted in v1 by schema rejection)* — schema rejects all non-`native_id` kinds upfront. Adapter-level refusal exists as defensive handling but is not reached in v1.
+4. **Fork launch failed after source resolution** — runtime command (`claude --resume <parent> --fork-session` or `codex fork <id>`) returned non-zero or hung. Preserve runtime stderr; do not record new seat as launched; do not write parent token onto seat.
+5. **Persistence inconsistency** — fork succeeded but seat-token persistence cannot record new continuity token. **Internal failure**: seat is not considered launched until new token is durably written.
+
+## Honest UX rule (verbatim)
+
+The primitive must NOT report "restored the original agent" or "resumed
+the original seat" or "snapshot." The correct framing is **"forked from
+source session"** / **"started from prior conversation source."**
+
+Negative-grep over adapter source confirms ZERO `restored` / `resumed` /
+`snapshot` strings in fork code paths.
+
+## Hard boundaries (do-not list; verbatim)
+
+- **Do NOT introduce a DIVERGENT fork primitive.** The primitive flows through existing spec/expansion pathways. *(Update 2026-08-07: `rig fork <source-session>` has since shipped as a thin convenience verb that COMPOSES the existing agent-image fork path — this honors the boundary; it is not a divergent primitive. The rule now reads: no NEW fork mechanics outside the spec / expansion / agent-image pathways.)*
+- **Do NOT report "restored" / "resumed the original seat" / "snapshot"** in any UX surface.
+- **Do NOT couple `session_source` to AgentSpec.** It's a member-level launch-time input.
+- **Do NOT change `restore` semantics.** `session_source` creates a seat; `restore` continues an existing managed seat.
+
+## Adapter command shape (shipped v1)
+
+| Runtime | Command shape |
+|---|---|
+| Claude (`mode: fork` + `ref.kind: native_id`) | `claude --resume <parent-id> --fork-session` |
+| Codex (`mode: fork` + `ref.kind: native_id`) | `codex... fork <parent-id>` |
+| Terminal | Rejected at schema level |
+
+Mutual exclusion between `resumeToken` (restore path) and `forkSource`
+(fork path) is enforced at three layers in the daemon.
+
+## Continuity outcome literals
+
+| Outcome | When |
+|---|---|
+| `forked` | Fork succeeded; new seat has new native token; parent never written onto new seat |
+| `fresh` | Fresh launch (no `session_source` declared) |
+| `resumed` | Restore of existing managed seat |
+| `failed` | Resolution or fork failed |
+
+For `seat handover over fork` composition, the binding outcome is
+independent (see `seat-continuity-and-handover` skill).
+
+## Active-daemon caveat (live-runtime gap)
+
+2026-04-30 live scale-out dogfood found: source checkout contained fork
+support, but active daemon was running from a pre-fork commit. **Verify
+the active daemon/runtime commit contains the fork path before live
+proof.** Isolated daemon proof at the target commit can prove the
+feature safely; live forked scale-out remains unproven until the active
+daemon parity is verified.
+
+## Currently shipped (v1) vs deferred
+
+Shipped at openrig `c7b6df1` (2026-04-30):
+- Schema accept/reject for full Honest Refusal Matrix
+- Codec roundtrip (serialize → parse → normalize preserves `session_source` faithfully)
+- Expansion path through `rig expand` member-input
+- Adapter command shape for Claude + Codex `native_id`
+- Persistence honesty (seat's `resume_token` is the NEW post-fork token; parent token NEVER written)
+- Honest UX literal contract (`continuityOutcome: forked`)
+
+Deferred:
+- Tier 2 real-runtime fork proof (disposable Tart VM cycle, human-gated)
+- Claude `artifact_path` mode (schema currently refuses with deferred message)
+- Provenance columns (`parent_native_id` / `created_via` for queryable RSI consumer)
+- Cross-host fork (source on host A, new seat on host B) — depends on `cross-host-rig-commands`
+
+## See also
+
+- `seat-continuity-and-handover` skill — sibling occupant-creation primitives (resume / fork / rebuild / fresh) + seat-binding (handover composes with fork)
+- `agent-starters` skill — composes session_source fork into named reusable starting points
+- `cross-host-rig-commands` skill — multi-host fork (deferred)

package/daemon/context-packs/skills/core/session-source-fork/manifest.yaml

@@ -0,0 +1,9 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "session-source-fork"
+version: "0.5.3"
+purpose: "Use when authoring a rig spec member or `rig expand` payload that needs to start a new managed seat from a prior runtime conversation source — `session_source: { mode: fork, ref: { kind, value } }`. v1 supports `mode: fork` with `ref.kind: native_id` for Claude and Codex. The new seat persists a NEW post-fork token; the parent token is NEVER written onto the new seat. NOT for restoring an existing seat or for artifact-backed mental-model rebuild."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when authoring a rig spec member or `rig expand` payload that needs to start a new managed seat from a prior runtime conversation source — `session_source: { mode: fork, ref: { kind, value } }`. v1 supports `mode: fork` with `ref.kind: native_id` for Claude and Codex. The new seat persists a NEW post-fork token; the parent token is NEVER written onto the new seat. NOT for restoring an existing seat or for artifact-backed mental-model rebuild."

package/daemon/context-packs/skills/core/specification-system/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: specification-system
+description: Use when authoring rig specs, agent specs, workflow specs, startup/context fragments, operating-mode declarations, or designing the user spec library. Covers the 4 failure modes (spec instantiates topology but not workflow/mode; spec depends on local paths and fails on another host; agents modify specs as one-off files instead of preserving reusable intent; validation proves YAML shape but not whether topology can run) and the validation-vs-runtime-realization distinction.
+metadata:
+  cli_surfaces_referenced:
+    - agent
+    - bundle
+    - spec
+    - specs
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - rig-lifecycle
+      - topology-mutation-and-seat-management
+      - seat-scaling-and-specialization
+      - cross-host-rig-commands
+      - sidecar-operator
+      - rig-bundles-and-shareable-artifacts
+      - extension-and-user-workspace
+---
+
+# Specification System
+
+The declarative primitive family for OpenRig intent: **rig specs, agent
+specs, workflow specs, startup/context fragments, operating-mode
+declarations, and the user spec library that stores and reuses them.**
+
+Specs are how humans and agents describe **repeatable topology and
+behavior** without re-explaining it in chat. They are also shareable
+artifacts: a user should be able to publish a spec or spec family so
+another user can instantiate the same rig shape, role structure, or
+workflow pattern.
+
+**Without a dependable spec primitive, OpenRig depends on manual
+startup prompts and tribal memory.** That blocks repeatability, product
+demos, rig bundles, and autonomous rig construction.
+
+## Use this when
+
+- Authoring a RigSpec / AgentSpec / workflow spec
+- Designing a startup/context fragment
+- Reasoning about spec-library lifecycle (validation, sharing, upgrade semantics)
+- Auditing a spec for portability (does it run on another host?)
+- Distinguishing spec vs bundle vs extension cleanly
+
+## Don't use this when
+
+- The work is one-off and won't be reused. Manual rig assembly is fine for one-shot work.
+- The intent is to package a topology + workflow as a shareable artifact. That's `rig-bundles-and-shareable-artifacts`.
+- The intent is to add runtime behavior. That's `extension-and-user-workspace`.
+
+## Failure modes (4)
+
+1. **A spec can instantiate a topology but not the workflow or operating mode needed to use it.** Topology is necessary but not sufficient — workflow and operating mode must be declared too.
+2. **A shared spec depends on local paths or hidden startup fragments and fails on another host.** Specs must be self-describing for portability.
+3. **Agents modify specs as one-off files instead of preserving reusable user/library intent.** Specs are reusable; treating each instance as one-off destroys the primitive's value.
+4. **Validation proves YAML shape but not whether the declared topology can actually run.** Structural validation is not enough; runtime realization is the real proof.
+
+## Proof standard
+
+Proof should:
+
+1. Author a spec
+2. Validate it (structural)
+3. Install it (into spec library)
+4. Instantiate it on a **clean OpenRig environment**
+5. Show **both structural validation AND runtime realization**
+
+Validation alone is insufficient.
+
+## Spec / bundle / extension boundary
+
+| Concept | Declares | Example |
+|---|---|---|
+| **Spec** | Topology / role / workflow shape (declarative intent) | `rig.yaml`, `agent.yaml`, `workflow.yaml` |
+| **Bundle** | Spec(s) + supporting fragments packaged for shareable instantiation | A Velocity Team bundle |
+| **Extension** | Runtime behavior added to user workspace | RigX command, custom view |
+
+Don't conflate them. The contract should distinguish spec, bundle, and
+extension cleanly.
+
+## Currently shipped surfaces
+
+OpenRig already has:
+
+- RigSpec / AgentSpec authoring (`agent.yaml`, `rig.yaml` formats; see `openrig-architect` skill)
+- Workflow specs (markdown/YAML files, daemon read-through cache via `workflow_specs` table; see `workflow-runtime` skill)
+- Bundle/spec command surface (`rig bundle / spec / agent / specs ls/show/preview/add/sync/remove/rename`)
+- Spec library (filesystem-backed at `packages/daemon/specs/` + `~/.openrig/specs/` per cli-reference.md)
+
+Not yet shipped:
+- Spec library lifecycle (validation, sharing, upgrade) treated as a first-class primitive
+- Cross-host spec sharing
+- Marketplace / public registry
+
+## See also
+
+- `openrig-architect` skill — RigSpec / AgentSpec authoring discipline
+- `workflow-runtime` skill — workflow spec authoring + transactional-scribe contract
+- `rig-bundles-and-shareable-artifacts` skill — bundle is the packaged form of specs
+- `extension-and-user-workspace` skill — extensions add runtime behavior; specs declare intent
+- `openrig/docs/reference/rig-spec.md` (product reference doc) — RigSpec format specification
+- `openrig/docs/reference/agent-spec.md` (product reference doc) — AgentSpec format specification

package/daemon/context-packs/skills/core/specification-system/manifest.yaml

@@ -0,0 +1,9 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "specification-system"
+version: "0.5.3"
+purpose: "Use when authoring rig specs, agent specs, workflow specs, startup/context fragments, operating-mode declarations, or designing the user spec library. Covers the 4 failure modes (spec instantiates topology but not workflow/mode; spec depends on local paths and fails on another host; agents modify specs as one-off files instead of preserving reusable intent; validation proves YAML shape but not whether topology can run) and the validation-vs-runtime-realization distinction."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when authoring rig specs, agent specs, workflow specs, startup/context fragments, operating-mode declarations, or designing the user spec library. Covers the 4 failure modes (spec instantiates topology but not workflow/mode; spec depends on local paths and fails on another host; agents modify specs as one-off files instead of preserving reusable intent; validation proves YAML shape but not whether topology can run) and the validation-vs-runtime-realization distinction."

package/daemon/context-packs/skills/core/topology-mutation-and-seat-management/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: topology-mutation-and-seat-management
+description: Use when changing a rig while it is alive — `rig expand` / `rig shrink` / `rig launch` / `rig remove` / `rig discover` / `rig bind` / `rig adopt` / `rig attach`. Covers the 4 failure modes (newly created seat lacks queue/startup/role; edges and permissions not updated; adopt/bind succeeds at tmux but not OpenRig identity; shrink/remove leaves stale topology references) and the rule that mutation must work while the rig is active, not just in clean fixtures.
+metadata:
+  cli_surfaces_referenced:
+    - adopt
+    - attach
+    - bind
+    - discover
+    - expand
+    - launch
+    - ps
+    - release
+    - remove
+    - shrink
+    - unclaim
+    - up
+    - whoami
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - rig-lifecycle
+      - seat-scaling-and-specialization
+      - cross-host-rig-commands
+      - sidecar-operator
+      - rig-bundles-and-shareable-artifacts
+      - specification-system
+      - extension-and-user-workspace
+---
+
+# 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.
+
+## Proof standard
+
+Proof must cover **mutation while a rig is active**, not just in a
+clean test fixture. The useful matrix:
+
+| Operation | What to verify |
+|---|---|
+| Add seat | New seat has queue, startup context, role; `rig whoami` resolves it |
+| Remove seat | Stale references cleaned; edges/permissions updated |
+| Adopt existing session | tmux session bound at OpenRig identity layer; `rig whoami` reports correctly |
+| Attach observer terminal | External CLI attachment recorded |
+| Verify topology projections after each move | `rig ps --nodes` reflects current truth, not pre-mutation cache |
+
+A clean-fixture proof is necessary but not sufficient. Live-rig proof
+catches the failure modes that fixture-mode misses.
+
+## Why important strategically
+
+The current coordination experiments repeatedly need new queues,
+watchdogs, humans, and test seats — which makes this family
+**strategically important.** Seat continuity work will eventually
+separate stable seat identity from runtime occupant identity (see
+`seat-continuity-and-handover`).
+
+## Currently shipped surfaces
+
+Per `cli-reference.md` v0.2.0:
+
+- `rig expand <rig-id> <pod-fragment-path>` (with optional `session_source`)
+- `rig shrink <rigId> <podRef>`
+- `rig launch <rigId> <nodeRef>`
+- `rig remove <rigId> <nodeRef>`
+- `rig discover [--draft]`
+- `rig bind <discoveredId> --rig <rigId> (--node <id> | --pod <ns> --member <name>)`
+- `rig adopt <path> --bind <logicalId=tmuxSessionOrDiscoveryId>`
+- `rig attach --self --rig <rigId> --node <logicalId>`
+- `rig unclaim <sessionRef>` / `rig release <rigId>`
+
+## Active proof gap (current)
+
+The 2026-04-30 topology mutation add-seat proof pass is **active**.
+Product Lab shaped it; planner authored `IMPLEMENTATION.md`; driver
+landed the smallest honest CLI retry-guidance patch for failed
+`rig expand` recovery. **Remaining proof is the Section B disposable-rig
+runtime matrix, blocked on operator posture** and owned by
+`orch-lead@your-rig`.
+
+## See also
+
+- `openrig-user` skill — CLI surface for `rig expand / shrink / launch / remove / bind / adopt / attach`
+- `seat-scaling-and-specialization` skill — when to add specialized capacity vs generic
+- `seat-continuity-and-handover` skill — replacing an occupant on a stable seat (different shape than topology mutation)
+- `cross-host-rig-commands` skill — cross-host topology mutation (deferred)

package/daemon/context-packs/skills/core/topology-mutation-and-seat-management/manifest.yaml

@@ -0,0 +1,9 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "topology-mutation-and-seat-management"
+version: "0.5.3"
+purpose: "Use when changing a rig while it is alive — `rig expand` / `rig shrink` / `rig launch` / `rig remove` / `rig discover` / `rig bind` / `rig adopt` / `rig attach`. Covers the 4 failure modes (newly created seat lacks queue/startup/role; edges and permissions not updated; adopt/bind succeeds at tmux but not OpenRig identity; shrink/remove leaves stale topology references) and the rule that mutation must work while the rig is active, not just in clean fixtures."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when changing a rig while it is alive — `rig expand` / `rig shrink` / `rig launch` / `rig remove` / `rig discover` / `rig bind` / `rig adopt` / `rig attach`. Covers the 4 failure modes (newly created seat lacks queue/startup/role; edges and permissions not updated; adopt/bind succeeds at tmux but not OpenRig identity; shrink/remove leaves stale topology references) and the rule that mutation must work while the rig is active, not just in clean fixtures."