beatrina 0.8.6

package/host/settings.mjs

@@ -0,0 +1,379 @@
+// settings.mjs — the settings a USER may change, and the ones only an
+// administrator may. A transcription of spike/settings.R, rule for rule.
+//
+// ── THE PRECEDENCE RULE ─────────────────────────────────────────────────────
+//
+//   environment variable (set and non-empty)  ▸  config file  ▸  built-in default
+//
+// and the two consequences that matter more than the ordering:
+//
+//   · A setting whose env var is set is READ-ONLY for the life of this kernel.
+//     `settings_set` REFUSES it and does not write the file, because a value
+//     silently stored and never applied is a worse lie than a refusal.
+//   · An administrator's setting is NOT IN THIS FILE'S VOCABULARY AT ALL. It is
+//     rejected on read and refused on write, always — never "env wins if
+//     present", because that only guarantees anything when the env IS set, and
+//     a deployment that never set CARMAR_ROOT is still one where a user must
+//     not invent one.
+//
+// The tempting alternative — one layered getter handed to carmarDeployment()
+// and the AI policy — is deliberately NOT built here either. It would put every
+// administrator variable one argument-passing mistake away from being
+// file-settable. Those read process.env directly; only the user-writable call
+// sites read this module.
+//
+// Managed configuration (Jamf/Intune) is applied to process.env BEFORE any of
+// that resolves, for the reason settings.R gives: a managed desktop cannot
+// depend on shell startup files, so the administrator's values have to become
+// ordinary environment variables early enough that the env-wins-and-locks rule
+// stays the single source of truth.
+
+import fs from "node:fs";
+
+import path from "node:path";
+import { appId, ensureUserDir, privateModeHeld } from "./user-dirs.mjs";
+
+export const SETTINGS_VERSION = 1;
+
+/**
+ * The whole vocabulary. A key that is not here does not exist: there is no
+ * pass-through, so the file cannot grow a control by accident.
+ *
+ * `effect` is a FIELD, not a sentence the page composes, so a setting added
+ * later cannot arrive without an honest answer to "when does this take
+ * effect?". Its three values: live · restart_r · next_launch.
+ */
+export const SETTINGS = Object.freeze([
+  // Connection loss is not permission to discard the R workspace. Timed
+  // shutdown is opt-in; 0 retains an attached session until an explicit Quit.
+  { key: "linger_seconds", env: "CARMAR_LINGER", kind: "number", default: 0, min: 0, max: 86400, effect: "live", label: "Keep R running after all pages disconnect" },
+  { key: "history_enabled", env: "CARMAR_NO_HISTORY", kind: "bool", default: true, effect: "live", inverted: true, label: "Remember console history between sessions" },
+  { key: "analyze_budget_s", env: "CARMAR_ANALYZE_BUDGET", kind: "number", default: 3, min: 0, max: 60, effect: "next_launch", label: "Code-intelligence time budget" },
+  { key: "quarto_path", env: "CARMAR_QUARTO", kind: "path", default: "", effect: "live", label: "Quarto binary" },
+  { key: "rscript_path", env: "CARMAR_RSCRIPT", kind: "path", default: "", effect: "restart_r", label: "R binary" },
+  { key: "port", env: "CARMAR_PORT", kind: "number", default: 4747, min: 1024, max: 65535, effect: "next_launch", label: "Preferred port" },
+]);
+
+/**
+ * Reported to the page as read-only facts, never settable. Everything an
+ * administrator owns lives here and NOWHERE in SETTINGS, which is what makes
+ * the refusal structural rather than a lookup someone can forget.
+ */
+export const SETTINGS_ADMIN = Object.freeze([
+  "CARMAR_MANAGED_CONFIG",
+  "CARMAR_ROOT", "CARMAR_LOG", "CARMAR_LOG_AI_TEXT",
+  "CARMAR_CRAN_MIRROR",
+  "CARMAR_AI_LOCAL_ONLY", "CARMAR_AI_POLICY", "CARMAR_AI_PROVIDERS",
+  "CARMAR_BIND", "CARMAR_HOSTS", "CARMAR_ORIGINS", "CARMAR_REQUIRE_ORIGIN",
+  "CARMAR_TRUST_PROXY", "CARMAR_USER_HEADER", "CARMAR_TRUSTED_PROXY",
+  "CARMAR_ALLOW_UNAUTHENTICATED", "CARMAR_PORT_STRICT",
+  "CARMAR_UPDATE_FEED", "CARMAR_UPDATE_MIRROR", "CARMAR_UPDATE_OFFLINE_DIR",
+  "CARMAR_UPDATE_MANAGED",
+]);
+
+export const MANAGED_SETTINGS_SCHEMA = "carmar-managed-settings-v1";
+export const MANAGED_SETTINGS_ENV = Object.freeze([...new Set([
+  ...SETTINGS.map((s) => s.env),
+  ...SETTINGS_ADMIN.filter((n) => n !== "CARMAR_MANAGED_CONFIG"),
+  "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+])]);
+
+export const settingsEntry = (key) => SETTINGS.find((s) => s.key === key) || null;
+
+const sysEnv = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+
+// ── managed configuration ───────────────────────────────────────────────────
+
+export function managedDefaultPath(env = sysEnv, platform = process.platform) {
+  if (platform === "darwin") return "/Library/Application Support/CarmaR/managed-settings.json";
+  if (platform === "win32") {
+    const base = String(env("ProgramData", "")).trim() || "C:/ProgramData";
+    return path.join(base, "CarmaR", "managed-settings.json");
+  }
+  return "/etc/carmar/managed-settings.json";
+}
+
+/**
+ * Protection is checked from the standard user's point of view. Unix also
+ * requires root ownership, because a user-owned 0400 file can simply be
+ * chmod'd and replaced. Neither the file nor its parent may be writable by the
+ * running account.
+ */
+export function managedProtected(file, platform = process.platform) {
+  let st;
+  try { st = fs.lstatSync(file); } catch { return false; }
+  if (st.isSymbolicLink()) return false;
+  const writable = (p) => { try { fs.accessSync(p, fs.constants.W_OK); return true; } catch { return false; } };
+  if (writable(file) || writable(path.dirname(file))) return false;
+  if (platform !== "win32") {
+    if (st.uid !== 0) return false;
+    if ((st.mode & 0o077) !== 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Read one administrator policy atomically. Unlike the user settings file,
+ * unknown or malformed entries fail the WHOLE policy closed: partial policy is
+ * not a safe enterprise fallback.
+ */
+export function managedRead(file, { required = false, protection = managedProtected } = {}) {
+  const empty = { status: "missing", path: file, values: {}, errors: [] };
+  if (!fs.existsSync(file)) {
+    if (required) return { ...empty, status: "invalid", errors: ["CARMAR_MANAGED_CONFIG names a file that does not exist."] };
+    return empty;
+  }
+  if (protection(file) !== true) {
+    return { ...empty, status: "insecure",
+      errors: ["The managed settings file is writable by the current account, is a symlink, or is not administrator-owned; CarmaR refused it."] };
+  }
+  let size = NaN;
+  try { size = fs.statSync(file).size; } catch { size = NaN; }
+  if (!Number.isFinite(size) || size > 1024 * 1024) {
+    return { ...empty, status: "invalid", errors: ["The managed settings file exceeds the 1 MB limit."] };
+  }
+  let raw = null;
+  try { raw = JSON.parse(fs.readFileSync(file, "utf8")); } catch { raw = null; }
+  const plain = raw && typeof raw === "object" && !Array.isArray(raw);
+  const rootNames = plain ? Object.keys(raw) : null;
+  const settingsPlain = plain && raw.settings && typeof raw.settings === "object" && !Array.isArray(raw.settings);
+  if (!rootNames || rootNames.length !== 2 || !rootNames.includes("schema") || !rootNames.includes("settings")
+      || raw.schema !== MANAGED_SETTINGS_SCHEMA || !settingsPlain) {
+    return { ...empty, status: "invalid",
+      errors: [`The managed settings file must use schema ${MANAGED_SETTINGS_SCHEMA} with one settings object.`] };
+  }
+  const keys = Object.keys(raw.settings);
+  const unknown = keys.filter((k) => !MANAGED_SETTINGS_ENV.includes(k));
+  const bad = keys.filter((k) => {
+    const v = raw.settings[k];
+    return !(typeof v === "string" && v.length > 0 && !/[\r\n\t]/.test(v));
+  });
+  const errors = [];
+  if (unknown.length) errors.push(`Unknown managed setting: ${unknown.join(", ")}.`);
+  if (bad.length) errors.push(`Managed settings must be non-empty single-line strings: ${bad.join(", ")}.`);
+  if (errors.length) return { ...empty, status: "invalid", errors };
+  const values = {};
+  for (const k of keys) values[k] = raw.settings[k];
+  return { status: "ok", path: file, values, errors: [] };
+}
+
+/**
+ * Read the administrator's policy and put its values into the environment, so
+ * every subsystem that follows resolves under the ordinary env-wins rule.
+ */
+export function managedEnvironment({ env = sysEnv, file = null, protection = managedProtected, apply = true } = {}) {
+  const explicit = String(env("CARMAR_MANAGED_CONFIG", "")).trim();
+  const target = file || (explicit || managedDefaultPath(env));
+  const result = managedRead(target, { required: Boolean(explicit), protection });
+  if (apply && result.status === "ok") {
+    for (const [k, v] of Object.entries(result.values)) process.env[k] = v;
+  }
+  return result;
+}
+
+// ── the user's own file ─────────────────────────────────────────────────────
+
+/** Where the user's settings live — beside the AI key, same directory. */
+export function settingsPath() {
+  return path.join(ensureUserDir(appId(), "config"), "settings.json");
+}
+
+/**
+ * Is the file writable by anyone but its owner?
+ *
+ * This file is an INTEGRITY surface rather than a secret: another local account
+ * that can write it turns a knob in this user's next kernel. So a group- or
+ * other-writable file is IGNORED rather than repaired — silently chmod-ing
+ * someone else's file back to 0600 would hide that it had been changed at all.
+ */
+export function settingsInsecure(file, platform = process.platform) {
+  // Windows has no group/other bits: stat reports 0o666 for every writable
+  // file, so this read every settings.json there as tampered and ignored it.
+  if (platform === "win32") return false;
+  let st;
+  try { st = fs.statSync(file); } catch { return false; }
+  return (st.mode & 0o077) !== 0;
+}
+
+/**
+ * Validate one value against its entry.
+ * @returns {{ok: boolean, value?: any, reason?: string}}
+ */
+export function validateSetting(key, value) {
+  const entry = settingsEntry(key);
+  if (!entry) {
+    if (SETTINGS_ADMIN.includes(key)) return { ok: false, reason: "administrator setting" };
+    return { ok: false, reason: "unknown setting" };
+  }
+  if (entry.kind === "bool") {
+    if (typeof value !== "boolean") return { ok: false, reason: "must be true or false" };
+    return { ok: true, value };
+  }
+  if (entry.kind === "number") {
+    if (typeof value !== "number" || !Number.isFinite(value)) return { ok: false, reason: "must be a number" };
+    if (entry.min != null && value < entry.min) return { ok: false, reason: `must be at least ${entry.min}` };
+    if (entry.max != null && value > entry.max) return { ok: false, reason: `must be at most ${entry.max}` };
+    return { ok: true, value: Number(value) };
+  }
+  // path
+  if (typeof value !== "string") return { ok: false, reason: "must be a string" };
+  // An empty path means "use the ladder" — a legitimate value, not a missing
+  // one, and how a user clears an override.
+  if (value.length > 0 && !fs.existsSync(value)) return { ok: false, reason: "no such file" };
+  return { ok: true, value };
+}
+
+/**
+ * Read the config file. FOUR states, kept distinct — folding failure modes
+ * together is the fail-open bug the AI policy already paid for:
+ *   missing   no file. The ordinary single-user state, NOT an error.
+ *   ok        parsed, an object, the right version.
+ *   invalid   unparseable, not an object, wrong version → all defaults.
+ *   insecure  group/other writable → all defaults, different words.
+ *
+ * Per-key failure stays per-key: an unknown key joins `ignored`, a bad value
+ * joins `rejected`, and the rest of the file still applies.
+ */
+export function readSettingsFile(file = settingsPath()) {
+  const empty = { status: "missing", path: file, values: {}, ignored: [], rejected: [], error: "" };
+  if (!fs.existsSync(file)) return empty;
+  if (settingsInsecure(file)) {
+    return { ...empty, status: "insecure",
+      error: "The settings file is writable by other accounts on this machine, so it was ignored." };
+  }
+  let raw = null;
+  try { raw = JSON.parse(fs.readFileSync(file, "utf8")); } catch { raw = null; }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...empty, status: "invalid", error: "The settings file could not be read as JSON." };
+  }
+  if (Math.trunc(Number(raw.version || 0)) !== SETTINGS_VERSION) {
+    return { ...empty, status: "invalid", error: "The settings file is a version this CarmaR does not know." };
+  }
+  const block = raw.settings == null ? {} : raw.settings;
+  if (typeof block !== "object" || Array.isArray(block)) {
+    return { ...empty, status: "invalid", error: "The settings file's `settings` is not an object." };
+  }
+  const values = {};
+  const ignored = [];
+  const rejected = [];
+  for (const key of Object.keys(block)) {
+    const verdict = validateSetting(key, block[key]);
+    if (verdict.ok) values[key] = verdict.value;
+    else if (verdict.reason === "unknown setting") ignored.push(key);
+    else rejected.push({ key, reason: verdict.reason });
+  }
+  return { status: "ok", path: file, values, ignored, rejected, error: "" };
+}
+
+/**
+ * Write the whole settings block. Create → chmod 0600 → CHECK → write, the
+ * ordering the AI key uses and for the same reason: a file that was briefly
+ * group-writable was briefly tamperable.
+ */
+export function writeSettingsFile(values, file = settingsPath()) {
+  try {
+    if (!fs.existsSync(file)) fs.writeFileSync(file, "", { mode: 0o600 });
+  } catch { return false; }
+  try {
+    fs.chmodSync(file, 0o600);
+    if (!privateModeHeld(file)) { try { fs.unlinkSync(file); } catch { /* gone */ } return false; }
+  } catch { try { fs.unlinkSync(file); } catch { /* gone */ } return false; }
+  const body = { version: SETTINGS_VERSION, settings: values && Object.keys(values).length ? values : {} };
+  try { fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`); return true; } catch { return false; }
+}
+
+/**
+ * The whole decision: what every setting resolves to, and from where.
+ * @returns {{settings: Record<string, object>, admin: object[], file: object}}
+ */
+export function resolveSettings({ env = sysEnv, file = null } = {}) {
+  const read = file || readSettingsFile();
+  const usable = read.status === "ok";
+  const settings = {};
+  for (const s of SETTINGS) {
+    const raw = String(env(s.env, ""));
+    const fromEnv = raw.length > 0;
+    let value = s.default;
+    let source = "default";
+    if (fromEnv) {
+      source = "env";
+      if (s.kind === "bool") {
+        // CARMAR_NO_HISTORY is a NEGATIVE flag — any value means "off" — while
+        // the file and the UI hold the positive. Translating happens here, once.
+        value = s.inverted ? false : true;
+      } else if (s.kind === "number") {
+        const n = Number(raw);
+        value = Number.isFinite(n) ? n : s.default;
+      } else value = raw;
+    } else if (usable && read.values[s.key] !== undefined) {
+      source = "file";
+      value = read.values[s.key];
+    }
+    settings[s.key] = { key: s.key, label: s.label, kind: s.kind, effect: s.effect,
+      value, source, locked: fromEnv, writable: !fromEnv, min: s.min, max: s.max, env: s.env };
+  }
+  const admin = SETTINGS_ADMIN.map((name) => {
+    const raw = String(env(name, ""));
+    return { key: name, value: raw, source: raw.length ? "env" : "default" };
+  });
+  return { settings, admin, file: read };
+}
+
+/** The resolved scalar for one key. */
+export const settingsValue = (resolved, key) => (resolved.settings[key] ? resolved.settings[key].value : undefined);
+
+/**
+ * What a CHILD process should inherit — the settings that only take effect in
+ * a freshly spawned worker, job or analyzer, expressed back in the environment
+ * vocabulary those processes read.
+ */
+export function settingsChildEnv(resolved) {
+  const out = {};
+  const q = settingsValue(resolved, "quarto_path");
+  if (typeof q === "string" && q.length) out.CARMAR_QUARTO = q;
+  const b = settingsValue(resolved, "analyze_budget_s");
+  if (typeof b === "number") out.CARMAR_ANALYZE_BUDGET = String(b);
+  return out;
+}
+
+/**
+ * The live settings object the host holds: one resolve, re-resolved after a
+ * successful `settings_set`, so a later read reports the value actually in
+ * force. `errors` is non-empty only when the MANAGED policy failed — and that
+ * refuses startup, exactly as it does in serve.R.
+ *
+ * @param {{env?: Function, applyManaged?: boolean}} [opts]
+ */
+export function createSettings({ env = sysEnv, applyManaged = true } = {}) {
+  const managed = managedEnvironment({ env, apply: applyManaged });
+  let state = resolveSettings({ env });
+  const api = {
+    managed,
+    errors: managed.errors.slice(),
+    get state() { return state; },
+    reresolve() { state = resolveSettings({ env }); return state; },
+    value: (key) => settingsValue(state, key),
+    source: (key) => (state.settings[key] ? state.settings[key].source : "default"),
+    childEnv: () => settingsChildEnv(state),
+    path: () => settingsPath(),
+    /** Which R the worker, the analyzer and every job child should run. */
+    rscriptPreference() {
+      const chosen = api.value("rscript_path");
+      return typeof chosen === "string" && chosen.length ? chosen : String(env("CARMAR_RSCRIPT", ""));
+    },
+    /**
+     * The idle clock. The same safe default applies locally and behind a proxy:
+     * a setting still at its DEFAULT means "never", and only an explicit user
+     * or administrator value opts into timed shutdown — including an explicit 0.
+     */
+    lingerSeconds() {
+      const entry = state.settings.linger_seconds;
+      const value = Number(entry.value);
+      if (entry.source === "default" || !Number.isFinite(value)) return 0;
+      return value;
+    },
+    lingerIsDefault() { return state.settings.linger_seconds.source === "default"; },
+    historyEnabled() { return api.value("history_enabled") === true; },
+  };
+  return api;
+}

package/host/update-record.mjs

@@ -0,0 +1,59 @@
+// update-record.mjs — what the `beatrina` command learned about the npm registry, read back by the host.
+//
+// The host never reaches the network for this (host/planes/update.mjs says why: no feed, no clock of
+// its own). The `beatrina` command asks the registry at most once a day, at a door the person opened,
+// and writes a small record — {checked_at, latest} — under the app's cache folder
+// (tools/npm/bin/update-check.mjs). This module is the ONE definition of where that record lives and
+// what it means, so the command that writes it and the host that reads it cannot disagree: the host
+// puts `update_available` on /health and on the ready frame only when the recorded version is newer
+// than the build that is running, and the page says it (lib/info-pane.js, lib/doctor.js).
+//
+// CARMAR_NO_UPDATE_CHECK=1 or BEATRINA_NO_UPDATE_CHECK=1 turns the reading off as well as the asking
+// (the battery runner sets the first), so no test kernel reports a version some real run recorded.
+
+import fs from "node:fs";
+import path from "node:path";
+import { rUserDir } from "./user-dirs.mjs";
+
+/** -1, 0, 1 for semver-shaped versions; a pre-release sorts before its release; nonsense compares equal. */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = String(v).trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+    return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || "" } : null;
+  };
+  const x = parse(a);
+  const y = parse(b);
+  if (!x || !y) return 0;
+  for (let i = 0; i < 3; i += 1) if (x.nums[i] !== y.nums[i]) return x.nums[i] < y.nums[i] ? -1 : 1;
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+/** Where the command keeps its record for this app (R_user_dir(app, "cache")/update-check.json). */
+export function updateRecordFile(app) {
+  return path.join(rUserDir(app, "cache"), "update-check.json");
+}
+
+/** The check is off: nothing is asked and nothing is read. */
+export function updateCheckOff(env = process.env) {
+  return env.BEATRINA_NO_UPDATE_CHECK === "1" || env.CARMAR_NO_UPDATE_CHECK === "1";
+}
+
+/**
+ * The newer version the record names, or null: no record, a garbled one, the check switched off, or
+ * a recorded version that is not newer than `current`. A version is a short semver-shaped string
+ * or it is nothing — the record is a file another process wrote, so its content is checked, never echoed.
+ *
+ * @param {{file: string, current: string, env?: NodeJS.ProcessEnv}} o
+ * @returns {string|null}
+ */
+export function updateAvailable({ file, current, env = process.env }) {
+  if (updateCheckOff(env)) return null;
+  let record;
+  try { record = JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+  const latest = record && typeof record.latest === "string" ? record.latest.trim() : "";
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,32})?$/.test(latest)) return null;
+  return compareVersions(latest, current) > 0 ? latest : null;
+}

package/host/user-dirs.mjs

@@ -0,0 +1,117 @@
+// user-dirs.mjs — where the user's own machine state lives, decided exactly as
+// R decides it.
+//
+// Five stores in this work package sit under one of two directories:
+//
+//   config   the provider key (`ai-key`), the user's settings (`settings.json`)
+//   data     the console history, the appearance carry, the document journal,
+//            the AI conversation store
+//
+// serve.R reaches them through `tools::R_user_dir("carmar", which)`, and every
+// suite in the battery relocates them for a test by setting `R_USER_CONFIG_DIR`
+// / `R_USER_DATA_DIR` — the variables R itself honours. So the host cannot
+// invent its own layout: a JavaScript supervisor writing to `~/.beatrix` would
+// read none of the user's existing state AND would write into the real home
+// directory from every test that thought it had redirected it. This is
+// `tools::R_user_dir`, transcribed from R 4.5.2's source, with the same
+// precedence and the same platform branches.
+//
+// The `cache` branch is transcribed too even though nothing here uses it yet:
+// leaving one arm out is how the next store to need it quietly grows a second
+// layout.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const envOf = (name) => (process.env[name] == null ? "" : String(process.env[name]));
+
+/**
+ * Which R package's folders this host keeps its data, settings and caches in.
+ *
+ * "carmar" unless BEATRIX_APP_ID names another: the `beatrina` command sets
+ * it to "beatrina" (tools/npm/bin/beatrina.mjs), so a Beatrina installed
+ * beside CarmaR keeps its OWN settings, AI key, console history, document
+ * history, plugins and caches instead of reading and writing CarmaR's. The
+ * kernel runtime directory (~/.carmar/run) is deliberately NOT keyed on it:
+ * it is how the Sessions pane and the MCP bridge find every running kernel.
+ * A value that is not an R package name is refused, loudly — a typo must not
+ * quietly become a third data folder.
+ *
+ * @param {(name: string) => string} [env]
+ * @returns {string}
+ */
+export function appId(env = envOf) {
+  const id = String(env("BEATRIX_APP_ID") || "").trim();
+  if (!id) return "carmar";
+  if (!/^[A-Za-z][A-Za-z0-9.]*[A-Za-z0-9]$/.test(id)) {
+    throw new Error(`BEATRIX_APP_ID must be an R package name (letters, digits and dots); it is ${JSON.stringify(id)}.`);
+  }
+  return id;
+}
+
+/**
+ * `tools::R_user_dir(package, which)`.
+ *
+ * @param {string} pkg          the package name ("carmar")
+ * @param {"data"|"config"|"cache"} which
+ * @returns {string} an absolute directory path (NOT created)
+ */
+export function rUserDir(pkg, which = "data") {
+  const home = os.homedir();
+  const windows = process.platform === "win32";
+  const darwin = process.platform === "darwin";
+  let base = "";
+  if (which === "data") {
+    base = envOf("R_USER_DATA_DIR") || envOf("XDG_DATA_HOME")
+      || (windows ? path.join(envOf("APPDATA"), "R", "data")
+        : darwin ? path.join(home, "Library", "Application Support", "org.R-project.R")
+          : path.join(home, ".local", "share"));
+  } else if (which === "config") {
+    base = envOf("R_USER_CONFIG_DIR") || envOf("XDG_CONFIG_HOME")
+      || (windows ? path.join(envOf("APPDATA"), "R", "config")
+        : darwin ? path.join(home, "Library", "Preferences", "org.R-project.R")
+          : path.join(home, ".config"));
+  } else {
+    base = envOf("R_USER_CACHE_DIR") || envOf("XDG_CACHE_HOME")
+      || (windows ? path.join(envOf("LOCALAPPDATA"), "R", "cache")
+        : darwin ? path.join(home, "Library", "Caches", "org.R-project.R")
+          : path.join(home, ".cache"));
+  }
+  return path.join(base, "R", pkg);
+}
+
+/** The same, created on the way out — what every serve.R call site does. */
+export function ensureUserDir(pkg, which) {
+  const dir = rUserDir(pkg, which);
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* the caller reports the failure it hits */ }
+  return dir;
+}
+
+/**
+ * The launcher's state directory, or the package's (`state_dir()` in serve.R).
+ * The journal and the AI conversation store hang off this when their own
+ * variable is unset.
+ */
+export function stateDir() {
+  return envOf("CARMAR_STATE") || rUserDir(appId(), "data");
+}
+
+/**
+ * Did a chmod to 0600 take? Asked after every create → chmod → CHECK of a file
+ * in these directories (the key, settings, console history, appearance, the
+ * journal, the AI conversations).
+ *
+ * POSIX modes mean something only off Windows. There Node's chmod toggles the
+ * read-only attribute and nothing else, and stat reports 0o666 for every
+ * writable file, so `(mode & 0o777) === 0o600` can never hold: every one of
+ * those writes was refused on Windows and the page said "The writer lease could
+ * not be written" (first Windows tester, 2026-09-15). The privacy these files
+ * need on Windows comes from where they live — rUserDir resolves under
+ * %LOCALAPPDATA%, whose ACL admits only this account — which is also all R's
+ * Sys.chmod gave the retired R supervisor there.
+ */
+export function privateModeHeld(file, platform = process.platform) {
+  if (platform === "win32") return true;
+  return (fs.statSync(file).mode & 0o777) === 0o600;
+}