fix(session-defaults): Keep runtime config immutable after init

Limit config-store persistence updates to session-default fields so non-session runtime\nsettings stay fixed for process lifetime after server startup.\n\nUpdate session profile tooling/manifests to match the new flow, including\nprofile activation behavior and clearer session-default tool descriptions.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

docs/SESSION_DEFAULTS.md

@@ -28,8 +28,12 @@ You can also manually create the config file to essentially seed the defaults at
 ## Namespaced profiles
 Session defaults support named profiles so one workspace can keep separate defaults for iOS/watchOS/macOS (or any custom profile names).
 
-- Use `session_use_defaults_profile` to switch the active profile.
+- Use `session_use_defaults_profile` to switch the active profile (existing profiles only).
 - Existing tools (`session_set_defaults`, `session_show_defaults`, build/test tools) use the active profile automatically.
+- `session_set_defaults` can also accept `profile` to switch and set in one call; use `createIfNotExists: true` to create a new profile intentionally.
+- Profiles are strictly isolated: values are not inherited from global defaults or other profiles.
+- The unnamed global defaults profile exists for backwards compatibility and is the default active profile when no named profile is selected.
+- There is always an active profile context: either a named profile or `global`.
 - Use `global: true` to switch back to the unnamed global profile.
 - Set `persist: true` on `session_use_defaults_profile` to write `activeSessionDefaultsProfile` in `.xcodebuildmcp/config.yaml`.
 
@@ -59,6 +63,11 @@ Switch targets later in the same session:
 }}
 ```
 
+Isolation example:
+- Global profile has `workspacePath: /repo/MyApp.xcworkspace`
+- Active profile is `watch` with only `scheme` set
+- Result: `watch` does not see global `workspacePath` until you set it on `watch` or switch back to `global`
+
 ## Related docs
 - Configuration options: [CONFIGURATION.md](CONFIGURATION.md)
 - Tools reference: [TOOLS.md](TOOLS.md)

docs/TOOLS-CLI.md

@@ -189,4 +189,4 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T16:38:52.535Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T21:23:33.036Z UTC*

docs/TOOLS.md

@@ -128,10 +128,10 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 ### Session Management (`session-management`)
 **Purpose**: Manage session defaults for project/workspace paths, scheme, configuration, simulator/device settings. (5 tools)
 
-- `session_clear_defaults` - Clear session defaults.
-- `session_set_defaults` - Set the session defaults, should be called at least once to set tool defaults.
-- `session_show_defaults` - Show session defaults.
-- `session_use_defaults_profile` - Select the active session defaults profile for multi-target workflows.
+- `session_clear_defaults` - Clear session defaults for the active profile or a specified profile.
+- `session_set_defaults` - Set session defaults for the active profile, or for a specified profile and make it active.
+- `session_show_defaults` - Show the current active defaults.
+- `session_use_defaults_profile` - Switch the active session defaults profile.
 - `sync_xcode_defaults` - Sync session defaults (scheme, simulator) from Xcode's current IDE selection.
 
 
@@ -205,4 +205,4 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T16:38:52.535Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T21:23:33.036Z UTC*

manifests/tools/session_clear_defaults.yaml

@@ -3,7 +3,7 @@ module: mcp/tools/session-management/session_clear_defaults
 names:
   mcp: session_clear_defaults
   cli: clear-defaults
-description: Clear session defaults.
+description: Clear session defaults for the active profile or a specified profile.
 annotations:
   title: Clear Session Defaults
   destructiveHint: true

manifests/tools/session_set_defaults.yaml

@@ -3,7 +3,7 @@ module: mcp/tools/session-management/session_set_defaults
 names:
   mcp: session_set_defaults
   cli: set-defaults
-description: Set the session defaults, should be called at least once to set tool defaults.
+description: Set session defaults for the active profile, or for a specified profile and make it active.
 annotations:
   title: Set Session Defaults
   destructiveHint: true

manifests/tools/session_show_defaults.yaml

@@ -3,7 +3,7 @@ module: mcp/tools/session-management/session_show_defaults
 names:
   mcp: session_show_defaults
   cli: show-defaults
-description: Show session defaults.
+description: Show the current active defaults.
 annotations:
   title: Show Session Defaults
   readOnlyHint: true

manifests/tools/session_use_defaults_profile.yaml

@@ -3,7 +3,7 @@ module: mcp/tools/session-management/session_use_defaults_profile
 names:
   mcp: session_use_defaults_profile
   cli: use-defaults-profile
-description: Select the active session defaults profile for multi-target workflows.
+description: Switch the active session defaults profile.
 annotations:
   title: Use Session Defaults Profile
-  readOnlyHint: true
+  readOnlyHint: false

skills/xcodebuildmcp/SKILL.md

@@ -20,14 +20,16 @@ If a capability is missing, assume your tool list may be hiding tools (search/pr
 
 ### Session defaults
 
-Before you call any other tools, you **must** call `session_show_defaults` to show the current defaults, ensure you then fill in the appropriate missing defaults. You may need to call one or more discovery/list tools to obtain the values needed.
+Before you call any other tools, you **must** call `session_show_defaults` to show the current defaults, then fill in any missing defaults. You may need discovery/list tools first to obtain valid values.
 
-- `session_set_defaults`
-  - Set the session defaults, should be called at least once to set tool defaults.
 - `session_show_defaults`
-  - Show session defaults.
+  - Show the current active defaults (including the active profile name).
+- `session_set_defaults`
+  - Set defaults for the current active profile, or set defaults for a specific profile via `profile`.
+- `session_use_defaults_profile`
+  - Switch the active defaults profile.
 - `session_clear_defaults`
-  - Clear session defaults.
+  - Clear defaults (current active profile by default, or a specific profile when provided).
 
 ### Project discovery
 

src/mcp/tools/session-management/__tests__/session_set_defaults.test.ts

@@ -258,7 +258,58 @@ describe('session-set-defaults tool', () => {
       expect(parsed.sessionDefaults?.simulatorName).toBeUndefined();
     });
 
-    it('should persist into the active named profile when selected', async () => {
+    it('sets defaults on existing named profile and activates it', async () => {
+      sessionStore.setActiveProfile('ios');
+      sessionStore.setDefaults({ scheme: 'OldIOS' });
+      sessionStore.setActiveProfile(null);
+
+      const result = await sessionSetDefaultsLogic(
+        {
+          profile: 'ios',
+          scheme: 'NewIOS',
+          simulatorName: 'iPhone 16',
+        },
+        createContext(),
+      );
+
+      expect(result.isError).toBe(false);
+      expect(result.content[0].text).toContain('Activated profile "ios".');
+      expect(sessionStore.getActiveProfile()).toBe('ios');
+      expect(sessionStore.getAll().scheme).toBe('NewIOS');
+      expect(sessionStore.getAll().simulatorName).toBe('iPhone 16');
+    });
+
+    it('returns error when profile does not exist and createIfNotExists is false', async () => {
+      const result = await sessionSetDefaultsLogic(
+        {
+          profile: 'missing',
+          scheme: 'NewIOS',
+        },
+        createContext(),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('Profile "missing" does not exist');
+      expect(result.content[0].text).toContain('createIfNotExists=true');
+    });
+
+    it('creates profile when createIfNotExists is true and activates it', async () => {
+      const result = await sessionSetDefaultsLogic(
+        {
+          profile: 'ios',
+          createIfNotExists: true,
+          scheme: 'NewIOS',
+        },
+        createContext(),
+      );
+
+      expect(result.isError).toBe(false);
+      expect(result.content[0].text).toContain('Created and activated profile "ios".');
+      expect(sessionStore.getActiveProfile()).toBe('ios');
+      expect(sessionStore.getAll().scheme).toBe('NewIOS');
+    });
+
+    it('persists defaults and active profile when profile is provided', async () => {
       const yaml = [
         'schemaVersion: 1',
         'sessionDefaultsProfiles:',
@@ -268,37 +319,43 @@ describe('session-set-defaults tool', () => {
       ].join('\n');
 
       const writes: { path: string; content: string }[] = [];
+      let persistedYaml = yaml;
       const fs = createMockFileSystemExecutor({
         existsSync: (targetPath: string) => targetPath === configPath,
         readFile: async (targetPath: string) => {
           if (targetPath !== configPath) {
             throw new Error(`Unexpected readFile path: ${targetPath}`);
           }
-          return yaml;
+          return persistedYaml;
         },
         writeFile: async (targetPath: string, content: string) => {
           writes.push({ path: targetPath, content });
+          persistedYaml = content;
         },
       });
 
       await initConfigStore({ cwd, fs });
       sessionStore.setActiveProfile('ios');
+      sessionStore.setActiveProfile(null);
 
       await sessionSetDefaultsLogic(
         {
+          profile: 'ios',
           scheme: 'NewIOS',
           simulatorName: 'iPhone 16',
           persist: true,
         },
         createContext(),
       );
 
-      expect(writes.length).toBe(1);
-      const parsed = parseYaml(writes[0].content) as {
+      expect(writes.length).toBe(2);
+      const parsed = parseYaml(writes[writes.length - 1].content) as {
         sessionDefaultsProfiles?: Record<string, Record<string, unknown>>;
+        activeSessionDefaultsProfile?: string;
       };
       expect(parsed.sessionDefaultsProfiles?.ios?.scheme).toBe('NewIOS');
       expect(parsed.sessionDefaultsProfiles?.ios?.simulatorName).toBe('iPhone 16');
+      expect(parsed.activeSessionDefaultsProfile).toBe('ios');
     });
 
     it('should not persist when persist is true but no defaults were provided', async () => {

src/mcp/tools/session-management/__tests__/session_use_defaults_profile.test.ts

@@ -25,7 +25,10 @@ describe('session-use-defaults-profile tool', () => {
     expect(typeof schema).toBe('object');
   });
 
-  it('activates a named profile', async () => {
+  it('activates an existing named profile', async () => {
+    sessionStore.setActiveProfile('ios');
+    sessionStore.setActiveProfile(null);
+
     const result = await sessionUseDefaultsProfileLogic({ profile: 'ios' });
     expect(result.isError).toBe(false);
     expect(sessionStore.getActiveProfile()).toBe('ios');
@@ -45,12 +48,18 @@ describe('session-use-defaults-profile tool', () => {
     expect(result.content[0].text).toContain('either global=true or profile');
   });
 
-  it('returns error when profile is missing and create=false', async () => {
-    const result = await sessionUseDefaultsProfileLogic({ profile: 'macos', create: false });
+  it('returns error when profile does not exist', async () => {
+    const result = await sessionUseDefaultsProfileLogic({ profile: 'macos' });
     expect(result.isError).toBe(true);
     expect(result.content[0].text).toContain('does not exist');
   });
 
+  it('returns error when profile name is blank after trimming', async () => {
+    const result = await sessionUseDefaultsProfileLogic({ profile: '   ' });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Profile name cannot be empty');
+  });
+
   it('returns status for empty args', async () => {
     const result = await sessionUseDefaultsProfileLogic({});
     expect(result.isError).toBe(false);
@@ -68,6 +77,9 @@ describe('session-use-defaults-profile tool', () => {
     });
     await initConfigStore({ cwd, fs });
 
+    sessionStore.setActiveProfile('ios');
+    sessionStore.setActiveProfile(null);
+
     const result = await sessionUseDefaultsProfileLogic({ profile: 'ios', persist: true });
     expect(result.isError).toBe(false);
     expect(result.content[0].text).toContain('Persisted active profile selection');