beatrina 0.8.6

package/host/engine-pool.mjs

@@ -0,0 +1,383 @@
+// engine-pool.mjs — more than one engine in one document (WP4).
+//
+// `host/worker-plane.mjs` is ONE engine behind ONE queue, and that is right:
+// R and Python are two processes with two memories and there is no bridge
+// (docs/worker-protocol.md §6.1). What was missing is the router above them.
+// This is that router, and it presents the plane's OWN interface to
+// host/server.mjs, so the server is unchanged except where it has a genuine
+// choice to make.
+//
+// The rules it implements, each from docs/worker-protocol.md §6:
+//
+//   §6.1 One session per engine. Two planes, two processes, no shared names.
+//   §6.2 One queue per engine — so a Python chunk and an R chunk can be in
+//        flight at once, while chunks of one engine stay serial. (Run All's
+//        reading-order walk is the PAGE's; it dispatches the next chunk only
+//        after the previous one finished, whatever the engines.)
+//   §6.3 Stop, input and a debugger step belong to the RUN's engine, found by
+//        the run's id. A page never names an engine on a control op.
+//   §6.4 A data viewer belongs to the engine that produced the frame: `view`,
+//        `colstats` and the paging requests carry `engine`.
+//   §6.5 Restart is per engine. `restart {engine}` replaces that one process.
+//   §6.6 The working directory is per engine, reported by each.
+//   §6.9 An absent engine is a STATED FACT: a chunk whose engine has no
+//        runtime ends with a done frame that says so, never a hang.
+//
+// ON DEMAND, EXCEPT R. R starts at boot because the page will not leave
+// "connecting" until a `ready` arrives and because every existing suite
+// expects a session to be there. Every other engine starts the first time a
+// chunk of its language runs — an ipykernel that nobody asked for is 1.3
+// seconds and ~60 MB spent on a document that may hold no Python at all.
+
+import { EventEmitter } from "node:events";
+import { WorkerPlane } from "./worker-plane.mjs";
+
+const enc = (obj) => JSON.stringify(obj);
+const scalarChr = (x) => typeof x === "string" && x.length > 0;
+
+/** The engine key a value means. An ABSENT engine is the default one. */
+export function engineKey(engine, fallback = "r") {
+  if (engine == null) return fallback;
+  const key = String(engine).toLowerCase();
+  if (key === "py") return "python";
+  // knitr's JavaScript engine is `{js}`; `{javascript}` and `{node}` are the
+  // spellings people also write.
+  return key === "javascript" || key === "node" ? "js" : key;
+}
+
+export class EnginePool extends EventEmitter {
+  /**
+   * @param {Object} opts
+   * @param {Array<{name:string,label:string,factory:Function,boot?:"eager"|"on-demand",
+   *                available?:boolean,detail?:string,runtime?:object}>} opts.specs
+   *        Engines this host knows about. A spec with `available: false` is
+   *        still listed — it is the thing that lets a chunk be refused with a
+   *        reason instead of a hang.
+   * @param {(event:string, fields?:object) => void} [opts.audit]
+   * @param {number} [opts.deadlineScale]
+   * @param {number} [opts.respawnMax]
+   * @param {(hello:object, spec:object) => object} [opts.decorateReady]
+   */
+  constructor({ specs, audit = () => {}, deadlineScale = 1, respawnMax = 10, decorateReady = (x) => x }) {
+    super();
+    this.specs = specs;
+    this.audit = audit;
+    this.decorateReady = decorateReady;
+    this.planes = new Map();
+    this.starting = new Map();           // engine → Promise, so two chunks start one engine
+    this.sockets = () => [];
+    this.primaryName = specs[0] ? specs[0].name : "r";
+    for (const spec of specs) {
+      if (!spec.available) continue;
+      const plane = new WorkerPlane({
+        engineFactory: spec.factory, name: spec.name, label: spec.label,
+        audit: (event, fields = {}) => audit(event, { engine: spec.name, ...fields }),
+        deadlineScale, respawnMax,
+        decorateReady: (frame) => this.onReady(spec, frame),
+      });
+      plane.sockets = () => this.sockets();
+      plane.on("broadcast", (payload) => this.emit("broadcast", payload));
+      this.planes.set(spec.name, plane);
+    }
+  }
+
+  /** The plane for an engine, or null when this host has no such engine. */
+  planeFor(name) { return this.planes.get(engineKey(name, this.primaryName)) || null; }
+
+  get primary() { return this.planes.get(this.primaryName) || null; }
+
+  /** The names every advertised engine has — what the page's `engines` list is. */
+  get engineNames() { return this.specs.filter((s) => s.available).map((s) => s.name); }
+
+  /** Which engines are actually running right now (the rest start on demand). */
+  get startedNames() { return [...this.planes].filter(([, p]) => p.engine != null).map(([n]) => n); }
+
+  /**
+   * One row per engine this host knows about, available or not — the shape the
+   * ready frame and Doctor both carry, so "what was searched" is one answer.
+   */
+  engineRows() {
+    return this.specs.map((spec) => {
+      const plane = this.planes.get(spec.name) || null;
+      return {
+        engine: spec.name, label: spec.label, available: Boolean(spec.available),
+        detail: spec.detail || "", runtime: spec.runtime || null,
+        started: Boolean(plane && plane.engine), alive: Boolean(plane && plane.alive),
+        pid: plane && plane.engine ? plane.pid : null,
+        version: spec.version || "",
+      };
+    });
+  }
+
+  // ── the primary plane's surface, which server.mjs speaks ──────────────────
+
+  get alive() { return Boolean(this.primary && this.primary.alive); }
+  get language() { return this.primaryName; }
+  get readyFrame() { return this.primary ? this.primary.readyFrame : null; }
+  get hello() { return this.primary ? this.primary.hello : null; }
+  get notice() { return this.primary ? this.primary.notice : null; }
+  /** Every engine's in-flight execs, so the idle clock counts them all. */
+  /** Every engine forgets the results nobody came back for. */
+  sweepParked(lingerS) { for (const p of this.planes.values()) p.sweepParked?.(lingerS); }
+
+  get running() {
+    const all = new Set();
+    for (const [name, plane] of this.planes) for (const id of plane.running) all.add(`${name}:${id}`);
+    return all;
+  }
+  /**
+   * The PRIMARY engine — what every plane written against a single WorkerPlane
+   * reads (`plane.engine.rscript` in sessions, `plane.engine.alive`). The
+   * first shape of this getter returned a synthetic {alive, kill} over every
+   * started engine, which made `r_versions` report no current R and the file
+   * ops lose the worker's cwd; `killAll()` is the every-engine door now.
+   */
+  get engine() { return this.primary ? this.primary.engine : null; }
+  /** The primary engine's working directory, as it last reported it. */
+  get workerWd() { return this.primary ? this.primary.workerWd : process.cwd(); }
+  get mode() { return this.primary ? this.primary.mode : "batch"; }
+  get pid() { return this.primary ? this.primary.pid : null; }
+  /** main.mjs's exit handler: every started engine must go. */
+  killAll() {
+    for (const p of this.planes.values()) { if (p.engine && p.alive) { try { p.engine.kill(); } catch { /* gone */ } } }
+  }
+
+  async start() {
+    const eager = this.specs.filter((s) => s.available && s.boot !== "on-demand");
+    for (const spec of eager) await this.planes.get(spec.name).start();
+  }
+
+  /**
+   * Bring an engine up if it is not already, once.
+   * @returns {Promise<{ok: boolean, plane?: WorkerPlane, message?: string}>}
+   */
+  async ensure(name) {
+    const key = engineKey(name, this.primaryName);
+    const spec = this.specs.find((s) => s.name === key);
+    if (!spec) {
+      return { ok: false, message: `Beatrina has no ${key} engine; this chunk was not run.` };
+    }
+    if (!spec.available) {
+      // §6.9, word for word where it can be: the fact, then where to look.
+      return { ok: false, message: `${spec.label} is not installed or was not found; this chunk was not run. `
+        + `${spec.detail || ""} Doctor lists what was searched.`.replace(/\s+/g, " ").trim() };
+    }
+    const plane = this.planes.get(key);
+    if (plane.engine) return { ok: true, plane };
+    if (!this.starting.has(key)) {
+      this.audit("engine-start", { engine: key });
+      this.starting.set(key, plane.start().finally(() => this.starting.delete(key)));
+    }
+    try { await this.starting.get(key); } catch (e) {
+      return { ok: false, message: `The ${spec.label} engine would not start: ${e.message}` };
+    }
+    // The breakpoints go in BEFORE the command that started the engine: a
+    // start resolves once the process exists, so the exec that follows is
+    // written to its stdin next, and a replay on `ready` alone arrived after it.
+    this.replayBreaks(key);
+    return { ok: true, plane };
+  }
+
+  /**
+   * The ready frame of ONE engine, on its way to the page.
+   *
+   * A second engine does NOT send `ready`. `src/r-kernel.js` treats `ready` as
+   * the SESSION's identity — it re-runs the compatibility gate, resolves every
+   * readyWaiter and re-pumps the queue — so a second one arriving mid-session
+   * would read as the whole kernel having restarted. The engine is announced
+   * under its own type instead, carrying the same fields plus `engine`.
+   * Returning it from here (rather than emitting it separately) is what makes
+   * the plane store it as its `hello` and replay it to a page that connects
+   * later, which is the property the R ready has and the reason it is kept.
+   */
+  onReady(spec, frame) {
+    const decorated = this.decorateReady(frame, spec);
+    if (spec.name === this.primaryName) return decorated;
+    // A RESPAWNED engine knows no breakpoints (a first start is covered in
+    // ensure(), before its first command). Sending twice is harmless: the
+    // registry is state, not a count.
+    this.replayBreaks(spec.name);
+    return { ...decorated, type: "engine-ready", engine: spec.name };
+  }
+
+  // ── breakpoints ──────────────────────────────────────────────────────────
+  //
+  // The page sends `debug_breaks {file: "chunk:<stableId>", lines}` with no
+  // engine: lib/debugger.js addresses a CHUNK, and which engine runs that chunk
+  // is the document's business, not the gutter's. So the pool keeps the one
+  // registry, the primary engine answers the request exactly as it always did
+  // (R's reply, byte for byte), and every OTHER engine that has a debugger is
+  // told the same breakpoints — now if it is running, on its ready if it is not.
+  // Sent as a command with no id: nobody waits on it, and it must not queue
+  // behind a running chunk, which is precisely when someone toggles a
+  // breakpoint.
+
+  noteBreaks(cmd) {
+    if (!scalarChr(cmd.file)) return;
+    if (!this.breaks) this.breaks = new Map();
+    const lines = (Array.isArray(cmd.lines) ? cmd.lines : [])
+      .map(Number).filter((n) => Number.isInteger(n) && n >= 1);
+    if (lines.length) this.breaks.set(cmd.file, [...new Set(lines)].sort((a, b) => a - b));
+    else this.breaks.delete(cmd.file);
+    for (const [name, plane] of this.planes) {
+      if (name === this.primaryName || !plane.engine || !plane.canDebug) continue;
+      try { plane.engine.send({ type: "debug_breaks", file: cmd.file, lines: this.breaks.get(cmd.file) || [] }); }
+      catch { /* a dead engine is respawned and replayed on its ready */ }
+    }
+  }
+
+  replayBreaks(name) {
+    const plane = this.planes.get(name);
+    if (!this.breaks || !plane || !plane.engine || !plane.canDebug) return;
+    for (const [file, lines] of this.breaks) {
+      try { plane.engine.send({ type: "debug_breaks", file, lines }); } catch { return; }
+    }
+  }
+
+  /** A page that connects late is told about every engine already running. */
+  replay(ws) {
+    for (const [name, plane] of this.planes) {
+      if (name === this.primaryName) continue;
+      if (plane.hello) ws.send(plane.hello);
+      if (plane.notice) ws.send(plane.notice);
+    }
+  }
+
+  // ── routing ──────────────────────────────────────────────────────────────
+
+  exec(cmd, rec) {
+    if (!scalarChr(cmd.id) || typeof cmd.source !== "string") return undefined;
+    const key = engineKey(cmd.engine, this.primaryName);
+    const plane = this.planes.get(key);
+    if (plane && plane.engine) return plane.exec(cmd, rec);
+    // An engine that is not up yet: start it, THEN dispatch. The page sees a
+    // slower first chunk and nothing else — no queue of its own, no state here.
+    this.ensure(key).then((r) => {
+      if (!r.ok) {
+        this.audit("engine-absent", { engine: key });
+        return rec.ws.send(enc({ type: "done", id: cmd.id, status: "error", message: r.message }));
+      }
+      return r.plane.exec(cmd, rec);
+    }).catch((e) => {
+      rec.ws.send(enc({ type: "done", id: cmd.id, status: "error", message: e.message }));
+    });
+    return undefined;
+  }
+
+  /**
+   * A request for one engine's session — `env`, `view`, `colstats`, `obj`, …
+   * §6.4: it carries `engine` when it is about a value; without one it is the
+   * primary engine's, which is what every existing page sends.
+   *
+   * An engine that has not started is NOT started by a request: a page asking
+   * a Python session for its environment before any Python has run is asking
+   * about a session that does not exist, and booting an ipykernel to answer
+   * "nothing" would be a 1.3-second surprise. The empty answer says so.
+   */
+  request(cmd, rec) {
+    if (cmd.type === "debug_breaks") this.noteBreaks(cmd);
+    const key = engineKey(cmd.engine, this.primaryName);
+    const plane = this.planes.get(key);
+    if (plane && plane.engine) return plane.request(cmd, rec);
+    if (!scalarChr(cmd.id)) return undefined;
+    const spec = this.specs.find((s) => s.name === key);
+    const why = !spec ? `Beatrina has no ${key} engine.`
+      : !spec.available ? `${spec.label} is not installed or was not found; Doctor lists what was searched.`
+        : `The ${spec.label} session has not started yet — run a ${key} chunk first.`;
+    rec.ws.send(enc({ type: cmd.type, id: cmd.id, error: why, code: "no-engine" }));
+    return undefined;
+  }
+
+  /** Every plane a control op could belong to, the run's owner first (§6.3). */
+  ownerOf(rec, clientId) {
+    for (const plane of this.planes.values()) {
+      if (plane.engine && plane.ownsRun(rec, clientId)) return plane;
+    }
+    return null;
+  }
+
+  interrupt(cmd, rec) {
+    if (scalarChr(cmd.id)) {
+      const owner = this.ownerOf(rec, cmd.id);
+      if (owner) return owner.interrupt(cmd, rec);
+      // No plane owns it: a queued run this socket started may still be in a
+      // queue, and each plane drops what is not its own without signalling.
+      for (const plane of this.planes.values()) if (plane.engine) plane.interrupt(cmd, rec);
+      return undefined;
+    }
+    // An older bundle's id-less Stop: every engine that is busy.
+    for (const plane of this.planes.values()) if (plane.engine && plane.active) plane.interrupt(cmd, rec);
+    return undefined;
+  }
+
+  forceStop(rec, cmd = {}) {
+    const owner = scalarChr(cmd.id) ? this.ownerOf(rec, cmd.id) : null;
+    if (owner) return owner.forceStop(rec);
+    const named = scalarChr(cmd.engine) ? this.planes.get(engineKey(cmd.engine)) : null;
+    if (named && named.engine) return named.forceStop(rec);
+    // Neither a run nor an engine was named: force-stop every engine that is
+    // actually running something, and the primary if none is.
+    const busy = [...this.planes.values()].filter((p) => p.engine && p.active);
+    if (busy.length) { busy.forEach((p) => p.forceStop(rec)); return undefined; }
+    if (this.primary) this.primary.forceStop(rec);
+    return undefined;
+  }
+
+  /**
+   * Restart ONE engine (§6.5). `restart {engine: "python"}` replaces that
+   * process and fails that engine's routes; the other engine is untouched.
+   * With no engine named it is the primary's — which is what "Restart R" in
+   * the page means and what every existing client sends.
+   */
+  async restart(engine) {
+    const key = engineKey(engine, this.primaryName);
+    const plane = this.planes.get(key);
+    if (!plane) return undefined;
+    if (!plane.engine) {
+      // Restarting an engine that never started is "start it", not an error.
+      const r = await this.ensure(key);
+      return r.ok ? undefined : undefined;
+    }
+    return plane.restart();
+  }
+
+  inputReply(cmd, rec) {
+    const waiting = [...this.planes.values()].find((p) => p.engine && p.inputWaiting);
+    if (waiting) return waiting.inputReply(cmd, rec);
+    return this.primary ? this.primary.inputReply(cmd, rec) : undefined;
+  }
+
+  debugCmd(cmd, rec) {
+    const paused = [...this.planes.values()].find((p) => p.engine && p.debugPaused);
+    if (paused) return paused.debugCmd(cmd, rec);
+    return this.primary ? this.primary.debugCmd(cmd, rec) : undefined;
+  }
+
+  runstate(cmd, rec) {
+    if (!scalarChr(cmd.id)) return undefined;
+    const runId = scalarChr(cmd.run) ? cmd.run : "";
+    const running = Boolean(runId) && [...this.planes.values()].some((p) => p.engine && p.ownsRun(rec, runId));
+    rec.ws.send(enc({ type: "runstate", id: cmd.id, run: runId, running }));
+    return undefined;
+  }
+
+  /** Every engine's runs in one answer, each row naming its engine. */
+  runs(cmd, rec) {
+    if (!scalarChr(cmd.id)) return undefined;
+    const rows = [...this.planes.values()].filter((p) => p.engine).flatMap((p) => p.runRows(rec));
+    rec.ws.send(enc({ type: "runs", id: cmd.id, runs: rows }));
+    return undefined;
+  }
+
+  adopt(cmd, rec) {
+    if (!scalarChr(cmd.id) || !scalarChr(cmd.srcname)) return undefined;
+    const owner = [...this.planes.values()].find((p) => p.engine && p.hasAdoptable(cmd.srcname));
+    if (owner) return owner.adopt(cmd, rec);
+    rec.ws.send(enc({ type: "done", id: cmd.id, status: "lost", message: "that run is no longer in this session." }));
+    return undefined;
+  }
+
+  dropSocket(rec) { for (const plane of this.planes.values()) plane.dropSocket(rec); }
+
+  async stop() { for (const plane of this.planes.values()) await plane.stop(); }
+}

package/host/engine-python.mjs

@@ -0,0 +1,228 @@
+// engine-python.mjs — the Python engine's adapter.
+//
+// The process behind it is `engines/python/worker.py`, which speaks the same
+// wire `spike/worker.R` does (sentinel-framed JSON out, tagged JSON in). It
+// evaluates nothing itself: an ipykernel one process further out does, and
+// jupyter_client starts that kernel in its OWN session — measured on this
+// machine 2026-09-14, kernel sid == kernel pid — so the group SIGINT this
+// adapter sends reaches worker.py, which forwards `interrupt_request`. That is
+// the arrangement we want: a signal cannot queue behind a running cell the way
+// a stdin command can, and worker.py is never the process that is busy.
+//
+// DISCOVERY IS A STATED FACT, NEVER A HANG (docs/worker-protocol.md §6.9). A
+// runtime that is missing, or present without ipykernel, is reported on the
+// ready frame and in Doctor with the ladder that was searched — so a
+// `{python}` chunk says what is wrong instead of waiting on nothing.
+
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { StdioEngine } from "./engine-stdio.mjs";
+import { findInterruptTool } from "./windows-runtime.mjs";
+
+/** How long a probe of a candidate interpreter may take before it is "no". */
+export const PROBE_TIMEOUT_MS = 6000;
+
+/** Python's own variables that would aim a child at a different install. */
+const STRIP_PY_ENV = /^(PYTHONHOME|PYTHONPATH|PYTHONSTARTUP|PYTHONEXECUTABLE)$/;
+
+const exists = (p) => Boolean(p) && fs.existsSync(p);
+
+/**
+ * Every interpreter worth asking, in the order the answer is preferred, each
+ * labelled with WHY it was considered. The label is what Doctor prints, so a
+ * user who gets the wrong Python can see which rung chose it.
+ *
+ * `CARMAR_PYTHON` first (an explicit answer outranks a search), then the
+ * environment the user is already inside — an active venv, then conda — then
+ * pyenv's selected version, then PATH, then the usual installs. PATH is late
+ * for the reason `detectRscript` puts it last: a Finder-launched process has
+ * `/usr/bin:/bin:/usr/sbin:/sbin` and would miss Homebrew, conda and pyenv
+ * entirely, so a shell-launched and a Finder-launched session would silently
+ * pick different interpreters.
+ *
+ * @returns {Array<{path: string, why: string}>}
+ */
+export function pythonCandidates(env = process.env, platform = process.platform, io = null) {
+  if (platform === "win32") return windowsPythonCandidates(env, io);
+  const binName = "python3";
+  const rungs = [];
+  const add = (p, why) => { if (p && !rungs.some((r) => r.path === p)) rungs.push({ path: p, why }); };
+  if (env.CARMAR_PYTHON) add(env.CARMAR_PYTHON, "CARMAR_PYTHON");
+  // An interpreter Beatrix installed for itself. Nothing creates this yet —
+  // WP7 packages it — but the rung is here so that when something does, it
+  // outranks whatever happens to be on the user's PATH, which is the whole
+  // point of shipping one.
+  if (env.HOME) add(path.join(env.HOME, ".carmar", "python", "bin", binName), "the interpreter Beatrina manages");
+  if (env.VIRTUAL_ENV) add(path.join(env.VIRTUAL_ENV, "bin", binName), "the active virtualenv (VIRTUAL_ENV)");
+  if (env.CONDA_PREFIX) add(path.join(env.CONDA_PREFIX, "bin", binName), "the active conda environment (CONDA_PREFIX)");
+  const pyenvRoot = env.PYENV_ROOT || (env.HOME ? path.join(env.HOME, ".pyenv") : "");
+  if (pyenvRoot) {
+    const versionFile = path.join(pyenvRoot, "version");
+    let selected = "";
+    try { selected = fs.readFileSync(versionFile, "utf8").trim().split(/\s+/)[0] || ""; } catch { selected = ""; }
+    if (selected) add(path.join(pyenvRoot, "versions", selected, "bin", binName), `pyenv's selected version (${selected})`);
+    add(path.join(pyenvRoot, "shims", binName), "a pyenv shim");
+  }
+  for (const dir of String(env.PATH || "").split(path.delimiter)) {
+    if (dir) add(path.join(dir, binName), "PATH");
+  }
+  for (const p of ["/opt/homebrew/bin/python3", "/usr/local/bin/python3", "/usr/bin/python3"]) {
+    add(p, "a standard install location");
+  }
+  return rungs;
+}
+
+/**
+ * The Windows ladder. A venv keeps its interpreter in `Scripts\python.exe`,
+ * conda at the prefix root, python.org's installer under
+ * `%LOCALAPPDATA%\Programs\Python\Python3xx`; `python3.exe` on PATH is often
+ * the Microsoft Store STUB, which opens the Store instead of running, so the
+ * real installs come before PATH and the stub is skipped by name.
+ */
+export function windowsPythonCandidates(env = process.env, io = null) {
+  const w = path.win32;
+  const readdir = io ? io.readdir : (p) => { try { return fs.readdirSync(p); } catch { return []; } };
+  const rungs = [];
+  const add = (p, why) => { if (p && !rungs.some((r) => r.path === p)) rungs.push({ path: p, why }); };
+  if (env.CARMAR_PYTHON) add(env.CARMAR_PYTHON, "CARMAR_PYTHON");
+  if (env.USERPROFILE) add(w.join(env.USERPROFILE, ".carmar", "python", "python.exe"), "the interpreter Beatrina manages");
+  if (env.VIRTUAL_ENV) add(w.join(env.VIRTUAL_ENV, "Scripts", "python.exe"), "the active virtualenv (VIRTUAL_ENV)");
+  if (env.CONDA_PREFIX) add(w.join(env.CONDA_PREFIX, "python.exe"), "the active conda environment (CONDA_PREFIX)");
+  const versionOf = (d) => Number((String(d).match(/Python(\d+)/) || [0, 0])[1]);
+  for (const [root, why] of [
+    [env.LOCALAPPDATA ? w.join(env.LOCALAPPDATA, "Programs", "Python") : "", "python.org installer (per user)"],
+    [env.ProgramFiles || "", "python.org installer (all users)"],
+  ]) {
+    if (!root) continue;
+    const dirs = readdir(root).filter((d) => /^Python3\d+/.test(d)).sort((a, b) => versionOf(b) - versionOf(a));
+    for (const d of dirs) add(w.join(root, d, "python.exe"), `${why} (${d})`);
+  }
+  for (const dir of String(env.PATH || env.Path || "").split(";")) {
+    if (!dir || /\\WindowsApps\\?$/i.test(dir)) continue;       // the Store stub
+    add(w.join(dir, "python.exe"), "PATH");
+  }
+  return rungs;
+}
+
+/** Ask one interpreter what it is and whether it can host a kernel. */
+function probe(bin) {
+  return new Promise((resolve) => {
+    const script = "import json,sys\n"
+      + "out={'version':'.'.join(str(x) for x in sys.version_info[:3]),'executable':sys.executable,'missing':[]}\n"
+      + "for m in ('ipykernel','jupyter_client'):\n"
+      + "    try:\n"
+      + "        __import__(m)\n"
+      + "    except Exception:\n"
+      + "        out['missing'].append(m)\n"
+      + "print(json.dumps(out))\n";
+    execFile(bin, ["-c", script], { timeout: PROBE_TIMEOUT_MS, env: process.env },
+      (err, stdout) => {
+        if (err) return resolve(null);
+        try { resolve(JSON.parse(String(stdout).trim().split("\n").pop())); } catch { resolve(null); }
+      });
+  });
+}
+
+/**
+ * Find a Python that can host an ipykernel, and SAY WHAT WAS SEARCHED.
+ *
+ * The result is the same shape whether it succeeded or not, because both
+ * answers are shown in the same place: the `engines` row on the ready frame
+ * and Doctor. `searched` lists every rung that was actually executed, with the
+ * reason it was considered and what it said — a user with three Pythons and
+ * ipykernel in the wrong one can see that from the row.
+ *
+ * @returns {Promise<{available: boolean, path: string, version: string, why: string,
+ *                    detail: string, searched: Array<object>}>}
+ */
+export async function detectPython(env = process.env) {
+  const searched = [];
+  let firstWorking = null;
+  for (const rung of pythonCandidates(env)) {
+    if (!exists(rung.path)) continue;
+    const info = await probe(rung.path);
+    if (!info) {
+      searched.push({ ...rung, ok: false, detail: "did not answer" });
+      continue;
+    }
+    const missing = Array.isArray(info.missing) ? info.missing : [];
+    searched.push({ ...rung, ok: missing.length === 0, version: info.version,
+      detail: missing.length ? `${info.version}, missing ${missing.join(" and ")}` : info.version });
+    if (!missing.length) {
+      firstWorking = { path: rung.path, version: info.version, why: rung.why };
+      break;
+    }
+    // Keep looking: a system Python without ipykernel is not the answer, but
+    // the venv two rungs down may be.
+    if (searched.length > 12) break;              // a PATH of 40 dirs is not a search
+  }
+  if (firstWorking) {
+    return { available: true, ...firstWorking, detail: `Python ${firstWorking.version}`, searched };
+  }
+  const found = searched.filter((s) => s.version);
+  const detail = found.length
+    ? `Python is installed (${found.map((s) => `${s.version} at ${s.path}`).join("; ")}) but ipykernel is not. `
+      + "Install it with `python3 -m pip install ipykernel`, or point CARMAR_PYTHON at an interpreter that has it."
+    : "No Python interpreter was found. Set CARMAR_PYTHON to one, or install Python 3.";
+  return { available: false, path: "", version: "", why: "", detail, searched };
+}
+
+/** One `engines/python/worker.py` process. */
+export class PythonEngine extends StdioEngine {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.workerPath   engines/python/worker.py
+   * @param {string} opts.python       the interpreter detectPython chose
+   * @param {string} [opts.kernelName] the jupyter kernelspec (default python3)
+   * @param {Record<string,string>} [opts.env]
+   * @param {string} [opts.cwd]
+   */
+  constructor({ workerPath, python, kernelName = "python3", env = {}, cwd, platform = process.platform } = {}) {
+    super({ language: "python", workerPath, env, cwd, platform });
+    if (platform === "win32") this.interruptTool = findInterruptTool({ env: process.env });
+    if (!workerPath || !fs.existsSync(workerPath)) throw new Error(`PythonEngine: no worker at ${workerPath}`);
+    if (!python) throw new Error("PythonEngine: no Python found (set CARMAR_PYTHON)");
+    this.python = python;
+    this.kernelName = kernelName;
+  }
+
+  get label() { return "Python"; }
+  get stripEnv() { return STRIP_PY_ENV; }
+  /** `input()` works through input_request/input_reply. */
+  get canInput() { return true; }
+  /**
+   * A debugger lives in the kernel (engines/python/debugger.py): breakpoints
+   * by chunk srcname and line, a pause that is an `input()` the worker turns
+   * into a `debug` frame, and Stop that still works while paused.
+   */
+  get canDebug() { return true; }
+
+  /**
+   * One step command for a paused chunk. A COMMAND, not a console line: there
+   * is no Browse prompt to type `n` at, and the words R's plane spells as
+   * browser() keys mean nothing to Python. The plane has already checked the
+   * run is paused and owned by the asking page.
+   */
+  debugCommand(action, expr) {
+    return this.send({ type: "debug_cmd", action, ...(expr != null ? { expr } : {}) });
+  }
+
+  spawnPlan() {
+    return {
+      bin: this.python,
+      args: [path.resolve(this.workerPath)],
+      env: { CARMAR_WORKER_MODE: "interactive", CARMAR_PYTHON_KERNEL: this.kernelName },
+    };
+  }
+
+  /**
+   * A raw console line has no meaning here — worker.py's stdin reader parses
+   * commands, and there is no prompt behind it. An answer to `input()` is a
+   * COMMAND, read by the same reader while the kernel waits, so it reaches the
+   * kernel while a cell is running exactly as R's raw line does.
+   */
+  console(line) {
+    return this.send({ type: "input_reply", value: line });
+  }
+}