fix(build): Scope DerivedData by invocation context

Compute the default DerivedData path from the resolved workspace or project used for each xcodebuild invocation instead of storing execution-derived state in session defaults. This keeps concurrent worktrees from sharing the same build cache while preserving explicit derivedDataPath overrides.

Propagate explicit derivedDataPath through app-path lookups and generated next steps so follow-up commands inspect the same build location. Update unit and snapshot fixtures for the scoped DerivedData path shape.

Fixes #340
Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: cameroncooke

CHANGELOG.md

@@ -21,7 +21,7 @@
 
 ### Changed
 
-- Auto-scope DerivedData per workspace/project path when no explicit `derivedDataPath` is configured. The session store now derives a hashed sub-directory under the global DerivedData root from the active workspace or project path, so concurrent agents and git worktrees no longer share a single explicit DerivedData and corrupt incremental builds. Explicit `derivedDataPath` still takes precedence ([#340](https://github.com/getsentry/XcodeBuildMCP/issues/340)).
+- Auto-scope DerivedData per workspace/project path at xcodebuild invocation time when no explicit `derivedDataPath` is configured. Session defaults remain raw, while build/test/app-path commands derive a stable hashed subdirectory under the global DerivedData root from the resolved workspace or project path. Explicit `derivedDataPath` still takes precedence ([#340](https://github.com/getsentry/XcodeBuildMCP/issues/340)).
 
 ## [2.3.2]
 

src/mcp/tools/device/__tests__/build_device.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { DERIVED_DATA_DIR } from '../../../../utils/log-paths.ts';
+import { computeScopedDerivedDataPath } from '../../../../utils/derived-data-path.ts';
 import * as z from 'zod';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
 import { expectPendingBuildResponse, runToolLogic } from '../../../../test-utils/test-helpers.ts';
@@ -172,7 +172,7 @@ describe('build_device plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/MyProject.xcworkspace'),
         'build',
       ]);
       expect(spy.commandCalls[0].logPrefix).toBe('iOS Device Build');
@@ -206,7 +206,7 @@ describe('build_device plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/MyProject.xcodeproj'),
         'build',
       ]);
       expect(spy.commandCalls[0].logPrefix).toBe('iOS Device Build');
@@ -265,6 +265,30 @@ describe('build_device plugin', () => {
       expectPendingBuildResponse(result, 'get_device_app_path');
     });
 
+    it('should include explicit derivedDataPath in get_device_app_path next step', async () => {
+      const mockExecutor = createMockExecutor({
+        success: true,
+        output: 'Build succeeded',
+      });
+
+      const { result } = await runToolLogic(() =>
+        buildDeviceLogic(
+          {
+            projectPath: '/path/to/MyProject.xcodeproj',
+            scheme: 'MyScheme',
+            derivedDataPath: '/tmp/derived-data',
+          },
+          mockExecutor,
+        ),
+      );
+
+      expect(result.isError()).toBeFalsy();
+      expect(result.nextStepParams?.get_device_app_path).toEqual({
+        scheme: 'MyScheme',
+        derivedDataPath: '/tmp/derived-data',
+      });
+    });
+
     it('should return exact build failure response', async () => {
       const mockExecutor = createMockExecutor({
         success: false,

src/mcp/tools/device/__tests__/get_device_app_path.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { DERIVED_DATA_DIR } from '../../../../utils/log-paths.ts';
+import { computeScopedDerivedDataPath } from '../../../../utils/derived-data-path.ts';
 import * as z from 'zod';
 import {
   createMockCommandResponse,
@@ -134,7 +134,7 @@ describe('get_device_app_path plugin', () => {
           '-destination',
           'generic/platform=iOS',
           '-derivedDataPath',
-          DERIVED_DATA_DIR,
+          computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         ],
         logPrefix: 'Get App Path',
         useShell: false,
@@ -193,7 +193,7 @@ describe('get_device_app_path plugin', () => {
           '-destination',
           'generic/platform=watchOS',
           '-derivedDataPath',
-          DERIVED_DATA_DIR,
+          computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         ],
         logPrefix: 'Get App Path',
         useShell: false,
@@ -251,7 +251,7 @@ describe('get_device_app_path plugin', () => {
           '-destination',
           'generic/platform=iOS',
           '-derivedDataPath',
-          DERIVED_DATA_DIR,
+          computeScopedDerivedDataPath('/path/to/workspace.xcworkspace'),
         ],
         logPrefix: 'Get App Path',
         useShell: false,
@@ -343,6 +343,60 @@ describe('get_device_app_path plugin', () => {
       expect(result.nextStepParams).toBeUndefined();
     });
 
+    it('should use explicit derivedDataPath when resolving build settings', async () => {
+      const calls: Array<{
+        args: string[];
+        logPrefix?: string;
+        useShell?: boolean;
+        opts?: { cwd?: string };
+      }> = [];
+
+      const mockExecutor = (
+        args: string[],
+        logPrefix?: string,
+        useShell?: boolean,
+        opts?: { cwd?: string },
+        _detached?: boolean,
+      ) => {
+        calls.push({ args, logPrefix, useShell, opts });
+        return Promise.resolve(
+          createMockCommandResponse({
+            success: true,
+            output:
+              'Build settings for scheme "MyScheme"\n\nBUILT_PRODUCTS_DIR = /path/to/build/Debug-iphoneos\nFULL_PRODUCT_NAME = MyApp.app\n',
+            error: undefined,
+          }),
+        );
+      };
+
+      await runLogic(() =>
+        get_device_app_pathLogic(
+          {
+            projectPath: '/path/to/project.xcodeproj',
+            scheme: 'MyScheme',
+            derivedDataPath: '/custom/DerivedData',
+          },
+          mockExecutor,
+        ),
+      );
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].args).toEqual([
+        'xcodebuild',
+        '-showBuildSettings',
+        '-project',
+        '/path/to/project.xcodeproj',
+        '-scheme',
+        'MyScheme',
+        '-configuration',
+        'Debug',
+        '-destination',
+        'generic/platform=iOS',
+        '-derivedDataPath',
+        '/custom/DerivedData',
+      ]);
+    });
+
     it('should include optional configuration parameter in command', async () => {
       const calls: Array<{
         args: string[];
@@ -394,7 +448,7 @@ describe('get_device_app_path plugin', () => {
           '-destination',
           'generic/platform=iOS',
           '-derivedDataPath',
-          DERIVED_DATA_DIR,
+          computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         ],
         logPrefix: 'Get App Path',
         useShell: false,

src/mcp/tools/device/__tests__/test_device.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import * as z from 'zod';
-import { DERIVED_DATA_DIR } from '../../../../utils/log-paths.ts';
+import { computeScopedDerivedDataPath } from '../../../../utils/derived-data-path.ts';
 import {
   createMockExecutor,
   createMockFileSystemExecutor,
@@ -166,7 +166,7 @@ describe('test_device plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         'test',
       ]);
     });

src/mcp/tools/device/build_device.ts

@@ -27,13 +27,15 @@ import {
   setXcodebuildStructuredOutput,
 } from '../../../utils/xcodebuild-domain-results.ts';
 import type { BuildInvocationRequest } from '../../../types/domain-fragments.ts';
+import { resolveEffectiveDerivedDataPath } from '../../../utils/derived-data-path.ts';
 import { createBuildInvocationFragment } from '../../../utils/xcodebuild-pipeline.ts';
 
 function createBuildDeviceRequest(params: BuildDeviceParams): BuildInvocationRequest {
   return {
     scheme: params.scheme,
     workspacePath: params.workspacePath,
     projectPath: params.projectPath,
+    derivedDataPath: resolveEffectiveDerivedDataPath(params),
     configuration: params.configuration ?? 'Debug',
     platform: String(mapDevicePlatform(params.platform)),
     target: 'device',
@@ -123,6 +125,9 @@ export async function buildDeviceLogic(
     ctx.nextStepParams = {
       get_device_app_path: {
         scheme: params.scheme,
+        ...(params.derivedDataPath !== undefined
+          ? { derivedDataPath: params.derivedDataPath }
+          : {}),
       },
     };
   }

src/mcp/tools/device/build_run_device.ts

@@ -34,13 +34,15 @@ import {
   createDomainStreamingPipeline,
   setXcodebuildStructuredOutput,
 } from '../../../utils/xcodebuild-domain-results.ts';
+import { resolveEffectiveDerivedDataPath } from '../../../utils/derived-data-path.ts';
 import { createBuildInvocationFragment } from '../../../utils/xcodebuild-pipeline.ts';
 
 function createBuildRunDeviceRequest(params: BuildRunDeviceParams): BuildInvocationRequest {
   return {
     scheme: params.scheme,
     workspacePath: params.workspacePath,
     projectPath: params.projectPath,
+    derivedDataPath: resolveEffectiveDerivedDataPath(params),
     configuration: params.configuration ?? 'Debug',
     platform: String(mapDevicePlatform(params.platform)),
     deviceId: params.deviceId,

src/mcp/tools/device/get_device_app_path.ts

@@ -32,6 +32,7 @@ import {
 const baseOptions = {
   scheme: z.string().describe('The scheme to use'),
   configuration: z.string().optional().describe('Build configuration (Debug, Release, etc.)'),
+  derivedDataPath: z.string().optional(),
   platform: devicePlatformSchema,
 };
 
@@ -53,6 +54,7 @@ const publicSchemaObject = baseSchemaObject.omit({
   workspacePath: true,
   scheme: true,
   configuration: true,
+  derivedDataPath: true,
 } as const);
 
 function createRequest(params: GetDeviceAppPathParams) {
@@ -82,6 +84,7 @@ export function createGetDeviceAppPathExecutor(
           scheme: params.scheme,
           configuration,
           platform,
+          derivedDataPath: params.derivedDataPath,
         },
         executor,
       );

src/mcp/tools/device/test_device.ts

@@ -29,6 +29,7 @@ import {
   setXcodebuildStructuredOutput,
 } from '../../../utils/xcodebuild-domain-results.ts';
 import type { BuildInvocationRequest } from '../../../types/domain-fragments.ts';
+import { resolveEffectiveDerivedDataPath } from '../../../utils/derived-data-path.ts';
 import { createBuildInvocationFragment } from '../../../utils/xcodebuild-pipeline.ts';
 
 const baseSchemaObject = z.object({
@@ -102,6 +103,9 @@ async function prepareTestDeviceExecution(
     preflight: preflight ?? undefined,
     invocationRequest: {
       scheme: params.scheme,
+      workspacePath: params.workspacePath,
+      projectPath: params.projectPath,
+      derivedDataPath: resolveEffectiveDerivedDataPath(params),
       configuration,
       platform: String(platform),
       deviceId: params.deviceId,

src/mcp/tools/macos/__tests__/build_macos.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { DERIVED_DATA_DIR } from '../../../../utils/log-paths.ts';
+import { computeScopedDerivedDataPath } from '../../../../utils/derived-data-path.ts';
 import * as z from 'zod';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
 import { expectPendingBuildResponse, runToolLogic } from '../../../../test-utils/test-helpers.ts';
@@ -205,7 +205,7 @@ describe('build_macos plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         'build',
       ]);
     });
@@ -303,7 +303,7 @@ describe('build_macos plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         'build',
       ]);
     });
@@ -333,7 +333,7 @@ describe('build_macos plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/Users/dev/My Project/MyProject.xcodeproj'),
         'build',
       ]);
     });
@@ -363,7 +363,7 @@ describe('build_macos plugin', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/workspace.xcworkspace'),
         'build',
       ]);
     });

src/mcp/tools/macos/__tests__/build_run_macos.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { DERIVED_DATA_DIR } from '../../../../utils/log-paths.ts';
+import { computeScopedDerivedDataPath } from '../../../../utils/derived-data-path.ts';
 import * as z from 'zod';
 import { createMockExecutor, mockProcess } from '../../../../test-utils/mock-executors.ts';
 import { runToolLogic, type MockToolHandlerResult } from '../../../../test-utils/test-helpers.ts';
@@ -127,7 +127,7 @@ describe('build_run_macos', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         'build',
       ]);
       expect(executorCalls[0].description).toBe('macOS Build');
@@ -195,7 +195,7 @@ describe('build_run_macos', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/workspace.xcworkspace'),
         'build',
       ]);
 
@@ -398,7 +398,7 @@ describe('build_run_macos', () => {
         '-collect-test-diagnostics',
         'never',
         '-derivedDataPath',
-        DERIVED_DATA_DIR,
+        computeScopedDerivedDataPath('/path/to/project.xcodeproj'),
         'build',
       ]);
       expect(executorCalls[0].description).toBe('macOS Build');