beatrina 0.8.6 → 0.9.43

package/host/main.mjs

@@ -5,15 +5,18 @@
 // spike/serve.R does, so every launcher, fixture and agent that reads that
 // line works unchanged. Everything else goes to stderr.
 //
-// Env (the CARMAR_* names are the WIRE the page and its launchers speak; they
-// are kept on purpose — renaming them is WP7's job, with the launchers):
-//   CARMAR_PORT (4747), CARMAR_PORT_STRICT=1, CARMAR_BIND, CARMAR_HOSTS …
-//   (see deployment.mjs), CARMAR_RSCRIPT, CARMAR_KERNEL_BUILD,
-//   CARMAR_INSTALLED_BUILD, CARMAR_LOG, CARMAR_RUNTIME_DIR,
-//   CARMAR_NO_RUNTIME_FILE=1, CARMAR_LINGER, CARMAR_BOOT_GRACE,
-//   CARMAR_WORKER_DEADLINE_SCALE, CARMAR_WORKER_RESPAWN_MAX, CARMAR_OPEN_FILE,
-//   CARMAR_HOST_ROOT, CARMAR_KERNEL_DIR (WP7: where the files are when the
-//   host is not running from a source checkout — see hostRoot/kernelDir).
+// Env. The product's variables are `BEATRINA_*`; every one is still ACCEPTED
+// under its old `CARMAR_*` spelling (host/env-names.mjs — `env()` below reads
+// both, canonical first, and every call site may keep either spelling):
+//   BEATRINA_PORT (4747), BEATRINA_PORT_STRICT=1, BEATRINA_BIND,
+//   BEATRINA_HOSTS … (see deployment.mjs), BEATRINA_RSCRIPT,
+//   BEATRINA_KERNEL_BUILD, BEATRINA_INSTALLED_BUILD, BEATRINA_LOG,
+//   BEATRINA_RUNTIME_DIR (default ~/.beatrina/run; host/runtime-dir.mjs),
+//   BEATRINA_NO_RUNTIME_FILE=1, BEATRINA_LINGER, BEATRINA_BOOT_GRACE,
+//   BEATRINA_WORKER_DEADLINE_SCALE, BEATRINA_WORKER_RESPAWN_MAX,
+//   BEATRINA_OPEN_FILE, BEATRINA_HOST_ROOT, BEATRINA_KERNEL_DIR (WP7: where
+//   the files are when the host is not running from a source checkout — see
+//   hostRoot/kernelDir). Children are handed both spellings (mirrorEnv).
 //
 // PACKAGING (docs/packaging.md). Node's Single Executable Application runs its
 // main script as CommonJS — `embedderRunCjs`, measured on Node 25.5.0, an ESM
@@ -32,14 +35,18 @@ import { spawn } from "node:child_process";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
-import sea from "node:sea";
 import { fileURLToPath } from "node:url";
-import { carmarDeployment } from "./deployment.mjs";
+import { beatrinaDeployment } from "./deployment.mjs";
+import { envReader, envSetName, hasEnv, readEnv, unsetEnv } from "./env-names.mjs";
+import { runtimeWriteDir } from "./runtime-dir.mjs";
 import { REngine, detectRscript } from "./engine-r.mjs";
+import { payloadFingerprint, payloadGuardOn, guardFactory } from "./payload.mjs";
 import { PythonEngine, detectPython } from "./engine-python.mjs";
 import { JsEngine, detectNode } from "./engine-js.mjs";
 import { EnginePool } from "./engine-pool.mjs";
 import { createHostServer, secureToken } from "./server.mjs";
+import { gatewayCommands, loadGatewayToken } from "./gateway-token.mjs";
+import { decodeSessionDocuments, keepTokenOk, sessionDocumentsLabel } from "./session-keep.mjs";
 import { createSettings } from "./settings.mjs";
 // ── planes (one line per family; see the seam in server.mjs) ───────────────
 // Each work package registers its module here and nowhere else. Keep the
@@ -48,27 +55,28 @@ import { createSettings } from "./settings.mjs";
 import * as planeAiStore from "./planes/ai-store.mjs";
 import * as planeAi from "./planes/ai.mjs";
 import * as planeAnalyze from "./planes/analyze.mjs";
+import * as planeChoose from "./planes/choose.mjs";
 import * as planeCite from "./planes/cite.mjs";
 import * as planeLatex from "./planes/latex.mjs";
 import * as planeFiles from "./planes/files.mjs";
+import * as planeBundle from "./planes/bundle.mjs";
 import * as planeJobs from "./planes/jobs.mjs";
 import * as planeJournal from "./planes/journal.mjs";
 import * as planeMcp from "./planes/mcp.mjs";
 import * as planePair from "./planes/pair.mjs";
 import * as planePlugins from "./planes/plugins.mjs";
+import * as planeRecentDocuments from "./planes/recent-documents.mjs";
 import * as planeSessions from "./planes/sessions.mjs";
 import * as planeSettings from "./planes/settings.mjs";
 import * as planeTerminal from "./planes/terminal.mjs";
 import * as planeTestFile from "./planes/test-file.mjs";
 import * as planeUpdate from "./planes/update.mjs";
-import { appId } from "./user-dirs.mjs";
+import { appId, rUserDir } from "./user-dirs.mjs";
 import { updateAvailable, updateRecordFile } from "./update-record.mjs";
-const PLANE_MODULES = [planeAiStore, planeAi, planeAnalyze, planeCite, planeFiles, planeJobs, planeJournal, planeLatex, planeMcp, planePair, planePlugins, planeSessions, planeSettings, planeTerminal, planeTestFile, planeUpdate];
+const PLANE_MODULES = [planeAiStore, planeAi, planeAnalyze, planeBundle, planeChoose, planeCite, planeFiles, planeJobs, planeJournal, planeLatex, planeMcp, planePair, planePlugins, planeRecentDocuments, planeSessions, planeSettings, planeTerminal, planeTestFile, planeUpdate];
 
-const env = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const env = envReader(process.env);
 
-/** Whether this process is a packaged single executable, asked once. */
-const packaged = (() => { try { return sea.isSea(); } catch { return false; } })();
 
 /** This module's own directory — "" when the cjs bundler emptied import.meta. */
 function moduleDir() {
@@ -80,14 +88,16 @@ function moduleDir() {
  * Where the host's own files live.
  *
  * A source checkout answers from this module's location (host/.. = the repo).
- * A PACKAGED binary has no module path on disk, so it answers from the folder
- * it sits in — which is also the rule the page pin needs: `carmar_V<build>.html`
- * beside the binary, exactly as spike/notebook-page.R puts it beside kernel/.
+ * Anything with no module path on disk answers from the folder it sits in —
+ * which is also the rule the page pin needs: `beatrina_V<build>.html` beside
+ * the host, exactly as spike/notebook-page.R puts it beside kernel/. There was
+ * a `sea.isSea()` rung above this one; it dispatched to the SAME answer the
+ * moduleDir() fallback already gives, and the node:sea build it served is
+ * retired (f5979e5, 2026-09-16).
  */
 function hostRoot() {
-  const dictated = env("CARMAR_HOST_ROOT").trim();
+  const dictated = env("BEATRINA_HOST_ROOT").trim();
   if (dictated) return path.resolve(dictated);
-  if (packaged) return path.dirname(process.execPath);
   const mine = moduleDir();
   if (mine) return path.resolve(mine, "..");
   return path.dirname(process.execPath);
@@ -98,10 +108,10 @@ function hostRoot() {
  *
  * `spike/` in the repo; `kernel/` in every distribution, because that is what
  * tools/ship/build-r-pkg.sh and tools/app/build-app.sh have always called it.
- * Named by CARMAR_KERNEL_DIR when a launcher knows better.
+ * Named by BEATRINA_KERNEL_DIR when a launcher knows better.
  */
 function kernelDir(base) {
-  const dictated = env("CARMAR_KERNEL_DIR").trim();
+  const dictated = env("BEATRINA_KERNEL_DIR").trim();
   if (dictated) return path.resolve(dictated);
   for (const name of ["spike", "kernel"]) {
     if (fs.existsSync(path.join(base, name, "worker-boot.R"))) return path.join(base, name);
@@ -130,15 +140,15 @@ function sourceVersion() {
   return m ? m[1] : "unknown";
 }
 function readKernelBuild() {
-  const dictated = env("CARMAR_KERNEL_BUILD").trim();
+  const dictated = env("BEATRINA_KERNEL_BUILD").trim();
   if (dictated) return dictated;
   const stamp = path.join(spike, "kernel-version");
   if (fs.existsSync(stamp)) { const v = fs.readFileSync(stamp, "utf8").trim(); if (v) return v; }
   return sourceVersion();
 }
 function installedBuild() {
-  const dictated = env("CARMAR_KERNEL_BUILD").trim();
-  if (dictated) return env("CARMAR_INSTALLED_BUILD").trim() || dictated;
+  const dictated = env("BEATRINA_KERNEL_BUILD").trim();
+  if (dictated) return env("BEATRINA_INSTALLED_BUILD").trim() || dictated;
   const stamp = path.join(spike, "kernel-version");
   if (fs.existsSync(stamp)) { const v = fs.readFileSync(stamp, "utf8").trim(); if (v) return v; }
   return sourceVersion();
@@ -154,11 +164,16 @@ function installedBuild() {
  * alone, which is a difference in the fixture's eyes and not in the design's.
  */
 function notebookPage(build, { fallback = true } = {}) {
-  const wanted = `carmar_V${build}.html`;
+  const wanted = `beatrina_V${build}.html`;
   // serve.R's pin (spike/notebook-page.R): beside the KERNEL directory, not the
   // host's root — the two differ exactly when the kernel files are a staged or
-  // installed copy, which is the shape every upgrade has.
-  for (const p of [path.join(spike, "..", "dist", wanted), path.join(spike, "..", wanted)]) if (fs.existsSync(p)) return path.resolve(p);
+  // installed copy, which is the shape every upgrade has. Third, the copy the
+  // `beatrina` command keeps per version under the app's cache (tools/npm/bin/pages.mjs):
+  // npm replaces the package folder wholesale, so after `npm install -g beatrina@<next>`
+  // the page beside kernel/ is the NEW version's and a session still running the old one
+  // would serve the development index on every GET / (verified live 2026-09-16). The
+  // installed page beside kernel/ stays what the handoff and the "Restart into" door read.
+  for (const p of [path.join(spike, "..", "dist", wanted), path.join(spike, "..", wanted), path.join(rUserDir(appId(), "cache"), "pages", wanted)]) if (fs.existsSync(p)) return path.resolve(p);
   if (!fallback) return "";
   const dev = path.join(spike, "index.html");
   return fs.existsSync(dev) ? dev : "";
@@ -176,6 +191,41 @@ function notebookFileUrl(p, port, cap) {
   return `${prefix}${encodeURI(slashed)}#kernel=${port}${cap ? `&pair=${cap}` : ""}`;
 }
 
+// ── the handoff successor's preflight ───────────────────────────────────────
+/**
+ * Everything a successor needs to serve the session it is taking over, checked while the
+ * predecessor is still serving it: its page, its worker, and an R that runs. A protocol or build
+ * stamp that cannot be read has already thrown by the time this is called (main's first lines),
+ * which the predecessor sees as an exit before `ready`.
+ * @returns {Promise<{ok:boolean, error?:string, build:string, pid:number}>}
+ */
+async function handoffPreflight(kernelBuild, settings) {
+  const fail = (error) => ({ ok: false, error, build: kernelBuild, pid: process.pid });
+  if (!notebookPage(kernelBuild, { fallback: false })) return fail(`it has no notebook page for Beatrina ${kernelBuild}`);
+  if (!fs.existsSync(path.join(spike, "worker-boot.R"))) return fail(`its R worker is missing (${path.join(spike, "worker-boot.R")})`);
+  const rscript = detectRscript(settings.rscriptPreference());
+  if (!rscript) return fail("it cannot find R");
+  const { execFile } = await import("node:child_process");
+  const ran = await new Promise((resolve) => {
+    execFile(rscript, ["--version"], { timeout: 10000 }, (err, stdout, stderr) => {
+      resolve(err ? `${err.message}`.split("\n")[0] : /version \d/.test(`${stdout}${stderr}`) ? "" : "it did not say which R it is");
+    });
+  });
+  if (ran) return fail(`its R (${rscript}) would not run: ${ran}`);
+  return { ok: true, build: kernelBuild, pid: process.pid };
+}
+
+/** The ready file, replaced atomically so the predecessor never reads half of it. */
+function writeHandoffReady(file, verdict) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(verdict), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    console.error(`Beatrina: could not write the handoff ready file: ${e.message}`);
+  }
+}
+
 // ── the port: a preference by default, a promise when asked ────────────────
 const portTaken = (p) => new Promise((resolve) => {
   const s = net.connect({ port: p, host: "127.0.0.1" });
@@ -185,10 +235,10 @@ const portTaken = (p) => new Promise((resolve) => {
   s.once("timeout", () => { s.destroy(); resolve(false); });
 });
 async function choosePort() {
-  let wanted = Number.parseInt(env("CARMAR_PORT", "4747"), 10);
+  let wanted = Number.parseInt(env("BEATRINA_PORT", "4747"), 10);
   if (!Number.isInteger(wanted) || wanted < 1024 || wanted > 65535) wanted = 4747;
   if (!(await portTaken(wanted))) return wanted;
-  const waitS = Number(env("CARMAR_WAIT_PORT", "0"));
+  const waitS = Number(env("BEATRINA_WAIT_PORT", "0"));
   if (Number.isFinite(waitS) && waitS > 0) {
     const deadline = Date.now() + waitS * 1000;
     while (Date.now() < deadline) {                    // a wait is a loop
@@ -196,28 +246,50 @@ async function choosePort() {
       if (!(await portTaken(wanted))) return wanted;
     }
   }
-  if (env("CARMAR_PORT_STRICT") === "1") {
-    console.error(`Beatrina refuses to start: CARMAR_PORT=${wanted} is already in use and CARMAR_PORT_STRICT=1 forbids moving to another port.`);
+  if (env("BEATRINA_PORT_STRICT") === "1") {
+    console.error(`Beatrina refuses to start: ${envSetName(process.env, "PORT")}=${wanted} is already in use and ${envSetName(process.env, "PORT_STRICT")}=1 forbids moving to another port.`);
     process.exit(2);
   }
-  // Scan the session band, then let the OS pick.
-  for (let p = 4747; p <= 4947; p += 1) if (!(await portTaken(p))) return p;
+  // Scan the session band — BEATRINA_SESSION_BASE up, 4747..4947 by default, the ONE rule the
+  // sibling a page starts reads too (planes/sessions.mjs sessionBase) — from the WANTED port
+  // upward to the top, then from the base up to it, then let the OS pick. So a second `beatrina`
+  // (wanted 4848) is 4849, and 4747 — Beatrina's and the published pages' port, whose origin keys
+  // a browser's storage — is the last resort, not the first (docs/launch-menu-plan.md L2). With
+  // nothing set the default stays 4747, and a wanted port outside the band scans the band as before.
+  const base = planeSessions.sessionBase(env);
+  const top = base + planeSessions.SESSION_BAND - 1;
+  const order = wanted >= base && wanted <= top
+    ? [...range(wanted + 1, top), ...range(base, wanted - 1)]
+    : range(base, top);
+  for (const p of order) if (!(await portTaken(p))) return p;
   return 0;
 }
+/** The integers from `lo` to `hi`, both included; empty when `hi < lo`. */
+const range = (lo, hi) => Array.from({ length: Math.max(0, hi - lo + 1) }, (_, i) => lo + i);
 
 // The whole start-up is a FUNCTION, not a script: Node SEA runs its main as
 // CommonJS and esbuild refuses top-level await in cjs output (docs/packaging.md).
 // Nothing below may move back out to the module body.
 async function main() {
+  // A configured gateway is the sole runtime entry point, including on shared loopback.
+  const gatewayToken = loadGatewayToken(hasEnv(process.env, "GATEWAY_TOKEN_FILE") ? readEnv(process.env, "GATEWAY_TOKEN_FILE") : undefined);
+  // Neither worker environments nor tools launched by planes need this credential's path.
+  unsetEnv(process.env, "GATEWAY_TOKEN_FILE");
   const protocol = readProtocol();
   const kernelBuild = readKernelBuild();
+  // The payload this supervisor boots with, fingerprinted once: every worker it
+  // starts later is refused if the files under it have since been replaced
+  // (host/payload.mjs, docs/runplan.md R6).
+  const payloadGuard = payloadGuardOn(spike, env("BEATRINA_PAYLOAD_GUARD").trim());
+  const measurePayload = () => payloadFingerprint({ kernelDir: spike, root });
+  const bootPayload = payloadGuard ? measurePayload() : null;
   // A newer Beatrina on npm, as the `beatrina` command last recorded it (host/update-record.mjs):
-  // the host reads that record and never the registry. Null for CarmaR's doors, which write none.
+  // the host reads that record and never the registry. Null for Beatrina's doors, which write none.
   const newerOnNpm = () => updateAvailable({ file: updateRecordFile(appId()), current: kernelBuild });
   // WP5a — the user's settings, and the administrator's managed policy.
   // Created HERE, before the port and the deployment, because reading the managed
   // file puts its values into the environment (serve.R does the same at its line
-  // 63): CARMAR_PORT, CARMAR_HOSTS and CARMAR_BIND may all come from it, and the
+  // 63): BEATRINA_PORT, BEATRINA_HOSTS and BEATRINA_BIND may all come from it, and the
   // env-wins-and-locks rule is only a single source of truth if the environment
   // is already complete when the first subsystem reads it. Its errors refuse
   // startup for the deployment's reason: a governance control that silently
@@ -234,15 +306,27 @@ async function main() {
     for (const m of settings.errors) console.error(`Beatrina refuses to start: ${m}`);
     process.exit(2);
   }
+  // A handoff successor PROVES it can run before it waits for the port its predecessor still
+  // holds (planes/sessions.mjs handoffBegin, phase 1). The predecessor retires only on `ok`.
+  const handoffReady = env("BEATRINA_HANDOFF_READY").trim();
+  unsetEnv(process.env, "HANDOFF_READY");
+  if (handoffReady) {
+    const verdict = await handoffPreflight(kernelBuild, settings);
+    writeHandoffReady(handoffReady, verdict);
+    if (!verdict.ok) {
+      console.error(`Beatrina will not take over the session: ${verdict.error}`);
+      process.exit(2);
+    }
+  }
   const port = await choosePort();
-  const deployment = carmarDeployment(port, env);
+  const deployment = beatrinaDeployment(port, env);
   if (deployment.errors.length) {
     for (const m of deployment.errors) console.error(`Beatrina refuses to start: ${m}`);
     process.exit(2);
   }
 
   // ── the audit log ──────────────────────────────────────────────────────────
-  const logPath = env("CARMAR_LOG");
+  const logPath = env("BEATRINA_LOG");
   const audit = (event, fields = {}) => {
     if (!logPath) return;
     const rec = { ts: new Date().toISOString(), pid: process.pid, event, ...fields };
@@ -256,17 +340,17 @@ async function main() {
   // and tens of megabytes spent on a document that may hold no Python at all.
   const workerPath = path.join(spike, "worker-boot.R");
   const pythonWorker = path.join(root, "engines", "python", "worker.py");
-  const deadlineScale = Number(env("CARMAR_WORKER_DEADLINE_SCALE", "1")) > 0 ? Number(env("CARMAR_WORKER_DEADLINE_SCALE", "1")) : 1;
-  const respawnMax = Number.parseInt(env("CARMAR_WORKER_RESPAWN_MAX", "10"), 10) >= 1 ? Number.parseInt(env("CARMAR_WORKER_RESPAWN_MAX", "10"), 10) : 10;
+  const deadlineScale = Number(env("BEATRINA_WORKER_DEADLINE_SCALE", "1")) > 0 ? Number(env("BEATRINA_WORKER_DEADLINE_SCALE", "1")) : 1;
+  const respawnMax = Number.parseInt(env("BEATRINA_WORKER_RESPAWN_MAX", "10"), 10) >= 1 ? Number.parseInt(env("BEATRINA_WORKER_RESPAWN_MAX", "10"), 10) : 10;
   const childEnv = {};
-  if (env("CARMAR_ROOT")) childEnv.CARMAR_ROOT = env("CARMAR_ROOT");
+  if (env("BEATRINA_ROOT")) childEnv.BEATRINA_ROOT = env("BEATRINA_ROOT");
   // share()/use(): the one explicit bridge between the session's languages.
   // One 0700 directory per host, shared by every engine it starts, removed at
   // exit. A value crosses only when a chunk names it (engines/js/worker.mjs,
   // engines/r/handoff.R); nothing is ever copied implicitly.
   const handoffDir = fs.mkdtempSync(path.join(os.tmpdir(), "beatrix-handoff-"));
   fs.chmodSync(handoffDir, 0o700);
-  childEnv.CARMAR_HANDOFF_DIR = handoffDir;
+  childEnv.BEATRINA_HANDOFF_DIR = handoffDir;   // engineEnvironment mirrors it under the older spelling too
   process.on("exit", () => { try { fs.rmSync(handoffDir, { recursive: true, force: true }); } catch { /* best effort at exit */ } });
   const planes = PLANE_MODULES.map((mod) => (mod.createPlane ? mod.createPlane({ root, spike, env, audit, settings }) : mod.default));
   let servedCommands = [];
@@ -275,37 +359,40 @@ async function main() {
   // frame is what decides whether the page greys a {python} chunk, and a list
   // that filled in half a second later would grey it and then quietly change
   // its mind. Measured: 130–260 ms for the whole ladder.
-  const pythonFound = env("CARMAR_NO_PYTHON") === "1"
-    ? { available: false, detail: "The Python engine is disabled (CARMAR_NO_PYTHON=1).", searched: [] }
-    : await detectPython(process.env);
+  const pythonFound = env("BEATRINA_NO_PYTHON") === "1"
+    ? { available: false, detail: `The Python engine is disabled (${envSetName(process.env, "NO_PYTHON")}=1).`, searched: [] }
+    // The project rung of the ladder looks beside the document being opened,
+    // else beside the working directory (a `.venv` there is the user's answer).
+    : await detectPython(process.env, { root: env("BEATRINA_OPEN_FILE") ? path.dirname(env("BEATRINA_OPEN_FILE")) : process.cwd() });
   audit("engine-discovery", { engine: "python", available: pythonFound.available, detail: pythonFound.detail });
   const jsWorker = path.join(root, "engines", "js", "worker.mjs");
-  const nodeFound = env("CARMAR_NO_JS") === "1"
-    ? { available: false, detail: "The JavaScript engine is disabled (CARMAR_NO_JS=1).", path: "", version: "" }
-    : !packaged && !fs.existsSync(jsWorker)
+  const nodeFound = env("BEATRINA_NO_JS") === "1"
+    ? { available: false, detail: `The JavaScript engine is disabled (${envSetName(process.env, "NO_JS")}=1).`, path: "", version: "" }
+    : !fs.existsSync(jsWorker)
       ? { available: false, detail: `This Beatrina does not carry the JavaScript worker (${jsWorker}).`, path: "", version: "" }
-      : detectNode({ env: process.env, packaged });
+      : detectNode({ env: process.env });
   audit("engine-discovery", { engine: "js", available: nodeFound.available, detail: nodeFound.detail });
+  const pinned = (engine, make) => guardFactory(make, { enabled: payloadGuard, boot: bootPayload, bootBuild: kernelBuild, measure: measurePayload, audit, engine });
 
   const ENGINE_SPECS = [
     // WP5a — which R, and what the child inherits, come from the resolved
     // settings (`rscript_path`, the child env). Read per spawn, never
     // captured, so Restart R picks up a changed binary.
     { name: "r", label: "R", boot: "eager", available: true,
-      factory: () => new REngine({
+      factory: pinned("r", () => new REngine({
         workerPath, handoffScript: path.join(root, "engines", "r", "handoff.R"),
         rscript: detectRscript(settings.rscriptPreference()),
         env: { ...childEnv, ...settings.childEnv() },
-      }) },
+      })) },
     { name: "python", label: "Python", boot: "on-demand",
       available: pythonFound.available, detail: pythonFound.detail,
       version: pythonFound.version || "",
       runtime: { path: pythonFound.path || "", why: pythonFound.why || "", searched: pythonFound.searched },
-      factory: () => new PythonEngine({ workerPath: pythonWorker, python: pythonFound.path, env: { ...childEnv, ...settings.childEnv() } }) },
+      factory: pinned("python", () => new PythonEngine({ workerPath: pythonWorker, python: pythonFound.path, env: { ...childEnv, ...settings.childEnv() } })) },
     { name: "js", label: "JavaScript", boot: "on-demand",
       available: nodeFound.available, detail: nodeFound.detail, version: nodeFound.version || "",
       runtime: { path: nodeFound.path || "", why: nodeFound.detail },
-      factory: () => new JsEngine({ workerPath: jsWorker, node: nodeFound.path, selfHosted: Boolean(nodeFound.selfHosted), env: { ...childEnv, ...settings.childEnv() } }) },
+      factory: pinned("js", () => new JsEngine({ workerPath: jsWorker, node: nodeFound.path, env: { ...childEnv, ...settings.childEnv() } })) },
   ];
 
   // `/health r` before the worker is ready: ask the chosen Rscript once, in
@@ -332,10 +419,10 @@ async function main() {
       // Per engine, never merged: `commands` is a contract about what THIS
       // session answers, and lib/kernel-capability.js refuses an op by name on
       // the strength of it. The host's own verbs are added to the primary's.
-      commands: [...new Set([
+      commands: gatewayCommands([...new Set([
         ...(Array.isArray(frame.commands) ? frame.commands : [frame.commands]).filter(Boolean),
         ...(spec.name === plane.primaryName ? ["session_restart", ...servedCommands] : []),
-      ])],
+      ])], gatewayToken !== undefined),
       features: Array.isArray(frame.features) ? frame.features : (frame.features ? [frame.features] : []),
       engine: spec.name,
       language: frame.language || spec.name,
@@ -346,25 +433,53 @@ async function main() {
       host: "beatrix",
     }),
   });
+  // Set before the worker starts, so its first ready frame cannot arrive ahead of the token.
+  if (keepTokenOk(env("BEATRINA_RESUME_TOKEN"))) plane.setResumePending(env("BEATRINA_RESUME_TOKEN"));
+  unsetEnv(process.env, "RESUME_TOKEN");
   await plane.start();
 
   // ── the server ─────────────────────────────────────────────────────────────
   const bootAt = Date.now();
-  const fileLaunchCap = /^[A-Za-z0-9]{32}$/.test(env("CARMAR_FILE_LAUNCH_CAP")) ? env("CARMAR_FILE_LAUNCH_CAP") : secureToken(32);
-  delete process.env.CARMAR_FILE_LAUNCH_CAP;
+  const fileLaunchCap = /^[A-Za-z0-9]{32}$/.test(env("BEATRINA_FILE_LAUNCH_CAP")) ? env("BEATRINA_FILE_LAUNCH_CAP") : secureToken(32);
+  unsetEnv(process.env, "FILE_LAUNCH_CAP");
   let runtimeFile = "";
   // `app` says whose session this is (BEATRIX_APP_ID): a double-clicked document
-  // is handed to a running session of the SAME app, never to CarmaR's.
+  // is handed to a running session of the SAME app, never to Beatrina's.
   const runtimeRecord = { url: "", file: "", port, pid: process.pid, started: new Date(bootAt).toISOString(), host: "beatrix", app: appId() };
+  // Which gesture started this session (launch.sh's per-launch id and the door it came through,
+  // docs/runplan.md R5): "which double-click made this R?" is one grep across launches.log, this
+  // record and the audit log. Taken OUT of the environment so a sibling or a worker does not
+  // inherit a gesture that was not theirs.
+  const launchId = env("BEATRINA_LAUNCH_ID").trim().replace(/[^A-Za-z0-9._-]/g, "").slice(0, 64);
+  const launchVia = env("BEATRINA_LAUNCH_VIA").trim().replace(/[^A-Za-z0-9._-]/g, "").slice(0, 64);
+  unsetEnv(process.env, "LAUNCH_ID");
+  unsetEnv(process.env, "LAUNCH_VIA");
+  if (launchId) runtimeRecord.launch = launchId;
+  if (launchVia) runtimeRecord.launch_via = launchVia;
   // The document the session was started with, for `beatrina status`.
-  if (env("CARMAR_OPEN_FILE")) runtimeRecord.document = env("CARMAR_OPEN_FILE");
+  if (env("BEATRINA_OPEN_FILE")) runtimeRecord.document = env("BEATRINA_OPEN_FILE");
   // A successor started by a handoff keeps the session's name.
-  const inheritedTitle = env("CARMAR_SESSION_TITLE").trim();
+  const inheritedTitle = env("BEATRINA_SESSION_TITLE").trim();
   if (inheritedTitle) runtimeRecord.title = inheritedTitle.slice(0, 120);
-  const handoffFrom = env("CARMAR_HANDOFF_FROM").trim();
+  // A handoff successor starts with its predecessor's documents and, for "Restart, keep variables", the
+  // token its first worker restores (host/session-keep.mjs). Only a token travels, never a path.
+  const inheritedDocuments = decodeSessionDocuments(env("BEATRINA_SESSION_DOCUMENTS"));
+  unsetEnv(process.env, "SESSION_DOCUMENTS");
+  if (sessionDocumentsLabel(inheritedDocuments)) runtimeRecord.documents = sessionDocumentsLabel(inheritedDocuments);
+
+  const handoffFrom = env("BEATRINA_HANDOFF_FROM").trim();
+  // Why this returns the REASON and not just false: the record is how every
+  // other tool — `beatrina status`, the Sessions menu, the MCP bridge — learns
+  // this session exists, so a session that cannot write one is discoverable by
+  // nobody. It still serves (a notebook already open must not lose its R over
+  // a full disk), but it may not do so in silence: the caller says so on
+  // stderr and in the audit log. Swallowed until 2026-09-21, which is a
+  // running supervisor that no door can find and no line anywhere saying why.
+  let runtimeWriteError = "";
   const writeRuntime = () => {
     if (!runtimeFile) return false;
-    try { fs.writeFileSync(runtimeFile, JSON.stringify(runtimeRecord), { mode: 0o600 }); return true; } catch { return false; }
+    try { fs.writeFileSync(runtimeFile, JSON.stringify(runtimeRecord), { mode: 0o600 }); runtimeWriteError = ""; return true; }
+    catch (e) { runtimeWriteError = (e && e.message) || String(e); return false; }
   };
   let stopping = false;
   async function shutdown(reason) {
@@ -387,6 +502,7 @@ async function main() {
     process.exit(0);
   }
   const host = createHostServer({
+    gatewayToken,
     deployment, plane, audit, protocol, kernelBuild, installedBuild, updateAvailable: newerOnNpm, bootAt, app: appId(), fileLaunchCap, here: spike, planes,
     rVersionHint: () => rVersionHint,
     pagePath: () => notebookPage(kernelBuild),
@@ -395,7 +511,15 @@ async function main() {
     // session, so no fallback may answer "the installed build has a page".
     notebookPage: (build) => notebookPage(build, { fallback: false }), notebookFileUrl: (p, prt, cap) => notebookFileUrl(path.resolve(p), prt, cap),
     runtimeRecord: () => runtimeRecord, handoffFrom,
-    pendingOpen: env("CARMAR_OPEN_FILE") || null,
+    pendingOpen: env("BEATRINA_OPEN_FILE") || null,
+    sessionDocuments: inheritedDocuments,
+    // The menu helper names a session by its document ("SezerProfiles.qmd + 1 more").
+    onSessionDocuments: (documents) => {
+      const label = sessionDocumentsLabel(documents);
+      if ((runtimeRecord.documents || "") === label) return;
+      if (label) runtimeRecord.documents = label; else delete runtimeRecord.documents;
+      writeRuntime();
+    },
     onShutdown: (reason) => shutdown(reason || "explicit Quit request"),
     onPageTitle: (title) => {
       // eslint-disable-next-line no-control-regex
@@ -431,21 +555,37 @@ async function main() {
   const fileUrl = page ? notebookFileUrl(path.resolve(page), boundPort, fileLaunchCap) : "";
   runtimeRecord.url = url;
   runtimeRecord.file = fileUrl;
-  if (env("CARMAR_LISTEN") === "1") runtimeRecord.listen = true;
-  if (env("CARMAR_NO_RUNTIME_FILE") !== "1") {
-    const dir = env("CARMAR_RUNTIME_DIR") || path.join(os.homedir(), ".carmar", "run");
-    try { fs.mkdirSync(dir, { recursive: true }); runtimeFile = path.join(dir, `kernel-${boundPort}.json`); } catch { runtimeFile = ""; }
+  if (env("BEATRINA_LISTEN") === "1") runtimeRecord.listen = true;
+  if (env("BEATRINA_NO_RUNTIME_FILE") !== "1") {
+    const dir = runtimeWriteDir(process.env);
+    try { fs.mkdirSync(dir, { recursive: true }); runtimeFile = path.join(dir, `kernel-${boundPort}.json`); }
+    catch (e) { runtimeFile = ""; runtimeWriteError = (e && e.message) || String(e); }
     if (runtimeFile && !writeRuntime()) runtimeFile = "";
+    if (!runtimeFile) {
+      // Serving and undiscoverable: say it once, where a person and the log
+      // both see it. `BEATRINA_NO_RUNTIME_FILE=1` is the way to ask for this
+      // on purpose, and takes the branch above instead of this one.
+      const detail = runtimeWriteError || "the directory could not be created";
+      console.error(`Beatrina: this session could not write its discovery record in ${dir} (${detail}). `
+        + "It is serving, but `beatrina status`, the Sessions menu and the agent (MCP) bridge will not find it.");
+      audit("runtime-record-failed", { dir, port: boundPort, detail });
+    }
   }
   audit("listening", { bind: deployment.bind, port: boundPort, loopback: deployment.loopback, require_origin: deployment.require_origin, host: "beatrix" });
-  audit("started", { port: boundPort, root: env("CARMAR_ROOT") });
+  audit("started", { port: boundPort, root: env("BEATRINA_ROOT"), launch: launchId || null, launch_via: launchVia || null });
   process.stdout.write(`${JSON.stringify({ url, file: fileUrl })}\n`);
   // --open: open the notebook FILE, as serve.R did for the double-click
-  // launchers. The kernel stays hidden plumbing. CARMAR_OPENER is the seam a
-  // test uses so nothing opens on a real desktop.
-  if (process.argv.slice(2).includes("--open")) {
-    const target = fileUrl || url;
-    const opener = String(process.env.CARMAR_OPENER || "");
+  // launchers. --open=url opens the page THIS kernel serves instead
+  // (http://127.0.0.1:<port>/): the one origin the socket allows outright, so
+  // the page connects with no fragment and no pairing. The `beatrina` command
+  // uses it, because macOS `open` and Finder drop a file URL's #kernel=…&pair=…
+  // fragment and the page then cannot find its kernel ("needs R", 2026-09-16).
+  // The kernel stays hidden plumbing. BEATRINA_OPENER is the seam a test uses so
+  // nothing opens on a real desktop.
+  const openArg = process.argv.slice(2).find((a) => a === "--open" || a === "--open=url" || a === "--open=file");
+  if (openArg) {
+    const target = openArg === "--open=url" ? url : (fileUrl || url);
+    const opener = readEnv(process.env, "OPENER");
     try {
       const child = path.isAbsolute(opener) ? spawn(opener, [target], { stdio: "ignore", detached: true })
         : process.platform === "darwin" ? spawn("open", [target], { stdio: "ignore", detached: true })
@@ -461,13 +601,13 @@ async function main() {
   // grace instead, so an unopened launch does not leave an R behind — unless the
   // setting is explicitly 0, which says "headless, keep".
   //
-  // WP5a — the clock reads the RESOLVED setting rather than CARMAR_LINGER, so the
+  // WP5a — the clock reads the RESOLVED setting rather than BEATRINA_LINGER, so the
   // user's settings.json can turn it on and Settings can change it live. "Still
   // at its default" is the exact rule serve.R's resolve_linger() uses for "never
   // reap": an explicit 0 from the env or the file is a CHOICE and is honoured as
   // one, which is why it is `source === "default"` and not `value === 0`. Read
   // per tick, never captured, so a settings_set takes effect without a restart.
-  const bootGraceS = Number.isFinite(Number(env("CARMAR_BOOT_GRACE", "180"))) ? Number(env("CARMAR_BOOT_GRACE", "180")) : 180;
+  const bootGraceS = Number.isFinite(Number(env("BEATRINA_BOOT_GRACE", "180"))) ? Number(env("BEATRINA_BOOT_GRACE", "180")) : 180;
   let idleSince = null;
   setInterval(() => {
     const lingerS = settings.lingerSeconds();