claude-code-cache-fix 3.2.0 → 3.3.0

package/README.ko.md

@@ -254,6 +254,38 @@ export CACHE_FIX_IMAGE_KEEP_LAST=3
 
 최근 3개 사용자 메시지의 이미지를 유지하고 이전 것은 텍스트 자리 표시자로 대체합니다. `tool_result` 블록만 대상이며, 사용자가 직접 붙여넣은 이미지는 영향받지 않습니다.
 
+### 이미지 가드 파이프라인 (v3.3.0)
+
+Anthropic의 실제 이미지 규칙을 그대로 반영하는 조건부 파이프라인입니다. 단일 환경 변수로 명시적 활성화:
+
+```bash
+export CACHE_FIX_IMAGE_GUARD=1
+```
+
+활성화 시 프록시는 다음을 실행합니다:
+
+| 패스 | 트리거 | 동작 |
+|------|--------|------|
+| **Pass 0** (레거시) | `CACHE_FIX_IMAGE_KEEP_LAST=N` 설정 | 가장 최근 N개 이외 사용자 메시지의 tool_result 이미지 제거 |
+| **Pass 3** | `CACHE_FIX_IMAGE_PRESERVE_DETAIL=1` AND 긴 변 > 모델 네이티브 캡 | `sharp`를 통해 네이티브 캡(Opus 4.7은 2576px, 그 외는 1568px)으로 Lanczos 리사이즈, 종횡비와 미디어 타입 보존 |
+| **Pass 1** | 긴 변 > 활성 거부 캡 | 제거 후 forensic 자리 표시자로 대체. 활성 캡 = `MAX_DIM` 설정 시 그 값, 아니면 2000px (개수 > 20일 때) 또는 8000px (개수 ≤ 20) |
+| **Pass 2** | 요청 본문이 `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` (기본 30 MB) 초과 | 예산 이하가 될 때까지 가장 오래된 이미지부터 제거 |
+| **개수 캡** | 잔여 이미지 개수 > `CACHE_FIX_IMAGE_COUNT_MAX` (기본 100) | 캡까지 가장 오래된 이미지 제거 |
+
+실행 순서: **Pass 0 → Pass 3 → Pass 1 → Pass 2 → 개수 캡**. 각 패스는 독립적입니다 — Pass 1은 절대 리사이즈하지 않으며, Pass 3는 절대 제거하지 않습니다.
+
+#### 선택적 `sharp` 의존성
+
+Pass 3는 Lanczos 리사이즈를 위해 [sharp](https://www.npmjs.com/package/sharp)가 필요합니다. **선택적 peer dependency**로 선언되어 있으며, Pass 3를 사용하려면 별도로 설치하십시오:
+
+```bash
+npm install sharp
+```
+
+`sharp`가 없는 경우 Pass 3는 깨끗하게 건너뛰며 (telemetry에 `library_missing: true`), Pass 1 + Pass 2 + 개수 캡은 정상 실행됩니다.
+
+전체 우선순위 매트릭스(레거시 + 신규 환경 변수의 모든 조합) 및 튜닝 가능한 항목은 [README.md](README.md#image-guard-pipeline-v330)를 참조하십시오.
+
 ## 시스템 프롬프트 재작성 (프리로드 모드, 선택)
 
 인터셉터가 Claude Code의 `# Output efficiency` 시스템 프롬프트 섹션을 재작성할 수 있습니다. 기본 비활성화입니다. `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`로 활성화하십시오. 세 가지 알려진 프롬프트 변형과 사용법은 [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md)를 참조하십시오.

package/README.md

@@ -112,7 +112,7 @@ docker run -d --name cache-fix-proxy --restart=always -p 9801:9801 \
   ghcr.io/cnighswonger/claude-code-cache-fix:latest
 ```
 
-Image tags: `latest`, `3`, `3.2`, `3.2.0` (semver-ladder, so `3` always points to the newest 3.x). `latest` always tracks the newest tagged release.
+Image tags: `latest`, `3`, `3.2`, `3.2.1` (semver-ladder, so `3` always points to the newest 3.x). `latest` always tracks the newest tagged release.
 
 **Linux note:** the chained-upstream `host.docker.internal` example below is automatic on Docker Desktop (macOS / Windows). On plain Linux Docker Engine you usually need `--add-host=host.docker.internal:host-gateway` so the name resolves to the host bridge. Without it, the container's name lookup fails and the proxy can't reach the upstream service running on the host. Example chaining cache-fix proxy through `llm-relay` running on the host:
 
@@ -334,6 +334,81 @@ export CACHE_FIX_IMAGE_KEEP_LAST=3
 
 Keeps images in the last 3 user messages, replaces older ones with a text placeholder. Only targets `tool_result` blocks — user-pasted images are never touched.
 
+### Oversized-image guard (legacy, v3.2.1)
+
+```bash
+export CACHE_FIX_IMAGE_MAX_DIM=2000
+```
+
+The Anthropic API enforces TWO image-related limits on multi-image requests, and the same error message can fire for either:
+
+> `"An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images."`
+
+Two pressure axes to address them:
+
+| Pressure | Variable | What it does |
+|---|---|---|
+| **Too many images in conversation** | `CACHE_FIX_IMAGE_KEEP_LAST=N` | Strips images from old user messages, keeps only the last N. |
+| **Any single image too large** | `CACHE_FIX_IMAGE_MAX_DIM=2000` | Replaces images exceeding the dimension limit with a forensic placeholder noting the original dimensions. Covers both user-message direct images and tool_result-nested images. |
+
+The two compose: with both set, `KEEP_LAST` runs first (drops the count), then `MAX_DIM` runs on what remains (caps the size of the kept ones). Common triggers for the dimension axis: hi-res manuscript scans, retina screenshots, photos at full resolution.
+
+Pure-JS PNG and JPEG header parsing — no native deps. Other formats (GIF, WebP, AVIF, BMP) pass through unchanged regardless of dimension. Fail-open: images whose dimensions can't be parsed (truncated header, unsupported format) are kept rather than stripped — better to send a request that might error than to strip a valid image we just couldn't measure.
+
+### Image-guard pipeline (v3.3.0)
+
+A conditional pipeline that mirrors Anthropic's actual rules. Strictly opt-in via a single env var:
+
+```bash
+export CACHE_FIX_IMAGE_GUARD=1
+```
+
+When enabled, the proxy runs:
+
+| Pass | Trigger | Action |
+|------|---------|--------|
+| **Pass 0** (legacy) | `CACHE_FIX_IMAGE_KEEP_LAST=N` set | Strip tool_result images from user messages older than N most recent |
+| **Pass 3** | `CACHE_FIX_IMAGE_PRESERVE_DETAIL=1` AND image long edge > model native cap | Lanczos resize via `sharp` to native cap (2576 px for Opus 4.7, 1568 px otherwise), preserve aspect ratio and media type |
+| **Pass 1** | image long edge > active rejection cap | Strip and replace with forensic placeholder. Active cap = `MAX_DIM` if set, else 2000 px (when count > 20) or 8000 px (count ≤ 20) |
+| **Pass 2** | request body exceeds `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` (default 30 MB) | Drop oldest images until under budget |
+| **Count cap** | surviving image count > `CACHE_FIX_IMAGE_COUNT_MAX` (default 100) | Drop oldest images down to the cap |
+
+Execution order: **Pass 0 → Pass 3 → Pass 1 → Pass 2 → count cap**. Each pass is independent — Pass 1 never resizes; Pass 3 never strips.
+
+#### Optional `sharp` dependency
+
+Pass 3 requires [sharp](https://www.npmjs.com/package/sharp) for Lanczos resize. It's declared as an **optional peer dependency** — install separately if you want Pass 3:
+
+```bash
+npm install sharp
+```
+
+If `sharp` is missing, Pass 3 skips cleanly (telemetry records `library_missing: true`); Pass 1 + Pass 2 + the count cap still run.
+
+#### Precedence matrix
+
+| Env var combination | Behavior |
+|---|---|
+| Nothing set | No image processing (back-compat default; the extension short-circuits). |
+| `KEEP_LAST=N` only | Existing v3.2.1: count cap on tool_result images in user messages, runs first. No pipeline. |
+| `MAX_DIM=N` only | Existing v3.2.1: hard size cap, strip-only. No pipeline. |
+| `KEEP_LAST=N` + `MAX_DIM=N` | Existing v3.2.1 composition: `KEEP_LAST` runs first (drops count), then `MAX_DIM` runs on survivors (caps size). No pipeline, no Pass 2, no Pass 3. |
+| `IMAGE_GUARD=1` | New pipeline: Pass 1 (conditional cap) + Pass 2 (request-size guard) + image-count cap. |
+| `IMAGE_GUARD=1` + `MAX_DIM=N` | `MAX_DIM` overrides Pass 1's conditional cap (acts as the cap value); Pass 2 still runs. |
+| `IMAGE_GUARD=1` + `PRESERVE_DETAIL=1` | Adds Pass 3 (Lanczos resize via `sharp`). When `sharp` unavailable, falls back to strip behavior. |
+| `IMAGE_GUARD=1` + `KEEP_LAST=N` | `KEEP_LAST` runs first as count cap (Pass 0); pipeline runs on remainder. |
+| `IMAGE_GUARD=1` + `KEEP_LAST=N` + `MAX_DIM=N` | Three-way: `KEEP_LAST` runs first; pipeline runs on remainder, but `MAX_DIM` overrides Pass 1's conditional cap; Pass 2 still runs. |
+| `PRESERVE_DETAIL=1` without `IMAGE_GUARD=1` | Logs warning, treats as no-op. `PRESERVE_DETAIL` is meaningless without the pipeline running. |
+
+#### Tunables
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_IMAGE_GUARD` | unset | Top-level pipeline gate (`=1` enables). |
+| `CACHE_FIX_IMAGE_PRESERVE_DETAIL` | unset | Enable Pass 3 Lanczos resize via `sharp`. |
+| `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` | 31457280 (30 MB) | Pass 2 byte budget. 2 MB headroom from Anthropic's 32 MB ceiling. |
+| `CACHE_FIX_IMAGE_COUNT_MAX` | 100 | Hard image-count cap. Set to 600 for legacy Claude 1/2.x/Instant if needed. |
+
 ## System prompt rewrite (preload mode, optional)
 
 The interceptor can rewrite Claude Code's `# Output efficiency` system-prompt section. Disabled by default. Enable with `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`. See [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md) for the three known prompt variants and usage instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",
@@ -27,6 +27,11 @@
   "dependencies": {
     "hpagent": "^1.2.0"
   },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
   "keywords": [
     "claude-code",
     "claude",

package/proxy/extensions/image-strip.mjs

@@ -1,6 +1,62 @@
+// image-strip extension — back-compat for v3.2.1 KEEP_LAST/MAX_DIM behavior
+// PLUS the v3.3.0 image-guard pipeline.
+//
+// Activation pattern: `enabled: true` in extensions.json (the extension is
+// always loaded), runtime gates per-feature via env vars. Three independent
+// trigger surfaces:
+//
+//   - CACHE_FIX_IMAGE_KEEP_LAST=N        → legacy Pass 0 (count cap on
+//                                          tool_result images in user msgs)
+//   - CACHE_FIX_IMAGE_MAX_DIM=N          → legacy Pass 1 strip-only (back-compat)
+//   - CACHE_FIX_IMAGE_GUARD=1            → v3.3.0 pipeline (Pass 1 + 2 + count cap)
+//   - CACHE_FIX_IMAGE_GUARD=1 +
+//     CACHE_FIX_IMAGE_PRESERVE_DETAIL=1  → adds Pass 3 (Lanczos resize via sharp)
+//
+// Execution order: Pass 0 → Pass 3 → Pass 1 → Pass 2 → image-count cap.
+//
+// See `docs/directives/proxy-image-guard-pipeline.md` for full spec, including
+// the precedence matrix and per-pass trigger/action contracts.
+
+import { parseImageDimensions } from "../image-dimensions.mjs";
+import { resizeImageToCap } from "../image-resize.mjs";
+
+// --- Legacy v3.2.1 constants (back-compat) ---
 const KEEP_LAST = parseInt(process.env.CACHE_FIX_IMAGE_KEEP_LAST || "0", 10);
+const MAX_DIM = parseInt(process.env.CACHE_FIX_IMAGE_MAX_DIM || "0", 10);
 const PLACEHOLDER = "[image stripped from history — file may still be on disk]";
 
+function oversizedPlaceholder(maxDim, w, h) {
+  return `[image stripped — exceeded ${maxDim}px max dimension (was ${w}x${h}px)]`;
+}
+
+// --- v3.3.0 pipeline env helpers (read at call time, not at module load,
+// so per-test isolation works without re-importing the module) ---
+function isImageGuardEnabled() {
+  return process.env.CACHE_FIX_IMAGE_GUARD === "1";
+}
+function isPreserveDetailEnabled() {
+  return process.env.CACHE_FIX_IMAGE_PRESERVE_DETAIL === "1";
+}
+function getMaxDim() {
+  return parseInt(process.env.CACHE_FIX_IMAGE_MAX_DIM || "0", 10);
+}
+function getKeepLast() {
+  return parseInt(process.env.CACHE_FIX_IMAGE_KEEP_LAST || "0", 10);
+}
+function getRequestSizeMax() {
+  // Default 30 MB (31457280 bytes). 2 MB headroom from Anthropic's 32 MB body limit.
+  const v = parseInt(process.env.CACHE_FIX_IMAGE_REQUEST_SIZE_MAX || "31457280", 10);
+  return v > 0 ? v : 31457280;
+}
+function getImageCountMax() {
+  // Default 100 — single cap covering the only model family in active CC use.
+  // Users on legacy Claude 1/2.x/Instant who genuinely need 600 can override.
+  const v = parseInt(process.env.CACHE_FIX_IMAGE_COUNT_MAX || "100", 10);
+  return v > 0 ? v : 100;
+}
+
+// --- Legacy Pass 0: KEEP_LAST tool_result image strip ---
+// (Unchanged from v3.2.1 — only formatting tightened.)
 function stripOldToolResultImages(messages, keepLast) {
   if (!keepLast || keepLast <= 0 || !Array.isArray(messages)) {
     return { messages, stats: null };
@@ -58,26 +114,589 @@ function stripOldToolResultImages(messages, keepLast) {
   return { messages: strippedCount > 0 ? result : messages, stats };
 }
 
-export { stripOldToolResultImages, PLACEHOLDER };
+// --- Legacy Pass 1 (strip-only by max dim) ---
+// (Unchanged from v3.2.1.) The new pipeline's Pass 1 is a separate function
+// (`runPass1RejectionCapStrip`) that uses the conditional 2000/8000 logic.
+function stripOversizedImages(messages, maxDim) {
+  if (!maxDim || maxDim <= 0 || !Array.isArray(messages)) {
+    return { messages, stats: null };
+  }
+
+  let strippedCount = 0;
+  let strippedBytes = 0;
+
+  function maybeStrip(item) {
+    if (!item || item.type !== "image") return item;
+    const src = item.source;
+    if (!src || !src.data || !src.media_type) return item;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) return item;
+    if (dims.width <= maxDim && dims.height <= maxDim) return item;
+    strippedCount++;
+    strippedBytes += src.data.length;
+    return { type: "text", text: oversizedPlaceholder(maxDim, dims.width, dims.height) };
+  }
+
+  const result = messages.map((msg) => {
+    if (!Array.isArray(msg.content)) return msg;
+    let mutated = false;
+    const newContent = msg.content.map((block) => {
+      if (block && block.type === "image") {
+        const replaced = maybeStrip(block);
+        if (replaced !== block) {
+          mutated = true;
+          return replaced;
+        }
+        return block;
+      }
+      if (block && block.type === "tool_result" && Array.isArray(block.content)) {
+        let toolMutated = false;
+        const newToolContent = block.content.map((item) => {
+          const replaced = maybeStrip(item);
+          if (replaced !== item) toolMutated = true;
+          return replaced;
+        });
+        if (toolMutated) {
+          mutated = true;
+          return { ...block, content: newToolContent };
+        }
+      }
+      return block;
+    });
+    return mutated ? { ...msg, content: newContent } : msg;
+  });
+
+  const stats = strippedCount > 0
+    ? { strippedCount, strippedBytes, estimatedTokens: Math.ceil(strippedBytes * 0.125) }
+    : null;
+
+  return { messages: strippedCount > 0 ? result : messages, stats };
+}
+
+// =============================================================================
+// v3.3.0 pipeline
+// =============================================================================
+
+// --- Pure helpers (exported for tests) ---
+
+// Pass 1 cap selector. `maxDimOverride > 0` always wins over the conditional
+// rejection cap. Otherwise: count > 20 → 2000 px, else 8000 px.
+function pickPass1Cap(imageCount, maxDimOverride) {
+  if (maxDimOverride && maxDimOverride > 0) return maxDimOverride;
+  return imageCount > 20 ? 2000 : 8000;
+}
+
+// Pass 3 native-cap selector. Only Opus 4.7 has the higher cap.
+function pickPass3NativeCap(modelString) {
+  if (typeof modelString === "string" && modelString.startsWith("claude-opus-4-7")) {
+    return 2576;
+  }
+  return 1568;
+}
+
+// Anthropic's documented per-image token formula: `width * height / 750`,
+// capped at the model's native token cap. Diagnostic only (no enforcement).
+function estimateImageTokens(width, height, modelTokenCap) {
+  if (!width || !height) return 0;
+  const raw = Math.ceil((width * height) / 750);
+  if (modelTokenCap && raw > modelTokenCap) return modelTokenCap;
+  return raw;
+}
+
+function nativeTokenCap(modelString) {
+  if (typeof modelString === "string" && modelString.startsWith("claude-opus-4-7")) {
+    return 4784;
+  }
+  return 1568;
+}
+
+// Walker: enumerate every image in `body.messages`, both user-msg direct content
+// and tool_result.content. Returns a list of `{ msgIdx, blockIdx, itemIdx | null,
+// item }` references. `itemIdx === null` means the image is a direct user-msg
+// content block (not nested in tool_result).
+function walkImages(messages) {
+  const out = [];
+  if (!Array.isArray(messages)) return out;
+  for (let m = 0; m < messages.length; m++) {
+    const msg = messages[m];
+    if (!Array.isArray(msg.content)) continue;
+    for (let b = 0; b < msg.content.length; b++) {
+      const block = msg.content[b];
+      if (!block) continue;
+      if (block.type === "image") {
+        out.push({ msgIdx: m, blockIdx: b, itemIdx: null, item: block });
+      } else if (block.type === "tool_result" && Array.isArray(block.content)) {
+        for (let i = 0; i < block.content.length; i++) {
+          const item = block.content[i];
+          if (item && item.type === "image") {
+            out.push({ msgIdx: m, blockIdx: b, itemIdx: i, item });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// Mutate a single image at the given (msgIdx, blockIdx, itemIdx) reference,
+// either replacing it with a placeholder text block (strip) or updating its
+// source.data + dims (resize).
+function replaceImageInPlace(messages, ref, replacement) {
+  const msg = messages[ref.msgIdx];
+  if (!msg || !Array.isArray(msg.content)) return;
+  const block = msg.content[ref.blockIdx];
+  if (!block) return;
+  if (ref.itemIdx === null) {
+    msg.content[ref.blockIdx] = replacement;
+  } else {
+    if (!Array.isArray(block.content)) return;
+    block.content[ref.itemIdx] = replacement;
+  }
+}
+
+// Pure walker for Pass 1: returns the list of image refs whose long edge
+// exceeds `capPx`, alongside their measured dims. Unparseable images are not
+// included (fail-open). Exposed for tests.
+function walkImagesForPass1(messages, capPx) {
+  const refs = walkImages(messages);
+  const plan = [];
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data || !src.media_type) continue;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) {
+      plan.push({ ref, dims: null, action: "skip_unmeasurable" });
+      continue;
+    }
+    const longEdge = Math.max(dims.width, dims.height);
+    if (longEdge > capPx) {
+      plan.push({ ref, dims, action: "strip" });
+    }
+  }
+  return plan;
+}
+
+// Pure walker for Pass 3: returns refs whose long edge exceeds `nativeCapPx`,
+// plus the dims/cap so the caller can do the actual resize.
+function walkImagesForPass3(messages, nativeCapPx) {
+  const refs = walkImages(messages);
+  const plan = [];
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data || !src.media_type) continue;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) {
+      plan.push({ ref, dims: null, action: "skip_unmeasurable" });
+      continue;
+    }
+    const longEdge = Math.max(dims.width, dims.height);
+    if (longEdge > nativeCapPx) {
+      plan.push({ ref, dims, action: "resize", capPx: nativeCapPx });
+    }
+  }
+  return plan;
+}
+
+// Eviction order for Pass 2 / count cap: oldest first (low msgIdx wins),
+// within a message tool_result images are preferred over direct images at the
+// same age. Returns an ordered list of refs to drop.
+function pickEvictionTargets(messages) {
+  const refs = walkImages(messages);
+  // Stable sort: by msgIdx ascending, then prefer tool_result (itemIdx !== null)
+  // over direct (itemIdx === null) at the same msgIdx.
+  refs.sort((a, b) => {
+    if (a.msgIdx !== b.msgIdx) return a.msgIdx - b.msgIdx;
+    const aTool = a.itemIdx !== null ? 0 : 1;
+    const bTool = b.itemIdx !== null ? 0 : 1;
+    if (aTool !== bTool) return aTool - bTool;
+    if (a.blockIdx !== b.blockIdx) return a.blockIdx - b.blockIdx;
+    return (a.itemIdx ?? 0) - (b.itemIdx ?? 0);
+  });
+  return refs;
+}
+
+// --- Stats initializer (matches the directive's telemetry surface verbatim) ---
+function initStats() {
+  return {
+    total_images: 0,
+    count_axis_path: "few",
+    unsupported_format_count: 0,
+    dimension_probe_fail_count: 0,
+    resize_attempted: 0,
+    resize_succeeded: 0,
+    resize_failed: 0,
+    library_missing: false,
+    images_stripped_pass1: 0,
+    images_dropped_for_size: 0,
+    images_dropped_for_count_cap: 0,
+
+    request_bytes_before: 0,
+    request_bytes_after: 0,
+    request_bytes_headroom: 0,
+    image_bytes_total: 0,
+    image_bytes_dropped: 0,
+
+    estimated_image_tokens_total: 0,
+  };
+}
+
+// --- Pass 3 runtime: native-cap resize via sharp ---
+async function runPass3NativeCapResize(reqCtx, stats) {
+  if (stats.library_missing) return;
+
+  const messages = reqCtx.body.messages;
+  const model = reqCtx.body.model;
+  const nativeCap = pickPass3NativeCap(model);
+  const tokenCap = nativeTokenCap(model);
+
+  const plan = walkImagesForPass3(messages, nativeCap);
+  for (const step of plan) {
+    if (step.action === "skip_unmeasurable") {
+      // Tracked separately via the unsupported/probe counters at the top-level
+      // walker (we double-count if we touch them here too — leave it to the
+      // central counter pass).
+      continue;
+    }
+    if (step.action !== "resize") continue;
+
+    const src = step.ref.item.source;
+    stats.resize_attempted++;
+    const result = await resizeImageToCap(src.data, src.media_type, step.capPx);
+    if (result.ok) {
+      stats.resize_succeeded++;
+      // Mutate in place: keep the same content block shape, swap data + record dims.
+      const newImage = {
+        ...step.ref.item,
+        source: { ...src, data: result.base64 },
+      };
+      replaceImageInPlace(messages, step.ref, newImage);
+      const tokensBefore = estimateImageTokens(step.dims.width, step.dims.height, tokenCap);
+      const tokensAfter = estimateImageTokens(result.dims.width, result.dims.height, tokenCap);
+      stats.estimated_image_tokens_total += tokensAfter - tokensBefore;
+    } else if (result.reason === "library_missing") {
+      stats.library_missing = true;
+      // Sticky: stop attempting Pass 3 for the remainder of this request.
+      // (loadSharp() inside image-resize.mjs is also sticky for the process.)
+      return;
+    } else {
+      stats.resize_failed++;
+      // Leave image untouched; Pass 1 will evaluate it against its own cap.
+    }
+  }
+}
+
+// --- Pass 1 runtime: conditional rejection-cap strip ---
+function runPass1RejectionCapStrip(reqCtx, stats, opts) {
+  const { maxDimOverride } = opts || {};
+  const messages = reqCtx.body.messages;
+
+  const refs = walkImages(messages);
+  const imageCount = refs.length;
+  stats.total_images = Math.max(stats.total_images, imageCount);
+  stats.count_axis_path = imageCount > 20 ? "many" : "few";
+  const cap = pickPass1Cap(imageCount, maxDimOverride);
+
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data || !src.media_type) continue;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) {
+      // Distinguish unsupported format from probe failure on a known type.
+      const mt = (src.media_type || "").toLowerCase();
+      if (mt === "image/png" || mt === "image/jpeg" || mt === "image/jpg") {
+        stats.dimension_probe_fail_count++;
+      } else {
+        stats.unsupported_format_count++;
+      }
+      continue;
+    }
+    const longEdge = Math.max(dims.width, dims.height);
+    if (longEdge > cap) {
+      replaceImageInPlace(messages, ref, {
+        type: "text",
+        text: oversizedPlaceholder(cap, dims.width, dims.height),
+      });
+      stats.images_stripped_pass1++;
+    }
+  }
+}
+
+// --- Pass 2 runtime: request-size guard ---
+function runPass2RequestSizeGuard(reqCtx, stats) {
+  const budget = getRequestSizeMax();
+  const before = Buffer.byteLength(JSON.stringify(reqCtx.body));
+  if (stats.request_bytes_before === 0) stats.request_bytes_before = before;
+
+  if (before <= budget) {
+    stats.request_bytes_after = before;
+    stats.request_bytes_headroom = budget - before;
+    return;
+  }
+
+  // Build eviction queue once; drop one at a time, re-measuring after each drop.
+  const queue = pickEvictionTargets(reqCtx.body.messages);
+  let bytes = before;
+  for (const ref of queue) {
+    if (bytes <= budget) break;
+    const src = ref.item.source;
+    const droppedBytes = src && src.data ? src.data.length : 0;
+    replaceImageInPlace(reqCtx.body.messages, ref, {
+      type: "text",
+      text: "[image dropped to fit request-size budget]",
+    });
+    stats.images_dropped_for_size++;
+    stats.image_bytes_dropped += droppedBytes;
+    bytes = Buffer.byteLength(JSON.stringify(reqCtx.body));
+  }
+  stats.request_bytes_after = bytes;
+  stats.request_bytes_headroom = budget - bytes;
+  // If we exhausted the queue and bytes still exceed budget, the body is
+  // over-budget for non-image reasons; the request will fail upstream and we
+  // don't address that here. Telemetry already records the final bytes.
+}
+
+// --- Hard image-count cap ---
+function runImageCountCap(reqCtx, stats) {
+  const cap = getImageCountMax();
+  const queue = pickEvictionTargets(reqCtx.body.messages);
+  if (queue.length <= cap) return;
+  const toDrop = queue.length - cap;
+  for (let i = 0; i < toDrop; i++) {
+    const ref = queue[i];
+    const src = ref.item.source;
+    const droppedBytes = src && src.data ? src.data.length : 0;
+    replaceImageInPlace(reqCtx.body.messages, ref, {
+      type: "text",
+      text: "[image dropped — exceeded image-count cap]",
+    });
+    stats.images_dropped_for_count_cap++;
+    stats.image_bytes_dropped += droppedBytes;
+  }
+  // Recompute request_bytes_after after count-cap evictions so the final
+  // telemetry reflects the post-pipeline body. Without this, count-cap-only
+  // requests would report unchanged byte totals (Codex review note).
+  if (toDrop > 0) {
+    const budget = getRequestSizeMax();
+    const after = Buffer.byteLength(JSON.stringify(reqCtx.body));
+    stats.request_bytes_after = after;
+    stats.request_bytes_headroom = budget - after;
+  }
+}
+
+// --- Telemetry: walk surviving images for byte/token totals ---
+function finalizeTelemetry(reqCtx, stats) {
+  const refs = walkImages(reqCtx.body.messages);
+  let totalBytes = 0;
+  let totalTokens = 0;
+  const tokenCap = nativeTokenCap(reqCtx.body.model);
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data) continue;
+    totalBytes += src.data.length;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (dims) {
+      totalTokens += estimateImageTokens(dims.width, dims.height, tokenCap);
+    }
+  }
+  stats.image_bytes_total = totalBytes;
+  // estimated_image_tokens_total was decremented by Pass 3 deltas; for the
+  // baseline (Pass 3 disabled) recompute from surviving images.
+  if (stats.resize_attempted === 0) {
+    stats.estimated_image_tokens_total = totalTokens;
+  } else {
+    // Pass 3 mutated in place; re-measure surviving population to ground-truth.
+    stats.estimated_image_tokens_total = totalTokens;
+  }
+}
+
+// --- Top-level pipeline orchestrator ---
+async function runImageGuard(reqCtx) {
+  const stats = initStats();
+  const messages = reqCtx.body.messages;
+  if (!Array.isArray(messages)) return stats;
+
+  // Capture initial population count for the summary line.
+  stats.total_images = walkImages(messages).length;
+  stats.count_axis_path = stats.total_images > 20 ? "many" : "few";
+
+  const guardOn = isImageGuardEnabled();
+  const preserveOn = isPreserveDetailEnabled();
+  const maxDimOverride = getMaxDim();
+
+  // Warn if PRESERVE_DETAIL is set without IMAGE_GUARD (one-time per process).
+  if (!guardOn && preserveOn && !_preserveDetailWarned) {
+    process.stderr.write(
+      "[image-guard] CACHE_FIX_IMAGE_PRESERVE_DETAIL=1 has no effect without CACHE_FIX_IMAGE_GUARD=1\n"
+    );
+    _preserveDetailWarned = true;
+  }
+
+  // Pass 3: native-cap resize (only when both gates are on)
+  if (guardOn && preserveOn) {
+    await runPass3NativeCapResize(reqCtx, stats);
+  }
+
+  // Pass 1: rejection-cap strip — runs if IMAGE_GUARD=1 OR legacy MAX_DIM > 0
+  if (guardOn || maxDimOverride > 0) {
+    runPass1RejectionCapStrip(reqCtx, stats, { maxDimOverride });
+  }
+
+  // Pass 2: request-size guard — IMAGE_GUARD only
+  if (guardOn) {
+    runPass2RequestSizeGuard(reqCtx, stats);
+  }
+
+  // Hard image-count cap — IMAGE_GUARD only
+  if (guardOn) {
+    runImageCountCap(reqCtx, stats);
+  }
+
+  // Final telemetry sweep over surviving images
+  finalizeTelemetry(reqCtx, stats);
+
+  return stats;
+}
+
+// One-time warning state for PRESERVE_DETAIL-without-GUARD.
+let _preserveDetailWarned = false;
+
+// Test hook to reset warning flag.
+function _resetWarningStateForTests() {
+  _preserveDetailWarned = false;
+}
+
+export {
+  // Legacy v3.2.1 exports (kept stable for back-compat tests)
+  stripOldToolResultImages,
+  stripOversizedImages,
+  PLACEHOLDER,
+  oversizedPlaceholder,
+  // v3.3.0 pipeline pure functions (test seams)
+  pickPass1Cap,
+  pickPass3NativeCap,
+  estimateImageTokens,
+  walkImagesForPass1,
+  walkImagesForPass3,
+  pickEvictionTargets,
+  // Orchestrator (used by the extension default export and direct test calls)
+  runImageGuard,
+  // Test utilities
+  _resetWarningStateForTests,
+};
 
 export default {
   name: "image-strip",
-  description: "Strip base64 images from old tool results to reduce token waste",
-  enabled: false,
+  description:
+    "v3.2.1 KEEP_LAST/MAX_DIM legacy paths PLUS v3.3.0 image-guard pipeline " +
+    "(conditional rejection cap + request-size guard + optional Lanczos resize)",
+  enabled: false,        // overridden by extensions.json
   order: 150,
 
   async onRequest(ctx) {
-    const keepLast = parseInt(ctx.meta.imageKeepLast ?? KEEP_LAST, 10);
-    if (!keepLast || keepLast <= 0) return;
-    if (!ctx.body.messages) return;
-
-    const { messages, stats } = stripOldToolResultImages(ctx.body.messages, keepLast);
-    if (stats) {
-      ctx.body.messages = messages;
-      ctx.meta.imageStripStats = stats;
+    const guardOn = isImageGuardEnabled();
+    const preserveOn = isPreserveDetailEnabled();
+    // ctx.meta overrides allow tests to drive the legacy paths without env vars.
+    // Pipeline gates (IMAGE_GUARD, PRESERVE_DETAIL) remain env-only — tests that
+    // need to flip them set process.env directly.
+    const keepLast = parseInt(ctx.meta?.imageKeepLast ?? getKeepLast(), 10);
+    const maxDim = parseInt(ctx.meta?.imageMaxDim ?? getMaxDim(), 10);
+
+    // Short-circuit: nothing to do.
+    if (!guardOn && keepLast <= 0 && maxDim <= 0) {
+      // Surface the PRESERVE_DETAIL-without-GUARD warning even when the
+      // pipeline doesn't run otherwise.
+      if (preserveOn && !_preserveDetailWarned) {
+        process.stderr.write(
+          "[image-guard] CACHE_FIX_IMAGE_PRESERVE_DETAIL=1 has no effect without CACHE_FIX_IMAGE_GUARD=1\n"
+        );
+        _preserveDetailWarned = true;
+      }
+      return;
+    }
+
+    if (!ctx.body || !ctx.body.messages) return;
+
+    // ========== Legacy path (v3.2.1 back-compat) ==========
+    // When IMAGE_GUARD=1 is OFF but legacy env vars are set, run the v3.2.1
+    // pipeline exactly as before — preserves bug-for-bug compatibility for
+    // existing users.
+    if (!guardOn) {
+      let messages = ctx.body.messages;
+      const logParts = [];
+
+      if (keepLast > 0) {
+        const r = stripOldToolResultImages(messages, keepLast);
+        if (r.stats) {
+          messages = r.messages;
+          ctx.meta.imageStripStats = r.stats;
+          logParts.push(
+            `keep_last: ${r.stats.strippedCount} stripped (~${r.stats.estimatedTokens} tokens saved)`
+          );
+        }
+      }
+
+      if (maxDim > 0) {
+        const r = stripOversizedImages(messages, maxDim);
+        if (r.stats) {
+          messages = r.messages;
+          ctx.meta.imageStripOversizedStats = r.stats;
+          logParts.push(
+            `max_dim: ${r.stats.strippedCount} oversized stripped ` +
+            `(~${r.stats.estimatedTokens} tokens saved)`
+          );
+        }
+      }
+
+      if (logParts.length > 0) {
+        ctx.body.messages = messages;
+        process.stderr.write(`[image-strip] ${logParts.join("; ")}\n`);
+      }
+      return;
+    }
+
+    // ========== v3.3.0 pipeline path ==========
+    // KEEP_LAST runs first as Pass 0 (back-compat behavior preserved).
+    if (keepLast > 0) {
+      const r = stripOldToolResultImages(ctx.body.messages, keepLast);
+      if (r.stats) {
+        ctx.body.messages = r.messages;
+        ctx.meta.imageStripStats = r.stats;
+      }
+    }
+
+    const stats = await runImageGuard(ctx);
+    ctx.meta.imageGuardStats = stats;
+
+    // Emit summary only if the pipeline actually did anything observable.
+    const didSomething =
+      stats.images_stripped_pass1 > 0 ||
+      stats.images_dropped_for_size > 0 ||
+      stats.images_dropped_for_count_cap > 0 ||
+      stats.resize_attempted > 0 ||
+      stats.resize_succeeded > 0 ||
+      stats.unsupported_format_count > 0 ||
+      stats.dimension_probe_fail_count > 0;
+    if (didSomething) {
+      const parts = [];
+      if (stats.resize_succeeded > 0) parts.push(`resized=${stats.resize_succeeded}`);
+      if (stats.resize_failed > 0) parts.push(`resize_failed=${stats.resize_failed}`);
+      if (stats.library_missing) parts.push("sharp=missing");
+      if (stats.images_stripped_pass1 > 0) parts.push(`stripped=${stats.images_stripped_pass1}`);
+      if (stats.images_dropped_for_size > 0) parts.push(`evicted=${stats.images_dropped_for_size}`);
+      if (stats.images_dropped_for_count_cap > 0) {
+        parts.push(`count_capped=${stats.images_dropped_for_count_cap}`);
+      }
+      if (stats.unsupported_format_count > 0) parts.push(`unsupported=${stats.unsupported_format_count}`);
+      const summary = parts.join(" ") || "ran";
+      const finalImages = stats.total_images
+        - stats.images_stripped_pass1
+        - stats.images_dropped_for_size
+        - stats.images_dropped_for_count_cap;
       process.stderr.write(
-        `[image-strip] stripped ${stats.strippedCount} images (~${stats.estimatedTokens} tokens saved)\n`
+        `[image-guard] ${summary} req_bytes=${stats.request_bytes_before}->${stats.request_bytes_after} ` +
+        `(headroom=${stats.request_bytes_headroom}) images=${stats.total_images}->${finalImages}\n`
       );
     }
   },
 };
+

package/proxy/extensions.json

@@ -1,5 +1,6 @@
 {
   "fingerprint-strip": { "enabled": true, "order": 100 },
+  "image-strip": { "enabled": true, "order": 150 },
   "sort-stabilization": { "enabled": true, "order": 200 },
   "fresh-session-sort": { "enabled": true, "order": 250 },
   "identity-normalization": { "enabled": true, "order": 300 },

package/proxy/image-dimensions.mjs

@@ -0,0 +1,120 @@
+// Pure-JS image header dimension parsing for PNG and JPEG.
+//
+// Used by the image-strip extension to detect images exceeding a configurable
+// max dimension. Stays in a separate module so it can be unit-tested without
+// the rest of the proxy machinery.
+//
+// No native deps. Decode-only — never modifies the image data.
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// PNG: after the 8-byte magic, the IHDR chunk begins. IHDR layout:
+//   [4 bytes length][4 bytes "IHDR"][4 bytes width BE][4 bytes height BE]...
+// Width starts at byte 16, height at byte 20, both 32-bit big-endian.
+export function parsePngDimensions(buffer) {
+  if (!buffer || buffer.length < 24) return null;
+  for (let i = 0; i < PNG_MAGIC.length; i++) {
+    if (buffer[i] !== PNG_MAGIC[i]) return null;
+  }
+  // Verify the IHDR chunk type (offset 12-15 should be ASCII "IHDR")
+  if (
+    buffer[12] !== 0x49 || buffer[13] !== 0x48 ||
+    buffer[14] !== 0x44 || buffer[15] !== 0x52
+  ) {
+    return null;
+  }
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+  if (width <= 0 || height <= 0) return null;
+  return { width, height };
+}
+
+// JPEG SOF (Start Of Frame) markers we care about. We don't differentiate
+// between SOF0 (baseline), SOF1 (extended sequential), SOF2 (progressive),
+// SOF3 (lossless) etc — all carry dimensions in the same layout.
+const JPEG_SOF_MARKERS = new Set([
+  0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+]);
+
+// JPEG: starts with FF D8 (SOI). Each segment after is FF <marker> [length BE]
+// [data...]. We scan for an SOF marker and read width/height from its segment.
+// SOF segment layout after the marker: [length 2B][precision 1B][height 2B][width 2B]...
+export function parseJpegDimensions(buffer) {
+  if (!buffer || buffer.length < 4) return null;
+  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
+
+  let i = 2;
+  const max = buffer.length;
+  // Bound iterations to keep malformed inputs from looping. JPEG headers we
+  // care about are well under 1KB; cap at the buffer size we got.
+  let iterations = 0;
+  while (i < max - 8 && iterations++ < 1000) {
+    // Each marker segment starts with 0xFF followed by the marker byte.
+    if (buffer[i] !== 0xff) {
+      // Skip over fill bytes / pad bytes (not valid in standard JPEG but tolerated)
+      i++;
+      continue;
+    }
+    // Skip multiple 0xFF prefixes (pad fill — valid per spec)
+    while (i < max - 1 && buffer[i] === 0xff) i++;
+    const marker = buffer[i];
+    i++;
+
+    // Markers without a length-prefixed segment: SOI (D8), EOI (D9), RST0-7 (D0-D7).
+    if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
+      continue;
+    }
+
+    if (i + 1 >= max) return null;
+    const segLen = (buffer[i] << 8) | buffer[i + 1];
+    if (segLen < 2 || i + segLen > max) return null;
+
+    if (JPEG_SOF_MARKERS.has(marker)) {
+      // Layout: [length 2B][precision 1B][height 2B][width 2B]
+      // i currently points at the length field's first byte.
+      if (i + 6 >= max) return null;
+      const height = (buffer[i + 3] << 8) | buffer[i + 4];
+      const width = (buffer[i + 5] << 8) | buffer[i + 6];
+      if (width <= 0 || height <= 0) return null;
+      return { width, height };
+    }
+
+    // Skip this segment to its end and continue scanning.
+    i += segLen;
+  }
+  return null;
+}
+
+// Decode a small prefix of base64 data and dispatch to the right parser based
+// on media_type. Returns { width, height } or null.
+//
+// We decode only the first ~512 bytes — enough for PNG IHDR (always near the
+// start) and the typical JPEG SOF location (most image encoders place the SOF
+// within the first few hundred bytes).
+const HEADER_PROBE_BYTES = 1024;
+
+export function parseImageDimensions(mediaType, base64Data) {
+  if (!mediaType || !base64Data || typeof base64Data !== "string") return null;
+  // Base64 expands by ~4/3, so to get HEADER_PROBE_BYTES decoded bytes we need
+  // ~HEADER_PROBE_BYTES * 4 / 3 base64 chars. Round up generously.
+  const probeChars = Math.min(base64Data.length, HEADER_PROBE_BYTES * 2);
+  let buffer;
+  try {
+    buffer = Buffer.from(base64Data.slice(0, probeChars), "base64");
+  } catch {
+    return null;
+  }
+  if (!buffer || buffer.length === 0) return null;
+
+  switch (mediaType.toLowerCase()) {
+    case "image/png":
+      return parsePngDimensions(buffer);
+    case "image/jpeg":
+    case "image/jpg":
+      return parseJpegDimensions(buffer);
+    default:
+      // Unsupported format — fail-open. Caller treats null as "can't measure"
+      // and keeps the image rather than stripping what it can't verify.
+      return null;
+  }
+}

package/proxy/image-resize.mjs

@@ -0,0 +1,133 @@
+// Lazy `sharp` wrapper for the image-guard pipeline's Pass 3 (native-cap resize).
+//
+// `sharp` is declared as an OPTIONAL peer dependency in package.json. The proxy
+// must run without it. This module:
+//
+//   1. Lazy-imports `sharp` only when first needed (no module-load cost when
+//      Pass 3 is disabled or sharp is absent).
+//   2. Caches the import result (success or library-missing failure) so we
+//      don't pay the import cost or re-throw repeatedly.
+//   3. Returns a stable `{ ok, reason }` shape the caller can branch on
+//      without try/catch around every call.
+//
+// The actual resize uses Lanczos resampling (sharp's default kernel for
+// downscales), preserves aspect ratio, and re-encodes using the SAME media
+// type as the input. No transcoding in v1 — JPEG stays JPEG, PNG stays PNG.
+
+let _sharpModule = null;          // resolved sharp module (or null if missing)
+let _sharpResolved = false;       // have we attempted the import?
+let _sharpMissing = false;        // sticky flag — if first import fails, never retry
+
+// Reset hook for tests. Not exported in the default surface; tests import by name.
+export function _resetSharpCacheForTests() {
+  _sharpModule = null;
+  _sharpResolved = false;
+  _sharpMissing = false;
+}
+
+// Override hook for tests: inject a fake sharp without going through real import.
+// The fake should be callable as `fake(buffer)` returning an object with
+// `.resize()` and `.toBuffer()`/`.toFormat()` methods like real sharp.
+export function _setSharpForTests(fakeSharp) {
+  _sharpModule = fakeSharp;
+  _sharpResolved = true;
+  _sharpMissing = !fakeSharp;
+}
+
+async function loadSharp() {
+  if (_sharpResolved) {
+    return { ok: !_sharpMissing, sharp: _sharpModule };
+  }
+  try {
+    const mod = await import("sharp");
+    _sharpModule = mod.default || mod;
+    _sharpResolved = true;
+    _sharpMissing = false;
+    return { ok: true, sharp: _sharpModule };
+  } catch (err) {
+    _sharpResolved = true;
+    _sharpMissing = true;
+    _sharpModule = null;
+    return { ok: false, sharp: null, err };
+  }
+}
+
+// Re-encode media type → sharp output format name. Keep symmetric with the
+// dimension probe (PNG + JPEG only in v1).
+function mediaTypeToSharpFormat(mediaType) {
+  switch ((mediaType || "").toLowerCase()) {
+    case "image/png":
+      return "png";
+    case "image/jpeg":
+    case "image/jpg":
+      return "jpeg";
+    default:
+      return null;
+  }
+}
+
+// Resize a base64-encoded image to `capPx` on the long edge using Lanczos.
+// Returns:
+//   { ok: true, base64, dims: { width, height }, bytes }     on success
+//   { ok: false, reason: "library_missing" | "unsupported_media_type" | "decode_failed" | "resize_failed" }
+//
+// Caller is expected to:
+//   - skip Pass 3 entirely on `library_missing` (sticky for the process)
+//   - increment per-image telemetry counters on the other failure modes and
+//     leave the original image untouched for Pass 1 to evaluate.
+export async function resizeImageToCap(base64Data, mediaType, capPx) {
+  if (!base64Data || typeof base64Data !== "string") {
+    return { ok: false, reason: "decode_failed" };
+  }
+  const format = mediaTypeToSharpFormat(mediaType);
+  if (!format) {
+    return { ok: false, reason: "unsupported_media_type" };
+  }
+
+  const loaded = await loadSharp();
+  if (!loaded.ok) {
+    return { ok: false, reason: "library_missing" };
+  }
+  const sharp = loaded.sharp;
+
+  let inputBuffer;
+  try {
+    inputBuffer = Buffer.from(base64Data, "base64");
+  } catch {
+    return { ok: false, reason: "decode_failed" };
+  }
+  if (!inputBuffer || inputBuffer.length === 0) {
+    return { ok: false, reason: "decode_failed" };
+  }
+
+  try {
+    const pipeline = sharp(inputBuffer).resize({
+      width: capPx,
+      height: capPx,
+      fit: "inside",          // preserve aspect ratio, neither edge exceeds capPx
+      withoutEnlargement: true, // never upscale
+      kernel: "lanczos3",
+    });
+
+    // Re-encode using the SAME format as the input. No transcoding in v1.
+    const encoded = format === "png"
+      ? await pipeline.png().toBuffer({ resolveWithObject: true })
+      : await pipeline.jpeg().toBuffer({ resolveWithObject: true });
+
+    const newBase64 = encoded.data.toString("base64");
+    return {
+      ok: true,
+      base64: newBase64,
+      dims: { width: encoded.info.width, height: encoded.info.height },
+      bytes: encoded.data.length,
+    };
+  } catch {
+    return { ok: false, reason: "resize_failed" };
+  }
+}
+
+// Tiny helper for tests: returns whether sharp was successfully imported once.
+// Doesn't trigger an import — caller must have invoked resizeImageToCap first.
+export function _sharpStatusForTests() {
+  return { resolved: _sharpResolved, missing: _sharpMissing };
+}