Skip to content
Closed
Show file tree
Hide file tree
Changes from 22 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
fdefc51
Hibernation: make notification lifecycle correct for all agent types …
lawrencecchen Jun 24, 2026
abf33a1
Hibernation: per-evaluation observability so non-hibernation is never…
lawrencecchen Jun 24, 2026
57b8c38
Hibernation: gate persisted lifecycle for nonblocking notifications
lawrencecchen Jun 24, 2026
9afdd6b
Hibernation: route copilot/codebuddy/factory Notification to notifica…
lawrencecchen Jun 24, 2026
deb7af2
Hibernation: make classifier package-testable + guard DEBUG-only logs
lawrencecchen Jun 24, 2026
15a274a
Hibernation: classifier as package type + Swift Testing suite
lawrencecchen Jun 24, 2026
1052a1e
Hibernation: classifier as instantiable value type (package-conventio…
lawrencecchen Jun 24, 2026
56bb289
Hibernation: require a recorded transcript path for the claude restor…
lawrencecchen Jun 24, 2026
f5857ff
Hibernation: keep claude restorability fail-closed (diagnostic only)
lawrencecchen Jun 24, 2026
6d2072c
Hibernation: deterministic planner unit test + all-agent-types coverage
lawrencecchen Jun 24, 2026
ed339fb
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen Jul 1, 2026
64a4820
ci: isolate heavy WKWebView BrowserSessionHistoryRestoreTests as a fo…
lawrencecchen Jul 1, 2026
37d6676
ci: focused-gate AgentHibernationPlannerTests to keep shard compositi…
lawrencecchen Jul 1, 2026
e6580b2
test: pin claude background-work detection (red)
lawrencecchen Jul 1, 2026
cf9ccee
fix: keep claude panes with live background work out of hibernation
lawrencecchen Jul 1, 2026
366889c
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen Jul 1, 2026
565e197
fix: treat genuine question prompts as hibernation-blocking
lawrencecchen Jul 1, 2026
fb7c61e
chore: satisfy Aziz package policy (docs + file-scope helpers)
lawrencecchen Jul 1, 2026
395b5b8
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen Jul 2, 2026
b0d05e7
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen Jul 2, 2026
3d3cc47
fix: claude Stop status pill shows Running while background work is live
lawrencecchen Jul 2, 2026
157ef0a
fix: blocking questions beat completion cues; malformed payloads fail…
lawrencecchen Jul 2, 2026
81badf1
chore: fold field-parse helper struct into a file-scope function
lawrencecchen Jul 2, 2026
9de2730
Merge origin/main (PR #7129 notify gating) into feat-hibernation-all-…
lawrencecchen Jul 3, 2026
f837b8d
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen Jul 3, 2026
454483b
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen Jul 4, 2026
2ed1744
perf: gate the per-record hibernation restorability debug log
lawrencecchen Jul 4, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/swift-file-length-budget.tsv
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 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.
34427 CLI/cmux.swift
34522 CLI/cmux.swift
17978 Sources/AppDelegate.swift
16487 Sources/ContentView.swift
14224 Sources/TerminalController.swift
Expand Down Expand Up @@ -46,7 +46,7 @@
2126 cmuxTests/CmuxConfigTests.swift
2085 cmuxTests/ShortcutAndCommandPaletteTests.swift
2078 Sources/SessionPersistence.swift
1966 Sources/RestorableAgentSession.swift
2000 Sources/RestorableAgentSession.swift
1952 Sources/KeyboardShortcutSettingsFileStore.swift
1900 cmuxTests/NotificationAndMenuBarTests.swift
1866 Sources/Panels/BrowserWebAuthnSupport.swift
Expand Down Expand Up @@ -121,7 +121,7 @@
803 Packages/iOS/CmuxMobilePairedMac/Sources/CmuxMobilePairedMac/MobilePairedMacStore.swift
797 Sources/ClosedItemHistory.swift
793 Sources/TerminalController+ControlPaneContext.swift
782 CLI/CMUXCLI+AgentHookDefinitions.swift
795 CLI/CMUXCLI+AgentHookDefinitions.swift
779 cmuxUITests/BrowserOmnibarSuggestionsUITests.swift
773 Sources/App/MenuBarExtraController.swift
769 Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Input.swift
Expand Down
20 changes: 20 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -524,6 +524,26 @@ jobs:
-only-testing:cmuxTests/GhosttyOptionAsAltModsTests \
test

- name: Run agent hibernation planner regression
if: ${{ matrix.shard == fromJSON(env.CMUX_APP_HOST_FOCUSED_REGRESSION_SHARD) }}
run: |
# Pure hibernation-planner selection tests, run isolated so this new
# suite does not perturb the greedy shard packing (which carries
# order/load-sensitive WKWebView suites). See the note in
# scripts/ci/cmux_unit_test_shard.py FOCUSED_GATE_SELECTORS.
set -euo pipefail
SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
scripts/ci/run-in-console-session.sh \
scripts/ci/run-app-host-xcodebuild.sh \
-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/AgentHibernationPlannerTests \
test

- name: Run unit tests
run: |
set -euo pipefail
Expand Down
12 changes: 9 additions & 3 deletions CLI/CMUXCLI+AgentHookDefinitions.swift
Original file line number Diff line number Diff line change
Expand Up @@ -325,7 +325,11 @@ extension CMUXCLI {
events: [
.init(agentEvent: "SessionStart", cmuxSubcommand: "session-start"),
.init(agentEvent: "Stop", cmuxSubcommand: "stop"),
.init(agentEvent: "Notification", cmuxSubcommand: "stop"),
// Notification is the permission/attention channel (turn-end is Stop).
// Route through the notification lane so blocking prompts assert
// .needsInput and routine ones preserve idle, instead of "stop"
// forcing idle on a live permission prompt (hibernate mid-prompt).
.init(agentEvent: "Notification", cmuxSubcommand: "notification"),
.init(agentEvent: "SessionEnd", cmuxSubcommand: "session-end"),
],
feedHookEvents: ["PreToolUse"]
Expand All @@ -338,7 +342,8 @@ extension CMUXCLI {
events: [
.init(agentEvent: "SessionStart", cmuxSubcommand: "session-start"),
.init(agentEvent: "Stop", cmuxSubcommand: "stop"),
.init(agentEvent: "Notification", cmuxSubcommand: "stop"),
// See copilot: notification lane, not "stop".
.init(agentEvent: "Notification", cmuxSubcommand: "notification"),
.init(agentEvent: "SessionEnd", cmuxSubcommand: "session-end"),
],
feedHookEvents: ["PreToolUse"]
Expand All @@ -351,7 +356,8 @@ extension CMUXCLI {
events: [
.init(agentEvent: "SessionStart", cmuxSubcommand: "session-start"),
.init(agentEvent: "Stop", cmuxSubcommand: "stop"),
.init(agentEvent: "Notification", cmuxSubcommand: "stop"),
// See copilot: notification lane, not "stop".
.init(agentEvent: "Notification", cmuxSubcommand: "notification"),
.init(agentEvent: "SessionEnd", cmuxSubcommand: "session-end"),
],
feedHookEvents: ["PreToolUse"]
Expand Down
169 changes: 132 additions & 37 deletions CLI/cmux.swift

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import Foundation

/// Live background work an agent left running when its turn ended.
///
/// The hibernation lifecycle marks a pane `.idle` at the Stop hook, which makes it
/// eligible for reclamation (the planner SIGTERMs the scoped process group). That is
/// wrong when the agent has `run_in_background` tasks or a Monitor still running: a
/// silent background task has its own process group and produces no terminal output,
/// so it is invisible to the scrollback+PID activity fingerprint and gets killed on
/// hibernation. Claude Code reports this state to the Stop hook via `background_tasks`
/// (and scheduled `session_crons`); this value turns that payload into a single
/// `isActive` decision the Stop lane uses to record `.running` instead of `.idle`,
/// mirroring the existing antigravity `fullyIdle` gate.
///
/// Modeled as an instantiated value (it parses the payload in its initializer) and
/// lives in this package (not the CLI executable) so it is unit testable via
/// `swift test` without launching the app.
public struct AgentBackgroundWorkStatus: Equatable, Sendable {
/// Background tasks whose status is not a known terminal state (running/pending/
/// unknown all count — see `agentBackgroundTerminalStatuses`).
public let runningBackgroundTaskCount: Int
/// Scheduled cron jobs the session will wake itself for.
public let scheduledCronCount: Int

/// Create a status from explicit counts (used by tests and the parsing initializer).
public init(runningBackgroundTaskCount: Int, scheduledCronCount: Int) {
self.runningBackgroundTaskCount = runningBackgroundTaskCount
self.scheduledCronCount = scheduledCronCount
}

/// Detect live background work from a Claude Code hook payload object (the full
/// parsed JSON, e.g. `ClaudeHookParsedInput.rawObject`). Claude Code drops finished
/// tasks from `background_tasks`, so a task present with a non-terminal status means
/// work is still running; any `session_crons` entry means the session expects to
/// wake itself later.
///
/// Trust-boundary rule: an ABSENT field means "no background work" (older clients
/// never send it, and they must keep hibernating), but a PRESENT field this parser
/// cannot read — schema drift to a keyed object, an array of non-objects — fails
/// CLOSED as one active task. This payload is the only guard between hibernation's
/// group SIGTERM and a live background process; unreadable evidence of work must
/// keep the pane alive (until the next parseable Stop), never authorize the kill.
public init(hookObject object: [String: Any]?) {
let tasks = AgentHookFieldParse(value: object?["background_tasks"])
let crons = AgentHookFieldParse(value: object?["session_crons"])
let running = tasks.objects.reduce(into: tasks.unreadableCount) { count, task in
let status = ((task["status"] as? String) ?? "")
.trimmingCharacters(in: .whitespacesAndNewlines)
.lowercased()
if !agentBackgroundTerminalStatuses.contains(status) { count += 1 }
}
self.init(
runningBackgroundTaskCount: running,
scheduledCronCount: crons.objects.count + crons.unreadableCount
)
}

/// Whether the pane has live background work and must stay out of hibernation.
public var isActive: Bool {
runningBackgroundTaskCount > 0 || scheduledCronCount > 0
}
}

/// Statuses that mean a background task has finished and is safe to hibernate through.
/// Anything else (running, pending, queued, in_progress, or an unrecognized value) is
/// treated as live — the safe direction is to keep the pane alive rather than risk
/// killing real work.
private let agentBackgroundTerminalStatuses: Set<String> = [
"completed", "complete", "done", "finished", "succeeded", "success",
"failed", "failure", "error", "errored",
"cancelled", "canceled", "killed", "terminated", "stopped",
"exited", "timeout", "timedout",
]

/// One parsed hook array field: the readable object entries, plus how many values were
/// present but unreadable (a non-array field, or non-object array elements). Callers
/// decide what unreadable means; the background-work parser fails closed on it.
private struct AgentHookFieldParse {
let objects: [[String: Any]]
let unreadableCount: Int

init(value: Any?) {
guard let value else {
objects = []
unreadableCount = 0
return
}
guard let array = value as? [Any] else {
objects = []
unreadableCount = 1
return
}
let parsed = array.compactMap { $0 as? [String: Any] }
objects = parsed
unreadableCount = array.count - parsed.count
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
import Foundation

/// A coding-agent notification, classified for hibernation purposes.
///
/// `isBlockingPrompt` is the single source of truth for "should this notification
/// keep the pane live", shared by the dedicated Claude hook lane and the generic
/// agent-hook lane. The hibernation lifecycle has one authoritative idle source (the
/// Stop hook); a notification may only *assert* `.needsInput` (never force `.idle`
/// from ambiguous prose) and only when `isBlockingPrompt` is true. Everything else
/// leaves the lifecycle untouched so a finished agent stays hibernation-eligible
/// across every agent kind.
///
/// Modeled as an instantiated value (rather than a static helper) so it owns its
/// inputs, and lives in this package (rather than the CLI executable target) so it is
/// unit testable via `swift test` without launching the app.
public struct AgentNotification {
/// The structured event/reason field (e.g. `permission_prompt`, `error`).
public let signal: String
/// The free-text notification message.
public let message: String

/// Create a notification from its structured signal/reason field and free-text message.
public init(signal: String, message: String) {
self.signal = signal
self.message = message
}

/// Whether this notification describes a genuinely blocking prompt (the user must
/// act now) rather than a routine waiting/idle reminder or a completion.
///
/// Blocking == a permission/approval request, an error, or a genuine question the
/// user must answer. A routine "waiting for input" / "idle" reminder is NOT blocking
/// (it fires after every turn end, so blocking on it would clobber the Stop hook's
/// `.idle` and the pane would never hibernate). The genuine-question rule mirrors the
/// CLI notification classifier's question branch (`containsWaitingCue`), so a prompt
/// that surfaces only through a Notification hook (agents without a dedicated
/// needs-input path) still keeps its pane live while the user answers.
public var isBlockingPrompt: Bool {
let lower = "\(signal) \(message)".lowercased()
if lower.contains("permission") || lower.contains("approve") || lower.contains("approval")
|| lower.contains("permission_prompt")
|| lower.contains("error") || lower.contains("failed") || lower.contains("failure")

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Loose substring matching for error, failed, failure, exception risks false-positive blocking on routine non-blocking notifications, directly undermining the classifier's purpose.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At Packages/macOS/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentNotificationBlockingClassifier.swift, line 33:

<comment>Loose substring matching for `error`, `failed`, `failure`, `exception` risks false-positive blocking on routine non-blocking notifications, directly undermining the classifier's purpose.</comment>

<file context>
@@ -0,0 +1,36 @@
+        let lower = "\(signal) \(message)".lowercased()
+        return lower.contains("permission") || lower.contains("approve") || lower.contains("approval")
+            || lower.contains("permission_prompt")
+            || lower.contains("error") || lower.contains("failed") || lower.contains("failure")
+            || lower.contains("exception")
+    }
</file context>

|| lower.contains("exception") {
return true
}
return agentNotificationContainsGenuineQuestionCue(lower)
}
}

/// A genuine prompt the user must answer, as opposed to a routine "waiting for input"
/// nudge. Detected from high-confidence signals only: a direct interrogative (contains
/// `?`), or the literal `question` token paired with an interaction word.
///
/// Deliberately NOT keyed on bare verbs like `confirm`/`choose`/`continue`/`proceed`:
/// those collide with routine agent chatter ("continue when ready", "proceed to the
/// next step"), and blocking on them would clobber the Stop hook's `.idle` so the pane
/// never hibernates — the exact bug this lane exists to prevent. Routine idle/waiting
/// reminders never carry a `?`, so they stay non-blocking. A genuine but
/// punctuation-free imperative ("Choose an option") is intentionally left to the
/// authoritative structured signal (`notification_type`), not this free-text heuristic.
/// Mirrors the CLI classifier's `containsWaitingCue` so the blocking decision and the
/// `.needsInput` classification stay in lockstep.
private func agentNotificationContainsGenuineQuestionCue(_ lowercasedText: String) -> Bool {
if lowercasedText.contains("?") { return true }
let tokens = lowercasedText.split { !$0.isLetter && !$0.isNumber }.map(String.init)
guard tokens.contains("question") else { return false }
let interactionCues: Set<String> = [
"answer", "respond", "response", "reply", "choose", "confirm", "continue",
]
return tokens.contains { interactionCues.contains($0) }
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
import CMUXAgentLaunch
import Testing

/// The Claude Stop hook fires when a turn ends, and cmux records the pane `.idle`
/// there — which makes it hibernation-eligible. But Claude may have launched
/// `run_in_background` Bash tasks or a Monitor that outlives the turn: a silent
/// background task (its own process group, no terminal output) is invisible to the
/// scrollback+PID activity fingerprint, so the pane hibernates and the group SIGTERM
/// kills the live work. Claude Code hands the Stop hook a structured `background_tasks`
/// array (and `session_crons`); a task with a non-terminal status means work is still
/// running. This suite pins the detection that keeps such a pane out of hibernation.
@Suite("AgentBackgroundWork")
struct AgentBackgroundWorkStatusTests {
// The exact shape observed empirically from a Claude Code 2.1.197 Stop hook while a
// `sleep 20 && echo BGDONE` background shell was still alive.
private func runningTask(status: String = "running") -> [String: Any] {
[
"id": "bnlimlndi",
"type": "shell",
"status": status,
"description": "Background sleep and echo command",
"command": "sleep 20 && echo BGDONE",
]
}

@Test("A running background task keeps the pane active")
func runningBackgroundTaskIsActive() {
let status = AgentBackgroundWorkStatus(hookObject: [
"hook_event_name": "Stop",
"background_tasks": [runningTask()],
"session_crons": [],
])
#expect(status.isActive)
#expect(status.runningBackgroundTaskCount == 1)
}

@Test("An empty payload is inactive (turn is genuinely idle)")
func emptyPayloadIsInactive() {
// Control: no background work. Claude drops finished tasks from the array, so
// both arrays empty cleanly means nothing is pending and the pane may hibernate.
let status = AgentBackgroundWorkStatus(hookObject: [
"hook_event_name": "Stop",
"background_tasks": [],
"session_crons": [],
])
#expect(!status.isActive)
#expect(status.runningBackgroundTaskCount == 0)
#expect(status.scheduledCronCount == 0)
}

@Test("A scheduled session cron keeps the pane active")
func scheduledCronIsActive() {
// A cron means Claude expects to wake itself later; hibernating would kill it.
let status = AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [],
"session_crons": [["id": "job1", "cron": "*/5 * * * *"]],
])
#expect(status.isActive)
#expect(status.scheduledCronCount == 1)
}

@Test("Only-terminal-status tasks are inactive")
func terminalTasksAreInactive() {
// Finished tasks normally vanish from the array, but if a terminal-status entry
// lingers it must NOT block hibernation.
for terminal in ["completed", "done", "failed", "error", "cancelled", "killed", "exited"] {
let status = AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [runningTask(status: terminal)],
"session_crons": [],
])
#expect(!status.isActive, "Expected inactive for terminal status \(terminal)")
}
}

@Test("Unknown/empty status fails safe to active")
func unknownStatusFailsSafeActive() {
// A task present with a status we don't recognize (or no status) is treated as
// live: the safe direction is to NOT hibernate and risk killing real work.
for unknown in ["", "queued", "pending", "in_progress", "weird-new-state"] {
let status = AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [["id": "x", "status": unknown]],
])
#expect(status.isActive, "Expected active for non-terminal status \(unknown.debugDescription)")
}
// A task object with no status key at all is still active.
let noStatus = AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [["id": "x", "command": "sleep 99"]],
])
#expect(noStatus.isActive)
}

@Test("Absent payloads are inactive (older clients keep hibernating)")
func absentPayloadsAreInactive() {
// Clients older than 2.1.145 never send these fields; hibernation must keep
// working for them, so absence means "no background work".
#expect(!AgentBackgroundWorkStatus(hookObject: nil).isActive)
#expect(!AgentBackgroundWorkStatus(hookObject: [:]).isActive)
#expect(!AgentBackgroundWorkStatus(hookObject: ["hook_event_name": "Stop"]).isActive)
}

@Test("Present-but-unreadable payloads fail closed as active")
func unreadablePayloadsFailClosedActive() {
// This payload is the only guard between hibernation's group SIGTERM and a live
// background process. A field that is PRESENT but unparseable (schema drift to a
// keyed object, an array of non-objects) is unreadable evidence of work — it must
// keep the pane alive, never authorize the kill. Must not crash either.
#expect(AgentBackgroundWorkStatus(hookObject: ["background_tasks": "nope"]).isActive)
#expect(AgentBackgroundWorkStatus(hookObject: ["background_tasks": 7]).isActive)
#expect(AgentBackgroundWorkStatus(hookObject: ["background_tasks": ["a", "b"]]).isActive)
#expect(AgentBackgroundWorkStatus(hookObject: ["background_tasks": ["t1": ["status": "running"]]]).isActive)
#expect(AgentBackgroundWorkStatus(hookObject: ["session_crons": "soon"]).isActive)
// A readable terminal-status entry alongside unreadable garbage: garbage wins.
#expect(AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [["status": "completed"], "garbage"],
]).isActive)
// An EMPTY array is readable and clean: inactive.
#expect(!AgentBackgroundWorkStatus(hookObject: ["background_tasks": [Any]()]).isActive)
}

@Test("Status matching ignores case and surrounding whitespace")
func statusNormalization() {
#expect(!AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [["status": " COMPLETED "]],
]).isActive)
#expect(AgentBackgroundWorkStatus(hookObject: [
"background_tasks": [["status": " Running "]],
]).isActive)
}
}
Loading
Loading