fix: resolve lifecycle memory leaks by cleaning up listeners and root closures

[spencer426]

Summary

This PR addresses multiple severe memory leaks that cause the CLI's memory usage to continually grow over long sessions, leading to terminal backbuffer retention and massive React Fiber tree bloat.

Details

1. TerminalBuffer & Render Teardown Leaks (cleanupFunctions): registerCleanup was being used in both interactiveCli.tsx and AppContainer.tsx to register instance.unmount() and background task termination logic. Because the application was missing a corresponding removeCleanup hook, these closures (and by extension the entire rootUiRef and internalOnBeforeRender functions from Ink) were retained indefinitely in the global array. A new removeCleanup utility function has been added to packages/cli/src/utils/cleanup.ts and called in the appropriate finally and React lifecycle cleanup stages to prevent this unbounded growth.
2. Fuzzy Finder Status Listener Leaks (statusChangeListeners): The statusChangeListeners in packages/core/src/tools/mcp-client.ts was implemented using a simple array. During rapid mounting/unmounting of the fuzzy finder dialog, failure to correctly find and slice listeners could cause duplicate retention. It has been converted to a Set<StatusChangeListener> which intrinsically enforces uniqueness and guards against these leaks.

Related Issues

Fixes #24924

How to Validate

Run preflgiht

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:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-cli]

Hi @spencer426, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[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 addresses critical memory leaks within the CLI, which previously led to significant memory consumption over extended sessions. The changes focus on improving lifecycle management by ensuring cleanup functions are properly unregistered and listener collections prevent duplicate entries, thereby stabilizing the application's memory footprint and enhancing overall performance.

Highlights

• Lifecycle Memory Leaks Resolution: Introduced removeCleanup and removeSyncCleanup utilities to ensure proper teardown of listeners and root closures, preventing unbounded memory growth in interactiveCli.tsx and AppContainer.tsx by explicitly unregistering cleanup functions.
• Fuzzy Finder Listener Leaks Resolution: Converted statusChangeListeners in mcp-client.ts from an array to a Set to intrinsically enforce uniqueness and prevent duplicate retention during rapid mounting/unmounting of the fuzzy finder dialog.

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.

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. ↩

[github-actions]

Size Change: +1.9 kB (+0.01%)

Total Size: 34 MB

Filename	Size	Change
./bundle/chunk-NSV3EDCI.js	0 B	-3.47 kB (removed)	🏆
./bundle/chunk-TX3L2CZM.js	0 B	-3.16 MB (removed)	🏆
./bundle/chunk-WBME2IS5.js	0 B	-14.8 MB (removed)	🏆
./bundle/core-4WDRA6GU.js	0 B	-46 kB (removed)	🏆
./bundle/devtoolsService-GK4ZSKAX.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-RLRDCNNM.js	0 B	-552 kB (removed)	🏆
./bundle/interactiveCli-3TID3HYD.js	0 B	-1.66 MB (removed)	🏆
./bundle/oauth2-provider-BHXHWIBC.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-H6CR7SHM.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/chunk-SYAAMTN2.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/chunk-YDFZPSYQ.js	3.8 kB	+3.8 kB (new file)	🆕
./bundle/core-Y3ZKAGVC.js	46 kB	+46 kB (new file)	🆕
./bundle/devtoolsService-BXTXP4NU.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-BI6MRXHN.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-L2FV6ASX.js	1.66 MB	+1.66 MB (new file)	🆕
./bundle/oauth2-provider-D4T73C7O.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5NENR2YT.js	1.96 MB	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-KGJHUSFI.js	0 B	-856 B (removed)	🏆
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/gemini.js	4.97 kB	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/memoryDiscovery-GD6P6WBI.js	980 B	0 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/cleanup-AB4IJ55C.js	932 B	+932 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces removeCleanup and removeSyncCleanup utilities, enabling cleanup functions to be unregistered from a global list. This functionality is then used in interactiveCli.tsx to ensure various cleanup tasks (Ink unmount, console patcher, TTY checks, line wrapping) are explicitly executed and unregistered within a try...finally block upon application exit. Additionally, mcp-client.ts refactors its listener management to use a Set for cleaner add and delete operations. A high-severity issue was identified in AppContainer.tsx where a useEffect cleanup function removes a registered cleanup function from the global list but fails to execute it, potentially leading to resource leaks and incorrect application state. A suggestion was provided to explicitly invoke the cleanup function.

_{Note: Security Review did not run due to the size of the PR.}

[jacob314]

Review from /review-frontend (Audited by Jacob)

This PR implements an excellent approach to resolving the memory leak issues by explicitly unregistering cleanup handlers and converting the listener collection to a Set. The title and methodology are fully aligned with the codebase standards.

During review, I identified two areas where error handling robustness could be improved to prevent unhandled promise rejections or terminal state corruption:

1. Unhandled Promise Rejection in AppContainer.tsx
In packages/cli/src/ui/AppContainer.tsx, the useEffect cleanup block invokes the asynchronous cleanupFn but uses void without error handling:

    return () => {
      removeCleanup(cleanupFn);
      void cleanupFn();
    };

Because cleanupFn kills background tasks and disconnects the IDE client asynchronously, if any of those operations throw, it will result in an unhandled promise rejection. It might be safer to explicitly catch and log errors:

    return () => {
      removeCleanup(cleanupFn);
      cleanupFn().catch(e => debugLogger.error('Error during cleanup:', e));
    };

2. Fragile finally block in interactiveCli.tsx
In packages/cli/src/interactiveCli.tsx, multiple cleanups are executed sequentially within a single finally block:

  } finally {
    removeCleanup(cleanupConsolePatcher);
    cleanupConsolePatcher();

    removeCleanup(cleanupUnmount);
    instance.unmount();

    removeCleanup(cleanupTtyCheck);
    cleanupTtyCheck();
    
    // ...
  }

If cleanupConsolePatcher() or instance.unmount() throws a synchronous error, the remaining cleanups (crucially, restoring the terminal with cleanupLineWrapping()) will be bypassed, potentially leaving the user's terminal in a broken visual state. It might be safer to execute these independently or ensure exceptions are caught and swallowed, similar to how runExitCleanup() handles them.

[github-actions]

✅ 59 tests passed successfully on gemini-3-flash-preview.

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• ⚠️ Consider adding Evals: No behavioral evaluations (evals/*.eval.ts) were added or updated in this PR. Consider adding a test case to verify the new behavior and prevent regressions.
• 🚀 Maintainer Reminder: Please ensure that these changes do not regress results on benchmark evals before merging.

---

This is an automated guidance message triggered by steering logic signatures.

[jacob314]