Fix UTF-8 encoding in ExecaTerminalProcess

[mr-ryan-james]

Problem

I discovered an Encoding::CompatibilityError when running commands like pod install (CocoaPods/Ruby) within Roo Code's integrated terminal when the "Disable terminal shell integration" setting is enabled. The root cause was identified as the ExecaTerminalProcess not being configured with UTF-8 encoding, leading to character encoding compatibility issues in Ruby scripts.

The error message specifically suggested setting export LANG=en_US.UTF-8.

Root Cause Analysis

When users enable the "Disable terminal shell integration" setting, Roo Code switches from VSCode's built-in terminal to the ExecaTerminal implementation. This fallback path uses Node.js execa library via ExecaTerminalProcess, which was not inheriting proper UTF-8 locale settings.

Code Path When "Disable Terminal Shell Integration" is Enabled:

1. executeCommandTool.ts:149 → provider = "execa"
2. TerminalRegistry.ts:133 → new ExecaTerminal()
3. ExecaTerminal.ts:21 → new ExecaTerminalProcess()
4. ExecaTerminalProcess.ts → 🎯 Where UTF-8 fix is applied

Solution

This PR resolves the UTF-8 encoding issue by ensuring the ExecaTerminalProcess sets proper UTF-8 locale environment variables when creating subprocesses.

Changes Made:

Updated ExecaTerminalProcess Environment Configuration (src/integrations/terminal/ExecaTerminalProcess.ts):

• Added LANG: "en_US.UTF-8" to the subprocess environment variables
• Added LC_ALL: "en_US.UTF-8" to the subprocess environment variables
• This ensures consistent UTF-8 encoding for all commands executed through the ExecaTerminal path

Scope and Impact

✅ What this fixes:

• UTF-8 encoding issues for users with "Disable terminal shell integration" enabled
• Ruby/CocoaPods commands that fail due to encoding compatibility
• Locale-related command execution problems in the ExecaTerminal fallback path

✅ What this doesn't affect:

• Default VSCode terminal behavior (shell integration enabled)
• Users who use the default terminal settings
• VSCode's built-in terminal API and shell integration features

Testing

The fix has been tested and resolves the Encoding::CompatibilityError that was preventing Ruby/CocoaPods commands from executing successfully when the "Disable terminal shell integration" setting is enabled.

Alignment with Project Goals

This change aligns with the Reliability First roadmap goal by:

• Ensuring command execution is consistently reliable across different terminal configurations
• Guaranteeing smooth operation across different locale configurations
• Reducing friction points for users who utilize the ExecaTerminal implementation

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Technical Details

This fix specifically targets the ExecaTerminal code path which is only used when:

1. User has the "Disable terminal shell integration" setting enabled
2. Roo Code uses Node.js execa instead of VSCode terminal API
3. Commands are executed through ExecaTerminalProcess subprocess creation

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• My changes generate no new warnings
• My changes are targeted to the specific ExecaTerminal implementation
• My changes align with the project roadmap

Fixes #4033

[daniel-lxs]

Hey @mr-ryan-james, this makes sense, I'll try to repro the issue and see if this is a correct fix.

[daniel-lxs]

Hey @mr-ryan-james. Just tested this and can confirm the fix works as intended.

I created a test script that simulates the encoding issue, without the UTF-8 env vars, Ruby defaults to US-ASCII which would break CocoaPods. With your fix setting LANG/LC_ALL to en_US.UTF-8, everything works.

I think it might be worth adding a unit test for this. I noticed ExecaTerminalProcess doesn't have test coverage yet. Could help catch any future regressions. What do you think?

[mr-ryan-james]

Hey @mr-ryan-james. Just tested this and can confirm the fix works as intended.

I created a test script that simulates the encoding issue, without the UTF-8 env vars, Ruby defaults to US-ASCII which would break CocoaPods. With your fix setting LANG/LC_ALL to en_US.UTF-8, everything works.

I think it might be worth adding a unit test for this. I noticed ExecaTerminalProcess doesn't have test coverage yet. Could help catch any future regressions. What do you think?

Thanks for taking the time to test thsi! I will start iterating a bit on tesing my functionality.

[daniel-lxs]

Hey @mr-ryan-james, Thanks for adding the tests so quickly!

Everything looks good to me now.