@bismawy/pi-vision-watcher 1.0.10 → 1.0.12

package/README.md

@@ -1,140 +1,129 @@
-# 👁️ @bismawy/pi-vision-watcher
-
-**Give text-only [pi](https://github.com/earendil-works/pi-coding-agent) models vision capabilities.**
-
-Seamlessly inspect, describe, and convert visual inputs (screenshots, mockups, terminal errors, clipboard pastes) into structured descriptions using your preferred vision model, and hand them off to text-only coding models without interrupting your workflow.
-
-[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
-[![npm](https://img.shields.io/npm/v/@bismawy/pi-vision-watcher)](https://www.npmjs.com/package/@bismawy/pi-vision-watcher)
-[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-
-![pi-vision-watcher](https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/screenshot.webp)
-
----
-
-## ⚡ Quick Start
-
-### 1. Installation
-```bash
-pi install npm:@bismawy/pi-vision-watcher
-```
-*(Or install directly from Git: `pi install git:github.com/bismawy/pi-vision-watcher`)*
-
-### 2. Select Vision Model
-Open the interactive TUI selector to choose your vision describer model from your connected providers:
-```bash
-/vision-watcher
-```
-*(You can also set it directly: `/vision-watcher model openai/gpt-4o`)*
-
-### 3. Work Seamlessly
-Switch to any text-only model in Pi (e.g. DeepSeek, Claude text-only, local models). Whenever you paste an image, attach a file, or the agent runs `read` on an image, `pi-vision-watcher` describes it automatically in the background.
-
----
-
-## 🚀 Key Capabilities
-
-- 🎯 **Connected-Only Interactive Picker:** Shows only vision-capable models from providers where you actually have active credentials (`/login`, `models.json`, or environment variables).
-- ⚡ **DataLoader Batching & SHA-256 Cache:** Automatically groups multiple images across parallel tool calls or multi-file prompts into a single batched describer request. Cached images are never re-described.
-- 🛡️ **Proactive False-Vision Healing:** Aggregator providers often mistakenly flag models (like DeepSeek V4) as multimodal, causing HTTP 400 errors (`This model does not support image`). `pi-vision-watcher` proactively forces handoff for these models and auto-heals `models.json` `modelOverrides` in-process.
-- 🧠 **Thinking & Reasoning Controls:** Adjust reasoning levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) for reasoning-capable vision models (o-series, Claude, DeepSeek).
-- 🔄 **Multi-Model Fallback Chains:** Automatically falls back to backup vision models if your primary provider is rate-limited or unavailable.
-
----
-
-## 🕹️ Command Reference
-
-| Command | Action |
-|---|---|
-| `/vision-watcher` | Open interactive TUI picker for connected vision models |
-| `/vision-watcher model <provider/id>` | Set primary vision describer directly |
-| `/vision-watcher status` | View current configuration and active model status |
-| `/vision-watcher auto <on\|off>` | Toggle automatic handoff for non-vision models (default: `on`) |
-| `/vision-watcher add <provider/id>` | Force handoff on a specific model |
-| `/vision-watcher remove <provider/id>` | Remove model from forced handoff list |
-| `/vision-watcher thinking <level>` | Configure reasoning effort for vision models |
-| `/vision-watcher enable` / `disable` | Toggle extension active state |
-| `/vision-watcher help` | Show in-CLI command documentation |
-
----
-
-## 📖 Deep Dive & Advanced Configuration
-
-<details>
-<summary><b>⚙️ Configuration File Schema (<code>pi-vision-watcher.json</code>)</b></summary>
-
-Configuration is stored at `~/.pi/agent/extensions/pi-vision-watcher.json`:
-
-```json
-{
-  "enabled": true,
-  "visionModel": "openai/gpt-4o",
-  "fallbackModels": [],
-  "autoHandoff": true,
-  "handoffModels": [],
-  "thinking": false,
-  "thinkingLevel": "medium",
-  "describeTimeoutMs": 45000,
-  "prewarmPastedImages": false,
-  "asyncClipboardHandoff": false,
-  "maxTokens": null,
-  "cacheMax": 50,
-  "maxDescriptionLines": 0
-}
-```
-
-| Field | Type | Default | Description |
-|---|---|---|---|
-| `enabled` | `boolean` | `true` | Master switch for handoff processing. |
-| `visionModel` | `string \| null` | `null` | Primary describer model ref (`provider/id`). |
-| `fallbackModels` | `string[]` | `[]` | Ordered backup models if the primary model fails. |
-| `autoHandoff` | `boolean` | `true` | Automatically describe images for models lacking native vision. |
-| `handoffModels` | `string[]` | `[]` | Specific model IDs forced to receive descriptions. |
-| `thinking` | `boolean` | `false` | Enable reasoning tokens for vision model. |
-| `thinkingLevel` | `string` | `"medium"` | Reasoning effort (`minimal`, `low`, `medium`, `high`, `xhigh`, `max`). |
-| `describeTimeoutMs` | `number` | `45000` | Per-batch timeout before aborting or triggering fallbacks. |
-| `prewarmPastedImages` | `boolean` | `false` | Start describing clipboard images immediately upon pasting in prompt. |
-| `asyncClipboardHandoff` | `boolean` | `false` | Async clipboard injection fallback mechanism. |
-| `maxTokens` | `number \| null` | `null` | Max output tokens for descriptions (`null` = model default). |
-| `cacheMax` | `number` | `50` | Maximum cached image hashes per session. |
-| `maxDescriptionLines` | `number` | `0` | Truncate lines in description block (`0` = full description). |
-
-</details>
-
-<details>
-<summary><b>🔍 Troubleshooting, Recovery & Diagnostics</b></summary>
-
-### Structured Error Logging
-If a vision call fails, errors are appended with stack traces and request metadata to:
-```text
-~/.pi/agent/logs/pi-vision-watcher/errors.log
-```
-Failures degrade gracefully to `[Image: description unavailable]` without breaking the agent turn.
-
-### False-Vision Auto-Recovery
-When a model falsely advertises image capability and returns an HTTP 400 rejection:
-1. `pi-vision-watcher` captures the error in the `message_end` event.
-2. It automatically updates `~/.pi/agent/models.json` under `providers.<name>.modelOverrides.<model>.input = ["text"]`.
-3. It triggers an in-process registry refresh so subsequent turns use handoff naturally.
-
-</details>
-
-<details>
-<summary><b>🛠️ Development & Testing</b></summary>
-
-```bash
-bun install
-bun run test          # Run Vitest test suite (240+ unit tests)
-bun run typecheck     # Run TypeScript compiler check
-bun run lint:dead     # Scan for unused exports with Knip
-```
-
-</details>
-
----
-
-## 📜 License & Acknowledgments
-
-- Built for the **[pi coding agent](https://github.com/earendil-works/pi-coding-agent)** ecosystem.
-- Evolved from concepts in `pi-vision-handoff` by Tom X Nguyen and `pi-umans-provider`.
-- Distributed under the **[MIT License](./LICENSE)**.
+<div align="center">
+
+# pi-vision-watcher
+
+Give text-only [pi](https://github.com/earendil-works/pi-coding-agent) models vision — images are described by a vision model you pick, then handed off to text-only coding models without interrupting your workflow.
+
+[pi package](https://pi.dev/packages/@bismawy/pi-vision-watcher) · [npm](https://www.npmjs.com/package/@bismawy/pi-vision-watcher) · [Issues](https://github.com/bismawy/pi-vision-watcher/issues)
+
+![npm](https://img.shields.io/npm/v/@bismawy/pi-vision-watcher)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+<img src="assets/screenshot.webp" alt="pi-vision-watcher" width="100%">
+
+## What it does
+
+Paste an image, attach a file, or have the agent `read` one — pi-vision-watcher describes it in the background with your chosen vision model and feeds the description to whatever text-only model you're using (DeepSeek, local models, etc.).
+
+- **Connected-only picker:** `/vision-watcher` shows only vision-capable models from providers where you actually have credentials.
+- **Batching & cache:** multiple images across parallel tool calls are batched into one describer request; cached images (SHA-256) are never re-described.
+- **False-vision healing:** aggregator providers sometimes flag text-only models as multimodal, causing HTTP 400s. The extension proactively forces handoff for them and auto-heals `models.json` in-process.
+- **Thinking controls:** adjust reasoning effort (`off` – `max`) for reasoning-capable vision models.
+- **Fallback chains:** automatically falls back to backup vision models when the primary is rate-limited or down.
+
+## Install
+
+```bash
+pi install npm:@bismawy/pi-vision-watcher
+```
+
+Then run `/vision-watcher` to pick your vision model (or set it directly: `/vision-watcher model openai/gpt-4o`). Handoff is on by default — just switch to any text-only model and work as usual.
+
+## Commands
+
+| Command | Action |
+| :--- | :--- |
+| `/vision-watcher` | Interactive picker for connected vision models |
+| `/vision-watcher model <provider/id>` | Set primary vision describer directly |
+| `/vision-watcher status` | View current configuration |
+| `/vision-watcher auto <on\|off>` | Toggle automatic handoff (default: `on`) |
+| `/vision-watcher add <provider/id>` | Force handoff on a specific model |
+| `/vision-watcher remove <provider/id>` | Remove model from forced handoff list |
+| `/vision-watcher thinking <level>` | Configure reasoning effort |
+| `/vision-watcher timeout <ms>` | Set the base per-image description timeout (default `45000`) |
+| `/vision-watcher prewarm <on\|off>` | Describe pasted images at paste-time (opt-in) |
+| `/vision-watcher async <on\|off>` | Inject pasted-image descriptions asynchronously when no matching `read` wins (alias: `fallback`) |
+| `/vision-watcher clear` | Clear the configured vision model |
+| `/vision-watcher enable` / `disable` | Toggle extension active state |
+| `/vision-watcher help` | List all subcommands |
+
+`async` is the async *clipboard* fallback and has nothing to do with the
+`fallbackModels` failover chain.
+
+In the picker:
+
+| Key | Action |
+|---|---|
+| `space` | Select the highlighted model as the primary describer (press again to clear) |
+| `ctrl+q` | Toggle the highlighted model in/out of the failover chain (marked 🔁, max 3). Not a mnemonic, and that's on purpose: `ctrl+f` is pi's find-text (bound since pi 0.85), `alt+f` is editor word-right, and `ctrl+alt+f` never survives Windows conhost/Windows Terminal. pi 0.85 also binds `ctrl+q` to `app.message.followUp`, which is inert while a picker is open — if it ever double-fires, `f2` is the free fallback (unbound in 0.84 and 0.85) |
+| `ctrl+t` | Walk the thinking ladder: off → minimal → low → medium → high → xhigh → max → off → … |
+| `ctrl+a` | Toggle async paste handoff |
+| `enter` / `ctrl+s` | Save (primary **and** chain together) |
+| `esc` | Cancel |
+
+The detail pane always shows the current configuration — primary, chain,
+thinking, async handoff — so every keypress shows exactly what will be saved.
+`space` is left to the search box while a filter query is present, so multi-word
+searches like `gemini 3.8` stay typeable.
+
+## How it works
+
+<details>
+<summary><b>Configuration</b> (<code>~/.pi/agent/extensions/pi-vision-watcher.json</code>)</summary>
+
+```json
+{
+  "enabled": true,
+  "visionModel": "openai/gpt-4o",
+  "fallbackModels": [],
+  "autoHandoff": true,
+  "handoffModels": [],
+  "thinking": false,
+  "thinkingLevel": "medium",
+  "describeTimeoutMs": 45000,
+  "prewarmPastedImages": false,
+  "asyncClipboardHandoff": false,
+  "maxTokens": null,
+  "cacheMax": 50,
+  "maxDescriptionLines": 0
+}
+```
+
+Most fields have sane defaults — `visionModel` is the only one you normally set.
+
+`fallbackModels` is the failover chain: when the primary describer fails (timeout,
+rate limit, auth), each entry is tried **in order** — fallback 1 fails, fallback 2
+runs, and so on until one returns a description. The picker caps the chain at 3
+entries (`ctrl+q`). Set it from the picker instead of hand-editing the file.
+
+</details>
+
+<details>
+<summary><b>Diagnostics & recovery</b></summary>
+
+- Failed vision calls log with stack traces to `~/.pi/agent/logs/pi-vision-watcher/errors.log` and degrade gracefully to `[Image: description unavailable]`.
+- When a model falsely advertises image capability and 400s, the error is captured on `message_end`, `modelOverrides.<model>.input = ["text"]` is written to `models.json`, and the registry refreshes in-process.
+
+</details>
+
+<details>
+<summary><b>Development</b></summary>
+
+```bash
+bun install
+bun run test          # Vitest suite (240+ unit tests)
+bun run typecheck
+bun run lint:dead
+```
+
+</details>
+
+## License
+
+Distributed under the **MIT** license.
+
+## Developer
+
+Developed and maintained by [Bisma](https://github.com/bismawy).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bismawy/pi-vision-watcher",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Give text-only pi models vision — describe images with a vision model you pick via an interactive picker, then hand off the text description to non-vision models",
   "type": "module",
   "author": "bismawy",
@@ -44,9 +44,9 @@
     "lint:dead": "knip --no-gitignore"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.2",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "25.9.1",
     "@vitest/coverage-v8": "4.1.7",
     "knip": "6.14.1",

package/src/dataloader.ts

@@ -212,7 +212,13 @@ export class DescriptionLoader implements Disposable {
   loadDescription(img: ExtractedImage): Promise<string> {
     const hash = imageHash(img.mimeType, img.data);
     const cached = this.cache.get(hash);
-    if (cached) return cached;
+    if (cached) {
+      // Re-insert to refresh Map order: insertion order is FIFO, so without
+      // this a hot image ages like a cold one and gets evicted ahead of it.
+      this.cache.delete(hash);
+      this.cache.set(hash, cached);
+      return cached;
+    }
 
     if (!this.batch) {
       this.batch = { keys: [], imgs: [], callbacks: [] };

package/src/describer.ts

@@ -187,6 +187,11 @@ export interface DescriberDeps {
   /** Set the most-recent describer failure message (surfaced to the user by the engine).
    *  Pass `null` to clear before a fresh attempt. */
   setLastError(msg: string | null): void;
+  /** Record the model ref ACTUALLY attempted for the latest describer call.
+   *  Differs from `config.visionModel` when a failover fallback ran — the
+   *  warning must name the model that failed, not the configured primary.
+   *  Optional so older callers/tests compile unchanged. */
+  setAttemptedModel?(ref: string): void;
 }
 
 /** The result of a batched describer call: per-image raw descriptions keyed by hash. */
@@ -212,6 +217,7 @@ export async function runBatch(
   turnSignal?: AbortSignal,
 ): Promise<BatchResult> {
   const out: BatchResult = new Map();
+  deps.setAttemptedModel?.(formatModelRef(visionModel.provider, visionModel.id));
   const auth = await modelRegistry.getApiKeyAndHeaders(visionModel);
   if (!auth.ok || !auth.apiKey) {
     const reason = !auth.ok
@@ -222,6 +228,7 @@ export async function runBatch(
       phase: "batch",
       reason,
       visionModel: cfg.visionModel,
+      attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
       imageHashes: misses.map((m) => m.hash),
       imageCount: misses.length,
       config: configSnapshot(cfg),
@@ -277,6 +284,7 @@ export async function runBatch(
           phase: "batch",
           reason,
           visionModel: cfg.visionModel,
+          attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
           imageHashes: hashes,
           imageCount: misses.length,
           stopReason: response.stopReason,
@@ -299,6 +307,7 @@ export async function runBatch(
         phase: "batch",
         reason: "vision model returned an empty description",
         visionModel: cfg.visionModel,
+        attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
         imageHashes: hashes,
         imageCount: misses.length,
         config: configSnapshot(cfg),
@@ -356,6 +365,7 @@ export async function runBatch(
         phase: "batch",
         reason,
         visionModel: cfg.visionModel,
+        attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
         imageHashes: misses.map((m) => m.hash),
         imageCount: misses.length,
         timedOut,
@@ -386,6 +396,7 @@ export async function describeSingle(
   deps: DescriberDeps,
   turnSignal?: AbortSignal,
 ): Promise<string | null> {
+  deps.setAttemptedModel?.(formatModelRef(visionModel.provider, visionModel.id));
   const auth = await modelRegistry.getApiKeyAndHeaders(visionModel);
   if (!auth.ok || !auth.apiKey) {
     const reason = !auth.ok
@@ -396,6 +407,7 @@ export async function describeSingle(
       phase: "single",
       reason,
       visionModel: cfg.visionModel,
+      attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
       imageHashes: [imageHash(img.mimeType, img.data)],
       imageCount: 1,
       config: configSnapshot(cfg),
@@ -449,6 +461,7 @@ export async function describeSingle(
           phase: "single",
           reason,
           visionModel: cfg.visionModel,
+          attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
           imageHashes: [hash],
           imageCount: 1,
           stopReason: response.stopReason,
@@ -471,6 +484,7 @@ export async function describeSingle(
         phase: "single",
         reason: "vision model returned an empty description",
         visionModel: cfg.visionModel,
+        attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
         imageHashes: [hash],
         imageCount: 1,
         config: configSnapshot(cfg),
@@ -496,6 +510,7 @@ export async function describeSingle(
         phase: "single",
         reason,
         visionModel: cfg.visionModel,
+        attemptedModel: formatModelRef(visionModel.provider, visionModel.id),
         imageHashes: [imageHash(img.mimeType, img.data)],
         imageCount: 1,
         timedOut,

package/src/error-log.ts

@@ -53,6 +53,9 @@ export interface VisionErrorLogEntry {
   reason: string;
   /** Configured vision model ref ("provider/id"), or null if unset. */
   visionModel: string | null;
+  /** The model ACTUALLY called for this entry ("provider/id") — differs from
+   *  {@link visionModel} when a failover fallback was attempted. */
+  attemptedModel?: string;
   /** Image hashes the failure covered (batch/single) or the warning named. */
   imageHashes: string[];
   /** Number of images involved. */

package/src/index.ts

@@ -5,7 +5,7 @@
  * convention pi-model-sort uses for picker-backed extensions.
  */
 
-import type { ImageContent, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -86,15 +86,15 @@ export function isThinkingLevel(level: unknown): level is ThinkingLevel {
  *  per batch size. */
 export const DESCRIBE_TIMEOUT_MS = 45_000;
 
-/** Per-batch timeout: the base timeout plus a per-image budget so a 5-image
- *  batch isn't held to the same wall-clock budget as a single image. The
- *  describer generates exhaustive prose per image, and websocket transport
- *  adds latency, so the budget scales with the number of images in the call.
- *  `baseTimeout` defaults to {@link DESCRIBE_TIMEOUT_MS} and is overridden by
- *  the configured `describeTimeoutMs` field. */
+/** Per-batch timeout: `baseTimeout` is the per-image budget, so the wall-clock
+ *  budget scales with the number of images in the call (a 5-image batch isn't
+ *  held to a single image's budget — the describer generates exhaustive prose
+ *  per image and websocket transport adds latency). `baseTimeout` defaults to
+ *  {@link DESCRIBE_TIMEOUT_MS} and is overridden by the configured
+ *  `describeTimeoutMs` field, so lowering it fails over sooner for the *whole*
+ *  batch. */
 export function describeTimeoutMs(imageCount: number, baseTimeout: number = DESCRIBE_TIMEOUT_MS): number {
-  const perImage = 45_000;
-  return baseTimeout + Math.max(0, imageCount - 1) * perImage;
+  return baseTimeout * Math.max(1, imageCount);
 }
 
 /**
@@ -456,15 +456,6 @@ export function extractImageFromBlock(block: unknown): ExtractedImage | null {
   return null;
 }
 
-/** Build a text block that replaces an image block, matching the request format. */
-export function makeReplacementText(block: unknown, description: string): Record<string, unknown> {
-  const b = (block ?? null) as Record<string, unknown> | null;
-  if (b?.type === "input_image") {
-    return { type: "input_text", text: description };
-  }
-  return { type: "text", text: description };
-}
-
 /** Outcome of {@link truncateDescription}. */
 export interface TruncatedDescription {
   text: string;
@@ -590,73 +581,3 @@ export function wrapDescription(description: string, cfg: VisionHandoffConfig):
       : { text: description };
   return `${IMAGE_PLACEHOLDER_PREFIX}${final}${IMAGE_PLACEHOLDER_SUFFIX}`;
 }
-
-/** Outcome of {@link insertImageDescriptions}. */
-export interface ReplacedContent {
-  content: (TextContent | ImageContent)[];
-  /** True iff at least one image block had a description inserted before it. */
-  changed: boolean;
-}
-
-/**
- * Insert a description text block before each image block in a tool-result /
- * message content array, KEEPING the image block in place.
- *
- * Why insert (not replace): the stored tool-result content is the single
- * source for both the TUI render (kitty inline images read it via
- * `result.content.filter(c => c.type === "image")`) and the provider payload.
- * Replacing the image would strip it from the terminal render. Keeping the
- * image preserves kitty rendering; the inserted description still reaches
- * non-vision models because pi-ai's `downgradeUnsupportedImages` only rewrites
- * `type: "image"` blocks for non-vision models — text blocks (including this
- * description) pass through untouched to the provider.
- *
- * `describe` is injected (rather than calling the vision model directly) so the
- * extract → describe → insert pipeline is unit-testable without standing up a
- * provider, registry, and API call. The extension wires its real `describeImage`
- * into this helper in its `tool_result` handler.
- *
- * When at least one description is inserted, also strips pi core's
- * {@link NON_VISION_IMAGE_NOTE} from text blocks — the note (appended by the
- * read tool for non-vision models) would otherwise contradict the inserted
- * description. Text blocks are reassigned (not mutated in place); the input
- * array is left untouched.
- *
- * Returns a new array and `changed: false` when there were no images, so
- * callers can short-circuit and avoid mutating pi's stored result unnecessarily.
- */
-export async function insertImageDescriptions(
-  content: readonly (TextContent | ImageContent)[] | undefined,
-  describe: (img: ExtractedImage) => Promise<string>,
-): Promise<ReplacedContent> {
-  if (!Array.isArray(content)) {
-    return { content: [], changed: false };
-  }
-  const next: (TextContent | ImageContent)[] = [];
-  let changed = false;
-  for (const block of content) {
-    const img = extractImageFromBlock(block);
-    if (!img) {
-      next.push(block);
-      continue;
-    }
-    const description = await describe(img);
-    next.push({ type: "text", text: description } satisfies TextContent);
-    next.push(block);
-    changed = true;
-  }
-  if (!changed) {
-    return { content: next, changed };
-  }
-  // We inserted at least one description. Strip the read tool's
-  // "[Current model does not support images...]" note from text blocks — it
-  // contradicts the description we just inserted ("image will be omitted" vs.
-  // the description that follows) and confuses the model.
-  for (let i = 0; i < next.length; i++) {
-    const block = next[i];
-    if (block.type === "text" && typeof block.text === "string" && block.text.includes(NON_VISION_IMAGE_NOTE)) {
-      next[i] = { type: "text", text: stripNonVisionImageNote(block.text) } satisfies TextContent;
-    }
-  }
-  return { content: next, changed };
-}

package/src/vision-model-selector.ts

@@ -5,10 +5,11 @@
  * Uses the same patterns as pi's built-in selectors and pi-hide-providers:
  * - Lists connected (authenticated) models, vision-capable ones first (👀 badge)
  * - A leading "None" row clears the configured vision model
- * - Search/filter via Input component
- * - Enter or Ctrl+S confirms the highlighted model and saves
- * - Esc / Ctrl+C cancels
- * - The currently configured vision model is marked ✓
+ * - Space selects the highlighted model as the primary describer (toggle)
+ * - Ctrl+Alt+F toggles the highlighted model in/out of the failover chain (max 3)
+ * - Ctrl+T walks the thinking ladder, Ctrl+A toggles async paste handoff
+ * - Enter or Ctrl+S saves, Esc / Ctrl+C cancels
+ * - The primary is marked ✓, chain members 🔁
  */
 
 import {
@@ -29,6 +30,47 @@ import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import { DynamicBorder, keyText } from "@earendil-works/pi-coding-agent";
 import { formatModelRef, isVisionModel, THINKING_LEVELS } from "./index.js";
 
+/** Failover chain length cap — three is already far past the point where a
+ *  fourth describer would ever be reached. */
+export const MAX_FALLBACKS = 3;
+
+/** Key that toggles failover-chain membership, and the hint shown for it.
+ *
+ *  Deliberately a single control byte nobody else wants: `ctrl+alt+f` never
+ *  survives Windows conhost/Windows Terminal (AltGr handling drops or downgrades
+ *  it), `alt+f` is pi's editor word-right, and `ctrl+f` is pi's find-text. */
+const FALLBACK_KEY = Key.ctrl("q");
+const FALLBACK_KEY_HINT = "ctrl+q";
+
+/** Provider ids that don't title-case cleanly. Everything else falls back to
+ *  word-capitalisation (`custom-openrouter-ai` → "Custom Openrouter AI"). */
+const PROVIDER_LABELS: Record<string, string> = {
+  openai: "OpenAI",
+  "openai-codex": "OpenAI Codex",
+  anthropic: "Anthropic",
+  xai: "xAI",
+  github: "GitHub",
+  huggingface: "Hugging Face",
+  vertex: "Vertex AI",
+};
+
+const ACRONYMS = new Set(["ai", "api", "gpt", "llm", "mcp", "cli", "glm"]);
+
+/** Human-readable provider name for the detail pane. */
+export function providerLabel(provider: string): string {
+  const known = PROVIDER_LABELS[provider];
+  if (known) return known;
+  return provider
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((word) =>
+      ACRONYMS.has(word.toLowerCase())
+        ? word.toUpperCase()
+        : word.charAt(0).toUpperCase() + word.slice(1),
+    )
+    .join(" ");
+}
+
 interface DisplayItem {
   /** "provider/id", or null for the synthetic "None" row. */
   ref: string | null;
@@ -52,6 +94,9 @@ export interface VisionModelSelectorResult {
   thinkingLevel: ThinkingLevel;
   /** Whether pasted paths should be injected if no matching read wins. */
   asyncClipboardHandoff: boolean;
+  /** The failover chain, in list order. Enter/ctrl+s saves it together with
+   *  the primary selection — the picker edits both in one screen. */
+  fallbackModels: string[];
 }
 
 export class VisionModelSelectorComponent implements Component {
@@ -70,6 +115,10 @@ export class VisionModelSelectorComponent implements Component {
   private thinking: boolean;
   private thinkingLevel: ThinkingLevel;
   private asyncClipboardHandoff: boolean;
+  /** Fallback-chain membership, toggled in-place with {@link FALLBACK_KEY}. */
+  private fallbacks: Set<string>;
+  /** Transient hint (e.g. chain cap hit), rendered in the detail pane. */
+  private notice: string | null = null;
 
   private _focused = false;
   get focused(): boolean {
@@ -94,6 +143,7 @@ export class VisionModelSelectorComponent implements Component {
     currentThinkingLevel: ThinkingLevel,
     currentAsyncClipboardHandoff: boolean,
     done: (result: VisionModelSelectorResult) => void,
+    currentFallbacks: string[] = [],
   ) {
     this.theme = theme;
     this.done = done;
@@ -101,6 +151,7 @@ export class VisionModelSelectorComponent implements Component {
     this.thinking = currentThinking;
     this.thinkingLevel = currentThinkingLevel;
     this.asyncClipboardHandoff = currentAsyncClipboardHandoff;
+    this.fallbacks = new Set(currentFallbacks);
     this.allItems = this.buildItems(allModels);
     this.filteredItems = this.allItems;
 
@@ -111,10 +162,7 @@ export class VisionModelSelectorComponent implements Component {
     this.listContainer = new Container();
     this.footerText = new Text(this.getFooterText(), 0, 0);
 
-    this.searchInput.onSubmit = () => {
-      const item = this.filteredItems[this.selectedIndex];
-      if (item) this.confirm(item);
-    };
+    this.searchInput.onSubmit = () => this.save();
 
     this.updateList();
   }
@@ -172,15 +220,8 @@ export class VisionModelSelectorComponent implements Component {
       return;
     }
 
-    if (kb.matches(data, "tui.select.confirm")) {
-      const item = this.filteredItems[this.selectedIndex];
-      if (item) this.confirm(item);
-      return;
-    }
-
-    if (matchesKey(data, Key.ctrl("s"))) {
-      const item = this.filteredItems[this.selectedIndex];
-      if (item) this.confirm(item);
+    if (kb.matches(data, "tui.select.confirm") || matchesKey(data, Key.ctrl("s"))) {
+      this.save();
       return;
     }
 
@@ -199,24 +240,38 @@ export class VisionModelSelectorComponent implements Component {
       return;
     }
 
-    if (matchesKey(data, Key.ctrl("a"))) {
-      this.asyncClipboardHandoff = !this.asyncClipboardHandoff;
-      this.updateList();
+    // Space selects the highlighted model as the primary describer; pressing it
+    // again on the same model clears it back to "None". While a filter query is
+    // present, space is left to the search input so multi-word queries like
+    // "gemini 3.8" stay typeable.
+    if ((data === " " || matchesKey(data, Key.space)) && !this.searchInput.getValue()) {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.selectPrimary(item.ref);
       return;
     }
 
-    // Thinking controls — reuse pi's own app.thinking.* keybindings so the
-    // hints and behaviour match the rest of pi: ctrl+t toggles thinking
-    // on/off, shift+tab cycles the effort level. Intercepted before the
-    // search input so they never get swallowed as filter text.
-    if (kb.matches(data, "app.thinking.toggle")) {
-      this.thinking = !this.thinking;
+    // Toggles the highlighted model in/out of the failover chain — a per-row
+    // flag rather than a separate screen, so the primary and the chain are
+    // chosen together. Intercepted before the search input (like the other ctrl
+    // shortcuts) so the key never lands in the filter text. See
+    // {@link FALLBACK_KEY} for why it isn't ctrl+f.
+    if (matchesKey(data, FALLBACK_KEY)) {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item?.ref) this.toggleFallback(item.ref);
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl("a"))) {
+      this.asyncClipboardHandoff = !this.asyncClipboardHandoff;
       this.updateList();
       return;
     }
 
-    if (kb.matches(data, "app.thinking.cycle")) {
-      this.cycleThinkingLevel();
+    // ctrl+t walks the whole thinking ladder (off → minimal → … → max → off) so
+    // one key covers on/off *and* effort — no separate shift+tab binding.
+    // Intercepted before the search input so it never lands in the filter text.
+    if (kb.matches(data, "app.thinking.toggle") || matchesKey(data, Key.ctrl("t"))) {
+      this.cycleThinking();
       this.updateList();
       return;
     }
@@ -277,22 +332,58 @@ export class VisionModelSelectorComponent implements Component {
 
   private getFooterText(): string {
     const totalCount = this.allItems.length - 1; // exclude the None row
+    const matches = this.searchInput.getValue()
+      ? `${this.filteredItems.length - 1} matches`
+      : `total ${totalCount} vision-capable models`;
 
-    const current = this.currentRef
-      ? `current: ${this.currentRef}`
-      : "current: none";
-
+    // The current selection lives in the detail pane above, so the footer only
+    // carries keys + the model count.
     const parts: string[] = [
-      `${keyText("tui.select.confirm")} select`,
-      `ctrl+s done`,
-      `${keyText("app.thinking.toggle")} thinking`,
-      `${keyText("app.thinking.cycle")} effort`,
-      `ctrl+a async fallback`,
-      `esc cancel`,
-      this.searchInput.getValue() ? `${this.filteredItems.length - 1} match` : `${totalCount} vision-capable models`,
+      `${keyText("tui.select.confirm")} = done`,
+      "space = select vision models (👀)",
+      `${FALLBACK_KEY_HINT} = fallback models (🔁)`,
+      "ctrl+t = thinking",
+      "ctrl+a = async fallback",
+      "esc = cancel",
+      matches,
     ];
 
-    return this.theme.fg("dim", `  ${parts.join(" · ")} · ${current} `);
+    return this.theme.fg("dim", `  ${parts.join(" · ")} `);
+  }
+
+  /** Toggle a model's membership in the fallback chain, preserving list order
+   *  (the chain is tried in order, so the config array must be deterministic
+   *  rather than Set-iteration order). */
+  private toggleFallback(ref: string): void {
+    if (this.fallbacks.has(ref)) {
+      this.fallbacks.delete(ref);
+      this.notice = null;
+    } else if (this.fallbacks.size >= MAX_FALLBACKS) {
+      this.notice = `max ${MAX_FALLBACKS} fallbacks — remove one first (${FALLBACK_KEY_HINT})`;
+    } else {
+      this.fallbacks.add(ref);
+      this.notice = null;
+    }
+    this.updateList();
+  }
+
+  /** Space toggles the primary describer; picking the current one again clears
+   *  it (same as the None row), so one key both sets and unsets. */
+  private selectPrimary(ref: string | null): void {
+    this.currentRef = this.currentRef === ref ? null : ref;
+    this.notice = null;
+    this.updateList();
+  }
+
+  /** Fallback refs in list order (models the picker didn't show — e.g. one that
+   *  is no longer resolvable — are appended so a config value can't be
+   *  silently dropped just by opening the picker). */
+  private orderedFallbacks(): string[] {
+    const shown = this.allItems
+      .map((i) => i.ref)
+      .filter((r): r is string => !!r && this.fallbacks.has(r));
+    const unshown = [...this.fallbacks].filter((r) => !shown.includes(r));
+    return [...shown, ...unshown];
   }
 
   private refresh(): void {
@@ -318,8 +409,6 @@ export class VisionModelSelectorComponent implements Component {
       this.listContainer.addChild(
         new Text(this.theme.fg("muted", "  No matching models"), 0, 0),
       );
-      this.footerText.setText(this.getFooterText());
-      return;
     }
 
     const startIndex = Math.max(
@@ -355,8 +444,15 @@ export class VisionModelSelectorComponent implements Component {
         : item.none && this.currentRef === null
           ? this.theme.fg("success", " ✓")
           : "";
+      // Fallback marker — distinct from the primary's ✓ so a model can visibly
+      // be both the primary and a fallback (Sonnet as primary, Gemini as the
+      // chain behind it).
+      const fallbackMark =
+        item.ref && this.fallbacks.has(item.ref)
+          ? this.theme.fg("warning", " 🔁")
+          : "";
 
-      this.listContainer.addChild(new Text(`${prefix}${label}${current}`, 0, 0));
+      this.listContainer.addChild(new Text(`${prefix}${label}${current}${fallbackMark}`, 0, 0));
     }
 
     if (startIndex > 0 || endIndex < this.filteredItems.length) {
@@ -368,63 +464,96 @@ export class VisionModelSelectorComponent implements Component {
       );
     }
 
-    const selected = this.filteredItems[this.selectedIndex];
-    if (selected) {
-      this.listContainer.addChild(new Spacer(1));
-      if (selected.none) {
-        this.listContainer.addChild(
-          new Text(this.theme.fg("muted", `  ${selected.modelName}`), 0, 0),
-        );
-      } else {
-        this.listContainer.addChild(
-          new Text(this.theme.fg("muted", `  Model Name: ${selected.modelName}`), 0, 0),
-        );
-        this.listContainer.addChild(
-          new Text(this.theme.fg("dim", "  👀 vision-capable — recommended describer"), 0, 0),
-        );
-      }
-      this.renderThinkingDetail(selected);
-      const fallback = this.asyncClipboardHandoff
-        ? this.theme.fg("success", "on")
-        : this.theme.fg("muted", "off");
+    this.renderDetail();
+    this.footerText.setText(this.getFooterText());
+  }
+
+  private itemByRef(ref: string): DisplayItem | undefined {
+    return this.allItems.find((i) => i.ref === ref);
+  }
+
+  /** "Gemini 3.8 Flash (Antigravity)", or the raw ref when it isn't in the
+   *  registry right now (stale config) so it stays visible instead of blank. */
+  private refLabel(ref: string): string {
+    const item = this.itemByRef(ref);
+    if (!item) return ref;
+    const provider = providerLabel(item.provider);
+    // Model display names often already carry the vendor — "Gemini 3.8 Flash
+    // (Antigravity)" would otherwise come out as "… (Antigravity) (Antigravity)".
+    return item.modelName.toLowerCase().includes(provider.toLowerCase())
+      ? item.modelName
+      : `${item.modelName} (${provider})`;
+  }
+
+  /** The detail pane summarises the *configuration* (primary, failover chain
+   *  and toggles) rather than the highlighted row, so each space / ctrl+q
+   *  press shows exactly what will be saved. */
+  private renderDetail(): void {
+    const line = (label: string, value: string) =>
       this.listContainer.addChild(
-        new Text(this.theme.fg("dim", `  Async pasted-path fallback: ${fallback}`), 0, 0),
+        new Text(this.theme.fg("dim", `  ${label}`) + value, 0, 0),
       );
-    }
 
-    this.footerText.setText(this.getFooterText());
-  }
+    this.listContainer.addChild(new Spacer(1));
+    line(
+      "Vision-capable (👀): ",
+      this.currentRef
+        ? this.refLabel(this.currentRef)
+        : this.theme.fg("muted", "none — vision handoff disabled"),
+    );
+
+    const chain = this.orderedFallbacks();
+    line(
+      "Fallback (🔁): ",
+      chain.length
+        ? `${this.theme.fg("success", "on")} - ${chain.map((r) => this.refLabel(r)).join(", ")}`
+        : this.theme.fg("muted", "off"),
+    );
+
+    line(
+      "Thinking: ",
+      this.thinking
+        ? this.theme.fg("success", `on (${this.thinkingLevel})`)
+        : this.theme.fg("muted", "off"),
+    );
 
-  /** Append the thinking on/off + effort line to the detail pane, with a
-   *  warning when the highlighted model can't reason (so the setting would
-   *  be silently ignored by the describer). */
-  private renderThinkingDetail(selected: DisplayItem): void {
-    const state = this.thinking
-      ? this.theme.fg("success", `on (${this.thinkingLevel})`)
-      : this.theme.fg("muted", "off");
-    this.listContainer.addChild(
-      new Text(this.theme.fg("dim", `  Thinking: ${state}`), 0, 0),
+    line(
+      "Async pasted-path fallback: ",
+      this.asyncClipboardHandoff
+        ? this.theme.fg("success", "on")
+        : this.theme.fg("muted", "off"),
     );
-    if (this.thinking && !selected.none && !selected.reasoning) {
+
+    // The warning follows the *highlighted* row: it answers "what happens if I
+    // pick this model", which is also how you'd notice it while browsing.
+    const highlighted = this.filteredItems[this.selectedIndex];
+    if (this.thinking && highlighted && !highlighted.none && !highlighted.reasoning) {
       this.listContainer.addChild(
         new Text(
           this.theme.fg(
             "warning",
-            `  ⚠ ${selected.modelId} declares no reasoning — thinking will be ignored`,
+            `  ⚠ ${highlighted.modelId} declares no reasoning — thinking will be ignored`,
           ),
           0, 0,
         ),
       );
     }
+
+    if (this.notice) {
+      this.listContainer.addChild(
+        new Text(this.theme.fg("warning", `  ${this.notice}`), 0, 0),
+      );
+    }
   }
 
-  private confirm(item: DisplayItem): void {
+  private save(): void {
     this.done({
-      ref: item.ref,
+      ref: this.currentRef,
       cancelled: false,
       thinking: this.thinking,
       thinkingLevel: this.thinkingLevel,
       asyncClipboardHandoff: this.asyncClipboardHandoff,
+      fallbackModels: this.orderedFallbacks(),
     });
   }
 
@@ -435,18 +564,23 @@ export class VisionModelSelectorComponent implements Component {
       thinking: this.thinking,
       thinkingLevel: this.thinkingLevel,
       asyncClipboardHandoff: this.asyncClipboardHandoff,
+      fallbackModels: this.orderedFallbacks(),
     });
   }
 
-  /** Cycle the thinking effort forward through {@link THINKING_LEVELS},
-   *  wrapping from the last back to the first. Cycling implicitly turns
-   *  thinking on (you don't usually cycle a switch you want off) — matching
-   *  pi's own `app.thinking.cycle` behaviour, which is a no-op only when the
-   *  active model has no reasoning. */
-  private cycleThinkingLevel(): void {
-    if (!this.thinking) this.thinking = true;
-    const idx = THINKING_LEVELS.indexOf(this.thinkingLevel);
-    const next = THINKING_LEVELS[(idx + 1) % THINKING_LEVELS.length]!;
-    this.thinkingLevel = next;
+  /** Walk the thinking ladder with one key: off → minimal → low → medium →
+   *  high → xhigh → max → off → minimal → …
+   *
+   *  A single index over off + {@link THINKING_LEVELS} so the cycle always
+   *  advances. Keeping a separate "remembered level" while off turns the tail
+   *  into a two-position toggle once you reach max (off → max → off → max). */
+  private cycleThinking(): void {
+    const ladder = THINKING_LEVELS.length + 1; // position 0 = off
+    const current = this.thinking
+      ? THINKING_LEVELS.indexOf(this.thinkingLevel) + 1
+      : 0;
+    const next = (Math.max(current, 0) + 1) % ladder;
+    this.thinking = next > 0;
+    if (next > 0) this.thinkingLevel = THINKING_LEVELS[next - 1]!;
   }
 }

package/vision-watcher.ts

@@ -76,6 +76,11 @@ let config: VisionHandoffConfig = readConfig();
  *  Cleared at the start of each describer attempt. */
 let lastDescriberError: string | null = null;
 
+/** Model ref actually attempted for the most recent describer call. Set by the
+ *  describer (via {@link LoaderDeps}) so a failover failure is attributed to
+ *  the fallback that ran, not to `config.visionModel`. */
+let lastDescriberModel: string | null = null;
+
 /** Image hashes we've already warned the user about this session. Prevents the
  *  `context` hook (which fires before every LLM turn) from re-warning on the
  *  same failing images every turn — describer failures aren't cached, so
@@ -230,6 +235,9 @@ const loaderDeps: LoaderDeps = {
   setLastError: (msg) => {
     lastDescriberError = msg;
   },
+  setAttemptedModel: (ref) => {
+    lastDescriberModel = ref;
+  },
 };
 const loader = new DescriptionLoader(loaderDeps);
 
@@ -390,13 +398,21 @@ function warnFailedImages(
     phase: "warn",
     reason,
     visionModel: config.visionModel,
+    attemptedModel: lastDescriberModel ?? undefined,
     imageHashes: newlyFailed,
     imageCount: newlyFailed.length,
     activeModel: ctx.model ? formatModelRef(ctx.model.provider, ctx.model.id) : undefined,
   });
   if (!ctx.hasUI) return;
+  // Name the model that actually failed. After a failover the error belongs to
+  // a fallback, so reporting the configured primary sends users chasing the
+  // wrong provider (e.g. a 429 from the fallback attributed to the primary).
+  const attempted =
+    lastDescriberModel && lastDescriberModel !== config.visionModel
+      ? `${config.visionModel} → fallback ${lastDescriberModel}`
+      : config.visionModel;
   ctx.ui.notify(
-    `pi-vision-watcher: image description failed — ${reason}. Vision model: ${config.visionModel}`,
+    `pi-vision-watcher: image description failed — ${reason}. Vision model: ${attempted}`,
     "warning",
   );
 }
@@ -779,9 +795,11 @@ export default function (pi: ExtensionAPI) {
   // in-process (modelOverrides is Pi's topmost config layer, so it wins even
   // over a regenerated models[] entry). The model then registers as text-only,
   // autoHandoff covers it naturally, and /model shows it correctly. FALLBACK
-  // (write failed): force handoff via handoffModels. Either way, the failed
-  // turn's images are still in history; the context hook describes them on the
-  // retry instead of failing again.
+  // (write failed): force handoff via handoffModels. On success we ALSO add the
+  // model to handoffModels — belt and braces, so the retry is described even if
+  // the metadata write is later reverted by a models.json regeneration. Either
+  // way, the failed turn's images are still in history; the context hook
+  // describes them on the retry instead of failing again.
   pi.on("message_end", (event, ctx) => {
     const msg = event.message as {
       role?: string;
@@ -843,7 +861,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("vision-watcher", {
     description: HANDOFF_COMMAND_DESCRIPTION,
     getArgumentCompletions(prefix: string) {
-      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "prewarm", "fallback", "timeout", "add", "remove", "clear", "help"];
+      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "prewarm", "async", "fallback", "timeout", "add", "remove", "clear", "help"];
       const matches = subcommands.filter((s) => s.startsWith(prefix));
       return matches.length > 0 ? matches.map((s) => ({ value: s, label: s })) : null;
     },
@@ -879,8 +897,9 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "                               Set the vision describer's thinking effort (off = disabled)",
         "  /vision-watcher prewarm <on|off>",
         "                               Toggle describing pasted images at paste-time (opt-in, off by default)",
-        "  /vision-watcher fallback <on|off>",
+        "  /vision-watcher async <on|off>",
         "                               Inject pasted-image descriptions asynchronously when no matching read wins",
+        "                               (alias: /vision-watcher fallback — NOT the model failover chain)",
         "  /vision-watcher timeout <ms>   Set the per-image description timeout (default 45000)",
         "  /vision-watcher add <p/id>     Force handoff for an extra model",
         "  /vision-watcher remove <p/id>  Stop forcing handoff for a model",
@@ -892,7 +911,7 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "  read images through a dataloader (one batched vision call); context swaps",
         "  image blocks in the payload for the cached text description.",
         "  prewarm on wraps the editor to describe pasted images at paste-time.",
-        "  fallback on asynchronously injects a collapsed description unless a matching read wins.",
+        "  async on asynchronously injects a collapsed description unless a matching read wins.",
       ].join("\n"),
       "info",
     );
@@ -939,7 +958,7 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
     return;
   }
 
-  if (subcommand === "fallback") {
+  if (subcommand === "async" || subcommand === "fallback") {
     handleFallbackSubcommand(ctx, rest);
     return;
   }
@@ -1099,19 +1118,19 @@ function handlePrewarmSubcommand(ctx: ExtensionCommandContext, rest: string): vo
   updateConfig(ctx, (c) => ({ ...c, prewarmPastedImages: on }), note);
 }
 
-/** Handle /vision-watcher fallback <on|off>. */
+/** Handle `/vision-watcher async <on|off>` (alias: `fallback`). */
 function handleFallbackSubcommand(ctx: ExtensionCommandContext, rest: string): void {
   const value = rest.trim().toLowerCase();
   if (!value) {
     ctx.ui.notify(
       `Async pasted-path fallback: ${config.asyncClipboardHandoff ? "on" : "off"}.\n` +
-        "Usage: /vision-watcher fallback <on|off>",
+        "Usage: /vision-watcher async <on|off>",
       "info",
     );
     return;
   }
   if (value !== "on" && value !== "off") {
-    ctx.ui.notify("Usage: /vision-watcher fallback <on|off>", "warning");
+    ctx.ui.notify("Usage: /vision-watcher async <on|off>", "warning");
     return;
   }
   const on = value === "on";
@@ -1153,21 +1172,30 @@ function handleTimeoutSubcommand(ctx: ExtensionCommandContext, rest: string): vo
   );
 }
 
+/** Connected, vision-capable models — the same set the pickers show. Text-only
+ *  models can't describe images, so they would only produce
+ *  "[Image: description unavailable]" errors. getAvailable() excludes the whole
+ *  catalogue of unauthenticated models. */
+function availableVisionModels(ctx: ExtensionCommandContext): Array<{
+  provider: string;
+  id: string;
+  name: string;
+  input?: ("text" | "image")[];
+  reasoning?: boolean;
+}> {
+  return ctx.modelRegistry
+    .getAvailable()
+    .map((m) => ({ provider: m.provider, id: m.id, name: m.name, input: m.input, reasoning: m.reasoning }))
+    .filter((m) => isVisionModel(m));
+}
+
 async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
   if (!ctx.hasUI) {
     ctx.ui.notify("/vision-watcher requires interactive mode.", "error");
     return;
   }
 
-  // Only list models that are actually connected (configured auth via /login,
-  // /better-custom, a models.json apiKey, or env/command keys) — the same set
-  // the built-in /model picker shows. getAvailable() excludes the whole
-  // catalogue of unauthenticated models.
-  // Only vision-capable models can describe images — text-only models are hidden.
-  const availableModels = ctx.modelRegistry
-    .getAvailable()
-    .map((m) => ({ provider: m.provider, id: m.id, name: m.name, input: m.input, reasoning: m.reasoning }))
-    .filter((m) => isVisionModel(m));
+  const availableModels = availableVisionModels(ctx);
 
   if (ctx.mode !== "tui") {
     const modelItems = ["None", ...availableModels.map((m) => `${m.provider}/${m.id}`)];
@@ -1204,6 +1232,7 @@ async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
       config.thinkingLevel,
       config.asyncClipboardHandoff,
       (r) => done(r),
+      config.fallbackModels,
     );
     return {
       render(width: number) {
@@ -1233,10 +1262,16 @@ async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
   const thinkingNote = thinking
     ? `thinking on (${thinkingLevel})${ref ? " — applies only if the vision model supports reasoning" : ""}`
     : "thinking off";
+  const fallbackModels = result.fallbackModels ?? config.fallbackModels;
+  const fallbackNote = fallbackModels.length
+    ? ` · 🔁 fallbacks: ${fallbackModels.join(" → ")}`
+    : " · 🔁 no fallbacks";
   updateConfig(
     ctx,
-    (c) => ({ ...c, visionModel: ref, thinking, thinkingLevel, asyncClipboardHandoff }),
-    ref ? `Vision model set to ${ref} · ${thinkingNote}` : `Vision model cleared · ${thinkingNote}`,
+    (c) => ({ ...c, visionModel: ref, thinking, thinkingLevel, asyncClipboardHandoff, fallbackModels }),
+    ref
+      ? `Vision model set to ${ref} · ${thinkingNote}${fallbackNote}`
+      : `Vision model cleared · ${thinkingNote}${fallbackNote}`,
   );
   if (!ref) {
     ctx.ui.notify("Handoff is inactive until you pick a vision model.", "warning");
@@ -1252,6 +1287,7 @@ function showStatus(ctx: ExtensionCommandContext): void {
   lines.push(`Thinking: ${config.thinking ? `on (${config.thinkingLevel})` : "off"}`);
   lines.push(`Paste-time prewarm: ${config.prewarmPastedImages ? `on${editorInstalled ? "" : " (inactive — another custom editor is active)"}` : "off"}`);
   lines.push(`Async pasted-path fallback: ${config.asyncClipboardHandoff ? "on" : "off"}`);
+  lines.push(`Fallback models: ${config.fallbackModels.length ? config.fallbackModels.join(" → ") : "(none)"}`);
   lines.push(`Timeout (per image): ${config.describeTimeoutMs} ms`);
   lines.push(`maxTokens: ${config.maxTokens ?? "unbounded"} · cacheMax: ${config.cacheMax} · maxDescriptionLines: ${config.maxDescriptionLines === 0 ? "unbounded" : config.maxDescriptionLines}`);