beatrina 0.8.6 → 0.9.43

package/host/engine-js.mjs

@@ -4,11 +4,12 @@
 // can name. It speaks the wire worker.R and worker.py speak, so everything but
 // three answers is StdioEngine's:
 //
-//   · WHICH NODE. The host's own `process.execPath` when the host is a plain
-//     `node host/main.mjs` — the Node the R launcher already found and
-//     version-checked. A packaged single-executable host (node:sea) cannot run
-//     a script, so there the engine needs `BEATRIX_NODE` / `CARMAR_NODE`, and
-//     says so on the ready frame rather than appearing and failing.
+//   · WHICH NODE. The host's own `process.execPath` — the Node the R launcher
+//     already found and version-checked — or `BEATRIX_NODE`/`BEATRINA_NODE`
+//     when one is named. There is no self-hosted rung: the node:sea build that
+//     needed one is retired (f5979e5, 2026-09-16), and every distribution now
+//     stages `engines/js/` beside the host, so the worker is a script on disk
+//     in all three of them.
 //   · A CONSOLE LINE MEANS NOTHING. The worker reads commands only; there is
 //     no prompt, so canInput and canDebug are false and the plane refuses
 //     input_reply and debug_cmd for this engine by those capabilities.
@@ -18,6 +19,7 @@
 
 import fs from "node:fs";
 import { StdioEngine } from "./engine-stdio.mjs";
+import { mirrorEnv, readEnv } from "./env-names.mjs";
 import { findInterruptTool } from "./windows-runtime.mjs";
 
 export const JS_MIN_NODE = 22;
@@ -26,17 +28,12 @@ export const JS_MIN_NODE = 22;
  * Find a Node for the JavaScript engine, and SAY WHAT WAS DECIDED.
  * @returns {{available: boolean, path: string, version: string, detail: string}}
  */
-export function detectNode({ env = process.env, packaged = false, execPath = process.execPath, versions = process.versions } = {}) {
-  const explicit = env.BEATRIX_NODE || env.CARMAR_NODE || "";
+export function detectNode({ env = process.env, execPath = process.execPath, versions = process.versions } = {}) {
+  const explicit = env.BEATRIX_NODE || readEnv(env, "NODE");
   if (explicit) {
     if (!fs.existsSync(explicit)) return { available: false, path: "", version: "", detail: `BEATRIX_NODE points at ${explicit}, which does not exist.` };
     return { available: true, path: explicit, version: "", detail: `Node at ${explicit} (BEATRIX_NODE)` };
   }
-  if (packaged) {
-    // A single executable IS a Node: it runs the worker bundled inside it when
-    // started with BEATRIX_ENGINE_ROLE=js (the retired executable build; kept for any old binary).
-    return { available: true, path: execPath, version: versions.node, detail: `Node ${versions.node} (inside this executable)`, selfHosted: true };
-  }
   const major = Number(String(versions.node || "").split(".")[0]);
   if (!(major >= JS_MIN_NODE)) return { available: false, path: "", version: versions.node || "", detail: `JavaScript chunks need Node ${JS_MIN_NODE} or newer; this host runs on ${versions.node}.` };
   return { available: true, path: execPath, version: versions.node, detail: `Node ${versions.node}` };
@@ -51,10 +48,9 @@ export class JsEngine extends StdioEngine {
    * @param {Record<string,string>} [opts.env]
    * @param {string} [opts.cwd]
    */
-  constructor({ workerPath, node, env = {}, cwd, platform = process.platform, selfHosted = false } = {}) {
+  constructor({ workerPath, node, env = {}, cwd, platform = process.platform } = {}) {
     super({ language: "js", workerPath, env, cwd, platform });
-    this.selfHosted = selfHosted;
-    if (!selfHosted && (!workerPath || !fs.existsSync(workerPath))) throw new Error(`JsEngine: no worker at ${workerPath}`);
+    if (!workerPath || !fs.existsSync(workerPath)) throw new Error(`JsEngine: no worker at ${workerPath}`);
     if (!node) throw new Error("JsEngine: no Node found (set BEATRIX_NODE)");
     this.node = node;
     if (platform === "win32") this.interruptTool = findInterruptTool({ env: process.env });
@@ -69,8 +65,7 @@ export class JsEngine extends StdioEngine {
     // which Node still labels experimental and announces on stderr — into the
     // first chunk that imports anything. The label is Node's; the output is not
     // the user's, so it is not printed.
-    if (this.selfHosted) return { bin: this.node, args: [], env: { CARMAR_WORKER_MODE: "batch", BEATRIX_ENGINE_ROLE: "js" } };
-    return { bin: this.node, args: ["--disable-warning=ExperimentalWarning", this.workerPath], env: { CARMAR_WORKER_MODE: "batch" } };
+    return { bin: this.node, args: ["--disable-warning=ExperimentalWarning", this.workerPath], env: mirrorEnv({ BEATRINA_WORKER_MODE: "batch" }) };
   }
 
   /**
@@ -93,6 +88,10 @@ export class JsEngine extends StdioEngine {
     return true;
   }
 
+  /** process.kill, replaceable in tests. */
+  get killImpl() { return this._killImpl || process.kill.bind(process); }
+  set killImpl(fn) { this._killImpl = fn; }
+
   /** There is no prompt behind this worker: a console line is refused, not typed. */
   console() { throw new Error("The JavaScript engine has no console prompt."); }
 }

package/host/engine-pool.mjs

@@ -77,6 +77,7 @@ export class EnginePool extends EventEmitter {
       });
       plane.sockets = () => this.sockets();
       plane.on("broadcast", (payload) => this.emit("broadcast", payload));
+      plane.on("broadcast-pages", (payload) => this.emit("broadcast-pages", payload));
       this.planes.set(spec.name, plane);
     }
   }
@@ -329,7 +330,7 @@ export class EnginePool extends EventEmitter {
    * With no engine named it is the primary's — which is what "Restart R" in
    * the page means and what every existing client sends.
    */
-  async restart(engine) {
+  async restart(engine, opts = {}) {
     const key = engineKey(engine, this.primaryName);
     const plane = this.planes.get(key);
     if (!plane) return undefined;
@@ -338,19 +339,66 @@ export class EnginePool extends EventEmitter {
       const r = await this.ensure(key);
       return r.ok ? undefined : undefined;
     }
-    return plane.restart();
+    return plane.restart(key === this.primaryName ? opts : {});
+  }
+
+  /** "Restart, keep variables" belongs to the primary (R) engine. */
+  setResumePending(token) { this.primary?.setResumePending(token); }
+  freshResumeReport(now) { return this.primary ? this.primary.freshResumeReport(now) : null; }
+  cancelSuspend(rec) { return this.primary ? this.primary.cancelSuspend(rec) : false; }
+
+  /** Controls name the originating exec in `run`; `id` identifies the reply.
+   * Older pages omit `run`, so allow that only when this socket owns exactly
+   * one matching prompt. Never choose another page's or another run's engine.
+   *
+   * THE NARROWING IS IN STAGES, AND THAT IS THE POINT. The routing rule is one
+   * predicate — waiting, mine, the run named — but written as one `filter` it
+   * can only ever answer "no", and every refusal read alike: a debugger command
+   * sent when nothing is paused, an answer to a question another window is
+   * holding, and a reply naming a run that has already finished all came back
+   * as "This page has no matching run waiting for this control." Those are
+   * three different situations for the person reading the message and three
+   * different bugs for whoever is reading the log, so the list is narrowed a
+   * stage at a time and whichever stage empties it names the reason (S3,
+   * 2026-09-18). The routing itself is unchanged — the stages compose to the
+   * same predicate, and `test/engine-pool-controls.test.mjs` pins that across
+   * all seven ownership scenarios.
+   */
+  controlPlane(cmd, rec, state, type) {
+    const noun = type === "debug_cmd" ? "a debugger command" : "an answer";
+    // Stage 0: every engine actually waiting for this control, whoever it
+    // belongs to. The route is carried along because each later stage asks it
+    // a different question.
+    const waiting = [...this.planes.values()]
+      .map((plane) => ({ plane, route: plane.engine && plane[state] ? plane.routes.get(plane.active) : null }))
+      .filter((c) => c.route?.kind === "exec");
+    // Stage 1: the run this control names, if it names one. A queued run is
+    // correctly absent here — it is not waiting, it has not started.
+    const named = scalarChr(cmd.run) ? cmd.run : "";
+    const forRun = named ? waiting.filter((c) => c.route.clientId === named) : waiting;
+    // Stage 2: of those, the ones this socket started.
+    const candidates = forRun.filter((c) => c.route.rec === rec);
+    if (candidates.length === 1) return candidates[0].plane;
+
+    const error = candidates.length > 1
+      ? "More than one run is waiting; name the originating run in this control."
+      : forRun.length > 0
+        // It IS waiting — for somebody else. The distinction the reload path
+        // depends on: `adopt` is how the other page takes it over.
+        ? `That prompt is not this page's — another page owns the run waiting for ${noun}.`
+        : waiting.length > 0 && named
+          ? `The run named in this control is not waiting for ${noun}.`
+          : `This session is not waiting for ${noun}.`;
+    rec.ws.send(enc({ type, ...(scalarChr(cmd.id) ? { id: cmd.id } : {}), error }));
+    return null;
   }
 
   inputReply(cmd, rec) {
-    const waiting = [...this.planes.values()].find((p) => p.engine && p.inputWaiting);
-    if (waiting) return waiting.inputReply(cmd, rec);
-    return this.primary ? this.primary.inputReply(cmd, rec) : undefined;
+    return this.controlPlane(cmd, rec, "inputWaiting", "input_reply")?.inputReply(cmd, rec);
   }
 
   debugCmd(cmd, rec) {
-    const paused = [...this.planes.values()].find((p) => p.engine && p.debugPaused);
-    if (paused) return paused.debugCmd(cmd, rec);
-    return this.primary ? this.primary.debugCmd(cmd, rec) : undefined;
+    return this.controlPlane(cmd, rec, "debugPaused", "debug_cmd")?.debugCmd(cmd, rec);
   }
 
   runstate(cmd, rec) {

package/host/engine-python.mjs

@@ -18,42 +18,74 @@ import { execFile } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { StdioEngine } from "./engine-stdio.mjs";
+import { envSetName, readEnv } from "./env-names.mjs";
 import { findInterruptTool } from "./windows-runtime.mjs";
 
 /** How long a probe of a candidate interpreter may take before it is "no". */
 export const PROBE_TIMEOUT_MS = 6000;
 
 /** Python's own variables that would aim a child at a different install. */
-const STRIP_PY_ENV = /^(PYTHONHOME|PYTHONPATH|PYTHONSTARTUP|PYTHONEXECUTABLE)$/;
+export const STRIP_PY_ENV = /^(PYTHONHOME|PYTHONPATH|PYTHONSTARTUP|PYTHONEXECUTABLE)$/;
 
 const exists = (p) => Boolean(p) && fs.existsSync(p);
 
+/**
+ * The managed interpreter's home: `~/.beatrina/python`, a venv that
+ * `beatrina python setup` creates (tools/npm/bin/python-setup.mjs). No older
+ * home is searched: a venv is not relocatable and nobody was set up before this
+ * name, so a machine with an older folder runs `beatrina python setup` once.
+ */
+export const MANAGED_PYTHON_DIRS = Object.freeze([
+  { dir: [".beatrina", "python"], why: "the interpreter Beatrina manages (~/.beatrina/python)" },
+]);
+
+/** The interpreter inside a venv directory, by platform. */
+export function venvInterpreter(dir, platform = process.platform) {
+  return platform === "win32" ? path.win32.join(dir, "Scripts", "python.exe") : path.join(dir, "bin", "python3");
+}
+
+/** The venv directories a project keeps beside its documents, in the order they are tried. */
+export const PROJECT_VENV_DIRS = Object.freeze([".venv", "venv"]);
+
 /**
  * Every interpreter worth asking, in the order the answer is preferred, each
  * labelled with WHY it was considered. The label is what Doctor prints, so a
  * user who gets the wrong Python can see which rung chose it.
  *
- * `CARMAR_PYTHON` first (an explicit answer outranks a search), then the
- * environment the user is already inside — an active venv, then conda — then
- * pyenv's selected version, then PATH, then the usual installs. PATH is late
- * for the reason `detectRscript` puts it last: a Finder-launched process has
+ * `BEATRINA_PYTHON` first (an explicit answer outranks a search; the older
+ * spelling of the variable is accepted, host/env-names.mjs), then the
+ * interpreter Beatrina manages (`~/.beatrina/python`) — it outranks
+ * everything the user did not name because it is the one `beatrina python
+ * setup` built for exactly this — then the project's own venv (`.venv` or
+ * `venv` under `root`, the session's document directory), then the environment
+ * the user is already inside — an active venv, then conda — then pyenv's
+ * selected version, then PATH, then the usual installs. PATH is late for the
+ * reason `detectRscript` puts it last: a Finder-launched process has
  * `/usr/bin:/bin:/usr/sbin:/sbin` and would miss Homebrew, conda and pyenv
  * entirely, so a shell-launched and a Finder-launched session would silently
  * pick different interpreters.
  *
+ * @param {Record<string,string|undefined>} env
+ * @param {string} platform
+ * @param {{readdir: (p: string) => string[]}|null} io  Windows only: a fake fs for tests
+ * @param {{root?: string}} [opts] `root`: the directory whose `.venv`/`venv` is a candidate
  * @returns {Array<{path: string, why: string}>}
  */
-export function pythonCandidates(env = process.env, platform = process.platform, io = null) {
-  if (platform === "win32") return windowsPythonCandidates(env, io);
+export function pythonCandidates(env = process.env, platform = process.platform, io = null, { root = "" } = {}) {
+  if (platform === "win32") return windowsPythonCandidates(env, io, { root });
   const binName = "python3";
   const rungs = [];
   const add = (p, why) => { if (p && !rungs.some((r) => r.path === p)) rungs.push({ path: p, why }); };
-  if (env.CARMAR_PYTHON) add(env.CARMAR_PYTHON, "CARMAR_PYTHON");
-  // An interpreter Beatrix installed for itself. Nothing creates this yet —
-  // WP7 packages it — but the rung is here so that when something does, it
-  // outranks whatever happens to be on the user's PATH, which is the whole
-  // point of shipping one.
-  if (env.HOME) add(path.join(env.HOME, ".carmar", "python", "bin", binName), "the interpreter Beatrina manages");
+  const explicit = readEnv(env, "PYTHON");
+  if (explicit) add(explicit, envSetName(env, "PYTHON"));
+  if (env.HOME) {
+    for (const m of MANAGED_PYTHON_DIRS) add(venvInterpreter(path.join(env.HOME, ...m.dir), platform), m.why);
+  }
+  if (root) {
+    // The task's spelling is `.venv/bin/python`: a venv links python, python3
+    // and python3.X to the same file, so `python` is the name that is always there.
+    for (const d of PROJECT_VENV_DIRS) add(path.join(root, d, "bin", "python"), `the project's virtualenv (${path.join(root, d)})`);
+  }
   if (env.VIRTUAL_ENV) add(path.join(env.VIRTUAL_ENV, "bin", binName), "the active virtualenv (VIRTUAL_ENV)");
   if (env.CONDA_PREFIX) add(path.join(env.CONDA_PREFIX, "bin", binName), "the active conda environment (CONDA_PREFIX)");
   const pyenvRoot = env.PYENV_ROOT || (env.HOME ? path.join(env.HOME, ".pyenv") : "");
@@ -74,29 +106,36 @@ export function pythonCandidates(env = process.env, platform = process.platform,
 }
 
 /**
- * The Windows ladder. A venv keeps its interpreter in `Scripts\python.exe`,
- * conda at the prefix root, python.org's installer under
- * `%LOCALAPPDATA%\Programs\Python\Python3xx`; `python3.exe` on PATH is often
- * the Microsoft Store STUB, which opens the Store instead of running, so the
- * real installs come before PATH and the stub is skipped by name.
+ * The Windows ladder. A venv keeps its interpreter in `Scripts\python.exe` —
+ * the managed `%USERPROFILE%\.beatrina\python` and a project's `.venv` are
+ * venvs, so that is where they are looked for — conda at the prefix root, python.org's
+ * installer under `%LOCALAPPDATA%\Programs\Python\Python3xx`; `python3.exe` on
+ * PATH is often the Microsoft Store STUB, which opens the Store instead of
+ * running, so the real installs come before PATH and the stub is skipped by name.
  */
-export function windowsPythonCandidates(env = process.env, io = null) {
+export function windowsPythonCandidates(env = process.env, io = null, { root = "" } = {}) {
   const w = path.win32;
   const readdir = io ? io.readdir : (p) => { try { return fs.readdirSync(p); } catch { return []; } };
   const rungs = [];
   const add = (p, why) => { if (p && !rungs.some((r) => r.path === p)) rungs.push({ path: p, why }); };
-  if (env.CARMAR_PYTHON) add(env.CARMAR_PYTHON, "CARMAR_PYTHON");
-  if (env.USERPROFILE) add(w.join(env.USERPROFILE, ".carmar", "python", "python.exe"), "the interpreter Beatrina manages");
+  const explicit = readEnv(env, "PYTHON");
+  if (explicit) add(explicit, envSetName(env, "PYTHON"));
+  if (env.USERPROFILE) {
+    add(w.join(env.USERPROFILE, ".beatrina", "python", "Scripts", "python.exe"), MANAGED_PYTHON_DIRS[0].why);
+  }
+  if (root) {
+    for (const d of PROJECT_VENV_DIRS) add(w.join(root, d, "Scripts", "python.exe"), `the project's virtualenv (${w.join(root, d)})`);
+  }
   if (env.VIRTUAL_ENV) add(w.join(env.VIRTUAL_ENV, "Scripts", "python.exe"), "the active virtualenv (VIRTUAL_ENV)");
   if (env.CONDA_PREFIX) add(w.join(env.CONDA_PREFIX, "python.exe"), "the active conda environment (CONDA_PREFIX)");
   const versionOf = (d) => Number((String(d).match(/Python(\d+)/) || [0, 0])[1]);
-  for (const [root, why] of [
+  for (const [root_, why] of [
     [env.LOCALAPPDATA ? w.join(env.LOCALAPPDATA, "Programs", "Python") : "", "python.org installer (per user)"],
     [env.ProgramFiles || "", "python.org installer (all users)"],
   ]) {
-    if (!root) continue;
-    const dirs = readdir(root).filter((d) => /^Python3\d+/.test(d)).sort((a, b) => versionOf(b) - versionOf(a));
-    for (const d of dirs) add(w.join(root, d, "python.exe"), `${why} (${d})`);
+    if (!root_) continue;
+    const dirs = readdir(root_).filter((d) => /^Python3\d+/.test(d)).sort((a, b) => versionOf(b) - versionOf(a));
+    for (const d of dirs) add(w.join(root_, d, "python.exe"), `${why} (${d})`);
   }
   for (const dir of String(env.PATH || env.Path || "").split(";")) {
     if (!dir || /\\WindowsApps\\?$/i.test(dir)) continue;       // the Store stub
@@ -133,13 +172,18 @@ function probe(bin) {
  * reason it was considered and what it said — a user with three Pythons and
  * ipykernel in the wrong one can see that from the row.
  *
+ * @param {Record<string,string|undefined>} env
+ * @param {{root?: string}} [opts] `root`: the session's document directory,
+ *   whose `.venv`/`venv` is the project rung. Defaults to the working
+ *   directory, which is the project when `beatrina` is run from one; the host
+ *   passes the open document's directory when it knows it.
  * @returns {Promise<{available: boolean, path: string, version: string, why: string,
  *                    detail: string, searched: Array<object>}>}
  */
-export async function detectPython(env = process.env) {
+export async function detectPython(env = process.env, { root = process.cwd() } = {}) {
   const searched = [];
   let firstWorking = null;
-  for (const rung of pythonCandidates(env)) {
+  for (const rung of pythonCandidates(env, process.platform, null, { root })) {
     if (!exists(rung.path)) continue;
     const info = await probe(rung.path);
     if (!info) {
@@ -161,10 +205,15 @@ export async function detectPython(env = process.env) {
     return { available: true, ...firstWorking, detail: `Python ${firstWorking.version}`, searched };
   }
   const found = searched.filter((s) => s.version);
+  // The two phrases "but ipykernel is not" and "No Python interpreter" are
+  // read by tools/run-test-suite.mjs (--require-python): a suite that skips
+  // with this detail is a Python skip. Change them there too.
   const detail = found.length
     ? `Python is installed (${found.map((s) => `${s.version} at ${s.path}`).join("; ")}) but ipykernel is not. `
-      + "Install it with `python3 -m pip install ipykernel`, or point CARMAR_PYTHON at an interpreter that has it."
-    : "No Python interpreter was found. Set CARMAR_PYTHON to one, or install Python 3.";
+      + "Run `beatrina python setup` to create an interpreter Beatrina manages, install it with "
+      + "`python3 -m pip install ipykernel`, or point BEATRINA_PYTHON at an interpreter that has it."
+    : "No Python interpreter was found. Run `beatrina python setup` after installing Python 3 from "
+      + "https://www.python.org/downloads/, or set BEATRINA_PYTHON to an interpreter that has ipykernel.";
   return { available: false, path: "", version: "", why: "", detail, searched };
 }
 
@@ -182,7 +231,7 @@ export class PythonEngine extends StdioEngine {
     super({ language: "python", workerPath, env, cwd, platform });
     if (platform === "win32") this.interruptTool = findInterruptTool({ env: process.env });
     if (!workerPath || !fs.existsSync(workerPath)) throw new Error(`PythonEngine: no worker at ${workerPath}`);
-    if (!python) throw new Error("PythonEngine: no Python found (set CARMAR_PYTHON)");
+    if (!python) throw new Error("PythonEngine: no Python found (run `beatrina python setup`, or set BEATRINA_PYTHON)");
     this.python = python;
     this.kernelName = kernelName;
   }
@@ -212,7 +261,7 @@ export class PythonEngine extends StdioEngine {
     return {
       bin: this.python,
       args: [path.resolve(this.workerPath)],
-      env: { CARMAR_WORKER_MODE: "interactive", CARMAR_PYTHON_KERNEL: this.kernelName },
+      env: { BEATRINA_WORKER_MODE: "interactive", BEATRINA_PYTHON_KERNEL: this.kernelName },
     };
   }
 

package/host/engine-r.mjs

@@ -17,27 +17,21 @@
 // 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.
+// The re-exports this file used to carry for `LineFramer`, `MAX_CONSOLE_LINE`
+// and `workerEnvironment` are gone: the migration they eased finished, nothing
+// imported them from here, and the two suites that want the framer take it from
+// host/engine-stdio.mjs, its real home.
 
 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 { StdioEngine } from "./engine-stdio.mjs";
+import { mirrorEnv, readEnv } from "./env-names.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",
@@ -48,14 +42,18 @@ const KNOWN_RSCRIPT = [
 ];
 
 /**
- * Which R should host the session? An explicit `CARMAR_RSCRIPT`, then the
+ * Which R should host the session? An explicit `BEATRINA_RSCRIPT`
+ * (beatrina-names: keep-start — or the old `CARMAR_RSCRIPT`, named here on
+ * purpose: the rename rewrote the legacy spelling into the current one and
+ * left this sentence offering a variable as its own alternative.
+ * beatrina-names: keep-end), 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) {
+export function detectRscript(explicit = readEnv(process.env, "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);
@@ -82,6 +80,11 @@ export function detectRBinary(rscript) {
 }
 
 /** One R worker process. */
+/** readline's screen width for the interactive worker (see spawnPlan). */
+export const READLINE_COLUMNS = 100000;
+/** First on the boot line: give user code back the COLUMNS it started with (or none). */
+export const R_WIDTH_BOOT = 'local({ cols <- Sys.getenv("BEATRINA_USER_COLUMNS"); Sys.unsetenv("BEATRINA_USER_COLUMNS"); if (nzchar(cols)) Sys.setenv(COLUMNS = cols) else Sys.unsetenv("COLUMNS") }); ';
+
 export class REngine extends StdioEngine {
   /**
    * @param {Object} opts
@@ -103,14 +106,15 @@ export class REngine extends StdioEngine {
     // 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)");
+    if (!rscript) throw new Error("REngine: no Rscript found (set BEATRINA_RSCRIPT)");
     this.rscript = rscript;
+    this.userColumns = processEnv.COLUMNS == null ? "" : String(processEnv.COLUMNS);
     // 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
+    // BEATRINA_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.rBinary = readEnv(processEnv, "WIN_BATCH") === "1" ? "" : detectRterm(rscript, winIo);
       this.interruptTool = findInterruptTool({ env: processEnv, rscript, io: winIo });
     } else {
       this.rBinary = detectRBinary(rscript);
@@ -130,7 +134,7 @@ export class REngine extends StdioEngine {
 
   spawnPlan() {
     if (this.mode === "interactive" && this.platform === "win32") {
-      return { bin: this.rBinary, args: [...RTERM_INTERACTIVE_ARGS], env: { CARMAR_WORKER_MODE: "interactive" } };
+      return { bin: this.rBinary, args: [...RTERM_INTERACTIVE_ARGS], env: mirrorEnv({ BEATRINA_WORKER_MODE: "interactive" }) };
     }
     if (this.mode === "interactive") {
       return {
@@ -138,24 +142,26 @@ export class REngine extends StdioEngine {
         // --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" },
+        // COLUMNS is readline's screen width when there is no terminal. At the
+        // default 80, readline's horizontal scrolling redraws a long command
+        // line as "<" + its tail — which carries no cmdtag, so on Linux (R 4.3.3,
+        // `beatrina check`, 2026-09-16) fragments of the wire command leaked into
+        // chunk output. A width no line reaches keeps the echo whole, tag and
+        // all, and the scrub drops it. It is readline's width only: the boot
+        // line restores the user's COLUMNS before any user code (R_WIDTH_BOOT),
+        // and getOption("width") never read it. --no-readline was the first fix
+        // and is WRONG: without readline R reads the console with stdio fgets,
+        // and a Stop at an idle prompt left the stream in error — test:aicoding
+        // and test:sessionrecovery hung. test/r-echo.test.mjs pins both.
+        args: ["--interactive", "--no-echo", "--no-save", "--no-restore", "--no-site-file"],
+        // Both spellings on purpose (mirrorEnv): R_WIDTH_BOOT reads BEATRINA_USER_COLUMNS.
+        env: mirrorEnv({ BEATRINA_WORKER_MODE: "interactive", COLUMNS: String(READLINE_COLUMNS), BEATRINA_USER_COLUMNS: this.userColumns }),
       };
     }
     return {
       bin: this.rscript,
       args: ["--no-save", "--no-restore", "--no-site-file", this.workerPath, this.sentinel],
-      env: { CARMAR_WORKER_MODE: "batch" },
+      env: mirrorEnv({ BEATRINA_WORKER_MODE: "batch" }),
     };
   }
 
@@ -174,7 +180,7 @@ export class REngine extends StdioEngine {
     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)`);
+    this.rawLine(`${R_WIDTH_BOOT}${attach}sys.source(${JSON.stringify(worker)}, envir = globalenv(), keep.source = FALSE)`);
   }
 
   /** engines/r/handoff.R for this host, or "" when this build has none. */