@stigmer/runner 3.9.0 → 3.11.0

package/src/payload-codecs.ts

@@ -0,0 +1,56 @@
+/**
+ * Single assembly point for the worker's payload codec chain, shared by
+ * the standalone runner (runner.ts) and the runner manager
+ * (runner-manager.ts) so the two entrypoints cannot drift.
+ *
+ * Codec order is a correctness property, not a style choice. Temporal
+ * applies codecs in array order on encode and in reverse on decode, so
+ * with [encryption, claimcheck]:
+ *
+ *   encode: encrypt → claim-check   (payloads the claim-check codec
+ *           relocates to object storage are already ciphertext)
+ *   decode: claim-check → decrypt   (restore the blob, then decrypt)
+ */
+
+import type { PayloadCodec } from "@temporalio/common";
+import type { Config } from "./config.js";
+
+export async function createPayloadCodecs(
+  config: Config,
+): Promise<PayloadCodec[] | undefined> {
+  const codecs: PayloadCodec[] = [];
+
+  const { loadPayloadEncryptionConfig, EncryptionPayloadCodec } = await import(
+    "./encryption/index.js"
+  );
+  const encryptionConfig = loadPayloadEncryptionConfig();
+  if (encryptionConfig) {
+    codecs.push(new EncryptionPayloadCodec(encryptionConfig));
+    console.log(
+      `[runner] Payload encryption enabled (key_id=${encryptionConfig.primary.keyId}` +
+        (encryptionConfig.secondary
+          ? `, secondary_key_id=${encryptionConfig.secondary.keyId})`
+          : ")"),
+    );
+  }
+
+  const { loadClaimcheckConfig, ClaimcheckPayloadCodec } = await import(
+    "./claimcheck/index.js"
+  );
+  const claimcheckConfig = loadClaimcheckConfig();
+  if (claimcheckConfig.enabled) {
+    const { loadArtifactStorageConfig, createArtifactStorage } = await import(
+      "./shared/artifact-storage.js"
+    );
+    const storageConfig = loadArtifactStorageConfig(config);
+    const storage = createArtifactStorage(storageConfig);
+    codecs.push(new ClaimcheckPayloadCodec(storage, claimcheckConfig));
+    console.log(
+      `[runner] Claimcheck enabled (threshold=${claimcheckConfig.thresholdBytes}B, ` +
+        `compression=${claimcheckConfig.compressionEnabled}, ` +
+        `storage=${storageConfig.type})`,
+    );
+  }
+
+  return codecs.length > 0 ? codecs : undefined;
+}

package/src/preflight.ts

@@ -21,8 +21,15 @@
  * The gate is unconditional (not checkpointer-type-dependent): the eager
  * import chain needs `node:sqlite` to LOAD regardless of configuration, so
  * the gate mirrors the actual load-time requirement.
+ *
+ * This module also hosts {@link assertLlmBackendsPreflight}, the
+ * deployment-config gate the runner factories run at construction. The
+ * llm-backend import below is a pure, dependency-free module, so it does
+ * not compromise the load-order guarantees above.
  */
 
+import { preflightLlmBackends } from "./shared/llm-backend.js";
+
 /**
  * True when this Node binary provides the built-in `node:sqlite`.
  *
@@ -57,3 +64,41 @@ export function preflightNodeRuntime(
     `Use Node >= 22.13 (22.x line) or >= 23.4 (23.x and later).`
   );
 }
+
+/**
+ * Validate LLM backend configuration (STIGMER_ANTHROPIC_BACKEND /
+ * STIGMER_OPENAI_BACKEND) at runner construction, throwing an actionable
+ * operator message on fatal misconfiguration and logging precedence
+ * warnings.
+ *
+ * Called from the runner factories rather than main.ts because
+ * @stigmer/runner is a public library: in-process embedders never execute
+ * main.ts, while all of main.ts's process modes construct through the
+ * factories. A library must never process.exit, so this throws — manager
+ * mode's factory catch converts it to a fatal IPC error for the desktop
+ * host, static/pool modes exit through main()'s fatal handler, and
+ * embedders get a rejected promise.
+ *
+ * Backend misconfiguration is deployment-static; failing here means a
+ * broken deployment refuses to accept work instead of failing every
+ * execution mid-flight (the createClient factories construct lazily on
+ * first request, far too late for a good operator experience).
+ *
+ * @param proxyEndpoint The effective proxy endpoint. Factories receive it
+ *   via options (env-derived in main.ts flows, caller-supplied for
+ *   embedders), so it is threaded explicitly instead of re-read from env —
+ *   an options-supplied proxy must downgrade backend vars to warnings the
+ *   same way STIGMER_PROXY_ENDPOINT does.
+ */
+export function assertLlmBackendsPreflight(proxyEndpoint?: string | null): void {
+  const env = proxyEndpoint
+    ? { ...process.env, STIGMER_PROXY_ENDPOINT: proxyEndpoint }
+    : process.env;
+  const { error, warnings } = preflightLlmBackends(env);
+  for (const warning of warnings) {
+    console.warn(`[runner] ${warning}`);
+  }
+  if (error !== null) {
+    throw new Error(error);
+  }
+}

package/src/runner-manager.ts

@@ -22,7 +22,6 @@ import {
   type InjectedSinks,
   type WorkflowBundleOption,
 } from "@temporalio/worker";
-import type { PayloadCodec } from "@temporalio/common";
 import type { Config } from "./config.js";
 import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS, DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./config.js";
 // Boot marks mirror the static runner's segment names where the work is the
@@ -32,6 +31,7 @@ import { markBoot } from "./shared/cold-start-timing.js";
 import type { WorkerActivities } from "./worker.js";
 import { resolveWorkflowSource, OTEL_WORKFLOW_INTERCEPTOR_MODULE } from "./workflow-source.js";
 import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "./bootstrap.js";
+import { assertLlmBackendsPreflight } from "./preflight.js";
 import { createRunnerTokenCoordinator } from "./runner-token-coordinator.js";
 // Per-task-queue in-flight activity tracking lives in ./in-flight.ts so the
 // activity interceptor (no manager-closure handle) and unit tests can reach it.
@@ -237,6 +237,8 @@ export async function createStigmerRunnerManager(
   const runnerTokenRef = { current: options.stigmerToken ?? null };
   const baseConfig = mapManagerOptionsToConfig(options, tokenRef, runnerTokenRef);
 
+  assertLlmBackendsPreflight(baseConfig.proxyEndpoint);
+
   // Install the Cursor SDK interceptors BEFORE resolving Temporal coordinates.
   // Coordinate discovery dials the control plane via StigmerClient, which loads
   // @connectrpc/connect-node and snapshots the node:http2 ESM facade on first
@@ -351,7 +353,8 @@ export async function createStigmerRunnerManager(
       `[runner-manager] Artifact store: could not resolve config for boot log: ${err}`,
     );
   }
-  const payloadCodec = await createPayloadCodec(config);
+  const { createPayloadCodecs } = await import("./payload-codecs.js");
+  const payloadCodecs = await createPayloadCodecs(config);
 
   const connection = await NativeConnection.connect({
     address: config.temporalAddress,
@@ -396,9 +399,7 @@ export async function createStigmerRunnerManager(
       activities,
       workflowBundle,
       maxConcurrentActivityTaskExecutions: config.maxConcurrentActivities,
-      dataConverter: payloadCodec
-        ? { payloadCodecs: [payloadCodec] }
-        : undefined,
+      dataConverter: payloadCodecs?.length ? { payloadCodecs } : undefined,
       sinks: interceptorConfig.sinks,
       interceptors: interceptorConfig.interceptors,
     });
@@ -739,25 +740,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
   };
 }
 
-async function createPayloadCodec(
-  config: Config,
-): Promise<PayloadCodec | undefined> {
-  const { loadClaimcheckConfig, ClaimcheckPayloadCodec } = await import(
-    "./claimcheck/index.js"
-  );
-  const claimcheckConfig = loadClaimcheckConfig();
-  if (!claimcheckConfig.enabled) {
-    return undefined;
-  }
-
-  const { loadArtifactStorageConfig, createArtifactStorage } = await import(
-    "./shared/artifact-storage.js"
-  );
-  const storageConfig = loadArtifactStorageConfig(config);
-  const storage = createArtifactStorage(storageConfig);
-  return new ClaimcheckPayloadCodec(storage, claimcheckConfig);
-}
-
 interface InterceptorConfig {
   sinks: InjectedSinks<any>;
   interceptors: Record<string, any>;

package/src/runner.ts

@@ -15,11 +15,11 @@
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
-import type { PayloadCodec } from "@temporalio/common";
 import type { Config } from "./config.js";
 import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS, DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./config.js";
 import type { WorkerActivities } from "./worker.js";
 import { resolveRunnerBootstrap } from "./bootstrap.js";
+import { assertLlmBackendsPreflight } from "./preflight.js";
 import { markBoot, emitRunnerBootTiming } from "./shared/cold-start-timing.js";
 
 /**
@@ -197,6 +197,8 @@ export async function createStigmerRunner(
 
   const baseConfig = mapOptionsToConfig(options);
 
+  assertLlmBackendsPreflight(baseConfig.proxyEndpoint);
+
   // Install the Cursor SDK interceptors BEFORE resolving Temporal coordinates.
   // Coordinate discovery dials the control plane via StigmerClient, which loads
   // @connectrpc/connect-node and snapshots the node:http2 ESM facade on first
@@ -302,10 +304,11 @@ export async function createStigmerRunner(
     );
   }
 
-  const payloadCodec = await createPayloadCodec(config);
+  const { createPayloadCodecs } = await import("./payload-codecs.js");
+  const payloadCodecs = await createPayloadCodecs(config);
 
   const { startWorker } = await import("./worker.js");
-  const worker = await startWorker({ config, activities, payloadCodec });
+  const worker = await startWorker({ config, activities, payloadCodecs });
   markBoot("worker_created");
 
   return {
@@ -455,28 +458,6 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
   };
 }
 
-async function createPayloadCodec(config: Config): Promise<PayloadCodec | undefined> {
-  const { loadClaimcheckConfig, ClaimcheckPayloadCodec } = await import("./claimcheck/index.js");
-  const claimcheckConfig = loadClaimcheckConfig();
-  if (!claimcheckConfig.enabled) {
-    return undefined;
-  }
-
-  const { loadArtifactStorageConfig, createArtifactStorage } = await import(
-    "./shared/artifact-storage.js"
-  );
-  const storageConfig = loadArtifactStorageConfig(config);
-  const storage = createArtifactStorage(storageConfig);
-
-  console.log(
-    `[runner] Claimcheck enabled (threshold=${claimcheckConfig.thresholdBytes}B, ` +
-      `compression=${claimcheckConfig.compressionEnabled}, ` +
-      `storage=${storageConfig.type})`,
-  );
-
-  return new ClaimcheckPayloadCodec(storage, claimcheckConfig);
-}
-
 function resolveDefaultWorkspaceDir(): string {
   try {
     const dir = join(homedir(), ".stigmer", "workspaces", "runner");

package/src/shared/__tests__/approval-policy.test.ts

@@ -19,7 +19,6 @@ import {
 } from "../approval-policy.js";
 import type { ToolApprovalCategory } from "../tool-kind.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
-import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ApprovalAction, ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
@@ -83,6 +82,9 @@ function makeServer(
   slug: string,
   toolApprovals: Array<{ toolName: string; message?: string }>,
   pinnedToolApprovals: Array<{ toolName: string; message?: string }> = [],
+  // Layer-3 overrides ride the server they were declared on (issue #349) —
+  // there is no cross-server override input to the merge anymore.
+  toolApprovalOverrides: Array<{ toolName: string; requiresApproval: boolean; message?: string }> = [],
 ): ResolvedMcpServer {
   return {
     slug,
@@ -95,6 +97,11 @@ function makeServer(
       toolName: a.toolName,
       message: a.message ?? "",
     })) as any[],
+    toolApprovalOverrides: toolApprovalOverrides.map(o => ({
+      toolName: o.toolName,
+      requiresApproval: o.requiresApproval,
+      message: o.message ?? "",
+    })) as any[],
     discoveredCapabilitiesEmpty: false,
   };
 }
@@ -102,7 +109,7 @@ function makeServer(
 describe("mergeApprovalPolicies", () => {
   it("returns empty map under a global lease (spec.auto_approve_all)", () => {
     const servers = [makeServer("github", [{ toolName: "push" }])];
-    const result = mergeApprovalPolicies(servers, [], leases({ global: true }));
+    const result = mergeApprovalPolicies(servers, leases({ global: true }));
     expect(result.size).toBe(0);
   });
 
@@ -111,7 +118,7 @@ describe("mergeApprovalPolicies", () => {
       makeServer("github", [{ toolName: "push" }]),
       makeServer("database", [{ toolName: "drop_table" }]),
     ];
-    const result = mergeApprovalPolicies(servers, [], leases({ servers: ["github"] }));
+    const result = mergeApprovalPolicies(servers, leases({ servers: ["github"] }));
     expect(result.has("github/push")).toBe(false);
     expect(result.has("database/drop_table")).toBe(true);
   });
@@ -122,7 +129,7 @@ describe("mergeApprovalPolicies", () => {
         { toolName: "create_issue", message: "Create issue?" },
       ]),
     ];
-    const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
 
     expect(result.size).toBe(1);
     const policy = result.get("github/create_issue")!;
@@ -139,7 +146,7 @@ describe("mergeApprovalPolicies", () => {
         [{ toolName: "push", message: "pinned message" }],
       ),
     ];
-    const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
 
     const policy = result.get("github/push")!;
     expect(policy.approvalMessage).toBe("pinned message");
@@ -147,34 +154,74 @@ describe("mergeApprovalPolicies", () => {
 
   it("agent overrides can disable approval", () => {
     const servers = [
-      makeServer("github", [{ toolName: "push" }]),
+      makeServer("github", [{ toolName: "push" }], [], [
+        { toolName: "push", requiresApproval: false },
+      ]),
     ];
-    const overrides: ToolApprovalOverride[] = [{
-      toolName: "push",
-      requiresApproval: false,
-      message: "",
-    }] as any[];
 
-    const result = mergeApprovalPolicies(servers, overrides, NO_LEASES);
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
     expect(result.size).toBe(0);
   });
 
   it("agent overrides can add new approval requirement", () => {
-    const servers = [makeServer("github", [])];
-    const overrides: ToolApprovalOverride[] = [{
-      toolName: "delete_repo",
-      requiresApproval: true,
-      message: "Really delete?",
-    }] as any[];
-
-    const result = mergeApprovalPolicies(servers, overrides, NO_LEASES);
+    const servers = [
+      makeServer("github", [], [], [
+        { toolName: "delete_repo", requiresApproval: true, message: "Really delete?" },
+      ]),
+    ];
+
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
     expect(result.has("github/delete_repo")).toBe(true);
   });
 
+  describe("override scoping (issue #349 — no cross-server leak)", () => {
+    it("a disable override on one server leaves a same-named classifier-gated tool on another server gated", () => {
+      // The dangerous direction: before #349 this override silently
+      // un-gated database/delete_item too (authorization widening).
+      const servers = [
+        makeServer("github", [{ toolName: "delete_item" }], [], [
+          { toolName: "delete_item", requiresApproval: false },
+        ]),
+        makeServer("database", [{ toolName: "delete_item" }]),
+      ];
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
+      expect(result.has("github/delete_item")).toBe(false);
+      const other = result.get("database/delete_item")!;
+      expect(other.requiresApproval).toBe(true);
+      expect(other.source).toBe("classifier_default");
+    });
+
+    it("an enable override on one server adds no gate for a same-named tool on another server", () => {
+      const servers = [
+        makeServer("github", [], [], [
+          { toolName: "send_message", requiresApproval: true },
+        ]),
+        makeServer("slack", []),
+      ];
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
+      expect(result.has("github/send_message")).toBe(true);
+      expect(result.has("slack/send_message")).toBe(false);
+    });
+
+    it("a message override on one server does not re-message a same-named gate on another server", () => {
+      const servers = [
+        makeServer("github", [{ toolName: "push", message: "github classifier" }], [], [
+          { toolName: "push", requiresApproval: true, message: "github override" },
+        ]),
+        makeServer("gitlab", [{ toolName: "push", message: "gitlab classifier" }]),
+      ];
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
+      expect(result.get("github/push")!.approvalMessage).toBe("github override");
+      const other = result.get("gitlab/push")!;
+      expect(other.approvalMessage).toBe("gitlab classifier");
+      expect(other.source).toBe("classifier_default");
+    });
+  });
+
   describe("provenance (source stamping)", () => {
     it("stamps classifier_default for a layer-1 tool approval", () => {
       const servers = [makeServer("github", [{ toolName: "create_issue" }])];
-      const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
       expect(result.get("github/create_issue")!.source).toBe("classifier_default");
     });
 
@@ -182,31 +229,27 @@ describe("mergeApprovalPolicies", () => {
       const servers = [
         makeServer("github", [{ toolName: "push" }], [{ toolName: "push" }]),
       ];
-      const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
       expect(result.get("github/push")!.source).toBe("pinned_override");
     });
 
     it("stamps agent_override when a per-agent override adds a gate", () => {
-      const servers = [makeServer("github", [])];
-      const overrides: ToolApprovalOverride[] = [{
-        toolName: "delete_repo",
-        requiresApproval: true,
-        message: "Really delete?",
-      }] as any[];
-      const result = mergeApprovalPolicies(servers, overrides, NO_LEASES);
+      const servers = [
+        makeServer("github", [], [], [
+          { toolName: "delete_repo", requiresApproval: true, message: "Really delete?" },
+        ]),
+      ];
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
       expect(result.get("github/delete_repo")!.source).toBe("agent_override");
     });
 
     it("stamps agent_override when it overrides a classifier/pinned entry", () => {
       const servers = [
-        makeServer("github", [{ toolName: "push", message: "classifier" }]),
+        makeServer("github", [{ toolName: "push", message: "classifier" }], [], [
+          { toolName: "push", requiresApproval: true, message: "agent says gate" },
+        ]),
       ];
-      const overrides: ToolApprovalOverride[] = [{
-        toolName: "push",
-        requiresApproval: true,
-        message: "agent says gate",
-      }] as any[];
-      const result = mergeApprovalPolicies(servers, overrides, NO_LEASES);
+      const result = mergeApprovalPolicies(servers, NO_LEASES);
       const policy = result.get("github/push")!;
       expect(policy.source).toBe("agent_override");
       expect(policy.approvalMessage).toBe("agent says gate");
@@ -217,7 +260,7 @@ describe("mergeApprovalPolicies", () => {
     const servers = [
       makeServer("github", [{ toolName: "" }]),
     ];
-    const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
     expect(result.size).toBe(0);
   });
 
@@ -225,7 +268,7 @@ describe("mergeApprovalPolicies", () => {
     const servers = [
       makeServer("github", [{ toolName: "push" }]),
     ];
-    const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
     expect(result.get("github/push")!.approvalMessage).toContain("Execute tool: push");
   });
 
@@ -234,7 +277,7 @@ describe("mergeApprovalPolicies", () => {
       makeServer("github", [{ toolName: "push" }]),
       makeServer("database", [{ toolName: "drop_table" }]),
     ];
-    const result = mergeApprovalPolicies(servers, [], NO_LEASES);
+    const result = mergeApprovalPolicies(servers, NO_LEASES);
     expect(result.size).toBe(2);
     expect(result.has("github/push")).toBe(true);
     expect(result.has("database/drop_table")).toBe(true);

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

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { uniquifyFilename, allocateUniqueName } from "../attachment-naming.js";
+import { injectAttachments } from "../../activities/execute-deep-agent/attachment-injector.js";
+import { resolveAttachments } from "../../activities/execute-cursor/attachment-resolver.js";
+import { getPlatformDir } from "../workspace/platform-dir.js";
+import { makeInMemoryArtifactStorage } from "../../__test-utils__/fake-artifact-storage.js";
+import type { WorkspaceBackend } from "../workspace/types.js";
+
+describe("uniquifyFilename", () => {
+  // This table is the byte-for-byte twin of the React SDK suite
+  // (sdk/react/src/attachment/__tests__/attachment-utils.test.ts) — the two
+  // implementations are kept in sync by hand, so their pins must agree.
+  const cases: Array<{
+    scenario: string;
+    name: string;
+    taken: string[];
+    expected: string;
+  }> = [
+    {
+      scenario: "returns the name unchanged when nothing collides",
+      name: "report.pdf",
+      taken: [],
+      expected: "report.pdf",
+    },
+    {
+      scenario: "suffixes -2 before the extension on first collision",
+      name: "report.pdf",
+      taken: ["report.pdf"],
+      expected: "report-2.pdf",
+    },
+    {
+      scenario: "walks past already-taken suffixes",
+      name: "report.pdf",
+      taken: ["report.pdf", "report-2.pdf", "report-3.pdf"],
+      expected: "report-4.pdf",
+    },
+    {
+      scenario: "handles names without an extension",
+      name: "Makefile",
+      taken: ["Makefile"],
+      expected: "Makefile-2",
+    },
+    {
+      scenario: "treats a leading dot as a hidden-file prefix, not an extension",
+      name: ".env",
+      taken: [".env"],
+      expected: ".env-2",
+    },
+    {
+      scenario: "only splits on the last dot of a multi-dot name",
+      name: "backup.tar.gz",
+      taken: ["backup.tar.gz"],
+      expected: "backup.tar-2.gz",
+    },
+  ];
+
+  for (const { scenario, name, taken, expected } of cases) {
+    it(scenario, () => {
+      expect(uniquifyFilename(name, new Set(taken))).toBe(expected);
+    });
+  }
+});
+
+describe("allocateUniqueName", () => {
+  it("claims the allocated name so sequential allocations see each other", () => {
+    const taken = new Set<string>();
+
+    expect(allocateUniqueName("data.csv", taken)).toEqual({ name: "data.csv" });
+    expect(allocateUniqueName("data.csv", taken)).toEqual({
+      name: "data-2.csv",
+      renamedFrom: "data.csv",
+    });
+    expect(allocateUniqueName("data.csv", taken)).toEqual({
+      name: "data-3.csv",
+      renamedFrom: "data.csv",
+    });
+    expect(taken).toEqual(new Set(["data.csv", "data-2.csv", "data-3.csv"]));
+  });
+
+  it("carries no renamedFrom when the name was free (nothing to disclose)", () => {
+    const allocated = allocateUniqueName("report.pdf", new Set());
+    expect(allocated.name).toBe("report.pdf");
+    expect("renamedFrom" in allocated && allocated.renamedFrom !== undefined).toBe(false);
+  });
+});
+
+describe("cross-harness naming parity", () => {
+  // Both harnesses must resolve the same attachment list to the same final
+  // basenames — one platform answer, not two accidental ones (issue #364).
+  let workspaceDir: string;
+  let sessionId: string;
+  let platformDir: string;
+
+  beforeEach(() => {
+    workspaceDir = mkdtempSync(join(tmpdir(), "naming-parity-ws-"));
+    sessionId = `parity-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    platformDir = getPlatformDir(sessionId);
+  });
+
+  afterEach(() => {
+    rmSync(platformDir, { recursive: true, force: true });
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  function makeAttachment(filename: string, storageKey: string) {
+    return {
+      filename,
+      storageKey,
+      mountPath: "",
+      contentType: "text/plain",
+      extract: false,
+      localPath: "",
+      $typeName: "ai.stigmer.agentic.agentexecution.v1.Attachment" as const,
+      $unknown: undefined,
+    } as any;
+  }
+
+  it("both harnesses produce identical final basenames for the same duplicate-heavy list", async () => {
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01A/data.csv", Buffer.from("a"), "text/plain");
+    await storage.upload("attachments/01B/data.csv", Buffer.from("b"), "text/plain");
+    await storage.upload("attachments/01C/Makefile", Buffer.from("c"), "text/plain");
+    await storage.upload("attachments/01D/Makefile", Buffer.from("d"), "text/plain");
+    const attachments = [
+      makeAttachment("data.csv", "attachments/01A/data.csv"),
+      makeAttachment("data.csv", "attachments/01B/data.csv"),
+      makeAttachment("Makefile", "attachments/01C/Makefile"),
+      makeAttachment("Makefile", "attachments/01D/Makefile"),
+    ];
+
+    const backend = { writeFileBuffer: vi.fn() } as unknown as WorkspaceBackend;
+    const injected = await injectAttachments({
+      backend,
+      attachments,
+      storage,
+      isLocalMode: false,
+    });
+
+    const resolved = await resolveAttachments(attachments, {
+      sessionId,
+      primaryWorkspaceDir: workspaceDir,
+      mode: "cloud",
+      storage,
+    });
+
+    const injectedNames = injected.map((f) => f.filename);
+    const resolvedNames = resolved.map((r) => r.filename);
+    expect(injectedNames).toEqual(["data.csv", "data-2.csv", "Makefile", "Makefile-2"]);
+    expect(resolvedNames).toEqual(injectedNames);
+    expect(injected.map((f) => f.renamedFrom)).toEqual(
+      resolved.map((r) => r.renamedFrom),
+    );
+    // The resolver's files really land under the renamed paths.
+    expect(readFileSync(join(platformDir, "inputs", "data-2.csv"), "utf-8")).toBe("b");
+  });
+});