Hydration: install & rollback

Hydration is Quartermaster’s word for installing a capability onto a target — copying a skill into ~/.claude/skills/, for example — because the registry stores the canonical form and “hydrates” it into the shape a tool expects.

The three-step loop

1. preview_hydration — returns a draft plan: every operation the install would perform, marked dryRun: true. Nothing is written, no backups are created, nothing touches the target. The same preview is available from the dashboard (POST /api/hydration/preview).
2. apply_hydration — executes a plan, but only if it passes the gates:
   • requires approval: "approve";
   • rejects plans that are high-risk, unknown-origin, blocked, or carry block-effect policy findings (memories block hydration by default);
   • validates every target path against the HYDRATION_ROOTS allow-list (absolute paths outside the roots and .. traversal are rejected before any write);
   • backs up every file it overwrites and records everything it creates.
3. rollback_hydration — restores the recorded files and removes only what the apply created.

Device targets

register_device / list_devices / census_devices manage device profiles — metadata rows in the local database describing hydration targets. Registering a device writes no artifact files.

What can block an apply

Gate	Effect
High-risk finding from scan_risk	apply refused
Unknown origin	apply refused
Compatibility blocker (e.g. conversion_rule_missing)	apply refused
Policy finding with block effect	apply refused
Target path outside HYDRATION_ROOTS	write refused

The refusal always carries a structured reason, so an agent can explain why and what review step would unblock it. See the security model for the full write-safety guarantees.