deepline 0.3.89 → 0.3.91

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/progress-sidecar.ts

@@ -0,0 +1,47 @@
+import type { PlayRunnerEvent } from '../protocol';
+
+export const PLAY_RUNNER_STDOUT_EVENT_MODE_ENV =
+  'DEEPLINE_PLAY_RUNNER_STDOUT_EVENT_MODE';
+
+export const PLAY_RUNNER_STDOUT_EVENT_MODE_COMPACT = 'compact';
+
+const PROGRESS_SIDECAR_LOG_PATTERNS = [
+  /Starting map over \d+ items/i,
+  /Map completed:/i,
+  /\bBatch pass \d+/i,
+  /\bQueue depth before drain:/i,
+  /Executing tool batch/i,
+  /^\[perf\] runtime map /i,
+  /^\[perf\] runtime receipt /i,
+  /^\[perf\] runtime state(?:[ =])/i,
+  /^\[perf\]\[worker\.receipt_writer\.retry\] /i,
+] as const;
+
+function shouldEmitProgressSidecarLog(line: string): boolean {
+  return PROGRESS_SIDECAR_LOG_PATTERNS.some((pattern) => pattern.test(line));
+}
+
+export function shouldEmitProgressSidecarEvent(
+  event: PlayRunnerEvent,
+): boolean {
+  if (event.type === 'execution_event') {
+    return event.event.type !== 'map.row.updated';
+  }
+  if (event.type === 'log') {
+    // Customer-authored ctx.log/console output is part of the run contract,
+    // not a diagnostic sample. Push every play line so detached runners have
+    // useful live logs; keep worker chatter sampled to the progress patterns.
+    return event.source === 'play' || shouldEmitProgressSidecarLog(event.line);
+  }
+  return false;
+}
+
+export function shouldEmitStdoutEvent(
+  event: PlayRunnerEvent,
+  mode = process.env[PLAY_RUNNER_STDOUT_EVENT_MODE_ENV]?.trim(),
+): boolean {
+  if (mode !== PLAY_RUNNER_STDOUT_EVENT_MODE_COMPACT) {
+    return true;
+  }
+  return event.type === 'result';
+}

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/runtime-deadline.ts

@@ -0,0 +1,84 @@
+import type { PlayRunnerExecutionConfig } from '../protocol';
+import {
+  STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+  validatePlaySandboxRuntimeLimits,
+} from '../../plays/sandbox-runtime-limits';
+
+export interface PlayRunnerRuntimeDeadlineOptions {
+  limitMs: number;
+  onDeadline: () => void | Promise<void>;
+  onError?: (error: unknown) => void;
+  setTimeoutImpl?: (callback: () => void, delayMs: number) => unknown;
+  clearTimeoutImpl?: (handle: unknown) => void;
+}
+
+export interface PlayRunnerRuntimeDeadlineHandle {
+  /** Claim normal settlement. False means the deadline already won. */
+  claimCompletion: () => boolean;
+  /** Settles only if the deadline callback unexpectedly returns or rejects. */
+  deadlineSettled: Promise<void>;
+}
+
+export function startConfiguredPlayRunnerRuntimeDeadline(input: {
+  config: Pick<PlayRunnerExecutionConfig, 'context'>;
+  onDeadline: (runtimeLimitSeconds: number) => void | Promise<void>;
+  onError?: (error: unknown) => void;
+  setTimeoutImpl?: (callback: () => void, delayMs: number) => unknown;
+  clearTimeoutImpl?: (handle: unknown) => void;
+}): PlayRunnerRuntimeDeadlineHandle {
+  const runtimeLimits = validatePlaySandboxRuntimeLimits(
+    input.config.context.sandboxRuntimeLimits ?? {
+      ...STANDARD_PLAY_SANDBOX_RUNTIME_LIMITS,
+    },
+  );
+  const runtimeLimitSeconds = runtimeLimits.timeoutSeconds;
+  return startPlayRunnerRuntimeDeadline({
+    limitMs: runtimeLimitSeconds * 1_000,
+    onDeadline: () => input.onDeadline(runtimeLimitSeconds),
+    onError: input.onError,
+    setTimeoutImpl: input.setTimeoutImpl,
+    clearTimeoutImpl: input.clearTimeoutImpl,
+  });
+}
+
+/**
+ * Enforce the user-code deadline inside the sandbox runner. Daytona's detached
+ * session has no asynchronous command timeout, so the parked worker's outer
+ * ceiling is only a salvage backstop and must not be the primary deadline.
+ */
+export function startPlayRunnerRuntimeDeadline(
+  options: PlayRunnerRuntimeDeadlineOptions,
+): PlayRunnerRuntimeDeadlineHandle {
+  const limitMs = Math.max(1, Math.floor(options.limitMs));
+  const setTimeoutImpl =
+    options.setTimeoutImpl ??
+    ((callback, delayMs) => setTimeout(callback, delayMs));
+  const clearTimeoutImpl =
+    options.clearTimeoutImpl ??
+    ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+  let fired = false;
+  let completionClaimed = false;
+  let settleDeadline = () => {};
+  const deadlineSettled = new Promise<void>((resolve) => {
+    settleDeadline = resolve;
+  });
+  const handle = setTimeoutImpl(() => {
+    if (fired || completionClaimed) return;
+    fired = true;
+    void Promise.resolve(options.onDeadline())
+      .catch((error) => {
+        options.onError?.(error);
+      })
+      .finally(() => settleDeadline());
+  }, limitMs);
+
+  return {
+    claimCompletion: () => {
+      if (fired || completionClaimed) return false;
+      completionClaimed = true;
+      clearTimeoutImpl(handle);
+      return true;
+    },
+    deadlineSettled,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/runtime-gateway-transport.ts

@@ -0,0 +1,91 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Privacy-safe runner-to-gateway evidence. Keep payloads, URLs, bearer tokens,
+ * response bodies, and raw error messages out of this shape: it is written to
+ * sandbox stderr and correlated with Fly gateway logs during an incident.
+ */
+export type RunnerGatewayTransportOperation =
+  | 'runner_heartbeat'
+  | 'runner_terminal';
+
+export type RunnerGatewayTransportOutcome =
+  | 'ok'
+  | 'terminal'
+  | 'redirect'
+  | 'gateway_4xx'
+  | 'gateway_5xx'
+  | 'protocol_error'
+  | 'timeout'
+  | 'network_error';
+
+export type RunnerGatewayTransportEvent = {
+  operation: RunnerGatewayTransportOperation;
+  attempt: number;
+  transportAttemptId: string;
+  durationMs: number;
+  outcome: RunnerGatewayTransportOutcome;
+  status?: number;
+  errorCode?: string;
+};
+
+export type RunnerGatewayTransportSummary = {
+  attempts: number;
+  last: RunnerGatewayTransportEvent;
+};
+
+const SAFE_ERROR_CODE = /^(?:E[A-Z0-9_]+|ERR_[A-Z0-9_]+|UND_ERR_[A-Z0-9_]+)$/;
+const SAFE_ERROR_NAMES = new Set(['AbortError', 'TimeoutError', 'TypeError']);
+
+export function createRunnerGatewayTransportAttemptId(): string {
+  return randomUUID();
+}
+
+/** Return a compact class/code without serializing untrusted error text. */
+export function runnerGatewayTransportErrorCode(error: unknown): string {
+  const candidates: unknown[] = [error];
+  if (error && typeof error === 'object' && 'cause' in error) {
+    candidates.push((error as { cause?: unknown }).cause);
+  }
+
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object') continue;
+    const code = (candidate as { code?: unknown }).code;
+    if (typeof code === 'string' && SAFE_ERROR_CODE.test(code)) return code;
+  }
+
+  const name = error instanceof Error ? error.name : '';
+  return SAFE_ERROR_NAMES.has(name) ? name : 'unknown';
+}
+
+export function updateRunnerGatewayTransportSummary(
+  previous: RunnerGatewayTransportSummary | null,
+  event: RunnerGatewayTransportEvent,
+): RunnerGatewayTransportSummary {
+  return {
+    attempts: (previous?.attempts ?? 0) + 1,
+    last: event,
+  };
+}
+
+/** A safe, compact string suitable for the durable failed-run error. */
+export function formatRunnerGatewayTransportSummary(
+  summary: RunnerGatewayTransportSummary | undefined,
+): string {
+  if (!summary) return 'gateway_transport_evidence=unavailable';
+  const { last } = summary;
+  return [
+    `gateway_transport_attempts=${summary.attempts}`,
+    `gateway_transport_operation=${last.operation}`,
+    `gateway_transport_attempt=${last.attempt}`,
+    `gateway_transport_id=${last.transportAttemptId}`,
+    `gateway_transport_outcome=${last.outcome}`,
+    `gateway_transport_duration_ms=${last.durationMs}`,
+    ...(last.status === undefined
+      ? []
+      : [`gateway_transport_status=${last.status}`]),
+    ...(last.errorCode
+      ? [`gateway_transport_error_code=${last.errorCode}`]
+      : []),
+  ].join(' ');
+}

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/runtime-heartbeat.ts

@@ -0,0 +1,424 @@
+import { RUNTIME_CLAIM_HEARTBEAT_DIVISOR } from '../runtime-constants';
+import { PLAY_RUNTIME_TRANSPORT_ATTEMPT_HEADER } from '../runtime-contract';
+import {
+  createRunnerGatewayTransportAttemptId,
+  runnerGatewayTransportErrorCode,
+  updateRunnerGatewayTransportSummary,
+  type RunnerGatewayTransportEvent,
+  type RunnerGatewayTransportSummary,
+} from './runtime-gateway-transport';
+
+/**
+ * Push-execution runner heartbeat loop (runs INSIDE the Daytona sandbox).
+ *
+ * B2-final park-and-wake: the worker PARKS after the detached start and holds
+ * no claim while the sandbox executes, so there is no lease to extend. The
+ * heartbeat is a liveness + CANCELLATION channel: it calls the receipt
+ * gateway's `runner_heartbeat` action on a
+ * `leaseSeconds / RUNTIME_CLAIM_HEARTBEAT_DIVISOR` cadence; the gateway bumps
+ * the attempt row's liveness timestamp and reads the play-level run status.
+ *
+ * The gateway response is the cancellation channel:
+ *  - `{ ok: true, schedulerStatus }` -> run still live. Customer execution
+ *    remains fenced until `schedulerStatus === "waiting"`, proving the worker
+ *    durably parked after observing this runner's heartbeat.
+ *  - `{ ok: false, terminal }` -> the run was cancelled/failed elsewhere; the
+ *    runner must abort the same way the worker's CancelledTask path does. Inside
+ *    the sandbox that means terminating the process loudly — the terminal is
+ *    owned by the scheduler, never by a zombie runner.
+ *
+ * Reachability is bounded (FIX 5): a heartbeat that cannot reach the gateway
+ * for longer than one full lease window self-terminates the runner. An
+ * unreachable gateway also means receipts/tools/terminal-push are down — the
+ * run cannot make durable progress — and a cancelled run must never keep
+ * burning sandbox compute invisibly. The parked attempt's ceiling timeout +
+ * salvage then owns the outcome.
+ */
+
+export type RunnerHeartbeatTerminal = 'cancelled' | 'failed' | 'completed';
+
+export type RunnerHeartbeatResponse =
+  | {
+      ok: true;
+      schedulerStatus: 'queued' | 'running' | 'waiting';
+    }
+  | { ok: false; terminal: RunnerHeartbeatTerminal };
+
+export type RunnerHeartbeatStop =
+  | { reason: 'terminal'; terminal: RunnerHeartbeatTerminal }
+  | {
+      reason: 'unreachable';
+      sinceMs: number;
+      lastError: string;
+      gatewayTransport?: RunnerGatewayTransportSummary;
+    }
+  | { reason: 'stopped' };
+
+export interface RunnerHeartbeatLoopOptions {
+  gatewayBaseUrl: string;
+  executorToken: string;
+  runId: string;
+  leaseSeconds: number;
+  /**
+   * Invoked once when the loop decides the runner must self-terminate (terminal
+   * cancellation channel, or gateway unreachable past the lease window). The
+   * caller wires this to a loud process termination.
+   */
+  onSelfTerminate: (stop: RunnerHeartbeatStop) => void;
+  /** Injectable for tests. Defaults to a bearer POST to the gateway. */
+  sendHeartbeat?: (input: {
+    gatewayBaseUrl: string;
+    executorToken: string;
+    runId: string;
+    leaseSeconds: number;
+    attempt?: number;
+  }) => Promise<RunnerHeartbeatResponse>;
+  /** Injectable timer for tests. Defaults to setInterval. */
+  setIntervalImpl?: (fn: () => void, ms: number) => { unref?: () => void };
+  clearIntervalImpl?: (handle: unknown) => void;
+  /** Injectable clock for tests. Defaults to Date.now. */
+  nowImpl?: () => number;
+  /** Injectable logger for tests. Defaults to console.warn. */
+  warn?: (message: string, detail: Record<string, unknown>) => void;
+  /** Receives privacy-safe sandbox-to-gateway transport evidence. */
+  onTransport?: (event: RunnerGatewayTransportEvent) => void;
+}
+
+export interface RunnerHeartbeatLoopHandle {
+  /** Stop the loop (called when execution settles normally). */
+  stop: () => void;
+  /**
+   * Resolves after the receipt gateway accepts the first heartbeat. Detached
+   * Daytona launch uses this as its handoff fence: the worker must not park
+   * until the runner can reach the durable control plane.
+   */
+  firstHeartbeat: Promise<void>;
+  /**
+   * Resolves only after a heartbeat response proves the scheduler durably
+   * parked this attempt. Customer play execution must await this fence.
+   */
+  executionAcknowledged: Promise<void>;
+  /** Trigger an immediate heartbeat while waiting for the park acknowledgement. */
+  requestHeartbeat: () => void;
+}
+
+const APP_RUNTIME_COMPAT_PATH = '/api/v2/plays/runtime';
+export const RUNNER_HEARTBEAT_REQUEST_TIMEOUT_MS = 10_000;
+// The detached startup deadline is shorter than the normal 40s cadence.
+// Retry initial transport failures while customer execution remains fenced.
+const RUNNER_STARTUP_HEARTBEAT_INTERVAL_MS = 1_000;
+
+export async function sendRunnerHeartbeat(
+  input: {
+    gatewayBaseUrl: string;
+    executorToken: string;
+    runId: string;
+    leaseSeconds: number;
+    attempt?: number;
+  },
+  options: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    nowImpl?: () => number;
+    createTransportAttemptId?: () => string;
+    onTransport?: (event: RunnerGatewayTransportEvent) => void;
+  } = {},
+): Promise<RunnerHeartbeatResponse> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const now = options.nowImpl ?? Date.now;
+  const timeoutMs = Math.max(
+    1,
+    options.timeoutMs ?? RUNNER_HEARTBEAT_REQUEST_TIMEOUT_MS,
+  );
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const url = `${input.gatewayBaseUrl.replace(/\/$/, '')}${APP_RUNTIME_COMPAT_PATH}`;
+  const startedAt = now();
+  const transportAttemptId =
+    options.createTransportAttemptId?.() ??
+    createRunnerGatewayTransportAttemptId();
+  let transportReported = false;
+  const reportTransport = (
+    outcome: RunnerGatewayTransportEvent['outcome'],
+    detail: Pick<RunnerGatewayTransportEvent, 'status' | 'errorCode'> = {},
+  ) => {
+    if (transportReported) return;
+    transportReported = true;
+    try {
+      options.onTransport?.({
+        operation: 'runner_heartbeat',
+        attempt: input.attempt ?? 1,
+        transportAttemptId,
+        durationMs: Math.max(0, now() - startedAt),
+        outcome,
+        ...detail,
+      });
+    } catch {
+      // Diagnostics must never alter the runner's durable control path.
+    }
+  };
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${input.executorToken}`,
+        [PLAY_RUNTIME_TRANSPORT_ATTEMPT_HEADER]: transportAttemptId,
+      },
+      body: JSON.stringify({
+        action: 'runner_heartbeat',
+        runId: input.runId,
+      }),
+      redirect: 'manual',
+      signal: controller.signal,
+    });
+    if (response.status >= 300 && response.status < 400) {
+      // A redirect means the request escaped the gateway to Vercel Deployment
+      // Protection (the sandbox holds no bypass credential). Treat it as a hard
+      // transport failure so the unreachable window logic engages, never as ok.
+      await response.text().catch(() => '');
+      reportTransport('redirect', { status: response.status });
+      throw new Error(
+        `runner_heartbeat was redirected (${response.status}); expected the receipt gateway.`,
+      );
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      let errorCode: string | undefined;
+      try {
+        const parsed = JSON.parse(body) as { code?: unknown };
+        if (
+          typeof parsed.code === 'string' &&
+          /^[A-Z0-9_]{1,64}$/.test(parsed.code)
+        ) {
+          errorCode = parsed.code;
+        }
+      } catch {
+        // A non-JSON gateway failure still has a useful status code.
+      }
+      reportTransport(response.status >= 500 ? 'gateway_5xx' : 'gateway_4xx', {
+        status: response.status,
+        ...(errorCode ? { errorCode } : {}),
+      });
+      throw new Error(`runner_heartbeat failed (${response.status}): ${body}`);
+    }
+    const body = (await response.json().catch(() => null)) as
+      | RunnerHeartbeatResponse
+      | { ok?: unknown; terminal?: unknown; schedulerStatus?: unknown }
+      | null;
+    if (
+      body &&
+      body.ok === false &&
+      (body as { terminal?: unknown }).terminal
+    ) {
+      const terminal = (body as { terminal?: unknown }).terminal;
+      if (
+        terminal === 'cancelled' ||
+        terminal === 'failed' ||
+        terminal === 'completed'
+      ) {
+        reportTransport('terminal', { status: response.status });
+        return { ok: false, terminal };
+      }
+    }
+    if (body && body.ok === true) {
+      const schedulerStatus = (body as { schedulerStatus?: unknown })
+        .schedulerStatus;
+      // Rolling-deploy compatibility: an older gateway returns only
+      // `{ ok: true }`. Treat that as live-but-not-acknowledged so the runner
+      // stays fenced and retries until a new gateway reports `waiting`.
+      if (schedulerStatus === undefined) {
+        reportTransport('ok', { status: response.status });
+        return { ok: true, schedulerStatus: 'running' };
+      }
+      if (
+        schedulerStatus !== 'queued' &&
+        schedulerStatus !== 'running' &&
+        schedulerStatus !== 'waiting'
+      ) {
+        reportTransport('protocol_error', { status: response.status });
+        throw new Error(
+          `runner_heartbeat returned an invalid scheduler status: ${JSON.stringify(schedulerStatus)}`,
+        );
+      }
+      reportTransport('ok', { status: response.status });
+      return { ok: true, schedulerStatus };
+    }
+    reportTransport('protocol_error', { status: response.status });
+    throw new Error(
+      `runner_heartbeat returned an unrecognized body: ${JSON.stringify(body)}`,
+    );
+  } catch (error) {
+    if (!transportReported) {
+      reportTransport(controller.signal.aborted ? 'timeout' : 'network_error', {
+        errorCode: runnerGatewayTransportErrorCode(error),
+      });
+    }
+    if (controller.signal.aborted) {
+      throw new Error(`runner_heartbeat timed out after ${timeoutMs}ms.`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function startRunnerHeartbeatLoop(
+  options: RunnerHeartbeatLoopOptions,
+): RunnerHeartbeatLoopHandle {
+  const setIntervalImpl =
+    options.setIntervalImpl ??
+    ((fn, ms) => setInterval(fn, ms) as unknown as { unref?: () => void });
+  const clearIntervalImpl =
+    options.clearIntervalImpl ??
+    ((handle) => clearInterval(handle as ReturnType<typeof setInterval>));
+  const now = options.nowImpl ?? Date.now;
+  const warn =
+    options.warn ??
+    ((message, detail) =>
+      console.warn(`[play-runner.heartbeat] ${message}`, detail));
+  let gatewayTransport: RunnerGatewayTransportSummary | null = null;
+  const onTransport = (event: RunnerGatewayTransportEvent) => {
+    const notify = () => {
+      try {
+        options.onTransport?.(event);
+      } catch {
+        // Caller-provided diagnostics must never terminate a healthy runner.
+      }
+    };
+    if (event.outcome === 'ok' || event.outcome === 'terminal') {
+      gatewayTransport = null;
+      notify();
+      return;
+    }
+    gatewayTransport = updateRunnerGatewayTransportSummary(
+      gatewayTransport,
+      event,
+    );
+    warn('gateway_transport', {
+      runId: options.runId,
+      ...event,
+    });
+    notify();
+  };
+  const sendHeartbeat =
+    options.sendHeartbeat ??
+    ((input: {
+      gatewayBaseUrl: string;
+      executorToken: string;
+      runId: string;
+      leaseSeconds: number;
+      attempt?: number;
+    }) => sendRunnerHeartbeat(input, { onTransport }));
+
+  const leaseMs = Math.max(1_000, Math.floor(options.leaseSeconds * 1_000));
+  const cadenceMs = Math.max(
+    250,
+    Math.floor(leaseMs / RUNTIME_CLAIM_HEARTBEAT_DIVISOR),
+  );
+
+  let stopped = false;
+  let inFlight = false;
+  let heartbeatAttempt = 0;
+  let lastSuccessAt = now();
+  let handle: { unref?: () => void } | null = null;
+  let resolveFirstHeartbeat: (() => void) | null = null;
+  const firstHeartbeat = new Promise<void>((resolve) => {
+    resolveFirstHeartbeat = resolve;
+  });
+  let resolveExecutionAcknowledged: (() => void) | null = null;
+  const executionAcknowledged = new Promise<void>((resolve) => {
+    resolveExecutionAcknowledged = resolve;
+  });
+
+  const stopLoop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (handle) {
+      clearIntervalImpl(handle);
+      handle = null;
+    }
+  };
+
+  const selfTerminate = (stop: RunnerHeartbeatStop) => {
+    if (stopped) return;
+    stopLoop();
+    options.onSelfTerminate(stop);
+  };
+
+  const tick = () => {
+    if (stopped || inFlight) return;
+    inFlight = true;
+    heartbeatAttempt += 1;
+    void sendHeartbeat({
+      gatewayBaseUrl: options.gatewayBaseUrl,
+      executorToken: options.executorToken,
+      runId: options.runId,
+      leaseSeconds: options.leaseSeconds,
+      attempt: heartbeatAttempt,
+    })
+      .then((result) => {
+        if (stopped) return;
+        if (result.ok === false) {
+          selfTerminate({ reason: 'terminal', terminal: result.terminal });
+          return;
+        }
+        lastSuccessAt = now();
+        if (resolveFirstHeartbeat) {
+          resolveFirstHeartbeat();
+          resolveFirstHeartbeat = null;
+          // Restore the steady-state cadence only after durable startup succeeds.
+          if (handle) clearIntervalImpl(handle);
+          handle = setIntervalImpl(tick, cadenceMs);
+          handle.unref?.();
+        }
+        if (
+          result.schedulerStatus === 'waiting' &&
+          resolveExecutionAcknowledged
+        ) {
+          resolveExecutionAcknowledged();
+          resolveExecutionAcknowledged = null;
+        }
+      })
+      .catch((error) => {
+        if (stopped) return;
+        const sinceMs = now() - lastSuccessAt;
+        const message = error instanceof Error ? error.message : String(error);
+        if (sinceMs > leaseMs) {
+          selfTerminate({
+            reason: 'unreachable',
+            sinceMs,
+            lastError: message,
+            ...(gatewayTransport ? { gatewayTransport } : {}),
+          });
+          return;
+        }
+        warn('heartbeat_failed_retrying', {
+          runId: options.runId,
+          sinceMs,
+          leaseMs,
+          error: message,
+        });
+      })
+      .finally(() => {
+        inFlight = false;
+      });
+  };
+
+  // Keep this timer referenced until the first accepted heartbeat: a pending
+  // Promise alone does not keep Node alive after an initial transport failure.
+  handle = setIntervalImpl(
+    tick,
+    Math.min(cadenceMs, RUNNER_STARTUP_HEARTBEAT_INTERVAL_MS),
+  );
+  // Fire one immediately so a cancel that landed before the first interval is
+  // observed within a cadence, not a full lease window.
+  tick();
+
+  return {
+    stop: stopLoop,
+    firstHeartbeat,
+    executionAcknowledged,
+    requestHeartbeat: tick,
+  };
+}