fix(xcode-ide): Bound IDE state fallback to workspace root

Limit parent-directory fallback discovery for xcuserstate to a configured
search root instead of traversing to filesystem root.

Pass the resolved workspace root from server bootstrap so Xcode IDE sync
and watcher startup only search within the active workspace context.

Add regression coverage for nested cwd discovery and boundary enforcement.

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

Author: cameroncooke

CHANGELOG.md

@@ -13,6 +13,9 @@
 - Added daemon idle shutdown in CLI mode: per-workspace daemons now auto-exit after 10 minutes of inactivity when no active stateful sessions exist.
 - Inverted idle activity tracking to a generic daemon activity registry so long-running tools report lifecycle activity without hardcoded daemon imports.
 
+### Fixed
+- Fix Xcode IDE state discovery fallback to check parent directories only up to the resolved workspace root boundary when started from a nested working directory without explicit `projectPath`/`workspacePath`.
+
 ## [2.0.0] - 2026-02-02
 
 ### Breaking

src/server/bootstrap.ts

@@ -8,6 +8,7 @@ import { getRegisteredWorkflows, registerWorkflowsFromManifest } from '../utils/
 import { bootstrapRuntime } from '../runtime/bootstrap-runtime.ts';
 import { getXcodeToolsBridgeManager } from '../integrations/xcode-tools-bridge/index.ts';
 import { getMcpBridgeAvailability } from '../integrations/xcode-tools-bridge/core.ts';
+import { resolveWorkspaceRoot } from '../daemon/socket-path.ts';
 import { detectXcodeRuntime } from '../utils/xcode-process.ts';
 import { readXcodeIdeState } from '../utils/xcode-state-reader.ts';
 import { sessionStore } from '../utils/session-store.ts';
@@ -60,6 +61,10 @@ export async function bootstrapServer(
   }
 
   const enabledWorkflows = result.runtime.config.enabledWorkflows;
+  const workspaceRoot = resolveWorkspaceRoot({
+    cwd: result.runtime.cwd,
+    projectConfigPath: result.configPath,
+  });
   const mcpBridge = await getMcpBridgeAvailability();
   const xcodeToolsAvailable = mcpBridge.available;
   log('info', `🚀 Initializing server...`);
@@ -79,6 +84,7 @@ export async function bootstrapServer(
     const xcodeState = await readXcodeIdeState({
       executor,
       cwd: result.runtime.cwd,
+      searchRoot: workspaceRoot,
       projectPath,
       workspacePath,
     });
@@ -125,6 +131,7 @@ export async function bootstrapServer(
       const watcherStarted = await startXcodeStateWatcher({
         executor,
         cwd: result.runtime.cwd,
+        searchRoot: workspaceRoot,
         projectPath,
         workspacePath,
       });

src/utils/__tests__/xcode-state-reader.test.ts

@@ -78,6 +78,41 @@ describe('findXcodeStateFile', () => {
     expect(result).toBeUndefined();
   });
 
+  it('finds project in parent directory when cwd is nested within searchRoot', async () => {
+    const executor = createCommandMatchingMockExecutor({
+      whoami: { output: 'testuser\n' },
+      'find /test/project/subdir -maxdepth 6': { output: '' },
+      'find /test/project -maxdepth 1': { output: '/test/project/MyApp.xcodeproj\n' },
+      stat: { output: '1704067200\n' },
+    });
+
+    const result = await findXcodeStateFile({
+      executor,
+      cwd: '/test/project/subdir',
+      searchRoot: '/test/project',
+    });
+
+    expect(result).toBe(
+      '/test/project/MyApp.xcodeproj/project.xcworkspace/xcuserdata/testuser.xcuserdatad/UserInterfaceState.xcuserstate',
+    );
+  });
+
+  it('does not search above searchRoot boundary', async () => {
+    const executor = createCommandMatchingMockExecutor({
+      whoami: { output: 'testuser\n' },
+      'find /test/project/subdir -maxdepth 6': { output: '' },
+      'find /test/project -maxdepth 1': { output: '' },
+    });
+
+    const result = await findXcodeStateFile({
+      executor,
+      cwd: '/test/project/subdir',
+      searchRoot: '/test/project',
+    });
+
+    expect(result).toBeUndefined();
+  });
+
   it('uses configured workspacePath directly', async () => {
     const executor = createCommandMatchingMockExecutor({
       whoami: { output: 'testuser\n' },

src/utils/xcode-state-reader.ts

@@ -8,6 +8,7 @@
  * running under Xcode's coding agent.
  */
 
+import { dirname, resolve, sep } from 'node:path';
 import { log } from './logger.ts';
 import { parseXcuserstate } from './nskeyedarchiver-parser.ts';
 import type { CommandExecutor } from './execution/index.ts';
@@ -22,6 +23,8 @@ export interface XcodeStateResult {
 export interface XcodeStateReaderContext {
   executor: CommandExecutor;
   cwd: string;
+  /** Optional boundary for parent-directory fallback search (typically workspace root) */
+  searchRoot?: string;
   /** Optional pre-configured workspace path to use directly */
   workspacePath?: string;
   /** Optional pre-configured project path to use directly */
@@ -33,16 +36,79 @@ export interface XcodeStateReaderContext {
  *
  * Search order:
  * 1. Use configured workspacePath/projectPath if provided
- * 2. Search for .xcworkspace/.xcodeproj in cwd and parent directories
+ * 2. Search for .xcworkspace/.xcodeproj under cwd
+ * 3. If none (or to broaden candidates), search direct children of parent directories
+ *    up to searchRoot (workspace boundary)
  *
  * For each found project:
  * - .xcworkspace: <workspace>/xcuserdata/<user>.xcuserdatad/UserInterfaceState.xcuserstate
  * - .xcodeproj: <project>/project.xcworkspace/xcuserdata/<user>.xcuserdatad/UserInterfaceState.xcuserstate
  */
+function buildFindProjectsCommand(root: string, maxDepth: number): string[] {
+  return [
+    'find',
+    root,
+    '-maxdepth',
+    String(maxDepth),
+    '(',
+    '-name',
+    '*.xcworkspace',
+    '-o',
+    '-name',
+    '*.xcodeproj',
+    ')',
+    '-type',
+    'd',
+  ];
+}
+
+function isPathWithinBoundary(path: string, boundary: string): boolean {
+  return path === boundary || path.startsWith(`${boundary}${sep}`);
+}
+
+function listParentDirectories(startPath: string, boundaryPath: string): string[] {
+  const parents: string[] = [];
+  const start = resolve(startPath);
+  const boundary = resolve(boundaryPath);
+
+  if (!isPathWithinBoundary(start, boundary)) {
+    return parents;
+  }
+
+  let current = start;
+  while (true) {
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+
+    if (!isPathWithinBoundary(parent, boundary)) {
+      break;
+    }
+
+    parents.push(parent);
+    if (parent === boundary) {
+      break;
+    }
+
+    current = parent;
+  }
+
+  return parents;
+}
+
+function collectFindPaths(output: string): string[] {
+  return output
+    .trim()
+    .split('\n')
+    .map((path) => path.trim())
+    .filter(Boolean);
+}
+
 export async function findXcodeStateFile(
   ctx: XcodeStateReaderContext,
 ): Promise<string | undefined> {
-  const { executor, cwd, workspacePath, projectPath } = ctx;
+  const { executor, cwd, searchRoot, workspacePath, projectPath } = ctx;
 
   // Get current username
   const userResult = await executor(['whoami'], 'Get username', false);
@@ -68,33 +134,47 @@ export async function findXcodeStateFile(
     log('debug', `[xcode-state] Configured path xcuserstate not found: ${xcuserstatePath}`);
   }
 
-  // Search for projects with increased depth (projects can be nested deeper)
-  const findResult = await executor(
-    [
-      'find',
-      cwd,
-      '-maxdepth',
-      '6',
-      '(',
-      '-name',
-      '*.xcworkspace',
-      '-o',
-      '-name',
-      '*.xcodeproj',
-      ')',
-      '-type',
-      'd',
-    ],
-    'Find Xcode project/workspace',
+  const discoveredPaths = new Set<string>();
+
+  // Search descendants from cwd with increased depth (projects can be nested deeper).
+  const descendantsResult = await executor(
+    buildFindProjectsCommand(cwd, 6),
+    'Find Xcode project/workspace in cwd descendants',
     false,
   );
+  if (descendantsResult.success && descendantsResult.output.trim()) {
+    for (const path of collectFindPaths(descendantsResult.output)) {
+      discoveredPaths.add(path);
+    }
+  }
 
-  if (!findResult.success || !findResult.output.trim()) {
-    log('debug', `[xcode-state] No Xcode project/workspace found in ${cwd}`);
+  // Also search direct children of parent directories to support nested cwd usage.
+  // Example: cwd=/repo/feature/subdir, project=/repo/App.xcodeproj
+  // Parent traversal stops at searchRoot (workspace boundary).
+  const parentSearchBoundary = searchRoot ?? cwd;
+  for (const parentDir of listParentDirectories(cwd, parentSearchBoundary)) {
+    const parentResult = await executor(
+      buildFindProjectsCommand(parentDir, 1),
+      'Find Xcode project/workspace in parent directory',
+      false,
+    );
+    if (!parentResult.success || !parentResult.output.trim()) {
+      continue;
+    }
+    for (const path of collectFindPaths(parentResult.output)) {
+      discoveredPaths.add(path);
+    }
+  }
+
+  if (discoveredPaths.size === 0) {
+    log(
+      'debug',
+      `[xcode-state] No Xcode project/workspace found in ${cwd} (boundary: ${parentSearchBoundary})`,
+    );
     return undefined;
   }
 
-  const paths = findResult.output.trim().split('\n').filter(Boolean);
+  const paths = [...discoveredPaths];
 
   // Filter out nested workspaces inside xcodeproj and sort
   const filteredPaths = paths

src/utils/xcode-state-watcher.ts

@@ -179,6 +179,7 @@ async function processFileChange(): Promise<void> {
 export interface StartWatcherOptions {
   executor?: CommandExecutor;
   cwd?: string;
+  searchRoot?: string;
   workspacePath?: string;
   projectPath?: string;
 }
@@ -198,6 +199,7 @@ export async function startXcodeStateWatcher(options: StartWatcherOptions = {}):
   const xcuserstatePath = await findXcodeStateFile({
     executor,
     cwd,
+    searchRoot: options.searchRoot,
     workspacePath: options.workspacePath,
     projectPath: options.projectPath,
   });