pi-multimodal-proxy 1.16.1 → 1.18.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.18.0] - 2026-08-30
+
+### Added
+
+- **Key-aware default model resolution.** The implicit vision default now resolves to a model the user can actually call: when the configured default (`zai/glm-5.3-flash`) is not usable — missing from the catalog **or its provider has no API key** — `applyDefaultModelFallback` walks a preference-ordered candidate chain and picks the first entry that is both in the registry and keyed. `DEFAULT_MODEL_FALLBACKS` gained `deepseek/deepseek-v4-flash-vision-exp` (vision-capable via the built-in DeepSeek provider since Pi 0.84.4, ≈$0.22/M in) ahead of the Claude fallbacks. Safety rules: a keyed legacy default is never traded for an unkeyed model; explicit choices (`modelExplicit`, `PI_VISION_PROXY_MODEL`) are never rewritten; when nothing is keyed the catalog-only behavior applies so first use still surfaces the actionable "No API key — pi --login" notice. `withModelFallback` became async and probes keys via `ModelRegistry.getApiKeyAndHeaders` with a per-session cache; substitutions are announced once per session (`notifyDefaultSubstitution`) from `session_start` / `before_agent_start`.
+- **Content-sniffed image validation** (Pi ≥ 0.84.4, graceful on older runtimes). `readImageFileWithReason` accepts an injectable sniffer backed by Pi's newly exported `detectSupportedImageMimeTypeFromFile`; new pure helper `decideImageMime` merges the extension map with the sniff: sniffed type wins (corrects mis-typed files), a sniff that finds no image rejects files whose extension is inside the sniffer's coverage (new reason `invalid-image`), PNG-signature files the sniffer rejects as animated still pass as `image/png` (APNG passthrough), formats outside coverage (tiff/ico/avif) and sniffer-unavailable runtimes keep the extension-only path, and extensionless files with recognizable contents are now accepted. The sniffer fails open: a throwing sniffer degrades to extension-only.
+- **`/multimodal-proxy doctor`** — one-shot setup diagnostics covering effective model resolution (explicit / implicit / substituted), catalog presence, API keys, data-egress consent, fallback and video model, yt-dlp/ffmpeg availability (with versions), path-detection/allowlist state, and in-memory recall-store usage. Also available from the interactive menu.
+- **`/multimodal-proxy test`** — end-to-end self-test: generates a tiny gradient PNG locally (ImageScript, no fixture file), runs it through the full describe pipeline (model resolution → key check → consent → retry/backoff → upload), and reports the model, latency, and description (or the failure pointer to `doctor`). Also available from the interactive menu.
+- **Hardened syntax gate** (`tools/check-syntax.mjs` stage 2): beside the existing parse-only check, a `ts.createProgram` pass filtered to syntax-range diagnostic codes (< 2000) catches constructs the parser alone accepts but the runtime rejects — most notably `await` inside a non-async function (introduced and caught during this release's review; it crash-loops every pi loading the package, the exact 1.16.1 incident class). Type-level noise (TS2xxx) stays out of the gate, so the baseline is zero.
+
+## [1.17.0] - 2026-08-27
+
+### Changed
+
+- **Default vision model is now GLM 5.3 Flash (`zai/glm-5.3-flash`).** `DEFAULT_CONFIG` ships `zai/glm-5.3-flash` (image input, 1M context, $0.075/M input — $0.25/M output) as the default image-description model, replacing `anthropic/claude-sonnet-5`. Implicit configs keep tracking the package default: `anthropic/claude-sonnet-5` was added to `LEGACY_DEFAULT_MODELS` (so configs that merely inherited Sonnet 5 upgrade to GLM 5.3 Flash once it's in the catalog), `DEFAULT_MODEL_FALLBACKS` now tries `anthropic/claude-sonnet-5` and then `anthropic/claude-sonnet-4-5` on catalogs without GLM 5.3 Flash, and explicit choices (`modelExplicit`, `PI_VISION_PROXY_MODEL`) are never rewritten. README (What's new, env-table default, privacy note, requirements) and the `/multimodal-proxy model` usage example updated to the new default.
+
 ## [1.16.1] - 2026-08-22
 
 ### Fixed

package/README.md

@@ -8,6 +8,17 @@ When **video or audio files** are detected, they are routed to a **multimodal mo
 
 **YouTube links** are detected too: paste a URL (`youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`, etc.) and the video is downloaded with [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) and analyzed exactly like a local file.
 
+## What's new in 1.18.0
+
+- **Key-aware default model resolution** — the implicit vision default now lands on a model you can actually call. If the default (`zai/glm-5.3-flash`) has no API key in your setup, the proxy walks a preference-ordered candidate chain — `zai/glm-5.3-flash` → `deepseek/deepseek-v4-flash-vision-exp` (new in Pi 0.84.4, cheap, built-in provider) → `anthropic/claude-sonnet-5` — and picks the first candidate that is in the catalog **and keyed**. A keyed legacy default is never traded for an unkeyed model; explicit choices (`/multimodal-proxy model`, `pick`, `PI_VISION_PROXY_MODEL`) are still never rewritten; and when nothing is keyed you get the actionable `pi --login` hint as before. A substitution is announced once per session.
+- **Content-sniffed image validation** (Pi ≥ 0.84.4, graceful on older) — image files are validated by magic bytes via Pi's exported `detectSupportedImageMimeTypeFromFile()`: a `notes.png` that is really a PDF is rejected with a clear `invalid-image` reason instead of being shipped to the vision model, mis-typed extensions are **corrected** (a JPEG named `.png` uploads as `image/jpeg`), extensionless files with recognizable contents are accepted, and formats outside the sniffer's coverage (tiff/ico/avif) keep the extension-only path. APNG still passes as `image/png`.
+- **`/multimodal-proxy doctor`** — one-shot setup diagnostics: effective model (explicit / implicit / substituted), catalog presence, API keys, consent state, fallback + video model, yt-dlp & ffmpeg availability, path access, and recall-store usage.
+- **`/multimodal-proxy test`** — end-to-end self-test: synthesizes a tiny gradient image locally and describes it through the full pipeline (model resolution → key → consent → retry → upload), reporting the model, latency, and result. No fixture files, no extra setup.
+
+## What's new in 1.17.0
+
+- **Default vision model is now GLM 5.3 Flash** (`zai/glm-5.3-flash`) — fast, cheap image description ($0.075/M input, $0.25/M output) with a 1M-token context window. Models you never chose explicitly track the package default: configs that merely inherited the old default (`anthropic/claude-sonnet-5`) are upgraded when GLM 5.3 Flash is in the catalog, and on Pi versions without it the default falls back to `anthropic/claude-sonnet-5` (then `anthropic/claude-sonnet-4-5` on the oldest catalogs). Models chosen explicitly — via `/multimodal-proxy model`, `pick`, or `PI_VISION_PROXY_MODEL` — are never rewritten. **Heads-up:** the default provider is now Z.ai — you need a `zai` API key and will be asked for first-use data-egress consent unless you pin a different model (e.g. `/multimodal-proxy model anthropic/claude-sonnet-5`).
+
 ## What's new in 1.16.0
 
 Reliability features borrowed from a survey of [atlas-vision-mcp](https://github.com/QuangThai/vision-bridge-mcp) (ideas worth stealing, implementation our own):
@@ -148,6 +159,8 @@ Settings persist across sessions in `~/.pi/agent/multimodal-proxy.json`. Environ
 /multimodal-proxy allow-home on | off                  → allow reading media anywhere under your home folder
 /multimodal-proxy path-detection on | off              → auto-load media file paths found in prompt text (off = attachments only)
 /multimodal-proxy describe <path>... [--question "<text>"] [--crop <i>:<form>] [--model <provider/id>] [--save]
+/multimodal-proxy doctor                                → one-shot setup diagnostics (model, keys, consent, yt-dlp/ffmpeg, paths, recall)
+/multimodal-proxy test                                  → end-to-end self-test with a locally generated image
 
 Legacy alias: /vision-proxy <args> works identically.
 ```
@@ -157,7 +170,7 @@ Legacy alias: /vision-proxy <args> works identically.
 | Variable | Values | Default |
 |----------|--------|---------|
 | `PI_VISION_PROXY_MODE` | `fallback`, `always`, `off` | `fallback` |
-| `PI_VISION_PROXY_MODEL` | `provider/model-id` | `anthropic/claude-sonnet-5` |
+| `PI_VISION_PROXY_MODEL` | `provider/model-id` | `zai/glm-5.3-flash` |
 | `PI_VISION_PROXY_INCLUDE_CONTEXT` | bool | `true` |
 | `PI_VISION_PROXY_TOOL` | `on`, `off` | `on` |
 | `PI_VISION_PROXY_MAX_IMAGES_PER_CALL` | 1–20 | `10` |
@@ -306,7 +319,7 @@ When a model is in the grounding registry, a format-specific instruction is appe
 
 ## Privacy & security
 
-This extension **sends data to a third-party provider**. By default that is `anthropic/claude-sonnet-5` for images (`anthropic/claude-sonnet-4-5` on older Pi versions without Sonnet 5 in the catalog) and `xai/grok-4.3` for video/audio. Be aware:
+This extension **sends data to a third-party provider**. By default that is `zai/glm-5.3-flash` for images (`anthropic/claude-sonnet-5` on older Pi versions without GLM 5.3 Flash in the catalog, then `anthropic/claude-sonnet-4-5`) and `xai/grok-4.3` for video/audio. Be aware:
 
 1. **Image and video data is uploaded** to the configured provider on every proxied request. Crop coordinates are applied locally before upload — only the cropped region is sent.
 2. **Recent conversation context** (last 8 messages, truncated) is uploaded with the image unless you set `/multimodal-proxy context off` or `PI_VISION_PROXY_INCLUDE_CONTEXT=false`. Disable it for sensitive sessions.
@@ -325,9 +338,10 @@ For the full security audit see [`SECURITY-REVIEW.md`](./SECURITY-REVIEW.md).
 
 ## Requirements
 
-- A vision-capable model with a valid API key (e.g. Claude, GPT-4o, Gemini, Qwen-VL)
+- A vision-capable model with a valid API key (e.g. GLM 5.3 Flash, Claude, GPT-4o, Gemini, Qwen-VL) — any provider you already have a key for works; the implicit default picks a keyed model automatically (1.18.0)
 - For video/audio: a multimodal model that supports video input (e.g. Grok 4.3, Gemini 2.5 Pro)
 - The models must be registered in Pi (built-in or via `models.json`)
+- Optional: Pi ≥ 0.84.4 enables content-sniffed image validation (mis-typed extensions are corrected or rejected); older versions keep the extension-only path
 
 ## License
 

package/extensions/__tests__/internal.test.ts

@@ -1466,6 +1466,62 @@ describe("readImageFileWithReason", () => {
 			await rm(dir, { recursive: true, force: true });
 		}
 	});
+
+	it("rejects a mis-typed image via the injected sniffer (invalid-image)", async () => {
+		const dir = await mkdtemp(join(os.tmpdir(), "vp-test-"));
+		const file = join(dir, "fake.png");
+		const contents = Buffer.from("this is actually text, not an image");
+		await writeFile(file, contents);
+		try {
+			const r = await readImageFileWithReason(file, undefined, async () => null);
+			assert.equal(r.image, null);
+			assert.equal(r.reason, "invalid-image");
+			assert.equal(r.bytes, contents.length);
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("corrects the MIME type when the sniff disagrees with the extension", async () => {
+		const dir = await mkdtemp(join(os.tmpdir(), "vp-test-"));
+		const file = join(dir, "actually-jpeg.png");
+		await writeFile(file, Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0, 16, 0x4a, 0x46, 0x49, 0x46]));
+		try {
+			const r = await readImageFileWithReason(file, undefined, async () => "image/jpeg");
+			assert.ok(r.image, "image should be returned");
+			assert.equal(r.image?.mimeType, "image/jpeg");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("accepts an unknown extension when the sniffer recognizes the contents", async () => {
+		const dir = await mkdtemp(join(os.tmpdir(), "vp-test-"));
+		const file = join(dir, "no-extension");
+		await writeFile(file, TINY_PNG);
+		try {
+			const r = await readImageFileWithReason(file, undefined, async () => "image/png");
+			assert.ok(r.image, "image should be returned");
+			assert.equal(r.image?.mimeType, "image/png");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("degrades to extension-only when the sniffer throws", async () => {
+		const dir = await mkdtemp(join(os.tmpdir(), "vp-test-"));
+		const file = join(dir, "ok.png");
+		await writeFile(file, TINY_PNG);
+		try {
+			const r = await readImageFileWithReason(file, undefined, async () => {
+				throw new Error("sniffer exploded");
+			});
+			assert.ok(r.image, "image should be returned");
+			assert.equal(r.image?.mimeType, "image/png");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
 });
 
 describe("readMediaFileWithReason", () => {
@@ -3023,7 +3079,7 @@ describe("Review fixes: storeImageMeta filename backfill", () => {
 
 // ── Default model fallback (1.8.0) ──────────────────────────────────────────
 
-import { applyDefaultModelFallback, DEFAULT_MODEL_FALLBACKS } from "../internal.ts";
+import { applyDefaultModelFallback, DEFAULT_MODEL_FALLBACKS, decideImageMime, SNIFFABLE_IMAGE_MIMES } from "../internal.ts";
 
 describe("applyDefaultModelFallback", () => {
 	const registryWith = (...models: string[]) => (p: string, m: string) => models.includes(`${p}/${m}`);
@@ -3100,6 +3156,153 @@ describe("applyDefaultModelFallback", () => {
 	});
 });
 
+describe("1.18.0 key-aware default model resolution", () => {
+	const registryWith = (...models: string[]) => (p: string, m: string) => models.includes(`${p}/${m}`);
+	const keyWith = (...keyed: string[]) => (p: string, m: string) => keyed.includes(`${p}/${m}`);
+	const builtin = { ...DEFAULT_CONFIG };
+	const deepseek = DEFAULT_MODEL_FALLBACKS.find((m) => m.provider === "deepseek")!;
+	const sonnet5 = { provider: "anthropic", modelId: "claude-sonnet-5" };
+
+	it("lists the DeepSeek vision model first among fallbacks", () => {
+		assert.equal(DEFAULT_MODEL_FALLBACKS[0]!.provider, "deepseek");
+		assert.equal(DEFAULT_MODEL_FALLBACKS[0]!.modelId, "deepseek-v4-flash-vision-exp");
+	});
+
+	it("keeps the default when it is in the catalog and keyed", () => {
+		const out = applyDefaultModelFallback(
+			builtin,
+			registryWith(`${builtin.provider}/${builtin.modelId}`),
+			false,
+			keyWith(`${builtin.provider}/${builtin.modelId}`),
+		);
+		assert.equal(out.modelId, DEFAULT_CONFIG.modelId);
+	});
+
+	it("substitutes the first keyed candidate when the default has no key", () => {
+		const out = applyDefaultModelFallback(
+			builtin,
+			registryWith(`${builtin.provider}/${builtin.modelId}`, `${deepseek.provider}/${deepseek.modelId}`, "anthropic/claude-sonnet-5"),
+			false,
+			keyWith(`${deepseek.provider}/${deepseek.modelId}`, "anthropic/claude-sonnet-5"),
+		);
+		assert.equal(out.provider, deepseek.provider);
+		assert.equal(out.modelId, deepseek.modelId);
+	});
+
+	it("skips unkeyed candidates and picks the next keyed one", () => {
+		const out = applyDefaultModelFallback(
+			builtin,
+			registryWith(`${builtin.provider}/${builtin.modelId}`, `${deepseek.provider}/${deepseek.modelId}`, "anthropic/claude-sonnet-5"),
+			false,
+			keyWith("anthropic/claude-sonnet-5"),
+		);
+		assert.equal(out.provider, "anthropic");
+		assert.equal(out.modelId, "claude-sonnet-5");
+	});
+
+	it("keeps the in-catalog default when nothing is keyed (login-hint path)", () => {
+		const out = applyDefaultModelFallback(
+			builtin,
+			registryWith(`${builtin.provider}/${builtin.modelId}`, "anthropic/claude-sonnet-5"),
+			false,
+			() => false,
+		);
+		assert.equal(out.modelId, DEFAULT_CONFIG.modelId);
+	});
+
+	it("prefers a keyed legacy default over an unkeyed current default", () => {
+		const legacy = { ...DEFAULT_CONFIG, ...sonnet5 };
+		const out = applyDefaultModelFallback(
+			legacy,
+			registryWith(`${builtin.provider}/${builtin.modelId}`, "anthropic/claude-sonnet-5"),
+			false,
+			keyWith("anthropic/claude-sonnet-5"),
+		);
+		assert.equal(out.provider, "anthropic");
+		assert.equal(out.modelId, "claude-sonnet-5");
+	});
+
+	it("substitutes a keyed chain member for an unkeyed legacy default", () => {
+		const legacy = { ...DEFAULT_CONFIG, ...sonnet5 };
+		const out = applyDefaultModelFallback(
+			legacy,
+			registryWith("anthropic/claude-sonnet-5", `${deepseek.provider}/${deepseek.modelId}`),
+			false,
+			keyWith(`${deepseek.provider}/${deepseek.modelId}`),
+		);
+		assert.equal(out.provider, deepseek.provider);
+		assert.equal(out.modelId, deepseek.modelId);
+	});
+
+	it("never rewrites an explicit choice even with key information", () => {
+		const explicit = { ...DEFAULT_CONFIG, modelExplicit: true };
+		const out = applyDefaultModelFallback(
+			explicit,
+			registryWith(`${deepseek.provider}/${deepseek.modelId}`),
+			false,
+			keyWith(`${deepseek.provider}/${deepseek.modelId}`),
+		);
+		assert.equal(out.modelId, DEFAULT_CONFIG.modelId);
+	});
+
+	it("does not mutate other config fields when substituting for a keyed candidate", () => {
+		const cfg = { ...DEFAULT_CONFIG, mode: "always" as const, cacheSize: 9 };
+		const out = applyDefaultModelFallback(
+			cfg,
+			registryWith(`${deepseek.provider}/${deepseek.modelId}`),
+			false,
+			keyWith(`${deepseek.provider}/${deepseek.modelId}`),
+		);
+		assert.equal(out.mode, "always");
+		assert.equal(out.cacheSize, 9);
+	});
+});
+
+describe("decideImageMime (content sniffing)", () => {
+	const pngHead = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13]);
+
+	it("sniffed type wins over the extension", () => {
+		const out = decideImageMime("image/png", "image/jpeg", pngHead);
+		assert.deepEqual(out, { mime: "image/jpeg" });
+	});
+
+	it("rejects an in-coverage extension whose contents are not an image", () => {
+		const out = decideImageMime("image/png", null, new TextEncoder().encode("hello world"));
+		assert.deepEqual(out, { reject: true });
+	});
+
+	it("accepts a PNG-signature file the sniffer rejected (APNG passthrough)", () => {
+		const out = decideImageMime("image/png", null, pngHead);
+		assert.deepEqual(out, { mime: "image/png" });
+	});
+
+	it("trusts extensions outside sniffer coverage when the sniff finds nothing", () => {
+		const out = decideImageMime("image/tiff", null, new TextEncoder().encode("whatever"));
+		assert.deepEqual(out, { mime: "image/tiff" });
+	});
+
+	it("falls back to the extension map when the sniffer is unavailable", () => {
+		const out = decideImageMime("image/png", undefined, new TextEncoder().encode("not really"));
+		assert.deepEqual(out, { mime: "image/png" });
+	});
+
+	it("returns no mime for an unknown extension without a sniffer", () => {
+		const out = decideImageMime(undefined, undefined, pngHead);
+		assert.equal(out.mime, undefined);
+		assert.equal(out.reject, undefined);
+	});
+
+	it("coverage set matches the formats Pi's sniffer validates", () => {
+		assert.ok(SNIFFABLE_IMAGE_MIMES.has("image/jpeg"));
+		assert.ok(SNIFFABLE_IMAGE_MIMES.has("image/png"));
+		assert.ok(SNIFFABLE_IMAGE_MIMES.has("image/gif"));
+		assert.ok(SNIFFABLE_IMAGE_MIMES.has("image/webp"));
+		assert.ok(SNIFFABLE_IMAGE_MIMES.has("image/bmp"));
+		assert.ok(!SNIFFABLE_IMAGE_MIMES.has("image/tiff"));
+		assert.ok(!SNIFFABLE_IMAGE_MIMES.has("image/avif"));
+	});
+});
+
 describe("1.16.0 reliability: config defaults & sanitize", () => {
 	it("defaults retryMax / maxUploadDim / maxUploadBytes, no fallback model", () => {
 		const cfg = resolveConfig([], {});

package/extensions/internal.ts

@@ -681,8 +681,8 @@ export const DEFAULT_VIDEO_SYSTEM_PROMPT = [
 
 export const DEFAULT_CONFIG: VisionConfig = {
 	mode: "fallback",
-	provider: "anthropic",
-	modelId: "claude-sonnet-5",
+	provider: "zai",
+	modelId: "glm-5.3-flash",
 	systemPrompt: [
 		"You are a precise image analysis assistant.",
 		"Describe the image factually for a downstream agent that may act on the description.",
@@ -1261,9 +1261,14 @@ export function resolveConfig(
 
 /**
  * Ordered fallbacks tried when the built-in default vision model is missing
- * from the model registry — e.g. Pi < 0.80.3 catalogs without Claude Sonnet 5.
+ * from the model registry — e.g. Pi catalogs that predate GLM 5.3 Flash. The
+ * same list (prefixed with the current default) forms the key-aware candidate
+ * chain: the first candidate that is both in the registry and has an API key
+ * wins when the default itself isn't usable.
  */
 export const DEFAULT_MODEL_FALLBACKS: ReadonlyArray<{ provider: string; modelId: string }> = [
+	{ provider: "deepseek", modelId: "deepseek-v4-flash-vision-exp" }, // Pi ≥ 0.84.4, cheap, common key
+	{ provider: "anthropic", modelId: "claude-sonnet-5" },
 	{ provider: "anthropic", modelId: "claude-sonnet-4-5" },
 ];
 
@@ -1274,6 +1279,7 @@ export const DEFAULT_MODEL_FALLBACKS: ReadonlyArray<{ provider: string; modelId:
  * model" and may track the current package default.
  */
 export const LEGACY_DEFAULT_MODELS: ReadonlyArray<{ provider: string; modelId: string }> = [
+	{ provider: "anthropic", modelId: "claude-sonnet-5" },
 	{ provider: "anthropic", modelId: "claude-sonnet-4-5" },
 ];
 
@@ -1284,36 +1290,76 @@ export const LEGACY_DEFAULT_MODELS: ReadonlyArray<{ provider: string; modelId: s
  * - a legacy baked-in default is upgraded to the current package default when
  *   the registry has it (otherwise it keeps working as-is);
  * - the current default is substituted with the first available fallback when
- *   the registry doesn't know it (older Pi catalogs).
+ *   the registry doesn't know it (older Pi catalogs);
+ * - with `hasKey` (optional, 1.18.0) resolution is key-aware: a candidate only
+ *   wins when it is in the registry AND its provider has an API key, so the
+ *   implicit default lands on a model the user can actually call. A keyed
+ *   legacy default is never traded for an unkeyed model, and when nothing is
+ *   keyed the catalog-only rules above apply unchanged (the first image then
+ *   fails with the actionable "No API key … pi --login" notice).
  *
  * Explicit choices are never rewritten: `userConfigured` (the caller saw
  * PI_VISION_PROXY_MODEL) or `config.modelExplicit` (persisted via
- * /multimodal-proxy model|pick) disable both substitutions, so a missing
+ * /multimodal-proxy model|pick) disable all substitutions, so a missing
  * explicit model still surfaces as "Model not found".
  */
 export function applyDefaultModelFallback(
 	config: VisionConfig,
 	hasModel: (provider: string, modelId: string) => boolean,
 	userConfigured = false,
+	hasKey?: (provider: string, modelId: string) => boolean,
 ): VisionConfig {
 	if (userConfigured || config.modelExplicit === true) return config;
 
-	const isCurrentDefault =
-		config.provider === DEFAULT_CONFIG.provider && config.modelId === DEFAULT_CONFIG.modelId;
-	if (!isCurrentDefault) {
-		const isLegacyDefault = LEGACY_DEFAULT_MODELS.some(
-			(m) => m.provider === config.provider && m.modelId === config.modelId,
-		);
-		if (isLegacyDefault && hasModel(DEFAULT_CONFIG.provider, DEFAULT_CONFIG.modelId)) {
-			return { ...config, provider: DEFAULT_CONFIG.provider, modelId: DEFAULT_CONFIG.modelId };
+	const currentDefault = { provider: DEFAULT_CONFIG.provider, modelId: DEFAULT_CONFIG.modelId };
+	const isSame = (m: { provider: string; modelId: string }) =>
+		m.provider === config.provider && m.modelId === config.modelId;
+	const isCurrentDefault = isSame(currentDefault);
+	const isLegacyDefault = LEGACY_DEFAULT_MODELS.some(isSame);
+	if (!isCurrentDefault && !isLegacyDefault) return config;
+
+	// Candidate chain in preference order: current default first, then fallbacks.
+	const chain = [currentDefault, ...DEFAULT_MODEL_FALLBACKS];
+	// "Usable" = in the registry (and keyed, when key information is available).
+	const usable = (m: { provider: string; modelId: string }) =>
+		hasKey ? hasModel(m.provider, m.modelId) && hasKey(m.provider, m.modelId) : hasModel(m.provider, m.modelId);
+
+	if (isLegacyDefault) {
+		// Old rule first: upgrade an implicit legacy default to the current
+		// default when that one is usable.
+		if (usable(currentDefault)) {
+			return { ...config, provider: currentDefault.provider, modelId: currentDefault.modelId };
 		}
+		if (hasKey) {
+			// A keyed legacy default keeps working — never trade it for an unkeyed model.
+			if (usable(config)) return config;
+			// Otherwise the first keyed candidate anywhere in the chain wins.
+			for (const cand of chain) {
+				if (usable(cand)) return { ...config, provider: cand.provider, modelId: cand.modelId };
+			}
+		}
+		// No key information (older callers): exact pre-1.18 behavior — only the
+		// current-default upgrade above applies.
 		return config;
 	}
 
-	if (hasModel(config.provider, config.modelId)) return config;
-	for (const fb of DEFAULT_MODEL_FALLBACKS) {
-		if (hasModel(fb.provider, fb.modelId)) {
-			return { ...config, provider: fb.provider, modelId: fb.modelId };
+	// Config holds the current default pair.
+	if (usable(currentDefault)) return config;
+
+	if (hasKey) {
+		// First keyed candidate in the chain wins (current default is not usable).
+		for (const cand of chain) {
+			if (isSame(cand)) continue;
+			if (usable(cand)) return { ...config, provider: cand.provider, modelId: cand.modelId };
+		}
+		// Nothing keyed anywhere: fall through to catalog-only resolution so the
+		// user still gets the actionable "No API key" notice on first use.
+	}
+
+	if (hasModel(currentDefault.provider, currentDefault.modelId)) return config;
+	for (const cand of chain) {
+		if (hasModel(cand.provider, cand.modelId)) {
+			return { ...config, provider: cand.provider, modelId: cand.modelId };
 		}
 	}
 	return config;
@@ -1554,6 +1600,64 @@ function mimeTypeForExt(filePath: string): string | undefined {
 	return EXT_TO_MIME[extname(filePath).toLowerCase()];
 }
 
+// ── Content-sniffed image validation (Pi ≥ 0.84.4) ───────────────────────────────
+
+/**
+ * Image MIME types Pi's exported content sniffer can validate
+ * (`detectSupportedImageMimeTypeFromFile`, public since Pi 0.84.4). Files
+ * whose extension maps to one of these are rejected when the sniffer says
+ * the bytes are not that kind of image; formats outside this set (tiff, ico,
+ * avif) keep the extension-only behavior.
+ */
+export const SNIFFABLE_IMAGE_MIMES: ReadonlySet<string> = new Set([
+	"image/jpeg",
+	"image/png",
+	"image/gif",
+	"image/webp",
+	"image/bmp",
+]);
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+function hasPngSignature(buffer: Uint8Array): boolean {
+	if (buffer.length < PNG_SIGNATURE.length) return false;
+	return PNG_SIGNATURE.every((byte, i) => buffer[i] === byte);
+}
+
+/** Outcome of combining the extension map with a content sniff. */
+export interface ImageMimeDecision {
+	/** MIME type to use, when the file is accepted. */
+	mime?: string;
+	/** True when the extension claims an image but the contents are not one. */
+	reject?: boolean;
+}
+
+/**
+ * Decide an image file's MIME type from its extension and (optionally) a
+ * content sniff:
+ *
+ * - a sniffed type wins over the extension (corrects mis-typed files, e.g. a
+ *   JPEG named `.png`);
+ * - a sniff that finds no image rejects files whose extension is inside the
+ *   sniffer's coverage — with one carve-out: a file with a PNG signature that
+ *   the sniffer rejects as animated (APNG) is still accepted as `image/png`,
+ *   matching the pre-sniff behavior for providers that decode the first frame;
+ * - formats outside sniffer coverage, or a missing/unavailable sniffer
+ *   (`sniffed === undefined`), keep the extension-only behavior.
+ */
+export function decideImageMime(
+	extMime: string | undefined,
+	sniffed: string | null | undefined,
+	head: Uint8Array,
+): ImageMimeDecision {
+	if (typeof sniffed === "string") return { mime: sniffed };
+	if (sniffed === null) {
+		if (extMime === "image/png" && hasPngSignature(head)) return { mime: "image/png" };
+		if (extMime && SNIFFABLE_IMAGE_MIMES.has(extMime)) return { reject: true };
+	}
+	return { mime: extMime };
+}
+
 // ── File-path video detection ────────────────────────────────────────────────
 
 const VIDEO_EXT_TO_MIME: Record<string, string> = {
@@ -1789,11 +1893,20 @@ function maxImageFileBytes(): number {
 
 export type ReadImageReason =
 	| "not-an-image"
+	| "invalid-image"
 	| "denied"
 	| "unreadable"
 	| "empty"
 	| "too-large";
 
+/**
+ * Optional content sniffer: returns a sniffed MIME type, `null` when the
+ * contents are not a recognizable image, or `undefined` when sniffing is
+ * unavailable (Pi < 0.84.4, or the export failed to load). Backed by Pi's
+ * exported `detectSupportedImageMimeTypeFromFile` at runtime.
+ */
+export type SniffImageFile = (filePath: string) => Promise<string | null | undefined>;
+
 export interface ReadImageResult {
 	image: PiAiImage | null;
 	reason?: ReadImageReason;
@@ -1909,10 +2022,18 @@ export async function isPathAllowed(filePath: string, access?: PathAccessOptions
 
 /**
  * Read an image file and return as base64 ImageContent with a structured reason on failure.
- */
-export async function readImageFileWithReason(filePath: string, access?: PathAccessOptions): Promise<ReadImageResult> {
+ *
+ * The MIME type comes from the extension map, validated (and corrected) by a
+ * content sniff when a sniffer is available — see `decideImageMime`. With no
+ * sniffer the behavior is exactly the pre-1.18 extension-only path.
+ */
+export async function readImageFileWithReason(
+	filePath: string,
+	access?: PathAccessOptions,
+	sniffFile?: SniffImageFile,
+): Promise<ReadImageResult> {
 	const mimeType = mimeTypeForExt(filePath);
-	if (!mimeType) return { image: null, reason: "not-an-image" };
+	if (!mimeType && !sniffFile) return { image: null, reason: "not-an-image" };
 	if (!(await isPathAllowed(filePath, access))) return { image: null, reason: "denied" };
 	let content: Buffer;
 	try {
@@ -1928,8 +2049,22 @@ export async function readImageFileWithReason(filePath: string, access?: PathAcc
 	if (content.length === 0) return { image: null, reason: "empty", bytes: 0 };
 	const limit = maxImageFileBytes();
 	if (content.length > limit) return { image: null, reason: "too-large", bytes: content.length };
+
+	let sniffed: string | null | undefined;
+	if (sniffFile) {
+		try {
+			sniffed = await sniffFile(filePath);
+		} catch {
+			sniffed = undefined; // sniffer failure degrades to extension-only
+		}
+	}
+	const decision = decideImageMime(mimeType, sniffed, content);
+	if (decision.reject) {
+		return { image: null, reason: "invalid-image", bytes: content.length, filename: basename(filePath) };
+	}
+	if (!decision.mime) return { image: null, reason: "not-an-image", bytes: content.length };
 	return {
-		image: { type: "image", data: content.toString("base64"), mimeType },
+		image: { type: "image", data: content.toString("base64"), mimeType: decision.mime },
 		bytes: content.length,
 		filename: basename(filePath),
 	};

package/extensions/vision-proxy.ts

@@ -18,6 +18,8 @@
  *                                                    - persisted pre-consented providers
  *                                                    - use "*" or "all" to consent globally for all providers
  *                 /multimodal-proxy tool on|off     - enable/disable analyze_image tool
+ *                 /multimodal-proxy doctor          - one-shot setup diagnostics
+ *                 /multimodal-proxy test            - end-to-end self-test (synthetic image)
  *                 /multimodal-proxy max-images-per-call <n>
  *                 /multimodal-proxy max-batch <n>
  *                 /multimodal-proxy cache-size <n>
@@ -274,6 +276,7 @@ import {
 	canonicalYouTubeUrl,
 	youTubeVideoId,
 	applyDefaultModelFallback,
+	DEFAULT_MODEL_FALLBACKS,
 	applyRecallCompletion,
 	buildRecallItems,
 	collectRecallCandidates,
@@ -317,6 +320,7 @@ import {
 	persistedBase,
 	pluralImages,
 	type ReadImageReason,
+	type SniffImageFile,
 	readImageFileWithReason,
 	readPersistentFile,
 	resolveConfig,
@@ -447,6 +451,10 @@ interface SessionState {
 	 * post-compaction recall digest.
 	 */
 	compaction?: { reason?: "manual" | "threshold" | "overflow"; willRetry?: boolean };
+	/** Cached "provider/model has an API key" probes (cleared per session). */
+	keyProbe?: Map<string, boolean>;
+	/** Last implicit-default substitution already notified this session. */
+	notifiedDefaultSub?: string;
 }
 
 const _sessionState = new WeakMap<object, SessionState>();
@@ -649,19 +657,93 @@ function shouldStripImages(config: VisionConfig, model: ExtensionContext["model"
 }
 
 /**
- * Swap the untouched built-in default vision model for a fallback when the
- * running Pi's catalog doesn't know it (e.g. Claude Sonnet 5 on Pi < 0.80.3).
- * A model set via PI_VISION_PROXY_MODEL is an explicit user choice and is
- * never rewritten, even when it equals the built-in default.
+ * Swap the untouched built-in default vision model for a usable one when the
+ * running Pi's catalog doesn't know it (e.g. GLM 5.3 Flash on Pi < 0.84.x) or
+ * its provider has no API key (1.18.0: key-aware resolution). A model set via
+ * PI_VISION_PROXY_MODEL is an explicit user choice and is never rewritten,
+ * even when it equals the built-in default.
+ *
+ * Key probes are cached per session — they are cheap env/file lookups, but
+ * this runs on every prompt, tool result, and status refresh.
+ */
+async function withModelFallback(config: VisionConfig, ctx: ExtensionContext): Promise<VisionConfig> {
+	const hasModel = (p: string, m: string) => Boolean(ctx.modelRegistry.find(p, m));
+	if (envFlags().model) return applyDefaultModelFallback(config, hasModel, true);
+
+	const state = getSessionState(ctx);
+	state.keyProbe ??= new Map<string, boolean>();
+	const probe = async (p: string, m: string): Promise<boolean> => {
+		const key = `${p}/${m}`;
+		const cached = state.keyProbe!.get(key);
+		if (cached !== undefined) return cached;
+		let ok = false;
+		try {
+			const model = ctx.modelRegistry.find(p, m);
+			if (model) {
+				const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+				ok = auth.ok && Boolean(auth.apiKey);
+			}
+		} catch {
+			ok = false;
+		}
+		state.keyProbe!.set(key, ok);
+		return ok;
+	};
+
+	const pairs = [
+		{ provider: DEFAULT_CONFIG.provider, modelId: DEFAULT_CONFIG.modelId },
+		...DEFAULT_MODEL_FALLBACKS,
+		{ provider: config.provider, modelId: config.modelId },
+	];
+	const keys = new Map<string, boolean>();
+	for (const pair of pairs) {
+		keys.set(`${pair.provider}/${pair.modelId}`, await probe(pair.provider, pair.modelId));
+	}
+	const hasKey = (p: string, m: string) => keys.get(`${p}/${m}`) === true;
+	return applyDefaultModelFallback(config, hasModel, false, hasKey);
+}
+
+/**
+ * Notify (once per session) when implicit-default resolution substituted the
+ * configured model — e.g. no zai key → deepseek/deepseek-v4-flash-vision-exp.
  */
-function withModelFallback(config: VisionConfig, ctx: ExtensionContext): VisionConfig {
-	return applyDefaultModelFallback(
-		config,
-		(p, m) => Boolean(ctx.modelRegistry.find(p, m)),
-		envFlags().model,
+function notifyDefaultSubstitution(config: VisionConfig, resolved: VisionConfig, ctx: ExtensionContext): void {
+	const state = getSessionState(ctx);
+	const before = `${config.provider}/${config.modelId}`;
+	const after = `${resolved.provider}/${resolved.modelId}`;
+	if (before === after) return;
+	const key = `${before}→${after}`;
+	if (state.notifiedDefaultSub === key) return;
+	state.notifiedDefaultSub = key;
+	ctx.ui.notify(
+		`[multimodal-proxy] Vision default resolved to ${after} (${before} not usable here). ` +
+			`Pin a model with /multimodal-proxy model, or add a key: pi --login ${config.provider}`,
+		"info",
 	);
 }
 
+// ── Content sniffing (Pi ≥ 0.84.4) ───────────────────────────────────────
+
+/**
+ * Lazily resolve Pi's exported `detectSupportedImageMimeTypeFromFile`
+ * (public since 0.84.4). Returns undefined when unavailable — callers then
+ * degrade to the extension-only MIME path.
+ */
+let _sniffImageFile: SniffImageFile | null | undefined;
+async function sniffImageFile(filePath: string): Promise<string | null | undefined> {
+	if (_sniffImageFile === undefined) {
+		try {
+			const mod = (await import("@earendil-works/pi-coding-agent")) as Record<string, unknown>;
+			const fn = mod.detectSupportedImageMimeTypeFromFile;
+			_sniffImageFile = typeof fn === "function" ? (fn as SniffImageFile) : null;
+		} catch {
+			_sniffImageFile = null;
+		}
+	}
+	if (_sniffImageFile === null) return undefined;
+	return _sniffImageFile(filePath);
+}
+
 /**
  * Parse a max-upload value for the /multimodal-proxy max-upload subcommand
  * and menu: "<dim>" px long-edge, "<n>mb" byte budget, or "off" (both limits
@@ -764,6 +846,8 @@ function describeReadReason(reason: ReadImageReason, bytes?: number): string {
 			return `${bytes ?? "?"} bytes exceeds limit (override with PI_VISION_PROXY_MAX_IMAGE_BYTES)`;
 		case "not-an-image":
 			return "unsupported extension";
+		case "invalid-image":
+			return "file contents are not a recognized image (extension does not match contents — e.g. a non-image renamed to .png)";
 		default:
 			return reason;
 	}
@@ -1567,7 +1651,7 @@ async function handleAnalyzeImage(
 		if (ref.includes("..")) {
 			return `Error: path contains disallowed ".." segments.`;
 		}
-		const r = await readImageFileWithReason(ref, pathAccessFromConfig(config));
+		const r = await readImageFileWithReason(ref, pathAccessFromConfig(config), sniffImageFile);
 		if (!r.image) {
 			return `Error: could not read image: ${describeReadReason(r.reason ?? "not-an-image", r.bytes)}`;
 		}
@@ -1862,7 +1946,7 @@ export default function (pi: ExtensionAPI) {
 				parameters: AnalyzeImageParams,
 				execute: async (_toolCallId, params, _signal, _onUpdate, extCtx) => {
 					const entries = extCtx.sessionManager.getEntries();
-					const config = withModelFallback(resolveConfig(entries, process.env, _fileConfig), extCtx);
+					const config = await withModelFallback(resolveConfig(entries, process.env, _fileConfig), extCtx);
 
 					// Runtime check - tool may have been disabled mid-session
 					if (config.tool !== "on" || config.mode === "off") {
@@ -1901,12 +1985,13 @@ export default function (pi: ExtensionAPI) {
 		state.imageMeta.clear();
 		clearImageData(state.imageData);
 		state.compaction = undefined;
+		state.keyProbe = undefined;
+		state.notifiedDefaultSub = undefined;
 
 		_fileConfig = await readPersistentFile();
-		const config = withModelFallback(
-			resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig),
-			ctx,
-		);
+		const rawConfig = resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig);
+		const config = await withModelFallback(rawConfig, ctx);
+		notifyDefaultSubstitution(rawConfig, config, ctx);
 		ctx.ui.setStatus("multimodal-proxy", steadyStatusText(config, ctx.modelRegistry));
 
 		// Register tool if enabled
@@ -1931,7 +2016,9 @@ export default function (pi: ExtensionAPI) {
 			// Resolve config up front — file loading below honors the configurable
 			// folder allowlist (allowedFolders / allowHome).
 			const entries = ctx.sessionManager.getEntries();
-			const config = withModelFallback(resolveConfig(entries, process.env, _fileConfig), ctx);
+			const rawConfig = resolveConfig(entries, process.env, _fileConfig);
+			const config = await withModelFallback(rawConfig, ctx);
+			notifyDefaultSubstitution(rawConfig, config, ctx);
 			const pathAccess = pathAccessFromConfig(config);
 
 			// Collect images: structured attachments + file paths detected in prompt
@@ -1944,7 +2031,7 @@ export default function (pi: ExtensionAPI) {
 			const acceptedPaths: string[] = [];
 			for (const fp of filePaths) {
 				if (fp.includes("..")) continue; // defense-in-depth: reject traversal
-				const r = await readImageFileWithReason(fp, pathAccess);
+				const r = await readImageFileWithReason(fp, pathAccess, sniffImageFile);
 				if (r.image) {
 					images.push(r.image);
 					acceptedPaths.push(fp);
@@ -2378,7 +2465,7 @@ export default function (pi: ExtensionAPI) {
 		if (images.length === 0) return; // fast path: most tool results carry no image
 
 		const entries = ctx.sessionManager.getEntries();
-		const config = withModelFallback(resolveConfig(entries, process.env, _fileConfig), ctx);
+		const config = await withModelFallback(resolveConfig(entries, process.env, _fileConfig), ctx);
 		// Model supports images, or proxy is off → pass the block through unchanged.
 		if (!shouldStripImages(config, ctx.model)) return;
 
@@ -2567,6 +2654,138 @@ export default function (pi: ExtensionAPI) {
 
 	// ── /multimodal-proxy command ─────────────────────────────────────────
 
+	/**
+	 * /multimodal-proxy doctor — one-shot setup diagnostics: effective model
+	 * resolution, catalog presence, API keys, consent, fallback and video model,
+	 * yt-dlp/ffmpeg availability, path access, and recall-store usage.
+	 */
+	const runDoctor = async (ctx: ExtensionContext, entries: readonly SessionEntry[], effective: VisionConfig) => {
+		const lines: string[] = [];
+		const resolved = await withModelFallback(effective, ctx);
+		const explicit = Boolean(envFlags().model) || effective.modelExplicit === true;
+		const substituted =
+			!explicit && (resolved.provider !== effective.provider || resolved.modelId !== effective.modelId);
+		const model = ctx.modelRegistry.find(resolved.provider, resolved.modelId);
+		let keyOk = false;
+		try {
+			if (model) {
+				const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+				keyOk = auth.ok && Boolean(auth.apiKey);
+			}
+		} catch {
+			keyOk = false;
+		}
+		lines.push(`mode: ${modeLabel(resolved.mode)}`);
+		lines.push(
+			`vision model: ${resolved.provider}/${resolved.modelId}` +
+				(explicit ? " (explicit)" : substituted ? " (implicit default, substituted)" : " (implicit default)") +
+				(model ? "" : " — NOT in catalog (update pi, or /multimodal-proxy model)") +
+				(model && !keyOk ? ` — no API key (run: pi --login ${resolved.provider})` : ""),
+		);
+		lines.push(
+			`consent (${resolved.provider}): ` +
+				(hasConsent(entries, resolved.provider, resolved.allowedProviders, resolved.deniedProviders)
+					? "granted"
+					: "not granted (/multimodal-proxy consent yes)"),
+		);
+		if (resolved.fallbackProvider && resolved.fallbackModelId) {
+			const fb = ctx.modelRegistry.find(resolved.fallbackProvider, resolved.fallbackModelId);
+			lines.push(
+				`fallback model: ${resolved.fallbackProvider}/${resolved.fallbackModelId}` +
+					(fb ? "" : " — NOT in catalog"),
+			);
+		}
+		const videoModel = ctx.modelRegistry.find(resolved.videoProvider, resolved.videoModelId);
+		let videoKeyOk = false;
+		try {
+			if (videoModel) {
+				const auth = await ctx.modelRegistry.getApiKeyAndHeaders(videoModel);
+				videoKeyOk = auth.ok && Boolean(auth.apiKey);
+			}
+		} catch {
+			videoKeyOk = false;
+		}
+		lines.push(
+			`video model: ${resolved.videoProvider}/${resolved.videoModelId}` +
+				(videoModel ? "" : " — NOT in catalog") +
+				(videoModel && !videoKeyOk ? ` — no API key (run: pi --login ${resolved.videoProvider})` : ""),
+		);
+		const toolVersion = async (bin: string): Promise<string> => {
+			try {
+				const { stdout } = await execFileAsync(bin, ["--version"], { windowsHide: true, timeout: 10_000 });
+				return (stdout.trim().split(/\r?\n/)[0] ?? "").slice(0, 48);
+			} catch {
+				return "";
+			}
+		};
+		const ytdlpVersion = await toolVersion("yt-dlp");
+		lines.push(`yt-dlp: ${ytdlpVersion || "not found (needed for YouTube URLs)"}`);
+		const ffmpegVersion = await toolVersion("ffmpeg");
+		lines.push(`ffmpeg: ${ffmpegVersion || "not found (needed for video duration probing / stream merging)"}`);
+		lines.push(
+			`path detection: ${resolved.pathDetection === "on" ? "ON" : "OFF"}` +
+				` | allow home: ${resolved.allowHome ? "ON" : "OFF"}` +
+				` | extra folders: ${resolved.allowedFolders.length}`,
+		);
+		const store = getSessionState(ctx).imageData;
+		lines.push(
+			`recall store: ${store.map.size} image(s), ${(store.totalBytes / 1048576).toFixed(1)} MB retained (in-memory only)`,
+		);
+		ctx.ui.notify(`[multimodal-proxy] doctor\n  ${lines.join("\n  ")}`, "info");
+	};
+
+	/**
+	 * /multimodal-proxy test — end-to-end self-test: synthesizes a tiny image
+	 * locally and describes it through the full pipeline (model resolution, key,
+	 * consent, retry/backoff, upload path). No file or network fixture needed.
+	 */
+	const runSelfTest = async (ctx: ExtensionContext, entries: readonly SessionEntry[], effective: VisionConfig) => {
+		if (effective.mode === "off") {
+			ctx.ui.notify("[multimodal-proxy] Proxy is off — enable with /multimodal-proxy fallback or always.", "warning");
+			return;
+		}
+		const resolved = await withModelFallback(effective, ctx);
+		// Tiny locally generated gradient PNG — no fixture file, no network.
+		const { Image } = await import("imagescript");
+		const img = new Image(96, 96);
+		img.fill(
+			(x, y) => ((0xff << 24) | ((x * 2) << 16) | ((y * 2) << 8) | ((x + y) % 256)) >>> 0,
+		);
+		const encoded = await img.encode();
+		const image: PiAiImage = {
+			type: "image",
+			data: Buffer.from(encoded).toString("base64"),
+			mimeType: "image/png",
+		};
+		if (!(await ensureConsent(resolved, ctx, entries, pi))) {
+			ctx.ui.notify("[multimodal-proxy] Self-test aborted — data-egress consent declined.", "warning");
+			return;
+		}
+		const started = Date.now();
+		const results = await analyzeImages(
+			[image],
+			"This is a connectivity self-test with a locally generated gradient image. Describe it in one short sentence.",
+			"",
+			resolved,
+			ctx,
+		);
+		const elapsed = ((Date.now() - started) / 1000).toFixed(1);
+		const first = results?.[0];
+		if (first?.description) {
+			const snippet = first.description.length > 200 ? `${first.description.slice(0, 200)}…` : first.description;
+			ctx.ui.notify(
+				`[multimodal-proxy] Self-test OK via ${resolved.provider}/${resolved.modelId} in ${elapsed}s:\n"${snippet}"`,
+				"info",
+			);
+		} else {
+			ctx.ui.notify(
+				`[multimodal-proxy] Self-test FAILED in ${elapsed}s — run /multimodal-proxy doctor (model, API key, consent)` +
+					(first?.error ? ` Error: ${first.error}` : ""),
+				"error",
+			);
+		}
+	};
+
 	// Register both names — /multimodal-proxy (canonical) and /multimodal-proxy (legacy alias)
 	const commandHandler = async (args: string, ctx: ExtensionContext) => {
 			const entries = ctx.sessionManager.getEntries();
@@ -2593,9 +2812,10 @@ export default function (pi: ExtensionAPI) {
 				writePersistentFile(fileNext);
 				_fileConfig = fileNext;
 				const eff = resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig);
-				ctx.ui.setStatus(
-					"multimodal-proxy",
-					steadyStatusText(withModelFallback(eff, ctx), ctx.modelRegistry),
+				// Fire-and-forget: writePersisted stays synchronous for its ~30 call
+				// sites; the status refresh just needs the resolved model eventually.
+				void withModelFallback(eff, ctx).then((resolved) =>
+					ctx.ui.setStatus("multimodal-proxy", steadyStatusText(resolved, ctx.modelRegistry)),
 				);
 				return validated;
 			};
@@ -2653,7 +2873,7 @@ export default function (pi: ExtensionAPI) {
 				const parsed = parseModelString(value);
 				if (!parsed) {
 					ctx.ui.notify(
-						"Usage: /multimodal-proxy model provider/model-id\nExample: /multimodal-proxy model anthropic/claude-sonnet-5",
+						"Usage: /multimodal-proxy model provider/model-id\nExample: /multimodal-proxy model zai/glm-5.3-flash",
 						"warning",
 					);
 					return;
@@ -3384,6 +3604,17 @@ Use "*" or "all" to grant consent for all providers globally.`,
 			}
 
 			// ── describe / redescribe ───────────────────────────
+			// ── Diagnostics ────────────────────────────────────────
+			if (sub === "doctor") {
+				await runDoctor(ctx, entries, effective);
+				return;
+			}
+
+			if (sub === "test") {
+				await runSelfTest(ctx, entries, effective);
+				return;
+			}
+
 			if (sub === "describe" || sub === "redescribe") {
 				if (effective.mode === "off") {
 					ctx.ui.notify("[multimodal-proxy] Proxy is off - enable with /multimodal-proxy fallback or /multimodal-proxy always.", "warning");
@@ -3396,7 +3627,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				}
 
 				// Resolve model override
-				let descConfig = withModelFallback(effective, ctx);
+				let descConfig = await withModelFallback(effective, ctx);
 				if (parsed.model) {
 					const parsedModel = parseModelString(parsed.model);
 					if (!parsedModel) {
@@ -3438,7 +3669,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 						ctx.ui.notify(`[multimodal-proxy] Error: path contains disallowed \"..\" segments.`, "error");
 						return;
 					}
-					const r = await readImageFileWithReason(ref, pathAccessFromConfig(effective));
+					const r = await readImageFileWithReason(ref, pathAccessFromConfig(effective), sniffImageFile);
 					if (!r.image) {
 						ctx.ui.notify(`[multimodal-proxy] Could not read image: ${ref} (${describeReadReason(r.reason ?? "not-an-image", r.bytes)})`, "error");
 						return;
@@ -3629,7 +3860,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 
 			// ── Interactive config ──────────────────────────────
 			// Display the model requests will actually use (registry fallback applied)
-			const friendlyEffective = friendlyModelLabel(withModelFallback(effective, ctx), ctx.modelRegistry);
+			const friendlyEffective = friendlyModelLabel(await withModelFallback(effective, ctx), ctx.modelRegistry);
 			const activeEnvOverrides = [
 				env.mode && "mode", env.model && "model", env.context && "context", env.tool && "tool",
 				env.maxImagesPerCall && "maxImagesPerCall", env.maxBatch && "maxBatch", env.cacheSize && "cacheSize",
@@ -3661,7 +3892,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 			if (!ctx.hasUI) {
 				ctx.ui.notify(
 					summary +
-						`\nCommands: /multimodal-proxy fallback|always|off | pick | model provider/model-id | video-model provider/model-id | context on|off | consent yes|no|always | allowed-providers add|remove <provider>|clear | tool on|off | max-images-per-call <n> | max-batch <n> | cache-size <n> | folders list|add|remove|reset | allow-home on|off | status on|off | path-detection on|off | fallback-model provider/model-id|clear | retry <0-5> | max-upload <dim|nmb|off>`,
+						`\nCommands: /multimodal-proxy fallback|always|off | pick | model provider/model-id | video-model provider/model-id | context on|off | consent yes|no|always | allowed-providers add|remove <provider>|clear | tool on|off | max-images-per-call <n> | max-batch <n> | cache-size <n> | folders list|add|remove|reset | allow-home on|off | status on|off | path-detection on|off | fallback-model provider/model-id|clear | retry <0-5> | max-upload <dim|nmb|off> | doctor | test`,
 					"info",
 				);
 				return;
@@ -3684,6 +3915,8 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				`Path detection: ${effective.pathDetection === "on" ? "ON" : "OFF"}`,
 				`Consent: ${hasConsent(entries, effective.provider, effective.allowedProviders, effective.deniedProviders) ? "granted" : "not granted"}`,
 				`Allowed providers: ${(effective.allowedProviders ?? []).length > 0 ? effective.allowedProviders!.join(", ") : "none"}`,
+				"Run diagnostics (doctor)",
+				"Run self-test (test image)",
 			]);
 
 			if (!choice) return;
@@ -3943,6 +4176,16 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				);
 				return;
 			}
+
+			if (choice === "Run diagnostics (doctor)") {
+				await runDoctor(ctx, entries, effective);
+				return;
+			}
+
+			if (choice === "Run self-test (test image)") {
+				await runSelfTest(ctx, entries, effective);
+				return;
+			}
 		};
 
 	// Register both command names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multimodal-proxy",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "Automatic image, video and audio description for any model in Pi. Routes media to a multimodal model and injects descriptions into context.",
   "keywords": [
     "pi-package"