Bound recorded sessions with a safe global janitor (Fixes #3164)

docs/cli/configuration.md

@@ -228,11 +228,31 @@ In addition to a project settings file, a project's `.llxprt` directory can cont
 
 #### `sessionRetention`
 
-- **`sessionRetention`** (object):
-  - **Description:** Settings for automatic session cleanup.
+- **`sessionRetention.enabled`** (boolean):
+  - **Description:** Enable automatic session cleanup. Set to false to disable all janitorial mutations.
+  - **Default:** `true`
+  - **Requires restart:** No
+
+- **`sessionRetention.maxTotalSizeMB`** (number):
+  - **Description:** Machine-wide aggregate size limit for all session recordings and cold archives, in MiB. Defaults to 4096 (4 GiB).
+  - **Default:** `4096`
+  - **Requires restart:** No
+
+- **`sessionRetention.maxAge`** (string):
+  - **Description:** Maximum age of sessions to keep (e.g. "30d", "7d", "24h"). No default age limit.
   - **Default:** `undefined`
   - **Requires restart:** No
 
+- **`sessionRetention.maxCount`** (number):
+  - **Description:** Maximum number of sessions to keep (most recent). No default count limit.
+  - **Default:** `undefined`
+  - **Requires restart:** No
+
+- **`sessionRetention.minRetention`** (string):
+  - **Description:** Minimum retention period (safety floor, defaults to "1d").
+  - **Default:** `"1d"`
+  - **Requires restart:** No
+
 #### `output`
 
 - **`output.format`** (enum):

packages/cli/src/config/settings-schema/schema-core.ts

@@ -322,7 +322,60 @@ export const CORE_SETTINGS_SCHEMA = {
     category: 'General',
     requiresRestart: false,
     default: undefined as SessionRetentionSettings | undefined,
-    description: 'Settings for automatic session cleanup.',
+    description:
+      'Settings for automatic session cleanup. Cleanup is enabled by default with a machine-wide 4 GiB aggregate size budget.',
+    properties: {
+      enabled: {
+        type: 'boolean',
+        label: 'Enabled',
+        category: 'General',
+        requiresRestart: false,
+        default: true,
+        description:
+          'Enable automatic session cleanup. Set to false to disable all janitorial mutations.',
+        showInDialog: true,
+      },
+      maxTotalSizeMB: {
+        type: 'number',
+        label: 'Max Total Size (MiB)',
+        category: 'General',
+        requiresRestart: false,
+        default: 4096,
+        description:
+          'Machine-wide aggregate size limit for all session recordings and cold archives, in MiB (see the default property).',
+        showInDialog: true,
+      },
+      maxAge: {
+        type: 'string',
+        label: 'Max Age',
+        category: 'General',
+        requiresRestart: false,
+        default: undefined,
+        description:
+          'Maximum age of sessions to keep (e.g. "30d", "7d", "24h"). No default age limit.',
+        showInDialog: true,
+      },
+      maxCount: {
+        type: 'number',
+        label: 'Max Count',
+        category: 'General',
+        requiresRestart: false,
+        default: undefined,
+        description:
+          'Maximum number of sessions to keep (most recent). No default count limit.',
+        showInDialog: true,
+      },
+      minRetention: {
+        type: 'string',
+        label: 'Min Retention',
+        category: 'General',
+        requiresRestart: false,
+        default: '1d',
+        description:
+          'Minimum retention period (safety floor, defaults to "1d").',
+        showInDialog: true,
+      },
+    },
   },
   output: {
     type: 'object',

packages/cli/src/config/settings.ts

@@ -112,7 +112,7 @@ export interface AccessibilitySettings {
 }
 
 export interface SessionRetentionSettings {
-  /** Enable automatic session cleanup */
+  /** Enable automatic session cleanup (default-on when unset). */
   enabled?: boolean;
 
   /** Maximum age of sessions to keep (e.g., "30d", "7d", "24h", "1w") */
@@ -123,6 +123,9 @@ export interface SessionRetentionSettings {
 
   /** Minimum retention period (safety limit, defaults to "1d") */
   minRetention?: string;
+
+  /** Machine-wide aggregate size limit in MiB (defaults to 4096 = 4 GiB). */
+  maxTotalSizeMB?: number;
 }
 
 export interface SettingsError {