@liustack/modlens 3.24.0 → 3.24.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.24.2 - 2026-08-24
+
+- **dsh: repeated `modlens_read_image` calls reuse one image read ([#81](https://github.com/liustack/modlens/issues/81)).** A small host model can emit the same path-tool call repeatedly inside its thinking loop, and every call started a new CLI process because #68 cached attachment conversion but not the explicit tool. The tool now keeps a per-plugin LRU cache keyed by the CLI-normalized source identity and focus prompt. Identical concurrent calls join the same pending read. A changed local file or focus creates a fresh read, remote results expire after 60 seconds, and failures cool for 60 seconds before retrying. Returned evidence is cloned so one consumer cannot mutate the shared result, and the model-facing description explicitly says to call once and reuse the evidence. This prevents repeated tool decisions from becoming repeated vision-provider work. It cannot make a small model stop hallucinating calls or recover reliably from every tool failure, so duplicate call events may remain visible and hosts should still cap tool rounds where available.
+
+## 3.24.1 - 2026-08-24
+
+- **dsh bundle startup no longer logs `inactive context` before `llm` is ready ([#79](https://github.com/liustack/modlens/issues/79)).** Bundle loaders can invoke the plugin while required services are still inactive. The first auto-discovery sweep read `ctx.llm` immediately, logged one to three errors, then relied on later topology events to recover. Discovery now runs inside Cordis's injected `llm` lifecycle. Each activation binds its own service, invalidates pending probes before teardown, and releases its wrapper ownership. A Cordis effect boundary also stops Promise continuations that were already queued from registering or refreshing adapters after the scope starts unloading. Existing and late providers are still discovered exactly once, and preview hosts without injection retain their previous feature-detected path.
+
 ## 3.24.0 - 2026-08-22
 
 - A single `gemini-api`, `openai`, or `anthropic` provider can now use multiple API keys. Both `providers.<name>.apiKey` and the corresponding environment variable accept a comma-separated list, trim each item, and ignore empty entries. Requests use the configured order and rotate only after authentication, rate-limit, or quota failures. Network, 5xx, and response-parsing failures skip the remaining keys and preserve the existing cross-provider failover. Quota cooldown is recorded per key, and a provider moves to the back only when every configured key is cooling. Legacy provider-level cooldown state still loads. Every sibling key is registered for redaction, `doctor` reports the key count, and the dsh settings card explains the syntax. Single-key and keyless attempts keep their previous JSON shape, while multi-key attempts add a zero-based `keyIndex`.

package/README.md

@@ -33,7 +33,7 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** install it instantly with one command: `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.0`. See the [setup guide](docs/harness-setup.md) for installation and update details. If the command line is not your thing but you still want to try DSH, check out <a href="https://github.com/liustack/aimanager"><b>AIManager</b></a>, the lightest desktop wrapper for DeepSeek Harness. It gets you started with zero code or configuration and installs every dependency for you with one click.
+**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** install it instantly with one command: `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.2`. See the [setup guide](docs/harness-setup.md) for installation and update details. If the command line is not your thing but you still want to try DSH, check out <a href="https://github.com/liustack/aimanager"><b>AIManager</b></a>, the lightest desktop wrapper for DeepSeek Harness. It gets you started with zero code or configuration and installs every dependency for you with one click.
 
 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

@@ -33,7 +33,7 @@ DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别
 
 ## 亮点
 
-**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令即刻安装 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.0`。更多安装与更新细节参考 [配置手册](docs/harness-setup.zh-CN.md) 。如果用不惯命令行，也想想玩玩 DSH，推荐食用全网最轻量级的 DeepSeek Harness 桌面版封装 <a href="https://github.com/liustack/aimanager"><b> AIManager</b></a>，零代码零配置起手，一键帮你安装所有依赖环境。
+**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令即刻安装 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.2`。更多安装与更新细节参考 [配置手册](docs/harness-setup.zh-CN.md) 。如果用不惯命令行，也想想玩玩 DSH，推荐食用全网最轻量级的 DeepSeek Harness 桌面版封装 <a href="https://github.com/liustack/aimanager"><b> AIManager</b></a>，零代码零配置起手，一键帮你安装所有依赖环境。
 
 DeepSeek Harness 粘贴识图有两种玩法。
 
@@ -71,7 +71,7 @@ agy                                                           # 浏览器完成
 **DeepSeek Harness（dsh）用户不走 skill 流程**，本包就是原生 dsh 插件：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.0
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.2
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。

package/dist/main.js

@@ -5520,7 +5520,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.24.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.24.2");
 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"}}'`
@@ -5631,7 +5631,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.24.0"
+      version: "3.24.2"
     });
     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.24.0
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.2
 ```
 
 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.24.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.2
 ```
 
 `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.24.0
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.2
 ```
 
 这会注册一个 `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.24.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.2
 ```
 
 `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.24.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.2
 ```
 
 `npm view @liustack/modlens version` prints the current one. pnpm 11 installs a named
@@ -178,7 +178,7 @@ file:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.24.0'
+  - '@liustack/modlens@3.24.2'
 ```
 
 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.24.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.24.2
 ```
 
 `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.24.0
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.24.0'
+  - '@liustack/modlens@3.24.2'
 ```
 
 或者只为这一条命令解除冷静期，注意它解除的是这条命令解析到的所有包，不只 modlens：

package/dsh/index.js

@@ -10,9 +10,9 @@
 // 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 { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { chmodSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawnHidden } from './spawnHidden.js'
 
@@ -22,6 +22,90 @@ const CLI_PATH = fileURLToPath(new URL('../dist/main.js', import.meta.url))
 const OUTPUT_SCHEMA = JSON.parse(readFileSync(new URL('./vision-schema.json', import.meta.url), 'utf8'))
 
 const CLI_TIMEOUT_MS = 180_000
+const TOOL_READ_CACHE_LIMIT = 256
+const TOOL_READ_FAILURE_COOLDOWN_MS = 60_000
+const TOOL_READ_REMOTE_TTL_MS = 60_000
+// Shared by both evidence caches. Monotonic time keeps an NTP adjustment from
+// extending or collapsing a retry window.
+const monotonicNow = () => performance.now()
+
+function toolReadSourceKey(rawSource) {
+  const source = rawSource.trim()
+  if (/^https?:\/\//i.test(source)) {
+    return `remote:${source}`
+  }
+  try {
+    const file = /^file:\/\//i.test(source) ? fileURLToPath(source) : resolve(source)
+    const stat = statSync(file, { bigint: true })
+    // A path is not an image identity. The inode and nanosecond timestamps
+    // make an overwrite or replacement a fresh read while unchanged bytes at
+    // the same path stay reusable during a thinking loop.
+    return `local:${file}:${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`
+  } catch {
+    // Let the CLI produce the canonical missing-file or invalid-path error.
+    // If the file appears later, the successful stat above changes the key.
+    return `local-unreadable:${source}`
+  }
+}
+
+function trimToolReadCache(cache) {
+  while (cache.size > TOOL_READ_CACHE_LIMIT) {
+    let victim
+    for (const [key, entry] of cache) {
+      if (entry.state !== 'pending') {
+        victim = key
+        break
+      }
+    }
+    // In-flight work stays joinable. The cap goes soft only while every
+    // candidate is pending, then settlement runs this trim again.
+    if (victim === undefined) return
+    cache.delete(victim)
+  }
+}
+
+function cachedToolRead(cache, key, remote, load) {
+  const now = monotonicNow()
+  let entry = cache.get(key)
+  if (entry && entry.expiresAt <= now) {
+    cache.delete(key)
+    entry = undefined
+  }
+  if (entry) {
+    // Map insertion order is the LRU order.
+    cache.delete(key)
+    cache.set(key, entry)
+    return entry.promise
+  }
+
+  entry = { state: 'pending', expiresAt: Number.POSITIVE_INFINITY, promise: undefined }
+  const promise = Promise.resolve()
+    .then(load)
+    .then(
+      (value) => {
+        if (cache.get(key) === entry) {
+          entry.state = 'success'
+          entry.expiresAt = remote ? monotonicNow() + TOOL_READ_REMOTE_TTL_MS : Number.POSITIVE_INFINITY
+          trimToolReadCache(cache)
+        }
+        return value
+      },
+      (error) => {
+        if (cache.get(key) === entry) {
+          // The same failure is free and stable during the cooldown. A later
+          // call probes again, so a recovered engine needs no restart.
+          entry.state = 'failure'
+          entry.expiresAt = monotonicNow() + TOOL_READ_FAILURE_COOLDOWN_MS
+          trimToolReadCache(cache)
+        }
+        throw error
+      },
+    )
+  entry.promise = promise
+  cache.set(key, entry)
+  trimToolReadCache(cache)
+  return promise
+}
 
 export const name = 'modlens'
 export const inject = ['tools', 'agents', 'attachments', 'llm']
@@ -41,6 +125,10 @@ export function apply(ctx, config = {}) {
   // whichever surface asks first (issue #68; auto-read used to bypass
   // caching entirely and re-read every image on every step).
   const evidenceCache = new Map()
+  // Explicit path-tool calls can repeat inside a small model's thinking loop.
+  // Keep their completed evidence beside the attachment cache so the model's
+  // repeated decision does not become repeated vision-provider work (#81).
+  const toolReadCache = new Map()
   // Off by default since the vision provider converts at request time and
   // keeps the durable log (and the UI thumbnail) intact; turn it on only for
   // setups where images enter through a provider this plugin does not wrap.
@@ -55,7 +143,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
@@ -130,7 +231,7 @@ export function apply(ctx, config = {}) {
   const readImageTool = (toolName) => ({
     name: toolName,
     description:
-      'Read an image through the modlens vision bridge. Use whenever a message references an image the current model cannot see: a local file path or an http(s) URL to a screenshot, photo, chart, diagram, or document scan. Returns structured evidence with every word transcribed (ocr.full_text), layout regions in reading order, semantics, and an uncertainty list; quote the evidence instead of guessing. Requires a configured modlens engine (run `npx @liustack/modlens doctor` in a terminal to check).',
+      'Read an image through the modlens vision bridge. Use whenever a message references an image the current model cannot see: a local file path or an http(s) URL to a screenshot, photo, chart, diagram, or document scan. Returns structured evidence with every word transcribed (ocr.full_text), layout regions in reading order, semantics, and an uncertainty list. Quote the evidence instead of guessing. For the same image and focus, call this tool once and reuse its returned evidence instead of calling again. Requires a configured modlens engine (run `npx @liustack/modlens doctor` in a terminal to check).',
     parameters: {
       type: 'object',
       properties: {
@@ -165,23 +266,31 @@ export function apply(ctx, config = {}) {
       if (typeof args?.path !== 'string' || args.path.trim() === '') {
         throw new Error(`${toolName} needs a non-empty string "path".`)
       }
-      const cliArgs = [CLI_PATH, '-i', args.path, '--timeout', String(CLI_TIMEOUT_MS)]
-      if (args.prompt) {
-        cliArgs.push('--prompt', args.prompt)
-      }
-      const { stdout, stderr, code } = await run(process.execPath, cliArgs, exec.signal)
-      if (code !== 0) {
-        throw new Error(`modlens failed (exit ${code}): ${(stderr || stdout).trim().slice(0, 500)}`)
-      }
-      let parsed
-      try {
-        parsed = JSON.parse(stdout)
-      } catch {
-        throw new Error(`modlens produced no JSON: ${stdout.trim().slice(0, 300)}`)
-      }
-      // The canonical value is the vision result itself; routing details
-      // (meta.attempts, whose quota a reused engine spent) stay operational.
-      return parsed.result
+      const sourceKey = toolReadSourceKey(args.path)
+      const cacheKey = JSON.stringify([sourceKey, typeof args.prompt === 'string' ? args.prompt : ''])
+      const pending = cachedToolRead(toolReadCache, cacheKey, sourceKey.startsWith('remote:'), async () => {
+        const cliArgs = [CLI_PATH, '-i', args.path, '--timeout', String(CLI_TIMEOUT_MS)]
+        if (args.prompt) {
+          cliArgs.push('--prompt', args.prompt)
+        }
+        // The shared read has the CLI's own deadline but not one caller's
+        // signal. A caller may stop waiting without cancelling every other
+        // concurrent caller that joined the same image read.
+        const { stdout, stderr, code } = await run(process.execPath, cliArgs, undefined)
+        if (code !== 0) {
+          throw new Error(`modlens failed (exit ${code}): ${(stderr || stdout).trim().slice(0, 500)}`)
+        }
+        let parsed
+        try {
+          parsed = JSON.parse(stdout)
+        } catch {
+          throw new Error(`modlens produced no JSON: ${stdout.trim().slice(0, 300)}`)
+        }
+        // The canonical value is the vision result itself; routing details
+        // (meta.attempts, whose quota a reused engine spent) stay operational.
+        return parsed.result
+      })
+      return structuredClone(await abortableWait(pending, exec.signal))
     },
   })
   // A name of our own rather than the host's. dsh's registry is layered and
@@ -569,10 +678,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 +731,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 +740,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 +758,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 +812,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 +822,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 +846,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 +856,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 +876,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 +924,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 +941,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 +953,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 +1001,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 +1013,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 +1033,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 +1059,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 +1096,7 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
       void sweep()
     })
   }
+  return deactivate
 }
 
 // The same pasted attachment rides every later step of its session, and the
@@ -947,10 +1113,6 @@ function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
 // text forever.
 const EVIDENCE_CACHE_LIMIT = 256
 const EVIDENCE_FAILURE_COOLDOWN_MS = 60_000
-// Monotonic, so an NTP step backwards cannot freeze a cooling failure for
-// the size of the jump: a recovered engine is re-probed one cooldown after
-// the failure, whatever the wall clock did in between.
-const monotonicNow = () => performance.now()
 
 /**
  * A cache key that survives replay: the same attachment serialized with a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.24.0",
+    "version": "3.24.2",
     "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.24.0):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.24.2):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.24.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.24.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.24.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.24.2: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.24.2 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.24.2 <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.24.0
+- Pinned CLI version: 3.24.2
 - 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.24.0'
+$Pinned = '3.24.2'
 # -------------------------------------------------------------------------------
 
 $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.24.0"
+PINNED="3.24.2"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"