beatrina 0.8.6

package/host/planes/sessions.mjs

@@ -0,0 +1,434 @@
+// sessions.mjs — the sessions plane: which kernels this user is running, which
+// R installations the machine has, and starting another session.
+//
+// A port of serve.R's `session_list`, `r_versions` / `current_rscript`,
+// `live_session_ports` / `start_sibling_session` and the `session-new` op.
+// Page-only: a list of the user's running kernels and of the R installations
+// on the machine is a map of the desk, not something a native client or an
+// agent needs the kernel to draw for it (serve.R keeps `session_list` and
+// `r_versions` in AGENT_REFUSED for exactly that reason).
+//
+// The runtime RECORD itself is main.mjs's (it owns the file's lifetime and
+// the `page-title` write); this plane only READS the directory, so a session
+// started by a launcher or by the R package counts too. A killed kernel leaves
+// its file behind, which is why every row is health-checked before it is
+// believed.
+//
+// THE HANDOFF: `session_upgrade` and `session_restart`, plus their native doors
+// POST /session/upgrade and POST /session/restart. A port of serve.R's
+// handoff_refusal / session_handoff_begin / session_handoff_spawn: a successor
+// supervisor is started on the SAME port from the files beside this one (after
+// an in-place upgrade, the installed build's), every page is told where its
+// successor's notebook is, the worker's whole tree is killed, and this process
+// exits. The successor's R is FRESH — no save.image() bridge, by decision
+// (docs/upgrade.md); a restart says so and does not pretend otherwise.
+//
+// `CARMAR_SESSION_BASE` is Beatrix's only addition to the wire's behaviour
+// here: serve.R hardcodes the 4747..4947 scan, and a TEST may not bind 4747
+// (FORK.md), so the base is readable from the environment and defaults to
+// 4747 — the published-page port, fixed because browsers key storage to the
+// ORIGIN and a session that moved ports would greet its reader with an empty
+// notebook.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { PAGE_ONLY_CLASSES, secureToken } from "../server.mjs";
+import { stateDir } from "../user-dirs.mjs";
+
+export const SESSION_OPS = Object.freeze(["session_list", "r_versions", "session-new"]);
+export const HANDOFF_OPS = Object.freeze(["session_upgrade", "session_restart"]);
+/** How many ports above the base a new session may take (serve.R: 4747..4947). */
+export const SESSION_BAND = 201;
+
+const RUNTIME_NAME = /^kernel-([0-9]+)\.json$/;
+
+/** The runtime directory both supervisors write their records into. */
+export function runtimeDir(env) {
+  return env("CARMAR_RUNTIME_DIR") || path.join(os.homedir(), ".carmar", "run");
+}
+
+/** Every `kernel-<port>.json` in the runtime directory, parsed; unreadable ones dropped. */
+export function runtimeRecords(env) {
+  const dir = runtimeDir(env);
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of names) {
+    const m = RUNTIME_NAME.exec(name);
+    if (!m) continue;
+    let rec = null;
+    try { rec = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8")); } catch { rec = null; }
+    if (!rec || typeof rec !== "object" || rec.port == null || rec.url == null) continue;
+    const port = Number.parseInt(rec.port, 10);
+    if (!Number.isInteger(port)) continue;
+    out.push({ ...rec, port });
+  }
+  return out.sort((a, b) => a.port - b.port);
+}
+
+/**
+ * Is a kernel actually answering on `url`?
+ *
+ * ONE SECOND, not sixty. serve.R learned this the hard way: a port squatted by
+ * something that accepts TCP and never answers froze routing for every
+ * connected page for a full minute per port.
+ */
+export async function healthy(url, timeoutMs = 1000) {
+  const target = `${String(url).replace(/\/+$/, "")}/health`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(target, { signal: ctrl.signal, cache: "no-store" });
+    if (!res.ok) return false;
+    return (await res.text()).includes('"ok":true');
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The ports of kernels that are answering right now (ourselves, definitionally). */
+export async function liveSessionPorts(env, ownPort) {
+  const recs = runtimeRecords(env);
+  const checked = await Promise.all(recs.map(async (rec) => ({
+    port: rec.port,
+    alive: rec.port === ownPort ? true : await healthy(rec.url),
+  })));
+  return checked.filter((r) => r.alive).map((r) => r.port);
+}
+
+// ── R installations ────────────────────────────────────────────────────────
+
+/** Every path under one child level of `dir` that ends in `tail` — the one glob shape the ladder needs. */
+function globOneLevel(dir, tail) {
+  let kids = [];
+  try { kids = fs.readdirSync(dir); } catch { return []; }
+  return kids.map((k) => path.join(dir, k, tail)).filter((p) => fs.existsSync(p));
+}
+
+/** `Sys.which("Rscript")`: the first Rscript on PATH. */
+function whichRscript(env) {
+  const exe = process.platform === "win32" ? "Rscript.exe" : "Rscript";
+  for (const dir of String(env("PATH") || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const cand = path.join(dir, exe);
+    try { fs.accessSync(cand, fs.constants.X_OK); return cand; } catch { /* next */ }
+  }
+  return "";
+}
+
+/**
+ * Every R installation on this machine, with its version — serve.R's ladder,
+ * kept in its order. Read once per kernel life: each probe spawns a process.
+ * @returns {Array<{path: string, version: string, current: boolean}>} newest first
+ */
+export function rVersions(env, currentPath, execFileSync) {
+  const cands = [
+    ...globOneLevel("/Library/Frameworks/R.framework/Versions", "Resources/bin/Rscript"),
+    ...globOneLevel("/opt/R", "bin/Rscript"),
+    ...globOneLevel("/opt/homebrew/Cellar/r", "bin/Rscript"),
+    "/opt/homebrew/bin/Rscript", "/usr/local/bin/Rscript", "/opt/local/bin/Rscript",
+    "/usr/bin/Rscript", "/usr/lib/R/bin/Rscript",
+    ...globOneLevel("/usr/lib", "bin/Rscript").filter((p) => /\/R-[^/]*\/bin\/Rscript$/.test(p)),
+    whichRscript(env),
+  ].filter((p) => p && fs.existsSync(p));
+  const seenPath = new Set();
+  const unique = cands.filter((p) => (seenPath.has(p) ? false : (seenPath.add(p), true)));
+  // `Versions/Current` and a Homebrew symlink point at a versioned install
+  // already in the list: one entry per REAL binary, preferring the versioned
+  // path because it says which R it is.
+  const seenReal = new Set();
+  const rows = [];
+  for (const p of unique) {
+    let real = p;
+    try { real = fs.realpathSync(p); } catch { real = p; }
+    if (seenReal.has(real)) continue;
+    seenReal.add(real);
+    let version = "";
+    try {
+      const out = String(execFileSync(p, ["--version"], { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"] }));
+      const hit = /[0-9]+\.[0-9]+\.[0-9]+/.exec(out);
+      version = hit ? hit[0] : "";
+    } catch (e) {
+      // R < 3.3 printed --version to stderr and exited non-zero; read what came.
+      const out = `${(e && e.stdout) || ""}${(e && e.stderr) || ""}`;
+      const hit = /[0-9]+\.[0-9]+\.[0-9]+/.exec(out);
+      version = hit ? hit[0] : "";
+    }
+    rows.push({ path: p, version, current: real === currentPath });
+  }
+  rows.sort((a, b) => (a.version < b.version ? 1 : a.version > b.version ? -1 : (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)));
+  return rows;
+}
+
+// ── the plane ──────────────────────────────────────────────────────────────
+
+export function createPlane({ root, env, audit }) {
+  // How to start ANOTHER host. A source checkout or an installed package runs
+  // `node host/main.mjs`; a packaged single executable has no module path
+  // (the cjs bundle empties import.meta, and fileURLToPath(undefined) threw at
+  // boot — every SEA build since this plane landed failed to start, found
+  // 2026-09-15 running tools/beatrina/acceptance.mjs --binary) and IS the host,
+  // so it starts itself with no script.
+  const metaUrl = import.meta.url;
+  const mainPath = typeof metaUrl === "string" && metaUrl.startsWith("file:")
+    ? path.join(path.dirname(path.dirname(fileURLToPath(metaUrl))), "main.mjs") : "";
+  const siblingArgs = mainPath ? [mainPath] : [];
+  let versionsCache = null;
+
+  const sessionBase = (() => {
+    const given = Number.parseInt(env("CARMAR_SESSION_BASE", "4747"), 10);
+    return Number.isInteger(given) && given >= 1024 && given <= 65000 ? given : 4747;
+  })();
+
+  /**
+   * Start another supervisor on the next free adjacent port.
+   *
+   * Adjacent and stable on purpose (browsers key storage to the origin), and
+   * DETACHED — closing this session must not close that one. The port is a
+   * PREFERENCE, not a promise: between the probe and the child's own bind the
+   * port can go, so what is waited for is a NEW live port, whichever appears.
+   * serve.R learned that too: waiting for the exact port reported failure for
+   * a session that had started perfectly well, and orphaned it.
+   */
+  const startSibling = async (ctx) => {
+    const own = ctx.port();
+    const used = new Set(await liveSessionPorts(env, own));
+    let chosen = null;
+    for (let p = sessionBase; p <= sessionBase + SESSION_BAND - 1; p += 1) {
+      if (!used.has(p)) { chosen = p; break; }
+    }
+    if (chosen == null) return null;
+    const before = new Set(await liveSessionPorts(env, own));
+    // The pipes go to a FILE, not to a pipe nobody reads: a detached sibling
+    // wedges once ~64 KB of stderr accumulates in an unread buffer.
+    let logFd = "ignore";
+    try {
+      logFd = fs.openSync(path.join(os.tmpdir(), `beatrix-session-${process.pid}-${chosen}.log`), "a");
+    } catch { logFd = "ignore"; }
+    let child;
+    try {
+      child = spawn(process.execPath, siblingArgs, {
+        cwd: root,
+        env: { ...process.env, CARMAR_PORT: String(chosen) },
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+      });
+      child.unref();
+    } catch { return null; }
+    const deadline = Date.now() + 60000;
+    while (Date.now() < deadline) {
+      const fresh = (await liveSessionPorts(env, own)).filter((p) => !before.has(p));
+      if (fresh.length) {
+        const got = fresh[0];
+        const rec = runtimeRecords(env).find((r) => r.port === got);
+        return { port: got, url: rec ? rec.url : `http://127.0.0.1:${got}/` };
+      }
+      if (child.exitCode !== null || child.signalCode !== null) return null;
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    return null;
+  };
+
+  // ── the handoff ─────────────────────────────────────────────────────────
+  let handoff = null;
+
+  /** Why a handoff may not begin, or null. serve.R's table, reason words included. */
+  const handoffRefusal = (ctx, mode, force) => {
+    const refuse = (error, reason) => ({ error, reason });
+    const installed = ctx.installedBuild();
+    if (!installed || installed === "unknown") return refuse("This kernel cannot tell which CarmaR is installed.", "unknown-install");
+    if (mode === "upgrade" && installed === ctx.kernelBuild) {
+      return refuse(`This session already runs the installed CarmaR ${installed}.`, "same-build");
+    }
+    if (!ctx.notebookPage(installed)) {
+      return refuse(`The installed CarmaR ${installed} has no notebook page beside this kernel.`, "no-page");
+    }
+    // An attempt that has spawned owns the port until this process exits.
+    if (handoff) return refuse("A session restart is already under way.", "under-way");
+    if (force && mode === "restart") return null;
+    const pl = ctx.plane;
+    if ((pl.running && pl.running.size > 0) || (pl.primary ? pl.primary.active != null : pl.active != null)) {
+      return refuse("R is busy — wait for the running chunk, or interrupt it, then try again.", "busy");
+    }
+    const planes = pl.planes ? [...pl.planes.values()] : [pl];
+    if (planes.some((p) => p.debugPaused || p.inputWaiting)) {
+      return refuse("R is waiting at a prompt — finish it first.", "prompt");
+    }
+    return null;
+  };
+
+  /** The command that starts a supervisor of THIS kind from the files beside this one. */
+  const successorCommand = () => {
+    const script = process.argv[1] && /main\.mjs$/.test(process.argv[1]) ? process.argv[1] : "";
+    return script ? { cmd: process.execPath, args: [script] } : { cmd: process.execPath, args: [] };
+  };
+
+  const handoffBegin = (ctx, mode = "upgrade", force = false) => {
+    mode = mode === "restart" ? "restart" : "upgrade";
+    force = force === true && mode === "restart";
+    const auditName = mode === "restart" ? "session-restart" : "session-upgrade";
+    const why = handoffRefusal(ctx, mode, force);
+    if (why) {
+      audit(`${auditName}-refused`, { reason: why.reason, force });
+      return { ok: false, error: why.error, reason: why.reason };
+    }
+    const installed = ctx.installedBuild();
+    const cap = secureToken(32);
+    const page = ctx.notebookFileUrl(ctx.notebookPage(installed), ctx.port(), cap);
+    const started = ctx.startedSeconds;
+    handoff = { to: installed, cap, page, mode, force };
+    audit(auditName, { from: ctx.kernelBuild, to: installed, force });
+    // Every page learns where its successor's notebook is — over the gated
+    // socket only; the capability never appears in /health. `started` is this
+    // kernel's boot time: a page recognises its successor by a LATER one, the
+    // only test that also works when the build does not change.
+    const told = ctx.enc({ type: "session-upgrade", from: ctx.kernelBuild, to: installed, page, started, mode, force });
+    ctx.pageRecs().forEach((r) => { try { r.ws.send(told); } catch { /* gone */ } });
+    const spawned = handoffSpawn(ctx);
+    if (!spawned) return { ok: false, error: "The installed CarmaR could not be started.", reason: "spawn" };
+    return { ok: true, from: ctx.kernelBuild, to: installed, page, started, mode, force };
+  };
+
+  const handoffAbandon = (ctx, reason) => {
+    audit("session-upgrade-failed", { reason });
+    handoff = null;
+    const told = ctx.enc({ type: "session-upgrade-failed", error: reason });
+    ctx.pageRecs().forEach((r) => { try { r.ws.send(told); } catch { /* gone */ } });
+  };
+
+  /** Start the successor on this port, kill the worker tree, and leave. */
+  const handoffSpawn = (ctx) => {
+    const h = handoff;
+    const dir = stateDir();
+    try { fs.mkdirSync(dir, { recursive: true }); } catch { /* the log is a courtesy */ }
+    const port = ctx.port();
+    const record = ctx.runtimeRecord();
+    const childEnv = { ...process.env,
+      CARMAR_PORT: String(port), CARMAR_WAIT_PORT: "30",
+      // A successor that quietly moved to a free port would leave the page
+      // polling a dead one; strict means it refuses and its log says why.
+      CARMAR_PORT_STRICT: "1",
+      CARMAR_FILE_LAUNCH_CAP: h.cap, CARMAR_HANDOFF_FROM: ctx.kernelBuild,
+      CARMAR_SESSION_TITLE: record.title || "" };
+    if (record.listen) childEnv.CARMAR_LISTEN = "1"; else delete childEnv.CARMAR_LISTEN;
+    let out = "ignore";
+    try { out = fs.openSync(path.join(dir, `kernel-handoff-${port}.log`), "a"); } catch { out = "ignore"; }
+    let child = null;
+    try {
+      const { cmd, args } = successorCommand();
+      child = spawn(cmd, args, { env: childEnv, stdio: ["ignore", out, out], detached: true });
+      child.unref();
+    } catch { child = null; }
+    if (typeof out === "number") { try { fs.closeSync(out); } catch { /* closed */ } }
+    if (!child || !child.pid) { handoffAbandon(ctx, "The installed CarmaR could not be started."); return false; }
+    audit("session-upgrade-spawned", { to: h.to, pid: child.pid, mode: h.mode });
+    // Spawn first, kill second: the worker's whole process GROUP goes down only
+    // once the successor exists, so a failed spawn leaves the session untouched.
+    // The group kill reaches the shell grandchildren a hung R never signals.
+    const planes = ctx.plane.planes ? [...ctx.plane.planes.values()] : [ctx.plane];
+    for (const pl of planes) {
+      pl.expectedExit = true;
+      try { pl.failRoutes("R was stopped for a session restart — this run was abandoned."); } catch { /* none */ }
+      try { if (pl.engine && pl.alive) pl.engine.kill(); } catch { /* gone */ }
+    }
+    // Deferred, so the reply and the broadcast flush before the sockets close.
+    setTimeout(() => ctx.shutdown("session handoff"), 300);
+    return true;
+  };
+
+  return {
+    name: "sessions",
+    ops: [...SESSION_OPS, ...HANDOFF_OPS],
+    // Page-only in both senses, exactly as serve.R has them — with ONE
+    // deliberate divergence, stated rather than inherited: serve.R's
+    // `session-new` handler has no role check at all, so a declared agent can
+    // start a kernel there. That reads as an oversight beside the four ops
+    // around it, and starting processes is not something an agent does through
+    // a door the user cannot see, so Beatrix refuses it. Recorded in
+    // docs/wp/wp3a-files-sessions.md as a divergence, not a port.
+    agentRefused: [...SESSION_OPS, ...HANDOFF_OPS],
+    /** serve.R's own sentences, op by op (its AGENT_REFUSED reply table). */
+    agentRefusalFor: (op) => ({
+      session_list: "Agents cannot list the user's sessions.",
+      r_versions: "Agents cannot list or choose R installations.",
+      session_upgrade: "Agents cannot restart the user's session into another CarmaR.",
+      session_restart: "Agents cannot restart the user's session.",
+      "session-new": "Agents cannot start a session for the user.",
+    })[op] || null,
+    // The handoff IS advertised: a page decides "this kernel can restart into
+    // the installed build" from `ready.commands`, exactly as serve.R's ready
+    // frame lets it. The session list verbs are called and read, not advertised.
+    commands: [...HANDOFF_OPS],
+    capabilities: ["session-list-v1"],
+
+    handle(cmd, rec, ctx) {
+      if (typeof cmd.id !== "string" || !cmd.id.length) return undefined;
+      const reply = (fields) => rec.ws.send(ctx.enc({ type: cmd.type, id: cmd.id, ...fields }));
+      if (rec.role !== "page") return undefined;           // as serve.R: not this door's business
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit(`${cmd.type}-refused`, { class: rec.class || "unknown" });
+        return reply({ error: "Only the local notebook page may ask this." });
+      }
+      if (HANDOFF_OPS.includes(cmd.type)) {
+        return reply(handoffBegin(ctx, cmd.type === "session_restart" ? "restart" : "upgrade", cmd.force === true));
+      }
+      if (cmd.type === "session_list") {
+        const own = ctx.port();
+        const recs = runtimeRecords(env);
+        return Promise.all(recs.map(async (r) => {
+          const isThis = r.port === own;
+          return { port: r.port, url: String(r.url), title: r.title ?? "",
+            pid: r.pid ?? null, alive: isThis ? true : await healthy(r.url), this: isThis };
+        })).then((sessions) => reply({ sessions }))
+          .catch((e) => reply({ error: e.message }));
+      }
+      if (cmd.type === "r_versions") {
+        const current = (() => {
+          const p = ctx.plane.engine && ctx.plane.engine.rscript ? ctx.plane.engine.rscript : "";
+          try { return p ? fs.realpathSync(p) : ""; } catch { return p; }
+        })();
+        // Spawning N processes is the whole cost here; once per kernel life,
+        // exactly as serve.R caches it.
+        if (!versionsCache) versionsCache = rVersions(env, current, execFileSync);
+        const shown = ctx.plane.engine && ctx.plane.engine.rscript ? ctx.plane.engine.rscript : "";
+        return reply({ versions: versionsCache, current: shown });
+      }
+      if (cmd.type === "session-new") {
+        audit("session-new", { id: cmd.id });
+        return startSibling(ctx).then((started) => {
+          if (!started) return reply({ error: "Could not start another session." });
+          return reply({ port: started.port, url: started.url });
+        }).catch((e) => {
+          audit("session-new-failed", { detail: e.message });
+          reply({ error: "Could not start another session." });
+        });
+      }
+      return undefined;
+    },
+
+    /** The native doors of the same handoff (the menu helper, launch.sh --restart). */
+    http(req, res, pathname, ctx) {
+      if (pathname !== "/session/upgrade" && pathname !== "/session/restart") return false;
+      const blocked = ctx.controlRejection(req, { allowFile: true });
+      if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
+      if (req.method !== "POST") {
+        ctx.respond(res, 405, "application/json", ctx.enc({ ok: false, error: "POST only" }));
+        return true;
+      }
+      const restart = pathname === "/session/restart";
+      const begun = handoffBegin(ctx, restart ? "restart" : "upgrade", restart && ctx.queryParam(req, "force") === "1");
+      ctx.respond(res, begun.ok === true ? 200 : 409, "application/json", ctx.enc(begun));
+      return true;
+    },
+
+    /** Busy while a successor is being handed the port: the idle clock must not race it. */
+    busy: () => handoff != null,
+  };
+}
+
+export default { createPlane };

package/host/planes/settings.mjs

@@ -0,0 +1,164 @@
+// planes/settings.mjs — the user's own settings, over the wire.
+//
+// In NEITHER of the evaluating allow-lists, and that is the decision rather
+// than an omission. FORWARDED routes to the evaluating worker and
+// ANALYZE_FORWARDED to the analyzer; these read a file the SUPERVISOR owns and
+// mutate SUPERVISOR state (the idle clock, whether history records), which the
+// worker could not change at all — and routing a config-file WRITER into the
+// process that evaluates user code is precisely where such an op is most
+// dangerous.
+//
+// Page-only for the ai-key reason exactly: a native client could edit
+// settings.json itself as this user, but the kernel does not do it for it, so
+// the promise holds for every client rather than only the polite ones. A
+// published origin is refused because its reader approved that site to run the
+// chunks they press, not to reconfigure their kernel.
+//
+// NOT advertised in `ready.commands`: serve.R does not advertise it either, and
+// `commands` means "what this kernel serves that a page may have to detect by
+// name". Nothing in the page gates on these.
+
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
+import { SETTINGS_ADMIN, settingsEntry, validateSetting, writeSettingsFile, settingsPath } from "../settings.mjs";
+import fs from "node:fs";
+
+const OPS = Object.freeze(["settings_get", "settings_set", "settings_reset"]);
+const AGENT_WHY = Object.freeze({
+  // settings_GET is refused as firmly as the writes. Not because the values are
+  // secret, but because handing back the confinement root, the audit-log path
+  // and whether AI-text logging is on is a MAP OF THE DEPLOYMENT'S CONTROLS,
+  // given to a process whose entire premise is that it is not the user.
+  settings_get: "Agents cannot read CarmaR's settings.",
+  settings_set: "Agents cannot change CarmaR's settings.",
+  settings_reset: "Agents cannot reset CarmaR's settings.",
+});
+
+export function createPlane({ audit, settings } = {}) {
+  return {
+    name: "settings",
+    ops: OPS,
+    commands: [],
+    handle(cmd, rec, ctx) {
+      if (typeof cmd.id !== "string" || !cmd.id.length) return undefined;
+      const reply = (extra) => rec.ws.send(ctx.enc({ type: cmd.type, id: cmd.id, ...extra }));
+      if (rec.role === "mcp") {
+        audit?.("mcp-refused", { reason: `agent asked for ${cmd.type}` });
+        reply({ error: AGENT_WHY[cmd.type] });
+        return undefined;
+      }
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit?.("settings-refused", { reason: "class", detail: cmd.type, class: rec.class || "unknown" });
+        reply({ ok: false, reason: "class", error: "Only the notebook page may read or change CarmaR's settings." });
+        return undefined;
+      }
+      // An unauthenticated shared kernel has no "the user" whose home directory
+      // this is, so there is nobody to save a preference for.
+      if (ctx.deployment.loopback !== true && !(rec.user || "").length) {
+        audit?.("settings-refused", { reason: "posture", detail: cmd.type });
+        reply({ ok: false, reason: "posture", error: "This kernel serves unauthenticated clients, so it keeps no per-user settings." });
+        return undefined;
+      }
+
+      const sendState = (extra = {}) => {
+        const st = settings.state;
+        const rows = Object.keys(st.settings).map((k) => {
+          const e = st.settings[k];
+          const stored = st.file.values[k];
+          return { key: e.key, label: e.label, kind: e.kind, effect: e.effect,
+            value: e.value, source: e.source, locked: e.locked === true, writable: e.writable === true,
+            env: e.env, min: e.min ?? null, max: e.max ?? null,
+            // "the stored value differs from the one in force" — which is how a
+            // restart_r / next_launch setting shows a pending badge instead of
+            // pretending it already applied.
+            pending: stored !== undefined && stored !== e.value };
+        });
+        reply({ settings: rows, admin: st.admin,
+          file: { status: st.file.status, path: st.file.path, error: st.file.error,
+            ignored: st.file.ignored, rejected: st.file.rejected },
+          ...extra });
+      };
+
+      if (cmd.type === "settings_get") {
+        // RE-RESOLVE, never report the cache. The file can change under a
+        // running kernel — a hand edit, another session, a restored backup —
+        // and a page told the cached value would be shown a setting the kernel
+        // is not actually using. The live ones are back in force at the same
+        // moment, because reporting a new linger while running on the old one
+        // is the lie the whole `effect` field exists to prevent (the host reads
+        // the idle clock straight off this object every tick, so there is
+        // nothing else to re-apply).
+        settings.reresolve();
+        audit?.("settings", { detail: "get", status: settings.state.file.status });
+        sendState();
+        return undefined;
+      }
+
+      if (cmd.type === "settings_reset") {
+        try { fs.unlinkSync(settingsPath()); } catch { /* already gone */ }
+        settings.reresolve();
+        audit?.("settings", { detail: "reset", ok: true });
+        sendState({ ok: true });
+        return undefined;
+      }
+
+      // settings_set — one key per frame. A batch has to answer "three landed,
+      // one did not", and the honest answer is per-key anyway.
+      const key = typeof cmd.key === "string" ? cmd.key : "";
+      const entry = settingsEntry(key);
+      if (!entry) {
+        audit?.("settings-refused", { reason: "unknown", key });
+        reply({ ok: false, key, reason: SETTINGS_ADMIN.includes(key) ? "admin" : "unknown",
+          error: SETTINGS_ADMIN.includes(key)
+            ? "That setting belongs to this deployment's administrator."
+            : "No such setting." });
+        return undefined;
+      }
+      if (settings.state.settings[key].locked === true) {
+        audit?.("settings-refused", { reason: "env", key });
+        reply({ ok: false, key, reason: "env", error: `This deployment sets ${entry.env}, so it cannot be changed here.` });
+        return undefined;
+      }
+      const status = settings.state.file.status;
+      if (status !== "ok" && status !== "missing") {
+        // Writing over a file a human hand-edited, because of one stray byte,
+        // would destroy their config. Reset is the documented way out.
+        audit?.("settings-refused", { reason: "file", key });
+        reply({ ok: false, key, reason: "file", error: settings.state.file.error });
+        return undefined;
+      }
+
+      const values = { ...settings.state.file.values };
+      if (cmd.value === null || cmd.value === undefined) {
+        delete values[key];                         // unset: back to env/default
+      } else {
+        const verdict = validateSetting(key, cmd.value);
+        if (!verdict.ok) {
+          // Refused, never coerced, and the file is NOT written — the ai-key
+          // scar, where a payload of the wrong type fell through to "" and
+          // deleted the key while replying ok:true.
+          audit?.("settings-refused", { reason: "value", key });
+          reply({ ok: false, key, reason: entry.kind === "number" ? "range" : "type",
+            error: `${entry.label} ${verdict.reason}.` });
+          return undefined;
+        }
+        values[key] = verdict.value;
+      }
+
+      if (!writeSettingsFile(values)) {
+        audit?.("settings", { detail: "set", key, ok: false });
+        reply({ ok: false, key, reason: "write", error: "The settings file could not be written." });
+        return undefined;
+      }
+      settings.reresolve();
+      // A `live` setting is in force the moment the resolve lands: the idle
+      // clock and the console history both read this object per use, exactly as
+      // serve.R re-reads its two globals. `quarto_path` is live because the job
+      // child is spawned per job.
+      const applied = entry.effect === "live"
+        && ["linger_seconds", "history_enabled", "quarto_path"].includes(key);
+      audit?.("settings", { detail: "set", key, ok: true });
+      sendState({ ok: true, key, effect: entry.effect, applied, pending: !applied });
+      return undefined;
+    },
+  };
+}