beatrina 0.8.7 → 0.9.43

package/host/planes/update.mjs

@@ -1,7 +1,7 @@
 // update.mjs — signed product updates: two ops, and a very narrow API.
 //
 // A port of the `update_*` half of spike/serve.R. The updater is a
-// PRODUCT-OWNED SCRIPT injected by the launcher (`CARMAR_UPDATE_SCRIPT`). The
+// PRODUCT-OWNED SCRIPT injected by the launcher (`BEATRINA_UPDATE_SCRIPT`). The
 // browser never supplies a path or a command line: it may name one action from
 // a fixed four-word vocabulary, and the supervisor starts that exact script
 // directly, as an argument vector.
@@ -10,7 +10,7 @@
 // not poll a feed and has no clock of its own — that belongs to the R package's
 // `check_upgrade()`, once a day, at a door the person opened. All this plane
 // can do is read the script's six-field status record and ask it to act, which
-// is why `CARMAR_NO_UPDATE_CHECK=1` holds here trivially: with no script there
+// is why `BEATRINA_NO_UPDATE_CHECK=1` holds here trivially: with no script there
 // is no process, and with a script there is still no feed.
 //
 // Who may ask: page-only in BOTH senses (agentRefused at the seam,
@@ -28,12 +28,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
+import { whichSync } from "../which.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
 
-const PAGE_ONLY_CLASSES = ["served", "file", "local"];
 const OPS = ["update_status", "update_action"];
 const AGENT_WHY = {
   update_status: "Agents cannot inspect desktop update state.",
-  update_action: "Agents cannot install, defer, or roll back CarmaR.",
+  update_action: "Agents cannot install, defer, or roll back Beatrina.",
 };
 const ACTIONS = ["check", "defer", "install", "rollback"];
 const STATES = ["unknown", "current", "available", "deferred", "installing",
@@ -55,14 +56,6 @@ export function updateRunnerSpec(script, args = [], platform = process.platform)
   return { command: "/bin/sh", args: [script, ...args] };
 }
 
-function whichSync(name) {
-  for (const dir of String(process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
-    const cand = path.join(dir, name);
-    try { fs.accessSync(cand, fs.constants.X_OK); return cand; } catch { /* next */ }
-  }
-  return "";
-}
-
 // eslint-disable-next-line no-control-regex
 const updateText = (x, max = 240) => String(x ?? "").replace(/[\x00-\x1f\x7f]/g, " ").slice(0, max).trim();
 const updateVersion = (x) => {
@@ -74,7 +67,7 @@ export function createPlane({ env, audit }) {
   const job = { proc: null, action: "", started: 0 };
 
   const scriptPath = (deployment) => {
-    const script = env("CARMAR_UPDATE_SCRIPT", "").trim();
+    const script = env("BEATRINA_UPDATE_SCRIPT", "").trim();
     if (deployment.loopback !== true || !script || !fs.existsSync(script)) return "";
     const real = fs.realpathSync(script);
     return updateRunnerSpec(real) ? real : "";

package/host/plugin-store.mjs

@@ -9,8 +9,8 @@
 //
 // Three layers, searched in order, exactly as .libPaths() is:
 //
-//   user     R_user_dir("carmar","data")/plugins/<kind>/<id>/   the ONLY layer written
-//   system   $CARMAR_PLUGIN_DIR/<kind>/<id>/                     an administrator's, read-only
+//   user     R_user_dir("beatrina","data")/plugins/<kind>/<id>/   the ONLY layer written
+//   system   $BEATRINA_PLUGIN_DIR/<kind>/<id>/                     an administrator's, read-only
 //   shipped  <kernel>/plugins/<kind>/<id>/                       the bundle's, read-only
 //
 // The first OK copy of an id wins. A BROKEN copy never wins: integrity is
@@ -32,15 +32,20 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { appId } from "./user-dirs.mjs";
+import { appId, rUserDir } from "./user-dirs.mjs";
 
 export const PLUGIN_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 export const PLUGIN_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export const PLUGIN_MANIFEST = "plugin.json";
 export const PLUGIN_MANIFEST_MAX_BYTES = 65536;
 export const PLUGIN_FETCH_TIMEOUT_S = 20;
-export const PLUGIN_POLICY_DEFAULT_FILE = "/etc/carmar/plugin-policy.json";
-export const PLUGIN_SYSTEM_DEFAULT_DIR = "/etc/carmar/plugins";
+export const PLUGIN_POLICY_DEFAULT_FILE = "/etc/beatrina/plugin-policy.json";
+export const PLUGIN_SYSTEM_DEFAULT_DIR = "/etc/beatrina/plugins";
+// Where an administrator deployed them for Beatrina 0.8.x: read when the current path is absent.
+// beatrina-names: keep-start
+const LEGACY_PLUGIN_POLICY_FILE = "/etc/carmar/plugin-policy.json";
+const LEGACY_PLUGIN_SYSTEM_DIR = "/etc/carmar/plugins";
+// beatrina-names: keep-end
 
 /** A CROSS-LANGUAGE CONTRACT with `EDITOR_TOKENS` in lib/editor-themes.js. */
 export const THEME_TOKENS = Object.freeze([
@@ -130,8 +135,8 @@ export function cslLooksLikeStyle(file) {
 }
 
 /** The registry a `csl` install fetches by name from. Env-driven, as in R. */
-export const cslIndexUrl = (env) => env("CARMAR_CSL_INDEX_URL", "https://www.zotero.org/styles-files/styles.json");
-export const cslStyleBase = (env) => env("CARMAR_CSL_STYLE_BASE", "https://www.zotero.org/styles/");
+export const cslIndexUrl = (env) => env("BEATRINA_CSL_INDEX_URL", "https://www.zotero.org/styles-files/styles.json");
+export const cslStyleBase = (env) => env("BEATRINA_CSL_STYLE_BASE", "https://www.zotero.org/styles/");
 
 /* ── the kinds table ──────────────────────────────────────────────────────
  *
@@ -288,37 +293,12 @@ export function urlHost(url) {
   return m[0].replace(/^https?:\/\//, "").replace(/:[0-9]+$/, "").toLowerCase();
 }
 
-/**
- * `tools::R_user_dir(pkg, which)`, in JavaScript.
- *
- * The whole plugin store, the CSL index cache and every test that relocates
- * them turn on this function agreeing with R's, so it is a transcription of
- * R 4.5's source rather than a guess: the env var, then XDG, then the
- * platform's own place, then `R/<package>` under it.
- */
-export function rUserDir(pkg, which, env) {
-  const home = os.homedir();
-  const win = process.platform === "win32";
-  const mac = process.platform === "darwin";
-  let p = "";
-  if (which === "data") {
-    p = env("R_USER_DATA_DIR") || env("XDG_DATA_HOME")
-      || (win ? path.join(env("APPDATA"), "R", "data")
-        : mac ? path.join(home, "Library", "Application Support", "org.R-project.R")
-          : path.join(home, ".local", "share"));
-  } else if (which === "cache") {
-    p = env("R_USER_CACHE_DIR") || env("XDG_CACHE_HOME")
-      || (win ? path.join(env("LOCALAPPDATA"), "R", "cache")
-        : mac ? path.join(home, "Library", "Caches", "org.R-project.R")
-          : path.join(home, ".cache"));
-  } else {
-    p = env("R_USER_CONFIG_DIR") || env("XDG_CONFIG_HOME")
-      || (win ? path.join(env("APPDATA"), "R", "config")
-        : mac ? path.join(home, "Library", "Preferences", "org.R-project.R")
-          : path.join(home, ".config"));
-  }
-  return path.join(p, "R", pkg);
-}
+// rUserDir is IMPORTED. Both copies described themselves as faithful
+// transcriptions of R 4.5's tools::R_user_dir, and they had already diverged on
+// the fall-through branch — this one answered "config" where the other answered
+// "cache" for an unrecognised `which`. Two transcriptions of one R function that
+// already disagree is the definition of drift, and host/user-dirs.mjs explains
+// at length why the host must not invent a second layout.
 
 /* ── the administrator's policy ──────────────────────────────────────────── */
 
@@ -333,7 +313,7 @@ export function rUserDir(pkg, which, env) {
  *   network:boolean, kinds:string[], unknown:string[], note:string,
  *   system_dir:string, errors:string[]}}
  */
-export function carmarPluginPolicy(env, {
+export function beatrinaPluginPolicy(env, {
   defaultFile = PLUGIN_POLICY_DEFAULT_FILE, defaultDir = PLUGIN_SYSTEM_DEFAULT_DIR,
 } = {}) {
   const kinds_table = pluginKinds(env);
@@ -344,19 +324,22 @@ export function carmarPluginPolicy(env, {
   let sourcesRaw = null;
   let kindsRaw = null;
   let note = "";
-  let systemDir = env("CARMAR_PLUGIN_DIR", "").trim();
+  let systemDir = env("BEATRINA_PLUGIN_DIR", "").trim();
   if (!systemDir && defaultDir && dirExists(defaultDir)) systemDir = defaultDir;
+  // The older deployment path counts only for the default, never for a caller's own.
+  if (!systemDir && defaultDir === PLUGIN_SYSTEM_DEFAULT_DIR && dirExists(LEGACY_PLUGIN_SYSTEM_DIR)) systemDir = LEGACY_PLUGIN_SYSTEM_DIR;
 
-  let file = env("CARMAR_PLUGIN_POLICY", "").trim();
+  let file = env("BEATRINA_PLUGIN_POLICY", "").trim();
   if (!file && defaultFile && fileExists(defaultFile)) file = defaultFile;
+  if (!file && defaultFile === PLUGIN_POLICY_DEFAULT_FILE && fileExists(LEGACY_PLUGIN_POLICY_FILE)) file = LEGACY_PLUGIN_POLICY_FILE;
   if (file) {
     source = file;
     if (!fileExists(file)) {
-      errors.push(`CARMAR_PLUGIN_POLICY names a file that does not exist: ${file}`);
+      errors.push(`BEATRINA_PLUGIN_POLICY names a file that does not exist: ${file}`);
     } else {
       let doc = null;
       try { doc = JSON.parse(fs.readFileSync(file, "utf8")); }
-      catch (e) { errors.push(`CARMAR_PLUGIN_POLICY is not valid JSON: ${e.message}`); }
+      catch (e) { errors.push(`BEATRINA_PLUGIN_POLICY is not valid JSON: ${e.message}`); }
       if (doc && typeof doc === "object") {
         install = String(doc.install ?? "").trim();
         if (doc.sources != null) sourcesRaw = [].concat(doc.sources).map(String);
@@ -367,9 +350,9 @@ export function carmarPluginPolicy(env, {
       }
     }
   } else {
-    if (env("CARMAR_PLUGIN_INSTALL", "")) { source = "env"; install = env("CARMAR_PLUGIN_INSTALL", "").trim(); }
-    if (env("CARMAR_PLUGIN_SOURCES", "")) { source = "env"; sourcesRaw = policySplit(env("CARMAR_PLUGIN_SOURCES", "")); }
-    if (env("CARMAR_PLUGIN_KINDS", "")) { source = "env"; kindsRaw = policySplit(env("CARMAR_PLUGIN_KINDS", "")); }
+    if (env("BEATRINA_PLUGIN_INSTALL", "")) { source = "env"; install = env("BEATRINA_PLUGIN_INSTALL", "").trim(); }
+    if (env("BEATRINA_PLUGIN_SOURCES", "")) { source = "env"; sourcesRaw = policySplit(env("BEATRINA_PLUGIN_SOURCES", "")); }
+    if (env("BEATRINA_PLUGIN_KINDS", "")) { source = "env"; kindsRaw = policySplit(env("BEATRINA_PLUGIN_KINDS", "")); }
   }
 
   if (!install) install = "user";
@@ -432,11 +415,11 @@ export function pluginDefaultHosts(env) {
 /** The sentence shown when the policy refuses something. */
 export function pluginPolicyReason(policy, what = "install") {
   const base = {
-    install: "This CarmaR is configured so that plugins are not installed by users; the set is fixed by the deployment.",
-    network: "This CarmaR is configured to fetch no plugins from the network; a plugin arrives as a file.",
-    host: `This CarmaR is configured to fetch plugins only from: ${policy.sources.join(", ")}.`,
-    kind: "This CarmaR is configured without that plugin kind.",
-  }[what] || "This CarmaR's plugin policy refuses that.";
+    install: "This Beatrina is configured so that plugins are not installed by users; the set is fixed by the deployment.",
+    network: "This Beatrina is configured to fetch no plugins from the network; a plugin arrives as a file.",
+    host: `This Beatrina is configured to fetch plugins only from: ${policy.sources.join(", ")}.`,
+    kind: "This Beatrina is configured without that plugin kind.",
+  }[what] || "This Beatrina's plugin policy refuses that.";
   return policy.note ? `${base} ${policy.note}` : base;
 }
 
@@ -833,6 +816,6 @@ export function pluginPolicyDisclosure(here, policy, env) {
 /** ONE policy per host process, as serve.R has ONE `plugin_policy`. */
 let cachedPolicy = null;
 export function pluginPolicyOnce(env, opts) {
-  if (!cachedPolicy) cachedPolicy = carmarPluginPolicy(env, opts);
+  if (!cachedPolicy) cachedPolicy = beatrinaPluginPolicy(env, opts);
   return cachedPolicy;
 }

package/host/recent-documents.mjs

@@ -0,0 +1,124 @@
+// recent-documents.mjs — the rules of the machine's list of documents this
+// person opened, with no file system in them.
+//
+// One record per document: `{name, path, when}` — the name a row shows, the
+// ABSOLUTE path a reopen reads, and the millisecond clock of the last time it
+// was opened or saved. Newest first, one row per path, twenty deep.
+//
+// These rules are the page's (lib/recent-files.js), written a second time in
+// the host, and test/recent-documents.test.mjs pins the two equal on the same
+// inputs. The page keeps a cache of the list in its origin's storage and hands
+// it over once per connection (`merge`), so a page and a host that disagreed
+// about what a valid row is, or which of two rows of one path wins, would
+// merge into a list neither of them wrote. Keep the two files in step.
+//
+// Pure: every function takes a list and returns a new one; `now` is a
+// parameter so a test can pin what the clock does.
+
+export const RECENT_DOCUMENTS_MAX = 20;
+const PATH_MAX = 4096;
+const NAME_MAX = 255;
+
+// A POSIX root, a Windows drive (`C:\` or `C:/`) or a UNC share. The kernel
+// hands the page resolved absolute paths, so a relative one is a row that was
+// never openable — a picker's bare filename, a typo — and is dropped.
+const ABSOLUTE_PATH = /^(\/|[A-Za-z]:[\\/]|\\\\)/;
+
+const baseName = (p) => String(p || "").replace(/[\\/]+$/, "").split(/[\\/]/).pop();
+
+/**
+ * One record as the list keeps it, or null when it could not be reopened.
+ *
+ * The path must be absolute, printable and bounded; the name is trimmed,
+ * stripped of line breaks and bounded, and falls back to the path's last
+ * segment; `when` is a positive millisecond clock, else `now`.
+ *
+ * @param {*} entry
+ * @param {number} [now]
+ * @returns {{name:string, path:string, when:number}|null}
+ */
+export function cleanRecentDocument(entry, now = Date.now()) {
+  if (!entry || typeof entry !== "object") return null;
+  const path = typeof entry.path === "string" ? entry.path : "";
+  if (!path || path.length > PATH_MAX || /[\r\n\0]/.test(path) || !ABSOLUTE_PATH.test(path)) return null;
+  const rawName = typeof entry.name === "string" ? entry.name.replace(/[\r\n\0]/g, " ").trim() : "";
+  const name = (rawName || baseName(path) || path).slice(0, NAME_MAX);
+  const clock = Number(entry.when);
+  const when = Number.isFinite(clock) && clock > 0 ? Math.floor(clock) : now;
+  return { name, path, when };
+}
+
+/**
+ * The list as it is kept: invalid rows dropped, one row per path — the one
+ * with the newest `when` wins, and on a tie the one that came FIRST — newest
+ * first, capped at RECENT_DOCUMENTS_MAX.
+ *
+ * The tie rule is what makes `note` deterministic: a row just noted is put in
+ * front with the clock's value, and two notes within one millisecond keep
+ * their order rather than being re-sorted by path. The sort is stable, so
+ * rows of one `when` keep the order they arrived in.
+ *
+ * @param {Array} list
+ * @param {number} [now]
+ * @returns {Array<{name:string, path:string, when:number}>}
+ */
+export function cleanRecentDocuments(list, now = Date.now()) {
+  const byPath = new Map();
+  (Array.isArray(list) ? list : []).forEach((raw) => {
+    const row = cleanRecentDocument(raw, now);
+    if (!row) return;
+    const have = byPath.get(row.path);
+    if (!have || row.when > have.when) byPath.set(row.path, row);
+  });
+  return [...byPath.values()].sort((a, b) => b.when - a.when).slice(0, RECENT_DOCUMENTS_MAX);
+}
+
+/** How many rows of `list` `cleanRecentDocuments` would drop as unopenable. */
+export function countUnopenable(list, now = Date.now()) {
+  return (Array.isArray(list) ? list : []).filter((raw) => !cleanRecentDocument(raw, now)).length;
+}
+
+/**
+ * Remember a document: it goes to the top, stamped `now`, and any older row
+ * of the same path goes.
+ *
+ * @param {Array} list
+ * @param {{name?:string, path:string}} document
+ * @param {number} [now]
+ */
+export function noteRecentDocument(list, document, now = Date.now()) {
+  const row = cleanRecentDocument({ ...(document || {}), when: now }, now);
+  if (!row) return cleanRecentDocuments(list, now);
+  return cleanRecentDocuments([row, ...(Array.isArray(list) ? list : [])], now);
+}
+
+/**
+ * Drop one path. Clearing the whole list was the only deletion once, so a
+ * document that had moved could be removed only by throwing away the others.
+ *
+ * @param {Array} list
+ * @param {string} path
+ * @param {number} [now]
+ */
+export function forgetRecentDocument(list, path, now = Date.now()) {
+  const gone = String(path || "");
+  return cleanRecentDocuments(list, now).filter((row) => row.path !== gone);
+}
+
+/**
+ * Two lists as one: every path of either, the newer row of each, newest
+ * first, capped. `a` comes first so that on a tie of `when` its row wins —
+ * the host passes the machine's list as `a` and a page's cache as `b`.
+ *
+ * @param {Array} a
+ * @param {Array} b
+ * @param {number} [now]
+ */
+export function mergeRecentDocuments(a, b, now = Date.now()) {
+  return cleanRecentDocuments([...(Array.isArray(a) ? a : []), ...(Array.isArray(b) ? b : [])], now);
+}
+
+export default {
+  RECENT_DOCUMENTS_MAX, cleanRecentDocument, cleanRecentDocuments, countUnopenable,
+  noteRecentDocument, forgetRecentDocument, mergeRecentDocuments,
+};

package/host/runtime-dir.mjs

@@ -0,0 +1,47 @@
+// runtime-dir.mjs — where a running kernel leaves its `kernel-<port>.json`.
+// beatrina-names: keep-file — this module reads the older directory on purpose.
+//
+// The product's runtime directory is `~/.beatrina/run` (`BEATRINA_RUNTIME_DIR`
+// names another; `CARMAR_RUNTIME_DIR` is still accepted, host/env-names.mjs).
+// Until 2026-09-16 it was `~/.carmar/run`, and a kernel started by an older
+// launcher, or one still running from before the rename, wrote its record
+// THERE. So the two questions have two answers:
+//
+//   · WRITE goes to one directory: the explicit one, else `~/.beatrina/run`.
+//   · READ (the Sessions pane, `beatrina status`/`stop`, the MCP bridge's
+//     discovery) covers both, the current first, so a session is never lost
+//     to the rename. An EXPLICIT directory is read alone: a test that
+//     relocates the records must not see the user's real sessions.
+//
+// It is deliberately not keyed on the app id (host/user-dirs.mjs says why: it
+// is how every tool finds every running kernel).
+
+import os from "node:os";
+import path from "node:path";
+import { readEnv } from "./env-names.mjs";
+
+export const RUNTIME_DIR_CURRENT = [".beatrina", "run"];
+export const RUNTIME_DIR_LEGACY = [".carmar", "run"];
+
+/**
+ * @param {Record<string,string|undefined>|((name: string, unset?: string) => string)} [env]
+ *   process.env, or a `Sys.getenv`-style getter
+ * @param {string} [home]
+ * @returns {{write: string, read: string[], explicit: boolean}}
+ */
+export function runtimeDirs(env = process.env, home = os.homedir()) {
+  const explicit = readEnv(env, "RUNTIME_DIR").trim();
+  if (explicit) return { write: explicit, read: [explicit], explicit: true };
+  const current = path.join(home, ...RUNTIME_DIR_CURRENT);
+  return { write: current, read: [current, path.join(home, ...RUNTIME_DIR_LEGACY)], explicit: false };
+}
+
+/** The one directory a new record is written to. */
+export function runtimeWriteDir(env = process.env, home = os.homedir()) {
+  return runtimeDirs(env, home).write;
+}
+
+/** Every directory a record may be read from, current first. */
+export function runtimeReadDirs(env = process.env, home = os.homedir()) {
+  return runtimeDirs(env, home).read;
+}

package/host/server.mjs

@@ -31,8 +31,10 @@ 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",
@@ -40,8 +42,6 @@ export const FORWARDED = Object.freeze(["env", "obj", "struct", "view", "colstat
   // 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"]);
-export const SESSION_CONTROLS = Object.freeze(["exec", "interrupt", "force_stop", "restart", "runstate", "runs", "adopt",
-  "input_reply", "debug_cmd"]);
 /** 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",
@@ -55,7 +55,9 @@ export const NOT_YET = Object.freeze({
 });
 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"]);
+  "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({
@@ -63,6 +65,7 @@ export const AGENT_WHY = Object.freeze({
   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";
@@ -88,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;
@@ -100,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)
@@ -113,9 +123,15 @@ 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}
@@ -124,7 +140,19 @@ export function createHostServer(opts) {
     // 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)));
 
@@ -226,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;
@@ -243,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": "*" });
@@ -271,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);
@@ -291,13 +328,16 @@ 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") {
@@ -340,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;
@@ -455,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);
@@ -479,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

@@ -7,7 +7,7 @@
 //     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 CarmaR's R supervisor sources; pinned against
+// (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";