clearotron 0.3.2-beta.13 → 0.3.2-beta.14

package/bin/clearotron.mjs

@@ -25,6 +25,7 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { nodeFloorVerdict, nodeFloorRefusal } from "../shared/node-floor.mjs";   // — one floor, read from package.json
 import { invocationPrefix } from "../shared/invocation.mjs";   // — print a command the reader can type
 import { watchParent } from "../shared/parent-watch.mjs";
+import { EXPERIMENTAL_WARNING_OFF } from "../shared/demo-start-args.mjs";
 
 export const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -193,7 +194,12 @@ const [verb, ...rest] = process.argv.slice(2);
   // — tell the child how the READER reached us, so its own advice names a command they can type.
   // Without this every spawned verb sees argv[1] = its own implementation file and would print `npx`
   // even for somebody who typed a bare `clearotron`.
-  const child = spawn(process.execPath, [target, ...builtin, ...rest], {
+  // THE DEMO RUNS WITHOUT NODE'S EXPERIMENTAL-FEATURE WARNING. Node prints one the first time anything loads
+  // its built-in SQLite, and on the demo it landed on the first screen, above the sentence saying what the
+  // demo is. A flag on the demo's own process; `bin/example.mjs` hands it on to the services it starts
+  // (EXPERIMENTAL_WARNING_OFF). Every other warning still prints.
+  const quiet = verb === "demo" ? [EXPERIMENTAL_WARNING_OFF] : [];
+  const child = spawn(process.execPath, [...quiet, target, ...builtin, ...rest], {
     stdio: "inherit",
     env: { ...process.env, CLEAROTRON_INVOKED_AS: process.argv[1] ?? "" },
   });

package/bin/example.mjs

@@ -38,7 +38,7 @@ import "../shared/env-local.mjs";   // step 4 / — FIRST: this program read a
 // handed it nothing and the read fell through to a default. Proven both ways from one
 // environment: without this import the value is invisible, with it the retired spelling is
 // back-filled. Placed above every other import because a side-effecting import runs in order.
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { removeDirectory } from "../shared/os-advice.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — the printed command is resolved once, for the reader who is actually standing there
@@ -53,7 +53,7 @@ import { ensureDemoProgram, demoProgramEnv } from "../shared/permanent-install.m
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 
 import { usageBlock } from "../shared/usage-block.mjs";
-import { demoStartArgs } from "../shared/demo-start-args.mjs";
+import { demoStartArgs, withWarningOff } from "../shared/demo-start-args.mjs";
 import { bundleVerdict } from "../shared/bundle-freshness.mjs";
 const argv = process.argv.slice(2);
 const flag = (n, d = null) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : d; };
@@ -258,6 +258,14 @@ if (existsSync(poolRoot) && !statSync(poolRoot).isDirectory()) die(`demo: ${pool
 
 // ── 3. replay ────────────────────────────────────────────────────────────────────────────────────────
 console.log(`\n  ${BRAND.name} ${BRAND.product.toLowerCase()} — demo\n`);
+// THE LABEL, FIRST. The reader is about to look at a document that reads like advice about a real mark. It
+// is not, and the demo says so before anything else rather than in a footnote nobody reaches. It printed
+// after the replay, below the engine's own diagnostics and a Node warning, so the first thing a newcomer
+// read was internal tallies (measured on the published beta, 2026-09-19).
+console.log("  Real engine output for the fictional mark VENQORI, captured against Clarivate Compumark.");
+console.log("  Replaying it needs no account, no key and no network.");
+console.log("  Every number, band and citation below was produced by that real run and is being");
+console.log("  re-rendered from its artifacts. It is an example, not advice.\n");
 console.log(samples.length === 1
   ? `  sample:  ${samples[0].dir}`
   : `  samples: ${samples.length}${failures.length ? ` of ${shipped}` : ""} — ${samples.map((x) => x.name).join(", ")}`);
@@ -276,14 +284,33 @@ const { republishRun } = await import(pathToFileURL(join(REPO, "driver", "publis
 // The failures are collected and reported together at the end, and the process exits non-zero, because a
 // demo that came up missing a quarter of itself is not a success however good the three look.
 const results = [];
-for (const s0 of samples) {
-  try {
-    // poolUrl "" on purpose: the report's own link block is for a deployment that serves the pool at a
-    // public URL. This one is served from this process, at a port picked below.
-    results.push({ ...s0, published: await republishRun({ runId: s0.meta.runId, meta: s0.meta, pool: poolRoot, poolUrl: "", runDir: join(s0.publishFrom, "run") }) });
-  } catch (e) {
-    failures.push({ name: s0.name, why: String(e?.message ?? e) });
+// THE PUBLISHER'S OWN DIAGNOSTICS GO TO A FILE. It prints its tallies as it works (`[record-links] …`,
+// `knockout receipts: …`), which is right for an operator watching a delivery and wrong as the first
+// screen a newcomer reads. The replay's output is written to `replay.log` in the folder this demo made,
+// and restored when the replay ends, so everything below prints as before. A failure is not lost: it is
+// collected here and reported after the list.
+const replayLog = join(flag("--pool") ? poolRoot : demoBase, "replay.log");
+const toLog = (chunk, encoding, cb) => {
+  try { appendFileSync(replayLog, chunk, typeof encoding === "string" ? encoding : undefined); } catch { /* a log that cannot be written must not stop the replay */ }
+  if (typeof encoding === "function") encoding(); else if (typeof cb === "function") cb();
+  return true;
+};
+const screen = { out: process.stdout.write, err: process.stderr.write };
+process.stdout.write = toLog;
+process.stderr.write = toLog;
+try {
+  for (const s0 of samples) {
+    try {
+      // poolUrl "" on purpose: the report's own link block is for a deployment that serves the pool at a
+      // public URL. This one is served from this process, at a port picked below.
+      results.push({ ...s0, published: await republishRun({ runId: s0.meta.runId, meta: s0.meta, pool: poolRoot, poolUrl: "", runDir: join(s0.publishFrom, "run") }) });
+    } catch (e) {
+      failures.push({ name: s0.name, why: String(e?.message ?? e) });
+    }
   }
+} finally {
+  process.stdout.write = screen.out;
+  process.stderr.write = screen.err;
 }
 // PUBLISHED, SO THE COPIES THEY WERE PUBLISHED FROM GO NOW, whatever comes next.
 releaseDemoCopies();
@@ -293,12 +320,6 @@ if (!results.length) {
 }
 const published = results[0].published;
 
-// THE LABEL. The reader is about to look at a document that reads like advice about a real mark. It is
-// not, and the demo says so before the browser opens rather than in a footnote nobody reaches.
-console.log("  Real engine output for the fictional mark VENQORI, captured against Clarivate Compumark.");
-console.log("  Replaying it needs no account, no key and no network.");
-console.log("  Every number, band and citation below was produced by that real run and is being");
-console.log("  re-rendered from its artifacts. It is an example, not advice.\n");
 // NAMES THE POPULATION. This printed "13 finding(s)" beside a report showing
 // twelve, in the first sentence a reader meets. The number is not wrong — it comes from the audit
 // spine (`driver/publish/audit-from-spine.mjs`, `counts.findings`), which counts every finding the run
@@ -307,10 +328,8 @@ console.log("  re-rendered from its artifacts. It is an example, not advice.\n")
 // EACH LANE'S PUBLISHER REPORTS ITS OWN NUMBER, AND THEY ARE NOT THE SAME NUMBER.
 //
 // The clearance branch returns `counts.findings` — every finding in the run's audit spine. The knockout
-// branch returns no `counts` at all; it returns `receipts`, whose `findings` counts the findings whose
-// citations the publisher traced to the run's own held evidence. That is a subset by definition, so it
-// is printed in its own words rather than mapped onto the clearance sentence. They happen to agree on
-// the demo in this tree, which is one member of a class and proves nothing about the metric.
+// branch returns no `counts` at all; it returns the names it screened and the rating each was given, so
+// its line states those rather than a count mapped onto the clearance sentence.
 //
 // The third branch is the point: a lane whose publisher reports no count says so. This line printed a
 // bare "?" to the knockout — a could-not-look wearing the costume of a number.
@@ -322,9 +341,13 @@ const spineOf = (pub) =>
   Number.isFinite(pub.counts?.findings)
     ? `${pub.counts.findings} finding(s) recorded in the run's audit trail; the report shows
              the ones it retains`
-    : Number.isFinite(pub.receipts?.findings)
-      ? `${pub.receipts.findings} finding(s) with citations traced to this run's own held
-             evidence, on ${pub.receipts.citing}/${pub.receipts.marks} mark(s)`
+    // A KNOCKOUT STATES WHAT IT SCREENED AND HOW EACH NAME WAS RATED, in the words its own report opens
+    // with ("One name screened: VENQORI, rated Low."). It used to count citations traced to held evidence,
+    // which a knockout's register-only findings never carry, so the line read "0 finding(s)" and a stranger
+    // took it as "the demo found nothing". Chosen 2026-09-19.
+    : Array.isArray(pub.reports) && pub.reports.length
+      ? `${pub.reports.length} name${pub.reports.length === 1 ? "" : "s"} screened: ${pub.reports
+        .map((r) => (r.band ? `${r.mark}, rated ${r.band}` : r.mark)).join("; ")}; the report shows why`
       : `this lane's publisher reported no finding count — the report itself is the record`;
 for (const r of results) console.log(`  published: ${r.published.runId}\n             ${r.name} — ${spineOf(r.published)}`);
 // "ONE PER PRODUCT" ONLY WHEN IT IS TRUE: with a sample missing, the count below says how many of how many.
@@ -418,6 +441,10 @@ console.log("");
 // made, it starts from here as before.
 const programRoot = ensureDemoProgram({ base: demoBase, say: (line) => console.log(line) });
 const startFrom = programRoot ?? REPO;
+// The services inherit the demo's Node flag through NODE_OPTIONS, so none of them prints the SQLite warning
+// either. Set on this process's own environment, which both branches below hand on; the reader's own
+// NODE_OPTIONS is kept.
+process.env.NODE_OPTIONS = withWarningOff(process.env.NODE_OPTIONS);
 const child = spawn(process.execPath, [join(startFrom, "bin", "start.mjs"), ...startArgs], {
   cwd: startFrom, stdio: ["ignore", "inherit", "inherit"],
   env: programRoot ? demoProgramEnv(process.env) : process.env,

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "f107c38f60f6cd5536cd30edb3d2b3ad8a1d1d97",
-  "version": "0.3.2-beta.13"
+  "commit": "94613f865f0ca4af3a17122f5d51cbfb7615f738",
+  "version": "0.3.2-beta.14"
 }

package/driver/CHANGELOG.md

@@ -1,5 +1,13 @@
 # clearotron-driver
 
+## 0.3.2-beta.14
+
+### Patch Changes
+
+- Fixed: The lines for connecting an AI assistant now work when a folder name contains spaces, and the Codex settings block now works on Windows.
+- Fixed: The demo now opens by saying what it shows, without internal diagnostics or a Node warning, and its knockout sample states the rating it reached.
+- Fixed: A knockout report ordered for named countries now lists those countries under Registers counted, instead of a count of the provider's registers.
+
 ## 0.3.2-beta.13
 
 ### Patch Changes

package/driver/engine/mcp/codex-config.mjs

@@ -5,6 +5,7 @@
 // exact server/tool wiring. Two inputs, both produced today by the gateway gather block:
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { tomlString } from "../../../shared/toml-string.mjs";
 
 //   • mcpConfig     — the claude-shaped JSON string `{mcpServers:{name:{command,args,env,connectionTimeoutMs?}}}`
 //                     (buildGatherMcpConfig → JSON.stringify)
@@ -36,17 +37,8 @@ export const CRED_ENV_FORWARD = [
 ];
 
 // ── TOML value escaping (basic strings) ──────────────────────────────────────────────────────────────
-export function tomlString(s) {
-  const str = String(s ?? "");
-  // TOML basic-string escapes: backslash, double-quote, and the C0 controls TOML names (\b \t \n \f \r).
-  const esc = str
-    .replace(/\\/g, "\\\\").replace(/"/g, '\\"')
-    .replace(/\x08/g, "\\b").replace(/\t/g, "\\t").replace(/\n/g, "\\n")
-    .replace(/\f/g, "\\f").replace(/\r/g, "\\r")
-    // any remaining control char → \uXXXX (TOML-legal)
-    .replace(/[\x00-\x1f]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
-  return `"${esc}"`;
-}
+// One encoder for every TOML block the product writes; re-exported so this module's callers keep their import.
+export { tomlString };
 function tomlStringArray(arr) {
   return "[" + (arr || []).map(tomlString).join(", ") + "]";
 }

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.2-beta.13",
+  "version": "0.3.2-beta.14",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/publish/render-knockout.mjs

@@ -63,6 +63,7 @@ import { EXPORT_TOGGLE, exportPopover, EXPORT_MENU_JS } from './report-topbar.mj
 import { makeClassifyStatus, isAllClass } from '../../providers/_shared/screen.mjs';
 import { saysSomethingNew } from '../../shared/says-something-new.mjs';
 import { isNextStepHeading } from '../knockout-next-step.mjs';
+import OFFERED from '../../shared/offered-territories.json' with { type: 'json' };   // the order form's own territory names
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -481,6 +482,14 @@ function territoryName(code, { bare = false } = {}) {
   } catch { return ''; }
 }
 
+/** A territory the order names, in the order form's own words, or '' when that list has no such code. */
+const ORDER_FORM_NAMES = new Map([...OFFERED.regions, ...OFFERED.countries].map((t) => [t.code, t.name]));
+const orderedTerritoryName = (code) => {
+  const c = String(code ?? '').trim().toUpperCase();
+  // EM is the European Union register's own code, and some records carry it for an EU order.
+  return ORDER_FORM_NAMES.get(c === 'EM' ? 'EU' : c) ?? '';
+};
+
 /** "a, b and c" — the reader's list, not a join on commas. */
 function listWords(items) {
   const xs = (items ?? []).filter(Boolean);
@@ -1244,12 +1253,28 @@ function aboutRequestBlock(scope, requestNotes, depthNote = '', productContext =
   // the middle of the panel is the thing a reader skips; the count and its source are what they read.
   const regions = (registerCounts?.scope?.regions ?? []).filter(Boolean);
   const provider = registerCounts?.providerLabel ?? registerCounts?.provider ?? '';
-  // THE BOARD'S OWN ROW: "186 registers, on Clarivate Compumark." — registers, because that is what was
-  // counted, and no fold: the board lists no territories here, and the workbook's counts sheet carries
-  // every register a figure was taken over.
-  const counted = regions.length
-    ? `${regions.length} ${regions.length === 1 ? 'register' : 'registers'}${provider ? `, on ${provider}` : ''}.`
-    : (registerCounts ? `Counted worldwide${provider ? `, on ${provider}` : ''}` : '');
+  // THE ORDER'S TERRITORIES, NOT THE PROVIDER'S REGISTERS (owner, 2026-09-19). The row counted the
+  // registers the provider searched, and for a one-country order that is not one: a United States order is
+  // counted over the United States and the international register, because an international filing can
+  // designate the United States. A client who ordered one country read "2 registers" as a mistake. So an
+  // order that names its territories is stated as it named them, in the order form's own names; the
+  // registers actually counted stay in the line under the counts table. A worldwide order keeps the board's
+  // row, "186 registers, on Clarivate Compumark.", because there the count is the scope (the record says
+  // worldwide by carrying no jurisdictions). A territory the provider does not cover was not counted, so it
+  // is not listed here; it is disclosed where deferrals are. A territory the form's list cannot name, or an
+  // office this install could not reach, falls back to the count rather than printing a code or claiming
+  // a territory nothing was counted in.
+  const on = provider ? `, on ${provider}` : '';
+  const sc = registerCounts?.scope ?? {};
+  const deferred = new Set((sc.deferredJurisdictions ?? []).map((c) => String(c ?? '').trim().toUpperCase()));
+  const ordered = [...new Set((sc.jurisdictions ?? [])
+    .filter((c) => !deferred.has(String(c ?? '').trim().toUpperCase())).map(orderedTerritoryName))];
+  const namesTheOrder = sc.worldwide !== true && !(sc.unreachableOffices ?? []).length
+    && ordered.length > 0 && ordered.every(Boolean);
+  const counted = namesTheOrder ? `${listWords(ordered)}${on}.`
+    : regions.length
+      ? `${regions.length} ${regions.length === 1 ? 'register' : 'registers'}${on}.`
+      : (registerCounts ? `Counted worldwide${on}` : '');
   if (!asked && !where && !classLine && !stage && !context && !counted) return '';
   // ONE PANEL, THE SAME ON BOTH REPORTS (the 2026-09-16 report redesign). The rows carry what was asked for; the
   // counts row says what was counted and hides the territory list behind a fold rather than running a

package/driver/suite-census.json

@@ -201,6 +201,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-connect-line-keeps-every-path-whole.test.mjs": {
+          "tests": 8,
+          "asserts": 20,
+          "skips": 0,
+          "todos": 0
+        },
         "a-connect-line-says-where-it-runs.test.mjs": {
           "tests": 11,
           "asserts": 56,
@@ -4869,6 +4875,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-demo-says-what-it-is-first.test.mjs": {
+          "tests": 3,
+          "asserts": 16,
+          "skips": 0,
+          "todos": 0
+        },
         "the-demo-takes-its-folder-with-it.test.mjs": {
           "tests": 6,
           "asserts": 12,
@@ -5051,7 +5063,7 @@
         },
         "the-knockout-page-leads-with-the-read.test.mjs": {
           "tests": 39,
-          "asserts": 120,
+          "asserts": 125,
           "skips": 0,
           "todos": 0
         },

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-artifacts-mcp
 
+## 0.3.2-beta.14
+
+No changes in this release.
+
 ## 0.3.2-beta.13
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.2-beta.13",
+  "version": "0.3.2-beta.14",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.3.2-beta.13",
+  "version": "0.3.2-beta.14",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.2-beta.13",
+  "version": "0.3.2-beta.14",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.2-beta.14
+
+No changes in this release.
+
 ## 0.3.2-beta.13
 
 No changes in this release.

package/providers/oauth-mcp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.3.2-beta.13",
+  "version": "0.3.2-beta.14",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",

package/shared/demo-start-args.mjs

@@ -12,6 +12,16 @@
  * `--demo-own-base` says it is the demo's default, which is what lets the supervisor remove the folder
  * when the window closes. `--keep` is the reader's, and it travels as given.
  */
+/**
+ * The Node flag the demo runs under, so Node's one-time warning that its built-in SQLite is experimental
+ * does not land on the demo's first screen. Named once: the launcher puts it on the demo's own process,
+ * and `bin/example.mjs` hands it to the services it starts through NODE_OPTIONS.
+ */
+export const EXPERIMENTAL_WARNING_OFF = "--disable-warning=ExperimentalWarning";
+
+/** The same flag added to whatever NODE_OPTIONS the reader already has, which is kept. PURE. */
+export const withWarningOff = (nodeOptions) => [nodeOptions, EXPERIMENTAL_WARNING_OFF].filter(Boolean).join(" ");
+
 export function demoStartArgs({ demoBase, readerBase = false, keep = false, port = null, noOpen = false } = {}) {
   const args = ["--demo", "--base", demoBase];
   if (!readerBase) args.push("--demo-own-base");

package/shared/stdio-connect.mjs

@@ -32,6 +32,7 @@
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { stableInstallRoot } from "./permanent-install.mjs";
+import { tomlString } from "./toml-string.mjs";
 
 /** The install root — the directory holding `mcp-server/`, resolved from this module rather than cwd. */
 export const INSTALL_ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
@@ -103,15 +104,38 @@ export function stdioConnectOffer(opts = {}) {
 function envOf({ workDir = null, reportsDir = null } = {}) {
   return { ...(workDir ? { CLEAROTRON_WORK_DIR: workDir } : {}), ...(reportsDir ? { CLEAROTRON_REPORTS_DIR: reportsDir } : {}) };
 }
-const envFlags = (o) => Object.entries(envOf(o)).map(([k, v]) => ` -e ${k}=${v}`).join("");
 const envBlock = (o) => (Object.keys(envOf(o)).length ? { env: envOf(o) } : {});
 
+// ── ONE WORD PER ARGUMENT, IN THE SHELL THAT READS THE LINE ───────────────────────────────────────────
+//
+// The command was the arguments joined with spaces, so a path with a space in it became two arguments:
+// `/tmp/Example User/node/bin/node` reached the assistant as `/tmp/Example` and `User/node/bin/node`
+// (measured on the published beta, 2026-09-19). Each argument is now written as one word for the shell it
+// is pasted into. A word made only of characters no shell treats specially is left bare, so the line for
+// an ordinary install reads exactly as it did.
+//
+// POSIX shells: single quotes, the one quoting in which no character is special. A single quote inside is
+// closed, escaped and reopened.
+const POSIX_BARE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+export const posixWord = (s) => (POSIX_BARE.test(String(s)) ? String(s) : `'${String(s).replace(/'/g, "'\\''")}'`);
+// Windows: cmd and PowerShell both honour double quotes, and the program then splits its command line by
+// the C runtime's rules, under which backslashes are literal except where they run up to a quote; there
+// they are doubled, and a quote inside the word is escaped. A comma or a parenthesis is quoted too, because
+// PowerShell reads a bare one as an array or an expression. `$`, a backtick and `%` cannot be quoted the
+// same way for both shells, and a path holding one is left to the reader.
+const WINDOWS_BARE = /^[A-Za-z0-9_+=:./\\-]+$/;
+export const windowsWord = (s) => {
+  const w = String(s);
+  if (WINDOWS_BARE.test(w)) return w;
+  return `"${w.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+};
+
 /**
  * The argument that ends Claude Code's own options. Windows PowerShell 5.1 drops a bare `--` before it
  * reaches a native program, so the line failed with "missing required argument"; quoted, every shell passes
  * it through (bash, zsh, PowerShell and cmd alike), so a Windows install is handed the quoted form.
  */
-const separator = (platform = process.platform) => (platform === "win32" ? '"--"' : "--");
+const separator = (windowsShell) => (windowsShell ? '"--"' : "--");
 
 /**
  * WHAT THE HOST ACTUALLY RUNS, and on WSL that is not `node`.
@@ -180,11 +204,17 @@ export const STDIO_SHAPES = Object.freeze({
     where: null,
     render: ({ server, workDir, reportsDir, platform, wsl, node }) => {
       const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
+      // WHICH SHELL READS IT. A native Windows install's line is pasted on Windows, and so is the row
+      // that crosses into WSL: it exists for an assistant on the Windows side. Everything else is pasted
+      // into a POSIX shell.
+      const windowsShell = platform === "win32" || l.crossesIntoWsl;
+      const word = windowsShell ? windowsWord : posixWord;
       // 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.
-      const flags = l.crossesIntoWsl ? "" : envFlags({ workDir, reportsDir });
-      return `claude mcp add ${STDIO_SERVER_NAME} --scope user${flags} ${separator(platform)} ${l.command} ${l.args.join(" ")}`;
+      const flags = l.crossesIntoWsl ? ""
+        : Object.entries(envOf({ workDir, reportsDir })).map(([k, v]) => ` -e ${windowsShell ? word(`${k}=${v}`) : `${k}=${word(v)}`}`).join("");
+      return `claude mcp add ${STDIO_SERVER_NAME} --scope user${flags} ${separator(windowsShell)} ${[l.command, ...l.args].map(word).join(" ")}`;
     },
     after: null,
   },
@@ -224,7 +254,8 @@ export const STDIO_SHAPES = Object.freeze({
     kind: "config",
     where: "~/.codex/config.toml",
     // Written out rather than produced by a TOML library: this is four lines with no user-supplied
-    // strings in key positions, and adding a dependency to emit them would be the larger risk.
+    // strings in key positions, and adding a dependency to emit them would be the larger risk. Every
+    // value goes through `tomlString`, so a Windows path's backslashes are escaped as TOML requires.
     //
     // `env` and not `env_vars`, deliberately, and CONNECT.md explains why the distinction matters:
     // Codex does not forward the shell environment, and a credential would have to be forwarded BY NAME
@@ -234,10 +265,10 @@ export const STDIO_SHAPES = Object.freeze({
       const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return [
         `[mcp_servers.${STDIO_SERVER_NAME}]`,
-        `command = "${l.command}"`,
-        `args = [${l.args.map((a) => `"${a}"`).join(", ")}]`,
+        `command = ${tomlString(l.command)}`,
+        `args = [${l.args.map(tomlString).join(", ")}]`,
         ...(Object.keys(l.env).length
-          ? [`env = { ${Object.entries(l.env).map(([k, v]) => `${k} = "${v}"`).join(", ")} }`] : []),
+          ? [`env = { ${Object.entries(l.env).map(([k, v]) => `${k} = ${tomlString(v)}`).join(", ")} }`] : []),
       ].join("\n");
     },
     after: null,
@@ -297,7 +328,7 @@ export const REMOTE_SHAPES = Object.freeze({
     label: "Copy block",
     render: ({ address }) => [
       `[mcp_servers.${STDIO_SERVER_NAME}]`,
-      `url = "${address}"`,
+      `url = ${tomlString(address)}`,
     ].join("\n"),
   },
   "claude-cli-http": {
@@ -309,7 +340,7 @@ export const REMOTE_SHAPES = Object.freeze({
     label: null,
     render: ({ address }) => [
       `[mcp_servers.${STDIO_SERVER_NAME}]`,
-      `url = "${address}"`,
+      `url = ${tomlString(address)}`,
       `bearer_token_env_var = "${KEY_ENV_VAR}"`,
     ].join("\n"),
   },

package/shared/toml-string.mjs

@@ -0,0 +1,25 @@
+// 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
+//
+// ONE TOML STRING ENCODER, for every block this product writes.
+//
+// Two composers write TOML: the engine's per-run Codex configuration and the connection block a reader
+// pastes into `~/.codex/config.toml`. The second wrapped raw values in double quotes, so a Windows path
+// such as `C:\Program Files\nodejs\node.exe` produced a file TOML parsers refuse ("Unescaped '\' in a
+// string"). A value is a TOML string only once it has been through here.
+
+/**
+ * A TOML basic string holding exactly `s`. PURE.
+ *
+ * TOML requires the quotation mark, the backslash and every control character other than tab to be
+ * escaped (U+0000 to U+0008, U+000A to U+001F, and U+007F). The named escapes are used where TOML has one,
+ * and `\uXXXX` for the rest.
+ */
+export function tomlString(s) {
+  const esc = String(s ?? "")
+    .replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+    .replace(/\x08/g, "\\b").replace(/\t/g, "\\t").replace(/\n/g, "\\n")
+    .replace(/\f/g, "\\f").replace(/\r/g, "\\r")
+    .replace(/[\x00-\x1f\x7f]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+  return `"${esc}"`;
+}