beatrina 0.8.6

package/host/planes/pair.mjs

@@ -0,0 +1,325 @@
+// pair.mjs — the consent doors, and the one that hands a document to a page.
+//
+// A port of spike/serve.R's `/pair`, `/pair/approve`, `/published/authorize`
+// and `/open`, plus the `CARMAR_PUBLISHED_ORIGIN` seed. Nothing here opens a
+// socket; it decides which exact Origin STRING the upgrade gate in
+// host/server.mjs will admit this session (`ctx.approvals`), and it is the
+// only writer of that set.
+//
+// The shape, and why it is this shape (serve.R, lines 686–880 and 1575–1730):
+//
+//   · Merely OPENING /pair grants nothing. It renders a LOCAL, non-frameable
+//     consent page (X-Frame-Options: DENY and `frame-ancestors 'none'` come
+//     from the host's SAFE_HEADERS) carrying a 48-character challenge minted
+//     from the OS CSPRNG. A foreign page can navigate to this route, but
+//     same-origin policy keeps it from READING the challenge, so it cannot
+//     manufacture the approval navigation without the reader pressing the
+//     button. Only that button can spend it, it is spent ONCE, and it dies
+//     after 300 seconds.
+//   · There are THREE consent texts, not one, because the three cases are
+//     genuinely different and a person has to be able to tell them apart: a
+//     published site (an exact https origin), a page opened from disk (the
+//     literal four-character Origin "null", which is not a web origin and
+//     never becomes one), and a notebook another loopback kernel served that
+//     is re-attaching after its own session stopped. Nothing is granted for
+//     being loopback — the local case asks too — but once approved it is
+//     classed `local`, which is in PAGE_ONLY_CLASSES.
+//   · A PUBLISHED origin gets the bridge page afterwards: a published reader's
+//     page never holds this socket itself, the local bridge window does, and
+//     relays only messages from the exact approved origin. A file or local
+//     page dials the kernel directly the moment its retry fires, so all its
+//     window has left to do is say so.
+//   · /published/authorize is the NATIVE door (the carmar:// handler). It is
+//     gated by controlRejection, so a browser page cannot grant itself R
+//     execution by visiting a URL; `publishedOriginValid` stays strict
+//     (^https?://…) because it also guards the environment seed, and widening
+//     it there would let one variable pre-approve every file on disk.
+//   · /open is the double-click door: it hands a path to a page that is
+//     ALREADY RUNNING instead of starting a fourth R. No extension list, on
+//     purpose — the authority on what may be read is `readfile` in the worker,
+//     and a second weaker copy of that judgment only ever produced false
+//     rejections. Origin-gated exactly like /shutdown.
+
+import fs from "node:fs";
+import { FILE_ORIGIN, LOCAL_ORIGIN_RE, secureToken } from "../server.mjs";
+
+/** How long an unspent consent challenge lives. serve.R: 300 seconds. */
+export const PAIR_CHALLENGE_TTL_S = 300;
+/** The consent challenge is 48 bytes of CSPRNG, not 32: it is read off a page. */
+export const PAIR_CHALLENGE_CHARS = 48;
+
+/**
+ * Is this an exact web origin (scheme + authority, no path or credentials)?
+ *
+ * Deliberately a small parser: the value is only ever used as an opaque key
+ * compared with the browser-supplied Origin header. Keeping paths, fragments
+ * and control characters out is also what makes it safe to show on the
+ * consent page.
+ *
+ * @param {unknown} origin
+ * @returns {boolean}
+ */
+export function publishedOriginValid(origin) {
+  return typeof origin === "string" && Buffer.byteLength(origin) <= 512
+    && /^https?:\/\/[A-Za-z0-9._~-]+(:[0-9]{1,5})?$/.test(origin);
+}
+
+/** A notebook page another loopback kernel served (serve.R: local_origin). */
+export function localOrigin(origin) {
+  return typeof origin === "string" && LOCAL_ORIGIN_RE.test(origin);
+}
+
+/** The five characters that can change the meaning of the markup around them. */
+export function htmlEscape(x) {
+  return String(x)
+    .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+const PAGE_CSS = "body{font:16px/1.5 system-ui,sans-serif;max-width:42rem;margin:10vh auto;padding:0 1.25rem;color:#172033}"
+  + ".site{padding:.75rem 1rem;background:#f3f6fb;border-radius:.55rem;overflow-wrap:anywhere}"
+  + "button{border:0;border-radius:.5rem;background:#2357d9;color:white;padding:.7rem 1rem;font:inherit;font-weight:650;cursor:pointer}"
+  + "small{color:#59657a}";
+const NARROW_CSS = "body{font:16px/1.5 system-ui,sans-serif;max-width:38rem;margin:10vh auto;padding:0 1.25rem;color:#172033}"
+  + ".site{overflow-wrap:anywhere;color:#2357d9}";
+
+/**
+ * The consent page for one origin, and the challenge it carries.
+ * @returns {{html: string, challenge: string}}
+ */
+export function pairingPage(origin, nonce, mint) {
+  const isFile = origin === FILE_ORIGIN;
+  const isLocal = localOrigin(origin);
+  const challenge = mint(origin, String(nonce ?? "").slice(0, 200));
+  const title = isFile ? "Allow this notebook file to use CarmaR?"
+    : isLocal ? "Attach this notebook to this CarmaR session?"
+      : "Allow this book to use CarmaR?";
+  const body = isFile
+    ? '<h1>Run this notebook file with your R?</h1>'
+      + '<p>A notebook opened from a file on this computer</p>'
+      + '<p class="site"><strong>a page opened from disk (file://)</strong></p>'
+      + '<p>wants to use this CarmaR session. The code will run as your user '
+      + 'and can access your files and network. A page opened from a file '
+      + 'cannot be identified any more exactly than this, so approve it only '
+      + 'if you just opened a notebook of your own.</p>'
+    : isLocal
+      ? '<h1>Attach this notebook to this R session?</h1>'
+        + '<p>A CarmaR notebook page served at</p>'
+        + `<p class="site"><strong>${htmlEscape(origin)}</strong></p>`
+        + '<p>wants to use this CarmaR session instead of its own &mdash; usually '
+        + 'because the session that served it has stopped. It will be treated as '
+        + 'your notebook: its chunks run as your user, and it may open a terminal '
+        + 'and use your saved AI settings. Approve it only if you just asked a '
+        + 'notebook of your own to attach.</p>'
+      : '<h1>Run this book with your R?</h1><p>The published site</p>'
+        + `<p class="site"><strong>${htmlEscape(origin)}</strong></p>`
+        + '<p>wants to send R chunks to this CarmaR session on your computer. '
+        + 'The code will run as your user and can access your files and network.</p>';
+  const html = '<!doctype html><html><head><meta charset="utf-8">'
+    + '<meta name="viewport" content="width=device-width,initial-scale=1">'
+    + '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
+    + "style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'\">"
+    + `<title>${title}</title><style>${PAGE_CSS}</style></head><body>`
+    + body
+    + '<form method="get" action="/pair/approve"><input type="hidden" name="challenge" value="'
+    + challenge + '"><button type="submit">'
+    + (isLocal ? "Attach for this session" : "Allow for this session")
+    + '</button></form>'
+    + "<p><small>Nothing runs until you press a chunk's Run button. "
+    + 'Approval disappears when this CarmaR session stops.</small></p></body></html>';
+  return { html, challenge };
+}
+
+/**
+ * The window that HOLDS the socket for a published site and relays its frames.
+ *
+ * The reader's page never connects here; this local window does, and it only
+ * ever forwards messages whose origin and nonce match the pairing it was
+ * opened for.
+ */
+export function pairingBridgePage(rec, port) {
+  const target = JSON.stringify(rec.origin);
+  const nonce = JSON.stringify(rec.nonce ?? "");
+  const socketUrl = JSON.stringify(`ws://127.0.0.1:${port}/ws`);
+  return '<!doctype html><html><head><meta charset="utf-8">'
+    + '<meta name="viewport" content="width=device-width,initial-scale=1">'
+    + '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
+    + "script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self' ws://127.0.0.1:"
+    + port + "; base-uri 'none'\">"
+    + '<title>CarmaR connected</title><style>' + NARROW_CSS + '</style></head><body>'
+    + '<h1>CarmaR is connected</h1><p>This session now runs chunks pressed on</p>'
+    + `<p class="site"><strong>${htmlEscape(rec.origin)}</strong></p>`
+    + '<p>The page connects by itself and closes this window; if it stays open, you can close it. '
+    + 'The approval lasts until this R session stops.</p><script>(function(){'
+    + 'const target=' + target + ',nonce=' + nonce + ',socketUrl=' + socketUrl + ';let ws=null,wsGeneration=0;'
+    + 'const tell=(type,extra)=>{if(window.opener)window.opener.postMessage('
+    + 'Object.assign({type,nonce,origin:target,port:' + port + '},extra||{}),target)};'
+    + 'addEventListener("message",event=>{const data=event.data||{};'
+    + 'if(event.source!==window.opener||event.origin!==target||data.nonce!==nonce)return;'
+    + 'if(data.type==="carmar:bridge-attach"){const generation=++wsGeneration,old=ws;'
+    + 'if(old){old.onmessage=old.onerror=old.onclose=null;try{old.close()}catch(e){}}'
+    + 'ws=new WebSocket(socketUrl);const current=ws;'
+    + 'current.onmessage=message=>{if(generation===wsGeneration)tell("carmar:bridge-frame",{data:message.data})};'
+    + 'current.onerror=()=>{if(generation===wsGeneration)tell("carmar:bridge-error")};'
+    + 'current.onclose=()=>{if(generation===wsGeneration)tell("carmar:bridge-close")};return}'
+    + 'if(data.type==="carmar:bridge-send"&&ws&&ws.readyState===1)ws.send(data.data);'
+    + 'if(data.type==="carmar:bridge-close"&&ws)ws.close()});'
+    + 'tell("carmar:paired");})();</script></body></html>';
+}
+
+/** The last word for a file or local page: it dials the kernel by itself. */
+export function pairingDonePage(rec) {
+  return '<!doctype html><html><head><meta charset="utf-8">'
+    + '<meta name="viewport" content="width=device-width,initial-scale=1">'
+    + '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
+    + "style-src 'unsafe-inline'; base-uri 'none'\">"
+    + '<title>CarmaR attached</title><style>' + NARROW_CSS + '</style></head><body>'
+    + '<h1>Attached</h1><p>The notebook</p>'
+    + '<p class="site"><strong>'
+    + (rec.origin === FILE_ORIGIN ? "a page opened from disk (file://)" : htmlEscape(rec.origin))
+    + '</strong></p>'
+    + '<p>may use this CarmaR session until it stops. It reconnects by itself within '
+    + 'a few seconds; you can close this window.</p></body></html>';
+}
+
+export function createPlane({ env, audit }) {
+  /** challenge → {origin, nonce, created} — unspent consent requests. */
+  const requests = new Map();
+
+  const prune = (now = Date.now()) => {
+    for (const [key, rec] of requests) {
+      if (!(rec.created > 0) || (now - rec.created) / 1000 > PAIR_CHALLENGE_TTL_S) requests.delete(key);
+    }
+  };
+  const mint = (origin, nonce) => {
+    prune();
+    const challenge = secureToken(PAIR_CHALLENGE_CHARS);
+    requests.set(challenge, { origin, nonce, created: Date.now() });
+    return challenge;
+  };
+
+  /**
+   * The page an /open should land on: the one the user most recently focused
+   * (WP5's MCP plane claims it), else the most recently opened page. `null`
+   * when no notebook window is connected at all — which is an ANSWER (the
+   * caller is told "parked"), never silence.
+   */
+  const targetPage = (ctx) => {
+    const active = ctx.state.activePage;
+    if (active && ctx.sockets.includes(active)) return active;
+    const pages = ctx.pageRecs();
+    return pages.length ? pages[pages.length - 1] : null;
+  };
+
+  return {
+    name: "pair",
+    ops: [],                 // every door here is HTTP; none is a socket frame
+    commands: [],
+    capabilities: [],
+
+    init(ctx) {
+      // A native CarmaR launcher may start the kernel for one published page.
+      // The URL-scheme handoff is the user's consent gesture; carrying only
+      // the exact origin into this process keeps the permission session-scoped
+      // and stops a second site borrowing it.
+      const seed = env("CARMAR_PUBLISHED_ORIGIN", "");
+      if (publishedOriginValid(seed)) {
+        ctx.approvals.add(seed);
+        audit("published-origin-authorized", { origin: seed, source: "launcher" });
+      }
+      if (ctx.state.pendingOpen) audit("open-file-parked", {});
+    },
+
+    http(req, res, pathname, ctx) {
+      if (pathname === "/published/authorize") {
+        const blocked = ctx.controlRejection(req);
+        if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
+        const origin = ctx.queryParam(req, "origin");
+        if (!publishedOriginValid(origin)) {
+          audit("published-origin-rejected", { detail: origin });
+          ctx.respond(res, 400, "application/json", JSON.stringify({ ok: false, error: "invalid origin" }));
+          return true;
+        }
+        ctx.approvals.add(origin);
+        audit("published-origin-authorized", { origin, source: "native" });
+        ctx.respond(res, 200, "application/json", JSON.stringify({ ok: true, origin }));
+        return true;
+      }
+
+      if (pathname === "/pair") {
+        const origin = ctx.queryParam(req, "origin");
+        const nonce = ctx.queryParam(req, "nonce");
+        // FILE_ORIGIN is accepted HERE and only here.
+        if (origin !== FILE_ORIGIN && !publishedOriginValid(origin)) {
+          audit("pair-rejected", { detail: origin });
+          ctx.respond(res, 400, "text/plain", "A valid http(s) publishing origin is required.");
+          return true;
+        }
+        if (ctx.approvals.has(origin)) {
+          audit("pair-reconnected", { origin });
+          ctx.respond(res, 200, "text/html", pairingBridgePage({ origin, nonce }, ctx.port()));
+          return true;
+        }
+        audit("pair-offered", { origin });
+        ctx.respond(res, 200, "text/html", pairingPage(origin, nonce, mint).html);
+        return true;
+      }
+
+      if (pathname === "/pair/approve") {
+        prune();
+        const challenge = ctx.queryParam(req, "challenge");
+        const rec = challenge ? requests.get(challenge) : null;
+        if (!rec) {
+          audit("pair-rejected", { detail: "missing or expired challenge" });
+          ctx.respond(res, 400, "text/plain", "This CarmaR approval request has expired.");
+          return true;
+        }
+        requests.delete(challenge);                 // consume-once: no replay
+        ctx.approvals.add(rec.origin);
+        audit("published-origin-approved", { origin: rec.origin });
+        const page = (rec.origin === FILE_ORIGIN || localOrigin(rec.origin))
+          ? pairingDonePage(rec) : pairingBridgePage(rec, ctx.port());
+        ctx.respond(res, 200, "text/html", page);
+        return true;
+      }
+
+      if (pathname === "/open") {
+        const blocked = ctx.controlRejection(req);
+        if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
+        const asked = ctx.queryParam(req, "file");
+        let file = "";
+        if (asked) {
+          try {
+            const st = fs.statSync(asked);
+            if (st.isFile()) file = fs.realpathSync(asked);
+          } catch { file = ""; }         // no such path: the refusal below says so
+        }
+        if (!file) {
+          audit("open-rejected", { detail: asked });
+          ctx.respond(res, 400, "text/plain", "no such file");
+          return true;
+        }
+        const page = targetPage(ctx);
+        const park = () => {
+          ctx.state.pendingOpen = file;
+          audit("open-parked", { detail: file });
+          ctx.respond(res, 200, "application/json", '{"ok":true,"delivered":"parked"}');
+        };
+        // No page is connected yet — this kernel was started for this very
+        // document and its notebook is still loading. Park it exactly as the
+        // environment channel does; the first page to ask collects it.
+        if (!page) { park(); return true; }
+        audit("open", { detail: file });
+        let sent = false;
+        try { sent = page.ws.send(JSON.stringify({ type: "open-file", path: file })) !== false; } catch { sent = false; }
+        // The page we picked died between the roster read and the send. Park
+        // rather than report a success nobody acted on.
+        if (!sent) { park(); return true; }
+        ctx.respond(res, 200, "application/json", '{"ok":true,"delivered":"page"}');
+        return true;
+      }
+
+      return false;
+    },
+  };
+}

package/host/planes/pipe-term.mjs

@@ -0,0 +1,122 @@
+// pipe-term.mjs — a terminal without a pty, for a kernel that has no node-pty.
+//
+// node-pty is a NATIVE module. The carmar R package is source-only and
+// CRAN-shaped (tools/ship/build-r-pkg.sh), so an installed Beatrix has never
+// had it: every term_open from an installed package answered "node-pty is not
+// installed on this kernel" (measured 2026-09-15, tools/beatrina/acceptance.mjs
+// against build/carmar_0.8.4.tar.gz). The terminal pane then had nothing.
+//
+// This is the honest second rung: the user's shell on plain pipes, wearing the
+// same shape node-pty's IPty has (pid · onData · onExit · write · resize ·
+// kill), so host/planes/terminal.mjs keeps one code path. What a pipe CAN do is
+// what lib/terminal.js already promises — "Line programs run here: shell, git,
+// make, python" — and what it cannot is said once, in the pane, when it opens:
+// no full-screen programs, no password prompts, no job control.
+//
+// Two keys a pty would translate are translated here instead, because a pipe
+// carries them as bytes the shell would never see as signals:
+//   · ^C interrupts what the SHELL started, never the shell itself: the
+//     shell's descendants get SIGINT (Unix), or a console Ctrl+C goes to the
+//     shell's own console through processx's interrupt.exe (Windows), which
+//     cmd.exe survives and the running program does not.
+//   · ^D closes the shell's stdin, which ends it, as at a prompt.
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { descendantsOf } from "./proc-tree.mjs";
+import { findInterruptTool, windowsInterruptPlan, windowsKillPlan } from "../windows-runtime.mjs";
+
+/** What the pane is told when the terminal is a pipe. */
+export const PIPE_NOTICE = "[This terminal has no pty: line programs work (git, R, python scripts); "
+  + "full-screen programs and password prompts do not.]\r\n";
+
+/**
+ * The shell and arguments for a pipe terminal. A login shell where the shell
+ * supports it, so PATH is the user's; never `-i`, which on a pipe prints job
+ * control warnings and prompts to stderr.
+ */
+export function pipeShell(env = process.env, platform = process.platform) {
+  if (platform === "win32") {
+    return { cmd: env.ComSpec || env.COMSPEC || "cmd.exe", args: ["/Q"] };
+  }
+  const shell = env.SHELL || "/bin/sh";
+  const base = path.basename(shell);
+  return { cmd: shell, args: ["bash", "zsh", "fish"].includes(base) ? ["-l"] : [] };
+}
+
+/**
+ * Spawn a shell on pipes, returning an object shaped like node-pty's IPty.
+ * @param {string} file
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: object, platform?: string, spawnImpl?: Function, signal?: Function, tree?: Function}} opts
+ */
+export function pipeSpawn(file, args, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const spawnImpl = opts.spawnImpl || spawn;
+  const signal = opts.signal || ((pid, sig) => process.kill(pid, sig));
+  const tree = opts.tree || descendantsOf;
+  const win = platform === "win32";
+  const child = spawnImpl(file, args, {
+    cwd: opts.cwd, env: opts.env, stdio: ["pipe", "pipe", "pipe"],
+    // Unix: its own group, so nothing aimed at the host's group reaches it.
+    // Windows: its own (hidden) console, so interrupt.exe can target it.
+    detached: !win, windowsHide: true,
+  });
+  const dataFns = [];
+  const exitFns = [];
+  const emit = (d) => dataFns.forEach((fn) => { try { fn(d); } catch { /* a listener must not break the stream */ } });
+  // A pty turns "\n" into "\r\n"; lib/terminal.js reads either, but a bare
+  // "\r" is a carriage return to it, so the output is normalised the pty's way.
+  const cooked = (buf) => String(buf).replace(/\r?\n/g, "\r\n");
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (d) => emit(cooked(d)));
+  child.stderr.on("data", (d) => emit(cooked(d)));
+  child.stdin.on("error", () => { /* the shell has gone; exit says so */ });
+  child.on("exit", (code) => exitFns.forEach((fn) => fn({ exitCode: code })));
+  child.on("error", (e) => { emit(`[the shell could not start: ${e.message}]\r\n`); exitFns.forEach((fn) => fn({ exitCode: null })); });
+  const interruptTool = win ? findInterruptTool({ env: opts.env || process.env }) : "";
+
+  const api = {
+    pid: child.pid,
+    pty: false,
+    onData: (fn) => { dataFns.push(fn); },
+    onExit: (fn) => { exitFns.push(fn); },
+    write(text) {
+      // Split on the two control keys; everything between them is typed text.
+      let rest = String(text);
+      for (;;) {
+        const at = rest.search(/[\x03\x04]/);
+        const plain = at < 0 ? rest : rest.slice(0, at);
+        // A pipe has no line discipline: Enter arrives as "\r" from a pane
+        // that talks to ptys, and the shell reads lines ending in "\n".
+        if (plain) child.stdin.write(plain.replace(/\r\n?/g, "\n"));
+        if (at < 0) return;
+        if (rest[at] === "\x03") api.interrupt();
+        else child.stdin.end();
+        rest = rest.slice(at + 1);
+      }
+    },
+    /** ^C: what the shell is running, never the shell. */
+    interrupt() {
+      if (win) {
+        const plan = windowsInterruptPlan(child.pid, interruptTool);
+        if (!plan) { emit("[^C needs processx's interrupt helper on Windows; it was not found.]\r\n"); return; }
+        try { spawnImpl(plan.bin, plan.args, { stdio: "ignore", windowsHide: true }); } catch { /* gone */ }
+        return;
+      }
+      for (const pid of tree(child.pid)) { try { signal(pid, "SIGINT"); } catch { /* gone */ } }
+    },
+    resize() { /* a pipe has no size */ },
+    kill() {
+      if (win) {
+        const plan = windowsKillPlan(child.pid);
+        try { spawnImpl(plan.bin, plan.args, { stdio: "ignore", windowsHide: true }); } catch { /* gone */ }
+        return;
+      }
+      try { signal(-child.pid, "SIGKILL"); } catch { /* the group is gone */ }
+      try { signal(child.pid, "SIGKILL"); } catch { /* gone */ }
+    },
+  };
+  return api;
+}

package/host/planes/plugins.mjs

@@ -0,0 +1,112 @@
+// plugins.mjs — the five plugin ops, and who may send each.
+//
+// The store itself is host/plugin-store.mjs (a port of spike/plugins.R); this
+// file is only the door, which is serve.R's half of the same decision:
+//
+//   plugin_list · plugin_read · plugin_policy   open to ANY socket. An agent
+//     that can see which styles exist writes `csl: apa.csl` instead of
+//     guessing, and a page consumer (the editor's themes) reads what it needs.
+//   plugin_install · plugin_remove              page-only in BOTH senses —
+//     PAGE_ONLY_CLASSES here, agentRefused at the seam — and AUDITED. They
+//     write the user layer and (install) fetch from the network, and changing
+//     what a machine renders with is the person's decision, made visibly.
+//
+// The policy is ENFORCEMENT, unlike the AI policy, because every fetch and
+// every write is the supervisor's. It keeps the three-state rule: a policy that
+// names only junk REFUSES TO START. That refusal lives in `init()`, which
+// host/main.mjs runs before the server listens, so a misconfigured deployment
+// never announces a url — the same shape as serve.R joining `plugin_policy$errors`
+// to its startup gate.
+
+import {
+  pluginInstall, pluginKindOk, pluginKinds, pluginPolicyDisclosure, pluginPolicyOnce,
+  pluginRead, pluginRemove, pluginRows,
+} from "../plugin-store.mjs";
+
+const PAGE_ONLY_CLASSES = ["served", "file", "local"];
+const OPS = ["plugin_list", "plugin_read", "plugin_policy", "plugin_install", "plugin_remove"];
+const AGENT_REFUSED = ["plugin_install", "plugin_remove"];
+const AGENT_WHY = {
+  plugin_install: "Agents cannot install a plugin; ask the user to, in Settings ▸ Plugins.",
+  plugin_remove: "Agents cannot remove a plugin.",
+};
+
+export function createPlane({ spike, env, audit }) {
+  const here = spike;
+  const policy = pluginPolicyOnce(env);
+  const kinds = pluginKinds(env);
+
+  return {
+    name: "plugins",
+    ops: OPS,
+    agentRefused: AGENT_REFUSED,
+    agentReason: (op) => AGENT_WHY[op],
+    commands: OPS,
+    capabilities: ["plugins-v1"],
+
+    /** A policy that permits nothing does not come up degraded; it does not come up. */
+    init() {
+      if (policy.errors.length) throw new Error(policy.errors.join(" "));
+    },
+
+    handle(cmd, rec, ctx) {
+      const { enc, scalarChr } = ctx;
+      if (!scalarChr(cmd.id)) return undefined;
+      const reply = (payload) => rec.ws.send(enc({ type: cmd.type, id: cmd.id, ...payload }));
+
+      if (cmd.type === "plugin_policy") {
+        reply(pluginPolicyDisclosure(here, policy, env));
+        return undefined;
+      }
+      if (cmd.type === "plugin_list") {
+        const kind = scalarChr(cmd.kind) && cmd.kind ? cmd.kind : null;
+        if (kind != null && !pluginKindOk(kinds, kind)) {
+          reply({ error: "That is not a plugin kind this kernel has." });
+          return undefined;
+        }
+        reply({ rows: pluginRows(here, policy, env, kind).map((r) => ({
+          kind: r.kind, id: r.id, name: r.name, version: r.version,
+          layer: r.layer, file: r.file, requires: r.requires.filter(Boolean),
+          source: r.source, license: r.license, installed: r.installed,
+          bytes: r.bytes, status: r.status, reason: r.reason,
+          verified: r.verified, active: r.active,
+        })) });
+        return undefined;
+      }
+      if (cmd.type === "plugin_read") {
+        const r = pluginRead(here, policy, env, cmd.kind, cmd.plugin,
+          scalarChr(cmd.file) && cmd.file ? cmd.file : null);
+        if (r.ok !== true) reply({ error: r.error });
+        else reply({ ok: true, kind: r.kind, plugin: r.id, file: r.file, name: r.name, text: r.text });
+        return undefined;
+      }
+
+      // Writes, from here down. A declared agent was answered by name at the
+      // seam; this is the CLASS half, which is what the upgrade gate proved.
+      if (rec.role !== "page") return undefined;
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("plugin-refused", { op: cmd.type, reason: "class", class: rec.class || "unknown" });
+        reply({ error: "Only the local notebook page may change plugins." });
+        return undefined;
+      }
+
+      if (cmd.type === "plugin_install") {
+        const from = (cmd.from && typeof cmd.from === "object" && !Array.isArray(cmd.from)) ? cmd.from : {};
+        return pluginInstall(here, policy, env, cmd.kind, from).then((r) => {
+          audit("plugin-install", {
+            kind: cmd.kind ?? "", plugin: r.id ?? "", door: Object.keys(from)[0] ?? "",
+            ok: r.ok === true, reason: r.ok === true ? "" : r.error,
+          });
+          if (r.ok !== true) reply({ error: r.error });
+          else reply({ ok: true, kind: r.kind, plugin: r.id, name: r.name, version: r.version,
+            file: r.file, requires: [].concat(r.requires ?? []), layer: r.layer, already: r.already === true });
+        });
+      }
+
+      const r = pluginRemove(here, policy, env, cmd.kind, cmd.plugin);
+      audit("plugin-remove", { kind: cmd.kind ?? "", plugin: cmd.plugin ?? "", ok: r.ok === true });
+      if (r.ok !== true) reply({ error: r.error }); else reply({ ok: true, kind: r.kind, plugin: r.id });
+      return undefined;
+    },
+  };
+}

package/host/planes/proc-tree.mjs

@@ -0,0 +1,76 @@
+// proc-tree.mjs — "kill everything this child started", for the two planes
+// that own children of their own (jobs, terminal).
+//
+// There is no ONE mechanism that does it, which is why this is a file and not
+// a line. Measured on 2026-09-14, both failures in the same afternoon:
+//
+//   · signalling the process GROUP alone misses a child in a group of its
+//     own — processx puts its children in a new one, and an interactive shell
+//     with job control puts every background job in one (`sleep 600 &`
+//     survived a group kill of the shell);
+//   · walking the DESCENDANTS alone misses a child that double-forked and was
+//     reparented to init — `system(..., wait = FALSE)` does exactly that, and
+//     the orphan is still in the group.
+//
+// So callers do both: `descendantsOf()` first, then the group, then the
+// leader. spike/kernel.R's `kernel_kill_tree()` does only the first half
+// (processx's `kill_tree()`, which finds children by its own environment
+// marker and therefore misses a grandchild another processx started).
+
+import { execFileSync } from "node:child_process";
+
+/**
+ * Every descendant of `pid`, nearest first — one `ps` and a breadth-first walk.
+ *
+ * Synchronous on purpose: it runs on a user gesture (Stop, a closed page, the
+ * kernel shutting down), it costs about ten milliseconds, and a kill that
+ * raced the read would be worse than one turn of the event loop. Bounded, so
+ * a pathological table — or a ppid cycle, which cannot happen but is cheap to
+ * refuse — cannot spin the host.
+ *
+ * @param {number} pid
+ * @param {number} [max] most descendants to return
+ * @returns {number[]}
+ */
+export function descendantsOf(pid, max = 2000) {
+  if (!pid || pid <= 0 || process.platform === "win32") return [];
+  let table = "";
+  try { table = execFileSync("/bin/ps", ["-Ao", "pid=,ppid="], { encoding: "utf8", timeout: 5000 }); } catch { return []; }
+  const children = new Map();
+  for (const line of table.split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)$/);
+    if (!m) continue;
+    const kid = Number(m[1]);
+    const parent = Number(m[2]);
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push(kid);
+  }
+  const out = [];
+  const seen = new Set([pid]);
+  const queue = [pid];
+  while (queue.length && out.length < max) {
+    const next = queue.shift();
+    for (const kid of children.get(next) || []) {
+      if (seen.has(kid)) continue;
+      seen.add(kid);
+      out.push(kid);
+      queue.push(kid);
+    }
+  }
+  return out;
+}
+
+/**
+ * SIGKILL a process and everything it started: descendants, then its process
+ * group, then the leader itself.
+ *
+ * @param {number} pid a process this host spawned DETACHED (so it leads its
+ *   own group) or that owns a pty session.
+ */
+export function killProcessTree(pid) {
+  if (!pid || pid <= 0) return;
+  for (const child of descendantsOf(pid)) { try { process.kill(child, "SIGKILL"); } catch { /* gone */ } }
+  if (process.platform === "win32") return;      // callers use taskkill /T there
+  try { process.kill(-pid, "SIGKILL"); } catch { /* the group is gone */ }
+  try { process.kill(pid, "SIGKILL"); } catch { /* the leader is gone */ }
+}