beatrina 0.8.6

package/host/planes/terminal.mjs

@@ -0,0 +1,286 @@
+// terminal.mjs — a pty shell in the kernel, owned by the PAGE.
+//
+// A port of `term_open`, `term_input`, `term_close`, `term_owned`,
+// `term_shell` and `pump_terms` in spike/serve.R, plus `term_resize`, which
+// carmapy added (`../carmar-python/docs/kernel-protocol.md` §3: "R only sizes
+// at open"). Both are served here; a page that never resizes behaves exactly
+// as it does against serve.R.
+//
+// The terminal is the FOURTH child, and it is the opposite of a job on
+// purpose:
+//   · it BELONGS to the socket that opened it — bytes stream to that socket
+//     alone, and `ws.onClose` kills the shell. A shell nobody can see is not
+//     a detached task, it is an orphan with the user's credentials.
+//   · it is page-only AND agent-refused. An agent runs code through
+//     chunk_run, visibly, or not at all; a terminal would be exactly the raw
+//     `exec` door the MCP plane refuses, wearing a prompt.
+//
+// What the shell can do is what the user can do; this grants nothing new and
+// is audited like every other door. `CARMAR_NO_TERMINAL=1` refuses it BY
+// NAME, with the reason, rather than dropping the frame — a dropped frame
+// reads as a hang, and lib/terminal.js already renders `event: "refused"`.
+//
+// The one dependency this package adds is `node-pty` (1.1.0), and it is the
+// reason there is no `script`/`expect` ladder here: a login shell without a
+// controlling terminal has no job control, no ^C, no prompt and no `pwd`
+// that a user would recognise. processx gave R the same thing.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { killProcessTree } from "./proc-tree.mjs";
+import { PIPE_NOTICE, pipeShell, pipeSpawn } from "./pipe-term.mjs";
+
+const MAX_TERMS = 4;
+const TERM_INPUT_MAX = 65536;
+const PAGE_ONLY = Object.freeze(["served", "file", "local"]);
+
+const scalarChr = (x) => typeof x === "string";
+const clamp = (x, lo, hi, fallback) => {
+  const v = Number.parseInt(x, 10);
+  return Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : fallback;
+};
+
+/**
+ * The shell to run and how to make it interactive. bash and zsh get a login
+ * shell so PATH matches the user's own terminal; sh gets -i.
+ */
+export function termShell(env = process.env, platform = process.platform) {
+  // Windows has no SHELL and no /bin/sh: ComSpec is the shell a user has.
+  if (platform === "win32") return { cmd: env.ComSpec || env.COMSPEC || "cmd.exe", args: [] };
+  let shell = env.SHELL || "";
+  if (!shell || !fs.existsSync(shell)) shell = "/bin/sh";
+  const base = path.basename(shell);
+  const args = ["bash", "zsh", "fish"].includes(base) ? ["-i", "-l"] : ["-i"];
+  return { cmd: shell, args };
+}
+
+/**
+ * How to start that shell on a pty with ECHO OFF.
+ *
+ * serve.R gets this from processx (`pty_options`, whose `echo` defaults to
+ * FALSE); node-pty has no such option and no termios binding, so the slave's
+ * mode is set by the one process that has the slave as its stdin — a `/bin/sh
+ * -c` that turns echo off and immediately `exec`s the real shell, keeping the
+ * pid, the controlling terminal and the argument vector.
+ *
+ * It is not cosmetic. `lib/terminal.js` has no terminal library: it draws the
+ * line being typed ITSELF, from its own input element, and renders what the
+ * shell emits underneath. With echo on, every keystroke appears twice.
+ *
+ * The wrapper is always `/bin/sh`, never the user's shell, because `$@` and
+ * `exec "$@"` are POSIX and fish is not; and the shell and its arguments
+ * travel as POSITIONAL PARAMETERS, so a path with a space or a quote in it is
+ * one argument and nothing is ever pasted into a shell string.
+ */
+export function termArgv(sh) {
+  if (process.platform === "win32") return { file: sh.cmd, args: sh.args };
+  return { file: "/bin/sh", args: ["-c", 'stty -echo 2>/dev/null; exec "$@"', "beatrina-terminal", sh.cmd, ...sh.args] };
+}
+
+/**
+ * Load node-pty, repairing the one packaging fault measured on this machine.
+ *
+ * node-pty 1.1.0 ships its darwin prebuild's `spawn-helper` WITHOUT the
+ * executable bit after `npm install` (measured 2026-09-14: mode 0644, and
+ * every `spawn` fails with "posix_spawnp failed" until it is 0755). The
+ * repair is one chmod on a file inside our own node_modules, done once, said
+ * out loud in the audit stream — not a swallowed retry: a terminal that fails
+ * for a reason nobody can see is worse than one that refuses in words.
+ */
+function loadPty(audit) {
+  // A packaged single executable has no module path and can load no native
+  // module, so it has no node-pty: the pipe terminal answers instead. Asking
+  // createRequire(undefined) here threw inside term_open and the page waited
+  // for an answer that never came.
+  if (!(typeof import.meta.url === "string" && import.meta.url.startsWith("file:"))) {
+    return { pty: null, error: "a packaged Beatrina executable cannot load node-pty" };
+  }
+  const require = createRequire(import.meta.url);
+  let entry;
+  try { entry = require.resolve("node-pty"); } catch { return { pty: null, error: "node-pty is not installed on this kernel." }; }
+  const root = path.dirname(path.dirname(entry));      // …/node-pty
+  const arch = `${process.platform}-${process.arch}`;
+  const helper = path.join(root, "prebuilds", arch, "spawn-helper");
+  try {
+    const st = fs.statSync(helper);
+    if (!(st.mode & 0o111)) { fs.chmodSync(helper, 0o755); audit("term-helper-chmod", { detail: helper }); }
+  } catch { /* no prebuild helper on this platform: node-pty will say so */ }
+  try { return { pty: require("node-pty"), error: "" }; } catch (e) { return { pty: null, error: `node-pty could not load: ${e.message}` }; }
+}
+
+// What a declared agent may never do here, in the op's own words (serve.R).
+const AGENT_REFUSED = Object.freeze({
+  term_open: "Agents cannot open a terminal; run code through chunk_run.",
+  term_input: "Agents cannot type into the user's terminal.",
+  term_resize: "Agents cannot resize the user's terminal.",
+  term_close: "Agents cannot close the user's terminal.",
+});
+
+export function createPlane({ env, audit }) {
+  /** @type {Map<string, {id: string, term: object, rec: object, pid: number, started: number, closing: boolean}>} */
+  const terms = new Map();
+  let seq = 0;
+  let loaded = null;                       // lazy: a kernel that never opens one pays nothing
+  let ctxRef = null;
+  const ctxPort = () => (ctxRef ? ctxRef.port() : 0);
+
+  const enc = (o) => JSON.stringify(o);
+  const send = (rec, id, fields) => { try { rec.ws.send(enc({ type: "term", id, ...fields })); } catch { /* the page is gone */ } };
+  const turnedOff = () => env("CARMAR_NO_TERMINAL") === "1";
+
+  /** Only the page that opened a terminal may type into it, resize it or close it. */
+  const owned = (rec, id) => {
+    const t = scalarChr(id) ? terms.get(id) : null;
+    return t && t.rec === rec ? t : null;
+  };
+
+  /**
+   * Kill the shell AND everything it started, and say so once.
+   *
+   * node-pty's own `kill()` signals the leader only, and the leader's group is
+   * not enough either: an interactive shell has JOB CONTROL, so `sleep 600 &`
+   * lives in a process group of its own and survived a group kill of the shell
+   * (measured 2026-09-14). `killProcessTree` walks the descendants first for
+   * exactly that case. serve.R kills the shell process and leaves the
+   * background child running.
+   */
+  const closeTerm = (id, why = "closed") => {
+    const t = terms.get(id);
+    if (!t || t.closing) return;
+    t.closing = true;
+    terms.delete(id);
+    killProcessTree(t.pid);
+    try { t.term.kill("SIGKILL"); } catch { /* already reaped */ }
+    audit("term-close", { id, detail: why });
+    send(t.rec, id, { event: "exit", code: null, reason: why });
+  };
+
+  function termOpen(cmd, rec) {
+    const refuse = (why) => {
+      audit("term-refused", { detail: why });
+      send(rec, "", { event: "refused", error: why });
+    };
+    if (turnedOff()) return refuse("The terminal is turned off on this kernel (CARMAR_NO_TERMINAL=1).");
+    // serve.R refuses Windows outright ("CarmaR does not provide a pty on
+    // Windows yet"), because processx has none there. node-pty ships ConPTY
+    // prebuilds, so the refusal is no longer true by construction — the
+    // platform is not asked, the loader is, and it says so if the prebuild
+    // for this platform is missing. (docs/host-plan.md §1, "Windows".)
+    const mine = [...terms.values()].filter((t) => t.rec === rec);
+    if (mine.length >= MAX_TERMS) return refuse(`${mine.length} terminals are already open on this page.`);
+    // node-pty first; with none (every installed R package: it is a native
+    // module) the pipe terminal in pipe-term.mjs. CARMAR_TERMINAL_PTY=0 forces
+    // the pipe, which is how a machine that HAS node-pty tests the other rung.
+    if (!loaded) loaded = env("CARMAR_TERMINAL_PTY") === "0" ? { pty: null, error: "CARMAR_TERMINAL_PTY=0" } : loadPty(audit);
+
+    const cols = clamp(cmd.cols, 20, 400, 100);
+    const rows = clamp(cmd.rows, 5, 200, 30);
+    let wd = process.cwd();
+    if (scalarChr(cmd.cwd) && cmd.cwd) {
+      try { if (fs.statSync(cmd.cwd).isDirectory()) wd = cmd.cwd; } catch { /* keep the kernel's cwd */ }
+    }
+    const usePipe = !loaded.pty;
+    const sh = usePipe ? pipeShell(process.env) : termShell(process.env);
+    const argv = usePipe ? { file: sh.cmd, args: sh.args } : termArgv(sh);
+    // The shell runs in the PHYSICAL directory (processx resolves the wd for
+    // serve.R, and `pwd` in the shell must agree with what the page shows);
+    // the frame reports the path the page ASKED for, which is what serve.R
+    // echoes back and what lib/terminal.js labels the tab with.
+    let real = wd;
+    try { real = fs.realpathSync(wd); } catch { real = wd; }
+    let term;
+    try {
+      term = usePipe
+        ? pipeSpawn(argv.file, argv.args, { cwd: real,
+          env: { ...process.env, TERM: "dumb", COLUMNS: String(cols), LINES: String(rows), CARMAR_PORT: String(ctxPort()) } })
+        : loaded.pty.spawn(argv.file, argv.args, {
+          name: "xterm-256color", cols, rows, cwd: real,
+          env: { ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor",
+            COLUMNS: String(cols), LINES: String(rows), CARMAR_PORT: String(ctxPort()) },
+        });
+    } catch (e) { return refuse(`the shell could not start: ${e.message}`); }
+
+    seq += 1;
+    const id = `term-${seq}`;
+    const t = { id, term, rec, pid: term.pid, started: Date.now() / 1000, closing: false };
+    terms.set(id, t);
+    // Streamed straight to the OWNING socket. No pump: node-pty is
+    // event-driven, so the R supervisor's `pump_terms()` turn has no
+    // counterpart here — the bytes arrive when the shell writes them.
+    term.onData((data) => { if (!t.closing) send(rec, id, { event: "data", text: data }); });
+    term.onExit(({ exitCode }) => {
+      if (t.closing) return;
+      t.closing = true;
+      terms.delete(id);
+      audit("term-exit", { id, detail: String(exitCode) });
+      send(rec, id, { event: "exit", code: exitCode ?? null, reason: "exited" });
+    });
+    audit("term-open", { id, detail: sh.cmd, class: rec.class ?? "unknown", pty: !usePipe });
+    send(rec, id, { event: "open", shell: sh.cmd, pid: term.pid, cols, rows, cwd: wd, pty: !usePipe });
+    if (usePipe) {
+      if (loaded.error) audit("term-pipe", { id, detail: loaded.error });
+      send(rec, id, { event: "data", text: PIPE_NOTICE });
+    }
+  }
+
+  return {
+    name: "terminal",
+    ops: ["term_open", "term_input", "term_resize", "term_close"],
+    // Answered here, not through the seam's list: the R replies in the op's
+    // own words and a suite pins them (test/terminal.test.mjs).
+    agentRefused: [],
+    // serve.R advertises no terminal verb in ready.commands; neither does this.
+    // A kernel with CARMAR_NO_TERMINAL=1 still answers the op — with a refusal
+    // that names the reason, which is what the pane renders.
+    commands: [],
+    capabilities: [],
+
+    init(ctx) { ctxRef = ctx; },
+
+    handle(cmd, rec, ctx) {
+      ctxRef = ctx;
+      const type = cmd.type;
+      if (rec.role === "mcp") {
+        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;
+      }
+      if (rec.role !== "page") return;
+      // Page-only in BOTH senses: a declared agent is refused above, and a
+      // client that merely never declared is refused here by the CLASS the
+      // upgrade gate proved.
+      if (!PAGE_ONLY.includes(rec.class)) {
+        audit("term-refused", { reason: "class", class: rec.class ?? "unknown" });
+        send(rec, cmd.id ?? "", { event: "refused", error: "Only the local notebook page may open a terminal." });
+        return;
+      }
+      if (type === "term_open") return termOpen(cmd, rec);
+      const t = owned(rec, cmd.id);
+      if (!t) return;
+      if (type === "term_input") {
+        if (!scalarChr(cmd.text) || !cmd.text) return;
+        if (Buffer.byteLength(cmd.text) > TERM_INPUT_MAX) return;
+        try { t.term.write(cmd.text); } catch { /* the shell has gone; onExit says so */ }
+        return;
+      }
+      if (type === "term_resize") {
+        const cols = clamp(cmd.cols, 20, 400, 100);
+        const rows = clamp(cmd.rows, 5, 200, 30);
+        // The ioctl is what makes the kernel deliver SIGWINCH to the
+        // foreground group, so nothing is signalled by hand here.
+        try { t.term.resize(cols, rows); } catch { /* the shell has gone */ }
+        return;
+      }
+      if (type === "term_close") closeTerm(cmd.id, "closed");
+    },
+
+    /** A terminal dies with the socket that opened it. */
+    onClose(rec) {
+      for (const [id, t] of [...terms]) if (t.rec === rec) closeTerm(id, "page closed");
+    },
+
+    /** The kernel is going away; no shell may outlive it. */
+    shutdown() { for (const id of [...terms.keys()]) closeTerm(id, "kernel stopping"); },
+  };
+}

package/host/planes/test-file.mjs

@@ -0,0 +1,80 @@
+// test-file.mjs — File ▾ ▸ Open Test File: a known document, one click away.
+//
+// The product ships one real-world R Markdown document beside the kernel files
+// (`<kernel>/examples/tna-complete-tutorial.Rmd`, the tna package's complete
+// tutorial — spike/examples/NOTICE.md carries its source and MIT license). This
+// plane answers `test_file` with a path the page opens like any other document.
+//
+// THE PATH IS A COPY, NEVER THE SHIPPED FILE. The shipped copy lives inside the
+// app bundle or the installed package, which a Save must not write into (and on
+// an installed Mac cannot). So the first ask copies it to
+// `R_user_dir("carmar", "data")/test-files/` and every later ask returns that
+// copy UNTOUCHED — edits a person made to it are theirs, and a menu row that
+// silently reverted them would be the wrong kind of "always there". A copy that
+// was deleted comes back on the next click. `fresh: true` asks for a new copy
+// beside it rather than over it.
+//
+// Page-only in both senses: it writes a file, and an agent that wants to read
+// the tutorial can ask the page to open it.
+
+import fs from "node:fs";
+import path from "node:path";
+import { appId, ensureUserDir } from "../user-dirs.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
+
+export const TEST_FILE_NAME = "tna-complete-tutorial.Rmd";
+const OPS = ["test_file"];
+
+/**
+ * Resolve (and if needed create) the user's copy of the shipped test file.
+ * @param {string} kernelDir  the directory holding examples/
+ * @param {{fresh?: boolean}} [opts]
+ * @returns {{ok: true, path: string, created: boolean} | {ok: false, error: string}}
+ */
+export function testFileCopy(kernelDir, { fresh = false } = {}) {
+  const source = path.join(kernelDir, "examples", TEST_FILE_NAME);
+  if (!fs.existsSync(source)) {
+    return { ok: false, error: "This CarmaR does not carry its test file (examples/tna-complete-tutorial.Rmd is missing). Reinstall CarmaR." };
+  }
+  const dir = path.join(ensureUserDir(appId(), "data"), "test-files");
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) { return { ok: false, error: `Could not create ${dir}: ${e.message}` }; }
+  let dest = path.join(dir, TEST_FILE_NAME);
+  if (fresh && fs.existsSync(dest)) {
+    const stem = TEST_FILE_NAME.replace(/\.Rmd$/, "");
+    let n = 2;
+    while (fs.existsSync(path.join(dir, `${stem}-${n}.Rmd`))) n += 1;   // a wait for a free name is a loop
+    dest = path.join(dir, `${stem}-${n}.Rmd`);
+  }
+  if (fs.existsSync(dest)) return { ok: true, path: dest, created: false };
+  try {
+    fs.copyFileSync(source, dest, fs.constants.COPYFILE_EXCL);
+  } catch (e) {
+    return { ok: false, error: `Could not copy the test file to ${dir}: ${e.message}` };
+  }
+  return { ok: true, path: dest, created: true };
+}
+
+export function createPlane({ spike, audit }) {
+  return {
+    name: "test-file",
+    ops: OPS,
+    agentRefused: OPS,
+    agentReason: () => "Agents cannot write the test file into the user's data folder; ask the page to open it.",
+    commands: OPS,
+    capabilities: ["test-file-v1"],
+    handle(cmd, rec, ctx) {
+      if (rec.role !== "page" || !ctx.scalarChr(cmd.id)) return undefined;
+      const reply = (fields) => rec.ws.send(ctx.enc({ type: "test_file", id: cmd.id, ...fields }));
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("test-file-refused", { reason: "class", class: rec.class || "unknown" });
+        return reply({ error: "Only the local notebook page may ask this." });
+      }
+      const out = testFileCopy(spike, { fresh: cmd.fresh === true });
+      if (out.ok !== true) return reply({ error: out.error });
+      audit("test-file", { created: out.created });
+      return reply({ path: out.path, created: out.created });
+    },
+  };
+}
+
+export default { createPlane };

package/host/planes/update.mjs

@@ -0,0 +1,214 @@
+// update.mjs — signed product updates: two ops, and a very narrow API.
+//
+// A port of the `update_*` half of spike/serve.R. The updater is a
+// PRODUCT-OWNED SCRIPT injected by the launcher (`CARMAR_UPDATE_SCRIPT`). The
+// browser never supplies a path or a command line: it may name one action from
+// a fixed four-word vocabulary, and the supervisor starts that exact script
+// directly, as an argument vector.
+//
+// Nothing here reaches the network. The host does not check for updates, does
+// not poll a feed and has no clock of its own — that belongs to the R package's
+// `check_upgrade()`, once a day, at a door the person opened. All this plane
+// can do is read the script's six-field status record and ask it to act, which
+// is why `CARMAR_NO_UPDATE_CHECK=1` holds here trivially: with no script there
+// is no process, and with a script there is still no feed.
+//
+// Who may ask: page-only in BOTH senses (agentRefused at the seam,
+// PAGE_ONLY_CLASSES here) and loopback-only. A remote or shared kernel is
+// updated by its fleet operator, and a native socket does not get a UI gesture
+// by pretending to be the person looking at the settings pane.
+//
+// One transcription note. `processx::run(timeout = 5000)` in serve.R is FIVE
+// THOUSAND SECONDS, not five: processx counts seconds. That is effectively no
+// timeout at all, and it blocks the R loop while it runs. The same number is
+// used here (as milliseconds × 1000) rather than quietly tightened, because a
+// status read that takes ninety seconds on one machine and is killed on the
+// other is a difference between the two backends that nobody asked for.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+
+const PAGE_ONLY_CLASSES = ["served", "file", "local"];
+const OPS = ["update_status", "update_action"];
+const AGENT_WHY = {
+  update_status: "Agents cannot inspect desktop update state.",
+  update_action: "Agents cannot install, defer, or roll back CarmaR.",
+};
+const ACTIONS = ["check", "defer", "install", "rollback"];
+const STATES = ["unknown", "current", "available", "deferred", "installing",
+  "rolling-back", "error", "offline", "refused", "unconfigured"];
+/** serve.R's `timeout = 5000` is processx seconds. */
+const STATUS_TIMEOUT_MS = 5000 * 1000;
+/** A running action older than this is killed; serve.R's own ceiling. */
+const ACTION_MAX_S = 360;
+
+/** The interpreter that runs the updater, or null when this platform has none. */
+export function updateRunnerSpec(script, args = [], platform = process.platform) {
+  if (platform === "win32") {
+    const found = ["powershell.exe", "powershell"].map((name) => whichSync(name)).find(Boolean);
+    if (!found || !/\.ps1$/i.test(script)) return null;
+    return { command: found, args: ["-NoLogo", "-NoProfile", "-NonInteractive",
+      "-ExecutionPolicy", "Bypass", "-File", script, ...args] };
+  }
+  if (!fs.existsSync("/bin/sh")) return null;
+  return { command: "/bin/sh", args: [script, ...args] };
+}
+
+function whichSync(name) {
+  for (const dir of String(process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    const cand = path.join(dir, name);
+    try { fs.accessSync(cand, fs.constants.X_OK); return cand; } catch { /* next */ }
+  }
+  return "";
+}
+
+// eslint-disable-next-line no-control-regex
+const updateText = (x, max = 240) => String(x ?? "").replace(/[\x00-\x1f\x7f]/g, " ").slice(0, max).trim();
+const updateVersion = (x) => {
+  const value = updateText(x, 64);
+  return /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/.test(value) ? value : "";
+};
+
+export function createPlane({ env, audit }) {
+  const job = { proc: null, action: "", started: 0 };
+
+  const scriptPath = (deployment) => {
+    const script = env("CARMAR_UPDATE_SCRIPT", "").trim();
+    if (deployment.loopback !== true || !script || !fs.existsSync(script)) return "";
+    const real = fs.realpathSync(script);
+    return updateRunnerSpec(real) ? real : "";
+  };
+
+  const busy = () => {
+    if (!job.proc) return false;
+    let alive = job.proc.exitCode === null && job.proc.signalCode === null;
+    if (alive && job.started && (Date.now() - job.started) / 1000 > ACTION_MAX_S) {
+      try { job.proc.kill("SIGKILL"); } catch { /* gone */ }
+      alive = false;
+      audit("update-timeout", { detail: job.action });
+    }
+    if (!alive) { job.proc = null; job.action = ""; }
+    return alive;
+  };
+
+  /**
+   * Read the updater's deliberately small status record.
+   *
+   * The FOURTH tab-separated field is an installer PATH, and it is discarded on
+   * purpose: the settings page needs state and versions, not a map of the
+   * user's disk.
+   */
+  const statusState = (deployment, kernelBuild) => {
+    const script = scriptPath(deployment);
+    if (!script) {
+      return { supported: false, state: "unavailable", current: kernelBuild,
+        offered: "", previous: "", busy: false, action: "",
+        can_check: false, can_update: false, can_defer: false, can_rollback: false,
+        message: "Signed desktop updates are not available in this deployment." };
+    }
+    if (busy()) {
+      return { supported: true, state: "checking", current: kernelBuild,
+        offered: "", previous: "", busy: true, action: job.action,
+        can_check: false, can_update: false, can_defer: false, can_rollback: false,
+        message: {
+          check: "Checking and verifying the signed update…",
+          install: "Opening the verified installer…",
+          rollback: "Opening the last-known-good installer…",
+          defer: "Saving the defer choice…",
+        }[job.action] || "Working…" };
+    }
+    const spec = updateRunnerSpec(script, ["status"]);
+    let ran = null;
+    try { ran = spawnSync(spec.command, spec.args, { encoding: "utf8", timeout: STATUS_TIMEOUT_MS }); }
+    catch { ran = null; }
+    const line = ran && ran.status === 0 ? String(ran.stdout || "").split("\n")[0] : "";
+    const fields = line ? line.split("\t") : [];
+    const at = (i) => (fields.length >= i ? fields[i - 1] : "");
+    let state = updateText(at(1), 32);
+    if (!STATES.includes(state)) state = "error";
+    const current = updateVersion(at(2));
+    const offered = updateVersion(at(3));
+    const previous = updateVersion(at(5));
+    let message = updateText(at(6));
+    if (!message) {
+      message = state === "error" ? "The signed updater did not return a valid status."
+        : "Update status is available.";
+    }
+    return { supported: true, state, current, offered, previous, busy: false, action: "",
+      can_check: state !== "unconfigured",
+      can_update: state === "available" && Boolean(offered),
+      can_defer: ["current", "available", "deferred", "offline"].includes(state),
+      can_rollback: state !== "unconfigured" && Boolean(previous),
+      message };
+  };
+
+  const startAction = (deployment, kernelBuild, action, daysRaw) => {
+    const script = scriptPath(deployment);
+    if (!script) {
+      return { ok: false, reason: "unavailable", error: "Signed desktop updates are not available in this deployment." };
+    }
+    if (!ACTIONS.includes(action)) return { ok: false, reason: "action", error: "No such update action." };
+    if (busy()) return { ok: false, reason: "busy", error: "Another update action is still running." };
+
+    const status = statusState(deployment, kernelBuild);
+    if (action === "check" && status.can_check !== true) return { ok: false, reason: "state", error: status.message };
+    if (action === "defer" && status.can_defer !== true) {
+      return { ok: false, reason: "state", error: "Update checks cannot be deferred in the current state." };
+    }
+    if (action === "install" && status.can_update !== true) return { ok: false, reason: "state", error: "No verified update is ready." };
+    if (action === "rollback" && status.can_rollback !== true) {
+      return { ok: false, reason: "state", error: "No last-known-good version is available." };
+    }
+    let days = null;
+    if (action === "defer") {
+      days = Number.parseInt(daysRaw, 10);
+      if (!Number.isInteger(days) || days < 1 || days > 30) {
+        return { ok: false, reason: "days", error: "Defer days must be from 1 to 30." };
+      }
+    }
+    const spec = updateRunnerSpec(script, action === "defer" ? [action, String(days)] : [action]);
+    let proc = null;
+    try {
+      proc = spawn(spec.command, spec.args, { stdio: ["ignore", "ignore", "ignore"], detached: false });
+    } catch { proc = null; }
+    if (!proc) return { ok: false, reason: "start", error: "The signed updater could not be started." };
+    proc.on("error", () => { /* a failed spawn ends the job like any other exit */ });
+    job.proc = proc;
+    job.action = action;
+    job.started = Date.now();
+    audit("update-action", { detail: action });
+    return { ok: true, accepted: true, action };
+  };
+
+  return {
+    name: "update",
+    ops: OPS,
+    agentRefused: OPS,
+    agentReason: (op) => AGENT_WHY[op],
+    commands: OPS,
+    capabilities: ["signed-updates-v1"],
+
+    handle(cmd, rec, ctx) {
+      const { enc, scalarChr, deployment } = ctx;
+      if (!scalarChr(cmd.id)) return undefined;
+      const reply = (payload) => rec.ws.send(enc({ type: cmd.type, id: cmd.id, ...payload }));
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("update-refused", { reason: "class", class: rec.class || "unknown" });
+        reply({ ok: false, reason: "class", error: "Only the local notebook page may manage desktop updates." });
+        return undefined;
+      }
+      if (deployment.loopback !== true) {
+        audit("update-refused", { reason: "posture", class: rec.class || "unknown" });
+        reply({ ok: false, reason: "posture", error: "This deployment is updated by its administrator." });
+        return undefined;
+      }
+      if (cmd.type === "update_status") {
+        reply(statusState(deployment, ctx.kernelBuild));
+      } else {
+        reply(startAction(deployment, ctx.kernelBuild, scalarChr(cmd.action) ? cmd.action : "", cmd.days ?? null));
+      }
+      return undefined;
+    },
+  };
+}