fix(core,cli,docs): harden IDE bootstrap, diagnostics, and connect timeout handling

[Sangria-hbm]

Summary

Improve IDE integration reliability by making bootstrap behavior deterministic, improving disconnected diagnostics, and preventing /ide enable from hanging when IDE transport connection never resolves.

Details

• Core IDE bootstrap hardening:
  • Prefer valid discovery-file ideInfo deterministically.
  • Validate file-provided ideInfo shape/blank values and fall back safely to env detection.
  • Lock connection attempt order in tests: file-port -> file-stdio -> env-port -> env-stdio.
  • Normalize failure messages for noWorkspacePath, workspaceNotOpen, workspaceMismatch, connectFailed.
  • Add connect timeout guard for HTTP/stdio (GEMINI_IDE_CONNECT_TIMEOUT_MS, default 10000ms) so hangs become disconnected failures.
• CLI UX hardening:
  • Improve /ide status fallback naming and disconnected diagnostics rendering.
  • Keep IDE command tests type-safe for workspace typecheck.
• Docs alignment:
  • Add Custom IDE Companion quick start.
  • Align IDE companion spec with implemented bootstrap/discovery behavior.

Related Issues

Related to #15538
Historical context: #4800 (closed by #10501)

How to Validate

Automated:

npm run test:ci --workspace @google/gemini-cli-core -- src/ide/detect-ide.test.ts src/ide/ide-connection-utils.test.ts src/ide/ide-client.test.ts
npm run test:ci --workspace @google/gemini-cli -- src/ui/commands/ideCommand.test.ts
npm run typecheck --workspace @google/gemini-cli-core
npm run typecheck --workspace @google/gemini-cli
npx prettier --check docs/ide-integration/index.md docs/ide-integration/ide-companion-spec.md

Expected result:

• All commands above pass without new errors.

Manual:

1. In VS Code integrated terminal, run Gemini CLI from the repository workspace.
2. Run /ide enable, then /ide status.
3. Expected: status is connected and IDE context is shown.
4. Run /ide disable, then /ide enable.
5. Expected: reconnect succeeds.
6. Simulate unavailable/unresponsive companion (for example, disable the VS Code Gemini CLI Companion extension or set an invalid IDE server port), then run /ide enable again.
7. Expected: returns disconnected with actionable message and does not hang indefinitely.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any): none
• Validated on required platforms/methods for this PR scope (Windows):
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, 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 robustness and user experience of the IDE integration by making connection processes more reliable and predictable. It addresses potential hanging issues, improves diagnostic feedback for disconnected states, and standardizes how IDE information is discovered and validated, ultimately leading to a more stable and user-friendly interaction with the Gemini CLI.

Highlights

• Core IDE Bootstrap Hardening: Improved the reliability and determinism of IDE discovery by preferring valid ideInfo from discovery files, validating its structure, and falling back safely to environment detection. A deterministic connection attempt order (file-port -> file-stdio -> env-port -> env-stdio) was established, and failure messages for common connection issues were normalized.
• Connection Timeout Implementation: Added a configurable connect timeout (GEMINI_IDE_CONNECT_TIMEOUT_MS, default 10s) for HTTP/stdio connections to prevent the CLI from hanging indefinitely when an IDE companion is unresponsive, ensuring hangs become disconnected failures.
• CLI UX Enhancements: Enhanced the /ide status command to provide better fallback naming for IDEs and improved rendering of disconnected diagnostics, offering more actionable messages to the user. IDE command tests were also updated for type-safety.
• Documentation Alignment: Updated the IDE integration documentation to include a 'Custom IDE Companion Quick Start' guide and aligned the IDE companion specification with the newly implemented bootstrap and discovery behaviors.

Changelog

• docs/ide-integration/ide-companion-spec.md
  • Updated the 'Last Updated' date to March 15, 2026.
  • Added a compatibility note for stdio-based connection bootstrap.
  • Included a backward compatibility note for legacy discovery filenames.
  • Clarified that ideInfo is optional but recommended in the discovery file, detailing fallback behavior.
  • Added a note on CLI connection attempt order for deterministic behavior.
  • Added an optional suppressNotification field to CloseDiffRequest.
  • Updated the CloseDiffRequest success response to return JSON with content or null.
• docs/ide-integration/index.md
  • Added a new 'Custom IDE Companion Quick Start' section with detailed instructions for building third-party IDE companions.
• packages/cli/src/ui/commands/ideCommand.test.ts
  • Added a test case to verify connected status with a fallback name when the IDE display name is unavailable.
  • Included a test to ensure actionable disconnected details are shown when auto-enable fails after installation.
• packages/cli/src/ui/commands/ideCommand.ts
  • Introduced getIdeDisplayNameForStatus to provide a fallback 'IDE companion' name when the detected IDE display name is undefined.
  • Updated various status messages and command descriptions to use the new fallback display name.
  • Modified the error message for failed auto-enable to include specific connection details if available.
• packages/core/src/ide/detect-ide.test.ts
  • Added tests to ensure ideInfoFromFile fields are trimmed before use.
  • Included tests for falling back to environment detection if ideInfoFromFile fields are blank or malformed.
  • Expanded test cases for falling back to environment detection when ideInfoFromFile is missing or malformed.
• packages/core/src/ide/detect-ide.ts
  • Implemented normalizeIdeInfoFromFile to validate and trim ideInfo objects read from connection files, returning undefined if malformed or blank.
  • Updated detectIde to use the new normalizeIdeInfoFromFile function, ensuring robust ideInfo processing.
• packages/core/src/ide/ide-client.test.ts
  • Added a resetIdeClientSingleton helper for better test isolation.
  • Included tests to verify that valid ideInfo from a file is passed to detectIde and that partial or malformed ideInfo from a file causes a fallback to environment detection.
  • Implemented comprehensive tests for the deterministic connection attempt order, covering file-based and environment-based HTTP/stdio connections.
  • Added a test to confirm that a hanging HTTP connection attempt times out and results in a disconnected status.
• packages/core/src/ide/ide-client.ts
  • Introduced getIdeConnectTimeoutMs to retrieve the connection timeout duration from environment variables or use a default.
  • Added withConnectTimeout utility function to apply a timeout to connection promises.
  • Implemented parseIdeInfoFromConnectionFile to safely extract and validate ideInfo from connection configuration.
  • Updated the IdeClient constructor to use parseIdeInfoFromConnectionFile for ideInfo processing.
  • Modified the disconnected status message to use the new getConnectionFailureMessage utility for standardized diagnostics.
  • Integrated withConnectTimeout into connectViaHttp and connectViaStdio methods to prevent indefinite hangs.
• packages/core/src/ide/ide-connection-utils.test.ts
  • Added tests for the new getConnectionFailureMessage utility, verifying correct messages for various failure reasons.
  • Updated existing validateWorkspacePath tests to use getConnectionFailureMessage for consistent error reporting.
• packages/core/src/ide/ide-connection-utils.ts
  • Defined ConnectionFailureReason enum for standardized connection error types.
  • Created getConnectionFailureMessage function to generate consistent, user-friendly error messages based on predefined reasons and options.
  • Updated validateWorkspacePath to utilize getConnectionFailureMessage for all error scenarios, ensuring uniform diagnostic output.

Activity

• No specific activity (comments, reviews) found in the provided context.

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 hardens the IDE integration by introducing deterministic bootstrap behavior, connection timeouts to prevent hangs, and improved diagnostic messages. The changes span documentation, CLI commands, and core logic, providing a more reliable user experience. My review found one area for improvement in packages/core/src/ide/ide-client.ts where a redundant validation function can be removed to reduce code duplication and simplify the logic.

[gemini-code-assist]

The call to parseIdeInfoFromConnectionFile is redundant. The detectIde function already performs robust validation and normalization on the ideInfo object via normalizeIdeInfoFromFile.

You can simplify this by passing connectionConfig?.ideInfo directly and removing the now-unused parseIdeInfoFromConnectionFile function (lines 77-97).

Suggested change

	client.currentIde = detectIde(
	client.ideProcessInfo,
	connectionConfig?.ideInfo,
	parseIdeInfoFromConnectionFile(connectionConfig),
	);
	client.currentIde = detectIde(
	client.ideProcessInfo,
	connectionConfig?.ideInfo as { name?: unknown; displayName?: unknown },
	);

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!