clearotron 0.4.0-beta.1 → 0.4.0-beta.3

package/INSTALL.md

@@ -45,23 +45,10 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
   Node 20, or on 22.0 through 22.12, the install succeeds and the first US search fails with
   `ERR_UNKNOWN_BUILTIN_MODULE`, saying nothing about Node. `package.json` declares the floor, the
   install refuses below it before writing anything, and `nvm use` picks the pin up.
-- **macOS, Linux, or native Windows for the demo; WSL2 for a clearance.** `npx clearotron
-  demo` runs anywhere Node does, native Windows included. A real clearance does not: the engine spawns
-  each stage with POSIX path and process semantics, so on native Windows a clearance is refused before it
-  starts, even with the program installed. Native Windows clearances are planned for a later
-  release. Until then, on Windows,
-  `wsl --install -d Ubuntu`, then `wsl -d Ubuntu`, and work through this page
-  from **inside** that distribution. Name it: plain `wsl` can open a minimal image with no apt, no
-  curl and no bash, and everything below assumes Ubuntu. A fresh Ubuntu has no Node at all, and
-  apt's package is below the floor above, so `npx` answers "not found" before anything of ours runs.
-  From the Ubuntu prompt:
-
-  ```bash
-  sudo apt update && sudo apt install -y curl
-  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
-  . "$HOME/.nvm/nvm.sh" && nvm install 22    # 22.13 or newer, per the floor above
-  npx clearotron install  # offers to install the reasoning program if the machine has none, and shows you how to sign it in
-  ```
+- **macOS, Linux or Windows.** On Windows everything runs natively in PowerShell, with no WSL2, no Git
+  and no administrator rights: `npm install --global clearotron`, then `clearotron install`, which installs
+  the AI program you choose into your own user folder. On Windows and macOS Clearotron runs in the window
+  you start it from, and closing the window stops it.
 
   Run from `npx`, the install first installs Clearotron under `~/.local`, as `npm install -g --prefix
   ~/.local` would, and finishes from there. That way the `clearotron` command and your assistant's connection
@@ -163,20 +150,6 @@ with `sudo`; install under your home instead: `npm install -g clearotron --prefi
 **Upgrade production to stables only.** What each channel promises and how often one is cut:
 **[docs/RELEASES.md](docs/RELEASES.md)**.
 
-**Upgrading an install made before 0.2.2: pin the agent id first.** The default agent id changed from
-`clawdi` to `localagent`, and that id is part of a path — your runs live under
-`<workspaceRoot>/workspace-<agent>/studio/clearance-search/`. If you never set an agent id, the upgraded
-install reads a workspace that does not exist yet, and an empty workspace looks like an account with no
-runs rather than like a misconfiguration. Set **both** names in your environment file before starting
-it, because the register-search servers read their own:
-
-```
-CLEAROTRON_DEFAULT_AGENT=clawdi
-CLEAROTRON_GATHER_AGENT=clawdi
-```
-
-If your environment file already sets them, nothing changes. A first-time install needs neither.
-
 The rest of this section is about the two ways a package reaches you, which is a separate question from
 which version it is.
 

package/README.md

@@ -42,14 +42,14 @@ exits, and keeps the folder the same way.
 npx clearotron install
 ```
 
-Node 22.13 or newer, on macOS or Linux. It needs no root: it puts the program under `~/.local`, with the
+Node 22.13 or newer, on macOS, Linux or Windows. It needs no root: it puts the program under `~/.local`, with the
 `clearotron` command in `~/.local/bin`, then asks one question at a time and checks each credential
 before it saves it. Every command below uses the `clearotron` it installed — the same channel you
 installed from — so if `~/.local/bin` is not on your `PATH` yet, type the full path,
-`~/.local/bin/clearotron`, instead. **On Windows the demo above runs natively; a
-real clearance needs WSL2.** Native Windows clearances are planned for a later release. Until then the
-engine does not run on native Windows: it spawns each stage with POSIX path and process semantics, so
-a clearance is refused there before it starts.
+`~/.local/bin/clearotron`, instead. **On Windows it runs natively, from PowerShell: no WSL2, no Git and
+no administrator rights.** Install it with `npm install --global clearotron`, then run `clearotron install`.
+It runs in the window you start it from, as on a Mac: closing the window stops a search, and the next
+`clearotron start` picks it up again.
 
 Installing with npm's own global form instead is covered in [INSTALL.md](INSTALL.md) §2.
 

package/THIRD-PARTY-NOTICES.md

@@ -110,7 +110,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @modelcontextprotocol/sdk@1.30.0
+## @modelcontextprotocol/sdk@1.30.1
 
 - **Licence declared:** `MIT`
 - **Repository:** https://github.com/modelcontextprotocol/typescript-sdk
@@ -566,7 +566,7 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
-## brace-expansion@1.1.18
+## brace-expansion@1.1.21
 
 - **Licence declared:** `MIT`
 - **Repository:** git://github.com/juliangruber/brace-expansion
@@ -596,7 +596,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## brace-expansion@2.1.4
+## brace-expansion@2.1.7
 
 - **Licence declared:** `MIT`
 - **Repository:** git://github.com/juliangruber/brace-expansion
@@ -1968,7 +1968,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## fast-uri@3.1.7
+## fast-uri@3.1.8
 
 - **Licence declared:** `BSD-3-Clause`
 - **Repository:** https://github.com/fastify/fast-uri
@@ -2626,7 +2626,7 @@ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 PERFORMANCE OF THIS SOFTWARE.
 ```
 
-## ip-address@10.5.0
+## ip-address@10.7.2
 
 - **Licence declared:** `MIT`
 - **Repository:** https://github.com/beaugunderson/ip-address

package/bin/brandowner.mjs

@@ -112,7 +112,7 @@ const USAGE = `
     --name       the brand owner's legal name (required)
     --domains    comma-separated email domains that resolve to this owner
     --platforms  comma-separated marketplaces their searches cover
-                 omitted ⇒ the Generic default's platforms are applied and named in the output
+                 omitted ⇒ none — searches use the general web, plus any stores chosen for each matter
     --framework  their risk framework, as skills/clearance-search/<file>.md
                  omitted ⇒ the Generic default is applied and named in the output
     --industry   free text, shown on their profile

package/bin/onboard.mjs

@@ -103,6 +103,8 @@ import { resolveAuthMode, CLOUD_SWITCH, CLOUD_SETTINGS, CLOUD_SECRETS, cloudsSwi
 import { isInsideCheckout } from "../shared/inside-checkout.mjs";   // — one copy of the rule, and it is testable
 import { packagedBuild as sharedPackagedBuild } from "../shared/packaged-build.mjs";   // — one reader of build-info.json, reachable from the driver
 import { processTable } from "../shared/process-table.mjs";   // — /proc is not the only box
+import { hasSep } from "../shared/path-seps.mjs";   // a Windows path is written with "\"
+import { npmInvocation } from "../shared/npm-cli.mjs";   // npm without a shell, which Windows needs
 import { programsFromAnotherCheckout } from "../shared/checkout-move.mjs";
 import { entrypointOf } from "../driver/systemd/install-census.mjs";         // one ExecStart parser
 import { overlayReport, renderOverlayReport } from "../shared/doctrine-overlay.mjs";   // — the doctor reports the overlay
@@ -790,7 +792,8 @@ export async function askSignIn(io, { localAccount = "user", existing = null } =
  * Was `resolveClaudeBin`. The body never had anything claude-specific in it; the NAME was the last place
  * this file still assumed one engine, and a name that lies is how the second adapter stayed invisible.
  */
-export function resolveEngineBin(bin, { env = process.env, wsl = null, onWindowsDrive = null, engine = null, enginesDir = undefined } = {}) {
+export function resolveEngineBin(bin, { env = process.env, wsl = null, onWindowsDrive = null, engine = null, enginesDir = undefined,
+  platform = process.platform } = {}) {
   // A VIEW OVER THE DRIVER'S ONE RESOLVER (driver.config.mjs resolveEngineProgram), which every other
   // reader asks too: the run door, the inventory the portal reads, and both adapters. This used to be a
   // second PATH walk of its own, and it was the only one that knew to pass over a Windows copy under WSL;
@@ -803,14 +806,14 @@ export function resolveEngineBin(bin, { env = process.env, wsl = null, onWindows
   // Linux runner without root, so an arm that could only supply a PATH could never drive the skip.
   const id = engine ?? Object.keys(ENGINE_BINARIES).find((k) => ENGINE_BINARIES[k].fallback === bin) ?? DEFAULT_ENGINE_ID;
   const spec = ENGINE_BINARIES[id];
-  const r = resolveEngineProgram(id, { env: { ...env, [spec.env]: bin }, wsl, onWindowsDrive, enginesDir });
+  const r = resolveEngineProgram(id, { env: { ...env, [spec.env]: bin }, wsl, onWindowsDrive, enginesDir, platform });
   const found = { source: r.source, version: r.version, rejected: r.rejected, skipped: r.skipped, windowsShim: r.windowsShim };
   // A RELATIVE path is the trap for both adapters: stage subprocesses run with cwd set to the RUN
   // DIRECTORY (driver/engine/common.mjs resolveSpawnCwd), so it resolves against a directory that did not
   // exist at setup time. Reported with its absolute form from here, which is what the wizard then uses.
   if (r.relative) { const abs = resolve(bin); return { path: abs, executable: isExec(abs), relative: true, ...found }; }
   // A PATH SOMEBODY TYPED IS NOT OVERRULED, only reported: the resolver never falls through from it.
-  if (!r.resolved && r.explicit && bin.includes("/")) return { path: resolve(bin), executable: false, relative: false, ...found };
+  if (!r.resolved && r.explicit && hasSep(bin, platform)) return { path: resolve(bin), executable: false, relative: false, ...found };
   return { path: r.resolved, executable: Boolean(r.resolved), relative: false, ...found };
 }
 
@@ -927,30 +930,11 @@ export function windowsShimNote(skipped, bin) {
 const isExec = (p) => { try { accessSync(p, constants.X_OK); return statSync(p).isFile(); } catch { return false; } };
 
 /**
- * What doctor says about the engine on a platform the run door refuses outright, or `null` where the
- * ordinary binary checks apply.
+ * How to leave demo mode. The first line is the same everywhere; the second differs by whether the
+ * machine has a background form. Windows has none, so there it names closing the window and starting
+ * again, where elsewhere it names restarting the services and the file background services read.
  *
- * `platform` IS INJECTABLE, and for the reason `preflightEngineBinary` gives at its own refusal: the
- * population this protects is the one that cannot run this suite to find out. An arm on a Linux runner
- * has to be able to ask what a Windows reader is shown, or the Windows text is asserted by nobody —
- * and reading `process.platform` inside the caller would make that arm read source instead of driving
- * the answer.
- */
-export function platformEngineRefusal({ platform = process.platform } = {}) {
-  if (platform !== "win32") return null;
-  return "this engine does not run on native Windows — stage subprocesses are spawned with POSIX path "
-    + "and process semantics, so the run door refuses before it reads PATH. Run it under WSL2, or in "
-    + "the devcontainer. The demo works here as it is: it replays finished reports and needs no engine.";
-}
-
-/**
- * How to leave demo mode, which is not the same instruction everywhere.
- *
- * On the platform the run door refuses, the standard advice is a loop: install a CLI the reader may
- * already have, then restart a service — neither of which can change the answer, because the refusal
- * is about the platform rather than the program. Naming WSL2 is the only instruction that ends it.
- *
- * ELSEWHERE IT NAMES SETUP, WHICH DOES THE WORK NOW. This used to say to install the CLI by hand with
+ * IT NAMES SETUP, WHICH DOES THE WORK NOW. This used to say to install the CLI by hand with
  * `npm install -g`, then run `claude` to sign in, and to restart the engine service so it re-read its PATH.
  * Setup offers to install the program itself, into a folder that is not on PATH, so the bare `claude` it
  * named was a command the reader's shell does not have; and a run finds that copy without re-reading PATH.
@@ -961,16 +945,16 @@ export function platformEngineRefusal({ platform = process.platform } = {}) {
  */
 export function leaveDemoAdvice(engSpec, { platform = process.platform, command = reachableCommand("install"),
   startCommand = reachableCommand("start") } = {}) {
+  const first = `To leave demo: run \`${command}\`. It offers to install ${engSpec.vendor}'s CLI if this machine has none, `
+    + "asks how it is paid for, and proves it with one turn; if the CLI is not signed in, it names the command that signs it in.";
+  // WINDOWS HAS NO BACKGROUND FORM, so the second line there names the one restart it has: the window.
   if (platform === "win32") {
-    return [`To leave demo on Windows: run the product under WSL2, or in the devcontainer. Installing `
-      + `${engSpec.vendor}'s CLI natively will not change this — the run door refuses on the platform, `
-      + "not on the program."];
+    return [first, "If Clearotron is already running, close its window and start it again: it reads the settings setup writes when it starts."];
   }
   // BACKGROUND SERVICES ARE THE EXCEPTION to "restart them": they read `~/.env`, which setup does not write,
   // and `start --background` only adds lines to it (see programDisagreement below, which says the same).
   return [
-    `To leave demo: run \`${command}\`. It offers to install ${engSpec.vendor}'s CLI if this machine has none, `
-      + "asks how it is paid for, and proves it with one turn; if the CLI is not signed in, it names the command that signs it in.",
+    first,
     "If Clearotron's services are already running, restart them afterwards: they read the settings setup writes "
       + "when they start, and the portal reports what the engine saw when it last started. Background services "
       + `read \`~/.env\` instead, which setup does not write, and \`${startCommand} --background\` adds to it only the `
@@ -1813,27 +1797,6 @@ export async function runCheck() {
     const seen = versionOf(bin);
     const copyWords = (b) => `${b.source === "installed" ? "the copy Clearotron installed"
       : b.source === "explicit" ? `set in ${engSpec.env}` : "on PATH"}${seen ? `, version ${seen}` : ", version not read"}`;
-    // ── NATIVE WINDOWS IS ANSWERED HERE, BEFORE ANY PATH IS RESOLVED OR REPORTED ──────────────────
-    //
-    // `resolveEngineBin` tests a candidate with `accessSync(X_OK)` and `isFile()`. Windows has no
-    // execute bit, so X_OK is satisfied by any file that exists — and an npm global install writes
-    // BOTH `claude`, an extensionless shell script for Git Bash, and `claude.cmd`. The POSIX test
-    // passes on the shell script, so this line reported the engine FOUND at a path CreateProcess
-    // cannot start, and the probe then failed with `spawn claude ENOENT`. Reported from a real
-    // Windows run, 2026-09-09.
-    //
-    // RESOLVING `claude.cmd` INSTEAD WOULD MOVE THE CONTRADICTION, NOT REMOVE IT.
-    // `preflightEngineBinary` refuses native Windows by name, and the run door calls it
-    // unconditionally — so a clearance cannot run here whatever this line finds. Making the probe
-    // succeed would produce a doctor that says ready, a probe that passes, and a run that refuses
-    // anyway: the same disagreement one step later, and more convincing for having spawned something.
-    //
-    // So doctor says what the run door says. That is the property — the two agree — and the reader
-    // gets one refusal they can act on instead of a found-then-failed sequence that sends them
-    // looking for a PATH problem they do not have. The demo is unaffected: it replays finished runs
-    // and needs no engine, which is why four reports published on that same Windows box.
-    const platformRefusal = platformEngineRefusal();
-    if (platformRefusal) problem(platformRefusal);
     // ── AND WHETHER THAT COPY IS NEW ENOUGH FOR THE MODELS IT WILL BE ASKED FOR ──────────────────
     //
     // The floor governed the copy setup INSTALLS and nothing else, and a copy already on the machine
@@ -1845,7 +1808,7 @@ export async function runCheck() {
     // compared. The last is said rather than passed over — doctor's own contract is that a failure to
     // look is not a clean result — and it is the ordinary state for a copy the machine installed by
     // another route, where there is no package.json to read and doctor spawns nothing to ask.
-    else if (bin.executable && !bin.relative && olderThanFloor(seen, engSpec.floor) === true)
+    if (bin.executable && !bin.relative && olderThanFloor(seen, engSpec.floor) === true)
       problem(`${bin.path} — ${copyWords(bin)}. Clearotron needs ${engSpec.floor} or newer. ${belowFloorTail(engSpec, bin)}`);
     else if (bin.executable && !bin.relative) {
       ok(`${bin.path} — ${copyWords(bin)}`);
@@ -3872,26 +3835,6 @@ try {
     if (!pick.id) { sayNoEngine(); break; }
     const eng = ENGINE_BINARIES[pick.id];
 
-    // ── NATIVE WINDOWS IS ANSWERED HERE TOO, AND THE ESCAPE IS OFFERED RATHER THAN LEFT ON A MENU ──
-    //
-    // Doctor learned this and the wizard did not, and the gap is worse than it sounds: the two "no
-    // engine" escapes below both sit behind "no usable binary", and on Windows that is FALSE. X_OK is
-    // satisfied by any file that exists, so the wizard says "found C:\...\claude", walks past both
-    // escapes, asks which lane pays, spends a proof turn, and meets `spawn claude ENOENT`. The only
-    // prompt left then defaults to No and returns to the engine menu — with nothing changed between
-    // iterations, on either lane. Reported from a real Windows run: the menu's last row was the one
-    // way out and nothing on screen said so.
-    //
-    // So the refusal is stated before a candidate is resolved, and finishing with no engine is OFFERED
-    // rather than being a row the reader has to notice. Declining leaves them on the menu exactly as
-    // before, which is the branch that was already there.
-    const wizardRefusal = platformEngineRefusal();
-    if (wizardRefusal) {
-      problem(wizardRefusal);
-      if (await confirm("Finish setup with no engine configured?", true)) { sayNoEngine(); break engine; }
-      continue;
-    }
-
     let bin = resolveEngineBin(process.env[eng.env] || eng.fallback, { engine: pick.id });
     // Under WSL the Windows build on the appended PATH has been passed over. Said before the install
     // offer below, because otherwise a reader whose Linux install is genuinely missing is asked to
@@ -3929,7 +3872,8 @@ try {
       say("");
       if (await confirm(`Run \`${engineInstallCommand(eng, dir)}\` now?`, false)) {
         say(`  $ ${engineInstallCommand(eng, dir)}`);
-        const r = spawnSync("npm", engineInstallArgs(eng, dir), { stdio: "inherit" });
+        const npm = npmInvocation(engineInstallArgs(eng, dir));
+        const r = spawnSync(npm.command, npm.args, { stdio: "inherit" });
         // THE EXIT CODE IS NOT THE ANSWER, and this is the issue's own rule. An install that exits 0 may
         // have left the vendor's placeholder (npm told to skip install scripts), and one that exits
         // non-zero may still have left a usable program. So what decides is the same resolution the

package/bin/start.mjs

@@ -87,6 +87,7 @@ import { writeSecretFile } from "../shared/secret-file.mjs";   // one atomic wri
 import { runRequiredNames, missingRequirements, CLOUD_ROUTES } from "../driver/run-requirements.mjs";
 import { CLOUD_SWITCH, cloudsSwitchedOn } from "../driver/engine/auth.mjs";   // a switch compared the way the program reads it: on or off
 import { ENGINE_BINARIES, DEFAULT_ENGINE_ID as RUN_DEFAULT_ENGINE, resolveEngineProgram } from "../driver/driver.config.mjs";
+import { spawnsDetached, killWindowsTreesNow } from "../driver/engine/engine-spawn.mjs";   // Windows has no process group to stop
 import { unitEnvironment, unitValue } from "../driver/unit-environment.mjs";   // the PATH the worker unit will run with, read the way doctor reads it
 
 /**
@@ -149,7 +150,7 @@ import { addressRefusal } from "../shared/staff-domain.mjs";
 // entry is written through them, so this command cannot produce a shape of its own.
 import { withPerson, withOrganisation, withCompany } from "../shared/grants-edit.mjs";
 import { assertGrantsShape, resolvePerson } from "../shared/scope.mjs";
-import { backgroundManager } from "../shared/os-advice.mjs";
+import { backgroundManager, backgroundRefusal } from "../shared/os-advice.mjs";
 import { recordRunning } from "../shared/running-start.mjs";
 import { frontingVariablesSet } from "../shared/install-auth.mjs";   // — one owner for what counts as a proxy in front of a door
 
@@ -713,6 +714,26 @@ export const BACKGROUND_EXCLUDED = Object.freeze({
   "profile-service.service": "the portal constructs the profile service IN-PROCESS (driver/portal-service.mjs); the standalone unit is the separate-editor deployment shape and running both double-serves the store",
 });
 
+/**
+ * The key that signs every access token, and the one it replaces while a rotation is under way. Only the
+ * processes that mint or check keys hold them: the portal and the two doors. The worker holds neither,
+ * because it starts the AI program for every stage.
+ */
+export const SIGNING_KEY_NAMES = Object.freeze(["TRADEMARK_MCP_TOKEN_SECRET", "TRADEMARK_MCP_TOKEN_SECRET_PREVIOUS"]);
+
+/**
+ * A child's environment: this supervisor's, then the child's own block over it. The signing keys are the
+ * exception: a child whose own block does not carry the current key gets neither of them. This process
+ * sets the key on itself to mint the portal's key, so without the exception every child would inherit it,
+ * whatever its block said. A child that is handed the key keeps the previous one too, from this process,
+ * so a rotation under way still checks the keys signed before it.
+ */
+export function childProcessEnv(parent = process.env, own = {}) {
+  const env = { ...parent, ...own };
+  if (!Object.hasOwn(own, SIGNING_KEY_NAMES[0])) for (const k of SIGNING_KEY_NAMES) delete env[k];
+  return env;
+}
+
 export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsToken, host = HOST, localWorker = false, demo = false, clientFence = null, credential = null, env = process.env }) {
   // ONE AUTHOR FOR THIS EXPRESSION. The hosted install path composes the same
   // origin, and the near-miss is specific: this is an ORIGIN, the portal's client appends `/mcp`
@@ -811,8 +832,10 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       CLIENT_MCP_HTTP_PORT: String(ports.client),
     },
     // The worker needs the install's PATHS and nothing else — no ports, no secrets, no door config. It
-    // talks to the queue and the pool, not to either listener.
-    worker: { ...shared },
+    // talks to the queue and the pool, not to either listener. `shared` carries the signing key for the two
+    // doors and the portal, which mint and check keys; the worker does neither, and it starts the AI program
+    // for every stage, so the key is taken out here and withheld again at the spawn (childProcessEnv).
+    worker: Object.fromEntries(Object.entries(shared).filter(([k]) => !SIGNING_KEY_NAMES.includes(k))),
     // ── THE CLIENT DOOR, ON BOTH PATHS ( — F26) ──────────────────────────────
     //
     // Ruling, restated several times in session: START BOTH. It already held on the systemd path
@@ -976,6 +999,9 @@ if (isMain) {
   // exactly how to drain when they do.
   const wantWorker = !argv.includes("--no-worker");
   const wantBackground = argv.includes("--background");
+  // ON WINDOWS THERE IS NO BACKGROUND FORM: it is systemd units. Answered here, before anything is written
+  // or systemctl is called, in the owner's sentence and nothing else, so no `start:` prefix either.
+  if (wantBackground && backgroundRefusal()) { err(backgroundRefusal()); process.exit(1); }
 
   // A flag with its value forgotten is a MISTAKE, not a request for the default. `--base` swallowing the
   // next flag, or falling through to ~/trademark, would put an install somewhere nobody asked for.
@@ -2187,8 +2213,9 @@ if (isMain) {
       cwd: REPO,
       // Its OWN process group, so Ctrl-C reaches this supervisor alone and teardown is one ordered
       // sequence rather than a race between the terminal's signal and ours. It also means the group
-      // kill below reaches anything a child spawns, not just the child.
-      detached: true,
+      // kill below reaches anything a child spawns, not just the child. NOT ON WINDOWS, where a detached
+      // child has no console and outlives the window it was started from (engine/engine-spawn.mjs).
+      detached: spawnsDetached(),
       // — STDERR IS TEED RATHER THAN INHERITED, AND ONLY STDERR.
       //
       // These children announce a refusal as one FATAL line on stderr and exit 1. With `inherit` the
@@ -2202,7 +2229,7 @@ if (isMain) {
       // progress rendering intact. Piping a stream costs the child its TTY, so only the stream that has to
       // be read is piped.
       stdio: ["ignore", "inherit", "pipe"],
-      env: { ...process.env, ...env },
+      env: childProcessEnv(process.env, env),
     });
     // The last lines of that child's stderr, forwarded on as they arrive so nothing is delayed or
     // swallowed, and kept so the failure can QUOTE them rather than refer to them.
@@ -2252,7 +2279,6 @@ if (isMain) {
     return rec;
   };
 
-  const signalGroup = (rec, sig) => { try { process.kill(-rec.child.pid, sig); } catch { /* already gone */ } };
 
   async function shutdown(code) {
     if (stopping) return;
@@ -2260,15 +2286,14 @@ if (isMain) {
     const live = children.filter((c) => c.alive);
     if (live.length) {
       say(`\n  stopping ${live.map((c) => c.name).join(" and ")}…`);
-      for (const c of live) signalGroup(c, "SIGTERM");
+      stopChildren(live.map((c) => c.child), "SIGTERM");
       // A grace window, then the hammer. Nothing this command starts holds unflushed client state, so
       // the window is short; it exists so a service gets to close its listener and log its own line.
       const deadline = Date.now() + 5000;
       while (children.some((c) => c.alive) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 100));
-      for (const c of children.filter((x) => x.alive)) {
-        err(`  ${c.name} did not stop on SIGTERM — killing it.`);
-        signalGroup(c, "SIGKILL");
-      }
+      const stuck = children.filter((x) => x.alive);
+      for (const c of stuck) err(`  ${c.name} did not stop on SIGTERM — killing it.`);
+      stopChildren(stuck.map((c) => c.child), "SIGKILL");
       await new Promise((r) => setTimeout(r, 200));
     }
     // ── THE DEMO TAKES ITS FOLDER WITH IT ───────────────────────────────────────────────────────────
@@ -2589,8 +2614,7 @@ if (isMain) {
   // `--background` installs and enables service units. There are none on Windows, so both the offer
   // and the sentence naming what manages them were wrong there — a reader was told to run a flag that
   // cannot succeed and given a service manager that is not on the machine and cannot be put there.
-  // Reported from a real run. Same rule as the engine refusal above: do not name a route this platform
-  // does not have.
+  // Reported from a real run. The rule: do not name a route this platform does not have.
   for (const line of backgroundOfferLines({ demo: DEMO, keep: DEMO_KEEP || READER_BASE, manager: backgroundManager(), start: invoke("start") })) say(line);
   say("");
 }
@@ -2693,6 +2717,26 @@ export function windowCloseSignals() {
   return ["SIGHUP"];
 }
 
+/**
+ * Stop children of this command, and whatever they started.
+ *
+ * On Linux and macOS each child leads its own process group, so the signal goes to the group, and to the
+ * child alone when the group is already gone. Windows has neither groups nor signals a Node child can
+ * catch, so there every child's process tree is ended at once, from one process listing: closing the
+ * window leaves only seconds, and a listing takes most of one. The second call finds nothing left.
+ * `platform` and the two effects are parameters so both branches run on a Linux CI.
+ */
+export function stopChildren(children, sig, { platform = process.platform, kill = (pid, s) => process.kill(pid, s),
+  endTrees = killWindowsTreesNow } = {}) {
+  const live = (children ?? []).filter((c) => c?.pid);
+  if (platform === "win32") {
+    const pids = live.filter((c) => c.exitCode === null && c.signalCode === null).map((c) => c.pid);
+    if (pids.length) endTrees(pids);
+    return;
+  }
+  for (const c of live) { try { kill(-c.pid, sig); } catch { try { c.kill(sig); } catch { /* already gone */ } } }
+}
+
 /**
  * What a reader is told when a child this install cannot run without exits.
  *

package/bin/update.mjs

@@ -53,6 +53,7 @@ import { fileURLToPath } from "node:url";
 
 import { config, ENGINE_BINARIES, enginesFolder, engineInstallArgs } from "../driver/driver.config.mjs";
 import { isInsideCheckout } from "../shared/inside-checkout.mjs";   // — one copy of the rule
+import { npmInvocation } from "../shared/npm-cli.mjs";   // npm without a shell, which Windows needs
 import { overlayReport, renderOverlayReport, treeFiles } from "../shared/doctrine-overlay.mjs";
 import { liveRunHolds } from "../driver/deploy-live-run-guard.mjs";   // — one live-run test, shared with deploy-preflight
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -210,7 +211,9 @@ function refreshEngines(engines, dir = enginesFolder()) {
 
 function runInCheckout(cmd, args) {
   say(`\n  $ ${cmd} ${args.join(" ")}`);
-  const r = spawnSync(cmd, args, { cwd: REPO, stdio: "inherit" });
+  // npm is a batch file on Windows, which Node will not start without a shell (shared/npm-cli.mjs).
+  const run = cmd === "npm" ? npmInvocation(args) : { command: cmd, args };
+  const r = spawnSync(run.command, run.args, { cwd: REPO, stdio: "inherit" });
   if (r.error) { console.error(`  could not run ${cmd}: ${r.error.message}`); return 70; }
   if (r.signal) { console.error(`  ${cmd} was killed by ${r.signal}`); return 70; }
   return r.status ?? 0;

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "e60329390d653439053b900cf97b65e082e06622",
-  "version": "0.4.0-beta.1"
+  "commit": "c8159f8575f90587b1c78d5151d9acf9235977e1",
+  "version": "0.4.0-beta.3"
 }

package/demo/full-country-search/run/_driver/search-policy.json

@@ -17,7 +17,7 @@
   "recipeScope": null,
   "deliveryRoute": null,
   "enqueuedVia": "mcp/start_run",
-  "enqueuedBy": "e2e-capella",
+  "enqueuedBy": "demo",
   "parentRunId": null,
   "frozenAt": "2026-09-18T15:08:47.364Z"
 }

package/demo/full-country-search/run/status.json

@@ -5,7 +5,7 @@
   "slug": "tmpdemo2014fullcountrysearch-venqori",
   "codename": "sample-capture",
   "date": "2026-09-18",
-  "agent": "clawdi",
+  "agent": "localagent",
   "forwarder": "e2e",
   "ref": "DEMO-2014-full-country-search",
   "markName": "VENQORI",

package/demo/global-preliminary-search/run/_driver/search-policy.json

@@ -17,7 +17,7 @@
   "recipeScope": null,
   "deliveryRoute": null,
   "enqueuedVia": "mcp/start_run",
-  "enqueuedBy": "e2e-capella",
+  "enqueuedBy": "demo",
   "parentRunId": null,
   "frozenAt": "2026-09-18T12:35:08.518Z"
 }

package/demo/global-preliminary-search/run/status.json

@@ -5,7 +5,7 @@
   "slug": "tmpdemo2014globalpreliminarysearch-venqori",
   "codename": "sample-capture",
   "date": "2026-09-18",
-  "agent": "clawdi",
+  "agent": "localagent",
   "forwarder": "e2e",
   "ref": "DEMO-2014-global-preliminary-search",
   "markName": "VENQORI",

package/demo/knockout-search/run/_driver/search-policy.json

@@ -17,7 +17,7 @@
   "recipeScope": null,
   "deliveryRoute": null,
   "enqueuedVia": "mcp/start_run",
-  "enqueuedBy": "e2e-capella",
+  "enqueuedBy": "demo",
   "parentRunId": null,
   "frozenAt": "2026-09-18T16:18:15.945Z"
 }

package/demo/knockout-search/run/status.json

@@ -5,7 +5,7 @@
   "slug": "tmpdemo2014knockoutsearch-venqori",
   "codename": "sample-capture",
   "date": "2026-09-18",
-  "agent": "clawdi",
+  "agent": "localagent",
   "forwarder": "e2e",
   "ref": "DEMO-2014-knockout-search",
   "state": "delivered",

package/demo/multi-country-focus-search/run/_driver/search-policy.json

@@ -17,7 +17,7 @@
   "recipeScope": null,
   "deliveryRoute": null,
   "enqueuedVia": "mcp/start_run",
-  "enqueuedBy": "e2e-capella",
+  "enqueuedBy": "demo",
   "parentRunId": null,
   "frozenAt": "2026-09-18T14:03:02.805Z"
 }

package/demo/multi-country-focus-search/run/status.json

@@ -5,7 +5,7 @@
   "slug": "tmpdemo2014multicountryfocussearch-venqori",
   "codename": "sample-capture",
   "date": "2026-09-18",
-  "agent": "clawdi",
+  "agent": "localagent",
   "forwarder": "e2e",
   "ref": "DEMO-2014-multi-country-focus-search",
   "markName": "VENQORI",

package/docs/README.md

@@ -40,6 +40,7 @@ the vendor flags approximate is UNKNOWN, never a number.
 | [`E2E.md`](E2E.md) | Proving a deployment works end to end |
 | [`GLOSSARY.md`](GLOSSARY.md) | The words this codebase uses in a particular way — one line each, for a contributor meeting them for the first time |
 | [`SECURITY.md`](SECURITY.md) | The security envelope — what protects what, and where it is enforced in code. To report a vulnerability, use [`../SECURITY.md`](../SECURITY.md) |
+| [`SECURITY-OWASP.md`](SECURITY-OWASP.md) | Each risk on OWASP's two lists for AI systems, what Clearotron does about it, and the file on `main` where that lives |
 
 Access control is stated once, in [`SECURITY.md`](SECURITY.md): who may see which runs, what an unset
 guest list means on each face, and which door proves identity. Issuing and rotating grants and ops