@liustack/modlens 3.23.1 → 3.24.1

package/docs/cli.md

@@ -98,6 +98,7 @@ Six providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `o
 Other subcommands:
 
 - `modlens guard [--model <id>]`: should the engine run for the active model at all? Exit 0 allow, 1 deny, verdict as JSON.
-- `modlens config <init|set|show>`: `set` with the value omitted on an `apiKey` field prompts for it with the echo hidden, so the key never enters argv, shell history, or the conversation with an agent driving the terminal. It also accepts one piped line (`pbpaste | modlens config set openai.apiKey`), which keeps the key out of argv, though whatever produced that pipe is still your own command to keep out of history. Keys are `provider`, `proxy` (HTTP/HTTPS proxy for the API providers, `HTTPS_PROXY`/`HTTP_PROXY` also honored), `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`, plus `openai.structuredOutput` (that route only).
-- `modlens doctor`: Node and node:sqlite, provider readiness, the failover chains for this machine, the detected harness, the guard's rules with a live verdict, and the Reuse section with per-harness grant decisions and discovered vision. Spends no quota; `--json` for a machine-readable report.
+- `modlens config <init|set|show>`: `set` with the value omitted on an `apiKey` field prompts for it with the echo hidden, so the key never enters argv, shell history, or the conversation with an agent driving the terminal. It also accepts one piped line (`pbpaste | modlens config set openai.apiKey`), which keeps the key out of argv, though whatever produced that pipe is still your own command to keep out of history. Keys are `provider`, `proxy` (HTTP/HTTPS proxy for the API providers, `HTTPS_PROXY`/`HTTP_PROXY` also honored), `cooldown` (`on` or `off`, on by default), `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`, plus `openai.structuredOutput` (that route only). `apiKey` accepts a comma-separated list and rotates after authentication, rate-limit, or quota failures.
+- `modlens state clear`: forget every provider cooldown in `~/.modlens/state.json`, so all providers are tried at full priority again.
+- `modlens doctor`: Node and node:sqlite, provider readiness (including API key counts), the failover chains for this machine, the cooldown switch and any cooling keys, the detected harness, the guard's rules with a live verdict, and the Reuse section with per-harness grant decisions and discovered vision. Spends no quota; `--json` for a machine-readable report.
 

package/docs/cli.zh-CN.md

@@ -95,5 +95,6 @@ modlens recover-paste                           # pull a pasted image into a fil
 其他子命令：
 
 - `modlens guard [--model <id>]`：判断当前激活的模型到底该不该运行引擎。退出码 0 表示放行，1 表示拒绝，判定结果以 JSON 输出。
-- `modlens config <init|set|show>`：`set` 在 `apiKey` 字段上省略值会进入不回显的输入提示，密钥不进 argv、不进 shell 历史，也不进你与终端里那个 agent 的对话。它也接受从管道读一行（`pbpaste | modlens config set openai.apiKey`），这样密钥不进 argv，但产生这条管道的命令本身是否留在历史里，由你自己决定。可用的键有 `provider`、`proxy`（API provider 的 HTTP/HTTPS 代理，也认 `HTTPS_PROXY`/`HTTP_PROXY`）、`reuse.<claude|codex|opencode|pi|grok>`、`guards.<denyModels|allowModels|denyWhenUnknown>`，以及 `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`，另有 `openai.structuredOutput`（仅这条路线用得上）。
-- `modlens doctor`：报告 Node 与 node:sqlite、各 provider 的就绪状态、本机的故障转移链、检测到的 harness、guard 规则和一次现场判定，以及 Reuse 一节里按 harness 的授权决定与发现的视觉能力。不花任何额度，`--json` 输出机器可读报告。
+- `modlens config <init|set|show>`：`set` 在 `apiKey` 字段上省略值会进入不回显的输入提示，密钥不进 argv、不进 shell 历史，也不进你与终端里那个 agent 的对话。它也接受从管道读一行（`pbpaste | modlens config set openai.apiKey`），这样密钥不进 argv，但产生这条管道的命令本身是否留在历史里，由你自己决定。可用的键有 `provider`、`proxy`（API provider 的 HTTP/HTTPS 代理，也认 `HTTPS_PROXY`/`HTTP_PROXY`）、`cooldown`（`on` 或 `off`，默认打开）、`reuse.<claude|codex|opencode|pi|grok>`、`guards.<denyModels|allowModels|denyWhenUnknown>`，以及 `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`，另有 `openai.structuredOutput`（仅这条路线用得上）。`apiKey` 接受英文逗号分隔的列表，鉴权、限流或配额失败后会轮换。
+- `modlens state clear`：忘掉 `~/.modlens/state.json` 里每一条 provider 冷却，让所有 provider 重新按完整优先级尝试。
+- `modlens doctor`：报告 Node 与 node:sqlite、各 provider 的就绪状态（含密钥数量）、本机的故障转移链、冷却开关和正在冷却的密钥、检测到的 harness、guard 规则和一次现场判定，以及 Reuse 一节里按 harness 的授权决定与发现的视觉能力。不花任何额度，`--json` 输出机器可读报告。

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.23.1
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.1
 ```
 
 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.
@@ -87,7 +87,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.23.1
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.1
 ```
 
 `npm view @liustack/modlens version` prints the current one, and this page is
@@ -137,6 +137,28 @@ becomes a file path and the session never holds an attachment, so nothing locks
 the model selector. It only comes up after a paste on a variant or on a vision
 model, where an attachment is the point.
 
+### For other plugin authors: injecting images on a `(modlens vision)` route
+
+A wrapper route's declared `inputModalities: ['text', 'image']` is a promise,
+not decoration ([#74](https://github.com/liustack/modlens/issues/74)). Every
+`image` block in the request — pasted by the user or injected by another
+plugin, including blocks nested in tool results — is converted to structured
+evidence text at request time, before the wire reaches the text-only upstream.
+Nothing is silently dropped, so the branch "declared image → inject a native
+image block, otherwise inject a file path" works unchanged whether the
+declaring route is a real vision model or a modlens wrapper.
+
+One requirement: the block must carry a host attachment reference, the shape
+`ctx.attachments.saveImage` returns and a Web UI paste produces — the plugin
+reads bytes through `ctx.attachments.readImage(block.attachment)`. A
+hand-built block holding only a path or base64 payload degrades to a constant
+read-failure placeholder. And do not add a file-path text next to an image
+block on an image-declaring route: the block already becomes complete
+evidence there, and the extra path invites a second read of the same image
+through the tool — double quota, and a second wording of the same content,
+which is exactly the prefix-cache churn
+[#68](https://github.com/liustack/modlens/issues/68) removed.
+
 ### Paste-to-path (web profile)
 
 Pasting an image into the dsh Web UI under a **text-only model** used to die at

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.23.1
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.1
 ```
 
 这会注册一个 `modlens_read_image` 工具，它的 schema 随每次请求抵达模型（不靠触发启发式），运行同一个包里自带的 modlens CLI，并把结构化证据作为工具的标准 JSON 输出返回。引擎、复用授权和 guard 规则仍在 `~/.modlens/config.json` 里，与其他所有 harness 共享。dsh 还在开发者预览阶段，插件接口可能变化。这个插件刻意保持很小的接触面（原生工具注册、视觉变体所用的 llm 适配层、附件读取器，以及一个 agent 执行前钩子），其中任何一处变动，它都会大声报错而不是无声退化。
@@ -73,7 +73,7 @@ dsh 的网页用户面前没有终端，所以引擎设置有一张卡片，在*
 modlens 发布很频繁，而两种安装形态都会冻结在装进来的那个版本上。dsh 上重跑一遍安装即可，版本号要点名：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.23.1
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.1
 ```
 
 `npm view @liustack/modlens version` 可以查到当前版本号，本页的版本号则由发布流程自动写入。
@@ -96,6 +96,12 @@ skill 类 harness 上，skill 是一个拷贝出来的文件夹，拷贝会保
 
 走上面第一条粘贴路线就不会遇到:图片变成文件路径,会话里从不存在附件,模型选择器也就不会被锁住。只有在变体或视觉模型上粘贴时才会产生附件,而那种场景下附件本来就是目的。
 
+### 给其他插件作者：向 `(modlens vision)` 路由注入图片
+
+包装路由声明的 `inputModalities: ['text', 'image']` 是承诺，不是装饰（[#74](https://github.com/liustack/modlens/issues/74)）。请求里的每一个 `image` 块，无论来自用户粘贴还是其他插件注入（包括嵌在 tool result 里的），都会在请求时转成结构化证据文本，再发往 text-only 上游。没有任何内容被静默丢弃，所以「声明 image 就注入原生图片块，否则注入文件路径」这条分支不用区分对面是真视觉模型还是 modlens 包装。
+
+唯一前提：块必须带宿主附件引用，即 `ctx.attachments.saveImage` 返回、Web UI 粘贴产生的那种形状，插件靠 `ctx.attachments.readImage(block.attachment)` 取字节。手搓的只含路径或 base64 的块会落进固定的读取失败占位。另外不要在声明 image 的路由上给图片块旁边再附路径文本：块在这里已经变成完整证据，多出的路径会诱导模型用工具把同一张图再读一遍，双倍配额，还产生同一内容的第二种措辞，正是 [#68](https://github.com/liustack/modlens/issues/68) 清除过的前缀缓存抖动。
+
 ### 粘贴转路径（paste-to-path，web profile）
 
 过去在 dsh Web UI 里，**纯文本模型**下粘贴图片会死在图片准入检查这一步。插件现在带了一个浏览器端半边（由 dsh 的客户端插件系统自动加载），恰好在这种情况下接管粘贴：图片字节发到插件在 dsh web 服务器上的 `/modlens/paste` 路由（仅回环地址，校验 magic byte，上限 25 MB），落成一个私有临时文件，输入框收到的则是纯文本的文件路径。这与 Pi、OpenCode、Claude Code 递给模型的形态一致，也正是 modlens skill 和 `modlens_read_image` 工具的首要触发条件。消息里不带图片附件，准入检查根本不会触发。

package/docs/security.md

@@ -38,6 +38,10 @@ So the private-address guards, the magic-byte check, and the size cap protect ex
 
 Text inside an image is untrusted, the same as a web page. A screenshot can contain instructions aimed at whatever reads it. The prompt says so explicitly, but that is mitigation, not a guarantee: analyze images you are willing to open, and prefer a sandboxed working directory when they came from elsewhere.
 
+## Credentials in errors
+
+Gateway bodies, subprocess stderr, per-attempt records, warnings, and persisted cooldown reasons all go through redaction before they travel. When a provider has several API keys, every sibling key is registered as a secret, not the joined `'k1,k2'` string as one. Truncation happens after that pass, so a cut cannot hide a key from the exact-match scrub.
+
 ## Evidence, not invention
 
 What the engine cannot read goes into `uncertainty` rather than being filled in. v2 dropped pixel coordinates and confidence scores entirely, because those are the two fields models fabricate most convincingly.

package/docs/security.zh-CN.md

@@ -38,6 +38,10 @@ ModLens 调用 `agy` 时带上 `--dangerously-skip-permissions`，因为某些
 
 图片里的文字是不可信的，和网页一样。一张截图可能带着写给任何读取者的指令。prompt 里明确说了这一点，但那是缓解措施，不是保证：只分析你愿意打开的图片，图片来自别处时优先用沙箱化的工作目录。
 
+## 报错里的凭据
+
+网关响应体、子进程 stderr、每次尝试记录、警告，以及写入冷却状态的原因，都会先脱敏再往外走。一个 provider 配了多把密钥时，每一把都会登记为秘密，而不是把 `'k1,k2'` 整串当成一把。截断发生在脱敏之后，避免切到密钥中间让精确匹配找不到。
+
 ## 证据，而非编造
 
 引擎读不出来的内容会进入 `uncertainty`，而不是被脑补出来。v2 彻底去掉了像素坐标和置信度分数，因为这两个字段正是模型编造得最像真的。

package/docs/troubleshooting.md

@@ -10,7 +10,7 @@ read_when:
 
 English | [中文](troubleshooting.zh-CN.md)
 
-Start with `modlens doctor`: it checks your Node version, which providers are ready, which one will be selected and why, and the detected harness, all without spending quota or making a network request. It catches most setup problems before you read any further.
+Start with `modlens doctor`: it checks your Node version, which providers are ready (including how many API keys each one has), which one will be selected and why, the cooldown switch and any cooling keys, and the detected harness, all without spending quota or making a network request. It catches most setup problems before you read any further. A spent key rotates to the next one, then cools, so the next run tries a healthy key first.
 
 Every message below is one modlens actually prints. Search this file for the words you saw.
 
@@ -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.23.1
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.1
 ```
 
 `npm view @liustack/modlens version` prints the current one. pnpm 11 installs a named
@@ -178,7 +178,7 @@ file:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.23.1'
+  - '@liustack/modlens@3.24.1'
 ```
 
 Or lift the gate for a single command, which lifts it for everything that

package/docs/troubleshooting.zh-CN.md

@@ -10,7 +10,7 @@ read_when:
 
 [English](troubleshooting.md) | 中文
 
-先跑 `modlens doctor`：它会检查你的 Node 版本、哪些 provider 已就绪、将选中哪一个及其原因，以及检测到的 harness，全程不消耗额度，也不发网络请求。大多数配置问题在你继续往下读之前就能被它查出来。
+先跑 `modlens doctor`：它会检查你的 Node 版本、哪些 provider 已就绪（含各家有几把密钥）、将选中哪一个及其原因、冷却开关和正在冷却的密钥，以及检测到的 harness，全程不消耗额度，也不发网络请求。大多数配置问题在你继续往下读之前就能被它查出来。一把密钥用尽会先轮换到下一把，再进入冷却，下次运行会优先试还健康的密钥。
 
 下面每条消息都是 modlens 实际会打印的。拿你看到的字眼在本文里搜索即可。
 
@@ -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.23.1
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.1
 ```
 
 `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.23.1
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.23.1'
+  - '@liustack/modlens@3.24.1'
 ```
 
 或者只为这一条命令解除冷静期，注意它解除的是这条命令解析到的所有包，不只 modlens：

package/dsh/client.js

@@ -192,6 +192,8 @@ window.__ModuleLoader__.load({
         pickToConfigure: 'Pick an engine above to configure its key and endpoint.',
         engine: 'Engine',
         apiKey: 'API key',
+        apiKeyHint:
+          'Separate multiple keys with commas. ModLens rotates to the next key after authentication, rate-limit, or quota failures.',
         baseUrl: 'Base URL',
         model: 'Model',
         stored: 'stored, leave empty to keep it',
@@ -219,6 +221,7 @@ window.__ModuleLoader__.load({
         pickToConfigure: '在上面选一个引擎，才能配置它的密钥和地址。',
         engine: '引擎',
         apiKey: 'API 密钥',
+        apiKeyHint: '多个密钥用英文逗号分隔。鉴权、限流或配额失败时会自动轮换到下一个密钥。',
         baseUrl: '接口地址',
         model: '模型',
         stored: '已保存，留空即不改动',
@@ -644,6 +647,22 @@ window.__ModuleLoader__.load({
                       'clinote',
                     )
                   : secretField(t.apiKey, 'apiKey', current.hasKey ? t.stored : t.unset),
+              draft.provider === '' || keyless
+                ? null
+                : fieldRow(
+                    '',
+                    h(
+                      'div',
+                      {
+                        style: {
+                          fontSize: '13px',
+                          color: 'var(--dsw-alias-label-tertiary, rgba(127,127,127,0.8))',
+                        },
+                      },
+                      t.apiKeyHint,
+                    ),
+                    'api-key-rotation',
+                  ),
               draft.provider === '' || keyless ? null : textField(t.baseUrl, 'baseUrl', 'text', t.fallback),
               draft.provider === '' ? null : textField(t.model, 'model', 'text', t.fallback),
               // Where these values are coming from, said once, because the

package/dsh/index.js

@@ -55,7 +55,20 @@ export function apply(ctx, config = {}) {
   // wrappers land, including the later sweeps, and read by the verdict.
   const ownProviders = new Set()
   if (config.visionProvider !== false) {
-    registerVisionProvider(ctx, config, ownProviders, evidenceCache)
+    // Bundle loaders can call apply while this outer context is still waiting
+    // for its required services. Reading ctx.llm here then throws "inactive
+    // context" before the first discovery sweep can register any lifecycle
+    // work (#79). Put the whole provider registry inside an injected child
+    // scope: Cordis starts it only while llm is active, and tears its listeners
+    // and registrations down with that service. Preview hosts without inject
+    // keep the dependency-free plugin's former feature-detected path.
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['llm'], (scope) => {
+        return registerVisionProvider(scope, config, ownProviders, evidenceCache)
+      })
+    } else {
+      registerVisionProvider(ctx, config, ownProviders, evidenceCache)
+    }
   }
   // Paste-to-path: the browser half (dsh/client.js) intercepts image pastes
   // and POSTs the bytes here; the file lands in a private temp dir and the
@@ -569,10 +582,50 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
     if (Array.isArray(info?.inputModalities) && info.inputModalities.includes('image')) return false
     return true
   }
-  if (typeof ctx.llm?.registerAdapter !== 'function' || typeof ctx.llm?.stream !== 'function') {
+  // Keep this activation bound to the exact service implementation that made
+  // it runnable. Cordis reuses the child context when llm is replaced, so
+  // looking the service up again after an await could otherwise move an old
+  // topology result into the new registry.
+  const llm = ctx.llm
+  if (typeof llm?.registerAdapter !== 'function' || typeof llm?.stream !== 'function') {
     return
   }
 
+  // Discovery promises are ordinary JavaScript work, not Cordis effects.
+  // The disposer invalidates this activation before the injected child is
+  // re-run, and clears the ownership facts whose actual adapter effects the
+  // framework tears down independently.
+  let active = true
+  const claimedProviders = new Set()
+  const deactivate = () => {
+    active = false
+    for (const providerId of claimedProviders) ownProviders?.delete(providerId)
+    claimedProviders.clear()
+  }
+  // Cordis marks a fiber UNLOADING before it runs activation disposers. A
+  // promise continuation already in the microtask queue can therefore see
+  // `active` before the disposer flips it. Creating and immediately releasing
+  // a zero-work effect is the framework's atomic liveness boundary: once it
+  // succeeds, the following synchronous registry mutation cannot race an
+  // unload. A lifecycle refusal cancels this activation without turning an
+  // expected teardown into a terminal diagnostic.
+  const activationCanCommit = () => {
+    if (!active) return false
+    if (typeof ctx.effect !== 'function') return true
+    try {
+      const release = ctx.effect(() => {})
+      if (typeof release === 'function') release()
+      return active
+    } catch (error) {
+      const inactive =
+        error?.code === 'INACTIVE_EFFECT' ||
+        /cannot create effect on inactive context/i.test(String(error?.message ?? error))
+      if (!inactive) throw error
+      deactivate()
+      return false
+    }
+  }
+
   // 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
@@ -582,6 +635,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
   const policyKey = (policy) => (policy === undefined ? undefined : JSON.stringify(policy))
 
   const registerWrapper = (upstream, providerId, displayName) => {
+    if (!activationCanCommit()) return false
     const state = { displayName, retryPolicyKey: undefined }
     const withVision = (info) => {
       const inputModalities = Array.isArray(info?.inputModalities) ? [...info.inputModalities] : []
@@ -590,7 +644,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       return { ...info, provider: providerId, inputModalities }
     }
     try {
-      const registration = ctx.llm.registerAdapter([providerId], {
+      const registration = 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
@@ -608,20 +662,20 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
           // and the registration boundary below fails closed instead; the
           // ordinary not-mounted-yet case never reaches this method, because
           // reconcile waits for the upstream before registering (#66).
-          if (typeof ctx.llm.providerRetryPolicy !== 'function') return undefined
-          const policy = ctx.llm.providerRetryPolicy(upstream)
+          if (typeof llm.providerRetryPolicy !== 'function') return undefined
+          const policy = llm.providerRetryPolicy(upstream)
           state.retryPolicyKey = policyKey(policy)
           return policy
         },
         async listModels(_provider, signal) {
-          const models = await ctx.llm.listModels(upstream, signal)
+          const models = await 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)
+          const info = await llm.resolveModelInfo(upstream, model, signal)
           if (!shouldWrap(info)) {
             // Refusing is right: wrapping a model that reads images itself
             // would claim a bridge it does not need, hand it text evidence
@@ -662,7 +716,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
           return (async function* () {
             const converted = await convertImagesToEvidence(ctx, options.messages, options.signal, self)
             const messages = restoreUpstreamSource(converted, providerId, upstream)
-            yield* ctx.llm.stream({ ...options, provider: upstream, messages })
+            yield* llm.stream({ ...options, provider: upstream, messages })
           })()
         },
         evidenceCache,
@@ -672,6 +726,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       // 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
       // taken over, which is the bug the verdict exists to prevent.
+      claimedProviders.add(providerId)
       ownProviders?.add(providerId)
       return true
     } catch (error) {
@@ -695,6 +750,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
   const dropWrapper = (upstream, current) => {
     registrations.delete(upstream)
     wrapped.delete(upstream)
+    claimedProviders.delete(current.providerId)
     ownProviders?.delete(current.providerId)
     if (typeof current.registration === 'function') current.registration()
   }
@@ -704,9 +760,9 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
   // 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
+    if (typeof llm.listProviders !== 'function') return false
     try {
-      return ctx.llm.listProviders().some((info) => (typeof info === 'string' ? info : info?.id) === providerId)
+      return llm.listProviders().some((info) => (typeof info === 'string' ? info : info?.id) === providerId)
     } catch {
       return false
     }
@@ -724,7 +780,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
     let nextPolicyKey
     try {
       nextPolicyKey =
-        typeof ctx.llm.providerRetryPolicy === 'function' ? policyKey(ctx.llm.providerRetryPolicy(upstream)) : undefined
+        typeof llm.providerRetryPolicy === 'function' ? policyKey(llm.providerRetryPolicy(upstream)) : undefined
     } catch (error) {
       dropWrapper(upstream, current)
       console.error(`[modlens] vision provider refresh removed (${current.providerId}): ${error}`)
@@ -772,9 +828,9 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
     // 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
+      if (typeof llm.listProviders !== 'function') return upstream
       try {
-        const found = ctx.llm.listProviders().find((entry) => entry.id === upstream)
+        const found = llm.listProviders().find((entry) => entry.id === upstream)
         return found?.name ?? upstream
       } catch {
         return upstream
@@ -789,6 +845,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
     // re-examined when the holder's route disappears.
     let claimedElsewhere = false
     const reconcile = () => {
+      if (!activationCanCommit()) 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
@@ -800,8 +857,8 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       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)
+          typeof llm.listProviders !== 'function' ||
+          llm.listProviders().some((info) => (typeof info === 'string' ? info : info?.id) === upstream)
         if (!current) {
           if (claimedElsewhere) {
             if (routed(providerId)) return
@@ -848,7 +905,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
     }
     reconcile()
     if (typeof ctx.on === 'function') ctx.on('llm/adapters-updated', reconcile)
-    return
+    return deactivate
   }
 
   // Auto-discovery. `wrapped` guards duplicates across sweeps and the
@@ -860,16 +917,19 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
   // one promise chain so two can never interleave their probes at all.
   const discover = Array.isArray(config.discover) ? new Set(config.discover) : null
   const sweepOnce = async () => {
+    if (!activationCanCommit()) return
     try {
       await sweepBody()
     } catch (error) {
+      if (!active) return
       // A sweep failure must never become an unhandled rejection inside the
       // host process; the next topology notification simply tries again.
       console.error(`[modlens] vision provider discovery sweep failed: ${error}`)
     }
   }
   const sweepBody = async () => {
-    if (typeof ctx.llm.listProviders !== 'function') {
+    if (!active) return
+    if (typeof llm.listProviders !== 'function') {
       // Older registry surface: fall back to the single legacy wrap once.
       if (!wrapped.has('__legacy_fallback__')) {
         wrapped.add('__legacy_fallback__')
@@ -877,15 +937,18 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       }
       return
     }
-    const providers = ctx.llm.listProviders()
+    const providers = llm.listProviders()
+    if (!active) return
     // 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 (!active) return
       if (available.has(upstream)) continue
       dropWrapper(upstream, current)
     }
     for (const info of providers) {
+      if (!active) return
       const id = idOf(info)
       if (!id || String(id).startsWith('modlens-')) continue
       if (discover && !discover.has(id)) continue
@@ -900,13 +963,19 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       wrapped.add(id)
       let models = []
       try {
-        models = await ctx.llm.listModels(id)
+        models = await llm.listModels(id)
       } catch {
+        if (!activationCanCommit()) return
         // Unreachable route today; release the claim so a later topology
         // change retries it.
         wrapped.delete(id)
         continue
       }
+      // The promise can settle just before Cordis marks this fiber UNLOADING,
+      // while the activation disposer is still one microtask away. Re-enter
+      // the atomic lifecycle boundary before either continuing to refresh a
+      // later registration or committing this provider's wrapper.
+      if (!activationCanCommit()) return
       if (!models.some(shouldWrap)) {
         // No eligible models yet: release, the route may gain some later.
         wrapped.delete(id)
@@ -931,6 +1000,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       void sweep()
     })
   }
+  return deactivate
 }
 
 // The same pasted attachment rides every later step of its session, and the
@@ -1397,16 +1467,27 @@ const REUSE_HARNESSES = ['claude', 'codex', 'opencode', 'pi', 'grok']
 // one source whole, so the card has to read the same two places a read does or
 // it shows an empty form for an engine that works.
 const ENGINE_ENV_BINDINGS = {
-  'gemini-api': { apiKey: 'GEMINI_API_KEY' },
+  'gemini-api': { apiKey: 'GEMINI_API_KEY', baseUrl: 'GEMINI_BASE_URL' },
   openai: { apiKey: 'OPENAI_API_KEY', baseUrl: 'OPENAI_BASE_URL' },
   anthropic: { apiKey: 'ANTHROPIC_API_KEY', baseUrl: 'ANTHROPIC_BASE_URL' },
 }
 
+/** Whether a comma-separated API-key value contains at least one real key. */
+function hasApiKeys(value) {
+  return (
+    typeof value === 'string' &&
+    value
+      .split(',')
+      .map((key) => key.trim())
+      .some((key) => key !== '')
+  )
+}
+
 function engineEnvSettings(engine, env = process.env) {
   const settings = {}
   for (const [field, variable] of Object.entries(ENGINE_ENV_BINDINGS[engine] ?? {})) {
     const value = typeof env[variable] === 'string' ? env[variable].trim() : ''
-    if (value !== '') settings[field] = value
+    if (value !== '' && (field !== 'apiKey' || hasApiKeys(value))) settings[field] = value
   }
   return settings
 }
@@ -1472,7 +1553,7 @@ function engineSummary(config = readModlensConfig()) {
     engines[name] = {
       baseUrl: typeof settings.baseUrl === 'string' ? settings.baseUrl : '',
       model: typeof settings.model === 'string' ? settings.model : '',
-      hasKey: typeof settings.apiKey === 'string' && settings.apiKey !== '',
+      hasKey: hasApiKeys(settings.apiKey),
       // '' means neither source holds anything, which is not the same as the
       // file holding an empty entry: that one is already off its variables.
       source: inFile ? 'file' : Object.keys(settings).length > 0 ? 'env' : '',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.23.1",
+    "version": "3.24.1",
     "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.23.1):
+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.24.1):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.23.1: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.23.1 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.23.1 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.24.1: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.24.1 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.24.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

@@ -19,11 +19,12 @@ modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model
 
 ## The file's exact shape
 
-Everything lives under six top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
+Everything lives under seven top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
 
 ```json
 {
   "provider": "gemini-api",
+  "cooldown": "on",
   "proxy": "http://127.0.0.1:7890",
   "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
   "saved": {
@@ -64,7 +65,8 @@ Everything lives under six top-level keys, all optional. This example shows ever
 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`, `kimi`/`kimi-code` for `kimi-cli`, `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>`: six fields exist, `apiKey`, `baseUrl`, `model`, `proxy`, `extraBody`, and `structuredOutput` (the openai route only). 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.
+- `cooldown`: `'on'` (default) or `'off'`. On, a quota-spent key is remembered in `~/.modlens/state.json` and tried last until it recovers (45 minutes by default, 24 hours for monthly HTTP 432/433, or the engine-reported `Resets in` clause). Off, that file is neither read nor written. `modlens state clear` forgets every cooldown.
+- `providers.<name>.<field>`: six fields exist, `apiKey`, `baseUrl`, `model`, `proxy`, `extraBody`, and `structuredOutput` (the openai route only). 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. `apiKey` accepts a comma-separated list. Requests use the configured order and rotate only after authentication, rate-limit, or quota failures. Other failures skip remaining keys and keep provider failover.
 - `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 each route's own enforcement machinery are refused with an error naming the field. `response_format` on the `openai` route is not one of them: setting it there deliberately replaces the schema modlens would otherwise send. The three CLI providers take no request body, so a run on `antigravity-cli`, `claude-cli` or `kimi-cli` ignores it and says so in `meta.warnings`.
 - `providers.openai.structuredOutput`: `true` asks an OpenAI-compatible gateway to enforce the vision contract itself, as `response_format: json_schema` in the strict form those endpoints require. Off by default, since a gateway without structured-output support answers 400 for the field. A `response_format` you set in `extraBody` wins over it.
 - `saved.openai.<label>`: named saved copies of the openai slot, written only by `modlens config save openai <label>` and swapped in whole by `modlens config use openai <label>`. Switching gateways used to mean overwriting `providers.openai` and losing the previous key; a saved copy is where it survives. `use` refuses to overwrite an active slot that no label holds (pass `--discard` to drop it deliberately), and nothing in resolution, guards, or the env bindings reads this section: the active slot stays the only openai route in any run.
@@ -73,7 +75,7 @@ Field semantics:
   - `allowModels` non-empty (allowlist mode): only the listed models run the engine, every other identified model is denied. Right for the actual 2026 landscape, where text-only models are the short list. A deny pattern still wins over an allow match, so a broad allow can have its vision variants carved out, as in the example above: `glm-5.*` allows the text line while `glm-*v*` catches `glm-5v-turbo`. Anchor allow patterns tightly (`deepseek-v4-*`, not `deepseek*`) so a vendor's next multimodal generation falls off the list and steps aside until you have checked it.
   - List a model by what actually reaches it, not by what it could see: a multimodal model behind a gateway that strips images still needs modlens, and your session transcript records the model name the gateway reports. `modlens doctor`'s Guard section shows the rules and a live verdict for checking the result.
   - `denyWhenUnknown` (default `false`) decides what happens when no signal identifies the active model, in either mode: `false` proceeds, `true` denies. The active model is detected from, strongest first: the `MODLENS_MODEL` env var (`none` means "treat as unknown"), the harness's session storage, the `--model` self-report.
-- `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` configure a provider this file says nothing about, and are ignored entirely for one it does. They used to merge field by field, which built pairings that existed nowhere: a baseUrl and an apiKey are one credential. modlens still reads `MODLENS_HARNESS` (paste-recovery and guard scope), `MODLENS_MODEL` (guard override, see `guards`), and the fingerprints harnesses inject themselves, which pin the guard's storage lookup to the current session: `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, plus the presence markers harness detection relies on (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_SANDBOX`).
+- `GEMINI_API_KEY`, `GEMINI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` configure a provider this file says nothing about, and are ignored entirely for one it does. They used to merge field by field, which built pairings that existed nowhere: a baseUrl and an apiKey are one credential. The key variables accept a comma-separated list the same way the file field does. modlens still reads `MODLENS_HARNESS` (paste-recovery and guard scope), `MODLENS_MODEL` (guard override, see `guards`), and the fingerprints harnesses inject themselves, which pin the guard's storage lookup to the current session: `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, plus the presence markers harness detection relies on (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_SANDBOX`).
 - `reuse.<claude|codex|opencode|pi|grok>`: per-harness grants for spending other local logins, written by the onboarding conversation (`references/onboard.md`). `true` lets reads reuse that harness (pi credentials join the inline region with every guard intact; a signed-in Codex, an OpenCode vision model, or pi driven directly join the agent region before `claude-cli`), `false` records a refusal so the user is never re-asked, absent means never asked and nothing runs. `claude` absent counts as granted: `claude-cli` predates this model as a built-in provider, and `reuse.claude false` removes it from the chain (`-p claude-cli` still pins). Reused engines get no priority over the user's own: regions order by speed class only. Every reused answer adds a `meta.warnings` line naming whose quota it spent, and `modlens doctor`'s Reuse section shows each harness's decision plus what discovery found (probe results cache for 6 hours in `~/.modlens/auto-cache.json`; doctor always re-probes). Set with `modlens config set reuse.codex true` (empty clears back to never-asked).
 - Unknown top-level keys and unknown provider names are ignored rather than rejected, so a typo fails quiet: run `modlens doctor` after hand-editing, it shows which file and env values are actually in effect.