clearotron 0.3.2-beta.12 → 0.3.2-beta.13

package/scripts/citation-anchor-report.mjs

@@ -113,7 +113,7 @@ export function anchorRows(citations, linesOf) {
     if (!others.length) { rows.push({ ...c, verdict: "silent", anchor }); continue; }
     let elsewhere = null;
     for (const n of others) {
-      const decl = new RegExp(`^\\s*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function|const|let|var|class)\\s+${n.replace(/\$/g, "\\$")}\\b`);
+      const decl = new RegExp(`^\\s*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function|const|let|var|class)\\s+${n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
       for (let i = 0; i < target.length; i++) {
         if (!decl.test(target[i])) continue;
         // THE CITATION POINTING INSIDE WHAT IT NAMES IS CORRECT, not drifted — see the header.

package/scripts/citation-line-check.mjs

@@ -528,7 +528,7 @@ function main() {
 //     WATCHLIST_OWNERS_MAX declared in variant-manifest-model.mjs   anything else — `declared` marks it
 //
 // A BARE WORD BEFORE `in <file>` IS NOT A SYMBOL CITATION, deliberately, and this is the difference
-// between this arm and 's. reads the token beside a number SPECULATIVELY and drops it when it
+// between this arm and the line arm, which reads the token beside a number SPECULATIVELY and drops it when it
 // is not declared, because "ALREADY computes (coverage-ledger.mjs:180)" would otherwise manufacture a
 // defect out of emphatic prose. This arm cannot do that: an undeclared symbol has to FAIL or the check
 // has no teeth at all. So the form is opted into. `the field in scope-ledger.mjs` and `checked in
@@ -923,8 +923,8 @@ export function symbolMisses(citations, readLines) {
 // WHAT IT CANNOT SEE, and why this stays a slice. A citation that lands on the WRONG NON-BLANK LINE is
 // invisible to it — that looks identical to a correct one. Three of the eleven citations repointed in
 // `stages.mjs` under this issue were exactly that: `stages.mjs:1474` pointed at a transliteration `why:`
-// row, `pipeline.mjs:2908` at a different function entirely, and neither line was blank. Only 's
-// arm can decide those, and only where the citation names a symbol. A clean run here is evidence about
+// row, line 2908 of `pipeline.mjs` at a different function entirely, and neither line was blank. Only the
+// symbol arm can decide those, and only where the citation names a symbol. A clean run here is evidence about
 // punctuation, not about correctness.
 //
 // AN OVERRUN IS NOT THIS FINDING. A span running past the file's last line is already reported as

package/scripts/e2e.mjs

@@ -2370,7 +2370,7 @@ const TERMINAL_BY_SUFFIX_RAN = { failed: "failed", done: "delivered", cancelled:
 
 // REPAIR — the live-state vocabulary is IMPORTED, not retyped. This file's first draft spelled it
 // out twice more (an in-flight suffix set and a claim-lock regex), which is exactly the failure
-// queue-markers.mjs was created for: "written down three times and the copies disagreed ". 's
+// queue-markers.mjs was created for: "written down three times and the copies disagreed". The
 // claim lock in particular is a NORMAL in-flight state — a live token is a claim in progress, a dead one
 // is restored by sweepAbandonedTakeovers — and one more private copy of that rule is one more chance to
 // report a claim race as a stranded job.

package/scripts/env-audit.mjs

@@ -624,7 +624,7 @@ const EXTERNAL_RE = /^#\s*external:\s*(\S.*)$/;
 //
 // THE TWO MARKERS DO NOT CLEAR EACH OTHER. `pending` was a single slot, and any comment line that was
 // not an `# external:` reset it. Adding a second marker to that shape would mean an `# effect:` line
-// silently DELETED the `# external:` declaration above it — the row would go orphaned and 's
+// silently DELETED the `# external:` declaration above it — the row would go orphaned and the orphan
 // guard would red, with the cause three lines away and invisible. Each marker carries its own slot.
 const EFFECT_RE = /^#\s*effect:\s*(\S.*)$/;
 // A COMMENTED-OUT ROW STILL COUNTS, the same rule `assigned` uses above and for the same reason: `# X=`

package/scripts/env-classify.mjs

@@ -248,7 +248,7 @@ function namesMergedIntoCandidate(src) {
   const helpers = new Set([...src.matchAll(/Object\.assign\(\s*candidate\s*,\s*(?:await\s+)?([A-Za-z_$][\w$]*)\s*\(/g)]
     .map((m) => m[1]));
   for (const fn of helpers) {
-    const at = src.search(new RegExp(`\\bfunction\\s+${fn.replace(/\$/g, "\\$")}\\s*\\(`));
+    const at = src.search(new RegExp(`\\bfunction\\s+${fn.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\(`));
     const refuse = (why) => new Error(`env-classify: bin/onboard.mjs writes what ${fn}() returns, and ${why}, so `
       + "the names it writes cannot be read. Read as none, they would land in `tuning` and on the deletion "
       + "population; that is this script failing to look, not a finding about the wizard.");

package/scripts/pack-publishable.mjs

@@ -123,7 +123,7 @@ async function main() {
     try {
       ({ reconcileAndScan: gate } = await import("../cut/packed-artifact.mjs"));
     } catch (e) {
-      console.error("  REFUSING (exit 2, could-not-look): cut/packed-artifact.mjs did not load —"
+      console.error("  REFUSING (exit 2, could not look): cut/packed-artifact.mjs did not load —"
         + ` ${String(e?.message ?? e)}.\n`
         + "  That module carries the only rule that says which files may leave this repository, and a\n"
         + "  pack that cannot ask it produces an artifact nobody has checked. An exported tree does not\n"

package/scripts/release-artifact-seal.mjs

@@ -106,10 +106,10 @@ function main() {
     console.error("usage: node scripts/release-artifact-seal.mjs --tarball <path>");
     process.exit(2);
   }
-  // A path that is not there is a could-not-look, never a seal that found nothing to do. Exit 2 is
+  // A path that is not there is a check that could not look, never a seal that found nothing to do. Exit 2 is
   // the house meaning and it keeps this distinguishable from a tarball that was sealed and was clean.
   if (!existsSync(tarball)) {
-    console.error(`  REFUSING (exit 2, could-not-look): ${tarball} does not exist, so nothing was sealed.`);
+    console.error(`  REFUSING (exit 2, could not look): ${tarball} does not exist, so nothing was sealed.`);
     process.exit(2);
   }
 

package/scripts/settings-render-check.mjs

@@ -148,6 +148,10 @@ const sessionId = sess.sessionId
 const cmd = (method, params = {}) => new Promise((r) => { const i = ++id; pending.set(i, r); ws.send(JSON.stringify({ id: i, sessionId, method, params })) })
 await cmd('Page.enable')
 // A probe that throws says so, rather than returning nothing for the assertions after it to misread.
+// A value pasted into code the page evaluates, as a JavaScript string or object literal. JSON.stringify
+// alone leaves `<`, `>`, `/` and the two line separators as they are; escaped, they read the same once
+// parsed and cannot close or break the code they are pasted into.
+const jsLiteral = (v) => JSON.stringify(v).replace(/[<>\/\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)
 const evalIn = async (expr) => {
   const r = (await cmd('Runtime.evaluate', { expression: expr, awaitPromise: true, returnByValue: true })).result
   if (r?.exceptionDetails) console.error(`  ! a probe threw: ${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text}`)
@@ -184,7 +188,7 @@ async function reload(ready, what) {
 }
 
 async function setTheme(theme) {
-  await evalIn(`(() => { document.documentElement.setAttribute('data-theme', ${JSON.stringify(theme)}); try { localStorage.setItem('cordillera-theme', ${JSON.stringify(theme)}) } catch {} return true })()`)
+  await evalIn(`(() => { document.documentElement.setAttribute('data-theme', ${jsLiteral(theme)}); try { localStorage.setItem('cordillera-theme', ${jsLiteral(theme)}) } catch {} return true })()`)
   await sleep(250)
 }
 

package/scripts/strip-tracker-citations.mjs

@@ -2,15 +2,15 @@
 // 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
 //
-// Removes the internal citation OPENER from comments and prose in the tree (tracker issue 309).
+// Removes the internal citation OPENER from comments and prose in the tree.
 //
 // The form is `tracker issue NNN — ` standing at the head of a sentence, where the citation is not part
 // of what the sentence says but a label in front of it. Stripping the opener leaves the sentence intact:
 //
-//     // tracker issue 1149 — the walk must start at the repository root
+//     // tracker issue NNNN — the walk must start at the repository root
 //     // the walk must start at the repository root
 //
-//     assert.ok(x, "Refs tracker issue 2075 — an absent file is a finding")
+//     assert.ok(x, "Refs tracker issue NNNN — an absent file is a finding")
 //     assert.ok(x, "an absent file is a finding")
 //
 // WHY THE PATTERN LOOKS OVER-SPECIFIED. Three parts of it are load-bearing and each was measured, not
@@ -20,7 +20,7 @@
 //     and the replacement is `$1`, which puts that opener back. Without the group the sweep deletes the
 //     opening quote of every test name it touches, and a broken string literal is a syntax error in the
 //     lucky cases and a changed assertion in the unlucky ones.
-//   · `\s+` AFTER THE SEPARATOR, never `\s*`. `tracker issue 1149-12` is an ITEM suffix, not a citation
+//   · `\s+` AFTER THE SEPARATOR, never `\s*`. `tracker issue NNNN-12` is an ITEM suffix, not a citation
 //     followed by prose: there is no space after its hyphen. `\s*` eats the item number.
 //   · THE `i` FLAG. `Refs tracker issue NNN` is capitalised at the head of a commit-style line and is a
 //     fifth of the corpus.

package/scripts/test-run.mjs

@@ -271,8 +271,8 @@ process.env.CLEAROTRON_DEMO_PROFILES ??= "1";
 // driver/test/*.test.mjs. They are indistinguishable from code defects. An agent who runs the suite on a
 // branch, sees 295 red, and diffs the failing NAMES against a baseline taken the same way sees zero
 // regressions and calls the branch clean — and it is, but roughly 190 tests never executed, and a real
-// regression inside any of them is invisible by exactly that arithmetic. It has already happened: 's
-// first full-suite comparison was taken against a 295-fail baseline.
+// regression inside any of them is invisible by exactly that arithmetic. It has already happened: a
+// full-suite comparison was taken against a 295-fail baseline.
 //
 // So: refuse, name what is missing, and name the command. REFUSE RATHER THAN INSTALL — this wrapper is
 // what CI and scripts/publication-scan.mjs run the suite through, and a wrapper that can start a network
@@ -751,6 +751,37 @@ const repoBefore = snapshotRepo(REPO_ROOT);
 const RUN_HOME = String(process.env.HOME ?? "").trim() || homedir();
 const homeBefore = snapshotHome(RUN_HOME);
 
+// ── AND NOTHING THE RUN MADE IS LEFT IN THE MACHINE'S TEMP DIRECTORY ────────────────────────────────
+//
+// The run's own root is removed on every exit. What escapes it is a child handed an environment without
+// TMPDIR: it falls back to the machine's temp directory, and nothing removes what it made there. Measured
+// 2026-09-19: fifteen `clearotron-demo-*` directories per `npm test`, from the demo's temporary sample
+// copies, and 36 GB accumulated on one box. Named by the product prefix, so the guard reads only what
+// this product makes; owned by this account, so another user's run is not ours to count.
+//
+// THE OUTERMOST RUN WATCHES THE MACHINE'S TEMP ROOTS. A nested run watches only its own base, and only
+// when a test arms it (CT_TEMP_LEAK_GUARD=1): the runner's own tests drive nested runs while the rest of
+// the suite is working, and a nested guard reading the shared root would count its neighbours' files.
+const LEAK_PREFIXES = Object.freeze(["clearotron-demo-"]);
+const OUTERMOST = !String(process.env.CT_TEST_MACHINE_TMP ?? "").trim();
+const LEAK_ROOTS = OUTERMOST
+  ? [...new Set([MACHINE_TMP, REAL_TMP, ...PLATFORM_TMP].map((p) => resolve(p)))]
+  : String(process.env.CT_TEMP_LEAK_GUARD ?? "") === "1" ? [resolve(REAL_TMP)] : [];
+function tempLeftovers() {
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  const out = new Set();
+  for (const r of LEAK_ROOTS) {
+    let names;
+    try { names = readdirSync(r); } catch { continue; }
+    for (const n of names) {
+      if (!LEAK_PREFIXES.some((p) => n.startsWith(p))) continue;
+      try { if (uid == null || statSync(join(r, n)).uid === uid) out.add(join(r, n)); } catch { /* gone already */ }
+    }
+  }
+  return out;
+}
+const tempBefore = tempLeftovers();
+
 
 child = spawn(argv[0], argv.slice(1), {
   stdio: "inherit",
@@ -808,8 +839,20 @@ child.on("close", (code, signal) => {
   if (wrote.length) for (const line of explainRepoWrites(wrote)) console.error(line);
   const wroteHome = repoWrites(homeBefore, snapshotHome(RUN_HOME), RUN_HOME);
   if (wroteHome.length) for (const line of explainHomeWrites(wroteHome, RUN_HOME)) console.error(line);
+  const leftInTemp = [...tempLeftovers()].filter((p) => !tempBefore.has(p)).sort();
+  if (leftInTemp.length) {
+    console.error("");
+    console.error(`[test-run] THIS RUN LEFT ${leftInTemp.length} DIRECTOR${leftInTemp.length === 1 ? "Y" : "IES"} IN THE MACHINE'S TEMP DIRECTORY:`);
+    for (const p of leftInTemp) console.error(`  + ${p}`);
+    console.error("");
+    console.error("  A child handed an environment without TMPDIR puts its temporary files in the machine's temp");
+    console.error("  directory, where nothing removes them. Pass `TMPDIR: tmpdir()` in that child's env, so they land");
+    console.error("  in this run's own root, which is removed on every exit.");
+    console.error("");
+    console.error("  (Another run on this account making the same directories at the same time prints this too.)");
+  }
   // THIS MAY TURN A GREEN RUN RED. IT MUST NEVER TURN A RED RUN GREEN — a failing suite keeps its own
   // exit code, because what the tests found matters more than what they wrote while finding it.
   const childCode = code ?? 1;
-  process.exit(childCode !== 0 ? childCode : (wrote.length || wroteHome.length ? 1 : 0));
+  process.exit(childCode !== 0 ? childCode : (wrote.length || wroteHome.length || leftInTemp.length ? 1 : 0));
 });

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

@@ -214,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
@@ -238,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 };
 }
 
 /**
@@ -300,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 `
@@ -313,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/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/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)
 }