beatrina 0.8.7 → 0.9.83

package/host/planes/sessions.mjs

@@ -18,12 +18,13 @@
 // POST /session/upgrade and POST /session/restart. A port of serve.R's
 // handoff_refusal / session_handoff_begin / session_handoff_spawn: a successor
 // supervisor is started on the SAME port from the files beside this one (after
-// an in-place upgrade, the installed build's), every page is told where its
-// successor's notebook is, the worker's whole tree is killed, and this process
-// exits. The successor's R is FRESH — no save.image() bridge, by decision
+// an in-place upgrade, the installed build's) and must PROVE it can run before
+// anything of this session is touched (handoffBegin: prepare, then retire);
+// then every page is told where its successor's notebook is, the worker's whole
+// tree is killed, and this process exits. The successor's R is FRESH — no save.image() bridge, by decision
 // (docs/upgrade.md); a restart says so and does not pretend otherwise.
 //
-// `CARMAR_SESSION_BASE` is Beatrix's only addition to the wire's behaviour
+// `BEATRINA_SESSION_BASE` is Beatrix's only addition to the wire's behaviour
 // here: serve.R hardcodes the 4747..4947 scan, and a TEST may not bind 4747
 // (FORK.md), so the base is readable from the environment and defaults to
 // 4747 — the published-page port, fixed because browsers key storage to the
@@ -37,6 +38,8 @@ import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { PAGE_ONLY_CLASSES, secureToken } from "../server.mjs";
 import { stateDir } from "../user-dirs.mjs";
+import { mirrorEnv, unsetEnv } from "../env-names.mjs";
+import { runtimeReadDirs } from "../runtime-dir.mjs";
 import { encodeSessionDocuments, keepTokenOk } from "../session-keep.mjs";
 
 export const SESSION_OPS = Object.freeze(["session_list", "r_versions", "session-new"]);
@@ -46,28 +49,39 @@ export const SESSION_BAND = 201;
 
 const RUNTIME_NAME = /^kernel-([0-9]+)\.json$/;
 
-/** The runtime directory both supervisors write their records into. */
-export function runtimeDir(env) {
-  return env("CARMAR_RUNTIME_DIR") || path.join(os.homedir(), ".carmar", "run");
+/**
+ * The first port of the session band: BEATRINA_SESSION_BASE when it names one, else 4747. ONE
+ * definition — the sibling a page starts (below) and the host's own choosePort (main.mjs) read
+ * it, so the two starters agree on where a second session lands.
+ */
+export function sessionBase(env) {
+  const given = Number.parseInt(env("BEATRINA_SESSION_BASE", "4747"), 10);
+  return Number.isInteger(given) && given >= 1024 && given <= 65000 ? given : 4747;
 }
 
-/** Every `kernel-<port>.json` in the runtime directory, parsed; unreadable ones dropped. */
+/**
+ * Every `kernel-<port>.json` a kernel may have left, parsed; unreadable ones
+ * dropped. Read from the current directory AND the legacy `~/.carmar/run`   (beatrina-names: keep)
+ * (a kernel started before the rename, or by an older launcher, is still a
+ * session); one record per port, the current directory's winning.
+ */
 export function runtimeRecords(env) {
-  const dir = runtimeDir(env);
-  let names = [];
-  try { names = fs.readdirSync(dir); } catch { return []; }
-  const out = [];
-  for (const name of names) {
-    const m = RUNTIME_NAME.exec(name);
-    if (!m) continue;
-    let rec = null;
-    try { rec = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8")); } catch { rec = null; }
-    if (!rec || typeof rec !== "object" || rec.port == null || rec.url == null) continue;
-    const port = Number.parseInt(rec.port, 10);
-    if (!Number.isInteger(port)) continue;
-    out.push({ ...rec, port });
+  const byPort = new Map();
+  for (const dir of runtimeReadDirs(env)) {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    for (const name of names) {
+      const m = RUNTIME_NAME.exec(name);
+      if (!m) continue;
+      let rec = null;
+      try { rec = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8")); } catch { rec = null; }
+      if (!rec || typeof rec !== "object" || rec.port == null || rec.url == null) continue;
+      const port = Number.parseInt(rec.port, 10);
+      if (!Number.isInteger(port) || byPort.has(port)) continue;
+      byPort.set(port, { ...rec, port });
+    }
   }
-  return out.sort((a, b) => a.port - b.port);
+  return [...byPort.values()].sort((a, b) => a.port - b.port);
 }
 
 /**
@@ -78,15 +92,22 @@ export function runtimeRecords(env) {
  * connected page for a full minute per port.
  */
 export async function healthy(url, timeoutMs = 1000) {
+  return (await healthOf(url, timeoutMs)) != null;
+}
+
+/** The /health frame of a kernel that is answering on `url` (`"ok":true`), else null. Same one-second rule. */
+export async function healthOf(url, timeoutMs = 1000) {
   const target = `${String(url).replace(/\/+$/, "")}/health`;
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
     const res = await fetch(target, { signal: ctrl.signal, cache: "no-store" });
-    if (!res.ok) return false;
-    return (await res.text()).includes('"ok":true');
+    if (!res.ok) return null;
+    const text = await res.text();
+    if (!text.includes('"ok":true')) return null;
+    try { const h = JSON.parse(text); return h && h.ok === true ? h : null; } catch { return null; }
   } catch {
-    return false;
+    return null;
   } finally {
     clearTimeout(timer);
   }
@@ -181,10 +202,9 @@ export function createPlane({ root, env, audit }) {
   const siblingArgs = mainPath ? [mainPath] : [];
   let versionsCache = null;
 
-  const sessionBase = (() => {
-    const given = Number.parseInt(env("CARMAR_SESSION_BASE", "4747"), 10);
-    return Number.isInteger(given) && given >= 1024 && given <= 65000 ? given : 4747;
-  })();
+  const base = sessionBase(env);
+  /** Ports chosen by a sibling start that has not finished yet. */
+  const pendingPorts = new Set();
 
   /**
    * Start another supervisor on the next free adjacent port.
@@ -192,47 +212,73 @@ export function createPlane({ root, env, audit }) {
    * Adjacent and stable on purpose (browsers key storage to the origin), and
    * DETACHED — closing this session must not close that one. The port is a
    * PREFERENCE, not a promise: between the probe and the child's own bind the
-   * port can go, so what is waited for is a NEW live port, whichever appears.
-   * serve.R learned that too: waiting for the exact port reported failure for
-   * a session that had started perfectly well, and orphaned it.
+   * port can go, so the answer is the port the child ANNOUNCES in its runtime
+   * record, never the one asked for. serve.R learned that too: waiting for the
+   * exact port reported failure for a session that had started perfectly well,
+   * and orphaned it.
+   *
+   * The session waited for is THIS child's, identified by a launch id carried
+   * in its environment (BEATRINA_LAUNCH_ID → the record's `launch`) and by its
+   * pid. Until 0.9.6 it was "the first live port that was not there before",
+   * so two New Session clicks at once — or any launch from the menu bar in the
+   * same seconds — could each be handed the other's session (hardening.md 3).
+   *
+   * Resolves {port, url} or {error, log}: an early exit or a timeout is said
+   * with the tail of the child's own log, not folded into a bare null.
    */
   const startSibling = async (ctx) => {
     const own = ctx.port();
     const used = new Set(await liveSessionPorts(env, own));
+    // A port another start in THIS process has chosen is taken too: two
+    // requests probing at once both saw the same free port, and the second
+    // child found it bound (the concurrent case in test/host-sessions).
     let chosen = null;
-    for (let p = sessionBase; p <= sessionBase + SESSION_BAND - 1; p += 1) {
-      if (!used.has(p)) { chosen = p; break; }
+    for (let p = base; p <= base + SESSION_BAND - 1; p += 1) {
+      if (!used.has(p) && !pendingPorts.has(p)) { chosen = p; break; }
     }
-    if (chosen == null) return null;
-    const before = new Set(await liveSessionPorts(env, own));
+    if (chosen == null) return { error: `Every port from ${base} to ${base + SESSION_BAND - 1} holds a session.` };
+    pendingPorts.add(chosen);
+    try { return await startOn(chosen); } finally { pendingPorts.delete(chosen); }
+  };
+
+  /** The start itself, on a port already reserved by startSibling. */
+  const startOn = async (chosen) => {
+    const launch = `sibling-${secureToken(12).replace(/[^A-Za-z0-9]/g, "").slice(0, 12)}`;
     // The pipes go to a FILE, not to a pipe nobody reads: a detached sibling
     // wedges once ~64 KB of stderr accumulates in an unread buffer.
+    const logPath = path.join(os.tmpdir(), `beatrix-session-${process.pid}-${launch}.log`);
     let logFd = "ignore";
-    try {
-      logFd = fs.openSync(path.join(os.tmpdir(), `beatrix-session-${process.pid}-${chosen}.log`), "a");
-    } catch { logFd = "ignore"; }
+    try { logFd = fs.openSync(logPath, "a"); } catch { logFd = "ignore"; }
+    const logTail = () => {
+      try { return fs.readFileSync(logPath, "utf8").trim().split("\n").slice(-6).join("\n"); } catch { return ""; }
+    };
     let child;
     try {
       child = spawn(process.execPath, siblingArgs, {
         cwd: root,
-        env: { ...process.env, CARMAR_PORT: String(chosen) },
+        env: mirrorEnv({ ...process.env, BEATRINA_PORT: String(chosen), BEATRINA_LAUNCH_ID: launch, BEATRINA_LAUNCH_VIA: "session-menu" }),
         detached: true,
         stdio: ["ignore", logFd, logFd],
       });
       child.unref();
-    } catch { return null; }
+    } catch (e) {
+      return { error: `The session could not be started: ${e.message}` };
+    } finally {
+      if (typeof logFd === "number") { try { fs.closeSync(logFd); } catch { /* the child holds its own copy */ } }
+    }
+    let spawnError = null;
+    child.on("error", (e) => { spawnError = e; });
     const deadline = Date.now() + 60000;
     while (Date.now() < deadline) {
-      const fresh = (await liveSessionPorts(env, own)).filter((p) => !before.has(p));
-      if (fresh.length) {
-        const got = fresh[0];
-        const rec = runtimeRecords(env).find((r) => r.port === got);
-        return { port: got, url: rec ? rec.url : `http://127.0.0.1:${got}/` };
+      const rec = runtimeRecords(env).find((r) => r.launch === launch && Number(r.pid) === child.pid);
+      if (rec && rec.url && await healthy(rec.url)) return { port: rec.port, url: rec.url, launch };
+      if (spawnError) return { error: `The session could not be started: ${spawnError.message}`, log: logTail() };
+      if (child.exitCode !== null || child.signalCode !== null) {
+        return { error: `The new session stopped before it was ready (${child.signalCode || `exit ${child.exitCode}`}).`, log: logTail() };
       }
-      if (child.exitCode !== null || child.signalCode !== null) return null;
       await new Promise((r) => setTimeout(r, 250));
     }
-    return null;
+    return { error: "The new session did not become ready within 60 seconds.", log: logTail() };
   };
 
   // ── the handoff ─────────────────────────────────────────────────────────
@@ -242,12 +288,12 @@ export function createPlane({ root, env, audit }) {
   const handoffRefusal = (ctx, mode, force) => {
     const refuse = (error, reason) => ({ error, reason });
     const installed = ctx.installedBuild();
-    if (!installed || installed === "unknown") return refuse("This kernel cannot tell which CarmaR is installed.", "unknown-install");
+    if (!installed || installed === "unknown") return refuse("This kernel cannot tell which Beatrina is installed.", "unknown-install");
     if (mode === "upgrade" && installed === ctx.kernelBuild) {
-      return refuse(`This session already runs the installed CarmaR ${installed}.`, "same-build");
+      return refuse(`This session already runs the installed Beatrina ${installed}.`, "same-build");
     }
     if (!ctx.notebookPage(installed)) {
-      return refuse(`The installed CarmaR ${installed} has no notebook page beside this kernel.`, "no-page");
+      return refuse(`The installed Beatrina ${installed} has no notebook page beside this kernel.`, "no-page");
     }
     // An attempt that has spawned owns the port until this process exits.
     if (handoff) return refuse("A session restart is already under way.", "under-way");
@@ -269,7 +315,24 @@ export function createPlane({ root, env, audit }) {
     return script ? { cmd: process.execPath, args: [script] } : { cmd: process.execPath, args: [] };
   };
 
-  const handoffBegin = (ctx, mode = "upgrade", force = false, resume = null) => {
+  /**
+   * Begin a handoff. TWO PHASES (docs/runplan.md, "Two-phase handoff"):
+   *
+   *   1. PREPARE — the successor is started with a ready file to write. It reads its protocol and
+   *      build, finds its page and its worker, and runs its R once, all BEFORE it waits for the
+   *      port (host/main.mjs, handoffPreflight). Nothing of this session has been touched: pages
+   *      have not been told, workers are running, the port is ours.
+   *   2. RETIRE — only once the successor says `ok`: pages are told where it is, workers are
+   *      stopped, this process leaves and the successor takes the port.
+   *
+   * Until 0.9.5 there was one phase: spawn, kill the workers, exit 300 ms later — so a successor
+   * that could not start (a broken install, a missing page, an R that would not run) took the
+   * session down with it. A successor that fails or stays silent is now killed and the session
+   * carries on, and the reply says why.
+   *
+   * @returns {Promise<object>} the reply — `{ok:true, …}` or `{ok:false, error, reason}`
+   */
+  const handoffBegin = async (ctx, mode = "upgrade", force = false, resume = null) => {
     mode = mode === "restart" ? "restart" : "upgrade";
     force = force === true && mode === "restart";
     const auditName = mode === "restart" ? "session-restart" : "session-upgrade";
@@ -284,56 +347,124 @@ export function createPlane({ root, env, audit }) {
     const started = ctx.startedSeconds;
     handoff = { to: installed, cap, page, mode, force, resume: keepTokenOk(resume) ? resume : null };
     audit(auditName, { from: ctx.kernelBuild, to: installed, force });
+
+    const prepared = await handoffPrepare(ctx);
+    if (!prepared.ok) {
+      handoff = null;
+      audit("session-upgrade-failed", { reason: prepared.reason, detail: prepared.error });
+      return { ok: false, error: prepared.error, reason: prepared.reason };
+    }
+    // R may have been given a chunk while the successor prepared. Retiring now would kill it; a
+    // forced restart was asked for exactly that, anything else is refused and the successor goes.
+    const pl = ctx.plane;
+    if (!force && ((pl.running && pl.running.size > 0) || (pl.primary ? pl.primary.active != null : pl.active != null))) {
+      killSuccessor(prepared.child);
+      handoff = null;
+      audit(`${auditName}-refused`, { reason: "busy", force, phase: "prepared" });
+      return { ok: false, error: "R became busy while the new session was being prepared — wait for the running chunk, or interrupt it, then try again.", reason: "busy" };
+    }
     // Every page learns where its successor's notebook is — over the gated
     // socket only; the capability never appears in /health. `started` is this
     // kernel's boot time: a page recognises its successor by a LATER one, the
     // only test that also works when the build does not change.
     const told = ctx.enc({ type: "session-upgrade", from: ctx.kernelBuild, to: installed, page, started, mode, force, keep: handoff.resume != null });
     ctx.pageRecs().forEach((r) => { try { r.ws.send(told); } catch { /* gone */ } });
-    const spawned = handoffSpawn(ctx);
-    if (!spawned) return { ok: false, error: "The installed CarmaR could not be started.", reason: "spawn" };
+    handoffRetire(ctx);
     return { ok: true, from: ctx.kernelBuild, to: installed, page, started, mode, force };
   };
 
-  const handoffAbandon = (ctx, reason) => {
-    audit("session-upgrade-failed", { reason });
-    handoff = null;
-    const told = ctx.enc({ type: "session-upgrade-failed", error: reason });
-    ctx.pageRecs().forEach((r) => { try { r.ws.send(told); } catch { /* gone */ } });
+  /** A successor that will not be used: its whole group goes, since it was started detached. */
+  const killSuccessor = (child) => {
+    if (!child || !child.pid) return;
+    try { process.kill(-child.pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch { /* gone */ } }
+  };
+
+  /** How long a successor may take to prove it can run. */
+  const prepareSeconds = () => {
+    const v = Number(env("BEATRINA_HANDOFF_PREPARE_S", "20"));
+    return Number.isFinite(v) && v > 0 ? v : 20;
   };
 
-  /** Start the successor on this port, kill the worker tree, and leave. */
-  const handoffSpawn = (ctx) => {
+  /**
+   * Phase 1: start the successor on this port and wait for its ready file.
+   * @returns {Promise<{ok:true, child:object}|{ok:false, error:string, reason:string}>}
+   */
+  const handoffPrepare = async (ctx) => {
     const h = handoff;
     const dir = stateDir();
     try { fs.mkdirSync(dir, { recursive: true }); } catch { /* the log is a courtesy */ }
     const port = ctx.port();
     const record = ctx.runtimeRecord();
-    const childEnv = { ...process.env,
-      CARMAR_PORT: String(port), CARMAR_WAIT_PORT: "30",
+    const readyFile = path.join(dir, `handoff-ready-${port}-${process.pid}-${secureToken(8)}.json`);
+    try { fs.rmSync(readyFile, { force: true }); } catch { /* not there */ }
+    // Canonical names, mirrored at the spawn so an installed Beatrina-era host
+    // (one that reads only CARMAR_*) starts as a successor too.
+    const childEnv = unsetEnv({ ...process.env,
+      BEATRINA_PORT: String(port), BEATRINA_WAIT_PORT: "30",
       // A successor that quietly moved to a free port would leave the page
       // polling a dead one; strict means it refuses and its log says why.
-      CARMAR_PORT_STRICT: "1",
-      CARMAR_FILE_LAUNCH_CAP: h.cap, CARMAR_HANDOFF_FROM: ctx.kernelBuild,
-      CARMAR_SESSION_TITLE: record.title || "",
-      CARMAR_SESSION_DOCUMENTS: encodeSessionDocuments(ctx.sessionDocuments?.() || []),
+      BEATRINA_PORT_STRICT: "1",
+      BEATRINA_FILE_LAUNCH_CAP: h.cap, BEATRINA_HANDOFF_FROM: ctx.kernelBuild,
+      BEATRINA_HANDOFF_READY: readyFile,
+      BEATRINA_SESSION_TITLE: record.title || "",
+      BEATRINA_SESSION_DOCUMENTS: encodeSessionDocuments(ctx.sessionDocuments?.() || []),
       // Only a token travels, never a path; the successor re-checks it.
-      CARMAR_RESUME_TOKEN: h.resume || "" };
-    if (record.listen) childEnv.CARMAR_LISTEN = "1"; else delete childEnv.CARMAR_LISTEN;
+      BEATRINA_RESUME_TOKEN: h.resume || "" }, "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.
+    let logFrom = 0;
+    try { logFrom = fs.statSync(logPath).size; } catch { logFrom = 0; }
     let out = "ignore";
-    try { out = fs.openSync(path.join(dir, `kernel-handoff-${port}.log`), "a"); } catch { out = "ignore"; }
+    try { out = fs.openSync(logPath, "a"); } catch { out = "ignore"; }
     let child = null;
     try {
       const { cmd, args } = successorCommand();
-      child = spawn(cmd, args, { env: childEnv, stdio: ["ignore", out, out], detached: true });
+      child = spawn(cmd, args, { env: mirrorEnv(childEnv), stdio: ["ignore", out, out], detached: true });
       child.unref();
+      child.on("error", () => { /* reported through exitCode / the deadline below */ });
     } catch { child = null; }
     if (typeof out === "number") { try { fs.closeSync(out); } catch { /* closed */ } }
-    if (!child || !child.pid) { handoffAbandon(ctx, "The installed CarmaR could not be started."); return false; }
+    if (!child || !child.pid) return { ok: false, error: "The installed Beatrina could not be started.", reason: "spawn" };
     audit("session-upgrade-spawned", { to: h.to, pid: child.pid, mode: h.mode });
-    // Spawn first, kill second: the worker's whole process GROUP goes down only
-    // once the successor exists, so a failed spawn leaves the session untouched.
-    // The group kill reaches the shell grandchildren a hung R never signals.
+
+    // The sentence a failed successor said about itself: its own "Beatrina …" line, else the first
+    // error line, else the last line. A stack's LAST line is a frame of Node's loader, not a reason.
+    const logTail = () => {
+      let lines = [];
+      try { lines = fs.readFileSync(logPath).subarray(logFrom).toString("utf8").split("\n").map((l) => l.trim()).filter(Boolean); } catch { return ""; }
+      return lines.find((l) => /^Beatrina\b/.test(l)) || lines.find((l) => /Error\b/.test(l)) || lines[lines.length - 1] || "";
+    };
+    const deadline = Date.now() + prepareSeconds() * 1000;
+    try {
+      while (Date.now() < deadline) {
+        let said = null;
+        try { said = JSON.parse(fs.readFileSync(readyFile, "utf8")); } catch { said = null; }
+        if (said && said.ok === true) {
+          audit("session-upgrade-prepared", { to: h.to, pid: child.pid, build: said.build || "" });
+          return { ok: true, child };
+        }
+        if (said && said.ok === false) {
+          killSuccessor(child);
+          return { ok: false, error: `The installed Beatrina ${h.to} could not take over this session: ${said.error || "it refused to start"}. This session is untouched.`, reason: "successor" };
+        }
+        if (child.exitCode !== null || child.signalCode !== null) {
+          const tail = logTail();
+          return { ok: false, error: `The installed Beatrina ${h.to} exited before it was ready${tail ? ` (${tail.slice(0, 300)})` : ""}. This session is untouched.`, reason: "successor" };
+        }
+        await new Promise((r) => setTimeout(r, 100));
+      }
+      killSuccessor(child);
+      return { ok: false, error: `The installed Beatrina ${h.to} did not say it was ready within ${prepareSeconds()} seconds. This session is untouched.`, reason: "successor-timeout" };
+    } finally {
+      try { fs.rmSync(readyFile, { force: true }); } catch { /* gone */ }
+    }
+  };
+
+  /** Phase 2: stop the workers and leave; the prepared successor is waiting for the port. */
+  const handoffRetire = (ctx) => {
+    // The worker's whole process GROUP goes down only once the successor has
+    // proved it can run. The group kill reaches the shell grandchildren a hung R never signals.
     const planes = ctx.plane.planes ? [...ctx.plane.planes.values()] : [ctx.plane];
     for (const pl of planes) {
       pl.expectedExit = true;
@@ -342,7 +473,6 @@ export function createPlane({ root, env, audit }) {
     }
     // Deferred, so the reply and the broadcast flush before the sockets close.
     setTimeout(() => ctx.shutdown("session handoff"), 300);
-    return true;
   };
 
   return {
@@ -360,7 +490,7 @@ export function createPlane({ root, env, audit }) {
     agentRefusalFor: (op) => ({
       session_list: "Agents cannot list the user's sessions.",
       r_versions: "Agents cannot list or choose R installations.",
-      session_upgrade: "Agents cannot restart the user's session into another CarmaR.",
+      session_upgrade: "Agents cannot restart the user's session into another Beatrina.",
       session_restart: "Agents cannot restart the user's session.",
       "session-new": "Agents cannot start a session for the user.",
     })[op] || null,
@@ -379,15 +509,24 @@ export function createPlane({ root, env, audit }) {
         return reply({ error: "Only the local notebook page may ask this." });
       }
       if (HANDOFF_OPS.includes(cmd.type)) {
-        return reply(handoffBegin(ctx, cmd.type === "session_restart" ? "restart" : "upgrade", cmd.force === true, keepTokenOk(cmd.resume) ? cmd.resume : null));
+        return handoffBegin(ctx, cmd.type === "session_restart" ? "restart" : "upgrade", cmd.force === true, keepTokenOk(cmd.resume) ? cmd.resume : null)
+          .then(reply, (e) => { handoff = null; reply({ ok: false, error: `The session restart failed: ${e.message}`, reason: "internal" }); });
       }
       if (cmd.type === "session_list") {
         const own = ctx.port();
         const recs = runtimeRecords(env);
         return Promise.all(recs.map(async (r) => {
           const isThis = r.port === own;
+          const h = isThis ? null : await healthOf(r.url);
+          // The fields the page reads (port, url, title, pid, alive, this) as they were; beside them,
+          // ADDITIVE, what the record says a session is (`app`, `document`, `documents`, `started`)
+          // and what its /health says it runs (`kernel_build`) — the same rows `beatrina status`
+          // and the menu describe a session by (docs/launch-menu-plan.md L1).
           return { port: r.port, url: String(r.url), title: r.title ?? "",
-            pid: r.pid ?? null, alive: isThis ? true : await healthy(r.url), this: isThis };
+            pid: r.pid ?? null, alive: isThis ? true : h != null, this: isThis,
+            app: typeof r.app === "string" ? r.app : "", document: typeof r.document === "string" ? r.document : "",
+            documents: typeof r.documents === "string" ? r.documents : "", started: typeof r.started === "string" ? r.started : "",
+            kernel_build: isThis ? ctx.kernelBuild : (h && typeof h.kernel_build === "string" ? h.kernel_build : "") };
         })).then((sessions) => reply({ sessions }))
           .catch((e) => reply({ error: e.message }));
       }
@@ -405,7 +544,11 @@ export function createPlane({ root, env, audit }) {
       if (cmd.type === "session-new") {
         audit("session-new", { id: cmd.id });
         return startSibling(ctx).then((started) => {
-          if (!started) return reply({ error: "Could not start another session." });
+          if (!started || started.error) {
+            audit("session-new-failed", { detail: started ? started.error : "no answer" });
+            return reply({ error: started ? started.error : "Could not start another session.", log: started ? started.log || "" : "" });
+          }
+          audit("session-new-started", { port: started.port, launch: started.launch });
           return reply({ port: started.port, url: started.url });
         }).catch((e) => {
           audit("session-new-failed", { detail: e.message });
@@ -425,8 +568,9 @@ export function createPlane({ root, env, audit }) {
         return true;
       }
       const restart = pathname === "/session/restart";
-      const begun = handoffBegin(ctx, restart ? "restart" : "upgrade", restart && ctx.queryParam(req, "force") === "1");
-      ctx.respond(res, begun.ok === true ? 200 : 409, "application/json", ctx.enc(begun));
+      handoffBegin(ctx, restart ? "restart" : "upgrade", restart && ctx.queryParam(req, "force") === "1")
+        .catch((e) => { handoff = null; return { ok: false, error: `The session restart failed: ${e.message}`, reason: "internal" }; })
+        .then((begun) => ctx.respond(res, begun.ok === true ? 200 : 409, "application/json", ctx.enc(begun)));
       return true;
     },
 

package/host/planes/settings.mjs

@@ -28,9 +28,9 @@ const AGENT_WHY = Object.freeze({
   // secret, but because handing back the confinement root, the audit-log path
   // and whether AI-text logging is on is a MAP OF THE DEPLOYMENT'S CONTROLS,
   // given to a process whose entire premise is that it is not the user.
-  settings_get: "Agents cannot read CarmaR's settings.",
-  settings_set: "Agents cannot change CarmaR's settings.",
-  settings_reset: "Agents cannot reset CarmaR's settings.",
+  settings_get: "Agents cannot read Beatrina's settings.",
+  settings_set: "Agents cannot change Beatrina's settings.",
+  settings_reset: "Agents cannot reset Beatrina's settings.",
 });
 
 export function createPlane({ audit, settings } = {}) {
@@ -48,7 +48,7 @@ export function createPlane({ audit, settings } = {}) {
       }
       if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
         audit?.("settings-refused", { reason: "class", detail: cmd.type, class: rec.class || "unknown" });
-        reply({ ok: false, reason: "class", error: "Only the notebook page may read or change CarmaR's settings." });
+        reply({ ok: false, reason: "class", error: "Only the notebook page may read or change Beatrina's settings." });
         return undefined;
       }
       // An unauthenticated shared kernel has no "the user" whose home directory

package/host/planes/terminal.mjs

@@ -2,7 +2,7 @@
 //
 // A port of `term_open`, `term_input`, `term_close`, `term_owned`,
 // `term_shell` and `pump_terms` in spike/serve.R, plus `term_resize`, which
-// carmapy added (`../carmar-python/docs/kernel-protocol.md` §3: "R only sizes
+// carmapy added (`docs/python-kernel-records/kernel-protocol.md` §3: "R only sizes
 // at open"). Both are served here; a page that never resizes behaves exactly
 // as it does against serve.R.
 //
@@ -16,7 +16,7 @@
 //     `exec` door the MCP plane refuses, wearing a prompt.
 //
 // What the shell can do is what the user can do; this grants nothing new and
-// is audited like every other door. `CARMAR_NO_TERMINAL=1` refuses it BY
+// is audited like every other door. `BEATRINA_NO_TERMINAL=1` refuses it BY
 // NAME, with the reason, rather than dropping the frame — a dropped frame
 // reads as a hang, and lib/terminal.js already renders `event: "refused"`.
 //
@@ -30,6 +30,9 @@ 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;
 const TERM_INPUT_MAX = 65536;
@@ -122,12 +125,13 @@ 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);
 
   const enc = (o) => JSON.stringify(o);
   const send = (rec, id, fields) => { try { rec.ws.send(enc({ type: "term", id, ...fields })); } catch { /* the page is gone */ } };
-  const turnedOff = () => env("CARMAR_NO_TERMINAL") === "1";
+  const turnedOff = () => env("BEATRINA_NO_TERMINAL") === "1";
 
   /** Only the page that opened a terminal may type into it, resize it or close it. */
   const owned = (rec, id) => {
@@ -161,8 +165,8 @@ export function createPlane({ env, audit }) {
       audit("term-refused", { detail: why });
       send(rec, "", { event: "refused", error: why });
     };
-    if (turnedOff()) return refuse("The terminal is turned off on this kernel (CARMAR_NO_TERMINAL=1).");
-    // serve.R refuses Windows outright ("CarmaR does not provide a pty on
+    if (turnedOff()) return refuse(`The terminal is turned off on this kernel (${envSetName(env, "NO_TERMINAL")}=1).`);
+    // serve.R refuses Windows outright ("Beatrina does not provide a pty on
     // Windows yet"), because processx has none there. node-pty ships ConPTY
     // prebuilds, so the refusal is no longer true by construction — the
     // platform is not asked, the loader is, and it says so if the prebuild
@@ -170,9 +174,9 @@ export function createPlane({ env, audit }) {
     const mine = [...terms.values()].filter((t) => t.rec === rec);
     if (mine.length >= MAX_TERMS) return refuse(`${mine.length} terminals are already open on this page.`);
     // node-pty first; with none (every installed R package: it is a native
-    // module) the pipe terminal in pipe-term.mjs. CARMAR_TERMINAL_PTY=0 forces
+    // module) the pipe terminal in pipe-term.mjs. BEATRINA_TERMINAL_PTY=0 forces
     // the pipe, which is how a machine that HAS node-pty tests the other rung.
-    if (!loaded) loaded = env("CARMAR_TERMINAL_PTY") === "0" ? { pty: null, error: "CARMAR_TERMINAL_PTY=0" } : loadPty(audit);
+    if (!loaded) loaded = env("BEATRINA_TERMINAL_PTY") === "0" ? { pty: null, error: `${envSetName(env, "TERMINAL_PTY")}=0` } : loadPty(audit);
 
     const cols = clamp(cmd.cols, 20, 400, 100);
     const rows = clamp(cmd.rows, 5, 200, 30);
@@ -180,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
@@ -190,15 +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: { ...process.env, TERM: "dumb", COLUMNS: String(cols), LINES: String(rows), CARMAR_PORT: String(ctxPort()) } })
-        : loaded.pty.spawn(argv.file, argv.args, {
-          name: "xterm-256color", cols, rows, cwd: real,
-          env: { ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor",
-            COLUMNS: String(cols), LINES: String(rows), CARMAR_PORT: String(ctxPort()) },
-        });
+          env: mirrorEnv({ ...process.env, TERM: "dumb", 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;
@@ -216,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 });
@@ -231,7 +247,7 @@ export function createPlane({ env, audit }) {
     // own words and a suite pins them (test/terminal.test.mjs).
     agentRefused: [],
     // serve.R advertises no terminal verb in ready.commands; neither does this.
-    // A kernel with CARMAR_NO_TERMINAL=1 still answers the op — with a refusal
+    // A kernel with BEATRINA_NO_TERMINAL=1 still answers the op — with a refusal
     // that names the reason, which is what the pane renders.
     commands: [],
     capabilities: [],