@liustack/modlens 3.15.0 → 3.16.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.16.1 - 2026-08-14
+
+- **OpenChamber (OpenCode's desktop UI) is detected, and Windows detection got quieter and sharper ([#30](https://github.com/liustack/modlens/issues/30)).** Three stacked Windows gaps from one runtime-confirmed report. The env-fingerprint fallback never checked the markers opencode servers inject (`OPENCODE`, `OPENCODE_PID`, `OPENCODE_BINARY`), so OpenChamber read as "none detected" and `recover-paste` never auto-ran, while the pasted bytes sat recoverable in the opencode database the whole time; the fingerprint now resolves to `opencode`, placed before Claude Code's so nested setups pick the innermost input box. The `ps` ancestry probe now runs only off Windows: MSYS machines carry a `ps` that exists but rejects `-Ao`, and a failed child's stderr printed into every `doctor` run (the docs always said Windows skips ancestry, now the code agrees). And `findOnPath` tries the PATHEXT extensions before the bare name, so the POSIX `sh` shim npm installs next to `opencode.cmd` no longer shadows the executable into a `spawnSync ENOENT`. Thanks to @IA20201 for a report with the evidence already attached: observed env markers, doctor output, and the exact database row.
+
+## 3.16.0 - 2026-08-14
+
+- **dsh: whether a paste is taken over is now the host's call, made from real model metadata.** The browser half used to guess with a name regex, which read every vision model it did not recognize (Qwen2.5-VL, GPT-4o, ...) as text-only and hijacked its native paste. And turning `pasteToPath` off only removed the host route while the client kept capturing pastes into a 404. The client now asks `GET /modlens/paste?model=<selector label>` and the host answers from the provider registry's declared `inputModalities`, with every unknown answered conservatively: the label carries no provider id, so EVERY model whose name or id appears in it must be confirmed text-only. One image-capable match anywhere vetoes, an unreadable provider catalog vetoes (the vision twin could live there), and missing modality metadata counts as unknown, never as text-only. Verdicts are re-asked on every composer focus and every paste, the host empties its own cache on every provider-topology change (a same-named vision route mounting mid-session is seen within one round-trip), a 60-second hard age bound backstops both, and a route that vanishes mid-session costs only the pastes inside the one round-trip it takes the failure to come back, after which the client forgets its verdicts and stands down. Until a model is positively confirmed text-only, pastes stay native. The paste route's magic-byte table now matches the CLI's signature for signature (a plain `ftypmp42` video is refused instead of saved as `paste.heic`, real heic/heif brands pass), and the browser half gained its first test suite, loaded straight from `dsh/client.js`.
+- **A provider that ignores SIGTERM no longer outlives the CLI.** The SIGKILL escalation timer was unref'd, so in a standalone run it died with the event loop and a stubborn provider process survived its parent indefinitely, found by independent review with a live repro. The timer is now ref'd and cleared by the child's own exit (normal runs pay nothing, the stubborn case at most the 2s grace), pinned by a test that drives the real spawn path from a genuinely independent parent process, because inside the test runner its own timers had been masking exactly this.
+- **`config show` and error text stop leaking proxy credentials.** A proxy URL's userinfo (`http://alice:s3cr3t@proxy`) rendered verbatim in the one command whose contract is being safe to paste into an issue. It is now masked everywhere config show renders a proxy, and the shared redactor handles URL userinfo through the same WHATWG parser the runtime connects with, instead of a regex approximation: backslash authorities, slash runs, tabs inside the authority, and passwords containing `@` all get their credentials removed in normalized form, while scheme-less `//text@` prose and ordinary query `@`s stay verbatim.
+- **The release pipeline can no longer publish first and fail later.** The tag workflow validated the CHANGELOG section only after `npm publish`. The notes are now extracted and verified before anything irreversible runs. And the release script's `git push --follow-tags` could deliver the tag while a stale main was rejected, triggering a release from a tree the remote branch never contained. It now syncs with origin first, refuses a behind or diverged main and an already-existing remote tag, and pushes branch and tag atomically, together or not at all.
+- **The gates got honest.** `pnpm lint` always claimed to check `dsh` while the Biome config silently excluded it (now covered, with the plugin's own style rules); CI ran "Node 22" as latest-22.x while calling it the 22.19 floor (the matrix now runs the exact floor); and an Electron-runtime argv test pins the [#25](https://github.com/liustack/modlens/issues/25) fix against regression. Docs corrections ride along: both READMEs present the two paste flows as they actually ship, an empty `provider` is documented as the failover chain rather than a hardcoded antigravity pin, and the skill front matter carries the real 22.19 floor.
+
 ## 3.15.0 - 2026-08-14
 
 - **dsh: the vision wrap discovers every eligible provider route ([#29](https://github.com/liustack/modlens/issues/29)).** The wrapper used to bind one hardcoded upstream, so a machine with several subscription packages (opencode-go, zai, ...) had to hand-pick a single route and lose the rest. With `upstream` unset the plugin now sweeps the llm registry and registers a `modlens-<provider>` wrapper for every route carrying wrappable text-only DeepSeek/GLM models, re-sweeping on the registry's own `llm/adapters-updated` notification so late-registering routes (llm-pi-ai mounts after settings load) are picked up without polling. A `discover` array narrows the set, `families` filters as before, setting `upstream` keeps exact legacy single-route behavior, wrappers never wrap themselves, and the deepseek-official wrap keeps its historical `deepseek-modlens` id so an upgraded machine's model selection survives. Design and behavior spec contributed by @zlycode01, who also published a reference implementation in a public fork; this is an independent upstream implementation of that spec, with the polling schedule replaced by the registry notification.

package/README.md

@@ -26,7 +26,7 @@
   <img src="https://img.shields.io/badge/users-unknown-lightgrey?style=flat-square" alt="Users unknown">
 </p>
 
-DeepSeek and GLM have no vision capability and cannot read images. ModLens is a plug-in vision engine that gives a text-only model sight. **ModLens reads images pasted straight into the chat**, no saving to a file and passing a path first.
+The flagship DeepSeek and GLM chat models are text-only and cannot read images. ModLens is a plug-in vision engine that gives a text-only model sight. **ModLens reads images pasted straight into the chat**, no saving to a file and passing a path first.
 
 ## Talk to us
 
@@ -34,10 +34,13 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`, and the text-only DeepSeek model behind dsh reads images through a native `read_image` tool. If dsh warns `declares no dsh.bundle`, pnpm's release-age gate installed an old version: see [troubleshooting](docs/troubleshooting.md#dsh-says-declares-no-dshbundle--installed-as-a-plain-dependency) for the one-line fix. For pasted images, switch the model selector to one of the two entries the plugin adds, **`DeepSeek-V4-Flash (modlens vision)`** or **`DeepSeek-V4-Pro (modlens vision)`**: pastes are admitted there, converted to evidence at request time (your message keeps its native thumbnail), and answered by the same DeepSeek route. The wrap covers DeepSeek and GLM text models only; their own vision models are excluded automatically.
+**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`, and the text-only DeepSeek model behind dsh reads images through a native `read_image` tool. If dsh warns `declares no dsh.bundle`, pnpm's release-age gate installed an old version: see [troubleshooting](docs/troubleshooting.md#dsh-says-declares-no-dshbundle--installed-as-a-plain-dependency) for the one-line fix.
+
+Pasting an image works two ways. **① Just paste.** On a text-only model the pasted image lands as a private temp file and its path enters the composer — the same interaction OpenCode and Pi ship — and the `read_image` tool takes it from there. **② Pick a `(modlens vision)` entry** in the model selector (it remembers your choice, so once is enough), then paste: the thumbnail stays visible in your message, closer to the Codex app feel, and the image is converted to structured evidence at request time, answered by the same underlying route. The plugin auto-discovers every provider route carrying text-only DeepSeek or GLM models and adds a wrapped entry per route (a stock install gets **`DeepSeek-V4-Flash (modlens vision)`** and **`DeepSeek-V4-Pro (modlens vision)`**; extra routes like opencode-go or zai get their own); the two families' own vision models are excluded automatically. Which paste route applies is the host's per-model call: only a model its metadata positively confirms text-only is taken over, anything unconfirmed is left alone, so vision models keep their native paste ([details](docs/harness-setup.md)).
 
 **Paste an image and it reads it.** No saving to a file and passing a path first.
 
+- **The lightest touch on the market.** No hooks, no wrappers, no local proxy daemon, not a single line changed in any harness config: on the skill harnesses it is exactly one skill folder, on dsh exactly one plugin. Uninstalling is deleting a folder, and your agents are back to stock.
 - **Zero-config start.** Reuses what Claude Code, Codex, OpenCode, or Pi already have set up: the multimodal models on your machine go straight to work. Nothing at all? Antigravity CLI is a free no-key channel, and a free Gemini key brings a read down to 5-10 seconds.
 - **Evidence, not imagination.** Full transcription, reading-order layout regions, entity and relation lists. The model quotes specifics.
 - **Install once, use everywhere.** Verified on real machines in Claude Code, Codex, Pi, and OpenCode.

package/README.zh-CN.md

@@ -26,7 +26,7 @@
   <img src="https://img.shields.io/badge/users-unknown-lightgrey?style=flat-square" alt="Users unknown">
 </p>
 
-DeepSeek 和 GLM 没有视觉能力，无法进行图片识别。ModLens 借助外挂视觉引擎，为纯文本模型补上视觉能力。**ModLens 支持直接粘贴图片识别**，无需先保存成文件再提供路径。
+DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别。ModLens 借助外挂视觉引擎，为纯文本模型补上视觉能力。**ModLens 支持直接粘贴图片识别**，无需先保存成文件再提供路径。
 
 ## 交流
 
@@ -34,10 +34,17 @@ DeepSeek 和 GLM 没有视觉能力，无法进行图片识别。ModLens 借助
 
 ## 亮点
 
-**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `read_image` 工具读图。如果 dsh 提示 `declares no dsh.bundle`，是 pnpm 的发布冷静期把版本压旧了，一行配置可解，见[故障排查](docs/troubleshooting.zh-CN.md#dsh-提示-declares-no-dshbundle--installed-as-a-plain-dependency)。要粘贴识图，把模型选择器切到插件新增的两个条目之一：**`DeepSeek-V4-Flash (modlens vision)`** 或 **`DeepSeek-V4-Pro (modlens vision)`**，贴图放行、发请求时转成证据（你的消息保留原生缩略图）、仍由原 DeepSeek 路由回答。包装只覆盖 DeepSeek 与 GLM 的文本模型，两家自己的视觉型号自动排除。
+**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `read_image` 工具读图。如果 dsh 提示 `declares no dsh.bundle`，是 pnpm 的发布冷静期装了旧版，一行命令可解，见[故障排查](docs/troubleshooting.zh-CN.md#dsh-提示-declares-no-dshbundle--installed-as-a-plain-dependency)。
+
+DeepSeek Harness 粘贴识图有两种玩法。
+
+**① 直接粘贴** 贴进来的图片自主转换成文件路径进输入框（与 OpenCode、Pi 同款交互），`read_image` 工具接手读图。
+
+**② 切到带 `(modlens vision)` 后缀的模型变体**（选择器有记忆，选一次就行）再粘贴：缩略图直接可见、所见即所得，体验更接近 Codex App。变体由插件自动发现生成：每条承载纯文本 DeepSeek 或 GLM 模型的 provider 路由各得一组包装条目（默认安装下就是 **`DeepSeek-V4-Flash (modlens vision)`** 和 **`DeepSeek-V4-Pro (modlens vision)`**，装了 opencode-go、zai 等额外路由的机器会各自多出一组），两家自己的视觉型号自动排除。走哪条通路由 host 依据真实模型元数据逐个裁决：只有被元数据确认纯文本的模型才会被接管，确认不了的一律不动，视觉模型因此保留原生贴图（[细节](docs/harness-setup.zh-CN.md)）。
 
 **直接粘贴图片识别** 无需先保存成文件再提供路径。
 
+- **全网最轻量。** 不用 hook，不套壳，不跑本地代理进程，不改任何 harness 配置的一行字：在 skill 类 harness 里它就是一个 skill 文件夹，在 dsh 里就是一个插件。卸载等于删个文件夹，你的 agent 立刻回到原样。
 - **零配置起手。** 复用 Claude Code、Codex、OpenCode、Pi 已配置，直接复用你本机的其他多模态模型。什么都没有？Antigravity CLI 是免 key 的免费通道，配一个免费 Gemini key 可将识别耗时降至 5 到 10 秒。
 - **基于证据而非想象。** 全文转录、按阅读顺序划分的版面区块、实体与关系列表，模型引用的是具体内容。
 - **一次安装，多端可用。** Claude Code、Codex、Pi、OpenCode 均经真机验证。
@@ -75,13 +82,13 @@ npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 
 ModLens 不绑定任何单一视觉服务。视觉来源一共九个：五个内置 provider（配好任意一个就能用），加四家本机 agent CLI 的登录可以复用。先看内置的：
 
-| Provider | 需要什么 | 单次识别耗时 | 适合谁 |
-| :-- | :-- | :-- | :-- |
-| `gemini-api` | 免费 Gemini key（[三分钟领取，无需信用卡](https://aistudio.google.com)） | 5-10 秒 | 推荐默认 |
-| `openai` | 任意 OpenAI 兼容端点（key + baseUrl + model） | 5-10 秒 | qwen-vl、GLM、自建网关 |
-| `anthropic` | Anthropic API key | 5-10 秒 | 手上已有 key 的机器 |
-| `antigravity-cli` | 免费的 `agy` CLI，浏览器登录一次，无需 key | 15-45 秒 | 完全免注册起步 |
-| `claude-cli` | 已登录的 Claude Code | 20-45 秒 | 复用现有 Claude 订阅 |
+| Provider          | 需要什么                                                                 | 单次识别耗时 | 适合谁                 |
+| :---------------- | :----------------------------------------------------------------------- | :----------- | :--------------------- |
+| `gemini-api`      | 免费 Gemini key（[三分钟领取，无需信用卡](https://aistudio.google.com)） | 5-10 秒      | 推荐默认               |
+| `openai`          | 任意 OpenAI 兼容端点（key + baseUrl + model）                            | 5-10 秒      | qwen-vl、GLM、自建网关 |
+| `anthropic`       | Anthropic API key                                                        | 5-10 秒      | 手上已有 key 的机器    |
+| `antigravity-cli` | 免费的 `agy` CLI，浏览器登录一次，无需 key                               | 15-45 秒     | 完全免注册起步         |
+| `claude-cli`      | 已登录的 Claude Code                                                     | 20-45 秒     | 复用现有 Claude 订阅   |
 
 不钉死 provider 时，所有配好的引擎组成一条故障转移链：API 快车道先试，agent CLI 兜底，第一个可用结果胜出，`meta.attempts` 记录每次尝试，回退永远不是无声的。
 
@@ -104,12 +111,12 @@ modlens config set openai.model   qwen3-vl-plus
 - **你正在对话的这个 harness 本身。**在登录了订阅的 Claude Code 里用？`claude-cli` 开箱即可借它读图。装进哪个 harness，安装流程就会问哪个 harness 的授权。
 - **机器上其他的 agent CLI。**`modlens doctor` 会逐个发现，你按家授权，它们与你自己的 key 平级入链，不插队。每次复用都在 `meta.warnings` 里标明花的是谁的额度，绝不无声扣费：
 
-| 复用来源 | 需要什么 | 授权命令 | 走哪条道 |
-| :-- | :-- | :-- | :-- |
-| Codex | 已登录且有视觉模型的 Codex CLI | `config set reuse.codex true` | agent 通道，15-45 秒 |
-| OpenCode | OpenCode 里配好的视觉模型 | `config set reuse.opencode true` | agent 通道，15-45 秒 |
-| Pi | Pi 持有的模型凭据 | `config set reuse.pi true` | API key 直接升级到 5-10 秒的快车道，OAuth 驱动 Pi 本体 |
-| Grok | 已登录的 Grok CLI（SuperGrok） | `config set reuse.grok true` | agent 通道，15-45 秒 |
+| 复用来源 | 需要什么                       | 授权命令                         | 走哪条道                                               |
+| :------- | :----------------------------- | :------------------------------- | :----------------------------------------------------- |
+| Codex    | 已登录且有视觉模型的 Codex CLI | `config set reuse.codex true`    | agent 通道，15-45 秒                                   |
+| OpenCode | OpenCode 里配好的视觉模型      | `config set reuse.opencode true` | agent 通道，15-45 秒                                   |
+| Pi       | Pi 持有的模型凭据              | `config set reuse.pi true`       | API key 直接升级到 5-10 秒的快车道，OAuth 驱动 Pi 本体 |
+| Grok     | 已登录的 Grok CLI（SuperGrok） | `config set reuse.grok true`     | agent 通道，15-45 秒                                   |
 
 ### 选择与路由
 
@@ -141,16 +148,16 @@ Codex 桌面 App 中识别一张推文截图。作者、配文、照片内容（
 
 ## 文档
 
-| 文档                                               | 适用场景                                   |
-| :------------------------------------------------- | :----------------------------------------- |
-| [安装手册](INSTALL.md)                             | 一步步安装 skill（为 agent 编写）          |
+| 文档                                                     | 适用场景                                   |
+| :------------------------------------------------------- | :----------------------------------------- |
+| [安装手册](INSTALL.md)                                   | 一步步安装 skill（为 agent 编写）          |
 | [CLI 手册](docs/cli.zh-CN.md)                            | skill 所驱动的 CLI：参数、配置与体检       |
 | [故障排查](docs/troubleshooting.zh-CN.md)                | 命令报错，查成因和解法                     |
 | [配置手册](skills/modlens/references/configure.zh-CN.md) | 配置 key、切换 provider、排查配置          |
 | [输出契约](docs/output-schema.zh-CN.md)                  | 解析 JSON 或构建下游工具                   |
 | [宿主接入](docs/harness-setup.zh-CN.md)                  | 在 Codex、Claude Code、Pi、OpenCode 中配置 |
 | [安全说明](docs/security.zh-CN.md)                       | 恢复文件的权限、图片内容作为不可信输入     |
-| [更新日志](CHANGELOG.md)                           | 查询版本变更                               |
+| [更新日志](CHANGELOG.md)                                 | 查询版本变更                               |
 
 ## 参与方式
 

package/dist/main.js

@@ -355,6 +355,8 @@ async function fetchRemoteImageBase64(url, timeoutMs) {
       if (response.status >= 300 && response.status < 400) {
         const location = response.headers.get("location");
         if (!location) {
+          await response.body?.cancel().catch(() => {
+          });
           throw new Error(
             `Redirect response (${response.status}) missing location header: ${safeUrl(current.toString())}`
           );
@@ -367,12 +369,16 @@ async function fetchRemoteImageBase64(url, timeoutMs) {
         continue;
       }
       if (!response.ok) {
+        await response.body?.cancel().catch(() => {
+        });
         throw new Error(
           `Failed to download image (${response.status}): ${safeUrl(current.toString())}`
         );
       }
       const declaredLength = Number(response.headers.get("content-length"));
       if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_IMAGE_BYTES) {
+        await response.body?.cancel().catch(() => {
+        });
         throw new Error(
           `Remote image is ${declaredLength} bytes, over the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${safeUrl(current.toString())}`
         );
@@ -385,9 +391,7 @@ async function fetchRemoteImageBase64(url, timeoutMs) {
     }
     throw new Error(`Too many redirects (max ${MAX_REDIRECTS}): ${safeUrl(url)}`);
   } finally {
-    for (const dispatcher of dispatchers) {
-      void dispatcher.close();
-    }
+    await Promise.allSettled(dispatchers.map((dispatcher) => dispatcher.close()));
   }
 }
 function pinnedDispatcher(pinned) {
@@ -773,10 +777,29 @@ const TOKEN_SHAPES = [
   /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\b/g,
   // Auth headers: "Bearer xyz" / "Authorization: xyz" (space form is real).
   /\b(?:bearer|authorization)\b[=:\s]+"?[A-Za-z0-9._~+/-]{12,}"?/gi,
-  // Labeled keys need an explicit = or : separator; prose like
+  // Labeled keys need an explicit = or : separator. Prose like
   // "token limit_exceeded" is diagnostics, not a credential.
   /\b(?:token|api[-_]?key)\b\s*[=:]\s*"?[A-Za-z0-9._~+/-]{12,}"?/gi
 ];
+const URL_CANDIDATE = /\b[a-z][a-z0-9+.-]*:[^ ]*@[^ ]*/gi;
+const RAW_USERINFO = /^([a-z][a-z0-9+.-]*:[\\/]{2,4})[^\s/?#]*@/i;
+function parseUrl(candidate) {
+  try {
+    return new URL(candidate);
+  } catch {
+    return null;
+  }
+}
+function rebuildMasked(url, replacement) {
+  return `${url.protocol}//${replacement}@${url.host}${url.pathname}${url.search}${url.hash}`;
+}
+function maskUrlCredentials(url) {
+  const parsed = parseUrl(url);
+  if (parsed) {
+    return parsed.username !== "" || parsed.password !== "" ? rebuildMasked(parsed, "***") : url;
+  }
+  return url.replace(RAW_USERINFO, "$1***@");
+}
 function redactSecrets(text, knownSecrets = []) {
   let out = text;
   for (const secret of knownSecrets) {
@@ -787,6 +810,23 @@ function redactSecrets(text, knownSecrets = []) {
   for (const shape of TOKEN_SHAPES) {
     out = out.replace(shape, "[redacted]");
   }
+  out = out.replace(URL_CANDIDATE, (token) => {
+    const pieces = token.split(/(?<=[^a-z0-9+.-])(?=[a-z][a-z0-9+.-]*:[\\/]{1,4})/i);
+    if (pieces.length === 1) {
+      const parsed = parseUrl(token);
+      if (parsed) {
+        return parsed.username !== "" || parsed.password !== "" ? rebuildMasked(parsed, "[redacted]") : token;
+      }
+      return token.replace(RAW_USERINFO, "$1[redacted]@");
+    }
+    return pieces.map((piece) => {
+      const parsed = parseUrl(piece);
+      if (parsed) {
+        return parsed.password !== "" ? rebuildMasked(parsed, "[redacted]") : piece;
+      }
+      return piece.replace(RAW_USERINFO, "$1[redacted]@");
+    }).join("");
+  });
   return out;
 }
 const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
@@ -1498,7 +1538,7 @@ function renderEffectiveConfig(config2, env = process.env) {
       const value = envValue ?? fileSettings[field];
       const source = envValue ? "env" : fileSettings[field] !== void 0 ? "file" : null;
       if (value !== void 0 && source) {
-        const shown = field === "apiKey" ? maskKey(value) : value;
+        const shown = field === "apiKey" ? maskKey(value) : field === "proxy" ? maskUrlCredentials(value) : value;
         fields[field] = `${shown} (${source})`;
       }
     }
@@ -1516,9 +1556,10 @@ function renderEffectiveConfig(config2, env = process.env) {
     effective.provider = config2.provider.trim();
   }
   if (config2.proxy?.trim()) {
-    effective.proxy = `${config2.proxy.trim()} (file)`;
+    effective.proxy = `${maskUrlCredentials(config2.proxy.trim())} (file)`;
   } else if (env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy) {
-    effective.proxy = `${env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy} (env)`;
+    const raw = env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy;
+    effective.proxy = `${maskUrlCredentials(raw)} (env)`;
   }
   if (config2.guards) {
     const guards = {};
@@ -1589,7 +1630,7 @@ const PROVIDER_DESCRIPTORS = [
 ];
 function findOnPath(bin, env) {
   const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
-  const suffixes = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const suffixes = process.platform === "win32" ? [...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean), ""] : [""];
   for (const dir of dirs) {
     for (const suffix of suffixes) {
       const full = path.join(dir, bin + suffix);
@@ -2575,15 +2616,16 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
     let timedOut = false;
     let settled = false;
     let drainTimer;
+    let killTimer;
     const timer = setTimeout(() => {
       timedOut = true;
       child.kill("SIGTERM");
       settle(null);
-      setTimeout(() => {
+      killTimer = setTimeout(() => {
         if (!exited) {
           child.kill("SIGKILL");
         }
-      }, SIGKILL_GRACE_MS).unref();
+      }, SIGKILL_GRACE_MS);
     }, timeoutMs);
     const settle = (code) => {
       if (settled) {
@@ -2638,6 +2680,7 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
       settled = true;
       clearTimeout(timer);
       clearTimeout(drainTimer);
+      clearTimeout(killTimer);
       if (error.code === "ENOENT") {
         const missingCwd = !fs.existsSync(invocation.cwd);
         reject(
@@ -2652,6 +2695,7 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
     child.on("exit", (code) => {
       exitCode = code;
       exited = true;
+      clearTimeout(killTimer);
       restartDrain();
     });
     child.on("close", (code) => settle(code));
@@ -2701,27 +2745,40 @@ function detectHarnessDetailed() {
   if (override) {
     return { harness: override === "none" ? null : override, source: "override" };
   }
-  try {
-    const ps = childProcess.execFileSync("ps", ["-Ao", "pid=,ppid=,command="], {
-      encoding: "utf-8",
-      maxBuffer: 16 * 1024 * 1024
-    });
-    const found = harnessFromPsTable(ps, process.pid);
-    if (found) {
-      return { harness: found, source: "ancestry" };
+  if (process.platform !== "win32") {
+    try {
+      const ps = childProcess.execFileSync("ps", ["-Ao", "pid=,ppid=,command="], {
+        encoding: "utf-8",
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const found = harnessFromPsTable(ps, process.pid);
+      if (found) {
+        return { harness: found, source: "ancestry" };
+      }
+    } catch {
     }
-  } catch {
   }
-  if (process.env.PI_CODING_AGENT) {
-    return { harness: "pi", source: "env" };
+  const fromEnv = harnessFromEnv(process.env);
+  if (fromEnv) {
+    return { harness: fromEnv, source: "env" };
   }
-  if (process.env.CODEX_THREAD_ID || process.env.CODEX_SANDBOX) {
-    return { harness: "codex", source: "env" };
+  return { harness: null, source: "none" };
+}
+function harnessFromEnv(env) {
+  if (env.PI_CODING_AGENT) {
+    return "pi";
   }
-  if (process.env.CLAUDECODE || process.env.CLAUDE_CODE_SESSION_ID) {
-    return { harness: "claude-code", source: "env" };
+  if (env.CODEX_THREAD_ID || env.CODEX_SANDBOX) {
+    return "codex";
   }
-  return { harness: null, source: "none" };
+  if (env.OPENCODE || env.OPENCODE_PID || env.OPENCODE_BINARY) {
+    return "opencode";
+  }
+  if (env.CLAUDECODE || env.CLAUDE_CODE_SESSION_ID) {
+    return "claude-code";
+  }
+  return null;
 }
 function detectHarness() {
   return detectHarnessDetailed().harness;
@@ -3737,7 +3794,7 @@ function parsePositiveInt(raw, flag) {
   }
   return Number.parseInt(raw, 10);
 }
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.15.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.1");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").option(
   "--extra-body <json>",
   `JSON merged into the API request body, e.g. '{"thinking":{"type":"disabled"}}'`
@@ -3788,7 +3845,7 @@ program.command("recover-paste").description(
   "Recover images pasted into Claude Code, Pi, or OpenCode from local session storage (they never hit disk otherwise)"
 ).option("--count <n>", "How many recent pasted images to recover", "1").option("--out-dir <path>", "Directory to write recovered images to").option(
   "--session <id>",
-  "Claude Code session id for exact targeting (skills get it via ${CLAUDE_SESSION_ID})"
+  "Claude Code session id for exact targeting (skills get it via ${CLAUDE_CODE_SESSION_ID})"
 ).option("--transcript <path>", "Explicit transcript .jsonl or .db (overrides --session)").option(
   "--harness <name>",
   "Force the storage scope: claude-code, pi, opencode, or none (default: auto-detect via process ancestry and env)"

package/docs/harness-setup.md

@@ -72,8 +72,20 @@ OpenCode, and Claude Code hand their models, and the modlens skill's and
 `read_image` tool's primary trigger. Admission never fires because the message
 carries no image attachment.
 
-The takeover is conditional: when the selected model is a `(modlens vision)`
-variant or a known vision model, the native paste flow is left alone (variants
+The takeover is conditional, and the decision is the host's: the browser half
+asks the plugin's route whether the currently selected model is text-only,
+and the host answers from the provider registry's declared model metadata
+(`inputModalities`), not from a name heuristic. A `(modlens vision)` variant
+or any model that declares image input keeps its native paste flow (variants
 convert at request time with the thumbnail preserved; vision models read
-images themselves). `pasteToPath: false` in the plugin row turns the whole
-feature off.
+images themselves), and so does any model the host cannot resolve. Pastes
+stay native until the host has confirmed a takeover is right. A model whose
+metadata declares no input modalities counts as unresolved: absent metadata is
+never read as "confirmed text-only". Verdicts also age out (60s), so a route
+whose models changed mid-session is re-asked, not trusted forever.
+`pasteToPath: false` in the plugin row turns the whole feature off: the
+browser half stands down when the policy endpoint 404s. If the route vanishes
+mid-session after a verdict already confirmed it, the pastes made in the
+brief window before the failed upload comes back (one local round-trip) are
+lost. The client then forgets its verdicts and every later paste goes
+native.

package/docs/harness-setup.zh-CN.md

@@ -64,4 +64,4 @@ npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 
 过去在 dsh Web UI 里，**纯文本模型**下粘贴图片会死在图片准入检查这一步。插件现在带了一个浏览器端半边（由 dsh 的客户端插件系统自动加载），恰好在这种情况下接管粘贴：图片字节发到插件在 dsh web 服务器上的 `/modlens/paste` 路由（仅回环地址，校验 magic byte，上限 25 MB），落成一个私有临时文件，输入框收到的则是纯文本的文件路径。这与 Pi、OpenCode、Claude Code 递给模型的形态一致，也正是 modlens skill 和 `read_image` 工具的首要触发条件。消息里不带图片附件，准入检查根本不会触发。
 
-接管是有条件的：当选中的模型是 `(modlens vision)` 变体或已知的视觉模型时，原生粘贴流程不受影响（变体在发请求时转换且保留缩略图，视觉模型则自己读图）。在插件配置行里设 `pasteToPath: false` 可整体关掉这个功能。
+接管是有条件的，且裁决权在 host 一侧：浏览器半边先向插件路由询问当前选中的模型是否纯文本，host 用 provider 注册表里声明的模型元数据（`inputModalities`）回答，而不是靠名称猜。`(modlens vision)` 变体和任何声明支持图片输入的模型都保留原生粘贴流程（变体在发请求时转换且保留缩略图，视觉模型自己读图），host 认不出的模型同样不接管：在 host 确认该接管之前，粘贴一律走原生路径。模型元数据里没有声明输入模态的，一律算认不出：元数据缺失绝不当成「已确认纯文本」。裁决还有 60 秒时效，模型中途变了会重新问询，不会永远信旧答案。在插件配置行里设 `pasteToPath: false` 可整体关掉这个功能：策略端点 404 时浏览器半边彻底停手。若路由在裁决确认后中途消失，失败结果返回前那个短暂窗口（一次本地往返）内发生的粘贴会丢失，之后客户端清空全部裁决，后续粘贴一律走原生路径。

package/dsh/client.js

@@ -20,7 +20,7 @@ window.__ModuleLoader__.load({
     var exports = module.exports
 
     function imageFilesOf(event) {
-      var items = event.clipboardData && event.clipboardData.items
+      var items = event.clipboardData?.items
       if (!items) return []
       var files = []
       for (var i = 0; i < items.length; i++) {
@@ -33,10 +33,7 @@ window.__ModuleLoader__.load({
     }
 
     function insertText(target, text) {
-      var el =
-        target && (target.tagName === 'TEXTAREA' || target.tagName === 'INPUT')
-          ? target
-          : document.activeElement
+      var el = target && (target.tagName === 'TEXTAREA' || target.tagName === 'INPUT') ? target : document.activeElement
       if (!el || (el.tagName !== 'TEXTAREA' && el.tagName !== 'INPUT')) return
       el.focus()
       // execCommand fires the input event React's controlled textarea needs;
@@ -48,8 +45,7 @@ window.__ModuleLoader__.load({
         inserted = false
       }
       if (!inserted) {
-        var proto =
-          el.tagName === 'TEXTAREA' ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype
+        var proto = el.tagName === 'TEXTAREA' ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype
         var setter = Object.getOwnPropertyDescriptor(proto, 'value').set
         setter.call(el, el.value + text)
         el.dispatchEvent(new Event('input', { bubbles: true }))
@@ -64,7 +60,9 @@ window.__ModuleLoader__.load({
               .json()
               .catch(() => ({}))
               .then((body) => {
-                throw new Error(body.error || `paste upload failed (${res.status})`)
+                var error = new Error(body.error || `paste upload failed (${res.status})`)
+                error.status = res.status
+                throw error
               })
           }
           return res.json()
@@ -72,14 +70,6 @@ window.__ModuleLoader__.load({
       )
     }
 
-    // The takeover is for text-only models: the (modlens vision) variants
-    // convert pastes at request time with the thumbnail preserved, and real
-    // vision models read images natively — both keep the original paste UX.
-    // The model selector button's accessible label is the only client-side
-    // source of the current model; when it cannot be found, taking over is
-    // the safe default (text-only is the common case this exists for).
-    var VISION_HINT = /\(modlens vision\)|deepseek-(vl|ocr)|janus|glm-[\d.]*v\b|vision|image/i
-
     function currentModelLabel() {
       var buttons = document.querySelectorAll('button[aria-label]')
       for (var i = 0; i < buttons.length; i++) {
@@ -89,10 +79,73 @@ window.__ModuleLoader__.load({
       return ''
     }
 
+    // Whether to take a paste over is the HOST's call (GET /modlens/paste
+    // with the selector label; the host resolves it against real model
+    // metadata). A name regex here once declared every vision model it did
+    // not recognize text-only and hijacked its native paste. The verdict is
+    // cached per label and refreshed in the background; until a label has a
+    // cached `true`, pastes stay native — the safe direction for both a
+    // vision model (keeps its thumbnail) and a text-only one (keeps only its
+    // old error message, once). A 404 means the route is off (pasteToPath:
+    // false, or no host half), so the client stands down entirely instead of
+    // swallowing pastes into a dead endpoint.
+    var routeAvailable = true
+    var verdicts = {}
+    // A verdict older than this is UNKNOWN again, even while a refresh is in
+    // flight: the route's model metadata can change mid-session (discovery
+    // sweeps, provider mounts), and acting on a long-stale `true` is exactly
+    // the vision-model hijack this design exists to prevent. The bound is a
+    // backstop, since every focus and paste re-asks anyway.
+    var VERDICT_MAX_AGE_MS = 60000
+
+    function refreshVerdict(label) {
+      if (!routeAvailable) return
+      var cached = verdicts[label]
+      // Dedupe only on an in-flight request, never on freshness: the host's
+      // model inventory can change under an unchanged label (a same-named
+      // route mounting mid-session), so every focus and paste re-asks and a
+      // stale answer survives at most one local round-trip.
+      if (cached?.pending) return
+      var entry = { pending: true, takeover: cached ? cached.takeover : false, at: cached ? cached.at : 0 }
+      verdicts[label] = entry
+      fetch(`/modlens/paste?model=${encodeURIComponent(label)}`)
+        .then((res) => {
+          if (res.status === 404) {
+            routeAvailable = false
+            entry.pending = false
+            return null
+          }
+          if (!res.ok) throw new Error(`policy ${res.status}`)
+          return res.json()
+        })
+        .then((body) => {
+          entry.pending = false
+          if (body) {
+            entry.takeover = body.takeover === true
+            entry.at = Date.now()
+          }
+        })
+        .catch(() => {
+          entry.pending = false
+        })
+    }
+
+    // A paste needs the composer focused first, so a focus-time prefetch has
+    // the verdict ready before the first paste can land.
+    function onFocusIn() {
+      refreshVerdict(currentModelLabel())
+    }
+
     function onPaste(event) {
+      if (!routeAvailable) return
       var files = imageFilesOf(event)
       if (files.length === 0) return
-      if (VISION_HINT.test(currentModelLabel())) return
+      var label = currentModelLabel()
+      var cached = verdicts[label]
+      refreshVerdict(label)
+      // No fresh confirmed host verdict: leave the paste native. Wrong only
+      // for a text-only model's very first paste, and self-correcting.
+      if (!cached || cached.at === 0 || cached.takeover !== true || Date.now() - cached.at > VERDICT_MAX_AGE_MS) return
       // Take the paste before the composer's intake starts an attachment (and
       // with it the host-side image admission a text-only model fails).
       event.preventDefault()
@@ -107,15 +160,30 @@ window.__ModuleLoader__.load({
           if (text) insertText(target, `${text} `)
         })
         .catch((error) => {
-          console.error(`[modlens] paste-to-path failed: ${error && error.message ? error.message : error}`)
+          // A 404 here means the route vanished AFTER a verdict confirmed it
+          // (plugin disposed mid-session): that race can cost this one paste
+          // — preventDefault already ran — but never another. Stand down and
+          // forget every verdict, so the next paste goes native immediately.
+          if (error && error.status === 404) {
+            routeAvailable = false
+            verdicts = {}
+          }
+          console.error(`[modlens] paste-to-path failed: ${error?.message ? error.message : error}`)
         })
     }
 
     function apply(ctx) {
       document.addEventListener('paste', onPaste, true)
+      document.addEventListener('focusin', onFocusIn, true)
       // cordis effect: unregister on plugin disposal (HMR, profile reload).
       if (typeof ctx.effect === 'function') {
-        ctx.effect(() => () => document.removeEventListener('paste', onPaste, true), 'modlens: paste-to-path listener')
+        ctx.effect(
+          () => () => {
+            document.removeEventListener('paste', onPaste, true)
+            document.removeEventListener('focusin', onFocusIn, true)
+          },
+          'modlens: paste-to-path listener',
+        )
       }
     }
 

package/dsh/index.js

@@ -15,9 +15,7 @@ import { fileURLToPath } from 'node:url'
 const CLI_PATH = fileURLToPath(new URL('../dist/main.js', import.meta.url))
 // Kept in lockstep with src/schema.ts by a repo test; the plugin file cannot
 // import the TS source and stays fully dependency-free (node builtins only).
-const OUTPUT_SCHEMA = JSON.parse(
-  readFileSync(new URL('./vision-schema.json', import.meta.url), 'utf8'),
-)
+const OUTPUT_SCHEMA = JSON.parse(readFileSync(new URL('./vision-schema.json', import.meta.url), 'utf8'))
 
 const CLI_TIMEOUT_MS = 180_000
 
@@ -55,7 +53,9 @@ export function apply(ctx, config = {}) {
   if (config.pasteToPath !== false && typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], (scope) => {
       try {
-        registerPasteRoute(scope)
+        // scope carries webServer; the plugin's own ctx carries llm for the
+        // takeover verdicts.
+        registerPasteRoute(scope, ctx)
       } catch (error) {
         console.error(`[modlens] paste-to-path route skipped: ${error}`)
       }
@@ -117,9 +117,7 @@ export function apply(ctx, config = {}) {
       }
       const { stdout, stderr, code } = await run(process.execPath, cliArgs, exec.signal)
       if (code !== 0) {
-        throw new Error(
-          `modlens failed (exit ${code}): ${(stderr || stdout).trim().slice(0, 500)}`,
-        )
+        throw new Error(`modlens failed (exit ${code}): ${(stderr || stdout).trim().slice(0, 500)}`)
       }
       let parsed
       try {
@@ -140,9 +138,7 @@ export function apply(ctx, config = {}) {
     if (preferred !== fallback && /already|duplicate/i.test(String(error))) {
       try {
         ctx.tools.register(readImageTool(fallback))
-        console.error(
-          `[modlens] tool name "${preferred}" is taken by the host; registered as "${fallback}" instead`,
-        )
+        console.error(`[modlens] tool name "${preferred}" is taken by the host; registered as "${fallback}" instead`)
       } catch (retryError) {
         console.error(`[modlens] read_image registration skipped: ${retryError}`)
       }
@@ -153,27 +149,188 @@ export function apply(ctx, config = {}) {
 }
 
 // Image magic bytes for the paste route: refuse anything that is not a real
-// image before a byte touches disk. Mirrors the CLI's sniffing table.
+// image before a byte touches disk. Mirrors the CLI's sniffing table
+// (src/imageInput.ts SNIFFERS) signature for signature: full PNG magic, both
+// GIF variants, and ftyp only with a known heic/heif brand — a generic BMFF
+// (`ftypmp42`, plain video) must not be saved as an image.
 const PASTE_SNIFFS = [
-  { ext: '.png', test: (b) => b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
+  {
+    ext: '.png',
+    test: (b) =>
+      b.length >= 8 &&
+      b[0] === 0x89 &&
+      b[1] === 0x50 &&
+      b[2] === 0x4e &&
+      b[3] === 0x47 &&
+      b[4] === 0x0d &&
+      b[5] === 0x0a &&
+      b[6] === 0x1a &&
+      b[7] === 0x0a,
+  },
   { ext: '.jpg', test: (b) => b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
-  { ext: '.gif', test: (b) => b.length >= 6 && b.toString('ascii', 0, 3) === 'GIF' },
-  { ext: '.webp', test: (b) => b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP' },
-  { ext: '.heic', test: (b) => b.length >= 12 && b.toString('ascii', 4, 8) === 'ftyp' },
+  {
+    ext: '.gif',
+    test: (b) => b.length >= 6 && ['GIF87a', 'GIF89a'].includes(b.toString('ascii', 0, 6)),
+  },
+  {
+    ext: '.webp',
+    test: (b) => b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP',
+  },
+  {
+    ext: '.heic',
+    test: (b) =>
+      b.length >= 12 &&
+      b.toString('ascii', 4, 8) === 'ftyp' &&
+      ['heic', 'heix', 'hevc', 'hevx'].includes(b.toString('ascii', 8, 12)),
+  },
+  {
+    ext: '.heif',
+    test: (b) =>
+      b.length >= 12 &&
+      b.toString('ascii', 4, 8) === 'ftyp' &&
+      ['mif1', 'msf1', 'heif'].includes(b.toString('ascii', 8, 12)),
+  },
 ]
 const PASTE_MAX_BYTES = 25 * 1024 * 1024
 
 /**
- * POST /modlens/paste: image bytes in, `{ path }` out. Bound to the dsh web
- * server, which listens on loopback by default; the file is private (0600)
- * in a fresh unpredictable temp dir, magic-byte checked and size-capped.
+ * Should the browser take a paste over for the model behind this selector
+ * label? Decided here, not in the browser, because only the host holds the
+ * structured model metadata: a name regex in the client called every vision
+ * model it did not recognize text-only and hijacked its native paste.
+ *
+ * The label carries no provider id, only prose plus a display name, so the
+ * host cannot know WHICH matching model is selected: a longest-match pick
+ * was still hijackable (a text route named "Current Pro" outscored a selected
+ * vision model named "Pro", because the label's own "current" prose completed
+ * the longer name). So no picking at all: the answer is true only when EVERY
+ * model whose name or id appears in the label is positively confirmed
+ * text-only. One image-capable match anywhere vetoes; a model with no
+ * declared inputModalities is UNKNOWN, not text-only; and a provider whose
+ * catalog cannot be read is unknown too, a veto rather than a shrug, since the
+ * unreadable route is exactly where the vision twin could live. Anything
+ * unresolvable answers false: the native path is the safe default, and a
+ * text-only model merely keeps its old error message.
+ */
+async function pasteTakeoverVerdict(host, label) {
+  if (typeof label !== 'string' || label.trim() === '') return false
+  // Our own wrappers convert pastes at request time with the thumbnail
+  // preserved; taking their paste over would defeat the better path.
+  if (/\(modlens vision\)/i.test(label)) return false
+  const llm = host.llm
+  if (!llm || typeof llm.listProviders !== 'function' || typeof llm.listModels !== 'function') {
+    return false
+  }
+  const lowered = label.toLowerCase()
+  let matchedAny = false
+  for (const info of llm.listProviders()) {
+    const providerId = info?.id
+    if (!providerId) continue
+    let models = []
+    try {
+      models = await llm.listModels(providerId)
+    } catch {
+      return false
+    }
+    for (const model of models) {
+      for (const candidate of [model?.name, model?.id]) {
+        if (typeof candidate !== 'string' || candidate.length === 0) continue
+        if (!lowered.includes(candidate.toLowerCase())) continue
+        // The veto has no length floor: a vision model named "AI" appears in
+        // the label just as legitimately as a long name does, and skipping
+        // short names let a longer text-only name confirm the takeover alone.
+        const modalities = model?.inputModalities
+        if (!Array.isArray(modalities) || modalities.includes('image')) {
+          return false
+        }
+        // Positive confirmation does have a floor: one- and two-character
+        // text-only names match label prose far too easily to identify the
+        // selected model.
+        if (candidate.length >= 3) {
+          matchedAny = true
+        }
+      }
+    }
+  }
+  return matchedAny
+}
+
+// Verdicts are stable for the lifetime of a model route but the inventory can
+// grow (llm-pi-ai mounts after settings load), so cache briefly, not forever.
+const PASTE_VERDICT_TTL_MS = 15_000
+const PASTE_VERDICT_CAP = 32
+
+/**
+ * The paste route. POST /modlens/paste: image bytes in, `{ path }` out; the
+ * file is private (0600) in a fresh unpredictable temp dir, magic-byte
+ * checked and size-capped. GET /modlens/paste?model=<selector label>:
+ * `{ takeover }`: the browser half asks before ever touching a paste, so a
+ * disabled route (pasteToPath: false, or no web profile) means the client
+ * stands down instead of swallowing pastes into a 404. Bound to the dsh web
+ * server, which listens on loopback by default.
  */
-function registerPasteRoute(ctx) {
+function registerPasteRoute(ctx, host) {
+  const verdicts = new Map()
+  // The cache key is only the selector label, which cannot tell two
+  // same-named models on different routes apart. A route mounting mid-TTL
+  // (llm-pi-ai lands after settings load) could therefore serve a stale
+  // verdict computed before its vision twin existed, so every topology
+  // change empties the cache at exactly the boundary that invalidates it.
+  // The epoch guards the async gap the clear cannot reach: a verdict whose
+  // computation STARTED before the event describes a registry that no longer
+  // exists, and without the counter it was written back into the just-
+  // emptied cache and served for a full TTL.
+  let topologyEpoch = 0
+  if (typeof host.on === 'function') {
+    host.on('llm/adapters-updated', () => {
+      topologyEpoch += 1
+      verdicts.clear()
+    })
+  }
   ctx.webServer.register({
     name: 'modlens-paste',
     kind: 'exact',
     path: '/modlens/paste',
     handler: async (req, res) => {
+      if (req.method === 'GET') {
+        try {
+          const label = new URL(req.url, 'http://localhost').searchParams.get('model') ?? ''
+          const cached = verdicts.get(label)
+          let takeover
+          if (cached && Date.now() - cached.at < PASTE_VERDICT_TTL_MS) {
+            takeover = cached.takeover
+          } else {
+            // Recompute while the topology moves under the computation: an
+            // answer read from a pre-event registry snapshot must be neither
+            // cached nor served. Bounded, and the give-up answer is the
+            // conservative one.
+            let attempts = 0
+            for (;;) {
+              const startedEpoch = topologyEpoch
+              takeover = await pasteTakeoverVerdict(host, label)
+              if (topologyEpoch === startedEpoch) {
+                verdicts.delete(label)
+                verdicts.set(label, { takeover, at: Date.now() })
+                if (verdicts.size > PASTE_VERDICT_CAP) {
+                  verdicts.delete(verdicts.keys().next().value)
+                }
+                break
+              }
+              attempts += 1
+              if (attempts >= 3) {
+                takeover = false
+                break
+              }
+            }
+          }
+          res.writeHead(200, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ takeover }))
+        } catch (error) {
+          res.writeHead(500, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ error: String(error?.message ?? error) }))
+        }
+        return
+      }
       if (req.method !== 'POST') {
         res.writeHead(405).end()
         return
@@ -208,7 +365,7 @@ function registerPasteRoute(ctx) {
         res.end(JSON.stringify({ path: file }))
       } catch (error) {
         res.writeHead(500, { 'content-type': 'application/json' })
-        res.end(JSON.stringify({ error: String(error && error.message ? error.message : error) }))
+        res.end(JSON.stringify({ error: String(error?.message ? error.message : error) }))
       }
     },
   })
@@ -321,11 +478,7 @@ function registerVisionProvider(ctx, config) {
   }
 
   if (config.upstream) {
-    registerWrapper(
-      config.upstream,
-      config.providerId || 'deepseek-modlens',
-      'DeepSeek (modlens vision)',
-    )
+    registerWrapper(config.upstream, config.providerId || 'deepseek-modlens', 'DeepSeek (modlens vision)')
     return
   }
 
@@ -488,9 +641,7 @@ function abortableWait(promise, signal) {
 function contentHasImage(blocks) {
   return (
     Array.isArray(blocks) &&
-    blocks.some(
-      (b) => b?.type === 'image' || (b?.type === 'tool-result' && contentHasImage(b.content)),
-    )
+    blocks.some((b) => b?.type === 'image' || (b?.type === 'tool-result' && contentHasImage(b.content)))
   )
 }
 
@@ -574,9 +725,7 @@ async function readImageBlock(ctx, block, signal) {
     if (!stored?.data) {
       // Named failure instead of Buffer.from(undefined)'s bare TypeError the
       // next time a developer-preview release moves the field (issue #17).
-      throw new Error(
-        "attachments.readImage returned no 'data' bytes; the dsh attachment shape may have changed",
-      )
+      throw new Error("attachments.readImage returned no 'data' bytes; the dsh attachment shape may have changed")
     }
     const mediaType = stored.ref?.mediaType ?? block.attachment?.mediaType
     const ext = MEDIA_EXT[mediaType]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.15.0",
+    "version": "3.16.1",
     "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
     "type": "module",
     "bin": {

package/skills/modlens/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: modlens
 description: "Plug-in vision for text-only models. Hard rule: when a file path or URL with an image extension (.png, .jpg, .jpeg, .webp, .gif, .heic, .heif) appears anywhere in the conversation (typed by the user, injected as a `[Image: source: <path>]` line, or inside a tag) and you cannot see that image's content, run this skill on it before any other approach: no self-built OCR, no PIL, no tesseract. Also triggers on pasted-image placeholders such as `[Image #1]` and `[Unsupported Image]`. If you can actually see the image, do not use this skill. When unsure, run `modlens guard` before the first read of a session: a deny verdict means the active model has native vision and must read the image itself. Runs the modlens CLI to convert the image into structured JSON evidence: every word transcribed, layout regions, semantics, visual clues. Also use when the user asks how to install, configure, or switch modlens providers (Gemini API key, OpenAI-compatible endpoints, Claude API or Claude Code CLI)."
-compatibility: Requires network access and one of node 22+/npx, bun/bunx, or a preinstalled modlens binary on PATH.
+compatibility: Requires network access and one of node 22.19+/npx, bun/bunx, or a preinstalled modlens binary on PATH.
 allowed-tools: Bash
 ---
 
@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.15.0):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.1):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.15.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.15.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.15.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.1: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.1 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.1 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the pin and the diagnostic fields.

package/skills/modlens/references/configure.md

@@ -6,7 +6,7 @@ Read this when the user asks how to set up, configure, or switch ModLens provide
 
 ## Where config lives
 
-`~/.modlens/config.json`, managed by the CLI. Precedence: CLI flags > environment variables > config file > built-in defaults. The default provider with zero config is `antigravity-cli`.
+`~/.modlens/config.json`, managed by the CLI. Precedence: CLI flags > environment variables > config file > built-in defaults. With no `provider` set, runs walk the failover chain in order (an available `gemini-api` key is tried before the agent CLIs); a machine with nothing configured at all ends up on `antigravity-cli`.
 
 ```bash
 modlens config init                     # write a starter config (refuses to overwrite; --force to redo)
@@ -56,7 +56,7 @@ Everything lives under four top-level keys, all optional. This example shows eve
 
 Field semantics:
 
-- `provider`: which provider runs when `-p` is not given. Canonical names or aliases both work (`agy`/`antigravity` for `antigravity-cli`, `gemini` for `gemini-api`, `openai-compat` for `openai`, `claude` for `anthropic`, `claude-code` for `claude-cli`). Empty or absent means `antigravity-cli`.
+- `provider`: which provider runs when `-p` is not given. Canonical names or aliases both work (`agy`/`antigravity` for `antigravity-cli`, `gemini` for `gemini-api`, `openai-compat` for `openai`, `claude` for `anthropic`, `claude-code` for `claude-cli`). Empty or absent pins nothing: the failover chain decides, trying configured API providers before the agent CLIs.
 - `providers.<name>.<field>`: four fields exist, `apiKey`, `baseUrl`, `model`, and `extraBody`. Every provider entry is optional, and every field inside it is optional. Alias keys are read too (settings saved under `gemini` are found when `gemini-api` resolves), with the canonical key winning on conflict.
 - `providers.<name>.extraBody`: a JSON object merged into the request body of the API providers (`gemini-api`, `openai`, `anthropic`), for whatever knobs that vendor has and modlens has no flag for. Turning thinking off is the usual reason, see the section below. Nested objects merge key by key, so adding one knob leaves the rest of that block alone. The fields carrying the image, the prompt, and the schema enforcement are refused with an error naming the field. The two CLI providers take no request body, so a run on `antigravity-cli` or `claude-cli` ignores it and says so in `meta.warnings`.
 - `guards`: the invocation guard, for people who run both text-only and vision-capable models through the same client. Both lists hold glob patterns (`*` and `?`, case-insensitive, matched against the model name and `provider/model`), set with `modlens config set guards.denyModels '["gemini-3*"]'` or `guards.allowModels` (a JSON array or a comma-separated list, empty clears). Two ways to express the same intent, pick the shorter list:

package/skills/modlens/references/configure.zh-CN.md

@@ -6,7 +6,7 @@
 
 ## 配置放在哪
 
-`~/.modlens/config.json`，由 CLI 管理。优先级：CLI 参数 > 环境变量 > 配置文件 > 内置默认值。零配置时的默认 provider 是 `antigravity-cli`。
+`~/.modlens/config.json`，由 CLI 管理。优先级：CLI 参数 > 环境变量 > 配置文件 > 内置默认值。不设 `provider` 时按失败切换链依次尝试（有 `gemini-api` key 会先于 agent CLI 被试到），机器上什么都没配才会落在 `antigravity-cli`。
 
 ```bash
 modlens config init                     # 写入一份起步配置（已存在则拒绝，--force 重写）
@@ -56,7 +56,7 @@ modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、mo
 
 字段含义：
 
-- `provider`：不传 `-p` 时由哪个 provider 执行。标准名和别名都行（`agy`/`antigravity` 对应 `antigravity-cli`，`gemini` 对应 `gemini-api`，`openai-compat` 对应 `openai`，`claude` 对应 `anthropic`，`claude-code` 对应 `claude-cli`）。留空或缺失表示 `antigravity-cli`。
+- `provider`：不传 `-p` 时由哪个 provider 执行。标准名和别名都行（`agy`/`antigravity` 对应 `antigravity-cli`，`gemini` 对应 `gemini-api`，`openai-compat` 对应 `openai`，`claude` 对应 `anthropic`，`claude-code` 对应 `claude-cli`）。留空或缺失表示不钉任何一个：由失败切换链决定，已配置的 API provider 先于 agent CLI 被尝试。
 - `providers.<name>.<field>`：共四个字段，`apiKey`、`baseUrl`、`model`、`extraBody`。每个 provider 条目都可选，条目里的每个字段也都可选。别名键同样会被读取（存在 `gemini` 下的设置在解析到 `gemini-api` 时也能找到），冲突时标准键胜出。
 - `providers.<name>.extraBody`：一个 JSON 对象，合并进 API provider（`gemini-api`、`openai`、`anthropic`）的请求体，用来传厂商有而 modlens 没有对应参数的开关。最常见的用途是关掉思考，见下文小节。嵌套对象逐键合并，所以加一个开关不会动到该块里的其他内容。承载图片、提示词和 schema 约束的字段会被拒绝，报错会点名该字段。两个 CLI provider 不发请求体，所以在 `antigravity-cli` 或 `claude-cli` 上运行时它会被忽略，并在 `meta.warnings` 里说明。
 - `guards`：调用 guard，给在同一个客户端里既跑纯文本模型又跑视觉模型的人用。两个列表都放 glob 模式（支持 `*` 和 `?`，不区分大小写，同时匹配模型名和 `provider/model`），用 `modlens config set guards.denyModels '["gemini-3*"]'` 或 `guards.allowModels` 设置（JSON 数组或逗号分隔的列表都行，传空则清除）。两种写法表达同一个意图，选列表更短的那种：

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.15.0
+- Pinned CLI version: 3.16.1
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.15.0'
+$Pinned = '3.16.1'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.15.0"
+PINNED="3.16.1"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"