beatrina 0.8.7 → 0.9.43

package/host/planes/pair.mjs

@@ -1,7 +1,7 @@
 // pair.mjs — the consent doors, and the one that hands a document to a page.
 //
 // A port of spike/serve.R's `/pair`, `/pair/approve`, `/published/authorize`
-// and `/open`, plus the `CARMAR_PUBLISHED_ORIGIN` seed. Nothing here opens a
+// and `/open`, plus the `BEATRINA_PUBLISHED_ORIGIN` seed. Nothing here opens a
 // socket; it decides which exact Origin STRING the upgrade gate in
 // host/server.mjs will admit this session (`ctx.approvals`), and it is the
 // only writer of that set.
@@ -29,7 +29,7 @@
 //     relays only messages from the exact approved origin. A file or local
 //     page dials the kernel directly the moment its retry fires, so all its
 //     window has left to do is say so.
-//   · /published/authorize is the NATIVE door (the carmar:// handler). It is
+//   · /published/authorize is the NATIVE door (the beatrina:// handler). It is
 //     gated by controlRejection, so a browser page cannot grant itself R
 //     execution by visiting a URL; `publishedOriginValid` stays strict
 //     (^https?://…) because it also guards the environment seed, and widening
@@ -91,29 +91,29 @@ export function pairingPage(origin, nonce, mint) {
   const isFile = origin === FILE_ORIGIN;
   const isLocal = localOrigin(origin);
   const challenge = mint(origin, String(nonce ?? "").slice(0, 200));
-  const title = isFile ? "Allow this notebook file to use CarmaR?"
-    : isLocal ? "Attach this notebook to this CarmaR session?"
-      : "Allow this book to use CarmaR?";
+  const title = isFile ? "Allow this notebook file to use Beatrina?"
+    : isLocal ? "Attach this notebook to this Beatrina session?"
+      : "Allow this book to use Beatrina?";
   const body = isFile
     ? '<h1>Run this notebook file with your R?</h1>'
       + '<p>A notebook opened from a file on this computer</p>'
       + '<p class="site"><strong>a page opened from disk (file://)</strong></p>'
-      + '<p>wants to use this CarmaR session. The code will run as your user '
+      + '<p>wants to use this Beatrina session. The code will run as your user '
       + 'and can access your files and network. A page opened from a file '
       + 'cannot be identified any more exactly than this, so approve it only '
       + 'if you just opened a notebook of your own.</p>'
     : isLocal
       ? '<h1>Attach this notebook to this R session?</h1>'
-        + '<p>A CarmaR notebook page served at</p>'
+        + '<p>A Beatrina notebook page served at</p>'
         + `<p class="site"><strong>${htmlEscape(origin)}</strong></p>`
-        + '<p>wants to use this CarmaR session instead of its own &mdash; usually '
+        + '<p>wants to use this Beatrina session instead of its own &mdash; usually '
         + 'because the session that served it has stopped. It will be treated as '
         + 'your notebook: its chunks run as your user, and it may open a terminal '
         + 'and use your saved AI settings. Approve it only if you just asked a '
         + 'notebook of your own to attach.</p>'
       : '<h1>Run this book with your R?</h1><p>The published site</p>'
         + `<p class="site"><strong>${htmlEscape(origin)}</strong></p>`
-        + '<p>wants to send R chunks to this CarmaR session on your computer. '
+        + '<p>wants to send R chunks to this Beatrina session on your computer. '
         + 'The code will run as your user and can access your files and network.</p>';
   const html = '<!doctype html><html><head><meta charset="utf-8">'
     + '<meta name="viewport" content="width=device-width,initial-scale=1">'
@@ -126,7 +126,7 @@ export function pairingPage(origin, nonce, mint) {
     + (isLocal ? "Attach for this session" : "Allow for this session")
     + '</button></form>'
     + "<p><small>Nothing runs until you press a chunk's Run button. "
-    + 'Approval disappears when this CarmaR session stops.</small></p></body></html>';
+    + 'Approval disappears when this Beatrina session stops.</small></p></body></html>';
   return { html, challenge };
 }
 
@@ -146,8 +146,8 @@ export function pairingBridgePage(rec, port) {
     + '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
     + "script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self' ws://127.0.0.1:"
     + port + "; base-uri 'none'\">"
-    + '<title>CarmaR connected</title><style>' + NARROW_CSS + '</style></head><body>'
-    + '<h1>CarmaR is connected</h1><p>This session now runs chunks pressed on</p>'
+    + '<title>Beatrina connected</title><style>' + NARROW_CSS + '</style></head><body>'
+    + '<h1>Beatrina is connected</h1><p>This session now runs chunks pressed on</p>'
     + `<p class="site"><strong>${htmlEscape(rec.origin)}</strong></p>`
     + '<p>The page connects by itself and closes this window; if it stays open, you can close it. '
     + 'The approval lasts until this R session stops.</p><script>(function(){'
@@ -156,15 +156,15 @@ export function pairingBridgePage(rec, port) {
     + 'Object.assign({type,nonce,origin:target,port:' + port + '},extra||{}),target)};'
     + 'addEventListener("message",event=>{const data=event.data||{};'
     + 'if(event.source!==window.opener||event.origin!==target||data.nonce!==nonce)return;'
-    + 'if(data.type==="carmar:bridge-attach"){const generation=++wsGeneration,old=ws;'
+    + 'if(data.type==="beatrina:bridge-attach"){const generation=++wsGeneration,old=ws;'
     + 'if(old){old.onmessage=old.onerror=old.onclose=null;try{old.close()}catch(e){}}'
     + 'ws=new WebSocket(socketUrl);const current=ws;'
-    + 'current.onmessage=message=>{if(generation===wsGeneration)tell("carmar:bridge-frame",{data:message.data})};'
-    + 'current.onerror=()=>{if(generation===wsGeneration)tell("carmar:bridge-error")};'
-    + 'current.onclose=()=>{if(generation===wsGeneration)tell("carmar:bridge-close")};return}'
-    + 'if(data.type==="carmar:bridge-send"&&ws&&ws.readyState===1)ws.send(data.data);'
-    + 'if(data.type==="carmar:bridge-close"&&ws)ws.close()});'
-    + 'tell("carmar:paired");})();</script></body></html>';
+    + 'current.onmessage=message=>{if(generation===wsGeneration)tell("beatrina:bridge-frame",{data:message.data})};'
+    + 'current.onerror=()=>{if(generation===wsGeneration)tell("beatrina:bridge-error")};'
+    + 'current.onclose=()=>{if(generation===wsGeneration)tell("beatrina:bridge-close")};return}'
+    + 'if(data.type==="beatrina:bridge-send"&&ws&&ws.readyState===1)ws.send(data.data);'
+    + 'if(data.type==="beatrina:bridge-close"&&ws)ws.close()});'
+    + 'tell("beatrina:paired");})();</script></body></html>';
 }
 
 /** The last word for a file or local page: it dials the kernel by itself. */
@@ -173,12 +173,12 @@ export function pairingDonePage(rec) {
     + '<meta name="viewport" content="width=device-width,initial-scale=1">'
     + '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
     + "style-src 'unsafe-inline'; base-uri 'none'\">"
-    + '<title>CarmaR attached</title><style>' + NARROW_CSS + '</style></head><body>'
+    + '<title>Beatrina attached</title><style>' + NARROW_CSS + '</style></head><body>'
     + '<h1>Attached</h1><p>The notebook</p>'
     + '<p class="site"><strong>'
     + (rec.origin === FILE_ORIGIN ? "a page opened from disk (file://)" : htmlEscape(rec.origin))
     + '</strong></p>'
-    + '<p>may use this CarmaR session until it stops. It reconnects by itself within '
+    + '<p>may use this Beatrina session until it stops. It reconnects by itself within '
     + 'a few seconds; you can close this window.</p></body></html>';
 }
 
@@ -218,11 +218,11 @@ export function createPlane({ env, audit }) {
     capabilities: [],
 
     init(ctx) {
-      // A native CarmaR launcher may start the kernel for one published page.
+      // A native Beatrina launcher may start the kernel for one published page.
       // The URL-scheme handoff is the user's consent gesture; carrying only
       // the exact origin into this process keeps the permission session-scoped
       // and stops a second site borrowing it.
-      const seed = env("CARMAR_PUBLISHED_ORIGIN", "");
+      const seed = env("BEATRINA_PUBLISHED_ORIGIN", "");
       if (publishedOriginValid(seed)) {
         ctx.approvals.add(seed);
         audit("published-origin-authorized", { origin: seed, source: "launcher" });
@@ -271,7 +271,7 @@ export function createPlane({ env, audit }) {
         const rec = challenge ? requests.get(challenge) : null;
         if (!rec) {
           audit("pair-rejected", { detail: "missing or expired challenge" });
-          ctx.respond(res, 400, "text/plain", "This CarmaR approval request has expired.");
+          ctx.respond(res, 400, "text/plain", "This Beatrina approval request has expired.");
           return true;
         }
         requests.delete(challenge);                 // consume-once: no replay

package/host/planes/pipe-term.mjs

@@ -1,10 +1,10 @@
 // pipe-term.mjs — a terminal without a pty, for a kernel that has no node-pty.
 //
-// node-pty is a NATIVE module. The carmar R package is source-only and
+// node-pty is a NATIVE module. The beatrina R package is source-only and
 // CRAN-shaped (tools/ship/build-r-pkg.sh), so an installed Beatrix has never
 // had it: every term_open from an installed package answered "node-pty is not
 // installed on this kernel" (measured 2026-09-15, tools/beatrina/acceptance.mjs
-// against build/carmar_0.8.4.tar.gz). The terminal pane then had nothing.
+// against build/beatrina_0.8.4.tar.gz). The terminal pane then had nothing.
 //
 // This is the honest second rung: the user's shell on plain pipes, wearing the
 // same shape node-pty's IPty has (pid · onData · onExit · write · resize ·

package/host/planes/plugins.mjs

@@ -22,8 +22,8 @@ import {
   pluginInstall, pluginKindOk, pluginKinds, pluginPolicyDisclosure, pluginPolicyOnce,
   pluginRead, pluginRemove, pluginRows,
 } from "../plugin-store.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
 
-const PAGE_ONLY_CLASSES = ["served", "file", "local"];
 const OPS = ["plugin_list", "plugin_read", "plugin_policy", "plugin_install", "plugin_remove"];
 const AGENT_REFUSED = ["plugin_install", "plugin_remove"];
 const AGENT_WHY = {

package/host/planes/recent-documents.mjs

@@ -0,0 +1,170 @@
+// planes/recent-documents.mjs — the list of documents this person opened,
+// kept on the machine.
+//
+// WHY THE HOST. The page kept the list in localStorage, which a browser
+// partitions BY ORIGIN, and a Beatrina origin is a port (4747, or the next
+// free one for a second session): a second window, a restart on another port
+// and tomorrow's session each started with an empty list. A file under the
+// user's own R data directory is what every window of every session reads —
+// the same folder the console history, the journal and the AI store live in
+// (host/user-dirs.mjs). Answered by the host itself, like the file ops, so a
+// note lands while a forty-second fit runs.
+//
+// ONE op, `recent-documents`, with an `action`:
+//   list             the list
+//   merge {documents} the page's cache, once per connection — union, the
+//                    newer row of each path (host/recent-documents.mjs)
+//   note {document}  opened or saved: to the top, stamped with this clock
+//   forget {path}    one row goes
+//   clear            every row goes
+// Every reply carries the WHOLE list, so the page adopts it and needs no
+// second round trip. The file is read on every op — never cached — because two
+// kernels on two ports share it and each must see the other's rows.
+//
+// The file is `recent-documents.json` under R_user_dir("beatrina", "data")
+// (BEATRINA_RECENT_DOCUMENTS_DIR relocates it; the test runner sets that, since
+// every e2e page connects and would seed the owner's real list with scratch
+// paths — LEARNINGS 2026-09-10, the appearance carry). 0600, replaced
+// atomically (writePrivateAtomic). An UNREADABLE file is never discarded: it is
+// set aside as `recent-documents.corrupt-<ms>` beside, the reply says
+// `recovered: true` with the name, and the list starts again.
+//
+// Page-only in BOTH senses (PAGE_ONLY_CLASSES, and refused to a declared
+// agent): where a person has been working is theirs, and an agent that wants
+// a document open can ask the page to open it. BEATRINA_NO_RECENT_DOCUMENTS=1
+// keeps no list at all — the op is then not advertised, and answers `disabled`.
+
+import fs from "node:fs";
+import path from "node:path";
+import { appId, ensureUserDir, writePrivateAtomic } from "../user-dirs.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
+import { envReader } from "../env-names.mjs";
+import {
+  cleanRecentDocument, cleanRecentDocuments, countUnopenable,
+  noteRecentDocument, forgetRecentDocument, mergeRecentDocuments,
+} from "../recent-documents.mjs";
+
+export const RECENT_DOCUMENTS_OP = "recent-documents";
+export const RECENT_DOCUMENTS_FILE = "recent-documents.json";
+export const RECENT_DOCUMENTS_ACTIONS = Object.freeze(["list", "merge", "note", "forget", "clear"]);
+const OPS = Object.freeze([RECENT_DOCUMENTS_OP]);
+const FILE_VERSION = 1;
+
+const envOf = envReader(process.env);   // dual-read (host/env-names.mjs)
+
+/** Where the list lives: the dictated folder, else the user's R data dir. */
+export function recentDocumentsFile(env = envOf) {
+  const dictated = env("BEATRINA_RECENT_DOCUMENTS_DIR").trim();
+  return path.join(dictated || ensureUserDir(appId(), "data"), RECENT_DOCUMENTS_FILE);
+}
+
+/**
+ * Read the list. A file that cannot be read as a list — not JSON, not the
+ * shape written here, an embedded NUL — is renamed aside and reported, so a
+ * person can see what happened and nothing is lost in silence.
+ *
+ * @param {string} file
+ * @param {number} [now]
+ * @returns {{documents:Array, recovered:boolean, aside?:string, reason?:string}}
+ */
+export function readRecentDocuments(file, now = Date.now()) {
+  if (!fs.existsSync(file)) return { documents: [], recovered: false };
+  let parsed;
+  try {
+    const raw = fs.readFileSync(file);
+    if (raw.includes(0)) throw new Error("an embedded NUL byte");
+    parsed = JSON.parse(raw.toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.documents)) {
+      throw new Error("not a list of documents");
+    }
+  } catch (e) {
+    const aside = `${file.replace(/\.json$/, "")}.corrupt-${Math.floor(now)}`;
+    fs.renameSync(file, aside);           // a failure here is the op's error: nothing is overwritten
+    return { documents: [], recovered: true, aside, reason: e.message };
+  }
+  return { documents: cleanRecentDocuments(parsed.documents, now), recovered: false };
+}
+
+/** Write the list, whole, privately and atomically. */
+export function writeRecentDocuments(file, documents) {
+  writePrivateAtomic(file, `${JSON.stringify({ version: FILE_VERSION, documents }, null, 2)}\n`);
+}
+
+/**
+ * One action against the file: read, apply, write when anything changed.
+ * Pure over the file system: no state survives between calls, which is what
+ * lets two kernels share one list.
+ *
+ * @param {string} action
+ * @param {Object} cmd   the request frame
+ * @param {{file:string, now?:number}} opts
+ * @returns {{documents:Array, recovered?:boolean, aside?:string, dropped?:number}|{error:string, code:string}}
+ */
+export function answerRecentDocuments(action, cmd, { file, now = Date.now() }) {
+  if (!RECENT_DOCUMENTS_ACTIONS.includes(action)) {
+    return { error: `recent-documents has no action "${String(action)}" — list, merge, note, forget or clear.`, code: "bad_action" };
+  }
+  const read = readRecentDocuments(file, now);
+  const before = JSON.stringify(read.documents);
+  let documents = read.documents;
+  let dropped = 0;
+  if (action === "merge") {
+    if (!Array.isArray(cmd.documents)) return { error: "`merge` takes `documents`, a list of {name, path, when}.", code: "bad_request" };
+    dropped = countUnopenable(cmd.documents, now);
+    documents = mergeRecentDocuments(documents, cmd.documents, now);
+  } else if (action === "note") {
+    if (!cleanRecentDocument(cmd.document, now)) {
+      return { error: "`note` takes `document`, a {name, path} whose path is absolute.", code: "bad_request" };
+    }
+    documents = noteRecentDocument(documents, cmd.document, now);
+  } else if (action === "forget") {
+    if (typeof cmd.path !== "string" || !cmd.path) return { error: "`forget` takes `path`.", code: "bad_request" };
+    documents = forgetRecentDocument(documents, cmd.path, now);
+  } else if (action === "clear") {
+    documents = [];
+  }
+  if (JSON.stringify(documents) !== before) writeRecentDocuments(file, documents);
+  return {
+    documents,
+    ...(read.recovered ? { recovered: true, aside: read.aside } : {}),
+    ...(dropped ? { dropped } : {}),
+  };
+}
+
+export function createPlane({ audit }) {
+  const enabled = envOf("BEATRINA_NO_RECENT_DOCUMENTS") !== "1";
+  return {
+    name: "recent-documents",
+    ops: OPS,
+    agentRefused: OPS,
+    agentReason: () => "Agents cannot read or rewrite the list of documents this person opened; ask the page to open one.",
+    // Advertised only when kept: the page decides by name (lib/recent-documents-
+    // transport.js) and "not advertised" is the flag's face on the page.
+    commands: enabled ? OPS : [],
+    capabilities: enabled ? ["recent-documents-v1"] : [],
+    handle(cmd, rec, ctx) {
+      if (rec.role !== "page" || !ctx.scalarChr(cmd.id)) return undefined;
+      const reply = (fields) => rec.ws.send(ctx.enc({ type: RECENT_DOCUMENTS_OP, id: cmd.id, ...fields }));
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("recent-documents-refused", { reason: "class", class: rec.class || "unknown" });
+        return reply({ error: "Only the local notebook page may read the list of recent documents.", code: "class" });
+      }
+      if (!enabled) {
+        return reply({ error: "This machine keeps no list of recent documents (BEATRINA_NO_RECENT_DOCUMENTS=1).", code: "disabled" });
+      }
+      const action = typeof cmd.action === "string" ? cmd.action : "";
+      let out;
+      try {
+        out = answerRecentDocuments(action, cmd, { file: recentDocumentsFile() });
+      } catch (e) {
+        audit("recent-documents", { action, ok: false, detail: e.message });
+        return reply({ error: `The list of recent documents could not be written: ${e.message}`, code: "write_failed" });
+      }
+      if (out.error) return reply(out);
+      audit("recent-documents", { action, count: out.documents.length, ...(out.recovered ? { recovered: true } : {}), ...(out.dropped ? { dropped: out.dropped } : {}) });
+      return reply(out);
+    },
+  };
+}
+
+export default { createPlane };