refactor(core): use centralized path resolution for Linux sandbox

[ehedlund]

Summary

Refactor the Linux sandbox management (LinuxSandboxManager and buildBwrapArgs) to leverage the unified resolveSandboxPaths and ResolvedSandboxPaths from sandboxManager.ts. This change centralizes path resolution and symlink expansion, removing redundant and manual path handling from the Linux-specific implementation.

Details

• Interface Alignment: Updated BwrapArgsOptions to accept ResolvedSandboxPaths, mirroring the architecture used in the Windows sandbox.
• Simplified Argument Building: Removed manual tryRealpath and sanitizePaths calls in buildBwrapArgs, as these are now provided by the shared resolution service.
• Robust Path Mounting: Ensures both the original path and its realpath are bound in the sandbox for critical areas like the workspace and governance files.
• No-Op Implementation: Maintained exact behavioral parity with the previous implementation, including Linux-specific features like Git worktree resolution and parent-directory binding for non-existent paths.
• Refined Testing: Updated the test suite to use the new structured path interface, while improving test readability and focus.

Related Issues

Internal refactor.

How to Validate

1. Run core unit tests: npm test -w @google/gemini-cli-core -- src/sandbox/linux/bwrapArgsBuilder.test.ts
2. Run Linux sandbox manager tests: npm test -w @google/gemini-cli-core -- src/sandbox/linux/LinuxSandboxManager.test.ts

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 @ehedlund, 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 refactors the Linux sandbox management by integrating a centralized path resolution mechanism. This change significantly simplifies the bwrapArgsBuilder module by offloading complex path handling, such as symlink expansion and sanitization, to a shared service. The refactor ensures consistent and robust path management across the sandbox, mirroring the architecture used in the Windows sandbox, while maintaining existing behavioral parity.

Highlights

• Centralized Linux sandbox path resolution: The Linux sandbox now uses a unified ResolvedSandboxPaths object, streamlining how file system paths are handled.
• Simplified bwrapArgsBuilder interface: The BwrapArgsOptions interface was refactored to accept the ResolvedSandboxPaths object, removing redundant individual path arrays and permission objects.
• Removed manual path handling: Manual tryRealpath and sanitizePaths calls have been eliminated from buildBwrapArgs, as these concerns are now managed by the centralized resolution service.
• Enhanced path binding for workspace and governance files: The system now explicitly binds both the original and resolved (real) paths for critical workspace and governance files, improving robustness.
• Refactored test suite: Unit tests for bwrapArgsBuilder have been updated to align with the new ResolvedSandboxPaths interface, making them clearer and more focused.

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.62 kB (0%)

Total Size: 34 MB

Filename	Size	Change
./bundle/chunk-42YNSZXF.js	0 B	-3.47 kB (removed)	🏆
./bundle/chunk-LEXYTOZN.js	0 B	-14.8 MB (removed)	🏆
./bundle/chunk-XRUV2WUR.js	0 B	-3.16 MB (removed)	🏆
./bundle/core-2FQGKLRS.js	0 B	-45.4 kB (removed)	🏆
./bundle/devtoolsService-HYIF5EJM.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-AJUBQKT5.js	0 B	-552 kB (removed)	🏆
./bundle/interactiveCli-AW6L7ZLZ.js	0 B	-1.64 MB (removed)	🏆
./bundle/oauth2-provider-KDW6YRJD.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-JIBP4MLK.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/chunk-KTYWP3CG.js	3.47 kB	+3.47 kB (new file)	🆕
./bundle/chunk-V6MJTBOS.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/core-6H7A2Y3K.js	45.4 kB	+45.4 kB (new file)	🆕
./bundle/devtoolsService-L7EBIJDQ.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-MWNFNIUW.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-72YVGPPT.js	1.64 MB	+1.64 MB (new file)	🆕
./bundle/oauth2-provider-X2OY3US3.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-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-OGWWODAT.js	1.96 MB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-EFS577AW.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-JNNGTYL3.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-DY3QEBW6.js	856 B	+856 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request refactors the bwrapArgsBuilder to use a resolvedPaths object, streamlining path handling within the sandbox. This change simplifies the BwrapArgsOptions interface and the buildBwrapArgs function by centralizing path resolution. Corresponding test files have been updated to reflect these new path management strategies, including the introduction of a createResolvedPaths helper. A review comment highlighted a potential regression in secret masking for symlinked workspaces, noting that the getSecretFilesArgs function should include both the original and resolved workspace paths to ensure comprehensive secret detection.

[DavidAPierce]

LGMT and the CLI:

CLI review:
Summary of Review
This PR significantly improves the robustness and maintainability of the Linux sandbox implementation by centralizing path resolution into a shared service (resolveSandboxPaths). This aligns the Linux implementation with
Windows, ensuring consistent handling of symlinks, path sanitization, and security policies across platforms.

Analysis

• Correctness: The refactor correctly replaces manual tryRealpath and sanitizePaths calls with the unified ResolvedSandboxPaths structure. The logic for mounting both original and resolved workspace paths ensures that
  governance files and workspace assets are correctly mapped inside the sandbox even when symlinks are involved.
• Maintainability: Centralizing path resolution logic in packages/core/src/services/sandboxManager.ts reduces code duplication and makes it easier to reason about the security boundaries of the sandbox.
• Security:
  • The getSecretFilesArgs function now scans globalIncludes in addition to the workspace and explicitly allowed paths, providing better protection against accidental secret exposure.
  • The use of ResolvedSandboxPaths ensures that both the symlink and its target are considered when applying forbidden path rules.
• Testability: The test suites (bwrapArgsBuilder.test.ts and LinuxSandboxManager.test.ts) have been updated to reflect the new architecture. The introduction of createResolvedPaths in tests makes them cleaner and more
  focused.

Findings

Correctness
The update to LinuxSandboxManager.ts correctly passes includeDirectories to the resolution service and uses the merged permissions for network access detection.

Efficiency
By offloading path resolution to a single pass in resolveSandboxPaths, the system avoids redundant filesystem calls previously scattered throughout the bubblewrap argument builder.

Recommendation
Approved. The changes are architecturally sound, improve code quality, and enhance the security posture of the Linux sandbox.