beatrina 0.8.7 → 0.9.43

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);
@@ -85,7 +83,7 @@ export function detectRBinary(rscript) {
 /** 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("CARMAR_USER_COLUMNS"); Sys.unsetenv("CARMAR_USER_COLUMNS"); if (nzchar(cols)) Sys.setenv(COLUMNS = cols) else Sys.unsetenv("COLUMNS") }); ';
+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 {
   /**
@@ -108,15 +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);
@@ -136,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 {
@@ -156,13 +154,14 @@ export class REngine extends StdioEngine {
         // 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"],
-        env: { CARMAR_WORKER_MODE: "interactive", COLUMNS: String(READLINE_COLUMNS), CARMAR_USER_COLUMNS: this.userColumns },
+        // 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" }),
     };
   }
 

package/host/engine-stdio.mjs

@@ -40,6 +40,7 @@ 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";
+import { mirrorEnv } from "./env-names.mjs";
 
 export const MAX_CONSOLE_LINE = 32000;
 /** The gap between the group SIGINT and the pid SIGINT: the measured lifetime of the spawned
@@ -58,6 +59,11 @@ export const token = () => {
  * 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.
+ *
+ * Every `BEATRINA_*` variable goes out under its `CARMAR_*` spelling as well
+ * (host/env-names.mjs mirrorEnv): spike/worker.R, job-run.R and analyze.R are
+ * upstream code that reads the old names, and a user's own Python or Node may
+ * be older than this host.
  */
 export function engineEnvironment({ sentinel, cmdtag, workerDir, extra = {}, base = process.env, strip = null }) {
   const env = {};
@@ -75,10 +81,10 @@ export function engineEnvironment({ sentinel, cmdtag, workerDir, extra = {}, bas
   // 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;
+  env.BEATRINA_SENTINEL = sentinel;
+  env.BEATRINA_CMD_TAG = cmdtag;
+  env.BEATRINA_WORKER_DIR = workerDir;
+  return mirrorEnv(env);
 }
 
 /**
@@ -181,8 +187,8 @@ export class StdioEngine extends EventEmitter {
   }
 
   /**
-   * 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
+   * Does the worker read a stop flag between top-level expressions (BEATRINA_STOP_DIR)? R's does
+   * (spike/worker.R `beatrina_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
@@ -229,7 +235,7 @@ export class StdioEngine extends EventEmitter {
     }
     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,
+      extra: { ...this.extraEnv, ...(plan.env || {}), ...(this.stopDir ? { BEATRINA_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
@@ -253,8 +259,14 @@ export class StdioEngine extends EventEmitter {
     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) => {
+    // A failed spawn emits `error` and `close`, but no `exit`. Give the plane
+    // the same terminal event and cleanup in either case, exactly once.
+    let finished = false;
+    let spawned = false;
+    this.proc.once("spawn", () => { spawned = true; });
+    const finish = (code, signal) => {
+      if (finished) return;
+      finished = true;
       this.alive = false;
       out.feed("", { flush: true }).forEach((e) => this.emit("event", e));
       err.feed("", { flush: true }).forEach((e) => this.emit("event", e));
@@ -262,7 +274,20 @@ export class StdioEngine extends EventEmitter {
       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.proc.on("error", (e) => {
+      if (finished) return;
+      // ChildProcess also emits error when kill/send fails after a successful
+      // spawn. That says nothing about whether the worker has exited.
+      if (spawned) {
+        this.emit("event", { type: "stderr", text: `${this.label} process control failed: ${e.message}` });
+        return;
+      }
+      this.alive = false;
+      this.emit("spawn-error", e);
+      finish(null, null);
     });
+    this.proc.on("exit", finish);
     this.afterSpawn();
     return Promise.resolve(this);
   }
@@ -288,7 +313,7 @@ export class StdioEngine extends EventEmitter {
     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`);
+      const spill = path.join(os.tmpdir(), `beatrina-cmd-${crypto.randomBytes(8).toString("hex")}.json`);
       fs.writeFileSync(spill, json, { mode: 0o600 });
       this.spilled.add(spill);
       json = JSON.stringify({ type: "cmdfile", path: spill });

package/host/env-names.mjs

@@ -0,0 +1,148 @@
+// env-names.mjs — one place that knows the product's environment-variable names.
+// beatrina-names: keep-file — this module IS the reader of the older spelling.
+//
+// The product is Beatrina. Its environment variables are `BEATRINA_<NAME>`.
+// Every one of them was `CARMAR_<NAME>` until 2026-09-16, and that spelling is
+// still ACCEPTED — launchers, CI, the R package and users' shells set it — so
+// reading a variable means asking for both, new name first. Nothing in the
+// host reads `process.env.CARMAR_…` or `process.env.BEATRINA_…` directly;
+// it calls `readEnv(process.env, "PORT")` and gets whichever is set.
+//
+// Children (engines, jobs, the terminal, a spawned kernel under test) may be
+// older code that knows only the old name, so an environment handed to a child
+// is passed through `mirrorEnv()`, which sets each name under both prefixes.
+// When the last reader of `CARMAR_` is gone, `LEGACY_PREFIX` goes with it and
+// `mirrorEnv` becomes the identity.
+
+export const PREFIX = "BEATRINA_";
+export const LEGACY_PREFIX = "CARMAR_";
+
+/** The canonical variable name for a suffix: envName("PORT") → "BEATRINA_PORT". */
+export function envName(suffix) {
+  return PREFIX + suffix;
+}
+
+/** The names a reader accepts for a suffix, canonical first. */
+export function envNames(suffix) {
+  return [PREFIX + suffix, LEGACY_PREFIX + suffix];
+}
+
+/**
+ * Read a variable under either prefix, canonical first.
+ * @param {Record<string, string|undefined>} source usually process.env
+ * @param {string} suffix the name without its prefix, e.g. "RUNTIME_DIR"
+ * @param {string} unset what an absent variable reads as
+ * @returns {string}
+ */
+export function readEnv(source, suffix, unset = "") {
+  for (const name of envNames(suffix)) {
+    const v = valueOf(source, name);
+    if (v != null) return String(v);
+  }
+  return unset;
+}
+
+/** True when the variable is set under either prefix (even to ""). */
+export function hasEnv(source, suffix) {
+  return envNames(suffix).some((name) => valueOf(source, name) != null);
+}
+
+/**
+ * The spelling that is actually set, for a message that names a switch:
+ * `envSetName(env, "NO_TERMINAL")` is "CARMAR_NO_TERMINAL" on a launcher that
+ * still sets the old name and "BEATRINA_NO_TERMINAL" otherwise (also when
+ * neither is set — the canonical name is the one to document).
+ */
+export function envSetName(source, suffix) {
+  return envNames(suffix).find((name) => valueOf(source, name) != null) || envName(suffix);
+}
+
+/**
+ * Read a FULL variable name the way the host's `Sys.getenv`-style getters do:
+ * a name under either prefix is read under both (canonical first); any other
+ * name (`PATH`, `BEATRIX_APP_ID`, `ProgramData`) is read as it is. This is
+ * what lets every `env("CARMAR_PORT")` call site keep its spelling while a
+ * launcher that sets `BEATRINA_PORT` is honoured.
+ */
+export function readEnvName(source, name, unset = "") {
+  const suffix = suffixOf(name);
+  if (suffix != null) return readEnv(source, suffix, unset);
+  const v = valueOf(source, name);
+  return v == null ? unset : String(v);
+}
+
+/**
+ * A `(name, unset = "") => string` getter over `source`, dual-read (readEnvName).
+ * It carries `source` so that a helper handed the GETTER (the planes get one)
+ * can still see which spelling is really set: asked for `BEATRINA_X`, the
+ * getter answers from `CARMAR_X` too, which is right for a read and wrong for
+ * `envSetName`.
+ */
+export function envReader(source = process.env) {
+  const reader = (name, unset = "") => readEnvName(source, name, unset);
+  reader.source = source;
+  return reader;
+}
+
+/** Set a variable under BOTH prefixes on `target` (an environment object). */
+export function setEnv(target, suffix, value) {
+  for (const name of envNames(suffix)) target[name] = String(value);
+  return target;
+}
+
+/** Set a FULL name on `target`; a prefixed name is set under both prefixes. */
+export function setEnvName(target, name, value) {
+  const suffix = suffixOf(name);
+  if (suffix != null) return setEnv(target, suffix, value);
+  target[name] = String(value);
+  return target;
+}
+
+/** Remove a variable under BOTH prefixes from `target`. */
+export function unsetEnv(target, suffix) {
+  for (const name of envNames(suffix)) delete target[name];
+  return target;
+}
+
+/** The suffix of a name under either prefix, or null for any other name. */
+export function suffixOf(name) {
+  const n = String(name);
+  if (n.startsWith(PREFIX)) return n.slice(PREFIX.length);
+  if (n.startsWith(LEGACY_PREFIX)) return n.slice(LEGACY_PREFIX.length);
+  return null;
+}
+
+// A source is an environment OBJECT (process.env, a child's env) or a
+// `Sys.getenv`-style GETTER (what the planes are handed); a getter answers ""
+// for an unset name, so "" from a getter is read as unset.
+function valueOf(source, name) {
+  if (!source) return undefined;
+  if (typeof source === "function" && source.source) return valueOf(source.source, name);
+  if (typeof source === "function") {
+    const v = source(name, undefined);
+    return v == null || v === "" ? undefined : v;
+  }
+  return source[name];
+}
+
+/**
+ * A copy of `source` in which every `BEATRINA_X` is also present as `CARMAR_X`
+ * and vice versa, the canonical spelling winning when both are set and differ.
+ * For environments handed to child processes.
+ * @param {Record<string, string|undefined>} source
+ * @returns {Record<string, string>}
+ */
+export function mirrorEnv(source) {
+  const out = {};
+  for (const [k, v] of Object.entries(source || {})) if (v != null) out[k] = String(v);
+  for (const [k, v] of Object.entries(source || {})) {
+    if (v == null) continue;
+    if (k.startsWith(PREFIX)) out[LEGACY_PREFIX + k.slice(PREFIX.length)] = String(v);
+  }
+  for (const [k, v] of Object.entries(source || {})) {
+    if (v == null || !k.startsWith(LEGACY_PREFIX)) continue;
+    const canonical = PREFIX + k.slice(LEGACY_PREFIX.length);
+    if (out[canonical] == null) out[canonical] = String(v);
+  }
+  return out;
+}

package/host/gateway-token.mjs

@@ -0,0 +1,51 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+export const GATEWAY_TOKEN_HEADER = "x-beatrina-gateway-token";
+export const GATEWAY_MANAGED_COMMANDS = Object.freeze(["session-new", "session_upgrade", "session_restart", "update_action"]);
+export const GATEWAY_MANAGED_PATHS = Object.freeze(["/session/upgrade", "/session/restart", "/shutdown", "/pair", "/pair/approve", "/published/authorize"]);
+export const GATEWAY_HIDDEN_CAPABILITIES = Object.freeze(["session-restart-v1", "published-direct-v1", "published-pairing-v3", "signed-updates-v1"]);
+
+/** Gateway sessions are launched and upgraded exclusively by their broker. */
+export function gatewayCommands(commands, enabled) {
+  return enabled ? commands.filter((command) => !GATEWAY_MANAGED_COMMANDS.includes(command)) : commands;
+}
+
+/** Validate a gateway credential without ever including its value in errors. */
+export function validateGatewayToken(token) {
+  if (typeof token !== "string" || !/^(?:[a-fA-F0-9]{2}){32,256}$/.test(token)) {
+    throw new Error("Gateway token must contain 32–256 bytes encoded as hexadecimal.");
+  }
+  return token;
+}
+
+/** Read the gateway-only credential from a private regular file at startup. */
+export function loadGatewayToken(file) {
+  if (file === undefined || file === null) return undefined;
+  if (typeof file !== "string" || !file.trim()) throw new Error("Gateway token file path is empty.");
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | fs.constants.O_NONBLOCK);
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 1024 || (process.platform !== "win32" && (stat.mode & 0o077))) {
+      throw new Error("unsafe gateway token file");
+    }
+    return validateGatewayToken(fs.readFileSync(fd, "utf8").trim());
+  } catch {
+    throw new Error("Cannot load gateway token: use a private regular file containing 32–256 bytes encoded as hexadecimal.");
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/** Build a constant-time credential check; only absent configuration disables it. */
+export function gatewayTokenGate(token) {
+  if (token === undefined) return () => true;
+  const expected = crypto.createHash("sha256").update(validateGatewayToken(token)).digest();
+  return (req) => {
+    const supplied = req.headers[GATEWAY_TOKEN_HEADER];
+    if (typeof supplied !== "string" || supplied.length > 512) return false;
+    const actual = crypto.createHash("sha256").update(supplied).digest();
+    return crypto.timingSafeEqual(expected, actual);
+  };
+}