@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/src/services/downloader.test.ts

@@ -0,0 +1,888 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readAssignments } from "./assignments";
+import { findCatalogModel } from "./catalog";
+import { Downloader } from "./downloader";
+import type { Eliza1DeviceCaps } from "./manifest";
+import { registryPath } from "./paths";
+import type {
+	CatalogModel,
+	DownloadJob,
+	HardwareProbe,
+	InstalledModel,
+} from "./types";
+
+/** Minimal HardwareProbe with a controllable free-disk value for preflight tests. */
+function fakeProbe(freeDiskGb: number): HardwareProbe {
+	return {
+		totalRamGb: 32,
+		freeRamGb: 16,
+		freeDiskGb,
+		gpu: null,
+		cpuCores: 8,
+		platform: "darwin",
+		arch: "arm64",
+		appleSilicon: true,
+		recommendedBucket: "mid",
+		source: "os-fallback",
+	};
+}
+
+function eliza1Manifest(overrides: {
+	ramBudgetMin?: number;
+	ramBudgetRecommended?: number;
+	verifiedBackends?: Record<
+		string,
+		{ status: string; atCommit: string; report: string }
+	>;
+	shaFor: (key: string) => string;
+}): string {
+	const textPath = "text/eliza-1-2b-128k.gguf";
+	const voicePath = "tts/voice.gguf";
+	const asrPath = "asr/asr.gguf";
+	const cachePath = "cache/voice-preset-default.bin";
+	const vadPath = "vad/eliza-1-vad.onnx";
+	const visionPath = "vision/mmproj-2b.gguf";
+	const verifiedBackends = overrides.verifiedBackends ?? {
+		metal: { status: "pass", atCommit: "t", report: "metal" },
+		vulkan: { status: "pass", atCommit: "t", report: "vulkan" },
+		cuda: { status: "pass", atCommit: "t", report: "cuda" },
+		rocm: { status: "pass", atCommit: "t", report: "rocm" },
+		cpu: { status: "pass", atCommit: "t", report: "cpu" },
+	};
+	return JSON.stringify({
+		id: "eliza-1-2b",
+		tier: "2b",
+		version: "1.0.0",
+		publishedAt: "2026-05-11T00:00:00.000Z",
+		lineage: {
+			text: { base: "eliza-1-text", license: "test" },
+			voice: { base: "eliza-1-voice", license: "test" },
+			asr: { base: "eliza-1-asr", license: "test" },
+			vad: { base: "eliza-1-vad", license: "test" },
+			vision: { base: "eliza-1-vision", license: "test" },
+		},
+		defaultEligible: true,
+		// Downloader-mechanics fixture: MTP mode is incidental here, so this
+		// bundle is the legacy embedded-draft-head shape (no separate drafter
+		// GGUF to serve). The Gemma-4 separate-drafter contract is exercised in
+		// manifest.test.ts.
+		mtp: "embedded-draft-head",
+		files: {
+			text: [
+				{
+					path: textPath,
+					sha256: overrides.shaFor("text"),
+					ctx: 131072,
+				},
+			],
+			voice: [{ path: voicePath, sha256: overrides.shaFor("voice") }],
+			asr: [{ path: asrPath, sha256: overrides.shaFor("asr") }],
+			vision: [{ path: visionPath, sha256: overrides.shaFor("vision") }],
+			mtp: [],
+			cache: [
+				{
+					path: cachePath,
+					sha256: overrides.shaFor("cache"),
+				},
+			],
+			vad: [{ path: vadPath, sha256: overrides.shaFor("vad") }],
+		},
+		kernels: {
+			required: ["turboquant_q4", "qjl", "polarquant", "turbo3_tcq"],
+			optional: [],
+			verifiedBackends,
+		},
+		evals: {
+			textEval: { score: 1, passed: true },
+			voiceRtf: { rtf: 0.5, passed: true },
+			asrWer: { wer: 0.05, passed: true },
+			vadLatencyMs: { median: 16, passed: true },
+			mtp: { acceptanceRate: 0.72, speedup: 1.8, passed: true },
+			e2eLoopOk: true,
+			thirtyTurnOk: true,
+		},
+		ramBudgetMb: {
+			min: overrides.ramBudgetMin ?? 2048,
+			recommended: overrides.ramBudgetRecommended ?? 4096,
+		},
+	});
+}
+
+const cpuOnlyCaps: Eliza1DeviceCaps = {
+	availableBackends: ["cpu"],
+	ramMb: 16_384,
+};
+
+function remotePathOf(url: string | URL | Request): string {
+	const href =
+		typeof url === "string" ? url : url instanceof URL ? url.href : url.url;
+	const pathname = new URL(href).pathname;
+	const marker = "/resolve/main/";
+	const idx = pathname.indexOf(marker);
+	return idx >= 0
+		? decodeURIComponent(pathname.slice(idx + marker.length))
+		: "";
+}
+
+function bundleRemotePath(
+	model: { bundleManifestFile?: string; hfPathPrefix?: string },
+	rel: string,
+): string {
+	if (model.hfPathPrefix && !rel.startsWith(`${model.hfPathPrefix}/`)) {
+		return path.posix.join(model.hfPathPrefix, rel);
+	}
+	if (!model.bundleManifestFile) {
+		throw new Error("missing bundle manifest path");
+	}
+	return path.posix.join(path.posix.dirname(model.bundleManifestFile), rel);
+}
+
+function eliza1BundleRemotePath(rel: string): string {
+	const model = findCatalogModel("eliza-1-2b");
+	if (!model) throw new Error("missing 2b catalog model");
+	return bundleRemotePath(model, rel);
+}
+
+function eliza1BundleManifestPath(): string {
+	const model = findCatalogModel("eliza-1-2b");
+	if (!model?.bundleManifestFile) {
+		throw new Error("missing 2b bundle manifest path");
+	}
+	return bundleRemotePath(model, model.bundleManifestFile);
+}
+
+/** A fetch that serves only the manifest; any weight fetch throws. */
+function installManifestOnlyFetch(
+	manifestBody: string,
+	manifestPath: string = eliza1BundleManifestPath(),
+): ReturnType<typeof vi.fn> {
+	const spy = vi.fn(async (url: string | URL | Request) => {
+		if (remotePathOf(url) === manifestPath) {
+			return new Response(manifestBody, {
+				status: 200,
+				headers: { "content-length": String(Buffer.byteLength(manifestBody)) },
+			});
+		}
+		throw new Error(`unexpected weight fetch for ${remotePathOf(url)}`);
+	});
+	globalThis.fetch = spy as unknown as typeof fetch;
+	return spy;
+}
+
+const originalEnv = { ...process.env };
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+	process.env = { ...originalEnv };
+	globalThis.fetch = originalFetch;
+	vi.restoreAllMocks();
+});
+
+function sha256(content: string): string {
+	return createHash("sha256").update(content).digest("hex");
+}
+
+function readOwnedRegistryModels(): InstalledModel[] {
+	if (!fs.existsSync(registryPath())) return [];
+	const parsed = JSON.parse(fs.readFileSync(registryPath(), "utf8")) as {
+		models?: InstalledModel[];
+	};
+	return parsed.models ?? [];
+}
+
+function installFetchFixture(files: Map<string, string>): void {
+	globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+		const href =
+			typeof url === "string" ? url : url instanceof URL ? url.href : url.url;
+		const pathname = new URL(href).pathname;
+		const marker = "/resolve/main/";
+		const markerIndex = pathname.indexOf(marker);
+		const remotePath =
+			markerIndex >= 0
+				? decodeURIComponent(pathname.slice(markerIndex + marker.length))
+				: "";
+		const body = files.get(remotePath);
+		if (body === undefined) {
+			return new Response(`missing ${remotePath}`, { status: 404 });
+		}
+		return new Response(body, {
+			status: 200,
+			headers: { "content-length": String(Buffer.byteLength(body)) },
+		});
+	}) as unknown as typeof fetch;
+}
+
+function waitForTerminal(
+	downloader: Downloader,
+	modelId: string,
+): Promise<DownloadJob> {
+	return new Promise((resolve, reject) => {
+		const unsubscribe = downloader.subscribe((event) => {
+			if (event.job.modelId !== modelId) return;
+			if (event.type === "completed") {
+				unsubscribe();
+				resolve(event.job);
+			}
+			if (event.type === "failed") {
+				unsubscribe();
+				reject(new Error(event.job.error ?? "download failed"));
+			}
+		});
+	});
+}
+
+describe("local inference downloader status", () => {
+	it("loads persisted terminal failures into snapshots", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const statusDir = path.join(root, "local-inference");
+		fs.mkdirSync(statusDir, { recursive: true });
+		fs.writeFileSync(
+			path.join(statusDir, "download-status.json"),
+			JSON.stringify({
+				version: 1,
+				jobs: [
+					{
+						jobId: "job-1",
+						modelId: "eliza-1-2b",
+						state: "failed",
+						received: 64,
+						total: 128,
+						bytesPerSec: 0,
+						etaMs: null,
+						startedAt: "2026-05-08T00:00:00.000Z",
+						updatedAt: "2026-05-08T00:00:01.000Z",
+						error: "network reset",
+					},
+				],
+			}),
+			"utf8",
+		);
+
+		const [job] = new Downloader().snapshot();
+
+		expect(job?.modelId).toBe("eliza-1-2b");
+		expect(job?.state).toBe("failed");
+		expect(job?.error).toBe("network reset");
+	});
+
+	it("installs Eliza-1 manifest bundles with embedded-draft-head MTP metadata", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		expect(model).toBeDefined();
+		if (!model) throw new Error("missing test catalog model");
+		const manifestFile = model.bundleManifestFile;
+		if (!manifestFile) throw new Error("missing bundle manifest path");
+
+		const text = "GGUF text model";
+		const voice = "GGUF voice model";
+		const asr = "GGUF ASR model";
+		const vad = "VAD model";
+		const cache = "voice preset";
+		const vision = "vision projector";
+		const textPath = "text/eliza-1-2b-128k.gguf";
+		const voicePath = "tts/voice.gguf";
+		const asrPath = "asr/asr.gguf";
+		const vadPath = "vad/eliza-1-vad.onnx";
+		const cachePath = "cache/voice-preset-default.bin";
+		const visionPath = "vision/mmproj-2b.gguf";
+		const manifest = JSON.stringify({
+			id: "eliza-1-2b",
+			tier: "2b",
+			version: "1.0.0",
+			publishedAt: "2026-05-11T00:00:00.000Z",
+			lineage: {
+				text: { base: "eliza-1-text", license: "test" },
+				voice: { base: "eliza-1-voice", license: "test" },
+				asr: { base: "eliza-1-asr", license: "test" },
+				vad: { base: "eliza-1-vad", license: "test" },
+				vision: { base: "eliza-1-vision", license: "test" },
+			},
+			defaultEligible: true,
+			mtp: "embedded-draft-head",
+			files: {
+				text: [
+					{
+						path: textPath,
+						sha256: sha256(text),
+						ctx: 131072,
+					},
+				],
+				voice: [{ path: voicePath, sha256: sha256(voice) }],
+				asr: [{ path: asrPath, sha256: sha256(asr) }],
+				vision: [{ path: visionPath, sha256: sha256(vision) }],
+				mtp: [],
+				cache: [
+					{
+						path: cachePath,
+						sha256: sha256(cache),
+					},
+				],
+				vad: [{ path: vadPath, sha256: sha256(vad) }],
+			},
+			kernels: {
+				required: ["turboquant_q4", "qjl", "polarquant", "turbo3_tcq"],
+				optional: [],
+				verifiedBackends: {
+					metal: {
+						status: "pass",
+						atCommit: "test",
+						report: "test-metal",
+					},
+					vulkan: {
+						status: "pass",
+						atCommit: "test",
+						report: "test-vulkan",
+					},
+					cuda: {
+						status: "pass",
+						atCommit: "test",
+						report: "test-cuda",
+					},
+					rocm: {
+						status: "pass",
+						atCommit: "test",
+						report: "test-rocm",
+					},
+					cpu: {
+						status: "pass",
+						atCommit: "test",
+						report: "test-cpu",
+					},
+				},
+			},
+			evals: {
+				textEval: { score: 1, passed: true },
+				voiceRtf: { rtf: 0.5, passed: true },
+				asrWer: { wer: 0.05, passed: true },
+				vadLatencyMs: { median: 16, passed: true },
+				mtp: { acceptanceRate: 0.72, speedup: 1.8, passed: true },
+				e2eLoopOk: true,
+				thirtyTurnOk: true,
+			},
+			ramBudgetMb: { min: 2048, recommended: 4096 },
+		});
+		installFetchFixture(
+			new Map([
+				[bundleRemotePath(model, manifestFile), manifest],
+				[bundleRemotePath(model, textPath), text],
+				[bundleRemotePath(model, voicePath), voice],
+				[bundleRemotePath(model, asrPath), asr],
+				[bundleRemotePath(model, vadPath), vad],
+				[bundleRemotePath(model, cachePath), cache],
+				[bundleRemotePath(model, visionPath), vision],
+			]),
+		);
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+		});
+		const completed = waitForTerminal(downloader, model.id);
+		await downloader.start(model);
+		const job = await completed;
+		const installed = readOwnedRegistryModels();
+		const main = installed.find((entry) => entry.id === model.id);
+		expect(main).toBeDefined();
+		const bundleRoot = main?.bundleRoot;
+		expect(bundleRoot).toBeDefined();
+		if (!main || !bundleRoot) {
+			throw new Error("bundle install did not register expected files");
+		}
+
+		expect(job.state).toBe("completed");
+		expect(path.normalize(main.path).endsWith(path.normalize(textPath))).toBe(
+			true,
+		);
+		expect(bundleRoot).toBe(
+			path.join(root, "local-inference", "models", "eliza-1-2b.bundle"),
+		);
+		expect(main.manifestPath).toBe(path.join(bundleRoot, manifestFile));
+		expect(main.bundleVersion).toBe("1.0.0");
+		expect(main.bundleSizeBytes).toBeGreaterThan(main.sizeBytes);
+		expect(fs.existsSync(path.join(bundleRoot, voicePath))).toBe(true);
+		expect(fs.existsSync(path.join(bundleRoot, asrPath))).toBe(true);
+		expect(fs.existsSync(path.join(bundleRoot, vadPath))).toBe(true);
+		expect(fs.existsSync(path.join(bundleRoot, visionPath))).toBe(true);
+		expect(installed.some((entry) => entry.id.endsWith("-drafter"))).toBe(
+			false,
+		);
+		expect(main.bundleVerifiedAt).toBeUndefined();
+		expect(await readAssignments()).toEqual({});
+	});
+
+	it("rejects a pinned bundle manifest sha before fetching weights", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		const fetchSpy = installManifestOnlyFetch("tampered manifest");
+		const pinnedModel = {
+			...model,
+			companionModelIds: [],
+			bundleManifestSha256: sha256("expected manifest"),
+		};
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === model.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		await downloader.start(pinnedModel);
+		const job = await failed;
+
+		expect(job.error).toContain(
+			`SHA256 mismatch for bundle file ${model.bundleManifestFile}`,
+		);
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("rejects custom CatalogModel specs before starting a download", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const baseModel = findCatalogModel("eliza-1-2b");
+		if (!baseModel) throw new Error("missing test catalog model");
+		const customSpec: CatalogModel = {
+			...baseModel,
+			id: "hf:test/partial::model.gguf",
+			displayName: "Partial Test Model",
+			ggufFile: "model.gguf",
+			bundleManifestFile: undefined,
+			bundleManifestSha256: undefined,
+			companionModelIds: [],
+			runtimeRole: undefined,
+		};
+
+		const downloader = new Downloader();
+		await expect(downloader.start(customSpec)).rejects.toThrow(
+			/Custom model downloads are disabled/i,
+		);
+
+		expect(fs.existsSync(registryPath())).toBe(false);
+		expect(downloader.snapshot()).toEqual([]);
+	});
+
+	it("aborts before any weight byte when no verified backend overlaps the device", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		// Simulate a CUDA-only bundle that a CPU-only host cannot run. Build the
+		// test object from a visible catalog entry while restricting verifiedBackends
+		// to CUDA only so the CPU-only host probe triggers the backend-mismatch path.
+		const baseModel = findCatalogModel("eliza-1-4b");
+		if (!baseModel) throw new Error("missing test catalog model");
+		const model = {
+			...baseModel,
+			id: "eliza-1-27b-256k",
+			hfPathPrefix: "bundles/27b-256k",
+			ggufFile: "text/eliza-1-27b-256k-256k.gguf",
+			bundleManifestFile: "eliza-1.manifest.json",
+			companionModelIds: [],
+		};
+		const manifestFile = model.bundleManifestFile;
+		if (!manifestFile) throw new Error("missing bundle manifest path");
+
+		const textPath = model.ggufFile;
+		const voicePath = "tts/voice.gguf";
+		const cachePath = "cache/voice-preset-default.bin";
+		const visionPath = "vision/mmproj-27b-256k.gguf";
+		const manifest = JSON.stringify({
+			id: "eliza-1-27b-256k",
+			tier: "27b-256k",
+			version: "1.0.0",
+			publishedAt: "2026-05-11T00:00:00.000Z",
+			lineage: {
+				text: { base: "eliza-1-text", license: "test" },
+				voice: { base: "eliza-1-voice", license: "test" },
+				vision: { base: "eliza-1-vision", license: "test" },
+			},
+			defaultEligible: false,
+			files: {
+				text: [
+					{
+						path: textPath,
+						sha256: sha256("x"),
+						ctx: 1_048_576,
+					},
+				],
+				voice: [{ path: voicePath, sha256: sha256("v") }],
+				asr: [],
+				vision: [{ path: visionPath, sha256: sha256("vision") }],
+				mtp: [],
+				cache: [{ path: cachePath, sha256: sha256("c") }],
+			},
+			kernels: {
+				required: ["turboquant_q4", "qjl", "polarquant", "turbo3_tcq"],
+				optional: [],
+				verifiedBackends: {
+					metal: { status: "skipped", atCommit: "t", report: "n/a" },
+					vulkan: { status: "skipped", atCommit: "t", report: "n/a" },
+					cuda: { status: "pass", atCommit: "t", report: "cuda" },
+					rocm: { status: "skipped", atCommit: "t", report: "n/a" },
+					cpu: { status: "skipped", atCommit: "t", report: "n/a" },
+				},
+			},
+			evals: {
+				textEval: { score: 1, passed: true },
+				voiceRtf: { rtf: 0.5, passed: true },
+				e2eLoopOk: true,
+				thirtyTurnOk: true,
+			},
+			ramBudgetMb: { min: 8_000, recommended: 12_000 },
+		});
+		const fetchSpy = installManifestOnlyFetch(
+			manifest,
+			bundleRemotePath(model, manifestFile),
+		);
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === model.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+		await downloader.start(model);
+		const job = await failed;
+		expect(job.state).toBe("failed");
+		expect(job.error).toMatch(/kernels\.verifiedBackends/i);
+		// Manifest is fetched (it's metadata, not a weight); nothing else is.
+		const weightFetches = fetchSpy.mock.calls.filter(
+			([u]) => remotePathOf(u) !== bundleRemotePath(model, manifestFile),
+		);
+		expect(weightFetches).toHaveLength(0);
+		expect(readOwnedRegistryModels().some((m) => m.id === model.id)).toBe(
+			false,
+		);
+	});
+
+	it("aborts before any weight byte when the RAM budget exceeds the device", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		const manifest = eliza1Manifest({
+			shaFor: () => sha256("x"),
+			ramBudgetMin: 999_999,
+			ramBudgetRecommended: 999_999,
+		});
+		installManifestOnlyFetch(manifest);
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === model.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+		await downloader.start(model.id);
+		const job = await failed;
+		expect(job.error).toMatch(/needs at least 999999 MB RAM/);
+		expect(readOwnedRegistryModels().some((m) => m.id === model.id)).toBe(
+			false,
+		);
+	});
+
+	it("runs the verify-on-device hook before the bundle fills a default slot", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		const bytes = {
+			text: "GGUF text",
+			voice: "GGUF voice",
+			asr: "GGUF asr",
+			vad: "VAD onnx",
+			cache: "voice preset",
+			vision: "vision projector",
+		} as const;
+		const manifest = eliza1Manifest({
+			shaFor: (k) => sha256(bytes[k as keyof typeof bytes]),
+		});
+		installFetchFixture(
+			new Map([
+				[eliza1BundleManifestPath(), manifest],
+				[eliza1BundleRemotePath("text/eliza-1-2b-128k.gguf"), bytes.text],
+				[eliza1BundleRemotePath("tts/voice.gguf"), bytes.voice],
+				[eliza1BundleRemotePath("asr/asr.gguf"), bytes.asr],
+				[eliza1BundleRemotePath("vad/eliza-1-vad.onnx"), bytes.vad],
+				[eliza1BundleRemotePath("cache/voice-preset-default.bin"), bytes.cache],
+				[eliza1BundleRemotePath("vision/mmproj-2b.gguf"), bytes.vision],
+			]),
+		);
+
+		const verifyCalls: Array<{
+			modelId: string;
+			bundleRoot: string;
+			manifestPath: string;
+			textGgufPath: string;
+		}> = [];
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			verifyOnDevice: async ({
+				modelId,
+				bundleRoot,
+				manifestPath,
+				textGgufPath,
+			}) => {
+				if (!modelId) throw new Error("verify hook missing modelId");
+				verifyCalls.push({ modelId, bundleRoot, manifestPath, textGgufPath });
+			},
+		});
+		const completed = waitForTerminal(downloader, model.id);
+		await downloader.start(model.id);
+		await completed;
+
+		expect(verifyCalls).toHaveLength(1);
+		expect(verifyCalls[0]?.modelId).toBe(model.id);
+		expect(
+			path
+				.normalize(verifyCalls[0]?.textGgufPath ?? "")
+				.endsWith(path.normalize("text/eliza-1-2b-128k.gguf")),
+		).toBe(true);
+		const installed = readOwnedRegistryModels();
+		const main = installed.find((m) => m.id === model.id);
+		expect(main?.bundleVerifiedAt).toBeTruthy();
+		expect(verifyCalls[0]?.bundleRoot).toBe(main?.bundleRoot);
+		expect(verifyCalls[0]?.manifestPath).toBe(main?.manifestPath);
+	});
+
+	it("fails the download (no install) when the verify-on-device hook rejects", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		const bytes = {
+			text: "GGUF text",
+			voice: "GGUF voice",
+			asr: "GGUF asr",
+			vad: "VAD onnx",
+			cache: "voice preset",
+			vision: "vision projector",
+		} as const;
+		const manifest = eliza1Manifest({
+			shaFor: (k) => sha256(bytes[k as keyof typeof bytes]),
+		});
+		installFetchFixture(
+			new Map([
+				[eliza1BundleManifestPath(), manifest],
+				[eliza1BundleRemotePath("text/eliza-1-2b-128k.gguf"), bytes.text],
+				[eliza1BundleRemotePath("tts/voice.gguf"), bytes.voice],
+				[eliza1BundleRemotePath("asr/asr.gguf"), bytes.asr],
+				[eliza1BundleRemotePath("vad/eliza-1-vad.onnx"), bytes.vad],
+				[eliza1BundleRemotePath("cache/voice-preset-default.bin"), bytes.cache],
+				[eliza1BundleRemotePath("vision/mmproj-2b.gguf"), bytes.vision],
+			]),
+		);
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			verifyOnDevice: async () => {
+				throw new Error("barge-in cancel test failed");
+			},
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === model.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+		await downloader.start(model.id);
+		const job = await failed;
+		expect(job.error).toMatch(/barge-in cancel test failed/);
+		expect(readOwnedRegistryModels().some((m) => m.id === model.id)).toBe(
+			false,
+		);
+	});
+
+	it("dedups concurrent start(sameId) onto one job (no .part write race)", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+		});
+		// Fire two starts for the same id concurrently. The first reserves the
+		// active slot synchronously before its first await, so the second sees it
+		// and returns the SAME job instead of racing a second write onto the .part.
+		const [a, b] = await Promise.all([
+			downloader.start(model.id),
+			downloader.start(model.id),
+		]);
+		expect(a.jobId).toBe(b.jobId);
+		expect(
+			downloader.snapshot().filter((j) => j.modelId === model.id),
+		).toHaveLength(1);
+		downloader.cancel(model.id);
+	});
+
+	it("rejects a non-GGUF (HTML) body on the single-file path", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const base = findCatalogModel("eliza-1-2b");
+		if (!base) throw new Error("missing test catalog model");
+		// Decorate a default-eligible id as a single-file (non-bundle) download so
+		// it routes through runJob's single-file path.
+		const singleFileSpec: CatalogModel = {
+			...base,
+			hfRepo: "test/single-file",
+			ggufFile: "model.gguf",
+			sizeGb: 0.000001,
+			bundleManifestFile: undefined,
+			bundleManifestSha256: undefined,
+			companionModelIds: [],
+			runtimeRole: undefined,
+		};
+
+		// A gated repo can answer HTTP 200 with an HTML login page.
+		globalThis.fetch = vi.fn(
+			async () =>
+				new Response("<html><body>Sign in to HuggingFace</body></html>", {
+					status: 200,
+					headers: { "content-type": "text/html" },
+				}),
+		) as unknown as typeof fetch;
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			probeHardware: async () => fakeProbe(100),
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === base.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		await downloader.start(singleFileSpec);
+		const job = await failed;
+
+		expect(job.error).toContain("not a valid GGUF");
+		// The HTML body must never be registered or left on disk as a model.
+		const finalPath = path.join(
+			root,
+			"local-inference",
+			"models",
+			"eliza-1-2b.gguf",
+		);
+		// (registry path lives elsewhere; the rejected file is removed regardless)
+		expect(fs.existsSync(finalPath)).toBe(false);
+	});
+
+	it("forwards the Eliza Cloud bearer on a single-file download when cloud-linked", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		// The product never holds a local HF token. When cloud-linked, all HF
+		// resolve traffic is routed through the cloud HF proxy and authenticated
+		// with the Eliza Cloud API key (the proxy attaches the cloud-side HF_TOKEN).
+		const savedKey = process.env.ELIZAOS_CLOUD_API_KEY;
+		process.env.ELIZAOS_CLOUD_API_KEY = "secret-token";
+
+		const base = findCatalogModel("eliza-1-2b");
+		if (!base) throw new Error("missing test catalog model");
+		const singleFileSpec: CatalogModel = {
+			...base,
+			hfRepo: "test/single-file",
+			ggufFile: "model.gguf",
+			sizeGb: 0.000001,
+			bundleManifestFile: undefined,
+			bundleManifestSha256: undefined,
+			companionModelIds: [],
+			runtimeRole: undefined,
+		};
+
+		const ggufBody = Buffer.concat([Buffer.from("GGUF"), Buffer.alloc(60, 0)]);
+		let capturedAuth: string | undefined;
+		globalThis.fetch = vi.fn(
+			async (_url: string | URL | Request, init?: RequestInit) => {
+				const headers = (init?.headers ?? {}) as Record<string, string>;
+				capturedAuth = headers.authorization;
+				return new Response(ggufBody, {
+					status: 200,
+					headers: { "content-length": String(ggufBody.length) },
+				});
+			},
+		) as unknown as typeof fetch;
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			probeHardware: async () => fakeProbe(100),
+		});
+		const completed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === base.id && event.type === "completed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		try {
+			await downloader.start(singleFileSpec);
+			await completed;
+			expect(capturedAuth).toBe("Bearer secret-token");
+		} finally {
+			if (savedKey === undefined) delete process.env.ELIZAOS_CLOUD_API_KEY;
+			else process.env.ELIZAOS_CLOUD_API_KEY = savedKey;
+		}
+	});
+
+	it("blocks a download that does not fit on the models volume", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		// Fetch must never be called: the preflight fails before any byte.
+		const fetchSpy = vi.fn(async () => {
+			throw new Error("network must not be touched when disk is full");
+		});
+		globalThis.fetch = fetchSpy as unknown as typeof fetch;
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			probeHardware: async () => fakeProbe(0.05),
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === model.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		await downloader.start(model.id);
+		const job = await failed;
+
+		expect(job.error).toContain("Not enough disk space");
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+});