[ISSUE] CLI Tab is Non-Functional on macOS

[lacerbi]

Summary

The integrated CLI tab feature implemented in #60 is currently not working on macOS in either development or packaged builds. This is detected on startup and the CLI tab won't be visible. (Had the tab been present, it would have shown a blank black screen.) This is a known issue that we have investigated extensively.

Problem Description

When a user attempts to launch the CLI tab on macOS, the backend process that powers the terminal fails to start. The main process logs reveal a posix_spawnp fail error, which indicates that the application is blocked from spawning the required pseudo-terminal (pty) process.

This issue is specific to node-pty, the library used to create interactive terminal sessions. As detailed in docs/guides/cli-macos-failure.md, basic process creation via Node.js's built-in child_process.spawn succeeds, confirming the problem lies with the specialized pty-spawning operation.

Root Cause & Investigation

The failure likely stems from macOS's security model (Hardened Runtime), which requires applications to be explicitly granted special permissions (entitlements) for sensitive operations. Spawning a pseudo-terminal is one such operation.

We have performed a thorough investigation, which included:

1. Verifying and correcting environment PATH variables.
2. Isolating the failure to node-pty specifically.
3. Adding the necessary security entitlement com.apple.security.device.pty to entitlements.mac.plist.
4. Ensuring the entitlements are correctly included in the application bundle via forge.config.js during the packaging process.

Despite applying the documented and correct entitlement, the posix_spawnp fail error persists in the final packaged application. This suggests a deep-seated issue with how node-pty interacts with Electron's lifecycle and the macOS security sandbox that is not resolved by standard configuration.

The ShellService in electron/services/ShellService.ts contains the core logic for spawning the shell, and its diagnostic logs confirm the failure occurs at the this.nodePtyModule.spawn(...) call.

Current Status & Workaround

• Status: The CLI feature is currently unusable on macOS.
• Workaround: There is no workaround at this time. Users on macOS who need a terminal should use an external terminal application.

Due to the persistent nature of this problem, the CLI feature will remain non-functional on macOS until a viable solution or alternative is found. We welcome any insights from the community on this challenging platform-specific issue.