beatrina 0.8.6

package/host/engine-r.mjs

@@ -0,0 +1,206 @@
+// engine-r.mjs — the R engine: owns one `worker.R` process. Knows nothing
+// about HTTP, sockets or pages.
+//
+// This is spike/kernel.R in JavaScript, and the shape it exposes is the seam
+// the 2026-09-14 review asked for (docs/host-plan.md §9.5): the host talks to
+// an ENGINE ADAPTER — start / send / interrupt / console / stop / kill and a
+// stream of events — while the adapter owns the NATIVE transport underneath.
+// For R that transport is not "a frame on stdin" for everything: Stop is a
+// SIGINT to the worker's process group (a busy R does not read its stdin), and
+// the debugger's step commands and a `readline()` answer are RAW console
+// lines. Both survive here, behind the adapter, so "everything is a frame" is
+// true of the host and false of the wire, which is the honest split.
+//
+// WP4 moved the transport — the two tokens, the sentinel framing, the cmdfile
+// spill, the process group, the interrupt sequence — into host/engine-stdio.mjs,
+// because the Python engine needed every line of it. What is R's, and stays
+// here: finding an Rscript, the interactive `R` binary beside it, the batch
+// fallback, the `sys.source` boot line, the R_* environment strip, and the two
+// capabilities (R has a readline AND a debugger; Python has only the first).
+// `LineFramer`, `workerEnvironment` and `MAX_CONSOLE_LINE` are re-exported so
+// nothing that imported them from here has to move.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { LineFramer, MAX_CONSOLE_LINE, StdioEngine, engineEnvironment } from "./engine-stdio.mjs";
+import { RTERM_INTERACTIVE_ARGS, detectRterm, detectWindowsRscript, findInterruptTool } from "./windows-runtime.mjs";
+
+export { LineFramer, MAX_CONSOLE_LINE };
+
+/** The R_* variables a user's shell may carry that would aim R elsewhere. */
+const STRIP_R_ENV = /^R_(HOME|LIBS|LIBS_USER|LIBS_SITE|PROFILE|ENVIRON|DOC_DIR|INCLUDE_DIR|SHARE_DIR)$/;
+
+/** Kept for callers that built a worker environment by hand. */
+export function workerEnvironment({ sentinel, cmdtag, workerDir, extra = {}, base = process.env }) {
+  return engineEnvironment({
+    sentinel, cmdtag, workerDir, base, strip: STRIP_R_ENV,
+    extra: { CARMAR_WORKER_MODE: "interactive", ...extra },
+  });
+}
+
+const KNOWN_RSCRIPT = [
+  "/Library/Frameworks/R.framework/Versions/Current/Resources/bin/Rscript",
+  "/opt/homebrew/bin/Rscript",
+  "/usr/local/bin/Rscript",
+  "/opt/local/bin/Rscript",
+  "/usr/bin/Rscript",
+];
+
+/**
+ * Which R should host the session? An explicit `CARMAR_RSCRIPT`, then the
+ * macOS framework R, then PATH — PATH last on purpose: a Finder-launched
+ * process has `/usr/bin:/bin:/usr/sbin:/sbin` and would miss Homebrew, rig,
+ * conda and Posit entirely.
+ * @param {string} [explicit]
+ * @returns {string} path to an Rscript binary, or ""
+ */
+export function detectRscript(explicit = process.env.CARMAR_RSCRIPT || "", platform = process.platform) {
+  if (explicit && fs.existsSync(explicit)) return explicit;
+  // Windows R is not on PATH after a default install; its ladder is its own.
+  if (platform === "win32") return detectWindowsRscript(process.env);
+  for (const cand of KNOWN_RSCRIPT) if (fs.existsSync(cand)) return cand;
+  const versions = "/Library/Frameworks/R.framework/Versions";
+  if (fs.existsSync(versions)) {
+    const hits = fs.readdirSync(versions)
+      .map((v) => path.join(versions, v, "Resources/bin/Rscript"))
+      .filter((p) => fs.existsSync(p)).sort().reverse();
+    if (hits.length) return hits[0];
+  }
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    const cand = path.join(dir, process.platform === "win32" ? "Rscript.exe" : "Rscript");
+    if (dir && fs.existsSync(cand)) return cand;
+  }
+  return "";
+}
+
+/** The full R binary beside an Rscript — the interactive worker needs it. */
+export function detectRBinary(rscript) {
+  if (!rscript) return "";
+  const cand = path.join(path.dirname(rscript), process.platform === "win32" ? "R.exe" : "R");
+  return fs.existsSync(cand) ? cand : "";
+}
+
+/** One R worker process. */
+export class REngine extends StdioEngine {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.workerPath  spike/worker.R (or the boot shim beside it)
+   * @param {string} [opts.rscript]
+   * @param {Record<string,string>} [opts.env]  extra environment for the worker
+   * @param {string} [opts.cwd]
+   * @param {"batch"} [opts.mode]  force BATCH: `Rscript <script> <sentinel>`,
+   *   no interactive console and therefore no raw console channel at all. The
+   *   analysis child (spike/analyze.R) is spawned this way — exactly as
+   *   `kernel_start(..., interactive = FALSE)` spawns it in R — because it
+   *   must never be able to evaluate anything. Omitted, the mode is decided by
+   *   whether a full R binary sits beside Rscript, as before.
+   */
+  constructor({ workerPath, rscript = detectRscript(), env = {}, cwd, mode, platform = process.platform,
+    io = null, processEnv = process.env, handoffScript = null } = {}) {
+    super({ language: "r", workerPath, env, cwd, platform });
+    // share()/use() for R. The host passes the path from ITS root; a packaged
+    // binary has no module path to derive one from (host/main.mjs, moduleDir).
+    this.handoffPath = handoffScript;
+    if (!workerPath || !fs.existsSync(workerPath)) throw new Error(`REngine: no worker at ${workerPath}`);
+    if (!rscript) throw new Error("REngine: no Rscript found (set CARMAR_RSCRIPT)");
+    this.rscript = rscript;
+    // Windows: Rterm.exe --ess is the interactive worker (host/windows-runtime.mjs).
+    // CARMAR_WIN_BATCH=1 keeps the old batch worker, as an escape hatch should
+    // some R build refuse --ess with a piped stdin.
+    if (platform === "win32") {
+      const winIo = io || undefined;
+      this.rBinary = processEnv.CARMAR_WIN_BATCH === "1" ? "" : detectRterm(rscript, winIo);
+      this.interruptTool = findInterruptTool({ env: processEnv, rscript, io: winIo });
+    } else {
+      this.rBinary = detectRBinary(rscript);
+    }
+    // `mode: "batch"` is the analysis child (host/planes/analyze.mjs): it must
+    // never be interactive, because it never evaluates and has no debugger.
+    this.mode = mode === "batch" ? "batch" : (this.rBinary ? "interactive" : "batch");
+  }
+
+  get label() { return "R"; }
+  /** The analysis child never evaluates, so it never needs one. */
+  get usesStopFlag() { return !/analyze\.R$/.test(String(this.workerPath)); }
+  get stripEnv() { return STRIP_R_ENV; }
+  /** R's readline and R's browser() both ride the raw console line. */
+  get canInput() { return this.mode === "interactive"; }
+  get canDebug() { return this.mode === "interactive"; }
+
+  spawnPlan() {
+    if (this.mode === "interactive" && this.platform === "win32") {
+      return { bin: this.rBinary, args: [...RTERM_INTERACTIVE_ARGS], env: { CARMAR_WORKER_MODE: "interactive" } };
+    }
+    if (this.mode === "interactive") {
+      return {
+        bin: this.rBinary,
+        // --no-echo suppresses the "> " prompt; the echo it does not suppress
+        // is scrubbed by LineFramer through the cmdtag.
+        //
+        // --no-readline FIRST. With readline, R echoes every line it reads back
+        // on stdout — and on Linux (R 4.3.3, 2026-09-16) readline's horizontal
+        // scrolling redraws a long command line as "<" + its tail, which no
+        // longer carries the cmdtag, so the echo leaked into chunk output
+        // (`beatrina check` on .39 read it as "the line after Stop ran").
+        // R honours --no-readline only BEFORE --interactive: after it, the flag
+        // is ignored and capabilities("cledit") stays TRUE (measured on Linux
+        // R 4.3.3 and macOS R 4.5.2). Without readline R reads plain lines,
+        // echoes nothing, and readline()/browser() still read the console.
+        // test/r-echo.test.mjs pins both the order and the silence.
+        args: ["--no-readline", "--interactive", "--no-echo", "--no-save", "--no-restore", "--no-site-file"],
+        env: { CARMAR_WORKER_MODE: "interactive" },
+      };
+    }
+    return {
+      bin: this.rscript,
+      args: ["--no-save", "--no-restore", "--no-site-file", this.workerPath, this.sentinel],
+      env: { CARMAR_WORKER_MODE: "batch" },
+    };
+  }
+
+  afterSpawn() {
+    if (this.mode !== "interactive") return;
+    // The boot line replaces worker-boot.R: sys.source parses the ~3,000-line
+    // file in one pass instead of feeding it through the REPL reader.
+    const workerDir = path.dirname(path.resolve(this.workerPath));
+    const realWorker = path.join(workerDir, "worker.R");
+    const worker = fs.existsSync(realWorker) ? realWorker : path.resolve(this.workerPath);
+    // share()/use() (engines/r/handoff.R) ride the SAME line, attached before
+    // the worker starts, because sys.source(worker.R) never returns: its
+    // command loop is the rest of the process's life, so a second raw line
+    // would be read as a command. Absent file (an older package) → nothing.
+    const handoff = this.handoffScript();
+    const attach = handoff
+      ? `local({ e <- attach(NULL, name = "beatrix:handoff", warn.conflicts = FALSE); sys.source(${JSON.stringify(handoff)}, envir = e, keep.source = FALSE) }); `
+      : "";
+    this.rawLine(`${attach}sys.source(${JSON.stringify(worker)}, envir = globalenv(), keep.source = FALSE)`);
+  }
+
+  /** engines/r/handoff.R for this host, or "" when this build has none. */
+  handoffScript() {
+    let cand = this.handoffPath;
+    if (cand == null) {
+      const u = import.meta.url;
+      cand = typeof u === "string" && u.startsWith("file:") ? path.resolve(path.dirname(fileURLToPath(u)), "..", "engines", "r", "handoff.R") : "";
+    }
+    return cand && fs.existsSync(cand) ? cand : "";
+  }
+
+  /** One RAW console line: the debugger's channel, and a readline() answer. */
+  console(line) { return this.rawLine(line); }
+
+  /**
+   * Deliver one JSON command. The batch worker reads plain JSON lines off
+   * stdin and has no console to comment into, so the cmdtag and the cmdfile
+   * spill are the interactive path's only.
+   */
+  send(cmd) {
+    if (!cmd || typeof cmd.type !== "string") throw new Error("REngine.send: a command needs a string type");
+    if (this.mode !== "interactive") {
+      if (cmd.type === "exec") this.interruptRefusalSaid = false;
+      return this.write(`${JSON.stringify(cmd)}\n`);
+    }
+    return super.send(cmd);
+  }
+}

package/host/engine-stdio.mjs

@@ -0,0 +1,401 @@
+// engine-stdio.mjs — what every stdio engine shares, extracted from
+// host/engine-r.mjs when the Python engine arrived (WP4).
+//
+// The host talks to an ENGINE ADAPTER — start / send / console / interrupt /
+// stop / kill and a stream of events — and the adapter owns the NATIVE
+// transport underneath (docs/worker-protocol.md §1). R and Python turned out
+// to share the whole transport and to differ only in three answers:
+//
+//   · which binary, with which arguments, and what to say to it first
+//     (R's interactive worker is booted with a `sys.source(...)` console line;
+//     Python's worker is an ordinary script argument);
+//   · what a raw "console line" MEANS (R: the debugger and a readline answer;
+//     Python: there is no debugger, and an answer is a command);
+//   · whether this engine has a debugger at all.
+//
+// Everything else — the two tokens, the sentinel framing, the cmdfile spill,
+// the process group, the interrupt sequence, the stop ladder — is one body.
+// Subclasses override `spawnPlan()`, `afterSpawn()`, `console()` and the two
+// capability getters, and nothing else.
+//
+// Three rules carried over from spike/kernel.R, each with its measurement:
+//   · TWO tokens. The sentinel frames control lines FROM the worker; the
+//     cmdtag prefixes command lines TO it (`#<cmdtag> {json}` — a comment, so
+//     a line that ever reached a raw prompt is inert, and its echo is
+//     self-identifying). One token for both directions would let an echoed
+//     command parse as a frame from the worker.
+//   · The sentinel is found ANYWHERE in a line, not at its start: a cell
+//     ending in cat("done") with no newline leaves the cursor mid-line and the
+//     next frame lands glued to that text.
+//   · A command longer than 32,000 bytes travels through a 0600 temp file
+//     (`cmdfile`): R's interactive console reader wedges the whole process
+//     somewhere past 40,000 bytes, and the hang is a hang, not an error.
+//     Python has no such limit, but the spill costs nothing and one code path
+//     is worth more than a saved file write.
+
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { NO_INTERRUPT_TOOL, windowsInterruptPlan, windowsKillPlan } from "./windows-runtime.mjs";
+
+export const MAX_CONSOLE_LINE = 32000;
+/** The gap between the group SIGINT and the pid SIGINT: the measured lifetime of the spawned
+ *  `kill` that used to separate them (median 3.2 ms, p90 5.3 ms, 2026-09-16). */
+export const INTERRUPT_PAIR_GAP_MS = 5;
+
+export const token = () => {
+  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+  const bytes = crypto.randomBytes(24);
+  let out = "";
+  for (const b of bytes) out += alphabet[b % alphabet.length];
+  return out;
+};
+
+/**
+ * The child's environment: a UTF-8 LC_CTYPE guaranteed, a dumb terminal, and
+ * the worker's two tokens. `strip` removes variables a user's shell may carry
+ * that would aim the child at a different install of its own runtime.
+ */
+export function engineEnvironment({ sentinel, cmdtag, workerDir, extra = {}, base = process.env, strip = null }) {
+  const env = {};
+  for (const [k, v] of Object.entries(base)) {
+    if (strip && strip.test(k)) continue;
+    env[k] = v;
+  }
+  const utf8 = (x) => /utf-?8/i.test(String(x || ""));
+  const effective = env.LC_ALL || env.LC_CTYPE || env.LANG || "";
+  if (!utf8(effective)) {
+    if (env.LC_ALL && !utf8(env.LC_ALL)) delete env.LC_ALL;   // LC_ALL outranks LC_CTYPE
+    env.LC_CTYPE = "C.UTF-8";
+  }
+  Object.assign(env, extra);
+  // TERM=dumb: readline's terminal probe writes an escape sequence to stdout
+  // before anything else, and a dumb terminal keeps it out of the stream.
+  env.TERM = "dumb";
+  env.CARMAR_SENTINEL = sentinel;
+  env.CARMAR_CMD_TAG = cmdtag;
+  env.CARMAR_WORKER_DIR = workerDir;
+  return env;
+}
+
+/**
+ * Split a stream of worker bytes into events, exactly as kernel_poll does.
+ *
+ * Pure and incremental: feed it text, get back the events that are complete.
+ * Consecutive plain lines COALESCE into one event (a chunk printing 100k
+ * lines must not be 100k socket sends), a line carrying the sentinel is split
+ * into the user text before it and the frame, and a line carrying the cmdtag
+ * is our own command echoed back (kept only for the text before the tag).
+ */
+export class LineFramer {
+  constructor({ sentinel, cmdtag, channel }) {
+    this.sentinel = sentinel;
+    this.tag = cmdtag ? `#${cmdtag}` : null;
+    this.channel = channel;        // "stdout" | "stderr"
+    this.tail = "";
+  }
+  /** @returns {Array<object>} events */
+  feed(text, { flush = false } = {}) {
+    const data = this.tail + text;
+    const nl = data.lastIndexOf("\n");
+    let complete;
+    if (nl < 0) {
+      if (flush && data) { this.tail = ""; complete = data; }
+      else { this.tail = data; return []; }
+    } else {
+      complete = data.slice(0, nl);
+      this.tail = data.slice(nl + 1);
+      if (flush && this.tail) { complete += `\n${this.tail}`; this.tail = ""; }
+    }
+    const lines = complete.split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+    const events = [];
+    let plain = [];
+    const flushPlain = () => {
+      if (plain.length) { events.push({ type: this.channel, text: plain.join("\n") }); plain = []; }
+    };
+    for (let line of lines) {
+      if (this.tag) {
+        const at = line.indexOf(this.tag);
+        if (at >= 0) { line = line.slice(0, at); if (!line) continue; }
+      }
+      const at = line.indexOf(this.sentinel);
+      if (at < 0) { plain.push(line); continue; }
+      const prefix = line.slice(0, at);
+      const payload = line.slice(at + this.sentinel.length);
+      let parsed = null;
+      try { parsed = JSON.parse(payload); } catch { parsed = null; }
+      // A control frame must be a JSON OBJECT: an array or a bare scalar parses
+      // cleanly and is not a frame. Same answer a parse failure gets.
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { plain.push(line); continue; }
+      if (prefix) plain.push(prefix);
+      flushPlain();
+      events.push({ ...parsed, __raw: payload });
+    }
+    flushPlain();
+    return events;
+  }
+}
+
+/**
+ * One engine process, behind stdio.
+ *
+ * Events: `event` (one worker event: a frame with `__raw`, or `{type:"stdout"|
+ * "stderr", text}`), `exit` ({code, signal}), `spawn-error` (Error).
+ */
+export class StdioEngine extends EventEmitter {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.language       the engine key ("r", "python")
+   * @param {string} opts.workerPath     the file the runtime is pointed at
+   * @param {Record<string,string>} [opts.env]  extra environment for the worker
+   * @param {string} [opts.cwd]
+   */
+  constructor({ language, workerPath, env = {}, cwd, platform = process.platform } = {}) {
+    super();
+    // Both are instance state so a test can drive the Windows branches on any
+    // machine (test/windows-runtime.test.mjs); nothing else reassigns them.
+    this.platform = platform;
+    this.spawnImpl = spawn;
+    // Windows only: processx's interrupt.exe (host/windows-runtime.mjs). A
+    // subclass that knows where R's libraries are fills it in.
+    this.interruptTool = "";
+    this.interruptRefusalSaid = false;
+    this.language = language;
+    this.workerPath = workerPath;
+    this.extraEnv = env;
+    this.cwd = cwd;
+    this.mode = "interactive";
+    this.sentinel = token();
+    this.cmdtag = token();
+    this.proc = null;
+    this.alive = false;
+    this.pid = null;
+    this.spilled = new Set();
+    this.stopDir = null;
+  }
+
+  /**
+   * Does the worker read a stop flag between top-level expressions (CARMAR_STOP_DIR)? R's does
+   * (spike/worker.R `carmar_stop_requested`), because a signal cannot always reach R: libc's
+   * system() ignores SIGINT in R while its child runs, and whether the signal the host sends after
+   * the child dies lands before or after R walks on to the next line is a race — on Linux it lost
+   * every time (`beatrina check` on .39, 2026-09-16: 0/3 Stops of system("sleep 60")). The flag is
+   * read at the next expression boundary, so the line after the busy call never runs, on any OS.
+   */
+  get usesStopFlag() { return false; }
+
+  /** Ask the worker to stop the run `wireId` at its next expression boundary. */
+  requestStop(wireId) {
+    if (!this.stopDir || !/^[A-Za-z0-9_.:-]{1,120}$/.test(String(wireId))) return false;
+    try { fs.writeFileSync(path.join(this.stopDir, `stop-${wireId}`), "", { mode: 0o600 }); return true; } catch { return false; }
+  }
+
+  /** The run ended: its flag, if any, goes. */
+  clearStop(wireId) {
+    if (!this.stopDir || !/^[A-Za-z0-9_.:-]{1,120}$/.test(String(wireId))) return;
+    try { fs.unlinkSync(path.join(this.stopDir, `stop-${wireId}`)); } catch { /* none was written */ }
+  }
+
+  /** Can this engine answer a `readline()`-style question mid-run? */
+  get canInput() { return this.mode === "interactive"; }
+  /** Does it have a step debugger the page's `debug_cmd` can drive? */
+  get canDebug() { return false; }
+
+  /** Which environment variables the child must NOT inherit. */
+  get stripEnv() { return null; }
+
+  /**
+   * @abstract
+   * @returns {{bin: string, args: string[], env?: Record<string,string>}}
+   */
+  spawnPlan() { throw new Error("StdioEngine.spawnPlan: subclass must implement"); }
+
+  /** Anything to say to the child before the first command. */
+  afterSpawn() { /* most engines need nothing */ }
+
+  /** Spawn the worker. Resolves once the process exists (not once it is ready). */
+  start() {
+    const workerDir = path.dirname(path.resolve(this.workerPath));
+    const plan = this.spawnPlan();
+    // One private folder per worker for stop flags (0700; removed when the worker exits).
+    if (this.usesStopFlag && !this.stopDir) {
+      try { this.stopDir = fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-stop-")); fs.chmodSync(this.stopDir, 0o700); } catch { this.stopDir = null; }
+    }
+    const env = engineEnvironment({
+      sentinel: this.sentinel, cmdtag: this.cmdtag, workerDir,
+      extra: { ...this.extraEnv, ...(plan.env || {}), ...(this.stopDir ? { CARMAR_STOP_DIR: this.stopDir } : {}) }, strip: this.stripEnv,
+    });
+    // `detached`: the worker leads its OWN process group, so an interrupt can
+    // be sent to the group and reach a child under system() too — a terminal's
+    // ^C goes to the whole foreground group, and so does this.
+    // `windowsHide` (CREATE_NO_WINDOW) gives the worker a console of its OWN
+    // on Windows. That is what lets interrupt.exe attach to it and send Ctrl+C
+    // to the worker and its children without also reaching the host.
+    this.proc = this.spawnImpl(plan.bin, plan.args, {
+      cwd: this.cwd, env, stdio: ["pipe", "pipe", "pipe"],
+      detached: this.platform !== "win32",
+      windowsHide: true,
+    });
+    this.alive = true;
+    this.pid = this.proc.pid;
+    const out = new LineFramer({ sentinel: this.sentinel, cmdtag: this.cmdtag, channel: "stdout" });
+    const err = new LineFramer({ sentinel: this.sentinel, cmdtag: null, channel: "stderr" });
+    this.proc.stdout.setEncoding("utf8");
+    this.proc.stderr.setEncoding("utf8");
+    this.proc.stdout.on("data", (d) => out.feed(d).forEach((e) => this.emit("event", e)));
+    this.proc.stderr.on("data", (d) => err.feed(d).forEach((e) => this.emit("event", e)));
+    this.proc.stdin.on("error", () => { /* a dead worker's pipe: the exit event reports it */ });
+    this.proc.on("error", (e) => { this.alive = false; this.emit("spawn-error", e); });
+    this.proc.on("exit", (code, signal) => {
+      this.alive = false;
+      out.feed("", { flush: true }).forEach((e) => this.emit("event", e));
+      err.feed("", { flush: true }).forEach((e) => this.emit("event", e));
+      for (const f of this.spilled) { try { fs.unlinkSync(f); } catch { /* the worker took it */ } }
+      this.spilled.clear();
+      if (this.stopDir) { try { fs.rmSync(this.stopDir, { recursive: true, force: true }); } catch { /* gone */ } this.stopDir = null; }
+      this.emit("exit", { code, signal });
+    });
+    this.afterSpawn();
+    return Promise.resolve(this);
+  }
+
+  /** One RAW line on stdin, with no command framing. */
+  rawLine(line) {
+    if (/\n/.test(line)) throw new Error("StdioEngine.rawLine: one line, no newline");
+    return this.write(`${line}\n`);
+  }
+
+  /**
+   * The channel a `readline()` answer and a debugger step travel on. R's is a
+   * raw console line; an engine with no raw prompt overrides this.
+   */
+  console(line) { return this.rawLine(line); }
+
+  /** Deliver one JSON command, however it must travel. */
+  send(cmd) {
+    if (!cmd || typeof cmd.type !== "string") throw new Error("StdioEngine.send: a command needs a string type");
+    if (cmd.type === "exec") this.interruptRefusalSaid = false;
+    let json = JSON.stringify(cmd);
+    if (Buffer.byteLength(json) > MAX_CONSOLE_LINE) {
+      const spill = path.join(os.tmpdir(), `carmar-cmd-${crypto.randomBytes(8).toString("hex")}.json`);
+      fs.writeFileSync(spill, json, { mode: 0o600 });
+      this.spilled.add(spill);
+      json = JSON.stringify({ type: "cmdfile", path: spill });
+    }
+    return this.write(`#${this.cmdtag} ${json}\n`);
+  }
+
+  write(text) {
+    if (!this.alive || !this.proc || this.proc.stdin.destroyed) {
+      throw new Error(`${this.label} is not running — this command could not be sent.`);
+    }
+    this.proc.stdin.write(text);
+    return true;
+  }
+
+  /** The word this engine's sentences use. */
+  get label() { return this.language === "r" ? "R" : this.language; }
+
+  /**
+   * Interrupt whatever the worker is doing: SIGINT to the worker's process
+   * GROUP, then SIGINT to the worker itself INTERRUPT_PAIR_GAP_MS later.
+   *
+   * Both, in that order, because each alone fails on `system("sleep 60")` in
+   * R. libc's system() ignores SIGINT in the caller while the child runs, so
+   * the pid signal alone never lands (measured: 0/5, and the sleep is
+   * orphaned). The group signal ends the child, but the SIGINT R got while
+   * waiting was thrown away, so R walks on to the next line (measured: 1/5)
+   * — which is what the stop FLAG (requestStop) now settles: R reads it at
+   * the next expression boundary, so the pair's timing no longer decides
+   * whether the line after a system() call runs.
+   *
+   * Both signals are sent from THIS process, and each is guarded by
+   * `stillWanted` at the instant it is sent. Until 0.8.6 the group signal was
+   * a spawned `kill -INT -- -pid` (whose 3–6 ms lifetime placed the pid signal
+   * inside system()'s return window, before the flag existed) and only the
+   * pid signal was guarded — the group signal had already left with the
+   * child. A signal in flight when the run ends reaches the NEXT command the
+   * plane writes: measured with the plane's ladder (tools/beatrina rigs,
+   * 2026-09-16), one such signal 3 ms after the next command was written
+   * escaped every handler in the worker and ended R, and the 8-hour soak had
+   * lost a session to the same window. A `process.kill` from here is
+   * synchronous with the guard: nothing can be dispatched between the check
+   * and the delivery. test/interrupt-guard.test.mjs pins the guard on both
+   * signals; test/stop-wedge.test.mjs pins the worker against a stray signal
+   * that still arrives (it is in-process, but the worker cannot know that).
+   */
+  interrupt(stillWanted = () => true) {
+    if (!this.alive || !this.pid) return false;
+    const pid = this.pid;
+    if (this.platform === "win32") return this.interruptWindows(pid);
+    if (!stillWanted()) return false;
+    try { this.killImpl(-pid, "SIGINT"); } catch {
+      try { this.killImpl(pid, "SIGINT"); } catch { return false; }   // not a group leader after all
+    }
+    const later = setTimeout(() => {
+      if (!this.alive || this.pid !== pid || !stillWanted()) return;
+      try { this.killImpl(pid, "SIGINT"); } catch { /* gone */ }
+    }, INTERRUPT_PAIR_GAP_MS);
+    if (typeof later.unref === "function") later.unref();
+    return true;
+  }
+
+  /** process.kill, replaceable in tests (every signal this adapter sends goes through it). */
+  get killImpl() { return this._killImpl || process.kill.bind(process); }
+  set killImpl(fn) { this._killImpl = fn; }
+
+  /**
+   * Windows: a console Ctrl+C through processx's helper — never
+   * `proc.kill("SIGINT")`, which on Windows ends the process. With no helper
+   * the chunk is left running and the page is TOLD, once per run, rather than
+   * Stop quietly becoming Force Stop.
+   */
+  interruptWindows(pid) {
+    const plan = windowsInterruptPlan(pid, this.interruptTool);
+    if (!plan) {
+      if (!this.interruptRefusalSaid) {
+        this.interruptRefusalSaid = true;
+        this.emit("event", { type: "stderr", text: NO_INTERRUPT_TOOL });
+      }
+      return false;
+    }
+    try {
+      const child = this.spawnImpl(plan.bin, plan.args, { stdio: "ignore", windowsHide: true });
+      if (child && typeof child.on === "function") child.on("error", () => { /* the exit of the run reports it */ });
+    } catch { return false; }
+    return true;
+  }
+
+  /** Ask the worker to exit, then make sure it did. */
+  async stop(graceMs = 2000) {
+    if (!this.alive) return;
+    try { this.send({ type: "shutdown" }); } catch { /* already gone */ }
+    const gone = await this.exited(graceMs);
+    if (!gone) this.kill();
+  }
+
+  /** SIGKILL — Force Stop. The host's recovery loop starts a fresh session. */
+  kill() {
+    if (!this.alive || !this.pid) return;
+    try {
+      if (this.platform !== "win32") process.kill(-this.pid, "SIGKILL");
+      else {
+        // The tree, not the process: a system() child would outlive R.
+        const plan = windowsKillPlan(this.pid);
+        const child = this.spawnImpl(plan.bin, plan.args, { stdio: "ignore", windowsHide: true });
+        if (child && typeof child.on === "function") child.on("error", () => { try { this.proc.kill("SIGKILL"); } catch { /* gone */ } });
+      }
+    } catch { /* already gone */ }
+  }
+
+  exited(ms) {
+    if (!this.alive) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const t = setTimeout(() => resolve(false), ms);
+      this.once("exit", () => { clearTimeout(t); resolve(true); });
+    });
+  }
+}