fix(plan): clean up session directories and plans on deletion (#20914)

docs/cli/plan-mode.md

@@ -28,6 +28,7 @@ implementation. It allows you to:
     - [Example: Enable research subagents in Plan Mode](#example-enable-research-subagents-in-plan-mode)
   - [Custom Plan Directory and Policies](#custom-plan-directory-and-policies)
 - [Automatic Model Routing](#automatic-model-routing)
+- [Cleanup](#cleanup)
 
 ## Enabling Plan Mode
 
@@ -290,6 +291,24 @@ performance. You can disable this automatic switching in your settings:
 }
 ```
 
+## Cleanup
+
+By default, Gemini CLI automatically cleans up old session data, including all
+associated plan files and task trackers.
+
+- **Default behavior:** Sessions (and their plans) are retained for **30 days**.
+- **Configuration:** You can customize this behavior via the `/settings` command
+  (search for **Session Retention**) or in your `settings.json` file. See
+  [session retention] for more details.
+
+Manual deletion also removes all associated artifacts:
+
+- **Command Line:** Use `gemini --delete-session <index|id>`.
+- **Session Browser:** Press `/resume`, navigate to a session, and press `x`.
+
+If you use a [custom plans directory](#custom-plan-directory-and-policies),
+those files are not automatically deleted and must be managed manually.
+
 [`list_directory`]: /docs/tools/file-system.md#1-list_directory-readfolder
 [`read_file`]: /docs/tools/file-system.md#2-read_file-readfile
 [`grep_search`]: /docs/tools/file-system.md#5-grep_search-searchtext
@@ -311,3 +330,4 @@ performance. You can disable this automatic switching in your settings:
 [auto model]: /docs/reference/configuration.md#model-settings
 [model routing]: /docs/cli/telemetry.md#model-routing
 [preferred external editor]: /docs/reference/configuration.md#general
+[session retention]: /docs/cli/session-management.md#session-retention

docs/cli/session-management.md

@@ -121,27 +121,36 @@ session lengths.
 
 ### Session retention
 
-To prevent your history from growing indefinitely, enable automatic cleanup
-policies in your settings.
+By default, Gemini CLI automatically cleans up old session data to prevent your
+history from growing indefinitely. When a session is deleted, Gemini CLI also
+removes all associated data, including implementation plans, task trackers, tool
+outputs, and activity logs.
+
+The default policy is to **retain sessions for 30 days**.
+
+#### Configuration
+
+You can customize these policies using the `/settings` command or by manually
+editing your `settings.json` file:
 
 ```json
 {
   "general": {
     "sessionRetention": {
       "enabled": true,
-      "maxAge": "30d", // Keep sessions for 30 days
-      "maxCount": 50 // Keep the 50 most recent sessions
+      "maxAge": "30d",
+      "maxCount": 50
     }
   }
 }
 ```
 
 - **`enabled`**: (boolean) Master switch for session cleanup. Defaults to
-  `false`.
+  `true`.
 - **`maxAge`**: (string) Duration to keep sessions (for example, "24h", "7d",
-  "4w"). Sessions older than this are deleted.
+  "4w"). Sessions older than this are deleted. Defaults to `"30d"`.
 - **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
-  sessions exceeding this count are deleted.
+  sessions exceeding this count are deleted. Defaults to undefined (unlimited).
 - **`minRetention`**: (string) Minimum retention period (safety limit). Defaults
   to `"1d"`. Sessions newer than this period are never deleted by automatic
   cleanup.