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.

packages/ai/src/bridge.ts

@@ -9,6 +9,11 @@ import { acquireVenvRead, tryAcquireVenvRead } from "./venv-lock.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PYTHON_DIR = resolve(__dirname, "../python");
 
+function appendEnvPath(base: string, suffix: string): string {
+  const normalizedBase = base.replace(/\/+$/, "");
+  return `${normalizedBase || "/"}${normalizedBase === "" ? "" : "/"}${suffix}`;
+}
+
 /**
  * Build a minimal environment for spawned Python processes.
  * Only passes through variables needed for venv, CUDA, model cache,
@@ -44,6 +49,10 @@ function buildMinimalEnv(): Record<string, string> {
       env[key] = process.env[key] as string;
     }
   }
+
+  env.DATA_DIR ??= "./data";
+  env.MODELS_PATH ??= appendEnvPath(env.DATA_DIR, "ai/models");
+
   // Runtime model downloads are allowed by default (public model weights
   // only, never user data). SNAPOTTER_ALLOW_MODEL_DOWNLOAD=0 enables strict
   // offline mode for airgapped deployments: the sidecar then gets the

packages/ai/src/feature-gate.ts

@@ -29,9 +29,9 @@ export const SCRIPT_BUNDLE_MAP: Record<string, string> = {
 
 /** Bundle ids currently recorded as installed in DATA_DIR/ai/installed.json. */
 function installedBundles(): Set<string> {
-  // Resolve DATA_DIR the same way the Python dispatcher does
-  // (os.environ.get("DATA_DIR", "/data")).
-  const installedPath = join(process.env.DATA_DIR || "/data", "ai", "installed.json");
+  // Resolve DATA_DIR the same way the API config does for native checkouts.
+  // Docker images set DATA_DIR=/data explicitly.
+  const installedPath = join(process.env.DATA_DIR || "./data", "ai", "installed.json");
   try {
     const data = JSON.parse(readFileSync(installedPath, "utf-8")) as {
       bundles?: Record<string, unknown>;