beatrina 0.9.83 → 1.0.1

package/host/main.mjs

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

package/host/planes/analyze.mjs

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

package/host/planes/jobs.mjs

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

package/host/planes/sessions.mjs

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

package/host/quarto.mjs

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

package/host/server.mjs

@@ -82,6 +82,13 @@ export const SAFE_HEADERS = Object.freeze({
 const scalarChr = (x) => typeof x === "string" && x.length > 0;
 const enc = (obj) => JSON.stringify(obj);
 
+/**
+ * The version of the `host-ready` handshake (plans/getting_rid_of_R.md K2). A
+ * page reads `host_protocol` to know which fields it may rely on; it never
+ * replaces `protocol`, which is the worker wire's and gates compatibility.
+ */
+export const HOST_READY_PROTOCOL = 1;
+
 /** Bytes no caller can predict — the OS CSPRNG, never Math.random. */
 export function secureToken(n = 32) {
   const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
@@ -91,6 +98,38 @@ export function secureToken(n = 32) {
   return out;
 }
 
+/**
+ * INSTALL AS AN APP (a Progressive Web App), for whoever wants it: the browser
+ * offers "Install Beatrina Note" (Chrome, Edge) or File ▸ Add to Dock (Safari) and
+ * the page opens in a window of its own — the same page, from the same host,
+ * locally or from a server. Added to the SERVED page only, like the session
+ * stamp: the file on disk is unchanged, so a notebook double-clicked from Finder
+ * behaves exactly as before. The page's CSP admits `manifest-src 'self'` and
+ * nothing more for it — no service worker; Chromium reports the page
+ * installable without one (test/pwa.browser.mjs).
+ */
+export const PWA_HEAD = '<link rel="manifest" href="/manifest.webmanifest">'
+  + '<link rel="icon" type="image/png" sizes="192x192" href="/pwa/icon-192.png">'
+  + '<link rel="apple-touch-icon" href="/pwa/icon-192.png">'
+  + '<meta name="theme-color" content="#1f2937">';
+
+/** The manifest the installed app is made from; `start_url` is the page this host serves. */
+export function pwaManifest(app = "beatrina") {
+  // "Beatrina Note": the page installed from the browser, told apart from Beatrina, the desktop
+  // window (`beatrina app`), in the Dock, the Start menu and the app list.
+  const name = app && app !== "beatrina" ? `${app} Note` : "Beatrina Note";
+  return JSON.stringify({
+    name, short_name: name, description: "A Quarto writer that also runs R, Python and JavaScript.",
+    id: "/", start_url: "/", scope: "/", display: "standalone",
+    background_color: "#ffffff", theme_color: "#1f2937",
+    icons: [
+      { src: "/pwa/icon-192.png", sizes: "192x192", type: "image/png", purpose: "any" },
+      { src: "/pwa/icon-512.png", sizes: "512x512", type: "image/png", purpose: "any" },
+    ],
+  });
+}
+const PWA_ICONS = Object.freeze({ "/pwa/icon-192.png": "icon-192.png", "/pwa/icon-512.png": "icon-512.png" });
+
 /**
  * Stamp the served HTML with this session's identity, once per load — and, for a product other
  * than Beatrina (`app`, BEATRIX_APP_ID: "beatrina"), with which product served it, so the page's
@@ -100,7 +139,7 @@ export function secureToken(n = 32) {
  */
 export function stampSession(html, stamp, app = "") {
   const product = String(app || "").replace(/[^A-Za-z0-9.]/g, "");
-  const meta = `<meta name="beatrina-session" content="${stamp}">${product && product !== "beatrina" ? `<meta name="beatrina-app" content="${product}">` : ""}`;
+  const meta = `<meta name="beatrina-session" content="${stamp}">${product && product !== "beatrina" ? `<meta name="beatrina-app" content="${product}">` : ""}${PWA_HEAD}`;
   let m = html.match(/<head\b[^>]*>/);
   if (!m) m = html.match(/<html\b[^>]*>/);
   if (!m) return meta + html;
@@ -153,6 +192,33 @@ export function createHostServer(opts) {
     } catch { return payload; }
   };
   plane.on("broadcast", (payload) => { const out = strandedNotice(payload); sockets.forEach((r) => r.ws.send(out)); });
+
+  // ── host-ready: the HOST's readiness, independent of every engine (K2) ────
+  // Sent to every socket on open, BEFORE any engine's frame, and again when an
+  // engine's row changes. It carries the host's own verbs — the ones planes
+  // answer with no engine at all (files, journal, settings, …) — so a page
+  // with no R still learns that it may save and recover. It is DISCLOSURE:
+  // who may call a verb is still decided per frame below (gatewayCommands,
+  // AGENT_REFUSED, PAGE_ONLY_CLASSES), never by what this frame lists (K2c).
+  // R's legacy `ready` keeps carrying the same verbs while R runs, so a page
+  // older than this frame still connects to a host that has R (K2).
+  const hostReadyFrame = () => {
+    const newerOnNpm = opts.updateAvailable ? opts.updateAvailable() : null;
+    return enc({
+      type: "host-ready", host_protocol: HOST_READY_PROTOCOL, host: "beatrix", app: opts.app || "beatrina",
+      protocol: opts.protocol, kernel_build: opts.kernelBuild,
+      installed_build: typeof opts.installedBuild === "function" ? opts.installedBuild() : null,
+      ...(newerOnNpm ? { update_available: newerOnNpm } : {}),
+      commands: gatewayCommands(["session_restart", ...commands], gatewayMode),
+      capabilities,
+      // The routing default for a request that names no engine — NOT a
+      // primary: nothing waits for it (K2).
+      default_engine: plane.primaryName || null,
+      engines: typeof plane.engineNames !== "undefined" ? plane.engineNames : [],
+      engine_status: typeof plane.engineRows === "function" ? plane.engineRows() : [],
+    });
+  };
+  plane.on("engines-changed", () => { const out = hostReadyFrame(); sockets.forEach((r) => r.ws.send(out)); });
   // A restore's report is about every object in the session: pages only, never an agent or a native client.
   plane.on("broadcast-pages", (payload) => sockets.filter((r) => PAGE_ONLY_CLASSES.includes(r.class) && r.role === "page").forEach((r) => r.ws.send(payload)));
 
@@ -267,7 +333,9 @@ export function createHostServer(opts) {
       // CORS is granted HERE AND ONLY HERE, so a file page probing for its
       // kernel can read the answer. Booleans and versions only.
       return respond(res, 200, "application/json", enc({
-        ok: true, worker: plane.alive, pending_open: state.pendingOpen != null,
+        // `host_ready`: this host speaks the host-ready handshake, so a probing page need not
+        // wait for `worker` — which is only "R is running", and false forever with no R.
+        ok: true, host_ready: HOST_READY_PROTOCOL, worker: plane.alive, pending_open: state.pendingOpen != null,
         r: rVersion(), started: startedSeconds, protocol: opts.protocol,
         kernel_build: opts.kernelBuild, installed_build: opts.installedBuild(),
         pages: pageRecs().length,
@@ -300,6 +368,17 @@ export function createHostServer(opts) {
     for (const pl of planes) {
       if (typeof pl.http === "function" && pl.http(req, res, pathname, ctx) === true) return undefined;
     }
+    if (pathname === "/manifest.webmanifest") {
+      return respond(res, 200, "application/manifest+json", pwaManifest(opts.app || "beatrina"));
+    }
+    if (Object.prototype.hasOwnProperty.call(PWA_ICONS, pathname)) {
+      // host/pwa beside the kernel directory's parent — the host's own root, in a
+      // checkout and in the npm package alike (never import.meta: host/main.mjs PACKAGING).
+      const icon = path.join(opts.here, "..", "host", "pwa", PWA_ICONS[pathname]);
+      let bytes;
+      try { bytes = fs.readFileSync(icon); } catch { return respond(res, 404, "text/plain", "not found"); }
+      return respond(res, 200, "image/png", bytes);
+    }
     if (pathname === "/" || pathname === "/spike") {
       const page = pathname === "/spike" ? path.join(opts.here, "index.html") : (opts.pagePath() || path.join(opts.here, "index.html"));
       let html;
@@ -333,6 +412,8 @@ export function createHostServer(opts) {
       ws.onPong(() => { rec.lastSeen = Date.now(); });
       state.everConnected = true;
       audit("socket-open", { sockets: sockets.length, class: rec.class, user: rec.user });
+      // The host first: the page may save, recover and edit on this alone.
+      ws.send(hostReadyFrame());
       // The engine announced itself long before this page connected; replay
       // it — and every other engine that has since started, each under its own
       // `engine-ready` (host/engine-pool.mjs replay()).

package/host/worker-plane.mjs

@@ -324,9 +324,15 @@ export class WorkerPlane extends EventEmitter {
     this.audit("restart", { keep: keepTokenOk(resume) });
     this.failRoutes(`${this.label} was restarted — this request was abandoned.`);
     this.expectedExit = true;
+    // Not ready from THIS moment, not after the old process is gone: a command
+    // that arrives while the old engine is being stopped would otherwise be
+    // queued on it and wiped by resetSession() below with no reply at all. With
+    // `hello` cleared the pool holds it until the fresh engine's ready
+    // (EnginePool.whenEngineReady) — measured by test/stop.test.mjs, whose probe
+    // landed in exactly that window once host-ready moved R's ready off frame 0.
+    this.hello = null;
     if (this.engine) await this.engine.stop(1000);
     this.resetSession();
-    this.hello = null;
     this.recovering = false;
     this.restartAttempts = 0;
     this.gaveUp = false;