feat(cli): add /bug-memory command and auto-capture heap snapshot in /bug

[Anjaligarhwal]

Summary

Adds a new /bug-memory slash command that captures a V8 heap snapshot and saves it to disk, and teaches the existing /bug command to do the same automatically when process RSS exceeds 2 GB. Closes the friction gap called
out in #25337 — users no longer need to attach Chrome DevTools just to share a memory snapshot with a bug report.

The URL shown by /bug always renders before capture begins, so the 20+ second snapshot never makes the CLI look frozen.

Details

How the capture works

• captureHeapSnapshot(filePath) pipes v8.getHeapSnapshot() straight into fs.createWriteStream(filePath) via node:stream/promises pipeline. This is entirely in-process — nothing is exposed over a debugger port, which addresses the "don't require port 9229" constraint in Add a /bug-memory command that takes a memory snapshot and saves it to disk #25337 by not requiring any port.
• pipeline propagates backpressure end-to-end, so V8 slows its snapshot producer whenever the downstream write stream cannot keep up. A 2 GB+ heap is written with constant memory overhead; chunks never accumulate in the JavaScript heap.
• pipeline also handles error propagation and stream cleanup, so there is no manual try/finally, no listener bookkeeping, and no separate "disconnect" step.

/bug integration

• After the bug URL is displayed and open() is invoked, /bug checks process.memoryUsage().rssagainstMEMORY_SNAPSHOT_AUTO_THRESHOLD_BYTES(2 GB). If over the threshold and a project temp dir is available, it captures a snapshot to/bug-memory-<Date.now()>.heapsnapshot` and shows the resulting path + size in the UI history.
• A capture failure is surfaced as an error message but never throws — the bug-report flow still completes.

Shared utility

• captureHeapSnapshot(filePath) lives in packages/cli/src/ui/utils/memorySnapshot.ts so /bug and /bug-memory
  can never drift.

Related Issues

Fixes #25337

How to Validate

Automated

# All 30 tests in the affected files pass:
cd packages/cli
npx vitest run \
  src/ui/utils/memorySnapshot.test.ts \
  src/ui/commands/bugMemoryCommand.test.ts \
  src/ui/commands/bugCommand.test.ts \
  src/services/BuiltinCommandLoader.test.ts

npx tsc --noEmit       # clean
npx eslint .           # clean on touched files
npx prettier --check . # clean on touched files

Manual — /bug-memory happy path

1. Start the CLI: npm run start
2. Run /bug-memory
3. Expected: info message lists the destination path and warns about 20+ second duration; a second info message appears when capture completes showing size and duration.
4. Load the *.heapsnapshot file in Chrome DevTools → Memory → Load to confirm it is a valid snapshot.

Manual — /bug auto-capture

1. Start the CLI with a higher heap so RSS can cross 2 GB, e.g. NODE_OPTIONS='--max-old-space-size=4096' npm run start, then run some memory-heavy prompts until process.memoryUsage().rss exceeds 2 GB (you can confirm via /bug which reports current RSS in the report info).
2. Run /bug some memory leak.
3. Expected ordering in the UI history:
   1. Bug URL message (and the browser opens).
   2. "High memory usage detected (…). Capturing V8 heap snapshot to …" info.
   3. After ~20 s, "Heap snapshot saved (…) in …ms: …" info.
4. Below 2 GB, step 2 and 3 are skipped — the command behaves exactly as it does today.

Edge cases covered by tests

• /bug-memory when the project temp directory is unavailable → clean error, no capture attempted.
• /bug-memory when HeapProfiler.takeHeapSnapshot rejects → the session is still disconnected, the user sees an error.
• /bug below the threshold → no capture at all (existing behavior unchanged).
• /bug above the threshold where capture fails → bug URL still opened, capture error surfaced, command resolves normally.

Validation Evidence

End-to-end run on Windows 11, Node 20, npm run start, current RSS 211.6 MB
(below the 2 GB auto-capture threshold, so /bug behaves unchanged while /bug-memory captures on demand).

1. /bug runs unchanged below the 2 GB threshold, and /bug-memory appears alongside it in autocomplete.

2. /bug-memory emits the destination message before capture begins and the "snapshot saved" message after.

3. The snapshot file is physically written to the project temp directory with the expected size.

4. The snapshot loads in Chrome DevTools → Memory and parses cleanly; the expanded (compiled code) node shows real source paths from the running process, confirming the captured data is genuine.

5. The Constructors summary shows the expected Node.js + gemini-cli heap composition — live classes include Module, ModuleLoader, ResolveCache, ZodObject, plus Node internals (ArrayBuffer, system / Context) — exactly what a healthy CLI session should retain.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed) — no public docs reference the /bug command internals; slash-command description is self-documenting in /help.
• Added/updated tests (if needed) — 10 new tests (3 in memorySnapshot, 4 in bugMemoryCommand, 3 in bugCommand for the auto-capture branches) plus the existing BuiltinCommandLoader registration test covers the new command.
• Noted breaking changes (if any) — none; /bug behavior below 2 GB is byte-identical.
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run — end-to-end: command registers, captures, writes to disk,
      Chrome DevTools parses the snapshot (see Validation Evidence above).
    • 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 enhances the CLI's diagnostic capabilities by adding functionality to capture V8 heap snapshots. By providing both a manual command and an automated trigger based on memory usage thresholds, it significantly reduces the friction for users to provide actionable data when reporting memory-related bugs, without requiring external debugging tools or port exposure.

Highlights

• New /bug-memory command: Introduced a new slash command that allows users to manually trigger a V8 heap snapshot capture for debugging purposes.
• Automated memory snapshotting: Updated the existing /bug command to automatically capture a heap snapshot when the process RSS exceeds 2 GB, streamlining the reporting of memory-related issues.
• Memory-efficient implementation: Implemented snapshot streaming directly to disk using node:inspector/promises to ensure constant memory overhead during the capture process.

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

[gemini-code-assist]

Code Review

This pull request introduces V8 heap snapshotting to the CLI, adding a manual /bug-memory command and an automatic trigger in the /bug command for high memory usage. Feedback highlights a potential out-of-memory risk due to lack of stream backpressure in the current implementation, recommending the v8 module instead. Additionally, a correction was suggested for a UI message that incorrectly claims the CLI remains responsive during the blocking snapshot operation.

[Anjaligarhwal]

/gemini review

[gemini-code-assist]

Hello @Anjaligarhwal, I'm ready to perform the code review for this pull request. I will analyze the changes and provide feedback based on the review criteria. Please give me a moment to process the code.

[Anjaligarhwal]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new bug-memory command and enhances the existing bug command to automatically capture V8 heap snapshots when high memory usage (RSS > 2 GB) is detected. It also includes a new utility captureHeapSnapshot for efficient streaming of heap snapshots to disk and comprehensive unit tests for the new functionality. I have no feedback to provide.