@liustack/modlens 2.7.3 → 2.7.4

package/README.md

@@ -11,13 +11,13 @@
 
 DeepSeek-V4-Flash gives you a lot of model for very little money: fast, strong, and its one real flaw is no multimodal. And it's not just DeepSeek. Every text-only model running inside Codex, Claude Code, Pi Agent, or OpenClaw hits the same wall.
 
-ModLens fixes this the lightest way possible. It never touches your config and never adds a local proxy. It's just a vision plug-in, usable as a CLI or as an Agent Skill, that turns any image into structured visual evidence: text, layout, regions, entities, relations, visual clues. Under the hood it runs on [Antigravity CLI](https://antigravity.google) (`agy`), whose vision comes from free-quota Gemini 3.6 Flash. And Gemini's image understanding is famously good, good enough to embarrass most flagships, Fable 5 included. How it works:
+ModLens fixes this the lightest way possible: it never touches your config, never adds a local proxy, and is just a vision plug-in you can run as a CLI or install as an Agent Skill. What it hands back is not a one-line caption but structured visual evidence: text, layout, regions, entities, relations, visual clues. Five vision engines to pick from. The default one needs no key at all, and the fastest one runs on a free Gemini key whose image understanding embarrasses most flagships, Fable 5 included. How it works:
 
 ```text
 text-only model in your agent harness ──▶ modlens skill (auto-triggers on images)
                               │
                               ▼
-                   agy · Gemini 3.6 Flash (free quota)
+                  vision engine · Gemini 3.6 Flash (free)
                               │
                               ▼
               structured JSON evidence ──▶ model answers with sight
@@ -25,49 +25,45 @@ text-only model in your agent harness ──▶ modlens skill (auto-triggers on
 
 ## You can just paste the image
 
-The mainstream way to give a text-only model sight is a vision MCP server. Read their docs and you'll find the same admission: they can't catch a paste. The reason is structural. Pasting is handled entirely by the client: the moment an image lands in the chat box, the client encodes it and sends it straight to the model, and the MCP server never gets a chance to step in. The usual advice is to save the image to a local folder first, then mention the filename or path in the chat.
+Every other bridge makes you save the image to a file first, then mention the path in the chat. ModLens lets you paste it.
 
-ModLens catches that paste. You paste, the text-only model can't see it (the gateway strips the image down to a pathless placeholder), and the skill quietly pulls the image bytes back out of local session storage, writes them to a file, and feeds that to the vision engine. The model answers with the full image content, not a request for a path. You do nothing extra.
+That is not laziness on their part. Pasting is handled end to end by the client: the moment an image lands in the chat box it is encoded and sent, and a vision MCP server never gets a chance to step in, which is why their docs can only tell you to save the file and report the path. ModLens takes the other route. Before those bytes are ever sent, the harness has already written them to local session storage, so the skill goes there, pulls them back out into a real file, and feeds that to the vision engine. You do nothing, and the model answers with the full image instead of asking you for a path.
 
-Verified on real machines across all four harnesses: Claude Code pinpoints the exact session via the injected session id, Pi stores sessions the same way, OpenCode swaps in SQLite, and Codex's pasted images already carry a temp file path, so the skill takes the path-tag route and never misuses recovery. `recover-paste` figures out which harness it is running inside first, by walking the process ancestry and checking environment fingerprints, then reads only that harness's storage, so another tool's stale sessions can't impersonate it.
-
-As far as we know, no other tool catches this paste yet. The usual answer is save the file, then report the path. ModLens's answer is just paste it.
+Verified on real machines across four harnesses: Claude Code pinpoints the exact session from its injected session id, Pi stores sessions the same way, OpenCode swaps in SQLite, and Codex's pasted images already carry a temp path so the path-tag route handles them. Before touching anything, `recover-paste` works out which harness it is running inside, by walking the process ancestry and checking environment fingerprints, and reads only that harness's storage, so another tool's stale sessions can't impersonate it.
 
 ## Quick start
 
-**1. Pick a path and wire up a vision engine** (one-time, pick either one):
+**1. Install the skill.** Just tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):
+
+```text
+Install the skill from https://github.com/liustack/modlens
+```
 
-**Recommended: grab a free Gemini key.** Three minutes, no credit card, 5-10 seconds per image versus 15-40 for agy, and you won't hit a quota wall nearly as fast. Get a key at [aistudio.google.com](https://aistudio.google.com), then:
+or do it yourself:
 
 ```bash
-modlens config set gemini-api.apiKey <key>
-modlens config set provider gemini-api
+npx -y skills add liustack/modlens
 ```
 
-Don't want to type that? Install the skill (step 2 below), then just tell your agent: "set my Gemini key in modlens." It'll run those two commands for you.
+Harnesses look for skills in different places: Claude Code reads `~/.claude/skills/`, Codex reads `~/.codex/skills/`, Pi and OpenCode read `~/.agents/skills/`. Symlinks work in all of them, so linking the skill folder once keeps every agent on the latest version.
 
-**Or: no sign-up, start right now with Antigravity CLI.** No key, pure free quota, but slower (15-40s) and the quota is tight. Details below in Providers and config.
+**2. Wire up a vision engine.** Recommended: a free Gemini key from [aistudio.google.com](https://aistudio.google.com). Three minutes, no credit card, 5-10 seconds per image:
 
 ```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash
-agy    # opens browser sign-in, then exit
+modlens config set gemini-api.apiKey <key>
+modlens config set provider gemini-api
 ```
 
-**2. Install the skill.** Just tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):
-
-```text
-Install the skill from https://github.com/liustack/modlens
-```
+Don't feel like typing those two lines? Tell your agent "set my Gemini key in modlens" and it runs them for you.
 
-or do it yourself:
+Skipping the sign-up is fine too: Antigravity CLI works with no key at all, it is just slower (15-40s) and its free quota is tight.
 
 ```bash
-npx -y skills add liustack/modlens
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy    # opens browser sign-in, then exit
 ```
 
-Harnesses look for skills in different places: Claude Code reads `~/.claude/skills/`, Codex reads `~/.codex/skills/`, Pi and OpenCode read `~/.agents/skills/`. Symlinks work in all of them, so linking the skill folder once keeps every agent on the latest version.
-
-**3. Use it.** Paste an image (or its path) and ask anything. The skill fires on its own.
+**3. Use it.** Paste an image, or throw a path at it, and ask anything. The skill fires on its own.
 
 ## See it work
 
@@ -157,7 +153,7 @@ ModLens ships five vision providers. `antigravity-cli` stays the default: zero k
 | `anthropic` | `ANTHROPIC_API_KEY` | a few seconds | Claude Haiku by default, schema via forced tool call |
 | `claude-cli` | Claude Code signed in | 20-45s | no key, rides your Claude subscription, Read-only permissions |
 
-`antigravity-cli` is free, but it costs you on both ends. It's slower (a full agent loop takes 15-40 seconds, versus 5-10 for `gemini-api` direct), and the quota is tight. At launch in November 2025 the free tier was 250 requests a day. By December it was cut to 20 a day. In 2026 it moved to a one-time weekly grant, and once you hit it, you wait out the cycle: we hit that wall ourselves, and the message read "94 hours until reset." That quota is also a shared pool across the desktop app, the CLI, and the SDK, and running subagents in parallel drains it faster. For steady work, `gemini-api` is the better bet.
+`antigravity-cli` wins on needing no key and loses on both other fronts: it's slower (a full agent loop takes 15-40 seconds against 5-10 for `gemini-api` direct) and its quota is tight. The free tier is now a one-time weekly grant, pooled across the desktop app, the CLI, and the SDK, and parallel subagents drain it faster. Once it's gone you wait out the cycle: we hit that wall ourselves and the message read "94 hours until reset." Great for a first look, but `gemini-api` is what holds up day to day.
 
 Config lives in `~/.modlens/config.json`. Environment variables override the file (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`), and CLI flags override everything.
 
@@ -170,7 +166,7 @@ modlens config set provider gemini-api       # switch the default provider
 
 The free Gemini key takes three minutes at [aistudio.google.com](https://aistudio.google.com), no credit card.
 
-Don't want to type the commands yourself? Once the skill is installed, these are all one sentence away: ask your agent "how do I configure modlens," "set my Gemini key in modlens," or "switch modlens to claude-cli." It follows the skill's own provider setup guide and runs the `modlens config set` commands for you. No docs to read, no flags to memorize.
+You don't actually have to remember any of these commands. The skill ships a per-provider setup guide, so once it's installed you can just ask your agent: "how do I configure modlens," "set my Gemini key in modlens," "switch modlens to claude-cli." It reads the guide and runs them.
 
 ## Using it in Codex (DeepSeek and friends)
 

package/README.zh-CN.md

@@ -11,13 +11,13 @@
 
 DeepSeek-V4-Flash 碗大又好吃，速度快，性能强，要说唯一的缺点就是没有多模态。不仅 DeepSeek-V4-Flash，只要是纯文本语言模型，跑在 Codex、Claude Code、Pi Agent、OpenClaw 中，都有这个问题。
 
-ModLens 用最轻量级方案解决这个问题。ModLens 不会入侵你的配置，也不会给你添加本地代理，ModLens 只是一个视觉外挂，有 cli 或 skill 两种模式。ModLens 能产出结构化的视觉证据：文字、版面、区块、实体、关系、视觉线索。ModLens 由 [Antigravity CLI](https://antigravity.google)（`agy`）驱动，而 Antigravity 的视觉由免费额度的 Gemini 3.6 Flash 驱动。Gemini 的识图能力，连 Fable 5 都吊打。原理如下：
+ModLens 用最轻的方式解决它：不动你的配置，不装本地代理，就是一个视觉外挂，CLI 和 skill 两种用法。它产出的不是一句话描述，是结构化的视觉证据：文字、版面、区块、实体、关系、视觉线索。视觉引擎有五个可选，默认那个零 key 就能跑，最快的那个用免费 Gemini key，识图能力连 Fable 5 都吊打。原理如下：
 
 ```text
 Agent Harness 中的纯文本模型 ──▶ modlens skill（遇到图片自动触发）
                         │
                         ▼
-             agy · Gemini 3.6 Flash（免费额度）
+             视觉引擎 · Gemini 3.6 Flash（免费）
                         │
                         ▼
            结构化 JSON 证据 ──▶ 模型带着视力回答
@@ -25,49 +25,45 @@ Agent Harness 中的纯文本模型 ──▶ modlens skill（遇到图片自动
 
 ## 你可以直接粘贴图片
 
-纯文本模型想看图，主流方案是装一个识图 MCP server。翻开它们的文档，你会看到一句坦白：接不住粘贴。原因很简单，粘贴这个动作从头到尾都是客户端自己办的，图一贴进对话框，客户端就把它转码直接发给模型了，MCP server 连插手的机会都没有。文档给的建议通常是：先把图存到本地某个目录，再在对话里报一句文件名或路径。
+别的方案让你先把图存成文件，再在对话里报一句路径。ModLens 让你直接粘贴。
 
-ModLens 接住了这一下。你粘贴，纯文本模型看不见（网关把图剥成一个不带路径的占位符），skill 自动从本地的会话存储里把图片字节捞回来落成文件，再喂给视觉引擎。模型拿到的是完整图片内容，不是一句「麻烦告诉我路径」。整个过程你不用做任何事。
+这不怪它们偷懒。粘贴这个动作从头到尾是客户端办的，图一进对话框就被转码发走，识图 MCP server 连插手的机会都没有，所以它们的文档只能教你存文件、报路径。ModLens 走的是另一条路：图片字节在发走之前，早被 harness 原样写进了本地会话存储，skill 直接去那里把它捞回来落成文件，再喂给视觉引擎。你什么都不用做，模型拿到的是完整图片，不是一句「麻烦告诉我路径」。
 
-四家主流 harness 都在真机上验证过：Claude Code 用注入的会话 ID 精确定位到当前会话，Pi 的存储路数和它一样，OpenCode 换成了 SQLite，Codex 的粘贴图本来就带临时文件路径，skill 走路径标签这条路，不会误用恢复逻辑。`recover-paste` 会先判断自己正跑在哪一家宿主里（沿进程祖先链往上查，再核对环境变量指纹），只读那一家的存储，别家的旧会话没机会冒充。
-
-据我们所知，还没有第二个工具接住粘贴这一下。别的方案是先存文件、再报路径。ModLens 是你直接粘贴。
+四家 harness 真机验证过：Claude Code 按注入的会话 ID 精确定位，Pi 的存储路数和它同构，OpenCode 换成了 SQLite，Codex 的粘贴图本来就带临时路径，走路径标签就行。动手之前 `recover-paste` 会先认清自己跑在哪一家（查进程祖先链，核对环境变量指纹），只读那一家的存储，别家的旧会话冒充不了。
 
 ## 快速开始
 
-**1. 选一条路，把视觉引擎接好**（一次性，选一条就好）：
+**1. 装 skill。** 直接告诉你的 agent（Claude Code、Codex、OpenClaw、Cursor 等）：
+
+```text
+安装这个 skill https://github.com/liustack/modlens
+```
 
-**推荐：领一个免费 Gemini key。** 三分钟，不要信用卡，直连模型 5-10 秒出结果（agy 要 15-40 秒），额度也没那么容易撞墙。去 [aistudio.google.com](https://aistudio.google.com) 拿到 key，然后：
+或者自己动手：
 
 ```bash
-modlens config set gemini-api.apiKey <key>
-modlens config set provider gemini-api
+npx -y skills add liustack/modlens
 ```
 
-嫌敲命令麻烦？装完下面第 2 步的 skill 后，直接跟你的 agent 说「帮我把 Gemini key 配进 modlens」，它会替你跑完这两行。
+各家 harness 找 skill 的位置不一样：Claude Code 读 `~/.claude/skills/`，Codex 读 `~/.codex/skills/`，Pi 和 OpenCode 读 `~/.agents/skills/`。软链接在哪家都好使，把 skill 目录链一次，各家永远用最新版。
 
-**次选：不想注册、想立刻开跑，就直接用 Antigravity CLI。** 零 key，纯免费额度，但慢一些（15-40 秒），额度也紧，细节见下文「Provider 与配置」。
+**2. 接一个视觉引擎。** 推荐去 [aistudio.google.com](https://aistudio.google.com) 领个免费 Gemini key，三分钟，不要信用卡，出图 5-10 秒：
 
 ```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash
-agy    # 浏览器完成登录后退出
+modlens config set gemini-api.apiKey <key>
+modlens config set provider gemini-api
 ```
 
-**2. 安装 skill。** 直接告诉你的 agent（Claude Code、Codex、OpenClaw、Cursor 等）：
-
-```text
-安装这个 skill https://github.com/liustack/modlens
-```
+懒得敲这两行？跟 agent 说一句「帮我把 Gemini key 配进 modlens」，它自己会跑。
 
-或者自己动手：
+不想注册也行，装上 Antigravity CLI 就能零 key 开跑，代价是慢（15-40 秒），免费额度也紧：
 
 ```bash
-npx -y skills add liustack/modlens
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy    # 浏览器完成登录后退出
 ```
 
-各家 harness 找 skill 的位置不一样：Claude Code 读 `~/.claude/skills/`，Codex 读 `~/.codex/skills/`，Pi 和 OpenCode 读 `~/.agents/skills/`。软链接在哪家都好使，把 skill 目录链一次，各家永远用最新版。
-
-**3. 用起来。** 粘贴一张图（或者图片路径），随便问，skill 会自动触发。
+**3. 用起来。** 粘贴一张图，或者甩个图片路径，随便问。skill 自己会触发。
 
 ## 看看效果
 
@@ -157,7 +153,7 @@ ModLens 内置五个视觉 provider，默认还是 `antigravity-cli`：零 key
 | `anthropic` | `ANTHROPIC_API_KEY` | 几秒 | 默认 Claude Haiku，强制工具调用保 schema |
 | `claude-cli` | Claude Code 已登录 | 20-45 秒 | 零 key，吃你的 Claude 订阅额度，只放行 Read 工具 |
 
-`antigravity-cli` 免费，但两头都紧：慢（完整 agent 循环要 15-40 秒，`gemini-api` 直连只要 5-10 秒），额度也紧。2025 年 11 月刚上线时每天 250 次请求，12 月直接砍到每天 20 次，2026 年又改成一次性发放的周配额，用超了就得等下一个周期重置，我们实测撞过一次墙，提示是「94 小时后重置」。这份配额还是桌面应用、CLI、SDK 三头共用一个池子，用 subagent 并行跑消耗得更快。想稳定干活，还是建议换成 `gemini-api`。
+`antigravity-cli` 胜在零 key，输在两头：慢（完整 agent 循环 15-40 秒，`gemini-api` 直连 5-10 秒），额度紧。它的免费档如今是一次性发放的周配额，桌面应用、CLI、SDK 共用一个池子，subagent 并行还加倍消耗，用超了得等下个周期（我们实测撞过一次，提示「94 小时后重置」）。所以它适合尝鲜，日常主力还是 `gemini-api` 稳。
 
 配置放在 `~/.modlens/config.json`，环境变量能盖过它（`GEMINI_API_KEY`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`ANTHROPIC_API_KEY`），CLI 参数最大。
 
@@ -170,7 +166,7 @@ modlens config set provider gemini-api       # 换默认 provider
 
 免费 Gemini key 去 [aistudio.google.com](https://aistudio.google.com) 领，三分钟，不要信用卡。
 
-嫌自己敲命令麻烦？装完 skill 之后这些配置全部能甩给 agent：问一句「modlens 怎么配置」「帮我把 Gemini key 配进 modlens」「把默认 provider 切成 claude-cli」，agent 会照着 skill 自带的配置手册，自己跑 `modlens config set` 这些命令，不用你查文档，也不用你记参数。
+这些命令你其实一条都不用记。skill 自带一份分 provider 的配置手册，装完之后直接问你的 agent：「modlens 怎么配置」「帮我把 Gemini key 配进 modlens」「把默认 provider 切成 claude-cli」，它照着手册自己跑完。
 
 ## 在 Codex 里用（DeepSeek 等纯文本模型）
 

package/dist/main.js

@@ -36,8 +36,18 @@ function loadConfigFile(configPath = CONFIG_PATH) {
 function defaultProviderName(config2) {
   return config2.provider?.trim() || "antigravity-cli";
 }
+const PROVIDER_ALIASES = {
+  antigravity: "antigravity-cli",
+  agy: "antigravity-cli",
+  gemini: "gemini-api",
+  claude: "claude-cli"
+};
 function resolveProviderSettings(providerName, config2, env = process.env) {
-  const fromFile = config2.providers?.[providerName] ?? {};
+  const aliasNames = Object.entries(PROVIDER_ALIASES).filter(([, canonical]) => canonical === providerName).map(([alias]) => alias);
+  const fromFile = {
+    ...Object.assign({}, ...aliasNames.map((alias) => config2.providers?.[alias] ?? {})),
+    ...config2.providers?.[providerName] ?? {}
+  };
   const bindings = ENV_BINDINGS[providerName] ?? {};
   const settings = { ...fromFile };
   for (const [field, envName] of Object.entries(bindings)) {
@@ -318,6 +328,7 @@ const SWITCH_HINT = `Or switch to a provider with its own quota and no interacti
   modlens config set gemini-api.apiKey <key>   # free key, no card: https://aistudio.google.com
   modlens config set provider gemini-api`;
 function describeAntigravityFailure(context) {
+  const since = context.startedAt ?? Date.now() - LOG_FRESHNESS_MS;
   let envelope = null;
   try {
     envelope = parseEnvelope$1(context.stdout);
@@ -330,7 +341,7 @@ function describeAntigravityFailure(context) {
   const agyError = typeof envelope?.error === "string" ? envelope.error.trim() : "";
   const evidence = `${agyError}
 ${context.stderr}
-${readRecentAgyLog()}`.toLowerCase();
+${readRecentAgyLog(since)}`.toLowerCase();
   if (evidence.includes("quota")) {
     return [
       agyError || "Antigravity CLI reported a quota error.",
@@ -359,14 +370,14 @@ function agyLogDir() {
   return path.join(os.homedir(), ".gemini", "antigravity-cli", "log");
 }
 const LOG_FRESHNESS_MS = 2 * 60 * 1e3;
-function readRecentAgyLog() {
+function readRecentAgyLog(since) {
   try {
     const dir = agyLogDir();
     const newest = fs.readdirSync(dir).filter((name) => name.endsWith(".log")).map((name) => {
       const full = path.join(dir, name);
       return { full, mtime: fs.statSync(full).mtimeMs };
     }).sort((a, b) => b.mtime - a.mtime)[0];
-    if (!newest || Date.now() - newest.mtime > LOG_FRESHNESS_MS) {
+    if (!newest || newest.mtime < since) {
       return "";
     }
     return fs.readFileSync(newest.full, "utf-8").slice(-8e3);
@@ -379,7 +390,8 @@ const antigravityCliProvider = {
   defaultModel: DEFAULT_MODEL,
   buildInvocation: buildAntigravityInvocation,
   parseOutput: parseAntigravityOutput,
-  describeFailure: describeAntigravityFailure
+  describeFailure: describeAntigravityFailure,
+  hasInternalTimeout: true
 };
 const MIME_BY_EXT = {
   ".jpg": "image/jpeg",
@@ -732,9 +744,12 @@ Respond with ONE JSON object only, no markdown fences, no commentary. Fill this
     throw new Error(`OpenAI-compatible API returned non-JSON output: ${truncate(text)}`);
   }
   const shaped = result;
-  if (typeof shaped.summary !== "string" || typeof shaped.ocr !== "object") {
+  const missing = ["summary", "ocr", "layout", "semantics", "visual", "uncertainty"].filter(
+    (field) => shaped[field] === void 0 || shaped[field] === null
+  );
+  if (missing.length > 0 || typeof shaped.summary !== "string" || typeof shaped.ocr !== "object" || !Array.isArray(shaped.uncertainty)) {
     throw new Error(
-      `OpenAI-compatible API returned JSON that does not match the vision schema (missing summary/ocr). Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${truncate(text)}`
+      `OpenAI-compatible API returned JSON that does not match the vision schema${missing.length > 0 ? ` (missing: ${missing.join(", ")})` : ""}. Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${truncate(text)}`
     );
   }
   return {
@@ -811,10 +826,11 @@ async function analyzeImage(options) {
     parsed = await provider.execute(providerOptions);
   } else if (provider.buildInvocation && provider.parseOutput) {
     const invocation = provider.buildInvocation(providerOptions);
+    const backstop = provider.hasInternalTimeout ? timeoutMs + KILL_GRACE_MS : timeoutMs;
     const commandResult = await runCommand(
       provider.name,
       invocation,
-      timeoutMs + KILL_GRACE_MS,
+      backstop,
       provider.describeFailure
     );
     parsed = provider.parseOutput(commandResult.stdout);
@@ -861,11 +877,14 @@ function validateInputFile(filePath) {
   }
 }
 function runCommand(providerName, invocation, timeoutMs, describeFailure) {
+  const runStartedAt = Date.now();
   return new Promise((resolve, reject) => {
     const child = spawn(invocation.command, invocation.args, {
       cwd: invocation.cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
+    const outDecoder = new TextDecoder("utf-8");
+    const errDecoder = new TextDecoder("utf-8");
     let stdout = "";
     let stderr = "";
     let timedOut = false;
@@ -890,7 +909,7 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
         return;
       }
       if (code !== 0) {
-        const explained = describeFailure?.({ stdout, stderr, code }) ?? null;
+        const explained = describeFailure?.({ stdout, stderr, code, startedAt: runStartedAt }) ?? null;
         reject(
           new Error(
             explained ?? `${providerName} provider failed with code ${code}.${stderr ? ` stderr: ${stderr.trim()}` : ""}`
@@ -910,11 +929,11 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
       drainTimer = setTimeout(() => settle(exitCode), DRAIN_GRACE_MS);
     };
     child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
+      stdout += outDecoder.decode(chunk, { stream: true });
       restartDrain();
     });
     child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
+      stderr += errDecoder.decode(chunk, { stream: true });
       restartDrain();
     });
     child.on("error", (error) => {
@@ -925,9 +944,10 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
       clearTimeout(timer);
       clearTimeout(drainTimer);
       if (error.code === "ENOENT") {
+        const missingCwd = !fs.existsSync(invocation.cwd);
         reject(
           new Error(
-            `Provider CLI not found: ${invocation.command}. Install Antigravity CLI and sign in first.`
+            missingCwd ? `Working directory does not exist: ${invocation.cwd}` : `Provider CLI not found: ${invocation.command}. Install it and sign in first.`
           )
         );
         return;
@@ -942,12 +962,39 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
     child.on("close", (code) => settle(code));
   });
 }
+function extensionFromMediaType(mediaType) {
+  const subtype = mediaType.split("/")[1]?.split("+")[0]?.replace(/[^a-z0-9]/gi, "");
+  return subtype ? subtype.toLowerCase() : "bin";
+}
 const EXT_BY_MIME = {
   "image/png": "png",
   "image/jpeg": "jpg",
   "image/webp": "webp",
   "image/gif": "gif"
 };
+function transcriptBelongsTo(filePath, cwd) {
+  const wanted = path.resolve(cwd);
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return false;
+  }
+  for (const line of raw.split("\n")) {
+    if (!line.includes('"cwd"')) {
+      continue;
+    }
+    try {
+      const recorded = JSON.parse(line).cwd;
+      if (typeof recorded === "string") {
+        const resolved = path.resolve(recorded);
+        return resolved === wanted || resolved.startsWith(`${wanted}${path.sep}`);
+      }
+    } catch {
+    }
+  }
+  return true;
+}
 function forEachJsonLine(filePath, visit) {
   let raw;
   try {
@@ -1007,6 +1054,9 @@ function jsonlAdapter(options) {
     findNewest: (cwd) => {
       let best = null;
       for (const file of listJsonl(dirFor(cwd))) {
+        if (!transcriptBelongsTo(file, cwd)) {
+          continue;
+        }
         const timestamp = newestJsonlTimestamp(file, extractLine);
         if (timestamp !== null && (!best || timestamp > best.timestamp)) {
           best = { ref: jsonlSource(name, file, extractLine), timestamp };
@@ -1016,7 +1066,7 @@ function jsonlAdapter(options) {
     },
     findSession: (cwd, sessionId) => {
       for (const file of listJsonl(dirFor(cwd))) {
-        if (matchesSession(path.basename(file), sessionId)) {
+        if (matchesSession(path.basename(file), sessionId) && transcriptBelongsTo(file, cwd)) {
           return jsonlSource(name, file, extractLine);
         }
       }
@@ -1075,6 +1125,9 @@ const piAdapter = jsonlAdapter({
 function opencodeDbPath() {
   return path.join(os.homedir(), ".local", "share", "opencode", "opencode.db");
 }
+function escapeLikePattern(value) {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
 function opencodeQuery(dbPath, cwd, sessionId) {
   let DatabaseSync;
   try {
@@ -1088,8 +1141,10 @@ function opencodeQuery(dbPath, cwd, sessionId) {
   const db = new DatabaseSync(dbPath, { readOnly: true });
   try {
     const resolved = path.resolve(cwd);
-    const sessionFilter = sessionId ? `AND (session.id = ? OR session.slug = ?)` : `AND (session.directory = ? OR session.directory LIKE ? || '/%' OR ? LIKE session.directory || '/%')`;
-    const params = sessionId ? [sessionId, sessionId] : [resolved, resolved, resolved];
+    const directoryFilter = `(session.directory = ? OR session.directory LIKE ? || '/%' ESCAPE '\\' OR ? LIKE session.directory || '/%' ESCAPE '\\')`;
+    const escaped = escapeLikePattern(resolved);
+    const sessionFilter = sessionId ? `AND ${directoryFilter} AND (session.id = ? OR session.slug = ?)` : `AND ${directoryFilter}`;
+    const params = sessionId ? [resolved, escaped, resolved, sessionId, sessionId] : [resolved, escaped, resolved];
     const rows = db.prepare(
       `SELECT part.data AS data, part.time_created AS time_created, part.session_id AS session_id
                  FROM part
@@ -1182,8 +1237,16 @@ function harnessFromPsTable(psOutput, startPid) {
     if (!proc) {
       return null;
     }
-    for (const token of proc.command.trim().split(/\s+/).slice(0, 8)) {
-      const mapped = HARNESS_BY_BASENAME[path.basename(token)];
+    const tokens = proc.command.trim().split(/\s+/);
+    const candidates = [tokens[0]];
+    if (/^(node|bun|deno)$/.test(path.basename(tokens[0] ?? ""))) {
+      const script = tokens.slice(1).find((token) => !token.startsWith("-"));
+      if (script) {
+        candidates.push(script);
+      }
+    }
+    for (const token of candidates) {
+      const mapped = token ? HARNESS_BY_BASENAME[path.basename(token)] : void 0;
       if (mapped) {
         return mapped;
       }
@@ -1220,26 +1283,29 @@ function detectHarness() {
   return null;
 }
 const ADAPTERS = [claudeAdapter, piAdapter, opencodeAdapter];
-function sourceForExplicitPath(filePath) {
-  if (filePath.endsWith(".db")) {
+function sourceForExplicitPath(filePath, cwd, harness) {
+  const declared = harness && harness !== "none" ? harness : void 0;
+  if (declared === "opencode" || !declared && filePath.endsWith(".db")) {
     return {
       harness: "opencode",
       location: filePath,
-      extract: () => opencodeImagesFromRows(opencodeQuery(filePath, process.cwd()))
+      extract: () => opencodeImagesFromRows(opencodeQuery(filePath, cwd))
     };
   }
-  if (filePath.includes(`${path.sep}.pi${path.sep}`)) {
+  if (declared === "pi" || !declared && filePath.includes(`${path.sep}.pi${path.sep}`)) {
     return jsonlSource("pi", filePath, piExtractLine);
   }
   return jsonlSource("claude-code", filePath, claudeExtractLine);
 }
 function locateSource(cwd, adapters = ADAPTERS) {
   let best = null;
+  const blockers = [];
   for (const adapter of adapters) {
     let candidate = null;
     try {
       candidate = adapter.findNewest(cwd);
-    } catch {
+    } catch (error) {
+      blockers.push(`${adapter.name}: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (candidate && (!best || candidate.timestamp > best.timestamp)) {
       best = candidate;
@@ -1247,25 +1313,31 @@ function locateSource(cwd, adapters = ADAPTERS) {
   }
   if (!best) {
     const dirs = adapters.map((a) => a.describe(cwd)).join(" , ");
+    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.`
+      `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}`
     );
   }
   return best.ref;
 }
 function sourceForSession(cwd, sessionId, adapters = ADAPTERS) {
+  const blockers = [];
   for (const adapter of adapters) {
     try {
       const ref = adapter.findSession(cwd, sessionId);
       if (ref) {
         return ref;
       }
-    } catch {
+    } catch (error) {
+      blockers.push(`${adapter.name}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
   const dirs = adapters.map((a) => a.describe(cwd)).join(" , ");
+  const blocked = blockers.length > 0 ? `
+Blocked: ${blockers.join(" | ")}` : "";
   throw new Error(
-    `No session ${sessionId} with pasted images under this project (looked in: ${dirs}). Check --cwd, or drop --session to auto-locate by newest pasted image.`
+    `No session ${sessionId} with pasted images under this project (looked in: ${dirs}). Check --cwd, or drop --session to auto-locate by newest pasted image.${blocked}`
   );
 }
 function recoverPastedImages(options = {}) {
@@ -1285,7 +1357,7 @@ function recoverPastedImages(options = {}) {
   const adapters = scoped ? ADAPTERS.filter((adapter) => adapter.name === scoped) : ADAPTERS;
   let source = null;
   if (options.transcript) {
-    source = sourceForExplicitPath(options.transcript);
+    source = sourceForExplicitPath(options.transcript, cwd, options.harness);
   } else if (options.session) {
     source = sourceForSession(cwd, options.session, adapters);
   } else {
@@ -1307,14 +1379,22 @@ function recoverPastedImages(options = {}) {
       `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.`
     );
   }
-  fs.mkdirSync(outDir, { recursive: true });
+  fs.mkdirSync(outDir, { recursive: true, mode: 448 });
+  try {
+    fs.chmodSync(outDir, 448);
+  } catch {
+  }
   const picked = all.slice(-count);
   const images = picked.map((image) => {
     const buffer = Buffer.from(image.data, "base64");
     const hash = crypto.createHash("sha256").update(buffer).digest("hex").slice(0, 8);
-    const ext = EXT_BY_MIME[image.mediaType] ?? "png";
+    const ext = EXT_BY_MIME[image.mediaType] ?? extensionFromMediaType(image.mediaType);
     const filePath = path.join(outDir, `paste-${hash}.${ext}`);
-    fs.writeFileSync(filePath, buffer);
+    fs.writeFileSync(filePath, buffer, { mode: 384 });
+    try {
+      fs.chmodSync(filePath, 384);
+    } catch {
+    }
     const recovered = {
       path: filePath,
       mediaType: image.mediaType,
@@ -1332,7 +1412,7 @@ 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("2.7.3");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.7.4");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);

package/package.json

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