(release) Add explicit incomplete snapshot cleanup

Add a dedicated cleanup path for incomplete snapshots instead of letting
retention prune them implicitly. The retention plan now exposes a guarded
form that requires host and delete-count confirmation before removing
.incomplete snapshot directories and their SQL records.

Keep scheduled/manual retention behavior unchanged, add path safety checks,
and cover cleanup success, confirmation failures, max-delete limits, and
unexpected paths in tests.

Refs #10

src/pobsync_backend/retention.py

@@ -131,6 +131,76 @@ def run_sql_retention_apply(
     return _do_apply()
 
 
+def run_incomplete_cleanup(
+    *,
+    prefix: Path,
+    host: str,
+    yes: bool,
+    max_delete: int,
+    acquire_lock: bool = True,
+) -> dict[str, Any]:
+    host = sanitize_host(host)
+    if not yes:
+        raise ConfigError("Refusing to delete incomplete snapshots without --yes")
+    if max_delete < 0:
+        raise ConfigError("--max-delete must be >= 0")
+
+    paths = PobsyncPaths(home=prefix)
+
+    def _do_cleanup() -> dict[str, Any]:
+        host_config = _enabled_host_config(host)
+        incomplete_list = [
+            _snapshot_to_item(snapshot, reasons=["manual incomplete cleanup"])
+            for snapshot in _incomplete_snapshots_for_host(host_config)
+        ]
+        if max_delete == 0 and len(incomplete_list) > 0:
+            raise ConfigError("Incomplete cleanup blocked by --max-delete=0")
+        if len(incomplete_list) > max_delete:
+            raise ConfigError(
+                f"Refusing to delete {len(incomplete_list)} incomplete snapshots (exceeds --max-delete={max_delete})"
+            )
+
+        actions: list[str] = []
+        deleted: list[dict[str, Any]] = []
+
+        for item in incomplete_list:
+            dirname = item["dirname"]
+            snap_path = Path(item["path"])
+            path = _snapshot_delete_path(path=snap_path, dirname=dirname)
+            _validate_incomplete_delete_path(host=host, path=path, dirname=dirname)
+
+            if not path.exists():
+                actions.append(f"skip missing incomplete/{dirname}")
+            elif not path.is_dir():
+                raise ConfigError(f"Refusing to delete non-directory path: {path}")
+            else:
+                _remove_snapshot_tree(path)
+                actions.append(f"deleted incomplete {dirname}")
+
+            SnapshotRecord.objects.filter(
+                host__host=host,
+                kind=SnapshotRecord.Kind.INCOMPLETE,
+                dirname=dirname,
+            ).delete()
+            deleted.append({"dirname": dirname, "kind": SnapshotRecord.Kind.INCOMPLETE, "path": str(path)})
+
+        return {
+            "ok": True,
+            "host": host,
+            "kind": SnapshotRecord.Kind.INCOMPLETE,
+            "max_delete": max_delete,
+            "source": "sql",
+            "planned_delete_count": len(incomplete_list),
+            "deleted": deleted,
+            "actions": actions,
+        }
+
+    if acquire_lock:
+        with acquire_host_lock(paths.locks_dir, host, command="incomplete-cleanup"):
+            return _do_cleanup()
+    return _do_cleanup()
+
+
 def _enabled_host_config(host: str) -> HostConfig:
     try:
         return HostConfig.objects.get(host=host, enabled=True)
@@ -212,6 +282,15 @@ def _snapshot_delete_path(*, path: Path, dirname: str) -> Path:
     return path
 
 
+def _validate_incomplete_delete_path(*, host: str, path: Path, dirname: str) -> None:
+    path_parts = path.parts
+    if path.name != dirname or ".incomplete" not in path_parts or host not in path_parts:
+        raise ConfigError(f"Refusing to delete unexpected incomplete snapshot path: {path}")
+    incomplete_index = path_parts.index(".incomplete")
+    if incomplete_index == 0 or path_parts[incomplete_index - 1] != host:
+        raise ConfigError(f"Refusing to delete incomplete snapshot outside host backup root: {path}")
+
+
 def _remove_snapshot_tree(path: Path) -> None:
     _make_directories_user_writable(path)
     shutil.rmtree(path)