beatrina 0.8.6

package/host/worker-plane.mjs

@@ -0,0 +1,713 @@
+// worker-plane.mjs — one evaluating engine behind a single-flight queue.
+//
+// The routing half of spike/serve.R, engine-neutral: everything here talks to
+// an ENGINE ADAPTER (host/engine-r.mjs is the first) and to socket RECORDS
+// (`rec.ws.send`), and evaluates nothing itself. Browser request ids are only
+// unique inside one tab, so every command gets a supervisor-owned wire id and
+// this table maps it back to the socket and id that originated it — isolation
+// is a server guarantee, not a client courtesy.
+//
+// Rules carried over from serve.R, each with the failure that put it there:
+//   · The engine is serial, so the plane owns one queue and one active slot.
+//   · Frames are RELAYED as the engine's own bytes, only the routing id
+//     rewritten (relay_frame): re-encoding rounded 1.2345e-05 to 0.
+//   · A terminal frame is HELD until the pipes are quiet, or the page settles
+//     the result before a trailing stderr line arrives.
+//   · A deadline is a property of the COMMAND CLASS: an unanswered `env` after
+//     120 s means a worker that will never answer; an unanswered `exec` after
+//     two hours means a model fit. Expiry fails that route and frees the slot;
+//     it never touches the engine.
+//   · Stop is a LADDER: the first re-send 60 ms after the group signal (libc
+//     drops the SIGINT R got while inside system()), then every 400 ms, five
+//     times, while the same run is still active. Every rung's signals leave
+//     from THIS process, guarded at the instant they are sent: a rung's
+//     spawned `kill` used to land after the run had settled and the next
+//     command was written, and that stray signal tore the command line R was
+//     reading (a session alive and silent — the 8-hour soak of 2026-09-16)
+//     or escaped the worker's handlers and ended R.
+//   · A command written to an idle worker is ACKNOWLEDGED (`ack`, a worker
+//     that declares `command_ack_v1`). One that is not acknowledged within
+//     COMMAND_ACK_MS never reached the worker's loop — the torn line above —
+//     and is failed with a sentence so the queue moves on; an exec has no
+//     other deadline, by design.
+//   · A dead engine is RESPAWNED on a bounded backoff (0.25 … 10 s, ten
+//     attempts); past that it is a terminal state the page is told about, and
+//     an explicit `restart` is the one door out of it.
+
+import { EventEmitter } from "node:events";
+
+export const WORKER_DEADLINE_FAST = 120;
+export const WORKER_DEADLINE_SLOW = 600;
+export const WORKER_DEADLINES = Object.freeze({
+  env: WORKER_DEADLINE_FAST, obj: WORKER_DEADLINE_FAST, struct: WORKER_DEADLINE_FAST,
+  packages: WORKER_DEADLINE_FAST, wd: WORKER_DEADLINE_FAST, parse: WORKER_DEADLINE_FAST,
+  complete: WORKER_DEADLINE_FAST, hover: WORKER_DEADLINE_FAST, help: WORKER_DEADLINE_FAST,
+  package_help: WORKER_DEADLINE_FAST, project_status: WORKER_DEADLINE_FAST, rm: WORKER_DEADLINE_FAST,
+  debug_breaks: WORKER_DEADLINE_FAST, files: WORKER_DEADLINE_FAST, mkdir: WORKER_DEADLINE_FAST,
+  renamepath: WORKER_DEADLINE_FAST, sniff: WORKER_DEADLINE_FAST,
+  view: WORKER_DEADLINE_SLOW, colstats: WORKER_DEADLINE_SLOW, import: WORKER_DEADLINE_SLOW,
+  format: WORKER_DEADLINE_SLOW, doctor: WORKER_DEADLINE_SLOW, readfile: WORKER_DEADLINE_SLOW,
+  writefile: WORKER_DEADLINE_SLOW, writefiles_atomic: WORKER_DEADLINE_SLOW,
+  copypath: WORKER_DEADLINE_SLOW, deletepath: WORKER_DEADLINE_SLOW, revealpath: WORKER_DEADLINE_SLOW,
+});
+export const INTERRUPT_LADDER_FIRST_MS = 60;
+export const INTERRUPT_LADDER_STEP_MS = 400;
+export const INTERRUPT_LADDER_MAX = 5;
+/** How long a command written to an idle worker may go unacknowledged. An idle
+ *  worker acks in milliseconds (a 300 KB command spilled to a file, ~30 ms);
+ *  the only thing this ever catches is a command the worker never received. */
+export const COMMAND_ACK_MS = 3000;
+export const ORPHAN_BUFFER_BYTES = 262144;
+const RESPAWN_DELAYS_S = [0.25, 0.5, 1, 2, 5, 10];
+/** How long after the last engine event a terminal frame is released. serve.R
+ *  waits one empty 50 ms poll; this is the same quiet window, event-driven. */
+const TERMINAL_QUIET_MS = 30;
+/** The step commands a paused run takes — lib/debugger.js's and lib/console.js's words. */
+export const DEBUG_ACTIONS = Object.freeze(["continue", "over", "into", "out", "where", "abort", "eval"]);
+
+const scalarChr = (x) => typeof x === "string" && x.length > 0;
+const enc = (obj) => JSON.stringify(obj);
+
+/**
+ * Serialise one engine frame for the browser WITHOUT re-encoding it.
+ * @param {object} e   a frame; `__raw` carries the engine's own bytes when it came from the engine
+ * @param {string|null} wireId
+ * @param {string|null} clientId
+ * @returns {string}
+ */
+export function relayFrame(e, wireId = null, clientId = null) {
+  const raw = e && e.__raw;
+  if (typeof raw === "string") {
+    if (wireId == null) return raw;
+    if (scalarChr(clientId)) {
+      const needle = `"id":${JSON.stringify(wireId)}`;
+      const at = raw.indexOf(needle);
+      if (at >= 0) return raw.slice(0, at) + `"id":${JSON.stringify(clientId)}` + raw.slice(at + needle.length);
+    }
+  }
+  const { __raw, ...plain } = e;
+  return enc(plain);
+}
+
+export class WorkerPlane extends EventEmitter {
+  /**
+   * @param {Object} opts
+   * @param {() => import("./engine-r.mjs").REngine} opts.engineFactory
+   * @param {(event: string, fields?: object) => void} [opts.audit]
+   * @param {number} [opts.deadlineScale]   tests need seconds, not minutes
+   * @param {number} [opts.respawnMax]
+   * @param {(hello: object) => object} [opts.decorateReady]  the host stamps protocol/build here
+   */
+  constructor({ engineFactory, name = "r", label = "R", audit = () => {}, deadlineScale = 1, respawnMax = 10, decorateReady = (x) => x }) {
+    super();
+    this.engineFactory = engineFactory;
+    // The engine this plane owns, and the word its sentences use. One plane
+    // per engine (docs/worker-protocol.md §6.2), so both are constants here.
+    this.name = name;
+    this.label = label;
+    this.audit = audit;
+    this.deadlineScale = deadlineScale;
+    this.respawnMax = respawnMax;
+    this.decorateReady = decorateReady;
+    this.engine = null;
+    this.routes = new Map();       // wireId → route
+    this.routeSeq = 0;
+    this.queue = [];
+    this.active = null;            // wireId
+    this.activeSince = null;
+    this.activeType = null;
+    this.terminal = null;          // {wireId, route, frame, timer}
+    this.running = new Set();      // exec wire ids in flight (the busy guard's evidence)
+    this.hello = null;             // the decorated ready payload, replayed to late pages
+    this.notice = null;            // a kept give-up notice
+    this.readyFrame = null;
+    this.workerWd = process.cwd();
+    this.debugPaused = false;
+    this.inputWaiting = false;
+    this.recovering = false;
+    this.gaveUp = false;
+    this.restartAttempts = 0;
+    this.restartAfter = 0;
+    this.forceStopAsked = false;
+    this.expectedExit = false;     // a stop/restart we asked for is not a crash
+    this.ladder = null;            // {wireId, at, count, step}
+    this.expectsAck = false;       // the ready frame declared command_ack_v1
+    this.acked = false;            // the active command reached the worker's loop
+    this.ackDue = null;            // when an unacknowledged active command is given up on
+    this.sockets = () => [];       // the host supplies the live roster
+    this.sweeper = setInterval(() => this.tick(), 100);
+    this.sweeper.unref();
+  }
+
+  get alive() { return Boolean(this.engine && this.engine.alive); }
+  get pid() { return this.engine ? this.engine.pid : null; }
+  get mode() { return this.engine ? this.engine.mode : "batch"; }
+  /** Can this engine answer a question while a cell runs? (readline, input()) */
+  get canInput() { return Boolean(this.engine && this.engine.canInput); }
+  /** Does it have a step debugger `debug_cmd` can drive? R yes, Python no. */
+  get canDebug() { return Boolean(this.engine && this.engine.canDebug); }
+  get language() { return this.engine ? this.engine.language : null; }
+
+  async start() {
+    this.expectedExit = false;
+    const engine = this.engineFactory();
+    this.engine = engine;
+    engine.on("event", (e) => { if (this.engine === engine) this.onEvent(e); });
+    engine.on("exit", (info) => { if (this.engine === engine) this.onExit(info); });
+    engine.on("spawn-error", (err) => {
+      this.audit("worker-spawn-error", { detail: err.message });
+    });
+    await engine.start();
+    return engine;
+  }
+
+  // ── routes ──────────────────────────────────────────────────────────────
+
+  route(cmd, rec, kind) {
+    this.routeSeq += 1;
+    const wireId = `wire-${this.routeSeq}`;
+    const route = { rec, clientId: cmd.id, kind, responseType: cmd.type, onReply: null,
+      buffer: [], bufferedBytes: 0, bufferTruncated: false, parked: null, parkedAt: null,
+      srcname: "", started: Date.now() };
+    this.routes.set(wireId, route);
+    return { cmd: { ...cmd, id: wireId }, wireId, route };
+  }
+
+  routeIsOrphan(route) {
+    if (!route) return true;
+    if (typeof route.onReply === "function") return false;
+    if (!route.rec) return true;
+    return !this.sockets().includes(route.rec);
+  }
+
+  /**
+   * Forget results nobody came back for (serve.R `sweep_parked_results`).
+   * Only under an explicit idle timeout: a retained session keeps a parked
+   * result for as long as it lives, but with a configured grace an abandoned
+   * route must not block the very policy the user chose — it held `running`
+   * open and the kernel never stopped.
+   */
+  sweepParked(lingerS) {
+    if (!(lingerS > 0)) return;
+    const now = Date.now();
+    for (const [wireId, route] of [...this.routes]) {
+      if (!route || route.parked == null) continue;
+      if (now - (route.parkedAt ?? now) >= lingerS * 1000) {
+        this.audit("result-forgotten", { srcname: route.srcname || "" });
+        this.dropRoute(wireId);
+      }
+    }
+  }
+
+  dropRoute(wireId) {
+    this.routes.delete(wireId);
+    this.running.delete(wireId);
+  }
+
+  deliver(route, frame) {
+    if (typeof route.onReply === "function") { try { route.onReply(frame); } catch { /* a continuation must not break the plane */ } }
+    else if (route.rec && route.rec.ws) route.rec.ws.send(enc(frame));
+  }
+
+  failRoutes(reason) {
+    for (const [wireId, route] of this.routes) {
+      const frame = route.kind === "exec"
+        ? { type: "done", id: route.clientId, status: "error", message: reason }
+        : { type: route.responseType, id: route.clientId, error: reason };
+      this.deliver(route, frame);
+      this.dropRoute(wireId);
+    }
+  }
+
+  // ── the queue ───────────────────────────────────────────────────────────
+
+  enqueue(cmd, wireId) {
+    this.queue.push({ cmd, wireId });
+    this.dispatch();
+  }
+
+  dispatch() {
+    if (this.active !== null || !this.queue.length) return;
+    const item = this.queue.shift();
+    this.active = item.wireId;
+    this.activeSince = Date.now();     // the deadline clock starts at the WRITE
+    this.activeType = scalarChr(item.cmd.type) ? item.cmd.type : "";
+    let failed = null;
+    try { this.engine.send(item.cmd); } catch (e) { failed = e.message; }
+    this.acked = false;
+    this.ackDue = !failed && this.expectsAck ? Date.now() + COMMAND_ACK_MS : null;
+    if (failed) {
+      const route = this.routes.get(item.wireId);
+      if (route) {
+        this.deliver(route, route.kind === "exec"
+          ? { type: "done", id: route.clientId, status: "error", message: failed }
+          : { type: item.cmd.type, id: route.clientId, error: failed });
+      }
+      this.dropRoute(item.wireId);
+      this.releaseSlot();
+      this.dispatch();
+    }
+  }
+
+  releaseSlot() {
+    if (this.active && typeof this.engine?.clearStop === "function") this.engine.clearStop(this.active);
+    this.active = null;
+    this.activeSince = null;
+    this.activeType = null;
+    this.acked = false;
+    this.ackDue = null;
+  }
+
+  // ── what a page may ask ─────────────────────────────────────────────────
+
+  exec(cmd, rec) {
+    if (!scalarChr(cmd.id) || typeof cmd.source !== "string") return;
+    this.audit("exec", { id: cmd.id, bytes: Buffer.byteLength(cmd.source) });
+    const routed = this.route(cmd, rec, "exec");
+    routed.route.srcname = scalarChr(cmd.srcname) ? cmd.srcname : "";
+    this.running.add(routed.wireId);
+    this.enqueue(routed.cmd, routed.wireId);
+  }
+
+  request(cmd, rec) {
+    if (!scalarChr(cmd.id)) return;
+    this.audit(cmd.type, { id: cmd.id });
+    const routed = this.route(cmd, rec, "request");
+    this.enqueue(routed.cmd, routed.wireId);
+  }
+
+  /** A command the HOST asks on its own behalf; the reply goes to `onReply`. */
+  internal(cmd, onReply) {
+    this.routeSeq += 1;
+    const wireId = `wire-${this.routeSeq}`;
+    this.routes.set(wireId, { rec: null, clientId: wireId, kind: "request", responseType: cmd.type,
+      onReply, buffer: [], bufferedBytes: 0, srcname: "", started: Date.now() });
+    this.enqueue({ ...cmd, id: wireId }, wireId);
+  }
+
+  interrupt(cmd, rec) {
+    this.audit("interrupt", { id: cmd.id || "" });
+    if (scalarChr(cmd.id)) {
+      const hit = [...this.routes].find(([, r]) => r.rec === rec && r.clientId === cmd.id && r.kind === "exec");
+      if (!hit) return;
+      const [wireId] = hit;
+      if (wireId === this.active) {
+        this.startLadder(wireId);
+        return;
+      }
+      // Queued: released where it stands, without signalling the engine.
+      this.queue = this.queue.filter((item) => item.wireId !== wireId);
+      rec.ws.send(enc({ type: "done", id: cmd.id, status: "interrupted", message: "Execution interrupted" }));
+      this.dropRoute(wireId);
+      return;
+    }
+    // An older bundle's id-less Stop: the active run, with its flag written first —
+    // the worker treats a signal that carries no flag as one meant for a run
+    // that has ended, and resumes.
+    if (this.active && typeof this.engine.requestStop === "function") this.engine.requestStop(this.active);
+    this.engine.interrupt();
+  }
+
+  forceStop(rec) {
+    this.audit("force-stop", { class: rec.class || "unknown" });
+    this.forceStopAsked = true;
+    if (this.alive) this.engine.kill();
+  }
+
+  async restart() {
+    this.audit("restart", {});
+    this.failRoutes(`${this.label} was restarted — this request was abandoned.`);
+    this.expectedExit = true;
+    if (this.engine) await this.engine.stop(1000);
+    this.resetSession();
+    this.hello = null;
+    this.recovering = false;
+    this.restartAttempts = 0;
+    this.gaveUp = false;
+    this.notice = null;
+    await this.start();
+  }
+
+  resetSession() {
+    this.running.clear();
+    this.routes.clear();
+    this.queue = [];
+    this.releaseSlot();
+    if (this.terminal) clearTimeout(this.terminal.timer);
+    this.terminal = null;
+    this.debugPaused = false;
+    this.inputWaiting = false;
+    this.clearLadder();
+  }
+
+  runstate(cmd, rec) {
+    if (!scalarChr(cmd.id)) return;
+    const runId = scalarChr(cmd.run) ? cmd.run : "";
+    let alive = Boolean(runId) && [...this.routes.values()].some((r) => r.kind === "exec" && r.clientId === runId && r.rec === rec);
+    if (!alive && this.terminal) {
+      const held = this.terminal.route;
+      alive = Boolean(held) && held.clientId === runId && held.rec === rec;
+    }
+    rec.ws.send(enc({ type: "runstate", id: cmd.id, run: runId, running: alive }));
+  }
+
+  runs(cmd, rec) {
+    if (!scalarChr(cmd.id)) return;
+    const rows = [...this.routes.values()].filter((r) => r.kind === "exec").map((r) => ({
+      run: r.clientId || "", srcname: r.srcname || "", mine: r.rec === rec,
+      orphan: this.routeIsOrphan(r), finished: r.parked != null,
+      seconds: Math.round((Date.now() - r.started) / 100) / 10,
+    }));
+    rec.ws.send(enc({ type: "runs", id: cmd.id, runs: rows }));
+  }
+
+  /** Does this socket have a run by this page-side id here? The pool's router
+   *  asks every plane this before it forwards a control op — a page never has
+   *  to name an engine on Stop, input or a debugger step
+   *  (docs/worker-protocol.md §6.3). */
+  ownsRun(rec, clientId) {
+    if (!scalarChr(clientId)) return false;
+    for (const route of this.routes.values()) {
+      if (route.kind === "exec" && route.rec === rec && route.clientId === clientId) return true;
+    }
+    if (this.terminal && this.terminal.route && this.terminal.route.kind === "exec"
+      && this.terminal.route.rec === rec && this.terminal.route.clientId === clientId) return true;
+    return false;
+  }
+
+  /** Is there an orphaned run here with this srcname? Asked before `adopt`,
+   *  because `adopt` answers a miss with a refusal frame and only ONE plane
+   *  may do that. */
+  hasAdoptable(srcname) {
+    if (!scalarChr(srcname)) return false;
+    return [...this.routes.values()].some((r) => r.kind === "exec"
+      && (r.srcname || "") === srcname && this.routeIsOrphan(r));
+  }
+
+  /** The exec rows this plane is carrying, for a merged `runs` answer. */
+  runRows(rec) {
+    return [...this.routes.values()].filter((r) => r.kind === "exec").map((r) => ({
+      run: r.clientId || "", srcname: r.srcname || "", engine: this.name, mine: r.rec === rec,
+      orphan: this.routeIsOrphan(r), finished: r.parked != null,
+      seconds: Math.round((Date.now() - r.started) / 100) / 10,
+    }));
+  }
+
+  adopt(cmd, rec) {
+    if (!scalarChr(cmd.id) || !scalarChr(cmd.srcname)) return;
+    const refuse = (msg) => rec.ws.send(enc({ type: "done", id: cmd.id, status: "lost", message: msg }));
+    const hit = [...this.routes].find(([, r]) => r.kind === "exec" && (r.srcname || "") === cmd.srcname && this.routeIsOrphan(r));
+    if (!hit) return refuse("that run is no longer in this session.");
+    const [wireId, route] = hit;
+    route.rec = rec;
+    route.clientId = cmd.id;
+    this.audit("adopt", { srcname: cmd.srcname });
+    const buffered = route.buffer;
+    route.buffer = []; route.bufferedBytes = 0;
+    for (const frame of buffered) rec.ws.send(relayFrame({ ...frame, id: cmd.id }, wireId, cmd.id));
+    if (route.bufferTruncated) {
+      route.bufferTruncated = false;
+      rec.ws.send(enc({ type: "message", id: cmd.id, kind: "warning",
+        text: `Output printed while this notebook was closed exceeded ${Math.floor(ORPHAN_BUFFER_BYTES / 1024)} KB; the rest was dropped.` }));
+    }
+    if (route.parked) {
+      const parked = route.parked;
+      route.parked = null;
+      rec.ws.send(relayFrame({ ...parked, id: cmd.id }, wireId, cmd.id));
+      this.dropRoute(wireId);
+    }
+    return undefined;
+  }
+
+  /** A raw console line answering a readline(). Same gate as debug_cmd. */
+  inputReply(cmd, rec) {
+    const err = (msg) => { if (scalarChr(cmd.id)) rec.ws.send(enc({ type: "input_reply", id: cmd.id, error: msg })); };
+    if (!this.canInput) return err("this worker cannot read input");
+    if (!this.inputWaiting) return err(`${this.label} is not waiting for input`);
+    const route = this.active ? this.routes.get(this.active) : null;
+    if (!route || route.rec !== rec) return err("another page owns the waiting run");
+    const value = scalarChr(cmd.value) ? cmd.value : "";
+    if (/[\n\r]/.test(value) || value.length > 4000) return err("an answer must be a single line under 4000 characters");
+    this.audit("input_reply", { bytes: Buffer.byteLength(value) });
+    let sent = false;
+    try { this.engine.console(value); sent = true; } catch { sent = false; }
+    if (!sent) return err(`Beatrina could not deliver the answer to ${this.label}. The question is still open; try again.`);
+    this.inputWaiting = false;
+    return undefined;
+  }
+
+  debugCmd(cmd, rec) {
+    const err = (msg) => { if (scalarChr(cmd.id)) rec.ws.send(enc({ type: "debug_cmd", id: cmd.id, error: msg })); };
+    if (!this.canDebug) return err(`the ${this.label} engine has no debugger`);
+    if (!this.debugPaused) return err(`${this.label} is not paused in the debugger`);
+    const route = this.active ? this.routes.get(this.active) : null;
+    if (!route || route.rec !== rec) return err("another page owns the paused run");
+    const action = scalarChr(cmd.action) ? cmd.action : "";
+    // An engine whose debugger is not a console prompt takes the COMMAND, not
+    // a line spelled in R (engines/python/debugger.py). The gate above is the
+    // same for every engine; R has no such method and takes the lines below,
+    // unchanged.
+    if (typeof this.engine.debugCommand === "function") {
+      const expr = action === "eval" && scalarChr(cmd.expr) ? cmd.expr : null;
+      if (!DEBUG_ACTIONS.includes(action) || (action === "eval" && (expr == null || /[\n\r]/.test(expr) || expr.length > 4000))) {
+        return err("bad debug command");
+      }
+      this.audit("debug_cmd", { action });
+      try { this.engine.debugCommand(action, expr); } catch { /* the exit event reports it */ }
+      return undefined;
+    }
+    const line = { continue: "c", over: "n", into: "s", out: "f", where: ".carmar_debug_where()",
+      abort: 'invokeRestart("carmar_abort_cell")', eval: scalarChr(cmd.expr) ? cmd.expr : null }[action] ?? null;
+    if (line == null || /[\n\r]/.test(line) || line.length > 4000) return err("bad debug command");
+    this.audit("debug_cmd", { action });
+    try { this.engine.console(line); } catch { /* the exit event reports it */ }
+    if (["over", "into", "out"].includes(action)) { try { this.engine.console(".carmar_debug_where()"); } catch { /* same */ } }
+    return undefined;
+  }
+
+  /** A socket closed: spend no engine time on commands nobody will receive. */
+  dropSocket(rec) {
+    const abandoned = this.queue.filter((item) => { const r = this.routes.get(item.wireId); return r && r.rec === rec; });
+    if (abandoned.length) {
+      this.queue = this.queue.filter((item) => !abandoned.includes(item));
+      abandoned.forEach((item) => this.dropRoute(item.wireId));
+    }
+  }
+
+  // ── engine events ───────────────────────────────────────────────────────
+
+  onEvent(e) {
+    if (this.terminal) {
+      clearTimeout(this.terminal.timer);
+      this.terminal.timer = setTimeout(() => this.settleTerminal(), TERMINAL_QUIET_MS);
+    }
+    if (e.type === "debug") this.debugPaused = true;
+    if (e.type === "done") this.debugPaused = false;
+    if ((e.type === "ready" || e.type === "done") && scalarChr(e.cwd)) this.workerWd = e.cwd;
+    if (e.type === "wd" && scalarChr(e.path)) this.workerWd = e.path;
+    if (e.type === "input_request") this.inputWaiting = true;
+    if (e.type === "input_done" || e.type === "done") this.inputWaiting = false;
+
+    // The worker's receipt for the active command: the plane's own bookkeeping,
+    // never a page's frame — a request route would otherwise take it as its reply.
+    if (e.type === "ack") {
+      if (scalarChr(e.id) && e.id === this.active) this.acked = true;
+      return;
+    }
+    const hadId = scalarChr(e.id);
+    const wireId = hadId ? e.id : (["stdout", "stderr", "debug"].includes(e.type) ? this.active : null);
+    const route = wireId != null ? this.routes.get(wireId) : null;
+    if (wireId != null && wireId === this.active) this.acked = true;   // any word from the run is receipt enough
+    if (route) {
+      const isTerminal = (route.kind === "request" && hadId) || e.type === "done"
+        || (route.kind === "exec" && hadId && e.error != null);
+      if (isTerminal) {
+        if (this.terminal) clearTimeout(this.terminal.timer);
+        this.terminal = { wireId, route, frame: e, timer: setTimeout(() => this.settleTerminal(), TERMINAL_QUIET_MS) };
+      } else {
+        // The page's id, ALWAYS — plain stdout/stderr carries no protocol id
+        // at all (it belongs to the run that owns the slot), and an id-bearing
+        // frame carries the WIRE id, which no page has ever heard of. relayFrame
+        // still prefers the engine's own bytes with only that id swapped; this
+        // object is what it falls back to, and it used to fall back to the wire
+        // id. The fallback is not hypothetical: an engine whose JSON writer
+        // spaces its colons takes it on every frame (measured with the Python
+        // engine, 2026-09-14 — the page dropped a whole chunk's output).
+        const addressed = { ...e, id: route.clientId };
+        if (route.kind === "exec") this.recordOutput(route, addressed);
+        if (!this.routeIsOrphan(route)) route.rec.ws.send(relayFrame(addressed, wireId, route.clientId));
+      }
+      return;
+    }
+    // Session-wide lifecycle frames have no owner and reach every socket.
+    if (e.type === "ready") {
+      this.readyFrame = e;
+      this.expectsAck = Array.isArray(e.features) && e.features.includes("command_ack_v1");
+      const { __raw, ...plain } = e;
+      const decorated = this.decorateReady(plain);
+      this.recovering = false;
+      this.restartAttempts = 0;
+      this.restartAfter = 0;
+      this.gaveUp = false;
+      this.notice = null;
+      this.audit("worker-ready", { pid: e.pid ?? null });
+      const payload = enc(decorated);
+      this.hello = payload;
+      this.emit("broadcast", payload);
+      this.emit("ready", decorated);
+      return;
+    }
+    this.emit("broadcast", relayFrame(e));
+  }
+
+  recordOutput(route, frame) {
+    const size = Buffer.byteLength(frame.__raw ?? frame.text ?? "");
+    if (route.bufferedBytes + size > ORPHAN_BUFFER_BYTES) { route.bufferTruncated = true; return; }
+    route.buffer.push(frame);
+    route.bufferedBytes += size;
+  }
+
+  settleTerminal() {
+    const terminal = this.terminal;
+    if (!terminal) return;
+    this.terminal = null;
+    const { wireId, route, frame } = terminal;
+    if (typeof route.onReply === "function") {
+      try { route.onReply(frame); } catch { /* a continuation must not break the plane */ }
+      this.dropRoute(wireId);
+    } else if (this.routeIsOrphan(route) && route.kind === "exec") {
+      route.parked = frame;
+      route.parkedAt = Date.now();
+      this.audit("result-parked", { srcname: route.srcname || "" });
+    } else {
+      route.rec.ws.send(relayFrame({ ...frame, id: route.clientId }, wireId, route.clientId));
+      this.dropRoute(wireId);
+    }
+    if (this.active === wireId) this.releaseSlot();
+    this.dispatch();
+  }
+
+  onExit() {
+    if (this.expectedExit) { this.expectedExit = false; return; }
+    this.recover();
+  }
+
+  recover() {
+    if (this.gaveUp) return;
+    if (!this.recovering) {
+      this.recovering = true;
+      this.restartAttempts = 0;
+      this.restartAfter = 0;
+      this.hello = null;
+      this.failRoutes(this.forceStopAsked
+        ? `${this.label} was force-stopped. Its variables and loaded packages are gone; Beatrina is starting a fresh ${this.label} session.`
+        : `The ${this.label} worker stopped unexpectedly. Its session state was lost; Beatrina is starting a fresh ${this.label} session.`);
+      this.resetSession();
+      const payload = enc({ type: "worker-died", engine: this.name, recovering: true, forced: this.forceStopAsked });
+      this.emit("broadcast", payload);
+      this.audit("worker-died", { recovering: true, forced: this.forceStopAsked });
+      this.forceStopAsked = false;
+    }
+    if (Date.now() < this.restartAfter) return;
+    if (this.restartAttempts >= this.respawnMax) {
+      this.gaveUp = true;
+      this.recovering = false;
+      const reason = `${this.label} would not start after ${this.restartAttempts} attempts. Beatrina is still running — the notebook, `
+        + `your text and Save all work — but nothing can be run until ${this.label} is fixed. A broken startup file or a moved `
+        + `installation is the usual cause; the kernel log beside this session has ${this.label}'s own message. Restart to try again.`;
+      this.audit("worker-gave-up", { attempt: this.restartAttempts });
+      this.notice = enc({ type: "worker-died", engine: this.name, recovering: false, terminal: true, attempts: this.restartAttempts, message: reason });
+      this.emit("broadcast", this.notice);
+      return;
+    }
+    this.restartAttempts += 1;
+    const attempt = this.restartAttempts;
+    this.restartAfter = Date.now() + RESPAWN_DELAYS_S[Math.min(attempt, 6) - 1] * 1000;
+    let started = null;
+    try { started = this.start(); } catch (e) { this.audit("worker-respawn-failed", { attempt, detail: e.message }); }
+    if (!started) return;
+    this.audit("worker-respawn", { attempt });
+    this.emit("broadcast", enc({ type: "worker-restarting", engine: this.name, attempt }));
+  }
+
+  // ── the per-turn sweeps ─────────────────────────────────────────────────
+
+  tick() {
+    this.ackCheck();
+    this.deadlineCheck();
+    if (this.engine && !this.engine.alive && this.recovering && !this.gaveUp) this.recover();
+  }
+
+  /**
+   * The ladder runs on its OWN timers, not the 100 ms sweep: the first re-send
+   * must land 60 ms after the group signal, because when that signal ends a
+   * child under system() libc has thrown away the SIGINT R got while waiting
+   * and R walks on to the next line — measured here, `system("sleep 30")`
+   * finished `ok` in 65 ms when the re-send waited for the sweep.
+   */
+  startLadder(wireId) {
+    this.clearLadder();
+    // The guard travels with the signal: a signal still in flight when this
+    // run ends must not reach the chunk the queue starts next.
+    const stillThisRun = () => wireId === this.active;
+    // The flag first: it is what stops R at the next expression when no signal can land (system()).
+    if (typeof this.engine.requestStop === "function") this.engine.requestStop(wireId);
+    this.engine.interrupt(stillThisRun);
+    let count = 1;
+    const again = () => {
+      if (wireId !== this.active || count >= INTERRUPT_LADDER_MAX) { this.ladder = null; return; }
+      count += 1;
+      this.audit("interrupt-again", { count });
+      this.engine.interrupt(stillThisRun);
+      this.ladder = { wireId, count, timer: setTimeout(again, INTERRUPT_LADDER_STEP_MS) };
+    };
+    this.ladder = { wireId, count, timer: setTimeout(again, INTERRUPT_LADDER_FIRST_MS) };
+  }
+
+  clearLadder() {
+    if (this.ladder && this.ladder.timer) clearTimeout(this.ladder.timer);
+    this.ladder = null;
+  }
+
+  /**
+   * A command the worker never received. The plane writes a command only to
+   * an idle worker, which acknowledges it within milliseconds; silence past
+   * COMMAND_ACK_MS means the line never reached the worker's loop — measured
+   * 2026-09-16: a Stop signal landing while R's console reader is half-way
+   * through a line loses that line, with R alive and its loop intact, and
+   * the exec behind it would otherwise wait forever. Failed with a sentence,
+   * the slot released, the queue moved on; the engine is untouched.
+   */
+  ackCheck() {
+    const wireId = this.active;
+    if (wireId == null || this.ackDue == null || this.acked) return;
+    if (this.inputWaiting || this.debugPaused || this.terminal) return;
+    if (Date.now() < this.ackDue) return;
+    const type = this.activeType || "";
+    const route = this.routes.get(wireId);
+    const reason = `${this.label} never received this command: Beatrina wrote it, but ${this.label} did not acknowledge it within `
+      + `${Math.round(COMMAND_ACK_MS / 1000)} seconds. A Stop signal that arrives while a command is being read can tear the line. `
+      + "Nothing ran and the session's variables are intact; run it again.";
+    this.audit("command-lost", { detail: type, id: wireId });
+    if (route) {
+      this.deliver(route, route.kind === "exec"
+        ? { type: "done", id: route.clientId, status: "error", message: reason }
+        : { type: route.responseType || type, id: route.clientId, error: reason });
+    }
+    this.dropRoute(wireId);
+    this.releaseSlot();
+    this.dispatch();
+  }
+
+  deadlineCheck() {
+    const wireId = this.active;
+    if (wireId == null || this.activeSince == null) return;
+    const type = this.activeType || "";
+    if (!type || !(type in WORKER_DEADLINES)) return;
+    // R is at a prompt: the slot is held by a question, not by a silence.
+    if (this.inputWaiting || this.debugPaused) return;
+    if (this.terminal) return;
+    const limit = WORKER_DEADLINES[type] * this.deadlineScale * 1000;
+    const waited = Date.now() - this.activeSince;
+    if (waited < limit) return;
+    const route = this.routes.get(wireId);
+    const reason = `${this.label} did not answer \`${type}\` within ${Math.round(limit / 1000)} seconds. The session and its `
+      + "variables are intact; only this request was abandoned. If it keeps happening, this Beatrina may be newer than the "
+      + `${this.label} session it is talking to — restart it.`;
+    this.audit("worker-deadline", { detail: type, id: wireId, bytes: Math.round(waited / 1000) });
+    if (route) {
+      this.deliver(route, route.kind === "exec"
+        ? { type: "done", id: route.clientId, status: "error", message: reason }
+        : { type: route.responseType || type, id: route.clientId, error: reason });
+    }
+    this.dropRoute(wireId);
+    this.releaseSlot();
+    this.dispatch();
+  }
+
+  async stop() {
+    clearInterval(this.sweeper);
+    this.expectedExit = true;
+    if (this.engine) await this.engine.stop();
+  }
+}