From e040e52a13d535949525472f2132781660495c4e Mon Sep 17 00:00:00 2001 From: Leo Li Date: Mon, 28 Sep 2026 02:32:24 -0700 Subject: [PATCH 1/2] Describe memory-pressure hibernation the way it works With routine Agent Hibernation off, cmux still hibernates safe idle agents under memory pressure. The docs, config schema and settings subtitle said this happens only under critical pressure and in a bounded batch ("at most two"). The planner actually takes every eligible agent, and the aggregate lane also fires at cmux's own warning threshold (50% of physical memory). Co-Authored-By: Claude Opus 5.5 (1M context) --- .../CmuxConfigSchema.generated.swift | 4 ++-- .../Sections/TerminalSection.swift | 2 +- Resources/Localizable.xcstrings | 18 +++++++++--------- docs/agent-hooks.md | 6 +++--- skills/cmux-settings/references/all-keys.md | 2 +- web/data/cmux.schema.json | 4 ++-- web/messages/en.json | 4 ++-- web/messages/ja.json | 4 ++-- 8 files changed, 22 insertions(+), 22 deletions(-) diff --git a/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift b/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift index 7f7dbd58016c..5348b710b702 100644 --- a/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift +++ b/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift @@ -824,13 +824,13 @@ enum CmuxEmbeddedConfigSchema { "type": "object", "additionalProperties": false, "descriptionKey": "schemaDescriptions.terminal.agentHibernation", - "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, during critical memory pressure cmux may hibernate a bounded batch of safe idle background agents even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", + "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", "properties": { "enabled": { "type": "boolean", "default": false, "descriptionKey": "schemaDescriptions.terminal.agentHibernationEnabled", - "description": "Enable routine Agent Hibernation based on the live-terminal limit. Critical-pressure safety hibernation remains active when false." + "description": "Enable routine Agent Hibernation based on the live-terminal limit. Memory-pressure safety hibernation remains active when false." }, "idleSeconds": { "type": "integer", diff --git a/Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/TerminalSection.swift b/Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/TerminalSection.swift index 42e12284603b..e12305a01ffa 100644 --- a/Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/TerminalSection.swift +++ b/Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/TerminalSection.swift @@ -501,7 +501,7 @@ public struct TerminalSection: View { SettingsCardRow( configurationReview: .json("terminal.agentHibernation.enabled"), String(localized: "settings.terminal.agentHibernation", defaultValue: "Agent Hibernation"), - subtitle: String(localized: "settings.terminal.agentHibernation.subtitle", defaultValue: "Hibernates idle background agent terminals above the live terminal limit. Even when this is off, cmux may hibernate them under critical memory pressure.") + subtitle: String(localized: "settings.terminal.agentHibernation.subtitle", defaultValue: "Hibernates idle background agent terminals above the live terminal limit. Even when this is off, cmux may hibernate them under memory pressure.") ) { Toggle("", isOn: Binding(get: { hibernation.current }, set: { hibernation.set($0) })) .labelsHidden() diff --git a/Resources/Localizable.xcstrings b/Resources/Localizable.xcstrings index d3988de233d7..c324cc7c4546 100644 --- a/Resources/Localizable.xcstrings +++ b/Resources/Localizable.xcstrings @@ -554995,55 +554995,55 @@ "en": { "stringUnit": { "state": "translated", - "value": "Hibernates idle background agent terminals above the live terminal limit. Even when this is off, cmux may hibernate them under critical memory pressure." + "value": "Hibernates idle background agent terminals above the live terminal limit. Even when this is off, cmux may hibernate them under memory pressure." } }, "de": { "stringUnit": { "state": "translated", - "value": "Versetzt inaktive Agenten-Terminals im Hintergrund in den Ruhezustand, sobald das Limit für aktive Terminals überschritten ist. Auch wenn diese Option deaktiviert ist, kann cmux sie bei kritischer Speicherauslastung in den Ruhezustand versetzen." + "value": "Versetzt inaktive Agenten-Terminals im Hintergrund in den Ruhezustand, sobald das Limit für aktive Terminals überschritten ist. Auch wenn diese Option deaktiviert ist, kann cmux sie bei hoher Speicherauslastung in den Ruhezustand versetzen." } }, "fr": { "stringUnit": { "state": "translated", - "value": "Met en hibernation les terminaux d’agent inactifs en arrière-plan au-delà de la limite de terminaux actifs. Même si cette option est désactivée, cmux peut les mettre en hibernation en cas de pression mémoire critique." + "value": "Met en hibernation les terminaux d’agent inactifs en arrière-plan au-delà de la limite de terminaux actifs. Même si cette option est désactivée, cmux peut les mettre en hibernation en cas de pression mémoire." } }, "ar": { "stringUnit": { "state": "translated", - "value": "يُدخل طرفيات الوكلاء الخاملة في الخلفية في السبات عند تجاوز حد الطرفيات النشطة. وحتى عند إيقاف هذا الخيار، قد يُدخلها cmux في السبات عند ضغط الذاكرة الحرج." + "value": "يُدخل طرفيات الوكلاء الخاملة في الخلفية في السبات عند تجاوز حد الطرفيات النشطة. وحتى عند إيقاف هذا الخيار، قد يُدخلها cmux في السبات عند ضغط الذاكرة." } }, "es": { "stringUnit": { "state": "translated", - "value": "Pone en hibernación las terminales de agentes inactivas en segundo plano que superan el límite de terminales activas. Aunque esta opción esté desactivada, cmux puede ponerlas en hibernación si la presión de memoria es crítica." + "value": "Pone en hibernación las terminales de agentes inactivas en segundo plano que superan el límite de terminales activas. Aunque esta opción esté desactivada, cmux puede ponerlas en hibernación si hay presión de memoria." } }, "zh-Hant": { "stringUnit": { "state": "translated", - "value": "作用中終端機超過上限時，閒置的背景代理終端機會進入休眠。即使關閉此選項，cmux 仍可能在記憶體壓力達到嚴重程度時讓它們休眠。" + "value": "作用中終端機超過上限時，閒置的背景代理終端機會進入休眠。即使關閉此選項，cmux 仍可能在記憶體吃緊時讓它們休眠。" } }, "zh-Hans": { "stringUnit": { "state": "translated", - "value": "活动终端超过上限时，空闲的后台代理终端会进入休眠。即使关闭此选项，cmux 仍可能在内存压力达到严重程度时让它们休眠。" + "value": "活动终端超过上限时，空闲的后台代理终端会进入休眠。即使关闭此选项，cmux 仍可能在内存紧张时让它们休眠。" } }, "ko": { "stringUnit": { "state": "translated", - "value": "활성 터미널 수가 한도를 넘으면 백그라운드에서 유휴 상태인 에이전트 터미널을 최대 절전 모드로 전환합니다. 이 옵션을 꺼도 메모리 압박이 심각하면 cmux가 해당 터미널을 최대 절전 모드로 전환할 수 있습니다." + "value": "활성 터미널 수가 한도를 넘으면 백그라운드에서 유휴 상태인 에이전트 터미널을 최대 절전 모드로 전환합니다. 이 옵션을 꺼도 메모리가 부족하면 cmux가 해당 터미널을 최대 절전 모드로 전환할 수 있습니다." } }, "ja": { "stringUnit": { "state": "translated", - "value": "実行中のターミナル数が上限を超えると、アイドル状態のバックグラウンドエージェントのターミナルを休止させます。この設定がオフでも、メモリ逼迫が深刻な場合は cmux がこれらを休止させることがあります。" + "value": "実行中のターミナル数が上限を超えると、アイドル状態のバックグラウンドエージェントのターミナルを休止させます。この設定がオフでも、メモリが逼迫している場合は cmux がこれらを休止させることがあります。" } } } diff --git a/docs/agent-hooks.md b/docs/agent-hooks.md index 3e6665c31105..38cee1d48e0a 100644 --- a/docs/agent-hooks.md +++ b/docs/agent-hooks.md @@ -73,7 +73,7 @@ When the opt-in `automation.workspaceAutoNaming` setting is enabled, turn-end ho ## Agent Hibernation -Agent Hibernation kills idle background agent processes to free their RAM and CPU, then resumes each one with its saved session when you return to its tab. Routine hibernation based on the live-terminal limit is opt-in and off by default. A separate bounded safety path remains active for critical system memory pressure. cmux knows which process belongs to which terminal because the agent hooks associate each session ID with its surface (see the session-restore section above), so it can terminate the right process and bring back the right session. +Agent Hibernation kills idle background agent processes to free their RAM and CPU, then resumes each one with its saved session when you return to its tab. Routine hibernation based on the live-terminal limit is opt-in and off by default. A separate safety path remains active under memory pressure, even when routine hibernation is off. cmux knows which process belongs to which terminal because the agent hooks associate each session ID with its surface (see the session-restore section above), so it can terminate the right process and bring back the right session. ### When a terminal hibernates @@ -91,9 +91,9 @@ Before killing, cmux watches the terminal tail. It samples the last lines of out So with the defaults, routine hibernation only affects power users running more than 12 agents at once, and even then only ~1 minute after an agent has gone quiet off-screen. -### Critical memory pressure +### Memory pressure -When macOS reports critical memory pressure, cmux can run the same protected teardown path independently of the `enabled` setting and live-terminal limit. Each pass selects at most two of the oldest eligible background agents. The agent must still be restorable, off-screen, explicitly idle, free of unconfirmed input, stable through the confirmation window, and backed by a transcript cmux can protect. Visible, running, needs-input, recently changed, or unprotectable agents are never selected. Before signaling anything, cmux revalidates the exact process generation and workspace/surface scope. +Under memory pressure, cmux can run the same protected teardown path independently of the `enabled` setting and live-terminal limit. Two signals trigger it: macOS reporting critical memory pressure, and cmux's own memory use (the cmux process and its descendants) passing its aggregate warning threshold, 50% of physical memory (see [configuration.md](configuration.md#aggregate-memory-pressure-safety-policy)). Each pass considers every eligible background agent; the live-terminal limit does not apply. The agent must still be restorable, off-screen, explicitly idle, free of unconfirmed input, stable through the confirmation window, and backed by a transcript cmux can protect. Visible, running, needs-input, recently changed, or unprotectable agents are never selected. Before signaling anything, cmux revalidates the exact process generation and workspace/surface scope. ### What gets killed and how it comes back diff --git a/skills/cmux-settings/references/all-keys.md b/skills/cmux-settings/references/all-keys.md index 41f305c055e0..bdce74128ae1 100644 --- a/skills/cmux-settings/references/all-keys.md +++ b/skills/cmux-settings/references/all-keys.md @@ -64,7 +64,7 @@ Terminal presentation settings from Settings > Terminal. | `terminal.showPasswordInputDots` | boolean | `false` | When the password input badge is shown, also draw one dot per typed character. cmux keeps only a count, never the typed characters. Backspace removes a dot; Enter or echo turning back on clears them. Pasted text is not counted. | | `terminal.showTextBoxOnNewTerminals` | boolean | `false` | Show the beta TextBox input by default for newly created workspaces, terminal tabs, and terminal splits. | | `terminal.focusTextBoxOnNewTerminals` | boolean | `false` | Focus the beta TextBox input by default for newly created workspaces, terminal tabs, and terminal splits. Focusing also shows the TextBox. | -| `terminal.agentHibernation` | object | — | Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, during critical memory pressure cmux may hibernate a bounded batch of safe idle background agents even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback. | +| `terminal.agentHibernation` | object | — | Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback. | | `terminal.rendererRealization` | object | — | Reclaim off-screen terminal GPU renderer memory. cmux releases the Metal renderer (IOSurface) of a terminal that has stayed off-screen and idle while keeping its process and terminal state alive, then rebuilds the renderer instantly when the tab is visited again. Non-destructive and on by default. | | `terminal.textBoxMaxLines` | integer | `10` | Maximum number of lines the rich terminal TextBox input can grow to before it scrolls. | | `terminal.textBoxDefaultSubmitAction` | string | `"text-entry"` | Default TextBox submit action ID for new terminal sessions. Use text-entry for plain input or one of the configured action IDs. | diff --git a/web/data/cmux.schema.json b/web/data/cmux.schema.json index e4cbc00a5412..171820157668 100644 --- a/web/data/cmux.schema.json +++ b/web/data/cmux.schema.json @@ -814,13 +814,13 @@ "type": "object", "additionalProperties": false, "descriptionKey": "schemaDescriptions.terminal.agentHibernation", - "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, during critical memory pressure cmux may hibernate a bounded batch of safe idle background agents even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", + "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", "properties": { "enabled": { "type": "boolean", "default": false, "descriptionKey": "schemaDescriptions.terminal.agentHibernationEnabled", - "description": "Enable routine Agent Hibernation based on the live-terminal limit. Critical-pressure safety hibernation remains active when false." + "description": "Enable routine Agent Hibernation based on the live-terminal limit. Memory-pressure safety hibernation remains active when false." }, "idleSeconds": { "type": "integer", diff --git a/web/messages/en.json b/web/messages/en.json index 166ff7f24b40..97c09178ee2b 100644 --- a/web/messages/en.json +++ b/web/messages/en.json @@ -2585,8 +2585,8 @@ }, "terminal": { "adaptiveDefaultTheme": "When true (the default), cmux supplies an appearance-adaptive default palette unless a Ghostty theme or terminal colors are configured. Font and other settings are preserved. When false, Ghostty uses its fixed built-in palette. Explicit themes and colors always take precedence, including theme = light:X,dark:Y.", - "agentHibernation": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, during critical memory pressure cmux may hibernate a bounded batch of safe idle background agents even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", - "agentHibernationEnabled": "Enable routine Agent Hibernation based on the live-terminal limit. Critical-pressure safety hibernation remains active when false.", + "agentHibernation": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", + "agentHibernationEnabled": "Enable routine Agent Hibernation based on the live-terminal limit. Memory-pressure safety hibernation remains active when false.", "copyOnSelect": "When true, copy selected terminal text to the system clipboard when the selection is committed. When false, cmux does not emit a Ghostty copy-on-select override; Ghostty config and defaults control selection-clipboard behavior.", "scrollSpeed": "Scales how far the terminal moves for each mouse-wheel or trackpad scroll event. Values above 1 speed scrolling up and values below 1 slow it down.", "sessionContentMaxWidth": "Optional maximum width, in points, for terminal and built-in agent chat content. Set false to use the full pane width.", diff --git a/web/messages/ja.json b/web/messages/ja.json index c24b4250780b..6f5f69eca220 100644 --- a/web/messages/ja.json +++ b/web/messages/ja.json @@ -2508,8 +2508,8 @@ }, "terminal": { "adaptiveDefaultTheme": "true（既定）の場合、Ghostty のテーマやターミナルの色が設定されていなければ、外観に追従する既定のパレットを適用します。フォントなどの設定は保持されます。false の場合は Ghostty の固定された組み込みパレットを使用します。theme = light:X,dark:Y を含め、明示的なテーマと色の設定が常に優先されます。", - "agentHibernation": "通常のエージェント休止の設定です。cmux はアイドル中のバックグラウンドエージェントプロセスを終了して RAM と CPU を解放し、そのタブを開いたときに保存済みセッションから再開します。通常の休止には、再開可能なコーディングエージェントであること、ライフサイクルがアイドルと報告していること、ターミナルが画面外にあること、ライブターミナル数が設定上限を超えていること、アイドル時間と確認時間を通して出力が変化していないことが必要です。これとは別に、メモリ負荷が危険な状態では enabled が false でも、安全なアイドル中のバックグラウンドエージェントを cmux が上限付きのバッチで休止する場合があります。表示中、実行中、入力待ち、最近変更された、またはトランスクリプトを保護できないエージェントは対象外です。プレースホルダーの「再開」ボタンは手動の代替手段です。", - "agentHibernationEnabled": "ライブターミナル数の上限に基づく通常のエージェント休止を有効にします。false の場合も、メモリ負荷が危険な状態での安全休止は有効です。", + "agentHibernation": "通常のエージェント休止の設定です。cmux はアイドル中のバックグラウンドエージェントプロセスを終了して RAM と CPU を解放し、そのタブを開いたときに保存済みセッションから再開します。通常の休止には、再開可能なコーディングエージェントであること、ライフサイクルがアイドルと報告していること、ターミナルが画面外にあること、ライブターミナル数が設定上限を超えていること、アイドル時間と確認時間を通して出力が変化していないことが必要です。これとは別に、メモリ負荷が高い状態（macOS のメモリ負荷が危険な状態、または cmux 自身のメモリ使用量が集計警告しきい値を超えた状態）では、enabled が false でも、安全なアイドル中のバックグラウンドエージェントをすべて cmux が休止する場合があります。表示中、実行中、入力待ち、最近変更された、またはトランスクリプトを保護できないエージェントは対象外です。プレースホルダーの「再開」ボタンは手動の代替手段です。", + "agentHibernationEnabled": "ライブターミナル数の上限に基づく通常のエージェント休止を有効にします。false の場合も、メモリ負荷時の安全休止は有効です。", "copyOnSelect": "true の場合、選択が確定したときにターミナルで選択したテキストをシステムクリップボードへコピーします。false の場合、cmux は Ghostty の copy-on-select 上書きを出力せず、選択クリップボードの動作は Ghostty の設定と既定値に従います。", "scrollSpeed": "マウスホイールやトラックパッドのスクロールイベント 1 回あたりにターミナルが移動する量を調整します。1 より大きい値でスクロールが速くなり、1 より小さい値で遅くなります。", "sessionContentMaxWidth": "ターミナルと組み込みエージェントチャットのコンテンツ幅の上限をポイント単位で指定します。ペインの全幅を使うには false を設定します。", From f7197b8c041357f8538f725bc2a22e6bb85b3af9 Mon Sep 17 00:00:00 2001 From: Leo Li Date: Mon, 28 Sep 2026 02:36:06 -0700 Subject: [PATCH 2/2] Name every memory-pressure trigger in the hibernation docs Critical pressure also comes from the cmux app's own footprint (16 GiB), not only from macOS. Review follow-up. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../ConfigValidation/CmuxConfigSchema.generated.swift | 2 +- docs/agent-hooks.md | 2 +- docs/configuration.md | 5 +++-- skills/cmux-settings/references/all-keys.md | 2 +- web/data/cmux.schema.json | 2 +- web/messages/en.json | 2 +- web/messages/ja.json | 2 +- 7 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift b/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift index 5348b710b702..fbb518b1f525 100644 --- a/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift +++ b/Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift @@ -824,7 +824,7 @@ enum CmuxEmbeddedConfigSchema { "type": "object", "additionalProperties": false, "descriptionKey": "schemaDescriptions.terminal.agentHibernation", - "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", + "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical pressure from macOS or from the cmux app's own footprint, or cmux's total memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", "properties": { "enabled": { "type": "boolean", diff --git a/docs/agent-hooks.md b/docs/agent-hooks.md index 38cee1d48e0a..0dd5c19625e0 100644 --- a/docs/agent-hooks.md +++ b/docs/agent-hooks.md @@ -93,7 +93,7 @@ So with the defaults, routine hibernation only affects power users running more ### Memory pressure -Under memory pressure, cmux can run the same protected teardown path independently of the `enabled` setting and live-terminal limit. Two signals trigger it: macOS reporting critical memory pressure, and cmux's own memory use (the cmux process and its descendants) passing its aggregate warning threshold, 50% of physical memory (see [configuration.md](configuration.md#aggregate-memory-pressure-safety-policy)). Each pass considers every eligible background agent; the live-terminal limit does not apply. The agent must still be restorable, off-screen, explicitly idle, free of unconfirmed input, stable through the confirmation window, and backed by a transcript cmux can protect. Visible, running, needs-input, recently changed, or unprotectable agents are never selected. Before signaling anything, cmux revalidates the exact process generation and workspace/surface scope. +Under memory pressure, cmux can run the same protected teardown path independently of the `enabled` setting and live-terminal limit. It runs on critical memory pressure (macOS reports critical pressure, which cmux holds for 120 s, or the cmux app process's own footprint reaches 16 GiB), and when cmux's total memory use (the cmux process and its descendants) passes its aggregate warning threshold, 50% of physical memory (see [configuration.md](configuration.md#aggregate-memory-pressure-safety-policy)). Each pass considers every eligible background agent; the live-terminal limit does not apply. The agent must still be restorable, off-screen, explicitly idle, free of unconfirmed input, stable through the confirmation window, and backed by a transcript cmux can protect. Visible, running, needs-input, recently changed, or unprotectable agents are never selected. Before signaling anything, cmux revalidates the exact process generation and workspace/surface scope. ### What gets killed and how it comes back diff --git a/docs/configuration.md b/docs/configuration.md index 6ddcaddd4422..80eea620fb68 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -117,8 +117,9 @@ Default: `right`. Routine Agent Hibernation is opt-in. cmux hibernates idle background agent processes to free RAM and CPU, then resumes each one with its saved session -when you visit its tab. Independently, aggregate memory pressure can offer the -same lossless hibernation lifecycle even when routine hibernation is disabled. +when you visit its tab. Independently, memory pressure (critical system pressure, +or aggregate pressure below) can use the same lossless hibernation lifecycle even +when routine hibernation is disabled. See [agent-hooks.md](agent-hooks.md#agent-hibernation) for the full eligibility rules, confirmation settle window, and resume behavior. diff --git a/skills/cmux-settings/references/all-keys.md b/skills/cmux-settings/references/all-keys.md index bdce74128ae1..2f36bbb7aa07 100644 --- a/skills/cmux-settings/references/all-keys.md +++ b/skills/cmux-settings/references/all-keys.md @@ -64,7 +64,7 @@ Terminal presentation settings from Settings > Terminal. | `terminal.showPasswordInputDots` | boolean | `false` | When the password input badge is shown, also draw one dot per typed character. cmux keeps only a count, never the typed characters. Backspace removes a dot; Enter or echo turning back on clears them. Pasted text is not counted. | | `terminal.showTextBoxOnNewTerminals` | boolean | `false` | Show the beta TextBox input by default for newly created workspaces, terminal tabs, and terminal splits. | | `terminal.focusTextBoxOnNewTerminals` | boolean | `false` | Focus the beta TextBox input by default for newly created workspaces, terminal tabs, and terminal splits. Focusing also shows the TextBox. | -| `terminal.agentHibernation` | object | — | Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback. | +| `terminal.agentHibernation` | object | — | Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical pressure from macOS or from the cmux app's own footprint, or cmux's total memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback. | | `terminal.rendererRealization` | object | — | Reclaim off-screen terminal GPU renderer memory. cmux releases the Metal renderer (IOSurface) of a terminal that has stayed off-screen and idle while keeping its process and terminal state alive, then rebuilds the renderer instantly when the tab is visited again. Non-destructive and on by default. | | `terminal.textBoxMaxLines` | integer | `10` | Maximum number of lines the rich terminal TextBox input can grow to before it scrolls. | | `terminal.textBoxDefaultSubmitAction` | string | `"text-entry"` | Default TextBox submit action ID for new terminal sessions. Use text-entry for plain input or one of the configured action IDs. | diff --git a/web/data/cmux.schema.json b/web/data/cmux.schema.json index 171820157668..f4340c3deebf 100644 --- a/web/data/cmux.schema.json +++ b/web/data/cmux.schema.json @@ -814,7 +814,7 @@ "type": "object", "additionalProperties": false, "descriptionKey": "schemaDescriptions.terminal.agentHibernation", - "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", + "description": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical pressure from macOS or from the cmux app's own footprint, or cmux's total memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", "properties": { "enabled": { "type": "boolean", diff --git a/web/messages/en.json b/web/messages/en.json index 97c09178ee2b..3584b416529e 100644 --- a/web/messages/en.json +++ b/web/messages/en.json @@ -2585,7 +2585,7 @@ }, "terminal": { "adaptiveDefaultTheme": "When true (the default), cmux supplies an appearance-adaptive default palette unless a Ghostty theme or terminal colors are configured. Font and other settings are preserved. When false, Ghostty uses its fixed built-in palette. Explicit themes and colors always take precedence, including theme = light:X,dark:Y.", - "agentHibernation": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical macOS memory pressure, or cmux's own memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", + "agentHibernation": "Routine Agent Hibernation settings. cmux kills idle background agent processes to free RAM and CPU, then resumes them with their saved session when their tab is visited. Routine hibernation requires a restorable coding agent whose lifecycle reports idle, an off-screen terminal, a live-terminal count above the configured limit, and unchanged output through the idle and confirmation windows. Independently, under memory pressure (critical pressure from macOS or from the cmux app's own footprint, or cmux's total memory use past its aggregate warning threshold) cmux may hibernate every safe idle background agent even when enabled is false; visible, running, needs-input, recently changed, and unprotectable agents remain excluded. The placeholder Resume button is a manual fallback.", "agentHibernationEnabled": "Enable routine Agent Hibernation based on the live-terminal limit. Memory-pressure safety hibernation remains active when false.", "copyOnSelect": "When true, copy selected terminal text to the system clipboard when the selection is committed. When false, cmux does not emit a Ghostty copy-on-select override; Ghostty config and defaults control selection-clipboard behavior.", "scrollSpeed": "Scales how far the terminal moves for each mouse-wheel or trackpad scroll event. Values above 1 speed scrolling up and values below 1 slow it down.", diff --git a/web/messages/ja.json b/web/messages/ja.json index 6f5f69eca220..4fb851f951ae 100644 --- a/web/messages/ja.json +++ b/web/messages/ja.json @@ -2508,7 +2508,7 @@ }, "terminal": { "adaptiveDefaultTheme": "true（既定）の場合、Ghostty のテーマやターミナルの色が設定されていなければ、外観に追従する既定のパレットを適用します。フォントなどの設定は保持されます。false の場合は Ghostty の固定された組み込みパレットを使用します。theme = light:X,dark:Y を含め、明示的なテーマと色の設定が常に優先されます。", - "agentHibernation": "通常のエージェント休止の設定です。cmux はアイドル中のバックグラウンドエージェントプロセスを終了して RAM と CPU を解放し、そのタブを開いたときに保存済みセッションから再開します。通常の休止には、再開可能なコーディングエージェントであること、ライフサイクルがアイドルと報告していること、ターミナルが画面外にあること、ライブターミナル数が設定上限を超えていること、アイドル時間と確認時間を通して出力が変化していないことが必要です。これとは別に、メモリ負荷が高い状態（macOS のメモリ負荷が危険な状態、または cmux 自身のメモリ使用量が集計警告しきい値を超えた状態）では、enabled が false でも、安全なアイドル中のバックグラウンドエージェントをすべて cmux が休止する場合があります。表示中、実行中、入力待ち、最近変更された、またはトランスクリプトを保護できないエージェントは対象外です。プレースホルダーの「再開」ボタンは手動の代替手段です。", + "agentHibernation": "通常のエージェント休止の設定です。cmux はアイドル中のバックグラウンドエージェントプロセスを終了して RAM と CPU を解放し、そのタブを開いたときに保存済みセッションから再開します。通常の休止には、再開可能なコーディングエージェントであること、ライフサイクルがアイドルと報告していること、ターミナルが画面外にあること、ライブターミナル数が設定上限を超えていること、アイドル時間と確認時間を通して出力が変化していないことが必要です。これとは別に、メモリ負荷が高い状態（macOS または cmux アプリ自身のメモリ使用量によるメモリ負荷が危険な状態、あるいは cmux 全体のメモリ使用量が集計警告しきい値を超えた状態）では、enabled が false でも、cmux が安全なアイドル中のバックグラウンドエージェントをすべて休止する場合があります。表示中、実行中、入力待ち、最近変更された、またはトランスクリプトを保護できないエージェントは対象外です。プレースホルダーの「再開」ボタンは手動の代替手段です。", "agentHibernationEnabled": "ライブターミナル数の上限に基づく通常のエージェント休止を有効にします。false の場合も、メモリ負荷時の安全休止は有効です。", "copyOnSelect": "true の場合、選択が確定したときにターミナルで選択したテキストをシステムクリップボードへコピーします。false の場合、cmux は Ghostty の copy-on-select 上書きを出力せず、選択クリップボードの動作は Ghostty の設定と既定値に従います。", "scrollSpeed": "マウスホイールやトラックパッドのスクロールイベント 1 回あたりにターミナルが移動する量を調整します。1 より大きい値でスクロールが速くなり、1 より小さい値で遅くなります。",