@stigmer/runner 3.9.0 → 3.10.0

package/src/shared/__tests__/attachment-vision.test.ts

@@ -143,6 +143,71 @@ describe("VisionBudget.offer — eligibility", () => {
   });
 });
 
+describe("VisionBudget — model vision capability gate", () => {
+  const blind = () => new VisionBudget(DEEP_AGENT_VISION_PROFILE, { modelVision: false });
+
+  it("degrades every recognizable image with model_no_vision when the model is flagged blind", () => {
+    expect(blind().offer("photo.png", "image/png", imageBytes("png"))).toEqual({
+      kind: "degraded",
+      reason: "model_no_vision",
+    });
+    // Sniff-authoritative acceptance is gated too: real image bytes with a
+    // non-image declared type are still image-shaped.
+    expect(blind().offer("blob.bin", "application/octet-stream", imageBytes("jpeg"))).toEqual({
+      kind: "degraded",
+      reason: "model_no_vision",
+    });
+  });
+
+  it("reports model_no_vision (not type_mismatch) for declared-but-unsniffable images", () => {
+    // A HEIC renamed .jpg on a blind model: "unreadable format" would invite
+    // a re-encode that cannot help — blindness is the whole story.
+    expect(blind().offer("photo.jpg", "image/jpeg", Buffer.from("not an image"))).toEqual({
+      kind: "degraded",
+      reason: "model_no_vision",
+    });
+  });
+
+  it("gates before format and size rules so their resend advice never leaks", () => {
+    const cursorBlind = new VisionBudget(CURSOR_VISION_PROFILE, {
+      maxImageBytes: 100,
+      modelVision: false,
+    });
+    // WebP on the Cursor profile would be unsupported_format; oversized would
+    // be too_large. Blindness pre-empts both.
+    expect(cursorBlind.offer("sticker.webp", "image/webp", imageBytes("webp"))).toEqual({
+      kind: "degraded",
+      reason: "model_no_vision",
+    });
+    expect(cursorBlind.offer("big.png", "image/png", imageBytes("png", 101))).toEqual({
+      kind: "degraded",
+      reason: "model_no_vision",
+    });
+  });
+
+  it("still skips non-image input silently on a blind model", () => {
+    expect(blind().offer("doc.pdf", "application/pdf", Buffer.from("%PDF-1.7"))).toEqual({
+      kind: "skipped",
+    });
+  });
+
+  it("treats explicit true and unknown identically: fail-open", () => {
+    const sighted = new VisionBudget(DEEP_AGENT_VISION_PROFILE, { modelVision: true });
+    const unknown = new VisionBudget(DEEP_AGENT_VISION_PROFILE, { modelVision: undefined });
+    expect(sighted.offer("a.png", "image/png", imageBytes("png")).kind).toBe("accepted");
+    expect(unknown.offer("a.png", "image/png", imageBytes("png")).kind).toBe("accepted");
+  });
+
+  it("modelCannotSee + offerBlind settle a candidate without reading bytes", () => {
+    const budget = blind();
+    expect(budget.modelCannotSee()).toBe(true);
+    expect(budget.offerBlind()).toEqual({ kind: "degraded", reason: "model_no_vision" });
+
+    const sighted = new VisionBudget(DEEP_AGENT_VISION_PROFILE);
+    expect(sighted.modelCannotSee()).toBe(false);
+  });
+});
+
 describe("VisionBudget — size and count budgets", () => {
   it("accepts exactly at the per-image cap and degrades one byte over it", () => {
     const budget = new VisionBudget(DEEP_AGENT_VISION_PROFILE, {
@@ -317,6 +382,38 @@ describe("visionDisclosureLines", () => {
     expect(lines).toHaveLength(2);
   });
 
+  it("gives blind-model entries honest advice instead of the resend suggestion", () => {
+    const lines = visionDisclosureLines(
+      [],
+      [
+        { path: ".stigmer/inputs/a.png", reason: "model_no_vision" },
+        { path: ".stigmer/inputs/b.jpg", reason: "model_no_vision" },
+      ],
+    );
+    expect(lines[0]).toBe(
+      "NOT VIEWABLE INLINE: `.stigmer/inputs/a.png` (model cannot view images), " +
+        "`.stigmer/inputs/b.jpg` (model cannot view images).",
+    );
+    expect(lines[1]).toContain("does not support image input");
+    expect(lines[1]).toContain("no resend will help");
+    // The resend-smaller suggestion must never appear for a blind model.
+    expect(lines.join("\n")).not.toContain("resend it as a smaller PNG or JPEG");
+    expect(lines).toHaveLength(2);
+  });
+
+  it("keeps both advice lines, each scoped to its reasons, when reasons mix", () => {
+    const lines = visionDisclosureLines(
+      [],
+      [
+        { path: ".stigmer/inputs/big.png", reason: "too_large" },
+        { path: ".stigmer/inputs/a.png", reason: "model_no_vision" },
+      ],
+    );
+    expect(lines[1]).toContain("ask the user to resend");
+    expect(lines[2]).toContain("no resend will help");
+    expect(lines).toHaveLength(3);
+  });
+
   it("returns nothing when there is nothing to disclose", () => {
     expect(visionDisclosureLines([], [])).toEqual([]);
   });

package/src/shared/__tests__/mcp-manager.test.ts

@@ -1,4 +1,5 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import type { Connection } from "@langchain/mcp-adapters";
 import { toMcpClientConfig } from "../mcp-manager.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
 
@@ -13,6 +14,18 @@ function makeServer(overrides: Partial<ResolvedMcpServer>): ResolvedMcpServer {
   };
 }
 
+/** Narrow a Connection to its stdio variant and return its env. */
+function stdioEnv(
+  config: Record<string, Connection>,
+  slug: string,
+): Record<string, string> | undefined {
+  const conn = config[slug];
+  if (!conn || !("command" in conn)) {
+    throw new Error(`expected a stdio connection for '${slug}'`);
+  }
+  return conn.env;
+}
+
 describe("toMcpClientConfig", () => {
   it("maps stdio servers to the client config format", () => {
     const servers = [
@@ -81,3 +94,76 @@ describe("toMcpClientConfig", () => {
     expect(toMcpClientConfig([])).toEqual({});
   });
 });
+
+// Runner-internal credentials that must never reach an MCP stdio subprocess
+// (oss#256). Names mirror what the runner actually reads: config.ts,
+// fingerprint-secret.ts, model-client.ts, registry-endpoint.ts.
+const RUNNER_CREDENTIAL_KEYS = [
+  "STIGMER_RUNNER_HITL_SECRET",
+  "STIGMER_TOKEN",
+  "STIGMER_AUTH_TOKEN",
+  "CURSOR_API_KEY",
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+] as const;
+
+describe("toMcpClientConfig — stdio env isolation (oss#256)", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("gives a stdio server with no declared env none of the runner's variables", () => {
+    for (const key of RUNNER_CREDENTIAL_KEYS) {
+      vi.stubEnv(key, `leaked-${key}`);
+    }
+    vi.stubEnv("STIGMER_TEST_LEAK_SENTINEL", "canary");
+
+    const config = toMcpClientConfig([
+      makeServer({ slug: "bare", command: "some-mcp-server", env: undefined }),
+    ]);
+
+    // Passing no env means the MCP SDK supplies its minimal base environment
+    // (HOME, LOGNAME, PATH, SHELL, TERM, USER) — the runner must add nothing.
+    expect(stdioEnv(config, "bare")).toBeUndefined();
+  });
+
+  it("never copies process.env into a stdio config (fallback-reintroduction tripwire)", () => {
+    vi.stubEnv("STIGMER_TEST_LEAK_SENTINEL", "canary");
+
+    const config = toMcpClientConfig([
+      makeServer({ slug: "bare", command: "some-mcp-server", env: undefined }),
+    ]);
+
+    const env = stdioEnv(config, "bare") ?? {};
+    for (const key of Object.keys(process.env)) {
+      expect(
+        env,
+        `process.env key '${key}' must not leak into an MCP stdio env`,
+      ).not.toHaveProperty(key);
+    }
+  });
+
+  it("passes a declared env through exactly, without merging process.env", () => {
+    vi.stubEnv("STIGMER_TOKEN", "runner-secret");
+
+    const config = toMcpClientConfig([
+      makeServer({
+        slug: "declared",
+        command: "some-mcp-server",
+        env: { API_KEY: "user-value" },
+      }),
+    ]);
+
+    expect(stdioEnv(config, "declared")).toEqual({ API_KEY: "user-value" });
+  });
+
+  it("passes an empty declared env through unchanged (same child env as undeclared)", () => {
+    vi.stubEnv("STIGMER_TOKEN", "runner-secret");
+
+    const config = toMcpClientConfig([
+      makeServer({ slug: "empty", command: "some-mcp-server", env: {} }),
+    ]);
+
+    expect(stdioEnv(config, "empty")).toEqual({});
+  });
+});

package/src/shared/__tests__/model-registry.test.ts

@@ -3,6 +3,7 @@ import {
   getSummarizationModel,
   getEconomyModel,
   getDefaultModel,
+  getModelVisionCapability,
   resolveToApiModelId,
   _resetRegistryCache,
 } from "../model-registry.js";
@@ -253,6 +254,75 @@ describe("resolveToApiModelId", () => {
   });
 });
 
+describe("getModelVisionCapability", () => {
+  beforeEach(() => {
+    _resetRegistryCache();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    _resetRegistryCache();
+  });
+
+  it("returns the explicit vision flag when the capabilities block is present", async () => {
+    mockRegistryResponse([
+      { id: "claude-sonnet-4.6", provider: "anthropic", costTier: "standard", harness: "native", capabilities: { vision: true, toolUse: true } },
+      { id: "llama3.1", provider: "ollama", costTier: "economy", harness: "native", capabilities: { vision: false, toolUse: true } },
+    ]);
+
+    expect(await getModelVisionCapability("claude-sonnet-4.6")).toBe(true);
+    _resetRegistryCache();
+    mockRegistryResponse([
+      { id: "llama3.1", provider: "ollama", costTier: "economy", harness: "native", capabilities: { vision: false } },
+    ]);
+    expect(await getModelVisionCapability("llama3.1")).toBe(false);
+  });
+
+  it("returns undefined when the capabilities block is absent (never assessed ≠ blind)", async () => {
+    // The cursor-harness convention today: pricing + UI fields, no
+    // capabilities block. Must stay undefined, never coerce to false.
+    mockRegistryResponse([
+      { id: "composer-2.5", provider: "cursor", costTier: "economy", harness: "cursor" },
+    ]);
+
+    expect(await getModelVisionCapability("composer-2.5")).toBeUndefined();
+  });
+
+  it("matches by apiModelId as well as registry id", async () => {
+    // getDefaultModel() hands the deep-agent harness the provider API id, so
+    // both identifier forms must resolve to the same capability.
+    mockRegistryResponse([
+      { id: "claude-sonnet-4.6", apiModelId: "claude-sonnet-4-6", provider: "anthropic", costTier: "standard", harness: "native", capabilities: { vision: true } },
+    ]);
+
+    expect(await getModelVisionCapability("claude-sonnet-4-6")).toBe(true);
+  });
+
+  it("returns undefined for unknown names, the empty string, and the Auto pool", async () => {
+    mockRegistryResponse([
+      { id: "claude-sonnet-4.6", provider: "anthropic", costTier: "standard", harness: "native", capabilities: { vision: true } },
+    ]);
+
+    expect(await getModelVisionCapability("never-heard-of-it")).toBeUndefined();
+    expect(await getModelVisionCapability("")).toBeUndefined();
+    expect(await getModelVisionCapability("default")).toBeUndefined();
+  });
+
+  it("returns undefined when the registry fetch fails (fail-open)", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValueOnce(new Error("network error"));
+
+    expect(await getModelVisionCapability("claude-sonnet-4.6")).toBeUndefined();
+  });
+
+  it("treats a malformed capabilities value as undefined", async () => {
+    mockRegistryResponse([
+      { id: "weird-model", provider: "anthropic", costTier: "standard", harness: "native", capabilities: "yes" as unknown as { vision?: boolean } },
+    ]);
+
+    expect(await getModelVisionCapability("weird-model")).toBeUndefined();
+  });
+});
+
 interface MockModel {
   id: string;
   apiModelId?: string;
@@ -260,6 +330,7 @@ interface MockModel {
   costTier: string;
   harness: string;
   featured?: boolean;
+  capabilities?: { vision?: boolean; toolUse?: boolean };
 }
 
 function mockRegistryResponse(models: MockModel[]) {

package/src/shared/attachment-vision.ts

@@ -16,6 +16,14 @@
  * authoritative. A declared image whose bytes are not a recognizable image
  * degrades to the file-pointer story instead of shipping a mislabeled payload.
  *
+ * Model capability gate: eligibility also consults the execution model's
+ * vision capability, sourced from the model registry's `capabilities.vision`
+ * flag (model-registry.ts, `getModelVisionCapability`) and passed in at
+ * budget construction. The gate fails OPEN on unknown — only an explicit
+ * `vision: false` degrades — because most registry entries have never been
+ * capability-assessed, and blocking images on missing data would regress
+ * behavior that works today (issue #370 has the full evidence trail).
+ *
  * Degradation is always non-fatal and always disclosed: an image the model
  * cannot see is announced in the prompt (see {@link visionDisclosureLines}) so
  * the agent can tell the user instead of silently ignoring a photo the user
@@ -83,7 +91,14 @@ export type VisionDegradedReason =
   /** A real image type the current harness cannot display (e.g. WebP on Cursor). */
   | "unsupported_format"
   /** Declared as an image but the bytes are not a recognizable image (HEIC named .jpg, corrupt file). */
-  | "type_mismatch";
+  | "type_mismatch"
+  /**
+   * The model registry explicitly flags the execution's model as unable to
+   * see images (`capabilities.vision: false`). Unlike every other reason,
+   * this one is not resend-fixable — no smaller or re-encoded image can help
+   * — so the disclosure gives it its own honest wording.
+   */
+  | "model_no_vision";
 
 export type VisionOutcome =
   | { readonly kind: "accepted"; readonly image: VisionImage }
@@ -187,17 +202,32 @@ export class VisionBudget {
   private readonly maxImageBytes: number;
   private readonly maxTotalBytes: number;
   private readonly maxImages: number;
+  /**
+   * Tri-state model capability from the registry (model-registry.ts,
+   * `getModelVisionCapability`). Only an explicit `false` gates: `undefined`
+   * means the capability was never assessed (or the registry was
+   * unreachable, or the model is the Cursor "default" Auto pool), and the
+   * policy fails OPEN on unknown — degrading every image because a flag is
+   * missing would regress behavior that works today.
+   */
+  private readonly modelVision?: boolean;
   private totalBytes = 0;
   private imageCount = 0;
 
   constructor(
     profile: VisionProfile,
-    limits?: { maxImageBytes?: number; maxTotalBytes?: number; maxImages?: number },
+    options?: {
+      maxImageBytes?: number;
+      maxTotalBytes?: number;
+      maxImages?: number;
+      modelVision?: boolean;
+    },
   ) {
     this.profile = profile;
-    this.maxImageBytes = limits?.maxImageBytes ?? MAX_VISION_IMAGE_BYTES;
-    this.maxTotalBytes = limits?.maxTotalBytes ?? MAX_VISION_TOTAL_BYTES;
-    this.maxImages = limits?.maxImages ?? MAX_VISION_IMAGES;
+    this.maxImageBytes = options?.maxImageBytes ?? MAX_VISION_IMAGE_BYTES;
+    this.maxTotalBytes = options?.maxTotalBytes ?? MAX_VISION_TOTAL_BYTES;
+    this.maxImages = options?.maxImages ?? MAX_VISION_IMAGES;
+    this.modelVision = options?.modelVision;
   }
 
   /** Evaluate one attachment's bytes against every eligibility and budget rule. */
@@ -205,6 +235,17 @@ export class VisionBudget {
     const sniffed = sniffImageMime(bytes);
     const declaredIsImage = declaredType.toLowerCase().startsWith("image/");
 
+    // The blind-model gate comes before every other rule: for a model that
+    // cannot see images, format/size/budget reasons would be irrelevant and
+    // their "resend smaller" advice actively misleading. Anything
+    // image-shaped (recognizable bytes OR a declared image type) is
+    // disclosed; everything else stays on the silent file story.
+    if (this.modelVision === false) {
+      return sniffed !== undefined || declaredIsImage
+        ? { kind: "degraded", reason: "model_no_vision" }
+        : { kind: "skipped" };
+    }
+
     if (sniffed === undefined) {
       // Declared an image but isn't one we can recognize — the user plausibly
       // expects it to be seen (iPhone HEIC renamed .jpg is the common case),
@@ -250,6 +291,28 @@ export class VisionBudget {
   offerOversized(): VisionOutcome {
     return { kind: "degraded", reason: "too_large" };
   }
+
+  /**
+   * True when the model is explicitly flagged as unable to see images, so no
+   * candidate can ever be accepted. Callers on a no-read path (the Cursor
+   * local-file fast branch) check this BEFORE stat/size logic — a blind
+   * model's oversized image must report {@link offerBlind}'s honest reason,
+   * never `too_large`'s "resend smaller" advice — then record the outcome
+   * via {@link offerBlind}, mirroring the exceedsImageCap/offerOversized
+   * pattern.
+   */
+  modelCannotSee(): boolean {
+    return this.modelVision === false;
+  }
+
+  /**
+   * Record a vision candidate the caller chose not to read because
+   * {@link modelCannotSee} was true — the model's blindness alone settles
+   * the outcome.
+   */
+  offerBlind(): VisionOutcome {
+    return { kind: "degraded", reason: "model_no_vision" };
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -331,6 +394,8 @@ function reasonLabel(reason: VisionDegradedReason): string {
       return "unsupported format";
     case "type_mismatch":
       return "unreadable image format";
+    case "model_no_vision":
+      return "model cannot view images";
   }
 }
 
@@ -358,10 +423,28 @@ export function visionDisclosureLines(
       .map((e) => `\`${e.path}\` (${reasonLabel(e.reason)})`)
       .join(", ");
     lines.push(`NOT VIEWABLE INLINE: ${entries}.`);
-    lines.push(
-      "You cannot see these files; if you need one, ask the user to resend it " +
-        "as a smaller PNG or JPEG.",
-    );
+    // The advice must match the reason. Resending helps only when the image
+    // itself was the problem; for a blind model that advice would send the
+    // user on a pointless resize-and-resend errand, so that arm gets its own
+    // honest wording. (In practice a blind model degrades EVERY image, so
+    // the two lines rarely co-occur — but the wording stays reason-accurate
+    // either way.)
+    const resendFixable = notViewable.filter((e) => e.reason !== "model_no_vision");
+    const modelBlind = notViewable.filter((e) => e.reason === "model_no_vision");
+    if (resendFixable.length > 0) {
+      lines.push(
+        "You cannot see these files; if you need one, ask the user to resend it " +
+          "as a smaller PNG or JPEG.",
+      );
+    }
+    if (modelBlind.length > 0) {
+      lines.push(
+        "The current model does not support image input, so no resend will " +
+          "help. The files are saved on disk at the paths above; if the user " +
+          "needs an image understood, suggest switching to a vision-capable " +
+          "model.",
+      );
+    }
   }
   if (inlineFilenames.length > 0) {
     lines.push(

package/src/shared/mcp-manager.ts

@@ -10,9 +10,22 @@
  * resolution time by shared/mcp-transport-guard.ts — servers reaching
  * this manager have already passed it.
  *
+ * Stdio env contract (oss#256): a subprocess receives exactly the
+ * variables declared in the server's spec.env (resolved upstream by
+ * filterEnvToDeclaredKeys) plus the MCP SDK's minimal base environment
+ * (HOME, LOGNAME, PATH, SHELL, TERM, USER — getDefaultEnvironment in
+ * @modelcontextprotocol/sdk, merged under whatever we pass). The
+ * runner's own process env is never passed: it carries runner-internal
+ * credentials (STIGMER_TOKEN, STIGMER_RUNNER_HITL_SECRET,
+ * CURSOR_API_KEY, LLM provider keys) that no third-party MCP subprocess
+ * may see. A declared-empty env and an undeclared env are deliberately
+ * equivalent — both yield the SDK base environment.
+ *
  * The Cursor execution path does NOT use this manager — it passes MCP
  * configs directly to the Cursor SDK via toCursorMcpConfig(). This
- * manager is exclusively for LangGraph-based deep agent executions.
+ * manager serves LangGraph-based deep agent executions, and discovery
+ * (activities/discover-mcp-server.ts) builds its spawn config through
+ * toMcpClientConfig too.
  */
 
 import { MultiServerMCPClient } from "@langchain/mcp-adapters";
@@ -32,11 +45,18 @@ export function toMcpClientConfig(
   for (const server of servers) {
     if (server.connectionType === "stdio") {
       if (!server.command) continue;
+      if (!server.env || Object.keys(server.env).length === 0) {
+        console.log(
+          `[MCP] Server '${server.slug}' declares no env — its subprocess ` +
+          `starts with the minimal base environment only. Declare variables ` +
+          `in the McpServer's spec.env to pass them.`,
+        );
+      }
       config[server.slug] = {
         transport: "stdio",
         command: server.command,
         args: server.args ?? [],
-        env: server.env ?? processEnvAsStrings(),
+        env: server.env,
         cwd: server.cwd,
       };
     } else if (server.connectionType === "http" || server.connectionType === "sse") {
@@ -91,23 +111,3 @@ export async function connectMcpServers(
 
   return { client, tools, serverToolMap };
 }
-
-/**
- * Snapshot of process.env as a string-only record (no undefined values).
- * Used as a fallback when an MCP server has no declared env — the
- * subprocess inherits the runner's full environment, matching standard
- * Unix child-process behavior.
- *
- * Without this, @modelcontextprotocol/sdk only passes a restricted
- * whitelist (HOME, PATH, USER, etc.) which drops platform variables
- * like STIGMER_SERVER_ADDRESS.
- */
-function processEnvAsStrings(): Record<string, string> {
-  const env: Record<string, string> = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (value !== undefined) {
-      env[key] = value;
-    }
-  }
-  return env;
-}

package/src/shared/model-registry.ts

@@ -1,10 +1,13 @@
 /**
- * Model registry — provider lookup and economy-tier model derivation.
+ * Model registry — provider lookup, economy-tier model derivation, and
+ * model capability resolution.
  *
  * Fetches the model registry from the runner's control plane (see
  * registry-endpoint.ts for endpoint resolution — same endpoint as
  * model-pricing-data.ts) and uses `costTier` + `harness` fields to
- * dynamically resolve economy-tier models for extraction/summarization.
+ * dynamically resolve economy-tier models for extraction/summarization,
+ * plus `capabilities` catalog metadata for per-model capability lookups
+ * (getModelVisionCapability).
  */
 
 import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
@@ -22,6 +25,14 @@ interface RegistryModel {
   costTier: string;
   harness: string;
   featured: boolean;
+  /**
+   * Tri-state vision capability from the registry's `capabilities` block.
+   * The registry serializes `capabilities` only for models whose capabilities
+   * have actually been assessed, so `undefined` means "never assessed" —
+   * deliberately distinct from an explicit `false` ("assessed as blind").
+   * Consumers gate only on the explicit `false` (see attachment-vision.ts).
+   */
+  visionCapability?: boolean;
 }
 
 let cache: { models: readonly RegistryModel[]; expiresAt: number } | null = null;
@@ -41,9 +52,20 @@ function parseRegistry(json: unknown): RegistryModel[] {
       costTier: (m.costTier as string) ?? "standard",
       harness: (m.harness as string) ?? "native",
       featured: !!m.featured,
+      visionCapability: parseVisionCapability(m.capabilities),
     }));
 }
 
+/**
+ * Extract `capabilities.vision` preserving the tri-state: a missing or
+ * malformed `capabilities` block stays `undefined` (never coerced to false).
+ */
+function parseVisionCapability(capabilities: unknown): boolean | undefined {
+  if (!capabilities || typeof capabilities !== "object") return undefined;
+  const vision = (capabilities as Record<string, unknown>).vision;
+  return typeof vision === "boolean" ? vision : undefined;
+}
+
 async function fetchRegistry(): Promise<readonly RegistryModel[]> {
   const url = resolveModelRegistryUrl();
   const res = await fetch(url, { headers: buildRegistryHeaders() });
@@ -211,6 +233,32 @@ export async function resolveToApiModelId(registryId: string): Promise<string> {
   return entry.apiModelId ?? registryId;
 }
 
+/**
+ * Look up a model's vision capability from the registry's `capabilities`
+ * catalog metadata. Returns the tri-state the vision policy expects
+ * (attachment-vision.ts): `false` only when the registry explicitly says the
+ * model cannot see images; `undefined` whenever the answer is unknown —
+ * capability never assessed, model not in the registry, registry
+ * unreachable, or no concrete model name (the Cursor harness's ""/"default"
+ * Auto pool). Callers gate on the explicit `false` only, so every unknown
+ * degrades to today's behavior instead of blocking images.
+ *
+ * Matches by registry `id` OR `apiModelId`: getDefaultModel() hands the
+ * deep-agent harness the provider API id, while executionConfig.modelName
+ * carries the registry id, so both forms arrive here.
+ */
+export async function getModelVisionCapability(
+  modelName: string,
+): Promise<boolean | undefined> {
+  if (!modelName || modelName === "default") return undefined;
+
+  const registry = await getRegistry();
+  const entry = registry.find(
+    (m) => m.id === modelName || m.apiModelId === modelName,
+  );
+  return entry?.visionCapability;
+}
+
 /** Exposed for testing — resets the in-memory cache. */
 export function _resetRegistryCache(): void {
   cache = null;