@oar-sh/oar 0.9.2 → 0.9.3

package/shared/steer-note.mjs

@@ -0,0 +1,66 @@
+// The hidden note a steered message carries to the model.
+//
+// A message the user sends while a turn is running is pushed into that turn
+// (steering). When it lands before the model has produced anything, the model
+// sees two user messages at once — and in the 2026-09-25 burn-in gpt-5.4-mini
+// answered only the newest and silently dropped the original request (the
+// runtime's own event log confirmed nothing was lost by the relay). The note
+// tells the model the new message is an addition, not a replacement, unless
+// the user says otherwise. Only the model sees it: the relay stores and shows
+// the user's own text.
+//
+// Shared by the Claude and Copilot SDK workers (maintainer decision, 2026-09-25: both).
+
+// Worded to stay true whether the runtime folds the message into the running
+// turn or runs it as a turn of its own after that one finished: "if not
+// finished yet" never asks the model to redo work it already completed. The
+// opening words are the stable handle the prompt sanitizers match on
+// (services/relay-prompt-sanitizer.mjs and its browser copy).
+export const STEERED_MESSAGE_NOTE = '[Sent while you were still working on my previous message. '
+  + 'If that request is not finished yet, finish it too; do not drop it unless this message says so.]';
+
+// The note LEADS the user's text, inside the same text block, and that
+// position is load-bearing beyond the replay's shape. The Claude CLI runs a
+// prompt as a slash command when the string, or its LAST text block trimmed,
+// starts with "/" — and one dequeued mid-turn is deferred to a turn of its
+// own, whose output the relay would misattribute. The relay itself runs only
+// /compact and /preview as commands (any other "/x" is confirmed as text
+// first), so a steered "/cmd …" must reach the model as plain text folded
+// into the running turn, which the leading note guarantees. Appended, the
+// prompt would still start with "/" and run as a command whose arguments
+// include the note; as a separate leading block, the last block would still
+// start with "/". A "/x" that is not steered (or is pushed into a continuation,
+// which gets no note) is kept text by the Claude worker's slash-command guard
+// instead (shared/slash-command-guard.mjs).
+
+/** Prefix a plain-text prompt with the steer note. */
+export function withSteerNote(text) {
+  const body = String(text ?? '');
+  return body.trim() ? `${STEERED_MESSAGE_NOTE}\n\n${body}` : STEERED_MESSAGE_NOTE;
+}
+
+/**
+ * Prefix a content-block array (Claude's user message content) with the note:
+ * into the first text block when there is one, so the block structure — and
+ * with it the replay the CLI echoes back — keeps its shape; otherwise as a new
+ * leading text block. Returns a new array; the input is not mutated.
+ */
+export function withSteerNoteContent(content) {
+  if (typeof content === 'string') return withSteerNote(content);
+  if (!Array.isArray(content)) return content;
+  const index = content.findIndex((block) => block?.type === 'text');
+  if (index < 0) return [{ type: 'text', text: STEERED_MESSAGE_NOTE }, ...content];
+  return content.map((block, i) => (i === index ? { ...block, text: withSteerNote(block.text) } : block));
+}
+
+/**
+ * The user's own text from a prompt that may carry the steer note — what a
+ * worker compares a replayed message against. Note-agnostic matching: the
+ * replay the CLI echoes back carries the note, the relay row does not.
+ */
+export function stripSteerNote(text) {
+  const value = String(text ?? '');
+  if (value === STEERED_MESSAGE_NOTE) return '';
+  const prefix = `${STEERED_MESSAGE_NOTE}\n\n`;
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}

package/shared/steer-settle-failure.mjs

@@ -0,0 +1,89 @@
+// The terminal failure for a message whose prompt the agent already consumed
+// but whose outcome could not be recorded. At-most-once: such a row is never
+// requeued (a re-delivery would run the prompt a second time), so it fails for
+// good with wording that tells the user where the answer went. Shared by the
+// session workers (their own settle paths) and the relay (recovery paths that
+// meet a row marked consumed).
+//
+// Provider-neutral: the wording names `agentLabel` ("the agent" unless the
+// caller knows better — the Claude worker passes 'Claude').
+
+export const STEER_SETTLE_FAILED_CODE = 'steer-settle-failed';
+export const STEER_SETTLE_FAILED_STABLE_CODE = `relay.${STEER_SETTLE_FAILED_CODE}`;
+export const DEFAULT_STEER_AGENT_LABEL = 'the agent';
+
+function normalizeAgentLabel(value) {
+  const text = String(value || '').trim();
+  return text || DEFAULT_STEER_AGENT_LABEL;
+}
+
+// "the agent" → "The agent" at the start of a sentence; a proper name is
+// left as it is.
+function sentenceCase(label) {
+  return label.charAt(0).toUpperCase() + label.slice(1);
+}
+
+const VARIANTS = Object.freeze({
+  // Folded into a turn whose reply answered it (or the path is unknown — the
+  // relay's recovery paths cannot tell which).
+  folded: (label) => ({
+    message: `This message was already sent to ${label} — check the reply above.`,
+    guidance: 'Resend it only if it went unanswered.',
+  }),
+  // Handed off mid-reply: its own partial reply stands, and the rest of the
+  // answer continued on the next message.
+  handoff: (label) => ({
+    message: `${sentenceCase(label)} started answering this message, then carried on with your next one — check both replies.`,
+    guidance: 'Resend it only if something went unanswered.',
+  }),
+  // Steered into a turn the user stopped.
+  stopped: (label) => ({
+    message: `This message was sent to ${label} just before you stopped the turn, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+  // Pulled back out of the runtime's queue by the user (un-steer) — the
+  // prompt never ran — but the relay could not be told in time.
+  cancelled: (label) => ({
+    message: `This message was cancelled before ${label} started on it, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+});
+
+/**
+ * The name a provider's runtime goes by in the settle wording, for callers
+ * that only know the conversation's provider type (the relay's recovery
+ * paths). Workers that know exactly which runtime took the prompt pass the
+ * label themselves.
+ */
+export function steerAgentLabelForProvider(providerType) {
+  switch (String(providerType || '').trim().toLowerCase()) {
+    case 'claude': return 'Claude';
+    case 'github':
+    case 'openai': return 'Copilot';
+    case 'cursor': return 'Cursor';
+    case 'grok': return 'Grok';
+    default: return DEFAULT_STEER_AGENT_LABEL;
+  }
+}
+
+function wordingFor(variant, agentLabel) {
+  const build = VARIANTS[variant] || VARIANTS.folded;
+  return build(normalizeAgentLabel(agentLabel));
+}
+
+export function steerSettleFailureText(variant = 'folded', agentLabel = DEFAULT_STEER_AGENT_LABEL) {
+  return wordingFor(variant, agentLabel).message;
+}
+
+export function buildSteerSettleFailure(message, { variant = 'folded', agentLabel = DEFAULT_STEER_AGENT_LABEL } = {}) {
+  const wording = wordingFor(variant, agentLabel);
+  return {
+    kind: STEER_SETTLE_FAILED_CODE,
+    code: STEER_SETTLE_FAILED_CODE,
+    stableCode: STEER_SETTLE_FAILED_STABLE_CODE,
+    message: wording.message,
+    guidance: wording.guidance,
+    failedAt: new Date().toISOString(),
+    queueMessageId: String(message?.id || '') || null,
+  };
+}

package/shared/steer-settle-markers.mjs

@@ -0,0 +1,18 @@
+// The settle stubs of steered messages the Claude CLI consumed without opening
+// a turn of their own. Each is stamped with its own message kind, which is
+// what the client renders from; the texts are shared so the relay's migration
+// can recognise stubs saved before the kind existed.
+
+/**
+ * A steer folded into the running turn and answered by that turn's reply.
+ * Stamped kind='folded' (before 0.9.3: kind='absorbed', which the client read
+ * as "the reply continues through the next message" and mis-merged the next
+ * ordinary message on reload).
+ */
+export const STEER_FOLDED_TEXT = '_(Handled together with the previous reply — this message was steered into that turn.)_';
+
+/**
+ * A steer pushed into a turn the user then stopped: never answered. Stamped
+ * kind='stopped' — the stable handle the client keys its Resend on.
+ */
+export const STEER_STOPPED_TEXT = '_(Stopped with the turn — not answered.)_';

package/shared/worker-crash-guard.mjs

@@ -11,6 +11,45 @@
  * The requeue is strictly bounded: a crash handler that hangs is worse than
  * no handler at all.
  */
+/**
+ * Post a bounded, fenced requeue for each owed row. Entries are plain ids or
+ * { id, attemptId, terminalError } objects: the attempt id fences the requeue
+ * (a row that has moved on to another attempt must not be yanked back by a
+ * dying predecessor), and a `terminalError` makes the requeue route fail the
+ * row outright — for a row whose prompt was already consumed, which must not
+ * be requeued and run a second time. Never waits longer than `timeoutMs`.
+ */
+export async function requeueOwedRows({ api, entries = [], timeoutMs = 2_000 } = {}) {
+  const seen = new Set();
+  const owed = (Array.isArray(entries) ? entries : [])
+    .map((entry) => (entry && typeof entry === 'object'
+      ? {
+        id: String(entry.id || '').trim(),
+        attemptId: String(entry.attemptId || '').trim() || null,
+        terminalError: entry.terminalError && typeof entry.terminalError === 'object' ? entry.terminalError : null,
+      }
+      : { id: String(entry || '').trim(), attemptId: null, terminalError: null }))
+    .filter((entry) => {
+      if (!entry.id || seen.has(entry.id)) return false;
+      seen.add(entry.id);
+      return true;
+    });
+  if (!owed.length || typeof api !== 'function') return;
+  let timer = null;
+  await Promise.race([
+    Promise.allSettled(owed.map((entry) => api('POST', '/api/requeue', {
+      messageId: entry.id,
+      ...(entry.attemptId ? { attemptId: entry.attemptId } : {}),
+      ...(entry.terminalError ? { terminalError: entry.terminalError } : {}),
+    }))),
+    new Promise((resolve) => {
+      timer = setTimeout(resolve, Math.max(0, Number(timeoutMs) || 0));
+      timer.unref?.();
+    }),
+  ]);
+  clearTimeout(timer);
+}
+
 export function installWorkerCrashGuard({
   api,
   workerName = 'session-worker',
@@ -28,31 +67,7 @@ export function installWorkerCrashGuard({
     logError(`${workerName} ${kind}:`, error?.stack || error?.message || error);
     (async () => {
       try {
-        // Entries are plain ids or { id, attemptId } objects. The attempt id,
-        // when known, fences the requeue: a row that has already moved on to
-        // another attempt must not be yanked back by a dying predecessor.
-        const seen = new Set();
-        const entries = (getActiveQueueMessageIds() || [])
-          .map((entry) => (entry && typeof entry === 'object'
-            ? { id: String(entry.id || '').trim(), attemptId: String(entry.attemptId || '').trim() || null }
-            : { id: String(entry || '').trim(), attemptId: null }))
-          .filter((entry) => {
-            if (!entry.id || seen.has(entry.id)) return false;
-            seen.add(entry.id);
-            return true;
-          });
-        if (entries.length && typeof api === 'function') {
-          await Promise.race([
-            Promise.allSettled(entries.map((entry) => api('POST', '/api/requeue', {
-              messageId: entry.id,
-              ...(entry.attemptId ? { attemptId: entry.attemptId } : {}),
-            }))),
-            new Promise((resolve) => {
-              const timer = setTimeout(resolve, Math.max(0, Number(requeueTimeoutMs) || 0));
-              timer.unref?.();
-            }),
-          ]);
-        }
+        await requeueOwedRows({ api, entries: getActiveQueueMessageIds() || [], timeoutMs: requeueTimeoutMs });
       } catch {}
       try { onBeforeExit(); } catch {}
       exit(1);

package/shared/worker-runtime/heartbeat.mjs

@@ -10,7 +10,24 @@ export function createHeartbeatController({
   // queued behind it, and a background continuation at once). Each reported
   // id gets its owner lease refreshed; unreported owned rows are recovered.
   getActiveQueueMessageIds,
+  // Optional: the worker's steering snapshot ({turnActive, canSteer,
+  // holdReason}) for the composer. Workers that do not steer leave it unset
+  // and the heartbeat body is unchanged.
+  getSteeringState,
+  // Optional: rows the worker gave up settling ([{id, attemptId,
+  // terminalError}]); the relay fails them and names them back in
+  // `settleFailedHandled`, which `onSettleFailedHandled` receives.
+  getSettleFailed,
+  onSettleFailedHandled = () => {},
+  // 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.
+  pulseCoalesceMs = 300,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
 }) {
+  let requestedPulseTimer = null;
+
   async function pulseHeartbeat() {
     if (!getSessionReady()) return false;
     try {
@@ -20,17 +37,49 @@ export function createHeartbeatController({
       const activeQueueMessageIds = typeof getActiveQueueMessageIds === "function"
         ? (getActiveQueueMessageIds() || []).map((id) => String(id || "").trim()).filter(Boolean)
         : [];
+      const steering = typeof getSteeringState === "function"
+        ? getSteeringState()
+        : null;
+      const settleFailed = typeof getSettleFailed === "function"
+        ? (getSettleFailed() || []).filter((entry) => entry && String(entry.id || "").trim())
+        : [];
       const body = {
         ...(activeQueueMessageId ? { activeQueueMessageId } : {}),
         ...(activeQueueMessageIds.length ? { activeQueueMessageIds } : {}),
+        ...(steering && typeof steering === "object" ? { steering } : {}),
+        ...(settleFailed.length ? { settleFailed } : {}),
       };
-      await api("POST", "/api/heartbeat", body);
+      const response = await api("POST", "/api/heartbeat", body);
+      // Failed by the relay, or skipped because this worker has no claim on
+      // the row: either way the worker releases it.
+      const handled = [
+        ...(Array.isArray(response?.settleFailedHandled) ? response.settleFailedHandled : []),
+        ...(Array.isArray(response?.settleFailedSkipped) ? response.settleFailedSkipped : []),
+      ];
+      if (handled.length) {
+        try { onSettleFailedHandled(handled); } catch {}
+      }
       return true;
     } catch {
       return false;
     }
   }
 
+  /**
+   * 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
+   * up). Requests inside one window share a single pulse, sent at its end so
+   * it carries the settled state.
+   */
+  function requestPulse() {
+    if (requestedPulseTimer) return;
+    requestedPulseTimer = setTimeoutImpl(() => {
+      requestedPulseTimer = null;
+      void pulseHeartbeat();
+    }, pulseCoalesceMs);
+    requestedPulseTimer?.unref?.();
+  }
+
   function startHeartbeat() {
     if (getHeartbeatTimer()) return;
     void pulseHeartbeat();
@@ -41,6 +90,10 @@ export function createHeartbeatController({
   }
 
   function stopHeartbeat() {
+    if (requestedPulseTimer) {
+      clearTimeoutImpl(requestedPulseTimer);
+      requestedPulseTimer = null;
+    }
     const timer = getHeartbeatTimer();
     if (!timer) return;
     clearInterval(timer);
@@ -49,6 +102,7 @@ export function createHeartbeatController({
 
   return {
     pulseHeartbeat,
+    requestPulse,
     startHeartbeat,
     stopHeartbeat,
   };

package/shared/worker-runtime/runner-link-wiring.mjs

@@ -0,0 +1,44 @@
+// Glue between a steering-capable session runner and the relay socket link —
+// shared by every worker whose runner exposes a delivery gate (the Claude
+// session runner, the Copilot SDK runner). Kept out of the worker entry files
+// (which run main() on import) so the wiring itself is testable.
+
+import { requeueOwedRows } from '../worker-crash-guard.mjs';
+
+/**
+ * The runner reports every flip of its delivery gate; the link turns them
+ * into relay readiness frames. `attach` is late-bound because the runner is
+ * built before the link (the link's probes call into the runner).
+ */
+export function createRunnerLinkBridge() {
+  let link = null;
+  return {
+    attach(nextLink) {
+      link = nextLink || null;
+    },
+    onDeliveryReadinessChange(ready) {
+      if (!link) return;
+      if (ready) void link.notifyReady('steering-resumed');
+      else link.notifyUnready('steering-held');
+    },
+    // Only a relay that advertised the capability in server.hello understands
+    // the penalty-free hand-back; before any hello, assume an older relay.
+    canHandBackHeldDelivery() {
+      return Boolean(link?.serverSupports?.('steering-held'));
+    },
+  };
+}
+
+/**
+ * Worker shutdown (SIGTERM/SIGINT): rows whose prompt the engine already
+ * consumed and whose settle has not landed are failed terminally before the
+ * process goes — left behind, the relay's dead-worker recovery would requeue
+ * them and run them a second time. Bounded like the crash guard: a shutdown
+ * that hangs is worse than none. Other owed rows are left to the relay's
+ * recovery, as before.
+ */
+export async function failSettlingRowsOnShutdown({ api, runner, timeoutMs = 2_000 } = {}) {
+  const settling = (runner?.getActiveQueueMessageIds?.() || []).filter((entry) => entry?.terminalError);
+  await requeueOwedRows({ api, entries: settling, timeoutMs });
+  return settling.length;
+}

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

@@ -45,6 +45,25 @@ export function createWorkerWebSocketLink({
   // task). Never blocks delivery; failures are the handler's to log.
   onControl = () => {},
   getSessionReady = () => false,
+  // Mid-turn steering opt-in. A worker whose runner can absorb another
+  // delivered message into the live turn (the Claude session runner; the
+  // Copilot runner's steerIntoActiveTurn is compatible but not yet opted in)
+  // reports so here, and the link then keeps signalling readiness while a
+  // delivery is still in flight and runs the resulting concurrent delivery
+  // instead of coalescing it. Workers that leave this unset keep the strict
+  // single-flight contract.
+  getSteeringReady = null,
+  // Steering-capable workers only: true while the runner is holding deliveries
+  // (a question card or plan approval is open, a compaction or adoption is in
+  // progress, a turn-opening delivery is mid-flight). A held worker never
+  // signals readiness — idle or not — and tells the server so with
+  // worker.unready, because a delivery landing in a hold is handed back.
+  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.
+  onServerHello = () => {},
   getSessionId = () => null,
   getPid = () => null,
   minBackoffMs = 1000,
@@ -65,11 +84,20 @@ export function createWorkerWebSocketLink({
   let readyRefreshTimer = null;
   let reconnectAttempt = 0;
   let reconnectDelayMs = 0;
-  let deliveryInFlight = null;
+  // Insertion-ordered: the first entry is the oldest in-flight delivery, which
+  // is what a legacy worker's coalesced delivery waits on.
+  const deliveriesInFlight = new Set();
+  // message id → in-flight delivery. Only a redelivery of the SAME message is
+  // coalesced; a different message is never folded onto another's promise.
+  const deliveriesById = new Map();
   let lastOpenAt = null;
   let lastMessageAt = null;
   let lastHelloSentAt = null;
   let lastReadySentAt = null;
+  let lastUnreadySentAt = null;
+  // What the connected relay advertised in server.hello (see
+  // WORKER_PROTOCOL_CAPABILITIES in the relay's worker websocket service).
+  let serverCapabilities = new Set();
   let lastPingSentAt = null;
   let lastPongAt = null;
   let lastQueueChangedAt = null;
@@ -94,20 +122,61 @@ export function createWorkerWebSocketLink({
     }
   }
 
+  function steeringCapable() {
+    return typeof getSteeringReady === "function";
+  }
+
+  function steeringReady() {
+    if (!steeringCapable()) return false;
+    try {
+      return getSteeringReady() === true;
+    } catch {
+      return false;
+    }
+  }
+
+  function deliveryHeld() {
+    if (typeof getDeliveryHeld !== "function") return false;
+    try {
+      return getDeliveryHeld() === true;
+    } catch {
+      // Fail closed: a held worker that signals ready bounces every delivery.
+      return true;
+    }
+  }
+
   function notifyHello(reason = "worker-hello") {
     if (!getSessionReady()) return false;
+    // The server treats hello as readiness; a held worker still has to bind
+    // its identity, so it says hello without claiming to be ready.
+    const held = deliveryHeld();
     const sent = send({
       type: "worker.hello",
       reason,
       sessionId: normalizeText(getSessionId()),
       pid: normalizePositiveInt(getPid()),
+      ...(held ? { ready: false } : {}),
     });
     if (sent) lastHelloSentAt = getNowMs();
     return sent;
   }
 
+  function notifyUnready(reason = "worker-unready") {
+    if (!getSessionReady()) return false;
+    const sent = send({
+      type: "worker.unready",
+      reason,
+      sessionId: normalizeText(getSessionId()),
+      pid: normalizePositiveInt(getPid()),
+    });
+    if (sent) lastUnreadySentAt = getNowMs();
+    return sent;
+  }
+
   async function notifyReady(reason = "worker-ready") {
-    if (!getSessionReady() || deliveryInFlight) return false;
+    if (!getSessionReady()) return false;
+    if (deliveryHeld()) return false;
+    if (deliveriesInFlight.size && !steeringReady()) return false;
     const sent = send({
       type: "worker.ready",
       reason,
@@ -132,8 +201,21 @@ export function createWorkerWebSocketLink({
 
   async function deliverPending(pending, reason = "queue-deliver") {
     if (!getSessionReady()) return false;
-    if (deliveryInFlight) return deliveryInFlight;
-    deliveryInFlight = Promise.resolve()
+    // A redelivery of a message that is already running (socket reconnect)
+    // coalesces onto it rather than double-running the turn.
+    const messageId = normalizeText(pending?.message?.id);
+    if (messageId && deliveriesById.has(messageId)) return deliveriesById.get(messageId);
+    // A DIFFERENT message while one is in flight: a steering-capable worker's
+    // runner decides — it steers the message into the live turn, or hands it
+    // back to the queue when the turn is holding (the server's readiness can
+    // lag a hold by a round-trip). Coalescing it here used to drop its payload
+    // and strand the row `processing` until heartbeat recovery. Workers
+    // without the steering opt-in keep strict single-flight: their runners
+    // have no hand-back path, and the heartbeat recovers the row.
+    if (deliveriesInFlight.size && !steeringCapable()) {
+      return deliveriesInFlight.values().next().value;
+    }
+    const delivery = Promise.resolve()
       .then(() => onDeliver(pending, reason))
       .catch((error) => {
         dbg("worker ws delivery failed", reason, error?.message || String(error));
@@ -141,9 +223,12 @@ export function createWorkerWebSocketLink({
       })
       .finally(() => {
         lastDeliveryAt = getNowMs();
-        deliveryInFlight = null;
+        deliveriesInFlight.delete(delivery);
+        if (messageId && deliveriesById.get(messageId) === delivery) deliveriesById.delete(messageId);
       });
-    return deliveryInFlight;
+    deliveriesInFlight.add(delivery);
+    if (messageId) deliveriesById.set(messageId, delivery);
+    return delivery;
   }
 
   function clearReconnectTimer() {
@@ -173,7 +258,18 @@ export function createWorkerWebSocketLink({
       return closeStaleSocket(`no-server-message:${reason}`);
     }
     notifyPing(reason);
-    if (deliveryInFlight) return true;
+    if (deliveryHeld()) {
+      // Re-asserted on every refresh: a ready frame that crossed the hold on
+      // the wire would otherwise leave the server's readiness stuck on.
+      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);
     void notifyReady(reason);
     return true;
@@ -215,6 +311,7 @@ export function createWorkerWebSocketLink({
     }
     const url = toWebSocketUrl(serverUrl, token, getSessionId, getPid);
     ws = new WebSocketImpl(url);
+    let serverHelloSeen = false;
     ws.addEventListener("open", () => {
       const openedAt = getNowMs();
       reconnectAttempt = 0;
@@ -240,6 +337,15 @@ export function createWorkerWebSocketLink({
         return;
       }
       if (payload?.type === "server.hello") {
+        serverCapabilities = new Set(Array.isArray(payload.capabilities) ? payload.capabilities.map(String) : []);
+        if (!serverHelloSeen) {
+          serverHelloSeen = true;
+          try {
+            onServerHello(String(payload.reason || "server-hello"));
+          } catch (error) {
+            dbg("worker ws hello handler failed", error?.message || String(error));
+          }
+        }
         void notifyReady(String(payload.reason || "server-hello"));
         return;
       }
@@ -271,6 +377,8 @@ export function createWorkerWebSocketLink({
     });
     ws.addEventListener("close", () => {
       clearReadyRefreshTimer();
+      // The next connection may reach a different (restarted) relay.
+      serverCapabilities = new Set();
       if (stopped) return;
       dbg("worker ws disconnected");
       scheduleReconnect();
@@ -302,13 +410,14 @@ export function createWorkerWebSocketLink({
     const connected = !!ws && ws.readyState === resolveSocketStateValue(ws, "OPEN", 1);
     return {
       connected,
-      delivering: !!deliveryInFlight,
+      delivering: deliveriesInFlight.size > 0,
       reconnectAttempt,
       reconnectDelayMs,
       lastOpenAt,
       lastMessageAt,
       lastHelloSentAt,
       lastReadySentAt,
+      lastUnreadySentAt,
       lastPingSentAt,
       lastPongAt,
       lastQueueChangedAt,
@@ -318,6 +427,8 @@ export function createWorkerWebSocketLink({
 
   return {
     notifyReady,
+    notifyUnready,
+    serverSupports: (capability) => serverCapabilities.has(String(capability || "")),
     start,
     stop,
     status,