@stigmer/runner 3.9.0 → 3.11.0

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

@@ -0,0 +1,104 @@
+/**
+ * Datastore degradation disclosure, activity half (issue #325).
+ *
+ * The activity appends the operator-facing MESSAGE_SYSTEM notice to
+ * `initialStatus.messages` BEFORE streaming (index.ts) — deliberately not
+ * through a status builder, because the v2 and v3 stream paths each
+ * construct their own builder around that same proto. These tests pin the
+ * property that push site depends on: BOTH builders preserve pre-seeded
+ * messages (ExecutionState only appends; index rebuilds touch runtime
+ * tool-call state, and a MESSAGE_SYSTEM row carries no tool calls), so
+ * the notice survives whichever stream version runs and rides every
+ * persist. The prompt half (section selection) is pinned in
+ * shared/__tests__/datastore-attachment.test.ts.
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  EXPECTED_RECORD_TOOLS,
+  formatDatastoreDegradationNotice,
+} from "../../../shared/datastore-attachment.js";
+import { StatusBuilder } from "../status-builder.js";
+import { V3StatusBuilder } from "../v3-status-builder.js";
+import { normalize } from "../v3-protocol-normalizer.js";
+import {
+  resetSeq,
+  makeMessageStart,
+  makeMessageFinish,
+  makeTextDelta,
+} from "../__test-utils__/v3-event-fixtures.js";
+
+beforeEach(() => resetSeq());
+
+/** initialStatus as index.ts shapes it when setup reports missing tools. */
+function statusWithDegradationNotice(): AgentExecutionStatus {
+  const status = create(AgentExecutionStatusSchema, {});
+  status.messages.push(create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_SYSTEM,
+    content: formatDatastoreDegradationNotice(1, [...EXPECTED_RECORD_TOOLS]),
+    timestamp: "2026-08-11T00:00:00.000Z",
+  }));
+  return status;
+}
+
+describe("datastore degradation notice survives streaming (issue #325)", () => {
+  it("v2 StatusBuilder preserves the pre-seeded notice through a streamed turn", () => {
+    const initialStatus = statusWithDegradationNotice();
+    const sb = new StatusBuilder("exec-1", initialStatus);
+
+    sb.processEvent({
+      event: "on_chat_model_stream",
+      run_id: "run-1",
+      data: { chunk: { content: "I cannot reach the datastore right now." } },
+    });
+    sb.processEvent({ event: "on_chat_model_end", run_id: "run-1", data: {} });
+
+    const messages = sb.currentStatus.messages;
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+    expect(messages[0].type).toBe(MessageType.MESSAGE_SYSTEM);
+    expect(messages[0].content).toContain("0/5 record tools connected");
+    expect(messages[0].content).toContain("declared 1 datastore(s)");
+  });
+
+  it("v3 V3StatusBuilder preserves the pre-seeded notice through a streamed turn", () => {
+    const initialStatus = statusWithDegradationNotice();
+    const sb = new V3StatusBuilder("exec-1", initialStatus);
+
+    const protocolEvents = [
+      makeMessageStart("run-1"),
+      makeTextDelta("run-1", "I cannot reach the datastore right now."),
+      makeMessageFinish("run-1"),
+    ];
+    for (const raw of protocolEvents) {
+      for (const e of normalize(raw)) {
+        sb.processEvent(e);
+      }
+    }
+
+    const messages = sb.currentStatus.messages;
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+    expect(messages[0].type).toBe(MessageType.MESSAGE_SYSTEM);
+    expect(messages[0].content).toContain("0/5 record tools connected");
+  });
+
+  it("both builders share the initialStatus proto, so the append needs no builder", () => {
+    // The push-site contract itself: mutating initialStatus.messages is
+    // visible through whichever builder wraps it.
+    const initialStatus = create(AgentExecutionStatusSchema, {});
+    const sb = new StatusBuilder("exec-1", initialStatus);
+    initialStatus.messages.push(create(AgentMessageSchema, {
+      type: MessageType.MESSAGE_SYSTEM,
+      content: formatDatastoreDegradationNotice(2, ["delete_record"]),
+      timestamp: "2026-08-11T00:00:00.000Z",
+    }));
+    expect(sb.currentStatus.messages).toHaveLength(1);
+    expect(sb.currentStatus.messages[0].content).toContain(
+      "4/5 record tools connected",
+    );
+  });
+});

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

@@ -184,6 +184,7 @@ function fakeHttpRejectSetup(): SetupResult {
     session: { spec: { workspaceEntries: [] } },
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-reject-http" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",
@@ -219,6 +220,7 @@ function fakeMemoryRejectSetup(): SetupResult {
     session: { spec: { workspaceEntries: [] } },
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-reject-mem" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -264,6 +264,7 @@ function fakeDurableResumeSetup(): SetupResult {
     // path shared across files would serialize parallel test workers for real.
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-hitl-approve-all" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -219,6 +219,7 @@ function fakeDurableResumeSetup(): SetupResult {
     // path shared across files would serialize parallel test workers for real.
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-hitl-history" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -142,6 +142,10 @@ describe("buildEnhancedSystemPrompt", () => {
   });
 
   it("includes injected files section with size info", () => {
+    // The section renders the injector's own result type (sizeBytes). A local
+    // structural twin with a `size` field used to live in the prompt builder,
+    // and production wiring silently dropped the size — this pin holds the
+    // real field name so that drift class cannot return.
     const prompt = buildEnhancedSystemPrompt({
       instructions: "Test",
       provisionResults: [],
@@ -150,15 +154,40 @@ describe("buildEnhancedSystemPrompt", () => {
       workspaceFileRefs: [],
       workspaceRoot: "/workspace",
       injectedFiles: [
-        { filename: "data.csv", path: ".stigmer/inputs/data.csv", size: 1024 },
-        { filename: "notes.md", path: ".stigmer/inputs/notes.md", size: null },
+        { filename: "data.csv", path: ".stigmer/inputs/data.csv", sizeBytes: 1024 },
+        { filename: "notes.md", path: ".stigmer/inputs/notes.md", sizeBytes: 12 },
       ],
     });
 
     expect(prompt).toContain("## Input Files");
     expect(prompt).toContain("`.stigmer/inputs/data.csv` (1024 bytes)");
-    expect(prompt).toContain("`.stigmer/inputs/notes.md`");
-    expect(prompt).not.toContain("null");
+    expect(prompt).toContain("`.stigmer/inputs/notes.md` (12 bytes)");
+  });
+
+  it("discloses a duplicate-renamed injected file's original name", () => {
+    const prompt = buildEnhancedSystemPrompt({
+      instructions: "Test",
+      provisionResults: [],
+      containerRoot: "",
+      skillsPromptSection: "",
+      workspaceFileRefs: [],
+      workspaceRoot: "/workspace",
+      injectedFiles: [
+        { filename: "report.pdf", path: ".stigmer/inputs/report.pdf", sizeBytes: 10 },
+        {
+          filename: "report-2.pdf",
+          path: ".stigmer/inputs/report-2.pdf",
+          sizeBytes: 20,
+          renamedFrom: "report.pdf",
+        },
+      ],
+    });
+
+    expect(prompt).toContain(
+      "`.stigmer/inputs/report-2.pdf` (20 bytes) (renamed from duplicate 'report.pdf')",
+    );
+    // The first file keeps a clean entry — no disclosure noise.
+    expect(prompt).toContain("`.stigmer/inputs/report.pdf` (10 bytes)\n");
   });
 
   it("produces a git repo description for git workspace entries", () => {
@@ -361,7 +390,7 @@ describe("buildEnhancedSystemPrompt", () => {
     const planFile = {
       filename: "plan.md",
       path: ".stigmer/inputs/plan.md",
-      size: 1024,
+      sizeBytes: 1024,
     };
 
     it("appends the implement-plan directive pointing at the injected plan", () => {

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

@@ -196,6 +196,7 @@ function fakeMemoryGateSetup(opts: {
       readFile: vi.fn(async () => ""),
     },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

package/src/activities/execute-deep-agent/__tests__/subagent-plan-mode-permissions.test.ts

@@ -0,0 +1,173 @@
+/**
+ * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that a
+ * plan-mode SUB-AGENT is read-only BY CONSTRUCTION (issue #255).
+ *
+ * The parent graph receives PLAN_MODE_PERMISSIONS in setup.ts, but deepagents'
+ * parent-permission inheritance covers only spec-style sub-agents — our
+ * pre-built CompiledSubAgents bypass `normalizeSubagentSpec` entirely, so
+ * `compileSubagents` must bake the rules into each sub-agent graph itself.
+ * These tests exercise that exact wiring with NO approval gate installed (the
+ * auto-approve-all shape): any denial must come from the permission rules
+ * alone, proving plan mode's "read-only by construction, not by gate"
+ * contract at the sub-agent level. A contrast case pins that without the
+ * rules (act mode) the same write flows — this change is a plan-mode-only
+ * delta.
+ *
+ * The rule under test is the PRODUCTION constant from
+ * shared/plan-mode-permissions.ts (the same one setup.ts applies to both
+ * graph sites), not a test copy, so a change to the plan-mode permission set
+ * re-proves sub-agent coverage automatically.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, readFile, writeFile, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HumanMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
+
+import { PLAN_MODE_PERMISSIONS } from "../../../shared/plan-mode-permissions.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import { compileSubagents } from "../subagent-transformer.js";
+import { ScriptedModel, type ScriptSelector } from "../__test-utils__/scripted-model.js";
+
+const SEEDED_CONTENT = "PLAN_MODE_README_TOKEN: hello from the seeded file";
+
+describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
+  let root: string;
+  let observer: CasCaptureObserver;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "sa-plan-"));
+    await mkdir(join(root, "dist"), { recursive: true });
+    await writeFile(join(root, "notes.md"), SEEDED_CONTENT);
+    // Everything is gitignored from the observer's view — the strictest case:
+    // every write would be CAS-observed if it ever reached the backend.
+    observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * Compile a worker through the production path with NO approval gate, so the
+   * permission rules are the only thing standing between the model and the
+   * filesystem. `permissions` present = the plan-mode wiring under test;
+   * absent = the act-mode contrast.
+   */
+  async function compileWorker(script: ScriptSelector, planMode: boolean) {
+    const compiled = await compileSubagents(
+      [{ name: "worker", description: "test worker", systemPrompt: "do the work", tools: [] }],
+      {
+        approvalGate: null,
+        parentModelName: "test-model",
+        workspaceRootDir: root,
+        casObserver: observer,
+        modelFactory: async () => new ScriptedModel(script),
+        ...(planMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
+      },
+    );
+    expect(compiled).toHaveLength(1);
+    return compiled[0];
+  }
+
+  function toolResultById(messages: BaseMessage[], toolCallId: string): string {
+    const match = messages.find(
+      (m): m is ToolMessage => m instanceof ToolMessage && m.tool_call_id === toolCallId,
+    );
+    expect(match, `expected a tool result for call '${toolCallId}'`).toBeDefined();
+    return typeof match!.content === "string" ? match!.content : JSON.stringify(match!.content);
+  }
+
+  it("denies write_file and edit_file at the tool level, while read_file still works", async () => {
+    // One turn, three tool calls: both mutation tools must be denied by the
+    // permission rules; the read must pass through untouched (the deny rule
+    // covers the `write` operation class only).
+    // Real absolute workspace paths, as production models use (the prompt's
+    // file tree is absolute, and the tools' contract says absolute). With
+    // permission rules present this is also the only shape that reaches the
+    // rules at all: enforcePermission's canonicalization refuses relative
+    // paths with a validation error before any rule or backend runs — a
+    // different denial, but still nothing written.
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
+        { name: "edit_file", args: { file_path: join(root, "notes.md"), old_string: "hello", new_string: "HACKED" }, id: "c_edit" },
+        { name: "read_file", args: { file_path: join(root, "notes.md") }, id: "c_read" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t1" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    // Both mutations denied with deepagents' permission error, and nothing on disk:
+    // the new file was never created and the seeded file is byte-identical.
+    expect(toolResultById(result.messages, "c_write")).toMatch(/permission denied for write/i);
+    expect(toolResultById(result.messages, "c_edit")).toMatch(/permission denied for write/i);
+    await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
+    expect(await readFile(join(root, "notes.md"), "utf8")).toBe(SEEDED_CONTENT);
+
+    // The read flowed: its result carries the seeded content, not a denial.
+    const readResult = toolResultById(result.messages, "c_read");
+    expect(readResult).toContain("PLAN_MODE_README_TOKEN");
+    expect(readResult).not.toMatch(/permission denied/i);
+
+    // The denial fired INSIDE the tool handler, before any backend was reached:
+    // the CAS observer (which records pre-write bytes on the backend's write/edit
+    // seams) saw neither mutation.
+    expect(observer.before.size).toBe(0);
+  });
+
+  it("act-mode contrast: without the permissions option the same write lands (zero-delta outside plan mode)", async () => {
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, false);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t2" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    expect(toolResultById(result.messages, "c_write")).not.toMatch(/permission denied/i);
+    expect(await readFile(join(root, "dist/out.txt"), "utf8")).toBe("new file");
+    // And the backend WAS reached this time — the observer recorded a write.
+    // (Key shape is DD-19 territory, deliberately not pinned here.)
+    expect(observer.before.size).toBe(1);
+  });
+
+  it("relative-path mutations are refused too — by validation, before the rules", async () => {
+    // The native prompt steers models to workspace-relative paths, but
+    // deepagents' permission canonicalization accepts only absolute ones, so
+    // with rules present a relative-path call fails validation before any
+    // rule (or backend) runs. Read-only still holds — nothing is written —
+    // but the model sees "path must be absolute", not "permission denied",
+    // and prompt-compliant relative READS degrade the same way. That
+    // relative-vs-absolute friction is a pre-existing parent-plan-mode
+    // behavior, tracked as issue #429; this pins that the sub-agent's
+    // read-only contract survives it.
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: "dist/out.txt", content: "new file" }, id: "c_write_rel" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t3" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    expect(toolResultById(result.messages, "c_write_rel")).toMatch(/path must be absolute/i);
+    await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
+    expect(observer.before.size).toBe(0);
+  });
+});

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

@@ -7,10 +7,11 @@ describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
     const stack = buildSubAgentMiddleware();
 
-    expect(stack).toHaveLength(3);
+    expect(stack).toHaveLength(4);
     expect(stack[0].name).toBe("LoopDetectionMiddleware");
     expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
     expect(stack[2].name).toBe("ToolTruncationMiddleware");
+    expect(stack[3].name).toBe("ErrorHintsMiddleware");
   });
 
   it("includes cost cap view when parent cost cap is provided", () => {
@@ -24,8 +25,9 @@ describe("buildSubAgentMiddleware", () => {
 
     const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack[3].name).toBe("CostCapSubAgentView");
+    expect(stack[4].name).toBe("ErrorHintsMiddleware");
   });
 
   it("sub-agent cost cap view shares parent state", () => {
@@ -75,8 +77,8 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate
-    expect(stack).toHaveLength(4);
+    // loop, budget, truncation, approval gate, error hints
+    expect(stack).toHaveLength(5);
     expect(stack[3].name).toBe("ApprovalGateMiddleware");
     expect(stack[3].wrapToolCall).toBeDefined();
   });
@@ -84,7 +86,7 @@ describe("buildSubAgentMiddleware", () => {
   it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
     const stack = buildSubAgentMiddleware({ approvalGate: null });
 
-    expect(stack).toHaveLength(3);
+    expect(stack).toHaveLength(4);
     expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
   });
 
@@ -102,10 +104,13 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, cost cap view
-    expect(stack).toHaveLength(5);
+    // loop, budget, truncation, approval gate, cost cap view, error hints.
+    // Hints AFTER the gate matches the parent nesting: the gate's HITL
+    // interrupt stays outside the hints' try/catch (issue #255).
+    expect(stack).toHaveLength(6);
     expect(stack[3].name).toBe("ApprovalGateMiddleware");
     expect(stack[4].name).toBe("CostCapSubAgentView");
+    expect(stack[5].name).toBe("ErrorHintsMiddleware");
   });
 
   // captureIgnored is the structural coupling that makes sub-agent gitignored

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

@@ -12,14 +12,22 @@
  * Error model: fail-hard. Any attachment failure aborts the entire injection
  * and propagates a descriptive error. Attachments are explicit user inputs —
  * running with partial inputs produces silently incorrect results.
+ *
+ * Duplicate names are NOT a failure (issue #364): a default-derived mount
+ * path that collides is renamed with the platform's `stem-2.ext` semantics
+ * (shared/attachment-naming.ts) and the rename is disclosed in the prompt's
+ * Input Files section. Only two attachments EXPLICITLY pinning the same
+ * `mountPath` still abort — that is a user contradiction no rename can
+ * honestly resolve.
  */
 
 import { readFile } from "node:fs/promises";
 import { createInflateRaw } from "node:zlib";
-import { basename, posix } from "node:path";
+import { 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 { allocateUniqueName } from "../../shared/attachment-naming.js";
 import type {
   VisionBudget,
   VisionDegradedReason,
@@ -38,9 +46,17 @@ export { MAX_ZIP_FILES, MAX_ZIP_EXTRACTED_SIZE };
 // ── Types ────────────────────────────────────────────────────────────
 
 export interface InjectedFile {
+  /** The final on-disk basename — after any duplicate rename, so it always
+   * agrees with {@link path} and with the vision payload's image label. */
   readonly filename: string;
   readonly path: string;
   readonly sizeBytes: number;
+  /**
+   * The attachment's original filename, present only when a duplicate name
+   * was renamed (shared/attachment-naming.ts) — rendered as disclosure in
+   * the prompt's Input Files section.
+   */
+  readonly renamedFrom?: string;
   /** Present when the attachment was accepted into the turn's vision payload. */
   readonly vision?: VisionImage;
   /**
@@ -257,7 +273,9 @@ export function validateZipForExtraction(
 /**
  * Download, validate, and inject all attachments into the workspace.
  *
- * Performs mount path collision detection before any downloads begin.
+ * Resolves all mount paths before any downloads begin: duplicate
+ * default-derived names are renamed (never fatal — see module doc), and an
+ * explicit-mountPath contradiction throws before any bytes move.
  * On any failure, throws AttachmentInjectionError with an actionable message.
  */
 export async function injectAttachments(opts: InjectAttachmentsOptions): Promise<InjectedFile[]> {
@@ -273,17 +291,24 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
 
   for (const attachment of attachments) {
     const content = await downloadAttachment(attachment, storage, isLocalMode);
-    const mountPath = mountPaths.get(attachment)!;
+    const { path: mountPath, renamedFrom } = mountPaths.get(attachment)!;
 
     if (attachment.extract) {
       const entries = validateZipForExtraction(content, attachment.filename);
       const extracted = await extractZipToWorkspace(
         content, entries, mountPath, backend,
       );
+      // A renamed mount DIR is visible through every extracted path; the
+      // entries themselves were not renamed, so they carry no renamedFrom
+      // (per-file disclosure would misattribute the rename).
       injectedFiles.push(...extracted);
     } else {
       await backend.writeFileBuffer(mountPath, content);
-      const filename = attachment.filename || basename(mountPath);
+      // 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 or the
+      // agent sees two images with one indistinguishable name.
+      const filename = posix.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).
@@ -292,6 +317,7 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
         filename,
         path: mountPath,
         sizeBytes: content.length,
+        ...(renamedFrom !== undefined ? { renamedFrom } : {}),
         ...(vision?.kind === "accepted" ? { vision: vision.image } : {}),
         ...(vision?.kind === "degraded" ? { visionDegraded: vision.reason } : {}),
       });
@@ -307,14 +333,24 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
 
 // ── Internal Helpers ─────────────────────────────────────────────────
 
+interface ResolvedMountPath {
+  readonly path: string;
+  /** Present when a default-derived name was uniquified (issue #364). */
+  readonly renamedFrom?: string;
+}
+
 function resolveMountPaths(
   attachments: readonly Attachment[],
-): Map<Attachment, string> {
-  const result = new Map<Attachment, string>();
+): Map<Attachment, ResolvedMountPath> {
+  const result = new Map<Attachment, ResolvedMountPath>();
   const pathToAttachment = new Map<string, Attachment>();
 
+  // Pass 1: explicit mount paths claim their exact targets first. Two
+  // attachments explicitly pinning the SAME path is a user contradiction no
+  // rename can honestly resolve — keep rejecting with the actionable message.
   for (const attachment of attachments) {
-    const mountPath = resolveMountPath(attachment);
+    if (!attachment.mountPath) continue;
+    const mountPath = resolveExplicitMountPath(attachment);
     const existing = pathToAttachment.get(mountPath);
 
     if (existing) {
@@ -326,35 +362,63 @@ function resolveMountPaths(
     }
 
     pathToAttachment.set(mountPath, attachment);
-    result.set(attachment, mountPath);
+    result.set(attachment, { path: mountPath });
+  }
+
+  // Pass 2: default-derived names (`.stigmer/inputs/{filename}`) uniquify
+  // around everything already taken — other defaults AND explicit paths that
+  // landed inside the inputs prefix — instead of failing the execution
+  // (issue #364). The taken-set is seeded with the basenames the explicit
+  // pass claimed directly under the prefix.
+  const takenNames = new Set<string>();
+  for (const path of pathToAttachment.keys()) {
+    if (path.startsWith(`${DEFAULT_INPUTS_PREFIX}/`)) {
+      const rest = path.slice(DEFAULT_INPUTS_PREFIX.length + 1);
+      if (rest.length > 0 && !rest.includes("/")) takenNames.add(rest);
+    }
+  }
+  for (const attachment of attachments) {
+    if (attachment.mountPath) continue;
+    const { name, renamedFrom } = allocateUniqueName(
+      deriveDefaultFilename(attachment),
+      takenNames,
+    );
+    const path = `${DEFAULT_INPUTS_PREFIX}/${name}`;
+    pathToAttachment.set(path, attachment);
+    result.set(
+      attachment,
+      renamedFrom !== undefined ? { path, renamedFrom } : { path },
+    );
   }
 
   return result;
 }
 
-function resolveMountPath(attachment: Attachment): string {
-  if (attachment.mountPath) {
-    const cleaned = attachment.mountPath.replace(/^\/+/, "");
-    if (cleaned.length === 0) {
-      throw new AttachmentInjectionError(
-        attachment.filename,
-        "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;
+function resolveExplicitMountPath(attachment: Attachment): string {
+  const cleaned = attachment.mountPath.replace(/^\/+/, "");
+  if (cleaned.length === 0) {
+    throw new AttachmentInjectionError(
+      attachment.filename,
+      "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;
+}
 
+// Derives the single-component filename an attachment without an explicit
+// mountPath materializes under (the name that pass 2 uniquifies).
+function deriveDefaultFilename(attachment: Attachment): string {
   const rawName = attachment.filename || deriveFilename(attachment.storageKey);
   if (!rawName) {
     throw new AttachmentInjectionError(
@@ -373,7 +437,7 @@ function resolveMountPath(attachment: Attachment): string {
     );
   }
 
-  return `${DEFAULT_INPUTS_PREFIX}/${filename}`;
+  return filename;
 }
 
 // escapesRoot reports whether a workspace-relative mount path would climb out

package/src/activities/execute-deep-agent/environment.ts

@@ -30,7 +30,9 @@ export async function resolveEnvironment(
 ): Promise<EnvironmentResult> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this execution's session, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would resolve redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     agentExecutionId: executionId,
   });