beatrina 0.8.7 → 0.9.43

package/bin/shortcut.mjs

@@ -20,8 +20,11 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { listSessions } from "./sessions.mjs";
+import { defaultFor, lsQuery, registeredPaths } from "./finder.mjs";
 
 export const BUNDLE_ID = "me.saqr.beatrina";
+// beatrina-names: keep-start — the other product's identities, reclaimed from, are named here on purpose.
 // Each type is EXPORTED by Beatrina.app as its own UTI (UTExportedTypeDeclarations) and named in its
 // document types (LSItemContentTypes): Launch Services sets a default handler per UTI, and an app that
 // only lists an extension has no UTI of its own to be the default FOR — the first --default answered
@@ -36,12 +39,23 @@ export const DOC_TYPES = Object.freeze([
   { ext: "qmd", name: "Quarto document", mime: "text/x-quarto-markdown", uti: "me.saqr.beatrina.qmd", legacy: "me.saqr.carmar.qmd" },
   { ext: "Rmd", name: "R Markdown document", mime: "text/x-r-markdown", uti: "me.saqr.beatrina.rmd", legacy: "me.saqr.carmar.rmd" },
   { ext: "carmd", name: "Beatrina notebook document", mime: "text/markdown", uti: "me.saqr.beatrina.carmd", legacy: "me.saqr.carmar.carmd" },
+  // The .btrn is a ZIP (host/bundle.mjs): it conforms to zip-archive, not text, and its MIME type is
+  // its own — declaring application/zip would make Beatrina a Linux handler for every zip on the disk.
+  { ext: "btrn", name: "Beatrina document", mime: "application/x-beatrina-bundle", uti: "me.saqr.beatrina.btrn", conforms: "public.zip-archive" },
 ]);
+// beatrina-names: keep-end
 
 const q = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;           // POSIX single-quote
 const asString = (s) => `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 
-/** The AppleScript applet's source. `launch` is the shell command prefix. */
+/** The URL scheme the applet registers: `beatrina://start` from the page's Start R (lib/attach-menu.js startHint). */
+export const URL_SCHEME = "beatrina";
+
+/**
+ * The AppleScript applet's source. `launch` is the shell command prefix. `open location` is the
+ * page's Start R (beatrina://start, docs/launch-menu-plan.md L6): another session, whatever runs —
+ * the page asked because it found none — through the same background start the icon makes.
+ */
 export function appleScriptSource(launch) {
   return `on run
 \tdo shell script ${asString(`${launch} --from-app > /dev/null 2>&1 &`)}
@@ -52,23 +66,36 @@ on open theItems
 \t\tdo shell script ${asString(launch)} & " --from-app " & quoted form of (POSIX path of anItem) & " > /dev/null 2>&1 &"
 \tend repeat
 end open
+
+on open location theURL
+\tdo shell script ${asString(`${launch} --from-app --new > /dev/null 2>&1 &`)}
+end open location
 `;
 }
 
+/** The URL type the applet's Info.plist declares (CFBundleURLTypes), as plutil-insertable XML. */
+export function urlTypesXml() {
+  return `<array><dict><key>CFBundleURLName</key><string>${BUNDLE_ID}.start</string>`
+    + `<key>CFBundleURLSchemes</key><array><string>${URL_SCHEME}</string></array></dict></array>`;
+}
+
+/** A type's extension spellings, once each (`Rmd` and `rmd`; `qmd` alone — not `qmd, qmd`). */
+const extensionsXml = (t) => `<array>${[...new Set([t.ext, t.ext.toLowerCase()])].map((e) => `<string>${e}</string>`).join("")}</array>`;
+
 /** The document types an Info.plist declares, as plutil-insertable XML. */
 export function documentTypesXml() {
   return `<array>${DOC_TYPES.map((t) => `<dict><key>CFBundleTypeName</key><string>${t.name}</string>`
     + `<key>CFBundleTypeRole</key><string>Editor</string><key>LSHandlerRank</key><string>Alternate</string>`
-    + `<key>LSItemContentTypes</key><array><string>${t.uti}</string><string>${t.legacy}</string></array>`
-    + `<key>CFBundleTypeExtensions</key><array><string>${t.ext}</string><string>${t.ext.toLowerCase()}</string></array></dict>`).join("")}</array>`;
+    + `<key>LSItemContentTypes</key><array>${[t.uti, t.legacy].filter(Boolean).map((u) => `<string>${u}</string>`).join("")}</array>`
+    + `<key>CFBundleTypeExtensions</key>${extensionsXml(t)}</dict>`).join("")}</array>`;
 }
 
 /** The UTIs Beatrina.app exports for those types (UTExportedTypeDeclarations), as plutil-insertable XML. */
 export function exportedTypesXml() {
   return `<array>${DOC_TYPES.map((t) => `<dict><key>UTTypeIdentifier</key><string>${t.uti}</string>`
     + `<key>UTTypeDescription</key><string>${t.name}</string>`
-    + `<key>UTTypeConformsTo</key><array><string>public.plain-text</string></array>`
-    + `<key>UTTypeTagSpecification</key><dict><key>public.filename-extension</key><array><string>${t.ext}</string><string>${t.ext.toLowerCase()}</string></array>`
+    + `<key>UTTypeConformsTo</key><array><string>${t.conforms || "public.plain-text"}</string></array>`
+    + `<key>UTTypeTagSpecification</key><dict><key>public.filename-extension</key>${extensionsXml(t)}`
     + `<key>public.mime-type</key><array><string>${t.mime}</string></array></dict></dict>`).join("")}</array>`;
 }
 
@@ -85,34 +112,103 @@ function run(cmd, args, opts = {}) {
 
 const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
 
-function macShortcut({ cli, dir, port, makeDefault, noOpen }) {
+/**
+ * Take one registered copy of the app out of Launch Services. A path that no longer exists (a
+ * folder renamed or deleted under a registration) is made to resolve for the moment it takes — a
+ * symlink to `resolveTo`, the parents it needs — unregistered, and the symlink and those parents
+ * removed again; that is the one technique that made LS drop a dead path (LEARNINGS 2026-09-16).
+ * @returns {{ok: boolean, gone: boolean, detail?: string}}
+ */
+export function unregisterCopy(stale, resolveTo, { lsregister = LSREGISTER } = {}) {
+  const gone = !fs.existsSync(stale);
+  const made = [];
+  try {
+    if (gone) {
+      let parent = path.dirname(stale);
+      const missing = [];
+      while (!fs.existsSync(parent)) { missing.unshift(parent); parent = path.dirname(parent); }
+      for (const d of missing) { fs.mkdirSync(d); made.push(d); }
+      fs.symlinkSync(resolveTo, stale);
+    }
+    run(lsregister, ["-u", stale]);
+    return { ok: true, gone };
+  } catch (e) {
+    return { ok: false, gone, detail: e.message };
+  } finally {
+    if (gone) {
+      try { fs.unlinkSync(stale); } catch { /* never made */ }
+      for (const d of made.reverse()) { try { fs.rmdirSync(d); } catch { /* not empty: leave it */ } }
+    }
+  }
+}
+
+/** Point every UTI a type can carry at `bundleId` (the JXA bridge is the only writer; 0 is success). */
+function setDefaultHandler(types, bundleId) {
+  // Beatrina's own UTI for each type, CarmaR's legacy one, and whatever UTI Launch Services currently   (beatrina-names: keep)
+  // resolves the extension to (another app's declaration, or a dynamic one) — all pointed at Beatrina,
+  // so a .qmd opens here whichever identity the system had attached to it.
+  const js = `ObjC.import("CoreServices");
+    const types = ${JSON.stringify(types.map((t) => ({ ext: t.ext, uti: t.uti, legacy: t.legacy })))};
+    types.map((t) => { const tagged = $.UTTypeCreatePreferredIdentifierForTag($.kUTTagClassFilenameExtension, $(t.ext), $()).js;
+      const utis = [...new Set([t.uti, t.legacy, tagged])].filter(Boolean);
+      return t.ext + "=" + utis.map((u) => $.LSSetDefaultRoleHandlerForContentType($(u), $.kLSRolesAll, $(${JSON.stringify(bundleId)}))).join("/"); }).join(" ");`;
+  const out = run("osascript", ["-l", "JavaScript", "-e", js]).trim();
+  return { out, failed: /=(?:[^0 /]|-\d)/.test(out) };
+}
+
+function macShortcut({ cli, dir, port, makeDefault, noOpen, bundleId }) {
   const app = path.join(dir || path.join(os.homedir(), "Applications"), "Beatrina.app");
+  const exts = DOC_TYPES.map((t) => t.ext);
+  // Before anything changes: what Finder does today (finder.mjs, read-only) — which extensions
+  // Beatrina is already the default for, so a rebuild puts that choice back rather than losing it,
+  // and which copies are registered under this id, so every other one can be taken out below.
+  const before = lsQuery({ exts, bundleIds: [bundleId] });
+  const wasDefault = DOC_TYPES.filter((t) => defaultFor(before, bundleId, [t.ext]).length);
   fs.mkdirSync(path.dirname(app), { recursive: true });
   fs.rmSync(app, { recursive: true, force: true });
   const src = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-app-")), "Beatrina.applescript");
   fs.writeFileSync(src, appleScriptSource(launchCommand({ cli, port, noOpen })));
   run("osacompile", ["-o", app, src]);
   const plist = path.join(app, "Contents", "Info.plist");
-  run("plutil", ["-replace", "CFBundleIdentifier", "-string", BUNDLE_ID, plist]);
+  run("plutil", ["-replace", "CFBundleIdentifier", "-string", bundleId, plist]);
   run("plutil", ["-replace", "CFBundleName", "-string", "Beatrina", plist]);
   run("plutil", ["-replace", "CFBundleDocumentTypes", "-xml", documentTypesXml(), plist]);
   run("plutil", ["-replace", "UTExportedTypeDeclarations", "-xml", exportedTypesXml(), plist]);
+  run("plutil", ["-replace", "CFBundleURLTypes", "-xml", urlTypesXml(), plist]);
   run("codesign", ["--force", "--sign", "-", app]);        // the plist changed after osacompile signed it
-  if (fs.existsSync(LSREGISTER)) run(LSREGISTER, ["-f", app]);
-  const said = [`Beatrina.app is in ${path.dirname(app)}. Double-click it, or right-click a .qmd and choose Open With ▸ Beatrina.`];
-  if (makeDefault) {
-    // Beatrina's own UTI for each type, and whatever UTI Launch Services currently resolves the
-    // extension to (another app's declaration, or a dynamic one) — both are pointed at Beatrina, so
-    // a .qmd opens here whichever identity the system had attached to it. 0 is success.
-    const js = `ObjC.import("CoreServices");
-      const types = ${JSON.stringify(DOC_TYPES.map((t) => ({ ext: t.ext, uti: t.uti, legacy: t.legacy })))};
-      types.map((t) => { const tagged = $.UTTypeCreatePreferredIdentifierForTag($.kUTTagClassFilenameExtension, $(t.ext), $()).js;
-        const utis = [...new Set([t.uti, t.legacy, tagged])];
-        return t.ext + "=" + utis.map((u) => $.LSSetDefaultRoleHandlerForContentType($(u), $.kLSRolesAll, $(${JSON.stringify(BUNDLE_ID)}))).join("/"); }).join(" ");`;
-    const out = run("osascript", ["-l", "JavaScript", "-e", js]).trim();
-    const failed = /=(?:[^0 /]|-\d)/.test(out);
-    said.push(failed ? `Beatrina could not be made the default for every type (${out}; 0 means done).`
-      : `Beatrina is now the default app for ${DOC_TYPES.map((t) => `.${t.ext}`).join(", ")}.`);
+  const said = [];
+  // Idempotent: every OTHER copy registered under this id is unregistered before this one is
+  // registered. Launch Services picks between copies at its own discretion — an older Beatrina.app
+  // dragged somewhere, a scratch build a killed test left behind, a folder that no longer exists —
+  // so which copy a double-click reaches is its choice until there is one.
+  if (fs.existsSync(LSREGISTER)) {
+    for (const stale of registeredPaths(before, bundleId).filter((p) => path.resolve(p) !== path.resolve(app))) {
+      const done = unregisterCopy(stale, app);
+      said.push(done.ok ? `Unregistered another copy of Beatrina.app at ${stale}${done.gone ? " (a folder that no longer exists)" : ""}.`
+        : `Could not unregister the copy of Beatrina.app at ${stale} (${done.detail}); Finder may still pick it.`);
+    }
+    run(LSREGISTER, ["-f", app]);
+  }
+  said.push(`Beatrina.app is in ${path.dirname(app)}. Double-click it, or right-click a .qmd and choose Open With ▸ Beatrina.`);
+  // The default: every type with --default; otherwise only the types Beatrina was already the
+  // default for (a rebuild is not a choice — "never by surprise"), re-asserted because a fresh
+  // registration can lose it.
+  const wanted = makeDefault ? DOC_TYPES : wasDefault;
+  if (wanted.length) {
+    const set = setDefaultHandler(wanted, bundleId);
+    if (set.failed) said.push(`Beatrina could not be made the default for every type (${set.out}; 0 means done).`);
+    else if (!makeDefault) said.push(`Beatrina stays the default app for ${wasDefault.map((t) => `.${t.ext}`).join(", ")}, as before.`);
+    if (makeDefault && !set.failed) {
+      // Read back from Launch Services, never inferred from return codes.
+      const after = lsQuery({ exts, bundleIds: [bundleId] });
+      if (!after) said.push(`Beatrina is now the default app for ${exts.map((e) => `.${e}`).join(", ")} (not read back: no Swift toolchain).`);
+      else {
+        const now = defaultFor(after, bundleId, exts);
+        const still = exts.filter((e) => !now.includes(e)).map((e) => { const r = after.ext.find((x) => x.ext === e); return `.${e} (${(r && (r.name || r.handler)) || "no app"})`; });
+        if (now.length) said.push(`Finder now opens ${now.map((e) => `.${e}`).join(", ")} with Beatrina.`);
+        if (still.length) said.push(`Finder still opens ${still.join(", ")} elsewhere — run beatrina doctor, then beatrina shortcut --default again.`);
+      }
+    }
   }
   return { app, said };
 }
@@ -155,25 +251,137 @@ function linuxShortcut({ cli, port, makeDefault }) {
   return { app: desktop, said };
 }
 
-/** Make the icon (and, with makeDefault, the default .qmd app). */
-export function makeShortcut({ cli, dir = "", port = "", makeDefault = false, noOpen = false, platform = process.platform }) {
-  if (platform === "darwin") return macShortcut({ cli, dir, port, makeDefault, noOpen });
-  if (platform === "win32") return windowsShortcut({ cli, port, makeDefault });
-  return linuxShortcut({ cli, port, makeDefault });
-}
-
-/** A running session of this app (runtime records + a live /health), or null. */
-export async function liveSession({ app = "beatrina", runtimeDir = process.env.CARMAR_RUNTIME_DIR || path.join(os.homedir(), ".carmar", "run"), port = "" } = {}) {
-  let names = [];
-  try { names = fs.readdirSync(runtimeDir).filter((n) => /^kernel-\d+\.json$/.test(n)); } catch { return null; }
-  for (const name of names) {
-    let rec;
-    try { rec = JSON.parse(fs.readFileSync(path.join(runtimeDir, name), "utf8")); } catch { continue; }
-    if (rec.app !== app || (port && String(rec.port) !== String(port))) continue;
-    try {
-      const res = await fetch(`http://127.0.0.1:${rec.port}/health`, { signal: AbortSignal.timeout(1500) });
-      if (res.ok) return rec;
-    } catch { /* a record the session left behind */ }
+// ── the menu (docs/launch-menu-plan.md M2) ──────────────────────────────────
+// `Beatrina Menu.app` ships in the npm package at menu/ (tools/app/build-helper.sh --product
+// beatrina; a binary and an Info.plist, nothing of its own inside). `beatrina shortcut --menu`
+// copies it beside Beatrina.app, writes the exact command line the applet bakes to
+// Contents/Resources/beatrina-command (an absolute Node and CLI path: a menu-bar process has no
+// PATH), registers it and opens it; --login adds a LaunchAgent with RunAtLoad and NO KeepAlive (a
+// menu, not a daemon — helper-agent.sh's "additive and explicit" rule); --no-menu removes both.
+// Explicit both ways: `beatrina shortcut` alone installs no menu, and only refreshes the command
+// line of a menu already installed beside the applet, so the two stay in step after a Node upgrade.
+export const MENU_BUNDLE_ID = "me.saqr.beatrina.menu";
+export const MENU_NAME = "Beatrina Menu.app";
+const menuLabel = () => process.env.BEATRINA_MENU_LABEL || MENU_BUNDLE_ID;
+const menuAgentPlist = () => path.join(os.homedir(), "Library", "LaunchAgents", `${menuLabel()}.plist`);
+const launchDomain = () => `gui/${process.getuid()}`;
+
+/** The LaunchAgent that starts the menu at login: RunAtLoad, and deliberately no KeepAlive. */
+export function menuAgentXml({ label, binary }) {
+  const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${esc(label)}</string>
+  <key>ProgramArguments</key><array><string>${esc(binary)}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>ProcessType</key><string>Interactive</string>
+</dict></plist>
+`;
+}
+
+/** Write (or refresh) the command line the menu runs, and re-seal the bundle around it. */
+function writeMenuCommand(menuApp, cli) {
+  const resources = path.join(menuApp, "Contents", "Resources");
+  fs.mkdirSync(resources, { recursive: true });
+  fs.writeFileSync(path.join(resources, "beatrina-command"), `${launchCommand({ cli })}\n`, { mode: 0o644 });
+  run("codesign", ["--force", "--deep", "--sign", "-", menuApp]);   // the resources changed after the build signed it
+}
+
+/** Install the menu beside the applet. @returns {string[]} what was done */
+function installMenu({ cli, dir, login, noOpen, menuSource }) {
+  const said = [];
+  if (!menuSource || !fs.existsSync(path.join(menuSource, "Contents", "MacOS", "Beatrina Menu"))) {
+    return [`This Beatrina carries no menu (${menuSource || "no menu/ folder"}); a package built on a Mac ships one. Nothing was installed.`];
   }
-  return null;
+  const menuApp = path.join(dir || path.join(os.homedir(), "Applications"), MENU_NAME);
+  // Quit a running menu before its files change under it; a menu that is not running is not an error.
+  spawnSync("osascript", ["-e", `tell application id "${MENU_BUNDLE_ID}" to quit`], { timeout: 10000 });
+  fs.rmSync(menuApp, { recursive: true, force: true });
+  fs.cpSync(menuSource, menuApp, { recursive: true });
+  writeMenuCommand(menuApp, cli);
+  if (fs.existsSync(LSREGISTER)) run(LSREGISTER, ["-f", menuApp]);
+  said.push(`${MENU_NAME} is in ${path.dirname(menuApp)}; it runs \`beatrina\` for you and starts nothing itself.`);
+  if (login) {
+    const plist = menuAgentPlist();
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.writeFileSync(plist, menuAgentXml({ label: menuLabel(), binary: path.join(menuApp, "Contents", "MacOS", "Beatrina Menu") }), { mode: 0o644 });
+    spawnSync("launchctl", ["bootout", `${launchDomain()}/${menuLabel()}`], { timeout: 10000 });
+    if (noOpen) said.push(`It will start at your next login (${plist}).`);
+    else {
+      const up = spawnSync("launchctl", ["bootstrap", launchDomain(), plist], { encoding: "utf8", timeout: 20000 });
+      said.push(up.status === 0 ? `It is running now and starts at every login (${plist}); beatrina shortcut --no-menu removes it.`
+        : `It starts at every login (${plist}), but launchctl could not start it now (${String(up.stderr).trim() || up.status}) — open it from ${path.dirname(menuApp)}.`);
+    }
+  } else if (!noOpen) {
+    const opened = spawnSync("open", ["-a", menuApp], { encoding: "utf8", timeout: 20000 });
+    said.push(opened.status === 0 ? "It is in your menu bar now (the B); beatrina shortcut --menu --login makes it start at every login, --no-menu removes it."
+      : `It could not be opened (${String(opened.stderr).trim() || opened.status}); open it from ${path.dirname(menuApp)}.`);
+  }
+  return said;
+}
+
+/**
+ * `beatrina shortcut --no-menu`: the login agent, the running menu and the bundle, gone. Nothing
+ * else changes — Beatrina.app, the file types and the sessions are untouched.
+ */
+export function removeMenu({ dir = "", platform = process.platform } = {}) {
+  if (platform !== "darwin") return { said: ["The menu-bar item is macOS only; nothing to remove."] };
+  const said = [];
+  const menuApp = path.join(dir || path.join(os.homedir(), "Applications"), MENU_NAME);
+  const plist = menuAgentPlist();
+  spawnSync("launchctl", ["bootout", `${launchDomain()}/${menuLabel()}`], { timeout: 10000 });
+  if (fs.existsSync(plist)) { fs.rmSync(plist, { force: true }); said.push(`Removed the login item ${plist}.`); }
+  spawnSync("osascript", ["-e", `tell application id "${MENU_BUNDLE_ID}" to quit`], { timeout: 10000 });
+  if (fs.existsSync(menuApp)) {
+    if (fs.existsSync(LSREGISTER)) spawnSync(LSREGISTER, ["-u", menuApp]);
+    fs.rmSync(menuApp, { recursive: true, force: true });
+    said.push(`Removed ${menuApp}.`);
+  }
+  if (!said.length) said.push("No Beatrina menu was installed; nothing to remove.");
+  said.push("Beatrina.app, the file types and any running session are as they were.");
+  return { said };
+}
+
+/**
+ * Make the icon (and, with makeDefault, the default .qmd app; with menu, the menu-bar item).
+ * BEATRINA_BUNDLE_ID substitutes the bundle id (the suites build a scratch Beatrina.app under a
+ * scratch id, so the one in ~/Applications is never a second copy of theirs).
+ */
+export function makeShortcut({ cli, dir = "", port = "", makeDefault = false, noOpen = false, platform = process.platform,
+  bundleId = process.env.BEATRINA_BUNDLE_ID || BUNDLE_ID, menu = false, login = false, menuSource = "" }) {
+  if (platform === "darwin") {
+    const made = macShortcut({ cli, dir, port, makeDefault, noOpen, bundleId });
+    const menuApp = path.join(dir || path.join(os.homedir(), "Applications"), MENU_NAME);
+    if (menu) made.said.push(...installMenu({ cli, dir, login, noOpen, menuSource }));
+    else if (fs.existsSync(path.join(menuApp, "Contents", "MacOS", "Beatrina Menu"))) {
+      writeMenuCommand(menuApp, cli);
+      made.said.push(`${MENU_NAME} in ${path.dirname(menuApp)} now runs this beatrina too.`);
+    }
+    return made;
+  }
+  const said = menu ? ["The menu-bar item is macOS only; the rest was done."] : [];
+  const made = platform === "win32" ? windowsShortcut({ cli, port, makeDefault }) : linuxShortcut({ cli, port, makeDefault });
+  made.said.push(...said);
+  return made;
+}
+
+/**
+ * A running session of this app, or null — the door every double-click, icon and menu row goes through.
+ *
+ * A thin wrapper over `listSessions` (sessions.mjs), so `beatrina status`, `stop`, `doctor`, the menu
+ * and this one door read ONE discovery: the runtime records of the asked app whose /health proves the
+ * same session (host and boot instant). With no `port`, the NEWEST `started` first — the rule
+ * launch.sh applies to a delivered document — so a double-click with two sessions running lands in the
+ * one started most recently, not on the lowest port readdir happens to list first. With `port`, that
+ * session or null. The row carries what the record does (port, url, file, pid, started, document…).
+ */
+export async function liveSession({ app = "beatrina", runtimeDir = null, port = "" } = {}) {
+  // Records live in ~/.beatrina/run, and in the older directory for a session an older build started;
+  // an explicit BEATRINA_RUNTIME_DIR, under either spelling (or the `runtimeDir` option), is read alone.
+  const rows = await listSessions({ dir: runtimeDir, apps: new Set([app]) });
+  const startedAt = (r) => Date.parse(r.started) || 0;
+  const live = rows.filter((r) => r.live && (!port || String(r.port) === String(port)))
+    .sort((a, b) => startedAt(b) - startedAt(a) || a.port - b.port);
+  return live[0] || null;
 }

package/bin/update-check.mjs

@@ -4,8 +4,8 @@
 // At most once a day per user (the last check is recorded in a small JSON file, which the host reads
 // back to put `update_available` on /health — host/update-record.mjs), with a short timeout, and never
 // in the way: a registry that cannot be reached, an unpublished package (404) or a garbled answer all
-// mean "nothing to say". BEATRINA_NO_UPDATE_CHECK=1 or CARMAR_NO_UPDATE_CHECK=1 turns it off (the
-// battery runner sets the second). BEATRINA_REGISTRY points at another registry (tests).
+// mean "nothing to say". BEATRINA_NO_UPDATE_CHECK=1 (or its older spelling) turns it off (the
+// battery runner sets it). BEATRINA_REGISTRY points at another registry (tests).
 
 import fs from "node:fs";
 import path from "node:path";

package/build-info.json

@@ -1 +1 @@
-{"version":"0.8.7","commit":"b7aa1255558293d1e2b47a4799a344fde0846b2e","dirty":false}
+{"version":"0.9.43","commit":"ce1dbc09721024a43c3666122e3e0759a24b294f","dirty":false}

package/engines/js/worker.mjs

@@ -39,10 +39,13 @@ import vm from "node:vm";
 import { createRequire } from "node:module";
 import { persistDeclarations } from "./persist.mjs";
 import { DocumentExecError, DocumentSetups, FEATURE } from "./document-exec.mjs";
+// host/ sits beside engines/ in every distribution (tools/npm/build-npm.mjs).
+import { readEnv } from "../../host/env-names.mjs";
 
-const SENTINEL = process.env.CARMAR_SENTINEL || "";
-const CMD_TAG = process.env.CARMAR_CMD_TAG || "";
-const HANDOFF_DIR = process.env.CARMAR_HANDOFF_DIR || "";
+// BEATRINA_* first, the old CARMAR_* spelling second (host/env-names.mjs).
+const SENTINEL = readEnv(process.env, "SENTINEL");
+const CMD_TAG = readEnv(process.env, "CMD_TAG");
+const HANDOFF_DIR = readEnv(process.env, "HANDOFF_DIR");
 const COMMANDS = ["exec", "wd", "doctor", "env", "rm", "parse", "complete"];
 const PREVIEW_ROWS = 200;
 const PREVIEW_COLS = 20;

package/engines/python/adapter.py

@@ -1,11 +1,12 @@
 """adapter.py — Jupyter messages in, Beatrix frames out.
 
-Ported from `../carmar-python/py/carmapy/kernel_adapter.py` (read 2026-09-14).
+Ported from carmapy's `py/carmapy/kernel_adapter.py` (read 2026-09-14; that
+repository is closed — github.com/mohsaqr/carmar-python, see docs/python-kernel-records/).
 It does not evaluate anything itself; `ipykernel` does that, in its own OS
 process, and this translates.
 
 THE RULE THAT COST THREE WRONG MEASUREMENTS OVER THERE
-(`../carmar-python/notes/probes/RESULTS.md` P1):
+(`docs/python-kernel-records/probes/RESULTS.md` P1):
 
     A cell is finished when iopub reports `status: idle` for its parent
     msg_id — NEVER when execute_reply arrives.
@@ -37,14 +38,14 @@ from typing import Awaitable, Callable
 
 from jupyter_client.manager import AsyncKernelManager
 
-from bootstrap import BOOTSTRAP, CARMAR_MIME, CONTROL_MIME, REPLY_MIME
+from bootstrap import BOOTSTRAP, BEATRINA_MIME, CONTROL_MIME, REPLY_MIME
 
 #: debugger.py's PROMPT. Restated, not imported: debugger.py is kernel-side
 #: source and is never imported into this process. test/host-python-debug
 #: pins the two spellings against each other.
-DEBUG_PROMPT = "\x1bcarmar-debug\x1b"
-#: debugger.py's CarmarDebugAbort, as ipykernel names it on the error message.
-DEBUG_ABORT = "CarmarDebugAbort"
+DEBUG_PROMPT = "\x1bbeatrina-debug\x1b"
+#: debugger.py's BeatrinaDebugAbort, as ipykernel names it on the error message.
+DEBUG_ABORT = "BeatrinaDebugAbort"
 
 Emit = Callable[[dict], Awaitable[None]]
 
@@ -56,7 +57,7 @@ class PythonSession:
     """One Python session: the notebook's `worker.R` equivalent.
 
     Owns exactly one ipykernel process. Not a pool, not a registry — one
-    document, one kernel, which is both Jupyter's rule and CarmaR's.
+    document, one kernel, which is both Jupyter's rule and Beatrina's.
     """
 
     def __init__(self, kernel_name: str = "python3", on_input=None, on_debug=None):
@@ -219,7 +220,7 @@ class PythonSession:
             try:
                 if srcname:
                     spec = json.dumps(json.dumps({"srcname": srcname, "breaks": breaks or {}}))
-                    prep = self.kc.execute(f"__carmar_debug_prepare({spec})",
+                    prep = self.kc.execute(f"__beatrina_debug_prepare({spec})",
                                            store_history=False, allow_stdin=False)
                     await self._drain_until_idle(prep, None, None, timeout=30)
                 msg_id = self.kc.execute(code, store_history=store_history,
@@ -250,13 +251,13 @@ class PythonSession:
 
         The wire never carries code. `spec` is JSON, passed as ONE argument to
         a function the bootstrap installed; the kernel-side half parses it. A
-        composed `__carmapy_view(df, sort='...')` string would be the browser
+        composed `__beatrina_view(df, sort='...')` string would be the browser
         writing Python, which is the door this design does not have.
         """
         async with self._chan:
             self._reply = None
             payload = json.dumps(json.dumps(spec, allow_nan=False))
-            code = f"__carmapy_reply({op!r}, {payload})"
+            code = f"__beatrina_reply({op!r}, {payload})"
             msg_id = self.kc.execute(code, store_history=False, allow_stdin=False)
             await self._drain_until_idle(msg_id, None, None, timeout=300)
             reply, self._reply = self._reply, None
@@ -403,7 +404,7 @@ class PythonSession:
                 self.interrupted = True
                 return []
             # The debugger's Stop: R reports it as `interrupted` with the
-            # message "Stopped from the debugger" (worker.R carmar_abort_cell),
+            # message "Stopped from the debugger" (worker.R beatrina_abort_cell),
             # and so does this — no traceback for a button the user pressed.
             if ename == DEBUG_ABORT:
                 self.interrupted = True
@@ -449,8 +450,8 @@ class PythonSession:
             self._reply = json.loads(payload) if isinstance(payload, str) else payload
             return []
 
-        if CARMAR_MIME in data:
-            payload = data[CARMAR_MIME]
+        if BEATRINA_MIME in data:
+            payload = data[BEATRINA_MIME]
             if isinstance(payload, str):
                 payload = json.loads(payload)
             return [{"type": "dataframe", "id": wire_id, "source": None, **payload}]

package/engines/python/analyze.py

@@ -8,7 +8,8 @@ and that must not take syntax checking, navigation and rename down with it.
     browser  ⇅  host/main.mjs  ⇅  ipykernel     — evaluates everything
                                ⇅  analyze.py    — evaluates NOTHING
 
-Ported from carmapy's analyze.py (../carmar-python/py/carmapy/analyze.py), with
+Ported from carmapy's analyze.py (`py/carmapy/analyze.py` in the closed
+repository github.com/mohsaqr/carmar-python, see docs/python-kernel-records/), with
 one deliberate change recorded in docs/wp/wp8a-python-analyzer.md: the
 reference index is built from `ast`, not from `jedi`, and jedi is not imported.
 
@@ -69,7 +70,8 @@ import warnings
 
 def _budget() -> float:
     try:
-        v = float(os.environ.get("CARMAR_ANALYZE_BUDGET", "3"))
+        v = float(os.environ.get("BEATRINA_ANALYZE_BUDGET")
+                  or os.environ.get("CARMAR_ANALYZE_BUDGET", "3"))  # beatrina-names: keep
     except ValueError:
         v = 3.0
     if v != v or v in (float("inf"), float("-inf")):