beatrina 0.8.6 → 0.9.43

package/host/server.mjs

@@ -30,13 +30,18 @@ import http from "node:http";
 import path from "node:path";
 import { attachWebSocket } from "./ws.mjs";
 import { rookOf, proxyUser } from "./deployment.mjs";
+import { cleanSessionDocuments } from "./session-keep.mjs";
+import { readEnv } from "./env-names.mjs";
+import { gatewayCommands, gatewayTokenGate, GATEWAY_MANAGED_COMMANDS, GATEWAY_MANAGED_PATHS, GATEWAY_HIDDEN_CAPABILITIES } from "./gateway-token.mjs";
 
-export const FORWARDED = Object.freeze(["env", "obj", "struct", "view", "colstats", "rm", "packages", "doctor",
+export const FORWARDED = Object.freeze(["env", "obj", "struct", "view", "colstats", "column_values", "rm", "packages", "doctor",
   "package_action", "package_help", "project_status", "project_action", "help", "wd",
   "parse", "complete", "files", "import", "readfile", "writefile", "writefiles_atomic",
-  "hover", "format", "sniff", "mkdir", "renamepath", "deletepath", "copypath", "revealpath", "debug_breaks"]);
-export const SESSION_CONTROLS = Object.freeze(["exec", "interrupt", "force_stop", "restart", "runstate", "runs", "adopt",
-  "input_reply", "debug_cmd"]);
+  "hover", "format", "sniff", "mkdir", "renamepath", "deletepath", "copypath", "revealpath", "debug_breaks",
+  // "Restart, keep variables", step one (spike/workspace-keep.R). Page-only in both senses: AGENT_REFUSED
+  // below and the class gate in handleFrame. Step two, `resume`, is deliberately NOT here — only the
+  // host asks it, after a restart it performed (WorkerPlane.startResume).
+  "suspend"]);
 /** Answered by serve.R itself, not yet by this host. Refused by NAME so the page never hangs. */
 export const NOT_YET = Object.freeze({
   files: "the file system", journal: "the document journal", ai: "the AI conversation store",
@@ -48,12 +53,19 @@ export const NOT_YET = Object.freeze({
   "open-request": "the open-file door", "page-title": "", "session-new": "session management",
   cite_styles: "citations",
 });
-export const AGENT_REFUSED = Object.freeze(["exec", "interrupt", "force_stop", "restart", "debug_cmd", "input_reply", "project_action"]);
+export const AGENT_REFUSED = Object.freeze(["exec", "interrupt", "force_stop", "restart", "debug_cmd", "input_reply", "project_action",
+  // A copy of every object in the session, written to disk.
+  "suspend", "suspend_cancel",
+  // The grid's clipboard door (a whole column, up to a million values); an agent reads data through a chunk.
+  "column_values"]);
 /** Why, in the sentence serve.R uses. A plane supplies its own via `agentReason`. */
 export const AGENT_WHY_DEFAULT = "Agents run code through notebook chunks (chunk_run), not raw exec.";
 export const AGENT_WHY = Object.freeze({
   input_reply: "Agents cannot answer a prompt on the user's behalf.",
   project_action: "Agents cannot install or restore project packages.",
+  suspend: "Agents cannot keep the user's workspace.",
+  suspend_cancel: "Agents cannot keep the user's workspace.",
+  column_values: "Agents read data through notebook chunks (chunk_run), not the grid's copy door.",
 });
 export const PAGE_ONLY_CLASSES = Object.freeze(["served", "file", "local"]);
 export const FILE_ORIGIN = "null";
@@ -79,9 +91,16 @@ export function secureToken(n = 32) {
   return out;
 }
 
-/** Stamp the served HTML with this session's identity, once per load. */
-export function stampSession(html, stamp) {
-  const meta = `<meta name="carmar-session" content="${stamp}">`;
+/**
+ * Stamp the served HTML with this session's identity, once per load — and, for a product other
+ * than Beatrina (`app`, BEATRIX_APP_ID: "beatrina"), with which product served it, so the page's
+ * Start R can name the door this product has (docs/launch-menu-plan.md L6). A Beatrina page is the
+ * installed file plus the ONE session meta, exactly as before (test/host-launch.test.mjs pins that
+ * byte for byte); a page opened from disk carries neither, and its Start R stays Beatrina's.
+ */
+export function stampSession(html, stamp, app = "") {
+  const product = String(app || "").replace(/[^A-Za-z0-9.]/g, "");
+  const meta = `<meta name="beatrina-session" content="${stamp}">${product && product !== "beatrina" ? `<meta name="beatrina-app" content="${product}">` : ""}`;
   let m = html.match(/<head\b[^>]*>/);
   if (!m) m = html.match(/<html\b[^>]*>/);
   if (!m) return meta + html;
@@ -91,7 +110,7 @@ export function stampSession(html, stamp) {
 
 /**
  * @param {Object} opts
- * @param {ReturnType<import("./deployment.mjs").carmarDeployment>} opts.deployment
+ * @param {ReturnType<import("./deployment.mjs").beatrinaDeployment>} opts.deployment
  * @param {import("./engine-pool.mjs").EnginePool} opts.plane  the engine
  *   router; it presents one WorkerPlane's surface, so everything here reads as
  *   it did when there was one engine (WP4, docs/wp/wp4-python.md)
@@ -104,16 +123,38 @@ export function stampSession(html, stamp) {
  * @param {(event: string, fields?: object) => void} opts.audit
  * @param {() => void} opts.onShutdown
  * @param {string} opts.here                     the directory holding the fallback spike page
+ * @param {string} [opts.gatewayToken]           private gateway credential, required on HTTP and WS
  */
 export function createHostServer(opts) {
   const { deployment, plane, audit, onShutdown, planes = [] } = opts;
+  const gatewayOk = gatewayTokenGate(opts.gatewayToken);
+  const gatewayMode = opts.gatewayToken !== undefined;
+  const commands = gatewayCommands(planes.flatMap((pl) => pl.commands || []), gatewayMode);
+  const capabilities = planes.flatMap((pl) => pl.capabilities || []).filter((capability) => !gatewayMode || !GATEWAY_HIDDEN_CAPABILITIES.includes(capability));
+  const managedError = "Sessions and software updates are managed by the Beatrina server. Use the server workspace controls.";
   const originsOk = deployment.origins;
   const hostsOk = deployment.hosts;
   const sockets = [];                       // records: {ws, role, name, class, user, lastSeen, beats}
   const approvals = new Set();              // exact origins the user approved this session
-  const state = { everConnected: false, heldAt: null, pendingOpen: opts.pendingOpen || null, quit: false };
+  const state = { everConnected: false, heldAt: null, pendingOpen: opts.pendingOpen || null, quit: false,
+    // The documents open in this session, as the pages last reported them (host/session-keep.mjs).
+    sessionDocuments: Array.isArray(opts.sessionDocuments) ? opts.sessionDocuments : [] };
   plane.sockets = () => sockets;
-  plane.on("broadcast", (payload) => sockets.forEach((r) => r.ws.send(payload)));
+  // A TERMINAL worker death leaves the page stranded: no R, but a supervisor that still answers the
+  // handoff (src/r-kernel.js `stranded`). A page that connects AFTER the death — the page's own
+  // reconnect does exactly that — never saw a ready frame to learn this session's build or its
+  // doors from, so the notice carries them. Our own frame, re-encoded; never a worker's bytes.
+  const strandedNotice = (payload) => {
+    if (typeof payload !== "string" || !payload.includes('"worker-died"') || !payload.includes('"terminal":true')) return payload;
+    try {
+      const frame = JSON.parse(payload);
+      const doors = commands.filter((c) => c === "session_upgrade" || c === "session_restart");
+      return enc({ ...frame, session: { kernel_build: opts.kernelBuild, installed_build: opts.installedBuild(), commands: doors } });
+    } catch { return payload; }
+  };
+  plane.on("broadcast", (payload) => { const out = strandedNotice(payload); sockets.forEach((r) => r.ws.send(out)); });
+  // A restore's report is about every object in the session: pages only, never an agent or a native client.
+  plane.on("broadcast-pages", (payload) => sockets.filter((r) => PAGE_ONLY_CLASSES.includes(r.class) && r.role === "page").forEach((r) => r.ws.send(payload)));
 
   // The session stamp: ONE string, rendered once, that the page's meta and
   // /health's `started` share so they can never differ in their digits.
@@ -187,6 +228,7 @@ export function createHostServer(opts) {
   const ctx = {
     deployment, plane, audit, sockets, approvals, state, opts,
     enc, scalarChr, pageRecs, socketClass,
+    sessionDocuments: () => state.sessionDocuments,
     port: () => (server.address() ? server.address().port : deployment.port),
     respond: (res, status, type, body, extra) => respond(res, status, type, body, extra),
     reject: (res, reason, detail) => reject(res, reason, detail),
@@ -212,8 +254,13 @@ export function createHostServer(opts) {
   }
 
   const server = http.createServer((req, res) => {
+    if (!gatewayOk(req)) return reject(res, "gateway authentication required");
     if (!hostOk(req)) return reject(res, "bad host", req.headers.host || "(none)");
     const pathname = new URL(req.url, "http://x").pathname;
+    if (gatewayMode && GATEWAY_MANAGED_PATHS.includes(pathname)) {
+      audit("server-managed-refused", { path: pathname });
+      return respond(res, 403, "application/json", enc({ ok: false, reason: "server-managed", error: managedError }));
+    }
     if (pathname === "/health") {
       if (queryParam(req, "hold") === "1") state.heldAt = Date.now();
       const newerOnNpm = opts.updateAvailable ? opts.updateAvailable() : null;
@@ -229,14 +276,14 @@ export function createHostServer(opts) {
         // Which build this kernel replaced, for the first 90 s of its life —
         // how a page recognises its successor. Never the page or its capability.
         ...(opts.handoffFrom && Date.now() - opts.bootAt <= 90000 ? { handoff_from: opts.handoffFrom } : {}),
-        capabilities: ["published-direct-v1", "published-pairing-v3", "session-restart-v1", ...planes.flatMap((pl) => pl.capabilities || [])],
+        capabilities: [...(gatewayMode ? [] : ["published-direct-v1", "published-pairing-v3", "session-restart-v1"]), ...capabilities],
         // `engines` is what a chunk may be RUN on, so a file page probing for
         // a kernel can tell a two-engine host from a one-engine one before it
         // opens a socket. It names every engine a runtime was found for, not
         // only the ones that have started (WP4; docs/wp/wp4-python.md).
         host: "beatrix",
         // Which product this host is (BEATRIX_APP_ID): a report from the page files under it.
-        app: opts.app || "carmar",
+        app: opts.app || "beatrina",
         engines: typeof plane.engineNames !== "undefined" ? plane.engineNames : (plane.language ? [plane.language] : []),
         engine_status: typeof plane.engineRows === "function" ? plane.engineRows() : undefined,
       }), { "Access-Control-Allow-Origin": "*" });
@@ -257,13 +304,17 @@ export function createHostServer(opts) {
       const page = pathname === "/spike" ? path.join(opts.here, "index.html") : (opts.pagePath() || path.join(opts.here, "index.html"));
       let html;
       try { html = fs.readFileSync(page, "utf8"); } catch { return respond(res, 404, "text/plain", "no notebook page is built for this kernel"); }
-      return respond(res, 200, "text/html", stampSession(html, sessionStamp));
+      return respond(res, 200, "text/html", stampSession(html, sessionStamp, opts.app || "beatrina"));
     }
     return respond(res, 404, "text/plain", "not found");
   });
 
   attachWebSocket(server, {
     gate: (req) => {
+      if (!gatewayOk(req)) {
+        audit("rejected", { reason: "gateway authentication required" });
+        return { status: 403, body: "forbidden: gateway authentication required" };
+      }
       if (!hostOk(req)) { audit("rejected", { reason: "bad host", detail: req.headers.host || "(none)" }); return { status: 403, body: "forbidden: bad host" }; }
       const origin = req.headers.origin;
       const approved = origin != null && approvals.has(origin);
@@ -277,14 +328,22 @@ export function createHostServer(opts) {
       const rec = { ws, role: "page", name: "", class: socketClass(ws.request),
         user: proxyUser(rookOf(ws.request), deployment), lastSeen: Date.now(), beats: false };
       sockets.push(rec);
+      // A pong is the transport answering: the browser's network process sends it even while the
+      // page's thread is busy rendering or throttled behind another window, so it counts as life.
+      ws.onPong(() => { rec.lastSeen = Date.now(); });
       state.everConnected = true;
       audit("socket-open", { sockets: sockets.length, class: rec.class, user: rec.user });
       // The engine announced itself long before this page connected; replay
       // it — and every other engine that has since started, each under its own
       // `engine-ready` (host/engine-pool.mjs replay()).
       if (plane.hello) ws.send(plane.hello);
-      if (plane.notice) ws.send(plane.notice);
+      if (plane.notice) ws.send(strandedNotice(plane.notice));
       if (typeof plane.replay === "function") plane.replay(ws);
+      // …and a restore that finished before this page arrived (a page following a handoff).
+      if (PAGE_ONLY_CLASSES.includes(rec.class) && typeof plane.freshResumeReport === "function") {
+        const report = plane.freshResumeReport();
+        if (report) ws.send(report);
+      }
       for (const pl of planes) { try { pl.onOpen?.(rec, ctx); } catch (e) { audit("plane-error", { plane: pl.name, detail: e.message }); } }
       ws.onMessage((message) => {
         try { handleFrame(message, rec); } catch (e) { audit("frame-error", { detail: e.message }); }
@@ -321,6 +380,11 @@ export function createHostServer(opts) {
     if (!cmd || typeof cmd !== "object" || Array.isArray(cmd) || !scalarChr(cmd.type)) return undefined;
     rec.lastSeen = Date.now();
     const type = cmd.type;
+    if (gatewayMode && GATEWAY_MANAGED_COMMANDS.includes(type)) {
+      audit("server-managed-refused", { type });
+      rec.ws.send(enc({ type, ...(scalarChr(cmd.id) ? { id: cmd.id } : {}), ok: false, reason: "server-managed", error: managedError }));
+      return undefined;
+    }
 
     if (type === "hb") {
       rec.beats = true;
@@ -346,6 +410,24 @@ export function createHostServer(opts) {
       rec.ws.send(enc({ type: "open-request", id: scalarChr(cmd.id) ? cmd.id : "open", path: p || "" }));
       return undefined;
     }
+    // The documents this session has open. Page-only in BOTH senses: the list is file paths, and a page
+    // that could not open a terminal must not be able to rewrite what the session reopens either.
+    if (type === "page-documents") {
+      if (rec.role === "page" && PAGE_ONLY_CLASSES.includes(rec.class)) {
+        state.sessionDocuments = cleanSessionDocuments(cmd.documents);
+        opts.onSessionDocuments?.(state.sessionDocuments);
+      }
+      return undefined;
+    }
+    // A page asks what this session had open, to reopen it. `others` counts the OTHER pages attached: a
+    // page joining a session another window shows must not open the same documents a second time.
+    if (type === "session-documents") {
+      if (!scalarChr(cmd.id)) return undefined;
+      const allowed = rec.role === "page" && PAGE_ONLY_CLASSES.includes(rec.class);
+      const others = pageRecs().filter((r) => r !== rec).length;
+      rec.ws.send(enc({ type, id: cmd.id, documents: allowed ? state.sessionDocuments : [], others, refused: !allowed }));
+      return undefined;
+    }
     if (AGENT_REFUSED.includes(type) && rec.role === "mcp") {
       audit("mcp-refused", { reason: `agent asked for ${type}` });
       // serve.R answers IN THE ASKED TYPE with an `error`, never a `done`: the
@@ -363,14 +445,22 @@ export function createHostServer(opts) {
       audit("project-action-refused", { reason: "class", class: rec.class || "unknown" });
       return undefined;
     }
+    // "Restart, keep variables": the save is a copy of the whole session, so it is page-only in BOTH
+    // senses, and its cancel interrupts only a save THIS page asked for.
+    if ((type === "suspend" || type === "suspend_cancel") && !PAGE_ONLY_CLASSES.includes(rec.class)) {
+      if (scalarChr(cmd.id)) rec.ws.send(enc({ type, id: cmd.id, error: "Only the local notebook page may keep the workspace." }));
+      audit("suspend-refused", { reason: "class", class: rec.class || "unknown" });
+      return undefined;
+    }
     switch (type) {
+      case "suspend_cancel": if (typeof plane.cancelSuspend === "function") plane.cancelSuspend(rec); return undefined;
       case "exec": return plane.exec(cmd, rec);
       case "interrupt": return plane.interrupt(cmd, rec);
       // Both carry an OPTIONAL engine. `restart` with none is the primary
       // engine's — which is what "Restart R" in the page means and what every
       // client built before there was a second engine sends (§6.5).
       case "force_stop": return plane.forceStop(rec, cmd);
-      case "restart": Promise.resolve(plane.restart(cmd.engine)).catch((e) => audit("restart-failed", { detail: e.message })); return undefined;
+      case "restart": Promise.resolve(plane.restart(cmd.engine, { resume: cmd.resume })).catch((e) => audit("restart-failed", { detail: e.message })); return undefined;
       case "runstate": return plane.runstate(cmd, rec);
       case "runs": return plane.runs(cmd, rec);
       case "adopt": return plane.adopt(cmd, rec);
@@ -410,13 +500,25 @@ export function createHostServer(opts) {
     return undefined;
   }
 
-  /** Close and forget sockets that have stopped answering (only those that beat). */
-  const silenceMs = Math.max(0, Number(process.env.CARMAR_SOCKET_SILENCE ?? 90)) * 1000;
+  /** Close and forget sockets that have stopped answering (only those that beat).
+   *
+   * Silence alone used to be the verdict, and a page whose OWN thread was busy — rendering a
+   * large result, or throttled by the browser behind another window during a long chunk — sent
+   * no `hb` for 90 s and was cut off while R worked; the page then printed "Connection to the R
+   * kernel closed", redialled and adopted the run back. Misleading, and the owner said so
+   * (2026-09-17). So a page silent for half the threshold is PINGED at the protocol level: the
+   * browser answers a ping from its network process whatever the page's thread is doing, the
+   * pong refreshes `lastSeen` (onPong above), and only a socket that answers nothing — a
+   * sleeping laptop, a dropped link, a killed browser — reaches the threshold and is closed. */
+  const silenceMs = Math.max(0, Number(readEnv(process.env, "SOCKET_SILENCE", "90"))) * 1000;
   const reaper = setInterval(() => {
     if (!silenceMs || !sockets.length) return;
     const now = Date.now();
     for (const rec of [...sockets]) {
-      if (rec.beats && now - rec.lastSeen >= silenceMs) {
+      if (!rec.beats) continue;
+      const silent = now - rec.lastSeen;
+      if (silent >= silenceMs / 2 && silent < silenceMs) { rec.ws.ping(); continue; }
+      if (silent >= silenceMs) {
         audit("socket-silent", { role: rec.role, silence: silenceMs / 1000 });
         const at = sockets.indexOf(rec);
         if (at >= 0) sockets.splice(at, 1);
@@ -434,8 +536,8 @@ export function createHostServer(opts) {
     sessionStamp,
     ctx,
     /** Every verb the registered planes serve — merged into ready.commands by main.mjs. */
-    commands: planes.flatMap((pl) => pl.commands || []),
-    capabilities: planes.flatMap((pl) => pl.capabilities || []),
+    commands,
+    capabilities,
     close: () => { clearInterval(reaper); sockets.forEach((r) => r.ws.close(1001, "shutdown")); server.close(); },
   };
 }

package/host/session-keep.mjs

@@ -0,0 +1,70 @@
+// session-keep.mjs — the pure rules behind two CarmaR 0.8.5 features, as the host answers them.
+//
+//   · "Restart, keep variables": the worker saves the session (`suspend`, spike/workspace-keep.R) and
+//     answers a TOKEN; the host never reads a kept workspace, it only checks that a token is one the
+//     worker could have minted and carries it to the next worker (`resume`). A path is never a token.
+//   · "A session keeps its documents": the page reports what it has open (`page-documents`), the host
+//     keeps the list, labels the runtime record with it, and hands it back (`session-documents`).
+//
+// Transcribed rule for rule from spike/workspace-keep.R (keep_token_ok) and spike/session-documents.R
+// (session_documents_clean/label/encode/decode), which Beatrina's R supervisor sources; pinned against
+// the same cases by test/session-keep.test.mjs.
+
+import path from "node:path";
+
+export const KEEP_TOKEN_RE = /^[0-9]{14}-[0-9a-f]{16}$/;
+export const SESSION_DOCUMENTS_MAX = 64;
+export const SESSION_DOCUMENT_FORMATS = Object.freeze(["qmd", "Rmd", "md", "carmd"]);
+/** How long a restore's report is replayed to a page that connects late (serve.R: 120 s). */
+export const RESUME_REPORT_MS = 120000;
+
+/** Is `x` a token the worker could have minted? */
+export const keepTokenOk = (x) => typeof x === "string" && KEEP_TOKEN_RE.test(x);
+
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\x00-\x1f\x7f]/g;
+const textOf = (value, cap) => {
+  if (typeof value !== "string") return null;
+  const v = value.replace(CONTROL, " ");
+  return v.length > cap ? null : v;
+};
+
+/** The documents a page reported, cleaned: absolute paths, bounded names, known formats, no duplicates. */
+export function cleanSessionDocuments(documents) {
+  if (!Array.isArray(documents) || !documents.length) return [];
+  const rows = [];
+  const seen = new Set();
+  for (const row of documents) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    const p = textOf(row.path ?? "", 4096);
+    const name = textOf(row.name ?? "", 200);
+    let format = textOf(row.format ?? "", 16);
+    if (p == null || name == null || format == null) continue;
+    // Reopened through the file ops, which resolve it themselves; here it need only be absolute.
+    if (p && !/^(\/|[A-Za-z]:[/\\])/.test(p)) continue;
+    if (!p && !name.trim()) continue;
+    if (!SESSION_DOCUMENT_FORMATS.includes(format)) format = "qmd";
+    if (p) { if (seen.has(p)) continue; seen.add(p); }
+    rows.push({ path: p, name: name.trim(), format, active: row.active === true });
+    if (rows.length >= SESSION_DOCUMENTS_MAX) break;
+  }
+  return rows;
+}
+
+/** "SezerProfiles.qmd + 1 more": what the menu helper shows for a session. */
+export function sessionDocumentsLabel(documents) {
+  if (!Array.isArray(documents) || !documents.length) return "";
+  const lead = documents.find((d) => d.active === true) || documents[0];
+  let name = lead.path ? path.basename(lead.path.replace(/\\/g, "/")) : lead.name;
+  if (!lead.path) name = `${name} (unsaved)`;
+  const rest = documents.length - 1;
+  const label = rest > 0 ? `${name} + ${rest} more` : name;
+  return label.replace(CONTROL, " ").replace(/["\\]/g, "'").slice(0, 120).trim();
+}
+
+export const encodeSessionDocuments = (documents) => (Array.isArray(documents) && documents.length ? JSON.stringify(documents) : "");
+
+export function decodeSessionDocuments(text) {
+  if (typeof text !== "string" || !text) return [];
+  try { return cleanSessionDocuments(JSON.parse(text)); } catch { return []; }
+}

package/host/settings.mjs

@@ -13,10 +13,10 @@
 //   · An administrator's setting is NOT IN THIS FILE'S VOCABULARY AT ALL. It is
 //     rejected on read and refused on write, always — never "env wins if
 //     present", because that only guarantees anything when the env IS set, and
-//     a deployment that never set CARMAR_ROOT is still one where a user must
+//     a deployment that never set BEATRINA_ROOT is still one where a user must
 //     not invent one.
 //
-// The tempting alternative — one layered getter handed to carmarDeployment()
+// The tempting alternative — one layered getter handed to beatrinaDeployment()
 // and the AI policy — is deliberately NOT built here either. It would put every
 // administrator variable one argument-passing mistake away from being
 // file-settable. Those read process.env directly; only the user-writable call
@@ -32,6 +32,7 @@ import fs from "node:fs";
 
 import path from "node:path";
 import { appId, ensureUserDir, privateModeHeld } from "./user-dirs.mjs";
+import { envReader, mirrorEnv, setEnvName } from "./env-names.mjs";
 
 export const SETTINGS_VERSION = 1;
 
@@ -46,12 +47,19 @@ export const SETTINGS_VERSION = 1;
 export const SETTINGS = Object.freeze([
   // Connection loss is not permission to discard the R workspace. Timed
   // shutdown is opt-in; 0 retains an attached session until an explicit Quit.
-  { key: "linger_seconds", env: "CARMAR_LINGER", kind: "number", default: 0, min: 0, max: 86400, effect: "live", label: "Keep R running after all pages disconnect" },
-  { key: "history_enabled", env: "CARMAR_NO_HISTORY", kind: "bool", default: true, effect: "live", inverted: true, label: "Remember console history between sessions" },
-  { key: "analyze_budget_s", env: "CARMAR_ANALYZE_BUDGET", kind: "number", default: 3, min: 0, max: 60, effect: "next_launch", label: "Code-intelligence time budget" },
-  { key: "quarto_path", env: "CARMAR_QUARTO", kind: "path", default: "", effect: "live", label: "Quarto binary" },
-  { key: "rscript_path", env: "CARMAR_RSCRIPT", kind: "path", default: "", effect: "restart_r", label: "R binary" },
-  { key: "port", env: "CARMAR_PORT", kind: "number", default: 4747, min: 1024, max: 65535, effect: "next_launch", label: "Preferred port" },
+  { key: "linger_seconds", env: "BEATRINA_LINGER", kind: "number", default: 0, min: 0, max: 86400, effect: "live", label: "Keep R running after all pages disconnect" },
+  { key: "history_enabled", env: "BEATRINA_NO_HISTORY", kind: "bool", default: true, effect: "live", inverted: true, label: "Remember console history between sessions" },
+  { key: "analyze_budget_s", env: "BEATRINA_ANALYZE_BUDGET", kind: "number", default: 3, min: 0, max: 60, effect: "next_launch", label: "Code-intelligence time budget" },
+  { key: "quarto_path", env: "BEATRINA_QUARTO", kind: "path", default: "", effect: "live", label: "Quarto binary" },
+  { key: "rscript_path", env: "BEATRINA_RSCRIPT", kind: "path", default: "", effect: "restart_r", label: "R binary" },
+  { key: "port", env: "BEATRINA_PORT", kind: "number", default: 4747, min: 1024, max: 65535, effect: "next_launch", label: "Preferred port" },
+  // WHO IS WRITING. Machine scope, beside console history and the AI store,
+  // and deliberately NOT localStorage: every file:// page shares one origin,
+  // so a name kept there would be readable by any local HTML the user opens
+  // and would not follow them to a served page either. With no kernel there
+  // is no name, which is consistent — with no kernel there is no comment
+  // store to attribute anything in.
+  { key: "person_name", env: "BEATRINA_NAME", kind: "text", max: 120, default: "", effect: "live", label: "Your name" },
 ]);
 
 /**
@@ -60,37 +68,63 @@ export const SETTINGS = Object.freeze([
  * the refusal structural rather than a lookup someone can forget.
  */
 export const SETTINGS_ADMIN = Object.freeze([
-  "CARMAR_MANAGED_CONFIG",
-  "CARMAR_ROOT", "CARMAR_LOG", "CARMAR_LOG_AI_TEXT",
-  "CARMAR_CRAN_MIRROR",
-  "CARMAR_AI_LOCAL_ONLY", "CARMAR_AI_POLICY", "CARMAR_AI_PROVIDERS",
-  "CARMAR_BIND", "CARMAR_HOSTS", "CARMAR_ORIGINS", "CARMAR_REQUIRE_ORIGIN",
-  "CARMAR_TRUST_PROXY", "CARMAR_USER_HEADER", "CARMAR_TRUSTED_PROXY",
-  "CARMAR_ALLOW_UNAUTHENTICATED", "CARMAR_PORT_STRICT",
-  "CARMAR_UPDATE_FEED", "CARMAR_UPDATE_MIRROR", "CARMAR_UPDATE_OFFLINE_DIR",
-  "CARMAR_UPDATE_MANAGED",
+  "BEATRINA_MANAGED_CONFIG",
+  "BEATRINA_ROOT", "BEATRINA_LOG", "BEATRINA_LOG_AI_TEXT",
+  "BEATRINA_CRAN_MIRROR",
+  "BEATRINA_AI_LOCAL_ONLY", "BEATRINA_AI_POLICY", "BEATRINA_AI_PROVIDERS",
+  "BEATRINA_BIND", "BEATRINA_HOSTS", "BEATRINA_ORIGINS", "BEATRINA_REQUIRE_ORIGIN",
+  "BEATRINA_TRUST_PROXY", "BEATRINA_USER_HEADER", "BEATRINA_TRUSTED_PROXY",
+  "BEATRINA_ALLOW_UNAUTHENTICATED", "BEATRINA_PORT_STRICT",
+  "BEATRINA_UPDATE_FEED", "BEATRINA_UPDATE_MIRROR", "BEATRINA_UPDATE_OFFLINE_DIR",
+  "BEATRINA_UPDATE_MANAGED",
 ]);
 
-export const MANAGED_SETTINGS_SCHEMA = "carmar-managed-settings-v1";
+export const MANAGED_SETTINGS_SCHEMA = "beatrina-managed-settings-v1";
 export const MANAGED_SETTINGS_ENV = Object.freeze([...new Set([
   ...SETTINGS.map((s) => s.env),
-  ...SETTINGS_ADMIN.filter((n) => n !== "CARMAR_MANAGED_CONFIG"),
+  ...SETTINGS_ADMIN.filter((n) => n !== "BEATRINA_MANAGED_CONFIG"),
   "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
 ])]);
 
+// An administrator's file written for Beatrina 0.8.x: its schema string and
+// its keys spell the old product name. Both are read; `managedRead` reports
+// the values under the current names, and nothing writes the old ones.
+// beatrina-names: keep-start
+const LEGACY_MANAGED_SETTINGS_SCHEMA = "carmar-managed-settings-v1";
+const LEGACY_MANAGED_KEY = /^CARMAR_/;
+// beatrina-names: keep-end
+// A key is reported as itself when the vocabulary knows it, else under its current spelling.
+const currentKey = (k) => (MANAGED_SETTINGS_ENV.includes(k) ? k : k.replace(LEGACY_MANAGED_KEY, "BEATRINA_"));
+
 export const settingsEntry = (key) => SETTINGS.find((s) => s.key === key) || null;
 
-const sysEnv = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+// Dual-read (host/env-names.mjs): every `env:` name in SETTINGS is answered
+// under its older spelling too; the page (lib/settings/kernel-pane.js) keys its
+// admin rows on the same names, in the same spelling.
+const sysEnv = envReader(process.env);
 
 // ── managed configuration ───────────────────────────────────────────────────
 
-export function managedDefaultPath(env = sysEnv, platform = process.platform) {
-  if (platform === "darwin") return "/Library/Application Support/CarmaR/managed-settings.json";
+/** The places an administrator's file is looked for on this platform, the current one first. */
+export function managedDefaultPaths(env = sysEnv, platform = process.platform) {
+  if (platform === "darwin") {
+    return ["/Library/Application Support/Beatrina/managed-settings.json",
+      "/Library/Application Support/CarmaR/managed-settings.json"];   // beatrina-names: keep — a file deployed for 0.8.x
+  }
   if (platform === "win32") {
     const base = String(env("ProgramData", "")).trim() || "C:/ProgramData";
-    return path.join(base, "CarmaR", "managed-settings.json");
+    return [path.join(base, "Beatrina", "managed-settings.json"),
+      path.join(base, "CarmaR", "managed-settings.json")];   // beatrina-names: keep — a file deployed for 0.8.x
   }
-  return "/etc/carmar/managed-settings.json";
+  return ["/etc/beatrina/managed-settings.json",
+    "/etc/carmar/managed-settings.json"];   // beatrina-names: keep — a file deployed for 0.8.x
+}
+
+/** The administrator's file: the current path, unless only the older one exists. */
+export function managedDefaultPath(env = sysEnv, platform = process.platform) {
+  const [current, ...older] = managedDefaultPaths(env, platform);
+  if (fs.existsSync(current)) return current;
+  return older.find((p) => p !== current && fs.existsSync(p)) || current;
 }
 
 /**
@@ -120,12 +154,12 @@ export function managedProtected(file, platform = process.platform) {
 export function managedRead(file, { required = false, protection = managedProtected } = {}) {
   const empty = { status: "missing", path: file, values: {}, errors: [] };
   if (!fs.existsSync(file)) {
-    if (required) return { ...empty, status: "invalid", errors: ["CARMAR_MANAGED_CONFIG names a file that does not exist."] };
+    if (required) return { ...empty, status: "invalid", errors: ["BEATRINA_MANAGED_CONFIG names a file that does not exist."] };
     return empty;
   }
   if (protection(file) !== true) {
     return { ...empty, status: "insecure",
-      errors: ["The managed settings file is writable by the current account, is a symlink, or is not administrator-owned; CarmaR refused it."] };
+      errors: ["The managed settings file is writable by the current account, is a symlink, or is not administrator-owned; Beatrina refused it."] };
   }
   let size = NaN;
   try { size = fs.statSync(file).size; } catch { size = NaN; }
@@ -138,12 +172,12 @@ export function managedRead(file, { required = false, protection = managedProtec
   const rootNames = plain ? Object.keys(raw) : null;
   const settingsPlain = plain && raw.settings && typeof raw.settings === "object" && !Array.isArray(raw.settings);
   if (!rootNames || rootNames.length !== 2 || !rootNames.includes("schema") || !rootNames.includes("settings")
-      || raw.schema !== MANAGED_SETTINGS_SCHEMA || !settingsPlain) {
+      || ![MANAGED_SETTINGS_SCHEMA, LEGACY_MANAGED_SETTINGS_SCHEMA].includes(raw.schema) || !settingsPlain) {
     return { ...empty, status: "invalid",
       errors: [`The managed settings file must use schema ${MANAGED_SETTINGS_SCHEMA} with one settings object.`] };
   }
   const keys = Object.keys(raw.settings);
-  const unknown = keys.filter((k) => !MANAGED_SETTINGS_ENV.includes(k));
+  const unknown = keys.filter((k) => !MANAGED_SETTINGS_ENV.includes(currentKey(k)));
   const bad = keys.filter((k) => {
     const v = raw.settings[k];
     return !(typeof v === "string" && v.length > 0 && !/[\r\n\t]/.test(v));
@@ -153,7 +187,7 @@ export function managedRead(file, { required = false, protection = managedProtec
   if (bad.length) errors.push(`Managed settings must be non-empty single-line strings: ${bad.join(", ")}.`);
   if (errors.length) return { ...empty, status: "invalid", errors };
   const values = {};
-  for (const k of keys) values[k] = raw.settings[k];
+  for (const k of keys) values[currentKey(k)] = raw.settings[k];
   return { status: "ok", path: file, values, errors: [] };
 }
 
@@ -162,11 +196,13 @@ export function managedRead(file, { required = false, protection = managedProtec
  * every subsystem that follows resolves under the ordinary env-wins rule.
  */
 export function managedEnvironment({ env = sysEnv, file = null, protection = managedProtected, apply = true } = {}) {
-  const explicit = String(env("CARMAR_MANAGED_CONFIG", "")).trim();
+  const explicit = String(env("BEATRINA_MANAGED_CONFIG", "")).trim();
   const target = file || (explicit || managedDefaultPath(env));
   const result = managedRead(target, { required: Boolean(explicit), protection });
   if (apply && result.status === "ok") {
-    for (const [k, v] of Object.entries(result.values)) process.env[k] = v;
+    // Under BOTH spellings: a managed value must be what every reader sees,
+    // whichever prefix it asks for.
+    for (const [k, v] of Object.entries(result.values)) setEnvName(process.env, k, v);
   }
   return result;
 }
@@ -215,6 +251,18 @@ export function validateSetting(key, value) {
     if (entry.max != null && value > entry.max) return { ok: false, reason: `must be at most ${entry.max}` };
     return { ok: true, value: Number(value) };
   }
+  if (entry.kind === "text") {
+    if (typeof value !== "string") return { ok: false, reason: "must be a string" };
+    const text = value.trim();
+    const cap = entry.max == null ? 200 : entry.max;
+    if (text.length > cap) return { ok: false, reason: `must be at most ${cap} characters` };
+    // A control character is not a typo here: this value is written into
+    // JSON-lines logs (a comment's author), and a newline in one of those
+    // forges a record. `ai-audit` strips them for the same reason; a setting
+    // can refuse instead, because a person typed it and can be told.
+    if (/[\u0000-\u001f\u007f]/.test(text)) return { ok: false, reason: "must not contain control characters" };
+    return { ok: true, value: text };
+  }
   // path
   if (typeof value !== "string") return { ok: false, reason: "must be a string" };
   // An empty path means "use the ladder" — a legitimate value, not a missing
@@ -247,7 +295,7 @@ export function readSettingsFile(file = settingsPath()) {
     return { ...empty, status: "invalid", error: "The settings file could not be read as JSON." };
   }
   if (Math.trunc(Number(raw.version || 0)) !== SETTINGS_VERSION) {
-    return { ...empty, status: "invalid", error: "The settings file is a version this CarmaR does not know." };
+    return { ...empty, status: "invalid", error: "The settings file is a version this Beatrina does not know." };
   }
   const block = raw.settings == null ? {} : raw.settings;
   if (typeof block !== "object" || Array.isArray(block)) {
@@ -298,7 +346,7 @@ export function resolveSettings({ env = sysEnv, file = null } = {}) {
     if (fromEnv) {
       source = "env";
       if (s.kind === "bool") {
-        // CARMAR_NO_HISTORY is a NEGATIVE flag — any value means "off" — while
+        // BEATRINA_NO_HISTORY is a NEGATIVE flag — any value means "off" — while
         // the file and the UI hold the positive. Translating happens here, once.
         value = s.inverted ? false : true;
       } else if (s.kind === "number") {
@@ -330,10 +378,10 @@ export const settingsValue = (resolved, key) => (resolved.settings[key] ? resolv
 export function settingsChildEnv(resolved) {
   const out = {};
   const q = settingsValue(resolved, "quarto_path");
-  if (typeof q === "string" && q.length) out.CARMAR_QUARTO = q;
+  if (typeof q === "string" && q.length) out.BEATRINA_QUARTO = q;
   const b = settingsValue(resolved, "analyze_budget_s");
-  if (typeof b === "number") out.CARMAR_ANALYZE_BUDGET = String(b);
-  return out;
+  if (typeof b === "number") out.BEATRINA_ANALYZE_BUDGET = String(b);
+  return mirrorEnv(out);   // a child that still reads BEATRINA_QUARTO sees it
 }
 
 /**
@@ -359,7 +407,7 @@ export function createSettings({ env = sysEnv, applyManaged = true } = {}) {
     /** Which R the worker, the analyzer and every job child should run. */
     rscriptPreference() {
       const chosen = api.value("rscript_path");
-      return typeof chosen === "string" && chosen.length ? chosen : String(env("CARMAR_RSCRIPT", ""));
+      return typeof chosen === "string" && chosen.length ? chosen : String(env("BEATRINA_RSCRIPT", ""));
     },
     /**
      * The idle clock. The same safe default applies locally and behind a proxy:

package/host/update-record.mjs

@@ -8,12 +8,13 @@
 // puts `update_available` on /health and on the ready frame only when the recorded version is newer
 // than the build that is running, and the page says it (lib/info-pane.js, lib/doctor.js).
 //
-// CARMAR_NO_UPDATE_CHECK=1 or BEATRINA_NO_UPDATE_CHECK=1 turns the reading off as well as the asking
+// BEATRINA_NO_UPDATE_CHECK=1 (or its older spelling) turns the reading off as well as the asking
 // (the battery runner sets the first), so no test kernel reports a version some real run recorded.
 
 import fs from "node:fs";
 import path from "node:path";
 import { rUserDir } from "./user-dirs.mjs";
+import { readEnv } from "./env-names.mjs";
 
 /** -1, 0, 1 for semver-shaped versions; a pre-release sorts before its release; nonsense compares equal. */
 export function compareVersions(a, b) {
@@ -38,7 +39,7 @@ export function updateRecordFile(app) {
 
 /** The check is off: nothing is asked and nothing is read. */
 export function updateCheckOff(env = process.env) {
-  return env.BEATRINA_NO_UPDATE_CHECK === "1" || env.CARMAR_NO_UPDATE_CHECK === "1";
+  return readEnv(env, "NO_UPDATE_CHECK") === "1";
 }
 
 /**