viewable-one 0.0.0-stage → 0.12.2

package/lib/rowsAnswers.mjs

@@ -0,0 +1,388 @@
+// ANSWERS AND MESSAGES OVER ROWS (brief 30, W2b, 2026-09-11).
+//
+// A runner-spawned child now reaches the board through the hosted endpoint
+// (lib/hosted.mjs, brief 30 W2a) under its own run key (X-Glytch-Session,
+// session.key) instead of a locally-spawned stdio server. This file is what
+// replaces the mirror-and-receipt push runner.mjs used to make while the
+// child was still running - `answerPoll`'s `latestGraphWriteMs` scan and
+// `undeliveredAnswers` over `inbox/ops/*.result.txt` receipts and `canvas/`
+// (see the dated retirement note above `undeliveredAnswers` in
+// questions.mjs). The new door is the SAME one everything else on the hosted
+// endpoint uses: `collect_session`, the tool `check_answer` already used to
+// answer "did HE answer me", now asked for the whole run.
+//
+// `collect_session` (supabase/functions/board-mcp/tools.mjs) already matches
+// "this run's own rows" server-side - every question stamped with THIS run's
+// sessionKey/reportKey (`applyOps` stamps every node it creates with
+// `data.sessionKey: store.sessionKey`, and `X-Glytch-Session` is what makes
+// that the RUN's key rather than the runner's own OAuth token's), and every
+// `session_messages` row addressed to it, drained (`delivered_at` stamped)
+// on read (supabase/functions/_shared/rows.mjs `takeMessages`). What the
+// endpoint does NOT deduplicate is an ANSWERED QUESTION: it returns every
+// question this key ever asked that carries an answer, on every single call,
+// so a poller has to remember which ones it has already delivered. A MESSAGE
+// is different - the server marks it delivered the moment it is fetched, so
+// `delivered_at` is what survives a runner restart for it, the same way a
+// file's absence is what survives one for a reply file.
+//
+// THE TOOL'S ANSWER IS TEXT FOR A MODEL, not a second JSON API - there is no
+// structured door into the same call, so this parses the exact shape the
+// handler writes (its "ANSWERED QUESTIONS:" / "MESSAGES FROM OTHER SESSIONS:"
+// / "next_since:" lines, `flat()`-ed to one line per row on that end already,
+// which is what makes a per-line parser safe here). The sections also come in
+// one fixed order, so the parser takes each header once and only moving
+// forward: a header that turns up again or out of order is text, never a
+// section. Messages come last, so nothing a peer sends (its label or its
+// text) can open the answered section and pass as the human's ruling (#324).
+//
+// A MESSAGE'S IMAGES (2026-09-11, brief 30 Move 2 M1b) ride the same text
+// reply, one line below the message they belong to - a bare JSON object,
+// the same "put a JSON block in a text result" idiom get_node already uses
+// for a node's own body. `parseCollected` below reads it back onto the
+// message object as `images`. Keep the payload intact so each transport
+// validates it before delivery; invalid pictures must not become text-only
+// success or disappear from late-reply recovery.
+
+import { createHash } from "node:crypto";
+import { callTool as hostedCallTool } from "./hosted.mjs";
+
+/** Parse collect_session's reply into rows a poller can act on. Tolerant of
+ *  every shape the tool actually writes: the "Nothing collected" sentence
+ *  (no section headers at all, just an intro line and `next_since:`), a
+ *  subset of the four sections, or all of them.
+ *
+ *  IMAGES (2026-09-11, brief 30 Move 2 M1b): a message that carries pictures
+ *  gets one more line right after its own, `  {"images":[...]}` - the exact
+ *  shape board-mcp/tools.mjs's collect_session handler writes. It is parsed
+ *  here and folded onto the message object that line follows, as `images`;
+ *  a message with none gets no such line and no such field, so a caller
+ *  that has never heard of images reads this exactly as it always has. A
+ *  malformed or misplaced JSON line (no preceding message in this poll,
+ *  or not valid JSON) is ignored rather than thrown - the same tolerance
+ *  this function already extends to a section header it does not
+ *  recognize. */
+// The order collect_session writes its sections in, and what each one is
+// read as here (null: not read).
+const SECTIONS = [
+  ["ANSWERED QUESTIONS:", "answered"],
+  ["STILL OPEN:", null],
+  ["COMMENTS HE WROTE:", null],
+  ["MESSAGES FROM OTHER SESSIONS:", "messages"],
+];
+
+export function parseCollected(text) {
+  const answered = [];
+  const messages = [];
+  let nextSince = 0;
+  let section = null;
+  let reached = -1;
+  for (const line of String(text ?? "").split("\n")) {
+    const since = line.match(/^next_since:\s*(\d+)/);
+    if (since) {
+      nextSince = Number(since[1]);
+      continue;
+    }
+    const header = SECTIONS.findIndex(([marker]) => marker === line);
+    if (header !== -1) {
+      // Only forward, each once: a repeated or out-of-order header is a
+      // line someone wrote, not the server's (#324).
+      if (header > reached) {
+        reached = header;
+        section = SECTIONS[header][1];
+      }
+      continue;
+    }
+    if (section === "answered") {
+      const m = line.match(/^ {2}(\S+) "(.*)" -> (.*)$/);
+      if (m) answered.push({ id: m[1], question: m[2], decision: m[3] });
+    } else if (section === "messages") {
+      const m = line.match(/^ {2}\[message from (.*?)\] (.*)$/);
+      if (m) {
+        messages.push({ from: m[1], text: m[2] });
+        continue;
+      }
+      const imagesLine = line.match(/^ {2}(\{.*\})$/);
+      if (imagesLine && messages.length > 0) {
+        try {
+          const parsed = JSON.parse(imagesLine[1]);
+          // The row's id (item 75): what the next call's `delivered` names.
+          if (typeof parsed.id === "number" || typeof parsed.id === "string") messages[messages.length - 1].id = parsed.id;
+          if (Object.hasOwn(parsed, "images")) {
+            messages[messages.length - 1].images = parsed.images;
+          }
+        } catch {
+          /* not the images line after all - leave the message as it was */
+        }
+      }
+    }
+  }
+  return { answered, messages, nextSince };
+}
+
+/** One call to collect_session, resolved and parsed. Never throws: a network
+ *  or auth failure is logged and read the same as an empty poll - a spawned
+ *  child's own turn is not this call's to fail. */
+export async function pollCollectSession({
+  callTool = hostedCallTool,
+  sessionKey,
+  since = 0,
+  env,
+  log = () => {},
+  // THE IDS THE CHILD TOOK since the last call (item 75). Always sent, so
+  // the endpoint hands messages back unstamped until one names them.
+  delivered = [],
+} = {}) {
+  let result;
+  try {
+    result = await callTool("collect_session", { since, delivered }, { sessionKey, env });
+  } catch (error) {
+    log(`collect_session failed: ${error instanceof Error ? error.message : String(error)}`);
+    return { ok: false, answered: [], messages: [], nextSince: since };
+  }
+  if (result.isError) {
+    log(`collect_session refused: ${result.text}`);
+    return { ok: false, answered: [], messages: [], nextSince: since };
+  }
+  // IMAGES RIDE ALONGSIDE THE TEXT REPLY, WHOLE-CALL (item 6): there is no
+  // per-message attribution in a flattened text protocol, so they are
+  // attached below only when this poll's whole batch is unambiguous - see
+  // `createRowsAnswerPoll`. Converted to the SAME data-URL shape a reply
+  // file's `images` array already carries (`data:<mediaType>;base64,<data>`
+  // - src/folder/spawnRequest.ts:376, child.mjs's `imageAttachments`), so
+  // `userMessage`/`imageAttachments` need no second shape to understand.
+  const images = (result.images ?? []).map((i) => `data:${i.mediaType};base64,${i.data}`);
+  return { ok: true, ...parseCollected(result.text), images };
+}
+
+/** The words a child reads for a ruling that arrived after ask_user had
+ *  already returned. Byte for byte what the old mirror-based `answerPoll`
+ *  said, so a session told about a late answer reads the same sentence it
+ *  always has. */
+export const formatAnswer = (a) =>
+  `The human answered a question you asked on the board. It arrived after ` +
+  `ask_user had already returned, so this is the only place you will see it.\n\n` +
+  `Q: ${a.question}\n` +
+  `A: ${a.decision}\n\n` +
+  `That is his ruling. Act on it, and do not ask it again.`;
+
+/** The same attribution wrapper a reply file's `from` field gets
+ *  (child.mjs's `watchReplies`), so a peer's message reads identically
+ *  whichever door delivered it. */
+export const formatMessage = (m) => `[message from ${m.from}] ${m.text}`;
+
+/** Preserve the complete attachment payload for transport validation and
+ *  late-reply recovery. Presence, not validity, chooses the per-message
+ *  payload over the legacy single-message fallback. */
+function deliverable(message, fallback = []) {
+  return { text: formatMessage(message), images: message.images !== undefined ? message.images : fallback };
+}
+
+/** A stateful poller: one `since` watermark plus one delivered-question set,
+ *  both scoped to this run and kept in memory only. A runner restart loses
+ *  them - accepted the same way `scannedMirrorAt` accepted it before this
+ *  (SPAWN.md, "a runner that dies mid-session leaks its concurrency slot") -
+ *  and a MESSAGE needs no such set at all: the endpoint's own `delivered_at`
+ *  is what keeps it from coming back, in this process or the next.
+ *
+ *  `poll()` is answerPoll-shaped for child.mjs's `runStreamingChild`: an
+ *  array of `{text, onDelivered}`. `onDelivered` marks a QUESTION delivered;
+ *  a message needs no bookkeeping on success, because the server already
+ *  will not hand it back. If `sendToChild` never calls `onDelivered` (the
+ *  child's stdin was already gone), the question stays undelivered and is
+ *  picked up by `promoteLateRows` below - a message in that same situation
+ *  has already been marked delivered server-side and is the one gap this
+ *  design accepts, spelled out where `promoteLateRows` is defined. */
+/** How close a repeat of the last message must follow it to be dropped. */
+export const REPEAT_WINDOW_MS = 30_000;
+
+export function createRowsAnswerPoll({ callTool = hostedCallTool, sessionKey, env, log = () => {}, now = Date.now, realtime, pushPollMs = 60_000 } = {}) {
+  let since = 0;
+  let dirty = true;
+  let lastPoll = -Infinity;
+  let wake = null;
+  const unsubscribe = realtime?.subscribe?.((event) => {
+    if (event.type !== "joined" && event.type !== "left" &&
+      !(event.type === "reply" && event.payload?.session_key === sessionKey)) return;
+    dirty = true;
+    wake?.();
+  });
+  const delivered = new Set();
+  // DELIVERY IS THE CHILD TAKING IT (round 4 item 75): a message's id goes
+  // into `toAck` only once `sendToChild` accepted it (its onDelivered), and
+  // the next call carries those ids so the endpoint stamps them. Until then
+  // the endpoint keeps handing the row back; `offered` skips the ones already
+  // put in front of the child. A message with no id (an older endpoint) is
+  // stamped on read there, as before.
+  const offered = new Set();
+  let toAck = [];
+  const took = (m) => { if (m.id !== undefined) toAck.push(m.id); };
+  // The last message put in front of this session (brief 52 round 1, Codex
+  // review: two app instances deliver the same held note, since every open
+  // tab delivers). The same sender, words and pictures again within
+  // REPEAT_WINDOW_MS is that second copy, and is dropped.
+  let last = null;
+  const repeats = (m, images) => {
+    const key = JSON.stringify([m.from, m.text, images]);
+    const at = now();
+    if (last !== null && last.key === key && at - last.at <= REPEAT_WINDOW_MS) {
+      if (last.accepted) took(m);
+      else last.copies.push(m);
+      return true;
+    }
+    last = { key, at, accepted: false, copies: [] };
+    return false;
+  };
+  const poll = async () => {
+    // Delivery acknowledgements also fetch the next queued batch. Only an
+    // idle session may wait for the push safety interval.
+    if (realtime?.joined && !dirty && toAck.length === 0 && now() - lastPoll < pushPollMs) return [];
+    dirty = false;
+    lastPoll = now();
+    // Only retire IDs serialized into this request, not deliveries that
+    // arrive while collect_session is in flight.
+    const acking = toAck.slice();
+    const collected = await pollCollectSession({ callTool, sessionKey, since, env, log, delivered: acking });
+    if (!collected.ok) { dirty = true; return []; }
+    toAck = toAck.filter((id) => !acking.includes(id));
+    if (collected.nextSince > since) since = collected.nextSince;
+    const out = [];
+    for (const a of collected.answered) {
+      if (delivered.has(a.id)) continue;
+      out.push({
+        deliveryKey: `answer:${a.id}`,
+        text: formatAnswer(a),
+        onDelivered: async () => {
+          delivered.add(a.id);
+          log(`delivered the answer to ${a.id}`);
+        },
+      });
+    }
+    // IMAGES, PER MESSAGE (brief 52 ruling 10). collect_session writes a
+    // message's pictures on the line right under it, so `parseCollected` has
+    // already put them on the message they belong to. The old whole-call
+    // `collected.images` (native image blocks on the reply, which the tool
+    // does not send) is the fallback for a batch of exactly one message.
+    for (const m of collected.messages) {
+      if (m.id !== undefined && offered.has(m.id)) continue;
+      if (m.id !== undefined) offered.add(m.id);
+      const delivery = deliverable(m, collected.messages.length === 1 ? collected.images : []);
+      if (repeats(m, delivery.images)) {
+        // A copy is acknowledged only after the original was accepted.
+        // In particular, invalid images must leave every source row unacked.
+        log(`dropped a repeat of the last message from ${m.from}`);
+        continue;
+      }
+      const pending = last;
+      out.push({
+        text: delivery.text,
+        ...(!(Array.isArray(delivery.images) && delivery.images.length === 0) ? { images: delivery.images } : {}),
+        onDelivered: async () => {
+          if (pending.accepted) return;
+          pending.accepted = true;
+          took(m);
+          for (const copy of pending.copies) took(copy);
+          pending.copies.length = 0;
+          log(`delivered a message from ${m.from}`);
+        },
+      });
+    }
+    return out;
+  };
+  // A child installs its existing delivery callback; retries replace it.
+  poll.subscribe = (fn) => { wake = fn; };
+  return {
+    close: () => { wake = null; unsubscribe?.(); },
+    poll,
+    since: () => since,
+    hasDelivered: (id) => delivered.has(id),
+    /** A question the runner asked for ITSELF (a permission question, see
+     *  permissionAsk.mjs) and reads the answer to on its own. Marked delivered
+     *  so neither the live poll nor the late sweep hands it to the session as
+     *  a message: its answer resolves the pending request instead. */
+    claim: (id) => { delivered.add(id); },
+    /** Ids the child took that no call has stamped yet; the late sweep sends them. */
+    pendingAcks: () => toAck.slice(),
+    acked: (ids) => { toAck = toAck.filter((id) => !ids.includes(id)); },
+  };
+}
+
+/** A row-derived id stable enough to survive a duplicate promotion attempt
+ *  without filing twice - the same reservation trick `lateReplyRequestId`
+ *  uses for a reply FILE (hash the thing that names it), spelled for a row
+ *  instead of a filename. Messages carry no id of their own from
+ *  collect_session's text reply, so their tag is a hash of who sent it and
+ *  what it said; two identical messages from the same sender promote to the
+ *  same request, which is the same content-addressed behaviour a repeated
+ *  reply FILE already has under `lateReplyRequestId`. */
+export const lateRowRequestId = (requestId, tag) =>
+  `spawn-reply-${createHash("sha256").update(`${requestId} ${tag}`).digest("hex")}`;
+
+/** After the child has exited, ONE more collect_session call - the row
+ *  equivalent of `promoteLateReplies` sweeping a `.reply-*.json` written
+ *  after stdin closed. A late ANSWER or MESSAGE for a PERSISTENT session
+ *  becomes a resume request through the exact function a late reply file
+ *  already uses (`promoteReplyToRequest`, fed a row instead of a file) -
+ *  the worktree, the resume session id, and "was this ever approved" are
+ *  all its, unchanged; it already refuses (returns null) for a one-shot
+ *  session via its own `acceptsMessages` check, which is what makes "log
+ *  and drop, same as today" the natural result of calling it here too
+ *  rather than a second branch to keep in sync with the first.
+ *
+ *  KNOWN GAP, spelled out rather than hidden: a MESSAGE that arrived WHILE
+ *  the child was still running, in the same poll tick the child happened to
+ *  exit on, is marked delivered server-side by that poll (collect_session's
+ *  own `takeMessages` stamps `delivered_at` on fetch, not on successful
+ *  delivery to a pipe) whether or not `sendToChild` actually got to write
+ *  it - `child.mjs`'s `watchAnswers` breaks out of its delivery loop the
+ *  moment the child is settled, before calling `onDelivered`. Such a
+ *  message will not be seen again by THIS poll (it is no longer
+ *  undelivered on the server) or by this sweep (it is not "late" - it was
+ *  already fetched). It is the one situation this design does not recover,
+ *  and it is symmetric with why a message needs no in-memory delivered set
+ *  at all: the same field that makes redelivery impossible also makes this
+ *  one narrow race unrecoverable. An ANSWERED QUESTION has no such gap - it
+ *  carries no delivered_at, so it is simply asked for again next time,
+ *  here or on the next live poll. */
+export async function promoteLateRows(
+  root,
+  id,
+  // `promote` has no default: the only caller left, `runnerCompletion.mjs`,
+  // always passes `runnerApi.resume` (item 6 of brief 30 Move 2b) - there is
+  // no file-based request to fall back to promoting any more
+  // (`lateReplies.mjs`, deleted the same pass).
+  { poller, callTool = hostedCallTool, sessionKey, env, promote } = {},
+  log = () => {},
+) {
+  // THE LAST ACKS GO WITH THE SWEEP (item 75): what the child took is
+  // stamped here, and what comes back is what never reached it.
+  const acking = poller.pendingAcks?.() ?? [];
+  const collected = await pollCollectSession({ callTool, sessionKey, since: poller.since(), env, log, delivered: acking });
+  if (!collected.ok) return { filed: [], dropped: [] };
+  poller.acked?.(acking);
+  const late = [];
+  for (const a of collected.answered) {
+    if (poller.hasDelivered(a.id)) continue;
+    late.push({ tag: `q:${a.id}`, text: formatAnswer(a) });
+  }
+  for (const m of collected.messages) {
+    const hash = createHash("sha256").update(`${m.from} ${m.text}`).digest("hex").slice(0, 16);
+    const delivery = deliverable(m, collected.messages.length === 1 ? collected.images : []);
+    late.push({ tag: `m:${hash}`, text: delivery.text, images: delivery.images, message: { from: m.from, text: m.text } });
+  }
+  const filed = [];
+  // The messages no run will carry (item 75): completion records them on
+  // the sidecar so the card can say "did not reach the session".
+  const dropped = [];
+  for (const item of late) {
+    const promotionId = lateRowRequestId(id, item.tag);
+    const newId = await promote(root, id, { text: item.text, attributed: item.text, images: item.images }, log, promotionId);
+    if (newId) {
+      filed.push(newId);
+      log(`[${id}] a late row (${item.tag}) arrived after the session ended; filed ${newId} to continue it`);
+    } else {
+      if (item.message) dropped.push(item.message);
+      log(`[${id}] a late row (${item.tag}) arrived after a one-shot session ended; logged and dropped`);
+    }
+  }
+  return { filed, dropped };
+}

package/lib/rowsEvents.mjs

@@ -0,0 +1,86 @@
+// Live transcript chunks are authoritative. Sends are serialized, and a
+// failed batch retains its sequence number: board-runner upserts on
+// (run_id, seq), so retrying after a lost HTTP response cannot duplicate it.
+import { createHash } from "node:crypto";
+
+/** Stream a run's log to hosted rows. tick() is safe to call without awaiting
+ * it; settle() closes input and drains all earlier sends before returning.
+ * Failed events remain queued for the next tick or settlement retry. */
+export function makeRowEventStreamer({ send, log = () => {} } = {}) {
+  let seq = 0;
+  let pending = "";
+  let closed = false;
+  let received = 0;
+  const streamedHash = createHash("sha256");
+  const queue = [];
+  let inFlight = null;
+  let settlement = null;
+
+  const enqueue = (kind, text) => {
+    if (text !== "") queue.push({ seq: ++seq, kind, text });
+  };
+  const flushPending = () => {
+    enqueue("log", pending);
+    pending = "";
+  };
+  const drain = () => {
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+      while (queue.length > 0) {
+        const row = queue[0];
+        try {
+          const outcome = await send([row]);
+          if (!outcome.ok) throw new Error(outcome.error ?? "unknown error");
+        } catch (error) {
+          log(`events flush failed (seq ${row.seq}): ${error?.message ?? error}`);
+          return false;
+        }
+        queue.shift();
+      }
+      return true;
+    })().finally(() => { inFlight = null; });
+    return inFlight;
+  };
+
+  return {
+    onChunk(chunk) {
+      if (closed) return;
+      pending += chunk;
+      received += chunk.length;
+      streamedHash.update(chunk);
+    },
+    async tick() {
+      if (closed) return;
+      flushPending();
+      return drain();
+    },
+    settle(finalText, { dropped = 0 } = {}) {
+      if (settlement) return settlement;
+      if (!closed) {
+        closed = true;
+        flushPending();
+        const text = finalText ?? "";
+        // A capped ring or a retry receipt can rewrite the final text. It
+        // cannot be indexed by a live-stream offset. Only append a suffix
+        // when the final view has the exact streamed prefix; otherwise the
+        // live chunks already carry the transcript without those wrappers.
+        if (received === 0) enqueue("log", text);
+        else if (dropped === 0 && text.length > received &&
+          createHash("sha256").update(text.slice(0, received)).digest("hex") === streamedHash.digest("hex")) {
+          enqueue("log", text.slice(received));
+        }
+        if (dropped > 0) enqueue("cut", `[The local log summary elided ${dropped} characters; the streamed transcript is retained above.]`);
+      }
+      settlement = (async () => {
+        // An earlier drain may already have observed an empty queue before
+        // its promise settled; run a fresh drain for the closing rows too.
+        if (inFlight) await inFlight;
+        let ok = await drain();
+        // Retry once at exit, using the same immutable rows and sequence ids.
+        if (!ok) ok = await drain();
+        return { ok };
+      })().finally(() => { settlement = null; });
+      return settlement;
+    },
+  };
+}

package/lib/run-engine.mjs

@@ -0,0 +1,16 @@
+// RunEngine is the boundary shared by every coding engine. The runner owns
+// approval, worktrees, receipts, and budgets; adapters own only their child
+// protocol and translate its events to the existing session-log contract.
+import { runChild, runStreamingChild } from "./child.mjs";
+import { runAcpChild } from "./acp.mjs";
+import { runCodexChild } from "./codex.mjs";
+
+/** @typedef {{run: Function, streaming: Function, acceptsMessages: boolean}} RunEngine */
+/** @type {Record<string, RunEngine>} */
+export const RUN_ENGINES = {
+  "stream-json": { run: runChild, streaming: runStreamingChild, acceptsMessages: true },
+  acp: { run: runAcpChild, streaming: runAcpChild, acceptsMessages: true },
+  "codex-app-server": { run: runCodexChild, streaming: runCodexChild, acceptsMessages: true },
+  process: { run: runChild, streaming: runChild, acceptsMessages: false },
+};
+export const runEngineFor = (spec) => RUN_ENGINES[spec.protocol ?? (spec.streamingArgs ? "stream-json" : "process")];

package/lib/runner-health.mjs

@@ -0,0 +1,57 @@
+// Local proof of a running process, separate from package.json on disk.
+// Written only after a successful hosted heartbeat. No credentials or content.
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { writeFileAtomic } from "./atomic.mjs";
+import { join } from "node:path";
+import { viewableHome } from "./registry.mjs";
+
+export function readRunnerHealth(env = process.env, name = "health") {
+  try { return JSON.parse(readFileSync(join(viewableHome(env), `${name}.json`), "utf8")); }
+  catch { return null; }
+}
+
+export async function writeRunnerHealth(value, env = process.env, name = "health") {
+  const home = viewableHome(env);
+  await mkdir(home, { recursive: true });
+  await writeFileAtomic(join(home, `${name}.json`), JSON.stringify(value), "utf8", { mode: 0o600 });
+}
+
+export function makeRunnerHealth({ env = process.env, version, now = Date.now, instance = randomUUID() } = {}) {
+  const startedAt = now();
+  const paths = {};
+  let pending = Promise.resolve();
+  return {
+    beat(path) {
+      paths[path] = now();
+      const value = { instance, startedAt, version, paths: { ...paths } };
+      pending = pending.catch(() => {}).then(() => writeRunnerHealth(value, env));
+      return pending;
+    },
+    mark() {
+      const proof = readRunnerHealth(env, "cli");
+      return proof && proof.version === version ? { cliVersion: version, setupId: proof.setupId } : {};
+    },
+  };
+}
+
+export async function waitForRunnerHealth({
+  env = process.env, version, after = 0, previousInstance, root,
+  read = () => readRunnerHealth(env), now = Date.now,
+  pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  timeoutMs = 45_000, requireStartedAfter = true,
+} = {}) {
+  const deadline = now() + timeoutMs;
+  do {
+    const health = read();
+    const beats = root ? [health?.paths?.[root]] : Object.values(health?.paths ?? {});
+    if (health?.version === version && health.instance && health.instance !== previousInstance &&
+        (!requireStartedAfter || health.startedAt >= after) && beats.some((at) => typeof at === "number" && at >= after && now() - at < 30_000)) {
+      return { ok: true, health };
+    }
+    if (now() >= deadline) break;
+    await pause(500);
+  } while (now() <= deadline);
+  return { ok: false, error: "No fresh connection from the installed version. Run viewable doctor, then try again. Folders and sign-in were kept." };
+}