@oar-sh/oar 0.9.20 → 0.9.22

package/server/services/worker-replacement.mjs

@@ -0,0 +1,197 @@
+/**
+ * Replacing a session's worker: the stop and the launch that the Claude
+ * billing swap (claude-billing-swap-service.mjs) and the worker recycle
+ * (worker-recycle-service.mjs) share, and the predicate both use to tell
+ * whether a worker may be replaced now.
+ *
+ * The stop is the kill route's: nothing may start the session while it is
+ * stopped, every process of the session must be gone before it counts as
+ * stopped, and only then is the registry entry dropped. The launch never
+ * reuses a live process, so two CLIs never share a session's transcript.
+ * The fence keeps the deliveries away from the process being replaced for the
+ * whole of it (createWorkerReplacementFence).
+ */
+
+import { stopSessionWorkerProcesses as defaultStopSessionWorkerProcesses } from './session-worker-stop-service.mjs';
+
+/**
+ * What keeps a worker from being replaced now: null when nothing does, else
+ * 'turn', 'question', 'compaction' or 'background'. From the steering
+ * snapshot its heartbeat sends; a worker too old to say `releasable` is read
+ * from the rest of it.
+ */
+export function workerReleaseHold(worker) {
+  if (!worker) return null;
+  const steering = worker.steering || null;
+  if (steering && typeof steering.releasable === 'boolean') {
+    return steering.releasable ? null : (steering.releaseHold || 'turn');
+  }
+  if (steering) {
+    if (steering.holdReason === 'question') return 'question';
+    if (steering.holdReason === 'compaction') return 'compaction';
+    if (steering.turnActive) return 'turn';
+    if (steering.autoCompactWindow?.backgroundWork) return 'background';
+    return null;
+  }
+  return String(worker.status || '') === 'processing' ? 'turn' : null;
+}
+
+function toFencePid(value) {
+  const pid = Number(value);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+/**
+ * The replacement fence: while a worker process is being replaced, no work
+ * is handed to it.
+ *
+ * The killed marker the stop sets does not do this. It lapses after the
+ * supervisor's short kill grace (a stop that verifies every process gone can
+ * take longer), and any path that relaunches a session lifts it at once
+ * (`clearRestartSchedule({ resetKilledMarker: true })`, the delivery's own
+ * fallback restart among them), after which a delivery would start a turn on
+ * the very process being killed. The fence is its own structure, so nothing
+ * that resets the supervisor's lifecycle state touches it.
+ *
+ * Keyed by session and the pid being replaced: the new worker has another
+ * pid and is never fenced, so it takes the work that waited meanwhile. A
+ * request that names no pid cannot be told from the old process and is
+ * refused while the session's fence is up.
+ *
+ * - `hold(sid, pid)`: raise the fence for that process of the session.
+ * - `isHeld(sid, pid)`: true while the fence is up for that pid (or for any
+ *   pid of the session, when `pid` is unknown).
+ * - `release(sid, pid?)`: lower it; with a pid, only if that is the fenced
+ *   one, so a late release from an older replacement never lifts a newer one.
+ */
+export function createWorkerReplacementFence() {
+  const held = new Map();
+
+  function key(sid) {
+    return String(sid || '').trim();
+  }
+
+  function hold(sid, pid) {
+    const sessionId = key(sid);
+    if (!sessionId) return false;
+    held.set(sessionId, toFencePid(pid));
+    return true;
+  }
+
+  function isHeld(sid, pid = null) {
+    const sessionId = key(sid);
+    if (!sessionId || !held.has(sessionId)) return false;
+    const fencedPid = held.get(sessionId);
+    const askingPid = toFencePid(pid);
+    // An unknown pid on either side: the old process cannot be ruled out.
+    if (fencedPid === null || askingPid === null) return true;
+    return fencedPid === askingPid;
+  }
+
+  function release(sid, pid = undefined) {
+    const sessionId = key(sid);
+    if (!sessionId || !held.has(sessionId)) return false;
+    if (pid !== undefined && toFencePid(pid) !== held.get(sessionId)) return false;
+    held.delete(sessionId);
+    return true;
+  }
+
+  function list() {
+    return Array.from(held, ([sdkSessionId, pid]) => ({ sdkSessionId, pid }));
+  }
+
+  return { hold, isHeld, release, list };
+}
+
+export function createWorkerReplacement({
+  // The session worker registry: getWorker(sid), removeWorker(sid).
+  registry,
+  // The session worker supervisor: markKilled, cancelPendingStart,
+  // clearRestartSchedule, resetHealth, ensureWorker.
+  supervisor,
+  // Handed to stopSessionWorkerProcesses to find every process of a session.
+  processInspector = null,
+  // session-worker-stop-service.mjs by default; tests inject a fake so they
+  // need no processes: async ({ sdkSessionId, worker, processInspector,
+  // isPidAliveImpl, killTmuxSessionImpl }) → { ok, error?, remainingPids? }.
+  stopSessionWorkerProcesses = defaultStopSessionWorkerProcesses,
+  isProcessAlive = undefined,
+  killTmuxSession = undefined,
+  logger = console,
+  // The caller's tag for its warnings ('BILLING SWAP', 'WORKER RECYCLE'), and
+  // a function for the runtime's own log prefix, or a fixed string.
+  logPrefix = '',
+  // The replacement fence the caller raises before the stop and lowers once
+  // the launch is done (createWorkerReplacementFence). Passed in so the
+  // runtime's replacements and its delivery paths share one; this module
+  // only hands it back.
+  fence = createWorkerReplacementFence(),
+} = {}) {
+  if (typeof stopSessionWorkerProcesses !== 'function') {
+    throw new Error('createWorkerReplacement requires stopSessionWorkerProcesses');
+  }
+
+  function prefix() {
+    try {
+      return typeof logPrefix === 'function' ? String(logPrefix() || '') : String(logPrefix || '');
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Stop every process of the session. `{ ok: true }` once they are all gone
+   * and the registry and the supervisor's health state are cleared; else
+   * `{ ok: false, error, remainingPids }`, and the caller retries with a
+   * backoff.
+   *
+   * `keepKilled: true` is for a session that must stay stopped (an archived
+   * conversation): the killed marker set here is left in place on either
+   * outcome, as the archive route leaves it, so nothing relaunches the
+   * session meanwhile.
+   */
+  async function stopWorker(sid, { keepKilled = false } = {}) {
+    const worker = registry?.getWorker?.(sid) || null;
+    // Nothing may start the session while it is being stopped: a launch then
+    // would adopt the old process, kind and build and all.
+    supervisor?.markKilled?.(sid);
+    // A stop that fails backs off (the caller retries it). Unless the session
+    // is to stay stopped, the killed marker goes with it, so the session's
+    // worker, alive or relaunched, keeps asking for work meanwhile.
+    const backOff = (error, remainingPids = []) => {
+      if (!keepKilled) supervisor?.clearRestartSchedule?.(sid, { resetKilledMarker: true });
+      const remaining = remainingPids.length ? ` remaining=${remainingPids.join(',')}` : '';
+      const marker = keepKilled ? 'kill marker kept' : 'kill marker cleared';
+      try {
+        logger.warn?.(`${prefix()}STOP FAILED session=${String(sid).slice(0, 8)} ${error}${remaining} — ${marker}, retrying with a backoff`);
+      } catch {}
+      return { ok: false, error, remainingPids };
+    };
+    let stopped = null;
+    try {
+      await supervisor?.cancelPendingStart?.(sid, { wait: true });
+      stopped = await stopSessionWorkerProcesses({
+        sdkSessionId: sid,
+        worker,
+        processInspector,
+        isPidAliveImpl: isProcessAlive,
+        killTmuxSessionImpl: killTmuxSession,
+      });
+    } catch (error) {
+      return backOff(String(error?.message || error || 'worker-stop-failed'));
+    }
+    if (!stopped?.ok) return backOff(stopped?.error || 'worker-survived-stop', stopped?.remainingPids || []);
+    registry?.removeWorker?.(sid);
+    supervisor?.resetHealth?.(sid, { clearFailureCount: false });
+    return { ok: true };
+  }
+
+  /** Launch the session's worker, never reusing a live process: `{ ok, error }`. */
+  async function launchWorker(sid) {
+    supervisor?.clearRestartSchedule?.(sid, { resetKilledMarker: true });
+    const launched = await supervisor?.ensureWorker?.(sid, { allowProcessReuse: false });
+    return { ok: launched?.ok === true, error: launched?.error || null };
+  }
+
+  return { stopWorker, launchWorker, fence };
+}

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/build-id.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The build id names the code a process runs, so the relay can tell a session
+// worker that started on older code from one that runs what the relay runs.
+//
+// It is `${version}+${commit.slice(0, 12)}` when both are known, the version
+// alone when there is no commit, and null when there is no version either. The
+// commit is part of it because on a git checkout a deploy is a new
+// commit at the same version; on an npm install without a `gitHead` stamp the
+// version alone decides.
+//
+// The relay and every worker compute it once at process start and never read
+// it again, so a tree that moved on under a running process still describes
+// the code that process started with.
+//
+// This module lives in shared/ because both the relay and the workers import
+// it; it depends on nothing beyond node:fs and node:path for the same reason.
+
+const COMMIT_PATTERN = /^[0-9a-f]{40}$/i;
+const COMMIT_ID_LENGTH = 12;
+
+// The relay stores the build id a worker states, so what it accepts is bounded
+// in length and limited to the characters a version and a commit use.
+const BUILD_ID_MAX_LENGTH = 80;
+const BUILD_ID_PATTERN = /^[A-Za-z0-9+._-]+$/;
+
+function readFileText(fsImpl, filePath) {
+  try {
+    return String(fsImpl.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readPackageManifest(packageRoot, { fsImpl, pathImpl }) {
+  if (!packageRoot) return null;
+  try {
+    const manifest = JSON.parse(readFileText(fsImpl, pathImpl.join(packageRoot, 'package.json')) || '');
+    return manifest && typeof manifest === 'object' ? manifest : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The commit a git checkout has checked out, read from its .git files rather
+ * than from a `git` process: HEAD, then the loose ref, then packed-refs. A
+ * linked worktree's .git is a file naming its git dir, whose refs live in the
+ * common dir. Anything unexpected reads as null. `pathImpl` is the host's path
+ * module; tests pass path.posix and path.win32.
+ */
+export function readGitCommit(root, { fsImpl = fs, pathImpl = path } = {}) {
+  if (!root) return null;
+  const dotGit = pathImpl.join(root, '.git');
+  let gitDir = dotGit;
+  const pointer = readFileText(fsImpl, dotGit);
+  if (pointer !== null) {
+    const match = pointer.match(/^gitdir:\s*(.+)$/m);
+    if (!match) return null;
+    gitDir = pathImpl.resolve(root, match[1].trim());
+  }
+  const head = readFileText(fsImpl, pathImpl.join(gitDir, 'HEAD'));
+  if (head === null) return null;
+  const headText = head.trim();
+  if (COMMIT_PATTERN.test(headText)) return headText.toLowerCase();
+  const refMatch = headText.match(/^ref:\s*(\S+)$/);
+  if (!refMatch) return null;
+  const ref = refMatch[1];
+  const commonDirText = readFileText(fsImpl, pathImpl.join(gitDir, 'commondir'));
+  const commonDir = commonDirText ? pathImpl.resolve(gitDir, commonDirText.trim()) : gitDir;
+  for (const dir of new Set([gitDir, commonDir])) {
+    const loose = readFileText(fsImpl, pathImpl.join(dir, ...ref.split('/')));
+    if (loose && COMMIT_PATTERN.test(loose.trim())) return loose.trim().toLowerCase();
+  }
+  const packed = readFileText(fsImpl, pathImpl.join(commonDir, 'packed-refs')) || '';
+  for (const line of packed.split(/\r?\n/)) {
+    const [hash, name] = line.trim().split(/\s+/);
+    if (name === ref && COMMIT_PATTERN.test(hash || '')) return hash.toLowerCase();
+  }
+  return null;
+}
+
+/** The commit this build came from: the checkout's HEAD, else a `gitHead` stamp in package.json. */
+export function resolveBuildCommit(packageRoot, { fsImpl = fs, pathImpl = path } = {}) {
+  const fromGit = readGitCommit(packageRoot, { fsImpl, pathImpl });
+  if (fromGit) return fromGit;
+  const stamp = String(readPackageManifest(packageRoot, { fsImpl, pathImpl })?.gitHead || '').trim();
+  return COMMIT_PATTERN.test(stamp) ? stamp.toLowerCase() : null;
+}
+
+/** The package.json `version`, or null when the manifest cannot be read or names none. */
+export function readPackageVersion(packageRoot, { fsImpl = fs, pathImpl = path } = {}) {
+  const version = readPackageManifest(packageRoot, { fsImpl, pathImpl })?.version;
+  return typeof version === 'string' && version.trim() ? version.trim() : null;
+}
+
+/**
+ * The build id of the tree at `packageRoot`: `{ version, commit, id }`. Call it
+ * once at process start and keep the result; see the header for why.
+ */
+export function resolveBuildId(packageRoot, { fsImpl = fs, pathImpl = path } = {}) {
+  const version = readPackageVersion(packageRoot, { fsImpl, pathImpl });
+  const commit = resolveBuildCommit(packageRoot, { fsImpl, pathImpl });
+  let id = null;
+  if (version && commit) id = `${version}+${commit.slice(0, COMMIT_ID_LENGTH)}`;
+  else if (version) id = version;
+  return { version, commit, id };
+}
+
+/**
+ * True only when both ids are known and differ. An unknown id on either side
+ * is not evidence of a change, so it never reads as one.
+ */
+export function buildIdsDiffer(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const left = a.trim();
+  const right = b.trim();
+  return !!left && !!right && left !== right;
+}
+
+/** A stated build id, trimmed, or null when it is too long or carries other characters. */
+export function normalizeBuildId(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!text || text.length > BUILD_ID_MAX_LENGTH || !BUILD_ID_PATTERN.test(text)) return null;
+  return text;
+}

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,10 +33,18 @@ 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.
   workerKind = null,
+  // Optional: the build id of the code this worker started on
+  // (shared/build-id.mjs). A worker whose websocket is down still beats, so
+  // the relay learns the build here as well as from the hello.
+  buildId = null,
   // requestPulse's window: one turn transition can flip the steering
   // snapshot several times in quick succession, and each flip only needs to
   // reach the relay once.
@@ -71,6 +79,7 @@ export function createHeartbeatController({
         ...(settleFailed.length ? { settleFailed } : {}),
         ...(Array.isArray(backgroundTaskIds) ? { backgroundTasks: backgroundTaskDigest(backgroundTaskIds) } : {}),
         ...(workerKind ? { workerKind: String(workerKind) } : {}),
+        ...(typeof buildId === "string" && buildId.trim() ? { buildId: buildId.trim() } : {}),
       };
       const response = await api("POST", "/api/heartbeat", body);
       // Failed by the relay, or skipped because this worker has no claim on
@@ -94,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
@@ -130,6 +160,7 @@ export function createHeartbeatController({
   }
 
   return {
+    hasWork,
     pulseHeartbeat,
     requestPulse,
     startHeartbeat,

package/shared/worker-runtime/simple-steering-state.mjs

@@ -0,0 +1,38 @@
+/**
+ * The heartbeat steering snapshot of a worker that runs one delivered message
+ * at a time and never steers into a running turn: the Cursor, Grok and Claude
+ * cloud workers. They send it for the release fields, which tell the relay
+ * whether it may stop this worker and launch a fresh one now (its recycle
+ * after a deploy), the same fields the Claude and Copilot SDK workers send.
+ *
+ * `supported: false` keeps the composer as it was for these kinds: it offers
+ * mid-turn steering only to a worker that says `supported: true`, and reads
+ * neither the hold nor the cancellable ids of one that does not.
+ *
+ * - `activeAttempt`: the runner's `getActiveQueueAttempt()` (`{ id, attemptId }`
+ *   or null), the row the running turn owns.
+ * - `turnActive`: the runner's own word that a turn runs (`isTurnActive()`),
+ *   for a turn whose row has no id to show.
+ * - `backgroundTaskCount`: live background work that ends with the worker
+ *   (Grok's terminals).
+ *
+ * A turn holds the release ('turn'), then live background work ('background').
+ */
+export function buildSimpleSteeringState({ activeAttempt = null, turnActive = false, backgroundTaskCount = 0 } = {}) {
+  const messageId = String(activeAttempt?.id || '').trim() || null;
+  const turn = turnActive === true || Boolean(messageId);
+  const tasks = Number(backgroundTaskCount);
+  const liveTasks = Number.isInteger(tasks) && tasks > 0 ? tasks : 0;
+  const releaseHold = turn ? 'turn' : (liveTasks > 0 ? 'background' : null);
+  return {
+    turnActive: turn,
+    canSteer: false,
+    holdReason: null,
+    messageId,
+    supported: false,
+    cancellableIds: [],
+    releasable: !releaseHold,
+    releaseHold,
+    backgroundTaskCount: liveTasks,
+  };
+}

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 }),
+  };
+}