@liustack/modlens 3.21.0 → 3.21.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 3.21.1 - 2026-08-19
+
+- **`config use openai constructor` can no longer destroy a key, and hostile hand edits meet one discipline everywhere ([3.21.0 acceptance]).** An independent acceptance run against 3.21.0 found real data loss: the label `constructor` walked the prototype chain, came back as Object's constructor, and emptied the active slot under a success message, destroying an unsaved key with `--discard`. Seven adversarial review rounds then hardened every surface the same hostile input can reach: bundle labels, provider names (`config set constructor.apiKey` used to write the key onto a global object and print success), and the registry all read own properties only; malformed roots, entries, bundles, and field types fail with a fix-or-remove sentence naming the path, at `set`, `save`, `use`, `guards.*`, and a new execute boundary in reads and doctor; and `config show`, built to be pasted into issues, now runs every value through redaction against every known key with no length assumption, while no property name in the view ever carries user data, the structural guarantee a dedicated regression walks and asserts. Two display designs that keyed rows by user data each grew a credential leak during review; the shipped view keeps labels, slot names, and unknown spellings inside redacted values, where they cannot leak or collide.
+- **dsh: a failed image read no longer bills the whole session, and never rewrites history while the outcome stands ([#68](https://github.com/liustack/modlens/issues/68)).** A session that pasted an image the engine happened to fail on paid full price for every request after it: the failure placeholder embedded that attempt's own error text, the cache evicted failures on settle so every step re-ran the engine and rewrote the same message, and the provider's prefix cache missed from that message on. Failure placeholders are now constants per stage, with the attempt's detail in the harness log and no attacker-shaped media type on the wire; failures hold for a 60-second cooldown on the monotonic clock, so a broken engine is probed once per cooldown per attachment and a recovered one moves the text exactly once; the cache key ignores attachment key order; cached blocks are frozen; and one evidence cache serves every wrapper route and auto-read, which used to bypass caching entirely. Eviction went through three designs under adversarial review, each broken by a measured reproduction, and what ships pins every open walk's keys as exact refcounts: within the cap, wire bytes move only when an outcome changes. Thanks to @nanami-0713 for a report that named the mechanism, the reproduction, and the cost curve, and for respecting the no-PR policy while still making the fix easy to verify.
+
 ## 3.21.0 - 2026-08-18
 
 - **Switching OpenAI-compatible gateways no longer costs a key ([#67](https://github.com/liustack/modlens/issues/67)).** The openai slot is the one slot users point at many different gateways, and switching meant overwriting `providers.openai` field by field, with the previous endpoint's key lost unless backed up by hand. `modlens config save openai <label>` snapshots the slot whole under a name; `modlens config use openai <label>` swaps a saved copy back in whole, never merged. A slot that no label holds refuses to be overwritten without `--discard`, so the silent key loss this exists to remove now takes saying so in as many words. The saved section is inert data: resolution, guards, the failover chain, and the environment bindings never read it, the effective view lists labels with keys masked, and older CLI versions carry it through their writes untouched. The issue's own proposal, named provider slots with a type field, was declined with reasons on the thread: it opens the closed provider registry every downstream consumer assumes, and reopens the mistyped-name trap 3.19.0 closed. Per-call routing and a dsh passthrough are likewise declined; endpoint choice stays user-owned configuration.

package/README.md

@@ -34,7 +34,7 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.0`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. Updating is the same command again. The version is named rather than `@latest` on purpose: pnpm 11 holds back releases published in the last 24 hours and resolves the tag against what survives, so `@latest` would install whatever shipped a day ago ([details](docs/harness-setup.md#keeping-it-up-to-date)).
+**🥇 The most capable vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.1`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. Updating is the same command again. The version is named rather than `@latest` on purpose: pnpm 11 holds back releases published in the last 24 hours and resolves the tag against what survives, so `@latest` would install whatever shipped a day ago ([details](docs/harness-setup.md#keeping-it-up-to-date)).
 
 Pasting an image works two ways. **① Just paste.** On a text-only model the pasted image lands as a private temp file and its path enters the composer — the same interaction OpenCode and Pi ship — and the `modlens_read_image` tool takes it from there. **② Pick a `(modlens vision)` entry** in the model selector (it remembers your choice, so once is enough), then paste: the thumbnail stays visible in your message, closer to the Codex app feel, and the image is converted to structured evidence at request time, answered by the same underlying route. The plugin auto-discovers every provider route carrying text-only DeepSeek or GLM models and adds a wrapped entry per route (a stock install gets **`DeepSeek-V4-Flash (modlens vision)`** and **`DeepSeek-V4-Pro (modlens vision)`**; extra routes like opencode-go or zai get their own); the two families' own vision models are excluded automatically. Which paste route applies is the host's per-model call: only a model its metadata positively confirms text-only is taken over, anything unconfirmed is left alone, so vision models keep their native paste ([details](docs/harness-setup.md)).
 

package/README.zh-CN.md

@@ -34,7 +34,7 @@ DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别
 
 ## 亮点
 
-**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.0`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。更新就是再跑一遍同一条命令。这里点名版本号而不用 `@latest` 是有意的：pnpm 11 会扣住最近 24 小时内发布的版本，dist-tag 只在剩下的里面解析，用 `@latest` 装到的会是一天前发布的那个（[细节](docs/harness-setup.zh-CN.md#保持更新)）。
+**🥇 全网最强的 DeepSeek Harness（dsh）外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.1`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。更新就是再跑一遍同一条命令。这里点名版本号而不用 `@latest` 是有意的：pnpm 11 会扣住最近 24 小时内发布的版本，dist-tag 只在剩下的里面解析，用 `@latest` 装到的会是一天前发布的那个（[细节](docs/harness-setup.zh-CN.md#保持更新)）。
 
 DeepSeek Harness 粘贴识图有两种玩法。
 
@@ -69,7 +69,7 @@ agy                                                           # 浏览器完成
 **DeepSeek Harness（dsh）用户不走 skill 流程**，本包就是原生 dsh 插件：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.0
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.1
 ```
 
 装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。

package/dist/main.js

@@ -830,7 +830,7 @@ function tail(text, max = 300) {
 }
 function parseExtraBody(raw, origin) {
   const parsed = parseJsonOrExplain(raw, origin);
-  if (!isPlainObject(parsed)) {
+  if (!isPlainObject$1(parsed)) {
     throw new Error(
       `${origin} must be a JSON object, for example {"thinking":{"type":"disabled"}}`
     );
@@ -854,21 +854,21 @@ function deepMerge(base, overlay) {
   const merged = { ...base };
   for (const [key, value] of Object.entries(overlay)) {
     const current = merged[key];
-    merged[key] = isPlainObject(current) && isPlainObject(value) ? deepMerge(current, value) : value;
+    merged[key] = isPlainObject$1(current) && isPlainObject$1(value) ? deepMerge(current, value) : value;
   }
   return merged;
 }
 function hasPath(value, dottedPath) {
   let cursor = value;
   for (const segment of dottedPath.split(".")) {
-    if (!isPlainObject(cursor) || !Object.hasOwn(cursor, segment)) {
+    if (!isPlainObject$1(cursor) || !Object.hasOwn(cursor, segment)) {
       return false;
     }
     cursor = cursor[segment];
   }
   return true;
 }
-function isPlainObject(value) {
+function isPlainObject$1(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 const TOKEN_SHAPES = [
@@ -1571,7 +1571,7 @@ const PROVIDERS = {
 };
 function resolveProvider(providerName = "antigravity-cli") {
   const normalized = providerName.trim().toLowerCase();
-  const provider = PROVIDERS[normalized];
+  const provider = Object.hasOwn(PROVIDERS, normalized) ? PROVIDERS[normalized] : void 0;
   if (!provider) {
     throw new Error(
       `Unsupported provider: ${providerName}. Available: ${listProviders().join(", ")}`
@@ -1597,9 +1597,8 @@ const ENV_BINDINGS = {
   anthropic: { apiKey: "ANTHROPIC_API_KEY", baseUrl: "ANTHROPIC_BASE_URL" }
 };
 function fileKeysFor(providerName, config2) {
-  const aliases = providerAliases();
-  return Object.keys(config2.providers ?? {}).filter(
-    (key) => (aliases[key] ?? key) === providerName
+  return Object.keys(isPlainObject(config2.providers) ? config2.providers : {}).filter(
+    (key) => foldProviderName(key) === providerName
   );
 }
 function fileSettingsFor(providerName, config2) {
@@ -1608,7 +1607,13 @@ function fileSettingsFor(providerName, config2) {
     ...keys.filter((key) => key !== providerName),
     ...keys.filter((key) => key === providerName)
   ];
-  return Object.assign({}, ...ordered.map((key) => config2.providers?.[key] ?? {}));
+  return Object.assign(
+    {},
+    ...ordered.map((key) => {
+      const entry = config2.providers?.[key];
+      return isPlainObject(entry) ? entry : {};
+    })
+  );
 }
 function envSettingsFor(providerName, env) {
   const settings = {};
@@ -1674,7 +1679,7 @@ function providerConfiguredInFile(providerName, config2) {
 function resolveProviderSettings(providerName, config2, env = process.env) {
   const mentioned = providerConfiguredInFile(providerName, config2);
   const settings = mentioned ? { ...fileSettingsFor(providerName, config2) } : envSettingsFor(providerName, env);
-  if (!settings.proxy && config2.proxy?.trim()) {
+  if (!settings.proxy && typeof config2.proxy === "string" && config2.proxy.trim()) {
     settings.proxy = config2.proxy.trim();
   }
   return settings;
@@ -1721,6 +1726,19 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
     const typedName = dottedKey.slice(0, dot);
     const field = dottedKey.slice(dot + 1);
     const providerName = typedName.trim().toLowerCase();
+    if (config2.providers !== void 0 && !isPlainObject(config2.providers)) {
+      throw new Error(
+        `The "providers" section in ${configPath} is not an object. Fix or remove it, then try again.`
+      );
+    }
+    for (const spelling of fileKeysFor(foldProviderName(providerName), config2)) {
+      const entry = config2.providers?.[spelling];
+      if (entry !== void 0 && !isPlainObject(entry)) {
+        throw new Error(
+          `"providers.${spelling}" in ${configPath} is not an object. Fix or remove it, then try again.`
+        );
+      }
+    }
     try {
       resolveProvider(providerName);
     } catch {
@@ -1731,7 +1749,7 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
       );
     }
     if (field === "structuredOutput") {
-      if ((providerAliases()[providerName] ?? providerName) !== "openai") {
+      if (foldProviderName(providerName) !== "openai") {
         throw new Error(
           `structuredOutput applies to the openai provider only, not ${providerName}.`
         );
@@ -1781,7 +1799,134 @@ function persistConfig(config2, configPath) {
   } catch {
   }
 }
+function assertReadableConfig(config2, configPath = CONFIG_PATH) {
+  const sentence = (path2, what) => new Error(`${path2} in ${configPath} ${what}. Fix or remove it, then try again.`);
+  if (config2.provider !== void 0 && typeof config2.provider !== "string") {
+    throw sentence('"provider"', "is not a string");
+  }
+  if (config2.proxy !== void 0 && typeof config2.proxy !== "string") {
+    throw sentence('"proxy"', "is not a string");
+  }
+  if (config2.reuse !== void 0 && !isPlainObject(config2.reuse)) {
+    throw sentence('"reuse"', "is not an object");
+  }
+  if (config2.providers !== void 0 && !isPlainObject(config2.providers)) {
+    throw sentence('"providers"', "is not an object");
+  }
+  for (const [name, entry] of Object.entries(
+    isPlainObject(config2.providers) ? config2.providers : {}
+  )) {
+    if (!isPlainObject(entry)) {
+      throw sentence(`"providers.${name}"`, "is not an object");
+    }
+    const offence = entryFieldOffence(entry);
+    if (offence !== null) {
+      throw sentence(`"providers.${name}"`, offence);
+    }
+  }
+  if (config2.saved !== void 0 && !isPlainObject(config2.saved)) {
+    throw sentence('"saved"', "is not an object");
+  }
+  if (config2.guards !== void 0) {
+    if (!isPlainObject(config2.guards)) {
+      throw sentence('"guards"', "is not an object");
+    }
+    for (const field of ["denyModels", "allowModels"]) {
+      const value = config2.guards[field];
+      if (value !== void 0 && !Array.isArray(value)) {
+        throw sentence(`"guards.${field}"`, "is not an array");
+      }
+    }
+    const flag = config2.guards.denyWhenUnknown;
+    if (flag !== void 0 && typeof flag !== "boolean") {
+      throw sentence('"guards.denyWhenUnknown"', "is not true or false");
+    }
+  }
+}
+function entryFieldOffence(entry) {
+  for (const field of ["apiKey", "baseUrl", "model", "proxy"]) {
+    if (entry[field] !== void 0 && typeof entry[field] !== "string") {
+      return `has a non-string ${field}`;
+    }
+  }
+  if (entry.extraBody !== void 0 && !isPlainObject(entry.extraBody)) {
+    return "has an extraBody that is not an object";
+  }
+  if (entry.structuredOutput !== void 0 && typeof entry.structuredOutput !== "boolean") {
+    return "has a structuredOutput that is not true or false";
+  }
+  return null;
+}
+function redactValues(value, keys) {
+  const ordered = [...keys].sort((a, b) => b.length - a.length);
+  const scrub = (text) => {
+    let out = text;
+    for (const key of ordered) {
+      if (key.length > 0) {
+        out = out.split(key).join("[redacted]");
+      }
+    }
+    return out;
+  };
+  const walk = (node) => {
+    if (typeof node === "string") return scrub(node);
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === "object") {
+      const out = /* @__PURE__ */ Object.create(null);
+      for (const [key, entry] of Object.entries(node)) {
+        out[key] = walk(entry);
+      }
+      return out;
+    }
+    return node;
+  };
+  return walk(value);
+}
+function knownApiKeys(config2, env = process.env) {
+  const keys = /* @__PURE__ */ new Set();
+  const providersRoot = isPlainObject(config2.providers) ? config2.providers : {};
+  for (const entry of Object.values(providersRoot)) {
+    if (isPlainObject(entry) && typeof entry.apiKey === "string") {
+      keys.add(entry.apiKey);
+    }
+  }
+  for (const bindings of Object.values(ENV_BINDINGS)) {
+    const variable = bindings.apiKey;
+    const value = variable ? env[variable]?.trim() : void 0;
+    if (value) {
+      keys.add(value);
+    }
+  }
+  const savedRoot = isPlainObject(config2.saved) ? config2.saved : {};
+  for (const bundles of Object.values(savedRoot)) {
+    if (!isPlainObject(bundles)) continue;
+    for (const bundle of Object.values(bundles)) {
+      if (isPlainObject(bundle) && typeof bundle.apiKey === "string") {
+        keys.add(bundle.apiKey);
+      }
+    }
+  }
+  return [...keys];
+}
+function bundleFieldOffence(bundle) {
+  const offence = entryFieldOffence(bundle);
+  if (offence !== null) {
+    return offence;
+  }
+  const KNOWN = ["apiKey", "baseUrl", "model", "proxy", "extraBody", "structuredOutput"];
+  if (!KNOWN.some((field) => bundle[field] !== void 0)) {
+    return "holds none of the openai fields, so using it would empty the slot";
+  }
+  return null;
+}
+function foldProviderName(name) {
+  const aliases = providerAliases();
+  return Object.hasOwn(aliases, name) ? aliases[name] : name;
+}
 const SAVED_LABEL = /^[a-z][a-z0-9-]*$/;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function deepEqualJson(a, b) {
   if (a === b) return true;
   if (Array.isArray(a) && Array.isArray(b)) {
@@ -1801,10 +1946,10 @@ function deepEqualJson(a, b) {
 }
 function savedSlotFor(slot) {
   const folded = slot.trim().toLowerCase();
-  const canonical = providerAliases()[folded] ?? folded;
+  const canonical = foldProviderName(folded);
   if (canonical !== "openai") {
     throw new Error(
-      `Only the openai slot has saved copies; "${slot}" does not. It is the one slot users point at many different gateways.`
+      `Saved copies exist only for the openai slot, the one slot users point at many different gateways. "${slot}" has none.`
     );
   }
   return canonical;
@@ -1823,25 +1968,62 @@ function saveProviderBundle(slot, label, configPath = CONFIG_PATH) {
       `Nothing to save: the ${canonical} slot is empty in ${configPath}. Configure it first (modlens config set openai.baseUrl <url>).`
     );
   }
+  if (config2.saved !== void 0 && !isPlainObject(config2.saved)) {
+    throw new Error(
+      `The "saved" section in ${configPath} is not an object. Fix or remove it, then save again.`
+    );
+  }
   config2.saved ??= {};
+  if (config2.saved[canonical] !== void 0 && !isPlainObject(config2.saved[canonical])) {
+    throw new Error(
+      `"saved.${canonical}" in ${configPath} is not an object. Fix or remove it, then save again.`
+    );
+  }
   config2.saved[canonical] ??= {};
+  const replaced = Object.hasOwn(config2.saved[canonical], label);
   config2.saved[canonical][label] = snapshot;
   persistConfig(config2, configPath);
+  return replaced;
 }
 function useProviderBundle(slot, label, discard = false, configPath = CONFIG_PATH) {
   const canonical = savedSlotFor(slot);
   const config2 = loadConfigFile(configPath);
-  const bundle = config2.saved?.[canonical]?.[label];
-  if (bundle === void 0) {
-    const known = Object.keys(config2.saved?.[canonical] ?? {}).sort();
+  if (config2.providers !== void 0 && !isPlainObject(config2.providers)) {
+    throw new Error(
+      `The "providers" section in ${configPath} is not an object. Fix or remove it, then try again.`
+    );
+  }
+  if (config2.saved !== void 0 && !isPlainObject(config2.saved)) {
+    throw new Error(
+      `The "saved" section in ${configPath} is not an object. Fix or remove it, then try again.`
+    );
+  }
+  if (config2.saved?.[canonical] !== void 0 && !isPlainObject(config2.saved[canonical])) {
+    throw new Error(
+      `"saved.${canonical}" in ${configPath} is not an object. Fix or remove it, then try again.`
+    );
+  }
+  const bundles = config2.saved?.[canonical] ?? {};
+  const known = Object.keys(bundles).sort();
+  if (!Object.hasOwn(bundles, label)) {
     throw new Error(
       known.length === 0 ? `No saved copies exist for ${canonical} yet. Save the current one first: modlens config save openai <label>.` : `No saved copy named "${label}". Saved: ${known.join(", ")}.`
     );
   }
+  const bundle = bundles[label];
+  if (!isPlainObject(bundle)) {
+    throw new Error(
+      `The saved copy "${label}" in ${configPath} is not an object (found ${bundle === null ? "null" : Array.isArray(bundle) ? "an array" : typeof bundle}). Fix or remove it under "saved.${canonical}.${label}", then try again.`
+    );
+  }
+  const offence = bundleFieldOffence(bundle);
+  if (offence !== null) {
+    throw new Error(
+      `The saved copy "${label}" in ${configPath} ${offence}. Fix it under "saved.${canonical}.${label}", then try again.`
+    );
+  }
   const current = fileSettingsFor(canonical, config2);
-  const currentSaved = Object.keys(current).length === 0 || Object.values(config2.saved?.[canonical] ?? {}).some(
-    (entry) => deepEqualJson(entry, current)
-  );
+  const currentSaved = Object.keys(current).length === 0 || Object.values(bundles).some((entry) => deepEqualJson(entry, current));
   if (!currentSaved && !discard) {
     throw new Error(
       `The current ${canonical} settings are not saved under any label and would be lost. Save them first (modlens config save openai <label>) or pass --discard.`
@@ -1855,6 +2037,11 @@ function useProviderBundle(slot, label, discard = false, configPath = CONFIG_PAT
   persistConfig(config2, configPath);
 }
 function setGuardsValue(config2, field, value) {
+  if (config2.guards !== void 0 && !isPlainObject(config2.guards)) {
+    throw new Error(
+      'The "guards" section in the config file is not an object. Fix or remove it, then try again.'
+    );
+  }
   if (field === "denyModels" || field === "allowModels") {
     if (value.trim() === "") {
       delete config2.guards?.[field];
@@ -1895,7 +2082,9 @@ const CONFIG_TEMPLATE = {
 };
 function initConfigFile(configPath = CONFIG_PATH, force = false) {
   if (!force && fs.existsSync(configPath)) {
-    throw new Error(`${configPath} already exists. Use --force to overwrite.`);
+    throw new Error(
+      `${configPath} already exists. Use --force to overwrite (that also deletes every saved gateway copy under "saved").`
+    );
   }
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, `${JSON.stringify(CONFIG_TEMPLATE, null, 2)}
@@ -1906,34 +2095,57 @@ function initConfigFile(configPath = CONFIG_PATH, force = false) {
   }
 }
 function renderEffectiveConfig(config2, env = process.env) {
-  const aliases = providerAliases();
+  const providersRoot = isPlainObject(config2.providers) ? config2.providers : void 0;
+  const canonicalNames = new Set(listProviders());
   const providerNames = new Set(
-    Object.keys(config2.providers ?? {}).map((key) => aliases[key] ?? key)
+    Object.keys(providersRoot ?? {}).map((key) => foldProviderName(key)).filter((name) => canonicalNames.has(name))
   );
   for (const [providerName, bindings] of Object.entries(ENV_BINDINGS)) {
     if (Object.values(bindings).some((variable) => env[variable]?.trim())) {
       providerNames.add(providerName);
     }
   }
-  const providers = {};
+  const providers = /* @__PURE__ */ Object.create(null);
+  const notes = [];
+  for (const [rawName, entry] of Object.entries(providersRoot ?? {})) {
+    if (entry !== void 0 && !isPlainObject(entry)) {
+      notes.push(`providers.${rawName} is not an object; fix or remove it`);
+      continue;
+    }
+    if (!canonicalNames.has(foldProviderName(rawName))) {
+      notes.push(`providers.${rawName} is not a known provider; runs ignore it`);
+    }
+  }
+  if (config2.providers !== void 0 && providersRoot === void 0) {
+    providers["(malformed)"] = {
+      providers: 'the "providers" section is not an object; fix or remove it'
+    };
+  }
   for (const name of [...providerNames].sort()) {
     const fileSettings = fileSettingsFor(name, config2);
     const mentioned = providerConfiguredInFile(name, config2);
     const effective2 = mentioned ? fileSettings : envSettingsFor(name, env);
     const source = mentioned ? "file" : "env";
     const fields = {};
+    const entryKey = typeof effective2.apiKey === "string" ? effective2.apiKey : void 0;
+    const guard = (shown) => redactSecrets(shown, [entryKey]);
     for (const field of STRING_FIELDS) {
       const value = effective2[field];
-      if (value !== void 0) {
-        const shown = field === "apiKey" ? maskKey(value) : field === "proxy" ? maskUrlCredentials(value) : value;
-        fields[field] = `${shown} (${source})`;
+      if (value === void 0) {
+        continue;
+      }
+      if (typeof value !== "string") {
+        fields[field] = `(malformed: not a string) (${source})`;
+        continue;
       }
+      const shown = field === "apiKey" ? maskKey(value) : field === "proxy" ? maskUrlCredentials(guard(value)) : guard(value);
+      fields[field] = `${shown} (${source})`;
     }
     if (fileSettings.structuredOutput !== void 0) {
       fields.structuredOutput = `${fileSettings.structuredOutput} (file)`;
     }
     if (fileSettings.extraBody !== void 0) {
-      fields.extraBody = `${JSON.stringify(fileSettings.extraBody)} (file)`;
+      fields.extraBody = `${guard(JSON.stringify(fileSettings.extraBody))} (file)`;
     }
     if (Object.keys(fields).length > 0 || mentioned) {
       providers[name] = fields;
@@ -1942,32 +2154,51 @@ function renderEffectiveConfig(config2, env = process.env) {
   const effective = {
     providers
   };
-  const savedView = {};
-  for (const [slot, bundles] of Object.entries(config2.saved ?? {})) {
+  const savedRows = [];
+  const savedRoot = config2.saved;
+  if (savedRoot !== void 0 && !isPlainObject(savedRoot)) {
+    savedRows.push('the "saved" section is not an object; fix or remove it');
+  }
+  for (const [slot, bundles] of Object.entries(isPlainObject(savedRoot) ? savedRoot : {})) {
+    if (!isPlainObject(bundles)) {
+      savedRows.push(`saved.${slot} is not an object; fix or remove it`);
+      continue;
+    }
     for (const label of Object.keys(bundles).sort()) {
       const bundle = bundles[label];
+      if (!isPlainObject(bundle)) {
+        savedRows.push(`${slot}/${label}: (malformed: not an object; fix or remove it)`);
+        continue;
+      }
       const parts = [
-        bundle.model,
-        bundle.baseUrl,
-        bundle.apiKey !== void 0 ? `key ${maskKey(bundle.apiKey)}` : "no key"
+        typeof bundle.model === "string" ? bundle.model : void 0,
+        typeof bundle.baseUrl === "string" ? bundle.baseUrl : void 0,
+        bundle.apiKey === void 0 ? "no key" : typeof bundle.apiKey === "string" ? `key ${maskKey(bundle.apiKey)}` : "key (malformed: not a string)"
       ].filter(Boolean);
-      savedView[slot] ??= {};
-      savedView[slot][label] = parts.join(" @ ");
+      savedRows.push(`${slot}/${label}: ${parts.join(" @ ")}`);
     }
   }
-  if (Object.keys(savedView).length > 0) {
-    effective.saved = savedView;
+  if (savedRows.length > 0) {
+    effective.saved = savedRows;
   }
-  if (config2.provider?.trim()) {
+  if (typeof config2.provider === "string" && config2.provider.trim()) {
     effective.provider = config2.provider.trim();
+  } else if (config2.provider !== void 0 && typeof config2.provider !== "string") {
+    effective.provider = "(malformed: not a string)";
   }
-  if (config2.proxy?.trim()) {
+  if (config2.proxy !== void 0 && typeof config2.proxy !== "string") {
+    effective.proxy = "(malformed: not a string)";
+  } else if (config2.proxy?.trim()) {
     effective.proxy = `${maskUrlCredentials(config2.proxy.trim())} (file)`;
   } else if (env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy) {
     const raw = env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy;
     effective.proxy = `${maskUrlCredentials(raw)} (env)`;
   }
-  if (config2.guards) {
+  if (config2.guards !== void 0 && !isPlainObject(config2.guards)) {
+    effective.guards = {
+      "(malformed)": 'the "guards" section is not an object; fix or remove it'
+    };
+  } else if (config2.guards) {
     const guards = {};
     if (config2.guards.denyModels !== void 0) {
       guards.denyModels = `${JSON.stringify(config2.guards.denyModels)} (file)`;
@@ -1982,15 +2213,31 @@ function renderEffectiveConfig(config2, env = process.env) {
       effective.guards = guards;
     }
   }
-  if (config2.reuse && Object.keys(config2.reuse).length > 0) {
-    effective.reuse = Object.fromEntries(
-      Object.entries(config2.reuse).map(([harness, granted]) => [
-        harness,
-        `${granted} (file)`
-      ])
-    );
+  if (config2.reuse !== void 0 && !isPlainObject(config2.reuse)) {
+    effective.reuse = {
+      "(malformed)": 'the "reuse" section is not an object; fix or remove it'
+    };
+  } else if (config2.reuse && Object.keys(config2.reuse).length > 0) {
+    const reuse = {};
+    for (const harness of REUSE_HARNESSES) {
+      const granted = config2.reuse[harness];
+      if (granted !== void 0) {
+        reuse[harness] = `${granted} (file)`;
+      }
+    }
+    for (const stranger of Object.keys(config2.reuse).filter(
+      (key) => !REUSE_HARNESSES.includes(key)
+    )) {
+      notes.push(`reuse.${stranger} is not a known harness; runs ignore it`);
+    }
+    if (Object.keys(reuse).length > 0) {
+      effective.reuse = reuse;
+    }
+  }
+  if (notes.length > 0) {
+    effective.notes = notes;
   }
-  return JSON.stringify(effective, null, 2);
+  return JSON.stringify(redactValues(effective, knownApiKeys(config2, env)), null, 2);
 }
 function maskKey(key) {
   if (key.length <= 8) {
@@ -3163,6 +3410,7 @@ async function analyzeImage(options) {
     validateInputFile(resolvedInput.source);
   }
   const config2 = options.config ?? loadConfigFile();
+  assertReadableConfig(config2);
   const chain = options.provider ? [resolveProvider(options.provider)] : options.providerBin ? [resolveProvider("antigravity-cli")] : composeChain(resolvedInput.kind, config2, options.autoOptions);
   const named = options.provider ?? config2.provider?.trim();
   if (named) {
@@ -4365,6 +4613,7 @@ function inspectConfigFile(configPath) {
 function buildDoctorReport(input) {
   const env = input.env ?? process.env;
   const configPath = input.configPath ?? CONFIG_PATH;
+  assertReadableConfig(input.config, configPath);
   const harnessDetection = detectHarnessDetailed();
   const guardDetection = detectActiveModel({
     cwd: process.cwd(),
@@ -4746,7 +4995,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.21.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.21.1");
 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"}}'`
@@ -4856,7 +5105,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.21.0"
+      version: "3.21.1"
     });
     const output = options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report);
     process.stdout.write(`${output}
@@ -4895,9 +5144,12 @@ config.command("save <slot> <label>").description(
   "Snapshot a provider slot under a label (openai only), so switching gateways never loses a key"
 ).action((slot, label) => {
   try {
-    saveProviderBundle(slot, label);
-    process.stdout.write(`Saved the ${slot} slot as "${label}" in ${CONFIG_PATH}
-`);
+    const replaced = saveProviderBundle(slot, label);
+    process.stdout.write(
+      replaced ? `Saved the ${slot} slot as "${label}", replacing the previous snapshot (${CONFIG_PATH})
+` : `Saved the ${slot} slot as "${label}" in ${CONFIG_PATH}
+`
+    );
   } catch (error) {
     process.stderr.write(
       `Error: ${error instanceof Error ? error.message : String(error)}

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.21.0
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.1
 ```
 
 This registers a `modlens_read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin keeps its touch small (raw tool registration, the llm adapter surface for the vision variants, the attachment reader, and one agent pre-step hook) and degrades loudly if any of them moves.
@@ -81,7 +81,7 @@ modlens ships often, and both install shapes freeze at whatever version they
 got. On dsh, re-run the install with the version named:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.1
 ```
 
 `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.21.0
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.21.1
 ```
 
 这会注册一个 `modlens_read_image` 工具，它的 schema 随每次请求抵达模型（不靠触发启发式），运行同一个包里自带的 modlens CLI，并把结构化证据作为工具的标准 JSON 输出返回。引擎、复用授权和 guard 规则仍在 `~/.modlens/config.json` 里，与其他所有 harness 共享。dsh 还在开发者预览阶段，插件接口可能变化。这个插件刻意保持很小的接触面（原生工具注册、视觉变体所用的 llm 适配层、附件读取器，以及一个 agent 执行前钩子），其中任何一处变动，它都会大声报错而不是无声退化。
@@ -71,7 +71,7 @@ dsh 的网页用户面前没有终端，所以引擎设置有一张卡片，在*
 modlens 发布很频繁，而两种安装形态都会冻结在装进来的那个版本上。dsh 上重跑一遍安装即可，版本号要点名：
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.1
 ```
 
 `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.21.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.1
 ```
 
 `npm view @liustack/modlens version` prints the current one. pnpm 11 installs a named
@@ -178,7 +178,7 @@ file:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.21.0'
+  - '@liustack/modlens@3.21.1'
 ```
 
 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.21.0
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.1
 ```
 
 `npm view @liustack/modlens version` 可以查到当前版本号。pnpm 11 会装上被点名的版本，11.1.3 起还会把它作为一条已批准的例外写进该 profile 的 `pnpm-workspace.yaml`，其余所有包和 modlens 以后的版本仍然留在窗口后面。
@@ -153,7 +153,7 @@ npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@3.21.0
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@liustack/modlens@3.21.0'
+  - '@liustack/modlens@3.21.1'
 ```
 
 或者只为这一条命令解除冷静期，注意它解除的是这条命令解析到的所有包，不只 modlens：

package/dsh/index.js

@@ -36,11 +36,16 @@ export const MEDIA_EXT = {
 }
 
 export function apply(ctx, config = {}) {
+  // One evidence cache for the whole plugin: every wrapper route and the
+  // auto-read path share it, so the same pasted attachment is read once,
+  // 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()
   // 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.
   if (config.autoRead === true) {
-    registerAutoRead(ctx)
+    registerAutoRead(ctx, evidenceCache)
   }
   // The provider ids this plugin registered itself. The takeover verdict has
   // to skip them: our wrapper models are synthetic twins of upstream ones,
@@ -50,7 +55,7 @@ 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)
+    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
@@ -541,7 +546,7 @@ function restoreUpstreamSource(messages, wrapperId, upstream) {
   return changed ? out : messages
 }
 
-function registerVisionProvider(ctx, config, ownProviders) {
+function registerVisionProvider(ctx, config, ownProviders, evidenceCache) {
   // Wrap only the text-only members of these families. Their own vision
   // models (present or future: deepseek-vl/ocr/janus, glm-4.5v, glm-5v-...)
   // need no bridge and are excluded by name and by declared modality.
@@ -640,7 +645,7 @@ function registerVisionProvider(ctx, config, ownProviders) {
             yield* ctx.llm.stream({ ...options, provider: upstream, messages })
           })()
         },
-        evidenceCache: new Map(),
+        evidenceCache,
       })
       registrations.set(upstream, { providerId, registration, state })
       // Trusted as ours only on a registration this call actually made. A
@@ -908,57 +913,182 @@ function registerVisionProvider(ctx, config, ownProviders) {
   }
 }
 
-// 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
+// The same pasted attachment rides every later step of its session, and the
+// provider caches by prefix, so what this cache protects is not just the
+// engine bill but the BYTES of the rewritten history: a message whose text
+// changes between steps busts the provider's context cache for everything
+// after it (issue #68). So it stores promises (concurrent readers join the
+// first run), keeps successes for good, and holds failures for a cooldown
+// instead of evicting them on settle: a broken engine is probed once per
+// cooldown per attachment rather than once per step, the placeholder text is
+// byte-stable while the outcome is unchanged, and the first step after the
+// cooldown retries, so a fixed engine is picked up without a restart. It
+// caps itself LRU-style so a long-lived Web profile cannot hoard evidence
+// 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()
 
-function cachedEvidence(ctx, adapter, block) {
-  const key = JSON.stringify(block.attachment ?? block)
+/**
+ * A cache key that survives replay: the same attachment serialized with a
+ * different key order used to miss its own entry, re-run the engine, and
+ * rewrite the history with a fresh reading (issue #68).
+ */
+function evidenceKey(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(evidenceKey).join(',')}]`
+  const keys = Object.keys(value).sort()
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${evidenceKey(value[key])}`).join(',')}}`
+}
+
+function cachedEvidence(ctx, adapter, block, walk) {
+  const key = evidenceKey(block.attachment ?? block)
+  // Everything the current walk touches is pinned for the walk's duration:
+  // eviction picks victims outside the union of every open walk, or nothing.
+  walk?.pin(key)
   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
+    const cooling = typeof hit === 'object' && hit !== null && 'retryAfter' in hit
+    if (!cooling || monotonicNow() < hit.retryAfter) {
+      // Refresh recency: Map iteration order is insertion order.
+      adapter.evidenceCache.delete(key)
+      adapter.evidenceCache.set(key, hit)
+      return cooling ? Promise.resolve(hit.block) : hit
+    }
+    // Cooldown over: fall through into one fresh probe.
   }
   // 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.
+      // Only replace 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)
+        adapter.evidenceCache.set(key, {
+          retryAfter: monotonicNow() + EVIDENCE_FAILURE_COOLDOWN_MS,
+          block: evidence.block,
+        })
       }
       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 {
+      // the cache forever. Same stable text as the engine stage: the detail
+      // belongs in the harness log, never in the wire history.
+      const block = Object.freeze({
         type: 'text',
-        text: `[A pasted image could not be read by modlens: ${
-          error instanceof Error ? error.message.slice(0, 300) : String(error)
-        }]`,
+        text: FAILURE_TEXTS.engine,
+      })
+      if (adapter.evidenceCache.get(key) === pending) {
+        adapter.evidenceCache.set(key, {
+          retryAfter: monotonicNow() + EVIDENCE_FAILURE_COOLDOWN_MS,
+          block,
+        })
       }
+      return block
     },
   )
   adapter.evidenceCache.set(key, pending)
-  while (adapter.evidenceCache.size > EVIDENCE_CACHE_LIMIT) {
-    adapter.evidenceCache.delete(adapter.evidenceCache.keys().next().value)
-  }
+  trimEvidenceCache(adapter.evidenceCache)
   return pending
 }
 
+/**
+ * Overflow evicts the least-recently-used entry OUTSIDE the current walk's
+ * working set, and nothing when the whole cache IS the working set.
+ *
+ * Both naive policies fail a real session shape. Oldest-first thrashes a
+ * front-to-back history walk once it passes the cap (the 257th attachment
+ * evicts the 1st, whose miss next step evicts the 2nd, and so on: the #68
+ * retry storm wearing a cap). Newest-first survives that but starves a NEW
+ * session on a long-lived profile: the cache sits full of a previous
+ * session's entries, every new attachment evicts the previous new one, and
+ * the storm returns with the old entries pinned in place forever.
+ *
+ * Pinning the walk resolves both. A new session's working set evicts stale
+ * entries one by one, in LRU order, and resides in full; a single history
+ * larger than the cap keeps everything it is walking (the cap goes soft for
+ * the walk's duration, bounded by that history's own length) and is stable
+ * again on the next step. The remaining honesty: an entry genuinely evicted
+ * and later re-read by a healthy engine may be worded differently, so bytes
+ * can move with the outcome unchanged; the cap exists so a long-lived Web
+ * profile cannot hoard evidence forever.
+ */
+// Active pins per cache, as exact refcounts: victim selection must see EVERY
+// walk's pins, or two interleaved sessions on the shared Map evict each
+// other's in-flight entries and the full-thrash storm returns with company.
+// Refcounts rather than a set of sets, so the union is exact (two walks
+// pinning the same keys is one union, not a doubled sum) and every check is
+// O(1). WeakMap so a cache that dies takes its registry with it.
+const ACTIVE_PINS = new WeakMap()
+
+function activePinsFor(cache) {
+  let counts = ACTIVE_PINS.get(cache)
+  if (!counts) {
+    counts = new Map()
+    ACTIVE_PINS.set(cache, counts)
+  }
+  return counts
+}
+
+/**
+ * Open one walk over a cache: everything the walk pins stays unevictable
+ * until end() runs, whichever walk a trim happens under. Ending the walk
+ * releases its share of the pins; entries above the cap then linger until
+ * the next miss trims them, which is the stability-over-punctuality trade
+ * the cap makes on purpose.
+ */
+export function beginEvidenceWalk(cache) {
+  const counts = activePinsFor(cache)
+  const mine = new Set()
+  return {
+    pin: (key) => {
+      if (mine.has(key)) return
+      mine.add(key)
+      counts.set(key, (counts.get(key) ?? 0) + 1)
+    },
+    end: () => {
+      for (const key of mine) {
+        const left = (counts.get(key) ?? 1) - 1
+        if (left <= 0) {
+          counts.delete(key)
+        } else {
+          counts.set(key, left)
+        }
+      }
+      mine.clear()
+    },
+  }
+}
+
+export function trimEvidenceCache(cache) {
+  const counts = ACTIVE_PINS.get(cache)
+  while (cache.size > EVIDENCE_CACHE_LIMIT) {
+    // Exact union early-out: when every key in the cache is pinned by some
+    // open walk, a scan would find nothing; counts.size is the union's true
+    // cardinality, so overlapping walks cannot inflate it.
+    if (counts !== undefined && counts.size >= cache.size) {
+      return
+    }
+    let victim
+    for (const key of cache.keys()) {
+      if (counts === undefined || !counts.has(key)) {
+        victim = key
+        break
+      }
+    }
+    if (victim === undefined) {
+      return
+    }
+    cache.delete(victim)
+  }
+}
+
 /**
  * Wait on a shared promise without inheriting its lifetime: the caller's
  * abort rejects THIS wait immediately, while the underlying read keeps
@@ -1017,15 +1147,23 @@ async function convertBlocks(blocks, convertOne) {
 
 async function convertImagesToEvidence(ctx, messages, signal, adapter) {
   const out = []
-  for (const message of messages) {
-    if (!contentHasImage(message.content)) {
-      out.push(message)
-      continue
+  // One walk per conversion: its pins are visible to every trim on the
+  // shared cache until end(), so concurrent sessions cannot evict each
+  // other's in-flight work.
+  const walk = beginEvidenceWalk(adapter.evidenceCache)
+  try {
+    for (const message of messages) {
+      if (!contentHasImage(message.content)) {
+        out.push(message)
+        continue
+      }
+      const content = await convertBlocks(message.content, (block) =>
+        abortableWait(cachedEvidence(ctx, adapter, block, walk), signal),
+      )
+      out.push({ ...message, content })
     }
-    const content = await convertBlocks(message.content, (block) =>
-      abortableWait(cachedEvidence(ctx, adapter, block), signal),
-    )
-    out.push({ ...message, content })
+  } finally {
+    walk.end()
   }
   return out
 }
@@ -1038,7 +1176,7 @@ async function convertImagesToEvidence(ctx, messages, signal, adapter) {
  * injectors) see and shape the same final message set; a failed read degrades
  * to an explanatory text block instead of rejecting the step.
  */
-function registerAutoRead(ctx) {
+function registerAutoRead(ctx, evidenceCache) {
   ctx.on('agent/pre-step', async (payload, next) => {
     const decision = await next()
     if (decision.kind !== 'enter') {
@@ -1048,32 +1186,63 @@ function registerAutoRead(ctx) {
       return decision
     }
     const messages = []
-    for (const message of decision.messages) {
-      if (!contentHasImage(message.content)) {
-        messages.push(message)
-        continue
+    // One walk per pre-step, spanning every message in it; pins are visible
+    // to every trim on the shared cache until the walk ends.
+    const walk = beginEvidenceWalk(evidenceCache)
+    try {
+      for (const message of decision.messages) {
+        if (!contentHasImage(message.content)) {
+          messages.push(message)
+          continue
+        }
+        const content = await convertBlocks(message.content, (block) =>
+          // The same cache the wrapper routes use: auto-read used to re-read
+          // every image on every step, healthy engine or not (issue #68).
+          abortableWait(cachedEvidence(ctx, { evidenceCache }, block, walk), payload.signal),
+        )
+        messages.push({ ...message, content })
       }
-      const content = await convertBlocks(
-        message.content,
-        async (block) => (await readImageBlock(ctx, block, payload.signal)).block,
-      )
-      messages.push({ ...message, content })
+    } finally {
+      walk.end()
     }
     return { kind: 'enter', messages }
   })
 }
 
+/**
+ * The wire history must not change bytes unless the outcome changed, so a
+ * failure's placeholder is a constant per failure stage, never the attempt's
+ * own error text: the same broken engine words its failures differently on
+ * every try, and each wording rewrote the history and busted the provider's
+ * prefix cache for the rest of the session (issue #68). The attempt's detail
+ * goes to the harness log, which never rides a request.
+ */
+const FAILURE_TEXTS = {
+  store:
+    '[A pasted image could not be read: the attachment store did not return it. Tell the user, and suggest running `npx @liustack/modlens doctor`.]',
+  media:
+    '[A pasted image could not be read: its media type is not supported. Tell the user, and suggest running `npx @liustack/modlens doctor`.]',
+  engine:
+    '[A pasted image could not be read: the vision engine failed. Tell the user, and suggest running `npx @liustack/modlens doctor`.]',
+}
+
 /**
  * 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).
+ * what a failure means (the pre-step keeps the step going, the cache holds
+ * it only for a cooldown).
  */
 async function readImageBlock(ctx, block, signal) {
   const { mkdtemp, rm, writeFile } = await import('node:fs/promises')
   const { tmpdir } = await import('node:os')
   const { join } = await import('node:path')
   let dir
+  // Which stage failed decides the (constant) placeholder text below. Even
+  // the media stage carries no variable part: the type string arrives from
+  // paste metadata and replayed content, so it is attacker-shaped, and an
+  // unbounded newline-carrying value on the wire is a fake turn boundary.
+  // The concrete type goes to the harness log with the rest of the detail.
+  let stage = 'store'
   try {
     // StoredImageAttachment carries { ref, data: Uint8Array }; the media type
     // rides the reference (verified against dsh attachment/src/types.ts).
@@ -1088,8 +1257,10 @@ async function readImageBlock(ctx, block, signal) {
     if (!ext) {
       // Refusing beats disguising: a fake .png suffix would make the CLI (and
       // the provider behind it) judge mislabelled bytes.
+      stage = 'media'
       throw new Error(`unsupported pasted media type ${mediaType ?? '(none declared)'}`)
     }
+    stage = 'engine'
     dir = await mkdtemp(join(tmpdir(), 'modlens-dsh-'))
     const file = join(dir, `paste${ext}`)
     await writeFile(file, Buffer.from(stored.data), { mode: 0o600 })
@@ -1105,20 +1276,22 @@ async function readImageBlock(ctx, block, signal) {
     const parsed = JSON.parse(stdout)
     return {
       ok: true,
-      block: {
+      // Frozen: the same object rides every later step from the cache, and a
+      // downstream listener mutating it would silently rewrite history.
+      block: Object.freeze({
         type: 'text',
         text: `[Pasted image, read by the modlens vision bridge]\n${renderEvidence(parsed.result)}`,
-      },
+      }),
     }
   } catch (error) {
+    const detail = error instanceof Error ? error.message.slice(0, 300) : String(error)
+    console.error(`[modlens] image read failed (${stage}): ${detail}`)
     return {
       ok: false,
-      block: {
+      block: Object.freeze({
         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\`.]`,
-      },
+        text: FAILURE_TEXTS[stage],
+      }),
     }
   } finally {
     if (dir) {

package/package.json

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

package/skills/modlens/SKILL.md

@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.21.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.21.1):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.21.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.21.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.21.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.21.1: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.21.1 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.21.1 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the pin and the diagnostic fields.

package/skills/modlens/references/configure.md

@@ -19,13 +19,18 @@ modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model
 
 ## The file's exact shape
 
-Everything lives under five top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
+Everything lives under six top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
 
 ```json
 {
   "provider": "gemini-api",
   "proxy": "http://127.0.0.1:7890",
   "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
+  "saved": {
+    "openai": {
+      "dashscope": { "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-...", "model": "qwen3-vl-plus" }
+    }
+  },
   "guards": {
     "allowModels": ["deepseek-v4-*", "glm-5.*", "minimax-m2.5*", "qwen3-coder*"],
     "denyModels": ["glm-*v*", "deepseek-vl*"],

package/skills/modlens/references/configure.zh-CN.md

@@ -19,13 +19,18 @@ modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、mo
 
 ## 配置文件的完整形状
 
-所有内容都在五个顶层键之下，全部可选。下面的示例一次性展示了所有支持的键和字段（真实文件只需要写你用到的部分）。文件不存在就全用默认值。provider 的设置放在 `providers.<name>` 下面，不在顶层，手工编辑最常犯的就是这个错。
+所有内容都在六个顶层键之下，全部可选。下面的示例一次性展示了所有支持的键和字段（真实文件只需要写你用到的部分）。文件不存在就全用默认值。provider 的设置放在 `providers.<name>` 下面，不在顶层，手工编辑最常犯的就是这个错。
 
 ```json
 {
   "provider": "gemini-api",
   "proxy": "http://127.0.0.1:7890",
   "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
+  "saved": {
+    "openai": {
+      "dashscope": { "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-...", "model": "qwen3-vl-plus" }
+    }
+  },
   "guards": {
     "allowModels": ["deepseek-v4-*", "glm-5.*", "minimax-m2.5*", "qwen3-coder*"],
     "denyModels": ["glm-*v*", "deepseek-vl*"],
@@ -62,6 +67,7 @@ modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、mo
 - `providers.<name>.<field>`：共六个字段，`apiKey`、`baseUrl`、`model`、`proxy`、`extraBody`、`structuredOutput`（仅 openai 路线）。每个 provider 条目都可选，条目里的每个字段也都可选。别名键同样会被读取（存在 `gemini` 下的设置在解析到 `gemini-api` 时也能找到），冲突时标准键胜出。
 - `providers.<name>.extraBody`：一个 JSON 对象，合并进 API provider（`gemini-api`、`openai`、`anthropic`）的请求体，用来传厂商有而 modlens 没有对应参数的开关。最常见的用途是关掉思考，见下文小节。嵌套对象逐键合并，所以加一个开关不会动到该块里的其他内容。承载图片、提示词和各路线自身强制机制的字段会被拒绝，报错会点名该字段。`openai` 路线上的 `response_format` 不在此列：在那里设置它就是有意替换掉 modlens 本来会发的那份 schema。三个 CLI provider 不发请求体，所以在 `antigravity-cli`、`claude-cli` 或 `kimi-cli` 上运行时它会被忽略，并在 `meta.warnings` 里说明。
 - `providers.openai.structuredOutput`：设为 `true` 时，让 OpenAI 兼容网关自己强制执行视觉契约，以 `response_format: json_schema` 的严格形式发出。默认关闭，因为不支持结构化输出的网关会对这个字段返回 400。你在 `extraBody` 里设的 `response_format` 优先级更高。
+- `saved.openai.<标签>`：openai 槽的命名存档，只有 `modlens config save openai <标签>` 写入、`modlens config use openai <标签>` 整包换入。切换网关不再丢上一个端点的 key：`use` 拒绝覆盖没有任何标签保存过的活跃槽（`--discard` 表示明确放弃）。解析、guard、failover、环境变量规则都不读这个区，活跃槽始终是唯一生效的 openai 路由。
 - `guards`：调用 guard，给在同一个客户端里既跑纯文本模型又跑视觉模型的人用。两个列表都放 glob 模式（支持 `*` 和 `?`，不区分大小写，同时匹配模型名和 `provider/model`），用 `modlens config set guards.denyModels '["gemini-3*"]'` 或 `guards.allowModels` 设置（JSON 数组或逗号分隔的列表都行，传空则清除）。两种写法表达同一个意图，选列表更短的那种：
   - 只用 `denyModels`：除了列出的视觉模型，其余全部运行引擎。适合你接入的模型大多是纯文本的情况。
   - `allowModels` 非空（白名单模式）：只有列出的模型运行引擎，其他所有已识别的模型一律拒绝。适合 2026 年的实际格局，纯文本模型才是那份短名单。deny 模式仍然优先于 allow 匹配，所以宽泛的 allow 可以把视觉变体剔出去，正如上面的示例：`glm-5.*` 放行文本系列，`glm-*v*` 抓住 `glm-5v-turbo`。allow 模式要锚定得紧一些（写 `deepseek-v4-*` 而不是 `deepseek*`），这样厂商下一代多模态型号会自动掉出名单，等你检查过再上场。

package/skills/modlens/references/runtime.md

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