@liustack/modlens 3.18.6 → 3.19.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 3.19.0 - 2026-08-18
+
+An adversarial review swept everything written since 3.17.0, three reviewers by area plus release-artifact checks. One crash, a config trap, and a set of lifecycle and Windows-lookup defects came out of it, all fixed here with tests that failed before the fix. One behaviour change is deliberate and marked breaking below.
+
+- **openai: a `finish_reason: null` no longer crashes the diagnosis it was part of.** null is the streaming-chunk spelling of the field, and compat gateways that reuse one response model send it in non-streaming answers too. It fell past the length and stop checks into the quoted-reason branch, where redaction called `.split` on it, so both unusable-output paths surfaced a TypeError in place of the advice they exist to give. Anything that is not a string now reads as the field being absent. The non-JSON branch had carried this since 3.17.1.
+- **config: `config set` folds and validates the provider name.** `config set OpenAI.apiKey` was saved verbatim, reported as saved, and never read, since reads look sections up by exact lowercase key; the environment quietly kept answering for the provider the user thought they had just configured, and the effective view showed two rows for one provider. The name is now folded the way `-p` folds it, aliases stay the storage key they always were, and a name no provider answers to is refused with the valid ones listed.
+- **analyzer: an isolation that fails to set up removes its directory.** A copy failure between creating the throwaway workdir and returning it leaked one directory per failover attempt, since the run's cleanup only knows directories that were returned.
+- **dsh: the pinned-upstream lifecycle gains the protections the discovery sweep already had.** A duplicate registration retried and logged on every topology event instead of being remembered as another holder's claim, and is now retried only once their route disappears. The wrapper's own drop emits a topology event mid-reconcile, which the re-entrancy guard used to swallow, so an upstream that unmounted and remounted in one breath stayed unregistered until an unrelated event; the guard now queues a rerun. A refresh whose replace throws after the host already committed kept disposing a healthy registration; the catch now asks the registry which side of the commit the failure landed on. And the sweep's availability set reads bare-string provider listings the way the pinned path always did.
+- **Windows: the bare-node lookup is as picky as cmd, and shim-supplied targets stay on this machine.** A directory that happened to carry the name counted as the found executable, so spawn was handed a directory while cmd skipped it and ran the node one entry later. Quoted PATH entries were probed with their quotes on, which deleted them from the search: a different node ran, silently, or the shim was declined where cmd works. Both now read the way the Windows search reads them. A shim whose text supplies a plain-absolute target may no longer name UNC or device paths, and an execution line glued to `%*` is declined, since cmd concatenates there and a split argv would not be that spawn.
+- **dsh (BREAKING): a pinned upstream's default provider id now encodes the upstream, `modlens-<upstream>`.** The flat default, `deepseek-modlens` whatever the upstream, was also the id auto-discovery mints for `deepseek-official`, so history recorded under a pinned foreign upstream was indistinguishable from DeepSeek history, and a later switch to auto-discovery could hand that route's private replay state to the DeepSeek adapter, the exact transfer the 3.17.2 boundary exists to prevent. It also meant pinned foreign setups never got that boundary's relabelling at all, so their reasoning continuity was silently dropped every turn. A pinned `deepseek-official` keeps its name, and an explicit `providerId` is honoured as before. If a session or default-model setting on a pinned foreign setup named `deepseek-modlens`, reselect the model once; those routes gain the reasoning continuity they were losing.
+
+Known and recorded rather than fixed here: default-configuration pnpm shims carry a NODE_PATH preamble the recogniser does not know yet, so they still land on the spawn error 3.18.0 removed for npm; recognition for that template is the next piece of work.
+
 ## 3.18.6 - 2026-08-18
 
 - **dsh: startup no longer logs a scary failure while waiting for a late upstream ([#66](https://github.com/liustack/modlens/issues/66)).** A pinned upstream that mounts after this plugin is ordinary startup order: llm-pi-ai, for one, mounts its providers once settings load. But the wrapper registered against the absence anyway, and that attempt cannot succeed, because dsh snapshots the retry policy synchronously during registration and the upstream lookup throws `NO_ADAPTER`. Every reconcile before the mount burned one doomed attempt and logged `vision provider registration skipped ... LlmError`, which reads fatal while the next topology event quietly healed it, so the plugin looked broken in exactly the logs people check when it matters. The reconcile now waits: nothing is attempted until the upstream is actually mounted, the first real registration snapshots the upstream's own retry policy rather than burning a placeholder round, and while waiting a single calm line names the upstream being waited on, so a mistyped upstream that never arrives still leaves a breadcrumb saying exactly what was expected. Thanks to @abyss-stars, whose report named the race, the synchronous snapshot inside registration, and the self-heal, and drew the boundary against #57 and #29 before anyone had to ask.

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.6`, 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.19.0`, 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.6`，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.19.0`，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.6
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.19.0
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。

package/dist/main.js

@@ -1432,6 +1432,9 @@ function requestShapeAdvice(settings) {
   }
   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 stringOrAbsent(value) {
+  return typeof value === "string" ? value : void 0;
+}
 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}'.`;
@@ -1511,7 +1514,7 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
   const rawResult = extractJson(text);
   if (rawResult === null) {
     const advice = unusableOutputAdvice(
-      payload.choices?.[0]?.finish_reason,
+      stringOrAbsent(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."
@@ -1524,7 +1527,7 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
   const missing = missingSchemaFields(result);
   if (missing.length > 0) {
     const advice = unusableOutputAdvice(
-      payload.choices?.[0]?.finish_reason,
+      stringOrAbsent(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."
@@ -1715,8 +1718,18 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
         `Invalid config key: ${dottedKey}. Use "provider", "proxy", "reuse.<claude|codex|opencode|pi|grok>", "guards.<denyModels|allowModels|denyWhenUnknown>", or "<provider>.<apiKey|baseUrl|model|proxy|extraBody|structuredOutput>".`
       );
     }
-    const providerName = dottedKey.slice(0, dot);
+    const typedName = dottedKey.slice(0, dot);
     const field = dottedKey.slice(dot + 1);
+    const providerName = typedName.trim().toLowerCase();
+    try {
+      resolveProvider(providerName);
+    } catch {
+      throw new Error(
+        `Unknown provider: ${typedName}. Use one of ${listProviders().join(", ")} (aliases like ${Object.keys(
+          providerAliases()
+        ).filter((alias) => providerAliases()[alias] !== alias).slice(0, 4).join(", ")} work too).`
+      );
+    }
     if (field === "structuredOutput") {
       if ((providerAliases()[providerName] ?? providerName) !== "openai") {
         throw new Error(
@@ -2057,12 +2070,30 @@ function execFileSyncHidden(file, args, options) {
 }
 function existenceOf(target) {
   try {
-    fs.statSync(target);
-    return "present";
+    return fs.statSync(target).isDirectory() ? "directory" : "present";
   } catch (error) {
     return error.code === "ENOENT" ? "absent" : "unknown";
   }
 }
+function splitWindowsPath(pathValue) {
+  const entries = [];
+  let current = "";
+  let inQuotes = false;
+  for (const char of pathValue) {
+    if (char === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (char === ";" && !inQuotes) {
+      if (current) entries.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) entries.push(current);
+  return entries;
+}
 const REAL_DEPS = {
   platform: process.platform,
   readFileSync: (p) => fs.readFileSync(p, "utf-8"),
@@ -2092,7 +2123,7 @@ function resolveLikeCmd(name, env, cwd, deps) {
   const effectiveCwd = cwd ?? process.cwd();
   const dirs = [
     ...skipCwd ? [] : [effectiveCwd],
-    ...pathValue.split(";").filter(Boolean).map((dir) => path.win32.resolve(effectiveCwd, dir))
+    ...splitWindowsPath(pathValue).map((dir) => path.win32.resolve(effectiveCwd, dir))
   ];
   for (const dir of dirs) {
     for (const suffix of [...exts, ""]) {
@@ -2111,7 +2142,7 @@ function resolveLikeCmd(name, env, cwd, deps) {
 function templatePath(text, shimDir) {
   const rooted = /^%(?:dp0%|~dp0)\\?(.*)$/i.exec(text);
   if (!rooted) {
-    return path.win32.isAbsolute(text) && !text.includes("%") ? text : null;
+    return isFullyQualifiedLocalPath(text) && !text.includes("%") ? text : null;
   }
   const rest = rooted[1];
   if (rest.includes("%") || rest === "") {
@@ -2145,7 +2176,7 @@ function nodeRecipe(shimDir, tail2, effective, env, cwd, deps) {
   if (found === "unknown") {
     return null;
   }
-  if (found === "present") {
+  if (found === "present" || found === "directory") {
     return {
       command: local,
       args: tail2,
@@ -2170,13 +2201,13 @@ const NPM_PROLOGUE = [
   "CALL :find_dp0"
 ];
 const NPM_PREFIX = "endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & ";
-const NPM_EXEC_LEGACY = /^"%_prog%"(.*)%\*$/;
-const NPM_EXEC_CURRENT = /^set PATHEXT=%PATHEXT:;\.([A-Z]+);=;% & "%_prog%"(.*)%\*$/;
+const NPM_EXEC_LEGACY = /^"%_prog%"(.*)\s%\*$/;
+const NPM_EXEC_CURRENT = /^set PATHEXT=%PATHEXT:;\.([A-Z]+);=;% & "%_prog%"(.*)\s%\*$/;
 const NPM_NATIVE_EXEC = /^"([^"]*)"\s+%\*$/;
 const PNPM_IF = /^@IF EXIST "([^"]*)" \($/;
-const PNPM_ARM = /^"([^"]*)"(.*)%\*$/;
-const PNPM_BARE_ARM = /^node(.*)%\*$/;
-const PNPM_ONELINE = /^@"([^"]*)"(.*)%\*$/;
+const PNPM_ARM = /^"([^"]*)"(.*)\s%\*$/;
+const PNPM_BARE_ARM = /^node(.*)\s%\*$/;
+const PNPM_ONELINE = /^@"([^"]*)"(.*)\s%\*$/;
 function normalizeLines(content) {
   const lines = content.split(/\r?\n/).map((line) => line.trim());
   while (lines.length > 0 && lines[lines.length - 1] === "") {
@@ -3204,7 +3235,7 @@ async function runProvider(provider, model, options, resolvedInput, timeoutMs, c
   } else if (provider.buildInvocation && provider.parseOutput) {
     const buildInvocation = provider.buildInvocation;
     const parseOutput = provider.parseOutput;
-    const isolation = !options.workdir && provider.isolateWorkdir ? resolvedInput.kind === "local" ? isolateImage(resolvedInput.source) : emptyWorkdir() : null;
+    const isolation = !options.workdir && provider.isolateWorkdir ? resolvedInput.kind === "local" ? await isolateImage(resolvedInput.source) : emptyWorkdir() : null;
     try {
       const invocation = buildInvocation({
         ...providerOptions,
@@ -3272,16 +3303,21 @@ async function removeWorkdir(workdir) {
   } catch {
   }
 }
-function isolateImage(source) {
+async function isolateImage(source) {
   const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "modlens-work-"));
-  const imageSource = path.join(workdir, path.basename(source));
-  fs.copyFileSync(source, imageSource);
-  fs.chmodSync(imageSource, 384);
-  return {
-    imageSource,
-    workdir,
-    cleanup: () => removeWorkdir(workdir)
-  };
+  try {
+    const imageSource = path.join(workdir, path.basename(source));
+    fs.copyFileSync(source, imageSource);
+    fs.chmodSync(imageSource, 384);
+    return {
+      imageSource,
+      workdir,
+      cleanup: () => removeWorkdir(workdir)
+    };
+  } catch (error) {
+    await removeWorkdir(workdir);
+    throw error;
+  }
 }
 function emptyWorkdir() {
   const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "modlens-work-"));
@@ -4598,7 +4634,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.6");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.19.0");
 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"}}'`
@@ -4708,7 +4744,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.6"
+      version: "3.19.0"
     });
     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.6
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.19.0
 ```
 
 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.6
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.19.0
 ```
 
 `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.6
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.19.0
 ```
 
 这会注册一个 `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.6
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.19.0
 ```
 
 `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.6
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.19.0
 ```
 
 `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.6'
+  - '@liustack/modlens@3.19.0'
 ```
 
 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.6
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.19.0
 ```
 
 `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.6
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.18.6'
+  - '@liustack/modlens@3.19.0'
 ```
 
 或者只为这一条命令解除冷静期，注意它解除的是这条命令解析到的所有包，不只 modlens：

package/dsh/index.js

@@ -674,11 +674,25 @@ function registerVisionProvider(ctx, config, ownProviders) {
     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.
+  // Whether our synthetic route is currently in the registry, spelled the
+  // way reconcile spells its availability check. Used where an operation
+  // failed and what to do next depends on whether it failed before or after
+  // the host committed.
+  const routed = (providerId) => {
+    if (typeof ctx.llm.listProviders !== 'function') return false
+    try {
+      return ctx.llm.listProviders().some((info) => (typeof info === 'string' ? info : info?.id) === providerId)
+    } catch {
+      return false
+    }
+  }
+
+  // commitRoutes mutates the registry and only then emits, so a listener
+  // throwing during that emit means the replace already SUCCEEDED, and
+  // treating the throw as failure would drop a healthy registration. dsh
+  // even ships such a listener (its llm invariant re-reads every policy on
+  // each update and fails loud), so the catch below asks the registry which
+  // side of the commit the failure landed on before deciding.
   const refreshWrapper = (upstream, displayName) => {
     const current = registrations.get(upstream)
     if (!current || typeof current.registration?.replace !== 'function') return
@@ -700,6 +714,15 @@ function registerVisionProvider(ctx, config, ownProviders) {
       current.registration.replace([current.providerId])
     } catch (error) {
       current.state.displayName = previousName
+      if (routed(current.providerId)) {
+        // The route survived, so the throw came from after the commit (a
+        // listener), or the host kept the old snapshot. Either converges on
+        // the next refresh; disposing would not.
+        console.error(
+          `[modlens] vision provider refresh failed (${current.providerId}), keeping the existing registration: ${error}`,
+        )
+        return
+      }
       dropWrapper(upstream, current)
       console.error(`[modlens] vision provider refresh failed (${current.providerId}): ${error}`)
     }
@@ -707,7 +730,17 @@ function registerVisionProvider(ctx, config, ownProviders) {
 
   if (config.upstream) {
     const upstream = config.upstream
-    const providerId = config.providerId || 'deepseek-modlens'
+    // The default id encodes its upstream, the same minting rule the sweep
+    // uses, because #49's relabelling trusts only ids that prove their
+    // upstream. The old flat default, deepseek-modlens for every pinned
+    // upstream, was also the id auto-discovery mints for deepseek-official,
+    // so history recorded under a pinned foreign upstream became
+    // indistinguishable from DeepSeek history, and switching to
+    // auto-discovery could hand that foreign replay state to the DeepSeek
+    // adapter. An explicit config.providerId is honoured as before, and a
+    // pinned deepseek-official keeps the name existing setups know.
+    const providerId =
+      config.providerId || (upstream === 'deepseek-official' ? 'deepseek-modlens' : `modlens-${upstream}`)
     // 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
@@ -723,9 +756,21 @@ function registerVisionProvider(ctx, config, ownProviders) {
       }
     }
     let reconciling = false
+    let rerunQueued = false
     let waitingLogged = false
+    // The id is held by someone else (a second modlens install, most
+    // likely). Their registration answers the routing, so retrying ours on
+    // every topology event would only repeat the same log line; the claim is
+    // re-examined when the holder's route disappears.
+    let claimedElsewhere = false
     const reconcile = () => {
-      if (reconciling) return
+      if (reconciling) {
+        // dropWrapper's disposer makes the host emit adapters-updated while
+        // this very run is on the stack, and whatever that event announced
+        // (a quick remount, say) must not wait for an unrelated next event.
+        rerunQueued = true
+        return
+      }
       reconciling = true
       try {
         const current = registrations.get(upstream)
@@ -733,6 +778,11 @@ function registerVisionProvider(ctx, config, ownProviders) {
           typeof ctx.llm.listProviders !== 'function' ||
           ctx.llm.listProviders().some((info) => (typeof info === 'string' ? info : info?.id) === upstream)
         if (!current) {
+          if (claimedElsewhere) {
+            if (routed(providerId)) return
+            // The holder released the id: it is ours to try again.
+            claimedElsewhere = false
+          }
           if (!available) {
             // A pinned upstream that mounts after this plugin is ordinary
             // startup order (llm-pi-ai mounts its providers once settings
@@ -751,7 +801,11 @@ function registerVisionProvider(ctx, config, ownProviders) {
             return
           }
           waitingLogged = false
-          registerWrapper(upstream, providerId, `${upstreamName()} (modlens vision)`)
+          if (registerWrapper(upstream, providerId, `${upstreamName()} (modlens vision)`)) {
+            // True with nothing recorded is the duplicate branch: another
+            // holder already answers for this id.
+            claimedElsewhere = !registrations.has(upstream)
+          }
           return
         }
         if (!available) {
@@ -761,6 +815,10 @@ function registerVisionProvider(ctx, config, ownProviders) {
         refreshWrapper(upstream, `${upstreamName()} (modlens vision)`)
       } finally {
         reconciling = false
+        if (rerunQueued) {
+          rerunQueued = false
+          reconcile()
+        }
       }
     }
     reconcile()
@@ -795,16 +853,18 @@ function registerVisionProvider(ctx, config, ownProviders) {
       return
     }
     const providers = ctx.llm.listProviders()
-    const available = new Set(providers.map((info) => info?.id).filter(Boolean))
+    // Same tolerance as the pinned path: an entry may be a bare id string.
+    const idOf = (info) => (typeof info === 'string' ? info : info?.id)
+    const available = new Set(providers.map(idOf).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
+      const id = idOf(info)
       if (!id || String(id).startsWith('modlens-')) continue
       if (discover && !discover.has(id)) continue
-      const base = info.name ?? id
+      const base = (typeof info === 'string' ? undefined : info.name) ?? id
       if (registrations.has(id)) {
         refreshWrapper(id, `${base} (modlens vision)`)
         continue

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.18.6",
+    "version": "3.19.0",
     "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.6):
+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.19.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.18.6: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.18.6 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.18.6 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.19.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.19.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.19.0 <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.6
+- Pinned CLI version: 3.19.0
 - 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.6'
+$Pinned = '3.19.0'
 # -------------------------------------------------------------------------------
 
 $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.6"
+PINNED="3.19.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"