feat(companion): expose heartbeat loop failure observability

src/companion/heartbeatLoop.test.ts

@@ -109,9 +109,13 @@ describe('CompanionHeartbeatLoop', () => {
     loop.start();
     await Promise.resolve();
     expect(onError).toHaveBeenCalledTimes(1);
+    expect(loop.failureCount).toBe(1);
+    expect(loop.lastFailure?.message).toBe('boom');
 
     await vi.advanceTimersByTimeAsync(400);
     expect(publishHeartbeat).toHaveBeenCalledTimes(2);
+    expect(loop.failureCount).toBe(0);
+    expect(loop.lastFailure).toBeNull();
 
     loop.stop();
   });
@@ -154,6 +158,8 @@ describe('CompanionHeartbeatLoop', () => {
 
     await vi.advanceTimersByTimeAsync(300);
     expect(loop.running).toBe(false);
+    expect(loop.failureCount).toBe(2);
+    expect(loop.lastFailure?.message).toBe('persistent-failure');
     expect(onError).toHaveBeenCalledTimes(2);
     expect(onFailureLimitReached).toHaveBeenCalledTimes(1);
     expect(onFailureLimitReached).toHaveBeenCalledWith(expect.any(Error), 2);

src/companion/heartbeatLoop.ts

@@ -33,6 +33,7 @@ export class CompanionHeartbeatLoop {
   private started = false;
   private inFlight = false;
   private consecutiveFailures = 0;
+  private lastError: Error | null = null;
 
   constructor(publisher: HeartbeatPublisher, options: CompanionHeartbeatLoopOptions = {}) {
     const intervalMs = options.intervalMs ?? 30_000;
@@ -65,12 +66,21 @@ export class CompanionHeartbeatLoop {
     return this.started;
   }
 
+  get failureCount(): number {
+    return this.consecutiveFailures;
+  }
+
+  get lastFailure(): Error | null {
+    return this.lastError;
+  }
+
   start(runImmediately = true): void {
     if (this.started) {
       return;
     }
     this.started = true;
     this.consecutiveFailures = 0;
+    this.lastError = null;
 
     if (runImmediately) {
       void this.tick();
@@ -121,9 +131,11 @@ export class CompanionHeartbeatLoop {
       const payload = this.buildHeartbeat ? await this.buildHeartbeat() : undefined;
       await this.publisher.publishHeartbeat(payload);
       this.consecutiveFailures = 0;
+      this.lastError = null;
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       this.consecutiveFailures += 1;
+      this.lastError = err;
       this.onError?.(err);
       if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
         this.onFailureLimitReached?.(err, this.consecutiveFailures);