@oar-sh/oar 0.9.21 → 0.9.23

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/server/services/update-install-service.mjs

@@ -11,6 +11,7 @@ import {
   stripTerminalEscapes,
   tailOf,
 } from './cli-process-runner.mjs';
+import { NATIVE_BUILD_COMMAND, buildBetterSqlite3, needsSourceBuild } from './native-addon-build-service.mjs';
 import { NPM_ALLOW_SCRIPTS_ARG, resolveNpmInvocation } from './oar-cli-helpers.mjs';
 import { compareSemverIsh, parseSemverIsh } from '../../shared/update-semver.mjs';
 
@@ -107,6 +108,8 @@ export function createUpdateInstallService({
   spawnImpl = defaultSpawn,
   env = process.env,
   platform = process.platform,
+  arch = process.arch,
+  buildNativeAddons = buildBetterSqlite3,
   setTimeoutImpl = setTimeout,
   clearTimeoutImpl = clearTimeout,
   nowImpl = Date.now,
@@ -242,15 +245,43 @@ export function createUpdateInstallService({
     );
     activeChild = null;
     flushLogNow();
-    finishedAt = new Date(nowImpl()).toISOString();
 
     if (!result.ok) {
+      finishedAt = new Date(nowImpl()).toISOString();
       state = UPDATE_INSTALL_STATES.ERROR;
       lastError = result.error || `npm exited with code ${result.code}`;
       broadcast();
       return { ok: false, statusCode: 500, error: lastError };
     }
 
+    // No prebuilt SQLite binding here: build it before the restart, which
+    // would start on none (native-addon-build-service.mjs). A failed build
+    // keeps this relay running on the binding it has loaded.
+    if (needsSourceBuild({ platform, arch })) {
+      const toLog = (line) => appendLog(`${line}\n`);
+      const build = await buildNativeAddons({
+        packageRoot,
+        platform,
+        arch,
+        execPath,
+        env: npm.env,
+        spawnImpl,
+        onOutput: (text) => appendLog(text),
+        onChild: (child) => { activeChild = child; },
+        logger: { log: toLog, error: toLog },
+      });
+      activeChild = null;
+      flushLogNow();
+      if (!build.ok) {
+        finishedAt = new Date(nowImpl()).toISOString();
+        state = UPDATE_INSTALL_STATES.ERROR;
+        lastError = `${UPDATE_PACKAGE_NAME}@${target} is installed, but its SQLite binding did not build (${build.error}). Run ${NATIVE_BUILD_COMMAND}, then restart the relay.`;
+        broadcast();
+        return { ok: false, statusCode: 500, error: lastError };
+      }
+    }
+    finishedAt = new Date(nowImpl()).toISOString();
+
     // Persist the attempt BEFORE the restart request: the next boot compares
     // the running version against it and turns "nothing changed" into a
     // visible failure carrying this log tail.

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

package/shared/worker-runtime/worker-websocket-link.mjs

@@ -63,9 +63,13 @@ export function createWorkerWebSocketLink({
   getDeliveryHeld = null,
   // Called with the hello's reason once per connection, on the relay's first
   // server.hello: from then on the relay (possibly a restarted one that knows
-  // nothing of this worker) has the socket. Later hellos only ack the
-  // worker.hello every idle readiness refresh re-sends, and are not reported.
+  // nothing of this worker) has the socket. Later hellos only ack a later
+  // worker.hello, and are not reported.
   onServerHello = () => {},
+  // Called with "server-hello" on every server.hello and with "deliver" on
+  // every queue.deliver: the keepalive keeps its busy cadence for a while
+  // after either (worker-keepalive.mjs).
+  onRelayFrame = () => {},
   getSessionId = () => null,
   getPid = () => null,
   // The kind of worker this is ("claude", "claude-api", ...), stated in
@@ -88,8 +92,12 @@ export function createWorkerWebSocketLink({
   // Failed attempts after the first few are logged at most once per this
   // interval, with a count of the ones in between.
   failureLogIntervalMs = 60_000,
+  // The link's own readiness refresh; 0 leaves it to the caller, which then
+  // calls refreshReadiness itself (worker-keepalive.mjs does, on its beat).
   readyRefreshMs = 10_000,
-  staleConnectionMs = 30_000,
+  // Three missed idle beats (30 s each) without any word from the relay: the
+  // connection is given up and made again.
+  staleConnectionMs = 90_000,
   WebSocketImpl = globalThis.WebSocket,
   setTimeoutImpl = setTimeout,
   clearTimeoutImpl = clearTimeout,
@@ -309,19 +317,17 @@ export function createWorkerWebSocketLink({
       notifyUnready(reason);
       return true;
     }
-    if (deliveriesInFlight.size) {
-      // notifyReady gates itself: it only goes through mid-delivery when the
-      // worker is steering-ready. Hello stays an idle-only affair.
-      void notifyReady(reason);
-      return true;
-    }
-    notifyHello(reason);
+    // notifyReady gates itself: mid-delivery it only goes through when the
+    // worker is steering-ready. No hello: the socket's identity, kind and
+    // build were bound by the hello at open, and a ready carries them again;
+    // a hello would only draw a second server.hello and a second ready.
     void notifyReady(reason);
     return true;
   }
 
   function startReadyRefreshTimer() {
     clearReadyRefreshTimer();
+    if (Number(readyRefreshMs) === 0) return;
     const intervalMs = Math.max(1000, Number(readyRefreshMs) || 10_000);
     readyRefreshTimer = setIntervalImpl(() => {
       refreshReadiness("readiness-refresh");
@@ -449,11 +455,13 @@ export function createWorkerWebSocketLink({
         return;
       }
       if (payload?.type === "queue.deliver") {
+        try { onRelayFrame("deliver"); } catch {}
         void deliverPending(payload.pending || null, String(payload.reason || "queue-deliver"))
           .finally(() => notifyReady("delivery-complete"));
         return;
       }
       if (payload?.type === "server.hello") {
+        try { onRelayFrame("server-hello"); } catch {}
         serverCapabilities = new Set(Array.isArray(payload.capabilities) ? payload.capabilities.map(String) : []);
         relayBuildId = normalizeText(payload.buildId);
         // Only a line in the log: the relay decides when to replace this
@@ -565,6 +573,9 @@ export function createWorkerWebSocketLink({
   return {
     notifyReady,
     notifyUnready,
+    refreshReadiness,
+    // A delivery in flight or a hold: the keepalive beats at its busy cadence.
+    isBusy: () => deliveriesInFlight.size > 0 || deliveryHeld(),
     serverSupports: (capability) => serverCapabilities.has(String(capability || "")),
     start,
     stop,