Hibernate idle background terminal surfaces and cap live surfaces (LRU)

.github/swift-file-length-budget.tsv

@@ -1,15 +1,15 @@
 # cmux-owned Swift file length budget.
 # Format: max_lines<TAB>relative path
 # Reduce counts as files shrink. CI fails if tracked files exceed this budget.
-32655	CLI/cmux.swift
-22098	Sources/TerminalController.swift
-19820	Sources/Workspace.swift
+32697	CLI/cmux.swift
+22159	Sources/TerminalController.swift
+19958	Sources/Workspace.swift
 19209	Sources/ContentView.swift
-18044	Sources/AppDelegate.swift
-16539	Sources/GhosttyTerminalView.swift
+18047	Sources/AppDelegate.swift
+16746	Sources/GhosttyTerminalView.swift
 13589	Sources/Panels/BrowserPanel.swift
 11916	cmuxTests/AppDelegateShortcutRoutingTests.swift
-9939	Sources/TabManager.swift
+9959	Sources/TabManager.swift
 8494	cmuxTests/CLINotifyProcessIntegrationRegressionTests.swift
 7737	Sources/Panels/BrowserPanelView.swift
 7198	cmuxTests/WorkspaceUnitTests.swift
@@ -44,10 +44,10 @@
 2290	Sources/FileExplorerView.swift
 2260	Sources/TerminalWindowPortal.swift
 2208	Sources/Mobile/MobileHostService.swift
-2138	Sources/SessionPersistence.swift
+2188	Sources/SessionPersistence.swift
 2123	cmuxTests/ShortcutAndCommandPaletteTests.swift
 2117	cmuxTests/CmuxConfigTests.swift
-1996	Sources/KeyboardShortcutSettingsFileStore.swift
+2039	Sources/KeyboardShortcutSettingsFileStore.swift
 1949	Sources/Panels/BrowserWebAuthnSupport.swift
 1860	cmuxTests/NotificationAndMenuBarTests.swift
 1793	Sources/SessionIndexStore.swift
@@ -76,13 +76,14 @@
 1144	Sources/VaultAgentProcessScanner.swift
 1139	cmuxTests/PiVaultAgentPersistenceTests.swift
 1107	Sources/AppDelegate+CmuxSSHURL.swift
-1084	cmuxTests/AgentHibernationTests.swift
+1096	Sources/GhosttyConfig.swift
+1096	cmuxTests/AgentHibernationTests.swift
 1068	cmuxTests/FileExplorerStoreTests.swift
 1058	cmuxUITests/BonsplitTabDragUITests.swift
-1096	Sources/GhosttyConfig.swift
 1021	cmuxUITests/TerminalCmdClickUITests.swift
 1006	cmuxTests/CmuxSSHURLRequestTests.swift
 1000	cmuxTests/CmuxTopSnapshotScopeTests.swift
+963	Sources/Panels/TerminalPanel.swift
 949	Packages/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift
 947	Sources/TerminalNotificationPolicy.swift
 945	Sources/SessionIndexRegisteredAgents.swift
@@ -93,10 +94,10 @@
 924	Sources/DockPanelView.swift
 913	cmuxTests/WorkspaceGroupTests.swift
 905	Sources/CmuxSSHURLRequest.swift
+894	Sources/CommandPalette/CommandPaletteSettingsToggle.swift
+884	cmuxTests/SurfaceHibernationPolicyTests.swift
 878	Sources/WorkspaceContentView.swift
 868	Sources/Panels/BrowserScreenshotSnapshotter.swift
-866	Sources/CommandPalette/CommandPaletteSettingsToggle.swift
-863	Sources/Panels/TerminalPanel.swift
 856	Packages/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/AppSection.swift
 846	cmuxTests/AgentSessionAutoResumeSettingsTests.swift
 845	cmuxTests/SSHStartupSignalLifecycleTests.swift
@@ -119,6 +120,7 @@
 705	cmuxUITests/BrowserOmnibarSuggestionsUITests.swift
 701	CLI/CMUXCLI+AgentHookDefinitions.swift
 698	cmuxTests/RestorableAgentHookProviderResumeTests.swift
+697	Sources/App/AgentHibernationController.swift
 697	cmuxTests/TerminalNotificationClearAllTests.swift
 696	cmuxTests/UpdatePillReleaseVisibilityTests.swift
 693	Sources/Panels/BrowserPopupWindowController.swift
@@ -131,8 +133,8 @@
 668	cmuxTests/FeedCoordinatorTests.swift
 668	cmuxTests/KeyboardShortcutContextTests.swift
 654	Packages/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/KeyboardShortcutsSection.swift
+653	Sources/CmuxTopSnapshot.swift
 650	Sources/Panels/MarkdownRemoteImageLoader.swift
-649	Sources/CmuxTopSnapshot.swift
 640	cmuxTests/CommandPaletteNucleoFFITests.swift
 638	Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ExpressionEvaluator.swift
 630	Packages/CmuxSettings/Sources/CmuxSettings/Values/ShortcutWhenClause.swift
@@ -145,8 +147,8 @@
 599	Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizerPrimaryPolicies.swift
 596	cmuxTests/CmuxEventBusTests.swift
 594	Sources/SessionIndexModels.swift
+594	Sources/SettingsNavigation.swift
 594	cmuxTests/PortalTabDragRoutingTests.swift
-589	Sources/SettingsNavigation.swift
 588	cmuxTests/CommandPaletteShortcutCustomizationTests.swift
 586	Sources/JSONCParser.swift
 585	Sources/Cloud/VMClient.swift
@@ -157,6 +159,7 @@
 574	Sources/Feed/FeedTextEditorDebugWindowController.swift
 568	Packages/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift
 566	Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizer.swift
+562	Sources/App/WorkspaceRuntimeSettings.swift
 562	cmuxTests/AgentExecutableResolverTests.swift
 560	cmuxTests/GhosttyConfigPathResolverTests.swift
 558	Packages/CmuxGit/Sources/CmuxGit/Parsing/GitMetadataService+Config.swift

.github/workflows/ci.yml

@@ -331,6 +331,23 @@ jobs:
             -only-testing:cmuxTests/AppearanceSettingsTests/testSplitGhosttyThemeUsesSystemDarkWhenAppAppearanceIsStaleLight \
             test
 
+      # The full unit-test pass below tolerates app-host crashes by classifying
+      # the surviving summary lines, so suites that sort after an early crash
+      # can be skipped without failing the job. Surface hibernation policy
+      # tests gate memory reclamation (issue 5731) and must always execute.
+      - name: Run surface hibernation policy regression
+        run: |
+          set -euo pipefail
+          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
+          xcodebuild -project cmux.xcodeproj -scheme cmux-unit -configuration Debug \
+            -derivedDataPath "$CMUX_DERIVED_DATA_PATH" \
+            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
+            -disableAutomaticPackageResolution \
+            -destination "platform=macOS" \
+            CMUX_SKIP_ZIG_BUILD=1 \
+            -only-testing:cmuxTests/SurfaceHibernationPolicyTests \
+            test
+
       - name: Run unit tests
         run: |
           set -euo pipefail

CLI/cmux.swift

@@ -3347,6 +3347,9 @@ struct CMUXCLI {
         case "agent-hibernation":
             try runAgentHibernation(commandArgs: commandArgs, client: client, jsonOutput: jsonOutput)
 
+        case "surface-hibernation":
+            try runSurfaceHibernation(commandArgs: commandArgs, client: client, jsonOutput: jsonOutput)
+
         case "auth", "login", "logout":
             let authArgs = command == "auth" ? commandArgs : [command] + commandArgs
             let sub = authArgs.first?.lowercased() ?? "status"
@@ -5012,6 +5015,7 @@ struct CMUXCLI {
         "__codex-teams-watch",
         "__tmux-compat",
         "agent-hibernation",
+        "surface-hibernation",
         "auth",
         "bind-key",
         "break-pane",
@@ -13060,6 +13064,13 @@ struct CMUXCLI {
             Enable or disable Agent Hibernation.
             Configure idle and live-terminal limits from Settings or cmux settings JSON.
             """
+        case "surface-hibernation":
+            return """
+            Usage: cmux surface-hibernation <on|off> [--json]
+
+            Enable or disable Surface Hibernation for idle background terminals.
+            Configure idle and live-surface limits from Settings or cmux settings JSON.
+            """
         case "restore-session":
             return """
             Usage: cmux restore-session
@@ -22370,6 +22381,36 @@ struct CMUXCLI {
         }
     }
 
+    private func runSurfaceHibernation(
+        commandArgs: [String],
+        client: SocketClient,
+        jsonOutput: Bool
+    ) throws {
+        guard let subcommand = commandArgs.first?.lowercased() else {
+            throw CLIError(message: "Usage: cmux surface-hibernation <on|off> [--json]")
+        }
+        let response: String
+        switch subcommand {
+        case "on", "enable":
+            response = try sendV1Command("surface_hibernation on", client: client)
+        case "off", "disable":
+            response = try sendV1Command("surface_hibernation off", client: client)
+        default:
+            throw CLIError(message: "Usage: cmux surface-hibernation <on|off> [--json]")
+        }
+
+        if jsonOutput {
+            let ok = response == "OK"
+            var fallback: [String: Any] = ["ok": ok]
+            if !ok {
+                fallback["message"] = response
+            }
+            print(jsonString(fallback))
+        } else {
+            print(response)
+        }
+    }
+
     private func shouldApplyClaudeHookVisibleMutation(
         sessionStore: ClaudeHookSessionStore,
         parsedInput: ClaudeHookParsedInput,
@@ -32429,6 +32470,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
           shortcuts
           disable-browser | enable-browser | browser-status
           agent-hibernation <on|off>
+          surface-hibernation <on|off>
           restore-session
           open <path-or-url>... [--workspace <id|ref|index>] [--surface <id|ref|index>] [--pane <id|ref|index>] [--window <id|ref|index>] [--focus <true|false>] [--no-focus]
           diff [patch-file|-] [--source <unstaged|staged|branch|last-turn>] [--unstaged|--staged|--branch|--last-turn] [--workspace <id|ref|index>] [--surface <id|ref|index>] [--window <id|ref|index>] [--cwd <path>] [--base <ref>] [--focus <true|false>] [--no-focus] [--title <text>] [--layout <split|unified>] [--font-size <points>]

Packages/CmuxSettings/Sources/CmuxSettings/Keys/TerminalCatalogSection.swift

@@ -38,6 +38,39 @@ public struct TerminalCatalogSection: SettingCatalogSection {
         userDefaultsKey: "terminal.agentHibernation.maxLiveTerminals"
     )
 
+    /// Whether Surface Hibernation reclaims idle plain-shell terminals in
+    /// hidden workspaces (scrollback and working directory are restored on
+    /// the next visit).
+    public let surfaceHibernationEnabled = DefaultsKey<Bool>(
+        id: "terminal.surfaceHibernation.enabled",
+        defaultValue: true,
+        userDefaultsKey: "terminal.surfaceHibernation.enabled"
+    )
+
+    /// Minimum quiet seconds before the live-surface cap may reclaim a
+    /// background shell terminal.
+    public let surfaceHibernationIdleSeconds = DefaultsKey<Double>(
+        id: "terminal.surfaceHibernation.idleSeconds",
+        defaultValue: 300,
+        userDefaultsKey: "terminal.surfaceHibernation.idleSeconds"
+    )
+
+    /// Seconds a workspace must stay hidden — with its terminal quiet —
+    /// before its idle shell surfaces hibernate even under the cap.
+    public let surfaceHibernationUnmountedIdleSeconds = DefaultsKey<Double>(
+        id: "terminal.surfaceHibernation.unmountedIdleSeconds",
+        defaultValue: 1800,
+        userDefaultsKey: "terminal.surfaceHibernation.unmountedIdleSeconds"
+    )
+
+    /// Maximum simultaneously live terminal surfaces before the oldest
+    /// eligible background terminals hibernate.
+    public let surfaceHibernationMaxLiveSurfaces = DefaultsKey<Int>(
+        id: "terminal.surfaceHibernation.maxLiveSurfaces",
+        defaultValue: 12,
+        userDefaultsKey: "terminal.surfaceHibernation.maxLiveSurfaces"
+    )
+
     public let showTextBoxOnNewTerminals = DefaultsKey<Bool>(
         id: "terminal.showTextBoxOnNewTerminals",
         defaultValue: false,

Packages/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/TerminalSection.swift

@@ -20,6 +20,10 @@ public struct TerminalSection: View {
     @State private var hibernation: DefaultsValueModel<Bool>
     @State private var idleSeconds: DefaultsValueModel<Double>
     @State private var maxLive: DefaultsValueModel<Int>
+    @State private var surfaceHibernation: DefaultsValueModel<Bool>
+    @State private var surfaceIdleSeconds: DefaultsValueModel<Double>
+    @State private var surfaceUnmountedIdleSeconds: DefaultsValueModel<Double>
+    @State private var surfaceMaxLive: DefaultsValueModel<Int>
 
     public init(
         defaultsStore: UserDefaultsSettingsStore,
@@ -37,6 +41,10 @@ public struct TerminalSection: View {
         _hibernation = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.agentHibernationEnabled))
         _idleSeconds = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.agentHibernationIdleSeconds))
         _maxLive = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.agentHibernationMaxLiveTerminals))
+        _surfaceHibernation = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.surfaceHibernationEnabled))
+        _surfaceIdleSeconds = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.surfaceHibernationIdleSeconds))
+        _surfaceUnmountedIdleSeconds = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.surfaceHibernationUnmountedIdleSeconds))
+        _surfaceMaxLive = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.surfaceHibernationMaxLiveSurfaces))
     }
 
     public var body: some View {
@@ -210,6 +218,64 @@ public struct TerminalSection: View {
                 )
                 .accessibilityIdentifier("SettingsTerminalAgentHibernationMaxLiveStepper")
             }
+            SettingsCardDivider()
+            SettingsCardRow(
+                configurationReview: .json("terminal.surfaceHibernation.enabled"),
+                String(localized: "settings.terminal.surfaceHibernation", defaultValue: "Surface Hibernation"),
+                subtitle: surfaceHibernation.current
+                    ? String(localized: "settings.terminal.surfaceHibernation.subtitleOn", defaultValue: "Idle shell terminals in hidden workspaces release their renderer and restart with scrollback and directory restored on the next visit.")
+                    : String(localized: "settings.terminal.surfaceHibernation.subtitleOff", defaultValue: "Terminal surfaces stay live until you close them or quit cmux.")
+            ) {
+                Toggle("", isOn: Binding(get: { surfaceHibernation.current }, set: { surfaceHibernation.set($0) }))
+                    .labelsHidden()
+                    .controlSize(.small)
+                    .accessibilityIdentifier("SettingsTerminalSurfaceHibernationToggle")
+            }
+            SettingsCardDivider()
+            SettingsCardRow(
+                configurationReview: .json("terminal.surfaceHibernation.idleSeconds"),
+                String(localized: "settings.terminal.surfaceHibernation.idleSeconds", defaultValue: "Cap Reclaim After Idle Seconds"),
+                subtitle: String(localized: "settings.terminal.surfaceHibernation.idleSeconds.subtitle", defaultValue: "A background shell terminal must be quiet for this long before the live-surface cap may reclaim it."),
+                controlWidth: 140
+            ) {
+                Stepper(
+                    "\(Int(surfaceIdleSeconds.current))",
+                    value: Binding(get: { surfaceIdleSeconds.current }, set: { surfaceIdleSeconds.set($0) }),
+                    in: 30...604_800,
+                    step: 60
+                )
+                .accessibilityIdentifier("SettingsTerminalSurfaceHibernationIdleSecondsStepper")
+            }
+            SettingsCardDivider()
+            SettingsCardRow(
+                configurationReview: .json("terminal.surfaceHibernation.unmountedIdleSeconds"),
+                String(localized: "settings.terminal.surfaceHibernation.unmountedIdleSeconds", defaultValue: "Hibernate Hidden Workspaces After Seconds"),
+                subtitle: String(localized: "settings.terminal.surfaceHibernation.unmountedIdleSeconds.subtitle", defaultValue: "Shell terminals in workspaces hidden and quiet for this long hibernate even under the live-surface cap."),
+                controlWidth: 140
+            ) {
+                Stepper(
+                    "\(Int(surfaceUnmountedIdleSeconds.current))",
+                    value: Binding(get: { surfaceUnmountedIdleSeconds.current }, set: { surfaceUnmountedIdleSeconds.set($0) }),
+                    in: 60...2_592_000,
+                    step: 300
+                )
+                .accessibilityIdentifier("SettingsTerminalSurfaceHibernationUnmountedIdleSecondsStepper")
+            }
+            SettingsCardDivider()
+            SettingsCardRow(
+                configurationReview: .json("terminal.surfaceHibernation.maxLiveSurfaces"),
+                String(localized: "settings.terminal.surfaceHibernation.maxLiveSurfaces", defaultValue: "Max Live Terminal Surfaces"),
+                subtitle: String(localized: "settings.terminal.surfaceHibernation.maxLiveSurfaces.subtitle", defaultValue: "Every live surface counts toward the cap; only idle, non-busy, hidden ones are reclaimed, oldest first."),
+                controlWidth: 120
+            ) {
+                Stepper(
+                    "\(surfaceMaxLive.current)",
+                    value: Binding(get: { surfaceMaxLive.current }, set: { surfaceMaxLive.set($0) }),
+                    in: 1...256,
+                    step: 1
+                )
+                .accessibilityIdentifier("SettingsTerminalSurfaceHibernationMaxLiveStepper")
+            }
         }
     }