beatrina 0.8.7 → 0.9.43

package/host/payload.mjs

@@ -0,0 +1,131 @@
+// payload.mjs — the files a supervisor starts its workers from, and whether
+// they are still the files it booted with.
+//
+// The fault this exists for (docs/runplan.md R6): an install replaces the app's
+// files IN PLACE under a running session. The supervisor process keeps running
+// the code it loaded, but every worker it starts afterwards — a Restart R, a
+// respawn after a crash, the first {python} chunk — is spawned from the NEW
+// files. An old supervisor then drives a new worker over a wire neither was
+// tested against, and nothing says so. `/health` could already tell
+// (`installed_build` differs from `kernel_build`); nothing acted on it.
+//
+// So the supervisor fingerprints its payload at boot and, before it starts any
+// worker, fingerprints it again. A difference is refused with a sentence that
+// names the build now installed and the door that moves the session onto it
+// ("Restart into"). This is the DETECTION half of S1b; retaining a complete
+// payload per live build is the other half and is not built here.
+//
+// A source checkout (`spike/`) is exempt: there, editing worker.R and pressing
+// Restart R is the development loop, not a fault. BEATRINA_PAYLOAD_GUARD=1/0
+// forces the answer either way (tests, and an operator who wants it off).
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/** Names that change while a payload is running without the payload changing. */
+const VOLATILE = /^(\.|__pycache__$)|\.pyc$/;
+
+/** Every regular file under `dir` (recursively when `deep`), sorted, relative to `base`. */
+function listFiles(dir, base, deep) {
+  let names;
+  try { names = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  const out = [];
+  for (const d of names) {
+    if (VOLATILE.test(d.name)) continue;
+    const full = path.join(dir, d.name);
+    if (d.isFile()) out.push(path.relative(base, full));
+    else if (deep && d.isDirectory()) out.push(...listFiles(full, base, deep));
+  }
+  return out.sort();
+}
+
+/**
+ * A digest of the files a worker is started from.
+ *
+ * The kernel directory's own files (not its subfolders — plugins and examples
+ * are data a worker reads on request, not code it boots from) and everything
+ * under `engines/`. Content, not mtimes: a same-version rebuild that changed a
+ * byte is a different payload, and a copy that preserved every byte is not.
+ *
+ * @param {{kernelDir: string, root: string}} where
+ * @returns {{digest: string, files: number, build: string}}
+ */
+export function payloadFingerprint({ kernelDir, root }) {
+  const hash = crypto.createHash("sha256");
+  const entries = [
+    ...listFiles(kernelDir, kernelDir, false).map((rel) => ({ tag: "kernel", rel, full: path.join(kernelDir, rel) })),
+    ...listFiles(path.join(root, "engines"), path.join(root, "engines"), true)
+      .map((rel) => ({ tag: "engines", rel, full: path.join(root, "engines", rel) })),
+  ];
+  for (const e of entries) {
+    hash.update(`${e.tag}/${e.rel}\0`);
+    try { hash.update(fs.readFileSync(e.full)); } catch { hash.update("<unreadable>"); }
+    hash.update("\0");
+  }
+  let build = "";
+  try { build = fs.readFileSync(path.join(kernelDir, "kernel-version"), "utf8").trim(); } catch { build = ""; }
+  return { digest: hash.digest("hex"), files: entries.length, build };
+}
+
+/**
+ * Is the guard on for this kernel directory?
+ * @param {string} kernelDir
+ * @param {string} [override]  BEATRINA_PAYLOAD_GUARD: "1" on, "0" off, "" decide by shape
+ */
+export function payloadGuardOn(kernelDir, override = "") {
+  if (override === "1") return true;
+  if (override === "0") return false;
+  return path.basename(path.resolve(kernelDir)) !== "spike";
+}
+
+/**
+ * Why a worker may not start from the payload as it is now, or null.
+ *
+ * Pure: the two fingerprints in, a sentence out. `bootBuild` is the build the
+ * supervisor announced at boot (what it runs), which may be dictated by the
+ * environment and so need not equal the boot fingerprint's stamp.
+ *
+ * @param {{digest:string, build:string}} boot
+ * @param {{digest:string, build:string}} now
+ * @param {string} bootBuild
+ * @returns {string|null}
+ */
+export function payloadDrift(boot, now, bootBuild) {
+  if (!boot || !now || boot.digest === now.digest) return null;
+  const was = bootBuild || boot.build || "this build";
+  const installed = now.build && now.build !== boot.build
+    ? `Beatrina ${now.build} was installed over this session's files`
+    : "This session's files were replaced while it was running";
+  return `${installed}, so a worker cannot be started from them: this session runs Beatrina ${was}, `
+    + `and mixing it with newer files is how an old supervisor ends up driving a new worker. `
+    + `Use "Restart into ${now.build || "the installed build"}" (Session menu) to move the session onto the installed files; `
+    + `your documents come with it.`;
+}
+
+/** The error a refused start throws, so callers can tell it from a spawn failure. */
+export class PayloadDriftError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PayloadDriftError";
+    this.code = "BEATRINA_PAYLOAD_DRIFT";
+  }
+}
+
+/**
+ * Wrap an engine factory so it refuses to build from a drifted payload.
+ * @param {() => object} make
+ * @param {{enabled:boolean, boot:object, bootBuild:string, measure:() => object, audit?:Function, engine:string}} opts
+ */
+export function guardFactory(make, { enabled, boot, bootBuild, measure, audit = () => {}, engine }) {
+  if (!enabled) return make;
+  return () => {
+    const now = measure();
+    const why = payloadDrift(boot, now, bootBuild);
+    if (why) {
+      audit("payload-drift", { engine, boot_build: bootBuild, now_build: now.build, boot_digest: boot.digest.slice(0, 12), now_digest: now.digest.slice(0, 12) });
+      throw new PayloadDriftError(why);
+    }
+    return make();
+  };
+}

package/host/planes/README.md

@@ -1,6 +1,6 @@
 # host/planes — one supervisor-answered family per module
 
-A plane is what `spike/serve.R` calls an allow-list family: the file ops, the
+A plane is an allow-list family — the name the retired R supervisor used for it: the file ops, the
 journal, the AI store, jobs, the terminal, citations, plugins, sessions, the
 MCP plane. Each is one module here, registered by one line in `host/main.mjs`
 (`PLANE_MODULES`), and consulted by `host/server.mjs` before its not-yet

package/host/planes/ai-store.mjs

@@ -35,6 +35,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { privateModeHeld, stateDir } from "../user-dirs.mjs";
 import { PAGE_ONLY_CLASSES } from "../server.mjs";
+import { envReader } from "../env-names.mjs";
 
 export const AI_STORE_OPS = Object.freeze(["ai_list", "ai_read", "ai_write", "ai_delete", "ai_purge", "ai_keys"]);
 
@@ -57,13 +58,13 @@ const AI_MAX_BYTES = 2 * 1024 * 1024;       // one conversation
 const AI_MAX_PER_DOCUMENT = 200;            // conversations kept per document
 const AI_MAX_REPLY_BYTES = 6e6;             // under the 8 MB frame cap, with room
 
-const envOf = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const envOf = envReader(process.env);   // dual-read (host/env-names.mjs)
 const bytesOf = (text) => Buffer.byteLength(text, "utf8");
 const withCommas = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 
 export function createAiConversationStore() {
-  const enabled = envOf("CARMAR_NO_AI_STORE") !== "1";
-  const root = () => envOf("CARMAR_AI_STORE_DIR") || path.join(stateDir(), "ai");
+  const enabled = envOf("BEATRINA_NO_AI_STORE") !== "1";
+  const root = () => envOf("BEATRINA_AI_STORE_DIR") || path.join(stateDir(), "ai");
   const validKey = (key) => typeof key === "string" && AI_KEY_RE.test(key) && !AI_DOTS_RE.test(key.replace(/^[a-z]+:/, ""));
   const validId = (id) => typeof id === "string" && AI_ID_RE.test(id) && !AI_DOTS_RE.test(id);
   const dirOf = (key) => path.join(root(), key.replace(":", "__"));
@@ -117,7 +118,7 @@ export function createAiConversationStore() {
   };
   /** Atomic replace within the same directory: write a sibling, rename over. */
   const replace = (file, text) => {
-    const temp = path.join(path.dirname(file), `.carmar-ai-${crypto.randomBytes(8).toString("hex")}`);
+    const temp = path.join(path.dirname(file), `.beatrina-ai-${crypto.randomBytes(8).toString("hex")}`);
     writePrivate(temp, text);
     try { fs.renameSync(temp, file); } catch {
       try { fs.unlinkSync(temp); } catch { /* gone */ }
@@ -191,7 +192,7 @@ export function createAiConversationStore() {
   const answer = (cmd) => {
     const { type, id } = cmd;
     if (!enabled) {
-      return err(type, id, "disabled", "Conversation storage is switched off on this machine (CARMAR_NO_AI_STORE=1).");
+      return err(type, id, "disabled", "Conversation storage is switched off on this machine (BEATRINA_NO_AI_STORE=1).");
     }
     // Every op but `ai_keys` names a document, and the key is checked BEFORE
     // the file system is touched — the journal's rule, for the same reason.

package/host/planes/ai.mjs

@@ -25,9 +25,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { PAGE_ONLY_CLASSES } from "../server.mjs";
 import { appId, ensureUserDir, privateModeHeld } from "../user-dirs.mjs";
-import { carmarAiPolicy, aiPolicyReason } from "../ai-policy.mjs";
+import { beatrinaAiPolicy, aiPolicyReason } from "../ai-policy.mjs";
+import { envReader } from "../env-names.mjs";
 
-const envOf = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const envOf = envReader(process.env);   // dual-read (host/env-names.mjs)
 const isStr = (v) => typeof v === "string" && v.length > 0;
 
 // ── what the page may write into the audit stream ───────────────────────────
@@ -53,7 +54,7 @@ export const AI_AUDIT_FIELDS = Object.freeze(["provider", "model", "lane", "tool
 // The prompt and the response themselves. OFF unless an administrator asks,
 // because a notebook that silently recorded everything its user typed at an AI
 // would be a worse thing to ship than no audit at all — the same judgement
-// CARMAR_LOG itself is off by default for.
+// BEATRINA_LOG itself is off by default for.
 export const AI_AUDIT_TEXT_FIELDS = Object.freeze(["prompt", "response"]);
 /** How many ai-* records the reviewer export may read back at once. */
 export const AI_AUDIT_READ_MAX = 5000;
@@ -65,7 +66,7 @@ export const AI_AUDIT_READ_MAX = 5000;
 // same reason: this is MACHINE state, not notebook content, so it belongs in
 // the R user directory and never in the notebook file, an export, or
 // localStorage — where any local page sharing the file:// origin could read the
-// user's code. Off entirely with CARMAR_NO_HISTORY=1 (and from Settings),
+// user's code. Off entirely with BEATRINA_NO_HISTORY=1 (and from Settings),
 // because "record everything I type" must be refusable.
 export const HISTORY_MAX = 2000;
 
@@ -85,27 +86,27 @@ export const HISTORY_MAX = 2000;
 // local HTML file shares the file:// origin, so without it `prefs` is a
 // free-form key/value bag any of them could fill.
 //
-// The values travel as the STRINGS localStorage holds. carmar-chunk-custom is
+// The values travel as the STRINGS localStorage holds. beatrina-chunk-custom is
 // itself JSON; re-parsing it here would make the kernel a party to a format
 // only the page understands.
 export const PREF_MAX_VALUE = 4096;
 export const PREF_KEYS = Object.freeze([
-  "carmar-app-theme",        // lib/app-themes.js       standard/flat/plain/graphite/onyx
-  "carmar-editor-theme",     // lib/editor-themes.js    one of 37
-  "carmar-chunk-style",      // lib/chunk-style.js      the pre-7.8 key, kept in step
-  "carmar-chunk-style-v2",   // lib/chunk-style.js      the explicit choice
-  "carmar-chunk-custom",     // lib/chunk-style.js      the designer's token overrides
-  "carmar-writing-chunk",    // lib/writing-chunk.js    the Writing surface's own card
-  "carmar-run-style",        // lib/run-style.js
-  "carmar-table-style-v2",   // lib/table-render.js
-  "carmar-line-numbering",   // lib/line-numbering.js
-  "carmar-density",          // lib/density.js
-  "carmar-add-strip-v3",     // lib/add-strip.js
-  "carmar-soft-wrap",        // lib/soft-wrap.js
-  "carmar-content-width-v1", // src/notebook-entry.js   Standard / Wide / Full
-  "carmar-brand-v1",         // lib/brand.js            the organisation's accent
-  "carmar:rich-text",        // lib/rtf-editor.js
-  "carmar:latex-template",   // lib/latex-templates.js
+  "beatrina-app-theme",        // lib/app-themes.js       standard/flat/plain/graphite/onyx
+  "beatrina-editor-theme",     // lib/editor-themes.js    one of 37
+  "beatrina-chunk-style",      // lib/chunk-style.js      the pre-7.8 key, kept in step
+  "beatrina-chunk-style-v2",   // lib/chunk-style.js      the explicit choice
+  "beatrina-chunk-custom",     // lib/chunk-style.js      the designer's token overrides
+  "beatrina-writing-chunk",    // lib/writing-chunk.js    the Writing surface's own card
+  "beatrina-run-style",        // lib/run-style.js
+  "beatrina-table-style-v2",   // lib/table-render.js
+  "beatrina-line-numbering",   // lib/line-numbering.js
+  "beatrina-density",          // lib/density.js
+  "beatrina-add-strip-v3",     // lib/add-strip.js
+  "beatrina-soft-wrap",        // lib/soft-wrap.js
+  "beatrina-content-width-v1", // src/notebook-entry.js   Standard / Wide / Full
+  "beatrina-brand-v1",         // lib/brand.js            the organisation's accent
+  "beatrina:rich-text",        // lib/rtf-editor.js
+  "beatrina:latex-template",   // lib/latex-templates.js
 ]);
 
 const AGENT_WHY = Object.freeze({
@@ -223,11 +224,21 @@ export function prefsClean(values) {
   return out;
 }
 
+// The file a Beatrina 0.8.x kernel wrote names its keys the old way; they are
+// read under the current names (the page's lib/legacy-keys.js does the same for
+// its storage), and the next write puts the current names on disk.
+const LEGACY_PREF_KEY = /^carmar(?=[-:])/;   // beatrina-names: keep
+// The current prefix, as a token the rename script moves with PREF_KEYS (lib/legacy-keys.js does the same).
+const CURRENT_PREF_PREFIX = "beatrina-x".slice(0, -2);
+export const modernPrefs = (values) => (values && typeof values === "object" && !Array.isArray(values))
+  ? Object.fromEntries(Object.entries(values).map(([k, v]) => [k.replace(LEGACY_PREF_KEY, CURRENT_PREF_PREFIX), v]))
+  : values;
+
 export function prefsRead(enabled) {
   if (!enabled) return {};
   const file = prefsPath();
   if (!fs.existsSync(file)) return {};
-  try { return prefsClean(JSON.parse(fs.readFileSync(file, "utf8"))); } catch { return {}; }
+  try { return prefsClean(modernPrefs(JSON.parse(fs.readFileSync(file, "utf8")))); } catch { return {}; }
 }
 
 export function prefsWrite(enabled, values) {
@@ -252,11 +263,11 @@ export function prefsWrite(enabled, values) {
 const OPS = Object.freeze(["ai-key", "ai-policy", "ai-audit", "ai-audit-read", "console_history", "prefs"]);
 
 export function createPlane({ audit, settings } = {}) {
-  const policy = carmarAiPolicy();
-  const logPath = envOf("CARMAR_LOG");
-  const auditText = envOf("CARMAR_LOG_AI_TEXT") === "1";
-  const prefsEnabled = envOf("CARMAR_NO_PREFS") !== "1";
-  const historyEnabled = () => (settings ? settings.historyEnabled() : envOf("CARMAR_NO_HISTORY") !== "1");
+  const policy = beatrinaAiPolicy();
+  const logPath = envOf("BEATRINA_LOG");
+  const auditText = envOf("BEATRINA_LOG_AI_TEXT") === "1";
+  const prefsEnabled = envOf("BEATRINA_NO_PREFS") !== "1";
+  const historyEnabled = () => (settings ? settings.historyEnabled() : envOf("BEATRINA_NO_HISTORY") !== "1");
 
   return {
     name: "ai",
@@ -343,12 +354,21 @@ export function createPlane({ audit, settings } = {}) {
         // the attempt is in the audit log. The refusal covers `set` as much as
         // `get`, because a key held under a local-only policy is a key that
         // should never have been accepted.
-        if (policy.set === true && policy.allows_key !== true) {
+        const action = isStr(cmd.action) ? cmd.action : "get";
+        // DELETING IS NOT USING. The refusal above covers `get` and `set` —
+        // "we will not hand this out, and we will not start keeping a new one"
+        // — and it used to be checked before the action was even read, so it
+        // covered `clear` as well. That is the one outcome the policy cannot
+        // want: a key already on disk under a policy permitting no key-based
+        // provider is exactly the key that should be removable, and refusing
+        // the removal KEEPS the secret. An authorized deletion always works;
+        // the reads stay denied on either side of it.
+        const clearing = action === "clear" || (action === "set" && cmd.key === "");
+        if (!clearing && policy.set === true && policy.allows_key !== true) {
           audit?.("ai-key-refused", { reason: "policy", class: rec.class || "unknown" });
           reply({ error: aiPolicyReason(policy), policy: true });
           return undefined;
         }
-        const action = isStr(cmd.action) ? cmd.action : "get";
         if (action === "get") {
           audit?.("ai-key", { detail: "get", class: rec.class });
           reply({ key: aiKeyRead() });

package/host/planes/analyze.mjs

@@ -55,6 +55,8 @@ import path from "node:path";
 import { REngine } from "../engine-r.mjs";
 import { StdioEngine } from "../engine-stdio.mjs";
 import { relayFrame } from "../worker-plane.mjs";
+import { mirrorEnv } from "../env-names.mjs";
+import { STRIP_PY_ENV } from "../engine-python.mjs";
 
 /** The four ops the browser may send. An allow-list, deliberately tiny. */
 export const ANALYZE_FORWARDED = Object.freeze(["analyze", "analyze_ping", "analyze_workspace",
@@ -74,7 +76,7 @@ export const ANALYZE_REPLY_TYPE = Object.freeze({
  *
  * serve.R has no such bound: analysis is milliseconds and the queue is nearly
  * always empty, so a wedged child simply wedged the plane. 120 s is above the
- * widest legitimate answer — `CARMAR_ANALYZE_BUDGET` clamps a workspace scan to
+ * widest legitimate answer — `BEATRINA_ANALYZE_BUDGET` clamps a workspace scan to
  * 60 s — and far below "the editor has no diagnostics and nobody said why".
  * Expiry fails the route AND kills the child, because a parse that did not
  * return in two minutes will not return; the next request spawns a fresh one.
@@ -83,7 +85,6 @@ export const ANALYZE_DEADLINE_S = 120;
 
 const scalarChr = (x) => typeof x === "string" && x.length > 0;
 /** What a Python child must not inherit (host/engine-python.mjs's list, restated). */
-const STRIP_PY_ENV = /^(PYTHONHOME|PYTHONPATH|PYTHONSTARTUP|PYTHONEXECUTABLE)$/;
 
 /**
  * The Python analysis child: `python -I engines/python/analyze.py <sentinel>`.
@@ -113,7 +114,7 @@ export class PythonAnalysisEngine extends StdioEngine {
 
   spawnPlan() {
     return { bin: this.python, args: ["-I", path.resolve(this.workerPath), this.sentinel],
-      env: { CARMAR_WORKER_MODE: "batch" } };
+      env: mirrorEnv({ BEATRINA_WORKER_MODE: "batch" }) };
   }
 
   /** Plain JSON lines, as analyze.R's batch reader takes them: no console to tag into. */
@@ -136,7 +137,7 @@ export function analyzeEngineOf(cmd) {
 
 export function createPlane({ root, spike, env, audit }) {
   const deadlineS = (() => {
-    const raw = Number(env("CARMAR_ANALYZE_DEADLINE", String(ANALYZE_DEADLINE_S)));
+    const raw = Number(env("BEATRINA_ANALYZE_DEADLINE", String(ANALYZE_DEADLINE_S)));
     return Number.isFinite(raw) && raw >= 0 ? raw : ANALYZE_DEADLINE_S;
   })();
   const hostRoot = root || path.resolve(spike, "..");
@@ -321,7 +322,7 @@ export function createPlane({ root, spike, env, audit }) {
       name: "python", label: "Python",
       makeEngine: () => {
         // The SAME interpreter the Python engine runs on — the pool's own
-        // discovery, including CARMAR_PYTHON and CARMAR_NO_PYTHON — so "Python
+        // discovery, including BEATRINA_PYTHON and BEATRINA_NO_PYTHON — so "Python
         // is available" means one thing on this host, and its reason is the
         // one Doctor shows.
         const spec = pool && Array.isArray(pool.specs) ? pool.specs.find((x) => x.name === "python") : null;