beatrina 0.8.7 → 0.9.43

package/host/ai-authority.mjs

@@ -0,0 +1,55 @@
+// ai-authority.mjs — the supervisor's half of the chat authority contract.
+//
+// The page's half is `lib/ai-authority.js`, and the two lists are ONE list in
+// two files for the reason every other pair in this project is (THEME_TOKENS /
+// EDITOR_TOKENS, LATEX_TEMPLATE_KEYS / TEMPLATE_KEYS): the kernel ships `host/`
+// and `spike/` without `lib/`, and no host module imports across that line.
+// `test/ai-chat-authority.test.mjs` reads both files and fails if they drift.
+//
+// WHY THE HOST IS WHERE THIS IS DECIDED. A CLI turn is a process THIS process
+// spawns. The tool list handed to that process is the only gate with no
+// page-side bypass: there is nothing in the browser to work around, because
+// the spawn was never made with those tools in it. The page's copy exists to
+// ASK for a level and to describe the lane honestly; the host's copy is what
+// happens.
+//
+// The level arriving on the wire is a REQUEST, and `normalizeAuthority` fails
+// closed — absent or unrecognised is `read`. An older page that never heard of
+// the field asks for the reading tools and gets them; silence never grants the
+// most (fix.md P1.5: "switching providers never silently increases authority"
+// covers switching anything else, too).
+
+export const READ_TOOLS = Object.freeze([
+  "beatrina_status", "notebook_read", "chunk_read", "file_list", "file_read",
+]);
+
+export const WRITE_TOOLS = Object.freeze([
+  "chunk_insert", "chunk_update", "chunk_run",
+]);
+
+export const AUTHOR_TOOLS = Object.freeze([...READ_TOOLS, ...WRITE_TOOLS]);
+
+export const AUTHORITY_LEVELS = Object.freeze(["text", "read", "author"]);
+
+/** Read a level off the wire, failing closed. */
+export function normalizeAuthority(value) {
+  const asked = String(value || "").toLowerCase();
+  return AUTHORITY_LEVELS.includes(asked) ? asked : "read";
+}
+
+/** The tools a level may use. `text` gets none. */
+export function toolsFor(authority) {
+  if (authority === "author") return AUTHOR_TOOLS.slice();
+  if (authority === "read") return READ_TOOLS.slice();
+  return [];
+}
+
+/** The `--allowedTools` value for a spawned Claude Code turn at this level. */
+export function allowedToolsArg(authority) {
+  return toolsFor(authority).map((name) => `mcp__beatrina__${name}`).join(",");
+}
+
+export default {
+  READ_TOOLS, WRITE_TOOLS, AUTHOR_TOOLS, AUTHORITY_LEVELS,
+  normalizeAuthority, toolsFor, allowedToolsArg,
+};

package/host/ai-policy.mjs

@@ -26,15 +26,16 @@
 //
 // ── where a policy comes from ──────────────────────────────────────────────
 //
-//   CARMAR_AI_POLICY=/etc/carmar/ai-policy.json   a file the user cannot write
-//   CARMAR_AI_PROVIDERS=anthropic,lmstudio        the quick form
-//   CARMAR_AI_LOCAL_ONLY=1                        only on-machine providers
+//   BEATRINA_AI_POLICY=/etc/beatrina/ai-policy.json   a file the user cannot write
+//   BEATRINA_AI_PROVIDERS=anthropic,lmstudio        the quick form
+//   BEATRINA_AI_LOCAL_ONLY=1                        only on-machine providers
 //
 // The file wins where both are set, because a file is the form an administrator
 // can own while an environment variable is inherited from whoever started the
 // process — on a shared host, that may be the user.
 
 import fs from "node:fs";
+import { envReader } from "./env-names.mjs";
 
 /**
  * The providers whose text never leaves the machine.
@@ -54,7 +55,7 @@ export const KEY_PROVIDERS = Object.freeze(["openai", "anthropic", "google", "gr
 export const CLI_PROVIDERS = Object.freeze(["claudecode", "codex"]);
 export const ALL_PROVIDERS = Object.freeze([...ON_MACHINE_PROVIDERS, ...KEY_PROVIDERS, ...CLI_PROVIDERS]);
 
-const sysEnv = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const sysEnv = envReader(process.env);   // dual-read: BEATRINA_AI_POLICY or its older spelling (host/env-names.mjs)
 const asList = (v) => (v == null ? [] : (Array.isArray(v) ? v : [v]));
 
 /**
@@ -101,6 +102,12 @@ export function normaliseBaseUrls(raw) {
   return { values, errors };
 }
 
+// Every key this file reads. A policy carrying anything else is a policy
+// whose author meant something the supervisor will not do — `provider` for
+// `providers` was accepted in silence and read as "permit all fifteen"
+// (fix.md P1.4). An unknown key is a refusal, with the key named.
+export const POLICY_KEYS = Object.freeze(["providers", "local_only", "note", "models", "base_urls"]);
+
 const policySplit = (value) => String(value || "").split(/[,\s]+/).map((s) => s.trim()).filter((s) => s.length);
 // Control characters are 0x00-0x1f and 0x7f — R's [[:cntrl:]], spelled out.
 // eslint-disable-next-line no-control-regex
@@ -115,12 +122,13 @@ const stripControl = (s) => String(s).replace(/[\u0000-\u001f\u007f]/g, " ");
  * named nothing / named something valid / named only junk — and conflating the
  * last two is the fail-open bug.
  */
-export function carmarAiPolicy(env = sysEnv) {
-  const file = String(env("CARMAR_AI_POLICY", "")).trim();
+export function beatrinaAiPolicy(env = sysEnv) {
+  const file = String(env("BEATRINA_AI_POLICY", "")).trim();
   let named = [];
   let models = {};
   let baseUrls = {};
-  let localOnly = env("CARMAR_AI_LOCAL_ONLY", "") === "1";
+  let localOnly = env("BEATRINA_AI_LOCAL_ONLY", "") === "1";
+  let namedKeyPresent = false;
   let note = "";
   let source = "";
   let errors = [];
@@ -128,13 +136,25 @@ export function carmarAiPolicy(env = sysEnv) {
   if (file.length) {
     source = file;
     if (!fs.existsSync(file)) {
-      errors.push(`CARMAR_AI_POLICY names a file that does not exist: ${file}`);
+      errors.push(`BEATRINA_AI_POLICY names a file that does not exist: ${file}`);
     } else {
       let doc = null;
       let parseError = "";
       try { doc = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { parseError = e.message; }
-      if (parseError) errors.push(`CARMAR_AI_POLICY is not valid JSON: ${parseError}`);
-      else {
+      if (parseError) errors.push(`BEATRINA_AI_POLICY is not valid JSON: ${parseError}`);
+      else if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+        errors.push("BEATRINA_AI_POLICY must be a JSON object of policy keys.");
+      } else {
+        const unknownKeys = Object.keys(doc).filter((k) => !POLICY_KEYS.includes(k));
+        if (unknownKeys.length) {
+          errors.push(`AI policy: ${unknownKeys.map((k) => `'${k}'`).join(", ")} `
+            + `${unknownKeys.length === 1 ? "is not a policy key" : "are not policy keys"}. `
+            + `A policy may name: ${POLICY_KEYS.join(", ")}. A key nobody reads permits everything, which is never what the file meant.`);
+        }
+        // "the key is present" and "the key names something" are different
+        // facts: `providers: []` used to read as "said nothing", which the
+        // default answers with every provider.
+        namedKeyPresent = Object.prototype.hasOwnProperty.call(doc, "providers");
         named = asList(doc && doc.providers).flat().map((v) => String(v));
         if (doc && doc.local_only === true) localOnly = true;
         note = String(asList(doc && doc.note).flat()[0] ?? "").trim();
@@ -148,20 +168,34 @@ export function carmarAiPolicy(env = sysEnv) {
         errors = errors.concat(endpoints.errors);
       }
     }
-  } else if (String(env("CARMAR_AI_PROVIDERS", "")).length) {
+  } else if (String(env("BEATRINA_AI_PROVIDERS", "")).length) {
     source = "env";
-    named = policySplit(env("CARMAR_AI_PROVIDERS", ""));
+    named = policySplit(env("BEATRINA_AI_PROVIDERS", ""));
   } else if (localOnly) {
     source = "env";
   }
 
   const unknown = named.filter((n) => !ALL_PROVIDERS.includes(n));
-  const asked = named.length > 0;                 // did the policy NAME anything at all?
+  // ASKED means the policy spoke about providers at all — including an empty
+  // list, which speaks and names nothing. Only silence inherits the default.
+  const asked = named.length > 0 || namedKeyPresent;
   named = named.filter((n) => ALL_PROVIDERS.includes(n));
 
   let providers = named.length ? named : (asked ? [] : [...ALL_PROVIDERS]);
   if (localOnly) providers = providers.filter((p) => ON_MACHINE_PROVIDERS.includes(p));
 
+  // local_only is a promise about where the words GO, so an endpoint that
+  // leaves the machine contradicts it — and an on-machine provider pointed at
+  // a hosted gateway is exactly how that happens without looking wrong.
+  if (localOnly) {
+    Object.entries(baseUrls).forEach(([provider, url]) => {
+      if (!LOOPBACK_RE.test(url)) {
+        errors.push(`AI policy: local_only is set, but base_urls.${provider} is ${url}, which leaves this machine. `
+          + "Point it at loopback, or drop local_only.");
+      }
+    });
+  }
+
   let set = source.length > 0 && errors.length === 0;
   if (set && !providers.length) {
     errors.push(`The AI policy permits no provider at all${
@@ -193,18 +227,6 @@ export function carmarAiPolicy(env = sysEnv) {
 export const aiProviderAllowed = (provider, policy) =>
   policy.set !== true || (typeof provider === "string" && provider.length > 0 && policy.providers.includes(provider));
 
-/**
- * May this model be used with this provider? TRUE when no models are pinned for
- * that provider — pinning is opt-in per provider. DISCLOSURE ONLY: a model id
- * is a field in a request body the page builds and sends itself, so there is no
- * door here to close.
- */
-export const aiModelAllowed = (provider, model, policy) => {
-  if (policy.set !== true) return true;
-  const allowed = policy.models[provider || ""];
-  if (!allowed || !allowed.length) return true;
-  return typeof model === "string" && model.length > 0 && allowed.includes(model);
-};
 
 /**
  * The sentence the notebook shows when something is refused. Names the
@@ -213,6 +235,6 @@ export const aiModelAllowed = (provider, model, policy) => {
  * message.
  */
 export const aiPolicyReason = (policy) => {
-  const base = `This CarmaR is configured to allow only: ${policy.providers.join(", ")}.`;
+  const base = `This Beatrina is configured to allow only: ${policy.providers.join(", ")}.`;
   return policy.note.length ? `${base} ${policy.note}` : base;
 };

package/host/bundle.mjs

@@ -0,0 +1,194 @@
+// bundle.mjs — `.btrn`, the Beatrina document that travels (docs/results-plan.md R2).
+//
+// A standard ZIP (host/zip.mjs) holding the document, its results and the files
+// it needs — "transfer the whole document like carmnote" (owner, 2026-09-19):   // beatrina-names: keep
+//
+//   manifest.json          format, version, app, created, title, what is inside
+//                          (every entry: size + SHA-256), and the data: its mode
+//                          and every file's path, size and SHA-256
+//   <name>.qmd             the document, plain text (its own .Rmd/.md if it was one)
+//   results/results.json   the beatrina-results/1 record (lib/document-results.js)
+//   results/figures/*      the record's figures, stored (PNG is compressed already)
+//   data/<relative path>   every file the document needs, deflated, at the path it
+//                          uses: data, bibliography, citation style, images, included
+//                          files, project settings (lib/bundle.js documentFiles)
+//
+// NO HISTORY, by the owner's decision (2026-09-19): Undo history holds every
+// keystroke, deleted text included — a document sent to someone must not carry
+// what its author removed. A CarmNote carries none either; the author's own
+// history stays in their session's journal.
+//
+// DATA ≤ 100 MB (compressed, in total) travels inside. Past that it goes BESIDE
+// the bundle, in `<name>.btrn-data/` at the same relative paths, and the manifest
+// keeps each file's size and SHA-256 so the receiver can tell a missing or a
+// changed file by name. A folder, not a second zip: big data stays usable as it
+// is, and ZIP's 4 GB ceiling never comes up.
+//
+// Pure where it can be: buildBundle / readBundle take bytes and return bytes or
+// parts; the plane (host/planes/bundle.mjs) does the file system and the doors.
+
+import crypto from "node:crypto";
+import path from "node:path";
+import { writeZip, readZip, listZip, safeEntryName } from "./zip.mjs";
+
+export const BUNDLE_FORMAT = "beatrina-bundle";
+export const BUNDLE_VERSION = 1;
+export const BUNDLE_EXT = ".btrn";
+/** Data travels inside up to this many compressed bytes; past it, beside. */
+export const DATA_INSIDE_MAX = 100 * 1024 * 1024;
+/** Reading: the whole archive may not expand past this. */
+export const BUNDLE_READ_MAX = 2 * 1024 ** 3;
+
+export const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+/** `/w/paper.btrn` → `/w/paper.btrn-data` — where beside-mode data lives. */
+export const dataFolderFor = (bundlePath) => `${bundlePath}-data`;
+
+/** A data path the bundle may carry: relative, safe, a file (not a folder). */
+export function safeDataPath(rel) {
+  const r = String(rel ?? "").replace(/\\/g, "/");
+  return safeEntryName(r) && !r.endsWith("/") && r.length <= 512;
+}
+
+/**
+ * Build a .btrn.
+ *
+ * @param {object} parts
+ * @param {string} parts.source        the document's text
+ * @param {string} parts.sourceName    its name inside, e.g. "paper.qmd"
+ * @param {string} [parts.title]
+ * @param {string|null} [parts.results]   the results record, JSON text (figures external)
+ * @param {Array<{name:string, data:Buffer, mime?:string}>} [parts.figures]  results/figures/<name>
+ * @param {Array<{path:string, bytes:Buffer}>} [parts.data]  files the code reads, by relative path
+ * @param {string} [parts.app]         the app version that wrote it
+ * @param {Date} [parts.created]
+ * @param {number} [parts.insideMax]   DATA_INSIDE_MAX unless a test says otherwise
+ * @param {string} [parts.bundleName]  the .btrn's own file name, for the beside folder's name
+ * @returns {{zip:Buffer, manifest:object, beside:Array<{path:string, bytes:Buffer}>}}
+ *   `beside` is the data to write in <bundle>-data/ when it did not fit inside
+ */
+export function buildBundle(parts) {
+  const {
+    source, sourceName, title = "", results = null, figures = [],
+    data = [], app = "", created = new Date(), insideMax = DATA_INSIDE_MAX, bundleName = "",
+  } = parts || {};
+  if (typeof source !== "string") throw fail("bundle_input", "a bundle needs the document's source");
+  if (!/^[^/\\]+\.(qmd|Rmd|rmd|md)$/.test(String(sourceName || ""))) {
+    throw fail("bundle_input", `the document inside must be a .qmd, .Rmd or .md file name, not ${JSON.stringify(sourceName)}`);
+  }
+  const files = [];
+  const seen = new Set();
+  const add = (name, bytes, compress = true) => {
+    if (seen.has(name)) throw fail("bundle_input", `${name} twice`);
+    seen.add(name);
+    files.push({ name, data: bytes, compress });
+  };
+  add(sourceName, Buffer.from(source, "utf8"));
+  if (results != null) {
+    add("results/results.json", Buffer.from(String(results), "utf8"));
+    for (const f of figures || []) {
+      if (!safeEntryName(`results/figures/${f.name}`) || f.name.includes("/")) throw fail("bundle_input", `bad figure name ${JSON.stringify(f.name)}`);
+      add(`results/figures/${f.name}`, f.data, false);
+    }
+  }
+  const dataFiles = (data || []).map((d) => {   // each: {path, bytes, kind?}
+    const rel = String(d.path).replace(/\\/g, "/");
+    if (!safeDataPath(rel)) throw fail("bundle_bad_path", `a data path must be relative and stay inside the document's folder: ${JSON.stringify(d.path)}`);
+    return { path: rel, bytes: d.bytes, size: d.bytes.length, sha256: sha256(d.bytes), kind: d.kind || "data" };
+  });
+
+  const manifestFor = (mode, dataEntries) => ({
+    format: BUNDLE_FORMAT, version: BUNDLE_VERSION, app, created: created.toISOString(), title,
+    source: sourceName,
+    entries: dataEntries.concat(files).map((f) => ({ name: f.name, size: f.data.length, sha256: sha256(f.data) })),
+    data: {
+      mode, ...(mode === "beside" ? { folder: `${path.basename(bundleName || sourceName.replace(/\.[^.]+$/, ".btrn"))}-data` } : {}),
+      files: dataFiles.map(({ path: p, size, sha256: h, kind }) => ({ path: p, size, sha256: h, kind })),
+    },
+  });
+  const zipWith = (manifest, dataEntries) => writeZip([
+    { name: "manifest.json", data: Buffer.from(JSON.stringify(manifest, null, 1), "utf8") },
+    ...files, ...dataEntries,
+  ], { date: created });
+
+  // Inside first; measure what the data costs compressed, and move it beside
+  // only when it passes the cap.
+  const inside = dataFiles.map((d) => ({ name: `data/${d.path}`, data: d.bytes, compress: true }));
+  let zip = zipWith(manifestFor(dataFiles.length ? "inside" : "none", inside), inside);
+  const dataBytes = listZip(zip).filter((e) => e.name.startsWith("data/")).reduce((a, e) => a + e.csize, 0);
+  if (dataBytes <= insideMax) {
+    return { zip, manifest: manifestFor(dataFiles.length ? "inside" : "none", inside), beside: [] };
+  }
+  const manifest = manifestFor("beside", []);
+  zip = zipWith(manifest, []);
+  return { zip, manifest, beside: dataFiles.map((d) => ({ path: d.path, bytes: d.bytes })), dataCompressed: dataBytes };
+}
+
+/**
+ * Read a .btrn: every part, VERIFIED. The manifest's SHA-256 for each entry is
+ * checked, and an entry the manifest does not list is refused — nothing is
+ * half-loaded.
+ *
+ * @param {Buffer} buf
+ * @returns {{manifest:object, source:string, sourceName:string, results:string|null,
+ *   figures:Map<string,Buffer>, data:Map<string,Buffer>}}
+ */
+export function readBundle(buf, { maxTotal = BUNDLE_READ_MAX } = {}) {
+  const all = readZip(buf, { maxTotal });
+  const rawManifest = all.get("manifest.json");
+  if (!rawManifest) throw fail("bundle_no_manifest", "not a Beatrina document (no manifest.json)");
+  let manifest;
+  try { manifest = JSON.parse(rawManifest.toString("utf8")); } catch { throw fail("bundle_bad_manifest", "manifest.json is not JSON"); }
+  if (manifest.format !== BUNDLE_FORMAT) throw fail("bundle_bad_manifest", `not a Beatrina document (format ${JSON.stringify(manifest.format)})`);
+  if (!(Number(manifest.version) >= 1)) throw fail("bundle_bad_manifest", "the manifest names no version");
+  if (Number(manifest.version) > BUNDLE_VERSION) {
+    throw fail("bundle_newer", `this document was written by a newer Beatrina (bundle version ${manifest.version}); update Beatrina to open it`);
+  }
+  const listed = new Map((manifest.entries || []).map((e) => [e.name, e]));
+  for (const [name, bytes] of all) {
+    if (name === "manifest.json") continue;
+    const want = listed.get(name);
+    if (!want) throw fail("bundle_unlisted", `${name} is in the archive but not in its manifest`);
+    if (want.size !== bytes.length || want.sha256 !== sha256(bytes)) throw fail("bundle_digest", `${name} does not match its manifest — the document is damaged`);
+  }
+  for (const name of listed.keys()) if (!all.has(name)) throw fail("bundle_missing", `the manifest lists ${name}, which is not in the archive`);
+  const sourceName = String(manifest.source || "");
+  if (!all.has(sourceName)) throw fail("bundle_missing", "the document itself is missing");
+  const figures = new Map();
+  const data = new Map();
+  for (const [name, bytes] of all) {
+    if (name.startsWith("results/figures/")) figures.set(name.slice("results/figures/".length), bytes);
+    else if (name.startsWith("data/")) data.set(name.slice("data/".length), bytes);
+  }
+  return {
+    manifest, sourceName, source: all.get(sourceName).toString("utf8"),
+    results: all.has("results/results.json") ? all.get("results/results.json").toString("utf8") : null,
+    figures, data,
+  };
+}
+
+/**
+ * What opening a bundle would do to each data file, pure: compare the
+ * manifest's digest with the file at the document's folder.
+ *
+ * @param {object} manifest
+ * @param {(rel:string) => (Buffer|null)} readLocal  the file beside the document, or null
+ * @returns {Array<{path:string, size:number, kind:string, state:'absent'|'same'|'differs'}>}
+ */
+export function dataPlan(manifest, readLocal) {
+  return ((manifest && manifest.data && manifest.data.files) || []).map((f) => {
+    const local = readLocal(f.path);
+    const state = !local ? "absent" : sha256(local) === f.sha256 ? "same" : "differs";
+    return { path: f.path, size: f.size, kind: f.kind || "data", state };
+  });
+}
+
+/** `paper.btrn` → `paper.qmd` — the name the document takes inside. */
+export function innerNameFor(bundlePath, format = "qmd") {
+  const stem = path.basename(String(bundlePath || "document")).replace(/\.btrn$/i, "") || "document";
+  const ext = { qmd: "qmd", rmd: "Rmd", md: "md" }[String(format).toLowerCase()] || "qmd";
+  return `${stem}.${ext}`;
+}
+
+export default { buildBundle, readBundle, dataPlan, innerNameFor, dataFolderFor, safeDataPath, sha256 };

package/host/deployment.mjs

@@ -13,6 +13,8 @@
 // client is not a browser and therefore is this same OS user; anywhere the port
 // is reachable by someone else the same header proves nothing, so it is refused.
 
+import { envReader } from "./env-names.mjs";
+
 export const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "[::1]", "localhost"];
 
 /** Split a comma/space-separated environment value into trimmed, non-empty parts. */
@@ -45,8 +47,8 @@ export function isLoopbackBind(bind) {
  *   `errors` is EMPTY when the posture is safe to serve. A non-empty `errors`
  *   must abort startup; it is never a warning.
  */
-export function carmarDeployment(port, env = envFromProcess()) {
-  let bind = env("CARMAR_BIND", "127.0.0.1").trim();
+export function beatrinaDeployment(port, env = envFromProcess()) {
+  let bind = env("BEATRINA_BIND", "127.0.0.1").trim();
   if (!bind) bind = "127.0.0.1";
   const loopback = isLoopbackBind(bind);
 
@@ -54,9 +56,9 @@ export function carmarDeployment(port, env = envFromProcess()) {
   // the same-origin case. Off loopback the server is behind a proxy, so its own
   // page arrives with the PROXY's origin — which the operator must name.
   const selfOrigins = [`http://${bind}:${port}`, `http://127.0.0.1:${port}`, `http://localhost:${port}`];
-  const origins = unique([...selfOrigins, ...splitList(env("CARMAR_ORIGINS", ""))]);
+  const origins = unique([...selfOrigins, ...splitList(env("BEATRINA_ORIGINS", ""))]);
 
-  let hostsEnv = splitList(env("CARMAR_HOSTS", ""));
+  let hostsEnv = splitList(env("BEATRINA_HOSTS", ""));
   const defaultHosts = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
   // A configured host may or may not carry a port. Accept both spellings so an
   // operator writing `stats.example.edu` is not silently refused behind a proxy
@@ -68,31 +70,31 @@ export function carmarDeployment(port, env = envFromProcess()) {
   // allowing an Origin-less client. Binding off loopback breaks it, but so does
   // a shared multi-user host or a container whose 127.0.0.1 is forwarded out,
   // so the posture is declarable in its own right.
-  const requireOrigin = env("CARMAR_REQUIRE_ORIGIN", "") === "1" || !loopback;
+  const requireOrigin = env("BEATRINA_REQUIRE_ORIGIN", "") === "1" || !loopback;
 
-  const trustProxy = env("CARMAR_TRUST_PROXY", "") === "1";
-  const userHeader = env("CARMAR_USER_HEADER", "X-Forwarded-User").trim();
-  const proxyAddrs = splitList(env("CARMAR_TRUSTED_PROXY", "127.0.0.1 ::1"));
-  const allowOpen = env("CARMAR_ALLOW_UNAUTHENTICATED", "") === "1";
+  const trustProxy = env("BEATRINA_TRUST_PROXY", "") === "1";
+  const userHeader = env("BEATRINA_USER_HEADER", "X-Forwarded-User").trim();
+  const proxyAddrs = splitList(env("BEATRINA_TRUSTED_PROXY", "127.0.0.1 ::1"));
+  const allowOpen = env("BEATRINA_ALLOW_UNAUTHENTICATED", "") === "1";
 
   const errors = [];
   if (!loopback) {
     if (!hostsEnv.length) {
-      errors.push(`CARMAR_BIND is ${bind} but CARMAR_HOSTS is unset. Off loopback the `
+      errors.push(`BEATRINA_BIND is ${bind} but BEATRINA_HOSTS is unset. Off loopback the `
         + "Host allow-list is the only defence against DNS rebinding, so it must "
-        + "name the hostname readers will use (e.g. CARMAR_HOSTS=stats.example.edu).");
+        + "name the hostname readers will use (e.g. BEATRINA_HOSTS=stats.example.edu).");
     }
     if (!trustProxy && !allowOpen) {
-      errors.push(`CARMAR_BIND is ${bind} with no authentication in front of it. Put `
+      errors.push(`BEATRINA_BIND is ${bind} with no authentication in front of it. Put `
         + "Beatrina behind a reverse proxy that authenticates and set "
-        + "CARMAR_TRUST_PROXY=1, or set CARMAR_ALLOW_UNAUTHENTICATED=1 to serve code "
+        + "BEATRINA_TRUST_PROXY=1, or set BEATRINA_ALLOW_UNAUTHENTICATED=1 to serve code "
         + "execution to everyone who can reach this port. See docs/server.md.");
     }
     if (trustProxy && !userHeader) {
-      errors.push("CARMAR_TRUST_PROXY=1 requires a non-empty CARMAR_USER_HEADER.");
+      errors.push("BEATRINA_TRUST_PROXY=1 requires a non-empty BEATRINA_USER_HEADER.");
     }
     if (trustProxy && !proxyAddrs.length) {
-      errors.push("CARMAR_TRUST_PROXY=1 requires CARMAR_TRUSTED_PROXY to name the proxy's address.");
+      errors.push("BEATRINA_TRUST_PROXY=1 requires BEATRINA_TRUSTED_PROXY to name the proxy's address.");
     }
   }
 
@@ -127,7 +129,7 @@ export function carmarDeployment(port, env = envFromProcess()) {
  *
  * @param {{REMOTE_ADDR?: string} & Record<string, string>} req a Rook-shaped
  *   request: `REMOTE_ADDR` plus `HTTP_*` header keys
- * @param {ReturnType<typeof carmarDeployment>} deployment
+ * @param {ReturnType<typeof beatrinaDeployment>} deployment
  * @returns {string}
  */
 export function proxyUser(req, deployment) {
@@ -150,9 +152,14 @@ export function rookOf(req) {
   return out;
 }
 
-/** A getter with `Sys.getenv`'s signature over `process.env`. */
+/**
+ * A getter with `Sys.getenv`'s signature over `process.env` — dual-read: a
+ * `CARMAR_*` name asked for here is also answered by its `BEATRINA_*` spelling
+ * (host/env-names.mjs), so the call sites above keep the vocabulary the
+ * deployment vectors in test/host-deployment.test.mjs use.
+ */
 export function envFromProcess(source = process.env) {
-  return (name, unset = "") => (source[name] == null ? unset : String(source[name]));
+  return envReader(source);
 }
 
 function unique(list) {

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" }) };
   }
 
   /**

package/host/engine-pool.mjs

@@ -347,16 +347,58 @@ export class EnginePool extends EventEmitter {
   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) {