fix(workspaces): migrate overlapping workspace trees offline

Co-Authored-By: Paperclip <noreply@paperclip.ing>

doc/DEVELOPING.md

@@ -1894,6 +1894,18 @@ corrupt, or unbound sources block the import. Publication still requires an
 independent download and restore of the new encrypted snapshot. The old folder
 remains absent, and the importer does not change the original restore point.
 
+Shared physical folders require Cloud's offline enrollment maintenance process.
+A task-level hold cannot fence another workspace record pointing at the same
+folder. Maintenance verifies that legacy deployments have stopped and that no
+runs are active or queued, then imports nested task directories before parent
+roots. A parent can omit a runtime-created nested task folder only after an
+independent restore and source comparison prove that its committed snapshot
+covers those bytes. The parent snapshot records that dependency, and retention
+pins the child snapshot until the parent is deleted. Changed or unavailable
+nested data blocks publication. Ordinary user folders remain in the archive.
+Interrupted maintenance resumes the same import journals; completed records
+leave the pending set. Original folders remain on the retained volume.
+
 Supported sources include empty task folders, repository URLs, and managed
 mutable repositories. Authorized mentioned projects attach all their configured
 Git repositories as writable copies under `.paperclip-repositories/` in the task

doc/plans/2026-11-03-existing-workspace-ephemeral-migration.md

@@ -23,8 +23,10 @@ encrypted task-directory restoration, Git restoration recipes, and legacy
 branch-deletion receipts. PostgreSQL and real-file tests prove cold restoration
 of saved bytes, index state, and unpushed commits, including after pruning the
 old Git object store. Invalid or unavailable retained data still blocks import.
-Shared-root migration and recovery-obligation reconciliation remain separate
-gaps; this slice does not make a whole tenant eligible for enrollment.
+The next slice adds leaf-first offline migration of overlapping folders, verified
+nested snapshot dependencies, interruption recovery, and dependency retention.
+Recovery-obligation reconciliation remains a separate gap; these slices do not
+yet make the whole tenant eligible for enrollment.
 
 - Import existing files or a verified retained source. A missing folder alone is
   not permission to publish an empty workspace or choose a newer Git branch.