@openrig/cli 0.4.6 → 0.4.7

package/daemon/specs/agents/shared/skills/core/rig-bundles-and-shareable-artifacts/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: rig-bundles-and-shareable-artifacts
+description: Use when authoring or installing a rig bundle (packaged, shareable artifact that instantiates an opinionated OpenRig topology + workflow), reasoning about the bundle vs extension boundary, or auditing a bundle for portability. Covers the 4 failure modes that prevent bundles from working anywhere but the operator's machine, and the inspect-before-install discipline.
+metadata:
+  cli_surfaces_referenced:
+    - bundle create
+    - bundle inspect
+    - bundle install
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - rig-lifecycle
+      - topology-mutation-and-seat-management
+      - seat-scaling-and-specialization
+      - cross-host-rig-commands
+      - sidecar-operator
+      - specification-system
+      - extension-and-user-workspace
+---
+
+# Rig Bundles and Shareable Artifacts
+
+A **rig bundle** is a packaged, shareable artifact that can instantiate
+an opinionated OpenRig topology and workflow. It may include:
+
+- rig specs
+- agent specs
+- workflow specs
+- startup files
+- skills or skill references
+- operating-mode declarations
+- proof expectations
+- supporting fragments
+
+**Shareable artifact** is broader than bundle: specs, bundles, skills,
+workflows, and extensions can all be shared. A bundle is the packaged
+form for "load this topology and way of working."
+
+## Use this when
+
+- Authoring a bundle from a proven lab pattern
+- Installing a bundle (`rig bundle install <path>`)
+- Inspecting a bundle before install (`rig bundle inspect <path>`)
+- Reasoning about bundle vs extension boundary (bundle declares topology + workflow; extension adds behavior)
+- Auditing a bundle for portability — does it work on a clean OpenRig environment, or only the author's machine?
+
+## Don't use this when
+
+- The work is a one-off topology you won't reuse. Specs alone are sufficient.
+- The intent is to add runtime behavior (commands, views, dashboards). Use `extension-and-user-workspace`, not bundles.
+- You want to ship a workflow as a daemon feature. Bundle is the path *before* daemon promotion.
+
+## The bundle vs extension boundary (load-bearing)
+
+| Concept | Declares | Example |
+|---|---|---|
+| **Bundle** | Rig shape + workflow ("load this topology and way of working") | A Velocity Team bundle |
+| **Extension** | Behavior added to user workspace/runtime | A custom command, view, or dashboard |
+
+Don't confuse them. A bundle is *opinionated content*; an extension is
+*added behavior*. Both can be shareable artifacts, but they're
+structurally distinct.
+
+## Failure modes (4)
+
+1. **A bundle works only on the operator's machine** because paths, providers, or credentials are implicit. Bundles must be self-describing for a clean OpenRig environment.
+2. **A bundle includes too much local state and becomes a backup archive instead of a reusable artifact.** Bundle is the *intended shape*, not the current state of one specific install.
+3. **A bundle declares topology but omits proof expectations or workflow mode.** Topology alone doesn't tell users what "working as advertised" means.
+4. **Users cannot inspect what a bundle will create before installing it.** `rig bundle inspect` must show what will be created without side effects.
+
+## Proof standard
+
+Proof should:
+
+1. Install the bundle into a **clean OpenRig environment**
+2. Instantiate it
+3. Verify the expected seats and workflow mode
+4. Run a small smoke proof that the topology behaves as advertised
+
+## Bundle path → product
+
+Bundles are how proven lab patterns become reusable product experiences:
+
+```
+local dogfood pattern
+  → bundle (with manifest, parameterization, proof expectations)
+  → installed by another user on clean OpenRig
+  → opinionated workflow shipped without becoming a daemon feature
+  → if dependable, graduate parts into core daemon
+```
+
+This is also how OpenRig can ship opinionated workflows **without making
+every workflow a daemon feature.**
+
+## See also
+
+- `extension-and-user-workspace` skill — sibling primitive for user-owned behavior added to runtime; bundle vs extension boundary
+- `specification-system` skill — rig specs / agent specs / workflow specs that bundles package
+- `agent-starters` skill — bundles can include or reference Agent Starters
+- `composable-priming-packs` skill — bundles can package priming packs
+- `openrig-user` skill — `rig bundle create / inspect / install` CLI surface

package/daemon/specs/agents/shared/skills/core/rig-lifecycle/SKILL.md

@@ -2,18 +2,27 @@
 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
-    last_verified: "2026-05-04"
-    distribution_scope: product-bound
-    source_evidence: |
-      Lifecycle Reboot/Recovery Scenario Matrix (Tier 1 complete; Tier 2
-      human-gated). Codex auth-refusal surfaces as attention_required.
     sibling_skills:
-      - openrig-user
-      - openrig-operator
-      - seat-continuity-and-handover
-    transfer_test: pending
+      - 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
@@ -53,7 +62,7 @@ states.
 
 **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 `docs/as-built/architecture/architecture-rules-and-event-system.md` rule 15).
+at the daemon level (per `architecture.md` §7 rule 15).
 
 The locked restore-outcome vocabulary:
 
@@ -112,5 +121,7 @@ different claims; don't conflate.
 
 - `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 — occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
+- `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/specs/agents/shared/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 new top-level command** (e.g., `rig fork`). The primitive flows through existing spec/expansion 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/specs/agents/shared/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/specs/agents/shared/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/specs/agents/shared/skills/core/watchdog/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: watchdog
+description: Use when configuring `rig watchdog` policies, authoring wake/refocus/alignment-checkpoint messages, or choosing the right intervention level for a stale-owner situation. The 3-level continuity-check stack (wake / refocus / alignment-checkpoint), the discipline that prevents cadence pollution and bureaucracy theater, and the artifact-pool loop-edge pattern for evidence-aware waking.
+metadata:
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      # Sibling sweep 2026-07-19 audit: superseded control-plane-* family
+      # dropped (control-plane-watchdog now redirects HERE); kept the
+      # genuinely adjacent set.
+      - queue-handoff
+      - workflow-runtime
+      - alignment-trace
+      - looping-workflows
+      - intake-routing
+      - human-in-the-loop
+      - status-not-chat-orchestrator
+---
+
+# Watchdog
+
+Continuity checks are timed or evidence-triggered interventions that
+keep an agent workflow from going idle, drifting, or entering needless
+bureaucracy. They operationalize the alignment-trace doctrine.
+
+## Use this when
+
+- **Authoring a watchdog policy** for a long-running rig (artifact-pool
+  edges, stale-owner detection, periodic reminders).
+- **Choosing the intervention level** for a stale-owner situation: is
+  this a wake, a refocus, or an alignment checkpoint?
+- **Drafting wake/refocus/alignment-checkpoint message text** that
+  prevents cadence pollution and bureaucracy theater.
+- **Deciding cadence** — scan vs wake intervals, conservative vs
+  aggressive nudging.
+
+## Don't use this when
+
+- The agent is actively working and closing artifacts. Prefer no-op.
+- The intervention is masking bad startup or workflow design — fix the
+  underlying cause, don't compensate via watchdog.
+- The work has a clear next-action handoff already in queue. Use queue
+  nudges instead of a watchdog policy.
+
+## The 3-level intervention stack
+
+| Level | Goal | When | What it does |
+|---|---|---|---|
+| **Wake** | Restart motion | Owner appears idle, stale, blocked, or missing a next handoff | Small liveness nudge — does NOT reframe the work |
+| **Refocus** | Correct drift | Output shows mode drift, approval regression, weak stop-condition reasoning | Medium alignment nudge — re-centers on role, north star, current approved workstream, coordination mode, stop conditions; does NOT interrupt valid work |
+| **Alignment checkpoint** | Rebuild shared map | Phase boundary, lifecycle mutation, product-intent decision, confusing contradiction | Larger deliberate pause — agent runs full alignment-trace before proceeding |
+
+`cron`, timers, and `rig watchdog` are scheduling substrates. They
+should NOT imply that every tick means the same semantic action. The
+intervention level is chosen by evidence, not cadence.
+
+## Current best practice for refocus message text
+
+A well-shaped refocus message:
+
+- Starts with: **finish current action first**.
+- Names the intervention kind: wake, refocus, or alignment checkpoint.
+- Names the current approved workstream or says none is known.
+- Says what continuity means: continue, verify, hand off, or explicitly park.
+- Names stop conditions: scope/risk/posture changes, failed gate, contradictory evidence, or no continuity chain naming a sensible next step.
+- Does NOT convert itself into a fresh approval gate.
+- Does NOT wake delivery seats unless an approved workflow exists and the owner is stale.
+
+## Failure modes (7; verbatim)
+
+1. Cadence is too frequent and pollutes the workstream.
+2. Watchdog wakes the wrong seat instead of the stale owner.
+3. Refocus text is too rule-shaped and creates brittle behavior.
+4. Watchdog compensates for bad startup or workflow design instead of revealing it.
+5. Refocus is misread as a new top-priority task and interrupts the current action.
+6. Refocus becomes bureaucracy theater: an already-approved workflow stops for re-approval.
+7. Repeated static nudges teach agents to answer the reminder instead of progressing the artifact.
+
+## Artifact-pool loop edges (the first evidence-aware pattern)
+
+The first evidence-aware watchdog use that should remain small and
+explicit:
+
+- **Consumer-pool wake**: if a ready artifact exists, wake the consumer loop head.
+- **Producer-edge repair**: if upstream completion exists but the downstream artifact is missing, wake the producer loop head.
+
+**Scan cadence and wake cadence are separate.** Worked example (from the
+RSI v2 mission, now archived — the numbers are era-specific, the
+scan-vs-wake separation is the durable rule): scan every 30 seconds, wake
+at most every 600 seconds while work remains actionable.
+
+This is not a generic workflow engine. It's a guardrail against cold
+pools and missing edge artifacts.
+
+## Two surfaces: rigx watchdog (config-layer) and rig watchdog (daemon-shipped)
+
+| Surface | Status | Policies |
+|---|---|---|
+| `rigx watchdog` (config-layer dogfood) | Tmux-backed loops; coexists with daemon | Static periodic-reminder + artifact-pool-ready + edge-artifact-required (per-RSI-loop) |
+| `rig watchdog` (daemon-shipped, v0.2.0 Phase C) | SQLite-backed scheduler; survives daemon restart | `periodic-reminder` / `artifact-pool-ready` / `edge-artifact-required` / `workflow-keepalive` (Phase D — reads workflow_instances directly) |
+
+Daemon `rig watchdog` is the active host coordination surface for new
+work. History records only loud evaluations (`sent` / `terminal`);
+quiet skip reasons are NOT recorded — POC parity so agents are not
+woken about scheduler polls.
+
+## Future shape (current limit)
+
+The mature primitive should be evidence-aware: inspect durable
+queue/workflow state, pane activity, transcript/context growth, and
+known workstream frontier; classify the intervention as no-op / wake /
+refocus / alignment-checkpoint; prefer no-op for active owners; render
+message text from the active orientation graph instead of hard-coding
+static policy.
+
+Until queue substrate, activity state, and lifecycle evidence are fully
+productized at this level of granularity: keep config-layer use small
+and explicit, prefer one workflow watchdog plus targeted exception
+handling over many per-seat nag loops.
+
+## See also
+
+- `alignment-trace` skill — the doctrine this primitive operationalizes; full and light trace templates
+- `queue-handoff` skill — durable handoff via queue items; watchdog is complementary (watchdog wakes; queue routes)
+- `looping-workflows` skill — operating discipline for self-driving rig-shaped loops; uses watchdog policies for loop edges