fix(core): robust workspace-based IDE connection discovery

[ehedlund]

Summary

This PR improves the robustness of the IDE connection discovery mechanism in the Gemini CLI. It addresses common connection failures, especially in containerized (DevContainer) and sandboxed environments, by transitioning from a strict PID-based discovery to a PID-agnostic, workspace-matching approach.

Details

The previous implementation relied heavily on accurately traversing the process tree to find the parent IDE's PID. This was brittle because:

1. Process Tree Fragmentation: In environments like VS Code DevContainers or modern Linux/macOS sandboxes, the terminal and the Extension Host often live in different PID namespaces or are separated by utility processes (like ptyhost), breaking the parent-child link.
2. Race Conditions: During startup, the first terminal session often lacks the injected environment variables (GEMINI_CLI_IDE_SERVER_PORT), forcing the CLI to fall back to filesystem discovery which then fails due to the PID mismatch.

Changes:

• PID-Agnostic Fallback: getConnectionConfigFromFile now scans the shared /tmp/gemini/ide/ directory for any Gemini connection file if the specific PID match fails.
• Workspace Matching: Discovered connection files are validated against the current working directory (process.cwd()). This ensures the CLI connects to the correct IDE window even if multiple are open.
• Process Aliveness Check: Added isPidAlive using process.kill(pid, 0) to correctly filter out stale connection files from crashed or previous sessions.
• Refactoring: Moved sorting and aliveness logic into helper functions for better maintainability.
• Improved Logging: Added debug logs to indicate which connection file was selected and why.

Related Issues

Fixes #13627
Fixes #13848
Fixes #15622
Fixes #18420

How to Validate

Manual Verification

The fix was verified locally by simulating the production failure:

1. Hardcoded a fake PID (e.g., 999999) in IdeClient.getInstance() to ensure the strict PID-based discovery would fail.
2. Ran DEBUG=1 gemini /ide status.
3. Confirmed that the CLI successfully fell back to the new workspace-matching logic and connected to the active IDE server.

Automated Tests

Added a new test case in packages/core/src/ide/ide-connection-utils.test.ts:

• should fall back to a different PID if it matches the current workspace: Mocks a scenario where the requested PID has no file, but a different PID file exists for the same workspace.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • Linux
    • npm run

[gemini-code-assist]

Summary of Changes

Hello @ehedlund, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the reliability of the Gemini CLI's IDE connection discovery, particularly in challenging environments like DevContainers and sandboxed systems. By moving away from a brittle PID-dependent method to a more flexible workspace-matching and process-aliveness-aware approach, it resolves common connection failures and ensures a more stable user experience.

Highlights

• PID-Agnostic Connection Discovery: The IDE connection discovery mechanism has been made more robust by transitioning from a strict PID-based approach to a PID-agnostic fallback. If a direct PID match fails, the system now scans all available connection files in the shared /tmp/gemini/ide/ directory.
• Workspace-Based Validation: Discovered connection files are now validated against the current working directory (process.cwd()) to ensure the CLI connects to the correct IDE instance, especially when multiple IDEs are open or in complex environments like DevContainers.
• Process Aliveness Check: A new isPidAlive utility function has been introduced, utilizing process.kill(pid, 0), to filter out stale connection files from crashed or previous IDE sessions, improving reliability.
• Improved Connection File Sorting: Connection files are now sorted to prioritize the one matching the target PID, then by process aliveness, and finally by the newest PID as a heuristic, ensuring the most relevant connection is selected.
• Enhanced Debug Logging: Additional debug logs have been added to provide clearer insights into which connection file is selected and the reasoning behind the selection, aiding in troubleshooting.
• New Test Coverage: A new test case has been added to verify the fallback mechanism, ensuring that the system correctly connects to a different PID if it matches the current workspace when the target PID's file is not found.

Changelog

• packages/core/src/ide/ide-connection-utils.test.ts
  • Added a new test case should fall back to a different PID if it matches the current workspace to validate the new connection discovery logic.
• packages/core/src/ide/ide-connection-utils.ts
  • Introduced IDE_SERVER_FILE_REGEX for consistent parsing of IDE server file names.
  • Modified getConnectionConfigFromFile to initially filter all gemini-ide-server files, rather than strictly by the target PID.
  • Implemented sortConnectionFiles function to prioritize connection files based on target PID, process aliveness, and PID value.
  • Added isPidAlive helper function to check if a process is still running, filtering out stale connection files.
  • Integrated debug logging to output the selected IDE connection file and the reason for its selection.

Activity

• The author manually verified the fix by simulating production failures, hardcoding a fake PID, and confirming successful fallback to the new workspace-matching logic.
• Automated tests were added, specifically a new test case in ide-connection-utils.test.ts to cover the fallback scenario.
• The changes have been validated on Linux platforms using npm run.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the robustness of IDE connection discovery by shifting from a strict PID-based method to a more flexible workspace-matching approach. This is a valuable change, especially for containerized and sandboxed development environments. My review highlights two critical areas for improvement to ensure the solution is fully robust. Firstly, the implementation for checking process aliveness on Windows is currently a no-op, which can lead to connection failures on that platform. Secondly, the new, more complex file sorting logic lacks sufficient automated tests to guarantee its correctness across different scenarios. Addressing these points will solidify the reliability of this new feature.

[skeshive]

Can you please test on both windows & mac? I usually disable / re-enable the extension and then run CLI in an existing terminal to confirm the port file is being used (instead of falling back on stale env vars)

[ehedlund]

@skeshive confirmed it's WAI on Mac, but I don't have a Windows machine to test on