viewable-one 0.0.0-stage → 0.12.1

package/lib/runnerPace.mjs

@@ -0,0 +1,283 @@
+// HOW OFTEN THE RUNNER CALLS THE BOARD (ticket e8, measured 2026-10-01,
+// approved by the owner 2026-10-03).
+//
+// Each watched folder ran two fixed loops: claim every 5 s and beat every
+// 10 s, with no backoff when idle and none on a server error. Idle runners
+// made about 3,500 board-runner calls per half hour, and during an hour of
+// 502s they kept the same pace. This file is the one place that decides the
+// next wait, for both loops:
+//
+//   - work, or a run already active: the base interval (claim 5 s, beat 10 s)
+//   - an empty claim: the claim interval grows by half the base per empty
+//     claim up to 6x the base (5 s -> 30 s; 4x until #616), so a queued run
+//     is still picked up within about 30 s
+//   - a server error (5xx, 429) or a network failure: exponential backoff
+//     with jitter, from the base up to 12 claim intervals or 6 beats (60 s
+//     at the defaults), reset by the first success
+//
+// The caps scale with the base interval rather than being fixed numbers, so
+// a test that polls every 10 ms backs off in milliseconds too.
+//
+// ONE BEAT PER RUNNER, NOT PER FOLDER (#616, 2026-10-16). Every folder ran
+// its own heartbeat and claim, about 9 calls a minute per idle folder, and a
+// runner with 5 folders tripped Cloudflare's per-IP rate limit on the
+// function. Now:
+//
+//   - one heartbeat covers every folder of the process (`makeHeartbeatHub`)
+//   - its `pending` field says which folders have a run waiting, and only
+//     those claim; an idle folder makes no claim call at all
+//   - `register` is shared and only repeats every 5 minutes, or at once
+//     when the folder list changes
+//   - against a function without `pending` (an older deploy) each folder
+//     polls `claim` as before, slowing to 6x the base (30 s) while idle
+//   - a 429 that says Retry-After waits that long (`failed(retryAfterMs)`),
+//     up to an hour, because calling sooner only extends the block
+//
+// A 401 is not a server error here. It keeps its own path (auth.mjs marks
+// the credential dead and later calls do not reach the network at all).
+//
+// Nothing else counts as a failure for backoff: a refusal (`not yours`, a
+// full runs-at-once count, a local lock) keeps the base interval, because none of
+// those get better by calling less often and none of them load the server.
+
+/** The wait after `failures` server errors in a row: base * 2^(n-1), capped,
+ * then jittered down by up to 20% so many runners do not retry in step. Never
+ * shorter than the base interval. */
+export function backoffMs(failures, { baseMs, capMs, random = Math.random }) {
+  if (failures <= 0) return baseMs;
+  const ceiling = Math.min(capMs, baseMs * 2 ** (failures - 1));
+  return Math.max(baseMs, Math.round(ceiling * (0.8 + 0.2 * random())));
+}
+
+/** The longest Retry-After the runner honours (#616). Cloudflare's block
+ * lasts minutes; a bigger number is more likely a bad header than a plan. */
+export const RETRY_AFTER_CAP_MS = 60 * 60_000;
+
+/** The wait after `empty` empty claims in a row: base plus half the base per
+ * empty claim, up to `maxMs`. */
+export function idleMs(empty, { baseMs, maxMs }) {
+  return Math.min(Math.max(baseMs, maxMs), baseMs + (empty * baseMs) / 2);
+}
+
+/** One loop's pace. Each method records what the last call did and returns
+ * how long to wait before the next one.
+ *
+ *  - `work()`   the call did something, or a run is active: base interval
+ *  - `idle()`   a claim found nothing: grows toward `idleMaxMs`
+ *  - `failed(retryAfterMs?)` a server error or network failure: backs off
+ *    toward `errorCapMs`, and never sooner than a Retry-After the server sent
+ *  - `steady()` anything else (a refusal, a local wait): base interval */
+export function makePace({ baseMs, idleMaxMs = baseMs, errorCapMs = baseMs, random = Math.random }) {
+  let failures = 0;
+  let empty = 0;
+  return {
+    work() {
+      failures = 0;
+      empty = 0;
+      return baseMs;
+    },
+    steady() {
+      failures = 0;
+      empty = 0;
+      return baseMs;
+    },
+    idle() {
+      failures = 0;
+      empty += 1;
+      return idleMs(empty, { baseMs, maxMs: idleMaxMs });
+    },
+    failed(retryAfterMs) {
+      empty = 0;
+      failures += 1;
+      const backoff = backoffMs(failures, { baseMs, capMs: errorCapMs, random });
+      return Number.isFinite(retryAfterMs) && retryAfterMs > backoff ? Math.min(retryAfterMs, RETRY_AFTER_CAP_MS) : backoff;
+    },
+  };
+}
+
+/** The claim loop's pace for these settings: 5 s base, 30 s when idle, 60 s
+ * under errors, at the defaults. */
+export function claimPace(settings) {
+  const baseMs = settings.pollMs;
+  return makePace({
+    baseMs,
+    idleMaxMs: settings.idleMaxMs ?? baseMs * 6,
+    errorCapMs: settings.errorCapMs ?? baseMs * 12,
+    random: settings.random,
+  });
+}
+
+/** The beat's pace: 10 s base, 60 s under errors. A healthy beat stays at the
+ * base, which keeps presence inside the 30 s window the app and doctor read
+ * as "runner online" (RUNNER_STALE_MS). Under errors the beats are failing
+ * anyway, so presence is already going stale whatever the interval. */
+export function beatPace(settings, fallbackMs) {
+  const baseMs = settings.beatMs ?? fallbackMs;
+  return makePace({ baseMs, errorCapMs: settings.errorCapMs ?? baseMs * 6, random: settings.random });
+}
+
+/** How long a successful `register` answer is reused (#616). The folder list
+ * is the key, so a folder joining or leaving registers at once; this only
+ * spaces out the repeats of an unchanged list. Presence stays fresh through
+ * the heartbeat, which bumps the same `last_seen_at`. */
+export const REGISTER_REFRESH_MS = 5 * 60_000;
+
+/** One shared answer: reused while in flight and until it expires. A success
+ * lives `ttlMs`; a failure `failureTtlMs`, or as long as its Retry-After. A
+ * failure is shared too, so a server that just failed one folder is not
+ * asked again by the next folder a second later. */
+function shareAnswer(send, { at, ttlMs, failureTtlMs }) {
+  const entry = { at, pending: true, expiresAt: Infinity, serverFailed: false };
+  entry.promise = Promise.resolve()
+    .then(send)
+    .then((answer) => {
+      const failed = !answer || answer.ok !== true;
+      const hold = failed ? Math.max(failureTtlMs, Math.min(answer?.retryAfterMs ?? 0, RETRY_AFTER_CAP_MS)) : ttlMs;
+      entry.expiresAt = at + hold;
+      entry.serverFailed = failed && answer?.transient === true;
+      return answer;
+    }, (error) => {
+      entry.expiresAt = at + failureTtlMs;
+      entry.serverFailed = true;
+      throw error;
+    })
+    .finally(() => {
+      entry.pending = false;
+    });
+  return entry;
+}
+const fresh = (entry, at) => entry.pending || at < entry.expiresAt;
+
+/** Coalesce `register` across the folders of one process (ticket e8 item 3).
+ * Every folder's beat registers the whole folder list, so the second and third
+ * folder beating inside the same window would send exactly the same call
+ * again. Within `ttlMs` of the last register for the same list, or while it is
+ * still in flight, callers share its answer; a failure for `failureTtlMs`. */
+export function makeRegistrar({ ttlMs, failureTtlMs = ttlMs, now = Date.now }) {
+  let last = null;
+  return {
+    register(key, send) {
+      const at = now();
+      if (last && last.key === key && fresh(last, at)) return last.promise;
+      last = Object.assign(shareAnswer(send, { at, ttlMs, failureTtlMs }), { key });
+      return last.promise;
+    },
+    // A login to another account makes every cached project id obsolete.
+    invalidate() {
+      last = null;
+    },
+  };
+}
+
+/** ONE HEARTBEAT FOR EVERY FOLDER OF A PROCESS (#616).
+ *
+ * `beat(projectId, send)` joins the folder and answers with a heartbeat that
+ * covers it: the last one, if it is fresh (in flight, or under `ttlMs` old)
+ * and already covered this folder, or a new `send(projectIds)` for every
+ * folder that beat in the last `memberTtlMs`. With folders beating every
+ * `ttlMs / 0.9`, the process sends one heartbeat per beat interval however
+ * many folders it watches. The answer holds every folder's stops and ops;
+ * each folder keeps its own (`op.project_id`).
+ *
+ * A function that predates #616 sends no `pending` and no `project_id` on
+ * run ops, so its answer cannot be split. The first such answer turns the
+ * hub off for good: a covering answer for more than this folder is thrown
+ * away (its ops come back on the next beat), and each folder beats on its
+ * own from then on, as before.
+ *
+ * A server failure (5xx, 429, network) is shared with every folder while it
+ * is fresh, covered or not: the server is failing for all of them, and a 429
+ * holds for its whole Retry-After.
+ *
+ * A refusal ("not yours": a folder the server no longer knows) would refuse
+ * the whole batch, so each folder of that batch asks alone once, and a folder
+ * refused alone keeps beating alone until the server takes it again. The
+ * others go back to one shared call. `leave` drops a folder at once (a
+ * forget, a watcher that ended).
+ *
+ * Every answer comes back as a copy with `coveredProjectIds`, the folders the
+ * call was for, so a folder can tell an op that is its own from one that
+ * names no project.
+ *
+ * PUSH (#813). `ttlMs` and `memberTtlMs` may be functions, read at each beat,
+ * so the hub follows the beat: 10 s while polling, 5 min while the runner is
+ * joined to its topic. A failed answer lives `failureTtlMs` (number or
+ * function, never longer than `ttlMs`), so a retry 10 s after a blip is a real
+ * call and not the cached failure. `invalidate(at)` makes every answer started before
+ * `at` stale, so the next beat really asks: a join, a dropped socket or an op
+ * event. Every folder hearing the same event passes the same `at`, so they
+ * still share the one call that follows. */
+export function makeHeartbeatHub({ ttlMs, memberTtlMs, failureTtlMs, now = Date.now }) {
+  const ttl = () => (typeof ttlMs === "function" ? ttlMs() : ttlMs);
+  const failureTtl = () => Math.min(typeof failureTtlMs === "function" ? failureTtlMs() : failureTtlMs ?? Infinity, ttl());
+  const memberTtl = () => (typeof memberTtlMs === "function" ? memberTtlMs() : memberTtlMs ?? 3 * ttl());
+  const members = new Map(); // projectId -> when it last beat
+  const alone = new Set(); // refused inside a batch and alone: beats alone
+  let last = null;
+  let notBefore = -Infinity;
+  let batching = true;
+  const covered = (answer, ids) => (answer && typeof answer === "object" ? { ...answer, coveredProjectIds: ids } : answer);
+  const single = async (projectId, send) => {
+    const answer = await send([projectId]);
+    if (batching) {
+      if (answer?.ok === false && answer.transient !== true) alone.add(projectId);
+      else if (answer?.ok === true) alone.delete(projectId);
+    }
+    return covered(answer, [projectId]);
+  };
+  return {
+    get batching() {
+      return batching;
+    },
+    async beat(projectId, send) {
+      if (!batching || alone.has(projectId)) return single(projectId, send);
+      const at = now();
+      members.set(projectId, at);
+      let entry = last && last.at >= notBefore && fresh(last, at) && (last.ids.includes(projectId) || last.serverFailed) ? last : null;
+      if (!entry) {
+        const memberMs = memberTtl();
+        for (const [id, seen] of members) if (at - seen > memberMs) members.delete(id);
+        const ids = [...members.keys()].sort();
+        const ttlNow = ttl();
+        entry = Object.assign(shareAnswer(() => send(ids), { at, ttlMs: ttlNow, failureTtlMs: failureTtl() }), { ids });
+        last = entry;
+      }
+      const answer = await entry.promise;
+      const mine = entry.ids.length === 1 && entry.ids[0] === projectId;
+      if (answer?.ok === true && !Array.isArray(answer.pending)) {
+        batching = false;
+        if (last === entry) last = null;
+        return mine ? covered(answer, entry.ids) : single(projectId, send);
+      }
+      if (answer?.ok === false && answer.transient !== true && !mine) {
+        if (last === entry) last = null;
+        members.delete(projectId);
+        return single(projectId, send);
+      }
+      return covered(answer, entry.ids);
+    },
+    leave(projectId) {
+      members.delete(projectId);
+      alone.delete(projectId);
+      if (last?.ids.includes(projectId)) last = null;
+    },
+    invalidate(at = now()) {
+      notBefore = Math.max(notBefore, at);
+    },
+  };
+}
+
+/** A wait that ends early when `signal` aborts, so a long backoff never holds
+ * up a stop. */
+export function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}

package/lib/runnerPerformance.mjs

@@ -0,0 +1,26 @@
+// Operational run timings only. Never inspect prompts, logs, paths or identity.
+export function createRunnerPerformance(run, now = () => performance.now()) {
+  const began = now();
+  const created = typeof run.created_at === 'string' ? Date.parse(run.created_at) : NaN;
+  const claimed = typeof run.claimed_at === 'string' ? Date.parse(run.claimed_at) : NaN;
+  const queue = claimed - created;
+  let launched, firstOutput, exited;
+  const elapsed = (end, start) => Math.max(0, Math.round(end - start));
+  return {
+    launched() { launched ??= now(); },
+    output() { if (launched !== undefined) firstOutput ??= now(); },
+    exited() { if (launched !== undefined) exited ??= now(); },
+    snapshot() {
+      const ended = now();
+      return {
+        schema_version: 1,
+        ...(Number.isFinite(queue) && queue >= 0 ? { queue_ms: queue } : {}),
+        setup_ms: elapsed(launched ?? ended, began),
+        ...(launched !== undefined ? { execution_ms: elapsed(exited ?? ended, launched) } : {}),
+        ...(firstOutput !== undefined ? { first_output_ms: elapsed(firstOutput, launched) } : {}),
+        ...(exited !== undefined ? { completion_ms: elapsed(ended, exited) } : {}),
+        total_ms: elapsed(ended, began),
+      };
+    },
+  };
+}

package/lib/runnerRealtime.mjs

@@ -0,0 +1,340 @@
+// THE RUNNER'S PUSH CHANNEL (#813, server in #811 / PR 819, report #795
+// option c).
+//
+// The database tells the runner the moment something happens: a run is
+// waiting (`pending`), a Stop (`stop`), an op on a run (`op`). It sends each
+// one to the account's private Realtime topic. This file holds the runner's
+// end of that topic and nothing else:
+//
+//   - asks `board-runner` for the topic (`realtime` op: url, public key,
+//     topic, expiresAt, renewAt), joins it, and tracks presence there as
+//     `{runnerId, version, folders}`, keyed by the runner id
+//   - asks again from `renewAt` and moves to the next topic, leaving the old
+//     one once the new one has joined; no access token, no setAuth
+//   - tells its listeners when it joins or drops (`joined`/`left`) and passes
+//     each event on, with the moment it arrived (`at`)
+//
+// It never claims, stops or takes an op itself. The watch loop (runner.mjs)
+// turns an event into the call it already makes: `claimOne` for a waiting
+// run (so runs-at-once still applies, #364), `stopped.add` for a Stop, a
+// heartbeat for an op. The heartbeat stays the full catch-up, so an event
+// that never arrives costs time, never a run: while not joined the runner
+// beats every 10 s, as before; while joined, every 5 minutes.
+//
+// THE LIBRARY IS ON TRIAL (library-choices rule). `@supabase/realtime-js` is
+// reached only through `connectRealtime` below, imported on first use. The
+// state machine takes any `connect` with the same small shape, which is what
+// the tests pass (test/runnerRealtime.test.mjs, a fake socket).
+
+import * as runnerApiModule from "./runnerApi.mjs";
+import { backoffMs } from "./runnerPace.mjs";
+
+/** The beat while joined. The app counts a 0.12 runner online for 6 minutes
+ *  after its last beat when it cannot see its presence (src/runs/projects.ts,
+ *  RUNNER_PUSH_STALE_MS), so this must stay under that. */
+export const PUSH_BEAT_MS = 5 * 60_000;
+/** The beat interval of the moment: `pushBeatMs` (5 min) while `realtime`
+ *  is joined, `beatMs` (10 s) otherwise or without one. */
+export const beatBaseMs = (realtime, beatMs, pushBeatMs = PUSH_BEAT_MS) => (realtime?.joined ? pushBeatMs : beatMs);
+/** A join that has not come back SUBSCRIBED by then is dropped and asked
+ *  for again. */
+export const JOIN_WAIT_MS = 60_000;
+/** Asking again before the server has a new topic gets the same one back. */
+export const SAME_TOPIC_RETRY_MS = 60_000;
+/** Backoff while the op fails on a server error or the network. */
+const RETRY_BASE_MS = 10_000;
+const RETRY_CAP_MS = 5 * 60_000;
+/** An older function ("Unknown op"), or one with no topic to give: ask now
+ *  and then, not every few seconds. */
+const REFUSED_RETRY_MS = 30 * 60_000;
+
+/** The `realtime` op's answer, checked. null when it is not usable. */
+export function readGrant(out, now = Date.now()) {
+  if (!out || out.ok !== true) return null;
+  const { url, anonKey, topic } = out;
+  const expiresAt = Date.parse(out.expiresAt);
+  const renewAt = Date.parse(out.renewAt);
+  if (typeof url !== "string" || !/^https?:\/\//.test(url)) return null;
+  if (typeof anonKey !== "string" || anonKey === "") return null;
+  if (typeof topic !== "string" || !topic.startsWith("runner:")) return null;
+  if (!Number.isFinite(expiresAt) || !Number.isFinite(renewAt) || expiresAt <= now) return null;
+  return { url, anonKey, topic, expiresAt, renewAt };
+}
+
+/** The real socket, through `@supabase/realtime-js`. `connect({url,
+ *  anonKey})` -> `{join(topic, {key, onStatus, onBroadcast}) -> {track(meta),
+ *  leave()}, close()}`. The public key goes as the socket's `apikey` and as
+ *  the join's access token, as supabase-js sends it for a client with no
+ *  session; nothing here ever calls setAuth. */
+export async function connectRealtime({ url, anonKey }, { RealtimeClient } = {}) {
+  const Client = RealtimeClient ?? (await import("@supabase/realtime-js")).RealtimeClient;
+  const endpoint = `${url.replace(/^http/, "ws").replace(/\/+$/, "")}/realtime/v1`;
+  const client = new Client(endpoint, { params: { apikey: anonKey }, accessToken: async () => anonKey });
+  return {
+    join(topic, { key, onStatus, onBroadcast }) {
+      const channel = client.channel(topic, { config: { private: true, presence: { key } } });
+      for (const event of ["pending", "stop", "op", "reply"]) {
+        channel.on("broadcast", { event }, (message) => onBroadcast(event, message?.payload ?? {}));
+      }
+      channel.subscribe((status, error) => onStatus(status, error));
+      return {
+        track: (meta) => channel.track(meta),
+        leave: () => client.removeChannel(channel),
+      };
+    },
+    close: () => client.disconnect(),
+  };
+}
+
+const errorText = (error) => (error instanceof Error ? error.message : String(error ?? ""));
+
+/**
+ * One per process. `start()` once; `close()` on the way out.
+ *
+ * `subscribe(fn)` -> unsubscribe. `fn({type, at, payload?})`, where `type` is
+ * `joined`, `left`, `pending`, `stop`, `op` or `reply`, and `at` is when it happened
+ * here: every folder hearing one event gets the same `at`, which is what the
+ * heartbeat hub keys on (`invalidate(at)`).
+ *
+ * `joined` is true while a topic is SUBSCRIBED and has not expired.
+ * `setFolder(projectId, on)` keeps presence's `folders` current.
+ */
+export function makeRunnerRealtime({
+  runnerId,
+  version,
+  runnerApi = runnerApiModule,
+  env,
+  fetchImpl,
+  connect = connectRealtime,
+  now = Date.now,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  random = Math.random,
+  log = () => {},
+} = {}) {
+  const listeners = new Set();
+  const folders = new Set();
+  let socket = null; // {url, anonKey, conn} once connected
+  let held = null; // the topic events come from: {grant, handle, joined, timers}
+  let joining = null; // the next topic, while it joins
+  let asking = null;
+  let askTimer = null;
+  let failures = 0;
+  let closed = false;
+  let wasJoined = false;
+  let lastComplaint = "";
+
+  const emit = (event) => {
+    for (const fn of [...listeners]) {
+      try { fn(event); } catch (error) { log(`realtime listener failed: ${errorText(error)}`); }
+    }
+  };
+  const isJoined = () => Boolean(held?.joined && now() < held.grant.expiresAt);
+  // `joined`/`left` only on a real change, so a rejoin that lands while the
+  // runner is already joined does not beat twice.
+  const settle = () => {
+    const joined = isJoined();
+    if (joined === wasJoined) return;
+    wasJoined = joined;
+    emit({ type: joined ? "joined" : "left", at: now() });
+  };
+  const meta = () => ({ runnerId, version, folders: [...folders].sort() });
+  const track = (entry) => {
+    if (!entry?.joined) return;
+    Promise.resolve()
+      .then(() => entry.handle.track(meta()))
+      .catch((error) => log(`realtime presence failed: ${errorText(error)}`));
+  };
+  const clearEntry = (entry) => {
+    if (!entry) return;
+    entry.retired = true;
+    for (const timer of entry.timers) clearTimer(timer);
+    entry.timers.length = 0;
+    Promise.resolve()
+      .then(() => entry.handle?.leave())
+      .catch(() => {});
+  };
+  const schedule = (entry, ms, fn) => {
+    const timer = setTimer(fn, Math.max(0, ms));
+    timer?.unref?.();
+    entry.timers.push(timer);
+  };
+  const askLater = (ms) => {
+    if (closed) return;
+    clearTimer(askTimer);
+    askTimer = setTimer(() => {
+      askTimer = null;
+      void ask();
+    }, Math.max(0, ms));
+    askTimer?.unref?.();
+  };
+  const complain = (line) => {
+    if (line === lastComplaint) return;
+    lastComplaint = line;
+    log(line);
+  };
+
+  const join = (grant) => {
+    // A new client for a new address or key, and for a topic joined again:
+    // realtime-js hands back the channel it already has for a topic, and a
+    // dead join is the one thing a rejoin must not reuse.
+    const again = [held, joining].some((entry) => entry && entry.grant.topic === grant.topic);
+    if (!socket || again || socket.url !== grant.url || socket.anonKey !== grant.anonKey) {
+      const old = socket;
+      clearEntry(held);
+      clearEntry(joining);
+      held = null;
+      joining = null;
+      socket = { url: grant.url, anonKey: grant.anonKey, conn: Promise.resolve(connect({ url: grant.url, anonKey: grant.anonKey })) };
+      if (old) void old.conn.then((c) => c.close()).catch(() => {});
+    }
+    const entry = { grant, handle: null, joined: false, retired: false, timers: [] };
+    // A topic that is joined replaces `held` once it joins; one that is not
+    // replaces it now, since nothing comes from it anyway.
+    if (held?.joined) {
+      clearEntry(joining);
+      joining = entry;
+    } else {
+      clearEntry(held);
+      clearEntry(joining);
+      joining = null;
+      held = entry;
+    }
+    const onStatus = (status, error) => {
+      if (entry.retired || closed) return;
+      if (status === "SUBSCRIBED") {
+        entry.joined = true;
+        if (joining === entry) {
+          clearEntry(held);
+          held = entry;
+          joining = null;
+        }
+        track(entry);
+        lastComplaint = "";
+        // ONE HEARTBEAT ON EVERY JOIN AFTER A GAP, rejoins included: what was
+        // sent while the socket was down is what that beat catches up on. A
+        // move to the next topic has no gap (the old one stayed joined until
+        // now), so it beats nothing.
+        settle();
+        return;
+      }
+      // CHANNEL_ERROR, TIMED_OUT, CLOSED: the socket dropped, or the topic
+      // refused the join. The library rejoins on its own when it can; until
+      // then the runner beats every 10 s. One that stays down past
+      // JOIN_WAIT_MS is asked for again, in case the topic itself is gone.
+      entry.joined = false;
+      if (status !== "CLOSED") complain(`realtime: ${status}${error ? `: ${errorText(error)}` : ""}; checking in every 10 s until it is back`);
+      schedule(entry, JOIN_WAIT_MS, () => {
+        if (!entry.retired && !entry.joined && (held === entry || joining === entry)) void ask();
+      });
+      settle();
+    };
+    const onBroadcast = (type, payload) => {
+      if (entry.retired || closed) return;
+      emit({ type, payload: payload ?? {}, at: now() });
+    };
+    // Expiry: the database stops sending to a topic at `expiresAt`. A renewal
+    // that worked has moved on long before; one that did not ends here.
+    schedule(entry, grant.expiresAt - now(), () => {
+      if (entry.retired) return;
+      entry.joined = false;
+      if (held === entry) held = null;
+      if (joining === entry) joining = null;
+      clearEntry(entry);
+      settle();
+      void ask();
+    });
+    schedule(entry, JOIN_WAIT_MS, () => {
+      if (!entry.retired && !entry.joined && (held === entry || joining === entry)) void ask();
+    });
+    void socket.conn
+      .then((conn) => {
+        if (entry.retired || closed) return;
+        entry.handle = conn.join(grant.topic, { key: runnerId, onStatus, onBroadcast });
+      })
+      .catch((error) => {
+        complain(`realtime: could not connect: ${errorText(error)}`);
+        if (held === entry) held = null;
+        if (joining === entry) joining = null;
+        clearEntry(entry);
+        socket = null;
+        failures += 1;
+        askLater(backoffMs(failures, { baseMs: RETRY_BASE_MS, capMs: RETRY_CAP_MS, random }));
+      });
+  };
+
+  async function askOnce() {
+    // A runner api with no `realtime` (an injected fake) is an older server.
+    const out = typeof runnerApi.realtime === "function"
+      ? await runnerApi.realtime({ env, fetchImpl })
+      : { ok: false, error: "no realtime op" };
+    if (closed) return;
+    const grant = readGrant(out, now());
+    if (!grant) {
+      failures += 1;
+      const transient = out?.ok === false && out.transient === true;
+      complain(`realtime: ${out?.ok === false ? out.error : "the answer had no usable topic"}; checking in every 10 s`);
+      const wait = transient ? backoffMs(failures, { baseMs: RETRY_BASE_MS, capMs: RETRY_CAP_MS, random }) : REFUSED_RETRY_MS;
+      askLater(Number.isFinite(out?.retryAfterMs) ? Math.max(wait, out.retryAfterMs) : wait);
+      return;
+    }
+    failures = 0;
+    const current = joining ?? held;
+    if (current && current.grant.topic === grant.topic && current.grant.url === grant.url) {
+      // Same topic. While it is joined (or still joining) there is nothing
+      // to do but ask again at its renew time; a dead join is rejoined.
+      if (current.joined || (!current.retired && current === joining)) {
+        current.grant = grant;
+        askLater(grant.renewAt > now() ? grant.renewAt - now() : SAME_TOPIC_RETRY_MS);
+        return;
+      }
+    }
+    join(grant);
+    askLater(grant.renewAt > now() ? grant.renewAt - now() : SAME_TOPIC_RETRY_MS);
+  }
+  const ask = () => {
+    if (closed) return Promise.resolve();
+    clearTimer(askTimer);
+    askTimer = null;
+    return (asking ??= askOnce()
+      .catch((error) => {
+        failures += 1;
+        complain(`realtime: ${errorText(error)}`);
+        askLater(backoffMs(failures, { baseMs: RETRY_BASE_MS, capMs: RETRY_CAP_MS, random }));
+      })
+      .finally(() => { asking = null; }));
+  };
+
+  return {
+    get joined() {
+      return isJoined();
+    },
+    start: () => ask(),
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    setFolder(projectId, on) {
+      if (typeof projectId !== "string" || projectId === "") return;
+      const had = folders.has(projectId);
+      if (on === had) return;
+      if (on) folders.add(projectId);
+      else folders.delete(projectId);
+      track(held);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      clearTimer(askTimer);
+      clearEntry(held);
+      clearEntry(joining);
+      held = null;
+      joining = null;
+      wasJoined = false;
+      listeners.clear();
+      const conn = socket?.conn;
+      socket = null;
+      if (conn) await conn.then((c) => c.close()).catch(() => {});
+    },
+  };
+}