fix: wrap fireHeartbeat in try/catch/finally to prevent timer death

Bug: if pi.sendMessage() or saveState() threw, the exception propagated
uncaught from the setTimeout callback. The armTimer() call at the end
was never reached, permanently killing the heartbeat loop after a single
failure. The consecutiveErrors counter was also never incremented, making
the backoff machinery dead code.

Fix:
- try/catch/finally around the entire fire path
- Success resets consecutiveErrors to 0
- Catch increments consecutiveErrors (drives exponential backoff)
- finally always calls armTimer() so the loop never dies
- saveState() in catch is best-effort (nested try/catch)
- Removed stale comment referencing nonexistent agent_end handler

Added 6 tests simulating the error handling contract.

Author: benvinegar

pi/extensions/heartbeat.test.mjs

@@ -332,6 +332,84 @@ describe("heartbeat: computeBackoffMs", () => {
   });
 });
 
+describe("heartbeat: fireHeartbeat error handling", () => {
+  // Simulate the try/catch/finally pattern from fireHeartbeat to verify
+  // that the error counter and re-arm behavior work correctly.
+
+  function simulateFireHeartbeat(state, sendThrows, saveThrows) {
+    let timerArmed = false;
+
+    try {
+      state.totalRuns += 1;
+
+      if (sendThrows) throw new Error("sendMessage failed");
+
+      // Success — reset error counter
+      state.consecutiveErrors = 0;
+
+      if (saveThrows) throw new Error("saveState failed");
+    } catch {
+      state.consecutiveErrors += 1;
+      try {
+        if (saveThrows) throw new Error("saveState failed in catch");
+      } catch {
+        // Best-effort — don't prevent re-arm
+      }
+    } finally {
+      timerArmed = true;
+    }
+
+    return { timerArmed, state };
+  }
+
+  it("resets consecutiveErrors on success", () => {
+    const state = { consecutiveErrors: 3, totalRuns: 5 };
+    const result = simulateFireHeartbeat(state, false, false);
+    assert.equal(result.state.consecutiveErrors, 0);
+    assert.equal(result.state.totalRuns, 6);
+    assert.equal(result.timerArmed, true);
+  });
+
+  it("increments consecutiveErrors on sendMessage failure", () => {
+    const state = { consecutiveErrors: 0, totalRuns: 5 };
+    const result = simulateFireHeartbeat(state, true, false);
+    assert.equal(result.state.consecutiveErrors, 1);
+    assert.equal(result.timerArmed, true, "timer should always re-arm");
+  });
+
+  it("accumulates errors across multiple failures", () => {
+    const state = { consecutiveErrors: 4, totalRuns: 10 };
+    const result = simulateFireHeartbeat(state, true, false);
+    assert.equal(result.state.consecutiveErrors, 5);
+    assert.equal(result.timerArmed, true, "timer should always re-arm");
+  });
+
+  it("re-arms timer even when both send and save throw", () => {
+    const state = { consecutiveErrors: 0, totalRuns: 0 };
+    const result = simulateFireHeartbeat(state, true, true);
+    assert.equal(result.timerArmed, true, "timer must re-arm regardless of errors");
+    assert.equal(result.state.consecutiveErrors, 1);
+  });
+
+  it("consecutive errors increase backoff delay", () => {
+    const base = 600_000;
+    // After 1 error: 2x
+    assert.equal(computeBackoffMs(1, base), 1_200_000);
+    // After 2 errors: 4x (capped at max)
+    assert.equal(computeBackoffMs(2, base), 2_400_000);
+    // After 3 errors: would be 8x = 4.8M but capped at 3.6M
+    assert.equal(computeBackoffMs(3, base), MAX_BACKOFF_MS);
+  });
+
+  it("success after errors resets to base interval", () => {
+    const state = { consecutiveErrors: 5, totalRuns: 10 };
+    const result = simulateFireHeartbeat(state, false, false);
+    assert.equal(result.state.consecutiveErrors, 0);
+    // With 0 errors, backoff returns base interval
+    assert.equal(computeBackoffMs(result.state.consecutiveErrors, 600_000), 600_000);
+  });
+});
+
 describe("heartbeat: deploy checklist file", () => {
   beforeEach(setup);
   afterEach(teardown);

pi/extensions/heartbeat.ts

@@ -120,45 +120,58 @@ export default function heartbeatExtension(pi: ExtensionAPI): void {
   }
 
   function fireHeartbeat() {
-    const content = readHeartbeatFile(state.heartbeatFile);
-    if (!content) {
-      // No checklist — skip silently, re-arm for next interval
-      armTimer();
-      return;
-    }
-
-    const now = Date.now();
-    state.lastRunAt = now;
-    state.totalRuns += 1;
-
-    const prompt = [
-      `🫀 **Heartbeat** (run #${state.totalRuns}, ${new Date(now).toISOString()})`,
-      ``,
-      `Review the following checklist and take action on any items that need attention.`,
-      `If everything is healthy, respond briefly with what you checked. Do NOT take action unless something is wrong.`,
-      ``,
-      `---`,
-      content,
-      `---`,
-      ``,
-      `If you find issues, fix them. If everything looks good, say so briefly and move on.`,
-    ].join("\n");
-
-    pi.sendMessage(
-      {
-        customType: "heartbeat",
-        content: prompt,
-        display: true,
-      },
-      {
-        deliverAs: "followUp",
-        triggerTurn: true,
+    try {
+      const content = readHeartbeatFile(state.heartbeatFile);
+      if (!content) {
+        // No checklist — skip silently, re-arm for next interval
+        armTimer();
+        return;
       }
-    );
 
-    saveState();
-    // Re-arm after firing (the agent_end handler will also re-arm on error)
-    armTimer();
+      const now = Date.now();
+      state.lastRunAt = now;
+      state.totalRuns += 1;
+
+      const prompt = [
+        `🫀 **Heartbeat** (run #${state.totalRuns}, ${new Date(now).toISOString()})`,
+        ``,
+        `Review the following checklist and take action on any items that need attention.`,
+        `If everything is healthy, respond briefly with what you checked. Do NOT take action unless something is wrong.`,
+        ``,
+        `---`,
+        content,
+        `---`,
+        ``,
+        `If you find issues, fix them. If everything looks good, say so briefly and move on.`,
+      ].join("\n");
+
+      pi.sendMessage(
+        {
+          customType: "heartbeat",
+          content: prompt,
+          display: true,
+        },
+        {
+          deliverAs: "followUp",
+          triggerTurn: true,
+        }
+      );
+
+      // Success — reset error counter
+      state.consecutiveErrors = 0;
+      saveState();
+    } catch (err) {
+      // Increment error counter for backoff — never let the heartbeat die
+      state.consecutiveErrors += 1;
+      try {
+        saveState();
+      } catch {
+        // Best-effort state persistence — don't let a save failure prevent re-arm
+      }
+    } finally {
+      // Always re-arm the timer, even after errors (with backoff)
+      armTimer();
+    }
   }
 
   function stopTimer() {