feat(companion): add heartbeat loop getState snapshot

src/companion/heartbeatLoop.test.ts

@@ -191,5 +191,10 @@ describe('CompanionHeartbeatLoop', () => {
     await loop.tickNow();
     expect(publishHeartbeat).toHaveBeenCalledTimes(1);
     expect(loop.running).toBe(false);
+    expect(loop.getState()).toEqual({
+      running: false,
+      failureCount: 0,
+      lastFailure: null,
+    });
   });
 });

src/companion/heartbeatLoop.ts

@@ -16,6 +16,12 @@ export interface CompanionHeartbeatLoopOptions {
   randomFn?: () => number;
 }
 
+export interface CompanionHeartbeatLoopState {
+  running: boolean;
+  failureCount: number;
+  lastFailure: Error | null;
+}
+
 /**
  * Lightweight periodic heartbeat loop for companion runtimes.
  * Calls `publishHeartbeat` on a fixed interval with optional dynamic payload generation.
@@ -77,6 +83,14 @@ export class CompanionHeartbeatLoop {
     return this.lastError;
   }
 
+  getState(): CompanionHeartbeatLoopState {
+    return {
+      running: this.running,
+      failureCount: this.failureCount,
+      lastFailure: this.lastFailure,
+    };
+  }
+
   start(runImmediately = true): void {
     if (this.started) {
       return;

src/companion/index.ts

@@ -57,4 +57,5 @@ export type {
 export type {
   HeartbeatPublisher,
   CompanionHeartbeatLoopOptions,
+  CompanionHeartbeatLoopState,
 } from './heartbeatLoop.js';