uloop-cli 1.6.4 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "1.6.4",
+  "version": "1.7.2",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via Unity CLI Loop",
   "main": "dist/cli.bundle.cjs",
@@ -49,19 +49,19 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/jest": "30.0.0",
-    "@types/node": "25.5.0",
+    "@types/node": "25.5.2",
     "@types/semver": "7.7.1",
     "esbuild": "0.28.0",
-    "eslint": "10.1.0",
+    "eslint": "10.2.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-security": "4.0.0",
     "jest": "30.3.0",
-    "knip": "6.3.0",
+    "knip": "6.3.1",
     "prettier": "3.8.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.58.0"
+    "typescript-eslint": "8.58.1"
   },
   "overrides": {
     "minimatch": "10.2.4"

package/src/__tests__/busy-state-order.test.ts

@@ -0,0 +1,120 @@
+const mockResolveUnityPort = jest.fn<Promise<number>, [number | undefined, string | undefined]>();
+const mockValidateProjectPath = jest.fn<string, [string]>();
+const mockFindUnityProjectRoot = jest.fn<string | null, []>();
+const mockExistsSync = jest.fn<boolean, [string]>();
+
+jest.mock('../port-resolver.js', () => ({
+  resolveUnityPort: (explicitPort?: number, projectPath?: string): Promise<number> =>
+    mockResolveUnityPort(explicitPort, projectPath),
+  validateProjectPath: (projectPath: string): string => mockValidateProjectPath(projectPath),
+}));
+
+jest.mock('../project-root.js', () => ({
+  findUnityProjectRoot: (): string | null => mockFindUnityProjectRoot(),
+}));
+
+jest.mock('fs', () => ({
+  existsSync: (path: string): boolean => mockExistsSync(path),
+}));
+
+import { executeToolCommand, listAvailableTools, syncTools } from '../execute-tool.js';
+
+describe('busy state detection order', () => {
+  beforeEach(() => {
+    mockResolveUnityPort.mockReset();
+    mockResolveUnityPort.mockRejectedValue(new Error('RESOLVE_CALLED_BEFORE_BUSY_CHECK'));
+
+    mockValidateProjectPath.mockReset();
+    mockValidateProjectPath.mockReturnValue('/project');
+
+    mockFindUnityProjectRoot.mockReset();
+    mockFindUnityProjectRoot.mockReturnValue('/project');
+
+    mockExistsSync.mockReset();
+    mockExistsSync.mockImplementation((path: string) => path.endsWith('serverstarting.lock'));
+  });
+
+  it('checks busy state before resolving port for tool execution', async () => {
+    await expect(executeToolCommand('get-logs', {}, { projectPath: '/project' })).rejects.toThrow(
+      'UNITY_SERVER_STARTING',
+    );
+
+    expect(mockResolveUnityPort).not.toHaveBeenCalled();
+  });
+
+  it('checks busy state before resolving port for list', async () => {
+    await expect(listAvailableTools({ projectPath: '/project' })).rejects.toThrow(
+      'UNITY_SERVER_STARTING',
+    );
+
+    expect(mockResolveUnityPort).not.toHaveBeenCalled();
+  });
+
+  it('checks busy state before resolving port for sync', async () => {
+    await expect(syncTools({ projectPath: '/project' })).rejects.toThrow('UNITY_SERVER_STARTING');
+
+    expect(mockResolveUnityPort).not.toHaveBeenCalled();
+  });
+
+  it('skips busy state checks when an explicit port is provided for tool execution', async () => {
+    mockResolveUnityPort.mockRejectedValue(new Error('EXPLICIT_PORT_RESOLVED'));
+
+    await expect(executeToolCommand('get-logs', {}, { port: '8711' })).rejects.toThrow(
+      'EXPLICIT_PORT_RESOLVED',
+    );
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, undefined);
+  });
+
+  it('preserves usage errors before busy state checks for tool execution', async () => {
+    mockResolveUnityPort.mockRejectedValue(
+      new Error('Cannot specify both --port and --project-path. Use one or the other.'),
+    );
+
+    await expect(
+      executeToolCommand('get-logs', {}, { port: '8711', projectPath: '/project' }),
+    ).rejects.toThrow('Cannot specify both --port and --project-path. Use one or the other.');
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, '/project');
+  });
+
+  it('skips busy state checks when an explicit port is provided for list', async () => {
+    mockResolveUnityPort.mockRejectedValue(new Error('EXPLICIT_PORT_RESOLVED'));
+
+    await expect(listAvailableTools({ port: '8711' })).rejects.toThrow('EXPLICIT_PORT_RESOLVED');
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, undefined);
+  });
+
+  it('preserves usage errors before busy state checks for list', async () => {
+    mockResolveUnityPort.mockRejectedValue(
+      new Error('Cannot specify both --port and --project-path. Use one or the other.'),
+    );
+
+    await expect(listAvailableTools({ port: '8711', projectPath: '/project' })).rejects.toThrow(
+      'Cannot specify both --port and --project-path. Use one or the other.',
+    );
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, '/project');
+  });
+
+  it('skips busy state checks when an explicit port is provided for sync', async () => {
+    mockResolveUnityPort.mockRejectedValue(new Error('EXPLICIT_PORT_RESOLVED'));
+
+    await expect(syncTools({ port: '8711' })).rejects.toThrow('EXPLICIT_PORT_RESOLVED');
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, undefined);
+  });
+
+  it('preserves usage errors before busy state checks for sync', async () => {
+    mockResolveUnityPort.mockRejectedValue(
+      new Error('Cannot specify both --port and --project-path. Use one or the other.'),
+    );
+
+    await expect(syncTools({ port: '8711', projectPath: '/project' })).rejects.toThrow(
+      'Cannot specify both --port and --project-path. Use one or the other.',
+    );
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, '/project');
+  });
+});

package/src/__tests__/cli-project-error.test.ts

@@ -0,0 +1,33 @@
+import { getProjectResolutionErrorLines } from '../cli-project-error.js';
+import { UnityNotRunningError } from '../port-resolver.js';
+import { ProjectMismatchError } from '../project-validator.js';
+
+describe('getProjectResolutionErrorLines', () => {
+  it('returns not-running guidance for UnityNotRunningError', () => {
+    const lines = getProjectResolutionErrorLines(new UnityNotRunningError('/project/root'));
+
+    expect(lines).toEqual([
+      'Error: Unity Editor for this project is not running.',
+      '',
+      '  Project: /project/root',
+      '',
+      'Start the Unity Editor for this project and try again.',
+    ]);
+  });
+
+  it('returns mismatch guidance for ProjectMismatchError', () => {
+    const lines = getProjectResolutionErrorLines(
+      new ProjectMismatchError('/expected/project', '/connected/project'),
+    );
+
+    expect(lines).toEqual([
+      'Error: Connected Unity instance belongs to a different project.',
+      '',
+      '  Project:      /expected/project',
+      '  Connected to: /connected/project',
+      '',
+      'Another Unity instance was found, but it belongs to a different project.',
+      'Start the Unity Editor for this project, or use --project-path to specify the target.',
+    ]);
+  });
+});

package/src/__tests__/cli-update.test.ts

@@ -0,0 +1,129 @@
+type SpawnArgs = [string, string[], Record<string, unknown>?];
+
+const mockSpawn = jest.fn<unknown, SpawnArgs>();
+
+jest.mock('child_process', () => ({
+  spawn: (...args: SpawnArgs): unknown => mockSpawn(...args),
+}));
+
+jest.mock(
+  'launch-unity',
+  () => ({
+    orchestrateLaunch: jest.fn(),
+  }),
+  { virtual: true },
+);
+
+import { getInstalledVersion, updateCli } from '../cli.js';
+
+type CloseHandler = (code: number | null) => void;
+type ErrorHandler = (error: Error) => void;
+type DataHandler = (chunk: Buffer) => void;
+
+interface MockChildProcess {
+  stdout: {
+    on: jest.Mock<void, [string, DataHandler]>;
+  };
+  on: jest.Mock<void, [string, CloseHandler | ErrorHandler]>;
+  emitStdout: (chunk: string) => void;
+  emitClose: (code: number | null) => void;
+  emitError: (error: Error) => void;
+}
+
+function createMockChildProcess(): MockChildProcess {
+  let closeHandler: CloseHandler | undefined;
+  let errorHandler: ErrorHandler | undefined;
+  let dataHandler: DataHandler | undefined;
+
+  return {
+    stdout: {
+      on: jest.fn((event: string, handler: DataHandler) => {
+        if (event === 'data') {
+          dataHandler = handler;
+        }
+      }),
+    },
+    on: jest.fn((event: string, handler: CloseHandler | ErrorHandler) => {
+      if (event === 'close') {
+        closeHandler = handler as CloseHandler;
+      }
+
+      if (event === 'error') {
+        errorHandler = handler as ErrorHandler;
+      }
+    }),
+    emitStdout: (chunk: string): void => {
+      dataHandler?.(Buffer.from(chunk));
+    },
+    emitClose: (code: number | null): void => {
+      closeHandler?.(code);
+    },
+    emitError: (error: Error): void => {
+      errorHandler?.(error);
+    },
+  };
+}
+
+describe('CLI update npm invocation', () => {
+  const expectedNpmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+  beforeEach(() => {
+    mockSpawn.mockReset();
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('gets installed version without enabling shell mode', () => {
+    const child = createMockChildProcess();
+    const callback = jest.fn();
+    mockSpawn.mockReturnValue(child);
+
+    getInstalledVersion(callback);
+
+    expect(mockSpawn).toHaveBeenCalledWith(expectedNpmCommand, [
+      'list',
+      '-g',
+      'uloop-cli',
+      '--json',
+    ]);
+    expect(mockSpawn.mock.calls[0]).toHaveLength(2);
+
+    child.emitStdout(JSON.stringify({ dependencies: { 'uloop-cli': { version: '1.8.0' } } }));
+    child.emitClose(0);
+
+    expect(callback).toHaveBeenCalledWith('1.8.0');
+  });
+
+  it('updates the CLI without enabling shell mode', () => {
+    const updateChild = createMockChildProcess();
+    const listChild = createMockChildProcess();
+    mockSpawn.mockReturnValueOnce(updateChild).mockReturnValueOnce(listChild);
+
+    updateCli();
+
+    expect(mockSpawn).toHaveBeenNthCalledWith(
+      1,
+      expectedNpmCommand,
+      ['install', '-g', 'uloop-cli@latest'],
+      { stdio: 'inherit' },
+    );
+    const installOptions = mockSpawn.mock.calls[0]?.[2];
+    expect(installOptions?.['shell']).toBeUndefined();
+
+    updateChild.emitClose(0);
+
+    expect(mockSpawn).toHaveBeenNthCalledWith(2, expectedNpmCommand, [
+      'list',
+      '-g',
+      'uloop-cli',
+      '--json',
+    ]);
+    expect(mockSpawn.mock.calls[1]).toHaveLength(2);
+
+    listChild.emitStdout(JSON.stringify({ dependencies: { 'uloop-cli': { version: '1.7.1' } } }));
+    listChild.emitClose(0);
+  });
+});

package/src/__tests__/port-resolver.test.ts

@@ -142,4 +142,49 @@ describe('resolveUnityPort with project settings', () => {
       'Could not read Unity server port from settings',
     );
   });
+
+  it('returns port when primary settings file is missing but backup exists', async () => {
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json.bak'),
+      JSON.stringify({ isServerRunning: true, customPort: 8722 }),
+    );
+
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8722);
+  });
+
+  it('returns port when primary settings file is missing but temp exists', async () => {
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json.tmp'),
+      JSON.stringify({ isServerRunning: true, customPort: 8723 }),
+    );
+
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8723);
+  });
+
+  it('returns port from temp when both temp and backup exist', async () => {
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json.tmp'),
+      JSON.stringify({ isServerRunning: true, customPort: 8724 }),
+    );
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json.bak'),
+      JSON.stringify({ isServerRunning: true, customPort: 8725 }),
+    );
+
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8724);
+  });
+
+  it('falls back to temp when primary settings file contains invalid JSON', async () => {
+    writeFileSync(join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json'), 'not valid json{{{');
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json.tmp'),
+      JSON.stringify({ isServerRunning: true, customPort: 8726 }),
+    );
+
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8726);
+  });
 });

package/src/__tests__/project-root.test.ts

@@ -4,7 +4,11 @@
 import { mkdirSync, writeFileSync, rmSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
-import { findUnityProjectRoot, resetMultipleProjectsWarning } from '../project-root.js';
+import {
+  findUnityProjectRoot,
+  hasUloopInstalled,
+  resetMultipleProjectsWarning,
+} from '../project-root.js';
 
 function createUnityProject(basePath: string, name: string): string {
   const projectPath = join(basePath, name);
@@ -95,3 +99,33 @@ describe('findUnityProjectRoot', () => {
     expect(result).toBe(join(testDir, 'Alpha'));
   });
 });
+
+describe('hasUloopInstalled', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(
+      tmpdir(),
+      `uloop-installed-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(join(testDir, 'Assets'), { recursive: true });
+    mkdirSync(join(testDir, 'ProjectSettings'), { recursive: true });
+    mkdirSync(join(testDir, 'UserSettings'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('returns true when only backup settings file exists', () => {
+    writeFileSync(join(testDir, 'UserSettings/UnityMcpSettings.json.bak'), '{}');
+
+    expect(hasUloopInstalled(testDir)).toBe(true);
+  });
+
+  it('returns true when only temp settings file exists', () => {
+    writeFileSync(join(testDir, 'UserSettings/UnityMcpSettings.json.tmp'), '{}');
+
+    expect(hasUloopInstalled(testDir)).toBe(true);
+  });
+});

package/src/cli-project-error.ts

@@ -0,0 +1,26 @@
+import { UnityNotRunningError } from './port-resolver.js';
+import { ProjectMismatchError } from './project-validator.js';
+
+export function getProjectResolutionErrorLines(
+  error: UnityNotRunningError | ProjectMismatchError,
+): string[] {
+  if (error instanceof UnityNotRunningError) {
+    return [
+      'Error: Unity Editor for this project is not running.',
+      '',
+      `  Project: ${error.projectRoot}`,
+      '',
+      'Start the Unity Editor for this project and try again.',
+    ];
+  }
+
+  return [
+    'Error: Connected Unity instance belongs to a different project.',
+    '',
+    `  Project:      ${error.expectedProjectRoot}`,
+    `  Connected to: ${error.connectedProjectRoot}`,
+    '',
+    'Another Unity instance was found, but it belongs to a different project.',
+    'Start the Unity Editor for this project, or use --project-path to specify the target.',
+  ];
+}

package/src/cli.ts

@@ -39,6 +39,7 @@ import { findUnityProjectRoot } from './project-root.js';
 import { validateProjectPath, UnityNotRunningError } from './port-resolver.js';
 import { ProjectMismatchError } from './project-validator.js';
 import { filterEnabledTools, isToolEnabled } from './tool-settings-loader.js';
+import { getProjectResolutionErrorLines } from './cli-project-error.js';
 
 interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
@@ -430,24 +431,16 @@ async function runWithErrorHandling(fn: () => Promise<void>): Promise<void> {
     await fn();
   } catch (error) {
     if (error instanceof UnityNotRunningError) {
-      console.error('\x1b[31mError: Unity Editor for this project is not running.\x1b[0m');
-      console.error('');
-      console.error(`  Project: ${error.projectRoot}`);
-      console.error('');
-      console.error('Start the Unity Editor for this project and try again.');
+      for (const line of getProjectResolutionErrorLines(error)) {
+        console.error(line.startsWith('Error: ') ? `\x1b[31m${line}\x1b[0m` : line);
+      }
       process.exit(1);
     }
 
     if (error instanceof ProjectMismatchError) {
-      console.error('\x1b[31mError: Unity Editor for this project is not running.\x1b[0m');
-      console.error('');
-      console.error(`  Project:      ${error.expectedProjectRoot}`);
-      console.error(`  Connected to: ${error.connectedProjectRoot}`);
-      console.error('');
-      console.error('Another Unity instance was found, but it belongs to a different project.');
-      console.error(
-        'Start the Unity Editor for this project, or use --project-path to specify the target.',
-      );
+      for (const line of getProjectResolutionErrorLines(error)) {
+        console.error(line.startsWith('Error: ') ? `\x1b[31m${line}\x1b[0m` : line);
+      }
       process.exit(1);
     }
 
@@ -604,11 +597,9 @@ compdef _uloop uloop`;
 /**
  * Get the currently installed version of uloop-cli from npm.
  */
-function getInstalledVersion(callback: (version: string | null) => void): void {
+export function getInstalledVersion(callback: (version: string | null) => void): void {
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const child = spawn(npmCommand, ['list', '-g', 'uloop-cli', '--json'], {
-    shell: true,
-  });
+  const child = spawn(npmCommand, ['list', '-g', 'uloop-cli', '--json']);
 
   let stdout = '';
   child.stdout.on('data', (data: Buffer) => {
@@ -663,14 +654,13 @@ function getInstalledVersion(callback: (version: string | null) => void): void {
 /**
  * Update uloop CLI to the latest version using npm.
  */
-function updateCli(): void {
+export function updateCli(): void {
   const previousVersion = VERSION;
   console.log('Updating uloop-cli to the latest version...');
 
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
   const child = spawn(npmCommand, ['install', '-g', 'uloop-cli@latest'], {
     stdio: 'inherit',
-    shell: true,
   });
 
   child.on('close', (code) => {
@@ -1039,4 +1029,6 @@ async function main(): Promise<void> {
   program.parse();
 }
 
-void main();
+if (process.env.JEST_WORKER_ID === undefined) {
+  void main();
+}

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.6.4",
+  "version": "1.7.2",
   "tools": [
     {
       "name": "compile",

package/src/execute-tool.ts

@@ -188,6 +188,14 @@ function checkUnityBusyState(projectPath?: string): void {
   }
 }
 
+function checkUnityBusyStateBeforeProjectResolution(globalOptions: GlobalOptions): void {
+  if (globalOptions.port !== undefined) {
+    return;
+  }
+
+  checkUnityBusyState(globalOptions.projectPath);
+}
+
 export async function executeToolCommand(
   toolName: string,
   params: Record<string, unknown>,
@@ -201,6 +209,7 @@ export async function executeToolCommand(
     }
     portNumber = parsed;
   }
+  checkUnityBusyStateBeforeProjectResolution(globalOptions);
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const compileOptions = getCompileExecutionOptions(toolName, params);
   const shouldWaitForDomainReload = compileOptions.waitForDomainReload;
@@ -228,7 +237,7 @@ export async function executeToolCommand(
   let requestDispatched = false;
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState(globalOptions.projectPath);
+    checkUnityBusyStateBeforeProjectResolution(globalOptions);
 
     const client = new DirectUnityClient(port);
     try {
@@ -391,6 +400,7 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
     }
     portNumber = parsed;
   }
+  checkUnityBusyStateBeforeProjectResolution(globalOptions);
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const projectRoot =
     globalOptions.projectPath !== undefined
@@ -403,7 +413,7 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState(globalOptions.projectPath);
+    checkUnityBusyStateBeforeProjectResolution(globalOptions);
 
     const client = new DirectUnityClient(port);
     try {
@@ -488,6 +498,7 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
     }
     portNumber = parsed;
   }
+  checkUnityBusyStateBeforeProjectResolution(globalOptions);
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const projectRoot =
     globalOptions.projectPath !== undefined
@@ -500,7 +511,7 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState(globalOptions.projectPath);
+    checkUnityBusyStateBeforeProjectResolution(globalOptions);
 
     const client = new DirectUnityClient(port);
     try {

package/src/port-resolver.ts

@@ -10,7 +10,12 @@ import { PRODUCT_DISPLAY_NAME } from './cli-constants';
 import { readFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join, resolve } from 'path';
-import { findUnityProjectRoot, isUnityProject, hasUloopInstalled } from './project-root.js';
+import {
+  findUnityProjectRoot,
+  getUnitySettingsCandidatePaths,
+  isUnityProject,
+  hasUloopInstalled,
+} from './project-root.js';
 
 export class UnityNotRunningError extends Error {
   constructor(public readonly projectRoot: string) {
@@ -105,41 +110,37 @@ function createSettingsReadError(projectRoot: string): Error {
 
 // File I/O and JSON parsing can fail for external reasons (permissions, corruption, concurrent writes)
 async function readPortFromSettingsOrThrow(projectRoot: string): Promise<number> {
-  const settingsPath = join(projectRoot, 'UserSettings/UnityMcpSettings.json');
-
-  if (!existsSync(settingsPath)) {
-    throw createSettingsReadError(projectRoot);
-  }
-
-  let content: string;
-  try {
-    content = await readFile(settingsPath, 'utf-8');
-  } catch {
-    throw createSettingsReadError(projectRoot);
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    throw createSettingsReadError(projectRoot);
-  }
-
-  if (typeof parsed !== 'object' || parsed === null) {
-    throw createSettingsReadError(projectRoot);
-  }
-  const settings = parsed as UnityMcpSettings;
-
-  // Only block when isServerRunning is explicitly false (Unity clean shutdown).
-  // undefined/missing means old settings format — proceed to next validation stage.
-  if (settings.isServerRunning === false) {
-    throw new UnityNotRunningError(projectRoot);
-  }
-
-  const port = resolvePortFromUnitySettings(settings);
-  if (port === null) {
-    throw createSettingsReadError(projectRoot);
-  }
-
-  return port;
+  for (const settingsPath of getUnitySettingsCandidatePaths(projectRoot)) {
+    let content: string;
+    try {
+      content = await readFile(settingsPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      continue;
+    }
+
+    if (typeof parsed !== 'object' || parsed === null) {
+      continue;
+    }
+    const settings = parsed as UnityMcpSettings;
+
+    // Only block when isServerRunning is explicitly false (Unity clean shutdown).
+    // undefined/missing means old settings format — proceed to next validation stage.
+    if (settings.isServerRunning === false) {
+      throw new UnityNotRunningError(projectRoot);
+    }
+
+    const port = resolvePortFromUnitySettings(settings);
+    if (port !== null) {
+      return port;
+    }
+  }
+
+  throw createSettingsReadError(projectRoot);
 }