beatrina 0.9.43 → 1.0.0

package/host/main.mjs

@@ -14,6 +14,8 @@
 //   BEATRINA_RUNTIME_DIR (default ~/.beatrina/run; host/runtime-dir.mjs),
 //   BEATRINA_NO_RUNTIME_FILE=1, BEATRINA_LINGER, BEATRINA_BOOT_GRACE,
 //   BEATRINA_WORKER_DEADLINE_SCALE, BEATRINA_WORKER_RESPAWN_MAX,
+//   BEATRINA_NO_R=1 (the R engine is off — tests and administrators; the host
+//   serves without it, plans/getting_rid_of_R.md K2b),
 //   BEATRINA_OPEN_FILE, BEATRINA_HOST_ROOT, BEATRINA_KERNEL_DIR (WP7: where
 //   the files are when the host is not running from a source checkout — see
 //   hostRoot/kernelDir). Children are handed both spellings (mirrorEnv).
@@ -104,17 +106,22 @@ function hostRoot() {
 }
 
 /**
- * The directory holding the R kernel scripts and the build stamps.
+ * The directory holding the build stamps (and the R kernel scripts, when this
+ * Beatrina carries R's worker).
  *
  * `spike/` in the repo; `kernel/` in every distribution, because that is what
  * tools/ship/build-r-pkg.sh and tools/app/build-app.sh have always called it.
- * Named by BEATRINA_KERNEL_DIR when a launcher knows better.
+ * Named by BEATRINA_KERNEL_DIR when a launcher knows better. Recognised by its
+ * protocol STAMP, which the host needs whatever engines exist, and only then
+ * by R's worker — a host must be findable without R (plans/getting_rid_of_R.md A5).
  */
 function kernelDir(base) {
   const dictated = env("BEATRINA_KERNEL_DIR").trim();
   if (dictated) return path.resolve(dictated);
-  for (const name of ["spike", "kernel"]) {
-    if (fs.existsSync(path.join(base, name, "worker-boot.R"))) return path.join(base, name);
+  for (const marker of ["kernel-protocol", "worker-boot.R"]) {
+    for (const name of ["spike", "kernel"]) {
+      if (fs.existsSync(path.join(base, name, marker))) return path.join(base, name);
+    }
   }
   return path.join(base, "spike");
 }
@@ -194,16 +201,21 @@ function notebookFileUrl(p, port, cap) {
 // ── the handoff successor's preflight ───────────────────────────────────────
 /**
  * Everything a successor needs to serve the session it is taking over, checked while the
- * predecessor is still serving it: its page, its worker, and an R that runs. A protocol or build
- * stamp that cannot be read has already thrown by the time this is called (main's first lines),
- * which the predecessor sees as an exit before `ready`.
+ * predecessor is still serving it. The HOST's floor is the page — the document. A protocol or
+ * build stamp that cannot be read has already thrown by the time this is called (main's first
+ * lines), which the predecessor sees as an exit before `ready`.
+ *
+ * R is part of the floor only when the predecessor's R is RUNNING (`needsR`, set by
+ * planes/sessions.mjs): handing a live R session to a successor that cannot run R would drop it.
+ * A session that never started R hands off with or without one (plans/getting_rid_of_R.md A4).
  * @returns {Promise<{ok:boolean, error?:string, build:string, pid:number}>}
  */
-async function handoffPreflight(kernelBuild, settings) {
+async function handoffPreflight(kernelBuild, settings, { needsR = false } = {}) {
   const fail = (error) => ({ ok: false, error, build: kernelBuild, pid: process.pid });
   if (!notebookPage(kernelBuild, { fallback: false })) return fail(`it has no notebook page for Beatrina ${kernelBuild}`);
+  if (!needsR) return { ok: true, build: kernelBuild, pid: process.pid };
   if (!fs.existsSync(path.join(spike, "worker-boot.R"))) return fail(`its R worker is missing (${path.join(spike, "worker-boot.R")})`);
-  const rscript = detectRscript(settings.rscriptPreference());
+  const rscript = env("BEATRINA_NO_R") === "1" ? "" : detectRscript(settings.rscriptPreference());
   if (!rscript) return fail("it cannot find R");
   const { execFile } = await import("node:child_process");
   const ran = await new Promise((resolve) => {
@@ -309,9 +321,11 @@ async function main() {
   // A handoff successor PROVES it can run before it waits for the port its predecessor still
   // holds (planes/sessions.mjs handoffBegin, phase 1). The predecessor retires only on `ok`.
   const handoffReady = env("BEATRINA_HANDOFF_READY").trim();
+  const handoffNeedsR = env("BEATRINA_HANDOFF_NEEDS_R") === "1";
   unsetEnv(process.env, "HANDOFF_READY");
+  unsetEnv(process.env, "HANDOFF_NEEDS_R");
   if (handoffReady) {
-    const verdict = await handoffPreflight(kernelBuild, settings);
+    const verdict = await handoffPreflight(kernelBuild, settings, { needsR: handoffNeedsR });
     writeHandoffReady(handoffReady, verdict);
     if (!verdict.ok) {
       console.error(`Beatrina will not take over the session: ${verdict.error}`);
@@ -334,10 +348,11 @@ async function main() {
   };
 
   // ── the engines and the pool ───────────────────────────────────────────────
-  // R is spawned at boot: the page will not leave "connecting" until a `ready`
-  // arrives. Every other engine starts the first time a chunk of its language
-  // runs (docs/host-plan.md §1) — an ipykernel nobody asked for is 1.3 seconds
-  // and tens of megabytes spent on a document that may hold no Python at all.
+  // No engine is on the start-up path: a page waits for the HOST (`host-ready`,
+  // host/server.mjs). R boots in the BACKGROUND when it is found — optional is
+  // not late — and every other engine starts the first time a chunk of its
+  // language runs (docs/host-plan.md §1): an ipykernel nobody asked for is 1.3
+  // seconds and tens of megabytes spent on a document that may hold no Python.
   const workerPath = path.join(spike, "worker-boot.R");
   const pythonWorker = path.join(root, "engines", "python", "worker.py");
   const deadlineScale = Number(env("BEATRINA_WORKER_DEADLINE_SCALE", "1")) > 0 ? Number(env("BEATRINA_WORKER_DEADLINE_SCALE", "1")) : 1;
@@ -372,13 +387,30 @@ async function main() {
       ? { available: false, detail: `This Beatrina does not carry the JavaScript worker (${jsWorker}).`, path: "", version: "" }
       : detectNode({ env: process.env });
   audit("engine-discovery", { engine: "js", available: nodeFound.available, detail: nodeFound.detail });
+  let rVersionHint = "";
   const pinned = (engine, make) => guardFactory(make, { enabled: payloadGuard, boot: bootPayload, bootBuild: kernelBuild, measure: measurePayload, audit, engine });
 
+  // R's availability is a QUESTION asked before every start (K2b), from the
+  // same resolved settings the spawn reads, so installing R or pointing
+  // Settings at another one needs no host restart. Absent R is a stated fact
+  // on R's engine row, never a host that will not come up (A1).
+  const rAbsent = (detail) => ({ available: false, detail, runtime: { path: "", why: detail } });
+  const detectR = () => {
+    if (env("BEATRINA_NO_R") === "1") return rAbsent(`The R engine is disabled (${envSetName(process.env, "NO_R")}=1).`);
+    if (!fs.existsSync(workerPath)) return rAbsent(`This Beatrina does not carry the R worker (${workerPath}).`);
+    const rscript = detectRscript(settings.rscriptPreference());
+    if (!rscript) return rAbsent("No R was found. Install R from https://cran.r-project.org, or set the path to Rscript in Settings.");
+    return { available: true, detail: "", version: rVersionHint, runtime: { path: rscript, why: "" } };
+  };
+  const rFound = detectR();
+  audit("engine-discovery", { engine: "r", available: rFound.available, detail: rFound.detail });
+
   const ENGINE_SPECS = [
     // WP5a — which R, and what the child inherits, come from the resolved
     // settings (`rscript_path`, the child env). Read per spawn, never
     // captured, so Restart R picks up a changed binary.
-    { name: "r", label: "R", boot: "eager", available: true,
+    { name: "r", label: "R", boot: env("BEATRINA_R_BOOT") === "on-demand" ? "on-demand" : "background",
+      ...rFound, detect: detectR,
       factory: pinned("r", () => new REngine({
         workerPath, handoffScript: path.join(root, "engines", "r", "handoff.R"),
         rscript: detectRscript(settings.rscriptPreference()),
@@ -398,13 +430,12 @@ async function main() {
   // `/health r` before the worker is ready: ask the chosen Rscript once, in
   // the background, so a launcher polling /health the instant the port answers
   // sees the R it is about to get rather than "".
-  let rVersionHint = "";
   {
     const { execFile } = await import("node:child_process");
-    const rscript = detectRscript(settings.rscriptPreference());
+    const rscript = rFound.available ? rFound.runtime.path : "";
     if (rscript) execFile(rscript, ["--version"], { timeout: 5000 }, (err, stdout, stderr) => {
       const m = String(stdout || "").concat(String(stderr || "")).match(/version (\d+\.\d+(?:\.\d+)?)/);
-      if (!err && m) rVersionHint = m[1];
+      if (!err && m) { rVersionHint = m[1]; const spec = ENGINE_SPECS.find((x) => x.name === "r"); if (spec && !spec.version) spec.version = m[1]; }
     });
   }
 
@@ -634,6 +665,15 @@ async function main() {
   }, 1000).unref();
 
   for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(sig, () => shutdown(sig));
+  // A window that started this host (Beatrina) holds its stdin open for as long as it lives. It
+  // stops the host itself on a clean quit; this covers the unclean one — a crash or a Force Quit
+  // closes the pipe, and without it the host would outlive its window forever (idle shutdown is off
+  // by default). BEATRINA_EXIT_WITH_STDIN=1 opts in; nothing else reads the host's stdin.
+  if (readEnv(process.env, "EXIT_WITH_STDIN") === "1") {
+    process.stdin.on("end", () => shutdown("the window that started this session is gone"));
+    process.stdin.on("error", () => shutdown("the window that started this session is gone"));
+    process.stdin.resume();
+  }
   process.on("exit", () => { try { if (typeof plane.killAll === "function") plane.killAll(); else if (plane.engine && plane.engine.alive) plane.engine.kill(); } catch { /* gone */ } });
 }
 

package/host/planes/analyze.mjs

@@ -2,7 +2,9 @@
 // it, one per language — spike/analyze.R and engines/python/analyze.py — each
 // with its own queue, its own slot and its own routes. A request's `engine`
 // picks the child; an ABSENT engine is R, so every page that predates Python
-// analysis reaches analyze.R exactly as before.
+// analysis reaches analyze.R exactly as before — when this host HAS R. With no
+// R the request is answered with the reason, never a spawn that cannot work
+// (plans/getting_rid_of_R.md A6).
 //
 // A port of spike/serve.R's analyzer half (`ANALYZE_FORWARDED`,
 // `ensure_analyzer`, `route_analyze`, `enqueue_analyze_command`,
@@ -317,7 +319,21 @@ export function createPlane({ root, spike, env, audit }) {
   let pool = null;
 
   const lanes = {
-    r: createLane({ name: "r", label: "R", makeEngine: () => new REngine({ workerPath: rWorkerPath, mode: "batch" }) }),
+    r: createLane({
+      name: "r", label: "R",
+      makeEngine: () => {
+        // The SAME R the R engine runs on — the pool's own spec, re-read now
+        // (K2b), including BEATRINA_NO_R and the Rscript chosen in Settings —
+        // so "R is available" means one thing on this host.
+        const spec = pool && typeof pool.refresh === "function" ? pool.refresh("r")
+          : pool && Array.isArray(pool.specs) ? pool.specs.find((x) => x.name === "r") : null;
+        if (spec && !spec.available) {
+          return { error: `R analysis is unavailable: ${spec.detail || "No R was found."}` };
+        }
+        const rscript = spec && spec.runtime && spec.runtime.path ? spec.runtime.path : undefined;
+        return new REngine({ workerPath: rWorkerPath, mode: "batch", ...(rscript ? { rscript } : {}) });
+      },
+    }),
     python: createLane({
       name: "python", label: "Python",
       makeEngine: () => {

package/host/planes/choose.mjs

@@ -50,7 +50,12 @@ 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"];
+// `choose_cancel` closes the panel the SAME page opened, from the page: the
+// panel can open behind the window or on another Space, and a page that says
+// "a panel is open on your desktop" must also offer a way out of it
+// (FINDINGS 2026-09-22 B6). Answered as a plain cancel, not an error.
+const OPS = ["choose", "choose_cancel"];
+const PAGE_CANCEL = "cancelled from the page";
 /** 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. */
@@ -342,6 +347,11 @@ export function createPlane({ env, audit }) {
         audit("choose-refused", { reason: "class", class: rec.class || "unknown" });
         return reply({ error: "Only the local notebook page may open the file panel." });
       }
+      if (cmd.type === "choose_cancel") {
+        const had = !!(open && open.rec === rec && alive(open.child));
+        if (had) kill(PAGE_CANCEL);
+        return reply({ ok: true, closed: had });
+      }
       const req = readChooseRequest(cmd);
       if (req.error) return reply({ error: req.error });
       if (flagged) return reply({ unsupported: true, reason: offReason });
@@ -382,7 +392,8 @@ export function createPlane({ env, audit }) {
       };
       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}).` });
+        if (mine.killed) return finish(mine.killed === PAGE_CANCEL ? { cancelled: true }
+          : { 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 }));

package/host/planes/expect-term.mjs

@@ -0,0 +1,102 @@
+// expect-term.mjs — a REAL pty for the terminal, without a native module.
+//
+// A packaged Beatrina executable can load no native module, so node-pty is
+// never there and the terminal fell to plain pipes: "This terminal has no pty:
+// line programs work; full-screen programs and password prompts do not"
+// (FINDINGS 2026-09-22 B8, the installed app). But the machine usually has a
+// pty provider of its own: `expect` (Tcl) ships with macOS and is one package
+// away on Linux, and its whole job is to run a program on a pseudo-terminal
+// while reading and writing plain pipes. Measured on macOS 15: `tty` answers
+// /dev/ttys001, `stty size` the size asked for, and `read -s` hides a
+// password as a terminal should.
+//
+// The shape is node-pty's IPty (pid · pty · onData · onExit · write · resize ·
+// kill), so host/planes/terminal.mjs keeps one code path:
+//   · write: raw bytes into the pty — Enter, ^C, ^D, arrows mean what they
+//     mean at a terminal, because the line discipline is real;
+//   · resize: a private escape sequence the expect script intercepts and turns
+//     into `stty rows … columns …` on the pty, which is what makes the kernel
+//     deliver SIGWINCH to the foreground program;
+//   · kill: the expect process group; the shell, in its own session on the
+//     pty, gets the hangup a closed terminal gives.
+
+import { spawn } from "node:child_process";
+
+/** The escape a resize travels as; nothing a person types can produce it. */
+export const RESIZE_PREFIX = "\x1b]beatrina-resize;";
+
+/**
+ * The expect program. It reads its parameters from the environment rather
+ * than from a command line, so a shell path with a space or a quote is never
+ * pasted into Tcl source: BEATRINA_TERM_ARGV is the argument vector joined by
+ * TAB (a TAB cannot occur in a path we would run), and the size is two numbers.
+ */
+export const EXPECT_SCRIPT = [
+  "log_user 1",
+  "set stty_init \"rows $env(BEATRINA_TERM_ROWS) columns $env(BEATRINA_TERM_COLS)\"",
+  "set argl [split $env(BEATRINA_TERM_ARGV) \"\\t\"]",
+  "spawn -noecho {*}$argl",
+  "set slave $spawn_out(slave,name)",
+  "interact {",
+  "  -re \"\\033\\\\\\]beatrina-resize;(\\[0-9\\]+);(\\[0-9\\]+)\\007\" {",
+  "    catch {stty rows $interact_out(2,string) columns $interact_out(1,string) < $slave}",
+  "  }",
+  "}",
+  "catch {wait} result",
+  "exit [lindex $result 3]",
+].join("\n");
+
+/**
+ * Start `file args…` on a pty through expect.
+ *
+ * @param {string} expectBin   the expect executable (whichSync("expect"))
+ * @param {string} file
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: object, cols?: number, rows?: number, spawnImpl?: Function, signal?: Function}} opts
+ * @returns {{pid:number, pty:true, onData:Function, onExit:Function, write:Function, resize:Function, kill:Function}}
+ */
+export function expectSpawn(expectBin, file, args, opts = {}) {
+  const spawnImpl = opts.spawnImpl || spawn;
+  const signal = opts.signal || ((pid, sig) => process.kill(pid, sig));
+  const cols = Math.round(Number(opts.cols) || 100);
+  const rows = Math.round(Number(opts.rows) || 30);
+  const argv = [file, ...(args || [])];
+  if (argv.some((a) => String(a).includes("\t"))) throw new Error("a terminal argument contains a TAB");
+  const child = spawnImpl(expectBin, ["-c", EXPECT_SCRIPT], {
+    cwd: opts.cwd,
+    env: { ...(opts.env || process.env), BEATRINA_TERM_ARGV: argv.join("\t"),
+      BEATRINA_TERM_COLS: String(cols), BEATRINA_TERM_ROWS: String(rows) },
+    stdio: ["pipe", "pipe", "pipe"],
+    detached: true,
+  });
+  const dataFns = [];
+  const exitFns = [];
+  const emit = (d) => dataFns.forEach((fn) => { try { fn(d); } catch { /* a listener must not break the stream */ } });
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", emit);
+  child.stderr.on("data", emit);
+  child.stdin.on("error", () => { /* the terminal has gone; exit says so */ });
+  let exited = false;
+  const done = (exitCode) => { if (exited) return; exited = true; exitFns.forEach((fn) => fn({ exitCode })); };
+  child.on("exit", (code) => done(code));
+  child.on("error", (e) => { emit(`[the terminal could not start: ${e.message}]\r\n`); done(null); });
+  return {
+    pid: child.pid,
+    pty: true,
+    onData: (fn) => { dataFns.push(fn); },
+    onExit: (fn) => { exitFns.push(fn); },
+    write(text) { try { child.stdin.write(String(text)); } catch { /* gone */ } },
+    resize(c, r) {
+      const cc = Math.round(Number(c)), rr = Math.round(Number(r));
+      if (!(cc > 0) || !(rr > 0)) return;
+      try { child.stdin.write(`${RESIZE_PREFIX}${cc};${rr}\x07`); } catch { /* gone */ }
+    },
+    kill() {
+      try { signal(-child.pid, "SIGKILL"); } catch { /* the group is gone */ }
+      try { signal(child.pid, "SIGKILL"); } catch { /* gone */ }
+    },
+  };
+}
+
+export default expectSpawn;

package/host/planes/jobs.mjs

@@ -33,6 +33,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { REngine } from "../engine-r.mjs";
+import { NodeJobEngine } from "../engine-node-job.mjs";
 import { killProcessTree } from "./proc-tree.mjs";
 import { readEnv } from "../env-names.mjs";
 
@@ -318,8 +319,27 @@ const AGENT_REFUSED = Object.freeze({
  * @param {{root: string, spike: string, env: (n: string, d?: string) => string,
  *   audit: (event: string, fields?: object) => void}} deps
  */
-export function createPlane({ spike, env, audit }) {
+/**
+ * The tasks the Node child runs when this session has no R: every task that
+ * acts on a DOCUMENT. `latex` joined when spike/latex.R's compile was ported to
+ * host/latex-compile.mjs (K7); only the package tasks still need R.
+ */
+const NODE_TASKS = new Set(["render", "typst", "latex"]);
+
+export function createPlane({ root, spike, env, audit }) {
   const jobRun = path.join(spike, "job-run.R");
+  // A render with no R in this session runs Quarto from Node instead
+  // (plans/getting_rid_of_R.md Stage 3): the R child cannot start at all
+  // without R, and a prose document needs none. With R the R child renders,
+  // exactly as before — rmarkdown for an .Rmd is an R package.
+  const documentChild = path.join(root || path.resolve(spike, ".."), "host", "jobs", "document-child.mjs");
+  /** Does this session have R right now? Read at the start of each job (K2b). */
+  const rAvailable = () => {
+    const pool = ctxRef && ctxRef.plane;
+    if (!pool || typeof pool.refresh !== "function") return true;   // an older host: R, as always
+    const spec = pool.refresh("r");
+    return !spec || Boolean(spec.available);
+  };
   // 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.
@@ -442,10 +462,23 @@ export function createPlane({ spike, env, audit }) {
     const id = `job-${seq}`;
     let engine;
     try {
-      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";
+      const haveR = rAvailable();
+      if (!haveR && NODE_TASKS.has(spec.task)) {
+        engine = new NodeJobEngine({ workerPath: documentChild, env: { ...spec.env, BEATRINA_JOB_ID: id, BEATRINA_JOB_R_AVAILABLE: "0" } });
+      } else if (!haveR) {
+        // Said before anything is spawned, in the task's own terms — not
+        // "the job process could not start: REngine: no Rscript found". Only a
+        // package task reaches here: every document task is in NODE_TASKS.
+        const why = `${JOB_TASKS[spec.task].label} is an R package task, and R is not available in this session.`;
+        audit("job-refused", { detail: `no R: ${spec.task}` });
+        jobEmit("", { event: "refused", request, error: why });
+        return;
+      } else {
+        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";
+      }
     } catch (e) {
       audit("job-start-failed", { detail: e.message });
       jobEmit(id, { event: "refused", request, error: `the job process could not start: ${e.message}` });

package/host/planes/sessions.mjs

@@ -409,7 +409,11 @@ export function createPlane({ root, env, audit }) {
       BEATRINA_SESSION_TITLE: record.title || "",
       BEATRINA_SESSION_DOCUMENTS: encodeSessionDocuments(ctx.sessionDocuments?.() || []),
       // Only a token travels, never a path; the successor re-checks it.
-      BEATRINA_RESUME_TOKEN: h.resume || "" }, "LISTEN");
+      BEATRINA_RESUME_TOKEN: h.resume || "",
+      // A session whose R is RUNNING must not be handed to a successor with no working R — that
+      // would drop the R session it was asked to continue. A session that never started R has
+      // nothing of R's to lose and hands off with or without one (plans/getting_rid_of_R.md A4).
+      BEATRINA_HANDOFF_NEEDS_R: ctx.plane && ctx.plane.primary && ctx.plane.primary.engine ? "1" : "" }, "LISTEN");
     if (record.listen) childEnv.BEATRINA_LISTEN = "1";
     const logPath = path.join(dir, `kernel-handoff-${port}.log`);
     // The log is appended across attempts: only what THIS successor wrote is quoted.

package/host/planes/terminal.mjs

@@ -30,6 +30,8 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { killProcessTree } from "./proc-tree.mjs";
 import { PIPE_NOTICE, pipeShell, pipeSpawn } from "./pipe-term.mjs";
+import { expectSpawn } from "./expect-term.mjs";
+import { whichSync } from "../which.mjs";
 import { envSetName, mirrorEnv } from "../env-names.mjs";
 
 const MAX_TERMS = 4;
@@ -123,6 +125,7 @@ export function createPlane({ env, audit }) {
   const terms = new Map();
   let seq = 0;
   let loaded = null;                       // lazy: a kernel that never opens one pays nothing
+  let expectBin;                           // undefined: not yet looked for; "" when there is none
   let ctxRef = null;
   const ctxPort = () => (ctxRef ? ctxRef.port() : 0);
 
@@ -181,7 +184,17 @@ export function createPlane({ env, audit }) {
     if (scalarChr(cmd.cwd) && cmd.cwd) {
       try { if (fs.statSync(cmd.cwd).isDirectory()) wd = cmd.cwd; } catch { /* keep the kernel's cwd */ }
     }
-    const usePipe = !loaded.pty;
+    // THREE rungs: node-pty; else `expect`, which ships with macOS and runs a
+    // program on a real pty over plain pipes (host/planes/expect-term.mjs) —
+    // the packaged app, which can load no native module, gets a real terminal
+    // from it (FINDINGS 2026-09-22 B8); else the pipe. BEATRINA_TERMINAL_EXPECT=0
+    // skips the middle rung, which is how a machine with expect tests the pipe.
+    if (expectBin === undefined) {
+      expectBin = loaded.pty || process.platform === "win32" || env("BEATRINA_TERMINAL_EXPECT") === "0"
+        ? "" : whichSync("expect");
+    }
+    const useExpect = !loaded.pty && !!expectBin;
+    const usePipe = !loaded.pty && !useExpect;
     const sh = usePipe ? pipeShell(process.env) : termShell(process.env);
     const argv = usePipe ? { file: sh.cmd, args: sh.args } : termArgv(sh);
     // The shell runs in the PHYSICAL directory (processx resolves the wd for
@@ -191,16 +204,16 @@ export function createPlane({ env, audit }) {
     let real = wd;
     try { real = fs.realpathSync(wd); } catch { real = wd; }
     let term;
+    const ptyEnv = () => mirrorEnv({ ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor",
+      COLUMNS: String(cols), LINES: String(rows), BEATRINA_PORT: String(ctxPort()) });
     try {
-      term = usePipe
+      term = useExpect
+        ? expectSpawn(expectBin, argv.file, argv.args, { cols, rows, cwd: real, env: ptyEnv() })
+        : usePipe
         ? pipeSpawn(argv.file, argv.args, { cwd: real,
           env: mirrorEnv({ ...process.env, TERM: "dumb", COLUMNS: String(cols), LINES: String(rows), BEATRINA_PORT: String(ctxPort()) }) })
-        : loaded.pty.spawn(argv.file, argv.args, {
-          name: "xterm-256color", cols, rows, cwd: real,
-          // The shell sees BEATRINA_PORT and, mirrored, its older spelling (a script written before the rename).
-          env: mirrorEnv({ ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor",
-            COLUMNS: String(cols), LINES: String(rows), BEATRINA_PORT: String(ctxPort()) }),
-        });
+        // The shell sees BEATRINA_PORT and, mirrored, its older spelling (a script written before the rename).
+        : loaded.pty.spawn(argv.file, argv.args, { name: "xterm-256color", cols, rows, cwd: real, env: ptyEnv() });
     } catch (e) { return refuse(`the shell could not start: ${e.message}`); }
 
     seq += 1;
@@ -218,7 +231,8 @@ export function createPlane({ env, audit }) {
       audit("term-exit", { id, detail: String(exitCode) });
       send(rec, id, { event: "exit", code: exitCode ?? null, reason: "exited" });
     });
-    audit("term-open", { id, detail: sh.cmd, class: rec.class ?? "unknown", pty: !usePipe });
+    audit("term-open", { id, detail: sh.cmd, class: rec.class ?? "unknown", pty: !usePipe,
+      via: loaded.pty ? "node-pty" : useExpect ? "expect" : "pipe" });
     send(rec, id, { event: "open", shell: sh.cmd, pid: term.pid, cols, rows, cwd: wd, pty: !usePipe });
     if (usePipe) {
       if (loaded.error) audit("term-pipe", { id, detail: loaded.error });

package/host/quarto.mjs

@@ -0,0 +1,118 @@
+// quarto.mjs — finding Quarto, and asking it how it will run a document, from
+// Node (plans/getting_rid_of_R.md Stage 3, K4).
+//
+// Two questions, both answered by QUARTO rather than by a table kept here:
+//
+//   · WHERE IS IT? A ladder, not `which`: measured on a normal Mac with RStudio,
+//     `quarto` is not on PATH and a working 1.9.37 sits inside RStudio.app
+//     (the same finding spike/job-run.R's find_quarto() is built on, same order).
+//   · WHICH ENGINE WILL IT USE? `quarto inspect <doc>` names it — `markdown`
+//     for prose only, `knitr` for R chunks (which needs R), `jupyter` for
+//     Python. Copying Quarto's binding rules here would drift from Quarto's;
+//     asking it cannot.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { readEnv } from "./env-names.mjs";
+
+/** Where Quarto lives when nothing put it on PATH, most specific first. */
+export const QUARTO_LOCATIONS = Object.freeze([
+  "/Applications/RStudio.app/Contents/Resources/app/quarto/bin/quarto",
+  "/Applications/Positron.app/Contents/Resources/app/quarto/bin/quarto",
+  "/Applications/quarto/bin/quarto",
+  "/usr/local/bin/quarto",
+  "/opt/homebrew/bin/quarto",
+  "/opt/quarto/bin/quarto",
+  "/usr/lib/rstudio/resources/app/bin/quarto/bin/quarto",
+  "C:/Program Files/Quarto/bin/quarto.exe",
+  "C:/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe",
+]);
+
+/**
+ * The Quarto binary to use, or "" when there is none.
+ *
+ * Order: BEATRINA_QUARTO (the person's choice), QUARTO_PATH (Quarto's own
+ * variable), PATH, ~/.local/bin, then the known install locations.
+ *
+ * @param {Object} [o]
+ * @param {Record<string,string|undefined>} [o.env]
+ * @param {(p: string) => boolean} [o.exists]  injected for tests
+ * @param {string} [o.platform]
+ * @returns {string}
+ */
+export function findQuarto({ env = process.env, exists = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } }, platform = process.platform } = {}) {
+  const exe = platform === "win32" ? "quarto.exe" : "quarto";
+  const chosen = readEnv(env, "QUARTO");
+  if (chosen && exists(chosen)) return chosen;
+  if (env.QUARTO_PATH && exists(env.QUARTO_PATH)) return env.QUARTO_PATH;
+  for (const dir of String(env.PATH || "").split(path.delimiter)) {
+    if (dir && exists(path.join(dir, exe))) return path.join(dir, exe);
+  }
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const local = home ? path.join(home, ".local", "bin", exe) : "";
+  if (local && exists(local)) return local;
+  return QUARTO_LOCATIONS.find((p) => exists(p)) || "";
+}
+
+/**
+ * The engines Quarto will use for one document, as `quarto inspect` reports
+ * them: ["markdown"], ["knitr"], ["jupyter"], … — or null when it could not
+ * say (the document does not parse, Quarto is too old, the call timed out).
+ * Null is "unknown", never "none": the caller renders and lets Quarto speak.
+ *
+ * @param {string} bin     the Quarto binary
+ * @param {string} target  the document
+ * @param {{timeoutMs?: number, run?: Function}} [o]
+ * @returns {{engines: string[]|null, detail: string}}
+ */
+export function quartoEngines(bin, target, { timeoutMs = 30000, run = spawnSync } = {}) {
+  const r = run(bin, ["inspect", target], { encoding: "utf8", timeout: timeoutMs, windowsHide: true });
+  if (r.error) return { engines: null, detail: r.error.message };
+  if (r.status !== 0) return { engines: null, detail: String(r.stderr || r.stdout || "").trim().split("\n").pop() || `exit ${r.status}` };
+  try {
+    const out = JSON.parse(String(r.stdout));
+    return { engines: Array.isArray(out.engines) ? out.engines.map(String) : null, detail: "" };
+  } catch (e) {
+    return { engines: null, detail: `quarto inspect did not answer in JSON (${e.message})` };
+  }
+}
+
+/**
+ * What a document needs that this session does not have, as a sentence — or ""
+ * when nothing is missing. Only the engines Beatrina knows the runtime of are
+ * judged; anything else is Quarto's to report when it renders.
+ *
+ * @param {string[]|null} engines  from quartoEngines
+ * @param {{r: boolean}} have
+ * @returns {string}
+ */
+export function missingForRender(engines, { r }) {
+  if (!Array.isArray(engines)) return "";
+  if (engines.includes("knitr") && !r) {
+    return "This document has R chunks, which Quarto runs with knitr — that needs R, and R is not available in this session. "
+      + "Install R, or set the R chunks to `eval: false`, and render again.";
+  }
+  return "";
+}
+
+/**
+ * The folder a document declares with `beatrina-workdir:` in its front matter —
+ * the rule spike/job-run.R's document_workdir() follows, so a render from here
+ * and from R start in one folder. {path, declared}; declared "" when unsaid.
+ */
+export function documentWorkdir(file, text, { home = process.env.HOME || "" } = {}) {
+  const base = path.dirname(file);
+  const lines = String(text || "").split(/\r?\n/).slice(0, 200);
+  if ((lines[0] || "").trim() !== "---") return { path: base, declared: "" };
+  const close = lines.slice(1).findIndex((l) => ["---", "..."].includes(l.trim()));
+  if (close < 0) return { path: base, declared: "" };
+  const hit = lines.slice(1, close + 1).find((l) => /^beatrina-workdir:/.test(l));
+  if (!hit) return { path: base, declared: "" };
+  const value = hit.replace(/^beatrina-workdir:/, "").replace(/[ \t]+#.*$/, "").trim().replace(/^["']|["']$/g, "");
+  if (!value) return { path: base, declared: "" };
+  const absolute = /^(\/|~|[A-Za-z]:[\\/]|\\\\)/.test(value);
+  const expanded = value.startsWith("~") ? path.join(home, value.slice(1)) : value;
+  return { path: absolute ? expanded : path.resolve(base, value), declared: value };
+}