@liustack/modlens 3.18.2 → 3.18.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.18.4 - 2026-08-18
+
+- **Windows: cleaning up after a read can no longer take the whole process down with it ([#58](https://github.com/liustack/modlens/issues/58)).** Node 24.0.0 through 24.13.0 carry an upstream bug where `fs.rmSync` aborts the process outright (exit `0xC0000409`) instead of throwing, when the path handed to it holds non-ASCII characters (nodejs/node#58759, fixed upstream in 24.13.1). The throwaway directory each isolated CLI read runs in lives under the system temp directory, so a Windows machine whose temp path holds non-ASCII characters, a non-ASCII user name being the common way, hit that abort on the cleanup of every read, and an abort is not something a `try`/`catch` can stop. Removal now goes through the asynchronous `fs.rm`, which never reaches the affected code, keeps the one delayed retry for a directory the provider still holds open (#50), and is awaited, so a read returns only after its directory is gone or formally given up on. Thanks to @Vaking02 for the exit code and the failing path, which is what made the crash findable upstream.
+- **A schema mismatch on the openai route now names the setting that fixes it ([#59](https://github.com/liustack/modlens/issues/59)).** The error used to say "switch to gemini-api / anthropic for enforced schemas", which is advice to abandon an endpoint that one config line would have fixed, and on the Kimi Code endpoint it cost a reader a debugging round of blaming the model. The message now says what actually applies: a cut-off answer points at the token limit, a gateway that stopped for its own reason is quoted rather than diagnosed, a `response_format` of your own in `extraBody` is named as the thing deciding the shape, plain `structuredOutput: false` gets the one-liner that turns enforcement on, and only when the schema was genuinely sent and still missed does the switch-providers advice remain. Both failure branches, JSON that will not parse and JSON that parses into the wrong shape, read the same rule the request itself uses, so the advice and the request can no longer disagree. The issue also carries @StarChen-Cycler's verified recipe for the Kimi Code coding endpoint, worth finding if you run one.
+- **Windows: reads from a console-less host no longer flash a black console window per child ([#60](https://github.com/liustack/modlens/issues/60)).** A child process started from a host without a console of its own gets one allocated, and Windows shows its window. The desktop app is exactly such a host, so every read popped a console window for the provider child, and the probes and the config-file opener could do the same. Node's `windowsHide` suppresses it and defaults to off, and it was passed nowhere. Every child, in the core and in the dsh plugin, is now started through a wrapper that writes the option after the caller's, and a contract test holds the boundary: no shipped file other than the two wrappers may reach `child_process` at all, so the next child someone adds cannot forget an option it never sees. Thanks to @DoiiarX for the report and the call-site list.
+
+## 3.18.3 - 2026-08-17
+
+- **dsh: a `(modlens vision)` route now inherits the retry policy its upstream already had ([#57](https://github.com/liustack/modlens/issues/57)).** A user set `maxRetries: 50` on their route and watched the vision group give up after 2, the harness default. The wrapper registers an adapter of its own, and the method dsh reads that policy from was returning nothing, which asks for the default on a synthetic route that ultimately calls the real one. It delegates now.
+  This was the second time the wrapper had been found dropping something the upstream had, after [#49](https://github.com/liustack/modlens/issues/49) and its reasoning state, and both were reported by users rather than found here. So the fix went through every method the host calls on an adapter instead of the one that got reported, and four more came out of that. dsh captures a route's display name and retry policy when it registers, so editing your config mid-session left the wrapper on the old values; the wrappers refresh now. A revoked upstream left its wrapper behind as a route to nowhere. The duplicate-registration check matched any error containing the word "already", which is wider than the one error it was meant to catch. And a wrapper overwrote the upstream's declared input modalities instead of adding to them.
+  One deliberate behaviour change: when the upstream cannot list its models, that failure now travels instead of becoming an empty catalogue. dsh files it per provider and the model selector shows a load warning with a retry, which is both survivable and more honest than a route that appears to have no models. Thanks to @ZzAltMan, whose report came with the session log showing the wrapper's own retry event, which is what made the cause unambiguous.
+- **A wrapped route is named after the route it wraps.** Pointing the single-route configuration at anything other than DeepSeek still produced a model group labelled DeepSeek, and the refresh added above could never correct it, because the name it compared against was a constant.
+- **A route that turns out to read images itself explains itself.** The wrapper declines to bridge a model with native image input, which is right: bridging would claim work it does not do and hand the model text where it could have had the picture. But the refusal named an internal scope and offered no way out, while a session already holding that entry fails every turn. It now says what changed and which entry to pick instead, and only in that case; a model that has simply left the configured families is a different situation and keeps its own message.
+
 ## 3.18.2 - 2026-08-17
 
 - **dsh: the settings card no longer sets off Safari's password manager ([#56](https://github.com/liustack/modlens/issues/56)).** Safari's iCloud Keychain offers to enable autofill for any site carrying a password input, then shows its bubble whenever that field is focused. Here it did so for a field that is always empty: API keys live in `~/.modlens/config.json` and the host route reports only whether one is stored, never the key itself. `autocomplete="off"` cannot turn it off either, because WebKit ignores it on password fields on purpose. The field is masked with `-webkit-text-security` now, which hides the characters without ever being a password field, and it keeps a key meant for one machine out of a synced keychain. Where a browser lacks that property the field stays a password input: the nuisance is worth more than an API key rendered in clear text while somebody types it.

package/README.md

@@ -34,7 +34,7 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.2`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. Updating is the same command again. The version is named rather than `@latest` on purpose: pnpm 11 holds back releases published in the last 24 hours and resolves the tag against what survives, so `@latest` would install whatever shipped a day ago ([details](docs/harness-setup.md#keeping-it-up-to-date)).
+**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.4`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. Updating is the same command again. The version is named rather than `@latest` on purpose: pnpm 11 holds back releases published in the last 24 hours and resolves the tag against what survives, so `@latest` would install whatever shipped a day ago ([details](docs/harness-setup.md#keeping-it-up-to-date)).
 
 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 `modlens_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)).
 

package/README.zh-CN.md

@@ -34,7 +34,7 @@ DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别
 
 ## 亮点
 
-**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.2`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。更新就是再跑一遍同一条命令。这里点名版本号而不用 `@latest` 是有意的：pnpm 11 会扣住最近 24 小时内发布的版本，dist-tag 只在剩下的里面解析，用 `@latest` 装到的会是一天前发布的那个（[细节](docs/harness-setup.zh-CN.md#保持更新)）。
+**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.4`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。更新就是再跑一遍同一条命令。这里点名版本号而不用 `@latest` 是有意的：pnpm 11 会扣住最近 24 小时内发布的版本，dist-tag 只在剩下的里面解析，用 `@latest` 装到的会是一天前发布的那个（[细节](docs/harness-setup.zh-CN.md#保持更新)）。
 
 DeepSeek Harness 粘贴识图有两种玩法。
 
@@ -69,7 +69,7 @@ agy                                                           # 浏览器完成
 **DeepSeek Harness（dsh）用户不走 skill 流程**，本包就是原生 dsh 插件：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.4
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。

package/dist/main.js

@@ -2,13 +2,12 @@
 import { Command } from "commander";
 import * as fs from "fs";
 import * as path from "path";
-import * as childProcess from "child_process";
-import { execFileSync, spawn } from "child_process";
 import * as os from "os";
 import { fileURLToPath } from "url";
 import { fetch as fetch$1, Agent, ProxyAgent, EnvHttpProxyAgent } from "undici";
 import * as dns from "dns/promises";
 import { isIP } from "net";
+import { execFileSync, spawn } from "child_process";
 import { createRequire } from "module";
 import * as crypto from "crypto";
 import * as readline from "readline";
@@ -1421,6 +1420,27 @@ const kimiCliProvider = {
   // it gets a throwaway directory holding only the image.
   isolateWorkdir: true
 };
+function derivedSchemaSent(settings) {
+  return Boolean(settings?.structuredOutput) && settings?.extraBody?.response_format === void 0;
+}
+function requestShapeAdvice(settings) {
+  if (settings?.extraBody?.response_format !== void 0) {
+    return "The response_format in your extraBody replaces the schema modlens derives, so yours decides the shape here. Check it against the contract, or drop it to hand enforcement back to modlens.";
+  }
+  if (!derivedSchemaSent(settings)) {
+    return "The gateway was never asked to enforce the shape, so this is the model free-handing it. Ask the gateway instead: modlens config set openai.structuredOutput true.";
+  }
+  return "The gateway was asked to enforce the shape and answered with this anyway. Retry, or switch to gemini-api / anthropic for enforced schemas.";
+}
+function unusableOutputAdvice(finishReason, settings, quoteReason, whenFinished) {
+  if (finishReason === "length") {
+    return `The answer was cut off (finish_reason=length), so this is a length limit rather than a shape problem. Raise it, e.g. modlens config set openai.extraBody '{"max_tokens":4096}'.`;
+  }
+  if (finishReason !== void 0 && finishReason !== "stop") {
+    return `The gateway ended the answer with finish_reason=${quoteReason(finishReason)}, so it may be incomplete for a reason of its own. Check what that reason means for this endpoint before changing the request.`;
+  }
+  return `${whenFinished} ${requestShapeAdvice(settings)}`;
+}
 async function executeOpenaiCompat(options) {
   assertNoRetiredEndpointBinding("openai", options.settings ?? {});
   const apiKey = options.settings?.apiKey;
@@ -1458,7 +1478,7 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
             // caller supplied wins outright rather than being
             // merged into ours, since the two describe the same
             // thing and a blend of them describes neither.
-            ...options.settings?.structuredOutput && options.settings?.extraBody?.response_format === void 0 ? { response_format: visionResponseFormat() } : {},
+            ...derivedSchemaSent(options.settings) ? { response_format: visionResponseFormat() } : {},
             messages: [
               {
                 role: "user",
@@ -1490,8 +1510,12 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
   }
   const rawResult = extractJson(text);
   if (rawResult === null) {
-    const finishReason = payload.choices?.[0]?.finish_reason;
-    const advice = finishReason === "length" ? `The answer was cut off (finish_reason=length). Raise the limit, e.g. modlens config set openai.extraBody '{"max_tokens":4096}'.` : finishReason === void 0 || finishReason === "stop" ? "The answer ended normally but no complete JSON object could be read from it. Ask the gateway to enforce the shape: modlens config set openai.structuredOutput true." : `The gateway ended the answer with finish_reason=${quote(finishReason, (t) => truncate(t, 80))}, so it may be incomplete for a reason of its own. Check what that reason means for this endpoint before changing the request.`;
+    const advice = unusableOutputAdvice(
+      payload.choices?.[0]?.finish_reason,
+      options.settings,
+      (reason) => quote(reason, (clipped) => truncate(clipped, 80)),
+      "The answer ended normally but no complete JSON object could be read from it."
+    );
     throw new Error(
       `OpenAI-compatible API returned non-JSON output. ${advice} Output ended with: ${quote(text, tail)}`
     );
@@ -1499,8 +1523,14 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
   const result = normalizeVisionResult(rawResult);
   const missing = missingSchemaFields(result);
   if (missing.length > 0) {
+    const advice = unusableOutputAdvice(
+      payload.choices?.[0]?.finish_reason,
+      options.settings,
+      (reason) => quote(reason, (clipped) => truncate(clipped, 80)),
+      "The answer ended normally and parsed, but not into the contract."
+    );
     throw new Error(
-      `OpenAI-compatible API returned JSON that does not match the vision schema (wrong or missing: ${missing.join(", ")}). Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${quote(text)}`
+      `OpenAI-compatible API returned JSON that does not match the vision schema (wrong or missing: ${missing.join(", ")}). ${advice} Got: ${quote(text)}`
     );
   }
   return {
@@ -2019,6 +2049,12 @@ function providerChain(kind, config2, env = process.env) {
   }
   return names.filter((name) => providerAvailable(name, config2, env)).map((name) => resolveProvider(name));
 }
+function spawnHidden(command, args, options) {
+  return spawn(command, args, { ...options, windowsHide: true });
+}
+function execFileSyncHidden(file, args, options) {
+  return execFileSync(file, args, { ...options, windowsHide: true });
+}
 function existenceOf(target) {
   try {
     fs.statSync(target);
@@ -2332,7 +2368,7 @@ const DEFAULT_TTL_MS = 6 * 60 * 60 * 1e3;
 const CLI_TIMEOUT_MS = 1e4;
 function defaultRunCli(bin, args, timeoutMs) {
   const plan = resolveSpawnPlan(bin, args);
-  return execFileSync(plan.command, plan.args, {
+  return execFileSyncHidden(plan.command, plan.args, {
     encoding: "utf-8",
     timeout: timeoutMs,
     stdio: "pipe",
@@ -2920,7 +2956,7 @@ function fetchPiKey(piPath, modelId, provider, timeoutMs) {
       "--provider",
       provider
     ]);
-    const key = execFileSync(plan.command, plan.args, {
+    const key = execFileSyncHidden(plan.command, plan.args, {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"],
       timeout: timeoutMs,
@@ -3184,7 +3220,7 @@ async function runProvider(provider, model, options, resolvedInput, timeoutMs, c
       );
       parsed = parseOutput(commandResult.stdout);
     } finally {
-      isolation?.cleanup();
+      await isolation?.cleanup();
     }
   } else {
     throw new Error(
@@ -3225,19 +3261,16 @@ function validateInputFile(filePath) {
     throw new Error(`Input is not a file: ${filePath}`);
   }
 }
-function removeWorkdir(workdir) {
+async function removeWorkdir(workdir) {
   try {
-    fs.rmSync(workdir, { recursive: true, force: true });
-    return;
+    await fs.promises.rm(workdir, {
+      recursive: true,
+      force: true,
+      maxRetries: 1,
+      retryDelay: 500
+    });
   } catch {
   }
-  const retry = setTimeout(() => {
-    try {
-      fs.rmSync(workdir, { recursive: true, force: true });
-    } catch {
-    }
-  }, 500);
-  retry.unref();
 }
 function isolateImage(source) {
   const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "modlens-work-"));
@@ -3268,7 +3301,7 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
       invocation.cwd
     );
     const spawnEnv = plan.env ?? childEnv;
-    const child = spawn(plan.command, plan.args, {
+    const child = spawnHidden(plan.command, plan.args, {
       cwd: invocation.cwd,
       stdio: ["ignore", "pipe", "pipe"],
       // A provider may mark its own child, which is how kimi-cli tells a
@@ -3418,7 +3451,7 @@ function detectHarnessDetailed() {
   }
   if (process.platform !== "win32") {
     try {
-      const ps = childProcess.execFileSync("ps", ["-Ao", "pid=,ppid=,command="], {
+      const ps = execFileSyncHidden("ps", ["-Ao", "pid=,ppid=,command="], {
         encoding: "utf-8",
         maxBuffer: 16 * 1024 * 1024,
         stdio: ["ignore", "pipe", "pipe"]
@@ -4565,7 +4598,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.18.2");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.18.4");
 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"}}'`
@@ -4675,7 +4708,7 @@ program.command("doctor").description(
       configPath: CONFIG_PATH,
       // Lets doctor name an installed skill copy that is older than
       // the CLI reporting on it (issue #33).
-      version: "3.18.2"
+      version: "3.18.4"
     });
     const output = options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report);
     process.stdout.write(`${output}

package/docs/harness-setup.md

@@ -55,7 +55,7 @@ OpenCode with DeepSeek: `opencode auth login`, pick DeepSeek and paste the key (
 dsh is different from the other harnesses: modlens plugs in as a native tool, not a prompt-triggered skill. The package itself is a dsh bundle, so one command installs it into a profile:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.4
 ```
 
 This registers a `modlens_read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin keeps its touch small (raw tool registration, the llm adapter surface for the vision variants, the attachment reader, and one agent pre-step hook) and degrades loudly if any of them moves.
@@ -81,7 +81,7 @@ modlens ships often, and both install shapes freeze at whatever version they
 got. On dsh, re-run the install with the version named:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.4
 ```
 
 `npm view @liustack/modlens version` prints the current one, and this page is

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

@@ -55,7 +55,7 @@ OpenCode 接 DeepSeek：执行 `opencode auth login`，选择 DeepSeek 并粘贴
 dsh 与其他 harness 不同：modlens 以原生工具的形式接入，而不是靠提示词触发的 skill。本包自身就是一个 dsh bundle，一条命令即可装进某个 profile：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.18.4
 ```
 
 这会注册一个 `modlens_read_image` 工具，它的 schema 随每次请求抵达模型（不靠触发启发式），运行同一个包里自带的 modlens CLI，并把结构化证据作为工具的标准 JSON 输出返回。引擎、复用授权和 guard 规则仍在 `~/.modlens/config.json` 里，与其他所有 harness 共享。dsh 还在开发者预览阶段，插件接口可能变化。这个插件刻意保持很小的接触面（原生工具注册、视觉变体所用的 llm 适配层、附件读取器，以及一个 agent 执行前钩子），其中任何一处变动，它都会大声报错而不是无声退化。
@@ -71,7 +71,7 @@ dsh 的网页用户面前没有终端，所以引擎设置有一张卡片，在*
 modlens 发布很频繁，而两种安装形态都会冻结在装进来的那个版本上。dsh 上重跑一遍安装即可，版本号要点名：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.4
 ```
 
 `npm view @liustack/modlens version` 可以查到当前版本号，本页的版本号则由发布流程自动写入。

package/docs/troubleshooting.md

@@ -163,7 +163,7 @@ simply lands on an older one. Name the exact version instead, which pnpm treats
 as a deliberate request rather than a resolution:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.4
 ```
 
 `npm view @liustack/modlens version` prints the current one. pnpm 11 installs a named
@@ -178,7 +178,7 @@ file:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.18.2'
+  - '@liustack/modlens@3.18.4'
 ```
 
 Or lift the gate for a single command, which lifts it for everything that

package/docs/troubleshooting.zh-CN.md

@@ -144,7 +144,7 @@ dsh profile 装到的是旧版 modlens。`dsh.bundle` 声明从 3.9.0 起才存
 `@latest` 绕不开这一层，本页早先的说法是错的。冷静期先把候选版本过滤掉，dist-tag 才在剩下的里面解析，于是它直接落到了更旧的那个上。改成写死精确版本号，pnpm 会把它当作一次明确的指定，而不是一次解析：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.2
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.4
 ```
 
 `npm view @liustack/modlens version` 可以查到当前版本号。pnpm 11 会装上被点名的版本，11.1.3 起还会把它作为一条已批准的例外写进该 profile 的 `pnpm-workspace.yaml`，其余所有包和 modlens 以后的版本仍然留在窗口后面。
@@ -153,7 +153,7 @@ npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.18.2
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.18.2'
+  - '@liustack/modlens@3.18.4'
 ```
 
 或者只为这一条命令解除冷静期，注意它解除的是这条命令解析到的所有包，不只 modlens：

package/dsh/index.js

@@ -10,11 +10,11 @@
 // Loaded via the cordis.patch.yml row `@liustack/modlens/dsh` (see the
 // package.json `dsh.bundle` manifest). Providers, reuse grants, and guard
 // rules keep living in ~/.modlens/config.json, shared with every harness.
-import { spawn } from 'node:child_process'
 import { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { spawnHidden } from './spawnHidden.js'
 
 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
@@ -533,39 +533,71 @@ function registerVisionProvider(ctx, config, ownProviders) {
     return
   }
 
+  // dsh snapshots providerInfo and providerRetryPolicy at registration time.
+  // Keep the state and registration handle for each wrapper so an upstream
+  // replacement can refresh those snapshots instead of leaving a synthetic
+  // route on yesterday's name or recovery policy.
+  const registrations = new Map()
+  const wrapped = new Set(['deepseek-modlens'])
+  const policyKey = (policy) => (policy === undefined ? undefined : JSON.stringify(policy))
+
   const registerWrapper = (upstream, providerId, displayName) => {
-    const withVision = (info) => ({
-      ...info,
-      provider: providerId,
-      inputModalities: ['text', 'image'],
-    })
+    const state = { displayName, retryPolicyKey: undefined }
+    const withVision = (info) => {
+      const inputModalities = Array.isArray(info?.inputModalities) ? [...info.inputModalities] : []
+      if (!inputModalities.includes('text')) inputModalities.unshift('text')
+      if (!inputModalities.includes('image')) inputModalities.push('image')
+      return { ...info, provider: providerId, inputModalities }
+    }
     try {
-      ctx.llm.registerAdapter([providerId], {
+      const registration = ctx.llm.registerAdapter([providerId], {
         // Duck-typing LlmAdapter: providerInfo/providerRetryPolicy are
         // base-class defaults a plain object must supply itself (their
         // absence is exactly the silent registration failure this catch
         // used to swallow).
         providerInfo(provider) {
-          return { id: provider, name: displayName }
+          return { id: provider, name: state.displayName }
         },
         providerRetryPolicy() {
-          return undefined
+          // dsh captures this synchronously when the wrapper route registers.
+          // Returning the base default here gives the synthetic route a retry
+          // budget unrelated to the real route it ultimately calls (#57).
+          // Older preview builds exposed registration before this runtime
+          // query, so keep their former default only when the query itself is
+          // absent. A current runtime that cannot resolve `upstream` throws,
+          // and the registration boundary below fails closed instead.
+          if (typeof ctx.llm.providerRetryPolicy !== 'function') return undefined
+          const policy = ctx.llm.providerRetryPolicy(upstream)
+          state.retryPolicyKey = policyKey(policy)
+          return policy
         },
         async listModels(_provider, signal) {
-          try {
-            const models = await ctx.llm.listModels(upstream, signal)
-            return models.filter(shouldWrap).map((model) => ({
-              ...withVision(model),
-              name: `${model.name ?? model.id} (modlens vision)`,
-            }))
-          } catch {
-            return []
-          }
+          const models = await ctx.llm.listModels(upstream, signal)
+          return models.filter(shouldWrap).map((model) => ({
+            ...withVision(model),
+            name: `${model.name ?? model.id} (modlens vision)`,
+          }))
         },
         async resolveModel(_provider, model, signal) {
           const info = await ctx.llm.resolveModelInfo(upstream, model, signal)
           if (!shouldWrap(info)) {
-            throw new Error(`model "${model}" is outside the modlens vision wrap scope`)
+            // Refusing is right: wrapping a model that reads images itself
+            // would claim a bridge it does not need, hand it text evidence
+            // instead of the picture, and lose whatever its own vision does
+            // better. What was wrong is that the refusal explained nothing.
+            // A session that already picked this entry fails every turn, and
+            // the catalogue is advisory so nothing clears the stale choice,
+            // leaving the user to read internal vocabulary and guess.
+            //
+            // Only the image case gets the specific wording. The same check
+            // also fails when a model leaves the configured families, which
+            // is a different situation and keeps the general message.
+            const declaresImage = Array.isArray(info?.inputModalities) && info.inputModalities.includes('image')
+            throw new Error(
+              declaresImage
+                ? `model "${model}" declares native image input, so its "(modlens vision)" entry no longer applies. Select the same model from the provider group without "(modlens vision)".`
+                : `model "${model}" is outside the modlens vision wrap scope`,
+            )
           }
           return { ...withVision(info), id: model }
         },
@@ -583,6 +615,7 @@ function registerVisionProvider(ctx, config, ownProviders) {
         },
         evidenceCache: new Map(),
       })
+      registrations.set(upstream, { providerId, registration, state })
       // Trusted as ours only on a registration this call actually made. A
       // duplicate below means someone else holds that id, and skipping a
       // provider we do not own would let a real vision model's paste be
@@ -592,7 +625,10 @@ function registerVisionProvider(ctx, config, ownProviders) {
     } catch (error) {
       // A duplicate means a concurrent or earlier registration already won:
       // that is success for the claim, not a reason to retry forever.
-      if (/already|duplicate/i.test(String(error))) {
+      const duplicate =
+        error?.code === 'DUPLICATE_ADAPTER' ||
+        /\balready registered\b|\bduplicate (adapter|provider)\b/i.test(String(error))
+      if (duplicate) {
         console.error(`[modlens] vision provider ${providerId} already registered, keeping the existing one`)
         return true
       }
@@ -604,8 +640,85 @@ function registerVisionProvider(ctx, config, ownProviders) {
     }
   }
 
+  const dropWrapper = (upstream, current) => {
+    registrations.delete(upstream)
+    wrapped.delete(upstream)
+    ownProviders?.delete(current.providerId)
+    if (typeof current.registration === 'function') current.registration()
+  }
+
+  // A caveat for whoever reads the catch below: commitRoutes mutates the
+  // registry and only then emits, so a listener throwing during that emit
+  // means the replace already SUCCEEDED. Treating the throw as failure and
+  // disposing would drop a healthy registration. No shipped listener can
+  // throw there today, which is why this is a comment rather than a guard.
+  const refreshWrapper = (upstream, displayName) => {
+    const current = registrations.get(upstream)
+    if (!current || typeof current.registration?.replace !== 'function') return
+    let nextPolicyKey
+    try {
+      nextPolicyKey =
+        typeof ctx.llm.providerRetryPolicy === 'function' ? policyKey(ctx.llm.providerRetryPolicy(upstream)) : undefined
+    } catch (error) {
+      dropWrapper(upstream, current)
+      console.error(`[modlens] vision provider refresh removed (${current.providerId}): ${error}`)
+      return
+    }
+    if (current.state.displayName === displayName && current.state.retryPolicyKey === nextPolicyKey) return
+    const previousName = current.state.displayName
+    current.state.displayName = displayName
+    try {
+      // Re-read both adapter methods at the same atomic boundary dsh's own
+      // adapters use when their registration-captured facts change.
+      current.registration.replace([current.providerId])
+    } catch (error) {
+      current.state.displayName = previousName
+      dropWrapper(upstream, current)
+      console.error(`[modlens] vision provider refresh failed (${current.providerId}): ${error}`)
+    }
+  }
+
   if (config.upstream) {
-    registerWrapper(config.upstream, config.providerId || 'deepseek-modlens', 'DeepSeek (modlens vision)')
+    const upstream = config.upstream
+    const providerId = config.providerId || 'deepseek-modlens'
+    // Named after the route it actually wraps. This used to say DeepSeek
+    // whatever `upstream` was, so anyone pointing it at another route got a
+    // model group labelled for a provider they were not using. The refresh
+    // plumbing below could never correct it, because the name it compared
+    // against was a constant.
+    const upstreamName = () => {
+      if (typeof ctx.llm.listProviders !== 'function') return upstream
+      try {
+        const found = ctx.llm.listProviders().find((entry) => entry.id === upstream)
+        return found?.name ?? upstream
+      } catch {
+        return upstream
+      }
+    }
+    let reconciling = false
+    const reconcile = () => {
+      if (reconciling) return
+      reconciling = true
+      try {
+        const current = registrations.get(upstream)
+        const available =
+          typeof ctx.llm.listProviders !== 'function' ||
+          ctx.llm.listProviders().some((info) => (typeof info === 'string' ? info : info?.id) === upstream)
+        if (!current) {
+          registerWrapper(upstream, providerId, `${upstreamName()} (modlens vision)`)
+          return
+        }
+        if (!available) {
+          dropWrapper(upstream, current)
+          return
+        }
+        refreshWrapper(upstream, `${upstreamName()} (modlens vision)`)
+      } finally {
+        reconciling = false
+      }
+    }
+    reconcile()
+    if (typeof ctx.on === 'function') ctx.on('llm/adapters-updated', reconcile)
     return
   }
 
@@ -617,7 +730,6 @@ function registerVisionProvider(ctx, config, ownProviders) {
   // skip it while this one is still probing), and sweeps are serialized on
   // one promise chain so two can never interleave their probes at all.
   const discover = Array.isArray(config.discover) ? new Set(config.discover) : null
-  const wrapped = new Set(['deepseek-modlens'])
   const sweepOnce = async () => {
     try {
       await sweepBody()
@@ -636,10 +748,22 @@ function registerVisionProvider(ctx, config, ownProviders) {
       }
       return
     }
-    for (const info of ctx.llm.listProviders()) {
+    const providers = ctx.llm.listProviders()
+    const available = new Set(providers.map((info) => info?.id).filter(Boolean))
+    for (const [upstream, current] of registrations) {
+      if (available.has(upstream)) continue
+      dropWrapper(upstream, current)
+    }
+    for (const info of providers) {
       const id = info?.id
-      if (!id || wrapped.has(id) || String(id).startsWith('modlens-')) continue
+      if (!id || String(id).startsWith('modlens-')) continue
       if (discover && !discover.has(id)) continue
+      const base = info.name ?? id
+      if (registrations.has(id)) {
+        refreshWrapper(id, `${base} (modlens vision)`)
+        continue
+      }
+      if (wrapped.has(id)) continue
       // Claim before the await: the probe may suspend, and the sweep a
       // registration triggers must not probe the same id concurrently.
       wrapped.add(id)
@@ -658,7 +782,6 @@ function registerVisionProvider(ctx, config, ownProviders) {
         continue
       }
       const providerId = id === 'deepseek-official' ? 'deepseek-modlens' : `modlens-${id}`
-      const base = info.name ?? id
       if (!registerWrapper(id, providerId, `${base} (modlens vision)`)) {
         wrapped.delete(id)
       }
@@ -900,7 +1023,7 @@ async function readImageBlock(ctx, block, signal) {
 
 function run(command, args, signal) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    const child = spawnHidden(command, args, {
       stdio: ['ignore', 'pipe', 'pipe'],
       signal,
       // In the packaged desktop app process.execPath is the Electron binary;
@@ -1226,7 +1349,11 @@ function openConfigFile() {
       : process.platform === 'win32'
         ? ['cmd', ['/c', 'start', '', file]]
         : ['xdg-open', [file]]
-  spawn(command, args, { detached: true, stdio: 'ignore' }).unref()
+  // Hiding applies to the `cmd` that runs `start`, not to the editor it hands
+  // off to: `start` opens the file through its association in a process of its
+  // own. Windows ignores CREATE_NO_WINDOW next to DETACHED_PROCESS, so what
+  // this leaves is SW_HIDE on the middleman.
+  spawnHidden(command, args, { detached: true, stdio: 'ignore' }).unref()
 }
 
 /** localhost, ::1, or anything in 127/8, matching dsh's own /api fence. */

package/dsh/spawnHidden.d.ts

@@ -0,0 +1,13 @@
+import type { ChildProcess, SpawnOptions } from 'child_process';
+
+/**
+ * Starts a child with its console window hidden, whatever the caller asked for
+ * (issue #60). `windowsHide` is accepted and ignored rather than refused: the
+ * plugin is plain JavaScript, so refusing it in the types would stop nothing,
+ * and the wrapper overwrites it either way.
+ */
+export declare function spawnHidden(
+    command: string,
+    args: readonly string[],
+    options: SpawnOptions,
+): ChildProcess;

package/dsh/spawnHidden.js

@@ -0,0 +1,20 @@
+// The only place this plugin starts a child process.
+//
+// The desktop app has no console of its own, so on Windows every child it
+// starts would be given one and shown its window: a black box per read
+// (issue #60). `windowsHide` suppresses that, defaults to false in Node, and is
+// ignored elsewhere.
+//
+// It lives in a file of its own, apart from its callers, so the rule can be
+// checked by looking at which files reach `child_process` at all rather than at
+// what each call passes. A call site cannot forget an option it never writes,
+// and writing the option after the caller's leaves nothing to override it.
+//
+// The core has its own copy in src/util/spawnHidden.ts. The duplication is on
+// purpose: this plugin ships as a unit and must not import from the CLI it
+// drives.
+import { spawn } from 'node:child_process'
+
+export function spawnHidden(command, args, options) {
+  return spawn(command, args, { ...options, windowsHide: true })
+}

package/package.json

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

package/skills/modlens/SKILL.md

@@ -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.18.2):
+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.18.4):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.18.2: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.18.2 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.18.2 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.18.4: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.18.4 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.18.4 <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/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.18.2
+- Pinned CLI version: 3.18.4
 - 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.18.2'
+$Pinned = '3.18.4'
 # -------------------------------------------------------------------------------
 
 $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.18.2"
+PINNED="3.18.4"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"