@outputai/core 0.12.0 → 0.12.1-next.1243f78.0

package/src/worker/configs.spec.js

@@ -69,8 +69,8 @@ describe( 'worker/configs', () => {
     expect( configs.workerTelemetryIntervalMs ).toBe( 0 );
     expect( configs.activityHeartbeatIntervalMs ).toBe( 2 * 60 * 1000 );
     expect( configs.activityHeartbeatEnabled ).toBe( true );
-    expect( configs.shutdownForceTime ).toBeUndefined();
-    expect( configs.shutdownGraceTime ).toBeUndefined();
+    expect( configs.shutdownForceTime ).toBe( '25s' );
+    expect( configs.shutdownGraceTime ).toBe( '20s' );
     expect( configs.taskQueue ).toBe( 'test-catalog' );
     expect( configs.catalogId ).toBe( 'test-catalog' );
   } );
@@ -136,15 +136,15 @@ describe( 'worker/configs', () => {
     expect( configs.shutdownGraceTime ).toBe( '15s' );
   } );
 
-  it( 'treats empty Temporal shutdown durations as unset', async () => {
+  it( 'falls back to the defaults when Temporal shutdown durations are empty', async () => {
     setEnv( {
       TEMPORAL_SHUTDOWN_FORCE_TIME: '',
       TEMPORAL_SHUTDOWN_GRACE_TIME: ''
     } );
     const configs = await loadConfigs();
 
-    expect( configs.shutdownForceTime ).toBeUndefined();
-    expect( configs.shutdownGraceTime ).toBeUndefined();
+    expect( configs.shutdownForceTime ).toBe( '25s' );
+    expect( configs.shutdownGraceTime ).toBe( '20s' );
   } );
 
   it( 'throws when Temporal shutdown durations are invalid', async () => {

package/src/worker/connection_monitor.js

@@ -1,101 +1,129 @@
+import { sleepCancellable } from '#helpers/promise';
 import { createChildLogger } from '#logger';
 import { setTimeout as delay } from 'node:timers/promises';
-import { CancellablePromise } from '#helpers/promise';
 
 const log = createChildLogger( 'Connection' );
 
+/** Raised when the connection health check fails repeatedly. */
+export class ConnectionLostError extends Error {
+  name = 'ConnectionLostError';
+};
+
+const MAX_FAILURES = 3;
+const CHECK_INTERVAL_MS = 60_000;
+const CHECK_TIMEOUT_MS = 5_000;
+const HEALTHY_LOG_EVERY_LOOPS = 60;
+
+/**
+ * Watches the Temporal connection health.
+ * Rejects with a ConnectionLostError once the connection is considered lost.
+ */
 export class TemporalConnectionMonitor {
-  #MAX_FAILURES = 3;
-  #CHECK_INTERVAL_MS = 60_000;
-  #CHECK_TIMEOUT_MS = 5_000;
+  #maxFailures = MAX_FAILURES;
+  #checkIntervalMs = CHECK_INTERVAL_MS;
+  #checkTimeoutMs = CHECK_TIMEOUT_MS;
 
-  #cancellation = new CancellablePromise();
+  #abortCtrl = new AbortController();
   #failures = 0;
-  #error = null;
+  #loops = 0;
   #running = false;
-  #watchPromise = null;
+  #execution = null;
   #connection = null;
-  #connectionLostCb = null;
-
-  #getTimeout = async () => delay( this.#CHECK_TIMEOUT_MS, 0, { ref: false } ).then( () => {
-    throw new Error( 'Connection health check timed out' );
-  } );
-
-  #healthcheck = async () => this.#connection.workflowService.getSystemInfo( {} );
+  #signal = null;
 
-  #sleep = async () => delay( this.#CHECK_INTERVAL_MS, 0, { ref: false } );
-
-  #watch = async () => {
-    while ( !this.#cancellation.completed ) {
+  #watch = async signal => {
+    while ( !signal.aborted ) {
       try {
-        await Promise.race( [ this.#healthcheck(), this.#getTimeout(), this.#cancellation.promise ] );
-
-        // cancellation won the race
-        if ( this.#cancellation.completed ) {
-          break;
+        await Promise.race( [
+          this.#connection.workflowService.getSystemInfo( {} ),
+          delay( this.#checkTimeoutMs, 0, { ref: false, signal } ).then( () => {
+            throw new Error( 'Connection health check timed out' );
+          } )
+        ] );
+
+        if ( this.#failures > 0 ) {
+          log.info( 'Recovered' );
+        }
+        if ( this.#loops === 0 || this.#loops % HEALTHY_LOG_EVERY_LOOPS === 0 ) {
+          log.info( 'Healthy' );
         }
-
-        log.info( this.#failures === 0 ? 'Healthy' : 'Recovered' );
         this.#failures = 0;
+
       } catch ( error ) {
-        // cancellation will ignore warnings and not throw errors;
-        if ( this.#cancellation.completed ) {
-          break;
+        // aborting will ignore warnings and not report errors
+        if ( signal.aborted ) {
+          return;
         }
 
-        if ( ++this.#failures >= this.#MAX_FAILURES ) {
-          log.warn( 'Connection lost', { error: error.message, failures: this.#failures } );
-          this.#error = error;
-          this.#connectionLostCb?.( error );
-          this.#cancellation.complete();
-          break;
-        } else {
-          log.warn( 'Connection unhealthy', { error: error.message, failures: this.#failures } );
+        const failureMessage = error?.message ?? String( error );
+        if ( ++this.#failures >= this.#maxFailures ) {
+          log.warn( 'Connection lost', { error: failureMessage, failures: this.#failures } );
+          this.#abortCtrl.abort();
+          throw new ConnectionLostError( 'Connection lost', { cause: error } );
         }
+
+        log.warn( 'Connection unhealthy', { error: failureMessage, failures: this.#failures } );
       }
 
-      await Promise.race( [ this.#sleep(), this.#cancellation.promise ] );
+      this.#loops++;
+      await sleepCancellable( this.#checkIntervalMs, signal );
     }
   };
 
-  constructor( connection, overrides = {} ) {
+  /**
+   * @param {object} options
+   * @param {import('@temporalio/worker').NativeConnection} options.connection - Temporal connection
+   * @param {AbortSignal} options.signal - stops watching when aborted
+   * @param {object} [options.overrides] - health check tuning, mostly for tests
+   */
+  constructor( { connection, signal, overrides = {} } ) {
     this.#connection = connection;
+    this.#signal = signal;
     if ( Number.isFinite( overrides?.maxFailures ) ) {
-      this.#MAX_FAILURES = overrides.maxFailures;
+      this.#maxFailures = overrides.maxFailures;
     }
     if ( Number.isFinite( overrides?.checkIntervalMs ) ) {
-      this.#CHECK_INTERVAL_MS = overrides.checkIntervalMs;
+      this.#checkIntervalMs = overrides.checkIntervalMs;
     }
     if ( Number.isFinite( overrides?.checkTimeoutMs ) ) {
-      this.#CHECK_TIMEOUT_MS = overrides.checkTimeoutMs;
+      this.#checkTimeoutMs = overrides.checkTimeoutMs;
     }
   }
 
-  onConnectionLost( cb ) {
-    this.#connectionLostCb = cb;
-  }
-
+  /** Returns whether the monitor is watching */
   get running() {
     return this.#running;
   }
 
+  /**
+   * Starts watching the connection. Aborting the signal stops the watch.
+   * @returns {Promise<void>} resolves when the watch has stopped, rejects when the connection is lost
+   */
   start() {
-    if ( this.#watchPromise ) {
-      return this.#watchPromise;
+    if ( this.#execution ) {
+      return this.#execution;
+    }
+
+    const signal = AbortSignal.any( [ this.#signal, this.#abortCtrl.signal ] );
+
+    if ( signal.aborted ) {
+      return Promise.resolve();
     }
+
     this.#running = true;
-    this.#watchPromise = this.#watch().finally( () => {
+    this.#execution = this.#watch( signal ).finally( () => {
       this.#running = false;
     } );
-    return this.#watchPromise;
-  }
 
-  stop() {
-    this.#cancellation.complete();
-    return this.#watchPromise ?? Promise.resolve();
+    return this.#execution;
   }
 
-  get connectionLossError() {
-    return this.#error;
+  /**
+   * Stops watching, without reporting a connection loss.
+   * @returns {Promise<void>} resolves when the watch has fully stopped, rejects when it failed
+   */
+  stop() {
+    this.#abortCtrl.abort();
+    return this.#execution ?? Promise.resolve();
   }
 };

package/src/worker/connection_monitor.spec.js

@@ -1,44 +1,51 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { TemporalConnectionMonitor } from './connection_monitor.js';
+import { ConnectionLostError, TemporalConnectionMonitor } from './connection_monitor.js';
 
 const CHECK_TIMEOUT_MS = 50;
 const CHECK_INTERVAL_MS = 100;
 
-const { scheduledDelays, delayMock, mockLogger } = vi.hoisted( () => {
+const { scheduledDelays, delayMock, mockLog } = vi.hoisted( () => {
   const scheduledDelays = [];
-  const delayMock = vi.fn( ( ms, value, options ) => new Promise( resolve => {
+  const abortError = () => Object.assign( new Error( 'The operation was aborted' ), { name: 'AbortError' } );
+
+  // Mirrors node:timers/promises: rejects with an AbortError when the signal aborts, or if already aborted.
+  const delayMock = vi.fn( ( ms, value, options ) => new Promise( ( resolve, reject ) => {
+    const signal = options?.signal;
+
+    if ( signal?.aborted ) {
+      reject( abortError() );
+      return;
+    }
+
     scheduledDelays.push( { ms, value, options, resolve } );
+    signal?.addEventListener( 'abort', () => reject( abortError() ), { once: true } );
   } ) );
 
   return {
     scheduledDelays,
     delayMock,
-    mockLogger: {
-      info: vi.fn(),
-      warn: vi.fn()
-    }
+    mockLog: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }
   };
 } );
 
 vi.mock( 'node:timers/promises', () => ( { setTimeout: delayMock } ) );
-vi.mock( '#logger', () => ( { createChildLogger: vi.fn( () => mockLogger ) } ) );
+vi.mock( '#logger', () => ( { createChildLogger: () => mockLog } ) );
 
-const createConnection = check => ( {
-  workflowService: { getSystemInfo: check }
-} );
+const delayOptions = { ref: false, signal: expect.any( AbortSignal ) };
 
-const createMonitor = ( check, overrides = {} ) => new TemporalConnectionMonitor( createConnection( check ), {
-  checkIntervalMs: CHECK_INTERVAL_MS,
-  checkTimeoutMs: CHECK_TIMEOUT_MS,
-  ...overrides
-} );
+const createMonitor = ( check, overrides = {}, signal = new AbortController().signal ) =>
+  new TemporalConnectionMonitor( {
+    connection: { workflowService: { getSystemInfo: check } },
+    signal,
+    overrides: { checkIntervalMs: CHECK_INTERVAL_MS, checkTimeoutMs: CHECK_TIMEOUT_MS, ...overrides }
+  } );
 
 const flushPromises = async () => Array
   .from( { length: 10 } )
   .reduce( promise => promise.then( () => Promise.resolve() ), Promise.resolve() );
 
 const resolveNextDelay = ms => {
-  const index = scheduledDelays.findIndex( delay => delay.ms === ms );
+  const index = scheduledDelays.findIndex( scheduled => scheduled.ms === ms );
   expect( index ).not.toBe( -1 );
   const [ scheduled ] = scheduledDelays.splice( index, 1 );
   scheduled.resolve( scheduled.value );
@@ -50,133 +57,272 @@ describe( 'TemporalConnectionMonitor', () => {
     scheduledDelays.length = 0;
   } );
 
-  it( 'logs healthy when the workflow service is reachable', async () => {
-    const check = vi.fn().mockResolvedValue( {} );
-    const monitor = createMonitor( check );
+  describe( 'health checks', () => {
+    it( 'logs healthy and schedules the next check when the workflow service is reachable', async () => {
+      const check = vi.fn().mockResolvedValue( {} );
+      const monitor = createMonitor( check );
 
-    const run = monitor.start();
-    await flushPromises();
+      const run = monitor.start();
+      await flushPromises();
 
-    expect( check ).toHaveBeenCalledWith( {} );
-    expect( mockLogger.info ).toHaveBeenCalledWith( 'Healthy' );
-    expect( delayMock ).toHaveBeenCalledWith( CHECK_TIMEOUT_MS, 0, { ref: false } );
-    expect( delayMock ).toHaveBeenCalledWith( CHECK_INTERVAL_MS, 0, { ref: false } );
-    expect( monitor.running ).toBe( true );
+      expect( check ).toHaveBeenCalledWith( {} );
+      expect( mockLog.info ).toHaveBeenCalledWith( 'Healthy' );
+      expect( delayMock ).toHaveBeenCalledWith( CHECK_TIMEOUT_MS, 0, delayOptions );
+      expect( delayMock ).toHaveBeenCalledWith( CHECK_INTERVAL_MS, true, delayOptions );
+      expect( monitor.running ).toBe( true );
 
-    await monitor.stop();
-    await run;
+      await monitor.stop();
+      await run;
 
-    expect( monitor.running ).toBe( false );
-  } );
+      expect( monitor.running ).toBe( false );
+    } );
 
-  it( 'logs transient timeout failures before retrying', async () => {
-    const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
-    const monitor = createMonitor( check );
+    it( 'counts a timed out check as a transient failure', async () => {
+      const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
+      const monitor = createMonitor( check );
 
-    monitor.start();
-    resolveNextDelay( CHECK_TIMEOUT_MS );
-    await flushPromises();
+      const run = monitor.start();
+      resolveNextDelay( CHECK_TIMEOUT_MS );
+      await flushPromises();
 
-    expect( mockLogger.warn ).toHaveBeenCalledWith( 'Connection unhealthy', {
-      error: 'Connection health check timed out',
-      failures: 1
+      expect( mockLog.warn ).toHaveBeenCalledWith( 'Connection unhealthy', {
+        error: 'Connection health check timed out',
+        failures: 1
+      } );
+
+      await monitor.stop();
+      await run;
     } );
 
-    await monitor.stop();
-  } );
+    it( 'logs recovered without a healthy line when the first check fails', async () => {
+      const check = vi.fn()
+        .mockRejectedValueOnce( new Error( 'temporary outage' ) )
+        .mockResolvedValue( {} );
+      const monitor = createMonitor( check );
 
-  it( 'logs recovered after a transient failure succeeds', async () => {
-    const check = vi.fn()
-      .mockRejectedValueOnce( new Error( 'temporary outage' ) )
-      .mockResolvedValueOnce( {} );
-    const monitor = createMonitor( check );
+      const run = monitor.start();
+      await flushPromises();
 
-    monitor.start();
-    await flushPromises();
+      expect( mockLog.warn ).toHaveBeenCalledWith( 'Connection unhealthy', { error: 'temporary outage', failures: 1 } );
 
-    expect( mockLogger.warn ).toHaveBeenCalledWith( 'Connection unhealthy', {
-      error: 'temporary outage',
-      failures: 1
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+
+      expect( mockLog.info ).toHaveBeenCalledOnce();
+      expect( mockLog.info ).toHaveBeenCalledWith( 'Recovered' );
+
+      await monitor.stop();
+      await run;
     } );
 
-    resolveNextDelay( CHECK_INTERVAL_MS );
-    await flushPromises();
+    it( 'logs healthy once while the connection stays reachable', async () => {
+      const check = vi.fn().mockResolvedValue( {} );
+      const monitor = createMonitor( check );
 
-    expect( mockLogger.info ).toHaveBeenCalledWith( 'Recovered' );
+      const run = monitor.start();
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
 
-    await monitor.stop();
-  } );
+      expect( check ).toHaveBeenCalledTimes( 3 );
+      expect( mockLog.info ).toHaveBeenCalledOnce();
+      expect( mockLog.info ).toHaveBeenCalledWith( 'Healthy' );
 
-  it( 'stores connection loss error and calls callback after max consecutive failures', async () => {
-    const error = new Error( 'connection refused' );
-    const check = vi.fn().mockRejectedValue( error );
-    const connectionLost = vi.fn();
-    const monitor = createMonitor( check );
-
-    monitor.onConnectionLost( connectionLost );
-    monitor.start();
-
-    await flushPromises();
-    resolveNextDelay( CHECK_INTERVAL_MS );
-    await flushPromises();
-    resolveNextDelay( CHECK_INTERVAL_MS );
-    await flushPromises();
-
-    expect( mockLogger.warn ).toHaveBeenCalledTimes( 3 );
-    expect( mockLogger.warn ).toHaveBeenCalledWith( 'Connection lost', {
-      error: 'connection refused',
-      failures: 3
-    } );
-    expect( connectionLost ).toHaveBeenCalledWith( error );
-    expect( monitor.connectionLossError ).toBe( error );
-    expect( monitor.running ).toBe( false );
+      await monitor.stop();
+      await run;
+    } );
+
+    it( 'logs recovered on a later failure without repeating healthy', async () => {
+      const check = vi.fn()
+        .mockResolvedValueOnce( {} )
+        .mockRejectedValueOnce( new Error( 'temporary outage' ) )
+        .mockResolvedValue( {} );
+      const monitor = createMonitor( check );
+
+      const run = monitor.start();
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+
+      expect( mockLog.info ).toHaveBeenCalledTimes( 2 );
+      expect( mockLog.info ).toHaveBeenNthCalledWith( 1, 'Healthy' );
+      expect( mockLog.info ).toHaveBeenNthCalledWith( 2, 'Recovered' );
+
+      await monitor.stop();
+      await run;
+    } );
+
+    it( 'describes non error rejections with their string value', async () => {
+      const check = vi.fn().mockRejectedValue( 'socket hang up' );
+      const monitor = createMonitor( check, { maxFailures: 2 } );
+
+      const run = monitor.start();
+      const rejection = expect( run ).rejects.toThrow( ConnectionLostError );
+
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+      await rejection;
+
+      expect( mockLog.warn ).toHaveBeenCalledWith( 'Connection unhealthy', { error: 'socket hang up', failures: 1 } );
+      expect( mockLog.warn ).toHaveBeenCalledWith( 'Connection lost', { error: 'socket hang up', failures: 2 } );
+    } );
   } );
 
-  it( 'returns the same lifecycle promise when started more than once', async () => {
-    const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
-    const monitor = createMonitor( check );
+  describe( 'connection loss', () => {
+    it( 'rejects after the maximum consecutive failures', async () => {
+      const check = vi.fn().mockRejectedValue( new Error( 'connection refused' ) );
+      const monitor = createMonitor( check, { maxFailures: 3 } );
+
+      const run = monitor.start();
+      const rejection = expect( run ).rejects.toThrow( ConnectionLostError );
+
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+      resolveNextDelay( CHECK_INTERVAL_MS );
+      await flushPromises();
+      await rejection;
+
+      expect( check ).toHaveBeenCalledTimes( 3 );
+      expect( mockLog.warn ).toHaveBeenCalledTimes( 3 );
+      expect( mockLog.warn ).toHaveBeenCalledWith( 'Connection lost', { error: 'connection refused', failures: 3 } );
+      expect( monitor.running ).toBe( false );
+    } );
+
+    it( 'preserves the original failure as the error cause', async () => {
+      const error = new Error( 'connection refused' );
+      const check = vi.fn().mockRejectedValue( error );
+      const monitor = createMonitor( check, { maxFailures: 1 } );
 
-    const firstRun = monitor.start();
-    const secondRun = monitor.start();
+      await expect( monitor.start() ).rejects.toMatchObject( {
+        name: 'ConnectionLostError',
+        message: 'Connection lost',
+        cause: error
+      } );
+    } );
 
-    expect( secondRun ).toBe( firstRun );
-    expect( check ).toHaveBeenCalledOnce();
+    it( 'stops watching once the connection is lost', async () => {
+      const check = vi.fn().mockRejectedValue( new Error( 'connection refused' ) );
+      const monitor = createMonitor( check, { maxFailures: 1 } );
+
+      await expect( monitor.start() ).rejects.toThrow( ConnectionLostError );
+      await flushPromises();
+
+      expect( check ).toHaveBeenCalledOnce();
+      expect( monitor.running ).toBe( false );
+    } );
 
-    await monitor.stop();
+    it( 'reports the loss through stop so it is never silent', async () => {
+      const check = vi.fn().mockRejectedValue( new Error( 'connection refused' ) );
+      const monitor = createMonitor( check, { maxFailures: 1 } );
+
+      await expect( monitor.start() ).rejects.toThrow( ConnectionLostError );
+      await expect( monitor.stop() ).rejects.toThrow( ConnectionLostError );
+    } );
   } );
 
-  it( 'stops without calling connection lost callback for in-flight health checks', async () => {
-    const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
-    const connectionLost = vi.fn();
-    const monitor = createMonitor( check, { maxFailures: 1 } );
+  describe( 'abort', () => {
+    it( 'never checks when the signal is already aborted', async () => {
+      const controller = new AbortController();
+      controller.abort();
+      const check = vi.fn();
+      const monitor = createMonitor( check, {}, controller.signal );
+
+      await expect( monitor.start() ).resolves.toBeUndefined();
+
+      expect( check ).not.toHaveBeenCalled();
+      expect( monitor.running ).toBe( false );
+    } );
+
+    it( 'stops without reporting when aborted during a check', async () => {
+      const controller = new AbortController();
+      const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
+      const monitor = createMonitor( check, {}, controller.signal );
+
+      const run = monitor.start();
+      await flushPromises();
 
-    monitor.onConnectionLost( connectionLost );
-    monitor.start();
+      expect( monitor.running ).toBe( true );
 
-    expect( monitor.running ).toBe( true );
+      controller.abort();
 
-    await monitor.stop();
+      await expect( run ).resolves.toBeUndefined();
+      expect( mockLog.warn ).not.toHaveBeenCalled();
+      expect( monitor.running ).toBe( false );
+    } );
+
+    it( 'stops without reporting when aborted between checks', async () => {
+      const controller = new AbortController();
+      const check = vi.fn().mockResolvedValue( {} );
+      const monitor = createMonitor( check, {}, controller.signal );
+
+      const run = monitor.start();
+      await flushPromises();
+
+      expect( mockLog.info ).toHaveBeenCalledWith( 'Healthy' );
 
-    expect( connectionLost ).not.toHaveBeenCalled();
-    expect( monitor.connectionLossError ).toBeNull();
-    expect( monitor.running ).toBe( false );
+      controller.abort();
+
+      await expect( run ).resolves.toBeUndefined();
+      expect( check ).toHaveBeenCalledOnce();
+      expect( mockLog.warn ).not.toHaveBeenCalled();
+    } );
   } );
 
-  it( 'applies timing and failure threshold overrides', async () => {
-    const error = new Error( 'fast failure' );
-    const check = vi.fn().mockRejectedValue( error );
-    const connectionLost = vi.fn();
-    const monitor = createMonitor( check, {
-      maxFailures: 1,
-      checkIntervalMs: 7,
-      checkTimeoutMs: 3
+  describe( 'lifecycle', () => {
+    it( 'returns the same watch when started more than once', async () => {
+      const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
+      const monitor = createMonitor( check );
+
+      const first = monitor.start();
+      const second = monitor.start();
+
+      expect( second ).toBe( first );
+      expect( check ).toHaveBeenCalledOnce();
+
+      await monitor.stop();
+      await first;
+    } );
+
+    it( 'stops an in flight check without reporting a failure', async () => {
+      const check = vi.fn().mockReturnValue( new Promise( () => {} ) );
+      const monitor = createMonitor( check, { maxFailures: 1 } );
+
+      const run = monitor.start();
+
+      expect( monitor.running ).toBe( true );
+
+      await monitor.stop();
+      await run;
+
+      expect( mockLog.warn ).not.toHaveBeenCalled();
+      expect( monitor.running ).toBe( false );
     } );
 
-    monitor.onConnectionLost( connectionLost );
-    await monitor.start();
+    it( 'never watches when stopped before starting', async () => {
+      const check = vi.fn();
+      const monitor = createMonitor( check );
+
+      await expect( monitor.stop() ).resolves.toBeUndefined();
+      await expect( monitor.start() ).resolves.toBeUndefined();
+
+      expect( check ).not.toHaveBeenCalled();
+      expect( monitor.running ).toBe( false );
+    } );
 
-    expect( delayMock ).toHaveBeenCalledWith( 3, 0, { ref: false } );
-    expect( delayMock ).not.toHaveBeenCalledWith( 7, 0, { ref: false } );
-    expect( connectionLost ).toHaveBeenCalledWith( error );
+    it( 'applies the timing and failure threshold overrides', async () => {
+      const check = vi.fn().mockRejectedValue( new Error( 'fast failure' ) );
+      const monitor = createMonitor( check, { maxFailures: 1, checkIntervalMs: 7, checkTimeoutMs: 3 } );
+
+      await expect( monitor.start() ).rejects.toThrow( ConnectionLostError );
+
+      expect( delayMock ).toHaveBeenCalledWith( 3, 0, delayOptions );
+      expect( delayMock ).not.toHaveBeenCalledWith( 7, true, delayOptions );
+    } );
   } );
 } );