beatrina 0.8.6

package/host/planes/jobs.mjs

@@ -0,0 +1,704 @@
+// jobs.mjs — development jobs: the THIRD kind of child process.
+//
+// A port of spike/jobs.R (the pure decision) and of everything named `job_*`,
+// `jobs_running`, `pump_jobs`, `prune_jobs`, `job_broadcast`, `job_emit`,
+// `job_log`, `job_snapshot`, `output_cap_*` and `/job-output` in spike/serve.R.
+// The CHILD is spike/job-run.R, spawned UNCHANGED: it stamps its own ids and
+// speaks the same sentinel-framed wire the worker does, so host/engine-r.mjs's
+// REngine (in batch mode) and LineFramer are reused rather than reinvented.
+//
+// Why a job is its own process, kept from the R:
+//   · it never consumes the interactive worker — a four-minute check would
+//     take the user's variables with it and make Stop a lie for the duration;
+//   · it is DETACHED: frames are BROADCAST to every page (the page that
+//     pressed Test may be gone), the log is BUFFERED so a page that reloads
+//     mid-check catches up, and a running job holds the idle clock open;
+//   · it carries no session identity, which is what makes a third evaluating
+//     child safe at all (the header of spike/job-run.R).
+//
+// THE WIRE NEVER CARRIES CODE. The browser sends a task NAME out of a closed
+// vocabulary plus a target; this file decides whether that pair is runnable
+// and the host builds the argument vector. Every option reaches the child
+// through its ENVIRONMENT, where `Sys.getenv()` cannot parse it.
+//
+// Two decisions that look like details and are not:
+//   · `job_open` names a JOB, never a path. The host opens the path IT
+//     recorded from the child's own `output` frame; a path from the wire
+//     would be "open any file on this machine" wearing a helpful label.
+//   · a child frame is BROADCAST AS BYTES (`__raw`), never re-encoded — the
+//     frame-fidelity rule, which is also why job-run.R stamps its own id.
+
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { REngine } from "../engine-r.mjs";
+import { killProcessTree } from "./proc-tree.mjs";
+
+// ── the vocabulary ──────────────────────────────────────────────────────────
+//
+// Every task declares WHAT IT ACTS ON, and that field is why this is a table
+// and not a list of names: six tasks act on a package root, `render` and
+// `latex` act on a single document, which has no DESCRIPTION and never will.
+// `pkg` is what the task needs INSTALLED, carried so the child can say so in
+// words; `render` depends on the document, so it carries null.
+export const JOB_TASKS = Object.freeze({
+  load: { label: "Load", running: "Loading", target: "package", pkg: "pkgload" },
+  document: { label: "Document", running: "Documenting", target: "package", pkg: "devtools" },
+  test: { label: "Test", running: "Testing", target: "package", pkg: "testthat" },
+  check: { label: "Check", running: "Checking", target: "package", pkg: "devtools" },
+  build: { label: "Build", running: "Building", target: "package", pkg: "devtools" },
+  install: { label: "Install", running: "Installing", target: "package", pkg: "devtools" },
+  render: { label: "Render", running: "Rendering", target: "document", pkg: null },
+  latex: { label: "Compile", running: "Compiling", target: "document", pkg: null },
+});
+export const RENDER_EXTENSIONS = Object.freeze(["qmd", "rmd", "md"]);
+// "" FIRST because it is the default and the default matters: no `--to` at
+// all, so a document whose header says `format: revealjs` renders as revealjs.
+export const RENDER_FORMATS = Object.freeze(["", "html", "pdf", "docx"]);
+export const LATEX_ENGINES = Object.freeze(["tectonic", "latexmk", "pdflatex", "xelatex", "lualatex"]);
+export const LATEX_TIMEOUT = 180;
+const JOB_FILTER_MAX = 200;
+
+const MAX_JOBS = 4;               // a job is CPU- and disk-heavy; unbounded is a fork bomb
+const JOB_HISTORY_MAX = 20;
+const JOB_LOG_MAX = 5000;
+const JOB_LOG_CHARS = 1000000;
+const OUTPUT_CAP_MAX_BYTES = 128 * 1024 * 1024;
+
+const scalarChr = (x) => typeof x === "string";
+const isNum = (x) => typeof x === "number" && Number.isFinite(x);
+/** The classes the upgrade gate proved are the user's own page (server.mjs). */
+const PAGE_ONLY = Object.freeze(["served", "file", "local"]);
+
+/** `fs.realpathSync` where the path exists, the resolved path where it does not. */
+function realish(p) {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+}
+
+/**
+ * Is this directory the root of an R package?
+ *
+ * A DESCRIPTION carrying a `Package:` field, not merely a file called
+ * DESCRIPTION — Bioconductor build dirs and a stray copied file both put that
+ * name somewhere it does not mean this. An unreadable file answers FALSE,
+ * which is a decision and not a swallowed error: "this is not a package root"
+ * is the right answer for a malformed file.
+ */
+export function isPackageRoot(dir) {
+  const desc = path.join(dir, "DESCRIPTION");
+  let stat;
+  try { stat = fs.statSync(desc); } catch { return false; }
+  if (!stat.isFile()) return false;
+  let text;
+  try { text = fs.readFileSync(desc, "utf8"); } catch { return false; }
+  return Boolean(packageFieldOf(text));
+}
+
+/** The first record's `Package:` field of a DCF text, or "". */
+function packageFieldOf(text) {
+  const m = String(text).match(/^Package:[ \t]*(.*)$/m);
+  return m ? m[1].trim() : "";
+}
+
+/**
+ * Every directory from `p` up to the filesystem root, nearest first.
+ *
+ * A parent chain cannot be vectorised — each step is computed from the last —
+ * so this is a BOUNDED loop, and the bound is the point: a symlink loop must
+ * not spin the host's event loop.
+ */
+export function pathAncestors(p, maxUp = 40) {
+  const out = [];
+  let current = p;
+  while (out.length < maxUp) {
+    out.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;      // "/" is its own dirname
+    current = parent;
+  }
+  return out;
+}
+
+/** The package root at or above a path, or "". */
+export function findPackageRoot(p) {
+  if (!scalarChr(p) || !p) return "";
+  let start = p;
+  try { start = fs.statSync(p).isDirectory() ? p : path.dirname(p); } catch { start = path.dirname(p); }
+  start = realish(start);
+  return pathAncestors(start).find(isPackageRoot) || "";
+}
+
+/** The package's name, for a label a person recognises. */
+export function packageName(root) {
+  if (!root || !isPackageRoot(root)) return "";
+  try { return packageFieldOf(fs.readFileSync(path.join(root, "DESCRIPTION"), "utf8")); } catch { return ""; }
+}
+
+/** The lower-cased extension of a path, with no dot. */
+export function pathExtension(p) {
+  const base = path.basename(p);
+  if (!base.includes(".")) return "";
+  return base.replace(/^.*\./, "").toLowerCase();
+}
+
+/**
+ * The data-only options a compile job carries, validated (spike/latex.R's
+ * `latex_options`). Throws a readable message, which becomes the refusal.
+ *
+ * `fetch` is strict where the others are lenient — exactly `true` turns it
+ * on, anything else is off. An option that means "reach the network" must
+ * never be arrived at by coercion.
+ */
+export function latexOptions(opts = {}) {
+  const engine = opts.engine == null ? "auto" : opts.engine;
+  const timeout = opts.timeout == null ? LATEX_TIMEOUT : opts.timeout;
+  if (!scalarChr(engine) || !["auto", ...LATEX_ENGINES].includes(engine)) {
+    throw new Error("Choose auto, tectonic, latexmk, pdflatex, xelatex or lualatex.");
+  }
+  if (!isNum(timeout) || timeout !== Math.floor(timeout) || timeout < 1 || timeout > 600) {
+    throw new Error("Compile timeout must be a whole number from 1 to 600 seconds.");
+  }
+  let identity = opts.identity;
+  if (identity != null) {
+    const number = (v) => isNum(v) && v >= 0 && v <= 9007199254740991 && v === Math.floor(v);
+    if (typeof identity !== "object" || Array.isArray(identity) || !scalarChr(identity.uri) || !identity.uri
+      || identity.uri.length > 4096 || !number(identity.version) || !number(identity.generation)) {
+      throw new Error("Invalid compile source identity.");
+    }
+    identity = { uri: identity.uri, version: identity.version, generation: identity.generation };
+  }
+  const fetch = opts.fetch === true;
+  return {
+    CARMAR_LATEX_ENGINE: engine,
+    CARMAR_LATEX_TIMEOUT: String(timeout),
+    CARMAR_LATEX_FETCH: fetch ? "1" : "",
+    CARMAR_LATEX_IDENTITY: identity == null ? "" : JSON.stringify(identity),
+  };
+}
+
+/**
+ * Decide whether one task may run, and exactly what would run.
+ *
+ * The whole decision in one pure function, returned whole — the same shape as
+ * `carmarDeployment()`, for the same reason: three callers (the host, the
+ * tests, the UI's error message) must not each re-derive it and drift.
+ *
+ * @returns {{ok: boolean, error?: string, task?: string, target?: string,
+ *   root?: string, label?: string, running?: string, targets?: string,
+ *   package?: string, needs?: string|null, env?: Record<string,string>}}
+ */
+export function jobSpec(task, target, opts = {}) {
+  const bad = (error) => ({ ok: false, error });
+  if (!scalarChr(task) || !task) return bad("no task was named");
+  if (!Object.prototype.hasOwnProperty.call(JOB_TASKS, task)) {
+    return bad(`'${task}' is not a task this kernel runs (${Object.keys(JOB_TASKS).join(", ")})`);
+  }
+  const spec = JOB_TASKS[task];
+  if (!scalarChr(target) || !target) {
+    return bad(spec.target === "document" ? "no document was named" : "no folder was named");
+  }
+  let filter = scalarChr(opts.filter) ? opts.filter : "";
+  const format = scalarChr(opts.format) ? opts.format : "";
+  let latexEnv = {};
+  if (task === "latex") {
+    try { latexEnv = latexOptions(opts); } catch (e) { return bad(e.message); }
+  }
+
+  let root;
+  let resolved = target;
+  if (spec.target === "package") {
+    let isDir = false;
+    try { isDir = fs.statSync(target).isDirectory(); } catch { isDir = false; }
+    if (!isDir) return bad(`'${target}' is not a folder`);
+    resolved = realish(target);
+    if (!isPackageRoot(resolved)) {
+      return bad(`'${resolved}' is not an R package — no DESCRIPTION with a Package field. `
+        + "Open a file inside the package and try again.");
+    }
+    root = resolved;
+  } else {
+    let isFile = false;
+    try { isFile = fs.statSync(target).isFile(); } catch { isFile = false; }
+    if (!isFile) return bad(`'${target}' is not a file`);
+    resolved = realish(target);
+    const ext = pathExtension(resolved);
+    const extensions = task === "latex" ? ["tex"] : RENDER_EXTENSIONS;
+    if (!extensions.includes(ext)) {
+      return bad(`CarmaR renders ${extensions.map((e) => `.${e}`).join(", ")} files; `
+        + `'${path.basename(resolved)}' is a .${ext || "(no extension)"}`);
+    }
+    // The document's own folder, so a job still has one place it belongs.
+    root = path.dirname(resolved);
+  }
+
+  if (filter && task !== "test") return bad("a filter only applies to the test task");
+  // Data, never code — but still bounded and stripped of control characters,
+  // because it is echoed into a label and into the audit stream, where a
+  // newline would forge a record.
+  // eslint-disable-next-line no-control-regex
+  filter = filter.replace(/[\x00-\x1f\x7f]/g, "");
+  if (filter.length > JOB_FILTER_MAX) return bad("the test filter is too long");
+
+  if (format && task !== "render") return bad("a format only applies to the render task");
+  if (!RENDER_FORMATS.includes(format)) {
+    return bad(`'${format}' is not a format this kernel renders (${RENDER_FORMATS.filter(Boolean).join(", ")})`);
+  }
+
+  return {
+    ok: true, error: "",
+    task, target: resolved, root,
+    label: spec.label, running: spec.running, targets: spec.target,
+    package: spec.target === "package" ? packageName(root) : "",
+    needs: spec.pkg,
+    env: {
+      CARMAR_JOB_TASK: task, CARMAR_JOB_TARGET: resolved,
+      CARMAR_JOB_ROOT: root, CARMAR_JOB_FILTER: filter,
+      CARMAR_JOB_FORMAT: format, ...latexEnv,
+    },
+  };
+}
+
+/** A sentence naming what is about to happen, before it happens. */
+export function jobTitle(spec) {
+  if (spec.task === "latex") return `Compiling ${path.basename(spec.target)}`;
+  if (spec.targets === "document") {
+    const format = spec.env.CARMAR_JOB_FORMAT;
+    return `Rendering ${path.basename(spec.target)}${format ? ` to ${format}` : ""}`;
+  }
+  const name = spec.package || path.basename(spec.root);
+  const filter = spec.env.CARMAR_JOB_FILTER;
+  if (spec.task === "test" && filter) return `${spec.running} ${name} — tests matching '${filter}'`;
+  return `${spec.running} ${name}`;
+}
+
+const token = (n = 32) => {
+  const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let out = "";
+  for (const b of crypto.randomBytes(n)) out += alphabet[b % alphabet.length];
+  return out;
+};
+
+// What a declared agent may never do here, in the op's own words. `job_start`
+// is on this list DELIBERATELY and is the entry most open to argument: a job
+// IS visible, so the chunk_run rule is satisfied — but a second evaluation
+// door is a policy call, not a consequence of building the mechanism.
+// Reading job state is not refused: an agent that can see the suite is red is
+// more useful and evaluates nothing.
+const AGENT_REFUSED = Object.freeze({
+  job_start: "Agents cannot start development jobs; ask the user to run one.",
+  job_stop: "Agents cannot stop development jobs.",
+  job_open: "Agents cannot open files on the user's desktop.",
+  job_output_cap: "Agents run code through notebook chunks (chunk_run), not raw exec.",
+});
+
+/**
+ * @param {{root: string, spike: string, env: (n: string, d?: string) => string,
+ *   audit: (event: string, fields?: object) => void}} deps
+ */
+export function createPlane({ spike, env, audit }) {
+  const jobRun = path.join(spike, "job-run.R");
+  // 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.
+  const ttlGiven = Number(env("CARMAR_OUTPUT_CAP_TTL", ""));
+  const OUTPUT_CAP_TTL = Number.isFinite(ttlGiven) && ttlGiven >= 1 && ttlGiven <= 3600 ? ttlGiven : 60;
+
+  /** @type {Map<string, object>} */
+  const jobs = new Map();
+  /** @type {Map<string, {job: string, path: string, expires: number}>} */
+  const outputCaps = new Map();
+  let seq = 0;
+  let ctxRef = null;
+
+  const enc = (o) => JSON.stringify(o);
+  /** Broadcast, not addressed: a job is detached, and the page that pressed
+   *  Test may be gone while the page that is here now needs to see it. */
+  const broadcast = (text) => { for (const r of ctxRef.pageRecs()) { try { r.ws.send(text); } catch { /* gone */ } } };
+  const jobEmit = (id, fields) => {
+    const job = id ? jobs.get(id) : null;
+    broadcast(enc({ type: "job", id, ...fields, ...(job && job.identity ? job.identity : {}) }));
+  };
+
+  /** Append output to a job's buffer, bounded — and REPORT what was dropped. */
+  const jobLog = (job, text) => {
+    // `strsplit("", "\n")[[1]]` is character(0) in R and `"".split("\n")` is
+    // `[""]` here, so the empty case is refused explicitly rather than
+    // appending a blank line the R never would.
+    if (!text) return;
+    const lines = String(text).split("\n");
+    job.log.push(...lines);
+    if (job.log.length > JOB_LOG_MAX) {
+      job.dropped += job.log.length - JOB_LOG_MAX;
+      job.log = job.log.slice(job.log.length - JOB_LOG_MAX);
+    }
+    let joined = job.log.join("\n");
+    if (joined.length > JOB_LOG_CHARS) {
+      const before = job.log.length;
+      joined = joined.slice(joined.length - JOB_LOG_CHARS);
+      job.log = joined.split("\n");
+      job.dropped += Math.max(1, before - job.log.length);
+    }
+  };
+
+  /** What a page needs to render one job in a list. */
+  const snapshot = (job, withLog = false) => {
+    const out = {
+      id: job.id, task: job.task, root: job.root, target: job.target,
+      output: job.output, title: job.title, state: job.state, ok: job.ok,
+      error: job.error, started: job.started, elapsed: job.elapsed,
+      counts: job.counts, rows: job.rows, diagnostics: job.diagnostics,
+      truncated: job.truncated, dropped: job.dropped,
+      ...(job.identity || {}),
+    };
+    if (withLog) out.log = job.log.slice();
+    return out;
+  };
+
+  /**
+   * Kill the whole tree. This is spike/kernel.R's `kernel_kill_tree()` with
+   * the half processx cannot reach added: `killProcessTree` does the three
+   * things that are only correct together — descendants, the process group,
+   * then the leader — and host/planes/proc-tree.mjs records the two measured
+   * failures that make each of them necessary.
+   */
+  const killTree = (job) => {
+    const pid = job.engine && job.engine.pid;
+    if (!pid) return;
+    if (process.platform === "win32") {
+      try { spawn("taskkill", ["/T", "/F", "/PID", String(pid)], { stdio: "ignore" }); } catch { /* gone */ }
+      return;
+    }
+    killProcessTree(pid);
+  };
+
+  const pruneJobs = () => {
+    const finished = [...jobs.values()].filter((j) => j.state !== "running");
+    if (finished.length <= JOB_HISTORY_MAX) return;
+    finished.sort((a, b) => a.started - b.started);
+    for (const j of finished.slice(0, finished.length - JOB_HISTORY_MAX)) jobs.delete(j.id);
+  };
+
+  const finish = (job, fields) => {
+    job.state = fields.state || "done";
+    job.ok = fields.ok;
+    if (!job.ok) job.output = null;
+    job.error = fields.error ?? "";
+    job.elapsed = fields.elapsed ?? Math.round((Date.now() / 1000 - job.started) * 100) / 100;
+  };
+
+  const sweepCaps = () => {
+    const now = Date.now() / 1000;
+    for (const [t, g] of outputCaps) if (g.expires < now) outputCaps.delete(t);
+  };
+
+  // ── starting one ─────────────────────────────────────────────────────────
+  function jobStart(cmd, rec) {
+    const request = scalarChr(cmd.id) && cmd.id.length <= 200 ? cmd.id : "";
+    const running = [...jobs.values()].filter((j) => j.state === "running");
+    if (running.length >= MAX_JOBS) {
+      jobEmit("", { event: "refused", request, error: `${running.length} jobs are already running. Wait for one to finish, or stop it.` });
+      return;
+    }
+    // `fetch` is the ONE option that changes what the child may TOUCH — a
+    // compile that may download what it is missing. Read as an exact true,
+    // never remembered, and AUDITED separately, because "the kernel reached
+    // the network" is a fact a person should be able to find afterwards.
+    const fetch = cmd.fetch === true;
+    const spec = jobSpec(cmd.task ?? "", cmd.target ?? "", {
+      filter: cmd.filter ?? "", format: cmd.format ?? "",
+      engine: cmd.engine, timeout: cmd.timeout, fetch, identity: cmd.identity,
+    });
+    if (!spec.ok) {
+      audit("job-refused", { detail: spec.error });
+      jobEmit("", { event: "refused", request, error: spec.error });
+      return;
+    }
+    if (fetch) audit("latex-fetch", { target: path.basename(cmd.target ?? "") });
+    seq += 1;
+    const id = `job-${seq}`;
+    let engine;
+    try {
+      engine = new REngine({ workerPath: jobRun, env: { ...spec.env, CARMAR_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}` });
+      return;
+    }
+    const job = {
+      id, engine, task: spec.task, root: spec.root, target: spec.target,
+      identity: spec.env.CARMAR_LATEX_IDENTITY ? JSON.parse(spec.env.CARMAR_LATEX_IDENTITY) : null,
+      output: null, title: jobTitle(spec), state: "running", ok: null, error: "",
+      started: Date.now() / 1000, elapsed: null, log: [], dropped: 0,
+      rows: [], diagnostics: [], renderer: "", counts: null, truncated: 0, pid: null,
+    };
+    jobs.set(id, job);
+
+    engine.on("event", (e) => {
+      if (job.state !== "running") return;
+      if (e.type === "stdout" || e.type === "stderr") {
+        const text = e.text ?? "";
+        jobLog(job, text);
+        jobEmit(id, { event: "log", stream: e.type, text });
+        return;
+      }
+      if (e.type !== "job") return;
+      const event = e.event ?? "";
+      if (event === "started") job.pid = e.pid;
+      if (event === "output") {
+        // Kept so a page that connects after the render still learns where
+        // the file went — and so `job_open` has a path of its OWN to trust.
+        job.output = scalarChr(e.path) ? e.path : null;
+        job.renderer = e.renderer ?? "";
+      }
+      if (event === "tests") {
+        job.rows = Array.isArray(e.rows) ? e.rows : [];
+        job.counts = e.counts ?? null;
+        job.truncated = e.truncated ?? 0;
+      }
+      if (event === "diagnostics") job.diagnostics = Array.isArray(e.rows) ? e.rows : [];
+      if (event === "done") finish(job, { ok: e.ok === true, error: e.error ?? "", elapsed: e.elapsed ?? null });
+      // The child stamps its own id, so this is byte-faithful: no re-encode,
+      // no four-digit rounding, no `{}` where the child wrote null.
+      broadcast(e.__raw ?? enc(e));
+      if (event === "done") pruneJobs();
+    });
+    engine.on("spawn-error", (err) => {
+      if (job.state !== "running") return;
+      audit("job-start-failed", { detail: err.message });
+      finish(job, { ok: false, error: `the job process could not start: ${err.message}` });
+      jobEmit(id, { event: "done", ok: false, error: job.error, elapsed: job.elapsed });
+      pruneJobs();
+    });
+    engine.on("exit", ({ code }) => {
+      if (job.state !== "running") return;
+      // Died without a `done`. Never silent: an empty log and a crashed job
+      // look identical on screen and mean opposite things.
+      finish(job, { ok: false, error: `the job process stopped unexpectedly (exit ${code == null ? "unknown" : code})` });
+      audit("job-died", { id, detail: String(code) });
+      jobEmit(id, { event: "done", ok: false, error: job.error, elapsed: job.elapsed });
+      pruneJobs();
+    });
+
+    try {
+      engine.start();
+    } catch (e) {
+      jobs.delete(id);
+      audit("job-start-failed", { detail: e.message });
+      jobEmit(id, { event: "refused", request, error: `the job process could not start: ${e.message}` });
+      return;
+    }
+    audit("job-start", { id, detail: spec.task });
+    // Announced before it runs, in the words of the thing that will happen.
+    jobEmit(id, { event: "accepted", request, task: spec.task, root: spec.root,
+      target: spec.target, title: job.title, started: job.started });
+  }
+
+  /** Any page may stop any job: a job is the kernel's, not a socket's. */
+  function jobStop(id) {
+    const job = jobs.get(id);
+    if (!job || job.state !== "running") return;
+    // No graceful protocol: job-run.R never reads stdin, so a shutdown frame
+    // would go unread and only the kill would land. Kill the tree directly.
+    killTree(job);
+    finish(job, { state: "stopped", ok: false, error: "stopped" });
+    audit("job-stop", { id });
+    jobEmit(id, { event: "done", ok: false, stopped: true, error: "stopped", elapsed: job.elapsed });
+    pruneJobs();
+  }
+
+  const plane = {
+    name: "jobs",
+    ops: ["job_start", "job_stop", "job_list", "job_context", "job_root", "job_open", "job_output_cap"],
+    // Not declared through the seam's `agentRefused`: the R answers each of
+    // these in the OP'S OWN WORDS, and a suite pins those words. The refusal
+    // is made here, first thing in handle(), with the same messages.
+    agentRefused: [],
+    // serve.R advertises no job verb in ready.commands, so neither does this.
+    commands: [],
+    capabilities: [],
+
+    /** Is any job still running? The idle clock must not stop a kernel that
+     *  is three minutes into a check nobody is watching — precisely the case
+     *  a detached job exists for. */
+    busy: () => [...jobs.values()].some((j) => j.state === "running"),
+
+    init(ctx) { ctxRef = ctx; },
+
+    handle(cmd, rec, ctx) {
+      ctxRef = ctx;
+      const type = cmd.type;
+      if (rec.role === "mcp" && AGENT_REFUSED[type]) {
+        audit("mcp-refused", { reason: `agent asked for ${type}` });
+        if (scalarChr(cmd.id)) rec.ws.send(enc({ type, id: cmd.id, error: AGENT_REFUSED[type] }));
+        return;
+      }
+      switch (type) {
+        case "job_start":
+          if (rec.role !== "page") return;
+          return jobStart(cmd, rec);
+        case "job_stop":
+          if (rec.role !== "page" || !scalarChr(cmd.job)) return;
+          return jobStop(cmd.job);
+        case "job_list": {
+          // Reattachment: everything a page needs to render the pane it just
+          // opened, including the buffered log of a job that started before
+          // this page existed. This is what makes a job detached rather than
+          // merely asynchronous.
+          if (!scalarChr(cmd.id)) return;
+          const wantLog = scalarChr(cmd.job);
+          const ordered = [...jobs.values()].sort((a, b) => a.started - b.started);
+          rec.ws.send(enc({ type: "job_list", id: cmd.id,
+            jobs: ordered.map((j) => snapshot(j, wantLog && j.id === cmd.job)) }));
+          return;
+        }
+        case "job_context":
+        case "job_root": {
+          // "What can I do with what I am looking at?" — ONE question with two
+          // halves: the file may be inside a package, and may itself be
+          // renderable. It was `job_root` while it could only answer the first;
+          // both spellings are answered, each typed as the op that was asked,
+          // so an older page is never handed a frame type it does not know.
+          if (!scalarChr(cmd.id)) return;
+          let p = cmd.path ?? "";
+          const root = findPackageRoot(p);
+          const isFile = (() => { try { return fs.statSync(p).isFile(); } catch { return false; } })();
+          const renderable = scalarChr(p) && Boolean(p) && isFile && RENDER_EXTENSIONS.includes(pathExtension(p));
+          const compilable = scalarChr(p) && Boolean(p) && isFile && pathExtension(p) === "tex";
+          // Report the path the JOB will act on, not the one the page sent:
+          // jobSpec normalizes, and on macOS those differ by a /private prefix
+          // on everything under /var.
+          if (renderable || compilable) p = realish(p);
+          rec.ws.send(enc({ type, id: cmd.id, root, package: packageName(root),
+            document: renderable ? p : "", latex: compilable ? p : "",
+            engines: ["auto", ...LATEX_ENGINES], formats: [...RENDER_FORMATS],
+            tasks: Object.keys(JOB_TASKS) }));
+          return;
+        }
+        case "job_output_cap": {
+          // Page-only in BOTH senses: an agent may not ask (above), and only a
+          // socket the upgrade gate classed as the user's own page may ask.
+          if (!scalarChr(cmd.id)) return;
+          const reply = (fields) => rec.ws.send(enc({ type, id: cmd.id, ...fields }));
+          if (rec.role !== "page" || !PAGE_ONLY.includes(rec.class)) {
+            audit("job-output-cap-refused", { class: rec.class ?? "unknown" });
+            reply({ error: "Only the local notebook page may ask this." });
+            return;
+          }
+          if (!scalarChr(cmd.job)) { reply({ error: "which job?" }); return; }
+          const job = jobs.get(cmd.job);
+          if (!job || job.task !== "latex" || job.state !== "done" || job.ok !== true
+            || !scalarChr(job.output) || !fs.existsSync(job.output)) {
+            reply({ job: cmd.job, error: "That job has no PDF to show." });
+            return;
+          }
+          sweepCaps();
+          const t = token(32);
+          outputCaps.set(t, { job: cmd.job, path: job.output, expires: Date.now() / 1000 + OUTPUT_CAP_TTL });
+          audit("job-output-cap", { id: cmd.job });
+          reply({ job: cmd.job, token: t, bytes: fs.statSync(job.output).size,
+            name: path.basename(job.output), ttl: OUTPUT_CAP_TTL });
+          return;
+        }
+        case "job_open": {
+          // The wire names a JOB, never a path, and the host opens the path IT
+          // recorded from the child's own `output` frame.
+          if (rec.role !== "page" || !scalarChr(cmd.job)) return;
+          const job = jobs.get(cmd.job);
+          if (!job || job.state !== "done" || job.ok !== true
+            || !scalarChr(job.output) || !fs.existsSync(job.output)) return;
+          audit("job-open", { id: cmd.job });
+          openOnDesktop(job.output);
+          return;
+        }
+        default:
+      }
+    },
+
+    /**
+     * The file a finished job produced, by ONE-TIME CAPABILITY. The page asked
+     * `job_output_cap` over its gated socket and was handed a token; the token
+     * names a job, is spent on first use, dies after the TTL, and appears in no
+     * listing. A drive-by that merely found the port has nothing to present.
+     */
+    http(req, res, pathname, ctx) {
+      if (pathname !== "/job-output") return false;
+      const blocked = ctx.controlRejection(req, { allowFile: true, allowApproved: true });
+      if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
+      const origin = req.headers.origin || "";
+      // A page that sent an Origin needs CORS to READ the body it was granted;
+      // a same-origin page needs nothing. Never "*". REFUSALS carry it too, or
+      // a 404 reaches a file page as the browser's own "Failed to fetch".
+      const cors = origin ? { "Access-Control-Allow-Origin": origin, Vary: "Origin" } : {};
+      const cap = ctx.queryParam(req, "cap");
+      sweepCaps();
+      let grant = null;
+      if (/^[A-Za-z0-9]{32}$/.test(cap)) {
+        grant = outputCaps.get(cap) || null;
+        outputCaps.delete(cap);                       // spent on first use
+        if (grant && grant.expires < Date.now() / 1000) grant = null;
+      }
+      if (!grant) {
+        audit("job-output-refused", {});
+        ctx.respond(res, 404, "text/plain", "no such output", cors);
+        return true;
+      }
+      const job = jobs.get(grant.job);
+      let stat = null;
+      try { stat = fs.statSync(grant.path); } catch { stat = null; }
+      if (!job || job.state !== "done" || job.ok !== true || job.output !== grant.path
+        || !stat || !stat.isFile()) {
+        audit("job-output-refused", { id: grant.job });
+        ctx.respond(res, 404, "text/plain", "no such output", cors);
+        return true;
+      }
+      if (!Number.isFinite(stat.size) || stat.size > OUTPUT_CAP_MAX_BYTES) {
+        audit("job-output-refused", { id: grant.job, detail: "too large" });
+        ctx.respond(res, 413, "text/plain", "output too large to serve", cors);
+        return true;
+      }
+      let bytes;
+      try { bytes = fs.readFileSync(grant.path); } catch { bytes = null; }
+      if (!bytes) { ctx.respond(res, 500, "text/plain", "could not read the output", cors); return true; }
+      audit("job-output", { id: grant.job });
+      ctx.respond(res, 200, "application/pdf", bytes, {
+        // serve.R writes the name's UTF-8 BYTES into the header. Node writes a
+        // header string as Latin-1 and THROWS on anything above U+00FF, which
+        // dropped the connection for `paper 🧬.pdf` — so the same bytes are
+        // handed over spelled as Latin-1, and the wire matches R's exactly.
+        "Content-Disposition": Buffer.from(`inline; filename="${path.basename(grant.path).replace(/["\\\r\n]/g, "_")}"`, "utf8").toString("latin1"),
+        "Content-Length": String(bytes.length),
+        ...cors,
+      });
+      return true;
+    },
+
+    /** A job outlives the socket that started it, so nothing happens here. */
+    onClose() {},
+
+    /** The kernel is going away; no job may outlive it. */
+    shutdown() { for (const job of jobs.values()) if (job.state === "running") killTree(job); },
+  };
+  return plane;
+}
+
+/** `utils::browseURL` for the platform — an argument VECTOR, never a shell string. */
+function openOnDesktop(p) {
+  try {
+    // CARMAR_OPENER: an executable handed the path as its ONE argument. R's
+    // browseURL reads `options(browser)` for the same purpose, and a test rig
+    // that swaps that option is invisible to a supervisor that is not R — so
+    // without this the host opened every synthetic PDF a suite produced on the
+    // user's real desktop. Absolute paths only; never a shell string.
+    const opener = String(process.env.CARMAR_OPENER || "");
+    const child = path.isAbsolute(opener) ? spawn(opener, [p], { stdio: "ignore", detached: true })
+      : process.platform === "darwin" ? spawn("open", [p], { stdio: "ignore", detached: true })
+      : process.platform === "win32" ? spawn("cmd", ["/c", "start", "", p], { stdio: "ignore", detached: true })
+        : spawn("xdg-open", [p], { stdio: "ignore", detached: true });
+    child.on("error", () => { /* no desktop opener: nothing opens, nothing breaks */ });
+    child.unref();
+  } catch { /* no desktop opener */ }
+}