Repository navigation
Hibernation: correct notification lifecycle for all agent types #6721
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
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 abf33a1
Hibernation: per-evaluation observability so non-hibernation is never…
lawrencecchen 57b8c38
Hibernation: gate persisted lifecycle for nonblocking notifications
lawrencecchen 9afdd6b
Hibernation: route copilot/codebuddy/factory Notification to notifica…
lawrencecchen deb7af2
Hibernation: make classifier package-testable + guard DEBUG-only logs
lawrencecchen 15a274a
Hibernation: classifier as package type + Swift Testing suite
lawrencecchen 1052a1e
Hibernation: classifier as instantiable value type (package-conventio…
lawrencecchen 56bb289
Hibernation: require a recorded transcript path for the claude restor…
lawrencecchen f5857ff
Hibernation: keep claude restorability fail-closed (diagnostic only)
lawrencecchen 6d2072c
Hibernation: deterministic planner unit test + all-agent-types coverage
lawrencecchen ed339fb
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen 64a4820
ci: isolate heavy WKWebView BrowserSessionHistoryRestoreTests as a fo…
lawrencecchen 37d6676
ci: focused-gate AgentHibernationPlannerTests to keep shard compositi…
lawrencecchen e6580b2
test: pin claude background-work detection (red)
lawrencecchen cf9ccee
fix: keep claude panes with live background work out of hibernation
lawrencecchen 366889c
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen 565e197
fix: treat genuine question prompts as hibernation-blocking
lawrencecchen fb7c61e
chore: satisfy Aziz package policy (docs + file-scope helpers)
lawrencecchen 395b5b8
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen b0d05e7
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen 3d3cc47
fix: claude Stop status pill shows Running while background work is live
lawrencecchen 157ef0a
fix: blocking questions beat completion cues; malformed payloads fail…
lawrencecchen 81badf1
chore: fold field-parse helper struct into a file-scope function
lawrencecchen 9de2730
Merge origin/main (PR #7129 notify gating) into feat-hibernation-all-…
lawrencecchen f837b8d
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen 454483b
Merge remote-tracking branch 'origin/main' into feat-hibernation-all-…
lawrencecchen 2ed1744
perf: gate the per-record hibernation restorability debug log
lawrencecchen File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
97 changes: 97 additions & 0 deletions
97
Packages/macOS/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentBackgroundWorkStatus.swift
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| } | ||
| } |
71 changes: 71 additions & 0 deletions
71
...s/macOS/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentNotificationBlockingClassifier.swift
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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") | ||
| || 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) } | ||
| } | ||
129 changes: 129 additions & 0 deletions
129
...ges/macOS/CMUXAgentLaunch/Tests/CMUXAgentLaunchTests/AgentBackgroundWorkStatusTests.swift
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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) | ||
| } | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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,exceptionrisks false-positive blocking on routine non-blocking notifications, directly undermining the classifier's purpose.Prompt for AI agents