@oar-sh/oar 0.9.21 → 0.9.22

package/server/services/session-history-refresh-service.mjs

@@ -367,6 +367,9 @@ export function createSessionHistoryRefreshService({
           timestamp,
           activity.subagentRunId,
           activity.metadata ? JSON.stringify(activity.metadata) : null,
+          // turn_seq: an imported turn has no order of its own; it keeps the
+          // grouped layout.
+          null,
         );
       }
       const thoughts = ensureArray(message?.thoughts)
@@ -386,6 +389,7 @@ export function createSessionHistoryRefreshService({
           thought.done ? 1 : 0,
           timestamp,
           thought.subagentRunId,
+          null, // turn_seq, as for the activity rows above
         );
       }
     }

package/server/services/session-worker-supervisor-service.mjs

@@ -88,6 +88,12 @@ export function createSessionWorkerSupervisor({
   // short enough that stopping a turn and immediately sending a new message
   // does not add 30s in front of the worker's boot.
   killBlockGraceMs = 3_000,
+  // A kill's block on new launches and deliveries for the session ended (its
+  // grace ran out, or the marker was cleared): (sessionId). The relay hands
+  // out what waited for it.
+  onKillBlockLifted = null,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
   isPidAlive = defaultIsPidAlive,
   diagnosticPlanReference = null,
   log = null,
@@ -98,6 +104,8 @@ export function createSessionWorkerSupervisor({
 
   const pendingStarts = new Map();
   const lifecycleBySession = new Map();
+  // sessionId → the timer that reports the end of its kill block.
+  const killBlockTimers = new Map();
   const retryLimit = Math.max(0, clampInt(maxRestartRetries, 5));
   const backoffBaseMs = Math.max(1, clampInt(restartBackoffBaseMs, 1_000));
   const backoffMaxMs = Math.max(backoffBaseMs, clampInt(restartBackoffMaxMs, 30_000));
@@ -301,9 +309,35 @@ export function createSessionWorkerSupervisor({
     });
   }
 
+  function reportKillBlockLifted(sessionId) {
+    if (typeof onKillBlockLifted !== 'function') return;
+    try { onKillBlockLifted(sessionId); } catch {}
+  }
+
+  function clearKillBlockTimer(sessionId) {
+    const timer = killBlockTimers.get(sessionId);
+    if (!timer) return false;
+    clearTimeoutImpl(timer);
+    killBlockTimers.delete(sessionId);
+    return true;
+  }
+
   function markKilled(sessionId) {
     if (!normalizeSessionId(sessionId)) return null;
     const killed = setLifecycle(sessionId, { killedAtMs: nowMs() });
+    // The block itself is read off the clock (isKillBlocked); this timer only
+    // says when it ends, so the rows that waited go out then.
+    if (killGraceMs > 0 && typeof onKillBlockLifted === 'function') {
+      clearKillBlockTimer(sessionId);
+      const timer = setTimeoutImpl(() => {
+        killBlockTimers.delete(sessionId);
+        if (!isKillBlocked(sessionId)) reportKillBlockLifted(sessionId);
+        // A few ms past the grace: the timer's clock and nowMs() may differ
+        // by a tick.
+      }, killGraceMs + 5);
+      timer?.unref?.();
+      killBlockTimers.set(sessionId, timer);
+    }
     return toLifecycleSnapshot(sessionId, killed);
   }
 
@@ -489,10 +523,12 @@ export function createSessionWorkerSupervisor({
       patch.degradedAtMs = null;
       patch.uiState = 'white';
     }
+    const liftsKillBlock = resetKilledMarker && clearKillBlockTimer(sessionId);
     if (resetKilledMarker) {
       patch.killedAtMs = null;
     }
     const cleared = setLifecycle(sessionId, patch);
+    if (liftsKillBlock) reportKillBlockLifted(sessionId);
     return toLifecycleSnapshot(sessionId, cleared);
   }
 

package/server/services/session-worker-websocket-service.mjs

@@ -86,18 +86,21 @@ function queueSnapshotChanged(left, right) {
     || left.parkedCount !== right.parkedCount;
 }
 
-// The worker link heartbeats every ~10s (readyRefreshMs in
-// worker-websocket-link.mjs) and itself abandons a connection after 30s of
-// server silence (staleConnectionMs). Mirror that on this side: three missed
-// heartbeats and a retained socket no longer proves the worker is alive.
-const WORKER_SOCKET_LIVENESS_MAX_SILENCE_MS = 30_000;
+// The worker keepalive beats every 30 s while the worker is idle and every
+// 10 s while it works (shared/worker-runtime/worker-keepalive.mjs; an older
+// worker always every 10 s), and the link itself abandons a connection after
+// 90 s of server silence (staleConnectionMs). Mirror that on this side: three
+// missed idle beats and a retained socket no longer proves the worker is
+// alive.
+export const WORKER_SOCKET_LIVENESS_MAX_SILENCE_MS = 90_000;
 
 // Protocol features this relay understands, advertised in server.hello. A
 // worker that updated on disk before the relay restarted must not rely on
 // them otherwise: an older relay ignores worker.unready / hello ready:false
 // and treats a `steering-held` requeue as a failure (retry, backoff,
-// worker marked errored).
-export const WORKER_PROTOCOL_CAPABILITIES = Object.freeze(['worker-unready', 'steering-held']);
+// worker marked errored). `idle-keepalive`: an idle worker may beat every
+// 30 s; an older relay's liveness and CLI windows expect a beat every 10 s.
+export const WORKER_PROTOCOL_CAPABILITIES = Object.freeze(['worker-unready', 'steering-held', 'idle-keepalive']);
 
 export function createSessionWorkerWebSocketService({
   WebSocketServerImpl,
@@ -108,6 +111,19 @@ export function createSessionWorkerWebSocketService({
   noteWorkerHeartbeat = () => {},
   onDeliverySendFailed = async () => {},
   onWorkerSocketClosed = async () => {},
+  // The number of open worker sockets changed: (count). The CLI presence
+  // window is wider while a worker socket is open.
+  onSocketCountChange = () => {},
+  // Every queue snapshot the poll takes: ({pendingCount, processingCount,
+  // parkedCount}). The relay arms its worker prime while rows are pending.
+  onQueueSnapshot = () => {},
+  // The earliest future retry time of a pending row, in ms (null: none). A
+  // one-shot timer fires then, so a backoff or a usage-limit hold ends on
+  // time rather than at the next poll.
+  nextDueAtMs = () => null,
+  // That timer fired with a row due: the relay wakes its queue (prime, hand
+  // out, arm), since a row whose hold ended may have no worker yet.
+  onDue = () => {},
   requestWork = async () => null,
   // A worker stated its kind ("claude", "claude-api", ...) in a hello or a
   // ready: (sessionId, kind, pid). The registry keeps it.
@@ -147,6 +163,10 @@ export function createSessionWorkerWebSocketService({
   const relayBuildId = normalizeBuildId(buildId);
 
   let interval = null;
+  let dueTimer = null;
+  // The retry time the armed due timer stands for.
+  let dueTimerForMs = null;
+  let stopped = false;
   let lastSnapshot = null;
   let attached = false;
 
@@ -155,10 +175,15 @@ export function createSessionWorkerWebSocketService({
     return Number.isFinite(value) ? value : Date.now();
   }
 
+  function noteSocketCount() {
+    try { onSocketCountChange(clients.size); } catch {}
+  }
+
   function removeSocket(socket, reason) {
     const meta = clientState.get(socket);
-    clients.delete(socket);
+    const removed = clients.delete(socket);
     clientState.delete(socket);
+    if (removed) noteSocketCount();
     // Death-detection hook: a worker socket closing while its session owns
     // an in-flight processing row used to be silently forgotten, leaving
     // the row to the 600s stale sweep. The handler PID-probes and recovers.
@@ -222,11 +247,12 @@ export function createSessionWorkerWebSocketService({
     };
   }
 
-  function emitQueueChanged(reason = 'queue-update') {
+  function emitQueueChanged(reason = 'queue-update', { skip = null } = {}) {
     const event = toQueueChangedEvent(reason);
     const payload = JSON.stringify(event);
     for (const socket of clients) {
       if (socket.readyState !== socket.OPEN) continue;
+      if (skip?.has(socket)) continue;
       try {
         socket.send(payload);
       } catch {
@@ -364,25 +390,115 @@ export function createSessionWorkerWebSocketService({
     }
   }
 
+  /** Hands a row to every ready socket; resolves to the sockets that got one. */
   async function maybeDeliverToReadyClients(reason = 'queue-update') {
+    const sockets = [];
     const deliveries = [];
     for (const socket of clients) {
       const meta = clientState.get(socket);
       if (!meta?.ready || meta.delivering) continue;
+      sockets.push(socket);
       deliveries.push(maybeDeliverToSocket(socket, reason));
     }
-    if (!deliveries.length) return;
-    await Promise.allSettled(deliveries);
+    const handed = new Set();
+    if (!deliveries.length) return handed;
+    const results = await Promise.allSettled(deliveries);
+    results.forEach((result, index) => {
+      if (result.status === 'fulfilled' && result.value === true) handed.add(sockets[index]);
+    });
+    return handed;
+  }
+
+  // Ready sockets get their rows first; then every other socket hears that
+  // the queue changed (a worker the relay does not count as ready, a steering
+  // one mid-turn, answers with a ready of its own). A socket just handed a
+  // row is busy with it and is not told.
+  async function deliverThenAnnounce(reason, { announce = true } = {}) {
+    const handed = await maybeDeliverToReadyClients(reason);
+    if (announce) emitQueueChanged(reason, { skip: handed });
+    return handed;
+  }
+
+  /**
+   * The queue may have work: a write, a gate that lifted, a retry come due.
+   * Hands rows out now instead of at the next poll.
+   */
+  async function notifyQueueChanged(reason = 'queue-update') {
+    if (stopped) return new Set();
+    lastSnapshot = normalizeQueueSnapshot(queueCounts());
+    // A turn that ended with nothing behind it: no row to hand out, so no
+    // dequeue attempt per ready socket and no announcement.
+    const handed = lastSnapshot.pendingCount > 0 ? await deliverThenAnnounce(reason) : new Set();
+    armDueTimer();
+    return handed;
   }
 
+  // The backstop. With nothing pending nothing can be handed out: no dequeue
+  // attempt, only the count change announced. With rows pending (a retry in
+  // backoff, a gate, a worker not yet up) every tick tries the ready sockets,
+  // as a net under the event-driven wakes.
   function monitorQueue() {
     const snapshot = normalizeQueueSnapshot(queueCounts());
+    try { onQueueSnapshot(snapshot); } catch {}
     const changed = queueSnapshotChanged(snapshot, lastSnapshot);
     lastSnapshot = snapshot;
-    if (changed) {
+    if (snapshot.pendingCount > 0) {
+      void deliverThenAnnounce(changed ? 'queue-count-changed' : 'ready-check', { announce: changed });
+    } else if (changed) {
       emitQueueChanged('queue-count-changed');
     }
-    void maybeDeliverToReadyClients(changed ? 'queue-count-changed' : 'ready-check');
+    armDueTimer();
+  }
+
+  const DUE_TIMER_MIN_MS = 50;
+  const DUE_TIMER_MAX_MS = 60_000;
+
+  function clearDueTimer() {
+    dueTimerForMs = null;
+    if (!dueTimer) return;
+    clearTimeout(dueTimer);
+    dueTimer = null;
+  }
+
+  /**
+   * One timer for the earliest future retry time. An armed timer for the same
+   * time is kept; any other arm clears the one before. A time further than a
+   * minute away is re-read after a minute.
+   */
+  function armDueTimer() {
+    if (stopped) {
+      clearDueTimer();
+      return;
+    }
+    // A timer whose time has come fires and re-arms itself: a poll in the
+    // same instant (its row no longer "future") must not clear it unfired.
+    if (dueTimer && dueTimerForMs !== null && dueTimerForMs <= nowMsSafe()) return;
+    let dueAt = null;
+    try { dueAt = nextDueAtMs(); } catch { dueAt = null; }
+    const dueMs = Number(dueAt);
+    if (dueAt === null || dueAt === undefined || !Number.isFinite(dueMs)) {
+      clearDueTimer();
+      return;
+    }
+    if (dueTimer && dueTimerForMs === dueMs) return;
+    clearDueTimer();
+    const untilDueMs = dueMs - nowMsSafe();
+    const delayMs = Math.min(DUE_TIMER_MAX_MS, Math.max(DUE_TIMER_MIN_MS, untilDueMs));
+    // A time further than the cap: this firing only re-reads.
+    const reachesDue = untilDueMs <= DUE_TIMER_MAX_MS;
+    dueTimerForMs = dueMs;
+    dueTimer = setTimeout(() => {
+      dueTimer = null;
+      dueTimerForMs = null;
+      if (stopped) return;
+      if (reachesDue) {
+        // Whatever came due may go now; a row that was claimed or cancelled
+        // meanwhile makes this a wake with nothing to do.
+        try { onDue('retry-due'); } catch {}
+      }
+      armDueTimer();
+    }, delayMs);
+    if (typeof dueTimer.unref === 'function') dueTimer.unref();
   }
 
   function rejectUpgrade(socket) {
@@ -432,6 +548,7 @@ export function createSessionWorkerWebSocketService({
       deliveryFailures: 0,
     });
     if (identity.sessionId) supersedePriorSockets(ws, identity.sessionId);
+    noteSocketCount();
     touchCli();
     emitEvent(ws, serverHello('connected', identity.sessionId));
 
@@ -466,8 +583,13 @@ export function createSessionWorkerWebSocketService({
         noteWorkerBuildId(meta, payload);
         meta.ready = true;
         meta.lastReadyAt = nowIso();
-        noteHeartbeat(meta, String(payload.reason || 'worker-ready'));
-        void maybeDeliverToSocket(ws, String(payload.reason || 'worker-ready'));
+        const readyReason = String(payload.reason || 'worker-ready');
+        noteHeartbeat(meta, readyReason);
+        // A keepalive's ready with nothing pending has nothing to draw: one
+        // count instead of a dequeue attempt. Any row that appears wakes the
+        // queue, and this socket stays ready for it.
+        if (readyReason === 'readiness-refresh' && normalizeQueueSnapshot(queueCounts()).pendingCount === 0) return;
+        void maybeDeliverToSocket(ws, readyReason);
         return;
       }
       if (payload.type === 'worker.unready') {
@@ -526,6 +648,7 @@ export function createSessionWorkerWebSocketService({
   }
 
   function start() {
+    stopped = false;
     if (!attached) {
       httpServer.on('upgrade', onUpgrade);
       wss.on('connection', onConnection);
@@ -537,10 +660,13 @@ export function createSessionWorkerWebSocketService({
     }
     lastSnapshot = normalizeQueueSnapshot(queueCounts());
     emitQueueChanged('started');
+    armDueTimer();
     logDebug(`[worker-ws] listening on ${wsPath}`);
   }
 
   function stop() {
+    stopped = true;
+    clearDueTimer();
     if (interval) {
       clearInterval(interval);
       interval = null;
@@ -554,6 +680,7 @@ export function createSessionWorkerWebSocketService({
     }
     clients.clear();
     clientState.clear();
+    noteSocketCount();
     try { wss.close(); } catch (error) {
       logWarn(`[worker-ws] close failed: ${error?.message || error}`);
     }
@@ -610,6 +737,7 @@ export function createSessionWorkerWebSocketService({
     stop,
     status,
     emitQueueChanged,
+    notifyQueueChanged,
     emitDraining,
     handleUpgrade,
     sendControlToSession,

package/server/services/ssh-tunnel-manager-service.mjs

@@ -171,6 +171,9 @@ export function createSshTunnelManager({
   io = null,
   logger = console,
   runtimeShutdownRef = () => false,
+  // The tunnel stopped blocking queue delivery (it connected): the relay
+  // hands out what waited for it.
+  onBlockingLifted = () => {},
   platform = process.platform,
   spawnImpl = spawn,
   nowIso = () => new Date().toISOString(),
@@ -225,7 +228,11 @@ export function createSshTunnelManager({
   };
 
   const updateBlockingState = () => {
+    const wasBlocking = state.blocking;
     state.blocking = state.required && state.mode === 'managed' && !state.connected;
+    if (wasBlocking && !state.blocking) {
+      try { onBlockingLifted(); } catch {}
+    }
   };
 
   const scheduleReconnect = (spawnTunnel, delayOverrideMs = null) => {

package/shared/ask-user-bridge.mjs

@@ -67,7 +67,10 @@ export function createAskUserBridge({
     });
   }
 
-  async function askSingleQuestion(entry, { signal } = {}) {
+  // `source` / `rationale` override the bridge-wide card identity for one ask
+  // (the Claude worker's safety-check approvals are not clarifications), and
+  // `allowFreeform: false` makes a card answered by its choices alone.
+  async function askSingleQuestion(entry, { signal, source, rationale, allowFreeform } = {}) {
     const activeMsg = typeof getActiveMessage === 'function' ? getActiveMessage() : null;
     const choices = entry.options.map((option) => option.label);
     const promptParts = [entry.question];
@@ -82,7 +85,7 @@ export function createAskUserBridge({
       mode: activeMsg?.relayMode || 'agent',
       prompt: promptParts.join('\n\n'),
       choices,
-      allowFreeform: true,
+      allowFreeform: allowFreeform !== false,
       // Top-level, as the create route reads it (elicitation parity; absent
       // for the flat question shape every existing caller sends).
       ...(entry.requestedSchema ? { requestedSchema: entry.requestedSchema } : {}),
@@ -92,8 +95,8 @@ export function createAskUserBridge({
       attemptId: activeMsg?.attemptId || undefined,
       timeout_ms: questionTimeoutMs,
       context: {
-        source: questionSource,
-        rationale: questionRationale,
+        source: source || questionSource,
+        rationale: rationale || questionRationale,
         queueMessageId: activeMsg?.id || null,
         conversationId: activeMsg?.conversationId || null,
         relayMode: activeMsg?.relayMode || 'agent',
@@ -106,7 +109,7 @@ export function createAskUserBridge({
     return waitForRelayQuestionAnswer(questionId, { signal });
   }
 
-  async function handleAskUserQuestion(input, { signal } = {}) {
+  async function handleAskUserQuestion(input, { signal, source, rationale, allowFreeform } = {}) {
     const questions = normalizeQuestions(input);
     if (!questions.length) {
       return { answers: {}, structuredAnswers: {}, timedOut: false };
@@ -118,7 +121,7 @@ export function createAskUserBridge({
     const structuredAnswers = {};
     let timedOut = false;
     for (const entry of questions) {
-      const result = await askSingleQuestion(entry, { signal });
+      const result = await askSingleQuestion(entry, { signal, source, rationale, allowFreeform });
       answers[entry.question] = result.answer;
       if (result.structuredAnswer) structuredAnswers[entry.question] = result.structuredAnswer;
       if (entry.rawQuestion && entry.rawQuestion !== entry.question) {

package/shared/relay-asks.mjs

@@ -25,6 +25,11 @@ export const RELAY_QUESTION_KINDS = Object.freeze(['ask', 'ask_user', 'approval'
 // Stored and sent between relays, so it kept the tool's name from before
 // 0.9.18.
 export const REMOTE_RELAY_APPROVAL_SOURCE = 'remote_relay';
+// The `context.source` of a Claude session's Safety check card: an ask Claude
+// Code marks as person-only (claude-sdk-adapter.mjs). Like the approval card,
+// it is the user's to answer: never listed to an agent, never answered by
+// one, from this relay or another.
+export const PERSON_ONLY_QUESTION_SOURCE = 'ClaudeSafetyCheck';
 export const RELAY_ASK_KIND = 'ask';
 
 export const RELAY_ASK_URGENCIES = Object.freeze(['normal', 'now']);
@@ -145,6 +150,11 @@ export function normalizeRelayAskAnswer(ask, { answer = '', choice = '' } = {})
   return { ok: true, value: { answer: text || picked, choice: picked } };
 }
 
+/** True for a Safety check card's context (a formatted question's or a stored request envelope's). */
+export function isPersonOnlyQuestion(context) {
+  return !!context && typeof context === 'object' && toText(context.source) === PERSON_ONLY_QUESTION_SOURCE;
+}
+
 /** The kind of a formatted question card (a row of /api/relay-questions). */
 export function relayQuestionKind(question) {
   const kind = toText(question?.kind);

package/shared/relay-events.mjs

@@ -560,6 +560,7 @@ export function formatRelayEventLine(event) {
       const parts = [`${head} ${quote(detail.prompt, RELAY_EVENT_LIMITS.questionChars)}`];
       if (options.length) parts.push(`options: ${options.map((option) => `[${option}]`).join(' ')}`);
       if (detail.approvalCard) parts.push('(an approval card: only the user can answer it)');
+      else if (detail.personOnly) parts.push('(a Safety check: the user\'s to answer)');
       else if (oneLine(detail.questionId, 80)) parts.push(`(question_id ${oneLine(detail.questionId, 80)})`);
       if (detail.kind === 'ask') parts.push('(asked with ask: it does not block that session)');
       return parts.join(' ');

package/shared/worker-runtime/heartbeat.mjs

@@ -33,6 +33,10 @@ export function createHeartbeatController({
   // Optional: called after every beat the relay answered, for work that
   // waits for a reachable relay (posts kept after a failure).
   onAnswered = () => {},
+  // Optional: how many posts are kept for a reachable relay (flushed by
+  // onAnswered). While any is, the worker counts as busy, so the next beat,
+  // which flushes them, is not an idle wait away.
+  getKeptPostCount = null,
   // Optional: the kind of worker this is ("claude", "claude-api", ...). The
   // relay hands a Claude chat's row only to a worker of the row's billing,
   // and knows a worker's kind from what it says here and in its hello.
@@ -99,6 +103,27 @@ export function createHeartbeatController({
     }
   }
 
+  /**
+   * Whether the worker has work the relay follows by its beats: a row it
+   * owns, a live background task, a running turn, a settle failure to report,
+   * a kept post to flush.
+   * The keepalive beats at its busy cadence while this holds
+   * (worker-keepalive.mjs). A getter that throws counts as work.
+   */
+  function hasWork() {
+    try {
+      if (typeof getActiveQueueMessageId === "function" && String(getActiveQueueMessageId() || "").trim()) return true;
+      if (typeof getActiveQueueMessageIds === "function" && (getActiveQueueMessageIds() || []).length) return true;
+      if (typeof getBackgroundTaskIds === "function" && (getBackgroundTaskIds() || []).length) return true;
+      if (typeof getSettleFailed === "function" && (getSettleFailed() || []).length) return true;
+      if (typeof getKeptPostCount === "function" && Number(getKeptPostCount()) > 0) return true;
+      if (typeof getSteeringState === "function" && getSteeringState()?.turnActive === true) return true;
+      return false;
+    } catch {
+      return true;
+    }
+  }
+
   /**
    * An out-of-cycle pulse for state the relay should see before the next
    * periodic one (the composer's steering snapshot, a relay that just came
@@ -135,6 +160,7 @@ export function createHeartbeatController({
   }
 
   return {
+    hasWork,
     pulseHeartbeat,
     requestPulse,
     startHeartbeat,

package/shared/worker-runtime/worker-keepalive.mjs

@@ -0,0 +1,108 @@
+// The worker's one keepalive timer. Each beat posts the heartbeat
+// (heartbeat.mjs) and refreshes the websocket readiness
+// (worker-websocket-link.mjs, built with readyRefreshMs: 0); before, each ran
+// its own 10 s timer.
+//
+// Cadence: every 10 s while the worker has work (a row it owns, a delivery in
+// flight, a hold, a background task, a running turn), and every 30 s while it
+// is idle, but only on a relay that advertised `idle-keepalive` in its
+// server.hello. An older relay expects a beat every 10 s (its liveness, CLI
+// and stranded-session windows), and a worker whose socket is down knows no
+// relay at all, so both get 10 s. Every server.hello and every delivery
+// (nudge) keeps the busy cadence for the next 30 s and cuts an idle wait
+// down to 10 s: the first beat naming a new turn's row is never an idle wait
+// away, and a delivery lost on the wire or a relay that just came up is
+// noticed as fast as before.
+
+export const IDLE_KEEPALIVE_MS = 30_000;
+export const BUSY_KEEPALIVE_MS = 10_000;
+export const IDLE_KEEPALIVE_CAPABILITY = "idle-keepalive";
+export const BUSY_HOLD_MS = 30_000;
+
+export function createWorkerKeepalive({
+  heartbeat,
+  link,
+  idleMs = IDLE_KEEPALIVE_MS,
+  busyMs = BUSY_KEEPALIVE_MS,
+  busyHoldMs = BUSY_HOLD_MS,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+  now = () => Date.now(),
+} = {}) {
+  let timer = null;
+  let dueAtMs = 0;
+  let running = false;
+  let busyUntilMs = 0;
+
+  function busy() {
+    if (now() < busyUntilMs) return true;
+    try {
+      if (heartbeat?.hasWork?.() === true) return true;
+      if (link?.isBusy?.() === true) return true;
+      return false;
+    } catch {
+      return true;
+    }
+  }
+
+  function relayAllowsIdleCadence() {
+    try {
+      return link?.serverSupports?.(IDLE_KEEPALIVE_CAPABILITY) === true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** The wait before the next beat, decided after each beat. */
+  function nextDelayMs() {
+    if (busy() || !relayAllowsIdleCadence()) return busyMs;
+    return idleMs;
+  }
+
+  function schedule(delayMs) {
+    if (timer) clearTimeoutImpl(timer);
+    dueAtMs = now() + delayMs;
+    timer = setTimeoutImpl(beat, delayMs);
+    timer?.unref?.();
+  }
+
+  function beat() {
+    timer = null;
+    if (!running) return;
+    void heartbeat?.pulseHeartbeat?.();
+    try { link?.refreshReadiness?.("readiness-refresh"); } catch {}
+    schedule(nextDelayMs());
+  }
+
+  function start() {
+    if (running) return;
+    running = true;
+    // The first heartbeat goes out at once, as the heartbeat's own start did;
+    // the socket is not open yet, so its refresh waits for the next beat.
+    void heartbeat?.pulseHeartbeat?.();
+    schedule(nextDelayMs());
+  }
+
+  /**
+   * The relay said hello or handed over work: the busy cadence holds for a
+   * while, and a beat further away than it comes sooner.
+   */
+  function nudge() {
+    if (!running) return;
+    busyUntilMs = Math.max(busyUntilMs, now() + busyHoldMs);
+    if (timer && dueAtMs - now() > busyMs) schedule(busyMs);
+  }
+
+  function stop() {
+    running = false;
+    if (timer) clearTimeoutImpl(timer);
+    timer = null;
+  }
+
+  return {
+    start,
+    stop,
+    nudge,
+    status: () => ({ running, dueAtMs: timer ? dueAtMs : null }),
+  };
+}