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

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

@@ -153,6 +153,7 @@
 575	cmuxTests/FeedCoordinatorTests.swift
 574	Sources/Feed/FeedTextEditorDebugWindowController.swift
 568	Packages/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift
+562	Sources/App/WorkspaceRuntimeSettings.swift
 562	cmuxTests/AgentExecutableResolverTests.swift
 560	cmuxTests/GhosttyConfigPathResolverTests.swift
 558	Packages/CmuxGit/Sources/CmuxGit/Parsing/GitMetadataService+Config.swift
@@ -174,6 +175,7 @@
 519	Packages/CmuxSwiftRender/Tests/CmuxSwiftRenderTests/Corpus/stress-two-column-cockpit-sidebar.swift
 518	Packages/CmuxSwiftRender/Tests/CmuxSwiftRenderTests/Corpus/stress-git-review-queue-command-deck.swift
 516	Sources/CmuxConfigExecutor.swift
+514	cmuxTests/SurfaceHibernationPolicyTests.swift
 514	cmuxUITests/UpdatePillUITests.swift
 509	Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizerAdditionalPolicies.swift
 507	Sources/TerminalControllerTopSupport.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

Sources/App/SurfaceHibernationPolicy.swift

@@ -0,0 +1,113 @@
+import Foundation
+
+/// How a live Ghostty runtime surface can be reclaimed by hibernation.
+enum SurfaceHibernationMechanism: Equatable, Sendable {
+    /// The panel runs a restorable coding agent. Hibernation terminates the
+    /// scoped agent processes and frees the runtime surface; the agent resumes
+    /// with its saved session when the panel is visited again.
+    case agentResume
+    /// The panel is a plain shell whose recreation has no side effects.
+    /// Hibernation captures scrollback, frees the runtime surface (which ends
+    /// the shell), and starts a fresh shell in the captured working directory
+    /// with the scrollback replayed when the panel is visited again.
+    case shellRestart
+}
+
+/// One terminal panel as seen by the surface-lifecycle planner.
+struct SurfaceHibernationPlannerInput: Sendable {
+    let key: AgentHibernationPanelKey
+    /// nil when the panel must never be hibernated (deferred startup work,
+    /// remote PTY attach, tmux-bound, or queued input that suspension would drop).
+    let mechanism: SurfaceHibernationMechanism?
+    /// Whether the panel currently owns a live Ghostty runtime surface (or, for
+    /// agent panels, a live scoped process). Every live input counts toward the
+    /// global cap census even when it is exempt from eviction.
+    let isLive: Bool
+    /// Visible in the selected workspace's rendered layout.
+    let isProtected: Bool
+    /// The surface reports it is not safely at a shell prompt
+    /// (`needsConfirmClose`), e.g. a foreground process is running.
+    let isBusy: Bool
+    /// Agent lifecycle reported by hooks; `.unknown` for plain shells.
+    let lifecycle: AgentHibernationLifecycleState
+    let hasUnconfirmedTerminalInput: Bool
+    let lastActivityAt: TimeInterval
+    /// When the owning workspace last stopped rendering (unmounted), or nil
+    /// while it is mounted.
+    let workspaceUnmountedAt: TimeInterval?
+
+    init(
+        key: AgentHibernationPanelKey,
+        mechanism: SurfaceHibernationMechanism?,
+        isLive: Bool,
+        isProtected: Bool,
+        isBusy: Bool = false,
+        lifecycle: AgentHibernationLifecycleState = .unknown,
+        hasUnconfirmedTerminalInput: Bool = false,
+        lastActivityAt: TimeInterval,
+        workspaceUnmountedAt: TimeInterval? = nil
+    ) {
+        self.key = key
+        self.mechanism = mechanism
+        self.isLive = isLive
+        self.isProtected = isProtected
+        self.isBusy = isBusy
+        self.lifecycle = lifecycle
+        self.hasUnconfirmedTerminalInput = hasUnconfirmedTerminalInput
+        self.lastActivityAt = lastActivityAt
+        self.workspaceUnmountedAt = workspaceUnmountedAt
+    }
+}
+
+/// Pure selection policy for which live terminal surfaces to hibernate.
+///
+/// Three rules compose, and the result is their union:
+/// - Agent cap: live restorable-agent terminals above
+///   `AgentHibernationSettings.maxLiveTerminals`, oldest first.
+/// - Global LRU cap: live surfaces of any kind above
+///   `SurfaceHibernationSettings.maxLiveSurfaces`, oldest first. The census
+///   counts every live surface — including ones materialized by background
+///   priming or queued socket input — while only eligible ones are evicted.
+/// - Unmounted idle: surfaces whose workspace has been unmounted longer than
+///   `SurfaceHibernationSettings.unmountedIdleSeconds`, regardless of cap
+///   pressure.
+enum SurfaceHibernationPlanner {
+    static func selectedPanelKeys(
+        inputs: [SurfaceHibernationPlannerInput],
+        agentSettings: AgentHibernationSettings.Values,
+        surfaceSettings: SurfaceHibernationSettings.Values,
+        now: TimeInterval
+    ) -> Set<AgentHibernationPanelKey> {
+        // This mirrors the shipped AgentHibernationPlanner policy: only
+        // restorable-agent terminals are counted or evicted, and only under
+        // agent-cap pressure. Plain-shell surfaces are invisible to it, the
+        // global cap census does not exist, and workspaces unmounted for long
+        // periods keep every runtime surface alive
+        // (https://github.com/manaflow-ai/cmux/issues/5731).
+        guard agentSettings.enabled else { return [] }
+        let liveRestorable = inputs.filter { $0.mechanism == .agentResume && $0.isLive }
+        let excess = liveRestorable.count - agentSettings.maxLiveTerminals
+        guard excess > 0 else { return [] }
+
+        let eligible = liveRestorable
+            .filter { input in
+                !input.isProtected &&
+                    input.lifecycle.allowsHibernation &&
+                    !input.hasUnconfirmedTerminalInput &&
+                    now - input.lastActivityAt >= agentSettings.idleSeconds
+            }
+            .sorted(by: Self.leastRecentlyUsedFirst)
+
+        return Set(eligible.prefix(excess).map(\.key))
+    }
+
+    static func leastRecentlyUsedFirst(
+        _ lhs: SurfaceHibernationPlannerInput,
+        _ rhs: SurfaceHibernationPlannerInput
+    ) -> Bool {
+        if lhs.lastActivityAt == rhs.lastActivityAt {
+            return lhs.key.panelId.uuidString < rhs.key.panelId.uuidString
+        }
+        return lhs.lastActivityAt < rhs.lastActivityAt
+    }
+}

Sources/App/WorkspaceRuntimeSettings.swift

@@ -360,6 +360,135 @@ enum AgentHibernationSettings {
     }
 }
 
+enum SurfaceHibernationSettings {
+    struct Values: Equatable, Sendable {
+        var enabled: Bool
+        var idleSeconds: TimeInterval
+        var unmountedIdleSeconds: TimeInterval
+        var maxLiveSurfaces: Int
+        var confirmationSeconds: TimeInterval
+    }
+
+    static let enabledKey = "terminal.surfaceHibernation.enabled"
+    static let idleSecondsKey = "terminal.surfaceHibernation.idleSeconds"
+    static let unmountedIdleSecondsKey = "terminal.surfaceHibernation.unmountedIdleSeconds"
+    static let maxLiveSurfacesKey = "terminal.surfaceHibernation.maxLiveSurfaces"
+    static let confirmationSecondsKey = "terminal.surfaceHibernation.confirmationSeconds"
+
+    // Surface hibernation is on by default: it only reclaims surfaces that are
+    // safely at a shell prompt, restores scrollback and working directory on
+    // the next visit, and is the P0 backstop against unbounded per-workspace
+    // surface accumulation (https://github.com/manaflow-ai/cmux/issues/5731).
+    static let defaultEnabled = true
+    static let defaultIdleSeconds: TimeInterval = 300
+    static let defaultUnmountedIdleSeconds: TimeInterval = 1800
+    static let defaultMaxLiveSurfaces = 12
+    static let defaultConfirmationSeconds: TimeInterval = 60
+    static let didChangeNotification = Notification.Name("cmux.surfaceHibernationSettingsDidChange")
+
+    static func values(defaults: UserDefaults = .standard) -> Values {
+        Values(
+            enabled: isEnabled(defaults: defaults),
+            idleSeconds: idleSeconds(defaults: defaults),
+            unmountedIdleSeconds: unmountedIdleSeconds(defaults: defaults),
+            maxLiveSurfaces: maxLiveSurfaces(defaults: defaults),
+            confirmationSeconds: confirmationSeconds(defaults: defaults)
+        )
+    }
+
+    static func isEnabled(defaults: UserDefaults = .standard) -> Bool {
+        guard defaults.object(forKey: enabledKey) != nil else { return defaultEnabled }
+        return defaults.bool(forKey: enabledKey)
+    }
+
+    static func idleSeconds(defaults: UserDefaults = .standard) -> TimeInterval {
+        guard defaults.object(forKey: idleSecondsKey) != nil else { return defaultIdleSeconds }
+        return sanitizedIdleSeconds(defaults.double(forKey: idleSecondsKey))
+    }
+
+    static func unmountedIdleSeconds(defaults: UserDefaults = .standard) -> TimeInterval {
+        guard defaults.object(forKey: unmountedIdleSecondsKey) != nil else { return defaultUnmountedIdleSeconds }
+        return sanitizedUnmountedIdleSeconds(defaults.double(forKey: unmountedIdleSecondsKey))
+    }
+
+    static func maxLiveSurfaces(defaults: UserDefaults = .standard) -> Int {
+        guard defaults.object(forKey: maxLiveSurfacesKey) != nil else { return defaultMaxLiveSurfaces }
+        return sanitizedMaxLiveSurfaces(defaults.integer(forKey: maxLiveSurfacesKey))
+    }
+
+    static func confirmationSeconds(defaults: UserDefaults = .standard) -> TimeInterval {
+        guard defaults.object(forKey: confirmationSecondsKey) != nil else { return defaultConfirmationSeconds }
+        return sanitizedConfirmationSeconds(defaults.double(forKey: confirmationSecondsKey))
+    }
+
+    static func sanitizedIdleSeconds(_ value: TimeInterval) -> TimeInterval {
+        guard value.isFinite else { return defaultIdleSeconds }
+        return min(max(value.rounded(), 30), 7 * 24 * 60 * 60)
+    }
+
+    static func sanitizedUnmountedIdleSeconds(_ value: TimeInterval) -> TimeInterval {
+        guard value.isFinite else { return defaultUnmountedIdleSeconds }
+        return min(max(value.rounded(), 60), 30 * 24 * 60 * 60)
+    }
+
+    static func sanitizedMaxLiveSurfaces(_ value: Int) -> Int {
+        min(max(value, 1), 256)
+    }
+
+    static func sanitizedConfirmationSeconds(_ value: TimeInterval) -> TimeInterval {
+        guard value.isFinite else { return defaultConfirmationSeconds }
+        return min(max(value.rounded(), 5), 60 * 60)
+    }
+
+    static func setValues(
+        enabled: Bool? = nil,
+        idleSeconds: TimeInterval? = nil,
+        unmountedIdleSeconds: TimeInterval? = nil,
+        maxLiveSurfaces: Int? = nil,
+        defaults: UserDefaults = .standard,
+        notificationCenter: NotificationCenter = .default
+    ) {
+        let oldValues = values(defaults: defaults)
+        if let enabled {
+            defaults.set(enabled, forKey: enabledKey)
+        }
+        if let idleSeconds {
+            defaults.set(sanitizedIdleSeconds(idleSeconds), forKey: idleSecondsKey)
+        }
+        if let unmountedIdleSeconds {
+            defaults.set(sanitizedUnmountedIdleSeconds(unmountedIdleSeconds), forKey: unmountedIdleSecondsKey)
+        }
+        if let maxLiveSurfaces {
+            defaults.set(sanitizedMaxLiveSurfaces(maxLiveSurfaces), forKey: maxLiveSurfacesKey)
+        }
+        if oldValues != values(defaults: defaults) {
+            notifyDidChange(notificationCenter: notificationCenter)
+        }
+    }
+
+    @discardableResult
+    static func reset(
+        defaults: UserDefaults = .standard,
+        notificationCenter: NotificationCenter = .default
+    ) -> Bool {
+        let oldValues = values(defaults: defaults)
+        defaults.removeObject(forKey: enabledKey)
+        defaults.removeObject(forKey: idleSecondsKey)
+        defaults.removeObject(forKey: unmountedIdleSecondsKey)
+        defaults.removeObject(forKey: maxLiveSurfacesKey)
+        defaults.removeObject(forKey: confirmationSecondsKey)
+        let didChange = oldValues != values(defaults: defaults)
+        if didChange {
+            notifyDidChange(notificationCenter: notificationCenter)
+        }
+        return didChange
+    }
+
+    static func notifyDidChange(notificationCenter: NotificationCenter = .default) {
+        notificationCenter.post(name: didChangeNotification, object: nil)
+    }
+}
+
 enum AgentHibernationTrackingGate {
     private static let lock = NSLock()
     private static var enabled = AgentHibernationSettings.isEnabled()

cmux.xcodeproj/project.pbxproj

@@ -584,6 +584,8 @@
 		F6355600A1B2C3D4E5F60718 /* SSHStartupSignalLifecycleTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = F6355601A1B2C3D4E5F60718 /* SSHStartupSignalLifecycleTests.swift */; };
 		F20F85FC5900550685FA33AD /* StackAuth in Frameworks */ = {isa = PBXBuildFile; productRef = A8BD195031FC4B82B4354297 /* StackAuth */; };
 		D35B71010000000000000001 /* StartupBreadcrumbLog.swift in Sources */ = {isa = PBXBuildFile; fileRef = D35B71010000000000000002 /* StartupBreadcrumbLog.swift */; };
+		D36A00050000000000000001 /* SurfaceHibernationPolicy.swift in Sources */ = {isa = PBXBuildFile; fileRef = D36A00050000000000000002 /* SurfaceHibernationPolicy.swift */; };
+		D36A00060000000000000001 /* SurfaceHibernationPolicyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = D36A00060000000000000002 /* SurfaceHibernationPolicyTests.swift */; };
 		A5001303 /* SurfaceSearchOverlay.swift in Sources */ = {isa = PBXBuildFile; fileRef = A5001301 /* SurfaceSearchOverlay.swift */; };
 		C9A5720BC9A5720BC9A5720B /* TabItemView+WorkspaceGroups.swift in Sources */ = {isa = PBXBuildFile; fileRef = C9A5720CC9A5720CC9A5720C /* TabItemView+WorkspaceGroups.swift */; };
 		C3677003000000000000001 /* TabManager+CompatibilityTypes.swift in Sources */ = {isa = PBXBuildFile; fileRef = C3677003000000000000002 /* TabManager+CompatibilityTypes.swift */; };
@@ -1310,6 +1312,8 @@
 		E3309A0E /* SplitEqualizer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SplitEqualizer.swift; sourceTree = "<group>"; };
 		F6355601A1B2C3D4E5F60718 /* SSHStartupSignalLifecycleTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SSHStartupSignalLifecycleTests.swift; sourceTree = "<group>"; };
 		D35B71010000000000000002 /* StartupBreadcrumbLog.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = App/StartupBreadcrumbLog.swift; sourceTree = "<group>"; };
+		D36A00050000000000000002 /* SurfaceHibernationPolicy.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = App/SurfaceHibernationPolicy.swift; sourceTree = "<group>"; };
+		D36A00060000000000000002 /* SurfaceHibernationPolicyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SurfaceHibernationPolicyTests.swift; sourceTree = "<group>"; };
 		A5001301 /* SurfaceSearchOverlay.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Find/SurfaceSearchOverlay.swift; sourceTree = "<group>"; };
 		C9A5720CC9A5720CC9A5720C /* TabItemView+WorkspaceGroups.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "TabItemView+WorkspaceGroups.swift"; sourceTree = "<group>"; };
 		C3677003000000000000002 /* TabManager+CompatibilityTypes.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "TabManager+CompatibilityTypes.swift"; sourceTree = "<group>"; };
@@ -1699,6 +1703,7 @@
 				C0DE32470000000000000002 /* ContentViewIdentifierCopyCommands.swift */,
 				9960CC3992F3C44489E7627C /* WorkspaceRuntimeSettings.swift */,
 				D36A00010000000000000002 /* AgentHibernationController.swift */,
+				D36A00050000000000000002 /* SurfaceHibernationPolicy.swift */,
 				243632BA1DBBA36FD46E0610 /* SidebarAppearanceSupport.swift */,
 				D50D9BCE46701FBA91C2EFB6 /* SidebarWorkspaceSnapshotRefreshPolicy.swift */,
 				D35450020000000000000002 /* SidebarWorkspaceRowHoverTracker.swift */,
@@ -2107,6 +2112,7 @@
 				A9E050000000000000000001 /* AgentSessionWebRendererTests.swift */,
 				A9E040000000000000000001 /* CodexAppServerSessionTests.swift */,
 				D36A00020000000000000002 /* AgentHibernationTests.swift */,
+				D36A00060000000000000002 /* SurfaceHibernationPolicyTests.swift */,
 				F5410001A1B2C3D4E5F60718 /* RestorableAgentHookProviderResumeTests.swift */,
 				F5410005A1B2C3D4E5F60718 /* RestorableAgentHookProviderHermesTests.swift */,
 				F5410003A1B2C3D4E5F60718 /* RestorableAgentNonInteractiveTests.swift */,
@@ -2974,6 +2980,7 @@
 				A5001226 /* SocketControlMode+Display.swift in Sources */,
 				E3309A0D /* SplitEqualizer.swift in Sources */,
 				D35B71010000000000000001 /* StartupBreadcrumbLog.swift in Sources */,
+				D36A00050000000000000001 /* SurfaceHibernationPolicy.swift in Sources */,
 				A5001303 /* SurfaceSearchOverlay.swift in Sources */,
 				C9A5720BC9A5720BC9A5720B /* TabItemView+WorkspaceGroups.swift in Sources */,
 				C3677003000000000000001 /* TabManager+CompatibilityTypes.swift in Sources */,
@@ -3295,6 +3302,7 @@
 				62270F3DCECB4787D789CCE3 /* SidebarWorkspaceSnapshotRefreshPolicyTests.swift in Sources */,
 				F8000000A1B2C3D4E5F60718 /* SocketControlPasswordStoreTests.swift in Sources */,
 				F6355600A1B2C3D4E5F60718 /* SSHStartupSignalLifecycleTests.swift in Sources */,
+				D36A00060000000000000001 /* SurfaceHibernationPolicyTests.swift in Sources */,
 				2BB56A710BB1FC50367E5BCF /* TabManagerSessionSnapshotTests.swift in Sources */,
 				B6BF3DC98DB1495E57900199 /* TabManagerUnitTests.swift in Sources */,
 				C7A507000000000000000002 /* TaskManagerResourcesTests.swift in Sources */,