feat(buddy): let Mac drive task timer via 0xF2 frame

Mac now owns the task timer instead of the firmware estimating it. A new
downlink task frame (0xF2) carries a rolling taskId + elapsed seconds; the
firmware adopts the elapsed value as a baseline and ticks locally, re-syncing
on taskId change (also recovers correctly across reconnects). Removes the
firmware self-timing block and keys task boundaries on the displayed session
(fixes timer not resetting when switching sessions of the same source).

Author: lltx

Sources/CodeIsland/ESP32BridgeManager.swift

@@ -377,6 +377,11 @@ final class ESP32BridgeManager: NSObject {
         send(timeHint.encode(), priority: .auxiliary)
     }
 
+    /// Write task timer frame to Buddy (Mac-authoritative timing). No-op when not connected.
+    func sendTask(_ task: BuddyTaskPayload) {
+        send(task.encode(), priority: .normal)
+    }
+
     /// Write tool history entry frame to Buddy. No-op when not connected.
     func sendToolHistory(_ entry: BuddyToolHistoryPayload) {
         send(entry.encode(), priority: .auxiliary)

Sources/CodeIsland/ESP32StatePublisher.swift

@@ -25,12 +25,23 @@ final class ESP32StatePublisher {
     private var keepAliveActivity: NSObjectProtocol?
     private var interactiveRetryTask: Task<Void, Never>?
     private var lastSentDisplay: SentDisplayState?
+    private var currentTask: ActiveTask?
+    private var nextTaskId: UInt8 = 1   // rolling 1..255, skips 0 (0 = no active task)
 
     private struct SentDisplayState {
         let identity: String
         let status: MascotStatusCode
     }
 
+    /// Tracks the currently-running task so the publisher (not the firmware) owns
+    /// the timer. A task starts when the displayed context becomes busy and ends
+    /// when it returns to idle or the displayed session changes.
+    private struct ActiveTask {
+        let identity: String
+        let startedAt: Date
+        let id: UInt8
+    }
+
     private init() {
         self.bridge = ESP32BridgeManager.shared
     }
@@ -105,6 +116,7 @@ final class ESP32StatePublisher {
         bridge.sendTimeHint(BuddyTimeHintPayload(hour: Calendar.current.component(.hour, from: Date())))
         bridge.sendStats(appState.esp32StatsPayload(session: session))
         bridge.sendSubagent(appState.esp32SubagentPayload(session: session))
+        bridge.sendTask(taskPayload(displayIdentity: displayIdentity, status: frame.status))
         let toolHistory = appState.esp32ToolHistoryPayloads(session: session)
         if toolHistory.isEmpty {
             bridge.sendToolHistoryClear()
@@ -135,6 +147,28 @@ final class ESP32StatePublisher {
         Self.log.debug("push(\(reason)): mascot=\(frame.mascot.sourceName) status=\(frame.status.rawValue) tool=\(frame.toolName ?? "")")
     }
 
+    /// Resolve the task-timer frame for the current display. Starts a fresh task
+    /// (new rolling id, reset clock) when the displayed context becomes busy or the
+    /// displayed session changes; clears it on idle. `currentTask` is intentionally
+    /// preserved across reconnects so the elapsed time keeps counting from the real
+    /// start instead of restarting at 0.
+    private func taskPayload(displayIdentity: String, status: MascotStatusCode) -> BuddyTaskPayload {
+        guard status != .idle else {
+            currentTask = nil
+            return BuddyTaskPayload(taskId: 0, elapsedSeconds: 0)
+        }
+        let task: ActiveTask
+        if let existing = currentTask, existing.identity == displayIdentity {
+            task = existing
+        } else {
+            task = ActiveTask(identity: displayIdentity, startedAt: Date(), id: nextTaskId)
+            currentTask = task
+            nextTaskId = nextTaskId == 255 ? 1 : nextTaskId + 1
+        }
+        let elapsed = Int(Date().timeIntervalSince(task.startedAt))
+        return BuddyTaskPayload(taskId: task.id, elapsedSeconds: elapsed)
+    }
+
     private func resetEventState() {
         lastSentDisplay = nil
     }

Sources/CodeIslandCore/ESP32Protocol.swift

@@ -18,6 +18,15 @@ import Foundation
 ///   byte[1] = workspaceLen (0..18)
 ///   byte[2..] = workspace UTF-8 (truncated to 18 bytes)
 ///
+/// Downlink task timer frame (4 bytes):
+///   byte[0] = 0xF2          (task frame marker — Mac is the timing authority)
+///   byte[1] = taskId        (rolling 1..255; 0 = no active task)
+///   byte[2] = elapsedSeconds high byte
+///   byte[3] = elapsedSeconds low byte (uint16, seconds the current task has been running)
+///   NOTE: downlink 0xF2 (task) shares its byte value with the *uplink-only* control
+///   opcode 0xF2 (skipCurrentQuestion, Buddy→Mac notify). They never collide because
+///   they travel on different characteristics/directions.
+///
 /// Downlink message preview frame (≤ 20 bytes):
 ///   byte[0] = 0xFB
 ///   byte[1] = messageIndex (0-based)
@@ -81,6 +90,7 @@ public enum ESP32Protocol {
     public static let subagentFrameMarker: UInt8 = 0xF8
     public static let eventFrameMarker: UInt8 = 0xF7
     public static let timeHintFrameMarker: UInt8 = 0xF6
+    public static let taskFrameMarker: UInt8 = 0xF2
     public static let toolHistoryFrameMarker: UInt8 = 0xF5
     public static let maxToolHistoryNameBytes = 11
     public static let approveCurrentPermissionMarker: UInt8 = 0xF0
@@ -508,6 +518,31 @@ public struct BuddyTimeHintPayload: Equatable, Sendable {
     }
 }
 
+/// Task timer frame for Buddy (0xF2).
+///
+/// Mac is the authoritative timekeeper: `taskId` lets the firmware detect a new
+/// task and re-baseline its local clock, `elapsedSeconds` is how long the current
+/// task has been running. A `taskId` of 0 means there is no active task (the
+/// firmware hides the timer).
+public struct BuddyTaskPayload: Equatable, Sendable {
+    public let taskId: UInt8          // 0 = no active task
+    public let elapsedSeconds: UInt16
+
+    public init(taskId: UInt8, elapsedSeconds: Int) {
+        self.taskId = taskId
+        self.elapsedSeconds = UInt16(min(65535, max(0, elapsedSeconds)))
+    }
+
+    public func encode() -> Data {
+        Data([
+            ESP32Protocol.taskFrameMarker,
+            taskId,
+            UInt8(elapsedSeconds >> 8),
+            UInt8(elapsedSeconds & 0xFF),
+        ])
+    }
+}
+
 /// Tool history entry frame for Buddy (0xF5).
 public struct BuddyToolHistoryPayload: Equatable, Sendable {
     public let index: UInt8

Tests/CodeIslandCoreTests/ESP32ProtocolTests.swift

@@ -85,6 +85,19 @@ final class ESP32ProtocolTests: XCTestCase {
         XCTAssertEqual(BuddyBrightnessPayload(percent: Double.nan).percent, ESP32Protocol.defaultBrightnessPercent)
     }
 
+    func testEncodeTaskFrame() {
+        let frame = BuddyTaskPayload(taskId: 7, elapsedSeconds: 300)
+        XCTAssertEqual(Array(frame.encode()), [ESP32Protocol.taskFrameMarker, 7, 0x01, 0x2C])
+    }
+
+    func testTaskFrameClampsAndSplitsElapsedSeconds() {
+        XCTAssertEqual(BuddyTaskPayload(taskId: 0, elapsedSeconds: 0).elapsedSeconds, 0)
+        XCTAssertEqual(BuddyTaskPayload(taskId: 1, elapsedSeconds: -5).elapsedSeconds, 0)
+        XCTAssertEqual(BuddyTaskPayload(taskId: 1, elapsedSeconds: 100_000).elapsedSeconds, 65535)
+        XCTAssertEqual(Array(BuddyTaskPayload(taskId: 1, elapsedSeconds: 100_000).encode()),
+                       [ESP32Protocol.taskFrameMarker, 1, 0xFF, 0xFF])
+    }
+
     func testEncodeScreenOrientationConfigFrame() {
         XCTAssertEqual(
             Array(BuddyScreenOrientationPayload(orientation: .up).encode()),

hardware/hardware.ino

@@ -72,6 +72,7 @@ static char bleDeviceName[BLE_DEVICE_NAME_LEN] = "Buddy";
 // --- Buddy config frames ---
 #define BUDDY_BRIGHTNESS_FRAME          0xFE
 #define BUDDY_ORIENTATION_FRAME         0xFD
+#define BUDDY_TASK_FRAME                0xF2   // Mac-authoritative task timer: [0xF2, taskId, elapsedHi, elapsedLo]
 #define BUDDY_BRIGHTNESS_MIN_PERCENT    10
 #define BUDDY_BRIGHTNESS_MAX_PERCENT    100
 #define BUDDY_BRIGHTNESS_DEFAULT_PERCENT 70
@@ -138,7 +139,7 @@ volatile unsigned long lastBleData = 0;
 volatile unsigned long lastWakeActivity = 0;
 volatile bool     taskTimerActive = false;
 volatile unsigned long taskTimerStart = 0;
-volatile uint8_t  taskTimerSourceId = 0xFF;
+volatile uint8_t  taskTimerId = 0;    // Mac-provided rolling task id (0 = no active task)
 volatile uint8_t  buddyBrightnessPercent = BUDDY_BRIGHTNESS_DEFAULT_PERCENT;
 volatile uint8_t  buddyScreenOrientation = BUDDY_SCREEN_UP;
 volatile bool     buddyOrientationDirty = false;
@@ -337,10 +338,6 @@ bool statusKeepsScreenAwake(uint8_t status) {
   return status == 1 || status == 2 || status == 3 || status == 4;
 }
 
-bool statusHasTaskTimer(uint8_t status) {
-  return status == 1 || status == 2 || status == 3 || status == 4;
-}
-
 uint8_t clampBuddyBrightness(uint8_t percent) {
   if (percent < BUDDY_BRIGHTNESS_MIN_PERCENT) return BUDDY_BRIGHTNESS_MIN_PERCENT;
   if (percent > BUDDY_BRIGHTNESS_MAX_PERCENT) return BUDDY_BRIGHTNESS_MAX_PERCENT;
@@ -741,6 +738,32 @@ class CharCallbacks : public BLECharacteristicCallbacks {
       return;
     }
 
+    // Task timer frame (0xF2): Mac is the timing authority. The firmware no longer
+    // estimates the task start itself — it only adopts the Mac-provided elapsed time
+    // as a baseline and ticks locally via millis() between updates.
+    if (len >= 4 && data[0] == BUDDY_TASK_FRAME) {
+      uint8_t tid = data[1];
+      uint16_t elapsed = ((uint16_t)data[2] << 8) | data[3];
+      unsigned long now_t = millis();
+      portENTER_CRITICAL(&bleMux);
+      if (tid == 0) {
+        taskTimerActive = false;
+        taskTimerStart = 0;
+        taskTimerId = 0;
+      } else {
+        if (tid != taskTimerId) {                 // new task → re-baseline the local clock
+          taskTimerId = tid;
+          unsigned long offset = (unsigned long)elapsed * 1000UL;
+          taskTimerStart = (now_t >= offset) ? (now_t - offset) : 0;
+        }
+        taskTimerActive = true;                    // same task → keep baseline, tick smoothly
+      }
+      lastBleData = now_t;
+      portEXIT_CRITICAL(&bleMux);
+      Serial.printf("[BLE] Task: id=%d elapsed=%us\n", tid, elapsed);
+      return;
+    }
+
 #ifdef BUDDY_OTA_ENABLED
     // OTA SSID frame (0xF4)
     if (len >= 2 && data[0] == 0xF4) {
@@ -833,17 +856,7 @@ class CharCallbacks : public BLECharacteristicCallbacks {
     portENTER_CRITICAL(&bleMux);
     if (bleSourceId != nextSourceId) headerDirty = true;
     if (bleStatusId != nextStatusId) infoDirty = true;
-    if (statusHasTaskTimer(nextStatusId)) {
-      if (!taskTimerActive || taskTimerSourceId != nextSourceId) {
-        taskTimerActive = true;
-        taskTimerStart = now_write;
-        taskTimerSourceId = nextSourceId;
-      }
-    } else {
-      taskTimerActive = false;
-      taskTimerStart = 0;
-      taskTimerSourceId = 0xFF;
-    }
+    // Task timer is driven entirely by the Mac via the 0xF2 task frame (see below).
     bleSourceId = nextSourceId;
     bleStatusId = nextStatusId;
     if (statusKeepsScreenAwake(bleStatusId)) {
@@ -1576,7 +1589,7 @@ void loop() {
       pendingAnim = ANIM_NONE;
       taskTimerActive = false;
       taskTimerStart = 0;
-      taskTimerSourceId = 0xFF;
+      taskTimerId = 0;
       infoDirty = true;
       clearedStaleAgentState = true;
     }