fix: reliable, self-healing AI feature-bundle installs (#472)

Make on-demand AI feature-bundle installs reliable and self-healing, closing
the failure modes behind most "some tool doesn't work" reports.

Multi-bundle installs: tools needing more than one bundle (Passport Photo,
Enhance Faces) install every required bundle from one action and stay
not-installed until all are present. Verified across all 19 AI tools.

Downloads: self-heal the accelerated Hugging Face (Xet) client so an upgraded
venv no longer silently falls back to slow urllib; restart instead of
corrupting a resumed partial when a proxy ignores Range and returns 200;
verify the completed size; fail fast on disk-full and HTTP 4xx; retry
transient errors five times; add hf_transfer fallback and document Xet egress.

Install integrity: crash-atomic venv writes so a killed or out-of-space
install can no longer tear the shared venv and break other tools; a boot
breadcrumb reseeds a torn venv to a clean state automatically; a post-install
smoke import test refuses to record a bundle whose libraries cannot load; an
install watchdog stops a wedged installer that would otherwise hold the venv
writer lock forever.

Adds unit and end-to-end tests for every failure mode above.

docker/Dockerfile

@@ -366,6 +366,7 @@ RUN --mount=type=cache,target=/root/.cache/pip \
         Pillow==12.2.0 \
         numpy==1.26.4 \
         opencv-python-headless==4.10.0.84 \
+        "huggingface-hub[hf_xet,hf_transfer]==0.36.2" \
         pikepdf==10.8.0 \
         PyMuPDF==1.27.2.3 \
         weasyprint==69.0 \

docker/feature-manifest.json

@@ -2,7 +2,12 @@
   "manifestVersion": 2,
   "imageVersion": "2.0.0",
   "pythonVersion": { "amd64": "3.12", "arm64": "3.11" },
-  "basePackages": ["numpy==1.26.4", "Pillow==12.2.0", "opencv-python-headless==4.10.0.84"],
+  "basePackages": [
+    "numpy==1.26.4",
+    "Pillow==12.2.0",
+    "opencv-python-headless==4.10.0.84",
+    "huggingface-hub[hf_xet,hf_transfer]==0.36.2"
+  ],
   "constraints": [
     "numpy==1.26.4",
     "scipy==1.12.0",
@@ -79,6 +84,7 @@
           "args": ["birefnet-hr-matting"]
         }
       ],
+      "smokeImports": ["rembg", "onnxruntime"],
       "enablesTools": [
         "remove-background",
         "passport-photo",
@@ -126,6 +132,7 @@
           "minSize": 1000000
         }
       ],
+      "smokeImports": ["mediapipe"],
       "enablesTools": ["blur-faces", "red-eye-removal", "smart-crop"]
     },
     "object-eraser-colorize": {
@@ -147,7 +154,7 @@
         }
       },
       "packages": {
-        "common": ["huggingface-hub"],
+        "common": ["huggingface-hub[hf_xet]==0.36.2"],
         "amd64": ["onnxruntime-gpu==1.20.1"],
         "arm64": ["onnxruntime==1.20.1", "protobuf>=4.25.3,<5"]
       },
@@ -192,6 +199,7 @@
           "minSize": 0
         }
       ],
+      "smokeImports": ["onnxruntime"],
       "enablesTools": ["erase-object", "colorize", "ai-canvas-expand"]
     },
     "upscale-enhance": {
@@ -213,7 +221,12 @@
         }
       },
       "packages": {
-        "common": ["codeformer-pip==0.0.4", "huggingface-hub", "einops", "setuptools<75"],
+        "common": [
+          "codeformer-pip==0.0.4",
+          "huggingface-hub[hf_xet]==0.36.2",
+          "einops",
+          "setuptools<75"
+        ],
         "amd64": [
           "torch==2.7.0+cu126 torchvision==0.22.0+cu126 --index-url https://download.pytorch.org/whl/cu126",
           "lpips",
@@ -301,6 +314,7 @@
           "replace": "from torchvision.transforms.functional import rgb_to_grayscale"
         }
       ],
+      "smokeImports": ["torch", "torchvision"],
       "enablesTools": ["upscale", "enhance-faces", "noise-removal"]
     },
     "photo-restoration": {
@@ -322,7 +336,7 @@
         }
       },
       "packages": {
-        "common": ["codeformer-pip==0.0.4", "huggingface-hub", "setuptools<75"],
+        "common": ["codeformer-pip==0.0.4", "huggingface-hub[hf_xet]==0.36.2", "setuptools<75"],
         "amd64": [
           "onnxruntime-gpu==1.20.1",
           "mediapipe>=0.10.21",
@@ -406,6 +420,7 @@
           "replace": "from torchvision.transforms.functional import rgb_to_grayscale"
         }
       ],
+      "smokeImports": ["onnxruntime", "torch", "mediapipe"],
       "enablesTools": ["restore-photo"]
     },
     "ocr": {
@@ -427,7 +442,7 @@
         }
       },
       "packages": {
-        "common": ["huggingface-hub"],
+        "common": ["huggingface-hub[hf_xet]==0.36.2"],
         "amd64": [
           "paddlepaddle-gpu>=3.2.1 --index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/ --extra-index-url https://pypi.org/simple/",
           "paddleocr[doc-parser]>=3.4.0,<3.5.0"
@@ -482,6 +497,7 @@
           "args": ["PaddlePaddle/PaddleOCR-VL-1.5", "PaddleOCR-VL-1.5"]
         }
       ],
+      "smokeImports": ["paddle", "paddleocr"],
       "enablesTools": ["ocr", "ocr-pdf"]
     },
     "transcription": {
@@ -516,6 +532,7 @@
           "args": ["Systran/faster-whisper-small", "faster-whisper-small"]
         }
       ],
+      "smokeImports": ["faster_whisper", "ctranslate2"],
       "enablesTools": ["transcribe-audio", "auto-subtitles"]
     }
   }