dsh-vision-router 1.4.1 → 1.4.2

package/README.md

@@ -15,8 +15,8 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.1"><img src="https://img.shields.io/badge/release-v1.4.1-5B4CF0?style=flat-square" alt="Release v1.4.1" /></a>
-  <a href="tests"><img src="https://img.shields.io/badge/verified-149%20tests-2EA44F?style=flat-square" alt="Verified: 149 tests" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.2"><img src="https://img.shields.io/badge/release-v1.4.2-5B4CF0?style=flat-square" alt="Release v1.4.2" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-252%20tests-2EA44F?style=flat-square" alt="Verified: 252 tests" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
   <img src="https://img.shields.io/badge/runtime-no%20Python-8A2BE2?style=flat-square" alt="No Python" />
@@ -28,9 +28,9 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v1.4.1)**
+> 📌 **Announcement (v1.4.2)**
 >
-> **v1.4.1 now supports** hardened vision failure handling — a single broken vision backend (401 / 429 / outage) can no longer stall a text turn: circuit breaking, shared task budgets and structured failure results keep DeepSeek conversations moving.
+> **v1.4.2 now supports** Oh-DSH Desktop — the plugin no longer races the stock DeepSeek route on the bundled DSH 0.1.0-rc.5 runtime (fixes "DSH runtime exited before readiness"), opencode-go qwen3.6-plus vision calls reach the correct Anthropic endpoint, and "+ Auto Vision" twins keep the picker's reasoning effort across multi-step turns.
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />
@@ -40,6 +40,7 @@
 
 - [Why this exists](#why-this-exists)
 - [How it compares](#how-it-compares)
+- [Acknowledgements](#acknowledgements)
 - [Quick start](#quick-start)
 - [Highlights](#highlights)
 - [How it works](#how-it-works)
@@ -61,20 +62,41 @@ Most DSH vision plugins bridge images to DeepSeek as *text descriptions* — los
 
 ## How it compares
 
-The closest alternative is [@anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) (Anionex), a native DSH bundle of the well-known `agent-vision-toolkit` lineage. Both packages ship a `vision-tools` skill and a family of pixel-level tools; they differ in philosophy — **zero-config paste-and-go** versus **agent-driven visual engineering**:
+**One-line take**: most dsh vision plugins turn images into *text descriptions* for DeepSeek
+(description bridge — lossy); this plugin hands the image turn *straight to a vision model*
+(routing bridge — pixel-faithful), with a built-in keyless free fallback.
 
-| | dsh-vision-router | @anionex/dsh-vision-toolkit |
-|---|---|---|
-| Image Q&A out of the box | ✅ Built-in free chain (anonymous OVHcloud endpoint) — no account, no key | Requires your own vision API key (local pixel tools work without one) |
-| Runtime | ✅ Node only — no Python | Python 3.11+ managed runtime |
-| Getting an image in | ✅ Pick a “+ Auto Vision” group once, then paste directly | Workspace path + `/vision-tools` command, then explicit tool calls |
-| Turn routing | ✅ Image turns switch to vision, text turns switch back to DeepSeek — optional stealth takeover keeps the model picker looking stock | Tool-driven; no whole-turn auto-routing |
-| Profiles | Web | Web + Headless |
-| Playbooks | The pixel loop: ground → crop → diff → fix → screenshot again | Richer case library (long-screenshot OCR, UI restoration, GUI automation) |
-| Tests | 144 | 162 |
-| Install | One command | One command (npm) |
+| | Manual model switching | MCP vision bridge | dsh-vision-router |
+|---|---|---|---|
+| Pixel fidelity | ✅ full (when switched) | ❌ text description only | ✅ full, on the image turn |
+| Automatic | ❌ | ✅ | ✅ |
+| Daily model untouched | ❌ (whole session swapped) | ✅ | ✅ |
+| Provider failure recovery | ❌ | ❌ | ✅ fallback chains |
+| Reusable structured queries | — | partial | ✅ JSON mode + caching |
+| Free out-of-the-box | ❌ | ❌ | ✅ built-in keyless endpoint |
+| Fits dsh composition | — | external server | ✅ one plugin row |
+
+**Difference from existing dsh community projects** (all excellent, each with its own focus; descriptions reflect their READMEs as of 2026-08):
 
-Both are MIT-licensed and one command away. Pick this plugin when you want images to *just work* with zero setup; pick theirs when you need headless profiles or the extended playbook library. (Feature comparison reflects their README as of 2026-08.)
+| Project | Approach | What this plugin adds |
+|---|---|---|
+| [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | Pre-describes images with an external VLM; the description joins the session as a message to DeepSeek; LLM7.io anonymous endpoint by default (OVHcloud listed as a no-key alternative) | Description bridge; this plugin adds raw-image routing, with `vision_describe` covering descriptions on demand |
+| [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | Wraps a provider route and transcribes images into text in the request stream | Transcription bridge; this plugin wraps no provider — it rewrites routing through `agent/request` waterfalls |
+| [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | Registers `DeepSeek + Vision` combined routes: images are described by the chosen vision model before reaching DeepSeek | Two-model bridge idea; this plugin adds automatic routing, fallback chains and tools on top |
+| [modlens](https://github.com/liustack/modlens) | The first dsh vision plugin; reuses local Claude Code/Codex/OpenCode/Pi logins as vision engines | Engine-reuse idea; this plugin ships its own provider chain and depends on no other local CLI |
+| [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | Ten intent-aware visual tools (Q&A/OCR/pixel verification/UI restoration), called explicitly on demand | Broader tool set; this plugin adds whole-turn auto-routing and a keyless free fallback |
+| [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | An `inspect_image` tool plus an `agent/pre-step` waterfall bridge (pasted images become tool hints before entering the log) | Similar waterfall bridge; this plugin adds turn routing, fallback chains, caching and the free endpoint |
+
+## Acknowledgements
+
+This project borrows ideas from all of the above — especially the keyless free-endpoint
+exploration (LLM7.io and OVHcloud anonymous tiers) by
+[dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar). Thanks to the authors of
+[dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy),
+[dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider),
+[modlens](https://github.com/liustack/modlens),
+[dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit), and
+[dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision).
 
 ## Quick start
 
@@ -283,6 +305,7 @@ Everything is optional; defaults work out of the box. Edit via the Web card or a
 | `timeoutMs` | `120000` | per vision call deadline |
 | `artifactsDir` | `.dsh-vision-router/artifacts` | artifact directory (relative to the session workspace) |
 | `proxy` / `proxyHosts` | `''` / openrouter hosts | optional proxy for vision provider hosts only |
+| `catalogCorrections` | `true` | built-in catalog-routing corrections: when the installed pi-ai catalog routes a known model to the wrong wire protocol (e.g. `opencode-go/qwen3.6-plus` to OpenAI chat completions while OpenCode Go only serves it on `/v1/messages`), the plugin answers that backend directly over the corrected protocol. Each correction disarms itself once the catalog is fixed upstream |
 
 ## Requirements
 
@@ -317,6 +340,25 @@ npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
 
 When first adding the plugin to an already long-lived Web profile, let that Web process reload the plugin bundle; the host discovers the browser bundle through `dsh.client` at startup. **After the plugin is loaded, model-catalog and wrapper-scope changes hot-update and do not require a restart.**
 
+### Oh-DSH Desktop
+
+[Oh-DSH Desktop](https://github.com/hust-open-atom-club/oh-dsh) ships its own packaged DSH runtime and its own home layout: the desktop surface runs the `desktop` profile under `~/.ohdsh` and does **not** load ordinary `~/.dsh` profiles. The `--profile web` commands above therefore install into the wrong environment on that product.
+
+Install into the desktop profile by pointing `DSH_HOME` at the Oh-DSH home:
+
+```sh
+DSH_HOME=~/.ohdsh npx @deepseek-ai/dsh plugin --profile desktop add dsh-vision-router
+```
+
+(Windows PowerShell: run `$env:DSH_HOME = "$env:USERPROFILE\.ohdsh"` first, then the same command.)
+
+> [!WARNING]
+> Oh-DSH Desktop ≤ 0.1.5 bundles DSH `0.1.0-rc.5`. `dsh-vision-router` v1.4.1 and earlier crash that runtime at startup (`configurable provider "deepseek-official" is already declared`, surfacing as `DSH runtime exited before readiness`). Install v1.4.2+.
+
+If a broken install already keeps the Desktop from starting, open `~/.ohdsh/profiles/desktop/package.json`, remove the `dsh-vision-router` entry from both `dependencies` and `dsh.profile.bundles`, save, and restart the Desktop.
+
+Oh-DSH Desktop's built-in plugin marketplace (search → prepare → isolated preview → apply, with a `previous` snapshot for recovery) also works once the community catalog lists this plugin; do not mix marketplace installs with the direct command above. The bundled `@oh-dsh/vision` (`view_image`) coexists with this plugin — the tool names do not collide.
+
 ### Disable / re-enable
 
 ```yaml

package/README.zh.md

@@ -15,8 +15,8 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.1"><img src="https://img.shields.io/badge/release-v1.4.1-5B4CF0?style=flat-square" alt="Release v1.4.1" /></a>
-  <a href="tests"><img src="https://img.shields.io/badge/verified-149%20tests-2EA44F?style=flat-square" alt="Verified: 149 tests" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v1.4.2"><img src="https://img.shields.io/badge/release-v1.4.2-5B4CF0?style=flat-square" alt="Release v1.4.2" /></a>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-252%20tests-2EA44F?style=flat-square" alt="Verified: 252 tests" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
   <img src="https://img.shields.io/badge/runtime-no%20Python-8A2BE2?style=flat-square" alt="No Python" />
@@ -28,9 +28,9 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v1.4.1）**
+> 📌 **公告（v1.4.2）**
 >
-> **v1.4.1 现已支持**：视觉失败链加固——单个视觉后端（401 / 429 / 故障）不再拖垮文本对话；熔断、共享任务预算与结构化失败结果让对话始终顺畅继续。
+> **v1.4.2 现已支持**：Oh-DSH Desktop 兼容——在内置的 DSH 0.1.0-rc.5 上不再与官方 DeepSeek 路由竞争导致启动崩溃（修复「DSH runtime exited before readiness」）；opencode-go qwen3.6-plus 视觉调用走正确的 Anthropic 端点；「+ 自动识图」twin 组在多步对话中保留选择器里的推理等级。
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
@@ -40,6 +40,7 @@
 
 - [为什么做这个](#为什么做这个)
 - [对比同类插件](#对比同类插件)
+- [致谢](#致谢)
 - [快速开始](#快速开始)
 - [亮点](#亮点)
 - [工作原理](#工作原理)
@@ -61,20 +62,39 @@
 
 ## 对比同类插件
 
-最接近的同类是 [@anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)（Anionex），它是知名 `agent-vision-toolkit` 系列的 DSH 原生版。两者都提供 `vision-tools` 技能和一组像素级工具，区别在理念：**零配置粘贴即用** vs **Agent 主导的视觉工程**：
+**一句话讲清区别**：其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"（描述桥，有信息损耗）；
+本插件主打"**图片轮直接交给视觉模型看原图**"（路由桥，像素保真），同时内置免 Key 免费模型兜底。
 
-| | dsh-vision-router | @anionex/dsh-vision-toolkit |
-|---|---|---|
-| 开箱图片问答 | ✅ 内置免费视觉链（OVHcloud 匿名端点），免注册免 Key | 远程工具需自备视觉 API Key（本地像素工具免 Key） |
-| 运行时 | ✅ 纯 Node，无需 Python | 需要 Python 3.11+ 受管运行时 |
-| 图片怎么进来 | ✅ 选一次「+ 自动识图」模型组后直接粘贴 | 工作区路径 + `/vision-tools` 命令，再显式调用工具 |
-| 轮次路由 | ✅ 图片轮切视觉、文本轮切回 DeepSeek——可选隐身接管，模型选择器与官方一致 | 工具驱动，无整轮自动路由 |
-| 支持 profile | Web | Web + Headless |
-| 玩法库 | 像素循环：定位 → 裁剪 → 对比 → 修复 → 再截图 | 更丰富的案例库（长截图 OCR、UI 还原、GUI 自动化） |
-| 测试 | 144 | 162 |
-| 安装 | 一条命令 | 一条命令（npm） |
+| | 手动切换模型 | MCP 视觉桥 | 本插件 |
+|---|---|---|---|
+| 像素保真 | ✅ 完整（切换后） | ❌ 只有文字描述 | ✅ 完整，图片轮内 |
+| 自动化 | ❌ | ✅ | ✅ |
+| 日常模型不受影响 | ❌（整会话被换） | ✅ | ✅ |
+| 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
+| 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
+| 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
+| 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
+
+**与现有 dsh 社区方案的差异**（均为优秀项目，各有侧重；描述以各家 README 2026-08 状态为准）：
 
-两者都是 MIT 许可、一条命令安装。想要图片**粘贴即用**、零配置就选本插件；需要 Headless 部署或更丰富的案例库，可以看 @anionex/dsh-vision-toolkit。（功能对比以其 README 2026-08 状态为准。）
+| 项目 | 思路 | 本插件的差异 |
+|---|---|---|
+| [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | 图片先经外部 VLM 做 OCR/描述，描述作为会话消息交给 DeepSeek；默认 LLM7.io 匿名端点（OVHcloud 为无 Key 备选） | 描述桥方案；本插件提供"原图直看"路由，描述能力由 `vision_describe` 按需替代 |
+| [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | 包装 provider 路由，请求流里把图片转译成文本再交给 DeepSeek | 转译桥方案；本插件不包装 provider，通过 `agent/request` 瀑布改写路由 |
+| [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | 注册 `DeepSeek + Vision` 组合路由：图片先经所选视觉模型转成描述，再交给 DeepSeek | 双模型桥思路；本插件在此基础上增加自动路由、降级链与工具 |
+| [modlens](https://github.com/liustack/modlens) | 最早的 dsh 视觉插件；复用本机 Claude Code/Codex/OpenCode/Pi 等登录态作为视觉引擎 | 引擎复用思路；本插件自带供应商链，不依赖本机其他 CLI |
+| [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | 10 个意图化视觉工具（Q&A/OCR/像素校验/UI 还原），按需显式调用 | 工具集更全；本插件多出整轮自动路由与免 Key 免费兜底 |
+| [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | `inspect_image` 工具 + `agent/pre-step` 瀑布图片桥（粘贴图入日志前转成工具提示） | 瀑布桥思路相近；本插件多出轮次路由、降级链、缓存与免费端点 |
+
+## 致谢
+
+本插件借鉴了以上全部社区项目的思路，特别是 [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar)
+对免注册免 Key 视觉端点的探索（LLM7.io 与 OVHcloud 匿名层）。感谢
+[dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)、
+[dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider)、
+[modlens](https://github.com/liustack/modlens)、
+[dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)、
+[dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) 作者们的探索。
 
 ## 快速开始
 
@@ -283,6 +303,7 @@ Web 配置页在 **设置 → 插件 → 插件配置** 下注册「视觉路由
 | `timeoutMs` | `120000` | 单次视觉调用超时 |
 | `artifactsDir` | `.dsh-vision-router/artifacts` | 产物目录（相对会话工作区） |
 | `proxy` / `proxyHosts` | `''` / openrouter 域名 | 仅视觉供应商域名可选的本地代理 |
+| `catalogCorrections` | `true` | 内置目录纠错：当已安装的 pi-ai 目录把已知模型路由到错误协议时（例如 `opencode-go/qwen3.6-plus` 被指向 OpenAI chat completions，而 OpenCode Go 只在 `/v1/messages` 上提供该模型），插件直接按正确协议应答该后端；上游目录修复后每条纠错自动失效 |
 
 ## 环境要求
 
@@ -317,6 +338,25 @@ npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router
 
 首次把插件装进已经长期运行的 Web profile 时，需要让 Web 进程重新加载插件本体；宿主在启动时通过 `dsh.client` 声明发现浏览器端包。**插件加载完成后，模型目录与包装范围的变化会热更新，不需要为这些变化重启。**
 
+### Oh-DSH Desktop
+
+[Oh-DSH Desktop](https://github.com/hust-open-atom-club/oh-dsh) 自带一套独立打包的 DSH 运行时和独立的数据目录：桌面端实际运行的是 `~/.ohdsh` 下的 `desktop` profile，**不会**加载普通 `~/.dsh` 的 profile。因此上面 `--profile web` 的命令在 Oh-DSH Desktop 上会装错环境。
+
+把 `DSH_HOME` 指向 Oh-DSH 的数据目录再安装即可：
+
+```sh
+DSH_HOME=~/.ohdsh npx @deepseek-ai/dsh plugin --profile desktop add dsh-vision-router
+```
+
+（Windows PowerShell 先执行 `$env:DSH_HOME = "$env:USERPROFILE\.ohdsh"`，再运行同一命令。）
+
+> [!WARNING]
+> Oh-DSH Desktop ≤ 0.1.5 内置的是 DSH `0.1.0-rc.5`。`dsh-vision-router` v1.4.1 及更早版本会让该运行时在启动时崩溃（报 `configurable provider "deepseek-official" is already declared`，在 Oh-DSH Desktop 里表现为 `DSH runtime exited before readiness`）。请安装 v1.4.2+。
+
+如果错误安装已经导致 Desktop 无法启动：打开 `~/.ohdsh/profiles/desktop/package.json`，从 `dependencies` 和 `dsh.profile.bundles` 中删掉 `dsh-vision-router` 条目，保存后重启 Desktop。
+
+Oh-DSH Desktop 内置的插件市场（搜索 → 准备 → 隔离预览 → 应用，并保留 `previous` 快照用于恢复）在社区目录收录本插件后同样可用；不要与上面的直接安装命令混用。其内置的 `@oh-dsh/vision`（`view_image`）与本插件可共存，工具名不冲突。
+
 ### 禁用 / 恢复
 
 ```yaml

package/index.js

@@ -31,6 +31,11 @@ import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
 import { appendPromptToImageOnlyMessage, fetchWithOpenAICompatibility } from './lib/http-compat.js'
+import {
+  routingCorrectionFor,
+  toAnthropicMessages,
+  callAnthropicCompatible,
+} from './lib/catalog-corrections.js'
 import { createCachedUpdateChecker } from './lib/update-check.js'
 import { detectDshSelfUpdatePlan, runDshPluginUpdate } from './lib/self-update.js'
 import {
@@ -254,6 +259,13 @@ export const Config = z.object({
   // id (or "provider/model") per entry. Only consulted for vision BACKEND
   // capability (the session-side admission stays host-owned).
   extraVisionModels: z.array(z.string()).default([]),
+  // Built-in catalog-routing corrections (see lib/catalog-corrections.js):
+  // when the installed pi-ai catalog routes a known provider/model to the
+  // wrong wire protocol (e.g. opencode-go/qwen3.6-plus to openai-completions
+  // while the gateway only serves it on /v1/messages), the plugin dispatches
+  // that pair directly over the corrected protocol instead of the harness
+  // adapter. Each correction disarms itself once the catalog entry matches.
+  catalogCorrections: z.boolean().default(true),
   // Client-persisted UI state (issue #78): DSH Desktop serves the Web UI from
   // a random port on every launch, so origin-scoped localStorage forgets the
   // first-run onboarding dialog and it re-appeared on every boot. These keys
@@ -1952,6 +1964,15 @@ export function createNativeDeepSeekAdapter(ctx) {
  * turns with continuous multi-step operations.
  */
 export function createWrapperStreamBody(ctx, { imageMemory, delegateProvider, preserveImageInput }) {
+  // issue #103: the reasoning level is a per-session picker choice (the chat
+  // page's bottom-right selector), but the host can drop reasoningEffort from
+  // the later steps of a multi-step turn once the twin metadata lacks a
+  // reasoning.defaultEffort (only step 1 thinks). Remember the last explicit
+  // effort seen per delegate — whatever the user actually picked — and
+  // re-inject it when a later call arrives without one, so every step keeps
+  // the user's chosen level. The vision chain never flows through this body
+  // and keeps its own reasoningEffort: undefined.
+  const lastReasoningEffort = new Map() // "provider\0model" -> last explicit effort
   return {
     async *stream(options) {
       const messages = options.messages ?? []
@@ -2006,8 +2027,21 @@ export function createWrapperStreamBody(ctx, { imageMemory, delegateProvider, pr
         })
         return result.changed ? { ...message, content: result.content } : message
       })
+      // Remember per delegate+model rather than per delegate alone: the
+      // stream boundary carries no session id, so provider+model is the
+      // narrowest scope available and keeps two concurrent sessions on the
+      // same twin from sharing one memory slot.
+      const effortKey = `${delegateProvider}\u0000${options.model ?? ''}`
+      let effort = typeof options.reasoningEffort === 'string' && options.reasoningEffort !== ''
+        ? options.reasoningEffort
+        : undefined
+      if (effort !== undefined) {
+        lastReasoningEffort.set(effortKey, effort)
+      } else {
+        effort = lastReasoningEffort.get(effortKey)
+      }
       yield* ctx.llm.stream({
-        ...options,
+        ...(effort === undefined ? options : { ...options, reasoningEffort: effort }),
         provider: delegateProvider,
         messages: rewritten,
       })
@@ -2417,12 +2451,26 @@ export function apply(ctx, config = {}) {
   // ourselves is the only way to keep the DeepSeek models in the picker.
   // The settings card surfaces this condition as a hint, and re-enabling
   // the stock row restores the fully official route.
-  const officialRouteAlive = adapterAvailable(ctx.llm, 'deepseek-official')
-  const takeoverReason = stealthEnabled ? 'stealth' : officialRouteAlive ? undefined : 'official-unavailable'
+  //
+  // The takeover decision runs AFTER a short settle window, never inside
+  // apply(): entry activation is service-driven, so this row can apply
+  // BEFORE the stock llm-deepseek row (reproduced on DSH 0.1.0-rc.5 hosts,
+  // e.g. Oh-DSH Desktop). Deciding synchronously misreads the not-yet-applied
+  // stock route as dead, and our directory registration then makes the stock
+  // row's own registration throw DUPLICATE_DIRECTORY, killing the whole
+  // runtime before readiness. Once the window elapses, a registered stock
+  // route means hands off; a still-dead route means the row is genuinely
+  // absent/disabled and the takeover is safe.
+  const KEEPALIVE_SETTLE_MS = 2000
   const nativeRoute = 'deepseek-official-native'
   let stealthActive = false
+  let takeoverReason
   let nativeAdapter
-  if (takeoverReason !== undefined) {
+  let takeoverAttempted = false
+  const attemptTakeover = (reason) => {
+    if (takeoverAttempted) return
+    takeoverAttempted = true
+    takeoverReason = reason
     try {
       nativeAdapter = createNativeDeepSeekAdapter(ctx)
       const nativeHandle = ctx.llm.registerAdapter([nativeRoute], {
@@ -2470,14 +2518,33 @@ export function apply(ctx, config = {}) {
         /* the stock row may still own the directory entry */
       }
     } catch (error) {
+      nativeAdapter = undefined
       stealthActive = false
       ctx.logger?.warn(
         'vision-router: deepseek-official takeover skipped (%s: %s); keeping the visible wrapper',
-        takeoverReason,
+        reason,
         error && error.message ? error.message : String(error),
       )
     }
   }
+  const maybeTakeover = () => {
+    if (!takeoverSettled || stealthActive || takeoverAttempted) return
+    if (adapterAvailable(ctx.llm, 'deepseek-official')) {
+      if (stealthEnabled) {
+        ctx.logger?.warn(
+          'vision-router: stealth is enabled but the stock deepseek-official route is alive; disable the llm-deepseek row to take it over',
+        )
+      }
+      return
+    }
+    attemptTakeover(stealthEnabled ? 'stealth' : 'official-unavailable')
+  }
+  let takeoverSettled = false
+  const settleTimer = setTimeout(() => {
+    takeoverSettled = true
+    maybeTakeover()
+  }, KEEPALIVE_SETTLE_MS)
+  ctx.effect(() => () => clearTimeout(settleTimer), 'vision-router: takeover settle timer')
   // ── vision-http route: first-class llm route over the OpenAI-compatible
   // http providers. The built-in OVHcloud anonymous endpoint (no account, no
   // key, 2 req/min/IP) is the DEFAULT vision model, so a fresh install works
@@ -2642,7 +2709,13 @@ export function apply(ctx, config = {}) {
   // declares image input so the admission passes, shows up in the model
   // picker as "DeepSeek + 自动识图", and delegates to the real text-provider
   // adapter for anything the waterfalls did not rewrite.
-  if (wrapperRoute() !== undefined) {
+  //
+  // The adapter is built unconditionally; whether (and under which name) it
+  // mounts is reconciled reactively against the resolved settings document by
+  // syncRoutingMounts() below, so the card's wrapperRoute/routing switches
+  // take effect without a restart.
+  let wrapperAdapter
+  {
     const WRAPPER_MODEL_IDS = ['deepseek-v4-pro', 'deepseek-v4-flash']
     const wrapName = (name) => name ?? 'DeepSeek'
     const textProviderRoute = () => (stealthActive ? nativeRoute : textProvider().provider)
@@ -2653,7 +2726,7 @@ export function apply(ctx, config = {}) {
         return undefined
       }
     }
-    const wrapperAdapter = {
+    wrapperAdapter = {
       providerInfo(provider) {
         return { id: provider, name: 'DeepSeek + 自动识图' }
       },
@@ -2742,9 +2815,6 @@ export function apply(ctx, config = {}) {
         delegateProvider: textProviderRoute(),
       }),
     }
-    const handle = ctx.llm.registerAdapter([wrapperRoute()], wrapperAdapter)
-    wrapperRegistered = true
-    ctx.effect(() => handle, 'vision-router: wrapper route')
   }
 
 
@@ -2817,6 +2887,12 @@ export function apply(ctx, config = {}) {
         return false
       }
     }
+    // issue #103: the twin mirrors the source metadata one-to-one, so any
+    // reasoning.defaultEffort the source advertises is inherited as-is. The
+    // reasoning LEVEL itself stays a per-session picker choice (bottom-right
+    // selector): the wrapper body below preserves it across the twin switch
+    // by remembering the last explicit effort and re-injecting it on the
+    // later steps that arrive without one.
     return {
       providerInfo() {
         const original = originalAdapter()
@@ -2992,6 +3068,27 @@ export function apply(ctx, config = {}) {
       return undefined
     }
   }
+  // Wire facts of one resolved catalog entry — the fingerprint a routing
+  // correction is checked against ({ api, baseUrl }). Undefined when the
+  // provider is not owned by the pi-ai adapter or the entry cannot be read:
+  // corrections fail closed and the normal harness path keeps the call.
+  const resolvedCatalogFactsOf = (provider, model) => {
+    try {
+      const profile = resolvedPiAiProfileOf(provider)
+      const getModels = profile && profile.piProvider && profile.piProvider.getModels
+      if (typeof getModels !== 'function') return undefined
+      const models = getModels.call(profile.piProvider)
+      if (!Array.isArray(models)) return undefined
+      const entry = models.find((candidate) => candidate && String(candidate.id) === String(model))
+      if (!entry) return undefined
+      return {
+        api: typeof entry.api === 'string' ? entry.api : undefined,
+        baseUrl: typeof entry.baseUrl === 'string' ? entry.baseUrl : '',
+      }
+    } catch {
+      return undefined
+    }
+  }
   const channelBridgePlan = (provider, model) => {
     const rawProfile = rawChannelProfileOf(provider)
     const resolvedProfile = resolvedPiAiProfileOf(provider)
@@ -3071,6 +3168,99 @@ export function apply(ctx, config = {}) {
     )
   }
 
+  // ── catalog routing corrections (lib/catalog-corrections.js) ─────────────
+  //
+  // Known provider/model pairs whose installed pi-ai catalog routes them to
+  // the wrong wire protocol (opencode-go/qwen3.6-plus → openai-completions,
+  // while the gateway only serves it on /v1/messages). While the resolved
+  // catalog still shows the broken facts, the pair is dispatched directly
+  // over the corrected protocol; the moment upstream fixes the catalog (or
+  // the user points the route at their own gateway) the correction disarms
+  // itself and the pair returns to the harness path.
+  const routingCorrectionForPair = async (pair) => {
+    if (!pair || current().catalogCorrections === false) return undefined
+    const correction = routingCorrectionFor(
+      resolvedCatalogFactsOf(pair.provider, pair.model),
+      pair.provider,
+      pair.model,
+    )
+    if (correction === undefined) return undefined
+    const rawProfile = rawChannelProfileOf(pair.provider)
+    const resolvedProfile = resolvedPiAiProfileOf(pair.provider)
+    const apiKeyEnv = [rawProfile, resolvedProfile]
+      .map((profile) => (profile && typeof profile.apiKeyEnv === 'string' ? profile.apiKeyEnv : ''))
+      .find((ref) => ref !== '')
+    return {
+      ...correction,
+      plan: {
+        rawProfile,
+        resolvedProfile,
+        transport: {
+          baseURL: correction.baseURL,
+          api: correction.api,
+          ...(apiKeyEnv === undefined ? {} : { apiKeyEnv }),
+        },
+      },
+    }
+  }
+
+  /**
+   * One vision-model answer through a corrected route, or undefined when the
+   * pair has no active correction (callers then use the harness path). The
+   * credential is resolved exactly like the harness adapter would resolve it:
+   * the route's apiKeyEnv first, then the catalog provider's native auth
+   * (process.env.OPENCODE_API_KEY for opencode-go).
+   */
+  const correctedVisionAnswer = async (pair, messages, options = {}) => {
+    const correction = await routingCorrectionForPair(pair)
+    if (correction === undefined) return undefined
+    const apiKey = await resolveChannelApiKey(correction.plan)
+    if (apiKey === undefined || apiKey === '') {
+      throw new Error(
+        `corrected route "${pair.provider}/${pair.model}": channel credential could not be resolved`,
+      )
+    }
+    const attachments = ctx.get('attachments')
+    if (attachments === undefined) {
+      throw new Error('corrected route: the attachment service is not registered')
+    }
+    const bytesOf = async (attachment) => {
+      const stored = await attachments.readImage(attachment)
+      let bytes = stored.data
+      if (downscaleEnabled() && bytes && bytes.length > 0) {
+        bytes = await downscaleImage(bytes, downscaleMaxPixels())
+      }
+      return bytes
+    }
+    const anthropic = await toAnthropicMessages(messages, bytesOf)
+    if (anthropic.messages.length === 0) {
+      throw new Error(`corrected route "${pair.provider}/${pair.model}": no representable content to send`)
+    }
+    return callAnthropicCompatible(
+      { name: pair.provider, baseURL: correction.baseURL, model: pair.model, apiKeyEnv: '' },
+      anthropic.messages,
+      {
+        system: anthropic.system,
+        maxTokens: options.maxTokens ?? 4096,
+        signal: options.signal,
+        apiKey,
+      },
+    )
+  }
+
+  /** Shared single-answer dispatch: corrected route first, harness path otherwise. */
+  const callVisionPair = async (pair, messages, options = {}) => {
+    const corrected = await correctedVisionAnswer(pair, messages, options)
+    if (corrected !== undefined) return corrected
+    return visionAnswer(ctx.llm, {
+      provider: pair.provider,
+      model: pair.model,
+      messages,
+      maxTokens: options.maxTokens ?? 4096,
+      signal: options.signal,
+    })
+  }
+
   const collectVisionBackendCapabilities = async () => {
     const capabilities = {}
     if (typeof ctx.llm.listProviders !== 'function') return capabilities
@@ -3143,8 +3333,13 @@ export function apply(ctx, config = {}) {
   // model-switch retry. To make fallback reliable, image turns are routed to
   // this chain adapter instead; it walks the configured providers itself and
   // only surfaces a failure once every model has failed.
-  if (chainRoute() !== undefined && routingEnabled()) {
-    const chainAdapter = {
+  //
+  // Built unconditionally; syncRoutingMounts() below mounts it whenever the
+  // resolved settings enable routing, so the card's routing switch takes
+  // effect without a restart.
+  let chainAdapter
+  {
+    chainAdapter = {
       providerInfo(provider) {
         return { id: provider, name: 'Vision Chain' }
       },
@@ -3260,14 +3455,35 @@ export function apply(ctx, config = {}) {
           let failed = false
           let failMessage = 'unknown error'
           try {
-            for await (const chunk of ctx.llm.stream({
-              ...options,
-              provider: pair.provider,
-              model: pair.model,
-              reasoningEffort: undefined,
-              messages,
-              signal: combineSignals(options.signal, deadline.signal(), AbortSignal.timeout(timeoutMs())),
-            })) {
+            const streamPair = async function* () {
+              // Catalog routing corrections: pairs whose installed catalog
+              // points at the wrong wire protocol are answered directly over
+              // the corrected endpoint instead of the harness adapter.
+              const text = await correctedVisionAnswer(pair, messages, {
+                maxTokens: options.maxTokens ?? 65536,
+                signal: combineSignals(options.signal, deadline.signal(), AbortSignal.timeout(timeoutMs())),
+              })
+              if (text === undefined) {
+                yield* ctx.llm.stream({
+                  ...options,
+                  provider: pair.provider,
+                  model: pair.model,
+                  reasoningEffort: undefined,
+                  messages,
+                  signal: combineSignals(options.signal, deadline.signal(), AbortSignal.timeout(timeoutMs())),
+                })
+                return
+              }
+              if (text !== '') {
+                // Same chunk protocol as the vision-http route: a bare
+                // text-delta without block frames is dropped by assemblers.
+                yield { type: 'block-start', index: 0, blockType: 'text' }
+                yield { type: 'text-delta', index: 0, text }
+                yield { type: 'block-end', index: 0, block: { type: 'text', text } }
+              }
+              yield { type: 'finish', reason: { kind: 'stop' } }
+            }
+            for await (const chunk of streamPair()) {
               if (chunk && chunk.type === 'finish') {
                 const kind = chunk.reason && chunk.reason.kind
                 if (kind === 'error' || kind === 'aborted') {
@@ -3317,9 +3533,79 @@ export function apply(ctx, config = {}) {
         }
       },
     }
-    const handle = ctx.llm.registerAdapter([chainRoute()], chainAdapter)
-    ctx.effect(() => handle, 'vision-router: chain route')
   }
+
+  // ── reactive routing mounts ────────────────────────────────────────────────
+  //
+  // Legacy routing used to be composition-gated at apply time while the
+  // settings card exposes the same switches — flipping them mid-session left
+  // the flow half-wired (hooks reading the settings document against mounts
+  // registered from the composition). The wrapper route, the chain route and
+  // the agent/request hook now reconcile against the resolved settings
+  // document: the settings seam below runs one initial sync and re-syncs on
+  // every document change, so toggles take effect immediately.
+  let wrapperRouteHandle
+  let wrapperRouteMounted
+  let chainRouteHandle
+  let chainRouteMounted
+  const syncRoutingMounts = () => {
+    const wantWrapper = wrapperRoute()
+    if (wantWrapper !== wrapperRouteMounted) {
+      if (wrapperRouteHandle) {
+        wrapperRouteHandle()
+        wrapperRouteHandle = undefined
+        wrapperRouteMounted = undefined
+      }
+      wrapperRegistered = false
+      if (wantWrapper !== undefined) {
+        try {
+          wrapperRouteHandle = ctx.llm.registerAdapter([wantWrapper], wrapperAdapter)
+          wrapperRouteMounted = wantWrapper
+          wrapperRegistered = true
+        } catch (error) {
+          if (error && error.code === 'DUPLICATE_ADAPTER') {
+            // Another layer already serves this name: adopt it and keep the
+            // flow functional instead of failing the apply.
+            wrapperRouteMounted = wantWrapper
+            wrapperRegistered = true
+          } else {
+            throw error
+          }
+        }
+      }
+    }
+    const wantChain = routingEnabled() ? chainRoute() : undefined
+    if (wantChain !== chainRouteMounted) {
+      if (chainRouteHandle) {
+        chainRouteHandle()
+        chainRouteHandle = undefined
+        chainRouteMounted = undefined
+      }
+      if (wantChain !== undefined) {
+        try {
+          chainRouteHandle = ctx.llm.registerAdapter([wantChain], chainAdapter)
+          chainRouteMounted = wantChain
+        } catch (error) {
+          if (error && error.code === 'DUPLICATE_ADAPTER') {
+            chainRouteMounted = wantChain
+          } else {
+            throw error
+          }
+        }
+      }
+    }
+  }
+  ctx.effect(
+    () => () => {
+      if (wrapperRouteHandle) wrapperRouteHandle()
+      if (chainRouteHandle) chainRouteHandle()
+      wrapperRouteHandle = undefined
+      chainRouteHandle = undefined
+      wrapperRouteMounted = undefined
+      chainRouteMounted = undefined
+    },
+    'vision-router: reactive routing mounts',
+  )
   // session -> Map<attachmentId, ref> (uploaded images visible to vision_describe)
   const sessionAttachments = new WeakMap()
   // secondary index by session id string (agent.session object identity can change across turns)
@@ -3717,52 +4003,54 @@ export function apply(ctx, config = {}) {
     return sanitizedToolResults.changed ? { ...decision, messages } : decision
   })
 
-  if (routingEnabled()) {
-    ctx.on('agent/request', async (payload, next) => {
-      const config0 = await next()
-      const session = payload.agent && payload.agent.session
-      if (!session) return config0
-      const state = turnState.get(session)
-      if (!state || state.turn !== payload.turn) return config0
-      if (!state.hasImage) {
-        const events = session.events ?? []
-        for (let i = state.startIndex; i < events.length; i++) {
-          if (eventHasImage(events[i])) {
-            state.hasImage = true
-            break
-          }
-        }
+  // Registered unconditionally and gated at runtime so the settings card's
+  // routing switch takes effect immediately (syncRoutingMounts reconciles the
+  // adapters the same way).
+  ctx.on('agent/request', async (payload, next) => {
+    const config0 = await next()
+    if (!routingEnabled()) return config0
+    const session = payload.agent && payload.agent.session
+    if (!session) return config0
+    const state = turnState.get(session)
+    if (!state || state.turn !== payload.turn) return config0
+    if (!state.hasImage) {
+    const events = session.events ?? []
+    for (let i = state.startIndex; i < events.length; i++) {
+      if (eventHasImage(events[i])) {
+        state.hasImage = true
+        break
       }
-      if (!state.hasImage) {
-        // Reverse routing: the session's entry model is a vision provider
-        // (needed to pass the prompt admission); send text-only turns back
-        // to the text provider (DeepSeek) so daily work stays on it.
-        if (reverseRoutingEnabled()) {
-          const target = reverseRouteTarget(config0, {
-            pairs: pairs(),
-            wrapperRoute: wrapperRoute(),
-            wrapperRegistered,
-            textProvider: textProvider(),
-            hasAdapter: (provider) => adapterAvailable(ctx.llm, provider),
-          })
-          if (target !== undefined) {
-            return switchRoute(config0, target.provider, target.model)
-          }
+    }
+    }
+    if (!state.hasImage) {
+      // Reverse routing: the session's entry model is a vision provider
+      // (needed to pass the prompt admission); send text-only turns back
+      // to the text provider (DeepSeek) so daily work stays on it.
+      if (reverseRoutingEnabled()) {
+        const target = reverseRouteTarget(config0, {
+          pairs: pairs(),
+          wrapperRoute: wrapperRoute(),
+          wrapperRegistered,
+          textProvider: textProvider(),
+          hasAdapter: (provider) => adapterAvailable(ctx.llm, provider),
+        })
+        if (target !== undefined) {
+          return switchRoute(config0, target.provider, target.model)
         }
-        return config0
       }
-      // Route the image turn to the chain adapter (falls back under our own
-      // control), or directly to the first vision model when the chain route
-      // is disabled.
-      if (chainRoute() !== undefined) {
-        if (config0.provider === chainRoute()) return config0
-        return switchRoute(config0, chainRoute(), `${pairs()[0].provider}/${pairs()[0].model}`)
-      }
-      const first = pairs()[0]
-      if (first === undefined || config0.provider === first.provider) return config0
-      return switchRoute(config0, first.provider, first.model)
-    })
-  }
+      return config0
+    }
+    // Route the image turn to the chain adapter (falls back under our own
+    // control), or directly to the first vision model when the chain route
+    // is disabled.
+    if (chainRoute() !== undefined) {
+      if (config0.provider === chainRoute()) return config0
+      return switchRoute(config0, chainRoute(), `${pairs()[0].provider}/${pairs()[0].model}`)
+    }
+    const first = pairs()[0]
+    if (first === undefined || config0.provider === first.provider) return config0
+    return switchRoute(config0, first.provider, first.model)
+  })
 
   if (toolEnabled()) {
     const deepToolDefs = []
@@ -3989,13 +4277,7 @@ export function apply(ctx, config = {}) {
           try {
             let messages = baseMessages
             const signal = combineSignals(deadline.signal(), AbortSignal.timeout(timeoutMs()))
-            let text = await visionAnswer(ctx.llm, {
-              provider: pair.provider,
-              model: pair.model,
-              messages,
-              maxTokens: 4096,
-              signal,
-            })
+            let text = await callVisionPair(pair, messages, { maxTokens: 4096, signal })
             if (wantJson) {
               for (let attempt = 0; attempt < 2; attempt++) {
                 const parsed = extractJson(text)
@@ -4018,13 +4300,7 @@ export function apply(ctx, config = {}) {
                       source: { kind: 'plugin', plugin: 'dsh-vision-router' },
                     },
                   ]
-                  text = await visionAnswer(ctx.llm, {
-                    provider: pair.provider,
-                    model: pair.model,
-                    messages,
-                    maxTokens: 4096,
-                    signal,
-                  })
+                  text = await callVisionPair(pair, messages, { maxTokens: 4096, signal })
                 }
               }
               const fallback = `vision_describe: the model did not produce valid JSON. Raw output:\n${text.slice(0, 2000)}`
@@ -4352,15 +4628,14 @@ export function apply(ctx, config = {}) {
           pairCapabilities.set(pairKey, pairCapability)
         }
         try {
-          const text = await visionAnswer(ctx.llm, {
-            provider: pair.provider,
-            model: pair.model,
-            messages: [
-              { role: 'user', content: [block, { type: 'text', text: instruction }] },
-            ],
-            maxTokens: 4096,
-            signal: combineSignals(deadline.signal(), AbortSignal.timeout(timeoutMs())),
-          })
+          const text = await callVisionPair(
+            pair,
+            [{ role: 'user', content: [block, { type: 'text', text: instruction }] }],
+            {
+              maxTokens: 4096,
+              signal: combineSignals(deadline.signal(), AbortSignal.timeout(timeoutMs())),
+            },
+          )
           if (text && text.trim() !== '') return { ok: true, text: text.trim() }
         } catch (error) {
           const classification = classifyVisionFailure(error)
@@ -5337,6 +5612,9 @@ export function apply(ctx, config = {}) {
       base: config,
     })
     current = () => scope.get()
+    // With the settings document now visible, reconcile the routing mounts
+    // (wrapper route, chain route) against the resolved values.
+    syncRoutingMounts()
     sctx.effect(
       () => () => {
         // The settings provider went away: fall back to the composition entry.
@@ -5346,9 +5624,10 @@ export function apply(ctx, config = {}) {
     )
     scope.watch(() => {
       // Most consumers read current() per call, but the wrappedProviders
-      // twins are registered eagerly: re-sync them whenever the settings
-      // document loads or the user edits the wrappers section.
+      // twins and the routing mounts are registered eagerly: re-sync them
+      // whenever the settings document loads or the user edits the card.
       syncTwins()
+      syncRoutingMounts()
     })
   })
 

package/lib/catalog-corrections.js

@@ -0,0 +1,278 @@
+// Known catalog-routing corrections: provider/model entries where the
+// installed pi-ai model catalog disagrees with the provider's OFFICIAL
+// endpoint table. Each entry names the wire protocol (api) and baseURL the
+// model actually speaks. A correction only engages when the harness-resolved
+// catalog entry still routes that pair to a DIFFERENT protocol — the moment
+// the upstream catalog is fixed, the correction disarms itself and the normal
+// harness path resumes. This is deliberately data, not scattered if-blocks:
+// when a gateway renames or adds an affected model, extend the table.
+
+import { kindForHttpStatus } from './vision-resilience.js'
+
+export const CATALOG_ROUTING_CORRECTIONS = [
+  {
+    provider: 'opencode-go',
+    model: 'qwen3.6-plus',
+    // OpenCode Go official endpoints (https://opencode.ai/docs/go): Qwen3.6
+    // Plus is served ONLY through the Anthropic Messages endpoint
+    // (https://opencode.ai/zen/go/v1/messages, @ai-sdk/anthropic). The pi-ai
+    // catalog still classifies it as openai-completions, so the harness sends
+    // vision requests to /v1/chat/completions where the gateway falls back to
+    // a different model (user report: MiniMax M3 answered instead).
+    api: 'anthropic-messages',
+    baseURL: 'https://opencode.ai/zen/go',
+    // The exact broken configuration this correction recognizes. A route the
+    // user pointed elsewhere (or a catalog fixed upstream) never engages it.
+    wrongApi: 'openai-completions',
+    wrongBaseURLPrefix: 'opencode.ai/zen/go',
+  },
+  {
+    provider: 'opencode-go',
+    model: 'minimax-m2.7',
+    // Same misclassification as qwen3.6-plus; the catalog marks it text-only,
+    // so it never appears as a vision backend today — corrected for chat use
+    // and in case a future catalog declares image input on the wrong protocol.
+    api: 'anthropic-messages',
+    baseURL: 'https://opencode.ai/zen/go',
+    wrongApi: 'openai-completions',
+    wrongBaseURLPrefix: 'opencode.ai/zen/go',
+  },
+]
+
+/**
+ * Decide whether a routing correction engages for one resolved backend.
+ *
+ * @param facts - the harness-resolved catalog facts for the pair:
+ *   `{ api, baseUrl }`. Undefined (or an unknown api) fails closed — the
+ *   plugin never bypasses the harness for a route it cannot fingerprint.
+ * @param provider - provider id.
+ * @param model - model id.
+ * @param enabled - the runtime switch (settings `catalogCorrections`).
+ * @returns the correction entry to dispatch through, or undefined to use the
+ *   normal harness path.
+ */
+export function routingCorrectionFor(facts, provider, model, enabled = true) {
+  if (enabled === false) return undefined
+  if (!facts || typeof facts.api !== 'string' || facts.api === '') return undefined
+  const entry = CATALOG_ROUTING_CORRECTIONS.find(
+    (candidate) => candidate.provider === provider && candidate.model === model,
+  )
+  if (entry === undefined) return undefined
+  // Upstream fixed: the catalog now agrees with the correction — stand down.
+  if (entry.api === facts.api) return undefined
+  // The resolved route is broken in some OTHER way (or speaks yet another
+  // protocol); not the configuration this correction was written for.
+  if (entry.wrongApi !== undefined && entry.wrongApi !== facts.api) return undefined
+  // A user route pointed at their own gateway keeps its own routing: only the
+  // exact catalog baseURL this correction documents gets intercepted.
+  if (entry.wrongBaseURLPrefix !== undefined) {
+    const baseUrl = String(facts.baseUrl ?? '')
+    if (!baseUrl.includes(entry.wrongBaseURLPrefix)) return undefined
+  }
+  return entry
+}
+
+/** Normalize attachment media types to the set the Anthropic wire accepts. */
+export function anthropicMediaType(mediaType) {
+  const value = String(mediaType ?? '').toLowerCase()
+  if (value === 'image/jpg') return 'image/jpeg'
+  return value
+}
+
+function parseArguments(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value
+  if (typeof value === 'string' && value.trim() !== '') {
+    try {
+      const parsed = JSON.parse(value)
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed
+    } catch {
+      /* keep the empty object below */
+    }
+  }
+  return {}
+}
+
+async function convertBlocks(blocks, bytesOf, depth = 0) {
+  const out = []
+  if (!Array.isArray(blocks) || depth > 4) return out
+  for (const block of blocks) {
+    if (!block) continue
+    if (block.type === 'text' && typeof block.text === 'string' && block.text !== '') {
+      out.push({ type: 'text', text: block.text })
+    } else if (block.type === 'image') {
+      if (typeof bytesOf !== 'function') continue
+      let bytes
+      try {
+        bytes = await bytesOf(block.attachment)
+      } catch {
+        continue // an unreadable image must not sink the whole request
+      }
+      if (!bytes || bytes.length === 0) continue
+      out.push({
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: anthropicMediaType(block.attachment && block.attachment.mediaType) || 'image/png',
+          data: Buffer.from(bytes).toString('base64'),
+        },
+      })
+    } else if (block.type === 'tool-call') {
+      out.push({
+        type: 'tool_use',
+        id: typeof block.id === 'string' ? block.id : `call_${out.length}`,
+        name: typeof block.name === 'string' ? block.name : 'tool',
+        input: parseArguments(block.arguments),
+      })
+    } else if (block.type === 'tool-result') {
+      const nested = await convertBlocks(block.content, bytesOf, depth + 1)
+      if (nested.length > 0) {
+        out.push({
+          type: 'tool_result',
+          tool_use_id: typeof block.toolCallId === 'string' ? block.toolCallId : '',
+          content: nested,
+        })
+      }
+    } else if (block.type === 'reasoning' || block.type === 'thinking') {
+      // Prior reasoning does not belong in a vision request; skip it.
+      continue
+    } else if (Array.isArray(block.content)) {
+      out.push(...(await convertBlocks(block.content, bytesOf, depth + 1)))
+    }
+  }
+  return out
+}
+
+/**
+ * Convert harness messages into the Anthropic Messages wire shape.
+ * Consecutive same-role messages are merged (the wire requires alternation),
+ * system messages fold into the `system` string, and tool results follow the
+ * `tool_result` block convention. Unrepresentable blocks are skipped rather
+ * than failing the request — vision answers only need the visible content.
+ *
+ * @param messages - harness chat messages (array-form content blocks).
+ * @param bytesOf - async (attachment) => image bytes; image blocks are dropped
+ *   when it throws or returns nothing.
+ * @returns { system, messages } ready for the /v1/messages request body.
+ */
+export async function toAnthropicMessages(messages, bytesOf) {
+  const system = []
+  const wire = []
+  const push = (role, content) => {
+    if (content.length === 0) return
+    const last = wire[wire.length - 1]
+    if (last && last.role === role) last.content.push(...content)
+    else wire.push({ role, content })
+  }
+  for (const message of messages ?? []) {
+    if (!message) continue
+    const role = message.role
+    if (role === 'system') {
+      const text = await convertBlocks(message.content, bytesOf)
+      const joined = text.map((block) => (block.type === 'text' ? block.text : '')).join('\n').trim()
+      if (joined !== '') system.push(joined)
+      continue
+    }
+    if (role === 'user') {
+      push('user', await convertBlocks(message.content, bytesOf))
+      continue
+    }
+    if (role === 'assistant') {
+      push('assistant', await convertBlocks(message.content, bytesOf))
+      continue
+    }
+    // Any other role (tool results carried outside assistant tool-call
+    // frames, future harness shapes) folds into the user stream as text —
+    // the same posture as the vision-http route's OpenAI conversion.
+    if (typeof message.content === 'string') {
+      push('user', [{ type: 'text', text: message.content }])
+    } else if (Array.isArray(message.content)) {
+      push('user', await convertBlocks(message.content, bytesOf))
+    }
+  }
+  // The Anthropic wire rejects a conversation that does not open with a user
+  // message (e.g. history starting mid-turn with an assistant reply). Open
+  // with a synthetic marker instead of dropping real history.
+  if (wire.length > 0 && wire[0].role !== 'user') {
+    wire.unshift({ role: 'user', content: [{ type: 'text', text: '(conversation history)' }] })
+  }
+  return { system: system.join('\n').trim(), messages: wire }
+}
+
+/**
+ * One non-streaming Anthropic Messages call. Parallel to callOpenAICompatible:
+ * same credential seam, same typed failures (status/code/retry-after) so the
+ * circuit breaker and fallback chains classify it identically.
+ *
+ * @param provider - { name, baseURL, model, apiKeyEnv? }; baseURL without the
+ *   /v1 suffix (the client appends /v1/messages).
+ * @param messages - anthropic wire messages (see toAnthropicMessages).
+ * @param options - { maxTokens, signal, apiKey, resolveCredential, system }.
+ * @returns the joined assistant text content.
+ */
+export async function callAnthropicCompatible(provider, messages, options = {}) {
+  const apiKeyEnv = typeof provider.apiKeyEnv === 'string' ? provider.apiKeyEnv : ''
+  let resolvedApiKey = typeof options.apiKey === 'string' ? options.apiKey : ''
+  if (resolvedApiKey === '' && apiKeyEnv !== '') {
+    if (typeof options.resolveCredential === 'function') {
+      const hit = await options.resolveCredential(apiKeyEnv)
+      if (hit) resolvedApiKey = String(hit)
+    }
+    if (resolvedApiKey === '' && typeof process !== 'undefined' && process.env) {
+      resolvedApiKey = process.env[apiKeyEnv] ?? ''
+    }
+  }
+  if (resolvedApiKey === '') {
+    throw new Error(`anthropic provider "${provider.name}": api key is not set`)
+  }
+  const headers = {
+    'content-type': 'application/json',
+    'x-api-key': resolvedApiKey,
+    'anthropic-version': '2023-06-01',
+  }
+  const body = {
+    model: provider.model,
+    messages,
+    max_tokens: options.maxTokens ?? provider.maxTokens ?? 4096,
+    stream: false,
+  }
+  const system = options.system && String(options.system).trim() !== '' ? options.system : undefined
+  const url = `${String(provider.baseURL).replace(/\/+$/, '')}/v1/messages`
+  let response
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(system === undefined ? body : { ...body, system }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+  } catch (error) {
+    if (error && error.name === 'AbortError') {
+      const abort = new Error(`anthropic provider "${provider.name}": request aborted`)
+      abort.name = 'AbortError'
+      throw abort
+    }
+    throw new Error(`anthropic provider "${provider.name}": ${error && error.message ? error.message : String(error)}`)
+  }
+  if (!response.ok) {
+    const detail = (await response.text().catch(() => '')).slice(0, 300)
+    const retryAfter = Number(response.headers.get('retry-after'))
+    const error = new Error(`anthropic provider "${provider.name}": ${response.status} ${detail}`)
+    error.status = response.status
+    error.code = kindForHttpStatus(response.status) ?? 'HTTP_PROVIDER_FAILED'
+    if (Number.isFinite(retryAfter) && retryAfter > 0) {
+      error.providerRetryAfterMs = Math.min(retryAfter * 1000, 60 * 60 * 1000)
+    }
+    throw error
+  }
+  const data = await response.json()
+  const blocks = Array.isArray(data && data.content) ? data.content : []
+  const text = blocks
+    .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('')
+    .trim()
+  if (text === '') {
+    throw new Error(`anthropic provider "${provider.name}": response carried no text content`)
+  }
+  return text
+}

package/lib/client.js

@@ -840,6 +840,11 @@ window.__ModuleLoader__.load({
     let onboardingSeenMemory = false
     let visionGuideStepMemory
     let visionGuideMemoryAuthoritative = false
+    // Whether the app-owned settings modal has been seen open during this
+    // walkthrough round, plus a grace timer so a host re-render that rebuilds
+    // the dialog in place is not mistaken for the user closing it.
+    let visionGuidePanelSeen = false
+    let visionGuidePanelCloseTimer
     // Installed by apply(): a narrow, defensive view of the settings scope.
     // { get, set, unset } never throw, and subscribe returns a disposer (or
     // undefined when the scope is unavailable — the legacy paths take over).
@@ -1068,6 +1073,11 @@ window.__ModuleLoader__.load({
       const dialogs = Array.from(document.querySelectorAll('[role="dialog"][aria-modal="true"]'))
       return dialogs.find((dialog) => !dialog.closest || !dialog.closest('.vr-onboarding-dialog'))
     }
+    // The settings modal can close by unmounting or by the host hiding it in
+    // place; a panel that is gone or not visibly rendered counts as closed.
+    function guideSettingsPanelOpen() {
+      return guideElementUsable(guideSettingsPanel())
+    }
     function guideElementUsable(el) {
       if (!el || typeof el.getBoundingClientRect !== 'function') return false
       const rect = el.getBoundingClientRect()
@@ -1322,6 +1332,32 @@ window.__ModuleLoader__.load({
     function syncVisionGuidePrompt(t) {
       if (typeof document === 'undefined' || typeof window === 'undefined' || !document.body) return
       const step = readVisionGuideStep()
+      const panelOpen = guideSettingsPanelOpen()
+      if (step !== undefined && visionGuidePanelSeen && !panelOpen) {
+        // The settings panel was open during this walkthrough round and the
+        // user has just closed it: honor the close by ending the round
+        // instead of re-pointing the prompt at the gear and nagging again.
+        // A short grace period absorbs SPA re-renders that rebuild the dialog
+        // in place; if the panel is still gone afterwards, the guide finishes
+        // for good and can never pop back up for this round.
+        clearGuidePromptUI()
+        if (visionGuidePanelCloseTimer === undefined) {
+          visionGuidePanelCloseTimer = window.setTimeout(() => {
+            visionGuidePanelCloseTimer = undefined
+            if (readVisionGuideStep() !== undefined && !guideSettingsPanelOpen()) {
+              finishVisionSettingsGuide()
+            }
+          }, 400)
+        }
+        return
+      }
+      if (panelOpen) {
+        visionGuidePanelSeen = true
+        if (visionGuidePanelCloseTimer !== undefined) {
+          window.clearTimeout(visionGuidePanelCloseTimer)
+          visionGuidePanelCloseTimer = undefined
+        }
+      }
       const phase = guidePhase(step)
       if (phase === 'none' || phase === 'done' || phase === 'suspend') {
         // No floating layer: the walkthrough is over, the in-card callout
@@ -1359,11 +1395,21 @@ window.__ModuleLoader__.load({
       anchorGuidePrompt(visionGuidePrompt, step, phase, rect, menuOpen)
     }
     function startVisionSettingsGuide(t) {
+      visionGuidePanelSeen = false
+      if (visionGuidePanelCloseTimer !== undefined) {
+        window.clearTimeout(visionGuidePanelCloseTimer)
+        visionGuidePanelCloseTimer = undefined
+      }
       writeVisionGuideStep('step1')
       syncVisionGuidePrompt(t)
       notifyVisionGuideChanged()
     }
     function finishVisionSettingsGuide() {
+      visionGuidePanelSeen = false
+      if (visionGuidePanelCloseTimer !== undefined) {
+        window.clearTimeout(visionGuidePanelCloseTimer)
+        visionGuidePanelCloseTimer = undefined
+      }
       writeVisionGuideStep(undefined)
       removeVisionGuidePrompt()
       notifyVisionGuideChanged()
@@ -1383,6 +1429,11 @@ window.__ModuleLoader__.load({
       // snapshot changes (e.g. the first read resolves after page load).
       const unsubscribe = settingsPersistence && settingsPersistence.subscribe(sync)
       return () => {
+        visionGuidePanelSeen = false
+        if (visionGuidePanelCloseTimer !== undefined) {
+          window.clearTimeout(visionGuidePanelCloseTimer)
+          visionGuidePanelCloseTimer = undefined
+        }
         window.removeEventListener(VISION_GUIDE_EVENT, sync)
         window.removeEventListener('popstate', sync)
         window.removeEventListener('resize', sync)
@@ -2002,6 +2053,10 @@ window.__ModuleLoader__.load({
       }
       const save = async () => {
         if (blocked) return
+        // Saving ends the walkthrough: the user has reached the settings card
+        // and acted, so the guide must never nag again afterwards — even when
+        // a hidden write is rejected (dismissal stays page-authoritative).
+        finishGuide()
         setSaving(true)
         setFailed(false)
         setFailedFields([])
@@ -2234,7 +2289,14 @@ window.__ModuleLoader__.load({
               h('select', {
                 className: 'vr-input vr-select', value: visionModelVisible(row.provider, row.model) ? row.model : '',
                 disabled: editBlocked || !visionProviderVisible(row.provider),
-                onChange: (event) => updateChain(index, { provider: row.provider, model: event.target.value }),
+                onChange: (event) => {
+                  updateChain(index, { provider: row.provider, model: event.target.value })
+                  // Picking a real vision model is an active backend choice:
+                  // the walkthrough has done its job, so end it right away
+                  // instead of waiting for the in-card button. Picking only a
+                  // provider (model still empty) does not finish it.
+                  if (row.provider && event.target.value) finishGuide()
+                },
               },
                 h('option', { value: '' }, visionProviderVisible(row.provider) ? t('selectModel') : t('pickProviderFirst')),
                 modelOptionsOf(visionModelsFor(row.provider)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-router",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Eyes for text-only DeepSeek Harness agents: built-in free vision chain (no key) + pixel-level vision tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots). One-command install, no Python, image turns work like ordinary tool-calling turns.",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
     "sharp": "^0.35.3"
   },
   "scripts": {
-    "test": "node --test tests/core.test.js tests/vision-resilience.test.js tests/client.test.js tests/http-compat.test.js tests/update-check.test.js tests/self-update.test.js tests/doctor.test.js tests/doctor-cli.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/replay-delegation.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js"
+    "test": "node --test tests/core.test.js tests/vision-resilience.test.js tests/client.test.js tests/http-compat.test.js tests/catalog-corrections.test.js tests/update-check.test.js tests/self-update.test.js tests/doctor.test.js tests/doctor-cli.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/replay-delegation.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -83,4 +83,4 @@
       "patch": "./cordis.patch.yml"
     }
   }
-}
+}