beatrina 0.8.6

package/host/main.mjs

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+// main.mjs — `beatrix`: start the host on a loopback port and print where it is.
+//
+// Prints ONE line of JSON on stdout — {"url": ..., "file": ...} — exactly as
+// spike/serve.R does, so every launcher, fixture and agent that reads that
+// line works unchanged. Everything else goes to stderr.
+//
+// Env (the CARMAR_* names are the WIRE the page and its launchers speak; they
+// are kept on purpose — renaming them is WP7's job, with the launchers):
+//   CARMAR_PORT (4747), CARMAR_PORT_STRICT=1, CARMAR_BIND, CARMAR_HOSTS …
+//   (see deployment.mjs), CARMAR_RSCRIPT, CARMAR_KERNEL_BUILD,
+//   CARMAR_INSTALLED_BUILD, CARMAR_LOG, CARMAR_RUNTIME_DIR,
+//   CARMAR_NO_RUNTIME_FILE=1, CARMAR_LINGER, CARMAR_BOOT_GRACE,
+//   CARMAR_WORKER_DEADLINE_SCALE, CARMAR_WORKER_RESPAWN_MAX, CARMAR_OPEN_FILE,
+//   CARMAR_HOST_ROOT, CARMAR_KERNEL_DIR (WP7: where the files are when the
+//   host is not running from a source checkout — see hostRoot/kernelDir).
+//
+// PACKAGING (docs/packaging.md). Node's Single Executable Application runs its
+// main script as CommonJS — `embedderRunCjs`, measured on Node 25.5.0, an ESM
+// blob dies with "Cannot use import statement outside a module" — so this file
+// must survive `esbuild --format=cjs`. That costs three rules, and they are why
+// the body below is a function rather than a script:
+//   * no top-level `await` (esbuild refuses it outright in cjs output),
+//   * no bare `import.meta.url` on a path a packaged binary walks, because cjs
+//     output leaves it empty — `moduleDir()` is the one place that reads it, and
+//   * the planes are STATIC imports, not `await import(variable)`: a bundler
+//     cannot follow a dynamic specifier, so a packaged binary would boot with
+//     no planes at all and refuse every family by name.
+
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import sea from "node:sea";
+import { fileURLToPath } from "node:url";
+import { carmarDeployment } from "./deployment.mjs";
+import { REngine, detectRscript } from "./engine-r.mjs";
+import { PythonEngine, detectPython } from "./engine-python.mjs";
+import { JsEngine, detectNode } from "./engine-js.mjs";
+import { EnginePool } from "./engine-pool.mjs";
+import { createHostServer, secureToken } from "./server.mjs";
+import { createSettings } from "./settings.mjs";
+// ── planes (one line per family; see the seam in server.mjs) ───────────────
+// Each work package registers its module here and nowhere else. Keep the
+// list alphabetical by file so two packages landing at once merge cleanly.
+// Static imports on purpose — see PACKAGING above.
+import * as planeAiStore from "./planes/ai-store.mjs";
+import * as planeAi from "./planes/ai.mjs";
+import * as planeAnalyze from "./planes/analyze.mjs";
+import * as planeCite from "./planes/cite.mjs";
+import * as planeLatex from "./planes/latex.mjs";
+import * as planeFiles from "./planes/files.mjs";
+import * as planeJobs from "./planes/jobs.mjs";
+import * as planeJournal from "./planes/journal.mjs";
+import * as planeMcp from "./planes/mcp.mjs";
+import * as planePair from "./planes/pair.mjs";
+import * as planePlugins from "./planes/plugins.mjs";
+import * as planeSessions from "./planes/sessions.mjs";
+import * as planeSettings from "./planes/settings.mjs";
+import * as planeTerminal from "./planes/terminal.mjs";
+import * as planeTestFile from "./planes/test-file.mjs";
+import * as planeUpdate from "./planes/update.mjs";
+import { appId } from "./user-dirs.mjs";
+import { updateAvailable, updateRecordFile } from "./update-record.mjs";
+const PLANE_MODULES = [planeAiStore, planeAi, planeAnalyze, planeCite, planeFiles, planeJobs, planeJournal, planeLatex, planeMcp, planePair, planePlugins, planeSessions, planeSettings, planeTerminal, planeTestFile, planeUpdate];
+
+const env = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+
+/** Whether this process is a packaged single executable, asked once. */
+const packaged = (() => { try { return sea.isSea(); } catch { return false; } })();
+
+/** This module's own directory — "" when the cjs bundler emptied import.meta. */
+function moduleDir() {
+  const u = import.meta.url;
+  return typeof u === "string" && u.startsWith("file:") ? path.dirname(fileURLToPath(u)) : "";
+}
+
+/**
+ * Where the host's own files live.
+ *
+ * A source checkout answers from this module's location (host/.. = the repo).
+ * A PACKAGED binary has no module path on disk, so it answers from the folder
+ * it sits in — which is also the rule the page pin needs: `carmar_V<build>.html`
+ * beside the binary, exactly as spike/notebook-page.R puts it beside kernel/.
+ */
+function hostRoot() {
+  const dictated = env("CARMAR_HOST_ROOT").trim();
+  if (dictated) return path.resolve(dictated);
+  if (packaged) return path.dirname(process.execPath);
+  const mine = moduleDir();
+  if (mine) return path.resolve(mine, "..");
+  return path.dirname(process.execPath);
+}
+
+/**
+ * The directory holding the R kernel scripts and the build stamps.
+ *
+ * `spike/` in the repo; `kernel/` in every distribution, because that is what
+ * tools/ship/build-r-pkg.sh and tools/app/build-app.sh have always called it.
+ * Named by CARMAR_KERNEL_DIR when a launcher knows better.
+ */
+function kernelDir(base) {
+  const dictated = env("CARMAR_KERNEL_DIR").trim();
+  if (dictated) return path.resolve(dictated);
+  for (const name of ["spike", "kernel"]) {
+    if (fs.existsSync(path.join(base, name, "worker-boot.R"))) return path.join(base, name);
+  }
+  return path.join(base, "spike");
+}
+
+const root = hostRoot();
+const spike = kernelDir(root);
+
+// ── identity: protocol and build, read the way serve.R reads them ──────────
+function readProtocol() {
+  for (const p of [path.join(spike, "kernel-protocol"), path.join(root, "kernel.protocol")]) {
+    if (fs.existsSync(p)) {
+      const v = Number.parseInt(fs.readFileSync(p, "utf8").trim(), 10);
+      if (Number.isInteger(v) && v >= 1) return v;
+      throw new Error("Beatrina: the kernel protocol stamp is invalid.");
+    }
+  }
+  throw new Error("Beatrina: the kernel protocol stamp is missing.");
+}
+function sourceVersion() {
+  const f = path.join(root, "notebook.version.cjs");
+  if (!fs.existsSync(f)) return "unknown";
+  const m = fs.readFileSync(f, "utf8").match(/version\s*:\s*"([^"]+)"/);
+  return m ? m[1] : "unknown";
+}
+function readKernelBuild() {
+  const dictated = env("CARMAR_KERNEL_BUILD").trim();
+  if (dictated) return dictated;
+  const stamp = path.join(spike, "kernel-version");
+  if (fs.existsSync(stamp)) { const v = fs.readFileSync(stamp, "utf8").trim(); if (v) return v; }
+  return sourceVersion();
+}
+function installedBuild() {
+  const dictated = env("CARMAR_KERNEL_BUILD").trim();
+  if (dictated) return env("CARMAR_INSTALLED_BUILD").trim() || dictated;
+  const stamp = path.join(spike, "kernel-version");
+  if (fs.existsSync(stamp)) { const v = fs.readFileSync(stamp, "utf8").trim(); if (v) return v; }
+  return sourceVersion();
+}
+/**
+ * The ONE page a kernel of a given build serves: a pin, never a search.
+ *
+ * `spike/index.html` is the fallback, exactly as `notebook_page()` in
+ * spike/serve.R has one: a source checkout with nothing built still ANNOUNCES
+ * a page, and the suites that wait for that announcement (anything through
+ * test/fixtures/ai-e2e.mjs, which resolves on the `file` field) work without a
+ * build on both supervisors. Returning "" here made them time out on the host
+ * alone, which is a difference in the fixture's eyes and not in the design's.
+ */
+function notebookPage(build, { fallback = true } = {}) {
+  const wanted = `carmar_V${build}.html`;
+  // serve.R's pin (spike/notebook-page.R): beside the KERNEL directory, not the
+  // host's root — the two differ exactly when the kernel files are a staged or
+  // installed copy, which is the shape every upgrade has.
+  for (const p of [path.join(spike, "..", "dist", wanted), path.join(spike, "..", wanted)]) if (fs.existsSync(p)) return path.resolve(p);
+  if (!fallback) return "";
+  const dev = path.join(spike, "index.html");
+  return fs.existsSync(dev) ? dev : "";
+}
+/** "4.5.2" out of "R version 4.5.2 (2025-10-31)" — the only kernel that sends
+ *  a version without a `language_version` field is R, which sends this. */
+function rVersionOf(frame) {
+  const m = typeof frame.r === "string" ? frame.r.match(/R version (\S+)/) : null;
+  return m ? m[1] : "";
+}
+
+function notebookFileUrl(p, port, cap) {
+  const slashed = p.replace(/\\/g, "/");
+  const prefix = slashed.startsWith("/") ? "file://" : "file:///";
+  return `${prefix}${encodeURI(slashed)}#kernel=${port}${cap ? `&pair=${cap}` : ""}`;
+}
+
+// ── the port: a preference by default, a promise when asked ────────────────
+const portTaken = (p) => new Promise((resolve) => {
+  const s = net.connect({ port: p, host: "127.0.0.1" });
+  s.setTimeout(1000);
+  s.once("connect", () => { s.destroy(); resolve(true); });
+  s.once("error", () => resolve(false));
+  s.once("timeout", () => { s.destroy(); resolve(false); });
+});
+async function choosePort() {
+  let wanted = Number.parseInt(env("CARMAR_PORT", "4747"), 10);
+  if (!Number.isInteger(wanted) || wanted < 1024 || wanted > 65535) wanted = 4747;
+  if (!(await portTaken(wanted))) return wanted;
+  const waitS = Number(env("CARMAR_WAIT_PORT", "0"));
+  if (Number.isFinite(waitS) && waitS > 0) {
+    const deadline = Date.now() + waitS * 1000;
+    while (Date.now() < deadline) {                    // a wait is a loop
+      await new Promise((r) => setTimeout(r, 250));
+      if (!(await portTaken(wanted))) return wanted;
+    }
+  }
+  if (env("CARMAR_PORT_STRICT") === "1") {
+    console.error(`Beatrina refuses to start: CARMAR_PORT=${wanted} is already in use and CARMAR_PORT_STRICT=1 forbids moving to another port.`);
+    process.exit(2);
+  }
+  // Scan the session band, then let the OS pick.
+  for (let p = 4747; p <= 4947; p += 1) if (!(await portTaken(p))) return p;
+  return 0;
+}
+
+// The whole start-up is a FUNCTION, not a script: Node SEA runs its main as
+// CommonJS and esbuild refuses top-level await in cjs output (docs/packaging.md).
+// Nothing below may move back out to the module body.
+async function main() {
+  const protocol = readProtocol();
+  const kernelBuild = readKernelBuild();
+  // A newer Beatrina on npm, as the `beatrina` command last recorded it (host/update-record.mjs):
+  // the host reads that record and never the registry. Null for CarmaR's doors, which write none.
+  const newerOnNpm = () => updateAvailable({ file: updateRecordFile(appId()), current: kernelBuild });
+  // WP5a — the user's settings, and the administrator's managed policy.
+  // Created HERE, before the port and the deployment, because reading the managed
+  // file puts its values into the environment (serve.R does the same at its line
+  // 63): CARMAR_PORT, CARMAR_HOSTS and CARMAR_BIND may all come from it, and the
+  // env-wins-and-locks rule is only a single source of truth if the environment
+  // is already complete when the first subsystem reads it. Its errors refuse
+  // startup for the deployment's reason: a governance control that silently
+  // failed to apply is worse than one that does not come up.
+  // Which package's folders hold this host's data (host/user-dirs.mjs appId).
+  // Asked first: every store below keys on it, and a malformed value would
+  // otherwise surface as a crash inside whichever store touched it first.
+  try { appId(); } catch (e) {
+    console.error(`Beatrina refuses to start: ${e.message}`);
+    process.exit(2);
+  }
+  const settings = createSettings({ env });
+  if (settings.errors.length) {
+    for (const m of settings.errors) console.error(`Beatrina refuses to start: ${m}`);
+    process.exit(2);
+  }
+  const port = await choosePort();
+  const deployment = carmarDeployment(port, env);
+  if (deployment.errors.length) {
+    for (const m of deployment.errors) console.error(`Beatrina refuses to start: ${m}`);
+    process.exit(2);
+  }
+
+  // ── the audit log ──────────────────────────────────────────────────────────
+  const logPath = env("CARMAR_LOG");
+  const audit = (event, fields = {}) => {
+    if (!logPath) return;
+    const rec = { ts: new Date().toISOString(), pid: process.pid, event, ...fields };
+    try { fs.appendFileSync(logPath, `${JSON.stringify(rec)}\n`); } catch { /* logging must never take the host down */ }
+  };
+
+  // ── the engines and the pool ───────────────────────────────────────────────
+  // R is spawned at boot: the page will not leave "connecting" until a `ready`
+  // arrives. Every other engine starts the first time a chunk of its language
+  // runs (docs/host-plan.md §1) — an ipykernel nobody asked for is 1.3 seconds
+  // and tens of megabytes spent on a document that may hold no Python at all.
+  const workerPath = path.join(spike, "worker-boot.R");
+  const pythonWorker = path.join(root, "engines", "python", "worker.py");
+  const deadlineScale = Number(env("CARMAR_WORKER_DEADLINE_SCALE", "1")) > 0 ? Number(env("CARMAR_WORKER_DEADLINE_SCALE", "1")) : 1;
+  const respawnMax = Number.parseInt(env("CARMAR_WORKER_RESPAWN_MAX", "10"), 10) >= 1 ? Number.parseInt(env("CARMAR_WORKER_RESPAWN_MAX", "10"), 10) : 10;
+  const childEnv = {};
+  if (env("CARMAR_ROOT")) childEnv.CARMAR_ROOT = env("CARMAR_ROOT");
+  // share()/use(): the one explicit bridge between the session's languages.
+  // One 0700 directory per host, shared by every engine it starts, removed at
+  // exit. A value crosses only when a chunk names it (engines/js/worker.mjs,
+  // engines/r/handoff.R); nothing is ever copied implicitly.
+  const handoffDir = fs.mkdtempSync(path.join(os.tmpdir(), "beatrix-handoff-"));
+  fs.chmodSync(handoffDir, 0o700);
+  childEnv.CARMAR_HANDOFF_DIR = handoffDir;
+  process.on("exit", () => { try { fs.rmSync(handoffDir, { recursive: true, force: true }); } catch { /* best effort at exit */ } });
+  const planes = PLANE_MODULES.map((mod) => (mod.createPlane ? mod.createPlane({ root, spike, env, audit, settings }) : mod.default));
+  let servedCommands = [];
+
+  // Discovery runs BEFORE the first ready, not beside it: `engines` on that
+  // frame is what decides whether the page greys a {python} chunk, and a list
+  // that filled in half a second later would grey it and then quietly change
+  // its mind. Measured: 130–260 ms for the whole ladder.
+  const pythonFound = env("CARMAR_NO_PYTHON") === "1"
+    ? { available: false, detail: "The Python engine is disabled (CARMAR_NO_PYTHON=1).", searched: [] }
+    : await detectPython(process.env);
+  audit("engine-discovery", { engine: "python", available: pythonFound.available, detail: pythonFound.detail });
+  const jsWorker = path.join(root, "engines", "js", "worker.mjs");
+  const nodeFound = env("CARMAR_NO_JS") === "1"
+    ? { available: false, detail: "The JavaScript engine is disabled (CARMAR_NO_JS=1).", path: "", version: "" }
+    : !packaged && !fs.existsSync(jsWorker)
+      ? { available: false, detail: `This Beatrina does not carry the JavaScript worker (${jsWorker}).`, path: "", version: "" }
+      : detectNode({ env: process.env, packaged });
+  audit("engine-discovery", { engine: "js", available: nodeFound.available, detail: nodeFound.detail });
+
+  const ENGINE_SPECS = [
+    // WP5a — which R, and what the child inherits, come from the resolved
+    // settings (`rscript_path`, the child env). Read per spawn, never
+    // captured, so Restart R picks up a changed binary.
+    { name: "r", label: "R", boot: "eager", available: true,
+      factory: () => new REngine({
+        workerPath, handoffScript: path.join(root, "engines", "r", "handoff.R"),
+        rscript: detectRscript(settings.rscriptPreference()),
+        env: { ...childEnv, ...settings.childEnv() },
+      }) },
+    { name: "python", label: "Python", boot: "on-demand",
+      available: pythonFound.available, detail: pythonFound.detail,
+      version: pythonFound.version || "",
+      runtime: { path: pythonFound.path || "", why: pythonFound.why || "", searched: pythonFound.searched },
+      factory: () => new PythonEngine({ workerPath: pythonWorker, python: pythonFound.path, env: { ...childEnv, ...settings.childEnv() } }) },
+    { name: "js", label: "JavaScript", boot: "on-demand",
+      available: nodeFound.available, detail: nodeFound.detail, version: nodeFound.version || "",
+      runtime: { path: nodeFound.path || "", why: nodeFound.detail },
+      factory: () => new JsEngine({ workerPath: jsWorker, node: nodeFound.path, selfHosted: Boolean(nodeFound.selfHosted), env: { ...childEnv, ...settings.childEnv() } }) },
+  ];
+
+  // `/health r` before the worker is ready: ask the chosen Rscript once, in
+  // the background, so a launcher polling /health the instant the port answers
+  // sees the R it is about to get rather than "".
+  let rVersionHint = "";
+  {
+    const { execFile } = await import("node:child_process");
+    const rscript = detectRscript(settings.rscriptPreference());
+    if (rscript) execFile(rscript, ["--version"], { timeout: 5000 }, (err, stdout, stderr) => {
+      const m = String(stdout || "").concat(String(stderr || "")).match(/version (\d+\.\d+(?:\.\d+)?)/);
+      if (!err && m) rVersionHint = m[1];
+    });
+  }
+
+  const plane = new EnginePool({
+    specs: ENGINE_SPECS, audit, deadlineScale, respawnMax,
+    decorateReady: (frame, spec) => ({
+      ...frame,
+      protocol,
+      kernel_build: kernelBuild,
+      installed_build: installedBuild(),
+      ...(newerOnNpm() ? { update_available: newerOnNpm() } : {}),
+      // Per engine, never merged: `commands` is a contract about what THIS
+      // session answers, and lib/kernel-capability.js refuses an op by name on
+      // the strength of it. The host's own verbs are added to the primary's.
+      commands: [...new Set([
+        ...(Array.isArray(frame.commands) ? frame.commands : [frame.commands]).filter(Boolean),
+        ...(spec.name === plane.primaryName ? ["session_restart", ...servedCommands] : []),
+      ])],
+      features: Array.isArray(frame.features) ? frame.features : (frame.features ? [frame.features] : []),
+      engine: spec.name,
+      language: frame.language || spec.name,
+      language_version: frame.language_version || rVersionOf(frame) || null,
+      // EVERY engine this host has a runtime for, on every engine's frame.
+      engines: plane.engineNames,
+      engine_status: plane.engineRows(),
+      host: "beatrix",
+    }),
+  });
+  await plane.start();
+
+  // ── the server ─────────────────────────────────────────────────────────────
+  const bootAt = Date.now();
+  const fileLaunchCap = /^[A-Za-z0-9]{32}$/.test(env("CARMAR_FILE_LAUNCH_CAP")) ? env("CARMAR_FILE_LAUNCH_CAP") : secureToken(32);
+  delete process.env.CARMAR_FILE_LAUNCH_CAP;
+  let runtimeFile = "";
+  // `app` says whose session this is (BEATRIX_APP_ID): a double-clicked document
+  // is handed to a running session of the SAME app, never to CarmaR's.
+  const runtimeRecord = { url: "", file: "", port, pid: process.pid, started: new Date(bootAt).toISOString(), host: "beatrix", app: appId() };
+  // The document the session was started with, for `beatrina status`.
+  if (env("CARMAR_OPEN_FILE")) runtimeRecord.document = env("CARMAR_OPEN_FILE");
+  // A successor started by a handoff keeps the session's name.
+  const inheritedTitle = env("CARMAR_SESSION_TITLE").trim();
+  if (inheritedTitle) runtimeRecord.title = inheritedTitle.slice(0, 120);
+  const handoffFrom = env("CARMAR_HANDOFF_FROM").trim();
+  const writeRuntime = () => {
+    if (!runtimeFile) return false;
+    try { fs.writeFileSync(runtimeFile, JSON.stringify(runtimeRecord), { mode: 0o600 }); return true; } catch { return false; }
+  };
+  let stopping = false;
+  async function shutdown(reason) {
+    if (stopping) return;
+    stopping = true;
+    audit("stopping", { reason });
+    try { host.close(); } catch { /* closing */ }
+    // A plane may own children of its own (a job's process tree, a pty shell).
+    // They are spawned DETACHED so a group signal can reach what they started,
+    // which is exactly why nothing reaps them for us. serve.R kills the same
+    // trees in its exit handler; this is that handler.
+    for (const pl of planes) { try { await pl.shutdown?.(); } catch (e) { audit("plane-error", { plane: pl.name, detail: e.message }); } }
+    await plane.stop();
+    if (runtimeFile) {
+      try {
+        const rec = JSON.parse(fs.readFileSync(runtimeFile, "utf8"));
+        if (rec.pid === process.pid) fs.unlinkSync(runtimeFile);
+      } catch { /* not ours, or already gone */ }
+    }
+    process.exit(0);
+  }
+  const host = createHostServer({
+    deployment, plane, audit, protocol, kernelBuild, installedBuild, updateAvailable: newerOnNpm, bootAt, app: appId(), fileLaunchCap, here: spike, planes,
+    rVersionHint: () => rVersionHint,
+    pagePath: () => notebookPage(kernelBuild),
+    // The handoff asks for the PIN alone (spike/notebook-page.R): a successor
+    // with nothing but the development index to serve is worse than a stale
+    // session, so no fallback may answer "the installed build has a page".
+    notebookPage: (build) => notebookPage(build, { fallback: false }), notebookFileUrl: (p, prt, cap) => notebookFileUrl(path.resolve(p), prt, cap),
+    runtimeRecord: () => runtimeRecord, handoffFrom,
+    pendingOpen: env("CARMAR_OPEN_FILE") || null,
+    onShutdown: (reason) => shutdown(reason || "explicit Quit request"),
+    onPageTitle: (title) => {
+      // eslint-disable-next-line no-control-regex
+      // `null` is a page-title that named no settable title: the listener mark
+      // still goes (a listener with a page is an attached session), the title stays.
+      if (title !== null) {
+        const clean = String(title).replace(/[\x00-\x1f\x7f]/g, " ").replace(/["\\]/g, "'").trim().slice(0, 120);
+        if (clean) runtimeRecord.title = clean; else delete runtimeRecord.title;
+      }
+      delete runtimeRecord.listen;
+      writeRuntime();
+    },
+  });
+  servedCommands = host.commands;
+  // A plane that refuses to start (a policy permitting nothing) stops the whole
+  // host — and takes the worker it already spawned with it, because the exit
+  // handler at the foot of this file has not been registered yet.
+  for (const pl of planes) {
+    try { await pl.init?.(host.ctx); } catch (e) {
+      console.error(`Beatrina: plane ${pl.name} failed to start: ${e.message}`);
+      await plane.stop().catch(() => {});
+      process.exit(2);
+    }
+  }
+  await new Promise((resolve, reject) => {
+    host.server.once("error", reject);
+    host.server.listen(port, deployment.bind, resolve);
+  });
+  const boundPort = host.server.address().port;
+  const originOk = `http://${deployment.loopback ? deployment.bind : "127.0.0.1"}:${boundPort}`;
+  const url = `${originOk}/`;
+  const page = notebookPage(kernelBuild);
+  const fileUrl = page ? notebookFileUrl(path.resolve(page), boundPort, fileLaunchCap) : "";
+  runtimeRecord.url = url;
+  runtimeRecord.file = fileUrl;
+  if (env("CARMAR_LISTEN") === "1") runtimeRecord.listen = true;
+  if (env("CARMAR_NO_RUNTIME_FILE") !== "1") {
+    const dir = env("CARMAR_RUNTIME_DIR") || path.join(os.homedir(), ".carmar", "run");
+    try { fs.mkdirSync(dir, { recursive: true }); runtimeFile = path.join(dir, `kernel-${boundPort}.json`); } catch { runtimeFile = ""; }
+    if (runtimeFile && !writeRuntime()) runtimeFile = "";
+  }
+  audit("listening", { bind: deployment.bind, port: boundPort, loopback: deployment.loopback, require_origin: deployment.require_origin, host: "beatrix" });
+  audit("started", { port: boundPort, root: env("CARMAR_ROOT") });
+  process.stdout.write(`${JSON.stringify({ url, file: fileUrl })}\n`);
+  // --open: open the notebook FILE, as serve.R did for the double-click
+  // launchers. The kernel stays hidden plumbing. CARMAR_OPENER is the seam a
+  // test uses so nothing opens on a real desktop.
+  if (process.argv.slice(2).includes("--open")) {
+    const target = fileUrl || url;
+    const opener = String(process.env.CARMAR_OPENER || "");
+    try {
+      const child = path.isAbsolute(opener) ? spawn(opener, [target], { stdio: "ignore", detached: true })
+        : process.platform === "darwin" ? spawn("open", [target], { stdio: "ignore", detached: true })
+          : process.platform === "win32" ? spawn("cmd", ["/c", "start", "", target], { stdio: "ignore", detached: true })
+            : spawn("xdg-open", [target], { stdio: "ignore", detached: true });
+      child.on("error", () => { /* no desktop opener: the URL is printed above */ });
+      child.unref();
+    } catch { /* no desktop opener */ }
+  }
+
+  // ── lifetime ───────────────────────────────────────────────────────────────
+  // Idle shutdown is OPT-IN. A kernel nobody has EVER connected to gets the boot
+  // grace instead, so an unopened launch does not leave an R behind — unless the
+  // setting is explicitly 0, which says "headless, keep".
+  //
+  // WP5a — the clock reads the RESOLVED setting rather than CARMAR_LINGER, so the
+  // user's settings.json can turn it on and Settings can change it live. "Still
+  // at its default" is the exact rule serve.R's resolve_linger() uses for "never
+  // reap": an explicit 0 from the env or the file is a CHOICE and is honoured as
+  // one, which is why it is `source === "default"` and not `value === 0`. Read
+  // per tick, never captured, so a settings_set takes effect without a restart.
+  const bootGraceS = Number.isFinite(Number(env("CARMAR_BOOT_GRACE", "180"))) ? Number(env("CARMAR_BOOT_GRACE", "180")) : 180;
+  let idleSince = null;
+  setInterval(() => {
+    const lingerS = settings.lingerSeconds();
+    const everSeen = host.state.everConnected || host.state.heldAt != null;
+    const unopenedDefault = !everSeen && settings.lingerIsDefault();
+    if (!(lingerS > 0) && !unopenedDefault) { idleSince = null; return; }
+    plane.sweepParked?.(lingerS);
+    if (!everSeen && Date.now() - bootAt < bootGraceS * 1000) return;
+    const held = host.state.heldAt != null && Date.now() - host.state.heldAt < 30000;
+    // A plane that says it is busy holds the clock open. The case this exists
+    // for: a detached job three minutes into a check nobody is watching — the
+    // one moment a long task matters is the one an idle timer would end it.
+    const planeBusy = planes.some((pl) => pl.busy?.() === true);
+    const idle = host.sockets.length === 0 && plane.running.size === 0 && !held && !planeBusy;
+    if (!idle) { idleSince = null; return; }
+    if (idleSince == null) { idleSince = Date.now(); return; }
+    const grace = unopenedDefault ? bootGraceS : lingerS;
+    if (Date.now() - idleSince >= grace * 1000) {
+      const reason = unopenedDefault ? "unopened-launch" : "configured-idle-timeout";
+      audit("linger-shutdown", { grace, reason });
+      console.error(`Beatrina stopping: ${reason} (grace ${grace} seconds).`);
+      shutdown(reason);
+    }
+  }, 1000).unref();
+
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(sig, () => shutdown(sig));
+  process.on("exit", () => { try { if (typeof plane.killAll === "function") plane.killAll(); else if (plane.engine && plane.engine.alive) plane.engine.kill(); } catch { /* gone */ } });
+}
+
+main().catch((e) => {
+  console.error(`Beatrina failed to start: ${e && e.stack ? e.stack : e}`);
+  process.exit(2);
+});

package/host/planes/README.md

@@ -0,0 +1,41 @@
+# host/planes — one supervisor-answered family per module
+
+A plane is what `spike/serve.R` calls an allow-list family: the file ops, the
+journal, the AI store, jobs, the terminal, citations, plugins, sessions, the
+MCP plane. Each is one module here, registered by one line in `host/main.mjs`
+(`PLANE_MODULES`), and consulted by `host/server.mjs` before its not-yet
+refusals.
+
+```js
+export function createPlane({ root, spike, env, audit }) {
+  return {
+    name: "files",
+    ops: ["files", "readfile", …],          // the frames this plane answers
+    agentRefused: ["writefile", …],          // subset an mcp-role socket may not send
+    agentRefusalFor: (op) => "…",            // that op's OWN sentence (serve.R gives each one)
+    commands: ["files", "readfile", …],      // advertised in ready.commands — only what is served
+    capabilities: ["document-journal-v1"],  // added to /health capabilities
+    async init(ctx) {},                      // once, before listen
+    handle(cmd, rec, ctx, rawMessage) {},    // one frame; reply with rec.ws.send(ctx.enc({...}))
+    http(req, res, pathname, ctx) {},        // return true when handled
+    onOpen(rec, ctx) {}, onClose(rec, ctx) {},
+    busy() {},                               // true holds the idle clock open
+    async shutdown() {},                      // the kernel is going: reap your children
+  };
+}
+```
+
+`busy()` and `shutdown()` are read by `host/main.mjs`. A plane that spawns a
+child spawns it DETACHED (so a group signal can reach what the child started),
+which is exactly why nothing reaps it for us: `shutdown()` is where that is
+done, and it is the counterpart of serve.R's exit handler.
+
+`ctx` carries `deployment`, `plane` (the worker plane), `audit`, `sockets`,
+`approvals`, `state`, `enc`, `pageRecs`, `socketClass`, `port()`, `respond`,
+`reject`, `controlRejection`, `queryParam`, `broadcast`, `installedBuild`,
+`kernelBuild`, `fileLaunchCap`, `sessionStamp`.
+
+Rules: a page-only op checks `rec.class` against `PAGE_ONLY_CLASSES`
+(served/file/local) — role is an honour system, class is what the upgrade gate
+proved. Records that must not be re-encoded travel as strings. No dependency
+without a stated reason (`node-pty` for the terminal is the first).