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

package/src/services/catalog.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
 	buildHuggingFaceResolveUrl,
 	DEFAULT_ELIGIBLE_MODEL_IDS,
+	ELIZA_1_HOSTED_MTP_TIER_IDS,
 	ELIZA_1_MTP_TIER_IDS,
 	ELIZA_1_TIER_IDS,
 	FIRST_RUN_DEFAULT_MODEL_ID,
@@ -124,16 +125,30 @@ describe("local inference catalog", () => {
 		expect(offenders).toEqual([]);
 	});
 
-	it("declares native MTP on every Eliza-1 tier", () => {
+	it("does not declare native MTP until Gemma drafter GGUFs are hosted", () => {
+		const hostedMtpTiers: ReadonlySet<string> = new Set(
+			ELIZA_1_HOSTED_MTP_TIER_IDS,
+		);
+		expect(ELIZA_1_MTP_TIER_IDS).toEqual(ELIZA_1_TIER_IDS);
+		expect(ELIZA_1_HOSTED_MTP_TIER_IDS).toEqual([]);
 		for (const id of ELIZA_1_MTP_TIER_IDS) {
 			const model = findCatalogModel(id);
-			expect(model?.runtime?.mtp?.specType, `${id} mtp`).toBe("draft-mtp");
+			expect(model?.runtime?.mtp, `${id} mtp`).toBeUndefined();
 			expect(model?.companionModelIds, `${id} companions`).toBeUndefined();
 		}
+		for (const id of ELIZA_1_TIER_IDS.filter(
+			(tier) => !hostedMtpTiers.has(tier),
+		)) {
+			const model = findCatalogModel(id);
+			expect(model?.runtime?.mtp, `${id} mtp`).toBeUndefined();
+		}
 	});
 
 	it("declares the mandatory local runtime contract for every default tier", () => {
-		const baseKernels = ["turbo3", "turbo4", "qjl_full", "polarquant"];
+		const baseKernels = ["turbo3", "turbo4"];
+		const hostedMtpTiers: ReadonlySet<string> = new Set(
+			ELIZA_1_HOSTED_MTP_TIER_IDS,
+		);
 		for (const id of ELIZA_1_TIER_IDS) {
 			const model = findCatalogModel(id);
 			expect(model?.runtime?.preferredBackend, `${id} backend`).toBe(
@@ -145,8 +160,12 @@ describe("local inference catalog", () => {
 					`${id} kernel ${kernel}`,
 				).toContain(kernel);
 			}
-			expect(model?.runtime?.mtp?.specType, `${id} mtp`).toBe("draft-mtp");
 			expect(model?.companionModelIds, `${id} companions`).toBeUndefined();
+			if (hostedMtpTiers.has(id)) {
+				expect(model?.runtime?.mtp?.specType, `${id} mtp`).toBe("draft-mtp");
+			} else {
+				expect(model?.runtime?.mtp, `${id} mtp`).toBeUndefined();
+			}
 			if ((model?.contextLength ?? 0) >= 65536) {
 				expect(model?.runtime?.optimizations?.requiresKernel).toContain(
 					"turbo3_tcq",
@@ -167,13 +186,15 @@ describe("local inference catalog", () => {
 		for (const id of ELIZA_1_TIER_IDS) {
 			const model = findCatalogModel(id);
 			expect(model?.quantization?.defaultVariantId).toBe("q4_k_m");
-			expect(model?.quantization?.variants.map((v) => v.id)).toEqual([
-				"q3_k_m",
-				"q4_k_m",
-				"q5_k_m",
-				"q6_k",
-				"q8_0",
-			]);
+			const variantIds = model?.quantization?.variants.map((v) => v.id);
+			const expected = ["q3_k_m", "q4_0", "q4_k_m", "q5_k_m", "q6_k", "q8_0"];
+			if (id === "eliza-1-2b" || id === "eliza-1-4b") {
+				expected.push("wna8o8");
+			}
+			expect(variantIds).toEqual(expected);
+			expect(
+				model?.quantization?.variants.find((v) => v.id === "q4_0")?.status,
+			).toBe("planned");
 		}
 
 		// Mobile-class tiers (2b/4b) ship Kokoro only — it is smaller +

package/src/services/catalog.ts

@@ -12,6 +12,7 @@ export {
 	buildHuggingFaceResolveUrlForPath,
 	DEFAULT_ELIGIBLE_MODEL_IDS,
 	ELIZA_1_HF_REPO,
+	ELIZA_1_HOSTED_MTP_TIER_IDS,
 	ELIZA_1_MTP_TIER_IDS,
 	ELIZA_1_PLACEHOLDER_IDS,
 	ELIZA_1_RELEASE_TIER_IDS,
@@ -22,6 +23,11 @@ export {
 	eliza1TierPublishStatus,
 	FIRST_RUN_DEFAULT_MODEL_ID,
 	findCatalogModel,
+	hasHuggingFaceToken,
 	isDefaultEligibleId,
+	isHuggingFaceHost,
 	MODEL_CATALOG,
+	resolveHfDownloadBase,
+	resolveHubAuthHeaders,
+	resolveHuggingFaceToken,
 } from "@elizaos/shared";

package/src/services/cloud-fallback.ts

@@ -188,7 +188,7 @@ export function makeCloudFallbackHandler(
 ) => Promise<string> {
 	const log = opts.log ?? (() => undefined);
 	return async (runtime, params) => {
-		const generateParams = params as unknown as GenerateTextParams;
+		const generateParams = params as GenerateTextParams;
 		const local = await opts.localGenerate(runtime, generateParams);
 		if (local.kind === "ok") {
 			return local.text;

package/src/services/context-fit.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { computeRuntimeContextFit } from "./context-fit";
+
+describe("computeRuntimeContextFit", () => {
+	it("shrinks context to the largest 4k window that fits the q8_0 KV budget", () => {
+		const fit = computeRuntimeContextFit({
+			params: "2B",
+			weightMb: 1434,
+			usableMb: 2560,
+			nativeContext: 131072,
+		});
+
+		expect(fit).not.toBeNull();
+		expect(fit?.contextDownscaled).toBe(true);
+		expect(fit?.contextSize).toBeGreaterThanOrEqual(8192);
+		expect(fit?.contextSize).toBeLessThan(131072);
+		expect(fit?.contextSize % 4096).toBe(0);
+		expect(fit?.kvBytesPerToken).toBeGreaterThan(0);
+	});
+
+	it("keeps the native context when the KV budget has headroom", () => {
+		const fit = computeRuntimeContextFit({
+			params: "9B",
+			weightMb: 5529,
+			usableMb: 23 * 1024,
+			nativeContext: 131072,
+		});
+
+		expect(fit?.contextSize).toBe(131072);
+		expect(fit?.contextDownscaled).toBe(false);
+		expect(fit?.maxFittingContext).toBeGreaterThanOrEqual(131072);
+	});
+
+	it("returns null when not even the minimum local context fits", () => {
+		const fit = computeRuntimeContextFit({
+			params: "2B",
+			weightMb: 2200,
+			usableMb: 2300,
+			nativeContext: 131072,
+		});
+
+		expect(fit).toBeNull();
+	});
+
+	it("defaults to q8_0 KV", () => {
+		const fit = computeRuntimeContextFit({
+			params: "9B",
+			weightMb: 5529,
+			usableMb: 64 * 1024,
+			nativeContext: 131072,
+		});
+		expect(fit?.kvQuant).toBe("q8_0");
+	});
+
+	it("upgrades to f16 KV when there's headroom and it's opted in (#8809 AC#4)", () => {
+		const fit = computeRuntimeContextFit({
+			params: "9B",
+			weightMb: 5529,
+			usableMb: 64 * 1024,
+			nativeContext: 131072,
+			preferAccurateKvWhenHeadroom: true,
+		});
+		expect(fit?.kvQuant).toBe("f16");
+		// f16 still affords the full native window on a roomy host.
+		expect(fit?.contextSize).toBe(131072);
+		expect(fit?.contextDownscaled).toBe(false);
+	});
+
+	it("never trades context for f16 KV precision (stays q8_0 when f16 would shrink the window)", () => {
+		// kvBudget here lets q8_0 reach the full native window but f16 (≈1.88×)
+		// would not — so the opt-in must keep q8_0 rather than downscale context.
+		const fit = computeRuntimeContextFit({
+			params: "9B",
+			weightMb: 5529,
+			usableMb: 8053,
+			nativeContext: 131072,
+			preferAccurateKvWhenHeadroom: true,
+		});
+		expect(fit?.contextSize).toBe(131072);
+		expect(fit?.kvQuant).toBe("q8_0");
+	});
+
+	it("scales the selected context with the device RAM class (4/8/16/24/128 GB) (#8809 AC#4)", () => {
+		// One representative tier across the five canonical device classes.
+		// `weightMb` is the resident weight; `usableMb` is the post-headroom
+		// budget the caller (active-model.ts) passes. The q8_0 KV rate comes from
+		// the tier params, so the selected window tracks free RAM.
+		const deviceClassesGb = [4, 8, 16, 24, 128];
+		const fits = deviceClassesGb.map((gb) =>
+			computeRuntimeContextFit({
+				params: "9B",
+				weightMb: 6500,
+				usableMb: gb * 1024,
+				nativeContext: 131072,
+			}),
+		);
+
+		// 4 GB can't hold the weights + a minimum KV window → no fit.
+		expect(fits[0]).toBeNull();
+
+		// Every class that fits gets a 4k-aligned window within [min, native].
+		for (const fit of fits.slice(1)) {
+			expect(fit).not.toBeNull();
+			expect((fit?.contextSize ?? 0) % 4096).toBe(0);
+			expect(fit?.contextSize).toBeGreaterThanOrEqual(8192);
+			expect(fit?.contextSize).toBeLessThanOrEqual(131072);
+		}
+
+		// Context never shrinks as RAM grows (headroom → larger KV window).
+		const sizes = fits.map((f) => f?.contextSize ?? 0);
+		for (let i = 1; i < sizes.length; i++) {
+			expect(sizes[i]).toBeGreaterThanOrEqual(sizes[i - 1]);
+		}
+
+		// Tight-but-fitting (8 GB) downscales below native; roomy (128 GB) hits it.
+		expect(fits[1]?.contextDownscaled).toBe(true);
+		expect(fits[1]?.contextSize).toBeLessThan(131072);
+		expect(fits.at(-1)?.contextSize).toBe(131072);
+		expect(fits.at(-1)?.contextDownscaled).toBe(false);
+	});
+});

package/src/services/context-fit.ts

@@ -0,0 +1,113 @@
+import { ELIZA_1_MIN_LOCAL_CONTEXT } from "@elizaos/shared/local-inference";
+import { estimateQuantizedKvBytesPerToken } from "./kv-spill";
+
+const BYTES_PER_MIB = 1024 * 1024;
+const CONTEXT_STEP = 4096;
+const DEFAULT_WORKING_SET_MB = 1024;
+
+// q8_0 stores the KV cache at 34 bytes / 32 elements; f16 at 2 bytes / element.
+// f16 KV therefore costs ~1.88× the q8_0 per-token rate the estimate is keyed to.
+const F16_OVER_Q8_0_KV_RATIO = 2 / (34 / 32);
+
+export interface RuntimeContextFitInput {
+	params: string;
+	weightMb: number;
+	usableMb: number;
+	nativeContext: number;
+	minContext?: number;
+	workingSetMb?: number;
+	contextStep?: number;
+	/**
+	 * When the host has enough headroom to run the more accurate f16 KV cache at
+	 * (at least) the same window q8_0 would give, prefer f16 instead of leaving
+	 * precision on the table. Opt-in — q8_0 stays the default per the device-fit
+	 * contract; this only ever *upgrades* precision and never trades away context
+	 * (#8809 AC#4). See CONTEXT_SCALING.md §5.
+	 */
+	preferAccurateKvWhenHeadroom?: boolean;
+}
+
+export interface RuntimeContextFit {
+	contextSize: number;
+	contextDownscaled: boolean;
+	maxFittingContext: number;
+	kvBytesPerToken: number;
+	workingSetMb: number;
+	/** The KV cache precision the chosen window was sized against. */
+	kvQuant: "q8_0" | "f16";
+}
+
+function roundDownToStep(value: number, step: number): number {
+	return Math.max(0, Math.floor(value / step) * step);
+}
+
+/**
+ * Choose the runtime context window that fits the current host budget.
+ *
+ * The admission gate still decides whether the model may load at all. This
+ * helper only sizes the q8_0 KV window for an admitted Eliza-1 tier so a tight
+ * host gets the largest safe window instead of blindly taking the catalog
+ * ceiling.
+ */
+export function computeRuntimeContextFit(
+	input: RuntimeContextFitInput,
+): RuntimeContextFit | null {
+	const minContext = input.minContext ?? ELIZA_1_MIN_LOCAL_CONTEXT;
+	const step = input.contextStep ?? CONTEXT_STEP;
+	const workingSetMb = input.workingSetMb ?? DEFAULT_WORKING_SET_MB;
+	if (
+		!Number.isFinite(input.weightMb) ||
+		!Number.isFinite(input.usableMb) ||
+		!Number.isFinite(input.nativeContext) ||
+		input.weightMb <= 0 ||
+		input.usableMb <= 0 ||
+		input.nativeContext < minContext ||
+		step <= 0
+	) {
+		return null;
+	}
+
+	const kvBytesPerToken = estimateQuantizedKvBytesPerToken(input.params);
+	if (!Number.isFinite(kvBytesPerToken) || kvBytesPerToken <= 0) return null;
+
+	const kvBudgetMb = input.usableMb - input.weightMb - workingSetMb;
+	if (kvBudgetMb <= 0) return null;
+	const kvBudgetBytes = kvBudgetMb * BYTES_PER_MIB;
+
+	const q8MaxFittingContext = roundDownToStep(
+		kvBudgetBytes / kvBytesPerToken,
+		step,
+	);
+	if (q8MaxFittingContext < minContext) return null;
+	const q8ContextSize = Math.min(input.nativeContext, q8MaxFittingContext);
+
+	// Default: q8_0 KV, sized to the host. Opt-in headroom upgrade: if f16 KV
+	// still affords at least the q8_0-selected window, use it — more precise, and
+	// never at the cost of context.
+	let kvQuant: "q8_0" | "f16" = "q8_0";
+	let kvBytesPerTokenChosen = kvBytesPerToken;
+	let maxFittingContext = q8MaxFittingContext;
+	let contextSize = q8ContextSize;
+	if (input.preferAccurateKvWhenHeadroom) {
+		const f16BytesPerToken = kvBytesPerToken * F16_OVER_Q8_0_KV_RATIO;
+		const f16MaxFittingContext = roundDownToStep(
+			kvBudgetBytes / f16BytesPerToken,
+			step,
+		);
+		if (f16MaxFittingContext >= q8ContextSize) {
+			kvQuant = "f16";
+			kvBytesPerTokenChosen = f16BytesPerToken;
+			maxFittingContext = f16MaxFittingContext;
+			contextSize = Math.min(input.nativeContext, f16MaxFittingContext);
+		}
+	}
+
+	return {
+		contextSize,
+		contextDownscaled: contextSize < input.nativeContext,
+		maxFittingContext,
+		kvBytesPerToken: kvBytesPerTokenChosen,
+		workingSetMb,
+		kvQuant,
+	};
+}

package/src/services/desktop-fused-ffi-backend-runtime.ts

@@ -8,7 +8,7 @@
  * model.
  *
  *   - The fused lib's `eliza_inference_llm_stream_open` loads the bundle's text
- *     GGUF (`<bundleRoot>/text/*.gguf`) and applies same-file MTP speculative
+ *     GGUF (`<bundleRoot>/text/*.gguf`) and applies MTP speculative
  *     decoding + KV-cache quant + per-load GPU layers natively (ABI v9). The
  *     path is gated on the capability probes
  *     (`llmStreamSupported && llmMtpSupported && llmKvQuantSupported`).
@@ -44,6 +44,13 @@ import {
 	loadElizaInferenceFfi,
 } from "./voice/ffi-bindings";
 
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("Aborted", "AbortError");
+}
+
 /**
  * Candidate filenames for the fused library, per platform. Mirrors
  * `samantha-preset-regenerator.ts::libraryFilenames` so the runtime and the
@@ -116,7 +123,7 @@ export class DesktopFusedFfiBackendRuntime implements FfiBackendRuntime {
 	 * Viable only when:
 	 *   - bun:ffi resolves on the current runtime,
 	 *   - the fused dylib is present AND reports ABI-v9 capability: the
-	 *     streaming-LLM surface, same-file MTP, KV-cache quant, AND native
+	 *     streaming-LLM surface, MTP, KV-cache quant, AND native
 	 *     tokenization (`eliza_inference_tokenize`).
 	 * A pre-v9 fused lib reports the probes as unsupported → refused, and the
 	 * engine raises LocalInferenceUnavailable. libllama has been retired; there
@@ -237,8 +244,13 @@ export class DesktopFusedFfiBackendRuntime implements FfiBackendRuntime {
 			draftModelPath: overrides?.draftModelPath ?? null,
 			mmprojPath: overrides?.mmprojPath ?? null,
 			// The fused path applies these at its first `llmStreamOpen`:
-			// gpuLayers + KV-cache quant types from the session config.
+			// context size, gpuLayers, and KV-cache quant types from the
+			// session config.
 			loadConfig: {
+				contextSize:
+					typeof overrides?.contextSize === "number"
+						? overrides.contextSize
+						: undefined,
 				gpuLayers:
 					typeof overrides?.gpuLayers === "number"
 						? overrides.gpuLayers
@@ -272,10 +284,35 @@ export class DesktopFusedFfiBackendRuntime implements FfiBackendRuntime {
 	}
 
 	/**
-	 * Vision describe through the fused `eliza_inference_describe_image`
-	 * (ABI v9). Reuses the mtmd machinery linked for ASR over the bundle's text
-	 * model + the passed mmproj projector. The `FfiStreamingBackend` forwards
-	 * `describeImage`/`visionSupported` to this runtime by duck-typing.
+	 * Whether the LIVE session can STREAM a vision describe token-by-token
+	 * through `eliza_inference_describe_image_stream_open` + the existing
+	 * `llmStreamNext` loop (ABI v13). A <=v12 lib reports false and the handler
+	 * uses the buffered one-shot `describeImage` path.
+	 */
+	visionStreamSupported(): boolean {
+		if (!this.active) return false;
+		const { ffi } = this.active;
+		return (
+			typeof ffi.visionStreamSupported === "function" &&
+			ffi.visionStreamSupported() === true &&
+			typeof ffi.describeImageStreamOpen === "function" &&
+			typeof ffi.llmStreamNext === "function" &&
+			typeof ffi.llmStreamClose === "function"
+		);
+	}
+
+	/**
+	 * Vision describe through the fused mmproj path. Reuses the mtmd machinery
+	 * linked for ASR over the bundle's text model + the passed mmproj projector.
+	 * The `FfiStreamingBackend` forwards `describeImage`/`visionSupported` to this
+	 * runtime by duck-typing.
+	 *
+	 * When `onTextChunk` is supplied AND the fused lib exposes ABI-v13 streaming
+	 * vision, the description is decoded token-by-token: `describeImageStreamOpen`
+	 * primes a stream with the image+prompt KV and the EXISTING `llmStreamNext`
+	 * loop pulls tokens — the same machinery that streams chat text, so vision
+	 * flows into the dashboard through one pipe. Otherwise it falls back to the
+	 * buffered one-shot `eliza_inference_describe_image`.
 	 */
 	async describeImage(args: {
 		imageBytes: Uint8Array;
@@ -284,6 +321,8 @@ export class DesktopFusedFfiBackendRuntime implements FfiBackendRuntime {
 		maxTokens?: number;
 		temperature?: number;
 		signal?: AbortSignal;
+		onTextChunk?: (chunk: string) => void | Promise<void>;
+		maxTokensPerStep?: number;
 	}): Promise<{ text: string; projectorMs?: number; decodeMs?: number }> {
 		if (!this.active) {
 			throw new Error(
@@ -302,6 +341,59 @@ export class DesktopFusedFfiBackendRuntime implements FfiBackendRuntime {
 					"lib with -DELIZA_ENABLE_VISION=ON (verify-fused-symbols requires it).",
 			);
 		}
+
+		// Token-by-token streaming path (ABI v13): open a vision stream and drive
+		// the shared `llmStreamNext` loop, surfacing each decoded piece through
+		// `onTextChunk` so the description renders as it generates.
+		if (
+			typeof args.onTextChunk === "function" &&
+			this.visionStreamSupported() &&
+			typeof ffi.describeImageStreamOpen === "function" &&
+			typeof ffi.llmStreamNext === "function" &&
+			typeof ffi.llmStreamClose === "function"
+		) {
+			throwIfAborted(args.signal);
+			const startedAt = Date.now();
+			const stream = ffi.describeImageStreamOpen({
+				ctx,
+				imageBytes: args.imageBytes,
+				mmprojPath: args.mmprojPath,
+				prompt: args.prompt,
+			});
+			let full = "";
+			let generated = 0;
+			// JS-side token budget: the native ELIZA_VISION_MAX_TOKENS env does not
+			// reliably reach the loaded DLL's getenv across runtimes, so cap here.
+			const tokenBudget =
+				typeof args.maxTokens === "number" && args.maxTokens > 0
+					? args.maxTokens
+					: 256;
+			try {
+				for (;;) {
+					if (args.signal?.aborted) {
+						ffi.llmStreamCancel?.(stream);
+						throwIfAborted(args.signal);
+					}
+					const step = ffi.llmStreamNext({
+						stream,
+						// Fine-grained by default so the description renders token-by-token
+						// in the dashboard rather than in coarse ~32-token jumps (matches
+						// the tuned chat default). Callers may override per request.
+						maxTokensPerStep: args.maxTokensPerStep ?? 8,
+					});
+					if (step.text.length > 0) {
+						full += step.text;
+						await args.onTextChunk(step.text);
+					}
+					generated += step.tokens.length;
+					if (step.done || generated >= tokenBudget) break;
+				}
+			} finally {
+				ffi.llmStreamClose(stream);
+			}
+			return { text: full, decodeMs: Date.now() - startedAt };
+		}
+
 		const startedAt = Date.now();
 		const text = ffi.describeImage({
 			ctx,

package/src/services/device-tier.test.ts

@@ -4,6 +4,7 @@ import {
 	DEVICE_TIER_ORDER,
 	DEVICE_TIER_THRESHOLDS,
 	effectiveModelMemoryGb,
+	selectBestEliza1FitForDevice,
 	TIER_WARNING_COPY,
 } from "./device-tier";
 import type { HardwareProbe } from "./types";
@@ -24,6 +25,90 @@ function probe(overrides: Partial<HardwareProbe>): HardwareProbe {
 	return { ...baseProbe, ...overrides };
 }
 
+describe("selectBestEliza1FitForDevice — mobile guard never hands a phone 9B", () => {
+	const prevPlatform = process.env.ELIZA_PLATFORM;
+	function withPlatform(value: string | undefined, fn: () => void) {
+		if (value === undefined) delete process.env.ELIZA_PLATFORM;
+		else process.env.ELIZA_PLATFORM = value;
+		try {
+			fn();
+		} finally {
+			if (prevPlatform === undefined) delete process.env.ELIZA_PLATFORM;
+			else process.env.ELIZA_PLATFORM = prevPlatform;
+		}
+	}
+
+	// The on-device bun probe: reports linux + arm64 + no gpu + no mobile field.
+	const devicePhoneProbe = probe({
+		totalRamGb: 7.4,
+		freeRamGb: 3.3,
+		gpu: null,
+		arch: "arm64",
+		platform: "linux",
+	});
+
+	it("this 8GB phone lands on 2B with a phone-sized window", () => {
+		withPlatform("android", () => {
+			const fit = selectBestEliza1FitForDevice(devicePhoneProbe);
+			expect(fit?.tierId).toBe("eliza-1-2b");
+			expect(fit?.contextLength).toBeLessThanOrEqual(65536);
+		});
+	});
+
+	it("caps a HIGH-RAM phone at 4B (never 9B+) even when the probe says linux", () => {
+		const bigPhone = probe({
+			totalRamGb: 24,
+			freeRamGb: 16,
+			gpu: null,
+			arch: "arm64",
+			platform: "linux",
+		});
+		withPlatform("android", () => {
+			const fit = selectBestEliza1FitForDevice(bigPhone);
+			expect(["eliza-1-2b", "eliza-1-4b"]).toContain(fit?.tierId);
+			expect(fit?.tierId).not.toBe("eliza-1-9b");
+			expect(fit?.contextLength).toBeLessThanOrEqual(65536);
+		});
+	});
+
+	it("arm64 phones never hit the AVX2/NEON POOR gate (NEON is mandatory on ARMv8)", () => {
+		// The on-device os-fallback probe (Pixel 9a) reports arm64 + no cpuFeatures.
+		// Before the fix it fell to "No AVX2 baseline" → POOR; that wrong reason must
+		// be gone (NEON is mandatory on ARMv8).
+		const assessment = classifyDeviceTier(devicePhoneProbe);
+		expect(assessment.reasons.some((r) => /AVX2|< 4 CPU cores/i.test(r))).toBe(
+			false,
+		);
+		// A 16GB arm64 phone (above the mobile floor) with no cpuFeatures now runs
+		// local instead of being misclassified cloud-only by the SIMD gate.
+		const midPhone = probe({
+			totalRamGb: 16,
+			freeRamGb: 9,
+			gpu: null,
+			arch: "arm64",
+			cpuFeatures: undefined,
+		});
+		expect(classifyDeviceTier(midPhone).canRunLocalLm).toBe(true);
+	});
+
+	it("an 8GB phone is OKAY / local-capable (runs eliza-1 2B), not cloud-only POOR", () => {
+		withPlatform("android", () => {
+			const assessment = classifyDeviceTier(devicePhoneProbe);
+			expect(assessment.tier).toBe("OKAY");
+			expect(assessment.canRunLocalLm).toBe(true);
+		});
+	});
+
+	it("the SAME 24GB box as a desktop (no android env) may use a larger tier", () => {
+		const bigBox = probe({ totalRamGb: 48, freeRamGb: 40, gpu: null });
+		withPlatform(undefined, () => {
+			const fit = selectBestEliza1FitForDevice(bigBox);
+			// effective = 48*0.5 = 24 → 9B fits on a desktop (not capped).
+			expect(fit?.tierId).toBe("eliza-1-9b");
+		});
+	});
+});
+
 describe("classifyDeviceTier", () => {
 	describe("MAX tier", () => {
 		it("classifies a CUDA workstation with 24 GB VRAM as MAX", () => {
@@ -197,7 +282,9 @@ describe("classifyDeviceTier", () => {
 			expect(result.reasons.join(" ")).toMatch(/AVX2|cores/);
 		});
 
-		it("classifies ARM without CPU feature evidence as POOR", () => {
+		it("classifies 32-bit ARM (ARMv7) without NEON evidence as POOR", () => {
+			// NEON is optional on 32-bit ARMv7, so we still require explicit feature
+			// evidence there (unlike arm64/ARMv8, where NEON is mandatory).
 			const result = classifyDeviceTier(
 				probe({
 					totalRamGb: 32,
@@ -205,7 +292,7 @@ describe("classifyDeviceTier", () => {
 					gpu: null,
 					cpuCores: 8,
 					platform: "linux",
-					arch: "arm64",
+					arch: "arm",
 					cpuFeatures: undefined,
 				}),
 			);