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/ai/bridge-extended.test.ts

@@ -1309,6 +1309,7 @@ describe("bridge - env passthrough for sidecar-specific vars", () => {
     vi.restoreAllMocks();
     delete process.env.U2NET_HOME;
     delete process.env.DATA_DIR;
+    delete process.env.MODELS_PATH;
     delete process.env.DISPATCHER_MAX_REQUESTS;
   });
 
@@ -1360,9 +1361,10 @@ describe("bridge - env passthrough for sidecar-specific vars", () => {
     expect(getLastSpawnEnv()?.DISPATCHER_MAX_REQUESTS).toBe("100");
   });
 
-  it("does not include unset vars in subprocess env", async () => {
+  it("defaults data/model paths but does not include other unset vars in subprocess env", async () => {
     delete process.env.U2NET_HOME;
     delete process.env.DATA_DIR;
+    delete process.env.MODELS_PATH;
     delete process.env.DISPATCHER_MAX_REQUESTS;
 
     const mock = createMockProcess();
@@ -1375,7 +1377,8 @@ describe("bridge - env passthrough for sidecar-specific vars", () => {
 
     const env = getLastSpawnEnv();
     expect(env?.U2NET_HOME).toBeUndefined();
-    expect(env?.DATA_DIR).toBeUndefined();
+    expect(env?.DATA_DIR).toBe("./data");
+    expect(env?.MODELS_PATH).toBe("./data/ai/models");
     expect(env?.DISPATCHER_MAX_REQUESTS).toBeUndefined();
   });
 });

tests/unit/ai/feature-gate.test.ts

@@ -9,15 +9,18 @@ import {
 
 let tempDir: string;
 let savedDataDir: string | undefined;
+let savedCwd: string;
 
 beforeEach(() => {
   savedDataDir = process.env.DATA_DIR;
+  savedCwd = process.cwd();
   tempDir = mkdtempSync(join(tmpdir(), "snapotter-gate-"));
   mkdirSync(join(tempDir, "ai"), { recursive: true });
   process.env.DATA_DIR = tempDir;
 });
 
 afterEach(() => {
+  process.chdir(savedCwd);
   if (savedDataDir === undefined) delete process.env.DATA_DIR;
   else process.env.DATA_DIR = savedDataDir;
   rmSync(tempDir, { recursive: true, force: true });
@@ -73,6 +76,28 @@ describe("missingBundleForScript", () => {
     expect(missingBundleForScript("face_landmarks")).toBe("face-detection");
     expect(missingBundleForScript("remove_bg")).toBeNull();
   });
+
+  it("uses the native ./data fallback when DATA_DIR is unset", () => {
+    delete process.env.DATA_DIR;
+    process.chdir(tempDir);
+    const defaultAiDir = join(tempDir, "data", "ai");
+    mkdirSync(defaultAiDir, { recursive: true });
+    writeFileSync(
+      join(defaultAiDir, "installed.json"),
+      JSON.stringify({
+        bundles: {
+          "object-eraser-colorize": {
+            version: "1.0.0-test",
+            installedAt: "2026-01-01T00:00:00.000Z",
+            models: [],
+          },
+        },
+      }),
+      "utf-8",
+    );
+
+    expect(missingBundleForScript("inpaint.py")).toBeNull();
+  });
 });
 
 describe("SCRIPT_BUNDLE_MAP drift vs dispatcher.py", () => {

tests/unit/ai/gpu-detection.test.ts

@@ -67,6 +67,7 @@ describe("buildMinimalEnv - env passthrough", () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    delete process.env.DATA_DIR;
     delete process.env.SNAPOTTER_GPU;
     delete process.env.MODELS_PATH;
     delete process.env.MODELS_DIR;
@@ -110,6 +111,24 @@ describe("buildMinimalEnv - env passthrough", () => {
     expect(env?.MODELS_PATH).toBe("/data/ai/models");
   });
 
+  it("sets matching native DATA_DIR and MODELS_PATH defaults", async () => {
+    delete process.env.DATA_DIR;
+    delete process.env.MODELS_PATH;
+
+    const mock = createMockProcess();
+    vi.mocked(spawn).mockReturnValue(mock.process);
+
+    const promise = runPythonWithProgress("test.py", []);
+    mock.stdout.emit("data", Buffer.from('{"ok": true}\n'));
+    mock.emitEvent("close", 0, null);
+    await promise;
+
+    const env = getSpawnEnv();
+    expect(env).toBeDefined();
+    expect(env?.DATA_DIR).toBe("./data");
+    expect(env?.MODELS_PATH).toBe("./data/ai/models");
+  });
+
   it("does not pass MODELS_DIR (removed dead entry)", async () => {
     process.env.MODELS_DIR = "/some/path";