beatrina 0.8.7 → 0.9.43

package/beatrina_V0.9.43.html.inputs.json

@@ -0,0 +1 @@
+{"schema":1,"sources":"846c329ab149b159e5984bb6bcbf336828381df44094a015a69f5a4b2da526bb","artifact":"23fedd72d63de1b612b4760addaa827f88d84ccb35909a947ae0ade8c29d2ec0"}

package/bin/beatrina.mjs

@@ -7,9 +7,12 @@
 // (asked once, installed from CRAN into the user's own library on yes).
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { fileURLToPath } from "node:url";
 import { USAGE, ask, installRPackages, missingRPackages, parseArgs, REQUIRED_R_PACKAGES } from "./cli.mjs";
+import { setupManagedPython } from "./python-setup.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
@@ -25,11 +28,26 @@ if (major < 22) fail(`Beatrina needs Node.js 22 or newer; this is ${process.vers
 
 const { APP_ID, describeMigration, migrateAppData } = await import("./identity.mjs");
 
+/**
+ * The kept notebook pages (pages.mjs): drop the versions no live session runs, other than this
+ * one. `rows` are `listSessions()`'s; a live row that cannot say its build keeps everything.
+ */
+async function pruneKeptPages(rows) {
+  const { pagesDir, prunePages, versionsInUse } = await import("./pages.mjs");
+  const { rUserDir } = await import("../host/user-dirs.mjs");
+  const keep = versionsInUse(rows);
+  if (!keep) return [];
+  return prunePages({ dir: pagesDir(process.env.BEATRIX_APP_ID || APP_ID, rUserDir), installed: pkg.version, keep });
+}
+
 if (args.command === "status" || args.command === "stop") {
   const { chooseToStop, formatSessions, listSessions, stopSession } = await import("./sessions.mjs");
   const rows = await listSessions();
   if (args.command === "status") {
-    for (const line of formatSessions(rows)) console.log(line);
+    // --json: the rows as listSessions returns them, one array — what the menu and a script read;
+    // the table is for a person.
+    if (args.json) console.log(JSON.stringify(rows));
+    else for (const line of formatSessions(rows)) console.log(line);
     process.exit(0);
   }
   const chosen = chooseToStop(rows, { port: args.port, all: args.all });
@@ -42,9 +60,38 @@ if (args.command === "status" || args.command === "stop") {
       "removed-stale": `Removed the record of a session on port ${row.port} that was no longer running.`, failed: `Could not stop the session on port ${row.port}: ${done.detail}` }[done.outcome];
     if (done.outcome === "failed") { failed += 1; console.error(said); } else console.log(said);
   }
+  // The pages kept for the sessions that just stopped are not needed any more (pages.mjs).
+  await pruneKeptPages(await listSessions());
   process.exit(failed ? 1 : 0);
 }
 
+if (args.command === "knit") {
+  // The report is the page's — knitFile() builds the same cells the window
+  // would and calls the same knitDocument(), so a knit from the terminal and
+  // a knit from the menu are the same file.
+  // Installed, the knitter is one bundled file beside the acceptance check
+  // (tools/npm/build-npm.mjs); in a checkout it is its own source tree. Trying
+  // the staged path FIRST means the published package never depends on a
+  // `tools/` directory it does not ship — `beatrina knit` was unusable from an
+  // npm install until 2026-09-18 for exactly that reason.
+  const staged = path.join(root, "kernel", "check", "knit-file.mjs");
+  const { knitFile } = await import(
+    fs.existsSync(staged) ? pathToFileURL(staged).href : "../../tools/beatrina/knit-file.mjs");
+  try {
+    const r = await knitFile(args.file, {
+      run: args.run, echo: args.echo, out: args.out, width: args.width, port: args.port,
+      rebuild: args.rebuild, code: args.code, toc: args.toc, numberSections: args.numberSections, rows: args.rows,
+      say: (line) => console.log(line),
+    });
+    // The last line is the file, alone, so `open "$(beatrina knit x.qmd | tail -1)"` works.
+    console.log(r.out);
+    process.exit(r.failed ? 1 : 0);
+  } catch (e) {
+    console.error(`beatrina knit: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 if (args.command === "upgrade") {
   // The explicit door (upgrade.mjs): npm's work, so R is not needed for it.
   const { runUpgrade } = await import("./upgrade.mjs");
@@ -53,8 +100,18 @@ if (args.command === "upgrade") {
 }
 
 const { detectRscript } = await import("../host/engine-r.mjs");
-const { detectPython } = await import("../host/engine-python.mjs");
-const rscript = detectRscript(process.env.CARMAR_RSCRIPT || "");
+const { detectPython, pythonCandidates } = await import("../host/engine-python.mjs");
+
+if (args.command === "python") {
+  // `beatrina python setup` (python-setup.mjs): the interpreter discovery looks for first. R is not needed.
+  const os = await import("node:os");
+  const done = await setupManagedPython({ home: os.homedir(), env: process.env, platform: process.platform,
+    candidates: pythonCandidates(process.env), minimal: Boolean(args.minimal), log: (line) => console.log(line) });
+  if (!done.ok) fail(done.refusal);
+  process.exit(0);
+}
+
+const rscript = detectRscript(process.env.BEATRINA_RSCRIPT || "");
 
 if (args.command === "doctor") {
   const rows = [["Beatrina", `${pkg.version} (${root})`], ["Node.js", `${process.version} at ${process.execPath}`]];
@@ -76,9 +133,28 @@ if (args.command === "doctor") {
     try { missing = missingRPackages(rscript); } catch (e) { missing = [`(${e.message})`]; }
     rows.push(["R packages", missing.length ? `missing: ${missing.join(", ")} — run beatrina, which offers to install them` : `${REQUIRED_R_PACKAGES.join(", ")}: installed`]);
   }
+  // detectPython, the same ladder the host runs, so doctor and the session agree; the row says
+  // which rung chose the interpreter, or what to run when none has ipykernel.
   const py = await detectPython(process.env);
-  rows.push(["Python (optional)", py.available ? `${py.version} at ${py.path}` : py.detail]);
-  let pty = "not installed — the terminal pane runs line programs only";
+  rows.push(["Python (optional)", py.available ? `${py.version} at ${py.path} (${py.why})`
+    : `none with ipykernel — run \`beatrina python setup\`. ${py.detail}`]);
+  {
+    // What is running, on which version, and the doors out of a session that predates the installed
+    // files — from the one discovery `status` and `stop` read (sessions.mjs). Before node-pty: the
+    // npm-cli suite reads the LAST line for that row.
+    const { listSessions } = await import("./sessions.mjs");
+    const { sessionsRow } = await import("./doctor-rows.mjs");
+    rows.push(["Sessions", sessionsRow(await listSessions(), pkg.version)]);
+  }
+  if (process.platform === "darwin") {
+    // What Finder does with a .qmd, .Rmd, .carmd, and which Beatrina.app copies Launch Services
+    // knows — asked of Launch Services itself (finder.mjs); "not checked" without a Swift toolchain.
+    const { finderRows, lsQuery } = await import("./finder.mjs");
+    const { BUNDLE_ID, DOC_TYPES } = await import("./shortcut.mjs");
+    const exts = DOC_TYPES.map((t) => t.ext);
+    for (const row of finderRows(lsQuery({ exts, bundleIds: [BUNDLE_ID] }), { bundleId: BUNDLE_ID, exts })) rows.push(row);
+  }
+  let pty ="not installed — the terminal pane runs line programs only";
   try { await import("node-pty"); pty = "installed — full terminal"; } catch { /* optional */ }
   rows.push(["node-pty (optional)", pty]);
   const width = Math.max(...rows.map((r) => r[0].length));
@@ -95,8 +171,8 @@ if (args.command === "check") {
   // BEATRINA_CHECK_JUNIT keeps the report where the caller wants it (fordist/beatrina-windows-check.ps1).
   const junit = process.env.BEATRINA_CHECK_JUNIT || path.join(scratch, "acceptance.xml");
   const code = await new Promise((resolve) => {
-    const child = spawn(process.execPath, [path.join(root, "check", "acceptance.mjs"), `--host=${path.join(root, "host", "main.mjs")}`, `--junit=${junit}`],
-      { stdio: "inherit", env: { ...process.env, CARMAR_RSCRIPT: rscript } });
+    const child = spawn(process.execPath, [path.join(root, "kernel", "check", "acceptance.mjs"), `--host=${path.join(root, "host", "main.mjs")}`, `--junit=${junit}`],
+      { stdio: "inherit", env: { ...process.env, BEATRINA_RSCRIPT: rscript } });
     child.on("exit", (c) => resolve(c ?? 1));
     child.on("error", () => resolve(1));
   });
@@ -116,9 +192,12 @@ if (args.command === "check") {
 }
 
 if (args.command === "shortcut") {
-  const { makeShortcut } = await import("./shortcut.mjs");
+  const { makeShortcut, removeMenu } = await import("./shortcut.mjs");
   try {
-    const made = makeShortcut({ cli: fileURLToPath(import.meta.url), dir: args.dir, port: args.port, makeDefault: args.makeDefault, noOpen: !args.open });
+    // --no-menu removes the menu-bar item and its login agent, and nothing else.
+    const made = args.noMenu ? removeMenu({ dir: args.dir })
+      : makeShortcut({ cli: fileURLToPath(import.meta.url), dir: args.dir, port: args.port, makeDefault: args.makeDefault, noOpen: !args.open,
+        menu: args.menu, login: args.login, menuSource: path.join(root, "menu", "Beatrina Menu.app") });
     for (const line of made.said) console.log(line);
     process.exit(0);
   } catch (e) { fail(`the shortcut could not be made: ${e.message}`); }
@@ -131,12 +210,16 @@ if (args.fromApp) {
   const { liveSession } = await import("./shortcut.mjs");
   const { spawn, spawnSync } = await import("node:child_process");
   const alert = (msg) => {
-    if (process.platform === "darwin") spawnSync("osascript", ["-e", `display alert "Beatrina" message ${JSON.stringify(msg)}`]);
+    // BEATRINA_NO_ALERT: the suites, where a modal dialog would block the run.
+    if (process.env.BEATRINA_NO_ALERT === "1") console.error(`beatrina: ${msg}`);
+    else if (process.platform === "darwin") spawnSync("osascript", ["-e", `display alert "Beatrina" message ${JSON.stringify(msg)}`]);
     else if (process.platform === "win32") spawnSync("powershell.exe", ["-NoProfile", "-Command", `Add-Type -AssemblyName PresentationFramework; [System.Windows.MessageBox]::Show(${JSON.stringify(msg).replace(/^"|"$/g, "'")}, 'Beatrina')`]);
     else console.error(msg);
   };
   const file = args.file ? path.resolve(args.file) : "";
-  const live = await liveSession({ app: process.env.BEATRIX_APP_ID || APP_ID, port: args.port });
+  // --new (the menu's New Session, launch.sh's --new): another session even when one is running —
+  // the background start below, with no look for a live one.
+  const live = args.new ? null : await liveSession({ app: process.env.BEATRIX_APP_ID || APP_ID, port: args.port });
   if (live) {
     let delivered = "none";
     if (file) {
@@ -150,22 +233,51 @@ if (args.fromApp) {
     if (delivered !== "page" && args.open && live.url) {
       // The page the session SERVES (http://127.0.0.1:<port>/), never the file: macOS `open` drops a
       // file URL's #kernel=…&pair=… fragment and the page then cannot find its kernel. The served
-      // origin needs no pairing. BEATRINA_OPENER substitutes the program (test/beatrina-sessions.test.mjs).
-      const opener = process.env.BEATRINA_OPENER ? [process.env.BEATRINA_OPENER, [live.url]]
-        : process.platform === "darwin" ? ["open", [live.url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", live.url]] : ["xdg-open", [live.url]];
-      spawnSync(opener[0], opener[1]);
+      // origin needs no pairing (browser.mjs; BEATRINA_OPENER substitutes the program in the suites).
+      const { openUrl } = await import("./browser.mjs");
+      openUrl(live.url);
     }
     if (delivered === "refused") alert(`The running Beatrina session could not open ${file}.`);
     process.exit(0);
   }
   if (!rscript) { alert("Beatrina needs R. Install R from https://cran.r-project.org, then open Beatrina again."); process.exit(1); }
+  // The session starts DETACHED (it must outlive this process), but this
+  // process no longer exits the moment it has spawned it: it waits, bounded,
+  // for the session's own announcement, and a child that dies first is SAID
+  // with the tail of its log (hardening.md 2). Until 0.9.6 stdio was "ignore"
+  // and the exit was immediate, so a missing package, a refused port or a
+  // host that crashed at start ended in success and an empty screen.
+  const logPath = path.join(os.tmpdir(), `beatrina-from-app-${process.pid}.log`);
+  let logFd = "ignore";
+  try { logFd = fs.openSync(logPath, "a"); } catch { logFd = "ignore"; }
+  const readLog = () => { try { return fs.readFileSync(logPath, "utf8"); } catch { return ""; } };
   const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...(file ? [file] : []), "--yes",
-    ...(args.port ? ["--port", args.port] : []), ...(args.open ? [] : ["--no-open"])], { detached: true, stdio: "ignore", windowsHide: true });
+    ...(args.port ? ["--port", args.port] : []), ...(args.open ? [] : ["--no-open"])],
+    { detached: true, stdio: ["ignore", logFd, logFd], windowsHide: true });
+  if (typeof logFd === "number") fs.closeSync(logFd);
+  let spawnError = null;
+  child.on("error", (e) => { spawnError = e; });
   child.unref();
-  process.exit(0);
+  // Under the menu helper's own 180 s limit, so the helper hears THIS answer.
+  const waitS = Number(process.env.BEATRINA_FROM_APP_DEADLINE || 150);
+  const until = Date.now() + (Number.isFinite(waitS) && waitS > 0 ? waitS : 150) * 1000;
+  const tail = () => readLog().trim().split("\n").filter((l) => !/"url"\s*:/.test(l)).slice(-5).join("\n");
+  while (Date.now() < until) {
+    const url = /"url"\s*:\s*"([^"]*)"/.exec(readLog());
+    if (url) { console.log(JSON.stringify({ url: url[1], pid: child.pid, log: logPath })); process.exit(0); }
+    if (spawnError) { alert(`Beatrina could not start a session: ${spawnError.message}`); process.exit(1); }
+    if (child.exitCode !== null || child.signalCode !== null) {
+      const said = tail();
+      alert(`Beatrina could not start a session (${child.signalCode || `exit ${child.exitCode}`}).${said ? `\n\n${said}` : ""}\n\nThe log is at ${logPath}`);
+      process.exit(1);
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  alert(`Beatrina is still starting after ${Math.round(waitS)} seconds. It may yet open; the log is at ${logPath}`);
+  process.exit(1);
 }
 
-if (!rscript) fail("Beatrina needs R and none was found. Install R from https://cran.r-project.org, or set CARMAR_RSCRIPT to your Rscript.");
+if (!rscript) fail("Beatrina needs R and none was found. Install R from https://cran.r-project.org, or set BEATRINA_RSCRIPT to your Rscript.");
 let missing;
 try { missing = missingRPackages(rscript); } catch (e) { fail(e.message); }
 if (missing.length) {
@@ -178,18 +290,30 @@ if (missing.length) {
 
 // Beatrina's own data folders and port, unless the caller chose otherwise. Data a Beatrix build
 // left under R/beatrix moves across once (identity.mjs).
+const { rUserDir } = await import("../host/user-dirs.mjs");
 if (!process.env.BEATRIX_APP_ID) {
   process.env.BEATRIX_APP_ID = APP_ID;
-  const { rUserDir } = await import("../host/user-dirs.mjs");
   for (const line of describeMigration(migrateAppData({ dirOf: rUserDir }))) console.error(`beatrina: ${line}`);
 }
-process.env.CARMAR_RSCRIPT = rscript;
-if (args.port) process.env.CARMAR_PORT = args.port;
-else process.env.CARMAR_PORT ||= "4848";
+// The page this session will serve, kept once per version under the app's cache, where the host
+// reads it as its third location (pages.mjs): `npm install -g beatrina@<next>` replaces the package
+// folder wholesale, and without the copy a session still running the old version answers GET /
+// with the development index. Then the pages of versions nobody runs any more are dropped.
+{
+  const { keepPage, pageName, pagesDir } = await import("./pages.mjs");
+  const dir = pagesDir(process.env.BEATRIX_APP_ID, rUserDir);
+  const kept = keepPage({ from: path.join(root, pageName(pkg.version)), dir });
+  if (kept.outcome === "failed") console.error(`beatrina: the notebook page could not be kept under ${dir} (${kept.detail}); upgrading while this session runs will take its page until it restarts.`);
+  const { listSessions } = await import("./sessions.mjs");
+  await pruneKeptPages(await listSessions());
+}
+process.env.BEATRINA_RSCRIPT = rscript;
+if (args.port) process.env.BEATRINA_PORT = args.port;
+else process.env.BEATRINA_PORT ||= "4848";
 if (args.file) {
   const file = path.resolve(args.file);
   if (!fs.existsSync(file)) fail(`no such file: ${file}`);
-  process.env.CARMAR_OPEN_FILE = file;
+  process.env.BEATRINA_OPEN_FILE = file;
 }
 const open = args.open && process.env.BEATRIX_NO_OPEN !== "1";
 // Once a day: is a newer Beatrina on the registry? Said, never acted on, and never waited for.
@@ -218,8 +342,12 @@ else {
   }
   let staged;
   try { staged = stageFailsafe(root); } catch (e) { fail(`Beatrina could not start: ${started.reason}, and ${e.message}.`); }
-  started = await runUntilAnnounced({ cmd: rscript, args: [staged.serve, ...(open ? ["--open"] : [])],
+  // No `--open` for serve.R: its own open is `browseURL` on the FILE URL, whose #kernel=…&pair=…
+  // fragment macOS `open` drops (the page then says "needs R"). The command opens the served origin
+  // itself once the supervisor has announced it — exactly what the host path opens (browser.mjs).
+  started = await runUntilAnnounced({ cmd: rscript, args: [staged.serve],
     env: { ...process.env, BEATRINA_FAILSAFE_REASON: started.reason }, deadlineMs: 120000 });
   if (!started.announced) fail(`the failsafe did not start either: ${started.reason.replace("the Node host", "the R supervisor")}.`);
+  if (open && started.url) { const { openUrl } = await import("./browser.mjs"); openUrl(started.url); }
   followChild(started.child, { onExit: (code) => { fs.rmSync(staged.stage, { recursive: true, force: true }); process.exit(code); } });
 }

package/bin/browser.mjs

@@ -0,0 +1,31 @@
+// browser.mjs — open a URL in the person's browser, from the command (docs/launch-menu-plan.md L3).
+//
+// ONE platform switch for everything the `beatrina` command opens itself: `--from-app` reopening a
+// running session's page, and the failsafe once the R supervisor has announced. The host keeps its
+// own `--open*` handling (the dev door, the handoff, Beatrina's launchers); this is the command's.
+//
+// What is opened is always the page a session SERVES (http://127.0.0.1:<port>/), never a file URL:
+// macOS `open` drops a file URL's #kernel=…&pair=… fragment and the page then cannot find its kernel
+// (LEARNINGS 2026-09-16). BEATRINA_OPENER substitutes the program (the suites), and its older
+// spelling — the host's seam before the rename — is honoured too, so a test that sets either sees
+// the same thing open.
+
+import { spawnSync } from "node:child_process";
+
+/** The program and arguments that open `url` on this platform, or through the seam. */
+export function openerFor(url, { env = process.env, platform = process.platform } = {}) {
+  const seam = env.BEATRINA_OPENER || env.CARMAR_OPENER || "";   // beatrina-names: keep
+  if (seam) return [seam, [url]];
+  return platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+}
+
+/**
+ * Open `url`. Nothing is waited for beyond the opener handing the URL over; a desktop with no
+ * opener is not an error (the URL was printed by the announce line).
+ * @returns {{cmd: string, args: string[], ok: boolean}}
+ */
+export function openUrl(url, { env = process.env, platform = process.platform, spawnImpl = spawnSync } = {}) {
+  const [cmd, args] = openerFor(url, { env, platform });
+  const r = spawnImpl(cmd, args, { stdio: "ignore" }) || {};
+  return { cmd, args, ok: !r.error && (r.status == null || r.status === 0) };
+}

package/bin/cli.mjs

@@ -9,40 +9,81 @@ export const REQUIRED_R_PACKAGES = Object.freeze(["jsonlite", "knitr", "evaluate
 export const USAGE = `beatrina — R, Python and JavaScript notebooks on your own computer
 
   beatrina [file]     start a session and open the notebook (Ctrl+C stops it)
-  beatrina status     list running sessions: port, process, uptime, document
+  beatrina status     list running sessions: port, process, uptime, document (--json for scripts and the menu)
   beatrina stop       stop the running session (--port <n> for one of several, --all for every one)
   beatrina doctor     show what Beatrina found: Node, R, R packages, Python, and whether npm has a newer Beatrina
+  beatrina python setup
+                      create the Python interpreter Beatrina manages (~/.beatrina/python: a virtual
+                      environment with ipykernel, pandas and matplotlib; --minimal installs ipykernel only)
   beatrina check      run the acceptance check on this machine (a private session on a spare port);
                       --prova <url> --token <t> (or PROVA_URL / PROVA_TOKEN) sends the results to Prova
   beatrina shortcut   add a Beatrina icon, and "Open With ▸ Beatrina" for .qmd and .Rmd files
-                      (--default also makes it the default app for them)
+                      (--default also makes it the default app for them; safe to run again — it repairs
+                      a second registered copy). On macOS, --menu also installs the Beatrina menu-bar
+                      item (--login: at every login too); --no-menu removes it
+  beatrina knit <file>
+                      knit a .qmd/.Rmd/.md to one self-contained HTML file, without opening a window:
+                      every chunk runs in a private session first (--no-run keeps the code and says in
+                      the file that the results are missing), --no-echo writes a results-only report,
+                      --width standard|wide|full (or a CSS length) sets the report page width,
+                      --code chunk|show|fold|hide how code appears (chunk: each chunk's echo decides),
+                      --toc / --no-toc, --number-sections, --rows 50|200|all rows per table,
+                      --rebuild re-runs cached chunks and refreshes knitr's cache (shared with the
+                      window: a chunk cached there is restored here), --out <file.html> chooses where
+                      it goes. One line per chunk: ✓ ran, ↺ cached, ✗ failed, then what it wrote
   beatrina upgrade    install the newest Beatrina from npm (npm install -g beatrina@latest);
                       a session already running keeps this version until it restarts
 
   --port <n>          port for the session (default 4848)
   --no-open           do not open a browser
   --yes               install missing R packages without asking
+  --from-app [file]   what the icon, a double-clicked document and the menu run: hand the file to the
+                      running session, or start one in the background (--new: start another regardless)
   --version, --help`;
 
-export const COMMANDS = Object.freeze(["doctor", "shortcut", "status", "stop", "check", "upgrade"]);
+export const COMMANDS = Object.freeze(["doctor", "shortcut", "status", "stop", "check", "upgrade", "python", "knit"]);
+/** What `beatrina python` can be asked to do. */
+export const PYTHON_VERBS = Object.freeze(["setup"]);
 
 /** Parse the command line. */
 export function parseArgs(argv) {
-  const out = { command: "run", file: "", port: "", open: true, yes: false, help: false, version: false, fromApp: false, makeDefault: false, dir: "", all: false, prova: "", token: "" };
+  const out = { command: "run", file: "", port: "", open: true, yes: false, help: false, version: false, fromApp: false, makeDefault: false, dir: "", all: false, prova: "", token: "", json: false, new: false, menu: false, noMenu: false, login: false, run: true, echo: true, out: "", width: "" };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--version" || a === "-v") out.version = true;
     else if (a === "--no-open") out.open = false;
+    else if (a === "--no-run") out.run = false;
+    else if (a === "--no-echo") out.echo = false;
+    else if (a === "--out") out.out = argv[++i] || "";
+    else if (a === "--width") out.width = argv[++i] || "";
+    else if (a.startsWith("--out=")) out.out = a.slice(6);
+    // The knit vocabulary (lib/knit.js KNIT_CODE …), set only when given so
+    // the document's own front matter decides otherwise.
+    else if (a === "--rebuild") out.rebuild = true;
+    else if (a === "--code" || a.startsWith("--code=")) out.code = a === "--code" ? argv[++i] || "" : a.slice(7);
+    else if (a === "--toc") out.toc = true;
+    else if (a === "--no-toc") out.toc = false;
+    else if (a === "--number-sections") out.numberSections = true;
+    else if (a === "--rows" || a.startsWith("--rows=")) out.rows = a === "--rows" ? argv[++i] || "" : a.slice(7);
     else if (a === "--yes" || a === "-y") out.yes = true;
     else if (a === "--port") out.port = argv[++i] || "";
     else if (a.startsWith("--port=")) out.port = a.slice(7);
     else if (COMMANDS.includes(a) && out.command === "run" && !out.file) out.command = a;
+    // `beatrina python <verb>`: the verb and its one option are set only when
+    // given, so the shape of every other command's result is unchanged.
+    else if (out.command === "python" && !out.verb && PYTHON_VERBS.includes(a)) out.verb = a;
+    else if (a === "--minimal") out.minimal = true;
     else if (a === "--all") out.all = true;
     else if (a === "--prova") out.prova = argv[++i] || "";
     else if (a === "--token") out.token = argv[++i] || "";
     else if (a === "--from-app") out.fromApp = true;
+    else if (a === "--new") out.new = true;
+    else if (a === "--json") out.json = true;
     else if (a === "--default") out.makeDefault = true;
+    else if (a === "--menu") out.menu = true;
+    else if (a === "--no-menu") out.noMenu = true;
+    else if (a === "--login") out.login = true;
     else if (a === "--dir") out.dir = argv[++i] || "";
     else if (a.startsWith("-")) throw new Error(`unknown option ${a}\n\n${USAGE}`);
     else if (!out.file) out.file = a;
@@ -50,8 +91,26 @@ export function parseArgs(argv) {
   }
   if (out.port && !/^\d{2,5}$/.test(out.port)) throw new Error(`--port must be a number, not ${JSON.stringify(out.port)}`);
   if (out.all && out.command !== "stop") throw new Error(`--all belongs to beatrina stop\n\n${USAGE}`);
+  if (out.json && out.command !== "status") throw new Error(`--json belongs to beatrina status\n\n${USAGE}`);
+  if (out.new && !out.fromApp) throw new Error(`--new belongs to beatrina --from-app\n\n${USAGE}`);
+  if ((out.menu || out.noMenu || out.login) && out.command !== "shortcut") throw new Error(`--menu, --no-menu and --login belong to beatrina shortcut\n\n${USAGE}`);
+  if (out.menu && out.noMenu) throw new Error(`--menu and --no-menu are opposites; give one\n\n${USAGE}`);
+  if (out.login && !out.menu) throw new Error(`--login goes with --menu\n\n${USAGE}`);
   if ((out.prova || out.token) && out.command !== "check") throw new Error(`--prova and --token belong to beatrina check\n\n${USAGE}`);
-  if (out.file && (out.command === "status" || out.command === "stop" || out.command === "check" || out.command === "upgrade")) throw new Error(`beatrina ${out.command} takes no file\n\n${USAGE}`);
+  if (out.command === "knit" && !out.file) throw new Error(`beatrina knit takes the document to knit\n\n${USAGE}`);
+  const knitFlags = out.out || out.width || out.run === false || out.echo === false || out.rebuild
+    || out.code !== undefined || out.toc !== undefined || out.numberSections || out.rows !== undefined;
+  if (knitFlags && out.command !== "knit") throw new Error(`--out, --width, --no-run, --no-echo, --code, --toc, --number-sections, --rows and --rebuild belong to beatrina knit\n\n${USAGE}`);
+  if (out.code !== undefined && !["chunk", "show", "fold", "hide"].includes(out.code)) throw new Error(`--code is one of chunk, show, fold, hide — not ${JSON.stringify(out.code)}`);
+  if (out.rows !== undefined) {
+    if (out.rows === "all") out.rows = 0;
+    else if (/^\d+$/.test(String(out.rows)) && Number(out.rows) > 0) out.rows = Number(out.rows);
+    else throw new Error(`--rows is a positive number or "all", not ${JSON.stringify(out.rows)}`);
+  }
+  if (out.rebuild && out.run === false) throw new Error("--rebuild runs the chunks; it cannot go with --no-run");
+  if (out.command === "python" && !out.verb) throw new Error(`beatrina python takes a verb: ${PYTHON_VERBS.join(", ")}\n\n${USAGE}`);
+  if (out.file && (out.command === "status" || out.command === "stop" || out.command === "check" || out.command === "upgrade" || out.command === "python")) throw new Error(`beatrina ${out.command} takes no file\n\n${USAGE}`);
+  if (out.minimal && !(out.command === "python" && out.verb === "setup")) throw new Error(`--minimal belongs to beatrina python setup\n\n${USAGE}`);
   return out;
 }
 

package/bin/doctor-rows.mjs

@@ -0,0 +1,31 @@
+// doctor-rows.mjs — the rows `beatrina doctor` builds from what other doors already know: pure
+// functions over `listSessions()`' rows, so the sentences are pinned without a session
+// (docs/launch-menu-plan.md L5).
+
+import { compareVersions } from "./update-check.mjs";
+
+/**
+ * The Sessions row: what is running, on which version, and — when a session predates the installed
+ * files — the two doors out of it. Left-behind records are counted with the command that removes them.
+ *
+ *   none
+ *   1 running — port 4848, 0.8.7 (installed 0.8.8: Session ▾ ▸ Restart into 0.8.8, or beatrina stop then beatrina)
+ *   2 running — port 4848, 0.8.8; port 4849, 0.8.8; 1 left-behind record (beatrina stop removes it)
+ */
+export function sessionsRow(rows, installed) {
+  const live = rows.filter((r) => r.live);
+  const stale = rows.filter((r) => !r.live);
+  if (!rows.length) return "none";
+  const parts = [];
+  if (live.length) {
+    const each = live.map((r) => {
+      const build = r.kernel_build || "?";
+      const behind = Boolean(r.kernel_build && installed && r.kernel_build !== installed && compareVersions(installed, r.kernel_build) > 0);
+      const stop = live.length > 1 ? `beatrina stop --port ${r.port}` : "beatrina stop";
+      return `port ${r.port}, ${build}${behind ? ` (installed ${installed}: Session ▾ ▸ Restart into ${installed}, or ${stop} then beatrina)` : ""}`;
+    });
+    parts.push(`${live.length} running — ${each.join("; ")}`);
+  } else parts.push("none running");
+  if (stale.length) parts.push(`${stale.length} left-behind record${stale.length === 1 ? "" : "s"} (beatrina stop removes ${stale.length === 1 ? "it" : "them"})`);
+  return parts.join("; ");
+}

package/bin/failsafe.mjs

@@ -31,7 +31,8 @@ export function exitReason(code, signal, stderrTail) {
 
 /**
  * Run a supervisor child, mirroring its output, until it announces its URL, exits, or misses the deadline.
- * @returns {Promise<{announced: true, child: import("node:child_process").ChildProcess} | {announced: false, refused: boolean, reason: string, code: number|null}>}
+ * `url` is the announced one (the served origin), read from the line, for the caller that opens it.
+ * @returns {Promise<{announced: true, child: import("node:child_process").ChildProcess, url: string} | {announced: false, refused: boolean, reason: string, code: number|null}>}
  */
 export function runUntilAnnounced({ cmd, args, env, deadlineMs, spawnImpl = spawn, out = process.stdout, err = process.stderr }) {
   return new Promise((resolve) => {
@@ -42,7 +43,11 @@ export function runUntilAnnounced({ cmd, args, env, deadlineMs, spawnImpl = spaw
     const settle = (value) => { if (!settled) { settled = true; clearTimeout(timer); resolve(value); } };
     child.stdout.on("data", (d) => {
       out.write(d);
-      if (!settled) { stdout += d; if (/"url"\s*:/.test(stdout)) settle({ announced: true, child }); }
+      if (!settled) {
+        stdout += d;
+        const m = /"url"\s*:\s*"([^"]*)"/.exec(stdout);
+        if (m) settle({ announced: true, child, url: m[1] });
+      }
     });
     child.stderr.on("data", (d) => { err.write(d); if (!settled) stderr = (stderr + d).slice(-8000); });
     child.on("error", (e) => settle({ announced: false, refused: false, reason: `the Node host could not be started (${e.message})`, code: null }));
@@ -62,7 +67,7 @@ export function stageFailsafe(root, scratchParent = os.tmpdir()) {
   const stage = fs.mkdtempSync(path.join(scratchParent, "beatrina-failsafe-"));
   fs.cpSync(path.join(root, "kernel"), path.join(stage, "kernel"), { recursive: true });
   for (const f of fs.readdirSync(failsafe)) fs.copyFileSync(path.join(failsafe, f), path.join(stage, "kernel", f));
-  for (const page of fs.readdirSync(root).filter((f) => /^carmar_V.*\.html$/.test(f))) fs.copyFileSync(path.join(root, page), path.join(stage, page));
+  for (const page of fs.readdirSync(root).filter((f) => /^beatrina_V.*\.html$/.test(f))) fs.copyFileSync(path.join(root, page), path.join(stage, page));
   return { stage, serve: path.join(stage, "kernel", "serve.R") };
 }
 

package/bin/finder.mjs

@@ -0,0 +1,74 @@
+// finder.mjs — what Finder does with a .qmd, read from Launch Services (docs/launch-menu-plan.md F2).
+//
+// `lsquery.swift` beside this file is the read: extension → UTI → default handler → every handler,
+// and bundle id → every registered path. It runs through the Swift toolchain when one answers
+// `xcrun --find swift`; without one the rows say so rather than guess. `finderRows` is pure over the
+// script's lines, so the sentences are pinned with canned answers (test/beatrina-doctor-ls.test.mjs).
+// Nothing here changes a registration or a default: `beatrina shortcut` does, and reads this back.
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const QUERY = path.join(path.dirname(fileURLToPath(import.meta.url)), "lsquery.swift");
+export const NO_TOOLCHAIN = "not checked (no Swift toolchain — install the Xcode Command Line Tools: xcode-select --install)";
+
+/** The swift that runs the query, or "" (not macOS, or no toolchain). */
+export function swiftToolchain({ platform = process.platform, spawnImpl = spawnSync } = {}) {
+  if (platform !== "darwin") return "";
+  const r = spawnImpl("xcrun", ["--find", "swift"], { encoding: "utf8", timeout: 20000 });
+  const found = r && r.status === 0 ? String(r.stdout).trim() : "";
+  return found && fs.existsSync(found) ? found : "";
+}
+
+/**
+ * The query's lines, parsed.
+ * @returns {{ext: {ext: string, uti: string, handler: string, name: string, handlers: string[]}[], bundle: {id: string, paths: string[]}[]}}
+ */
+export function parseQuery(text) {
+  const out = { ext: [], bundle: [] };
+  for (const line of String(text).split("\n")) {
+    const f = line.split("\t");
+    if (f[0] === "ext" && f.length >= 6) out.ext.push({ ext: f[1], uti: f[2], handler: f[3], name: f[4], handlers: f[5] ? f[5].split(",").filter(Boolean) : [] });
+    else if (f[0] === "bundle" && f.length >= 2) out.bundle.push({ id: f[1], paths: f.slice(2).filter(Boolean) });
+  }
+  return out;
+}
+
+/** Ask Launch Services. Null when there is no toolchain or the query did not answer (the caller says so). */
+export function lsQuery({ exts = [], bundleIds = [], swift = swiftToolchain(), spawnImpl = spawnSync } = {}) {
+  if (!swift) return null;
+  const args = [QUERY, ...(exts.length ? ["ext", ...exts] : []), ...(bundleIds.length ? ["bundle", ...bundleIds] : [])];
+  const r = spawnImpl(swift, args, { encoding: "utf8", timeout: 90000 });
+  if (!r || r.status !== 0) return null;
+  return parseQuery(r.stdout);
+}
+
+/** The registered paths of a bundle id in an answer. */
+export const registeredPaths = (answer, bundleId) => (answer && answer.bundle.find((b) => b.id === bundleId) || { paths: [] }).paths;
+
+/** The extensions of `exts` whose default handler is `bundleId`, in an answer. */
+export const defaultFor = (answer, bundleId, exts) => (answer ? exts.filter((e) => answer.ext.find((x) => x.ext === e)?.handler === bundleId) : []);
+
+/**
+ * The doctor's Finder rows: one per extension (which app opens it, and the door when it is not this
+ * one), then the app's registered copies (one path, or the copies to repair with `beatrina shortcut`).
+ * @returns {[string, string][]}
+ */
+export function finderRows(answer, { bundleId, exts, appName = "Beatrina" }) {
+  if (!answer) return [...exts.map((e) => [`Finder opens .${e}`, NO_TOOLCHAIN]), [`${appName}.app`, NO_TOOLCHAIN]];
+  const rows = exts.map((e) => {
+    const row = answer.ext.find((x) => x.ext === e);
+    const label = `Finder opens .${e}`;
+    if (!row || !row.uti) return [label, `no type is registered for .${e} — run: beatrina shortcut`];
+    if (row.handler === bundleId) return [label, appName];
+    if (!row.handler) return [label, "no default app — run: beatrina shortcut --default"];
+    return [label, `${row.name || row.handler} — run: beatrina shortcut --default`];
+  });
+  const copies = registeredPaths(answer, bundleId);
+  rows.push([`${appName}.app`, !copies.length ? "not registered — run: beatrina shortcut"
+    : copies.length === 1 ? copies[0]
+      : `${copies.length} copies registered: ${copies.join(", ")} — run: beatrina shortcut`]);
+  return rows;
+}

package/bin/lsquery.swift

@@ -0,0 +1,55 @@
+// lsquery.swift — ask Launch Services, read-only (docs/launch-menu-plan.md F2).
+//
+//   swift lsquery.swift ext qmd Rmd carmd bundle me.saqr.beatrina
+//
+// One tab-separated line per question:
+//   ext     <ext>  <uti>  <default handler bundle id>  <that app's name>  <every handler, comma-separated>
+//   bundle  <id>   <registered path>...
+//
+// The API is the only reliable read: `defaults read …LSHandlers` lags and the JXA bridge hands back
+// Refs it cannot unwrap (LEARNINGS 2026-09-16). Launch Services makes an app the default per UTI, not
+// per extension, which is why the extension is resolved to its UTI first. Nothing here changes a
+// registration or a default; `beatrina shortcut --default` does that and then reads this back.
+
+import CoreServices
+import Foundation
+
+func utiFor(_ ext: String) -> String {
+  guard let u = UTTypeCreatePreferredIdentifierForTag(kUTTagClassFilenameExtension, ext as CFString, nil) else { return "" }
+  return u.takeRetainedValue() as String
+}
+
+func defaultHandler(_ uti: String) -> String {
+  if uti.isEmpty { return "" }
+  guard let h = LSCopyDefaultRoleHandlerForContentType(uti as CFString, LSRolesMask.all) else { return "" }
+  return h.takeRetainedValue() as String
+}
+
+func allHandlers(_ uti: String) -> [String] {
+  if uti.isEmpty { return [] }
+  guard let a = LSCopyAllRoleHandlersForContentType(uti as CFString, LSRolesMask.all) else { return [] }
+  return (a.takeRetainedValue() as? [String]) ?? []
+}
+
+func bundlePaths(_ id: String) -> [String] {
+  guard let a = LSCopyApplicationURLsForBundleIdentifier(id as CFString, nil) else { return [] }
+  return ((a.takeRetainedValue() as? [URL]) ?? []).map { $0.path }
+}
+
+func appName(_ id: String) -> String {
+  guard let first = bundlePaths(id).first else { return "" }
+  let last = (first as NSString).lastPathComponent
+  return last.hasSuffix(".app") ? String(last.dropLast(4)) : last
+}
+
+var mode = ""
+for a in CommandLine.arguments.dropFirst() {
+  if a == "ext" || a == "bundle" { mode = a; continue }
+  if mode == "ext" {
+    let uti = utiFor(a)
+    let handler = defaultHandler(uti)
+    print(["ext", a, uti, handler, appName(handler), allHandlers(uti).joined(separator: ",")].joined(separator: "\t"))
+  } else if mode == "bundle" {
+    print((["bundle", a] + bundlePaths(a)).joined(separator: "\t"))
+  }
+}