@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/src/shared/__tests__/cost-guard.test.ts

@@ -44,9 +44,9 @@ describe("costCapExceeded", () => {
 
 describe("cost-limit terminal copy", () => {
   it("pins the error prefix consumers match on (no structured termination reason exists)", () => {
-    // Mirrors the TOOL_CALL_LIMIT_ERROR_PREFIX guard in
-    // streaming-terminal.test.ts: a reword silently downgrades any consumer
-    // matching this prefix to generic error copy.
+    // The twin of TOOL_CALL_LIMIT_ERROR_PREFIX's pin (`shared/tool-rounds.ts`,
+    // matched by the cloud's reply-extractor): a reword silently downgrades
+    // any consumer matching this prefix to generic error copy.
     expect(COST_LIMIT_ERROR_PREFIX).toBe("Agent reached the cost limit");
   });
 

package/src/shared/__tests__/prompt-sections.test.ts

@@ -0,0 +1,167 @@
+/**
+ * The shared prompt glue (`shared/prompt-sections.ts`): the standing order,
+ * the input-files lines, the skill selection and the also-available sentence
+ * (the sentence's arms came from `skill-writer.test.ts`, retired with its
+ * module at S3 M5). What each harness renders AROUND these is pinned whole by
+ * the two builders' prompt goldens (`execute-deep-agent/__tests__/
+ * prompt-goldens.test.ts`, `execute-cursor/__tests__/prompt-goldens.test.ts`);
+ * this file pins the glue's own contract, harness-free.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  alsoAvailableSkillsNote,
+  inputFileLines,
+  selectSkillsForPrompt,
+  standingContextSections,
+  visionPromptInfoOf,
+  type StandingSectionKind,
+} from "../prompt-sections.js";
+import type { ResolvedAttachment } from "../attachment-resolver.js";
+import type { SkillMetadata } from "../skill-resolver.js";
+import { SKILL_COUNT_THRESHOLD } from "../skill-relevance.js";
+import { formatDeclaredPreferencesText } from "../declared-preferences.js";
+
+describe("standingContextSections", () => {
+  const ORDER: readonly StandingSectionKind[] = [
+    "conversation-sender",
+    "declared-preferences",
+    "recalled-memories",
+    "session-context",
+    "previous-conversation",
+  ];
+
+  it("renders every present section in the one ruled order, whatever order the fields arrive in", () => {
+    const sections = standingContextSections({
+      contextBridge: "bridge",
+      sessionContext: "session",
+      recalledMemories: { facts: ["fact"] },
+      declaredPreferences: { orgContext: "org" },
+      senderIdentity: { value: "15550001111", kind: "whatsapp_phone" },
+    });
+    expect(sections.map((s) => s.kind)).toEqual(ORDER);
+  });
+
+  it("omits an absent section and keeps the relative order of the rest", () => {
+    const sections = standingContextSections({ contextBridge: "bridge", senderIdentity: { value: "U1", kind: "slack_user_id" } });
+    expect(sections.map((s) => s.kind)).toEqual(["conversation-sender", "previous-conversation"]);
+  });
+
+  it("renders nothing for an empty context", () => {
+    expect(standingContextSections({})).toEqual([]);
+  });
+
+  it("carries each body from the fact's own module, unframed", () => {
+    const [section] = standingContextSections({ declaredPreferences: { userContext: "Keep answers terse." } });
+    expect(section?.body).toBe(formatDeclaredPreferencesText({ userContext: "Keep answers terse." }));
+    expect(section?.body.startsWith("<")).toBe(false);
+    expect(section?.body.startsWith("#")).toBe(false);
+  });
+});
+
+describe("inputFileLines", () => {
+  const file = (relativePath: string, extra: Partial<ResolvedAttachment> = {}): ResolvedAttachment => ({
+    filename: relativePath.split("/").pop()!,
+    relativePath,
+    sizeBytes: 1024,
+    ...extra,
+  });
+
+  it("one bullet per file with the size, the rename disclosure and the download URL", () => {
+    const { entries } = inputFileLines(
+      [
+        file(".stigmer/inputs/spec.pdf"),
+        file(".stigmer/inputs/report-2.pdf", { renamedFrom: "report.pdf" }),
+        file(".stigmer/inputs/diagram.png", { downloadUrl: "https://r2.example/d?sig=1" }),
+      ],
+      undefined,
+      undefined,
+    );
+    expect(entries).toEqual([
+      "- `.stigmer/inputs/spec.pdf` (1024 bytes)",
+      "- `.stigmer/inputs/report-2.pdf` (1024 bytes) (renamed from duplicate 'report.pdf')",
+      "- `.stigmer/inputs/diagram.png` (1024 bytes) — download URL: https://r2.example/d?sig=1",
+    ]);
+  });
+
+  it("renders the URL hand-off line only when a listed file carries a URL AND the storage's kind is known", () => {
+    const withUrl = [file("a.pdf", { downloadUrl: "https://r2.example/a" })];
+    expect(inputFileLines(withUrl, undefined, "presigned").urlHandoff).toBeDefined();
+    expect(inputFileLines(withUrl, undefined, undefined).urlHandoff).toBeUndefined();
+    expect(inputFileLines([file("a.pdf")], undefined, "presigned").urlHandoff).toBeUndefined();
+  });
+
+  it("renders the vision lines only when the turn carries vision facts", () => {
+    expect(inputFileLines([file("a.png")], undefined, undefined).vision).toEqual([]);
+    const { vision } = inputFileLines(
+      [file("a.png")],
+      { inlineFilenames: ["a.png"], notViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }] },
+      undefined,
+    );
+    expect(vision.some((l) => l.includes("a.png"))).toBe(true);
+    expect(vision.some((l) => l.includes("big.png"))).toBe(true);
+  });
+});
+
+describe("visionPromptInfoOf", () => {
+  it("is undefined when the turn has neither inline images nor degraded ones", () => {
+    expect(visionPromptInfoOf({ visionImages: [], visionNotViewable: [] })).toBeUndefined();
+  });
+
+  it("names the inline images in send order and carries the degraded entries", () => {
+    const info = visionPromptInfoOf({
+      visionImages: [{ filename: "b.png" }, { filename: "a.jpg" }],
+      visionNotViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }],
+    });
+    expect(info).toEqual({
+      inlineFilenames: ["b.png", "a.jpg"],
+      notViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }],
+    });
+  });
+});
+
+describe("selectSkillsForPrompt", () => {
+  const skill = (name: string, description: string): SkillMetadata => ({ name, description, path: `.stigmer/skills/${name}/SKILL.md` });
+
+  it("highlights every skill below the threshold, in mount order, and names none as also-available", () => {
+    const skills = [skill("alpha", "Deploy to kubernetes"), skill("beta", "Reshape CSV exports")];
+    const selection = selectSkillsForPrompt("deploy the service", skills);
+    expect(selection.highlighted).toEqual(skills);
+    expect(selection.alsoAvailable).toEqual([]);
+  });
+
+  it("at the threshold, highlights the skills the message reaches and names the rest", () => {
+    const skills = Array.from({ length: SKILL_COUNT_THRESHOLD }, (_, i) =>
+      i === 0 ? skill("k8s-deploy", "Deploy services to kubernetes clusters") : skill(`other-${i}`, `Unrelated thing number ${i}`),
+    );
+    const selection = selectSkillsForPrompt("Deploy the payments service to kubernetes", skills);
+    expect(selection.highlighted.map((s) => s.name)).toContain("k8s-deploy");
+    expect(selection.alsoAvailable.length).toBeGreaterThan(0);
+    expect(selection.highlighted.length + selection.alsoAvailable.length).toBe(SKILL_COUNT_THRESHOLD);
+  });
+
+  it("selects nothing from nothing", () => {
+    expect(selectSkillsForPrompt("anything", [])).toEqual({ highlighted: [], alsoAvailable: [] });
+  });
+});
+
+describe("alsoAvailableSkillsNote", () => {
+  it("returns empty for no excluded names", () => {
+    expect(alsoAvailableSkillsNote([])).toBe("");
+  });
+
+  it("lists excluded skills with backtick formatting", () => {
+    const note = alsoAvailableSkillsNote(["alpha", "beta", "gamma"]);
+    expect(note).toContain("`alpha`");
+    expect(note).toContain("`beta`");
+    expect(note).toContain("`gamma`");
+  });
+
+  it("includes activation instructions that name no tool, so any harness can carry it", () => {
+    const note = alsoAvailableSkillsNote(["some-skill"]);
+    expect(note).toContain(".stigmer/skills/<name>/SKILL.md");
+    expect(note).toContain("relevant to your task");
+    expect(note).not.toMatch(/\b(read|Read) tool\b/);
+    expect(note.startsWith("#")).toBe(false);
+  });
+});

package/src/shared/__tests__/secret-leak-scan.test.ts

@@ -10,8 +10,8 @@
  * An offline end-to-end test is structurally infeasible for this path (DD-23 /
  * DD-26 F3: the offline harness always runs a git workspace with LocalArtifactDir,
  * so deriveCaptureMode is always true and the no-storage deny-gate is unreachable).
- * This test exercises the exact function both `execute-deep-agent/index.ts` and the
- * Cursor `persist` wrapper invoke, over a full AgentExecutionStatus.
+ * This test exercises the exact function the turn runtime's persist chokepoint
+ * invokes for both harnesses, over a full AgentExecutionStatus.
  */
 
 import { describe, it, expect } from "vitest";

package/src/{activities/execute-deep-agent → shared}/__tests__/stamp-flowed-rows.test.ts

@@ -1,9 +1,12 @@
 /**
- * Unit tests for the deep-agent turn-boundary flowed-row stamping
- * (`stamp-flowed-rows.ts`), with emphasis on the sub-agent path added by the
- * DD-24 follow-up: sub-agent edit rows fold into the parent turn's change set,
- * so they carry the parent change set id, scoped to this turn by tool-call-id
- * novelty (they lack the already-stamped/hidden shields the top-level pass has).
+ * Unit tests for the shared turn-boundary flowed-row stamping
+ * (`shared/tool-row.ts` `stampFlowedFileEditRows` /
+ * `stampFlowedSubAgentFileEditRows`; the deep-agent's copy until S3 M4), with
+ * emphasis on the sub-agent path added by the DD-24 follow-up: sub-agent edit
+ * rows fold into the parent turn's change set, so they carry the parent change
+ * set id, scoped to this turn by tool-call-id novelty (they lack the
+ * already-stamped/hidden shields the top-level pass has). The `flowed`
+ * predicate is the one seam a deny-gate harness narrows the pass with.
  */
 
 import { describe, it, expect } from "vitest";
@@ -15,11 +18,12 @@ import {
 import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { collectSubAgentToolCallIds } from "../../../shared/tool-row.js";
 import {
+  collectSubAgentToolCallIds,
+  hideToolCallRow,
   stampFlowedFileEditRows,
   stampFlowedSubAgentFileEditRows,
-} from "../stamp-flowed-rows.js";
+} from "../tool-row.js";
 
 const CHANGE_SET_ID = "exec-1:0";
 
@@ -42,7 +46,7 @@ function subAgent(subId: string, ...messages: AgentMessage[]) {
   return create(SubAgentExecutionSchema, { id: subId, name: "code_editor", messages });
 }
 
-describe("stampFlowedFileEditRows (deep-agent)", () => {
+describe("stampFlowedFileEditRows", () => {
   it("stamps a flowed write/delete row and leaves a non-file row untouched", () => {
     const write = editMessage("tc-1", "src/a.ts", "write_file");
     const shell = create(AgentMessageSchema, {
@@ -60,7 +64,7 @@ describe("stampFlowedFileEditRows (deep-agent)", () => {
     const prior = editMessage("tc-prior", "src/old.ts");
     const current = editMessage("tc-current", "src/new.ts");
 
-    stampFlowedFileEditRows([prior, current], CHANGE_SET_ID, new Set(["tc-prior"]));
+    stampFlowedFileEditRows([prior, current], CHANGE_SET_ID, { skipToolCallIds: new Set(["tc-prior"]) });
 
     expect(prior.toolCalls[0].fileChangeSetId).toBe(""); // skipped
     expect(current.toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
@@ -74,9 +78,28 @@ describe("stampFlowedFileEditRows (deep-agent)", () => {
 
     expect(row.toolCalls[0].fileChangeSetId).toBe("exec-1:prior");
   });
+
+  it("skips a legacy hidden row (a pre-stamping session's collapsed edit): it belongs to an earlier turn's set", () => {
+    const legacy = editMessage("tc-legacy", "src/old.ts");
+    hideToolCallRow(legacy.toolCalls[0]!);
+
+    stampFlowedFileEditRows([legacy], CHANGE_SET_ID);
+
+    expect(legacy.toolCalls[0]!.fileChangeSetId).toBe("");
+  });
+
+  it("leaves a row the caller's `flowed` predicate refuses (a denied identity, a non-terminal status) unstamped", () => {
+    const flowed = editMessage("tc-flowed", "src/a.ts");
+    const denied = editMessage("tc-denied", "src/b.ts");
+
+    stampFlowedFileEditRows([flowed, denied], CHANGE_SET_ID, { flowed: (tc) => tc.id !== "tc-denied" });
+
+    expect(flowed.toolCalls[0].fileChangeSetId).toBe(CHANGE_SET_ID);
+    expect(denied.toolCalls[0].fileChangeSetId).toBe("");
+  });
 });
 
-describe("stampFlowedSubAgentFileEditRows (deep-agent)", () => {
+describe("stampFlowedSubAgentFileEditRows", () => {
   it("stamps a current-turn sub-agent's edit row with the parent change set id", () => {
     const sub = subAgent("sa-1", editMessage("sa-tc-1", "src/sub.ts"));
 

package/src/shared/__tests__/vertex-adapter.test.ts

@@ -119,7 +119,7 @@ describe("buildChatModel vertex adapter", () => {
   });
 
   it("translated ids inherit the same default maxTokens as canonical ids", () => {
-    // setup.ts deliberately omits maxTokens, so the LangChain per-model
+    // turn-setup.ts deliberately omits maxTokens, so the LangChain per-model
     // default applies. That default prefix-matches the model string — and the
     // vertex branch hands ChatAnthropic the TRANSLATED string. This pins the
     // equality the zero-behavior-change criterion rests on (verified 16384 ==

package/src/shared/attachment-resolver.ts

@@ -14,34 +14,56 @@
  *   the backend's create pipeline requires a storage key on every attachment
  *   it accepts, and in local mode the storage reads directly off disk.
  *
- * Placement is always `inputs/{filename}` — the platform namespace this
- * harness can surface in the workspace. An attachment's `mountPath` is
- * honored by convention, not mechanism: the standard mounts (e.g. the
- * approved plan at `.stigmer/inputs/<slug>_<id>.plan.md`) resolve to exactly this
- * placement, and the prompt's `<input_files>` section plus any path-derived
- * directives are built from the RESOLVED paths, so prompt and filesystem can
- * never disagree.
+ * Placement is the `inputs/` namespace — the platform directory every
+ * harness surfaces in the workspace through the `.stigmer` link, and the
+ * only place an attachment may land. An attachment names its place INSIDE
+ * that namespace with `mountPath` (`inputs/<name>`, `inputs/<dir>/`,
+ * `.stigmer/inputs/<name>`; a leading slash is stripped), or takes the
+ * default `inputs/{filename}`. A `mountPath` outside the namespace is
+ * refused with an actionable error, never relocated silently: a file
+ * written into the user's own tree would be committed to the session's
+ * write-back branch on completion (`git add -A`), and every real producer —
+ * the CLI's directory attachments, the approved plan the console mounts —
+ * already stays inside `inputs/` (S3 M1, Q-M1-2; the proto's `/workspace/…`
+ * example is a doc issue). The prompt's `<input_files>` section and every
+ * path-derived directive are built from the RESOLVED paths, so prompt and
+ * filesystem can never disagree.
  *
- * Duplicate filenames are renamed, never overwritten (issue #364): because
- * placement keys purely on the filename, two attachments with the same name
- * contend for one path — the later one takes the platform's `stem-2.ext`
- * rename (shared/attachment-naming.ts, same semantics as the deep-agent
- * injector and the React composer) and the rename is disclosed in the
- * prompt's `<input_files>` section via {@link ResolvedAttachment.renamedFrom}.
+ * Archives: an attachment marked `extract` is a ZIP whose entries land under
+ * its mount as a DIRECTORY (`inputs/<mount>/<entry>`), validated and
+ * decompressed by `attachment-zip.ts` (the #567 guards). Each entry is its
+ * own {@link ResolvedAttachment} with no vision, no `renamedFrom` and no
+ * `downloadUrl`: an image inside a ZIP has no attachment-level bytes, a
+ * renamed mount directory is visible through every entry path, and the
+ * stored object is the ZIP, not any listed file.
  *
- * Error model: fail-hard, matching the native harness's attachment injector.
- * Attachments are explicit user inputs — an execution that silently runs
- * without one produces silently incorrect results (the "plan file wasn't
- * found" class of failure). Any attachment that cannot be materialized aborts
- * the execution with an actionable error.
+ * Duplicate names are renamed, never overwritten (issue #364), in two passes:
+ * explicit mount paths claim their exact targets first — two attachments
+ * pinning the SAME path is a user contradiction no rename can honestly
+ * resolve, so that alone still refuses — and default-derived names then
+ * uniquify around everything already taken with the platform's `stem-2.ext`
+ * rename (shared/attachment-naming.ts, the React composer's semantics),
+ * disclosed in the prompt via {@link ResolvedAttachment.renamedFrom}.
+ *
+ * Error model: fail-hard. Attachments are explicit user inputs — an
+ * execution that silently runs without one produces silently incorrect
+ * results (the "plan file wasn't found" class of failure). Any attachment
+ * that cannot be materialized aborts the execution with an actionable
+ * {@link AttachmentResolutionError}; an archive that fails its guards
+ * aborts with the guard's own `AttachmentValidationError`.
+ *
+ * Until S3 M1 this resolver ignored `mountPath` and could not extract; the
+ * native harness's `attachment-injector.ts` did both and was retired at S3
+ * M2b for this one pipeline (Q-S3-14).
  */
 
 import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
-import { join, basename } from "node:path";
+import { join, basename, dirname, posix } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "./artifact-storage.js";
 import { mintAttachmentDownloadUrl } from "./attachment-download-urls.js";
 import { allocateUniqueName } from "./attachment-naming.js";
+import { decompressEntry, parseAndValidateZip } from "./attachment-zip.js";
 import {
   isVisionCandidate,
   type VisionBudget,
@@ -59,6 +81,8 @@ export interface ResolvedAttachment {
   filename: string;
   /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
   relativePath: string;
+  /** The bytes on disk; a prompt discloses it beside the path so the agent can weigh a read. */
+  sizeBytes: number;
   /**
    * The attachment's original filename, present only when a duplicate name
    * was renamed (shared/attachment-naming.ts) — rendered as disclosure in
@@ -138,13 +162,18 @@ export async function resolveAttachments(
   // it, but only when the agent has skills).
   await ensureStigmerSymlink(options.primaryWorkspaceDir, platformDir);
 
-  // Placement keys purely on the filename, so this set is the whole
-  // collision domain — sequential resolution means each attachment sees
-  // every name claimed before it (see module doc on duplicate handling).
-  const takenNames = new Set<string>();
+  // Every place is decided before any bytes move: an explicit-path
+  // contradiction refuses up front, and a default name never lands on a path
+  // an explicit one claims (see module doc on duplicate handling).
+  const places = resolvePlacements(attachments);
   const results: ResolvedAttachment[] = [];
   for (const attachment of attachments) {
-    results.push(await resolveAttachment(attachment, inputsDir, takenNames, options));
+    const place = places.get(attachment)!;
+    if (attachment.extract) {
+      results.push(...(await extractArchive(attachment, place, inputsDir, options)));
+    } else {
+      results.push(await resolveAttachment(attachment, place, inputsDir, options));
+    }
   }
 
   console.log(
@@ -157,19 +186,22 @@ export async function resolveAttachments(
 
 async function resolveAttachment(
   attachment: Attachment,
+  place: Placement,
   inputsDir: string,
-  takenNames: Set<string>,
   options: AttachmentResolverOptions,
 ): Promise<ResolvedAttachment> {
+  const { relative, renamedFrom } = place;
+  // The final basename is the canonical filename: after a duplicate rename
+  // the original attachment.filename no longer names the file on disk, and
+  // the vision label must match what the prompt lists.
+  const filename = posix.basename(relative);
+  await mkdir(dirname(join(inputsDir, relative)), { recursive: true });
+
   // Local-mode fast path: the file is already on this machine's disk.
   if (options.mode === "local" && attachment.localPath) {
-    const { name: filename, renamedFrom } = allocateUniqueName(
-      safeInputName(attachment.filename || attachment.localPath),
-      takenNames,
-    );
     let vision: VisionOutcome | undefined;
     try {
-      vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
+      vision = await materializeLocalFile(attachment, filename, join(inputsDir, relative), options.visionBudget);
     } catch (err) {
       throw new AttachmentResolutionError(
         attachment.filename,
@@ -185,7 +217,8 @@ async function resolveAttachment(
     );
     return {
       filename,
-      relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+      relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, relative),
+      sizeBytes: (await stat(join(inputsDir, relative))).size,
       ...(renamedFrom !== undefined ? { renamedFrom } : {}),
       ...visionOutcomeFields(vision),
       ...(downloadUrl !== undefined ? { downloadUrl } : {}),
@@ -193,6 +226,77 @@ async function resolveAttachment(
   }
 
   // Universal path: download the uploaded content by storage key.
+  const content = await downloadFromStorage(attachment, options);
+  await writeFile(join(inputsDir, relative), content);
+
+  // The bytes are already in hand for the file write — offer them to the
+  // vision budget before they go out of scope (the sniff decides eligibility;
+  // no pre-filter needed on this branch).
+  const vision = options.visionBudget?.offer(filename, attachment.contentType, content);
+
+  const downloadUrl = await mintAttachmentDownloadUrl(
+    options.storage, attachment.storageKey, filename,
+  );
+
+  return {
+    filename,
+    relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, relative),
+    sizeBytes: content.byteLength,
+    ...(renamedFrom !== undefined ? { renamedFrom } : {}),
+    ...visionOutcomeFields(vision),
+    ...(downloadUrl !== undefined ? { downloadUrl } : {}),
+  };
+}
+
+/**
+ * Extract an `extract` attachment's archive under its mount directory. The
+ * bytes are read whole (an archive is never a vision candidate, so the local
+ * fast path's lazy read has nothing to save), validated and decompressed by
+ * the shared guards, and written entry by entry; the entries are the
+ * resolved attachments (see the module doc for what they do not carry).
+ */
+async function extractArchive(
+  attachment: Attachment,
+  place: Placement,
+  inputsDir: string,
+  options: AttachmentResolverOptions,
+): Promise<ResolvedAttachment[]> {
+  const content = await bytesOf(attachment, options);
+  const entries = parseAndValidateZip(content, attachment.filename);
+  const mountDir = place.relative.replace(/\/+$/, "");
+  const results: ResolvedAttachment[] = [];
+  for (const entry of entries) {
+    const bytes = await decompressEntry(entry, attachment.filename);
+    const relative = posix.join(mountDir, entry.relativePath);
+    const dest = join(inputsDir, relative);
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, bytes);
+    results.push({
+      filename: posix.basename(entry.relativePath),
+      relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, relative),
+      sizeBytes: bytes.byteLength,
+    });
+  }
+  return results;
+}
+
+/** The attachment's bytes, from the local fast path or from storage. */
+async function bytesOf(attachment: Attachment, options: AttachmentResolverOptions): Promise<Buffer> {
+  if (options.mode === "local" && attachment.localPath) {
+    try {
+      return await readFile(attachment.localPath);
+    } catch (err) {
+      throw new AttachmentResolutionError(
+        attachment.filename,
+        `failed to read local file '${attachment.localPath}': ` +
+        `${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  return downloadFromStorage(attachment, options);
+}
+
+async function downloadFromStorage(attachment: Attachment, options: AttachmentResolverOptions): Promise<Buffer> {
   if (!attachment.storageKey) {
     throw new AttachmentResolutionError(
       attachment.filename,
@@ -206,14 +310,8 @@ async function resolveAttachment(
       `(key: ${attachment.storageKey}) cannot be downloaded`,
     );
   }
-
-  const { name: filename, renamedFrom } = allocateUniqueName(
-    safeInputName(attachment.filename || attachment.storageKey),
-    takenNames,
-  );
-  let content: Buffer;
   try {
-    content = await options.storage.download(attachment.storageKey);
+    return await options.storage.download(attachment.storageKey);
   } catch (err) {
     throw new AttachmentResolutionError(
       attachment.filename,
@@ -221,24 +319,90 @@ async function resolveAttachment(
       `${err instanceof Error ? err.message : String(err)}`,
     );
   }
-  await writeFile(join(inputsDir, filename), content);
+}
 
-  // The bytes are already in hand for the file write — offer them to the
-  // vision budget before they go out of scope (the sniff decides eligibility;
-  // no pre-filter needed on this branch).
-  const vision = options.visionBudget?.offer(filename, attachment.contentType, content);
+// ── Placement ────────────────────────────────────────────────────────
 
-  const downloadUrl = await mintAttachmentDownloadUrl(
-    options.storage, attachment.storageKey, filename,
-  );
+/** Where an attachment lands, relative to the `inputs/` directory. */
+interface Placement {
+  readonly relative: string;
+  /** Present when a default-derived name was uniquified (issue #364). */
+  readonly renamedFrom?: string;
+}
 
-  return {
-    filename,
-    relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
-    ...(renamedFrom !== undefined ? { renamedFrom } : {}),
-    ...visionOutcomeFields(vision),
-    ...(downloadUrl !== undefined ? { downloadUrl } : {}),
-  };
+/**
+ * The two-pass placement (see module doc): explicit mount paths first, each
+ * resolved into the namespace and refused on a contradiction; then the
+ * default-derived names, uniquified around every name already taken directly
+ * under `inputs/`.
+ */
+function resolvePlacements(attachments: readonly Attachment[]): Map<Attachment, Placement> {
+  const places = new Map<Attachment, Placement>();
+  const claimed = new Map<string, Attachment>();
+
+  for (const attachment of attachments) {
+    if (!attachment.mountPath) continue;
+    const relative = explicitPlacement(attachment);
+    const existing = claimed.get(relative);
+    if (existing) {
+      throw new AttachmentResolutionError(
+        attachment.filename,
+        `mount path '${attachment.mountPath}' collides with attachment '${existing.filename}'. ` +
+        "Set distinct mountPath values on the attachments to resolve this conflict.",
+      );
+    }
+    claimed.set(relative, attachment);
+    places.set(attachment, { relative });
+  }
+
+  const takenNames = new Set<string>();
+  for (const relative of claimed.keys()) {
+    if (!relative.includes("/")) takenNames.add(relative);
+  }
+  for (const attachment of attachments) {
+    if (attachment.mountPath) continue;
+    const { name, renamedFrom } = allocateUniqueName(
+      safeInputName(attachment.filename || attachment.localPath || attachment.storageKey),
+      takenNames,
+    );
+    places.set(attachment, renamedFrom !== undefined ? { relative: name, renamedFrom } : { relative: name });
+  }
+  return places;
+}
+
+/** The namespace prefixes an explicit `mountPath` may name, longest first. */
+const INPUTS_NAMESPACE_PREFIXES = [`${STIGMER_LOCAL_STATE_DIR}/${INPUTS_SUBDIR}`, INPUTS_SUBDIR] as const;
+
+/**
+ * Resolve an explicit `mountPath` into a path relative to `inputs/`, or
+ * refuse: empty after cleaning, outside the namespace, or climbing out of it.
+ * A caller-supplied path is untrusted, so `..` is judged after normalization.
+ */
+function explicitPlacement(attachment: Attachment): string {
+  const cleaned = attachment.mountPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  const prefix = INPUTS_NAMESPACE_PREFIXES.find((p) => cleaned === p || cleaned.startsWith(`${p}/`));
+  if (prefix === undefined) {
+    throw new AttachmentResolutionError(
+      attachment.filename,
+      `mount path '${attachment.mountPath}' is outside the attachment namespace. ` +
+      `Attachments land under '${INPUTS_SUBDIR}/' (surfaced as '${STIGMER_LOCAL_STATE_DIR}/${INPUTS_SUBDIR}/'); ` +
+      `set mountPath to '${INPUTS_SUBDIR}/<name>' or leave it empty for the default placement.`,
+    );
+  }
+  const relative = posix.normalize(cleaned.slice(prefix.length).replace(/^\/+/, ""));
+  if (relative === "" || relative === ".") {
+    throw new AttachmentResolutionError(
+      attachment.filename,
+      `mount path '${attachment.mountPath}' names the inputs directory itself, not a place inside it`,
+    );
+  }
+  if (relative === ".." || relative.startsWith("../") || posix.isAbsolute(relative)) {
+    throw new AttachmentResolutionError(
+      attachment.filename,
+      `mount path '${attachment.mountPath}' escapes the attachment namespace`,
+    );
+  }
+  return relative;
 }
 
 /**
@@ -251,10 +415,9 @@ async function resolveAttachment(
 async function materializeLocalFile(
   attachment: Attachment,
   filename: string,
-  inputsDir: string,
+  dest: string,
   visionBudget: VisionBudget | undefined,
 ): Promise<VisionOutcome | undefined> {
-  const dest = join(inputsDir, filename);
   if (!visionBudget || !isVisionCandidate(attachment.contentType, filename)) {
     await copyFile(attachment.localPath, dest);
     return undefined;