Skip to content

CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息

feat: 增加异常会话保护

Bob37cc79c036a1
diff --git a/AGENTS.md b/AGENTS.md
index ec34476..f9de45a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -35,6 +35,12 @@ CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用, 使用 Swift 6,
保持三条数据链路独立: app-server 额度与用量, Hook 历史聚合, `CodexActivityMonitor` 实时任务; helper 只能控制睡眠, 不得增加网络, 任意命令执行或额外文件访问; 修改 Hook 配置时必须保留用户和其他应用已有的 handler; 启用和校验 Hook 必须检查当前 app-server 的实际版本不低于 `0.145.0`; 新增网络访问, 日志数据或 CloudKit 字段前先核对隐私边界
+`CodexActivityMonitor` 的异常会话保护跟随防睡眠主开关, 只判定运行中任务, 等待批准任务不参与判定. 静默阈值可选 30 分钟, 1, 2 或 4 小时, 默认 1 小时. Hook bootstrap, 系统睡眠, 唤醒恢复或 Hook 数据源不可用期间必须暂停判定, 数据恢复后统一无通知对账
+
+`HookEventTailReader.drainNow()` 是读取屏障, 每个调用方必须等待一轮在本次请求之后开始的读取. 系统唤醒只有在该轮读取成功后才执行 rollout 生命周期对账并恢复异常会话保护判定; reader 更换时丢弃旧结果, 数据源不可用或任务取消时不得使用旧快照继续判定
+
+异常会话保护记录由 `ActivityProtectionStateStore` 保存在 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`, 只包含哈希任务标识和时间戳, 最长保留到最后进展后的 24 小时. Debug 与 Release 通过 `flock` 共用该文件, 当前 schema 为 1; 修改格式或身份计算属于兼容性问题
+
需要从原始 Hook 事件重新计算的聚合算法, 输出字段, 字段含义或去重规则变化时必须递增 `WorkflowMaintenanceState.currentAggregationSchema`, 统一从保留期内的原始 JSONL 完整重建, 不新增字段级历史迁移. Hook 计数字段缺失表示历史来源不可用, 不能解码成明确的 0
## 测试规范
diff --git a/CLAUDE.md b/CLAUDE.md
index a77ac63..c1d1d05 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -119,12 +119,28 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
`CodexActivityMonitor` 是菜单栏图标, 活动卡片, 通知, 触觉反馈和防睡眠的**唯一任务状态来源**, 由两个 reader 供料
-- `HookEventTailReader` (actor) 的 bootstrap 覆盖滚动 24 小时并作为单次事务发送, 之后按当日文件 offset 增量 tail
-- `CodexSessionLifecycleReader` (actor) 增量读取 `~/.codex/sessions` 与 `archived_sessions` 下的 rollout JSONL, 只提取 turn 生命周期字段, 不解码会话或工具内容
+- `HookEventTailReader` (actor) 的 bootstrap 覆盖滚动 24 小时并作为单次事务发送, 之后按当日文件 offset 增量 tail, 同时向下游报告数据源健康状态
+- `CodexSessionLifecycleReader` (actor) 增量读取 `~/.codex/sessions` 与 `archived_sessions` 下的 rollout JSONL, 只提取 turn 生命周期与最近进展时间, 不解码会话或工具内容
- 任务监控只在 `codexHookSettings.isOperable` 为 true 时运行, 即本地已安装且最近一次明确校验没有失败; 链路失效时立即停 reader 并清空实时状态
- `SessionEnd` 没有 `turn_id`, 收到后按 session 把对应任务立即移出活跃列表并放进 5 秒终态确认窗口; rollout 在窗口内补回准确的完成或终止分类, 超时后按终止处理
+- `HookEventTailReader.drainNow()` 是读取屏障, 每个调用方等待一轮在本次请求之后开始的读取, 返回 `completed` `sourceUnavailable` 或 `cancelled`
-系统唤醒时 `NSWorkspace.didWakeNotification` 会触发立即 drain 并重置生命周期解析回退
+系统唤醒时 `NSWorkspace.didWakeNotification` 先暂停异常会话保护. 读取屏障成功时重置生命周期解析回退并完成 rollout 对账后恢复判定; 数据源不可用时继续由 source health 门槛暂停, reader generation 变化时旧结果直接丢弃
+
+#### 异常会话保护
+
+- `CodexActivityProtection.swift` 管理异常会话保护状态机, `ActivityProtectionSettings` 只保存静默阈值; 保护开关跟随用户保存的 KeepAlive 主开关, 不依赖 helper 是否已获系统授权
+- 静默阈值可选 30 分钟, 1, 2 或 4 小时, 默认 1 小时, UserDefaults key 固定为 `KeepAlive.abnormalTaskInactivitySeconds`
+- 候选只包含 `.running` 任务, `.waitingApproval` 不参与异常判定; `lastProgressAt` 同时吸收 Hook 顶层事件, 子 Agent 事件与 rollout 行时间
+- 达到阈值后先持久化候选记录并尝试提交本地通知, 通知使用系统默认声音且不重试; 最多等待 3 秒后无论通知是否提交成功都隐藏任务
+- 通知以 task ID 与 attempt ID 共同标识, 候选失效或任务恢复, 终止, 完成, 过期时会撤回仍可识别的待处理和已送达通知; 迟到的提交结果不得影响新的 attempt
+- 隐藏任务不进入 `CodexActivitySnapshot` 的运行中与等待批准列表, 因而不参与 UI 和 KeepAlive 的活跃任务计算; 后续进展会恢复任务并清除保护记录
+- KeepAlive 关闭时恢复当前进程内所有隐藏任务并撤回通知, 已经隐藏任务的持久化记录保留; 再次开启后按当前阈值和最近进展时间无通知对账
+- 判定要求监控已启动, KeepAlive 已开启, reader 存在, bootstrap 已结束, 不在睡眠或唤醒恢复阶段且 Hook 数据源健康; 进入不满足条件的阶段时会取消计时器和在途通知 attempt
+- 静默定时器使用 `SuspendingClock`, 系统时间变化由 `NSSystemClockDidChange` 触发无通知重算; 系统睡眠期间暂停判定, 唤醒完成 Hook 读取和 rollout 对账后再恢复
+- `ActivityProtectionStateStore` 把记录写入 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`, 字段只有 SHA-256 任务标识与 `lastProgressAt` `markedAt` `expiresAt`, 最长保留到最后进展后的 24 小时
+- Debug 与 Release 共用状态文件, actor 串行化进程内访问, `flock` 保护跨进程读写, 文件权限固定为 `0600`, 当前 schema 为 1; 状态在 task reader 启动前完成加载
+- 持久化操作按 `activityProtectionPersistenceTask` 串行排队, 条件删除用 `markedAt` 防止旧 attempt 删除新记录, 终态与保留期清理执行无条件删除
### 防睡眠 (KeepAlive) 与 root helper
@@ -138,6 +154,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
关键约束
- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点, 要求 `isStarted && !isPreparingForTermination && isEnabled && isHookEnabled && hasRunningTasks && helperStatus == .enabled && !isRefreshingHelper && !isLowBatteryActive && !hasReachedMaximumDuration` 同时成立; **依赖不满足只让效果失效, 绝不回写用户保存的 `isEnabled`**
+- `hasRunningTasks` 只消费 `CodexActivitySnapshot` 中仍可见的运行中任务与按设置纳入的等待批准任务, 被异常会话保护隐藏的任务不参与防睡眠
- Hook 状态在类内只认 `isHookEnabled` 这份镜像, 它跟的是 `codexHookSettings.isOperable`; 不要回读那个属性, 订阅回调跑在 `willSet`, 那一刻它的两个输入里正在变的那一项还是旧值, 只能认 `CombineLatest` 给的闭包参数
- 新增拦截条件一律加进 `sleepBlockReason` 的顺序判断里, 它和 `shouldDisableSleep` 同源, 顺带保证日志的 `reason=` 不会漏项
- UI 用的 `isLowBatteryBlocking` 与 `canShowOptions` 由 `reconcileSleepState` 从 `sleepBlockReason` 单点派生, 新增拦截条件时 `allowsOptions` 那个穷举 `switch` 会强制表态, 于是不会出现入口亮着却点不动
@@ -183,7 +200,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
- `SleepConditions` 里只放 `battery` 布尔, 放电量百分比会让每掉 1% 刷一条变化日志; 真实电量只在触发那一条单独记
- 状态只呈现在主面板活动卡片右侧的咖啡杯标记 (带 tooltip), 由 `KeepAliveController.isActivelyPreventingSleep` 驱动, `sleepPreventionSource` 区分外部来源与 CodexBar 所有权, 卡片折叠成"暂无数据"时标记要跟着一起收
- 设置页那一行说明只在异常, 外部来源, 低电量生效或达到上限时出现, CodexBar 自己正常持有所有权时整行收起, `keepAliveCaption` 返回 nil 即代表收起
-- 最长防睡眠时间与低电量阈值都在防睡眠子面板里, 台式机读不到电池时低电量那一行整行隐藏而不是置灰
+- 最长防睡眠时间, 异常会话保护阈值与低电量阈值都在防睡眠子面板里, 台式机读不到电池时低电量那一行整行隐藏而不是置灰
- 保持屏幕常亮跟 `isActivelyPreventingSleep` 走, 由 `reconcileDisplayAwake` 单点切换, 于是低电量拦下, 达到上限, 任务结束时屏幕都跟着放开
- 显示断言只保证屏幕不睡, 屏保与闲置锁屏跟的是系统 idle 计时, 要靠 30 秒一次的 `IOPMAssertionDeclareUserActivity` 压住, 两者缺一不可
- 声明用户活动复用同一个 assertion ID, 每次传 null 会新建一条, `pmset -g assertions` 里会堆成一串同名断言
@@ -195,6 +212,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
- `CodexNotificationService` 是集中式的 MainActor 服务, 订阅额度快照与实时活动, 负责阈值穿越判定, 去重, 额度重置识别, 触觉反馈和本地通知; dedup key 落 UserDefaults
- `send` 是唯一的提交入口, 返回一个 `Task<Bool, Never>?` 值, 需要等通知真的发出去再做下一步的调用方 `await` 它的 `value` 即可; 不要另开一条 async 通道, 那会悄悄少掉去重 时效判定与提交失败回调三项能力
- 去重判定留在 `send` 的同步段而不是挪进 `Task` 内部, 这样连续两次调用的第二次一定被挡下, 不依赖任务调度顺序
+- 异常会话保护通知只依赖通知总开关与系统授权, 使用系统默认声音, `retryCount` 为 0; 提交前后都调用 monitor 的 relevance 检查, 过期通知立即撤回
- `NotificationSettings` 管 CodexBar 自身通知; `CodexCLINotificationSettings` 是另一回事, 它通过 app-server `config/read` 与 `config/batchWrite` 读写 Codex 自己的用户级 `config.toml`
- 通知面板里带依赖的行一律显示为关闭并置灰而不是隐藏, 任务类看 `codexHookSettings.isOperable`, 低电量保护通知看 `KeepAliveController.isLowBatteryProtectionEnabled` (防睡眠可用, 阈值开着, 且这台机器确实有电池), 防睡眠上限通知看 `KeepAliveController.isMaximumDurationEnabled` (防睡眠可用且不是无限制); 都不回写用户保存的开关
- 两条防睡眠通知的依赖里都含"防睡眠可用"这一层, 即防睡眠开关与 Hook 都开着, 判定收在 `publishNotificationDependencies` 一处; 只判各自的子设置会让防睡眠关着时这两行还亮着
@@ -206,7 +224,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 设置, 所有类型默认 MainActor 隔离
- UI, 控制器, ViewModel, Settings, 更新类直接依赖默认隔离, 不需要额外标注
-- 服务共享状态用 actor 管理, 包括 `CodexStatusService` `WorkflowService` `WorkflowSyncService` `CodexCLIVersionService` `HookEventTailReader` `CodexSessionLifecycleReader`
+- 服务共享状态用 actor 管理, 包括 `CodexStatusService` `WorkflowService` `WorkflowSyncService` `CodexCLIVersionService` `HookEventTailReader` `CodexSessionLifecycleReader` `ActivityProtectionStateStore`
- DTO, 纯模型, 静态工具, 跨 actor 传递的类型必须显式标注 `nonisolated`
- 跨进程写统计文件用 `stats.lock` 加 `flock` 保护, Hook 子进程有等待上限, 主 App 无限等待; `RequestLogStorage` 用 `OSAllocatedUnfairLock`
- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer` 里, `JSONLineReader` 与 `PipeDrain` 复用它
@@ -288,6 +306,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
- 只读查询打到 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 这一个地址, 也是全仓库唯一的 `URLSession` 调用点, 位于 `CodexResetCreditsService` 内; Sparkle 更新走 `https://codexbar.zabrian.app/appcast.xml` 这个 feed
- 不展示 app-server stderr; 不展示或记录 Codex OAuth token 与 `auth.json` 内容; 不把原始敏感 RPC 响应写进文档
- CloudKit 只同步去掉 `sessionIds` 与 `turnIds` 的 daily 聚合, 不同步原始 Hook events, 账号, 额度或 Token 用量
+- 异常会话保护状态只保存在本机, 不同步 CloudKit; 记录不含原始 session ID, turn ID, 项目名或任务内容
- CloudKit 的 `sessionEndCount` `userPromptSubmitCount` 与其他 Hook 计数字段保持可选, 远端缺失表示历史来源没有提供, 不能在读取时补成 0; 改变远端格式时同时评估并更新 `syncSchemaVersion`
- 系统日志不写用户数据: 额度与 Token 用量只记 `state=` 这类结果分类, 任务内容, 项目名, 会话与轮次标识一律不记; 可执行文件路径含用户名, 用 `source=global|bundled` 之类的标识代替
- 事件数, 任务数, 日期这类聚合数字可以记, 它们是判断重建是否正确和定位哪天出问题的依据, 不含任何内容
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index c4f6f70..13be5d6 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -14,6 +14,7 @@ final class SettingsWindowController: HostingWindowController {
private let menuBarQuotaSettings: MenuBarQuotaSettings
private let mainPanelSettings: MainPanelSettings
private let notificationSettings: NotificationSettings
+ private let activityProtectionSettings: ActivityProtectionSettings
private let keepAliveController: KeepAliveController
private let onSyncChanged: (Bool) -> Void
private let onRebuildWorkflowData: WorkflowSyncScheduler.RebuildHandler
@@ -32,6 +33,7 @@ final class SettingsWindowController: HostingWindowController {
menuBarQuotaSettings: MenuBarQuotaSettings,
mainPanelSettings: MainPanelSettings,
notificationSettings: NotificationSettings,
+ activityProtectionSettings: ActivityProtectionSettings,
keepAliveController: KeepAliveController,
screenProvider: @escaping () -> NSScreen?,
onSyncChanged: @escaping (Bool) -> Void,
@@ -46,6 +48,7 @@ final class SettingsWindowController: HostingWindowController {
self.menuBarQuotaSettings = menuBarQuotaSettings
self.mainPanelSettings = mainPanelSettings
self.notificationSettings = notificationSettings
+ self.activityProtectionSettings = activityProtectionSettings
self.keepAliveController = keepAliveController
self.onSyncChanged = onSyncChanged
self.onRebuildWorkflowData = onRebuildWorkflowData
@@ -110,6 +113,7 @@ final class SettingsWindowController: HostingWindowController {
syncSettings.refresh()
menuBarQuotaSettings.refresh()
mainPanelSettings.refresh()
+ activityProtectionSettings.refresh()
keepAliveController.refresh()
}
@@ -182,9 +186,12 @@ final class SettingsWindowController: HostingWindowController {
SettingsOptionsPanelController(
animationKey: "CodexBar.keepAliveOptionsDrawerTransform",
initialPanelSize: KeepAliveOptionsView.initialPanelSize,
- contentControllerProvider: { [keepAliveController] entryCue in
+ contentControllerProvider: { [keepAliveController, activityProtectionSettings] entryCue in
SettingsOptionsPanelController.makeContentController(
- KeepAliveOptionsView(keepAliveController: keepAliveController),
+ KeepAliveOptionsView(
+ keepAliveController: keepAliveController,
+ activityProtectionSettings: activityProtectionSettings
+ ),
rebuiltBy: entryCue
)
},
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 1c775d0..7287f94 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -13,7 +13,11 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
lazy var codexCLINotificationSettings = CodexCLINotificationSettings(
codexStatusService: codexStatusService
)
- lazy var activityMonitor = CodexActivityMonitor(codexHookSettings: codexHookSettings)
+ let activityProtectionSettings = ActivityProtectionSettings()
+ lazy var activityMonitor = CodexActivityMonitor(
+ codexHookSettings: codexHookSettings,
+ activityProtectionSettings: activityProtectionSettings
+ )
lazy var keepAliveController = KeepAliveController(
activityMonitor: activityMonitor,
codexHookSettings: codexHookSettings
@@ -68,6 +72,12 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
keepAliveController.onKeepAliveLimitTriggered = { [weak notificationService] duration in
await notificationService?.notifyKeepAliveLimitReached(durationText: duration.title) ?? false
}
+ activityMonitor.onInactivityProtectionTriggered = { [weak notificationService] notice in
+ await notificationService?.notifyActivityProtection(notice) ?? false
+ }
+ activityMonitor.onInactivityProtectionInvalidated = { [weak notificationService] taskID, attemptID in
+ notificationService?.invalidateActivityProtectionNotification(taskID: taskID, attemptID: attemptID)
+ }
activityMonitor.start()
keepAliveController.start()
logLaunchState()
@@ -110,34 +120,22 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
/// 启动时把各开关的初始值记成一条基线, 之后的变更日志都是相对这条基线的增量
/// 排查时先看这条就知道当时的配置, 不必让用户逐项回忆
private func logLaunchState() {
- // 全部先落到局部量再插值: Logger 的插值是 autoclosure, 直接写属性会与 --self remove 打架
- let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "-"
- let build = Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "-"
- let hook = codexHookSettings.isEnabled ? 1 : 0
- let keepAlive = keepAliveController.isEnabled ? 1 : 0
- let keepAliveLimit = keepAliveController.maximumDuration.loggedHours
- let keepAliveBattery = keepAliveController.lowBatteryThreshold.rawValue
- let keepAliveWaiting = keepAliveController.keepsAwakeWhileWaiting ? 1 : 0
- let keepAliveDisplay = keepAliveController.keepsDisplayAwake ? 1 : 0
- let sync = syncSettings.isEnabled ? 1 : 0
- let notification = notificationSettings.isEnabled ? 1 : 0
- let menuBarQuota = menuBarQuotaSettings.selection.rawValue
- let taskCenter = mainPanelSettings.showsTaskCenter ? 1 : 0
- let hotKey = globalHotKeySettings.shortcut == nil ? 0 : 1
+ // 先拼成普通字符串再交给 Logger, 避免在日志 autoclosure 中直接捕获属性
let state = LogFields.joined(
- "version=\(version)",
- "build=\(build)",
- "hook=\(hook)",
- "keepAlive=\(keepAlive)",
- "keepAliveLimit=\(keepAliveLimit)",
- "keepAliveBattery=\(keepAliveBattery)",
- "keepAliveWaiting=\(keepAliveWaiting)",
- "keepAliveDisplay=\(keepAliveDisplay)",
- "sync=\(sync)",
- "notification=\(notification)",
- "menuBarQuota=\(menuBarQuota)",
- "taskCenter=\(taskCenter)",
- "hotKey=\(hotKey)"
+ "version=\(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "-")",
+ "build=\(Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "-")",
+ "hook=\(codexHookSettings.isEnabled ? 1 : 0)",
+ "keepAlive=\(keepAliveController.isEnabled ? 1 : 0)",
+ "keepAliveLimit=\(keepAliveController.maximumDuration.loggedHours)",
+ "keepAliveBattery=\(keepAliveController.lowBatteryThreshold.rawValue)",
+ "keepAliveWaiting=\(keepAliveController.keepsAwakeWhileWaiting ? 1 : 0)",
+ "keepAliveDisplay=\(keepAliveController.keepsDisplayAwake ? 1 : 0)",
+ "activityProtectionMinutes=\(activityProtectionSettings.inactivityDuration.loggedMinutes)",
+ "sync=\(syncSettings.isEnabled ? 1 : 0)",
+ "notification=\(notificationSettings.isEnabled ? 1 : 0)",
+ "menuBarQuota=\(menuBarQuotaSettings.selection.rawValue)",
+ "taskCenter=\(mainPanelSettings.showsTaskCenter ? 1 : 0)",
+ "hotKey=\(globalHotKeySettings.shortcut == nil ? 0 : 1)"
)
AppLog.app.notice("App 已启动: \(state, privacy: .public)")
}
@@ -191,6 +189,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
menuBarQuotaSettings: menuBarQuotaSettings,
mainPanelSettings: mainPanelSettings,
notificationSettings: notificationSettings,
+ activityProtectionSettings: activityMonitor.activityProtectionSettings,
keepAliveController: keepAliveController
) { [weak self] in
self?.statusItem.button?.window?.screen
diff --git a/CodexBar/Models/CodexActivityModels.swift b/CodexBar/Models/CodexActivityModels.swift
index bcb34d2..39dbae3 100644
--- a/CodexBar/Models/CodexActivityModels.swift
+++ b/CodexBar/Models/CodexActivityModels.swift
@@ -59,6 +59,16 @@ nonisolated struct CodexActivityTermination: Equatable, Identifiable {
let duration: TimeInterval?
}
+/// 实时越过静默阈值时交给通知服务的最小信息, 不包含原始 session 或 turn ID
+nonisolated struct CodexActivityProtectionNotice: Equatable, Sendable {
+ let taskID: UUID
+ let attemptID: UUID
+ let projectName: String?
+ let inactivityDurationText: String
+ let inactivityDurationSeconds: Int
+ let progressGeneration: UInt64
+}
+
/// UI 只消费该快照, 不直接读取或解释 Hook 事件
nonisolated struct CodexActivitySnapshot: Equatable {
let waitingTasks: [CodexActivityTaskSnapshot]
diff --git a/CodexBar/Resources/Localizable.xcstrings b/CodexBar/Resources/Localizable.xcstrings
index bfef094..8e638f7 100644
--- a/CodexBar/Resources/Localizable.xcstrings
+++ b/CodexBar/Resources/Localizable.xcstrings
@@ -289,6 +289,38 @@
}
}
},
+ "activity-protection.duration.hours" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "%lld hr"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "%lld 小时"
+ }
+ }
+ }
+ },
+ "activity-protection.duration.thirty-minutes" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "30 min"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "30 分钟"
+ }
+ }
+ }
+ },
"app.command.settings" : {
"extractionState" : "manual",
"localizations" : {
@@ -1298,6 +1330,54 @@
}
}
},
+ "notification.activity-protection.body.codex" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "No Codex task progress for %@; hidden and excluded from keep-awake"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Codex 任务已静默 %@, 已隐藏并停止参与防睡眠"
+ }
+ }
+ }
+ },
+ "notification.activity-protection.body.project" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "No progress in “%1$@” for %2$@; hidden and excluded from keep-awake"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "%1$@ 已静默 %2$@, 已隐藏并停止参与防睡眠"
+ }
+ }
+ }
+ },
+ "notification.activity-protection.title" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Codex Task Has No Progress"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Codex 任务长时间无进展"
+ }
+ }
+ }
+ },
"notification.credit-expiry.body" : {
"localizations" : {
"en" : {
@@ -2322,6 +2402,38 @@
}
}
},
+ "异常会话保护" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Inactive Task Protection"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "异常会话保护"
+ }
+ }
+ }
+ },
+ "长时间没有进展时隐藏任务并停止参与防睡眠" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Hide inactive tasks and exclude them from keep-awake"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "长时间没有进展时隐藏任务并停止参与防睡眠"
+ }
+ }
+ }
+ },
"最长任务" : {
"localizations" : {
"en" : {
diff --git a/CodexBar/Services/KeepAlive/KeepAliveController.swift b/CodexBar/Services/KeepAlive/KeepAliveController.swift
index afd0718..5db0b49 100644
--- a/CodexBar/Services/KeepAlive/KeepAliveController.swift
+++ b/CodexBar/Services/KeepAlive/KeepAliveController.swift
@@ -171,6 +171,7 @@ final class KeepAliveController: ObservableObject {
keepsAwakeWhileWaiting = defaults.bool(forKey: Self.keepsAwakeWhileWaitingKey)
// 默认关闭: 它会让人离开后机器一直停在解锁状态, 这个取舍只能由用户自己做
keepsDisplayAwake = defaults.bool(forKey: Self.keepsDisplayAwakeKey)
+ activityMonitor.setActivityProtectionEnabled(isEnabled)
}
func start() {
@@ -303,6 +304,7 @@ final class KeepAliveController: ObservableObject {
AppLog.keepAlive.notice("KeepAlive 开关变更: enabled=\(enabled ? 1 : 0)")
isEnabled = enabled
defaults.set(enabled, forKey: Self.enabledKey)
+ activityMonitor.setActivityProtectionEnabled(enabled)
registrationErrorMessage = nil
operationErrorMessage = nil
@@ -1044,7 +1046,7 @@ final class KeepAliveController: ObservableObject {
"source=\(String(describing: source))",
"lidCausesSleep=\(lidCausesSleep)"
)
- AppLog.keepAlive.notice("系统睡眠已防止: \(details, privacy: .public)")
+ AppLog.keepAlive.notice("已防止系统睡眠: \(details, privacy: .public)")
}
durationLimiter.begin()
completePendingRequest(success: true)
diff --git a/CodexBar/Services/Notifications/CodexNotificationService.swift b/CodexBar/Services/Notifications/CodexNotificationService.swift
index d2bce34..8b22013 100644
--- a/CodexBar/Services/Notifications/CodexNotificationService.swift
+++ b/CodexBar/Services/Notifications/CodexNotificationService.swift
@@ -16,6 +16,7 @@ final class CodexNotificationService: NSObject {
private var cancellables = Set<AnyCancellable>()
private var taskHapticFeedbackTask: Task<Void, Never>?
private var taskWaitingNotificationIdentifiers = Set<String>()
+ private var activityProtectionNotificationIdentifiers = Set<String>()
private let creditExpiryReminderScheduler = ReminderCheckScheduler()
private var latestQuotaSnapshot: CodexQuotaSnapshot?
@@ -205,6 +206,56 @@ final class CodexNotificationService: NSObject {
}
}
+ // MARK: - 异常任务保护
+
+ func notifyActivityProtection(_ notice: CodexActivityProtectionNotice) async -> Bool {
+ guard settings.canDeliver else {
+ return false
+ }
+
+ let identifier = Self.activityProtectionNotificationIdentifier(
+ taskID: notice.taskID,
+ attemptID: notice.attemptID
+ )
+ activityProtectionNotificationIdentifiers.insert(identifier)
+ let deliveryTask = send(
+ .activityProtection(
+ project: notice.projectName,
+ inactivityDurationText: notice.inactivityDurationText
+ ),
+ sound: .systemDefault,
+ identifier: identifier,
+ isStillRelevant: { [weak self] in
+ self?.activityMonitor.isInactivityProtectionNoticeRelevant(
+ taskID: notice.taskID,
+ attemptID: notice.attemptID,
+ progressGeneration: notice.progressGeneration,
+ inactivityDurationSeconds: notice.inactivityDurationSeconds
+ ) ?? false
+ },
+ onSubmissionFailure: { [weak self] in
+ self?.activityProtectionNotificationIdentifiers.remove(identifier)
+ },
+ retryCount: 0
+ )
+ let wasSubmitted = await deliveryTask?.value ?? false
+ if !wasSubmitted {
+ activityProtectionNotificationIdentifiers.remove(identifier)
+ }
+ return wasSubmitted
+ }
+
+ func invalidateActivityProtectionNotification(taskID: UUID, attemptID: UUID) {
+ let identifier = Self.activityProtectionNotificationIdentifier(
+ taskID: taskID,
+ attemptID: attemptID
+ )
+ guard activityProtectionNotificationIdentifiers.remove(identifier) != nil else {
+ return
+ }
+ removeNotifications(withIdentifiers: [identifier])
+ }
+
// MARK: - 快照处理
private func handleSnapshot(_ snapshot: CodexQuotaSnapshot?) {
@@ -499,7 +550,8 @@ final class CodexNotificationService: NSObject {
identifier: String = UUID().uuidString,
dedupKey: String? = nil,
isStillRelevant: (() -> Bool)? = nil,
- onSubmissionFailure: (() -> Void)? = nil
+ onSubmissionFailure: (() -> Void)? = nil,
+ retryCount: Int = CodexNotificationService.notificationSubmissionRetryCount
) -> Task<Bool, Never>? {
let kind = notification.kind
if let dedupKey {
@@ -530,7 +582,8 @@ final class CodexNotificationService: NSObject {
kind: kind,
dedupKey: dedupKey,
isStillRelevant: isStillRelevant,
- onSubmissionFailure: onSubmissionFailure
+ onSubmissionFailure: onSubmissionFailure,
+ retryCount: retryCount
) ?? false
}
}
@@ -541,7 +594,8 @@ final class CodexNotificationService: NSObject {
kind: String,
dedupKey: String?,
isStillRelevant: (() -> Bool)?,
- onSubmissionFailure: (() -> Void)?
+ onSubmissionFailure: (() -> Void)?,
+ retryCount: Int
) async -> Bool {
defer {
if let dedupKey {
@@ -549,7 +603,7 @@ final class CodexNotificationService: NSObject {
}
}
- for _ in 0 ... Self.notificationSubmissionRetryCount {
+ for _ in 0 ... max(0, retryCount) {
guard isStillRelevant?() != false else {
let details = LogFields.joined(
"kind=\(kind)",
@@ -608,6 +662,13 @@ final class CodexNotificationService: NSObject {
"taskWaiting|\(taskID.uuidString)"
}
+ private nonisolated static func activityProtectionNotificationIdentifier(
+ taskID: UUID,
+ attemptID: UUID
+ ) -> String {
+ "activityProtection|\(taskID.uuidString)|\(attemptID.uuidString)"
+ }
+
private nonisolated static func quotaWindowStateKey(
accountKey: String,
limitId: String,
@@ -757,6 +818,32 @@ nonisolated struct CodexNotificationContent: Equatable {
)
}
+ static func activityProtection(
+ project: String?,
+ inactivityDurationText: String
+ ) -> CodexNotificationContent {
+ let body = if let project {
+ String(
+ localized: "notification.activity-protection.body.project",
+ defaultValue: "\(project) 已静默 \(inactivityDurationText), 已隐藏并停止参与防睡眠"
+ )
+ } else {
+ String(
+ localized: "notification.activity-protection.body.codex",
+ defaultValue: "Codex 任务已静默 \(inactivityDurationText), 已隐藏并停止参与防睡眠"
+ )
+ }
+
+ return CodexNotificationContent(
+ kind: "activityProtection",
+ title: String(
+ localized: "notification.activity-protection.title",
+ defaultValue: "Codex 任务长时间无进展"
+ ),
+ body: body
+ )
+ }
+
static func creditExpiry(count: Int, expirationDate: Date) -> CodexNotificationContent {
let expirationText = CodexDateFormat.localDisplayString(from: expirationDate)
return CodexNotificationContent(
diff --git a/CodexBar/Services/Settings/ActivityProtectionSettings.swift b/CodexBar/Services/Settings/ActivityProtectionSettings.swift
new file mode 100644
index 0000000..ad293e4
--- /dev/null
+++ b/CodexBar/Services/Settings/ActivityProtectionSettings.swift
@@ -0,0 +1,79 @@
+import Combine
+import Foundation
+import os
+
+/// 异常任务保护跟随防睡眠开关, 此处只管理静默阈值
+@MainActor
+final class ActivityProtectionSettings: ObservableObject {
+ @Published private(set) var inactivityDuration: InactivityDuration
+
+ private let defaults: UserDefaults
+
+ init(defaults: UserDefaults = .standard) {
+ self.defaults = defaults
+ inactivityDuration = Self.storedDuration(in: defaults)
+ }
+
+ func setInactivityDuration(_ duration: InactivityDuration) {
+ guard duration != inactivityDuration else {
+ return
+ }
+
+ inactivityDuration = duration
+ defaults.set(duration.rawValue, forKey: Self.inactivityDurationKey)
+ AppLog.activity.notice(
+ "异常任务静默阈值变更: minutes=\(duration.loggedMinutes)"
+ )
+ }
+
+ func refresh() {
+ let storedDuration = Self.storedDuration(in: defaults)
+ guard storedDuration != inactivityDuration else {
+ return
+ }
+ inactivityDuration = storedDuration
+ }
+
+ private static func storedDuration(in defaults: UserDefaults) -> InactivityDuration {
+ (defaults.object(forKey: inactivityDurationKey) as? Int)
+ .flatMap(InactivityDuration.init(rawValue:)) ?? .oneHour
+ }
+
+ private static let inactivityDurationKey = "KeepAlive.abnormalTaskInactivitySeconds"
+}
+
+extension ActivityProtectionSettings {
+ enum InactivityDuration: Int, CaseIterable, Identifiable {
+ case thirtyMinutes = 1800
+ case oneHour = 3600
+ case twoHours = 7200
+ case fourHours = 14400
+
+ var id: Int {
+ rawValue
+ }
+
+ var timeInterval: TimeInterval {
+ TimeInterval(rawValue)
+ }
+
+ var loggedMinutes: Int {
+ rawValue / 60
+ }
+
+ var title: String {
+ if self == .thirtyMinutes {
+ return String(
+ localized: "activity-protection.duration.thirty-minutes",
+ defaultValue: "30 分钟"
+ )
+ }
+
+ let hours = rawValue / 3600
+ return String(
+ localized: "activity-protection.duration.hours",
+ defaultValue: "\(hours) 小时"
+ )
+ }
+ }
+}
diff --git a/CodexBar/Services/Workflow/ActivityProtectionStateStore.swift b/CodexBar/Services/Workflow/ActivityProtectionStateStore.swift
new file mode 100644
index 0000000..5494c44
--- /dev/null
+++ b/CodexBar/Services/Workflow/ActivityProtectionStateStore.swift
@@ -0,0 +1,174 @@
+import Darwin
+import Foundation
+import os
+
+nonisolated struct ActivityProtectionRecord: Codable, Equatable, Sendable {
+ let taskIdentifier: String
+ let lastProgressAt: Date
+ let markedAt: Date
+ let expiresAt: Date
+}
+
+nonisolated struct ActivityProtectionRemoval: Sendable {
+ let taskIdentifier: String
+ let matchingMarkedAt: Date?
+
+ init(taskIdentifier: String, matchingMarkedAt: Date? = nil) {
+ self.taskIdentifier = taskIdentifier
+ self.matchingMarkedAt = matchingMarkedAt
+ }
+}
+
+/// 异常任务标记的本地存储, actor 隔离进程内访问, flock 保护 Debug 和 Release 共用文件
+actor ActivityProtectionStateStore {
+ private let directoryURL: URL
+ private let stateURL: URL
+ private let lockURL: URL
+ private let fileManager: FileManager
+
+ init(fileManager: FileManager = .default) {
+ self.fileManager = fileManager
+ let applicationSupportURL = fileManager.urls(
+ for: .applicationSupportDirectory,
+ in: .userDomainMask
+ ).first ?? URL(fileURLWithPath: NSHomeDirectory())
+ .appendingPathComponent("Library", isDirectory: true)
+ .appendingPathComponent("Application Support", isDirectory: true)
+ directoryURL = applicationSupportURL
+ .appendingPathComponent("CodexBar", isDirectory: true)
+ .appendingPathComponent("ActivityProtection", isDirectory: true)
+ stateURL = directoryURL.appendingPathComponent("state.json", isDirectory: false)
+ lockURL = directoryURL.appendingPathComponent("state.lock", isDirectory: false)
+ }
+
+ func load(now: Date = Date()) -> [String: ActivityProtectionRecord] {
+ do {
+ return try withExclusiveLock {
+ var records = loadRecordsWithoutLock()
+ let originalCount = records.count
+ records = records.filter { $0.value.expiresAt > now }
+ if records.count != originalCount {
+ try saveRecordsWithoutLock(records)
+ }
+ return records
+ }
+ } catch {
+ AppLog.activity.error(
+ "异常任务状态读取失败: reason=\(error.localizedDescription, privacy: .public)"
+ )
+ return [:]
+ }
+ }
+
+ func apply(
+ upserts: [ActivityProtectionRecord] = [],
+ removals: [ActivityProtectionRemoval] = [],
+ now: Date = Date()
+ ) throws {
+ try withExclusiveLock {
+ var records = loadRecordsWithoutLock()
+ records = records.filter { $0.value.expiresAt > now }
+
+ for removal in removals {
+ guard let existing = records[removal.taskIdentifier] else {
+ continue
+ }
+ if let matchingMarkedAt = removal.matchingMarkedAt,
+ existing.markedAt != matchingMarkedAt {
+ continue
+ }
+ records.removeValue(forKey: removal.taskIdentifier)
+ }
+
+ for record in upserts {
+ guard record.expiresAt > now else {
+ continue
+ }
+ if let existing = records[record.taskIdentifier],
+ existing.markedAt > record.markedAt {
+ continue
+ }
+ records[record.taskIdentifier] = record
+ }
+
+ try saveRecordsWithoutLock(records)
+ }
+ }
+
+ private func withExclusiveLock<T>(_ work: () throws -> T) throws -> T {
+ try fileManager.createDirectory(
+ at: directoryURL,
+ withIntermediateDirectories: true
+ )
+
+ let fileDescriptor = open(lockURL.path, O_RDWR | O_CREAT, 0o600)
+ guard fileDescriptor >= 0 else {
+ throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+ }
+ defer {
+ close(fileDescriptor)
+ }
+
+ let lockDeadline = ProcessInfo.processInfo.systemUptime + Self.lockTimeout
+ while flock(fileDescriptor, LOCK_EX | LOCK_NB) != 0 {
+ let lockError = errno
+ guard lockError == EWOULDBLOCK || lockError == EAGAIN || lockError == EINTR else {
+ throw POSIXError(POSIXErrorCode(rawValue: lockError) ?? .EIO)
+ }
+ guard ProcessInfo.processInfo.systemUptime < lockDeadline else {
+ throw POSIXError(.ETIMEDOUT)
+ }
+ usleep(Self.lockRetryMicroseconds)
+ }
+ defer {
+ flock(fileDescriptor, LOCK_UN)
+ }
+
+ return try work()
+ }
+
+ private static let lockTimeout: TimeInterval = 2
+ private static let lockRetryMicroseconds: useconds_t = 50000
+
+ private func loadRecordsWithoutLock() -> [String: ActivityProtectionRecord] {
+ guard fileManager.fileExists(atPath: stateURL.path) else {
+ return [:]
+ }
+ guard let data = try? Data(contentsOf: stateURL), !data.isEmpty,
+ let state = try? JSONDecoder().decode(ActivityProtectionState.self, from: data),
+ state.schemaVersion == ActivityProtectionState.currentSchemaVersion else {
+ AppLog.activity.error("异常任务状态已忽略: reason=invalidState")
+ return [:]
+ }
+
+ return Dictionary(
+ state.records.map { ($0.taskIdentifier, $0) },
+ uniquingKeysWith: { current, candidate in
+ current.markedAt >= candidate.markedAt ? current : candidate
+ }
+ )
+ }
+
+ private func saveRecordsWithoutLock(
+ _ records: [String: ActivityProtectionRecord]
+ ) throws {
+ let state = ActivityProtectionState(
+ schemaVersion: ActivityProtectionState.currentSchemaVersion,
+ records: records.values.sorted {
+ $0.taskIdentifier < $1.taskIdentifier
+ }
+ )
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ let data = try encoder.encode(state)
+ try data.write(to: stateURL, options: .atomic)
+ chmod(stateURL.path, 0o600)
+ }
+}
+
+private nonisolated struct ActivityProtectionState: Codable {
+ static let currentSchemaVersion = 1
+
+ let schemaVersion: Int
+ let records: [ActivityProtectionRecord]
+}
diff --git a/CodexBar/Services/Workflow/CodexActivityMonitor.swift b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
index 5322f4e..908ba42 100644
--- a/CodexBar/Services/Workflow/CodexActivityMonitor.swift
+++ b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
@@ -12,32 +12,57 @@ final class CodexActivityMonitor: ObservableObject {
transitionSubject.eraseToAnyPublisher()
}
+ var onInactivityProtectionTriggered: ((CodexActivityProtectionNotice) async -> Bool)?
+ var onInactivityProtectionInvalidated: ((UUID, UUID) -> Void)?
+
private let codexHookSettings: CodexHookSettings
+ let activityProtectionSettings: ActivityProtectionSettings
+ let activityProtectionStateStore: ActivityProtectionStateStore
private let sessionLifecycleReader = CodexSessionLifecycleReader()
- private let transitionSubject = PassthroughSubject<CodexActivityTransition, Never>()
- private var tasks: [CodexActivityTaskKey: CodexActivityTask] = [:]
- private var pendingTerminalTasks: [CodexActivityTaskKey: PendingTerminalTask] = [:]
- private var completions: [CodexActivityCompletion] = []
- private var terminations: [CodexActivityTermination] = []
- private var recentlyCompletedTaskAt: [CodexActivityTaskKey: Date] = [:]
- private var recentlyTerminatedTaskAt: [CodexActivityTaskKey: Date] = [:]
- private var tailReader: HookEventTailReader?
+ let transitionSubject = PassthroughSubject<CodexActivityTransition, Never>()
+ var tasks: [CodexActivityTaskKey: CodexActivityTask] = [:]
+ var pendingTerminalTasks: [CodexActivityTaskKey: PendingTerminalTask] = [:]
+ var completions: [CodexActivityCompletion] = []
+ var terminations: [CodexActivityTermination] = []
+ var recentlyCompletedTaskAt: [CodexActivityTaskKey: Date] = [:]
+ var recentlyTerminatedTaskAt: [CodexActivityTaskKey: Date] = [:]
+ var tailReader: HookEventTailReader?
private var tailReaderControlTask: Task<Void, Never>?
private var tailReaderGeneration: UInt64 = 0
private var sessionLifecyclePollTask: Task<Void, Never>?
private var cleanupTask: Task<Void, Never>?
private var cleanupDeadline: Date?
+ var inactivityCheckTask: Task<Void, Never>?
+ var inactivityCheckDeadline: Date?
+ var activityProtectionAttempts: [CodexActivityTaskKey: ActivityProtectionAttempt] = [:]
+ var activityProtectionNoticeAttemptIDs: [UUID: UUID] = [:]
+ var activityProtectionRecords: [String: ActivityProtectionRecord] = [:]
+ private var activityProtectionStateLoadTask: Task<Void, Never>?
+ var activityProtectionPersistenceTask: Task<Void, Never>?
+ private var isActivityProtectionStateLoaded = false
+ var isActivityProtectionEnabled = false
+ var isActivitySourceHealthy = false
+ var isActivityProtectionRecoveryInProgress = false
+ var activityProtectionRecoveryGeneration: UInt64 = 0
+ private var requestedMonitoringEnabled = false
private var cancellables = Set<AnyCancellable>()
- private var isStarted = false
- private var isBootstrapping = false
+ var isStarted = false
+ var isBootstrapping = false
/// 历史回放跨多个批次到达, 事件数累加到 bootstrapEnd 才一次记完
/// reader 每次重试都会重新发一遍 bootstrapStart, 所以事件数跟着重置, 但耗时要累计
private var bootstrapEventCount = 0
private var bootstrapDuration = LogDuration()
- private var sessionTransitionNotBefore: Date?
+ private var bootstrapCompletionGeneration: UInt64 = 0
+ var sessionTransitionNotBefore: Date?
- init(codexHookSettings: CodexHookSettings) {
+ init(
+ codexHookSettings: CodexHookSettings,
+ activityProtectionSettings: ActivityProtectionSettings,
+ activityProtectionStateStore: ActivityProtectionStateStore = ActivityProtectionStateStore()
+ ) {
self.codexHookSettings = codexHookSettings
+ self.activityProtectionSettings = activityProtectionSettings
+ self.activityProtectionStateStore = activityProtectionStateStore
}
func start() {
@@ -46,11 +71,34 @@ final class CodexActivityMonitor: ObservableObject {
}
isStarted = true
+ loadActivityProtectionState()
+
Publishers.CombineLatest(codexHookSettings.$isEnabled, codexHookSettings.$isVerified)
.map { $0 && $1 }
.removeDuplicates()
.sink { [weak self] isOperable in
- self?.setMonitoringEnabled(isOperable)
+ self?.requestMonitoringEnabled(isOperable)
+ }
+ .store(in: &cancellables)
+
+ activityProtectionSettings.$inactivityDuration
+ .dropFirst()
+ // @Published 在 willSet 发值, 切回主队列后再按已经提交的新阈值重算
+ .receive(on: DispatchQueue.main)
+ .sink { [weak self] _ in
+ self?.handleActivityProtectionTimingChange()
+ }
+ .store(in: &cancellables)
+
+ NSWorkspace.shared.notificationCenter
+ .publisher(for: NSWorkspace.willSleepNotification)
+ .receive(on: DispatchQueue.main)
+ .sink { [weak self] _ in
+ guard let self else {
+ return
+ }
+ beginActivityProtectionRecovery()
+ AppLog.activity.notice("异常任务判定已暂停: reason=systemSleep")
}
.store(in: &cancellables)
@@ -64,12 +112,37 @@ final class CodexActivityMonitor: ObservableObject {
AppLog.activity.notice(
"事件重读已触发: trigger=\(LogTrigger.wake.rawValue, privacy: .public)"
)
- if let reader = tailReader {
- Task {
- await reader.drainNow()
+ let recoveryGeneration = beginActivityProtectionRecovery()
+ guard let reader = tailReader else {
+ finishActivityProtectionRecovery(generation: recoveryGeneration)
+ return
+ }
+ let readerGeneration = tailReaderGeneration
+ Task { @MainActor [weak self] in
+ let drainResult = await reader.drainNow()
+ guard let self,
+ readerGeneration == tailReaderGeneration else {
+ return
+ }
+ guard case .completed = drainResult else {
+ finishActivityProtectionRecovery(generation: recoveryGeneration)
+ return
}
+ await sessionLifecycleReader.resetResolutionFallbacks()
+ await reconcileSessionLifecycles(generation: readerGeneration)
+ guard readerGeneration == tailReaderGeneration else {
+ return
+ }
+ finishActivityProtectionRecovery(generation: recoveryGeneration)
}
- refreshSessionLifecycleNow(resetsResolutionFallbacks: true)
+ }
+ .store(in: &cancellables)
+
+ NotificationCenter.default
+ .publisher(for: .NSSystemClockDidChange)
+ .receive(on: DispatchQueue.main)
+ .sink { [weak self] _ in
+ self?.handleActivityProtectionTimingChange()
}
.store(in: &cancellables)
}
@@ -80,9 +153,40 @@ final class CodexActivityMonitor: ObservableObject {
}
isStarted = false
cancellables.removeAll()
+ activityProtectionStateLoadTask?.cancel()
+ activityProtectionStateLoadTask = nil
stopReaderAndClearState()
}
+ private func loadActivityProtectionState() {
+ guard !isActivityProtectionStateLoaded,
+ activityProtectionStateLoadTask == nil else {
+ return
+ }
+
+ activityProtectionStateLoadTask = Task { @MainActor [weak self] in
+ guard let self else {
+ return
+ }
+ let records = await activityProtectionStateStore.load()
+ guard isStarted, !Task.isCancelled else {
+ return
+ }
+ activityProtectionRecords = records
+ isActivityProtectionStateLoaded = true
+ activityProtectionStateLoadTask = nil
+ setMonitoringEnabled(requestedMonitoringEnabled)
+ }
+ }
+
+ private func requestMonitoringEnabled(_ isEnabled: Bool) {
+ requestedMonitoringEnabled = isEnabled
+ guard isActivityProtectionStateLoaded else {
+ return
+ }
+ setMonitoringEnabled(isEnabled)
+ }
+
private func setMonitoringEnabled(_ isOperable: Bool) {
guard isOperable else {
AppLog.activity.notice("任务监控已停止: reason=hookInoperable")
@@ -120,6 +224,7 @@ final class CodexActivityMonitor: ObservableObject {
private func stopReaderAndClearState() {
tailReaderGeneration &+= 1
+ resetActivityProtectionRecovery()
tailReaderControlTask?.cancel()
tailReaderControlTask = nil
let reader = tailReader
@@ -131,6 +236,8 @@ final class CodexActivityMonitor: ObservableObject {
}
sessionLifecyclePollTask?.cancel()
sessionLifecyclePollTask = nil
+ cancelInactivityCheck()
+ isActivitySourceHealthy = false
cleanupTask?.cancel()
cleanupTask = nil
cleanupDeadline = nil
@@ -216,11 +323,22 @@ final class CodexActivityMonitor: ObservableObject {
}
var taskDidChange = Self.mergeLifecycleBackfill(from: state, into: &task)
+ let progressDidChange = mergeLifecycleProgress(
+ from: state,
+ key: key,
+ into: &task
+ )
+ taskDidChange = progressDidChange || taskDidChange
if let terminal = state.terminal {
tasks.removeValue(forKey: key)
if case .completed = terminal, recentCompletionDate(for: key) != nil {
// 迟到事件恢复出的任务不能被 rollout 再次完成
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .terminal
+ )
return true
}
resolveTerminal(
@@ -239,10 +357,18 @@ final class CodexActivityMonitor: ObservableObject {
taskDidChange = true
}
+ let wasSuppressedBeforeApproval = task.state == .suppressed
if resolvePendingApprovalIfPossible(
for: &task,
into: &transitions
) {
+ if wasSuppressedBeforeApproval, task.state == .waitingApproval {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ }
taskDidChange = true
}
@@ -250,6 +376,35 @@ final class CodexActivityMonitor: ObservableObject {
return false
}
tasks[key] = task
+ if progressDidChange {
+ suppressBackfilledActivityTaskIfOverdue(key, now: Date())
+ }
+ return true
+ }
+
+ private func mergeLifecycleProgress(
+ from state: CodexSessionTaskLifecycleState,
+ key: CodexActivityTaskKey,
+ into task: inout CodexActivityTask
+ ) -> Bool {
+ guard let lastProgressAt = state.lastProgressAt,
+ lastProgressAt > task.lastProgressAt else {
+ return false
+ }
+
+ let wasSuppressed = task.state == .suppressed
+ task.recordProgress(at: lastProgressAt)
+ if shouldRestoreActivityProtection(for: key, progressAt: lastProgressAt) {
+ if wasSuppressed {
+ task.state = .running
+ task.stateChangedAt = lastProgressAt
+ }
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ }
return true
}
@@ -297,49 +452,34 @@ final class CodexActivityMonitor: ObservableObject {
bootstrapDuration = LogDuration()
}
isBootstrapping = true
+ bootstrapCompletionGeneration &+= 1
sessionTransitionNotBefore = nil
bootstrapEventCount = 0
+ isActivitySourceHealthy = false
+ cancelInactivityCheck()
clearCollectedActivityState()
case let .bootstrapEvents(events):
bootstrapEventCount += events.count
for event in events {
- _ = apply(event)
+ _ = apply(event, source: .bootstrap)
}
case let .bootstrapEnd(degraded, attempts):
- isBootstrapping = false
+ isActivitySourceHealthy = !degraded
sessionTransitionNotBefore = Date()
- refreshSnapshot(now: Date())
- refreshSessionLifecycleNow()
- backfillPromptStartTimesFromHistory()
- let activeCount = snapshot.activeCount
- let eventCount = bootstrapEventCount
- let elapsed = bootstrapDuration.elapsed
- guard !degraded else {
- let details = LogFields.joined(
- "attempts=\(attempts)",
- "events=\(eventCount)",
- "activeTasks=\(activeCount)",
- "elapsed=\(elapsed)",
- "reason=unstableBoundary",
- "action=skipHistory"
+ let completionGeneration = bootstrapCompletionGeneration
+ Task { @MainActor [weak self] in
+ await self?.finishBootstrap(
+ degraded: degraded,
+ attempts: attempts,
+ completionGeneration: completionGeneration
)
- AppLog.activity.notice("历史回放已降级: \(details, privacy: .public)")
- return
}
-
- let details = LogFields.joined(
- "attempts=\(attempts)",
- "events=\(eventCount)",
- "activeTasks=\(activeCount)",
- "elapsed=\(elapsed)"
- )
- AppLog.activity.notice("历史回放完成: \(details, privacy: .public)")
case let .live(events):
let pendingKeysBefore = Set(pendingTerminalTasks.keys)
let activeCountBefore = snapshot.activeCount
var transitions: [CodexActivityLiveTransition] = []
for event in events {
- if let transition = apply(event) {
+ if let transition = apply(event, source: .live) {
transitions.append(transition)
}
}
@@ -364,7 +504,77 @@ final class CodexActivityMonitor: ObservableObject {
.subtracting(pendingKeysBefore).isEmpty
refreshSessionLifecycleNow(resetsResolutionFallbacks: hasNewPendingTasks)
}
+ case let .sourceHealthChanged(isHealthy):
+ guard isHealthy != isActivitySourceHealthy else {
+ return
+ }
+ isActivitySourceHealthy = isHealthy
+ if isHealthy {
+ reconcileActivityProtection(now: Date(), sendsNotification: false)
+ } else {
+ cancelInactivityCheck()
+ cancelAllActivityProtectionAttempts()
+ AppLog.activity.error(
+ "异常任务判定已暂停: reason=hookSourceUnavailable"
+ )
+ }
+ }
+ }
+
+ private func finishBootstrap(
+ degraded: Bool,
+ attempts: Int,
+ completionGeneration: UInt64
+ ) async {
+ if !degraded {
+ let references = tasks.values.compactMap(\.turnReference)
+ + pendingTerminalTasks.values.compactMap(\.task.turnReference)
+ if !references.isEmpty {
+ let states = await sessionLifecycleReader.lifecycleStates(for: references)
+ guard completionGeneration == bootstrapCompletionGeneration,
+ tailReader != nil else {
+ return
+ }
+ var ignoredTransitions: [CodexActivityTransition] = []
+ for state in states {
+ _ = applyLifecycleState(state, into: &ignoredTransitions)
+ }
+ }
}
+
+ guard completionGeneration == bootstrapCompletionGeneration,
+ tailReader != nil else {
+ return
+ }
+ isBootstrapping = false
+ let now = Date()
+ applyPersistedActivityProtection(now: now)
+ reconcileActivityProtection(now: now, sendsNotification: false)
+ backfillPromptStartTimesFromHistory()
+
+ let activeCount = snapshot.activeCount
+ let eventCount = bootstrapEventCount
+ let elapsed = bootstrapDuration.elapsed
+ guard !degraded else {
+ let details = LogFields.joined(
+ "attempts=\(attempts)",
+ "events=\(eventCount)",
+ "activeTasks=\(activeCount)",
+ "elapsed=\(elapsed)",
+ "reason=unstableBoundary",
+ "action=skipHistory"
+ )
+ AppLog.activity.notice("历史回放已降级: \(details, privacy: .public)")
+ return
+ }
+
+ let details = LogFields.joined(
+ "attempts=\(attempts)",
+ "events=\(eventCount)",
+ "activeTasks=\(activeCount)",
+ "elapsed=\(elapsed)"
+ )
+ AppLog.activity.notice("历史回放完成: \(details, privacy: .public)")
}
/// bootstrap 只覆盖 24 小时窗口; 窗口内恢复出的无起点任务向更早日期回查 Prompt 起点
@@ -405,26 +615,53 @@ final class CodexActivityMonitor: ObservableObject {
}
}
- private func apply(_ event: WorkflowHookEvent) -> CodexActivityLiveTransition? {
+ private func apply(
+ _ event: WorkflowHookEvent,
+ source: CodexActivityEventSource
+ ) -> CodexActivityLiveTransition? {
+ let isTopLevelEvent = event.agentId == nil
switch event.hookEvent {
case .userPromptSubmit:
- startTask(from: event)
+ startTask(from: event, source: source)
case .preToolUse:
- resumeTask(from: event, latestEvent: .toolStarted, allowsRecovery: true)
+ resumeTask(
+ from: event,
+ latestEvent: .toolStarted,
+ allowsRecovery: isTopLevelEvent,
+ source: source
+ )
case .postToolUse:
- resumeTask(from: event, latestEvent: .toolFinished, allowsRecovery: true)
+ resumeTask(
+ from: event,
+ latestEvent: .toolFinished,
+ allowsRecovery: isTopLevelEvent,
+ source: source
+ )
case .preCompact:
- resumeTask(from: event, latestEvent: .compactionStarted, allowsRecovery: true)
+ resumeTask(
+ from: event,
+ latestEvent: .compactionStarted,
+ allowsRecovery: isTopLevelEvent,
+ source: source
+ )
case .postCompact:
- resumeTask(from: event, latestEvent: .compactionFinished, allowsRecovery: true)
+ resumeTask(
+ from: event,
+ latestEvent: .compactionFinished,
+ allowsRecovery: isTopLevelEvent,
+ source: source
+ )
case .subagentStart:
// 子智能体只更新所属顶层任务, 不自行创建一条并发任务
- updateSubagentActivity(from: event, isStarting: true)
+ updateSubagentActivity(from: event, isStarting: true, source: source)
case .subagentStop:
- updateSubagentActivity(from: event, isStarting: false)
+ updateSubagentActivity(from: event, isStarting: false, source: source)
case .permissionRequest:
- return waitForApproval(from: event)
+ return waitForApproval(from: event, source: source)
case .stop:
+ guard isTopLevelEvent else {
+ return nil
+ }
return completeTask(from: event)
case .sessionEnd:
terminateSession(from: event)
@@ -436,9 +673,13 @@ final class CodexActivityMonitor: ObservableObject {
// MARK: - 任务状态转换
- private func startTask(from event: WorkflowHookEvent) {
+ private func startTask(
+ from event: WorkflowHookEvent,
+ source: CodexActivityEventSource
+ ) {
let key = CodexActivityTaskKey(event: event)
- let displayID = tasks[key]?.displayID ?? UUID()
+ let existingTask = tasks[key]
+ let displayID = existingTask?.displayID ?? UUID()
if let completedAt = recentCompletionDate(for: key),
event.timestamp <= completedAt {
return
@@ -463,6 +704,8 @@ final class CodexActivityMonitor: ObservableObject {
$0.key != key && $0.key.sessionId == sessionId
}
for task in supersededTasks {
+ cancelActivityProtectionAttempt(for: task.key)
+ invalidateActivityProtectionNotification(for: task.displayID)
pendingTerminalTasks[task.key] = PendingTerminalTask(
task: task,
supersededAt: event.timestamp,
@@ -474,6 +717,14 @@ final class CodexActivityMonitor: ObservableObject {
}
}
+ if source == .live {
+ clearActivityProtection(
+ for: key,
+ taskID: displayID,
+ reason: .progress
+ )
+ }
+
recentlyCompletedTaskAt.removeValue(forKey: key)
recentlyTerminatedTaskAt.removeValue(forKey: key)
if let sessionId = key.sessionId {
@@ -488,27 +739,33 @@ final class CodexActivityMonitor: ObservableObject {
event: event,
state: .running,
latestEvent: .promptSubmitted,
- startedAt: event.timestamp
+ startedAt: event.timestamp,
+ progressGeneration: (existingTask?.progressGeneration ?? 0) &+ 1
)
}
private func resumeTask(
from event: WorkflowHookEvent,
latestEvent: CodexActivityEvent,
- allowsRecovery: Bool
+ allowsRecovery: Bool,
+ source: CodexActivityEventSource
) {
let eventKey = CodexActivityTaskKey(event: event)
- guard recentCompletionDate(for: eventKey) == nil,
- recentTerminationDate(for: eventKey) == nil,
- pendingTerminalTasks[eventKey] == nil else {
- return
- }
-
- if let key = matchingTaskKey(for: event), var task = tasks[key] {
+ let matchedKey = event.agentId == nil
+ ? matchingActiveTaskKey(for: event)
+ : matchingSubagentParentTaskKey(for: event)
+
+ if let key = matchedKey, var task = tasks[key] {
+ guard recentCompletionDate(for: key) == nil,
+ recentTerminationDate(for: key) == nil,
+ pendingTerminalTasks[key] == nil else {
+ return
+ }
guard event.timestamp >= task.lastActivityAt else {
return
}
+ let wasSuppressed = task.state == .suppressed
if task.state != .running {
task.state = .running
task.stateChangedAt = event.timestamp
@@ -516,34 +773,53 @@ final class CodexActivityMonitor: ObservableObject {
task.pendingApprovalRequestedAt = nil
task.latestEvent = latestEvent
task.mergeMetadata(from: event)
- task.lastActivityAt = event.timestamp
+ task.recordProgress(at: event.timestamp)
tasks[key] = task
+ if wasSuppressed || source == .live {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ }
return
}
- guard allowsRecovery else {
+ guard allowsRecovery,
+ recentCompletionDate(for: eventKey) == nil,
+ recentTerminationDate(for: eventKey) == nil,
+ pendingTerminalTasks[eventKey] == nil else {
return
}
- tasks[eventKey] = CodexActivityTask(
+ let recoveredTask = CodexActivityTask(
displayID: UUID(),
key: eventKey,
event: event,
state: .running,
latestEvent: latestEvent,
- startedAt: nil
+ startedAt: nil,
+ progressGeneration: 1
)
+ tasks[eventKey] = recoveredTask
+ if source == .live {
+ clearActivityProtection(
+ for: eventKey,
+ taskID: recoveredTask.displayID,
+ reason: .progress
+ )
+ }
}
private func updateSubagentActivity(
from event: WorkflowHookEvent,
- isStarting: Bool
+ isStarting: Bool,
+ source: CodexActivityEventSource
) {
- let eventKey = CodexActivityTaskKey(event: event)
- guard recentCompletionDate(for: eventKey) == nil,
- recentTerminationDate(for: eventKey) == nil,
- pendingTerminalTasks[eventKey] == nil,
- let key = matchingTaskKey(for: event),
+ guard let key = matchingSubagentParentTaskKey(for: event),
+ recentCompletionDate(for: key) == nil,
+ recentTerminationDate(for: key) == nil,
+ pendingTerminalTasks[key] == nil,
var task = tasks[key] else {
return
}
@@ -564,6 +840,7 @@ final class CodexActivityMonitor: ObservableObject {
)
if event.timestamp >= task.lastActivityAt {
+ let wasSuppressed = task.state == .suppressed
if task.state != .running {
task.state = .running
task.stateChangedAt = event.timestamp
@@ -571,7 +848,14 @@ final class CodexActivityMonitor: ObservableObject {
task.pendingApprovalRequestedAt = nil
task.latestEvent = isStarting ? .subagentStarted : .subagentFinished
task.mergeMetadata(from: event)
- task.lastActivityAt = event.timestamp
+ task.recordProgress(at: event.timestamp)
+ if wasSuppressed || source == .live {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ }
}
tasks[key] = task
}
@@ -597,38 +881,67 @@ final class CodexActivityMonitor: ObservableObject {
return activeTaskCount == 1 && !hasPendingTask
}
- private func waitForApproval(from event: WorkflowHookEvent) -> CodexActivityLiveTransition? {
+ private func waitForApproval(
+ from event: WorkflowHookEvent,
+ source: CodexActivityEventSource
+ ) -> CodexActivityLiveTransition? {
let eventKey = CodexActivityTaskKey(event: event)
- guard recentCompletionDate(for: eventKey) == nil,
- recentTerminationDate(for: eventKey) == nil,
- pendingTerminalTasks[eventKey] == nil else {
- return nil
- }
-
- if let key = matchingTaskKey(for: event), var task = tasks[key] {
+ let matchedKey = event.agentId == nil
+ ? matchingActiveTaskKey(for: event)
+ : matchingSubagentParentTaskKey(for: event)
+
+ if let key = matchedKey, var task = tasks[key] {
+ guard recentCompletionDate(for: key) == nil,
+ recentTerminationDate(for: key) == nil,
+ pendingTerminalTasks[key] == nil else {
+ return nil
+ }
guard event.timestamp >= task.lastActivityAt else {
return nil
}
+ let wasSuppressed = task.state == .suppressed
task.mergeMetadata(from: event)
// 权限事件描述当前请求; 缺失工具名时不能沿用上一条工具事件
task.toolName = event.toolName
- task.lastActivityAt = event.timestamp
+ task.recordProgress(at: event.timestamp)
let enteredWaiting = task.recordApprovalRequest(at: event.timestamp)
tasks[key] = task
+ if wasSuppressed || source == .live {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ }
return enteredWaiting ? .waitingApproval(key) : nil
}
+ guard event.agentId == nil,
+ recentCompletionDate(for: eventKey) == nil,
+ recentTerminationDate(for: eventKey) == nil,
+ pendingTerminalTasks[eventKey] == nil else {
+ return nil
+ }
+
var task = CodexActivityTask(
displayID: UUID(),
key: eventKey,
event: event,
state: .running,
latestEvent: .toolStarted,
- startedAt: nil
+ startedAt: nil,
+ progressGeneration: 1
)
let enteredWaiting = task.recordApprovalRequest(at: event.timestamp)
tasks[eventKey] = task
+ if source == .live {
+ clearActivityProtection(
+ for: eventKey,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ }
return enteredWaiting ? .waitingApproval(eventKey) : nil
}
@@ -636,31 +949,50 @@ final class CodexActivityMonitor: ObservableObject {
let eventKey = CodexActivityTaskKey(event: event)
guard recentCompletionDate(for: eventKey) == nil else {
// 清掉旧版本或异常顺序留下的同键恢复任务
- tasks.removeValue(forKey: eventKey)
+ discardStaleTerminalTask(for: eventKey)
return nil
}
guard recentTerminationDate(for: eventKey) == nil else {
+ discardStaleTerminalTask(for: eventKey)
return nil
}
- if let pending = pendingTerminalTasks[eventKey] {
+ let match = matchingTerminalTask(for: event)
+ if case .ambiguous = match {
+ AppLog.activity.error(
+ "任务终态已延后: reason=ambiguousStop"
+ )
+ return nil
+ }
+
+ if case let .pending(key) = match,
+ let pending = pendingTerminalTasks[key] {
guard event.timestamp >= pending.task.lastActivityAt else {
return nil
}
- pendingTerminalTasks.removeValue(forKey: eventKey)
+ pendingTerminalTasks.removeValue(forKey: key)
+ clearActivityProtection(
+ for: key,
+ taskID: pending.task.displayID,
+ reason: .terminal
+ )
let completion = storeResolvedCompletion(
pending.task,
- key: eventKey,
+ key: key,
completedAt: event.timestamp,
reportedDuration: nil,
projectName: event.projectDisplayName,
modelName: event.modelName,
effort: event.effort
)
+ recordCompletedTask(eventKey, at: event.timestamp)
return .completed(completion)
}
- let matchedKey = matchingTaskKey(for: event)
+ let matchedKey: CodexActivityTaskKey? = switch match {
+ case let .active(key): key
+ default: nil
+ }
let task = matchedKey.flatMap { tasks[$0] }
if let task, event.timestamp < task.lastActivityAt {
return nil
@@ -676,6 +1008,11 @@ final class CodexActivityMonitor: ObservableObject {
if let matchedKey {
tasks.removeValue(forKey: matchedKey)
+ clearActivityProtection(
+ for: matchedKey,
+ taskID: task?.displayID,
+ reason: .terminal
+ )
}
let duration = task?.preciseDuration(until: event.timestamp)
@@ -692,6 +1029,23 @@ final class CodexActivityMonitor: ObservableObject {
return .completed(completion)
}
+ private func discardStaleTerminalTask(for key: CodexActivityTaskKey) {
+ if let task = tasks.removeValue(forKey: key) {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .terminal
+ )
+ }
+ if let pending = pendingTerminalTasks.removeValue(forKey: key) {
+ clearActivityProtection(
+ for: key,
+ taskID: pending.task.displayID,
+ reason: .terminal
+ )
+ }
+ }
+
/// SessionEnd 没有 turn_id, 以 session 为边界把活跃任务移入终态确认窗口
/// 任务会立即退出活跃列表, rollout 仍有 5 秒补回准确的完成或终止分类
private func terminateSession(from event: WorkflowHookEvent) {
@@ -716,6 +1070,8 @@ final class CodexActivityMonitor: ObservableObject {
}
for (key, task) in matchingActiveTasks {
tasks.removeValue(forKey: key)
+ cancelActivityProtectionAttempt(for: key)
+ invalidateActivityProtectionNotification(for: task.displayID)
pendingTerminalTasks[key] = PendingTerminalTask(
task: task,
supersededAt: event.timestamp,
@@ -724,18 +1080,27 @@ final class CodexActivityMonitor: ObservableObject {
}
}
- /// 精确 turn 失败后回退同 session 最近活动, 再回退同项目匿名任务
- private func matchingTaskKey(for event: WorkflowHookEvent) -> CodexActivityTaskKey? {
+ /// 精确 turn 失败后只接受同 session 唯一活动任务, 有待确认旧 turn 时不猜测
+ private func matchingActiveTaskKey(for event: WorkflowHookEvent) -> CodexActivityTaskKey? {
let exactKey = CodexActivityTaskKey(event: event)
if tasks[exactKey] != nil {
return exactKey
}
- if let sessionId = event.sessionId,
- let match = tasks.values
- .filter({ $0.key.sessionId == sessionId })
- .max(by: { $0.lastActivityAt < $1.lastActivityAt }) {
- return match.key
+ if let sessionId = event.sessionId {
+ guard !pendingTerminalTasks.values.contains(where: {
+ $0.task.key.sessionId == sessionId
+ }) else {
+ return nil
+ }
+ let candidates = tasks.values.filter { task in
+ task.key.sessionId == sessionId
+ && (event.turnId == nil || task.key.isSessionOnly)
+ }
+ guard candidates.count == 1 else {
+ return nil
+ }
+ return candidates[0].key
}
let anonymousKey = CodexActivityTaskKey.anonymous(
@@ -744,9 +1109,76 @@ final class CodexActivityMonitor: ObservableObject {
return tasks[anonymousKey] == nil ? nil : anonymousKey
}
+ /// 子 Agent 的 turn_id 属于它自己, 只能在没有待确认旧 turn 时关联同 session 唯一父任务
+ private func matchingSubagentParentTaskKey(
+ for event: WorkflowHookEvent
+ ) -> CodexActivityTaskKey? {
+ guard let sessionId = event.sessionId,
+ !pendingTerminalTasks.values.contains(where: {
+ $0.task.key.sessionId == sessionId
+ }) else {
+ return nil
+ }
+ let candidates = tasks.values.filter { $0.key.sessionId == sessionId }
+ guard candidates.count == 1 else {
+ return nil
+ }
+ return candidates[0].key
+ }
+
+ private func matchingTerminalTask(
+ for event: WorkflowHookEvent
+ ) -> CodexTerminalTaskMatch {
+ let exactKey = CodexActivityTaskKey(event: event)
+ if pendingTerminalTasks[exactKey] != nil {
+ return .pending(exactKey)
+ }
+ if tasks[exactKey] != nil,
+ event.turnId != nil || event.sessionId == nil {
+ return .active(exactKey)
+ }
+
+ if let sessionId = event.sessionId {
+ let pendingCandidates = pendingTerminalTasks.values.filter {
+ $0.task.key.sessionId == sessionId
+ && $0.task.lastActivityAt <= event.timestamp
+ && (event.turnId == nil || $0.task.key.isSessionOnly)
+ }
+ if pendingCandidates.count == 1 {
+ return .pending(pendingCandidates[0].task.key)
+ }
+ if pendingCandidates.count > 1 {
+ return .ambiguous
+ }
+
+ let activeCandidates = tasks.values.filter {
+ $0.key.sessionId == sessionId
+ && $0.lastActivityAt <= event.timestamp
+ && (event.turnId == nil || $0.key.isSessionOnly)
+ }
+ if activeCandidates.count == 1 {
+ return .active(activeCandidates[0].key)
+ }
+ if activeCandidates.count > 1 {
+ return .ambiguous
+ }
+ }
+
+ let anonymousKey = CodexActivityTaskKey.anonymous(
+ project: CodexActivityTaskKey.projectIdentifier(event.projectDisplayName)
+ )
+ if tasks[anonymousKey] != nil {
+ return .active(anonymousKey)
+ }
+ if pendingTerminalTasks[anonymousKey] != nil {
+ return .pending(anonymousKey)
+ }
+ return .none
+ }
+
// MARK: - 快照与过期清理
- private func refreshSnapshot(now: Date) {
+ func refreshSnapshot(now: Date) {
pruneExpiredState(now: now)
let waitingTasks = sortedTasks(in: .waitingApproval)
@@ -769,6 +1201,7 @@ final class CodexActivityMonitor: ObservableObject {
}
scheduleNextCleanup(now: now, mostRecentCompletion: mostRecentCompletion)
+ scheduleNextInactivityCheck(now: now)
}
private func sortedTasks(in state: CodexActivityTaskState) -> [CodexActivityTask] {
@@ -794,8 +1227,18 @@ final class CodexActivityMonitor: ObservableObject {
finalizeExpiredPendingTerminalTasks(now: now)
let activityCutoff = now.addingTimeInterval(-Self.activityRetention)
+ let expiredTasks = tasks.filter { $0.value.lastActivityAt <= activityCutoff }
+ for (key, task) in expiredTasks {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .retention
+ )
+ }
tasks = tasks.filter { $0.value.lastActivityAt > activityCutoff }
+ removeExpiredActivityProtectionRecords(now: now)
+
let historyCutoff = now.addingTimeInterval(-Self.recentHistoryRetention)
completions.removeAll { $0.completedAt <= historyCutoff }
terminations.removeAll { $0.terminatedAt <= historyCutoff }
@@ -829,6 +1272,7 @@ final class CodexActivityMonitor: ObservableObject {
deadlines.append(contentsOf: recentlyTerminatedTaskAt.values.map {
$0.addingTimeInterval(Self.completedTaskRetention)
})
+ deadlines.append(contentsOf: activityProtectionRecords.values.map(\.expiresAt))
if let mostRecentCompletion {
let highlightDeadline = mostRecentCompletion.completedAt
.addingTimeInterval(Self.completionHighlightDuration)
@@ -862,501 +1306,9 @@ final class CodexActivityMonitor: ObservableObject {
private static let completionHighlightDuration: TimeInterval = 30
private static let recentHistoryRetention: TimeInterval = 10 * 60
- private static let completedTaskRetention: TimeInterval = 24 * 60 * 60
- private static let activityRetention = CodexActivityRetention.window
+ static let completedTaskRetention: TimeInterval = 24 * 60 * 60
+ static let activityRetention = CodexActivityRetention.window
+ static let activityProtectionNotificationSubmissionGrace: Duration = .seconds(3)
private static let supersededTerminalGracePeriod: TimeInterval = 5
private static let sessionLifecyclePollInterval: TimeInterval = 1
}
-
-private extension CodexActivityMonitor {
- // MARK: - 终态判定与记录
-
- /// PermissionRequest 表示进入审批流程; 只有 rollout 明确把审批路由给 user 时才是 UI 等待
- func resolvePendingApprovalIfPossible(
- for task: inout CodexActivityTask,
- into transitions: inout [CodexActivityTransition]
- ) -> Bool {
- guard let requestedAt = task.pendingApprovalRequestedAt,
- let approvalReviewer = task.approvalReviewer else {
- return false
- }
-
- switch approvalReviewer {
- case .user:
- let wasWaiting = task.state == .waitingApproval
- task.confirmPendingApproval()
- if !wasWaiting,
- let sessionTransitionNotBefore,
- requestedAt >= sessionTransitionNotBefore {
- transitions.append(.waitingApproval(task.snapshot))
- }
- case .autoReview, .guardianSubagent:
- task.pendingApprovalRequestedAt = nil
- }
- return true
- }
-
- /// rollout 终态归类的唯一入口; 活动任务和等待终态确认任务只有 abort 兜底时间不同
- /// 终止记录只供任务中心展示, 不发布 transition, 也不产生绿色状态或通知
- func resolveTerminal(
- _ terminal: CodexSessionTaskTerminalState,
- task: CodexActivityTask,
- key: CodexActivityTaskKey,
- abortFallback: Date,
- into transitions: inout [CodexActivityTransition]
- ) {
- switch terminal {
- case let .aborted(reportedAt):
- let terminatedAt = max(reportedAt ?? abortFallback, task.lastActivityAt)
- storeTermination(task, at: terminatedAt, includesDuration: reportedAt != nil)
- recordTerminatedTask(key, at: terminatedAt)
- case let .completed(completedAt, duration):
- let completion = storeResolvedCompletion(
- task,
- key: key,
- completedAt: completedAt,
- reportedDuration: duration
- )
- if let sessionTransitionNotBefore,
- completion.completedAt >= sessionTransitionNotBefore {
- transitions.append(.completed(completion))
- }
- }
- }
-
- static func backfilledStartedAt(
- for task: CodexActivityTask,
- state: CodexSessionTaskLifecycleState
- ) -> Date? {
- guard task.startedAt == nil,
- let startedAt = state.startedAt,
- startedAt <= task.lastActivityAt.addingTimeInterval(1) else {
- return nil
- }
- return startedAt
- }
-
- static func mergeLifecycleBackfill(
- from state: CodexSessionTaskLifecycleState,
- into task: inout CodexActivityTask
- ) -> Bool {
- var didChange = false
- if let startedAt = backfilledStartedAt(for: task, state: state) {
- task.startedAt = startedAt
- didChange = true
- }
- if task.mergeEffort(state.effort) {
- didChange = true
- }
- return didChange
- }
-
- func storeResolvedCompletion(
- _ task: CodexActivityTask,
- key: CodexActivityTaskKey,
- completedAt: Date,
- reportedDuration: TimeInterval?,
- projectName: String? = nil,
- modelName: String? = nil,
- effort: String? = nil
- ) -> CodexActivityCompletion {
- // rollout 时间戳是整秒, 避免因为同一秒内的 Hook 毫秒时间戳而把完成时间记在最后活动之前
- let recordedCompletedAt = max(completedAt, task.lastActivityAt)
- let completion = storeCompletion(
- projectName: projectName ?? task.projectName,
- modelName: modelName ?? task.modelName,
- effort: effort ?? task.effort,
- completedAt: recordedCompletedAt,
- duration: reportedDuration ?? task.preciseDuration(until: recordedCompletedAt)
- )
- recordCompletedTask(key, at: recordedCompletedAt)
- return completion
- }
-
- func storeCompletion(
- projectName: String?,
- modelName: String?,
- effort: String?,
- completedAt: Date,
- duration: TimeInterval?
- ) -> CodexActivityCompletion {
- let completion = CodexActivityCompletion(
- id: UUID(),
- projectName: projectName,
- modelName: modelName,
- effort: effort,
- completedAt: completedAt,
- duration: duration
- )
- completions.append(completion)
- return completion
- }
-
- func storeTermination(
- _ task: CodexActivityTask,
- at terminatedAt: Date,
- includesDuration: Bool
- ) {
- let termination = CodexActivityTermination(
- id: UUID(),
- projectName: task.projectName,
- modelName: task.modelName,
- effort: task.effort,
- terminatedAt: terminatedAt,
- duration: includesDuration ? task.preciseDuration(until: terminatedAt) : nil
- )
- terminations.append(termination)
- }
-
- func recentCompletionDate(
- for key: CodexActivityTaskKey,
- now: Date = Date()
- ) -> Date? {
- Self.recentTerminalDate(
- for: key,
- storedIn: &recentlyCompletedTaskAt,
- now: now
- )
- }
-
- func recentTerminationDate(
- for key: CodexActivityTaskKey,
- now: Date = Date()
- ) -> Date? {
- Self.recentTerminalDate(
- for: key,
- storedIn: &recentlyTerminatedTaskAt,
- now: now
- )
- }
-
- func recordCompletedTask(_ key: CodexActivityTaskKey, at completedAt: Date) {
- Self.recordTerminalTask(
- key,
- at: completedAt,
- storedIn: &recentlyCompletedTaskAt
- )
- }
-
- func recordTerminatedTask(_ key: CodexActivityTaskKey, at terminatedAt: Date) {
- Self.recordTerminalTask(
- key,
- at: terminatedAt,
- storedIn: &recentlyTerminatedTaskAt
- )
- }
-
- func clearCollectedActivityState() {
- tasks.removeAll()
- pendingTerminalTasks.removeAll()
- completions.removeAll()
- terminations.removeAll()
- recentlyCompletedTaskAt.removeAll()
- recentlyTerminatedTaskAt.removeAll()
- }
-
- static func recentTerminalDate(
- for key: CodexActivityTaskKey,
- storedIn dates: inout [CodexActivityTaskKey: Date],
- now: Date
- ) -> Date? {
- guard let date = dates[key] else {
- return nil
- }
- guard date > now.addingTimeInterval(-completedTaskRetention) else {
- dates.removeValue(forKey: key)
- return nil
- }
- return date
- }
-
- static func recordTerminalTask(
- _ key: CodexActivityTaskKey,
- at date: Date,
- storedIn dates: inout [CodexActivityTaskKey: Date]
- ) {
- dates[key] = max(dates[key] ?? .distantPast, date)
- if let sessionId = key.sessionId {
- let sessionKey = CodexActivityTaskKey.session(sessionId)
- dates[sessionKey] = max(dates[sessionKey] ?? .distantPast, date)
- }
- }
-
- func finalizeExpiredPendingTerminalTasks(now: Date) {
- let expiredKeys = pendingTerminalTasks.compactMap { key, pending in
- pending.deadline <= now ? key : nil
- }
- for key in expiredKeys {
- guard let pending = pendingTerminalTasks.removeValue(forKey: key) else {
- continue
- }
- let terminatedAt = max(pending.supersededAt, pending.task.lastActivityAt)
- storeTermination(pending.task, at: terminatedAt, includesDuration: true)
- recordTerminatedTask(key, at: terminatedAt)
- }
- }
-
- func publishLiveTransitions(_ transitions: [CodexActivityLiveTransition]) {
- var lastWaitingIndexByKey: [CodexActivityTaskKey: Int] = [:]
- for (index, transition) in transitions.enumerated() {
- if case let .waitingApproval(key) = transition {
- lastWaitingIndexByKey[key] = index
- }
- }
-
- var publishedCompletionIDs = Set<UUID>()
- for (index, transition) in transitions.enumerated() {
- switch transition {
- case let .waitingApproval(key):
- guard lastWaitingIndexByKey[key] == index,
- let task = tasks[key],
- task.state == .waitingApproval else {
- continue
- }
- transitionSubject.send(.waitingApproval(task.snapshot))
- case let .completed(completion):
- guard publishedCompletionIDs.insert(completion.id).inserted else {
- continue
- }
- transitionSubject.send(.completed(completion))
- }
- }
- }
-}
-
-// MARK: - 内部任务模型
-
-private enum CodexActivityTaskKey: Hashable {
- case turn(session: String, turn: String)
- case session(String)
- case anonymous(project: String)
-
- init(event: WorkflowHookEvent) {
- if let sessionId = event.sessionId, let turnId = event.turnId {
- self = .turn(session: sessionId, turn: turnId)
- } else if let sessionId = event.sessionId {
- self = .session(sessionId)
- } else {
- self = .anonymous(project: Self.projectIdentifier(event.projectDisplayName))
- }
- }
-
- var sessionId: String? {
- switch self {
- case let .turn(session, _), let .session(session): session
- case .anonymous: nil
- }
- }
-
- var isAnonymous: Bool {
- if case .anonymous = self {
- return true
- }
- return false
- }
-
- static func projectIdentifier(_ project: String?) -> String {
- project ?? "__codex__"
- }
-}
-
-private enum CodexActivityLiveTransition {
- case waitingApproval(CodexActivityTaskKey)
- case completed(CodexActivityCompletion)
-}
-
-private enum CodexActivityTaskState {
- case running
- case waitingApproval
-}
-
-private struct PendingTerminalTask {
- var task: CodexActivityTask
- let supersededAt: Date
- let deadline: Date
-}
-
-private struct CodexActivityTask {
- let displayID: UUID
- let key: CodexActivityTaskKey
- var state: CodexActivityTaskState
- var latestEvent: CodexActivityEvent
- var projectName: String?
- var modelName: String?
- var effort: String?
- var toolName: String?
- var startedAt: Date?
- var stateChangedAt: Date
- var lastActivityAt: Date
- var approvalReviewer: CodexApprovalReviewer?
- var pendingApprovalRequestedAt: Date?
- var subagentsByID: [String: CodexSubagentObservation]
- var isSubagentCountReliable: Bool
-
- init(
- displayID: UUID,
- key: CodexActivityTaskKey,
- event: WorkflowHookEvent,
- state: CodexActivityTaskState,
- latestEvent: CodexActivityEvent,
- startedAt: Date?
- ) {
- self.displayID = displayID
- self.key = key
- self.state = state
- self.latestEvent = latestEvent
- projectName = event.projectDisplayName
- modelName = event.modelName
- effort = Self.normalizedEffort(event.effort)
- toolName = event.toolName
- self.startedAt = startedAt
- stateChangedAt = event.timestamp
- lastActivityAt = event.timestamp
- approvalReviewer = event.approvalReviewer
- pendingApprovalRequestedAt = nil
- subagentsByID = [:]
- isSubagentCountReliable = startedAt != nil
- }
-
- var showsPreciseDuration: Bool {
- startedAt != nil && !key.isAnonymous
- }
-
- /// 起点可信时返回到 end 的精确耗时, 起点缺失或晚于 end 时为 nil
- func preciseDuration(until end: Date) -> TimeInterval? {
- guard showsPreciseDuration, let startedAt, end >= startedAt else {
- return nil
- }
- return end.timeIntervalSince(startedAt)
- }
-
- var snapshot: CodexActivityTaskSnapshot {
- CodexActivityTaskSnapshot(
- id: displayID,
- latestEvent: latestEvent,
- projectName: projectName,
- modelName: modelName,
- effort: effort,
- toolName: toolName,
- startedAt: startedAt,
- stateChangedAt: stateChangedAt,
- showsPreciseDuration: showsPreciseDuration,
- activeSubagentCount: activeSubagentCount
- )
- }
-
- var turnReference: CodexActivityTurnReference? {
- guard case let .turn(sessionId, turnId) = key else {
- return nil
- }
- return CodexActivityTurnReference(
- sessionId: sessionId,
- turnId: turnId,
- startedAt: startedAt ?? lastActivityAt
- )
- }
-
- var promptReference: CodexActivityPromptReference? {
- guard startedAt == nil,
- case let .turn(sessionId, turnId) = key else {
- return nil
- }
- return CodexActivityPromptReference(sessionId: sessionId, turnId: turnId)
- }
-
- mutating func mergeMetadata(from event: WorkflowHookEvent) {
- projectName = event.projectDisplayName ?? projectName
- modelName = event.modelName ?? modelName
- _ = mergeEffort(event.effort)
- toolName = event.toolName ?? toolName
- approvalReviewer = event.approvalReviewer ?? approvalReviewer
- }
-
- @discardableResult
- mutating func mergeEffort(_ incomingEffort: String?) -> Bool {
- guard let incomingEffort = Self.normalizedEffort(incomingEffort) else {
- return false
- }
- guard let effort else {
- effort = incomingEffort
- return true
- }
- guard effort != incomingEffort, effort != "mixed" else {
- return false
- }
- self.effort = "mixed"
- return true
- }
-
- mutating func recordSubagentActivity(
- agentId: String?,
- isStarting: Bool,
- at timestamp: Date,
- hasReliableTaskAssociation: Bool
- ) {
- guard hasReliableTaskAssociation, let agentId else {
- isSubagentCountReliable = false
- return
- }
-
- let previous = subagentsByID[agentId]
- if let previous, timestamp < previous.timestamp {
- return
- }
- if !isStarting, previous == nil {
- isSubagentCountReliable = false
- }
- subagentsByID[agentId] = CodexSubagentObservation(
- isRunning: isStarting,
- timestamp: timestamp
- )
- }
-
- private var activeSubagentCount: Int? {
- guard isSubagentCountReliable else {
- return nil
- }
- return subagentsByID.values.reduce(into: 0) { count, observation in
- if observation.isRunning {
- count += 1
- }
- }
- }
-
- private static func normalizedEffort(_ effort: String?) -> String? {
- guard let effort else {
- return nil
- }
- let value = effort.trimmingCharacters(in: .whitespacesAndNewlines)
- return value.isEmpty ? nil : value
- }
-
- /// 记录审批候选; 返回值只表示任务是否刚刚进入用户等待状态
- mutating func recordApprovalRequest(at requestedAt: Date) -> Bool {
- pendingApprovalRequestedAt = requestedAt
- guard approvalReviewer == .user else {
- return false
- }
-
- let enteredWaiting = state != .waitingApproval
- confirmPendingApproval()
- return enteredWaiting
- }
-
- mutating func confirmPendingApproval() {
- guard let requestedAt = pendingApprovalRequestedAt else {
- return
- }
- pendingApprovalRequestedAt = nil
- if state != .waitingApproval {
- state = .waitingApproval
- stateChangedAt = requestedAt
- }
- latestEvent = .approvalRequested
- }
-}
-
-private struct CodexSubagentObservation {
- let isRunning: Bool
- let timestamp: Date
-}
diff --git a/CodexBar/Services/Workflow/CodexActivityProtection.swift b/CodexBar/Services/Workflow/CodexActivityProtection.swift
new file mode 100644
index 0000000..6992e4c
--- /dev/null
+++ b/CodexBar/Services/Workflow/CodexActivityProtection.swift
@@ -0,0 +1,574 @@
+import Foundation
+import os
+
+extension CodexActivityMonitor {
+ // MARK: - 异常任务保护
+
+ private var canEvaluateActivityProtection: Bool {
+ isStarted
+ && isActivityProtectionEnabled
+ && tailReader != nil
+ && !isBootstrapping
+ && !isActivityProtectionRecoveryInProgress
+ && isActivitySourceHealthy
+ }
+
+ func setActivityProtectionEnabled(_ enabled: Bool) {
+ guard enabled != isActivityProtectionEnabled else {
+ return
+ }
+ isActivityProtectionEnabled = enabled
+ cancelInactivityCheck()
+ cancelAllActivityProtectionAttempts()
+
+ guard isStarted else {
+ return
+ }
+
+ let now = Date()
+ guard enabled else {
+ restoreAllSuppressedActivityTasks(restoredAt: now)
+ refreshSnapshot(now: now)
+ return
+ }
+ reconcileActivityProtection(now: now, sendsNotification: false)
+ }
+
+ func handleActivityProtectionTimingChange() {
+ cancelAllActivityProtectionAttempts()
+ reconcileActivityProtection(now: Date(), sendsNotification: false)
+ }
+
+ @discardableResult
+ func beginActivityProtectionRecovery() -> UInt64 {
+ activityProtectionRecoveryGeneration &+= 1
+ isActivityProtectionRecoveryInProgress = true
+ cancelInactivityCheck()
+ cancelAllActivityProtectionAttempts()
+ return activityProtectionRecoveryGeneration
+ }
+
+ func finishActivityProtectionRecovery(generation: UInt64) {
+ guard generation == activityProtectionRecoveryGeneration else {
+ return
+ }
+ isActivityProtectionRecoveryInProgress = false
+ reconcileActivityProtection(now: Date(), sendsNotification: false)
+ }
+
+ func resetActivityProtectionRecovery() {
+ activityProtectionRecoveryGeneration &+= 1
+ isActivityProtectionRecoveryInProgress = false
+ cancelAllActivityProtectionAttempts()
+ }
+
+ func applyPersistedActivityProtection(now: Date) {
+ removeExpiredActivityProtectionRecords(now: now)
+
+ guard isActivityProtectionEnabled else {
+ return
+ }
+
+ for (key, var task) in tasks {
+ let identifier = key.activityProtectionIdentifier
+ guard let record = activityProtectionRecords[identifier] else {
+ continue
+ }
+
+ if task.state == .waitingApproval || task.lastProgressAt > record.lastProgressAt {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .progress
+ )
+ continue
+ }
+
+ task.state = .suppressed
+ task.stateChangedAt = record.markedAt
+ tasks[key] = task
+ }
+ }
+
+ func reconcileActivityProtection(
+ now: Date,
+ sendsNotification: Bool
+ ) {
+ guard canEvaluateActivityProtection else {
+ cancelInactivityCheck()
+ refreshSnapshot(now: now)
+ return
+ }
+
+ if sendsNotification {
+ beginDueInactivityChecks(now: now)
+ return
+ }
+
+ let threshold = activityProtectionSettings.inactivityDuration.timeInterval
+ let restorableKeys = tasks.compactMap { key, task -> CodexActivityTaskKey? in
+ guard task.state == .suppressed,
+ task.lastProgressAt.addingTimeInterval(threshold) > now else {
+ return nil
+ }
+ return key
+ }
+ for key in restorableKeys {
+ restoreActivityTaskForCurrentThreshold(key, restoredAt: now)
+ }
+
+ let overdueKeys = tasks.compactMap { key, task -> CodexActivityTaskKey? in
+ guard task.state == .running,
+ task.lastProgressAt.addingTimeInterval(threshold) <= now else {
+ return nil
+ }
+ return key
+ }
+ for key in overdueKeys {
+ suppressActivityTaskSilently(key, markedAt: now)
+ }
+ refreshSnapshot(now: now)
+ }
+
+ func scheduleNextInactivityCheck(now: Date) {
+ guard canEvaluateActivityProtection else {
+ cancelInactivityCheck()
+ return
+ }
+
+ let threshold = activityProtectionSettings.inactivityDuration.timeInterval
+ let nextDeadline = tasks.compactMap { key, task -> Date? in
+ guard task.state == .running,
+ activityProtectionAttempts[key] == nil else {
+ return nil
+ }
+ return task.lastProgressAt.addingTimeInterval(threshold)
+ }.min()
+
+ guard let nextDeadline else {
+ cancelInactivityCheck()
+ return
+ }
+ guard inactivityCheckTask == nil || inactivityCheckDeadline != nextDeadline else {
+ return
+ }
+
+ cancelInactivityCheck()
+ inactivityCheckDeadline = nextDeadline
+ let remaining = max(0, nextDeadline.timeIntervalSince(now))
+ let deadline = SuspendingClock.Instant.now.advanced(by: .seconds(remaining))
+ inactivityCheckTask = Task { @MainActor [weak self] in
+ try? await Task.sleep(until: deadline, clock: SuspendingClock())
+ guard let self, !Task.isCancelled else {
+ return
+ }
+ inactivityCheckTask = nil
+ inactivityCheckDeadline = nil
+ reconcileActivityProtection(now: Date(), sendsNotification: true)
+ }
+ }
+
+ func cancelInactivityCheck() {
+ inactivityCheckTask?.cancel()
+ inactivityCheckTask = nil
+ inactivityCheckDeadline = nil
+ }
+
+ func beginDueInactivityChecks(now: Date) {
+ guard isActivityProtectionEnabled,
+ !isActivityProtectionRecoveryInProgress else {
+ refreshSnapshot(now: now)
+ return
+ }
+
+ let threshold = activityProtectionSettings.inactivityDuration.timeInterval
+ let candidates = tasks.compactMap { key, task -> ActivityProtectionCandidate? in
+ guard task.state == .running,
+ activityProtectionAttempts[key] == nil,
+ task.lastProgressAt.addingTimeInterval(threshold) <= now else {
+ return nil
+ }
+ return ActivityProtectionCandidate(
+ key: key,
+ taskID: task.displayID,
+ projectName: task.projectName,
+ lastProgressAt: task.lastProgressAt,
+ progressGeneration: task.progressGeneration,
+ inactivityDuration: activityProtectionSettings.inactivityDuration
+ )
+ }
+
+ for candidate in candidates {
+ beginActivityProtectionAttempt(candidate)
+ }
+ refreshSnapshot(now: now)
+ }
+
+ func beginActivityProtectionAttempt(_ candidate: ActivityProtectionCandidate) {
+ guard isActivityProtectionCandidateRelevant(candidate, now: Date()) else {
+ return
+ }
+
+ invalidateActivityProtectionNotification(for: candidate.taskID)
+
+ let attemptID = UUID()
+ let markedAt = Date()
+ persistActivityProtectionRecord(
+ for: candidate.key,
+ lastProgressAt: candidate.lastProgressAt,
+ markedAt: markedAt
+ )
+
+ let timeoutTask = Task { @MainActor [weak self] in
+ try? await Task.sleep(for: Self.activityProtectionNotificationSubmissionGrace)
+ guard let self, !Task.isCancelled else {
+ return
+ }
+ finishActivityProtectionAttempt(
+ candidate.key,
+ attemptID: attemptID,
+ taskID: candidate.taskID,
+ notificationWasSubmitted: false
+ )
+ }
+ activityProtectionAttempts[candidate.key] = ActivityProtectionAttempt(
+ id: attemptID,
+ candidate: candidate,
+ markedAt: markedAt,
+ timeoutTask: timeoutTask
+ )
+ activityProtectionNoticeAttemptIDs[candidate.taskID] = attemptID
+
+ let notice = CodexActivityProtectionNotice(
+ taskID: candidate.taskID,
+ attemptID: attemptID,
+ projectName: candidate.projectName,
+ inactivityDurationText: candidate.inactivityDuration.title,
+ inactivityDurationSeconds: candidate.inactivityDuration.rawValue,
+ progressGeneration: candidate.progressGeneration
+ )
+ let notificationHandler = onInactivityProtectionTriggered
+ Task { @MainActor [weak self] in
+ let notificationWasSubmitted = await notificationHandler?(notice) ?? false
+ self?.finishActivityProtectionAttempt(
+ candidate.key,
+ attemptID: attemptID,
+ taskID: candidate.taskID,
+ notificationWasSubmitted: notificationWasSubmitted
+ )
+ }
+ }
+
+ func finishActivityProtectionAttempt(
+ _ key: CodexActivityTaskKey,
+ attemptID: UUID,
+ taskID: UUID,
+ notificationWasSubmitted: Bool
+ ) {
+ guard let attempt = activityProtectionAttempts[key],
+ attempt.id == attemptID else {
+ if notificationWasSubmitted {
+ onInactivityProtectionInvalidated?(taskID, attemptID)
+ }
+ return
+ }
+
+ guard isActivityProtectionCandidateRelevant(attempt.candidate, now: Date()) else {
+ cancelActivityProtectionAttempt(for: key, matching: attemptID)
+ refreshSnapshot(now: Date())
+ return
+ }
+
+ attempt.timeoutTask.cancel()
+ activityProtectionAttempts.removeValue(forKey: key)
+ if !notificationWasSubmitted {
+ invalidateActivityProtectionNotification(
+ for: attempt.candidate.taskID,
+ matching: attemptID
+ )
+ }
+
+ guard var task = tasks[key] else {
+ return
+ }
+ task.state = .suppressed
+ task.stateChangedAt = attempt.markedAt
+ tasks[key] = task
+ AppLog.activity.notice(
+ "异常任务已隐藏: thresholdMinutes=\(attempt.candidate.inactivityDuration.loggedMinutes)"
+ )
+ refreshSnapshot(now: Date())
+ }
+
+ func suppressActivityTaskSilently(
+ _ key: CodexActivityTaskKey,
+ markedAt: Date
+ ) {
+ cancelActivityProtectionAttempt(for: key)
+ guard var task = tasks[key], task.state == .running else {
+ return
+ }
+
+ persistActivityProtectionRecord(
+ for: key,
+ lastProgressAt: task.lastProgressAt,
+ markedAt: markedAt
+ )
+ task.state = .suppressed
+ task.stateChangedAt = markedAt
+ tasks[key] = task
+ AppLog.activity.notice("异常任务已静默隐藏: reason=reconcile")
+ }
+
+ func suppressBackfilledActivityTaskIfOverdue(
+ _ key: CodexActivityTaskKey,
+ now: Date
+ ) {
+ guard isStarted,
+ isActivityProtectionEnabled,
+ tailReader != nil,
+ !isBootstrapping,
+ isActivitySourceHealthy,
+ let task = tasks[key],
+ task.state == .running,
+ task.lastProgressAt.addingTimeInterval(
+ activityProtectionSettings.inactivityDuration.timeInterval
+ ) <= now else {
+ return
+ }
+ suppressActivityTaskSilently(key, markedAt: now)
+ }
+
+ func restoreActivityTaskForCurrentThreshold(
+ _ key: CodexActivityTaskKey,
+ restoredAt: Date
+ ) {
+ guard var task = tasks[key], task.state == .suppressed else {
+ return
+ }
+
+ task.state = .running
+ task.stateChangedAt = restoredAt
+ tasks[key] = task
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .thresholdChange
+ )
+ AppLog.activity.notice("异常任务已静默恢复: reason=thresholdChange")
+ }
+
+ func restoreAllSuppressedActivityTasks(restoredAt: Date) {
+ let suppressedKeys = tasks.compactMap { key, task in
+ task.state == .suppressed ? key : nil
+ }
+ for key in suppressedKeys {
+ guard var task = tasks[key] else {
+ continue
+ }
+ task.state = .running
+ task.stateChangedAt = restoredAt
+ tasks[key] = task
+ invalidateActivityProtectionNotification(for: task.displayID)
+ }
+ for (taskID, attemptID) in Array(activityProtectionNoticeAttemptIDs) {
+ invalidateActivityProtectionNotification(for: taskID, matching: attemptID)
+ }
+ if !suppressedKeys.isEmpty {
+ AppLog.activity.notice(
+ "异常任务已全部恢复: reason=keepAliveDisabled; count=\(suppressedKeys.count)"
+ )
+ }
+ }
+
+ func isActivityProtectionCandidateRelevant(
+ _ candidate: ActivityProtectionCandidate,
+ now: Date
+ ) -> Bool {
+ guard canEvaluateActivityProtection,
+ activityProtectionSettings.inactivityDuration == candidate.inactivityDuration,
+ let task = tasks[candidate.key],
+ task.displayID == candidate.taskID,
+ task.state == .running,
+ task.lastProgressAt == candidate.lastProgressAt,
+ task.progressGeneration == candidate.progressGeneration else {
+ return false
+ }
+ return task.lastProgressAt
+ .addingTimeInterval(candidate.inactivityDuration.timeInterval) <= now
+ }
+
+ func isInactivityProtectionNoticeRelevant(
+ taskID: UUID,
+ attemptID: UUID,
+ progressGeneration: UInt64,
+ inactivityDurationSeconds: Int
+ ) -> Bool {
+ guard canEvaluateActivityProtection,
+ activityProtectionSettings.inactivityDuration.rawValue == inactivityDurationSeconds,
+ activityProtectionNoticeAttemptIDs[taskID] == attemptID,
+ let attempt = activityProtectionAttempts.values.first(where: {
+ $0.id == attemptID && $0.candidate.taskID == taskID
+ }) else {
+ return false
+ }
+
+ let now = Date()
+ guard let task = tasks[attempt.candidate.key] else {
+ return false
+ }
+ return task.displayID == taskID
+ && task.state == .running
+ && task.progressGeneration == progressGeneration
+ && task.lastProgressAt.addingTimeInterval(
+ activityProtectionSettings.inactivityDuration.timeInterval
+ ) <= now
+ }
+
+ func shouldRestoreActivityProtection(
+ for key: CodexActivityTaskKey,
+ progressAt: Date
+ ) -> Bool {
+ guard let record = activityProtectionRecords[key.activityProtectionIdentifier] else {
+ return true
+ }
+ return progressAt > record.lastProgressAt
+ }
+
+ func clearActivityProtection(
+ for key: CodexActivityTaskKey,
+ taskID: UUID?,
+ reason: ActivityProtectionClearReason
+ ) {
+ cancelActivityProtectionAttempt(for: key)
+ let identifier = key.activityProtectionIdentifier
+ let record = activityProtectionRecords.removeValue(forKey: identifier)
+ if let record {
+ let matchingMarkedAt: Date? = switch reason {
+ case .progress, .thresholdChange: record.markedAt
+ case .terminal, .retention: nil
+ }
+ enqueueActivityProtectionPersistence(
+ removals: [
+ ActivityProtectionRemoval(
+ taskIdentifier: identifier,
+ matchingMarkedAt: matchingMarkedAt
+ )
+ ]
+ )
+ }
+ if let taskID {
+ invalidateActivityProtectionNotification(for: taskID)
+ }
+ }
+
+ func invalidateActivityProtectionNotification(for taskID: UUID) {
+ guard let attemptID = activityProtectionNoticeAttemptIDs[taskID] else {
+ return
+ }
+ invalidateActivityProtectionNotification(for: taskID, matching: attemptID)
+ }
+
+ func invalidateActivityProtectionNotification(
+ for taskID: UUID,
+ matching attemptID: UUID
+ ) {
+ guard activityProtectionNoticeAttemptIDs[taskID] == attemptID else {
+ return
+ }
+ activityProtectionNoticeAttemptIDs.removeValue(forKey: taskID)
+ onInactivityProtectionInvalidated?(taskID, attemptID)
+ }
+
+ func cancelActivityProtectionAttempt(
+ for key: CodexActivityTaskKey,
+ matching attemptID: UUID? = nil
+ ) {
+ guard let attempt = activityProtectionAttempts[key],
+ attemptID == nil || attempt.id == attemptID else {
+ return
+ }
+
+ attempt.timeoutTask.cancel()
+ activityProtectionAttempts.removeValue(forKey: key)
+
+ let identifier = key.activityProtectionIdentifier
+ if let record = activityProtectionRecords[identifier],
+ record.markedAt == attempt.markedAt {
+ activityProtectionRecords.removeValue(forKey: identifier)
+ enqueueActivityProtectionPersistence(
+ removals: [
+ ActivityProtectionRemoval(
+ taskIdentifier: identifier,
+ matchingMarkedAt: attempt.markedAt
+ )
+ ]
+ )
+ }
+ invalidateActivityProtectionNotification(
+ for: attempt.candidate.taskID,
+ matching: attempt.id
+ )
+ }
+
+ func cancelAllActivityProtectionAttempts() {
+ for key in Array(activityProtectionAttempts.keys) {
+ cancelActivityProtectionAttempt(for: key)
+ }
+ }
+
+ func removeExpiredActivityProtectionRecords(now: Date) {
+ let expiredIdentifiers = activityProtectionRecords.compactMap { identifier, record in
+ record.expiresAt <= now ? identifier : nil
+ }
+ guard !expiredIdentifiers.isEmpty else {
+ return
+ }
+
+ for identifier in expiredIdentifiers {
+ activityProtectionRecords.removeValue(forKey: identifier)
+ }
+ enqueueActivityProtectionPersistence(
+ removals: expiredIdentifiers.map {
+ ActivityProtectionRemoval(taskIdentifier: $0)
+ }
+ )
+ }
+
+ func persistActivityProtectionRecord(
+ for key: CodexActivityTaskKey,
+ lastProgressAt: Date,
+ markedAt: Date
+ ) {
+ let record = ActivityProtectionRecord(
+ taskIdentifier: key.activityProtectionIdentifier,
+ lastProgressAt: lastProgressAt,
+ markedAt: markedAt,
+ expiresAt: lastProgressAt.addingTimeInterval(Self.activityRetention)
+ )
+ activityProtectionRecords[record.taskIdentifier] = record
+ enqueueActivityProtectionPersistence(upserts: [record])
+ }
+
+ func enqueueActivityProtectionPersistence(
+ upserts: [ActivityProtectionRecord] = [],
+ removals: [ActivityProtectionRemoval] = []
+ ) {
+ let previousTask = activityProtectionPersistenceTask
+ let stateStore = activityProtectionStateStore
+ let task = Task { @MainActor in
+ await previousTask?.value
+ do {
+ try await stateStore.apply(
+ upserts: upserts,
+ removals: removals
+ )
+ } catch {
+ AppLog.activity.error(
+ "异常任务状态写入失败: reason=\(error.localizedDescription, privacy: .public)"
+ )
+ }
+ }
+ activityProtectionPersistenceTask = task
+ }
+}
diff --git a/CodexBar/Services/Workflow/CodexActivityTask.swift b/CodexBar/Services/Workflow/CodexActivityTask.swift
new file mode 100644
index 0000000..5f1bbae
--- /dev/null
+++ b/CodexBar/Services/Workflow/CodexActivityTask.swift
@@ -0,0 +1,306 @@
+import CryptoKit
+import Foundation
+
+enum CodexActivityTaskKey: Hashable {
+ case turn(session: String, turn: String)
+ case session(String)
+ case anonymous(project: String)
+
+ init(event: WorkflowHookEvent) {
+ if let sessionId = event.sessionId, let turnId = event.turnId {
+ self = .turn(session: sessionId, turn: turnId)
+ } else if let sessionId = event.sessionId {
+ self = .session(sessionId)
+ } else {
+ self = .anonymous(project: Self.projectIdentifier(event.projectDisplayName))
+ }
+ }
+
+ var sessionId: String? {
+ switch self {
+ case let .turn(session, _), let .session(session): session
+ case .anonymous: nil
+ }
+ }
+
+ var isAnonymous: Bool {
+ if case .anonymous = self {
+ return true
+ }
+ return false
+ }
+
+ var isSessionOnly: Bool {
+ if case .session = self {
+ return true
+ }
+ return false
+ }
+
+ var activityProtectionIdentifier: String {
+ let value = switch self {
+ case let .turn(session, turn):
+ "turn\u{0}\(session)\u{0}\(turn)"
+ case let .session(session):
+ "session\u{0}\(session)"
+ case let .anonymous(project):
+ "anonymous\u{0}\(project)"
+ }
+ let data = Data("CodexBar.ActivityProtection.v1\u{0}\(value)".utf8)
+ return SHA256.hash(data: data).map {
+ String(format: "%02x", $0)
+ }.joined()
+ }
+
+ static func projectIdentifier(_ project: String?) -> String {
+ project ?? "__codex__"
+ }
+}
+
+enum CodexActivityLiveTransition {
+ case waitingApproval(CodexActivityTaskKey)
+ case completed(CodexActivityCompletion)
+}
+
+enum CodexActivityEventSource {
+ case bootstrap
+ case live
+}
+
+enum CodexTerminalTaskMatch {
+ case active(CodexActivityTaskKey)
+ case pending(CodexActivityTaskKey)
+ case ambiguous
+ case none
+}
+
+enum ActivityProtectionClearReason {
+ case progress
+ case thresholdChange
+ case terminal
+ case retention
+}
+
+struct ActivityProtectionCandidate {
+ let key: CodexActivityTaskKey
+ let taskID: UUID
+ let projectName: String?
+ let lastProgressAt: Date
+ let progressGeneration: UInt64
+ let inactivityDuration: ActivityProtectionSettings.InactivityDuration
+}
+
+struct ActivityProtectionAttempt {
+ let id: UUID
+ let candidate: ActivityProtectionCandidate
+ let markedAt: Date
+ let timeoutTask: Task<Void, Never>
+}
+
+enum CodexActivityTaskState: Equatable {
+ case running
+ case waitingApproval
+ case suppressed
+}
+
+struct PendingTerminalTask {
+ var task: CodexActivityTask
+ let supersededAt: Date
+ let deadline: Date
+}
+
+struct CodexActivityTask {
+ let displayID: UUID
+ let key: CodexActivityTaskKey
+ var state: CodexActivityTaskState
+ var latestEvent: CodexActivityEvent
+ var projectName: String?
+ var modelName: String?
+ var effort: String?
+ var toolName: String?
+ var startedAt: Date?
+ var stateChangedAt: Date
+ var lastActivityAt: Date
+ var lastProgressAt: Date
+ var progressGeneration: UInt64
+ var approvalReviewer: CodexApprovalReviewer?
+ var pendingApprovalRequestedAt: Date?
+ var subagentsByID: [String: CodexSubagentObservation]
+ var isSubagentCountReliable: Bool
+
+ init(
+ displayID: UUID,
+ key: CodexActivityTaskKey,
+ event: WorkflowHookEvent,
+ state: CodexActivityTaskState,
+ latestEvent: CodexActivityEvent,
+ startedAt: Date?,
+ progressGeneration: UInt64
+ ) {
+ self.displayID = displayID
+ self.key = key
+ self.state = state
+ self.latestEvent = latestEvent
+ projectName = event.projectDisplayName
+ modelName = event.modelName
+ effort = Self.normalizedEffort(event.effort)
+ toolName = event.toolName
+ self.startedAt = startedAt
+ stateChangedAt = event.timestamp
+ lastActivityAt = event.timestamp
+ lastProgressAt = event.timestamp
+ self.progressGeneration = progressGeneration
+ approvalReviewer = event.approvalReviewer
+ pendingApprovalRequestedAt = nil
+ subagentsByID = [:]
+ isSubagentCountReliable = startedAt != nil
+ }
+
+ var showsPreciseDuration: Bool {
+ startedAt != nil && !key.isAnonymous
+ }
+
+ /// 起点可信时返回到 end 的精确耗时, 起点缺失或晚于 end 时为 nil
+ func preciseDuration(until end: Date) -> TimeInterval? {
+ guard showsPreciseDuration, let startedAt, end >= startedAt else {
+ return nil
+ }
+ return end.timeIntervalSince(startedAt)
+ }
+
+ var snapshot: CodexActivityTaskSnapshot {
+ CodexActivityTaskSnapshot(
+ id: displayID,
+ latestEvent: latestEvent,
+ projectName: projectName,
+ modelName: modelName,
+ effort: effort,
+ toolName: toolName,
+ startedAt: startedAt,
+ stateChangedAt: stateChangedAt,
+ showsPreciseDuration: showsPreciseDuration,
+ activeSubagentCount: activeSubagentCount
+ )
+ }
+
+ var turnReference: CodexActivityTurnReference? {
+ guard case let .turn(sessionId, turnId) = key else {
+ return nil
+ }
+ return CodexActivityTurnReference(
+ sessionId: sessionId,
+ turnId: turnId,
+ startedAt: startedAt ?? lastActivityAt
+ )
+ }
+
+ var promptReference: CodexActivityPromptReference? {
+ guard startedAt == nil,
+ case let .turn(sessionId, turnId) = key else {
+ return nil
+ }
+ return CodexActivityPromptReference(sessionId: sessionId, turnId: turnId)
+ }
+
+ mutating func mergeMetadata(from event: WorkflowHookEvent) {
+ projectName = event.projectDisplayName ?? projectName
+ modelName = event.modelName ?? modelName
+ _ = mergeEffort(event.effort)
+ toolName = event.toolName ?? toolName
+ approvalReviewer = event.approvalReviewer ?? approvalReviewer
+ }
+
+ mutating func recordProgress(at timestamp: Date) {
+ lastActivityAt = max(lastActivityAt, timestamp)
+ lastProgressAt = timestamp
+ progressGeneration &+= 1
+ }
+
+ @discardableResult
+ mutating func mergeEffort(_ incomingEffort: String?) -> Bool {
+ guard let incomingEffort = Self.normalizedEffort(incomingEffort) else {
+ return false
+ }
+ guard let effort else {
+ effort = incomingEffort
+ return true
+ }
+ guard effort != incomingEffort, effort != "mixed" else {
+ return false
+ }
+ self.effort = "mixed"
+ return true
+ }
+
+ mutating func recordSubagentActivity(
+ agentId: String?,
+ isStarting: Bool,
+ at timestamp: Date,
+ hasReliableTaskAssociation: Bool
+ ) {
+ guard hasReliableTaskAssociation, let agentId else {
+ isSubagentCountReliable = false
+ return
+ }
+
+ let previous = subagentsByID[agentId]
+ if let previous, timestamp < previous.timestamp {
+ return
+ }
+ if !isStarting, previous == nil {
+ isSubagentCountReliable = false
+ }
+ subagentsByID[agentId] = CodexSubagentObservation(
+ isRunning: isStarting,
+ timestamp: timestamp
+ )
+ }
+
+ private var activeSubagentCount: Int? {
+ guard isSubagentCountReliable else {
+ return nil
+ }
+ return subagentsByID.values.reduce(into: 0) { count, observation in
+ if observation.isRunning {
+ count += 1
+ }
+ }
+ }
+
+ private static func normalizedEffort(_ effort: String?) -> String? {
+ guard let effort else {
+ return nil
+ }
+ let value = effort.trimmingCharacters(in: .whitespacesAndNewlines)
+ return value.isEmpty ? nil : value
+ }
+
+ /// 记录审批候选; 返回值只表示任务是否刚刚进入用户等待状态
+ mutating func recordApprovalRequest(at requestedAt: Date) -> Bool {
+ pendingApprovalRequestedAt = requestedAt
+ guard approvalReviewer == .user else {
+ return false
+ }
+
+ let enteredWaiting = state != .waitingApproval
+ confirmPendingApproval()
+ return enteredWaiting
+ }
+
+ mutating func confirmPendingApproval() {
+ guard let requestedAt = pendingApprovalRequestedAt else {
+ return
+ }
+ pendingApprovalRequestedAt = nil
+ if state != .waitingApproval {
+ state = .waitingApproval
+ stateChangedAt = requestedAt
+ }
+ latestEvent = .approvalRequested
+ }
+}
+
+struct CodexSubagentObservation {
+ let isRunning: Bool
+ let timestamp: Date
+}
diff --git a/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift b/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift
new file mode 100644
index 0000000..5b39056
--- /dev/null
+++ b/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift
@@ -0,0 +1,276 @@
+import Combine
+import Foundation
+
+extension CodexActivityMonitor {
+ // MARK: - 终态判定与记录
+
+ /// PermissionRequest 表示进入审批流程; 只有 rollout 明确把审批路由给 user 时才是 UI 等待
+ func resolvePendingApprovalIfPossible(
+ for task: inout CodexActivityTask,
+ into transitions: inout [CodexActivityTransition]
+ ) -> Bool {
+ guard let requestedAt = task.pendingApprovalRequestedAt,
+ let approvalReviewer = task.approvalReviewer else {
+ return false
+ }
+
+ switch approvalReviewer {
+ case .user:
+ let wasWaiting = task.state == .waitingApproval
+ task.confirmPendingApproval()
+ if !wasWaiting,
+ let sessionTransitionNotBefore,
+ requestedAt >= sessionTransitionNotBefore {
+ transitions.append(.waitingApproval(task.snapshot))
+ }
+ case .autoReview, .guardianSubagent:
+ task.pendingApprovalRequestedAt = nil
+ }
+ return true
+ }
+
+ /// rollout 终态归类的唯一入口; 活动任务和等待终态确认任务只有 abort 兜底时间不同
+ /// 终止记录只供任务中心展示, 不发布 transition, 也不产生绿色状态或通知
+ func resolveTerminal(
+ _ terminal: CodexSessionTaskTerminalState,
+ task: CodexActivityTask,
+ key: CodexActivityTaskKey,
+ abortFallback: Date,
+ into transitions: inout [CodexActivityTransition]
+ ) {
+ clearActivityProtection(
+ for: key,
+ taskID: task.displayID,
+ reason: .terminal
+ )
+ switch terminal {
+ case let .aborted(reportedAt):
+ let terminatedAt = max(reportedAt ?? abortFallback, task.lastActivityAt)
+ storeTermination(task, at: terminatedAt, includesDuration: reportedAt != nil)
+ recordTerminatedTask(key, at: terminatedAt)
+ case let .completed(completedAt, duration):
+ let completion = storeResolvedCompletion(
+ task,
+ key: key,
+ completedAt: completedAt,
+ reportedDuration: duration
+ )
+ if let sessionTransitionNotBefore,
+ completion.completedAt >= sessionTransitionNotBefore {
+ transitions.append(.completed(completion))
+ }
+ }
+ }
+
+ static func backfilledStartedAt(
+ for task: CodexActivityTask,
+ state: CodexSessionTaskLifecycleState
+ ) -> Date? {
+ guard task.startedAt == nil,
+ let startedAt = state.startedAt,
+ startedAt <= task.lastActivityAt.addingTimeInterval(1) else {
+ return nil
+ }
+ return startedAt
+ }
+
+ static func mergeLifecycleBackfill(
+ from state: CodexSessionTaskLifecycleState,
+ into task: inout CodexActivityTask
+ ) -> Bool {
+ var didChange = false
+ if let startedAt = backfilledStartedAt(for: task, state: state) {
+ task.startedAt = startedAt
+ didChange = true
+ }
+ if task.mergeEffort(state.effort) {
+ didChange = true
+ }
+ return didChange
+ }
+
+ func storeResolvedCompletion(
+ _ task: CodexActivityTask,
+ key: CodexActivityTaskKey,
+ completedAt: Date,
+ reportedDuration: TimeInterval?,
+ projectName: String? = nil,
+ modelName: String? = nil,
+ effort: String? = nil
+ ) -> CodexActivityCompletion {
+ // rollout 时间戳是整秒, 避免因为同一秒内的 Hook 毫秒时间戳而把完成时间记在最后活动之前
+ let recordedCompletedAt = max(completedAt, task.lastActivityAt)
+ let completion = storeCompletion(
+ projectName: projectName ?? task.projectName,
+ modelName: modelName ?? task.modelName,
+ effort: effort ?? task.effort,
+ completedAt: recordedCompletedAt,
+ duration: reportedDuration ?? task.preciseDuration(until: recordedCompletedAt)
+ )
+ recordCompletedTask(key, at: recordedCompletedAt)
+ return completion
+ }
+
+ func storeCompletion(
+ projectName: String?,
+ modelName: String?,
+ effort: String?,
+ completedAt: Date,
+ duration: TimeInterval?
+ ) -> CodexActivityCompletion {
+ let completion = CodexActivityCompletion(
+ id: UUID(),
+ projectName: projectName,
+ modelName: modelName,
+ effort: effort,
+ completedAt: completedAt,
+ duration: duration
+ )
+ completions.append(completion)
+ return completion
+ }
+
+ func storeTermination(
+ _ task: CodexActivityTask,
+ at terminatedAt: Date,
+ includesDuration: Bool
+ ) {
+ let termination = CodexActivityTermination(
+ id: UUID(),
+ projectName: task.projectName,
+ modelName: task.modelName,
+ effort: task.effort,
+ terminatedAt: terminatedAt,
+ duration: includesDuration ? task.preciseDuration(until: terminatedAt) : nil
+ )
+ terminations.append(termination)
+ }
+
+ func recentCompletionDate(
+ for key: CodexActivityTaskKey,
+ now: Date = Date()
+ ) -> Date? {
+ Self.recentTerminalDate(
+ for: key,
+ storedIn: &recentlyCompletedTaskAt,
+ now: now
+ )
+ }
+
+ func recentTerminationDate(
+ for key: CodexActivityTaskKey,
+ now: Date = Date()
+ ) -> Date? {
+ Self.recentTerminalDate(
+ for: key,
+ storedIn: &recentlyTerminatedTaskAt,
+ now: now
+ )
+ }
+
+ func recordCompletedTask(_ key: CodexActivityTaskKey, at completedAt: Date) {
+ Self.recordTerminalTask(
+ key,
+ at: completedAt,
+ storedIn: &recentlyCompletedTaskAt
+ )
+ }
+
+ func recordTerminatedTask(_ key: CodexActivityTaskKey, at terminatedAt: Date) {
+ Self.recordTerminalTask(
+ key,
+ at: terminatedAt,
+ storedIn: &recentlyTerminatedTaskAt
+ )
+ }
+
+ func clearCollectedActivityState() {
+ cancelAllActivityProtectionAttempts()
+ let taskIDs = Set(tasks.values.map(\.displayID))
+ .union(pendingTerminalTasks.values.map(\.task.displayID))
+ for taskID in taskIDs {
+ invalidateActivityProtectionNotification(for: taskID)
+ }
+ tasks.removeAll()
+ pendingTerminalTasks.removeAll()
+ completions.removeAll()
+ terminations.removeAll()
+ recentlyCompletedTaskAt.removeAll()
+ recentlyTerminatedTaskAt.removeAll()
+ }
+
+ static func recentTerminalDate(
+ for key: CodexActivityTaskKey,
+ storedIn dates: inout [CodexActivityTaskKey: Date],
+ now: Date
+ ) -> Date? {
+ guard let date = dates[key] else {
+ return nil
+ }
+ guard date > now.addingTimeInterval(-completedTaskRetention) else {
+ dates.removeValue(forKey: key)
+ return nil
+ }
+ return date
+ }
+
+ static func recordTerminalTask(
+ _ key: CodexActivityTaskKey,
+ at date: Date,
+ storedIn dates: inout [CodexActivityTaskKey: Date]
+ ) {
+ dates[key] = max(dates[key] ?? .distantPast, date)
+ if let sessionId = key.sessionId {
+ let sessionKey = CodexActivityTaskKey.session(sessionId)
+ dates[sessionKey] = max(dates[sessionKey] ?? .distantPast, date)
+ }
+ }
+
+ func finalizeExpiredPendingTerminalTasks(now: Date) {
+ let expiredKeys = pendingTerminalTasks.compactMap { key, pending in
+ pending.deadline <= now ? key : nil
+ }
+ for key in expiredKeys {
+ guard let pending = pendingTerminalTasks.removeValue(forKey: key) else {
+ continue
+ }
+ let terminatedAt = max(pending.supersededAt, pending.task.lastActivityAt)
+ if pending.task.state != .suppressed {
+ storeTermination(pending.task, at: terminatedAt, includesDuration: true)
+ }
+ recordTerminatedTask(key, at: terminatedAt)
+ clearActivityProtection(
+ for: key,
+ taskID: pending.task.displayID,
+ reason: .terminal
+ )
+ }
+ }
+
+ func publishLiveTransitions(_ transitions: [CodexActivityLiveTransition]) {
+ var lastWaitingIndexByKey: [CodexActivityTaskKey: Int] = [:]
+ for (index, transition) in transitions.enumerated() {
+ if case let .waitingApproval(key) = transition {
+ lastWaitingIndexByKey[key] = index
+ }
+ }
+
+ var publishedCompletionIDs = Set<UUID>()
+ for (index, transition) in transitions.enumerated() {
+ switch transition {
+ case let .waitingApproval(key):
+ guard lastWaitingIndexByKey[key] == index,
+ let task = tasks[key],
+ task.state == .waitingApproval else {
+ continue
+ }
+ transitionSubject.send(.waitingApproval(task.snapshot))
+ case let .completed(completion):
+ guard publishedCompletionIDs.insert(completion.id).inserted else {
+ continue
+ }
+ transitionSubject.send(.completed(completion))
+ }
+ }
+ }
+}
diff --git a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
index 8de9756..c9c25a4 100644
--- a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
+++ b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
@@ -49,7 +49,7 @@ actor CodexSessionLifecycleReader {
continue
}
- scanNewLifecycleEvents(into: &cursor)
+ scanNewLifecycleEvents(into: &cursor, fallbackReference: reference)
pruneEffortBackfillState(
in: &cursor,
activeTurnIds: Set(sessionReferences.map(\.turnId))
@@ -98,6 +98,7 @@ actor CodexSessionLifecycleReader {
startedAt: lifecycle.startedAt,
approvalReviewer: lifecycle.approvalReviewer,
effort: lifecycle.effort,
+ lastProgressAt: lifecycle.lastProgressAt,
terminal: lifecycle.terminal
)
)
@@ -292,7 +293,10 @@ actor CodexSessionLifecycleReader {
// MARK: - 增量扫描
- private func scanNewLifecycleEvents(into cursor: inout SessionFileCursor) {
+ private func scanNewLifecycleEvents(
+ into cursor: inout SessionFileCursor,
+ fallbackReference: CodexActivityTurnReference
+ ) {
let stat = WorkflowStorage.fileStat(at: cursor.url)
let size = stat?.size ?? 0
let identifier = stat?.identifier
@@ -331,12 +335,12 @@ actor CodexSessionLifecycleReader {
}
for envelope in JSONLines.decode(CodexRolloutLineEnvelope.self, from: completeData) {
- guard let event = envelope.lifecycleEvent else {
- continue
+ if let event = envelope.progressEvent(fallbackReference: fallbackReference) {
+ cursor.apply(event)
+ }
+ if let event = envelope.lifecycleEvent {
+ cursor.apply(event)
}
- var lifecycle = cursor.lifecycleByTurnId[event.turnId] ?? SessionTurnLifecycle()
- lifecycle.apply(event.change)
- cursor.lifecycleByTurnId[event.turnId] = lifecycle
}
}
@@ -356,6 +360,12 @@ private nonisolated struct SessionFileCursor {
let hasUnscannedHistoricalPrefix: Bool
var completedEffortBackfillTurnIds: Set<String>
var lastEffortBackfillAttemptByTurnId: [String: Date]
+
+ mutating func apply(_ event: SessionLifecycleEvent) {
+ var lifecycle = lifecycleByTurnId[event.turnId] ?? SessionTurnLifecycle()
+ lifecycle.apply(event.change)
+ lifecycleByTurnId[event.turnId] = lifecycle
+ }
}
private nonisolated enum EffortBackfillResult {
@@ -403,6 +413,24 @@ nonisolated struct CodexRolloutLinePayload: Decodable {
}
private nonisolated extension CodexRolloutLineEnvelope {
+ func progressEvent(
+ fallbackReference: CodexActivityTurnReference
+ ) -> SessionLifecycleEvent? {
+ let eventDate = timestamp.flatMap(CodexDateFormat.iso8601Date)
+ ?? payload?.completedAt.flatMap(Self.date)
+ ?? payload?.startedAt.flatMap(Self.date)
+ guard let eventDate,
+ eventDate >= fallbackReference.startedAt.addingTimeInterval(-1) else {
+ return nil
+ }
+
+ let turnId = payload?.turnId ?? fallbackReference.turnId
+ guard !turnId.isEmpty else {
+ return nil
+ }
+ return SessionLifecycleEvent(turnId: turnId, change: .progress(at: eventDate))
+ }
+
var lifecycleEvent: SessionLifecycleEvent? {
guard let payload,
let turnId = payload.turnId,
@@ -466,6 +494,7 @@ private nonisolated struct SessionLifecycleEvent {
}
private nonisolated enum SessionLifecycleChange {
+ case progress(at: Date)
case started(at: Date)
case context(approvalReviewer: CodexApprovalReviewer?, effort: String?)
case completed(at: Date, duration: TimeInterval?)
@@ -476,10 +505,13 @@ private nonisolated struct SessionTurnLifecycle {
var startedAt: Date?
var approvalReviewer: CodexApprovalReviewer?
var effort: String?
+ var lastProgressAt: Date?
var terminal: CodexSessionTaskTerminalState?
mutating func apply(_ change: SessionLifecycleChange) {
switch change {
+ case let .progress(at):
+ lastProgressAt = max(lastProgressAt ?? .distantPast, at)
case let .started(at):
if let currentStartedAt = startedAt {
startedAt = min(currentStartedAt, at)
@@ -503,6 +535,7 @@ nonisolated struct CodexSessionTaskLifecycleState {
let startedAt: Date?
let approvalReviewer: CodexApprovalReviewer?
let effort: String?
+ let lastProgressAt: Date?
let terminal: CodexSessionTaskTerminalState?
}
diff --git a/CodexBar/Services/Workflow/HookEventTailReader.swift b/CodexBar/Services/Workflow/HookEventTailReader.swift
index 8e01aa7..22454a5 100644
--- a/CodexBar/Services/Workflow/HookEventTailReader.swift
+++ b/CodexBar/Services/Workflow/HookEventTailReader.swift
@@ -7,6 +7,13 @@ nonisolated enum HookEventBatch {
/// attempts 由 reader 给出, 它才知道循环跑了几轮以及放弃时补发过一次清场
case bootstrapEnd(degraded: Bool, attempts: Int)
case live([WorkflowHookEvent])
+ case sourceHealthChanged(Bool)
+}
+
+nonisolated enum HookEventDrainResult: Sendable {
+ case completed
+ case sourceUnavailable
+ case cancelled
}
/// 在独立 actor 中按完整 JSONL 行读取 HookEvents/events
@@ -14,6 +21,7 @@ nonisolated enum HookEventBatch {
actor HookEventTailReader {
private let onBatch: @MainActor @Sendable (HookEventBatch) -> Void
private var pollTask: Task<Void, Never>?
+ private var readProcessingTask: Task<Void, Never>?
private var isRunning = false
// actor 会在 await 期间重入; 所有外部读取请求通过这两个标记合并为单一读取流程
private var isProcessingReads = false
@@ -21,6 +29,14 @@ actor HookEventTailReader {
private var activeDateKey = ""
private var activeFileOffset: UInt64 = 0
private var activeFileIdentifier: UInt64?
+ private var lastReportedSourceHealth: Bool?
+ private var requestedDrainGeneration: UInt64 = 0
+ private var drainWaiters: [
+ UUID: (
+ generation: UInt64,
+ continuation: CheckedContinuation<HookEventDrainResult, Never>
+ )
+ ] = [:]
init(onBatch: @escaping @MainActor @Sendable (HookEventBatch) -> Void) {
self.onBatch = onBatch
@@ -48,7 +64,7 @@ actor HookEventTailReader {
guard !Task.isCancelled else {
return
}
- await self?.drainNow()
+ _ = await self?.drainNow()
}
}
}
@@ -58,31 +74,92 @@ actor HookEventTailReader {
hasPendingDrain = false
pollTask?.cancel()
pollTask = nil
+ readProcessingTask?.cancel()
+ readProcessingTask = nil
+ completeAllDrainWaiters(with: .cancelled)
}
- func drainNow() async {
+ /// 每个调用方等待一轮在本次请求之后开始的读取, 已经在途的旧读取不能提前满足该请求
+ func drainNow() async -> HookEventDrainResult {
guard isRunning, !Task.isCancelled else {
- return
+ return .cancelled
}
+
+ requestedDrainGeneration &+= 1
+ let generation = requestedDrainGeneration
+ let waiterID = UUID()
hasPendingDrain = true
- guard !isProcessingReads else {
+ return await withTaskCancellationHandler {
+ await withCheckedContinuation { continuation in
+ drainWaiters[waiterID] = (generation, continuation)
+ startPendingReadIfNeeded()
+ }
+ } onCancel: {
+ Task {
+ await self.cancelDrainWaiter(waiterID)
+ }
+ }
+ }
+
+ private func startPendingReadIfNeeded() {
+ guard isRunning, !isProcessingReads else {
return
}
isProcessingReads = true
- defer {
- isProcessingReads = false
+ readProcessingTask = Task { [weak self] in
+ await self?.processPendingReads()
}
+ }
+
+ private func processPendingReads() async {
await drainPendingRequests()
+ isProcessingReads = false
+ readProcessingTask = nil
+
+ // 最后一轮完成后没有 await 空窗, 正常不会遗漏请求; 这里仍保留自愈以约束未来改动
+ if isRunning, hasPendingDrain {
+ startPendingReadIfNeeded()
+ }
}
private func drainPendingRequests() async {
while isRunning, hasPendingDrain, !Task.isCancelled {
hasPendingDrain = false
- await drainNewLines()
+ let generation = requestedDrainGeneration
+ let result = await drainNewLines()
+ completeDrainWaiters(through: generation, with: result)
+ }
+
+ if !isRunning || Task.isCancelled {
+ completeAllDrainWaiters(with: .cancelled)
}
}
+ private func completeDrainWaiters(
+ through generation: UInt64,
+ with result: HookEventDrainResult
+ ) {
+ let completedWaiterIDs = drainWaiters.compactMap { waiterID, waiter in
+ waiter.generation <= generation ? waiterID : nil
+ }
+ for waiterID in completedWaiterIDs {
+ drainWaiters.removeValue(forKey: waiterID)?.continuation.resume(returning: result)
+ }
+ }
+
+ private func completeAllDrainWaiters(with result: HookEventDrainResult) {
+ let waiters = Array(drainWaiters.values)
+ drainWaiters.removeAll()
+ for waiter in waiters {
+ waiter.continuation.resume(returning: result)
+ }
+ }
+
+ private func cancelDrainWaiter(_ waiterID: UUID) {
+ drainWaiters.removeValue(forKey: waiterID)?.continuation.resume(returning: .cancelled)
+ }
+
private var activeFileURL: URL {
WorkflowStorage.eventLogURL(for: activeDateKey)
}
@@ -99,6 +176,7 @@ actor HookEventTailReader {
activeFileOffset = result.activeFileOffset
activeFileIdentifier = result.activeFileIdentifier
await onBatch(.bootstrapEnd(degraded: false, attempts: attempt + 1))
+ await reportSourceHealth(true)
return
}
}
@@ -112,6 +190,7 @@ actor HookEventTailReader {
activeFileIdentifier = stat?.identifier
await onBatch(.bootstrapStart)
await onBatch(.bootstrapEnd(degraded: true, attempts: Self.bootstrapAttemptLimit))
+ await reportSourceHealth(false)
}
private func bootstrapAttempt(now: Date) async -> BootstrapResult? {
@@ -167,9 +246,9 @@ actor HookEventTailReader {
// MARK: - 增量 tail
- private func drainNewLines() async {
+ private func drainNewLines() async -> HookEventDrainResult {
guard isRunning, !Task.isCancelled else {
- return
+ return .cancelled
}
let todayKey = WorkflowStorage.dateKey(for: Date())
@@ -177,7 +256,10 @@ actor HookEventTailReader {
// 跨零点先读完旧文件尾部, 再切到新日期文件
guard await readAppendedLines() else {
// bootstrap 已经完成切日; 临时失败则保留旧日期, 下一轮继续重试
- return
+ return currentDrainResult()
+ }
+ guard isRunning, !Task.isCancelled else {
+ return .cancelled
}
activeDateKey = todayKey
activeFileOffset = 0
@@ -185,6 +267,14 @@ actor HookEventTailReader {
}
_ = await readAppendedLines()
+ guard isRunning, !Task.isCancelled else {
+ return .cancelled
+ }
+ return currentDrainResult()
+ }
+
+ private func currentDrainResult() -> HookEventDrainResult {
+ lastReportedSourceHealth == true ? .completed : .sourceUnavailable
}
/// 返回是否读到当前文件上界; 触发重新 bootstrap 或读取中断时为 false
@@ -206,6 +296,7 @@ actor HookEventTailReader {
}
guard size > activeFileOffset else {
+ await reportSourceHealth(true)
return true
}
@@ -217,9 +308,18 @@ actor HookEventTailReader {
makeBatch: HookEventBatch.live
)
activeFileOffset = streamResult.completeOffset
+ await reportSourceHealth(streamResult.didReachUpperBound)
return streamResult.didReachUpperBound
}
+ private func reportSourceHealth(_ isHealthy: Bool) async {
+ guard isHealthy != lastReportedSourceHealth else {
+ return
+ }
+ lastReportedSourceHealth = isHealthy
+ await onBatch(.sourceHealthChanged(isHealthy))
+ }
+
/// 返回已处理完整行的绝对 offset 和是否读完固定上界; 后续失败时保留此前进度
private func streamEvents(
at url: URL,
diff --git a/CodexBar/Views/Settings/KeepAliveOptionsView.swift b/CodexBar/Views/Settings/KeepAliveOptionsView.swift
index 923aec4..19e6177 100644
--- a/CodexBar/Views/Settings/KeepAliveOptionsView.swift
+++ b/CodexBar/Views/Settings/KeepAliveOptionsView.swift
@@ -4,12 +4,14 @@ import SwiftUI
/// 行样式与度量沿用通知子面板, 只有面板宽度按内容收窄
struct KeepAliveOptionsView: View {
@ObservedObject var keepAliveController: KeepAliveController
+ @ObservedObject var activityProtectionSettings: ActivityProtectionSettings
var body: some View {
VStack(alignment: .leading, spacing: Metrics.rowSpacing) {
waitingApprovalRow
displayAwakeRow
maximumDurationRow
+ activityProtectionRow
// 台式机读不到电池, 这一行整个收起而不是置灰
if keepAliveController.hasBattery {
@@ -45,6 +47,19 @@ struct KeepAliveOptionsView: View {
)
}
+ private var activityProtectionRow: some View {
+ pickerRow(
+ title: "异常会话保护",
+ caption: "长时间没有进展时隐藏任务并停止参与防睡眠",
+ selection: Binding(
+ get: { activityProtectionSettings.inactivityDuration },
+ set: { activityProtectionSettings.setInactivityDuration($0) }
+ ),
+ options: ActivityProtectionSettings.InactivityDuration.allCases,
+ label: \.title
+ )
+ }
+
/// 只改"哪些任务算数", 没有额外依赖, 所以不置灰也不隐藏
private var waitingApprovalRow: some View {
toggleRow(
@@ -147,7 +162,7 @@ struct KeepAliveOptionsView: View {
private enum Metrics {
static let panelWidth: CGFloat = 250
/// 有内置电池的设备时行数, 无内置电池设备少一行低电量保护
- static let maximumRowCount = 4
+ static let maximumRowCount = 5
static let horizontalPadding = SettingsOptionsPanelMetrics.horizontalPadding
static let verticalPadding = SettingsOptionsPanelMetrics.verticalPadding
static let rowSpacing = SettingsOptionsPanelMetrics.rowSpacing
diff --git a/Config/Version.xcconfig b/Config/Version.xcconfig
index 7871598..bcb198f 100644
--- a/Config/Version.xcconfig
+++ b/Config/Version.xcconfig
@@ -1,2 +1,2 @@
-MARKETING_VERSION = 3.5.12
-CURRENT_PROJECT_VERSION = 66
+MARKETING_VERSION = 3.6.0
+CURRENT_PROJECT_VERSION = 67
diff --git a/README.md b/README.md
index 168f79a..2038c94 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
[![Downloads](https://img.shields.io/github/downloads/bob-zebedy/CodexBar/total?color=2EA043)](https://github.com/bob-zebedy/CodexBar/releases)
[![License](https://img.shields.io/github/license/bob-zebedy/CodexBar?color=8957E5)](LICENSE)
-[安装](#安装) | [使用](#使用) | [语言](#语言) | [隐私](#隐私) | [实现](#实现)
+[功能总览](#功能总览) | [安装](#安装) | [基本使用](#基本使用) | [设置说明](#设置说明) | [CodexBar Hook](#codexbar-hook) | [防止系统睡眠](#防止系统睡眠) | [隐私与数据](#隐私与数据)
<img src="Images/preview.gif" width="640" alt="CodexBar 预览">
@@ -20,58 +20,111 @@
---
-CodexBar 把 Codex 的运行状态收进菜单栏: 账户信息, 剩余额度, 任务状态, 重置时间, Token 用量, 使用详细信息等, 并提供简体中文和英文界面
+CodexBar 是面向 macOS 15 及更高版本的菜单栏 App, 用于展示 Codex 账户 额度 Token 用量和实时任务状态, 并提供通知 跨设备 Hook 统计和按任务自动防睡眠等能力
-## 特性
+CodexBar 会优先使用全局安装的 Codex CLI, 找不到时回退到 ChatGPT App 或 Codex App 内置的 Codex, 通过本机 `codex app-server` 获取账户 额度和 Token 用量
-其中实时任务, 热力图面板中的详细统计数据与防睡眠功能依赖 CodexBar Hook, 开启方式见[关于 Hook](#关于-hook)
+## 功能总览
-### 账户信息
+CodexBar 的功能来自三条彼此独立的数据链路
-- 展示当前登录的账号
-- 右侧套餐徽章区分 Enterprise, Team, Pro, Plus, Edu, Free
-- 双击邮箱可模糊遮挡
-- 双击头像立即刷新
+| 功能 | 主要作用 | 数据来源 | 是否依赖 CodexBar Hook |
+| --- | --- | --- | --- |
+| 账户与额度 | 展示账户 套餐 额度窗口 重置时间 积分和手动重置次数 | 本机 `codex app-server` | 否 |
+| Token 用量 | 展示全时累计 峰值 连胜 最长任务和近 30 周热力图 | 本机 `codex app-server` | 否 |
+| 实时任务 | 判断运行中 等待批准 最近完成和最近终止任务 | Hook 事件与本机 rollout 生命周期 | 是 |
+| Hook 历史统计 | 按天统计会话 轮次 工具调用 权限请求 上下文压缩和子 Agent | 本机 Hook 原始事件 | 是 |
+| 系统通知 | 提醒额度变化 任务变化 重置临期和防睡眠保护事件 | 额度链路与实时任务链路 | 部分依赖 |
+| 防止系统睡眠 | 只在符合条件的 Codex 任务存在时阻止系统睡眠 | 实时任务链路与 CodexBar Helper | 是 |
+| 跨设备同步 | 通过 iCloud 合并多台 Mac 的每日 Hook 聚合 | CloudKit private database | 是 |
-### 额度与用量
+### 菜单栏图标
-- 分时间窗口展示剩余额度, 重置时间与可用的手动重置次数
-- 菜单栏可常驻显示主要或次要窗口的额度百分比, 无需展开面板
-- 30 周日历热力图呈现每日 Token 用量, 点击任意一格展开当天明细
+- 普通状态显示 Codex 图标, 账户或可信数据异常时切换为错误图标
+- 运行中任务显示蓝色状态点, 等待批准显示橙色状态点, 刚完成任务显示绿色状态点
+- 开启菜单栏额度指示后, 图标旁显示所选额度窗口的剩余比例
+- 鼠标悬停可查看任务状态 项目名 运行或等待时长以及额度窗口剩余比例
+- 额度数据来自缓存时会降低图标和进度条透明度, 避免把旧数据误认成最新状态
-### 实时任务
+### 主面板
-- 开启 CodexBar Hook 后, 菜单栏图标随任务状态实时变化
-- 任务中心区分运行中, 等待批准, 最近完成, 已终止四种状态
+#### 账户信息
-### 热力图统计
+- 展示当前登录账户和套餐标识
+- 套餐标识支持 Enterprise Team Business Pro Plus Edu 和 Free 等类型
+- 双击邮箱可切换模糊显示
+- 双击账户图标可立即刷新账户 额度和用量
+- 未登录或 app-server 初始化失败时显示对应状态, 具体请求错误保留在日志窗口
-- GitHub 贡献墙样式展示每日 Token 用量
-- 开启 CodexBar Hook 后的会话还可统计对话轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 等指标
-- 可选开启 iCloud 同步, 在多台 Mac 之间同步数据
+#### 额度与重置次数
-### 防止系统睡眠
+- 展示 Codex 返回的全部额度分组和额度窗口
+- 每个窗口展示名称 剩余比例 分段进度条和重置时间
+- 展示可用积分或无限积分状态
+- 展示可用手动重置次数
+- 点击手动重置次数可查看各批次的过期时间和数量
+- 手动重置次数将在 7 天内过期时按剩余天数提供通知提醒
-需要长时间运行 Codex 任务但是怕系统自动睡眠?
+#### Token 用量与热力图
-- 仅在任务运行期间防止系统睡眠, 任务结束恢复系统睡眠设置
-- 可开启等待批准时保持, 任务等待批准期间继续防止系统睡眠
-- 可开启保持屏幕常亮, 防睡眠期间同时阻止屏幕保护与自动锁屏
-- 可设置最长防睡眠时间 1, 2, 4, 8, 12, 24 小时或无限制
-- 可开启低电量保护, 使用电池且电量跌破阈值时恢复系统睡眠, 接通电源后自动恢复防睡眠
-- 防睡眠状态可在主面板的任务卡片右侧显示一个咖啡杯标记
+- 展示全时累计 Token
+- 展示单日 Token 峰值
+- 展示当前连续使用天数和最长连续使用天数
+- 展示最长任务时长
+- 使用 30 列乘 7 行热力图展示近 30 周每日 Token 用量
+- 方块颜色强度相对于当前热力图中的峰值计算
+- 鼠标移动到日期方块时展示日期 Token 数和用量强度
+- Hook 开启时, 日期详情还会展示最常用模型 会话数 对话轮次 子 Agent 工具调用 权限请求和上下文压缩次数
-### 通知与提醒
+#### 实时任务与任务中心
+
+- 主面板活动卡片优先展示等待批准或运行中的任务, 没有活跃任务时展示最近完成或最近终止状态
+- 活动卡片可展示模型 推理强度 项目名 工具名 运行时长 等待时长 活跃子 Agent 数和其他并发任务数
+- 点击有内容的活动卡片可打开任务中心
+- 任务中心分别列出等待确认 运行中 最近完成和最近终止任务
+- 每条任务可展示项目 模型 推理强度 状态持续时间和完成或终止时间
+- 防睡眠实际生效时, 活动卡片右侧显示咖啡杯标记
-- 本地通知: 额度预警, 额度重置, 任务等待批准, 任务完成, 手动重置即将过期, 低电量保护生效, 防睡眠阈值
-- 通知音效独立设置
-- 任务状态变化可设置触摸板震动反馈通知
+#### 底部状态
-### 系统集成
+- 展示数据更新时间和距离下一次自动刷新的倒计时
+- 账户 额度和 Token 用量每 60 秒自动刷新一次
+- 展示 iCloud 同步关闭 同步中 已同步或同步失败状态
+- 发现新版本时展示更新提示, 双击提示可开始更新
+
+### 通知与提醒
-- 简体中文和英文界面, 日期 时间 时长和百分比按当前语言与地区格式显示
-- 全局快捷键唤起
-- 内置日志窗口保留最近 500 条 app-server 请求记录
+CodexBar 通知总开关开启并获得 macOS 通知授权后, 支持以下通知
+
+| 通知 | 触发条件 | 可配置项 | 额外依赖 |
+| --- | --- | --- | --- |
+| 任务完成 | 任务完成且运行时长达到阈值 | 开关 最短时长 音效 | CodexBar Hook |
+| 任务等待 | 任务进入等待用户批准状态 | 开关 音效 | CodexBar Hook |
+| 额度预警 | 剩余额度首次跌到阈值或以下 | 开关 阈值 音效 | 无 |
+| 额度重置 | 已观察到消耗的额度窗口回到未消耗状态 | 开关 音效 | 无 |
+| 重置临期 | 手动重置次数进入过期前 7 天窗口 | 开关 音效 | 无 |
+| 低电量保护 | 低电量导致 CodexBar 成功恢复系统睡眠 | 开关 音效 | 防睡眠和低电量保护 |
+| 防睡眠上限 | 达到时长上限并成功恢复系统睡眠 | 开关 音效 | 防睡眠和有限时长上限 |
+| 异常会话保护 | 运行中任务超过静默阈值并仍然有效 | 固定使用系统默认声音 | CodexBar Hook 和防睡眠主开关 |
+
+- 每类可配置通知都可选择默认 静音 系统声音或 App 内置声音
+- 非默认且非静音的声音可在设置面板中试听
+- 任务完成和任务等待可额外开启触摸板震动, 触觉反馈不依赖系统通知授权, 但服从 CodexBar 通知总开关
+- 点击任意 CodexBar 通知会打开主面板
+- App 位于前台时仍会显示通知横幅 列表项和声音
+- 已经失效的等待批准或异常会话通知会从通知中心撤回
+- Codex TUI 通知是 Codex 自己的设置, 与 CodexBar 本地通知相互独立
+
+### 系统集成与辅助功能
+
+- 作为 `LSUIElement` 菜单栏 App 运行, 不占用 Dock 图标
+- 支持开机自动启动
+- 支持可录制的全局快捷键
+- 支持 Sparkle 自动检查 手动检查和应用内更新
+- 支持简体中文和英文界面
+- 日期 时间 时长 百分比 月历和星期顺序跟随当前地区设置
+- 提供 Codex CLI 和 Codex App 内置 CLI 的版本 来源和路径检查
+- 提供最多 500 条的内存 app-server 交互日志
## 安装
@@ -83,113 +136,472 @@ brew install --cask bob-zebedy/tap/codexbar
### 通过 DMG
-[Releases](https://github.com/bob-zebedy/CodexBar/releases)
+从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载并安装
-运行要求
+### 运行要求
- macOS 15.0 或更高版本
-- 已安装并登录 [Codex CLI](https://github.com/openai/codex), 或安装了内置 Codex 的 ChatGPT App
+- 已安装并登录 [Codex CLI](https://github.com/openai/codex), 或安装了内置 Codex 的 ChatGPT App 或 Codex App
+- 使用 Hook 相关功能时, 当前连接的 Codex app-server 版本必须为 `0.145.0` 或更高版本
+- 使用跨设备同步时, macOS 必须登录可用的 iCloud 账户
+
+## 基本使用
+
+| 操作 | 效果 |
+| --- | --- |
+| 左键点击菜单栏图标 | 打开或关闭主面板 |
+| 右键或 Control 点击菜单栏图标 | 打开设置 日志和退出菜单 |
+| `⌘⇧W` | 使用默认全局快捷键打开或关闭主面板 |
+| `⌘,` | 打开设置窗口 |
+| `⌘L` | 主面板打开时关闭面板并打开日志窗口 |
+| 双击账户图标 | 立即刷新账户 额度和用量 |
+| 双击账户邮箱 | 切换邮箱模糊显示 |
+| 悬停热力图方块 | 查看当日 Token 和 Hook 统计详情 |
+| 点击活动卡片 | 打开并发任务中心 |
+| 点击手动重置次数 | 查看各批次过期时间 |
+
+全局快捷键会优先在鼠标所在屏幕打开主面板, 菜单栏锚点不可用时使用独立浮动面板作为回退
+
+## 设置说明
+
+设置窗口包含通用 高级和关于三个页面
+
+### 通用设置
+
+| 设置 | 作用 | 当前默认或初始状态 |
+| --- | --- | --- |
+| 开机自动启动 | 通过 macOS 登录项启动 CodexBar | 跟随当前系统登录项状态 |
+| 自动检查更新 | 由 Sparkle 定期检查 appcast | 跟随 Sparkle 当前设置 |
+| 菜单栏额度指示 | 在菜单栏图标旁显示主额度或次额度剩余比例 | 主额度 |
+| 全局快捷键 | 在任意 App 中打开或关闭 CodexBar 主面板 | `⌘⇧W` |
+
+- 菜单栏额度指示会记住关闭前选择的窗口, 再次开启时恢复该选择
+- 全局快捷键至少需要两个修饰键
+- `Command-Space` 和 `Command-Tab` 等系统保留组合不可使用
+- 快捷键可清除或恢复为默认值
+
+### 高级设置
+
+| 设置 | 作用 | 当前默认或初始状态 |
+| --- | --- | --- |
+| CodexBar Hook | 安装并校验 Codex 事件 handler | 未安装时关闭 |
+| 主面板任务中心 | 控制活动卡片和任务中心是否显示 | 开启, Hook 关闭时不可用 |
+| 系统通知 | 控制 CodexBar 本地通知和触觉反馈 | 关闭 |
+| 防止系统睡眠 | 根据实时 Codex 任务自动切换系统睡眠 | 关闭 |
+| 跨设备同步 | 通过 iCloud 同步每日 Hook 聚合 | 关闭 |
+| 重建数据 | 从所选日期范围的本机 Hook 原始事件重新生成聚合 | 手动操作 |
+
+#### 通知子选项
+
+| 选项 | 可选值或默认值 |
+| --- | --- |
+| 任务完成通知 | 默认开启, 最短任务时长默认 1 分钟, 可选 30 秒 1 分钟 2 分钟或 5 分钟 |
+| 任务等待通知 | 默认开启 |
+| 额度预警通知 | 默认开启, 阈值默认 10%, 可选 5% 10% 或 25% |
+| 额度重置通知 | 默认开启 |
+| 重置临期通知 | 默认开启 |
+| 低电量保护通知 | 默认开启, 仅在低电量保护实际可用时生效 |
+| 防睡眠上限通知 | 默认开启, 仅在时长上限不是无限制时生效 |
+| 任务触觉反馈 | 默认关闭 |
+| Codex TUI 通知 | 读取并修改 Codex 用户配置中的 `tui.notifications` |
+
+通知总开关首次开启时会请求 macOS 通知权限, 权限被拒绝时设置页会提供系统设置入口
+
+#### 跨设备同步
+
+- 只有 CodexBar Hook 已开启且 iCloud 可用时才能开启
+- 开启后会回填保留期内的本机每日 Hook 聚合
+- 设置页显示同步中状态和最近一次成功上传时间
+- 主面板底部显示同步关闭 同步中 已同步或失败状态
+- 每台设备的同日数据独立保存, 展示时会合并不同设备的贡献并避免重复叠加当前设备的本地副本
+- CloudKit 使用 `iCloud.app.zabrian.codexbar` 容器的 private database
+
+#### 重建数据
+
+- 日期选择器只允许选择原始 Hook 数据保留期内的日期
+- 有原始事件的日期会显示数据标记
+- 执行前会确认所选日期范围
+- 重建会重新计算本机每日聚合, 跳过无法解析的无效行并报告结果
+- 开启跨设备同步后, 重建日期会在后续同步中替换当前设备对应日期的云端贡献
+- 重建不修改账户 额度或 Token 用量数据
+
+### 关于页面
+
+- 分别检测全局 Codex CLI 和 Codex App 内置 CLI 的磁盘版本
+- 标记当前 app-server 实际使用的 Codex 来源和运行版本
+- 磁盘中的 Codex 已更新但当前 app-server 尚未重连时显示新安装版本
+- 点击可执行文件路径可复制完整路径
+- 展示 CodexBar 当前版本 更新检查状态和可用更新
+- 提供 GitHub 项目入口 手动检查更新和退出 CodexBar 操作
+
+## CodexBar Hook
+
+### Hook 的作用
+
+账户 额度和 Token 用量接口只能提供周期性快照, 不能完整表达一个 Codex 任务何时开始 何时等待批准 调用了多少工具或是否启动了子 Agent
+
+CodexBar Hook 把 Codex 在关键节点产生的事件追加到本机日志, 让 CodexBar 能够获得以下能力
+
+- 实时任务状态和并发任务中心
+- 菜单栏任务状态点和任务 tooltip
+- 任务完成 等待批准和异常会话保护通知
+- 任务触觉反馈
+- 按天统计会话 轮次 工具调用 权限请求 上下文压缩和子 Agent
+- 基于任务状态自动防止系统睡眠
+- 跨设备同步每日 Hook 聚合
+- 从原始事件重建历史聚合
+
+关闭 Hook 不影响账户 额度 Token 热力图 更新检查或日志窗口, 但以上依赖实时事件的功能会停止工作
+
+### 启用条件
+
+- CodexBar 必须能连接当前实际运行的 `codex app-server`
+- app-server 握手版本必须为 `0.145.0` 或更高版本
+- Codex 用户配置中的 `features.hooks` 不能被全局关闭
+- Hook 配置文件必须是有效 JSON
+
+版本检查使用当前连接的 app-server 运行版本, 不是磁盘上刚安装的版本
+
+升级 Codex 后如果仍提示版本过低, 需要重启 CodexBar 以建立新连接
+
+### 开启和关闭时修改的内容
+
+CodexBar 使用 `$CODEX_HOME/hooks.json`, 未设置 `CODEX_HOME` 时使用 `~/.codex/hooks.json`
+
+开启 Hook 时会完成以下操作
+
+1. 读取并保留现有 `hooks.json` 内容
+2. 为当前 CodexBar 可执行文件追加独立的 command handler
+3. 通过 app-server 查询实际 Hook 列表
+4. 只为命令 来源路径和事件都匹配当前 CodexBar 的 handler 更新信任状态
+5. 再次查询并确认事件完整 启用 来源正确且已受信任
+
+关闭 Hook 时只删除同时匹配当前 CodexBar 可执行路径和 `--hook-event` 参数的 handler, 并只清理对应信任项
+
+用户自己配置的 handler 其他 App 的 handler 未识别的同级结构和无关信任项都会保留
+
+### 监听的事件
+
+| Hook 事件 | CodexBar 中的主要用途 |
+| --- | --- |
+| `SessionStart` `SessionEnd` | 会话生命周期 会话统计和任务收尾 |
+| `UserPromptSubmit` `Stop` | 对话轮次 任务进展和完成候选 |
+| `PreToolUse` `PostToolUse` | 工具调用统计和任务进展 |
+| `PermissionRequest` | 用户审批状态 权限请求统计和等待通知 |
+| `PreCompact` `PostCompact` | 上下文压缩统计和任务进展 |
+| `SubagentStart` `SubagentStop` | 子 Agent 数量 状态和任务进展 |
+
+`SessionEnd` 的 handler 超时为 3 秒, 其他事件为 5 秒
+
+### 一次 Hook 事件如何处理
+
+```text
+Codex 触发事件
+ -> 启动 CodexBar --hook-event 子进程
+ -> 子进程只读取 stdin JSON
+ -> 提取统计和任务状态需要的字段
+ -> 在跨进程文件锁内追加到当日 JSONL
+ -> 立即退出
+ -> 主 App 增量读取并更新聚合和实时任务
+```
+
+- Hook 子进程不会初始化菜单栏 UI app-server CloudKit 通知或防睡眠服务
+- 写入失败不会阻断 Codex, Hook 模式会忽略无效输入或本次记录失败并退出
+- 主 App 同时读取 Hook 事件和本机 Codex rollout 生命周期, 用于区分准确的完成与终止状态并补充最近进展时间
+- rollout 读取只提取生命周期 时间和推理强度等字段, 不展示或保存会话正文和工具内容
+
+### Hook 本地数据
+
+| 数据 | 路径 | 当前内容 | 保留规则 |
+| --- | --- | --- | --- |
+| 原始事件 | `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl` | 时间 事件名 模型 推理强度 权限模式 reviewer session turn agent 工具和工作目录 | 210 天 |
+| 每日聚合 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl` | 每类事件计数 会话与轮次 项目名计数和模型计数 | 210 天 |
+| 维护状态 | `~/Library/Application Support/CodexBar/HookEvents/maintenance.json` | 增量 offset 文件标识和待处理日期 | 跟随聚合维护 |
+
+- 原始事件只保存选定的结构化字段, 不保存 prompt 文本 Codex 回复 工具参数或工具输出
+- 原始事件中的 session turn 和 agent ID 会随对应 JSONL 一起保留 210 天
+- 每日聚合只在最近 3 天保留 session 和 turn ID 列表, 之后转换为计数并删除列表
+- 原始事件和每日聚合都只保存在本机
+- CloudKit 不上传原始事件 session ID turn ID agent ID 完整工作目录 账户 额度或 Token 用量
+
+### Hook 状态和排查
+
+| 状态或提示 | 含义 | 处理方式 |
+| --- | --- | --- |
+| 需要更高 Codex 版本 | 当前运行的 app-server 版本不足 | 更新 Codex 后重启 CodexBar |
+| Codex Hook 已全局关闭 | `features.hooks` 已禁用 | 在 Codex 配置中重新启用 Hooks |
+| CodexBar Hook 已不完整 | 至少一个必要事件缺少当前 handler | 关闭后重新开启 CodexBar Hook |
+| CodexBar Hook 未被信任 | app-server 仍将 handler 判定为未信任或已修改 | 重新开启 Hook 并检查 Codex 配置 |
+| CodexBar Hook 意外来源 | app-server 返回的来源文件不是当前配置文件 | 检查 `CODEX_HOME` 和运行中的 Codex 来源 |
+| hooks.json 文件格式错误 | 顶层或 `hooks` 结构不是有效 JSON 对象 | 修复 JSON 后重新操作 |
+| 无法验证 Codex Hook | app-server 暂时不可用或校验请求失败 | 查看日志并在 Codex 可用后重新打开设置页 |
+
+CodexBar 每次打开设置窗口或 App 重新激活时都会刷新配置并校验已安装 Hook
+
+升级后出现 Hook 不完整提示时, 关闭后重新开启即可补齐当前代码要求的事件
-> [!TIP]
-> CodexBar 会自动寻找可用的 codex 实例
+## 防止系统睡眠
-## 使用
+### 这个功能解决什么问题
-| 操作 | 效果 |
-| ------------------- | ------------------------------ |
-| 左键点击菜单栏图标 | 打开主面板 |
-| 右键或 Control 点击 | 打开上下文菜单 |
-| `⌘⇧W` | 全局唤起主面板, 可在设置中改键 |
-| `⌘,` | 打开设置窗口 |
-| `⌘L` | 主面板打开时, 打开日志窗口 |
+macOS 进入系统睡眠后, 正在运行的本机 Codex 任务可能会被挂起
-### 语言
+防睡眠功能根据 Codex 实时任务状态自动管理系统睡眠, 目标是让长任务在无人操作时继续运行, 同时在任务结束或保护条件触发后恢复系统原有睡眠行为
+
+它不是一个永久保持唤醒的通用开关
+
+打开设置只表示允许 CodexBar 自动管理睡眠, 没有符合条件的任务时不会修改系统睡眠
+
+### 生效条件
+
+以下条件同时满足时, CodexBar 才会实际阻止系统睡眠
+
+1. CodexBar 正在运行且未进入退出流程
+2. 防止系统睡眠主开关已打开
+3. CodexBar Hook 已安装且最近一次明确校验有效
+4. 至少有一个运行中任务, 或开启等待批准时保持后存在等待批准任务
+5. CodexBarHelper 已注册并获得系统批准
+6. Helper 当前不在更新过程中
+7. 低电量保护当前没有生效
+8. 本轮实际防睡眠时间尚未达到上限
+
+任一条件不满足时只停止实际防睡眠
+
+条件恢复后, 仍有符合条件任务时会自动重新生效
+
+### 工作方式
+
+```text
+Hook 事件和 rollout 生命周期
+ -> CodexActivityMonitor 判断运行中或等待批准任务
+ -> KeepAliveController 检查 Hook Helper 电量和时长上限
+ -> App 建立空闲睡眠断言
+ -> CodexBarHelper 管理 pmset SleepDisabled
+ -> 可选建立显示睡眠断言并持续声明用户活动
+```
+
+- App 侧建立 IOKit 空闲睡眠断言
+- CodexBarHelper 只通过受签名约束的 XPC 接口接受租约 状态查询和更新恢复请求
+- helper 使用 `pmset -g` 查询状态, 只使用 `pmset -a disablesleep 1` 或 `pmset -a disablesleep 0` 修改状态
+- 任务结束 设置关闭 Hook 失效 低电量或时长到期时会释放租约并恢复睡眠
+- 如果 CodexBar 自己恢复睡眠时设备已经合盖, 且系统配置要求合盖睡眠, App 会补发一次系统睡眠请求
+
+### 防睡眠子选项
+
+| 选项 | 作用 | 当前默认 | 可选值 |
+| --- | --- | --- | --- |
+| 等待批准时保持 | 将等待用户批准的任务也计入防睡眠 | 关闭 | 开启或关闭 |
+| 保持屏幕常亮 | 实际防睡眠期间同时阻止显示器睡眠 屏保和闲置锁屏 | 关闭 | 开启或关闭 |
+| 最长防睡眠时间 | 限制一轮实际阻止睡眠的累计时长 | 12 小时 | 1 2 4 8 12 24 小时或无限制 |
+| 异常会话保护 | 运行中任务长时间无进展时隐藏任务并停止其防睡眠贡献 | 1 小时 | 30 分钟 1 2 4 小时 |
+| 低电量保护 | 使用电池且电量过低时恢复系统睡眠 | 关闭 | 关闭或 5% 10% 15% 20% 25% |
+
+没有内置电池的 Mac 不显示低电量保护选项
+
+#### 等待批准时保持
+
+- 关闭时, 任务从运行中进入等待批准后不再支撑防睡眠
+- 开启时, 等待批准期间继续防止系统睡眠
+- 等待批准没有自然超时, 因此无人值守时可能长时间保持唤醒
+- 最长防睡眠时间仍会限制等待批准期间的实际防睡眠时长
+- 异常会话保护不处理等待批准任务
+
+#### 保持屏幕常亮
+
+- 只在系统睡眠实际被阻止时生效
+- 除了阻止显示器睡眠, 还每 30 秒声明一次用户活动以压住屏保和闲置锁屏
+- 任务结束 低电量保护生效 达到时长上限或防睡眠失败时会同步释放
+- 开启后可能让离开电脑时仍保持解锁界面, 因此默认关闭
+
+#### 最长防睡眠时间
+
+- 默认 12 小时
+- 只累计真正阻止系统睡眠的时间
+- 因低电量 Helper 不可用或其他条件暂停防睡眠的时间不计入上限
+- 使用可暂停时钟, 系统睡眠期间和系统时间调整不会消耗上限
+- 没有活跃任务时重置计时
+- 新运行任务出现或等待任务恢复运行时重新开始一轮计时
+- 达到上限后恢复系统睡眠, 直到新一轮任务重新开始
+
+#### 异常会话保护
+
+异常会话保护用于处理任务已经没有真实进展, 但缺少可靠终态而仍显示为运行中的情况
+
+- 跟随防睡眠主开关, 没有独立开关
+- 只判定运行中任务, 不判定等待批准任务
+- 最近进展时间来自 Hook 顶层事件 子 Agent 事件和 rollout 生命周期
+- 达到阈值后先保存保护记录并尝试发送系统通知
+- 无论通知是否开启或提交成功, 候选仍然有效时都会隐藏任务
+- 被隐藏任务不显示在活动卡片和任务中心, 也不参与防睡眠计算
+- 后续出现新进展时自动恢复任务并撤回仍有效的保护通知
+- 修改为更长阈值后, 尚未超过新阈值的隐藏任务会恢复
+- Hook 历史回放 系统睡眠 唤醒对账和 Hook 数据源不可用期间暂停判定
+- 保护记录最长保留到最后进展后的 24 小时
+- 保护记录只包含哈希任务标识和时间戳, 不包含原始 session ID turn ID 项目名或任务内容
+
+#### 低电量保护
+
+- 只在 Mac 使用电池供电时生效
+- 电量首次小于或等于所选阈值时恢复系统睡眠
+- 电量必须回升到阈值加 5 个百分点才解除保护, 避免在临界值附近反复切换
+- 接通电源会立即解除当前阻断, 仍有任务时自动恢复防睡眠
+- 只有 CodexBar 确实停止了自己持有的防睡眠状态后才发送低电量通知
+
+### Helper 授权与状态
+
+防睡眠需要随 App 嵌入的 `CodexBarHelper` LaunchDaemon 修改系统级睡眠状态
+
+- 首次开启时通过 macOS `SMAppService` 注册
+- macOS 要求批准后台项目时, 设置页显示打开系统设置按钮
+- Helper 文件缺失或注册失败时, 设置页显示错误且不执行防睡眠
+- App 更新导致 Helper 内容变化时会刷新注册并校验睡眠状态
+- App 退出前会先释放 Helper 租约并恢复由 CodexBar 修改的睡眠状态
+- XPC 连接意外中断后, Helper 会在宽限期结束后释放失联客户端租约
+- Helper 自身启动和终止时会根据持久化所有权记录恢复未完成的睡眠状态
+
+### 与其他防睡眠来源共存
+
+如果任务开始前 `SleepDisabled` 已经由其他 App 或用户设为 1, CodexBar 会把来源标记为外部
+
+- CodexBar 不会把外部设置据为己有
+- 任务结束时不会写回 `pmset` 或恢复外部来源的设置
+- 外部设置恢复为 0 而任务仍在运行时, CodexBar 会重新检查并按需接管
+- 主面板仍显示咖啡杯, tooltip 和设置页会说明系统睡眠由其他来源关闭
+
+## 语言与地区
CodexBar 提供简体中文和英文界面, 默认跟随 macOS 的 App 语言偏好
-需要单独切换时, 可在 macOS 系统设置的语言与地区中为 CodexBar 指定 App 语言. 日期 时间 时长和百分比会继续按照当前地区格式显示
+需要单独切换时, 可在 macOS 系统设置的语言与地区中为 CodexBar 指定 App 语言
-### 关于 Hook
+日期 时间 时长 百分比 月历和星期顺序继续按照当前地区格式显示
-实时任务展示, 热力图统计数据与防睡眠都依赖 CodexBar Hook
+## 日志与排查
-> [!NOTE]
-> CodexBar Hook 需要 Codex 0.145.0 或更高版本. CodexBar 按当前连接的 app-server 运行版本校验, 更新 Codex 后如果仍提示版本过低, 请先重启 CodexBar 以建立新连接
+- 右键菜单栏图标选择日志, 或在主面板打开时按 `⌘L`
+- 日志窗口保留当前 App 进程最近 500 条 app-server 请求
+- 每条记录展示请求时间 方法 状态和响应时间
+- 展开后可查看请求 响应或错误的单行预览
+- 完整内容可在独立窗口中查看或复制
+- JSON 内容会格式化并提供基础语法高亮
+- 日志存储只在内存中, 可手动清空, 退出 App 后不会保留
-> [!NOTE]
-> CodexBar 只增删自己的 handler, 不会影响用户或其他 App 原本的 Codex Hook
+## 隐私与数据
-> [!TIP]
-> 升级后如果设置页提示 `CodexBar Hook 已不完整`, 将 CodexBar Hook 关闭后重新开启即可补齐新增事件
+### 数据访问和网络行为
-### 关于防睡眠
+| 行为 | 目的 | 数据边界 |
+| --- | --- | --- |
+| 与本机 `codex app-server` 通过 stdio 通信 | 获取账户 额度 Token 用量 Hook 列表和 Codex 配置 | 本机进程通信 |
+| 请求 OpenAI 重置次数接口 | 查询手动重置次数的过期时间 | 只在存在可用重置次数时执行 |
+| Sparkle 更新检查 | 获取 appcast 和安装更新 | 使用配置的 HTTPS feed |
+| CloudKit 同步 | 同步多设备每日 Hook 聚合 | 仅在用户开启跨设备同步后使用 private database |
-开启后需要一个 Helper 进行守护, 因此首次开启时 macOS 会要求授权后台项目; 该功能同样依赖 CodexBar Hook
+### 本机保存的数据
-> [!WARNING]
-> 为了避免异常任务导致系统长时间处于禁止睡眠状态, 建议设置最长防睡眠时间
+| 数据 | 内容 | 位置或生命周期 |
+| --- | --- | --- |
+| Hook 原始事件 | 选定的结构化事件字段, 不含 prompt 回复 工具参数或工具输出 | `~/Library/Application Support/CodexBar/HookEvents/events`, 保留 210 天 |
+| Hook 每日聚合 | 事件计数 会话与轮次计数 项目名计数和模型计数 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl`, 保留 210 天 |
+| 异常会话保护 | 哈希任务标识和时间戳 | `~/Library/Application Support/CodexBar/ActivityProtection/state.json`, 最长 24 小时 |
+| App 偏好 | 开关 阈值 快捷键和通知去重状态 | macOS UserDefaults |
+| app-server 日志 | 最近 500 条请求和响应 | 仅当前进程内存 |
-## 隐私
+### CloudKit 上传内容
-CodexBar 对外网络请求只有以下四项
+CloudKit 每条记录包含设备伪标识 日期 来源 generation 各类 Hook 事件计数 会话与轮次计数 项目显示名计数 模型计数和更新时间
-| 行为 | 说明 |
-| ------------------------------ | ---------------------------------------------- |
-| 与本机 `codex app-server` 通信 | 获取账户, 额度信息, 获取&修改本机 codex 配置等 |
-| 查询额度重置次数和过期时间 | 请求 OpenAI 接口获取数据 |
-| Sparkle 更新检查 | 获取 appcast 检查新版本 |
-| CloudKit 同步 | 私有数据: 同步脱敏的每日 Hook 聚合数据 |
+CloudKit 不上传以下内容
-## 实现
+- 原始 Hook 事件文件
+- session ID turn ID 和 agent ID
+- 完整工作目录路径
+- prompt Codex 回复 工具参数或工具输出
+- Codex 账户 额度 Token 用量和 app-server 交互日志
+- 异常会话保护记录
+
+### 日志隐私
-Swift 6 + SwiftUI + AppKit, MVVM, 外部依赖 Sparkle
+- 系统日志只记录操作结果 状态分类 计数和错误阶段
+- 系统日志不记录账户额度数值 Token 用量 项目名 任务内容 session ID turn ID 或 OAuth token
+- app-server 交互日志可能包含请求和响应内容, 但只存在当前 App 进程内存并由用户主动打开查看
-工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 所有类型默认 MainActor 隔离; 共享状态收敛进 actor, 跨进程写统计文件由 `flock` 保护
+## 实现
+
+Swift 6 + SwiftUI + AppKit, 使用 MVVM, 外部依赖为 Sparkle
-三条数据链路各自独立
+工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, 共享状态收敛进 actor, 跨进程 Hook 文件写入由 `flock` 保护
```mermaid
flowchart LR
- subgraph L1["额度与用量 (每分钟刷新)"]
- A1["本机 codex 进程"] -->|"通过 app-server"| A2["获取剩余额度<br/>和 Token 用量"]
+ subgraph L1["额度与用量"]
+ A1["本机 Codex"] -->|"app-server stdio"| A2["账户 额度 Token 用量"]
end
- subgraph L2["历史统计"]
- B1["Codex 触发 Hook"] -->|"新增记录"| B2["按天汇总数据"]
+ subgraph L2["Hook 历史统计"]
+ B1["Codex Hook"] --> B2["本机按日 JSONL"]
+ B2 --> B3["每日聚合"]
end
subgraph L3["实时任务"]
- C1["Hook 事件"] --> C3["判断任务状态"]
- C2["Codex Rollout 数据"] --> C3
+ C1["Hook 事件"] --> C3["任务状态与异常会话保护"]
+ C2["本机 rollout 生命周期"] --> C3
end
A2 --> UI["菜单栏和主面板"]
- B2 --> UI
+ B3 --> UI
C3 --> UI
- C3 --> N["通知事件"]
- C3 --> K["防睡眠"]
+ B3 --> Cloud["可选 CloudKit 同步"]
+ C3 --> Notice["通知和触觉反馈"]
+ C3 --> KeepAlive["按任务防睡眠"]
```
<details>
-<summary><b>关键设计</b></summary>
+<summary><b>关键实现约束</b></summary>
<br>
**Hook 子进程模式**
-App 使用 `--hook-event` 参数启动时不初始化任何 UI, 只从 stdin 读一行 JSON, 在文件锁内追加到当日 JSONL 后立即退出
+App 使用 `--hook-event` 参数启动时不初始化 UI, 只从 stdin 读取 Hook payload, 在文件锁内追加到当日 JSONL 后立即退出
**历史聚合**
-原始 Hook 事件与每日聚合保留 210 天, 会话和轮次 ID 只保留 3 天; 聚合算法版本变化或已压缩日期收到新事件时, 会从仍在保留期内的原始 JSONL 统一完整重建
+原始 Hook 事件与每日聚合保留 210 天
+
+每日聚合只为最近 3 天保留 session 和 turn ID 列表, 更早日期只保留计数
+
+聚合算法版本变化或已压缩日期收到新事件时, 从仍在保留期内的原始 JSONL 完整重建
+
+**实时任务**
+
+`CodexActivityMonitor` 是菜单栏图标 活动卡片 通知和防睡眠的统一任务状态来源
+
+`HookEventTailReader` 增量读取 Hook JSONL, `CodexSessionLifecycleReader` 只从 rollout 提取任务生命周期和最近进展字段
+
+**异常会话保护**
+
+异常会话保护以 Hook 事件和 rollout 最近进展时间为依据
+
+达到静默阈值后先尝试提交本地通知, 随后隐藏任务并让它退出防睡眠计算
+
+新进展到达后恢复任务
+
+系统睡眠 Hook 历史回放和 Hook 数据源不可用期间暂停判定
+
+唤醒后等待新一轮 Hook 增量读取与 rollout 对账完成再恢复
+
+**CodexBar Helper 权限**
+
+`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露防睡眠租约 状态查询和更新恢复 XPC
-**root helper 权限**
+Helper 对外只执行 `/usr/bin/pmset`, 使用 `-g` 查询状态, 使用 `-a disablesleep 0/1` 修改状态
-`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露防睡眠租约与状态查询 XPC, 只执行 `pmset -a disablesleep`
+Helper 只在 CodexBar 自己将 `SleepDisabled` 从 0 改为 1 时取得所有权
-helper 只在 CodexBar 自己将 `SleepDisabled` 从 0 改为 1 时取得所有权, 取得所有权后任务结束始终恢复为 0; 任务开始时已经为 1 则视为其他来源, 不修改它, 该值在任务期间恢复为 0 时再由 CodexBar 接管
+任务开始时已经为 1 则视为外部来源, 不修改该值
-签名强制校验: helper 启动时读取自身签名拼出 requirement 交给 XPC listener, 修改签名或 bundle ID 都会导致连接被拒
+Helper 启动时读取自身签名并生成 XPC 客户端 requirement, 修改签名或 bundle ID 会导致连接被拒绝
</details>
@@ -201,13 +613,13 @@ cd CodexBar
xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
```
-区分 Debug 和 Release 构建产物
+Debug 和 Release 使用不同的 App 与 Helper bundle ID
-格式化与静态检查使用 `swiftformat` 和 `swiftlint`
+格式化和静态检查使用 `swiftformat` 和 `swiftlint`
## 反馈
-Bug, 功能建议或使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈
+Bug 功能建议或使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈
## 许可证
diff --git a/appcast.xml b/appcast.xml
index 20ea615..7484fbb 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 3.6.0</title>
+ <sparkle:version>67</sparkle:version>
+ <sparkle:shortVersionString>3.6.0</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.6.0</sparkle:releaseNotesLink>
+ <pubDate>Wed, 05 Aug 2026 23:03:27 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.6.0.dmg" sparkle:edSignature="kBBvyCDY/rw3zB1yjxyFsrWLHuNd4IlOQmPUAzbtJHjL7cyou187asAFLYw5ZizCXxLsetsQmq/vbvJSbSzTBA==" length="6945058" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.5.12</title>
<sparkle:version>66</sparkle:version>