Temporary Directory Leak During Background Shell Execution

[Daksh7785]

Reliability: Temporary directory leak for background shell executions

Category: Reliability / Resource Leak
Priority: High

Affected Components

• packages/core/src/tools/shell.ts
• packages/core/src/services/ShellExecutionService.ts

Summary

When a shell command is executed with is_background: true, the CLI creates a temporary directory (gemini-shell-*) to store bgpids.tmp. This directory is never removed after the background task finishes, resulting in a permanent resource leak.

Over time, repeated background executions accumulate orphaned directories inside the system temporary folder.

Current Behavior

The shell tool creates a temporary directory using fs.mkdtempSync() before executing the command.

For foreground commands, the directory is removed in the finally block.

For background commands, cleanup is intentionally skipped:

// Only clean up if NOT running in background.
if (!this.params.is_background) {
  // cleanup...
}

However, ownership of this temporary directory is never transferred to ShellExecutionService, so nothing removes it after the background process exits.

Expected Behavior

The temporary directory should be automatically deleted once the background process has completed.

Steps to Reproduce

1. Run any background command (e.g., sleep 10) with is_background: true.
2. Inspect the system temp directory (/tmp or %TEMP%).
3. Observe a new gemini-shell-* directory.
4. Wait for the background process to finish.
5. The directory still exists.

Impact

• Temporary directories accumulate indefinitely.
• Long-running CLI sessions or A2A server mode may create thousands of orphaned directories.
• Can eventually consume temporary storage or available inodes, leading to ENOSPC errors.

Suggested Solution

Transfer ownership of the temporary directory to ShellExecutionService.

A minimal approach would be to:

• Extend ShellExecutionService.background(...) to accept the tempDir path.
• Store the directory alongside the background process metadata.
• Remove the directory when the background process exits using:

await fsPromises.rm(tempDir, {
  recursive: true,
  force: true,
});

This keeps the existing behavior unchanged while ensuring temporary resources are cleaned up after the background task completes.

Testing

Add an integration test that:

1. Starts a short-lived background command.
2. Waits for it to exit.
3. Verifies the temporary directory has been deleted.

Acceptance Criteria

• ShellExecutionService accepts ownership of the temporary directory.
• Temporary directory is deleted when the background process exits.
• Integration test verifies cleanup.
• No behavior change for foreground shell execution.

[gemini-cli]

Effort Analysis:
The ShellToolInvocation.execute method in packages/core/src/tools/shell.ts creates a temporary directory (e.g., gemini-shell-*) using fs.mkdtempSync to store a PID file (bgpids.tmp). For background executions (where is_background: true), the finally block explicitly skips directory cleanup. However, the ownership of this directory is never passed to ShellExecutionService in packages/core/src/services/shellExecutionService.ts, which manages the background process lifecycle. Consequently, when the background process eventually exits, the temporary directory remains on disk. Fixing this requires a cross-component refactor: 1) Extending ShellExecutionService.background(pid, sessionId, command) to accept an optional tempDir parameter. 2) Updating ShellExecutionService to track these temporary directories in a new static map. 3) Modifying the onExit or cleanupLogStream logic in ShellExecutionService to remove the directory using fs.promises.rm. 4) Updating ShellToolInvocation.execute to pass the tempDir during the backgrounding call. This spans multiple files and involves coordinating state across different architectural layers, mapping to the 'Asynchronous Flow & Integration' and 'Cross-Component Refactors' guidelines for effort/medium.