[minatoaquaMK2]

Why

This is the fourth PR from the split agreed in #379, following #380, #382 and #383. It covers the controller docs, example and end-to-end tests for #300.

What changed

• Document how an external controller detaches a volume before hibernation and restores it after wake.
• Add a Python example with tests for failed attachments, cancellation and keeping access closed until data checks pass.
• Add an HTTP/Go SDK test for registration, writer exclusion, detach, hibernate, wake and reattachment. It checks that detached sleep releases the hold and wake does not restore the disk.

Scope

Disk lifecycle, reservation across sleep, node fencing and application access remain the external controller's responsibility. No daemon or SDK implementation changes.

Verification

• Race tests passed in sandboxd, e2e and the Go SDK. All 271 Python tests passed, along with mypy, Ruff, vet and Linux/Darwin lint.
• Ran the Python example on a real Linux/KVM VM with Cocoon v0.7.3. The same claim and backing survived detach, hibernate, a daemon restart while asleep, wake and reattachment. Disk serial, filesystem UUID and payload checks passed. The writer stopped without errors, and offline data checks passed after cleanup.
• Busy unmount kept the disk attached and access closed. A simulated lost response after a real successful detach required a successful retry before sleep. The gate and reservation were local test fixtures; multi-node fencing and access control were not tested.

[CMGS]

Thanks @minatoaquaMK2. I am folding this into #405 together with today's whole-repo audit. Your commit is cherry-picked there unchanged, with you as its author, and #405 will be rebase-merged so the commit keeps your authorship.

Changes on top of it, in review: tighten the volume controller example and its doc:

• The 26-line VolumeHooks docstring repeated docs/volume-controller.md. Each hook contract is now a short list in the doc, and the class docstring is one line pointing there. The example also gets a one-line module docstring.
• mount_and_verify links to the attach-only device discovery, which now advises a short retry when mount reports not a valid block device. engine: retry a volume mount while the device is not yet openable #404 found that the /dev node can exist before the kernel opens a hot-plugged disk.
• The first paragraph of the doc is tightened, and the recovery sentences that the hook list now covers are removed.
• The cancellation tests are dropped. The functions hold no cleanup, so a CancelledError takes the same path as the failure cases that are already tested.

I also ran your flow on bare metal (cocoon v0.7.4) on the #405 head. It used a tenant claim and a runtime-registered writable attach-only volume: attach, mount and write, detach, hibernate, restart sandboxd while asleep, exec wake, reattach, then mount and verify. The device, filesystem UUID, serial and payload matched, and unregistering after release returned 204.

Closing in favor of #405.