@stigmer/runner 3.7.0 → 3.9.0

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

@@ -15,6 +15,10 @@ import {
 } from "../attachment-injector.js";
 import { mockWorkspaceBackend } from "../../../__test-utils__/mock-workspace.js";
 import { makeInMemoryArtifactStorage } from "../../../__test-utils__/fake-artifact-storage.js";
+import {
+  DEEP_AGENT_VISION_PROFILE,
+  VisionBudget,
+} from "../../../shared/attachment-vision.js";
 
 // ── ZIP Construction Helpers ─────────────────────────────────────────
 
@@ -552,6 +556,28 @@ describe("injectAttachments", () => {
     })).rejects.toThrow(/missing storageKey/);
   });
 
+  it("rejects a caller-supplied mountPath that escapes the workspace root", async () => {
+    // `resolveMountPath` only stripped leading slashes, so `..` segments on a
+    // non-`.stigmer/` mount path reached the unchecked join(rootDir, path).
+    const storage = makeMockStorage();
+    storage.download.mockResolvedValue(Buffer.from("owned"));
+    const backend = mockWorkspaceBackend();
+
+    const escapes = ["../../escape.txt", "../etc/evil", "foo/../../bar"];
+    for (const mountPath of escapes) {
+      await expect(injectAttachments({
+        backend,
+        attachments: [makeAttachment({
+          filename: "data.txt",
+          storageKey: "attachments/xyz/data.txt",
+          mountPath,
+        })],
+        storage,
+        isLocalMode: false,
+      })).rejects.toThrow(/mount path .* escapes the workspace root|traversal/i);
+    }
+  });
+
   it("preserves binary content via writeFileBuffer", async () => {
     const binaryContent = Buffer.from([0x00, 0x01, 0xFF, 0xFE, 0x89, 0x50, 0x4E, 0x47]);
     const localFile = join(tempDir, "image.png");
@@ -705,3 +731,162 @@ describe("injectAttachments", () => {
     })).rejects.toThrow(AttachmentValidationError);
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════
+// Vision selection during injection (T04)
+// ═══════════════════════════════════════════════════════════════════════
+// Vision is strictly additive: every case also asserts the file was written
+// exactly as it would be without a budget.
+
+describe("injectAttachments — vision selection", () => {
+  const PNG_BYTES = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    Buffer.alloc(56, 0xab),
+  ]);
+  const WEBP_BYTES = Buffer.concat([
+    Buffer.from("RIFF", "ascii"),
+    Buffer.from([0x24, 0x00, 0x00, 0x00]),
+    Buffer.from("WEBP", "ascii"),
+    Buffer.alloc(52, 0xcd),
+  ]);
+
+  it("accepts a PNG into the vision payload (deep-agent profile) and still writes the file", 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),
+    });
+
+    expect(injected.vision).toMatchObject({
+      filename: "photo.png",
+      mimeType: "image/png",
+      byteSize: PNG_BYTES.length,
+    });
+    expect(Buffer.from(injected.vision!.base64, "base64").equals(PNG_BYTES)).toBe(true);
+    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();
+    await storage.upload("attachments/abc/pic.webp", WEBP_BYTES);
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "pic.webp",
+        storageKey: "attachments/abc/pic.webp",
+        contentType: "image/webp",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision?.mimeType).toBe("image/webp");
+  });
+
+  it("carries no vision fields for a non-image attachment", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/doc.pdf", Buffer.from("%PDF-1.7"));
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "doc.pdf",
+        storageKey: "attachments/abc/doc.pdf",
+        contentType: "application/pdf",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision).toBeUndefined();
+    expect(injected.visionDegraded).toBeUndefined();
+  });
+
+  it("degrades a declared image whose bytes are not one (type_mismatch)", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/photo.jpg", Buffer.from("actually HEIC"));
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "photo.jpg",
+        storageKey: "attachments/abc/photo.jpg",
+        contentType: "image/jpeg",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision).toBeUndefined();
+    expect(injected.visionDegraded).toBe("type_mismatch");
+  });
+
+  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.
+    const zip = makeZip({ "inner.png": PNG_BYTES });
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/bundle.zip", zip);
+
+    const injected = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "bundle.zip",
+        storageKey: "attachments/abc/bundle.zip",
+        extract: true,
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.length).toBeGreaterThan(0);
+    for (const file of injected) {
+      expect(file.vision).toBeUndefined();
+      expect(file.visionDegraded).toBeUndefined();
+    }
+  });
+
+  it("degrades over the total budget in attachment order (budget_exhausted)", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/a.png", PNG_BYTES);
+    await storage.upload("attachments/b/b.png", PNG_BYTES);
+
+    const injected = await injectAttachments({
+      backend,
+      attachments: [
+        makeAttachment({ filename: "a.png", storageKey: "attachments/a/a.png", contentType: "image/png" }),
+        makeAttachment({ filename: "b.png", storageKey: "attachments/b/b.png", contentType: "image/png" }),
+      ],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE, {
+        maxImageBytes: PNG_BYTES.length,
+        maxTotalBytes: PNG_BYTES.length,
+      }),
+    });
+
+    expect(injected[0].vision).toBeDefined();
+    expect(injected[1].vision).toBeUndefined();
+    expect(injected[1].visionDegraded).toBe("budget_exhausted");
+  });
+});

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

@@ -70,23 +70,23 @@ function makeGraphState(
 }
 
 describe("resolveResumeInput", () => {
-  it("returns fresh input when no interrupts exist", () => {
+  it("reports not-a-resume when no interrupts exist (caller falls back to setup.langgraphInput)", () => {
     const execution = makeExecution([]);
     const state: GraphStateSnapshot = { values: {}, tasks: [] };
 
-    const result = resolveResumeInput(execution, state, "hello");
+    const result = resolveResumeInput(execution, state);
 
     expect(result.isResumeFromApproval).toBe(false);
-    expect(result.graphInput).toEqual({
-      messages: [{ role: "user", content: "hello" }],
-    });
+    // No graphInput on this branch — the turn's user message has exactly ONE
+    // construction site (setup.langgraphInput), never a second copy here.
+    expect("graphInput" in result).toBe(false);
   });
 
-  it("returns fresh input when interrupts exist but no decisions", () => {
+  it("reports not-a-resume when interrupts exist but no decisions", () => {
     const execution = makeExecution([]);
     const state = makeGraphState([{ taskId: "task-1", toolCallId: "call-1" }]);
 
-    const result = resolveResumeInput(execution, state, "hello");
+    const result = resolveResumeInput(execution, state);
 
     expect(result.isResumeFromApproval).toBe(false);
   });
@@ -100,9 +100,9 @@ describe("resolveResumeInput", () => {
 
     const state = makeGraphState([{ taskId: "task-1", toolCallId: "call-1" }]);
 
-    const result = resolveResumeInput(execution, state, "hello");
+    const result = resolveResumeInput(execution, state);
 
-    expect(result.isResumeFromApproval).toBe(true);
+    if (!result.isResumeFromApproval) throw new Error("expected an approval resume");
     expect(result.graphInput).toBeInstanceOf(Command);
   });
 
@@ -115,13 +115,13 @@ describe("resolveResumeInput", () => {
 
     const state = makeGraphState([{ taskId: "task-1", toolCallId: "call-1" }]);
 
-    const result = resolveResumeInput(execution, state, "hello");
+    const result = resolveResumeInput(execution, state);
 
     // REJECT resumes the gate like any other decision — the gate returns a
     // denial ToolMessage and the run continues. There is no execution-level
     // "rejection" flag any more; the terminal tool status is set by
     // reconcileNonExecutingDecisions.
-    expect(result.isResumeFromApproval).toBe(true);
+    if (!result.isResumeFromApproval) throw new Error("expected an approval resume");
     expect(result.graphInput).toBeInstanceOf(Command);
   });
 
@@ -144,7 +144,7 @@ describe("resolveResumeInput", () => {
       { taskId: "task-2", toolCallId: "call-2" },
     ]);
 
-    const result = resolveResumeInput(execution, state, "hello");
+    const result = resolveResumeInput(execution, state);
 
     expect(result.isResumeFromApproval).toBe(true);
   });
@@ -160,7 +160,7 @@ describe("resolveResumeInput", () => {
       { taskId: "task-1", toolCallId: "call-1", hasResume: true },
     ]);
 
-    const result = resolveResumeInput(execution, state, "hello");
+    const result = resolveResumeInput(execution, state);
 
     expect(result.isResumeFromApproval).toBe(false);
   });

package/src/activities/execute-deep-agent/__tests__/mcp-gate.test.ts

@@ -0,0 +1,42 @@
+/**
+ * The deep-agent MCP gate, arm by arm. A missing arm here means a tool
+ * source silently dropped for exactly the agents whose only source it
+ * is — the failure DD-006 D7 documented for channel messaging and the
+ * reason the predicate lives in its own testable module instead of
+ * inline in setup.ts (whose import graph forbids a setup.test.ts).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { shouldConnectMcp } from "../mcp-gate.js";
+
+const nothing = {
+  mcpServerUsageCount: 0,
+  datastoreUsageCount: 0,
+  channelMessagingCount: 0,
+  conversationChannelId: undefined,
+};
+
+describe("shouldConnectMcp", () => {
+  it("skips the MCP block when no tool source exists", () => {
+    expect(shouldConnectMcp(nothing)).toBe(false);
+  });
+
+  it("enters on declared MCP server usages alone", () => {
+    expect(shouldConnectMcp({ ...nothing, mcpServerUsageCount: 1 })).toBe(true);
+  });
+
+  it("enters on datastore usages alone (the records attachment)", () => {
+    expect(shouldConnectMcp({ ...nothing, datastoreUsageCount: 1 })).toBe(true);
+  });
+
+  it("enters on a serving proactive channel alone (the channels attachment)", () => {
+    expect(shouldConnectMcp({ ...nothing, channelMessagingCount: 1 })).toBe(true);
+  });
+
+  it("enters on a channel conversation alone (the conversation attachment)", () => {
+    // The reply-only pilot shape: no declared servers, no datastores,
+    // no proactive channel — the escalation tool is the ONLY source.
+    expect(shouldConnectMcp({ ...nothing, conversationChannelId: "agch_1" })).toBe(true);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/prompt-builder.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { buildEnhancedSystemPrompt } from "../prompt-builder.js";
+import { buildEnhancedSystemPrompt, composeUserMessage } from "../prompt-builder.js";
 import { PLAN_MODE_DIRECTIVE } from "../../../shared/plan-mode-prompt.js";
 import { SourceType } from "../../../shared/workspace/types.js";
 import type { ProvisionResult } from "../../../shared/workspace/types.js";
@@ -408,3 +408,41 @@ describe("buildEnhancedSystemPrompt", () => {
     });
   });
 });
+
+describe("composeUserMessage (conversation catchup, cloud DD-006 / A27)", () => {
+  const MESSAGE = "where is my order?";
+  const DIGEST =
+    "Customer: I want a refund\nTeammate: I've refunded you in full.";
+
+  it("prepends the framed catchup to the turn's user message — history durability rides the checkpointer, not the rebuilt system prompt", () => {
+    const composed = composeUserMessage(MESSAGE, DIGEST);
+
+    expect(composed.endsWith(MESSAGE)).toBe(true);
+    expect(composed).toContain(DIGEST);
+    expect(composed).toContain("you have not seen");
+    expect(composed.indexOf(DIGEST)).toBeLessThan(composed.indexOf(MESSAGE));
+  });
+
+  it("separates the catchup from the customer's message with a horizontal rule", () => {
+    expect(composeUserMessage(MESSAGE, DIGEST)).toContain("\n\n---\n\n");
+  });
+
+  it("leaves the message untouched when there is no catchup — most turns carry none", () => {
+    expect(composeUserMessage(MESSAGE, undefined)).toBe(MESSAGE);
+  });
+
+  it("never renders in the system prompt — the rebuilt-per-invocation lane would forget the digest one turn later", () => {
+    const prompt = buildEnhancedSystemPrompt({
+      instructions: "Test",
+      provisionResults: [],
+      containerRoot: "",
+      skillsPromptSection: "",
+      workspaceFileRefs: [],
+      workspaceRoot: "/workspace",
+      injectedFiles: [],
+    });
+
+    expect(prompt).not.toContain("Conversation catchup");
+    expect(prompt).not.toContain("you have not seen");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/vision-input.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Proves the T04 vision input path end-to-end through the REAL framework
+ * stack: the exact `{ role: "user", content: [...] }` shape that setup.ts
+ * builds is driven through `createDeepAgent` (the production graph factory,
+ * default middleware included) and the test asserts what the chat model's
+ * `_generate` actually received.
+ *
+ * This is the offline stand-in for the deferred live provider probes (T01
+ * A4/A5): it cannot prove Anthropic renders the pixels, but it proves the
+ * image blocks survive the LangGraph message reducer and the full deepagents
+ * middleware stack byte-identically — the part of the path we own.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { BaseMessage } from "@langchain/core/messages";
+import { HumanMessage } from "@langchain/core/messages";
+import type { ChatResult } from "@langchain/core/outputs";
+import { MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent } from "deepagents";
+import { createCasCaptureBackend } from "../cas-capture-backend.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import {
+  ScriptedModel,
+  type ScriptSelector,
+} from "../__test-utils__/scripted-model.js";
+import {
+  DEEP_AGENT_VISION_PROFILE,
+  VisionBudget,
+  toLangChainImageBlocks,
+  type LangChainContentBlock,
+  type VisionImage,
+} from "../../../shared/attachment-vision.js";
+
+/**
+ * A ScriptedModel that records every `_generate` input. `bindTools` must
+ * return a NEW capturing instance sharing the same capture array — the base
+ * class re-instantiates itself on bind, which would silently drop the spy.
+ */
+class CapturingModel extends ScriptedModel {
+  constructor(
+    private readonly selectFn: ScriptSelector,
+    private readonly captured: BaseMessage[][],
+  ) {
+    super(selectFn);
+  }
+
+  // Reports as ChatAnthropic so createDeepAgent engages the same
+  // anthropic-prompt-caching middleware a production run gets — the stack the
+  // image blocks must survive.
+  override getName(): string {
+    return "ChatAnthropic";
+  }
+
+  override bindTools(tools: unknown[]): this {
+    const next = new CapturingModel(this.selectFn, this.captured);
+    next.toolNames = (tools as Array<{ name?: string }>).map((t) => t?.name ?? "");
+    return next as unknown as this;
+  }
+
+  override async _generate(messages: BaseMessage[]): Promise<ChatResult> {
+    this.captured.push(messages);
+    return super._generate(messages);
+  }
+}
+
+function makeVisionImage(filename: string): VisionImage {
+  const pngBytes = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    Buffer.alloc(56, 0xab),
+  ]);
+  const outcome = new VisionBudget(DEEP_AGENT_VISION_PROFILE).offer(
+    filename,
+    "image/png",
+    pngBytes,
+  );
+  if (outcome.kind !== "accepted") throw new Error("fixture PNG must be accepted");
+  return outcome.image;
+}
+
+describe("deep-agent vision input through the real graph", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "vision-input-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * `content` is exactly what setup.ts puts on the user message: a plain
+   * string, or the content-block array built by toLangChainImageBlocks plus
+   * the composed text block.
+   */
+  async function invokeGraphWith(
+    content: string | LangChainContentBlock[],
+  ): Promise<BaseMessage[][]> {
+    const captured: BaseMessage[][] = [];
+    const script: ScriptSelector = () => ({ toolCalls: [], done: "seen" });
+
+    const observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => false });
+    const backend = await createCasCaptureBackend({ rootDir: root, observer, shellEnv: {} });
+
+    const agent = await createDeepAgent({
+      model: new CapturingModel(script, captured),
+      checkpointer: new MemorySaver() as never,
+      backend,
+    } as Parameters<typeof createDeepAgent>[0]);
+
+    // The EXACT input shape setup.ts constructs (plain role/content dict, not
+    // a HumanMessage instance — the reducer does the coercion in production).
+    await agent.invoke(
+      { messages: [{ role: "user", content }] },
+      { configurable: { thread_id: "vision-thread" }, recursionLimit: 10 },
+    );
+    return captured;
+  }
+
+  it("delivers image_url blocks (labels first, text last) to the model byte-identically", async () => {
+    const image = makeVisionImage("photo.png");
+    const content: LangChainContentBlock[] = [
+      ...toLangChainImageBlocks([image]),
+      { type: "text", text: "what is in this image?" },
+    ];
+
+    const captured = await invokeGraphWith(content);
+
+    expect(captured.length).toBeGreaterThan(0);
+    const human = captured[0].find((m): m is HumanMessage => m instanceof HumanMessage);
+    expect(human).toBeDefined();
+    expect(human!.content).toEqual([
+      { type: "text", text: "Image 1: photo.png" },
+      {
+        type: "image_url",
+        image_url: { url: `data:image/png;base64,${image.base64}` },
+      },
+      { type: "text", text: "what is in this image?" },
+    ]);
+  });
+
+  it("keeps a plain-string user message untouched (the no-attachment path)", async () => {
+    const captured = await invokeGraphWith("just text, no images");
+
+    const human = captured[0].find((m): m is HumanMessage => m instanceof HumanMessage);
+    expect(human).toBeDefined();
+    expect(human!.content).toBe("just text, no images");
+  });
+});

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

@@ -20,6 +20,11 @@ import { basename, posix } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import type {
+  VisionBudget,
+  VisionDegradedReason,
+  VisionImage,
+} from "../../shared/attachment-vision.js";
 
 // ── Constants ────────────────────────────────────────────────────────
 
@@ -36,6 +41,15 @@ export interface InjectedFile {
   readonly filename: string;
   readonly path: string;
   readonly sizeBytes: number;
+  /** Present when the attachment was accepted into the turn's vision payload. */
+  readonly vision?: VisionImage;
+  /**
+   * Present when the attachment was plausibly an image but could not ride
+   * inline (see {@link VisionDegradedReason}) — disclosed in the system prompt
+   * so the agent never silently ignores a photo the user believes it can see.
+   * Attachments that were never image-shaped carry neither field.
+   */
+  readonly visionDegraded?: VisionDegradedReason;
 }
 
 export interface InjectAttachmentsOptions {
@@ -50,6 +64,13 @@ export interface InjectAttachmentsOptions {
    */
   readonly storage: ArtifactStorage | undefined;
   readonly isLocalMode: boolean;
+  /**
+   * The turn's vision selector (attachment-vision.ts owns all policy).
+   * `undefined` disables inline image delivery; file materialization is
+   * identical either way — vision is strictly additive. Archives (`extract`)
+   * are never offered: an image inside a ZIP has no attachment-level bytes.
+   */
+  readonly visionBudget?: VisionBudget;
 }
 
 export interface ZipEntryInfo {
@@ -240,7 +261,7 @@ export function validateZipForExtraction(
  * On any failure, throws AttachmentInjectionError with an actionable message.
  */
 export async function injectAttachments(opts: InjectAttachmentsOptions): Promise<InjectedFile[]> {
-  const { backend, attachments, storage, isLocalMode } = opts;
+  const { backend, attachments, storage, isLocalMode, visionBudget } = opts;
 
   if (attachments.length === 0) return [];
 
@@ -262,10 +283,17 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
       injectedFiles.push(...extracted);
     } else {
       await backend.writeFileBuffer(mountPath, content);
+      const filename = attachment.filename || basename(mountPath);
+      // The bytes are already in hand for the workspace write — offer them to
+      // the vision budget before they go out of scope (the sniff decides
+      // eligibility; the budget owns every size/count rule).
+      const vision = visionBudget?.offer(filename, attachment.contentType, content);
       injectedFiles.push({
-        filename: attachment.filename || basename(mountPath),
+        filename,
         path: mountPath,
         sizeBytes: content.length,
+        ...(vision?.kind === "accepted" ? { vision: vision.image } : {}),
+        ...(vision?.kind === "degraded" ? { visionDegraded: vision.reason } : {}),
       });
     }
   }
@@ -313,20 +341,53 @@ function resolveMountPath(attachment: Attachment): string {
         "mountPath resolves to an empty path after removing leading slashes",
       );
     }
+    // A caller-supplied mount path is untrusted. Stripping leading slashes does
+    // not stop `..` segments from climbing out of the workspace root on the
+    // non-`.stigmer/` branch (the `.stigmer/`-routed branch is already guarded
+    // by LocalWorkspaceBackend.resolvePath). Reject any path that normalizes to
+    // an escape before it reaches the backend write.
+    if (escapesRoot(cleaned)) {
+      throw new AttachmentInjectionError(
+        attachment.filename,
+        `mount path '${attachment.mountPath}' escapes the workspace root`,
+      );
+    }
     return cleaned;
   }
 
-  const filename = attachment.filename || deriveFilename(attachment.storageKey);
-  if (!filename) {
+  const rawName = attachment.filename || deriveFilename(attachment.storageKey);
+  if (!rawName) {
     throw new AttachmentInjectionError(
       "(unknown)",
       "attachment has neither filename nor storageKey — cannot determine mount path",
     );
   }
 
+  // The filename is untrusted; reduce it to a single path component so it lands
+  // directly under the inputs prefix rather than steering the write elsewhere.
+  const filename = posix.basename(rawName);
+  if (filename === "" || filename === "." || filename === "..") {
+    throw new AttachmentInjectionError(
+      rawName,
+      `filename '${rawName}' does not yield a usable name for materialization`,
+    );
+  }
+
   return `${DEFAULT_INPUTS_PREFIX}/${filename}`;
 }
 
+// escapesRoot reports whether a workspace-relative mount path would climb out
+// of the workspace root once normalized. Mount paths are forward-slash,
+// workspace-relative strings, so posix normalization is the correct semantics.
+function escapesRoot(relPath: string): boolean {
+  const normalized = posix.normalize(relPath);
+  return (
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    posix.isAbsolute(normalized)
+  );
+}
+
 function deriveFilename(storageKey: string): string {
   if (!storageKey) return "";
   const parts = storageKey.split("/");