@stigmer/runner 3.9.0 → 3.11.0

package/src/activities/execute-cursor/index.ts

@@ -64,6 +64,7 @@ import {
   toCursorImages,
   type NotViewableEntry,
 } from "../../shared/attachment-vision.js";
+import { getModelVisionCapability } from "../../shared/model-registry.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
@@ -83,6 +84,7 @@ import {
 import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment.js";
 import { mergeApprovalPolicies } from "./approval-policy.js";
 import { deriveActiveLeases, isUnattendedApprovalMode } from "../../shared/approval-policy.js";
+import { enabledToolsBySlug } from "../../shared/mcp-enabled-tools.js";
 import { backfillMcpServersIfNeeded } from "./connect-backfill.js";
 import { resolveExecutionEnv } from "./env-resolver.js";
 import { resolveBlueprint } from "./blueprint-resolver.js";
@@ -138,7 +140,7 @@ import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/
 import { activityStarted, activityFinished } from "../../idle-watchdog.js";
 import { normalizeActivityInput, type ExecuteActivityInput } from "../../shared/activity-input.js";
 import { getCapturedRejection, clearCapturedRejection } from "./rejection-capture.js";
-import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent } from "./error-classifier.js";
+import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent, extractRunErrorSources } from "./error-classifier.js";
 import type { ClassifiedError } from "./error-classifier.js";
 import { createAgent, createCloudAgent } from "./session-lifecycle.js";
 import { setMaxListeners } from "node:events";
@@ -643,9 +645,21 @@ async function executeCursorInner(
     // the messaging reach; undefined lets a cloud sandbox runner's
     // ambient session-scoped token or OSS's no-auth apply). The
     // attachment header falls back to the ambient credential where no
-    // exchange happens.
-    const exchangedRunnerToken =
-      await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    // exchange happens. Unlike the env read (which hard-fails on a broken
+    // exchange — secrets are load-bearing there), this exchange is
+    // opportunistic: every consumer below degrades to an empty answer by
+    // contract, and the server refuses the ambient fallback safely, so a
+    // failed exchange must not kill the run.
+    let exchangedRunnerToken: string | undefined;
+    try {
+      exchangedRunnerToken =
+        await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    } catch (err) {
+      console.warn(
+        "[execute-cursor] Scoped-token exchange failed for attachment/discovery " +
+        `reads; degrading to the ambient credential: ${err instanceof Error ? err.message : err}`,
+      );
+    }
     const attachmentCredential = exchangedRunnerToken
       ?? config.stigmerTokenRef?.current
       ?? config.stigmerToken;
@@ -733,11 +747,11 @@ async function executeCursorInner(
     // them as auto-approved); the global bypass empties the map entirely.
     const leases = deriveActiveLeases(execution);
     const globalBypass = leases.global;
-    const agentOverrides = blueprint.mergedMcpServerUsages
-      .flatMap((u) => u.toolApprovalOverrides ?? []);
+    // Layer-3 overrides ride each resolved server from its merged usage —
+    // see ResolvedMcpServer.toolApprovalOverrides (issue #349) — so there
+    // is no separate override input to pass here.
     const mergedPolicies = mergeApprovalPolicies(
       mcpResolution.resolvedServers,
-      agentOverrides,
       leases,
     );
     heartbeat();
@@ -770,7 +784,13 @@ async function executeCursorInner(
     // artifactStorage resolved for status offload above. The vision budget
     // rides along so image attachments are selected for inline delivery while
     // their bytes are already in hand (attachment-vision.ts owns all policy).
-    const visionBudget = new VisionBudget(CURSOR_VISION_PROFILE);
+    // The budget also carries the requested model's registry vision
+    // capability, looked up from the raw executionConfig name — full model
+    // validation (Phase 6) isn't needed for this, and ""/"default" (the Auto
+    // pool) resolves to unknown, which the policy treats as sighted.
+    const visionBudget = new VisionBudget(CURSOR_VISION_PROFILE, {
+      modelVision: await getModelVisionCapability(spec.executionConfig?.modelName ?? ""),
+    });
     const attachmentResults = await resolveAttachments(spec.attachments, {
       sessionId,
       primaryWorkspaceDir,
@@ -778,7 +798,10 @@ async function executeCursorInner(
       storage: artifactStorage,
       visionBudget,
     });
-    const attachmentPaths = attachmentResults.map((a) => a.relativePath);
+    const attachmentEntries = attachmentResults.map((a) => ({
+      path: a.relativePath,
+      ...(a.renamedFrom !== undefined ? { renamedFrom: a.renamedFrom } : {}),
+    }));
     // Vision facts, derived once from the single resolution result: the
     // images the model will see inline (in attachment order) and the ones
     // that degraded to path-only, disclosed in the prompt.
@@ -899,6 +922,11 @@ async function executeCursorInner(
       captureIgnored,
       gitWorkspace,
       isUnattendedApprovalMode(execution),
+      // The enabled_tools capability manifest (issue #350): restricted
+      // servers' allow-lists, enforced by the hook's "disabled" arm ahead of
+      // every approval bypass. The Cursor SDK config cannot hide a server's
+      // tools, so this deny-at-call is the harness's enforcement.
+      enabledToolsBySlug(mcpResolution.resolvedServers),
     );
     const hitlGate = await installHitlGate({
       workspaceRoot: primaryWorkspaceDir,
@@ -1123,7 +1151,7 @@ async function executeCursorInner(
       subAgents: blueprint.subAgents,
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
-      attachmentPaths,
+      attachments: attachmentEntries,
       vision: visionPromptInfo,
       pendingApprovals: adjudicatedApprovals,
       appliedToolCallIds,
@@ -1714,12 +1742,10 @@ async function executeCursorInner(
         status.phase = ExecutionPhase.EXECUTION_COMPLETED;
         break;
       case "error": {
-        const resultAny = result as unknown as Record<string, unknown>;
-        const sdkError = result.result
-          ?? resultAny.error
-          ?? resultAny.message
-          ?? resultAny.reason;
-        const sdkErrorStr = sdkError ? String(sdkError) : undefined;
+        // Shape-aware extraction, NOT String(): the result's error fields are
+        // structured at runtime often enough that a bare coercion showed users
+        // "[object Object]" and shadowed every fallback source below (oss#299).
+        const runErrorSources = extractRunErrorSources(result);
 
         // The SDK frequently resolves run.wait() to a bare { status: "error" }
         // while the real reason (e.g. the original grpc-status 12 routing
@@ -1731,7 +1757,8 @@ async function executeCursorInner(
         if (capturedRejection) clearCapturedRejection(executionId);
 
         const classified = synthesizeError({
-          sdkResultFields: sdkErrorStr,
+          sdkError: runErrorSources.sdkError,
+          sdkResultFields: runErrorSources.sdkResultFields,
           streamErrorMessage: turnState.streamErrorMessage,
           capturedRejection,
           conversationErrorText,
@@ -1782,7 +1809,7 @@ async function executeCursorInner(
             subAgents: blueprint.subAgents,
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
-            attachmentPaths,
+            attachments: attachmentEntries,
             vision: visionPromptInfo,
             pendingApprovals: adjudicatedApprovals,
             interactionMode,
@@ -1849,8 +1876,14 @@ async function executeCursorInner(
 
           const retryConversationErrorText = await introspectConversation(retryRun, executionId);
 
+          // Same shape-aware extraction as the primary error arm — the retry
+          // previously String()-coerced result.result alone, so a structured
+          // retry failure both read "[object Object]" and ignored the
+          // error/message/reason fields the primary arm consults.
+          const retryErrorSources = extractRunErrorSources(retryResult);
           const retryClassified = synthesizeError({
-            sdkResultFields: retryResult.result ? String(retryResult.result) : undefined,
+            sdkError: retryErrorSources.sdkError,
+            sdkResultFields: retryErrorSources.sdkResultFields,
             streamErrorMessage: turnState.streamErrorMessage,
             capturedRejection: retryRejection,
             conversationErrorText: retryConversationErrorText,
@@ -1967,6 +2000,7 @@ async function executeCursorInner(
             `finalTextLength=${finalText.length}`,
           );
           try {
+            const { extractStructuredOutput } = await import("./extract-structured-output.js");
             structuredOutput = await extractStructuredOutput(
               finalText, structuredOutputSchema, config, requestedModel,
             );
@@ -2291,53 +2325,6 @@ function seedCursorTranscriptFromExecution(
   return persisted.subAgentExecutions.map((sub) => clone(SubAgentExecutionSchema, sub));
 }
 
-// ---------------------------------------------------------------------------
-// Structured Output Extraction (Cursor Harness Tier 2)
-// ---------------------------------------------------------------------------
-
-/**
- * Extract structured data from an agent's free-text response using an
- * economy-tier LLM with withStructuredOutput (function-calling).
- * Guarantees schema-conformant JSON output via the API's tool-use mechanism.
- *
- * Construction (registry-id resolution, provider inference, proxy wiring) is
- * delegated to the shared buildChatModel so the economy model's registry id is
- * always resolved to a provider API id before the call.
- */
-async function extractStructuredOutput(
-  agentResponse: string,
-  schema: Record<string, unknown>,
-  config: Config,
-  primaryModel: string,
-): Promise<unknown | null> {
-  const { getEconomyModel } = await import("../../shared/model-registry.js");
-  const { buildChatModel } = await import("../../shared/model-client.js");
-
-  const extractionModel = await getEconomyModel(primaryModel);
-  const proxyEndpoint = config.proxyEndpoint ?? config.stigmerBackendEndpoint;
-
-  const { model: llm } = await buildChatModel({
-    modelName: extractionModel,
-    proxyEndpoint,
-    stigmerToken: config.stigmerToken ?? undefined,
-    maxTokens: 4096,
-  });
-
-  const zodSchema = jsonSchemaToZod(schema);
-  const structured = llm.withStructuredOutput(zodSchema);
-
-  const result = await structured.invoke([
-    { role: "system", content: "Extract the structured data from the agent's response. Return only the data that matches the schema." },
-    { role: "user", content: agentResponse },
-  ]);
-
-  return result ?? null;
-}
-
-// Re-export for use within this module; shared implementation eliminates
-// the three duplicate converters that previously drifted independently.
-import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
-
 // ---------------------------------------------------------------------------
 // Prompt selection
 // ---------------------------------------------------------------------------
@@ -2358,7 +2345,11 @@ export interface BuildPromptInput {
   subAgents: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
-  attachmentPaths: string[];
+  /**
+   * This turn's resolved attachments for the `<input_files>` section —
+   * final paths plus duplicate-rename disclosure (attachment-resolver.ts).
+   */
+  attachments: import("./prompt-builder.js").AttachmentPromptEntry[];
   /**
    * Vision facts for the input-files section (T04): which attachments the
    * model sees inline and which degraded to path-only. PER-TURN like the
@@ -2451,7 +2442,7 @@ export function buildPrompt(input: BuildPromptInput): string {
     subAgents,
     workspaceDirs,
     workspaceFileRefs,
-    attachmentPaths,
+    attachments,
     interactionMode,
     buildFromPlan,
     conversationCatchup,
@@ -2485,9 +2476,9 @@ export function buildPrompt(input: BuildPromptInput): string {
   if (resolution.reason === "resumed_successfully") {
     const prefixes = [
       formatInteractionModePrefix(interactionMode),
-      formatImplementPlanSection(buildFromPlan, attachmentPaths),
-      attachmentPaths.length > 0
-        ? formatInputFiles(attachmentPaths, input.vision)
+      formatImplementPlanSection(buildFromPlan, attachments),
+      attachments.length > 0
+        ? formatInputFiles(attachments, input.vision)
         : undefined,
       conversationCatchup !== undefined
         ? formatConversationCatchupSection(conversationCatchup)
@@ -2510,7 +2501,7 @@ export function buildPrompt(input: BuildPromptInput): string {
     subAgents,
     workspaceDirs,
     workspaceFileRefs,
-    attachmentPaths,
+    attachments,
     vision: input.vision,
     interactionMode,
     buildFromPlan,

package/src/activities/execute-cursor/mcp-resolver.ts

@@ -14,7 +14,7 @@
  * same pipeline as the Python agent-runner's config_transformer.py.
  */
 
-import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { McpServerUsage, ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { StigmerClient } from "../../client/stigmer-client.js";
@@ -29,6 +29,7 @@ import {
   filterEnvToDeclaredKeys,
   PlaceholderResolutionError,
 } from "./placeholder-resolver.js";
+import { effectiveEnabledTools } from "../../shared/mcp-enabled-tools.js";
 
 /**
  * Cursor SDK MCP server config shape (matches @cursor/sdk McpServerConfig).
@@ -70,6 +71,29 @@ export interface ResolvedMcpServer {
   pinnedToolApprovals: ToolApprovalPolicy[];
   /** True when the server has never been connected (no tool discovery yet). */
   discoveredCapabilitiesEmpty: boolean;
+  /**
+   * The EFFECTIVE tool allow-list for this server (issue #350): the usage's
+   * enabled_tools, falling back to the server's default_enabled_tools when
+   * the usage's list is empty (see shared/mcp-enabled-tools.ts). Absent when
+   * unrestricted. The Cursor SDK config cannot hide tools, so this harness
+   * enforces it in the HITL hook: the restricted map is written into the
+   * approval state (mcpServerEnabledTools) and non-enabled calls are denied
+   * with the non-pausing "disabled" kind (see hook-script.ts).
+   */
+  enabledTools?: string[];
+  /**
+   * Layer-3 per-agent approval overrides from the usage that resolved this
+   * server (issue #349): riding the resolved server is what SCOPES an
+   * override to its own server — a flat cross-server list is how an
+   * override once leaked onto (or silently un-gated) a same-named tool on
+   * another server. Deliberately REQUIRED, not optional: empty means "no
+   * overrides", and every construction site — including the shared
+   * resolver this one mirrors and the synthesized attachments, which have
+   * no usage and therefore no layer 3 — must say so explicitly, so a
+   * forgotten mirror cannot compile. Consumed by mergeApprovalPolicies
+   * (shared/approval-policy.ts).
+   */
+  toolApprovalOverrides: ToolApprovalOverride[];
 }
 
 /**
@@ -115,7 +139,13 @@ export async function resolveMcpServers(
         envVars,
         ref.slug,
       );
-      const server = mcpServerToResolved(mcpServer, ref.slug, serverEnv);
+      const server = mcpServerToResolved(
+        mcpServer,
+        ref.slug,
+        serverEnv,
+        usage.enabledTools,
+        usage.toolApprovalOverrides ?? [],
+      );
       if (server) {
         assertTransportAllowed(server.slug, server.connectionType, transportPosture);
         resolved.push(server);
@@ -152,6 +182,8 @@ function mcpServerToResolved(
   server: McpServer,
   slug: string,
   envVars: Record<string, string>,
+  usageEnabledTools?: readonly string[],
+  usageToolApprovalOverrides: ToolApprovalOverride[] = [],
 ): ResolvedMcpServer | null {
   const spec = server.spec;
   if (!spec) return null;
@@ -167,6 +199,8 @@ function mcpServerToResolved(
     toolApprovals,
     pinnedToolApprovals,
     discoveredCapabilitiesEmpty,
+    enabledTools: effectiveEnabledTools(usageEnabledTools, spec.defaultEnabledTools),
+    toolApprovalOverrides: usageToolApprovalOverrides,
   };
 
   switch (spec.serverType.case) {

package/src/activities/execute-cursor/prompt-builder.ts

@@ -71,6 +71,18 @@ export interface VisionPromptInfo {
   notViewable: NotViewableEntry[];
 }
 
+/**
+ * One resolved attachment as the `<input_files>` section renders it —
+ * the final workspace-relative path plus the duplicate-rename disclosure
+ * (attachment-resolver.ts / shared/attachment-naming.ts).
+ */
+export interface AttachmentPromptEntry {
+  /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
+  path: string;
+  /** Original filename, present only when a duplicate name was renamed. */
+  renamedFrom?: string;
+}
+
 export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
@@ -78,7 +90,10 @@ export interface EnhancedPromptOptions {
   /**
    * Datastores attached via `datastore_usages` — rendered as the
    * `<available_datastores>` section (DD-005 SD-5, skills precedent)
-   * pointing the model at the synthesized record tools.
+   * pointing the model at the synthesized record tools. Always the healthy
+   * rendering here: the Cursor SDK connects MCP itself, so this harness can
+   * never observe the live roster — the section's standing
+   * failure-disclosure instruction is its whole coverage (issue #325).
    */
   datastoreUsages?: DatastoreUsage[];
   /**
@@ -90,7 +105,7 @@ export interface EnhancedPromptOptions {
   subAgents: SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
-  attachmentPaths: string[];
+  attachments: AttachmentPromptEntry[];
   /** Inline/degraded image facts for the input-files section (T04 vision). */
   vision?: VisionPromptInfo;
   interactionMode?: InteractionMode;
@@ -153,7 +168,7 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
 
   const implementPlan = formatImplementPlanSection(
     options.buildFromPlan,
-    options.attachmentPaths,
+    options.attachments,
   );
   if (implementPlan) {
     sections.push(implementPlan);
@@ -195,8 +210,8 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatWorkspaceContext(safeDirs));
   }
 
-  if (options.attachmentPaths.length > 0) {
-    sections.push(formatInputFiles(options.attachmentPaths, options.vision));
+  if (options.attachments.length > 0) {
+    sections.push(formatInputFiles(options.attachments, options.vision));
   }
 
   if (options.workspaceFileRefs.length > 0) {
@@ -479,8 +494,18 @@ export function formatWorkspaceContext(dirs: string[]): string {
   ].join("\n");
 }
 
-export function formatInputFiles(paths: string[], vision?: VisionPromptInfo): string {
-  const entries = paths.map((p) => `- \`${p}\``);
+export function formatInputFiles(
+  attachments: readonly AttachmentPromptEntry[],
+  vision?: VisionPromptInfo,
+): string {
+  // A duplicate-renamed file (attachment-naming.ts) discloses its original
+  // name so the agent can connect "the two report.pdfs" in the user's
+  // message to distinct files on disk.
+  const entries = attachments.map((a) =>
+    a.renamedFrom !== undefined
+      ? `- \`${a.path}\` (renamed from duplicate '${a.renamedFrom}')`
+      : `- \`${a.path}\``,
+  );
   // The vision lines (shared wording, attachment-vision.ts) tell the model
   // which of these files it can already SEE inline versus which degraded to
   // path-only — without them an agent silently ignores a photo the user
@@ -541,14 +566,14 @@ export function formatInteractionModePrefix(
  */
 export function formatImplementPlanSection(
   buildFromPlan: boolean | undefined,
-  attachmentPaths: string[],
+  attachments: readonly AttachmentPromptEntry[],
 ): string | undefined {
   if (!buildFromPlan) {
     return undefined;
   }
 
   const directive = buildImplementPlanDirective(
-    findApprovedPlanPath(attachmentPaths),
+    findApprovedPlanPath(attachments.map((a) => a.path)),
   );
   return ["<implement_plan>", directive, "</implement_plan>"].join("\n");
 }

package/src/activities/execute-cursor/turn-stream.ts

@@ -387,8 +387,11 @@ export async function consumeCursorTurnStream(
         console.log(
           `ExecuteCursor stream status: execution=${executionId}, status=${JSON.stringify(event)}`,
         );
-        const statusEvent = event as { status?: string; message?: string };
-        if (statusEvent.status === "ERROR" && statusEvent.message) {
+        const statusEvent = event as { status?: string; message?: unknown };
+        // The cast is a claim, not a guarantee: message is untyped at runtime
+        // (the oss#299 class of bug). A structured value here would crash
+        // classification downstream, so only capture actual text.
+        if (statusEvent.status === "ERROR" && typeof statusEvent.message === "string" && statusEvent.message.length > 0) {
           state.streamErrorMessage = statusEvent.message;
         }
       }

package/src/activities/execute-deep-agent/__tests__/attachment-injector.test.ts

@@ -600,24 +600,97 @@ describe("injectAttachments", () => {
     expect(Buffer.compare(writtenBuffer, binaryContent)).toBe(0);
   });
 
-  it("detects mount path collision before any downloads", async () => {
+  it("uniquifies duplicate default-derived filenames instead of failing (issue #364)", async () => {
+    const contentA = Buffer.from("first");
+    const contentB = Buffer.from("second");
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/data.csv", contentA);
+    await storage.upload("attachments/b/data.csv", contentB);
+
+    const backend = mockWorkspaceBackend();
+
+    const result = await injectAttachments({
+      backend,
+      attachments: [
+        makeAttachment({ filename: "data.csv", storageKey: "attachments/a/data.csv" }),
+        makeAttachment({ filename: "data.csv", storageKey: "attachments/b/data.csv" }),
+      ],
+      storage,
+      isLocalMode: false,
+    });
+
+    // Both files land, both downloads run — the execution is never burned
+    // over a mechanically resolvable name.
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({
+      filename: "data.csv",
+      path: ".stigmer/inputs/data.csv",
+    });
+    expect(result[0].renamedFrom).toBeUndefined();
+    // The rename follows the platform's stem-2.ext semantics and carries the
+    // disclosure payload for the prompt.
+    expect(result[1]).toMatchObject({
+      filename: "data-2.csv",
+      path: ".stigmer/inputs/data-2.csv",
+      renamedFrom: "data.csv",
+    });
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/data.csv", contentA,
+    );
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/data-2.csv", contentB,
+    );
+  });
+
+  it("rejects two attachments explicitly pinning the same mountPath (a user contradiction)", async () => {
     const backend = mockWorkspaceBackend();
     const storage = makeMockStorage();
 
     await expect(injectAttachments({
       backend,
       attachments: [
-        makeAttachment({ filename: "data.csv", storageKey: "key1" }),
-        makeAttachment({ filename: "data.csv", storageKey: "key2" }),
+        makeAttachment({ filename: "a.csv", storageKey: "key1", mountPath: "inputs/data.csv" }),
+        makeAttachment({ filename: "b.csv", storageKey: "key2", mountPath: "inputs/data.csv" }),
       ],
       storage,
       isLocalMode: false,
     })).rejects.toThrow(/collides with/);
 
-    // Verify no downloads were attempted
+    // The contradiction is detected before any downloads
     expect(storage.download).not.toHaveBeenCalled();
   });
 
+  it("default-derived names dodge an explicit mountPath already inside the inputs prefix", async () => {
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/pinned", Buffer.from("pinned"));
+    await storage.upload("attachments/b/report.pdf", Buffer.from("derived"));
+
+    const backend = mockWorkspaceBackend();
+
+    const result = await injectAttachments({
+      backend,
+      attachments: [
+        // Listed AFTER the default-derived attachment: explicit paths claim
+        // first regardless of order, so the default still dodges.
+        makeAttachment({ filename: "report.pdf", storageKey: "attachments/b/report.pdf" }),
+        makeAttachment({
+          filename: "report.pdf",
+          storageKey: "attachments/a/pinned",
+          mountPath: ".stigmer/inputs/report.pdf",
+        }),
+      ],
+      storage,
+      isLocalMode: false,
+    });
+
+    const byPath = new Map(result.map((f) => [f.path, f]));
+    expect(byPath.get(".stigmer/inputs/report.pdf")?.renamedFrom).toBeUndefined();
+    expect(byPath.get(".stigmer/inputs/report-2.pdf")).toMatchObject({
+      filename: "report-2.pdf",
+      renamedFrom: "report.pdf",
+    });
+  });
+
   it("derives filename from storageKey when filename is empty", async () => {
     const content = Buffer.from("fallback");
     const localFile = join(tempDir, "fallback.txt");
@@ -662,7 +735,7 @@ describe("injectAttachments", () => {
     expect(result[0].path).toBe("workspace/input.csv");
   });
 
-  it("error message includes attachment filename and actionable suggestion", async () => {
+  it("explicit-collision error names both attachments and stays actionable", async () => {
     const backend = mockWorkspaceBackend();
     const storage = makeMockStorage();
 
@@ -670,8 +743,8 @@ describe("injectAttachments", () => {
       await injectAttachments({
         backend,
         attachments: [
-          makeAttachment({ filename: "first.csv" }),
-          makeAttachment({ filename: "first.csv", storageKey: "key2" }),
+          makeAttachment({ filename: "first.csv", mountPath: "inputs/shared.csv" }),
+          makeAttachment({ filename: "second.csv", storageKey: "key2", mountPath: "inputs/shared.csv" }),
         ],
         storage,
         isLocalMode: false,
@@ -680,7 +753,7 @@ describe("injectAttachments", () => {
     } catch (err) {
       expect(err).toBeInstanceOf(AttachmentInjectionError);
       const injErr = err as AttachmentInjectionError;
-      expect(injErr.attachmentFilename).toBe("first.csv");
+      expect(injErr.attachmentFilename).toBe("second.csv");
       expect(injErr.message).toContain("first.csv");
       expect(injErr.message).toContain("mountPath");
     }
@@ -776,6 +849,28 @@ describe("injectAttachments — vision selection", () => {
     expect(backend.writeFileBuffer).toHaveBeenCalledWith(".stigmer/inputs/photo.png", PNG_BYTES);
   });
 
+  it("degrades an image with model_no_vision on a blind model, file written intact", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/photo.png", PNG_BYTES);
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "photo.png",
+        storageKey: "attachments/abc/photo.png",
+        contentType: "image/png",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE, { modelVision: false }),
+    });
+
+    expect(injected.vision).toBeUndefined();
+    expect(injected.visionDegraded).toBe("model_no_vision");
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(".stigmer/inputs/photo.png", PNG_BYTES);
+  });
+
   it("accepts WebP on the deep-agent profile (unlike the Cursor harness)", async () => {
     const backend = mockWorkspaceBackend();
     const storage = makeMockStorage();
@@ -838,6 +933,35 @@ describe("injectAttachments — vision selection", () => {
     expect(injected.visionDegraded).toBe("type_mismatch");
   });
 
+  it("labels a duplicate-renamed image's vision payload with the on-disk name", async () => {
+    // Coherence pin: the prompt lists the renamed path and the vision
+    // disclosure lists image filenames — if the offer used the original
+    // attachment.filename, the agent would see two images with one
+    // indistinguishable name.
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/photo.png", PNG_BYTES);
+    await storage.upload("attachments/b/photo.png", PNG_BYTES);
+
+    const injected = await injectAttachments({
+      backend,
+      attachments: [
+        makeAttachment({ filename: "photo.png", storageKey: "attachments/a/photo.png", contentType: "image/png" }),
+        makeAttachment({ filename: "photo.png", storageKey: "attachments/b/photo.png", contentType: "image/png" }),
+      ],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected[0].vision?.filename).toBe("photo.png");
+    expect(injected[1]).toMatchObject({
+      filename: "photo-2.png",
+      renamedFrom: "photo.png",
+    });
+    expect(injected[1].vision?.filename).toBe("photo-2.png");
+  });
+
   it("never offers an extract archive to the budget — extracted files carry no vision fields", async () => {
     // A PNG inside a ZIP has no attachment-level bytes; the archive rides the
     // normal extraction story with no vision involvement or disclosure.