clearotron 0.3.1-beta.0 → 0.3.1-beta.2

package/.env.example

@@ -480,6 +480,23 @@ CLEAROTRON_CUT_REF=
 # effect: tuning
 CLEAROTRON_RELEASE_WAIT_MS=
 
+# The trickle floor: the fewest output tokens per second of ACTIVE time (elapsed minus tool wait) a
+# model turn may produce before it is stopped as a stall. Unset uses 1. A stage streaming a token every
+# few seconds holds off both other clocks — the stall clock resets on any byte, and the no-progress
+# ceiling counts token movement as progress deliberately — so before this the only thing that stopped
+# one was its wall, which throws the whole attempt away. Set 0 to disable the floor; that is read as "no
+# floor", never as a floor of zero. A negative or unreadable value falls back to the default rather than
+# switching the instrument off. Read by driver/engine/anthropic-agent.mjs.
+# effect: tuning
+CLEAROTRON_MIN_TOKENS_PER_SEC=
+
+# How much ACTIVE time a turn gets before the floor above may fire at all, in whole milliseconds. Unset
+# uses 300000 (five minutes). It exists because a rate measured over a few seconds is noise, and a turn
+# that thinks before it writes would fail an immediate floor while working perfectly. A non-positive or
+# unreadable value falls back to the default. Read by driver/engine/anthropic-agent.mjs.
+# effect: tuning
+CLEAROTRON_MIN_TOKENS_WARMUP_MS=
+
 # ── The local key door's socket ───────────────────────────────
 # Same shape as the two below: read by product code, in neither this file nor the governance table
 # until a private environment-contract ratchet caught it.

package/INSTALL.md

@@ -1326,7 +1326,7 @@ answer on any of them:
   by that vendor's terms. AGPL-3.0 grants you nothing over it, and this repository redistributes no
   part of it.
 - **Register and research providers are your own agreements.** EUIPO, the USPTO bulk product,
-  `PERPLEXITY_API_KEY`, CourtListener, and the subscription registers (Corsearch, Clarivate, Signa)
+  `PERPLEXITY_API_KEY`, CourtListener, and the subscription registers (Clarivate, Signa, Corsearch)
   each sit on terms you accept directly with that provider. The adapters in `providers/` are ours and
   are licensed with the rest of the code; what they connect to is not.
 - **npm dependencies carry their own licences.** `package-lock.json` is the resolved set, and each

package/README.md

@@ -29,6 +29,11 @@ That fetches the published package — it will ask once before downloading — t
 clearances into a local portal and prints the portal's address and the passphrase to sign in with. Open
 the address in your browser. No account, no credentials, no network calls to us.
 
+The demo runs for as long as that window stays open, and removes everything it made when you close it —
+nothing of it is left on the machine, and running it again later starts clean. If you want to keep the
+sample reports after closing the window, run `npx clearotron demo --keep`; it prints the one command
+that removes the folder when you are done with it.
+
 **Then install it.**
 
 ```bash
@@ -102,7 +107,7 @@ clearotron run --job my-job.json
 ## How it fits together
 
 - **A reasoning CLI does the thinking.** Every stage runs as a headless turn of the [Claude CLI](https://claude.com/claude-code) (`claude`) or the Codex CLI (`codex`), which must be installed. `CLEAROTRON_AI_BILLING` chooses what pays for the turn: your signed-in subscription, or an API key. Either way the CLI is what runs — there is no path that calls the model directly.
-- **One register credential sets coverage and cost.** `CLEAROTRON_DATABASE` has no default — a run refuses rather than picking a vendor for you. EUIPO and a local USPTO index cost nothing; Signa, Clarivate and Corsearch are subscriptions. [The six, and what each reaches](providers/README.md).
+- **One register credential sets coverage and cost.** `CLEAROTRON_DATABASE` has no default — a run refuses rather than picking a vendor for you. EUIPO and a local USPTO index cost nothing; Clarivate, Signa and Corsearch are subscriptions. [The six, and what each reaches](providers/README.md).
 - **One research key.** `PERPLEXITY_API_KEY` covers the open web and the marketplaces. A clearance refuses without it at the door, before a register stage has spent.
 - **A run takes hours, and survives interruption.** Every finished stage stays on disk; a resume re-runs only what is missing, and a run parked on a provider cap continues by itself.
 - **A finished run is queryable.** An MCP server lets Claude, ChatGPT or your editor read and question

package/THIRD-PARTY-NOTICES.md

@@ -5028,7 +5028,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
-## react@19.2.8
+## react@19.3.0
 
 - **Licence declared:** `MIT`
 - **Repository:** https://github.com/react/react
@@ -5058,7 +5058,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## react-dom@19.2.8
+## react-dom@19.3.0
 
 - **Licence declared:** `MIT`
 - **Repository:** https://github.com/react/react
@@ -5592,10 +5592,10 @@ SOFTWARE.
 - **Repository:** https://github.com/lddubeau/saxes
 - **Licence file:** none shipped
 
-## scheduler@0.27.0
+## scheduler@0.28.0
 
 - **Licence declared:** `MIT`
-- **Repository:** https://github.com/facebook/react
+- **Repository:** https://github.com/react/react
 - **Licence file:** `LICENSE`
 
 ```

package/bin/connect.mjs

@@ -47,7 +47,7 @@ import { execFileSync } from "node:child_process";
 import { createServer } from "node:net";
 import { CONNECT_CLIENTS, WHERE_FLAG, clientById, leadRouteFor, plainStep, whatItNeeds } from "../shared/connect-clients.mjs";
 import { stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";
-import { isWsl } from "../shared/wsl.mjs";
+import { isWsl, wslTarget } from "../shared/wsl.mjs";   // — and which distribution a row should start the server in
 import { defaultDenylistPath, clientDoorAddress, clientDoorPort, clientDoorState, enablePlan, applyEnablePlan, describeChange, recordConnectKey, CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { mintToken, tokenId, resolvePerson, loadGrants } from "../shared/scope.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
@@ -206,7 +206,7 @@ function deploymentHas(env = process.env) {
   return {
     // EVERY SHAPE, RESOLVED ONCE. A row picks its own; nothing here knows a client's name.
     stdioRoutes: Object.fromEntries(Object.keys(STDIO_SHAPES).map((shape) =>
-      [shape, stdioConnectFor(shape, { workDir: env.CLEAROTRON_WORK_DIR || null, reportsDir: env.CLEAROTRON_REPORTS_DIR || null })])),
+      [shape, stdioConnectFor(shape, { workDir: env.CLEAROTRON_WORK_DIR || null, reportsDir: env.CLEAROTRON_REPORTS_DIR || null, wsl: wslTarget({ env }) })])),
     wsl: isWsl({ env }),
     // WHERE THE DOOR BINDS — not an address handed to any assistant. It is the loopback address the
     // unit listens on, and `enablePlan` needs it to write the unit. It used to be passed to the

package/bin/onboard.mjs

@@ -66,6 +66,12 @@ import { homedir, userInfo } from "node:os";
 import { invocationPrefix, installRoute, reachableCommand } from "../shared/invocation.mjs";   // — one rule for how the reader invokes us
 import { nodeFloorVerdict } from "../shared/node-floor.mjs";   // — the floor is package.json engines, not a constant here
 import { invocationForm } from "../shared/invocation.mjs";   // — and WHY that form
+// One sentence about a page that is not ours, from the module that owns how a reader invokes us — NOT
+// from bin/start.mjs, which is where it used to live. A command importing a command closes a loop that
+// hangs at run time rather than failing at build: this file has a top-level await, so start.mjs asking
+// for it back mid-evaluation never resolves and the wizard installs nothing. The import-cycle guard
+// names that pair; the sentence now lives where both commands can read it.
+import { foreignPageHint } from "../shared/invocation.mjs";
 import { standFrom } from "../shared/invocation.mjs";   // is this tree one npm replaces?
 import { installShim } from "../shared/verb-shim.mjs";   // — the verb goes on PATH
 import { relocationPlan } from "../shared/permanent-install.mjs";   // — and the program out of npx's cache
@@ -118,6 +124,7 @@ import { usageBlock } from "../shared/usage-block.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
 import { parseEnvFile } from "../shared/env-file-merge.mjs";   // — ONE KEY=value reader, taken from a leaf: the unit renderer re-exports this same function, and it is a COMMAND, so importing it from here would put a command in this binary's graph
 import { unitEnvironment, unitValue, couldNotDetermine } from "../driver/unit-environment.mjs";   // — F34: claim about the UNITS only from the units' own environment
+import { DEPLOYMENT_BOXES } from "../shared/deployment-box.mjs";   // the allowlist, imported — never a second copy that drifts
 
 /**
  * A file's text, or null when it is not there or cannot be read.
@@ -1051,6 +1058,29 @@ export async function runCheck() {
   say("\n  Trademark clearance engine — configuration check\n");
   say(`  repo: ${REPO}`);
 
+  // ── ONE READING OF THE UNITS' ENVIRONMENT, FOR EVERY SECTION THAT CLAIMS ANYTHING ABOUT THEM ─────
+  //
+  // F34: two sections asserted facts about the units while reading the operator's shell, and both of
+  // their reported problems were false on a correctly-running install. Resolving this once is
+  // deliberate — a second reader would drift from this one exactly as the composer and the checker did
+  // in F41, and the drift is invisible because both sides keep passing their own arms.
+  //
+  // HOISTED TO THE TOP OF runCheck, from just above the Engine section, so that the FIRST section —
+  // Deployment — can name the box from the file the units load. A box line sourced from this command's
+  // own shell would be the defect it is there to catch: the shell and the units' file can disagree,
+  // and it is the units' value that decides what the running service thinks it is.
+  const fileEnv = readEnvFile(READ_ENV_PATH());
+  const unitDir = join(homedir(), ".config", "systemd", "user");
+  const { BACKGROUND_UNITS, startPaths } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
+  const hosted = BACKGROUND_UNITS.some((u) => existsSync(join(unitDir, u)));
+  const unitEnv = hosted
+    ? unitEnvironment({
+        units: BACKGROUND_UNITS.map((u) => ({ name: u, text: readIfPresent(join(unitDir, u)) })),
+        readEnvFile: readIfPresent,
+        // These are USER units under ~/.config/systemd/user, so systemd's %h is this home.
+        home: homedir() })
+    : null;
+
   // — CURRENT, not just configured. Printed before anything else because a stale deployment
   // makes every line below it a report about the wrong build.
   say("\n  Deployment");
@@ -1080,6 +1110,56 @@ export async function runCheck() {
     info("this does not fetch — the count is against the last fetch, not against the remote right now");
   }
 
+  // ── WHICH BOX THIS IS, NAMED OUT LOUD ───────────────────────────────────────────────────────────
+  //
+  // `CLEAROTRON_BOX` is how a deployment names itself; `shared/deployment-box.mjs` says it is never
+  // inferred from the account, the checkout or the port, because all three correlate with the answer
+  // and none of them IS the answer. But nothing here printed it, so an unset or misspelled value left
+  // doctor exiting 0 and ending "Nothing wrong with what is configured" — the one check that would
+  // catch a deployment lying about itself was the one check that did not report.
+  //
+  // FOUR STATES, NOT THREE. Set, unset and unrecognised are the three the requirement names. The
+  // fourth is a hosted box whose unit environment COULD NOT BE READ, and calling that "unset" would
+  // claim the file says nothing when it was never read — absence reported as a finding, in the section
+  // whose entire job is to make the box visible. `couldNotDetermine` already exists for exactly this
+  // and is what the token and URL checks below use.
+  //
+  // THE VALUE COMES FROM THE FILE THE UNITS LOAD, never from this command's shell, and the two can
+  // disagree: an operator with CLEAROTRON_BOX exported in their own environment would otherwise read
+  // their own shell back and call it the deployment's identity. The shell is reported only when it
+  // CONTRADICTS the file, because that disagreement is itself a finding.
+  //
+  // The allowlist is imported rather than re-typed. Two inline copies agree on the day they are
+  // written and drift afterwards, which is the reason that module exists at all.
+  const boxSource = hosted ? "the units' environment" : "your environment file";
+  const boxFileEnv = hosted ? (unitEnv?.known === true ? unitEnv.env : null) : fileEnv;
+  if (hosted && unitEnv?.known !== true) {
+    warn(couldNotDetermine("CLEAROTRON_BOX", unitEnv));
+  } else {
+    const raw = (boxFileEnv?.CLEAROTRON_BOX ?? "").trim();
+    if (!raw) {
+      // AN ABSENCE IS NOT A MISCONFIGURATION, and this command already separates the two — a machine
+      // nobody has configured yet has no box, legitimately, and `--check` on one exits 0 by contract.
+      // Reported at `!` so it is visible rather than silent, which is the whole requirement; raising it
+      // to `✗` made every unconfigured machine fail its own acceptance arm, and said "fault" about a
+      // state that is the normal beginning of an install.
+      warn(`no CLEAROTRON_BOX in ${boxSource} — this deployment does not name itself, so nothing below `
+        + `can be read as a statement about a particular box. Set it to one of: ${DEPLOYMENT_BOXES.join(", ")}`);
+    } else if (!DEPLOYMENT_BOXES.includes(raw)) {
+      problem(`CLEAROTRON_BOX is "${raw}" in ${boxSource}, which is not a box this build knows `
+        + `(${DEPLOYMENT_BOXES.join(", ")}). An unrecognised name reads as NO box everywhere it is `
+        + "consulted, which is quieter than a wrong one and just as wrong");
+    } else {
+      ok(`this box names itself "${raw}", from ${boxSource}`);
+      const shell = (process.env.CLEAROTRON_BOX ?? "").trim();
+      if (shell && shell !== raw) {
+        warn(`your shell says CLEAROTRON_BOX="${shell}", which disagrees with ${boxSource}. The running `
+          + "service goes by the file; your own commands go by the shell, so the two would report "
+          + "different boxes for the same machine");
+      }
+    }
+  }
+
   // ── THE TWO FILES MAY DISAGREE ABOUT THE DOOR ────────────────────────────────
   //
   // They are disjoint by design and are SUPPOSED to differ about paths, ports and secrets. What must
@@ -1163,7 +1243,10 @@ export async function runCheck() {
   // Read the file up here rather than at the `.env` heading below: the engine section is the first that
   // needs `effective()`, and which ENGINE is configured decides which binary variable to check. Reading
   // is not applying — see readEnvFile's header.
-  const fileEnv = readEnvFile(READ_ENV_PATH());
+  // `fileEnv` is read at the top of runCheck now — the Deployment section needs it to name the box on a
+  // box that runs no units, and a `const` used above its declaration is a dead-zone crash, not a
+  // fallback. It reached here as one on the first draft of that section: harmless on a hosted box,
+  // where the ternary never evaluates this branch, and fatal on every install without units.
   // Environment wins over the file (the loader contract), so report the effective value and say which
   // source it came from — a value read from the wrong place is the whole class of bug here.
   // ── CHECK 1 — THE CHECKER READS EVERY SPELLING THE ENGINE ACCEPTS ─────────────────────────
@@ -1210,16 +1293,9 @@ export async function runCheck() {
   // their reported problems were false on a correctly-running install. Resolving this once, here, is
   // deliberate — a second reader would drift from this one exactly as the composer and the checker did
   // in F41, and the drift is invisible because both sides keep passing their own arms.
-  const unitDir = join(homedir(), ".config", "systemd", "user");
-  const { BACKGROUND_UNITS, startPaths } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
-  const hosted = BACKGROUND_UNITS.some((u) => existsSync(join(unitDir, u)));
-  const unitEnv = hosted
-    ? unitEnvironment({
-        units: BACKGROUND_UNITS.map((u) => ({ name: u, text: readIfPresent(join(unitDir, u)) })),
-        readEnvFile: readIfPresent,
-        // These are USER units under ~/.config/systemd/user, so systemd's %h is this home.
-        home: homedir() })
-    : null;
+  // The reading itself was hoisted AGAIN, to the top of runCheck, so the Deployment section can name
+  // the box from the file the units load. `unitDir`, `hosted`, `unitEnv` and `startPaths` are all in
+  // scope from there; nothing between here and there consumed them, which is why the move is safe.
 
   // ── AND THE DOOR SECTION IS THE THIRD SUCH SECTION ──────────────────────────────────────────────
   //
@@ -3987,6 +4063,15 @@ try {
   say(`    ${invocationPrefix()}clearotron start\n`);
   say("      Starts the portal and the engine door and prints one address to open in your browser. That");
   say("      address is the product: you order a clearance from it and read the report there.\n");
+  // THE ONE SENTENCE A READER NEEDS BEFORE THEY OPEN THAT ADDRESS, and setup was the only one of the
+  // three commands that never said it. A port can be free where the product runs and taken where the
+  // BROWSER runs — a forwarding listener outside this environment answers 127.0.0.1 first — and the
+  // page that opens is then somebody else's, with nothing on screen saying so. It is printed here
+  // rather than beside an address because setup starts nothing and has no address to print: the reader
+  // meets it moments before the command that does. Composed by the same function `start` and `demo`
+  // use, with no number, so the three commands cannot drift into three answers.
+  for (const line of foreignPageHint("start")) say(`      ${line}`);
+  say("");
   say(`  ${style.dim(`Also: \`${invocationPrefix()}clearotron demo\` replays a finished report with no keys and no model calls;`)}`);
   say(`  ${style.dim(`\`${invocationPrefix()}clearotron run --job ${/\s/.test(EXAMPLE_JOB) ? `"${EXAMPLE_JOB}"` : EXAMPLE_JOB}\` runs a first real clearance on the EU register.`)}`);
   // THE OLD WAY IS A CHECKOUT'S. A package has no npm scripts where its reader stands.

package/bin/start.mjs

@@ -121,9 +121,13 @@ import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "
 import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort, demoTokenSecret, demoTokenSecretPath, keyIssueCommand } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
 import { createServer } from "node:net";
 import { listenErrorMessage, nextFreePort } from "../shared/listen.mjs";
-import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { invocationPrefix, invoke, reachableCommand } from "../shared/invocation.mjs";   // — the banner names the verb
+import { invocationPrefix, invoke, reachableCommand, foreignPageHint } from "../shared/invocation.mjs";   // — the banner names the verb
+// RE-EXPORTED, NOT RE-DECLARED. The sentence moved to a module that imports nothing of ours, because
+// setup imports it and setup has a top-level await: a command importing a command closes a loop that
+// hangs at run time rather than failing at build. Its readers keep this spelling.
+export { foreignPageHint };
 import { unitEnvPath, activeEnvPath } from "../shared/env-local.mjs";   // — the file the units read, named once
 import { parseEnvFile } from "../shared/env-file-merge.mjs";   // ONE KEY=value reader, in a leaf: render-units is a COMMAND, and importing it from here closed a cycle
 import { homedir, userInfo } from "node:os";
@@ -303,21 +307,6 @@ export function resolvePorts(env = {}) {
     client: one("CLIENT_MCP_HTTP_PORT", clientDoorPort({})) };
 }
 
-/**
- * WHAT TO DO WHEN THE PAGE THAT OPENS IS NOT OURS. Printed under every "Open" line.
- *
- * A port can be free where this runs and taken where the browser runs: on WSL, a Windows-side listener
- * (VS Code's Remote-SSH forwarding is the one measured, 2026-09-11) answers 127.0.0.1 before WSL does. The
- * doors bind cleanly, the in-use detection has nothing to see, and the browser shows somebody else's page
- * with nothing on this screen saying so. `--port` already moves all three doors; the reader has to be told
- * about it at the moment the address is handed over, which is here.
- */
-export function foreignPageHint(verb) {
-  return [
-    "If the page that opens is not this install's sign-in, another program on this machine holds that",
-    `port from outside this environment. Run \`${invoke(verb)} --port 28802\` (or any free number) instead.`,
-  ];
-}
 
 /**
  * Apply `--port <n>` to the three doors.
@@ -349,6 +338,37 @@ export function portsForFlag(portFlag, ports, env = {}) {
   };
 }
 
+/**
+ * THE DEMO'S OWN DOORS — the numbers it opens when the reader has asked for none.
+ *
+ * A demo used to start on the install's default portal port. On WSL that put the browser's address in
+ * the hands of whatever holds that number on the WINDOWS side: a Remote-SSH forward answered 127.0.0.1
+ * first, and the reader opened a production portal's "not signed in" page believing it was the demo.
+ * A local free-port walk cannot help there — the port IS free inside WSL, which is why the bind
+ * succeeded — so the fix is not to look harder but to stop using the number anybody else would.
+ *
+ * 18860 has no meaning: it is unusual, it is clear of the three an install opens by default (18802,
+ * 18790, 18811) and of the range a moved door walks into, and a stranger's machine is unlikely to be
+ * running something there. The two doors that follow take the next two numbers, which is the same
+ * arithmetic `--port` already uses, so a reader who moves the demo and a reader who does not meet one
+ * layout rather than two.
+ *
+ * AN EXPLICIT VARIABLE STILL WINS, exactly as it does for the flag: somebody who set a port chose that
+ * number, and a demo is a convenience over the defaults rather than an override of a decision. So is
+ * `--port`, which is applied after this and replaces it. PURE.
+ */
+export const DEMO_PORT_BASE = 18860;
+
+export function demoPortDefaults(ports, env = {}) {
+  const explicit = (name) => String(env[name] ?? "").trim() !== "";
+  return {
+    ...ports,
+    portal: explicit("PORTAL_SERVICE_PORT") ? ports.portal : DEMO_PORT_BASE,
+    mcp: explicit("TRADEMARK_MCP_HTTP_PORT") ? ports.mcp : DEMO_PORT_BASE + 1,
+    client: explicit("CLIENT_MCP_HTTP_PORT") ? ports.client : DEMO_PORT_BASE + 2,
+  };
+}
+
 /**
  * Where the grants file is, for a command that is NOT the supervisor.
  *
@@ -911,6 +931,14 @@ if (isMain) {
   // Decided before any path is, because in a demo every path below is the demo's own. The posture
   // itself is described at the DEMO block further down.
   const DEMO = argv.includes("--demo");
+  // THE DEMO CLEANS UP AFTER ITSELF (owner ruling, 2026-09-14). A reader who tries the product once
+  // should not be left with a folder they did not choose, a guest list and a signing secret in their
+  // home — and the next demo on that machine should not have to reason about the last one's leftovers.
+  // `--keep` is for somebody who wants the reports to outlive the window, and it prints the one command
+  // that removes them.
+  const DEMO_KEEP = argv.includes("--keep");
+  // Whether the reader chose this base, which decides whether leftovers in it are the demo's to reset.
+  const BASE_GIVEN = argv.includes("--base");
   // A DEMO HAS NO BACKGROUND FORM, and asking for one is refused before anything is written. The
   // background path installs units that run the reader's own install, so `--demo --background` would set
   // up an empty install in their home and call it the demo.
@@ -944,13 +972,36 @@ if (isMain) {
     // AN INSTALL NOBODY CONFIGURED still answers. `start --base <dir>` writes a guest list on every start
     // and no settings at all, so an install somewhere of its own passes every check above. A guest list
     // with no demo secret beside it is somebody's install; a demo's own base has both.
-    if (!found.length && existsSync(paths.grants) && !existsSync(demoTokenSecretPath(paths.base)))
+    //
+    // ONLY WHERE THE READER CHOSE THE BASE. On the demo's own default directory this check refused the
+    // demo's OWN leftovers — a 0.3.0-era demo wrote a guest list there, and the next `demo` with no
+    // flag at all was told to "run the demo without --base", which is the command it had just run. The
+    // default directory is the demo's; what is in it is the demo's to reset.
+    if (BASE_GIVEN && !found.length && existsSync(paths.grants) && !existsSync(demoTokenSecretPath(paths.base)))
       found.push(`it holds a guest list, ${paths.grants}, and no demo of its own`);
     if (found.length)
       fatal(`--demo cannot run in ${paths.base}: ${found.join("; ")}.\n`
         + "  The demo keeps its own data, and its own signing secret, in its base. Leaving those in an\n"
         + "  install's directory would make keys issued for that install refuse at its door.\n"
-        + "  Run the demo without --base, or give it a directory of its own.");
+        + `  Give the demo a directory of its own, or remove ${paths.base} if nothing in it is wanted.`);
+
+    // ── AN OLDER DEMO'S BASE IS RESET, SILENTLY, AND ONLY WHEN IT IS THE DEMO'S OWN ─────────────────
+    //
+    // Demos before this one kept their base, so a machine that met the product once carries one. The
+    // next demo must neither refuse it nor start half inside it: a base holding one version's pool and
+    // another's program is a state nobody designed and nobody can read.
+    //
+    // THE RAILS ARE WHAT MAKE THIS SAFE TO WRITE AT ALL, because this line removes a directory:
+    //   · a demo, never an ordinary start;
+    //   · a base the reader did NOT name — the demo's own default, not a directory they pointed at;
+    //   · every install signal above already checked and none found;
+    //   · the path still compared against the default before the call, so a future edit that changes
+    //     how the default is computed cannot silently widen what this removes.
+    const reset = demoBaseResetTarget({ baseGiven: BASE_GIVEN, base, demoDefault: resolve(join(homedir(), "trademark-demo")) });
+    if (reset && existsSync(reset)) {
+      try { rmSync(reset, { recursive: true, force: true }); }
+      catch (e) { fatal(`the demo could not reset its own folder ${reset} (${e.code ?? e.message}). Remove it and run the demo again.`); }
+    }
   }
   // ── THIS INSTALL'S FIRST START, read before this start writes either file that answers it ────────────
   //
@@ -1020,6 +1071,10 @@ if (isMain) {
   // the flag is a convenience over the defaults, not an override of a decision. Driven in the issue:
   // with all three exported, the demo already came up correctly — that path must not change.
   const portFlag = flag("--port");
+  // THE DEMO'S DEFAULTS, BEFORE THE FLAG AND AFTER THE ENVIRONMENT. Applied only when the reader asked
+  // for no port at all: `--port` below replaces whatever this chose, and a variable somebody set is
+  // preserved inside the function itself. See demoPortDefaults for why the demo may not share 18802.
+  if (DEMO && !portFlag) Object.assign(ports, demoPortDefaults(ports, process.env));
   if (portFlag) {
     let moved;
     try { moved = portsForFlag(portFlag, ports, process.env); }
@@ -1969,7 +2024,7 @@ if (isMain) {
     }
     say("");
     say(`  Open:            ${envs.url}`);
-    for (const line of foreignPageHint(DEMO ? "demo" : "start")) say(`                   ${line}`);
+    for (const line of foreignPageHint(DEMO ? "demo" : "start", ports.portal)) say(`                   ${line}`);
     say("  This SURVIVES the terminal — close the window, the product keeps running.");
     say(`  Stop it:         ${invoke("stop")}   (stops and removes the units; issued connect keys survive — \`${invoke("disconnect")}\` revokes those)`);
     say(`  Is it up?        ${invoke("status")}`);
@@ -2070,6 +2125,26 @@ if (isMain) {
       }
       await new Promise((r) => setTimeout(r, 200));
     }
+    // ── THE DEMO TAKES ITS FOLDER WITH IT ───────────────────────────────────────────────────────────
+    //
+    // AFTER the children are down, not before: the runner and the two services write into this base
+    // while they live, and removing it under them would turn an orderly stop into a page of ENOENT.
+    //
+    // The same rails as the reset at the top of the run, plus one more: the demo only removes a base it
+    // MADE this run. A reader who asked for a directory of their own keeps it — they named it, so it is
+    // theirs — and `--keep` is for the reader who wants the reports to outlive the window.
+    if (DEMO && !BASE_GIVEN && !DEMO_KEEP) {
+      try {
+        rmSync(paths.base, { recursive: true, force: true });
+        say(`\n  The demo removed everything it created: ${paths.base} is gone, and nothing of it is left on this machine.`);
+      } catch (e) {
+        // A FAILED CLEANUP IS SAID, NOT SWALLOWED. The promise this prints is the one thing a reader
+        // cannot check for themselves once the window closes.
+        err(`\n  The demo could not remove ${paths.base} (${e.code ?? e.message}) — remove it by hand if nothing in it is wanted.`);
+      }
+    } else if (DEMO) {
+      say(`\n  The demo's folder is kept at ${paths.base}. Remove it when you are done:  rm -rf ${paths.base}`);
+    }
     process.exit(code);
   }
 
@@ -2203,7 +2278,7 @@ if (isMain) {
 
   say("");
   say(`  Open   ${envs.url}`);
-  for (const line of foreignPageHint(DEMO ? "demo" : "start")) say(`         ${line}`);
+  for (const line of foreignPageHint(DEMO ? "demo" : "start", ports.portal)) say(`         ${line}`);
   say("");
   // ── TWO DOORS, TWO AUDIENCES, BOTH NAMED ( — F26) ─────────────────────────
   //
@@ -2285,6 +2360,11 @@ if (isMain) {
     say(`  │  WRITE THE PASSPHRASE DOWN NOW. It is stored only as a digest, so`);
     say(`  │  nothing — not this product, not this terminal — can read it back.`);
     say(`  │  Lost it? ${reset}`);
+    // THE HINT BELONGS IN THE BOX TOO, and this was the reader the whole sentence was written for. The
+    // frame exists because a first-time reader skips the log wall and acts on it — so the one address
+    // they copy was the one address with nothing beside it saying what to do when the page that opens
+    // is somebody else's. It was printed nine lines above, to a reader who by design did not read there.
+    for (const line of foreignPageHint(DEMO ? "demo" : "start", ports.portal)) say(`  │  ${line}`);
     say(`  └${rule}┘`);
   } else {
     // THE WAY BACK IN FIRST, then which credential, when and for whom: laterStartLines says why. Read for
@@ -2340,10 +2420,30 @@ if (isMain) {
   // 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.
-  for (const line of backgroundOfferLines({ demo: DEMO, manager: backgroundManager(), start: invoke("start") })) say(line);
+  for (const line of backgroundOfferLines({ demo: DEMO, keep: DEMO_KEEP || BASE_GIVEN, manager: backgroundManager(), start: invoke("start") })) say(line);
   say("");
 }
 
+/**
+ * WHICH DIRECTORY, IF ANY, A DEMO MAY RESET BEFORE IT STARTS. Null means none, and null is the answer
+ * for everything except one case.
+ *
+ * The one case: the demo's OWN DEFAULT directory, which the reader did not name. Demos before this one
+ * kept their base, so a machine that met the product once carries one; the next demo must neither
+ * refuse it — which is what happened, on a run with no flags, with a remedy telling the reader to drop
+ * a flag they had not passed — nor start half inside it.
+ *
+ * A DIRECTORY THE READER NAMED IS THEIRS. `--base` is a decision about where their data lives, and
+ * nothing in a demo may remove a path somebody chose; the install checks at the call site refuse those
+ * instead. Separated from the call site so the rule can be driven as a table rather than by starting a
+ * product, and because a rule this consequential should be readable in one screen. PURE.
+ */
+export function demoBaseResetTarget({ baseGiven = false, base = "", demoDefault = "" } = {}) {
+  if (baseGiven) return null;                      // the reader chose it, so it is not the demo's to clear
+  if (!base || !demoDefault) return null;          // nothing to compare: say no
+  return base === demoDefault ? base : null;       // compared whole, never by prefix — a sibling path is not this
+}
+
 /**
  * The closing offer of a foreground start: how to get the prompt back, where there is a way.
  *
@@ -2353,10 +2453,16 @@ if (isMain) {
  * offered one. Where the offer stands, it names what it needs BEFORE the reader stops what is running.
  * PURE.
  */
-export function backgroundOfferLines({ demo = false, manager = null, start = "clearotron start" } = {}) {
+export function backgroundOfferLines({ demo = false, keep = false, manager = null, start = "clearotron start" } = {}) {
   if (demo) return [
     "  The demo has no background form: it runs as long as this window does. Leave it open and use a",
     "  second terminal for the commands above.",
+    // SAID BEFORE THE READER PRESSES IT, not only afterwards. A person deciding whether to close the
+    // window is deciding whether to keep the reports, and finding that out from the last line is too
+    // late. `--keep` is named here because this is where the choice is made.
+    keep
+      ? "  This demo keeps its folder: the reports stay after the window closes, and the last line says how to remove them."
+      : "  Everything the demo made goes when this window closes — pass --keep to leave the folder and its reports behind.",
   ];
   if (!manager) return [
     "  There is no background form on this platform: the product runs as long as this window does.",

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "ee3ad6c3a561265588b8db72f153e3eb6694d9fe",
-  "version": "0.3.1-beta.0"
+  "commit": "3e6266f5960e7990e767edbdb95ca50831156b55",
+  "version": "0.3.1-beta.2"
 }

package/docs/architecture/05-config-governance.md

@@ -180,6 +180,20 @@ and only where it exceeds the stall window), `CLEAROTRON_KILL_ESCALATE_MS`
 fills mid-run surfaces as a *missing artifact* at a later stage rather than as a disk error. `0`
 disables; a non-numeric value throws rather than silently disabling the guard.).
 
+`CLEAROTRON_MIN_TOKENS_PER_SEC` (1) and `CLEAROTRON_MIN_TOKENS_WARMUP_MS` (5 minutes) — the trickle floor, and
+how long a turn is left alone before it applies. A stage that streams a token every few seconds is not a
+slow stage: it holds off the stall clock, which resets on any streamed byte, and the no-progress ceiling,
+which counts token movement as progress on purpose, so the only thing that ever stopped one was the wall
+— at which point the attempt is thrown away and done again from the start. The floor is counted in output
+tokens per second of ACTIVE time (elapsed minus tool wait), for the same reason the hard ceiling is: a
+turn waiting on a slow register lookup is producing nothing and must not be killed for it. A turn under
+the floor is stopped there and recorded as a stall, so a retry gets the ordinary budget rather than an
+extended one. `0` disables the floor entirely and is read as "no floor", never as a floor of zero; a
+negative or unreadable value falls back to the default rather than switching the instrument off. The
+default is a floor against a pathology rather than a budget for a stage — the readings it was written
+from were three orders of magnitude apart, 0.08 tokens per second against 74 — and it is expected to
+move once the same window has been read across more runs.
+
 ### 5.4 Pipeline feature gates & kill switches — T3 (defaults ON; `0` disables)
 
 `CLEAROTRON_PLAN_DISPATCH`, `CLEAROTRON_SATPROBE_CODESIDE`,

package/driver/CHANGELOG.md

@@ -1,5 +1,57 @@
 # clearotron-driver
 
+## 0.3.1-beta.2
+
+### Patch Changes
+
+- 240673c: Fixed: A chat notice now carries the channel to send it on, so an assistant with several chat channels no longer drops it silently.
+- 240673c: Fixed: Naming a country in words rather than by code now works for every country, including Belgium and Luxembourg. Before, some were carried as unrecognised.
+- 240673c: Fixed: A family search on a name whose first or last word is a single letter or digit now runs. Before, one register refused it and the search was reported as an outage.
+  
+  Fixed: A conflict whose owner could not be identified is no longer given a risk rating. It is carried as an open item naming who must be identified.
+- f96c089: Fixed: Running the test suite from inside another test run no longer lets the outer run delete the inner run's temporary files.
+- f96c089: Fixed: A clearance for a new client can be ordered through an assistant connector without setting up a company first.
+- 240673c: Fixed: In the staff editor, a refused territory in a project now highlights the field it is about, as it already did when editing a customer. Before, the message appeared but no field was marked.
+- 240673c: Fixed: A sign-in refusal now always says which instance answered — by organisation, by sign-in service, or by the address it runs on.
+- 240673c: Fixed: The published list of settings this build reads no longer keeps a name after the code stops reading it. The list was derived from a scan that included the list itself, so a retired name kept itself alive.
+- 240673c: Fixed: A search step that streams at a crawl is now stopped early and retried, instead of running to its time limit and losing the work.
+- f96c089: Fixed: A mark whose main element contains no vowel — a consonant-only initialism, for example — can now be cleared. Before, the search plan refused to compile and the whole clearance ended without delivering anything.
+- 240673c: Fixed: Use your AI now gives the steps your connector actually takes — sign-in where it signs you in, a key only where a key works.
+- f96c089: Fixed: `doctor` now names the deployment it is checking, and refuses a name that is missing or not recognised. Before, a deployment that was misnamed — or not named at all — passed the check in silence.
+- 240673c: Fixed: Setup and the framed first-run box now say what to do when the page that opens belongs to another program.
+  
+  Fixed: The port that advice suggests is never the port already in use.
+- f96c089: For operators: The repository's own comment-to-code references are now checked for having moved, not only for existing.
+- 240673c: Fixed: On WSL, the "on this computer" rows now start the server inside WSL for you, so an assistant running on Windows can use them.
+- 240673c: Fixed: Somebody you add on the People page can sign in straight away. Before, they were refused until the service restarted with a changed setting.
+- 240673c: Fixed: The demo now removes everything it created when its window closes, and says so. Pass `--keep` to leave the folder and its reports.
+  
+  Fixed: Trying the demo a second time on a machine that has run it before now works. Before, it refused its own folder and suggested dropping a flag that had not been given.
+- 240673c: Fixed: The demo opens ports of its own rather than the ones an installation uses, so the page it points you at is the demo's.
+- 240673c: Fixed: A search now covers every spelling and sound-alike of the name in each category of goods or services the engine judges relevant.
+  
+  Fixed: Before, the added categories were searched for the name exactly and nothing else. The matter frame records each one with the reason it was added.
+- 240673c: Fixed: An off-register search now also covers the channels the matter itself names, not only the account's usual marketplaces.
+  
+  Fixed: A channel no pass ran is now recorded as open rather than described in a note.
+  
+  Fixed: A finding reads what the platform's own record says before calling an owner unidentified.
+- 240673c: For operators: The portal can now call the engine over a local socket instead of a network port, by naming it as its engine address. The deployment check reports that address as wired and says which socket it is.
+- f96c089: Fixed: The run purge no longer deletes a clearance whose report or failure notice has not been sent yet.
+  
+  Fixed: Those runs are marked in the table the purge prints, and removing one now takes a flag that says so.
+  
+  For operators: Every applied purge leaves a record of what it removed, when, and whether any of it was still owed.
+- 1905ea4: Fixed: Saving a territory the engine cannot search now says so, instead of suggesting the kind of entry that was just refused.
+
+## 0.3.1-beta.1
+
+### Patch Changes
+
+- c3228f3: Fixed: A clearance that stops is recorded as owing a notice even when the folder its notice is queued in cannot be written to.
+- c3228f3: Fixed: Check now reports the same problems Save would refuse, so a company setting can no longer pass the check and then fail to save.
+- c3228f3: Fixed: On older Windows-Subsystem installations the engine now identifies the platform by its interop registration rather than by the kernel version string.
+
 ## 0.3.1-beta.0
 
 ### Patch Changes

package/driver/citation-census.json

@@ -1,4 +1,5 @@
 {
   "citations": 621,
-  "files": 1892
+  "files": 1892,
+  "checkable": 102
 }