clearotron 0.3.2-beta.11 → 0.3.2-beta.13

package/shared/browser-temp-root.mjs

@@ -111,13 +111,20 @@ export function browserTempRoot() {
 }
 
 /**
- * The environment a browser must be spawned with so its singleton lock lands under `root`.
+ * The environment a browser must be spawned with so everything it writes lands under `root`.
  *
- * `TMPDIR` is the whole mechanism, so this refuses rather than passing a root that cannot work.
+ * `TMPDIR` puts its singleton lock there, so this refuses rather than passing a root that cannot work.
+ * AND A HOME OF ITS OWN. A profile directory does not hold everything a browser writes: it keeps its
+ * font cache, certificate store, desktop settings and crash folder under the user's home, so a suite run
+ * left `.cache/fontconfig`, `.local/share/pki`, `.local/share/applications` and
+ * `.config/google-chrome/Crash Reports` in the real home of whoever ran it (measured on a fresh home,
+ * 2026-09-19). The home and the three XDG folders now sit inside the root, and go with it.
  */
 export function browserEnv(root, env = process.env) {
   assertRootFits(root);
-  return { ...env, TMPDIR: root };
+  const home = join(root, "home");
+  for (const d of [home, join(home, ".config"), join(home, ".cache"), join(home, ".local", "share")]) mkdirSync(d, { recursive: true });
+  return { ...env, TMPDIR: root, HOME: home, XDG_CONFIG_HOME: join(home, ".config"), XDG_CACHE_HOME: join(home, ".cache"), XDG_DATA_HOME: join(home, ".local", "share") };
 }
 
 /**

package/shared/client-door.mjs

@@ -134,6 +134,26 @@ export function demoTokenSecret(base, io) {
  * cannot type, and it names the demo's base so the verb reads that demo's secret and guest list. An
  * install moved with `--base` is named too, for its guest list; the default install needs neither.
  */
+/**
+ * What an account key is for, in the owner's words (2026-09-19), printed first by every command that
+ * hands one over. ONE COPY: `key issue` and `connect --base` both print it, and a second copy of an
+ * approved sentence is the one that drifts. `reset` is the passphrase command as the caller composes it.
+ */
+export function keyPurposeLine({ email, brand, reset }) {
+  return `This key lets an AI assistant act as ${email} through ${brand}'s client door. `
+    + `It is not a portal sign-in; the portal uses the passphrase (${reset}).`;
+}
+
+/**
+ * The command that connects an assistant to a running DEMO: it mints the key and names the client door
+ * in one step, so nobody issues a key by hand (owner, 2026-09-19). A demo keeps its own secret and guest
+ * list in its folder, which is why the folder is named.
+ */
+export function demoConnectCommand({ prefix = "", base }) {
+  const q = (d) => (/\s/.test(d) ? `"${d}"` : d);
+  return `${prefix}clearotron connect --base ${q(base)}`;
+}
+
 export function keyIssueCommand({ prefix = "", demo = false, user = null, base = null, defaultBase = null } = {}) {
   const q = (d) => (/\s/.test(d) ? `"${d}"` : d);
   const who = demo && user ? user : "<email>";
@@ -194,7 +214,7 @@ export const clientDoorAddress = (env = {}) => `http://127.0.0.1:${clientDoorPor
  * the fence off accepts no account key, and the fence on with nothing listening is a setting with no
  * server. Reporting "standing" on half of it would send a reader to paste an address at nothing.
  */
-export function clientDoorState({ env = {}, unitDir, exists, active = null, listening = null, activeState = null, subState = null } = {}) {
+export function clientDoorState({ env = {}, unitDir, exists, active = null, listening = null, ownListener = null, activeState = null, subState = null } = {}) {
   const fenceOn = String(env.CLIENT_MCP_ACCOUNT_ACCESS ?? "").trim() === "1";
   const unitInstalled = Boolean(exists(join(unitDir, CLIENT_DOOR_UNIT)));
   // `standing` IS UNCHANGED AND STILL MEANS CONFIGURED — a file on disk and a fence flag. Two callers
@@ -218,7 +238,7 @@ export function clientDoorState({ env = {}, unitDir, exists, active = null, list
     // so a crash loop (`activating/auto-restart`) and a unit that was never started (`inactive/dead`)
     // reduce to the same `false` and printed the same sentence — one is a fault to read the journal for,
     // the other is a connect that stopped half-way.
-    listening, activeState, subState, standing, fenceOn, unitInstalled, active, serving: standing && active === true };
+    listening, ownListener, activeState, subState, standing, fenceOn, unitInstalled, active, serving: standing && active === true };
 }
 
 /**
@@ -280,10 +300,17 @@ export function describeDoorState(door, {
       // reader whose foreground door was up to run the command they had just run — and it is NOT enough
       // to call it theirs: the product's ports are fixed defaults, so on a shared box the answer may be
       // another install's door entirely. Caught by 2145's arm on a machine where exactly that was true.
+      //
+      // AND WHOSE IT IS IS ASKED, NOT GUESSED. On a shared box the port is often another account's door,
+      // and "something is listening on the client door's address for this environment" read as this
+      // install's (measured 2026-09-19). `ownListener` is true only when this install's own record says
+      // it holds the port; anything else is said as exactly what was measured, a process on the port.
+      if (door.ownListener === true)
+        return { level: "info",
+          text: `this install's client door is running in the foreground — it stops when that terminal does; `
+            + `\`${startCmd} --background\` installs the unit.` };
       return { level: "info",
-        text: `something is listening on the client door's address for this environment — no ${unit} is `
-          + "installed, so either this install is running in the foreground (it stops when that terminal "
-          + `does; \`${startCmd} --background\` installs the unit) or another install holds the port.` };
+        text: "a process holds the client door's port, and nothing here shows it is this install's door." };
     }
     return { level: "info",
       text: `the client door is not set up here — ${missing}. \`${startCmd}\` writes both. Since the `
@@ -293,11 +320,16 @@ export function describeDoorState(door, {
   if (door.active === null) {
     // THE PROBE STILL COUNTS HERE. Not asking systemd is not the same as knowing nothing: if the port
     // answers, the door is serving whatever systemd would have said.
-    if (door.listening === true) {
+    if (door.listening === true && door.ownListener === true) {
       return { level: "ok",
         text: `${unit} is installed and account access is enabled, and the client door's port is `
           + "answering — systemd was not asked, so this is the port's word rather than the unit's" };
     }
+    if (door.listening === true) {
+      return { level: "info",
+        text: `${unit} is installed and account access is enabled — whether it is RUNNING was not checked. `
+          + "A process holds the client door's port, and nothing here shows it is this install's door." };
+    }
     return { level: "info",
       text: `${unit} is installed and account access is enabled — whether it is RUNNING was not checked, `
         + "so this says the door is set up, not that it answers" };

package/shared/connect-clients.mjs

@@ -429,6 +429,8 @@ const splitSides = (step) => {
   return variants.map((v) => ({
     ...step,
     text: v.heading,
+    // A side that needs something filled in before it is pasted says so under its own copy.
+    hint: v.hint ?? step.hint,
     copy: { ...step.copy, text: v.text, stdio: { ...step.copy.stdio, text: v.text, variants: null } },
   }));
 };

package/shared/identifier-scan.mjs

@@ -152,7 +152,7 @@ export function firesOn(name, line, suffixable) {
  * @returns {{start: number, end: number}[]}
  */
 export function matchSpans(name, line, suffixable) {
-  const body = name.replace(/[&]/g, "\\&").replace(/ /g, SEPARATOR_CLASS);
+  const body = name.replace(/[.*+?^${}()|[\]\\&]/g, "\\$&").replace(/ /g, SEPARATOR_CLASS);
   const tail = suffixable.has(name) ? "" : "(?![A-Za-z0-9])";
   const re = new RegExp(`(?<![A-Za-z0-9])${body}${tail}`, "gi");
   const out = [];
@@ -332,7 +332,7 @@ const COMMENT_LINE = /^\s*(\/\/|#|\*|<!--)/;
 // this repository is about to start printing addresses at — an allowlist for those mailboxes would
 // have been inert, because nothing ever examined them.
 //
-// WHY THE RULED MAILBOXES JOIN ROLE_LOCALPART RATHER THAN THE DOMAIN GETTING AN EXEMPTION. 's
+// WHY THE RULED MAILBOXES JOIN ROLE_LOCALPART RATHER THAN THE DOMAIN GETTING AN EXEMPTION. The
 // ruling says `security` joins ROLE_LOCALPART "in the same PR, never a bypass", and that is the
 // right shape: exempting the whole domain would also pass a named person's address at it, which is
 // exactly the thing nobody should paste into a public README. Measured before widening rather than

package/shared/invocation.mjs

@@ -312,7 +312,7 @@ export function reachableCommand(verb, { argv1 = process.argv[1] ?? "", env = pr
 /**
  * The verb by NAME ONLY — no prefix, no path, no `npx`.
  *
- * ✕ A DELIBERATE EXCEPTION TO "ONE TREATMENT", AND THE ONE SURFACE THAT NEEDS IT. 's
+ * ✕ A DELIBERATE EXCEPTION TO "ONE TREATMENT", AND THE ONE SURFACE THAT NEEDS IT. The
  * second requirement is that the choice is made once rather than per site, so an exception has to be
  * named rather than quietly spelled differently somewhere.
  *

package/shared/parent-watch.mjs

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// NOTICE WHEN THE PROCESS THAT STARTED US IS GONE.
+//
+// `npx clearotron demo` runs as npm → `sh -c clearotron demo …` → the launcher → the demo. A TERM to the
+// pid a shell hands back for a backgrounded `npx …` reaches npm, npm passes it to that `sh`, and `sh` exits
+// without passing it on. The launcher is reparented and the demo runs on, holding its three ports, with
+// nothing saying so. Measured on npm 10.9.8, 2026-09-18. Neither npm nor that `sh` is ours to change, and
+// a process is told nothing when its parent dies on Linux or macOS, so the launcher asks: its parent pid
+// changes the moment it is reparented, to init or to the nearest subreaper.
+//
+// A process whose parent is already init when it starts (started under `setsid`, or by a service manager
+// that exits) never sees its parent pid change, so this never fires for it.
+
+/**
+ * Call `onGone` once, the first time this process's parent pid differs from the one it had when this was
+ * called. Returns a function that stops watching. The timer never keeps the process alive on its own.
+ */
+export function watchParent(onGone, { intervalMs = 1000, parentPid = () => process.ppid } = {}) {
+  const first = parentPid();
+  let fired = false;
+  const timer = setInterval(() => {
+    if (fired) return;
+    const now = parentPid();
+    if (now === first) return;
+    fired = true;
+    clearInterval(timer);
+    onGone({ was: first, now });
+  }, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}

package/shared/reference-guard-classes.mjs

@@ -85,10 +85,12 @@ export const withoutColourValues = (line) => String(line).replace(HEX_COLOUR, (m
 });
 
 /** Strip the spans where a `#NNN` is an address rather than a reference. */
-export const withoutLinkTargets = (line) => String(line)
+export const withoutLinkTargets = (line) => withoutAngleSpans(String(line)
   .replace(/\]\([^)]*\)/g, "]()")                 // markdown link targets, anchors included
-  .replace(/https?:\/\/\S+/g, "")                  // bare URLs and their fragments
-  .replace(/<[^>]*>/g, "");                        // angle-bracket autolinks
+  .replace(/https?:\/\/\S+/g, ""));                // bare URLs and their fragments
+
+/** Angle-bracket spans (autolinks, tags), removed until none is left: one pass can reassemble one. */
+const withoutAngleSpans = (s) => { for (let prev = null; prev !== s;) { prev = s; s = s.replace(/<[^>]*>/g, ""); } return s; };
 
 // A `#` COMMENT IS A COMMENT WHEREVER THE FILE FORMAT SAYS SO, not only in YAML. Extensionless is
 // deliberate: a systemd unit or a dotfile often has no extension worth matching, so the KNOWN

package/shared/running-start.mjs

@@ -13,9 +13,9 @@
 // record whose process is gone is read as absent, and `status` asks the portal itself before saying the
 // product is up. Three answers, all honest: up; started but not answering; not running.
 
-import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 /**
  * Where the records live: one file per serving process, beside the settings and the revocation list.
@@ -37,9 +37,14 @@ export function pidAlive(pid) {
 /**
  * Record one serving start. Returns the function that removes the record; calling it twice is harmless,
  * so the caller can hang it on both its own shutdown and the process's `exit`.
+ *
+ * THE FOLDERS THIS RECORD MADE GO WITH IT, when nothing else is in them. On a home that had none, the
+ * demo's record created `~/.config/clearotron/running` and its parent, and a clean stop left both behind
+ * under a banner saying nothing of the demo was left (measured 2026-09-19). A folder that was already
+ * there, or that holds anything else, stays: `rmdirSync` removes only an empty directory.
  */
 export function recordRunning(rec, { dir = runningDir() } = {}) {
-  mkdirSync(dir, { recursive: true });
+  const made = mkdirSync(dir, { recursive: true });
   const file = join(dir, `${rec.pid}.json`);
   const tmp = `${file}.tmp`;
   writeFileSync(tmp, `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
@@ -49,6 +54,12 @@ export function recordRunning(rec, { dir = runningDir() } = {}) {
     if (gone) return;
     gone = true;
     try { rmSync(file, { force: true }); } catch { /* already gone */ }
+    if (made) {
+      for (let d = dir; ; d = dirname(d)) {
+        try { rmdirSync(d); } catch { break; }   // not empty, or gone: either way, not ours to take
+        if (d === made) break;
+      }
+    }
   };
 }
 

package/shared/scope.mjs

@@ -259,7 +259,7 @@ export const TOOL_SCOPES = {
 // The ONLY artifact a user (report-link) token may read via read_artifact — THE report (one report;
 // clientSummary was a second version by another name and is retired from client reach — the file
 // remains an internal cover-note source ops tokens may read). Everything else
-// (narrative, audit, run.jsonl, skepticFlags, lisaEyeReview, matterContext, caseLaw, register axes,
+// (narrative, audit, run.jsonl, skepticFlags, seniorEyeReview, matterContext, caseLaw, register axes,
 // status.json, …) is internal and stays sealed from a user token.
 // Exported so the server's Resources surface (ListResources/ReadResource) gates to the SAME set.
 /**
@@ -833,7 +833,7 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
         throw new Error("forbidden: client account access is not enabled on this door");
       return { kind: "account", runId: null, sub: t.sub, verbs: null, ...personScope(t.sub, t.accounts) };
     }
-    if (t.scope !== "user") throw new Error("forbidden: the client surface accepts only a run-scoped user token or an account key");
+    if (t.scope !== "user") throw new Error(`forbidden: the client surface accepts only a run-scoped user token or an account key${otherDoor("staff")}`);
     return { kind: "user", runId: t.runId, sub: t.sub, verbs: null, accounts: null }; // run-bound — accounts moot
   }
   if (local) return { kind: "ops", runId: null, sub: "local", verbs: null, accounts: "*" };
@@ -842,7 +842,7 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
     // An account key belongs to the CLIENT door and nowhere else. Falling through would land it in the
     // `user` arm below with runId:null — a "run-bound" scope bound to no run, which every run-pinning check
     // downstream would then wave through. Refuse it here instead.
-    if (t.scope === "account") throw new Error("forbidden: an account key is only accepted on the client surface");
+    if (t.scope === "account") throw new Error(`forbidden: an account key is only accepted on the client surface${otherDoor("client")}`);
     return t.scope === "ops"
       ? { kind: "ops", runId: null, sub: t.sub, verbs: t.verbs, accounts: t.accounts ?? "*" }
       : { kind: "user", runId: t.runId, sub: t.sub, verbs: null, accounts: null }; // run-bound — accounts moot
@@ -866,6 +866,25 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
   throw new Error("forbidden: no run-scoped token and not a firm-staff identity — refusing (internal read-all requires proven firm staff)");
 }
 
+/**
+ * WHERE THE OTHER DOOR IS, for the refusal that turns a key away from the wrong one: " (client surface:
+ * <address>)", or nothing when this process was not told. A key refused as "only accepted on the client
+ * surface" read as a permissions problem, and the next thing a reader did was the wrong thing; the demo's
+ * own output led an assistant to the staff door with an account key (measured on a published beta,
+ * 2026-09-19). Each door is handed the other's port and host by `start` and by the shared unit settings,
+ * under the names the other door listens on. The client door's public address, when one is set, is the
+ * one a remote assistant can reach, so it wins. A wildcard bind is named as loopback, where a reader on
+ * this machine reaches it. PURE given its env.
+ */
+export function otherDoor(which, env = process.env) {
+  const [url, host, port] = which === "client"
+    ? [env.CLEAROTRON_CLIENT_MCP_URL, env.CLIENT_MCP_HTTP_HOST, env.CLIENT_MCP_HTTP_PORT]
+    : [null, env.TRADEMARK_MCP_HTTP_HOST, env.TRADEMARK_MCP_HTTP_PORT];
+  const at = String(url ?? "").trim() || (String(port ?? "").trim()
+    ? `http://${!host || host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${String(port).trim()}/mcp` : "");
+  return at ? ` (${which} surface: ${at})` : "";
+}
+
 // The ENFORCEMENT chokepoint. Returns the (possibly run-pinned) args to dispatch, or throws an Error the
 // CallTool handler surfaces as an MCP error. ops ⇒ everything. user/internal ⇒ no write tools. user ⇒ also
 // no cross-run tool, and every run-scoped call is PINNED to the token's bound run (a mismatching explicit

package/shared/stdio-connect.mjs

@@ -50,8 +50,8 @@ export const STDIO_SERVER_NAME = "trademark-artifacts";
  * @param {{ installRoot?: string, workDir?: string|null }} [opts]
  * @returns {string} the exact command to run
  */
-export function stdioConnectCommand({ installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform } = {}) {
-  return STDIO_SHAPES["claude-cli"].render({ server: join(installRoot, "mcp-server", "server.mjs"), workDir, reportsDir, platform });
+export function stdioConnectCommand({ installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, node = process.execPath } = {}) {
+  return STDIO_SHAPES["claude-cli"].render({ server: join(installRoot, "mcp-server", STDIO_ENTRY), workDir, reportsDir, platform, node });
 }
 
 /**
@@ -125,6 +125,12 @@ const separator = (platform = process.platform) => (platform === "win32" ? '"--"
  * -e …`. The distribution is named from `WSL_DISTRO_NAME` when we have it, because a machine with more
  * than one would otherwise get whichever is default — which may be a distribution with no install.
  *
+ * AND IT IS NEVER LEFT BLANK (owner, 2026-09-19). With no name to hand the row used to drop `-d` and take
+ * the default distribution, which fails on a machine whose default is not this one, with nothing on screen
+ * to connect the failure to the choice. The row now carries WSL_DISTRO_PLACEHOLDER in the name's place,
+ * and the Windows side's hint says plainly to fill it in. `WSL_DISTRO_NAME` is the one place the name can
+ * be read from inside the distribution: `/etc/wsl.conf` holds settings for it, not its name.
+ *
  * THE ENVIRONMENT CROSSES THROUGH `env`, NOT THROUGH THE HOST'S OWN env BLOCK. A host on Windows sets
  * variables for the process it starts, which is `wsl.exe`; they do not cross the boundary into the
  * distribution, so a work directory set that way is silently absent on the other side and the server
@@ -134,17 +140,32 @@ const separator = (platform = process.platform) => (platform === "win32" ? '"--"
  * Off WSL the launcher is exactly what it always was, so every row on every other platform is
  * byte-identical to before. PURE.
  */
-export function stdioLauncher({ server, workDir = null, reportsDir = null, wsl = null } = {}) {
+/**
+ * WHICH NODE, AND WHICH FILE (owner, 2026-09-19). A line that said bare `node` ran whatever `node` the
+ * assistant's own PATH found. Through `wsl.exe -e`, a non-login shell, that was the distribution's system
+ * Node 18 while the demo ran on Node 22, and the server died on a syntax error before saying anything
+ * (measured on a Windows laptop). A desktop assistant on any platform starts from a bare PATH the same
+ * way. So every line names the absolute Node this install is running on, `process.execPath`, seen from
+ * where the line is composed, inside WSL when that is where the install is. It names `serve.mjs`, the
+ * entry that refuses an old Node in one plain line before the server loads.
+ */
+export const STDIO_ENTRY = "serve.mjs";
+
+/** What stands in the distribution's name when it cannot be read, and the line that says to fill it in. */
+export const WSL_DISTRO_PLACEHOLDER = "YOUR-WSL-DISTRIBUTION";
+export const WSL_DISTRO_FILL_IN = `Replace ${WSL_DISTRO_PLACEHOLDER} with this Linux's name before you paste it: \`wsl -l\` in Windows lists the names.`;
+
+export function stdioLauncher({ server, workDir = null, reportsDir = null, wsl = null, node = process.execPath } = {}) {
   const vars = envOf({ workDir, reportsDir });
-  if (!wsl) return { command: "node", args: [server], env: vars, crossesIntoWsl: false };
+  if (!wsl) return { command: node, args: [server], env: vars, crossesIntoWsl: false };
   const distro = String(wsl.distro ?? "").trim();
   return {
     command: "wsl.exe",
     // `-e` runs the command directly rather than through a login shell, so nothing of the reader's
     // profile can rewrite the arguments between Windows and the server.
-    args: [...(distro ? ["-d", distro] : []), "-e",
+    args: ["-d", distro || WSL_DISTRO_PLACEHOLDER, "-e",
       ...(Object.keys(vars).length ? ["env", ...Object.entries(vars).map(([k, v]) => `${k}=${v}`)] : []),
-      "node", server],
+      node, server],
     // Already carried inside the argument list above; a host-side env block would set them on the
     // Windows process and never reach the server.
     env: {},
@@ -157,8 +178,8 @@ export const STDIO_SHAPES = Object.freeze({
   "claude-cli": {
     kind: "command",
     where: null,
-    render: ({ server, workDir, reportsDir, platform, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, platform, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       // The host's own `-e` flags set variables for the process IT starts. Off WSL that is the server;
       // through the wrapper it is `wsl.exe`, and they stop at the boundary — so on WSL they ride inside
       // the command instead and this line carries none.
@@ -170,8 +191,8 @@ export const STDIO_SHAPES = Object.freeze({
   "desktop-json": {
     kind: "config",
     where: "Settings → Developer → Edit Config",
-    render: ({ server, workDir, reportsDir, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return JSON.stringify({
         mcpServers: {
           [STDIO_SERVER_NAME]: {
@@ -189,8 +210,8 @@ export const STDIO_SHAPES = Object.freeze({
   "generic-json": {
     kind: "config",
     where: "your agent's MCP server configuration",
-    render: ({ server, workDir, reportsDir, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return JSON.stringify({
         command: l.command,
         args: l.args,
@@ -209,8 +230,8 @@ export const STDIO_SHAPES = Object.freeze({
     // Codex does not forward the shell environment, and a credential would have to be forwarded BY NAME
     // rather than written into a file. This server takes no credential — the work directory is a path,
     // not a secret — so `env` is correct here and would not be for a server that wanted a key.
-    render: ({ server, workDir, reportsDir, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return [
         `[mcp_servers.${STDIO_SERVER_NAME}]`,
         `command = "${l.command}"`,
@@ -335,11 +356,11 @@ export function remoteConnectFor(shape, { address = null } = {}) {
  */
 export const WSL_ROW_HEADINGS = Object.freeze({ fromWindows: "From Windows", insideWsl: "Inside WSL" });
 
-export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, wsl = null } = {}) {
+export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, wsl = null, node = process.execPath } = {}) {
   const spec = Object.hasOwn(STDIO_SHAPES, String(shape ?? "")) ? STDIO_SHAPES[shape] : null;
   if (!spec) return null;
-  const server = join(installRoot, "mcp-server", "server.mjs");
-  const render = (target) => spec.render({ server, workDir, reportsDir, platform, wsl: target });
+  const server = join(installRoot, "mcp-server", STDIO_ENTRY);
+  const render = (target) => spec.render({ server, workDir, reportsDir, platform, wsl: target, node });
   const base = { shape, kind: spec.kind, where: spec.where, after: spec.after, name: STDIO_SERVER_NAME };
   // OFF WSL NOTHING CHANGES: one launcher, no variants, and `variants: null` rather than an empty array
   // so a consumer cannot read "this install has no sides" as "this install has two sides, both missing".
@@ -355,7 +376,7 @@ export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ insta
     ...base,
     text: render(wsl),
     variants: [
-      { heading: WSL_ROW_HEADINGS.fromWindows, text: render(wsl) },
+      { heading: WSL_ROW_HEADINGS.fromWindows, text: render(wsl), hint: String(wsl.distro ?? "").trim() ? null : WSL_DISTRO_FILL_IN },
       { heading: WSL_ROW_HEADINGS.insideWsl, text: render(null) },
     ],
   };

package/shared/writing-standard-classes.mjs

@@ -443,9 +443,8 @@ const H1_BLOCK = /<h1\b[^>]*>([\s\S]*?)<\/h1>/g
  * heading was entirely its subject.
  */
 const isSubjectHeading = (inner) => {
-  const bare = String(inner)
-    .replace(/\{(?:[^{}]|\{[^{}]*\})*\}/g, '')   // JSX expressions, one level of nesting
-    .replace(/<[^>]*>/g, '')                      // nested tags
+  let bare = String(inner).replace(/\{(?:[^{}]|\{[^{}]*\})*\}/g, '')   // JSX expressions, one level of nesting
+  for (let prev = null; prev !== bare;) { prev = bare; bare = bare.replace(/<[^>]*>/g, '') }   // nested tags, until none is left
   return !/[A-Za-z]{2}/.test(bare)
 }