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.

tests/unit/api/tool-factory-route.test.ts

@@ -100,6 +100,7 @@ vi.mock("../../../apps/api/src/lib/svg-sanitize.js", () => ({
 }));
 
 vi.mock("../../../apps/api/src/lib/feature-status.js", () => ({
+  getFirstMissingBundleForTool: vi.fn(() => null),
   isToolInstalled: vi.fn(() => true),
 }));
 
@@ -139,7 +140,10 @@ vi.mock("sharp", () => ({
 
 import { apiToolPath } from "@snapotter/shared";
 import { enqueueToolJob, waitForJob } from "../../../apps/api/src/jobs/enqueue.js";
-import { isToolInstalled } from "../../../apps/api/src/lib/feature-status.js";
+import {
+  getFirstMissingBundleForTool,
+  isToolInstalled,
+} from "../../../apps/api/src/lib/feature-status.js";
 import { validateImageBuffer } from "../../../apps/api/src/lib/file-validation.js";
 import type { AnyToolRouteConfig } from "../../../apps/api/src/routes/tool-factory.js";
 import {
@@ -281,6 +285,8 @@ function createMockRequest(opts: {
 describe("createToolRoute", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    vi.mocked(getFirstMissingBundleForTool).mockReset();
+    vi.mocked(getFirstMissingBundleForTool).mockReturnValue(null);
     vi.mocked(isToolInstalled).mockReset();
     vi.mocked(isToolInstalled).mockReturnValue(true);
   });
@@ -424,6 +430,31 @@ describe("createToolRoute", () => {
       // This validates the guard code path exists without false positives.
     });
 
+    it("returns 501 naming the first missing extra bundle for multi-bundle AI tools", async () => {
+      vi.mocked(isToolInstalled).mockReturnValueOnce(false);
+      vi.mocked(getFirstMissingBundleForTool).mockReturnValueOnce("face-detection");
+      const app = createMockApp();
+      const id = "enhance-faces";
+      createToolRoute(app as never, makeMockConfig(id));
+      const handler = app.routes[apiToolPath(id)];
+      const reply = createMockReply();
+      const req = createMockRequest({
+        fileBuffer: Buffer.from("png-data"),
+        settings: JSON.stringify({}),
+      });
+
+      await handler(req, reply);
+
+      expect(reply.status).toHaveBeenCalledWith(501);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: "FEATURE_NOT_INSTALLED",
+          feature: "face-detection",
+          featureName: "Face Detection",
+        }),
+      );
+    });
+
     it("returns 200 success envelope when waitForJob resolves", async () => {
       const app = createMockApp();
       const id = "resize";