@liustack/modlens 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.11.0 - 2026-08-14
+
+- **A full-project audit, all ten findings fixed, then re-reviewed until clean.** An independent deep review of the whole repository (P0: none) surfaced ten conditional-but-real defects. Every fix went back through further independent review rounds, which caught real bugs in the first fixes themselves (case and Unicode boundaries, a cancellation regression); the final round accepted with no blocking findings. Each item below carries a regression test — the suite grew by 32 cases.
+  - *Cross-project recovery, two ways in.* The OpenCode directory filter's ancestor branch built a LIKE pattern from the database's own `session.directory`, so `_`/`%` inside another project's path acted as wildcards; the comparison now uses exact SUBSTR prefixes in both directions, measured in Unicode code points (SQLite counts characters, JS counts UTF-16 units, so a path with an emoji shifted the boundary), case-sensitive on POSIX and LOWER-folded on Windows (SQLite's LIKE was ASCII case-insensitive, crossing projects on case-sensitive filesystems), with filesystem roots normalized so `/` and `E:/` match as ancestors. And a Claude/Pi transcript recording no cwd at all was accepted on slug evidence alone, though slugs collide (`/tmp/a.b` and `/tmp/a-b`); ownerless transcripts are now skipped by scanning and session lookup, while an explicit `--transcript` still reads anything you point it at.
+  - *Image-type spoofing.* When magic-byte sniffing failed, the extension or content-type used to win, so an `.png` URL serving HTML was encoded and uploaded as an image. Every allowed type must now prove itself from its file header — heic/heif included, via ftyp-box sniffing — so there is no extension or content-type fallback left at all.
+  - *Credential redaction, everywhere errors quote foreign text.* Subprocess stderr, the three API providers' error bodies, and discovery-probe failures now pass through a shared redactor (known keys replaced exactly, common token shapes as the second net) before reaching terminals, `meta.attempts`, model contexts, or the discovery cache. Remote-URL errors quote origin and path only, so signed query tokens (S3 presigns) never travel, and the shapes are tuned to leave prose like "token limit_exceeded" alone.
+  - *Windows PATH probing.* `findOnPath` now walks `PATHEXT`, so a real `agy.exe`/`claude.cmd` install no longer reads as "not on PATH" (doctor and the failover chain both trusted that verdict).
+  - *dsh evidence cache.* Failed reads are no longer memoized forever (a fixed config gets a fresh chance without restarting dsh), concurrent steps join one in-flight read instead of double-spending the engine, the cache is capped LRU-style, and cancellation is per-waiter: aborting one step stops its own wait immediately while the shared read completes into the cache, instead of killing every concurrent joiner. Pasted HEIC/HEIF now maps to its real extension, and an unknown media type refuses instead of dressing up as PNG.
+  - *Docs told the truth about less than the code did.* The security page now states per provider who fetches a remote URL (only gemini-api downloads locally behind the SSRF guards, magic-byte check, and size cap; openai/anthropic hand the URL to the vendor). The output contract now lists `visual` as required, matching the schema that always enforced it, with a docs-contract test pinning the two together. Doctor renders CLI providers as `[ok?] installed / sign-in not verified offline` instead of a flat ok, adds a machine-readable `status` field (`ready`/`installed`/`missing`) so JSON consumers stop reading bare-binary as ready, and the install flow treats the first real read as the auth check. The skill's trigger list drops `.bmp` (never supported by the CLI) and gains `.heif`.
+  - *Hardening around the edges.* The release script and workflow now run lint, refuse version downgrades, and verify the tag matches package.json; CLI numeric flags reject trailing garbage (`--count 3x`); error exits use `process.exitCode` so piped output survives.
+- **dsh install can silently land on 3.5.0 ([#18](https://github.com/liustack/modlens/issues/18)).** pnpm v11's release-age quarantine falls back to an old version when every recent one is inside the window (10 days on pnpm 11.21, measured), and versions before 3.9.0 carry no `dsh.bundle` declaration, so the plugin installs as a plain dependency and none of the tools appear. There is no CLI or env override for the gate ([pnpm#11224](https://github.com/pnpm/pnpm/issues/11224) is still open), but an explicit version or dist-tag skips it ([pnpm#9989](https://github.com/pnpm/pnpm/issues/9989), verified against pnpm 11.21: a bare add resolved 2.8.0 while `@latest` resolved 3.10.0 under the same default gate). The install command everywhere now carries `@latest`, so new installs land current with zero user-side setup; troubleshooting documents the mechanism plus the durable bare-name `minimumReleaseAgeExclude` fallback for whenever pnpm closes that skip. Thanks to @stonogic086-1 for the precise diagnosis.
+
 ## 3.10.0 - 2026-08-14
 
 - **Pasting into the dsh Web UI now works end to end, thumbnails included.** The plugin registers a wrapper provider whose model list carries two entries, `DeepSeek-V4-Flash (modlens vision)` and `DeepSeek-V4-Pro (modlens vision)`; select one and pastes are admitted, because dsh's image admission asks the selected provider for input modalities and the wrapper declares image input. Conversion happens at request time on the wire messages only: the durable session log and the UI keep the native image blocks (your paste keeps its thumbnail), each pasted attachment is read once through the modlens CLI and cached for every later step, and the wrapped request is answered by the same DeepSeek route it always used. The wrap covers DeepSeek and GLM text models only; their own vision models (deepseek-vl/ocr, janus, glm v-series) are excluded by name pattern and by declared modality, so a model that can already see is never wrapped. The `agent/pre-step` auto-read from 3.9.0 becomes opt-in (`autoRead: true`) since request-time conversion owns the paste path and preserves the native UX. Registration also stopped failing silently: the adapter now supplies the base-class methods dsh's duck-typing expects (`providerInfo`, `providerRetryPolicy`), whose absence was exactly the invisible failure, and a registration error is logged to the harness console instead of swallowed.

package/README.md

@@ -34,7 +34,7 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens`, and the text-only DeepSeek model behind dsh reads images through a native `read_image` tool. For pasted images, switch the model selector to one of the two entries the plugin adds, **`DeepSeek-V4-Flash (modlens vision)`** or **`DeepSeek-V4-Pro (modlens vision)`**: pastes are admitted there, converted to evidence at request time (your message keeps its native thumbnail), and answered by the same DeepSeek route. The wrap covers DeepSeek and GLM text models only; their own vision models are excluded automatically.
+**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`, and the text-only DeepSeek model behind dsh reads images through a native `read_image` tool. If dsh warns `declares no dsh.bundle`, pnpm's release-age gate installed an old version: see [troubleshooting](docs/troubleshooting.md#dsh-says-declares-no-dshbundle--installed-as-a-plain-dependency) for the one-line fix. For pasted images, switch the model selector to one of the two entries the plugin adds, **`DeepSeek-V4-Flash (modlens vision)`** or **`DeepSeek-V4-Pro (modlens vision)`**: pastes are admitted there, converted to evidence at request time (your message keeps its native thumbnail), and answered by the same DeepSeek route. The wrap covers DeepSeek and GLM text models only; their own vision models are excluded automatically.
 
 **Paste an image and it reads it.** No saving to a file and passing a path first.
 

package/README.zh-CN.md

@@ -34,7 +34,7 @@ DeepSeek 和 GLM 没有视觉能力，无法进行图片识别。ModLens 借助
 
 ## 亮点
 
-**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `read_image` 工具读图。要粘贴识图，把模型选择器切到插件新增的两个条目之一：**`DeepSeek-V4-Flash (modlens vision)`** 或 **`DeepSeek-V4-Pro (modlens vision)`**，贴图放行、发请求时转成证据（你的消息保留原生缩略图）、仍由原 DeepSeek 路由回答。包装只覆盖 DeepSeek 与 GLM 的文本模型，两家自己的视觉型号自动排除。
+**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `read_image` 工具读图。如果 dsh 提示 `declares no dsh.bundle`，是 pnpm 的发布冷静期把版本压旧了，一行配置可解，见[故障排查](docs/troubleshooting.md#dsh-says-declares-no-dshbundle--installed-as-a-plain-dependency)。要粘贴识图，把模型选择器切到插件新增的两个条目之一：**`DeepSeek-V4-Flash (modlens vision)`** 或 **`DeepSeek-V4-Pro (modlens vision)`**，贴图放行、发请求时转成证据（你的消息保留原生缩略图）、仍由原 DeepSeek 路由回答。包装只覆盖 DeepSeek 与 GLM 的文本模型，两家自己的视觉型号自动排除。
 
 **直接粘贴图片识别** 无需先保存成文件再提供路径。
 
@@ -62,7 +62,7 @@ agy                                                           # 浏览器完成
 **DeepSeek Harness（dsh）用户不走 skill 流程**，本包就是原生 dsh 插件：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 ```
 
 装完即有 `read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.md)。

package/dist/main.js

@@ -13672,7 +13672,7 @@ function requireMockUtils() {
     }
     return normalizedQp;
   }
-  function safeUrl(path2) {
+  function safeUrl2(path2) {
     if (typeof path2 !== "string") {
       return path2;
     }
@@ -13710,10 +13710,10 @@ function requireMockUtils() {
   }
   function getMockDispatch(mockDispatches, key) {
     const basePath = key.query ? serializePathWithQuery(key.path, key.query) : key.path;
-    const resolvedPath = typeof basePath === "string" ? safeUrl(basePath) : basePath;
+    const resolvedPath = typeof basePath === "string" ? safeUrl2(basePath) : basePath;
     const resolvedPathWithoutTrailingSlash = removeTrailingSlash(resolvedPath);
     let matchedMockDispatches = mockDispatches.filter(({ consumed }) => !consumed).filter(({ path: path2, ignoreTrailingSlash }) => {
-      return ignoreTrailingSlash ? matchValue(removeTrailingSlash(safeUrl(path2)), resolvedPathWithoutTrailingSlash) : matchValue(safeUrl(path2), resolvedPath);
+      return ignoreTrailingSlash ? matchValue(removeTrailingSlash(safeUrl2(path2)), resolvedPathWithoutTrailingSlash) : matchValue(safeUrl2(path2), resolvedPath);
     });
     if (matchedMockDispatches.length === 0) {
       throw new MockNotMatchedError(`Mock dispatch not matched for path '${resolvedPath}'`);
@@ -27236,15 +27236,6 @@ function parseIpv6Groups(groups) {
   }
   return parsed;
 }
-const MIME_BY_EXT = {
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".png": "image/png",
-  ".webp": "image/webp",
-  ".gif": "image/gif",
-  ".heic": "image/heic",
-  ".heif": "image/heif"
-};
 const MAX_REMOTE_IMAGE_BYTES = 25 * 1024 * 1024;
 const ALLOWED_MIME = /* @__PURE__ */ new Set([
   "image/png",
@@ -27270,8 +27261,27 @@ const SNIFFERS = [
   {
     mime: "image/webp",
     test: (b) => b.length >= 12 && b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP"
+  },
+  // ISO BMFF: bytes 4-8 spell "ftyp" and the brand names the format. This
+  // closes the last extension-trust hole: heic/heif must now prove
+  // themselves from the header like every other type.
+  {
+    mime: "image/heic",
+    test: (b) => b.length >= 12 && b.toString("ascii", 4, 8) === "ftyp" && ["heic", "heix", "hevc", "hevx"].includes(b.toString("ascii", 8, 12))
+  },
+  {
+    mime: "image/heif",
+    test: (b) => b.length >= 12 && b.toString("ascii", 4, 8) === "ftyp" && ["mif1", "msf1", "heif"].includes(b.toString("ascii", 8, 12))
   }
 ];
+function safeUrl(url) {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return "<unparseable url>";
+  }
+}
 function sniffImageMime(buffer) {
   for (const { mime, test } of SNIFFERS) {
     if (test(buffer)) {
@@ -27280,22 +27290,13 @@ function sniffImageMime(buffer) {
   }
   return null;
 }
-function extMime(source) {
-  const ext = /^https?:\/\//i.test(source) ? path.extname(new URL(source).pathname).toLowerCase() : path.extname(source).toLowerCase();
-  return MIME_BY_EXT[ext] ?? null;
-}
-function resolveImageMime(buffer, source, contentType) {
+function resolveImageMime(buffer, source, _contentType) {
   const sniffed = sniffImageMime(buffer);
   if (sniffed) {
     return sniffed;
   }
-  const declared = contentType?.split(";")[0]?.trim().toLowerCase();
-  const candidate = extMime(source) ?? (declared?.startsWith("image/") ? declared : null);
-  if (candidate && ALLOWED_MIME.has(candidate)) {
-    return candidate;
-  }
   throw new Error(
-    `Unsupported or unrecognized image type for ${source}. Allowed: ${[...ALLOWED_MIME].join(", ")}.`
+    `Content of ${source} does not look like a supported image (its bytes match no known image header). Allowed types: ${[...ALLOWED_MIME].join(", ")}.`
   );
 }
 function readLocalImageBase64(filePath) {
@@ -27331,32 +27332,34 @@ async function fetchRemoteImageBase64(url, timeoutMs) {
         const location = response2.headers.get("location");
         if (!location) {
           throw new Error(
-            `Redirect response (${response2.status}) missing location header: ${current}`
+            `Redirect response (${response2.status}) missing location header: ${safeUrl(current.toString())}`
           );
         }
         await response2.body?.cancel();
         if (hop === MAX_REDIRECTS) {
-          throw new Error(`Too many redirects (max ${MAX_REDIRECTS}): ${url}`);
+          throw new Error(`Too many redirects (max ${MAX_REDIRECTS}): ${safeUrl(url)}`);
         }
         current = normalizeRemoteImageUrl(new URL(location, current).toString());
         continue;
       }
       if (!response2.ok) {
-        throw new Error(`Failed to download image (${response2.status}): ${current}`);
+        throw new Error(
+          `Failed to download image (${response2.status}): ${safeUrl(current.toString())}`
+        );
       }
       const declaredLength = Number(response2.headers.get("content-length"));
       if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_IMAGE_BYTES) {
         throw new Error(
-          `Remote image is ${declaredLength} bytes, over the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${current}`
+          `Remote image is ${declaredLength} bytes, over the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${safeUrl(current.toString())}`
         );
       }
       const finalUrl = current.toString();
       const buffer = await readCapped(response2, finalUrl);
       const contentType = response2.headers.get("content-type") ?? void 0;
-      const mimeType = resolveImageMime(buffer, finalUrl, contentType);
+      const mimeType = resolveImageMime(buffer, safeUrl(finalUrl), contentType);
       return { data: buffer.toString("base64"), mimeType };
     }
-    throw new Error(`Too many redirects (max ${MAX_REDIRECTS}): ${url}`);
+    throw new Error(`Too many redirects (max ${MAX_REDIRECTS}): ${safeUrl(url)}`);
   } finally {
     for (const dispatcher2 of dispatchers) {
       void dispatcher2.close();
@@ -27387,7 +27390,7 @@ async function readCapped(response2, url) {
     const buffer = Buffer.from(await response2.arrayBuffer());
     if (buffer.length > MAX_REMOTE_IMAGE_BYTES) {
       throw new Error(
-        `Remote image exceeds the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${url}`
+        `Remote image exceeds the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${safeUrl(url)}`
       );
     }
     return buffer;
@@ -27404,7 +27407,7 @@ async function readCapped(response2, url) {
     if (total > MAX_REMOTE_IMAGE_BYTES) {
       await reader.cancel();
       throw new Error(
-        `Remote image exceeds the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${url}`
+        `Remote image exceeds the ${MAX_REMOTE_IMAGE_BYTES}-byte limit: ${safeUrl(url)}`
       );
     }
     chunks.push(Buffer.from(value));
@@ -27677,6 +27680,33 @@ function hasPath(value, dottedPath) {
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const TOKEN_SHAPES = [
+  // Vendor-prefixed keys (OpenAI/Anthropic sk-, Stripe rk/pk, Slack xox*).
+  /\b(?:sk|rk|pk|xox[a-z])-[A-Za-z0-9_-]{12,}\b/g,
+  // Google API keys.
+  /\bAIza[A-Za-z0-9_-]{20,}\b/g,
+  // GitHub tokens.
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+  // JWTs (three base64url segments, the first spelling {"alg" or {"typ").
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\b/g,
+  // Auth headers: "Bearer xyz" / "Authorization: xyz" (space form is real).
+  /\b(?:bearer|authorization)\b[=:\s]+"?[A-Za-z0-9._~+/-]{12,}"?/gi,
+  // Labeled keys need an explicit = or : separator; prose like
+  // "token limit_exceeded" is diagnostics, not a credential.
+  /\b(?:token|api[-_]?key)\b\s*[=:]\s*"?[A-Za-z0-9._~+/-]{12,}"?/gi
+];
+function redactSecrets(text, knownSecrets = []) {
+  let out = text;
+  for (const secret of knownSecrets) {
+    if (secret && secret.length >= 6) {
+      out = out.split(secret).join("[redacted]");
+    }
+  }
+  for (const shape of TOKEN_SHAPES) {
+    out = out.replace(shape, "[redacted]");
+  }
+  return out;
+}
 const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
 const DEFAULT_BASE_URL$1 = "https://api.anthropic.com";
 const TOOL_NAME = "report_vision_evidence";
@@ -27744,7 +27774,9 @@ Report your findings by calling the ${TOOL_NAME} tool.`;
   });
   if (!response2.ok) {
     const body2 = await response2.text();
-    throw new Error(`Anthropic API error ${response2.status}: ${truncate(body2)}`);
+    throw new Error(
+      `Anthropic API error ${response2.status}: ${truncate(redactSecrets(body2, [apiKey]))}`
+    );
   }
   const payload = await response2.json();
   const toolUse = payload.content?.find((block) => block.type === "tool_use");
@@ -28035,7 +28067,9 @@ async function executeGeminiApi(options) {
   });
   if (!response2.ok) {
     const body2 = await response2.text();
-    throw new Error(`Gemini API error ${response2.status}: ${truncate(body2)}`);
+    throw new Error(
+      `Gemini API error ${response2.status}: ${truncate(redactSecrets(body2, [apiKey]))}`
+    );
   }
   const payload = await response2.json();
   const text = payload.candidates?.[0]?.content?.parts?.map((part) => part.text ?? "").join("");
@@ -28109,7 +28143,9 @@ ${JSON_TEMPLATE_INSTRUCTION}`;
   });
   if (!response2.ok) {
     const body2 = await response2.text();
-    throw new Error(`OpenAI-compatible API error ${response2.status}: ${truncate(body2)}`);
+    throw new Error(
+      `OpenAI-compatible API error ${response2.status}: ${truncate(redactSecrets(body2, [apiKey]))}`
+    );
   }
   const payload = await response2.json();
   const text = payload.choices?.[0]?.message?.content;
@@ -28442,13 +28478,16 @@ const PROVIDER_DESCRIPTORS = [
 ];
 function findOnPath(bin, env) {
   const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const suffixes = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
   for (const dir of dirs) {
-    const full = path.join(dir, bin);
-    try {
-      if (fs.statSync(full).isFile()) {
-        return full;
+    for (const suffix of suffixes) {
+      const full = path.join(dir, bin + suffix);
+      try {
+        if (fs.statSync(full).isFile()) {
+          return full;
+        }
+      } catch {
       }
-    } catch {
     }
   }
   return null;
@@ -28609,7 +28648,10 @@ function probeCodex(env, home) {
         loggedIn,
         visionModels: [],
         source: "none",
-        error: error instanceof Error ? error.message : String(error)
+        error: redactSecrets(error instanceof Error ? error.message : String(error)).slice(
+          0,
+          200
+        )
       };
     }
   });
@@ -28682,7 +28724,10 @@ function probePi(env, home) {
         cliPath,
         visionModels: [],
         source: "none",
-        error: error instanceof Error ? error.message : String(error)
+        error: redactSecrets(error instanceof Error ? error.message : String(error)).slice(
+          0,
+          200
+        )
       };
     }
   });
@@ -28704,7 +28749,10 @@ function probeOpencode(env, runCli) {
         cliPath,
         visionModels: [],
         source: "none",
-        error: error instanceof Error ? error.message : String(error)
+        error: redactSecrets(error instanceof Error ? error.message : String(error)).slice(
+          0,
+          200
+        )
       };
     }
   });
@@ -29221,7 +29269,9 @@ async function analyzeImage(options) {
         provider: provider.name,
         ok: false,
         durationSeconds: (Date.now() - startedAt) / 1e3,
-        error: message.slice(0, 300)
+        // Providers redact their own errors, but attempts travel into
+        // output and model contexts, so the record gets the belt too.
+        error: redactSecrets(message).slice(0, 300)
       });
     }
   }
@@ -29444,7 +29494,9 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
         const explained = describeFailure?.({ stdout, stderr, code, startedAt: runStartedAt }) ?? null;
         reject(
           new Error(
-            explained ?? `${providerName} provider failed with code ${code}.${stderr ? ` stderr: ${stderr.trim()}` : ""}`
+            redactSecrets(
+              explained ?? `${providerName} provider failed with code ${code}.${stderr ? ` stderr: ${stderr.trim()}` : ""}`
+            )
           )
         );
         return;
@@ -29572,7 +29624,6 @@ function cwdMatches(recorded, wanted, bothDirections = false) {
   return bothDirections && resolvedWanted.startsWith(`${resolvedRecorded}${path.sep}`);
 }
 function transcriptBelongsTo(lines, cwd, bothDirections = false) {
-  let sawCwd = false;
   for (const line of lines) {
     if (!line.includes('"cwd"')) {
       continue;
@@ -29582,14 +29633,13 @@ function transcriptBelongsTo(lines, cwd, bothDirections = false) {
       if (typeof recorded !== "string") {
         continue;
       }
-      sawCwd = true;
       if (cwdMatches(recorded, cwd, bothDirections)) {
         return true;
       }
     } catch {
     }
   }
-  return !sawCwd;
+  return false;
 }
 function readLines(filePath) {
   try {
@@ -29718,16 +29768,19 @@ const claudeAdapter = jsonlAdapter({
 function opencodeDbPath() {
   return path.join(os.homedir(), ".local", "share", "opencode", "opencode.db");
 }
-function escapeLikePattern(value) {
-  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
-}
-function opencodeDirectoryFilter(resolvedCwd) {
+function opencodeDirectoryFilter(resolvedCwd, caseInsensitive = process.platform === "win32") {
   const normalized = resolvedCwd.replace(/\\/g, "/");
-  const escaped = escapeLikePattern(normalized);
-  const dir = `REPLACE(session.directory, '\\', '/')`;
+  const cwd = caseInsensitive ? normalized.toLowerCase() : normalized;
+  const prefix = `${cwd.replace(/\/+$/, "")}/`;
+  const rawDir = `REPLACE(session.directory, '\\', '/')`;
+  const dir = caseInsensitive ? `LOWER(${rawDir})` : rawDir;
+  const dirPrefix = `RTRIM(${dir}, '/') || '/'`;
   return {
-    clause: `(${dir} = ? OR ${dir} LIKE ? || '/%' ESCAPE '\\' OR ? LIKE ${dir} || '/%' ESCAPE '\\')`,
-    params: [normalized, escaped, normalized]
+    // SQLite SUBSTR counts Unicode characters while JS .length counts
+    // UTF-16 units, so the length parameter is measured in code points
+    // ([...str].length) or an emoji in a path would shift the boundary.
+    clause: `(${dir} = ? OR SUBSTR(${dir}, 1, ?) = ? OR SUBSTR(?, 1, LENGTH(${dirPrefix})) = ${dirPrefix})`,
+    params: [cwd, [...prefix].length, prefix, cwd]
   };
 }
 function buildOpencodeQuery(resolvedCwd, sessionId) {
@@ -30175,8 +30228,13 @@ function inspectProvider(descriptor, config2, env) {
       name: descriptor.name,
       kind: "subprocess",
       ready: binaryPath !== null,
+      status: binaryPath !== null ? "installed" : "missing",
+      // "On PATH" proves installation, not a working login: doctor runs
+      // offline and spends nothing, so sign-in state stays unverified
+      // here and the first real read is the auth check.
+      authUnverified: binaryPath !== null,
       binaryPath,
-      detail: binaryPath ? `${descriptor.bin} found at ${binaryPath}` : `${descriptor.bin} not on PATH`,
+      detail: binaryPath ? `${descriptor.bin} found at ${binaryPath} (installed; sign-in not verified offline)` : `${descriptor.bin} not on PATH`,
       fix: binaryPath ? void 0 : descriptor.install
     };
   }
@@ -30194,6 +30252,7 @@ function inspectProvider(descriptor, config2, env) {
     name: descriptor.name,
     kind: "api",
     ready,
+    status: ready ? "ready" : "missing",
     settings: statuses,
     detail,
     fix: ready ? void 0 : descriptor.fix
@@ -30314,7 +30373,8 @@ function renderDoctorReport(report) {
   lines.push("");
   lines.push("Providers");
   for (const provider of report.providers) {
-    lines.push(`  ${mark(provider.ready)} ${provider.name}: ${provider.detail}`);
+    const providerMark = provider.ready && provider.authUnverified ? "[ok?]" : mark(provider.ready);
+    lines.push(`  ${providerMark} ${provider.name}: ${provider.detail}`);
     if (provider.fix) {
       lines.push(`       fix: ${provider.fix}`);
     }
@@ -30461,7 +30521,7 @@ function locateSource(cwd, adapters = ADAPTERS) {
     const blocked = blockers.length > 0 ? `
 Blocked: ${blockers.join(" | ")}` : "";
     throw new Error(
-      `No pasted images found in any session storage for this directory (looked in: ${dirs}). The user may not have pasted any, or the storage format changed; ask for a file path instead.${blocked}`
+      `No pasted images found in any session storage for this directory (looked in: ${dirs}). The user may not have pasted any, the storage format changed, or a legacy transcript records no cwd (ownership cannot be proven; an explicit --transcript path bypasses that check). Ask for a file path instead.${blocked}`
     );
   }
   return best.ref;
@@ -30528,7 +30588,7 @@ function recoverPastedImages(options = {}) {
   const all = source.extract();
   if (all.length === 0) {
     throw new Error(
-      `No pasted images found in ${source.location}. The user may not have pasted any, or the storage format changed; ask for a file path instead.`
+      `No pasted images found in ${source.location}. The user may not have pasted any, the storage format changed, or a legacy transcript records no cwd (ownership cannot be proven; an explicit --transcript path bypasses that check). Ask for a file path instead.`
     );
   }
   const outDir = prepareOutDir(options.outDir);
@@ -30560,16 +30620,19 @@ function recoverPastedImages(options = {}) {
   return result;
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.10.0");
+function parsePositiveInt(raw, flag) {
+  if (!/^\d+$/.test(raw.trim()) || Number.parseInt(raw, 10) <= 0) {
+    throw new Error(`Invalid ${flag}. Use a positive integer.`);
+  }
+  return Number.parseInt(raw, 10);
+}
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.11.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"}}'`
 ).action(async (options) => {
   try {
-    const timeoutMs = Number.parseInt(options.timeout, 10);
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-      throw new Error("Invalid --timeout. Use a positive integer in milliseconds.");
-    }
+    const timeoutMs = parsePositiveInt(options.timeout, "--timeout (milliseconds)");
     const config2 = loadConfigFile();
     if (process.env.MODLENS_MODEL?.trim()) {
       const verdict = runGuard(config2.guards, {
@@ -30607,7 +30670,7 @@ program.command("analyze", { isDefault: true }).description("Analyze an image in
       `Error: ${error instanceof Error ? error.message : String(error)}
 `
     );
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
 program.command("recover-paste").description(
@@ -30620,10 +30683,7 @@ program.command("recover-paste").description(
   "Force the storage scope: claude-code, pi, opencode, or none (default: auto-detect via process ancestry and env)"
 ).option("--cwd <path>", "Project directory the image was pasted in", process.cwd()).action(async (options) => {
   try {
-    const count = Number.parseInt(options.count, 10);
-    if (!Number.isFinite(count) || count <= 0) {
-      throw new Error("Invalid --count. Use a positive integer.");
-    }
+    const count = parsePositiveInt(options.count, "--count");
     const result = recoverPastedImages({
       count,
       outDir: options.outDir,
@@ -30639,7 +30699,7 @@ program.command("recover-paste").description(
       `Error: ${error instanceof Error ? error.message : String(error)}
 `
     );
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
 program.command("guard").description(
@@ -30683,7 +30743,7 @@ program.command("doctor").description(
       `Error: ${error instanceof Error ? error.message : String(error)}
 `
     );
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
 const config = program.command("config").description(`Manage ${CONFIG_PATH} (providers, keys, models)`);
@@ -30705,7 +30765,7 @@ config.command("init").description(`Create a starter config at ${CONFIG_PATH}`).
       `Error: ${error instanceof Error ? error.message : String(error)}
 `
     );
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
 config.command("set <key> <value>").description("Set a value, e.g. modlens config set gemini-api.apiKey <key>").action((key, value) => {
@@ -30718,7 +30778,7 @@ config.command("set <key> <value>").description("Set a value, e.g. modlens confi
       `Error: ${error instanceof Error ? error.message : String(error)}
 `
     );
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
 config.command("show").description("Print the effective config (file merged with env vars), API keys masked").action(() => {
@@ -30730,7 +30790,7 @@ config.command("show").description("Print the effective config (file merged with
       `Error: ${error instanceof Error ? error.message : String(error)}
 `
     );
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
-program.parse();
+await program.parseAsync();

package/docs/cli.md

@@ -30,6 +30,8 @@ Output is a fixed JSON shape:
     "summary": "A workflow diagram with four nodes connected by labeled arrows.",
     "ocr": { "full_text": "/shaping\nBEFORE YOU BUILD\n...", "lines": [] },
     "layout": { "regions": [{ "reading_order": 1, "type": "title", "text": "/shaping" }] },
+    "semantics": { "scene": "workflow diagram", "entities": [], "relations": [] },
+    "visual": { "dominant_colors": ["white", "black"], "style": "flat", "notes": [] },
     "uncertainty": []
   },
   "meta": {
@@ -65,7 +67,7 @@ Output is a fixed JSON shape:
 `--extra-body` is how vendor-specific knobs get through, turning thinking off
 being the common one. It applies to the three API providers and replaces the
 configured `extraBody` for that run. Per-vendor spellings and the fields it
-refuses to touch are in [Configuration](configure.md).
+refuses to touch are in [Configuration](../skills/modlens/references/configure.md).
 
 The default `-m` model depends on the provider:
 
@@ -88,7 +90,7 @@ The default `-m` model depends on the provider:
 | `--harness <name>` | Force storage scope: `claude-code`, `pi`, `opencode`, `none` | auto-detect |
 | `--cwd <path>` | Project directory the image was pasted in | current directory |
 
-Five providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Without `-p`, a run tries every provider that is set up, inline API providers first (5-10s), then the agents; the first good result wins and `meta.attempts` records the rest. Harnesses granted via `reuse.<harness>` contribute reused engines to the same regions (pi credentials inline, agent CLIs behind), with no priority over the user's own; details and the `guards` deny/allow lists are in [Configuration](configure.md).
+Five providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Without `-p`, a run tries every provider that is set up, inline API providers first (5-10s), then the agents; the first good result wins and `meta.attempts` records the rest. Harnesses granted via `reuse.<harness>` contribute reused engines to the same regions (pi credentials inline, agent CLIs behind), with no priority over the user's own; details and the `guards` deny/allow lists are in [Configuration](../skills/modlens/references/configure.md).
 
 Other subcommands:
 

package/docs/harness-setup.md

@@ -18,7 +18,7 @@ One catch with text-only models: once `models.json` declares `input_modalities:
 
 ## Claude Code, Pi, OpenCode
 
-None of them writes a pasted image to a regular temp file, but all three persist the user message locally before any gateway strips it:
+None of them hands the model a usable temp-file path the way Codex does (newer Claude Code builds do write pastes to their own `~/.claude/image-cache/`, injected as a path line only in the terminal entrypoint), but all three persist the user message locally before any gateway strips it:
 
 | Harness | Storage | Notes |
 | :-- | :-- | :-- |
@@ -53,7 +53,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
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 ```
 
-This registers a `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 touches only `ctx.tools.register` to keep that surface minimal.
+This registers a `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.

package/docs/output-schema.md

@@ -67,6 +67,6 @@ The CLI prints one JSON object to stdout:
 }
 ```
 
-Required fields: `summary`, `ocr`, `layout`, `semantics`, `uncertainty`. `visual` is optional.
+Required fields: `summary`, `ocr`, `layout`, `semantics`, `visual`, `uncertainty` — every top-level field, `visual` included. (Earlier docs called `visual` optional; the enforced schema has always required it, so build to the schema.)
 
 Changes from v1: pixel `bbox` coordinates and numeric `confidence` scores were removed. Vision models fabricate both, so v2 stops pretending to provide them. `layout.regions[].type` gained `code`.

package/docs/security.md

@@ -22,7 +22,15 @@ The `claude-cli` provider runs with `--allowedTools Read` only, so it can read l
 
 Both subprocess providers also run in a throwaway directory created fresh per call and removed afterward. For a local image it holds a private copy of that one image and nothing else, and it is a real copy, never a hardlink, so a provider writing to its temp path cannot touch the original. For a remote image the directory is empty and the agent downloads into it. Without this, text inside an image could steer a broadly-permissioned agent into reading files next to the original, or whatever project the caller happened to be in. Passing `--workdir` opts out and runs where you point it.
 
-This is exposure reduction, not an OS sandbox: the agent can still read absolute paths, reach the network, and spawn processes. Treat it as a narrower default, not a security boundary. For images you do not trust, prefer an inline API provider (`-p gemini-api`), which hands the bytes to an HTTP endpoint and runs no local agent. Remote URLs already prefer that path: the failover chain for a remote URL tries the inline API providers first and the agent last, because the inline path downloads the image itself, behind the private-address guards, the magic-byte image check, and the size cap, none of which apply when an agent fetches the URL on its own. An explicit `-p` pins one provider and overrides the chain.
+This is exposure reduction, not an OS sandbox: the agent can still read absolute paths, reach the network, and spawn processes. Treat it as a narrower default, not a security boundary. For images you do not trust, prefer `-p gemini-api`, which downloads the bytes itself and runs no local agent. Remote URLs already prefer the inline region: the failover chain for a remote URL tries the inline API providers first and the agents last. Who actually fetches a remote URL differs per provider, and only a local download can be guarded locally:
+
+| Provider | Who fetches a remote URL | Local guards |
+| :-- | :-- | :-- |
+| `gemini-api` | modlens downloads, sends bytes inline | private-address guards, magic-byte check, 25 MB cap |
+| `openai`, `anthropic` | the URL is passed to the vendor, which fetches it | none locally; the vendor's own fetching policy applies |
+| `antigravity-cli`, agent CLIs | the agent fetches on its own | none locally |
+
+So the private-address guards, the magic-byte check, and the size cap protect exactly the paths where modlens itself downloads: every local file read, and gemini-api's remote fetch. An explicit `-p` pins one provider and overrides the chain.
 
 ## Image content is untrusted input
 

package/docs/troubleshooting.md

@@ -119,6 +119,41 @@ One known blind spot: storage detection reads the newest assistant turn recorded
 
 Note that the hard refusal above only fires on an actual `denyModels` match against the explicit `MODLENS_MODEL` value. Storage detection and the `denyWhenUnknown` policy never block `analyze`, they only speak through `modlens guard`, whose deny is advice to the agent rather than a locked door.
 
+## dsh says "declares no dsh.bundle — installed as a plain dependency"
+
+The dsh profile installed an old modlens version. The `dsh.bundle` declaration
+exists since 3.9.0, and pnpm v11's release-age gate (`minimumReleaseAge`,
+quarantining recently published versions, with a 10-day window measured on pnpm 11.21) silently falls back to an older version when every
+recent one is inside the window. That old version has no bundle declaration,
+so dsh correctly treats it as a plain dependency and none of the tools appear.
+
+The fix: name the version explicitly. pnpm applies the age gate when resolving
+a range, but an explicit version or dist-tag skips it ([pnpm#9989](https://github.com/pnpm/pnpm/issues/9989), verified on pnpm 11.21), which is why the install
+command carries `@latest`:
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@latest
+```
+
+dsh's reconcile notices the bundle declaration on the new version and
+activates it; restart dsh afterwards. Verify with
+`npx -y @deepseek-ai/dsh plugin --profile <name> list` — the version shown
+should be 3.9.0 or newer.
+
+If a future pnpm closes that skip, the durable alternative is a one-time
+exclusion in `~/.dsh/profiles/<name>/pnpm-workspace.yaml` — the bare package
+name, not `name@version`, so it survives future releases:
+
+```yaml
+minimumReleaseAgeExclude:
+  - '@liustack/modlens'
+```
+
+then `npx -y @deepseek-ai/dsh plugin --profile <name> update @liustack/modlens`.
+The trade-off is honest either way: an explicit `@latest` (or the exclusion)
+opts modlens out of pnpm's supply-chain cooling-off window, so new releases
+install immediately.
+
 ## Config file problems
 
 ```

package/dsh/index.js

@@ -24,11 +24,13 @@ const CLI_TIMEOUT_MS = 180_000
 export const name = 'modlens'
 export const inject = ['tools', 'agents', 'attachments', 'llm']
 
-const MEDIA_EXT = {
+export const MEDIA_EXT = {
   'image/png': '.png',
   'image/jpeg': '.jpg',
   'image/webp': '.webp',
   'image/gif': '.gif',
+  'image/heic': '.heic',
+  'image/heif': '.heif',
 }
 
 export function apply(ctx, config = {}) {
@@ -191,6 +193,84 @@ function registerVisionProvider(ctx, config) {
   }
 }
 
+// The same pasted attachment rides every later step of its session, but the
+// cache must never make a failure permanent or run the engine twice for
+// concurrent steps. So it stores promises (concurrent readers join the first
+// run), evicts failed reads on settle (a fixed config gets a fresh chance),
+// and caps itself LRU-style so a long-lived Web profile cannot hoard
+// evidence text forever.
+const EVIDENCE_CACHE_LIMIT = 64
+
+function cachedEvidence(ctx, adapter, block) {
+  const key = JSON.stringify(block.attachment ?? block)
+  const hit = adapter.evidenceCache.get(key)
+  if (hit !== undefined) {
+    // Refresh recency: Map iteration order is insertion order.
+    adapter.evidenceCache.delete(key)
+    adapter.evidenceCache.set(key, hit)
+    return hit
+  }
+  // Deliberately no caller signal: a shared entry must not die with its first
+  // caller (their abort used to cancel every concurrent joiner). A cancelled
+  // caller simply stops awaiting; the read finishes and the cache keeps it.
+  const pending = readImageBlock(ctx, block, undefined).then(
+    (evidence) => {
+      // Only evict our own entry: this promise may have been LRU-evicted and
+      // the key re-populated by a newer read meanwhile.
+      if (!evidence.ok && adapter.evidenceCache.get(key) === pending) {
+        adapter.evidenceCache.delete(key)
+      }
+      return evidence.block
+    },
+    (error) => {
+      // readImageBlock never rejects by contract; this is the belt for a
+      // future refactor breaking that, so a rejected promise cannot lodge in
+      // the cache forever.
+      if (adapter.evidenceCache.get(key) === pending) {
+        adapter.evidenceCache.delete(key)
+      }
+      return {
+        type: 'text',
+        text: `[A pasted image could not be read by modlens: ${
+          error instanceof Error ? error.message.slice(0, 300) : String(error)
+        }]`,
+      }
+    },
+  )
+  adapter.evidenceCache.set(key, pending)
+  while (adapter.evidenceCache.size > EVIDENCE_CACHE_LIMIT) {
+    adapter.evidenceCache.delete(adapter.evidenceCache.keys().next().value)
+  }
+  return pending
+}
+
+/**
+ * Wait on a shared promise without inheriting its lifetime: the caller's
+ * abort rejects THIS wait immediately, while the underlying read keeps
+ * running and lands in the cache for the retry.
+ */
+function abortableWait(promise, signal) {
+  if (!signal) return promise
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason ?? new Error('aborted'))
+      return
+    }
+    const onAbort = () => reject(signal.reason ?? new Error('aborted'))
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
 async function convertImagesToEvidence(ctx, messages, signal, adapter) {
   const out = []
   for (const message of messages) {
@@ -204,13 +284,7 @@ async function convertImagesToEvidence(ctx, messages, signal, adapter) {
         content.push(block)
         continue
       }
-      const key = JSON.stringify(block.attachment ?? block)
-      let text = adapter.evidenceCache.get(key)
-      if (text === undefined) {
-        text = (await readImageBlock(ctx, block, signal)).text
-        adapter.evidenceCache.set(key, text)
-      }
-      content.push({ type: 'text', text })
+      content.push(await abortableWait(cachedEvidence(ctx, adapter, block), signal))
     }
     out.push({ ...message, content })
   }
@@ -251,7 +325,7 @@ function registerAutoRead(ctx) {
           content.push(block)
           continue
         }
-        content.push(await readImageBlock(ctx, block, payload.signal))
+        content.push((await readImageBlock(ctx, block, payload.signal)).block)
       }
       messages.push({ ...message, content })
     }
@@ -259,6 +333,12 @@ function registerAutoRead(ctx) {
   })
 }
 
+/**
+ * Read one image block into an evidence text block. Never throws: failures
+ * degrade to an explanatory block with `ok: false`, so callers can decide
+ * what a failure means (the pre-step keeps the step going, the cache refuses
+ * to memoize it).
+ */
 async function readImageBlock(ctx, block, signal) {
   const { mkdtemp, rm, writeFile } = await import('node:fs/promises')
   const { tmpdir } = await import('node:os')
@@ -275,9 +355,15 @@ async function readImageBlock(ctx, block, signal) {
         "attachments.readImage returned no 'data' bytes; the dsh attachment shape may have changed",
       )
     }
-    dir = await mkdtemp(join(tmpdir(), 'modlens-dsh-'))
     const mediaType = stored.ref?.mediaType ?? block.attachment?.mediaType
-    const file = join(dir, `paste${MEDIA_EXT[mediaType] ?? '.png'}`)
+    const ext = MEDIA_EXT[mediaType]
+    if (!ext) {
+      // Refusing beats disguising: a fake .png suffix would make the CLI (and
+      // the provider behind it) judge mislabelled bytes.
+      throw new Error(`unsupported pasted media type ${mediaType ?? '(none declared)'}`)
+    }
+    dir = await mkdtemp(join(tmpdir(), 'modlens-dsh-'))
+    const file = join(dir, `paste${ext}`)
     await writeFile(file, Buffer.from(stored.data), { mode: 0o600 })
     const cli = process.env.MODLENS_DSH_CLI || CLI_PATH
     const { stdout, stderr, code } = await run(
@@ -290,15 +376,21 @@ async function readImageBlock(ctx, block, signal) {
     }
     const parsed = JSON.parse(stdout)
     return {
-      type: 'text',
-      text: `[Pasted image, read by the modlens vision bridge]\n${renderEvidence(parsed.result)}`,
+      ok: true,
+      block: {
+        type: 'text',
+        text: `[Pasted image, read by the modlens vision bridge]\n${renderEvidence(parsed.result)}`,
+      },
     }
   } catch (error) {
     return {
-      type: 'text',
-      text: `[A pasted image could not be read by modlens: ${
-        error instanceof Error ? error.message.slice(0, 300) : String(error)
-      }. Tell the user, and suggest running \`npx @liustack/modlens doctor\`.]`,
+      ok: false,
+      block: {
+        type: 'text',
+        text: `[A pasted image could not be read by modlens: ${
+          error instanceof Error ? error.message.slice(0, 300) : String(error)
+        }. Tell the user, and suggest running \`npx @liustack/modlens doctor\`.]`,
+      },
     }
   } finally {
     if (dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
-    "lint": "biome check src scripts",
+    "lint": "biome check src scripts dsh",
     "format": "biome check --write src scripts",
     "eval": "node evals/run.mjs",
     "release": "node scripts/release.mjs",

package/skills/modlens/SKILL.md

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

@@ -22,7 +22,7 @@ Everything lives under four top-level keys, all optional. This example shows eve
 ```json
 {
   "provider": "gemini-api",
-  "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true },
+  "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
   "guards": {
     "allowModels": ["deepseek-v4-*", "glm-5.*", "minimax-m2.5*", "qwen3-coder*"],
     "denyModels": ["glm-*v*", "deepseek-vl*"],

package/skills/modlens/references/find-image.md

@@ -18,7 +18,7 @@ Newer Claude Code builds write every pasted image to `~/.claude/image-cache/<ses
 
 ## Claude Code, Pi, or OpenCode (no usable path anywhere)
 
-The image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see. Whatever a gateway strips from the request, these harnesses persist user messages, image bytes included, in local session storage first: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+; Bun cannot load node:sqlite, so a bunx-resolved launcher needs a real Node install for OpenCode recovery).
+The image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see. Whatever a gateway strips from the request, these harnesses persist user messages, image bytes included, in local session storage first: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.13+; Bun cannot load node:sqlite, so a bunx-resolved launcher needs a real Node install for OpenCode recovery).
 
 - Run `modlens recover-paste` from the project directory the conversation is happening in (`--count <n>` for several images). It detects which harness it is running inside and reads ONLY that harness's storage. In Claude Code it targets your exact session automatically via the injected `CLAUDE_CODE_SESSION_ID`; `--session <id>` is only needed to override.
 - The output is JSON with real file paths, oldest to newest, so the LAST path is the most recent paste: analyze that one first. Entries carry `filename` when the harness stored one; match on it when the user's message mentions a name.

package/skills/modlens/references/onboard.md

@@ -8,7 +8,7 @@ Run this flow when `~/.modlens/config.json` does not exist, or `modlens config s
 modlens doctor --json
 ```
 
-Read three things from the report: which providers are `ready`, the Reuse section (per-harness decisions plus discovered logins and vision models; the harness this conversation runs inside is itself the first reusable engine), and the guard state. Doctor spends no quota and makes no network calls.
+Read three things from the report: each provider's `status` (`ready` means verified, `installed` means a CLI is on PATH with its sign-in unverified until the first real read, rendered as `[ok?]` in the text report), the Reuse section (per-harness decisions plus discovered logins and vision models, where the harness this conversation runs inside is itself the first reusable engine), and the guard state. Doctor spends no quota and makes no network calls.
 
 ## 2. Tell the user what their machine already has
 
@@ -16,9 +16,9 @@ One line per finding, plain words, in the user's language. Name concrete things,
 
 - An engine is ready: "modlens is ready to go: <provider> is configured (via <env var / config file / existing login>)."
 - Reusable vision found: "Your <harness> CLI is signed in and its model can read images. modlens can reuse it when needed, about <n> seconds per read, and it spends that account's quota."
-- Nothing at all: "No vision engine is set up yet. The fastest free option is a Gemini API key (three minutes, no card); Antigravity CLI works with no sign-up at all."
+- Nothing at all: "No vision engine is set up yet. The fastest free option is a Gemini API key (three minutes, no card). Antigravity CLI works with no sign-up at all."
 
-Do not dump the raw doctor output on the user; summarize it. Do not describe options the machine does not have.
+Do not dump the raw doctor output on the user, summarize it. Do not describe options the machine does not have.
 
 ## 3. Ask before touching anything
 
@@ -27,7 +27,7 @@ Consent rules:
 - One question per decision, never a bundled yes. Reusing Codex and reusing pi credentials are two questions (or one question with independent options), not one.
 - Each question names the harness, whose quota it spends, and the accounting promise. Example wording: "Allow modlens to reuse your signed-in Codex CLI for image reads? Every reused read is labeled in the result so you always see whose quota was spent."
 - The do-nothing outcome must be safe and stated: "If you skip this, modlens just uses the engines you configure yourself."
-- If the user offers an API key, take exactly that key; never go looking for keys they did not hand over.
+- If the user offers an API key, take exactly that key, and never go looking for keys they did not hand over.
 
 ## 4. Apply only what was consented to
 

package/skills/modlens/references/runtime.md

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