beatrina 0.8.7 → 0.9.43

package/host/planes/choose.mjs

@@ -0,0 +1,404 @@
+// choose.mjs — the operating system's own Open / Save / Folder panel, opened
+// by the HOST and answered while R is busy.
+//
+// One op, `choose`: `{mode: "file"|"files"|"dir"|"save", prompt?, start?,
+// defaultName?, accept?: [".qmd", …]}`. The reply is exactly one of `{path}`
+// / `{paths}` (absolute, canonical), `{cancelled: true}`, `{unsupported: true,
+// reason}` (no tool, no display, the panel switched off) or `{error, busy?}`
+// (a second panel while one is open; a class or agent refusal; a tool that
+// failed, with its first stderr line; an answer that cannot be used — a file
+// where a folder was asked).
+//
+// WHY THE HOST, AND WHY AGAIN. The panel used to be opened by R
+// (`spike/chooser.R`, deleted 2026-09-09 by docs/document-model-plan.md D4):
+// it queued behind a running cell, it talked to System Events — an Apple
+// event, which is what put the Automation prompt in front of every Chrome
+// user — and it read "cannot show a panel" and "the person pressed Cancel"
+// as the same silent non-zero exit. This plane answers from the supervisor
+// (a forty-second fit does not delay File ▸ Open), raises the panel with a
+// BARE `activate` — osascript's own process, no `tell application …`, no
+// Apple event, no prompt, no plist key — and classifies cancel PER TOOL.
+//
+// The pure half (`chooseCommand`, `readChooserResult`) builds argument
+// vectors and reads results without a screen, so every adapter is tested on
+// every platform; only `createPlane` spawns. Never a shell string: the prompt
+// and the start folder reach AppleScript and PowerShell as SOURCE, escaped
+// as the retired chooser.R escaped them, and zenity/kdialog as plain argv.
+//
+// NO TIMEOUT ON A PANEL. A person may read a folder for ten minutes; the
+// child lives until they answer, the page's socket closes (`onClose` kills
+// it — a panel nobody can answer is worse than one that vanishes), or the
+// kernel stops (`shutdown`). `busy()` holds the idle clock open meanwhile.
+// One panel at a time, by a module lock: a second ask is `{error, busy}`
+// and the first still answers.
+//
+// Page-only in both senses (a panel is a UI gesture on THIS person's screen)
+// and refused to agents. `BEATRINA_NO_NATIVE_DIALOG` (any value) switches the
+// panel off: `choose` is then not advertised in `ready.commands` — that is
+// the page's whole face of the flag — and answers `{unsupported}` if asked
+// anyway. Binary overrides for tests and odd machines: BEATRINA_OSASCRIPT,
+// BEATRINA_POWERSHELL, BEATRINA_ZENITY, BEATRINA_KDIALOG. A named binary that
+// is missing is an `error` sentence the page shows, never "unsupported": a
+// misconfiguration must be said, not silently routed around.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { envSetName, readEnv } from "../env-names.mjs";
+import { whichSync } from "../which.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
+import { canonicalPath, fsAbs, makeRoot } from "./files.mjs";
+
+export const CHOOSE_MODES = Object.freeze(["file", "files", "dir", "save"]);
+const OPS = ["choose"];
+/** The env suffix that overrides each tool's binary (BEATRINA_<suffix>). */
+const TOOL_ENV = Object.freeze({ osascript: "OSASCRIPT", powershell: "POWERSHELL", zenity: "ZENITY", kdialog: "KDIALOG" });
+/** Output kept per stream: a path list is small; a runaway tool is not. */
+const OUTPUT_CAP = 64 * 1024;
+const PROMPT_MAX = 120;
+const NAME_MAX = 255;
+
+// eslint-disable-next-line no-control-regex
+const oneLine = (x, max) => String(x ?? "").replace(/[\x00-\x1f\x7f]/g, " ").replace(/\s+/g, " ").trim().slice(0, max);
+
+/** An AppleScript double-quoted literal: the two characters that end or escape one, and no line breaks. */
+export function appleScriptString(x) {
+  return `"${oneLine(x, 4096).replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+
+/** A PowerShell single-quoted literal: only the quote itself is special, doubled. */
+export function powerShellString(x) {
+  return `'${oneLine(x, 4096).replace(/'/g, "''")}'`;
+}
+
+/** The `-EncodedCommand` form PowerShell reads: UTF-16LE, base64. */
+export function encodePowerShell(script) {
+  return Buffer.from(script, "utf16le").toString("base64");
+}
+
+/**
+ * Read one request off the wire into the five fields the adapters take, or
+ * say what is wrong with it. Nothing else travels: no path is executed, no
+ * name reaches a shell.
+ *
+ * @returns {{mode:string, prompt:string, start:string, defaultName:string, accept:string[]}|{error:string}}
+ */
+export function readChooseRequest(cmd) {
+  const mode = typeof cmd.mode === "string" ? cmd.mode : "";
+  if (!CHOOSE_MODES.includes(mode)) return { error: `\`mode\` must be one of ${CHOOSE_MODES.join(", ")}.` };
+  const prompt = oneLine(cmd.prompt, PROMPT_MAX) || { file: "Open", files: "Open", dir: "Choose Folder", save: "Save" }[mode];
+  const start = typeof cmd.start === "string" ? cmd.start.trim().slice(0, 4096) : "";
+  const defaultName = oneLine(cmd.defaultName, NAME_MAX);
+  if (/[\\/]/.test(defaultName)) return { error: "`defaultName` is a file name, not a path." };
+  const accept = (Array.isArray(cmd.accept) ? cmd.accept : [])
+    .filter((e) => typeof e === "string" && /^\.[A-Za-z0-9]{1,16}$/.test(e))
+    .slice(0, 32);
+  return { mode, prompt, start, defaultName, accept };
+}
+
+/** Which binary runs `tool`: an override that exists, else PATH, else "" — or a sentence about an override that does not exist. */
+function binaryFor(tool, env, which) {
+  const override = readEnv(env, TOOL_ENV[tool]).trim();
+  if (override) {
+    let ok = false;
+    try { fs.accessSync(override, fs.constants.X_OK); ok = fs.statSync(override).isFile(); } catch { ok = false; }
+    if (ok) return { path: override };
+    return { error: `${envSetName(env, TOOL_ENV[tool])} names ${override}, which is not an executable file; unset it or point it at ${tool}.` };
+  }
+  return { path: which(tool) || "" };
+}
+
+/** `default location` / `InitialDirectory` / `--filename` only for a folder that exists. */
+const defaultDirExists = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+/**
+ * The argument vector that opens this platform's panel for `req`.
+ *
+ * @param {{mode:string, prompt?:string, start?:string, defaultName?:string, accept?:string[]}} req
+ *   `start` is already absolute (the plane resolves it against the worker's cwd)
+ * @param {{platform?:string, env?:object, which?:(name:string)=>string, dirExists?:(p:string)=>boolean}} [deps]
+ * @returns {{tool:string, command:string, args:string[], script?:string}
+ *   | {unsupported:true, reason:string} | {error:string}}
+ */
+export function chooseCommand(req, deps = {}) {
+  const platform = deps.platform || process.platform;
+  const env = deps.env || process.env;
+  const which = deps.which || ((name) => whichSync(name, env.source || env));
+  const dirExists = deps.dirExists || defaultDirExists;
+  const mode = req.mode;
+  const prompt = oneLine(req.prompt, PROMPT_MAX) || "Choose";
+  const start = typeof req.start === "string" && req.start && dirExists(req.start) ? req.start : "";
+  const name = mode === "save" ? oneLine(req.defaultName, NAME_MAX) : "";
+  const accept = Array.isArray(req.accept) ? req.accept.filter((e) => /^\.[A-Za-z0-9]{1,16}$/.test(e)) : [];
+  const exts = accept.map((e) => e.slice(1));
+
+  if (platform === "darwin") {
+    const bin = binaryFor("osascript", env, which);
+    if (bin.error) return { error: bin.error };
+    if (!bin.path) return { unsupported: true, reason: "osascript was not found on PATH, so macOS cannot show its file panel." };
+    const verb = mode === "dir" ? "choose folder" : mode === "save" ? "choose file name" : "choose file";
+    const parts = [`${verb} with prompt ${appleScriptString(prompt)}`];
+    // `of type` only for a door that names types: File ▸ Open (kind "all") sends none.
+    if ((mode === "file" || mode === "files") && exts.length) parts.push(`of type {${exts.map(appleScriptString).join(", ")}}`);
+    if (mode === "save" && name) parts.push(`default name ${appleScriptString(name)}`);
+    // Parentheses are syntax: `default location POSIX file` is read as adjacent
+    // parameter/class names; coercing the POSIX path first gives the alias.
+    if (start) parts.push(`default location (POSIX file ${appleScriptString(start)})`);
+    if (mode === "files") parts.push("with multiple selections allowed");
+    // A bare `activate` raises osascript's own process — no `tell application`,
+    // no Apple event, no Automation prompt. It must stay bare.
+    const script = mode === "files"
+      ? ["activate",
+        `set theItems to ${parts.join(" ")}`,
+        "set out to \"\"",
+        "repeat with anItem in theItems",
+        "  set out to out & POSIX path of anItem & linefeed",
+        "end repeat",
+        "out"].join("\n")
+      : ["activate", `POSIX path of (${parts.join(" ")})`].join("\n");
+    return { tool: "osascript", command: bin.path, args: ["-e", script], script };
+  }
+
+  if (platform === "win32") {
+    const bin = binaryFor("powershell", env, which);
+    if (bin.error) return { error: bin.error };
+    const found = bin.path || which("powershell.exe");
+    if (!found) return { unsupported: true, reason: "PowerShell was not found on PATH, so Windows cannot show its file panel." };
+    const filter = exts.length
+      ? `Matching files (${exts.map((e) => `*.${e}`).join(";")})|${exts.map((e) => `*.${e}`).join(";")}|All files (*.*)|*.*`
+      : "All files (*.*)|*.*";
+    const lines = [
+      "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+      "Add-Type -AssemblyName System.Windows.Forms",
+      // An owner form that is TopMost is what puts the panel over the browser
+      // window; without one it opens behind it and the page looks hung.
+      "$f = New-Object System.Windows.Forms.Form; $f.TopMost = $true",
+    ];
+    if (mode === "dir") {
+      lines.push("$d = New-Object System.Windows.Forms.FolderBrowserDialog",
+        `$d.Description = ${powerShellString(prompt)}`);
+      if (start) lines.push(`$d.SelectedPath = ${powerShellString(start)}`);
+      lines.push("if ($d.ShowDialog($f) -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.Write($d.SelectedPath) }");
+    } else if (mode === "save") {
+      lines.push("$d = New-Object System.Windows.Forms.SaveFileDialog",
+        `$d.Title = ${powerShellString(prompt)}`, `$d.Filter = ${powerShellString(filter)}`,
+        "$d.AddExtension = $true", "$d.OverwritePrompt = $true");
+      if (exts.length) lines.push(`$d.DefaultExt = ${powerShellString(exts[0])}`);
+      if (start) lines.push(`$d.InitialDirectory = ${powerShellString(start)}`);
+      if (name) lines.push(`$d.FileName = ${powerShellString(name)}`);
+      lines.push("if ($d.ShowDialog($f) -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.Write($d.FileName) }");
+    } else {
+      lines.push("$d = New-Object System.Windows.Forms.OpenFileDialog",
+        `$d.Title = ${powerShellString(prompt)}`, `$d.Filter = ${powerShellString(filter)}`,
+        `$d.Multiselect = ${mode === "files" ? "$true" : "$false"}`);
+      if (start) lines.push(`$d.InitialDirectory = ${powerShellString(start)}`);
+      lines.push("if ($d.ShowDialog($f) -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.Write(($d.FileNames -join \"`n\")) }");
+    }
+    const script = lines.join("\n");
+    return { tool: "powershell", command: found,
+      args: ["-NoProfile", "-NonInteractive", "-STA", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encodePowerShell(script)], script };
+  }
+
+  // Linux and everything else: a desktop chooser, if there is a desktop.
+  const display = readEnvPlain(env, "DISPLAY") || readEnvPlain(env, "WAYLAND_DISPLAY");
+  if (!display) return { unsupported: true, reason: "No display (DISPLAY and WAYLAND_DISPLAY are unset), so no file panel can be shown." };
+  const zen = binaryFor("zenity", env, which);
+  if (zen.error) return { error: zen.error };
+  if (zen.path) {
+    const args = ["--file-selection", `--title=${prompt}`];
+    if (mode === "dir") args.push("--directory");
+    if (mode === "save") args.push("--save", "--confirm-overwrite");
+    if (mode === "files") args.push("--multiple", "--separator=\n");
+    if (start) args.push(`--filename=${start.replace(/\/+$/, "")}/${mode === "save" ? name : ""}`);
+    else if (mode === "save" && name) args.push(`--filename=${name}`);
+    if ((mode === "file" || mode === "files") && exts.length) {
+      args.push(`--file-filter=Matching files | ${exts.map((e) => `*.${e}`).join(" ")}`, "--file-filter=All files | *");
+    }
+    return { tool: "zenity", command: zen.path, args };
+  }
+  const kd = binaryFor("kdialog", env, which);
+  if (kd.error) return { error: kd.error };
+  if (kd.path) {
+    const verb = mode === "dir" ? "--getexistingdirectory" : mode === "save" ? "--getsavefilename" : "--getopenfilename";
+    const at = start ? (mode === "save" && name ? `${start.replace(/\/+$/, "")}/${name}` : start) : (mode === "save" && name ? name : ".");
+    const args = ["--title", prompt];
+    if (mode === "files") args.push("--multiple", "--separate-output");
+    args.push(verb, at);
+    if ((mode === "file" || mode === "files") && exts.length) args.push(`${exts.map((e) => `*.${e}`).join(" ")}|Matching files\n*|All files`);
+    return { tool: "kdialog", command: kd.path, args };
+  }
+  return { unsupported: true, reason: "Neither zenity nor kdialog was found on PATH, so no file panel can be shown." };
+}
+
+/** A non-product variable, read from a plain object or the host's env reader. */
+function readEnvPlain(env, name) {
+  if (typeof env === "function") return String(env(name, "") || "");
+  return env && env[name] != null ? String(env[name]) : "";
+}
+
+/**
+ * What the tool said, classified — per tool, because "non-zero and silent"
+ * means Cancel for zenity and kdialog and "could not show a panel" for
+ * osascript, which always names a real cancel (`User canceled. (-128)`).
+ *
+ * @param {string} tool  osascript | powershell | zenity | kdialog
+ * @param {string} mode
+ * @param {{status:number|null, signal?:string|null, stdout?:string, stderr?:string}} out
+ * @returns {{path:string}|{paths:string[]}|{cancelled:true}|{error:string}}
+ */
+export function readChooserResult(tool, mode, { status, signal = null, stdout = "", stderr = "" }) {
+  const lines = String(stdout || "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const said = String(stderr || "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  if (status == null) return { error: `The file panel was closed before it answered${signal ? ` (${signal})` : ""}.` };
+  const text = `${said.join(" ")} ${lines.join(" ")}`;
+  if (status !== 0) {
+    if (tool === "osascript" && /user cancell?ed|\(-128\)/i.test(text)) return { cancelled: true };
+    if ((tool === "zenity" || tool === "kdialog") && status === 1 && !lines.length) return { cancelled: true };
+    return { error: `The file panel failed: ${said[0] || lines[0] || `exit status ${status}`}` };
+  }
+  if (!lines.length) {
+    // A PowerShell dialog writes nothing on Cancel; the others exit non-zero.
+    if (tool === "powershell") return { cancelled: true };
+    return { error: "The file panel returned nothing readable." };
+  }
+  if (mode === "files") return { paths: lines };
+  // A GTK warning can share zenity's stream; the path is the LAST line.
+  return { path: lines[lines.length - 1] };
+}
+
+/**
+ * Check an answer before the page sees it: absolute, existing as the kind
+ * asked for (the folder for a save), canonical, and inside BEATRINA_ROOT when
+ * one is set — refused here with the files plane's own sentence, one step
+ * before `readfile`/`writefile` would refuse the same path.
+ *
+ * @returns {{path:string}|{paths:string[]}|{error:string}}
+ */
+export function validateChosen(mode, answer, { root }) {
+  const one = (raw) => {
+    const p = String(raw).replace(/[\\/]+$/, "") || String(raw);
+    if (!path.isAbsolute(p)) return { error: `The file panel answered with a relative path (${p}).` };
+    const full = canonicalPath(p);
+    let st = null;
+    try { st = fs.statSync(full); } catch { st = null; }
+    if (mode === "dir") {
+      if (!st || !st.isDirectory()) return { error: `${full} is not a folder.` };
+    } else if (mode === "save") {
+      let parent = null;
+      try { parent = fs.statSync(path.dirname(full)); } catch { parent = null; }
+      if (!parent || !parent.isDirectory()) return { error: `The folder ${path.dirname(full)} does not exist.` };
+      if (st && st.isDirectory()) return { error: `${full} is a folder, not a file name.` };
+    } else if (!st || !st.isFile()) {
+      return { error: `${full} is not a file.` };
+    }
+    if (!root.within(full)) return { error: root.outsideMsg() };
+    return { path: full };
+  };
+  if (mode === "files") {
+    const paths = [];
+    for (const raw of answer.paths || []) {          // every path is checked; the first bad one is the answer
+      const r = one(raw);
+      if (r.error) return r;
+      paths.push(r.path);
+    }
+    if (!paths.length) return { error: "The file panel returned nothing readable." };
+    return { paths };
+  }
+  return one(answer.path);
+}
+
+export function createPlane({ env, audit }) {
+  const flagged = env("BEATRINA_NO_NATIVE_DIALOG") !== "";
+  const offReason = `The OS file panel is switched off (${envSetName(env.source || process.env, "NO_NATIVE_DIALOG")} is set).`;
+  // Decided ONCE, at start: whether this machine can show a panel at all.
+  // `{error}` (an override naming a missing binary) still counts as available
+  // so the page asks and the misconfiguration sentence reaches the person.
+  const probe = flagged ? { unsupported: true, reason: offReason } : chooseCommand({ mode: "file", prompt: "Open" }, { env });
+  const available = probe.unsupported !== true;
+  const root = makeRoot(env("BEATRINA_ROOT"));
+  /** The one open panel: {child, rec, id, mode, tool, killed}. */
+  let open = null;
+  const alive = (child) => child && child.exitCode === null && child.signalCode === null;
+  const kill = (why) => {
+    if (!open || !alive(open.child)) return;
+    open.killed = why;
+    try { open.child.kill("SIGKILL"); } catch { /* already gone */ }
+  };
+
+  return {
+    name: "choose",
+    ops: OPS,
+    agentRefused: OPS,
+    agentReason: () => "Agents cannot open a file panel on this person's screen; ask the page to open or save the file.",
+    commands: available ? OPS : [],
+    capabilities: available ? ["native-dialog-v1"] : [],
+
+    handle(cmd, rec, ctx) {
+      if (rec.role !== "page" || !ctx.scalarChr(cmd.id)) return undefined;
+      const reply = (fields) => {
+        try { rec.ws.send(ctx.enc({ type: "choose", id: cmd.id, ...fields })); } catch { /* the page has gone; nothing to tell */ }
+      };
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("choose-refused", { reason: "class", class: rec.class || "unknown" });
+        return reply({ error: "Only the local notebook page may open the file panel." });
+      }
+      const req = readChooseRequest(cmd);
+      if (req.error) return reply({ error: req.error });
+      if (flagged) return reply({ unsupported: true, reason: offReason });
+      if (open && alive(open.child)) {
+        audit("choose-refused", { reason: "busy" });
+        return reply({ error: "A file panel is already open — answer it first.", busy: true });
+      }
+      // A relative start is the worker's business: resolved against the cwd it
+      // last reported, exactly as the files plane resolves a relative path.
+      const start = req.start ? fsAbs(req.start, ctx.plane.workerWd) : "";
+      const spec = chooseCommand({ ...req, start }, { env });
+      if (spec.unsupported) return reply({ unsupported: true, reason: spec.reason });
+      if (spec.error) return reply({ error: spec.error });
+
+      let child;
+      try {
+        child = spawn(spec.command, spec.args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+      } catch (e) {
+        return reply({ error: `The file panel could not start: ${e.message}` });
+      }
+      const mine = { child, rec, id: cmd.id, mode: req.mode, tool: spec.tool, killed: "" };
+      open = mine;
+      let stdout = "";
+      let stderr = "";
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (d) => { if (stdout.length < OUTPUT_CAP) stdout += d; });
+      child.stderr.on("data", (d) => { if (stderr.length < OUTPUT_CAP) stderr += d; });
+      let done = false;
+      const finish = (answer) => {
+        if (done) return;
+        done = true;
+        if (open === mine) open = null;
+        const outcome = answer.cancelled ? "cancelled" : answer.error ? "error" : "chosen";
+        audit("choose-answered", { mode: req.mode, tool: spec.tool, outcome, ...(mine.killed ? { killed: mine.killed } : {}) });
+        // A page that left while the panel was up has nobody to answer.
+        if (ctx.sockets.includes(rec)) reply(answer);
+      };
+      child.on("error", (e) => finish({ error: `The file panel could not start: ${e.message}` }));
+      child.on("close", (status, signal) => {
+        if (mine.killed) return finish({ error: `The file panel was closed (${mine.killed}).` });
+        const read = readChooserResult(spec.tool, req.mode, { status, signal, stdout, stderr });
+        if (read.cancelled || read.error) return finish(read);
+        finish(validateChosen(req.mode, read, { root }));
+      });
+      return undefined;
+    },
+
+    /** A panel that is up holds the idle clock open: a person is looking at it. */
+    busy: () => open != null && alive(open.child),
+
+    /** The page that asked has gone: a panel nobody can answer is worse than one that vanishes. */
+    onClose(rec) { if (open && open.rec === rec) kill("page closed"); },
+
+    /** The kernel is going; no panel may outlive it. */
+    shutdown() { kill("kernel stopping"); },
+  };
+}
+
+export default { createPlane };

package/host/planes/cite.mjs

@@ -33,11 +33,13 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
-import { appId } from "../user-dirs.mjs";
+import { appId, rUserDir } from "../user-dirs.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
 import {
   CSL_NAME_RE, cslInfo, cslIndexUrl, pluginFetch, pluginIdOk, pluginInstall,
-  pluginPolicyOnce, pluginPolicyReason, pluginRemove, pluginRows, rUserDir,
+  pluginPolicyOnce, pluginPolicyReason, pluginRemove, pluginRows,
 } from "../plugin-store.mjs";
+import { whichSync } from "../which.mjs";
 
 export { cslInfo, cslLooksLikeStyle } from "../plugin-store.mjs";
 
@@ -53,7 +55,6 @@ const CSL_MAX_INDEX_BYTES = 8000000;
 const CSL_INDEX_MAX_AGE_DAYS = 7;
 const CSL_SEARCH_LIMIT = 40;
 
-const PAGE_ONLY_CLASSES = ["served", "file", "local"];
 const OPS = ["cite", "cite_styles", "csl_place", "csl_search", "csl_import", "csl_remove"];
 /** Every op but `cite_styles`: a process, a file, or the network. */
 const AGENT_REFUSED = ["cite", "csl_place", "csl_search", "csl_import", "csl_remove"];
@@ -207,7 +208,6 @@ export function cslRemove(here, policy, env, file) {
 
 /* ── pandoc ───────────────────────────────────────────────────────────────── */
 
-const isExecutable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } };
 
 /**
  * Locate pandoc, the ladder spike/cite.R climbs: an explicit override, what
@@ -219,23 +219,24 @@ const isExecutable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return
  * starting an R process to find a binary — the host would spawn a worker to
  * answer a question about the file system — so the bundle list below carries
  * the same answers rmarkdown reaches for. On this machine both resolve to the
- * same binary; where they could differ, CARMAR_PANDOC settles it.
+ * same binary; where they could differ, BEATRINA_PANDOC settles it.
  *
  * @returns {string} the path, or "".
  */
 export function findPandoc(env) {
-  const explicit = env("CARMAR_PANDOC", "");
+  const explicit = env("BEATRINA_PANDOC", "");
   if (explicit && fs.existsSync(explicit)) return explicit;
   const fromEnv = env("RSTUDIO_PANDOC", "");
   if (fromEnv) {
     const cand = path.join(fromEnv, process.platform === "win32" ? "pandoc.exe" : "pandoc");
     if (fs.existsSync(cand)) return cand;
   }
-  const exe = process.platform === "win32" ? "pandoc.exe" : "pandoc";
-  for (const dir of String(env("PATH", "")).split(path.delimiter).filter(Boolean)) {
-    const cand = path.join(dir, exe);
-    if (isExecutable(cand)) return cand;
-  }
+  // The PATH walk is host/which.mjs's, which was lifted out precisely so two
+  // planes could not disagree about what "on PATH" means. This copy tried only
+  // `pandoc.exe` on Windows, where whichSync walks PATHEXT. `env` here is a
+  // READER, so PATH is handed over as the object whichSync expects.
+  const onPath = whichSync("pandoc", { PATH: env("PATH", "") });
+  if (onPath) return onPath;
   const arch = ["arm64"].includes(process.arch) ? "aarch64" : "x86_64";
   const bundles = [
     `/Applications/RStudio.app/Contents/Resources/app/quarto/bin/tools/${arch}/pandoc`,
@@ -327,7 +328,7 @@ export function citeValidate(here, policy, env, cmd) {
 export function citeDocument(yaml, groups) {
   const paras = groups.map((g) => {
     const cite = g.narrative ? `@${g.keys[0]}` : `[${g.keys.map((k) => `@${k}`).join("; ")}]`;
-    return `[${cite}]{.carmar-cite-group}`;
+    return `[${cite}]{.beatrina-cite-group}`;
   });
   return `---\n${yaml}\n---\n\n${paras.join("\n\n")}\n`;
 }
@@ -335,13 +336,13 @@ export function citeDocument(yaml, groups) {
 /**
  * Split pandoc's HTML into the group labels and the bibliography.
  *
- * Positional: the i-th `carmar-cite-group` span is the i-th group. A group span
+ * Positional: the i-th `beatrina-cite-group` span is the i-th group. A group span
  * holds nested spans of its own, so the closing tag is found by WALKING span
  * tags and counting depth, never by a non-greedy match.
  */
 export function citeSplit(html, nGroups) {
   const labels = new Array(nGroups).fill("");
-  const open = '<span class="carmar-cite-group">';
+  const open = '<span class="beatrina-cite-group">';
   const starts = [];
   for (let at = html.indexOf(open); at !== -1; at = html.indexOf(open, at + 1)) starts.push(at);
   for (let i = 0; i < Math.min(starts.length, nGroups); i += 1) {
@@ -369,8 +370,8 @@ export function citeSplit(html, nGroups) {
 
 /** Run pandoc over one validated request. */
 export async function citeRun(bin, valid, timeoutMs = CITE_TIMEOUT_MS) {
-  if (!bin) return { ok: false, error: "pandoc is not installed, or CarmaR could not find it." };
-  const input = path.join(os.tmpdir(), `carmar-cite-${crypto.randomBytes(8).toString("hex")}.md`);
+  if (!bin) return { ok: false, error: "pandoc is not installed, or Beatrina could not find it." };
+  const input = path.join(os.tmpdir(), `beatrina-cite-${crypto.randomBytes(8).toString("hex")}.md`);
   try {
     fs.writeFileSync(input, citeDocument(valid.yaml, valid.groups));
     fs.chmodSync(input, 0o600);
@@ -482,7 +483,7 @@ export function createPlane({ spike, env, audit }) {
 
       // csl_place: the style beside the document, as a .bib sits beside a .tex
       // — what makes `csl: apa.csl` in the front matter render the same style
-      // with no CarmaR present. A dependent style's parent goes too, or pandoc
+      // with no Beatrina present. A dependent style's parent goes too, or pandoc
       // would go looking for it. NEVER overwrites: a different file of that
       // name beside the document is the author's, and is reported.
       const style = cslResolve(here, policy, env, cmd.name);