beatrina 0.8.7 → 0.9.83

package/host/planes/jobs.mjs

@@ -34,6 +34,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { REngine } from "../engine-r.mjs";
 import { killProcessTree } from "./proc-tree.mjs";
+import { readEnv } from "../env-names.mjs";
 
 // ── the vocabulary ──────────────────────────────────────────────────────────
 //
@@ -51,11 +52,17 @@ export const JOB_TASKS = Object.freeze({
   install: { label: "Install", running: "Installing", target: "package", pkg: "devtools" },
   render: { label: "Render", running: "Rendering", target: "document", pkg: null },
   latex: { label: "Compile", running: "Compiling", target: "document", pkg: null },
+  // Typst is a second typesetter, not a second design: same shape as `latex`
+  // — one document in, one PDF out — and the same page-only PDF door below.
+  // The compiler is Quarto's bundled typst (or one on PATH); nothing to install.
+  typst: { label: "Compile", running: "Compiling", target: "document", pkg: null },
 });
 export const RENDER_EXTENSIONS = Object.freeze(["qmd", "rmd", "md"]);
 // "" FIRST because it is the default and the default matters: no `--to` at
 // all, so a document whose header says `format: revealjs` renders as revealjs.
-export const RENDER_FORMATS = Object.freeze(["", "html", "pdf", "docx"]);
+// `latex` and `typst` (2026-09-19, docs/latexplan.md WP5): the LaTeX export's
+// fresh-run engine. Typst goes through Quarto whatever the document is.
+export const RENDER_FORMATS = Object.freeze(["", "html", "pdf", "docx", "latex", "typst"]);
 export const LATEX_ENGINES = Object.freeze(["tectonic", "latexmk", "pdflatex", "xelatex", "lualatex"]);
 export const LATEX_TIMEOUT = 180;
 const JOB_FILTER_MAX = 200;
@@ -170,10 +177,10 @@ export function latexOptions(opts = {}) {
   }
   const fetch = opts.fetch === true;
   return {
-    CARMAR_LATEX_ENGINE: engine,
-    CARMAR_LATEX_TIMEOUT: String(timeout),
-    CARMAR_LATEX_FETCH: fetch ? "1" : "",
-    CARMAR_LATEX_IDENTITY: identity == null ? "" : JSON.stringify(identity),
+    BEATRINA_LATEX_ENGINE: engine,
+    BEATRINA_LATEX_TIMEOUT: String(timeout),
+    BEATRINA_LATEX_FETCH: fetch ? "1" : "",
+    BEATRINA_LATEX_IDENTITY: identity == null ? "" : JSON.stringify(identity),
   };
 }
 
@@ -181,7 +188,7 @@ export function latexOptions(opts = {}) {
  * Decide whether one task may run, and exactly what would run.
  *
  * The whole decision in one pure function, returned whole — the same shape as
- * `carmarDeployment()`, for the same reason: three callers (the host, the
+ * `beatrinaDeployment()`, for the same reason: three callers (the host, the
  * tests, the UI's error message) must not each re-derive it and drift.
  *
  * @returns {{ok: boolean, error?: string, task?: string, target?: string,
@@ -223,9 +230,9 @@ export function jobSpec(task, target, opts = {}) {
     if (!isFile) return bad(`'${target}' is not a file`);
     resolved = realish(target);
     const ext = pathExtension(resolved);
-    const extensions = task === "latex" ? ["tex"] : RENDER_EXTENSIONS;
+    const extensions = task === "latex" ? ["tex"] : task === "typst" ? ["typ"] : RENDER_EXTENSIONS;
     if (!extensions.includes(ext)) {
-      return bad(`CarmaR renders ${extensions.map((e) => `.${e}`).join(", ")} files; `
+      return bad(`Beatrina renders ${extensions.map((e) => `.${e}`).join(", ")} files; `
         + `'${path.basename(resolved)}' is a .${ext || "(no extension)"}`);
     }
     // The document's own folder, so a job still has one place it belongs.
@@ -241,6 +248,18 @@ export function jobSpec(task, target, opts = {}) {
   if (filter.length > JOB_FILTER_MAX) return bad("the test filter is too long");
 
   if (format && task !== "render") return bad("a format only applies to the render task");
+  if (task === "typst" && opts.engine) return bad("the typst task takes no engine — Typst is its own compiler");
+  // `pages` asks Typst for one SVG per page instead of a PDF: what the live
+  // preview draws, so it can keep the reader's place across a rebuild
+  // (lib/doc-preview.js). Strict like `fetch` — exactly `true`, never
+  // arrived at by coercion — and it means nothing to any other task.
+  const pages = opts.pages === true;
+  if (pages && task !== "typst") return bad("pages only apply to the typst task");
+  // …and only INSIDE the preview's own hidden folder. A pages compile deletes
+  // the last compile's `<stem>-N.svg` before it starts (a document that loses a
+  // page must not leave the old one to be drawn), and that deletion must never
+  // be aimed at a folder of somebody's own files.
+  if (pages && path.basename(path.dirname(resolved)) !== ".beatrina-preview") return bad("pages are compiled only in a document's .beatrina-preview folder");
   if (!RENDER_FORMATS.includes(format)) {
     return bad(`'${format}' is not a format this kernel renders (${RENDER_FORMATS.filter(Boolean).join(", ")})`);
   }
@@ -251,23 +270,26 @@ export function jobSpec(task, target, opts = {}) {
     label: spec.label, running: spec.running, targets: spec.target,
     package: spec.target === "package" ? packageName(root) : "",
     needs: spec.pkg,
+    // Canonical names; the R child (spike/job-run.R reads BEATRINA_JOB_*) gets
+    // both spellings from engineEnvironment's mirrorEnv.
     env: {
-      CARMAR_JOB_TASK: task, CARMAR_JOB_TARGET: resolved,
-      CARMAR_JOB_ROOT: root, CARMAR_JOB_FILTER: filter,
-      CARMAR_JOB_FORMAT: format, ...latexEnv,
+      BEATRINA_JOB_TASK: task, BEATRINA_JOB_TARGET: resolved,
+      BEATRINA_JOB_ROOT: root, BEATRINA_JOB_FILTER: filter,
+      BEATRINA_JOB_FORMAT: format, BEATRINA_TYPST_PAGES: pages ? "svg" : "",
+      ...latexEnv,
     },
   };
 }
 
 /** A sentence naming what is about to happen, before it happens. */
 export function jobTitle(spec) {
-  if (spec.task === "latex") return `Compiling ${path.basename(spec.target)}`;
+  if (spec.task === "latex" || spec.task === "typst") return `Compiling ${path.basename(spec.target)}`;
   if (spec.targets === "document") {
-    const format = spec.env.CARMAR_JOB_FORMAT;
+    const format = spec.env.BEATRINA_JOB_FORMAT;
     return `Rendering ${path.basename(spec.target)}${format ? ` to ${format}` : ""}`;
   }
   const name = spec.package || path.basename(spec.root);
-  const filter = spec.env.CARMAR_JOB_FILTER;
+  const filter = spec.env.BEATRINA_JOB_FILTER;
   if (spec.task === "test" && filter) return `${spec.running} ${name} — tests matching '${filter}'`;
   return `${spec.running} ${name}`;
 }
@@ -301,7 +323,7 @@ export function createPlane({ spike, env, audit }) {
   // Sixty seconds is long enough for a fetch that starts the moment the page
   // is handed the token, short enough that a token in a stray log is dead by
   // the time anyone reads it. Tests shorten it.
-  const ttlGiven = Number(env("CARMAR_OUTPUT_CAP_TTL", ""));
+  const ttlGiven = Number(env("BEATRINA_OUTPUT_CAP_TTL", ""));
   const OUTPUT_CAP_TTL = Number.isFinite(ttlGiven) && ttlGiven >= 1 && ttlGiven <= 3600 ? ttlGiven : 60;
 
   /** @type {Map<string, object>} */
@@ -408,6 +430,7 @@ export function createPlane({ spike, env, audit }) {
     const spec = jobSpec(cmd.task ?? "", cmd.target ?? "", {
       filter: cmd.filter ?? "", format: cmd.format ?? "",
       engine: cmd.engine, timeout: cmd.timeout, fetch, identity: cmd.identity,
+      pages: cmd.pages === true,
     });
     if (!spec.ok) {
       audit("job-refused", { detail: spec.error });
@@ -419,7 +442,7 @@ export function createPlane({ spike, env, audit }) {
     const id = `job-${seq}`;
     let engine;
     try {
-      engine = new REngine({ workerPath: jobRun, env: { ...spec.env, CARMAR_JOB_ID: id } });
+      engine = new REngine({ workerPath: jobRun, env: { ...spec.env, BEATRINA_JOB_ID: id } });
       // The child is a BATCH R: `Rscript job-run.R <sentinel>`. It never reads
       // stdin, has no session identity, and stamps its own frame ids.
       engine.mode = "batch";
@@ -430,7 +453,7 @@ export function createPlane({ spike, env, audit }) {
     }
     const job = {
       id, engine, task: spec.task, root: spec.root, target: spec.target,
-      identity: spec.env.CARMAR_LATEX_IDENTITY ? JSON.parse(spec.env.CARMAR_LATEX_IDENTITY) : null,
+      identity: spec.env.BEATRINA_LATEX_IDENTITY ? JSON.parse(spec.env.BEATRINA_LATEX_IDENTITY) : null,
       output: null, title: jobTitle(spec), state: "running", ok: null, error: "",
       started: Date.now() / 1000, elapsed: null, log: [], dropped: 0,
       rows: [], diagnostics: [], renderer: "", counts: null, truncated: 0, pid: null,
@@ -590,7 +613,7 @@ export function createPlane({ spike, env, audit }) {
           }
           if (!scalarChr(cmd.job)) { reply({ error: "which job?" }); return; }
           const job = jobs.get(cmd.job);
-          if (!job || job.task !== "latex" || job.state !== "done" || job.ok !== true
+          if (!job || (job.task !== "latex" && job.task !== "typst") || job.state !== "done" || job.ok !== true
             || !scalarChr(job.output) || !fs.existsSync(job.output)) {
             reply({ job: cmd.job, error: "That job has no PDF to show." });
             return;
@@ -688,12 +711,12 @@ export function createPlane({ spike, env, audit }) {
 /** `utils::browseURL` for the platform — an argument VECTOR, never a shell string. */
 function openOnDesktop(p) {
   try {
-    // CARMAR_OPENER: an executable handed the path as its ONE argument. R's
+    // BEATRINA_OPENER: an executable handed the path as its ONE argument. R's
     // browseURL reads `options(browser)` for the same purpose, and a test rig
     // that swaps that option is invisible to a supervisor that is not R — so
     // without this the host opened every synthetic PDF a suite produced on the
     // user's real desktop. Absolute paths only; never a shell string.
-    const opener = String(process.env.CARMAR_OPENER || "");
+    const opener = readEnv(process.env, "OPENER");
     const child = path.isAbsolute(opener) ? spawn(opener, [p], { stdio: "ignore", detached: true })
       : process.platform === "darwin" ? spawn("open", [p], { stdio: "ignore", detached: true })
       : process.platform === "win32" ? spawn("cmd", ["/c", "start", "", p], { stdio: "ignore", detached: true })

package/host/planes/latex.mjs

@@ -19,6 +19,7 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { findPandoc, run } from "./cite.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
 
 export const LATEX_PREVIEW_TIMEOUT_MS = 8000;
 export const LATEX_PREVIEW_MAX_SOURCE = 2e6;
@@ -34,7 +35,6 @@ export const LATEX_PREVIEW_IMAGE_TYPES = Object.freeze({
 
 const OPS = ["latex_preview"];
 const AGENT_WHY = { latex_preview: "Agents cannot render a LaTeX preview; read the .tex instead." };
-const PAGE_ONLY_CLASSES = ["served", "file", "local"];
 const scalar = (x) => typeof x === "string";
 const bytes = (s) => Buffer.byteLength(s, "utf8");
 
@@ -154,21 +154,21 @@ export async function latexPreview(source, docPath, buffers, { pandoc, timeoutMs
   if (!scalar(source) || source.length === 0) return { ok: false, error: "No LaTeX source to preview." };
   if (bytes(source) > LATEX_PREVIEW_MAX_SOURCE) return { ok: false, error: "This document is too large to preview while you type." };
   const bin = pandoc;
-  if (!bin) return { ok: false, error: "pandoc is not installed, or CarmaR could not find it. Compile still works; only the live preview needs pandoc." };
+  if (!bin) return { ok: false, error: "pandoc is not installed, or Beatrina could not find it. Compile still works; only the live preview needs pandoc." };
   let dir = "";
   if (scalar(docPath) && docPath) { try { if (fs.existsSync(docPath)) dir = path.dirname(fs.realpathSync(docPath)); } catch { dir = ""; } }
   const keep = {};
   if (buffers && typeof buffers === "object" && !Array.isArray(buffers)) {
     Object.keys(buffers).filter(Boolean).slice(0, LATEX_PREVIEW_MAX_FILES).forEach((k) => { if (typeof buffers[k] === "string") keep[k] = buffers[k]; });
   }
-  const expanded = latexPreviewCode(dir ? latexPreviewExpand(source, dir, keep) : source);
+  const expanded = latexStructureOnly(latexPreviewCode(dir ? latexPreviewExpand(source, dir, keep) : source));
   const started = process.hrtime.bigint();
   const args = ["--from=latex", "--to=html5", "--mathml", "--wrap=none", "--standalone", "--sandbox"];
   if (dir) latexPreviewBibliography(expanded, dir).forEach((bib) => args.push("--citeproc", `--bibliography=${bib}`));
   // A 0600 temp file, as cite does; HOME and the data dir moved aside so a
   // render never reads or writes this user's pandoc configuration.
-  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "carmar-preview-"));
-  const input = path.join(scratch, `carmar-preview-${crypto.randomBytes(4).toString("hex")}.tex`);
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-preview-"));
+  const input = path.join(scratch, `beatrina-preview-${crypto.randomBytes(4).toString("hex")}.tex`);
   try {
     fs.writeFileSync(input, expanded + "\n", { mode: 0o600 });
     const ran = await run(bin, [...args, input], { timeoutMs, env: { ...process.env, PANDOC_DATA_DIR: scratch, HOME: scratch } });
@@ -193,6 +193,16 @@ export async function latexPreview(source, docPath, buffers, { pandoc, timeoutMs
   }
 }
 
+/**
+ * pandoc EXPANDS the macros a preamble defines — and Beatrina's own template
+ * redefines \section through \@startsection, so every heading of a converted
+ * document was read as that macro's body and vanished. The redefinitions are
+ * typography; to a reader of STRUCTURE they are noise, and they go.
+ */
+export function latexStructureOnly(source) {
+  return String(source).replace(/^[ \t]*\\renewcommand\*?\{?\\(?:sub){0,2}section\}?\{\\@startsection.*$/gm, "");
+}
+
 export function createPlane({ env, audit }) {
   let pandocBin = null;
   const pandoc = () => { if (pandocBin === null) pandocBin = findPandoc(env); return pandocBin; };

package/host/planes/mcp.mjs

@@ -3,7 +3,7 @@
 //
 // ── the plane ──────────────────────────────────────────────────────────────
 //
-// A local agent (Claude Code / Codex through tools/mcp/carmar-mcp.mjs) connects
+// A local agent (Claude Code / Codex through tools/mcp/beatrina-mcp.mjs) connects
 // through the SAME loopback/Origin/Host gates a page does, then DECLARES itself
 // with `mcp-hello`. From then on it may only ASK — `mcp-request`, routed to the
 // active notebook window — and use the read-side forwarded ops; pages may only
@@ -17,7 +17,7 @@
 //     to; the PAGE is the only thing that can produce one, so its disappearance
 //     is the precise end of that request — reported immediately, as a fact —
 //     while the clock is only the backstop for a page that is alive and silent.
-//     `MCP_PENDING_MAX_S` matches the ceiling carmar-mcp.mjs lets a caller ask
+//     `MCP_PENDING_MAX_S` matches the ceiling beatrina-mcp.mjs lets a caller ask
 //     for (chunk_run's timeout_s caps at 3600), so the supervisor never gives up
 //     on a call the agent is still legitimately waiting for.
 //   · The roster is REPLAYED to a page that connects late. Same lesson as the
@@ -34,7 +34,7 @@
 // running cell. The CLI owns its own login — the host passes a prompt on STDIN
 // (argv is visible to every local user in `ps`), streams the CLI's stream-json
 // lines back to the ASKING page verbatim, and that is the whole exchange.
-// CarmaR reads, stores and proxies no credential. Pages only: a declared agent
+// Beatrina reads, stores and proxies no credential. Pages only: a declared agent
 // asking the kernel to spawn another agent is a loop nobody ordered.
 //
 // Two deliberate differences from serve.R, both mechanism rather than policy.
@@ -50,18 +50,16 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
+import { mirrorEnv } from "../env-names.mjs";
+import { runtimeWriteDir } from "../runtime-dir.mjs";
+import { beatrinaAiPolicy, aiProviderAllowed, aiPolicyReason } from "../ai-policy.mjs";
+import { whichSync } from "../which.mjs";
+import { normalizeAuthority, allowedToolsArg, toolsFor } from "../ai-authority.mjs";
 
 const OPS = ["mcp-hello", "mcp-active", "mcp-request", "mcp-response", "agent-chat", "agent-chat-stop"];
-/** The ceiling carmar-mcp.mjs allows a caller to ask for. */
+/** The ceiling beatrina-mcp.mjs allows a caller to ask for. */
 const MCP_PENDING_MAX_S = 3600;
 const MAX_CHATS = 3;
-/** The spawned session gets the DOCUMENT tools: it is an author, not a chatbot. */
-const AGENT_CHAT_TOOLS = [
-  "mcp__carmar__carmar_status", "mcp__carmar__notebook_read",
-  "mcp__carmar__chunk_read", "mcp__carmar__chunk_insert",
-  "mcp__carmar__chunk_update", "mcp__carmar__chunk_run",
-  "mcp__carmar__file_list", "mcp__carmar__file_read",
-].join(",");
 
 /* ── the AI policy, only as far as this plane needs it ────────────────────── */
 //
@@ -72,70 +70,36 @@ const AGENT_CHAT_TOOLS = [
 // page-side spawn to work around. That question needs only the provider list,
 // which is what is ported here — the three-state rule included.
 
-const ON_MACHINE_PROVIDERS = ["chrome", "webgpu", "ollama", "lmstudio", "jan"];
-const KEY_PROVIDERS = ["openai", "anthropic", "google", "groq", "together", "openrouter", "azure", "custom"];
-const CLI_PROVIDERS = ["claudecode", "codex"];
-const ALL_PROVIDERS = [...ON_MACHINE_PROVIDERS, ...KEY_PROVIDERS, ...CLI_PROVIDERS];
-
-/** @returns {{set:boolean, providers:string[], note:string}} */
-export function aiProviderPolicy(env) {
-  const file = env("CARMAR_AI_POLICY", "").trim();
-  let named = [];
-  let localOnly = env("CARMAR_AI_LOCAL_ONLY", "") === "1";
-  let note = "";
-  let source = "";
-  const errors = [];
-  if (file) {
-    source = file;
-    if (!fs.existsSync(file)) errors.push("missing");
-    else {
-      try {
-        const doc = JSON.parse(fs.readFileSync(file, "utf8"));
-        named = [].concat(doc.providers ?? []).map(String);
-        if (doc.local_only === true) localOnly = true;
-        note = String(doc.note ?? "").trim();
-      } catch { errors.push("unreadable"); }
-    }
-  } else if (env("CARMAR_AI_PROVIDERS", "")) {
-    source = "env";
-    named = String(env("CARMAR_AI_PROVIDERS", "")).split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
-  } else if (localOnly) {
-    source = "env";
-  }
-  const asked = named.length > 0;
-  named = named.filter((p) => ALL_PROVIDERS.includes(p));
-  let providers = named.length ? named : asked ? [] : ALL_PROVIDERS.slice();
-  if (localOnly) providers = providers.filter((p) => ON_MACHINE_PROVIDERS.includes(p));
-  let set = Boolean(source) && !errors.length;
-  if (set && !providers.length) errors.push("empty");
-  if (errors.length) { set = false; providers = ALL_PROVIDERS.slice(); }
-  // eslint-disable-next-line no-control-regex
-  note = note.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400).trim();
-  return { set, providers, note };
-}
-
-/** May this provider be used at all? */
-export const aiProviderAllowed = (provider, policy) =>
-  policy.set !== true || (Boolean(provider) && policy.providers.includes(provider));
-
-/** The sentence the notebook shows when something is refused. */
-export const aiPolicyReason = (policy) => {
-  const base = `This CarmaR is configured to allow only: ${policy.providers.join(", ")}.`;
-  return policy.note ? `${base} ${policy.note}` : base;
-};
+// The AI provider policy is ASKED of host/ai-policy.mjs, not decided again.
+// This plane carried a second implementation — the same three provider lists,
+// the same three-state read, the same two predicates — and only the canonical
+// one is pinned: test/ai-policy.test.mjs holds its ON_MACHINE_PROVIDERS against
+// lib/llm.js's staysOnMachine() across the language boundary, and nothing
+// looked at the copy. Adding a CLI provider would have left that test green
+// while this plane refused the provider the policy permits.
+//
+// beatrinaAiPolicy returns a superset of the three fields used here
+// (set, providers, note), so the callers below are unchanged.
+const aiProviderPolicy = beatrinaAiPolicy;
 
 /* ── finding things on this machine ───────────────────────────────────────── */
 
 /**
- * Find a binary the way a launcher must: an app-bundle supervisor inherits a
- * minimal PATH, so the PATH scan alone misses user-local installs.
+ * Find a launcher on PATH, then in the usual places a GUI process cannot see.
+ *
+ * The PATH WALK is host/which.mjs's — it was lifted out of another plane the day
+ * a second one needed it, "so the two cannot drift on what 'on PATH' means", and
+ * this was the third copy. It mattered: this copy tried only `${name}.exe` on
+ * Windows, while whichSync walks PATHEXT, and `claude` and `codex` arrive as
+ * npm shims that PATHEXT resolves and `.exe` does not.
+ *
+ * The extra locations stay here, because they are this plane's own answer to a
+ * different problem: an app-bundle supervisor inherits a PATH that has none of
+ * them.
  */
 export function findBinary(name, extra = []) {
-  const exe = process.platform === "win32" ? `${name}.exe` : name;
-  for (const dir of String(process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
-    const cand = path.join(dir, exe);
-    try { fs.accessSync(cand, fs.constants.X_OK); if (fs.statSync(cand).isFile()) return cand; } catch { /* next */ }
-  }
+  const onPath = whichSync(name);
+  if (onPath) return onPath;
   for (const p of [...extra, path.join(os.homedir(), ".local", "bin", name),
     path.join("/opt/homebrew/bin", name), path.join("/usr/local/bin", name)]) {
     if (fs.existsSync(p)) return p;
@@ -144,13 +108,13 @@ export function findBinary(name, extra = []) {
 }
 
 /**
- * Where the carmar-mcp stdio server lives on THIS machine, so the setup dialog
+ * Where the beatrina-mcp stdio server lives on THIS machine, so the setup dialog
  * can show a command that works verbatim. Repo layout first (tools/mcp beside
  * spike/), then a distribution copy beside the kernel.
  */
 export function mcpServerPath(here) {
-  for (const p of [path.join(here, "..", "tools", "mcp", "carmar-mcp.mjs"),
-    path.join(here, "mcp", "carmar-mcp.mjs")]) {
+  for (const p of [path.join(here, "..", "tools", "mcp", "beatrina-mcp.mjs"),
+    path.join(here, "mcp", "beatrina-mcp.mjs")]) {
     if (fs.existsSync(p)) return fs.realpathSync(p);
   }
   return "";
@@ -170,12 +134,12 @@ export function createPlane({ spike, env, audit }) {
   let ctxRef = null;
 
   const claudeBin = () => {
-    const override = env("CARMAR_CLAUDE_BIN", "");
+    const override = env("BEATRINA_CLAUDE_BIN", "");
     if (override && fs.existsSync(override)) return override;
     return findBinary("claude");
   };
   const codexBin = () => {
-    const override = env("CARMAR_CODEX_BIN", "");
+    const override = env("BEATRINA_CODEX_BIN", "");
     if (override && fs.existsSync(override)) return override;
     return findBinary("codex");
   };
@@ -220,9 +184,19 @@ export function createPlane({ spike, env, audit }) {
 
   function chatStart(rec, cmd, ctx) {
     const id = cmd.id;
-    // Reviewed source proposals must never get the notebook's MUTATING MCP
-    // tools. Enforced at the process boundary, not merely in a prompt.
+    // WHAT THIS TURN MAY DO, decided here and nowhere else (host/ai-authority.mjs).
+    //
+    // `text` is the reviewed-source lane: a proposal about a document must not
+    // be able to edit the document. `read` is Ask and Plan — the reading tools,
+    // for every provider. `author` is the explicit Code grant, which is what
+    // keeps CLI document authoring working while giving it a moment at which
+    // somebody asked for it.
+    //
+    // Enforced at the PROCESS boundary, not merely in a prompt, and failing
+    // closed: `text_only` still means text-only whatever else was asked for,
+    // and an absent or unrecognised level is `read`.
     const textOnly = cmd.text_only === true;
+    const authority = textOnly ? "text" : normalizeAuthority(cmd.authority);
     const client = chatClient(cmd);
     const label = chatLabel(client);
     // THE DOOR WITH NO PAGE-SIDE BYPASS AT ALL: if the policy does not name the
@@ -251,36 +225,44 @@ export function createPlane({ spike, env, audit }) {
     const scalar = (v) => typeof v === "string" && v !== "";
     let args;
     if (client === "codex") {
-      cfg = fs.mkdtempSync(path.join(os.tmpdir(), "carmar-codex-"));
+      cfg = fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-codex-"));
       fs.chmodSync(cfg, 0o700);
       // The values are TOML — a JSON string literal IS a TOML basic string —
       // and carry no secret: the MCP URL is the kernel origin, nothing more.
       const toml = (x) => JSON.stringify(x);
       args = ["exec", "--json", "--ephemeral", "--skip-git-repo-check", "--ignore-user-config", "-C", cfg];
-      args.push(...(textOnly
+      args.push(...(authority === "text"
         ? ["--sandbox", "read-only", "--disable", "shell_tool", "-c", 'web_search="disabled"']
         : ["--approve-for-me"]));
       if (scalar(cmd.system)) args.push("-c", `developer_instructions=${toml(cmd.system)}`);
       if (scalar(cmd.model) && cmd.model !== "default") args.push("-m", cmd.model);
-      if (!textOnly && server && node) {
-        args.push("-c", `mcp_servers.carmar.command=${toml(node)}`,
-          "-c", `mcp_servers.carmar.args=[${toml(server)}]`,
-          "-c", `mcp_servers.carmar.env={CARMAR_MCP_URL=${toml(`${originOk}/`)}}`);
+      if (authority !== "text" && server && node) {
+        args.push("-c", `mcp_servers.beatrina.command=${toml(node)}`,
+          "-c", `mcp_servers.beatrina.args=[${toml(server)}]`,
+          // Both spellings, the product's name first: the server reads BEATRINA_MCP_URL first
+          // (tools/mcp/beatrina-mcp.mjs); the old one stays for a 0.8.x server on the same machine.
+          // The TOOL LIST travels to the server, not the level: the host owns
+          // the decision and the server carries it out, so there is no second
+          // copy of the contract to drift. Codex has no per-tool allow-list
+          // flag the way `claude --allowedTools` does, so this is the only
+          // gate it has at all — and defence in depth for claude.
+          "-c", `mcp_servers.beatrina.env={BEATRINA_MCP_URL=${toml(`${originOk}/`)}, BEATRINA_MCP_TOOLS=${toml(toolsFor(authority).join(","))}, CARMAR_MCP_URL=${toml(`${originOk}/`)}}`);   // beatrina-names: keep
       }
       args.push("-");                     // the prompt arrives on stdin
     } else {
       args = ["-p", "--output-format", "stream-json", "--verbose", "--include-partial-messages"];
       if (scalar(cmd.system)) args.push("--append-system-prompt", cmd.system);
       if (scalar(cmd.model) && cmd.model !== "default") args.push("--model", cmd.model);
-      if (textOnly) {
+      if (authority === "text") {
         args.push("--tools", "", "--mcp-config", '{"mcpServers":{}}', "--strict-mcp-config", "--setting-sources", "");
       } else if (server && node) {
-        cfg = path.join(os.tmpdir(), `carmar-chat-${crypto.randomBytes(8).toString("hex")}.json`);
-        fs.writeFileSync(cfg, `${JSON.stringify({ mcpServers: { carmar: {
-          command: node, args: [server], env: { CARMAR_MCP_URL: `${originOk}/` },
+        cfg = path.join(os.tmpdir(), `beatrina-chat-${crypto.randomBytes(8).toString("hex")}.json`);
+        fs.writeFileSync(cfg, `${JSON.stringify({ mcpServers: { beatrina: {
+          command: node, args: [server],
+          env: mirrorEnv({ BEATRINA_MCP_URL: `${originOk}/`, BEATRINA_MCP_TOOLS: toolsFor(authority).join(",") }),
         } } })}\n`, { mode: 0o600 });
         fs.chmodSync(cfg, 0o600);
-        args.push("--mcp-config", cfg, "--strict-mcp-config", "--allowedTools", AGENT_CHAT_TOOLS);
+        args.push("--mcp-config", cfg, "--strict-mcp-config", "--allowedTools", allowedToolsArg(authority));
       }
     }
 
@@ -357,7 +339,7 @@ export function createPlane({ spike, env, audit }) {
       const stale = (now - entry.at) / 1000 >= MCP_PENDING_MAX_S;
       if (!pageGone && !stale) continue;
       const why = pageGone
-        ? "The CarmaR notebook window that was answering this request closed before it replied."
+        ? "The Beatrina notebook window that was answering this request closed before it replied."
         : `The notebook did not answer within ${MCP_PENDING_MAX_S} seconds.`;
       audit("mcp-abandoned", { id, reason: pageGone ? "page closed" : "timeout" });
       pending.delete(id);
@@ -409,8 +391,8 @@ export function createPlane({ spike, env, audit }) {
       if (pathname !== "/mcp-info") return false;
       const blocked = ctx.controlRejection(req, { allowFile: true });
       if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
-      const dir = env("CARMAR_RUNTIME_DIR") || path.join(os.homedir(), ".carmar", "run");
-      const runtime = env("CARMAR_NO_RUNTIME_FILE") !== "1"
+      const dir = runtimeWriteDir(env);
+      const runtime = env("BEATRINA_NO_RUNTIME_FILE") !== "1"
         && fs.existsSync(path.join(dir, `kernel-${ctx.port()}.json`));
       ctx.respond(res, 200, "application/json", ctx.enc({
         server: mcpServerPath(here), runtime, text_only_chat: true,
@@ -445,8 +427,15 @@ export function createPlane({ spike, env, audit }) {
         const page = targetPage(ctx);
         audit("mcp-request", { id: cmd.id, detail: cmd.tool });
         if (!page) {
+          // Notebook tools are answered by the PAGE (it owns the document);
+          // the kernel alone has no notebook to read. Name the door, so an
+          // agent can say what the user should do instead of retrying.
           rec.ws.send(enc({ type: "mcp-response", id: cmd.id, ok: false,
-            error: "No CarmaR notebook window is connected to this kernel. Open the notebook first." }));
+            error: "No Beatrina notebook window is connected to this kernel, so notebook tools "
+              + "(notebook_read, chunk_read, chunk_insert, chunk_update, chunk_run, file_open) have "
+              + "nothing to answer them. Ask the user to open the document in Beatrina — double-click "
+              + "the .qmd, run `beatrina <file>`, or use File ▸ Open in a running window — then retry. "
+              + "beatrina_status, file_list and file_read need no window." }));
           return undefined;
         }
         pending.set(cmd.id, { rec, page, at: Date.now() });